@bitkyc08/opencodex 2.67.0 → 2.68.0-preview.20260927

package/src/codex/runtime.ts

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { delimiter, join } from "node:path";
@@ -70,11 +70,18 @@ export type RuntimeExecFile = (
   },
 ) => string;
 
+/** Async twin of RuntimeExecFile, used by resolveCodexRuntimeAsync; resolves with stdout. */
+export type RuntimeExecFileAsync = (
+  ...args: Parameters<RuntimeExecFile>
+) => Promise<string>;
+
 export interface ResolveCodexRuntimeDeps {
   env?: NodeJS.ProcessEnv;
   platform?: NodeJS.Platform;
   configDir?: string;
   execFileSync?: RuntimeExecFile;
+  /** Probe exec for resolveCodexRuntimeAsync. Injected impls bypass the process memo like execFileSync. */
+  execFile?: RuntimeExecFileAsync;
   existsSync?: (path: string) => boolean;
   readFileSync?: (path: string, encoding: "utf8") => string;
   now?: () => number;
@@ -397,10 +404,10 @@ export function clearPersistedCodexRuntime(deps: ResolveCodexRuntimeDeps = {}):
   }
 }
 
-function probeVersion(
-  command: string,
-  deps: ResolveCodexRuntimeDeps,
-): { ok: true; version: string | null } | { ok: false; reason: string } {
+type VersionProbeResult = { ok: true; version: string | null } | { ok: false; reason: string };
+
+/** Checks that need no exec; a non-null answer settles the candidate without running `--version`. */
+function versionProbePrecheck(command: string, deps: ResolveCodexRuntimeDeps): VersionProbeResult | null {
   const platform = deps.platform ?? process.platform;
   if (command.includes("/") || command.includes("\\") || /^[A-Za-z]:/.test(command)) {
     const exists = deps.existsSync ?? existsSync;
@@ -414,7 +421,54 @@ function probeVersion(
   // dashboard probe that cost made Windows report Codex as missing even when
   // the App install was sitting under LOCALAPPDATA/OpenAI/Codex/bin (issue 4458).
   if (deps.probeVersion === false) return { ok: true, version: null };
-  const execFile = deps.execFileSync ?? (execFileSync as unknown as RuntimeExecFile);
+  return null;
+}
+
+function versionProbeInvocation(command: string, deps: ResolveCodexRuntimeDeps, probeHome: string) {
+  const invocation = codexExecInvocation(command, ["--version"], deps.platform ?? process.platform, {
+    env: deps.env,
+    exists: deps.existsSync,
+  });
+  return {
+    file: invocation.file,
+    args: invocation.args,
+    options: {
+      encoding: "utf8" as const,
+      stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"],
+      timeout: 8_000,
+      windowsHide: true,
+      env: { ...(deps.env ?? process.env), CODEX_HOME: probeHome },
+      ...invocation.options,
+    },
+  };
+}
+
+function versionProbeOutput(output: string): VersionProbeResult {
+  const version = parseCodexVersionOutput(output);
+  if (!version) return { ok: false, reason: "unrecognized --version output" };
+  return { ok: true, version };
+}
+
+function versionProbeError(error: unknown, probeHome: string | undefined): VersionProbeResult {
+  if (!probeHome) return { ok: false, reason: "probe sandbox unavailable" };
+  if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+    return { ok: false, reason: CODEX_PROGRAM_NOT_FOUND_REASON };
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const redacted = redactUserPath(redactSecretString(message)).slice(0, 160);
+  return { ok: false, reason: `failed --version (${redacted})` };
+}
+
+function removeProbeHome(probeHome: string | undefined): void {
+  if (!probeHome) return;
+  // Nested catch: a transient Windows EBUSY must never mask the probe result.
+  try { rmSync(probeHome, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+
+function probeVersion(command: string, deps: ResolveCodexRuntimeDeps): VersionProbeResult {
+  const settled = versionProbePrecheck(command, deps);
+  if (settled) return settled;
+  const exec = deps.execFileSync ?? (execFileSync as unknown as RuntimeExecFile);
   // Sandbox the probe's CODEX_HOME: a real Codex CLI creates state (tmp/, logs) under
   // CODEX_HOME even for `--version`, and the probe inherits the caller's env — so a
   // read-only `ocx status` would dirty the user's CODEX_HOME. Redirect it to a
@@ -423,36 +477,36 @@ function probeVersion(
   let probeHome: string | undefined;
   try {
     probeHome = mkdtempSync(join(tmpdir(), "ocx-codex-probe-"));
-    const invocation = codexExecInvocation(command, ["--version"], platform, {
-      env: deps.env,
-      exists: deps.existsSync,
-    });
-    const output = execFile(invocation.file, invocation.args, {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 8_000,
-      windowsHide: true,
-      env: { ...(deps.env ?? process.env), CODEX_HOME: probeHome },
-      ...invocation.options,
-    });
-    const version = parseCodexVersionOutput(output);
-    if (!version) {
-      return { ok: false, reason: "unrecognized --version output" };
-    }
-    return { ok: true, version };
+    const { file, args, options } = versionProbeInvocation(command, deps, probeHome);
+    return versionProbeOutput(exec(file, args, options));
   } catch (error) {
-    if (!probeHome) return { ok: false, reason: "probe sandbox unavailable" };
-    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
-      return { ok: false, reason: CODEX_PROGRAM_NOT_FOUND_REASON };
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    const redacted = redactUserPath(redactSecretString(message)).slice(0, 160);
-    return { ok: false, reason: `failed --version (${redacted})` };
+    return versionProbeError(error, probeHome);
   } finally {
-    if (probeHome) {
-      // Nested catch: a transient Windows EBUSY must never mask the probe result.
-      try { rmSync(probeHome, { recursive: true, force: true }); } catch { /* best effort */ }
-    }
+    removeProbeHome(probeHome);
+  }
+}
+
+const defaultExecFileAsync: RuntimeExecFileAsync = (file, args, options) =>
+  new Promise((resolve, reject) => {
+    // execFile always pipes stdout/stderr; it takes no stdio option.
+    const { stdio: _stdio, ...execOptions } = options;
+    execFile(file, args, execOptions, (error, stdout) => (error ? reject(error) : resolve(String(stdout))));
+  });
+
+/** probeVersion with the same sandbox and outcomes, but the exec never holds the event loop. */
+async function probeVersionAsync(command: string, deps: ResolveCodexRuntimeDeps): Promise<VersionProbeResult> {
+  const settled = versionProbePrecheck(command, deps);
+  if (settled) return settled;
+  const exec = deps.execFile ?? defaultExecFileAsync;
+  let probeHome: string | undefined;
+  try {
+    probeHome = mkdtempSync(join(tmpdir(), "ocx-codex-probe-"));
+    const { file, args, options } = versionProbeInvocation(command, deps, probeHome);
+    return versionProbeOutput(await exec(file, args, options));
+  } catch (error) {
+    return versionProbeError(error, probeHome);
+  } finally {
+    removeProbeHome(probeHome);
   }
 }
 
@@ -566,23 +620,6 @@ interface RankedCandidate {
   source: CodexRuntimeSource;
 }
 
-function tryCandidate(
-  candidate: RankedCandidate,
-  failures: RuntimeProbeFailure[],
-  deps: ResolveCodexRuntimeDeps,
-): ResolvedCodexRuntime | null {
-  const probed = probeVersion(candidate.command, deps);
-  if (!probed.ok) {
-    failures.push({ command: candidate.command, source: candidate.source, reason: probed.reason });
-    return null;
-  }
-  return {
-    command: candidate.command,
-    version: probed.version,
-    source: candidate.source,
-  };
-}
-
 function sameRuntimeCommand(a: string, b: string): boolean {
   return a.trim().toLowerCase() === b.trim().toLowerCase();
 }
@@ -704,10 +741,26 @@ export function clearCodexRuntimeResolveCache(): void {
   clearResolveCache();
 }
 
-/** Observe only an unexpired successful process memo; never resolves or probes. */
+/**
+ * Observe the successful process memo; never resolves or probes.
+ *
+ * An expired memo stays observable while an async refresh for the same inputs is in flight
+ * and nothing has invalidated it since. The sync resolver used to hold the event loop for the
+ * whole probe, so nothing could read in that window; with the refresh off the loop, dropping
+ * the memo there would send catalog gather to the persisted runtime (or none) and have
+ * convergence reject its process-local candidate every expiry. A published result or a clear
+ * still retires it; the deferred selection never enters this memo (#4458).
+ */
 export function peekCodexRuntimeProcessCache(): CodexRuntimeProcessCachePeek {
   const memo = resolveCache;
-  if (!memo || Date.now() - memo.at >= RESOLVE_CACHE_MS) {
+  const refreshing = memo !== null
+    && asyncResolveInflight !== null
+    && asyncResolveInflight.key === memo.key
+    && asyncResolveInflight.epoch === resolveCacheEpoch
+    // An expired memo only stands in for a refresh of the same selection; an out-of-process
+    // runtime switch changes the key without bumping the epoch.
+    && resolveCacheKey({}) === memo.key;
+  if (!memo || (Date.now() - memo.at >= RESOLVE_CACHE_MS && !refreshing)) {
     return Object.freeze({ kind: "unavailable" as const, epoch: resolveCacheEpoch });
   }
   return Object.freeze({
@@ -735,6 +788,7 @@ function resolveCacheKey(deps: ResolveCodexRuntimeDeps): string | null {
   // Only memoize uninjected process-env resolves (settings/status hot paths).
   if (
     deps.execFileSync
+    || deps.execFile
     || deps.existsSync
     || deps.readFileSync
     || deps.readdirSync
@@ -799,6 +853,59 @@ export function resolveCodexRuntime(deps: ResolveCodexRuntimeDeps = {}): Resolve
   return cloneAndDeepFreeze(result);
 }
 
+let asyncResolveInflight: { key: string; epoch: number; promise: Promise<ResolveCodexRuntimeResult> } | null = null;
+
+/**
+ * resolveCodexRuntime for server request paths: same selection and process memo, but every
+ * `codex --version` runs through async exec. The sync resolver blocked the whole proxy for
+ * ~0.6s per memo expiry while the dashboard polled settings, stalling unrelated requests.
+ */
+export async function resolveCodexRuntimeAsync(
+  deps: ResolveCodexRuntimeDeps = {},
+): Promise<ResolveCodexRuntimeResult> {
+  // A deferred selection never execs, so the sync path is already nonblocking.
+  if (deps.probeVersion === false) return resolveCodexRuntime(deps);
+  const cacheKey = resolveCacheKey(deps);
+  if (cacheKey && resolveCache && resolveCache.key === cacheKey && Date.now() - resolveCache.at < RESOLVE_CACHE_MS) {
+    return cloneAndDeepFreeze(resolveCache.value);
+  }
+  if (!cacheKey) return cloneAndDeepFreeze(await resolveCodexRuntimeUncachedAsync(deps));
+  const startedEpoch = resolveCacheEpoch;
+  if (asyncResolveInflight?.key === cacheKey && asyncResolveInflight.epoch === startedEpoch) {
+    return cloneAndDeepFreeze(await asyncResolveInflight.promise);
+  }
+  const promise = resolveCodexRuntimeUncachedAsync(deps).then(result => {
+    // A persist or clear while the probes ran makes this answer the previous selection's;
+    // publishing it would resurrect authority the write just revoked. Another process can also
+    // rewrite codex-runtime.json without touching this epoch, so the key is read again too.
+    if (resolveCacheEpoch === startedEpoch && resolveCacheKey(deps) === cacheKey) {
+      publishResolveCache(cacheKey, Date.now(), result);
+    }
+    return result;
+  }).finally(() => {
+    if (asyncResolveInflight?.promise === promise) asyncResolveInflight = null;
+  });
+  asyncResolveInflight = { key: cacheKey, epoch: startedEpoch, promise };
+  return cloneAndDeepFreeze(await promise);
+}
+
+/**
+ * Stale-while-revalidate runtime read for hot UI paths; never waits on a probe.
+ *
+ * Returns the process memo when fresh, otherwise the last memo for the same inputs, and kicks
+ * resolveCodexRuntimeAsync to refresh it. With no memo yet (cold start, or right after a runtime
+ * switch cleared it) the answer is the exec-free deferred selection, so a version and
+ * newerAvailable appear once the first background refresh lands.
+ */
+export function getCodexRuntimeSnapshot(): ResolveCodexRuntimeResult {
+  const cacheKey = resolveCacheKey({});
+  const memo = resolveCache?.key === cacheKey ? resolveCache : null;
+  if (memo && Date.now() - memo.at < RESOLVE_CACHE_MS) return cloneAndDeepFreeze(memo.value);
+  resolveCodexRuntimeAsync().catch(() => { /* the next read retries */ });
+  if (memo) return cloneAndDeepFreeze(memo.value);
+  return resolveCodexRuntime({ discoverAlternatives: false, probeVersion: false });
+}
+
 /** Test-only: drop the short-lived process resolve cache. */
 export function resetCodexRuntimeResolveCacheForTests(): void {
   clearCodexRuntimeResolveCache();
@@ -814,7 +921,14 @@ export function setCodexRuntimeResolveCacheForTests(
   publishResolveCache(key, Date.now(), value);
 }
 
-function resolveCodexRuntimeUncached(deps: ResolveCodexRuntimeDeps = {}): ResolveCodexRuntimeResult {
+/**
+ * Candidate ranking and selection, written once for both drivers: each yield hands a candidate to
+ * the caller, which sends back its `--version` outcome. The sync driver keeps CLI behavior; the
+ * async one lets a server path resolve without blocking every other request on the probes.
+ */
+function* resolveCodexRuntimeSteps(
+  deps: ResolveCodexRuntimeDeps,
+): Generator<RankedCandidate, ResolveCodexRuntimeResult, VersionProbeResult> {
   const env = deps.env ?? process.env;
   const failures: RuntimeProbeFailure[] = [];
   const ordered: RankedCandidate[] = [];
@@ -868,9 +982,12 @@ function resolveCodexRuntimeUncached(deps: ResolveCodexRuntimeDeps = {}): Resolv
     ) {
       continue;
     }
-    const resolved = tryCandidate(candidate, failures, deps);
-    if (!resolved) continue;
-    valid.push(resolved);
+    const probed: VersionProbeResult = yield candidate;
+    if (!probed.ok) {
+      failures.push({ command: candidate.command, source: candidate.source, reason: probed.reason });
+      continue;
+    }
+    valid.push({ command: candidate.command, version: probed.version, source: candidate.source });
   }
 
   if (valid.length === 0) {
@@ -954,6 +1071,20 @@ function resolveCodexRuntimeUncached(deps: ResolveCodexRuntimeDeps = {}): Resolv
   };
 }
 
+function resolveCodexRuntimeUncached(deps: ResolveCodexRuntimeDeps = {}): ResolveCodexRuntimeResult {
+  const steps = resolveCodexRuntimeSteps(deps);
+  let step = steps.next();
+  while (!step.done) step = steps.next(probeVersion(step.value.command, deps));
+  return step.value;
+}
+
+async function resolveCodexRuntimeUncachedAsync(deps: ResolveCodexRuntimeDeps): Promise<ResolveCodexRuntimeResult> {
+  const steps = resolveCodexRuntimeSteps(deps);
+  let step = steps.next();
+  while (!step.done) step = steps.next(await probeVersionAsync(step.value.command, deps));
+  return step.value;
+}
+
 /** Resolve and persist a successful selection (unless source is ephemeral fallback-only with no path). */
 export function resolveAndPersistCodexRuntime(
   deps: ResolveCodexRuntimeDeps = {},

package/src/codex/sibling-handoff.ts

@@ -0,0 +1,71 @@
+/** A one-use restart handoff from a running sibling to its own replacement. */
+import { randomBytes } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync, renameSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile } from "../config/atomic-write";
+import { getConfigDir } from "../config/paths";
+import { readRuntimePort } from "../config/process-state";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { siblingOfLivePort } from "./sibling-start";
+
+const NONCE_RE = /^[A-Za-z0-9_-]{43}$/;
+const MAX_HANDOFF_AGE_MS = 2 * 60_000;
+const MAX_RECORD_BYTES = 512;
+
+function handoffPath(home: string, nonce: string): string {
+  return join(home, `sibling-handoff-${nonce}.json`);
+}
+
+/** Issue only while this home's runtime record still identifies the running sibling. */
+export function issueSiblingHandoff(ownerPort: number): string {
+  const home = getConfigDir();
+  assertNotRealHomeUnderTest(home);
+  const runtime = readRuntimePort(process.pid);
+  if (siblingOfLivePort() !== ownerPort || !runtime
+    || runtime.siblingOfPort !== ownerPort || runtime.port === ownerPort) {
+    throw new Error("Cannot hand off sibling status without this home's live sibling record.");
+  }
+  const nonce = randomBytes(32).toString("base64url");
+  const record = {
+    version: 1,
+    nonce,
+    home: realpathSync(home),
+    issuerPid: process.pid,
+    issuerPort: runtime.port,
+    ownerPort,
+    issuedAt: Date.now(),
+  };
+  atomicWriteFile(handoffPath(home, nonce), JSON.stringify(record));
+  return nonce;
+}
+
+/** Atomically claim and consume the record; a copied env cannot replay it. */
+export function consumeSiblingHandoff(ownerPort: number, nonce: string | undefined): boolean {
+  if (!nonce || !NONCE_RE.test(nonce)) return false;
+  const home = getConfigDir();
+  let canonicalHome: string;
+  try { canonicalHome = realpathSync(home); }
+  catch { return false; }
+  const source = handoffPath(home, nonce);
+  const claimed = `${source}.claimed-${process.pid}`;
+  try { renameSync(source, claimed); }
+  catch { return false; }
+  try {
+    const stat = lstatSync(claimed);
+    if (!stat.isFile() || stat.size > MAX_RECORD_BYTES || stat.size === 0
+      || (process.platform !== "win32" && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.()))) return false;
+    const record = JSON.parse(readFileSync(claimed, "utf8")) as Record<string, unknown>;
+    const issuedAt = record.issuedAt;
+    const now = Date.now();
+    return record.version === 1 && record.nonce === nonce && record.home === canonicalHome
+      && record.ownerPort === ownerPort && Number.isSafeInteger(record.issuerPid)
+      && Number(record.issuerPid) > 0 && Number.isInteger(record.issuerPort)
+      && Number(record.issuerPort) > 0 && Number(record.issuerPort) <= 65535
+      && record.issuerPort !== ownerPort && typeof issuedAt === "number"
+      && issuedAt <= now && now - issuedAt <= MAX_HANDOFF_AGE_MS;
+  } catch {
+    return false;
+  } finally {
+    try { unlinkSync(claimed); } catch { /* already consumed */ }
+  }
+}

package/src/codex/sibling-start.ts

@@ -0,0 +1,139 @@
+/**
+ * The process-local "sibling instance" mark.
+ *
+ * A sibling is what `decideStartWithLiveOwner` calls `"sibling"`: `ocx start --port <other>` while a
+ * live proxy already serves the configured port. Only an independent `OPENCODEX_HOME` gets past the
+ * state-directory spend-ledger lease, and that independence ends at its own directory: the sibling
+ * still shares `CODEX_HOME`, `~/.claude`, `~/.grok`, the shell rc hook and the launchd domain with
+ * the live owner. A sibling that ran the ordinary startup sync therefore re-pointed Codex at its own
+ * port, and every thread broke with "Connection refused" once the sibling exited or was killed. The
+ * owner's client routing is the owner's, for this process's whole lifetime.
+ *
+ * So `handleStart` sets this mark the moment it takes the sibling path, before the server binds and
+ * before any client write, and the local-client gate (`localClientSyncAllowed` in
+ * `desired-state.ts`), the restore entry points, the catalog convergence funnel, the owned-catalog
+ * refresh, the Claude writers, the stop teardown and the management route guard all consult it. The
+ * sibling still serves direct requests on its own port.
+ *
+ * One-way and process-local on purpose. A mark that could be cleared would let a later code path
+ * resume writing mid-lifetime, and a persisted one would outlive the process it describes. Worker
+ * threads do not see it; that is acceptable because history jobs start only from inject and
+ * restore, and both return before spawning one.
+ *
+ * A sibling runs the no-op native-main lifecycle (the gate is closed), so it never contends for the
+ * native-main owner lease and cannot take ownership from the live proxy across that proxy's
+ * restarts. Its data-plane native-main admission is the same as a Codex-OFF proxy's: an `auth.json`
+ * refresh still runs under the machine-wide exclusive claim. The native-main mutation routes are
+ * refused by the management guard instead.
+ *
+ * The one hand-off is to this process's own replacement. A sibling's dashboard drain-and-restart and
+ * its standalone recycle spawn a fresh `ocx start` that re-probes; if the owner is down for that
+ * moment, the replacement used to start as an unmarked owner, re-point Codex at itself and persist
+ * `config.port`. Those spawns carry a port plus a one-use record nonce from `sibling-handoff.ts`.
+ * `handleStart` consumes the record before any probe; an env port alone grants nothing.
+ *
+ * Deliberately import-free: the gate, the server and the CLI all read it, and a leaf cannot form a
+ * cycle.
+ */
+
+let livePort: number | null = null;
+
+/** Mark this process as a sibling of the proxy serving `port`. Idempotent; never unset. */
+export function markSiblingStart(port: number): void {
+  livePort = port;
+}
+
+/** The live owner's port when this process is a sibling, otherwise `null`. */
+export function siblingOfLivePort(): number | null {
+  return livePort;
+}
+
+/** Test seam only: production never clears the mark. */
+export function resetSiblingStartForTests(): void {
+  livePort = null;
+}
+
+/**
+ * The one line a sibling prints wherever it declines a shared client write.
+ *
+ * With the sibling's own port it describes the split; without one (a skip deep inside a writer
+ * that does not know the port) it names what was left alone.
+ */
+export function siblingSkipMessage(ownPort?: number): string {
+  const live = livePort ?? "unknown";
+  return ownPort === undefined
+    ? `Client routing stays on the proxy at port ${live}; this instance does not rewrite Codex, Grok or Claude configs.`
+    : `Client routing stays on the proxy at port ${live}; this instance serves direct requests on port ${ownPort} only.`;
+}
+
+/**
+ * The optional runtime-record field that tells a later `ocx stop` it is stopping a sibling.
+ * Empty when unmarked, so a non-sibling record stays byte-identical.
+ */
+export function siblingRuntimeField(): { siblingOfPort?: number } {
+  return livePort === null ? {} : { siblingOfPort: livePort };
+}
+
+/** The env var a sibling hands its own replacement `ocx start`: the live owner's port. */
+export const SIBLING_OF_PORT_ENV = "OCX_SIBLING_OF_PORT";
+export const SIBLING_HANDOFF_NONCE_ENV = "OCX_SIBLING_HANDOFF_NONCE";
+
+type Env = Record<string, string | undefined>;
+
+/** The owner port an inherited marker names, or `null` when absent or not a TCP port. */
+export function parseSiblingMarker(raw: string | undefined): number | null {
+  const trimmed = raw?.trim() ?? "";
+  if (!/^[0-9]{1,5}$/.test(trimmed)) return null;
+  const port = Number(trimmed);
+  return port >= 1 && port <= 65535 ? port : null;
+}
+
+/**
+ * Honor a port only when its one-use handoff record was consumed. Both env fields are stripped
+ * before any probe, including on refusal, so a later detached child cannot inherit them.
+ */
+export function honorSiblingMarker(env: Env, consumeHandoff: (port: number, nonce: string | undefined) => boolean): number | null {
+  const port = parseSiblingMarker(env[SIBLING_OF_PORT_ENV]);
+  const nonce = env[SIBLING_HANDOFF_NONCE_ENV];
+  delete env[SIBLING_OF_PORT_ENV];
+  delete env[SIBLING_HANDOFF_NONCE_ENV];
+  if (port === null || !consumeHandoff(port, nonce)) return null;
+  markSiblingStart(port);
+  return port;
+}
+
+/** A copy of `env` for this process's own replacement, with a one-use handoff when marked. */
+export function withSiblingMarker<T extends Env>(env: T, issueHandoff?: (port: number) => string): T {
+  const next: Env = withoutSiblingMarker(env);
+  if (livePort !== null) {
+    if (!issueHandoff) throw new Error("Sibling replacement requires a one-use handoff issuer.");
+    next[SIBLING_OF_PORT_ENV] = String(livePort);
+    next[SIBLING_HANDOFF_NONCE_ENV] = issueHandoff(livePort);
+  }
+  return next as T;
+}
+
+/** A copy of `env` for a child that must start as an ordinary owner (`ocx ensure`, the tray). */
+export function withoutSiblingMarker<T extends Env>(env: T): T {
+  const next: Env = { ...env };
+  delete next[SIBLING_OF_PORT_ENV];
+  delete next[SIBLING_HANDOFF_NONCE_ENV];
+  return next as T;
+}
+
+/**
+ * Whether `ocx stop` of a sibling runtime found the live owner instead of the sibling.
+ *
+ * A hard-killed sibling leaves its record behind with a dead pid, so the stop falls through to
+ * discovery, and discovery ends on the configured port, where the live owner answers. Stopping that
+ * proxy is the outage the sibling design exists to prevent. The found proxy is the owner when it
+ * answers on `siblingOfPort`, or when only the configured-port fallback reached it (the sibling's
+ * own record did not answer). `live` is `findLiveProxy`'s result.
+ */
+export function siblingStopFoundOwner(
+  siblingOfPort: number | undefined,
+  live: { port: number; source: "runtime" | "config" } | null,
+): boolean {
+  if (siblingOfPort === undefined || live === null) return false;
+  return live.port === siblingOfPort || live.source === "config";
+}

package/src/codex/sync.ts

@@ -284,9 +284,11 @@ export async function syncModelsToCodex(
   if (result.status === "skipped") {
     return {
       status: "skipped",
-      // The apply direction's only under-lock policy skips are desired OFF and the hub gate;
-      // carry whichever the injector reported so the caller can say the honest thing.
-      skippedReason: result.skippedReason === "hub-gated" ? "hub-gated" : "desired_disabled",
+      // The apply direction's only policy skips are desired OFF, the hub gate and a sibling
+      // instance; carry whichever the injector reported so the caller can say the honest thing.
+      skippedReason: result.skippedReason === "hub-gated" || result.skippedReason === "sibling"
+        ? result.skippedReason
+        : "desired_disabled",
       ok: true,
       added: 0,
       catalogPath: null,

package/src/combos/failover.ts

@@ -230,11 +230,17 @@ export function coolComboTarget(
   const cooldownMs = serverDelayMs
     ?? parseResetCooldownMs(options?.resetAt, now)
     ?? options?.cooldownMs
-    ?? (isTransientRequestRateLimit({
-      status: options?.status,
-      code: options?.code,
-      message: options?.message,
-    }) ? COMBO_REQUEST_RATE_COOLDOWN_MS : DEFAULT_COOLDOWN_MS);
+    // A spent account window or an unpaid/rejected credential does not turn over in a minute,
+    // so the 60s default would re-offer a target that cannot succeed. Only the duration
+    // changes; the scope and hop decisions are untouched.
+    ?? (isAccountWindowExhausted(options?.message ?? "", options?.code)
+      || PROVIDER_SCOPED_FAILURE_CODES.has(normalizedFailureCode(options?.code))
+      ? MAX_COOLDOWN_MS
+      : isTransientRequestRateLimit({
+        status: options?.status,
+        code: options?.code,
+        message: options?.message,
+      }) ? COMBO_REQUEST_RATE_COOLDOWN_MS : DEFAULT_COOLDOWN_MS);
   targetCooldowns.set(cooldownMapKey(comboId, target), {
     // Local fallbacks are capped at ten minutes; explicit server delays at one day.
     cooldownUntil: now + (serverDelayMs ?? Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS)),
@@ -306,6 +312,27 @@ function normalizedFailureCode(code?: string | null): string {
   return code?.trim().toLowerCase().replaceAll("-", "_") ?? "";
 }
 
+/**
+ * A spent account window, by structured code or upstream prose. Status is deliberately not
+ * consulted: the ChatGPT Codex backend reports a depleted plan window as HTTP 502
+ * `upstream_server_error` carrying `The usage limit has been reached`, never the documented 429,
+ * so any status gate misses it. Read in exactly ONE place -- the cooldown DURATION fallback. A
+ * status-blind prose match is safe for choosing how long to wait; it is not safe for choosing
+ * what to black out, so `isProviderScopedQuotaCap` and the scope/decision paths stay untouched
+ * and a Codex 502 still resolves `target` scope and `hop` through `status >= 500`.
+ */
+// `1308` is the vendor code for a spent five-hour window and carries no prose of its own when the
+// upstream reports it bare, so it belongs here too. The rest of QUOTA_LIMIT_CODES stays out: those
+// are quota-limit codes whose window length this gateway has no evidence for, and guessing long on
+// them would hold a target that may clear sooner.
+const ACCOUNT_EXHAUSTION_CODES = new Set(["usage_limit_exceeded", "usage_limit_reached", "1308"]);
+const ACCOUNT_EXHAUSTION_TEXT = /usage limit (?:has been )?reached/;
+
+function isAccountWindowExhausted(message: string, code?: string | null): boolean {
+  return ACCOUNT_EXHAUSTION_CODES.has(normalizedFailureCode(code))
+    || ACCOUNT_EXHAUSTION_TEXT.test(message.toLowerCase());
+}
+
 function isProviderScopedQuotaCap(
   status: number | undefined,
   message: string,

package/src/combos/request.ts

@@ -1,5 +1,5 @@
 import type { OcxComboDefaultEffort, OcxComboDefaultEffortMode, OcxComboReasoningEffortMode, OcxComboTarget, OcxConfig } from "../types";
-import { isCodexReasoningEffort, resolveEffortAtOrBelow } from "../reasoning-effort";
+import { isCodexReasoningEffort, isDeclaredReasoningEffort, resolveEffortAtOrBelow } from "../reasoning-effort";
 import { resolveComboId } from "./types";
 
 const warnedUnsupportedDefaults = new Set<string>();
@@ -54,6 +54,11 @@ function responsesInputNodeHasImage(value: unknown): boolean {
   return false;
 }
 
+/**
+ * Clone a logical combo request for one concrete target and apply the combo's reasoning policy.
+ * Force mode overrides every valid declared caller effort only when the target ladder proves the
+ * configured default is representable; unknown capabilities stay conservative.
+ */
 export function concreteComboRequestBody(
   body: unknown,
   target: Pick<OcxComboTarget, "provider" | "model">,
@@ -79,9 +84,12 @@ export function concreteComboRequestBody(
   const hasEffort = reasoningRecord !== undefined
     && Object.prototype.hasOwnProperty.call(reasoningRecord, "effort");
   const callerEffort = reasoningRecord?.effort;
-  const validCallerEffort = typeof callerEffort === "string" && isCodexReasoningEffort(callerEffort);
+  const declaredCallerEffort = typeof callerEffort === "string" && isDeclaredReasoningEffort(callerEffort);
   const needsDefault = reasoning === undefined || (reasoningRecord !== undefined && !hasEffort);
-  const shouldForce = defaultEffortMode === "force" && validCallerEffort;
+  // `none` and `minimal` are valid request sentinels even though they are outside the ranked
+  // low..ultra Codex ladder. Force mode means the combo policy wins over any valid declared
+  // caller effort, including those sentinels.
+  const shouldForce = defaultEffortMode === "force" && declaredCallerEffort;
   if (!needsDefault && !shouldForce) return clone;
   // Picker availability treats an unknown ladder as a wildcard, but runtime
   // injection stays fail-closed until this concrete target advertises support.