@bitkyc08/opencodex 2.78.0 → 2.79.0

package/src/cli/ensure-readiness.ts

@@ -0,0 +1,48 @@
+/**
+ * Readiness wait for a proxy this process just asked to start.
+ *
+ * ocx ensure spawns a detached ocx start and returns once this home's proxy answers.
+ * It used to give up after a flat 8 s. A cold start can take longer than that on a
+ * busy Windows host (Windows CI measured 10-45 s for the first proxy child of a
+ * batch), so ensure reported "did not become healthy" for a proxy that came up
+ * moments later, and the Codex shim or autostart that called it saw a failure.
+ *
+ * The wait is now as long as the service start's follow-up (40 s) while the
+ * spawned child is alive. A child that has exited keeps the old 8 s bound, so a
+ * start that failed outright is reported no later than before.
+ */
+
+export const ENSURE_READY_TIMEOUT_MS = 40_000;
+export const ENSURE_EXITED_CHILD_TIMEOUT_MS = 8_000;
+const POLL_MS = 150;
+
+export interface LiveProxyWaitOptions<T> {
+  find: () => Promise<T | null>;
+  timeoutMs: number;
+  /** Return false to stop polling early; one observation is always made first. */
+  keepWaiting?: () => boolean;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export async function waitForLiveProxy<T>(options: LiveProxyWaitOptions<T>): Promise<T | null> {
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
+  const deadline = now() + options.timeoutMs;
+  while (now() < deadline) {
+    const live = await options.find();
+    if (live) return live;
+    if (options.keepWaiting && !options.keepWaiting()) return null;
+    await sleep(POLL_MS);
+  }
+  return null;
+}
+
+/** Keep waiting while the spawned child lives; once it exits, only inside the old 8 s bound. */
+export function ensureKeepWaiting(
+  spawnedAt: number,
+  childExited: () => boolean,
+  now: () => number = Date.now,
+): () => boolean {
+  return () => !childExited() || now() - spawnedAt < ENSURE_EXITED_CHILD_TIMEOUT_MS;
+}

package/src/cli/gui-pair-client.ts

@@ -1,5 +1,6 @@
 import { readRuntimePort, type RuntimePortState } from "../config/process-state";
 import { timingSafeEqual } from "node:crypto";
+import { createGuiPairIntent, GUI_PAIR_INTENT_HEADER, type GuiPairIntent } from "../lib/gui-pair-intent";
 import {
   LOCAL_ATTESTATION_CHALLENGE_HEADER,
   LOCAL_ATTESTATION_PROOF_HEADER,
@@ -30,7 +31,7 @@ import {
 
 export type GuiPairRequestResult =
   | { kind: "created"; grant: string; browserOrigin: string; serverOrigin: string; expiresAt: number }
-  | { kind: "unavailable"; reason: "unattested-target" | "runtime-mismatch" | "attestation" | "capability" | "transport" | "rejected" };
+  | { kind: "unavailable"; reason: "unattested-target" | "runtime-mismatch" | "attestation" | "capability" | "transport" | "rejected" | "local-intent" };
 
 export interface GuiPairClientDeps {
   fetchImpl?: typeof fetch;
@@ -38,6 +39,9 @@ export interface GuiPairClientDeps {
   createChallenge?: () => string;
   now?: () => number;
   timeoutMs?: number;
+  /** Hub invitation policy is unchanged; standalone commands require local write intent. */
+  requireLocalIntent?: boolean;
+  createIntent?: typeof createGuiPairIntent;
 }
 
 const GUI_PAIR_REQUEST_TIMEOUT_MS = 10_000;
@@ -136,9 +140,12 @@ export async function requestBoundGuiPairingGrant(
     expiresAt,
   );
   if (!capability) return { kind: "unavailable", reason: "capability" };
-  let response: Response;
+  let intent: GuiPairIntent | undefined;
   try {
-    response = await fetchImpl(`${baseUrl}${GUI_PAIR_PATH}`, {
+    if (deps.requireLocalIntent !== false) intent = (deps.createIntent ?? createGuiPairIntent)(capability);
+  } catch { return { kind: "unavailable", reason: "local-intent" }; }
+  try {
+    const response = await fetchImpl(`${baseUrl}${GUI_PAIR_PATH}`, {
       method: GUI_PAIR_METHOD,
       headers: {
         "Content-Length": "0",
@@ -147,13 +154,14 @@ export async function requestBoundGuiPairingGrant(
         [GUI_PAIR_EXPIRES_AT_HEADER]: String(expiresAt),
         [GUI_PAIR_BROWSER_ORIGIN_HEADER]: browserOrigin,
         [GUI_PAIR_CAPABILITY_HEADER]: capability,
+        ...(intent ? { [GUI_PAIR_INTENT_HEADER]: intent.proof } : {}),
       },
       signal: AbortSignal.timeout(timeoutMs),
     });
+    if (!response.ok) return { kind: "unavailable", reason: "rejected" };
+    const result = parseCreatedResult(await response.json().catch(() => null), browserOrigin);
+    return result ?? { kind: "unavailable", reason: "rejected" };
   } catch {
     return { kind: "unavailable", reason: "transport" };
-  }
-  if (!response.ok) return { kind: "unavailable", reason: "rejected" };
-  const result = parseCreatedResult(await response.json().catch(() => null), browserOrigin);
-  return result ?? { kind: "unavailable", reason: "rejected" };
+  } finally { intent?.dispose(); }
 }

package/src/cli/gui.ts

@@ -77,9 +77,12 @@ export async function runGuiCommand(args: string[], deps: GuiCommandDeps): Promi
   }
   const result = await (deps.requestPairingGrant ?? requestBoundGuiPairingGrant)(target, canonicalOrigin, {
     ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
+    requireLocalIntent: config.runtimeRole !== "hub",
   });
   if (result.kind !== "created") {
-    console.error(`GUI pairing failed (${result.reason}).`);
+    console.error(result.reason === "local-intent"
+      ? "GUI pairing requires write access to the private OpenCodex home; no code was issued."
+      : `GUI pairing failed (${result.reason}).`);
     return 1;
   }
   if (parsed.json) {

package/src/cli/hub.ts

@@ -328,6 +328,7 @@ async function runInvite(args: string[], deps: HubCommandDeps): Promise<number>
   const dataUrl = resolved.dataUrl;
   const result = await (deps.requestPairingGrant ?? requestBoundGuiPairingGrant)(target, browserOrigin, {
     ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
+    requireLocalIntent: false,
   });
   if (result.kind !== "created") {
     console.error(`Minting a pairing code failed (${result.reason}).`);

package/src/cli/index.ts

@@ -152,6 +152,7 @@ import {
   grokSyncFailureMessage,
   reconcileEnsureDesiredIntegrations,
 } from "./ensure-desired-integrations";
+import { ENSURE_READY_TIMEOUT_MS, ensureKeepWaiting, waitForLiveProxy } from "./ensure-readiness";
 import { refreshOwnedCatalogIntegrations } from "../integrations/catalog-refresh";
 import { loadExportModels } from "../server/management/model-rows";
 
@@ -235,16 +236,10 @@ function parseStartCliOptions(): ReturnType<typeof parseStartOptions> {
   }
 }
 
-async function waitForProxy(timeoutMs = 8_000): Promise<LiveProxy | null> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    // Runtime-state-first with identity: finds the proxy even when it started on a
-    // fallback port, and never mistakes a foreign 200 for our proxy.
-    const live = await findLiveProxy();
-    if (live) return live;
-    await new Promise(resolve => setTimeout(resolve, 150));
-  }
-  return null;
+async function waitForProxy(timeoutMs = 8_000, keepWaiting?: () => boolean): Promise<LiveProxy | null> {
+  // Runtime-state-first with identity: finds the proxy even when it started on a
+  // fallback port, and never mistakes a foreign 200 for our proxy.
+  return waitForLiveProxy({ find: findLiveProxy, timeoutMs, keepWaiting });
 }
 
 class StartCommandExit extends Error {
@@ -846,9 +841,13 @@ async function handleEnsure(options: { existingIsSuccess?: boolean; forceStart?:
     env: detachedStartEnvironment(),
   });
   options.onSpawn?.(child);
+  const spawnedAt = Date.now();
+  let childExited = false;
+  child.once("exit", () => { childExited = true; });
   child.unref();
 
-  const port = (await waitForProxy())?.port;
+  // A cold start can outlast 8 s on a busy Windows host; see ensure-readiness.ts.
+  const port = (await waitForProxy(ENSURE_READY_TIMEOUT_MS, ensureKeepWaiting(spawnedAt, () => childExited)))?.port;
   if (!port) {
     console.error("❌ Proxy did not become healthy after starting.");
     process.exitCode = 1;

package/src/cli/status.ts

@@ -7,7 +7,7 @@ import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../cod
 import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import { diagnoseService, serviceLogPath } from "../service";
-import { collectStartupHealth, type StartupHealth } from "../codex/autostart-health";
+import { collectStartupHealth, startupHealthReadBudgetMs, type StartupHealth } from "../codex/autostart-health";
 import { getCodexRoutingKind } from "../codex/inject";
 import { missingOwnedCatalogPath } from "../codex/inject/config-toml";
 import { CODEX_CONFIG_PATH } from "../codex/paths";
@@ -251,7 +251,7 @@ export async function fetchLiveStartupHealth(
   deps: Parameters<typeof fetchBoundLocalManagementRead>[2] = {},
 ): Promise<StartupHealth | null> {
   const result = await fetchBoundLocalManagementRead(
-    live, LOCAL_MANAGEMENT_READ_PATHS.startupHealth, { timeoutMs: 1_500, ...deps, requireResponseProof: true },
+    live, LOCAL_MANAGEMENT_READ_PATHS.startupHealth, { timeoutMs: startupHealthReadBudgetMs(), ...deps, requireResponseProof: true },
   );
   if (result.kind !== "response" || !result.response.ok) return null;
   let payload: unknown;

package/src/cli/update-restart-child.ts

@@ -18,8 +18,11 @@ function parseMarker(raw: string): UpdateRestartChildMarker {
     || value.version === "0.0.0" || !parseStrictSemver(value.version) || !value.home
     || !Number.isSafeInteger(value.home.revision)) throw new Error("update_restart_child_marker_invalid");
   for (const directory of [value.home.config, value.home.codex]) {
+    // Windows reports 64-bit NTFS file ids (MFT sequence in the high 16 bits) as doubles above
+    // 2^53. Parent and child read them through the same stat API, so any finite integer is a
+    // faithful identity token; assertUpdateRestartHome still compares path, dev and ino exactly.
     if (!directory || typeof directory.path !== "string" || !directory.path
-      || !Number.isSafeInteger(directory.dev) || !Number.isSafeInteger(directory.ino)) {
+      || !Number.isInteger(directory.dev) || !Number.isInteger(directory.ino)) {
       throw new Error("update_restart_child_marker_invalid");
     }
   }

package/src/codex/account-credit-use.ts

@@ -3,6 +3,7 @@ import { deleteConfigTopLevelKey } from "../config/rebase-provenance";
 import { isThirtyDayOnlyCodexPlan } from "./plan";
 import {
   CODEX_EXHAUSTED_USAGE_PERCENT,
+  TERMINAL_SHORT_WINDOW_FRESHNESS_MS,
   isTerminalShortWindow,
   hasSpendableCodexCredits,
   resetAtToMs,
@@ -73,8 +74,13 @@ export function codexUsageLimitResetAt(quota: StoredAccountQuota | null, plan: u
   if (!quota) return undefined;
   const full: number[] = [];
   if (isTerminalShortWindow(quota, now)) {
-    // A reset-less burst reading counts while it is fresh, so there is no instant to report.
-    full.push(typeof quota.shortResetAt === "number" && quota.shortResetAt > 0 ? resetAtToMs(quota.shortResetAt) : now);
+    // A reset-less burst reading holds until its observation goes stale: the freshness horizon
+    // is the deadline a retried request still meets, so report it rather than `now` (which
+    // collapsed the refusal's Retry-After to 1s against an account blocked for minutes).
+    // `isTerminalShortWindow` guarantees `shortObservedAt` is finite on this branch.
+    full.push(typeof quota.shortResetAt === "number" && quota.shortResetAt > 0
+      ? resetAtToMs(quota.shortResetAt)
+      : (quota.shortObservedAt ?? now) + TERMINAL_SHORT_WINDOW_FRESHNESS_MS);
   }
   const longWindows: Array<[number | undefined, number | undefined]> = isThirtyDayOnlyCodexPlan(plan)
     ? [[quota.monthlyPercent, quota.monthlyResetAt]]

package/src/codex/auth-api/account-pause-group.ts

@@ -0,0 +1,113 @@
+import { lstatSync } from "node:fs";
+import type { OcxConfig } from "../../types";
+import { inspectChatGptDomainClaim, extractEmail } from "../../oauth/chatgpt";
+import { MAIN_CODEX_ACCOUNT_ID, isSelectableCodexPoolAccount } from "../account-id";
+import { readCodexTokensResult } from "../auth-collision";
+import type { CodexTokenReadResult } from "../auth-collision";
+import { getCodexAccountCredential } from "../account-store";
+import { resolveCodexHomeDir } from "../home";
+import { tryAcquireNativeMainProfileClaim } from "../native-main-admission";
+import { withNativeMainSharedClaim } from "../native-main-claim";
+import { MAX_AUTH_BYTES, readBounded, resolveNativeProfileContext } from "../native-profile-store";
+import { NativeProfileError } from "../native-profile-types";
+import { isNativeMainClaimUnavailable, nativeMainProfileBusyResponse } from "./http";
+
+type AccountIdentity = { accountId: string; email: string };
+type MainAuth = CodexTokenReadResult | { status: "api-key-only" };
+
+/** A valid API-key login has no ChatGPT identity; anything else unreadable stays unknown. */
+function readMainAuth(authPath: string): MainAuth {
+  const main = readCodexTokensResult(authPath, { bounded: true });
+  if (main.status !== "invalid") return main;
+  try {
+    const j: unknown = JSON.parse(readBounded(authPath, MAX_AUTH_BYTES).toString("utf-8"));
+    if (j === null || typeof j !== "object" || Array.isArray(j)) return main;
+    const envelope = j as { auth_mode?: unknown; OPENAI_API_KEY?: unknown; tokens?: unknown };
+    const apiKeyOnly = envelope.tokens == null
+      && (envelope.auth_mode === undefined || envelope.auth_mode === "api_key")
+      && typeof envelope.OPENAI_API_KEY === "string" && envelope.OPENAI_API_KEY.trim() !== "";
+    return apiKeyOnly ? { status: "api-key-only" } : main;
+  } catch {
+    return main;
+  }
+}
+
+function identity(accountId: unknown, email: unknown): AccountIdentity | undefined {
+  const normalizedEmail = typeof email === "string" ? email.trim().toLowerCase() : undefined;
+  return typeof accountId === "string" && accountId.trim() && normalizedEmail
+    ? { accountId: accountId.trim(), email: normalizedEmail }
+    : undefined;
+}
+
+/** Resolve only existing entries, under native-main ownership, never on the request path. */
+function linkedAccountIds(config: OcxConfig, selectedId: string, main: MainAuth): string[] | undefined {
+  // Unknown main identity must not produce a successful but incomplete pause.
+  if (main.status === "unreadable" || main.status === "invalid") return undefined;
+  const identities = new Map<string, AccountIdentity | undefined>();
+  if (main.status === "ok") {
+    const tokens = main.tokens;
+    if (typeof tokens.access_token !== "string" || typeof tokens.account_id !== "string"
+      || (tokens.id_token !== undefined && typeof tokens.id_token !== "string")) return undefined;
+    const claims = [tokens.id_token, tokens.access_token]
+      .filter((token): token is string => typeof token === "string")
+      .map(inspectChatGptDomainClaim);
+    if (claims.some(claim => claim.kind === "invalid")) return undefined;
+    const claimIds = claims.flatMap(claim => claim.kind === "valid" ? [claim.accountId] : []);
+    // organizations[] describes memberships, not the selected workspace. Never use its first row.
+    const accountId = tokens.account_id.trim() || claimIds[0];
+    if (claimIds.some(claim => claim !== accountId)) return undefined;
+    // Both tokens must name the same member; otherwise the bearer's identity is unknown.
+    const emails = new Set([extractEmail(tokens.id_token), extractEmail(undefined, tokens.access_token)]
+      .flatMap(email => email?.trim() ? [email.trim().toLowerCase()] : []));
+    if (emails.size > 1) return undefined;
+    identities.set(MAIN_CODEX_ACCOUNT_ID, identity(accountId, [...emails][0]));
+  }
+  for (const account of config.codexAccounts ?? []) {
+    if (!isSelectableCodexPoolAccount(account)) continue;
+    const credential = getCodexAccountCredential(account.id);
+    identities.set(account.id, identity(credential?.chatgptAccountId, account.email));
+  }
+  const selected = identities.get(selectedId);
+  // Missing identity evidence never links unrelated logins, including members of one workspace.
+  if (!selected) return [selectedId];
+  return [selectedId, ...[...identities].flatMap(([id, candidate]) => (
+    id !== selectedId && candidate?.accountId === selected.accountId && candidate.email === selected.email
+      ? [id] : []
+  ))];
+}
+
+/** Hold admission throughout; claim the physical main whenever its home exists. */
+export async function withCodexAccountPauseGroup(
+  config: OcxConfig,
+  selectedId: string,
+  publish: (accountIds: string[]) => Response,
+): Promise<Response> {
+  const lease = tryAcquireNativeMainProfileClaim();
+  if (!lease) return nativeMainProfileBusyResponse();
+  try {
+    const codexHome = resolveCodexHomeDir();
+    try {
+      lstatSync(codexHome);
+    } catch (error) {
+      // Only positive absence permits Pool-only publication. A dangling symlink or access
+      // failure is not absence; do not create a home just to coordinate an unused main login.
+      if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") return nativeMainProfileBusyResponse();
+      const ids = linkedAccountIds(config, selectedId, { status: "missing" });
+      return ids ? publish(ids) : nativeMainProfileBusyResponse();
+    }
+    const context = resolveNativeProfileContext({ codexHome });
+    return await withNativeMainSharedClaim(context, async () => {
+      const main = readMainAuth(context.authPath);
+      const ids = linkedAccountIds(config, selectedId, main);
+      return ids ? publish(ids) : nativeMainProfileBusyResponse();
+    });
+  } catch (error) {
+    if (isNativeMainClaimUnavailable(error)
+      || (error instanceof NativeProfileError && error.code === "CODEX_HOME_UNAVAILABLE")) {
+      return nativeMainProfileBusyResponse();
+    }
+    throw error;
+  } finally {
+    lease.release();
+  }
+}

package/src/codex/auth-api/routes.ts

@@ -24,6 +24,7 @@ import { inspectResetCredits, consumeResetCredits } from "./reset-credit-service
 import { getRuntimeConfig, saveRuntimeConfig, configuredPoolAccount } from "./runtime-config";
 import { captureConfigTopLevelRollback } from "../../config/rebase-provenance";
 import { getEffectiveCodexAutoSwitchThreshold, isCodexAccountAutoSwitchThresholdKey, parseCodexAutoSwitchThreshold, setCodexAccountAutoSwitchThresholdOverride } from "../account-auto-switch";
+import { withCodexAccountPauseGroup } from "./account-pause-group";
 
 export async function handleCodexAuthAPI(
   req: Request,
@@ -100,18 +101,23 @@ export async function handleCodexAuthAPI(
       || (runtimeConfig.codexAccounts ?? []).some(account => isSelectableCodexPoolAccount(account) && account.id === id);
     if (!exists) return jsonResponse({ error: "Account not found" }, 404);
 
-    setCodexAccountPaused(runtimeConfig, id, body.paused);
-    if (body.paused) {
-      clearThreadAccountMapForAccount(id);
-      selectFallbackAfterPause(runtimeConfig, id);
-    }
-    saveRuntimeConfig(config, runtimeConfig);
-    return jsonResponse({
-      ok: true,
-      id,
-      paused: body.paused,
-      activeCodexAccountId: getEffectiveActiveCodexAccountId(runtimeConfig) ?? null,
-      appliesImmediately: true,
+    const paused = body.paused;
+    return withCodexAccountPauseGroup(runtimeConfig, id, accountIds => {
+      // Publish every exclusion before reconciling: a duplicate must never become the fallback.
+      for (const accountId of accountIds) setCodexAccountPaused(runtimeConfig, accountId, paused);
+      if (paused) {
+        for (const accountId of accountIds) clearThreadAccountMapForAccount(accountId);
+        for (const accountId of accountIds) selectFallbackAfterPause(runtimeConfig, accountId);
+      }
+      saveRuntimeConfig(config, runtimeConfig);
+      return jsonResponse({
+        ok: true,
+        id,
+        paused,
+        affectedAccountIds: accountIds,
+        activeCodexAccountId: getEffectiveActiveCodexAccountId(runtimeConfig) ?? null,
+        appliesImmediately: true,
+      });
     });
   }
 

package/src/codex/auth-context.ts

@@ -1,3 +1,4 @@
+import { bindPoolCreditPolicy, poolCreditHoldResetAt, poolContextCreditHoldResetAt } from "./pool-credit-policy";
 import { hasSpendableCodexCredits } from "./quota-types";
 import { noteMainAccountActivity } from "./main-account-external-usage";
 import { codexAccountPriorityFailbackEnabled } from "./account-priority";
@@ -525,6 +526,23 @@ export class CodexMainAccountHardLockError extends CodexAccountCooldownError {
   }
 }
 
+/** A stored pool account's spending policy is independent of account selection. */
+export class CodexPoolAccountCreditsOffError extends CodexAccountCooldownError {
+  readonly resetAt: number;
+
+  constructor(accountId: string, resetAt: number) {
+    super(accountId, resetAt);
+    this.name = "CodexPoolAccountCreditsOffError";
+    this.resetAt = resetAt;
+    this.message = "The selected Codex account reached its usage limit, and spending credits is off or no fresh spendable balance is available."
+      + " Wait for the limit to reset, choose another account, or explicitly allow credits for this account in Codex Auth.";
+  }
+}
+
+function assertPoolAccountCredits(accountId: string, resetAt: number | undefined): void {
+  if (resetAt !== undefined) throw new CodexPoolAccountCreditsOffError(accountId, resetAt);
+}
+
 /** The main login may not spend credits and one of its usage windows is full (#6334). */
 export class CodexMainAccountCreditsOffError extends CodexAccountCooldownError {
   readonly resetAt?: number;
@@ -597,7 +615,7 @@ export class CodexRecoveryWithheldError extends CodexAccountCooldownError {
 
 export type CodexAuthPolicyConfig = Readonly<Pick<OcxConfig,
   "codexMainAccountHardLock" | "codexMainAccountHardLockThresholds" | "codexDesktopAuthless" | "runtimeRole" | "pausedCodexAccountIds"
-  | "creditCodexAccountIds"
+  | "creditCodexAccountIds" | "codexAccounts"
 >>;
 
 interface CodexAuthMaterializationOptions {
@@ -725,6 +743,22 @@ export function unwrapUpstreamRetryEvidenceError(error: unknown): unknown {
  * Same evidence the hard lock reads, and no plan lookup: the plan can live in the physical auth
  * file, which several callers are forbidden to open, so every long window counts instead.
  */
+/** Recheck live account policy at the physical send, after pacing or retry backoff. */
+export function createCodexAuthDispatchGuard(
+  ctx: CodexAuthContext,
+  config: CodexAuthPolicyConfig,
+  modelId: string,
+  admission?: Pick<DataPlaneAdmission, "source">,
+  terminalHelper = false,
+): ((headers: Headers) => void) | undefined {
+  const reserveGuard = createCodexReserveDispatchGuard(ctx, config, modelId, admission, terminalHelper);
+  if (ctx.kind !== "pool") return reserveGuard;
+  return headers => {
+    assertPoolAccountCredits(ctx.accountId, poolContextCreditHoldResetAt(ctx, config));
+    reserveGuard?.(headers);
+  };
+}
+
 function mainCreditsHoldResetAt(config: Pick<OcxConfig, "creditCodexAccountIds">): number | undefined {
   if (codexAccountUsesCreditsAfterLimit(config, MAIN_CODEX_ACCOUNT_ID)
     && hasSpendableCodexCredits(getMainPolicyQuota())) return undefined;
@@ -868,6 +902,7 @@ export function cooldownErrorMessage(err: CodexAccountCooldownError, accountSele
     // A credits-off refusal is a configuration policy, not a cooldown: clearing a cooldown
     // cannot lift it, so its own wording (wait for the reset or allow credits) is the remedy.
     || err instanceof CodexMainAccountCreditsOffError
+    || err instanceof CodexPoolAccountCreditsOffError
     || err instanceof CodexReserveUnavailableError
     // A transient-hold refusal is not a quota cooldown. Its own wording is the only accurate
     // one, and the quota recovery advice below would send the operator after a cooldown that
@@ -917,6 +952,7 @@ export class CodexThreadAffinityExpiredError extends Error {
 export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown): boolean {
   return !(cause instanceof CodexMainAccountHardLockError)
     && !(cause instanceof CodexMainAccountCreditsOffError)
+    && !(cause instanceof CodexPoolAccountCreditsOffError)
     && !(cause instanceof CodexAccountValidationPendingError)
     && !(cause instanceof CodexReserveUnavailableError)
     && !(cause instanceof CodexCredentialGenerationConflictError)
@@ -1408,6 +1444,7 @@ export async function resolveCodexAuthContext(
   // deferred credential must never become request auth through that fallback.
   try {
     assertCodexAccountValidationReady(accountId);
+    assertPoolAccountCredits(accountId, poolCreditHoldResetAt(policy, accountId, config));
   } catch (cause) {
     // Nothing will reach upstream, so give the trial back instead of leaving the held account
     // unprobeable until the lease deadline lapses (#4701).
@@ -1533,7 +1570,8 @@ export async function resolveCodexAuthContext(
   try {
     const token = await getValidCodexToken(accountId, { signal: options.signal });
     assertCodexAccountValidationReady(accountId);
-    return {
+    assertPoolAccountCredits(accountId, poolCreditHoldResetAt(policy, accountId, config));
+    return bindPoolCreditPolicy({
       kind: "pool",
       accountId,
       writerGeneration,
@@ -1548,11 +1586,12 @@ export async function resolveCodexAuthContext(
       ...(probeQuotaScope ? { probeQuotaScope } : {}),
       ...(affinityDecision ? { affinityDecision } : {}),
       ...(transientProbe ? { transientProbe } : {}),
-    };
+    }, config, policy);
   } catch (cause) {
     releaseTransientProbeGrant();
     if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
     else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
+    if (cause instanceof CodexPoolAccountCreditsOffError) throw cause;
     if (!options.signal?.aborted && shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
       markAccountNeedsReauth(accountId, writerGeneration);
     }
@@ -1562,6 +1601,7 @@ export async function resolveCodexAuthContext(
 
 export function assertCodexAuthContextNotCooled(ctx: CodexAuthContext | undefined): void {
   if (ctx?.kind !== "pool" && ctx?.kind !== "main-pool") return;
+  if (ctx.kind === "pool") assertPoolAccountCredits(ctx.accountId, poolContextCreditHoldResetAt(ctx));
   // A context holding the probe lease was deliberately admitted through the cooldown.
   if (ctx.probeLeaseId) return;
   const cooldown = getCodexQuotaHealthSnapshot(ctx.accountId, ctx.quotaScope);
@@ -1577,6 +1617,7 @@ export function applyCodexAuthContextToProvider(
 ): OcxRuntimeProviderConfig {
   if (mode !== "pool" || (ctx.kind !== "pool" && ctx.kind !== "main-pool") || provider.authMode !== "forward") return provider;
   assertCodexAccountValidationReady(ctx.accountId);
+  if (ctx.kind === "pool") assertPoolAccountCredits(ctx.accountId, poolContextCreditHoldResetAt(ctx));
   return {
     ...provider,
     _codexAccountOverride: {
@@ -1620,6 +1661,7 @@ export function materializeCodexUpstreamAuth(
   }
   if (ctx.kind === "pool" || ctx.kind === "main-pool") {
     assertCodexAccountValidationReady(ctx.accountId);
+    if (ctx.kind === "pool") assertPoolAccountCredits(ctx.accountId, poolContextCreditHoldResetAt(ctx, options.config));
     selected.set("authorization", `Bearer ${ctx.accessToken}`);
     selected.set("chatgpt-account-id", ctx.chatgptAccountId);
     if (ctx.kind === "main-pool") {

package/src/codex/autostart-health.ts

@@ -10,6 +10,16 @@ export type StartupProtection = "service" | "desktop" | "shim" | "none";
 export type StartupHealthStatus = "native" | "protected" | "at-risk";
 export type ShimCoverage = "full" | "cli-only" | "none";
 
+/** Bound the isolated service-manager probe and let its reader outlive that probe. */
+export function startupHealthProbeBudgetMs(platform: NodeJS.Platform = process.platform): number {
+  return platform === "win32" ? 15_000 : 5_000;
+}
+
+export function startupHealthReadBudgetMs(platform: NodeJS.Platform = process.platform): number {
+  // The endpoint waits an extra 500ms for child settlement; reserve another second for HTTP.
+  return startupHealthProbeBudgetMs(platform) + 1_500;
+}
+
 export interface StartupHealthInputs {
   desktop?: DesktopStartupDiagnostic;
   routingKind: CodexRoutingKind;

package/src/codex/pool-credit-policy.ts

@@ -0,0 +1,67 @@
+import type { OcxConfig } from "../types";
+import { codexUsageLimitResetAt, isCodexAccountHeldForCredits } from "./account-credit-use";
+import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
+import { isSelectableCodexPoolAccount } from "./account-id";
+import { getAccountQuota } from "./quota";
+
+export type PoolCreditPolicyConfig = Readonly<Pick<OcxConfig, "creditCodexAccountIds" | "codexAccounts">>;
+type PoolContext = { kind: "pool"; accountId: string };
+
+// Keep live policy references private: they must not enter DTOs or serialized auth context.
+const policies = new WeakMap<object, {
+  config: PoolCreditPolicyConfig;
+  policy: PoolCreditPolicyConfig;
+}>();
+
+/** Read cached usage only. This helper never opens or refreshes a credential. */
+export function poolCreditHoldResetAt(
+  policy: PoolCreditPolicyConfig,
+  accountId: string,
+  catalog: PoolCreditPolicyConfig = policy,
+  now = Date.now(),
+): number | undefined {
+  // Native main has an independent identity-bound quota policy. Never read its physical plan.
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) return undefined;
+  const quota = getAccountQuota(accountId);
+  const plan = catalog.codexAccounts
+    ?.find(account => isSelectableCodexPoolAccount(account) && account.id === accountId)?.plan;
+  if (!isCodexAccountHeldForCredits(policy, accountId, quota, plan, now)) return undefined;
+  return codexUsageLimitResetAt(quota, plan, now);
+}
+
+/** Remember policy by reference so later credential materialization rechecks current values. */
+export function bindPoolCreditPolicy<T extends PoolContext>(
+  context: T,
+  config: PoolCreditPolicyConfig,
+  policy: PoolCreditPolicyConfig = config,
+): T {
+  policies.set(context, { config, policy });
+  return context;
+}
+
+/**
+ * Carry the resolver's live policy onto a context rebuilt by spread copy. The WeakMap keys on
+ * object identity, so `{ ...ctx }` alone loses the binding and every caller that omits an
+ * explicit override would skip credit-hold enforcement on the copy. A source with no binding
+ * leaves the target unbound rather than inventing a policy.
+ */
+export function rebindPoolCreditPolicy<S extends PoolContext, T extends object>(source: S, target: T): T {
+  const bound = policies.get(source);
+  if (bound) policies.set(target, bound);
+  return target;
+}
+
+/** Explicit policy wins; omitted materialization options retain the resolver's policy. */
+export function poolContextCreditHoldResetAt(
+  context: PoolContext,
+  override?: PoolCreditPolicyConfig,
+  now = Date.now(),
+): number | undefined {
+  const bound = policies.get(context);
+  const policy = override ?? bound?.policy;
+  // Unbound contexts skip credit-hold enforcement entirely: callers that require
+  // enforcement must supply `override` (or resolve through bindPoolCreditPolicy).
+  if (!policy) return undefined;
+  const catalog = override?.codexAccounts ? override : bound?.config ?? policy;
+  return poolCreditHoldResetAt(policy, context.accountId, catalog, now);
+}