@iislee/opencodex 2.11.0

package/src/lib/process-control.ts

@@ -0,0 +1,165 @@
+import { execFileSync } from "node:child_process";
+import { loadConfig, readRuntimePort } from "../config";
+import { configuredAdminToken } from "./admin-secrets";
+
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function waitForExit(pid: number, timeoutMs: number): boolean {
+  const deadline = Date.now() + timeoutMs;
+  const marker = new Int32Array(new SharedArrayBuffer(4));
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) return true;
+    Atomics.wait(marker, 0, 0, 50);
+  }
+  return !isProcessAlive(pid);
+}
+
+/** Injectable seams so the graceful-stop flow is unit-testable without a live proxy. */
+export interface GracefulStopIo {
+  fetchFn?: typeof fetch;
+  readRuntime?: (pid: number) => { port: number; hostname?: string } | null;
+  waitExit?: (pid: number, timeoutMs: number) => boolean;
+  env?: Record<string, string | undefined>;
+  exitTimeoutMs?: number;
+}
+
+/**
+ * Host to POST /api/stop against: follow the recorded bind hostname when it names a
+ * concrete address (a proxy bound to ::1 or a LAN IP is unreachable on 127.0.0.1);
+ * loopback aliases and wildcard binds all answer on IPv4 loopback.
+ */
+export function gracefulStopHost(hostname: string | undefined): string {
+  const trimmed = (hostname ?? "").trim();
+  const lower = trimmed.toLowerCase();
+  if (!trimmed || lower === "localhost" || trimmed === "127.0.0.1" || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]") {
+    return "127.0.0.1";
+  }
+  if (lower === "::1" || lower === "[::1]") return "[::1]";
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed;
+  return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
+}
+
+/**
+ * Outcome of a graceful stop attempt. `"refused"` is distinct from failure: the proxy answered
+ * that it must NOT be stopped from here, so callers must not escalate to a forced kill.
+ */
+export type GracefulStopResult = boolean | "refused";
+
+/**
+ * Ask a running proxy to stop itself via the management API (`POST /api/stop`), which
+ * drains in-flight turns, restores native Codex, and cleans its pid/runtime files.
+ * This is the only way to get a GRACEFUL stop on Windows, where the POSIX
+ * SIGTERM-then-SIGKILL ladder does not exist and `taskkill /F` gives the proxy no
+ * chance to run its shutdown handlers. Returns false when the proxy can't be reached
+ * or doesn't exit in time — callers fall back to {@link killProxy}. Returns `"refused"`
+ * when the proxy declines the stop (HTTP 409), which callers must NOT force past.
+ */
+export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}): Promise<GracefulStopResult> {
+  const readRuntime = io.readRuntime ?? readRuntimePort;
+  const runtime = readRuntime(pid);
+  if (!runtime?.port) return false;
+  const env = io.env ?? process.env;
+  const headers: Record<string, string> = {};
+  const token = configuredAdminToken(env.OPENCODEX_HOME?.trim() || undefined, env as NodeJS.ProcessEnv);
+  if (token) headers["x-opencodex-api-key"] = token;
+  const fetchFn = io.fetchFn ?? fetch;
+  try {
+    const res = await fetchFn(`http://${gracefulStopHost(runtime.hostname)}:${runtime.port}/api/stop`, {
+      method: "POST",
+      headers,
+      // Hung proxies with many CLOSE_WAIT clients can be slow to accept; give them
+      // longer than a health poll so we prefer drain over taskkill /F.
+      signal: AbortSignal.timeout(io.exitTimeoutMs ? Math.min(io.exitTimeoutMs, 10_000) : 10_000),
+    });
+    // 409 is the proxy REFUSING to stop (a service installed under another home owns it and
+    // would respawn it anyway). That is a policy answer, not a dead endpoint — escalating to
+    // SIGTERM here would run the daemon's cleanup and strip shared config out from under the
+    // still-running service. Report the refusal instead of forcing.
+    if (res.status === 409) return "refused";
+    if (!res.ok) return false;
+  } catch {
+    return false;
+  }
+  const waitExit = io.waitExit ?? waitForExit;
+  // Honor the server's own drain window: /api/stop answers 200 first, then drains for
+  // config.shutdownTimeoutMs. Waiting less than that hard-kills mid-drain.
+  const exitTimeoutMs = io.exitTimeoutMs ?? drainDeadlineMs();
+  return waitExit(pid, exitTimeoutMs);
+}
+
+function drainDeadlineMs(): number {
+  try {
+    return (loadConfig().shutdownTimeoutMs ?? 5000) + 3000;
+  } catch {
+    return 8000;
+  }
+}
+
+/** Graceful-first stop: management-API drain, then the platform kill ladder. */
+export async function stopProxy(pid: number): Promise<void> {
+  if (!isProcessAlive(pid)) return;
+  const runtime = readRuntimePort(pid);
+  const graceful = await stopProxyGracefully(pid);
+  if (graceful === "refused") {
+    // The proxy refused on purpose (foreign service owns it). Forcing would strip shared
+    // config while that service keeps the proxy alive.
+    throw new Error(
+      "The running proxy refused to stop: a service installed under a different "
+      + "CODEX_HOME/OPENCODEX_HOME owns it. Run the stop from that home.",
+    );
+  }
+  if (graceful) {
+    await waitForStoppedPort(runtime, pid);
+    return;
+  }
+  killProxy(pid);
+  await waitForStoppedPort(runtime, pid);
+}
+
+/** After stop/kill, wait for the former listen port to become bindable (Windows drain). */
+async function waitForStoppedPort(
+  runtime: { port: number; hostname?: string } | null | undefined,
+  stoppedPid?: number,
+): Promise<void> {
+  if (!runtime?.port) return;
+  try {
+    const { reclaimListenPort } = await import("../server/port-reclaim");
+    await reclaimListenPort(runtime.port, runtime.hostname ?? "127.0.0.1", {
+      timeoutMs: 15_000,
+      intervalMs: 100,
+      scanIntervalMs: 500,
+      // Only the process we just stopped — never kill a newly started twin proxy.
+      killOcxHolders: !!(stoppedPid && stoppedPid > 0),
+      onlyKillPids: stoppedPid && stoppedPid > 0 ? [stoppedPid] : [],
+    });
+  } catch {
+    /* best-effort — callers that need a hard guarantee reclaim again before bind */
+  }
+}
+
+export function killProxy(pid: number): void {
+  if (!isProcessAlive(pid)) return;
+  if (process.platform === "win32") {
+    // Windows process.kill(SIGTERM/SIGINT) is TerminateProcess — not a graceful signal.
+    // Graceful drain happens only via stopProxyGracefully() (POST /api/stop). This path
+    // is the hard fallback: taskkill /T /F so the process tree exits (ghost LISTEN /
+    // CLOSE_WAIT are then cleared by reclaimListenPort / SetTcpEntry).
+    const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
+    try {
+      execFileSync(taskkill, ["/PID", String(pid), "/T", "/F"], { stdio: "pipe", windowsHide: true });
+    } catch (err) {
+      if (isProcessAlive(pid)) throw err;
+    }
+  } else {
+    process.kill(pid, "SIGTERM");
+    if (!waitForExit(pid, 5000)) process.kill(pid, "SIGKILL");
+  }
+  if (!waitForExit(pid, 5000)) throw new Error(`process ${pid} did not exit`);
+}

