forgedock 1.42.0 → 1.43.0

package/bin/lean/guardgate.test.mjs

@@ -5,7 +5,7 @@ import assert from "node:assert/strict";
 import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { oldRanges, selectGuards, runGuards, commandFor, basePathOf, guardFailures, supersessionComment, supersededIds, loadGuards } from "./guardgate.mjs";
+import { oldRanges, selectGuards, runGuards, commandFor, basePathOf, failingNames, guardFailures, supersessionComment, supersededIds, loadGuards } from "./guardgate.mjs";
 import { applyAmendments, precheck } from "./conformance.mjs";
 import { builderImplementPrompt, conformanceResumePrompt } from "./prompts.mjs";
 import { tmpDir } from "../tests/_tmp.mjs";
@@ -19,13 +19,13 @@ const put = (cwd, p, body) => { mkdirSync(join(cwd, p, ".."), { recursive: true
 const TEST_SRC = (v) => `import test from "node:test";\nimport assert from "node:assert/strict";\nimport { price } from "./a.mjs";\ntest("price is ${v}", () => assert.equal(price(), ${v}));\n`;
 
 /** A repo whose fix commit (merge_sha) made price() return 2, guarded by src/a.test.mjs; the lane starts from it. */
-function fixture() {
+function fixture(testSrc = TEST_SRC(2)) {
   const d = tmpDir("guardgate-");
   sh(d, "init", "-q", "-b", "main");
   put(d, "src/a.mjs", "export function price() {\n  return 1;\n}\n");
   sh(d, "add", "-A"); sh(d, "commit", "-qm", "init");
   put(d, "src/a.mjs", "export function price() {\n  return 2;\n}\n");
-  put(d, "src/a.test.mjs", TEST_SRC(2));
+  put(d, "src/a.test.mjs", testSrc);
   sh(d, "add", "-A"); sh(d, "commit", "-qm", "fix: price");
   const sha = sh(d, "rev-parse", "HEAD").trim();
   put(d, "src/other.mjs", "export const x = 1;\n");
@@ -127,6 +127,24 @@ test("a base test that cannot run in the cap, or has no known runner, is skipped
   assert.equal(existsSync(join(d, basePathOf("src/a.test.mjs"))), false);
 });
 
+test("a verify.guard_command template wins over the contract and the fallbacks (#4792)", async () => {
+  const gc = { ".py": "scripts/pytest {path}" };
+  assert.equal(commandFor("tests/test_a__guardbase.py", {}, gc), "scripts/pytest tests/test_a__guardbase.py");
+  assert.equal(commandFor("tests/test_a__guardbase.py", { validate: [{ command: "pytest -q tests/test_a.py" }] }, gc), "scripts/pytest tests/test_a__guardbase.py");
+  assert.equal(commandFor("tests/test_a__guardbase.py", {}, { ".py": "uv run pytest -q" }), "uv run pytest -q tests/test_a__guardbase.py");
+  assert.equal(commandFor("src/a.test__guardbase.mjs", {}, gc), "node --test src/a.test__guardbase.mjs");
+  const { d, guard } = fixture();
+  put(d, "src/a.mjs", "export function price() {\n  return 1;\n}\n");
+  commit(d, "revert");
+  const git = gitIn(d);
+  const { selected, mergeBase } = await selectGuards({ guards: [guard], files: files(d), git, base: "origin/main" });
+  const seen = [];
+  const r = await runGuards({ selected, mergeBase, contract: {}, guardCommand: { ".mjs": "run-it {path}" }, git, runCommand: async (a) => { seen.push(a); return { rc: 0, output: "" }; }, cwd: d, env: {} });
+  assert.equal(r.runs.length, 1);
+  assert.equal(seen[0].command, "run-it src/a.test__guardbase.mjs");
+  assert.equal(seen[0].cwd, d);
+});
+
 test("pytest-style guards run through the contract's own validate command with the path substituted", () => {
   assert.equal(commandFor("tests/test_a__guardbase.py", { validate: [{ command: "pytest -q tests/test_a.py" }] }), "pytest -q tests/test_a__guardbase.py");
   assert.equal(commandFor("tests/test_a__guardbase.py", {}), "python -m pytest -q tests/test_a__guardbase.py");
@@ -189,3 +207,91 @@ test("an additive enum change that updates its coverage test fails the guard wit
   const withIt = precheck({ contract: a.contract, ...base });
   assert.deepEqual(withIt.failures.filter((f) => f.kind === "guard_broken"), []);
 });
+
+// #4968: a guard test already red on the merge base must not block the lane
+const FLAKY = (v) => `${TEST_SRC(v)}test("env dependent", () => assert.fail("red on base"));\n`;
+const revert = (d) => { put(d, "src/a.mjs", "export function price() {\n  return 1;\n}\n"); commit(d, "revert"); };
+
+test("a guard test that already fails on base is skipped (fails on base), not guard_broken", async () => {
+  const { d, guard } = fixture(FLAKY(2));
+  put(d, "src/a.mjs", "export function price() {\n  return 1 + 1;\n}\n"); // harmless edit of the guarded line
+  commit(d, "refactor");
+  const { selected, r } = await gate(d, guard);
+  assert.equal(selected.length, 1);
+  assert.equal(r.failures.length, 0, JSON.stringify(r));
+  assert.ok(r.skipped.some((x) => /guard #7 .*fails on base/.test(x)), r.skipped.join("|"));
+});
+
+test("a test that passes on base and fails on the lane is blocked, with no skip", async () => {
+  const { d, guard } = fixture();
+  revert(d);
+  const { r } = await gate(d, guard);
+  assert.equal(r.failures.length, 1);
+  assert.deepEqual(r.skipped, []);
+  assert.match(r.failures[0].detail, /failing tests: price is 2:/);
+});
+
+test("a new failure in a file that already had one is blocked and its name leads the detail", async () => {
+  const { d, guard } = fixture(FLAKY(2));
+  revert(d);
+  const { r } = await gate(d, guard);
+  assert.equal(r.failures.length, 1, JSON.stringify({ skipped: r.skipped }));
+  const detail = r.failures[0].detail;
+  assert.match(detail, /failing tests: price is 2:\n/, "only the new failure is named");
+  assert.ok(detail.indexOf("failing tests:") < detail.indexOf("env dependent"), "names precede the output tail (any reporter)");
+});
+
+test("a passing guard adds no baseline worktree, and a failing one removes its worktree", async () => {
+  const pass = fixture();
+  const calls = [];
+  const spy = (cwd) => async (args) => { calls.push(args[0]); return sh(cwd, ...args); };
+  put(pass.d, "src/a.mjs", "export function price() {\n  return 1 + 1;\n}\n"); commit(pass.d, "refactor");
+  let git = spy(pass.d);
+  let { selected, mergeBase } = await selectGuards({ guards: [pass.guard], files: files(pass.d), git, base: "origin/main" });
+  calls.length = 0;
+  const ok = await runGuards({ selected, mergeBase, contract: {}, git, runCommand, cwd: pass.d, env: process.env });
+  assert.equal(ok.failures.length, 0);
+  assert.ok(!calls.includes("worktree"), calls.join(","));
+  const bad = fixture();
+  revert(bad.d);
+  git = spy(bad.d);
+  ({ selected, mergeBase } = await selectGuards({ guards: [bad.guard], files: files(bad.d), git, base: "origin/main" }));
+  calls.length = 0;
+  const r = await runGuards({ selected, mergeBase, contract: {}, git, runCommand, cwd: bad.d, env: process.env });
+  assert.equal(r.failures.length, 1);
+  assert.ok(calls.includes("worktree"));
+  assert.equal(sh(bad.d, "worktree", "list").trim().split("\n").length, 1, "baseline worktree removed");
+});
+
+test("the baseline rerun uses the verify.guard_command runner, so a real break still blocks", async () => {
+  const { d, guard } = fixture();
+  revert(d);
+  const git = gitIn(d);
+  const { selected, mergeBase } = await selectGuards({ guards: [guard], files: files(d), git, base: "origin/main" });
+  const seen = [];
+  // run-it only exists through guard_command: the lane copy fails, the base copy passes
+  const r = await runGuards({ selected, mergeBase, contract: {}, guardCommand: { ".mjs": "run-it {path}" }, git, runCommand: async (a) => {
+    seen.push(a);
+    return a.cwd === d ? { rc: 1, output: "not ok 1 - price is 2\n" } : { rc: 0, output: "ok 1 - price is 2\n" };
+  }, cwd: d, env: {} });
+  assert.deepEqual(seen.map((s) => s.command), ["run-it src/a.test__guardbase.mjs", "run-it src/a.test.mjs"]);
+  assert.notEqual(seen[1].cwd, d, "baseline runs in the merge-base worktree");
+  assert.equal(r.failures.length, 1, JSON.stringify(r.skipped));
+});
+
+test("a baseline that cannot run is skipped, never blocking", async () => {
+  const { d, guard } = fixture();
+  revert(d);
+  const git = async (a) => { if (a[0] === "worktree" && a[1] === "add") throw new Error("no worktree"); return sh(d, ...a); };
+  const { selected, mergeBase } = await selectGuards({ guards: [guard], files: files(d), git, base: "origin/main" });
+  const r = await runGuards({ selected, mergeBase, contract: {}, git, runCommand, cwd: d, env: process.env });
+  assert.equal(r.failures.length, 0);
+  assert.match(r.skipped[0], /baseline unavailable \(no worktree\)/);
+});
+
+test("failingNames reads TAP, spec and pytest output and ignores skips", () => {
+  assert.deepEqual(failingNames("ok 1 - a\nnot ok 2 - b c\n    not ok 1 - nested # SKIP why\nnot ok 3 - d # TODO x"), ["b c"]);
+  assert.deepEqual(failingNames("  ✖ spec one (1.2ms)\n✖ failing tests:\n  ✖ spec one (1.2ms)"), ["spec one"]);
+  assert.deepEqual(failingNames("FAILED tests/t.py::test_x - assert 1 == 2"), ["tests/t.py::test_x"]);
+  assert.equal(failingNames("all fine"), null);
+});

package/bin/lean/heavy.test.mjs

@@ -9,7 +9,7 @@ import { tmpDir } from "../tests/_tmp.mjs";
 import { guardChain, isPassThroughWrapper, SHIM_LOOP_MAX, classifyStep, heavyConfig, openHeavy, acquireHeavy, writeHeavyShims, heavyShimScript, sumWaits, runWrapped, HEAVY_BINS, isHeavyProcess } from "./heavy.mjs";
 import { checkAdmission, ADMISSION_DEFAULTS, localLaneCap } from "./admission.mjs";
 import { formatAlertLines, formatWaitSummary } from "./orchestrate.mjs";
-import { readHeavy, liveLaneCap } from "../engine-cli.mjs";
+import { readHeavy, readAdmission, liveLaneCap } from "../engine-cli.mjs";
 
 // Injected pids, clock and host: `live` is the set of pids the registry sees as alive; `mem` the MemAvailable in MB.
 const world = ({ mem = 12000, cores = 4, swapFree = 0 } = {}) => {
@@ -336,4 +336,14 @@ describe("validation steps and the local lane cap (#4777)", () => {
     assert.equal(liveLaneCap(1, { cfg: {}, host: { cores: () => 8, memAvailableMb: () => 64000 } })(), 1);
     assert.equal(liveLaneCap(3, { cfg: { enabled: false }, host: { cores: () => 8, memAvailableMb: () => 64000 } })(), 3);
   });
+
+  it("batch cap follows the repo forge.yaml lane_cpu_reservation / lane_mem_mb, not the process cwd (#4828)", () => {
+    const d = tmpDir("lane-cap-");
+    writeFileSync(join(d, "forge.yaml"), "engine:\n  lane_cpu_reservation: 4\n  lane_mem_mb: 4096\n");
+    const host = { cores: () => 16, memAvailableMb: () => 2048 + 3 * 4096 + 10 };
+    assert.equal(liveLaneCap(null, { cfg: readAdmission(d), host })(), 3, "memory binds at 4096 MB per lane");
+    assert.equal(liveLaneCap(null, { cfg: {}, host })(), 6, "defaults: 2048 MB per lane");
+    writeFileSync(join(d, "forge.yaml"), "engine:\n  lane_cpu_reservation: 8\n");
+    assert.equal(liveLaneCap(null, { cfg: readAdmission(d), host: { cores: () => 16, memAvailableMb: () => 64000 } })(), 2);
+  });
 });

package/bin/lean/lean.mjs

@@ -14,12 +14,12 @@ import { ciPollDelayMs, ENGINE_VERSION, DEFAULT_MAX_SESSION_LIMIT_PAUSES, DEFAUL
 import { openDependency, laneMergedPrs, dependencyOnLane, isTrustedComment, decomposedSubissues, isDecomposedRecord, reopenRevokedDecomposition } from "../engine/phases.mjs";
 import { createHash, randomBytes } from "node:crypto";
 import { otherLaneOwner } from "./lanelock.mjs";
-import { TRACKED, normalizeKindModes, blockingFailures, unverifiedRequirements, mutationTargets, mutationFailures, runMutationCheck, MUTATION_SURVIVED, isBugIssue, scopeText, explainFailures, inIssue, validateContract, cliUsageError, normalizeRunnerCommand, applyAmendments, precheck, repoTracks, dropScopeValidates, tagOutOfBand, parseReview, decide, mergeReviewRows, evidencePathOnly, closePlan, followupItems, bucketTally, pendingTracking, unnamedEdges, structureNote, impliedDocDeliverables } from "./conformance.mjs";
+import { describesUnrunnableCommand, removedPathsOf, TRACKED, normalizeKindModes, blockingFailures, unverifiedRequirements, mutationTargets, mutationFailures, runMutationCheck, MUTATION_SURVIVED, isBugIssue, scopeText, explainFailures, inIssue, validateContract, cliUsageError, normalizeRunnerCommand, applyAmendments, precheck, repoTracks, dropScopeValidates, tagOutOfBand, parseReview, decide, mergeReviewRows, evidencePathOnly, closePlan, followupItems, bucketTally, pendingTracking, unnamedEdges, structureNote, impliedDocDeliverables } from "./conformance.mjs";
 import { checkAdmission, hostParallelism, ADMISSION_RETRY_SECONDS } from "./admission.mjs";
 import { namedPaths, isTrustedIssueComment } from "./prefilter.mjs";
 import { checksAt } from "./postdeploy-check.mjs";
 import { readRollouts, detectNewOffKeys } from "./activation.mjs";
-import { preflightProbes, preflightProblems, unsetEnvVars, runPreflight, knownToContract } from "./preflight.mjs";
+import { testRunnerProblems, preflightProbes, preflightProblems, unsetEnvVars, runPreflight, knownToContract } from "./preflight.mjs";
 import { resolveLane, isDefaultLane, isShippedLane, DEFAULT_STAGING_BRANCH } from "./lane.mjs";
 import { splitGate, rationaleLine } from "./decompose.mjs";
 import { dockerLabels, LEDGER_TTL_MS } from "./ledger.mjs";
@@ -37,7 +37,7 @@ import { hostCapabilityBlock, contractHostNeeds } from "./execution.mjs";
 const MISSING_TOOL_RE = /command not found|not found in PATH|no such file or directory.*\b(?:docker|promtool)\b|\b(?:docker|promtool)\b[^\n]{0,80}(?:not (?:installed|found|available)|no such file|cannot connect|daemon)|cannot connect to the docker daemon|no docker daemon|no module named|ModuleNotFoundError|\bENOENT\b[^\n]{0,60}spawn/i;
 /** #4685: true when a builder's block summary names a missing tool or module (environment), not a credential. */
 export function missingToolBlock(summary) { return MISSING_TOOL_RE.test(String(summary ?? "")); }
-import { REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, INVESTIGATION_FILE, IMPLEMENTATION_FILE, CONTRACT_FILE, builderPlanPrompt, builderImplementPrompt, contractCorrectionPrompt, conformanceResumePrompt, reviewerPrompt, decisionNote, reviewerRepairPrompt, REVIEW_DIFF_MAX_BYTES, blockCorrectionPrompt, HUMAN_BLOCK_REASONS, structurePrompt, hotspotPlanNote, hotspotBuildRule, reproPlanNote, contextPackNote, docsPrompt, ciFailurePrompt, ciUnavailablePrompt, precheckFailurePrompt, contextRestartPrompt, turnBudgetWrapupPrompt, syncChecks, GROUPING_SYSTEM, enumeratingPlanNote, enumeratingBuildRule, invariantsPlanNote, invariantsBuildRule, missingEntriesPrompt, sequencePrompt, sequenceSyncNote, sequenceSyncPrompt, fixSessionPrompt, postMergeFailurePrompt, duplicateExportsPrompt, migrationGeneratorPrompt, i18nCopiesPrompt } from "./prompts.mjs";
+import { REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, INVESTIGATION_FILE, IMPLEMENTATION_FILE, CONTRACT_FILE, builderPlanPrompt, builderImplementPrompt, contractCorrectionPrompt, conformanceResumePrompt, reviewerPrompt, investigationVerdict, decisionNote, reviewerRepairPrompt, REVIEW_DIFF_MAX_BYTES, blockCorrectionPrompt, HUMAN_BLOCK_REASONS, structurePrompt, hotspotPlanNote, hotspotBuildRule, reproPlanNote, unrunnableValidateNote, contextPackNote, docsPrompt, ciFailurePrompt, ciUnavailablePrompt, precheckFailurePrompt, contextRestartPrompt, turnBudgetWrapupPrompt, syncChecks, GROUPING_SYSTEM, enumeratingPlanNote, enumeratingBuildRule, invariantsPlanNote, invariantsBuildRule, missingEntriesPrompt, sequencePrompt, sequenceSyncNote, sequenceSyncPrompt, fixSessionPrompt, postMergeFailurePrompt, duplicateExportsPrompt, migrationGeneratorPrompt, i18nCopiesPrompt } from "./prompts.mjs";
 import { postMergeCommands } from "./postmerge.mjs";
 import { guardAfterMerge, withHistoryRows } from "./guards.mjs";
 import { loadGuards, selectGuards, runGuards, supersededIds, supersessionComment } from "./guardgate.mjs";
@@ -156,6 +156,9 @@ export function classifyBlock(result, issue) {
   }
   if (b.kind === "human") {
     const remainder = (Array.isArray(b.remainder) ? b.remainder : []).filter((x) => x && typeof x.title === "string" && x.title.trim() && typeof x.body === "string").slice(0, MAX_SUBISSUES).map((x) => ({ title: x.title.trim(), body: x.body })); // #4730
+    if (b.why === "product-decision" && describesUnrunnableCommand(`${result?.summary ?? ""} ${b.reason ?? ""} ${b.detail ?? ""}`)) { // #4857
+      return { kind: "untyped", problem: "an unrunnable validate command is an environment defect, never a product-decision: run an equivalent through the repo's toolchain and record it as a substitute-validate amendment" };
+    }
     return HUMAN_BLOCK_REASONS.includes(b.why) ? { kind: "human", why: b.why, ...(remainder.length ? { remainder } : {}) }
       : { kind: "untyped", problem: `"${String(b.why ?? "").slice(0, 80)}" is not a human-only reason (${HUMAN_BLOCK_REASONS.join(", ")})` };
   }
@@ -202,6 +205,7 @@ export function isProtectedLaneBranch(b, { issue, lane = null, branches = {}, de
  * @param {"off"|"prefer"} [o.reproTest] forge.yaml lean.repro_test (#4271): prefer (default) freezes a red-green repro_test on bug lanes; off is today's contract
  * @param {object} [o.refactorModule] refactor:split step module (default ./refactor.mjs; injectable for tests, #4211)
  * @param {number} [o.splitMaxLines] refactor:split moved-line budget per PR (default 4000); the rest becomes a chained issue (#4211)
+ * @param {object} [o.testRunners] forge.yaml verification.test_runners (#4857): {path prefix: runner command prefix}
  * @param {string} [o.toolchainOverride] forge.yaml env.toolchain: "<pm>@<x.y.z>" or "off" (#4163)
  * @param {string} [o.envSetup]      forge.yaml env.setup: run once per fresh worktree before the builder (#4163)
  * @param {string} [o.laneInstructions] forge.yaml engine.lane_instructions (#4395): repo-relative file appended to fresh sessions instead of CLAUDE.md
@@ -217,7 +221,7 @@ export function isProtectedLaneBranch(b, { issue, lane = null, branches = {}, de
  */
 export async function runCore(o) {
   const { issue, repo, lane: requestedLane = null, laneOverride = false, branches = {}, cwd, dir, io, builderModel = null, reviewerModel = DEFAULT_REVIEWER_MODEL, fixModel = null,
-    toolchainOverride = null, envSetup = null, ciMaxMinutes = 360, conformance = "shadow", conformanceKinds = null, conformanceMutation = "off", reviewIncomplete = "needs-human", reproTest = "prefer", closeParent = false, mergeWait = "required", maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES, cliIdleMinutes = 15, cliMaxMinutes = 180, cliBusyMinutes = 45, contextCeilingTokens = 120000, turnBudgets = null, laneLimits = null, maxMergeRetries = 5, sessionLimitMaxWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS, onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
+    toolchainOverride = null, testRunners = null, envSetup = null, ciMaxMinutes = 360, conformance = "shadow", conformanceKinds = null, conformanceMutation = "off", reviewIncomplete = "needs-human", reproTest = "prefer", closeParent = false, mergeWait = "required", maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES, cliIdleMinutes = 15, cliMaxMinutes = 180, cliBusyMinutes = 45, contextCeilingTokens = 120000, turnBudgets = null, laneLimits = null, maxMergeRetries = 5, sessionLimitMaxWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS, onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
   const now = io.now ?? (() => Date.now());
   const vcfg = { ...parseVerify({}), ...(o.verify ?? {}) };
   const learnedCommands = (Array.isArray(o.precheck?.commands) ? o.precheck.commands : []).map((c) => String(c ?? "").trim()).filter(Boolean);
@@ -640,7 +644,7 @@ export async function runCore(o) {
     } catch (e) { throw Object.assign(e, { laneCode: OUTCOME_CODES.CI_DCO }); }
   };
   const gitPush = async (args) => {
-    if (!args.includes("--delete")) { await untrackToolState({ git, base, ev }); await signOffUnpushed(); } // #4590: never push .forge-lean/ or tool caches this branch added
+    if (!args.includes("--delete")) { await untrackToolState({ git, base, ev, keep: await keepPaths() }); await signOffUnpushed(); } // #4590: never push .forge-lean/ or tool caches this branch added
     try { return await retrying(() => git(args), { transient: PUSH_TRANSIENT_RE, permanent: PUSH_PERMANENT_RE, attempts: 4, sleep: sleepFn, random }); }
     catch (e) {
       if (e?.transientExhausted) { e.deferCode = OUTCOME_CODES.PUSH_TRANSIENT; e.deferDetail = `git push kept failing transiently after 4 attempts: ${String(e?.stderr ?? e?.message ?? e).slice(0, 300)}`; }
@@ -825,6 +829,7 @@ export async function runCore(o) {
     const digest = budgetDigest({ size, budget, used: tb.record().build, digest: res?.status === "budget-exceeded" ? res.digest : null, stat: facts.stat, check: facts.check });
     throw Object.assign(new Error(digest), { laneCode: OUTCOME_CODES.BUDGET_EXCEEDED });
   }
+  const keepPaths = async () => ((await readContract())?.deliverables ?? []).map((d) => d?.path).filter((x) => typeof x === "string"); // #4959: deliverables are never untracked as generated files
   const readContract = async () => { try { const j = JSON.parse(await io.fs.read(`${wt}/${CONTRACT_FILE}`)); return j && typeof j === "object" ? j : null; } catch { return null; } };
   const readResult = async () => { try { const j = JSON.parse(await io.fs.read(`${wt}/${RESULT_FILE}`)); return j && typeof j === "object" ? j : null; } catch { return null; } };
   /** Containers/volumes the builder reported in result.json `resources` go into the ledger, so teardown removes them. */
@@ -1546,7 +1551,7 @@ export async function runCore(o) {
       enumList = io.enumeratingTests ? ((await io.enumeratingTests({ cwd: wt, paths: namedPaths(iss.body ?? "") }).catch(() => null)) ?? []) : [];
       facts = await factsPath([wt, cwd], io.fs?.exists);
       let ctxPack = frozen || lightTry ? null : await contextPackStep();
-      const planPrompt = () => builderPlanPrompt(issue, tcOpts()) + hotspotPlanNote(hotFacts) + enumeratingPlanNote(enumList) + invariantsPlanNote(vcfg.invariants) + reproPlanNote(reproOn()) + explorePlanRule(exploreCfg) + (ctxCfg.mode === "on" ? contextPackNote(ctxPack) : "");
+      const planPrompt = () => builderPlanPrompt(issue, tcOpts()) + hotspotPlanNote(hotFacts) + enumeratingPlanNote(enumList) + invariantsPlanNote(vcfg.invariants) + reproPlanNote(reproOn()) + unrunnableValidateNote(testRunners) + explorePlanRule(exploreCfg) + (ctxCfg.mode === "on" ? contextPackNote(ctxPack) : "");
       let lightDone = false, lightCommits = false;
       if (lightTry) {
         liveKeys = ["implementation"]; stage = "implement"; phaseLedger.enter("implement");
@@ -1622,8 +1627,8 @@ export async function runCore(o) {
         let vc = validateContract(contract, issueText, { repro: reproOn() });
         const missed = await preflightValidates(contract); // #4328: validate commands the host cannot run share the one correction
         let misses = missed;
-        if ((!vc.ok || missed.length) && sessionId) {
-          const problems = [...vc.problems, ...preflightProblems(missed)];
+        if ((!vc.ok || missed.length || testRunnerProblems(contract, testRunners).length) && sessionId) {
+          const problems = [...vc.problems, ...preflightProblems(missed), ...testRunnerProblems(contract, testRunners)];
           T.decisions.push(`Contract rejected (${problems[0]}); resumed once`);
           await builder(++attemptN, contractCorrectionPrompt(problems), sessionId, false, planPrompt, { trigger: "contract_correction" });
           contract = dropScope(await readContract());
@@ -1876,6 +1881,7 @@ export async function runCore(o) {
     }
     { const sq = await sequenceHandoff("hand-off"); if (sq?.done) return sq.done; }
     /** #4406: same-app duplicate exports (verify.duplicate_exports): one "rename or reuse" round, then an anomaly. True when a fix round ran. */
+    let engineWhy = null; // the reason an amendment gets when the engine demanded the change (a blank builder why is not its fault)
     async function duplicateGate(trigger) {
       if (!io.duplicateExports || isSplit || vcfg.duplicateExports === false) return false;
       const found = async () => (await io.duplicateExports({ cwd: wt, base }).catch(() => null)) ?? [];
@@ -1884,6 +1890,7 @@ export async function runCore(o) {
         const text = dups.map((d) => `duplicate export \`${d.symbol}\`: ${d.path} and ${(d.others ?? []).join(", ")}`).join("\n");
         ev({ event: "DUPLICATE_EXPORTS", trigger, count: dups.length });
         T.decisions.push(`Duplicate export(s) (${trigger}): ${dups.slice(0, 5).map((d) => `${d.symbol} in ${d.path} vs ${(d.others ?? []).join(", ")}`).join("; ")}; builder resumed once`);
+        engineWhy = `engine-demanded rename: duplicate export(s) ${dups.slice(0, 5).map((d) => d.symbol).join(", ")} (${trigger})`;
         await fixRound("duplicate", duplicateExportsPrompt(dups, vcfg.mode), [], "duplicate", text);
         result = (await readResult()) ?? result;
         files = await changedFiles();
@@ -1975,7 +1982,7 @@ export async function runCore(o) {
     async function ciVerify(trigger) {
       let fixes = 0;
       for (;;) {
-        await untrackToolState({ git, base, ev }); // #4621: gitPush's untrack commit would move HEAD after `head` was read; do it first so head is the pushed tip
+        await untrackToolState({ git, base, ev, keep: await keepPaths() }); // #4621: gitPush's untrack commit would move HEAD after `head` was read; do it first so head is the pushed tip
         await signOffUnpushed(); // #4651: likewise the sign-off rewrite
         const head = String(await git(["rev-parse", "HEAD"])).trim();
         if (head === ciVerifiedHead || ciFellBack) return { fixes };
@@ -2081,10 +2088,11 @@ export async function runCore(o) {
       genPaths ??= (hotFacts ? hotFacts.generated_paths : light ? [] : (await hotspotsOf({ paths: [] }))?.generated_paths) ?? [];
       const wantsDecision = (Array.isArray(result?.amendments) ? result.amendments : []).some((x) => x?.kind === "decision");
       baseTree ??= wantsDecision ? String(await git(["ls-tree", "-r", "--name-only", base]).catch(() => "")).split("\n").filter(Boolean) : null;
+      const addedPaths = wantsDecision ? String(await git(["diff", "--name-only", "--diff-filter=A", `${base}...HEAD`]).catch(() => "")).split("\n").filter(Boolean) : [];
       const own = [...(Array.isArray(result?.amendments) ? result.amendments : []), ...impliedDocs];
       const ownKeys = new Set(own.map((x) => JSON.stringify(x)));
       const all = [...priorAmendments.filter((x) => !ownKeys.has(JSON.stringify(x))), ...own];
-      const a = applyAmendments(frozen, all, issueText, { generatedPaths: genPaths, baseFiles: baseTree?.length ? baseTree : null });
+      const a = applyAmendments(frozen, all, issueText, { generatedPaths: genPaths, baseFiles: baseTree?.length ? baseTree : null, addedPaths, defaultWhy: engineWhy });
       const sig = JSON.stringify(a.applied);
       if (a.applied.length && sig !== lastAmend) {
         lastAmend = sig;
@@ -2115,7 +2123,7 @@ export async function runCore(o) {
         await renew();
         const rr = await callRunner({ role: "reviewer", issue, cwd: wt, model: reviewerModel, resume: null, system: REVIEWER_SYSTEM, readOnly: true,
           prompt: repair ? reviewerRepairPrompt({ missing: d.missing ?? [], problems: d.failures.map((f) => f.detail), rows: first })
-            : reviewerPrompt({ issue: iss, comments: trustedComments, contract: effective, result, files, diff, stat, base, structure: structureLine, ignore: IGNORE }) });
+            : reviewerPrompt({ issue: iss, comments: trustedComments, contract: effective, result, files, diff, stat, base, structure: structureLine, ignore: IGNORE, investigationVerdict: investigationVerdict(await io.fs.read(`${wt}/.forge-lean/investigation.md`).catch(() => null)) }) });
         await renew();
         await attempt("review", ++reviewN, rr, null, "review");
         const parsed = parseReview(rr?.text);
@@ -2173,7 +2181,6 @@ export async function runCore(o) {
     }
     const verifierSection = () => { const n = renderVerifierNote(verifierRun); return n ? `\n\n${n}` : ""; };
     /** #4323: rerun once each validate command the builder recorded as failed, with the lane env; {[id]: {rc, output}} or null. */
-    function rerunFailedValidates(contract) { return phaseLedger.during("validate", () => rerunFailedValidatesRaw(contract)); }
     async function rerunFailedValidatesRaw(contract) {
       if (!io.runCommand) return null;
       const runs = Array.isArray(result?.validation) ? result.validation : [], out = {};
@@ -2195,6 +2202,20 @@ export async function runCore(o) {
       if (Object.keys(out).length) ev({ event: "VALIDATE_RERUN", runs: Object.entries(out).map(([id, x]) => ({ id, rc: x.rc })) });
       return out;
     }
+    /** #4979 SPEC-2: rerun the frozen command of every substituted validate, so precheck accepts a substitute only for a command that cannot run. */
+    async function rerunSubstitutedOriginals(contract) {
+      const out = {};
+      if (!io.runCommand) return out;
+      const env = laneEnv();
+      for (const v of contract.validate ?? []) {
+        if (!v.substituted?.from) continue;
+        let x;
+        try { x = await heavyStep("precheck", async () => (await runWithTimeoutRetry((timeoutMs) => io.runCommand({ command: String(v.substituted.from), cwd: wt, timeoutMs, env }), vcfg.precheckTimeoutSeconds * 1000)).r); } catch (e) { x = { rc: 127, output: String(e?.message ?? e) }; }
+        out[v.id] = { rc: Number.isInteger(x?.rc) ? x.rc : 1, output: String(x?.output ?? "") };
+      }
+      if (Object.keys(out).length) ev({ event: "SUBSTITUTE_RERUN", runs: Object.entries(out).map(([id, x]) => ({ id, rc: x.rc })) });
+      return out;
+    }
     /** #4693: select the guards this diff intersects and rerun their base test files; zero cost when none is selected. Best effort: an error skips the gate. */
     let guardSel = [], guardNoted = ""; let guardEv = null; // #4705: this pass's guard_run event, emitted by the caller once the added wall time is known
     async function guardGate(files) {
@@ -2204,7 +2225,7 @@ export async function runCore(o) {
         const picked = guards.length ? await selectGuards({ guards, files, git: (a) => git(a), base }) : { selected: [], mergeBase: null };
         sel = picked.selected; guardSel = sel;
         if (!sel.length) return [];
-        r = await runGuards({ selected: sel, mergeBase: picked.mergeBase, contract: effective, git: (a) => git(a), runCommand: (a) => io.runCommand(a), cwd: wt, env: laneEnv(), parallelism: Number(process.env.FORGE_HOST_PARALLELISM) || 2 });
+        r = await runGuards({ selected: sel, mergeBase: picked.mergeBase, contract: effective, guardCommand: vcfg.guardCommand, git: (a) => git(a), runCommand: (a) => io.runCommand(a), cwd: wt, env: laneEnv(), parallelism: Number(process.env.FORGE_HOST_PARALLELISM) || 2 });
       } catch (e) { T.anomalies.push(`Guard gate skipped: ${String(e?.message ?? e).split("\n")[0].slice(0, 160)}`); guardEv = { event: "guard_run", selected: sel.map((x) => x.guard.issue), ran: 0, broken: 0, skipped: 0, wall_ms: 0, error: true }; return []; }
       const note = `Guard gate selected ${sel.map((x) => `#${x.guard.issue} (${x.reason})`).join("; ")}${r.skipped.length ? `; skipped: ${r.skipped.join("; ")}` : ""}${r.failures.length && shadow ? "; shadow: would block" : ""}`;
       if (note !== guardNoted) { guardNoted = note; T.decisions.push(note); }
@@ -2235,15 +2256,18 @@ export async function runCore(o) {
       const ciVerified = remoteVerify && ciVerifiedHead !== null && ciVerifiedHead === gateHead;
       const hotspots = await hotspotsOf({ base, paths: files }); // #4502
       const gateT0 = now(); let validateMs = 0;
-      const [validateRuns, guardFailures] = await Promise.all([rerunFailedValidates(effective).finally(() => { validateMs = now() - gateT0; }), guardGate(files)]); // #4693: guards run beside the validate rerun
+      // #4693: guards run beside the validate rerun; SPEC-11: the substituted-original rerun shares the one validate phase
+      const validatePhase = phaseLedger.during("validate", async () => ({ runs: await rerunFailedValidatesRaw(effective), subs: await rerunSubstitutedOriginals(effective) })).finally(() => { validateMs = now() - gateT0; });
+      const [{ runs: validateRuns, subs: substitutedRuns }, guardFailures] = await Promise.all([validatePhase, guardGate(files)]);
       // #4705: only the part not hidden behind the validate rerun; 0 when the gate errored or skipped
       const guardRunMs = guardEv && !guardEv.error ? Math.max(0, now() - gateT0 - validateMs) : 0;
       guardAddedMs += guardRunMs;
       if (guardEv) ev({ ...guardEv, added_wall_ms: guardRunMs });
-      const repoHas = validateRuns && Object.keys(validateRuns).length ? repoTracks(String(await git(["ls-files"]).catch(() => "")).split("\n").map((x) => x.trim()).filter(Boolean)) : undefined;
+      const repoHas = (validateRuns && Object.keys(validateRuns).length) || Object.keys(substitutedRuns ?? {}).length ? repoTracks(String(await git(["ls-files"]).catch(() => "")).split("\n").map((x) => x.trim()).filter(Boolean)) : undefined;
       // #4626: post-deploy check ids resolve against the lane base's checks file or this PR's
       const checkIds = effective.requirements?.some((r) => r.disposition === "post-deploy") ? new Set(Object.keys(await checksAt(git, [base, "HEAD"], wt))) : null;
-      const pc = precheck({ contract: effective, result, changedFiles: files, ignore: IGNORE, ciVerified, hotspots, repro: await reproOf(effective), validateRuns, repoHas, frozen, checkIds, guardFailures, newOffKeys: await newOffKeysOf() });
+      const removedPaths = (effective.validate ?? []).some((v) => v.substituted) ? await removedPathsOf(git, base) : []; // #4990
+      const pc = precheck({ contract: effective, result, changedFiles: files, ignore: IGNORE, ciVerified, hotspots, repro: await reproOf(effective), validateRuns, repoHas, frozen, checkIds, guardFailures, newOffKeys: await newOffKeysOf(), substitutedRuns, removedPaths });
       // #4350: a scope-check validate stale only by amended deliverables is judged by the engine's scope gate instead
       if (pc.superseded?.length) {
         ev({ event: "VALIDATE_SUPERSEDED", runs: pc.superseded });

package/bin/lean/lean.test.mjs

@@ -15,7 +15,7 @@ import { parseVerify } from "./verify.mjs";
 import { worktreeFingerprint } from "./precheck.mjs";
 import { renderInvestigation, renderPlan, renderImplementation, renderReview, renderPrBody, renderTrajectory, renderStructure, renderContract, renderAmendments, parseAmendmentsComment, contractJson, parseContractComment, sanitizeMd, capComment, section, cell, NR, MAX_COMMENT_CHARS } from "./render.mjs";
 import { orchestrate, parseDeps, formatTable, pickNext } from "./orchestrate.mjs";
-import { REVIEWER_SYSTEM, REVIEW_RUBRIC, approxTokens, builderPlanPrompt, builderImplementPrompt, reviewerPrompt, decisionNote, hotspotPlanNote, hotspotBuildRule } from "./prompts.mjs";
+import { REVIEWER_SYSTEM, REVIEW_RUBRIC, approxTokens as rawTokens, FORGEDOCK_CLI, builderPlanPrompt, builderImplementPrompt, reviewerPrompt, investigationVerdict, decisionNote, hotspotPlanNote, hotspotBuildRule } from "./prompts.mjs";
 import { parseReview, unnamedEdges, structureNote, applyAmendments, validateContract, scopeText, DECISION_SOURCES } from "./conformance.mjs";
 import { mapRecord } from "../engine/telemetry-seam.mjs";
 import { readLog as readRepoLog } from "../engine/runlog.mjs";
@@ -30,6 +30,10 @@ import { readAdmission, readConformanceMode, readReviewIncomplete, readEnvConfig
 import { prepareToolchain } from "./toolchain.mjs";
 import { isExternalKill } from "./hostkill.mjs";
 import { runFromCli, orchestrateFromCli, ENGINE_PATHS, readMaintenance } from "../engine-cli.mjs";
+// #4969: prompt budgets are measured with the install root as a fixed placeholder, so they never depend on the checkout location
+const INSTALL_ROOT = FORGEDOCK_CLI.replace(/[\\/]bin[\\/]forgedock\.mjs$/, "");
+const INSTALL_PATH_RE = /\S*?[\\/](?=bin[\\/][\w.\\/-]+\.mjs)/g;
+const approxTokens = (s) => rawTokens(String(s).replaceAll(INSTALL_ROOT, "<root>").replace(INSTALL_PATH_RE, "<root>/"));
 // orchestrateFromCli opens the host lane registry (#4191): keep it in a temp dir.
 process.env.FORGEDOCK_SCHED_DIR = tmpDir("lean-sched-");
 
@@ -573,6 +577,14 @@ describe("core work-on", () => {
     assert.ok(w.comments.some((c) => /FORGE:DECOMPOSED/.test(c) && /size: 40 files, 4000 lines .* oversize yes/.test(c)));
   });
 
+  it("#4857 a product-decision block over an unrunnable validate is untyped (one correction resume), a real one stays human", () => {
+    const u = classifyBlock({ summary: "V2 cannot run: poetry found no pyproject at the repo root", block: { kind: "human", why: "product-decision" } }, 1);
+    assert.equal(u.kind, "untyped");
+    assert.match(u.problem, /substitute-validate/);
+    assert.equal(classifyBlock({ summary: "needs a pricing decision", block: { kind: "human", why: "product-decision" } }, 1).kind, "human");
+    assert.equal(classifyBlock({ summary: "V1 needs the prod key", block: { kind: "human", why: "credentials" } }, 1).kind, "human");
+  });
+
   it("#4385 split siblings that declare a shared hub file are serialised (chained, no duplicate transitive edge); disjoint or undeclared files stay parallel", () => {
     const hub = ["src/domain/index.ts", "./src/domain/events.ts"];
     const BIG = { files: 40, lines: 2000 }; // #4396: shared or undeclared files are admitted only over the size budget
@@ -1354,6 +1366,24 @@ describe("conformance shadow mode (the default)", () => {
       assert.match(nhBody(w), /timed out \(exit 124\) even after one longer retry/);
     }
   });
+  it("#4979 the engine reruns a substituted validate's frozen command: a runnable failing one blocks, an unrunnable one lets the substitute stand", async () => {
+    const amendments = [{ kind: "substitute-validate", validate: "V1", command: "node --test test/foo2.test.js", why: "the frozen path does not exist" }];
+    const validation = [{ id: "V1", command: "node --test test/foo2.test.js", exit: 0 }];
+    const lane = (frozenOut) => {
+      const w = world({ validation, amendments, resumeValidation: validation, resumeAmendments: amendments }), ran = [];
+      w.io.runCommand = async (a) => { ran.push(a); return a.command === "node --test test/foo.test.js" ? frozenOut : { rc: 0, output: "" }; };
+      return { w, ran };
+    };
+    const dir = tmpDir("subst-");
+    const bad = lane({ rc: 1, output: "not ok 1 - foo handles null\nAssertionError: expected 1" });
+    const rb = await run(bad.w, { conformance: "enforce", dir });
+    assert.equal(rb.terminalReason, "needs-human"); assert.equal(bad.w.merges.length, 0);
+    assert.match(nhBody(bad.w), /frozen command runs and fails \(exit 1\)/);
+    assert.ok(bad.ran.some((a) => a.command === "node --test test/foo.test.js" && a.cwd === WT && a.env), "the frozen command is rerun in the worktree with the lane env");
+    assert.deepEqual(readLog(dir, 7).filter((e) => e.event === "SUBSTITUTE_RERUN").map((e) => e.runs), [[{ id: "V1", rc: 1 }], [{ id: "V1", rc: 1 }]]);
+    const good = lane({ rc: 1, output: "no tests ran: no test files matched test/foo.test.js" });
+    assert.equal((await run(good.w, { conformance: "enforce" })).terminalReason, "merged");
+  });
   it("#4323 a rerun that fails for a repo reason stays conformance.unimplemented; one that passes merges", async () => {
     const v = [{ id: "V1", command: "node --test test/foo.test.js", exit: 1 }];
     const w = world({ validation: v, resumeValidation: v });
@@ -1784,7 +1814,7 @@ describe("hotspot prevention (forge#4195): plan facts, build rule, unexempted gr
     const plan = builderPlanPrompt(7) + hotspotPlanNote(facts([HOT, { ...HOT, path: "a/b.py" }, { ...HOT, path: "c/d.py" }]));
     // 1850: #4404 (verify out_of_band) and #4396 (split size rule) grew the plan prompt to ~1803 tokens on CI paths; 1900: #4589 (check timeout is not a block, one block-rule line). 2050: #4724 (deferred-row bucket rule).
     assert.ok(approxTokens(plan) <= 2150, `plan prompt with hotspots is ${approxTokens(plan)} tokens`);
-    assert.ok(approxTokens(builderImplementPrompt() + hotspotBuildRule(facts([]))) <= 1650); // 1600: #4591 (never hand-name migration files) and #4596 (i18n translate rule), one line each; 1650: #4726 (e2e rule)
+    assert.ok(approxTokens(builderImplementPrompt() + hotspotBuildRule(facts([]))) <= 1650, `implement prompt with the hotspot rule is ${approxTokens(builderImplementPrompt() + hotspotBuildRule(facts([])))} of 1650 tokens`); // 1600: #4591 (never hand-name migration files) and #4596 (i18n translate rule), one line each; 1650: #4726 (e2e rule)
   });
 
   it("#4519 generated_paths: both prompts name the globs (even with the gate off), and an amendment adding one blocks", async () => {
@@ -2220,7 +2250,7 @@ describe("comment templates", () => {
   it("plan and implement prompts carry the stage templates and the contract schema within budget", () => {
     const plan = builderPlanPrompt(7), impl = builderImplementPrompt();
     assert.ok(approxTokens(plan) <= 2050, `plan prompt is ${approxTokens(plan)} tokens`); // 2050: #4769 (activation-row rule); 2000: #4730 (owner-step remainder); 1950: #4724 (deferred-row bucket rule)
-    assert.ok(approxTokens(impl) <= 1650, `implement prompt is ${approxTokens(impl)} tokens`); // 1650: #4726 e2e rule; 1550: #4596 i18n translate rule
+    assert.ok(approxTokens(impl) <= 1650, `implement prompt is ${approxTokens(impl)} of 1650 tokens`); // 1650: #4726 e2e rule; 1550: #4596 i18n translate rule
     for (const h of ["### What Was Claimed", "### What We Found", "### Root Cause", "### Affected Files", "### Sibling Sweep", "### History", "### Recommendation", "### Related Issues",
       "investigation.md", "contract.json", "PLANNING ONLY", '"requirements"', '"deliverables"', '"preserve"', '"validate"', "verbatim", "defer", "post-deploy"]) assert.ok(plan.includes(h), h);
     for (const h of ["### Approach", "### Changes", "### Acceptance Criteria Status", "### Verification", "### Notes", "implementation.md", "result.json",
@@ -4144,7 +4174,7 @@ describe("batch robustness (#4112-#4115)", () => {
     const prior = { body: `<!-- FORGE:AMENDMENT -->\n${renderAmendments([{ kind: "supersedes", target: "#4785", why: sup.why }], {}, { contract: contractHash(contractJson(CONTRACT)), amendments: [sup] })}`, author_association: "OWNER", user: { type: "User", login: "op" } };
     const dir = tmpDir("guard-recover-");
     const w = world({ prList: [], remote: "abc\trefs/heads/feat/issue-7-lean", issueComments: [frozenComment(), prior], baseFiles: { ":src/foo.js": "old" } });
-    w.io.runCommand = async () => ({ rc: 1, output: "guard test failed" });
+    w.io.runCommand = async (a) => ({ rc: String(a?.cwd).includes("guardbase-") ? 0 : 1, output: "guard test failed" }); // #4968: the base tree passes, so the lane tree is what broke
     await run(w, { dir, worktreeRoot: dir, recover: { code: "ci.red", attempt: 1 }, loadGuards: async () => [mkGuard(4785), mkGuard(9)] });
     const text = JSON.stringify([w.comments, w.calls.filter((c) => c[0] === "runner").map((c) => c[4])]);
     assert.match(text, /conformance\.guard_broken.{0,400}?guard\\":\\"#9\\"/, "precheck reports #9 as guard_broken");
@@ -6780,7 +6810,8 @@ describe("#4395 lane profile", () => {
       assert.match(p, /Issue independent read-only calls \(reads, greps, git log\/blame, gh\) in the same turn or one shell call\./);
       assert.match(p, /Read each file's ranges once .* and keep notes; don't re-read it\./);
     }
-    assert.ok(approxTokens(builderImplementPrompt()) <= 1650 && approxTokens(builderPlanPrompt(7)) <= 2050);
+    assert.ok(approxTokens(builderImplementPrompt()) <= 1650, `implement prompt is ${approxTokens(builderImplementPrompt())} of 1650 tokens`);
+    assert.ok(approxTokens(builderPlanPrompt(7)) <= 2050, `plan prompt is ${approxTokens(builderPlanPrompt(7))} of 2050 tokens`);
   });
 
   it("runCliBackendAsync reports the first stream turn's context as baselineTokens; makeLeanRunner drops it on resume", async () => {
@@ -7068,3 +7099,33 @@ describe("mutation check (engine.conformance_mutation, #4913)", () => {
     assert.equal(r.code, "conformance.mutation_survived"); assert.equal(w.merges.length, 0);
   });
 });
+
+describe("investigation verdict for the reviewer (#4959)", () => {
+  it("investigationVerdict reads the Verdict line", () => {
+    assert.equal(investigationVerdict("**Verdict**: validated\n**Confidence**: high"), "VALIDATED");
+    assert.equal(investigationVerdict("**Verdict**: CONFIRMED"), "CONFIRMED");
+    assert.equal(investigationVerdict("no verdict"), null);
+    assert.equal(investigationVerdict(null), null);
+  });
+  it("reviewerPrompt carries the verdict block and rubric rule, and is unchanged without it", () => {
+    const args = { issue: { number: 7, title: "t", body: "b" }, contract: {}, result: {}, files: [], diff: "x" };
+    assert.ok(reviewerPrompt({ ...args, investigationVerdict: "VALIDATED" }).includes("<investigation_verdict>VALIDATED</investigation_verdict>"));
+    assert.ok(!reviewerPrompt(args).includes("</investigation_verdict>"));
+    assert.ok(reviewerPrompt({ ...args, investigationVerdict: "VALIDATED" }).includes("is not a failing row"));
+    assert.ok(!REVIEW_RUBRIC.includes("is not a failing row"));
+  });
+});
+
+describe("prompt budgets (#4969)", () => {
+  it("do not depend on the install path length", () => {
+    const impl = builderImplementPrompt();
+    assert.ok(impl.includes(INSTALL_ROOT), "the implement prompt names files under the install root");
+    const deep = `/${"very-long-checkout-directory/".repeat(10)}forgedock`;
+    assert.ok(deep.length >= 200);
+    const moved = impl.replaceAll(INSTALL_ROOT, deep);
+    assert.notEqual(moved, impl);
+    assert.equal(approxTokens(moved), approxTokens(impl));
+    assert.equal(approxTokens(impl.replaceAll(INSTALL_ROOT, "C:\\fd")), approxTokens(impl));
+    assert.ok(approxTokens(moved) <= 1650, `implement prompt from a deep checkout is ${approxTokens(moved)} of 1650 tokens`);
+  });
+});

package/bin/lean/orchestrate-children.test.mjs

@@ -0,0 +1,83 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4965: the scheduler pass that adds epic and late children to a running batch.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { orchestrate } from "./orchestrate.mjs";
+
+const merged = { terminalReason: "merged" };
+const until = async (f, ms = 3000) => { const t = Date.now(); while (!f()) { if (Date.now() - t > ms) throw new Error("timeout"); await new Promise((r) => setTimeout(r, 5)); } };
+
+/** A batch with epic #1 running behind a gate; `list` is what the one list call returns. */
+async function run({ mode, list, pollS = 0.001, elsewhere = [], epics = [], bodies = {}, extra = {} }) {
+  const started = [], log = [], decisions = [];
+  let calls = 0, open;
+  const g = new Promise((r) => { open = r; });
+  const done = orchestrate({ issues: [1], parallel: 3, pollMs: 5, trusted: () => true, readBody: async (n) => bodies[n] ?? "", onUpdate: (r) => log.push(r), decide: (d) => decisions.push(d),
+    autoChildren: { mode, pollS, epics }, getChildren: async () => { calls++; return { list: typeof list === "function" ? list() : list, elsewhere }; },
+    runOne: async (n) => { started.push(n); if (n === 1) await g; return merged; }, ...extra });
+  return { started, log, decisions, calls: () => calls, open, done };
+}
+const L = (...kids) => [{ number: 1, body: "", labels: [] }, ...kids.map((n) => ({ number: n, body: "**Parent**: #1", labels: [] }))];
+
+describe("#4965 auto_add_children", () => {
+  it("epic: adds open children of a batch issue, one decision and one added row listing them", async () => {
+    const r = await run({ mode: "epic", list: L(2, 3), bodies: { 3: "Blocked by #2" } });
+    await until(() => r.started.includes(2) && r.started.includes(3));
+    r.open(); await r.done;
+    const added = r.log.filter((x) => x.outcome === "added");
+    assert.equal(added.length, 1);
+    assert.match(added[0].detail, /#2, #3; edges #3 blocked by #2/);
+    assert.equal(r.decisions.filter((d) => /auto_add_children/.test(d.what)).length, 1);
+    assert.ok(r.started.indexOf(2) < r.started.indexOf(3));
+  });
+  it("decomposed (default) and off never call getChildren", async () => {
+    for (const mode of ["decomposed", "off"]) {
+      const r = await run({ mode, list: L(2) });
+      await new Promise((x) => setTimeout(x, 40));
+      r.open(); await r.done;
+      assert.equal(r.calls(), 0, mode);
+      assert.deepEqual(r.started, [1]);
+    }
+  });
+  it("needs-human children and children live in another batch are not added", async () => {
+    const list = [...L(2, 3), { number: 4, body: "**Parent**: #1", labels: [{ name: "needs-human" }] }];
+    const r = await run({ mode: "all", list, elsewhere: [3] });
+    await until(() => r.started.includes(2));
+    await new Promise((x) => setTimeout(x, 40));
+    r.open(); await r.done;
+    assert.deepEqual([...r.started].sort(), [1, 2]);
+  });
+  it("an --epic root outside the batch adds its children; late children join on a later pass", async () => {
+    let list = [{ number: 50, body: "", labels: [] }, { number: 51, body: "**Parent**: #50", labels: [] }];
+    const r = await run({ mode: "epic", epics: [50], list: () => list });
+    await until(() => r.started.includes(51));
+    list = [...list, { number: 52, body: "**Parent**: #50", labels: [] }];
+    await until(() => r.started.includes(52));
+    r.open(); await r.done;
+    assert.equal(r.log.filter((x) => x.outcome === "added").length, 2);
+  });
+  it("a failing child scan is reported once as a decision, retried, and the batch still runs", async () => {
+    let calls = 0;
+    const r = await run({ mode: "epic", list: L(), extra: { getChildren: async () => { calls++; throw new Error("Unknown JSON field"); } } });
+    await new Promise((x) => setTimeout(x, 60));
+    r.open(); await r.done;
+    assert.ok(calls >= 2, "retried");
+    assert.equal(r.decisions.filter((d) => /child scan failed/.test(d.what)).length, 1);
+    assert.deepEqual(r.started, [1]);
+  });
+  it("scans at most once per poll window: one list call per pass", async () => {
+    const r = await run({ mode: "epic", list: L(), pollS: 3600 });
+    await new Promise((x) => setTimeout(x, 80));
+    r.open(); await r.done;
+    assert.equal(r.calls(), 1);
+  });
+  it("a decomposed lane's sub-issues join in decomposed|epic|all, not in off", async () => {
+    for (const [mode, joins] of [["decomposed", true], ["epic", true], ["all", true], ["off", false]]) {
+      const started = [];
+      await orchestrate({ issues: [1], parallel: 3, pollMs: 5, readBody: async () => "", autoChildren: { mode, pollS: 3600 }, getChildren: async () => ({ list: [], elsewhere: [] }),
+        runOne: async (n) => { started.push(n); return n === 1 ? { terminalReason: "decomposed", subissues: [2] } : merged; } });
+      assert.equal(started.includes(2), joins, mode);
+    }
+  });
+});