forgedock 1.42.0 → 1.43.1

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);
+    }
+  });
+});

package/bin/lean/orchestrate.mjs

@@ -19,13 +19,16 @@
  * A seam calls `onLive()` before it waits on a live lane (#4504); an adopt that resolves first is settled (or requeued on null)
  * before scheduling, so a live lane does not hold up the others.
  * `deferred` is a scheduling fact, not an end: each typed code is requeued with its retry-at (`deferPolicy`), a usage
- * limit holds admissions for that account until its reset, and deferrals other than a busy resource (`host.busy`,
- * `sandbox.capacity`, #4528; `sandbox.unreachable`, #4788) stop after `maxDeferrals`.
+ * limit holds admissions for that account until its reset, and deferrals other than a wait (`host.busy`,
+ * `sandbox.capacity`, #4528; `sandbox.unreachable`, #4788; `rate_limited`, #4784) stop after `maxDeferrals`.
  * Usage-limit holds (#4190) are keyed by backend identity in `limits` (the host store, shared by every batch on the
  * host; in memory when absent): admission checks the hold of `identity()`, the account the next lane would use. While held, the
  * batch re-reads the store every `pollMs` (#4446), so `forgedock limits clear` admits on the next poll, not at the reset. An `engine-error` is
  * relaunched once; `breaker` ({errors, window_min}) stops admissions after a burst and lets running lanes finish, the
  * rest stay pending (outcome `held`) for a resume. `getParallel()` is read on every pass, so K can change live.
+ * `getChildren()` + `autoChildren {mode, pollS, epics}` (#4965, `orchestration.auto_add_children`): with mode `epic`|`all`, at most once per `pollS`
+ * it reads one `{list, elsewhere}` and adds the open children (`**Parent**: #P`, sub-issues) of every batch issue and `epics` through the same
+ * path as `getAdded` (one decision and one `added` row listing the edges); mode `off` also stops the decomposed-lane join.
  * `getAdded()` (#4408, `forgedock orchestrate --add`) is read on every pass too: issues it returns that are not in the batch
  * join it through `addIssues` (the still-pending issues' `Depends on` are re-read first, so edges hold both ways), with one
  * batch decision and one `added` row; while it is set, lanes running with an empty queue still wake every `pollMs`.
@@ -112,13 +115,14 @@ import { formatParkedLine, postDeployOnly } from "./prefilter.mjs";
 import { laneSize, SIZES } from "./budget.mjs";
 import { requeueKey, REQUEUABLE } from "./batch.mjs";
 import { makeCapWait } from "./capwait.mjs";
+import { joinsDecomposed, addsEpicChildren, selectChildren, edgeText, DEFAULT_POLL_S } from "./autochildren.mjs";
 
 // A dependency that finished like this no longer blocks its dependents.
 const SATISFIED = new Set(["merged", "invalid"]);
 const WATCH_EVERY_MS = 60_000; // #4595
 // Times one issue may be requeued behind a dependency before its dependency-open row is final.
 export const MAX_REQUEUES = 2;
-// Deferrals other than a busy resource (UNCAPPED_DEFERRALS) one issue may take before its deferred row is final.
+// Deferrals other than a wait (UNCAPPED_DEFERRALS, usage limit) one issue may take before its deferred row is final.
 export const DEFAULT_MAX_DEFERRALS = 3;
 // Relaunches of an issue whose lane ended engine-error.
 export const ENGINE_ERROR_RELAUNCHES = 1;
@@ -176,18 +180,19 @@ export function parseDeps(body, issue) {
 const posNum = (v) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? n : null; };
 
 /**
- * When to run a `deferred` issue again. `deferrals` counts this issue's earlier capped deferrals (not UNCAPPED_DEFERRALS).
+ * When to run a `deferred` issue again. `deferrals` counts this issue's earlier capped deferrals (not UNCAPPED_DEFERRALS or a usage limit).
  * @returns {{delayMs:number, host?:true, hold?:true} | {capped:true}}
  */
 export function deferPolicy(r, { now, deferrals = 0, maxDeferrals = DEFAULT_MAX_DEFERRALS }) {
   const code = r?.code ?? null;
   if (UNCAPPED_DEFERRALS.has(code)) return { delayMs: (posNum(r?.retryInSeconds) ?? HOST_BUSY_RETRY_S) * 1000, host: true };
-  const k = deferrals + 1;
-  if (k > maxDeferrals) return { capped: true };
+  // #4784: a usage limit is a known-time wait gated by the account hold, never capped.
   if (code === "rate_limited") {
     const at = posNum(r?.resetAtEpochMs) && r.resetAtEpochMs > now ? r.resetAtEpochMs : now + (posNum(r?.retryInSeconds) ?? RATE_LIMIT_FALLBACK_S) * 1000;
     return { delayMs: at - now, hold: true };
   }
+  const k = deferrals + 1;
+  if (k > maxDeferrals) return { capped: true };
   if (posNum(r?.retryInSeconds)) return { delayMs: r.retryInSeconds * 1000 };
   // lease-held: "leased by X until <ISO>"
   const until = /\buntil (\d{4}-\d\d-\d\dT[\d:.]+Z)/.exec(String(r?.detail ?? ""))?.[1];
@@ -248,7 +253,8 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   store = null, adopt = null, getParallel = null, getAdded = null, getRequeued = null, breaker = null, maxDeferrals = DEFAULT_MAX_DEFERRALS, sleep = cancellableSleep, pollMs = 5000,
   classify = null, maintenance = null, limits = null, identity = () => "default", batchId = null, drift = null, integration = null, sched = null, priorityOf = null, remote = null, beforeAdmit = null, preflight = null,
   recovery = null, decide = () => {}, conflicting = null, relabelNeedsHuman = null, onExit = null, issueLabels = null, issueState = null, getCancelled = null, getHeld = null, getBlocked = null, trusted = null, getGates = null, stopLane = null,
-  estimate = null, starveMs = DEFAULT_STARVE_MS, signal = null, dispatchCheck = null, syncParked = null, syncEveryMs = DEFAULT_SYNC_EVERY_MS, lifecycle = null }) {
+  estimate = null, starveMs = DEFAULT_STARVE_MS, signal = null, dispatchCheck = null, syncParked = null, syncEveryMs = DEFAULT_SYNC_EVERY_MS, lifecycle = null,
+  getChildren = null, autoChildren = null }) {
   const saved = store?.load?.() ?? null;
   const order = saved ? [...saved.order] : [];
   const set = new Set(order);
@@ -632,7 +638,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
         try { capGated = Number.isInteger(remote?.capacity?.()?.free); } catch { capGated = false; }
       }
       if (!pol.capped) {
-        if (!pol.host) deferrals.set(n, (deferrals.get(n) ?? 0) + 1);
+        if (!pol.host && !pol.hold) deferrals.set(n, (deferrals.get(n) ?? 0) + 1);
         // A usage limit is held per account; the hold, not a per-issue delay, gates the retry, so a lane on another
         // account runs it at once. If the hold cannot be recorded, the reset delay applies to this issue instead.
         let delayMs = pol.delayMs;
@@ -655,7 +661,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
         return;
       }
     }
-    if (row.outcome === "decomposed" && subs.length) {
+    if (row.outcome === "decomposed" && subs.length && joinsDecomposed(autoChildren?.mode ?? "decomposed")) {
       await addIssues(subs, { head: true, parent: n }); // #4409: on the batch's critical path by construction
       decided({ issue: n, what: `added sub-issues ${subs.map((d) => `#${d}`).join(", ")} to the batch; dependents wait on them`, why: "the builder decomposed the issue",
         alternative: "end the batch row decomposed and let dependents wait for a later batch" });
@@ -847,11 +853,12 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
 
   // #4408: issues added to the running batch; returns how many joined. Re-reading the cumulative list is a no-op.
   const drainAdds = async () => {
-    if (!getAdded) return 0;
+    const kids = await drainChildren();
+    if (!getAdded) return kids;
     let got = [];
     try { got = getAdded() ?? []; } catch { got = []; }
     const fresh = [...new Set((Array.isArray(got) ? got : []).filter((n) => Number.isSafeInteger(n) && n > 0 && !set.has(n)))];
-    if (!fresh.length) return 0;
+    if (!fresh.length) return kids;
     // An edge an operator wrote into a pending issue after the batch started (it waits on an added issue) holds too.
     for (const n of pending) {
       let body;
@@ -864,6 +871,38 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     const list = fresh.map((n) => `#${n}`).join(", ");
     decided({ issue: null, what: `added ${list} to the batch (forgedock orchestrate --add)`, why: "operator request", alternative: "start a second batch" });
     update({ issue: null, outcome: "added", detail: list });
+    return fresh.length + kids;
+  };
+  // #4965: epic and late children (`orchestration.auto_add_children` epic|all): at most one `getChildren()` list call per poll window.
+  let nextChildScan = 0, childScanFailed = false;
+  const drainChildren = async () => {
+    if (!getChildren || !addsEpicChildren(autoChildren?.mode)) return 0;
+    const t = now();
+    if (t < nextChildScan) return 0;
+    nextChildScan = t + Math.max(0, autoChildren.pollS ?? DEFAULT_POLL_S) * 1000;
+    let list, elsewhere;
+    try { ({ list, elsewhere } = await getChildren()); } catch (e) {
+      if (!childScanFailed) { childScanFailed = true; decided({ issue: null, what: `auto_add_children: child scan failed (${firstLine(e?.message ?? e)}); retried every ${autoChildren.pollS ?? DEFAULT_POLL_S}s`, why: "the open-issue list could not be read", alternative: "add the children by hand with forgedock orchestrate --add" }); }
+      return 0;
+    }
+    childScanFailed = false;
+    const fresh = selectChildren({ list, roots: [...set, ...(autoChildren.epics ?? [])], skip: [...set, ...(elsewhere ?? [])] })
+      .filter((n) => { try { return !(reg?.holder && reg.holder(entryOf(n)) != null); } catch { return true; } });
+    if (!fresh.length) return 0;
+    for (const n of pending) {
+      let body;
+      try { body = await readBody(n); } catch { continue; }
+      if (drift?.holds) bodies.set(n, body);
+      deps.set(n, [...new Set([...(deps.get(n) ?? []), ...(await declared(n, body))])]);
+    }
+    await addIssues(fresh);
+    save();
+    const list2 = fresh.map((n) => `#${n}`).join(", ");
+    const created = fresh.flatMap((n) => edges(n).map((d) => ({ from: n, to: d })));
+    for (const n of pending) if (!fresh.includes(n)) for (const d of edges(n)) if (fresh.includes(d)) created.push({ from: n, to: d });
+    const detail = created.length ? `${list2}; edges ${edgeText(created)}` : list2;
+    decided({ issue: null, what: `added ${list2} to the batch (orchestration.auto_add_children: ${autoChildren.mode})${created.length ? `; edges ${edgeText(created)}` : ""}`, why: "open children of a batch issue or epic", alternative: "add them by hand with forgedock orchestrate --add" });
+    update({ issue: null, outcome: "added", detail });
     return fresh.length;
   };
   // #4550: `--requeue` entries (batch `requeue` file) not applied yet: a terminal issue and the dependents skipped behind it
@@ -1163,7 +1202,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
       if (holdUntil && pending.length) wake = Math.min(wake ?? pollMs, pollMs); // #4446: a cleared hold (forgedock limits clear) admits on the next poll
       if ((getParallel || getHeld) && pending.length) wake = Math.min(wake ?? pollMs, pollMs);
       if (offered.size && pending.length) wake = Math.min(wake ?? pollMs, pollMs); // a slot another batch frees
-      if ((getAdded || getRequeued) && running.size) wake = Math.min(wake ?? pollMs, pollMs); // #4408/#4550: an add or requeue while only lanes run
+      if ((getAdded || getRequeued || (getChildren && addsEpicChildren(autoChildren?.mode))) && running.size) wake = Math.min(wake ?? pollMs, pollMs); // #4408/#4550: an add or requeue while only lanes run
       if ((pfAll || pfRemote) && pending.length) wake = Math.min(wake ?? pollMs, pollMs); // #4866
       if (getBlocked && pending.length && blockedHit.size) wake = Math.min(wake ?? pollMs, pollMs); // #4773: a removed label releases on the next tick
       if (getHeld && running.size) wake = Math.min(wake ?? pollMs, pollMs); // #4592: a release while only lanes run

package/bin/lean/postmerge.mjs

@@ -15,6 +15,8 @@ import { exportNames, isTestPath } from "./enumerating.mjs";
 const SOURCE_RE = /\.(?:[cm]?[jt]sx?|py)$/;
 const SKIP_RE = /(?:^|\/)(?:node_modules|vendor|dist|build|coverage)\//;
 const MANIFESTS = ["package.json", "pyproject.toml", "setup.py", "go.mod", "Cargo.toml"];
+// entry points a standalone script defines by convention: never a shared export
+const ENTRY_NAMES = new Set(["main", "cli"]);
 const MIN_NAME = 3, MAX_NAMES = 50, CONVENTION = 3;
 const lines = (s) => String(s ?? "").split("\n").map((x) => x.trim()).filter(Boolean);
 const out = (git) => async (args) => { try { return String(await git(args)); } catch { return ""; } };
@@ -68,13 +70,14 @@ export async function duplicateExports({ git, cwd, base }) {
     let names = 0;
     for (const f of changed) {
       const was = new Set(added.has(f) ? [] : declaredExports(await g(["show", `${base}:${f}`]), f));
-      const fresh = declaredExports(read(f), f).filter((n) => !was.has(n) && n.length >= MIN_NAME);
+      const fresh = declaredExports(read(f), f).filter((n) => !was.has(n) && n.length >= MIN_NAME && !ENTRY_NAMES.has(n));
       const root = packageRoot(f, manifests);
+      if (root === "." && /^scripts\//.test(f)) continue; // standalone scripts, not a package
       for (const name of fresh) {
         if (++names > MAX_NAMES) return res;
         const hits = lines(await g(["-c", "core.quotepath=off", "grep", "-l", "-w", "-e", name, "HEAD", "--", ...(root === "." ? [] : [`${root}/`])]))
           .map((l) => l.replace(/^HEAD:/, ""))
-          .filter((p) => p !== f && keep(p) && packageRoot(p, manifests) === root);
+          .filter((p) => p !== f && keep(p) && packageRoot(p, manifests) === root && !(root === "." && /^scripts\//.test(p)));
         const others = [];
         for (const p of hits) if (declaredExports(read(p), p).includes(name)) others.push(p);
         if (others.length && others.length < CONVENTION) res.push({ symbol: name, path: f, others: others.sort() });

package/bin/lean/postmerge.test.mjs

@@ -51,6 +51,13 @@ describe("duplicate exports (#4406)", () => {
     assert.deepEqual(await dups(d), []);
   });
 
+  it("standalone scripts each defining main are not duplicate exports; a real duplicate still is", async () => {
+    const d = repo({ "scripts/openapi_diff.py": "def main():\n  pass\n\ndef shared_helper():\n  pass\n" }, { "scripts/seed_minimal.py": "def main():\n  pass\n\ndef shared_helper():\n  pass\n" });
+    assert.deepEqual(await dups(d), []);
+    const e = repo({ "svc/pyproject.toml": "", "svc/a.py": "def main():\n  pass\n" }, { "svc/b.py": "def main():\n  pass\n\ndef resolve_x():\n  pass\n" });
+    assert.deepEqual(await dups(e), []);
+  });
+
   it("Python modules of one package collide too; unreadable git yields []", async () => {
     const d = repo({ "svc/pyproject.toml": "", "svc/a.py": "def resolve_tenant():\n  pass\n" }, { "svc/b.py": "def resolve_tenant():\n  pass\n" });
     assert.deepEqual(await dups(d), [{ symbol: "resolve_tenant", path: "svc/b.py", others: ["svc/a.py"] }]);

package/bin/lean/preflight.mjs

@@ -131,6 +131,27 @@ export function preflightProbes(contract, { repoHas = () => false, cap = PREFLIG
   return { probes: all.slice(0, cap), dropped: Math.max(0, all.length - cap) };
 }
 
+/**
+ * #4857: validate commands that touch a path under a configured forge.yaml `verification.test_runners` prefix
+ * ({"services/worker": "poetry -C services/worker run"}) without using that runner, one problem per validate id. Pure.
+ */
+export function testRunnerProblems(contract, runners) {
+  const entries = Object.entries(runners && typeof runners === "object" ? runners : {}).filter(([k, v]) => k && typeof v === "string" && v.trim());
+  const out = [];
+  for (const v of Array.isArray(contract?.validate) ? contract.validate : []) {
+    if (!v?.id || typeof v.command !== "string") continue;
+    const cmd = v.command.replace(/\s+/g, " ");
+    for (const [prefix, runner] of entries) {
+      const p = prefix.replace(/^\.?\/+|\/+$/g, "");
+      if (new RegExp(`(^|[\\s=:'"])(\\./)?${p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`).test(cmd) && !cmd.includes(runner.trim().replace(/\s+/g, " "))) {
+        out.push(`${v.id}: touches ${p}/ but does not run through that path's configured test runner (forge.yaml verification.test_runners: \`${runner.trim()}\`); use it, with paths relative to its cwd`);
+        break;
+      }
+    }
+  }
+  return out;
+}
+
 const FIX_HOW = "run the check through the repo's own toolchain (its virtualenv, lockfile-pinned runner or package scripts) or use a check that does not need it, never a global install";
 /** One contract problem per miss: names the validate ids and the tool (or path, or env var), and how to fix the plan (never a global install). */
 export function preflightProblems(misses) {

package/bin/lean/preflight.test.mjs

@@ -4,7 +4,7 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { shellSegments, pythonImports, nodeImports, preflightProbes, preflightProblems, runProbeMiss, unsetEnvVars, runPreflight, knownToContract } from "./preflight.mjs";
+import { testRunnerProblems, shellSegments, pythonImports, nodeImports, preflightProbes, preflightProblems, runProbeMiss, unsetEnvVars, runPreflight, knownToContract } from "./preflight.mjs";
 import { runCheckCommand } from "./effects.mjs";
 import { repoTracks } from "./conformance.mjs";
 import { tmpDir } from "../tests/_tmp.mjs";
@@ -106,3 +106,17 @@ describe("#4393 validate preflight: running the command on base", () => {
     assert.deepEqual(r.misses.map((m) => [m.ids[0], m.tool]), [["V1", "absent-pkg-4393"]]);
   });
 });
+
+describe("testRunnerProblems (#4857)", () => {
+  const runners = { "services/worker": "poetry -C services/worker run" };
+  it("flags a validate on a mapped path that skips its runner", () => {
+    const p = testRunnerProblems(C("python3 -m pytest services/worker/tests/test_a.py"), runners);
+    assert.equal(p.length, 1);
+    assert.match(p[0], /V1: touches services\/worker\//);
+  });
+  it("accepts the runner, other paths, and no config", () => {
+    assert.deepEqual(testRunnerProblems(C("poetry -C services/worker run pytest tests/test_a.py"), runners), []);
+    assert.deepEqual(testRunnerProblems(C("node --test bin/lean/x.test.mjs"), runners), []);
+    assert.deepEqual(testRunnerProblems(C("pytest services/worker/t.py"), null), []);
+  });
+});

package/bin/lean/probe.mjs

@@ -179,7 +179,7 @@ export function probeEnv(allow = [], env = process.env) {
 export function spawnProbe({ run, cwd, env, timeoutMs }) {
   return new Promise((resolve) => {
     let stdout = "", stderr = "", timedOut = false;
-    const child = nodeSpawn("sh", ["-c", run], { cwd, env, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    const child = nodeSpawn("sh", ["-c", run], { cwd, env, detached: true, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
     const cap = (s, d) => (s + d).slice(-OUTPUT_TAIL * 4);
     child.stdout.on("data", (d) => { stdout = cap(stdout, d); });
     child.stderr.on("data", (d) => { stderr = cap(stderr, d); });

package/bin/lean/prompts.mjs

@@ -43,7 +43,7 @@ export const syncChecks = (mode = "local") => (mode === "ci" ? `${LIGHT} (the en
 /** CI failed on the pushed branch (#4167): one fix round in the builder's own session. */
 export function ciFailurePrompt(failures, mode = "local") {
   const list = failures.slice(0, 10).map((f) => `#### ${f.job ?? "check"}${f.url ? ` (${f.url})` : ""}\n${f.log ? `\`\`\`\n${f.log}\n\`\`\`` : "(no log available: open the url)"}`).join("\n\n");
-  return `CI failed on the pushed branch:\n\n${list}\n\nFix the cause in the code (or record a typed amendment with a why in ${RESULT_FILE}). ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
+  return `CI failed on the pushed branch:\n\n${list}\n\nFix the cause in the code (or record a typed amendment with a why in ${RESULT_FILE}). A failing check whose files this diff does not touch (a flaky or timing-dependent test) is not an amendment: name the check and why it is unrelated in ${IMPLEMENTATION_FILE} and change no code for it; unknown amendment kinds are rejected. ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
 }
 
 /** The repo's declared check commands (forge.yaml learned.test_commands) failed before the PR (#4240): fixed in-session. */
@@ -182,6 +182,15 @@ export const REVIEW_RUBRIC = `1. Fixed: does the diff resolve the issue as writt
 3. Contract: is every deliverable changed as described, every preserve item intact and every validate command passing?
 4. Scope: does the diff change only deliverable paths and tests?`;
 
+/** #4959: reviewer-only (kept out of REVIEW_RUBRIC, which the builder prompt shares and its token budget caps). */
+const VERDICT_RULE = "A criterion asking for a validation or finding verdict (VALIDATED, FALSE_POSITIVE, INCONCLUSIVE) is met by the recorded verdict here (read by the engine from the lane's investigation) together with a regression or repro test in the diff; it needs no prose in the diff. A gap you yourself call minor is not a failing row.";
+
+/** #4959: the verdict word of an investigation note's \`**Verdict**:\` line (uppercased), or null. */
+export function investigationVerdict(md) {
+  const m = /^\*\*Verdict\*\*:\s*([A-Za-z_-]+)/m.exec(String(md ?? ""));
+  return m ? m[1].toUpperCase() : null;
+}
+
 /** Builder call 2, same session: implement the frozen contract. */
 export function builderImplementPrompt(mode = "local", { toolchain = null, sparse = null, facts = null } = {}) {
   const remote = mode === "ci" || mode === "hybrid";
@@ -234,6 +243,12 @@ export function contextPackNote(pack) {
 }
 
 /** #4271: the bug-lane plan addition (lean.repro_test prefer on a bug/type:bug issue); "" when off, so the prompt is unchanged. */
+/** #4857: validate-command rules for the plan prompt (the implement session resumes it), kept out of the shared templates (their token caps are guarded). */
+export function unrunnableValidateNote(testRunners = null) {
+  const map = testRunners && typeof testRunners === "object" ? Object.entries(testRunners).map(([k, v]) => `${k}/ -> ${v}`).join("; ") : "";
+  return `\n\nValidate and repro commands must pass bash -n (no prose notes), select tests that exist, and run from the right cwd${map ? ` (forge.yaml verification.test_runners: ${map})` : ""}. An unrunnable validate (missing tool, wrong cwd, no tests selected) is never a block or "human" product-decision: run an equivalent through the repo's toolchain and record {"kind":"substitute-validate","validate":"V#","command":"<runnable equivalent>","why":""} in ${RESULT_FILE} amendments.`;
+}
+
 export function reproPlanNote(on) {
   if (!on) return "";
   return `\n\nThis issue is a bug. When it is testable, ${CONTRACT_FILE} must also carry "repro_test":{"path":"<test file>","id":"<test name>","command":"<exact command that runs only that test>"}: a test that fails on the base and passes after the fix. The engine proves it with scripts/acceptance-red-green.sh (head's changed test files are overlaid on the base) and fails the run if it is not red on base and green on head. When it is not testable (specs, docs, workflows, environment), write "repro_test":"none","repro_test_reason":"<one line why>" instead.`;
@@ -384,7 +399,7 @@ export const REVIEWER_SYSTEM = `You are an independent conformance reviewer of o
 
 You receive the GitHub issue with its comments, the frozen contract (requirements quoted from the issue, deliverables, preserve constraints, validate commands) with typed amendments, the builder's result with validation output, the changed files, the diff, and a row skeleton with one row per contract id and changed file. The engine computes the verdict from your rows; a reply without rows is rejected, so fill the skeleton rather than composing rows: fill EVERY row (set each empty status, evidence and validated_by, and each null deferral_ok; keep the ids and files as given):
 - issue_coverage: one row per requirement or acceptance criterion in the issue, quoted verbatim, saying whether the contract covers it, narrows it, or misses it. The skeleton lists the contract's quotes; add a row for any issue requirement the contract does not quote.
-- amendment: a requirement with an \`amendment\` is judged against amendment.text and its why, not the quote; its issue_coverage row is covered when the amendment follows from its why. If it does not hold, mark the row partial with note "amendment: <what to change>".
+- amendment: a requirement with an \`amendment\` is judged against amendment.text and its why, not the quote; its issue_coverage row is covered when the amendment follows from its why. A requirement with \`amended_from\` was contracted defer or post-deploy and flipped to deliver: compare amended_from.quote and amended_from.why with amendment.text side by side, and mark the row partial when the rewording drops the original work or only trivially restates it. If it does not hold, mark the row partial with note "amendment: <what to change>".
 - requirements: one row per contract requirement id: implemented|partial|missing|deferred|post-deploy|not-applicable, with evidence as a backtick-quoted repo-relative path:line copied verbatim from the changed files, including (group), [slug] and [...slug] folders (e.g. \`apps/web/app/(console)/layout.tsx:12\`, not route.ts:12) and the validate id or test that proves it (validated_by). For a defer or post-deploy requirement add deferral_ok: true only if it is genuinely separate work or only checkable after a deploy, false if it belongs in this change, including an outcome criterion (a metric, rate or log expectation) this change could ship as a test, metric or alert, or a read-only production check possible now (bucket verify-now). For a verify out_of_band row (measured by the named job, not in this lane) set instrumented: true only when its budget test or bench is committed and that job is configured, with that path:line as evidence; false otherwise. Do not judge the measured result.
 - post-deploy requirements: deferral_ok is false when the requirement has no \`check\` id, or its check is neither in .forge/post-deploy-checks.json on the default branch nor added by this change (the commands run from that file only).
 - scope: one row per changed file, pre-filled with the engine's authorization: the deliverable id that authorizes it (deliverables may be directories or globs), "test", "incidental" (changelog, lockfile), or "none" with what it changes. Change it only if the diff shows the file does something its deliverable does not cover.
@@ -441,12 +456,12 @@ export function decisionNote(comments = []) {
   return kept.length ? `\n\nBinding decisions posted after the contract froze (trusted; they override the issue text where they conflict, and the frozen contract still applies):\n${kept.join("\n---\n")}` : "";
 }
 
-export function reviewerPrompt({ issue, comments = [], contract, result, files = [], diff, stat = "", base = "", structure = "", ignore = [`${LEAN_DIR}/`], skeleton = null }) {
+export function reviewerPrompt({ issue, comments = [], contract, result, files = [], diff, stat = "", base = "", structure = "", ignore = [`${LEAN_DIR}/`], skeleton = null, investigationVerdict = null }) {
   const notes = comments.map((c) => String(c?.body ?? "")).filter((b) => !/^<!-- FORGE:/.test(b.trim()));
   const decisions = comments.filter((c) => isDecision(c?.body) && isTrustedIssueComment(c)).map((c) => String(c.body)); // #4901: operator decisions bind the review; other FORGE: records stay out
   notes.push(...decisions);
   const sk = JSON.stringify(skeleton ?? reviewSkeleton(contract ?? {}, files, ignore), null, 1);
-  return `Issue #${issue.number}: ${issue.title}\n\n<issue_body>\n${cap(issue.body ?? "", 20000)}\n</issue_body>\n\n<issue_comments>\n${cap(notes.join("\n---\n"), 8000)}\n</issue_comments>\n\n<contract>\n${cap(JSON.stringify(contract ?? {}, null, 1), 12000)}\n</contract>\n\n<builder_result>\n${cap(JSON.stringify(result ?? {}, null, 1), 6000)}\n</builder_result>\n\n<changed_files>\n${files.join("\n")}\n</changed_files>\n\n<rubric>\n${REVIEW_RUBRIC}\n</rubric>\n\n<row_skeleton>\n${cap(sk, 30000)}\n</row_skeleton>\n\n<diff>\n${boundDiff(diff, { stat, base })}\n</diff>${structure ? `\n<structure>${String(structure).replace(/[\r\n]+/g, " ")}</structure>` : ""}`;
+  return `Issue #${issue.number}: ${issue.title}\n\n<issue_body>\n${cap(issue.body ?? "", 20000)}\n</issue_body>\n\n<issue_comments>\n${cap(notes.join("\n---\n"), 8000)}\n</issue_comments>\n\n<contract>\n${cap(JSON.stringify(contract ?? {}, null, 1), 12000)}\n</contract>\n\n<builder_result>\n${cap(JSON.stringify(result ?? {}, null, 1), 6000)}\n</builder_result>\n\n${investigationVerdict ? `<investigation_verdict>${investigationVerdict}</investigation_verdict>\n${VERDICT_RULE}\n\n` : ""}<changed_files>\n${files.join("\n")}\n</changed_files>\n\n<rubric>\n${REVIEW_RUBRIC}\n</rubric>\n\n<row_skeleton>\n${cap(sk, 30000)}\n</row_skeleton>\n\n<diff>\n${boundDiff(diff, { stat, base })}\n</diff>${structure ? `\n<structure>${String(structure).replace(/[\r\n]+/g, " ")}</structure>` : ""}`;
 }
 
 /**