From 0c5f1322ae36e6681d03460fc1b32c98a042b27e Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 20:35:32 +0000 Subject: [PATCH 1/6] spec(FIX-2142): Claude Code: record subscription usage from rate_limit_event Retained spec set: SPEC.md, DECISIONS.md, three figures, and a POC that reads the pinned Claude Code CLI to show what a rate_limit_event carries. Builds on FIX-2141's usage store and query (#3768). Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6 --- specs/issues/FIX-2142/DECISIONS.md | 112 +++++++++++++ specs/issues/FIX-2142/SPEC.md | 152 ++++++++++++++++++ .../d1-error-reporter-not-recorded.svg | 93 +++++++++++ .../figures/open-show-what-claude-reports.svg | 93 +++++++++++ .../issues/FIX-2142/figures/what-changes.svg | 89 ++++++++++ .../FIX-2142/poc/rate-limit-event/NOTES.md | 31 ++++ .../FIX-2142/poc/rate-limit-event/inspect.mjs | 68 ++++++++ 7 files changed, 638 insertions(+) create mode 100644 specs/issues/FIX-2142/DECISIONS.md create mode 100644 specs/issues/FIX-2142/SPEC.md create mode 100644 specs/issues/FIX-2142/figures/d1-error-reporter-not-recorded.svg create mode 100644 specs/issues/FIX-2142/figures/open-show-what-claude-reports.svg create mode 100644 specs/issues/FIX-2142/figures/what-changes.svg create mode 100644 specs/issues/FIX-2142/poc/rate-limit-event/NOTES.md create mode 100644 specs/issues/FIX-2142/poc/rate-limit-event/inspect.mjs diff --git a/specs/issues/FIX-2142/DECISIONS.md b/specs/issues/FIX-2142/DECISIONS.md new file mode 100644 index 0000000000..58a1b3c10c --- /dev/null +++ b/specs/issues/FIX-2142/DECISIONS.md @@ -0,0 +1,112 @@ +# FIX-2142 · Decisions + +[Spec](SPEC.md) · **Decisions** + +FIX-2141 built the store, its one writer and its one query, and left three things for the first +run-time writer: the hook, the slot feed and the one-window write. This issue adds them, for the +one source Claude Code sanctions: the `rate_limit_event` a run sends. What that event carries +decides the rest, so the pinned CLI was read first ([POC](poc/rate-limit-event/NOTES.md)). + +## The tree + +```mermaid +flowchart TD + I["FIX-2142"] --> O["Open · ship what Claude Code reports · recommended"] + O -.->|"rejected"| X1["hold for a full percent · nothing until Anthropic ships one"] + O -.->|"banned"| X2["api/oauth/usage, the credentials file, the SDK's experimental call"] + I --> D1["D1 · Error Reporter runs not recorded"] + D1 -.->|"rejected"| X3["a second writer path · Workforce on harness-manager"] +``` + +Solid edges are what you're signing. Dashed edges lost, and the label says why. + + +## Open · Ship Claude's view with what Claude Code reports, or hold it? + +**Recommended: ship it.** + +| | | +|---|---| +| **Plain terms** | Claude Code tells a run its limits only when they change. Below a warning line it says which window binds, "ok", and when it resets, with no percent. Near a limit it sends the percent. At the limit it says "reached" and when it resets. The issue asked for a percent on every window after every run; no allowed source gives that today | +| **Ship it** | A person gets the warning the epic asks for (a percent as a window nears its limit, and "reached until 14:00"), and a reset time otherwise. The view says "under Claude's warning line", never a number it wasn't sent | +| **Hold it** | Nothing for Claude until Anthropic stabilises a usage read. The SDK has one, named `usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET`, and it calls the endpoint the brief bans | +| **Locks in** | `HarnessUsageWindow.usedPercent` may be `null`, and the window gains `level`: `ok`, `warning`, `reached`, or `null` (Codex, which always sends a percent). A missing percent is never stored or shown as 0 | +| **What would change my mind** | Anthropic stabilising a usage read in the Agent SDK, or a headless run shown to run a status line (which gets both windows' percent on every response; one try did not run it). Either fills the percent through the same writer | +| **What being wrong costs** | Someone below the line plans with a reset time and no number. Cheap to reverse: a fuller source writes the same window | + +![Open question: ship Claude's view with what Claude Code reports, recommended, beside holding for a full percent. Decides it: the warning before a pool runs out arrives now. The price: below the warning line, a reset time and no percent](figures/open-show-what-claude-reports.svg) + +It comes down to whether a warning now beats a full number later. + + +## D1 · The Error Reporter's Claude runs are not recorded + +| | | +|---|---| +| **Instead of** | Giving the Error Reporter's harness feeds an `onUsage` and installing the usage collection on its flow | +| **Because** | An event reports the whole pool, whatever used it, so the next coding run or the next look reports what a bug report used. Recording it would add a second flow that writes the collection and make Workforce depend on harness-manager for a rare, short run (tenet 3, *earn every addition*). Workforce stays a reader of the query | +| **Locks in** | Claude usage is written by harness-manager's coding runs, by its session door's talks (the same harness, run as the person talking), and by a refresh. `ErrorReporterHarnessFeeds` gains nothing | + +![D1: whether the Error Reporter's Claude runs are recorded. Not recorded, chosen, beside recording them too. Decides it: the next run reports the same pool. The price: a host where only the Error Reporter runs Claude shows an older row](figures/d1-error-reporter-not-recorded.svg) + +It comes down to what the next run tells us: the same pool, so the reporter's own write adds little. + +**What would change my mind:** a host that runs Claude only for bug reports, or Workforce gaining +coding runs of its own. + +## Decided, not asked + +- **The hook is the session hook's twin, in core.** `HarnessUsageHook` takes a report (the + harness's name, one `HarnessUsageWindow`, and when it was observed) and the run's context. It + names no vendor and no Workforce idea. The report names its harness, so the manager's feed + writes under `claude-code` without knowing which harness sits in its slot. +- **Only the run owner's row.** The feed writes through the run's own context, so the + `user`-scoped row is the principal that drained the task (or, on the session door, the person + talking). It never lists or writes another person's row, as FIX-2141 D1 requires; another + person's copy ages, and its age says so. +- **The one-window write goes through `recordHarnessUsage`,** still the collection's only writer. + It upserts one window by id with `origin: "run"`, keeps the others, and never goes backwards per + window (an event older than the stored window is refused). It leaves account and plan alone, + and lifts a no-number status to `windows`: a run that reports a window proves a subscription. +- **A read keeps what runs wrote, while the account is unchanged.** A full reading replaces its + own windows and keeps `run` windows it doesn't name when the hashed account is the same. A new + account or a no-number status clears them, as FIX-2141's leg h requires. Codex has no `run` + windows, so nothing changes for it. +- **Claude's account comes from the existing probe.** `readClaudeUsage` (in `claude-code`) maps + `probeClaudeAccount`: a key source is `api-key`; a sign-in or an OAuth token source is `windows` + with the email as the account id (hashed by the writer, never stored) and the plan, and no + windows; `none` is `signed-out`; `sdk-missing` is `unavailable`. FIX-2141's throttle and + timeout apply. +- **What maps, and the units.** `rateLimitType` is the window id; `five_hour` is 300 minutes and + every `seven_day*` 10 080; others (`overage`) have none and are labelled by id. `utilization`, a + fraction, is multiplied by 100: a unit change, not a derivation. `resetsAt` (seconds) becomes + ms. `status` maps to level: `allowed` → `ok`, `allowed_warning` → `warning`, `rejected` → + `reached`. An event with no `rateLimitType` (an API-key run) writes nothing. Overage fields are + not shown. +- **A usage write never touches the run.** The agent awaits `onUsage` like `onSession` (tracked, + so a late write can't land after the run ends), but a throw is logged and swallowed, and the + feed is not fenced: a replaced attempt's event is still a true reading of the pool. +- **The view says why a number is missing.** `null` percent with `ok` reads "under Claude's + warning line"; with `reached`, "limit reached". The server's clock still decides `rolledOver`. +- **Settled by POC: what an event carries.** [`poc/rate-limit-event/`](poc/rate-limit-event/NOTES.md) + read the pinned CLI (SDK 0.3.234): sent on change only, at least once per run on a subscription; + percent only on a warning; `utilization` a fraction; `resetsAt` in seconds; no window on an API + key. 8 of 8 found, and the control (`/bin/ls`) finds 0 and fails. A live event is goal leg g. + +## Considered and dropped + +| Option | Why it lost | +|---|---| +| The SDK's experimental usage call | It says not to rely on it, and it calls the banned endpoint | +| A status-line command on each run | A terminal feature; one headless try did not run it. Named under *what would change my mind* | +| Writing the event to every person's row | One pool on one machine, but a person's row is theirs (FIX-2141 D1). The age covers the gap | +| Turning "ok" into a percent (say, under 90 %) | A guess, which the brief forbids | +| A record per run, summed | Events report the pool, not the run's share. Per-worker tokens are FIX-2145 | + +## How it got here + +- **Draft** — framed as FIX-2141's reserved run-time half: the hook twin in core, the slot feed + and one-window write in harness-manager, and Claude's account from the existing probe. Reading + the pinned CLI first showed the event carries a percent only near a limit, so the issue's + "percent on every window" is put to Jake as an open question, recommended: ship what Claude + Code reports. diff --git a/specs/issues/FIX-2142/SPEC.md b/specs/issues/FIX-2142/SPEC.md new file mode 100644 index 0000000000..653a5f7eef --- /dev/null +++ b/specs/issues/FIX-2142/SPEC.md @@ -0,0 +1,152 @@ +# FIX-2142 · Claude Code: record subscription usage from rate_limit_event + +**Spec** · [Decisions](DECISIONS.md) + +## Five people, before and after + +| Someone who… | Today | After | +|---|---|---| +| **runs Claude Code in Shift Manager on a Pro or Max sign-in** | Learns a window ran out when a run fails | After any coding run, opens Usage and sees Claude's window: "5-hour · under Claude's warning line · resets 14:00", "from a run", checked 3 minutes ago | +| **is burning a window fast** | Nothing until the run fails | Sees "5-hour · 91 % used · resets 14:00" as soon as Claude Code warns, and "limit reached · resets 14:00" when it stops | +| **runs Claude Code with an API key** | Nothing | Sees "Claude Code uses an API key: no subscription limit". No percent | +| **has not signed Claude Code in on this machine** | Nothing | Sees "Claude Code is not signed in: not available automatically". No percent | +| **shares a machine with a second person** | Nothing | Each sees only the windows their own runs reported, with their age. A run never writes another person's row | + +## The goal, and how we'll know it's met + +**After a person's Claude Code run, Shift Manager shows them each Claude window that run reported, +with the percent when Claude Code sent one, the level and reset time always, where it came from and +how old it is, through the same query as Codex.** + +| Is it the right goal? | | +|---|---| +| **The real need** | *"Work fails with no warning when a pool runs out, and we can't plan which harness to use"* (the epic). *"After any Claude run, Shift Manager shows Claude's percent used and reset time per window"* (the issue) | +| **Smaller, and shipped** | The issue's percent on every window after every run. Claude Code sends a percent only near a limit ([POC](poc/rate-limit-event/NOTES.md)); below that it sends the window, *ok* and its reset. The only sources with a full percent are banned or unstable. This is [the open question](DECISIONS.md#open), recommended: ship it | +| **Bigger, and not this issue's** | Tokens and cost on an API key (FIX-2145). Cursor and Grok Build (FIX-2143, FIX-2144) | +| **Not done if** | A missing percent shows as 0 or as a guess · a fraction shows as a percent (0.91 as "0.91 %") · a run writes a row that isn't its owner's · a refresh wipes the windows a run wrote · an older event replaces a newer window · a usage write fails a run · signed out or API key shows any percent | + +```mermaid +flowchart LR + A["Shift Manager served · harness-manager runs · Claude Code SDK scripted at its import seam"] --> L1["leg a · run sends allowed"] + A --> L2["leg b · run sends a warning at 0.91"] + A --> L3["leg c · run sends rejected"] + A --> L4["leg d · Alice runs, Bob looks"] + A --> L5["leg e · refresh after a run · same sign-in, then an API key"] + A --> L6["leg f · two events out of order · a write that throws"] + A --> L7["leg g · Jake's own sign-in · owed by a person"] + L1 --> R["the query's rows · the Usage view in a browser"] + L2 --> R + L3 --> R + L4 --> R + L5 --> R + L6 --> R + L7 --> R + R -->|"a ok no percent · b 91 · c reached · d Bob has no Claude window · e kept then cleared · f newer kept, run completes · g matches"| P["PASS · goal met"] + R -.->|"control · no x100"| F1["must FAIL leg b"] + R -.->|"control · missing percent as 0"| F2["must FAIL leg a"] + R -.->|"control · write every row"| F3["must FAIL leg d"] + R -.->|"control · a read replaces run windows"| F4["must FAIL leg e"] +``` + +The check reads what the query returns and what the Usage view draws. Each control must fail, or +the check proves nothing. + +| How we verify | | +|---|---| +| **Goal check** | `goals/shift-manager/it-shows-claude-usage-left/` · no model · run by the implementer at completion · verdict in the implementation PR | +| **Signal** | a: one `five_hour` window, `usedPercent: null`, level `ok`, `resetsAt` in ms, `origin: "run"`; the view shows the reset and "under Claude's warning line", no number. b: `usedPercent: 91`, level `warning`, the view shows "91 %". c: level `reached`, the view shows "limit reached" and the reset. d: Alice's run writes Alice's row; Bob's query has no Claude window. e: a refresh on the same sign-in keeps the run's window and adds the plan; after a move to an API key, the row is `api-key` with no window. f: an event older than the stored window leaves it; an `onUsage` write that throws leaves the run `completed`. g: after Jake's real run, the reset time matches Claude Code's `/status` | +| **Input** | A scripted Agent SDK through `claudeCodeAgent`'s import seam, sending the event shapes the pinned CLI builds ([POC](poc/rate-limit-event/NOTES.md)). The real `probeClaudeAccount` on an empty and an API-key home for leg e | +| **Anti-game** | Events enter as SDK messages, not as hook calls. Rows read through the query over HTTP, the view read in a browser | +| **Control that must fail** | `GOAL_CONTROL=no-scale` FAILS b on *91*. `GOAL_CONTROL=absent-as-zero` FAILS a on *no number*. `GOAL_CONTROL=fan-out` FAILS d on *no Claude window*. `GOAL_CONTROL=read-replaces-run` FAILS e on *keeps the run's window* | + +Leg g needs a Claude subscription, which no CI has. Until Jake or `fsd-qa` runs it, the +implementation PR says *goal met except leg g*. + +## What changes + +![Before and after. Today Claude Code's rate_limit_event reaches the harness and is dropped. After: the harness hands each one to onUsage as one window; harness-manager's feed writes it into the run owner's row through recordHarnessUsage; a refresh writes the account from probeClaudeAccount through the same writer; the store and query are FIX-2141's. The Error Reporter's runs are not recorded](figures/what-changes.svg) + +A run writes the one window it heard about; a look writes who is signed in. One writer for both. + +```diff + // packages/shift-manager/teams/devteam/harness.mts (the Lab's slot feeds) + export interface HarnessFeeds { + cwd: …; resume: …; onSession: …; ++ onUsage: HarnessUsageHook; + mcpTools?: ProjectMcpToolsResolver; + } + // claudeCodeHarness already spreads its feeds into claudeCodeAgent({ ...feeds, … }) + + // packages/shift-manager/teams/devteam/fsdev.config.mts (the host) + usage: { + codex: ({ signal } = {}) => readCodexUsage({ env: …, signal }), ++ "claude-code": () => readClaudeUsage({ env: claudeCodeEnv() }), + }, +``` + +```ts +const { harnesses } = await harnessUsage(); +// [{ harness: "claude-code", status: "windows", plan: "max", +// windows: [{ id: "five_hour", minutes: 300, usedPercent: null, level: "ok", +// resetsAt, checkedAt, ageMs, rolledOver: false, origin: "run" }] }, …] +``` + +**Docs:** update *Tools → Claude Code SDK* (what a run reports about usage, and when there is no +percent), *Tools → Coding agents* (`onUsage`, a window without a percent), *Orchestration → +Harness manager* (the `onUsage` feed, run-written windows), and the READMEs of `core`, +`claude-code`, `harness-manager` and `shift-manager`. No new page. + +## How a number gets to the screen + +```mermaid +flowchart LR + E["Claude Code · rate_limit_event"] --> H["claudeCodeAgent · onUsage"] + H --> F["harness-manager feed · run owner"] + F --> W["recordHarnessUsage · one window"] + P["readClaudeUsage · probeClaudeAccount"] -->|"refresh"| W + W --> C["harness-usage · user scope"] + Q["harnessUsage query"] --> C + V["Usage view · a worker"] --> Q +``` + +## What stays as it is + +- **The store and the query.** FIX-2141's collection, its one writer and its one query. The + window shape gains a level and may lack a percent; nothing else moves. +- **Codex.** Its windows always carry a percent, and its level stays empty. +- **Credentials.** Nothing reads the credentials file, calls `api/oauth/usage`, or uses the SDK's + experimental usage call. +- **The run.** A usage write never fails, slows or fences a run. + +## What's already here, and the debt + +| Already here | What this does with it | +|---|---| +| Ways to put a harness's usage in the store | **One:** a registered reader through `harnessUsageAction` (FIX-2141, [#3768](https://github.com/fixpoint-labs/flow-state-dev/pull/3768)). **Extends** it: Claude Code gets a reader (`readClaudeUsage`), and the writer gains a one-window form for runs. This is the second *source*, not a second way to write | +| Ways a harness reports to its host during a run | **One:** `HarnessSessionHook` / `onSession` (core, fed by harness-manager's slot). **Twins** it: `HarnessUsageHook` / `onUsage`, as FIX-2141 *Decided, not asked* reserved | +| `probeClaudeAccount` (claude-code) | **Builds on** it: the reader maps its answer, so there is no second account read (FIX-2141, *Decided, not asked*) | +| FIX-2141's window shape: *"Percent is 0 to 100 as the vendor sent it, never derived"* | **Amends** it: the percent may be absent, and a level says why. Claude's fraction is scaled to 0 to 100; nothing else is derived | +| The Error Reporter runs Claude Code outside harness-manager (FIX-1983) | **Leaves** it unrecorded ([D1](DECISIONS.md#d1)) | +| Kitchen-sink's Claude Code mode runs `claudeCodeAgent` with no harness-manager | **Leaves** it unrecorded: it has no usage query to feed | + +| The debt | | +|---|---| +| **Removes** | Nothing. The event was dropped, not handled | +| **Adds** | One hook type and one slot feed (twins of the session pair), one reader, a one-window write, a level on the window. Permanent by design | +| **Leaves** | Below Claude's warning line there is no percent, until Anthropic stabilises a usage read (the SDK's call says not to rely on it). The Error Reporter's runs ([D1](DECISIONS.md#d1)) | + +**Net: up, small.** One hook beside its twin and one source into an existing store. + +## Sign off + +**Open, recommended · [ship Claude's view with what Claude Code reports](DECISIONS.md#open)**, a +percent near a limit and the level and reset always. If wrong: someone below the warning line +plans with a reset time and no number. + +**[The debt](#whats-already-here-and-the-debt), net up, small:** a hook twin and one source. If +wrong: a second way to write usage, which the one writer exists to prevent. + +1. **[D1](DECISIONS.md#d1) · The Error Reporter's Claude runs are not recorded.** If wrong: a + host that runs Claude only for bug reports shows an old Claude row, and its age says so. + +Feature · `core` + `claude-code` + `harness-manager` + `shift-manager` · small to medium · second child of epic FIX-2139 · builds on [#3768](https://github.com/fixpoint-labs/flow-state-dev/pull/3768) diff --git a/specs/issues/FIX-2142/figures/d1-error-reporter-not-recorded.svg b/specs/issues/FIX-2142/figures/d1-error-reporter-not-recorded.svg new file mode 100644 index 0000000000..6b6fb3ebdd --- /dev/null +++ b/specs/issues/FIX-2142/figures/d1-error-reporter-not-recorded.svg @@ -0,0 +1,93 @@ + + + + + + D1 · THE CALL + Are the Error Reporter's Claude runs recorded? + + + + CHOSEN + Not recorded + + INSTEAD OF + Record them too + + + + + WHAT THE NEXT + RUN TELLS US + ▸ DECIDES IT + + + The next run reports the pool + an event is the whole pool, whatever used it + = + The same pool, sooner + one report more, on a rare run + + + FRESHNESS + − + Older on a reporter-only host + the age says how old + + + Fresh after every run + including bug reports + + + + WHAT IT ADDS + + + Nothing + one writer path, in harness-manager + − + A second writer path + and Workforce depending on harness-manager + + + + + LOCKS IN + Runs and talks under harness-manager write + and a refresh writes the account + + + + FLIPS IF + A host runs Claude only for bug reports + then the reporter's feeds gain onUsage + + diff --git a/specs/issues/FIX-2142/figures/open-show-what-claude-reports.svg b/specs/issues/FIX-2142/figures/open-show-what-claude-reports.svg new file mode 100644 index 0000000000..fe1fd5b152 --- /dev/null +++ b/specs/issues/FIX-2142/figures/open-show-what-claude-reports.svg @@ -0,0 +1,93 @@ + + + + + + OPEN · RECOMMENDED + Ship Claude's view with what Claude Code reports, or hold it? + + + + CHOSEN + Ship what Claude Code reports + + INSTEAD OF + Hold for a full percent + + + + + WARNING BEFORE + IT RUNS OUT + ▸ DECIDES IT + + + A warning, with a percent + near a limit, and limit reached until a time + − + Nothing for now + until Anthropic ships a stable usage read + + + BELOW THE LINE + − + A reset time, no percent + under Claude's warning line + + + A percent every time + when a source exists + + + + SOURCES + = + Sanctioned only + rate_limit_event and the account probe + = + Sanctioned only + nothing to call yet + + + + + LOCKS IN + A window's percent may be absent + then its level says ok, warning or reached + + + + FLIPS IF + A stable usage read reaches the SDK + then it fills the percent; the store stays + + diff --git a/specs/issues/FIX-2142/figures/what-changes.svg b/specs/issues/FIX-2142/figures/what-changes.svg new file mode 100644 index 0000000000..0ab440f3bb --- /dev/null +++ b/specs/issues/FIX-2142/figures/what-changes.svg @@ -0,0 +1,89 @@ + + + + + + + TODAY · CLAUDE CODE REPORTS ITS LIMITS AND NOTHING KEEPS THEM + + Claude Code run + rate_limit_event + + the harness drops the event · Usage has no Claude row + + + + + AFTER · A RUN WRITES ONE WINDOW, A LOOK WRITES THE ACCOUNT, ONE WRITER FOR BOTH + + + Claude Code run + rate_limit_event · sparse + + + claudeCodeAgent + onUsage · one window + + + + manager's onUsage feed + the run owner's row only + + + + recordHarnessUsage + + one-window write · origin run + + + + readClaudeUsage + probeClaudeAccount · on refresh + + + + harness-usage/** · FIX-2141 + same store · percent may be absent + + + + harnessUsage query → Usage + percent when Claude sends one + + + + Error Reporter's Claude runs + not recorded · D1 + + + + + + + + + + + diff --git a/specs/issues/FIX-2142/poc/rate-limit-event/NOTES.md b/specs/issues/FIX-2142/poc/rate-limit-event/NOTES.md new file mode 100644 index 0000000000..69206eeb54 --- /dev/null +++ b/specs/issues/FIX-2142/poc/rate-limit-event/NOTES.md @@ -0,0 +1,31 @@ +# What a `rate_limit_event` carries, read from the pinned CLI + +Throwaway evidence, not production code. FIX-2142 rests on what Claude Code +sends in a `rate_limit_event`, and the Agent SDK's type (`SDKRateLimitInfo`) +says only that every field but `status` is optional. The CLI the pinned SDK +ships (`@anthropic-ai/claude-agent-sdk` 0.3.234) shows when each one is there. + +```bash +node specs/issues/FIX-2142/poc/rate-limit-event/inspect.mjs # 8/8 found, exit 0 +node specs/issues/FIX-2142/poc/rate-limit-event/inspect.mjs /bin/ls # 0/8, exit 1 (the control) +``` + +## What it showed + +| Claim | What the CLI does | +|---|---| +| Sparse | It builds the limits from each API response's `anthropic-ratelimit-unified-*` headers and sends an event only when they differ from the last ones. The first response of a run differs from the empty start, so a run on a subscription sends at least one | +| Plain `allowed` has no percent | Below a warning, the event is `{ status: "allowed", resetsAt, rateLimitType }`: the window the server names as the binding one (`representative-claim`) and its reset. No `utilization` | +| A percent comes with a warning | `utilization` is set only on `allowed_warning`: when the server sends a `*-surpassed-threshold` header, or when the CLI's own early-burn check fires (5-hour: 90 % used with 72 % of the window left to run; 7-day: 25 / 50 / 75 % used by 15 / 35 / 60 % of the window) | +| Limit reached | `status: "rejected"` with `resetsAt` and the window. No `utilization` | +| Units | `utilization` is a fraction, 0 to 1 (the thresholds above are 0.9, 0.75 …, and the status line multiplies the same header by 100 for `used_percentage`). `resetsAt` is epoch **seconds** (compared as `resetsAt * 1000` with `Date.now()`) | +| No subscription | On an API key the limits reset to a bare `allowed` with no window, so an event, if any, names no `rateLimitType` | + +## What it did not show + +- A live event from a real subscription. That is the goal check's leg owed by a + person (Jake's sign-in), as FIX-2141's leg f is. +- Whether a headless SDK run runs a configured status line, which gets both + windows' percent on every response. One try with an invalid key did not run it + (`statusLine` command never wrote its file). Not settled; the status line is a + terminal feature, and FIX-2142 does not depend on it. diff --git a/specs/issues/FIX-2142/poc/rate-limit-event/inspect.mjs b/specs/issues/FIX-2142/poc/rate-limit-event/inspect.mjs new file mode 100644 index 0000000000..370a5c0498 --- /dev/null +++ b/specs/issues/FIX-2142/poc/rate-limit-event/inspect.mjs @@ -0,0 +1,68 @@ +// Throwaway evidence for FIX-2142, not production code. +// Reads the Claude Code binary the pinned Agent SDK ships and prints, for each +// claim the spec rests on, the code that shows it. Exits 1 if any is missing. +// +// node specs/issues/FIX-2142/poc/rate-limit-event/inspect.mjs [path/to/claude] +import { readFileSync, readdirSync, existsSync } from "node:fs"; +import { join } from "node:path"; + +function findBinary() { + const store = "node_modules/.pnpm"; + for (const dir of readdirSync(store)) { + if (!dir.startsWith("@anthropic-ai+claude-agent-sdk-linux-x64@")) continue; + const bin = join(store, dir, "node_modules/@anthropic-ai/claude-agent-sdk-linux-x64/claude"); + if (existsSync(bin)) return bin; + } + throw new Error("no pinned claude binary under node_modules/.pnpm; run pnpm install"); +} + +const bin = process.argv[2] ?? findBinary(); +const text = readFileSync(bin).toString("latin1"); + +const claims = [ + { + claim: "An event is built from the current limits and sent on every status change (print mode)", + re: /function kjp\(e,t,r=\{\}\)\{let n=O_v\(e,r\);if\(!n\)return;return\{type:"rate_limit_event"/, + }, + { + claim: "A change is emitted only when the limits differ from the last ones (sparse)", + re: /if\(!zy\(this\.currentLimits,a\)\)this\.emitStatusChange\(a\)/, + }, + { + claim: "Plain 'allowed' carries status, reset and the representative window, and no utilization", + re: /return\{status:w,resetsAt:o,unifiedRateLimitFallbackAvailable:i,\.\.\.s&&\{rateLimitType:s\}/, + }, + { + claim: "Utilization is set only on a warning: a server threshold header, or the early-burn thresholds", + re: /status:"allowed_warning",resetsAt:s\?Math\.round\(Number\(s\)\):void 0,rateLimitType:n,utilization:a/, + }, + { + claim: "Utilization is a fraction 0..1 (thresholds 0.9, 0.75, 0.5, 0.25)", + re: /rateLimitType:"five_hour",claimAbbrev:"5h",windowSeconds:18000,thresholds:\[\{utilization:0\.9,timePct:0\.72\}\]/, + }, + { + claim: "The status line multiplies the same header value by 100 for its used_percentage", + re: /used_percentage:T\.five_hour\.utilization\*100/, + }, + { + claim: "resetsAt is epoch seconds (compared as resetsAt*1000 with Date.now())", + re: /e\.status==="rejected"&&e\.resetsAt!==void 0&&e\.resetsAt\*1000<=Date\.now\(\)/, + }, + { + claim: "Without a subscription the limits reset to bare 'allowed' with no window", + re: /if\(!nNr\(i\)\)\{if\(this\.rawUtilization=\{\}/, + }, +]; + +let missing = 0; +for (const { claim, re } of claims) { + const m = re.exec(text); + if (m === null) { + missing++; + console.log(`MISSING ${claim}`); + } else { + console.log(`FOUND ${claim}\n ${text.slice(m.index, m.index + 160).replace(/\s+/g, " ")}`); + } +} +console.log(`\n${claims.length - missing}/${claims.length} found in ${bin}`); +process.exit(missing === 0 ? 0 : 1); From 21ce069e82083f06dc9534d704c409f5a1c9734c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 20:41:19 +0000 Subject: [PATCH 2/6] spec(FIX-2142): record round-1 review notes for the implementer Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6 --- specs/issues/FIX-2142/DECISIONS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/specs/issues/FIX-2142/DECISIONS.md b/specs/issues/FIX-2142/DECISIONS.md index 58a1b3c10c..87828154ee 100644 --- a/specs/issues/FIX-2142/DECISIONS.md +++ b/specs/issues/FIX-2142/DECISIONS.md @@ -110,3 +110,15 @@ coding runs of its own. the pinned CLI first showed the event carries a percent only near a limit, so the issue's "percent on every window" is put to Jake as an open question, recommended: ship what Claude Code reports. + +## Notes from review + +For the implementer to weigh against the real code. Recorded as given, not folded into the design. + +- **Cursor, round 1 (hook payload).** *"Mirror `HarnessSessionHook` more closely — `(window, ctx)` with harness id coming from the slot feed, and `checkedAt` only on the window."* The report names its harness today because harness-manager's feed is harness-neutral; if the host's slot names it instead, either shape holds the direction. +- **Cursor, round 1 (window lengths).** *"Hard-coded `five_hour` → 300 / `seven_day*` → 10080 duplicates CLI knowledge … persist `id` + optional `minutes`, label by id when minutes are absent."* +- **Cursor, round 1 (one merge function).** *"A single named merge spec (function signature + invariants) … would shrink implementer error surface."* The run write and the read merge should share one function in `harness-usage.ts`. +- **Cursor, round 1 (what is swallowed).** *"Worth one explicit sentence on expected hook failures (only persistence errors?) so implementers don't accidentally broaden catch-all swallow."* +- **Cursor, round 1 (percent and level).** *"Consider a documented invariant … or a Claude-biased discriminated shape at the harness boundary while keeping the flat neutral type for Codex."* Note: `reached` has no percent and a warning can lack one if the header is missing, so check any invariant against the POC first. +- **Cursor, round 1 (fixtures).** *"Check in small fixture event objects (per status) as the contract tests/goal seam rely on; keep `inspect.mjs` as optional archaeology."* +- **Cursor, round 1 (docs and types).** One harness-usage section with README pointers may be enough; extend harness-manager's `HarnessFeeds` and use core's `HarnessUsageHook` in Shift Manager rather than a drifting local copy. Guard writes on an actual window change and keep per-event logging out of the message loop. From b16b125dc57b33879328a570a5062f870992ab9d Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 20:42:25 +0000 Subject: [PATCH 3/6] spec(FIX-2142): fold the Architect's coherence asks into Decided, not asked Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6 --- specs/issues/FIX-2142/DECISIONS.md | 33 +++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/specs/issues/FIX-2142/DECISIONS.md b/specs/issues/FIX-2142/DECISIONS.md index 87828154ee..c560cc7843 100644 --- a/specs/issues/FIX-2142/DECISIONS.md +++ b/specs/issues/FIX-2142/DECISIONS.md @@ -64,14 +64,25 @@ coding runs of its own. `user`-scoped row is the principal that drained the task (or, on the session door, the person talking). It never lists or writes another person's row, as FIX-2141 D1 requires; another person's copy ages, and its age says so. -- **The one-window write goes through `recordHarnessUsage`,** still the collection's only writer. - It upserts one window by id with `origin: "run"`, keeps the others, and never goes backwards per - window (an event older than the stored window is refused). It leaves account and plan alone, - and lifts a no-number status to `windows`: a run that reports a window proves a subscription. +- **The one-window write goes through `recordHarnessUsage`,** still the collection's only writer: + a second form inside the same function, under the same compare-and-swap. It upserts one window + by id with `origin: "run"` and keeps the others. It compares against that window's own + `checkedAt` (an older event is refused) and leaves the record's `checkedAt`, account and plan + alone: the record clock stays the reader's. It lifts a no-number status to `windows` only when + the event is newer than the record's `checkedAt`, so a stale event never undoes a fresher + `api-key` or `signed-out`. On a shared window id, the newer `checkedAt` wins, whichever wrote it. +- **The collection is installed where the writes happen.** `harnessUsageCollection` joins the + manager's capability and the session door's, and `harness-usage` joins the manager's reserved + accessors, so a host can't claim it. Without that, the feed would throw on a missing collection + and the swallow would hide it. `HarnessFeeds` in harness-manager gains `onUsage` at both places + that build it (the manager and the door, which stubs `onSession` today); the Lab's own + `HarnessFeeds` is a superset of it. `onUsage` stays out of `claudeCodeAgent`'s in-session-only + guard: it owns no continuity, so it races nothing. - **A read keeps what runs wrote, while the account is unchanged.** A full reading replaces its - own windows and keeps `run` windows it doesn't name when the hashed account is the same. A new - account or a no-number status clears them, as FIX-2141's leg h requires. Codex has no `run` - windows, so nothing changes for it. + own windows and keeps `run` windows it doesn't name. "Unchanged" includes a stored account that + was never read (`null`) and a reading with no account id: both adopt and keep. Only a different + non-null hash, or a no-number status, clears them, as FIX-2141's leg h requires. Codex has no + `run` windows, so nothing changes for it. - **Claude's account comes from the existing probe.** `readClaudeUsage` (in `claude-code`) maps `probeClaudeAccount`: a key source is `api-key`; a sign-in or an OAuth token source is `windows` with the email as the account id (hashed by the writer, never stored) and the plan, and no @@ -88,6 +99,8 @@ coding runs of its own. feed is not fenced: a replaced attempt's event is still a true reading of the pool. - **The view says why a number is missing.** `null` percent with `ok` reads "under Claude's warning line"; with `reached`, "limit reached". The server's clock still decides `rolledOver`. + `level` defaults to `null` so Codex rows stored by #3768 still parse; the Codex reader sets it + `null`, and the view (which assumes a number today) handles a missing one. - **Settled by POC: what an event carries.** [`poc/rate-limit-event/`](poc/rate-limit-event/NOTES.md) read the pinned CLI (SDK 0.3.234): sent on change only, at least once per run on a subscription; percent only on a warning; `utilization` a fraction; `resetsAt` in seconds; no window on an API @@ -111,6 +124,12 @@ coding runs of its own. "percent on every window" is put to Jake as an open question, recommended: ship what Claude Code reports. +- **Architect** — `fsd-architect` found the set coherent + ([agent-mailbox#45](https://github.com/fixpoint-labs/agent-mailbox/pull/45#issuecomment-6374320229)) + and pinned five things now in *Decided, not asked*: the collection installed on the manager and + the door, the one-window form inside the one writer, the run write leaving the record clock + alone, a `null` account adopting rather than clearing, and the newer window winning a shared id. + ## Notes from review For the implementer to weigh against the real code. Recorded as given, not folded into the design. From b27a2f441d679de4c197f13f3571cc2a9d7168c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 20:43:33 +0000 Subject: [PATCH 4/6] spec(FIX-2142): bind run windows to their account; cover the session door in the goal check Codex review round 1: the run's account comes from its own accountInfo(), so a sign-in change clears the old account's windows; token-only sign-ins are a named limit. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6 --- specs/issues/FIX-2142/DECISIONS.md | 32 +++++++++++++++++++++--------- specs/issues/FIX-2142/SPEC.md | 8 ++++---- 2 files changed, 27 insertions(+), 13 deletions(-) diff --git a/specs/issues/FIX-2142/DECISIONS.md b/specs/issues/FIX-2142/DECISIONS.md index c560cc7843..58aecb603d 100644 --- a/specs/issues/FIX-2142/DECISIONS.md +++ b/specs/issues/FIX-2142/DECISIONS.md @@ -57,9 +57,11 @@ coding runs of its own. ## Decided, not asked - **The hook is the session hook's twin, in core.** `HarnessUsageHook` takes a report (the - harness's name, one `HarnessUsageWindow`, and when it was observed) and the run's context. It - names no vendor and no Workforce idea. The report names its harness, so the manager's feed - writes under `claude-code` without knowing which harness sits in its slot. + harness's name, one `HarnessUsageWindow`, when it was observed, and the account id the run is + signed in as, or `null`) and the run's context. It names no vendor and no Workforce idea. The + report names its harness, so the manager's feed writes under `claude-code` without knowing which + harness sits in its slot. `claudeCodeAgent` asks its own running query for `accountInfo()` once, + at the first event (no extra process), so a run's windows are bound to the account that sent them. - **Only the run owner's row.** The feed writes through the run's own context, so the `user`-scoped row is the principal that drained the task (or, on the session door, the person talking). It never lists or writes another person's row, as FIX-2141 D1 requires; another @@ -78,14 +80,21 @@ coding runs of its own. that build it (the manager and the door, which stubs `onSession` today); the Lab's own `HarnessFeeds` is a superset of it. `onUsage` stays out of `claudeCodeAgent`'s in-session-only guard: it owns no continuity, so it races nothing. -- **A read keeps what runs wrote, while the account is unchanged.** A full reading replaces its - own windows and keeps `run` windows it doesn't name. "Unchanged" includes a stored account that - was never read (`null`) and a reading with no account id: both adopt and keep. Only a different - non-null hash, or a no-number status, clears them, as FIX-2141's leg h requires. Codex has no - `run` windows, so nothing changes for it. +- **Windows belong to one account at a time.** A run write or a full reading whose account hash + differs from the stored non-null one replaces the record's account and clears every window the + new account didn't send; so a sign-in change shows no old account's percent, whether a run or a + look notices it first. A stored account that was never read (`null`) adopts the incoming one and + keeps its windows. A reading with no account keeps the stored one. A full reading replaces its + own windows and keeps `run` windows it doesn't name while the account matches; a no-number status + clears them all, as FIX-2141's leg h requires. Codex has no `run` windows, so nothing changes for + it. +- **A token-only sign-in has no account id.** `probeClaudeAccount` can answer with a token source + and no email; the run's `accountInfo()` gives the same. Then the account is `null`, and a move + between two token-only accounts isn't seen as a change: their windows age and roll over instead. + A named limit, not a guess at an identity. - **Claude's account comes from the existing probe.** `readClaudeUsage` (in `claude-code`) maps `probeClaudeAccount`: a key source is `api-key`; a sign-in or an OAuth token source is `windows` - with the email as the account id (hashed by the writer, never stored) and the plan, and no + with the email, when there is one, as the account id (hashed by the writer, never stored) and the plan, and no windows; `none` is `signed-out`; `sdk-missing` is `unavailable`. FIX-2141's throttle and timeout apply. - **What maps, and the units.** `rateLimitType` is the window id; `five_hour` is 300 minutes and @@ -130,6 +139,11 @@ coding runs of its own. the door, the one-window form inside the one writer, the run write leaving the record clock alone, a `null` account adopting rather than clearing, and the newer window winning a shared id. +- **Review round 1** — Codex showed that a run's windows had no account, so a sign-in change + before the next look left one account's percent beside another's; the hook now carries the + run's account from its own `accountInfo()`, and the token-only case is a named limit. It also + added the session door's talk to the goal check's ownership leg. Cursor's notes are below. + ## Notes from review For the implementer to weigh against the real code. Recorded as given, not folded into the design. diff --git a/specs/issues/FIX-2142/SPEC.md b/specs/issues/FIX-2142/SPEC.md index 653a5f7eef..30d32788da 100644 --- a/specs/issues/FIX-2142/SPEC.md +++ b/specs/issues/FIX-2142/SPEC.md @@ -23,14 +23,14 @@ how old it is, through the same query as Codex.** | **The real need** | *"Work fails with no warning when a pool runs out, and we can't plan which harness to use"* (the epic). *"After any Claude run, Shift Manager shows Claude's percent used and reset time per window"* (the issue) | | **Smaller, and shipped** | The issue's percent on every window after every run. Claude Code sends a percent only near a limit ([POC](poc/rate-limit-event/NOTES.md)); below that it sends the window, *ok* and its reset. The only sources with a full percent are banned or unstable. This is [the open question](DECISIONS.md#open), recommended: ship it | | **Bigger, and not this issue's** | Tokens and cost on an API key (FIX-2145). Cursor and Grok Build (FIX-2143, FIX-2144) | -| **Not done if** | A missing percent shows as 0 or as a guess · a fraction shows as a percent (0.91 as "0.91 %") · a run writes a row that isn't its owner's · a refresh wipes the windows a run wrote · an older event replaces a newer window · a usage write fails a run · signed out or API key shows any percent | +| **Not done if** | A missing percent shows as 0 or as a guess · a fraction shows as a percent (0.91 as "0.91 %") · a run writes a row that isn't its owner's · a refresh wipes the windows a run wrote · one account's percent shows beside another's · an older event replaces a newer window · a usage write fails a run · signed out or API key shows any percent | ```mermaid flowchart LR A["Shift Manager served · harness-manager runs · Claude Code SDK scripted at its import seam"] --> L1["leg a · run sends allowed"] A --> L2["leg b · run sends a warning at 0.91"] A --> L3["leg c · run sends rejected"] - A --> L4["leg d · Alice runs, Bob looks"] + A --> L4["leg d · Alice runs, Bob talks to his finished run, each looks"] A --> L5["leg e · refresh after a run · same sign-in, then an API key"] A --> L6["leg f · two events out of order · a write that throws"] A --> L7["leg g · Jake's own sign-in · owed by a person"] @@ -41,7 +41,7 @@ flowchart LR L5 --> R L6 --> R L7 --> R - R -->|"a ok no percent · b 91 · c reached · d Bob has no Claude window · e kept then cleared · f newer kept, run completes · g matches"| P["PASS · goal met"] + R -->|"a ok no percent · b 91 · c reached · d only the owner's row changes · e kept, then cleared on a new key or account · f newer kept, run completes · g matches"| P["PASS · goal met"] R -.->|"control · no x100"| F1["must FAIL leg b"] R -.->|"control · missing percent as 0"| F2["must FAIL leg a"] R -.->|"control · write every row"| F3["must FAIL leg d"] @@ -54,7 +54,7 @@ the check proves nothing. | How we verify | | |---|---| | **Goal check** | `goals/shift-manager/it-shows-claude-usage-left/` · no model · run by the implementer at completion · verdict in the implementation PR | -| **Signal** | a: one `five_hour` window, `usedPercent: null`, level `ok`, `resetsAt` in ms, `origin: "run"`; the view shows the reset and "under Claude's warning line", no number. b: `usedPercent: 91`, level `warning`, the view shows "91 %". c: level `reached`, the view shows "limit reached" and the reset. d: Alice's run writes Alice's row; Bob's query has no Claude window. e: a refresh on the same sign-in keeps the run's window and adds the plan; after a move to an API key, the row is `api-key` with no window. f: an event older than the stored window leaves it; an `onUsage` write that throws leaves the run `completed`. g: after Jake's real run, the reset time matches Claude Code's `/status` | +| **Signal** | a: one `five_hour` window, `usedPercent: null`, level `ok`, `resetsAt` in ms, `origin: "run"`; the view shows the reset and "under Claude's warning line", no number. b: `usedPercent: 91`, level `warning`, the view shows "91 %". c: level `reached`, the view shows "limit reached" and the reset. d: Alice's run writes Alice's row and Bob's query has no Claude window; then Bob talks to his own finished run through the session door, and only Bob's row changes. e: a refresh on the same sign-in keeps the run's window and adds the plan; after a move to an API key, the row is `api-key` with no window; after a move to account B, B's next run clears A's windows before any look. f: an event older than the stored window leaves it; an `onUsage` write that throws leaves the run `completed`. g: after Jake's real run, the reset time matches Claude Code's `/status` | | **Input** | A scripted Agent SDK through `claudeCodeAgent`'s import seam, sending the event shapes the pinned CLI builds ([POC](poc/rate-limit-event/NOTES.md)). The real `probeClaudeAccount` on an empty and an API-key home for leg e | | **Anti-game** | Events enter as SDK messages, not as hook calls. Rows read through the query over HTTP, the view read in a browser | | **Control that must fail** | `GOAL_CONTROL=no-scale` FAILS b on *91*. `GOAL_CONTROL=absent-as-zero` FAILS a on *no number*. `GOAL_CONTROL=fan-out` FAILS d on *no Claude window*. `GOAL_CONTROL=read-replaces-run` FAILS e on *keeps the run's window* | From d44806e99428225ac9d91f7671394451cb83144f Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 20:51:31 +0000 Subject: [PATCH 5/6] spec(FIX-2142): make an account change one ordered step; only a newer run lifts a no-number status Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6 --- specs/issues/FIX-2142/DECISIONS.md | 30 +++++++++++++++++++++--------- specs/issues/FIX-2142/SPEC.md | 2 +- 2 files changed, 22 insertions(+), 10 deletions(-) diff --git a/specs/issues/FIX-2142/DECISIONS.md b/specs/issues/FIX-2142/DECISIONS.md index 58aecb603d..f3025a7d07 100644 --- a/specs/issues/FIX-2142/DECISIONS.md +++ b/specs/issues/FIX-2142/DECISIONS.md @@ -57,8 +57,8 @@ coding runs of its own. ## Decided, not asked - **The hook is the session hook's twin, in core.** `HarnessUsageHook` takes a report (the - harness's name, one `HarnessUsageWindow`, when it was observed, and the account id the run is - signed in as, or `null`) and the run's context. It names no vendor and no Workforce idea. The + harness's name, one `HarnessUsageWindow`, when it was observed, when the run started, and the + account id the run is signed in as, or `null`) and the run's context. It names no vendor and no Workforce idea. The report names its harness, so the manager's feed writes under `claude-code` without knowing which harness sits in its slot. `claudeCodeAgent` asks its own running query for `accountInfo()` once, at the first event (no extra process), so a run's windows are bound to the account that sent them. @@ -71,8 +71,9 @@ coding runs of its own. by id with `origin: "run"` and keeps the others. It compares against that window's own `checkedAt` (an older event is refused) and leaves the record's `checkedAt`, account and plan alone: the record clock stays the reader's. It lifts a no-number status to `windows` only when - the event is newer than the record's `checkedAt`, so a stale event never undoes a fresher - `api-key` or `signed-out`. On a shared window id, the newer `checkedAt` wins, whichever wrote it. + the *run started* after the record's `checkedAt`. A run that was already going when a look found + `api-key` or `signed-out` belongs to the old sign-in, so its later events don't undo the look. + On a shared window id, the newer `checkedAt` wins, whichever wrote it. - **The collection is installed where the writes happen.** `harnessUsageCollection` joins the manager's capability and the session door's, and `harness-usage` joins the manager's reserved accessors, so a host can't claim it. Without that, the feed would throw on a missing collection @@ -80,11 +81,15 @@ coding runs of its own. that build it (the manager and the door, which stubs `onSession` today); the Lab's own `HarnessFeeds` is a superset of it. `onUsage` stays out of `claudeCodeAgent`'s in-session-only guard: it owns no continuity, so it races nothing. -- **Windows belong to one account at a time.** A run write or a full reading whose account hash - differs from the stored non-null one replaces the record's account and clears every window the - new account didn't send; so a sign-in change shows no old account's percent, whether a run or a - look notices it first. A stored account that was never read (`null`) adopts the incoming one and - keeps its windows. A reading with no account keeps the stored one. A full reading replaces its +- **Windows belong to one account at a time, and a change of account is one step.** The record + keeps `accountAt`, when its account was last set. A run write or a full reading whose account + differs from the stored one is a rebind. It wins only if it was observed after `accountAt`, and + then it replaces the account and `accountAt`, clears the plan and every window the new account + didn't send. An older rebind is refused whole, so a retried event from account A can't land in a + record that account B already took, and it can't wipe B's windows either. A move from a `null` + account to a named one is a rebind too. A `null` account may be a real token-only sign-in, so its + windows are never handed to a named account. A sign-in change shows no old account's percent or + plan, whether a run or a look notices it first. A reading with no account keeps the stored one. A full reading replaces its own windows and keeps `run` windows it doesn't name while the account matches; a no-number status clears them all, as FIX-2141's leg h requires. Codex has no `run` windows, so nothing changes for it. @@ -144,6 +149,13 @@ coding runs of its own. run's account from its own `accountInfo()`, and the token-only case is a named limit. It also added the session door's talk to the goal check's ownership leg. Cursor's notes are below. +- **Review round 2** — Codex found four ways the account rules could still mix accounts. A run + that started before a look found `api-key` could reopen the windows. A token-only account's + windows could pass to a named one, which reverses the Architect's "a `null` account adopts". + A retried event could rebind a newer account. And the old plan was kept on a switch. All four + close with one change: an account change is a whole-record step, ordered by `accountAt`, and a + no-number status is lifted only by a run that started after it. Leg f covers the retried event. + ## Notes from review For the implementer to weigh against the real code. Recorded as given, not folded into the design. diff --git a/specs/issues/FIX-2142/SPEC.md b/specs/issues/FIX-2142/SPEC.md index 30d32788da..73dffd24f5 100644 --- a/specs/issues/FIX-2142/SPEC.md +++ b/specs/issues/FIX-2142/SPEC.md @@ -54,7 +54,7 @@ the check proves nothing. | How we verify | | |---|---| | **Goal check** | `goals/shift-manager/it-shows-claude-usage-left/` · no model · run by the implementer at completion · verdict in the implementation PR | -| **Signal** | a: one `five_hour` window, `usedPercent: null`, level `ok`, `resetsAt` in ms, `origin: "run"`; the view shows the reset and "under Claude's warning line", no number. b: `usedPercent: 91`, level `warning`, the view shows "91 %". c: level `reached`, the view shows "limit reached" and the reset. d: Alice's run writes Alice's row and Bob's query has no Claude window; then Bob talks to his own finished run through the session door, and only Bob's row changes. e: a refresh on the same sign-in keeps the run's window and adds the plan; after a move to an API key, the row is `api-key` with no window; after a move to account B, B's next run clears A's windows before any look. f: an event older than the stored window leaves it; an `onUsage` write that throws leaves the run `completed`. g: after Jake's real run, the reset time matches Claude Code's `/status` | +| **Signal** | a: one `five_hour` window, `usedPercent: null`, level `ok`, `resetsAt` in ms, `origin: "run"`; the view shows the reset and "under Claude's warning line", no number. b: `usedPercent: 91`, level `warning`, the view shows "91 %". c: level `reached`, the view shows "limit reached" and the reset. d: Alice's run writes Alice's row and Bob's query has no Claude window; then Bob talks to his own finished run through the session door, and only Bob's row changes. e: a refresh on the same sign-in keeps the run's window and adds the plan; after a move to an API key, the row is `api-key` with no window; after a move to account B, B's next run clears A's windows before any look. f: an event older than the stored window leaves it; account A's event retried after account B's leaves B's account, plan and windows; a run that started before a look found `api-key` doesn't bring windows back; an `onUsage` write that throws leaves the run `completed`. g: after Jake's real run, the reset time matches Claude Code's `/status` | | **Input** | A scripted Agent SDK through `claudeCodeAgent`'s import seam, sending the event shapes the pinned CLI builds ([POC](poc/rate-limit-event/NOTES.md)). The real `probeClaudeAccount` on an empty and an API-key home for leg e | | **Anti-game** | Events enter as SDK messages, not as hook calls. Rows read through the query over HTTP, the view read in a browser | | **Control that must fail** | `GOAL_CONTROL=no-scale` FAILS b on *91*. `GOAL_CONTROL=absent-as-zero` FAILS a on *no number*. `GOAL_CONTROL=fan-out` FAILS d on *no Claude window*. `GOAL_CONTROL=read-replaces-run` FAILS e on *keeps the run's window* | From e4656647dd4868b67549462c7067725b94fb9587 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 20:52:57 +0000 Subject: [PATCH 6/6] spec(FIX-2142): record accountAt as a stored-shape change with its default for existing rows Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6 --- specs/issues/FIX-2142/DECISIONS.md | 2 +- specs/issues/FIX-2142/SPEC.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/specs/issues/FIX-2142/DECISIONS.md b/specs/issues/FIX-2142/DECISIONS.md index f3025a7d07..24558378bf 100644 --- a/specs/issues/FIX-2142/DECISIONS.md +++ b/specs/issues/FIX-2142/DECISIONS.md @@ -30,7 +30,7 @@ Solid edges are what you're signing. Dashed edges lost, and the label says why. | **Plain terms** | Claude Code tells a run its limits only when they change. Below a warning line it says which window binds, "ok", and when it resets, with no percent. Near a limit it sends the percent. At the limit it says "reached" and when it resets. The issue asked for a percent on every window after every run; no allowed source gives that today | | **Ship it** | A person gets the warning the epic asks for (a percent as a window nears its limit, and "reached until 14:00"), and a reset time otherwise. The view says "under Claude's warning line", never a number it wasn't sent | | **Hold it** | Nothing for Claude until Anthropic stabilises a usage read. The SDK has one, named `usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET`, and it calls the endpoint the brief bans | -| **Locks in** | `HarnessUsageWindow.usedPercent` may be `null`, and the window gains `level`: `ok`, `warning`, `reached`, or `null` (Codex, which always sends a percent). A missing percent is never stored or shown as 0 | +| **Locks in** | `HarnessUsageWindow.usedPercent` may be `null`, and the window gains `level`: `ok`, `warning`, `reached`, or `null` (Codex, which always sends a percent). A missing percent is never stored or shown as 0. The record gains `accountAt`, when its account was last set; a row #3768 stored without it reads as 0, so the first rebind always wins | | **What would change my mind** | Anthropic stabilising a usage read in the Agent SDK, or a headless run shown to run a status line (which gets both windows' percent on every response; one try did not run it). Either fills the percent through the same writer | | **What being wrong costs** | Someone below the line plans with a reset time and no number. Cheap to reverse: a fuller source writes the same window | diff --git a/specs/issues/FIX-2142/SPEC.md b/specs/issues/FIX-2142/SPEC.md index 73dffd24f5..d4856e8003 100644 --- a/specs/issues/FIX-2142/SPEC.md +++ b/specs/issues/FIX-2142/SPEC.md @@ -126,13 +126,14 @@ flowchart LR | Ways a harness reports to its host during a run | **One:** `HarnessSessionHook` / `onSession` (core, fed by harness-manager's slot). **Twins** it: `HarnessUsageHook` / `onUsage`, as FIX-2141 *Decided, not asked* reserved | | `probeClaudeAccount` (claude-code) | **Builds on** it: the reader maps its answer, so there is no second account read (FIX-2141, *Decided, not asked*) | | FIX-2141's window shape: *"Percent is 0 to 100 as the vendor sent it, never derived"* | **Amends** it: the percent may be absent, and a level says why. Claude's fraction is scaled to 0 to 100; nothing else is derived | +| FIX-2141's record (account, plan, `checkedAt`, windows) | **Amends** it: adds `accountAt`, when the account was last set, so an account change is one ordered step. A row stored without it reads as 0 | | The Error Reporter runs Claude Code outside harness-manager (FIX-1983) | **Leaves** it unrecorded ([D1](DECISIONS.md#d1)) | | Kitchen-sink's Claude Code mode runs `claudeCodeAgent` with no harness-manager | **Leaves** it unrecorded: it has no usage query to feed | | The debt | | |---|---| | **Removes** | Nothing. The event was dropped, not handled | -| **Adds** | One hook type and one slot feed (twins of the session pair), one reader, a one-window write, a level on the window. Permanent by design | +| **Adds** | One hook type and one slot feed (twins of the session pair), one reader, a one-window write, a level on the window, `accountAt` on the record. Permanent by design | | **Leaves** | Below Claude's warning line there is no percent, until Anthropic stabilises a usage read (the SDK's call says not to rely on it). The Error Reporter's runs ([D1](DECISIONS.md#d1)) | **Net: up, small.** One hook beside its twin and one source into an existing store.