agl 40.4.0 → 40.5.1

package/ts_authswitch/classes.codexmanaged.ts

@@ -2,6 +2,7 @@ import * as plugins from './plugins.js';
 import { authSwitchRelease } from './packageidentity.js';
 import type { AuthSwitchAuthorityBroker } from './classes.authoritybroker.js';
 import { requireVerifiedCodexServer, verifyManagedCodexContract, type IManagedCodexContract } from './codexcontract.js';
+import { psLstartInstant } from './classes.harnessprocesses.js';
 
 export interface IAuthSwitchManagedCodexOptions {
   /** Private runtime root; only the disposable control socket lives here. */
@@ -71,6 +72,21 @@ const claimsManagedCodexSocket = (argv: readonly Buffer[], socketPath: string):
   return false;
 };
 
+/**
+ * Rows of `ps -o pid=,lstart=` run with `TZ=UTC0`: the start is read by the shared `psLstartInstant`, null when it
+ * cannot be read (a claimant with a null start fails the inspection).
+ */
+export const managedCodexProcessRows = (output: string): Array<{ pid: number; startedAt: string | null }> => {
+  const rows: Array<{ pid: number; startedAt: string | null }> = [];
+  for (const line of output.split('\n')) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length !== 6) continue;
+    const pid = Number(parts[0]);
+    if (Number.isSafeInteger(pid) && pid > 0) rows.push({ pid, startedAt: psLstartInstant(parts.slice(1, 6)) });
+  }
+  return rows;
+};
+
 /** Same-user Linux process inspection for a bounded socket set, using exact /proc argv boundaries. */
 export const observeManagedCodexProcesses = async (
   socketPaths: readonly string[],
@@ -85,30 +101,28 @@ export const observeManagedCodexProcesses = async (
   }
   const uid = process.getuid?.();
   if (uid === undefined) throw new Error('Managed Codex process owner inspection is unavailable.');
+  // ps prints lstart in its TZ; under UTC0 the shared reader takes it as UTC (never Date.parse, which reads local time).
   const output = await new Promise<string>((resolve, reject) => {
     plugins.childProcess.execFile('ps', ['-ww', '-u', String(uid), '-o', 'pid=,lstart='],
-      { timeout: 5_000, maxBuffer: 8 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C' } },
+      { timeout: 5_000, maxBuffer: 8 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C', TZ: 'UTC0' } },
       (error, stdout) => error ? reject(new Error('Managed Codex process inspection failed.')) : resolve(stdout));
   });
-  const processes: Array<{ pid: number; startedAt: string; argv: Buffer[] }> = [];
-  for (const line of output.split('\n')) {
-    const parts = line.trim().split(/\s+/);
-    if (parts.length !== 6) continue;
-    const pid = Number(parts[0]);
-    const date = Date.parse(parts.slice(1, 6).join(' '));
-    if (Number.isSafeInteger(pid) && pid > 0 && Number.isFinite(date)) {
-      const argv = await linuxArgv(pid);
-      if (argv) processes.push({ pid, startedAt: new Date(date).toISOString(), argv });
-    }
+  const processes: Array<{ pid: number; startedAt: string | null; argv: Buffer[] }> = [];
+  for (const row of managedCodexProcessRows(output)) {
+    const argv = await linuxArgv(row.pid);
+    if (argv) processes.push({ ...row, argv });
   }
   const result = new Map<string, TManagedCodexProcessObservation>();
   for (const socketPath of unique) {
     const matches = processes.filter(process => claimsManagedCodexSocket(process.argv, socketPath));
-    result.set(socketPath, matches.length === 0
-      ? { state: 'absent' }
-      : matches.length === 1
-        ? { state: 'observed', pid: matches[0].pid, startedAt: matches[0].startedAt }
-        : { state: 'multiple_claimants' });
+    if (matches.length !== 1) {
+      result.set(socketPath, matches.length === 0 ? { state: 'absent' } : { state: 'multiple_claimants' });
+      continue;
+    }
+    const [claimant] = matches;
+    // A claimant whose start cannot be read has no identity to compare: the inspection fails, never reads as absent.
+    if (claimant.startedAt === null) throw new Error('Managed Codex process inspection failed.');
+    result.set(socketPath, { state: 'observed', pid: claimant.pid, startedAt: claimant.startedAt });
   }
   return result;
 };

package/ts_authswitch/classes.harnessprocesses.ts

@@ -41,12 +41,31 @@ const executablePatterns: Record<THarnessBinary, RegExp[]> = {
 const MAX_COMMAND_LINE = 200;
 const POSIX_FIELDS = 'pid=,ppid=,uid=,lstart=,comm=,args=';
 
-/** A bounded read of the current user's process table. Never a pattern-based kill list. */
-const enumeratePosix = (): IEnumeratedProcess[] => {
-  const uid = process.getuid!();
-  const output = plugins.childProcess.execFileSync('ps', ['-u', String(uid), '-o', POSIX_FIELDS], {
-    encoding: 'utf8', timeout: 5000, maxBuffer: 4 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C' }, windowsHide: true,
-  });
+const LSTART_WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const LSTART_MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/**
+ * The instant of `ps -o lstart` under `LC_ALL=C` and `TZ=UTC0`: the five tokens `weekday month day hh:mm:ss year`,
+ * read as UTC with `Date.UTC`. Never `Date.parse`, which reads them in local time: in the repeated hour of a DST
+ * fall-back that dates a process an hour early. Anything that is not exactly that shape, or names no real day, is null.
+ */
+export const psLstartInstant = (tokens: readonly string[]): string | null => {
+  if (tokens.length !== 5) return null;
+  const [weekdayToken, monthToken, dayToken, timeToken, yearToken] = tokens;
+  const weekday = LSTART_WEEKDAYS.indexOf(weekdayToken);
+  const month = LSTART_MONTHS.indexOf(monthToken);
+  const time = /^(\d{2}):(\d{2}):(\d{2})$/.exec(timeToken);
+  if (weekday < 0 || month < 0 || !time || !/^\d{1,2}$/.test(dayToken) || !/^\d{4}$/.test(yearToken)) return null;
+  const [day, year, hours, minutes, seconds] = [dayToken, yearToken, time[1], time[2], time[3]].map(Number);
+  if (hours > 23 || minutes > 59 || seconds > 59) return null;
+  const instant = new Date(Date.UTC(year, month, day, hours, minutes, seconds));
+  if (instant.getUTCFullYear() !== year || instant.getUTCMonth() !== month || instant.getUTCDate() !== day
+    || instant.getUTCDay() !== weekday) return null;
+  return instant.toISOString();
+};
+
+/** Rows of `ps -o pid=,ppid=,uid=,lstart=,comm=,args=` run with `TZ=UTC0`, for the process owner `uid` only. */
+export const parsePosixProcessTable = (output: string, uid: number): IEnumeratedProcess[] => {
   const processes: IEnumeratedProcess[] = [];
   for (const line of output.split('\n')) {
     // pid ppid uid, then the five fixed tokens of lstart, then comm and the full argument vector.
@@ -54,17 +73,29 @@ const enumeratePosix = (): IEnumeratedProcess[] => {
     if (parts.length < 9) continue;
     const [pid, parentPid, owner] = parts.slice(0, 3).map(Number);
     if (!Number.isInteger(pid) || pid <= 0 || owner !== uid) continue;
-    const started = Date.parse(parts.slice(3, 8).join(' '));
     const args = parts.slice(9);
     processes.push({
       pid, parentPid: Number.isInteger(parentPid) ? parentPid : null, command: parts[8],
       executable: args[0] ?? parts[8], commandLine: (args.length ? args.join(' ') : parts[8]).slice(0, MAX_COMMAND_LINE),
-      startedAt: Number.isFinite(started) ? new Date(started).toISOString() : null,
+      startedAt: psLstartInstant(parts.slice(3, 8)),
     });
   }
   return processes;
 };
 
+/**
+ * A bounded read of the current user's process table. Never a pattern-based kill list. `ps` prints lstart in its
+ * `TZ`, so it runs with `TZ=UTC0` and the start is read as UTC (`psLstartInstant`).
+ */
+const enumeratePosix = (): IEnumeratedProcess[] => {
+  const uid = process.getuid!();
+  const output = plugins.childProcess.execFileSync('ps', ['-u', String(uid), '-o', POSIX_FIELDS], {
+    encoding: 'utf8', timeout: 5000, maxBuffer: 4 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C', TZ: 'UTC0' },
+    windowsHide: true,
+  });
+  return parsePosixProcessTable(output, uid);
+};
+
 /** Windows reports an image name and a pid, with no owner, parent or start time in this view. */
 const enumerateWindows = (): IEnumeratedProcess[] => {
   const output = plugins.childProcess.execFileSync('tasklist', ['/FO', 'CSV', '/NH'], {

package/ts_authswitch/native-contracts.md

@@ -312,10 +312,11 @@ custody item, so it is on `CLAUDE_NATIVE_CUSTODY_RELEASES`:
 - Logout `performLogout` (@34545518) clears two account caches more than 2.1.282's, `metricsStatusCache` and
   `metricsStatusCacheByPrincipal`. Both are now on `CLAUDE_NATIVE_ACCOUNT_CACHES`.
 
-2.1.288 is not on `CLAUDE_NATIVE_VERIFIED_RELEASES`. The newest entry of that list is the fleet's floor
-(`claudeCodeVerifiedRelease`), and the fleet items of the check need Claude Code run. The fleet never runs the SDK's
-binary, and the usage read already takes 2.1.288 as 2.1.282. The custody list names releases, so a natively installed
-2.1.288 is admitted like the SDK's build; only the SDK's `linux-x64` binary was read. The SDK's binary is named through
+Its lock table, live pickup and selector are the usage read's items too, so 2.1.288 is on
+`CLAUDE_NATIVE_VERIFIED_RELEASES` (AGL-686) for the usage read only. The fleet never runs the SDK's binary, so its fleet
+items were never confirmed: 2.1.288 is never the fleet's floor (`claudeCodeFleetFloor`) or the verified release
+(`claudeCodeVerifiedRelease`). Both lists name releases, so a natively installed 2.1.288 is admitted like the SDK's
+build; only the SDK's `linux-x64` binary was read. The SDK's binary is named through
 `CLAUDE_NATIVE_AGENT_SDK_RELEASES` (SDK 0.3.288 bundles 2.1.288), see process detection below.
 
 Claude Code 2.1.306 (AGL-686, read 2026-10-22). Linux ELF bundle `~/.local/share/claude/versions/2.1.306`, BuildID
@@ -407,6 +408,11 @@ process to a home by both directories (`claudeNativeHomeRelation`):
   as `override`.
 - A process whose home or store cannot be resolved is refused as uninspectable (`running_session` in the usage read).
 - The container-home and sign-in checks count a process whose store is their home.
+- The usage read requires the accounts service's own environment to keep its store on the home as well
+  (`assertNativeHome` applies `claudeNativeCredentialStoreDirectory` to it): a store elsewhere is refused as `override`.
+- A sign-in pins the variable to its home, in the command it prints and when `account add claude` starts Claude Code.
+  Inherited, the variable would send the new login to another store, over the login that store holds, while the sign-in
+  home never gets a `.credentials.json` and the sign-in expires.
 
 Which credential a 2.1.282 process uses (`jc` @16151504, `Cc` @16150518): `ANTHROPIC_AUTH_TOKEN` and `apiKeyHelper`
 outrank the stored claude.ai login and disable it for requests, though the stored login is still read (`dF`) and side
@@ -423,10 +429,12 @@ Until 38.0.0 a switch of an adopted home proved an installed release above the 2
 switch: from 38.0.0 on authswitch never moves a login into Claude Code's own home, and reads an adopted home's login for
 usage only while no session of such a release runs there.
 
-Newer releases (owner ruling 2026-10-22, AGL-685): the usage read takes a release at or after the newest verified one
-(2.1.282) as that one (`claudeNativeReleaseReadsAsVerified`), installed or running, and a remote agent's hashed build
-(`2.1.295-8b2928c330c4`) is ordered by its release there. An unlisted release between the floor and the newest verified
-one stays refused, since its selector was never read. Custody does not follow: it matches whole build names against
+Newer releases (owner ruling 2026-10-22, AGL-685): the usage read takes a listed release and every release from
+2.1.282 on as verified (`claudeNativeReleaseReadsAsVerified`, line `CLAUDE_NATIVE_READ_AS_VERIFIED_FROM`, held equal to
+the fleet's floor by a test), installed or running, and a remote agent's hashed build (`2.1.295-8b2928c330c4`) is
+ordered by its release there. The line does not move when a newer release is verified (arbiter ruling 2026-10-23,
+AGL-686). An unlisted release below it (2.1.274-2.1.281) stays refused, since its selector was never read. Custody does
+not follow: it matches whole build names against
 `CLAUDE_NATIVE_CUSTODY_RELEASES`, so a newer release and every hashed build stay refused until their custody contract is
 read, and the refusal names each process by pid, start and build. AGL mentions each newer release it meets once to the
 driver, who files the compatibility check below.
@@ -438,7 +446,7 @@ remote agent from `~/.claude/remote/ccd-cli/<version>` (since 2.1.295 a build na
 number as the command name while argv[0] carries the identity -- and a forked helper can
 carry the same `comm` while running something else entirely (`ugrep`). `HarnessProcesses`
 therefore matches argv[0] and those install paths (`ps -u <uid> -o pid=,ppid=,uid=,lstart=,comm=,args=`
-under `LC_ALL=C`, filtered on the uid column). It deliberately never matches the rest of the
+under `LC_ALL=C` and `TZ=UTC0`, filtered on the uid column; lstart is read as UTC with `Date.UTC`). It deliberately never matches the rest of the
 command line, which would count an unrelated process that merely mentions `claude`. The
 consequence is a known blind spot: an instance started through a wrapper that execs
 `node <path>/cli.js` has argv[0] `node`, so it is not listed. Listing signals nothing; the
@@ -504,17 +512,20 @@ can invalidate the grant. Requests to Claude account endpoints report an HTTP 42
 
 ## Claude Code compatibility check
 
-AGL verified Claude Code 2.1.282 (`claudeCodeVerifiedRelease` in `ts/functions.claudecoderelease.ts`, the newest of
-`CLAUDE_NATIVE_VERIFIED_RELEASES`). It runs a newer release optimistically -- fleet workers, Claude Code sessions in the
-session feed and the usage read -- refuses an older one in the fleet, and keeps custody (handing Claude Code's own
+AGL verified Claude Code 2.1.306 (`claudeCodeVerifiedRelease` in `ts/functions.claudecoderelease.ts`, on
+`CLAUDE_NATIVE_VERIFIED_RELEASES`; 2.1.282 before it). Its fleet's floor is a separate constant, `claudeCodeFleetFloor`
+(2.1.282): the oldest release whose fleet output the tests still pin. It rises only when the adapter stops handling an
+older release's output, never because a newer release was verified (arbiter ruling 2026-10-23, AGL-686). AGL runs a
+release newer than the verified one optimistically -- fleet workers, Claude Code sessions in the session feed and the
+usage read -- refuses one older than the floor in the fleet, and keeps custody (handing Claude Code's own
 sign-in to the accounts service) refused on it until its custody items were read (`CLAUDE_NATIVE_CUSTODY_RELEASES`, which
 may take a release before its fleet items are confirmed, as it took 2.1.306). The first time the controller's fleet or configuration probe meets a
 newer release it records it (`agl_harness_releases`) and publishes one `harness.release.discovered` fleet event to every
 owner's watch and the built-in Driver, so the driver files a compatibility check for that release on the board. The
 check works through this list against the release's own bundle (`~/.local/share/claude/versions/<release>`) and
-disposable homes, never a credential file. A release that keeps every item moves the verified releases (the controller
-constant, `CLAUDE_NATIVE_VERIFIED_RELEASES`, and `CLAUDE_NATIVE_CUSTODY_RELEASES` for the custody items), with its BuildID
-and SHA-256 recorded here and the tests that pin 2.1.282 output moved to it.
+disposable homes, never a credential file. A release that keeps every item moves the verified release (the controller
+constant `claudeCodeVerifiedRelease`, `CLAUDE_NATIVE_VERIFIED_RELEASES`, and `CLAUDE_NATIVE_CUSTODY_RELEASES` for the
+custody items), with its BuildID and SHA-256 recorded here and its output added to the tests beside the floor's.
 
 An Agent SDK update gets the same check against the binary its platform package ships, the custody and usage-read items
 at least, since AGL's own chats run that binary on the controller's home. Record the SDK version and the release it
@@ -542,9 +553,9 @@ are marked:
 - Relay stream-json: `system`/`init` and `result` (`subtype`, `is_error`, `permission_denials`, `api_error_status`,
   `terminal_reason`, `errors`).
 - Transcript growth against the 4 MiB window: the fleet reads a transcript's last 4 MiB and refuses an incremental read
-  of more as an observation gap. 2.1.306 writes `api-request`, `api-request-shape` and `api-request-blob` records, about
-  41 % of the bytes after its first record in a small sample on 2026-10-22; measure the share again and check that the
-  Agent SDK's chain reader (`getSessionMessages`, used for history) skips record types it does not know.
+  of more as an observation gap. Measure what the release adds and how much time and how many turns the window still
+  covers, and check that the Agent SDK's chain reader (`getSessionMessages`, used for history) skips record types it does
+  not know.
 
 The managed policy hook (`ts/configuration/policyhook/claude.ts`): the PreToolUse payload's `tool_name` (`Bash`,
 `mcp__agl__job_start`), `tool_input.command` and `tool_input.argv`, and exit code 2 as a denial. A renamed `tool_name`,
@@ -587,9 +598,59 @@ offsets, as for 2.1.280-2.1.282 above:
   "diskless" session (`ee()`, a launch option a hosting server sets; off on the host). A new mode like it must not let a
   process that has a disk refresh without the lock.
 
-2.1.306's bundle (AGL-686): its custody and usage-read items were read on 2026-10-22, and its fleet items wait for
-transcripts that 2.1.306 processes write under AGL 40.4.0. It is on `CLAUDE_NATIVE_CUSTODY_RELEASES`, not yet on
-`CLAUDE_NATIVE_VERIFIED_RELEASES` or the fleet's floor.
+2.1.306's fleet items (AGL-686, 2026-10-23). Sources: its bundle's `strings -n 6` dump (offsets as in its entry above),
+compared with 2.1.282's after renaming minified names; 56 transcripts 2.1.306 processes wrote on this host (6 sessions,
+50 subagents, 18,732 records with `version` 2.1.306); and the live controller on AGL 40.4.0, which watched the fleet's two
+2.1.306 driver workers from 23:35 UTC on 2026-10-22. AGL's own parsers (`parseFleetClaudeTranscript`,
+`fleetClaudeAssistantTexts`, `fleetClaudeCredentialFailures`, `fleetClaudePermissionMode`) and the history projection
+read every one of those records, and each file's 4 MiB window, without an error. Every item holds, so 2.1.306 is the
+verified release and on `CLAUDE_NATIVE_VERIFIED_RELEASES`; the fleet's floor stays 2.1.282. Items marked bundle only
+did not occur on 2.1.306 after the upgrade; the first natural occurrence gets a confirming line here, and one that
+contradicts the bundle read gets a fix ticket:
+- Inventory. `printAgentsJson` (@56964267) is 2.1.282's after renaming. A status goes through `p` (@56963968): `idle`,
+  `waiting`, anything else `busy`, so the session registry's `shell` reads `busy`. A pid and a status come from the same
+  live session entry, and a job's kind is `background`. The controller read the inventory at every poll after the
+  upgrade and published no Claude `worker.observation.failed`.
+- `--bg` and wake output, all 2.1.282's:
+  - `backgrounded · <id>[ · <name>]` (`lqe` @31980520);
+  - the wake note (@31978597), printed only when the job saved options;
+  - the copy note (`xn` @31973173, case `own-options`);
+  - the message saved for the job's next start (@31977716);
+  - `--mcp-config <configs...>` (@35482194), still variadic;
+  - the trust key `hasTrustDialogAccepted`.
+
+  New: `Couldn't tell whether <flag> is a flag or text here, so nothing was started` (@31974605, exit 1) when no `--bg`
+  flag can be stripped. The fleet passes `--bg` first, and exit 1 fails visibly. A wake's text is recorded as
+  `origin.kind` `human` with string content (three wakes on 2026-10-22). The output itself is bundle only: the fleet
+  started, woke and relayed nothing on 2.1.306 after the upgrade.
+- Held and delivery notices (bundle only). `Held peer message — from …` (@47687878) is unchanged. It is still appended to the session's
+  transcript as a `system`/`informational` record with `level: "warning"`, built like the release's other transcript
+  notices, and the loggable check `Mw` (@25426540) keeps a system record unless it says `persist:false`. Delivery notices (@47169054) still start
+  with `[Cross-session delivery notice]`. The hold now reads `… was held by that session. NOT delivered: …` instead of
+  `… held for the recipient user's approval …`. No 2.1.306 session held a message here, so neither text is in a 2.1.306
+  transcript yet.
+- SendMessage receipts. A peer send by name answers `{success: true, msg_id, message}` (6 in 2.1.306 transcripts) or
+  `{success: false, message}` (1). The caveat (@50880854) now reads `; in that session's inbox, not yet read by its
+  Claude — a [Cross-session delivery notice] follows if …`. It sits in the tool result, which the relay check skips. The
+  tool's input gained `recipient_kind`; `to` and `message` are unchanged.
+- API error records: `isApiErrorMessage: true` with `error` (9 records, `rate_limit`), built at @29824350. The error list
+  (@17985651) is 2.1.282's, `authentication_failed` and `oauth_org_not_allowed` included. `apiErrorStatus` and
+  `apiErrorIsTransient` are new beside them.
+- `system`/`turn_duration` records: 342 written. The 15 the two driver workers wrote after the upgrade matched the
+  controller's 15 `worker.turn.ended` events one for one.
+- `permission-mode` records (no `version` field; 435, one per turn as before), and `user.origin.kind` `human` and `peer`
+  with `origin.body` (4 peer messages). Copies keeping their uuids are bundle only: no copy was seen, and the copy path
+  of the dispatcher is 2.1.282's.
+- Relay stream-json (bundle only): `system`/`init` (@33617187), and the `result` fields `permission_denials`, `api_error_status`,
+  `terminal_reason`, `errors` and `is_api_error_message` are in the bundle. No relay ran on 2.1.306.
+- Transcript growth. `api-request`, `api-request-shape` and `api-request-blob` records are 27 % of the bytes written after
+  each file's first 2.1.306 record (26 of 95 MB, three quarters of it blobs), and 26 % of the two driver workers' 4 MiB
+  windows.
+  - Those windows still cover 4.5 h and 105 turns, and 3.7 h and 61 turns. Without the new records they would cover 4.9 h
+    and 4.2 h; two 2.1.282 drivers' windows covered 2.4 h and 7.8 h.
+  - The most written within 2 s was 0.7 MB, far from the 4 MiB gap, and every window held a `permission-mode` record.
+  - The Agent SDK's chain reader (`jM` in SDK 0.3.288) keeps only `user`, `assistant`, `progress`, `system` and
+    `attachment` records with a `uuid`, so it skips the new records.
 
 ## Managed Codex app-server contract (Codex 0.157.0, 2026-09-25)
 

package/ts_authswitch/readme.md

@@ -8,6 +8,6 @@ Keep the authority in its own process. The controller never owns refresh grants.
 
 Native credential files belong to their tools: the authority writes one only through a verified, journaled handoff, and never destroys or overwrites a native credential it has not first proven it can restore. Every operation that stops the owned Codex app-server restarts it on both success and failure. Structured authority state uses the existing NoSQLDB models and versioned migrations.
 
-Tests isolate all harness homes and use injected provider/process adapters. Never run account-mutating tests against the developer's own installations. Module import, CLI help/version and the browser leaves (`authority-contract.ts`, `authority-usagewindows.ts`, `authority-usagelimit.ts`, `authority-usageheaders.ts`, `authority-usagetokens.ts`, `authority-placement.ts`, `authority-subscription.ts`, `preuse-text.ts`) must not initialize a controller or touch credentials. `authority-subscription.ts` holds the one map of what Claude's `subscription_status` values mean (empty until a value is confirmed) and the words of a payment problem and a re-check, which the command line and the Accounts screen share; `classes.authorityusage.ts` holds a payment problem on the usage record (`reportPaymentProblem`) and clears it on a read that finds a changed subscription or a healthy re-check (`recheck`); a problem held without a subscription takes the one the next healthy read finds, and that read clears nothing. `authority-placement.ts` is the one rule of an account's lifecycle against its `lapsesAt` and of the placement score the proxy places new sessions by. `authority-usageheaders.ts` reads the usage a provider's answer headers state and joins it to the authority's own reading; the authority holds such observations in memory and answers every usage read with them (`authswitch.authority.usage.observe`). `classes.authorityusage.ts` owns the one usage-read schedule: each account is read from the provider every 10 minutes on the authority's timer and at once after an inference 429, a failed read keeps the held reading `stale` and waits for `retry-after` or the next slot, and no question waits for a read or an unseal. `authority-usagetokens.ts` (browser-safe) weighs the tokens the proxy reports by Anthropic's published prices, and `classes.authorityusageestimate.ts` carries each Claude window forward between reads with a ratio learned per account and window, in memory only. `authority-usagelimit.ts` is the one rule of whether an account's usage, against its `maxUsagePercent`, lets it take work; the proxy, Flex, the CLI and the Accounts screen all call it rather than restating it.
+Tests isolate all harness homes and use injected provider/process adapters. Never run account-mutating tests against the developer's own installations. Module import, CLI help/version and the browser leaves (`authority-contract.ts`, `authority-spend.ts`, `authority-usagewindows.ts`, `authority-usagelimit.ts`, `authority-usageheaders.ts`, `authority-usagetokens.ts`, `authority-placement.ts`, `authority-subscription.ts`, `preuse-text.ts`) must not initialize a controller or touch credentials. `authority-subscription.ts` holds the one map of what Claude's `subscription_status` values mean (empty until a value is confirmed) and the words of a payment problem and a re-check, which the command line and the Accounts screen share; `classes.authorityusage.ts` holds a payment problem on the usage record (`reportPaymentProblem`) and clears it on a read that finds a changed subscription or a healthy re-check (`recheck`); a problem held without a subscription takes the one the next healthy read finds, and that read clears nothing. `authority-placement.ts` is the one rule of an account's lifecycle against its `lapsesAt` and of the placement score the proxy places new sessions by. `authority-usageheaders.ts` reads the usage a provider's answer headers state and joins it to the authority's own reading; the authority holds such observations in memory and answers every usage read with them (`authswitch.authority.usage.observe`). `classes.authorityusage.ts` owns the one usage-read schedule: each account is read from the provider every 10 minutes on the authority's timer and at once after an inference 429, a failed read keeps the held reading `stale` and waits for `retry-after` or the next slot, and no question waits for a read or an unseal. `authority-usagetokens.ts` (browser-safe) weighs the tokens the proxy reports by Anthropic's published prices, and `classes.authorityusageestimate.ts` carries each Claude window forward between reads with a ratio learned per account and window, in memory only. `authority-usagelimit.ts` is the one rule of whether an account's usage, against its `maxUsagePercent`, lets it take work -- a switch on the reading's `kind`, where an API key's `spend` reading is judged by its spend limit alone; the proxy, Flex, the CLI and the Accounts screen all call it rather than restating it. `authority-spend.ts` (imports nothing) is the calendar month in UTC a key's spend counts in (`authSwitchSpendPeriod`, the one calendar function), the spend reading, the spend limit rule and dollar amounts. `authority-apikeys.ts` holds the key verifier (`authSwitchApiKeyVerifier`, a read of the provider's model list) and the guard against a key of the other provider; `AuthSwitchAuthorityDatabase.recordSpend` / `readSpend` keep the monthly ledger (`authswitch_authority_spend_entries`, `authswitch_authority_spend_periods`), and `classes.authorityusage.ts` answers a key's usage from it and holds a key's payment problem, by cause, on the key's usage record. A sealed key is `{ kind: 'anthropicApiKey' | 'openaiApiKey', apiKey }`, one kind per provider; never add a kind a reader must keep forever.
 
 Imported from authswitch 11.4.1, commit `c3fed26`; future fixes and releases belong to AGL. OpenAI adaptations retain their headers and the notices in the repository's `third-party-notices.md` and `openai-codex-license.txt`.

package/ts_authswitch/testsupport.ts

@@ -1,4 +1,5 @@
 import * as plugins from './plugins.js';
+import { authSwitchApiKeyVerifier } from './authority-apikeys.js';
 import { AuthSwitchAuthorityDaemon, type IAuthSwitchAuthorityDaemonOptions } from './classes.authoritydaemon.js';
 import { AuthSwitchOpenAiProvider } from './classes.openaiprovider.js';
 import { ClaudeAccountStatus } from './classes.claudestatus.js';
@@ -107,9 +108,9 @@ export interface IAuthSwitchFixtureUsage {
 }
 
 /**
- * Anthropic's profile, usage and token endpoints for exactly the fixture tokens it knows, its model list for the
- * fixture API keys it issued, and ChatGPT's `wham/usage` for the fixture ChatGPT logins; every other request fails with
- * an error, so nothing a test starts reaches a real provider.
+ * Anthropic's profile, usage and token endpoints for exactly the fixture tokens it knows, Anthropic's and OpenAI's
+ * model lists for the fixture API keys it issued, and ChatGPT's `wham/usage` for the fixture ChatGPT logins; every
+ * other request fails with an error, so nothing a test starts reaches a real provider.
  */
 export class AuthSwitchFakeClaudeProvider {
   /** Access token -> the account name it belongs to. */
@@ -138,6 +139,27 @@ export class AuthSwitchFakeClaudeProvider {
     return apiKey;
   }
 
+  /**
+   * The OpenAI API keys OpenAI accepts -> the account name each was issued for, and whether it may read the model list
+   * (a restricted key without that permission may not); delete one to revoke it.
+   */
+  public readonly openAiApiKeys = new Map<string, { name: string; modelRead: boolean }>();
+  /** While true, OpenAI's model list answers 503. */
+  public openAiModelsDown = false;
+  public openAiModelListCalls = 0;
+
+  /**
+   * Issues `name`'s OpenAI API key, which OpenAI accepts from then on, and answers it: `sk-proj-fixture-<name>`, a
+   * project key's prefix, so the authority tells it from an Anthropic key as it would a real one. `modelRead: false`
+   * issues a restricted key that may not read the model list.
+   */
+  public issueOpenAiApiKey(name: string, options: { modelRead?: boolean } = {}): string {
+    assertFixtureName(name);
+    const apiKey = `sk-proj-fixture-${name}`;
+    this.openAiApiKeys.set(apiKey, { name, modelRead: options.modelRead ?? true });
+    return apiKey;
+  }
+
   /** Accepts the access token of `name`'s login at `generation`, and its refresh token for the next generation. */
   public know(name: string, generation: number): void {
     assertFixtureName(name);
@@ -168,6 +190,33 @@ export class AuthSwitchFakeClaudeProvider {
       }
       return Response.json({ data: [], has_more: false });
     }
+    if (url === 'https://api.openai.com/v1/models') {
+      // The model list of an OpenAI API key, which the authority reads to learn whether OpenAI accepts a key.
+      this.openAiModelListCalls++;
+      if (this.openAiModelsDown) {
+        return Response.json({ error: { message: 'overloaded', type: 'server_error' } }, { status: 503 });
+      }
+      const headers = new Headers(init?.headers);
+      // Only the request the authority's verifier sends is a fixture request: anything else is answered as malformed.
+      if ((init?.method ?? 'GET') !== 'GET' || init?.redirect !== 'error' || headers.has('x-api-key')
+        || headers.has('openai-organization') || headers.has('openai-project')) {
+        return Response.json({ error: { message: 'not a fixture request', type: 'invalid_request_error' } },
+          { status: 400 });
+      }
+      const presented = (headers.get('authorization') ?? '').replace(/^Bearer /, '');
+      const issued = this.openAiApiKeys.get(presented);
+      if (!issued) {
+        // OpenAI quotes the key it refused (masked); the fake quotes it whole, so a test proves nothing repeats it.
+        return Response.json({ error: { message: `Incorrect API key provided: ${presented}`,
+          type: 'invalid_request_error', param: null, code: 'invalid_api_key' } }, { status: 401 });
+      }
+      if (!issued.modelRead) {
+        return Response.json({ error: { message: 'You have insufficient permissions for this operation. Missing scopes:'
+          + ' api.model.read.', type: 'invalid_request_error', param: null, code: null } }, { status: 403 });
+      }
+      return Response.json({ object: 'list', data: [{ id: 'gpt-fixture', object: 'model', created: 1_700_000_000,
+        owned_by: 'openai' }] });
+    }
     if (url === 'https://api.anthropic.com/api/oauth/usage') {
       const token = (new Headers(init?.headers).get('Authorization') ?? '').replace(/^Bearer /, '');
       const name = this.accessTokens.get(token);
@@ -395,7 +444,7 @@ export const authSwitchSeedClaudeAccount = async (daemon: AuthSwitchAuthorityDae
   } else {
     const account: IStoredAuthorityAccount = { id: accountId, providerId: 'anthropic', issuer: 'anthropic',
       subject: identity.accountUuid, workspaceId: identity.organizationUuid, label: name,
-      email: identity.emailAddress, plan: 'max', primaryGrantId: loginId, maxUsagePercent: null, reserveLiftUntil: null, lapsesAt: null, removed: false, revision: 1,
+      email: identity.emailAddress, plan: 'max', primaryGrantId: loginId, maxUsagePercent: null, reserveLiftUntil: null, lapsesAt: null, spendLimitMicroUsd: null, keyHint: null, removed: false, revision: 1,
       statusObservedAt: now, updateId };
     await database.changeAccountAndGrant(updateId, accountId, loginId, () => ({ account, grant }));
   }
@@ -418,8 +467,8 @@ export const authSwitchSeedClaudeAccount = async (daemon: AuthSwitchAuthorityDae
  * It serves the management and runtime sockets exactly as the installed authority does, with the Claude native
  * authority on a fixture host home, container homes confined to `homesDirectory` and Claude sign-ins made in
  * `claudeSignInDirectory`. Its OpenAI provider, its
- * Claude usage reads and its checks of an Anthropic API key go to the fake provider, which refuses everything that is
- * not a fixture request, and no Claude Code process is ever seen running on a home.
+ * Claude usage reads and its checks of an Anthropic or OpenAI API key go to the fake provider, which refuses everything
+ * that is not a fixture request, and no Claude Code process is ever seen running on a home.
  */
 export class AuthSwitchTestAuthority {
   private stopping: Promise<void> | null = null;
@@ -468,9 +517,7 @@ export class AuthSwitchTestAuthority {
         dataDirectory: plugins.path.join(directory, 'db'), socketPath: databaseSocketPath,
         authoritySocketPath, runtimeSocketPath,
         broker: { provider: new AuthSwitchOpenAiProvider({ fetch: provider.fetch }), secrets: plainCodec, proactive: false,
-          verifyAnthropicApiKey: async (apiKey, signal) => {
-            await plugins.flexAnthropic.listAnthropicApiKeyModels({ apiKey }, { signal, fetch: provider.fetch });
-          } },
+          verifyApiKey: authSwitchApiKeyVerifier(provider.fetch) },
         ...claude.options,
         codexNative: { home: new CodexNativeHome({ codexHome: codexHost.codexHome, executable: codexHost.binary,
           scope: codexHost.scope }), secrets: plainCodec },
@@ -663,7 +710,7 @@ export class AuthSwitchTestAuthority {
     await database.changeAccountAndGrant(updateId, account.accountId, account.loginId, () => ({
       account: { id: account.accountId, providerId: 'anthropic', issuer: 'anthropic', subject: identity.accountUuid,
         workspaceId: identity.organizationUuid, label: name, email: identity.emailAddress, plan: 'max',
-        primaryGrantId: account.loginId, maxUsagePercent: null, reserveLiftUntil: null, lapsesAt: null, removed: false, revision: 1, statusObservedAt: now, updateId },
+        primaryGrantId: account.loginId, maxUsagePercent: null, reserveLiftUntil: null, lapsesAt: null, spendLimitMicroUsd: null, keyHint: null, removed: false, revision: 1, statusObservedAt: now, updateId },
       grant: { id: account.loginId, accountId: account.accountId, providerId: 'anthropic', purpose: 'claude_host_native',
         audience: 'claude-code-host', state: 'native', owner: 'claude_native', grantGeneration: 1, authorizationGeneration: 1,
         revision: 1, ciphertext: null, accessExpiresAt: null, attemptId: null, retryAt: null, retryCount: 0,
@@ -701,7 +748,7 @@ export class AuthSwitchTestAuthority {
     const identity = authSwitchFixtureOpenAiIdentity(name);
     return { id: accountId, providerId: 'openai', issuer: 'openai', subject: identity.userId,
       workspaceId: identity.chatgptAccountId, label: name, email: identity.email, plan: 'pro', primaryGrantId: loginId,
-      maxUsagePercent: null, reserveLiftUntil: null, lapsesAt: null, removed: false, revision: 1, statusObservedAt: now, updateId };
+      maxUsagePercent: null, reserveLiftUntil: null, lapsesAt: null, spendLimitMicroUsd: null, keyHint: null, removed: false, revision: 1, statusObservedAt: now, updateId };
   }
 
   /**

package/ts_authswitch/ts_migration/0011_account_api_key_fields.ts

@@ -0,0 +1,20 @@
+import * as plugins from '../plugins.js';
+
+/**
+ * Gives every account recorded before API keys carried a spend limit the two members the account record now states.
+ *
+ * An API key account may carry a monthly spend limit (`spendLimitMicroUsd`) and names how its key ends (`keyHint`);
+ * the record states each, or `null` for none. Every account recorded earlier has neither: it gains
+ * `spendLimitMicroUsd: null` and `keyHint: null` -- an Anthropic key held from before keeps no hint, since its key is
+ * sealed -- and nothing else about it changes, neither its revision nor its update id, since no one changed the
+ * account. A record that already carries a member keeps it exactly as it is, which is what makes an interrupted run
+ * safe to repeat.
+ */
+export const addAccountApiKeyFields = async (db: plugins.nosqldb.SmartdataDb): Promise<void> => {
+  const accounts = db.mongoDb.collection('authswitch_authority_accounts');
+  for (const member of ['spendLimitMicroUsd', 'keyHint'] as const) {
+    const missing = { [member]: { $exists: false } };
+    if (!await accounts.findOne(missing)) continue;
+    await accounts.updateMany(missing, { $set: { [member]: null } });
+  }
+};

package/ts_authswitch/ts_migration/index.ts

@@ -9,6 +9,7 @@ import { addAccountMaxUsage } from './0007_account_max_usage.js';
 import { addAccountLapse } from './0008_account_lapse.js';
 import { addAccountReserveLift } from './0009_account_reserve_lift.js';
 import { prepareCodexHostRelease } from './0010_codex_host_release.js';
+import { addAccountApiKeyFields } from './0011_account_api_key_fields.js';
 
 /**
  * Runs on every start of an existing store, in this fixed order. Each module recognises the published shapes it
@@ -25,4 +26,5 @@ export const runAuthorityMigrations = async (db: plugins.nosqldb.SmartdataDb): P
   await addAccountLapse(db);
   await addAccountReserveLift(db);
   await prepareCodexHostRelease(db);
+  await addAccountApiKeyFields(db);
 };

package/ts_interfaces/functions.authorityscope.ts

@@ -147,10 +147,10 @@ export const findAuthorityDaemonLogin = (
 };
 
 /**
- * The login AGL's inference proxy binds for an account, and its purpose, like `findAuthorityDaemonLogin`: a
- * ChatGPT account's daemon-held `openai_managed` login, or an Anthropic account's daemon-held login -- a Claude
- * sign-in (`claude_host_native`), the one that can back a binding when the account holds several, or an API key
- * (`anthropic_api_key`).
+ * The login AGL's inference proxy binds for an account, and its purpose, like `findAuthorityDaemonLogin`: an OpenAI
+ * account's daemon-held login -- a ChatGPT sign-in (`openai_managed`) or an API key (`openai_api_key`) -- or an
+ * Anthropic account's daemon-held login -- a Claude sign-in (`claude_host_native`), the one that can back a binding
+ * when the account holds several, or an API key (`anthropic_api_key`).
  */
 export const findAuthorityGatewayLogin = (
   projectionArg: IControllerAuthorityProjection,
@@ -159,17 +159,37 @@ export const findAuthorityGatewayLogin = (
   const snapshot = projectionArg.snapshot;
   const account = snapshot?.accounts.find((accountArg) => accountArg.id === accountIdArg);
   if (!snapshot || !account || account.removed) return 'no_account';
-  if (account.providerId !== 'anthropic') return findAuthorityDaemonLogin(projectionArg, accountIdArg);
+  if (account.providerId !== 'anthropic') {
+    const managed = findAuthorityDaemonLogin(projectionArg, accountIdArg);
+    return managed !== 'no_login' ? managed : snapshot.logins.find((loginArg) => loginArg.accountId === accountIdArg
+      && loginArg.purpose === 'openai_api_key' && loginArg.owner === 'daemon') ?? 'no_login';
+  }
   const logins = snapshot.logins.filter((loginArg) => loginArg.accountId === accountIdArg
     && (loginArg.purpose === 'claude_host_native' || loginArg.purpose === 'anthropic_api_key')
     && loginArg.owner === 'daemon');
   return logins.find((loginArg) => loginArg.capabilities.canBind) ?? logins[0] ?? 'no_login';
 };
 
+/**
+ * The login an API key's answers are reported on (`authswitch.authority.usage.spend`): the key's live gateway login, or
+ * once the key was removed the login it had, as the projection publishes removed accounts and their logins too; the
+ * accounts service records a removed key's spend. `undefined` when the projection names no API-key login of the account.
+ */
+export const findAuthorityApiKeyLogin = (
+  projectionArg: IControllerAuthorityProjection,
+  accountIdArg: string,
+): TControllerAccountLogin | undefined => {
+  const isKeyLogin = (loginArg: TControllerAccountLogin) => loginArg.accountId === accountIdArg && loginArg.owner === 'daemon'
+    && (loginArg.purpose === 'anthropic_api_key' || loginArg.purpose === 'openai_api_key');
+  const live = findAuthorityGatewayLogin(projectionArg, accountIdArg);
+  if (typeof live !== 'string') return isKeyLogin(live) ? live : undefined;
+  return projectionArg.snapshot?.logins.filter(isKeyLogin).at(-1);
+};
+
 /**
  * A pool of AGL's inference proxy: its provider, and what its accounts authenticate with -- a subscription sign-in
- * (a ChatGPT or a Claude account), or an Anthropic API key. Claude Code runs on the Claude subscription pool, Flex's
- * Claude models only on the API-key pool.
+ * (a ChatGPT or a Claude account), or an API key of the provider. Claude Code runs on the Claude subscription pool,
+ * Flex's Claude models only on the Anthropic API-key pool.
  */
 export interface IInferencePool {
   provider: 'openai' | 'anthropic';
@@ -179,7 +199,7 @@ export interface IInferencePool {
 /**
  * The pool of AGL's inference proxy an account serves in, or `undefined` for none: an account whose gateway login
  * (`findAuthorityGatewayLogin`) the authority holds ready, can bind and keeps in no tool's home -- a ChatGPT account
- * this host's Codex does not run on, a Claude account, or an Anthropic API key.
+ * this host's Codex does not run on, a Claude account, or an Anthropic or OpenAI API key.
  */
 export const findInferencePool = (
   projectionArg: IControllerAuthorityProjection,
@@ -197,6 +217,9 @@ export const findInferencePool = (
   if (account.providerId === 'anthropic' && login.purpose === 'anthropic_api_key') {
     return { provider: 'anthropic', credential: 'api_key' };
   }
+  if (account.providerId === 'openai' && login.purpose === 'openai_api_key') {
+    return { provider: 'openai', credential: 'api_key' };
+  }
   return undefined;
 };
 
@@ -230,6 +253,18 @@ export const isFlexAuthorityConnectionId = (valueArg: unknown): valueArg is stri
  */
 export const flexClaudePoolConnectionId = 'flex:proxy:anthropic';
 
+/**
+ * Whether an account serves in the Claude pool Flex's Claude models run on: an Anthropic API key in the proxy's
+ * Anthropic API-key pool (`findInferencePool`). An OpenAI key serves the OpenAI API-key pool, which Flex does not use.
+ */
+export const isFlexClaudePoolMember = (
+  projectionArg: IControllerAuthorityProjection,
+  accountIdArg: string,
+): boolean => {
+  const pool = findInferencePool(projectionArg, accountIdArg);
+  return pool?.provider === 'anthropic' && pool.credential === 'api_key';
+};
+
 /** Whether a value is a Flex connection id: an authority account's, or the Claude pool's. */
 export const isFlexConnectionId = (valueArg: unknown): valueArg is string =>
   valueArg === flexClaudePoolConnectionId || isFlexAuthorityConnectionId(valueArg);

package/ts_interfaces/interfaces.ts

@@ -5,7 +5,7 @@ import type {
   TControllerBrowserPaintAvailability,
   TControllerBrowserPaintTermination,
 } from './browserpaint.js';
-export const controllerProtocolVersion = 43 as const;
+export const controllerProtocolVersion = 45 as const;
 export const controllerUpgradeManagementVersion = 2 as const;
 export const controllerPackageName = 'agl' as const;
 /** The systemd user unit `agl service install` writes; a controller it runs reports it in its status. */

package/ts_interfaces/plugins.ts

@@ -2,9 +2,12 @@ import * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
 import type * as browserRuntime from '@push.rocks/smartbrowser/runtime';
 // The account-management contract on its own. Its own doc comment declares it credential-free and
 // safe for browser code, while the package root is Node-only, so the browser-facing interfaces take
-// the subpath rather than the root export. It is a leaf that imports nothing, so the rules it
-// publishes -- the account label rule -- are taken from it as values rather than restated.
+// the subpath rather than the root export. Besides types it imports only the model id rule, itself a
+// leaf, so the rules it publishes -- the account label rule -- are taken from it as values rather than
+// restated.
 import * as authswitchAuthority from '../ts_authswitch/authority-contract.js';
+// An API key's monthly spend: the spend limit rule and dollar amounts, a leaf that imports nothing.
+import * as authswitchSpend from '../ts_authswitch/authority-spend.js';
 import type {
   AuthenticationResponseJSON,
   PublicKeyCredentialCreationOptionsJSON,
@@ -14,7 +17,7 @@ import type {
 
 export { typedrequestInterfaces };
 export type { browserRuntime };
-export { authswitchAuthority };
+export { authswitchAuthority, authswitchSpend };
 
 export type {
   AuthenticationResponseJSON,