@bitkyc08/opencodex 2.39.0 → 2.40.0

package/src/client/runtime.ts

@@ -0,0 +1,93 @@
+import { spawn } from "node:child_process";
+import type { Server } from "bun";
+import { loadConfig } from "../config";
+import { removePid, removeRuntimePort, writePid, writeRuntimePort } from "../config/process-state";
+import { installCrashGuards } from "../lib/crash-guard";
+import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { findAvailablePort } from "../server/ports";
+import { startMachineListener } from "./machine-listener";
+import { readClientConnectionState } from "./state";
+
+let activeServer: Server<unknown> | null = null;
+let activePort: number | null = null;
+let recycleScheduled = false;
+
+function cleanup(): void {
+  removePid(process.pid);
+  removeRuntimePort(process.pid);
+}
+
+export function scheduleStandaloneRecycle(): void {
+  if (recycleScheduled) return;
+  recycleScheduled = true;
+  const timer = setTimeout(() => {
+    const port = activePort;
+    try { activeServer?.stop(true); } catch { /* best effort */ }
+    cleanup();
+    // Recycling back to standalone after `ocx disconnect` must actually bring a standalone
+    // proxy back, under either launch shape.
+    //
+    // Unsupervised: spawn the replacement ourselves and exit 0.
+    //
+    // Supervised (`OCX_SERVICE=1`): do NOT spawn — the supervisor owns the process, and a
+    // second copy would fight it for the port. But exit 0 does not work either: the real
+    // supervisor configs are failure-only (systemd `Restart=on-failure`, WinSW
+    // `<onfailure action="restart"/>`, the Task Scheduler ERRORLEVEL loop), so a clean exit
+    // reads as "the service finished" and nothing restarts. The client stayed down until the
+    // operator noticed. Exit 1 is what those configs are watching for, and it is the same
+    // policy the dashboard recycle already uses (src/server/management/system-restart.ts).
+    //
+    // launchd's KeepAlive restarts on any exit, so it is correct under both branches.
+    if (process.env.OCX_SERVICE === "1") {
+      process.exit(1);
+    }
+    if (port) {
+      const child = spawn(process.execPath, selfLaunchArgv(["start", "--port", String(port)]), {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env: { ...process.env },
+      });
+      child.unref();
+    }
+    process.exit(0);
+  }, 50);
+  if (typeof timer === "object" && "unref" in timer) timer.unref();
+}
+
+export async function startClientRuntime(
+  options: { port?: number; block?: boolean } = {},
+): Promise<void> {
+  const state = readClientConnectionState();
+  if (state.kind !== "connected") throw new Error(`client runtime refused: client state is ${state.kind}`);
+  const config = loadConfig();
+  const preferred = options.port ?? config.port ?? 10100;
+  const port = await findAvailablePort(preferred, "127.0.0.1", {
+    preferRetryMs: options.port === undefined ? 750 : 5_000,
+    preferRetryIntervalMs: 50,
+    allowEphemeralFallback: options.port === undefined,
+  });
+  const server = startMachineListener(port, { state: state.value });
+  const boundPort = server.port ?? port;
+  activeServer = server;
+  activePort = boundPort;
+  installCrashGuards();
+  writePid(process.pid);
+  writeRuntimePort({ pid: process.pid, port: boundPort, hostname: "127.0.0.1" });
+
+  let shuttingDown = false;
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    try { server.stop(true); } finally {
+      cleanup();
+      process.exit(0);
+    }
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  if (process.platform !== "win32") process.on("SIGHUP", shutdown);
+  process.on("exit", cleanup);
+
+  if (options.block ?? true) await new Promise<void>(() => {});
+}

package/src/client/state.ts

