forgedock 1.40.0 → 1.42.0

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/pool/agent.mjs

@@ -10,6 +10,7 @@ import { cpus, hostname } from "node:os";
 import { bearerOk, call, readJson, route, sameSecret, send } from "./http.mjs";
 import { repoRoot, versionOf, laneImageTag, laneBuildArgs } from "./version.mjs";
 import { jsonStore } from "./store.mjs";
+import { makeWarm } from "./warm.mjs";
 
 const LABEL = "computeshare=1";
 const LOG_CHUNK = 256 * 1024;
@@ -60,7 +61,7 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
   const store = jsonStore(join(stateDir, "state.json"), { sandboxes: {} });
   const sb = () => store.data.sandboxes;
   // Sandbox ids come from requests: read own keys only, so "__proto__" or "constructor" never resolves to an inherited member (#4566).
-  const own = (id) => (typeof id === "string" && Object.hasOwn(sb(), id) ? sb()[id] : undefined);
+  const own = (id) => (typeof id === "string" && Object.hasOwn(sb(), id) ? sb()[id] : warm.byAlias(id)); // #4912: a claimed warm sandbox also answers to its lane id
   const leaseTtlMs = (cfg.lease_ttl_s ?? 600) * 1000;
   const maxLifeMs = (cfg.max_lifetime_s ?? 6 * 3600) * 1000;
   const keepExitedMs = (cfg.keep_exited_s ?? 2 * 3600) * 1000;
@@ -99,6 +100,7 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
     if (typeof spec?.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(spec.id) || !Array.isArray(spec.command) || !spec.command.length) throw Object.assign(new Error("spec.id ([A-Za-z0-9._-], max 128) and spec.command are required"), { status: 400 });
     const existing = own(spec.id);
     if (existing) { existing.lease = now(); store.save(); return { status: 200, body: view(existing) }; }
+    if (Number.isInteger(spec.warm)) warm.configure({ spec, cpus, mem_gb, limit, n: spec.warm }); // #4912: the lane's execution.warm_sandboxes sizes the repo's pool
     const c = capacity();
     if (c.paused || c.cpus_free < cpus || c.mem_free_gb < mem_gb) return { status: 503, body: { error: "no capacity", capacity: c }, retryAfter: 60 };
     // Burst model: reservations are small, so also refuse when the VM is genuinely short of memory or overloaded right now.
@@ -108,6 +110,7 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
     const dir = join(stateDir, "sandboxes", name);
     mkdirSync(join(dir, "result"), { recursive: true });
     mkdirSync(join(dir, "out"), { recursive: true });
+    if (spec.claim_dir) mkdirSync(join(dir, "claim"), { recursive: true });
     const envFile = join(dir, "env");
     const credToken = randomBytes(24).toString("hex");
     const withDocker = Boolean(spec.docker);
@@ -147,6 +150,7 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
         // --memory-swap above --memory lets a rare spike page out instead of being OOM-killed (swap deal).
         "--cpus", String(laneCpus), "--memory", mb(laneMem), "--memory-swap", mb(laneMem + swapFor(limit?.lane_swap_gb)), "--pids-limit", "4096",
         "--env-file", envFile, ...laneNet, ...work,
+        ...(spec.claim_dir ? ["-v", `${join(dir, "claim")}:/claim`] : []), // #4912: warm sandboxes receive their lane here
         "-v", `cs-cache-${cacheKey}:/cache`, "-v", `${join(dir, "result")}:/result`, "-v", `${join(dir, "out")}:/csout`,
         spec.image ?? image, ...spec.command.map(String),
       ]);
@@ -165,6 +169,8 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
 
   const view = (r) => ({ id: r.id, state: r.state, issue: r.issue, cpus: r.cpus, mem_gb: r.mem_gb, started_at: new Date(r.startedAt).toISOString(), ...(r.error ? { error: r.error } : {}) });
 