package/src/lib/provider-outbound.ts

@@ -0,0 +1,170 @@
+import type { OcxProviderConfig } from "../types";
+import {
+  assessUrlDestination,
+  DestinationDnsResolutionError,
+  providerAllowsPrivateNetwork,
+  providerDestinationConfigError,
+  resolvePublicAddresses,
+} from "./destination-policy";
+import { pinnedHttpGet } from "./pinned-http";
+import { outboundProxyConfigured } from "./proxy-env";
+import { publicProviderBaseUrl } from "./provider-url";
+
+type ProviderGetInit = Omit<RequestInit, "body" | "method" | "redirect">;
+type ProviderOutboundConfig = Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork"> & {
+  fetch?: typeof globalThis.fetch;
+};
+export interface ProviderOutboundDependencies {
+  resolveAddresses?: typeof resolvePublicAddresses;
+  pinnedGet?: typeof pinnedHttpGet;
+}
+
+export class ProviderOutboundPolicyError extends Error {
+  override readonly name = "ProviderOutboundPolicyError";
+}
+
+function pickPinnedAddress(addresses: Array<{ address: string; family: number }>): { address: string; family: number } {
+  return addresses.find(address => address.family === 4) ?? addresses[0]!;
+}
+
+function configuredProxyFor(): boolean {
+  return outboundProxyConfigured();
+}
+
+function normalizeProxyHostname(hostname: string): string {
+  const normalized = hostname.trim().toLowerCase().replace(/\.+$/, "");
+  return normalized.startsWith("[") && normalized.endsWith("]")
+    ? normalized.slice(1, -1)
+    : normalized;
+}
+
+function noProxyMatches(url: URL): boolean {
+  const raw = process.env.NO_PROXY ?? process.env.no_proxy ?? "";
+  const hostname = normalizeProxyHostname(url.hostname);
+  const port = url.port || (url.protocol === "https:" ? "443" : "80");
+  for (const rawEntry of raw.split(",")) {
+    let entry = rawEntry.trim().toLowerCase();
+    if (!entry) continue;
+    if (entry === "*") return true;
+    entry = entry.replace(/^https?:\/\//, "").split("/", 1)[0]!;
+
+    let entryHost = entry;
+    let entryPort = "";
+    const bracketed = /^\[([^\]]+)](?::(\d+))?$/.exec(entry);
+    if (bracketed) {
+      entryHost = bracketed[1]!;
+      entryPort = bracketed[2] ?? "";
+    } else if ((entry.match(/:/g)?.length ?? 0) === 1) {
+      const separator = entry.lastIndexOf(":");
+      const possiblePort = entry.slice(separator + 1);
+      if (/^\d+$/.test(possiblePort)) {
+        entryHost = entry.slice(0, separator);
+        entryPort = possiblePort;
+      }
+    }
+    if (entryPort && entryPort !== port) continue;
+    entryHost = normalizeProxyHostname(entryHost.replace(/^\*?\./, ""));
+    if (!entryHost) continue;
+    if (hostname === entryHost || hostname.endsWith(`.${entryHost}`)) return true;
+  }
+  return false;
+}
+
+let proxyBoundaryWarned = false;
+let proxyDnsDegradationWarned = false;
+
+function warnProxyBoundaryOnce(): void {
+  if (proxyBoundaryWarned) return;
+  proxyBoundaryWarned = true;
+  console.warn(
+    "[opencodex] Provider outbound proxy mode preserves Bun proxy/NO_PROXY routing and validates "
+    + "the URL plus available local DNS results; the final route and peer cannot be pinned locally.",
+  );
+}
+
+function warnProxyDnsDegradationOnce(): void {
+  if (proxyDnsDegradationWarned) return;
+  proxyDnsDegradationWarned = true;
+  console.warn(
+    "[opencodex] Local DNS could not resolve a proxied provider hostname; continuing after URL/literal checks. "
+    + "The proxy-selected peer cannot be verified or pinned locally.",
+  );
+}
+
+export async function providerRedirectError(response: Response, requestUrl: string): Promise<string | null> {
+  if (response.status < 300 || response.status >= 400) return null;
+  try { await response.body?.cancel(); } catch { /* ignore cancellation failures */ }
+  const location = response.headers.get("location");
+  let target = "the final upstream URL";
+  if (location) {
+    try { target = publicProviderBaseUrl(new URL(location, requestUrl).toString()); } catch { /* keep fallback */ }
+  }
+  return `provider returned ${response.status} redirect to ${target}; configure the final provider URL directly`;
+}
+
+export async function providerOutboundGet(
+  name: string,
+  provider: ProviderOutboundConfig,
+  url: string,
+  init: ProviderGetInit = {},
+  dependencies: ProviderOutboundDependencies = {},
+): Promise<Response> {
+  if (provider.fetch) {
+    // A caller-owned executor cannot be peer-pinned here. This branch keeps literal/config
+    // checks and redirect blocking, but does not provide the resolved-address guarantees of
+    // the built-in transport. Main-request migration must define that executor contract first.
+    const assessment = assessUrlDestination(url);
+    if (assessment?.kind === "metadata" || assessment?.kind === "link-local" || assessment?.kind === "unspecified") {
+      throw new ProviderOutboundPolicyError(`provider URL targets ${assessment.detail}`);
+    }
+    // Registry defaults count here too, not just the operator flag: a stock Ollama entry is
+    // local by definition and previously passed config validation only to be refused at the
+    // fetch (#758). Metadata/link-local/unspecified were already rejected above.
+    const allowPrivate = providerAllowsPrivateNetwork(name, provider);
+    if (!allowPrivate) {
+      const destinationError = providerDestinationConfigError(name, {
+        baseUrl: url,
+        allowPrivateNetwork: false,
+      });
+      if (destinationError) throw new ProviderOutboundPolicyError(destinationError);
+    }
+    return provider.fetch(url, { ...init, method: "GET", redirect: "manual" });
+  }
+  const parsed = new URL(url);
+  const proxyConfigured = configuredProxyFor();
+  const resolveAddresses = dependencies.resolveAddresses ?? resolvePublicAddresses;
+  const pinnedGet = dependencies.pinnedGet ?? pinnedHttpGet;
+  const allowPrivate = providerAllowsPrivateNetwork(name, provider);
+  let resolved: Awaited<ReturnType<typeof resolvePublicAddresses>>;
+  try {
+    resolved = await resolveAddresses(url, {
+      context: "provider URL",
+      allowPrivateNetwork: allowPrivate,
+    });
+  } catch (error) {
+    const dnsResolutionFailed = error instanceof DestinationDnsResolutionError
+      || (error instanceof Error && error.name === "DestinationDnsResolutionError");
+    if (!dnsResolutionFailed) {
+      throw new ProviderOutboundPolicyError(error instanceof Error ? error.message : "provider destination was blocked");
+    }
+    if (!proxyConfigured) throw error;
+    warnProxyBoundaryOnce();
+    warnProxyDnsDegradationOnce();
+    return globalThis.fetch(url, { ...init, method: "GET", redirect: "manual" });
+  }
+  if (proxyConfigured && !resolved.privateNetwork) {
+    warnProxyBoundaryOnce();
+    return globalThis.fetch(url, { ...init, method: "GET", redirect: "manual" });
+  }
+  if (proxyConfigured && resolved.privateNetwork && !noProxyMatches(parsed)) {
+    const hostname = normalizeProxyHostname(parsed.hostname);
+    throw new Error(
+      `provider URL resolves to a private-network destination; add ${hostname} to NO_PROXY before using allowPrivateNetwork with an outbound proxy`,
+    );
+  }
+  return pinnedGet(url, pickPinnedAddress(resolved.addresses), init.signal ?? undefined, {
+    headers: init.headers,
+    rejectUnauthorized: true,
+    context: "provider response",
+  });
+}

