forgedock 1.30.0 → 1.31.0

package/bin/lean/preflight.mjs

@@ -5,11 +5,15 @@
  * (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" };
+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, `'\\''`)}'`;
@@ -127,7 +131,108 @@ export function preflightProbes(contract, { repoHas = () => false, cap = PREFLIG
   return { probes: all.slice(0, cap), dropped: Math.max(0, all.length - cap) };
 }
 
-/** One contract problem per missed probe: names the validate ids and the tool, and how to fix the plan (never a global install). */
+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) => `${m.ids.join(", ")}: 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; 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`);
+  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

@@ -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 } from "./preflight.mjs";
+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";
@@ -59,3 +59,50 @@ describe("#4328 validate preflight: what a command needs", () => {
     }
   });
 });
+
+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"]]);
+  });
+});

package/bin/lean/probe.mjs

@@ -0,0 +1,297 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Outcome-based acceptance (#4399): an issue may declare an acceptance probe, a command plus its pass condition. Once the
+ * issue's fix is on the default (production) branch, the probe runs deterministically (no model call, no lane), the
+ * result is recorded on the issue as a `FORGE:PROBE` comment, and a fail reopens the issue with the output attached.
+ *
+ * Declaration: a top-level fenced block in the issue body or a comment by a declarer (the latest comment wins):
+ *   ```forge-probe
+ *   run: curl -fsS https://example.com/health
+ *   pass: exit 0            # default; or `pass: /regex/flags` matched against stdout
+ *   timeout: 120            # seconds, capped at 900
+ *   ```
+ * Only declarers' commands run (`isProbeDeclarer`, fail closed): a human trusted association or trusted login, never a
+ * Bot/App, the engine included, since bot-filed text quotes untrusted content (#4468). A block nested in another fence
+ * or indented as code is quoted content, not a declaration. The fix commit is the latest
+ * trusted FORGE:TRAJECTORY `merged at <sha>`, else the merge commit of the latest merged PR that closes the issue; it is
+ * promoted when `git merge-base --is-ancestor <fix> origin/<default>` holds. A recorded result is never re-run for the
+ * same fix. The probe gets a minimal env (PATH, HOME, LANG, TMPDIR) plus forge.yaml `acceptance_probe.env` (the repo's
+ * designated test identity); those values are masked in the posted output.
+ * Triggers: `forgedock probe [issue...]` and a sweep at the start of every `forgedock orchestrate` batch (`--no-probes`).
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseForgeYaml } from "../forge-utils.mjs";
+import { isTrustedComment } from "../engine/phases.mjs";
+import { noComments } from "./render.mjs";
+
+export const PROBE_MARKER = "FORGE:PROBE";
+export const DEFAULT_TIMEOUT_S = 120;
+export const MAX_TIMEOUT_S = 900;
+export const OUTPUT_TAIL = 4000;
+const BASE_ENV = ["PATH", "HOME", "LANG", "TMPDIR"];
+
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const isForgeMarker = (body) => /^\s*<!--\s*FORGE:/.test(String(body ?? ""));
+
+/**
+ * #4468: the contents of the top-level CommonMark fences of `text` whose info string is `forge-probe`. A fence closes on
+ * a line of its own character at least as long; anything inside another fence (a quoted sample) or indented 4+ columns
+ * (an indented code block) is content, never a declaration. An unclosed fence yields nothing.
+ */
+function probeBlocks(text) {
+  const blocks = [];
+  let open = null;
+  for (const line of text.split("\n")) {
+    const m = FENCE_RE.exec(line);
+    if (!open) {
+      if (m && !(m[1][0] === "`" && m[2].includes("`"))) open = { ch: m[1][0], len: m[1].length, lines: m[2].trim() === "forge-probe" ? [] : null };
+    } else if (m && m[1][0] === open.ch && m[1].length >= open.len && !m[2].trim()) {
+      if (open.lines) blocks.push(open.lines.join("\n"));
+      open = null;
+    } else open.lines?.push(line);
+  }
+  return blocks;
+}
+
+/** The last top-level ```forge-probe block of `text`: {run, pass, timeoutS}, or null when absent or malformed. */
+export function parseProbe(text) {
+  const blocks = probeBlocks(noComments(String(text ?? ""), " ").replace(/\r\n?/g, "\n"));
+  if (!blocks.length) return null;
+  const fields = {};
+  for (const line of blocks[blocks.length - 1].split("\n")) {
+    const m = /^\s*(run|pass|timeout)\s*:\s*(.*?)\s*$/i.exec(line);
+    if (m && !(m[1].toLowerCase() in fields)) fields[m[1].toLowerCase()] = m[2];
+  }
+  if (!fields.run) return null;
+  let pass = { kind: "exit" };
+  const p = (fields.pass ?? "").replace(/\s+#.*$/, "");
+  if (p && !/^exit\s+0$/i.test(p)) {
+    const r = /^\/(.+)\/([a-z]*)$/.exec(p);
+    if (!r) return null;
+    try { new RegExp(r[1], r[2]); } catch { return null; }
+    pass = { kind: "regex", re: r[1], flags: r[2] };
+  }
+  let timeoutS = null;
+  if (fields.timeout) {
+    const t = parseInt(fields.timeout, 10);
+    if (!Number.isFinite(t) || t <= 0) return null;
+    timeoutS = Math.min(t, MAX_TIMEOUT_S);
+  }
+  return { run: fields.run, pass, timeoutS };
+}
+
+/** REST issue/comment author fields as the trust predicate reads them. */
+const actorOf = (o) => ({ association: o?.author_association, type: o?.user?.type, login: o?.user?.login });
+
+/**
+ * #4468: who may declare a probe, a command the host runs. Unlike `isTrustedActor` (which trusts every Bot so engine
+ * markers count), only a human: association in FORGE_TRAIL_TRUSTED_ASSOCIATIONS (default OWNER,MEMBER,COLLABORATOR;
+ * explicitly empty trusts none) or login in FORGE_TRAIL_TRUSTED_LOGINS, never a Bot/App or `[bot]` login, the engine
+ * included: the issues it files quote untrusted PR content. Missing author data fails closed.
+ */
+export function isProbeDeclarer({ association, type, login } = {}) {
+  if (!type || type === "Bot" || /\[bot\]$/i.test(String(login ?? ""))) return false;
+  const list = (v) => String(v).split(",").map((x) => x.trim()).filter(Boolean);
+  return list(process.env.FORGE_TRAIL_TRUSTED_ASSOCIATIONS ?? "OWNER,MEMBER,COLLABORATOR").includes(association ?? "")
+    || list(process.env.FORGE_TRAIL_TRUSTED_LOGINS ?? "").includes(login ?? "");
+}
+
+/**
+ * The probe the issue declares: the latest declarer comment's block, else the body's when its author is a declarer.
+ * {probe, source} | {untrusted: true} (a block exists but only from non-declarers) | null.
+ */
+export function declaredProbe(iss) {
+  let untrusted = false;
+  for (const c of [...(iss?.comments ?? [])].reverse()) {
+    if (isForgeMarker(c?.body)) continue; // the engine's own comments (a FORGE:PROBE output tail) never declare a probe
+    const probe = parseProbe(c?.body);
+    if (!probe) continue;
+    if (isProbeDeclarer(actorOf(c))) return { probe, source: "comment" };
+    untrusted = true;
+  }
+  const probe = parseProbe(iss?.body);
+  if (probe) {
+    if (isProbeDeclarer(actorOf(iss))) return { probe, source: "body" };
+    untrusted = true;
+  }
+  return untrusted ? { untrusted: true } : null;
+}
+
+/** {fix, result} of a FORGE:PROBE comment body, or null. */
+export function probeResultOf(body) {
+  const s = String(body ?? "");
+  if (!s.trimStart().startsWith(`<!-- ${PROBE_MARKER} -->`)) return null;
+  const line = s.split("\n").find((l) => /^\s*`?\{.*"result"/.test(l));
+  if (!line) return null;
+  try {
+    const j = JSON.parse(line.trim().replace(/^`|`$/g, ""));
+    return j && (j.result === "pass" || j.result === "fail") ? { fix: String(j.fix ?? ""), result: j.result } : null;
+  } catch { return null; }
+}
+
+const sameSha = (a, b) => !!a && !!b && (a.startsWith(b) || b.startsWith(a));
+const closesRe = (n) => new RegExp(`\\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\b:?\\s+(?:[\\w.-]+/[\\w.-]+)?#${n}(?!\\d)`, "i");
+
+/** The fix commit: latest trusted FORGE:TRAJECTORY `merged at <sha>`, else the latest merged PR closing #N's merge commit. */
+export async function fixSha(iss, io, repo) {
+  for (const c of [...(iss?.comments ?? [])].reverse()) {
+    if (!String(c?.body ?? "").includes("FORGE:TRAJECTORY") || !isTrustedComment(c)) continue;
+    const m = /merged at ([0-9a-f]{7,40})\b/.exec(c.body);
+    if (m) return m[1];
+  }
+  try {
+    const prs = JSON.parse(String(await io.gh(["pr", "list", "-R", repo, "--state", "merged", "--search", `#${iss.number}`, "--json", "number,title,body,mergeCommit,mergedAt", "--limit", "20"])));
+    const hit = (Array.isArray(prs) ? prs : []).filter((p) => p?.mergeCommit?.oid && closesRe(iss.number).test(`${p.title ?? ""}\n${p.body ?? ""}`))
+      .sort((a, b) => String(b.mergedAt ?? "").localeCompare(String(a.mergedAt ?? "")))[0];
+    return hit?.mergeCommit?.oid ?? null;
+  } catch { return null; }
+}
+
+/** True when `sha` is an ancestor of origin/<defaultBranch>; any git failure (unknown object) is false. */
+export async function onDefault({ sha, defaultBranch, io, cwd }) {
+  try { await io.git(["merge-base", "--is-ancestor", sha, `origin/${defaultBranch}`], { cwd }); return true; } catch { return false; }
+}
+
+/** forge.yaml `acceptance_probe`: {env: [names], timeoutS, sweepDays, enabled}. */
+export function readProbeConfig(cwd = process.cwd()) {
+  let c = {};
+  try { c = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.acceptance_probe ?? {}; } catch { c = {}; }
+  if (typeof c !== "object" || !c) c = {};
+  const list = Array.isArray(c.env) ? c.env : String(c.env ?? "").replace(/^\[|\]$/g, "").split(/[\s,]+/);
+  const num = (v, d) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : d);
+  return {
+    env: list.map((s) => String(s).trim().replace(/^["']|["']$/g, "")).filter((s) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s)),
+    timeoutS: Math.min(num(c.timeout_s, DEFAULT_TIMEOUT_S), MAX_TIMEOUT_S),
+    sweepDays: num(c.sweep_days, 30),
+    enabled: !/^(false|no|off|0)$/i.test(String(c.enabled ?? "true").trim()),
+  };
+}
+
+/** The probe's environment: the base names plus the allowlisted test identity, nothing else. */
+export function probeEnv(allow = [], env = process.env) {
+  return Object.fromEntries([...BASE_ENV, ...allow].filter((k) => typeof env[k] === "string").map((k) => [k, env[k]]));
+}
+
+/** Run `sh -c <run>` in its own process group; a timeout kills the group. Resolves {code, stdout, stderr, timedOut}. */
+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 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); });
+    const timer = setTimeout(() => { timedOut = true; try { process.kill(-child.pid, "SIGKILL"); } catch { /* gone */ } }, timeoutMs);
+    child.on("error", (e) => { clearTimeout(timer); resolve({ code: 127, stdout, stderr: `${stderr}${e.message}`, timedOut }); });
+    child.on("close", (code) => { clearTimeout(timer); resolve({ code: code ?? 1, stdout, stderr, timedOut }); });
+  });
+}
+
+/** Run a probe: {result: pass|fail, exit, ms, output}. The output tail masks the allowlisted env values. */
+export async function runProbe(probe, { cwd, env = {}, mask = [], timeoutS = DEFAULT_TIMEOUT_S, spawn = spawnProbe, now = () => Date.now() } = {}) {
+  const t0 = now();
+  const r = await spawn({ run: probe.run, cwd, env, timeoutMs: (probe.timeoutS ?? timeoutS) * 1000 });
+  const ms = now() - t0;
+  let ok = !r.timedOut && r.code === 0;
+  if (!r.timedOut && probe.pass?.kind === "regex") ok = new RegExp(probe.pass.re, probe.pass.flags).test(String(r.stdout ?? ""));
+  let output = `${r.stdout ?? ""}${r.stderr ? `\n${r.stderr}` : ""}${r.timedOut ? `\n[timed out after ${probe.timeoutS ?? timeoutS}s]` : ""}`;
+  for (const v of mask) if (typeof v === "string" && v.length >= 4) output = output.split(v).join("***");
+  return { result: ok ? "pass" : "fail", exit: r.timedOut ? null : r.code, ms, output: output.slice(-OUTPUT_TAIL) };
+}
+
+/** The FORGE:PROBE comment. */
+export function renderProbeComment({ probe, fix, defaultBranch, defaultSha, r }) {
+  const fence = "`".repeat(Math.max(3, ...[...String(r.output).matchAll(/`+/g)].map((m) => m[0].length + 1)));
+  const pass = probe.pass?.kind === "regex" ? `stdout matches \`/${probe.pass.re}/${probe.pass.flags}\`` : "exit 0";
+  return [
+    `<!-- ${PROBE_MARKER} -->`,
+    `## Acceptance probe: ${r.result}`,
+    JSON.stringify({ fix, default_sha: defaultSha, result: r.result, exit: r.exit, ms: r.ms }),
+    "",
+    `Ran after the fix \`${String(fix).slice(0, 12)}\` reached \`${defaultBranch}\`. Pass condition: ${pass}.${r.result === "fail" ? " The issue is reopened." : ""}`,
+    "",
+    fence, r.output.trim() || "(no output)", fence,
+  ].join("\n");
+}
+
+/** Read the issue (REST, for author_association) and its comments. */
+async function readIssue(issue, repo, io) {
+  const iss = JSON.parse(String(await io.gh(["api", `repos/${repo}/issues/${issue}`])));
+  const raw = String(await io.gh(["api", `repos/${repo}/issues/${issue}/comments`, "--paginate", "--jq", ".[]"]));
+  const comments = raw.split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l));
+  return { ...iss, number: issue, comments };
+}
+
+/**
+ * Probe one issue. Outcomes: no-probe | untrusted | unresolved | already-recorded | awaiting-promotion | pass | fail.
+ * Writes (comment, reopen) only for pass/fail and never with `dryRun`.
+ */
+export async function probeIssue({ issue, repo, cwd = process.cwd(), io, defaultBranch, dryRun = false, config = readProbeConfig(cwd), env = process.env, spawn }) {
+  const row = (outcome, detail = "", extra = {}) => ({ issue, outcome, detail, ...extra });
+  const iss = await readIssue(issue, repo, io);
+  const d = declaredProbe(iss);
+  if (!d) return row("no-probe");
+  if (d.untrusted) return row("untrusted", "forge-probe declared only by untrusted actors; not run");
+  const fix = await fixSha(iss, io, repo);
+  if (!fix) return row("unresolved", "no fix commit found (FORGE:TRAJECTORY or a merged closing PR)");
+  const recorded = iss.comments.filter((c) => isTrustedComment(c)).map((c) => probeResultOf(c.body)).filter(Boolean).reverse()
+    .find((p) => sameSha(p.fix, fix));
+  if (recorded) return row("already-recorded", `${recorded.result} for ${fix.slice(0, 12)}`, { fix });
+  if (!(await onDefault({ sha: fix, defaultBranch, io, cwd }))) return row("awaiting-promotion", `fix ${fix.slice(0, 12)} is not on ${defaultBranch}`, { fix });
+  let defaultSha = null;
+  try { defaultSha = String(await io.git(["rev-parse", `origin/${defaultBranch}`], { cwd })).trim() || null; } catch { /* recorded as null */ }
+  const r = await runProbe(d.probe, { cwd, env: probeEnv(config.env, env), mask: config.env.map((k) => env[k]), timeoutS: config.timeoutS, ...(spawn ? { spawn } : {}) });
+  const detail = `exit ${r.exit ?? "timeout"} in ${r.ms}ms`;
+  if (dryRun) return row(r.result, `${detail} (dry run: not recorded)`, { fix, output: r.output });
+  const body = renderProbeComment({ probe: d.probe, fix, defaultBranch, defaultSha, r });
+  let note = "";
+  if (r.result === "fail") {
+    try { await io.gh(["issue", "reopen", String(issue), "-R", repo]); } catch (e) { note = `; reopen failed: ${String(e?.message ?? e).slice(0, 120)}`; }
+  }
+  await io.gh(["issue", "comment", String(issue), "-R", repo, "--body", body]);
+  return row(r.result, detail + note, { fix });
+}
+
+/** The default branch: forge.yaml `branches.default`, else GitHub's. */
+export async function resolveDefaultBranch({ repo, io, cwd = process.cwd() }) {
+  try {
+    const b = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.branches?.default;
+    if (typeof b === "string" && b.trim()) return b.trim();
+  } catch { /* GitHub's */ }
+  return String(await io.gh(["repo", "view", repo, "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"])).trim() || null;
+}
+
+/**
+ * Probe `issues`, or (none given) the issues closed within `sweepDays` that mention `forge-probe`, capped at `limit`.
+ * Sequential: probes hit production. Never throws per issue: an error is an `error` row.
+ */
+export async function sweepProbes({ repo, cwd = process.cwd(), io, issues = null, limit = 50, sinceDays = null, dryRun = false, config = readProbeConfig(cwd), now = () => Date.now(), env = process.env, spawn } = {}) {
+  if (!config.enabled && !issues?.length) return [];
+  const defaultBranch = await resolveDefaultBranch({ repo, io, cwd });
+  if (!defaultBranch) throw new Error("no default branch");
+  let list = issues;
+  if (!list?.length) {
+    const since = new Date(now() - (sinceDays ?? config.sweepDays) * 86400000).toISOString().slice(0, 10);
+    const found = JSON.parse(String(await io.gh(["issue", "list", "-R", repo, "--state", "closed", "--search", `forge-probe in:body,comments closed:>=${since}`, "--limit", String(limit), "--json", "number"])));
+    list = (Array.isArray(found) ? found : []).map((i) => i.number).filter(Number.isInteger);
+  }
+  if (!list.length) return [];
+  try { await io.git(["fetch", "origin", defaultBranch], { cwd }); } catch { /* offline: the local ref */ }
+  const rows = [];
+  for (const issue of list) {
+    try { rows.push(await probeIssue({ issue, repo, cwd, io, defaultBranch, dryRun, config, env, spawn })); } catch (e) {
+      rows.push({ issue, outcome: "error", detail: String(e?.message ?? e).slice(0, 160) });
+    }
+  }
+  return rows;
+}
+
+const GROUPS = [["pass", "pass"], ["fail", "fail (reopened)"], ["awaiting-promotion", "awaiting promotion"], ["unresolved", "unresolved fix"], ["untrusted", "untrusted (not run)"], ["error", "error"]];
+/** One line, e.g. `probes: pass #A; fail (reopened) #B; awaiting promotion #C`; "" when nothing ran or waits. */
+export function formatProbeSummary(rows) {
+  const parts = GROUPS.map(([k, label]) => [label, (rows ?? []).filter((r) => r.outcome === k).map((r) => `#${r.issue}`)])
+    .filter(([, l]) => l.length).map(([label, l]) => `${label} ${l.join(" ")}`);
+  return parts.length ? `probes: ${parts.join("; ")}` : "";
+}