forgedock 1.46.0 → 1.48.0

package/bin/lean/rotator.test.mjs

@@ -0,0 +1,143 @@
+// 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 { tmpDir } from "../tests/_tmp.mjs";
+import { parseLive, openRotator, rotatorRetry, quotaRequeue, ROTATOR_KINDS, HEADROOM_PCT } from "./rotator.mjs";
+import { laneBackendId, openLimits } from "./limits.mjs";
+import { orchestrate, formatTable } from "./orchestrate.mjs";
+import { parseExecution } from "./execution.mjs";
+
+const T0 = 1_800_000_000_000; // epoch ms
+const fakeClock = () => { const c = { t: T0 }; return { c, now: () => c.t, sleep: async (ms) => { c.t += ms; } }; };
+/** A tokenbaton home: `accounts` maps n -> [5h %, 5h reset ms, weekly %, weekly reset ms]. */
+const baton = (current, accounts) => {
+  const home = tmpDir("baton-"), dir = join(home, ".tokenbaton");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "current"), `${current}\n`);
+  const write = (n, [p5, r5, pw, rw]) => writeFileSync(join(dir, `live.${n}`), `${p5} ${Math.round(r5 / 1000)} ${pw} ${Math.round(rw / 1000)} ${Math.round(T0 / 1000)}\n`);
+  for (const [n, v] of Object.entries(accounts)) write(n, v);
+  return { home, write, setCurrent: (n) => writeFileSync(join(dir, "current"), `${n}\n`) };
+};
+const H = 3_600_000;
+
+describe("account rotator adapter (#5094)", () => {
+  it("parseLive reads the five fields and rejects malformed lines", () => {
+    assert.deepEqual(parseLive("42 1800000100 7 1800500000 1800000000"), { fiveHourPct: 42, fiveHourResetMs: 1_800_000_100_000, weeklyPct: 7, weeklyResetMs: 1_800_500_000_000 });
+    assert.equal(parseLive(""), null);
+    assert.equal(parseLive("12 abc 3 4"), null);
+    assert.equal(parseLive("1 2 3"), null);
+  });
+
+  it("openRotator is null for an unknown kind or unreadable state; parseExecution keeps only tokenbaton", () => {
+    assert.deepEqual(ROTATOR_KINDS, ["tokenbaton"]);
+    assert.equal(openRotator({ kind: undefined }), null);
+    assert.equal(openRotator({ kind: "other", home: baton(1, { 1: [0, T0 + H, 0, T0 + H] }).home }), null);
+    assert.equal(openRotator({ kind: "tokenbaton", home: tmpDir("empty-") }), null);
+    assert.equal(openRotator({ kind: "tokenbaton", home: baton(1, {}).home }), null, "no live.N");
+    assert.equal(parseExecution({ account_rotator: "tokenbaton" }).accountRotator, "tokenbaton");
+    assert.equal("accountRotator" in parseExecution({ account_rotator: "nope" }), false);
+    assert.equal("accountRotator" in parseExecution({}), false);
+  });
+
+  it("headroom: 5h under 95% and weekly under 100%; a passed reset counts as 0; resumeAt is the earliest regain; state is re-read", () => {
+    const { c, now } = fakeClock();
+    const b = baton(1, { 1: [HEADROOM_PCT, T0 + 2 * H, 10, T0 + 100 * H], 2: [99, T0 + 4 * H, 100, T0 + 3 * H] });
+    const rot = openRotator({ kind: "tokenbaton", home: b.home, now });
+    assert.equal(rot.headroom(), false);
+    assert.equal(rot.resumeAt(), T0 + 2 * H, "account 1 regains at its 5h reset; account 2 needs both resets (4h)");
+    assert.deepEqual(rot.accounts.map((a) => a.n), [1, 2]);
+    c.t = T0 + 2 * H; // account 1's 5h window reset: counts as 0
+    assert.equal(rot.headroom(), true);
+    assert.equal(rot.resumeAt(), c.t);
+    c.t = T0;
+    b.write(2, [10, T0 + H, 10, T0 + 100 * H]); // tokenbaton refreshed live.2
+    assert.equal(rot.headroom(), true, "no cache: the new file is read");
+    assert.equal(rot.current(), 1);
+    b.setCurrent(2);
+    assert.equal(rot.current(), 2);
+  });
+
+  it("account identity is the lane identity on ~/.claude-<n>; isAccount; laneBackendId follows the rotator's current account", () => {
+    const b = baton(1, { 1: [0, T0 + H, 0, T0 + H], 2: [0, T0 + H, 0, T0 + H] });
+    const rot = openRotator({ kind: "tokenbaton", home: b.home, env: {}, now: () => T0 });
+    assert.equal(rot.accountIdentity(2), laneBackendId({ CLAUDE_CONFIG_DIR: join(b.home, ".claude-2") }));
+    assert.equal(rot.isAccount(rot.accountIdentity(1)), true);
+    assert.equal(rot.isAccount("remote-credential"), false);
+    assert.equal(laneBackendId({}, rot), rot.accountIdentity(1));
+    b.setCurrent(2);
+    assert.equal(laneBackendId({}, rot), rot.accountIdentity(2), "#R13: the identity changes when tokenbaton rotates");
+    assert.equal(laneBackendId({ CLAUDE_CONFIG_DIR: "/x" }, null), laneBackendId({ CLAUDE_CONFIG_DIR: "/x" }), "no rotator: unchanged");
+    assert.equal(laneBackendId({ CLAUDE_CONFIG_DIR: "/x" }, { currentIdentity: () => { throw new Error("x"); } }), laneBackendId({ CLAUDE_CONFIG_DIR: "/x" }), "fail-open");
+  });
+
+  it("rotatorRetry and quotaRequeue: rotation is capped at the account count; a remote credential waits for its own reset", () => {
+    const rot = { accounts: [{ n: 1 }, { n: 2 }], headroom: () => true, isAccount: (id) => id === "acct-1" };
+    assert.equal(rotatorRetry(rot, 0), true);
+    assert.equal(rotatorRetry(rot, 2), false);
+    assert.equal(rotatorRetry(null, 0), false);
+    assert.equal(rotatorRetry({ ...rot, headroom: () => false }, 0), false);
+    assert.deepEqual(quotaRequeue({ rotator: rot, r: { backendId: "acct-1" }, delayMs: 600_000 }), { delayMs: 0, rotated: true });
+    assert.deepEqual(quotaRequeue({ rotator: rot, r: {}, delayMs: 600_000 }), { delayMs: 0, rotated: true });
+    assert.deepEqual(quotaRequeue({ rotator: rot, r: { backendId: "acct-1" }, prior: { rotations: 2 }, delayMs: 600_000 }), { delayMs: 600_000, rotated: false });
+    assert.deepEqual(quotaRequeue({ rotator: rot, r: { backendId: "sandbox-cred" }, delayMs: 600_000 }), { delayMs: 600_000, rotated: false }, "R6: remote credential");
+    assert.equal(quotaRequeue({ rotator: { ...rot, headroom: () => false }, r: {}, delayMs: 1 }), null);
+    assert.equal(quotaRequeue({ rotator: null, r: {}, delayMs: 1 }), null);
+  });
+});
+
+describe("orchestrate with an account rotator (#5094)", () => {
+  const limited = (id, until, cost = 0.5, minutes = 3) => ({ terminalReason: "deferred", code: "rate_limited", resetAtEpochMs: until, backendId: id, cost_usd: cost, minutes });
+
+  it("every account exhausted: admissions stop, and resume by themselves when the first account resets", async () => {
+    const { now, sleep } = fakeClock();
+    const rot = { accounts: [{ n: 1 }, { n: 2 }], headroom: () => now() >= T0 + 2 * H, resumeAt: () => T0 + 2 * H, isAccount: () => true, currentIdentity: () => "acct-1" };
+    const starts = [];
+    const rows = await orchestrate({ issues: [1], now, sleep, readBody: async () => "", rotator: rot, limits: openLimits(join(tmpDir("lim-"), "l.json"), { now }), identity: () => "acct-1",
+      runOne: async () => { starts.push(now()); return { terminalReason: "merged" }; } });
+    assert.deepEqual(rows.map((r) => r.outcome), ["merged"]);
+    assert.equal(starts[0], T0 + 2 * H, "held until the rotator's resumeAt, then admitted without operator action");
+  });
+
+  it("report: the requeue row is 'paused (quota)' with its resume time, never 'deferred', and the paused cost is counted once", async () => {
+    const { now, sleep } = fakeClock();
+    const updates = [];
+    let runs = 0;
+    const rows = await orchestrate({ issues: [1], now, sleep, readBody: async () => "", limits: openLimits(join(tmpDir("lim-"), "l.json"), { now }), identity: () => "A",
+      onUpdate: (u) => updates.push(u), runOne: async () => (++runs === 1 ? limited("A", T0 + H) : { terminalReason: "merged", cost_usd: 1.25, minutes: 4 }) });
+    const paused = updates.find((u) => u.issue === 1 && u.outcome === "paused");
+    assert.ok(paused, `paused row: ${JSON.stringify(updates.map((u) => u.outcome))}`);
+    assert.equal(updates.some((u) => u.outcome === "deferred"), false);
+    assert.equal(paused.quota.resumeAt, new Date(T0 + H).toISOString());
+    assert.match(paused.detail, /^paused \(quota\) until /);
+    assert.equal(rows[0].outcome, "merged");
+    assert.equal(rows[0].cost_usd, 1.75, "paused attempt + rerun, once");
+    assert.match(formatTable([{ ...paused }]), /paused \(quota\) until \d{4}-/);
+  });
+
+  it("a batch that ends while quota-paused leaves a resumable 'held' row with the quota resume time and the paused cost", async () => {
+    const { now, sleep } = fakeClock();
+    // #2's engine-errors trip the breaker while #1 waits for its quota: the batch ends with #1 pending.
+    const rows = await orchestrate({ issues: [2, 1], parallel: 1, now, sleep, readBody: async () => "", breaker: { errors: 2, window_min: 600 },
+      limits: openLimits(join(tmpDir("lim-"), "l.json"), { now }), identity: () => "A", runOne: async (n) => { if (n === 2) throw new Error("boom"); return limited("A", T0 + H); } });
+    const row = rows.find((r) => r.issue === 1);
+    assert.equal(row.outcome, "held", "P4: held stays the resumable marker");
+    assert.equal(row.quota?.resumeAt, new Date(T0 + H).toISOString());
+    assert.equal(row.cost_usd, 0.5);
+    assert.equal(row.detail, `paused (quota) until ${new Date(T0 + H).toISOString()}`);
+    assert.match(formatTable(rows), /paused \(quota\) until /);
+  });
+
+  it("a remote lane limited on its own credential waits for its own reset and sets no host hold while the rotator has headroom", async () => {
+    const { now, sleep } = fakeClock();
+    const limits = openLimits(join(tmpDir("lim-"), "l.json"), { now });
+    const rot = { accounts: [{ n: 1 }], headroom: () => true, resumeAt: () => now(), isAccount: (id) => id === "acct-1", currentIdentity: () => "acct-1" };
+    const starts = [];
+    await orchestrate({ issues: [1], now, sleep, readBody: async () => "", rotator: rot, limits, identity: () => "acct-1",
+      runOne: async () => { starts.push(now()); return starts.length === 1 ? limited("sandbox-cred", T0 + H) : { terminalReason: "merged" }; } });
+    assert.deepEqual(limits.list(), []);
+    assert.equal(starts[1], T0 + H);
+  });
+});

