forgedock 1.40.0 → 1.42.0

package/bin/lean/prodwatch.test.mjs

@@ -35,7 +35,17 @@ function world({ alerts = [], issues = [], probe = 0, killed = false, llmCost =
     now: () => NOW, exists: () => killed, emit: (r) => w.emits.push(r), page: (p) => { w.pages.push(p); return true; },
     exec: async (cmd) => { w.execs.push(cmd); return cmd === "am-alerts" ? { code: 0, stdout: JSON.stringify(alerts) } : { code: probe, stdout: "" }; },
     llm: async () => { w.llm++; return { text: "Hypothesis: pool exhausted.", cost_usd: llmCost }; },
-    gh: async (a) => { w.gh.push(a); if (a[1] === "list") return JSON.stringify(issues); return `https://github.com/o/r/issues/${100 + w.gh.length}\n`; },
+    gh: async (a) => {
+      w.gh.push(a);
+      if (a[0] === "api") {
+        const open = issues.filter((i) => i.state === "OPEN").sort((x, y) => y.createdAt.localeCompare(x.createdAt))
+          .map((i) => ({ number: i.number, state: "open", state_reason: i.stateReason ?? null, body: i.body, created_at: i.createdAt, closed_at: null }));
+        const pages = []; for (let k = 0; k < open.length; k += 100) pages.push(open.slice(k, k + 100));
+        if (pages.length) pages[0].push({ number: 9999, state: "open", body: "a PR", pull_request: {}, created_at: "2026-10-31T00:00:00Z" });
+        return JSON.stringify(pages.length ? pages : [[]]);
+      }
+      if (a[1] === "list") return JSON.stringify(issues.filter((i) => i.state === "CLOSED").slice(0, Number(a[a.indexOf("--limit") + 1])));
+      return `https://github.com/o/r/issues/${100 + w.gh.length}\n`; },
   };
   return w;
 }
@@ -95,7 +105,7 @@ describe("roundOnce", () => {
     const state = {};
     const r = await roundOnce({ cfg, io: w.io, state, dryRun: true });
     assert.equal(r.would_file.length, 1);
-    assert.equal(w.gh.every((a) => a[1] === "list"), true);
+    assert.equal(w.gh.every((a) => a[1] === "list" || a[0] === "api"), true);
     assert.equal(w.llm, 0); assert.equal(w.pages.length, 0); assert.equal(w.emits.length, 0);
     assert.deepEqual(state.filed, []);
   });
@@ -271,11 +281,30 @@ describe("roundOnce", () => {
   });
   it("files nothing when the issue list fails (no blind duplicates)", async () => {
     const w = world({ alerts: [alert("Slow", "P2")] });
-    const orig = w.io.gh; w.io.gh = async (a) => { if (a[1] === "list") throw new Error("rate limited"); return orig(a); };
+    const orig = w.io.gh; w.io.gh = async (a) => { if (a[0] === "api") throw new Error("rate limited"); return orig(a); };
     const r = await roundOnce({ cfg, io: w.io, state: {} });
     assert.equal(r.filed.length, 0);
     assert.match(r.errors[0], /nothing filed/);
   });
