forgedock 1.26.0 → 1.28.0

package/bin/lean/review-trigger.test.mjs

@@ -0,0 +1,104 @@
+// 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 { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { computeTrigger, parseRiskPaths, riskClassOf, triggerReport, readRunLogs, formatReport } from "./review-trigger.mjs";
+
+const HOT = { enabled: true, file_lines: 2000, growth_lines: 150, files: [] };
+const clean = (patch = {}) => computeTrigger({ files: ["src/foo.js", "test/foo.test.js"], hotspots: HOT, ...patch });
+const codes = (t) => t.reasons.map((r) => r.code);
+
+describe("computeTrigger (#4273)", () => {
+  it("a clean diff with passing gates would skip, with no reasons", () => {
+    assert.deepEqual(clean(), { would_skip: true, reasons: [] });
+  });
+  it("risk_path: a built-in risk word in any path segment, camelCase included", () => {
+    for (const f of ["src/auth/login.ts", "api/payments/charge.py", "lib/security/x.go", "app/userDelete.js", "db/migrations/001_init.sql", "src/AuthService.ts"]) {
+      const t = clean({ files: [f] });
+      assert.equal(t.would_skip, false, f);
+      assert.deepEqual(codes(t), ["risk_path"], f);
+    }
+    assert.equal(riskClassOf("src/billing/x.ts"), "payments");
+    assert.equal(riskClassOf("src/authorship.md"), null); // whole words only
+  });
+  it("risk_path: a configured review.risk_paths glob", () => {
+    const t = clean({ files: ["infra/main.tf"], riskPaths: ["infra/**"] });
+    assert.deepEqual(t.reasons, [{ code: "risk_path", detail: "infra/main.tf (review.risk_paths infra/**)" }]);
+    assert.equal(clean({ files: ["infra/main.tf"], riskPaths: ["other/**"] }).would_skip, true);
+  });
+  it("package_edge: any added package edge, declared or not", () => {
+    const t = clean({ structure: { package_edges_added: [{ from: "@a/web", to: "@a/db" }], import_pairs: [] } });
+    assert.deepEqual(t.reasons, [{ code: "package_edge", detail: "@a/web → @a/db" }]);
+    assert.equal(clean({ structure: { package_edges_added: [] } }).would_skip, true);
+  });
+  it("hotspot: a changed file over the threshold, unless excluded or not over", () => {
+    const files = [{ path: "src/foo.js", lines: 2400, over: true, excluded: false }];
+    assert.deepEqual(codes(clean({ hotspots: { ...HOT, files } })), ["hotspot"]);
+    assert.equal(clean({ hotspots: { ...HOT, files: [{ ...files[0], excluded: true }] } }).would_skip, true);
+    assert.equal(clean({ hotspots: { ...HOT, files: [{ ...files[0], over: false }] } }).would_skip, true);
+    assert.equal(clean({ hotspots: { enabled: false, files: [] } }).would_skip, true); // disabled is an answer
+  });
+  it("gate.failed: precheck failures, declared check commands still failing, CI fallback", () => {
+    assert.deepEqual(clean({ gates: { precheckFailures: [{ code: "conformance.scope" }] } }).reasons, [{ code: "gate.failed", detail: "precheck conformance.scope" }]);
+    assert.deepEqual(codes(clean({ gates: { checkCommandsFailing: true } })), ["gate.failed"]);
+    assert.deepEqual(codes(clean({ gates: { ciFellBack: true } })), ["gate.failed"]);
+  });
+  it("gate.ambiguous: hotspot facts unavailable, or a deferred/post-deploy requirement", () => {
+    assert.deepEqual(codes(computeTrigger({ files: ["src/foo.js"], hotspots: null })), ["gate.ambiguous"]);
+    assert.deepEqual(codes(computeTrigger({ files: ["src/foo.js"] })), ["gate.ambiguous"]);
+    const contract = { requirements: [{ id: "R1", disposition: "deliver" }, { id: "R2", disposition: "post-deploy" }] };
+    assert.deepEqual(clean({ contract }).reasons, [{ code: "gate.ambiguous", detail: "contract defers R2 (only the reviewer judges deferrals)" }]);
+    assert.equal(clean({ contract: { requirements: [{ id: "R1", disposition: "deliver" }] } }).would_skip, true);
+  });
+  it("is deterministic: same facts in any order give the same sorted reasons", () => {
+    const a = computeTrigger({ files: ["src/auth/a.ts", "db/migrations/1.sql"], hotspots: null, gates: { ciFellBack: true } });
+    const b = computeTrigger({ files: ["db/migrations/1.sql", "src/auth/a.ts"], hotspots: null, gates: { ciFellBack: true } });
+    assert.deepEqual(a, b);
+    assert.deepEqual(codes(a), ["gate.ambiguous", "gate.failed", "risk_path", "risk_path"]);
+  });
+  it("parseRiskPaths takes a comma string or a list", () => {
+    assert.deepEqual(parseRiskPaths(" a/** , ,*.sql"), ["a/**", "*.sql"]);
+    assert.deepEqual(parseRiskPaths(["x", " ", "y "]), ["x", "y"]);
+    assert.deepEqual(parseRiskPaths(undefined), []);
+  });
+});
+
+const start = (repo) => ({ event: "RUN_START", repo });
+const trig = (would_skip, skipped = false) => ({ event: "REVIEW_TRIGGER", mode: skipped ? "enforce" : "shadow", would_skip, reasons: would_skip ? [] : ["risk_path"], skipped });
+const conf = (state) => ({ event: "CONFORMANCE", round: 1, state });
+
+describe("triggerReport (#4273)", () => {
+  it("per repo: runs, would-skip, would-skip the reviewer flagged nonconforming, enforce skips", () => {
+    const logs = [
+      [start("o/a"), trig(true), conf("nonconforming"), conf("conforms")],
+      [start("o/a"), trig(true), conf("conforms")],
+      [start("o/a"), trig(false), conf("nonconforming")],
+      [start("o/b"), trig(true, true)],
+      // only the last RUN_START slice counts: the earlier flagged run is superseded
+      [start("o/b"), trig(true), conf("nonconforming"), start("o/b"), trig(true), conf("conforms")],
+      [start("o/b"), conf("conforms")], // trigger off: not counted
+      [trig(true)], // no RUN_START
+    ];
+    assert.deepEqual(triggerReport(logs), {
+      "o/a": { runs: 3, would_skip: 2, would_skip_flagged: 1, skipped: 0 },
+      "o/b": { runs: 2, would_skip: 2, would_skip_flagged: 0, skipped: 1 },
+    });
+  });
+  it("reads *.jsonl run logs, skipping corrupt lines; a missing dir is an empty report", () => {
+    const dir = tmpDir("rtrig-");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "7.jsonl"), [start("o/a"), trig(true), conf("nonconforming")].map((e) => JSON.stringify(e)).join("\n") + "\n{broken\n");
+    writeFileSync(join(dir, "notes.txt"), "ignored");
+    assert.deepEqual(triggerReport(readRunLogs(dir)), { "o/a": { runs: 1, would_skip: 1, would_skip_flagged: 1, skipped: 0 } });
+    assert.deepEqual(readRunLogs(join(dir, "missing")), []);
+    assert.match(formatReport(triggerReport(readRunLogs(dir))), /\| o\/a \| 1 \| 1 \| 1 \| 0 \|/);
+    const cli = spawnSync(process.execPath, [fileURLToPath(new URL("./review-trigger.mjs", import.meta.url)), "--dir", dir, "--json"], { encoding: "utf8" });
+    assert.equal(cli.status, 0);
+    assert.deepEqual(JSON.parse(cli.stdout)["o/a"].would_skip_flagged, 1);
+  });
+});

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

