@bitkyc08/opencodex 2.38.0 → 2.39.0

package/src/codex/quota-401-recovery.ts

@@ -0,0 +1,190 @@
+import { randomUUID } from "node:crypto";
+import { isCodexAccountGenerationLive, type CodexRefreshProvenance } from "./account-store";
+import { QUOTA_RECOVERY_LEASE_MS } from "./quota-recovery-timing";
+
+/**
+ * One refresh-and-replay per credential lineage, for a WHAM 401 (#3019).
+ *
+ * A bare 401 from `backend-api/wham/usage` is what a stale-but-refreshable bearer produces
+ * after a plan change, so quarantining on it tells the operator to re-authenticate an
+ * account that was fine. The fix is to refresh and replay once — and `once` is the whole
+ * problem, because an unbounded retry against an upstream 401 is a self-inflicted
+ * credential-stuffing loop.
+ *
+ * ## Why a claim id rather than the lineage
+ *
+ * Keying the budget on the lineage cannot separate an old claimant from a later retry on
+ * the same lineage: claim L, a transient failure releases L, another poll claims L, and
+ * the first caller's late settlement spends the second caller's claim. The claim id makes
+ * every mutation a compare-and-set on `(accountId, lineage, claimId)`, so a stale
+ * completion is a no-op instead of somebody else's budget.
+ *
+ * ## Why `spent` never expires and `claimed` does
+ *
+ * Expiring a spent record would hand the same lineage another refresh, which is exactly
+ * the property this module exists to hold. But a caller can be cancelled or die between
+ * claim and settle, so `claimed` carries a bounded lease: an expired lease is reclaimable,
+ * and is never promoted to `spent` because the refresh may not have happened.
+ */
+
+export type RecoveryRecord =
+  | { state: "claimed"; lineage: number; claimId: string; expiresAt: number }
+  /**
+   * `terminal` marks a lineage whose refresh proved the grant is dead. It is spent AND the
+   * account must keep reporting needs-reauth: without it, the next bare 401 finds the
+   * budget used, reports transient, and a dead credential looks healthy.
+   */
+  | { state: "spent"; lineage: number; terminal?: true }
+  | { state: "backoff"; lineage: number; nextAttemptAt: number };
+
+export type ClaimResult =
+  | { granted: true; claimId: string }
+  | { granted: false; reason: "spent" | "in-flight" | "backoff" };
+
+const records = new Map<string, RecoveryRecord>();
+
+function leaseExpired(record: RecoveryRecord, now: number): boolean {
+  return record.state === "claimed" && record.expiresAt <= now;
+}
+
+/**
+ * Claim the one refresh this lineage is entitled to.
+ *
+ * A live claim blocks EVERY lineage for the account, not just its own. The refresh it
+ * fences commits `G -> G+1` before the claimant can settle, so during that window a
+ * `G+1` claim would otherwise be granted and the late settlement would land on nothing.
+ */
+export function claimQuotaRecovery(
+  accountId: string,
+  lineage: number,
+  now: number = Date.now(),
+): ClaimResult {
+  const existing = records.get(accountId);
+  if (existing && !leaseExpired(existing, now)) {
+    if (existing.state === "claimed") return { granted: false, reason: "in-flight" };
+    if (existing.state === "spent") {
+      // Only this lineage is fenced. A different one is a new grant with its own budget.
+      if (existing.lineage === lineage) return { granted: false, reason: "spent" };
+    } else if (existing.lineage === lineage && existing.nextAttemptAt > now) {
+      return { granted: false, reason: "backoff" };
+    }
+  }
+  const claimId = randomUUID();
+  records.set(accountId, { state: "claimed", lineage, claimId, expiresAt: now + QUOTA_RECOVERY_LEASE_MS });
+  return { granted: true, claimId };
+}
+
+function heldClaim(accountId: string, claimId: string): Extract<RecoveryRecord, { state: "claimed" }> | null {
+  const existing = records.get(accountId);
+  if (!existing || existing.state !== "claimed" || existing.claimId !== claimId) return null;
+  return existing;
+}
+
+/**
+ * Record the outcome of a claimed refresh.
+ *
+ * Which lineage gets fenced depends on the outcome, and getting this backwards is how a
+ * fresh credential loses the recovery it is entitled to:
+ *
+ * - `self-refresh` and `joined-lineage` are this lineage's own attempt, so the RETURNED
+ *   generation is spent. The returned one, never the rejected one: a successful token
+ *   response can rotate only the refresh grant, leaving the access token byte-identical,
+ *   and the credential has already moved by then.
+ * - `external-replacement` means somebody else's credential is now stored. The claimed
+ *   OLD lineage is spent — this caller did use its attempt — and the returned generation
+ *   is left untouched so it can claim on its own next 401.
+ */
+export function settleQuotaRecovery(
+  accountId: string,
+  claimId: string,
+  outcome: { provenance: CodexRefreshProvenance; generation: number },
+): void {
+  const held = heldClaim(accountId, claimId);
+  if (!held) return; // superseded or already settled: never disturb a newer claimant
+  const fenced = outcome.provenance === "external-replacement" ? held.lineage : outcome.generation;
+  records.set(accountId, { state: "spent", lineage: fenced });
+}
+
+/**
+ * Record a refresh that failed with proof the grant itself is dead.
+ *
+ * Distinct from {@link releaseQuotaRecovery}: a revoked or expired grant will not become
+ * valid on the next poll, so backing off would let a later 401 report the account healthy
+ * while it is not. The lineage is fenced durably and the caller quarantines.
+ */
+export function settleQuotaRecoveryTerminal(accountId: string, claimId: string): void {
+  const held = heldClaim(accountId, claimId);
+  if (!held) return;
+  records.set(accountId, { state: "spent", lineage: held.lineage, terminal: true });
+}
+
+/** Did this lineage's one refresh prove the grant dead? */
+export function quotaRecoveryTerminalFor(accountId: string, lineage: number): boolean {
+  const record = records.get(accountId);
+  return record?.state === "spent" && record.lineage === lineage && record.terminal === true;
+}
+
+/**
+ * Release a claim whose refresh failed without proving anything about the credential.
+ *
+ * Into BACKOFF, not into eligibility: a failed quota request does not refresh the quota
+ * timestamp, so successive dashboard and background polls would each issue another token
+ * refresh — the loop, reopened from the other side.
+ */
+export function releaseQuotaRecovery(
+  accountId: string,
+  claimId: string,
+  backoffMs: number,
+  now: number = Date.now(),
+): void {
+  const held = heldClaim(accountId, claimId);
+  if (!held) return;
+  records.set(accountId, { state: "backoff", lineage: held.lineage, nextAttemptAt: now + backoffMs });
+}
+
+/**
+ * Drop records for accounts that no longer exist, and fences whose credential has moved.
+ *
+ * A live claim is exempt. Its refresh commits the generation forward, so "the fenced
+ * generation is no longer stored" is the EXPECTED state mid-flight, and removing it there
+ * would let a second claim in before the first settles.
+ */
+export function reconcileQuotaRecovery(liveAccountIds: ReadonlySet<string>, now: number = Date.now()): number {
+  let removed = 0;
+  for (const [accountId, record] of [...records]) {
+    if (!liveAccountIds.has(accountId)) {
+      records.delete(accountId);
+      removed += 1;
+      continue;
+    }
+    if (record.state === "claimed" && !leaseExpired(record, now)) continue;
+    if (!isCodexAccountGenerationLive(accountId, record.lineage)) {
+      records.delete(accountId);
+      removed += 1;
+    }
+  }
+  return removed;
+}
+
+/** Drop expired backoff windows and abandoned leases. */
+export function sweepExpiredQuotaRecovery(now: number = Date.now()): number {
+  let removed = 0;
+  for (const [accountId, record] of [...records]) {
+    // A spent record is durable: expiring it would grant the same lineage another refresh.
+    if (record.state === "spent") continue;
+    const stale = record.state === "backoff" ? record.nextAttemptAt <= now : leaseExpired(record, now);
+    if (stale) {
+      records.delete(accountId);
+      removed += 1;
+    }
+  }
+  return removed;
+}
+
+export function quotaRecoveryRecordForTests(accountId: string): RecoveryRecord | undefined {
+  return records.get(accountId);
+}
+
+export function resetQuotaRecoveryForTests(): void {
+  records.clear();
+}