package/src/lib/provider-url.ts

@@ -0,0 +1,14 @@
+/** Strip credentials and non-routing URL components before displaying a provider URL. */
+export function publicProviderBaseUrl(baseUrl: string): string {
+  try {
+    const parsed = new URL(baseUrl.trim());
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "(invalid URL)";
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString().replace(/\/$/, baseUrl.endsWith("/") ? "/" : "");
+  } catch {
+    return "(invalid URL)";
+  }
+}

package/src/lib/proxy-env.ts

@@ -0,0 +1,18 @@
+export const OUTBOUND_PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY"] as const;
+export const PROXY_ENV_KEYS = [...OUTBOUND_PROXY_ENV_KEYS, "NO_PROXY"] as const;
+
+export type ProxyEnvKey = typeof PROXY_ENV_KEYS[number];
+export type ProxyEnvMap = Record<string, string | undefined>;
+
+export function proxyEnvPresent(
+  key: ProxyEnvKey,
+  env: ProxyEnvMap = process.env,
+): boolean {
+  return Boolean(env[key]?.trim() || env[key.toLowerCase()]?.trim());
+}
+
+export function outboundProxyConfigured(
+  env: ProxyEnvMap = process.env,
+): boolean {
+  return OUTBOUND_PROXY_ENV_KEYS.some(key => proxyEnvPresent(key, env));
+}

