@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/server/system-env.ts

@@ -1,245 +1,18 @@
 import { execFileSync } from "node:child_process";
-import { accessSync, constants, readFileSync, writeFileSync, unlinkSync, mkdirSync, statSync } from "node:fs";
-import { delimiter, join } from "node:path";
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 import { getConfigDir } from "../config";
 import { resolveAutoContext, type AutoContextMode } from "../claude/context-windows";
-import { PROXY_MARKER, defaultAuthDetectDeps, detectClaudeAuth, ownAdmissionTokens, type AuthDetectDeps } from "../claude/auth-detect";
-import { resolveClaudeAuthMode } from "../claude/auth-mode";
-import { ANTHROPIC_PARENT_ENV_SLOTS, trustedNodeLauncherContext, type AnthropicParentEnvSlot } from "../cli/launcher-context";
+import { PROXY_MARKER } from "../claude/auth-detect";
 import { isProxyAdmissionSecret } from "./auth-cors";
 import type { OcxConfig } from "../types";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { providerContextCap } from "../providers/context-cap";
 import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
-
-/**
- * Does the opencodex dummy marker belong in the system environment?
- *
- * Keyed on the SAME resolver `ocx claude` uses, so an auto config with no Claude auth
- * also reaches plain `claude` launches — before this, auto-absent users got nothing
- * from auto-connect and the feature looked broken for exactly the people it helps
- * (devlog 260726_claude_auth_auto/035).
- *
- * NOTE this is a SNAPSHOT: the file only changes when this runs (proxy start, `ocx
- * ensure`, or a settings save). `ocx claude` re-resolves live on every launch.
- */
-export type SystemEnvDeps = {
-  /** Test seam; production uses the authenticated Node-launcher context. */
-  preBunAnthropicSlots?: readonly AnthropicParentEnvSlot[] | null;
-  /** Test seam for auth sources; `env` and `ownTokens` stay bound below. */
-  authDetect?: Omit<Partial<AuthDetectDeps>, "env" | "ownTokens">;
-};
-
-/**
- * Bun may synthesize Anthropic variables from a project `.env` before this module runs.
- * Only values recorded by the plain-Node launcher are trusted as parent exports. Direct
- * Bun/service launches have no proof-bound slot list, so they fail closed and let the
- * file/keychain auth sources decide instead of allowing dotenv to select subscription mode.
- */
-function systemEnvAnthropicEnv(
-  env: NodeJS.ProcessEnv,
-  preBunAnthropicSlots: readonly AnthropicParentEnvSlot[] | null | undefined,
-): NodeJS.ProcessEnv {
-  const trustedSlots = preBunAnthropicSlots === undefined
-    ? trustedNodeLauncherContext()?.anthropicEnvSlots ?? []
-    : preBunAnthropicSlots ?? [];
-  const exported = new Set<AnthropicParentEnvSlot>(trustedSlots);
-  const sanitized = { ...env };
-  for (const name of ANTHROPIC_PARENT_ENV_SLOTS) {
-    if (sanitized[name] !== undefined && !exported.has(name)) delete sanitized[name];
-  }
-  return sanitized;
-}
-
-function systemEnvMarkerMode(config: OcxConfig, deps: SystemEnvDeps = {}): "proxy" | "subscription" {
-  const env = systemEnvAnthropicEnv(process.env, deps.preBunAnthropicSlots);
-  const ownTokens = ownAdmissionTokens(config);
-  return resolveClaudeAuthMode(config, detectClaudeAuth({
-    ...defaultAuthDetectDeps(env, ownTokens),
-    ...(deps.authDetect ?? {}),
-    env: () => env,
-    ownTokens,
-  })).markerMode;
-}
-
-// ---------------------------------------------------------------------------
-// Shell-hook env file: written on inject, sourced by the shell hook in .zshrc.
-// This works for ALL new shells immediately, unlike launchctl setenv which only
-// reaches processes launched directly by launchd (not Terminal.app children).
-// ---------------------------------------------------------------------------
-
-export function getShellEnvFilePath(): string {
-  return join(getConfigDir(), "claude-env.sh");
-}
-
-function shellValue(value: string): string {
-  return `'${value.replaceAll("'", `'\\''`)}'`;
-}
-
-function writeShellEnvFile(
-  port: number,
-  config: OcxConfig,
-  modelEnv: Record<string, string> = {},
-  auto?: AutoContextMode,
-  deps: SystemEnvDeps = {},
-): void {
-  const lines = [
-    `# Generated by opencodex — do not edit manually`,
-    `export ANTHROPIC_BASE_URL=${shellValue(`http://127.0.0.1:${port}`)}`,
-    `export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=${shellValue("1")}`,
-  ];
-  // New lever keys are CONDITIONAL exports (audit 139 R2#1): a value the user already
-  // exported in their shell wins even though launchctl knows nothing about it.
-  const conditional = (name: string, value: string) =>
-    `[ -z "\${${name}+x}" ] && export ${name}=${shellValue(value)}`;
-  if (systemEnvMarkerMode(config, deps) === "proxy") {
-    if (config.apiKeys?.length) {
-      lines.push(`export ANTHROPIC_AUTH_TOKEN=${shellValue(config.apiKeys[0].key)}`);
-    } else {
-      lines.push(conditional("ANTHROPIC_AUTH_TOKEN", PROXY_MARKER));
-    }
-  }
-  // Model slots (default + tiers + legacy small-fast) with [1m] applied (devlog 260712 B2).
-  if (modelEnv.ANTHROPIC_MODEL) {
-    lines.push(`export ANTHROPIC_MODEL=${shellValue(modelEnv.ANTHROPIC_MODEL)}`);
-  } else if (config.claudeCode?.model) {
-    lines.push(`export ANTHROPIC_MODEL=${shellValue(config.claudeCode.model)}`);
-  }
-  for (const [name, value] of Object.entries(modelEnv)) {
-    if (name === "ANTHROPIC_MODEL") continue;
-    lines.push(conditional(name, value));
-  }
-  const maxCtx = config.claudeCode?.maxContextTokens;
-  if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
-    lines.push(conditional("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx))));
-    lines.push(conditional("DISABLE_COMPACT", "1"));
-  }
-  // Auto-context (devlog 260712 020): same contract as `ocx claude` / launchctl.
-  const autoShell = auto ?? resolveAutoContext(config.claudeCode);
-  if (autoShell.enabled) lines.push(conditional("CLAUDE_CODE_AUTO_COMPACT_WINDOW", String(autoShell.compactWindow)));
-  if (config.claudeCode?.alwaysEnableEffort === true) {
-    lines.push(conditional("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1"));
-  }
-  const shellEnvPath = getShellEnvFilePath();
-  recordOwnedConfigPath(getConfigDir(), shellEnvPath);
-  mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
-  writeFileSync(shellEnvPath, lines.join("\n") + "\n", { encoding: "utf8", mode: 0o600 });
-}
-
-function removeShellEnvFile(): void {
-  try { unlinkSync(getShellEnvFilePath()); } catch { /* already gone */ }
-}
-
-// ---------------------------------------------------------------------------
-// .zshrc hook auto-install: adds a one-liner that sources claude-env.sh.
-// Idempotent — skips if the hook line already exists.
-// ---------------------------------------------------------------------------
-
-const SHELL_HOOK_MARKER = "# opencodex claude-env hook";
-const SHELL_HOOK_LINE = `${SHELL_HOOK_MARKER}\n[ -f ~/.opencodex/claude-env.sh ] && source ~/.opencodex/claude-env.sh`;
-
-export function installShellHook(): { installed: boolean; reason?: string } {
-  if (process.platform !== "darwin") return { installed: false, reason: "not macOS" };
-  const home = process.env.HOME;
-  if (!home) return { installed: false, reason: "no HOME" };
-  const zshrcPath = join(home, ".zshrc");
-  try {
-    let content = "";
-    try { content = readFileSync(zshrcPath, "utf8"); } catch { /* file doesn't exist yet */ }
-    if (content.includes(SHELL_HOOK_MARKER)) return { installed: false, reason: "already installed" };
-    const addition = `\n${SHELL_HOOK_LINE}\n`;
-    writeFileSync(zshrcPath, content + addition, { encoding: "utf8", mode: 0o644 });
-    return { installed: true };
-  } catch (err) {
-    return { installed: false, reason: `write failed: ${err instanceof Error ? err.message : String(err)}` };
-  }
-}
-
-export function uninstallShellHook(): { removed: boolean; reason?: string } {
-  if (process.platform !== "darwin") return { removed: false, reason: "not macOS" };
-  const home = process.env.HOME;
-  if (!home) return { removed: false, reason: "no HOME" };
-  const zshrcPath = join(home, ".zshrc");
-  try {
-    const content = readFileSync(zshrcPath, "utf8");
-    if (!content.includes(SHELL_HOOK_MARKER)) return { removed: false, reason: "not installed" };
-    // Match CR?LF, not LF alone. A .zshrc with CRLF line endings — ordinary on a home
-    // directory an editor or another OS has touched — did not match, so the file was
-    // rewritten unchanged and the caller was told the hook was removed. Reporting success
-    // while the hook still sources on every new shell is the worse of the two failures.
-    const cleaned = content.replace(/\r?\n?# opencodex claude-env hook\r?\n\[.*claude-env\.sh.*(?:\r?\n)?/g, "\n");
-    // Verify instead of assuming: if the marker survives, the block is shaped in a way this
-    // pattern does not own, and the honest answer is failure rather than a silent no-op.
-    if (cleaned.includes(SHELL_HOOK_MARKER)) {
-      return { removed: false, reason: "hook block present but not in the expected shape; remove it manually" };
-    }
-    writeFileSync(zshrcPath, cleaned, { encoding: "utf8", mode: 0o644 });
-    return { removed: true };
-  } catch (error) {
-    if (error && typeof error === "object" && (error as { code?: unknown }).code === "ENOENT") {
-      return { removed: false, reason: "not installed" };
-    }
-    return { removed: false, reason: "read/write failed" };
-  }
-}
-
-/** Whether a real `claude` executable is discoverable from this process's PATH. */
-export function claudeCodeCliInstalled(pathValue = process.env.PATH): boolean {
-  if (!pathValue) return false;
-  for (const directory of pathValue.split(delimiter)) {
-    // An empty PATH segment means the current directory. Do not let the proxy treat a
-    // workspace-local file as a durable user installation.
-    if (!directory) continue;
-    const candidate = join(directory, "claude");
-    try {
-      if (!statSync(candidate).isFile()) continue;
-      accessSync(candidate, constants.X_OK);
-      return true;
-    } catch {
-      // Keep scanning PATH after missing, non-file, and non-executable entries.
-    }
-  }
-  return false;
-}
-
-/**
- * Keep the shell hook aligned with the integration that can actually consume it.
- * Claude Desktop uses its own profile and does not source `.zshrc`; this hook exists
- * only for plain Claude Code CLI launches.
- *
- * Reconciliation is PATH-sensitive by construction: "Claude Code is installed" is answered
- * from the PATH of whichever process calls this. A launchd/service context with a stripped
- * PATH can therefore fail to see a `claude` the user's interactive shell finds, and this will
- * remove the hook. That is the intended failure direction — removing an OpenCodex-owned block
- * is reversible on the next foreground `ocx start`, whereas leaving a hook pointing at an
- * uninstalled CLI is the stale state this reconciliation exists to clear. Only the block
- * carrying our own marker is ever touched; user lines are preserved.
- */
-export function reconcileShellHook(systemEnvInjected: boolean): {
-  changed: boolean;
-  state: "installed" | "absent" | "failed";
-  reason?: string;
-} {
-  if (process.platform !== "darwin") return { changed: false, state: "absent", reason: "not macOS" };
-  if (systemEnvInjected && claudeCodeCliInstalled()) {
-    const result = installShellHook();
-    if (result.installed) return { changed: true, state: "installed" };
-    if (result.reason === "already installed") {
-      return { changed: false, state: "installed", reason: result.reason };
-    }
-    return { changed: false, state: "failed", reason: result.reason ?? "install failed" };
-  }
-
-  const result = uninstallShellHook();
-  if (!result.removed && result.reason !== "not installed") {
-    return { changed: false, state: "failed", reason: result.reason ?? "remove failed" };
-  }
-  return {
-    changed: result.removed,
-    state: "absent",
-    reason: systemEnvInjected ? "Claude Code not installed" : "system environment inactive",
-  };
-}
+export { getShellEnvFilePath, installShellHook, uninstallShellHook, claudeCodeCliInstalled, reconcileShellHook } from "./system-env-shell";
+export type { SystemEnvDeps } from "./system-env-shell";
+import { systemEnvMarkerMode, writeShellEnvFile, removeShellEnvFile } from "./system-env-shell";
+import type { SystemEnvDeps } from "./system-env-shell";
 
 const SYSTEM_ENV_NAMES = [
   "ANTHROPIC_BASE_URL",

package/src/server/ws-bridge.ts

@@ -7,19 +7,13 @@ import type { ResponsesTerminalStatus } from "../bridge";
 import type { DataPlaneAdmission } from "./auth-cors";
 import type { AdmissionLease, AdmissionReservation } from "../lib/admission";
 import { BoundedSseFrameBuffer } from "./sse-frame-buffer";
+import { safeResponseHeaders } from "./safe-response-headers";
+
+export { safeResponseHeaders } from "./safe-response-headers";
 
 const OPEN = 1;
 type ResponsesTerminalReporter = (status: ResponsesTerminalStatus) => void;
 type ResponsesPayloadObserver = (payload: string) => void;
-const SAFE_RESPONSE_HEADER_EXACT = new Set([
-  "retry-after",
-  "x-request-id",
-  "openai-request-id",
-  "x-codex-turn-state",
-  "openai-model",
-  "x-models-etag",
-  "x-reasoning-included",
-]);
 
 export interface WsData {
   headers?: Headers; // base inbound forward headers only; per-turn auth refresh injects current pool tokens
@@ -104,22 +98,6 @@ export function selectForwardHeadersForAuthContext(headers: Headers, ctx: CodexA
   return headersForCodexAuthContext(headers, ctx);
 }
 
-export function safeResponseHeaders(headers: Headers): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const [name, value] of headers) {
-    const lower = name.toLowerCase();
-    if (
-      SAFE_RESPONSE_HEADER_EXACT.has(lower) ||
-      lower.startsWith("x-ratelimit-") ||
-      /^x-codex(?:-[a-z0-9-]+)?-(primary|secondary|tertiary)-(used-percent|window-minutes|reset-at)$/.test(lower) ||
-      /^x-codex(?:-[a-z0-9-]+)?-limit-name$/.test(lower)
-    ) {
-      out[lower] = value;
-    }
-  }
-  return out;
-}
-
 export function buildWarmupCompletionFrames(frame: Record<string, unknown>): string[] {
   const createdAt = Math.floor(Date.now() / 1000);
   const baseResponse: Record<string, unknown> = {

package/src/server/xai-responses-startup.ts

@@ -0,0 +1,21 @@
+import { mutatePersistedConfig } from "../config";
+import { migrateXaiResponsesDefault } from "../providers/xai-responses-opt-in";
+import type { OcxConfig } from "../types";
+
+/** Rebase the one-time wire upgrade before initializing any live config consumers. */
+export function migrateStartupXaiResponses(config: OcxConfig): OcxConfig {
+  const projection = { ...config };
+  if (!migrateXaiResponsesDefault(projection)) return config;
+  try {
+    const outcome = mutatePersistedConfig(fresh => ({
+      changed: migrateXaiResponsesDefault(fresh),
+      value: fresh,
+    }));
+    if (outcome.status !== "unavailable") return outcome.value;
+    console.warn(`[xai-responses-migration] Persistence unavailable (${outcome.reason}); using Responses in memory only.`);
+  } catch {
+    // Filesystem errors can carry private paths. Startup must still remain available.
+    console.warn("[xai-responses-migration] Persistence failed; using Responses in memory only.");
+  }
+  return projection;
+}

package/src/service-manager-probe.ts

@@ -619,7 +619,7 @@ function windowsTaskListContains(body: string, taskName: string): boolean {
  * denied", so a locked-down host answers the control and the real query
  * identically, and comparing them yields a false `absent` — the one direction
  * that lets an unattended write proceed into a home another process owns.
- * `tests/codex-service-manager-probe.test.ts` covers exactly that host.
+ * `tests/codex-integration/codex-service-manager-probe.test.ts` covers exactly that host.
  */
 const SCHTASKS_TASK_NOT_FOUND_EN = /cannot find the file specified/i;
 

package/src/service.ts

@@ -205,9 +205,9 @@ export interface ServiceInstallState {
   bunPath?: string;
   cliPath?: string;
   /**
-   * Linux only. The stable `ocx` launcher the unit actually invokes, when one was found.
-   * Present means `bunPath`/`cliPath` are provenance for the install, NOT what systemd
-   * runs — so staleness must be judged against THIS path instead. A version-manager
+   * launchd and systemd. The stable `ocx` launcher the service definition actually invokes,
+   * when one was found. Present means `bunPath`/`cliPath` are provenance for the install,
+   * NOT what the service runs — so staleness must be judged against THIS path instead. A version-manager
    * upgrade replaces the directory those two point into while the launcher survives, and
    * checking the old pair would report a stale service that is in fact healthy.
    */
@@ -486,8 +486,21 @@ function writeServiceApiTokenFile(): string | null {
   return path;
 }
 
-export function buildPlist(proxyEnv: { name: string; value: string }[] = resolvedProxyEnv()): string {
-  const { bun, bunRuntimeSource, cli } = cliEntry();
+/**
+ * Render the launchd plist. Mirrors `buildUnit`: when `deps.launcher` names a stable `ocx`
+ * executable, the job execs that launcher instead of the package-local Bun + CLI pair, so a
+ * version-manager upgrade (mise, asdf, nvm) that replaces the package directory is picked up
+ * on the next launchd start instead of leaving the old build serving (#3464 — the macOS
+ * counterpart of #2898). Discovery belongs to `installLaunchd()`; the default here is the
+ * legacy pair so callers and tests stay hermetic.
+ */
+export function buildPlist(
+  proxyEnv: { name: string; value: string }[] = resolvedProxyEnv(),
+  deps: { launcher?: string | null; runtime?: DurableBunRuntime } = {},
+): string {
+  const runtime = deps.runtime ?? durableBunRuntime();
+  const { bun, bunRuntimeSource, cli } = cliEntry(runtime);
+  const launcher = deps.launcher ?? null;
   const log = logPath();
   const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
   const codexHome = process.env.CODEX_HOME?.trim();
@@ -495,8 +508,16 @@ export function buildPlist(proxyEnv: { name: string; value: string }[] = resolve
   const opencodexHome = process.env.OPENCODEX_HOME?.trim();
   const envLines = [
     `    <key>OCX_SERVICE</key><string>1</string>`,
-    `    <key>${BUN_RUNTIME_SOURCE_ENV}</key><string>${bunRuntimeSource}</string>`,
-    `    <key>${BUN_RUNTIME_PATH_ENV}</key><string>${plistString(bun)}</string>`,
+    ...(launcher ? [] : [
+      `    <key>${BUN_RUNTIME_SOURCE_ENV}</key><string>${bunRuntimeSource}</string>`,
+      `    <key>${BUN_RUNTIME_PATH_ENV}</key><string>${plistString(bun)}</string>`,
+    ]),
+    // A launcher resolves the current package's bundled Bun after every upgrade. Preserve
+    // only a proof-bound shell override; baking a package-local path here would recreate
+    // the version-manager pin that launcher mode exists to remove (same rule as buildUnit).
+    launcher && runtime.source === "override"
+      ? `    <key>${runtime.overrideEnv}</key><string>${plistString(runtime.path)}</string>`
+      : null,
     `    <key>PATH</key><string>${plistString(path)}</string>`,
     codexHome ? `    <key>CODEX_HOME</key><string>${plistString(codexHome)}</string>` : null,
     codexSqliteHome ? `    <key>CODEX_SQLITE_HOME</key><string>${plistString(codexSqliteHome)}</string>` : null,
@@ -504,7 +525,9 @@ export function buildPlist(proxyEnv: { name: string; value: string }[] = resolve
     ...proxyEnv.map(({ name, value }) =>
       `    <key>${name}</key><string>${plistString(value)}</string>`),
   ].filter((line): line is string => Boolean(line)).join("\n");
-  const command = buildServiceShellCommand(bun, cli);
+  const command = launcher
+    ? buildServiceLauncherShellCommand(launcher)
+    : buildServiceShellCommand(bun, cli);
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -569,6 +592,23 @@ function buildServiceLauncherShellCommand(launcher: string, port = resolveServic
   return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(launcher)} start --port ${port}`;
 }
 
+/**
+ * The exec line the installed launchd plist is expected to carry, derived from the recorded
+ * install state rather than rediscovered: a launcher install runs the launcher, a legacy or
+ * stateless install runs the Bun + CLI pair. `start` and `status` compare the live job
+ * against this, so both must follow the launcher or a healthy launcher-backed job reads as
+ * "an OLDER plist" (#3464). PATH is deliberately NOT re-walked here.
+ */
+export function expectedLaunchdCommand(
+  port: number,
+  deps: { state?: ServiceInstallState | null; entry?: { bun: string; cli: string } } = {},
+): string {
+  const state = deps.state === undefined ? readServiceInstallState() : deps.state;
+  if (state?.launcherPath) return buildServiceLauncherShellCommand(state.launcherPath, port);
+  const entry = deps.entry ?? cliEntry();
+  return buildServiceShellCommand(entry.bun, entry.cli, port);
+}
+
 /**
  * The `--port <n>` actually baked into the installed launchd plist, or null when it
  * cannot be read. macOS only — named for launchd rather than "service" so no caller
@@ -2251,7 +2291,10 @@ function installLaunchd(): void {
   // Capture this BEFORE writing: the write below makes the plist exist unconditionally,
   // so a post-write existsSync would call every fresh install an "installed" service.
   const wasInstalled = existsSync(p);
-  writeServiceDefinitionFile(p, buildPlist(), "utf8");
+  // Resolve the launcher ONCE and hand the same value to the plist and to install state,
+  // so the staleness diagnostic judges exactly what launchd runs.
+  const launcher = stableLauncherEntry();
+  writeServiceDefinitionFile(p, buildPlist(resolvedProxyEnv(), { launcher }), "utf8");
   // Best-effort: an absent job is fine here, and a failed unload is caught by the
   // load verification below with a better message than a raw unload error.
   runLaunchctl(["unload", p]);
@@ -2268,7 +2311,7 @@ function installLaunchd(): void {
       + `then re-run '${wasInstalled ? "ocx service repair" : "ocx service install"}'.`,
     );
   }
-  writeServiceInstallState();
+  writeServiceInstallState("scheduler", launcher);
 }
 /**
  * Deps are named for the layer they replace, not for the process API: `launchctl`
@@ -2291,9 +2334,8 @@ export function startLaunchd(deps: {
   // already be bootstrapped from THIS plist, which is a no-op rather than an error.
   // `install` can assume a stale job (it just rewrote the plist); `start` cannot, and
   // throwing here would break `ocx service start` on every healthy service.
-  const entry = cliEntry();
   const live = (deps.matches ?? launchdJobMatchesPlist)(
-    buildServiceShellCommand(entry.bun, entry.cli),
+    expectedLaunchdCommand(installedServiceListenPort()),
   );
   if (live.loaded && live.matchesPlist) {
     console.log("ℹ️  service was already loaded from the current plist; nothing to do.");
@@ -4234,14 +4276,11 @@ export async function serviceStatusReport(
   // Linux/Windows and make the stale-plist case untestable there.
   const stalePlist = deps.matchesPlist?.() ?? (process.platform === "darwin"
     ? (() => {
-        const entry = cliEntry();
         // Pass the INSTALLED port explicitly: the default third argument is
         // resolveServiceListenPort(), which reads OCX_BAKE_PORT/config.port, so after
         // a config edit the expected string would never match and every run would
         // print a false "OLDER plist".
-        return launchdJobMatchesPlist(
-          buildServiceShellCommand(entry.bun, entry.cli, installedServiceListenPort()),
-        );
+        return launchdJobMatchesPlist(expectedLaunchdCommand(installedServiceListenPort()));
       })()
     : null);
   const staleLine = stalePlist && stalePlist.loaded && !stalePlist.matchesPlist

package/src/types/config.ts

@@ -375,6 +375,27 @@ export interface OcxConfig {
    * from Cursor's built-in effort table. Omitted/false preserves discovery output.
    */
   cursorEffortRows?: boolean;
+  /**
+   * Default-on synthetic Fast selectors. The raw OpenAI-style `/v1/models` list and
+   * Claude Code discovery add a `<base-id>--fast` row for every model whose resolved Fast
+   * policy is eligible, and selecting one routes the base model with the canonical
+   * `priority` service tier. Client config exports include the same selectors. Set false
+   * to disable them; omission enables them.
+   */
+  fastRows?: boolean;
+  /**
+   * Opt-in Ultra Fast service tier, default off.
+   *
+   * This does NOT synthesize an `ultrafast` row: `src/codex/data/upstream-models.json`
+   * advertises only `priority`, and PR #2994 was closed precisely because a catalog row
+   * the wire cannot honor is a picker entry that lies. What the flag turns on is honesty
+   * about a tier the operator supplies themselves — the catalog stops stripping an
+   * `ultrafast` the user configured, and the request path names it instead of recording
+   * "no fast tier was requested".
+   */
+  ultraFastTier?: boolean;
+  /** Stop new identity-matched main-account requests at observed 99% usage. Default off. */
+  codexMainAccountHardLock?: boolean;
   /** Explicit top-level deletion intent used by stale whole-config rebases. */
   configRebaseProvenance?: OcxConfigRebaseProvenance | Record<string, unknown>;
   /** OpenAI provider-contract migration marker (v2 = single `openai` provider with account mode). */
@@ -395,6 +416,8 @@ export interface OcxConfig {
    * into a selector-qualified group; Codex still advertises only the first 5 visible rows.
    */
   subagentModels?: string[];
+  /** One-time featured-roster upgrade marker; later user ordering is preserved. */
+  subagentModelsVersion?: number;
   /**
    * Optional full picker ordering for the Codex model catalog, independent of the
    * 5-slot `subagentModels` spawn_agent cap. DISPLAY-ONLY: it controls the visual order of
@@ -573,6 +596,13 @@ export interface OcxConfig {
     /** Maximum in-memory ciphertext-to-assignment entries. Default: 200. */
     cacheEntries?: number;
   };
+  /**
+   * Quota-reset detection and notification. Absent means off: no detection, no timer, no sink.
+   *
+   * Not in `getDefaultConfig()` on purpose — that function carries no optional-feature keys,
+   * so absence is the only default state this feature has.
+   */
+  quotaResetNotify?: OcxQuotaResetNotifyConfig;
   /** Provider-level Codex-visible context caps. Values only lower known model context windows. */
   providerContextCaps?: Record<string, number>;
   /** Global Codex-visible context cap value (tokens). Falls back to DEFAULT_PROVIDER_CONTEXT_CAP. */
@@ -675,6 +705,14 @@ export interface OcxConfig {
   codexAccounts?: CodexAccount[];
   /** Account ids administratively excluded from future pool selection until resumed. */
   pausedCodexAccountIds?: string[];
+  /** Opt-in per-account activation of newly reset Codex quota windows. */
+  codexQuotaAutoRefresh?: Record<string, {
+    fiveHour?: boolean;
+    weekly?: boolean;
+    /** Upstream reset timestamps already activated, retained across restarts. */
+    lastFiveHourResetAt?: number;
+    lastWeeklyResetAt?: number;
+  }>;
   /**
    * Selection order per account id, higher used earlier; absent = 0. Keyed by id
    * rather than stored on `codexAccounts` rows so the Desktop login (`__main__`),
@@ -742,9 +780,14 @@ export interface OcxConfig {
    */
   maxUpstreamBodyBytes?: number;
   /**
-   * Opt-in Anthropic OAuth account pool (#294). Default OFF.
-   * Failover on 429 + sticky affinity; new sessions may pick lowest known 5h usage.
+   * Opt-in Anthropic OAuth PROACTIVE routing (#294). Default OFF.
+   * Sticky session affinity; new sessions may pick lowest known 5h usage.
    * Experimental — see docs and GUI warning before enabling.
+   *
+   * Reactive 429 failover is NOT gated here. It activates on account presence, like every
+   * other multi-credential provider, and cannot be switched off: rotating away from an account
+   * upstream has just rate-limited only ever runs after a refusal, so stranding it while a
+   * second logged-in account sits idle is a defect rather than a configuration choice.
    */
   anthropicAccountPool?: {
     enabled?: boolean;
@@ -758,17 +801,17 @@ export interface OcxConfig {
     quotaWindow?: OcxAccountPoolQuotaWindow;
   };
   /**
-   * Generic OAuth multi-account 429 failover (#2568). Presence-driven by default.
+   * Generic OAuth multi-account PROACTIVE account preference (#2568, #695).
    *
-   * Rotates to another logged-in account of the SAME provider when one is rate-limited, for
-   * OAuth providers that have no pool of their own — xAI, Cursor, Kimi, GitHub Copilot,
-   * Antigravity, Nous. The Codex pool and the Anthropic pool own their own rotation and are
-   * excluded; this setting changes neither.
+   * Reactive 429 rotation — moving to another logged-in account of the SAME provider when one
+   * is rate-limited — is presence-driven and NOT configurable here. It activates whenever a
+   * provider has 2 or more eligible stored accounts, the same consent rule an `apiKeyPool` of
+   * two keys already applies, and a single account remains a strict no-op.
    *
-   * With the key absent, rotation activates when a provider has 2 or more eligible stored
-   * accounts — the same consent rule API-key pools already apply to a 2+ key pool (#2568d). A
-   * single account is a strict no-op. Set `false` to keep strict single-account behaviour;
-   * `providers.<name>.oauthAccountFailover` overrides this per provider.
+   * What `enabled: false` still refuses is the PRE-DISPATCH preference: steering a request
+   * upstream has not refused toward the account with more known headroom. That moves a healthy
+   * request, so it stays a real choice. `providers.<name>.oauthAccountFailover` overrides this
+   * per provider in either direction; reactive 429 rotation remains presence-driven.
    */
   oauthAccountFailover?: {
     enabled?: boolean;
@@ -820,6 +863,14 @@ export interface OcxComboConfig {
   strategy?: OcxComboStrategy;
   /** Successful requests retained on one RR selection batch. Default 1; range 1..100. */
   stickyLimit?: number;
+  /**
+   * Optional per-target cooldown used only when the upstream response has no Retry-After or Codex reset signal.
+   * Unset uses the upstream fallback (5 s for request-rate 429 codes 1302/1305, otherwise 60 s);
+   * an explicit value overrides that fallback. Range 1..600000.
+   */
+  cooldownMs?: number;
+  /** Maximum wait for an eligible target cooldown to expire before failing closed. Default 0; range 0..600000, per selection attempt. */
+  waitForCooldownMs?: number;
   /** Used when the client omits reasoning.effort. null/omitted leaves the target default unchanged. */
   defaultEffort?: OcxComboDefaultEffort | null;
   /**
@@ -1062,6 +1113,51 @@ export interface OcxWebSearchSidecarConfig {
    * stays atomic. Tradeoff: text the model emits BEFORE deciding to search — which buffered mode
    * silently drops — becomes visible to the client and may partially repeat in the post-search
    * answer. Default: false (buffered, previous behavior).
-   */
+  */
   streamRoutedModelOutput?: boolean;
 }
+
+/**
+ * Quota-reset notification settings.
+ *
+ * Every field is optional and the whole section defaults to off. `enabled: true` alone is not
+ * sufficient: without a webhook or a command there is nowhere to deliver, and treating that as
+ * off is what keeps the "a default install runs no detection code" guarantee true rather than
+ * nearly true.
+ */
+export interface OcxQuotaResetNotifyConfig {
+  /** Master switch. Default false — nothing detects, nothing polls, nothing fires. */
+  enabled?: boolean;
+  /** Which reset kinds to deliver. Default: both. */
+  kinds?: Array<"scheduled" | "surprise">;
+  /**
+   * Idle poll interval in seconds. Default 900, floor 60, and 0 disables polling entirely.
+   *
+   * Polling exists because the interesting case is a reset that happens while no request is in
+   * flight: without a poll, a window that reset overnight is only noticed on the next request.
+   */
+  pollSeconds?: number;
+  /**
+   * POST the event as JSON here.
+   *
+   * Treated as a credential: for Slack and Discord the URL itself is the authorization, so it
+   * is redacted by `ocx config show` and excluded from `config export`.
+   */
+  webhookUrl?: string;
+  /**
+   * Permit a loopback or private-network webhook target. Default false.
+   *
+   * An operator-supplied URL is an SSRF surface, so the default refuses anything that resolves
+   * private. Self-hosted receivers are the legitimate case for opting in.
+   */
+  allowPrivateNetwork?: boolean;
+  /** Webhook timeout in milliseconds. Default 5000. */
+  timeoutMs?: number;
+  /**
+   * Run a local command with the event JSON on stdin.
+   *
+   * An argv array, never a shell string: the command is spawned directly, so an operator value
+   * cannot become a shell-injection surface.
+   */
+  command?: string[];
+}