forgedock 1.26.0 → 1.28.0

package/bin/lean/effects.mjs

@@ -1,9 +1,9 @@
 // SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /** Core work-on: the real effects behind runCore's injected `io`. Argv only, no shell. */
-import { execFile, execFileSync } from "node:child_process";
+import { execFile, execFileSync, spawn } 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,9 @@ 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, countLiveLanes, ledgerRoot } from "./ledger.mjs";
+import { makeDepCache } from "./depcache.mjs";
+import { makeHeavyIo } from "./heavy.mjs";
 
 const pexec = promisify(execFile);
 const script = (n) => fileURLToPath(new URL(`../../scripts/${n}`, import.meta.url));
@@ -44,19 +47,45 @@ export function wrapLaneLimits(bin, args, limits) {
   return { bin: "systemd-run", args: ["--user", "--scope", "-q", ...(mem ? ["-p", `MemoryMax=${mem}`] : []), ...(cpu ? ["-p", `CPUQuota=${cpu}`] : []), "--", bin, ...args] };
 }
 
+/** #4211: a judgment call over data in the prompt only (the refactor:split grouping call): no tool can read a file. */
+export const noToolFlags = (caps) => (caps?.strictMcp ? ["--tools", ""]
+  : ["--disallowedTools", "Read", "Grep", "Glob", "Bash", "Edit", "Write", "MultiEdit", "NotebookEdit", "WebFetch", "WebSearch", "Task"]);
+
 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, noTools = 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 flags = [...buildLeanSessionFlags(caps), ...(noTools ? noToolFlags(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 +95,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 +131,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 {
@@ -118,31 +165,96 @@ export function makeHostProbe() {
     },
     loadAvg1: () => loadavg()[0],
     cores: () => cpus().length || 1,
+    /** Live lanes on this host from the ledger (#4182), this lane included once it registered. */
+    activeLanes: () => countLiveLanes({ root: ledgerRoot(), host: hostname() }),
     tmpPaths: () => [...new Set([join(homedir(), ".forge", "tmp"), tmpdir(), "/tmp"].filter((x) => existsSync(x) || x === join(homedir(), ".forge", "tmp")))],
   };
 }
 
+/**
+ * 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))];
+}
+
+/** Combined stdout+stderr kept per declared check command (tail). */
+const CHECK_OUTPUT_CAP = 64000;
+/** #4240: run a forge.yaml declared check command locally (no gh, no Actions); {rc, output}, rc 124 on timeout. */
+export function runCheckCommand({ command, cwd, timeoutMs = 300000 }) {
+  return new Promise((done) => {
+    let out = "", timedOut = false, child;
+    const add = (b) => { out += String(b); if (out.length > 2 * CHECK_OUTPUT_CAP) out = out.slice(-CHECK_OUTPUT_CAP); };
+    try { child = spawn("bash", ["-c", String(command)], { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] }); }
+    catch (e) { done({ rc: 127, output: String(e?.message ?? e) }); return; }
+    const kill = () => { try { process.kill(-child.pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch { /* gone */ } } };
+    const timer = setTimeout(() => { timedOut = true; kill(); }, timeoutMs);
+    child.stdout.on("data", add); child.stderr.on("data", add);
+    child.on("error", (e) => { clearTimeout(timer); done({ rc: 127, output: `${out}${String(e?.message ?? e)}`.slice(-CHECK_OUTPUT_CAP) }); });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const tail = out.slice(-CHECK_OUTPUT_CAP);
+      done(timedOut ? { rc: 124, output: `${tail}\n(timed out after ${Math.round(timeoutMs / 1000)}s)` } : { rc: Number.isInteger(code) ? code : 1, output: tail });
+    });
+  });
+}
+
 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 []; }
-    },
-    /** [{name, state: success|failure|pending}] for the PR's checks. */
+    gh: run("gh"), git: run("git"), docker: run("docker"), killGroup: async (pid, marker) => killLedgerPid(pid, marker), ledger: (opts) => makeLedger(opts), runTmp: makeRunTmp(), host: makeHostProbe(), heavy: makeHeavyIo({ host: makeHostProbe() }), projector: makeProjector({ gh: base.gh }), runner: makeLeanRunner(), waitCiGreen: base.waitCiGreen,
+    /** Shared dependency cache (#4220): the repo's own package manager, argv only, bounded by the cache's timeout. */
+    deps: makeDepCache({ exec: async (cmd, args, { cwd, env, timeoutMs } = {}) => String((await pexec(cmd, args, { cwd, env: { ...process.env, ...(env ?? {}) }, timeout: timeoutMs ?? 0, maxBuffer: 100 * 1024 * 1024 })).stdout) }),
+    /** 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, url, head}] for the PR's checks; `head` is the PR head the rollup belongs to (#4240). */
     async checkStates(pr) {
-      const j = JSON.parse(await run("gh")(["pr", "view", String(pr), "-R", repo, "--json", "statusCheckRollup"]));
+      const j = JSON.parse(await run("gh")(["pr", "view", String(pr), "-R", repo, "--json", "statusCheckRollup,headRefOid"]));
       return (j.statusCheckRollup ?? []).map((c) => {
         const v = String(c.conclusion || c.state || "").toUpperCase();
         const state = ["SUCCESS", "NEUTRAL", "SKIPPED"].includes(v) ? "success" : ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE"].includes(v) ? "failure" : "pending";
-        return { name: c.name ?? c.context, state };
+        return { name: c.name ?? c.context, state, url: c.detailsUrl || c.targetUrl || null, head: j.headRefOid ?? null };
       });
     },
