Skip to content

Commit e69bbf6

Browse files
committed
fix(codex): normalize the Win32 extended-length prefix in history path identity
Codex records some rollout paths as \\?\C:\... and others as C:\.... Both spellings name the same file, but codexHistoryPathIdentity compared them literally (resolve + lowercase only), so the history manifest integrity check failed intact sessions and resume/routing stayed fail-closed until syncResumeHistory=false bypassed it (lidge-jun#4442). The identity now strips the extended-length prefix (drive and UNC forms) before resolving, so database and rollout comparisons converge. Because a prefixed database path also hashed to a different backup filename before this change, readers fall back to the legacy manifest name when no canonical file exists; when both exist the canonical manifest wins and the legacy file is left in place rather than silently replaced. Sessions moved to archived_sessions are a real path change, not a spelling alias, and stay out of scope by design. Reported by @SeanChengN in lidge-jun#4442.
1 parent 9dc30c9 commit e69bbf6

5 files changed

Lines changed: 170 additions & 8 deletions

File tree

‎src/codex/history-manifest.ts‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,32 @@ export type CodexHistoryManifestValidation =
5454
readonly scope: "manifest" | "entry-shape" | "entry-provenance";
5555
};
5656

57+
/**
58+
* Strip the Win32 extended-length prefix: `\\?\C:\...` becomes `C:\...` and
59+
* `\\?\UNC\server\share\...` becomes `\\server\share\...` (forward-slash spellings
60+
* included). Codex records some rollout paths with the prefix and others without, and
61+
* both spellings name the same file — comparing them literally failed the history
62+
* integrity check for intact sessions (#4442). Stripping happens before resolve() so
63+
* the identity converges regardless of host path semantics.
64+
*/
65+
function withoutWindowsExtendedLengthPrefix(path: string): string {
66+
const match = /^(?:[\\/]{2}\?[\\/])(unc[\\/])?/i.exec(path);
67+
if (!match) return path;
68+
return match[1] ? `\\\\${path.slice(match[0].length)}` : path.slice(match[0].length);
69+
}
70+
5771
function codexHistoryPathIdentity(path: string): string {
72+
if (process.platform !== "win32") return resolve(path);
73+
return resolve(withoutWindowsExtendedLengthPrefix(path)).toLowerCase();
74+
}
75+
76+
/**
77+
* Identity as computed before the extended-length prefix was normalized (#4442). A
78+
* state database path spelled `\\?\C:\...` hashed to a DIFFERENT backup filename
79+
* before the fix; readers still check that name so an existing manifest keeps
80+
* shadowing its database instead of reading as absent.
81+
*/
82+
function legacyCodexHistoryPathIdentity(path: string): string {
5883
const canonical = resolve(path);
5984
return process.platform === "win32" ? canonical.toLowerCase() : canonical;
6085
}
@@ -76,6 +101,17 @@ export function codexHistoryBackupId(stateDbPath: string): string {
76101
.slice(0, 16);
77102
}
78103

