agl 40.4.0 → 40.5.0

package/ts_authswitch/classes.authorityusage.ts

@@ -8,6 +8,9 @@ import { authSwitchCombineUsageObservations, authSwitchObservedUsage,
   type TAuthSwitchUsageObservation } from './authority-usageheaders.js';
 import { usageWindowPeriod } from './accounts.js';
 import type { IAuthSwitchTokenUsage } from './authority-usagetokens.js';
+import { authSwitchSpendPeriod, type IAuthSwitchSpendReading } from './authority-spend.js';
+import type { IAuthSwitchSpendAnswer, TAuthSwitchPaymentProblemCause as TCause } from './authority-contract.js';
+import { authSwitchPaymentProblemHeld } from './authority-subscription.js';
 import { AuthSwitchUsageEstimator, authSwitchRolledOpenAiLimits, type IAuthSwitchUsageEstimateState,
   type IAuthSwitchUsageEstimatorOptions, type TAuthSwitchEstimateBasis } from './classes.authorityusageestimate.js';
 
@@ -16,12 +19,12 @@ type TRateLimits = IOpenAiAccountRateLimits;
 /**
  * Why a usage reading is missing or incomplete. `held_in_container`: the Claude login runs in a registered container
  * home, whose files are the container's; the authority reads its usage again once the login is moved out. `pending`:
- * the account's first read has not finished yet.
+ * the account's first read has not finished yet. `spend_unavailable`: an API key's spend ledger could not be read.
  */
 export type TAuthSwitchUsageProblem =
   | 'none' | 'unsupported' | 'access_unavailable' | 'provider_unavailable'
   | 'provider_rejected' | 'profile_unavailable' | 'usage_unavailable'