package/bin/lean/routecheck.mjs

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * #5087: route reachability. A fix that adds an HTTP route handler can pass every test while the production ingress sends
+ * the path to another service. forge.yaml `topology.route_reachability` is a repo-supplied command that takes the added
+ * route paths as arguments and exits non-zero when the production ingress does not deliver them to the service that
+ * implements them. Core stays repo-agnostic (#1347): it only derives the paths and runs the command. Absent key = no check.
+ */
+import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
+
+const APP_ROUTE_RE = /(?:^|\/)app\/(?:(.*)\/)?route\.(?:[cm]?[jt]sx?)$/;
+const PAGES_API_RE = /(?:^|\/)pages\/(api(?:\/.*)?)\.(?:[cm]?[jt]sx?)$/;
+
+/** URL path of one Next.js route handler file (app router `route.ts`, pages router `pages/api`), or null. Route groups `(x)` and slots `@x` are not URL segments. */
+export function routePathOf(file) {
+  const f = String(file ?? "").replace(/\\/g, "/");
+  const app = APP_ROUTE_RE.exec(f);
+  if (app) return `/${(app[1] ?? "").split("/").filter((s) => s && !/^\(.*\)$/.test(s) && !s.startsWith("@")).join("/")}`;
+  const pg = PAGES_API_RE.exec(f);
+  if (pg) return `/${pg[1].replace(/\/index$/, "")}`;
+  return null;
+}
+
+/** Sorted unique URL paths of the route-handler files in `files`. */
+export function routePathsFromFiles(files) {
+  return [...new Set((files ?? []).map(routePathOf).filter(Boolean))].sort();
+}
+
+const sq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+/**
+ * Blocking failures (conformance.unimplemented, kind route_unreachable) when the declared command exits non-zero for the
+ * added route paths. [] when no command is declared or no route was added. A command that cannot start (rc 127) is
+ * reported too: a declared blocking check that never ran is no evidence. `run` is ({command}) => {rc, output}
+ * (a `{r: {rc, output}}` wrapper is unwrapped).
+ */
+export async function routeReachabilityFailures({ command, paths, run }) {
+  const cmd = typeof command === "string" ? command.trim() : "";
+  if (!cmd || !paths?.length) return [];
+  let r;
+  try { r = await run({ command: `${cmd} ${paths.map(sq).join(" ")}` }); r = r?.r ?? r; } catch (e) { r = { rc: 127, output: String(e?.message ?? e) }; }
+  if (r?.rc === 0) return [];
+  const tail = String(r?.output ?? "").trim().split("\n").slice(-12).join("\n").slice(0, 1500);
+  return [{
+    code: OUTCOME_CODES.CONFORMANCE_UNIMPLEMENTED, kind: "route_unreachable",
+    detail: `forge.yaml topology.route_reachability (\`${cmd}\`) exited ${r?.rc ?? "?"} for the new route(s) ${paths.join(", ")}: the production ingress does not deliver them to the service that implements them; fix the route or the ingress, citing the ingress rule${tail ? `:\n${tail}` : ""}`,
+  }];
+}

package/bin/lean/routecheck.test.mjs

@@ -0,0 +1,69 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { routePathOf, routePathsFromFiles, routeReachabilityFailures } from "./routecheck.mjs";
+import { readEnvConfig } from "../engine-cli.mjs";
+import { tmpDir } from "../tests/_tmp.mjs";
+
+// Stand-in for AlterLab's scripts/generate-traefik-config.sh: the api-router sends /api/v1/* to FastAPI;
+// only /api/v1/batch and /api/v1/b2b/jobs go to web (#5087).
+const dir = tmpDir("routecheck-");
+const ingress = join(dir, "check-ingress.sh");
+writeFileSync(ingress, `#!/usr/bin/env bash
+rc=0
+for p in "$@"; do
+  case "$p" in
+    /api/v1/batch|/api/v1/batch/*|/api/v1/b2b/jobs|/api/v1/b2b/jobs/*) ;;
+    /api/v1/*) echo "unreachable: $p is routed to api (FastAPI) by api-router, not web" >&2; rc=1 ;;
+  esac
+done
+exit $rc
+`);
+const run = async ({ command }) => { const r = spawnSync("bash", ["-c", command], { encoding: "utf8" }); return { rc: r.status, output: `${r.stdout}${r.stderr}` }; };
+const SIGNUP = ["web/src/app/(site)/api/v1/agent/signup/pending/route.ts", "web/src/app/(site)/api/v1/agent/signup/by-code/[code]/route.ts"];
+
+describe("#5087 route reachability", () => {
+  it("maps Next.js handler files to URL paths", () => {
+    assert.equal(routePathOf(SIGNUP[0]), "/api/v1/agent/signup/pending");
+    assert.equal(routePathOf(SIGNUP[1]), "/api/v1/agent/signup/by-code/[code]");
+    assert.equal(routePathOf("web/src/pages/api/health/index.ts"), "/api/health");
+    assert.equal(routePathOf("web/src/app/route.ts"), "/");
+    assert.equal(routePathOf("web/src/app/page.tsx"), null);
+    assert.equal(routePathOf("bin/lean/routecheck.mjs"), null);
+    assert.deepEqual(routePathsFromFiles([...SIGNUP, SIGNUP[0], "README.md"]), ["/api/v1/agent/signup/by-code/[code]", "/api/v1/agent/signup/pending"]);
+  });
+  it("fixture ingress routes /api/v1/agent/signup to FastAPI and fails the check", async () => {
+    const f = await routeReachabilityFailures({ command: `bash ${ingress}`, paths: routePathsFromFiles(SIGNUP), run });
+    assert.equal(f.length, 1);
+    assert.equal(f[0].code, "conformance.unimplemented");
+    assert.equal(f[0].kind, "route_unreachable");
+    assert.match(f[0].detail, /signup\/pending/);
+  });
+  it("passes a route the ingress delivers to web", async () => {
+    assert.deepEqual(await routeReachabilityFailures({ command: `bash ${ingress}`, paths: ["/api/v1/batch"], run }), []);
+  });
+  it("a passing command wrapped as {r: {rc, output}} (lean io.runCommand shape) is not reported as a failure", async () => {
+    const wrapped = async (a) => ({ r: await run(a) });
+    assert.deepEqual(await routeReachabilityFailures({ command: `bash ${ingress}`, paths: ["/api/v1/batch"], run: wrapped }), []);
+    assert.equal((await routeReachabilityFailures({ command: `bash ${ingress}`, paths: ["/api/v1/agent/signup/pending"], run: wrapped })).length, 1);
+  });
+  it("is a no-op without a declared command or without added routes", async () => {
+    const never = async () => { throw new Error("must not run"); };
+    assert.deepEqual(await routeReachabilityFailures({ command: undefined, paths: ["/api/v1/x"], run: never }), []);
+    assert.deepEqual(await routeReachabilityFailures({ command: "false", paths: [], run: never }), []);
+  });
+  it("a command that cannot run is reported, not swallowed", async () => {
+    const f = await routeReachabilityFailures({ command: "x", paths: ["/a"], run: async () => { throw new Error("boom"); } });
+    assert.equal(f[0].kind, "route_unreachable");
+    assert.match(f[0].detail, /exited 127/);
+  });
+  it("forge.yaml topology.route_reachability is read; repos without topology get no key", () => {
+    const withKey = tmpDir("rc-yaml-"), without = tmpDir("rc-yaml-");
+    writeFileSync(join(withKey, "forge.yaml"), "topology:\n  route_reachability: \"bash scripts/check-ingress.sh\"\n");
+    writeFileSync(join(without, "forge.yaml"), "project: x/y\n");
+    assert.equal(readEnvConfig(withKey).routeReachability, "bash scripts/check-ingress.sh");
+    assert.equal("routeReachability" in readEnvConfig(without), false);
+  });
+});

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

@@ -189,6 +189,15 @@ describe("remote adapter (#4254)", () => {
     await assert.rejects(() => q.status(h), /ECONNRESET/); // #4672: a transport error propagates; providerLanes retries it for the unreachable window
   });
 
+  it("#5095 httpTransport: a 500 is transient (polled with backoff) and a 5xx carries Retry-After; only 429/503 are retryable", async () => {
+    const reply5xx = (status, ra) => async () => ({ status, ok: false, text: async () => "", headers: { get: (h) => (h === "retry-after" ? ra : null) } });
+    const t = httpTransport({ endpoint: "https://pool.example", fetchFn: reply5xx(500, "7") });
+    await assert.rejects(t.launch({ id: "x" }), (e) => e.status === 500 && e.transient === true && e.retryable !== true && e.retryInSeconds === 7);
+    await assert.rejects(t.status("x"), (e) => e.transient === true);
+    const t504 = httpTransport({ endpoint: "https://pool.example", fetchFn: reply5xx(504, null) });
+    await assert.rejects(t504.launch({ id: "x" }), (e) => e.status === 504 && e.transient === true && e.retryable !== true && e.retryInSeconds === undefined);
+  });
+
   it("#5053 httpTransport: a 401 on status is transient and names its hop; a launch 401 is not transient", async () => {
     const reply = (status, body) => ({ status, ok: status < 300, text: async () => JSON.stringify(body), headers: { get: () => null } });
     const t = httpTransport({ endpoint: "https://pool.example", token: TOKEN, fetchFn: async () => reply(401, { error: "unauthorized", hop: "agent", agent: "a1", reason: "agent auth: router token rejected by agent" }) });

package/bin/lean/sandbox-remote.mjs

@@ -68,8 +68,10 @@ export function httpTransport({ endpoint, token = null, fetchFn = globalThis.fet
     e.status = r.status;
     if (hop) e.hop = hop;
     if (reason) e.reason = reason;
-    if ([502, 503, 504].includes(r.status)) e.transient = true; // #4672: a router restart or gateway blip, retried by the lane poll
-    if (r.status === 429 || r.status === 503) { e.retryable = true; const n = Number(r.retryAfter); if (Number.isFinite(n) && n > 0) e.retryInSeconds = n; }
+    if ([500, 502, 503, 504].includes(r.status)) e.transient = true; // #4672: a router restart or gateway blip, retried by the lane poll; #5095: 500 too
+    if (r.status === 429 || r.status === 503) e.retryable = true;
+    // #5095: Retry-After is honoured on any 429/5xx, so a launch 5xx (sandbox.transient) backs off as the pool asks
+    if (r.status === 429 || r.status >= 500) { const n = Number(r.retryAfter); if (Number.isFinite(n) && n > 0) e.retryInSeconds = n; }
     return e;
   };
   const p = (id) => `/sandboxes/${encodeURIComponent(id)}`;

package/bin/lean/verify.mjs

@@ -68,7 +68,8 @@ export function parseVerify(sec = {}) {
       if (ext.length > 1 && cmd) guardCommand[ext] = cmd;
     }
   }
-  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds, precheckTotalSeconds, checkRun, checks, postMerge, flaky, duplicateExports, invariants, ...(Object.keys(guardCommand).length ? { guardCommand } : {}), e2e: parseE2e(s) };
+  const precheckBlock = str(s.precheck_block).toLowerCase() === "true"; // #5079: a still-failing declared check stops the lane (ci.red)
+  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds, precheckTotalSeconds, checkRun, checks, postMerge, flaky, duplicateExports, invariants, ...(precheckBlock ? { precheckBlock } : {}), ...(Object.keys(guardCommand).length ? { guardCommand } : {}), e2e: parseE2e(s) };
 }
 
 const globRe = (g) => new RegExp(`^${g.split("**").map((p) => p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")).join(".*")}$`);

