@iowarp/clio-coder 0.5.0 → 0.5.2

package/docs/architecture/observability.md

@@ -85,6 +85,8 @@ An `EvidenceIndexRow` has the following schema:
 
 ## Cross-Session Usage Facts
 
+Everything in this section describes what Clio itself recorded. Subscription quota is a separate source with separate meaning: `src/domains/quota/**` reads what each connected provider account reports about its own windows and credits, account-wide and shared across your sessions and devices, and nothing in that domain enters the cost ledger, the evidence spine, or the trace store. The `/usage` overlay shows both and keeps them in separate views, because a session's recorded tokens cannot be converted into a percentage of a provider's plan. See [Subscription quota and session usage](../guide/commands-and-modes.md#subscription-quota-and-session-usage).
+
 `clio-coder usage report` folds the local archive into one window of facts. Its token and cost facts come from two inputs: the per-session ledgers, folded through the session domain's `ledgerUsageCalls`, and the out-of-turn usage store described below. Both the text report and `--json` carry the same fields.
 
 | Field | Where it appears | Meaning |
@@ -92,7 +94,7 @@ An `EvidenceIndexRow` has the following schema:
 | `apiCalls` | `tokens in window: <total> over <n> model calls` and the `tokens` JSON fact | Provider calls folded in the window, out-of-turn rounds included. |
 | `input`, `output`, `cacheRead`, `cacheWrite`, `reasoningTokens`, `totalTokens` | the same line and fact | Provider-reported token breakdown for those calls. |
 | `costUsd` | `provider-reported cost in window` and the `tokens` fact | Provider-reported cost. Never estimated. |
-| `turns` | `turns in window` and the `tokens` fact | Folded calls that were turns, so labelled calls are subtracted exactly as `/cost` subtracts them. |
+| `turns` | `turns in window` and the `tokens` fact | Folded calls that were turns, so labelled calls are subtracted exactly as `/usage` subtracts them. |
 | `sideQuestions` | `side questions in window` and the `tokens` fact | `/btw` rounds in the window. |
 | `handoffs` | `handoffs in window` and the `tokens` fact | `/handoff` extraction rounds in the window. |
 | `prewarms` | `pre-warms in window` and the `tokens` fact | Prompt pre-warm rounds in the window. |
@@ -120,7 +122,7 @@ The row reads `top expected reason none` when the session recorded verdicts but
 
 ### The Out-of-Turn Usage Store
 
-A `/btw` side question and a `/handoff` extraction round are real provider calls that append nothing to the session JSONL, by design: a fleet run briefs its workers from the transcript, and a question the operator asked to orient themselves must not become context those workers inherit. The spend still has to be recorded somewhere durable, so it goes to `<stateDir>/usage/out-of-turn.jsonl`, one JSON line per priced call, written by the chat loop at the same moment it reports the call to `/cost`.
+A `/btw` side question and a `/handoff` extraction round are real provider calls that append nothing to the session JSONL, by design: a fleet run briefs its workers from the transcript, and a question the operator asked to orient themselves must not become context those workers inherit. The spend still has to be recorded somewhere durable, so it goes to `<stateDir>/usage/out-of-turn.jsonl`, one JSON line per priced call, written by the chat loop at the same moment it reports the call to `/usage`.
 
 The file is append-only NDJSON kept as a bounded ring (capped at 1000 rows, rewritten atomically under the shared state-file lock when it grows past the cap). Reads are tolerant: a malformed line is reported as a diagnostic on stderr and skipped.
 
@@ -155,9 +157,9 @@ Failed compaction attempts record one `failed-compaction` row per invoked summar
 
 New failed-compaction rows preserve missing usage fields as `null`. Positive partial-response facts survive an error that resets missing fields to zero. Ambiguous failed zeros remain unknown, reasoning is separate from ordinary output/total tokens, and an absent total is not inferred. Positive adapter prices are labeled `estimated`; zero or missing pricing is `unknown`, not a free-call claim. Existing numeric rows and historical checkpoints remain readable without rewriting them.
 
-`clio-coder usage report` includes these calls in its known subtotals, labels the failed-attempt count, and exposes `failedCompaction.knownUsage`, `erroredKnownUsage`, and per-field `unobservedUsageCalls` in the token and model JSON facts. A field with missing coverage and no known positive amount is `null`, including cost-only or wholly unobserved failures. Text output identifies incomplete subtotals. The live `/cost` view records positive known contributions under a failed-compaction label; its numeric token counters remain known subtotals. These figures do not certify provider billing or complete spending. The existing session-cost ceiling checks the numeric known sum, so unreported cost does not become an enforced complete-cost bound.
+`clio-coder usage report` includes these calls in its known subtotals, labels the failed-attempt count, and exposes `failedCompaction.knownUsage`, `erroredKnownUsage`, and per-field `unobservedUsageCalls` in the token and model JSON facts. A field with missing coverage and no known positive amount is `null`, including cost-only or wholly unobserved failures. Text output identifies incomplete subtotals. The live `/usage` view records positive known contributions under a failed-compaction label; its numeric token counters remain known subtotals. These figures do not certify provider billing or complete spending. The existing session-cost ceiling checks the numeric known sum, so unreported cost does not become an enforced complete-cost bound.
 
-In v0.5.0, eval tracked/stdout folds omit the failed-compaction sidecar, and live `/cost` reseeding reads the session ledger rather than this store. A later usage report can therefore include retained failed-compaction amounts that those views omit. These consumer projections remain separate; retained known amounts must not be presented as complete cross-surface billing.
+In v0.5.1, eval tracked/stdout folds omit the failed-compaction sidecar, and live `/usage` reseeding reads the session ledger rather than this store. A later usage report can therefore include retained failed-compaction amounts that those views omit. These consumer projections remain separate; retained known amounts must not be presented as complete cross-surface billing.
 
 A failed or empty summary produces no checkpoint. Required failed-compaction usage appends are flushed and a write failure remains an explicit operation error; no model call is repeated to repair accounting. If checkpoint append throws, Clio checks that checkpoint's exact identity in the original ledger before choosing the sidecar: an already written checkpoint is not counted again, and proven absence permits the sidecar. An unreadable or malformed ledger that leaves persistence ambiguous fails visibly without a speculative duplicate write. This is the existing bounded usage store, not a new recovery store; its 1000-row retention and unknown telemetry limits still apply.
 

package/docs/architecture/prompt-envelope-and-tools.md

@@ -316,7 +316,7 @@ Timing and cache behavior are persisted per API call, so a finished session can
 
 Native session timing uses a monotonic clock from each stream invocation, before the provider's response-header wait, to its first observed output (`ttftMs`) and completion (`apiMs`). A tool-loop continuation starts a new clock; no output leaves TTFT null, and a genuine rounded zero remains zero. Historical values are not rewritten and may omit the pre-header wait. Eval prefers these durable native call records. Its stdout-only fallback starts at the provider's `message_start` event, which can arrive after headers, so fallback spans are not complete request latency and must not be compared as equivalent measurements.
 
-For aggregate cost and token facts across sessions, use `clio-coder usage report --days <n>`. Inside the TUI, `/cost` shows session totals and `/context` opens the context-window ledger overlay.
+For aggregate cost and token facts across sessions, use `clio-coder usage report --days <n>`. Inside the TUI, `/usage` shows session totals and `/context` opens the context-window ledger overlay.
 
 ## Self-documentation retrieval
 

package/docs/architecture/session-lifecycle.md

@@ -167,7 +167,7 @@ cancels the whole handoff with nothing written in either session.
 The extraction round itself runs on the out-of-turn seam `/btw` uses: one call
 against the session's live target and model, the compiled message history as
 read-only input, no tools, and no entry in the ledger. Its provider usage is
-reported to `/cost` under a handoffs row and excluded from the turn count.
+reported to `/usage` under a handoffs row and excluded from the turn count.
 
 ### Streaming Turn Settlement During Session Transitions
 

package/docs/architecture/tui-design.md

@@ -203,7 +203,7 @@ Interactive startup uses one terminal lease across both boot stages. Stage 0 own
 The header has two operational modes: a framed launchpad dashboard on fresh start, and a single live session row after prompt admission. Source: `src/interactive/welcome-dashboard.ts`; contracts: `tests/extended/welcome-boot-header.test.ts`.
 
 - **Launchpad (before the first prompt): framed panel dashboard.** A boxed container (`buildWelcomeDashboardLines`) enclosed by `╭─ Clio Coder v<version> ─╮` and `╰─╯`:
-  - **11 Detail Rows:** Subhead/title ("Built for the code behind science."), model route status (`routeRow`), workspace path, permissions/autonomy (`stats.autonomy`), guidance ("Ask Clio how to use or extend her."), target inventory (`stats.targets`), and fleet recipes inventory (`stats.fleet`).
+  - **11 Detail Rows:** Subhead/title ("Built for the code behind science."), model route status (`routeRow`), workspace path, permissions/autonomy (`stats.autonomy`), guidance ("Ask Clio how to use or extend her."), target inventory (`stats.targets`), and fleet recipes inventory (`stats.fleet`). A `Subscriptions` field (`stats.quota`) joins the list between Targets and Fleet once a cached quota reading exists, wrapping at the detail-column width rather than clipping, and is absent entirely when no account is connected.
   - **Responsive Layout:** Renders wordmark ASCII art on the left at ≥76 columns (`sideBySide`), and rotating hint cards on the right at ≥160 columns (`WELCOME_HINT_MIN_WIDTH`) cycling commands and shortcuts every 15 seconds.
   - **Action Row:** A horizontal rule (`├─┤`) separates details from the action row (`actionRow`), which prints the next step or work blocker: no route or model (`/model`), route unavailable or degraded (`/settings targets`), malformed handbook (`CLIO-CODER.md malformed · /context to inspect`), uninitialized handbook (`describe a task · /context init to index this repo`), stale handbook (`describe a task · /context refresh to update it`), or default `describe a task · <SubmitKey> to send · / for commands`.
 
@@ -211,7 +211,7 @@ The header has two operational modes: a framed launchpad dashboard on fresh star
 
 - **Session header (after the first prompt): exactly one row, and live.**
   ```
-  >C_ Clio Coder v0.5.0 · dynamo · qwen3.8-27b · ~/iowarp/clio-coder · main*
+  >C_ Clio Coder v0.5.1 · dynamo · qwen3.8-27b · ~/iowarp/clio-coder · main*
   ```
   Collapsed via `sessionRow`, this line tracks mid-session model or branch mutations. It preserves identity (`>C_ Clio Coder v<version>`), active route, workspace tail, and git dirty state (`*`), dropping readiness and onboarding hints owned by the footer. Under extreme width pressure, the route is preserved longest, outliving workspace and version labels.
 
@@ -267,12 +267,12 @@ Starting Clio · you can type now
 Source: `src/interactive/footer/dashboard.ts`, `src/interactive/footer/pages.ts`.
 
 - **Compact Mode (Two-Line Ambient Strip)**:
-  - **Line 1 (Workload & Identity)**: Active phase (`accent` e.g. `Ready`) and worker counts (`agent` e.g. `· 2 active`) · Target/model identity (`fitIdentityLabel`) · Thinking level (`reason`) on the left; Context meter bar (8–14 cells) and token occupancy (`used / contextWindow`) on the right.
-  - **Line 2 (Status & Hints)**: Urgent input prompt (`Ctrl+C again to quit`, `Ctrl+G → choose key`), active notices (`• text`), demo tips, or rotating shortcut hints alternating with workspace path and git branch/dirty (`*`) on the left; Session throughput (`tok/s`) and dashboard toggle shortcut (`Alt+U`) on the right.
+  - **Line 1 (Workload & Identity)**: Active phase (`accent` e.g. `Ready`) and worker counts (`agent` e.g. `· 2 active`) · Target/model identity (`fitIdentityLabel`) · Selected model’s weekly quota (`weekly N% left`, when the local credential owner and model group are known) · Thinking level (`reason`) on the left; Context meter bar (8–14 cells) and token occupancy (`used / contextWindow`) on the right.
+  - **Line 2 (Status & Hints)**: Persistent workspace cwd and Git branch/dirty (`*`) on the left; rotating shortcut hints on the right. Urgent input prompts (`Ctrl+C again to quit`, `Ctrl+G → choose key`), active notices (`• text`), and demo tips borrow only the hint area. Quota never occupies this row.
 - **Expanded Mode (`Alt+U`)**: Renders across one-quarter of the viewport (minimum 8 rows), keeping the composer anchored below. Repeated presses cycle through three responsive pages (`DASHBOARD_PAGES`) and closed:
   1. `Activity`: Live agent phase, tool counts, session metrics, active worker cards (route, task, token usage, tool calls, timing, budget, `/view dispatch:<id>`), and finished worker history.
   2. `Context`: Context meter bar and category occupancy grid (system, tools, files, turns, memory), compaction/cache telemetry, headroom.
-  3. `Status`: Cost & Connections (session cost, MCP servers, plugins, extensions) and Local Machine metrics (CPU, memory, disk I/O sampled on 2s cadence), plus memory bank entries and free tokens.
+  3. `Status`: A session line (recorded tokens and tracked cost) above one compact row per connected subscription account (`renderQuotaAccounts`, `src/interactive/quota-view.ts`), then Cost & Connections (session cost, MCP servers, plugins, extensions) and Local Machine metrics (CPU, memory, disk I/O sampled on 2s cadence), plus memory bank entries and free tokens.
 
 ### 5.4 State Choreography Table
 
@@ -418,17 +418,20 @@ Agents and Fleets label plugin provider packages as `[plugin]` and show only the
 
 ## 8. Shared Vocabulary
 
-One quantity gets one word, and every surface that shows it uses that word. A user comparing the transcript, the footer, and an overlay is checking whether Clio is telling a consistent story; a synonym reads as a discrepancy. The current vocabulary is owned by `src/interactive/chat-panel.ts`, `src/interactive/cost-overlay.ts`, `src/interactive/status/reasoning.ts`, and `src/interactive/thinking-level-policy.ts`; there is no standalone `usage-vocabulary` contract test in the current tree.
+One quantity gets one word, and every surface that shows it uses that word. A user comparing the transcript, the footer, and an overlay is checking whether Clio is telling a consistent story; a synonym reads as a discrepancy. The current vocabulary is owned by `src/interactive/chat-panel.ts`, `src/interactive/usage-overlay.ts`, `src/interactive/status/reasoning.ts`, and `src/interactive/thinking-level-policy.ts`; there is no standalone `usage-vocabulary` contract test in the current tree.
 
 | Concept | Word | Surfaces |
 | --- | --- | --- |
-| One model API call | `call` | Chat panel `turn · in N over M calls`, `/cost` `model calls`, `/cost` `(avg/call …)` |
-| One user-to-assistant exchange | `turn` | Chat panel `turn · …`, `/cost` `turns` |
+| One model API call | `call` | Chat panel `turn · in N over M calls`, `/usage` `model calls`, `/usage` `(avg/call …)` |
+| One user-to-assistant exchange | `turn` | Chat panel `turn · …`, `/usage` `turns` |
 | Provider-reported reasoning tokens | `reasoning N provider` | Chat panel |
 | Reasoning tokens estimated from displayed text | `reasoning ≈N estimated` | Chat panel; the footer carries the same `≈` on `r≈N` |
-| Reasoning tokens in the cost tally | `reasoning N provider-reported only` | `/cost`. This tally never estimates, so it disagrees with the panel on a model that reports nothing, and the row says which one it is. |
+| Reasoning tokens in the cost tally | `reasoning N provider-reported only` | `/usage`. This tally never estimates, so it disagrees with the panel on a model that reports nothing, and the row says which one it is. |
 | Thinking level a model cannot turn off | `forced` | Editor rail, model overlay, thinking cycle (`thinkingLevelDisplayWord`) |
 | Thinking level on a model with only on and off | `on` / `off` | Same surfaces |
+| Consumed share of a subscription window | `N% used` | `/usage` Accounts, dashboard Status, welcome `Subscriptions`. A filled meter cell always means consumed capacity. |
+| Unconsumed share of the same window | `N% remaining` in a detailed meter, `N% left` in a compact badge | `/usage` Accounts and Status print `remaining` beside `used`; the compact footer, worker cards, and fleet islands carry `weekly N% left`. |
+| A limit belonging to the account rather than to this session | `Shared <account>` | Worker cards, fleet islands, `/usage` Workers. Never a measured per-worker share. |
 
 ### 8.1 Slash-Command Failures
 

package/docs/gui/parity/02-slash-and-surfaces.md

@@ -24,7 +24,7 @@ Two rows in the source are **corrupt Markdown**: an unescaped `|` inside the ope
 | 12 | Oracle advisory | `/oracle <question>` | **Absent** | No read-only record-briefed advisory operation exists. |
 | 13 | Council | `/council <task>` | **Partial** | Runs reconstructs the roster, plan approval, rounds, and synthesis shape from the ledger. Member voices are **host-only-by-design**; starting and sharing a council are absent. |
 | 14 | Agent reference | `/agents` | **Present** | Capability atlas provides the graphical recipe reference. |
-| 15 | Cost record | `/cost` | **Partial** | Exact tokens and historical reported cost exist, but live session cost, budget provenance, and provider-normalized totals are incomplete. |
+| 15 | Usage record | `/usage` | **Partial** | Exact tokens and historical reported cost exist, but live session cost, budget provenance, and provider-normalized totals are incomplete. |
 | 16 | Context family | `/context view \| compact \| recall \| init \| refresh \| reset` | **Partial** | `[RECONSTRUCTED]` — the source row is corrupt for the same reason. Verified against `src/interactive/slash-commands.ts:1695-1705`, whose `kinds` are `context-view, compact, context-recall, init, context-clear, context-refresh`. Reconstructed gap, consistent with the `Project context` row in part 1 and the `Context meter and overlay` row below: effective context sources and earlier replay are visible; live window pressure, working-set state, compaction, recall, and reset have no GUI surface. |
 | 17 | Fleet | `/fleet` settings and `/fleet run` preview/approval | **Partial** | Global dispatch status exists; fleet plan selection, variable binding, preview, approval, and run are absent. |
 | 18 | Decision ledger | `/decisions` | **Absent** | No typed decision-board projection reaches the GUI. |

package/docs/guide/commands-and-modes.md

@@ -250,7 +250,7 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/oracle` | `/oracle <question>` | Ask a read-only advisor to challenge a question against this session's settled decisions |
 | `/council` | `/council [--roster <name>] [--rounds <n>] [--synthesis <judge\|vote\|none>] <task>` | Ask a roster of read-only members the same task, with an optional vote or judge synthesis |
 | `/agents` | `/agents` | Open the Library on Agents. |
-| `/cost` | `/cost` | Show session token and cost totals |
+| `/usage` | `/usage` | Show subscription quota, credits, and session token and cost totals |
 | `/doctor` | `/doctor [deep]` | Show a diagnostic report with errors and warnings first and full wrapped check details; `deep` adds live tool probes on the session's targets and a validation-contract dry run at the session's autonomy. See [Doctor](doctor.md). |
 | `/context` | `/context compact [instructions] \| /context recall <ref> \| /context init [--preview] [--heuristic] [--adopt] [--global] [--propose\|--apply\|--rewrite] \| /context refresh \| /context reset` | Context hub: window overlay plus compact, recall, init, refresh, and reset |
 | `/fleet` | `/fleet [run [--var <key=value>] <name>]` | Open Fleet Runs, or run a fleet contract with an approval preview. Configure fleets with `/settings fleet`. |
@@ -270,6 +270,92 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/fork` | `/fork` | Fork from an assistant turn |
 | `/export` | `/export [path]` | Export a self-contained HTML transcript by default; a `.md` path writes Markdown |
 
+### Subscription quota and session usage
+
+`/usage` replaces `/cost`. There is no alias: `/cost` is no longer a command.
+The overlay keeps the token and cost accounting `/cost` carried and adds what
+the connected subscription accounts report. It is a live view of this session
+and of your accounts right now; `clio-coder usage report` remains the separate
+command for folding token and cost facts across past sessions.
+
+| View | What it shows |
+| --- | --- |
+| Accounts | Subscription and credit meters, every reported model group, remaining capacity, reset countdowns and local reset times with an explicit time zone, and stale or expired readings |
+| Session | Recorded token and cost totals, cache traffic, reasoning, and the background-call categories (side questions, handoffs, pre-warms, memory steps) |
+| Models | Each model's share of recorded processed tokens, including cache traffic, plus its detailed token and cost breakdown |
+| Workers | Active and recent runs, recorded tokens and cost, context usage, and the shared account limit when the local credential owner is known |
+
+Press 1–4, Tab/Shift+Tab, or ←/→ to change views; ↑/↓ or PgUp/PgDn to scroll;
+Home/End or Ctrl+Home/Ctrl+End to jump to either end; and Esc to close. Each
+view keeps its own scroll position while the overlay stays open.
+
+#### Used, left, and what a percentage describes
+
+One direction per label, on every surface. A filled meter cell always means
+consumed capacity, and the detailed meters in Accounts and Status label that
+number `used` and print the complement beside it as `remaining`. Compact badges
+carry the other direction and say so: `weekly 9% used` in a detailed meter is
+the same reading as `weekly 91% left` in a footer badge.
+
+Subscription percentages describe an account-wide provider window shared across
+your sessions and devices. Session tokens and costs describe only what this
+process recorded, and the two cannot be converted into each other. Context
+occupancy is a third quantity again: it measures one request against a model's
+window, not an account against its plan.
+
+#### Where quota appears outside the overlay
+
+The welcome header, the compact footer, the expanded dashboard, worker cards,
+and fleet islands read the same cached readings the overlay does.
+
+- The **welcome launchpad** carries a `Subscriptions` field beside the wordmark,
+  wrapped so every connected account and the free local-inference row stay visible.
+- The **compact footer** shows the selected model's weekly headroom on line 1,
+  beside the model identity, and only when the account and model group are
+  identifiable. Line 2 always keeps the working directory and Git branch or dirty
+  state; notices, tips, and urgent prompts borrow the rotating hint area beside
+  them. Quota never takes line 2, and the footer never promotes an unrelated
+  account's busier window in place of the selected model's.
+- The expanded dashboard's **Status** page puts the session total above the
+  account meters, **Activity** shows shared account headroom on worker cards, and
+  **Context** states that request occupancy and account limits are different
+  quantities.
+
+#### What Clio does not claim
+
+Worker badges are shared account headroom, not a measured per-worker share.
+Clio does not infer a worker's subscription consumption from its token counts or
+from account deltas, and a badge appears only for a supported local credential
+owner and the matching model group. Antigravity's Gemini group stays distinct
+from its Claude and GPT group. Remote workers and generic transports stay
+unlinked rather than being attributed to an account that may not be theirs.
+Clio's own `openai-codex` sign-in is separate storage from the Codex CLI's
+`auth.json`, so a Codex CLI reading is never attributed to an `openai-codex`
+worker.
+
+Local inference is listed at `$0.00` with no subscription window consumed. No
+saved-quota figure is claimed, because per-target token attribution does not
+exist yet.
+
+#### Reads, caching, and failures
+
+Quota reads are read-only. They read stored credentials and never refresh a
+token, write a credential, or start a sign-in. An expired credential is reported
+as expired with the provider's own sign-in guidance rather than repaired.
+
+A reading is cached for about five minutes and refreshed lazily when a surface
+that shows it is rendered, never on a background timer. A failed refresh keeps
+the last good reading and marks it `STALE` rather than blanking the account. A
+provider that reports no window for a period reports nothing for it: Codex sends
+a weekly window and no 5h window, and Clio prints the rows a provider actually
+sent instead of a fixed shape. Where a provider sends its own severity word,
+that word wins over Clio's thresholds.
+
+Two credentials on one Anthropic subscription (an `anthropic-max` sign-in and a
+Claude Code sign-in) report identical windows, so they are folded into one
+account and the apparent budget is not doubled. Accounts that merely happen to
+show equal percentages are never merged.
+
 ### Notes on individual commands
 
 The notes below explain commands whose behavior needs more than a usage line.
@@ -345,7 +431,7 @@ context every worker inherits. Esc closes the overlay, and cancels the round if
 is still streaming. `/btw` during an in-flight turn is refused with a notice
 rather than queued, because a side question answered after the run it was asked
 during has already missed its moment. The round's token usage still shows in
-`/cost`, labeled as a side question, because it was a real call and cost real
+`/usage`, labeled as a side question, because it was a real call and cost real
 money; it is deliberately not counted as a turn.
 
 `/council [--roster <name>] [--rounds <n>] [--synthesis judge|vote|none] <task>`
@@ -564,7 +650,7 @@ not a potentially double-counted total. Supported GPU drivers expose utilization
 and VRAM through sysfs. Missing counters stay unavailable; WSL measurements are
 labeled as guest measurements and do not describe the Windows host or remote GPU.
 Counter resets wait for a fresh baseline instead of showing negative rates. Memory
-bank and context-engine activity remain visible. `/cost`, `/mcp`, `/library`, `/context`, and
+bank and context-engine activity remain visible. `/usage`, `/mcp`, `/library`, `/context`, and
 Fleet Runs retain deeper inspection. Narrow or short terminals explicitly indicate
 when detail does not fit.
 
@@ -1047,9 +1133,9 @@ The footer owns live activity. Transcript actions have static running or outcome
 
 The Clio TUI maximizes operational focus, ergonomics, and discoverability:
 
-- **Welcome Launchpad & Session Header:** Prior to your first prompt, Clio renders a framed launchpad dashboard (`src/interactive/welcome-dashboard.ts`) with 11 detail rows (model route status, workspace path, permissions/autonomy, guidance, target inventory, and fleet recipes), accompanied by ASCII wordmark art at ≥76 columns and rotating hints at ≥160 columns. A bottom action row indicates the immediate step or blocker (`describe a task · Enter to send · / for commands`, or route blockers such as `/model` or `/settings targets`). On prompt submission, the launchpad collapses to a single live header row (`>C_ Clio Coder v0.5.0 · <target/model> · <workspace> · <branch>*`) tracking mid-session route or branch changes. `/new` restores the launchpad; `/resume`, `/tree`, `/fork`, and `/handoff` collapse it after transition. See [tui-design.md](../architecture/tui-design.md#51-welcome-launchpad--session-header).
+- **Welcome Launchpad & Session Header:** Prior to your first prompt, Clio renders a framed launchpad dashboard (`src/interactive/welcome-dashboard.ts`) with 11 detail rows (model route status, workspace path, permissions/autonomy, guidance, target inventory, and fleet recipes) plus a wrapping `Subscriptions` field once a connected account reports quota, accompanied by ASCII wordmark art at ≥76 columns and rotating hints at ≥160 columns. A bottom action row indicates the immediate step or blocker (`describe a task · Enter to send · / for commands`, or route blockers such as `/model` or `/settings targets`). On prompt submission, the launchpad collapses to a single live header row (`>C_ Clio Coder v0.5.1 · <target/model> · <workspace> · <branch>*`) tracking mid-session route or branch changes. `/new` restores the launchpad; `/resume`, `/tree`, `/fork`, and `/handoff` collapse it after transition. See [tui-design.md](../architecture/tui-design.md#51-welcome-launchpad--session-header).
 - **Quiet, Focused Clio Composer:** Normal composition rails remain clean and uncluttered (`src/interactive/clio-editor.ts`), omitting duplicate model identity or newline hints already provided by the footer. Exceptional operational states elevate to the top rail: `CONFIRM` (`warning` token, or `CONFIRM · FULL-AUTO` in `editorDanger`) when an approval prompt owns input, `PREPARING` during turn dispatch, `COMPACTING` during context compaction, or `FULL-AUTO` (`editorDanger`). Native editor scroll indicators (`↑/↓` line counts) remain on line 0 when drafts scroll. When the draft is empty, line 1 shows context-aware dim placeholder text (`Ask Clio…  / for commands`, `A parked call is waiting for your decision`, `Clio has your prompt and is preparing the turn`, or `Clio is compacting the session context`). During parked permission prompts, the bottom rail carries fitted decision keys (`confirmRailHint` via `src/interactive/permission-hint.ts`: `Enter` allow, or `Backspace` clear draft to allow if a draft is present; `Esc` deny; `s` stop turn; `v` inspect mutation; standing approval terms toggle via `?` on the permission card itself).
-- **Two-Line Compact Footer & Expanded Dashboard:** The compact footer (`src/interactive/footer/pages.ts`) renders an ambient two-line strip: Line 1 displays live activity phase (`accent`) and active worker counts (`agent`), model/target identity, thinking level, context meter bar, and token usage; Line 2 surfaces urgent input prompts (`Ctrl+C again to quit`, `Ctrl+G → choose key`), active notices, or rotating shortcut hints alternating with workspace cwd and git dirty state on the left, alongside session throughput and dashboard toggle keys on the right. Pressing `Alt+U` expands the dashboard into 1/4 of the viewport (minimum 8 rows), cycling through `Activity` (live worker cards and finished history), `Context` (meter bar/grid, category swatches, headroom), `Status` (Cost & Connections, Local Machine metrics, memory bank), and closed.
+- **Two-Line Compact Footer & Expanded Dashboard:** The compact footer (`src/interactive/footer/pages.ts`) renders an ambient two-line strip: Line 1 displays live activity phase (`accent`) and active worker counts (`agent`), model/target identity, thinking level, context meter bar, and token usage; Line 1 also shows the selected model’s weekly quota remaining when its account and model group are known; Line 2 preserves workspace cwd and Git branch/dirty state on the left, with rotating shortcuts, tips, or urgent notices on the right. Pressing `Alt+U` expands the dashboard into 1/4 of the viewport (minimum 8 rows), cycling through `Activity` (live worker cards and finished history), `Context` (meter bar/grid, category swatches, headroom), `Status` (Cost & Connections, Local Machine metrics, memory bank), and closed.
 - **Grouped Slash Command Palette:** Typing `/` opens an autocomplete command palette grouped by operational category (`Run`, `Inspect`, `Configure`, `Sessions`) with compact argument hints. Every suggestion is the command's one canonical spelling.
 - **Voice-First Transcript & Receipts:** User (`› `) and assistant (`✦ `) prose are formatted with a two-cell hanging indent, ensuring wrapped continuation lines remain visually tied to their voice prefix. Tool ledgers maintain full terminal width. Completed turn receipts honor Output style: Compact omits the separate receipt, Standard shows a small completion line with available duration, and Detailed includes available call counts, token usage and reasoning provenance.
 - **Transactional Settings Center:** Open `/settings` or deep-link to one of `chat`, `fleet`, `targets`, `context`, `safety`, `interface`, or `integrations`. Value edits construct change plans offering `Apply this session`, `Apply and save globally`, or `Cancel`; narrow terminals use a drill-down layout below 72 columns.

package/docs/guide/configuration-and-targets.md

@@ -687,7 +687,7 @@ Every new assistant ledger entry carries `responseModelIdObservation` in one of
 
 </details>
 
-The adapter retains `responseModel` as the differing response id because providers outside the stream tap still supply that fact. `clio-coder usage report` emits `attributedModelId`, `requestedModelIds`, and `responseModelIdObservationCounts`. Its text table and the `/cost` overlay use the labels `attributed model`, `requested model ids`, and `response model id observation`; requested ids are printed as ids rather than as `same`.
+The adapter retains `responseModel` as the differing response id because providers outside the stream tap still supply that fact. `clio-coder usage report` emits `attributedModelId`, `requestedModelIds`, and `responseModelIdObservationCounts`. Its text table and the `/usage` overlay use the labels `attributed model`, `requested model ids`, and `response model id observation`; requested ids are printed as ids rather than as `same`.
 
 The footer's last-turn line uses `response model id observation <state>`, with the id after `reported` or a historical `legacy difference-only` state. Dispatch receipt `upstreamResponses` entries carry `requestedModelId`, `responseModelIdObservation`, `differingResponseModelId`, and `providerResponseId`. The peer warning is said once per process per distinct fact (target, requested id, resolved instance, peer set), not once per turn.
 
@@ -1235,7 +1235,7 @@ integrations:
 ```
 Then invoke it using `/delegate claude-code <task>`.
 
-`/delegate [--share] <agent-id> <task>` does not accept `--model` in v0.5.0.
+`/delegate [--share] <agent-id> <task>` does not accept `--model` in v0.5.1.
 `/run --model <id>` selects a model for a Clio fleet worker; it does not configure
 an external ACP session. External model selection depends on the adapter's own
 supported configuration. Clio does not currently expose an ACP model selector.

package/docs/guide/context-continuity.md

@@ -0,0 +1,49 @@
+# Context continuity and recovery
+
+Clio can reduce a long native session while preserving the assistant's exact handoff note and the original task. Open `/context` to inspect the next request's input, output reservation, headroom, and pending handoff. The model can read the same accounting with `context(scope="budget")`.
+
+## Choosing a reduction
+
+| Action | Use it for |
+| --- | --- |
+| Automatic compaction | Routine pressure management under your configured threshold. |
+| `/context compact [instructions]` | An operator-directed summary, optionally focused on specific information. |
+| `self_compact({"note_to_self":"…"})` | An assistant-directed handoff followed by continuation of the same task. |
+| `/context recover <handoffId> <reduce\|deliver>` | Explicit recovery of an interrupted handoff. |
+
+`self_compact` is available to the native orchestrator. Dispatched workers do not receive its host callback, and external agents that own their own loop do not receive its schema through the native session tool surface. Skill restrictions and normal tool permission checks still apply.
+
+The assistant must call `self_compact` alone. A batch containing it and another tool, or two self-compaction calls, is rejected before any valid sibling executes. The note should preserve the objective, decisions, useful evidence, relevant paths, unresolved questions, and next steps. It must be nonblank and no larger than 8,192 UTF-8 bytes. Clio preserves the accepted text exactly and labels it as assistant-authored recall, rather than presenting it as an operator instruction.
+
+## What the receipt means
+
+The tool's first receipt means that the note was prepared and flushed to the session ledger. Reduction happens after that receipt has been persisted. Clio records the reduction attempt before invoking the summarizer, checkpoints the outcome, and records delivery intent before allowing another foreground request.
+
+A final, nonempty, successful assistant response acknowledges that delivery. Intermediate tool calls, empty responses, errors, cancellation, and a generic end-of-run event do not acknowledge it. Continuation does not append another operator turn or create a fresh durable-memory selection attempt.
+
+Each handoff allows at most two reduction attempts, with at most two summary stream invocations per attempt. The automatic window is bounded to 15 minutes. A new operator recovery request may renew that window, but does not refund spent attempts or mint a replacement handoff identity. Summarizer calls, including failed calls with known usage, remain attributable to their originating session.
+
+## Recovering an interrupted handoff
+
+The `/context` overlay shows the pending handoff ID and its phase. Use the exact ID:
+
+```text
+/context recover <handoffId> reduce
+/context recover <handoffId> deliver
+```
+
+`reduce` is available when the handoff has not committed and an attempt remains. `deliver` is available when a validated commit exists. A restarted process first records the interrupted state as paused; it does not automatically repeat an uncertain delivery. Recovery authority comes from the operator command and its durable control record, never from a tool argument or text found in a note.
+
+If the continuation still cannot fit, use `/context compact` to reduce more history before trying delivery again. Missing or conflicting storage evidence can prevent recovery. Clio retains uncertainty instead of silently creating a new transaction. A missing commit can be reconstructed only from a validated summary carry, using its original reserved identity and an exact storage check.
+
+Session forks inherit notes as recall only. They do not inherit permission to resume the parent's handoff. Ordinary summaries persist in the session ledger and replay after `/resume`; a separate handoff file remains useful when moving work to another session or another agent.
+
+## Request budgets and memory
+
+Submission and native continuation require estimated input plus the resolved output reservation to fit the effective window. Pending user-message framing and images count. A final check inspects the actual request after steering has been drained. Ordinary automatic-compaction preferences remain separate from this hard admission check: disabling automatic compaction cannot authorize an oversized request.
+
+Successful durable reductions invalidate older private-memory content jobs and queued memory reminders. Their known usage still counts. Restoration retains the private bank, selects a bounded set of remembered facts and procedures, and suppresses stale private status when an authoritative summary or handoff is available. The full reminder wrapper must fit, and restoration is consumed only after installation in an admitted context. This does not make remembered claims independently verified.
+
+Approved durable-memory selection is frozen for a prepared turn and its continuations. Changes in session, repository, runtime, model, or memory configuration invalidate that authority. A subsequent turn reads the current bounded store contents; a same-size rewrite cannot hide behind a file-size cache key. Default selection limits remain five records and 400 tokens. Experimental lexical ranking is not enabled by default.
+
+Token counts remain estimates unless a provider has attested the relevant prefix. Flush and checkpoint success establish the filesystem durability available to the running process; they do not guarantee survival of every hardware or power failure, or exactly-once execution by a remote provider.

package/docs/guide/proactive-memory.md

@@ -1,5 +1,8 @@
 # Proactive task memory
 
+
+After a durable context reduction, restoration uses a commit-scoped offer: stale content jobs and buffered reminders lose authority, known usage remains attributed, and restoration is consumed only after an admitted installation. See [Context continuity and recovery](context-continuity.md) for the lifecycle and its limits.
+
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still
 exist in the transcript while no longer influencing the next action. The design
@@ -19,7 +22,7 @@ writes, model resolution, reminders, handoff offers, and handoff seeding.
 | --- | --- |
 | Inspect the bank and recent memory steps | `/memory` |
 | Select a background model or change memory controls | `/settings` → **Context & Memory** |
-| Review recorded cost | `/cost` or `clio-coder usage report` |
+| Review recorded cost | `/usage` or `clio-coder usage report` |
 | Look up the default values and routing example | [Operator setup](#operator-setup) |
 | Understand what survives a handoff | [Handoff continuity](#handoff-continuity) |
 
@@ -234,7 +237,7 @@ The LLM tier costs real tokens, real seconds of model time, and a request slot o
 a server that is usually the same machine the operator's own turns run on.
 
 Every step is therefore accounted for the way a `/btw` side question is: one cost
-entry under the `background-memory` label, which `/cost` shows as its own
+entry under the `background-memory` label, which `/usage` shows as its own
 `memory steps` row, and one durable row in `<stateDir>/usage/out-of-turn.jsonl`
 carrying the usage, the call's duration, and the backend's prefill facts.
 `clio-coder usage report` folds those rows after the process exits, and `/memory`
@@ -582,7 +585,7 @@ Every exact-schema record has:
 - count of cited entries, input/output/total memory-model tokens, and latency.
 
 The same steps are also billed. See "Cost and the default decision" for the
-`/cost` row, the durable out-of-turn usage row, and the lifetime figures `/memory`
+`/usage` row, the durable out-of-turn usage row, and the lifetime figures `/memory`
 folds out of this file.
 
 `dropped` is the one outcome that ran no step. It has two causes, separated by