forgedock 1.35.0 → 1.37.0

package/bin/lean/execution.mjs

@@ -62,6 +62,16 @@ const safeRegExp = (src) => { try { return new RegExp(src, "i"); } catch { retur
 const ENV_RE = /^[A-Z_][A-Z0-9_]*$/;
 const IMAGE_RE = /^[A-Za-z0-9][A-Za-z0-9._\/:@-]*$/;
 const readJson = (file) => { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } };
+const TRANSPORT_CODES = new Set(["ECONNREFUSED", "ECONNRESET", "ETIMEDOUT", "EAI_AGAIN", "EPIPE", "ENOTFOUND", "EHOSTUNREACH", "ENETUNREACH", "UND_ERR_SOCKET", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT"]);
+/** #4672: a failure of the link to the provider (connection refused/reset, `fetch failed`, timeout, 502/503/504), not of the lane. */
+export function isTransportError(e) {
+  if (!e || e.unreachable) return false;
+  if (e.transient === true || [502, 503, 504].includes(e.status)) return true;
+  const code = e.code ?? e.cause?.code;
+  if (TRANSPORT_CODES.has(code)) return true;
+  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 errText = (e) => String(e?.stderr || e?.message || e).split("\n")[0].slice(0, 300);
 
 /**
@@ -98,7 +108,9 @@ 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));
-  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 } : {}) };
+  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 } : {}) };
 }
 
 const round1 = (x) => Math.round(x * 10) / 10;
@@ -429,7 +441,8 @@ export function providerByName(name, opts) {
     try { forgeYaml = opts?.cwd ? readFileSync(join(opts.cwd, "forge.yaml"), "utf8") : null; } catch { forgeYaml = null; }
     // The router's token is resolved under a fixed name so remoteProvider redacts it like any `token_env` credential.
     const tokenEnv = exec.tokenEnv ?? (router?.token ? "FORGEDOCK_POOL_TOKEN" : undefined);
-    const credentials = (n) => (n === "FORGEDOCK_POOL_TOKEN" && !exec.tokenEnv ? router?.token ?? null : resolveCredential(n, { env }));
+    // #4685: an empty env/keychain lookup of a configured token_env falls back to the router's token file.
+    const credentials = (n) => (n === "FORGEDOCK_POOL_TOKEN" && !exec.tokenEnv ? router?.token ?? null : resolveCredential(n, { env }) ?? router?.token ?? null);
     const settings = { ...exec, ...(exec.endpoint ? {} : router ? { endpoint: router.endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(forgeYaml ? { forgeYaml } : {}) };
     return remoteProvider({ batch: opts.batch, repo: opts.repo, settings, name: "pool", env, credentials, transport: remoteTransportFor(settings, { transport: opts?.transport, env, credentials }), ...(opts?.now ? { now: opts.now } : {}) });
   }
@@ -443,7 +456,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() }) {
+  costPerMinute = 0, now = () => Date.now(), unreachableWindowMs = 300000 }) {
   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.
@@ -463,29 +476,53 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
     if (ok) { try { led?.release("sandbox", h.id); led?.remove(); } catch { /* the reaper retries */ } }
     return ok;
   };
-  const wait = async (h) => {
+  // #4672: a transport failure (router restart, refused/reset connection, 502/503/504) is retried with backoff until the lane has
+  // waited `unreachableWindowMs` in a row without one successful poll; then it ends sandbox.unreachable with the sandbox kept.
+  const guard = (st) => async (fn) => {
+    for (;;) {
+      try { const v = await fn(); st.waited = 0; st.tries = 0; return v; } catch (e) {
+        if (!isTransportError(e)) throw e;
+        if (st.waited >= unreachableWindowMs) throw Object.assign(new Error(`unreachable for ${Math.round(st.waited / 1000)}s: ${errText(e)}`), { unreachable: true });
+        const d = Math.min(pollMs * 2 ** Math.min(st.tries++, 10), 30000, Math.max(1, unreachableWindowMs - st.waited));
+        st.waited += d;
+        await sleep(d);
+      }
+    }
+  };
+  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 wait = async (h, g = guard({ waited: 0, tries: 0 })) => {
     for (;;) {
-      const r = await provider.fetchResult(h);
+      const r = await g(() => provider.fetchResult(h));
       if (r) return r;
-      const st = await provider.status(h);
+      const st = await g(() => provider.status(h));
       if (st !== "running") {
-        const last = await provider.fetchResult(h); // it may have written the result just before exiting
+        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` };
       }
       await sleep(pollMs);
     }
   };
   // A start failure repeats on a relaunch: typed, never engine-error (#4254). Retryable (capacity) defers with backoff.
-  const startFailed = (id, e) => (e?.retryable === true
+  // #4685: a refused or missing credential defers with its own code (a fixed token is picked up on the retry), never needs-human.
+  const startFailed = (id, e) => ([401, 403].includes(e?.status)
+    ? { 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) } : {}) }
     : { 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.
+    stopLane: async (n, rec) => (typeof provider.stop === "function" && rec?.handle ? (await provider.stop(rec.handle)) === true : false),
     runOne: async (n, lane, ctx = {}) => {
       const led = ledgerFor(n);
       const base = { provider: provider.name, id: provider.idFor(n), issue: n, startedAt: now() };
       // A sandbox an earlier attempt left behind (same id) goes first, or the new one could not start.
-      if ((led?.entries("sandbox") ?? []).some((e) => e.value === base.id) && !(await tear(led, base))) {
-        return { terminalReason: "engine-error", detail: `sandbox ${base.id} from an earlier attempt could not be torn down` };
+      const left = (led?.entries("sandbox") ?? []).find((e) => e.value === base.id);
+      if (left) {
+        // #4672: a sandbox kept as unreachable is adopted when the provider answers again; it is torn down only when it is gone.
+        const kept = await adoptLeft(n, left, ctx);
+        if (kept) return kept;
+        if (!(await tear(led, base))) return { terminalReason: "engine-error", detail: `sandbox ${base.id} from an earlier attempt could not be torn down` };
       }
       led?.register("sandbox", base.id, { provider: provider.name, handle: base }); // before it exists
       let h = base, r, started = false;
@@ -496,12 +533,15 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
         ctx.onStart?.({ ...(Number.isInteger(h.pid) ? { pid: h.pid } : {}), handle: h, remote: true });
         r = await wait(h);
       } 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);
       }
       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
     },
-    adopt: async (n, rec, ctx = {}) => {
+    adopt: (n, rec, ctx = {}) => adoptSaved(n, rec, ctx),
+  };
+  async function adoptSaved(n, rec, ctx = {}) {
       const saved = rec?.handle;
       if (!saved?.id || saved.provider !== provider.name) return null;
       // Usage runs from the sandbox's real start (persisted on the handle), not from this adopt.
@@ -509,15 +549,21 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
       const led = ledgerFor(n);
       led?.register("sandbox", h.id, { provider: provider.name, handle: { provider: h.provider, id: h.id, issue: h.issue, ...(Number.isFinite(h.startedAt) ? { startedAt: h.startedAt } : {}) } }); // now owned by this dispatcher
       let r;
+      const g = guard({ waited: 0, tries: 0 });
       try {
-        const ended = await provider.fetchResult(h);
-        if (!ended && (await provider.status(h)) !== "running") r = null; // relaunched
-        else { if (!ended) ctx.onLive?.(); r = await wait(h); } // #4504: a live sandbox is awaited in the background
+        const ended = await g(() => provider.fetchResult(h));
+        if (!ended && (await g(() => provider.status(h))) !== "running") r = null; // relaunched
+        else { if (!ended) ctx.onLive?.(); r = await wait(h, g); } // #4504: a live sandbox is awaited in the background
       } catch (e) {
+        if (e?.unreachable) return withUsage(unreachable(h, e), h); // #4672: same tolerance; no tear, left for the next adopt
         r = { terminalReason: "engine-error", detail: `sandbox ${h.id}: ${errText(e)}` };
       }
       await tear(led, h);
       return withUsage(r, h);
-    },
-  };
+  }
+  // A leftover ledger entry of this lane's sandbox: its result if it can still be had, else null (torn down by the caller).
+  async function adoptLeft(n, left, ctx) {
+    const r = await adoptSaved(n, { handle: left.handle }, ctx).catch(() => null);
+    return r ?? null;
+  }
 }

package/bin/lean/execution.test.mjs

@@ -6,7 +6,7 @@ import assert from "node:assert/strict";
 import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
+import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, isTransportError, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
 import { makeLedger, countLiveLanes } from "./ledger.mjs";
 import { openBatch } from "./batch.mjs";
 import { orchestrate, formatTable, formatSandboxSummary } from "./orchestrate.mjs";
@@ -24,7 +24,7 @@ function fakeProvider(opts = {}) {
     async start({ issue, env, secrets }) {
       p.calls.push(["start", issue]);
       p.ledgerAtStart = opts.ledger?.entries("sandbox").map((e) => e.value) ?? null;
-      if (opts.startThrows) throw new Error("boom: no capacity");
+      if (opts.startThrows) throw Object.assign(new Error("boom: no capacity"), opts.startThrows === 401 ? { status: 401 } : {});
       p.live.add(issue);
       p.env = env; p.secrets = secrets;
       if (opts.finish) { const r = opts.finish(issue); if (r !== undefined) { p.results[issue] = r; p.live.delete(issue); } }
@@ -81,6 +81,56 @@ describe("execution config (#4253)", () => {
   });
 });
 
+describe("providerLanes: an unreachable provider is retried, then deferred without teardown (#4672)", () => {
+  const flaky = (failPolls) => {
+    const prov = fakeProvider(); let polls = 0;
+    prov.live.add(7);
+    const gate = () => { if (polls++ < failPolls) throw Object.assign(new TypeError("fetch failed"), { cause: { code: "ECONNREFUSED" } }); };
+    prov.fetchResult = async (h) => { gate(); return prov.results[h.issue] ?? null; };
+    prov.status = async (h) => { gate(); prov.calls.push(["status", h.issue]); return prov.live.has(h.issue) ? "running" : "exited"; };
+    return prov;
+  };
+  const lanes = (prov, extra = {}) => { const root = tmpDir("exec-unreach-"); const ledgerFor = ledgerIn(root); const slept = [];
+    return { slept, ledgerFor, l: providerLanes({ provider: prov, laneArgs: () => [], ledgerFor, pollMs: 1000, now: () => 1000, sleep: async (ms) => { slept.push(ms); if (slept.length === 6) { prov.results[7] = { terminalReason: "merged", pr: 9 }; prov.live.delete(7); } }, ...extra }) }; };
+
+  it("unreachable: N failed polls then recovery yields the real result", async () => {
+    const prov = flaky(3); prov.start = async () => ({ provider: "fake", id: "fake-7", issue: 7 });
+    const { l, slept } = lanes(prov);
+    const r = await l.runOne(7, "staging");
+    assert.equal(r.terminalReason, "merged");
+    assert.ok(slept.length >= 3 && slept[1] > slept[0]); // backoff
+    assert.equal(prov.calls.filter((c) => c[0] === "teardown").length, 1); // only after the result
+  });
+
+  it("unreachable: down past the window yields sandbox.unreachable, no teardown, ledger kept", async () => {
+    const prov = flaky(1e9); prov.start = async () => ({ provider: "fake", id: "fake-7", issue: 7 });
+    const { l, ledgerFor } = lanes(prov, { unreachableWindowMs: 5000 });
+    const r = await l.runOne(7, "staging");
+    assert.deepEqual([r.terminalReason, r.code], ["deferred", "sandbox.unreachable"]);
+    assert.equal(prov.calls.some((c) => c[0] === "teardown"), false);
+    assert.deepEqual(ledgerFor(7).entries("sandbox").map((e) => e.value), ["fake-7"]);
+  });
+
+  it("unreachable: adopt applies the same tolerance, and a non-transport error is still engine-error", async () => {
+    const down = flaky(1e9);
+    const { l } = lanes(down, { unreachableWindowMs: 3000 });
+    const r = await l.adopt(7, { handle: { provider: "fake", id: "fake-7", issue: 7 } });
+    assert.equal(r.code, "sandbox.unreachable");
+    assert.equal(down.calls.some((c) => c[0] === "teardown"), false);
+    const ok = flaky(2); ok.results[7] = { terminalReason: "merged", pr: 1 };
+    assert.equal((await lanes(ok).l.adopt(7, { handle: { provider: "fake", id: "fake-7", issue: 7 } })).terminalReason, "merged");
+    const bad = fakeProvider(); bad.fetchResult = async () => { throw new Error("boom"); };
+    assert.equal((await lanes(bad).l.adopt(7, { handle: { provider: "fake", id: "fake-7", issue: 7 } })).terminalReason, "engine-error");
+  });
+
+  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);
+    assert.equal(parseExecution({}).unreachableWindowMin, undefined); // providerLanes defaults it to 5 min
+    assert.equal(parseExecution({ unreachable_window_min: "2" }).unreachableWindowMin, 2);
+  });
+});
+
 describe("providerLanes: sandbox ledger and teardown on every exit path (#4253)", () => {
   const run = async ({ finish, startThrows, teardownOk, pollMs = 1 } = {}) => {
     const root = tmpDir("exec-ledger-");
@@ -118,6 +168,13 @@ describe("providerLanes: sandbox ledger and teardown on every exit path (#4253)"
     assert.equal(led.read(), null);
   });
 
+  it("#4685 start refused with HTTP 401: deferred sandbox.auth with a long retry, never needs-human", async () => {
+    const { r } = await run({ startThrows: 401 });
+    assert.equal(r.terminalReason, "deferred");
+    assert.equal(r.code, "sandbox.auth");
+    assert.equal(r.retryInSeconds, 300);
+  });
+
   it("start throws: typed needs-human sandbox.start_failed row (#4254), teardown still runs", async () => {
     const { r, prov, led } = await run({ startThrows: true });
     assert.equal(r.terminalReason, "needs-human");

package/bin/lean/gatewatch.mjs

@@ -0,0 +1,31 @@
+/**
+ * forge#4656: ship-gate watchdog. A gate (a settle pass, a hold list, `/milestone ship` pre-flight) that waits on an issue the
+ * scheduler will not admit never resolves; this pure module names those waits so the batch reports `GATE_DEADLOCK` within one pass
+ * instead of polling silently. No I/O.
+ */
+
+/**
+ * `gates`: [{ name, waitsOn: [issue...], since?: ms }]; `admissible(n)`: true when the scheduler could still run or finish `n`;
+ * `now`: ms. Returns one { issue, gate, ageMs } per (gate, issue) wait that cannot resolve, in gate order.
+ */
+export function detectGateDeadlock({ gates, admissible, now = Date.now(), firstSeen = null }) {
+  const out = [];
+  for (const g of Array.isArray(gates) ? gates : []) {
+    for (const n of Array.isArray(g?.waitsOn) ? g.waitsOn : []) {
+      let ok = true;
+      try { ok = admissible(n) !== false; } catch { ok = true; }
+      if (ok) continue;
+      const key = `${g.name}#${n}`;
+      if (firstSeen && !firstSeen.has(key)) firstSeen.set(key, Number.isFinite(g.since) ? g.since : now);
+      const since = firstSeen?.get(key) ?? (Number.isFinite(g.since) ? g.since : now);
+      out.push({ issue: n, gate: String(g.name), ageMs: Math.max(0, now - since) });
+    }
+  }
+  return out;
+}
+
+/** One `pipeline-status` line: `GATE_DEADLOCK issue=#N gate=G age=12m`. */
+export function formatGateDeadlock(d) {
+  const m = Math.round((Number(d.ageMs) || 0) / 60000);
+  return `GATE_DEADLOCK issue=#${d.issue} gate=${d.gate} age=${m}m`;
+}

package/bin/lean/gatewatch.test.mjs

@@ -0,0 +1,59 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { detectGateDeadlock, formatGateDeadlock } from "./gatewatch.mjs";
+import { orchestrate } from "./orchestrate.mjs";
+import { classifyNeedsHuman, classifyLegacyNeedsHuman, parkedLabel } from "../engine/outcome-codes.mjs";
+
+describe("#4656 gate watchdog", () => {
+  it("a milestone ship gate waiting on a parked issue yields GATE_DEADLOCK with issue, gate and age", () => {
+    const firstSeen = new Map([["ship#7", 0]]);
+    const d = detectGateDeadlock({ gates: [{ name: "ship", waitsOn: [7, 8] }], admissible: (n) => n !== 7, now: 120000, firstSeen });
+    assert.deepEqual(d, [{ issue: 7, gate: "ship", ageMs: 120000 }]);
+    assert.equal(formatGateDeadlock(d[0]), "GATE_DEADLOCK issue=#7 gate=ship age=2m");
+  });
+  it("an admissible wait is not a deadlock", () => {
+    assert.deepEqual(detectGateDeadlock({ gates: [{ name: "ship", waitsOn: [8] }], admissible: () => true }), []);
+  });
+  it("the batch runner reports GATE_DEADLOCK once per (gate, issue) for a parked issue on the gate, instead of waiting", async () => {
+    const rows = [], decisions = [];
+    const runOne = async (n) => n === 1
+      ? { terminalReason: "needs-human", code: "conformance.unimplemented", detail: "unknown requirement", pr: 9 }
+      : { terminalReason: "merged", pr: 10 };
+    const _unused = async (n) => n === 1
+      ? { terminalReason: "needs-human", code: "ci.red", detail: "lint failed", pr: 9 }
+      : { terminalReason: "merged", pr: 10 };
+    const relabels = [];
+    const res = await orchestrate({ issues: [1, 2], parallel: 1, runOne, readBody: async () => "", onUpdate: (r) => rows.push(r), decide: (d) => decisions.push(d),
+      getGates: () => [{ name: "ship", waitsOn: [1] }], recovery: { maxAttempts: 1 }, relabelNeedsHuman: async (a) => { relabels.push(a); return true; }, pollMs: 1, sleep: async () => {} });
+    const dl = rows.filter((r) => r.outcome === "GATE_DEADLOCK");
+    assert.equal(dl.length, 1);
+    assert.match(dl[0].detail, /GATE_DEADLOCK issue=#1 gate=ship/);
+    assert.ok(Array.isArray(res));
+    assert.deepEqual(relabels.map((r) => r.parked?.code), ["conformance.unimplemented"]);
+  });
+});
+
+describe("#4656 parked class and migration", () => {
+  it("parked is opt-in and leaves the default classes untouched", () => {
+    const row = { outcome: "needs-human", code: "conformance.unimplemented" };
+    assert.equal(classifyNeedsHuman(row), "terminal");
+    assert.equal(classifyNeedsHuman(row, { parked: true }), "parked");
+    assert.equal(classifyNeedsHuman({ outcome: "needs-human", code: "builder.blocked" }, { parked: true }), "human");
+    assert.equal(classifyNeedsHuman({ outcome: "needs-human", code: "ci.red" }, { parked: true }), "recoverable");
+    assert.equal(classifyNeedsHuman({ outcome: "needs-human" }, { parked: true }), "terminal");
+  });
+  it("legacy needs-human classifies from the terminal annotation and defaults to external", () => {
+    assert.deepEqual(classifyLegacyNeedsHuman("terminal: ci.red after final round"), { kind: "parked", code: "ci.red" });
+    assert.deepEqual(classifyLegacyNeedsHuman("waiting for the AWS account"), { kind: "external" });
+    assert.deepEqual(classifyLegacyNeedsHuman(null), { kind: "external" });
+    assert.equal(parkedLabel("ci.red"), "parked:ci.red");
+  });
+});
+
+describe("#4656 report routing", () => {
+  it("a parked row past recovery is listed on the remediation queue line, not unrecovered or escalations", async () => {
+    const { formatOutcomeLists } = await import("./orchestrate.mjs");
+    const lines = formatOutcomeLists([{ issue: 1, outcome: "needs-human", code: "conformance.unimplemented", pr: 9, parkedQueued: true }]);
+    assert.deepEqual(lines, ["remediation queue (/work-on:remediate): #1 (parked:conformance.unimplemented PR #9)"]);
+  });
+});

package/bin/lean/guardgate.mjs

@@ -0,0 +1,170 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Guard gate (#4693): execution-based, no pattern matching on diff text. A lane whose diff changes lines a merged fix
+ * protected (git blame on the lane's merge base names the guard's merge commit, or a later commit that kept the lines), or
+ * edits/deletes a guard's test file, reruns that guard's test files *as they exist on base* against the lane's tree. A
+ * failure is `conformance.guard_broken` (builder resumed once). The only override is a `supersedes` amendment (conformance.mjs).
+ * Deterministic, 0 LLM calls; a lane touching nothing guarded does one local index read and no git work.
+ */
+import * as nodeFs from "node:fs";
+import { dirname, extname, join } from "node:path";
+import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
+import { collectGuards, guardsIndexPath, readIndex, writeIndex } from "./guards.mjs";
+import { isTestPath } from "./enumerating.mjs";
+
+export const GUARD_CAP_MS = 120000;
+export const INDEX_MAX_AGE_MS = 6 * 3600000;
+const TIMEOUT_RC = 124;
+const SLACK = 10; // lines a guarded hunk may have drifted since its merge when only a later commit kept it
+const SHA_RE = /^[0-9a-f]{40}$/;
+const ok = async (fn) => { try { await fn(); return true; } catch { return false; } };
+const norm = (p) => String(p ?? "").replace(/^\.\//, "");
+
+/** Guards from the local index; rebuilt from the GitHub register when absent or older than INDEX_MAX_AGE_MS (a stale index is still used when GitHub is unreachable). */
+export async function loadGuards({ repo, gh, root, fs = nodeFs, now = Date.now() }) {
+  const cached = readIndex(repo, { root, fs });
+  let age = Infinity;
+  try { age = now - fs.statSync(guardsIndexPath(repo, root)).mtimeMs; } catch { /* no index yet */ }
+  if (cached && age < INDEX_MAX_AGE_MS) return cached;
+  try { const g = await collectGuards({ gh, repo }); writeIndex(repo, g, { root, fs }); return g; } catch { return cached ?? []; }
+}
+
+/** Old-side line ranges of a `git diff -U0` text for non-test files: {file: [[start, end]]}. Pure insertions touch no old line. */
+export function oldRanges(diff) {
+  const out = {};
+  let file = null;
+  for (const line of String(diff ?? "").split("\n")) {
+    if (line.startsWith("--- ")) { file = line === "--- /dev/null" ? null : line.replace(/^--- a\//, ""); continue; }
+    if (line.startsWith("+++ ")) { if (line === "+++ /dev/null") continue; continue; }
+    const m = /^@@ -(\d+)(?:,(\d+))? \+/.exec(line);
+    if (!m || !file || isTestPath(file)) continue;
+    const start = Number(m[1]), len = m[2] === undefined ? 1 : Number(m[2]);
+    if (len > 0) (out[file] ??= []).push([start, start + len - 1]);
+  }
+  return out;
+}
+
+/** Commit shas that last touched lines a..b of `file` at `rev` (git blame --porcelain). */
+export function blameShas(text) {
+  const shas = new Set();
+  for (const l of String(text ?? "").split("\n")) { const s = l.split(" ")[0]; if (SHA_RE.test(s)) shas.add(s); }
+  return shas;
+}
+
+/**
+ * The guards a lane's diff intersects, each with why it was selected: {guard, reason}. `files` are the lane's changed paths.
+ * Guards whose hunk files and test files the lane does not touch are never looked at (no git calls).
+ */
+export async function selectGuards({ guards, files, git, base }) {
+  const changed = new Set((files ?? []).map(norm));
+  const cands = (guards ?? []).filter((g) => (g.hunks ?? []).some((h) => changed.has(norm(h.file))) || (g.tests ?? []).some((t) => changed.has(norm(t.path))));
+  if (!cands.length) return { selected: [], mergeBase: null };
+  const mergeBase = String(await git(["merge-base", base, "HEAD"])).trim();
+  const hunkFiles = [...new Set(cands.flatMap((g) => (g.hunks ?? []).map((h) => norm(h.file))).filter((f) => changed.has(f)))];
+  const ranges = hunkFiles.length ? oldRanges(String(await git(["diff", "-U0", "--no-renames", `${base}...HEAD`, "--", ...hunkFiles]))) : {};
+  const blamed = new Map(); // `${file}:${a}-${b}` -> Set(sha)
+  const shasOf = async (file, [a, b]) => {
+    const k = `${file}:${a}-${b}`;
+    if (!blamed.has(k)) blamed.set(k, blameShas(await git(["blame", "--porcelain", "-L", `${a},${b}`, mergeBase, "--", file]).catch(() => "")));
+    return blamed.get(k);
+  };
+  const selected = [];
+  for (const g of cands) {
+    const sha = String(g.merge_sha ?? "");
+    const known = SHA_RE.test(sha) || sha.length >= 7 ? await ok(() => git(["cat-file", "-e", `${sha}^{commit}`])) : false;
+    let reason = null;
+    for (const h of g.hunks ?? []) {
+      const f = norm(h.file);
+      for (const r of ranges[f] ?? []) {
+        const near = r[0] <= h.end + SLACK && r[1] >= h.start - SLACK;
+        if (!known) { if (near) reason = `lines ${r[0]}-${r[1]} of ${f} overlap the protected hunk (merge commit not local)`; }
+        else if (near) {
+          for (const s of await shasOf(f, r)) {
+            if (s === sha || (s.startsWith(sha) && sha.length >= 7) || sha.startsWith(s) || await ok(() => git(["merge-base", "--is-ancestor", sha, s]))) { reason = `lines ${r[0]}-${r[1]} of ${f} last changed by ${s.slice(0, 10)}, which carries the fix`; break; }
+          }
+        }
+        if (reason) break;
+      }
+      if (reason) break;
+    }
+    if (!reason) { const t = (g.tests ?? []).find((x) => changed.has(norm(x.path))); if (t) reason = `the lane edits or deletes its test ${t.path}`; }
+    if (reason) selected.push({ guard: g, reason });
+  }
+  return { selected, mergeBase };
+}
+
+/** The command that runs one test file: the contract's own validate command with that path substituted, else a per-extension default; null when unknown. */
+export function commandFor(path, contract) {
+  const ext = extname(path);
+  for (const v of contract?.validate ?? []) {
+    const cmd = String(v?.command ?? "");
+    if (/(?:^|\s)(?:-k|-t|--grep|--test-name-pattern|--testNamePattern)(?:\s|=)|::/.test(cmd)) continue;
+    const toks = cmd.match(/[^\s"']+/g) ?? [];
+    const tests = toks.filter((t) => extname(t) === ext && isTestPath(t));
+    if (tests.length === 1 && /\b(?:node|pytest|python3?|vitest|jest|npx|pnpm|npm|yarn|bun)\b/.test(cmd)) return cmd.replace(tests[0], path);
+  }
+  if ([".mjs", ".cjs", ".js"].includes(ext)) return `node --test ${path}`;
+  if (ext === ".py") return `python -m pytest -q ${path}`;
+  return null;
+}
+
+/** Sibling path for the base copy of a test file, so its relative imports resolve against the lane's tree. */
+export const basePathOf = (path) => { const e = extname(path); return `${path.slice(0, path.length - e.length)}__guardbase${e}`; };
+
+const tailOf = (out) => String(out ?? "").split("\n").filter((l) => l.trim()).slice(-40).join("\n").slice(-1500);
+
+/**
+ * Rerun the selected guards' base test files against the lane tree, in a small pool, under one wall-time cap.
+ * Returns {failures, runs, skipped[], ms}. A test that cannot be run (no base copy, unknown runner, over the cap) is skipped, never a failure.
+ */
+export async function runGuards({ selected, mergeBase, contract, git, runCommand, cwd, env, capMs = GUARD_CAP_MS, parallelism = 2, fs = nodeFs, now = Date.now }) {
+  const t0 = now(), skipped = [], runs = [], jobs = [];
+  for (const { guard } of selected) {
+    for (const t of guard.tests ?? []) {
+      const path = norm(t.path), copy = basePathOf(path), command = commandFor(copy, contract);
+      if (!command) { skipped.push(`#${guard.issue} ${path}: no runner known for ${extname(path) || "this file"}`); continue; }
+      jobs.push({ guard, path, copy, command });
+    }
+  }
+  const made = [];
+  try {
+    const queue = jobs.slice();
+    const work = async () => {
+      for (let j = queue.shift(); j; j = queue.shift()) {
+        const left = capMs - (now() - t0);
+        if (left <= 0) { skipped.push(`#${j.guard.issue} ${j.path}: over the ${Math.round(capMs / 1000)}s guard cap`); continue; }
+        let body;
+        try { body = await git(["show", `${mergeBase}:${j.path}`]); } catch { skipped.push(`#${j.guard.issue} ${j.path}: not on base`); continue; }
+        const abs = join(cwd, j.copy);
+        try { fs.mkdirSync(dirname(abs), { recursive: true }); fs.writeFileSync(abs, body); made.push(abs); } catch (e) { skipped.push(`#${j.guard.issue} ${j.path}: ${String(e?.message ?? e).slice(0, 80)}`); continue; }
+        let r;
+        try { r = await runCommand({ command: j.command, cwd, timeoutMs: left, env }); } catch (e) { r = { rc: 127, output: String(e?.message ?? e) }; }
+        if (r?.rc === TIMEOUT_RC) { skipped.push(`#${j.guard.issue} ${j.path}: over the ${Math.round(capMs / 1000)}s guard cap`); continue; }
+        if (r?.rc === 127) { skipped.push(`#${j.guard.issue} ${j.path}: runner unavailable`); continue; }
+        runs.push({ issue: j.guard.issue, why: j.guard.why, test: j.path, command: j.command, rc: Number.isInteger(r?.rc) ? r.rc : 1, output: String(r?.output ?? "") });
+      }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(parallelism, jobs.length)) }, work));
+  } finally {
+    for (const p of made) { try { fs.rmSync(p, { force: true }); } catch { /* best effort */ } }
+  }
+  return { failures: guardFailures(runs), runs, skipped, ms: now() - t0 };
+}
+
+/** conformance.guard_broken rows (one per failing guard test): the guard's issue, its one-line why, the failing test and its output tail. */
+export function guardFailures(runs) {
+  return (runs ?? []).filter((r) => r.rc !== 0).map((r) => ({
+    code: OUTCOME_CODES.CONFORMANCE_GUARD_BROKEN, kind: "guard_broken", guard: `#${r.issue}`, test: r.test,
+    detail: `guard #${r.issue} broken (${String(r.why ?? "").slice(0, 200)}): base test ${r.test} fails against your tree (\`${r.command}\`, exit ${r.rc}):\n${tailOf(r.output)}`,
+  }));
+}
+
+/** The comment the engine posts on a guarded issue once its guard is superseded. */
+export const supersessionComment = ({ guard, pr, why }) => `The fix guard from ${guard} was superseded by PR #${pr}: ${String(why ?? "").trim()}\n\nThe lane's contract carried a \`supersedes\` amendment the reviewer accepted; this guard's test no longer describes current behaviour.`;
+
+/** Guard ids the effective contract's accepted supersedes amendments retire, limited to guards the gate selected. */
+export function supersededIds(contract, selected) {
+  const sel = new Set((selected ?? []).map((s) => `#${s.guard.issue}`));
+  return (contract?.supersedes ?? []).filter((s) => sel.has(s.guard));
+}