forgedock 1.40.0 → 1.42.0

package/bin/lean/conformance.test.mjs

@@ -81,6 +81,27 @@ describe("#4655 multi-requirement amendment references", () => {
     assert.match(applyAmendments(C, [{ kind: "defer", requirement: "R1/R9", why: "w" }]).problems[0], /unknown requirement R9/);
     assert.match(applyAmendments(C, [{ kind: "scope-note", requirement: "R1", why: "w" }]).problems[0], /unknown kind 'scope-note'; valid kinds are/);
   });
+  it("supersede-guard guards[] expands to per-guard supersedes", () => {
+    const a = applyAmendments(C, [{ kind: "supersede-guard", guards: ["#4879", "#4838"], why: "x" }]);
+    assert.deepEqual(a.problems, []);
+    assert.deepEqual(a.contract.supersedes, [{ guard: "#4879", why: "x" }, { guard: "#4838", why: "x" }]);
+    assert.equal(a.applied.length, 2);
+  });
+  it("synonym kinds and a supersedes amendment with guards[] expand alike; an invalid guard id is reported", () => {
+    for (const kind of ["supersede", "supersedes-guard", "supersedes"]) {
+      const a = applyAmendments(C, [{ kind, guards: ["4879", "#4838"], why: "x" }]);
+      assert.deepEqual(a.problems, [], kind);
+      assert.deepEqual(a.contract.supersedes.map((s) => s.guard), ["#4879", "#4838"], kind);
+    }
+    const bad = applyAmendments(C, [{ kind: "supersedes", guards: ["#4879", "abc"], why: "x" }]);
+    assert.equal(bad.problems.length, 1);
+    assert.match(bad.problems[0], /needs guard/);
+    assert.deepEqual(bad.contract.supersedes.map((s) => s.guard), ["#4879"]);
+    assert.match(applyAmendments(C, [{ kind: "supersede-guard", guards: [], why: "x" }]).problems[0], /needs guard/);
+  });
+  it("an unrelated unknown kind is still rejected with the valid-kinds message", () => {
+    assert.match(applyAmendments(C, [{ kind: "supersede-everything", guards: ["#1"], why: "w" }]).problems[0], /unknown kind 'supersede-everything'; valid kinds are/);
+  });
 });
 
 describe("#4574 amendment slips", () => {
@@ -141,6 +162,9 @@ describe("precheck (deterministic, no reviewer)", () => {
     assert.deepEqual(codes(precheck({ contract: C, result: failed, changedFiles: files, ciVerified: true, validateRuns: { V1: { rc: 127, output: "bash: pytest: command not found" } } })), [], "CI-verified head: like a validate left to CI");
     assert.deepEqual(codes(precheck({ contract: C, result: failed, changedFiles: files, validateRuns: { V1: { rc: 0, output: "" } } })), [], "a passing rerun counts as passed");
     assert.deepEqual(codes(precheck({ contract: C, result: failed, changedFiles: files, validateRuns: { V1: { rc: 1, output: "AssertionError: 1 !== 2" } } })), ["conformance.unimplemented"]);
+    // #4906: a rerun that timed out (rc 124) is infrastructure, never conformance.unimplemented
+    assert.deepEqual(codes(precheck({ contract: C, result: failed, changedFiles: files, validateRuns: { V1: { rc: 124, output: "(timed out)" } } })), ["env.validate_timeout"]);
+    assert.deepEqual(codes(precheck({ contract: C, result: failed, changedFiles: files, ciVerified: true, validateRuns: { V1: { rc: 124, output: "" } } })), [], "CI-verified head covers a timed-out rerun");
     const local = precheck({ contract: C, result: failed, changedFiles: files, repoHas: repoTracks(["src/leak/__init__.py"]), validateRuns: { V1: { rc: 1, output: "ModuleNotFoundError: No module named 'leak.core'" } } });
     assert.deepEqual(codes(local), ["conformance.unimplemented"], "a repo module the change did not create is a code defect");
   });
@@ -866,3 +890,105 @@ describe("implied docs-freshness deliverable", () => {
     assert.deepEqual(impliedDocDeliverables({ before: [...base, "docs/guide.md"], after, contract: C, wasFailing: true, nowOk: true }), []);
   });
 });
