forgedock 1.29.1 → 1.31.0

package/bin/lean/prefilter.test.mjs

@@ -2,9 +2,9 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { prefilterIssue, flakyReason, makePrefilter, formatPrefilterSummary, claimsFix, ciFailureRun, namedPaths, DEFAULT_PREFILTER_MODEL } from "./prefilter.mjs";
+import { prefilterIssue, flakyReason, makePrefilter, postDeployGate, postDeployOnly, deferredFrom, formatParkedLine, lazyDefaultBranch, ownLogins, resolveOwnLogins, formatPrefilterSummary, claimsFix, ciFailureRun, namedPaths, isTrustedIssueComment, DEFAULT_PREFILTER_MODEL } from "./prefilter.mjs";
 import { parsePrefilterVerdict, prefilterPrompt } from "./prompts.mjs";
-import { orchestrate, formatTable } from "./orchestrate.mjs";
+import { orchestrate, formatTable, formatOutcomeLists } from "./orchestrate.mjs";
 import { triageFromCli } from "../engine-cli.mjs";
 
 const fence = (o) => "```json\n" + JSON.stringify(o) + "\n```";
@@ -13,7 +13,7 @@ const fence = (o) => "```json\n" + JSON.stringify(o) + "\n```";
 function world(o = {}) {
   const w = { comments: [], closed: [], labels: [], runner: [], lanes: [], gitCalls: [],
     issues: o.issues ?? {}, prs: o.prs ?? [], commits: o.commits ?? "", paths: new Set(o.paths ?? []), runs: o.runs ?? {}, workflowRuns: o.workflowRuns ?? {}, shaRuns: o.shaRuns ?? {},
-    verdict: o.verdict ?? null };
+    verdict: o.verdict ?? null, mergedPrs: o.mergedPrs ?? [], ancestry: o.ancestry ?? {}, edits: [] };
   w.io = {
     gh: async (a) => {
       const k = a.slice(0, 2).join(" ");
@@ -30,6 +30,8 @@ function world(o = {}) {
       }
       if (k === "issue comment") { w.comments.push([Number(a[2]), a[a.indexOf("--body") + 1]]); return ""; }
       if (k === "issue close") { w.closed.push([Number(a[2]), a[a.indexOf("--reason") + 1]]); return ""; }
+      if (k === "pr list") return JSON.stringify(w.mergedPrs);
+      if (k === "issue edit") { w.edits.push([Number(a[2]), a[5], a[6]]); return ""; }
       throw new Error(`unexpected gh ${a.join(" ")}`);
     },
     git: async (a) => {
@@ -37,6 +39,7 @@ function world(o = {}) {
       if (a[0] === "log") return w.commits;
       if (a[0] === "cat-file") { if (w.paths.has(a[2].replace(/^origin\/staging:/, ""))) return ""; throw new Error("missing"); }
       if (a[0] === "fetch") return "";
+      if (a[0] === "merge-base") { const c = w.ancestry[a[2]] ?? 128; if (c === 0) return ""; throw Object.assign(new Error(`exit ${c}`), { code: c }); }
       if (a[0] === "ls-remote") return a.at(-1) === "refs/heads/staging" ? "abc\trefs/heads/staging\n" : "";
       throw new Error(`unexpected git ${a.join(" ")}`);
     },
@@ -71,6 +74,20 @@ describe("pre-filter (#4123)", () => {
     assert.match(w.comments[0][1], /FORGE:PREFILTER/); assert.match(w.comments[0][1], /src\/foo\.js:3 null guard/); assert.match(w.comments[0][1], /PR #90/);
   });
 
+  it("#4399 an issue reopened by a failed acceptance probe is never re-closed as already-fixed; a pass is no skip", async () => {
+    const probe = (result, author = { login: "rapiercraft-forgedock" }, assoc = "CONTRIBUTOR") => ({ author, authorAssociation: assoc,
+      body: `<!-- FORGE:PROBE -->\n## Acceptance probe: ${result}\n${JSON.stringify({ fix: "abc1234", default_sha: "d", result, exit: result === "pass" ? 0 : 1, ms: 5 })}` });
+    assert.deepEqual(flakyReason({ comments: [probe("fail")] }), { reason: "probe-failed", why: "acceptance probe failed after promotion" });
+    assert.equal(flakyReason({ comments: [probe("fail"), probe("pass")] }), null);
+    assert.equal(flakyReason({ comments: [probe("fail", { login: "someone" }, "NONE")] }), null);
+    const w = world({ issues: { 12: { title: "foo breaks", body: "foo crashes on null", comments: [probe("fail")] } },
+      prs: [{ number: 90, title: "fix: guard foo", body: "Fixes #12", url: "https://github.com/o/r/pull/90" }],
+      verdict: { verdict: "ALREADY-FIXED", summary: "guard added", evidence: ["src/foo.js:3"] } });
+    const r = await pf(w, 12);
+    assert.equal(r.closed, false); assert.match(r.detail, /acceptance probe failed after promotion/);
+    assert.equal(w.runner.length, 0); assert.deepEqual(w.closed, []); assert.deepEqual(w.comments, []);
+  });
+
   it("a candidate the validator CONFIRMS (or answers without evidence) is not closed", async () => {
     const mk = (verdict) => world({ issues: { 12: { body: "x" } }, prs: [{ number: 90, title: "fix (#12)", body: "" }], verdict });
     for (const v of [{ verdict: "CONFIRMED", evidence: ["src/foo.js:3 still derefs"] }, { verdict: "ALREADY-FIXED", evidence: [] }, null]) {
@@ -315,3 +332,158 @@ describe("orchestrate with the pre-filter (#4123)", () => {
     assert.ok(logs.some((s) => /^#12 → lane-refused \(lane\.default_branch/.test(s)));
   });
 });
+
+describe("#4318: the engine's own identity under an installation token or a differently named App", () => {
+  it("ownLogins falls back to the App slug from `gh api app` when `gh api user` fails", async () => {
+    const gh = async (a) => { if (a[1] === "user") throw new Error("Resource not accessible by integration"); if (a[1] === "app") return "Other-Forge\n"; return ""; };
+    assert.deepEqual((await resolveOwnLogins(gh)), { logins: ["rapiercraft-forgedock", "other-forge"], resolved: true });
+    assert.deepEqual(await ownLogins(gh), ["rapiercraft-forgedock", "other-forge"]);
+    const both = async () => { throw new Error("401"); };
+    assert.deepEqual(await resolveOwnLogins(both), { logins: ["rapiercraft-forgedock"], resolved: false });
+  });
+  it("an unresolved lookup is retried once in the batch, then the App-slug-only set is kept", async () => {
+    const link = "Run: https://github.com/o/r/actions/runs/500";
+    const real = { author: { login: "Other-Forge" }, authorAssociation: "CONTRIBUTOR", body: "<!-- FORGE:PREFILTER -->\n## Pre-filter" };
+    const w = world({ issues: { 34: { title: "shell-compat failed on staging", body: `Workflow failed.\n${link}`, comments: [real] } },
+      runs: { 500: { id: 500, workflow_id: 7, name: "shell-compat", head_branch: "staging", head_sha: "1111111111111111", created_at: "2026-10-10T00:00:00Z", html_url: "https://github.com/o/r/actions/runs/500" } },
+      workflowRuns: { "7:staging": [{ id: 600, conclusion: "success", created_at: "2026-10-12T00:00:00Z", html_url: "https://github.com/o/r/actions/runs/600", head_sha: "8d9f6ba0aaaaaaaa" }] },
+      shaRuns: { "8d9f6ba0aaaaaaaa": [{ id: 600, conclusion: "success" }] } });
+    let lookups = 0; const g0 = w.io.gh;
+    w.io.gh = async (a) => (a[0] === "api" && (a[1] === "user" || a[1] === "app") ? (lookups++, (() => { throw new Error("401"); })()) : g0(a));
+    const run = makePrefilter({ repo: "o/r", cwd: "/repo", io: w.io });
+    await run(34, "staging"); await run(34, "staging"); await run(34, "staging");
+    assert.equal(lookups, 4, "user + app, twice: one retry, then cached");
+  });
+});
+
+describe("post-deploy precondition gate (#4389)", () => {
+  const MERGE = "a".repeat(40);
+  const item = (id, disp) => `- [ ] \`${id}: After the next scheduled run, a health row exists\` — ${disp}: only checkable in prod after promotion`;
+  const followup = (parent, items) => `## Problem\n\nDeferred from #${parent}: the items below were declared out of scope.\n\n## Acceptance Criteria\n\n${items.join("\n")}\n\n<!-- FORGE:DEFERRED_FROM: #${parent} -->\n`;
+  const parentPr = [{ number: 90, title: "fix(x): health row (#40)", body: "", mergeCommit: { oid: MERGE } }];
+  const gated = (w, n, extra = {}) => pf(w, n, { defaultBranch: "main", ...extra });
+
+  it("parses the marker and requires every checklist item to be post-deploy", () => {
+    const body = followup(40, [item("R2", "post-deploy")]);
+    assert.equal(deferredFrom(body), 40);
+    assert.equal(deferredFrom("no marker"), null);
+    assert.ok(postDeployOnly(body));
+    assert.ok(!postDeployOnly(followup(40, [item("R2", "post-deploy"), item("R3", "defer")])));
+    assert.ok(!postDeployOnly("no checklist"));
+  });
+
+  it("not an ancestor of the default branch: parked awaiting-promotion, labelled and explained once, no validation run, $0", async () => {
+    const w = world({ issues: { 41: { body: followup(40, [item("R2", "post-deploy")]) } }, mergedPrs: parentPr, ancestry: { [MERGE]: 1 } });
+    const r = await gated(w, 41);
+    assert.equal(r.parked, true); assert.equal(r.kind, "awaiting-promotion"); assert.equal(r.closed, false); assert.equal(r.cost_usd, 0);
+    assert.match(r.detail, /of #40 is not on main/);
+    assert.deepEqual(w.edits, [[41, "--add-label", "awaiting-promotion"]]);
+    assert.equal(w.comments.length, 1); assert.match(w.comments[0][1], /FORGE:PRECONDITION/);
+    assert.equal(w.runner.length, 0); assert.deepEqual(w.closed, []);
+    // already labelled: no second comment
+    const w2 = world({ issues: { 41: { body: followup(40, [item("R2", "post-deploy")]), labels: [{ name: "awaiting-promotion" }] } }, mergedPrs: parentPr, ancestry: { [MERGE]: 1 } });
+    assert.equal((await gated(w2, 41)).parked, true);
+    assert.equal(w2.comments.length, 0);
+  });
+
+  it("an escalated (needs-human) promotion follow-up is parked too; a dry run changes nothing on GitHub", async () => {
+    const w = world({ issues: { 41: { body: followup(40, [item("R2", "post-deploy")]), labels: [{ name: "needs-human" }] } }, mergedPrs: parentPr, ancestry: { [MERGE]: 1 } });
+    const r = await gated(w, 41, { dryRun: true });
+    assert.equal(r.parked, true);
+    assert.deepEqual(w.edits, []); assert.deepEqual(w.comments, []);
+  });
+
+  it("an ancestor (after promotion): not parked, the label is removed, and the issue goes on as before", async () => {
+    const w = world({ issues: { 41: { body: followup(40, [item("R2", "post-deploy")]), labels: [{ name: "awaiting-promotion" }] } }, mergedPrs: parentPr, ancestry: { [MERGE]: 0 } });
+    const r = await gated(w, 41);
+    assert.ok(!r.parked); assert.equal(r.detail, "no already-fixed signal");
+    assert.deepEqual(w.edits, [[41, "--remove-label", "awaiting-promotion"]]);
+    const rows = await orchestrate({ issues: [41], readBody: async () => "", prefilter: makePrefilter({ repo: "o/r", cwd: "/repo", io: w.io, defaultBranch: "main" }),
+      runOne: async () => ({ terminalReason: "merged", pr: 7, cost_usd: 1 }) });
+    assert.deepEqual(rows.map((x) => x.outcome), ["merged"]);
+  });
+
+  it("an unresolvable parent (no merged PR, no trajectory) or an unknown SHA falls through to the lane", async () => {
+    const w = world({ issues: { 41: { body: followup(40, [item("R2", "post-deploy")]) }, 40: { comments: [] } } });
+    const r = await gated(w, 41);
+    assert.ok(!r.parked); assert.deepEqual(w.edits, []);
+    const g = await postDeployGate({ iss: { number: 41, body: followup(40, [item("R2", "post-deploy")]) }, repo: "o/r", lane: "staging", defaultBranch: "main", cwd: "/repo",
+      io: world({ mergedPrs: parentPr, ancestry: { [MERGE]: 128 } }).io });
+    assert.equal(g.state, "unresolved");
+    assert.equal((await postDeployGate({ iss: { number: 41, body: followup(40, [item("R2", "post-deploy")]) }, repo: "o/r", defaultBranch: async () => null, io: world().io })).state, "unresolved");
+  });
+
+  it("the trusted trajectory 'merged at <sha>' is the fallback when no merged PR names the parent", async () => {
+    const w = world({ issues: { 40: { comments: [{ author: { login: "rapiercraft-forgedock" }, authorAssociation: "CONTRIBUTOR", body: "<!-- FORGE:TRAJECTORY -->\n| Merge | merged at abcdef123456 |" },
+      { author: { login: "mallory" }, authorAssociation: "NONE", body: "<!-- FORGE:TRAJECTORY --> merged at 0123456789ab" }] } }, ancestry: { abcdef123456: 1 } });
+    const g = await postDeployGate({ iss: { number: 41, body: followup(40, [item("R2", "post-deploy")]) }, repo: "o/r", lane: "staging", defaultBranch: "main", cwd: "/repo", io: w.io });
+    assert.equal(g.state, "awaiting-promotion"); assert.deepEqual(g.shas, ["abcdef123456"]);
+  });
+
+  it("mixed post-deploy + code items, and issues without DEFERRED_FROM, are unaffected (no gate calls)", async () => {
+    for (const body of [followup(40, [item("R2", "post-deploy"), item("R3", "defer")]), item("R2", "post-deploy")]) {
+      const w = world({ issues: { 41: { body } }, mergedPrs: parentPr, ancestry: { [MERGE]: 1 } });
+      const r = await gated(w, 41);
+      assert.ok(!r.parked); assert.ok(!w.gitCalls.some((a) => a[0] === "merge-base"));
+    }
+    const w = world({ issues: { 41: { body: followup(40, [item("R2", "post-deploy")]), labels: [{ name: "needs-human" }] } } });
+    assert.equal((await pf(w, 41)).detail, "labelled, left to the lane"); // no default branch: gate off, today's behaviour
+  });
+
+  it("post_deploy.precondition_cmd: exit 0 ready, exit 1 parked awaiting-precondition, other exits fail open", async () => {
+    const body = followup(40, [item("R2", "post-deploy")]);
+    for (const [code, state] of [[0, "ready"], [1, "awaiting-precondition"], [2, "unresolved"], [-1, "unresolved"]]) {
+      const w = world({ mergedPrs: parentPr, ancestry: { [MERGE]: 0 } });
+      const calls = [];
+      w.io.execCode = async (cmd, args, opts) => { calls.push([cmd, args, opts.env.FORGE_ISSUE]); return code; };
+      const g = await postDeployGate({ iss: { number: 41, body }, repo: "o/r", lane: "staging", defaultBranch: "main", cwd: "/repo", io: w.io, preconditionCmd: "check-rollout" });
+      assert.equal(g.state, state);
+      assert.deepEqual(calls, [["sh", ["-c", "check-rollout", "precondition", "41"], "41"]]);
+    }
+  });
+
+  it("forgedock triage prints a parked issue, one awaiting-promotion line, and leaves it out of the lanes", async () => {
+    const w = world({ issues: { 41: { body: followup(40, [item("R2", "post-deploy")]) }, 13: { body: "y" } }, mergedPrs: parentPr, ancestry: { [MERGE]: 1 } });
+    const logs = []; const l = console.log; console.log = (x) => logs.push(String(x));
+    let res;
+    try { res = await triageFromCli(["41", "13", "--repo", "o/r", "--lane", "staging", "--dry-run"], { leanIo: w.io }); } finally { console.log = l; }
+    assert.deepEqual(res.lanes, [13]);
+    assert.ok(logs.some((x) => /^#41 → parked \(awaiting-promotion: /.test(x)));
+    assert.ok(logs.includes("awaiting promotion: #41 (fixes on staging, not on main)"));
+    assert.deepEqual(w.edits, []);
+  });
+
+  it("lazyDefaultBranch resolves GitHub's default and fetches it once, only when asked", async () => {
+    const w = world();
+    const d = lazyDefaultBranch({ io: w.io, repo: "o/r", cwd: "/repo" });
+    assert.equal(w.gitCalls.length, 0);
+    assert.equal(await d(), "main"); assert.equal(await d(), "main");
+    assert.deepEqual(w.gitCalls, [["fetch", "origin", "main"]]);
+  });
+
+  it("orchestrate: parked issues start no lane and the report has one awaiting-promotion line, no escalations", async () => {
+    const issues = {}; for (const n of [41, 42, 43]) issues[n] = { body: followup(40, [item("R2", "post-deploy")]) };
+    const w = world({ issues, mergedPrs: parentPr, ancestry: { [MERGE]: 1 } });
+    const lanes = [];
+    const rows = await orchestrate({ issues: [41, 42, 43], readBody: async () => "", prefilter: makePrefilter({ repo: "o/r", cwd: "/repo", io: w.io, defaultBranch: "main" }),
+      resolveLane: async () => ({ ok: true, lane: "staging" }),
+      runOne: async (n) => { lanes.push(n); return { terminalReason: "merged", pr: 1, cost_usd: 1 }; } });
+    assert.deepEqual(lanes, []);
+    assert.deepEqual(rows.map((r) => [r.outcome, r.cost_usd]), [["awaiting-promotion", 0], ["awaiting-promotion", 0], ["awaiting-promotion", 0]]);
+    const lists = formatOutcomeLists(rows);
+    assert.deepEqual(lists, ["awaiting promotion: #41 #42 #43 (fixes on staging, not on main)"]);
+    assert.match(formatTable(rows), /#41\s+awaiting-promotion \(pre-filter\)/);
+    assert.equal(formatParkedLine([{ issue: 1, outcome: "merged" }]), "");
+  });
+});
+
+describe("#4467: isTrustedIssueComment", () => {
+  it("trusts the App in gh issue view and REST shapes and trusted associations; not other contributors", () => {
+    assert.equal(isTrustedIssueComment({ author: { login: "rapiercraft-forgedock" }, authorAssociation: "CONTRIBUTOR" }), true);
+    assert.equal(isTrustedIssueComment({ user: { login: "rapiercraft-forgedock[bot]", type: "Bot" }, author_association: "NONE" }), true);
+    assert.equal(isTrustedIssueComment({ author: { login: "app/rapiercraft-forgedock" }, authorAssociation: "NONE" }), true);
+    assert.equal(isTrustedIssueComment({ author: { login: "owner" }, authorAssociation: "OWNER" }), true);
+    assert.equal(isTrustedIssueComment({ author: { login: "someone" }, authorAssociation: "CONTRIBUTOR" }), false);
+    assert.equal(isTrustedIssueComment(null), false);
+  });
+});

package/bin/lean/preflight.mjs

@@ -0,0 +1,238 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forge#4328: freeze-time preflight of a contract's validate commands. Pure: derives the host tools a command needs
+ * (each segment's bare executable, Python modules a bare python imports via -c/-m, Node packages `node -e` code imports)
+ * and a read-only bash probe for each. The engine runs the probes (lean.mjs) before the implement session, so a validate
+ * command the host cannot run is corrected in the plan instead of found after the build (#4323 env.tool_missing).
+ * #4393: text alone misses wrapped interpreters (`uv run python -m x`) and transitive imports, so `runPreflight` also runs
+ * each command once on the base worktree and classifies its output (`runProbeMiss`); `unsetEnvVars` flags `$NAME`s the lane
+ * env leaves empty (#4325).
+ */
+import { builtinModules } from "node:module";
+import { missingTool } from "./conformance.mjs";
+
+export const PREFLIGHT_CAP = 20;
+const KIND_NAME = { command: "command", "python-module": "Python module", "node-module": "Node package", path: "path", "env-var": "env var" };
+const PY_RE = /^python(\d+(\.\d+)?)?$/;
+const PY_ARG_FLAGS = new Set(["-W", "-X", "-Q"]);
+const sq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+/** Quote-aware split of a bash command into segments (on &&, ||, |, ;, newline) of unquoted words; `$(...)` stays one word. */
+export function shellSegments(command) {
+  const segs = [];
+  let words = [], word = "", has = false, q = null, depth = 0;
+  const endWord = () => { if (has) words.push(word); word = ""; has = false; };
+  const endSeg = () => { endWord(); if (words.length) segs.push(words); words = []; };
+  const s = String(command ?? "");
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (q === "'") { if (ch === "'") q = null; else word += ch; continue; }
+    if (ch === "\\" && i + 1 < s.length) { word += s[++i]; has = true; continue; }
+    if (q === '"') { if (ch === '"') q = null; else word += ch; continue; }
+    if (depth) { word += ch; if (ch === "(") depth++; else if (ch === ")") depth--; continue; }
+    if (ch === "'" || ch === '"') { q = ch; has = true; continue; }
+    if (ch === "$" && s[i + 1] === "(") { word += "$("; i++; depth = 1; has = true; continue; }
+    if (ch === " " || ch === "\t") { endWord(); continue; }
+    if (ch === "\n" || ch === ";" || ch === "|" || ch === "&") { if (ch === "&" && s[i + 1] !== "&") { endWord(); continue; } endSeg(); if (s[i + 1] === ch) i++; continue; }
+    if ((ch === "(" || ch === ")" || ch === "{" || ch === "}") && !has) continue;
+    word += ch; has = true;
+  }
+  endSeg();
+  return segs;
+}
+
+/** Top-level module names a Python `-c` program imports (absolute imports only). */
+export function pythonImports(code) {
+  const out = [];
+  for (const line of String(code ?? "").split(/[;\n]/)) {
+    const imp = /^\s*import\s+(.+)$/.exec(line), from = /^\s*from\s+([\w.]+)\s+import\b/.exec(line);
+    if (imp) for (const part of imp[1].split(",")) { const m = /^\s*([A-Za-z_]\w*)/.exec(part); if (m) out.push(m[1]); }
+    else if (from && !from[1].startsWith(".")) out.push(from[1].split(".")[0]);
+  }
+  for (const m of String(code ?? "").matchAll(/(?:__import__|import_module)\(\s*['"]([A-Za-z_][\w.]*)['"]/g)) out.push(m[1].split(".")[0]);
+  return [...new Set(out)].filter((x) => x !== "__future__");
+}
+
+/** Package names (bare specifiers, cut to the package) a `node -e` program imports; builtins, node:, relative and absolute are not packages. */
+export function nodeImports(code) {
+  const specs = [], c = String(code ?? "");
+  for (const re of [/\brequire\(\s*['"]([^'"]+)['"]\s*\)/g, /\bimport\s*\(\s*['"]([^'"]+)['"]/g, /\bfrom\s*['"]([^'"]+)['"]/g, /(?:^|[;\n])\s*import\s*['"]([^'"]+)['"]/g]) for (const m of c.matchAll(re)) specs.push(m[1]);
+  const out = [];
+  for (const spec of specs) {
+    if (/^(\.|\/|node:|file:|data:)/.test(spec)) continue;
+    const parts = spec.split("/"), pkg = spec.startsWith("@") ? (parts.length > 1 ? parts.slice(0, 2).join("/") : null) : parts[0];
+    if (pkg && !builtinModules.includes(pkg)) out.push(pkg);
+  }
+  return [...new Set(out)];
+}
+
+const PY_PROBE = "import importlib.util,sys;sys.exit(0 if importlib.util.find_spec(sys.argv[1]) else 3)";
+const NODE_PROBE = "const m=require('module'),p=require('path'),f=require('fs'),n=process.argv[1];if(m.builtinModules.includes(n))process.exit(0);for(let d=process.cwd();;){if(f.existsSync(p.join(d,'node_modules',n,'package.json')))process.exit(0);const u=p.dirname(d);if(u===d)process.exit(3);d=u}";
+
+/** The program text and modules of one python/node segment's arguments. */
+function moduleNeeds(exe, args) {
+  if (PY_RE.test(exe)) {
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i];
+      if (a === "-c") return pythonImports(args[i + 1]);
+      if (a.startsWith("-c") && a.length > 2) return pythonImports(a.slice(2));
+      if (a === "-m") return args[i + 1] ? [args[i + 1].split(".")[0]] : [];
+      if (a.startsWith("-m") && a.length > 2) return [a.slice(2).split(".")[0]];
+      if (PY_ARG_FLAGS.has(a)) { i++; continue; }
+      if (!a.startsWith("-")) return [];
+    }
+    return [];
+  }
+  if (exe === "node") {
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i];
+      if (["-e", "--eval", "-p", "--print"].includes(a)) return nodeImports(args[i + 1]);
+      const eq = /^--(?:eval|print)=(.*)$/s.exec(a);
+      if (eq) return nodeImports(eq[1]);
+      if (!a.startsWith("-")) return [];
+    }
+  }
+  return [];
+}
+
+/**
+ * The probes for `contract.validate[]`: {probes: [{ids, tool, kind, interp, needs, probe}], dropped}. `needs` is the command
+ * probe (tool) a module probe depends on: skip the module probe when its interpreter is missing. A name `repoHas(name)` holds
+ * or a deliverable's change text names (the change adds it) is not probed; paths and `$...` words are never probed.
+ */
+export function preflightProbes(contract, { repoHas = () => false, cap = PREFLIGHT_CAP } = {}) {
+  const changes = (Array.isArray(contract?.deliverables) ? contract.deliverables : []).map((d) => String(d?.change ?? "")).join("\n");
+  const named = (name) => new RegExp(`(^|[^\\w@/.-])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w/-])`).test(changes);
+  const skip = (name) => !name || name.includes("/") && !name.startsWith("@") || name.startsWith("$") || repoHas(name) || named(name);
+  const byKey = new Map();
+  const add = (id, kind, tool, interp = null) => {
+    const key = `${kind}|${tool}|${interp ?? ""}`;
+    const p = byKey.get(key);
+    if (p) { if (!p.ids.includes(id)) p.ids.push(id); return; }
+    const probe = kind === "command" ? `command -v -- ${sq(tool)} >/dev/null 2>&1`
+      : kind === "python-module" ? `${sq(interp)} -c ${sq(PY_PROBE)} ${sq(tool)} >/dev/null 2>&1`
+      : `node -e ${sq(NODE_PROBE)} ${sq(tool)} >/dev/null 2>&1`;
+    byKey.set(key, { ids: [id], tool, kind, interp, needs: kind === "command" ? null : interp, probe });
+  };
+  for (const v of Array.isArray(contract?.validate) ? contract.validate : []) {
+    if (!v?.id || typeof v.command !== "string") continue;
+    for (const seg of shellSegments(v.command)) {
+      let i = 0;
+      while (i < seg.length && (/^[A-Za-z_]\w*=/.test(seg[i]) || ["!", "time", "exec", "command", "env"].includes(seg[i]))) i++;
+      const exe = seg[i];
+      if (!exe || exe.includes("/") || exe.startsWith("$") || exe.startsWith("-")) continue;
+      if (!skip(exe)) add(v.id, "command", exe);
+      const kind = exe === "node" ? "node-module" : "python-module";
+      for (const mod of moduleNeeds(exe, seg.slice(i + 1))) if (!skip(mod)) add(v.id, kind, mod, exe);
+    }
+  }
+  const all = [...byKey.values()];
+  return { probes: all.slice(0, cap), dropped: Math.max(0, all.length - cap) };
+}
+
+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) {
+  return (misses ?? []).map((m) => {
+    const ids = m.ids.join(", ");
+    if (m.kind === "env-var") return `${ids}: uses $${m.tool}, which is unset or empty in the lane environment, so the validate command cannot run as written; set it inside the command or ${FIX_HOW}`;
+    if (m.source === "run") return `${ids}: running it on the base worktree stopped before any test ran: needs ${KIND_NAME[m.kind] ?? m.kind} '${m.tool}'${m.line ? ` (\`${m.line}\`)` : ""}, so the validate command cannot run here; ${m.kind === "path" ? "point it at a path the repo or a deliverable has, or " : ""}${FIX_HOW}`;
+    return `${ids}: needs ${KIND_NAME[m.kind] ?? m.kind} '${m.tool}'${m.interp ? ` (for ${m.interp})` : ""}, which this host lacks, so the validate command cannot run here; ${FIX_HOW}`;
+  });
+}
+
+/** #4393: per-command timeout and total budget of the freeze-time runs; a command cut by either is no evidence. */
+export const RUN_PROBE_MS = 30000, RUN_BUDGET_MS = 120000;
+const TIMEOUT_RC = 124;
+// bash sets these itself; they are never "missing from the lane env"
+const SHELL_VARS = new Set(["RANDOM", "SECONDS", "LINENO", "PWD", "OLDPWD", "HOME", "UID", "EUID", "PPID", "BASHPID", "IFS", "HOSTNAME", "SHELL", "USER", "PATH", "BASH", "BASH_SOURCE", "BASH_VERSION", "BASH_REMATCH", "PIPESTATUS", "FUNCNAME", "EPOCHSECONDS", "EPOCHREALTIME", "SHLVL", "OPTARG", "OPTIND", "REPLY", "HOSTTYPE", "OSTYPE", "MACHTYPE", "GROUPS"]);
+
+/**
+ * `$NAME` / `${NAME}` references (outside single quotes, not escaped) that are unset or empty in `env` and that the command
+ * does not assign itself (`NAME=`, `export NAME=`, `for NAME in`). `${NAME:-x}`-style defaults, `${#NAME}` and specials are not flagged.
+ */
+export function unsetEnvVars(command, env = {}) {
+  const s = String(command ?? ""), refs = [];
+  let q = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (q === "'") { if (ch === "'") q = null; continue; }
+    if (ch === "\\") { i++; continue; }
+    if (ch === '"') { q = q ? null : '"'; continue; }
+    if (ch === "'" && !q) { q = "'"; continue; }
+    if (ch !== "$") continue;
+    const m = /^\{([A-Za-z_]\w*)(\}|:?[-=+?])|^([A-Za-z_]\w*)/.exec(s.slice(i + 1));
+    if (m && (m[3] || m[2] === "}")) refs.push(m[1] ?? m[3]);
+  }
+  const assigned = (n) => new RegExp(`(^|[\\s;&|(])((export|local|readonly|declare)\\s+)?${n}=|\\bfor\\s+${n}\\s+in\\b`).test(s);
+  return [...new Set(refs)].filter((n) => !SHELL_VARS.has(n) && (env[n] === undefined || env[n] === null || env[n] === "") && !assigned(n));
+}
+
+// [rc, pattern]: bash could not exec a path (127), python could not open its script, pytest / node --test could not find a file
+const PATH_MISSING_RES = [[127, /(?:^|\s)([^\s:'"`]+): No such file or directory/m], [null, /can't open file '([^']+)'/], [null, /file or directory not found: (\S+)/], [null, /Could not find '([^']+)'/]];
+const TESTISH_RE = /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[^/]+$|(^|\/)test_[^/]*\.py$|_test\.(py|go)$/;
+
+/**
+ * #4393: why one freeze-time run of a validate command shows it cannot run on this host, or null when it ran (passed, or
+ * failed on test content: RED on base is expected), timed out (no evidence) or gave no recognisable reason.
+ * A path counts as missing unless `knownPath(path)` (repo-tracked, a deliverable, the repro test) or it looks like a test the
+ * builder adds; a module goes through conformance.mjs `missingTool` with `repoHas`, as the post-build gate does.
+ * Returns {tool, kind: command|python-module|node-module|path, line} with the output line that showed it.
+ */
+export function runProbeMiss(r, { repoHas = () => false, command = "", knownPath = () => false } = {}) {
+  const rc = r?.rc, out = String(r?.output ?? "");
+  if (!Number.isInteger(rc) || rc === 0 || rc === TIMEOUT_RC) return null;
+  const lineOf = (needle) => (out.split("\n").find((l) => l.includes(needle)) ?? "").trim().slice(0, 160);
+  for (const [onlyRc, re] of PATH_MISSING_RES) {
+    const p = onlyRc === null || onlyRc === rc ? re.exec(out)?.[1] : null;
+    if (!p) continue;
+    if (TESTISH_RE.test(p) || knownPath(p)) return null;
+    return { tool: p, kind: "path", line: lineOf(p) };
+  }
+  const miss = missingTool(r, { repoHas, command });
+  return miss ? { ...miss, line: lineOf(miss.tool) } : null;
+}
+
+/**
+ * #4393: what a freeze-time run may legitimately not find yet: `repoHas` (a name the repo tracks or a deliverable's change
+ * text names) and `knownPath` (a tracked file, a deliverable or the repro test, matched as a suffix of an absolute path).
+ */
+export function knownToContract(contract, files = []) {
+  const changes = (Array.isArray(contract?.deliverables) ? contract.deliverables : []).map((d) => String(d?.change ?? "")).join("\n");
+  const paths = [...files, ...(contract?.deliverables ?? []).map((d) => d?.path), contract?.repro_test?.path].filter((x) => typeof x === "string" && x).map((x) => x.replace(/^\.\//, "").replace(/\/+$/, ""));
+  const segs = new Set(paths.flatMap((x) => x.split("/")));
+  const repoHas = (name) => segs.has(name) || segs.has(`${name}.py`) || new RegExp(`(^|[^\\w@/.-])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w/-])`).test(changes);
+  const knownPath = (p) => { const rel = String(p).replace(/^\.\//, ""); return paths.some((k) => rel === k || rel.endsWith(`/${k}`) || rel.startsWith(`${k}/`) || rel.includes(`/${k}/`)); };
+  return { repoHas, knownPath };
+}
+
+const porcelain = (out) => new Map(String(out ?? "").split("\n").filter((l) => l.length > 3).map((l) => [l.slice(3), l.slice(0, 2)]));
+
+/**
+ * #4393: run each `contract.validate[]` command (ids in `skipIds` excepted) once through `run({command, timeoutMs, env})`,
+ * 30 s each inside a 120 s budget, and classify each with `runProbeMiss`. `git(args)` runs in the worktree: whatever the runs
+ * newly created or modified (`git status --porcelain`) is reverted; a path dirty before the runs is never touched.
+ * Returns {misses: [{ids, tool, kind, line, source: "run"}], skipped: ids not run (budget), reverted: paths}.
+ */
+export async function runPreflight({ contract, run, git, env = {}, repoHas = () => false, knownPath = () => false, skipIds = [], now = () => Date.now(), perCommandMs = RUN_PROBE_MS, budgetMs = RUN_BUDGET_MS }) {
+  const misses = [], skipped = [], reverted = [];
+  const todo = (Array.isArray(contract?.validate) ? contract.validate : []).filter((v) => v?.id && typeof v.command === "string" && !skipIds.includes(v.id));
+  if (!todo.length) return { misses, skipped, reverted };
+  const status = async () => porcelain(await git(["status", "--porcelain", "--untracked-files=all"]).catch(() => ""));
+  const before = await status(), deadline = now() + budgetMs;
+  for (const v of todo) {
+    const left = deadline - now();
+    if (left <= 0) { skipped.push(v.id); continue; }
+    let r;
+    try { r = await run({ command: v.command, timeoutMs: Math.min(perCommandMs, left), env }); } catch (e) { r = { rc: 127, output: String(e?.message ?? e) }; }
+    const miss = runProbeMiss(r, { repoHas, command: v.command, knownPath });
+    if (miss) misses.push({ ids: [v.id], ...miss, source: "run" });
+  }
+  const after = await status();
+  for (const [path, xy] of after) {
+    if (before.has(path) || path.includes(" -> ")) continue;
+    try { await git(xy === "??" ? ["clean", "-fdq", "--", path] : ["checkout", "--", path]); reverted.push(path); } catch { /* left as is; the scope gate still sees it */ }
+  }
+  return { misses, skipped, reverted };
+}

package/bin/lean/preflight.test.mjs

@@ -0,0 +1,108 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+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 { runCheckCommand } from "./effects.mjs";
+import { repoTracks } from "./conformance.mjs";
+import { tmpDir } from "../tests/_tmp.mjs";
+
+const C = (...commands) => ({ deliverables: [], validate: commands.map((command, i) => ({ id: `V${i + 1}`, command })) });
+const needs = (c, o) => preflightProbes(c, o).probes.map((p) => [p.kind, p.tool, p.interp ?? null, p.ids.join(",")]);
+
+describe("#4328 validate preflight: what a command needs", () => {
+  it("splits on && || | ; and newlines, keeps quotes and $(...) whole", () => {
+    assert.deepEqual(shellSegments(`cd a && python3 -c "import yaml; print('x | y')" | tee "$TMPDIR/o" ; git diff $(git merge-base HEAD origin/x) -- a || true`),
+      [["cd", "a"], ["python3", "-c", "import yaml; print('x | y')"], ["tee", "$TMPDIR/o"], ["git", "diff", "$(git merge-base HEAD origin/x)", "--", "a"], ["true"]]);
+  });
+  it("python -c imports and -m modules (top-level, absolute only); node -e bare packages", () => {
+    assert.deepEqual(pythonImports("import yaml, os.path as p\nfrom jsonschema.validators import x; from . import y; from __future__ import annotations; __import__('toml')"), ["yaml", "os", "jsonschema", "toml"]);
+    assert.deepEqual(nodeImports(`const z=require("zod"); import("@scope/pkg/sub"); import fs from "node:fs"; require("./x"); require("path")`), ["zod", "@scope/pkg"]);
+  });
+  it("probes each bare executable, a bare python's modules and node -e packages, deduped across validate ids", () => {
+    assert.deepEqual(needs(C(`FOO=1 python3 -c "import yaml,json"`, "python3 -m pytest -q tests/x.py && jq . a.json", `node -e "require('zod')"`, "python3 -c 'import yaml'")), [
+      ["command", "python3", null, "V1,V2,V4"], ["python-module", "yaml", "python3", "V1,V4"], ["python-module", "json", "python3", "V1"],
+      ["python-module", "pytest", "python3", "V2"], ["command", "jq", null, "V2"], ["command", "node", null, "V3"], ["node-module", "zod", "node", "V3"]]);
+  });
+  it("wrappers and paths: only the wrapper is probed; ./script and .venv/bin/python and $VAR never are", () => {
+    assert.deepEqual(needs(C(`uv run python -c "import yaml"`, "./scripts/check.sh", `.venv/bin/python -c "import yaml"`, "$PY -m x", "npx vitest run a.test.ts")),
+      [["command", "uv", null, "V1"], ["command", "npx", null, "V5"]]);
+  });
+  it("skips names the repo tracks and names a deliverable's change adds", () => {
+    const c = { ...C(`python3 -c "import app, yaml"`, `node -e "require('left-pad')"`), deliverables: [{ id: "D1", path: "package.json", change: "add devDependency left-pad for the check" }] };
+    assert.deepEqual(needs(c, { repoHas: repoTracks(["app/__init__.py"]) }).map((x) => x[1]), ["python3", "yaml", "node"]);
+  });
+  it("caps the probes and reports the dropped count", () => {
+    const r = preflightProbes(C(Array.from({ length: 25 }, (_, i) => `tool${i}`).join(" && ")), { cap: 20 });
+    assert.equal(r.probes.length, 20); assert.equal(r.dropped, 5);
+  });
+  it("a problem line names the ids, the kind and the tool and forbids a global install", () => {
+    const [p] = preflightProblems([{ ids: ["V5"], tool: "yaml", kind: "python-module", interp: "python3" }]);
+    assert.match(p, /^V5: needs Python module 'yaml' \(for python3\), which this host lacks/);
+    assert.match(p, /repo's own toolchain .*never a global install/);
+  });
+  it("the probes are real read-only shell checks: present tools pass, absent ones fail", async () => {
+    const dir = tmpDir("preflight-");
+    mkdirSync(join(dir, "node_modules", "here"), { recursive: true }); writeFileSync(join(dir, "node_modules", "here", "package.json"), "{}");
+    mkdirSync(join(dir, "sub"));
+    const probes = preflightProbes(C("bash -c true", "no-such-tool-4328 --x", `node -e "require('here'); require('fs'); require('absent-pkg-4328')"`)).probes;
+    const rc = {};
+    for (const p of probes) rc[`${p.kind}:${p.tool}`] = (await runCheckCommand({ command: p.probe, cwd: join(dir, "sub"), timeoutMs: 15000 })).rc;
+    assert.equal(rc["command:bash"], 0); assert.notEqual(rc["command:no-such-tool-4328"], 0);
+    assert.equal(rc["command:node"], 0); assert.equal(rc["node-module:here"], 0, "found in an ancestor node_modules");
+    assert.notEqual(rc["node-module:absent-pkg-4328"], 0);
+    const py = preflightProbes(C(`python3 -c "import json, no_such_mod_4328"`)).probes.filter((p) => p.kind === "python-module");
+    if ((await runCheckCommand({ command: "command -v python3", cwd: dir })).rc === 0) {
+      assert.deepEqual(await Promise.all(py.map(async (p) => (await runCheckCommand({ command: p.probe, cwd: dir })).rc !== 0)), [false, true]);
+    }
+  });
+});
+
+describe("#4393 validate preflight: running the command on base", () => {
+  const known = knownToContract({ deliverables: [{ id: "D1", path: "tools/new_check.py", change: "add module newlib" }], repro_test: { path: "test/r.test.mjs" } }, ["shared/detection/__init__.py", "scripts/run.sh"]);
+  it("unrunnable: a missing module, command or path; a repo-tracked or deliverable-named module is not the host", () => {
+    assert.deepEqual(runProbeMiss({ rc: 1, output: "Traceback (most recent call last):\nModuleNotFoundError: No module named 'httpx'\n" }, known),
+      { tool: "httpx", kind: "python-module", line: "ModuleNotFoundError: No module named 'httpx'" });
+    assert.equal(runProbeMiss({ rc: 1, output: "ModuleNotFoundError: No module named 'shared'" }, known), null);
+    assert.equal(runProbeMiss({ rc: 1, output: "ModuleNotFoundError: No module named 'newlib'" }, known), null);
+    assert.equal(runProbeMiss({ rc: 127, output: "bash: line 1: jq: command not found" }, known).tool, "jq");
+    assert.deepEqual(runProbeMiss({ rc: 127, output: "bash: line 1: ./scripts/gone.sh: No such file or directory" }, known), { tool: "./scripts/gone.sh", kind: "path", line: "bash: line 1: ./scripts/gone.sh: No such file or directory" });
+    assert.equal(runProbeMiss({ rc: 2, output: "python3: can't open file '/wt/x/tools/old.py': [Errno 2] No such file or directory" }, known).kind, "path");
+  });
+  it("runs: passes, RED test failures, timeouts and paths the change adds are no miss", () => {
+    for (const r of [{ rc: 0, output: "" }, { rc: 1, output: "AssertionError: expected 1 to equal 2" }, { rc: 124, output: "ModuleNotFoundError: No module named 'httpx'\n(timed out after 30s)" },
+      { rc: 2, output: "python3: can't open file '/wt/x/tools/new_check.py': [Errno 2] No such file or directory" }, { rc: 4, output: "ERROR: file or directory not found: tests/test_new.py" },
+      { rc: 1, output: "Could not find '/wt/x/test/r.test.mjs'" }, { rc: 1, output: "cat: data.json: No such file or directory" }]) assert.equal(runProbeMiss(r, known), null, r.output);
+  });
+  it("unset env vars: empty or unset, outside single quotes, not assigned or defaulted by the command", () => {
+    assert.deepEqual(unsetEnvVars(`cat "$TMPDIR/x" && echo \${OUT} '$SINGLE' \\$ESC \${D:-1} $? $HOME`, { TMPDIR: "", HOME: "/h" }), ["TMPDIR", "OUT"]);
+    assert.deepEqual(unsetEnvVars(`X=1; echo $X; export Y=2 && echo "$Y"; for F in a b; do echo $F; done; echo $SET`, { SET: "s" }), []);
+  });
+  it("runPreflight runs every command with the env and a capped timeout, skips ids, honours the budget and reverts only what the runs changed", async () => {
+    const ran = [], gits = [];
+    let clock = 0, st = " M kept.js\n";
+    const run = async (a) => { ran.push([a.command, a.timeoutMs, a.env.K]); clock += 70000; st += "?? new.log\n M src/a.js\n"; return { rc: 1, output: a.command === "c1" ? "ModuleNotFoundError: No module named 'httpx'" : "" }; };
+    const git = async (args) => { gits.push(args.join(" ")); return args[0] === "status" ? st : ""; };
+    const contract = { validate: ["c1", "c2", "c3", "c4"].map((command, i) => ({ id: `V${i + 1}`, command })) };
+    const r = await runPreflight({ contract, run, git, env: { K: "v" }, skipIds: ["V2"], now: () => clock });
+    assert.deepEqual(ran, [["c1", 30000, "v"], ["c3", 30000, "v"]]);
+    assert.deepEqual(r.misses.map((m) => [m.ids, m.tool, m.kind, m.source]), [[["V1"], "httpx", "python-module", "run"]]);
+    assert.deepEqual(r.skipped, ["V4"]);
+    assert.deepEqual(r.reverted, ["new.log", "src/a.js"]);
+    assert.deepEqual(gits.filter((g) => !g.startsWith("status")), ["clean -fdq -- new.log", "checkout -- src/a.js"], "kept.js was dirty before: untouched");
+  });
+  it("problem lines name the id, the tool and the observed line, or the env var", () => {
+    const [run, env] = preflightProblems([{ ids: ["V4"], tool: "httpx", kind: "python-module", source: "run", line: "ModuleNotFoundError: No module named 'httpx'" }, { ids: ["V2"], tool: "TMPDIR", kind: "env-var", source: "env" }]);
+    assert.match(run, /^V4: running it on the base worktree stopped before any test ran: needs Python module 'httpx' \(`ModuleNotFoundError[^`]*`\)[\s\S]*repo's own toolchain .*never a global install/);
+    assert.match(env, /^V2: uses \$TMPDIR, which is unset or empty in the lane environment/);
+  });
+  it("a real run: a missing module is a miss, a failing test is not", async () => {
+    const dir = tmpDir("preflight-run-");
+    const git = async () => "";
+    const contract = C(`node -e "require('absent-pkg-4393')"`, `node -e "process.exit(1)"`);
+    const r = await runPreflight({ contract, run: (a) => runCheckCommand({ ...a, cwd: dir }), git });
+    assert.deepEqual(r.misses.map((m) => [m.ids[0], m.tool]), [["V1", "absent-pkg-4393"]]);
+  });
+});