@bitkyc08/opencodex 2.89.0 → 2.91.0

package/src/codex/shim-templates.ts

@@ -5,7 +5,14 @@ import { selfLaunchArgv } from "../lib/self-launch-argv";
 import { windowsEnvIndirectBatchValue } from "../lib/win-paths";
 
 const SHIM_MARKER = "opencodex codex autostart shim";
-const UNIX_SHIM_REVISION_MARKER = "opencodex unix codex shim revision 3";
+// Revision 4: OCX_SHIM_BYPASS skips loading the service API token. Bumping the marker
+// makes installed revision-3 wrappers obsolete so the existing refresh path rewrites them.
+const UNIX_SHIM_REVISION_MARKER = "opencodex unix codex shim revision 4";
+// Windows CMD and PowerShell wrappers carry their own revision. Revision 1 is the first one that
+// skips the service token under OCX_SHIM_BYPASS; a marked wrapper without it is obsolete and
+// install/auto-restore rewrite it in place. (The extensionless Git-Bash wrapper is the Unix
+// template and carries the Unix revision.)
+const WINDOWS_SHIM_REVISION_MARKER = "opencodex windows codex shim revision 1";
 
 const CODEX_SHIM_REENTRY_EXIT_CODE = 126;
 const CODEX_SHIM_REENTRY_DIAGNOSTIC = "opencodex: saved Codex launcher resolved back to the autostart shim; run ocx codex-shim uninstall and reinstall Codex before enabling codexAutoStart.";
@@ -122,7 +129,9 @@ esac
 # redispatch reaches depth 2 and is rejected before it can form an infinite chain.
 OCX_SHIM_ACTIVE_PID=$$
 export OCX_SHIM_ACTIVE_PID OCX_SHIM_ACTIVE_DEPTH
-if [ -z "$OPENCODEX_API_AUTH_TOKEN" ] && [ -f ${shQuote(tokenFile)} ]; then
+# A bypassed launch is native passthrough: it never talks to this proxy, so it must not
+# hand the proxy's data-plane token to the real Codex and everything Codex spawns.
+if [ -z "$OCX_SHIM_BYPASS" ] && [ -z "$OPENCODEX_API_AUTH_TOKEN" ] && [ -f ${shQuote(tokenFile)} ]; then
   OPENCODEX_API_AUTH_TOKEN="$(cat ${shQuote(tokenFile)})"
   export OPENCODEX_API_AUTH_TOKEN
 fi
