Skip to content

spec(FIX-2142): Claude Code: record subscription usage from rate_limit_event - #3771

Merged
jhoffner merged 6 commits into
mainfrom
spec/FIX-2142
Oct 23, 2026
Merged

jhoffner merged 6 commits into
mainfrom
spec/FIX-2142

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Someone who… Today After
runs Claude Code in Shift Manager on a Pro or Max sign-in Learns that a window ran out when a run fails After a coding run, opens Usage and sees the window: "5-hour · under Claude's warning line · resets 14:00", "from a run", and its age
uses a window quickly Nothing until the run fails Sees "5-hour · 91 % used" when 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 person sees only the windows that their own runs reported. A run never writes the row of a different person

Goal: after a Claude Code run, Shift Manager shows the person each Claude window that the run reported. It shows the percent when Claude Code sent one, and always the level, the reset time, the source and the age. It uses the same query as Codex.

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"]
Loading

The check reads the rows that the query returns and the Usage view in a browser. Check: goals/shift-manager/it-shows-claude-usage-left/, no model. Controls no-scale, absent-as-zero, fan-out and read-replaces-run must fail. Leg g needs a Claude subscription, so Jake or fsd-qa runs it. Until then, the implementation PR says "goal met except leg g".

Before and after. Today the harness drops Claude Code's rate_limit_event. After: the harness gives each event to onUsage as one window, harness-manager writes it into the row of the run owner through recordHarnessUsage, and a refresh writes the account from probeClaudeAccount through the same writer. The store and the query are from FIX-2141. The Error Reporter's runs are not recorded

A run writes the one window that it got. A look writes who is signed in. One writer does both.

How: claudeCodeAgent gives each rate_limit_event to a new onUsage hook (the twin of onSession). The harness-manager slot feed writes that window into the user-scoped row of the run owner, through recordHarnessUsage. readClaudeUsage maps probeClaudeAccount for the API-key and signed-out states.

Sign off

Open: ship the Claude view with what Claude Code reports, or hold it?

<img src="''https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/0c5f1322ae36e6681d03460fc1b32c98a042b27e/specs/issues/FIX-2142/figures/open-show-what-claude-reports.svg"'' width="940" alt="Open question: ship the Claude view with what Claude Code reports (recommended), or hold it until a source gives a percent for each window. The deciding row: the warning before a pool runs out comes now. The cost: below the warning line, a reset time and no percent" />

  • Plain terms. Claude Code sends its limits to a run only when they change. Below a warning line, it sends the window, "ok", and the reset time, but no percent. Near a limit, it sends the percent. At the limit, it sends "reached" and the reset time. The issue asks for a percent for each window after each run. No permitted source gives that now. The POC read the pinned CLI to find this.
  • Trade-off. Ship: you get the warning that the epic asks for now, and a reset time at other times. Hold: you get nothing for Claude until Anthropic makes a stable usage read. The SDK read that exists now says "do not rely on this", and it calls the endpoint that the brief does not permit.
  • My recommendation: ship it.
  • What would change my mind: Anthropic makes a stable usage read in the Agent SDK, or a headless run is shown to run a status line. Each fills the percent through the same writer.
  • If wrong: a person below the warning line plans with a reset time and no number. It is easy to change later.

The debt: net up, small. It adds one hook type and one slot feed (twins of the session pair), one reader, a one-window write, and a level on the window. It removes nothing, because the event was dropped. If wrong: a second way to write usage, which the one writer is there to stop.

The Error Reporter's Claude runs are not recorded · D1