+
+import { normalizeKindModes, blockingFailures, unverifiedRequirements, KIND_MODES } from "./conformance.mjs";
+
+describe("per-kind modes and requirement evidence", () => {
+  const f = (code) => ({ code });
+  const ALLOW = ["conformance.unimplemented"];
+  it("normalizeKindModes keeps valid entries from a map or the flat forge.yaml string", () => {
+    assert.deepEqual(KIND_MODES, ["enforce", "shadow"]);
+    assert.deepEqual(normalizeKindModes({ "a.b": "shadow", c: "bogus", d: "enforce" }), { "a.b": "shadow", d: "enforce" });
+    assert.deepEqual(normalizeKindModes("a.b=shadow, c.d = enforce, x=nope"), { "a.b": "shadow", "c.d": "enforce" });
+    assert.deepEqual(normalizeKindModes(null), {});
+  });
+  it("a shadow kind is recorded and an enforce kind blocks, in either lane mode", () => {
+    const kinds = { "k.shadow": "shadow", "k.enforce": "enforce" };
+    for (const shadow of [true, false]) {
+      const r = blockingFailures([f("k.shadow"), f("k.enforce")], { shadow, kinds });
+      assert.deepEqual([r.block.map((x) => x.code), r.record.map((x) => x.code)], [["k.enforce"], ["k.shadow"]]);
+    }
+  });
+  it("kinds without their own mode follow the lane: enforce blocks all, shadow only the allowlist", () => {
+    assert.equal(blockingFailures([f("x"), f("conformance.unimplemented")], { shadow: false }).block.length, 2);
+    const r = blockingFailures([f("x"), f("conformance.unimplemented")], { shadow: true, allow: ALLOW });
+    assert.deepEqual([r.block.map((x) => x.code), r.record.map((x) => x.code)], [["conformance.unimplemented"], ["x"]]);
+    assert.equal(blockingFailures([f("conformance.unimplemented")], { shadow: true, allow: ALLOW, kinds: { "conformance.unimplemented": "shadow" } }).block.length, 0);
+  });
+  it("a deliver requirement with no executed evidence test is unverified, with its id", () => {
+    const c = {
+      requirements: [{ id: "R1", disposition: "deliver" }, { id: "R2", disposition: "deliver" }, { id: "R3", disposition: "deliver" }, { id: "R4", disposition: "defer" }, { id: "R5", disposition: "deliver", verify: "out_of_band" }],
+      deliverables: [{ id: "D1", path: "src/a.js", requirements: ["R1"] }, { id: "D2", path: "test/a.test.js", requirements: ["R1"] }, { id: "D3", path: "test/b.test.js", requirements: ["R2"] }],
+      validate: [{ id: "V1", command: "node --test test/a.test.js" }, { id: "V2", command: "node --test test/b.test.js" }],
+    };
+    const u = (o) => unverifiedRequirements(c, o).map((x) => x.id);
+    assert.deepEqual(u({ runs: [{ id: "V1", exit: 0 }, { id: "V2", exit: 1 }] }), ["R2", "R3"]);
+    assert.deepEqual(u({ runs: [{ id: "V1", exit: 1 }], reruns: { V1: { rc: 0 }, V2: { rc: 0 } } }), ["R3"]);
+    assert.deepEqual(u({ runs: [], ciCovered: ["V1", "V2"] }), ["R3"]);
+    assert.deepEqual(u({ runs: [{ id: "V1", exit: 0 }, { id: "V2", exit: 0 }], reruns: { V2: { rc: 1 } } }), ["R2", "R3"]);
+  });
+  it("formatShadowSummary adds per-kind shares only when rows carry kinds", () => {
+    const rows = [{ conformance: { mode: "shadow", would: "nonconforming", kinds: ["a.b"] } }, { conformance: { mode: "shadow", would: "conforms", kinds: [] } }];
+    assert.match(formatShadowSummary(rows), /; per kind: a\.b 1\/2 \(50%\)$/);
+    assert.doesNotMatch(formatShadowSummary([{ conformance: { mode: "shadow", would: "conforms" } }]), /per kind/);
+  });
+});
+
+import { mutationTargets, mutationFailures, runMutationCheck, MUTATION_SURVIVED } from "./conformance.mjs";
+
+describe("mutation check (#4913)", () => {
+  const c = {
+    requirements: [{ id: "R1", quote: "q1", disposition: "deliver" }, { id: "R2", quote: "q2", disposition: "deliver" }, { id: "R3", quote: "q3", disposition: "deliver", verify: "out_of_band", evidence: "job" }],
+    deliverables: [{ id: "D1", path: "test/a.test.js", requirements: ["R1", "R3"] }, { id: "D2", path: "src/b.js", requirements: ["R2"] }],
+    validate: [{ id: "V1", command: "node --test test/a.test.js" }],
+  };
+  const green = { runs: [{ id: "V1", exit: 0 }] };
+  it("targets only deliver requirements whose evidence test ran green", () => {
+    assert.deepEqual(mutationTargets(c, green), [{ id: "R1", commands: [{ id: "V1", command: "node --test test/a.test.js" }] }]);
+    assert.deepEqual(mutationTargets(c, { runs: [{ id: "V1", exit: 1 }] }), []);
+  });
+  it("only a survivor fails; killed and skipped never do", () => {
+    const f = mutationFailures([{ id: "R1", command: "x", status: "survived" }, { id: "R2", command: "y", status: "killed" }, { id: "R4", command: "z", status: "skipped" }]);
+    assert.equal(f.length, 1); assert.equal(f[0].code, MUTATION_SURVIVED); assert.match(f[0].detail, /^R1 /);
+  });
+  const harness = (o = {}) => {
+    const calls = [], fs = { writeFileSync() {}, rmSync() {} };
+    let restored = false;
+    const git = async (a) => { calls.push(a.join(" ")); if (a[0] === "reset") restored = true; if (a[0] === "status") return restored ? (o.stillDirty ?? "") : (o.dirty ?? ""); if (a[0] === "apply" && o.applyFails) throw new Error("no"); return "patch"; };
+    const runCommand = async () => { calls.push("run"); if (o.throws) throw new Error("boom"); return { rc: o.rc ?? 0 }; };
+    const targets = mutationTargets(c, green);
+    return { calls, go: () => runMutationCheck({ targets, files: ["src/b.js", "test/a.test.js"], base: "origin/staging", git, runCommand, cwd: "/w", fs, tmp: "/t" }) };
+  };
+  it("reverts only non-test files, reruns, then restores from HEAD (reset + clean of those paths)", async () => {
+    const h = harness(); const r = await h.go();
+    assert.deepEqual(r.results.map((x) => x.status), ["survived"]);
+    assert.ok(h.calls.some((x) => x.startsWith("diff --binary origin/staging...HEAD -- src/b.js") && !x.includes("test/a")));
+    assert.deepEqual(h.calls.filter((x) => /^(apply|run|reset|clean)/.test(x)), ["apply -R --whitespace=nowarn /t/mutation-" + process.pid + ".patch", "run", "reset -q --hard HEAD", "clean -fdq -- src/b.js"]);
+  });
+  it("a failing rerun is killed; the tree is restored even when the command throws", async () => {
+    assert.equal((await harness({ rc: 1 }).go()).results[0].status, "killed");
+    const h = harness({ throws: true }); assert.equal((await h.go()).results[0].status, "skipped");
+    assert.equal(h.calls.at(-1), "status --porcelain -- src/b.js");
+  });
+  it("a dirty tree or a failed revert skips without running anything or restoring", async () => {
+    for (const o of [{ dirty: " M src/b.js" }, { applyFails: true }]) { const h = harness(o); const r = await h.go(); assert.deepEqual(r.results, []); assert.ok(r.skipped); assert.ok(!h.calls.includes("run") && !h.calls.some((x) => x.startsWith("reset"))); }
+  });
+  it("#4931: a tree still dirty after the restore throws instead of returning (never push the reverted change)", async () => {
+    await assert.rejects(harness({ stillDirty: "?? src/b.js" }).go(), /could not restore the worktree: \?\? src\/b\.js/);
+  });
+  it("#4931: a real repo whose change deleted a non-test file is fully restored", async () => {
+    const { execFileSync } = await import("node:child_process");
+    const { writeFileSync, existsSync, readFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const { tmpDir } = await import("../tests/_tmp.mjs");
+    const d = tmpDir("mut-");
+    const g = (...a) => execFileSync("git", ["-C", d, "-c", "user.email=t@t", "-c", "user.name=t", ...a], { encoding: "utf8" });
+    g("init", "-q", "-b", "main"); writeFileSync(join(d, "a.js"), "a1\n"); writeFileSync(join(d, "b.js"), "b\n"); g("add", "."); g("commit", "-qm", "base");
+    g("checkout", "-qb", "lane"); writeFileSync(join(d, "a.js"), "a2\n"); g("rm", "-q", "b.js"); g("add", "a.js"); g("commit", "-qm", "change");
+    const r = await runMutationCheck({ targets: [{ id: "R1", commands: [{ id: "V1", command: "t" }] }], files: ["a.js", "b.js"], base: "main",
+      git: async (a) => g(...a), runCommand: async () => ({ rc: 1 }), cwd: d, tmp: d });
+    assert.equal(r.skipped, "", r.skipped); assert.equal(r.results[0].status, "killed");
+    assert.equal(readFileSync(join(d, "a.js"), "utf8"), "a2\n"); assert.equal(existsSync(join(d, "b.js")), false);
+    assert.equal(g("status", "--porcelain").trim(), "");
+  });
+});

package/bin/lean/depcache.mjs

@@ -146,7 +146,15 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
 
   // ---- trees ----
   const boundary = (p) => new RegExp(p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "(?=$|[/\\\\'\"\\s:;])", "g");
-  /** Hardlink `src` into `dst`; symlinks recreated; files in bin dirs that name `from` are copied with `to` instead. */
+  /** Hardlink a file; across filesystems (EXDEV, #4909) copy it with its mode so the cache is reused instead of reinstalled. */
+  function linkOrCopy(sp, dp) {
+    try { fs.linkSync(sp, dp); } catch (e) {
+      if (e?.code !== "EXDEV") throw e;
+      fs.copyFileSync(sp, dp);
+      fs.chmodSync(dp, fs.statSync(sp).mode & 0o7777);
+    }
+  }
+  /** Hardlink `src` into `dst` (copy on EXDEV); symlinks recreated; files in bin dirs that name `from` are copied with `to` instead. */
   function linkTree(src, dst, { from = null, to = null, binDir = () => false } = {}) {
     const re = from && to && from !== to ? boundary(from) : null;
     const walk = (s, d, rel) => {
@@ -165,7 +173,7 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
               continue;
             }
           }
-          fs.linkSync(sp, dp);
+          linkOrCopy(sp, dp);
         }
       }
     };

