Skip to content

Commit 2cb135b

Browse files
committed
fix(state): recover abandoned response snapshots
1 parent 911373d commit 2cb135b

3 files changed

Lines changed: 157 additions & 2 deletions

File tree

‎src/responses/state.ts‎

Lines changed: 102 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
1+
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, truncateSync, unlinkSync } from "node:fs";
22
import { dirname, join } from "node:path";
33
import { atomicWriteFile, getConfigDir } from "../config";
44
import type { OcxProviderContinuationState } from "../types";
@@ -14,6 +14,10 @@ const MAX_STORED_RESPONSE_BYTES = 64 * 1024 * 1024;
1414
* carry base64 `input_image` data URLs, and one screenshot-heavy thread must not balloon the file. */
1515
const SNAPSHOT_ENTRY_MAX_BYTES = 2 * 1024 * 1024;
1616
const SNAPSHOT_TOTAL_MAX_BYTES = 24 * 1024 * 1024;
17+
const STALE_TEMP_GRACE_MS = 15 * 60 * 1_000;
18+
const STALE_TEMP_MAX_CANDIDATES = 4_096;
19+
const STALE_TEMP_MAX_CLEANUPS = 512;
20+
const RESPONSE_STATE_TEMP_NAME = /^responses-state\.json\.ocx\.(\d+)\.(\d+)\.tmp$/;
1721

