forgedock 1.26.0 → 1.27.0

package/bin/lean/conformance.mjs

@@ -59,6 +59,33 @@ export function authorizationOf(contract, f) {
 }
 const blank = (s) => !String(s ?? "").trim() || /^none$/i.test(String(s).trim());
 
+/**
+ * #4160: an evidence path the reviewer gave as a bare or partial name (`route.ts`, `pdf/route.ts`) resolves to the one
+ * changed file it names. Returns the repo path, or null when it is not a unique match.
+ */
+export function resolveEvidencePath(p, changedFiles = []) {
+  const s = String(p ?? "").replace(/^\.\//, "");
+  if (!s) return null;
+  const hits = changedFiles.filter((f) => f === s || f.endsWith(`/${s}`));
+  return hits.length === 1 ? hits[0] : null;
+}
+
+/**
+ * #4160: the rows the engine requires, pre-filled with every id so the reviewer fills statuses instead of composing rows.
+ * Scope rows are listed only for changed files the contract does not already authorize (deliverable, test or
+ * incidental); issue_coverage starts from the contract's verbatim quotes, and the reviewer adds any the contract missed.
+ */
+export function reviewSkeleton({ contract, changedFiles = [], ignore = [] }) {
+  const reqs = contract?.requirements ?? [];
+  return {
+    issue_coverage: reqs.map((r) => ({ quote: r.quote, contract_ids: [r.id], status: "" })),
+    requirements: reqs.map((r) => ({ id: r.id, status: "", evidence: "", validated_by: "", ...(TRACKED.includes(r.disposition) ? { deferral_ok: null } : {}), note: "" })),
+    scope: changedFiles.filter((f) => !ignore.some((pre) => f.startsWith(pre)) && !authorizationOf(contract, f)).map((f) => ({ file: f, authorized_by: "", note: "" })),
+    preserve: (contract?.preserve ?? []).map((x) => ({ id: x.id, status: "", evidence: "" })),
+    regressions: [], verdict: "", summary: "",
+  };
+}
+
 /** Shape check of the builder's contract.json against the issue text. Returns {ok, problems[]}. */
 export function validateContract(c, issueText) {
   const problems = [];
@@ -97,7 +124,11 @@ export function applyAmendments(frozen, amendments, issueText = null) {
     const tag = JSON.stringify(a ?? null).slice(0, 100);
     if (blank(a?.why)) { problems.push(`amendment without why: ${tag}`); continue; }
     if (a.kind === "add-deliverable" && !blank(a.path)) {
-      if (!c.deliverables.some((d) => d.path === a.path)) c.deliverables.push({ id: a.id ?? `A${c.deliverables.length + 1}`, path: a.path, change: a.why, amended: true });
+      const have = c.deliverables.find((d) => d.path === a.path);
+      // An existing deliverable keeps its id and gains the why, so an amendment naming a package on an already-listed
+      // package.json declares the edge (forge#4159); before, it was reported as applied but changed nothing.
+      if (have) { have.change = have.change ? `${have.change}; ${a.why}` : a.why; have.amended = true; }
+      else c.deliverables.push({ id: a.id ?? `A${c.deliverables.length + 1}`, path: a.path, change: a.why, amended: true });
     } else if (a.kind === "add-requirement" && a.requirement?.id && !blank(a.requirement?.quote)) {
       if (c.requirements.some((r) => r.id === a.requirement.id)) { problems.push(`add-requirement reuses id ${a.requirement.id}`); continue; }
       if (issueText != null && !inIssue(a.requirement.quote, issueText)) { problems.push(`add-requirement ${a.requirement.id}: quote is not verbatim from the issue`); continue; }
@@ -118,25 +149,31 @@ export function applyAmendments(frozen, amendments, issueText = null) {
 
 /**
  * Deterministic checks before any reviewer tokens are spent: unauthorized files, failed or missing validation,
- * requirements not implemented, and deferrals without a tracking issue. Returns {ok, failures[]}.
+ * requirements not implemented, and deferrals without a tracking issue. Returns {ok, failures[]}; each failure carries a
+ * `kind` (scope_creep, validate_missing, validate_failed, requirement_unimplemented, untracked_deferral) so callers can
+ * tell the builder's own failed checks apart from bookkeeping gaps. `ciVerified` (#4167): the current head passed the
+ * engine's CI verification, so a validate id left to CI is not missing; a recorded non-zero exit still fails.
  */
-export function precheck({ contract, result, changedFiles, ignore = [] }) {
+export function precheck({ contract, result, changedFiles, ignore = [], ciVerified = false }) {
   const failures = [];
   const creep = changedFiles.filter((f) => !ignore.some((p) => f.startsWith(p)) && !authorizationOf(contract, f));
-  if (creep.length) failures.push({ code: C.CONFORMANCE_SCOPE_CREEP, detail: `changed outside the contract's deliverables: ${creep.join(", ")}` });
+  if (creep.length) failures.push({ code: C.CONFORMANCE_SCOPE_CREEP, kind: "scope_creep", detail: `changed outside the contract's deliverables: ${creep.join(", ")}` });
   const runs = Array.isArray(result?.validation) ? result.validation : [];
   for (const v of contract.validate ?? []) {
     const r = runs.find((x) => x?.id === v.id);
-    if (!r) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `validate ${v.id} (\`${v.command}\`) has no recorded result` });
-    else if (r.exit !== 0) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `validate ${v.id} failed (exit ${r.exit})` });
+    // #4167: a head the engine verified on CI covers validate ids the builder left to CI (no result, or ci:true without an exit)
+    const leftToCi = !r || (r.ci === true && r.exit === undefined);
+    if (ciVerified && leftToCi) continue;
+    if (leftToCi) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, kind: "validate_missing", detail: `validate ${v.id} (\`${v.command}\`) has no recorded result` });
+    else if (r.exit !== 0) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, kind: "validate_failed", detail: `validate ${v.id} failed (exit ${r.exit})` });
   }
   const st = Array.isArray(result?.requirements) ? result.requirements : [];
   for (const r of contract.requirements ?? []) {
     const s = st.find((x) => x?.id === r.id)?.status;
     if (TRACKED.includes(r.disposition)) continue; // typed deferrals are judged by the reviewer, then filed before the PR
     if (r.disposition === "deliver") {
-      if (s === "deferred" || s === "post-deploy") failures.push({ code: C.CONFORMANCE_UNTRACKED_DEFERRAL, detail: `${r.id} was contracted as deliver but reported "${s}" without a typed amendment` });
-      else if (s !== "implemented") failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `${r.id} reported "${s ?? "no status"}"` });
+      if (s === "deferred" || s === "post-deploy") failures.push({ code: C.CONFORMANCE_UNTRACKED_DEFERRAL, kind: "untracked_deferral", detail: `${r.id} was contracted as deliver but reported "${s}" without a typed amendment` });
+      else if (s !== "implemented") failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, kind: "requirement_unimplemented", detail: `${r.id} reported "${s ?? "no status"}"` });
     }
   }
   return { ok: failures.length === 0, failures };
