forgedock 1.23.1 → 1.24.1

package/bin/lean/lean.test.mjs

@@ -4,14 +4,20 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { tmpDir } from "../tests/_tmp.mjs";
 import { runCore } from "./lean.mjs";
-import { renderValidate, renderPlan, renderReview, renderRegister, renderPrBody, cell, NR } from "./render.mjs";
+import { renderInvestigation, renderPlan, renderImplementation, renderReview, renderPrBody, renderTrajectory, sanitizeMd, capComment, section, cell, NR, MAX_COMMENT_CHARS } from "./render.mjs";
 import { orchestrate, parseDeps, formatTable } from "./orchestrate.mjs";
 import { REVIEWER_SYSTEM, approxTokens, builderPrompt, reviewerPrompt, parseVerdict } from "./prompts.mjs";
 import { mapRecord } from "../engine/telemetry-seam.mjs";
 import { readLog } from "../engine/runlog.mjs";
+import { makeRunTmp } from "./effects.mjs";
 import { runFromCli, orchestrateFromCli, ENGINE_PATHS } from "../engine-cli.mjs";
 
 const WT = "/wt/lean-7";
+const STAGE_MD = {
+  investigation: "**Verdict**: CONFIRMED\n**Confidence**: high\n**Severity**: medium\n**Task Type**: bug\n\n### What Was Claimed\nfoo breaks\n\n### What We Found\n- src/foo.js:3 derefs null\n\n### Root Cause\nfoo derefs null at src/foo.js:3\n\n### Affected Files\n- src/foo.js: add guard\n\n### Sibling Sweep\n- src/bar.js:8 same guard\n\n### History\nintroduced in abc123\n\n### Recommendation\nguard null\n\n### Related Issues\nnone",
+  plan: "### Approach\nguard null in foo\n\n### Deliverables\n| File | Change | Why |\n| --- | --- | --- |\n| src/foo.js | add guard | avoid crash |\n\n### Acceptance Criteria\n- [ ] foo handles null\n\n### Implementation Order\n1. guard\n\n### Out of Scope\nrefactor: later\n\n### Risk Assessment\n| Risk | Severity | Mitigation |\n| --- | --- | --- |\n| none | low | test |",
+  implementation: "### Approach\nadded a guard\n\n### Changes\n- src/foo.js: guard\n\n### Acceptance Criteria Status\n- ✅ foo handles null\n\n### Verification\n- node --test test/foo.test.js: pass, fails without fix: yes\n\n### Notes\nnone",
+};
 const ok = (extra = {}) => "```json\n" + JSON.stringify({ verdict: "PASS", fixes_issue: true, regression: false, reason: "src/foo.js:3 fixed", ...extra }) + "\n```";
 const bad = (reason = "src/foo.js:9 still wrong") => ok({ verdict: "FAIL", fixes_issue: false, reason });
 
@@ -21,8 +27,12 @@ function world(o = {}) {
     comments: [], labels: [], closed: [], edits: [], prs: [], merges: [], calls: [], telemetry: [], files: {}, head: "aaaa1111aaaa1111",
     changed: o.changed ?? ["src/foo.js", "test/foo.test.js"], reviews: [...(o.reviews ?? [])], waits: [...(o.waits ?? [])], clock: 0,
     result: o.result ?? { status: "fixed", summary: "fixed foo", evidence: [], tests: ["test/foo.test.js"] },
-    prList: o.prList ?? [], remote: o.remote ?? "", resumeResult: o.resumeResult, seq: [],
+    prList: o.prList ?? [], remote: o.remote ?? "", resumeResult: o.resumeResult, seq: [], mtimes: {}, envs: [], prView: [...(o.prView ?? [])], mergeResults: [...(o.mergeResults ?? [])], mergeErrors: [...(o.mergeErrors ?? [])], conflictFiles: [], mergeInProgress: false, markers: false, mergeAttempts: 0,
+    stages: { ...STAGE_MD, ...(o.stages ?? {}) },
   };
