stack/agents/dewey/work/queue-126/DESIGN.md

Row 126 (#1620): design

Dewey, 2026-10-18T22:27Z. Base origin/refactor 70c9131f0 (sage-0940). Brief: docs/plans/2026-10-14_prd-1.2-build.md:480-547, blob 6b473b9304, with the sage-0910 rulings in DESIGN-NOTES.md. REQ-LIMIT-2, REQ-LIMIT-4. Nothing here has been run; there is no slot yet. Line numbers are on 70c9131f0.

Two questions for Sage before the build

Q1. The named set and the other credential variables. sessionEnv (packages/seat/src/session.mjs:101) passes every ENV_ALLOW credential variable into the session, whichever set the organization file names. If the file names CLAUDE_CODE_OAUTH_TOKEN and the bus environment also holds ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN, Claude Code logs in with those first, as far as I know its precedence (ANTHROPIC_AUTH_TOKEN, then ANTHROPIC_API_KEY, then CLAUDE_CODE_OAUTH_TOKEN). The usage records would then name an account that isn't the one in use, which is the false record sage-0910 refused to allow for a missing set. My recommendation is that the launcher refuses, before anything starts, when any SESSION_CREDENTIALS variable outside the named set is set, ANTHROPIC_BASE_URL included. That's a second code beside the missing-set one. The other fix is to pass only the named set in sessionEnv, but that changes what enters the sandbox, and the brief says no sandbox change. Is the refusal right?

Q2. Pi launches. SESSION_CREDENTIALS are Claude Code's login sets (session.mjs:94-98). My reading is that the account applies only to a claude-code launch. A pi launch would log account: null, its records keep NULL, and the credential checks don't run for it, so a daily quota never counts Pi turns. Is that right?

Unless Sage says otherwise, I build with both of these recommendations.

Sage's answers (sage-0942)

1. Q1: refuse account-credential-ambiguous.
   • It applies only when launch.account is set. With no account, the launch behaves exactly as it does today.
   • The message names variable names, never values.
   • ANTHROPIC_BASE_URL is included.
   • The design doesn't rest on Claude Code's credential precedence. The refusal stands whatever that order is, so the precedence remark above is background only.
   • Narrowing sessionEnv stays out of the row.
2. Q2: yes. Only a claude-code launch carries the account. A pi launch logs account: null, its records stay NULL, and the credential checks don't run for it. The cli README says so, and a test asserts the pi-null case.

The other design choices stand. The public/bus.js line needs Mos's decision 123 go before it lands; public.diff goes in this packet. 126 is rebased onto 156's landing before I ask for its slot, and nothing runs before then.

Item 1: the account

Organization file. A new optional launch.account, written by hand (Settings doesn't edit it, so SETTINGS_KEYS doesn't change):

"launch": { "by": "chief", "instances": [...], "models": {...},
  "account": { "name": "jason-max", "credential": "CLAUDE_CODE_OAUTH_TOKEN" } }

• business.mjs:121 gains account in its key list. A new checkAccount in launch.mjs uses rejectUnknownKeys(["name","credential"]). name uses requireId, the same rule as a tokens.keys key. credential must be variable names joined with "+" (sage-0910), checked by /^[A-Z][A-Z0-9_]*(\+[A-Z][A-Z0-9_]*)*$/. A secret can't pass that check.
• The organization-file read checks only the shape. Business can't import SESSION_CREDENTIALS from seat, because seat already imports business (session.mjs:37, sandbox.mjs:40). So the launcher checks that the name is one of the three sets, under the same refusal code.
• With no account, everything stays as it is today: records are NULL and keys are not enforced. Existing files still load, and no migration is needed.
• A tokens.daily.<a> leaf whose <a> isn't launch.account.name makes the read refuse, in the same way as the tokens.instances check at business.mjs:135. Without that check, the quota would match no record and still show as counted, a limit that never applies.

Launcher (packages/cli/src/launcher.mjs check(), after the no-session-credential check at :213):

• account-credential-missing: the file names a set that isn't one of SESSION_CREDENTIALS, or whose variables the bus environment doesn't all hold. The message gives the set name, never a value.
• account-credential-ambiguous (if Q1 is accepted): the environment holds a credential variable outside the named set.
• Both go in the refusal table at packages/cli/README.md:332-347, after no-session-credential.
• account = model.harness === "claude-code" ? b.launch.account?.name ?? null : null (Q2). It goes to the mayLaunch op (:225), to bindLaunch (:337), and to the launch log record (:367), as account.

Bus:

• runtime.mjs:187 passes account through to limits.mayLaunch.
• broker.mjs bindLaunch (:410) takes an optional account, which must be an identifier. The session keeps it. session.launched's body doesn't change, so launch-record-mismatch on a rebind is unaffected.
• broker.mjs:1231 mustStop passes account: s.account ?? null.
• usage.mjs:65 reads account = null from the session. The NULL at :94 becomes a bound ?.
• Corrected in round 4 (sage-0970, sage-0972). This line used to say "The column already exists, so there is no schema change and no migration". That was wrong: 3h made the column account TEXT CHECK (account IS NULL) (3g-3h.sql:10), and the first slot run on 81f26551b went red on that CHECK. Row 126 needs schema 3i, a rebuild of usage_records without the CHECK. See MIGRATION.md and BUILD.md "Round 4".

Item 2: tokens.daily.<account>

• launch.mjs checkTokenLimits gains daily. The keys use requireId. Each leaf is {limit, since, reset, timeZone}, all required:
  • limit and since follow tokenLimit's rules.
  • reset must match /^([01]\d|2[0-3]):[0-5]\d$/.
  • timeZone must match an IANA name shape (/^[A-Za-z][A-Za-z0-9_+-]*(\/[A-Za-z0-9_+-]+)*$/, so +05:00 is out), and new Intl.DateTimeFormat("en-US", {timeZone}) must accept it.
  • Anything else refuses the read.
• daily: 1 is added to the DEPTH tables in bus limits.mjs:32 and business launch-settings.mjs:24. The writer stamps a new daily leaf's since and reset moves it, as for the other kinds.
• token-limit's leaves() doesn't change: it walks named kinds and never reads daily.

Item 3: packages/plugins/limit-check/daily-quota/

The module is self-contained (index.mjs, README.md), interfaceVersion = 2, pure, with the same answer shapes and thrown {code} errors as token-limit. It copies token-limit's small tally helpers instead of importing a sibling check, so each check loads alone. The cost is about 20 duplicated lines.

The day window. A local date D's reset is the earliest instant whose date in timeZone is D and whose wall-clock time there is at or after reset. The window start is today's reset if it is at or before now; otherwise it is yesterday's. That one rule covers both DST cases:

• Skipped (America/Chicago 2026-03-08, reset 02:30): the reset is the first instant after the gap, 03:00 CDT (08:00Z). Temporal's compatible rule would give 03:30 instead, which leaves the old day running for half an hour after the wall clock passed the reset.
• Repeated (2026-11-01, reset 01:30): the reset is the first 01:30, CDT (06:30Z). The second 01:30, CST (07:30Z), doesn't start another window.

The implementation:

• offset(t) comes from Intl.DateTimeFormat formatToParts with hourCycle: "h23".
• A candidate is Date.UTC(D, reset) minus the offset in force a day before and minus the offset a day after.
• If some candidates read back as (D, reset), the earliest wins.
• If none does, reset is in a gap, and the reset is found by binary search between the two candidates for the first instant whose local reading is at or past (D, reset).
• The count runs from max(windowStart, since) over records with account === <a>, summing every kind. Unknown turns add nothing and are counted apart, the same as token-limit.
• mayLaunch and mustStop match on subject.account === <a>. A hit is {path, limit, count, unknownTurns}.
• report gives one counted entry per daily leaf, with since being the leaf's since (core's validEntry requires that), not the window start.