104+
/**
105+
* Backup filename id under the pre-#4442 identity. Differs from codexHistoryBackupId
106+
* only for extended-length-prefixed database paths; identical everywhere else.
107+
*/
108+
export function legacyCodexHistoryBackupId(stateDbPath: string): string {
109+
return createHash("sha256")
110+
.update(legacyCodexHistoryPathIdentity(stateDbPath))
111+
.digest("hex")
112+
.slice(0, 16);
113+
}
114+
79115
/** Platform-aware identity comparison shared by database and rollout checks. */
80116
export function sameCodexHistoryPath(left: string, right: string): boolean {
81117
return codexHistoryPathIdentity(left) === codexHistoryPathIdentity(right);

‎src/codex/history-provider.ts‎

Lines changed: 32 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import { atomicWriteFile, getConfigDir } from "../config";
88
import {
99
CODEX_HISTORY_RESUMABLE_SOURCES,
1010
codexHistoryBackupId,
11+
legacyCodexHistoryBackupId,
1112
sameCodexHistoryPath,
1213
validateCodexHistoryBackupManifest,
1314
type CodexHistoryBackupEntry,
@@ -32,6 +33,32 @@ export function historyBackupPathFor(stateDbPath: string): string {
3233
return join(getConfigDir(), `codex-history-backup-${codexHistoryBackupId(stateDbPath)}.json`);
3334
}
3435

36+
/**
37+
* Manifest name a database path spelled with the Win32 extended-length prefix
38+
* (`\\?\C:\...`) received before that prefix was normalized out of the identity
39+
* (#4442). Identical to historyBackupPathFor for every other spelling.
40+
*/
41+
export function legacyHistoryBackupPathFor(stateDbPath: string): string {
42+
return join(getConfigDir(), `codex-history-backup-${legacyCodexHistoryBackupId(stateDbPath)}.json`);
43+
}
44+
45+
/**
46+
* The manifest that actually shadows one state database. Canonical name first; when
47+
* only a pre-#4442 extended-length name exists, that manifest still shadows the
48+
* database rather than reading as absent. When BOTH names exist the canonical
49+
* manifest wins and the legacy file is left untouched — a conflict is resolved by
50+
* keeping both, never by silently replacing one.
51+
*/
52+
export function resolveExistingHistoryBackupPath(
53+
stateDbPath: string,
54+
exists: (path: string) => boolean = existsSync,
55+
): string {
56+
const canonical = historyBackupPathFor(stateDbPath);
57+
if (exists(canonical)) return canonical;
58+
const legacy = legacyHistoryBackupPathFor(stateDbPath);
59+
return legacy !== canonical && exists(legacy) ? legacy : canonical;
60+
}
61+
3562
/**
3663
* Open the live `state_5.sqlite` the way the Codex app expects a *secondary* writer to behave:
3764
* wait on the WAL/file lock instead of failing instantly, so we never race the app's own
@@ -318,7 +345,7 @@ export function preflightCodexHistoryInjection(
318345
// A partially restored row may already be native while its manifest still
319346
// owns work. Match the restore worker's target set before removing routing.
320347
const restoreEntries = providerTableMode ? []
321-
: Object.values(readBackup(historyBackupPathFor(resolvedPath), resolvedPath).manifest.entries);
348+
: Object.values(readBackup(resolveExistingHistoryBackupPath(resolvedPath), resolvedPath).manifest.entries);
322349
if (!existsSync(resolvedPath)) {
323350
return restoreEntries.length > 0 ? "history_state_database_missing" : null;
324351
}
@@ -1388,7 +1415,7 @@ function openaiRestoreIsNoop(stateDbPath: string, backupPath: string): boolean {
13881415
export function syncCodexHistoryProvider(
13891416
provider: CodexHistoryProvider,
13901417
stateDbPath = resolveCodexStateDbPath(),
1391-
backupPath = historyBackupPathFor(stateDbPath),
1418+
backupPath = resolveExistingHistoryBackupPath(stateDbPath),
13921419
opts: { skipWhenProvablyNoop?: boolean } = {},
13931420
): CodexHistorySyncResult {
13941421
// Opt-in steady-state gate (Design B loopback callers only): default semantics of
@@ -1714,7 +1741,7 @@ export function restoreLegacyOpenaiHistory(stateDbPath = resolveCodexStateDbPath
17141741
*/
17151742
export function migrateHistoryToOpenai(
17161743
stateDbPath = resolveCodexStateDbPath(),
1717-
backupPath = historyBackupPathFor(stateDbPath),
1744+
backupPath = resolveExistingHistoryBackupPath(stateDbPath),
17181745
opts: { attempts?: number; delayMs?: number; sleepFn?: (ms: number) => void } = {},
17191746
): CodexHistorySyncResult {
17201747
// Steady-state gate: this migration is Design-B-specific (inject + guardian callers),
@@ -1747,7 +1774,7 @@ export function snapshotCodexHistoryNoop(
17471774
const stateDbPresent = existsSync(stateDbPath);
17481775
const backupPresent = existsSync(backupPath);
17491776
const base = { canonicalStateDbPath, stateDbPresent, canonicalBackupPath, backupPresent };
1750-
if (!sameCodexHistoryPath(backupPath, historyBackupPathFor(stateDbPath))) {
1777+
if (!sameCodexHistoryPath(backupPath, resolveExistingHistoryBackupPath(stateDbPath))) {
17511778
return { kind: "unknown", pendingRows: null, backupEntries: null, ...base, reason: "backup-path" };
17521779
}
17531780
const backup = inspectBackupForNoop(backupPath, stateDbPath);
@@ -1831,7 +1858,7 @@ export interface PendingHistoryCount {
18311858
*/
18321859
export function countPendingOpencodexHistory(
18331860
stateDbPath = resolveCodexStateDbPath(),
1834-
backupPath = historyBackupPathFor(stateDbPath),
1861+
backupPath = resolveExistingHistoryBackupPath(stateDbPath),
18351862
opts: { validateRestoreTargets?: boolean } = {},
18361863
): PendingHistoryCount {
18371864
const backup = readBackupStrict(backupPath, stateDbPath);

‎src/codex/native-residue.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import {
22
closeSync,
3+
existsSync,
34
fstatSync,
45
lstatSync,
56
openSync,
@@ -16,7 +17,7 @@ import { Database } from "bun:sqlite";
1617

1718
import { getConfigDir } from "../config";
1819
import { catalogHasRoutedEntries, parseCatalogJson } from "./catalog/parsing";
19-
import { codexHistoryBackupId, validateCodexHistoryBackupManifest } from "./history-manifest";
20+
import { codexHistoryBackupId, legacyCodexHistoryBackupId, validateCodexHistoryBackupManifest } from "./history-manifest";
2021
import {
2122
hasInjectedCodexRouting,
2223
OCX_SECTION_MARKER,
@@ -590,7 +591,13 @@ function classifyHistoryDatabase(path: string): NativeRoutedResidueResult {
590591
}
591592

592593
function historyBackupPath(stateDatabasePath: string): string {
593-
return join(getConfigDir(), `codex-history-backup-${codexHistoryBackupId(stateDatabasePath)}.json`);
594+
const canonical = join(getConfigDir(), `codex-history-backup-${codexHistoryBackupId(stateDatabasePath)}.json`);
595+
if (existsSync(canonical)) return canonical;
596+
// A database path spelled with the Win32 extended-length prefix hashed to a different
597+
// manifest name before #4442; that manifest still shadows the database (and a canonical
598+
// file always wins over it, with the legacy one left in place).
599+
const legacy = join(getConfigDir(), `codex-history-backup-${legacyCodexHistoryBackupId(stateDatabasePath)}.json`);
600+
return legacy !== canonical && existsSync(legacy) ? legacy : canonical;
594601
}
595602

596603
function classifyHistoryBackup(path: string, stateDatabasePath: string): NativeRoutedResidueResult {

‎structure/config.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,15 @@ backup manifest. It owns the accepted provider/source provenance tuples, platfor
132132
path identity, backup filename id, and validation from unknown JSON to a typed manifest. It does
133133
not read files, inspect rollouts, open SQLite, retry, fingerprint, write, or delete anything.
134134

135+
On Windows the path identity strips the extended-length prefix (`\\?\` and `\\?\UNC\`)
136+
before resolution, because Codex records both spellings for the same file and comparing them
137+
literally failed the integrity check for intact sessions (#4442). A database path spelled with
138+
that prefix hashed to a different backup filename before the normalization, so the readers
139+
(`history-provider.ts` for mutation, `native-residue.ts` for observation) fall back to the
140+
legacy filename when no canonical manifest exists. When both names exist the canonical manifest
141+
wins and the legacy file is left in place; a conflict is never resolved by silently replacing
142+
either file.
143+
135144
`history-provider.ts` remains the strict mutation owner and maps shared validation failures to its
136145
restore/no-op integrity states. `native-residue.ts` remains a read-only observer and maps the same
137146
result to clean, residue, or indeterminate before inspecting referenced rollout files.

‎tests/codex-integration/codex-history-provider.test.ts‎

Lines changed: 84 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@ import { tmpdir } from "node:os";
33
import { join } from "node:path";
44
import { Database } from "bun:sqlite";
55
import { afterEach, describe, expect, setDefaultTimeout, test } from "bun:test";
6-
import { classifyRecoverableHistoryError, countPendingOpencodexHistory, historyBackupPathFor, isRecoverableHistoryError, migrateHistoryToOpenai, restoreLegacyOpenaiHistory, restoredUserEventFor, setAfterNoopPendingCountForTests, setAfterStrictHistoryRolloutAppendForTests, setBeforeHistoryApplyTransactionForTests, setBeforeHistoryBackupConsumeForTests, setBeforeStrictHistoryRolloutAppendForTests, setHistoryDbBusyTimeoutForTests, snapshotCodexHistoryNoop, syncCodexHistoryProvider, withHistoryRetry } from "../../src/codex/history-provider";
6+
import { classifyRecoverableHistoryError, countPendingOpencodexHistory, historyBackupPathFor, isRecoverableHistoryError, legacyHistoryBackupPathFor, migrateHistoryToOpenai, resolveExistingHistoryBackupPath, restoreLegacyOpenaiHistory, restoredUserEventFor, setAfterNoopPendingCountForTests, setAfterStrictHistoryRolloutAppendForTests, setBeforeHistoryApplyTransactionForTests, setBeforeHistoryBackupConsumeForTests, setBeforeStrictHistoryRolloutAppendForTests, setHistoryDbBusyTimeoutForTests, snapshotCodexHistoryNoop, syncCodexHistoryProvider, withHistoryRetry } from "../../src/codex/history-provider";
7+
import { codexHistoryBackupId, legacyCodexHistoryBackupId, sameCodexHistoryPath } from "../../src/codex/history-manifest";
78
import { INVALID_HISTORY_BACKUP_FIXTURES, validHistoryBackupFixture } from "../helpers/codex-history-manifest-fixtures";
89
import { preflightCodexHistoryInjection, setHistoryAppendHooksForTests } from "../../src/codex/history-provider";
910

@@ -1514,3 +1515,85 @@ describe("Design B migration helpers", () => {
15141515
db.close();
15151516
});
15161517
});
1518+
1519+
/**
1520+
* #4442: Codex records some rollout paths with the Win32 extended-length prefix
1521+
* (`\\?\C:\...`) and others without. Both spellings name the same file, but the
1522+
* integrity check compared them literally and failed intact sessions. The identity
1523+
* leaf strips the prefix before resolving, and the manifest filename keeps a
1524+
* legacy-name fallback so a backup written under the pre-fix identity is still
1525+
* discovered. These tests fake win32 to pin the path shapes directly; the real
1526+
* platform is restored after each one.
1527+
*/
1528+
describe("Windows history path identity (#4442)", () => {
1529+
const originalPlatform = process.platform;
1530+
afterEach(() => {
1531+
Object.defineProperty(process, "platform", { configurable: true, value: originalPlatform });
1532+
});
1533+
const fakeWin32 = () => {
1534+
Object.defineProperty(process, "platform", { configurable: true, value: "win32" });
1535+
};
1536+
1537+
test("treats extended-length-prefixed spellings as the same file", () => {
1538+
fakeWin32();
1539+
expect(sameCodexHistoryPath(
1540+
"\\\\?\\C:\\Users\\a\\.codex\\sessions\\r.jsonl",
1541+
"C:\\Users\\a\\.codex\\sessions\\r.jsonl",
1542+
)).toBe(true);
1543+
// The case-insensitive contract still holds across the prefix boundary.
1544+
expect(sameCodexHistoryPath(
1545+
"c:\\users\\a\\r.jsonl",
1546+
"\\\\?\\C:\\Users\\A\\r.jsonl",
1547+
)).toBe(true);
1548+
// The UNC form maps to its bare-share spelling.
1549+
expect(sameCodexHistoryPath(
1550+
"\\\\?\\UNC\\server\\share\\r.jsonl",
1551+
"\\\\server\\share\\r.jsonl",
1552+
)).toBe(true);
1553+
// Prefix normalization must not collapse genuinely different files.
1554+
expect(sameCodexHistoryPath(
1555+
"\\\\?\\C:\\Users\\a\\r.jsonl",
1556+
"C:\\Users\\a\\other.jsonl",
1557+
)).toBe(false);
1558+
// An archived_sessions move is a real path change, not a spelling alias (#4442
1559+
// keeps those cases out of this fix by design).
1560+
expect(sameCodexHistoryPath(
1561+
"\\\\?\\C:\\Users\\a\\.codex\\archived_sessions\\r.jsonl",
1562+
"C:\\Users\\a\\.codex\\sessions\\r.jsonl",
1563+
)).toBe(false);
1564+
});
1565+
1566+
test("hashes both spellings to one backup id while keeping the pre-fix id reachable", () => {
1567+
fakeWin32();
1568+
const plain = "C:\\Users\\a\\.codex\\state_5.sqlite";
1569+
const prefixed = "\\\\?\\C:\\Users\\a\\.codex\\state_5.sqlite";
1570+
expect(codexHistoryBackupId(prefixed)).toBe(codexHistoryBackupId(plain));
1571+
// The prefixed spelling hashed to a DIFFERENT manifest name before #4442; that is
1572+
// the file a machine that recorded the prefix already has on disk, so the legacy
1573+
// id must stay computable. Plain spellings are untouched by the whole change.
1574+
expect(legacyCodexHistoryBackupId(prefixed)).not.toBe(codexHistoryBackupId(prefixed));
1575+
expect(legacyCodexHistoryBackupId(plain)).toBe(codexHistoryBackupId(plain));
1576+
});
1577+
1578+
test("discovers a manifest named under the pre-#4442 identity and never replaces it silently", () => {
1579+
fakeWin32();
1580+
const stateDb = "\\\\?\\C:\\Users\\a\\.codex\\state_5.sqlite";
1581+
const canonical = historyBackupPathFor(stateDb);
1582+
const legacy = legacyHistoryBackupPathFor(stateDb);
1583+
expect(legacy).not.toBe(canonical);
1584+
1585+
const present = new Set<string>([legacy]);
1586+
const exists = (path: string) => present.has(path);
1587+
// Only the legacy name exists: it still shadows the database, so restore and
1588+
// no-op probes keep finding its provenance instead of reading it as absent.
1589+
expect(resolveExistingHistoryBackupPath(stateDb, exists)).toBe(legacy);
1590+
// Both names exist (conflicting old/new manifests): the canonical manifest wins
1591+
// and the legacy file is left in place — kept, never silently replaced.
1592+
present.add(canonical);
1593+
expect(resolveExistingHistoryBackupPath(stateDb, exists)).toBe(canonical);
1594+
expect(present.has(legacy)).toBe(true);
1595+
// Neither exists: a new manifest is written under the canonical name.
1596+
present.clear();
1597+
expect(resolveExistingHistoryBackupPath(stateDb, exists)).toBe(canonical);
1598+
});
1599+
});

0 commit comments

Comments
 (0)