forgedock 1.41.0 → 1.42.0

package/bin/engine-cli.mjs

@@ -2032,6 +2032,12 @@ async function scheddDue() {
   await sweepDue({ repo, cwd: process.cwd(), io: leanIo, onResult: probeEventSink(repo) });
   await sweepParkedFollowups({ repo, io: leanIo }); // #4689: re-queue parked post-deploy follow-ups on the same pass
   try { const prem = await import("./lean/needs-human-premise.mjs"); await prem.sweepPremises({ repo, io: { gh: (a) => leanIo.gh(a), pkgVersion: prem.registryPkgVersion } }); } catch { /* best effort (#4725) */ } // clear needs-human whose recorded premise now holds
+  try { // #4894: opt-in nightly live selftest (forge.yaml selftest.nightly_interval_hours); best effort
+    const { nightlyDue, launchNightly } = await import("./lean/selftest-nightly.mjs");
+    // Detached child: the harness calls back into this daemon (orchestrate --add), so it must never run on its event loop.
+    const launch = () => launchNightly({ cli: fileURLToPath(new URL("./forgedock.mjs", import.meta.url)), repo });
+    await nightlyDue({ repo, cwd: process.cwd(), io: leanIo, launch });
+  } catch { /* never stops the other sweeps */ }
 }
 
 /** #4689: re-evaluate the parked post-deploy follow-ups of the repo (promotion, due date, check now defined); never throws. */

package/bin/forgedock.mjs

