@iowarp/clio-coder 0.5.0 → 0.5.1

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/proactive-memory.md

@@ -19,7 +19,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 +234,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 +582,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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.5.0",
+	"version": "0.5.1",
 	"description": "An open-source terminal coding agent for scientific software: your models, bounded workers, and inspectable evidence.",
 	"keywords": [
 		"ai",

package/src/cli/usage.ts

@@ -114,7 +114,7 @@ function addResponseModelIdObservation(counts: ResponseModelIdObservationCounts,
  * session pre-warm, and a proactive-memory step are real spend and belong in
  * the token and cost totals, but none of them is a turn: they never entered
  * the session. `turns` therefore subtracts them from the folded row count,
- * which is exactly what the `/cost` overlay does.
+ * which is exactly what the `/usage` overlay does.
  */
 interface CallOrigins {
 	rows: number;
@@ -435,7 +435,7 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		}
 	}
 
-	// Token and cost facts fold the same per-call usage the `/cost` overlay
+	// Token and cost facts fold the same per-call usage the `/usage` overlay
 	// reseeds from, through the same session-domain function, so the report and
 	// the overlay cannot disagree about what a session spent.
 	// Keyed by the model id accounting attributes the call to. A reported LM

package/src/domains/gateway/mcp/client.ts

@@ -35,7 +35,7 @@ import {
 } from "./protocol.js";
 
 export const MCP_CLIENT_NAME = "clio-coder";
-export const DEFAULT_MCP_CLIENT_VERSION = "0.5.0";
+export const DEFAULT_MCP_CLIENT_VERSION = "0.5.1";
 export const DEFAULT_INITIALIZE_TIMEOUT_MS = 15_000;
 export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 export const DEFAULT_STDERR_TAIL_BYTES = 16 * 1024;

package/src/domains/observability/background-memory-usage.ts

@@ -10,7 +10,7 @@
  *
  * The two writes are the same pair the side-question path makes: the
  * in-process cost tracker under the `background-memory` label, which is what
- * `/cost` folds, and one durable row in the out-of-turn usage store, which is
+ * `/usage` folds, and one durable row in the out-of-turn usage store, which is
  * what an archive reader folds after the process is gone.
  */
 

package/src/domains/observability/cost.ts

@@ -7,7 +7,7 @@
  *
  * Per-entry token breakdown (input/output/cacheRead/cacheWrite/reasoning)
  * matches the shape of pi-ai's `Usage` plus provider-specific reasoning detail
- * fields. The /cost overlay aggregates it via `aggregateCostEntries`; the TUI
+ * fields. The /usage overlay aggregates it via `aggregateCostEntries`; the TUI
  * footer consumes the session sum through `ObservabilityContract.sessionTokens()`.
  */
 
@@ -92,7 +92,7 @@ export function formatCostAggregate(cost: CostAggregate | null | undefined): str
 
 /**
  * What a fixed-width surface says when there is no cost claim. The footer and
- * `/cost` drop their cost field instead; a table cell that owns a column cannot,
+ * `/usage` drop their cost field instead; a table cell that owns a column cannot,
  * so it says the same thing in words rather than inventing `$0.00`.
  */
 export const COST_NOT_MEASURED = "not measured";
@@ -134,7 +134,7 @@ export interface UsageBreakdown {
 }
 
 /**
- * What produced a priced call, when it was not an ordinary turn. `/cost` and
+ * What produced a priced call, when it was not an ordinary turn. `/usage` and
  * the usage surfaces separate these out so an operator can see that money was
  * spent beside the session rather than inside it.
  */

package/src/domains/observability/extension.ts

@@ -53,7 +53,7 @@ function recordDispatchCost(
 	}
 	telemetry.record("counter", "tokens.total", payload.tokenCount);
 	// Dispatch terminal payloads carry the same full split as receipts. Preserve
-	// it so /cost and the footer agree with the fleet board instead of showing
+	// it so /usage and the footer agree with the fleet board instead of showing
 	// zero input/output/cache for worker-only sessions.
 	cost.accumulate(
 		payload.targetId,

package/src/domains/observability/metrics.ts

@@ -1,5 +1,5 @@
 /**
- * Thin reducer over TelemetrySnapshot. Produces a view the TUI + /cost overlay
+ * Thin reducer over TelemetrySnapshot. Produces a view the TUI + /usage overlay
  * consume. Stays pure so tests can hand-roll snapshots and assert the shape.
  */
 

package/src/domains/quota/anthropic-max-provider.ts

@@ -0,0 +1,134 @@
+/**
+ * Quota adapter for the `anthropic-max` runtime, the account Clio itself
+ * spends when it runs a native turn.
+ *
+ * Unlike `claude-code`, this credential belongs to Clio: it is the OAuth
+ * record her own auth storage persists under the `anthropic` provider id.
+ * The adapter reads the stored credential without triggering a refresh,
+ * because a quota read must never mutate an authentication record.
+ *
+ * Both adapters can point at the same Anthropic account. That is a display
+ * concern rather than a correctness one: each reports what its own
+ * credential sees, and a consumer that shows both should say which
+ * credential produced which row.
+ */
+
+import { openAuthStorage } from "../providers/auth/index.js";
+import { fetchAnthropicUsage } from "./anthropic-usage.js";
+import type { QuotaProvider, UsageSnapshot } from "./types.js";
+
+export const ANTHROPIC_MAX_QUOTA_PROVIDER_ID = "anthropic-max";
+
+/** The provider id Clio's auth storage files an Anthropic OAuth credential under. */
+const AUTH_PROVIDER_ID = "anthropic";
+const DISPLAY_NAME = "Anthropic Max";
+const REQUEST_TIMEOUT_MS = 15_000;
+
+/** The subset of Clio's stored OAuth credential this adapter needs. */
+export interface AnthropicMaxCredentials {
+	accessToken: string;
+	/** Epoch milliseconds the access token expires, or null when the record omits it. */
+	expiresAtMs: number | null;
+	hasRefreshToken: boolean;
+}
+
+export interface AnthropicMaxQuotaOptions {
+	readCredentials?: () => Promise<AnthropicMaxCredentials | null>;
+	fetch?: typeof globalThis.fetch;
+	timeoutMs?: number;
+	now?: () => Date;
+}
+
+/** Shape a stored auth credential into the fields a usage read needs. */
+export function parseStoredAnthropicCredential(raw: unknown): AnthropicMaxCredentials | null {
+	if (!isRecord(raw) || raw.type !== "oauth") return null;
+	const access = raw.access;
+	if (typeof access !== "string" || access.length === 0) return null;
+	const refresh = raw.refresh;
+	return {
+		accessToken: access,
+		expiresAtMs: asNumber(raw.expires),
+		hasRefreshToken: typeof refresh === "string" && refresh.length > 0,
+	};
+}
+
+/**
+ * Read Clio's stored Anthropic credential.
+ *
+ * `AuthStorage.get` is the accessor that does no refresh, unlike
+ * `resolveApiKey`, which renews an expiring credential as a side effect.
+ */
+async function readStoredCredential(): Promise<AnthropicMaxCredentials | null> {
+	try {
+		return parseStoredAnthropicCredential(openAuthStorage().get(AUTH_PROVIDER_ID));
+	} catch {
+		return null;
+	}
+}
+
+/** Build the read-only `anthropic-max` quota adapter. */
+export function createAnthropicMaxQuotaProvider(options: AnthropicMaxQuotaOptions = {}): QuotaProvider {
+	const readCredentials = options.readCredentials ?? readStoredCredential;
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
+	const now = options.now ?? (() => new Date());
+
+	const snapshot = (
+		status: UsageSnapshot["status"],
+		message: string | null,
+		extra: Partial<UsageSnapshot> = {},
+	): UsageSnapshot => ({
+		providerId: ANTHROPIC_MAX_QUOTA_PROVIDER_ID,
+		displayName: DISPLAY_NAME,
+		status,
+		windows: [],
+		message,
+		fetchedAt: now().toISOString(),
+		...extra,
+	});
+
+	return {
+		id: ANTHROPIC_MAX_QUOTA_PROVIDER_ID,
+		displayName: DISPLAY_NAME,
+
+		async detect(): Promise<boolean> {
+			return (await readCredentials()) !== null;
+		},
+
+		async fetch(): Promise<UsageSnapshot> {
+			const credentials = await readCredentials();
+			if (credentials === null) {
+				return snapshot("no_credentials", "Clio holds no Anthropic OAuth credential");
+			}
+			if (credentials.expiresAtMs !== null && credentials.expiresAtMs <= now().getTime()) {
+				return snapshot(
+					"expired",
+					credentials.hasRefreshToken
+						? "Clio's Anthropic token expired; the next turn refreshes it"
+						: "Run clio-coder auth login anthropic again",
+				);
+			}
+
+			const usage = await fetchAnthropicUsage(credentials.accessToken, { fetch: doFetch, timeoutMs });
+			if (usage.status !== "ok") {
+				return snapshot(usage.status, usage.message ?? "Run clio-coder auth login anthropic again", {
+					retryAfterSeconds: usage.retryAfterSeconds,
+				});
+			}
+			return snapshot("ok", null, { windows: usage.windows, credits: usage.credits });
+		},
+	};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asNumber(value: unknown): number | null {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string") {
+		const parsed = Number.parseFloat(value.trim());
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	return null;
+}

package/src/domains/quota/anthropic-usage.ts

@@ -0,0 +1,220 @@
+/**
+ * Shared reader for Anthropic's OAuth usage endpoint.
+ *
+ * Two runtimes spend an Anthropic subscription: the `claude-code` CLI with
+ * its own stored login, and `anthropic-max` with the OAuth credential Clio
+ * itself holds. The account surface is the same endpoint and the same two
+ * response shapes, so only the token source differs. This module owns the
+ * request and the parsing; each adapter owns its credential.
+ *
+ * The endpoint has shipped both a `limits[]` array and flat
+ * `five_hour`/`seven_day` buckets, and has been observed serving both at
+ * once. The array wins when present because only it carries severity,
+ * the active flag, and per-model scope.
+ */
+
+import { parseRetryAfterSeconds, type UsageCredits, type UsageSnapshot, type UsageWindow } from "./types.js";
+
+export const ANTHROPIC_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+export const ANTHROPIC_OAUTH_BETA = "oauth-2025-04-20";
+
+const WINDOW_ORDER: Record<string, number> = { session: 0, weekly: 1 };
+
+/** What one usage read produced, before an adapter stamps its own identity on it. */
+export interface AnthropicUsageOutcome {
+	status: UsageSnapshot["status"];
+	message: string | null;
+	windows: UsageWindow[];
+	credits: UsageCredits | null;
+	retryAfterSeconds: number | null;
+}
+
+export interface AnthropicUsageDependencies {
+	fetch: typeof globalThis.fetch;
+	timeoutMs: number;
+}
+
+function outcome(
+	status: UsageSnapshot["status"],
+	message: string | null,
+	extra: Partial<AnthropicUsageOutcome> = {},
+): AnthropicUsageOutcome {
+	return { status, message, windows: [], credits: null, retryAfterSeconds: null, ...extra };
+}
+
+/** Read current Anthropic usage with a bearer token, reporting failure as a status. */
+export async function fetchAnthropicUsage(
+	token: string,
+	dependencies: AnthropicUsageDependencies,
+): Promise<AnthropicUsageOutcome> {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), dependencies.timeoutMs);
+	let response: Response;
+	try {
+		response = await dependencies.fetch(ANTHROPIC_USAGE_URL, {
+			method: "GET",
+			headers: {
+				Authorization: `Bearer ${token}`,
+				"anthropic-beta": ANTHROPIC_OAUTH_BETA,
+			},
+			signal: controller.signal,
+		});
+	} catch (error) {
+		return outcome("error", describeError(error, dependencies.timeoutMs));
+	} finally {
+		clearTimeout(timer);
+	}
+
+	if (response.status === 401 || response.status === 403) {
+		await discardBody(response);
+		return outcome("expired", null);
+	}
+	if (response.status === 429) {
+		await discardBody(response);
+		return outcome("error", "HTTP 429", {
+			retryAfterSeconds: parseRetryAfterSeconds(response.headers.get("Retry-After")),
+		});
+	}
+	if (response.status !== 200) {
+		await discardBody(response);
+		return outcome("error", `HTTP ${response.status}`);
+	}
+
+	let body: unknown;
+	try {
+		body = await response.json();
+	} catch {
+		return outcome("error", "Unexpected usage response");
+	}
+	if (!isRecord(body)) {
+		return outcome("error", "Unexpected usage response");
+	}
+
+	return outcome("ok", null, { windows: usageWindows(body), credits: usageCredits(body.spend) });
+}
+
+/** Windows from `limits[]` when the endpoint sends it, otherwise the flat buckets. */
+function usageWindows(body: Record<string, unknown>): UsageWindow[] {
+	const fromLimits = windowsFromLimits(body.limits);
+	const windows = fromLimits.length > 0 ? fromLimits : windowsFromFlat(body);
+	return windows.sort((left, right) => {
+		const order = (WINDOW_ORDER[left.key] ?? 2) - (WINDOW_ORDER[right.key] ?? 2);
+		return order !== 0 ? order : left.label.localeCompare(right.label);
+	});
+}
+
+function windowsFromLimits(raw: unknown): UsageWindow[] {
+	if (!Array.isArray(raw)) return [];
+	const windows: UsageWindow[] = [];
+	for (const entry of raw) {
+		if (!isRecord(entry)) continue;
+		const percent = asNumber(entry.percent);
+		if (percent === null) continue;
+		const common: Pick<UsageWindow, "usedPct" | "resetsAt" | "severity" | "active"> = {
+			usedPct: percent,
+			resetsAt: asIsoString(entry.resets_at),
+		};
+		if (typeof entry.severity === "string") common.severity = entry.severity;
+		if (entry.is_active === true) common.active = true;
+		if (entry.kind === "session") {
+			windows.push({ key: "session", label: "5h", short: "5h", ...common });
+		} else if (entry.kind === "weekly_all") {
+			windows.push({ key: "weekly", label: "Weekly", short: "wk", ...common });
+		} else if (entry.kind === "weekly_scoped") {
+			const name = scopeName(entry.scope);
+			if (name === null) continue;
+			windows.push({ key: `weekly_scoped.${slug(name)}`, label: name, scope: name, ...common });
+		}
+	}
+	return windows;
+}
+
+function windowsFromFlat(body: Record<string, unknown>): UsageWindow[] {
+	const windows: UsageWindow[] = [];
+	const fiveHour = bucketWindow(body.five_hour, "session", "5h", "5h");
+	if (fiveHour !== null) windows.push(fiveHour);
+	const sevenDay = bucketWindow(body.seven_day, "weekly", "Weekly", "wk");
+	if (sevenDay !== null) windows.push(sevenDay);
+	return windows;
+}
+
+function bucketWindow(raw: unknown, key: string, label: string, short: string): UsageWindow | null {
+	if (!isRecord(raw)) return null;
+	const usedPct = asNumber(raw.utilization);
+	if (usedPct === null) return null;
+	return { key, label, short, usedPct, resetsAt: asIsoString(raw.resets_at) };
+}
+
+function scopeName(raw: unknown): string | null {
+	if (!isRecord(raw)) return null;
+	const model = raw.model;
+	if (!isRecord(model)) return null;
+	const name = typeof model.display_name === "string" ? model.display_name.trim() : "";
+	if (name.length === 0) return null;
+	return slug(name) === "all-models" || slug(name) === "all" ? null : name;
+}
+
+/** Credit balance from the `spend` block, present only for credit-billed plans. */
+function usageCredits(raw: unknown): UsageCredits | null {
+	if (!isRecord(raw) || raw.enabled !== true) return null;
+	const percent = asNumber(raw.percent);
+	const limit = majorAmount(raw.limit);
+	if (limit === null) {
+		return percent === null ? null : { display: `${percent.toFixed(0)}% used`, usedPct: percent };
+	}
+	const used = majorAmount(raw.used);
+	if (used === null) return null;
+	const currency = isRecord(raw.limit) && typeof raw.limit.currency === "string" ? raw.limit.currency : "USD";
+	const symbol = currency === "USD" ? "$" : "";
+	const usedPct = percent ?? (limit > 0 ? (used / limit) * 100 : null);
+	return { display: `${symbol}${used.toFixed(2)} / ${symbol}${limit.toFixed(2)}`, usedPct };
+}
+
+function majorAmount(raw: unknown): number | null {
+	if (!isRecord(raw)) return null;
+	const minor = asNumber(raw.amount_minor);
+	if (minor === null) return null;
+	const exponent = asNumber(raw.exponent) ?? 0;
+	return minor / 10 ** exponent;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asNumber(value: unknown): number | null {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string") {
+		const parsed = Number.parseFloat(value.trim());
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	return null;
+}
+
+function asIsoString(value: unknown): string | null {
+	if (typeof value !== "string" || value.trim().length === 0) return null;
+	const parsed = new Date(value);
+	return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+}
+
+function slug(value: string): string {
+	return value
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+function describeError(error: unknown, timeoutMs: number): string {
+	if (error instanceof Error) {
+		return error.name === "AbortError" ? `timeout after ${timeoutMs}ms` : error.message;
+	}
+	return String(error);
+}
+
+async function discardBody(response: Response): Promise<void> {
+	try {
+		await response.body?.cancel();
+	} catch {
+		return;
+	}
+}