-  | 'context_changed' | 'expired' | 'held_in_container' | 'pending';
+  | 'context_changed' | 'expired' | 'held_in_container' | 'pending' | 'spend_unavailable';
 
 export interface IAuthSwitchNativeUsageSource {
   homeId: string;
@@ -69,10 +72,18 @@ export interface IAuthSwitchClaudeStatus {
   rateLimit: { retryAt: string | null } | null;
 }
 
-export type TAuthSwitchUsageReading =
+/** A usage reading the authority reads from a provider for a subscription sign-in, and stores between its runs. */
+export type TAuthSwitchProviderUsageReading =
   | { kind: 'openai'; rateLimits: TRateLimits }
   | { kind: 'anthropic'; status: IAuthSwitchClaudeStatus };
 
+/**
+ * A login's usage reading: a subscription sign-in's, as its provider stated it, or an API key's monthly spend
+ * (`spend`), which the authority answers from what AGL's inference proxy reported and never reads from a provider.
+ */
+export type TAuthSwitchUsageReading = TAuthSwitchProviderUsageReading
+  | { kind: 'spend'; spend: IAuthSwitchSpendReading };
+
 export interface IAuthSwitchUsageAccess {
   accessToken: string;
   accountId: string;
@@ -96,10 +107,33 @@ export interface IAuthSwitchUsageAccess {
 export interface IAuthSwitchPaymentProblem {
   at: string;
   subscription: IClaudeSubscription | null;
+  /**
+   * What the provider refused for (`TAuthSwitchPaymentProblemCause`), present only for `spend_cap` and `quota`, which
+   * only an API key's login is held with; absent, the cause is `billing`, on a Claude login and an API key alike. A
+   * problem with a cause has no subscription.
+   */
+  cause?: Exclude<TAuthSwitchPaymentProblemCause, 'billing'>;
+  /**
+   * When a `spend_cap` lifts by itself: the end of the month in UTC `at` falls in (`authSwitchSpendPeriod(at).end`),
+   * present exactly for that cause; once it passed the problem holds nothing (`authSwitchPaymentProblemHeld`). Every
+   * other problem holds until it is cleared: a Claude login's by a read, an API key's by a re-check (`usage.recheck`).
+   */
+  until?: string;
 }
 
 /**
- * How a re-check's read went (`AuthSwitchAuthorityUsage.recheck`): `healthy` -- the profile was found, the sign-in
+ * Why a provider refused inference on an API key for money, as AGL's inference proxy read the refusal: `billing`, the
+ * organization's billing (Anthropic HTTP 402 `billing_error`, and every Claude sign-in's payment problem); `spend_cap`,
+ * the monthly spend cap of the key's usage tier, which lifts at 00:00 UTC on the first of the next month (Anthropic 429
+ * `enforced_spend_limit_reached`); `quota`, the organization's or project's credit or spend limit (OpenAI 429
+ * `insufficient_quota`).
+ */
+export type TAuthSwitchPaymentProblemCause = 'billing' | 'spend_cap' | 'quota';
+
+/**
+ * How a re-check went (`AuthSwitchAuthorityUsage.recheck`). `cleared`: the login is an API key, whose hold a re-check
+ * lifts without asking the provider, which states no billing or quota on a model list; the next request shows whether the
+ * provider takes the key again. Every other outcome is a Claude login's read: `healthy` -- the profile was found, the sign-in
  * accepted and the identity matched -- clears a payment problem; every other outcome clears nothing. `credential_rejected`:
  * Anthropic rejected the sign-in, renewed too. `token_unusable`: no access token usable for a profile read (it could not
  * be resolved, is not fresh enough, or lacks the `user:profile` scope). `profile_missing`: the profile read failed or its
@@ -108,7 +142,7 @@ export interface IAuthSwitchPaymentProblem {
  * lies ahead.
  */
 export type TAuthSwitchRecheckOutcome = 'healthy' | 'credential_rejected' | 'token_unusable' | 'profile_missing'
-  | 'mismatch' | 'read_failed';
+  | 'mismatch' | 'read_failed' | 'cleared';
 
 /** A re-check's answer: the usage the authority holds once its read finished, and how that read went. */
 export interface IAuthSwitchUsageRecheck {
@@ -120,7 +154,7 @@ export interface IAuthSwitchUsageRecheck {
 export interface IAuthSwitchStoredUsage {
   context: IAuthSwitchUsageContext;
   updateId: string;
-  reading: TAuthSwitchUsageReading | null;
+  reading: TAuthSwitchProviderUsageReading | null;
   observedAt: string | null;
   currentUntil: string | null;
   staleUntil: string | null;
@@ -262,6 +296,15 @@ export interface IAuthSwitchAuthorityUsageOptions {
   estimate?: IAuthSwitchUsageEstimatorOptions;
   /** Where the reader's notes go, one line each: standard error, the service's journal, unless set. */
   log?: (lineArg: string) => void;
+  /**
+   * An API key's spend ledger: its month's reading at `nowArg`, and a spend report recorded in one transaction
+   * (`AuthSwitchAuthorityDatabase.readSpend`, `.recordSpend`). Without it the authority answers no key's usage.
+   */
+  spend?: {
+    read(accountId: string, loginId: string, nowArg: number): Promise<IAuthSwitchSpendReading>;
+    record(accountId: string, loginId: string, answers: readonly IAuthSwitchSpendAnswer[],
+      nowArg: number): Promise<IAuthSwitchSpendReading>;
+  };
 }
 
 /** What a client that served requests on a login reports about the account: see `report`. */
@@ -345,6 +388,15 @@ const usable = (context: IAuthSwitchUsageContext): boolean =>
         || (context.owner === 'claude_native' && context.nativeSource !== null
           && context.grantState === 'native'))));
 
+/** An API key of its account's provider, held or removed: its spend is recorded either way. */
+const apiKeyOfAccount = (context: IAuthSwitchUsageContext): boolean => context.workspaceId === 'api-key'
+  && ((context.providerId === 'anthropic' && context.purpose === 'anthropic_api_key')
+    || (context.providerId === 'openai' && context.purpose === 'openai_api_key'));
+
+/** An API key's login the authority holds: a key nothing else renews. Its usage is its spend ledger. */
+const apiKeyLogin = (context: IAuthSwitchUsageContext): boolean => apiKeyOfAccount(context) && context.owner === 'daemon'
+  && context.nativeSource === null;
+
 /** A login read through Claude Code's own home: its context names the home only once that home is opened for a read. */
 const native = (context: IAuthSwitchUsageContext): boolean => context.providerId === 'anthropic'
   && context.purpose === 'claude_host_native' && context.owner === 'claude_native' && context.grantState === 'native';
@@ -664,7 +716,8 @@ export class AuthSwitchAuthorityUsage {
    * carries it. Refused for any login but a Claude login the authority renews, and for one with no usage record of its
    * sign-in yet, which the proxy never routed to. The provider is not asked.
    */
-  public reportPaymentProblem(accountId: string, loginId: string, observedAt: string): Promise<IAuthSwitchUsageSnapshot> {
+  public reportPaymentProblem(accountId: string, loginId: string, observedAt: string,
+    cause: TCause = 'billing'): Promise<IAuthSwitchUsageSnapshot> {
     if (this.closed) return Promise.reject(new Error('Authority usage helper is closed.'));
     return this.admit((async () => {
       if (!/^[a-f0-9]{64}$/.test(accountId) || !/^[a-f0-9]{64}$/.test(loginId) || !Number.isFinite(Date.parse(observedAt))) {
@@ -672,9 +725,21 @@ export class AuthSwitchAuthorityUsage {
       }
       for (let attempt = 1; ; attempt++) {
         const context = await this.currentContext(accountId, loginId);
+        if (context && context.accountId === accountId && context.loginId === loginId && !context.removed
+          && apiKeyLogin(context) && context.grantState === 'ready') {
+          if (await this.holdApiKey(context, observedAt, cause)) return this.spendAnswer(context);
+          if (attempt >= paymentProblemWriteAttempts) {
+            throw new AuthSwitchRefusal('account_changed',
+              'The key\'s record kept changing, so its payment problem was not written; report it again.');
+          }
+          continue;
+        }
         if (!context || context.accountId !== accountId || context.loginId !== loginId || !paymentProblemLogin(context)) {
           throw new AuthSwitchRefusal('login_unavailable',
-            'Only a Claude login the account service renews is held with a payment problem.');
+            'Only a Claude login the account service renews, or an API key it holds, is held with a payment problem.');
+        }
+        if (cause !== 'billing') {
+          throw new AuthSwitchRefusal('login_unavailable', 'A Claude login is held only for a billing error.');
         }
         const stored = await this.options.store.read(accountId, loginId);
         const held = stored && authSwitchSameUsageSource(context, stored.context) ? stored : null;
@@ -714,9 +779,13 @@ export class AuthSwitchAuthorityUsage {
         throw new Error('Invalid authority usage identity.');
       }
       const context = await this.currentContext(accountId, loginId);
+      if (context && context.accountId === accountId && context.loginId === loginId && !context.removed
+        && apiKeyLogin(context)) {
+        return this.clearApiKey(context);
+      }
       if (!context || context.accountId !== accountId || context.loginId !== loginId
         || context.providerId !== 'anthropic' || context.purpose !== 'claude_host_native') {
-        throw new AuthSwitchRefusal('login_unavailable', 'Only a Claude login is re-checked.');
+        throw new AuthSwitchRefusal('login_unavailable', 'Only a Claude login or an API key is re-checked.');
       }
       const key = this.key(accountId, loginId);
       await this.answer(accountId, loginId, null);
@@ -737,6 +806,97 @@ export class AuthSwitchAuthorityUsage {
     })());
   }
 
+  /**
+   * Records what answers relayed on an API key's login cost (`authswitch.authority.usage.spend`) and answers the key's
+   * usage once the report committed. A removed key's spend is recorded too; its usage then answers unavailable.
+   */
+  public recordSpend(accountId: string, loginId: string,
+    answers: readonly IAuthSwitchSpendAnswer[]): Promise<IAuthSwitchUsageSnapshot> {
+    if (this.closed) return Promise.reject(new Error('Authority usage helper is closed.'));
+    return this.admit((async () => {
+      if (!/^[a-f0-9]{64}$/.test(accountId) || !/^[a-f0-9]{64}$/.test(loginId)) {
+        throw new Error('Invalid authority usage identity.');
+      }
+      const context = await this.currentContext(accountId, loginId);
+      const spend = this.options.spend;
+      if (!spend || !context || context.accountId !== accountId || context.loginId !== loginId || !apiKeyOfAccount(context)) {
+        throw new AuthSwitchRefusal('login_unavailable', 'Only an API key\'s login records spend.');
+      }
+      await spend.record(accountId, loginId, answers, this.now());
+      return this.answer(accountId, loginId, null);
+    })());
+  }
+
+  /**
+   * An API key's usage: its month's spend from the ledger, current as of now, which stays current until the month ends
+   * or a report or a limit change moves it, and the payment problem it is held with, while it holds.
+   */
+  private async spendAnswer(context: IAuthSwitchUsageContext): Promise<IAuthSwitchUsageSnapshot> {
+    const { accountId, loginId } = context;
+    if (context.removed || !this.options.spend) {
+      return this.unavailable(accountId, loginId, context.removed ? 'access_unavailable' : 'unsupported');
+    }
+    const now = this.now();
+    let spend: IAuthSwitchSpendReading;
+    let held: IAuthSwitchStoredUsage | null;
+    try {
+      [spend, held] = await Promise.all([this.options.spend.read(accountId, loginId, now),
+        this.options.store.read(accountId, loginId)]);
+    } catch {
+      this.log('Authswitch could not read an API key\'s spend; the key is answered without a reading.');
+      return this.unavailable(accountId, loginId, 'spend_unavailable');
+    }
+    const paymentProblem = held && authSwitchSameUsageSource(context, held.context) && held.paymentProblem
+      && authSwitchPaymentProblemHeld(held.paymentProblem, now) ? held.paymentProblem : undefined;
+    const readAt = timestamp(now);
+    return { accountId, loginId, state: 'current', reading: { kind: 'spend', spend }, observedAt: readAt, readAt,
+      currentUntil: spend.resetAt, staleUntil: spend.resetAt, lastAttemptAt: null, nextAttemptAt: null,
+      lastReadError: null, problem: 'none', ...(paymentProblem ? { paymentProblem } : {}) };
+  }
+
+  /**
+   * Holds an API key with a payment problem on its usage record, which holds nothing else: when it was seen -- a time
+   * ahead of the authority's clock counts as now -- and its cause; `billing` is written as no cause, and a `spend_cap`
+   * lifts at the end of the month it was seen in. False when another write of the record landed first.
+   */
+  private async holdApiKey(context: IAuthSwitchUsageContext, observedAt: string, cause: TCause): Promise<boolean> {
+    const stored = await this.options.store.read(context.accountId, context.loginId);
+    const held = stored && authSwitchSameUsageSource(context, stored.context) ? stored : null;
+    const now = this.now();
+    const at = timestamp(Math.min(Date.parse(observedAt), now));
+    const paymentProblem: IAuthSwitchPaymentProblem = cause === 'spend_cap'
+      ? { at, subscription: null, cause, until: authSwitchSpendPeriod(Date.parse(at)).end }
+      : cause === 'quota' ? { at, subscription: null, cause } : { at, subscription: null };
+    const next: IAuthSwitchStoredUsage = { context, updateId: plugins.crypto.randomUUID(), reading: null,
+      observedAt: null, currentUntil: null, staleUntil: null, lastAttemptAt: at, nextAttemptAt: at, failures: 0,
+      problem: 'none', paymentProblem };
+    return this.options.store.publishIfCurrent(context, held && sameContext(context, held.context) ? held.updateId : null,
+      next);
+  }
+
+  /**
+   * A re-check of an API key: lifts the payment problem it is held with, without asking the provider, whose model list
+   * states no billing or quota; the next request shows whether the provider takes the key again.
+   */
+  private async clearApiKey(context: IAuthSwitchUsageContext): Promise<IAuthSwitchUsageRecheck> {
+    for (let attempt = 1; ; attempt++) {
+      const stored = await this.options.store.read(context.accountId, context.loginId);
+      const held = stored && authSwitchSameUsageSource(context, stored.context) && stored.paymentProblem ? stored : null;
+      if (!held) return { usage: await this.spendAnswer(context), outcome: 'cleared' };
+      // A record without the member: the store's transition drops a problem the draft does not hold.
+      const { paymentProblem: _lifted, ...rest } = held;
+      const next: IAuthSwitchStoredUsage = { ...rest, context, updateId: plugins.crypto.randomUUID() };
+      if (await this.options.store.publishIfCurrent(context, sameContext(context, held.context) ? held.updateId : null,
+        next)) {
+        return { usage: await this.spendAnswer(context), outcome: 'cleared' };
+      }
+      if (attempt >= paymentProblemWriteAttempts) {
+        throw new AuthSwitchRefusal('account_changed', 'The key\'s record kept changing, so its hold was not lifted; '
+          + 're-check it again.');
+      }
+    }
+  }
+
   /** Logs a Claude subscription status the first time this run reads it, up to `maximumLoggedSubscriptionStatuses`. */
   private noteSubscriptionStatus(statusArg: string | null): void {
     if (statusArg === null || this.subscriptionStatusesCapped || this.loggedSubscriptionStatuses.has(statusArg)) return;
@@ -774,6 +934,7 @@ export class AuthSwitchAuthorityUsage {
     if (context.accountId !== accountId || context.loginId !== loginId) {
       return this.unavailable(accountId, loginId, 'context_changed');
     }
+    if (apiKeyLogin(context)) return this.spendAnswer(context);
     if (!readable(context)) {
       this.unschedule(accountId, loginId);
       return this.unavailable(accountId, loginId,
@@ -999,7 +1160,7 @@ export class AuthSwitchAuthorityUsage {
       previous = latest && sameContext(context, latest.context) ? latest : null;
       held = latest && authSwitchSameUsageSource(context, latest.context) ? latest : null;
     };
-    let reading: TAuthSwitchUsageReading | null = null;
+    let reading: TAuthSwitchProviderUsageReading | null = null;
     /** Whether the read stated the account's windows: only then is it a reading the schedule waits a full slot after. */
     let windowsRead = false;
     let rateLimited = false;

package/ts_authswitch/classes.claudenative.ts

@@ -14,11 +14,20 @@ export const CLAUDE_NATIVE_MINIMUM_VERSION = '2.1.273';
 /**
  * The releases whose lock table, live credential pickup and native-login selector were read from their own bundle
  * (native-contracts.md). The usage of an adopted home's login is read from the home only while every Claude Code
- * session running there runs one of these or a later release than the newest of them, which is read as that one
- * (`claudeNativeReleaseReadsAsVerified`, owner ruling 2026-10-22, AGL-685); an installed release between the floor and
- * the newest that is not listed is read from only while no session runs in that home.
+ * session running there runs one of these or a release from `CLAUDE_NATIVE_READ_AS_VERIFIED_FROM` on
+ * (`claudeNativeReleaseReadsAsVerified`, owner ruling 2026-10-22, AGL-685); an installed release below that line that
+ * is not listed is read from only while no session runs in that home. The controller's verified release (2.1.306,
+ * AGL-686) and its fleet floor (2.1.282) are listed. 2.1.288, the release AGL's own Claude chats run through the Agent
+ * SDK, had these items read from the SDK's binary (AGL-688) and is listed for the usage read only: the fleet never ran
+ * it, so it is never the fleet's floor or the verified release.
  */
-export const CLAUDE_NATIVE_VERIFIED_RELEASES: readonly string[] = ['2.1.273', '2.1.282'];
+export const CLAUDE_NATIVE_VERIFIED_RELEASES: readonly string[] = ['2.1.273', '2.1.282', '2.1.288', '2.1.306'];
+/**
+ * The line from which the usage read takes any release, listed or not, as verified (owner ruling 2026-10-22, AGL-685):
+ * the controller's fleet floor (`claudeCodeFleetFloor`), which a test holds equal to it. It does not move when a newer
+ * release is verified.
+ */
+export const CLAUDE_NATIVE_READ_AS_VERIFIED_FROM = '2.1.282';
 /**
  * The releases whose credential custody contract was read from their own bundle (native-contracts.md): the OAuth
  * refresh lock and its legacy twin, the credential store's write lock and the global config lock; the store read
@@ -126,7 +135,8 @@ export class ClaudeNativeEffectiveAuthUnsupportedError extends Error {
     public readonly sessions: readonly IClaudeNativeRefusedSession[] = []) {
     super((reason === 'unsupported_release'
       ? `Reading Claude Code's own login requires Claude Code ${CLAUDE_NATIVE_MINIMUM_VERSION} or newer, and a session `
-        + `running in this home must run a verified release (${CLAUDE_NATIVE_VERIFIED_RELEASES.join(', ')}) or a newer one.`
+        + `running in this home must run a verified release (${CLAUDE_NATIVE_VERIFIED_RELEASES.join(', ')}) or any release `
+        + `from ${CLAUDE_NATIVE_READ_AS_VERIFIED_FROM} on.`
       : `Cannot prove that Claude Code uses its native claude.ai login (${reason}).`)
       + (sessions.length ? ` Refused: ${sessions.map(describeClaudeNativeRefusedSession).join('; ')}.` : ''));
   }
@@ -251,17 +261,15 @@ const atLeast = (version: [number, number, number], minimum: [number, number, nu
 const claudeBuildPattern = /^(\d{1,6})\.(\d{1,6})\.(\d{1,6})(?:-[0-9a-f]{1,64})?$/;
 /**
  * Whether a session of this build is read like a verified release when its home's login is read for usage: a listed
- * release, or a build of a release no older than the newest listed one, which is read as that one. A hashed build is
- * ordered by its release. Custody never uses this: it matches whole build names (`CLAUDE_NATIVE_CUSTODY_RELEASES`).
+ * release, or a build of a release from `CLAUDE_NATIVE_READ_AS_VERIFIED_FROM` on. A hashed build is ordered by its
+ * release. Custody never uses this: it matches whole build names (`CLAUDE_NATIVE_CUSTODY_RELEASES`).
  */
 export const claudeNativeReleaseReadsAsVerified = (build: string | null): boolean => {
   if (build === null) return false;
   if (CLAUDE_NATIVE_VERIFIED_RELEASES.includes(build)) return true;
   const match = claudeBuildPattern.exec(build);
   if (!match) return false;
-  const newest = CLAUDE_NATIVE_VERIFIED_RELEASES.map(release => parseClaudeVersion(release)!)
-    .reduce((left, right) => atLeast(left, right) ? left : right);
-  return atLeast([Number(match[1]), Number(match[2]), Number(match[3])], newest);
+  return atLeast([Number(match[1]), Number(match[2]), Number(match[3])], parseClaudeVersion(CLAUDE_NATIVE_READ_AS_VERIFIED_FROM)!);
 };
 
 /**
@@ -458,10 +466,15 @@ export const claudeNativeCredentialStoreDirectory = (env: NodeJS.ProcessEnv): st
     ? plugins.path.join(env.HOME, '.claude').normalize('NFC') : null;
 };
 
+/**
+ * An environment selects this home and keeps its credential store there too: a store elsewhere
+ * (`CLAUDE_SECURESTORAGE_CONFIG_DIR`) selects another login, so it is refused as an override.
+ */
 const assertNativeHome = (env: NodeJS.ProcessEnv, configDir: string): void => {
-  const selected = selectedNativeHome(env);
-  if (!selected || !plugins.path.isAbsolute(selected) || plugins.path.normalize(selected) !== configDir) {
-    throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
+  for (const selected of [selectedNativeHome(env), claudeNativeCredentialStoreDirectory(env)]) {
+    if (!selected || !plugins.path.isAbsolute(selected) || plugins.path.normalize(selected) !== configDir) {
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
+    }
   }
 };
 
@@ -908,8 +921,8 @@ export class ClaudeNativeAdapter {
 
   /**
    * The whole support check of reading the login Claude Code selects in the home: the home's custody, and the proof
-   * that Claude Code selects its native login there -- for the daemon's own environment and settings and for every
-   * process running on the home.
+   * that Claude Code selects its native login there -- for the daemon's own environment (its home and its credential
+   * store are both this home) and settings, and for every process running on the home.
    */
   private assertSupported(): IClaudeNativeSupport {
     this.assertHomeDirectories();

package/ts_authswitch/classes.claudesignin.ts

@@ -107,8 +107,11 @@ export class ClaudeSignInAuthority {
     const now = this.now();
     const signIn: IClaudeSignIn = {
       operation: { id: operationId, state: 'pending',
+        // The credential store is pinned to the home as well: one an inherited CLAUDE_SECURESTORAGE_CONFIG_DIR names
+        // would take the new login, over whatever login it holds, and the home would never get it.
         prompt: { flow: 'terminal', directory,
-          command: `CLAUDE_CONFIG_DIR=${shellWord(directory)} claude ${authSwitchClaudeSignInArguments.join(' ')}` },
+          command: `CLAUDE_CONFIG_DIR=${shellWord(directory)} CLAUDE_SECURESTORAGE_CONFIG_DIR=${shellWord(directory)} `
+            + `claude ${authSwitchClaudeSignInArguments.join(' ')}` },
         result: null, error: null, createdAt: new Date(now).toISOString(), updatedAt: new Date(now).toISOString(),
         expiresAt: new Date(now + signInWindowMs).toISOString(), finishedAt: null, revision: 1 },
       directory, parent, timer: null, commit: null,

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.
@@ -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`.