Skip to content

Commit 40abd23

Browse files
committed
fix(codex): report a destroyed shim instead of bailing silently
A version manager (mise/asdf/volta) rewrites its install tree in place on upgrade, destroying both the opencodex shim and the sibling .opencodex-real backup that auto-restore needs. Auto-restore returned a bare ineligible with no message, and the CLI warns only when a message exists, so ocx start, ocx ensure, and ocx service repair all reported success while routing quietly stayed native. That is the cause behind the misleading green status in #2411. Auto-restore now explains itself. The message names the wrapper state, the missing backup, and both paths, and for a version-manager tree it says why no repair is coming and what to do instead. Restoring by adopting the newly installed binary as a replacement original would be wrong twice: it records a provenance that never happened, and the next upgrade overwrites it again, so the repair would silently un-repair on the version manager's schedule. allowFreshInstall stays false. The replacement path is also refused on a version-manager tree even when a stale backup survives, since that is the same adoption arriving through the back door. Per the plan audit, every reachable silent bail now carries a message, not only the one in the report: the preserveOnly sibling case and the unhealthy-probe case were equally invisible. Healthy shims are untouched, including version-manager-owned ones that are currently intact. Detection gates repair, not operation. Docs record that a version-manager install tree is not a supported shim target and point those users at openai_base_url routing plus the service. Closes #2412
1 parent 240ac38 commit 40abd23

3 files changed

Lines changed: 102 additions & 4 deletions

File tree

‎docs-site/src/content/docs/reference/cli/lifecycle.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -360,6 +360,19 @@ changing is left untouched and retried later. Repair failures warn without faili
360360
command; manual fallback: `ocx codex-shim install`. Set `codexShimAutoRestore` to `false`, or set
361361
`OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0` for a process-level opt-out.
362362

363+
That restore needs the original launcher OpenCodex saved next to the shim. A version manager —
364+
mise, asdf, volta — rewrites its whole install tree on upgrade, which destroys the shim *and* that
365+
backup, so there is nothing left to restore from. **A version-manager install tree is not a
366+
supported shim target.** OpenCodex reports the condition and stops rather than wrapping the newly
367+
installed binary as a replacement original: doing so would record a history that never happened, and
368+
the next upgrade would overwrite it again, so the repair would silently undo itself on the version
369+
manager's schedule.
370+
371+
If your `codex` is owned by a version manager, route through Codex configuration instead of the
372+
launcher: `ocx start` writes `openai_base_url`, and `ocx service install` provides autostart. Run
373+
`ocx status` to confirm — it reports the active routing, and warns when a running proxy is not the
374+
one Codex is pointed at.
375+
363376
| Subcommand | Action |
364377
| --- | --- |
365378
| `install` | Install the shim (or repair if stale). |

‎src/codex/shim.ts‎

Lines changed: 56 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -603,6 +603,47 @@ function backupPathFor(path: string): string {
603603
return ext ? `${path.slice(0, -ext.length)}.opencodex-real${ext}` : `${path}.opencodex-real`;
604604
}
605605