package/bin/lean/depcache.test.mjs

@@ -272,23 +272,12 @@ describe("depcache (#4220): shared dependency installs keyed by lock hash", () =
     assert.ok(!existsSync(join(wt, "node_modules")));
     assert.equal(snapDirs(s.root, "pnpm").length, 0);
 
-    const s2 = setup("npm");
-    const exdev = { ...fs, linkSync: () => { throw Object.assign(new Error("EXDEV: cross-device link"), { code: "EXDEV" }); } };
-    const c2 = makeDepCache({ root: s2.root, exec: s2.f.exec, env: {}, fs: exdev });
-    const wt2 = s2.lane("y");
-    const [r2] = await c2.prepare({ wt: wt2, repoKey: "r" });
-    assert.equal(r2.status, "miss-installed");
-    assert.equal(r2.published, false);
-    assert.match(r2.reason, /EXDEV/);
-    assert.ok(existsSync(join(wt2, "node_modules/left-pad/index.js")), "the lane keeps its own install");
-    assert.equal(snapDirs(s2.root, "npm").length, 0);
-    assert.deepEqual(readdirSync(join(s2.root, "r")), [], "no tmp or lock left");
-    // A published snapshot that cannot be linked (EXDEV) is skipped and leaves nothing half-linked.
-    await s2.cache.prepare({ wt: s2.lane("z"), repoKey: "r" });
-    const wt3 = s2.lane("w");
-    const [r3] = await c2.prepare({ wt: wt3, repoKey: "r" });
-    assert.equal(r3.status, "skipped");
-    assert.ok(!existsSync(join(wt3, "node_modules")));
+    const s4x = setup("npm");
+    const noLink = makeDepCache({ root: s4x.root, exec: s4x.f.exec, env: {}, fs: { ...fs, linkSync: () => { throw Object.assign(new Error("EACCES"), { code: "EACCES" }); } } });
+    const [rx] = await noLink.prepare({ wt: s4x.lane("y"), repoKey: "r" });
+    assert.equal(rx.status, "miss-installed");
+    assert.equal(rx.published, false);
+    assert.equal(snapDirs(s4x.root, "npm").length, 0);
 
     const s4 = setup("npm");
     const c4 = makeDepCache({ root: s4.root, exec: async (cmd, args) => { if (cmd === "git" || args[0] === "--version") return s4.f.exec(cmd, args, { cwd: s4.base }); throw Object.assign(new Error("spawn npm ENOENT"), { code: "ENOENT" }); }, env: {} });
@@ -297,6 +286,22 @@ describe("depcache (#4220): shared dependency installs keyed by lock hash", () =
     assert.match(r4.reason, /tool not found/);
   });
 