@@ -0,0 +1,175 @@
+import { readFileSync } from "node:fs";
+import {
+  getConfigPath,
+  deleteConfigTopLevelKey,
+  getDefaultConfig,
+  mutatePersistedConfig,
+  readConfigDiagnostics,
+  saveConfig,
+} from "../config";
+import type { OcxClientConnectionConfig } from "../types";
+import {
+  readServiceApiTokenState,
+  readTokenBackupState,
+  removeOrphanTokenBackup,
+} from "../lib/service-secrets";
+
+export type ClientConnectionState =
+  | { kind: "disconnected" }
+  | { kind: "connected"; value: OcxClientConnectionConfig }
+  | { kind: "invalid"; reason: string }
+  | { kind: "mismatched"; reason: string };
+
+export type ClientRotationRecoveryGate =
+  | { kind: "clean" }
+  | { kind: "orphan-cleaned" }
+  | { kind: "recovery-required"; reason: string }
+  | { kind: "unsafe"; reason: string };
+
+function rawTopLevelConfig(): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(readFileSync(getConfigPath(), "utf8").replace(/^\uFEFF/, "")) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readClientConnectionState(): ClientConnectionState {
+  const raw = rawTopLevelConfig();
+  const diagnostics = readConfigDiagnostics();
+  if (!raw) {
+    return diagnostics.source === "default"
+      ? { kind: "disconnected" }
+      : { kind: "invalid", reason: "config.json is missing or unreadable" };
+  }
+  const hasClient = Object.hasOwn(raw, "client") && raw.client !== undefined;
+  const role = raw.runtimeRole;
+  if (role !== undefined && role !== "standalone" && role !== "hub" && role !== "client") {
+    return { kind: "invalid", reason: "config.json.runtimeRole is invalid" };
+  }
+  if (!hasClient && (role === undefined || role === "standalone")) return { kind: "disconnected" };
+  // A hub is a server role, not a broken client: without client state it simply is not
+  // connected, and refusing here blocked `ocx start` on every hub (found on the first
+  // clisu-oracle dogfood boot). Hub role WITH client state remains mismatched below.
+  if (!hasClient && role === "hub") return { kind: "disconnected" };
+  if (!hasClient || role !== "client") {
+    return {
+      kind: "mismatched",
+      reason: hasClient
+        ? "config.json.client is present without runtimeRole=client"
+        : "runtimeRole=client is present without config.json.client",
+    };
+  }
+  const client = diagnostics.config.client;
+  if (!client) {
+    const warning = diagnostics.warnings?.find(value => value.startsWith("client"));
+    return { kind: "invalid", reason: warning ?? "config.json.client is malformed" };
+  }
+  return { kind: "connected", value: client };
+}
+
+/**
+ * Does the persisted config record a rotation that has not finished?
+ *
+ * Read fresh rather than taken from a caller-supplied snapshot: the whole point is to see a
+ * `pendingOperation` that landed after that snapshot was taken.
+ */
+function rotationInFlight(): boolean {
+  const current = readClientConnectionState();
+  return current.kind === "connected" && current.value.pendingOperation !== undefined;
+}
+
+export function inspectClientRotationRecoveryGate(
+  state: ClientConnectionState = readClientConnectionState(),
+): ClientRotationRecoveryGate {
+  const current = readServiceApiTokenState();
+  const backup = readTokenBackupState();
+  if (state.kind === "connected" && state.value.pendingOperation) {
+    if (current.kind !== "present" || backup.kind !== "present") {
+      return {
+        kind: "unsafe",
+        reason: "pending key rotation requires owner-only service-api-token and service-api-token.prev files",
+      };
+    }
+    return {
+      kind: "recovery-required",
+      reason: "rerun ocx connect rotate with --pairing-code-stdin or --admin-token-stdin",
+    };
+  }
+  if (backup.kind === "unsafe") return { kind: "unsafe", reason: backup.reason };
+  if (backup.kind === "present" && current.kind === "present") {
+    // Only an ORPHAN backup is cleanable, and this branch cannot always tell an orphan from
+    // a backup belonging to a rotation that is mid-flight.
+    //
+    // `rotateConnectedClientKey` writes the .prev backup BEFORE it persists
+    // `pendingOperation`. A concurrent `ocx connect status` landing in that window sees
+    // "backup present, token present, no pending marker" — indistinguishable from a stale
+    // leftover — and deleted the live rollback target. If the rotation then failed, its
+    // restore had nothing to restore from.
+    //
+    // Re-reading the persisted state closes most of the window: the caller's `state` may
+    // have been captured before the marker landed, while a fresh read sees it. The
+    // remaining window is narrow enough that the rotation's own lock is the right owner,
+    // and deleting nothing is the safe side of it.
+    if (rotationInFlight()) {
+      return { kind: "recovery-required", reason: "a key rotation is in flight; leave service-api-token.prev in place" };
+    }
+    try {
+      removeOrphanTokenBackup();
+      return { kind: "orphan-cleaned" };
+    } catch (error) {
+      return { kind: "unsafe", reason: error instanceof Error ? error.message : "token backup cleanup failed" };
+    }
+  }
+  return { kind: "clean" };
+}
+
+export function commitClientConnection(
+
+  state: OcxClientConnectionConfig,
+): "committed" | "unchanged" {
+  const outcome = mutatePersistedConfig(config => {
+    const unchanged = config.runtimeRole === "client"
+      && JSON.stringify(config.client) === JSON.stringify(state);
+    if (!unchanged) {
+      config.runtimeRole = "client";
+      config.client = structuredClone(state);
+    }
+    return { changed: !unchanged, value: undefined };
+  });
+  if (outcome.status === "committed" || outcome.status === "unchanged") return outcome.status;
+  if (outcome.status === "unavailable" && outcome.reason === "missing") {
+    // First ocx run on a fresh machine: ocx connect is the expected first command in
+    // client mode, so there is no config.json yet. mutatePersistedConfig correctly
+    // refuses to invent one (a lost config must fail closed), but a genuinely absent
+    // file is the bootstrap case, not corruption — seed defaults plus the client
+    // block atomically. Found on the first MacBook↔oracle dogfood connect.
+    const seeded = getDefaultConfig();
+    seeded.runtimeRole = "client";
+    seeded.client = structuredClone(state);
+    saveConfig(seeded);
+    return "committed";
+  }
+  throw new Error(`client state commit unavailable: ${"reason" in outcome ? outcome.reason : "unknown"}`);
+}
+
+export function clearClientConnection(
+  expectedApiKeyId: string,
+): "committed" | "absent" | "conflict" {
+  const outcome = mutatePersistedConfig(config => {
+    if (!config.client && config.runtimeRole !== "client") {
+      return { changed: false, value: "absent" as const };
+    }
+    if (!config.client || config.runtimeRole !== "client" || config.client.apiKeyId !== expectedApiKeyId) {
+      return { changed: false, value: "conflict" as const };
+    }
+    deleteConfigTopLevelKey(config, "client");
+    deleteConfigTopLevelKey(config, "runtimeRole");
+    return { changed: true, value: "committed" as const };
+  });
+  if (outcome.status === "unavailable") return "conflict";
+  return outcome.value;
+}