+  const put = (name, text) => { const p = `${WT}/.forge-lean/${name}`; if (w.files[p] !== text) w.mtimes[p] = Date.now(); w.files[p] = text; };
+  const writeStages = (keys) => { for (const k of keys) if (w.stages[k] != null) put(`${k}.md`, w.stages[k]); };
+  w.writeStages = writeStages;
   w.io = {
     now: () => w.clock, sleep: async (ms) => { w.clock += ms; },
     gh: async (a) => {
@@ -34,12 +44,28 @@ function world(o = {}) {
       if (k === "issue close") { w.closed.push(a); w.seq.push("close"); return ""; }
       if (k === "issue edit") { w.edits.push(a); return ""; }
       if (k === "pr create") { w.prs.push(a); w.seq.push("pr"); return "https://github.com/o/r/pull/77\n"; }
+      if (k === "pr view" && a.includes("mergeable,mergeStateStatus")) { const v = w.prView.length > 1 ? w.prView.shift() : (w.prView[0] ?? { mergeable: "MERGEABLE", mergeStateStatus: "CLEAN" }); return JSON.stringify(v); }
+      if (k === "pr merge" && w.mergeErrors.length) { w.mergeAttempts++; throw new Error(w.mergeErrors.shift()); }
+      if (k === "pr merge") { w.mergeAttempts++; }
       if (k === "pr merge") { w.merges.push(a); w.seq.push("merge"); return ""; }
       throw new Error(`unexpected gh ${a.join(" ")}`);
     },
     git: async (a) => {
       w.calls.push(["git", ...a]);
+      if (a[0] === "worktree" && a[1] === "add" && (w.lockFails ?? 0) > 0) {
+        w.lockFails--; const e = new Error("git failed"); e.stderr = "error: could not lock config file .git/config: File exists"; throw e;
+      }
       if (a[0] === "rev-parse" && a[1] === "--git-path") return "/repo/.git/info/exclude";
+      if (a[0] === "merge" && a[1] === "--no-edit") {
+        const r = w.mergeResults.shift() ?? "clean";
+        if (r === "clean") { w.head = `cccc${w.calls.length}`.padEnd(16, "0"); return ""; }
+        w.conflictFiles = o.conflictFiles ?? ["src/foo.js"]; w.mergeInProgress = true; throw new Error("CONFLICT (content): Merge conflict in src/foo.js");
+      }
+      if (a[0] === "rev-parse" && a.includes("MERGE_HEAD")) return w.mergeInProgress ? "deadbeef" : "";
+      if (a[0] === "diff" && a.includes("--diff-filter=U")) return w.conflictFiles.join("\n");
+      if (a[0] === "diff" && a[1] === "--check") return "";
+      if (a[0] === "grep") return w.markers ? "src/foo.js:3:<<<<<<< HEAD" : "";
+      if (a[0] === "merge" && a[1] === "--abort") { w.mergeInProgress = false; return ""; }
       if (a[0] === "rev-parse") return w.head;
       if (a[0] === "diff" && a[1] === "--name-only") return w.changed.join("\n");
       if (a[0] === "diff") return "diff --git a/src/foo.js b/src/foo.js\n+fix";
@@ -50,17 +76,20 @@ function world(o = {}) {
     runner: async (c) => {
       w.calls.push(["runner", c.role, c.resume ?? null, c.model ?? null, c.prompt, c.readOnly ?? false, c.system]);
       w.seq.push(c.role + (c.resume ? "-resume" : ""));
+      w.envs.push(c.env ?? null);
       if (c.role === "builder") {
         const r = c.resume ? (w.resumeResult ?? w.result) : w.result;
-        if (r) w.files[`${WT}/.forge-lean/result.json`] = JSON.stringify(r);
-        if (c.resume) w.head = `bbbb${w.calls.length}`.padEnd(16, "0");
+        if (o.live) await o.live(w, put);
+        else if (!c.resume && !o.noStages) writeStages(["investigation", "plan", "implementation"]);
+        if (r) put("result.json", JSON.stringify(r));
+        if (c.resume || /Merging origin\//.test(c.prompt)) { w.head = `bbbb${w.calls.length}`.padEnd(16, "0"); if (!o.leaveConflicts) { w.conflictFiles = []; w.mergeInProgress = false; } }
         return { text: "done", sessionId: "sess-1", usage: { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 100 }, costUsd: 0.1, durationMs: 1000, turns: 3, model: "default" };
       }
       return { text: w.reviews.length ? w.reviews.shift() : ok(), sessionId: "rev", usage: { input_tokens: 4, output_tokens: 2 }, costUsd: 0.05, durationMs: 500, turns: 2, model: c.model };
     },
     waitCiGreen: async () => (w.waits.length ? w.waits.shift() : { rc: 0, text: `CI_GATE_HEAD: ${w.head}` }),
     transitionLabel: async (n, s) => { w.labels.push(s); w.seq.push(`label:${s}`); },
-    fs: { read: async (p) => { if (!(p in w.files)) throw new Error("ENOENT"); return w.files[p]; }, append: async (p, t) => { w.files[p] = (w.files[p] ?? "") + t; } },
+    fs: { stat: async (p) => (p in w.files ? { mtimeMs: w.mtimes[p] ?? 1 } : null), read: async (p) => { if (!(p in w.files)) throw new Error("ENOENT"); return w.files[p]; }, append: async (p, t) => { w.files[p] = (w.files[p] ?? "") + t; } },
   };
   return w;
 }
@@ -68,22 +97,34 @@ const run = (w, extra = {}) => runCore({ issue: 7, repo: "o/r", lane: "staging",
   io: w.io, emitTelemetry: async (r) => w.telemetry.push(r), random: () => 0.5, ...extra });
 const builders = (w) => w.calls.filter((c) => c[0] === "runner" && c[1] === "builder");
 const reviewers = (w) => w.calls.filter((c) => c[0] === "runner" && c[1] === "reviewer");
-const registers = (w) => w.comments.filter((c) => c.startsWith("<!-- FORGE:WORK-ON -->"));
+const traj = (w) => w.comments.filter((c) => c.includes("<!-- FORGE:TRAJECTORY -->"));
+const markerOf = (c) => /<!-- (FORGE:[A-Z_-]+) -->/.exec(c)[1];
 
 describe("core work-on", () => {
-  it("happy path: started comment, one register comment with everything, merge at the reviewed head", async () => {
+  it("happy path: investigation, plan, implementation, review, trajectory in order; merge at the reviewed head", async () => {
     const w = world();
     const dir = tmpDir("core-");
     const r = await run(w, { dir });
     assert.equal(r.terminalReason, "merged");
     assert.equal(r.pr, 77);
-    assert.match(w.comments[0], /FORGE:STARTED/);
-    const reg = registers(w);
-    assert.equal(reg.length, 1);
-    for (const needle of ["fixed foo", "src/foo.js", "test/foo.test.js", "PASS", "src/foo.js:3 fixed", "https://github.com/o/r/pull/77", "cost $0.15", "tokens 14 in / 7 out / 100 cache", "wall"]) {
-      assert.ok(reg[0].includes(needle), `register comment lacks ${needle}:\n${reg[0]}`);
+    assert.deepEqual(w.comments.map(markerOf), ["FORGE:STARTED", "FORGE:INVESTIGATION", "FORGE:PLAN", "FORGE:IMPLEMENTATION", "FORGE:REVIEW", "FORGE:TRAJECTORY"]);
+    assert.match(w.comments[1], /<!-- FORGE:VALIDATE -->/, "VALIDATE stays as an alias marker");
+    assert.match(w.comments[1], /^<!-- FORGE:INVESTIGATION -->\n<!-- FORGE:VALIDATE -->\n## Investigation Report\n\*\*Verdict\*\*: CONFIRMED/);
+    assert.match(w.comments[2], /## Implementation Plan\n### Approach/);
+    assert.match(w.comments[3], /## Implementation Complete\n\*\*Branch:\*\* `feat\/issue-7-lean`\n\*\*Files changed:\*\*\n- `src\/foo.js`\n- `test\/foo.test.js`/);
+    assert.match(w.comments[4], /## Review\n\*\*Verdict:\*\* PASS/);
+    assert.match(w.comments[4], /Fixes the issue:\*\* yes \(src\/foo.js:3 fixed\)/);
+    const t = traj(w);
+    assert.equal(t.length, 1);
+    assert.match(t[0], /<!-- FORGE:TRAJECTORY -->\n<!-- FORGE:WORK-ON -->\n## Pipeline Trajectory — #7/);
+    for (const needle of ["| Validate | CONFIRMED |", "| Plan | posted |", "| Implement |", "| Review | PASS |", "| PR | #77 |", "| Merge |", "| Close | issue closed (completed) |", "**Decisions**", "**Anomalies**", "cost $0.1500", "tokens 14 in / 7 out / 100 cache", "wall"]) {
+      assert.ok(t[0].includes(needle), `trajectory lacks ${needle}:\n${t[0]}`);
     }
-    assert.match(w.prs[0][w.prs[0].indexOf("--body") + 1], /Closes #7/);
+    const body = w.prs[0][w.prs[0].indexOf("--body") + 1];
+    assert.match(body, /## Root cause\nfoo derefs null at src\/foo.js:3/);
+    assert.match(body, /## Deliverables\n\| File \| Change \| Why \|/);
+    assert.match(body, /## Verification\n- node --test/);
+    assert.match(body, /Closes #7$/);
     assert.deepEqual(w.merges[0].slice(-2), ["--match-head-commit", w.head]);
     assert.equal(w.closed.length, 1);
     assert.equal(builders(w).length, 1);
@@ -92,22 +133,14 @@ describe("core work-on", () => {
     assert.equal(ev[0], "RUN_START"); assert.equal(ev.at(-1), "RUN_TERMINAL");
   });
 
-  it("validation comment is posted before the reviewer and the in-review label; content for a fixed issue; register links it", async () => {
-    const w = world({ result: { status: "fixed", summary: "fixed foo\nmore", evidence: ["src/foo.js:3 null deref"], tests: ["t"] } });
+  it("investigation and plan comments are posted before the reviewer runs and before the in-review label", async () => {
+    const w = world();
     await run(w);
-    const vi = w.comments.findIndex((c) => c.startsWith("<!-- FORGE:VALIDATE -->"));
-    assert.ok(vi >= 0);
-    const v = w.comments[vi];
-    assert.match(v, /Verdict:\*\* valid/);
-    assert.match(v, /src\/foo.js:3 null deref/);
-    assert.match(v, /Summary:\*\* fixed foo$/);
-    assert.ok(!v.includes("more"));
-    const pos = (x) => w.seq.indexOf(x);
-    const commentSeq = w.seq.map((s, i) => (s === "comment" ? i : -1)).filter((i) => i >= 0);
-    assert.ok(commentSeq[vi] > pos("builder") && commentSeq[vi] < pos("reviewer"));
-    assert.ok(commentSeq[vi] < pos("label:in-review"));
-    assert.match(registers(w)[0], /Validation: https:\/\/github.com\/o\/r\/issues\/7#issuecomment-\d+/);
-    assert.equal(w.comments.filter((c) => c.includes("FORGE:VALIDATE")).length, 1);
+    const idx = []; w.seq.forEach((x, i) => { if (x === "comment") idx.push(i); });
+    const rv = w.seq.indexOf("reviewer");
+    assert.ok(idx[1] < rv && idx[2] < rv && idx[3] < rv, "investigation, plan, implementation precede the reviewer");
+    assert.ok(idx[3] < w.seq.indexOf("label:in-review"));
+    assert.ok(idx[4] > rv, "review comment follows the reviewer");
   });
 
   it("labels transition in order, and register is posted after the PR and before the merge", async () => {
@@ -116,7 +149,7 @@ describe("core work-on", () => {
     assert.deepEqual(w.labels, ["investigating", "building", "in-review", "merged"]);
     const order = w.seq.filter((s) => ["label:investigating", "label:building", "builder", "label:in-review", "reviewer", "push", "pr", "merge", "label:merged"].includes(s));
     assert.deepEqual(order, ["label:investigating", "label:building", "builder", "label:in-review", "reviewer", "push", "pr", "merge", "label:merged"]);
-    assert.ok(w.seq.indexOf("pr") < w.seq.lastIndexOf("comment") && w.seq.lastIndexOf("comment") < w.seq.indexOf("merge"));
+    assert.ok(w.seq.lastIndexOf("comment") > w.seq.indexOf("merge"), "the trajectory is posted last");
   });
 
   it("emits phase_attempt for builder and reviewer plus run_terminal, stats-compatible", async () => {
@@ -129,17 +162,17 @@ describe("core work-on", () => {
     assert.equal(mapped.at(-1).payload.reason, "merged");
   });
 
-  it("invalid with evidence closes the issue as invalid and opens no PR", async () => {
-    const w = world({ changed: [], result: { status: "invalid", summary: "not a bug", evidence: ["src/foo.js:3 already guards null"], tests: [] } });
+  it("invalid with evidence: the investigation is the evidence comment, closes, trajectory rows", async () => {
+    const w = world({ changed: [], stages: { investigation: "**Verdict**: INVALID\n**Confidence**: high\n\n### What We Found\n- src/foo.js:3 already guards null\n\n### Root Cause\nnone, not a bug" },
+      result: { status: "invalid", summary: "not a bug", evidence: ["src/foo.js:3 already guards null"], tests: [] } });
     const r = await run(w);
     assert.equal(r.terminalReason, "invalid");
     assert.deepEqual(w.labels, ["investigating", "building", "invalid"]);
-    const vs = w.comments.filter((c) => c.startsWith("<!-- FORGE:VALIDATE -->"));
-    assert.equal(vs.length, 1, "the validation comment is the evidence comment");
-    assert.match(vs[0], /Verdict:\*\* invalid/);
-    assert.match(vs[0], /src\/foo.js:3 already guards null/);
-    assert.match(vs[0], /Summary:\*\* not a bug/);
-    assert.equal(registers(w).length, 0, "no duplicate evidence comment");
+    assert.deepEqual(w.comments.map(markerOf), ["FORGE:STARTED", "FORGE:INVESTIGATION", "FORGE:TRAJECTORY"]);
+    assert.match(w.comments[1], /Verdict\*\*: INVALID/);
+    assert.match(w.comments[1], /src\/foo.js:3 already guards null/);
+    const t = traj(w)[0];
+    for (const needle of ["| Validate | INVALID |", "| Plan | skipped |", "| Implement | skipped |", "| Review | skipped |", "| PR | none |", "| Close | issue closed (not planned) |"]) assert.ok(t.includes(needle), needle);
     assert.equal(w.closed.length, 1);
     assert.equal(w.prs.length, 0);
     assert.equal(reviewers(w).length, 0);
@@ -157,6 +190,10 @@ describe("core work-on", () => {
     assert.equal(w.closed.length, 0);
     assert.ok(w.edits.some((e) => e.includes("needs-human")));
     assert.ok(w.comments.some((c) => c.includes("FORGE:NEEDS_HUMAN") && c.includes("without evidence")));
+    const t = traj(w)[0];
+    assert.match(t, /\| Close \| left open \| label needs-human \|/);
+    assert.match(t, /\*\*Anomalies\*\*\n- needs-human: Builder reported "invalid" without evidence/);
+    assert.match(t, /\| Plan \| not reached \|/);
   });
 
   it("review FAIL -> builder resumed via --resume with the reason -> re-review PASS -> merge", async () => {
@@ -169,7 +206,9 @@ describe("core work-on", () => {
     assert.match(b[1][4], /src\/foo.js:9 still wrong/);
     assert.equal(reviewers(w).length, 2);
     assert.equal(w.prs.length, 1);
-    assert.equal(registers(w).length, 1);
+    assert.equal(traj(w).length, 1);
+    assert.match(traj(w)[0], /2 rounds/);
+    assert.match(traj(w)[0], /Review FAIL \(round 1\)/);
     assert.deepEqual(w.merges[0].slice(-2), ["--match-head-commit", w.head]);
   });
 
@@ -194,6 +233,15 @@ describe("core work-on", () => {
     assert.equal((await run(world({ changed: [] }))).terminalReason, "needs-human");
   });
 
+  it("worktree add retries a concurrent .git lock collision, then gives up after 5 tries", async () => {
+    const w = world(); w.lockFails = 2;
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.equal(w.calls.filter((c) => c[1] === "worktree" && c[2] === "add").length, 3);
+    const w2 = world(); w2.lockFails = 99;
+    assert.notEqual((await run(w2)).terminalReason, "merged");
+    assert.equal(w2.calls.filter((c) => c[1] === "worktree" && c[2] === "add").length, 5);
+  });
+
   it("needs-human terminals carry a specific outcome code, never unclassified", async () => {
     const code = async (w, extra) => {
       const dir = tmpDir("lean-code-");
@@ -260,54 +308,131 @@ describe("core work-on", () => {
 });
 
 describe("comment templates", () => {
-  const full = { status: "fixed", summary: "fixed foo", evidence: ["src/foo.js:3 null deref"], root_cause: "foo derefs null at src/foo.js:3",
-    approach: "guard null", sibling_sites_checked: ["src/bar.js:8: same guard added"], changes: [{ file: "src/foo.js", change: "add guard", why: "avoid crash" }],
-    tests: [{ command: "node --test test/foo.test.js", result: "pass", fails_without_fix: true }], risks: ["none"], follow_ups: ["audit baz"] };
-  const rv = { verdict: "PASS", fixes_issue: true, regression: false, reason: "src/foo.js:3 ok", checked: "callers of foo" };
-
-  it("renders full fields", () => {
-    const v = renderValidate(full, "valid"); const p = renderPlan(full, ["src/foo.js"]);
-    assert.match(v, /Root cause:\*\* foo derefs null at src\/foo.js:3/);
-    assert.match(p, /Approach:\*\* guard null/); assert.match(p, /src\/bar.js:8: same guard added/); assert.match(p, /node --test test\/foo.test.js/);
-    assert.match(renderReview(rv), /Checked:\*\* callers of foo/);
-    const reg = renderRegister({ result: full, gitFiles: [], review: rv, links: { validate: "V", plan: "P", review: "R" }, prUrl: "PRURL", usage: "cost $1", policy: "required" });
-    for (const n of ["| src/foo.js | add guard | avoid crash |", "fails without fix: yes", "Risks:** none", "Follow-ups:** audit baz", "Validation: V", "Plan: P", "Review: R", "PR: PRURL", "Merge policy:** required", "cost $1"]) assert.ok(reg.includes(n), n);
-    const pr = renderPrBody({ issue: 7, result: full });
-    assert.match(pr, /^Closes #7/); assert.match(pr, /\| file \| change \| why \|/); assert.match(pr, /node --test/);
-  });
-
-  it("missing fields render as 'not reported', never broken markdown", () => {
-    const reg = renderRegister({ result: {}, gitFiles: ["a.js"], review: { ...rv, checked: undefined }, links: {}, prUrl: "U", usage: "u", policy: "none" });
-    assert.ok(reg.includes(NR));
-    assert.match(reg, /\| a.js \| not reported \| not reported \|/);
-    assert.match(reg, /Verification\*\*\nnot reported/);
-    assert.doesNotMatch(reg, /undefined|null|\[object/);
-    assert.doesNotMatch(renderValidate(null, "blocked"), /undefined|null/);
-    assert.doesNotMatch(renderPlan(undefined), /undefined/);
-    assert.doesNotMatch(renderReview({ verdict: "PASS", fixes_issue: true, regression: false }), /undefined/);
-  });
-
-  it("escapes pipes and newlines in table cells", () => {
+  const rv = { verdict: "PASS", fixes_issue: true, regression: false, reason: "src/foo.js:3 ok", evidence: "src/foo.js:3 guard", checked: "callers of foo, test/foo.test.js" };
+  const result = { status: "fixed", summary: "fixed foo", evidence: ["src/foo.js:3 null deref"], root_cause: "derefs null at src/foo.js:3", changes: [{ file: "src/foo.js", change: "add guard", why: "avoid crash" }],
+    tests: [{ command: "node --test test/foo.test.js", result: "pass", fails_without_fix: true }], risks: ["none"], follow_ups: ["audit baz"], approach: "guard null" };
+
+  it("renders builder-written files under the fixed headings", () => {
+    assert.match(renderInvestigation(STAGE_MD.investigation, null), /^## Investigation Report\n\*\*Verdict\*\*: CONFIRMED/);
+    assert.match(renderPlan(STAGE_MD.plan, null), /^## Implementation Plan\n### Approach/);
+    const im = renderImplementation(STAGE_MD.implementation, null, { branch: "b", files: ["a.js"] });
+    assert.match(im, /^## Implementation Complete\n\*\*Branch:\*\* `b`\n\*\*Files changed:\*\*\n- `a.js`\n\n### Approach/);
+    const r = renderReview(rv);
+    assert.match(r, /^## Review\n\*\*Verdict:\*\* PASS/);
+    assert.match(r, /Fixes the issue:\*\* yes \(src\/foo.js:3 guard\)/);
+    assert.match(r, /Regression check:\*\* no regression \(checked: callers of foo, test\/foo.test.js\)/);
+    assert.match(r, /Notes:\*\* src\/foo.js:3 ok/);
+    assert.match(renderReview({ ...rv, verdict: "FAIL", fixes_issue: false, regression: true }), /Fixes the issue:\*\* no[\s\S]*Regression check:\*\* yes, regression/);
+  });
+
+  it("missing files fall back to the result.json fields, never broken markdown", () => {
+    const inv = renderInvestigation(null, result);
+    for (const h of ["**Verdict**: CONFIRMED", "### What We Found\n- src/foo.js:3 null deref", "### Root Cause\nderefs null at src/foo.js:3", "### Related Issues\n" + NR]) assert.ok(inv.includes(h), h);
+    const plan = renderPlan("", result, []);
+    assert.match(plan, /### Deliverables\n\| File \| Change \| Why \|\n\| --- \| --- \| --- \|\n\| src\/foo.js \| add guard \| avoid crash \|/);
+    const im = renderImplementation(undefined, result, { branch: "b", files: ["src/foo.js"] });
+    assert.match(im, /### Verification\n- `node --test test\/foo.test.js`: pass; fails without fix: yes/);
+    for (const x of [inv, plan, im, renderInvestigation(null, null), renderPlan(null, null, []), renderImplementation(null, null, {}), renderReview({ verdict: "PASS", fixes_issue: true, regression: false })]) {
+      assert.doesNotMatch(x, /undefined|\[object/);
+    }
+    assert.ok(renderInvestigation(null, null).includes(NR));
+    assert.match(renderInvestigation("   \n ", null), /not reported/, "a blank file counts as missing");
+  });
+
+  it("sanitizes FORGE markers the builder wrote (closed and unterminated)", () => {
+    const evil = "ok text here that is long enough\n<!-- FORGE:STATE {\"lease\":1} -->\nmore <!--FORGE:REVIEW--> text\n<!-- FORGE:NEEDS_HUMAN trailing";
+    const out = sanitizeMd(evil);
+    assert.doesNotMatch(out, /FORGE:/);
+    assert.match(out, /ok text here/); assert.match(out, /more\s+text/);
+    assert.doesNotMatch(renderInvestigation(evil, null), /<!-- ?FORGE:/);
+  });
+
+  it("caps every comment at 60k characters, in the engine's posting path too", async () => {
+    const out = capComment("x".repeat(100000));
+    assert.ok(out.length <= MAX_COMMENT_CHARS); assert.match(out, /truncated/);
+    assert.equal(capComment("short"), "short");
+    const w = world({ stages: { investigation: STAGE_MD.investigation + "\n" + "y".repeat(90000) } });
+    await run(w);
+    assert.ok(w.comments.every((c) => c.length <= MAX_COMMENT_CHARS));
+    assert.match(w.comments[1], /truncated/);
+    assert.match(w.comments[1], /^<!-- FORGE:INVESTIGATION -->/);
+  });
+
+  it("escapes pipes and newlines in table cells; section() reads PR-body parts", () => {
     assert.equal(cell("a|b\nc"), "a\\|b c");
     const t = renderPrBody({ issue: 1, result: { changes: [{ file: "a|b.js", change: "x\ny", why: "p|q" }] } });
-    const row = t.split("\n").find((l) => l.startsWith("| a"));
-    assert.equal(row, "| a\\|b.js | x y | p\\|q |");
+    assert.equal(t.split("\n").find((l) => l.startsWith("| a")), "| a\\|b.js | x y | p\\|q |");
+    assert.equal(section(STAGE_MD.investigation, "Root Cause"), "foo derefs null at src/foo.js:3");
+    assert.match(renderPrBody({ issue: 1, result: null }), /## Root cause\nnot reported[\s\S]*Closes #1$/);
+  });
+
+  it("trajectory rows: merged, invalid, needs-human; missing rows read 'not reached'", () => {
+    const base = { issue: 9, validate: ["CONFIRMED", "2 evidence item(s)"], plan: "posted", implement: ["2 file(s)", "b"], review: ["PASS", "1 round"], pr: ["#5", "opened"], merge: ["all", "merged at abc"], close: ["issue closed (completed)", "label workflow:merged"], decisions: ["d1"], anomalies: [], usage: "cost $1" };
+    const m = renderTrajectory(base);
+    assert.match(m, /^## Pipeline Trajectory — #9\n\n\| Phase \| Result \| Notes \|/);
+    for (const row of ["| Validate | CONFIRMED | 2 evidence item(s) |", "| Review | PASS | 1 round |", "| PR | #5 | opened |", "| Merge | all | merged at abc |", "| Close | issue closed (completed) | label workflow:merged |", "- d1", "- none", "_cost $1_"]) assert.ok(m.includes(row), row);
+    const nh = renderTrajectory({ issue: 9, validate: "CONFIRMED", anomalies: ["needs-human: Review FAIL twice"], close: ["left open", "label needs-human"] });
+    assert.match(nh, /\| Implement \| not reached \| - \|/);
+    assert.match(nh, /\*\*Anomalies\*\*\n- needs-human: Review FAIL twice/);
+    assert.match(renderTrajectory({ issue: 9, validate: ["a|b", "x\ny"] }), /\| Validate \| a\\\|b \| x y \|/);
   });
 
-  it("posts VALIDATE, PLAN, REVIEW, WORK-ON in order; VALIDATE and PLAN before the reviewer", async () => {
-    const w = world({ result: full });
+  it("a merged run's trajectory and a needs-human run's trajectory carry the right rows", async () => {
+    const w = world({ reviews: [bad(), bad("still bad")] });
     await run(w);
-    const m = w.comments.map((c) => /FORGE:[A-Z_-]+/.exec(c)[0]);
-    assert.deepEqual(m, ["FORGE:STARTED", "FORGE:VALIDATE", "FORGE:PLAN", "FORGE:REVIEW", "FORGE:WORK-ON"]);
-    const idx = []; w.seq.forEach((s, i) => { if (s === "comment") idx.push(i); });
-    assert.ok(idx[1] < w.seq.indexOf("reviewer") && idx[2] < w.seq.indexOf("reviewer") && idx[3] > w.seq.indexOf("reviewer"));
-    const pr = w.prs[0][w.prs[0].indexOf("--body") + 1];
-    assert.match(pr, /Root cause/); assert.match(pr, /\| src\/foo.js \| add guard \| avoid crash \|/);
+    const t = traj(w)[0];
+    assert.match(t, /\| Validate \| CONFIRMED \|/);
+    assert.match(t, /\| Plan \| posted \|/);
+    assert.match(t, /\| Review \| not reached \|/);
+    assert.match(t, /\| Close \| left open \| label needs-human \|/);
+    assert.match(t, /Review FAIL twice/);
   });
 
-  it("builder prompt with the structured fields stays within 1.2k tokens", () => {
-    assert.ok(approxTokens(builderPrompt(7)) <= 1200);
-    assert.match(builderPrompt(7), /root_cause/); assert.match(builderPrompt(7), /sibling_sites_checked/);
+  it("missing stage files in a real run are rendered from result.json and noted as anomalies", async () => {
+    const w = world({ noStages: true, result: { status: "fixed", summary: "fixed foo", evidence: ["src/foo.js:3 x"], root_cause: "bad at src/foo.js:3", changes: [{ file: "src/foo.js", change: "guard", why: "w" }], tests: [{ command: "t", result: "pass", fails_without_fix: false }] } });
+    await run(w);
+    assert.deepEqual(w.comments.map(markerOf), ["FORGE:STARTED", "FORGE:INVESTIGATION", "FORGE:PLAN", "FORGE:IMPLEMENTATION", "FORGE:REVIEW", "FORGE:TRAJECTORY"]);
+    assert.match(w.comments[1], /Root Cause\nbad at src\/foo.js:3/);
+    assert.match(w.comments[3], /fails without fix: no/);
+    assert.match(traj(w)[0], /investigation.md missing or empty: rendered from result.json/);
+    for (const c of w.comments) assert.doesNotMatch(c, /undefined|\[object/);
+  });
+
+  it("live posting: stage notes appear while the builder session is still running", async () => {
+    const w = world({ live: async (wd, put) => {
+      const until = async (marker) => { for (let i = 0; i < 300 && !wd.comments.some((c) => c.includes(`<!-- ${marker} -->`)); i++) await new Promise((r) => setTimeout(r, 10)); return wd.comments.map(markerOf); };
+      wd.liveSeen = {};
+      put("investigation.md", STAGE_MD.investigation); wd.liveSeen.afterInvestigation = await until("FORGE:INVESTIGATION");
+      put("plan.md", STAGE_MD.plan); wd.liveSeen.afterPlan = await until("FORGE:PLAN");
+      put("implementation.md", STAGE_MD.implementation); wd.liveSeen.afterImplementation = await until("FORGE:IMPLEMENTATION");
+    } });
+    const r = await run(w, { livePollMs: 10, stableMs: 30 });
+    assert.equal(r.terminalReason, "merged");
+    assert.ok(w.liveSeen.afterInvestigation.includes("FORGE:INVESTIGATION"), "investigation posted before the session ended");
+    assert.ok(w.liveSeen.afterPlan.includes("FORGE:PLAN"));
+    assert.ok(w.liveSeen.afterImplementation.includes("FORGE:IMPLEMENTATION"));
+    assert.deepEqual(w.comments.map(markerOf), ["FORGE:STARTED", "FORGE:INVESTIGATION", "FORGE:PLAN", "FORGE:IMPLEMENTATION", "FORGE:REVIEW", "FORGE:TRAJECTORY"], "each posted exactly once, in order");
+  });
+
+  it("a file still being written is not posted until its mtime is stable", async () => {
+    let seenEarly = null;
+    const w = world({ live: async (wd, put) => {
+      const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+      for (let i = 0; i < 6; i++) { put("investigation.md", STAGE_MD.investigation + "\n".repeat(i)); await sleepMs(15); }
+      seenEarly = wd.comments.map(markerOf);
+      await sleepMs(900);
+    } });
+    await run(w, { livePollMs: 10, stableMs: 400 });
+    assert.ok(!seenEarly.includes("FORGE:INVESTIGATION"), "not posted while the file keeps changing");
+    assert.equal(w.comments.filter((c) => c.includes("FORGE:INVESTIGATION")).length, 1);
+  });
+
+  it("builder prompt (three stage templates) stays within 2.5k tokens", () => {
+    const p = builderPrompt(7);
+    assert.ok(approxTokens(p) <= 2500, `builder prompt is ${approxTokens(p)} tokens`);
+    for (const h of ["### What Was Claimed", "### What We Found", "### Root Cause", "### Affected Files", "### Sibling Sweep", "### History", "### Recommendation", "### Related Issues",
+      "### Approach", "### Deliverables", "### Acceptance Criteria", "### Implementation Order", "### Out of Scope", "### Risk Assessment", "### Changes", "### Acceptance Criteria Status", "### Verification", "### Notes",
+      "investigation.md", "plan.md", "implementation.md", "result.json", "BEFORE coding", "BEFORE editing code"]) assert.ok(p.includes(h), h);
   });
 });
 
@@ -319,7 +444,7 @@ describe("merge_wait policy", () => {
     w.io.waitCiGreen = async () => { polled++; return { rc: 2, text: "" }; };
     const r = await run(w);
     assert.equal(r.terminalReason, "merged"); assert.equal(polled, 0);
-    assert.match(registers(w)[0], /Merge policy:\*\* required \(no required checks/);
+    assert.match(traj(w)[0], /\| Merge \| required \(no required checks: merged right after review\) \|/);
   });
   it("required with a pending required check waits (backoff) then merges", async () => {
     const w = world(); const seqs = [states({ build: "pending" }), states({ build: "pending" }), states({ build: "success", other: "failure" })]; let sleeps = 0;
@@ -327,7 +452,7 @@ describe("merge_wait policy", () => {
     const s = w.io.sleep; w.io.sleep = async (ms) => { sleeps++; return s(ms); };
     const r = await run(w);
     assert.equal(r.terminalReason, "merged"); assert.equal(sleeps, 2);
-    assert.match(registers(w)[0], /required \(build\)/);
+    assert.match(traj(w)[0], /\| Merge \| required \(build\) \|/);
     assert.deepEqual(w.merges[0].slice(-2), ["--match-head-commit", w.head]);
   });
   it("required with a failing required check is needs-human; slow required check is ci-pending", async () => {
@@ -340,7 +465,7 @@ describe("merge_wait policy", () => {
     const w = world({ waits: [{ rc: 2, text: "" }] }); let req = 0; w.io.requiredChecks = async () => { req++; return []; };
     assert.equal((await run(w, { mergeWait: "all" })).terminalReason, "merged");
     assert.equal(w.waits.length, 0); assert.equal(req, 0);
-    assert.match(registers(w)[0], /Merge policy:\*\* all/);
+    assert.match(traj(w)[0], /\| Merge \| all \|/);
     const w2 = world({ waits: [{ rc: 1, text: "red" }] });
     assert.equal((await run(w2, { mergeWait: "none" })).terminalReason, "merged");
     assert.equal(w2.waits.length, 1); assert.deepEqual(w2.merges[0].slice(-2), ["--match-head-commit", w2.head]);
@@ -348,9 +473,8 @@ describe("merge_wait policy", () => {
 });
 
 describe("prompts", () => {
-  it("builder prompt is at most 1k tokens and short and plain", () => {
+  it("builder prompt keeps the short developer opening and the no-push rule", () => {
     const p = builderPrompt(7);
-    assert.ok(approxTokens(p) <= 1000);
     assert.match(p, /Resolve issue #7 \(read it with gh issue view 7 --comments\)/);
     assert.match(p, /Do not push or touch GitHub/);
     assert.match(p, /result\.json/);
@@ -373,6 +497,7 @@ describe("prompts", () => {
   });
 
   it("parseVerdict: flags decide, garbage is null", () => {
+    assert.equal(parseVerdict(ok({ evidence: "a.js:1", checked: "c" })).evidence, "a.js:1");
     assert.equal(parseVerdict(ok()).fail, false);
     assert.equal(parseVerdict(ok({ regression: true })).fail, true);
     assert.equal(parseVerdict(bad()).fail, true);
@@ -497,3 +622,286 @@ describe("orchestrate", () => {
     await assert.rejects(orchestrateFromCli([], {}), /usage/);
   });
 });
+
+describe("runCliBackendAsync", () => {
+  it("returns the same envelope as runCliBackend, without blocking the event loop", async () => {
+    const { writeFileSync, chmodSync } = await import("node:fs");
+    const { runCliBackend, runCliBackendAsync } = await import("../runner.mjs");
+    const d = tmpDir("core-async-");
+    const bin = `${d}/fake-claude`;
+    writeFileSync(bin, '#!/bin/sh\nsleep 0.3\necho \'{"result":"hello","session_id":"s-1","total_cost_usd":0.25,"num_turns":2,"duration_ms":300,"usage":{"input_tokens":3,"output_tokens":4}}\'\n');
+    chmodSync(bin, 0o755);
+    const base = { spec: { name: "t" }, userMessage: "go", systemPrompt: "sys", args: ["1"], cwd: d, bin, logger: { log() {} } };
+    let ticks = 0; const iv = setInterval(() => { ticks++; }, 20);
+    const a = await runCliBackendAsync(base);
+    clearInterval(iv);
+    const s = runCliBackend(base);
+    assert.ok(ticks >= 5, `event loop kept turning (${ticks} ticks)`);
+    assert.deepEqual({ ...a, durationMs: 0 }, { ...s, durationMs: 0 });
+    assert.equal(a.sessionId, "s-1"); assert.equal(a.text, "hello"); assert.equal(a.costUsd, 0.25);
+  });
+
+  it("surfaces a failing CLI as the same CLI_BACKEND_FAILED error", async () => {
+    const { writeFileSync, chmodSync } = await import("node:fs");
+    const { runCliBackendAsync } = await import("../runner.mjs");
+    const d = tmpDir("core-async-");
+    writeFileSync(`${d}/bad`, "#!/bin/sh\necho boom >&2\nexit 3\n"); chmodSync(`${d}/bad`, 0o755);
+    await assert.rejects(runCliBackendAsync({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: d, bin: `${d}/bad`, logger: { log() {} } }), (e) => e.code === "CLI_BACKEND_FAILED" && /boom/.test(e.message));
+  });
+});
+
+describe("base-sync (#4100)", () => {
+  const CONFLICTING = { mergeable: "CONFLICTING", mergeStateStatus: "DIRTY" };
+  const OKSTATE = { mergeable: "MERGEABLE", mergeStateStatus: "CLEAN" };
+  const gitCalls = (w) => w.calls.filter((c) => c[0] === "git").map((c) => c.slice(1));
+  const noRebaseNoForce = (w) => {
+    for (const g of gitCalls(w)) {
+      assert.notEqual(g[0], "rebase");
+      if (g[0] === "push") assert.ok(!g.some((x) => /^(--force|-f$|\+)/.test(x)), `force push: ${g.join(" ")}`);
+    }
+  };
+  const syncComment = (w) => w.comments.find((c) => c.includes("<!-- FORGE:BASE_SYNC -->"));
+
+  it("conflicting PR, clean merge: fetch, merge, push, merge the PR at the new head; no re-review", async () => {
+    const w = world({ prView: [CONFLICTING, OKSTATE], mergeResults: ["clean"] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(reviewers(w).length, 1, "no re-review for a conflict-free base merge");
+    assert.equal(builders(w).length, 1);
+    const g = gitCalls(w);
+    assert.ok(g.some((x) => x[0] === "fetch" && x[1] === "origin" && x[2] === "staging"));
+    assert.ok(g.some((x) => x[0] === "merge" && x[1] === "--no-edit" && x[2] === "origin/staging"));
+    assert.equal(g.filter((x) => x[0] === "push").length, 2, "initial push plus the sync push");
+    assert.match(syncComment(w), /## Base Sync[\s\S]*clean merge[\s\S]*not required \(conflict-free base merge\)/);
+    assert.deepEqual(w.merges[0].slice(-2), ["--match-head-commit", w.head]);
+    assert.match(traj(w)[0], /\| Base Sync \| 1 sync\(s\) \|/);
+    noRebaseNoForce(w);
+  });
+
+  it("no conflict: no Base Sync row detail and no sync comment", async () => {
+    const w = world();
+    await run(w);
+    assert.ok(!syncComment(w));
+    assert.match(traj(w)[0], /\| Base Sync \| not needed \| - \|/);
+  });
+
+  it("conflicting PR, real conflict: builder resumed with the files, reviewer PASS on the full diff, merge", async () => {
+    const w = world({ prView: [CONFLICTING, OKSTATE], mergeResults: ["conflict"], reviews: [ok(), ok()] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    const b = builders(w);
+    assert.equal(b.length, 2);
+    assert.equal(b[1][2], "sess-1", "same session resumed");
+    assert.match(b[1][4], /Merging origin\/staging into this branch conflicts in: src\/foo\.js\. Resolve the conflicts preserving both this fix's intent and the base's changes, run the relevant tests, and commit the merge\. Do not push\./);
+    assert.equal(reviewers(w).length, 2, "re-review after the conflict resolution");
+    assert.match(syncComment(w), /conflicts in `src\/foo\.js`[\s\S]*builder resolved 1 conflicted file[\s\S]*Re-review:\*\* PASS/);
+    assert.equal(w.merges.length, 1);
+    assert.deepEqual(w.merges[0].slice(-2), ["--match-head-commit", w.head]);
+    noRebaseNoForce(w);
+  });
+
+  it("conflict resolution that the re-review FAILs gets one retry then merges on PASS", async () => {
+    const w = world({ prView: [CONFLICTING, OKSTATE], mergeResults: ["conflict"], reviews: [ok(), bad("src/foo.js:4 lost base change"), ok()] });
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.equal(reviewers(w).length, 3);
+    assert.equal(builders(w).length, 3);
+  });
+
+  it("still conflicting after 2 base-syncs ends needs-human with base.conflict, never engine-error", async () => {
+    const w = world({ prView: [CONFLICTING], mergeResults: ["clean", "clean", "clean"] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "needs-human");
+    assert.equal(r.code, "base.conflict");
+    assert.equal(gitCalls(w).filter((x) => x[0] === "merge" && x[1] === "--no-edit").length, 2, "at most 2 base-syncs");
+    assert.equal(w.merges.length, 0);
+    assert.ok(w.edits.some((e) => e.includes("needs-human")));
+  });
+
+  it("unresolved conflict markers after the builder ends needs-human with base.conflict", async () => {
+    const w = world({ prView: [CONFLICTING], mergeResults: ["conflict"] });
+    w.markers = true;
+    const r = await run(w);
+    assert.equal(r.terminalReason, "needs-human"); assert.equal(r.code, "base.conflict");
+    assert.equal(w.merges.length, 0);
+    assert.ok(gitCalls(w).some((x) => x[0] === "merge" && x[1] === "--abort"));
+  });
+
+  it("a gh pr merge conflict error triggers base-sync, then the merge is retried", async () => {
+    const w = world({ prView: [OKSTATE], mergeErrors: ["GraphQL: Pull request is not mergeable (mergePullRequest)"], mergeResults: ["clean"] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(w.mergeAttempts, 2);
+    assert.match(syncComment(w), /gh pr merge reported a conflict/);
+    noRebaseNoForce(w);
+  });
+
+  it("an unrelated gh pr merge error is not a base-sync", async () => {
+    const w = world({ mergeErrors: ["HTTP 500 boom"] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "engine-error");
+    assert.ok(!syncComment(w));
+  });
+
+  it("a resumed run with a conflicting PR syncs (fresh builder when the conflict needs resolving)", async () => {
+    const w = world({ prList: [{ number: 77, headRefOid: "x" }], remote: "abc\trefs/heads/feat/issue-7-lean", prView: [CONFLICTING, OKSTATE], mergeResults: ["conflict"], reviews: [ok(), ok()] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    const b = builders(w);
+    assert.equal(b.length, 1);
+    assert.equal(b[0][2], null, "no session id on resume: a fresh builder");
+    assert.match(b[0][4], /Merging origin\/staging into this branch conflicts in: src\/foo\.js/);
+    assert.equal(w.prs.length, 0);
+    noRebaseNoForce(w);
+  });
+
+  it("UNKNOWN mergeability with nothing to merge is not treated as a conflict", async () => {
+    const w = world({ prView: [{ mergeable: "UNKNOWN", mergeStateStatus: "UNKNOWN" }, { mergeable: "UNKNOWN", mergeStateStatus: "UNKNOWN" }, OKSTATE], mergeResults: ["clean"] });
+    // a clean merge that changes head would count; here make the merge a no-op by pinning the head
+    const orig = w.io.git;
+    w.io.git = async (a, o2) => { const r = await orig(a, o2); if (a[0] === "merge" && a[1] === "--no-edit") w.head = "aaaa1111aaaa1111"; return r; };
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.ok(!syncComment(w));
+  });
+});
+
+describe("usage limit, lease takeover, worktree setup, run tmp (#4101-#4104)", () => {
+  const limitErr = (extra) => Object.assign(new Error("claude CLI exited with status 1. You've hit your session limit"), { code: "CLI_BACKEND_FAILED", usageLimit: true, ...extra });
+  const failFirstBuilder = (w, err, times = 1) => { const orig = w.io.runner; let n = 0; w.io.runner = async (c) => { if (c.role === "builder" && n++ < times) throw err; return orig(c); }; };
+  const projector = (w, lease) => { w.leaseWrites = []; w.io.projector = { readState: async () => (lease ? { v: 1, lease } : null), writeState: async (_i, st) => { w.leaseWrites.push(st); } }; };
+
+  it("#4101 a usage limit with a near reset pauses until the reset, then resumes the same step", async () => {
+    const w = world(); const sleeps = [];
+    const s0 = w.io.sleep; w.io.sleep = async (ms) => { sleeps.push(ms); return s0(ms); };
+    failFirstBuilder(w, limitErr({ resetAtEpochMs: 90000, resetAt: "8:30pm" }));
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.ok(sleeps.includes(90000), `slept until the reset: ${sleeps}`);
+    assert.equal(builders(w).length, 1);
+  });
+
+  it("#4101 a usage limit with a far reset ends deferred/rate_limited with the reset time, lease released, no needs-human", async () => {
+    const w = world(); projector(w, null);
+    failFirstBuilder(w, limitErr({ resetAtEpochMs: 3 * 3600 * 1000, resetAt: "8:30pm (Asia/Kolkata)" }));
+    const r = await run(w);
+    assert.equal(r.terminalReason, "deferred");
+    assert.equal(r.code, "rate_limited");
+    assert.match(r.detail, /resets at 8:30pm \(Asia\/Kolkata\)/);
+    assert.equal(w.edits.some((e) => e.includes("needs-human")), false);
+    assert.equal(traj(w).length, 0, "no trajectory comment for a deferral");
+    assert.equal(w.leaseWrites.at(-1).lease, null, "lease released");
+    assert.equal(w.merges.length, 0);
+  });
+
+  it("#4101 unknown reset pauses a bounded number of times, then defers", async () => {
+    const w = world(); let sleeps = 0;
+    const s0 = w.io.sleep; w.io.sleep = async (ms) => { sleeps++; return s0(ms); };
+    failFirstBuilder(w, limitErr(), 99);
+    const r = await run(w, { maxSessionLimitPauses: 2 });
+    assert.equal(r.terminalReason, "deferred"); assert.equal(r.code, "rate_limited");
+    assert.equal(sleeps, 2);
+    assert.match(r.detail, /resets at unknown/);
+  });
+
+  it("#4101 a non-limit runner error is still engine-error", async () => {
+    const w = world(); failFirstBuilder(w, new Error("boom"));
+    assert.equal((await run(w)).terminalReason, "engine-error");
+  });
+
+  it("#4102 a same-host holder whose pid is gone is taken over immediately; a live one or another host is not", async () => {
+    const future = Date.now() + 1e6;
+    const dead = Object.assign(new Error("no such process"), { code: "ESRCH" });
+    const w = world(); projector(w, { by: "core_4242", until: future, host: "h1", pid: 4242 });
+    const r = await run(w, { hostName: "h1", killFn: () => { throw dead; } });
+    assert.equal(r.terminalReason, "merged");
+    assert.ok(w.leaseWrites.some((x) => x.lease?.host === "h1" && Number.isSafeInteger(x.lease?.pid)), "lease records host and pid");
+    const w2 = world(); projector(w2, { by: "core_4242", until: 1e12, host: "h1", pid: 4242 });
+    assert.equal((await run(w2, { hostName: "h1", killFn: () => true })).terminalReason, "deferred");
+    const w3 = world(); projector(w3, { by: "core_4242", until: 1e12, host: "other-host", pid: 4242 });
+    assert.equal((await run(w3, { hostName: "h1", killFn: () => { throw dead; } })).terminalReason, "deferred");
+    assert.equal(builders(w3).length, 0);
+  });
+
+  it("#4103 a leftover unregistered worktree dir is removed (only this issue's lean dir) before add", async () => {
+    const w = world(); const removed = [];
+    w.io.fs.exists = async (p) => p === "/wt/lean-7"; w.io.fs.rmdir = async (p) => { removed.push(p); };
+    await run(w);
+    assert.deepEqual(removed, ["/wt/lean-7"]);
+    // a registered worktree dir is left to `git worktree remove`
+    const w2 = world(); const removed2 = [];
+    w2.io.fs.exists = async () => true; w2.io.fs.rmdir = async (p) => { removed2.push(p); };
+    const g = w2.io.git; w2.io.git = async (a, o2) => (a[0] === "worktree" && a[1] === "list" ? "worktree /wt/lean-7\nHEAD abc\n" : g(a, o2));
+    await run(w2);
+    assert.deepEqual(removed2, []);
+    // a worktree root that is not the lean root never deletes anything
+    const w3 = world(); const removed3 = [];
+    w3.io.fs.exists = async () => true; w3.io.fs.rmdir = async (p) => { removed3.push(p); };
+    await run(w3, { worktreeRoot: "/wt" , issue: 7 });
+    assert.ok(removed3.every((p) => p === "/wt/lean-7"));
+  });
+
+  it("#4103 'already exists' on add cleans the leftover and retries; index.lock and packed-refs.lock are retried", async () => {
+    for (const msg of ["fatal: '/wt/lean-7' already exists", "fatal: Unable to create '/r/.git/index.lock': File exists.", "error: cannot lock ref: Unable to create '/r/.git/packed-refs.lock': File exists", "fatal: could not lock config file /r/.git/config: File exists"]) {
+      const w = world(); let failed = false; const removed = [];
+      w.io.fs.exists = async (p) => failed && p === "/wt/lean-7"; w.io.fs.rmdir = async (p) => { removed.push(p); };
+      const g = w.io.git;
+      w.io.git = async (a, o2) => { if (a[0] === "worktree" && a[1] === "add" && !failed) { failed = true; throw Object.assign(new Error(msg), { stderr: msg }); } return g(a, o2); };
+      const r = await run(w);
+      assert.equal(r.terminalReason, "merged", msg);
+      if (/already exists/.test(msg)) assert.deepEqual(removed, ["/wt/lean-7"]);
+    }
+  });
+
+  it("#4104 the builder and reviewer run with a per-run TMPDIR that is removed on every terminal", async () => {
+    const mk = (w) => { w.tmpMade = []; w.tmpRemoved = []; w.io.runTmp = { prune: async () => { w.pruned = true; }, make: async (i, id) => { const d = `/home/x/.forge/tmp/runs/${id}`; w.tmpMade.push(d); return d; }, remove: async (d) => { w.tmpRemoved.push(d); } }; };
+    const cases = {
+      merged: (w) => w,
+      "needs-human": (w) => { w.reviews.push(bad(), bad()); return w; },
+      "engine-error": (w) => { failFirstBuilder(w, new Error("boom")); return w; },
+      deferred: (w) => { failFirstBuilder(w, limitErr({ resetAtEpochMs: 3 * 3600 * 1000 })); return w; },
+    };
+    for (const [reason, prep] of Object.entries(cases)) {
+      const w = world(); mk(w); prep(w);
+      const r = await run(w);
+      assert.equal(r.terminalReason, reason);
+      assert.equal(w.pruned, true);
+      assert.equal(w.tmpMade.length, 1);
+      assert.match(w.tmpMade[0], /\/\.forge\/tmp\/runs\/7-/);
+      assert.deepEqual(w.tmpRemoved, w.tmpMade, `${reason}: removed`);
+      for (const e of w.envs) assert.equal(e?.TMPDIR, w.tmpMade[0]);
+      if (["merged", "needs-human"].includes(reason)) assert.ok(w.envs.length >= 1);
+    }
+  });
+
+  it("#4104 makeRunTmp: removes only its own dirs; prune takes only old dirs with a dead owner and our marker", async () => {
+    const { mkdirSync, writeFileSync, existsSync, utimesSync } = await import("node:fs");
+    const root = tmpDir("core-runs-");
+    let t = 1_000_000_000_000;
+    const rt = makeRunTmp({ root, now: () => t, host: "h", alive: (pid) => pid === 111 });
+    const mine = await rt.make(7, "7-1");
+    assert.ok(existsSync(mine));
+    assert.equal(await rt.remove(mine), true); assert.ok(!existsSync(mine));
+    assert.equal(await rt.remove(`${root}/not-made`), false);
+    const outside = tmpDir("core-outside-"); writeFileSync(`${outside}/f`, "x");
+    assert.equal(await rt.remove(outside), false); assert.ok(existsSync(outside));
+    const own = (name, o2) => { mkdirSync(`${root}/${name}`); writeFileSync(`${root}/${name}/.forge-run-owner`, JSON.stringify({ host: "h", ...o2 })); };
+    own("old-dead", { pid: 999, created: t - 7 * 3600 * 1000 });
+    own("old-alive", { pid: 111, created: t - 7 * 3600 * 1000 });
+    own("fresh-dead", { pid: 999, created: t - 3600 * 1000 });
+    own("old-otherhost", { pid: 999, host: "zzz", created: t - 7 * 3600 * 1000 });
+    mkdirSync(`${root}/foreign`); writeFileSync(`${root}/foreign/data`, "not ours");
+    t += 1;
+    const removed = await rt.prune();
+    assert.deepEqual(removed.sort(), ["old-dead"]);
+    for (const keep of ["old-alive", "fresh-dead", "foreign"]) assert.ok(existsSync(`${root}/${keep}`), keep);
+  });
+
+  it("#4104 runCliBackend applies the per-run env to the child", async () => {
+    const { runCliBackend } = await import("../runner.mjs");
+    let seen;
+    runCliBackend({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: tmpDir("core-env-"), logger: { log() {} }, env: { TMPDIR: "/x/run-tmp", CLAUDE_CODE_TMPDIR: "/x/run-tmp" },
+      spawnFn: (_b, _a, o2) => { seen = o2.env; return { status: 0, stdout: "{}", stderr: "" }; } });
+    assert.equal(seen.TMPDIR, "/x/run-tmp"); assert.equal(seen.CLAUDE_CODE_TMPDIR, "/x/run-tmp");
+    assert.equal(seen.ANTHROPIC_API_KEY, undefined);
+  });
+});