package/src/lib/redact.ts

@@ -0,0 +1,105 @@
+export const REDACTED_SECRET = "[REDACTED]";
+
+const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn)$/i;
+
+const SECRET_VALUE_PATTERNS: Array<[RegExp, string]> = [
+  [/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}\b/gi, `Bearer ${REDACTED_SECRET}`],
+  [/\b(sk-[A-Za-z0-9][A-Za-z0-9._-]{6,})\b/g, REDACTED_SECRET],
+  // GitHub tokens (classic + fine-grained + OAuth/refresh): ghp_/gho_/ghu_/ghs_/ghr_/github_pat_.
+  [/\b(gh[pousr]_[A-Za-z0-9_]{8,}|github_pat_[A-Za-z0-9_]{20,})\b/g, REDACTED_SECRET],
+  // GitHub Copilot API tokens: semicolon-joined k=v grammar starting with tid=…
+  // (e.g. "tid=abc123;exp=1699999999;sku=copilot_pro;…:sig"). Redact the whole token —
+  // a Bearer-prefix rule alone leaves the suffix intact.
+  [/\btid=[A-Za-z0-9-]+(?:;[A-Za-z0-9_.-]+=[^;\s"']*)+(?::[A-Za-z0-9+/=_-]+)?/g, REDACTED_SECRET],
+  [/\b((?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|client[_-]?secret|refreshToken|accessToken|clientSecret|apiKey)=)([^&\s"',;]+)/gi, `$1${REDACTED_SECRET}`],
+  [/((?:"(?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|client[_-]?secret|refreshToken|accessToken|clientSecret|apiKey)"\s*:\s*"))([^"]+)(")/gi, `$1${REDACTED_SECRET}$3`],
+  // Raw JSON "token" field values (Copilot token exchange bodies echo the credential here).
+  [/(("token"\s*:\s*"))([^"]+)(")/gi, `$1${REDACTED_SECRET}$4`],
+  [/\b(arn:aws:[A-Za-z0-9_-]+:[A-Za-z0-9-]*:\d{12}:[A-Za-z0-9_/:+=,.@-]+)\b/g, REDACTED_SECRET],
+];
+
+type HeaderRecord = Record<string, string | string[] | undefined>;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isSensitiveKey(key: string): boolean {
+  return SENSITIVE_KEY_PATTERN.test(key);
+}
+
+export function redactSecretString(value: string): string {
+  let redacted = value;
+  for (const [pattern, replacement] of SECRET_VALUE_PATTERNS) {
+    redacted = redacted.replace(pattern, replacement);
+  }
+  return redacted;
+}
+
+export function redactSecrets(value: unknown): unknown {
+  if (typeof value === "string") return redactSecretString(value);
+  if (Array.isArray(value)) return value.map(item => redactSecrets(item));
+  if (value instanceof Date) return value;
+  if (!isPlainObject(value)) return value;
+
+  const result: Record<string, unknown> = {};
+  for (const [key, entryValue] of Object.entries(value)) {
+    result[key] = isSensitiveKey(key) ? REDACTED_SECRET : redactSecrets(entryValue);
+  }
+  return result;
+}
+
+export function redactHeaders(headers: Headers | HeaderRecord): Record<string, string> {
+  const result: Record<string, string> = {};
+  const entries = headers instanceof Headers ? headers.entries() : Object.entries(headers);
+
+  for (const [rawKey, rawValue] of entries) {
+    const key = rawKey.toLowerCase();
+    if (rawValue === undefined) continue;
+    const value = Array.isArray(rawValue) ? rawValue.join(", ") : String(rawValue);
+    result[key] = isSensitiveKey(key) ? REDACTED_SECRET : redactSecretString(value);
+  }
+
+  return result;
+}
+
+export function redactUrlForLog(url: string): string {
+  try {
+    const parsed = new URL(url);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return redactSecretString(url.split("?")[0] ?? url);
+  }
+}
+
+const USER_HOME_PATH_PATTERNS: Array<[RegExp, string]> = [
+  // Windows: C:\Users\<name>\...  ->  C:\Users\[USER]\...
+  [/([A-Za-z]:\\Users\\)[^\\/]+/gi, "$1[USER]"],
+  // POSIX: /Users/<name>/... (macOS) and /home/<name>/... (Linux)
+  [/(\/(?:Users|home)\/)[^/]+/gi, "$1[USER]"],
+];
+
+// Path segments whose name alone looks sensitive. Masked so a configured path
+// cannot surface a secret-flavored substring in diagnostics or logs.
+const SENSITIVE_SEGMENT_PATTERN = /(^|[\\/])([^\\/]*(?:secret|password|passwd|token|api[-_]?key|apikey|credential|email)[^\\/]*)(?=[\\/]|$)/gi;
+
+/**
+ * Mask the username segment of an absolute home path so diagnostics can print
+ * paths without leaking the OS account name, and mask any path segment whose
+ * name looks sensitive (token/secret/password/credential/email/...). Path-focused
+ * and secret-safe: also runs {@link redactSecretString} for token-shaped values.
+ */
+export function redactUserPath(path: string): string {
+  let masked = path;
+  for (const [pattern, replacement] of USER_HOME_PATH_PATTERNS) {
+    masked = masked.replace(pattern, replacement);
+  }
+  masked = masked.replace(SENSITIVE_SEGMENT_PATTERN, (_m, sep: string) => `${sep}[REDACTED]`);
+  return redactSecretString(masked);
+}

package/src/lib/retry-after.ts

@@ -0,0 +1,55 @@
+import { parseRetryAfterMs } from "../combos";
+import { classifyError, parseRetryAfterFromMessage } from "./errors";
+
+/** Small default when a retryable 429 has no upstream Retry-After (#507). */
+export const DEFAULT_RETRYABLE_429_RETRY_AFTER_SEC = "2";
+
+/**
+ * Validate a raw upstream Retry-After for client exposure.
+ * Instant-retry `"0"` is kept even though cooldown parsers reject it.
+ */
+export function validateClientRetryAfterHeader(
+  value: string | null | undefined,
+  now: number,
+): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed || trimmed.length > 128) return undefined;
+  // Instant-retry "0" is a valid client directive but rejected by cooldown parsers
+  // (parseRetryAfterMs requires seconds > 0). Preserve it for client headers.
+  if (trimmed === "0") return trimmed;
+  return parseRetryAfterMs(trimmed, now) !== undefined ? trimmed : undefined;
+}
+
+/**
+ * Pick a Retry-After value that clients (especially Codex) can back off on.
+ *
+ * Order: validated upstream header → delay embedded in the error message →
+ * small default for retryable rate-limit 429s. Quota-exhausted 429s get no
+ * default — hammering a spent quota is not a backoff problem.
+ *
+ * Pass `includeDefault: false` when the value feeds cooldown/failover metadata:
+ * the synthetic client fallback must not shorten combo cooldowns from 60s to 2s.
+ */
+export function resolveClientRetryAfter(opts: {
+  status: number;
+  message?: string;
+  upstreamRetryAfter?: string | null;
+  now?: number;
+  includeDefault?: boolean;
+}): string | undefined {
+  const now = opts.now ?? Date.now();
+  const fromHeader = validateClientRetryAfterHeader(opts.upstreamRetryAfter, now);
+  if (fromHeader) return fromHeader;
+
+  const message = opts.message ?? "";
+  const fromMessage = parseRetryAfterFromMessage(message);
+  if (fromMessage !== undefined) return String(fromMessage);
+
+  if (opts.includeDefault === false) return undefined;
+  if (opts.status !== 429) return undefined;
+  const classified = classifyError(429, "rate_limit_error", message || "Too Many Requests");
+  if (classified.type === "insufficient_quota" || classified.code === "insufficient_quota") {
+    return undefined;
+  }
+  return DEFAULT_RETRYABLE_429_RETRY_AFTER_SEC;
+}

package/src/lib/service-secrets.ts

@@ -0,0 +1,25 @@
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { getConfigDir } from "../config";
+
+export function serviceApiTokenFilePath(): string {
+  return join(getConfigDir(), "service-api-token");
+}
+
+/**
+ * App-side service token loading (WinSW native mode has no batch wrapper to read the
+ * token file into the environment). Pure: returns the token or null — the CALLER
+ * assigns it to process.env.OPENCODEX_API_AUTH_TOKEN. Loads only when the env token
+ * is empty and OCX_API_TOKEN_FILE names a readable file.
+ */
+export function loadServiceTokenFromFile(env: Record<string, string | undefined>): string | null {
+  if (env.OPENCODEX_API_AUTH_TOKEN?.trim()) return null;
+  const file = env.OCX_API_TOKEN_FILE?.trim();
+  if (!file) return null;
+  try {
+    const token = readFileSync(file, "utf8").trim();
+    return token || null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/shadow-call.ts

@@ -0,0 +1,30 @@
+/**
+ * Shadow-call intercept source models.
+ *
+ * Codex's hard-coded helper model is not stable across client versions: it was
+ * `gpt-5.4-mini` up to 0.144.x and became `gpt-5.6-luna` in 0.145.0. The
+ * intercept therefore matches a prefix SET, and every surface that names the
+ * intercepted model (management API, GUI badges/tooltips, CLI) reads it from
+ * here instead of hard-coding a slug that goes stale on the next client bump.
+ */
+export const DEFAULT_SHADOW_SOURCE_MODELS = ["gpt-5.4-mini", "gpt-5.6-luna"] as const;
+
+/** Normalize a persisted `sourceModels` override; falls back to the defaults. */
+export function shadowSourceModels(configured?: unknown): string[] {
+  const configuredStrings = Array.isArray(configured)
+    ? configured
+      .filter((v): v is string => typeof v === "string" && v.trim() !== "")
+      .map(v => v.trim())
+    : [];
+  return configuredStrings.length > 0 ? configuredStrings : [...DEFAULT_SHADOW_SOURCE_MODELS];
+}
+
+/**
+ * True when `modelId` is one of Codex's helper/shadow source models.
+ * Routed ids (`provider/model`) are hard-excluded: a shadow call is always a
+ * bare native slug, and an explicit routed selection must never be hijacked.
+ */
+export function isShadowSourceModel(modelId: string, configured?: unknown): boolean {
+  if (modelId.includes("/")) return false;
+  return shadowSourceModels(configured).some(prefix => modelId.startsWith(prefix));
+}

package/src/lib/sidecar-tracker.ts

@@ -0,0 +1,52 @@
+/**
+ * Lightweight in-flight breadcrumb for sidecar work (web-search / vision), read by crash-guard.
+ *
+ * The proxy's unhandled rejections arrive with a native-only stack, so the throw site is invisible.
+ * To confirm or rule out the strong correlation with sidecar activity (the gpt-mini web-search /
+ * vision passes that run an EXTRA upstream fetch alongside the main turn), each sidecar call brackets
+ * itself with enter()/exit(). crash-guard then records whether any sidecar was in flight when a
+ * rejection fired — turning a guess into evidence without a debugger.
+ */
+let inFlight = 0;
+let lastLabel = "";
+let lastEnterAt = 0;
+
+export function sidecarEnter(label: string): () => void {
+  inFlight++;
+  lastLabel = truncateRetainedUtf8(label, MAX_DIAGNOSTIC_VALUE_BYTES);
+  lastEnterAt = Date.now();
+  let exited = false;
+  return () => {
+    if (exited) return;
+    exited = true;
+    if (inFlight > 0) inFlight--;
+  };
+}
+
+export function sidecarBreadcrumb(): { inFlight: number; lastLabel: string; sinceMs: number } {
+  return {
+    inFlight,
+    lastLabel,
+    sinceMs: lastEnterAt ? Date.now() - lastEnterAt : 0,
+  };
+}
+
+/**
+ * Generic last-activity breadcrumb (any code path, not just sidecars). The proxy's native-only
+ * rejections carry no source location, so we record the most recent meaningful activity —
+ * request path + a short note — to correlate the next fault with what the daemon was doing.
+ */
+let lastActivity = "";
+let lastActivityAt = 0;
+
+export function markActivity(note: string): void {
+  lastActivity = truncateRetainedUtf8(note, MAX_DIAGNOSTIC_VALUE_BYTES);
+  lastActivityAt = Date.now();
+}
+
+export function activityBreadcrumb(): { note: string; sinceMs: number } {
+  return { note: lastActivity, sinceMs: lastActivityAt ? Date.now() - lastActivityAt : 0 };
+}
+import { truncateRetainedUtf8 } from "./admission";
+
+const MAX_DIAGNOSTIC_VALUE_BYTES = 8 * 1024;