forgedock 1.41.0 → 1.43.0

package/bin/lean/selftest-nightly.mjs

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Opt-in nightly `selftest --live` (#4894), started from schedd's due callback on the host (never GitHub Actions). Off unless
+// forge.yaml `selftest.nightly_interval_hours` is a positive number. The daemon only decides it is due and launches a
+// detached `forgedock selftest --live --nightly-report <repo>`: the harness itself talks to schedd (orchestrate --add), so
+// running it inside the daemon's event loop would deadlock it, and a 45-minute run would hold the due pass. A failing run
+// (or one that cannot start, e.g. no sandbox repo) files ONE issue naming the failed step; the next failure edits it.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { schedDir } from "./sched.mjs";
+
+export const NIGHTLY_MARKER = "<!-- FORGE:SELFTEST_NIGHTLY -->";
+const neutralize = (s) => String(s ?? "").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/** One last-run file per repo: two repos on one host never share (and so never skip) each other's schedule. */
+const stateFile = (repo) => `selftest-nightly-${String(repo).replace(/[^\w.-]+/g, "_")}.json`;
+
+/** Interval in hours from the forge.yaml text, or null when the key is unset, zero or not a number (= nothing scheduled). */
+export function nightlyConfig(raw) {
+  const sec = String(raw ?? "").split(/^selftest:/m)[1]?.split(/^\S/m)[0] ?? "";
+  const h = Number(/^\s+nightly_interval_hours:\s*["']?([\d.]+)/m.exec(sec)?.[1]);
+  return h > 0 ? h : null;
+}
+
+function readLast(dir, repo) {
+  try { return Number(JSON.parse(readFileSync(join(dir, stateFile(repo)), "utf8")).lastRun) || 0; } catch { return 0; }
+}
+function writeLast(dir, repo, ts) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, stateFile(repo)), JSON.stringify({ lastRun: ts }));
+}
+
+/**
+ * Start `node <cli> selftest --live --nightly-report <repo>` detached, from the daemon. A spawn failure (EAGAIN, EMFILE,
+ * a vanished cwd) arrives as an async 'error' event: without a listener it is an uncaught exception, which stops schedd.
+ * It is swallowed here; that night's run is lost, never the daemon.
+ */
+export function launchNightly({ cli, repo, cwd = process.cwd(), spawnFn = spawn }) {
+  try {
+    const c = spawnFn(process.execPath, [cli, "selftest", "--live", "--nightly-report", repo], { cwd, detached: true, stdio: "ignore" });
+    c.on("error", () => {});
+    c.unref();
+    return c;
+  } catch { return null; }
+}
+
+/** File (or edit) the one nightly failure issue in `repo`. `result` is {step, message}. @returns {Promise<{issue:?number, action:"create"|"edit"}>} */
+export async function reportNightly({ repo, io, now = () => Date.now(), result }) {
+  const step = result?.step ?? "unknown";
+  const title = `selftest --live failed at step ${step} (nightly)`;
+  const body = `The nightly \`forgedock selftest --live\` failed at step **${neutralize(step)}**.\n\n${neutralize(String(result?.message ?? "").slice(0, 2000))}\n\nLast failure: ${new Date(now()).toISOString()}\n\n${NIGHTLY_MARKER}\n`;
+  const open = JSON.parse(String(await io.gh(["issue", "list", "-R", repo, "--state", "open", "--search", `"FORGE:SELFTEST_NIGHTLY" in:body`, "--limit", "30", "--json", "number,body"])))
+    .find((i) => String(i.body ?? "").includes(NIGHTLY_MARKER));
+  if (open) {
+    await io.gh(["issue", "edit", String(open.number), "-R", repo, "--title", title, "--body", body]);
+    return { issue: open.number, action: "edit" };
+  }
+  const out = await io.gh(["issue", "create", "-R", repo, "--title", title, "--body", body]);
+  return { issue: Number(/(\d+)\s*$/.exec(String(out).trim())?.[1]) || null, action: "create" };
+}
+
+/**
+ * One schedd pass. With `launch` (the daemon) it only starts the detached run and returns {ran, launched}; with `runLive`
+ * (tests, or an in-process caller) it awaits {ok, step, message} and files the failure. A harness that throws is a
+ * failure at step "harness", never silent. Never throws.
+ * @returns {Promise<{ran:boolean, launched?:boolean, ok?:boolean, issue?:?number, action?:"create"|"edit"}>}
+ */
+export async function nightlyDue({ repo, cwd = process.cwd(), io, now = () => Date.now(), runLive, launch, stateDir = schedDir() } = {}) {
+  try {
+    const file = join(cwd, "forge.yaml");
+    const hours = nightlyConfig(existsSync(file) ? readFileSync(file, "utf8") : "");
+    if (!hours || !repo) return { ran: false };
+    if (now() - readLast(stateDir, repo) < hours * 3600_000) return { ran: false };
+    writeLast(stateDir, repo, now()); // before the run: a crashing harness must not re-run every 15 min
+    if (launch) { launch(); return { ran: true, launched: true }; }
+    let r;
+    try { r = await runLive(); } catch (e) { r = { ok: false, step: "harness", message: String(e?.message ?? e) }; }
+    if (r.ok) return { ran: true, ok: true };
+    return { ran: true, ok: false, ...(await reportNightly({ repo, io, now, result: r })) };
+  } catch { return { ran: false }; }
+}

