forgedock 1.25.1 → 1.27.0

package/bin/lean/conformance.test.mjs

@@ -0,0 +1,192 @@
+// 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 { validateContract, applyAmendments, precheck, parseReview, checkCompleteness, decide, closePlan, followupItems, inIssue, isTestPath, reviewSkeleton, resolveEvidencePath } from "./conformance.mjs";
+
+const ISSUE = "## Requirements\n1. The scrape route must release the spend reservation on 429.\n2. The search route must release the spend reservation on 429.\n\n- [ ] Billing pricing is unchanged.";
+const Q1 = "The scrape route must release the spend reservation on 429.";
+const Q2 = "The search route must release the spend reservation on 429.";
+const C = {
+  requirements: [{ id: "R1", quote: Q1, disposition: "deliver" }, { id: "R2", quote: Q2, disposition: "deliver" }],
+  deliverables: [{ id: "D1", path: "src/scrape.js" }, { id: "D2", path: "src/search.js" }],
+  preserve: [{ id: "P1", what: "Billing pricing is unchanged. (src/billing.js)" }],
+  validate: [{ id: "V1", command: "node --test test/leak.test.js" }],
+};
+const files = ["src/scrape.js", "src/search.js", "test/leak.test.js"];
+const ctx = { contract: C, changedFiles: files, issueText: ISSUE, pathExists: (p) => p === "src/billing.js" };
+const good = {
+  issue_coverage: [{ quote: Q1, status: "covered" }, { quote: Q2, status: "covered" }, { quote: "Billing pricing is unchanged.", status: "covered" }],
+  requirements: [{ id: "R1", status: "implemented", evidence: "src/scrape.js:7", validated_by: "V1" }, { id: "R2", status: "implemented", evidence: "src/search.js:7", validated_by: "V1" }],
+  scope: [{ file: "src/scrape.js", authorized_by: "D1" }, { file: "src/search.js", authorized_by: "D2" }, { file: "test/leak.test.js", authorized_by: "test" }],
+  preserve: [{ id: "P1", status: "intact", evidence: "src/billing.js:1" }], regressions: [], verdict: "CONFORMS", summary: "ok",
+};
+const row = (id, patch) => ({ ...good, requirements: good.requirements.map((r) => (r.id === id ? { ...r, ...patch } : r)) });
+const codes = (d) => d.failures.map((f) => f.code);
+
+describe("contract", () => {
+  it("a well-formed contract with verbatim quotes is valid", () => assert.deepEqual(validateContract(C, ISSUE), { ok: true, problems: [] }));
+  it("quotes must be verbatim (whitespace and emphasis aside) and long enough", () => {
+    assert.ok(inIssue("the  SCRAPE route must release the spend reservation on 429.", ISSUE));
+    assert.ok(!inIssue("scrape should free money", ISSUE));
+    assert.ok(!inIssue("429.", ISSUE), "too short to identify a requirement");
+  });
+  it("rejects paraphrases, a defer without why, not-applicable without evidence, missing validate, duplicate ids", () => {
+    const v = validateContract({ ...C, validate: [], requirements: [
+      { id: "R1", quote: "make scrape better", disposition: "deliver" }, { id: "R2", quote: Q2, disposition: "defer" },
+      { id: "R2", quote: Q2, disposition: "not-applicable" }, { id: "R4", quote: Q1, disposition: "maybe" }] }, ISSUE);
+    assert.equal(v.ok, false);
+    for (const p of [/R1: quote is not verbatim/, /R2: defer needs a why/, /duplicated: R2/, /not-applicable needs file:line evidence/, /R4: disposition must be one of/, /no validate\[\] commands/]) assert.ok(v.problems.some((x) => p.test(x)), String(p));
+    assert.equal(validateContract(null, ISSUE).ok, false);
+  });
+});
+
+describe("amendments", () => {
+  it("add-deliverable, add-requirement and defer apply with a why; defer is queued for tracking once", () => {
+    const a = applyAmendments(C, [
+      { kind: "add-deliverable", path: "src/shared.js", why: "both routes share the helper" },
+      { kind: "add-requirement", requirement: { id: "R3", quote: "Billing pricing is unchanged.", disposition: "deliver" }, why: "missed" },
+      { kind: "defer", requirement: "R2", why: "search is owned by another module" }]);
+    assert.deepEqual(a.problems, []);
+    assert.ok(a.contract.deliverables.some((d) => d.path === "src/shared.js"));
+    assert.equal(a.contract.requirements.find((r) => r.id === "R2").disposition, "defer");
+    assert.deepEqual(a.toTrack.map((r) => r.id), ["R2"]);
+    assert.equal(a.applied.length, 3);
+    assert.equal(C.requirements[1].disposition, "deliver", "the frozen contract is never mutated");
+  });
+  it("an amendment without a why, an unknown requirement or an unknown kind is a problem, not applied", () => {
+    const a = applyAmendments(C, [{ kind: "add-deliverable", path: "x.js" }, { kind: "defer", requirement: "R9", why: "w" }, { kind: "rewrite", why: "w" }]);
+    assert.equal(a.problems.length, 3); assert.equal(a.applied.length, 0);
+  });
+});
+
+describe("precheck (deterministic, no reviewer)", () => {
+  const res = { requirements: [{ id: "R1", status: "implemented" }, { id: "R2", status: "implemented" }], validation: [{ id: "V1", exit: 0 }] };
+  it("passes a complete, validated, in-scope change", () => assert.deepEqual(precheck({ contract: C, result: res, changedFiles: files }), { ok: true, failures: [] }));
+  it("unauthorized file -> scope_creep; tests and ignored paths are always allowed", () => {
+    assert.deepEqual(codes(precheck({ contract: C, result: res, changedFiles: [...files, "src/billing.js", ".forge-lean/x", "tests/test_x.py", "pkg/foo_test.go"], ignore: [".forge-lean/"] })), ["conformance.scope_creep"]);
+    for (const t of ["test/a.js", "src/a.test.ts", "tests/test_a.py", "a_test.go", "spec/a.spec.js"]) assert.ok(isTestPath(t), t);
+    assert.ok(!isTestPath("src/testing.js"));
+  });
+  it("failed or missing validation -> unimplemented", () => {
+    assert.deepEqual(codes(precheck({ contract: C, result: { ...res, validation: [{ id: "V1", exit: 1 }] }, changedFiles: files })), ["conformance.unimplemented"]);
+    assert.deepEqual(codes(precheck({ contract: C, result: { ...res, validation: [] }, changedFiles: files })), ["conformance.unimplemented"]);
+  });
+  it("a deliver requirement reported deferred without an amendment -> untracked_deferral; partial -> unimplemented", () => {
+    const r = { ...res, requirements: [{ id: "R1", status: "deferred" }, { id: "R2", status: "partial" }] };
+    assert.deepEqual(codes(precheck({ contract: C, result: r, changedFiles: files })), ["conformance.untracked_deferral", "conformance.unimplemented"]);
+  });
+  it("a typed deferral is not a precheck failure: the reviewer judges it, then it is filed", () => {
+    const k = { ...C, requirements: [C.requirements[0], { ...C.requirements[1], disposition: "defer", why: "w" }] };
+    assert.equal(precheck({ contract: k, result: res, changedFiles: files }).ok, true);
+  });
+  it("deliverables may be directories or globs; changelogs and lockfiles are always allowed", () => {
+    const k = { ...C, deliverables: [{ id: "D1", path: "src/" }, { id: "D2", path: "./lib/**/*.go" }] };
+    assert.equal(precheck({ contract: k, result: res, changedFiles: ["src/a/b.js", "lib/x/y/z.go", "CHANGELOG.md", "web/package-lock.json", "go.sum"] }).ok, true);
+    assert.deepEqual(codes(precheck({ contract: k, result: res, changedFiles: ["lib/x.py"] })), ["conformance.scope_creep"]);
+  });
+});
+
+describe("conformance review: the engine computes the verdict from complete rows", () => {
+  it("complete conforming rows conform", () => assert.equal(decide(good, ctx).state, "conforms"));
+  it("a generic PASS (the old two-question reply) is incomplete, never conforming", () => {
+    const d = decide({ verdict: "PASS", fixes_issue: true, regression: false, reason: "looks good" }, ctx);
+    assert.equal(d.state, "review.incomplete");
+    assert.ok(d.failures.every((f) => f.code === "review.incomplete"));
+  });
+  it("no JSON is unparseable", () => { assert.equal(parseReview("LGTM"), null); assert.equal(decide(null, ctx).state, "review.unparseable"); });
+  it("incomplete: missing requirement row, missing scope row for an unauthorized changed file, missing preserve row", () => {
+    assert.equal(decide({ ...good, requirements: good.requirements.slice(1) }, ctx).state, "review.incomplete");
+    const extra = { ...ctx, changedFiles: [...files, "src/billing.js"] };
+    assert.equal(checkCompleteness(good, extra).problems.includes("changed file src/billing.js has no scope row"), true);
+    assert.equal(decide({ ...good, preserve: [] }, ctx).state, "review.incomplete");
+  });
+  it("#4160: a changed file the contract already authorizes (deliverable, test, incidental) needs no scope row", () => {
+    assert.equal(decide({ ...good, scope: [] }, ctx).state, "conforms");
+    assert.equal(checkCompleteness({ ...good, scope: [] }, { ...ctx, changedFiles: [...files, "CHANGELOG.md"] }).complete, true);
+  });
+  it("#4160: a scope row the reviewer gives for an authorized file is still judged (none on a deliverable is creep)", () => {
+    const s = good.scope.map((x) => (x.file === "src/scrape.js" ? { ...x, authorized_by: "none", note: "unrelated rewrite" } : x));
+    assert.equal(decide({ ...good, scope: s }, ctx).state, "nonconforming");
+  });
+  it("#4160: evidence given as a bare or partial file name resolves to the one changed file it names", () => {
+    assert.equal(resolveEvidencePath("scrape.js", files), "src/scrape.js");
+    assert.equal(resolveEvidencePath("./src/scrape.js", files), "src/scrape.js");
+    assert.equal(resolveEvidencePath("leak.test.js", files), "test/leak.test.js");
+    assert.equal(resolveEvidencePath("x.js", ["a/x.js", "b/x.js"]), null, "ambiguous");
+    assert.equal(resolveEvidencePath("nope.js", files), null);
+    assert.equal(decide(row("R1", { evidence: "scrape.js:4" }), ctx).state, "conforms");
+  });
+  it("#4160: reviewSkeleton lists every required row, pre-filled, with scope rows only for unauthorized files", () => {
+    const k = { ...C, requirements: [...C.requirements, { id: "R9", quote: "Billing pricing is unchanged.", disposition: "defer", why: "w" }] };
+    const sk = reviewSkeleton({ contract: k, changedFiles: [...files, "src/billing.js", ".forge-lean/x"], ignore: [".forge-lean/"] });
+    assert.deepEqual(sk.requirements.map((r) => r.id), k.requirements.map((r) => r.id));
+    assert.equal(sk.requirements.find((r) => r.id === "R9").deferral_ok, null);
+    assert.ok(!("deferral_ok" in sk.requirements[0]));
+    assert.deepEqual(sk.preserve.map((p) => p.id), (k.preserve ?? []).map((p) => p.id));
+    assert.deepEqual(sk.scope.map((s) => s.file), ["src/billing.js"]);
+    assert.deepEqual(sk.issue_coverage.map((c) => c.quote), k.requirements.map((r) => r.quote));
+    assert.ok(sk.issue_coverage.every((c) => inIssue(c.quote, ISSUE)), "seeded quotes pass the verbatim check");
+    assert.ok([...sk.requirements, ...sk.preserve, ...sk.issue_coverage].every((r) => r.status === ""), "no status is pre-judged");
+  });
+  it("incomplete: implemented without path:line, with evidence in a nonexistent file, or without validation", () => {
+    assert.equal(decide(row("R1", { evidence: "looks fine" }), ctx).state, "review.incomplete");
+    assert.equal(decide(row("R1", { evidence: "src/nope.js:3" }), ctx).state, "review.incomplete");
+    assert.equal(decide(row("R1", { evidence: "src/billing.js:1" }), ctx).state, "conforms", "an existing unchanged file is valid evidence");
+    assert.equal(decide(row("R1", { validated_by: "none" }), ctx).state, "review.incomplete");
+  });
+  it("incomplete: a coverage quote paraphrased instead of verbatim", () => {
+    assert.equal(decide({ ...good, issue_coverage: [{ quote: "scrape should release money on rate limits", status: "covered" }] }, ctx).state, "review.incomplete");
+  });
+  it("omission: an issue requirement missing from or narrowed by the contract", () => {
+    const d = decide({ ...good, issue_coverage: [...good.issue_coverage.slice(0, 2), { quote: "Billing pricing is unchanged.", status: "missing" }] }, ctx);
+    assert.deepEqual(codes(d), ["conformance.omission"]);
+  });
+  it("contract mismatch: a deliver requirement partial or missing in the diff", () => {
+    assert.deepEqual(codes(decide(row("R2", { status: "missing", evidence: "src/search.js:5" }), ctx)), ["conformance.unimplemented"]);
+    assert.deepEqual(codes(decide(row("R2", { status: "deferred" }), ctx)), ["conformance.untracked_deferral"]);
+  });
+  it("scope creep, preserve violated or unverified, and regressions fail", () => {
+    assert.deepEqual(codes(decide({ ...good, scope: [{ ...good.scope[0], authorized_by: "none", note: "rewrites pricing inside scrape.js" }, ...good.scope.slice(1)] }, ctx)), ["conformance.scope_creep"]);
+    assert.equal(decide({ ...good, scope: [...good.scope.slice(0, 2), { file: "test/leak.test.js", authorized_by: "none" }] }, ctx).state, "conforms", "a reviewer 'none' on a test file is a misreading, not creep");
+    assert.deepEqual(codes(decide({ ...good, preserve: [{ id: "P1", status: "violated", evidence: "src/billing.js:1" }] }, ctx)), ["conformance.preserve_violated"]);
+    assert.deepEqual(codes(decide({ ...good, preserve: [{ id: "P1", status: "unverified" }] }, ctx)), ["conformance.preserve_violated"]);
+    assert.deepEqual(codes(decide({ ...good, regressions: [{ at: "src/x.js:3", failure: "caller passes null" }] }, ctx)), ["conformance.regression"]);
+  });
+  it("CONFORMS with a failing row is nonconforming and flagged inconsistent; NONCONFORMING with no failing row is re-asked (review.inconsistent)", () => {
+    const d = decide(row("R1", { status: "partial" }), ctx);
+    assert.equal(d.state, "nonconforming"); assert.equal(d.inconsistent, true);
+    const i = decide({ ...good, verdict: "NONCONFORMING" }, ctx);
+    assert.equal(i.state, "review.inconsistent"); assert.deepEqual(codes(i), ["review.inconsistent"]);
+  });
+  it("a deferred requirement needs the reviewer's deferral_ok; false is an unjustified deferral", () => {
+    const k = { ...C, requirements: [C.requirements[0], { ...C.requirements[1], disposition: "defer", why: "w" }] };
+    const c2 = { ...ctx, contract: k };
+    const rv = (extra) => ({ ...good, requirements: [good.requirements[0], { id: "R2", status: "deferred", ...extra }] });
+    assert.equal(decide(rv({}), c2).state, "review.incomplete");
+    assert.equal(decide(rv({ deferral_ok: true }), c2).state, "conforms");
+    assert.deepEqual(codes(decide(rv({ deferral_ok: false, note: "two lines in the same file" }), c2)), ["conformance.unjustified_deferral"]);
+  });
+  it("short quotes are accepted only as a whole issue line or list item", () => {
+    const t = "Do this:\n- [ ] add --dry-run\n2. keep -v";
+    assert.ok(inIssue("add --dry-run", t)); assert.ok(inIssue("keep -v", t)); assert.ok(!inIssue("dry-run", t)); assert.ok(!inIssue("do", t));
+  });
+  it("add-requirement quotes are checked against the issue; an oversized contract is invalid", () => {
+    assert.equal(applyAmendments(C, [{ kind: "add-requirement", requirement: { id: "R9", quote: "something nobody asked for at all", disposition: "defer" }, why: "w" }], ISSUE).problems.length, 1);
+    assert.equal(applyAmendments(C, [{ kind: "add-requirement", requirement: { id: "R9", quote: "Billing pricing is unchanged." }, why: "w" }], ISSUE).problems.length, 0);
+    assert.match(validateContract({ ...C, deliverables: [...C.deliverables, { id: "DX", path: "x".repeat(41000) }] }, ISSUE).problems.join(), /over 40000 characters/);
+  });
+  it("checkCompleteness lists every problem", () => assert.ok(checkCompleteness({}, ctx).problems.length >= 5));
+});
+
+describe("close plan and follow-up items", () => {
+  it("links every tracking issue once; nothing tracked when everything is delivered", () => {
+    assert.deepEqual(closePlan(C), { reason: "completed", tracked: [] });
+    const k = { requirements: [{ id: "R1", disposition: "deliver" }, { id: "R2", disposition: "defer", tracked: "#9" }, { id: "R3", disposition: "post-deploy", tracked: "#9" }] };
+    assert.deepEqual(closePlan(k).tracked, ["#9"]);
+  });
+  it("follow-up keys are single-line, tab-free and stable", () => {
+    const [i] = followupItems([{ id: "R2", quote: "a\tb\n`c`", disposition: "defer", why: "x\ny" }]);
+    assert.equal(i.key, "R2: a b c"); assert.equal(i.why, "defer: x y"); assert.doesNotMatch(i.key + i.why, /[\t\n`]/);
+  });
+});

package/bin/lean/effects.mjs

@@ -3,7 +3,7 @@
 /** Core work-on: the real effects behind runCore's injected `io`. Argv only, no shell. */
 import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
-import { readFileSync, appendFileSync, mkdirSync, statSync, existsSync, rmSync, writeFileSync, readdirSync, lstatSync } from "node:fs";
+import { readFileSync, appendFileSync, mkdirSync, statSync, existsSync, rmSync, writeFileSync, readdirSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
 import { homedir, hostname, freemem, loadavg, cpus, tmpdir } from "node:os";
 import { promises as fsp } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
@@ -11,9 +11,21 @@ import { fileURLToPath } from "node:url";
 import { runCliBackendAsync, resolveClaudeCliBinary, getClaudeCliCapabilities, buildLeanSessionFlags, buildReadOnlyToolFlags } from "../runner.mjs";
 import { makeIo } from "../engine-cli.mjs";
 import { makeProjector } from "../engine/projector.mjs";
+import { makeLedger } from "./ledger.mjs";
 
 const pexec = promisify(execFile);
 const script = (n) => fileURLToPath(new URL(`../../scripts/${n}`, import.meta.url));
+/** Argv-only child with stdin input; resolves stdout, rejects on a non-zero exit with stderr attached. */
+export function runWithInput(bin, args, input, timeout = 120000) {
+  return new Promise((res, rej) => {
+    const child = execFile(bin, args, { timeout, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) { err.stdout = stdout; err.stderr = stderr; rej(err); } else res(String(stdout));
+    });
+    // A child that exits before reading stdin closes the pipe: EPIPE must reject via the exit callback, never crash the lane.
+    child.stdin.on("error", () => {});
+    child.stdin.end(input);
+  });
+}
 
 /** Claude CLI session runner: fresh session, or `--resume <id>` for the builder. Resolves usage + session_id. */
 let systemdProbe = null;
@@ -34,18 +46,40 @@ export function wrapLaneLimits(bin, args, limits) {
 }
 
 export function makeLeanRunner({ runCli = runCliBackendAsync, probe = systemdRunAvailable } = {}) {
-  return async ({ role, issue, cwd, model, resume, system, prompt, readOnly = false, env = null, idleMs = 0, maxMs = 0, laneLimits = null, control = null }) => {
+  return async ({ role, issue, cwd, model, resume, system, prompt, readOnly = false, env = null, idleMs = 0, maxMs = 0, laneLimits = null, control = null, onSpawn = null }) => {
     const bin = resolveClaudeCliBinary(cwd) || "claude";
     const caps = getClaudeCliCapabilities(cwd);
     const flags = [...buildLeanSessionFlags(caps), ...(readOnly ? buildReadOnlyToolFlags(caps) : [])];
     const r = await runCli({ spec: { name: `core-${role}` }, userMessage: prompt, systemPrompt: resume ? "" : system,
       args: [String(issue)], cwd, bin, model, env, sessionFlags: flags, extraArgs: resume ? ["--resume", resume] : [],
       logger: { log() {} },
-      idleMs, maxMs, stream: idleMs > 0, control, wrap: laneLimits && probe() ? (b, a) => wrapLaneLimits(b, a, laneLimits) : null });
+      idleMs, maxMs, stream: idleMs > 0, control, onSpawn, wrap: laneLimits && probe() ? (b, a) => wrapLaneLimits(b, a, laneLimits) : null });
     return { text: r.text, sessionId: r.sessionId, usage: r.usage, costUsd: r.costUsd, durationMs: r.durationMs, turns: r.turns, model: r.cliModel ?? "default" };
   };
 }
 
+/** Parent pid from /proc/<pid>/stat (the field after the parenthesised command name); 0 when unreadable. */
+const ppidOf = (root, pid) => { try { const st = readFileSync(join(root, String(pid), "stat"), "utf8"); return Number(st.slice(st.lastIndexOf(")") + 2).split(" ")[1]) || 0; } catch { return 0; } };
+/**
+ * #4162: processes whose cwd is `dir` or inside it, from /proc (Linux). Excludes this process and its ancestors.
+ * Returns [{pid, cmd}]; [] where /proc is unavailable (the caller then skips stopping them).
+ */
+export function procsInDir(dir, { procRoot = "/proc", self = process.pid } = {}) {
+  if (!dir || !existsSync(procRoot)) return [];
+  try { dir = realpathSync(dir); } catch { /* not on disk: compare as given */ } // /proc cwd links are resolved paths
+  const skip = new Set();
+  for (let p = self, i = 0; p > 1 && i < 64 && !skip.has(p); i++) { skip.add(p); p = ppidOf(procRoot, p); }
+  const out = [];
+  for (const e of readdirSync(procRoot)) {
+    if (!/^\d+$/.test(e) || skip.has(Number(e))) continue;
+    let at; try { at = readlinkSync(join(procRoot, e, "cwd")); } catch { continue; }
+    if (at !== dir && !at.startsWith(`${dir}/`)) continue;
+    let cmd = ""; try { cmd = readFileSync(join(procRoot, e, "cmdline"), "utf8").split("\0").filter(Boolean).join(" ").slice(0, 200); } catch { /* exited */ }
+    out.push({ pid: Number(e), cmd });
+  }
+  return out;
+}
+
 export const RUN_TMP_MAX_AGE_MS = 6 * 3600 * 1000;
 export const runTmpRoot = () => join(homedir(), ".forge", "tmp", "runs");
 const OWNER = ".forge-run-owner";
@@ -55,6 +89,8 @@ const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e)
 export function makeRunTmp({ root = runTmpRoot(), now = () => Date.now(), alive = pidAlive, host = hostname() } = {}) {
   const inside = (d) => { const r = resolve(d); return r.startsWith(resolve(root) + sep) && !r.slice(resolve(root).length + 1).includes(sep); };
   return {
+    /** The dir make(issue, runId) creates, so a ledger can register it first (#4179). */
+    path: (runId) => join(root, String(runId)),
     async make(issue, runId) {
       const dir = join(root, String(runId));
       mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -89,6 +125,22 @@ export function makeRunTmp({ root = runTmpRoot(), now = () => Date.now(), alive
   };
 }
 
+/**
+ * SIGTERM to a ledger-registered pid's process group (#4179). Only when the pid is alive and, where /proc exists, its
+ * command line still names `marker`, so a reused pid is never signalled. Returns true when the pid is gone or signalled.
+ */
+export function killLedgerPid(pid, marker, { kill = process.kill.bind(process), procDir = "/proc" } = {}) {
+  const n = Number(pid);
+  if (!Number.isSafeInteger(n) || n <= 1) return false;
+  if (!pidAlive(n)) return true;
+  if (marker && existsSync(procDir)) {
+    let cmd = "";
+    try { cmd = readFileSync(join(procDir, String(n), "cmdline"), "utf8"); } catch { return true; } // exited meanwhile
+    if (!cmd.includes(String(marker))) return true; // pid reused by something else: not ours any more
+  }
+  try { kill(-n, "SIGTERM"); return true; } catch { try { kill(n, "SIGTERM"); return true; } catch (e) { return e?.code === "ESRCH"; } }
+}
+
 /** Real host probes for admission (#4105). MemAvailable from /proc/meminfo (fallback os.freemem), statfs for tmp. */
 export function makeHostProbe() {
   return {
@@ -111,18 +163,34 @@ export function makeHostProbe() {
   };
 }
 
+/**
+ * Required status checks for `lane` (#4158): the union of classic branch protection (contexts + checks) and the
+ * repository rulesets that apply to the branch (`rules/branches/{lane}`, type required_status_checks). Each source
+ * fails independently to [] (404, no protection, no rulesets, bad JSON), so one never hides the other.
+ */
+export async function requiredChecksFor({ gh, repo, lane }) {
+  const classic = async () => {
+    const j = JSON.parse(String(await gh(["api", `repos/${repo}/branches/${lane}/protection/required_status_checks`])));
+    return [...(j.contexts ?? []), ...(j.checks ?? []).map((c) => c?.context)];
+  };
+  const rulesets = async () => {
+    // --jq emits one context per line across all pages, so pagination needs no JSON stitching.
+    const out = String(await gh(["api", "--paginate", `repos/${repo}/rules/branches/${lane}`,
+      "--jq", '.[] | select(.type == "required_status_checks") | .parameters.required_status_checks[]?.context']));
+    return out.split("\n").map((x) => x.trim());
+  };
+  const safe = async (f) => { try { const v = await f(); return Array.isArray(v) ? v : []; } catch { return []; } };
+  const all = [...(await safe(classic)), ...(await safe(rulesets))];
+  return [...new Set(all.filter((x) => typeof x === "string" && x))];
+}
+
 export function makeLeanIo({ repo }) {
   const base = makeIo();
   const run = (bin) => async (args, opts = {}) => (await pexec(bin, args, { cwd: opts.cwd, maxBuffer: 100 * 1024 * 1024, timeout: 120000 })).stdout;
   return {
-    gh: run("gh"), git: run("git"), runTmp: makeRunTmp(), host: makeHostProbe(), projector: makeProjector({ gh: base.gh }), runner: makeLeanRunner(), waitCiGreen: base.waitCiGreen,
-    /** Names of the checks the base branch requires (contexts + checks). [] on 404 / no protection. */
-    async requiredChecks(lane) {
-      try {
-        const j = JSON.parse(await run("gh")(["api", `repos/${repo}/branches/${lane}/protection/required_status_checks`]));
-        return [...new Set([...(j.contexts ?? []), ...(j.checks ?? []).map((c) => c.context)].filter(Boolean))];
-      } catch { return []; }
-    },
+    gh: run("gh"), git: run("git"), docker: run("docker"), killGroup: async (pid, marker) => killLedgerPid(pid, marker), ledger: (opts) => makeLedger(opts), runTmp: makeRunTmp(), host: makeHostProbe(), projector: makeProjector({ gh: base.gh }), runner: makeLeanRunner(), waitCiGreen: base.waitCiGreen,
+    /** Names of the checks the base branch requires: classic protection plus rulesets (#4158). [] when neither has any. */
+    async requiredChecks(lane) { return requiredChecksFor({ gh: run("gh"), repo, lane }); },
     /** [{name, state: success|failure|pending}] for the PR's checks. */
     async checkStates(pr) {
       const j = JSON.parse(await run("gh")(["pr", "view", String(pr), "-R", repo, "--json", "statusCheckRollup"]));
@@ -132,13 +200,53 @@ export function makeLeanIo({ repo }) {
         return { name: c.name ?? c.context, state };
       });
     },
+    /** #4167 verify-by-CI: `gh workflow run` on the lane branch; inputs become -f key=value. */
+    async dispatchWorkflow({ workflow, ref, inputs = {} }) {
+      await run("gh")(["workflow", "run", String(workflow), "-R", repo, "--ref", String(ref), ...Object.entries(inputs).flatMap(([k, v]) => ["-f", `${k}=${v}`])]);
+    },
+    /** Recent workflow_dispatch runs of `workflow` on `branch`, newest first: [{databaseId, headSha, status, conclusion, url, name}]. */
+    async workflowRuns({ workflow, branch }) {
+      return JSON.parse(await run("gh")(["run", "list", "-R", repo, "--workflow", String(workflow), "--branch", String(branch), "--event", "workflow_dispatch",
+        "--limit", "10", "--json", "databaseId,headSha,status,conclusion,url,name"]) || "[]");
+    },
+    /** Check runs on a commit (push-triggered CI): [{name, state: success|failure|pending, url}], same mapping as checkStates. */
+    async commitChecks(sha) {
+      const out = String(await run("gh")(["api", "--paginate", `repos/${repo}/commits/${sha}/check-runs`, "--jq", ".check_runs[] | {name, status, conclusion, url: .html_url} | @json"]));
+      return out.split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l)).map((c) => {
+        const v = String(c.status === "completed" ? c.conclusion ?? "" : "").toUpperCase();
+        const state = ["SUCCESS", "NEUTRAL", "SKIPPED"].includes(v) ? "success" : ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE", "STALE"].includes(v) ? "failure" : "pending";
+        return { name: c.name, state, url: c.url ?? null };
+      });
+    },
+    /** Failed-job logs of an Actions run (`gh run view --log-failed`), tail-capped; "" when unreadable. */
+    async failedLogs(runId) {
+      try { const out = String(await run("gh")(["run", "view", String(runId), "-R", repo, "--log-failed"])); return out.length > 64000 ? out.slice(-64000) : out; } catch { return ""; }
+    },
     async transitionLabel(issue, state) { await pexec("bash", [script("transition-label.sh"), String(issue), "-R", repo, state], { timeout: 60000 }); },
+    /**
+     * File (or append to) the parent's ONE batched follow-up issue (scripts/file-deferred-followups.sh: trusted lookup,
+     * append, create, claim marker, duplicate re-check). items: [{key, why}]. Returns {key: issueNumber}; throws on exit 3/4.
+     */
+    async fileFollowups({ parent, items }) {
+      const tsv = items.map((i) => `${i.key}\t${i.why}\t`).join("\n") + "\n";
+      const out = await runWithInput("bash", [script("file-deferred-followups.sh"), "--parent", String(parent), "--repo", repo], tsv, 180000);
+      const map = {};
+      for (const l of out.split("\n")) { const [k, n] = l.split("\t"); if (k && /^\d+$/.test(String(n ?? "").trim())) map[k] = Number(n); }
+      return map;
+    },
+    /** forge#4159: scripts/structure-delta.sh over base...HEAD in cwd; null on any failure (never fails a run). */
+    async structureDelta({ cwd, base }) {
+      try { return JSON.parse((await pexec("bash", [script("structure-delta.sh"), `${base}...HEAD`], { cwd, timeout: 30000, maxBuffer: 16 * 1024 * 1024 })).stdout); } catch { return null; }
+    },
+    /** #4162: processes left running inside a lane worktree (Linux /proc). */
+    proc: { inDir: async (dir) => procsInDir(dir), alive: pidAlive, kill: (pid, sig) => { try { process.kill(pid, sig); } catch { /* already gone */ } } },
     fs: {
       read: async (p) => readFileSync(p, "utf8"),
       exists: async (p) => existsSync(p),
       rmdir: async (p) => rmSync(p, { recursive: true, force: true }),
       stat: async (p) => { try { return { mtimeMs: statSync(p).mtimeMs }; } catch { return null; } },
       append: async (p, t) => { mkdirSync(dirname(p), { recursive: true }); appendFileSync(p, t); },
+      write: async (p, t) => { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, t); },
     },
   };
 }