1822
interface StoredResponseState {
1923
createdAt: number;
@@ -88,6 +92,102 @@ function snapshotPath(): string {
8892
return join(getConfigDir(), "responses-state.json");
8993
}
9094

95+
export interface ResponseStateTempRecoveryResult {
96+
matched: number;
97+
removed: number;
98+
scrubbed: number;
99+
failed: number;
100+
bytesRemoved: number;
101+
}
102+
103+
interface ResponseStateTempRecoveryIO {
104+
now: () => number;
105+
list: (dir: string) => string[];
106+
inspect: (path: string) => { isFile: boolean; mtimeMs: number; size: number };
107+
isProcessAlive: (pid: number) => boolean;
108+
truncate: (path: string) => void;
109+
unlink: (path: string) => void;
110+
}
111+
112+
function processIsAlive(pid: number): boolean {
113+
if (pid === process.pid) return true;
114+
try {
115+
process.kill(pid, 0);
116+
return true;
117+
} catch (error) {
118+
// EPERM means the process exists but cannot be signalled. Unknown platform errors
119+
// are also protected; cleanup should prefer a false negative over touching a live writer.
120+
return (error as NodeJS.ErrnoException).code !== "ESRCH";
121+
}
122+
}
123+
124+
const responseStateTempRecoveryIO: ResponseStateTempRecoveryIO = {
125+
now: Date.now,
126+
list: dir => readdirSync(dir),
127+
inspect: path => {
128+
const stat = lstatSync(path);
129+
return { isFile: stat.isFile() && !stat.isSymbolicLink(), mtimeMs: stat.mtimeMs, size: stat.size };
130+
},
131+
isProcessAlive: processIsAlive,
132+
truncate: path => truncateSync(path, 0),
133+
unlink: unlinkSync,
134+
};
135+
136+
/**
137+
* Recover only abandoned response-state atomic-write files. The exact basename,
138+
* regular-file check, age gate, and PID liveness check protect unrelated/active files.
139+
* Cleanup is capped and best-effort because continuation state is only a cache.
140+
*/
141+
export function recoverStaleResponseStateTemps(
142+
dir = getConfigDir(),
143+
overrides: Partial<ResponseStateTempRecoveryIO> = {},
144+
): ResponseStateTempRecoveryResult {
145+
const io = { ...responseStateTempRecoveryIO, ...overrides };
146+
const result: ResponseStateTempRecoveryResult = {
147+
matched: 0,
148+
removed: 0,
149+
scrubbed: 0,
150+
failed: 0,
151+
bytesRemoved: 0,
152+
};
153+
let names: string[];
154+
try { names = io.list(dir); } catch { return result; }
155+
let candidates = 0;
156+
for (const name of names) {
157+
const match = RESPONSE_STATE_TEMP_NAME.exec(name);
158+
if (!match) continue;
159+
candidates += 1;
160+
if (candidates > STALE_TEMP_MAX_CANDIDATES || result.removed + result.failed >= STALE_TEMP_MAX_CLEANUPS) break;
161+
result.matched += 1;
162+
const pid = Number(match[1]);
163+
const sequence = Number(match[2]);
164+
if (!Number.isSafeInteger(pid) || pid <= 0 || !Number.isSafeInteger(sequence) || sequence <= 0) continue;
165+
const path = join(dir, name);
166+
let file: ReturnType<ResponseStateTempRecoveryIO["inspect"]>;
167+
try { file = io.inspect(path); } catch { continue; }
168+
if (!file.isFile || io.now() - file.mtimeMs < STALE_TEMP_GRACE_MS) continue;
169+
if (pid === process.pid || io.isProcessAlive(pid)) continue;
170+
171+
let scrubbed = false;
172+
try {
173+
io.truncate(path);
174+
scrubbed = true;
175+
result.scrubbed += 1;
176+
} catch { /* unlink may still remove the sensitive snapshot */ }
177+
try {
178+
io.unlink(path);
179+
result.removed += 1;
180+
result.bytesRemoved += file.size;
181+
} catch {
182+
// A zero-byte residual is harmless privacy-wise but should still count as a
183+
// cleanup failure so a later startup can retry its removal.
184+
result.failed += 1;
185+
if (!scrubbed) continue;
186+
}
187+
}
188+
return result;
189+
}
190+
91191
/**
92192
* Best-effort disk snapshot so previous_response_id chains survive a proxy restart (the
93193
* dominant expansion-miss cause: an in-memory-only store dies with the process, and the next
@@ -100,6 +200,7 @@ function ensureLoaded(): void {
100200
loaded = true;
101201
try {
102202
const path = snapshotPath();
203+
recoverStaleResponseStateTemps(dirname(path));
103204
if (!existsSync(path)) return;
104205
const raw = JSON.parse(readFileSync(path, "utf-8")) as { version?: unknown; states?: unknown };
105206
if ((raw.version !== 1 && raw.version !== 2) || !Array.isArray(raw.states)) return;

‎structure/02_config-and-codex-home.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,21 @@ the resolved `CODEX_HOME`.
1919
sequence number) to avoid collisions when concurrent writers (e.g. `ocx stop` and the proxy's own
2020
shutdown handler) both restore Codex config simultaneously. The temp is renamed atomically into place.
2121

22+
Response-state loading performs a bounded recovery pass for interrupted snapshot writes. It only
23+
matches regular files named `responses-state.json.ocx.<pid>.<sequence>.tmp`, waits at least 15
24+
minutes, and skips the current or any live PID. Eligible files are truncated before unlinking so a
25+
Windows lock that prevents deletion can still leave a privacy-safe zero-byte residual. Unrelated
26+
temporary files, symlinks, directories, and young/active writes are never touched; at most 512 stale
27+
files are attempted per process start.
28+
29+
[Decision Log]
30+
- 목적과 의도: Bound disk and conversation-state retention after abrupt process termination.
31+
- 기존 구현 및 제약 조건: Ordinary write failures clean up immediately, but a killed process cannot run that path and Windows may temporarily lock files.
32+
- 검토한 주요 대안: Delete every `.tmp`, rely on manual cleanup, or recover only exact response-state remnants with age and PID guards.
33+
- 선택한 방식: Run a capped, best-effort, truncate-before-unlink sweep on lazy response-state startup.
34+
- 다른 대안 대신 이 방식을 선택한 이유: It repairs known remnants without broad authority over unrelated temp files or active writers.
35+
- 장점, 단점 및 영향: Old dead-PID files are reclaimed automatically; locked or conservatively classified files remain for a later retry.
36+
2237
## Config injection
2338

2439
`src/codex/inject.ts` inserts root-level keys and an opencodex provider table:

‎tests/responses-state.test.ts‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
2-
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
2+
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
33
import { tmpdir } from "node:os";
44
import { join } from "node:path";
55
import { buildResponseJSON } from "../src/bridge";
@@ -14,6 +14,7 @@ import {
1414
flushResponseState,
1515
previousResponseConversationId,
1616
previousResponseProviderState,
17+
recoverStaleResponseStateTemps,
1718
rememberResponseState,
1819
responseStateMetrics,
1920
setResponseStateByteCapForTests,
@@ -650,6 +651,44 @@ describe("Responses previous_response_id state", () => {
650651
expect(previousResponseConversationId(first.id as string)).toBe("cursor_conv_9");
651652
});
652653

654+
test("recovers only old response-state temps owned by dead processes", () => {
655+
const old = new Date(Date.now() - 60 * 60 * 1_000);
656+
const stale = join(home, "responses-state.json.ocx.4242.1.tmp");
657+
const live = join(home, "responses-state.json.ocx.5252.2.tmp");
658+
const current = join(home, `responses-state.json.ocx.${process.pid}.3.tmp`);
659+
const young = join(home, "responses-state.json.ocx.6262.4.tmp");
660+
const unrelated = join(home, "responses-state.json.ocx.7272.tmp");
661+
const directory = join(home, "responses-state.json.ocx.8282.5.tmp");
662+
for (const path of [stale, live, current, young, unrelated]) writeFileSync(path, "private state");
663+
mkdirSync(directory);
664+
for (const path of [stale, live, current, unrelated, directory]) utimesSync(path, old, old);
665+
666+
const result = recoverStaleResponseStateTemps(home, {
667+
isProcessAlive: pid => pid === 5252,
668+
});
669+
670+
expect(result).toMatchObject({ matched: 5, removed: 1, scrubbed: 1, failed: 0 });
671+
expect(result.bytesRemoved).toBe("private state".length);
672+
expect(existsSync(stale)).toBe(false);
673+
for (const path of [live, current, young, unrelated, directory]) expect(existsSync(path)).toBe(true);
674+
});
675+
676+
test("stale temp recovery is best-effort when scrub and unlink both fail", () => {
677+
const path = join(home, "responses-state.json.ocx.4242.1.tmp");
678+
writeFileSync(path, "private state");
679+
const old = new Date(Date.now() - 60 * 60 * 1_000);
680+
utimesSync(path, old, old);
681+
682+
const result = recoverStaleResponseStateTemps(home, {
683+
isProcessAlive: () => false,
684+
truncate: () => { throw new Error("locked"); },
685+
unlink: () => { throw new Error("locked"); },
686+
});
687+
688+
expect(result).toMatchObject({ matched: 1, removed: 0, scrubbed: 0, failed: 1, bytesRemoved: 0 });
689+
expect(readFileSync(path, "utf-8")).toBe("private state");
690+
});
691+
653692
test("v1 Cursor snapshot migrates to versioned provider state", () => {
654693
mkdirSync(home, { recursive: true });
655694
writeFileSync(join(home, "responses-state.json"), JSON.stringify({

0 commit comments

Comments
 (0)