package/bin/lean/selftest-nightly.test.mjs

@@ -0,0 +1,84 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { EventEmitter } from "node:events";
+import { nightlyConfig, nightlyDue, launchNightly, NIGHTLY_MARKER } from "./selftest-nightly.mjs";
+
+const setup = (yaml) => { const cwd = tmpDir("nt-"), stateDir = tmpDir("ns-"); if (yaml) writeFileSync(join(cwd, "forge.yaml"), yaml); return { cwd, stateDir }; };
+const YAML = "selftest:\n  sandbox_repo: a/b\n  nightly_interval_hours: 24\n";
+const fakeIo = (open = []) => { const calls = []; return { calls, gh: async (a) => { calls.push(a); if (a[1] === "list") return JSON.stringify(open); if (a[1] === "create") return "https://github.com/o/r/issues/77\n"; return ""; } }; };
+
+test("nightlyConfig: unset, zero and other sections are off", () => {
+  assert.equal(nightlyConfig(""), null);
+  assert.equal(nightlyConfig("selftest:\n  sandbox_repo: a/b\n"), null);
+  assert.equal(nightlyConfig("selftest:\n  nightly_interval_hours: 0\n"), null);
+  assert.equal(nightlyConfig("other:\n  nightly_interval_hours: 5\n"), null);
+  assert.equal(nightlyConfig(YAML), 24);
+});
+
+test("key unset: nothing is scheduled", async () => {
+  const s = setup("selftest:\n  sandbox_repo: a/b\n"); let n = 0;
+  const r = await nightlyDue({ ...s, repo: "o/r", io: fakeIo(), runLive: async () => { n++; return { ok: true }; } });
+  assert.equal(r.ran, false); assert.equal(n, 0);
+});
+
+test("key set: runs when due, not again within the interval", async () => {
+  const s = setup(YAML); let n = 0, t = 1e13;
+  const run = () => nightlyDue({ ...s, repo: "o/r", io: fakeIo(), now: () => t, runLive: async () => { n++; return { ok: true }; } });
+  assert.equal((await run()).ran, true);
+  t += 3600_000; assert.equal((await run()).ran, false);
+  t += 24 * 3600_000; assert.equal((await run()).ran, true);
+  assert.equal(n, 2);
+});
+
+test("failure files one issue naming the step; the second failure edits it", async () => {
+  const s = setup(YAML); let t = 1e13;
+  const io1 = fakeIo();
+  const r1 = await nightlyDue({ ...s, repo: "o/r", io: io1, now: () => t, runLive: async () => ({ ok: false, step: "body", message: "lost <!-- x --> body" }) });
+  assert.deepEqual([r1.action, r1.issue], ["create", 77]);
+  const create = io1.calls.find((a) => a[1] === "create");
+  assert.match(create.join(" "), /step body/); assert.ok(create.join(" ").includes(NIGHTLY_MARKER));
+  assert.ok(!create[create.indexOf("--body") + 1].includes("<!-- x"));
+  t += 25 * 3600_000;
+  const io2 = fakeIo([{ number: 77, body: `x\n${NIGHTLY_MARKER}` }]);
+  const r2 = await nightlyDue({ ...s, repo: "o/r", io: io2, now: () => t, runLive: async () => ({ ok: false, step: "add", message: "m" }) });
+  assert.deepEqual([r2.action, r2.issue], ["edit", 77]);
+  assert.ok(!io2.calls.some((a) => a[1] === "create"));
+  assert.match(io2.calls.find((a) => a[1] === "edit").join(" "), /step add/);
+});
+
+test("a passing run writes no issue; a throwing harness is reported, never silent", async () => {
+  const s = setup(YAML), io = fakeIo();
+  await nightlyDue({ ...s, repo: "o/r", io, runLive: async () => ({ ok: true }) });
+  assert.equal(io.calls.length, 0);
+  const s2 = setup(YAML), io2 = fakeIo();
+  const r = await nightlyDue({ ...s2, repo: "o/r", io: io2, runLive: async () => { throw new Error("boom"); } });
+  assert.deepEqual([r.ran, r.ok, r.action], [true, false, "create"]);
+  assert.match(io2.calls.find((a) => a[1] === "create").join(" "), /step harness/);
+});
+
+test("with launch (the daemon) the run is only started, detached: nothing is awaited or filed in-process", async () => {
+  const s = setup(YAML), io = fakeIo(); let launched = 0;
+  const r = await nightlyDue({ ...s, repo: "o/r", io, launch: () => { launched++; }, runLive: async () => { throw new Error("must not run"); } });
+  assert.deepEqual(r, { ran: true, launched: true }); assert.equal(launched, 1); assert.equal(io.calls.length, 0);
+  assert.equal((await nightlyDue({ ...s, repo: "o/r", io, launch: () => { launched++; } })).ran, false, "not again within the interval");
+});
+
+test("the schedule is per repo: one repo's run never skips another's", async () => {
+  const s = setup(YAML); let n = 0; const t = 1e13;
+  const run = (repo) => nightlyDue({ ...s, repo, io: fakeIo(), now: () => t, runLive: async () => { n++; return { ok: true }; } });
+  assert.equal((await run("o/a")).ran, true); assert.equal((await run("o/b")).ran, true); assert.equal(n, 2);
+});
+
+test("launchNightly: detached, unref'd, and an async spawn error never escapes (it would stop schedd)", async () => {
+  let args = null, unrefd = false;
+  const child = new EventEmitter(); child.unref = () => { unrefd = true; };
+  const c = launchNightly({ cli: "/x/forgedock.mjs", repo: "o/r", cwd: "/tmp", spawnFn: (...a) => { args = a; return child; } });
+  assert.equal(c, child); assert.ok(unrefd);
+  assert.deepEqual(args[1], ["/x/forgedock.mjs", "selftest", "--live", "--nightly-report", "o/r"]);
+  assert.equal(args[2].detached, true); assert.equal(args[2].stdio, "ignore");
+  assert.doesNotThrow(() => child.emit("error", Object.assign(new Error("spawn EAGAIN"), { code: "EAGAIN" })));
+  assert.equal(launchNightly({ cli: "c", repo: "o/r", spawnFn: () => { throw new Error("EMFILE"); } }), null);
+});