+  it("with the cache on another filesystem (EXDEV) a second lane with the same lock hash copies the snapshot: deps hit, no install (#4909)", async () => {
+    const s = setup("npm");
+    const exdev = { ...fs, linkSync: () => { throw Object.assign(new Error("EXDEV: cross-device link"), { code: "EXDEV" }); } };
+    const c = makeDepCache({ root: s.root, exec: s.f.exec, env: {}, fs: exdev });
+    const [r1] = await c.prepare({ wt: s.lane("a"), repoKey: "r" });
+    assert.equal(r1.status, "miss-installed");
+    assert.equal(r1.published, true, "published by copy");
+    const installs = () => s.f.calls.filter((x) => x.cmd !== "git" && x.args[0] !== "--version").length;
+    const before = installs();
+    const wt2 = s.lane("b");
+    const [r2] = await c.prepare({ wt: wt2, repoKey: "r" });
+    assert.equal(r2.status, "hit");
+    assert.equal(installs(), before, "no install on the second lane");
+    assert.ok(existsSync(join(wt2, "node_modules/left-pad/index.js")));
+  });
+
   it("no lockfile, yarn Plug'n'Play, an existing node_modules and FORGE_DEPCACHE=0 are skipped untouched", async () => {
     const s = setup("npm");
     const empty = join(s.base, "empty"); mkdirSync(empty);

package/bin/lean/execution.mjs

@@ -79,6 +79,15 @@ export function isTransportError(e) {
   if (e.name === "AbortError" || e.name === "TimeoutError") return true;
   return /fetch failed|ECONNREFUSED|ECONNRESET|ETIMEDOUT|socket hang up|network error|timed? ?out/i.test(String(e.message ?? ""));
 }
+const CLONE_RE = /\bclone\b[^\n]*\b(time[ds]?\s?out|timeout|fail\w*|refused|reset|unreachable|early eof|could not)|\b(time[ds]?\s?out|timeout|fail\w*)\b[^\n]*\bclone\b/i;
+/** #4866: text of a sandbox clone failure (timeout, transport) as seen in an error or a lane result's detail. */
+export const isCloneFailure = (text) => CLONE_RE.test(String(text ?? ""));
+const CLONE_RETRY_S = 120;
+/** Outcome code of a retryable sandbox clone failure; local (not in OUTCOME_CODES), like the preflight codes in lanecheck.mjs. */
+export const SANDBOX_CLONE_CODE = "sandbox.clone";
+/** #4866: a sandbox clone failure is a retryable `deferred` `sandbox.clone`, never an engine-error (so the breaker never sees it). */
+const cloneDeferred = (id, detail) => ({ terminalReason: "deferred", code: SANDBOX_CLONE_CODE, retryInSeconds: CLONE_RETRY_S, detail: `sandbox ${id} could not clone the repo: ${detail}; retry in ${CLONE_RETRY_S}s` });
+const errLine = (t) => String(t ?? "").split("\n")[0].slice(0, 300);
 const errText = (e) => String(e?.stderr || e?.message || e).split("\n")[0].slice(0, 300);
 
 /**
@@ -115,10 +124,12 @@ export function parseExecution(sec = {}) {
   const patRaw = Array.isArray(s.host_capability_patterns) ? s.host_capability_patterns : str(s.host_capability_patterns) ? str(s.host_capability_patterns).split(",") : [];
   const hostCapabilityPatterns = patRaw.map((x) => { const t = str(x), i = t.indexOf(":"); return { name: t.slice(0, i).trim().toLowerCase(), pattern: t.slice(i + 1).trim() }; })
     .filter((x) => CAPABILITY_RE.test(x.name) && x.pattern && safeRegExp(x.pattern));
+  const wsN = Number(str(s.warm_sandboxes));
+  const warmSandboxes = str(s.warm_sandboxes) !== "" && Number.isInteger(wsN) && wsN > 0 ? wsN : 0; // #4912: warm sandboxes the pool agent keeps ready; 0 = off
   const relay = Object.fromEntries(Object.entries(parseRelayCommands(s.relay_commands)).filter(([c]) => CAPABILITY_RE.test(c))); // #4778
   const uw = Number(str(s.unreachable_window_min));
   const unreachableWindowMin = str(s.unreachable_window_min) !== "" && Number.isFinite(uw) && uw >= 0 ? uw : null; // unset: providerLanes defaults to 5
-  return { mode, maxRemote, provider, image, secrets, budget, ...(hostCapabilities.length ? { hostCapabilities } : {}), ...(hostCapabilityPatterns.length ? { hostCapabilityPatterns } : {}), ...(endpoint ? { endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(cacheStore ? { cacheStore } : {}), ...(allowActions ? { allowActions } : {}), ...(fallbackLocal ? { fallbackLocal } : {}), ...(heavy !== null ? { heavy } : {}), ...(unreachableWindowMin !== null ? { unreachableWindowMin } : {}), ...(Object.keys(relay).length ? { relay } : {}) };
+  return { mode, maxRemote, provider, image, secrets, budget, ...(hostCapabilities.length ? { hostCapabilities } : {}), ...(hostCapabilityPatterns.length ? { hostCapabilityPatterns } : {}), ...(endpoint ? { endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(cacheStore ? { cacheStore } : {}), ...(allowActions ? { allowActions } : {}), ...(fallbackLocal ? { fallbackLocal } : {}), ...(heavy !== null ? { heavy } : {}), ...(unreachableWindowMin !== null ? { unreachableWindowMin } : {}), ...(Object.keys(relay).length ? { relay } : {}), ...(warmSandboxes ? { warmSandboxes } : {}) };
 }
 
 const round1 = (x) => Math.round(x * 10) / 10;
@@ -525,7 +536,7 @@ export function providerByName(name, opts) {
  * returns that sandbox's ledger (ledger.mjs `makeLedger`).
  */
 export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env, secrets = [], pollMs = 5000, sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
-  costPerMinute = 0, now = () => Date.now(), unreachableWindowMs = 300000 }) {
+  costPerMinute = 0, now = () => Date.now(), unreachableWindowMs = 300000, logTail = null }) {
   const cpm = nonNeg(Number(costPerMinute)) ?? 0;
   // #4255: the sandbox's usage: the provider's `usage()`, else the billable minutes it put on the handle (#4254), else wall
   // clock since the handle's startedAt; cost is the provider's, else minutes x cost_per_minute.
@@ -560,6 +571,8 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
   };
   const unreachable = (h, e) => ({ terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_UNREACHABLE, retryInSeconds: 60,
     detail: `sandbox ${h.id} ${errText(e)}; kept for adopt on resume` });