@@ -190,13 +199,14 @@ export function buildWindowsCodexShim(realCodexPath: string, bunPath: string, cl
   const cliArgs = selfLaunchArgv([], { sourceEntrypoint: cliPath, isStandaloneExecutable: bunRuntimeSource === "standalone" });
   return `@echo off\r
 rem ${SHIM_MARKER}\r
+rem ${WINDOWS_SHIM_REVISION_MARKER}\r
 setlocal\r
 ${windowsBatchSet("OCX_REAL_CODEX", realCodexPath)}\r
 ${windowsBatchSet("OCX_BUN", bunPath)}\r
 ${cliArgs.length ? windowsBatchSet("OCX_CLI", cliArgs[0]!) : ""}\r
 ${windowsBatchSet("OCX_API_TOKEN_FILE", serviceApiTokenFilePath())}\r
-if "%OPENCODEX_API_AUTH_TOKEN%"=="" if exist "%OCX_API_TOKEN_FILE%" set /p OPENCODEX_API_AUTH_TOKEN=<"%OCX_API_TOKEN_FILE%"\r
 if not "%OCX_SHIM_BYPASS%"=="" goto run_codex\r
+if "%OPENCODEX_API_AUTH_TOKEN%"=="" if exist "%OCX_API_TOKEN_FILE%" set /p OPENCODEX_API_AUTH_TOKEN=<"%OCX_API_TOKEN_FILE%"\r
 goto scan_codex_args\r
 :scan_codex_args\r
 if "%~1"=="" goto ensure_ocx\r
@@ -240,10 +250,11 @@ export function buildWindowsPowerShellCodexShim(realCodexPath: string, bunPath:
     .map(arg => `${psString(arg)} `).join("");
   return `#!/usr/bin/env pwsh
 # ${SHIM_MARKER}
+# ${WINDOWS_SHIM_REVISION_MARKER}
 $hadApiAuthToken = Test-Path Env:\\OPENCODEX_API_AUTH_TOKEN
 $priorApiAuthToken = $env:OPENCODEX_API_AUTH_TOKEN
 try {
-if (-not $env:OPENCODEX_API_AUTH_TOKEN -and (Test-Path -LiteralPath ${psString(tokenFile)})) {
+if (-not $env:OCX_SHIM_BYPASS -and -not $env:OPENCODEX_API_AUTH_TOKEN -and (Test-Path -LiteralPath ${psString(tokenFile)})) {
   $env:OPENCODEX_API_AUTH_TOKEN = (Get-Content -Raw -LiteralPath ${psString(tokenFile)}).Trim()
 }
 $internalCommands = @(${internalCommands})
@@ -294,4 +305,4 @@ function gitBashPath(path: string): string {
   return path.replace(/\\/g, "/");
 }
 
-export { SHIM_MARKER, UNIX_SHIM_REVISION_MARKER, CODEX_SHIM_REENTRY_EXIT_CODE, CODEX_SHIM_REENTRY_DIAGNOSTIC, shQuote, windowsBatchSet, psString, gitBashPath };
+export { SHIM_MARKER, UNIX_SHIM_REVISION_MARKER, WINDOWS_SHIM_REVISION_MARKER, CODEX_SHIM_REENTRY_EXIT_CODE, CODEX_SHIM_REENTRY_DIAGNOSTIC, shQuote, windowsBatchSet, psString, gitBashPath };

package/src/codex/shim-windows-refresh.ts

@@ -0,0 +1,224 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, existsSync, fstatSync, linkSync, lstatSync, openSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+import { sameFingerprintAfterRename, sameStableShimPathProbe, shimPathFingerprint, stableShimPathProbe, type StableShimPathProbe } from "./shim-fingerprint";
+
+/**
+ * Identity of a directory entry: device, inode and whether the entry is itself a symbolic link.
+ *
+ * dev/ino alone is not an identity on Linux: ext4 and tmpfs hand a freed inode number straight to the
+ * next file or link created, so a stage unlinked and replaced by a link (or a new file) can carry the
+ * very numbers this refresh recorded. Every identity this module compares therefore belongs to a file
+ * it still holds open (an open inode cannot be freed, so its number cannot be reused), and the link
+ * flag is compared too, so a symlink never matches a regular file whatever the platform's link(2)
+ * does with a symlink source.
+ */
+interface EntryIdentity { dev: bigint; ino: bigint; link: boolean }
+
+/** Identity of the directory entry itself (a link is its own entry); null when absent. */
+function entryIdentity(path: string): EntryIdentity | null {
+  try {
+    const entry = lstatSync(path, { bigint: true });
+    return { dev: entry.dev, ino: entry.ino, link: entry.isSymbolicLink() };
+  } catch {
+    return null;
+  }
+}
+
+/** Identity of what a path resolves to; null when absent or dangling. */
+function targetIdentity(path: string): EntryIdentity | null {
+  try {
+    const target = statSync(path, { bigint: true });
+    return { dev: target.dev, ino: target.ino, link: false };
+  } catch {
+    return null;
+  }
+}
+
+const same = (left: EntryIdentity | null, right: EntryIdentity | null): boolean =>
+  !!left && !!right && left.dev === right.dev && left.ino === right.ino && left.link === right.link;
+
+/** The entry at `path` is exactly `identity` (same inode, same link-ness). */
+function entryIs(path: string, identity: EntryIdentity): boolean {
+  return same(entryIdentity(path), identity);
+}
+
+/** An open regular file and its identity; the descriptor pins the inode for as long as it is open. */
+interface HeldFile { fd: number; identity: EntryIdentity }
+
+function release(held: HeldFile | null): void {
+  if (held) { try { closeSync(held.fd); } catch { /* already closed */ } }
+}
+
+/** Create `path` exclusively (never through an existing entry or link), write it, and keep it open. */
+function createExclusive(path: string, content: string): HeldFile {
+  const flags = constants.O_RDWR | constants.O_CREAT | constants.O_EXCL
+    | (process.platform === "win32" ? 0 : constants.O_NOFOLLOW);
+  const fd = openSync(path, flags, 0o644);
+  try {
+    writeFileSync(fd, content, "utf8");
+    const stat = fstatSync(fd, { bigint: true });
+    return { fd, identity: { dev: stat.dev, ino: stat.ino, link: false } };
+  } catch (error) {
+    try { closeSync(fd); } catch { /* already closed */ }
+    throw error;
+  }
+}
+
+/** Open the regular file at `path` without following a link and confirm the entry is the opened file. */
+function holdExisting(path: string): HeldFile | null {
+  const entry = entryIdentity(path);
+  if (!entry || entry.link) return null;
+  const flags = process.platform === "win32"
+    ? constants.O_RDONLY
+    : constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+  let fd: number;
+  try { fd = openSync(path, flags); } catch { return null; }
+  try {
+    const stat = fstatSync(fd, { bigint: true });
+    const identity: EntryIdentity = { dev: stat.dev, ino: stat.ino, link: false };
+    if (stat.isFile() && same(identity, entry) && entryIs(path, identity)) return { fd, identity };
+  } catch { /* unreadable descriptor: treated like a mismatch */ }
+  // Every unsuccessful path releases the descriptor; the caller then hands the moved file back.
+  try { closeSync(fd); } catch { /* already closed */ }
+  return null;
+}
+
+/**
+ * Hard-link `source` onto the empty `destination` and keep the result only if the published entry
+ * is exactly `expected`. If `source` was swapped (for another file or a link) between the caller's
+ * check and the link, the entry this call created is withdrawn; an entry that matches neither the
+ * source nor its target belongs to an independent later publisher and stays.
+ */
+function linkExpected(source: string, destination: string, expected: EntryIdentity): "published" | "occupied" | "refused" {
+  try {
+    linkSync(source, destination);
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EEXIST" ? "occupied" : "refused";
+  }
+  const published = entryIdentity(destination);
+  if (same(published, expected)) return "published";
+  if (published && (same(published, entryIdentity(source)) || same(published, targetIdentity(source)))) {
+    try { unlinkSync(destination); } catch { /* nothing to withdraw */ }
+  }
+  return "refused";
+}
+
+/** Whether `directory` supports hard links, proven with a throwaway pair before anything is displaced. */
+function hardLinksWork(directory: string): boolean {
+  const probe = join(directory, `.ocx-link-probe-${randomUUID()}`);
+  const linked = `${probe}-linked`;
+  let held: HeldFile;
+  try { held = createExclusive(probe, ""); } catch { return false; }
+  try {
+    linkSync(probe, linked);
+    return entryIs(linked, held.identity);
+  } catch {
+    return false;
+  } finally {
+    for (const path of [linked, probe]) if (entryIs(path, held.identity)) { try { unlinkSync(path); } catch { /* best effort */ } }
+    release(held);
+  }
+}
+
+/**
+ * Replace an owned, obsolete Windows wrapper without ever truncating, replacing or writing through
+ * a file someone else published (an npm or version-manager install racing this refresh, or an entry
+ * planted beside the wrapper).
+ *
+ * 1. Move the observed wrapper aside, open it, and prove the moved file is the one that was probed;
+ *    a different file means a concurrent replacement, which is put back untouched.
+ * 2. Create the stage exclusively under an unpredictable name and keep it open.
+ * 3. Publish by hard link onto the empty path, keeping the result only if it is that stage file.
+ *
+ * Every restore, withdrawal and cleanup is bound to the identity of a file this refresh holds open:
+ * only the stage it created and only the moved copy of the observed wrapper are ever published or
+ * unlinked. Returns true only when the current wrapper was published; a filesystem that refuses hard
+ * links leaves the obsolete wrapper restored and the refresh deferred.
+ */
+export function refreshObsoleteWindowsShim(
+  wrapperPath: string,
+  observed: StableShimPathProbe,
+  render: () => string,
+  /** Test seam only: a fixed stage path, so a planted entry can be placed where the stage goes. */
+  stagedPathForTests?: string,
+): boolean {
+  const extension = extname(wrapperPath);
+  const aside = `${wrapperPath}.ocx-obsolete-${randomUUID()}${extension}`;
+  const staged = stagedPathForTests ?? `${wrapperPath}.ocx-refresh-${randomUUID()}${extension}`;
+  let moved: HeldFile | null = null;
+  let stage: HeldFile | null = null;
+  const discard = (path: string, held: HeldFile | null): void => {
+    if (held && entryIs(path, held.identity)) { try { unlinkSync(path); } catch { /* already gone */ } }
+  };
+  /**
+   * Put the moved wrapper back only onto an empty path, and only while the aside is still it. If the
+   * link fails (hard links became unavailable mid-refresh), an identity-checked rename keeps the
+   * launcher from staying missing.
+   */
+  const restoreAside = (): void => {
+    if (!moved || existsSync(wrapperPath) || !entryIs(aside, moved.identity)) return;
+    if (linkExpected(aside, wrapperPath, moved.identity) === "published") { discard(aside, moved); return; }
+    if (!existsSync(wrapperPath) && entryIs(aside, moved.identity)) { try { renameSync(aside, wrapperPath); } catch { /* the aside copy stays recoverable */ } }
+  };
+
+  // Never displace a working wrapper on a filesystem that cannot publish its replacement.
+  if (!hardLinksWork(dirname(wrapperPath))) return false;
+  try { renameSync(wrapperPath, aside); } catch { return false; }
+  try {
+    const movedFingerprint = shimPathFingerprint(aside);
+    moved = holdExisting(aside);
+    if (!moved || !movedFingerprint || !sameFingerprintAfterRename(observed.fingerprint, movedFingerprint)) {
+      // Not the observed wrapper: hand the path back to whatever was moved, untouched.
+      const foreign = entryIdentity(aside);
+      if (foreign && !existsSync(wrapperPath) && linkExpected(aside, wrapperPath, foreign) === "published" && entryIs(aside, foreign)) {
+        try { unlinkSync(aside); } catch { /* the restored link keeps the content */ }
+      }
+      return false;
+    }
+    try {
+      stage = createExclusive(staged, render());
+    } catch (error) {
+      restoreAside();
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === "EEXIST" || code === "ELOOP") return false;
+      throw error;
+    }
+    if (!entryIs(staged, stage.identity)) {
+      restoreAside();
+      return false;
+    }
+    const outcome = linkExpected(staged, wrapperPath, stage.identity);
+    discard(staged, stage);
+    if (outcome === "published") {
+      discard(aside, moved);
+      return true;
+    }
+    // Occupied: a concurrent publisher owns the path now; only our obsolete copy is discarded.
+    if (outcome === "occupied") discard(aside, moved);
+    else restoreAside();
+    return false;
+  } finally {
+    release(stage);
+    release(moved);
+  }
+}
+
+/**
+ * Automatic Windows revision recovery: refresh exactly the admitted obsolete wrappers, and only
+ * while every current sibling is still the file observed before the stability wait. It never
+ * adopts a replacement launcher or rewrites a backup; anything unexpected defers.
+ */
+export function refreshAdmittedWindowsShims(
+  obsolete: ReadonlyMap<string, StableShimPathProbe>,
+  current: ReadonlyMap<string, StableShimPathProbe>,
+  render: (wrapperPath: string) => string,
+): boolean {
+  for (const [path, first] of current) {
+    const second = stableShimPathProbe(path);
+    if (!second || !sameStableShimPathProbe(first, second)) return false;
+  }
+  let all = true;
+  for (const [path, observed] of obsolete) all = refreshObsoleteWindowsShim(path, observed, () => render(path)) && all;
+  return all;
+}

package/src/codex/shim.ts

@@ -26,6 +26,7 @@ import {
 } from "./shim-templates";
 import {
   hasUsableBackingPath,
+  isCurrentShimProbe,
   isCurrentUnixShimProbe,
   isHealthyShimProbe,
   isVersionManagerOwnedCodexPath,
@@ -55,6 +56,7 @@ import {
   type UnixShimProbeResult,
 } from "./shim-probe";
 import { tryAcquireShimRestoreLock } from "./shim-restore-lock";
+import { refreshAdmittedWindowsShims, refreshObsoleteWindowsShim } from "./shim-windows-refresh";
 import {
   isWindowsInteropDir,
   isExecutableCodexCandidate,
@@ -348,24 +350,22 @@ function rollbackFreshShimInstall(journal: readonly FreshShimInstallJournalEntry
  * updater's wrapper can carry them, and a replacement landing between the write
  * and the observation is otherwise indistinguishable from our own file.
  */
+/** The Windows wrapper for `wrapperPath`'s flavor (.ps1, .cmd/.bat, or extensionless Git-Bash sh). */
+function windowsShimContent(wrapperPath: string, realCodexPath: string, runtime?: DurableBunRuntime): string {
+  const { bun, bunRuntimeSource, cli } = cliEntry(runtime);
+  const lower = wrapperPath.toLowerCase();
+  // UTF-8 BOM: Windows PowerShell 5.1 decodes BOM-less .ps1 files in the ANSI
+  // codepage, which mangles non-ASCII paths embedded in the shim.
+  if (lower.endsWith(".ps1")) return `\uFEFF${buildWindowsPowerShellCodexShim(realCodexPath, bun, cli, bunRuntimeSource)}`;
+  if (lower.endsWith(".cmd") || lower.endsWith(".bat")) return buildWindowsCodexShim(realCodexPath, bun, cli, bunRuntimeSource);
+  // Extensionless Git-Bash sh launcher: sh shim with forward-slash paths.
+  return buildUnixCodexShim(gitBashPath(realCodexPath), gitBashPath(bun), gitBashPath(cli), bunRuntimeSource, gitBashPath(serviceApiTokenFilePath()));
+}
+
 function writeShim(wrapperPath: string, realCodexPath: string, runtime?: DurableBunRuntime): { dev: number; ino: number } | undefined {
   const { bun, bunRuntimeSource, cli } = cliEntry(runtime);
   if (process.platform === "win32") {
-    const lower = wrapperPath.toLowerCase();
-    if (lower.endsWith(".ps1")) {
-      // UTF-8 BOM: Windows PowerShell 5.1 decodes BOM-less .ps1 files in the ANSI
-      // codepage, which mangles non-ASCII paths embedded in the shim.
-      writeFileSync(wrapperPath, `\uFEFF${buildWindowsPowerShellCodexShim(realCodexPath, bun, cli, bunRuntimeSource)}`, "utf8");
-    } else if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
-      writeFileSync(wrapperPath, buildWindowsCodexShim(realCodexPath, bun, cli, bunRuntimeSource), "utf8");
-    } else {
-      // Extensionless Git-Bash sh launcher: sh shim with forward-slash paths.
-      writeFileSync(
-        wrapperPath,
-        buildUnixCodexShim(gitBashPath(realCodexPath), gitBashPath(bun), gitBashPath(cli), bunRuntimeSource, gitBashPath(serviceApiTokenFilePath())),
-        "utf8",
-      );
-    }
+    writeFileSync(wrapperPath, windowsShimContent(wrapperPath, realCodexPath, runtime), "utf8");
     return undefined;
   } else {
     // Stage the wrapper as its own inode and rename it into place, so ownership
@@ -509,6 +509,15 @@ function refreshShimFile(file: ShimFileState, runtime: DurableBunRuntime): boole
     writeShim(file.wrapperPath, file.realPath ?? file.backupPath, runtime);
     return true;
   }
+  // An owned Windows wrapper from an older template revision (e.g. one that loads the service
+  // token before honoring OCX_SHIM_BYPASS) is replaced over the same backing launcher through an
+  // ownership-checked stage-and-link transaction that never clobbers a concurrent replacement.
+  if (process.platform === "win32" && existsSync(file.wrapperPath) && isShim(file.wrapperPath) && hasUsableBackingPath(file)) {
+    const probe = stableShimPathProbe(file.wrapperPath);
+    if (probe && probe.prefix.includes(SHIM_MARKER) && !isCurrentShimProbe(probe, "win32")) {
+      return refreshObsoleteWindowsShim(file.wrapperPath, probe, () => windowsShimContent(file.wrapperPath, file.realPath ?? file.backupPath, runtime));
+    }
+  }
   return false;
 }
 
@@ -884,7 +893,8 @@ function installCodexShimInternal(options: InstallCodexShimInternalOptions): { i
   if (filesBefore.length > 0 && filesBefore.every(file => {
     if (file.preserveOnly) return existsSync(file.backupPath) && !existsSync(file.originalPath);
     const probe = stableShimPathProbe(file.wrapperPath);
-    return hasUsableBackingPath(file) && probe !== null && isHealthyShimProbe(probe, process.platform);
+    return hasUsableBackingPath(file) && probe !== null && isHealthyShimProbe(probe, process.platform)
+      && (process.platform !== "win32" || isCurrentShimProbe(probe, "win32"));
   })) {
     return { installed: false, message: "Codex autostart shim is already installed." };
   }
@@ -934,6 +944,12 @@ function installCodexShimInternal(options: InstallCodexShimInternalOptions): { i
     }
     let refreshed = false;
     for (const file of files) refreshed = refreshShimFile(file, runtime) || refreshed;
+    // A Windows refresh that refused to publish over a concurrent replacement is not a success.
+    if (process.platform === "win32" && files.some(file => {
+      if (file.preserveOnly) return false;
+      const probe = stableShimPathProbe(file.wrapperPath);
+      return !probe || !probe.prefix.includes(SHIM_MARKER) || !isCurrentShimProbe(probe, "win32");
+    })) return { installed: false, message: "Codex shim refresh deferred because a tracked launcher changed during the refresh." };
     const allInstalled = files.every(file => file.preserveOnly
       ? existsSync(file.backupPath) && !existsSync(file.originalPath)
       : existsSync(file.wrapperPath)
@@ -1106,7 +1122,7 @@ export function autoRestoreCodexShim(options: RuntimePreflightDeps & {
   const replacementProbes = new Map<string, StableShimPathProbe>();
   const obsoleteShimProbes = new Map<string, StableShimPathProbe>();
   const seen = new Set<string>();
-  let healthyCount = 0;
+  const currentShimProbes = new Map<string, StableShimPathProbe>();
   for (const file of files) {
     if (seen.has(file.wrapperPath)) return { status: "ineligible" };
     seen.add(file.wrapperPath);
@@ -1125,11 +1141,11 @@ export function autoRestoreCodexShim(options: RuntimePreflightDeps & {
       if (!isHealthyShimProbe(probe, state.platform)) {
         return { status: "ineligible", message: destroyedShimMessage(file) };
       }
-      if (state.platform !== "win32" && !isCurrentUnixShimProbe(probe)) {
+      if (!isCurrentShimProbe(probe, state.platform)) {
         obsoleteShimProbes.set(file.wrapperPath, probe);
         continue;
       }
-      healthyCount += 1;
+      currentShimProbes.set(file.wrapperPath, probe);
       continue;
     }
     // A surviving backup would otherwise let the replacement path below wrap the
@@ -1143,7 +1159,10 @@ export function autoRestoreCodexShim(options: RuntimePreflightDeps & {
 
   if (replacementProbes.size === 0 && obsoleteShimProbes.size === 0) return { status: "healthy" };
   if (!options.enabled()) return { status: "disabled" };
-  if (files.length > 1 && (healthyCount > 0 || (replacementProbes.size > 0 && obsoleteShimProbes.size > 0))) {
+  // Windows current + obsolete siblings (a partial revision upgrade) resume: only the obsolete
+  // wrappers are refreshed, so a transient publish failure cannot block recovery forever.
+  const revisionOnlyMix = state.platform === "win32" && replacementProbes.size === 0;
+  if (files.length > 1 && ((currentShimProbes.size > 0 && !revisionOnlyMix) || (replacementProbes.size > 0 && obsoleteShimProbes.size > 0))) {
     return {
       status: "deferred",
       message: "Codex shim auto-restore deferred because tracked launcher siblings are in a mixed shim/replacement state.",
@@ -1166,9 +1185,14 @@ export function autoRestoreCodexShim(options: RuntimePreflightDeps & {
     if (obsoleteShimProbes.size > 0) {
       for (const [path, firstProbe] of obsoleteShimProbes) {
         const secondProbe = stableShimPathProbe(path);
-        if (!secondProbe || isCurrentUnixShimProbe(secondProbe)
+        if (!secondProbe || isCurrentShimProbe(secondProbe, state.platform)
           || !sameStableShimPathProbe(firstProbe, secondProbe)) return { status: "deferred" };
       }
+      if (state.platform === "win32") {
+        const realFor = (path: string) => { const file = files.find(entry => entry.wrapperPath === path)!; return file.realPath ?? file.backupPath; };
+        return refreshAdmittedWindowsShims(obsoleteShimProbes, currentShimProbes, path => windowsShimContent(path, realFor(path), runtime))
+          ? { status: "restored", message: `Upgraded Codex autostart shim at ${[...obsoleteShimProbes.keys()].join(", ")}.` } : { status: "deferred" };
+      }
       const result = refreshObsoleteUnixShims(files);
       return result.installed
         ? { status: "restored", message: result.message }

package/src/codex/subagent-model-fallback.ts

@@ -38,6 +38,7 @@ import {
   isCanonicalOpenAiForwardProvider,
 } from "../providers/openai-tiers";
 import { routeModel, type RouteResult } from "../router";
+import { guardFallbackHop, type FallbackAdmission } from "../routing/fallback-policy";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
 import { codexAccountNamespaceForModel } from "./account-namespace-match";
 import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_MAIN_DRAIN_SENTINEL_MODELS } from "./catalog/native-models";
@@ -629,7 +630,8 @@ export function applySubagentModelFallback(
   modelEligibleAccountIdsForModel?: SubagentModelEligibleAccountIds,
   resolvedFallbackChain?: readonly string[] | null,
   restrictedRouteEligible?: SubagentFallbackRouteEligibility,
-): { from?: string; to?: string; skipped?: string[] } | null {
+  admission?: FallbackAdmission,
+): { from?: string; to?: string; skipped?: string[]; refusal?: Response } | null {
   if (!isThreadSpawnRequest(headers)) return null;
   const fallbackChain = resolvedFallbackChain === undefined
     ? resolveSubagentFallbackChain(parsed, config)
@@ -653,10 +655,31 @@ export function applySubagentModelFallback(
     ? { from: parsed.modelId, to: parsed.modelId, skipped: selection.skipped }
     : null;
   const from = parsed.modelId;
+  // OCX-11: the rewrite is a proactive hop away from an unavailable primary. Refused, the spawn
+  // keeps its model and the caller answers with the refusal instead of sending anything.
+  const hop = guardFallbackHop(config, {
+    site: "subagent",
+    route: from,
+    from: fallbackTargetOf(config, from),
+    to: fallbackTargetOf(config, selection.model),
+    trigger: "unavailable",
+    admission,
+    now,
+  });
+  if (!hop.ok) return { from, to: from, skipped: selection.skipped, refusal: hop.response };
+  // The rewrite is this site's admission: the spawn now carries the fallback model.
+  hop.commit();
   rewriteParsedModel(parsed, selection.model);
   return { from, to: selection.model, skipped: selection.skipped };
 }
 
+function fallbackTargetOf(config: OcxConfig, model: string): { provider: string; model: string } {
+  const route = tryRouteFallbackModel(config, model);
+  if (route) return { provider: route.providerName, model: route.modelId };
+  const slash = model.indexOf("/");
+  return slash > 0 ? { provider: model.slice(0, slash), model: model.slice(slash + 1) } : { provider: "", model };
+}
+
 /** Resolve the effective fallback chain once for one logical spawn request. */
 export function resolveSubagentFallbackChain(
   parsed: OcxParsedRequest,

package/src/combos/failover.ts

@@ -2,6 +2,7 @@ import { parseResetCooldownMs } from "../codex/routing";
 import { classifyError, isCyberPolicyCode } from "../lib/errors";
 import { isNonReplayableUpstreamCode } from "../lib/upstream-retry";
 import { isAnthropicBillingFailure } from "../providers/anthropic-billing-refusal";
+import { isKiroAccountProfileRefusal } from "../adapters/kiro-refusal";
 import type { OcxComboTarget } from "../types";
 import { targetKey } from "./types";
 import {
@@ -772,7 +773,7 @@ export function codexAccountModelRefusal(
 export function comboFailureDecision(
   status: number,
   message: string,
-  options?: { code?: string | null; codexModelRefusal?: CodexAccountModelRefusal },
+  options?: { code?: string | null; codexModelRefusal?: CodexAccountModelRefusal; failedAdapter?: string },
 ): ComboFailureDecision {
   if (status === 499) return "stop";
   if (message.toLowerCase().includes("origin_rejected")) return "stop";
@@ -856,6 +857,12 @@ export function comboFailureDecision(
   // could have served the request (#4903).
   if (isResponseFormatCapabilityRefusal(status, message, options?.code)) return "hop";
   if (isAnthropicBillingFailure(status, message, options?.code)) return "hop";
+  // Kiro's body validator rejects the request for the identity it was routed under. The account
+  // layer rotates logins first; this is the no-alternate case, so the next combo target is the
+  // only remaining chance to serve the turn. Only a caller that knows the failed target is a Kiro
+  // adapter grants it (the words alone prove nothing for another provider); it must precede the
+  // generic invalid_request_error stop.
+  if (options?.failedAdapter === "kiro" && isKiroAccountProfileRefusal(status, message)) return "hop";
   if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
     return "stop";
   }

package/src/combos/index.ts

@@ -23,6 +23,7 @@ export {
   advanceComboAfterFailure,
   clearComboSelectionState,
   comboExclusionReasons,
+  comboTargetSkipTrigger,
   NoAvailableComboTargetsError,
   noteComboFailure,
   noteComboSuccess,

package/src/combos/resolve.ts

@@ -74,6 +74,18 @@ function targetProviderIsUsable(config: OcxConfig, target: OcxComboTarget, now:
   return providerExclusionReason(config, target, now) === undefined;
 }
 
+/**
+ * OCX-11: the coarse fallback trigger for a target the picker passed over for a reason other
+ * than a cooldown (provider missing or disabled, cached quota spent, ineligible for the request).
+ */
+export function comboTargetSkipTrigger(
+  config: OcxConfig,
+  target: OcxComboTarget,
+  now = Date.now(),
+): "quota_exhausted" | "unavailable" {
+  return providerExclusionReason(config, target, now) === "quota exhausted" ? "quota_exhausted" : "unavailable";
+}
+
 /**
  * Why each target of a combo cannot be picked right now, for a zero-attempt refusal. Only the
  * configured provider/model and a coarse label are named, never account or request data.

package/src/config/diagnostics.ts

@@ -11,6 +11,7 @@ import { nativeReasoningRetentionConfigError } from "./schema/native-reasoning-r
 import { desktopCompatibilityConfigError } from "./schema/desktop-compatibility";
 import { blockedModelRedirectsError } from "./schema/blocked-model-redirects";
 import { mainAccountHardLockFallbackError } from "./schema/main-account-hard-lock-fallback";
+import { fallbackPolicyError } from "./schema/fallback-policy";
 import type { OcxConfig } from "../types";
 import { anthropicAccountPoolConfigError, anthropicOAuthInstanceConfigError, anthropicSidecarConfigError } from "./schema/anthropic-account-pool";
 import { configReasoningPinsConfigError } from "./provider-validation";
@@ -145,6 +146,7 @@ function validFileConfigDiagnostics(config: OcxConfig, rawParsed: unknown): Conf
   if (blockedModelRedirectsError(rawParsed)) warnings.push("blockedModelRedirects ignored: expected a map of nonempty model keys to nonempty string targets");
   if (nativeReasoningRetentionConfigError(rawParsed)) warnings.push("nativeReasoningRetention ignored: expected only optional boolean modelSwitch and accountSwitch fields; both remain off");
   if (mainAccountHardLockFallbackError(rawParsed)) warnings.push("codexMainAccountHardLockFallback ignored: expected a nonblank model selector and an optional declared reasoningEffort");
+  if (fallbackPolicyError(rawParsed)) warnings.push("fallback partly ignored: expected boolean model/provider switches, providers/routes/devices maps of them, and devices.<id>.localFallback; ignored leaves keep today's fallback behavior");
   const quotaAutoRefreshWarning = degradedCodexQuotaAutoRefreshWarning(rawParsed, normalized);
   if (quotaAutoRefreshWarning) warnings.push(quotaAutoRefreshWarning);
   if (rawEffort !== undefined && !isClaudeSubagentEffort(rawEffort)) {
@@ -729,6 +731,9 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
   const anthropicError = anthropicOAuthInstanceConfigError(value) ?? anthropicAccountPoolConfigError(value) ?? anthropicSidecarConfigError(value);
   if (anthropicError) return { ok: false, error: anthropicError };
   const boundaryError = blockedModelRedirectsError(value)
+    // OCX-11: the read schema degrades a malformed fallback leaf to absent, which would silently
+    // drop a refusal on the next whole-config save; the write boundary rejects it instead.
+    ?? fallbackPolicyError(value)
     ?? nativeReasoningRetentionConfigError(value)
     ?? mainAccountHardLockFallbackError(value)
     ?? compactionRecoveryConfigError(value) ?? desktopCompatibilityConfigError(value) ?? configReasoningPinsConfigError(value)

package/src/config/load-degrade.ts

@@ -7,6 +7,7 @@ import { nativeReasoningRetentionConfigError } from "./schema/native-reasoning-r
 import { desktopCompatibilityConfigError } from "./schema/desktop-compatibility";
 import { blockedModelRedirectsError } from "./schema/blocked-model-redirects";
 import { mainAccountHardLockFallbackError } from "./schema/main-account-hard-lock-fallback";
+import { fallbackPolicyError } from "./schema/fallback-policy";
 import { anthropicSidecarConfigError } from "./schema/anthropic-account-pool";
 import {
   modelPinnedEffortsConfigError,
@@ -142,6 +143,7 @@ export function warnDegradedTopLevelOptIns(rawParsed: unknown, validated: OcxCon
   if (desktopCompatibilityConfigError(rawParsed)) console.warn("Invalid desktopCompatibility startup preference ignored; no desktop compatibility service will start automatically.");
   if (blockedModelRedirectsError(rawParsed)) console.warn("⚠️  invalid blockedModelRedirects ignored; provider routing remains available");
   if (mainAccountHardLockFallbackError(rawParsed)) console.warn("⚠️  invalid codexMainAccountHardLockFallback ignored; the main-account hard lock still refuses while blocked");
+  if (fallbackPolicyError(rawParsed)) console.warn("⚠️  invalid fallback leaves ignored; those scopes keep today's fallback behavior");
   const chatgptDesktop = chatgptDesktopConfigIssue(rawParsed);
   if (chatgptDesktop) console.warn(`⚠️  config.json ${chatgptDesktop} — the whole chatgptDesktop block is ignored, so the ChatGPT desktop integration reads as off`);
   warnDegradedStreamMode(rawParsed, validated);

package/src/config/provider-validation.ts

@@ -463,7 +463,7 @@ export function modelCapabilitiesConfigError(value: unknown, allowTombstones = f
     if (allowTombstones && row === null) continue;
     if (!capabilityRecord(row)) return "modelCapabilities rows must be plain objects";
     for (const [axis, declaration] of Object.entries(row)) {
-      if (!["inputModalities", "contextTier", "video"].includes(axis)) return "modelCapabilities contains an unknown axis";
+      if (!["inputModalities", "contextTier", "video", "deepseekImageFiles"].includes(axis)) return "modelCapabilities contains an unknown axis";
       if (allowTombstones && declaration === null) continue;
       if (axis === "inputModalities") {
         if (!Array.isArray(declaration) || declaration.length === 0
@@ -472,6 +472,8 @@ export function modelCapabilitiesConfigError(value: unknown, allowTombstones = f
         }
       } else if (axis === "contextTier") {
         if (declaration !== "default" && declaration !== "long_context") return "modelCapabilities contextTier must be default or long_context";
+      } else if (axis === "deepseekImageFiles") {
+        if (typeof declaration !== "boolean") return "modelCapabilities deepseekImageFiles must be a boolean";
       } else {
         if (!capabilityRecord(declaration) || Object.keys(declaration).some(key => key !== "processing")) {
           return "modelCapabilities video must be a plain object containing only processing";
@@ -501,6 +503,9 @@ export function mergeModelCapabilities(
       } else if (axis === "contextTier") {
         if (value === null) delete row.contextTier;
         else row.contextTier = value as ModelCapabilities["contextTier"];
+      } else if (axis === "deepseekImageFiles") {
+        if (value === null) delete row.deepseekImageFiles;
+        else row.deepseekImageFiles = value as boolean;
       } else if (axis === "video") {
         if (value === null) delete row.video;
         else {
@@ -528,7 +533,7 @@ export function sanitizeModelCapabilitiesForLoad(value: unknown): Record<string,
   for (const [id, raw] of Object.entries(value).slice(0, MODEL_DISCOVERY_MAX_MODELS)) {
     if (!capabilityRecord(raw) || !isValidModelDiscoveryModelId(id) || ["__proto__", "prototype", "constructor"].includes(id)) continue;
     const row: Record<string, unknown> = {};
-    for (const axis of ["inputModalities", "contextTier", "video"] as const) {
+    for (const axis of ["inputModalities", "contextTier", "video", "deepseekImageFiles"] as const) {
       if (!Object.hasOwn(raw, axis)) continue;
       const declaration = raw[axis];
       if (modelCapabilitiesConfigError({ [id]: { [axis]: declaration } }) === null) row[axis] = declaration;

package/src/config/schema/config-schema.ts

@@ -8,6 +8,7 @@ import { nativeReasoningRetentionSchema } from "./native-reasoning-retention";
 import { desktopCompatibilitySchema } from "./desktop-compatibility";
 import { blockedModelRedirectsSchema } from "./blocked-model-redirects";
 import { mainAccountHardLockFallbackSchema } from "./main-account-hard-lock-fallback";
+import { fallbackPolicySchema } from "./fallback-policy";
 import {
   agentTaskRecoverySchema,
   catalogAutoRefreshSchema,
@@ -241,6 +242,8 @@ export const configSchema = z.object({
   // A malformed fallback section disables only the reroute, never the lock's refusal
   // behavior; the management write boundary still rejects the bad value.
   codexMainAccountHardLockFallback: mainAccountHardLockFallbackSchema.optional().catch(undefined),
+  // OCX-11: a malformed section reads as absent, which keeps today's fallback behavior.
+  fallback: fallbackPolicySchema.optional().catch(undefined),
   // #2999: a malformed hand edit falls back to auto detection rather than rejecting the config.
   nativeMainRefresh: z.enum(["codex", "opencodex"]).optional().catch(undefined),
   // Future versions remain opaque through passthrough-compatible whole-config saves.