+  it("still files when only the closed lookup fails", async () => {
+    const w = world({ alerts: [alert("Slow", "P2")] });
+    const orig = w.io.gh; w.io.gh = async (a) => { if (a[1] === "list") throw new Error("boom"); return orig(a); };
+    const r = await roundOnce({ cfg, io: w.io, state: {} });
+    assert.equal(r.filed.length, 1);
+    assert.match(r.errors.join(), /closed issue list failed/);
+  });
+  it("sees an open issue older than 200 newer ones: no duplicate filed", async () => {
+    const filed = world({ alerts: [alert("Slow", "P2")] });
+    await roundOnce({ cfg, io: filed.io, state: {} });
+    const c = creates(filed)[0], oldBody = c[c.indexOf("--body") + 1];
+    const mk = (n) => ({ number: n, state: "OPEN", body: "unrelated", createdAt: `2026-10-31T00:${String(Math.floor((n - 1000) / 60)).padStart(2, "0")}:${String((n - 1000) % 60).padStart(2, "0")}Z` });
+    const issues = [...Array.from({ length: 250 }, (_, k) => mk(1000 + k)), { number: 5, state: "OPEN", body: oldBody, createdAt: "2026-10-01T00:00:00Z" }];
+    const w = world({ alerts: [alert("Slow", "P2")], issues });
+    const r = await roundOnce({ cfg, io: w.io, state: {} });
+    assert.equal(creates(w).length, 0);
+    assert.equal(r.filed.length, 0);
+    assert.ok(w.gh.some((a) => a.includes("--paginate")));
+  });
 });
 
 describe("helpers and CLI", () => {

package/bin/lean/prompts.mjs

@@ -7,6 +7,7 @@ import { reviewSkeleton } from "./conformance.mjs";
 import { seqNumber } from "./sequence.mjs";
 import { capText, FIX_CAPS, FIX_PROMPT_MAX } from "./fixround.mjs";
 import { SPLIT_MIN_FILES, SPLIT_MIN_LINES } from "./decompose.mjs";
+import { isTrustedIssueComment } from "./prefilter.mjs"; // call-time use only: prefilter.mjs imports this module
 
 export const approxTokens = (s) => Math.ceil(String(s).length / 4);
 export const LEAN_DIR = ".forge-lean";
@@ -424,8 +425,26 @@ export function boundDiff(diff, { stat = "", base = "", maxBytes = REVIEW_DIFF_M
     + (list.length ? `\n<omitted_files>\n${list.join("\n")}\n</omitted_files>` : "");
 }
 
+const isDecision = (b) => /^<!-- FORGE:DECISION\b/.test(String(b ?? "").trim());
+const DECISION_NOTE_MAX = 4000;
+/**
+ * #4901: the trusted `FORGE:DECISION` comments posted after the last `FORGE:CONTRACT` comment (issue order), as a binding note for a
+ * lane that resumes a frozen contract without a plan session. The lane's own recovery records are skipped; the newest decisions survive the cap.
+ * "" when there are none.
+ */
+export function decisionNote(comments = []) {
+  const list = Array.isArray(comments) ? comments : [];
+  const at = list.map((c) => String(c?.body ?? "").trimStart().startsWith("<!-- FORGE:CONTRACT")).lastIndexOf(true);
+  const ds = list.slice(at + 1).filter((c) => isTrustedIssueComment(c) && isDecision(c?.body) && !/^##\s*Decision: recovery pass/m.test(String(c.body))).map((c) => String(c.body).trim());
+  let kept = [], n = 0;
+  for (const d of ds.reverse()) { if (n + d.length > DECISION_NOTE_MAX && kept.length) break; kept.unshift(d.length > DECISION_NOTE_MAX ? d.slice(0, DECISION_NOTE_MAX) : d); n += d.length; }
+  return kept.length ? `\n\nBinding decisions posted after the contract froze (trusted; they override the issue text where they conflict, and the frozen contract still applies):\n${kept.join("\n---\n")}` : "";
+}
+
 export function reviewerPrompt({ issue, comments = [], contract, result, files = [], diff, stat = "", base = "", structure = "", ignore = [`${LEAN_DIR}/`], skeleton = null }) {
   const notes = comments.map((c) => String(c?.body ?? "")).filter((b) => !/^<!-- FORGE:/.test(b.trim()));
+  const decisions = comments.filter((c) => isDecision(c?.body) && isTrustedIssueComment(c)).map((c) => String(c.body)); // #4901: operator decisions bind the review; other FORGE: records stay out
+  notes.push(...decisions);
   const sk = JSON.stringify(skeleton ?? reviewSkeleton(contract ?? {}, files, ignore), null, 1);
   return `Issue #${issue.number}: ${issue.title}\n\n<issue_body>\n${cap(issue.body ?? "", 20000)}\n</issue_body>\n\n<issue_comments>\n${cap(notes.join("\n---\n"), 8000)}\n</issue_comments>\n\n<contract>\n${cap(JSON.stringify(contract ?? {}, null, 1), 12000)}\n</contract>\n\n<builder_result>\n${cap(JSON.stringify(result ?? {}, null, 1), 6000)}\n</builder_result>\n\n<changed_files>\n${files.join("\n")}\n</changed_files>\n\n<rubric>\n${REVIEW_RUBRIC}\n</rubric>\n\n<row_skeleton>\n${cap(sk, 30000)}\n</row_skeleton>\n\n<diff>\n${boundDiff(diff, { stat, base })}\n</diff>${structure ? `\n<structure>${String(structure).replace(/[\r\n]+/g, " ")}</structure>` : ""}`;
 }

package/bin/lean/render.mjs

@@ -140,8 +140,16 @@ export function parseContractComment(body) {
 }
 
 /** Typed amendments, posted visibly before review. */
-export function renderAmendments(applied, filed = {}) {
-  return `## Contract Amendments\n| Kind | Target | Why |\n| --- | --- | --- |\n${applied.map((a) => `| ${esc(a.kind)} | ${esc(a.target)}${filed[a.target] ? ` → ${filed[a.target]}` : ""} | ${esc(a.why)} |`).join("\n")}`;
+export function renderAmendments(applied, filed = {}, state = null) {
+  const block = state ? `\n\n<!-- FORGE:AMENDMENT-STATE ${JSON.stringify(state).replace(/</g, "\\u003c").replace(/>/g, "\\u003e")} -->` : "";
+  return `## Contract Amendments\n| Kind | Target | Why |\n| --- | --- | --- |\n${applied.map((a) => `| ${esc(a.kind)} | ${esc(a.target)}${filed[a.target] ? ` → ${filed[a.target]}` : ""} | ${esc(a.why)} |`).join("\n")}${block}`;
+}
+
+/** #4899: the raw amendments a FORGE:AMENDMENT comment carries, `{contract, amendments}` (contract = frozen hash), or null. */
+export function parseAmendmentsComment(body) {
+  const m = /<!-- FORGE:AMENDMENT-STATE (.*?) --!?>/.exec(String(body ?? ""));
+  if (!m) return null;
+  try { const j = JSON.parse(m[1]); return typeof j?.contract === "string" && Array.isArray(j.amendments) ? j : null; } catch { return null; }
 }
 
 /** FORGE:REVIEW for a conforming change: the engine-computed verdict and the reviewer's rows. */

package/bin/lean/sandbox-provider.contract.test.mjs

@@ -373,3 +373,51 @@ describe("remote stop at the checkpoint (#4612)", () => {
     assert.deepEqual(transport.destroyed, []);
   });
 });
+
+describe("remote provider: warm sandboxes (#4912)", () => {
+  const warmFixture = ({ warm, claim } = {}) => {
+    const work = tmpDir("contract-warm-"); const batch = openBatch(join(work, "batches"), "bt");
+    const transport = fakeTransport();
+    const calls = [];
+    if (claim) transport.claim = async (spec) => { calls.push(spec); return claim(spec); };
+    const provider = remoteProvider({ batch, repo: "o/r", settings: { image: "img:1", secrets: ["GH_TOKEN"], ...(warm !== undefined ? { warmSandboxes: warm } : {}) }, transport,
+      env: { GH_TOKEN: SECRET }, credentials: () => null, gitIdentity: () => ({}) });
+    return { provider, transport, calls };
+  };
+  const start = (provider) => provider.start({ issue: 7, args: ["--repo", "o/r", "--lane", "staging"], env: { GH_TOKEN: SECRET }, secrets: ["GH_TOKEN"] });
+
+  it("warm_sandboxes > 0: a ready warm sandbox is claimed and no cold launch happens", async () => {
+    const { provider, transport, calls } = warmFixture({ warm: 2, claim: async () => ({ id: "fdrsbx-bt-7" }) });
+    const h = await start(provider);
+    assert.equal(h.id, "fdrsbx-bt-7");
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].warm, 2);
+    assert.equal(transport.specs.length, 0, "no cold launch");
+  });
+  it("warm_sandboxes > 0: none ready (null) or a claim error falls back to the cold launch", async () => {
+    for (const claim of [async () => null, async () => { throw new Error("sandbox claim: HTTP 500"); }]) {
+      const { provider, transport } = warmFixture({ warm: 1, claim });
+      await start(provider);
+      assert.equal(transport.specs.length, 1);
+    }
+  });
+  it("default (0 or unset): claim is never called and the spec carries no warm key", async () => {
+    for (const warm of [undefined, 0]) {
+      const { provider, transport, calls } = warmFixture({ warm, claim: async () => ({}) });
+      await start(provider);
+      assert.equal(calls.length, 0);
+      assert.equal("warm" in transport.specs[0], false);
+    }
+  });
+  it("a transport without claim is a cold start", async () => {
+    const { provider, transport } = warmFixture({ warm: 1 });
+    await start(provider);
+    assert.equal(transport.specs.length, 1);
+  });
+  it("httpTransport.claim: 200 = claimed, 404/204/405 = none, 500 throws", async () => {
+    const mk = (status, data) => httpTransport({ endpoint: "http://p", fetchFn: async () => ({ status, ok: status < 300, text: async () => (data ? JSON.stringify(data) : ""), headers: { get: () => null } }) });
+    assert.deepEqual(await mk(200, { id: "x" }).claim({ id: "x" }), { id: "x" });
+    for (const s of [204, 404, 405]) assert.equal(await mk(s).claim({ id: "x" }), null);
+    await assert.rejects(() => mk(500).claim({ id: "x" }), /HTTP 500/);
+  });
+});

package/bin/lean/sandbox-remote.mjs

@@ -69,6 +69,8 @@ export function httpTransport({ endpoint, token = null, fetchFn = globalThis.fet
   const p = (id) => `/sandboxes/${encodeURIComponent(id)}`;
   return {
     async launch(spec) { const r = await call("POST", "/sandboxes", spec); if (!r.ok) throw fail("launch", r); return r.data ?? {}; },
+    /** #4912: hand the lane to a ready warm sandbox. 200/201 = claimed; 204/404/405 (none ready, or a pool without warm sandboxes) = null. */
+    async claim(spec) { const r = await call("POST", "/sandboxes/claim", spec); if (r.status === 200 || r.status === 201) return r.data ?? {}; if (r.status === 204 || r.status === 404 || r.status === 405) return null; throw fail("claim", r); },
     async status(id) {
       const r = await call("GET", p(id));
       if (r.status === 404) return "gone";
@@ -185,16 +187,21 @@ export function remoteProvider({ batch, repo, settings = {}, name = "remote", tr
       const li = args.indexOf("--lane");
       const resultFile = `/result/${issue}.json`;
       const relayEnv = relays.length ? { CS_RELAY_COMMANDS: relayCommandNames(relay).join(","), CS_RELAY_CAPS: relays.join(","), ...(await prefetchEnv(issue)) } : {};
+      const warm = Number.isInteger(settings.warmSandboxes) && settings.warmSandboxes > 0 ? settings.warmSandboxes : 0;
       const spec = {
         id, issue, batch: batch.id, image: settings.image ?? null,
         repo: { slug: repo, url: repo ? `https://github.com/${repo}.git` : null, ref: li >= 0 ? args[li + 1] ?? null : null },
+        ...(warm ? { warm } : {}), // #4912: the pool agent keeps this many warm sandboxes for the repo
         cache: settings.cacheStore ? { store: settings.cacheStore, key: safeSegment(String(repo ?? "repo")) } : null,
         // The host's git identity: without it the lane image falls back to a placeholder author that fails DCO.
         env: { ...gitIdentityEnv(gitIdentity(), laneEnv ?? {}), ...scopedEnv({ env: resolved, secrets, batchId: batch.id, repo }), ...(settings.forgeYaml ? { CS_FORGE_YAML_B64: Buffer.from(settings.forgeYaml).toString("base64") } : {}), ...relayEnv }, // #4546: the dispatcher's forge.yaml (gitignored in the repo)
         command: ["forgedock", "run-issue", String(issue), ...args, "--result-file", resultFile], result_file: resultFile,
       };
       const startedAt = now();
-      await transport.launch(spec);
+      // #4912: a ready warm sandbox first; none, an error or a transport without claim is the cold start.
+      let claimed = null;
+      if (warm && typeof transport.claim === "function") { try { claimed = await transport.claim(spec); } catch { claimed = null; } }
+      if (!claimed) await transport.launch(spec);
       return { provider: name, id, issue, startedAt, minutes: 0 };
     },
     async status(h) {

package/bin/lean/schedd.mjs

@@ -130,7 +130,7 @@ function takeLock(lock, pid, alive) {
  */
 export async function startDaemon({ dir = schedDir(), runBatch, idleMs = Number(process.env.FORGEDOCK_SCHEDD_IDLE_MS) || IDLE_MS,
   root = batchRoot(), log = (m) => console.log(m), pid = process.pid, alive = pidAlive, resumeOnStart = true, stopMs = STOP_MS,
-  lockCheckMs = LOCK_CHECK_MS, due = null, dueMs = Number(process.env.FORGEDOCK_SCHEDD_DUE_MS) || DUE_MS } = {}) {
+  lockCheckMs = LOCK_CHECK_MS, due = null, dueMs = Number(process.env.FORGEDOCK_SCHEDD_DUE_MS) || DUE_MS, preflight = null } = {}) {
   const p = scheddPaths(dir);
   mkdirSync(dir, { recursive: true });
   const lock = takeLock(p.lock, pid, alive);
@@ -318,6 +318,10 @@ export async function startDaemon({ dir = schedDir(), runBatch, idleMs = Number(
   }, dueMs) : null;
   dueTimer?.unref?.();
 
+  // #4866: lane preflight at daemon start: each failing check is logged once with its typed code (batches re-check on every admission pass).
+  // Not awaited: gh and pool pings are slow, and startup (resume, socket) must not wait on them.
+  if (preflight) Promise.resolve().then(preflight).then((fails) => { for (const f of fails ?? []) log(`schedd: ${f.code}: ${f.detail}`); }).catch(() => { /* advisory */ });
+
   // #4787: plans written before secrets were dropped still hold token values; scrub them on start.
   for (const id of listBatches(root)) { try { const n = openBatch(root, id).scrubPlan(); if (n.length) log(`schedd: scrubbed ${n.join(", ")} from batch ${id}`); } catch { /* advisory */ } }
 

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