+  const tailOf = async (h) => { try { return typeof logTail === "function" ? String(await logTail(h) ?? "") : ""; } catch { return ""; } };
+  const settleClone = (r, id) => (r?.terminalReason === "engine-error" && r.code === undefined && isCloneFailure(r.detail) ? cloneDeferred(id, errLine(r.detail)) : r);
   const wait = async (h, g = guard({ waited: 0, tries: 0 })) => {
     for (;;) {
       const r = await g(() => provider.fetchResult(h));
@@ -567,7 +580,9 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
       const st = await g(() => provider.status(h));
       if (st !== "running") {
         const last = await g(() => provider.fetchResult(h)); // it may have written the result just before exiting
-        return last ?? { terminalReason: "engine-error", detail: `sandbox ${h.id} ${st} without a result` };
+        if (last) return last;
+        const why = `sandbox ${h.id} ${st} without a result`;
+        return isCloneFailure(await tailOf(h)) ? cloneDeferred(h.id, why) : { terminalReason: "engine-error", detail: why };
       }
       await sleep(pollMs);
     }
@@ -578,6 +593,7 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
     ? { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_AUTH, retryInSeconds: 300, detail: `sandbox ${id} could not start (auth): ${errText(e)}; check the pool token (COMPUTESHARE_TOKEN or ~/.config/computeshare/forgedock.token)` }
     : e?.retryable === true
     ? { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_CAPACITY, detail: `sandbox ${id} could not start (capacity): ${errText(e)}`, ...(Number(e.retryInSeconds) > 0 ? { retryInSeconds: Number(e.retryInSeconds) } : {}) }
+    : isCloneFailure(errText(e)) ? cloneDeferred(id, errText(e))
     : { terminalReason: "needs-human", code: OUTCOME_CODES.SANDBOX_START_FAILED, detail: `sandbox ${id} failed to start: ${errText(e)}` });
   return {
     // #4612: a graceful stop of a live sandbox (the provider's checkpoint stop); false when it has none.
@@ -600,10 +616,10 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
         if (!Number.isFinite(h.startedAt)) h.startedAt = base.startedAt;
         started = true;
         ctx.onStart?.({ ...(Number.isInteger(h.pid) ? { pid: h.pid } : {}), handle: h, remote: true });
-        r = await wait(h);
+        r = settleClone(await wait(h), base.id);
       } catch (e) {
         if (started && e?.unreachable) return withUsage(unreachable(h, e), h); // #4672: no tear, the ledger keeps it
-        r = started ? { terminalReason: "engine-error", detail: `sandbox ${base.id}: ${errText(e)}` } : startFailed(base.id, e);
+        r = started ? settleClone({ terminalReason: "engine-error", detail: `sandbox ${base.id}: ${errText(e)}` }, base.id) : startFailed(base.id, e);
       }
       await tear(led, h); // every path, after the result is in (tear never throws)
       return started ? withUsage(r, h) : r; // a sandbox that never started used nothing