+  const warm = makeWarm({ store, sb, own, now, launch, destroy: (id, why) => destroy(id, why), view, log });
+
   async function refresh(r) {
     if (r.state === "exited") return r;
     const s = await docker.inspect(r.name);
@@ -200,7 +206,7 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
     if (r.docker) { await docker.remove(dindName(r.name)); await docker.removeVolume(workVolume(r.name)); }
     try { await docker.wipe(r.dir, image); } catch (e) { log.warn?.(`wipe ${r.name}: ${String(e.stderr || e.message).slice(0, 200)}`); }
     rmSync(r.dir, { recursive: true, force: true });
-    delete sb()[id];
+    delete sb()[r.id];
     store.save();
     // Written once, after the sandbox is really gone (a teardown that throws and is retried must not log it twice).
     if (history) { try { appendFileSync(join(stateDir, "usage-history.jsonl"), history + "\n"); } catch { /* best effort */ } }
@@ -218,6 +224,7 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
     const known = new Set(Object.values(sb()).flatMap((r) => [r.name, dindName(r.name)]));
     for (const name of await docker.listLabelled(LABEL)) if (!known.has(name)) { await docker.remove(name); log.info?.(`removed orphan container ${name}`); }
     await sampleUsage();
+    await warm.maintain(maxLifeMs);
     if (pendingResize && capacity().active === 0) {
       const r = await resize(pendingResize);
       log.info?.(`pending resize applied: HTTP ${r.status} ${JSON.stringify(r.body)}`);
@@ -250,7 +257,8 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
     const r = own(id);
     const m = /^Bearer\s+(\S.*)$/i.exec(req.headers.authorization ?? "");
     if (!r || r.state === "exited" || !m || !sameSecret(m[1].trim(), r.credToken)) return { status: 401, body: { error: "unauthorized" } };
-    const path = `/agent/relay/${encodeURIComponent(id)}${rid ? `/${encodeURIComponent(rid)}` : ""}`;
+    const lane = r.alias ?? r.id; // #4935: a claimed warm sandbox posts under its warm id, but the router queue and the dispatcher use the lane id
+    const path = `/agent/relay/${encodeURIComponent(lane)}${rid ? `/${encodeURIComponent(rid)}` : ""}`;
     const x = rid ? await call(cfg.router_url, "GET", path, { token: cfg.token, timeoutMs: 20000 })
       : await call(cfg.router_url, "POST", path, { token: cfg.token, timeoutMs: 20000, body: { argv: (await readJson(req, 32 * 1024))?.argv } });
     return { status: x.status, body: x.data };
@@ -366,7 +374,10 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
   const routes = [
     [route("GET", "/health"), async () => ({ status: 200, body: { ok: true, ...capacity() } })],
     [route("GET", "/capacity"), async () => ({ status: 200, body: capacity() })],
-    [route("POST", "/sandboxes"), async (_p, body) => launch(body ?? {})],
+    [route("POST", "/sandboxes"), async (_p, body) => { const r = await launch(body ?? {}); if (Number.isInteger(body?.spec?.warm)) warm.replenish().catch((e) => log.warn?.(`warm replenish: ${e.message}`)); return r; }],
+    [route("GET", "/warm"), async () => ({ status: 200, body: { warm: warm.list() } })],
+    [route("POST", "/warm"), async (_p, body) => { const r = warm.configure({ ...(body ?? {}), n: body?.n }); await warm.replenish(); return { status: 200, body: { ...r, warm: warm.list() } }; }],
+    [route("POST", "/warm/claim"), async (_p, body) => warm.claim(body ?? {})],
     [route("GET", "/sandboxes/:id"), async ({ id }) => { const r = own(id); if (!r) return { status: 404, body: { state: "gone" } }; await refresh(r); store.save(); return { status: 200, body: view(r) }; }],
     [route("GET", "/sandboxes/:id/logs"), async ({ id }, _b, url) => { const r = own(id); return r ? { status: 200, body: readLog(r, url.searchParams.get("cursor")) } : { status: 404, body: { text: "", cursor: 0 } }; }],
     [route("GET", "/sandboxes/:id/result"), async ({ id }) => { const r = own(id); const x = r && readResult(r); return x ? { status: 200, body: x } : { status: 404, body: { error: "no result" } }; }],
@@ -411,7 +422,7 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
     await docker.build(join(cfg.code_root ?? repoRoot, "pool", "image"), image, laneBuildArgs(running.version));
   }
 
-  return { handle, launch, reap, destroy, capacity, refresh, store, prepullImages, ensureImage };
+  return { handle, launch, warm, reap, destroy, capacity, refresh, store, prepullImages, ensureImage };
 }
 
 /**

package/bin/pool/router.mjs

@@ -167,6 +167,21 @@ export function createRouter(cfg, { fetchFn = globalThis.fetch, now = () => Date
     return { status: 503, body: { error: "no host has a free reservation", lane: size }, retryAfter: cfg.retry_after_s ?? 60 };
   }
 
+  /** #4912: hand the lane to an agent's ready warm sandbox; 404 when no agent has one (the caller then launches cold). */
+  async function claim(spec) {
+    if (typeof spec?.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(spec.id)) return { status: 400, body: { error: "spec.id required ([A-Za-z0-9._-], max 128)" } };
+    if (own(sbx(), spec.id)) return launch(spec); // already placed: the same idempotent path
+    const size = sizeFor(spec);
+    for (const c of (await capacities()).filter((x) => x.ok && !x.paused)) {
+      const r = await agentCall(own(agents(), c.name), "POST", "/warm/claim", { spec: withForgeYaml(spec), ...size }, 30000);
+      if (!r.ok) continue;
+      sbx()[spec.id] = { agent: c.name, issue: spec.issue ?? null, batch: spec.batch ?? null, createdAt: now(), touched: now() };
+      store.save();
+      return { status: 200, body: { ...(r.data ?? {}), agent: c.name } };
+    }
+    return { status: 404, body: { error: "no warm sandbox ready" } };
+  }
+
   async function forward(id, method, path) {
     const s = own(sbx(), id);
     const a = s && own(agents(), s.agent);
@@ -253,6 +268,7 @@ export function createRouter(cfg, { fetchFn = globalThis.fetch, now = () => Date
   const routes = [
     [route("GET", "/health"), { fn: async () => ({ status: 200, body: { ok: true, agents: Object.keys(agents()).length, sandboxes: Object.keys(sbx()).length } }), auth: "none" }],
     [route("POST", "/sandboxes"), fd(async (_p, body) => launch(body))],
+    [route("POST", "/sandboxes/claim"), fd(async (_p, body) => claim(body))],
     [route("GET", "/sandboxes/:id"), fd(async ({ id }) => forward(id, "GET", `/sandboxes/${encodeURIComponent(id)}`))],
     [route("GET", "/sandboxes/:id/logs"), fd(async ({ id }, _b, url) => forward(id, "GET", `/sandboxes/${encodeURIComponent(id)}/logs?cursor=${encodeURIComponent(url.searchParams.get("cursor") ?? "0")}`))],
     [route("GET", "/sandboxes/:id/result"), fd(async ({ id }) => forward(id, "GET", `/sandboxes/${encodeURIComponent(id)}/result`))],
@@ -325,7 +341,7 @@ export function createRouter(cfg, { fetchFn = globalThis.fetch, now = () => Date
     }
   }
 
-  return { handle, launch, tick, enroll, issueCode, capacities, status, store };
+  return { handle, launch, claim, tick, enroll, issueCode, capacities, status, store };
 }
 
 export function startRouter(cfg, deps) {