forgedock 1.46.0 → 1.47.0

package/bin/lean/execution.mjs

@@ -20,8 +20,10 @@
  *
  * `remote` (#4254, sandbox-remote.mjs) reaches a runner pool or remote session through a transport (`execution.endpoint`,
  * credential `execution.token_env` from the env or the keychain). It is never a default, and a GitHub Actions endpoint
- * needs `allow_actions: true`. A sandbox that fails to start is a typed outcome, not an engine-error: `needs-human`
- * `sandbox.start_failed`, or `deferred` `sandbox.capacity` when the provider marks the error retryable. A provider that
+ * needs `allow_actions: true`. A sandbox that fails to start is a typed outcome, not an engine-error: `deferred` `sandbox.capacity`
+ * when the provider marks the error retryable (429/503), `deferred` `sandbox.transient` for any other 5xx (#5095), `deferred`
+ * `sandbox.auth` for 401/403, else `needs-human` `sandbox.start_failed` (a 4xx config error). #5095: a sandbox that exits without
+ * a result while its log tail shows a usage limit ends `deferred` `rate_limited` held under `remoteHoldId` (never the breaker). A provider that
  * sets `handle.minutes` (billable sandbox minutes) has them used as the lane's sandbox minutes (#4255 below).
  *
  * Sandbox cost and budget (#4255): a provider may implement `usage(handle, {startedAt, endedAt}) -> {minutes, cost_usd}`;
@@ -60,6 +62,7 @@ import { classifyStep, heavyConfig, memAvailableMb } from "./heavy.mjs";
 import { detectPins } from "./toolchain.mjs";
 import { parseContractComment, noComments } from "./render.mjs";
 import { parseRelayCommands } from "./relay.mjs";
+import { detectUsageLimit, parseSessionLimitResetEpochMs } from "../runner.mjs";
 
 export const EXECUTION_MODES = Object.freeze(["local", "remote", "hybrid"]);
 export const SANDBOX_PROVIDERS = Object.freeze(["local", "container", "remote", "pool"]);
@@ -128,8 +131,9 @@ export function parseExecution(sec = {}) {
   const warmSandboxes = str(s.warm_sandboxes) !== "" && Number.isInteger(wsN) && wsN > 0 ? wsN : 0; // #4912: warm sandboxes the pool agent keeps ready; 0 = off
   const relay = Object.fromEntries(Object.entries(parseRelayCommands(s.relay_commands)).filter(([c]) => CAPABILITY_RE.test(c))); // #4778
   const uw = Number(str(s.unreachable_window_min));
+  const accountRotator = str(s.account_rotator) === "tokenbaton" ? "tokenbaton" : null; // #5094: rotator.mjs reads its per-account quota state
   const unreachableWindowMin = str(s.unreachable_window_min) !== "" && Number.isFinite(uw) && uw >= 0 ? uw : null; // unset: providerLanes defaults to 5
-  return { mode, maxRemote, provider, image, secrets, budget, ...(hostCapabilities.length ? { hostCapabilities } : {}), ...(hostCapabilityPatterns.length ? { hostCapabilityPatterns } : {}), ...(endpoint ? { endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(cacheStore ? { cacheStore } : {}), ...(allowActions ? { allowActions } : {}), ...(fallbackLocal ? { fallbackLocal } : {}), ...(heavy !== null ? { heavy } : {}), ...(unreachableWindowMin !== null ? { unreachableWindowMin } : {}), ...(Object.keys(relay).length ? { relay } : {}), ...(warmSandboxes ? { warmSandboxes } : {}) };
+  return { mode, maxRemote, provider, image, secrets, budget, ...(hostCapabilities.length ? { hostCapabilities } : {}), ...(hostCapabilityPatterns.length ? { hostCapabilityPatterns } : {}), ...(endpoint ? { endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(cacheStore ? { cacheStore } : {}), ...(allowActions ? { allowActions } : {}), ...(fallbackLocal ? { fallbackLocal } : {}), ...(heavy !== null ? { heavy } : {}), ...(unreachableWindowMin !== null ? { unreachableWindowMin } : {}), ...(Object.keys(relay).length ? { relay } : {}), ...(warmSandboxes ? { warmSandboxes } : {}), ...(accountRotator ? { accountRotator } : {}) };
 }
 
 const round1 = (x) => Math.round(x * 10) / 10;
@@ -206,7 +210,7 @@ export function placement(exec) {
 /** Host-only capabilities and the issue-text signals that mean a lane needs them (#4542). */
 const CAPABILITY_SIGNALS = Object.freeze({
   sops: /\.secrets\/[^\s`'")]*\.enc\.ya?ml|\bsops\b|\bage key\b|\.age\//i,
-  prod_monitor: /\bssh\s+[\w.-]*-monitor\b|\b(?:ovh|netcup)-monitor\b|\bobs-psql\b|\bprod(?:uction)? monitor/i,
+  prod_monitor: /\bssh\s+[\w.-]*-monitor\b|\b(?:ovh|netcup)-monitor\b|\bobs-psql\b|\bprod(?:uction)?[ _-]monitor|\bread[- ]only (?:prod(?:uction)? )?(?:prod(?:uction)? )?telemetry\b/i,
   ops_credentials: /\bcredentials\.yaml\b|\bops[ _-]credentials\b/i,
 });
 
@@ -225,7 +229,8 @@ export function detectNeeds(text, exec = null) {
 
 /** Declared host capabilities a remote lane's block summary names (#4542); empty when it names none the host has. */
 export function hostCapabilityBlock(summary, caps = null) {
-  const have = new Set(caps?.hostCapabilities ?? []);
+  // #5080: with no declared capabilities, the read-only prod monitor (the dispatching host's, never a secret) still counts
+  const have = new Set(caps?.hostCapabilities?.length ? caps.hostCapabilities : ["prod_monitor"]);
   const named = detectNeeds(summary, caps);
   return named.length && named.every((n) => have.has(n)) ? named : [];
 }
@@ -531,17 +536,33 @@ export function providerByName(name, opts) {
   throw e;
 }
 
+/** #5095: the usage-limit hold key of a remote provider's account (the pool's), known to the dispatcher before any lane runs. */
+export const remoteHoldId = (provider) => `remote:${String(provider?.name ?? "remote")}`;
+const TRANSIENT_RETRY_S = 60;
+const LIMIT_RE = /usage limit hit; resets at ([^\n;]+)/i;
+const RESETS_RE = /\bresets?\s+(?:at\s+)?(\d{1,2}(?::\d{2})?\s*[ap]m\s*\([^)]+\)|\d{1,2}:\d{2}\s*\([^)]+\))/i;
+/** #5095: the usage-limit reset text in a lane log tail (the lean finish line, else the CLI's own limit message), or null. */
+export function usageLimitInTail(tail) {
+  const t = String(tail ?? "");
+  const lean = LIMIT_RE.exec(t);
+  if (lean) return { resetAt: lean[1].trim() };
+  if (!detectUsageLimit("", t)) return null;
+  return { resetAt: RESETS_RE.exec(t)?.[1]?.trim() ?? null };
+}
+
 /**
  * Lane seams for `orchestrate()` over a provider, the same contract as batch.mjs `detachedLanes`. `ledgerFor(issue)`
- * returns that sandbox's ledger (ledger.mjs `makeLedger`).
+ * returns that sandbox's ledger (ledger.mjs `makeLedger`). #5095: with `holdId` every `rate_limited` result is held under it
+ * (`backendId`; the sandbox's own id kept as `laneBackendId`), so orchestrate can place lanes away from a limited pool.
  */
 export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env, secrets = [], pollMs = 5000, sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
-  costPerMinute = 0, now = () => Date.now(), unreachableWindowMs = 300000, logTail = null }) {
+  costPerMinute = 0, now = () => Date.now(), unreachableWindowMs = 300000, logTail = null, holdId = null }) {
   const cpm = nonNeg(Number(costPerMinute)) ?? 0;
   // #4255: the sandbox's usage: the provider's `usage()`, else the billable minutes it put on the handle (#4254), else wall
   // clock since the handle's startedAt; cost is the provider's, else minutes x cost_per_minute.
   const withUsage = async (r, h) => {
     if (!r || typeof r !== "object") return r;
+    if (holdId && r.code === OUTCOME_CODES.RATE_LIMITED) r = { ...r, backendId: holdId, ...(r.backendId && r.backendId !== holdId ? { laneBackendId: r.backendId } : {}) };
     const endedAt = now(), startedAt = Number.isFinite(h?.startedAt) ? h.startedAt : endedAt;
     let u = null;
     try { u = typeof provider.usage === "function" ? await provider.usage(h, { startedAt, endedAt }) : null; } catch { u = null; }
@@ -585,7 +606,15 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
         const last = await g(() => provider.fetchResult(h)); // it may have written the result just before exiting
         if (last) return last;
         const why = `sandbox ${h.id} ${st} without a result`;
-        return isCloneFailure(await tailOf(h)) ? cloneDeferred(h.id, why) : { terminalReason: "engine-error", detail: why };
+        const tail = await tailOf(h);
+        // #5095: the pool account hit its usage limit: a known-time wait (held, never the breaker), not an engine-error
+        const lim = usageLimitInTail(tail);
+        if (lim) {
+          const at = lim.resetAt ? parseSessionLimitResetEpochMs(lim.resetAt, now()) : undefined;
+          return { terminalReason: "deferred", code: OUTCOME_CODES.RATE_LIMITED, resetAt: lim.resetAt ?? "unknown", resetAtEpochMs: Number.isFinite(at) ? at : null,
+            detail: `${why}: usage limit hit; resets at ${lim.resetAt ?? "unknown"}` };
+        }
+        return isCloneFailure(tail) ? cloneDeferred(h.id, why) : { terminalReason: "engine-error", detail: why };
       }
       await sleep(pollMs);
     }
@@ -596,6 +625,10 @@ export function providerLanes({ provider, laneArgs, ledgerFor, env = process.env
     ? { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_AUTH, retryInSeconds: 300, detail: `sandbox ${id} could not start (auth): ${errText(e)}; ${e?.hop === "agent" ? "the pool agent refused the router (re-enroll or fix the agent token)" : "check the pool token (COMPUTESHARE_TOKEN or ~/.config/computeshare/forgedock.token)"}` }
     : e?.retryable === true
     ? { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_CAPACITY, detail: `sandbox ${id} could not start (capacity): ${errText(e)}`, ...(Number(e.retryInSeconds) > 0 ? { retryInSeconds: Number(e.retryInSeconds) } : {}) }
+    // #5095: a 5xx from the pool router or agent is infrastructure: deferred with backoff (capped), never needs-human
+    : (Number.isInteger(e?.status) && e.status >= 500 && e.status <= 599) || e?.transient === true
+    ? { terminalReason: "deferred", code: OUTCOME_CODES.SANDBOX_TRANSIENT, retryInSeconds: Number(e.retryInSeconds) > 0 ? Number(e.retryInSeconds) : TRANSIENT_RETRY_S,
+      detail: `sandbox ${id} could not start (transient${Number.isInteger(e?.status) ? ` HTTP ${e.status}` : ""}): ${errText(e)}` }
     : isCloneFailure(errText(e)) ? cloneDeferred(id, errText(e))
     : { terminalReason: "needs-human", code: OUTCOME_CODES.SANDBOX_START_FAILED, detail: `sandbox ${id} failed to start: ${errText(e)}` });
   return {

package/bin/lean/execution.test.mjs

@@ -7,7 +7,7 @@ import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
 import { renderContract } from "./render.mjs";
-import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placementText, contractHostNeeds, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, isTransportError, isCloneFailure, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
+import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placementText, contractHostNeeds, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, remoteHoldId, usageLimitInTail, isTransportError, isCloneFailure, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
 import { makeLedger, countLiveLanes } from "./ledger.mjs";
 import { openBatch } from "./batch.mjs";
 import { orchestrate, formatTable, formatSandboxSummary } from "./orchestrate.mjs";
@@ -25,7 +25,7 @@ function fakeProvider(opts = {}) {
     async start({ issue, env, secrets }) {
       p.calls.push(["start", issue]);
       p.ledgerAtStart = opts.ledger?.entries("sandbox").map((e) => e.value) ?? null;
-      if (opts.startThrows) throw Object.assign(new Error("boom: no capacity"), opts.startThrows === 401 ? { status: 401 } : {});
+      if (opts.startThrows) throw Object.assign(new Error("boom: no capacity"), typeof opts.startThrows === "number" ? { status: opts.startThrows } : {});
       p.live.add(issue);
       p.env = env; p.secrets = secrets;
       if (opts.finish) { const r = opts.finish(issue); if (r !== undefined) { p.results[issue] = r; p.live.delete(issue); } }
@@ -757,6 +757,14 @@ describe("host capabilities in placement (#4542)", () => {
     assert.deepEqual(hostCapabilityBlock("owner must create an account", caps), []);
   });
 
+  it("#5080 the read-only prod monitor is a host capability by its own name or as read-only production telemetry, declared or not", () => {
+    const text = "D1 is gated by contract decision K1 on read-only production telemetry: a host-only prod_monitor capability this sandbox lacks";
+    assert.deepEqual(detectNeeds(text), ["prod_monitor"]);
+    assert.deepEqual(hostCapabilityBlock(text, null), ["prod_monitor"]);
+    assert.deepEqual(hostCapabilityBlock(text, { hostCapabilities: ["sops"] }), []);
+    assert.deepEqual(hostCapabilityBlock("no sops key", null), []);
+  });
+
   it("#4785 placementText: body, FORGE:DECISION comments and the last frozen contract's validate commands", () => {
     const exec = parseExecution({ mode: "remote", max_remote: 2, host_capabilities: "promtool" });
     const k = (cmd) => "<!-- FORGE:CONTRACT -->\n<!-- FORGE:PLAN -->\n" + renderContract({ requirements: [], deliverables: [], validate: [{ id: "V1", command: cmd }] }, "abcdef123456");
@@ -831,3 +839,65 @@ describe("host capabilities in placement (#4542)", () => {
     assert.equal(rows.find((r) => r.issue === 5).outcome, "merged");
   });
 });
+
+describe("#5095: launch 5xx and a pool usage limit are deferred, never needs-human or engine-error", () => {
+  const lanesFor = (prov, extra = {}) => providerLanes({ provider: prov, laneArgs: () => [], ledgerFor: ledgerIn(tmpDir("exec-5095-")), pollMs: 1, now: () => 1000, sleep: async () => {}, ...extra });
+
+  it("#5095 start HTTP 5xx (500/502/504): deferred with a retry delay, never needs-human", async () => {
+    for (const status of [500, 502, 504]) {
+      const r = await lanesFor(fakeProvider({ startThrows: status })).runOne(7, null);
+      assert.equal(r.terminalReason, "deferred", `HTTP ${status}`);
+      assert.equal(r.code, "sandbox.transient");
+      assert.equal(r.retryInSeconds, 60);
+      assert.match(r.detail, new RegExp(`HTTP ${status}`));
+    }
+    // a Retry-After the pool sent wins over the default delay
+    const prov = fakeProvider();
+    prov.start = async () => { throw Object.assign(new Error("sandbox launch: HTTP 500"), { status: 500, transient: true, retryInSeconds: 12 }); };
+    assert.equal((await lanesFor(prov).runOne(7, null)).retryInSeconds, 12);
+  });
+
+  it("a non-auth 4xx config error stays needs-human sandbox.start_failed; 429/503 stay sandbox.capacity", async () => {
+    const r = await lanesFor(fakeProvider({ startThrows: 422 })).runOne(7, null);
+    assert.deepEqual([r.terminalReason, r.code], ["needs-human", "sandbox.start_failed"]);
+    const prov = fakeProvider();
+    prov.start = async () => { throw Object.assign(new Error("sandbox launch: HTTP 503"), { status: 503, transient: true, retryable: true }); };
+    assert.equal((await lanesFor(prov).runOne(7, null)).code, "sandbox.capacity");
+  });
+
+  it("usageLimitInTail reads the lean finish line and the CLI's own limit message", () => {
+    assert.deepEqual(usageLimitInTail("x\n[lane] deferred: usage limit hit; resets at 3:20pm (UTC)\n"), { resetAt: "3:20pm (UTC)" });
+    assert.equal(usageLimitInTail("sandbox exited 1\nclone ok"), null);
+    assert.equal(usageLimitInTail(""), null);
+  });
+
+  it("a remote lane with no result and a usage limit in its log tail ends deferred rate_limited, held under the pool id, and never trips the breaker", async () => {
+    const prov = fakeProvider({ finish: () => null });
+    const holdId = remoteHoldId(prov);
+    assert.equal(holdId, "remote:fake");
+    const lanes = lanesFor(prov, { holdId, logTail: async () => "building...\nusage limit hit; resets at 3:20pm (UTC)\n" });
+    const r = await lanes.runOne(7, null);
+    assert.equal(r.terminalReason, "deferred");
+    assert.equal(r.code, "rate_limited");
+    assert.equal(r.resetAt, "3:20pm (UTC)");
+    assert.ok(Number.isFinite(r.resetAtEpochMs));
+    assert.equal(r.backendId, "remote:fake");
+    assert.ok(prov.calls.some((c) => c[0] === "teardown"));
+    // the same lane ends through orchestrate: a breaker of one engine-error never trips, the issue is requeued behind the hold
+    let t = 0, calls = 0;
+    const rows = await orchestrate({ issues: [7], parallel: 1, readBody: async () => "", now: () => t, sleep: async (ms) => { t += ms ?? 1; }, pollMs: 1,
+      breaker: { errors: 1, window_min: 30 }, identity: () => "local",
+      runOne: async () => (++calls === 1 ? { ...r, resetAtEpochMs: t + 60_000 } : { terminalReason: "merged", pr: 1 }) });
+    assert.ok(!rows.some((x) => x.outcome === "breaker"), "a usage limit is not an engine-error");
+    assert.equal(rows.find((x) => x.issue === 7).outcome, "merged");
+  });
+
+  it("a sandbox's own rate_limited result is held under the pool id, its own id kept as laneBackendId", async () => {
+    const prov = fakeProvider({ finish: () => ({ terminalReason: "deferred", code: "rate_limited", backendId: "cli:abc", resetAtEpochMs: 5000 }) });
+    const r = await lanesFor(prov, { holdId: remoteHoldId(prov) }).runOne(7, null);
+    assert.deepEqual([r.backendId, r.laneBackendId], ["remote:fake", "cli:abc"]);
+    // without a usage-limit signature the no-result path stays engine-error
+    const plain = await lanesFor(fakeProvider({ finish: () => null }), { logTail: async () => "exit 1" }).runOne(7, null);
+    assert.equal(plain.terminalReason, "engine-error");
+  });
+});

package/bin/lean/integration.mjs

@@ -14,7 +14,7 @@
  *   or over N, until a green run.
  * The workflow is dispatched on the milestone branch and awaited through runCiVerify (verify.mjs).
  */
-import { milestoneSlug, readBranches, DEFAULT_FEATURE_PATTERN } from "./lane.mjs";
+import { listMilestones, milestoneSlug, readBranches, DEFAULT_FEATURE_PATTERN } from "./lane.mjs";
 import { readMilestone } from "./drift.mjs";
 import { runCiVerify } from "./verify.mjs";
 import { parseForgeYaml } from "../forge-utils.mjs";
@@ -174,7 +174,7 @@ export async function runMilestone({ io, repo, ms, cfg, pattern, nowFn = () => D
 
 /** Every open milestone → {number, title, description}. */
 export async function listOpenMilestones({ gh, repo }) {
-  return arr(JSON.parse(String(await gh(["api", `repos/${repo}/milestones?state=open&per_page=100`])) || "[]")).map((m) => ({ number: m.number, title: m.title, description: m.description ?? "" }));
+  return arr(await listMilestones({ gh, repo, state: "open" })).map((m) => ({ number: m.number, title: m.title, description: m.description ?? "" }));
 }
 
 /** Run every due active milestone (optionally only `only`, a title). Sequential: one suite at a time. Resolves the per-milestone results. */

package/bin/lean/integration.test.mjs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { parseIntegration, parseIntegrationState, renderState, isDue, failingSpecs, runMilestone, runIntegration, makeIntegration, runIntegrationCli, emptyState } from "./integration.mjs";
+import { parseIntegration, parseIntegrationState, renderState, isDue, failingSpecs, runMilestone, runIntegration, makeIntegration, runIntegrationCli, emptyState, listOpenMilestones } from "./integration.mjs";
 import { orchestrate } from "./orchestrate.mjs";
 
 const SHA = "a".repeat(40), SHA2 = "b".repeat(40);
@@ -187,3 +187,24 @@ describe("integration status", () => {
     assert.equal(off.length, 1, "without ci.workflow only milestones with a state block");
   });
 });
+
+/** #5084: a GitHub-like milestones endpoint: pages of 100; without --paginate only page 1; `--jq '.[] | @json'` prints one object per line. */
+const pagedMilestones = (all) => (a) => {
+  const state = /state=(\w+)/.exec(a[1])?.[1] ?? "open";
+  const items = all.filter((m) => state === "all" || m.state === state);
+  const pages = []; for (let i = 0; i < items.length; i += 100) pages.push(items.slice(i, i + 100));
+  if (!a.includes("--paginate")) return JSON.stringify(pages[0] ?? []);
+  if (a.includes("--jq")) return items.map((m) => JSON.stringify(m)).join("\n") + "\n";
+  return pages.map((p) => JSON.stringify(p)).join("");
+};
+const manyMilestones = (target, n = 120) => [...Array.from({ length: n }, (_, i) => ({ number: i + 1, title: `M ${i + 1}`, state: i % 2 ? "open" : "closed", description: "" })), { number: n + 1, ...target }];
+
+describe("listOpenMilestones pagination (#5084)", () => {
+  it("(#5084) listOpenMilestones returns open milestones past page 1", async () => {
+    const all = manyMilestones({ title: "Target", state: "open" }, 220).map((m) => ({ ...m, state: "open" }));
+    const gh = async (a) => pagedMilestones(all)(a);
+    const got = await listOpenMilestones({ gh, repo: "o/r" });
+    assert.equal(got.length, 221);
+    assert.deepEqual(got.at(-1), { number: 221, title: "Target", description: "" });
+  });
+});

package/bin/lean/lane.mjs

@@ -21,6 +21,19 @@ export function milestoneSlug(title) {
   return String(title ?? "").toLowerCase().replace(/ /g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 
+/**
+ * Every milestone of `repo` in `state` (all|open|closed), across every page (#5084: one page of 100 hid newer milestones).
+ * One `gh api --paginate` call, one object per line; a whole-JSON reply (a single array) is accepted too. gh errors propagate.
+ */
+export async function listMilestones({ gh, repo, state = "all" }) {
+  const text = String(await gh(["api", `repos/${repo}/milestones?state=${state}&per_page=100`, "--paginate", "--jq", ".[] | @json"]) ?? "").trim();
+  if (!text) return [];
+  let whole;
+  try { whole = JSON.parse(text); } catch { whole = undefined; }
+  if (whole !== undefined) return Array.isArray(whole) ? whole : whole && typeof whole === "object" ? [whole] : [];
+  return text.split("\n").map((l) => l.trim()).filter(Boolean).flatMap((l) => JSON.parse(l));
+}
+
 /** forge.yaml `branches` from the checkout: {default, staging, featurePattern}; missing keys are null. */
 export function readBranches(cwd = process.cwd()) {
   let b = {};

package/bin/lean/lane.test.mjs

@@ -4,7 +4,7 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { writeFileSync } from "node:fs";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { milestoneSlug, readBranches, resolveLane, makeLaneCache } from "./lane.mjs";
+import { milestoneSlug, readBranches, resolveLane, makeLaneCache, listMilestones } from "./lane.mjs";
 
 /** Fake gh/git: the issue's milestone, GitHub's default branch, and the branches on origin. */
 function io({ milestone = null, ghDefault = "main", onOrigin = ["staging", "main"], ghFails = null, gitFails = false } = {}) {
@@ -133,3 +133,30 @@ describe("per-batch lane lookups (#4963)", () => {
     assert.equal((await resolveLane({ issue: 1, repo: "o/r", io: io(), cwd: "/r", cache, milestone: null })).ok, true);
   });
 });
+
+describe("(#5084) listMilestones", () => {
+  it("(#5084) listMilestones pages with --paginate, path at args[1], state in the query", async () => {
+    const calls = [];
+    const gh = async (a) => { calls.push(a); return '{"number":1,"title":"A"}\n{"number":2,"title":"B"}\n'; };
+    assert.deepEqual(await listMilestones({ gh, repo: "o/r", state: "open" }), [{ number: 1, title: "A" }, { number: 2, title: "B" }]);
+    assert.equal(calls[0][1], "repos/o/r/milestones?state=open&per_page=100");
+    assert.ok(calls[0].includes("--paginate"));
+    assert.equal(calls[0][calls[0].indexOf("--jq") + 1], ".[] | @json");
+    await listMilestones({ gh, repo: "o/r" });
+    assert.match(calls[1][1], /state=all/);
+  });
+  it("(#5084) listMilestones accepts a single array, a single object and empty output", async () => {
+    assert.deepEqual(await listMilestones({ gh: async () => '[{"number":3}]', repo: "o/r" }), [{ number: 3 }]);
+    assert.deepEqual(await listMilestones({ gh: async () => '{"number":4}\n', repo: "o/r" }), [{ number: 4 }]);
+    assert.deepEqual(await listMilestones({ gh: async () => "  \n", repo: "o/r" }), []);
+    assert.deepEqual(await listMilestones({ gh: async () => "", repo: "o/r" }), []);
+  });
+  it("(#5084) listMilestones keeps a description containing '][' intact", async () => {
+    const ms = [{ number: 1, title: "A", description: "see [a][b] and ] [" }, { number: 2, title: "B", description: "]\n[" }];
+    const out = ms.map((m) => JSON.stringify(m)).join("\n");
+    assert.deepEqual(await listMilestones({ gh: async () => out, repo: "o/r" }), ms);
+  });
+  it("(#5084) listMilestones propagates a gh error", async () => {
+    await assert.rejects(listMilestones({ gh: async () => { throw new Error("HTTP 502"); }, repo: "o/r" }), /HTTP 502/);
+  });
+});

package/bin/lean/lean.mjs

@@ -15,7 +15,7 @@ import { ciPollDelayMs, ENGINE_VERSION, DEFAULT_MAX_SESSION_LIMIT_PAUSES, DEFAUL
 import { openDependency, laneMergedPrs, dependencyOnLane, isTrustedComment, decomposedSubissues, isDecomposedRecord, reopenRevokedDecomposition } from "../engine/phases.mjs";
 import { createHash, randomBytes } from "node:crypto";
 import { otherLaneOwner } from "./lanelock.mjs";
-import { applyValidateRecipes, deferChecklessPostDeploy, reproEnvMiss, resolveForgedockPaths, describesUnrunnableCommand, removedPathsOf, TRACKED, normalizeKindModes, blockingFailures, unverifiedRequirements, mutationTargets, mutationFailures, runMutationCheck, MUTATION_SURVIVED, isBugIssue, scopeText, explainFailures, inIssue, validateContract, cliUsageError, normalizeRunnerCommand, applyAmendments, precheck, repoTracks, dropScopeValidates, tagOutOfBand, parseReview, decide, mergeReviewRows, evidencePathOnly, closePlan, followupItems, bucketTally, pendingTracking, unnamedEdges, structureNote, impliedDocDeliverables } from "./conformance.mjs";
+import { applyValidateRecipes, deferChecklessPostDeploy, reproEnvMiss, resolveForgedockPaths, describesUnrunnableCommand, removedPathsOf, TRACKED, normalizeKindModes, blockingFailures, unverifiedRequirements, mutationTargets, mutationFailures, runMutationCheck, MUTATION_SURVIVED, isBugIssue, scopeText, explainFailures, inIssue, validateContract, cliUsageError, normalizeRunnerCommand, applyAmendments, amendmentKindProblems, precheck, alreadyFixedOnBase, READONLY_PROD_RE, EXTERNAL_NEED_RE, repoTracks, dropScopeValidates, tagOutOfBand, parseReview, decide, mergeReviewRows, evidencePathOnly, closePlan, followupItems, bucketTally, pendingTracking, unnamedEdges, structureNote, impliedDocDeliverables } from "./conformance.mjs";
 import { checkAdmission, hostParallelism, ADMISSION_RETRY_SECONDS } from "./admission.mjs";
 import { namedPaths, isTrustedIssueComment } from "./prefilter.mjs";
 import { checksAt } from "./postdeploy-check.mjs";
@@ -38,9 +38,11 @@ import { hostCapabilityBlock, contractHostNeeds } from "./execution.mjs";
 const MISSING_TOOL_RE = /command not found|not found in PATH|no such file or directory.*\b(?:docker|promtool)\b|\b(?:docker|promtool)\b[^\n]{0,80}(?:not (?:installed|found|available)|no such file|cannot connect|daemon)|cannot connect to the docker daemon|no docker daemon|no module named|ModuleNotFoundError|\bENOENT\b[^\n]{0,60}spawn/i;
 /** #4685: true when a builder's block summary names a missing tool or module (environment), not a credential. */
 export function missingToolBlock(summary) { return MISSING_TOOL_RE.test(String(summary ?? "")); }
-import { CHECKS_CLI, FORGEDOCK_CLI, REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, INVESTIGATION_FILE, IMPLEMENTATION_FILE, CONTRACT_FILE, builderPlanPrompt, builderImplementPrompt, contractCorrectionPrompt, conformanceResumePrompt, reviewerPrompt, investigationVerdict, decisionNote, reviewerRepairPrompt, REVIEW_DIFF_MAX_BYTES, blockCorrectionPrompt, HUMAN_BLOCK_REASONS, structurePrompt, hotspotPlanNote, hotspotBuildRule, reproPlanNote, unrunnableValidateNote, contextPackNote, docsPrompt, ciFailurePrompt, ciUnavailablePrompt, precheckFailurePrompt, contextRestartPrompt, turnBudgetWrapupPrompt, syncChecks, GROUPING_SYSTEM, enumeratingPlanNote, enumeratingBuildRule, invariantsPlanNote, invariantsBuildRule, missingEntriesPrompt, sequencePrompt, sequenceSyncNote, sequenceSyncPrompt, fixSessionPrompt, postMergeFailurePrompt, duplicateExportsPrompt, migrationGeneratorPrompt, i18nCopiesPrompt } from "./prompts.mjs";
+import { CHECKS_CLI, FORGEDOCK_CLI, REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, INVESTIGATION_FILE, IMPLEMENTATION_FILE, CONTRACT_FILE, builderPlanPrompt, builderImplementPrompt, contractCorrectionPrompt, conformanceResumePrompt, amendmentCorrectionPrompt, reviewerPrompt, investigationVerdict, decisionNote, reviewerRepairPrompt, REVIEW_DIFF_MAX_BYTES, blockCorrectionPrompt, HUMAN_BLOCK_REASONS, structurePrompt, hotspotPlanNote, hotspotBuildRule, reproPlanNote, unrunnableValidateNote, contextPackNote, docsPrompt, ciFailurePrompt, ciUnavailablePrompt, precheckFailurePrompt, contextRestartPrompt, turnBudgetWrapupPrompt, syncChecks, GROUPING_SYSTEM, enumeratingPlanNote, enumeratingBuildRule, invariantsPlanNote, invariantsBuildRule, missingEntriesPrompt, sequencePrompt, sequenceSyncNote, sequenceSyncPrompt, fixSessionPrompt, postMergeFailurePrompt, duplicateExportsPrompt, migrationGeneratorPrompt, i18nCopiesPrompt } from "./prompts.mjs";
 import { postMergeCommands } from "./postmerge.mjs";
 import { guardAfterMerge, withHistoryRows } from "./guards.mjs";
+import { routePathsFromFiles, routeReachabilityFailures } from "./routecheck.mjs";
+import { parseCoupled, coupledFailures } from "./coupled.mjs";
 import { loadGuards, selectGuards, runGuards, supersededIds, supersessionComment } from "./guardgate.mjs";
 import { freshFix, issueSummary, firstPassOf, sessionCostDelta } from "./fixround.mjs";
 import { parseBuilderRouting, routeBuilder, shouldEscalate } from "./routing.mjs";
@@ -51,6 +53,7 @@ import { addLaneWorktree, DEFAULT_SPARSE_MAX_KB } from "./worktree.mjs";
 import { parseVerify, runCiVerify, collectFailedLogs, capLogs, VERIFY_MODES, VERIFY_CHECK_NAME, verifyReport, ciGate, rerunFailedOnce, rerunTarget, splitFlaky } from "./verify.mjs";
 import { e2eSpecs, e2eWanted, ownFailures, runE2eGate, NO_TRIGGER } from "./e2e.mjs";
 import { laneBackendId } from "./limits.mjs";
+import { openRotator, rotatorRetry } from "./rotator.mjs";
 import { SPLIT_LABEL } from "./refactor.mjs";
 import { writeHeavyShims, sumWaits, isHeavyProcess } from "./heavy.mjs";
 import { priorityFromLabels } from "./sched.mjs";
@@ -194,6 +197,7 @@ export function isProtectedLaneBranch(b, { issue, lane = null, branches = {}, de
  * @param {string} [o.fixModel]     model of fresh fix-round sessions (#4363, forge.yaml lean.fix_model); default the reviewer model
  * @param {object} [o.builderRouting] forge.yaml lean.builder_routing/builder_mid_model (#4394): {mode: on (default)|off, midModel}
  * @param {string} [o.followupsDefaultMilestone] forge.yaml followups.default_milestone (#4664): milestone of deferred follow-ups whose parent's milestone has shipped and has no next one
+ * @param {string} [o.followupsRollupLabel] forge.yaml followups.rollup_issue_label (#5078): a repo's own open issue with this label is the post-deploy rollup when no marked one is open
  * @param {string} [o.sequenceRegenerate] forge.yaml lean.sequence.regenerate (#4386): snapshot generator for a schema-changing renumbered migration
  * @param {object} [o.baseMerge] forge.yaml lean.base_merge_* (#4588): {unionGlobs, jsonGlobs, generatedGlobs, generatedCommand} for deterministic base-merge conflict resolution
  * @param {number} [o.ciMaxMinutes]  remote-CI wait budget (default 360); exhaustion is NOT needs-human
@@ -226,8 +230,9 @@ export function isProtectedLaneBranch(b, { issue, lane = null, branches = {}, de
  */
 export async function runCore(o) {
   const { issue, repo, lane: requestedLane = null, laneOverride = false, branches = {}, cwd, dir, io, builderModel = null, reviewerModel = DEFAULT_REVIEWER_MODEL, fixModel = null,
-    toolchainOverride = null, testRunners = null, validateRecipes = null, envSetup = null, ciMaxMinutes = 360, conformance = "shadow", conformanceKinds = null, conformanceMutation = "off", reviewIncomplete = "needs-human", reproTest = "prefer", closeParent = false, mergeWait = "required", maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES, cliIdleMinutes = 15, cliMaxMinutes = 180, cliBusyMinutes = 45, contextCeilingTokens = 120000, turnBudgets = null, laneLimits = null, maxMergeRetries = 5, sessionLimitMaxWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS, onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
+    toolchainOverride = null, testRunners = null, coupledFiles = null, validateRecipes = null, routeReachability = null, envSetup = null, ciMaxMinutes = 360, conformance = "shadow", conformanceKinds = null, conformanceMutation = "off", reviewIncomplete = "needs-human", reproTest = "prefer", closeParent = false, mergeWait = "required", maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES, cliIdleMinutes = 15, cliMaxMinutes = 180, cliBusyMinutes = 45, contextCeilingTokens = 120000, turnBudgets = null, laneLimits = null, maxMergeRetries = 5, sessionLimitMaxWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS, onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
   const now = io.now ?? (() => Date.now());
+  const rotator = io.rotator !== undefined ? io.rotator : openRotator({ kind: o.accountRotator }); // #5094
   const vcfg = { ...parseVerify({}), ...(o.verify ?? {}) };
   const learnedCommands = (Array.isArray(o.precheck?.commands) ? o.precheck.commands : []).map((c) => String(c ?? "").trim()).filter(Boolean);
   if (!VERIFY_MODES.includes(vcfg.mode)) vcfg.mode = "local";
@@ -348,6 +353,7 @@ export async function runCore(o) {
   let heavyEnv = null, heavyWaitsFile = null, heavyQueueMax = 0, stage = "plan", iss;
   let seqLease = null; // #4386: the host sequence lease, held from the merge-gate renumber through the merge
   const waits = {};
+  const followupsFiled = []; // #5078: {issue, class, count} per tracking issue this lane filed into, for the batch report
   let precheckMs = 0, precheckDeferred = 0, precheckRan = false; // #4331: pre-PR check wall time and deferrals, for the batch report
   const addWait = (phase, ms, queued = 0) => {
     if (Number.isFinite(ms) && ms > 0) waits[phase] = (waits[phase] ?? 0) + ms;
@@ -470,13 +476,14 @@ export async function runCore(o) {
         await ghc(["issue", "edit", String(issue), "-R", repo, "--add-label", "needs-human"]);
       } catch { /* best effort */ }
     }
-    if (["needs-human", "engine-error", "dependency-open", "dependency-blocked", "dependency-unreadable", "decomposed"].includes(reason)) {
+    if (["needs-human", "engine-error", "dependency-open", "dependency-blocked", "dependency-unreadable", "decomposed", "host-task"].includes(reason)) {
       const wf = ["investigating", "building", "in-review"].map((x) => `workflow:${x}`).join(",");
       try { await ghc(["issue", "edit", String(issue), "-R", repo, "--remove-label", wf]); } catch { /* best effort */ }
     }
     if (["merged", "invalid", "needs-human", "budget-exceeded"].includes(reason)) {
       if (reason === "budget-exceeded") T.close = ["left open", "recoverable budget.exceeded"]; // #4505: not a human escalation
       else if (reason === "merged") T.close = [extra.close === "partial" ? "issue closed (partial)" : "issue closed (completed)", "label workflow:merged"];
+      else if (reason === "invalid" && extra.close === "already-fixed") T.close = ["issue closed (completed)", "already fixed on the base"]; // #5080
       else if (reason === "invalid") T.close = ["issue closed (not planned)", "label workflow:invalid"];
       else { T.close = ["left open", "label needs-human"]; T.anomalies.push(`needs-human: ${String(detail).split("\n")[0].slice(0, 300)}`); }
       try { await post(["FORGE:TRAJECTORY", REGISTER_MARKER], renderTrajectory({ ...T, usage: usageLine() })); } catch { /* best effort */ }
@@ -484,7 +491,7 @@ export async function runCore(o) {
     await releaseLease(reason, code, extra.mergedTo ?? null);
     done = { terminalReason: reason, detail, branch, worktree: wt, cost_usd: usage.cost_usd, tokens: { input: usage.input, output: usage.output, cache: usage.cache }, wall_ms: now() - t0, model_ms: modelMs, phases: phaseLedger.snapshot(),
       ...(laneHead && reason !== "merged" ? { laneHead: { ...laneHead } } : {}), light, ...(lightVerdict ? { light_eligibility: lightVerdict } : {}), ...(lightUpgrade ? { light_upgrade: lightUpgrade } : {}), // #4453
-      ...(Object.keys(waits).length ? { waits: { ...waits } } : {}), ...(heavyQueueMax ? { heavyQueueMax } : {}), ...(precheckRan ? { precheckMs, precheckDeferred } : {}),
+      ...(Object.keys(waits).length ? { waits: { ...waits } } : {}), ...(followupsFiled.length ? { followups: followupsFiled.map((f) => ({ ...f })) } : {}), ...(heavyQueueMax ? { heavyQueueMax } : {}), ...(precheckRan ? { precheckMs, precheckDeferred } : {}),
       ...(firstPassOf(builderTriggers) != null ? { firstPass: firstPassOf(builderTriggers) } : {}), ...(tb.record() ? { turns: tb.record() } : {}), // #4392
       ...(route ? { builderRoute: { tier: route.tier, class: route.class, escalated, model: route.model ?? "default" } } : {}),
       ...(gateRan ? { conformance: { mode: conformance === "enforce" || riskEnforced ? "enforce" : "shadow", would: shadowWould, risk: Boolean(riskEnforced), ...(Object.keys(kinds).length ? { kinds: [...failureClasses] } : {}) } } : {}), ...extra };
@@ -625,7 +632,7 @@ export async function runCore(o) {
   }
   /** Runner call with the per-run TMPDIR and FORGE_HOST_PARALLELISM; a usage limit pauses and resumes the same step, or defers past the cap (#4101). */
   async function callRunner(args) {
-    let pauses = 0;
+    let pauses = 0, rotations = 0;
     for (;;) {
       // #4181: every Docker resource the builder creates carries the lane's ownership labels (same batch/lane as the ledger).
       const labels = dockerLabels({ batch: o.batchId ?? "adhoc", lane: `lean-${issue}`, issue, expires: now() + LEDGER_TTL_MS }).join(" ");
@@ -637,6 +644,7 @@ export async function runCore(o) {
       catch (e) {
         const epoch = Number.isFinite(e?.resetAtEpochMs) ? e.resetAtEpochMs : null;
         if (!(e?.usageLimit === true || epoch !== null)) throw e;
+        if (rotatorRetry(rotator, rotations)) { rotations++; ev({ event: "PHASE_ACCOUNT_ROTATED", phase: args.role }); continue; } // #5094: same args (resume too), next account
         const waitMs = epoch !== null && epoch > now() ? epoch - now() : DEFAULT_SESSION_LIMIT_WAIT_MS;
         if (pauses >= maxSessionLimitPauses || waitMs > sessionLimitMaxWaitMs) { e.deferUsageLimit = true; throw e; }
         pauses++;
@@ -929,6 +937,17 @@ export async function runCore(o) {
       const caps = hostCapabilityBlock(s, o.hostCaps);
       if (caps.length) return await needsHuman(`Remote sandbox lacks host capability ${caps.join(", ")} (Builder is blocked (credentials)): ${s}\n\nThe dispatching host has it; the lane is recovered locally.`, OUTCOME_CODES.ENV_CAPABILITY_REMOTE);
     }
+    if (b.kind === "human" && b.why === "credentials" && READONLY_PROD_RE.test(s) && !EXTERNAL_NEED_RE.test(s)) {
+      // #5080: read-only production access with no credential/spend/account need is host work: recovered on the host, never a human ask
+      T.decisions.push("Builder block: read-only production access is host work (host-task), not an owner ask");
+      if (o.placement?.where !== "remote") { // on the host already: a host task (label host-task), never needs-human
+        const why = `Host-task: the lane needs read-only production access (Builder is blocked (credentials)): ${s}\n\nNot a credential or an owner ask: run it on the host with its read-only prod tools.`;
+        try { await post("FORGE:HOST_TASK", `## Host task\n${why}\n\n_${usageLine()}_`); } catch { /* best effort */ }
+        try { await ghc(["issue", "edit", String(issue), "-R", repo, "--add-label", "host-task"]); } catch { /* best effort */ }
+        return await finish("host-task", why, { code: OUTCOME_CODES.ENV_CAPABILITY_REMOTE }, OUTCOME_CODES.ENV_CAPABILITY_REMOTE);
+      }
+      return await needsHuman(`Host-task: the lane needs read-only production access, which the dispatching host has (Builder is blocked (credentials)): ${s}\n\nNot a credential: the lane is recovered on the host.`, OUTCOME_CODES.ENV_CAPABILITY_REMOTE);
+    }
     if (b.kind === "human" && b.why === "credentials" && o.placement?.where === "remote" && missingToolBlock(s)) {
       // #4685: a tool the sandbox lacks (docker, promtool, a Python module) is an environment gap the host recovers, never a credential.
       return await needsHuman(`Remote sandbox lacks a validate tool (Builder is blocked (credentials)): ${s}\n\nNot a credential: the lane is recovered where the tool exists.`, OUTCOME_CODES.ENV_TOOL_MISSING);
@@ -1265,6 +1284,13 @@ export async function runCore(o) {
       const differs = new Set(names(await git(["diff", "--name-only", base, "HEAD"])));
       return touched.filter((f) => differs.has(f));
     };
+    /** #5079: verification.coupled_files failures for the lane diff ([] when unconfigured; added files only read when a rule needs them) */
+    const coupledOf = async (files) => {
+      const rules = parseCoupled(coupledFiles);
+      if (!rules.length) return null;
+      const addedFiles = rules.some((r) => r.addedOnly) ? names(await git(["diff", "--name-only", "--diff-filter=A", `${base}...HEAD`]).catch(() => "")) : [];
+      return coupledFailures({ rules, changedFiles: files, addedFiles });
+    };
     /** #4364: the last `forgedock check` record vs the current tree: skipped|stale|red|green; any read or git error is skipped. */
     const selfCheckNow = async () => {
       try { return selfCheckState(JSON.parse(await io.fs.read(`${wt}/${SELF_CHECK_FILE}`)), await worktreeFingerprint({ git, base })); } catch { return "skipped"; }
@@ -1332,7 +1358,7 @@ export async function runCore(o) {
         pitMatched = inPack.filter((x) => x.match === "files").length;
         // #4375: which pitfalls were in the pack (signatures only, run log only: never telemetry or a comment)
         const rec = { event: "CONTEXT_PACK", mode: ctxCfg.mode, ...ctxAb, lane_type: ctxLane, sources: p.sources, found: p.found, bytes: p.bytes, items: p.items, truncated: p.truncated,
-          hash: p.hash, cached: r.cached, ...(r.errors?.length ? { errors: r.errors } : {}) };
+          hash: p.hash, cached: r.cached, ...(p.recall ? { recall: p.recall.present ? "present" : "absent" } : {}), ...(r.errors?.length ? { errors: r.errors } : {}) };
         ev({ ...rec, pitfalls: inPack }); await emit(rec);
         const seen = trustedComments.some((c) => String(c?.body ?? "").startsWith("<!-- FORGE:CONTEXT -->") && String(c.body).includes(`hash ${p.hash})`));
         if (p.items && !seen) { try { await post("FORGE:CONTEXT", renderContextRecord(p, { mode: ctxCfg.mode, laneType: ctxLane })); } catch { /* best effort */ } }
@@ -1381,7 +1407,7 @@ export async function runCore(o) {
       if (!io.fileFollowups) throw fail("no follow-up filing effect is configured");
       const items = followupItems(reqs, { now: now() });
       let filed;
-      try { filed = await io.fileFollowups({ parent: issue, repo, items, milestone, defaultMilestone: o.followupsDefaultMilestone ?? null, lane }); } catch (e) { throw fail(`filing the follow-up issue failed: ${String(e?.message ?? e).slice(0, 200)}`); }
+      try { filed = await io.fileFollowups({ parent: issue, repo, items, milestone, defaultMilestone: o.followupsDefaultMilestone ?? null, lane, batchId: o.batchId ?? null, rollupLabel: o.followupsRollupLabel ?? null }); } catch (e) { throw fail(`filing the follow-up issue failed: ${String(e?.message ?? e).slice(0, 200)}`); }
       for (const [i, r] of reqs.entries()) {
         const n = Number(filed?.[items[i].key]);
         if (!Number.isSafeInteger(n) || n <= 0) throw fail(`no tracking issue was returned for ${r.id}`);
@@ -1389,6 +1415,8 @@ export async function runCore(o) {
         try { st = JSON.parse(String(await ghc(["issue", "view", String(n), "-R", repo, "--json", "number,state"]))); } catch { st = null; }
         if (String(st?.state).toUpperCase() !== "OPEN") throw fail(`tracking issue #${n} for ${r.id} is not open or unreadable`);
         r.tracked = `#${n}`;
+        const f = followupsFiled.find((x) => x.issue === n && x.class === items[i].class); // #5078: grouped per issue and class
+        if (f) f.count += 1; else followupsFiled.push({ issue: n, class: items[i].class, count: 1 });
       }
       const buckets = Object.entries(bucketTally(reqs)).map(([k, c]) => `${k}:${c}`).join(","); // #4724
       T.decisions.push(`Tracked ${reqs.map((r) => `${r.id} (${r.disposition})`).join(", ")} in ${[...new Set(reqs.map((r) => r.tracked))].join(", ")} (${why}; buckets ${buckets})`);
@@ -1802,7 +1830,7 @@ export async function runCore(o) {
         const names = failed.map((f) => `\`${f.command}\` (exit ${f.rc})`).join(", ");
         if (isSplit) return await needsHuman(`Declared check command(s) fail on the refactor:split move (no builder edits a split); nothing merged: ${names}`, OUTCOME_CODES.CI_RED);
         checkCommandsFailing = true;
-        if (round >= vcfg.maxRounds || !sessionId) { T.anomalies.push(`Declared check command(s) still failing before the PR: ${names}`); break; }
+        if (round >= vcfg.maxRounds || !sessionId) { if (vcfg.precheckBlock) return await needsHuman(`Declared check command(s) still failing before the PR (verify.precheck_block); nothing merged: ${names}`, OUTCOME_CODES.CI_RED); T.anomalies.push(`Declared check command(s) still failing before the PR: ${names}`); break; }
         T.decisions.push(`Declared check command(s) failed: ${names}; builder resumed (round ${round + 1}/${vcfg.maxRounds})`);
         const before = String(await git(["rev-parse", "HEAD"])).trim();
         const capped = capLogs(failed.map((f) => ({ ...f, log: f.output }))).map((f) => ({ command: f.command, rc: f.rc, output: f.log }));
@@ -1816,7 +1844,7 @@ export async function runCore(o) {
         await fixRound("precheck", precheckFailurePrompt(quiet, vcfg.mode), [], "precheck", capped.map((f) => `${f.command}\n${f.output ?? ""}`).join("\n"));
         await upsertStage("implementation");
         result = (await readResult()) ?? result;
-        if (String(await git(["rev-parse", "HEAD"])).trim() === before) { T.anomalies.push(`Declared check command(s) failing and the builder made no new commit for them: ${names}`); break; }
+        if (String(await git(["rev-parse", "HEAD"])).trim() === before) { if (vcfg.precheckBlock) return await needsHuman(`Declared check command(s) failing and the builder made no new commit for them (verify.precheck_block); nothing merged: ${names}`, OUTCOME_CODES.CI_RED); T.anomalies.push(`Declared check command(s) failing and the builder made no new commit for them: ${names}`); break; }
         files = await changedFiles();
       }
     }
@@ -2301,6 +2329,7 @@ export async function runCore(o) {
       const cfg = readRollouts(wt);
       return cfg ? detectNewOffKeys(cfg, String(await git(["diff", "-U0", `${base}...HEAD`, "--", ...cfg.files]).catch(() => ""))) : [];
     }
+    let amendFixed = false;
     async function gate() {
       await refreshIssue("conformance");
       result = (await readResult()) ?? result;
@@ -2313,6 +2342,14 @@ export async function runCore(o) {
         ev({ event: "CONFORMANCE_RISK_ENFORCED", paths: hits });
         T.decisions.push(`Conformance enforced (review.risk_paths): ${hits.slice(0, 10).join(", ")}${hits.length > 10 ? ` and ${hits.length - 10} more` : ""}`);
       }
+      if (!amendFixed && sessionId && amendmentKindProblems(result?.amendments).length) { // #5089: one in-lane correction, outside the conformance resume budget
+        amendFixed = true;
+        const bad = amendmentKindProblems(result.amendments);
+        T.decisions.push(`Amendment kinds invalid (${bad.length}); builder asked to correct ${RESULT_FILE} once`);
+        await builder(++attemptN, amendmentCorrectionPrompt(bad), sessionId, false, undefined, { mode: "resume", trigger: "contract_correction" });
+        result = (await readResult()) ?? result;
+        files = await changedFiles();
+      }
       const amendProblems = await amend();
       const gateHead = String(await git(["rev-parse", "HEAD"])).trim();
       const ciVerified = remoteVerify && ciVerifiedHead !== null && ciVerifiedHead === gateHead;
@@ -2321,6 +2358,8 @@ export async function runCore(o) {
       // #4693: guards run beside the validate rerun; SPEC-11: the substituted-original rerun shares the one validate phase
       const validatePhase = phaseLedger.during("validate", async () => ({ runs: await rerunFailedValidatesRaw(effective), subs: await rerunSubstitutedOriginals(effective) })).finally(() => { validateMs = now() - gateT0; });
       const [{ runs: validateRuns, subs: substitutedRuns }, guardFailures] = await Promise.all([validatePhase, guardGate(files)]);
+      // #5087: forge.yaml topology.route_reachability gates the route handlers this diff adds; unset = no check
+      const routeFailures = routeReachability && io.runCommand ? await routeReachabilityFailures({ command: routeReachability, paths: routePathsFromFiles(String(await git(["diff", "--name-only", "--diff-filter=A", `${base}...HEAD`]).catch(() => "")).split("\n").map((x) => x.trim()).filter(Boolean)), run: async ({ command }) => (await io.runCommand({ command, cwd: wt, timeoutMs: vcfg.precheckTimeoutSeconds * 1000, env: laneEnv() }).then((x) => x?.r ?? x)) ?? { rc: 127 } }) : [];
       // #4705: only the part not hidden behind the validate rerun; 0 when the gate errored or skipped
       const guardRunMs = guardEv && !guardEv.error ? Math.max(0, now() - gateT0 - validateMs) : 0;
       guardAddedMs += guardRunMs;
@@ -2330,7 +2369,7 @@ export async function runCore(o) {
       const checkIds = effective.requirements?.some((r) => r.disposition === "post-deploy") ? new Set(Object.keys(await checksAt(git, [base, "HEAD"], wt))) : null;
       const removedPaths = (effective.validate ?? []).some((v) => v.substituted) ? await removedPathsOf(git, base) : []; // #4990
       const subBaseFiles = (effective.validate ?? []).some((v) => v.substituted) ? String(await git(["ls-tree", "-r", "-z", "--name-only", base]).catch(() => "")).split("\0").filter(Boolean) : []; // #5003
-      const pc = precheck({ contract: effective, result, changedFiles: files, ignore: IGNORE, ciVerified, hotspots, repro: await reproOf(effective), validateRuns, repoHas, frozen, checkIds, guardFailures, newOffKeys: await newOffKeysOf(), substitutedRuns, removedPaths, baseFiles: subBaseFiles });
+      const pc = precheck({ contract: effective, result, changedFiles: files, ignore: IGNORE, ciVerified, hotspots, repro: await reproOf(effective), validateRuns, repoHas, frozen, checkIds, guardFailures, coupledFailures: await coupledOf(files), routeFailures, newOffKeys: await newOffKeysOf(), substitutedRuns, removedPaths, baseFiles: subBaseFiles });
       // #4350: a scope-check validate stale only by amended deliverables is judged by the engine's scope gate instead
       if (pc.superseded?.length) {
         ev({ event: "VALIDATE_SUPERSEDED", runs: pc.superseded });
@@ -2367,6 +2406,8 @@ export async function runCore(o) {
       const envFails = pc.failures.filter((f) => ENV_CODES.includes(f.code));
       const pre = [...pc.failures.filter((f) => !ENV_CODES.includes(f.code)), ...amendProblems, ...mutBlock];
       if (pre.length) ev({ event: "PRECHECK", failures: pre.map((f) => f.code) });
+      // #5080: the repro already passes on the base and the diff changes no source: the fix is on the base, not missing
+      if (alreadyFixedOnBase(pre, files, IGNORE)) return { state: "already-fixed", by: "precheck", failures: pre };
       if (pre.length && !recording()) return { state: "nonconforming", by: "precheck", failures: pre };
       // shadow: the builder's own failed checks block before any reviewer tokens are spent (#4160)
       const hard = recording() ? blockingOf(pre, SHADOW_PRE_BLOCKS).block : [];
@@ -2462,6 +2503,13 @@ export async function runCore(o) {
         const explained = explainFailures(outcome.failures, effective); // #4265: name the unmet requirement, not only the code
         const list = explained.slice(0, 15).map((f) => `- ${f.code}: ${f.detail}`).join("\n");
         if (outcome.state === "environment") return await envNeedsHuman(outcome.failures);
+        if (outcome.state === "already-fixed") { // #5080: close as delivered, citing the base commit
+          const sha = String(await git(["rev-parse", base]).catch(() => "")).trim().slice(0, 12) || base;
+          const note = `Already fixed on the base: the repro test passes on \`${base}\` (${sha}) without this change, and the diff changes no source file. Closing as delivered.\n\n${list}`;
+          T.decisions.push(`Already fixed on base ${sha} (repro BASE=RAN HEAD=RAN)`);
+          await ghw(["issue", "close", String(issue), "-R", repo, "--reason", "completed", "--comment", note]);
+          return await finish("invalid", `already fixed on base ${sha}`, { close: "already-fixed" });
+        }
         if (outcome.state === "review.unparseable") return await needsHuman(`The conformance reviewer returned no parseable JSON twice; nothing merged.`, OUTCOME_CODES.REVIEW_NO_VERDICT);
         if (shadow && reviewIncomplete === "degraded" && (outcome.state === "review.incomplete" || outcome.state === "review.inconsistent")) {
           degraded = { state: outcome.state, missing: outcome.missing ?? [] };
@@ -2982,7 +3030,7 @@ export async function runCore(o) {
   } catch (e) {
     if (e?.deferUsageLimit) {
       const when = e.resetAt || (Number.isFinite(e.resetAtEpochMs) ? new Date(e.resetAtEpochMs).toISOString() : "unknown");
-      return finish("deferred", `usage limit hit; resets at ${when}`, { code: OUTCOME_CODES.RATE_LIMITED, resetAt: when, resetAtEpochMs: Number.isFinite(e.resetAtEpochMs) ? e.resetAtEpochMs : null, backendId: laneBackendId(process.env) }, OUTCOME_CODES.RATE_LIMITED);
+      return finish("deferred", `usage limit hit; resets at ${when}`, { code: OUTCOME_CODES.RATE_LIMITED, resetAt: when, resetAtEpochMs: Number.isFinite(e.resetAtEpochMs) ? e.resetAtEpochMs : null, backendId: laneBackendId(process.env, rotator) }, OUTCOME_CODES.RATE_LIMITED);
     }
     if (e?.deferCode) return finish("deferred", e.deferDetail ?? String(e.message), { code: e.deferCode, ...(e.retryInSeconds ? { retryInSeconds: e.retryInSeconds } : {}) }, e.deferCode);
     // #4505: a turn overrun is mechanical: a non-human end the batch recovers, needs-human only once a budget recovery failed too