forgedock 1.26.0 → 1.27.0

package/bin/lean/lean.test.mjs

@@ -3,15 +3,17 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { writeFileSync } from "node:fs";
-import { runCore, contractHash } from "./lean.mjs";
+import { writeFileSync, existsSync, readFileSync, mkdirSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { runCore, contractHash, isProtectedLaneBranch } from "./lean.mjs";
+import { makeLedger } from "./ledger.mjs";
 import { renderInvestigation, renderPlan, renderImplementation, renderReview, renderPrBody, renderTrajectory, renderContract, contractJson, parseContractComment, sanitizeMd, capComment, section, cell, NR, MAX_COMMENT_CHARS } from "./render.mjs";
 import { orchestrate, parseDeps, formatTable } from "./orchestrate.mjs";
 import { REVIEWER_SYSTEM, approxTokens, builderPlanPrompt, builderImplementPrompt, reviewerPrompt } from "./prompts.mjs";
-import { parseReview } from "./conformance.mjs";
+import { parseReview, unnamedEdges, structureNote, applyAmendments } from "./conformance.mjs";
 import { mapRecord } from "../engine/telemetry-seam.mjs";
 import { readLog } from "../engine/runlog.mjs";
-import { makeRunTmp, wrapLaneLimits, systemdRunAvailable, makeLeanRunner } from "./effects.mjs";
+import { makeRunTmp, wrapLaneLimits, systemdRunAvailable, makeLeanRunner, requiredChecksFor, procsInDir } from "./effects.mjs";
 import { retrying, PUSH_TRANSIENT_RE } from "./retry.mjs";
 import { checkAdmission } from "./admission.mjs";
 import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
@@ -52,8 +54,9 @@ function world(o = {}) {
     contract: o.contract ?? CONTRACT, issueComments: o.issueComments, issueStates: o.issueStates,
     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: [], mtimes: {}, envs: [], pushes: 0, pushErrors: [...(o.pushErrors ?? [])], commentErrors: [...(o.commentErrors ?? [])], dirty: o.dirty ?? false, lastSubject: o.lastSubject ?? "", prView: [...(o.prView ?? [])], mergeResults: [...(o.mergeResults ?? [])], mergeErrors: [...(o.mergeErrors ?? [])], conflictFiles: [], mergeInProgress: false, markers: false, mergeAttempts: 0,
+    prList: o.prList ?? [], remote: o.remote ?? "", resumeResult: o.resumeResult, seq: [], mtimes: {}, envs: [], pushes: 0, pushErrors: [...(o.pushErrors ?? [])], commentErrors: [...(o.commentErrors ?? [])], dirty: o.dirty ?? false, lastSubject: o.lastSubject ?? "", prView: [...(o.prView ?? [])], mergeResults: [...(o.mergeResults ?? [])], mergeErrors: [...(o.mergeErrors ?? [])], conflictFiles: [], mergeInProgress: false, markers: false, mergeAttempts: 0, branchDeletes: [],
     stages: { ...STAGE_MD, ...(o.stages ?? {}) }, builderN: 0,
+    salvageTrees: [...(o.salvageTrees ?? [])], alive: new Set((o.procs ?? []).map((p) => p.pid)), kills: [],
   };
   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]); };
@@ -67,6 +70,7 @@ function world(o = {}) {
       if (k === "pr list") return JSON.stringify(w.prList);
       if (k === "repo view") return `${o.defaultBranch ?? "main"}\n`;
       if (k === "issue view" && a.includes("milestone")) { w.seq.push("lane"); return JSON.stringify({ milestone: o.milestone ? { title: o.milestone } : null }); }
+      if (k === "issue view" && o.issueBodies && a[2] === "7" && a.includes("number,title,body,state,comments")) { const b = o.issueBodies.length > 1 ? o.issueBodies.shift() : o.issueBodies[0]; return JSON.stringify({ number: 7, title: "foo breaks", body: b, state: "OPEN", comments: [] }); }
       if (k === "issue view") return JSON.stringify({ number: Number(a[2]), title: "foo breaks", body: ISSUE_BODY, state: w.issueStates?.[a[2]] ?? "OPEN", comments: [] });
       if (k === "pr edit") { w.prEdits.push(a); return ""; }
       if (k === "issue comment" && w.commentErrors.length) throw new Error(w.commentErrors.shift());
@@ -85,9 +89,12 @@ function world(o = {}) {
       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] === "worktree" && a[1] === "remove") w.seq.push("worktree-remove");
+      if (a[0] === "update-ref") w.seq.push(`update-ref ${a[1]}`);
       if (a[0] === "rev-parse" && a[1] === "--git-path") return "/repo/.git/info/exclude";
       if (a[0] === "status" && a[1] === "--porcelain") return w.dirty ? " M src/foo.js\n" : "";
       if (a[0] === "log" && a.includes("--format=%s")) return w.lastSubject;
+      if (a[0] === "push" && a.includes("--delete")) { w.branchDeletes.push(a.at(-1)); w.seq.push("delete-remote-branch"); return ""; }
       if (a[0] === "push") { w.pushes++; if (w.pushErrors.length) { const m = w.pushErrors.shift(); throw Object.assign(new Error(m), { stderr: m }); } }
       if (a[0] === "merge" && a[1] === "--no-edit") {
         const r = w.mergeResults.shift() ?? "clean";
@@ -95,6 +102,9 @@ function world(o = {}) {
         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] === "write-tree") return w.salvageTrees.length ? w.salvageTrees.shift() : "";
+      if (a[0] === "rev-parse" && a[1] === "HEAD^{tree}") return "0".repeat(40);
+      if (a.includes("commit-tree")) return "c".repeat(40);
       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" : "";
@@ -131,7 +141,7 @@ function world(o = {}) {
           if (/Merging origin\//.test(c.prompt) && o.syncChanged) w.changed = o.syncChanged;
           if (r?.status === "blocked" || ["invalid", "already-fixed"].includes(r?.status)) put("result.json", JSON.stringify(r));
           else if (r) put("result.json", JSON.stringify({ ...r, requirements: o.claims ?? w.contract.requirements.filter((x) => x.disposition === "deliver").map((x) => ({ id: x.id, status: "implemented", evidence: "src/foo.js:3" })),
-            validation: o.validation ?? (w.contract.validate ?? []).map((v) => ({ id: v.id, command: v.command, exit: 0 })), amendments: (c.resume && n > 2 ? o.resumeAmendments : null) ?? o.amendments ?? [] }));
+            validation: (c.resume && n > 2 ? o.resumeValidation : null) ?? o.validation ?? (w.contract.validate ?? []).map((v) => ({ id: v.id, command: v.command, exit: 0 })), amendments: (c.resume && n > 2 ? o.resumeAmendments : null) ?? o.amendments ?? [] }));
         }
         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" };
@@ -140,7 +150,8 @@ function world(o = {}) {
     },
     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: { 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; }, write: async (p, t) => { w.files[p] = t; } },