Item 4: refusal and stop

Both use core's existing mayLaunch/mustStop, logged as limit-reached with check: "daily-quota". Nothing in core changes beyond the DEPTH entry and the account passing.

Item 5: the fixed line

Both lines are keyed on path[1] === "daily" and print once when any daily row is present. The text is a draft for review:

Daily quotas count only this stack's own use of the account, not its use anywhere else.

• CLI (packages/cli/src/limits.mjs formatTokens): the line goes after the list.
• webui (packages/webui/src/public/bus.js tokenLimits, :593-603): a <p class="small muted" id="token-limits-daily"> under the table. Its test is packages/webui/tests/limits-browser.test.mjs.
• This is a public/ change, so it needs Mos's decision 123 go before landing. The diff goes in this packet as public.diff.
• serve.mjs doesn't change; it passes tokens through (:78-79).

Files

New:

• packages/plugins/limit-check/daily-quota/index.mjs
• packages/plugins/limit-check/daily-quota/README.md
• packages/plugins/tests/daily-quota.test.mjs

Changed source:

• packages/business/src/launch.mjs
• packages/business/src/business.mjs
• packages/business/src/launch-settings.mjs
• packages/bus/src/limits.mjs
• packages/bus/src/usage.mjs
• packages/bus/src/broker.mjs
• packages/bus/src/runtime.mjs
• packages/cli/src/launcher.mjs
• packages/cli/src/limits.mjs
• packages/webui/src/public/bus.js