package/bin/lean/execution.test.mjs

@@ -7,7 +7,7 @@ import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
 import { renderContract } from "./render.mjs";
-import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placementText, contractHostNeeds, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, isTransportError, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
+import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placementText, contractHostNeeds, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, isTransportError, isCloneFailure, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
 import { makeLedger, countLiveLanes } from "./ledger.mjs";
 import { openBatch } from "./batch.mjs";
 import { orchestrate, formatTable, formatSandboxSummary } from "./orchestrate.mjs";
@@ -43,6 +43,10 @@ const NO_BUDGET = { batchMinutes: null, batchUsd: null, dayMinutes: null, dayUsd
 const ledgerIn = (root, { pid = process.pid, host = HOST } = {}) => (n) => makeLedger({ root, batch: "bt", lane: `sandbox-${n}`, owner: "orch_test", issue: n, host, pid });
 
 describe("execution config (#4253)", () => {
+  it("warm_sandboxes: positive integer kept, default 0 omitted (#4912)", () => {
+    assert.equal(parseExecution({ mode: "remote", warm_sandboxes: "2" }).warmSandboxes, 2);
+    for (const v of [undefined, "0", "-1", "x", "1.5"]) assert.ok(!("warmSandboxes" in parseExecution({ mode: "remote", ...(v === undefined ? {} : { warm_sandboxes: v }) })));
+  });
   it("pool is a known sandbox provider (#4546)", () => {
     assert.ok(SANDBOX_PROVIDERS.includes("pool"));
     assert.equal(parseExecution({ mode: "hybrid", max_remote: "1", provider: "pool" }).provider, "pool");
@@ -127,6 +131,8 @@ describe("providerLanes: an unreachable provider is retried, then deferred witho
   it("unreachable: classifies transport errors and parses the window key", () => {
     for (const e of [new TypeError("fetch failed"), Object.assign(new Error("x"), { code: "ECONNRESET" }), Object.assign(new Error("x"), { status: 502 }), Object.assign(new Error("x"), { name: "AbortError" })]) assert.equal(isTransportError(e), true);
     for (const e of [new Error("boom"), Object.assign(new Error("HTTP 404"), { status: 404 })]) assert.equal(isTransportError(e), false);
+    for (const t of ["fatal: git clone timed out after 300s", "git clone failed: early EOF"]) assert.equal(isCloneFailure(t), true); // #4866
+    for (const t of ["clone of repo ok", "", null]) assert.equal(isCloneFailure(t), false);
     assert.equal(parseExecution({}).unreachableWindowMin, undefined); // providerLanes defaults it to 5 min
     assert.equal(parseExecution({ unreachable_window_min: "2" }).unreachableWindowMin, 2);
   });

package/bin/lean/heavy.mjs

@@ -20,7 +20,7 @@
 import { spawn } from "node:child_process";
 import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync, appendFileSync, writeFileSync, chmodSync } from "node:fs";
 import { cpus, freemem } from "node:os";
-import { dirname, join } from "node:path";
+import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { writeAtomic } from "./batch.mjs";
 import { schedDir, pidAlive, DEFAULT_PRIORITY } from "./sched.mjs";
@@ -310,6 +310,27 @@ export function sumWaits(text, waits = {}) {
   return { waits, queueMax };
 }
 
+/**
+ * Admission-time form of the guardChain loop (#4866): every PATH dir holding a pass-through wrapper for a heavy-shimmed tool
+ * with no real binary behind it (so the wrapper's own `command -v` lands back on the shim). Returns [{name, dir}].
+ */
+export function findShimLoops(path, { names = HEAVY_BINS, find = which, read = head, skip = [] } = {}) {
+  const out = [];
+  const dirs = String(path ?? "").split(delimiter).filter(Boolean);
+  for (const name of names) {
+    const wrappers = [];
+    for (const d of dirs) {
+      if (skip.includes(d)) continue;
+      const f = find(name, d, []);
+      if (f && isPassThroughWrapper(read(f), name)) wrappers.push(d);
+    }
+    if (!wrappers.length) continue;
+    const real = find(name, path, [...skip, ...wrappers]);
+    if (!real) for (const dir of wrappers) out.push({ name, dir });
+  }
+  return out;
+}
+
 export const SHIM_LOOP_MAX = 4;
 /**
  * Re-entry guard (#4680): FORGE_HEAVY_CHAIN lists `name:cmd` per shim run. A repeat of the same name+cmd where cmd is a

package/bin/lean/lanecheck.mjs

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forge#4866: lane preflight. Host and environment faults (no pool token, a stale pool agent, a PATH wrapper that loops back
+ * to the heavy shim, a gh without a --json field the engine reads) used to surface inside lanes as 401s, fork loops or
+ * untyped engine-errors. Each check here returns `{code, ok, detail, scope}`; `scope` is "remote" (only remote lanes are held)
+ * or "all". The orchestrator holds admission while any check fails and re-checks each pass (never the breaker); `forgedock
+ * doctor --lanes` prints every check. Pure: all I/O is injected (`io`), so a fixed cause clears on the next call.
+ */
+import { readFileSync } from "node:fs";
+import { findShimLoops } from "./heavy.mjs";
+
+/** The running CLI's package version. */
+export const cliVersion = () => JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+export const UPGRADE_COMMAND = "npx forgedock pool upgrade";
+/** The `gh <cmd> --json` fields the engine reads (keep next to the call sites' lists in engine-cli.mjs and lean/*.mjs). */
+export const GH_FIELDS = Object.freeze({
+  "issue view": ["number", "title", "body", "state", "stateReason", "labels", "comments", "milestone", "author", "createdAt", "updatedAt"],
+  "pr view": ["number", "state", "mergeable", "mergeStateStatus"],
+  "repo view": ["nameWithOwner", "defaultBranchRef"],
+});
+const pass = (code, detail, scope) => ({ code, ok: true, detail, scope });
+const fail = (code, detail, scope) => ({ code, ok: false, detail, scope });
+/** Preflight codes. Local to this module, not in OUTCOME_CODES: they are admission holds that never reach a run's terminal outcome. */
+export const PREFLIGHT_CODES = Object.freeze({
+  PREFLIGHT_POOL_AUTH: "preflight.pool_auth", PREFLIGHT_POOL_VERSION: "preflight.pool_version",
+  PREFLIGHT_PATH_LOOP: "preflight.path_loop", PREFLIGHT_GH_FIELDS: "preflight.gh_fields",
+});
+const C = PREFLIGHT_CODES;
+
+/** A remote or hybrid execution is configured (the only case the pool checks apply to). */
+export const usesPool = (exec) => Boolean(exec) && (exec.mode === "remote" || exec.mode === "hybrid") && ["pool", "remote"].includes(exec.provider ?? "pool");
+
+/** The pool token resolves (env/keychain `token_env`, else the router's `forgedock_token_file`) and the router does not answer 401/403 to an authenticated ping. */
+export async function checkPoolAuth({ exec, router = null, credential = () => null, ping = null }) {
+  const code = C.PREFLIGHT_POOL_AUTH;
+  if (!usesPool(exec)) return pass(code, "skipped: no remote or hybrid execution", "remote");
+  const name = exec.tokenEnv ?? "COMPUTESHARE_TOKEN";
+  const fromEnv = credential(name);
+  const token = fromEnv || router?.token || null;
+  if (!token) return fail(code, `pool token does not resolve: tried env/keychain ${name}, ${router ? "the router's forgedock_token_file" : "no router config (COMPUTESHARE_CONFIG / ~/.config/computeshare/router.json)"}`, "remote");
+  const endpoint = exec.endpoint ?? router?.endpoint ?? null;
+  if (!endpoint || typeof ping !== "function") return pass(code, `token resolved from ${fromEnv ? name : "forgedock_token_file"}`, "remote");
+  let r = null;
+  try { r = await ping(endpoint, token); } catch { r = null; }
+  if ([401, 403].includes(r?.status)) return fail(code, `router ${endpoint} answered HTTP ${r.status} to the token from ${fromEnv ? name : "forgedock_token_file"}`, "remote");
+  return pass(code, `token resolved from ${fromEnv ? name : "forgedock_token_file"}${r ? "" : "; router unreachable (not an auth failure)"}`, "remote");
+}
+
+/** Every online pool agent runs the CLI's version. `agents` is the router's `GET /agents` list (each spreads versionOf: version, image). */
+export function checkPoolVersion({ exec, agents = null, cliVersion }) {
+  const code = C.PREFLIGHT_POOL_VERSION;
+  if (!usesPool(exec)) return pass(code, "skipped: no remote or hybrid execution", "remote");
+  if (!Array.isArray(agents)) return pass(code, "skipped: pool agents not readable", "remote");
+  const bad = agents.filter((a) => a?.ok !== false && typeof a?.version === "string" && a.version !== cliVersion);
+  if (!bad.length) return pass(code, `${agents.length} agent(s) at ${cliVersion}`, "remote");
+  return fail(code, bad.map((a) => `agent ${a.name ?? "?"} runs image version ${a.version}, CLI is ${cliVersion}`).join("; ") + `; upgrade: ${UPGRADE_COMMAND}`, "remote");
+}
+
+/** No PATH wrapper dir resolves a heavy-shimmed tool back to the shim. */
+export function checkPathLoop({ env = {}, loops = findShimLoops }) {
+  const code = C.PREFLIGHT_PATH_LOOP;
+  const skip = env.FORGE_HEAVY_SHIM_DIR ? [env.FORGE_HEAVY_SHIM_DIR] : [];
+  const found = loops(env.PATH ?? "", { skip });
+  if (!found.length) return pass(code, "no PATH wrapper loops back to the heavy shim", "all");
+  return fail(code, found.map((l) => `${l.dir} wraps ${l.name} and resolves back to the heavy shim`).join("; "), "all");
+}
+
+/** Parse the field names `gh <cmd> --json bogus` lists as available (null when the output has no list). */
+export function availableFields(text) {
+  const m = /Available fields:\s*([\s\S]*)$/i.exec(String(text ?? ""));
+  if (!m) return null;
+  const f = m[1].split(/\s+/).map((x) => x.trim()).filter((x) => /^[A-Za-z]\w*$/.test(x));
+  return f.length ? f : null;
+}
+
+/** The installed gh offers every `--json` field the engine uses; `exec(args) -> {stdout, stderr}`. An unreadable gh passes (not this check's fault). */
+export async function checkGhFields({ exec, fields = GH_FIELDS }) {
+  const code = C.PREFLIGHT_GH_FIELDS;
+  let version = "unknown";
+  try { version = /gh version (\S+)/.exec(String((await exec(["--version"]))?.stdout ?? ""))?.[1] ?? "unknown"; } catch { return pass(code, "skipped: gh not runnable", "all"); }
+  const probes = await Promise.all(Object.entries(fields).map(async ([cmd, want]) => {
+    try { return [want, cmd, await exec([...cmd.split(" "), "--json", "forgedock_probe"])]; } catch { return null; }
+  }));
+  const missing = [];
+  for (const pr of probes) {
+    if (!pr) continue;
+    const [want, cmd, r] = pr;
+    const have = availableFields(`${r?.stderr ?? ""}\n${r?.stdout ?? ""}`);
+    if (!have) continue;
+    for (const f of want) if (!have.includes(f)) missing.push(`${f} (gh ${cmd} --json)`);
+  }
+  return missing.length ? fail(code, `gh ${version} lacks --json field ${missing.join(", ")}`, "all") : pass(code, `gh ${version} has every --json field the engine uses`, "all");
+}
+
+/** Run every check; never throws (a check that throws passes with the error as its detail). */
+export async function runLaneChecks({ exec = null, env = process.env, cliVersion: cliV = cliVersion(), io = {} } = {}) {
+  const safe = async (code, scope, fn) => { try { return await fn(); } catch (e) { return pass(code, `check errored: ${String(e?.message ?? e).split("\n")[0]}`, scope); } };
+  let router = null;
+  try { router = io.router?.() ?? null; } catch { router = null; }
+  const ping = io.ping ?? null;
+  const agentsOf = async () => { try { return (await io.agents?.(exec?.endpoint ?? router?.endpoint, exec?.tokenEnv ? (io.credential?.(exec.tokenEnv) ?? router?.token) : router?.token)) ?? null; } catch { return null; } };
+  return Promise.all([
+    safe(C.PREFLIGHT_POOL_AUTH, "remote", () => checkPoolAuth({ exec, router, credential: io.credential, ping })),
+    safe(C.PREFLIGHT_POOL_VERSION, "remote", async () => checkPoolVersion({ exec, agents: usesPool(exec) ? await agentsOf() : null, cliVersion: cliV })),
+    safe(C.PREFLIGHT_PATH_LOOP, "all", () => checkPathLoop({ env: { ...env, PATH: env.PATH ?? "" }, ...(io.loops ? { loops: io.loops } : {}) })),
+    safe(C.PREFLIGHT_GH_FIELDS, "all", () => (io.ghExec ? checkGhFields({ exec: io.ghExec }) : pass(C.PREFLIGHT_GH_FIELDS, "skipped: no gh", "all"))),
+  ]);
+}
+
+/** One line per check: `PASS|FAIL code  detail`. */
+export const formatLaneChecks = (checks) => checks.map((c) => `${c.ok ? "PASS" : "FAIL"} ${c.code}  ${c.detail}`).join("\n");
+
+/** Real-host io for the daemon, the batch and `doctor --lanes`. gh output is cached per process (it cannot change under a running engine). */
+export async function hostLaneIo({ env = process.env } = {}) {
+  const { poolRouterConfig } = await import("./execution.mjs");
+  const { resolveCredential } = await import("./credentials.mjs");
+  const { execFile } = await import("node:child_process");
+  const call = (url, token, timeoutMs = 5000) => fetch(url, { headers: token ? { authorization: `Bearer ${token}` } : {}, signal: AbortSignal.timeout(timeoutMs) });
+  const run = (args) => new Promise((res, rej) => execFile("gh", args, { timeout: 15000, env }, (e, stdout, stderr) => (e && e.code === "ENOENT" ? rej(e) : res({ stdout, stderr }))));
+  const memo = new Map();
+  return {
+    router: () => poolRouterConfig({ env }),
+    credential: (n) => resolveCredential(n, { env }),
+    ping: async (endpoint, token) => ({ status: (await call(`${endpoint}/status`, token)).status }),
+    agents: async (endpoint, token) => { const r = await call(`${endpoint}/agents`, token); return r.ok ? (await r.json())?.agents ?? null : null; },
+    ghExec: (args) => { const k = args.join(" "); if (!memo.has(k)) memo.set(k, run(args)); return memo.get(k); },
+  };
+}