forgedock 1.46.0 → 1.47.0

package/bin/lean/rotator.mjs

@@ -0,0 +1,96 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Account rotators (#5094). With `execution.account_rotator: tokenbaton`, the `claude` on PATH is a shim that runs every
+ * call on the logged-in account with the most room (`CLAUDE_CONFIG_DIR=~/.claude-<n>`), so an exhausted account is not an
+ * exhausted host. This adapter reads tokenbaton's per-account quota state: `~/.tokenbaton/current` (the account number)
+ * and `~/.tokenbaton/live.<n>` (`"<5h used %> <5h reset epoch s> <weekly used %> <weekly reset epoch s> <updated s>"`).
+ * Every method re-reads the files (no cache), never writes, and fails open: unreadable state behaves as no rotator.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { backendIdentity } from "../engine.mjs";
+
+export const ROTATOR_KINDS = ["tokenbaton"];
+/** An account has headroom below this 5-hour use (%), like the computeshare quota-aware picker. */
+export const HEADROOM_PCT = 95;
+
+/** One `live.N` line as numbers, or null when malformed. */
+export function parseLive(text) {
+  const f = String(text ?? "").trim().split(/\s+/).map(Number);
+  if (f.length < 4 || !f.slice(0, 4).every(Number.isFinite)) return null;
+  return { fiveHourPct: f[0], fiveHourResetMs: f[1] * 1000, weeklyPct: f[2], weeklyResetMs: f[3] * 1000 };
+}
+
+/**
+ * Handle on an account rotator, or null (unknown kind, or no readable state).
+ * @returns {null | {kind, accounts, current(), headroom(), resumeAt(), accountIdentity(n), currentIdentity(), isAccount(id)}}
+ */
+export function openRotator({ kind, home = homedir(), env = process.env, now = () => Date.now(), readFile = (p) => readFileSync(p, "utf8"), listDir = (d) => readdirSync(d) } = {}) {
+  if (!ROTATOR_KINDS.includes(kind)) return null;
+  const dir = join(home, ".tokenbaton");
+  const current = () => { try { const n = Number(String(readFile(join(dir, "current"))).trim()); return Number.isInteger(n) && n > 0 ? n : null; } catch { return null; } };
+  const accounts = () => {
+    let names = [];
+    try { names = listDir(dir); } catch { return []; }
+    const out = [];
+    for (const name of names) {
+      const m = /^live\.(\d+)$/.exec(name);
+      if (!m) continue;
+      let live = null;
+      try { live = parseLive(readFile(join(dir, name))); } catch { live = null; }
+      if (live) out.push({ n: Number(m[1]), ...live });
+    }
+    return out.sort((a, b) => a.n - b.n);
+  };
+  if (current() === null || !accounts().length) return null;
+  const used = (pct, resetMs) => (resetMs <= now() ? 0 : pct);
+  const hasRoom = (a) => used(a.fiveHourPct, a.fiveHourResetMs) < HEADROOM_PCT && used(a.weeklyPct, a.weeklyResetMs) < 100;
+  const accountIdentity = (n) => backendIdentity({ backend: "cli", env: { ...env, CLAUDE_CONFIG_DIR: join(home, `.claude-${n}`) } });
+  return {
+    kind,
+    /** The accounts with readable `live.N` state, re-read on every access. */
+    get accounts() { return accounts(); },
+    current,
+    /** True when any account has headroom. */
+    headroom: () => accounts().some(hasRoom),
+    /** Epoch ms at which the first account regains headroom (now when one has it), or null when unknown. */
+    resumeAt: () => {
+      const t = now(), at = accounts().map((a) => {
+        if (hasRoom(a)) return t;
+        const r = [];
+        if (used(a.fiveHourPct, a.fiveHourResetMs) >= HEADROOM_PCT) r.push(a.fiveHourResetMs);
+        if (used(a.weeklyPct, a.weeklyResetMs) >= 100) r.push(a.weeklyResetMs);
+        return Math.max(...r);
+      }).filter((x) => Number.isFinite(x) && x > 0);
+      return at.length ? Math.min(...at) : null;
+    },
+    accountIdentity,
+    /** Identity of the current account; null when `current` is unreadable. */
+    currentIdentity: () => { const n = current(); return n === null ? null : accountIdentity(n); },
+    /** True when `id` is the identity of one of the rotator's accounts. */
+    isAccount: (id) => typeof id === "string" && accounts().some((a) => accountIdentity(a.n) === id),
+  };
+}
+
+/** True while a usage-limited call should be retried at once on the next account: headroom, and fewer tries than accounts. */
+export function rotatorRetry(rotator, tries) {
+  try { return Boolean(rotator) && tries < rotator.accounts.length && rotator.headroom(); } catch { return false; }
+}
+
+/**
+ * How orchestrate requeues a `rate_limited` lane under a rotator (#5094), or null when the host hold applies (no rotator,
+ * no account with headroom, unreadable state). A lane that ran on one of the rotator's accounts (or reported none) is rerun
+ * at once, at most once per account; any other credential (a remote sandbox's) waits for its own reset. Neither sets a host hold.
+ * @returns {null | {delayMs:number, rotated:boolean}}
+ */
+export function quotaRequeue({ rotator, r, prior = null, delayMs }) {
+  if (!rotator) return null;
+  try {
+    if (!rotator.headroom()) return null;
+    const id = r?.backendId ?? null, rotations = Number(prior?.rotations) || 0;
+    if ((!id || rotator.isAccount(id)) && rotations < rotator.accounts.length) return { delayMs: 0, rotated: true };
+    return { delayMs, rotated: false };
+  } catch { return null; }
+}

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`).