+    ...(o.procs ? { proc: { inDir: async () => o.procs, alive: (pid) => w.alive.has(pid), kill: (pid, sig) => { w.kills.push([pid, sig]); w.seq.push(`kill-${sig}`); if (sig === "SIGKILL" || !o.stubborn) w.alive.delete(pid); } } } : {}),
+    fs: { ...(o.wtExists ? { exists: async (p) => p.startsWith("/wt/lean-7") } : {}), 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; }, write: async (p, t) => { w.files[p] = t; } },
     fileFollowups: async ({ parent, items }) => { w.followups.push({ parent, items }); if (o.followupError) throw new Error(o.followupError); return Object.fromEntries(items.map((i) => [i.key, o.followupIssue ?? 900])); },
   };
   return w;
@@ -407,6 +418,29 @@ describe("core work-on", () => {
     noNeedsHuman(w);
   });
 
+  it("#4153 a split of a milestone issue files every sub-issue with the parent's milestone; no milestone passes none", async () => {
+    const split = { status: "blocked", summary: "epic", block: { kind: "split-required", subissues: [{ title: "part A", body: "do A" }, { title: "part B", body: "do B", depends_on: [0] }] } };
+    const w = depWorld({ changed: [], result: split, milestone: "Remote MCP Server", branchesOnOrigin: ["staging", "milestone/remote-mcp-server"] }, {});
+    const r = await run(w, { lane: null });
+    assert.equal(r.terminalReason, "decomposed");
+    assert.equal(w.created.length, 2);
+    for (const c of w.created) assert.equal(c[c.indexOf("--milestone") + 1], "Remote MCP Server", c.join(" "));
+    const w2 = depWorld({ changed: [], result: split }, {});
+    assert.equal((await run(w2)).terminalReason, "decomposed");
+    assert.ok(w2.created.every((c) => !c.includes("--milestone")));
+  });
+
+  it("#4153 a dependency block on an open decomposed parent resolves to its open sub-issues", async () => {
+    const decomposed = { body: "<!-- FORGE:DECOMPOSED -->\n## Split into sub-issues\n- #31 part A\n- #32 part B\n", author_association: "NONE", user: { type: "Bot", login: "forge[bot]" } };
+    const parent = { state: "OPEN", labels: [{ name: "workflow:decomposed" }] };
+    const w = depWorld({ changed: [], issueComments: [decomposed], result: { status: "blocked", summary: "needs #3", block: { kind: "dependency", issues: [3] } } },
+      { 3: parent, 31: { state: "CLOSED", labels: [] }, 32: { state: "OPEN", labels: [] } });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "dependency-open");
+    assert.deepEqual(r.dependencies, [32]);
+    noNeedsHuman(w);
+  });
+
   it("#4124 a prod-data (non-human) or untyped block gets one corrective resume; a builder that then proceeds merges", async () => {
     const w = world({ result: { status: "blocked", summary: "needs live wire capture and prod baselines", block: { kind: "human", why: "prod-data" } },
       resumeResult: { status: "fixed", summary: "captured via read-only monitoring", evidence: [], tests: [] } });
@@ -634,9 +668,126 @@ describe("conformance gate (frozen contract, precheck, structured review)", () =
   });
 });
 