package/src/codex/quota-recovery-timing.ts

@@ -0,0 +1,28 @@
+/**
+ * Timing contract shared by the credential refresh, the WHAM quota request, and the
+ * 401-recovery budget (#3019).
+ *
+ * A leaf on purpose: `auth-api.ts` imports the recovery store to claim and settle, so the
+ * recovery store cannot import `auth-api.ts` back for the WHAM timeout. Both of them, and
+ * `account-store.ts`, import this instead.
+ *
+ * These were three inline literals in three files. The lease has to outlast the operations
+ * it fences — a lease that expires mid-refresh admits a second claim for a lineage that is
+ * already being refreshed — so it is derived here rather than restated as a round number
+ * that drifts away from what it covers.
+ */
+
+/** The refresh flight's own `AbortSignal.timeout` ceiling. */
+export const CODEX_REFRESH_FLIGHT_CEILING_MS = 30_000;
+
+/** Deadline for one `backend-api/wham/usage` request. */
+export const WHAM_REQUEST_TIMEOUT_MS = 8_000;
+
+/**
+ * How long a recovery claim stays valid without settlement.
+ *
+ * The sequence a claim covers is: WHAM request → refresh → WHAM replay. Both quota legs sit
+ * inside the lease, which is why the request timeout is counted twice.
+ */
+export const QUOTA_RECOVERY_LEASE_MS =
+  CODEX_REFRESH_FLIGHT_CEILING_MS + WHAM_REQUEST_TIMEOUT_MS * 2;