<img src="''''https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/0c5f1322ae36e6681d03460fc1b32c98a042b27e/specs/issues/FIX-2142/figures/d1-error-reporter-not-recorded.svg"'''' width="940" alt="D1: the Error Reporter's Claude runs are not recorded (chosen), or record them too. The deciding row: the next run reports the same pool. The cost: on a host where only the Error Reporter runs Claude, the row is older" />

The deciding row is what the next run tells us. An event reports the full pool, whatever used it. To record the Error Reporter would add a second flow that writes the collection, and Workforce would then depend on harness-manager. If wrong: a host that runs Claude only for bug reports shows an old Claude row, and the age shows that.

Reasons and the options that lost: DECISIONS.md.

Reviewers · look here

  • Decisions → decided, not asked. A read keeps the windows that runs wrote while the account is the same, and a new account or a no-number status clears them. Can the view show the percent of an old account?
  • Decisions → decided, not asked, "what maps, and the units". Is the scale of utilization (a fraction, multiplied by 100) correct? The POC shows the evidence from the CLI.
  • Spec → what's already here. Is there a second way for a harness to report to its host during a run that the search did not find?

Not here: tokens and cost on an API key, and tokens for each worker (FIX-2145). Cursor and Grok Build (on hold). The store and the query (FIX-2141, #3768).

Spec · Decisions · Linear FIX-2142 · epic FIX-2139 · builds on FIX-2141 (spec, implementation #3768) · merges after human approval and required checks

POC: what a rate_limit_event carries, from the pinned CLI

node specs/issues/FIX-2142/poc/rate-limit-event/inspect.mjs answers this question: when does Claude Code (Agent SDK 0.3.234) put a percent in a rate_limit_event, and in which units? Only on a warning, as a fraction from 0 to 1, with resetsAt in seconds. 8 of 8 claims are found. The control (/bin/ls) finds 0 and fails. The results are in NOTES.md. This code is throwaway.

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction set, not an implementation and not a build plan. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in SPEC.md — is the goal the real need at full size,
    for the people named, or a smaller goal that would let us call this done early? Would the
    named check fail if the goal were not met?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • The debt in SPEC.md → What's already here, and the debt — an existing primitive,
    method or prior design the change overlaps and doesn't name; something it adds that is debt
    and isn't listed; a net verdict the tables don't support.
  • A case a person would hit that the people table misses, when it would invalidate the
    design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • The build plan. Order, file-level changes, the test list, the PR split. The set has no
    plan on purpose: the implementer works it out against the real code.
  • Names, signatures, file paths, and module layout, beyond the few a decision locks.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Edge cases that don't change the approach. The implementer's tests own them.
  • Documentation wording. It is written at implementation, against what shipped.
  • Micro-optimizations and style preferences.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • POC implementation polish. Experiments under the owning spec's poc/ are retained,
    not production code. Read them for directional evidence, not production completeness.
    Their isolation from production/default discovery and absence of secrets or generated
    dependencies are in scope; retention is not permission to weaken repository checks.

One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in
DECISIONS.md → Notes from review
for the implementer to weigh against real code. It will not
be argued with, and it will not be folded into the design prose. Please don't re-raise it: one
mention is enough.

The one exception is the POC. Line-level feedback on it is dropped, not recorded — there
is nothing for an implementer to weigh about code that isn't shipping. Feedback about its
direction is not line-level and is treated like any other above-the-bar finding.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.

https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6


Generated by Claude Code

…t_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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6
@jhoffner jhoffner added the spec label Oct 23, 2026 — with Claude
@jhoffner jhoffner self-assigned this Oct 23, 2026
@vercel

vercel Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 23, 2026 8:53pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 23, 2026 8:53pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 23, 2026 8:53pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 23, 2026

Copy link
Copy Markdown

FIX-2142

Copy link
Copy Markdown
Collaborator Author

@codex review

This is a spec PR (a direction set, not code). Please look hardest at:

  • DECISIONS.md → Decided, not asked: the one-window write and the rule that a read keeps run-written windows while the hashed account is unchanged. Can the Usage view ever show a percent from an earlier account, or a stale window as current?
  • The units: utilization in rate_limit_event read as a fraction and scaled by 100, resetsAt read as epoch seconds. Evidence is in poc/rate-limit-event/NOTES.md.
  • Whether the onUsage feed writes only the run owner's user-scoped row on both paths (a manager run and a session-door talk).

Generated by Claude Code

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-23T20:58:16.899090Z e465664 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (direction review)

Verdict: the approach is right. Ship what Claude Code reports, and write it through the existing single writer, not a second path. I looked for a leaner shape and didn't find one. A twin of onSession is the smallest seam: agent.ts already awaits and tracks onSession in inFlightRef, and translateSdkMessage drops unknown types in its default: [] branch. A generic onEvent hook would be vaguer and leak vendor shapes into core. Two findings below are above the line. The rest is noted for the implementer.

Above the line

1. A run-written window has no account to bind to, so the "keep run windows while the account is the same" rule has a hole.

  • DECISIONS says a run write "leaves account and plan alone", and a read keeps run windows "when the hashed account is the same".
  • A run can write a window onto a row whose account is null (no refresh has happened yet). Then the person signs in as someone else, and the first probe arrives. Stored null versus new account A is not "different", so a rule that compares hashes can't tell.
  • Two outcomes are possible. If null counts as the same account, the previous account's 91 % survives under the new sign-in. That is exactly what leg e and "Can the view show the percent of an old account?" are meant to prevent. If null counts as different, a first refresh after any run wipes the window the run just wrote, which defeats the feature.
  • Suggested fix, in the spec's own vocabulary: have the run-time write stamp the row's account hash when it knows one, or state the null rule explicitly. The slot feed could take the hash from the last probe, which readClaudeUsage already throttles. Add a leg-e variant: run, then switch account, then refresh must clear the window.
  • Whichever rule is chosen, the spec should name it. Right now the decision is silent on it.

2. This spec amends a shape that is still unmerged, so the cheapest move is to change FIX-2141 instead.

Notes for the implementer (no design round needed)

  • Merge rules concentrate in recordHarnessUsage. Four behaviours now live in one function: upsert one window, refuse older observations per window, lift a no-number status to windows, and keep-or-clear on read. That's a lot of merge logic on a function that was a plain replace. Express it as small pure functions (for example mergeRunWindow(row, report) and applyRead(row, reading)) so each has its own unit test and the goal controls map one-to-one onto them.
  • "Never goes backwards per window" needs a clock choice. observedAt comes from the run host, and resetsAt is the window's end. A rolled-over window with an older observedAt but a newer resetsAt is a new window, not a stale event. Compare on resetsAt first, then observedAt.
  • One event names one window. rateLimitType is the binding window only, so the row can hold a seven_day warning from three days ago beside a fresh five_hour ok. The age field covers it. Make sure the view sorts by age or labels each window's own age, not the row's.
  • Scale check, which you asked about. The spec's units claim (utilization as a fraction, resetsAt in seconds) rests on regex matches in minified CLI code. The 0.9 / 0.75 thresholds and the *100 in the status line are solid corroboration. I couldn't cross-check against the SDK's SDKRateLimitInfo typings, because the package isn't installed in this checkout. Before the implementation PR, have the implementer assert the units in a test fixture taken from a real captured event, which leg g will produce. Consider a guard that treats utilization > 1 as a bug and doesn't scale it, because a double-scale would show "9100 %".
  • Second path for harness-to-host reporting. I searched packages/ for HarnessSessionHook and rate_limit_event. The only run-time channel is onSession (claude-code, codex, cursor, harness-manager's feed), so the "twin" claim holds. Codex and Cursor will accept onUsage later without a core change, which is the reason to keep the hook vendor-neutral as specced.
  • Un-fenced feed. Not fencing onUsage while onSession is fenced is the right call, and it's justified in the spec. Add a comment at the feed site so a later reader doesn't "fix" the asymmetry.

Restraint

Nothing to cut. The Error Reporter and kitchen-sink exclusions (D1) are correct. Recording them would add a second writer and a Workforce→harness-manager dependency for little gain.


Generated by Claude Code

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify / direction review (FIX-2142 focus)

Ran parallel read-only passes (code quality, performance, reuse) over the branch diff. FIX-2142’s core shape looks right — one sanctioned source (rate_limit_event), one writer (recordHarnessUsage), twin of the session hook, readClaudeUsage reusing probeClaudeAccount, D1 keeping the Error Reporter off the collection. I would not chase the banned/unstable OAuth or experimental SDK usage APIs, and I would not add a second store or a Workforce → harness-manager write path.

What pushed this review away from an approval is mostly scope and spec surface, not the Claude usage architecture.

PR scope (bigger than the title)

The branch also lands FIX-2141 and FIX-2063 retained specs and a full engine/core resume-replay-without-traces implementation (~changeset + resume-replay-traces-off.test.ts and friends). That’s a lot of unrelated review surface for a PR titled FIX-2142. For spec gates especially, splitting (2142 spec alone, or epic specs without the engine impl in the same PR) would make direction approval and later implementation PRs much easier to reason about. I’m not blocking FIX-2142’s design on the engine work — I just couldn’t treat this as “2142 only.”

Where the approach might be simpler (2142)

Area Take
Hook API HarnessSessionHook is (sessionId, ctx) — harness identity is implicit in the slot. The proposed HarnessUsageHook report adds harness name + observed time on top of fields already on HarnessUsageWindow (checkedAt). Consider (window, ctx) (or a thin patch type) and let the manager feed set harness: "claude-code" — same pattern as session, less parallel nullable semantics in the hook payload.
Merge / origin rules Run vs read merge (origin: "run", keep on same account, lift status, monotonic per window) is correct but reads like a scattered state machine across SPEC + DECISIONS + FIX-2141 leg h. Consider one implementer-facing “merge function” section: inputs (existing, incoming, source), 3–4 invariants, one diagram — reduces over-implementation risk.
usedPercent + level Nullable percent plus parallel level forces every caller/UI path to keep them aligned (Codex: percent always, level null). Consider a documented invariant (usedPercent != null iff level === 'warning') or a Claude-biased discriminated shape at the harness boundary while keeping the flat neutral type for Codex.
POC inspect.mjs with eight minified-regex claims on a pinned binary is useful but brittle on SDK bumps. Consider canonical fixture JSON per status (allowed, allowed_warning, rejected, api-key empty) as the long-lived contract; keep regex smoke optional.
Verification Goal legs a–f + controls are strong. Leg g (live subscription) can’t run in CI — fine as human smoke, but labeling the implementation PR “goal met except g” is a standing exception; consider demoting g to NOTES/manual checklist so the automated goal stays closed.
Docs line in SPEC Four doc areas + four READMEs is a lot for one hook. Consider one “Harness usage” cross-link section and short README pointers (match FIX-2141 brevity).
Types at the Lab boundary When implementing, extend HarnessFeeds in harness-manager and use HarnessUsageHook from core in Shift Manager — avoid a third local HarnessFeeds shape that drifts (already a smell with mcpTools).

Performance (for the implementation PR, not this spec)

Awaiting onUsage on the SDK message loop (like onSession) is the right shutdown contract, but it can add latency if every event writes. Spec already implies sparse events — implementer should guard on actual window change, keep one-window upsert lean, and avoid per-event info logs in the hot loop.

Reuse (implementation should mirror #3768)

Thin layer: translate.ts for rate_limit_event → window, readClaudeUsage modeled on readCodexUsage, inFlightRef + await from claudeCodeAgent, extend toHarnessUsage / Usage view / it-shows-codex-usage-left goal pattern. No new capability or collection.

Open sign-off

Sparse percent + level (recommended: ship) is the right trade vs holding for a full percent — worth an explicit gate answer before implementation merges.


Verdict: FIX-2142’s architecture is the clean path among realistic alternatives; I’m not asking for a different data source or storage model. I’m not approving in this pass because of bundled unrelated diff and the open product gate — happy to approve a FIX-2142-scoped spec once split and the open question is settled.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2142/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2142/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2142/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2142/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2142/SPEC.md Resolved
Comment thread specs/issues/FIX-2142/SPEC.md Resolved
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6

Copy link
Copy Markdown
Collaborator Author

Round 1 (Cursor review) is triaged.

  • Scope: the PR changes only specs/issues/FIX-2142/, 7 files. It does not carry the FIX-2141 or FIX-2063 specs, and it has no engine code. Those are already on main.
  • Recorded: six notes, kept word for word in DECISIONS.md → Notes from review (21ce069) for the implementer.
  • Kept: leg g.

None of them changes the direction.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0c5f1322ae

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread specs/issues/FIX-2142/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2142/SPEC.md Resolved
Comment thread specs/issues/FIX-2142/DECISIONS.md Resolved
… asked

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: not approving yet. Three Codex threads are still open and look real: binding run windows to the account that emitted them (specs/issues/FIX-2142/DECISIONS.md, the account-null adopt rule), a goal leg for session-door ownership since harnessSessionDoor builds its own feeds (specs/issues/FIX-2142/SPEC.md:33), and an account key for token-only probes (specs/issues/FIX-2142/DECISIONS.md:89). Resolving those three in the spec, with CI green, unblocks the label.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: not approving yet. Two Codex P1s are real and open: run windows must be bound to the account that emitted them (DECISIONS.md, the account-null adopt rule), and the goal needs a leg proving harnessSessionDoor (session-door.ts:165-169) feeds usage through the same writer as manager runs. The P2 on an account key for token-only probes (DECISIONS.md:89) also needs a stated rule. Settle those three in the spec and let CI finish green, and this clears.

— FSD Architect

…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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6

Copy link
Copy Markdown
Collaborator Author

@codex review

This is round 2, on head b27a2f4. Please look hardest at:

  • Account binding (DECISIONS → "Windows belong to one account at a time"). Can a run write and a refresh still interleave so that one account's percent shows beside another's?
  • The one-window form inside recordHarnessUsage. It keeps the record clock, and a no-number status is lifted only when the event is newer. Is there an ordering where a stale event undoes api-key or signed-out?

Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

Architect: all three were folded in at b27a2f4, and their threads are answered and resolved.

  • Run windows bound to their account: the report carries accountInfo(). A different hash clears the windows, and leg e covers a switch from A to B.
  • Session door: leg d now has Bob talk through the door, the door's feeds get onUsage, and the collection is installed on the door's capability.
  • Token-only: the stated rule is a null account, as a named limit.

CI is running on that head. A Codex round 2 was requested.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: checked b27a2f4, and all three match what I asked for. Run windows now carry the run's own accountInfo(), and a different account clears the old windows (leg e covers the move from A to B). The session door is in the ownership leg (leg d), with its feeds writing through recordHarnessUsage. Token-only sign-ins are a stated null-account limit. The optional level keeps #3768's Codex rows parsing, so this doesn't fork from FIX-2141's store. No more coherence asks from me. The label follows once CI is green and Codex round 2 comes back clean.

— FSD Architect

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b27a2f441d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread specs/issues/FIX-2142/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2142/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2142/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2142/DECISIONS.md Resolved
… run lifts a no-number status

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6

Copy link
Copy Markdown
Collaborator Author

Architect: Codex round 2 raised four account-ordering findings, and all are folded in at d44806e. An account change is now one whole-record step ordered by a new accountAt. It clears the plan with the windows. A null account no longer adopts; going from null to a named account is a rebind. This reverses your earlier pin, because null can be a real token-only sign-in. A no-number status is lifted only by a run that started after it. Leg f covers the retried event and the old run. This was the second and last design round for this spec (BP-040). Any later notes go to Notes from review.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: checked d44806e. The reversal is fine with me. A null account that adopts is the hole my first pass flagged, and treating null to named as a rebind is the safer rule. The four round-2 fixes match what Codex raised, and leg f covers them.

One small recording gap, not a new design round. accountAt is a new persisted field on FIX-2141's record, and #3768 (still open) defines that record. The spec doesn't list it yet. It isn't in Locks in (DECISIONS.md:33) or in the debt table's Adds or Amends rows (SPEC.md:128-135), and it has no rule for rows #3768 already stores. Please give it the same treatment as level: name it in Locks in and the debt table, and state its default for existing rows. For example, a missing accountAt reads as the epoch, so the first rebind always wins. That keeps this spec from quietly forking #3768's stored shape.

Once that's in and CI plus Codex come back clean, the label follows.

— FSD Architect

…fault for existing rows

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JQoHpLJAdvpaXWZ9EURap6

Copy link
Copy Markdown
Collaborator Author

Architect: recorded in e465664. accountAt is now named in Locks in, in the debt table's Adds, and in a new Amends row for FIX-2141's record. A row #3768 stored without it reads as 0, so the first rebind always wins.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Checked e465664: this matches what I asked. accountAt is named as a shape change in Locks in, Adds and a new Amends row on FIX-2141's record, and rows #3768 stored without it get a default of 0. No coherence concerns left on the spec from my side. CI and Codex still need to clear.

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

@codex review

This is head e465664. Since round 2 the account rules changed: accountAt orders a rebind, going from null to a named account is a rebind, and only a run that started after a no-number status can lift it. Please check them for an ordering that still mixes two accounts. Anything below the direction line goes to Notes from review.


Generated by Claude Code

@jhoffner
jhoffner merged commit d5ecdb7 into main Oct 23, 2026
13 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2142 branch October 23, 2026 20:54

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e4656647dd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Treat named-to-token-only reads as rebinds

When named account A is stored and the user switches to token-only account B, readClaudeUsage produces a windows reading with a null account, so this rule keeps A's binding and permits A's run windows to be retained alongside B's plan. This is the inverse of the resolved null-to-named case and still violates the requirement that a look never show one account's percentage beside another account's state; treat a named-to-null windows reading as a conservative whole-record rebind and cover it in leg e.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed at implementation in #3795. A null account now counts as an identity of its own, so a named-to-token-only reading is a whole-record rebind: it clears the windows and the plan. Covered in harness-usage.spec.ts.


Generated by Claude Code

Comment on lines +85 to +87
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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Advance accountAt on same-account observations

As written, accountAt advances only when a differing account rebinds: with A stored at t0, a B event observed at t1 can stall, an A reading at t2 can reconfirm the current account without advancing the watermark, and the delayed B event then wins because t1 is still newer than t0. That replaces newer A state with stale B state, so the binding watermark must advance on every accepted account-bearing observation, including observations matching the stored account, and leg f should cover this ABA ordering.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed at implementation in #3795. accountAt advances, to the larger of the two times, on every accepted write, so in the A→B(stalled)→A ordering the late B is refused. The ABA case is covered in harness-usage.spec.ts.


Generated by Claude Code

Comment on lines +72 to +75
`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 *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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Preserve runs newer than delayed no-number reads

If an API-key or signed-out probe is observed at t2 but its write stalls, then the user signs in and starts a run at t3 whose event commits at t4, the delayed t2 read can still pass the record CAS because run writes do not advance checkedAt and can clear the valid t4 window. The run-start guard cannot repair this because the qualifying event already committed before the status; order no-number clears against later run starts or window timestamps, and add this reverse commit order to leg f.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed at implementation in #3795. A run write advances accountAt to its observed time, and a no-number reading with checkedAt < accountAt is refused. So a delayed api-key or signed-out look can't clear a newer run's window. Covered in harness-usage.spec.ts.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants