Reading and repairing subscription usage¶

Use Brama's native commands or Brama Desktop. The commands below describe the product workflow; they are not captured execution results.

Read the recorded state

brama subscription list --json

The response includes ok, observed_at_ms, errors, accounts and subscriptions. Each member carries its identity, credential state, actual plan windows, observation/reset times and latest usage reading. A live credential alone is not proof of current usage.

Find accounts you already own

brama subscription discover --gateway-consumer <consumer> --bearer-role <console bearer role> --json

Run this where your coding harness knows your accounts. Brama reads public account metadata and the gateway checks synchronized receipts through Skrzynka. Each discovered account retains its provider, address, plan when reported, source and observation time. It enters the pool without copying a harness grant; Weles must obtain Brama's independent grant for that exact account.

Configure SKRZYNKA_ORGANIZATION in the gateway's environment with the organization whose synchronized mailboxes may supply purchase receipts. Brama captures its trimmed value once per collection and passes it explicitly as skrzynka --organization <organization> for mailbox listing, message pagination and message retrieval. A missing or blank value produces a receipt-discovery error before any mailbox command; neither the local discovery caller's environment nor an implicit Skrzynka default supplies gateway scope. CLI and Desktop retain that error beside other discovered account facts.

Receipt provenance and cache keys include the organization, mailbox and message IDs as a JSON tuple after skrzynka:. A previously unscoped cache entry cannot supply facts for a selected organization. The real receipt journey tests/subscriptions/discovery/sources/receipt.rs requires the same SKRZYNKA_ORGANIZATION on its host and gateway, plus its existing real receipt/account inputs. It checks that organization-bound provenance is persisted without replacing the current harness plan with historical receipt information. Run the historical_receipt filter of the subscription-capacity test target only against authorized isolated fixtures; discovery may register accounts and schedule their independent sign-in.

Desktop's Discover accounts action shows the same report. A missing grant, failed mailbox read or unavailable discovery source remains visible with its cause. Member names do not assign rank: capacity and availability decide which member can serve.

After a nonempty discovery with no source errors, the gateway reconciles obsolete membership before enrolling accounts. It removes members without a recorded account, borrowed-grant members, ledger-only entries without discovery metadata, and duplicate members for the same provider and account. Member labels never establish ownership or routing priority. The removed report names each removed member and its reason, and Desktop shows those same outcomes.

Reconciliation marks obsolete membership unavailable, checks for live session leases, moves only that member's tagged vault items to recoverable trash, confirms their absence from live inventory, and removes its overlay and usage-ledger entry. Shared login items are not removed. Active leases, changed account identity, unreadable account metadata, vault refusals and failed persistence stop reconciliation with the operation and cause. An interrupted removal is resumed on later discovery; its tombstone is distinct from an owner's retirement. Discovery still cannot reinstate an owner-retired account.

A donated-overlay update refuses unreadable files and malformed JSON before replacing the document. Its error names BRAMA_DONATED_SUBSCRIPTIONS_FILE's resolved path and the operating-system or JSON-decoder cause, including invalid or missing items. The same cause reaches discovery's CLI and Desktop report; it is not an empty overlay or proof that preceding reconciliation steps were rolled back.

The isolated persistence journey cargo test --test subscription-overlay -- --ignored --nocapture exercises the actual Brama overlay API and filesystem, not a gateway or provider substitute. Build the test binary with BRAMA_SOURCE_REVISION identifying the exact checkout revision. It rejects malformed documents and a directory in place of a file without replacing either, then creates and removes a real isolated membership. Its report and final state remain under target/real-tests/subscription-overlay. This does not qualify vault reconciliation or independent sign-in.

Real qualification is in tests/subscriptions/discovery/reconciliation/real.rs. Run the subscription capacity target on an isolated gateway's vault host with BRAMA, CONSUMER, BEARER_ROLE, GATEWAY_SOURCE_REVISION, SKARBIEC_BIN, RECONCILE_KEEPER, RECONCILE_DUPLICATE, RECONCILE_IDENTITYLESS and space-separated RECONCILE_VAULT_ITEMS. These identify actual fixture members and items, not operator data. The journey executes discovery, reads the persisted pool and actual vault inventory, checks unrelated items are unchanged, and repeats discovery to verify no repeated removal.

Every subscription capacity journey also requires CLI_SOURCE_REVISION. Setup verifies the actual brama version identity before contacting the gateway; the CLI candidate and GATEWAY_SOURCE_REVISION are independently selected and retained.

cargo test --test subscription-capacity membership_reconciliation -- --ignored --nocapture
cargo test --test subscription-capacity reconciliation_refusal -- --ignored --nocapture

The refusal journey additionally requires RECONCILE_LEASED_MEMBER, an obsolete member with an actual live lease on the isolated gateway. It verifies a nonzero discovery result with that member's cause and unchanged membership and leases. A failed reconciliation sets reconciliation_failed and does not schedule new sign-ins from that discovery operation.

After Refresh usage, inspect the selected member's saved reset count, expiry and eligibility. Refreshing reads credits without consuming them. Use the member's reset action with a reason, or brama subscription reset <provider> --member <id> --reason <why> with the same gateway options. See reset eligibility, automatic policy and uncertain outcomes before using saved capacity.

Change automatic saved-reset policy safely

brama subscription policy show --gateway-consumer <consumer> --bearer-role <console bearer role> --json
brama subscription policy set <provider> --keep-credits <count> --min-blocked-minutes <minutes> --salvage-horizon-hours <hours> --reason <why> --gateway-consumer <consumer> --bearer-role <console bearer role> --json
brama subscription policy clear <provider> --gateway-consumer <consumer> --bearer-role <console bearer role> --json

These operations read, replace or remove the selected provider's policy on the gateway that holds the pool. Brama Desktop's Saved-reset policy uses the same gateway operation. Changing policy does not itself consume a provider credit.

The native editor distinguishes a read in progress, a policy returned by the gateway, a confirmed absence and a failed observation. A failed read does not mean automatic redemption is disabled: its actual cause is shown and Read policy can request the state again. Mutations require a completed observation and remain disabled while that editor is reading or changing policy. Changing the gateway or provider creates a fresh editor, so another account's policy and unsent fields cannot appear as the new selection's state.

If an update or removal fails to return confirmation, Desktop does not claim the gateway left its policy unchanged: the mutation may already have been saved. It shows the actual failure, discards the earlier observation and disables further mutations until Read policy succeeds. It never repeats a mutation automatically.

Set and clear hold one operating-system lock across reading and replacing the policy document. A concurrent writer is refused immediately with the provider, lock path and operating-system cause, rather than overwriting another writer's state. CLI and Desktop retain that refusal. Read the policy again before making another change; no write is silently retried. Process exit releases the lock, and its file is not a stale-work marker to delete. Decode and persistence failures preserve their actual operation and cause; malformed JSON is not evidence of who changed it.

The real lifecycle and lock-contention journey is tests/subscriptions/resets/policy.rs. Run it on an isolated gateway's host with BRAMA, CONSUMER, BEARER_ROLE, GATEWAY_SOURCE_REVISION, its existing RESET_POLICY_STATE_DIR, and a POLICY_PROVIDER with declared reset support and no existing policy. Supply POLICY_KEEP_CREDITS, POLICY_MIN_BLOCKED_MINUTES and POLICY_SALVAGE_HORIZON_HOURS explicitly. It uses the actual CLI to create, update and clear policy, checks the persisted document and unrelated policies, and holds the real file lock to verify mutation refusals. It retains the source revision, binary checksum, command outputs and exit statuses; it neither reads nor consumes provider credits.

cargo test --test subscription-capacity reset_policy -- --ignored --nocapture

Read the pool of the gateway that serves, and who refreshes each grant

brama subscription list --gateway-consumer <consumer> --bearer-role <console bearer role>

Run on the machine whose harnesses hold the grants, this reads the pool of the gateway Stado places the service on, with the console's bearer taken from the vault at the moment it is used. Every member states who refreshes it: refreshed by: omp, the harness that holds it; Brama does not rotate it, or refreshed by: brama. In Desktop the same fact sits beside the member's credential state.

Read it first when a harness keeps losing its login. A provider rotates an OAuth refresh token on every refresh and revokes the one it replaced, so an account held by both a gateway and a harness signs the operator out of the harness within the hour — No API key for provider: anthropic in omp is what that looks like from the other side. Brama no longer takes a grant from a harness at all; a member left from when it could is given back with brama subscription disown, and a grant written before then is still never rotated.

Refresh free usage reports

brama subscription list --refresh-usage --json

In Desktop choose Refresh usage on Subscriptions or Subscription Pool. Both use the same Brama function, which obtains credentials from Skarbiec and reads the provider's own report without sending a model request. Expired OAuth grants are renewed when possible; sign-in is never opened as a side effect.

To inspect or manage live session leases, open Leases → Manage session leases in Brama Desktop. The window reads the serving gateway's lease register, names the proven scope and any read refusal, and offers take and release with confirmation. Taking a lease can buy an account when the pool has no room; the resulting lease or purchase refusal is shown before the inventory is read again. The Desktop bearer has console scope. Automation that must act as a particular agent uses brama subscription lease take|list|release --agent <agent> --signing-role <role#field> so the gateway enforces ownership on every operation.

Each successful report replaces that account's previous limit windows. An explicitly empty provider report means no windows were published, not zero percent used. Failed reads retain the last successful windows with their original observation times and a visible stale/error state.

Read failures without losing successful accounts

An incomplete report has ok: false and the CLI exits 1. errors preserves the failed operation, actual cause, account and attempt time. HTTP 200 alone does not mean success. A failing account does not hide successful accounts, and retained old measurements are visibly stale. Skarbiec failure is not an empty inventory; absent or malformed metrics are not zero usage. If Brama cannot answer, Desktop reports that connection failure itself instead of displaying a healthy empty screen.

Sign in only the account that requires it

brama subscription login codex --by weles --subscription-id <subscription-id> --login-item <login-item> --reason 'replace the provider-refused grant' --json

The equivalent Desktop action is Sign in on the selected account. Weles performs the login on the Stado-selected host. Brama checks the account mapping and requires a successful refresh of that exact subscription; a different working account cannot make the operation succeed.

After a successful sign-in, refresh usage again. A provider rejection, unavailable Weles worker or failed Skarbiec write remains an explicit error, not an instruction to infer success from stored metadata.

See the CLI report contract, login refusals, and HTTP result semantics.