package/bin/lean/selftest-static.mjs

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Static half of `forgedock selftest` (#4865): every `gh issue|pr view|list --json a,b` field list in bin/ must be a
+// subset of the fields `gh <cmd> --help` advertises on this host (#4859: `authorAssociation` is not a gh field).
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+
+/** Non-test .mjs files under `dir`, recursively (node_modules skipped). */
+export function listSources(dir) {
+  const out = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === "node_modules") continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...listSources(p));
+    else if (e.name.endsWith(".mjs") && !/\.test\.mjs$/.test(e.name)) out.push(p);
+  }
+  return out.sort();
+}
+
+/** @returns {{cmd:string, fields:string[], line:number}[]} the literal gh `--json` field lists of `text` (cmd e.g. "issue view"). */
+export function extractJsonFields(text) {
+  const out = [];
+  const re = /\[([^[\]]*?)["'`]--json["'`]\s*,\s*["'`]([A-Za-z0-9_,]+)["'`]/g;
+  for (let m; (m = re.exec(text));) {
+    const words = [...m[1].matchAll(/["'`]([a-z-]+)["'`]/g)].map((x) => x[1]);
+    const i = words.findIndex((w, k) => (w === "issue" || w === "pr") && (words[k + 1] === "view" || words[k + 1] === "list"));
+    if (i < 0) continue;
+    out.push({ cmd: `${words[i]} ${words[i + 1]}`, fields: m[2].split(",").filter(Boolean), line: text.slice(0, m.index).split("\n").length });
+  }
+  return out;
+}
+
+/** The field names of the `JSON FIELDS` section of `gh <cmd> --help`. */
+export function parseHelpFields(help) {
+  const lines = String(help).split("\n");
+  const at = lines.findIndex((l) => /^\s*JSON FIELDS\s*$/i.test(l));
+  if (at < 0) return [];
+  const out = [];
+  for (const l of lines.slice(at + 1)) {
+    if (!l.trim()) { if (out.length) break; continue; }
+    if (!/^\s/.test(l)) break;
+    out.push(...l.split(",").map((s) => s.trim()).filter(Boolean));
+  }
+  return out;
+}
+
+/**
+ * @param {{root:string, io:{gh:(args:string[])=>string, read?:(p:string)=>string, list?:(d:string)=>string[]}}} a
+ * @returns {{ok:boolean, checked:number, missing:{file:string,line:number,cmd:string,field:string}[], errors:string[]}}
+ */
+export function staticCheck({ root, io }) {
+  const read = io.read ?? ((p) => readFileSync(p, "utf8")), list = io.list ?? listSources;
+  const known = new Map(), errors = [], missing = [];
+  let checked = 0;
+  for (const file of list(root)) {
+    for (const u of extractJsonFields(read(file))) {
+      if (!known.has(u.cmd)) {
+        let fields = [];
+        try { fields = parseHelpFields(io.gh([...u.cmd.split(" "), "--help"])); } catch (e) { errors.push(`gh ${u.cmd} --help failed: ${e.message}`); }
+        if (!fields.length && !errors.length) errors.push(`gh ${u.cmd} --help lists no JSON fields`);
+        known.set(u.cmd, new Set(fields));
+      }
+      const set = known.get(u.cmd);
+      if (!set.size) continue;
+      checked++;
+      for (const field of u.fields) if (!set.has(field)) missing.push({ file, line: u.line, cmd: u.cmd, field });
+    }
+  }
+  return { ok: !missing.length && !errors.length, checked, missing, errors };
+}
+
+export const realGh = (args) => execFileSync("gh", args, { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 });
+
+export function formatStatic(r) {
+  return [
+    ...r.missing.map((m) => `${m.file}:${m.line}: gh ${m.cmd} --json field "${m.field}" is not offered by this gh`),
+    ...r.errors,
+    `static check: ${r.ok ? "ok" : "FAILED"} (${r.checked} field lists checked)`,
+  ].join("\n");
+}

package/bin/lean/selftest-static.test.mjs

@@ -0,0 +1,32 @@
+// 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 { extractJsonFields, parseHelpFields, staticCheck, formatStatic } from "./selftest-static.mjs";
+
+const HELP = "Usage\n\nJSON FIELDS\n  author, body, number,\n  title\n\nARGUMENTS\n  none\n";
+const gh = (args) => { if (args[0] === "issue" || args[0] === "pr") return HELP; throw new Error("no"); };
+
+describe("selftest static check (#4865)", () => {
+  it("extracts only gh issue|pr view|list field lists", () => {
+    const t = `x\nawait io.gh(["issue", "view", String(n), "--json", "body,title"]);\nrun(["repo", "view", "--json", "nameWithOwner"]);\ngh(["pr", "list", "--json", "number"])`;
+    assert.deepEqual(extractJsonFields(t), [{ cmd: "issue view", fields: ["body", "title"], line: 2 }, { cmd: "pr list", fields: ["number"], line: 4 }]);
+  });
+  it("parses the JSON FIELDS section of the help", () => {
+    assert.deepEqual(parseHelpFields(HELP), ["author", "body", "number", "title"]);
+  });
+  it("fails on a bogus field (#4859 authorAssociation) and names file:line", () => {
+    const r = staticCheck({ root: "/bin", io: { gh, list: () => ["/bin/a.mjs"], read: () => 'gh(["issue", "list", "--json", "number,authorAssociation"])' } });
+    assert.equal(r.ok, false);
+    assert.deepEqual(r.missing, [{ file: "/bin/a.mjs", line: 1, cmd: "issue list", field: "authorAssociation" }]);
+    assert.match(formatStatic(r), /a\.mjs:1: gh issue list --json field "authorAssociation"/);
+  });
+  it("passes when every field is offered", () => {
+    const r = staticCheck({ root: "/bin", io: { gh, list: () => ["/bin/a.mjs"], read: () => 'gh(["pr", "view", "1", "--json", "title,body"])' } });
+    assert.equal(r.ok, true); assert.equal(r.checked, 1);
+  });
+  it("fails closed when gh help cannot be read", () => {
+    const r = staticCheck({ root: "/bin", io: { gh: () => { throw new Error("no gh"); }, list: () => ["/a.mjs"], read: () => 'x(["pr", "view", "--json", "title"])' } });
+    assert.equal(r.ok, false);
+  });
+});

package/bin/lean/toolstate.mjs

@@ -51,14 +51,30 @@ export async function unstageToolState(git) {
   return stray.length ? (await git(["diff", "--cached", "--name-only"])).trim() !== "" : staged.length > 0;
 }
 
+const REQUIREMENTS_EXPORT = /^requirements([-_.][\w.-]+)?\.txt$/;
+
+/**
+ * #4959: `requirements*.txt` files the branch added to a Poetry/uv project (pyproject [tool.poetry], or poetry.lock / uv.lock at
+ * the base) that the base does not track and the contract does not list (`keep`): an export generated to run local tests.
+ */
+export async function strayGenerated(git, ref, added, keep = []) {
+  const cands = added.filter((p) => REQUIREMENTS_EXPORT.test(base(p)) && !keep.includes(p));
+  if (!cands.length) return [];
+  const tracked = zlist(await git(["ls-tree", "-r", "--name-only", "-z", ref]));
+  const managed = tracked.some((f) => /(^|\/)(poetry|uv)\.lock$/.test(f))
+    || (await Promise.all(tracked.filter((f) => /(^|\/)pyproject\.toml$/.test(f)).map((f) => git(["show", `${ref}:${f}`]).catch(() => "")))).some((t) => /^\[tool\.poetry[\].]/m.test(String(t)));
+  return managed ? cands : [];
+}
+
 /**
  * Remove from the index (and commit) the deny-listed files this branch added against `base`. Returns the removed paths ([]
- * when the branch is clean). Never throws: a failure leaves the branch as it was and the push proceeds.
+ * when the branch is clean). `keep`: contract deliverable paths, never removed as generated files. Never throws: a failure
+ * leaves the branch as it was and the push proceeds.
  */
-export async function untrackToolState({ git, base: ref, ev = () => {} }) {
+export async function untrackToolState({ git, base: ref, ev = () => {}, keep = [] }) {
   try {
     const added = zlist(await git(["diff", "--diff-filter=A", "--name-only", "-z", `${ref}...HEAD`]));
-    const stray = await strayPaths(git, added);
+    const stray = [...await strayPaths(git, added), ...await strayGenerated(git, ref, added, keep)];
     if (!stray.length) return [];
     await git(["rm", "--cached", "-r", "-q", "--ignore-unmatch", "--", ...stray]);
     await git(["commit", "--no-verify", "-m", "chore: untrack lane tool state (#4590)", "-m", stray.slice(0, 20).join("\n")]);

package/bin/lean/toolstate.test.mjs

@@ -112,3 +112,25 @@ describe("lane scratch is untracked and cleared (#4880)", () => {
     assert.equal(execFileSync("git", ["ls-files", ".forge-lean"], { cwd: root, encoding: "utf8" }).trim(), "");
   });
 });
+
+describe("generated requirements.txt is untracked in a Poetry project (#4959)", () => {
+  const lane = (poetry, files) => {
+    const d = tmpDir("toolstate-poetry-");
+    sh(d, "init", "-q", "-b", "main"); sh(d, "config", "user.email", "t@t"); sh(d, "config", "user.name", "t");
+    put(d, "pyproject.toml", poetry ? "[tool.poetry]\nname = \"x\"\n" : "[project]\nname = \"x\"\n");
+    sh(d, "add", "-A"); sh(d, "commit", "-q", "-m", "base"); sh(d, "checkout", "-q", "-b", "lane");
+    for (const f of files) put(d, f);
+    sh(d, "add", "-A"); sh(d, "commit", "-q", "-m", "lane");
+    return d;
+  };
+  it("drops an added requirements.txt, keeps product files and contract-listed ones", async () => {
+    const d = lane(true, ["services/worker/requirements.txt", "services/worker/app.py", "services/api/requirements.txt"]);
+    const removed = await untrackToolState({ git: gitIn(d), base: "main", keep: ["services/api/requirements.txt"] });
+    assert.deepEqual(removed, ["services/worker/requirements.txt"]);
+    assert.deepEqual(sh(d, "diff", "--name-only", "main...HEAD").trim().split("\n"), ["services/api/requirements.txt", "services/worker/app.py"]);
+  });
+  it("a non-Poetry project is untouched", async () => {
+    const d = lane(false, ["requirements.txt"]);
+    assert.deepEqual(await untrackToolState({ git: gitIn(d), base: "main" }), []);
+  });
+});

package/bin/lean/verify.mjs

@@ -60,7 +60,15 @@ export function parseVerify(sec = {}) {
   const flaky = [...new Set(rawFlaky.map((x) => String(x ?? "").trim().replace(/^(["'])(.*)\1$/s, "$2").trim()).filter(Boolean))];
   const duplicateExports = str(s.duplicate_exports).toLowerCase() !== "false";
   const invariants = [...new Set((Array.isArray(s.invariants) ? s.invariants : []).map((x) => String(x ?? "").trim()).filter(Boolean))];
-  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds, precheckTotalSeconds, checkRun, checks, postMerge, flaky, duplicateExports, invariants, e2e: parseE2e(s) };
+  // #4792: guard_command maps an extension (`.py` or `py`) to a test-file command template; read by engine-cli readYamlMap; the key is omitted when empty so unconfigured repos parse as before
+  const guardCommand = {};
+  if (s.guard_command && typeof s.guard_command === "object" && !Array.isArray(s.guard_command)) {
+    for (const [k, v] of Object.entries(s.guard_command)) {
+      const ext = String(k).trim().toLowerCase().replace(/^\.?/, "."), cmd = str(v);
+      if (ext.length > 1 && cmd) guardCommand[ext] = cmd;
+    }
+  }
+  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds, precheckTotalSeconds, checkRun, checks, postMerge, flaky, duplicateExports, invariants, ...(Object.keys(guardCommand).length ? { guardCommand } : {}), e2e: parseE2e(s) };
 }
 
 const globRe = (g) => new RegExp(`^${g.split("**").map((p) => p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")).join(".*")}$`);

package/bin/lean/verify.test.mjs

@@ -22,6 +22,10 @@ function fake(o = {}) {
 }
 
 describe("verify-by-CI config (#4167)", () => {
+  it("parseVerify normalises guard_command extensions and drops empty values (#4792)", () => {
+    assert.deepEqual(parseVerify({ guard_command: { PY: " scripts/pytest {path} ", ".js": "", "": "x" } }).guardCommand, { ".py": "scripts/pytest {path}" });
+    assert.equal("guardCommand" in parseVerify({ guard_command: "nope" }), false);
+  });
   it("parseVerify defaults to local and rejects invalid values", () => {
     assert.deepEqual(parseVerify({}), { mode: "local", workflow: null, pathsInput: null, skipPaths: [...DEFAULT_SKIP_PATHS], maxRounds: 2, precheckTimeoutSeconds: 300, precheckTotalSeconds: 600, checkRun: false, checks: null, postMerge: null, flaky: [], duplicateExports: true, invariants: [], e2e: parseE2e({}) });
     const v = parseVerify({ mode: "ci", workflow: ".github/workflows/verify.yml", paths_input: "changed_paths", skip_paths: "*.md, docs/** ,", max_rounds: "3" });

package/bin/review-staging.mjs

@@ -26,12 +26,15 @@ import * as nodeFs from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseForgeYaml } from "./forge-utils.mjs";
+import { selftestGate, readMarkerComments } from "./lean/selftest-gate.mjs";
 
 const INSTALL_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const USAGE = "usage: forgedock review-staging [<PR number|PR URL>] [--thorough | --delta <from-sha>] [--json]\n" +
   "       forgedock review-staging [<PR>] --finalize --test-gate-output <file> [--notes-dropped <n>] [--json]\n" +
   "       forgedock review-staging [<PR>] --summary [--filed <issue>]... [--json]";
 const SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+/** selftest.sandbox_repo turns the release gate on only when it names a repo (`null`, `~`, `false` or prose leave it off). */
+const SANDBOX_RE = /^[\w.-]+\/[\w.-]+$/;
 /** Persona file / catalog keys per canonical marker domain (review-pr-agents.md routing table). */
 const INDEX_KEY = { auth: "auth", billing: "billing", database: "database", api: "api", frontend: "frontend", infra: "infrastructure" };
 const CONFIG_DOMAIN = { scraper: "scraping" };
@@ -137,7 +140,7 @@ function readConfig(io) {
   try { cfg = parseForgeYaml(io.readFile(path)) ?? {}; } catch { /* absent config: owner/repo check below fails */ }
   const owner = cfg.project?.owner, repo = cfg.project?.repo;
   if (!owner || !repo) throw new Stop(1, [`review-staging: project.owner/project.repo not set in ${path}`]);
-  return { ghRepo: `${owner}/${repo}`, defaultBranch: cfg.branches?.default || "main", stagingBranch: cfg.branches?.staging || "staging", configPath: path };
+  return { ghRepo: `${owner}/${repo}`, defaultBranch: cfg.branches?.default || "main", stagingBranch: cfg.branches?.staging || "staging", configPath: path, sandboxRepo: SANDBOX_RE.test(String(cfg.selftest?.sandbox_repo ?? "").trim()) ? String(cfg.selftest.sandbox_repo).trim() : "", sandboxRaw: String(cfg.selftest?.sandbox_repo ?? "").trim() };
 }
 
 /** Same derivation as commands/review-pr-staging.md Phase -1 (and scripts/lib/fence-bootstrap.sh). */
@@ -223,6 +226,14 @@ async function main(argv, io) {
   const head = await headSha(io, c, pr);
   if (a.delta && a.delta === head) throw new Stop(1, [`REVIEW_RESULT: status: BLOCKED, blocker: --delta ${head} is the current head of PR #${pr}: nothing changed since that pass, nothing to review`]);
   const sha7 = head.slice(0, 7);
+  // #4865: with selftest.sandbox_repo set, the release needs a passing live selftest for exactly this head (fail closed).
+  // Without a sandbox repo there is nothing the harness can run against, so the gate is skipped and says so.
+  if (c.sandboxRepo) {
+    let marks;
+    try { marks = await readMarkerComments(io.gh, c.ghRepo, pr); } catch (e) { throw new Stop(1, [`REVIEW_RESULT: status: BLOCKED, blocker: could not read the FORGE:SELFTEST markers of PR #${pr} (${String(e?.message ?? e).split("\n")[0].slice(0, 200)}); nothing reviewed (fail closed)`]); }
+    const selftest = selftestGate(marks, head);
+    if (!selftest.ok) throw new Stop(1, [`REVIEW_RESULT: status: BLOCKED, blocker: ${selftest.reason}; nothing reviewed (fail closed)`]);
+  } else io.err(`SELFTEST: skipped (selftest.sandbox_repo ${c.sandboxRaw ? `"${c.sandboxRaw.slice(0, 80)}" is not an owner/repo` : "not set"} in forge.yaml; the release does not require a FORGE:SELFTEST marker)`);
   let priorRoutes = 0;
   try {
     const out = await io.gh(["api", "--paginate", `repos/${c.ghRepo}/issues/${pr}/comments`, "--jq", '[.[] | select(.body | test("FORGE:REVIEW_ROUTE"))] | length']);
@@ -454,9 +465,19 @@ const TEST_GATE_NOTE = {
   BLOCK: (r) => `> **Test Gate: BLOCK (override/advisory)**: Runtime failures were detected but deploy is proceeding. Reason: ${r}. Filed \`test-failure\` issues track the failures.`,
 };
 
+/** Checks that never count as CI failures: each only reports this review's own gate marker or the lean gate summary. */
+export const CI_EXCLUDED_CHECKS = ["forgedock/verify", "forge/deploy-gate", "Check for FORGE gate markers"];
+
+const parseChecks = (out) => { try { const j = JSON.parse(out); return Array.isArray(j) ? j : null; } catch { return null; } };
+
+/** Failing (fail/cancel) checks outside CI_EXCLUDED_CHECKS. */
+export function countFailingChecks(checks) {
+  return checks.filter((k) => !CI_EXCLUDED_CHECKS.includes(k?.name) && (k?.bucket === "fail" || k?.bucket === "cancel")).length;
+}
+
 /** Phase 8 verdict from the deterministic inputs (CI, test gate, CONFIRMED CRITICAL/HIGH). */
 export function stagingVerdict({ ciFailing, testGateInvalid, confirmedCritical, confirmedHigh }) {
-  if (ciFailing > 0) return { verdict: "BLOCK DEPLOY", why: `CI failing (${ciFailing} required check(s) red; forgedock/verify and forge/deploy-gate excluded)` };
+  if (ciFailing > 0) return { verdict: "BLOCK DEPLOY", why: `CI failing (${ciFailing} required check(s) red; forgedock/verify, forge/deploy-gate and the gate-marker check excluded)` };
   if (testGateInvalid) return { verdict: "BLOCK DEPLOY", why: "test-gate result missing/invalid (fail closed)" };
   if (confirmedCritical > 0) return { verdict: "BLOCK DEPLOY", why: `${confirmedCritical} CONFIRMED CRITICAL finding(s)` };
   if (confirmedHigh > 0) return { verdict: "NEEDS FIXES FIRST", why: `${confirmedHigh} CONFIRMED HIGH finding(s)` };
@@ -472,10 +493,11 @@ async function summary(a, io) {
   const tg = testGateResult(io, sd, pr);
 
   // Phase 1E read: forgedock/verify is excluded; an unreadable result counts as failing (fail closed). forge/deploy-gate
-  // is excluded too: it reports this review's own marker, so an earlier GATE_FAILURE must not block the re-run that clears it.
+  // and the gate-marker check are excluded too: they report this review's own marker, so an earlier GATE_FAILURE must not block the re-run that clears it.
   let ciFailing = 1;
-  const ci = await io.run("gh", ["pr", "checks", String(pr), "-R", c.ghRepo, "--json", "name,bucket", "--jq", '[.[] | select(.name != "forgedock/verify" and .name != "forge/deploy-gate") | select(.bucket == "fail" or .bucket == "cancel")] | length'], { env, cwd: io.cwd });
-  if (/^\d+$/.test(ci.stdout.trim())) ciFailing = Number(ci.stdout.trim());
+  const ci = await io.run("gh", ["pr", "checks", String(pr), "-R", c.ghRepo, "--json", "name,bucket"], { env, cwd: io.cwd });
+  const checks = ci.code === 0 ? parseChecks(ci.stdout) : null;
+  if (checks) ciFailing = countFailingChecks(checks);
 
   const v = stagingVerdict({ ciFailing, testGateInvalid: tg.invalid, confirmedCritical: st.confirmedCritical, confirmedHigh: st.confirmedHigh });
   const pass = v.verdict === "APPROVE FOR DEPLOY";
@@ -501,7 +523,7 @@ async function summary(a, io) {
     "### Risk Matrix",
     "| Domain | Result | Notes |",
     "|--------|--------|-------|",
-    `| CI | ${ciFailing > 0 ? "FAIL" : "PASS"} | ${ciFailing} failing required check(s), forgedock/verify and forge/deploy-gate excluded |`,
+    `| CI | ${ciFailing > 0 ? "FAIL" : "PASS"} | ${ciFailing} failing required check(s), forgedock/verify, forge/deploy-gate and the gate-marker check excluded |`,
     `| Findings | ${st.confirmedCritical} CRITICAL / ${st.confirmedHigh} HIGH (CONFIRMED) | per-domain verdicts are in the FORGE:REVIEW-AGENT comments |`,
     `| **Test Gate** | \`${tg.verdict}\` | \`${tg.reason || "Phase 6.5 not run"}\` |`,
     "",

package/commands/deploy-pr.md

@@ -370,9 +370,9 @@ else
   # Fail closed: valid fields only (`status`/`conclusion` do not exist on gh pr checks --json; the
   # old query errored and defaulted to 0 = "no failures"). An unreadable result counts as failing.
   # forgedock/verify (the lean engine's report-only gate summary) is not a code failure: ignored, as wait-ci-green.sh does.
-  # forge/deploy-gate (the staging review's marker status) is not fixable by /fix-ci: ignored here, still waited on in Phase 5.
+  # forge/deploy-gate and "Check for FORGE gate markers" (the staging review's marker status and its workflow job) are not fixable by /fix-ci: ignored here, still waited on in Phase 5.
   CURRENT_CI_STATUS=$(gh pr checks "$PR_NUMBER" $GH_FLAG --json name,bucket \
-    --jq '[.[] | select(.name != "forgedock/verify" and .name != "forge/deploy-gate") | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
+    --jq '[.[] | select(.name != "forgedock/verify" and .name != "forge/deploy-gate" and .name != "Check for FORGE gate markers") | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
 
   if [ "$CURRENT_CI_STATUS" -eq 0 ]; then
     echo "CI gate: PASSED (no failing checks)"
@@ -394,7 +394,7 @@ else
 
       # Re-check CI status after fix attempt (same fail-closed query as above)
       FAILING_AFTER=$(gh pr checks "$PR_NUMBER" $GH_FLAG --json name,bucket \
-        --jq '[.[] | select(.name != "forgedock/verify" and .name != "forge/deploy-gate") | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
+        --jq '[.[] | select(.name != "forgedock/verify" and .name != "forge/deploy-gate" and .name != "Check for FORGE gate markers") | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
 
       if [ "$FAILING_AFTER" -eq 0 ]; then
         echo "CI gate: PASSED after $CI_ITER iteration(s)"

package/commands/orchestrate.md

@@ -103,10 +103,10 @@ remaining maintenance once no feature is pending; otherwise the rest ends `held
   `forgedock orchestrate --set-parallel <id> K`. Issues filed while a batch runs join it with
   `forgedock orchestrate --add <id> N...` (or `--resume <id> N...`), under its K and DAG; never start a second batch
   for them. After a decision (a `FORGE:DECISION` posted and `needs-human` removed), a blocked issue that already ended in the batch
-  (`needs-human`, `invalid`, `skipped`, `dependency-*`, `ci-pending`) returns to it with
+  (`needs-human`, `invalid`, `skipped`, `dependency-*`, `ci-pending`, `deferred`) returns to it with
   `forgedock orchestrate --requeue <id> N... --reason "..."` (refused while it is labelled `needs-human` or closed; skipped dependents
   return to pending with it; a finished batch is reopened); `--add` on a `skipped` issue re-queues it (other ended issues still report `already in batch`). A dependency-skipped issue shows as `waiting on #X` while the batch runs (the blocker is re-checked each pass; merged or closed re-admits it, closed as not planned keeps it skipped) and ends `skipped` only if the blocker never resolved. Its pre-filter still closes already-fixed ones. The runner requeues `deferred` lanes by code (host busy and a full sandbox pool after their
-  retry-in, uncapped, a usage limit holds admissions for that account (backend identity) until the reset, across every batch on
+  retry-in, uncapped, a usage limit holds admissions for that account (backend identity) until the reset, never capped, across every batch on
   the host; `forgedock limits show|clear <id>|--all` lists or drops holds; transient merge/push/idle failures back off; other
   deferrals stop after `orchestration.max_deferrals`), relaunches an `engine-error` once, and stops admitting after
   `orchestration.breaker` engine-errors (`errors` within `window_min`; held issues continue on `--resume`). Lanes are

package/commands/review-pr-staging.md

@@ -212,10 +212,10 @@ gh pr checks "$PR_NUMBER" -R "$GH_REPO" 2>&1
 # forgedock/verify (the lean engine's report-only gate summary) is not a code failure: ignored, as wait-ci-green.sh does.
 # Fail closed: an unreadable result counts as failing.
 CI_FAILING=$(gh pr checks "$PR_NUMBER" -R "$GH_REPO" --json name,bucket \
-  --jq '[.[] | select(.name != "forgedock/verify" and .name != "forge/deploy-gate") | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
+  --jq '[.[] | select(.name != "forgedock/verify" and .name != "forge/deploy-gate" and .name != "Check for FORGE gate markers") | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
 echo "CI_FAILING: $CI_FAILING"
 ```
-`CI_FAILING` > 0 → BLOCK DEPLOY (unless autofixed in Phase 1F). A red `forgedock/verify` alone does not block, and neither does `forge/deploy-gate`: it reports this review's own gate marker, so an earlier `GATE_FAILURE` never blocks the re-run that clears it.
+`CI_FAILING` > 0 → BLOCK DEPLOY (unless autofixed in Phase 1F). A red `forgedock/verify` alone does not block, and neither do `forge/deploy-gate` or `Check for FORGE gate markers`: they report this review's own gate marker, so an earlier `GATE_FAILURE` never blocks the re-run that clears it.
 
 ### Phase 1F: CI Autofix