package/src/codex/quota.ts

@@ -110,6 +110,12 @@ function mayCommitAccountQuota(accountId: string, writerGeneration: number): boo
 // Valid upstream percentages are normalized to 0..100. Keep "unknown" outside that domain so an
 // actually exhausted account is still eligible for threshold rotation.
 export const CODEX_UNKNOWN_USAGE_SCORE = 101;
+/**
+ * A window reading at or above this is a measured refusal, not a position on a scale.
+ *
+ * Separate from `CODEX_UNKNOWN_USAGE_SCORE` because they mean opposite things: unknown is
+ * "we have not observed this account", 100 is "we observed it and it is full".
+ */
 export const CODEX_EXHAUSTED_USAGE_PERCENT = 100;
 
 export function isCodexQuotaExhausted(

package/src/codex/routing.ts

@@ -17,7 +17,7 @@ import {
   seedPoolRotationAccount,
   selectPriorityTier,
 } from "./pool-rotation";
-import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
+import { CODEX_EXHAUSTED_USAGE_PERCENT, CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
 import { isThirtyDayOnlyCodexPlan } from "./plan";
 import {
   MAIN_CODEX_ACCOUNT_ID,
@@ -364,7 +364,8 @@ export function computeCodexUsageScore(quota: {
   weeklyPercent?: number;
   monthlyPercent?: number;
   shortPercent?: number;
-} | null, plan?: unknown): number {
+  shortResetAt?: number;
+} | null, plan?: unknown, now: number = Date.now()): number {
   if (!quota) return CODEX_UNKNOWN_USAGE_SCORE;
   const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
   const longWindows = isThirtyDayOnlyCodexPlan(plan)
@@ -376,11 +377,50 @@ export function computeCodexUsageScore(quota: {
   // account whose weekly/monthly usage is entirely unverified look like the emptiest in the
   // pool, so `pickLowestUsageAmong` would send every request to it. Unknown has to stay
   // unknown until a governing window is actually observed.
-  if (knownLong.length === 0) return CODEX_UNKNOWN_USAGE_SCORE;
+  //
+  // A FULL burst window is the exception (#3029). It is not an optimistic guess about an
+  // unobserved window — it is a direct observation that the account cannot serve a request
+  // right now, whatever its monthly position turns out to be. Unknown-means-selectable is
+  // correct for uncertainty and wrong for a measured refusal: the account stays selected,
+  // `applyQuotaAutoSwitch` never fires, and the pool wedges on an exhausted credential.
+  if (knownLong.length === 0) {
+    return isTerminalShortWindow(quota, now) ? CODEX_EXHAUSTED_USAGE_PERCENT : CODEX_UNKNOWN_USAGE_SCORE;
+  }
   const values = finite(quota.shortPercent) ? [...knownLong, quota.shortPercent] : knownLong;
   return Math.max(...values);
 }
 
+/**
+ * A short-only reading that proves the account is blocked NOW.
+ *
+ * Freshness is not optional. `getAccountQuota` performs no expiry check, partial updates
+ * carry the old short tuple forward, and disk hydration accepts a persisted reading for
+ * hours — so scoring 100 from `shortPercent` alone would keep excluding an account whose
+ * five-hour window has since reset. That is #3029 pointed the other way: the issue is that
+ * an exhausted account stays selected, and "a recovered account stays excluded" trades one
+ * unusable pool for another.
+ *
+ * A reading with no `shortResetAt` cannot be aged, so it stays unknown. The conservative
+ * direction here is the one that keeps an account selectable: a wrongly-selected account
+ * fails one request, while a wrongly-excluded one is invisible until someone reads the pool
+ * by hand.
+ */
+function isTerminalShortWindow(
+  quota: { shortPercent?: number; shortResetAt?: number },
+  now: number,
+): boolean {
+  if (typeof quota.shortPercent !== "number" || !Number.isFinite(quota.shortPercent)) return false;
+  if (quota.shortPercent < CODEX_EXHAUSTED_USAGE_PERCENT) return false;
+  const resetAt = quota.shortResetAt;
+  if (typeof resetAt !== "number" || !Number.isFinite(resetAt) || resetAt <= 0) return false;
+  // Both units reach storage: `normalizeResetAt` does not scale, and the GUI disambiguates
+  // by magnitude at read time. A comparison written against one assumption is off by 1000x
+  // against the other, and in the seconds-read-as-milliseconds direction every terminal
+  // reading looks like it reset in 1970 — a fix that passes its own test and does nothing.
+  const resetAtMs = resetAt < 10_000_000_000 ? resetAt * 1000 : resetAt;
+  return resetAtMs > now;
+}
+
 export function classifyCodexUpstreamOutcome(
   outcome: CodexUpstreamOutcome,
   denial?: "workspace" | "entitlement",
@@ -1131,7 +1171,7 @@ function getEligiblePoolAccounts(
   return selectPriorityTier(
     ids,
     codexAccountPriorityLookup(config),
-    id => hasCodexQuotaHeadroom(config, id, selectionOptions),
+    id => hasCodexQuotaHeadroom(config, id, selectionOptions, now),
     pinnedCodexAccountId(config),
   );
 }
@@ -1163,12 +1203,14 @@ function hasCodexQuotaHeadroom(
   config: OcxConfig,
   accountId: string,
   selectionOptions?: CodexAccountUsabilityOptions,
+  now: number = Date.now(),
 ): boolean {
   const threshold = config.autoSwitchThreshold ?? 80;
   if (threshold <= 0) return true;
   const usage = computeCodexUsageScore(
     getAccountQuota(accountId),
     getPoolAccountPlanForSelection(config, accountId, selectionOptions),
+    now,
   );
   if (isUnknownUsage(usage)) return true;
   return usage < threshold;
@@ -1188,7 +1230,7 @@ function pickFillFirstCodexAccount(
   if (eligible.length === 0) return null;
 
   const active = getEffectiveActiveCodexAccountId(config);
-  if (active && eligible.includes(active) && hasCodexQuotaHeadroom(config, active, selectionOptions)) {
+  if (active && eligible.includes(active) && hasCodexQuotaHeadroom(config, active, selectionOptions, now)) {
     return active;
   }
 
@@ -1200,7 +1242,7 @@ function pickNextFillFirstCodexAccount(
   config: OcxConfig,
   afterId: string | null,
   eligible: readonly string[] = listEligibleCodexAccountIds(config, Date.now()),
-  _now = Date.now(),
+  now = Date.now(),
   selectionOptions?: CodexAccountUsabilityOptions,
 ): string | null {
   if (eligible.length === 0) return null;
@@ -1208,7 +1250,7 @@ function pickNextFillFirstCodexAccount(
   if (!afterId) {
     // Prefer an under-threshold account when starting with no active cursor.
     for (const id of ordered) {
-      if (hasCodexQuotaHeadroom(config, id, selectionOptions)) return id;
+      if (hasCodexQuotaHeadroom(config, id, selectionOptions, now)) return id;
     }
     return ordered[0] ?? null;
   }
@@ -1223,7 +1265,7 @@ function pickNextFillFirstCodexAccount(
   const startIdx = stableAll.indexOf(afterId);
   if (startIdx < 0) {
     for (const id of ordered) {
-      if (hasCodexQuotaHeadroom(config, id, selectionOptions)) return id;
+      if (hasCodexQuotaHeadroom(config, id, selectionOptions, now)) return id;
     }
     return ordered[0] ?? null;
   }
@@ -1234,7 +1276,7 @@ function pickNextFillFirstCodexAccount(
     const candidate = stableAll[(startIdx + step) % stableAll.length]!;
     if (!eligible.includes(candidate)) continue;
     if (!fallback) fallback = candidate;
-    if (hasCodexQuotaHeadroom(config, candidate, selectionOptions)) return candidate;
+    if (hasCodexQuotaHeadroom(config, candidate, selectionOptions, now)) return candidate;
   }
   return fallback ?? ordered[0] ?? null;
 }
@@ -1356,6 +1398,7 @@ function pickLowerUsageAccount(
     const usage = computeCodexUsageScore(
       getAccountQuota(id),
       getPoolAccountPlanForSelection(config, id, selectionOptions),
+      now,
     );
     if (usage < bestUsage) {
       best = id;
@@ -1370,6 +1413,7 @@ function pickLowestUsageAmong(
   config: OcxConfig,
   ids: readonly string[],
   selectionOptions?: CodexAccountUsabilityOptions,
+  now: number = Date.now(),
 ): string | null {
   let best: string | null = null;
   let bestUsage = Number.POSITIVE_INFINITY;
@@ -1377,6 +1421,7 @@ function pickLowestUsageAmong(
     const usage = computeCodexUsageScore(
       getAccountQuota(id),
       getPoolAccountPlanForSelection(config, id, selectionOptions),
+      now,
     );
     if (usage < bestUsage) {
       best = id;
@@ -1397,6 +1442,7 @@ export function pickLowestUsageCodexAccount(
     config,
     getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions),
     selectionOptions,
+    now,
   );
 }
 
@@ -1540,7 +1586,7 @@ function pickPriorityPreemption(
   if (
     pinned !== undefined
     && eligible.includes(pinned)
-    && hasCodexQuotaHeadroom(config, pinned, selectionOptions)
+    && hasCodexQuotaHeadroom(config, pinned, selectionOptions, now)
   ) return null;
   const priorityOf = codexAccountPriorityLookup(config);
   if (priorityOf(eligible[0]!) <= priorityOf(active)) return null;
@@ -1548,8 +1594,9 @@ function pickPriorityPreemption(
   // picking one would hand the request straight back to a drained account.
   return pickLowestUsageAmong(
     config,
-    eligible.filter(id => hasCodexQuotaHeadroom(config, id, selectionOptions)),
+    eligible.filter(id => hasCodexQuotaHeadroom(config, id, selectionOptions, now)),
     selectionOptions,
+    now,
   );
 }
 
@@ -1566,6 +1613,7 @@ function releaseDrainedCodexAccountPin(
     CodexAccountUsabilityOptions,
     "nativeMainSelectionOnly" | "isMainAccountTokenLive"
   >,
+  now: number = Date.now(),
 ): void {
   const pinned = pinnedCodexAccountId(config);
   if (pinned === undefined) return;
@@ -1580,7 +1628,7 @@ function releaseDrainedCodexAccountPin(
   // is readable. Cached reauth and configured pause state were handled above.
   if (pinned === MAIN_CODEX_ACCOUNT_ID && selectionOptions?.nativeMainSelectionOnly === true) return;
   const drained = !isCodexAccountUsable(config, pinned, selectionOptions)
-    || !hasCodexQuotaHeadroom(config, pinned, selectionOptions);
+    || !hasCodexQuotaHeadroom(config, pinned, selectionOptions, now);
   if (!drained) return;
   clearCodexAccountPin(config);
   saveConfigPreservingClaudeCode(config);
@@ -1600,6 +1648,7 @@ function applyQuotaAutoSwitch(
   const activeUsage = computeCodexUsageScore(
     quota,
     getPoolAccountPlanForSelection(config, active, selectionOptions),
+    now,
   );
   // Unknown usage is not evidence that a user's explicit selection crossed the
   // threshold. Wait for quota priming instead of rotating among guesses.
@@ -1633,7 +1682,7 @@ function isHealthySharedCodexSelection(
   selectionOptions: CodexAccountUsabilityOptions | undefined,
 ): boolean {
   return isCodexAccountSelectable(config, accountId, now, quotaScope, selectionOptions)
-    && hasCodexQuotaHeadroom(config, accountId, selectionOptions)
+    && hasCodexQuotaHeadroom(config, accountId, selectionOptions, now)
     && !shouldFailover(config, accountId, now);
 }
 
@@ -1720,6 +1769,7 @@ function previewReusableAffinityAccount(
       const usage = computeCodexUsageScore(
         getAccountQuota(entry.accountId),
         getPoolAccountPlanForSelection(config, entry.accountId, selectionOptions),
+      now,
       );
       if (!isUnknownUsage(usage) && usage >= threshold) {
         const best = pickLowerUsageAccount(
@@ -1755,6 +1805,7 @@ function reevaluateAffinityQuota(
     ? computeCodexUsageScore(
         getAccountQuota(entry.accountId),
         getPoolAccountPlanForSelection(config, entry.accountId, selectionOptions),
+      now,
       )
     : 0;
   const overThreshold = threshold > 0 && !isUnknownUsage(usage) && usage >= threshold;
@@ -1848,6 +1899,7 @@ export function previewCodexAccountForRequest(
     const usage = computeCodexUsageScore(
       getAccountQuota(active),
       getPoolAccountPlanForSelection(config, active, selectionOptions),
+      now,
     );
     if (!isUnknownUsage(usage) && usage >= threshold) {
       active = pickLowerUsageAccount(config, active, usage, now, quotaScope, selectionOptions);
@@ -1887,7 +1939,7 @@ export function resolveCodexAccountForThreadDetailed(
   // revive after quota resets. Independent model scopes must never persist a
   // change to shared routing state.
   if (!isIndependentCodexQuotaScope(quotaScope)) {
-    releaseDrainedCodexAccountPin(config, sharedStateSelectionOptions(selectionOptions));
+    releaseDrainedCodexAccountPin(config, sharedStateSelectionOptions(selectionOptions), now);
   }
   const sharedActiveBeforeSelection = getEffectiveActiveCodexAccountId(config);
   const preserveSharedSelectionForModelDetour = modelScopedSelection && (
@@ -1945,7 +1997,7 @@ export function resolveCodexAccountForThreadDetailed(
       && isCodexAccountSelectable(config, entry.accountId, now, quotaScope, selectionOptions);
     const failoverReady = shouldFailover(config, entry.accountId, now);
     const healthyForSharedAffinity = selectableForSharedState
-      && hasCodexQuotaHeadroom(config, entry.accountId, sharedSelectionOptions)
+      && hasCodexQuotaHeadroom(config, entry.accountId, sharedSelectionOptions, now)
       && !failoverReady;
     if (
       selectableForRequest
@@ -2041,7 +2093,7 @@ export function resolveCodexAccountForThreadDetailed(
     sharedSelectionOptions,
   );
   const activeHealthyForSharedSelection = activeSelectableForSharedState
-    && hasCodexQuotaHeadroom(config, active, sharedSelectionOptions)
+    && hasCodexQuotaHeadroom(config, active, sharedSelectionOptions, now)
     && !shouldFailover(config, active, now);
   if (!isCodexAccountSelectable(config, active, now, quotaScope, selectionOptions)) {
     const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope, selectionOptions);

package/src/codex/subagent-model-fallback.ts

@@ -226,7 +226,10 @@ export function isNativeModelQuotaExhausted(
   const resolvedAccountId = resolveRouteFallbackAccountId(route, config, accountId);
   if (!resolvedAccountId) return false;
   const quota = getAccountQuota(resolvedAccountId);
-  const usage = computeCodexUsageScore(quota, getPoolAccountPlan(config, resolvedAccountId));
+  // Subagent fallback reads the same score, so a stale terminal reading would push
+  // subagents off a native model whose window has already reset. Thread the caller's clock
+  // rather than letting the scorer read wall time - the two would silently diverge.
+  const usage = computeCodexUsageScore(quota, getPoolAccountPlan(config, resolvedAccountId), now);
   if (usage >= CODEX_UNKNOWN_USAGE_SCORE) return false;
   return usage >= quotaThreshold(config);
 }

package/src/config/pending-teardown-names.d.mts

@@ -0,0 +1,8 @@
+export declare const PENDING_TEARDOWN_PREFIX: string;
+export declare const PENDING_TEARDOWN_SUFFIX: string;
+export declare const PENDING_TEARDOWN_UNREADABLE_SUFFIX: string;
+export declare function isPendingTeardownFileName(name: unknown): boolean;
+export declare function isQuarantinedTeardownFileName(name: unknown): boolean;
+export declare function isAnyTeardownObligationFileName(name: unknown): boolean;
+export declare function pendingTeardownNonceFromFileName(name: string): string | null;
+export declare function hasPendingTeardownIn(readdir: (dir: string) => string[], dir: string): boolean;

package/src/config/pending-teardown-names.mjs

@@ -0,0 +1,69 @@
+/**
+ * Naming rules for pending-teardown receipts, shared by both update lanes (#3008).
+ *
+ * Plain ESM because `bin/ocx.mjs` runs under Node before Bun exists and cannot import the
+ * TypeScript module. It lives here rather than being spelled out twice because that is
+ * exactly how this broke: the launcher kept checking the retired singleton filename after
+ * the receipts moved to one file per claim, so the npm lane silently stopped seeing every
+ * outstanding obligation.
+ */
+
+export const PENDING_TEARDOWN_PREFIX = "pending-teardown-";
+export const PENDING_TEARDOWN_SUFFIX = ".json";
+/**
+ * Suffix for an obligation that could not be read.
+ *
+ * It is still an obligation. Quarantine renames the file so the ordinary recovery loop
+ * stops re-reading garbage, but it must NOT stop counting: an update that proceeds
+ * because the evidence was filed away is exactly the outcome the receipt exists to
+ * prevent. Both lanes treat this as outstanding until an operator removes it.
+ */
+export const PENDING_TEARDOWN_UNREADABLE_SUFFIX = ".unreadable.json";
+const NONCE_RE = /^[0-9a-f]{32}$/;
+
+/** A receipt the recovery loop should read and try to discharge. */
+export function isPendingTeardownFileName(name) {
+  if (typeof name !== "string") return false;
+  if (isQuarantinedTeardownFileName(name)) return false;
+  if (!name.startsWith(PENDING_TEARDOWN_PREFIX) || !name.endsWith(PENDING_TEARDOWN_SUFFIX)) return false;
+  return NONCE_RE.test(name.slice(PENDING_TEARDOWN_PREFIX.length, name.length - PENDING_TEARDOWN_SUFFIX.length));
+}
+
+/** A receipt that could not be read and is waiting on a human. */
+export function isQuarantinedTeardownFileName(name) {
+  if (typeof name !== "string") return false;
+  if (!name.startsWith(PENDING_TEARDOWN_PREFIX) || !name.endsWith(PENDING_TEARDOWN_UNREADABLE_SUFFIX)) return false;
+  return NONCE_RE.test(name.slice(
+    PENDING_TEARDOWN_PREFIX.length,
+    name.length - PENDING_TEARDOWN_UNREADABLE_SUFFIX.length,
+  ));
+}
+
+/** Any obligation at all — readable or quarantined. Both block an update. */
+export function isAnyTeardownObligationFileName(name) {
+  return isPendingTeardownFileName(name) || isQuarantinedTeardownFileName(name);
+}
+
+export function pendingTeardownNonceFromFileName(name) {
+  if (!isPendingTeardownFileName(name)) return null;
+  return name.slice(PENDING_TEARDOWN_PREFIX.length, name.length - PENDING_TEARDOWN_SUFFIX.length);
+}
+
+/**
+ * Does the given config directory hold any outstanding obligation?
+ *
+ * Quarantined receipts count. Filing one away to unblock an update would let the very
+ * next `ocx update` install over a teardown that never ran — the enforcement has to
+ * survive until a human removes the file.
+ */
+export function hasPendingTeardownIn(readdir, dir) {
+  try {
+    return readdir(dir).some(isAnyTeardownObligationFileName);
+  } catch (error) {
+    // "There is no home yet" is the only honest empty answer. Any other failure —
+    // permissions, I/O, a file where the directory should be — means an obligation may be
+    // sitting there unread, and reporting "none" would let an update install over a
+    // teardown that never ran. Absence of proof is not proof of absence.
+    return error?.code !== "ENOENT";
+  }
+}