forgedock 1.24.5 → 1.25.0

package/bin/lean/lean.test.mjs

@@ -43,6 +43,8 @@ function world(o = {}) {
       const k = a.slice(0, 2).join(" ");
       if (a[0] === "api") return "";
       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") return JSON.stringify({ number: 7, title: "foo breaks", body: "Bug in foo", state: "OPEN" });
       if (k === "issue comment" && w.commentErrors.length) throw new Error(w.commentErrors.shift());
       if (k === "issue comment") { w.comments.push(a[a.indexOf("--body") + 1]); w.seq.push("comment"); return `https://github.com/o/r/issues/7#issuecomment-${w.comments.length}\n`; }
@@ -77,6 +79,7 @@ function world(o = {}) {
       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";
+      if (a[0] === "ls-remote" && String(a.at(-1)).startsWith("refs/heads/")) { const b = a.at(-1).slice("refs/heads/".length); return (o.branchesOnOrigin ?? ["staging", "main"]).includes(b) ? `abc\trefs/heads/${b}\n` : ""; }
       if (a[0] === "ls-remote") return w.remote;
       if (a[0] === "push") w.seq.push("push");
       return "";
@@ -236,11 +239,86 @@ describe("core work-on", () => {
     assert.equal(builders(w).length, 1);
   });
 
-  it("builder blocked, or no commit, is needs-human", async () => {
-    assert.equal((await run(world({ result: { status: "blocked", summary: "need creds" } }))).terminalReason, "needs-human");
+  it("builder blocked on a typed human reason, or no commit, is needs-human", async () => {
+    assert.equal((await run(world({ result: { status: "blocked", summary: "need creds", block: { kind: "human", why: "credentials" } } }))).terminalReason, "needs-human");
     assert.equal((await run(world({ changed: [] }))).terminalReason, "needs-human");
   });
 
+  // #4124: a builder block is typed; only kind "human" with an allowed reason may reach needs-human.
+  const depWorld = (o, deps) => {
+    const w = world(o);
+    const gh = w.io.gh;
+    w.created = [];
+    w.io.gh = async (a) => {
+      if (a[0] === "issue" && a[1] === "view" && deps[a[2]]) return JSON.stringify(deps[a[2]]);
+      if (a[0] === "issue" && a[1] === "create") { w.created.push(a); return `https://github.com/o/r/issues/${200 + w.created.length}\n`; }
+      return gh(a);
+    };
+    return w;
+  };
+  const noNeedsHuman = (w) => {
+    assert.ok(!w.edits.some((e) => e.includes("--add-label") && e.includes("needs-human")), JSON.stringify(w.edits));
+    assert.ok(!w.comments.some((c) => c.includes("FORGE:NEEDS_HUMAN")));
+  };
+
+  it("#4124 a builder block naming an open issue ends dependency-open with dependencies, not needs-human", async () => {
+    const w = depWorld({ changed: [], result: { status: "blocked", summary: "needs #34927 first", block: { kind: "dependency", issues: ["#3", 7] } } },
+      { 3: { state: "OPEN", labels: [] } });
+    const dir = tmpDir("lean-dep-");
+    const r = await run(w, { dir });
+    assert.equal(r.terminalReason, "dependency-open");
+    assert.equal(r.code, "dependency.open");
+    assert.deepEqual(r.dependencies, [3]);
+    assert.equal(readLog(dir, 7).find((e) => e.event === "RUN_TERMINAL").code, "dependency.open");
+    assert.ok(w.comments.some((c) => c.includes("FORGE:DEPENDENCY") && c.includes("#3")));
+    assert.ok(w.edits.some((e) => e.includes("--remove-label")), "workflow labels are cleared");
+    assert.equal(builders(w).length, 1);
+    noNeedsHuman(w);
+  });
+
+  it("#4124 an open dependency that is itself needs-human ends dependency-blocked; this issue is not labelled needs-human", async () => {
+    const w = depWorld({ changed: [], result: { status: "blocked", summary: "upstream", block: { kind: "dependency", issues: [3] } } },
+      { 3: { state: "OPEN", labels: [{ name: "needs-human" }] } });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "dependency-blocked");
+    assert.equal(r.code, "dependency.blocked");
+    assert.deepEqual(r.blockers, [3]);
+    noNeedsHuman(w);
+  });
+
+  it("#4124 split-required files sub-issues with Parent / Depends-on lines and ends decomposed", async () => {
+    const w = depWorld({ changed: [], result: { 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 r = await run(w);
+    assert.equal(r.terminalReason, "decomposed");
+    assert.deepEqual(r.subissues, [201, 202]);
+    const bodyB = w.created[1][w.created[1].indexOf("--body") + 1];
+    assert.match(bodyB, /^\*\*Parent\*\*: #7$/m);
+    assert.match(bodyB, /^\*\*Depends on\*\*: #201$/m);
+    assert.ok(w.labels.includes("decomposed"));
+    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: [] } });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    const resumed = builders(w).filter((c) => c[2]);
+    assert.equal(resumed.length, 1);
+    assert.match(resumed[0][4], /not a block that needs a human/);
+    noNeedsHuman(w);
+  });
+
+  it("#4124 a block that stays untyped after the correction is needs-human with builder.block_untyped; a closed dependency is not a block", async () => {
+    const w = depWorld({ changed: [], result: { status: "blocked", summary: "upstream", block: { kind: "dependency", issues: [3] } } },
+      { 3: { state: "CLOSED", labels: [] } });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "needs-human");
+    assert.equal(r.code, "builder.block_untyped");
+    assert.equal(builders(w).filter((c) => c[2]).length, 1);
+  });
+
   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");
@@ -259,7 +337,8 @@ describe("core work-on", () => {
       assert.equal(term[0].code, r.code);
       return term[0].code;
     };
-    assert.equal(await code(world({ result: { status: "blocked", summary: "need creds" } })), "builder.blocked");
+    assert.equal(await code(world({ result: { status: "blocked", summary: "need creds", block: { kind: "human", why: "credentials" } } })), "builder.blocked");
+    assert.equal(await code(world({ result: { status: "blocked", summary: "need creds" } })), "builder.block_untyped");
     assert.equal(await code(world({ changed: [] })), "builder.no_commit");
     assert.equal(await code(world({ waits: [{ rc: 1, text: "lint failed" }] }), { mergeWait: "all" }), "ci.red");
   });
@@ -565,6 +644,11 @@ describe("orchestrate", () => {
     assert.deepEqual(parseDeps("x\n**Depends on**: #4\n**Depends on**: #7\n", 7), [4]);
   });
 
+  it("#4121 parseDeps reads every declaration form, all numbers, and ignores mid-line prose", () => {
+    assert.deepEqual(parseDeps("Depends on #3, #5\n**Depends on** #6\nBlocked by #8\n- depends on: #9 and #10\n**Blocked by:** #11 — why", 1), [3, 5, 6, 8, 9, 10, 11]);
+    assert.deepEqual(parseDeps("This is blocked by #2 and depends on #4\nsee **Depends on**: #5", 1), []);
+  });
+
   it("runs at most K at once", async () => {
     const h = harness({});
     const rows = await orchestrate({ issues: [1, 2, 3, 4, 5, 6], parallel: 2, ...h });
@@ -593,6 +677,44 @@ describe("orchestrate", () => {
     assert.match(rows[1].detail, /#1/);
   });
 
+  it("#4124 dependency-open requeues the issue behind an out-of-set dependency and does not skip its dependents", async () => {
+    const log = [];
+    let firstRun = true;
+    const rows = await orchestrate({ issues: [1, 2], parallel: 2,
+      readBody: async (n) => (n === 2 ? "**Depends on**: #1" : ""),
+      runOne: async (n) => {
+        log.push(n);
+        if (n === 1 && firstRun) { firstRun = false; return { terminalReason: "dependency-open", dependencies: [9], detail: "depends on #9" }; }
+        return { terminalReason: "merged", pr: 100 + n };
+      } });
+    assert.deepEqual(log, [1, 9, 1, 2]);
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[1, "merged"], [2, "merged"], [9, "merged"]]);
+  });
+
+  it("#4124 a repeated dependency-open stops after the requeue cap", async () => {
+    const h = harness({}, { 1: "dependency-open" });
+    const clock = { t: 0 }, starts = [];
+    const rows = await orchestrate({ issues: [1], readBody: h.readBody, now: () => clock.t, sleep: async (ms) => { clock.t += ms; },
+      runOne: async (n) => { if (n === 1) { starts.push(clock.t); return { terminalReason: "dependency-open", dependencies: [5] }; } return { terminalReason: "merged" }; } });
+    assert.equal(starts.length, 3);
+    assert.equal(rows[0].outcome, "dependency-open");
+    // #4121: #5 already merged but #1 still reports it open: wait before relaunching instead of a hot loop.
+    assert.ok(starts[2] - starts[1] >= 60_000, JSON.stringify(starts));
+  });
+
+  it("#4124 decomposed runs its sub-issues and the parent's dependents wait on them", async () => {
+    const log = [];
+    const rows = await orchestrate({ issues: [1, 2], parallel: 3,
+      readBody: async (n) => ({ 2: "**Depends on**: #1", 12: "**Parent**: #1\n**Depends on**: #11" })[n] ?? "",
+      runOne: async (n) => {
+        log.push(`start ${n}`); await new Promise((r) => setImmediate(r)); log.push(`end ${n}`);
+        return n === 1 ? { terminalReason: "decomposed", subissues: [11, 12] } : { terminalReason: "merged" };
+      } });
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[1, "decomposed"], [2, "merged"], [11, "merged"], [12, "merged"]]);
+    assert.ok(log.indexOf("end 11") < log.indexOf("start 12"));
+    assert.ok(log.indexOf("end 12") < log.indexOf("start 2"));
+  });
+
   it("a dependency that closed as invalid does not block", async () => {
     const h = harness({ 2: "**Depends on**: #1" }, { 1: "invalid" });
     const rows = await orchestrate({ issues: [1, 2], parallel: 2, ...h });
@@ -607,6 +729,22 @@ describe("orchestrate", () => {
     assert.equal(rows2[0].outcome, "engine-error");
   });
 
+  it("#4122 same-file issues run in parallel; a needs-human peer does not skip them", async () => {
+    const h = harness({ 1: "Fix `app/scrape_phases.py` retry", 2: "Also touches `app/scrape_phases.py`", 3: "See app/scrape_phases.py" }, { 1: "needs-human" });
+    const rows = await orchestrate({ issues: [1, 2, 3], parallel: 3, ...h });
+    assert.equal(h.log.maxActive, 3);
+    assert.deepEqual(rows.map((r) => r.outcome), ["needs-human", "merged", "merged"]);
+  });
+
+  it("#4122 /orchestrate spec builds no blocking edge from file overlap and skips only through explicit/logical edges", async () => {
+    const { readFileSync } = await import("node:fs");
+    const spec = readFileSync(new URL("../../commands/orchestrate.md", import.meta.url), "utf8");
+    assert.doesNotMatch(spec, /\*\*Conflict:\*\*/);
+    assert.doesNotMatch(spec, /run one after the\s+other/);
+    assert.match(spec, /File overlap is \*\*never\*\* an edge/);
+    assert.match(spec, /needs-human[\s\S]*Only\s+explicit or logical edges skip a dependent/);
+  });
+
   it("formatTable prints issue, outcome, PR, cost, minutes", () => {
     const t = formatTable([{ issue: 1, outcome: "merged", pr: 101, cost_usd: 0.5, minutes: 3.2 }, { issue: 2, outcome: "skipped", pr: null, cost_usd: 0, minutes: 0, detail: "dependency #1 ended needs-human" }]);
     assert.match(t, /issue\s+outcome\s+PR\s+cost\s+min/);
@@ -614,21 +752,47 @@ describe("orchestrate", () => {
     assert.match(t, /skipped \(dependency #1/);
   });
 
-  it("orchestrateFromCli wires parallel, lane and prints the table", async () => {
+  it("orchestrateFromCli routes each issue to its own lane (no --lane), reports cross-lane edges, refuses --lane main", async () => {
     const seen = [];
     const logs = [];
+    const milestones = { 1: "M One", 2: null, 3: "M One" };
+    const leanIo = {
+      gh: async (a) => {
+        if (a[0] === "repo" && a[1] === "view") return "main\n";
+        if (a.includes("milestone")) return JSON.stringify({ milestone: milestones[a[2]] ? { title: milestones[a[2]] } : null });
+        return JSON.stringify({ body: a[2] === "1" ? "**Depends on**: #2" : "" });
+      },
+      git: async (a) => (a[0] === "ls-remote" && ["refs/heads/staging", "refs/heads/milestone/m-one"].includes(a.at(-1)) ? "abc\tref\n" : ""),
+    };
+    const deps = { dir: tmpDir("core-orch-"), batchRoot: tmpDir("core-orch-batch-"), allowTmpfs: true, emitTelemetry: async () => {}, io: { gh: async () => "o/r\n" }, leanIo,
+      leanModule: { runCore: async (o) => { seen.push([o.issue, o.lane, o.repo]); return { terminalReason: "merged", pr: 50 + o.issue, cost_usd: 1, wall_ms: 1 }; } } };
     const l = console.log; console.log = (s) => logs.push(String(s));
-    try {
-      const res = await orchestrateFromCli(["1", "2", "--parallel", "2", "--lane", "main", "--repo", "o/r"], {
-        dir: tmpDir("core-orch-"), emitTelemetry: async () => {}, io: { gh: async () => "o/r\n" },
-        leanIo: { gh: async () => JSON.stringify({ body: "" }) },
-        leanModule: { runCore: async (o) => { seen.push([o.issue, o.lane, o.repo]); return { terminalReason: "merged", pr: 50 + o.issue, cost_usd: 1, wall_ms: 1 }; } } });
-      assert.equal(res.ok, true);
-    } finally { console.log = l; }
-    assert.deepEqual(seen.sort(), [[1, "main", "o/r"], [2, "main", "o/r"]]);
+    let res;
+    try { res = await orchestrateFromCli(["1", "2", "3", "--parallel", "2", "--repo", "o/r", "--no-prefilter"], deps); } finally { console.log = l; }
+    assert.equal(res.ok, true);
+    assert.deepEqual(seen.sort((a, b) => a[0] - b[0]), [[1, "milestone/m-one", "o/r"], [2, "staging", "o/r"], [3, "milestone/m-one", "o/r"]]);
+    assert.deepEqual(res.crossLane, [{ issue: 1, lane: "milestone/m-one", dependency: 2, dependencyLane: "staging" }]);
+    assert.ok(logs.some((s) => /^cross-lane: #1 \(milestone\/m-one\) depends on #2 \(staging\)/.test(s)), logs.join("\n"));
     assert.ok(logs.some((s) => /issue\s+outcome/.test(s)));
+    // --lane is an assertion per issue: the staging issue matches, the milestone issues are refused without a run.
+    seen.length = 0;
+    console.log = () => {};
+    try { res = await orchestrateFromCli(["2", "3", "--repo", "o/r", "--lane", "staging", "--no-prefilter"], deps); } finally { console.log = l; }
+    assert.deepEqual(res.rows.map((r) => [r.issue, r.outcome, r.code ?? null]), [[2, "merged", null], [3, "lane-refused", "lane.mismatch"]]);
+    assert.deepEqual(seen, [[2, "staging", "o/r"]]);
+    await assert.rejects(orchestrateFromCli(["1", "--lane", "main", "--repo", "o/r"], { ...deps, io: { gh: async () => "main\n" } }), /lane\.default_branch/);
     await assert.rejects(orchestrateFromCli([], {}), /usage/);
   });
+
+  it("#4125 a lane-refused issue starts no run and its dependents are skipped, not reported as a cycle", async () => {
+    const runs = [];
+    const rows = await orchestrate({ issues: [1, 2, 3], parallel: 2, readBody: async (n) => (n === 2 ? "**Depends on**: #1" : ""),
+      resolveLane: async (n) => (n === 1 ? { ok: false, code: "lane.branch_missing", detail: "milestone/x missing" } : { ok: true, lane: "staging" }),
+      runOne: async (n, lane) => { runs.push([n, lane]); return { terminalReason: "merged" }; } });
+    assert.deepEqual(rows.map((r) => [r.issue, r.outcome]), [[1, "lane-refused"], [2, "skipped"], [3, "merged"]]);
+    assert.match(rows[1].detail, /dependency #1 ended lane-refused/);
+    assert.deepEqual(runs, [[3, "staging"]]);
+  });
 });
 
 describe("runCliBackendAsync", () => {
@@ -1216,3 +1380,197 @@ describe("batch robustness (#4112-#4115)", () => {
     assert.ok(w.calls.some((c) => c[0] === "git" && c[1] === "worktree" && c[2] === "add" && c.includes("origin/feat/issue-7-lean")));
   });
 });
+
+describe("lane resolution in core work-on (#4125)", () => {
+  const leased = (w) => { w.leaseWrites = []; w.io.projector = { readState: async () => null, writeState: async (_i, st) => { w.leaseWrites.push(st); } }; return w; };
+  const touched = (w) => ({ comments: w.comments.length, leases: w.leaseWrites.length, worktree: w.calls.filter((c) => c[1] === "worktree").length,
+    runner: w.calls.filter((c) => c[0] === "runner").length, labels: w.labels.length, prs: w.prs.length, merges: w.merges.length });
+  const nothing = { comments: 0, leases: 0, worktree: 0, runner: 0, labels: 0, prs: 0, merges: 0 };
+
+  it("a milestone issue with no --lane builds on and opens its PR against milestone/<slug>", async () => {
+    const w = leased(world({ milestone: "Adaptive Unblocking Control Loop", branchesOnOrigin: ["staging", "milestone/adaptive-unblocking-control-loop"] }));
+    const r = await run(w, { lane: undefined });
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(w.prs[0][w.prs[0].indexOf("--base") + 1], "milestone/adaptive-unblocking-control-loop");
+    assert.match(w.comments[0], /base `milestone\/adaptive-unblocking-control-loop`/);
+    assert.ok(w.calls.some((c) => c[0] === "git" && c[1] === "worktree" && c.includes("origin/milestone/adaptive-unblocking-control-loop")), "worktree based on the milestone lane");
+    assert.equal(w.leaseWrites[0].lane, "milestone/adaptive-unblocking-control-loop");
+  });
+
+  it("--lane staging on a milestone issue is refused (lane.mismatch) before any lease, comment or worktree", async () => {
+    const w = leased(world({ milestone: "M1", branchesOnOrigin: ["staging", "milestone/m1"] }));
+    const r = await run(w, { lane: "staging" });
+    assert.deepEqual([r.terminalReason, r.code], ["lane-refused", "lane.mismatch"]);
+    assert.deepEqual(touched(w), nothing);
+    // An explicit override is allowed and recorded in the trajectory.
+    const w2 = leased(world({ milestone: "M1", branchesOnOrigin: ["staging", "milestone/m1"] }));
+    const r2 = await run(w2, { lane: "staging", laneOverride: true });
+    assert.equal(r2.terminalReason, "merged");
+    assert.equal(w2.prs[0][w2.prs[0].indexOf("--base") + 1], "staging");
+    assert.ok(traj(w2)[0].includes("Lane override: staging instead of the resolved milestone/m1"));
+  });
+
+  it("--lane main (or the configured default branch) is refused, even with an override", async () => {
+    for (const [extra, o] of [[{ lane: "main" }, {}], [{ lane: "main", laneOverride: true }, {}], [{ lane: "prod", branches: { default: "prod" } }, { branchesOnOrigin: ["staging", "prod"] }]]) {
+      const w = leased(world(o));
+      const r = await run(w, extra);
+      assert.deepEqual([r.terminalReason, r.code], ["lane-refused", "lane.default_branch"], JSON.stringify(extra));
+      assert.deepEqual(touched(w), nothing);
+    }
+  });
+
+  it("a missing milestone/<slug> branch fails closed with lane.branch_missing", async () => {
+    const w = leased(world({ milestone: "Not Yet" }));
+    const r = await run(w, { lane: undefined });
+    assert.deepEqual([r.terminalReason, r.code], ["lane-refused", "lane.branch_missing"]);
+    assert.match(r.detail, /milestone\/not-yet/);
+    assert.deepEqual(touched(w), nothing);
+  });
+
+  it("an open PR targeting the default branch (or another lane) is never merged", async () => {
+    for (const [base, code] of [["main", "lane.default_branch"], ["milestone/other", "lane.mismatch"]]) {
+      const w = world({ prList: [{ number: 77, headRefOid: "aaaa1111aaaa1111", baseRefName: base }], remote: "abc\trefs/heads/feat/issue-7-lean" });
+      const r = await run(w);
+      assert.equal(r.terminalReason, "needs-human", base);
+      assert.equal(r.code, code);
+      assert.equal(w.merges.length, 0); assert.equal(w.prs.length, 0);
+      assert.equal(builders(w).length, 0);
+    }
+  });
+});
+
+describe("lane entry points (#4125)", () => {
+  const quiet = async (fn) => { const l = console.log; console.log = () => {}; try { return await fn(); } finally { console.log = l; } };
+  const deps = () => ({ dir: tmpDir("core-cli-"), emitTelemetry: async () => {}, leanIo: {}, io: { gh: async (a) => (a.includes("defaultBranchRef") ? "main\n" : "o/r\n") },
+    leanModule: { runCore: async (o) => ({ terminalReason: "merged", seen: o }) }, runIssue: async () => ({ terminalReason: "merged" }) });
+
+  it("run-issue refuses --lane main on the core and full paths; the core path needs no --lane", async () => {
+    await assert.rejects(runFromCli(["7", "--lane", "main", "--repo", "o/r"], deps()), /lane\.default_branch/);
+    await assert.rejects(runFromCli(["7", "--lane", "main", "--path", "full"], deps()), /lane\.default_branch/);
+    await assert.rejects(runFromCli(["7", "--path", "full"], deps()), /--lane is required with --path full/);
+    const r = await quiet(() => runFromCli(["7", "--repo", "o/r"], deps()));
+    assert.equal(r.seen.lane, undefined); assert.equal(r.seen.laneOverride, false);
+    const r2 = await quiet(() => runFromCli(["7", "--repo", "o/r", "--lane", "staging", "--lane-override"], deps()));
+    assert.deepEqual([r2.seen.lane, r2.seen.laneOverride], ["staging", true]);
+  });
+
+  it("the core run-issue prints lane-refused with its code", async () => {
+    const d = deps(); d.leanModule = { runCore: async () => ({ terminalReason: "lane-refused", code: "lane.mismatch", detail: "--lane staging does not match" }) };
+    const lines = []; const l = console.log; console.log = (x) => lines.push(String(x));
+    try { await runFromCli(["7", "--repo", "o/r", "--lane", "staging"], d); } finally { console.log = l; }
+    assert.equal(lines.at(-1), "issue #7 → lane-refused lane.mismatch (--lane staging does not match)");
+  });
+
+  it("no staging lane default remains in engine.mjs, runlog.mjs or engine-cli.mjs", async () => {
+    const { readFileSync } = await import("node:fs");
+    for (const f of ["../engine.mjs", "../engine/runlog.mjs", "../engine-cli.mjs"]) {
+      const src = readFileSync(new URL(f, import.meta.url), "utf8");
+      assert.doesNotMatch(src, /lane\s*=\s*"staging"|lane:\s*"staging"|"--lane"\)\s*\?\?\s*"staging"/, f);
+      assert.doesNotMatch(src, /--lane main/, f);
+    }
+  });
+});
+
+describe("large diffs never reach argv (#4129)", () => {
+  const ARGV_SAFE = 128 * 1024; // Linux MAX_ARG_STRLEN is 131072 bytes per argument
+  const bigDiff = (files, perFile) => Array.from({ length: files }, (_, i) =>
+    `diff --git a/corpus/f${i}.txt b/corpus/f${i}.txt\n--- a/corpus/f${i}.txt\n+++ b/corpus/f${i}.txt\n@@ -0,0 +1 @@\n+${"golden — ".repeat(Math.ceil(perFile / 11))}\n`).join("");
+
+  it("review of a branch whose diff is over 256 KiB completes, with every CLI argv element under the bound", async () => {
+    const { runCliBackend } = await import("../runner.mjs");
+    const diff = bigDiff(8, 40 * 1024);
+    assert.ok(Buffer.byteLength(diff) > 256 * 1024);
+    const w = world();
+    const g = w.io.git;
+    w.io.git = async (a, o2) => {
+      if (a[0] === "diff" && a[1] === "--stat=200") return " corpus/f0.txt | 1 +\n 8 files changed";
+      if (a[0] === "diff" && a.length === 2) return diff;
+      return g(a, o2);
+    };
+    const spawned = [];
+    const r0 = w.io.runner;
+    w.io.runner = async (c) => {
+      if (c.role !== "reviewer") return r0(c);
+      w.calls.push(["runner", c.role, null, c.model ?? null, c.prompt, c.readOnly ?? false, c.system]);
+      const env = runCliBackend({ spec: { name: "core-reviewer" }, userMessage: c.prompt, systemPrompt: c.system, args: ["7"], cwd: tmpDir("core-4129-"), logger: { log() {} },
+        spawnFn: (bin, args, o2) => { spawned.push({ args, input: o2.input }); return { status: 0, stdout: JSON.stringify({ result: ok(), session_id: "rev" }), stderr: "" }; } });
+      return { text: env.text, sessionId: "rev", usage: {}, costUsd: 0, durationMs: 1, turns: 1, model: c.model };
+    };
+    const res = await run(w);
+    assert.equal(res.terminalReason, "merged");
+    assert.equal(spawned.length, 1);
+    for (const a of spawned[0].args) assert.ok(Buffer.byteLength(String(a)) <= ARGV_SAFE, `argv element of ${Buffer.byteLength(String(a))} bytes`);
+    const prompt = reviewers(w)[0][4];
+    assert.ok(Buffer.byteLength(prompt) < 160 * 1024, `bounded prompt (${Buffer.byteLength(prompt)} bytes)`);
+    assert.match(prompt, /<stat>[\s\S]*8 files changed/);
+    assert.match(prompt, /<omitted_files>[\s\S]*corpus\/f7\.txt/);
+    assert.match(prompt, /Read them in your worktree/);
+  });
+
+  it("boundDiff keeps a fitting diff unchanged and otherwise keeps whole file diffs only", async () => {
+    const { boundDiff } = await import("./prompts.mjs");
+    const small = bigDiff(2, 100);
+    assert.equal(boundDiff(small, { maxBytes: 10000 }), small);
+    const d = bigDiff(5, 3000);
+    const out = boundDiff(d, { stat: "5 files changed", base: "origin/staging", maxBytes: 7000 });
+    assert.ok(Buffer.byteLength(out) < 7000 + 1000);
+    const shown = (out.match(/^diff --git /gm) ?? []).length;
+    assert.ok(shown >= 1 && shown < 5);
+    assert.equal((out.match(/^- corpus\//gm) ?? []).length, 5 - shown);
+    assert.match(out, /base origin\/staging/);
+  });
+
+  it("runCliBackend sends a prompt over the argv bound on stdin, a small one stays in argv", async () => {
+    const { runCliBackend, CLI_ARGV_PROMPT_MAX_BYTES } = await import("../runner.mjs");
+    assert.ok(CLI_ARGV_PROMPT_MAX_BYTES <= ARGV_SAFE);
+    const seen = [];
+    const call = (msg) => runCliBackend({ spec: { name: "t" }, userMessage: msg, systemPrompt: "sys", args: ["1"], cwd: tmpDir("core-4129-"), logger: { log() {} },
+      spawnFn: (_b, args, o2) => { seen.push({ args, input: o2.input }); return { status: 0, stdout: "{}", stderr: "" }; } });
+    const big = "é".repeat(200 * 1024);
+    call(big);
+    assert.equal(seen[0].input, big);
+    assert.ok(!seen[0].args.includes(big));
+    for (const a of seen[0].args) assert.ok(Buffer.byteLength(String(a)) <= CLI_ARGV_PROMPT_MAX_BYTES);
+    assert.equal(seen[0].args[0], "--print"); assert.equal(seen[0].args[1], "--output-format");
+    call("go");
+    assert.equal(seen[1].args[1], "go"); assert.equal(seen[1].input, undefined);
+  });
+
+  it("runCliBackendAsync pipes a 300 KiB prompt to a real child (no E2BIG)", async () => {
+    const { writeFileSync, chmodSync } = await import("node:fs");
+    const { runCliBackendAsync } = await import("../runner.mjs");
+    const d = tmpDir("core-4129-");
+    const bin = `${d}/fake-claude`;
+    writeFileSync(bin, '#!/bin/sh\nn=$(wc -c | tr -d " ")\necho "{\\"result\\":\\"$n $#\\",\\"session_id\\":\\"s\\"}"\n');
+    chmodSync(bin, 0o755);
+    const msg = "x".repeat(300 * 1024);
+    const r = await runCliBackendAsync({ spec: { name: "t" }, userMessage: msg, systemPrompt: "sys", args: ["1"], cwd: d, bin, logger: { log() {} } });
+    const [n] = r.text.split(" ");
+    assert.equal(Number(n), msg.length);
+    const small = await runCliBackendAsync({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: d, bin, logger: { log() {} } });
+    assert.equal(small.text.split(" ")[0], "0"); // small prompt: argv, stdin ignored
+  });
+
+  it("a deterministic spawn failure is CLI_SPAWN_FAILED and ends needs-human with cli.spawn_failed, not engine-error", async () => {
+    const { runCliBackend } = await import("../runner.mjs");
+    assert.throws(() => runCliBackend({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: tmpDir("core-4129-"), logger: { log() {} },
+      spawnFn: () => ({ status: null, error: Object.assign(new Error("spawn E2BIG"), { code: "E2BIG" }) }) }),
+    (e) => e.code === "CLI_SPAWN_FAILED" && e.spawnErrno === "E2BIG" && /E2BIG/.test(e.message));
+    assert.throws(() => runCliBackend({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: tmpDir("core-4129-"), logger: { log() {} },
+      spawnFn: () => ({ status: null, error: Object.assign(new Error("spawn EACCES"), { code: "EACCES" }) }) }),
+    (e) => e.code === "EACCES" && e.spawnDeterministic === true);
+    const w = world();
+    const r0 = w.io.runner;
+    w.io.runner = async (c) => { if (c.role === "reviewer") throw Object.assign(new Error("Failed to invoke claude CLI: spawn E2BIG"), { code: "CLI_SPAWN_FAILED", spawnErrno: "E2BIG" }); return r0(c); };
+    const res = await run(w);
+    assert.equal(res.terminalReason, "needs-human");
+    assert.equal(res.code, OUTCOME_CODES.CLI_SPAWN_FAILED);
+    const w2 = world();
+    const r2 = w2.io.runner;
+    w2.io.runner = async (c) => { if (c.role === "builder") throw Object.assign(new Error("Failed to invoke claude CLI: spawn ENOENT"), { code: "ENOENT", spawnErrno: "ENOENT", spawnDeterministic: true }); return r2(c); };
+    assert.equal((await run(w2)).code, OUTCOME_CODES.CLI_SPAWN_FAILED);
+    assert.equal(OUTCOME_CODES.CLI_SPAWN_FAILED, "cli.spawn_failed");
+    const { readFileSync } = await import("node:fs");
+    assert.match(readFileSync(new URL("../../docs/OUTCOME-CODES.md", import.meta.url), "utf8"), /`cli\.spawn_failed`/);
+  });
+});