Skip to content

Commit 81ada7c

Browse files
committed
fix(codex): restore an unprobeable launcher on shim rollback (#1625)
A fresh install moves the user's existing launcher to codex.opencodex-real before writing the wrapper, and records a fingerprint so rollback can prove the backup is still the file it set aside. That fingerprint came from stableShimPathProbe, which reads content to judge whether a launcher looks like a healthy shim and deliberately returns null at zero bytes. An empty launcher is a legitimate thing to own, so the move was recorded with no fingerprint at all, and rollback -- which requires a match before it will restore -- refused. The install failed and left the user with no codex on PATH, the original stranded at codex.opencodex-real. Identity is metadata, not content. Add shimPathFingerprint, which reads dev/ino/mode/size/times (following a symlink to fingerprint its target too) and re-reads them to reject a path that moved under us. Record it right after the move and validate against it during rollback; the content probe still runs where it can, now purely as a consistency check. Two details the fix has to respect: Only Unix reaches the rollback path -- Windows rethrows freshApplyError without rolling back -- so only Unix treats a missing fingerprint as fatal. Throwing on Windows would abort after the original had already moved, stranding it with nothing to restore it. The restore itself no longer uses renameSync. sourceOccupied is sampled before the fingerprint check, so a concurrent installer can publish its own launcher at the original path in between, and rename would silently delete it. Regular files are republished with link()+unlink() and symlinks with symlink()+unlink(); both fail EEXIST on an occupied destination, which is the no-replace guarantee, and neither needs a native helper. Checking existence and then renaming would only narrow the race, not close it. Covered by two regression tests, each demonstrated red against the behavior it pins: the zero-byte launcher is restored rather than stranded, and a launcher published inside the restore window survives with the original still recoverable from the backup. The second needs a seam inside that window, because publishing any earlier makes sourceOccupied true and skips the restore branch. Ported by hand from #1625's f36aedf, taking only the fingerprint and rollback hunks. That commit also introduces a bun:ffi native no-replace helper with C sources and a Windows multi-launcher transaction rewrite; those are a separate proposal needing their own cross-platform validation. Closes #1625
1 parent d30ab74 commit 81ada7c

2 files changed

Lines changed: 196 additions & 6 deletions

File tree

‎src/codex/shim.ts‎

Lines changed: 100 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,19 @@ import {
88
existsSync,
99
fstatSync,
1010
lstatSync,
11+
linkSync,
1112
mkdirSync,
1213
mkdtempSync,
1314
openSync,
1415
readFileSync,
1516
readdirSync,
17+
readlinkSync,
1618
readSync,
1719
renameSync,
1820
rmSync,
1921
rmdirSync,
2022
statSync,
23+
symlinkSync,
2124
type Stats,
2225
unlinkSync,
2326
writeFileSync,
@@ -407,6 +410,63 @@ function sameStableShimPathProbe(left: StableShimPathProbe, right: StableShimPat
407410
return left.prefix === right.prefix && sameFingerprint(left.fingerprint, right.fingerprint);
408411
}
409412

413+
/**
414+
* Identity of whatever sits at `path`, read from metadata alone.
415+
*
416+
* `stableShimPathProbe` answers a different question: it reads content to decide
417+
* whether a launcher looks like a healthy shim, and it deliberately returns null
418+
* for a zero-byte file. That makes it the wrong instrument for rollback
419+
* bookkeeping. A user can legitimately own an empty `codex` launcher, and a fresh
420+
* install moves it aside before writing our wrapper; if the move is recorded
421+
* without a fingerprint, rollback cannot prove the backup is still the file it
422+
* set aside and refuses to restore it — the launcher stays lost (#1625).
423+
*
424+
* Content is irrelevant to that proof, so this reads dev/ino/mode/size/times and
425+
* re-reads them to reject a path that changed under us, following a symlink to
426+
* fingerprint its target as well.
427+
*/
428+
function shimPathFingerprint(path: string): ShimPathFingerprint | null {
429+
const before = statFingerprint(path, false);
430+
if (!before) return null;
431+
if (before.kind !== "symlink") {
432+
const after = statFingerprint(path, false);
433+
return after && sameFingerprint(before, after) ? before : null;
434+
}
435+
const targetBefore = statFingerprint(path, true);
436+
if (!targetBefore) return null;
437+
const targetAfter = statFingerprint(path, true);
438+
const after = statFingerprint(path, false);
439+
if (!targetAfter || !after
440+
|| !sameFingerprint(targetBefore, targetAfter)
441+
|| !sameFingerprint(before, after)) return null;
442+
return { ...before, target: targetBefore };
443+
}
444+
445+
/**
446+
* Move `from` onto `to` without ever replacing an existing entry.
447+
*
448+
* `renameSync` silently clobbers the destination on POSIX, which is wrong for a
449+
* rollback restore: `sourceOccupied` is sampled before the fingerprint check, so
450+
* a concurrent installer can publish its own launcher at the original path in
451+
* between, and the restore would delete it. `link` fails EEXIST instead, which
452+
* is the no-replace primitive we need and needs no native helper.
453+
*
454+
* `link` follows a symlink to its target rather than preserving the link, so a
455+
* symlink launcher is republished with `symlink`, which is also no-replace: it
456+
* fails EEXIST on an occupied destination. Checking existence and then renaming
457+
* would reintroduce exactly the race this function exists to close.
458+
*/
459+
function restoreWithoutReplacing(from: string, to: string): void {
460+
const source = lstatSync(from);
461+
if (source.isSymbolicLink()) {
462+
symlinkSync(readlinkSync(from), to);
463+
unlinkSync(from);
464+
return;
465+
}
466+
linkSync(from, to);
467+
unlinkSync(from);
468+
}
469+
410470
function isHealthyShimProbe(probe: StableShimPathProbe, platform: NodeJS.Platform): boolean {
411471
if (probe.prefix.length < 180 || !probe.prefix.includes(SHIM_MARKER) || !probe.prefix.includes("ensure")) return false;
412472
const mode = probe.fingerprint.target?.mode ?? probe.fingerprint.mode;
@@ -644,6 +704,7 @@ let codexShimProbeHookForTests: (() => void) | null = null;
644704
let codexShimProbeShellForTests: string | null = null;
645705
let codexShimGuardedWriteHookForTests: (() => void) | null = null;
646706
let codexShimFreshWriteHookForTests: (() => void) | null = null;
707+
let codexShimRollbackRestoreHookForTests: ((target: ShimFileState) => void) | null = null;
647708
let codexShimProbeObservationMs = CODEX_SHIM_INSTALL_PROBE_TIMEOUT_MS;
648709

649710
/** Narrow deterministic seam for transaction rollback tests. */
@@ -671,6 +732,20 @@ export function setCodexShimFreshWriteHookForTests(hook: (() => void) | null): v
671732
codexShimFreshWriteHookForTests = hook;
672733
}
673734

735+
/**
736+
* @internal Test-only seam for the rollback restore race.
737+
*
738+
* The window this closes opens after `sourceOccupied` is sampled and closes when
739+
* the backup is republished, so no earlier hook can reach it: publishing from
740+
* the fresh-write hook makes `sourceOccupied` true and skips the restore
741+
* entirely.
742+
*/
743+
export function setCodexShimRollbackRestoreHookForTests(
744+
hook: ((target: ShimFileState) => void) | null,
745+
): void {
746+
codexShimRollbackRestoreHookForTests = hook;
747+
}
748+
674749
function readProbeMetadata(path: string, maxBytes: number): string | null {
675750
try {
676751
if (!existsSync(path)) return "";
@@ -830,9 +905,9 @@ function rollbackFreshShimInstall(journal: readonly FreshShimInstallJournalEntry
830905
}
831906
try {
832907
if (entry.originalMovedToBackup && existsSync(target.backupPath)) {
833-
const movedOriginal = stableShimPathProbe(target.backupPath);
908+
const movedOriginal = shimPathFingerprint(target.backupPath);
834909
if (!movedOriginal || !entry.movedOriginalFingerprint
835-
|| !sameFingerprint(movedOriginal.fingerprint, entry.movedOriginalFingerprint)) {
910+
|| !sameFingerprint(movedOriginal, entry.movedOriginalFingerprint)) {
836911
throw new Error("Codex shim fresh-install backup changed during rollback");
837912
}
838913
if (sourceOccupied) {
@@ -842,7 +917,12 @@ function rollbackFreshShimInstall(journal: readonly FreshShimInstallJournalEntry
842917
// lose the command entirely. Keep it in that case — a stray
843918
// `codex.opencodex-real` is recoverable, a deleted launcher is not.
844919
if (ownsWrapperNow) unlinkSync(target.backupPath);
845-
} else renameSync(target.backupPath, target.originalPath);
920+
} else {
921+
// No-replace: sourceOccupied was sampled earlier, so a concurrent
922+
// installer may have published a launcher at the original path since.
923+
codexShimRollbackRestoreHookForTests?.(target);
924+
restoreWithoutReplacing(target.backupPath, target.originalPath);
925+
}
846926
}
847927
} catch (error) {
848928
errors.push(error instanceof Error ? error : new Error(String(error)));
@@ -1832,10 +1912,25 @@ function installCodexShimInternal(options: InstallCodexShimInternalOptions): { i
18321912
if (existsSync(target.originalPath)) {
18331913
renameSync(target.originalPath, target.backupPath);
18341914
entry.originalMovedToBackup = true;
1915+
// Metadata-only, and before the content probe: an empty or otherwise
1916+
// unprobeable launcher must still be restorable during rollback.
1917+
//
1918+
// Only Unix reaches the rollback path (Windows rethrows freshApplyError
1919+
// without rolling back), so only Unix may treat a missing fingerprint as
1920+
// fatal. Throwing here on Windows would abort AFTER the original moved,
1921+
// stranding the launcher at its backup path with nothing to restore it.
1922+
const movedOriginalFingerprint = shimPathFingerprint(target.backupPath);
1923+
if (movedOriginalFingerprint) entry.movedOriginalFingerprint = movedOriginalFingerprint;
18351924
if (process.platform !== "win32") {
1925+
if (!movedOriginalFingerprint) {
1926+
throw new Error("Codex shim fresh install could not fingerprint the staged launcher");
1927+
}
18361928
const movedOriginal = stableShimPathProbe(target.backupPath);
1837-
if (!movedOriginal) throw new Error("Codex shim fresh install could not fingerprint the staged launcher");
1838-
entry.movedOriginalFingerprint = movedOriginal.fingerprint;
1929+
// A content probe still runs where it can, purely as a consistency
1930+
// check: disagreement means the file moved under us mid-install.
1931+
if (movedOriginal && !sameFingerprint(movedOriginal.fingerprint, movedOriginalFingerprint)) {
1932+
throw new Error("Codex shim fresh install staged launcher changed while being fingerprinted");
1933+
}
18391934
}
18401935
}
18411936
if (!target.preserveOnly) {

‎tests/codex-shim.test.ts‎

Lines changed: 96 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, uninstallCodexShim } from "../src/codex/shim";
6+
import { autoRestoreCodexShim, buildUnixCodexShim, buildWindowsCodexShim, buildWindowsPowerShellCodexShim, diagnoseCodexShim, findCodexOnPath, installCodexShim, 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";
@@ -826,6 +826,101 @@ wait "$child"
826826
}
827827
});
828828

829+
test("Unix fresh install rolls an unprobeable original back into place", () => {
830+
if (process.platform === "win32") return;
831+
832+
// #1625. An empty launcher is a legitimate thing for a user to own, and
833+
// stableShimPathProbe deliberately returns null at zero bytes because it
834+
// answers "does this look like a healthy shim". Recording the backup with
835+
// that probe therefore left movedOriginalFingerprint unset, and rollback —
836+
// which requires a matching fingerprint before it will restore — refused,
837+
// stranding the launcher at codex.opencodex-real. Identity is metadata, not
838+
// content, so the fingerprint must not depend on the file having bytes.
839+
const binDir = mkdtempSync(join(tmpdir(), "ocx-shim-install-unprobeable-bin-"));
840+
const home = mkdtempSync(join(tmpdir(), "ocx-shim-install-unprobeable-home-"));
841+
const oldPath = process.env.PATH;
842+
const oldHome = process.env.OPENCODEX_HOME;
843+
const codexPath = join(binDir, "codex");
844+
const backupPath = `${codexPath}.opencodex-real`;
845+
try {
846+
process.env.PATH = prependPath(binDir, oldPath);
847+
process.env.OPENCODEX_HOME = home;
848+
writeFileSync(codexPath, "", "utf8");
849+
chmodSync(codexPath, 0o755);
850+
setCodexShimFreshWriteHookForTests(() => {
851+
throw new Error("synthetic unprobeable-original rollback");
852+
});
853+
854+
expect(() => installCodexShim()).toThrow("synthetic unprobeable-original rollback");
855+
856+
// The launcher is back where the user had it, still empty and executable,
857+
// and no backup residue is left behind.
858+
expect(existsSync(codexPath)).toBe(true);
859+
expect(readFileSync(codexPath, "utf8")).toBe("");
860+
expect(lstatSync(codexPath).mode & 0o777).toBe(0o755);
861+
expect(existsSync(backupPath)).toBe(false);
862+
expect(existsSync(join(home, "codex-shim.json"))).toBe(false);
863+
} finally {
864+
setCodexShimFreshWriteHookForTests(null);
865+
if (oldPath === undefined) delete process.env.PATH;
866+
else process.env.PATH = oldPath;
867+
if (oldHome === undefined) delete process.env.OPENCODEX_HOME;
868+
else process.env.OPENCODEX_HOME = oldHome;
869+
rmSync(binDir, { recursive: true, force: true });
870+
rmSync(home, { recursive: true, force: true });
871+
}
872+
});
873+
874+
test("Unix rollback restore refuses to replace a launcher published in the restore window", () => {
875+
if (process.platform === "win32") return;
876+
877+
// #1625 follow-up. sourceOccupied is sampled before the backup fingerprint
878+
// check, so a concurrent installer can still publish a launcher at the
879+
// original path afterwards. renameSync would silently delete it; the restore
880+
// uses link()+unlink(), which fails EEXIST instead. Only a hook inside that
881+
// window can reach this: publishing any earlier makes sourceOccupied true and
882+
// skips the restore branch entirely.
883+
const binDir = mkdtempSync(join(tmpdir(), "ocx-shim-restore-window-bin-"));
884+
const home = mkdtempSync(join(tmpdir(), "ocx-shim-restore-window-home-"));
885+
const oldPath = process.env.PATH;
886+
const oldHome = process.env.OPENCODEX_HOME;
887+
const codexPath = join(binDir, "codex");
888+
const backupPath = `${codexPath}.opencodex-real`;
889+
const original = successfulLauncher("restore-window-original");
890+
const intruder = successfulLauncher("restore-window-concurrent-installer");
891+
try {
892+
process.env.PATH = prependPath(binDir, oldPath);
893+
process.env.OPENCODEX_HOME = home;
894+
writeFileSync(codexPath, original, "utf8");
895+
chmodSync(codexPath, 0o755);
896+
setCodexShimFreshWriteHookForTests(() => {
897+
throw new Error("synthetic restore-window failure");
898+
});
899+
setCodexShimRollbackRestoreHookForTests(() => {
900+
writeFileSync(codexPath, intruder, "utf8");
901+
chmodSync(codexPath, 0o755);
902+
});
903+
904+
expect(() => installCodexShim()).toThrow();
905+
906+
// The competing launcher is untouched and the user's original is still
907+
// recoverable from the backup instead of having been overwritten.
908+
expect(readFileSync(codexPath, "utf8")).toBe(intruder);
909+
expect(existsSync(backupPath)).toBe(true);
910+
expect(readFileSync(backupPath, "utf8")).toBe(original);
911+
expect(existsSync(join(home, "codex-shim.json"))).toBe(false);
912+
} finally {
913+
setCodexShimFreshWriteHookForTests(null);
914+
setCodexShimRollbackRestoreHookForTests(null);
915+
if (oldPath === undefined) delete process.env.PATH;
916+
else process.env.PATH = oldPath;
917+
if (oldHome === undefined) delete process.env.OPENCODEX_HOME;
918+
else process.env.OPENCODEX_HOME = oldHome;
919+
rmSync(binDir, { recursive: true, force: true });
920+
rmSync(home, { recursive: true, force: true });
921+
}
922+
});
923+
829924
test("Unix fresh install preserves a concurrent wrapper replacement after a successful probe", () => {
830925
if (process.platform === "win32") return;
831926

0 commit comments

Comments
 (0)