606+
/**
607+
* True when a Codex binary lives inside a version manager's install tree.
608+
*
609+
* These trees are rewritten in place on upgrade, which destroys both the shim
610+
* and the sibling .opencodex-real backup it restores from (#2412). The tempting
611+
* repair — adopt the newly installed binary as a fresh original — is wrong
612+
* twice: it records a provenance that never happened, and the next upgrade wipes
613+
* it again, so the repair silently un-repairs on the version manager's schedule.
614+
*
615+
* Scope is the three managers named in the report. nvm/fnm/npm-prefix are
616+
* deliberately excluded: a false positive here refuses a restore that would
617+
* otherwise be correct.
618+
*/
619+
export function isVersionManagerOwnedCodexPath(path: string): boolean {
620+
const normalized = path.replace(/\\/g, "/").toLowerCase();
621+
return normalized.includes("/mise/installs/")
622+
|| normalized.includes("/mise/shims/")
623+
|| normalized.includes("/.asdf/installs/")
624+
|| normalized.includes("/.asdf/shims/")
625+
|| normalized.includes("/.volta/");
626+
}
627+
628+
/**
629+
* Why auto-restore refused, in the operator's own terms. Auto-restore used to
630+
* return a bare `{ status: "ineligible" }`, and the CLI warns only when a
631+
* message is present, so `ocx start`, `ocx ensure`, and `ocx service repair` all
632+
* reported success while routing quietly stayed native (#2412, the cause behind
633+
* the misleading green status in #2411).
634+
*/
635+
function destroyedShimMessage(file: ShimFileState): string {
636+
const wrapper = existsSync(file.wrapperPath)
637+
? isShim(file.wrapperPath) ? "present but unusable" : "present but not an opencodex shim"
638+
: "missing";
639+
const backup = existsSync(file.backupPath) ? "present" : "missing";
640+
const base = `Codex autostart shim not restored: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;
641+
if (!isVersionManagerOwnedCodexPath(file.wrapperPath)) {
642+
return `${base} Re-run 'ocx codex-shim install' once the Codex binary is stable.`;
643+
}
644+
return `${base} This Codex binary is owned by a version manager (mise/asdf/volta), so opencodex will not wrap it as a new original — the next upgrade would overwrite the shim and its backup again. Route through Codex instead with 'ocx start', and use 'ocx service install' for autostart.`;
645+
}
646+
606647
function shQuote(value: string): string {
607648
return `'${value.replace(/'/g, "'\\''")}'`;
608649
}
@@ -2039,21 +2080,33 @@ export function autoRestoreCodexShim(options: {
20392080
if (seen.has(file.wrapperPath)) return { status: "ineligible" };
20402081
seen.add(file.wrapperPath);
20412082
if (file.preserveOnly) {
2042-
if (!existsSync(file.backupPath) || existsSync(file.originalPath)) return { status: "ineligible" };
2083+
if (!existsSync(file.backupPath) || existsSync(file.originalPath)) {
2084+
return { status: "ineligible", message: destroyedShimMessage(file) };
2085+
}
20432086
continue;
20442087
}
2045-
if (!existsSync(file.wrapperPath) || !hasUsableBackingPath(file)) return { status: "ineligible" };
2088+
if (!existsSync(file.wrapperPath) || !hasUsableBackingPath(file)) {
2089+
return { status: "ineligible", message: destroyedShimMessage(file) };
2090+
}
20462091
const probe = stableShimPathProbe(file.wrapperPath);
20472092
if (!probe) return { status: "deferred" };
20482093
if (probe.prefix.includes(SHIM_MARKER)) {
2049-
if (!isHealthyShimProbe(probe, state.platform)) return { status: "ineligible" };
2094+
if (!isHealthyShimProbe(probe, state.platform)) {
2095+
return { status: "ineligible", message: destroyedShimMessage(file) };
2096+
}
20502097
if (state.platform !== "win32" && !isCurrentUnixShimProbe(probe)) {
20512098
obsoleteShimProbes.set(file.wrapperPath, probe);
20522099
continue;
20532100
}
20542101
healthyCount += 1;
20552102
continue;
20562103
}
2104+
// A surviving backup would otherwise let the replacement path below wrap the
2105+
// version manager's NEW binary as a fresh original — the same adoption the
2106+
// missing-backup case refuses, arriving through the back door.
2107+
if (isVersionManagerOwnedCodexPath(file.wrapperPath)) {
2108+
return { status: "ineligible", message: destroyedShimMessage(file) };
2109+
}
20572110
replacementProbes.set(file.wrapperPath, probe);
20582111
}
20592112

‎tests/codex-shim.test.ts‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { spawnSync } from "node:child_process";
33
import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
44
import { delimiter, dirname, join } from "node:path";
55
import { tmpdir } from "node:os";
6-
import { autoRestoreCodexShim, buildUnixCodexShim, buildWindowsCodexShim, buildWindowsPowerShellCodexShim, diagnoseCodexShim, findCodexOnPath, installCodexShim, isWindowsInteropDir, lastCodexDiscoveryError, setCodexShimFreshWriteHookForTests, setCodexShimGuardedWriteHookForTests, setCodexShimProbeHookForTests, setCodexShimProbeObservationMsForTests, setCodexShimProbeShellForTests, setCodexShimRollbackRestoreHookForTests, uninstallCodexShim } from "../src/codex/shim";
6+
import { autoRestoreCodexShim, buildUnixCodexShim, buildWindowsCodexShim, buildWindowsPowerShellCodexShim, diagnoseCodexShim, findCodexOnPath, installCodexShim, isVersionManagerOwnedCodexPath, isWindowsInteropDir, lastCodexDiscoveryError, setCodexShimFreshWriteHookForTests, setCodexShimGuardedWriteHookForTests, setCodexShimProbeHookForTests, setCodexShimProbeObservationMsForTests, setCodexShimProbeShellForTests, setCodexShimRollbackRestoreHookForTests, uninstallCodexShim } from "../src/codex/shim";
77

88
const SHIM_MARKER = "opencodex codex autostart shim";
99
const UNIX_SHIM_REVISION_MARKER = "opencodex unix codex shim revision 2";
@@ -1999,3 +1999,35 @@ describe("WSL PATH interop guard", () => {
19991999
expect(found).toBe(`${dir}/codex`);
20002000
});
20012001
});
2002+
2003+
// #2412: a version-manager upgrade (mise/asdf/volta) rewrites its install tree
2004+
// in place, destroying both the shim and its sibling .opencodex-real backup.
2005+
// The bail was silent, and the CLI warns only when a message exists, so start /
2006+
// ensure / service repair all reported success while routing stayed native.
2007+
describe("version-manager shim destruction (#2412)", () => {
2008+
test("classifies version-manager install trees without catching ordinary paths", () => {
2009+
expect(isVersionManagerOwnedCodexPath("/home/u/.local/share/mise/installs/codex/latest/bin/codex")).toBe(true);
2010+
expect(isVersionManagerOwnedCodexPath("/home/u/.local/share/mise/shims/codex")).toBe(true);
2011+
expect(isVersionManagerOwnedCodexPath("/home/u/.asdf/installs/codex/1.0/bin/codex")).toBe(true);
2012+
expect(isVersionManagerOwnedCodexPath("/home/u/.asdf/shims/codex")).toBe(true);
2013+
expect(isVersionManagerOwnedCodexPath("/home/u/.volta/bin/codex")).toBe(true);
2014+
expect(isVersionManagerOwnedCodexPath("C:\\Users\\u\\.volta\\bin\\codex.cmd")).toBe(true);
2015+
expect(isVersionManagerOwnedCodexPath("/usr/local/bin/codex")).toBe(false);
2016+
expect(isVersionManagerOwnedCodexPath("/home/u/.npm-global/bin/codex")).toBe(false);
2017+
expect(isVersionManagerOwnedCodexPath("/opt/homebrew/bin/codex")).toBe(false);
2018+
});
2019+
2020+
test("a destroyed shim reports the paths instead of bailing silently", () => {
2021+
withInstalledShim(({ wrappers, backups }) => {
2022+
writeFileSync(wrappers[0], "#!/bin/sh\necho version-manager codex\n", "utf8");
2023+
if (process.platform !== "win32") chmodSync(wrappers[0], 0o755);
2024+
rmSync(backups[0]);
2025+
const result = autoRestoreCodexShim({ enabled: () => true, stabilitySleep: skipStabilityWait });
2026+
expect(result.status).toBe("ineligible");
2027+
// The silent bail is the whole defect: cli/codex-shim-autorestore.ts warns
2028+
// only when a message exists.
2029+
expect(result.message).toBeTruthy();
2030+
expect(result.message).toContain("backup");
2031+
});
2032+
});
2033+
});

0 commit comments

Comments
 (0)