Skip to content

Commit 1a9eb11

Browse files
axisrowclaude
andauthored
feat(worktree): isolated rescue worktree, leave-branch cleanup (based on openai#137) (#12)
* feat(worktree): isolated rescue worktree, leave-branch cleanup (based on openai#137) Adds git-worktree isolation for write-capable rescue (/codex:rescue --worktree), the write-race fix tracked in fork#10 / openai#135. This commit ports the library layer + tests only; companion (--worktree flag) and markdown wiring follow in subsequent PRs. Based on @peterdrier's openai#137, refactored to a "leave-branch" cleanup model. The original capture-then-remove model (snapshot -> apply patch -> force-remove worktree + delete branch) had a deep fail-open class: `git add -A` skips ignored files (.env, dist/), dirty submodules and binary content can't be fully captured, and there is an inherent TOCTOU window between snapshot and remove. Four adversarial review cycles against the straight port found 10 data-loss paths of this shape, each fix closing one edge and the next cycle finding another. Removing the Destroy path removes the entire class by construction. Design (leave-branch): cleanupWorktreeSession NEVER removes the worktree or its branch. keep applies the tracked patch into repoRoot (byte-preserving via `git diff --cached --binary --output`, no JS-string round-trip) and leaves the worktree + branch for the user to inspect and remove manually. discard is a no-op. The cost is one `git worktree remove --force <path> && git branch -D <branch>` per rescue — acceptable for a rare, high-stakes operation whose whole point is write-safety. TOCTOU and the discard-after-failed-keep trap close for free because there is no Destroy path to gate. Files: - plugins/codex/scripts/lib/git.mjs: createWorktree, getWorktreeDiff (gitChecked, throw on failure), applyWorktreePatch (byte-preserving patch transfer). No removeWorktree/deleteWorktreeBranch/hasIgnoredChanges — those belonged to the removed Destroy path. - plugins/codex/scripts/lib/worktree.mjs (NEW): createWorktreeSession / diffWorktreeSession / cleanupWorktreeSession (leave-branch contract). - plugins/codex/scripts/lib/render.mjs: renderWorktreeTaskResult / renderWorktreeCleanupResult — always preservation + manual-remove instructions. - tests/worktree.test.mjs (NEW, 11 tests): session creation, diff capture, and the leave-branch invariant (worktree + branch survive keep tracked-only / ignored-only / mixed tracked+ignored, and discard no-op), byte round-trip, render. The invariant tests replace the old removal-assertion tests and are the proof the fail-open class is closed. Verified: worktree 11/11, full npm test 152 pass / 4 pre-existing (unchanged). Refs fork#10, openai#135, openai#137 (@peterdrier). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0189cGaohsYdpkB4otKZnpAt * fix(worktree): staged-aware recovery instructions + signal/spawn fail-closed runCommand Cycle-1 review of PR #12 (Codex + Claude subagent). Two real findings: 1. (Codex) The rendered inspection command was plain `git -C <path> diff`, but rescue changes are STAGED — getWorktreeDiff/applyWorktreePatch run `git add -A`, so `git diff` (unstaged-only) can read empty even when staged tracked/binary/formerly-untracked work exists. A user following the instructions would see "no changes", then force-remove the worktree + branch and irreversibly lose the staged work. Fixed: render a HEAD/base- based diff (`git diff <baseCommit> --binary --submodule=diff`) that includes staged state, plus a `git status --porcelain --ignored -uall` step, and a warning that ignored/submodule work is NOT in the diff. Regression test asserts the inspection command references baseCommit (not a bare `diff`). 2. (Claude) runCommand still normalized a signal-terminated OR spawn-failed child to status:0 (`result.status ?? 0`). A killed git apply (OOM, timeout) or missing git binary (ENOENT) read as success → false-success reporting on worktree capture/apply. Under leave-branch this is no longer data-loss (worktree preserved), but it's a correctness defect with the same root cause. Fixed structurally in process.mjs runCommand: `failed = signal != null || error; status = failed ? 1 : ...`. Regression tests: SIGKILL self-kill and ENOENT both report non-zero status. Codex also flagged "worktree isolation is dead code" — IRRELEVANT to this PR by design: this is the library layer; companion (--worktree wiring) is the next PR. The leave-branch invariant claim (Claude) is confirmed: no production Destroy path exists. Verified: worktree 12/12, process 5/5; full npm test 155 pass / 4 pre-existing. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0189cGaohsYdpkB4otKZnpAt --------- Co-authored-by: axisrow <[email protected]> Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 52bd80f commit 1a9eb11

6 files changed

Lines changed: 533 additions & 3 deletions

File tree

‎plugins/codex/scripts/lib/git.mjs‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,79 @@ function buildAdversarialCollectionGuidance(options = {}) {
297297
return "The repository context below is a lightweight summary. Inspect the target diff yourself with read-only git commands before finalizing findings.";
298298
}
299299

300+
// Worktree isolation for write-capable rescue (write-race fix, openai#135).
301+
// Ported from @peterdrier's openai/codex-plugin-cc#137, refactored to a
302+
// "leave-branch" cleanup model: the worktree is NEVER auto-removed by this library —
303+
// keep applies the tracked patch and leaves the worktree + branch for the user to
304+
// inspect and remove manually. The original capture-then-remove model had a deep
305+
// fail-open class (git add -A skips ignored files; dirty submodules and
306+
// binary content can't be fully captured; TOCTOU between snapshot and remove)
307+
// — removing the Destroy path removes the class by construction.
308+
309+
export function createWorktree(repoRoot) {
310+
const ts = Date.now();
311+
const worktreesDir = path.join(repoRoot, ".worktrees");
312+
fs.mkdirSync(worktreesDir, { recursive: true });
313+
314+
// Ensure .worktrees/ is excluded from the target repo without modifying tracked files.
315+
// Use git rev-parse to resolve the real git dir (handles linked worktrees where .git is a file).
316+
const rawGitDir = gitChecked(repoRoot, ["rev-parse", "--git-dir"]).stdout.trim();
317+
const gitDir = path.resolve(repoRoot, rawGitDir);
318+
const excludePath = path.join(gitDir, "info", "exclude");
319+
const excludeContent = fs.existsSync(excludePath) ? fs.readFileSync(excludePath, "utf8") : "";
320+
if (!excludeContent.includes(".worktrees")) {
321+
fs.mkdirSync(path.dirname(excludePath), { recursive: true });
322+
fs.appendFileSync(excludePath, `${excludeContent.endsWith("\n") || !excludeContent ? "" : "\n"}.worktrees/\n`);
323+
}
324+
325+
const worktreePath = path.join(worktreesDir, `codex-${ts}`);
326+
const branch = `codex/${ts}`;
327+
const baseCommit = gitChecked(repoRoot, ["rev-parse", "HEAD"]).stdout.trim();
328+
gitChecked(repoRoot, ["worktree", "add", worktreePath, "-b", branch]);
329+
return { worktreePath, branch, repoRoot, baseCommit, timestamp: ts };
330+
}
331+
332+
export function getWorktreeDiff(worktreePath, baseCommit) {
333+
// gitChecked (not git): a failed snapshot must throw, not be misclassified as
334+
// "no changes" — that was the fail-open root of the capture-then-remove bugs.
335+
gitChecked(worktreePath, ["add", "-A"]);
336+
const result = git(worktreePath, ["diff", "--cached", baseCommit, "--stat"]);
337+
if (result.status !== 0) {
338+
throw new Error(`Failed to diff worktree: ${result.stderr.trim()}`);
339+
}
340+
if (!result.stdout.trim()) {
341+
return { stat: "", patch: "" };
342+
}
343+
const stat = result.stdout.trim();
344+
const patchResult = gitChecked(worktreePath, ["diff", "--cached", baseCommit]);
345+
return { stat, patch: patchResult.stdout };
346+
}
347+
348+
export function applyWorktreePatch(repoRoot, worktreePath, baseCommit) {
349+
const patchPath = path.join(
350+
repoRoot,
351+
".codex-worktree-" + Date.now() + "-" + Math.random().toString(16).slice(2) + ".patch"
352+
);
353+
try {
354+
// Byte-preserving: write the patch via `git diff --cached --binary --output`
355+
// (git→file, never through a JS string). runCommand decodes stdout as UTF-8,
356+
// which would replace invalid bytes (0xff, NUL, legacy encodings) with U+FFFD
357+
// and apply a corrupted patch as "success". Detect empty via file size.
358+
gitChecked(worktreePath, ["add", "-A"]);
359+
gitChecked(worktreePath, ["diff", "--cached", "--binary", baseCommit, "--output", patchPath]);
360+
if (!fs.existsSync(patchPath) || fs.statSync(patchPath).size === 0) {
361+
return { applied: false, detail: "No tracked changes to apply." };
362+
}
363+
const applyResult = git(repoRoot, ["apply", "--index", patchPath]);
364+
if (applyResult.status !== 0) {
365+
return { applied: false, detail: applyResult.stderr.trim() || "Patch apply failed (conflicts?)." };
366+
}
367+
return { applied: true, detail: "Tracked changes applied and staged." };
368+
} finally {
369+
fs.rmSync(patchPath, { force: true });
370+
}
371+
}
372+
300373
export function collectReviewContext(cwd, target, options = {}) {
301374
const repoRoot = getRepoRoot(cwd);
302375
const currentBranch = getCurrentBranch(repoRoot);

‎plugins/codex/scripts/lib/process.mjs‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,23 @@ export function runCommand(command, args = [], options = {}) {
1313
windowsHide: true
1414
});
1515

16+
const succeeded = result.status === 0 && result.signal === null && !result.error;
17+
// A child killed by a signal OR that failed to spawn (ENOENT/EAGAIN/maxBuffer)
18+
// returns status:null from spawnSync. Treat any of those as a non-zero exit so
19+
// callers that check status===0 don't mistake an abnormal process for success —
20+
// for worktree patch capture/apply that would mean reporting a killed git op
21+
// (false-success) while the work holds un-captured changes.
22+
const failed = result.signal !== null || result.error;
23+
const status = failed ? 1 : result.status ?? 0;
24+
1625
return {
1726
command,
1827
args,
19-
status: result.status ?? 0,
28+
status,
2029
signal: result.signal ?? null,
2130
stdout: result.stdout ?? "",
2231
stderr: result.stderr ?? "",
23-
error: result.error ?? null
32+
error: succeeded ? null : result.error ?? null
2433
};
2534
}
2635

‎plugins/codex/scripts/lib/render.mjs‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -445,6 +445,62 @@ export function renderStoredJobResult(job, storedJob) {
445445
return `${lines.join("\n").trimEnd()}\n`;
446446
}
447447

448+
// Worktree isolation render (leave-branch model). The worktree + branch are
449+
// ALWAYS preserved — keep applies the tracked patch and leaves them for manual
450+
// inspection. There is no destructive discard command.
451+
export function renderWorktreeTaskResult(execution, session, diff, { jobId = null } = {}) {
452+
const lines = [];
453+
454+
if (execution.rendered) {
455+
lines.push(execution.rendered.trimEnd());
456+
lines.push("");
457+
}
458+
459+
lines.push("---");
460+
lines.push("");
461+
lines.push("## Worktree (preserved)");
462+
lines.push("");
463+
lines.push(`Branch: \`${session.branch}\``);
464+
lines.push(`Path: \`${session.worktreePath}\``);
465+
lines.push("");
466+
467+
if (diff.stat) {
468+
lines.push("### Changes");
469+
lines.push("");
470+
lines.push("```");
471+
lines.push(diff.stat);
472+
lines.push("```");
473+
lines.push("");
474+
} else {
475+
lines.push("Codex made no tracked file changes in the worktree.");
476+
lines.push("");
477+
}
478+
479+
lines.push("### Inspect and remove manually");
480+
lines.push("");
481+
lines.push("The worktree and branch are kept for inspection. Rescue changes are staged here — review with a HEAD-based diff that includes staged work:");
482+
lines.push("");
483+
lines.push(`- \`git -C ${session.worktreePath} diff ${session.baseCommit} --binary --submodule=diff\` (review tracked changes vs base, including staged)`);
484+
lines.push(`- \`git -C ${session.worktreePath} status --porcelain --ignored -uall\` (also check for ignored/submodule work the diff will not show)`);
485+
lines.push("");
486+
lines.push(`Only once you have verified (or copied out) everything you need, remove:`);
487+
lines.push("");
488+
lines.push(`- \`git worktree remove --force ${session.worktreePath} && git branch -D ${session.branch}\``);
489+
lines.push("");
490+
lines.push("_Warning: ignored files (e.g. .env, dist/) and submodule changes are NOT in the diff above and are NOT captured by the apply patch — copy them out of the worktree before removing, or they are lost._");
491+
492+
return `${lines.join("\n").trimEnd()}\n`;
493+
}
494+
495+
export function renderWorktreeCleanupResult(action, result, session) {
496+
const lines = ["# Worktree Cleanup", ""];
497+
lines.push(`Action: ${action}.`);
498+
lines.push(`Result: ${result.detail}`);
499+
lines.push("");
500+
lines.push(`The worktree \`${session.worktreePath}\` and branch \`${session.branch}\` are preserved regardless of this action — remove them manually after inspecting.`);
501+
return `${lines.join("\n").trimEnd()}\n`;
502+
}
503+
448504
export function renderCancelReport(job) {
449505
const lines = [
450506
"# Codex Cancel",
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Worktree isolation for write-capable rescue (write-race fix, openai#135).
2+
// Ported from @peterdrier's openai/codex-plugin-cc#137, refactored to a
3+
// "leave-branch" cleanup model.
4+
//
5+
// DESIGN: cleanupWorktreeSession NEVER removes the worktree or its branch.
6+
// - keep: applies the tracked patch into repoRoot, then leaves the worktree
7+
// + branch in place for the user to inspect and remove manually.
8+
// - discard: no-op; leaves the worktree + branch in place.
9+
//
10+
// Why: the original capture-then-remove model (snapshot → apply → force-remove)
11+
// had a deep fail-open class — `git add -A` skips ignored files (.env, dist/),
12+
// dirty submodules and binary content can't be fully captured, and there is an
13+
// inherent TOCTOU window between snapshot and remove. Each fix closed one edge
14+
// and the next review cycle found another (4 cycles, 10 findings). Removing the
15+
// Destroy path removes the entire class by construction. The cost is one manual
16+
// `git worktree remove --force <path> && git branch -D <branch>` per rescue —
17+
// acceptable for a rare, high-stakes operation whose whole point is write-safety.
18+
19+
import {
20+
createWorktree,
21+
getWorktreeDiff,
22+
applyWorktreePatch,
23+
ensureGitRepository
24+
} from "./git.mjs";
25+
26+
export function createWorktreeSession(cwd) {
27+
const repoRoot = ensureGitRepository(cwd);
28+
return createWorktree(repoRoot);
29+
}
30+
31+
export function diffWorktreeSession(session) {
32+
return getWorktreeDiff(session.worktreePath, session.baseCommit);
33+
}
34+
35+
// Returns the manual-removal hint included in every cleanup result. The worktree
36+
// and branch are ALWAYS preserved; the user removes them after inspecting.
37+
function preservationNote(session) {
38+
return `Worktree and branch preserved for inspection. Remove manually when done: git worktree remove --force ${session.worktreePath} && git branch -D ${session.branch}`;
39+
}
40+
41+
/**
42+
* Leave-branch cleanup. Never destroys the worktree.
43+
*
44+
* keep=true: applies the tracked patch into session.repoRoot (staged), leaves
45+
* the worktree + branch in place. Returns {applied, detail}.
46+
* keep=false: no-op, leaves the worktree + branch in place. Returns {applied:false, detail}.
47+
*
48+
* In both cases the worktree survives — the caller renders preservationNote()
49+
* so the user knows how to remove it manually after inspecting.
50+
*/
51+
export function cleanupWorktreeSession(session, { keep = false } = {}) {
52+
if (keep) {
53+
const result = applyWorktreePatch(session.repoRoot, session.worktreePath, session.baseCommit);
54+
return {
55+
...result,
56+
preserved: true,
57+
detail: `${result.detail} ${preservationNote(session)}`
58+
};
59+
}
60+
return {
61+
applied: false,
62+
preserved: true,
63+
detail: `Worktree discarded-from-transfer (left in place). ${preservationNote(session)}`
64+
};
65+
}

‎tests/process.test.mjs‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import test from "node:test";
22
import assert from "node:assert/strict";
33

4-
import { terminateProcessTree } from "../plugins/codex/scripts/lib/process.mjs";
4+
import { terminateProcessTree, runCommand } from "../plugins/codex/scripts/lib/process.mjs";
55

66
test("terminateProcessTree uses taskkill on Windows", () => {
77
let captured = null;
@@ -84,3 +84,20 @@ test("terminateProcessTree recognizes a missing Windows process with localized o
8484
assert.equal(outcome.delivered, false);
8585
assert.equal(outcome.method, "taskkill");
8686
});
87+
88+
// Regression: a child killed by a signal OR that failed to spawn returns
89+
// status:null from spawnSync. runCommand must NOT normalize that to status:0 —
90+
// callers checking status===0 would mistake a killed/missing git op (e.g. git
91+
// apply killed mid-run, or git missing) for success. For worktree patch capture/
92+
// apply that means false-success while the work holds un-captured changes.
93+
test("runCommand reports a signal-terminated child as failed (non-zero status)", () => {
94+
const result = runCommand(process.execPath, ["-e", "process.kill(process.pid, 'SIGKILL')"]);
95+
assert.ok(result.signal !== null, `expected a signal, got signal=${result.signal}`);
96+
assert.notEqual(result.status, 0, `signal-terminated child must not report status 0, got ${result.status}`);
97+
});
98+
99+
test("runCommand reports a spawn failure (ENOENT) as failed (non-zero status)", () => {
100+
const result = runCommand("/nonexistent-codex-binary-xyz", []);
101+
assert.ok(result.error, `expected an error, got ${result.error}`);
102+
assert.notEqual(result.status, 0, `spawn failure must not report status 0, got ${result.status}`);
103+
});

0 commit comments

Comments
 (0)