Tests and docs: the tests below; packages/plugins/README.md, packages/business/README.md, packages/cli/README.md.

The org-file change for Jason (the packet gives it; I don't edit the file): add "account": {"name": "<name>", "credential": "<set>"} to launch. <set> is whichever of CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN+ANTHROPIC_BASE_URL the bus unit's EnvironmentFile sets. I won't read that file. If Q1 is accepted, the file must set only that set.

No sandbox change. session.mjs, sandbox.mjs and ENV_ALLOW stay untouched.

Paths shared with other rows

• Row 165 (Darkwing, on the slot; paths from agents/darkwing/work/queue-165/BUILD.md):
  • packages/bus/src/broker.mjs
  • packages/bus/src/runtime.mjs
  • packages/webui/src/public/bus.js
  • packages/cli/README.md
  • possibly packages/bus/README.md, if 126 touches it (not planned)
• Row 156 (mine, in review, candidate afea1df3):
  • packages/bus/src/broker.mjs
  • packages/bus/src/runtime.mjs
  • packages/cli/src/launcher.mjs
  • packages/cli/tests/launcher.test.mjs
  • packages/cli/README.md
• Whichever lands first, 126 rebases onto it and reruns the whole gate on the new base (candidate-base-drift rule).

Tests (each run singly)

New, packages/plugins/tests/daily-quota.test.mjs (REQ-LIMIT-2, REQ-LIMIT-4):

• the count: every kind; only this account; from max(start, since); unknown turns kept apart
• the America/Chicago boundary at 05:00: a record at 04:59 CDT is outside today's window, and one at 05:00 is inside
• the spring DST change with a 00:00 reset: the window is 23 h
• the fall DST change with a 00:00 reset: the window is 25 h
• a reset DST skips (02:30 on 03-08), starting at 08:00Z
• a reset DST repeats (01:30 on 11-01): one window, from 06:30Z
• a refusal at the quota (count === limit)
• mustStop once the turn's records reach it
• an allow after the next reset
• bad leaves throw a code (fail closed)

Changed:

• token-limit.test.mjs: token-limit ignores tokens.daily.
• packages/business/tests (the launch schema test file, picked at build time):
  • a bad reset refuses the read
  • a bad timeZone refuses the read (a non-IANA name, an offset, an unknown zone)
  • a bad account refuses the read
  • a daily key that isn't the account refuses the read
• launch-settings tests: a daily leaf gets its since stamped and reset.
• bus:
  • limits.test.mjs: limitLeaves walks daily.
  • limit-checks.test.mjs or limits-runtime.test.mjs: daily-quota loaded through the loader refuses at the quota and allows after the reset.
  • limit-stop.test.mjs: a stop at the end of the turn that crosses it, with account on the subject.
  • usage-broker.test.mjs: records carry the bound account.
• launcher.test.mjs:
  • the launch log names the account
  • account-credential-missing
  • account-credential-ambiguous
  • a pi launch logs account: null
  • mayLaunch gets the account
• cli limits test: the fixed line.
• webui limits-browser.test.mjs: the fixed line.
• Hash pins and path-reading tests: I grep tests for every manifest path and for 64-hex pins on the changed files before in-review.

Mutants (one each, with the test that kills it)

#	Mutant	Killed by
D01	never steps back to yesterday	the boundary test
D02	window computed in UTC	the Chicago boundary test
D03	offset taken once from now	the two DST-change tests
D04	skipped reset uses Temporal-style +gap (03:30)	the skip test
D05	repeated reset takes the later 01:30	the repeat test
D06	ignores since	the count test
D07	ignores account	the count test
D08	>= becomes >	the refusal-at-quota test
D09	token-limit walks daily	the ignores-daily test
D10	schema drops the reset check	the bad reset test
D11	schema drops the timeZone check	the bad zone test
D12	no cross-check of the daily key against the account	the cross-check test
D13	launcher skips the missing-set refusal	the missing-set refusal test
D14	launcher skips the ambiguity refusal	the ambiguity refusal test
D15	launch log omits the account	the log test
D16	usage inserts NULL	the usage-broker test
D17	broker mustStop omits the account	the limit-stop test
D18	runtime drops the account from mayLaunch	the bus refusal test
D19	bus DEPTH lacks daily	the limitLeaves and bus refusal tests
D20	settings DEPTH lacks daily	the stamp test
D21	CLI line removed	the CLI test
D22	webui line removed	the browser test