+    /** #4240: one declared check command (`bash -c`) in `cwd`; never throws. A timeout kills the process group and gives rc 124. */
+    runCommand: runCheckCommand,
+    /** #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 +267,56 @@ 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#4163: forge.yaml env.setup, once per fresh lane worktree: `bash -c <command>` in cwd with the lane env.
+     * Resolves {exit, stdout, stderr} (output tails); a non-zero exit, timeout or spawn error never throws.
+     */
+    runSetup({ cwd, command, env = null, timeoutMs = 15 * 60000 }) {
+      return new Promise((res) => {
+        execFile("bash", ["-c", command], { cwd, env: { ...process.env, ...(env ?? {}) }, timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+          const tail = (x) => String(x ?? "").slice(-2000);
+          if (!err) return res({ exit: 0, stdout: tail(stdout), stderr: tail(stderr) });
+          const exit = Number.isInteger(err.code) ? err.code : 1;
+          const why = err.killed ? `timed out after ${Math.round(timeoutMs / 1000)}s` : typeof err.code === "string" ? err.code : "";
+          res({ exit: exit === 0 ? 1 : exit, stdout: tail(stdout), stderr: tail([stderr, why].filter(Boolean).join("\n")) });
+        });
+      });
+    },
+    /** 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; }
+    },
+    /** forge#4195: scripts/hotspots.sh facts for `paths` in cwd (growth since base when given); null on any failure. */
+    async hotspots({ cwd, base = null, paths = [] }) {
+      const args = [script("hotspots.sh"), ...(base ? ["--base", base] : []), "--", ...paths];
+      try { return JSON.parse((await pexec("bash", args, { cwd, timeout: 30000, maxBuffer: 16 * 1024 * 1024 })).stdout); } catch { return null; }
+    },
+    /** #4271: scripts/acceptance-red-green.sh for the frozen repro_test in cwd; {base, head} words, or null on any failure. */
+    async redGreen({ cwd, base, command, timeoutSec = 300 }) {
+      const args = [script("acceptance-red-green.sh"), "--repo-path", cwd, "--base-ref", base, "--test-cmd", command, "--timeout", String(timeoutSec)];
+      try {
+        const m = /BASE=(\w+) HEAD=(\w+)/.exec(String((await pexec("bash", args, { cwd, timeout: (timeoutSec * 2 + 60) * 1000, maxBuffer: 4 * 1024 * 1024 })).stdout ?? ""));
+        return m ? { base: m[1], head: m[2] } : null;
+      } catch { return null; }
+    },
+    /**
+     * The target repo's own docs-move-with-code rule, when it has one (scripts/check-devdocs-freshness.sh, forge#4185),
+     * over base...HEAD in cwd. null when the repo has no such script or it cannot run (exit 2+, timeout): never blocks.
+     * Otherwise {ok, output} with the script's stdout+stderr (exit 0 = ok, exit 1 = stale docs).
+     */
+    async docsFreshness({ cwd, base }) {
+      const s = join(cwd, "scripts", "check-devdocs-freshness.sh");
+      if (!existsSync(s)) return null;
+      try {
+        const r = await pexec("bash", [s, base], { cwd, timeout: 60000, maxBuffer: 4 * 1024 * 1024, env: { ...process.env, PR_BODY: "" } });
+        return { ok: true, output: String(r.stdout ?? "") };
+      } catch (e) {
+        if (e?.code !== 1) return null;
+        return { ok: false, output: `${e.stdout ?? ""}${e.stderr ?? ""}`.slice(0, 6000) };
+      }
+    },
+    /** #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),

package/bin/lean/execution.e2e.test.mjs

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Container sandbox end to end (#4253): a real `docker run` of a stub lane. Skipped unless docker answers and the image
+// (FORGEDOCK_E2E_IMAGE, default node:22.23.0-bookworm-slim) is already local; it never pulls.
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { containerProvider, providerLanes, runDocker } from "./execution.mjs";
+import { makeLedger } from "./ledger.mjs";
+import { openBatch } from "./batch.mjs";
+import { planGc, applyGc } from "../gc.mjs";
+
+const IMAGE = process.env.FORGEDOCK_E2E_IMAGE || "node:22.23.0-bookworm-slim";
+const has = (args) => { try { execFileSync("docker", args, { stdio: "ignore", timeout: 20000 }); return true; } catch { return false; } };
+const skip = !has(["version"]) ? "docker unavailable" : !has(["image", "inspect", IMAGE]) ? `image ${IMAGE} not local (never pulled)` : false;
+const LABELS = String(process.env.FORGE_DOCKER_LABELS ?? "").split(/\s+/).filter(Boolean);
+const exists = (name) => has(["inspect", name]);
+const names = new Set();
+after(() => { for (const n of names) try { execFileSync("docker", ["rm", "-f", n], { stdio: "ignore" }); } catch { /* gone */ } });
+
+describe("container provider e2e (#4253)", { skip }, () => {
+  const work = tmpDir("exec-e2e-");
+  const stubDir = join(work, "stub");
+  mkdirSync(stubDir);
+  // Stub lane: argv `<issue> --result-file <rf>`; issue 1 merges, 2 fails, 3 hangs (a lane whose dispatcher dies).
+  writeFileSync(join(stubDir, "lane.mjs"), `import { writeFileSync } from "node:fs";
+const a = process.argv.slice(2); const n = Number(a[0]); const rf = a[a.indexOf("--result-file") + 1];
+console.log("lane", n, "in", process.cwd(), "GH_REPO", process.env.GH_REPO, "leak", process.env.FD_E2E_LEAK ?? "none");
+if (n === 3) setInterval(() => {}, 1000);
+else writeFileSync(rf, JSON.stringify(n === 1 ? { terminalReason: "merged", pr: 41 } : { terminalReason: "needs-human", detail: "stub failure" }));
+`);
+  const batch = openBatch(join(work, "batches"), `e2e-${process.pid}`);
+  const gitDir = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" }).trim();
+  const provider = containerProvider({ batch, repo: "o/r", image: IMAGE, gitDir, cacheDir: join(work, "cache"), labels: LABELS, mounts: [`${stubDir}:/stub:ro`],
+    command: (issue, _args, rf) => ["node", "/stub/lane.mjs", String(issue), "--result-file", rf] });
+  const root = join(work, "ledger");
+  const ledgerFor = (n, pid = process.pid) => makeLedger({ root, batch: batch.id, lane: `sandbox-${n}`, owner: "e2e", issue: n, pid });
+  const lanes = providerLanes({ provider, laneArgs: () => [], ledgerFor: (n) => ledgerFor(n), pollMs: 200, env: { FD_E2E_LEAK: "x" }, secrets: [] });
+
+  it("success: the lane runs in the container, its result reaches the batch, the sandbox is gone", async () => {
+    names.add(provider.idFor(1));
+    const r = await lanes.runOne(1, null);
+    const { sandbox, ...rest } = r; // #4255: every sandbox result carries its usage
+    assert.deepEqual(rest, { terminalReason: "merged", pr: 41 });
+    assert.equal(sandbox.provider, "container");
+    assert.equal(sandbox.id, provider.idFor(1));
+    assert.equal(exists(provider.idFor(1)), false);
+    assert.equal(ledgerFor(1).read(), null);
+  });
+
+  it("failure: the failure result reaches the batch and the sandbox is torn down", async () => {
+    names.add(provider.idFor(2));
+    const r = await lanes.runOne(2, null);
+    assert.equal(r.terminalReason, "needs-human");
+    assert.equal(exists(provider.idFor(2)), false);
+    assert.equal(ledgerFor(2).read(), null);
+  });
+
+  it("runner kill: a sandbox whose dispatcher died stays in the ledger and gc --apply removes it", async () => {
+    const id = provider.idFor(3);
+    names.add(id);
+    const dead = ledgerFor(3, 2 ** 22 + 12345); // a pid that is not running
+    dead.register("sandbox", id, { provider: "container", handle: { provider: "container", id, issue: 3 } });
+    await provider.start({ issue: 3, args: [], env: {}, secrets: [] });
+    assert.equal(await provider.status({ id }), "running");
+    const home = join(work, "home");
+    mkdirSync(join(home, "tmp"), { recursive: true });
+    const probes = { cwd: work, host: dead.read().host, ledgerRoot: root, forgeTmpRoot: join(home, "tmp"), worktreeRoot: join(work, "wt"),
+      alive: (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } }, ppid: () => 0, procsInDir: () => [],
+      docker: (args) => runDocker(args), git: async () => "", gh: async () => "[]" };
+    const plan = await planGc({ probes, scopes: new Set(["sandboxes"]) });
+    assert.deepEqual(plan.items.map((i) => [i.type, i.id, i.action]), [["sandbox", id, "reclaim"]]);
+    const res = await applyGc(plan, probes);
+    assert.deepEqual(res.failed, []);
+    assert.equal(exists(id), false);
+    assert.equal(existsSync(dead.path), false);
+  });
+});