+describe("issue edited mid-run (#4188)", () => {
+  const BODY_B = "foo now also needs a bar mode.\n\n- foo must accept a bar flag and return bar output.\n- Existing callers of foo keep working.";
+  const contractB = { ...CONTRACT, requirements: [{ id: "R1", quote: "foo must accept a bar flag and return bar output.", disposition: "deliver" }] };
+  const reviewB = () => conf({ issue_coverage: [{ quote: "foo must accept a bar flag and return bar output.", status: "covered" }] }, contractB);
+
+  it("body A at RUN_START, body B at validation, contract quoting B: validates against B, logs ISSUE_EDITED, merges", async () => {
+    const dir = tmpDir("issue-edited-");
+    const w = world({ contract: contractB, issueBodies: [ISSUE_BODY, BODY_B], reviews: [reviewB()] });
+    const r = await run(w, { dir });
+    assert.notEqual(r.code, "contract.invalid");
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(builders(w).length, 2, "plan + implement, no contract correction");
+    const edits = readLog(dir, 7).filter((e) => e.event === "ISSUE_EDITED");
+    assert.equal(edits.length, 1);
+    assert.match(edits[0].old, /^[0-9a-f]{12}$/); assert.match(edits[0].new, /^[0-9a-f]{12}$/);
+    assert.notEqual(edits[0].old, edits[0].new);
+    assert.match(traj(w).at(-1), /Issue edited during the run \([0-9a-f]{12} -> [0-9a-f]{12}\)/);
+  });
+
+  it("an unchanged issue emits no ISSUE_EDITED", async () => {
+    const dir = tmpDir("issue-unedited-");
+    const w = world({ issueBodies: [ISSUE_BODY] });
+    assert.equal((await run(w, { dir })).terminalReason, "merged");
+    assert.equal(readLog(dir, 7).filter((e) => e.event === "ISSUE_EDITED").length, 0);
+  });
+});
+
+describe("review row skeleton and targeted retry (#4160)", () => {
+  it("the reviewer prompt carries a pre-filled skeleton with every requirement and preserve id", async () => {
+    const w = world();
+    assert.equal((await run(w)).terminalReason, "merged");
+    const p = reviewers(w)[0][4];
+    const sk = JSON.parse(/<row_skeleton>\n([\s\S]*?)\n<\/row_skeleton>/.exec(p)[1]);
+    assert.deepEqual(sk.requirements.map((r) => r.id), CONTRACT.requirements.map((r) => r.id));
+    assert.deepEqual(sk.preserve.map((x) => x.id), (CONTRACT.preserve ?? []).map((x) => x.id));
+    assert.doesNotMatch(p, /previous_reply_problems/);
+  });
+  it("an incomplete first reply gets one retry that lists exactly what was missing, and the complete second reply decides", async () => {
+    const w = world({ reviews: [genericPass(), ok()] });
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.equal(reviewers(w).length, 2);
+    const p2 = reviewers(w)[1][4];
+    assert.match(p2, /<previous_reply_problems>[\s\S]*requirement R1 needs exactly one row/);
+    assert.match(p2, /<previous_reply>[\s\S]*"verdict":"PASS"/);
+  });
+  it("a complete first reply needs no second reviewer run", async () => {
+    const w = world();
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.equal(reviewers(w).length, 1);
+  });
+});
+
+describe("worktree salvage and orphaned processes (#4162)", () => {
+  const T1 = "1".repeat(40), T2 = "2".repeat(40);
+  const salvageRefs = (w) => w.calls.filter((c) => c[0] === "git" && c[1] === "update-ref").map((c) => c[2]);
+
+  it("uncommitted work in an earlier run's worktree is saved to a salvage ref before the worktree is removed, and the implementer is told", async () => {
+    const dir = tmpDir("salvage-");
+    const w = world({ wtExists: true, salvageTrees: [T1] });
+    assert.equal((await run(w, { dir })).terminalReason, "merged");
+    const refs = salvageRefs(w);
+    assert.equal(refs.length, 1); assert.match(refs[0], /^refs\/forge\/salvage\/7\/\d+$/);
+    assert.ok(w.seq.indexOf(`update-ref ${refs[0]}`) < w.seq.indexOf("worktree-remove"), "saved before removal");
+    assert.ok(w.calls.some((c) => c[0] === "git" && c[1] === "add" && c[2] === "-f" && c.includes(".forge-lean")), ".forge-lean is included");
+    assert.ok(builders(w).some((b) => b[4].includes(`saved at \`${refs[0]}\``)), "implement prompt names the ref");
+    assert.match(traj(w).at(-1), /Uncommitted work from an earlier run saved to `refs\/forge\/salvage\/7\//);
+    assert.equal(readLog(dir, 7).filter((e) => e.event === "WORKTREE_SALVAGED").length, 1);
+  });
+
+  it("a clean earlier worktree (tree equals HEAD) saves nothing and the prompt is unchanged", async () => {
+    const w = world({ wtExists: true, salvageTrees: ["0".repeat(40)] });
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.equal(salvageRefs(w).length, 0);
+    assert.ok(builders(w).every((b) => !b[4].includes("saved at")));
+  });
+
+  it("no worktree on disk: nothing is staged or saved", async () => {
+    const w = world({ salvageTrees: [T1] });
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.equal(salvageRefs(w).length, 0);
+    assert.ok(!w.calls.some((c) => c[0] === "git" && c[1] === "write-tree"));
+  });
+
+  it("processes still running in the worktree are stopped (SIGTERM) before the worktree is removed", async () => {
+    const w = world({ procs: [{ pid: 4242, cmd: "claude --print" }] });
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.deepEqual(w.kills, [[4242, "SIGTERM"]]);
+    assert.ok(w.seq.indexOf("kill-SIGTERM") < w.seq.indexOf("worktree-remove"));
+    assert.match(traj(w).at(-1), /Stopped 1 process\(es\) still running in the worktree from an earlier run: 4242 claude --print/);
+  });
+
+  it("a process that ignores SIGTERM is killed with SIGKILL", async () => {
+    const w = world({ procs: [{ pid: 4243, cmd: "node x" }], stubborn: true });
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.deepEqual(w.kills, [[4243, "SIGTERM"], [4243, "SIGKILL"]]);
+  });
+
+  it("salvage runs only at the start: teardown at the end is the #4179 checkpoint, not a salvage ref", async () => {
+    const w = world({ wtExists: true, salvageTrees: ["0".repeat(40), T2] });
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.equal(salvageRefs(w).length, 0);
+  });
+
+  it("procsInDir reads cwd links from a /proc tree and skips this process and its ancestors", () => {
+    const root = tmpDir("proc-"), wtDir = tmpDir("wt-");
+    const mk = (pid, cwdTarget, ppid, cmd) => { mkdirSync(join(root, String(pid)), { recursive: true }); symlinkSync(cwdTarget, join(root, String(pid), "cwd")); writeFileSync(join(root, String(pid), "stat"), `${pid} (x y) S ${ppid} 0`); writeFileSync(join(root, String(pid), "cmdline"), cmd.split(" ").join("\0")); };
+    mk(100, wtDir, 1, "claude --print");
+    mk(101, join(wtDir, "src"), 1, "node test");
+    mk(102, "/elsewhere", 1, "bash");
+    mk(200, wtDir, 1, "self");
+    mkdirSync(join(root, "self")); // non-numeric entries are ignored
+    assert.deepEqual(procsInDir(wtDir, { procRoot: root, self: 200 }).map((p) => [p.pid, p.cmd]).sort(), [[100, "claude --print"], [101, "node test"]]);
+    assert.deepEqual(procsInDir(wtDir, { procRoot: join(root, "missing") }), []);
+  });
+});
+
 describe("conformance shadow mode (the default)", () => {
   const runShadow = (w, extra = {}) => run(w, { conformance: "shadow", ...extra });
   const shadowNote = (w) => w.comments.find((c) => c.includes("<!-- FORGE:REVIEW -->")) ?? "";
+  const nhBody = (w) => w.comments.find((c) => c.includes("FORGE:NEEDS_HUMAN")) ?? "";
   const omission = () => conf({ issue_coverage: [{ quote: "foo must handle a null argument without throwing.", status: "covered" }, { quote: "Existing callers of foo keep working.", status: "missing" }] }, { ...CONTRACT, preserve: [] }, ["src/foo.js", "test/foo.test.js"]);
 
   it("runCore defaults to shadow", async () => {
@@ -675,6 +826,40 @@ describe("conformance shadow mode (the default)", () => {
     assert.equal((await runShadow(w2)).terminalReason, "merged"); assert.equal(builders(w2).length, 3, "a regression is resumed in shadow too");
   });
 
+  it("shadow blocks a failed validate command (#4160): one resume, then needs-human, and no reviewer tokens are spent", async () => {
+    const failed = [{ id: "V1", command: "node --test test/foo.test.js", exit: 1 }];
+    const w = world({ validation: failed });
+    const r = await runShadow(w);
+    assert.equal(r.code, "conformance.unimplemented"); assert.equal(w.merges.length, 0);
+    assert.equal(builders(w).length, 3, "plan + implement + one resume"); assert.equal(reviewers(w).length, 0);
+    assert.match(builders(w)[2][4], /validate V1 failed \(exit 1\)/);
+    assert.match(nhBody(w), /validate V1 failed \(exit 1\)/);
+  });
+
+  it("shadow: a failed validate fixed by the resume merges", async () => {
+    const w = world({ validation: [{ id: "V1", command: "node --test test/foo.test.js", exit: 1 }], resumeValidation: [{ id: "V1", command: "node --test test/foo.test.js", exit: 0 }] });
+    assert.equal((await runShadow(w)).terminalReason, "merged"); assert.equal(builders(w).length, 3);
+  });
+
+  it("shadow blocks a deliver requirement the builder reported as partial (#4160)", async () => {
+    const w = world({ claims: [{ id: "R1", status: "partial" }] });
+    const r = await runShadow(w);
+    assert.equal(r.code, "conformance.unimplemented"); assert.equal(w.merges.length, 0); assert.equal(builders(w).length, 3);
+    assert.match(nhBody(w), /R1 reported "partial"/);
+  });
+
+  it("shadow still only records a validate step with no recorded result (CI-only steps) and does not block on it", async () => {
+    const w = world({ validation: [] });
+    assert.equal((await runShadow(w)).terminalReason, "merged");
+    assert.match(shadowNote(w), /validate V1 .*has no recorded result/);
+  });
+
+  it("enforce blocks a failed validate exactly as before", async () => {
+    const w = world({ validation: [{ id: "V1", command: "node --test test/foo.test.js", exit: 1 }] });
+    const r = await run(w, { conformance: "enforce" });
+    assert.equal(r.code, "conformance.unimplemented"); assert.equal(w.merges.length, 0);
+  });
+
   it("shadow files nothing: accepted deferrals are listed as not filed, and the PR links nothing", async () => {
     const k = { ...CONTRACT, preserve: [], requirements: [CONTRACT.requirements[0], { id: "R2", quote: "Existing callers of foo keep working.", disposition: "defer", why: "w" }] };
     const w = world({ contract: k, claims: [{ id: "R1", status: "implemented" }], reviews: [conf({}, k)] });
@@ -711,6 +896,107 @@ describe("conformance gate: base-sync and contract size", () => {
   });
 });
 
+describe("structure delta (forge#4159): undeclared package edges block, import growth only reports", () => {
+  const EDGE = { from: "@s/db", to: "@s/core", kind: "dependencies", manifest: "packages/db/package.json" };
+  const delta = (o = {}) => ({ package_edges_added: [], package_edges_removed: [], import_pairs: [], boundary_config_changed: { changed: false, files: [], loosens: false, tightens: false }, ...o });
+  /** world whose io.structureDelta returns the given deltas in order (the last one repeats). */
+  const sworld = (deltas, o = {}) => {
+    const w = world(o); const q = [...deltas]; w.structureCalls = [];
+    w.io.structureDelta = async (x) => { w.structureCalls.push(x); return q.length > 1 ? q.shift() : q[0]; };
+    return w;
+  };
+  const nh = (w) => w.comments.find((c) => c.includes("FORGE:NEEDS_HUMAN")) ?? "";
+  const withEdgeDeliverable = (change) => ({ ...CONTRACT, deliverables: [...CONTRACT.deliverables, { id: "D2", path: "packages/db/package.json", change }] });
+
+  it("a new package edge the contract does not name gets one builder resume; removed on the resume, it merges", async () => {
+    const dir = tmpDir("struct-");
+    const w = sworld([delta({ package_edges_added: [EDGE] }), delta()]);
+    const r = await run(w, { dir });
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(builders(w).length, 3); assert.equal(reviewers(w).length, 1);
+    assert.match(builders(w)[2][4], /@s\/db -> @s\/core \(dependencies, packages\/db\/package\.json\)[\s\S]*add it to the contract with a reason, or remove it/);
+    assert.equal(builders(w)[2][2], "sess-1", "resumed in the builder's own session");
+    assert.deepEqual(w.structureCalls[0], { cwd: "/wt/lean-7", base: "origin/staging" });
+    const e = readLog(dir, 7).find((x) => x.event === "STRUCTURE_DELTA");
+    assert.equal(e.edges_added, 1);
+    assert.ok(readLog(dir, 7).findIndex((x) => x.event === "STRUCTURE_DELTA") < readLog(dir, 7).findIndex((x) => x.event === "CONFORMANCE"), "before the conformance review");
+  });
+
+  it("an undeclared edge that survives the resume is needs-human structure.undeclared_edge, in enforce and in shadow, with no reviewer run", async () => {
+    for (const conformance of ["enforce", "shadow"]) {
+      const w = sworld([delta({ package_edges_added: [EDGE] })]);
+      const r = await run(w, { conformance });
+      assert.equal(r.terminalReason, "needs-human"); assert.equal(r.code, OUTCOME_CODES.STRUCTURE_UNDECLARED_EDGE);
+      assert.equal(builders(w).length, 3, "exactly one builder resume"); assert.equal(reviewers(w).length, 0);
+      assert.equal(w.prs.length, 0); assert.equal(w.merges.length, 0);
+      assert.match(nh(w), /@s\/db → @s\/core \(dependencies, `packages\/db\/package\.json`\)/);
+    }
+  });
+
+  it("an edge the contract names (a deliverable on the manifest whose change names the package) passes with no resume", async () => {
+    const w = sworld([delta({ package_edges_added: [EDGE] })], { contract: withEdgeDeliverable("add @s/core: db needs the tenant constants (docs/architecture.md: db depends on core)") });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged"); assert.equal(builders(w).length, 2);
+    // the manifest alone, without the package named, is not naming the edge
+    assert.equal(unnamedEdges(withEdgeDeliverable("bump versions"), delta({ package_edges_added: [EDGE] })).length, 1);
+    assert.equal(unnamedEdges(withEdgeDeliverable("add @s/core"), delta({ package_edges_added: [EDGE] })).length, 0);
+  });
+
+  it("an add-deliverable amendment on a package.json the contract already lists (for another change) declares the edge", () => {
+    const frozen = { requirements: [], deliverables: [{ id: "D1", path: "packages/db/package.json", change: "bump versions" }] };
+    const r = applyAmendments(frozen, [{ kind: "add-deliverable", path: "packages/db/package.json", why: "add @s/core: the architecture doc lets db depend on core" }]);
+    assert.equal(r.contract.deliverables.length, 1); assert.equal(r.contract.deliverables[0].id, "D1");
+    assert.match(r.contract.deliverables[0].change, /^bump versions; add @s\/core/);
+    assert.equal(unnamedEdges(r.contract, delta({ package_edges_added: [EDGE] })).length, 0);
+    assert.equal(frozen.deliverables[0].change, "bump versions", "the frozen contract is not mutated");
+  });
+
+  it("an add-deliverable amendment naming the package on the resume declares the edge", async () => {
+    const w = sworld([delta({ package_edges_added: [EDGE] })], { resumeAmendments: [{ kind: "add-deliverable", path: "packages/db/package.json", why: "add @s/core: the architecture doc lets db depend on core" }],
+      changed: ["src/foo.js", "test/foo.test.js"] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged"); assert.equal(builders(w).length, 3);
+  });
+
+  it("import-pair growth and boundary loosening never block: one <structure> line in the one reviewer prompt, telemetry recorded", async () => {
+    const d = delta({ import_pairs: [{ from: "@s/web", to: "@s/db", files_added: 8, files_removed: 0 }], boundary_config_changed: { changed: true, files: ["eslint.config.mjs"], loosens: true, tightens: false } });
+    for (const conformance of ["enforce", "shadow"]) {
+      const w = sworld([d]);
+      const r = await run(w, { conformance });
+      assert.equal(r.terminalReason, "merged"); assert.equal(builders(w).length, 2); assert.equal(reviewers(w).length, 1, "no extra reviewer run");
+      const lines = reviewers(w)[0][4].split("\n").filter((l) => l.includes("<structure>"));
+      assert.equal(lines.length, 1);
+      assert.match(lines[0], /^<structure>Structure \(report only\): this PR adds 8 value imports @s\/web→@s\/db \(files\); the repo's boundary config was loosened in this PR \(eslint\.config\.mjs\); flag only if the contract or the architecture doc says otherwise\.<\/structure>$/);
+      const t = w.telemetry.find((x) => x.event === "STRUCTURE_DELTA");
+      assert.deepEqual([t.import_files_added, t.boundary_loosened, t.phase], [8, true, "implement"]);
+      assert.deepEqual(mapRecord(t, 5).payload, { edges_added: 0, edges_removed: 0, import_files_added: 8, import_files_removed: 0, boundary_changed: 1, boundary_loosened: 1 });
+    }
+  });
+
+  it("no workspace packages ({}), a failed script or no io.structureDelta: no event, no prompt line, the same reviewer prompt", async () => {
+    const base = world(); await run(base);
+    for (const d of [{}, null]) {
+      const dir = tmpDir("struct-none-");
+      const w = sworld([d]);
+      assert.equal((await run(w, { dir })).terminalReason, "merged");
+      assert.equal(reviewers(w)[0][4], reviewers(base)[0][4]);
+      assert.ok(!readLog(dir, 7).some((x) => x.event === "STRUCTURE_DELTA")); assert.ok(!w.telemetry.some((x) => x.event === "STRUCTURE_DELTA"));
+      assert.equal(builders(w).length, 2);
+    }
+    assert.equal(structureNote({}), ""); assert.equal(structureNote(null), ""); assert.equal(structureNote(delta()), "");
+    assert.equal(structureNote(delta({ import_pairs: [{ from: "a", to: "b", files_added: 0, files_removed: 3 }] })), "", "removals are not growth");
+  });
+
+  it("the reviewer prompt is byte-identical without a structure line, and the planner and builder are told what declares an edge", () => {
+    const args = { issue: { number: 7, title: "t", body: "b" }, contract: CONTRACT, result: {}, files: ["a"], diff: "d" };
+    assert.equal(reviewerPrompt(args), reviewerPrompt({ ...args, structure: "" }));
+    assert.ok(reviewerPrompt({ ...args, structure: "x\ny" }).endsWith("</diff>\n<structure>x y</structure>"));
+    assert.match(builderPlanPrompt(7), /"the lint allows it" or "there is a precedent" is not a reason on its own/);
+    assert.match(builderPlanPrompt(7), /must be a deliverable on that package\.json whose change names the package and gives the reason/);
+    assert.match(builderImplementPrompt(), /blocked by the engine: add it through add-deliverable with a why naming the package/);
+  });
+});
+
 describe("comment templates", () => {
   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" }],
@@ -1141,6 +1427,46 @@ describe("runCliBackendAsync", () => {
   });
 });
 
+describe("requiredChecksFor: classic protection + rulesets (#4158)", () => {
+  const RULES_JQ = '.[] | select(.type == "required_status_checks") | .parameters.required_status_checks[]?.context';
+  const jqRules = (rules) => rules.filter((r) => r.type === "required_status_checks").flatMap((r) => r.parameters.required_status_checks.map((c) => c.context)).join("\n") + "\n";
+  const stub = ({ classic, rules }) => {
+    const calls = [];
+    const gh = async (a) => {
+      calls.push(a);
+      if (a[1] === "repos/o/r/branches/staging/protection/required_status_checks") { if (classic instanceof Error) throw classic; return JSON.stringify(classic); }
+      if (a.includes("repos/o/r/rules/branches/staging")) {
+        assert.ok(a.includes("--paginate")); assert.equal(a[a.indexOf("--jq") + 1], RULES_JQ);
+        if (rules instanceof Error) throw rules; return jqRules(rules);
+      }
+      throw new Error(`unexpected gh ${a.join(" ")}`);
+    };
+    return { gh, calls };
+  };
+  it("ruleset-only required checks are found when classic protection 404s", async () => {
+    const { gh } = stub({ classic: new Error("HTTP 404: Branch not protected"), rules: [{ type: "required_status_checks", parameters: { required_status_checks: [{ context: "build" }] } }, { type: "pull_request", parameters: {} }] });
+    assert.deepEqual(await requiredChecksFor({ gh, repo: "o/r", lane: "staging" }), ["build"]);
+  });
+  it("classic and ruleset checks are unioned without duplicates", async () => {
+    const { gh } = stub({ classic: { contexts: ["a"], checks: [{ context: "b" }] }, rules: [{ type: "required_status_checks", parameters: { required_status_checks: [{ context: "b" }, { context: "c" }] } }] });
+    assert.deepEqual(await requiredChecksFor({ gh, repo: "o/r", lane: "staging" }), ["a", "b", "c"]);
+  });
+  it("both sources failing yields [] and never throws", async () => {
+    const { gh } = stub({ classic: new Error("HTTP 404"), rules: new Error("HTTP 404") });
+    assert.deepEqual(await requiredChecksFor({ gh, repo: "o/r", lane: "staging" }), []);
+  });
+  it("a ruleset-derived required check is polled before the merge", async () => {
+    const w = world();
+    const { gh } = stub({ classic: new Error("HTTP 404"), rules: [{ type: "required_status_checks", parameters: { required_status_checks: [{ context: "build" }] } }] });
+    w.io.requiredChecks = (lane) => requiredChecksFor({ gh, repo: "o/r", lane });
+    const seqs = [[{ name: "build", state: "pending" }], [{ name: "build", state: "success" }]]; let polls = 0;
+    w.io.checkStates = async () => { polls++; return seqs.shift(); };
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged"); assert.equal(polls, 2);
+    assert.match(traj(w)[0], /\| Merge \| required \(build\) \|/);
+  });
+});
+
 describe("base-sync (#4100)", () => {
   const CONFLICTING = { mergeable: "CONFLICTING", mergeStateStatus: "DIRTY" };
   const OKSTATE = { mergeable: "MERGEABLE", mergeStateStatus: "CLEAN" };
@@ -1162,7 +1488,7 @@ describe("base-sync (#4100)", () => {
     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.equal(g.filter((x) => x[0] === "push" && !x.includes("--delete")).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\) \|/);
@@ -1233,6 +1559,27 @@ describe("base-sync (#4100)", () => {
     assert.ok(!syncComment(w));
   });
 
+  const BLOCKED = { mergeable: "MERGEABLE", mergeStateStatus: "BLOCKED" };
+  const POLICY = "GraphQL: Pull request is not mergeable: the base branch policy prohibits the merge (mergePullRequest)";
+  it("#4158 a policy block (MERGEABLE + BLOCKED) waits and retries the merge; no base-sync", async () => {
+    const w = world({ prView: [BLOCKED], mergeErrors: [POLICY] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(w.mergeAttempts, 2);
+    assert.equal(gitCalls(w).filter((x) => x[0] === "merge" && x[1] === "--no-edit").length, 0, "no base-sync");
+    assert.ok(!syncComment(w));
+    assert.deepEqual(w.merges[0].slice(-2), ["--match-head-commit", w.head]);
+  });
+  it("#4158 a persistent policy block ends ci-pending, never base.conflict", async () => {
+    const w = world({ prView: [BLOCKED], mergeErrors: Array(50).fill(POLICY) });
+    const r = await run(w, { ciMaxMinutes: 5 });
+    assert.equal(r.terminalReason, "ci-pending");
+    assert.notEqual(r.code, "base.conflict");
+    assert.equal(gitCalls(w).filter((x) => x[0] === "merge" && x[1] === "--no-edit").length, 0, "no base-sync");
+    assert.equal(w.merges.length, 0); assert.ok(!syncComment(w));
+    assert.ok(!w.edits.some((e) => e.includes("needs-human")));
+  });
+
   it("a resumed run with a conflicting PR re-plans, verifies, then syncs in the same session", 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);
@@ -1364,6 +1711,26 @@ describe("usage limit, lease takeover, worktree setup, run tmp (#4101-#4104)", (
     }
   });
 
+  it("#4181 the builder and reviewer get FORGE_DOCKER_LABELS with the ledger's batch and lane, with or without a run tmp", async () => {
+    for (const withTmp of [false, true]) {
+      const w = world();
+      if (withTmp) w.io.runTmp = { prune: async () => {}, make: async (i, id) => `/home/x/.forge/tmp/runs/${id}`, remove: async () => {} };
+      assert.equal((await run(w, { batchId: "b1" })).terminalReason, "merged");
+      assert.ok(w.envs.length >= 1);
+      for (const e of w.envs) {
+        const labels = String(e?.FORGE_DOCKER_LABELS ?? "").split(" ");
+        assert.deepEqual(labels.slice(0, 4), ["forgedock.owner=1", "forgedock.batch=b1", "forgedock.lane=lean-7", "forgedock.issue=7"]);
+        assert.match(labels[4], /^forgedock\.expires=\d+$/);
+        if (withTmp) assert.match(e.TMPDIR, /\/runs\/7-/); else assert.equal(e.TMPDIR, undefined);
+      }
+    }
+  });
+
+  it("#4181 the implement prompt tells the builder to use --rm, the labels and a trap teardown", () => {
+    const p = builderImplementPrompt();
+    for (const needle of ["FORGE_DOCKER_LABELS", "--rm", "--label", "trap", "volume create", "network create", "build"]) assert.ok(p.includes(needle), needle);
+  });
+
   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-");
@@ -1587,7 +1954,7 @@ describe("batch robustness (#4112-#4115)", () => {
     const w = world({ pushErrors: Array(10).fill("fatal: the remote end hung up unexpectedly\nerror: RPC failed; HTTP 503") });
     const r = await run(w);
     assert.equal(r.terminalReason, "deferred"); assert.equal(r.code, "push.transient");
-    assert.equal(w.pushes, 4);
+    assert.equal(w.pushes, 8, "4 for the PR push, then 4 by the exit checkpoint that never discards unpushed work (#4179)");
     assert.equal(w.prs.length, 0);
   });
 
@@ -1595,8 +1962,9 @@ describe("batch robustness (#4112-#4115)", () => {
     for (const msg of ["remote: error: GH006: Protected branch update failed for refs/heads/x", "fatal: unable to access: The requested URL returned error: 403", "! [remote rejected] x -> x (pre-receive hook declined)"]) {
       const w = world({ pushErrors: [msg, msg, msg] });
       const r = await run(w);
-      assert.equal(w.pushes, 1, msg);
+      assert.equal(w.pushes, 2, `${msg}: one rejected PR push, one rejected exit checkpoint (#4179), no retries`);
       assert.equal(r.terminalReason, "needs-human");
+      assert.equal(w.calls.filter((c) => c[1] === "worktree" && c[2] === "remove").length, 1, "the unpushed worktree is kept: only the setup remove ran");
     }
   });
 
@@ -1919,3 +2287,243 @@ describe("large diffs never reach argv (#4129)", () => {
     assert.match(readFileSync(new URL("../../docs/OUTCOME-CODES.md", import.meta.url), "utf8"), /`cli\.spawn_failed`/);
   });
 });
+
+describe("verify-by-CI (#4167): ci mode runs the heavy checks on CI and feeds failures to the builder", () => {
+  const CI = { mode: "ci", workflow: "verify.yml", pathsInput: "changed_paths", skipPaths: ["*.md", "docs/**"], maxRounds: 2 };
+  /** Adds the CI seams to a world: each dispatch creates a run for the current head; `conclusions` is consumed per run. */
+  const withCi = (w, { conclusions = ["success"], dispatchError = null, log = "ERROR: poetry.lock is not up to date" } = {}) => {
+    w.ci = { dispatched: [], runs: [], logsFor: [], conclusions: [...conclusions] };
+    Object.assign(w.io, {
+      dispatchWorkflow: async (a) => { w.seq.push("dispatch"); if (dispatchError) throw new Error(dispatchError); w.ci.dispatched.push(a); const id = 100 + w.ci.runs.length;
+        const c = w.ci.conclusions.length > 1 ? w.ci.conclusions.shift() : w.ci.conclusions[0]; w.ci.runs.unshift({ databaseId: id, headSha: w.head, status: c === "pending" ? "in_progress" : "completed", conclusion: c === "pending" ? null : c, url: `https://github.com/o/r/actions/runs/${id}`, name: "verify" }); },
+      workflowRuns: async () => w.ci.runs,
+      failedLogs: async (id) => { w.ci.logsFor.push(id); return log; },
+    });
+    return w;
+  };
+  const ciValidation = [{ id: "V1", command: "node --test test/foo.test.js", ci: true }];
+  const events = (dir) => readLog(dir, 7).filter((e) => e.event === "CI_VERIFY");
+
+  it("green CI: the builder is told not to run test suites, the branch is pushed and verified before review, validate left to CI passes enforce", async () => {
+    const w = withCi(world({ validation: ciValidation }));
+    const dir = tmpDir("core-ci-");
+    const r = await run(w, { verify: CI, dir });
+    assert.equal(r.terminalReason, "merged");
+    const impl = builders(w)[1][4];
+    assert.match(impl, /Do NOT run type-checks .*test suites .*docker\/test containers/);
+    assert.doesNotMatch(impl, /run every validate command/);
+    assert.deepEqual(w.ci.dispatched, [{ workflow: "verify.yml", ref: "feat/issue-7-lean", inputs: { changed_paths: "src/foo.js\ntest/foo.test.js" } }]);
+    assert.ok(w.seq.indexOf("dispatch") < w.seq.indexOf("reviewer"), "CI runs before the conformance review");
+    assert.ok(w.pushes >= 1);
+    assert.deepEqual(events(dir).map((e) => [e.result, e.mode]), [["pass", "ci"]]);
+    assert.match(traj(w)[0], /\| Verify \| CI green at /);
+  });
+
+  it("red CI: the failed job's log goes back to the builder, the fix is re-verified, then merged", async () => {
+    const w = withCi(world({ validation: ciValidation }), { conclusions: ["failure", "success"] });
+    const r = await run(w, { verify: CI });
+    assert.equal(r.terminalReason, "merged");
+    const fix = builders(w).find((b) => /CI failed on the pushed branch/.test(b[4]));
+    assert.ok(fix, "a CI-fix resume ran"); assert.equal(fix[2], "sess-1");
+    assert.match(fix[4], /poetry\.lock is not up to date/); assert.match(fix[4], /actions\/runs\/100/);
+    assert.deepEqual(w.ci.logsFor, [100]);
+    assert.equal(w.ci.dispatched.length, 2, "the fixed head is verified again");
+    assert.notEqual(w.ci.runs[0].headSha, w.ci.runs[1].headSha);
+  });
+
+  it("CI still red after max_rounds: needs-human ci.red and nothing merges to the lane", async () => {
+    const w = withCi(world({ validation: ciValidation }), { conclusions: ["failure"] });
+    const r = await run(w, { verify: { ...CI, maxRounds: 1 } });
+    assert.equal(r.terminalReason, "needs-human"); assert.equal(r.code, "ci.red");
+    assert.equal(w.prs.length, 0); assert.equal(w.merges.length, 0); assert.equal(reviewers(w).length, 0);
+  });
+
+  it("without the fix, a validate id left to CI is missing under enforce (the regression this guards)", async () => {
+    const w = world({ validation: ciValidation });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "needs-human"); assert.equal(w.merges.length, 0);
+  });
+
+  it("docs-only lane: no push for CI, no dispatch; the decision is recorded", async () => {
+    const w = withCi(world({ changed: ["README.md", "docs/guide.md"], validation: ciValidation }));
+    const r = await run(w, { verify: CI, conformance: "shadow" });
+    assert.equal(r.terminalReason, "merged"); assert.equal(w.ci.dispatched.length, 0);
+    assert.match(traj(w)[0], /CI verification skipped/);
+  });
+
+  it("CI unavailable: falls back once to local validation in the builder session", async () => {
+    const w = withCi(world({ validation: ciValidation, resumeValidation: [{ id: "V1", command: "node --test test/foo.test.js", exit: 0 }] }), { dispatchError: "HTTP 422: Workflow does not have 'workflow_dispatch' trigger" });
+    w.resumeResult = { ...w.result };
+    const r = await run(w, { verify: CI, conformance: "shadow" });
+    assert.equal(r.terminalReason, "merged");
+    assert.ok(builders(w).some((b) => /CI verification is unavailable/.test(b[4])));
+    assert.match(traj(w)[0], /local fallback/);
+  });
+
+  it("slow CI ends ci-pending (never needs-human) before any PR", async () => {
+    const w = withCi(world({ validation: ciValidation }), { conclusions: ["pending"] });
+    const r = await run(w, { verify: CI, ciMaxMinutes: 10 });
+    assert.equal(r.terminalReason, "ci-pending"); assert.equal(w.prs.length, 0);
+  });
+
+  it("local (default): no CI seam is touched and the implement prompt is unchanged", async () => {
+    const w = withCi(world());
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged"); assert.equal(w.ci.dispatched.length, 0);
+    assert.equal(builders(w)[1][4], builderImplementPrompt());
+    assert.doesNotMatch(traj(w)[0], /\| Verify \|/);
+  });
+
+  it("forge.yaml verify: block section is read; absent section is undefined", async () => {
+    const { readVerify } = await import("../engine-cli.mjs");
+    const d = tmpDir("verify-yaml-");
+    writeFileSync(`${d}/forge.yaml`, "engine:\n  conformance: shadow\n");
+    assert.equal(readVerify(d), undefined);
+    writeFileSync(`${d}/forge.yaml`, "verify:\n  mode: ci\n  workflow: verify.yml\n  skip_paths: \"*.md,docs/**\"\n  max_rounds: 3\n");
+    assert.deepEqual(readVerify(d), { mode: "ci", workflow: "verify.yml", pathsInput: null, skipPaths: ["*.md", "docs/**"], maxRounds: 3 });
+  });
+});
+
+describe("lane resource ledger + teardown on every exit path (#4179)", () => {
+  /** A world with a real on-disk ledger, fake docker/kill, a run tmp with a known path and a builder that reports its pid + a container. */
+  const ledgered = (o = {}) => {
+    const w = world(o);
+    const root = tmpDir("ledger-");
+    w.ledgerRoot = root; w.docker = []; w.killed = []; w.snapshots = []; w.tmpRemoved = [];
+    w.io.ledger = (opts) => makeLedger({ root, ...opts });
+    w.io.docker = async (a) => { w.docker.push(a); return ""; };
+    w.io.killGroup = async (pid, marker) => { w.killed.push([pid, marker]); return true; };
+    w.io.runTmp = { prune: async () => {}, path: (id) => `/home/x/.forge/tmp/runs/${id}`, make: async (_i, id) => `/home/x/.forge/tmp/runs/${id}`, remove: async (d) => { w.tmpRemoved.push(d); return true; } };
+    w.ledgerFile = join(root, o.batch ?? "adhoc", "lean-7.json");
+    const r0 = w.io.runner;
+    w.io.runner = async (c) => {
+      if (c.role === "builder") {
+        c.onSpawn?.({ pid: 4242, spawnfile: "/usr/bin/claude" });
+        w.snapshots.push(JSON.parse(readFileSync(w.ledgerFile, "utf8"))); // what a crash right now would leave behind
+        if (o.during) await o.during(w, c);
+      }
+      const r = await r0(c);
+      if (c.role === "builder" && !/PLANNING ONLY/.test(c.prompt) && w.files[`${WT}/.forge-lean/result.json`]) {
+        const j = JSON.parse(w.files[`${WT}/.forge-lean/result.json`]);
+        w.files[`${WT}/.forge-lean/result.json`] = JSON.stringify({ ...j, resources: { containers: ["lean7-testpg"], volumes: ["lean7-pgdata", "bad name; rm -rf /"] } });
+      }
+      return r;
+    };
+    return w;
+  };
+  const gitIdx = (w, pred) => { let i = -1; w.calls.forEach((c, k) => { if (c[0] === "git" && pred(c.slice(1))) i = k; }); return i; };
+  /** The exit teardown: the last two worktree calls are `remove --force <wt>` then `prune`; the ledger file is gone. */
+  const tornDown = (w, label) => {
+    const wtCalls = w.calls.filter((c) => c[0] === "git" && c[1] === "worktree");
+    assert.deepEqual(wtCalls.at(-2), ["git", "worktree", "remove", "--force", WT], `${label}: worktree removed`);
+    assert.deepEqual(wtCalls.at(-1), ["git", "worktree", "prune"], `${label}: then pruned`);
+    assert.equal(existsSync(w.ledgerFile), false, `${label}: ledger cleared`);
+  };
+
+  it("while the lane runs, the ledger on disk lists worktree, branch, run tmp and builder pid with owner/batch/lane/issue/created/expires (survives a crash)", async () => {
+    const w = ledgered({ batch: "b1" });
+    await run(w, { batchId: "b1" });
+    const snap = w.snapshots.at(-1);
+    for (const k of ["owner", "batch", "lane", "issue", "created", "expires"]) assert.ok(snap[k] != null, `ledger has ${k}`);
+    assert.equal(snap.batch, "b1"); assert.equal(snap.lane, "lean-7"); assert.equal(snap.issue, 7); assert.ok(snap.expires > snap.created);
+    const kinds = snap.resources.map((r) => `${r.kind}:${r.value}`);
+    for (const k of [`worktree:${WT}`, "branch:feat/issue-7-lean", "pid:4242"]) assert.ok(kinds.includes(k), `${k} in ${kinds}`);
+    assert.ok(kinds.some((k) => k.startsWith("tmp:/home/x/.forge/tmp/runs/7-")));
+    assert.equal(snap.resources.find((r) => r.kind === "pid").marker, "claude");
+    // a crash at this point leaves exactly this file: a fresh reader still sees every resource
+    const crashed = tmpDir("ledger-crash-");
+    const l = makeLedger({ root: crashed, batch: "b1", lane: "lean-7", owner: "x", issue: 7 });
+    for (const r of snap.resources) l.register(r.kind, r.value);
+    assert.deepEqual(makeLedger({ root: crashed, batch: "b1", lane: "lean-7", issue: 7 }).entries().map((r) => r.kind).sort(), ["branch", "pid", "tmp", "worktree"]);
+  });
+
+  it("merged: remote branch deleted after the merge, worktree removed + pruned, local branch deleted, reported docker resources removed, ledger cleared", async () => {
+    const w = ledgered();
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.deepEqual(w.branchDeletes, ["feat/issue-7-lean"]);
+    assert.ok(w.seq.indexOf("delete-remote-branch") > w.seq.indexOf("merge"), "deleted only after the merge");
+    tornDown(w, "merged");
+    const rm = gitIdx(w, (a) => a[0] === "worktree" && a[1] === "remove"), bd = gitIdx(w, (a) => a[0] === "branch" && a[1] === "-D");
+    assert.ok(bd > rm, "local branch deleted after its worktree is gone");
+    assert.deepEqual(w.docker, [["rm", "-f", "lean7-testpg"], ["volume", "rm", "lean7-pgdata"]], "only well-formed names the builder reported");
+    assert.equal(w.tmpRemoved.length, 1);
+    assert.equal(gitIdx(w, (a) => a[0] === "commit"), -1, "a merged lane is never checkpointed");
+  });
+
+  it("an open PR using the lane branch as head or base keeps it (remote and local)", async () => {
+    for (const side of ["--head", "--base"]) {
+      const w = ledgered();
+      const g = w.io.gh; let merged = false;
+      w.io.gh = async (a) => {
+        if (a[0] === "pr" && a[1] === "merge") merged = true;
+        if (merged && a[0] === "pr" && a[1] === "list" && a[a.indexOf(side) + 1] === "feat/issue-7-lean") return JSON.stringify([{ number: 99 }]);
+        return g(a);
+      };
+      assert.equal((await run(w)).terminalReason, "merged");
+      assert.deepEqual(w.branchDeletes, [], side);
+      assert.equal(gitIdx(w, (a) => a[0] === "branch" && a[1] === "-D"), -1, side);
+    }
+  });
+
+  it("main, staging, milestone/* and anything but the issue's own lane branch are never deletion targets", () => {
+    const ctx = { issue: 7, lane: "staging", branches: { default: "main", staging: "staging" }, defaults: ["main"] };
+    for (const b of ["main", "master", "staging", "milestone/x", "milestone/adaptive", "feat/issue-8-lean", "", null]) assert.equal(isProtectedLaneBranch(b, ctx), true, String(b));
+    assert.equal(isProtectedLaneBranch("feat/issue-7-lean", ctx), false);
+    assert.equal(isProtectedLaneBranch("feat/issue-7-lean", { ...ctx, lane: "feat/issue-7-lean" }), true, "never the lane itself");
+    assert.equal(isProtectedLaneBranch("feat/issue-7-lean", { ...ctx, defaults: ["feat/issue-7-lean"] }), true, "never a default branch");
+  });
+
+  const exits = {
+    invalid: { o: { changed: [], result: { status: "invalid", summary: "not a bug", evidence: ["src/foo.js:3 already guards null"], tests: [] } }, reason: "invalid" },
+    "needs-human": { o: { waits: [{ rc: 1, text: "lint failed" }] }, extra: { mergeWait: "all" }, reason: "needs-human" },
+    "engine-error": { o: { during: (w, c) => { if (!/PLANNING ONLY/.test(c.prompt)) throw new Error("boom"); } }, reason: "engine-error" },
+    deferred: { o: { during: (w, c) => { if (!/PLANNING ONLY/.test(c.prompt)) throw Object.assign(new Error("session limit"), { usageLimit: true, resetAtEpochMs: 1e13 }); } }, reason: "deferred" },
+  };
+  for (const [name, x] of Object.entries(exits)) {
+    it(`${name}: teardown runs (worktree remove --force + prune, pid killed, docker removed, ledger cleared); no branch is deleted on origin`, async () => {
+      const w = ledgered(x.o);
+      const r = await run(w, x.extra ?? {});
+      assert.equal(r.terminalReason, x.reason);
+      tornDown(w, name);
+      assert.deepEqual(w.branchDeletes, []);
+      assert.equal(w.tmpRemoved.length, 1);
+    });
+  }
+
+  it("an unmerged lane with uncommitted work is committed and pushed to the lane branch BEFORE its worktree is removed", async () => {
+    const w = ledgered({ dirty: true, waits: [{ rc: 1, text: "lint failed" }] });
+    const r = await run(w, { mergeWait: "all" });
+    assert.equal(r.terminalReason, "needs-human");
+    const commit = gitIdx(w, (a) => a[0] === "commit" && a.some((x) => /checkpoint after exit \(needs-human\)/.test(x)));
+    const push = gitIdx(w, (a) => a[0] === "push" && a.includes("feat/issue-7-lean") && !a.includes("--delete"));
+    const rm = gitIdx(w, (a) => a[0] === "worktree" && a[1] === "remove");
+    assert.ok(commit > 0 && push > commit && rm > push, `commit ${commit} < push ${push} < remove ${rm}`);
+    tornDown(w, "dirty needs-human");
+  });
+
+  it("a checkpoint that cannot push keeps the worktree and leaves worktree + branch listed in the ledger", async () => {
+    const msg = "remote: error: GH006: Protected branch update failed for refs/heads/x";
+    const w = ledgered({ dirty: true, pushErrors: [msg, msg, msg] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "needs-human");
+    assert.equal(w.calls.filter((c) => c[1] === "worktree" && c[2] === "remove").length, 1, "only the setup remove ran");
+    const left = JSON.parse(readFileSync(w.ledgerFile, "utf8")).resources.map((x) => x.kind).sort();
+    assert.deepEqual(left, ["branch", "worktree"]);
+  });
+
+  it("SIGTERM/SIGINT: the registered teardown checkpoints, removes the worktree, clears the ledger, releases the lease, ends deferred run.interrupted", async () => {
+    for (const sig of ["SIGTERM", "SIGINT"]) {
+      let td = null, out = null;
+      const w = ledgered({ dirty: true, during: async (w2, c) => { if (!/PLANNING ONLY/.test(c.prompt) && !out) out = await td(sig); } });
+      w.leaseWrites = []; w.io.projector = { readState: async () => null, writeState: async (_i, st) => { w.leaseWrites.push(st); } };
+      const r = await run(w, { onTeardown: (fn) => { td = fn; } });
+      assert.equal(out.terminalReason, "deferred", sig); assert.equal(out.code, "run.interrupted");
+      assert.equal(r, out, "the run's own later finish returns the same result (idempotent)");
+      assert.equal(w.leaseWrites.at(-1).lease, null, "lease released");
+      assert.ok(gitIdx(w, (a) => a[0] === "commit") > 0, "uncommitted work checkpointed");
+      assert.deepEqual(w.killed, [[4242, "claude"]], "the builder's process group is signalled");
+      tornDown(w, sig);
+    }
+  });
+});