package/src/clients/config-export.ts

@@ -1034,10 +1034,15 @@ export interface HermesProviderBlock {
   api_mode: "chat_completions";
   /** We supply the list, so skip their live `/models` probe. */
   discover_models: false;
-  models: string[];
+  models: Record<string, HermesModelEntry>;
   extra_headers?: Record<string, string>;
 }
 
+/** Capability metadata Hermes cannot discover for a custom local provider. */
+export interface HermesModelEntry {
+  supports_vision?: boolean;
+}
+
 export interface HermesGeneratedConfig {
   providers: Record<string, HermesProviderBlock>;
 }
@@ -1311,7 +1316,13 @@ function proxyAdmissionHeaders(config: OcxConfig | undefined, envRef: string): R
 }
 
 function buildHermesClientConfig(ctx: ExportContext): HermesGeneratedConfig {
-  const models = normalizeExportModels(ctx.models).map(model => model.namespaced);
+  const models: Record<string, HermesModelEntry> = {};
+  for (const model of normalizeExportModels(ctx.models)) {
+    const declared = model.inputModalities;
+    models[model.namespaced] = declared && declared.length > 0
+      ? { supports_vision: declared.includes("image") }
+      : {};
+  }
   const headers = proxyAdmissionHeaders(ctx.config, HERMES_API_KEY_ENV_REF);
   return {
     providers: {
@@ -1606,9 +1617,9 @@ function summarizeOmp(document: unknown): { modelCount: number; modelsWithoutLim
 }
 
 function summarizeHermes(document: unknown): { modelCount: number; modelsWithoutLimits: number } {
-  const models = (document as HermesGeneratedConfig | undefined)?.providers?.[OPENCODE_PROVIDER_ID]?.models ?? [];
-  // Hermes carries selectors only; it has no per-model limit to be missing.
-  return { modelCount: models.length, modelsWithoutLimits: 0 };
+  const models = (document as HermesGeneratedConfig | undefined)?.providers?.[OPENCODE_PROVIDER_ID]?.models ?? {};
+  // Hermes carries capability metadata but no per-model limit to be missing.
+  return { modelCount: Object.keys(models).length, modelsWithoutLimits: 0 };
 }
 
 function summarizeOpenclaw(document: unknown): { modelCount: number; modelsWithoutLimits: number } {

package/src/codex/auth-api.ts

@@ -389,6 +389,49 @@ function safeResetCreditConsumeDto(input: unknown): { code: string } {
   return { code: typeof obj.code === "string" ? obj.code : "unknown" };
 }
 
+/**
+ * Background reset-credit access for the auto-redeemer (#822). Goes through the same
+ * account/lease wrapper as the management routes, but takes a caller-owned
+ * `redeem_request_id` so a journaled id can be replayed idempotently after a crash.
+ * Throws on any auth or upstream failure; the caller treats a throw on consume as ambiguous.
+ */
+export function createResetCreditWhamClient(config: OcxConfig, accountId: string): {
+  inspect: () => Promise<{ credits: { granted_at: string; expires_at: string }[] }>;
+  consume: (redeemRequestId: string) => Promise<{ code: string }>;
+} {
+  const run = async <T>(operation: (auth: ResetCreditAuth) => Promise<T>): Promise<T> => {
+    const result = await withResetCreditAuth(getRuntimeConfig(config), accountId, operation);
+    if (result.ok) return result.value;
+    throw new Error(`reset-credit auth unavailable (${result.response.status})`);
+  };
+  return {
+    inspect: () => run(async auth => {
+      const resp = await fetch("https://chatgpt.com/backend-api/wham/rate-limit-reset-credits", {
+        headers: { Authorization: `Bearer ${auth.accessToken}`, "ChatGPT-Account-Id": auth.chatgptAccountId },
+        signal: AbortSignal.timeout(8000),
+      });
+      if (!resp.ok) { await resp.body?.cancel().catch(() => {}); throw new Error(`upstream ${resp.status}`); }
+      const parsed = await readResetCreditJson(resp, AbortSignal.timeout(8000));
+      if (!parsed.ok) throw new Error("invalid upstream reset-credit response");
+      return { credits: safeResetCreditsDto(parsed.value).credits };
+    }),
+    consume: redeemRequestId => run(async auth => {
+      const resp = await fetch("https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${auth.accessToken}`,
+          "ChatGPT-Account-Id": auth.chatgptAccountId,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ redeem_request_id: redeemRequestId }),
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (!resp.ok) { await resp.body?.cancel().catch(() => {}); throw new Error(`upstream ${resp.status}`); }
+      return safeResetCreditConsumeDto(await resp.json());
+    }),
+  };
+}
+
 type ResetCreditJsonRead =
   | { ok: true; value: unknown }
   | { ok: false };
@@ -843,6 +886,23 @@ interface PoolQuotaResult {
   /** Present only when this call's WHAM response included `rate_limit_reset_credits.available_count`. */
   freshResetCredits?: number;
   quotaProbeSkipped?: true;
+  /** Positive evidence captured immediately before an upstream WHAM dispatch. */
+  quotaProbeAttempted?: { at: number; credentialGeneration: number };
+}
+
+interface PoolQuotaProbeEvidence {
+  attempted?: NonNullable<PoolQuotaResult["quotaProbeAttempted"]>;
+}
+
+function markQuotaProbeAttempted(evidence: PoolQuotaProbeEvidence, credentialGeneration: number): void {
+  evidence.attempted = { at: Date.now(), credentialGeneration };
+}
+
+function withQuotaProbeEvidence(
+  result: PoolQuotaResult,
+  evidence: PoolQuotaProbeEvidence,
+): PoolQuotaResult {
+  return evidence.attempted ? { ...result, quotaProbeAttempted: evidence.attempted } : result;
 }
 
 interface PoolQuotaRefreshFlight {
@@ -988,6 +1048,7 @@ async function recoverPoolQuotaFrom401(ctx: {
   rejectedAccessToken: string;
   rejectedGeneration: number;
   resp: Response;
+  quotaProbeEvidence: PoolQuotaProbeEvidence;
   onCredentialGeneration?: (generation: number) => void;
 }): Promise<PoolQuotaResult> {
   const { accountId, existing, configuredPlan, rejectedAccessToken, rejectedGeneration, resp } = ctx;
@@ -1061,6 +1122,7 @@ async function recoverPoolQuotaFrom401(ctx: {
   ctx.onCredentialGeneration?.(refreshed.generation);
 
   const writerGeneration = captureConfigGeneration();
+  markQuotaProbeAttempted(ctx.quotaProbeEvidence, refreshed.generation);
   const replay = await fetch("https://chatgpt.com/backend-api/wham/usage", {
     headers: {
       Authorization: `Bearer ${refreshed.accessToken}`,
@@ -1147,57 +1209,75 @@ async function fetchFreshPoolAccountQuota(
   existing: StoredAccountQuota | null,
   configuredPlan?: string,
   onCredentialGeneration?: (generation: number) => void,
+  getValidToken: typeof getValidCodexToken = getValidCodexToken,
 ): Promise<PoolQuotaResult> {
   const writerGeneration = captureConfigGeneration();
   let requestCredentialGeneration = readCodexAccountRecord(accountId)?.generation;
+  const quotaProbeEvidence: PoolQuotaProbeEvidence = {};
   try {
-    const { accessToken, chatgptAccountId, generation } = await getValidCodexToken(accountId);
+    const { accessToken, chatgptAccountId, generation } = await getValidToken(accountId);
     requestCredentialGeneration = generation;
     onCredentialGeneration?.(generation);
+    markQuotaProbeAttempted(quotaProbeEvidence, generation);
     const resp = await fetch("https://chatgpt.com/backend-api/wham/usage", {
       headers: { Authorization: `Bearer ${accessToken}`, "ChatGPT-Account-Id": chatgptAccountId },
       signal: AbortSignal.timeout(8000),
     });
     if (!resp.ok) {
       if (resp.status !== 401) {
-        return { quota: existing ?? null, needsReauth: false, credentialGeneration: generation };
+        return withQuotaProbeEvidence(
+          { quota: existing ?? null, needsReauth: false, credentialGeneration: generation },
+          quotaProbeEvidence,
+        );
       }
       // A bare 401 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
       // (#3019). Refresh once, replay once, and only then decide.
-      return await recoverPoolQuotaFrom401({
+      const recovered = await recoverPoolQuotaFrom401({
         accountId,
         existing,
         configuredPlan,
         rejectedAccessToken: accessToken,
         rejectedGeneration: generation,
         resp,
+        quotaProbeEvidence,
         onCredentialGeneration,
       });
+      return withQuotaProbeEvidence(recovered, quotaProbeEvidence);
     }
-    return await commitPoolQuotaResponse(resp, {
+    const committed = await commitPoolQuotaResponse(resp, {
       accountId, existing, configuredPlan, generation, writerGeneration,
     });
+    return withQuotaProbeEvidence(committed, quotaProbeEvidence);
   } catch (e) {
     if (e instanceof CodexCredentialGenerationConflictError || e instanceof CodexCredentialRefreshLockTimeoutError
       || e instanceof CodexCredentialRefreshBusyError || e instanceof CodexCredentialRefreshStaleError) {
-      return {
+      return withQuotaProbeEvidence({
         quota: existing ?? null,
         needsReauth: false,
         credentialGeneration: requestCredentialGeneration,
-        ...(e instanceof CodexCredentialRefreshBusyError || e instanceof CodexCredentialRefreshStaleError
-          ? { quotaProbeSkipped: true as const }
-          : {}),
-      };
+        quotaProbeSkipped: true,
+      }, quotaProbeEvidence);
     }
     if (e instanceof TokenRefreshError) {
-      return { quota: existing ?? null, needsReauth: true, credentialGeneration: requestCredentialGeneration };
+      return withQuotaProbeEvidence(
+        { quota: existing ?? null, needsReauth: true, credentialGeneration: requestCredentialGeneration },
+        quotaProbeEvidence,
+      );
     }
-    return { quota: existing ?? null, needsReauth: false, credentialGeneration: requestCredentialGeneration };
+    return withQuotaProbeEvidence(
+      { quota: existing ?? null, needsReauth: false, credentialGeneration: requestCredentialGeneration },
+      quotaProbeEvidence,
+    );
   }
 }
 
-async function fetchPoolAccountQuota(accountId: string, forceRefresh = false, configuredPlan?: string): Promise<PoolQuotaResult> {
+async function fetchPoolAccountQuota(
+  accountId: string,
+  forceRefresh = false,
+  configuredPlan?: string,
+  getValidToken: typeof getValidCodexToken = getValidCodexToken,
+): Promise<PoolQuotaResult> {
   const existing = getAccountQuota(accountId);
   if (!forceRefresh && existing && Date.now() - existing.updatedAt < POOL_CACHE_TTL) {
     return {
@@ -1227,6 +1307,7 @@ async function fetchPoolAccountQuota(accountId: string, forceRefresh = false, co
     existing,
     configuredPlan,
     generation => { state.resolvedCredentialGeneration = generation; },
+    getValidToken,
   );
   const flight: PoolQuotaRefreshFlight = { state, promise: refresh };
   const activeFlights = flights ?? new Set<PoolQuotaRefreshFlight>();
@@ -1243,6 +1324,16 @@ async function fetchPoolAccountQuota(accountId: string, forceRefresh = false, co
 }
 
 let primeInFlight: Promise<void> | null = null;
+/**
+ * Last prime attempt per pool account. A failed WHAM lookup stores no quota, so
+ * without this the account stays "unknown" and every later prime trigger re-selects
+ * it as stale and repeats the same failing request. Successful lookups are already
+ * throttled by their stored updatedAt; this gives failures the same TTL backoff.
+ *
+ * Keyed by credential generation so a re-authentication, refresh, or account removal
+ * retries immediately instead of waiting out a backoff earned by the old credential.
+ */
+const poolQuotaPrimeAttemptedAt = new Map<string, { generation: number; at: number }>();
 let cooldownRecoveryInFlight: Promise<void> | null = null;
 
 export async function runCodexCooldownRecoveryProbes(config: OcxConfig, now = Date.now()): Promise<void> {
@@ -1294,6 +1385,19 @@ export interface PrimeCodexPoolQuotasOptions {
   fetchMainInfo?: typeof fetchMainAccountInfo;
 }
 
+let getValidPoolTokenForPrime = getValidCodexToken;
+
+/** Test-only: inject a deterministic pre-dispatch credential outcome for quota priming. */
+export function setCodexPoolQuotaTokenResolverForTests(
+  resolver: typeof getValidCodexToken,
+): () => void {
+  const previous = getValidPoolTokenForPrime;
+  getValidPoolTokenForPrime = resolver;
+  return () => {
+    if (getValidPoolTokenForPrime === resolver) getValidPoolTokenForPrime = previous;
+  };
+}
+
 function tryAcquireNativeMainPrimeLease(): AdmissionLease | null {
   return tryAcquireNativeMainProfileClaim();
 }
@@ -1319,6 +1423,16 @@ export async function primeCodexPoolQuotas(
   options: PrimeCodexPoolQuotasOptions = {},
 ): Promise<void> {
   const openai = config.providers[OPENAI_CODEX_PROVIDER_ID];
+  // Prune attempt markers for accounts that no longer exist BEFORE the eligibility
+  // return. A removal that happens while the provider is disabled or out of pool mode
+  // would otherwise leave a stale failure marker behind; restoring the same account id
+  // within POOL_CACHE_TTL would then read that old failure as current and skip the
+  // retry the restored credential is entitled to.
+  const runtimeConfig = getRuntimeConfig(config);
+  const configuredPoolIds = new Set((runtimeConfig.codexAccounts ?? []).map(account => account.id));
+  for (const accountId of poolQuotaPrimeAttemptedAt.keys()) {
+    if (!configuredPoolIds.has(accountId)) poolQuotaPrimeAttemptedAt.delete(accountId);
+  }
   if (
     !openai
     || openai.disabled === true
@@ -1327,11 +1441,18 @@ export async function primeCodexPoolQuotas(
   ) return;
   if (primeInFlight) return primeInFlight;
   primeInFlight = (async () => {
-    const runtimeConfig = getRuntimeConfig(config);
     const pool = (runtimeConfig.codexAccounts ?? []).filter(isSelectableCodexPoolAccount);
     const stale = pool.filter(a => {
       const q = getAccountQuota(a.id);
-      return !q || Date.now() - q.updatedAt >= POOL_CACHE_TTL;
+      if (q) return Date.now() - q.updatedAt >= POOL_CACHE_TTL;
+      // No stored quota: either never primed, or the last attempt failed. Retry only
+      // once per TTL window so an unreachable or rejecting account cannot turn every
+      // prime trigger into another upstream request.
+      const lastAttempt = poolQuotaPrimeAttemptedAt.get(a.id);
+      if (!lastAttempt) return true;
+      // A newer credential invalidates the previous failure: retry without waiting.
+      if (lastAttempt.generation !== readCodexAccountRecord(a.id)?.generation) return true;
+      return Date.now() - lastAttempt.at >= POOL_CACHE_TTL;
     });
     const primeMain = async () => {
       const mainLease = tryAcquireNativeMainPrimeLease();
@@ -1359,7 +1480,31 @@ export async function primeCodexPoolQuotas(
         primeMain(),
         mapWithConcurrency(stale, POOL_QUOTA_REFRESH_CONCURRENCY, async a => {
           if (!getCodexAccountCredential(a.id)) return;
-          await fetchPoolAccountQuota(a.id, false, a.plan);
+          let result: PoolQuotaResult;
+          try {
+            result = await fetchPoolAccountQuota(a.id, false, a.plan, getValidPoolTokenForPrime);
+          } catch (error) {
+            // Local quota-flight saturation proves no WHAM request existed for this account.
+            // Consume it per item so sibling workers remain inside the shared prime lifetime.
+            if (error instanceof PoolQuotaProbeBusyError) return;
+            throw error;
+          }
+          // Only the data-plane function knows whether upstream dispatch began. Any
+          // cache hit, credential deferral, or local admission failure remains eligible.
+          const attempted = result.quotaProbeAttempted;
+          if (!attempted) return;
+          if (!configuredPoolAccount(getRuntimeConfig(config), a.id)) {
+            poolQuotaPrimeAttemptedAt.delete(a.id);
+            return;
+          }
+          poolQuotaPrimeAttemptedAt.set(a.id, {
+            // getValidCodexToken may rotate the credential before WHAM is sent.
+            // Bind the backoff to the generation that actually made the request;
+            // otherwise the next prime sees a false generation change and retries
+            // the same failed WHAM call immediately.
+            generation: attempted.credentialGeneration,
+            at: attempted.at,
+          });
         }),
       ]);
     } catch {
@@ -1376,6 +1521,15 @@ export async function primeCodexPoolQuotas(
  * from another suite cannot coalesce into the next prime. */
 export function clearCodexQuotaPrimeState(): void {
   primeInFlight = null;
+  poolQuotaPrimeAttemptedAt.clear();
+  getValidPoolTokenForPrime = getValidCodexToken;
+}
+
+/** Test-only: drop the shared single-flight promise while keeping the per-account
+ * failure backoff, so a test can trigger a second real prime pass and still observe
+ * the throttle a production caller would see. */
+export function clearCodexQuotaPrimeSingleFlightForTests(): void {
+  primeInFlight = null;
 }
 
 /** Test-only reset for the worker-level single-flight. */