@@ -175,13 +212,15 @@ export function checkCompleteness(rv, { contract, changedFiles, issueText, pathE
     if (row.status === "implemented") {
       const m = EVIDENCE_RE.exec(String(row.evidence ?? ""));
       if (!m) p.push(`${r.id}: implemented needs path:line evidence`);
-      else if (!changedFiles.includes(m[1]) && !pathExists(m[1])) p.push(`${r.id}: evidence path ${m[1]} does not exist`);
+      else if (!changedFiles.includes(m[1]) && !pathExists(m[1]) && !resolveEvidencePath(m[1], changedFiles)) p.push(`${r.id}: evidence path ${m[1]} does not exist`);
       if (blank(row.validated_by)) p.push(`${r.id}: implemented needs validated_by (a validate id or test)`);
     }
   }
   const scope = arr("scope");
   if (!scope) p.push("scope rows are missing");
-  for (const f of changedFiles.filter((x) => !ignore.some((pre) => x.startsWith(pre)))) if (!(scope ?? []).some((s) => s?.file === f)) p.push(`changed file ${f} has no scope row`);
+  // #4160: a file the contract authorizes (deliverable, test, incidental) is already settled by the deterministic precheck;
+  // a row is required only for the files it could not authorize. A row the reviewer does give is still judged in decide().
+  for (const f of changedFiles.filter((x) => !ignore.some((pre) => x.startsWith(pre)) && !authorizationOf(contract, x))) if (!(scope ?? []).some((s) => s?.file === f)) p.push(`changed file ${f} has no scope row`);
   const pres = arr("preserve") ?? [];
   for (const c of contract.preserve ?? []) {
     const row = pres.find((x) => x?.id === c.id);
@@ -236,3 +275,30 @@ export function followupItems(reqs) {
   const flat = (s) => String(s ?? "").replace(/[\t\r\n`]+/g, " ").replace(/\s+/g, " ").trim();
   return reqs.map((r) => ({ id: r.id, key: flat(`${r.id}: ${r.quote}`).slice(0, 240), why: flat(`${r.disposition}: ${r.why ?? ""}`).slice(0, 400) }));
 }
+
+/**
+ * forge#4159: package.json edges between workspace packages (scripts/structure-delta.sh `package_edges_added`) that
+ * the contract does not name. Named = a deliverable covering the edge's manifest whose `change` names the target
+ * package (an add-deliverable amendment counts: its change is the why). A null or `{}` delta names nothing to check.
+ */
+export function unnamedEdges(contract, delta) {
+  const edges = Array.isArray(delta?.package_edges_added) ? delta.package_edges_added : [];
+  const dels = contract?.deliverables ?? [];
+  return edges.filter((e) => e?.manifest && e?.to && !dels.some((d) => pathCovers(d.path, e.manifest) && String(d.change ?? "").includes(e.to)));
+}
+
+/**
+ * forge#4159: the one report-only line for the existing reviewer prompt, or "" when there is no import-pair growth
+ * and no boundary-config loosening. Never blocks; adds no reviewer run.
+ */
+export function structureNote(delta) {
+  const grow = (Array.isArray(delta?.import_pairs) ? delta.import_pairs : []).filter((p) => p?.files_added > 0);
+  const b = delta?.boundary_config_changed;
+  const loosened = Boolean(b?.loosens);
+  if (!grow.length && !loosened) return "";
+  const pairs = grow.map((p) => `${p.files_added} value import${p.files_added === 1 ? "" : "s"} ${p.from}→${p.to}`).join(", ");
+  const files = (Array.isArray(b?.files) ? b.files : []).join(", ");
+  const config = loosened ? `the repo's boundary config was loosened in this PR (${files})` : "the repo's boundary config allows it";
+  const s = grow.length ? `this PR adds ${pairs} (files); ${config}` : `this PR loosens the repo's boundary config (${files})`;
+  return `Structure (report only): ${s}; flag only if the contract or the architecture doc says otherwise.`.replace(/[\r\n]+/g, " ");
+}

package/bin/lean/conformance.test.mjs

@@ -2,7 +2,7 @@
 // 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 } from "./conformance.mjs";
+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.";
@@ -95,11 +95,40 @@ describe("conformance review: the engine computes the verdict from complete rows
     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 a changed file, missing preserve row", () => {
+  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");
-    assert.equal(decide({ ...good, scope: good.scope.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");

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,6 +11,7 @@ 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));
@@ -45,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";
@@ -66,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 });
@@ -100,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 {
@@ -122,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"]));
@@ -143,6 +200,28 @@ 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,
@@ -155,6 +234,12 @@ export function makeLeanIo({ repo }) {
       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),