@@ -3362,6 +3362,7 @@ function help() {
     ["npx forgedock milestone train <slug...> [--parallel-milestones N] | --resume <id> | --insert <id> <slug> [--before s|--after s] | --show <id>", "Unattended multi-milestone train: one durable state file (order, active set, lifecycle), typed STOP reasons, resumable; never edits forge.yaml"],
     ["npx forgedock guards list [--path p] [--json] | backfill --since <date> [--dry-run]", "Fix guards: list the FORGE:GUARD records (test files + protected hunks of merged fixes) covering a path, or build them for already-merged lean lanes"],
     ["npx forgedock issue-watch run [--name <w>] [--repo owner/repo] [--once] [--dry-run] | status [--name <w>]", "Named, scoped, capped watches (forge.yaml issue_watch.watches) that claim matching open issues into lanes or one long-lived orchestrate batch, or (mode: release) pool them and cut themed releases; see docs/ISSUE-WATCH.md"],
+    ["npx forgedock selftest [--static] | --live --repo <owner/sandbox> [--lang node|python] [--pr <N>]", "Live contract harness: drives the real gh, git and orchestrate through a disposable sandbox repo (steps create, add, body, resume, merge, remote, cleanup) plus a static check of every gh --json field list; exits non-zero naming the failed step; --pr posts the FORGE:SELFTEST result the staging->main review requires; see docs/SELFTEST.md"],
     ["npx forgedock prod-watch run [--repo owner/repo] [--once] [--interval <s>] [--dry-run] | status", "Production-side watcher (forge.yaml prod_watch): read-only signal sources -> triage -> governor -> issues, kill-switch file, owner digest; see docs/PROD-WATCH.md"],
     ["npx forgedock limits show | clear <id>|--all", "Show or clear per-account usage-limit holds shared by orchestrate batches"],
     ["npx forgedock decisions list [--stale] [--refresh]", "List anchored decisions (FORGE:DECISION); --stale shows those with an anchor missing on the base"],
@@ -3953,7 +3954,7 @@ async function watch() {
 const SPLASH_COMMANDS = new Set(["run", "bootstrap", "run-issue", "orchestrate", "triage", "probe", "gc", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
 const KNOWN_COMMANDS = new Set([
   "install", "init", "enable", "disable", "status", "uninstall", "update",
-  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "milestone", "milestone-sync", "guards", "triage", "probe", "review-staging", "gc", "resume-stalled", "demo", "doctor", "watch", "issue-watch", "prod-watch", "labels", "config", "stats", "limits", "decisions", "sched", "schedd", "pool", "check", "guide", "help", "--help", "-h",
+  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "milestone", "milestone-sync", "guards", "triage", "probe", "review-staging", "gc", "resume-stalled", "demo", "doctor", "watch", "issue-watch", "prod-watch", "selftest", "labels", "config", "stats", "limits", "decisions", "sched", "schedd", "pool", "check", "guide", "help", "--help", "-h",
   "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
@@ -4224,6 +4225,16 @@ switch (command) {
     }
     break;
   }
+  case "selftest": {
+    const { selftestFromCli } = await import("./lean/selftest-live.mjs");
+    try {
+      if (!(await selftestFromCli(restArgs)).ok) exitCode = 1;
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
   case "prod-watch": {
     const { prodWatchFromCli } = await import("./lean/prodwatch.mjs");
     try {

package/bin/lean/selftest-gate.mjs

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// FORGE:SELFTEST marker (#4865): the live selftest result on the staging->main PR, and the release gate over it.
+import { isTrustedComment } from "../engine/phases.mjs";
+
+// Anchored: the marker leads the comment (postMarker writes it first), so prose that quotes a marker never counts.
+const MARKER_RE = /^\s*<!--\s*FORGE:SELFTEST\s+([^>]*?)\s*-->/;
+
+/** @param {{result:"pass"|"fail", sha:string, step?:string}} m */
+export function buildMarker({ result, sha, step }) {
+  return `<!-- FORGE:SELFTEST result=${result} sha=${sha} step=${step || "none"} -->`;
+}
+
+/** @returns {{result:string, sha:string, step:string}|null} null for a body without a well-formed marker. */
+export function parseMarker(body) {
+  const m = MARKER_RE.exec(String(body ?? ""));
+  if (!m) return null;
+  const kv = Object.fromEntries(m[1].split(/\s+/).map((p) => p.split("=")).filter((p) => p.length === 2));
+  if (!/^(pass|fail)$/.test(kv.result ?? "") || !/^[0-9a-f]{40}$/.test(kv.sha ?? "")) return null;
+  return { result: kv.result, sha: kv.sha, step: kv.step ?? "none" };
+}
+
+/** Fail closed: the newest marker must be a pass for exactly `headSha`. @param {string[]} comments comment bodies, oldest first */
+export function selftestGate(comments, headSha) {
+  const marks = comments.map(parseMarker).filter(Boolean);
+  const last = marks[marks.length - 1];
+  if (!last) return { ok: false, reason: "no FORGE:SELFTEST result on the PR; run `forgedock selftest --live --repo <sandbox> --pr <N>`" };
+  if (last.result !== "pass") return { ok: false, reason: `the latest FORGE:SELFTEST failed at step ${last.step}` };
+  if (last.sha !== headSha) return { ok: false, reason: `the passing FORGE:SELFTEST is for ${last.sha.slice(0, 7)}, not the PR head ${String(headSha).slice(0, 7)}` };
+  return { ok: true };
+}
+
+/**
+ * Bodies of the trusted comments of PR `pr` that carry a marker, oldest first (one JSON object per gh output line).
+ * Only comments `isTrustedComment` accepts count (maintainer association, a Bot, FORGE_TRAIL_TRUSTED_LOGINS): anyone can
+ * comment on a public PR, and a forged pass must not open the release gate. A gh failure throws (the caller fails closed).
+ */
+export async function readMarkerComments(gh, repo, pr) {
+  const out = await gh(["api", "--paginate", `repos/${repo}/issues/${pr}/comments`, "--jq", '.[] | select(.body | test("FORGE:SELFTEST")) | {body, author_association, user: {login: .user.login, type: .user.type}} | @json']);
+  return String(out).split("\n").filter(Boolean).flatMap((l) => { try { return [JSON.parse(l)]; } catch { return []; } })
+    .filter(isTrustedComment).map((c) => String(c.body ?? ""));
+}
+
+export async function postMarker(gh, repo, pr, m) {
+  await gh(["pr", "comment", String(pr), "-R", repo, "--body", `${buildMarker(m)}\nLive selftest: ${m.result}${m.step ? ` (step ${m.step})` : ""}`]);
+}

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

@@ -0,0 +1,40 @@
+// 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 { buildMarker, parseMarker, selftestGate, readMarkerComments, postMarker } from "./selftest-gate.mjs";
+
+const H = "a".repeat(40), O = "b".repeat(40);
+describe("FORGE:SELFTEST gate (#4865)", () => {
+  it("round-trips a marker", () => {
+    assert.deepEqual(parseMarker(buildMarker({ result: "fail", sha: H, step: "add" })), { result: "fail", sha: H, step: "add" });
+  });
+  it("accepts a passing marker for the head", () => assert.equal(selftestGate([buildMarker({ result: "pass", sha: H })], H).ok, true));
+  it("refuses missing, failing, stale and malformed markers", () => {
+    assert.equal(selftestGate([], H).ok, false);
+    assert.equal(selftestGate(["lgtm"], H).ok, false);
+    assert.match(selftestGate([buildMarker({ result: "fail", sha: H, step: "add" })], H).reason, /step add/);
+    assert.match(selftestGate([buildMarker({ result: "pass", sha: O })], H).reason, /not the PR head/);
+    assert.equal(selftestGate(["<!-- FORGE:SELFTEST result=pass sha=abc -->"], H).ok, false);
+  });
+  it("a marker quoted inside prose does not count", () => {
+    assert.equal(parseMarker(`see: ${buildMarker({ result: "pass", sha: H })}`), null);
+    assert.equal(selftestGate([buildMarker({ result: "fail", sha: H, step: "add" }), `quoting ${buildMarker({ result: "pass", sha: H })}`], H).ok, false);
+  });
+  it("a gh failure is not read as no marker", async () => {
+    await assert.rejects(readMarkerComments(async () => { throw new Error("HTTP 502"); }, "o/r", 5), /502/);
+  });
+  it("the newest marker wins", () => {
+    assert.equal(selftestGate([buildMarker({ result: "pass", sha: H }), buildMarker({ result: "fail", sha: H, step: "merge" })], H).ok, false);
+    assert.equal(selftestGate([buildMarker({ result: "fail", sha: H, step: "merge" }), buildMarker({ result: "pass", sha: H })], H).ok, true);
+  });
+  it("reads and posts through gh", async () => {
+    const calls = [];
+    const rows = [{ body: "x", author_association: "OWNER", user: { login: "m", type: "User" } }, { body: "forged", author_association: "NONE", user: { login: "drive-by", type: "User" } }, { body: "bot", author_association: "NONE", user: { login: "app[bot]", type: "Bot" } }];
+    const gh = async (a) => { calls.push(a); return a[0] === "api" ? rows.map((r) => JSON.stringify(r)).join("\n") + "\nnot json\n" : ""; };
+    assert.deepEqual(await readMarkerComments(gh, "o/r", 5), ["x", "bot"], "an untrusted commenter's marker is dropped");
+    await postMarker(gh, "o/r", 5, { result: "pass", sha: H });
+    assert.match(calls[1].at(-1), /FORGE:SELFTEST result=pass/);
+  });
+});
+

package/bin/lean/selftest-live.mjs

@@ -0,0 +1,248 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// `forgedock selftest --live --repo <owner/sandbox> [--lang node|python] [--pr N]` (#4865): drives the real binaries
+// (gh, git, forgedock orchestrate) against a disposable sandbox repo. The mocked unit tests missed #4859 (--add skipped
+// every issue), #4860 (issue body wiped to FORGE:STATE), #4817 and #4818; each step below fails on one of those classes.
+// All process access goes through `io` so the step logic is unit-tested with fakes; `realIo` is the live binding.
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+import { batchRoot, listBatches, openBatch } from "./batch.mjs";
+import { staticCheck, formatStatic, realGh } from "./selftest-static.mjs";
+import { postMarker } from "./selftest-gate.mjs";
+import { reportNightly } from "./selftest-nightly.mjs";
+import { parseForgeYaml } from "../forge-utils.mjs";
+
+export class StepError extends Error {
+  constructor(step, message) { super(message); this.step = step; }
+}
+const fail = (step, msg) => { throw new StepError(step, msg); };
+
+/** Fixture per toolchain: base files plus the two trivial issues (a test that fails on the old code). */
+export const FIXTURES = {
+  node: {
+    files: { "package.json": '{"name":"selftest-sandbox","private":true,"type":"module","scripts":{"test":"node --test"}}\n', "README.md": "ForgeDock selftest sandbox\n" },
+    a: { title: "selftest A: add a()", body: "Create `src/a.js` exporting `a()` that returns `\"a\"`, and `src/a.test.js` (node:test) asserting it. The test must fail on the current code." },
+    b: { title: "selftest B: add b()", body: "Create `src/b.js` exporting `b()` that returns `\"b\"`, and `src/b.test.js` (node:test) asserting it. The test must fail on the current code." },
+  },
+  python: {
+    files: { "pyproject.toml": '[project]\nname = "selftest-sandbox"\nversion = "0.0.0"\n', "README.md": "ForgeDock selftest sandbox\n" },
+    a: { title: "selftest A: add a()", body: "Create `a.py` with `def a(): return \"a\"` and `test_a.py` (pytest) asserting it. The test must fail on the current code." },
+    b: { title: "selftest B: add b()", body: "Create `b.py` with `def b(): return \"b\"` and `test_b.py` (pytest) asserting it. The test must fail on the current code." },
+  },
+};
+
+/** The issue body with its FORGE:STATE annotation removed. */
+export const stripState = (body) => String(body ?? "").replace(/<!--\s*FORGE:STATE[\s\S]*?-->/g, "").trim();
+
+const num = (out) => { const m = /\/issues\/(\d+)/.exec(String(out)) ?? /^(\d+)$/m.exec(String(out)); if (!m) throw new Error(`no issue number in: ${String(out).slice(0, 120)}`); return Number(m[1]); };
+
+async function waitFor(ctx, step, what, cond, onTick) {
+  const { io, timeoutMs } = ctx, t0 = io.now();
+  for (;;) {
+    if (onTick) await onTick();
+    const v = await cond();
+    if (v) return v;
+    if (io.now() - t0 > timeoutMs) fail(step, `timed out waiting for ${what}`);
+    await io.sleep(ctx.pollMs);
+  }
+}
+
+/** Step "body": every issue body still holds its creation text (#4860). */
+async function checkBodies(ctx, step = "body") {
+  for (const [name, n] of Object.entries(ctx.issues)) {
+    const now = JSON.parse(await ctx.io.gh(["issue", "view", String(n), "-R", ctx.repo, "--json", "body"])).body;
+    if (!stripState(now).includes(ctx.bodies[n])) fail(step, `issue ${name} (#${n}) lost its body text; now: ${JSON.stringify(stripState(now).slice(0, 80))}`);
+  }
+}
+
+export const STEPS = [
+  { name: "create", run: async (ctx) => {
+    const { io, repo, fx } = ctx;
+    for (const [path, content] of Object.entries(fx.files)) {
+      await io.gh(["api", "-X", "PUT", `repos/${repo}/contents/${path}`, "-f", `message=selftest fixture ${path}`, "-f", `content=${Buffer.from(content).toString("base64")}`]).catch(() => { /* already present */ });
+    }
+    const mk = async (t, body) => num(await io.gh(["issue", "create", "-R", repo, "--title", t, "--body", body]));
+    const a = await mk(fx.a.title, fx.a.body);
+    const b = await mk(fx.b.title, `${fx.b.body}\n\n**Depends on**: #${a}`);
+    ctx.issues = { A: a, B: b };
+    ctx.bodies = { [a]: fx.a.body, [b]: fx.b.body };
+    ctx.created.push(a, b);
+  } },
+  { name: "add", run: async (ctx) => {
+    const { io, repo, issues } = ctx;
+    ctx.run = await io.orchestrate.start(repo, [issues.A], 2);
+    const r = await io.cli(["orchestrate", "--add", ctx.run.id, String(issues.B)]);
+    if (r.code !== 0) fail("add", `orchestrate --add exited ${r.code}: ${String(r.stderr || r.stdout).slice(0, 200)}`);
+    if (/unreadable|skipped/i.test(`${r.stdout}\n${r.stderr}`)) fail("add", `--add skipped #${issues.B}: ${String(r.stdout || r.stderr).slice(0, 200)}`);
+    const st = await waitFor(ctx, "add", `#${issues.B} in the batch`, async () => { const s = await io.orchestrate.state(ctx.run.id); return s?.order?.includes(issues.B) ? s : null; });
+    if (!(st.deps?.[issues.B] ?? []).includes(issues.A)) fail("add", `#${issues.B} does not wait on #${issues.A} in the DAG (deps: ${JSON.stringify(st.deps?.[issues.B] ?? [])})`);
+  } },
+  { name: "body", run: (ctx) => checkBodies(ctx) },
+  { name: "resume", run: async (ctx) => {
+    const { io, issues } = ctx;
+    const pid = async () => (await io.orchestrate.state(ctx.run.id))?.running?.[issues.A]?.pid ?? null;
+    const before = await waitFor(ctx, "resume", `a live lane for #${issues.A}`, pid);
+    await ctx.run.kill();
+    ctx.run = await io.orchestrate.resume(ctx.run.id);
+    await io.sleep(ctx.pollMs);
+    const st = await io.orchestrate.state(ctx.run.id), after = st?.running?.[issues.A]?.pid ?? null;
+    const done = st?.results?.[issues.A];
+    if (!done && after !== before) fail("resume", `#${issues.A} was launched again after --resume (pid ${before} -> ${after}), not re-adopted`);
+    await checkBodies(ctx, "body");
+  } },
+  { name: "merge", run: async (ctx) => {
+    const { io, repo, issues } = ctx;
+    const res = await waitFor(ctx, "merge", "both lanes to finish", async () => {
+      const s = await io.orchestrate.state(ctx.run.id);
+      return s?.results?.[issues.A] && s?.results?.[issues.B] ? s.results : null;
+    }, () => checkBodies(ctx, "body"));
+    const merged = {};
+    for (const [k, n] of Object.entries(issues)) {
+      if (res[n].outcome !== "merged" || !res[n].pr) fail("merge", `#${n} ended ${res[n].outcome}, not merged`);
+      const pr = JSON.parse(await io.gh(["pr", "view", String(res[n].pr), "-R", repo, "--json", "mergedAt,state"]));
+      if (pr.state !== "MERGED") fail("merge", `PR #${res[n].pr} for ${k} is ${pr.state}`);
+      const is = JSON.parse(await io.gh(["issue", "view", String(n), "-R", repo, "--json", "state,labels"]));
+      if (is.state !== "CLOSED") fail("merge", `#${n} is not closed`);
+      if (!is.labels.some((l) => l.name === "workflow:merged")) fail("merge", `#${n} lacks the workflow:merged label`);
+      merged[k] = Date.parse(pr.mergedAt);
+    }
+    if (!(merged.A <= merged.B)) fail("merge", `B merged before A (${merged.B} < ${merged.A})`);
+  } },
+  { name: "remote", run: async (ctx) => {
+    const { io } = ctx;
+    if (!io.remote) { ctx.notes.push("remote: skipped (pool not configured)"); return; }
+    const c = num(await io.gh(["issue", "create", "-R", ctx.repo, "--title", `${ctx.fx.a.title.replace("A:", "C:")}`, "--body", ctx.fx.a.body]));
+    ctx.created.push(c);
+    const r = await io.remote.run({ repo: ctx.repo, issue: c, timeoutMs: ctx.timeoutMs, pollMs: ctx.pollMs });
+    if (r.where !== "remote") fail("remote", `#${c} ran ${r.where ?? "unknown"}, not in the pool`);
+    if (!r.authenticated) fail("remote", "the remote lane did not authenticate");
+    const cli = await io.cliVersion();
+    if (r.engineVersion !== cli) fail("remote", `sandbox engine ${r.engineVersion} != CLI ${cli}`);
+  } },
+];
+
+/**
+ * Run the steps in order; the first failure stops them, cleanup always runs.
+ * @returns {{ok:boolean, step:string|null, message:string|null, notes:string[], cleanupErrors:string[]}}
+ */
+export async function runSelftestLive({ repo, lang = "node", io, timeoutMs = 45 * 60 * 1000, pollMs = 5000 }) {
+  const fx = FIXTURES[lang];
+  if (!fx) return { ok: false, step: "setup", message: `unknown fixture language ${lang} (node|python)`, notes: [], cleanupErrors: [] };
+  const ctx = { io, repo, fx, timeoutMs, pollMs, issues: {}, bodies: {}, created: [], notes: [], run: null };
+  let out = { ok: true, step: null, message: null };
+  for (const s of STEPS) {
+    try { await s.run(ctx); } catch (e) { out = { ok: false, step: e.step ?? s.name, message: String(e.message ?? e) }; break; }
+  }
+  const cleanupErrors = [];
+  const tryC = async (what, f) => { try { await f(); } catch (e) { cleanupErrors.push(`${what}: ${String(e.message ?? e).slice(0, 120)}`); } };
+  if (ctx.run) await tryC("stop orchestrate", () => ctx.run.kill());
+  for (const n of ctx.created) {
+    await tryC(`close #${n}`, () => io.gh(["issue", "close", String(n), "-R", repo]));
+    await tryC(`delete branches of #${n}`, async () => {
+      const refs = String(await io.gh(["api", `repos/${repo}/git/matching-refs/heads/forge/issue-${n}`, "--jq", ".[].ref"])).split("\n").filter(Boolean);
+      for (const ref of refs) await io.gh(["api", "-X", "DELETE", `repos/${repo}/git/${ref}`]);
+    });
+    await tryC(`close PRs of #${n}`, async () => {
+      const prs = String(await io.gh(["pr", "list", "-R", repo, "--search", `#${n} in:title,body`, "--state", "open", "--json", "number", "--jq", ".[].number"])).split("\n").filter(Boolean);
+      for (const p of prs) await io.gh(["pr", "close", p, "-R", repo, "--delete-branch"]);
+    });
+  }
+  return { ...out, notes: ctx.notes, cleanupErrors };
+}
+
+// ── real io + CLI ───────────────────────────────────────────────────────────────────────────────────────────
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "..", "forgedock.mjs");
+
+export function realIo(env = process.env, { pool = false } = {}) {
+  let self;
+  const root = batchRoot(env);
+  const detached = (args) => { const p = spawn(process.execPath, [CLI, ...args], { detached: true, stdio: "ignore", env }); p.unref(); return { kill: async () => { try { process.kill(-p.pid, "SIGTERM"); } catch { /* gone */ } } }; };
+  const waitBatch = async (before) => { for (let i = 0; i < 60; i++) { const id = listBatches(root).find((b) => !before.has(b)); if (id) return id; await new Promise((r) => setTimeout(r, 1000)); } throw new Error("orchestrate did not create a batch within 60s"); };
+  return (self = {
+    now: () => Date.now(), sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    gh: async (args) => { const r = spawnSync("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }); if (r.status !== 0) throw new Error(r.stderr.trim() || `gh exited ${r.status}`); return r.stdout; },
+    cli: async (args) => { const r = spawnSync(process.execPath, [CLI, ...args], { encoding: "utf8", env }); return { code: r.status ?? 1, stdout: r.stdout, stderr: r.stderr }; },
+    cliVersion: async () => JSON.parse(readFileSync(join(dirname(CLI), "..", "package.json"), "utf8")).version,
+    orchestrate: {
+      start: async (repo, issues, parallel) => {
+        const before = new Set(listBatches(root)), h = detached(["orchestrate", ...issues.map(String), "--parallel", String(parallel), "--repo", repo]);
+        return { id: await waitBatch(before), kill: h.kill };
+      },
+      resume: async (id) => ({ id, ...detached(["orchestrate", "--resume", id]) }),
+      state: async (id) => openBatch(root, id).store.load(),
+    },
+    // Step 6: one lane through the pool. The issue's FORGE:STATE records the placement and the lane's FORGE:TELEMETRY rows
+    // carry the engine's forge_version (the sandbox's, not the CLI's: the #4818 stale-image defect).
+    remote: pool ? { run: async ({ repo, issue, timeoutMs, pollMs }) => {
+      const run = await self.orchestrate.start(repo, [issue], 1), t0 = Date.now();
+      let row = null;
+      try {
+        while (!row && Date.now() - t0 < timeoutMs) { row = (await self.orchestrate.state(run.id))?.results?.[issue] ?? null; if (!row) await self.sleep(pollMs); }
+      } finally { await run.kill(); }
+      if (!row) throw new Error(`#${issue} produced no result within ${Math.round(timeoutMs / 1000)}s`);
+      const v = JSON.parse(await self.gh(["issue", "view", String(issue), "-R", repo, "--json", "body,comments"]));
+      const text = `${v.body}\n${v.comments.map((c) => c.body).join("\n")}`;
+      const versions = [...text.matchAll(/"forge_version":"([^"]+)"/g)].map((m) => m[1]);
+      return { where: /"placement":\{"where":"(\w+)"/.exec(text)?.[1] ?? null, authenticated: versions.length > 0 && !/^env\./.test(String(row.code ?? row.outcome ?? "")), engineVersion: versions.at(-1) ?? null };
+    } } : null,
+  });
+}
+
+/** The value after flag `f`, or null when absent. A flag with no value (end of argv, or another `--flag` next) throws. */
+const flag = (argv, f) => {
+  const i = argv.indexOf(f);
+  if (i < 0) return null;
+  const v = argv[i + 1];
+  if (v == null || String(v).startsWith("--") || !String(v).trim()) throw new Error(`${f} needs a value`);
+  return v;
+};
+const REPO_RE = /^[\w.-]+\/[\w.-]+$/;
+const repoOrNull = (v) => (REPO_RE.test(String(v ?? "").trim()) ? String(v).trim() : null);
+
+/** `forgedock selftest [--static] | --live --repo <o/sandbox> [--lang node|python] [--pr N]`; non-zero exit names the failed step. */
+export async function selftestFromCli(argv, deps = {}) {
+  const cwd = deps.cwd ?? process.cwd(), env = deps.env ?? process.env, print = deps.print ?? ((l) => console.log(l));
+  const usage = "usage: forgedock selftest [--static] | --live [--repo <owner/sandbox>] [--lang node|python] [--pr <staging->main PR>]  (sandbox repo from --repo or forge.yaml selftest.sandbox_repo)";
+  if (!argv.includes("--live") && !argv.includes("--static")) throw new Error(usage);
+  const nightlyRepo = argv.includes("--nightly-report") ? flag(argv, "--nightly-report") : null;
+  if (nightlyRepo) {
+    // #4894: the detached nightly run. Any failure, including one before the harness starts (no sandbox repo), is filed.
+    const rest = argv.filter((a, i) => a !== "--nightly-report" && argv[i - 1] !== "--nightly-report");
+    const lines = [];
+    let r;
+    try { r = await selftestFromCli(rest, { ...deps, print: (l) => { lines.push(l); print(l); } }); } catch (e) { r = { ok: false, step: "config", message: String(e?.message ?? e) }; }
+    if (!r.ok) await reportNightly({ repo: nightlyRepo, io: { gh: async (a) => (deps.io?.gh ?? realGh)(a) }, result: { step: r.step, message: r.message ?? lines.filter((l) => /FAILED|FAIL/.test(l)).join("\n") } });
+    return r;
+  }
+  const gh = deps.io?.gh ?? realGh;
+  const st = staticCheck({ root: deps.binRoot ?? join(dirname(CLI)), io: { gh: (a) => gh(a) } });
+  print(formatStatic(st));
+  let exitCode = st.ok ? 0 : 1, step = st.ok ? null : "static";
+  if (argv.includes("--live")) {
+    let cfg = {}; try { cfg = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8")) ?? {}; } catch { /* none */ }
+    const repo = repoOrNull(flag(argv, "--repo") ?? cfg.selftest?.sandbox_repo);
+    if (!repo) throw new Error(`no sandbox repo: pass --repo owner/sandbox or set selftest.sandbox_repo in forge.yaml\n${usage}`);
+    const project = cfg.project?.owner && cfg.project?.repo ? `${cfg.project.owner}/${cfg.project.repo}` : null;
+    if (project && project.toLowerCase() === repo.toLowerCase()) throw new Error(`refusing to run in ${repo}: it is this project's repo (forge.yaml project), and the harness creates, merges, closes and deletes there; use a disposable sandbox repo`);
+    const lang = flag(argv, "--lang") ?? cfg.selftest?.fixture ?? "node";
+    const io = deps.io ?? realIo(env, { pool: ["remote", "hybrid"].includes(String(cfg.execution?.mode ?? "")) });
+    // The marker binds the head that was tested: read it (from the release repo) before the run, never after.
+    const pr = flag(argv, "--pr");
+    let releaseRepo = null, head = null;
+    if (pr) {
+      releaseRepo = flag(argv, "--release-repo") ?? JSON.parse(String(await io.gh(["repo", "view", "--json", "nameWithOwner"]))).nameWithOwner;
+      if (releaseRepo.toLowerCase() === repo.toLowerCase()) throw new Error(`refusing to run in ${repo}: it is the release repo`);
+      head = String(await io.gh(["pr", "view", String(pr), "-R", releaseRepo, "--json", "headRefOid", "--jq", ".headRefOid"])).trim();
+    }
+    const r = await runSelftestLive({ repo, lang, io, ...(deps.timing ?? {}) });
+    for (const n of r.notes) print(n);
+    for (const e of r.cleanupErrors) print(`cleanup: ${e}`);
+    if (r.ok) print(`selftest --live: all steps passed on ${repo}`);
+    else { print(`selftest --live FAILED at step ${r.step}: ${r.message}`); exitCode = 1; step = r.step; }
+    if (pr) await postMarker((a) => io.gh(a), releaseRepo, pr, { result: exitCode === 0 ? "pass" : "fail", sha: head, step });
+    if (!r.ok) return { ok: false, step, message: r.message };
+  }
+  return { ok: exitCode === 0, step };
+}

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

@@ -0,0 +1,154 @@
+// 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 { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { runSelftestLive, stripState, selftestFromCli, STEPS } from "./selftest-live.mjs";
+
+/** A fake sandbox world. `d` toggles a defect: add4859 (--add skips), wipe4860 (body wiped), double (resume relaunches), orderBA, noRemoteAuth. */
+function world(d = {}) {
+  const w = { issues: {}, closed: [], calls: [], killed: 0, pid: 100, results: {}, order: [], deps: {}, running: {}, clock: 0, pool: !!d.pool };
+  const gh = async (a) => {
+    w.calls.push(a.join(" "));
+    if (a[0] === "api" && a[1] === "-X" && a[2] === "PUT") return "{}";
+    if (a[0] === "issue" && a[1] === "create") {
+      const n = 10 + Object.keys(w.issues).length; w.issues[n] = { body: a[a.indexOf("--body") + 1], state: "OPEN", labels: [] }; return `https://github.com/o/r/issues/${n}\n`;
+    }
+    if (a[0] === "issue" && a[1] === "view") {
+      const n = a[2], i = w.issues[n];
+      if (a.includes("body")) return JSON.stringify({ body: d.wipe4860 && w.wiped ? "<!-- FORGE:STATE {} -->" : `${i.body}\n<!-- FORGE:STATE {"v":1} -->` });
+      return JSON.stringify({ state: i.state, labels: i.labels.map((name) => ({ name })) });
+    }
+    if (a[0] === "issue" && a[1] === "close") { w.closed.push(a[2]); return ""; }
+    if (a[0] === "pr" && a[1] === "view") return JSON.stringify({ state: "MERGED", mergedAt: `2026-01-01T00:0${a[2] === "101" ? (d.orderBA ? 2 : 1) : (d.orderBA ? 1 : 2)}:00Z` });
+    if (a[0] === "pr" && a[1] === "list") return "";
+    if (a[0] === "api") { throw new Error("fail cleanup api"); }
+    throw new Error(`unexpected gh ${a.join(" ")}`);
+  };
+  const io = {
+    now: () => (w.clock += 1000), sleep: async () => { w.tick = (w.tick ?? 0) + 1; if (d.wipe4860 && w.tick >= 1) w.wiped = true; finish(); },
+    gh, cliVersion: async () => "1.39.0",
+    cli: async (a) => {
+      if (a[1] === "--add") { const n = Number(a[3]); if (d.add4859) return { code: 0, stdout: `#${n} skipped: unreadable`, stderr: "" }; w.order.push(n); w.deps[n] = [Number(Object.keys(w.issues)[0])]; return { code: 0, stdout: "added", stderr: "" }; }
+      throw new Error("cli " + a);
+    },
+    orchestrate: {
+      start: async (repo, issues) => { w.order.push(...issues); w.running[issues[0]] = { pid: ++w.pid }; w.a = issues[0]; return { id: "b1", kill: async () => { w.killed++; } }; },
+      resume: async (id) => { w.resumedAt = w.tick ?? 0; if (d.double) w.running[w.a] = { pid: ++w.pid }; return { id, kill: async () => { w.killed++; } }; },
+      state: async () => ({ order: w.order, deps: w.deps, running: w.running, results: w.results }),
+    },
+    remote: w.pool ? { run: async ({ issue }) => { w.remoteIssue = issue; return { where: d.local ? "local" : "remote", authenticated: !d.noRemoteAuth, engineVersion: d.oldEngine ? "1.37.0" : "1.39.0" }; } } : null,
+  };
+  function finish() {
+    if (w.resumedAt !== undefined && !w.finished && (w.tick ?? 0) >= w.resumedAt + 2) {
+      w.finished = true;
+      const [a, b] = Object.keys(w.issues).map(Number);
+      w.results = { [a]: { outcome: "merged", pr: 101 }, [b]: { outcome: "merged", pr: 102 } };
+      for (const n of [a, b]) w.issues[n].labels.push("workflow:merged"), w.issues[n].state = "CLOSED";
+    }
+  }
+  return { w, io };
+}
+const run = (d, extra = {}) => { const { w, io } = world(d); return runSelftestLive({ repo: "o/sandbox", io, pollMs: 1, timeoutMs: 60000, ...extra }).then((r) => ({ w, r })); };
+
+describe("selftest --live steps (#4865)", () => {
+  it("all steps pass and cleanup runs", async () => {
+    const { w, r } = await run({});
+    assert.equal(r.ok, true, JSON.stringify(r));
+    assert.deepEqual(w.closed, ["10", "11"]);
+    assert.match(r.notes.join(), /remote: skipped/);
+  });
+  it("fixtures: B depends on A and the issue bodies are the fixture text", async () => {
+    const { w } = await run({});
+    assert.match(w.issues[11].body, /\*\*Depends on\*\*: #10/);
+  });
+  it("the #4859 defect (--add skips the issue) fails the add step", async () => {
+    const { r, w } = await run({ add4859: true });
+    assert.equal(r.ok, false); assert.equal(r.step, "add"); assert.match(r.message, /skipped #11/);
+    assert.deepEqual(w.closed, ["10", "11"], "cleanup ran after the failure");
+  });
+  it("the #4860 defect (body wiped to FORGE:STATE) fails the body step", async () => {
+    const { r } = await run({ wipe4860: true });
+    assert.equal(r.ok, false); assert.equal(r.step, "body"); assert.match(r.message, /lost its body text/);
+  });
+  it("a lane launched twice after --resume fails the resume step", async () => {
+    const { r } = await run({ double: true });
+    assert.equal(r.step, "resume"); assert.match(r.message, /launched again/);
+  });
+  it("B merging before A fails the merge step", async () => {
+    const { r } = await run({ orderBA: true });
+    assert.equal(r.step, "merge"); assert.match(r.message, /B merged before A/);
+  });
+  it("remote step: stale sandbox engine or no auth fails it; matching passes", async () => {
+    assert.equal((await run({ pool: true })).r.ok, true);
+    assert.match((await run({ pool: true, oldEngine: true })).r.message, /1\.37\.0 != CLI 1\.39\.0/);
+    assert.equal((await run({ pool: true, noRemoteAuth: true })).r.step, "remote");
+    assert.match((await run({ pool: true, local: true })).r.message, /not in the pool/);
+    const ok = await run({ pool: true });
+    assert.equal(ok.w.remoteIssue, 12); assert.deepEqual(ok.w.closed, ["10", "11", "12"]);
+  });
+  it("unknown fixture language fails at setup", async () => {
+    assert.equal((await runSelftestLive({ repo: "o/r", lang: "ruby", io: {} })).step, "setup");
+  });
+  it("stripState drops only the annotation", () => assert.equal(stripState("hi\n<!-- FORGE:STATE\n{}\n-->"), "hi"));
+  it("has the six ordered phases (cleanup runs after them)", () => assert.deepEqual(STEPS.map((s) => s.name), ["create", "add", "body", "resume", "merge", "remote"]));
+});
+
+describe("selftestFromCli", () => {
+  it("requires --live or --static and a sandbox repo", async () => {
+    await assert.rejects(selftestFromCli([]), /usage/);
+    await assert.rejects(selftestFromCli(["--live"], { cwd: "/nonexistent", print: () => {}, io: { gh: async () => "" } }), /no sandbox repo/);
+  });
+  it("a failing step is named in the output, returned not-ok, and the marker is posted as fail", async () => {
+    const { io } = world({ add4859: true }); const out = [], posted = [];
+    const gh = io.gh;
+    io.gh = async (a) => {
+      if (a[0] === "pr" && a[1] === "view" && a.includes("headRefOid")) return "a".repeat(40);
+      if (a[0] === "repo") return JSON.stringify({ nameWithOwner: "o/r" });
+      if (a[0] === "pr" && a[1] === "comment") { posted.push(a.at(-1)); return ""; }
+      if (a[1] === "--help" || a[2] === "--help") return "JSON FIELDS\n  body, number, title\n";
+      return gh(a);
+    };
+    const r = await selftestFromCli(["--live", "--repo", "o/sandbox", "--pr", "9"], { cwd: "/nonexistent", print: (l) => out.push(l), io, timing: { pollMs: 1 } });
+    assert.equal(r.ok, false); assert.equal(r.step, "add");
+    assert.ok(out.some((l) => /FAILED at step add/.test(l)));
+    assert.match(posted[0], /FORGE:SELFTEST result=fail sha=a{40} step=add/);
+  });
+  it("the PR head is read from the release repo before the run", async () => {
+    const { io } = world({}); const order = [];
+    const gh = io.gh;
+    io.gh = async (a) => {
+      if (a[0] === "pr" && a[1] === "view" && a.includes("headRefOid")) { order.push(`head ${a[a.indexOf("-R") + 1]}`); return "b".repeat(40); }
+      if (a[0] === "pr" && a[1] === "comment") { order.push("post"); return ""; }
+      if (a[1] === "--help" || a[2] === "--help") return "JSON FIELDS\n  body, number, title\n";
+      if (a[0] === "issue" && a[1] === "create" && !order.includes("run")) order.push("run");
+      return gh(a);
+    };
+    await selftestFromCli(["--live", "--repo", "o/sandbox", "--pr", "9", "--release-repo", "o/rel"], { cwd: "/nonexistent", print: () => {}, io, timing: { pollMs: 1 } });
+    assert.deepEqual(order.slice(0, 2), ["head o/rel", "run"]);
+  });
+  it("refuses the project repo or the release repo as the sandbox", async () => {
+    const cwd = tmpDir("st-"); writeFileSync(join(cwd, "forge.yaml"), "project:\n  owner: o\n  repo: R\n");
+    const io = { gh: async (a) => (a[1] === "--help" || a[2] === "--help" ? "JSON FIELDS\n  body\n" : "") };
+    await assert.rejects(selftestFromCli(["--live", "--repo", "o/r"], { cwd, print: () => {}, io }), /this project's repo/);
+    await assert.rejects(selftestFromCli(["--live", "--repo", "o/x", "--pr", "3", "--release-repo", "o/x"], { cwd: "/nonexistent", print: () => {}, io }), /release repo/);
+  });
+  it("a flag without a value throws instead of being skipped", async () => {
+    await assert.rejects(selftestFromCli(["--live", "--repo", "o/s", "--pr"], { cwd: "/nonexistent", print: () => {}, io: { gh: async () => "" } }), /--pr needs a value/);
+    await assert.rejects(selftestFromCli(["--live", "--repo", "--pr", "4"], { cwd: "/nonexistent", print: () => {}, io: { gh: async () => "" } }), /--repo needs a value/);
+  });
+  it("forge.yaml is read per section: another section's mode or sandbox_repo is not picked up", async () => {
+    const cwd = tmpDir("st-"); writeFileSync(join(cwd, "forge.yaml"), "selftest:\n  fixture: node\nother:\n  sandbox_repo: x/y\n");
+    await assert.rejects(selftestFromCli(["--live"], { cwd, print: () => {}, io: { gh: async () => "" } }), /no sandbox repo/);
+  });
+  it("--nightly-report files a failure that happens before the harness starts (no sandbox repo)", async () => {
+    const calls = [];
+    const gh = async (a) => { calls.push(a); if (a[1] === "list") return "[]"; if (a[1] === "create") return "https://github.com/o/r/issues/5\n"; return a[1] === "--help" || a[2] === "--help" ? "JSON FIELDS\n  body\n" : ""; };
+    const r = await selftestFromCli(["--live", "--nightly-report", "o/r"], { cwd: "/nonexistent", print: () => {}, io: { gh } });
+    assert.equal(r.ok, false); assert.equal(r.step, "config");
+    const create = calls.find((a) => a[0] === "issue" && a[1] === "create");
+    assert.ok(create && create.includes("o/r")); assert.match(create.join(" "), /step config/);
+  });
+});

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/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/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
 

package/docs/CONFIG.md

@@ -58,6 +58,7 @@ If you have both a local `claude` CLI and `ANTHROPIC_API_KEY` set and want to pi
 | [`verification`](#verification-optional) | No | Health-check patterns |
 | [`execution`](#execution-optional) | No | `forgedock orchestrate`: run lanes in sandboxes instead of host processes (`mode: local\|remote\|hybrid`, `max_remote`) |
 | [`verify`](#verify-optional) | No | Core work-on: run lane verification on CI runners instead of the host (`mode: local\|ci\|hybrid`) |
+| [`selftest`](#selftest-optional) | No | `forgedock selftest --live`: the disposable sandbox repo and fixture language of the live contract harness |
 | [`billing`](#billing-optional) | No | Enable financial integrity audit phase |
 | [`adaptive_scripts`](#adaptive_scripts-optional) | No | Per-repo script override configuration |
 
@@ -658,6 +659,27 @@ prod_watch:
 
 ---
 
+## `selftest` (OPTIONAL)
+
+Settings for `forgedock selftest --live` (see [SELFTEST.md](SELFTEST.md)): a harness that drives the real `gh`, git and `orchestrate` against a disposable sandbox repo, and the `FORGE:SELFTEST` result the staging->main review requires.
+
+```yaml
+selftest:
+  sandbox_repo: acme/forgedock-sandbox   # disposable repo; the harness creates and closes issues, PRs and branches in it
+  fixture: node                          # node (default) | python
+  nightly_interval_hours: 24             # opt-in: schedd runs `selftest --live` this often (default off)
+```
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `sandbox_repo` | string | No | `owner/repo` the live harness runs in. `--repo` overrides it; with neither the command stops. Never point it at a real project. Setting it also turns on the release gate: `forgedock review-staging` then requires a passing `FORGE:SELFTEST` marker for the release PR head; unset, the gate is skipped. |
+| `fixture` | string | No | Toolchain of the two trivial fixture issues: `node` (default) or `python`. `--lang` overrides it. |
+| `nightly_interval_hours` | number | No | Off when unset or 0. When positive, the schedd daemon (host, never GitHub Actions) starts a detached `selftest --live` against `sandbox_repo` once this many hours have passed since the last run of that repo. On failure, including a run that cannot start, it files or edits one issue naming the failed step, in the repo schedd resolves for its working directory. See [SELFTEST.md](SELFTEST.md#nightly-run). |
+
+**Commands that use this section**: `forgedock selftest`, `forgedock review-staging` (release gate, only when `sandbox_repo` is set)
+
+---
+
 ## `issue_watch` (OPTIONAL)
 
 Named, scoped, capped watches for `forgedock issue-watch` (see [ISSUE-WATCH.md](ISSUE-WATCH.md)). Write `issue_watch:`, then `watches:`, then one block per watch name. The release keys need `mode: release` and at least a `threshold` or `immediate`.

package/docs/RELEASE-NOTES.md

@@ -2,6 +2,16 @@
 
 Operator-facing notes for behavior changes that need action or awareness. Newest first.
 
+## Unreleased: `forgedock selftest`, opt-in release gate and nightly run; gate-marker check ignored
+
+- **New command** `forgedock selftest [--static] | --live [--repo <owner/sandbox>] [--pr N]`. It runs a live contract harness against a disposable sandbox repo, plus a static check of every `gh --json` field list. See [SELFTEST.md](SELFTEST.md).
+- **Opt-in nightly run:** `selftest.nightly_interval_hours` makes the schedd daemon start a detached live selftest on that schedule and file one issue on failure. Restart schedd after upgrading to pick it up.
+- **Gate-marker check ignored:** the `Check for FORGE gate markers` check is no longer read as a CI failure by `review-staging`, `/review-pr-staging` or `/deploy-pr`. It only echoes the latest gate marker, so after a GATE_FAILURE it blocked its own GATE_PASS (#4941).
+
+### Live selftest gates the staging->main release review (when a sandbox repo is set)
+
+When forge.yaml sets `selftest.sandbox_repo`, `forgedock review-staging` stops with `REVIEW_RESULT: status: BLOCKED` unless the staging->main PR carries a `FORGE:SELFTEST result=pass` comment for its current head commit (a missing, failing, malformed or stale marker refuses). Run `forgedock selftest --live --repo <owner/sandbox> --pr <N>` (sandbox repo or `selftest.sandbox_repo` in forge.yaml, see [CONFIG.md](CONFIG.md#selftest-optional)) after the last push to the release PR; it posts the marker. Without `selftest.sandbox_repo` the gate is skipped (the CLI prints `SELFTEST: skipped` on stderr), so repos without a sandbox are not blocked. Details: [SELFTEST.md](SELFTEST.md).
+
 ## v1.30.0: environment failures are recoverable, scoped pre-PR checks, decomposed parents can close
 
 - **New recoverable codes.** A validate command the host cannot run (missing interpreter, module or executable) ends `env.tool_missing`, and a repro test the harness could not run on head ends `env.repro_unrunnable`. Both were terminal `conformance.unimplemented` before. The batch runner recovers them like `ci.red` (see docs/OUTCOME-CODES.md).

package/docs/SELFTEST.md

@@ -0,0 +1,34 @@
+# Selftest
+
+The engine's unit tests mock `gh`, git and the pool transport, so defects such as #4859 (`authorAssociation` is not a gh field), #4860 (issue body wiped to `FORGE:STATE`), #4817 and #4818 passed CI. `forgedock selftest` checks the real binaries.
+
+```
+forgedock selftest --static
+forgedock selftest --live [--repo <owner/sandbox>] [--lang node|python] [--pr <staging->main PR>]
+```
+
+`--live` also runs the static check. The sandbox repo comes from `--repo` or `selftest.sandbox_repo` in forge.yaml ([CONFIG.md](CONFIG.md#selftest-optional)). Run it on the host or the pool, not in GitHub Actions. The exit code is non-zero and the output names the failed step.
+
+## Static check
+
+Every literal `gh issue|pr view|list --json a,b` field list in non-test `bin/**/*.mjs` must be a subset of the `JSON FIELDS` of `gh <cmd> --help` on this host. A violation is reported as `file:line`.
+
+## Live steps
+
+1. **create**: the fixture base files, then issues A and B (B has `**Depends on**: #A`), each a trivial change with a test that fails on the old code.
+2. **add**: `orchestrate A --parallel 2`, then `orchestrate --add <id> B`; B must be added (not skipped or unreadable) and wait on A in the DAG.
+3. **body**: after the add, after the resume and while waiting, each issue body must still contain its creation text (`FORGE:STATE` ignored).
+4. **resume**: the orchestrate client is killed and `--resume`d; the live lane of A must be re-adopted, not launched again.
+5. **merge**: both lanes merge; the PRs are `MERGED`, the issues closed with `workflow:merged`, and A merged before B.
+6. **remote**: with `execution.mode` `remote` or `hybrid`, one lane runs remotely; the sandbox engine version must equal the CLI version and the lane must authenticate. Skipped (noted) when no pool is configured.
+7. **cleanup**: always runs, even after a failure: the orchestrate client is stopped; the issues, PRs and branches are closed or deleted.
+
+The first failing step stops the run.
+
+## Release gate
+
+With `--pr N`, the PR head is read before the run (from `--release-repo`, else the current repo), and the result is posted on the PR as `<!-- FORGE:SELFTEST result=pass|fail sha=<head> step=<failed step|none> -->`. When forge.yaml sets `selftest.sandbox_repo`, `forgedock review-staging` reads the newest marker and refuses (`REVIEW_RESULT: status: BLOCKED`, nothing reviewed) unless it is a pass for the PR's current head. Only markers from trusted commenters count (maintainer association, a GitHub App bot, or `FORGE_TRAIL_TRUSTED_LOGINS`), and only when the marker leads the comment. A push after the selftest makes the marker stale: re-run it. The harness refuses a sandbox repo that is the project repo (forge.yaml `project`) or the release repo. Without `selftest.sandbox_repo` the gate is skipped and the CLI prints `SELFTEST: skipped` on stderr.
+
+## Nightly run
+
+Off by default. Set `selftest.nightly_interval_hours` (see [CONFIG.md](CONFIG.md#selftest-optional)) and the schedd daemon starts `selftest --live --nightly-report <repo>` on the host, as a detached process, once that many hours have passed since that repo's last run (last run time cached per repo in `selftest-nightly-<owner>_<repo>.json` under the sched dir). The daemon never runs the harness itself, so a long run never holds its other sweeps. It never runs on GitHub Actions. A failing run, including one that cannot start (for example no `selftest.sandbox_repo`, step `config`) or a harness crash, files one issue titled `selftest --live failed at step <step> (nightly)` carrying `<!-- FORGE:SELFTEST_NIGHTLY -->`; the next failure edits that open issue instead of filing another. A passing run writes nothing. The issue lives in the repo schedd resolves for the working directory, and the sandbox repo must be set by `selftest.sandbox_repo`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.41.0",
+  "version": "1.42.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"