@@ -0,0 +1,257 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Sandbox provider contract (#4254): one suite every provider passes (container over a fake docker, remote over a fake
+// transport), plus the remote adapter, credentials, config and gc specifics.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { containerProvider, parseExecution, providerByName, providerLanes, remoteTransportFor } from "./execution.mjs";
+import { remoteProvider, httpTransport, isActionsEndpoint, redact } from "./sandbox-remote.mjs";
+import { resolveCredential } from "./credentials.mjs";
+import { makeLedger } from "./ledger.mjs";
+import { openBatch } from "./batch.mjs";
+import { orchestrate } from "./orchestrate.mjs";
+import { planGc, applyGc } from "../gc.mjs";
+
+const HOST = "testhost";
+const SECRET = "s3cret-value-123";
+const TOKEN = "tok-credential-456";
+
+/** Fake docker daemon for the container provider: `run` starts, `inspect` reports, `rm` removes. */
+function containerFixture(batch, { startError = null } = {}) {
+  const live = new Map(); // id -> state
+  const docker = async (args) => {
+    if (args[0] === "run") {
+      if (startError) throw Object.assign(new Error("x"), { stderr: startError });
+      live.set(args[args.indexOf("--name") + 1], "running"); return "cid\n";
+    }
+    if (args[0] === "inspect") { const id = args.at(-1); if (!live.has(id)) throw new Error("Error: No such object"); return `${live.get(id)}\n`; }
+    if (args[0] === "rm") { const id = args.at(-1); if (!live.delete(id)) throw Object.assign(new Error("x"), { stderr: `No such container: ${id}` }); return ""; }
+    return "";
+  };
+  return {
+    provider: containerProvider({ batch, repo: "o/r", image: "img:1", gitDir: "/g/.git", cacheDir: null, docker, user: null }),
+    finish: (h, result) => { mkdirSync(dirname(batch.resultFile(h.issue)), { recursive: true }); writeFileSync(batch.resultFile(h.issue), JSON.stringify(result)); live.set(h.id, "exited"); },
+    exists: (id) => live.has(id),
+  };
+}
+
+/** In-memory transport: the "remote" end of the protocol. */
+function fakeTransport({ launchError = null } = {}) {
+  const t = {
+    boxes: new Map(), specs: [], destroyed: [],
+    async launch(spec) { if (launchError) throw launchError; t.specs.push(spec); t.boxes.set(spec.id, { state: "running", log: "", result: null, minutes: 0 }); return { id: spec.id }; },
+    async status(id) { return t.boxes.get(id)?.state ?? "gone"; },
+    async logs(id, cursor = 0) { const b = t.boxes.get(id); if (!b) return { text: "", cursor }; return { text: b.log.slice(cursor), cursor: b.log.length }; },
+    async result(id) { return t.boxes.get(id)?.result ?? null; },
+    async usage(id) { const b = t.boxes.get(id); return b ? { minutes: b.minutes } : null; },
+    async destroy(id) { t.destroyed.push(id); t.boxes.delete(id); return true; },
+  };
+  return t;
+}
+function remoteFixture(batch, { launchError = null } = {}) {
+  const transport = fakeTransport({ launchError });
+  const provider = remoteProvider({ batch, repo: "o/r", settings: { image: "img:1", cacheStore: "s3://cache", tokenEnv: "FD_TOKEN", secrets: ["GH_TOKEN"] }, transport,
+    env: { GH_TOKEN: SECRET, FD_TOKEN: TOKEN }, credentials: (n) => ({ GH_TOKEN: SECRET, FD_TOKEN: TOKEN })[n] ?? null });
+  return {
+    provider, transport,
+    finish: (h, result) => { const b = transport.boxes.get(h.id); b.log += `lane done; token ${SECRET} and ${TOKEN}\n`; b.result = result; b.state = "exited"; b.minutes = 3.5; },
+    exists: (id) => transport.boxes.has(id),
+  };
+}
+
+const FIXTURES = { container: containerFixture, remote: remoteFixture };
+
+for (const [name, make] of Object.entries(FIXTURES)) {
+  describe(`sandbox provider contract: ${name} (#4254)`, () => {
+    const setup = (opts) => { const work = tmpDir(`contract-${name}-`); const batch = openBatch(join(work, "batches"), "bt"); return { work, batch, ...make(batch, opts) }; };
+
+    it("idFor is stable and equals the started handle id; start -> running; result -> fetched, exited", async () => {
+      const { provider, finish } = setup();
+      assert.equal(provider.idFor(7), provider.idFor(7));
+      const h = await provider.start({ issue: 7, args: ["--repo", "o/r", "--lane", "staging"], env: { GH_TOKEN: SECRET }, secrets: ["GH_TOKEN"] });
+      assert.equal(h.id, provider.idFor(7));
+      assert.equal(h.provider, provider.name);
+      assert.equal(h.issue, 7);
+      assert.equal(await provider.status(h), "running");
+      assert.equal(await provider.fetchResult(h), null);
+      finish(h, { terminalReason: "merged", pr: 1 });
+      assert.deepEqual(await provider.fetchResult(h), { terminalReason: "merged", pr: 1 });
+      assert.equal(await provider.status(h), "exited");
+    });
+
+    it("teardown is true and idempotent; a gone sandbox is torn down", async () => {
+      const { provider, exists } = setup();
+      const h = await provider.start({ issue: 8, args: [], env: {}, secrets: [] });
+      assert.equal(await provider.teardown(h), true);
+      assert.equal(exists(h.id), false);
+      assert.equal(await provider.teardown(h), true);
+      assert.equal(await provider.status(h), "gone");
+    });
+
+    it("providerLanes: ledger before start, released after teardown; secrets never in handle, ledger, state or log", async () => {
+      const { work, provider, finish, batch } = setup();
+      const root = join(work, "ledger");
+      const ledgerFor = (n) => makeLedger({ root, batch: "bt", lane: `sandbox-${n}`, owner: "o", issue: n, host: HOST, pid: process.pid });
+      let atStart = null;
+      const wrapped = { ...provider, start: async (a) => { atStart = ledgerFor(a.issue).entries("sandbox").map((e) => e.value); const h = await provider.start(a); setTimeout(() => finish(h, { terminalReason: "merged", pr: 4 }), 5); return h; } };
+      const started = [];
+      const r = await providerLanes({ provider: wrapped, laneArgs: () => ["--repo", "o/r"], ledgerFor, env: { GH_TOKEN: SECRET }, secrets: ["GH_TOKEN"], pollMs: 2 }).runOne(9, "staging", { onStart: (x) => started.push(x) });
+      assert.equal(r.terminalReason, "merged");
+      assert.deepEqual(atStart, [provider.idFor(9)]);
+      assert.equal(ledgerFor(9).read(), null);
+      const files = [JSON.stringify(started), JSON.stringify(r)];
+      if (existsSync(join(root, "bt"))) for (const f of readdirSync(join(root, "bt"))) files.push(readFileSync(join(root, "bt", f), "utf8"));
+      if (existsSync(batch.logFile(9))) files.push(readFileSync(batch.logFile(9), "utf8"));
+      for (const f of files) { assert.equal(f.includes(SECRET), false); assert.equal(f.includes(TOKEN), false); }
+    });
+
+    it("a sandbox that fails to start: needs-human sandbox.start_failed, ledger released, orchestrate does not relaunch it", async () => {
+      const opts = name === "container" ? { startError: "Unable to find image 'img:1' locally" } : { launchError: new Error("sandbox launch: HTTP 400") };
+      const { work, provider } = setup(opts);
+      const root = join(work, "ledger");
+      const ledgerFor = (n) => makeLedger({ root, batch: "bt", lane: `sandbox-${n}`, owner: "o", issue: n, host: HOST, pid: process.pid });
+      const lanes = providerLanes({ provider, laneArgs: () => [], ledgerFor, pollMs: 1 });
+      let starts = 0;
+      const rows = await orchestrate({ issues: [5], parallel: 1, readBody: async () => "", runOne: async (n, l) => { starts++; return lanes.runOne(n, l); } });
+      assert.deepEqual(rows.map((x) => [x.issue, x.outcome, x.code]), [[5, "needs-human", "sandbox.start_failed"]]);
+      assert.equal(starts, 1, "not relaunched");
+      assert.equal(ledgerFor(5).read(), null);
+    });
+  });
+}
+
+describe("remote adapter (#4254)", () => {
+  const setup = () => { const batch = openBatch(join(tmpDir("remote-"), "batches"), "bt"); return { batch, ...remoteFixture(batch) }; };
+
+  it("launch spec: clones the target repo at the lane, mounts the shared cache store, scoped env only, run-issue command", async () => {
+    const { provider, transport } = setup();
+    await provider.start({ issue: 7, args: ["--repo", "o/r", "--lane", "staging"], env: { GH_TOKEN: SECRET, AWS_SECRET_ACCESS_KEY: "leak-leak" }, secrets: ["GH_TOKEN"] });
+    const spec = transport.specs[0];
+    assert.equal(spec.id, "fdrsbx-bt-7");
+    assert.deepEqual(spec.repo, { slug: "o/r", url: "https://github.com/o/r.git", ref: "staging" });
+    assert.deepEqual(spec.cache, { store: "s3://cache", key: "o_r" });
+    assert.deepEqual(spec.env, { FORGEDOCK_BATCH_ID: "bt", GH_REPO: "o/r", GH_TOKEN: SECRET });
+    assert.deepEqual(spec.command.slice(0, 3), ["forgedock", "run-issue", "7"]);
+    assert.deepEqual(spec.command.slice(-2), ["--result-file", "/result/7.json"]);
+    assert.equal(JSON.stringify(spec).includes(TOKEN), false, "the transport credential is never in the spec");
+  });
+
+  it("a secret missing from the env is read from the keychain (credential resolver)", async () => {
+    const batch = openBatch(join(tmpDir("remote-kc-"), "batches"), "bt");
+    const transport = fakeTransport();
+    const p = remoteProvider({ batch, repo: "o/r", settings: { secrets: ["GH_TOKEN"] }, transport, env: {}, credentials: (n) => (n === "GH_TOKEN" ? "from-keychain" : null) });
+    await p.start({ issue: 1, args: [], env: {}, secrets: ["GH_TOKEN"] });
+    assert.equal(transport.specs[0].env.GH_TOKEN, "from-keychain");
+  });
+
+  it("streams the lane log into the batch log, redacted; billable minutes on the handle and on the lane result", async () => {
+    const { provider, finish, batch } = setup();
+    const lanes = providerLanes({ provider: { ...provider, start: async (a) => { const h = await provider.start(a); setTimeout(() => finish(h, { terminalReason: "merged", pr: 2 }), 5); return h; } },
+      laneArgs: () => [], ledgerFor: () => null, env: { GH_TOKEN: SECRET }, secrets: ["GH_TOKEN"], pollMs: 2 });
+    const r = await lanes.runOne(3, null);
+    assert.equal(r.terminalReason, "merged");
+    assert.deepEqual(r.sandbox, { provider: "remote", id: "fdrsbx-bt-3", minutes: 3.5, cost_usd: 0 }); // #4255: cost from cost_per_minute (0 here)
+    const log = readFileSync(batch.logFile(3), "utf8");
+    assert.match(log, /lane done/);
+    assert.equal(log.includes(SECRET) || log.includes(TOKEN), false);
+    assert.match(log, /\[redacted\]/);
+  });
+
+  it("a capacity error defers (sandbox.capacity, retryInSeconds); persistent status errors end the lane", async () => {
+    const batch = openBatch(join(tmpDir("remote-cap-"), "batches"), "bt");
+    const transport = fakeTransport({ launchError: Object.assign(new Error("sandbox launch: HTTP 429"), { retryable: true, retryInSeconds: 30 }) });
+    const p = remoteProvider({ batch, repo: "o/r", transport, env: {} });
+    const r = await providerLanes({ provider: p, laneArgs: () => [], ledgerFor: () => null, pollMs: 1 }).runOne(4, null);
+    assert.deepEqual([r.terminalReason, r.code, r.retryInSeconds], ["deferred", "sandbox.capacity", 30]);
+    const flaky = { ...fakeTransport(), status: async () => { throw new Error("ECONNRESET"); } };
+    const q = remoteProvider({ batch, repo: "o/r", transport: flaky, env: {} });
+    const h = await q.start({ issue: 6, args: [] });
+    const seen = [];
+    for (let i = 0; i < 5; i++) seen.push(await q.status(h));
+    assert.deepEqual(seen, ["running", "running", "running", "running", "gone"]);
+  });
+
+  it("httpTransport: bearer token, JSON protocol, 404 = gone/destroyed, 429 retryable; the token never in errors", async () => {
+    const calls = [];
+    const reply = (status, body, headers = {}) => ({ status, ok: status >= 200 && status < 300, text: async () => (body === undefined ? "" : JSON.stringify(body)), headers: { get: (k) => headers[k] ?? null } });
+    let launchStatus = 201;
+    const fetchFn = async (url, init) => {
+      calls.push([init.method, url, init.headers.authorization]);
+      if (init.method === "POST") return launchStatus === 201 ? reply(201, { id: "x" }) : reply(launchStatus, { error: TOKEN }, { "retry-after": "12" });
+      if (url.endsWith("/usage")) return reply(200, { minutes: 2 });
+      if (url.endsWith("/result")) return reply(404);
+      if (url.includes("/logs")) return reply(200, { text: "hi", cursor: 2 });
+      if (init.method === "DELETE") return reply(404);
+      return reply(200, { state: "running" });
+    };
+    const t = httpTransport({ endpoint: "https://pool.example/v1/", token: TOKEN, fetchFn });
+    await t.launch({ id: "x" });
+    assert.deepEqual(calls[0], ["POST", "https://pool.example/v1/sandboxes", `Bearer ${TOKEN}`]);
+    assert.equal(await t.status("x"), "running");
+    assert.deepEqual(await t.logs("x", 0), { text: "hi", cursor: 2 });
+    assert.equal(await t.result("x"), null);
+    assert.deepEqual(await t.usage("x"), { minutes: 2 });
+    assert.equal(await t.destroy("x"), true);
+    launchStatus = 429;
+    await assert.rejects(t.launch({ id: "y" }), (e) => e.retryable === true && e.retryInSeconds === 12 && !e.message.includes(TOKEN));
+  });
+
+  it("redact replaces every secret value", () => {
+    assert.equal(redact(`a ${SECRET} b ${SECRET}`, [SECRET, "", null]), "a [redacted] b [redacted]");
+  });
+});
+
+describe("remote config and the Actions constraint (#4254)", () => {
+  it("parseExecution reads the remote settings; remote is never the default provider", () => {
+    assert.deepEqual(parseExecution({ mode: "remote", max_remote: "2", provider: "remote", endpoint: "https://pool.example/v1", token_env: "FD_POOL_TOKEN", cache_store: "s3://c", allow_actions: "true" }),
+      { mode: "remote", maxRemote: 2, provider: "remote", image: null, secrets: [], budget: { batchMinutes: null, batchUsd: null, dayMinutes: null, dayUsd: null, onBudget: "stop", costPerMinute: 0 }, endpoint: "https://pool.example/v1", tokenEnv: "FD_POOL_TOKEN", cacheStore: "s3://c", allowActions: true });
+    for (const sec of [{}, { mode: "remote", max_remote: "3" }, { mode: "hybrid" }, { mode: "remote", endpoint: "https://api.github.com/repos/o/r/actions/workflows/x/dispatches" }]) {
+      assert.notEqual(parseExecution(sec).provider, "remote");
+    }
+    assert.equal(parseExecution({ endpoint: "not a url", token_env: "bad-name" }).endpoint, undefined);
+  });
+
+  it("providerByName remote: needs an endpoint; a GitHub Actions endpoint is refused unless allow_actions", () => {
+    const batch = openBatch(tmpDir("remote-cfg-"), "bt");
+    assert.throws(() => providerByName("remote", { batch, repo: "o/r", exec: parseExecution({ mode: "remote", provider: "remote" }) }), (e) => e.code === "execution.provider.misconfigured");
+    const actions = { mode: "remote", provider: "remote", endpoint: "https://api.github.com/repos/o/r/actions/workflows/lane.yml/dispatches" };
+    assert.throws(() => providerByName("remote", { batch, repo: "o/r", exec: parseExecution(actions) }), (e) => e.code === "execution.provider.actions_refused");
+    assert.equal(providerByName("remote", { batch, repo: "o/r", exec: parseExecution({ ...actions, allow_actions: "true" }), env: {} }).name, "remote");
+    assert.equal(providerByName("remote", { batch, repo: "o/r", exec: parseExecution({ provider: "remote", endpoint: "https://pool.example/v1" }), env: {} }).name, "remote");
+    assert.ok(isActionsEndpoint("https://ghe.example/api/v3/repos/o/r/actions/runs") && !isActionsEndpoint("https://pool.example/v1"));
+    assert.equal(remoteTransportFor({}, { transport: fakeTransport() }) !== null, true);
+  });
+
+  it("resolveCredential: env first, then keychain, failures are null", () => {
+    assert.equal(resolveCredential("FD_T", { env: { FD_T: "e" }, keychain: () => "k" }), "e");
+    assert.equal(resolveCredential("FD_T", { env: { FD_T: "" }, keychain: (n) => (n === "FD_T" ? "k" : null) }), "k");
+    assert.equal(resolveCredential("FD_T", { env: {}, keychain: () => { throw new Error("locked"); } }), null);
+    assert.equal(resolveCredential("bad name", { env: { "bad name": "x" } }), null);
+  });
+});
+
+describe("gc reaps a remote sandbox left by a dead dispatcher (#4254)", () => {
+  it("destroys it through the transport and releases the ledger; failure keeps it listed", async () => {
+    const home = tmpDir("remote-gc-");
+    const root = join(home, ".forge", "ledger");
+    mkdirSync(join(home, ".forge", "tmp"), { recursive: true });
+    const led = makeLedger({ root, batch: "bt", lane: "sandbox-7", owner: "orch_1", issue: 7, host: HOST, pid: 424242 });
+    led.register("sandbox", "fdrsbx-bt-7", { provider: "remote", handle: { provider: "remote", id: "fdrsbx-bt-7", issue: 7 } });
+    const transport = fakeTransport();
+    const probes = { cwd: home, host: HOST, ledgerRoot: root, forgeTmpRoot: join(home, ".forge", "tmp"), worktreeRoot: join(home, "wt"), alive: () => false, ppid: () => 0,
+      procsInDir: () => [], dirSize: () => 0, docker: async () => "", git: async () => "", gh: async () => "[]", sandboxTransport: transport };
+    const plan = await planGc({ probes, scopes: new Set(["sandboxes"]) });
+    assert.deepEqual(plan.items.map((i) => [i.type, i.id, i.action]), [["sandbox", "fdrsbx-bt-7", "reclaim"]]);
+    // Without a configured transport (no forge.yaml execution endpoint) the teardown fails and the entry stays.
+    const failed = await applyGc(plan, { ...probes, sandboxTransport: undefined });
+    assert.equal(failed.reclaimed.length, 0);
+    assert.equal(existsSync(led.path), true);
+    const res = await applyGc(plan, probes);
+    assert.deepEqual(res.reclaimed.map((i) => i.id), ["fdrsbx-bt-7"]);
+    assert.deepEqual(transport.destroyed, ["fdrsbx-bt-7"]);
+    assert.equal(existsSync(led.path), false);
+  });
+});

package/bin/lean/sandbox-remote.mjs

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Remote sandbox provider (#4254) on the execution.mjs provider seam: an ephemeral VM or container from a runner pool
+ * or a remote agent session, reached through a transport. The transport is the only provider-specific part:
+ *   launch(spec) · status(id) -> running|exited|gone · logs(id, cursor) -> {text, cursor} · result(id) -> object|null
+ *   usage(id) -> {minutes}|null · destroy(id) -> true (a gone sandbox is destroyed)
+ * The sandbox is addressed by the id ForgeDock picks (`idFor`), so a ledger entry written before `launch` is enough to
+ * tear it down later. The launch spec asks the sandbox to clone the target repo, mount the configured shared cache
+ * store, and run `forgedock run-issue`; its env is only `scopedEnv` (the repo's allowlisted secret names, resolved from
+ * the env or the keychain, plus GH_REPO and FORGEDOCK_BATCH_ID). The lane log is streamed into the batch log file with
+ * every secret value and the transport credential redacted. Billable minutes go on the handle (`handle.minutes`);
+ * the handle never holds a secret.
+ *
+ * `httpTransport` is the one shipped transport: a small JSON protocol (docs/CONFIG.md `execution`) that a runner pool
+ * or a session gateway fronts. Tests use an in-memory transport.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { safeSegment } from "./ledger.mjs";
+import { scopedEnv } from "./execution.mjs";
+import { resolveCredential } from "./credentials.mjs";
+
+const REDACTED = "[redacted]";
+const STATUS_ERRORS = 5;
+/** Replace every value of `secrets` (4+ chars, longest first) in `text`. */
+export function redact(text, secrets = []) {
+  let s = String(text ?? "");
+  for (const v of [...new Set(secrets.filter((x) => typeof x === "string" && x.length >= 4))].sort((a, b) => b.length - a.length)) s = s.split(v).join(REDACTED);
+  return s;
+}
+
+/** True when an endpoint is a GitHub Actions API (spends Actions minutes): api.github.com or an `/actions/` path. */
+export function isActionsEndpoint(endpoint) {
+  try {
+    const u = new URL(String(endpoint));
+    return u.hostname.toLowerCase() === "api.github.com" || /\/actions(\/|$)/i.test(u.pathname);
+  } catch { return false; }
+}
+
+/**
+ * Generic HTTP transport: POST {endpoint}/sandboxes (body = launch spec), GET /sandboxes/:id -> {state},
+ * GET /sandboxes/:id/logs?cursor=N -> {text, cursor}, GET /sandboxes/:id/result -> lane result (404 = none yet),
+ * GET /sandboxes/:id/usage -> {minutes}, DELETE /sandboxes/:id (404 = gone). `Authorization: Bearer <token>`.
+ * 429/503 on launch is a retryable capacity error (`Retry-After` seconds). Error text never carries the token.
+ */
+export function httpTransport({ endpoint, token = null, fetchFn = globalThis.fetch }) {
+  const root = String(endpoint ?? "").replace(/\/+$/, "");
+  const call = async (method, path, body) => {
+    const res = await fetchFn(`${root}${path}`, { method, headers: { accept: "application/json", ...(body ? { "content-type": "application/json" } : {}), ...(token ? { authorization: `Bearer ${token}` } : {}) },
+      ...(body ? { body: JSON.stringify(body) } : {}) });
+    let data = null;
+    try { const t = await res.text(); data = t ? JSON.parse(t) : null; } catch { data = null; }
+    return { status: res.status, ok: res.ok, data, retryAfter: res.headers?.get?.("retry-after") ?? null };
+  };
+  const fail = (what, r) => {
+    const e = new Error(`sandbox ${what}: HTTP ${r.status}`);
+    if (r.status === 429 || r.status === 503) { e.retryable = true; const n = Number(r.retryAfter); if (Number.isFinite(n) && n > 0) e.retryInSeconds = n; }
+    return e;
+  };
+  const p = (id) => `/sandboxes/${encodeURIComponent(id)}`;
+  return {
+    async launch(spec) { const r = await call("POST", "/sandboxes", spec); if (!r.ok) throw fail("launch", r); return r.data ?? {}; },
+    async status(id) {
+      const r = await call("GET", p(id));
+      if (r.status === 404) return "gone";
+      if (!r.ok) throw fail("status", r);
+      const s = String(r.data?.state ?? "");
+      return s === "running" || s === "pending" || s === "starting" ? "running" : s === "gone" ? "gone" : "exited";
+    },
+    async logs(id, cursor = 0) { const r = await call("GET", `${p(id)}/logs?cursor=${encodeURIComponent(cursor)}`); return r.ok ? { text: String(r.data?.text ?? ""), cursor: r.data?.cursor ?? cursor } : { text: "", cursor }; },
+    async result(id) { const r = await call("GET", `${p(id)}/result`); return r.ok && r.data && typeof r.data === "object" ? r.data : null; },
+    async usage(id) { const r = await call("GET", `${p(id)}/usage`); return r.ok && Number.isFinite(Number(r.data?.minutes)) ? { minutes: Number(r.data.minutes) } : null; },
+    async destroy(id) { const r = await call("DELETE", p(id)); if (r.ok || r.status === 404) return true; throw fail("destroy", r); },
+  };
+}
+
+/**
+ * The remote provider. `settings` is parseExecution's output (image, cacheStore, tokenEnv, secrets); `env` is the
+ * dispatcher's env (secret values for redaction on adopt); `credentials(name)` resolves a secret (env, then keychain).
+ */
+export function remoteProvider({ batch, repo, settings = {}, transport, env = process.env, credentials = (name) => resolveCredential(name, { env }), now = () => Date.now() }) {
+  if (!transport) throw new Error("remote provider needs a transport");
+  const idFor = (issue) => `fdrsbx-${safeSegment(batch.id)}-${issue}`;
+  const errs = new Map(); // sandbox id -> consecutive status errors
+  const known = new Set(); // secret values seen this process, for redaction
+  const remember = (v) => { if (typeof v === "string" && v.length >= 4) known.add(v); };
+  for (const k of settings.secrets ?? []) remember(credentials(k));
+  if (settings.tokenEnv) remember(credentials(settings.tokenEnv));
+  const minutesOf = async (h) => {
+    let m = null;
+    try { const u = await transport.usage?.(h.id); if (u && Number.isFinite(Number(u.minutes))) m = Number(u.minutes); } catch { m = null; }
+    if (m === null && Number.isFinite(h.startedAt)) m = Math.round(((now() - h.startedAt) / 60000) * 10) / 10;
+    if (m !== null) h.minutes = Math.max(h.minutes ?? 0, m);
+  };
+  const pullLogs = async (h) => {
+    if (!transport.logs) return;
+    try {
+      const { text, cursor } = (await transport.logs(h.id, h.logCursor ?? 0)) ?? {};
+      if (text) { const f = batch.logFile(h.issue); mkdirSync(dirname(f), { recursive: true }); appendFileSync(f, redact(text, [...known])); }
+      if (cursor !== undefined) h.logCursor = cursor;
+    } catch { /* the next poll retries */ }
+  };
+  return {
+    name: "remote",
+    idFor,
+    async start({ issue, args = [], env: laneEnv = env, secrets = settings.secrets ?? [] }) {
+      const id = idFor(issue);
+      // Each allowlisted secret from the env, else the keychain (#4254); nothing else from the host.
+      const resolved = {};
+      for (const k of secrets) { const v = laneEnv?.[k] !== undefined && laneEnv[k] !== "" ? String(laneEnv[k]) : credentials(k); if (v) { resolved[k] = v; remember(v); } }
+      const li = args.indexOf("--lane");
+      const resultFile = `/result/${issue}.json`;
+      const spec = {
+        id, issue, batch: batch.id, image: settings.image ?? null,
+        repo: { slug: repo, url: repo ? `https://github.com/${repo}.git` : null, ref: li >= 0 ? args[li + 1] ?? null : null },
+        cache: settings.cacheStore ? { store: settings.cacheStore, key: safeSegment(String(repo ?? "repo")) } : null,
+        env: scopedEnv({ env: resolved, secrets, batchId: batch.id, repo }),
+        command: ["forgedock", "run-issue", String(issue), ...args, "--result-file", resultFile], result_file: resultFile,
+      };
+      const startedAt = now();
+      await transport.launch(spec);
+      return { provider: "remote", id, issue, startedAt, minutes: 0 };
+    },
+    async status(h) {
+      let s;
+      // A transient transport error is not an exit; STATUS_ERRORS in a row is (the lane then ends without a result).
+      try { s = await transport.status(h.id); errs.delete(h.id); } catch { const k = (errs.get(h.id) ?? 0) + 1; errs.set(h.id, k); return k >= STATUS_ERRORS ? "gone" : "running"; }
+      await pullLogs(h);
+      return s === "running" ? "running" : s === "gone" ? "gone" : "exited";
+    },
+    async fetchResult(h) {
+      const r = await transport.result(h.id);
+      if (r) { await pullLogs(h); await minutesOf(h); }
+      return r ?? null;
+    },
+    async teardown(h) {
+      await minutesOf(h);
+      try { return (await transport.destroy(h.id)) !== false; } catch { return false; }
+    },
+  };
+}