brama subscription acquire¶

Buy one new account of a provider when no account in the pool can serve and the pool holds fewer accounts than the operator allows. Weles creates the account on a fresh identity by the provider’s own purchase trajectory, pays for the plan the pool’s accounts hold with the purchase card in Skarbiec, writes its login row and subscription item to the vault and signs it in; Brama proves the new grant with a refresh.

Every provider is declared once, in src/subscription_dispatch/acquire/providers.json: its Weles provider (whose src/trajectories/<weles provider>/account/acquire.mjs buys the account), the names in numeric-provenance.json of the operator’s account cap and of how many sessions may share one subscription, and for each harness the harness’s own name for the provider and the model a session on it starts on. A provider is bought for exactly when it is declared with an account cap the operator stated; adding one is a declaration and a Weles trajectory, never a branch in code. claude-code, codex and kimi are declared today, and only claude-code names a purchase cap.

Every brama maintain pass takes the same decision by itself for every declared provider, so an operator does not have to run this: when the pool cannot serve and is below the cap the pass starts the purchase and reports acquisition: claude-code started (purchase_started) with the shortage. After an automatic purchase that failed or never reported how it ended, passes buy nothing until this command is run again, because each attempt can spend money.

A pool full of sessions is the other shortage an acquisition buys for: when brama subscription lease take finds every usable member of the provider carrying sessions_per_subscription_max live sessions (the operator's number in the same numeric-provenance.json), the gateway refuses the lease 409 pool_full and runs this decision with trigger sessions_full: the plans are not spent, so pool_not_spent does not apply, and the cap, the inventory and the plan tier decide as they do here; sessions_not_full refuses it when the shortage is gone by the time it decides. Its verdict is in the lease refusal's details.acquisition. Like a maintenance pass, it buys nothing after an unresolved attempt until this command is run again.

A lease for a provider with no usable member at all runs the same decision with trigger no_usable_member, which buys as a maintenance pass does (every account spent its plan or cannot be used). Like a maintenance pass, neither lease trigger buys again after an attempt that failed or never reported how it ended, until an operator runs this command. When either one buys an account, the gateway takes the waiting lease again on the bought account and answers the lease with this verdict beside it, so the session that found the pool full starts on the new account.

Invocation¶

brama subscription acquire <PROVIDER> --reason <REASON> [--gateway <ORIGIN> | --gateway-consumer <NAME>] [--bearer-role <ROLE>] [--json]

The decision¶

The cap is the operator’s own number named by the provider’s accounts_max (for claude-code, claude_code_accounts_max in src/subscription_dispatch/acquire/numeric-provenance.json with his words beside it); a provider whose cap is not stated is never bought. Accounts are the non-retired pool members counted by the account each declares in brama:account:; a member that declares none counts as an account of its own. Each member’s plan is read fresh from the provider’s own usage report (no quota is spent); a member is spent when a rate-limit block is in force or a current window is at its whole limit, and unread when its plan cannot be read. A member whose grant awaits a sign-in cannot be asked of the provider: when the coding harness signed into its account relayed the provider’s windows (a reading whose usage_source is harness, recorded by discovery from omp usage --json), those windows decide it the same way, a rolled window counting as empty; without them it is unread with the sign-in cause and stops the purchase. It buys for one of three shortages, named in the verdict’s shortage: spent (every account has spent its plan), unusable (no account has plan left: each is spent or cannot be read, or the pool holds none) and, on trigger sessions_full, sessions_full (every usable subscription carries the operator’s limit of sessions). One account with plan left stops the first two. The plan bought is the tier the provider’s profile names for the pool’s accounts (organization.rate_limit_tier, for example default_claude_max_20x).

Output and state¶

The first line is <provider> <result>: <detail>, then the accounts counted against the cap, each member’s standing (spent, available or unread), and the plan tier, subscription id, account and Weles run when there are any. With --json a purchase’s verdict carries shortage and why, the shortage as a sentence, and request_id, the correlation id Brama sent Weles. Weles’s stages print on stderr while the purchase runs. result is acquired (exit 0), refused or failed (exit 1). Every purchase is journaled twice in BRAMA_STATE_DIR/journal.jsonl as subscription_acquisition: requested when Weles is asked, and the verdict when it ends. The bought account becomes the member <provider>-<account address> (the verdict’s subscription_id, as Weles banked it) in brama subscription list; brama subscription handover signs it into a harness on the operator’s machine.

Refusals¶

Decided refusals carry a code: account_cap_reached (the pool holds the cap; the sentence names the cap and every account counted), pool_not_spent (names each account with plan left and its most spent window), plan_unstated (no grant stated its tier, or the pool holds more than one tier), account_cap_undeclared (the operator has not authorized account purchases for <provider>, so none is bought for a declaration without accounts_max, or the operator's account cap for <provider> is not stated: …numeric-provenance.json states no number `<name>`, so none is bought), inventory_unreadable, sessions_not_full, leases_unreadable, acquisition_running and, on a maintenance pass, previous_acquisition_unresolved. A failed purchase names Weles’s own code and stage, for example payment_declined, phone_verification_required, card_entry_failed or acquired_grant_unproven, and keeps the account, vault items and payment it already made. A purchase Weles reports done is accepted only when its answer echoes this request’s id as request_id and names the member it banked as subscription_id; an answer without the echo fails purchase_uncorrelated with Weles’s whole answer, because a Weles that predates the echo returns the correlation id where the member belongs, and one naming another member fails acquired_member_mismatch. A Weles that answers HTTP 404 for its purchase route predates account purchase: the failure is weles_purchase_route_absent; a Weles without the provider’s trajectory refuses provider_unsupported naming the missing src/trajectories/<provider>/account/acquire.mjs. A provider providers.json does not declare is refused before anything is read with src/subscription_dispatch/acquire/providers.json declares no subscription provider `<provider>`; it declares claude-code, codex, kimi; the route answers it HTTP 400 and requires the brama-desktop console identity. The real test is tests/subscriptions/acquire.sh.

See the command group or the CLI tree.