package/bin/review-staging.mjs

@@ -211,6 +211,19 @@ async function headSha(io, c, pr) {
   return head;
 }
 
+/** A gh write retried on a transient failure (FORGE_GH_RETRY_ATTEMPTS, default 6; FORGE_GH_RETRY_SLEEP seconds, default 2, doubling to 16), as gh_retry in the scripts. */
+async function retryGh(io, args) {
+  const max = Number(io.env.FORGE_GH_RETRY_ATTEMPTS) > 0 ? Math.floor(Number(io.env.FORGE_GH_RETRY_ATTEMPTS)) : 6;
+  const base = /^\d+$/.test(io.env.FORGE_GH_RETRY_SLEEP ?? "") ? Number(io.env.FORGE_GH_RETRY_SLEEP) : 2;
+  for (let n = 1; ; n++) {
+    try { return await io.gh(args); } catch (e) {
+      if (n >= max) throw e;
+      const w = Math.min(base * 2 ** (n - 1), 16);
+      if (w > 0) await new Promise((r) => setTimeout(r, w * 1000));
+    }
+  }
+}
+
 async function main(argv, io) {
   const a = parseArgs(argv);
   if (a.mode === "finalize") return finalize(a, io);
@@ -241,7 +254,7 @@ async function main(argv, io) {
   } catch { /* unreadable: treated as a first pass */ }
   const priorOpen = priorRoutes > 0 ? await priorFindings(io, c, pr, "open") : [];
   const priorResolved = priorRoutes > 0 ? await priorFindings(io, c, pr, "closed") : [];
-  await io.gh(["pr", "comment", String(pr), "-R", c.ghRepo, "--body", `<!-- FORGE:REVIEW_ROUTE mode=staging-deploy spec=review-pr-staging.md sha=${sha7} -->`]);
+  await retryGh(io, ["pr", "comment", String(pr), "-R", c.ghRepo, "--body", `<!-- FORGE:REVIEW_ROUTE mode=staging-deploy spec=review-pr-staging.md sha=${sha7} -->`]);
   io.writeFile(join(sd, `staging_pr_number.${runKey(io.env)}`), `${pr}\n`);
 
   // 0A: bundle PR set, then the open review-finding gate
@@ -365,6 +378,10 @@ async function finalize(a, io) {
   const { c, sd, env, pr, head } = await postContext(a, io);
   const common = ["--repo", c.ghRepo, "--pr", String(pr), "--sd", sd, "--head", head];
 
+  // The panel reviewed the head recorded at dispatch: a moved head is a refusal to --delta, never a degraded panel (no label, no gate failure).
+  const reviewed = readJson(io, join(sd, `review-ctx-${pr}.json`))?.pr?.review_sha;
+  if (SHA_RE.test(reviewed ?? "") && reviewed !== head) throw new Stop(1, [`REVIEW_RESULT: status: BLOCKED, blocker: head moved since the review (${reviewed.slice(0, 7)} -> ${head.slice(0, 7)}): run forgedock review-staging ${pr} --delta ${reviewed}`, BLOCK_DEPLOY]);
+
   // Incomplete-panel guard + 6.75 delivery
   const d = await bash(io, "review-staging-post.sh", ["delivery", ...common], env);
   relay(io, d);
@@ -424,7 +441,7 @@ async function finalize(a, io) {
 
   const findings = readJson(io, join(outDir, "findings.json"))?.findings ?? [];
   // A finding whose own filed issue is already closed (file-prepare: skip-resolved, delta pass) is resolved: it never blocks (#4569).
-  const resolvedBy = new Map(worklist.items.filter((i) => i.action === "skip-resolved").map((i) => [i.id, i.dedup_of]));
+  const resolvedBy = new Map(worklist.items.filter((i) => i.action === "skip-resolved" || i.action === "skip-fixed-in-delta").map((i) => [i.id, i.dedup_of]));
   const resolved = findings.filter((f) => resolvedBy.has(f.id) && upper(f.confidence) === "CONFIRMED" && ["CRITICAL", "HIGH"].includes(upper(f.severity)))
     .map((f) => ({ id: f.id, severity: upper(f.severity), title: f.title ?? "", issue: resolvedBy.get(f.id) }));
   const confirmed = (sev) => findings.filter((f) => !resolvedBy.has(f.id) && upper(f.confidence) === "CONFIRMED" && upper(f.severity) === sev).length;
@@ -534,7 +551,7 @@ async function summary(a, io) {
     `- findings_kept: ${n.findings_kept ?? 0}; dropped_stale: ${n.findings_dropped_stale ?? 0}; pre-existing: ${n.findings_preexisting ?? 0}; notes_demoted_no_scenario: ${n.notes_demoted_no_scenario ?? 0}`,
     `- findings_filed: ${n.findings_filed ?? 0}${filed.length ? ` (${filed.join(", ")})` : ""}; out_of_scope: ${n.out_of_scope ?? 0}`,
     `- notes_fixed: 0; notes_listed: ${n.notes_listed ?? 0}; notes_dropped: ${n.notes_dropped ?? 0}; notes_capped: ${n.notes_capped ?? 0}; notes_reflag: ${n.notes_reflag ?? 0}`,
-    `- resolved (excluded from the verdict): ${(st.resolved ?? []).length ? st.resolved.map((r) => `${r.severity} ${r.id} ${r.title} (closed #${r.issue})`.replace(/\s+/g, " ")).join("; ") : "(none)"}`,
+    `- resolved (excluded from the verdict): ${(st.resolved ?? []).length ? st.resolved.map((r) => `${r.severity} ${r.id} ${r.title} (${r.issue ? `closed #${r.issue}` : "fixed in delta"})`.replace(/\s+/g, " ")).join("; ") : "(none)"}`,
     `- deduped: ${deduped.length ? deduped.join("; ") : "(none)"}`,
     ...(st.delta?.from ? [`- delta pass: ${String(st.delta.from).slice(0, 7)}..${head.slice(0, 7)} (${(st.delta.files ?? []).length} file(s)); earlier pass at ${st.delta.from} credited (its findings re-read by extract)`] : []),
     "",

package/commands/deploy-info.md

@@ -57,13 +57,13 @@ else
   OPEN_FINDINGS_SUMMARY=""
   for pr_num in $ALL_PR_NUMBERS; do
     # Anchored post-filter (same as review-pr-staging.md): the search is a coarse candidate fetch only
-    FINDING_PR_FILTER='[.[] | select((.title | endswith("PR #" + $n + ")")) or ((.body // "") | test("(^|\\n)\\*\\*Source\\*\\*: PR #" + $n + "([^0-9]|$)")))] | .[] | "  - #\(.number): \(.title)"'  # FINDING_PR_FILTER
+    FINDING_PR_FILTER='[.[] | select(([.labels[]?.name] | (index("blocking") != null) or (index("priority:P0") != null) or (index("priority:P1") != null) or (map(select(startswith("priority:"))) | length == 0))) | select((.title | endswith("PR #" + $n + ")")) or ((.body // "") | test("(^|\\n)\\*\\*Source\\*\\*: PR #" + $n + "([^0-9]|$)")))] | .[] | "  - #\(.number): \(.title)"'  # FINDING_PR_FILTER
     OPEN_FINDINGS=$(gh issue list -R {GH_REPO} \
       --label "review-finding" \
       --state open \
       --search "PR #${pr_num}" \
       --limit 20 \
-      --json number,title,body 2>/dev/null \
+      --json number,title,body,labels 2>/dev/null \
       | jq -r --arg n "${pr_num}" "$FINDING_PR_FILTER" 2>/dev/null)  # uses FINDING_PR_FILTER
 
     if [ -n "$OPEN_FINDINGS" ]; then
@@ -307,13 +307,13 @@ if [ -z "$TRAIN_PR_NUMBER" ]; then
 else
   # Step 2: Check whether the train is held (has blocking findings)
   # Anchored post-filter (same as review-pr-staging.md): the search is a coarse candidate fetch only
-  FINDING_PR_FILTER='[.[] | select((.title | endswith("PR #" + $n + ")")) or ((.body // "") | test("(^|\\n)\\*\\*Source\\*\\*: PR #" + $n + "([^0-9]|$)")))] | .[] | "  - #\(.number): \(.title)"'  # FINDING_PR_FILTER
+  FINDING_PR_FILTER='[.[] | select(([.labels[]?.name] | (index("blocking") != null) or (index("priority:P0") != null) or (index("priority:P1") != null) or (map(select(startswith("priority:"))) | length == 0))) | select((.title | endswith("PR #" + $n + ")")) or ((.body // "") | test("(^|\\n)\\*\\*Source\\*\\*: PR #" + $n + "([^0-9]|$)")))] | .[] | "  - #\(.number): \(.title)"'  # FINDING_PR_FILTER
   HELD_BY=$(gh issue list {GH_FLAG} \
     --label "review-finding" \
     --state open \
     --search "PR #${TRAIN_PR_NUMBER}" \
     --limit 20 \
-    --json number,title,body 2>/dev/null \
+    --json number,title,body,labels 2>/dev/null \
     | jq -r --arg n "${TRAIN_PR_NUMBER}" "$FINDING_PR_FILTER" 2>/dev/null | sed 's/^  - //' || true)  # uses FINDING_PR_FILTER
 
   if [ -n "$HELD_BY" ]; then

package/commands/issue.md

@@ -81,7 +81,9 @@ The body MUST contain exactly one marker `<!-- FORGE:BODY-INTEGRITY:<entity>_<ro
 
 Read the actual code before drafting: the investigator inherits your file references. Map the domain (`forge.yaml → review.context`, the project's `CLAUDE.md`), read files from `origin/{STAGING_BRANCH}` via `git show`, and list every file the change touches: the primary file, its tests, config layers (`.env.example`, every compose override), migrations for schema changes, importers of a changed function.
 
-Duplicates: the script's token-overlap dedup is authoritative. Before drafting, also run a semantic search (`gh issue list --state open --search "{key_terms}"`, and `--state closed` for regressions). An open duplicate: tell the user and do not create. A closed one: create, and write "Regression of #N." in the body. If the user explicitly overrides a dedup STOP, re-run with `--exclude <that number>`; agents never do this without the user's authorization.
+Duplicates: the script's token-overlap dedup is authoritative; also run a semantic search (`gh issue list --state open --search "{key_terms}"`, and `--state closed` for regressions). An open duplicate: tell the user and do not create. A closed one: create, and write "Regression of #N." in the body. If the user explicitly overrides a dedup STOP, re-run with `--exclude <that number>`; agents never do this without the user's authorization.
+
+**Prior attempts (MANDATORY for bug/fix)**: `node "$(forge_resolve prior-attempts.mjs)" --repo {GH_REPO} --title "{TITLE}" --body-file "{DRAFT_BODY_FILE}"` searches by subject, not file. Paste its table as `## Prior Attempts`; fill the `?`s.
 
 ### 3. Draft
 
@@ -108,6 +110,9 @@ Duplicates: the script's token-overlap dedup is authoritative. Before drafting,
 ## Acceptance Criteria
 - [ ] {specific, testable criterion} [type:api|unit|e2e|manual]
 
+## Prior Attempts
+{prior-attempts.mjs table; bug/fix only}
+
 ## Dependencies
 Depends on #{N} — {reason}   (omit when none)
 

package/commands/review-pr-agents/frontend.md

@@ -35,6 +35,7 @@ If no frontend context is configured above, derive conventions from the changed
 8. **Accessibility**: Interactive elements have proper labels, keyboard navigation works
 9. **Performance**: Large bundles, unnecessary client-side rendering, missing dynamic imports
 10. **Hook provider scope**: For any new `useX()` hook call added to a component, verify the hook is safe to call outside its provider. If `useX` internally calls `useContext(XContext)` and throws when context is undefined (i.e., the hook contains `if (!ctx) throw new Error(...)`), check ALL mount sites of the component across the codebase. If the component is used in both authenticated routes (e.g., `app/dashboard/`) AND public routes (e.g., `app/(public)/`, `app/playground/`) that do not wrap children in the provider, the hook call will crash the public route with a React error boundary cascade. Flag as CONFIRMED HIGH if a public mount site exists without the provider. <!-- Added: forge#381 -->
+11. **Dynamic API in static/ISR tree**: Flag `headers()`, `cookies()`, `connection()` or `searchParams` reads in layouts, `not-found`/`error` boundaries and any module they import when the route tree is static or ISR (`revalidate`, `generateStaticParams`, `dynamic = 'force-static'`). They opt the route out of static rendering or throw at render, turning pages into HTTP 500. Flag as CONFIRMED HIGH when the call is reachable from such a tree. <!-- Added: forge#5077 -->
 
 ## Post Findings
 ```bash

package/commands/review-pr-agents/infra.md

@@ -25,6 +25,8 @@ You are auditing PR #[PR_NUMBER] for infrastructure and deployment safety in [PR
 If no infra context is configured above, derive the deployment model from the changed files: read docker-compose files, GitHub Actions workflows, and entrypoint scripts to understand the deployment pipeline.
 
 ## What to Check
+
+**New HTTP route handler (forge#5087)**: when the diff adds a route handler (Next.js `app/**/route.*`, `pages/api/**`, a FastAPI/Express router), confirm the production ingress delivers this path to this service: read the repo's ingress config (Traefik, nginx, gateway) and cite the rule. An app-level rewrite or fallback is not evidence; a path an ingress prefix rule sends to another service is a HIGH finding.
 1. **Downtime risk**: Will this change cause container restarts during deploy?
 1b. **Database container restart risk** (when `docker-compose*.yml` changes touch the `postgres` or `redis` service — `command:`, `image:`, `volumes:`, `environment:`):
    Changing any of these fields forces container recreation on `docker-compose up`. For stateful services this is **HIGH risk by default** — regardless of how simple the config change appears.

package/commands/review-pr-staging.md

@@ -379,6 +379,8 @@ Invoke `/test-gate` with the manifest's `BUNDLE_PRS` and the default branch. Sav
 >>> INVOKE: Skill(skill="{FORGE_SKILL_PREFIX}test-gate", args="--prs \"<BUNDLE_PRS>\" --base <default branch>")
 ```
 
+**Route reachability (forge#5087, blocking when declared)**: when `forge.yaml` declares `topology.route_reachability`, list the route paths the bundle adds (`git diff --name-only --diff-filter=A <default>...HEAD`, Next.js `app/**/route.*` / `pages/api/**` mapped to URL paths, route groups removed) and run the command with them as arguments. A non-zero exit is a BLOCK finding naming the path; unset = skip.
+
 Do not judge the result yourself. Step 7A reads the output's last `FORGE:TEST_GATE:RESULT=` marker through `scripts/review-staging-post.sh test-gate`. A missing or invalid marker (gate result missing/invalid) is BLOCK, never SKIP (fail closed). The step then applies the override and the posture. It posts `FORGE:GATE_PASS` (PASS) or `FORGE:GATE_FAILURE` (blocking BLOCK, with `RESULT: BLOCK DEPLOY`), and persists the verdict for Phase 8.
 
 **Incomplete-panel guard (MANDATORY):** Every reviewer selected in Phases 2–6 is appended to the launched-agent file before it is launched. If any dispatch fails, follow step 4 of Sub-Agent Dispatch Tool Resolution (hard stop). Before triage, step 7A counts unique trusted, current-head `FORGE:REVIEW-AGENT` markers. A marker counts only when all of these hold: the author is trusted per `scripts/trusted-comments.sh`, the body starts with the marker, the `Reviewed-SHA:` line matches the full head SHA, and the findings block is present. All comment pages are read. An unresolvable script or unreadable comments count as 0. If the completed count (`ACTUAL_AGENT_COUNT`) is lower than the selected count (`SELECTED_AGENT_COUNT`), the step labels the PR `review-degraded` and `needs-human`. It posts `FORGE:GATE_FAILURE:TYPE=review-panel-integrity` and stops. Do not create a deploy verdict from partial reviewer output.

package/commands/work-on/build/context.md

@@ -696,6 +696,8 @@ the index is absent or returns no results for a given file.
 ```bash
 # Resolve recall CLI path relative to repository root
 RECALL_PATH="${REPO_PATH:-$(git rev-parse --show-toplevel 2>/dev/null)}/bin/recall.mjs"
+# #5085: recall.mjs ships with ForgeDock, not the target repo: also probe the install root
+[ -f "$RECALL_PATH" ] || RECALL_PATH="$(forge_root 2>/dev/null)/bin/recall.mjs"
 LEDGER_AVAILABLE=0
 
 if [ -f "$RECALL_PATH" ]; then
@@ -735,7 +737,11 @@ Query closed issues with `review-finding` label, searching by filename:
 
 ```bash
 if [ "$LEDGER_AVAILABLE" -eq 0 ] || [ -z "$LEDGER_FINDINGS" ]; then
-  echo "[context:C1] Forge Ledger unavailable or empty — falling back to live gh search"
+  echo "WARNING: [context:C1] Forge Ledger index absent or empty — falling back to live gh + subject search"
+  # #5085: prior attempts by subject terms (codes, symbols, title words), not only by file
+  PA_BODY="${TMPDIR:-/tmp}/pa-{NUMBER}.md"; gh issue view {NUMBER} -R {GH_REPO} --json body --jq .body > "$PA_BODY" 2>/dev/null
+  node "$(forge_resolve prior-attempts.mjs)" --repo {GH_REPO} --issue {NUMBER} --body-file "$PA_BODY" \
+    --title "$(gh issue view {NUMBER} -R {GH_REPO} --json title --jq .title)" || true   # → **Prior Attempts** in output
   IFS=' ' read -ra AFFECTED_FILES_ARR <<< "{AFFECTED_FILES}"
   for file in "${AFFECTED_FILES_ARR[@]}"; do
     basename=$(basename "$file" .py)

package/commands/work-on/investigate.md

@@ -175,7 +175,7 @@ Print these blocks to stdout before Phase 1A begins. During Phase 1B (step 3 —
 
 **Goal**: Query the Forge Ledger knowledge index for prior cards matching this issue's title terms, affected files, and symbols — **before reading any code**. Inject above-threshold results with explicit delta-verification framing so the investigator builds on prior knowledge rather than re-deriving it.
 
-**This phase is non-blocking** — if the index is absent, empty, or returns no match above threshold, log a single line and proceed to Phase 1A. Never stall the pipeline for recall.
+**This phase is non-blocking** — if the index is absent or empty, print a WARNING and use the live subject search (Step 1); if it returns no match above threshold, log a single line and proceed to Phase 1A. Never stall the pipeline for recall.
 
 **Relationship to Phase 0.5**: Phase 0.5 retrieves structured priors from the Gist-based FORGE:MEMORY_INDEX (coarse keyword scoring over MEMORY_ENTRY lines). Phase 0.6 queries the Forge Ledger index (BM25 over structured knowledge cards, indexed by `build-knowledge-index.mjs`). Both are complementary and both run — neither replaces the other.
 
@@ -183,6 +183,8 @@ Print these blocks to stdout before Phase 1A begins. During Phase 1B (step 3 —
 
 ```bash
 RECALL_PATH="${REPO_PATH:-$(git rev-parse --show-toplevel 2>/dev/null)}/bin/recall.mjs"
+# #5085: recall.mjs ships with ForgeDock, not the target repo: also probe the install root
+[ -f "$RECALL_PATH" ] || RECALL_PATH="${FORGE_ROOT:-$(forge_root 2>/dev/null)}/bin/recall.mjs"
 LEDGER_AVAILABLE=0
 
 if [ -f "$RECALL_PATH" ]; then
@@ -192,8 +194,14 @@ if [ -f "$RECALL_PATH" ]; then
 fi
 
 if [ "$LEDGER_AVAILABLE" -eq 0 ]; then
-  echo "[recall] Forge Ledger index absent or empty — skipping Phase 0.6, proceeding to Phase 1A"
-  # → Continue to Phase 1A
+  WHICH=$([ -f "$RECALL_PATH" ] && echo "index ~/.forge/index empty or missing" || echo "bin/recall.mjs missing")
+  echo "WARNING: [recall] Forge Ledger index absent or empty (${WHICH}) — falling back to live subject search"
+  # #5085: prior attempts by subject terms (codes, symbols, title words) + repo-wide git log --grep, not only by file
+  PA_BODY="${TMPDIR:-/tmp}/pa-{NUMBER}.md"; gh issue view {NUMBER} {GH_FLAG} --json body --jq .body > "$PA_BODY" 2>/dev/null
+  PA=$(node "$(forge_resolve prior-attempts.mjs)" --repo {GH_REPO} --issue {NUMBER} --body-file "$PA_BODY" \
+    --title "$(gh issue view {NUMBER} {GH_FLAG} --json title --jq .title)" || true)
+  case "$PA" in *"| #"*) RECALL_RESULTS="$PA" ;; esac
+  # → Skip Steps 2-3; inject RECALL_RESULTS (the ## Prior Attempts table) via Step 4, then Phase 1A
 fi
 ```
 
@@ -462,6 +470,10 @@ fi
 
 **Mission**: Validate whether the issue is real. Assume description is wrong until proven otherwise.
 
+### Route-adding fixes: trace the production ingress (forge#5087)
+
+When the fix adds or relies on an HTTP route, trace the request from the production ingress inward, using the repo's declared topology (`forge.yaml topology`, ingress/proxy config such as Traefik or nginx), and cite the ingress rule that delivers each path to the service that implements it. "The app config rewrites it" (Next.js rewrites, filesystem-route precedence) is not evidence of production routing: flag it as insufficient. Existing handlers cited as a "working pattern" need the same check.
+
 ### Resolve target repo and branch
 
 The target repo is `{GH_REPO}` (resolved from `forge.yaml → project`). The working directory is `{REPO_PATH}` (resolved from `forge.yaml → paths.root`).

package/docs/CONFIG.md

@@ -717,6 +717,8 @@ issue_watch:
 | `mode` | string | No | `per-issue` (default), `batch` or `release` (pool, then cut themed releases). |
 | `parallel` | integer | No | K of the batch in `batch` mode. Default 4. |
 | `include_followups` | string | No | `none` (default) or `defer-only`. |
+| `trust_app` | boolean | No | Claim issues authored by this repo's ForgeDock App. Other bots and `NONE`-association authors stay untrusted. Default false. |
+| `trust_app_labels` | list | No | Needs `trust_app`: an App-authored issue must carry one of these labels. |
 | `postdeploy_rollup` | issue number | No | Release issue that collects post-deploy-only follow-ups as checklist lines. |
 | `sweep_needs_human` | boolean | No | Also settle `needs-human` escalations that predate the watch (the backlog). Default false; `forgedock issue-watch run --dry-run` classifies them first and writes nothing. |
 | `max_launches` | integer | No | Total lane launches (claims plus requeues by the decision engine); at N the watch drains. Default: none. Decision-stage issues also count against `max_issues`. |
@@ -730,11 +732,21 @@ issue_watch:
 
 ## `followups` (OPTIONAL)
 
-Deferred follow-ups (`scripts/file-deferred-followups.sh`) are filed as one issue per class per parent: `engineering`, `post-deploy`, `external` and `ops`. Each carries the label `followup:<class>` (`external` also `external-prerequisite`, and states the parent it is a prerequisite of) and inherits the parent's milestone. A requirement may set an optional `class` in the contract; otherwise `post-deploy` items are `post-deploy` and the rest `engineering`. A parent milestone that has shipped (closed) is replaced by the next open milestone by due date, else `followups.default_milestone`.
+Deferred follow-ups (`scripts/file-deferred-followups.sh`) are routed by kind (#5078):
+
+| Kind | Where it goes |
+|---|---|
+| Post-promotion, production-verify, rollout-promote (`post-deploy`, `owner:orchestrator`, `owner:promote:<flag>`, or an owner why such as "after release", "rollout", "purge") | A checklist line in the repo's ONE open post-deploy rollup (`FORGE:POSTDEPLOY_ROLLUP`, else the lowest open issue labelled `followups.rollup_issue_label`). Never a new issue when one is open. |
+| Read-only production data or capture (bucket `host`, or an owner why naming obs-psql, a `*-monitor` or a read-only prod query) | Class `host`: added to the parent's engineering follow-up of the same run, else one per-parent follow-up. Labels `followup:host` and `host-task`, never `needs-human`. |
+| Truly external (credentials, spend, an account, a third party, a customer) | ONE issue per batch (`FORGE:EXTERNAL_BATCH: <batch id>`) holding every item under a `### #<parent>` heading, labelled `followup:external`, `external-prerequisite` and `needs-human`. |
+| Engineering | The parent's open follow-up when one exists, else one issue per parent with all its items together. `ops` and `verify-now` also keep one issue per parent. |
+
+Each issue carries the label `followup:<class>` and inherits the parent's milestone. A requirement may set an optional `class` in the contract. Otherwise `post-deploy` items are `post-deploy` and the rest `engineering`. A parent milestone that has shipped (closed) is replaced by the next open milestone by due date, else `followups.default_milestone`. The batch report lists `follow-ups appended: #N (<class>: k item(s) from #a,#b)` per issue, not "issues filed".
 
 ```yaml
 followups:
-  default_milestone: "Backlog"   # optional: milestone title used when the parent's milestone has shipped and no later one is open
+  default_milestone: "Backlog"     # optional: milestone title used when the parent's milestone has shipped and no later one is open
+  rollup_issue_label: post-deploy  # optional: a repo's own open issue with this label is the post-deploy rollup when no marked one is open
 ```
 
 ## `rollouts` (OPTIONAL)
@@ -888,6 +900,7 @@ verify:
   guard_command:                # optional; per-extension command for the guard gate's base test files
     ".py": "scripts/pytest {path}"
   e2e: auto                     # optional e2e merge gate: auto (default) | always | never
+  precheck_block: false         # optional (#5079); true: a declared pre-PR check still failing after the fix round (or a round with no commit) ends the lane needs-human ci.red (recoverable) instead of opening the PR with an anomaly
   e2e_label: full-ci            # PR label that makes the repo's CI run e2e (label path)
   e2e_checks: "e2e"             # check names of the e2e jobs the label path waits on
   # e2e_workflow: e2e.yml       # or: a workflow_dispatch workflow that runs e2e (wins over the label)
@@ -1018,6 +1031,7 @@ execution:
 | `budget_minutes`, `budget_usd` | number | No | The `execution.budget` per batch: once the batch's sandbox minutes / estimated USD (settled lanes plus the running ones' elapsed time) reach the cap, no new remote lane is admitted. Missing, non-numeric or negative means no cap. |
 | `day_budget_minutes`, `day_budget_usd` | number | No | The same cap per host UTC day, summed over every batch on the host from the host-day store (`execution-budget.json` in `~/.forge/sched/`, or `FORGEDOCK_EXECUTION_BUDGET_FILE`). A corrupt or unreadable store refuses remote lanes while a day cap is set; remove the file to reset it. |
 | `fallback_local` | boolean | No | `true`: a remote-placed lane runs on the host while the provider reports no agent online (`GET {endpoint}/status -> {"online": N}`, the built-in router answers it with `online`, `total` and per-agent `ok`/`paused`), so a batch completes locally with every pool agent offline or asleep (forge#4547). Default `false`: such lanes defer (`sandbox.capacity`). A missing or failing `/status` is unknown and never triggers it. |
+| `account_rotator` | string | No | `tokenbaton`: the `claude` on PATH is the tokenbaton shim, which runs each call on the logged-in account with the most room (`CLAUDE_CONFIG_DIR=~/.claude-<n>`) (forge#5094). forgedock reads `~/.tokenbaton/current` (the account number) and `~/.tokenbaton/live.<n>` (`<5h used %> <5h reset s> <weekly used %> <weekly reset s> <updated s>`), re-read on every check and never written. An account has headroom when its 5-hour use is under 95% and its weekly use under 100% (a window whose reset has passed counts as 0). While any account has headroom no host-wide usage hold is recorded and admissions continue; they stop only when every account is exhausted and resume when the first one resets. A lane whose call hits a usage limit retries that same call (same session) on the next account at once, at most once per account, before it pauses or defers. `forgedock limits show` lists each account's 5-hour use. Any other value, or unreadable files: off (per-account holds as before). |
 | `warm_sandboxes` | integer | No | Warm sandboxes per repo the pool agent keeps ready (checkout at the base ref, dependency cache primed). When `N > 0` the launch spec carries `warm: N` and the lane first calls `POST {endpoint}/sandboxes/claim`; a ready warm sandbox takes the lane (refreshed to the lane's base ref with an incremental fetch before work starts), and when none is ready, the claim fails or the endpoint lacks the route the lane starts cold. Default `0` (off): no claim call and the launch spec is unchanged (forge#4912). |
 | `unreachable_window_min` | number | No | Remote providers: how long a lane keeps polling (with backoff, up to 30s) after the provider's transport fails (connection refused/reset, `fetch failed`, timeout, 502/503/504) before it ends `deferred` with `sandbox.unreachable` (forge#4672). Inside the window the lane never ends and the sandbox is never torn down; after it the sandbox is kept and adopted on the next attempt or `--resume`; the engine-error breaker does not count it. `adopt` applies the same window. Default: 5 |
 | `on_budget` | string | No | `stop` (default): running lanes finish and the rest end `held` (`execution budget: ...`) for a later `--resume`. `local`: the rest run as detached host lanes. |
@@ -1343,6 +1357,9 @@ verification:
   test_runners:            # path prefix -> runner command prefix (block-style map)
     services/worker: "poetry -C services/worker run"
     web: "pnpm --filter web exec"
+
+topology:
+  route_reachability: "bash scripts/check-ingress.sh"   # optional; blocking when declared
 ```
 
 | Field | Type | Required | Description |
@@ -1360,7 +1377,9 @@ verification:
 | `consumer_sweep.mode` | string | No | `advisory` (default): the validate consumer sweep (`scripts/consumer-sweep.sh`, V4.6) records unaddressed referencing sites and never fails. `blocking`: unaddressed sites fail validate with `consumer_unaddressed`, build runs one repair round, and sites still unaddressed are recorded as `CONSUMERS: unresolved` and passed to review as known risk (never `needs-human`). Flip to `blocking` only after `bash scripts/consumer-sweep.sh --eval-history 20` shows a mean of at most 2 flagged sites per merge and none above 10 on your repo |
 | `consumer_sweep.budget_seconds` | integer | No | Wall-clock budget for the sweep (default `60`). When it runs out the sweep stops with `BUDGET_EXCEEDED`, reports the partial result, and never fails, in either mode |
 | `test_runners` | map (path prefix → runner) | No | Default unset (no runner enforced). For repos whose validate commands need a managed runner (uv, poetry, pnpm workspace). The lean engine checks it at contract freeze (`testRunnerProblems`, `bin/lean/preflight.mjs`): a validate command that touches a configured path prefix without containing that prefix's runner string is reported as a contract problem, instead of failing later as `contract.invalid_command` / `env.tool_missing`. Paths in the command are relative to the runner's cwd. Write it as a block-style map: `parseForgeYaml` does not read inline `{ ... }` maps. |
+| `coupled_files` | map (glob → glob list) | No | Default unset (#5079). "If file A changes, file B must change": a block map `{when glob: required glob[, glob]}`, e.g. `"infra/guard/bootstrap.sh": "infra/guard/MANIFEST.sha256"`. A key prefixed `added:` fires only for files the lane adds (`"added:scripts/tests/test_*.py": ".github/workflows/ci.yml"`). A lane that changes a `when` file without a matching required file fails precheck with `coupled_file_missing` (`conformance.unimplemented`, builder resumed once). Quote keys that contain `*`, and list alternatives as separate keys: brace globs (`*.{ts,tsx}`) are not expanded. |
 | `validate.recipes` | map (regex → replacement) | No | Default unset. A top-level `validate:` block with a block-style `recipes:` map, e.g. `"poetry run pytest": "uv run --with-requirements r.txt pytest"`. Each key is a regex source; the first recipe that matches a frozen validate or `repro_test` command rewrites it at contract freeze (`applyValidateRecipes`), recorded as a decision. Use it for commands whose environment is not installed in lane sandboxes. |
+| `topology.route_reachability` | string (command) | No | Default unset (no check, no behaviour change). A repo-supplied command that takes the route paths a diff adds (Next.js `app/**/route.*`, `pages/api/**`; URL form, route groups removed) as arguments and exits non-zero when the production ingress does not deliver them to the service that implements them. Runs in the lean lane after validate and in `review-pr-staging`; a non-zero exit blocks (`conformance.unimplemented`, kind `route_unreachable`). Read by `readEnvConfig` (`bin/engine-cli.mjs`), run by `bin/lean/routecheck.mjs`. |
 
 **Commands that use this section**: `quality-gate`, `validate` (V2 runs `verification.commands`; V4.8 runs the local CI gate; health checks and `consumer_sweep`), `work-on`