forgedock 1.46.0 → 1.48.0

package/bin/lean/limits.test.mjs

@@ -183,3 +183,89 @@ describe("account-scoped usage-limit holds (#4190)", () => {
     assert.deepEqual(limits.list(), []);
   });
 });
+
+describe("#5095: a held pool account places hybrid lanes local", () => {
+  const remoteFor = (extra = {}) => ({ max: 2, isRemote: () => true, place: () => ({ where: "remote", reason: "heavy" }), identity: () => "remote:pool", ...extra });
+  const runWith = async ({ hold, remote }) => {
+    const { c, now, sleep } = fakeClock();
+    const limits = openLimits(storeFile(), { now });
+    for (const [id, ms] of Object.entries(hold)) limits.set(id, c.t + ms, "test");
+    const ctxs = [];
+    const rows = await orchestrate({ issues: [1], parallel: 1, now, sleep, readBody: async () => "", limits, identity: () => "local", remote,
+      runOne: async (n, _l, ctx) => { ctxs.push({ at: now() - 1_000_000, remote: ctx.remote, placement: ctx.placement }); return { terminalReason: "merged" }; } });
+    return { rows, ctxs };
+  };
+
+  it("hybrid: a hold on the remote identity and none on the local one places the next admission local", async () => {
+    const { rows, ctxs } = await runWith({ hold: { "remote:pool": 600_000 }, remote: remoteFor({ fallbackLocal: true }) });
+    assert.equal(rows[0].outcome, "merged");
+    assert.equal(ctxs.length, 1);
+    assert.equal(ctxs[0].at, 0, "admitted at once, not held");
+    assert.equal(ctxs[0].remote, false);
+    assert.equal(ctxs[0].placement.where, "local");
+    assert.match(ctxs[0].placement.reason, /fallback to local: pool usage limit until/);
+  });
+
+  it("remote-only: a held pool account waits for the reset; no hold places the lane remote", async () => {
+    const held = await runWith({ hold: { "remote:pool": 600_000 }, remote: remoteFor() });
+    assert.equal(held.ctxs[0].remote, true);
+    assert.ok(held.ctxs[0].at >= 600_000, "the remote lane starts after the pool reset");
+    const free = await runWith({ hold: {}, remote: remoteFor({ fallbackLocal: true }) });
+    assert.deepEqual([free.ctxs[0].at, free.ctxs[0].remote, free.ctxs[0].placement.where], [0, true, "remote"]);
+  });
+});
+
+describe("account rotator and usage-limit holds (#5094)", () => {
+  it("#5094 rotator headroom: a rate_limited lane records no host hold and admissions continue", async () => {
+    const { c, now, sleep } = fakeClock();
+    const t0 = c.t;
+    const limits = openLimits(storeFile(), { now });
+    let acct = "acct-1";
+    const rotator = { kind: "tokenbaton", accounts: [{ n: 1 }, { n: 2 }], headroom: () => true, resumeAt: () => now(),
+      isAccount: (id) => id === "acct-1" || id === "acct-2", currentIdentity: () => acct };
+    const starts = {};
+    const rows = await orchestrate({ issues: [1, 2], parallel: 1, now, sleep, readBody: async () => "", limits, rotator, identity: () => laneBackendId({}, rotator), batchId: "b1",
+      runOne: async (n) => {
+        (starts[n] ??= []).push(now());
+        if (n === 1 && starts[1].length === 1) { acct = "acct-2"; return limited("acct-1", t0 + 600_000); } // tokenbaton rotates
+        return { terminalReason: "merged" };
+      } });
+    assert.deepEqual(rows.map((r) => r.outcome), ["merged", "merged"]);
+    assert.deepEqual(limits.list(), [], "no host-wide hold while an account has headroom");
+    assert.equal(starts[2][0], t0, "admissions continue");
+    assert.equal(starts[1][1], t0, "the limited issue reruns at once on the next account");
+  });
+
+  it("#5094 a hold set for identity A does not block admissions once the rotator's active identity is B", async () => {
+    const { c, now, sleep } = fakeClock();
+    const t0 = c.t;
+    const limits = openLimits(storeFile(), { now });
+    limits.set("acct-1", t0 + 3_600_000, "batch b0 #1");
+    const rotator = { currentIdentity: () => "acct-2" };
+    const starts = [];
+    await orchestrate({ issues: [1], now, sleep, readBody: async () => "", limits, identity: () => laneBackendId({}, rotator),
+      runOne: async () => { starts.push(now()); return { terminalReason: "merged" }; } });
+    assert.deepEqual(starts, [t0]);
+  });
+
+  it("#5094 #5095 a limited pool account keeps its own hold under a rotator with headroom; the host account is never held", async () => {
+    const { c, now, sleep } = fakeClock();
+    const t0 = c.t;
+    const limits = openLimits(storeFile(), { now });
+    const rotator = { accounts: [{ n: 1 }], headroom: () => true, resumeAt: () => now(), isAccount: (id) => id === "acct-1", currentIdentity: () => "acct-1" };
+    const remote = { max: 2, fallbackLocal: true, isRemote: () => true, place: () => ({ where: "remote", reason: "heavy" }), identity: () => "remote:pool" };
+    const runs = [];
+    const rows = await orchestrate({ issues: [1, 2], parallel: 1, now, sleep, readBody: async () => "", limits, rotator, remote, identity: () => laneBackendId({}, rotator),
+      runOne: async (n, _l, ctx) => {
+        runs.push({ n, at: now(), where: ctx.placement?.where, poolHeld: limits.holdUntil("remote:pool"), hostHeld: limits.holdUntil("acct-1") });
+        return n === 1 && runs.length === 1 ? limited("remote:pool", t0 + 600_000) : { terminalReason: "merged" };
+      } });
+    assert.deepEqual(rows.map((r) => r.outcome), ["merged", "merged"]);
+    const second = runs.find((x) => x.n === 2);
+    assert.equal(runs[0].where, "remote");
+    assert.equal(second.at, t0, "the host account is not held: admissions continue");
+    assert.equal(second.poolHeld, t0 + 600_000, "the pool's own hold is recorded (#5095)");
+    assert.ok(!(second.hostHeld > now()), "no host-wide hold while the rotator has headroom");
+    assert.equal(second.where, "local", "hybrid falls back local while the pool is held");
+  });
+});

package/bin/lean/milestonesync.mjs

@@ -18,7 +18,7 @@ import { parseForgeYaml } from "../forge-utils.mjs";
 import { resolveBaseConflicts } from "./conflictres.mjs";
 import { parseLifecycle } from "./lifecycle.mjs";
 import { parseMinAge } from "./prefilter.mjs";
-import { DEFAULT_FEATURE_PATTERN, milestoneSlug, readBranches } from "./lane.mjs";
+import { DEFAULT_FEATURE_PATTERN, listMilestones, milestoneSlug, readBranches } from "./lane.mjs";
 
 export const SYNC_REASONS = ["ship", "batch", "conflict-risk", "manual"];
 export const DEFAULT_DEBOUNCE_MS = 10 * 60 * 1000;
@@ -57,7 +57,7 @@ export async function syncMilestone({ gh, git, repo, slug, base, branch = `miles
   let wt = null, baseSha;
   try {
     if (!SYNC_REASONS.includes(reason)) return { status: "refused", detail: `sync is on demand: reason must be one of ${SYNC_REASONS.join("|")}` };
-    const list = JSON.parse(String(await gh(["api", `repos/${repo}/milestones?state=all&per_page=100`])) || "[]");
+    const list = await listMilestones({ gh, repo, state: "all" });
     const ms = (Array.isArray(list) ? list : []).find((m) => milestoneSlug(m?.title) === slug);
     if (!ms) return { status: "refused", detail: `no milestone with slug ${slug}` };
     if (!isSyncable(ms)) return { status: "shipped", detail: `milestone is ${parseLifecycle(ms.description)?.state ?? ms.state}: never synced` };

package/bin/lean/milestonesync.test.mjs

@@ -131,3 +131,25 @@ describe("syncMilestone (#4663)", () => {
     assert.equal(remote("rev-parse", "milestone/alpha"), before);
   });
 });
+
+/** #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("milestone pagination (#5084)", () => {
+  it("finds a milestone on page 2 of the milestones API (#5084)", async () => {
+    sh(work, "push", "-q", "origin", "milestone/alpha:milestone/search-research-api");
+    const list = pagedMilestones(manyMilestones({ title: "Search & Research API", state: "open", description: "" }));
+    const paged = async (args) => (args[0] === "api" && args[1].includes("/milestones?") ? list(args) : gh(args));
+    const r = await syncMilestone({ gh: paged, git, repo: "o/r", slug: "search-research-api", base: "staging", reason: "manual", cfg: {}, tmp: tmpDir("msync-tmp-") });
+    assert.notEqual(r.status, "refused", r.detail);
+    assert.equal(r.status, "up-to-date");
+  });
+});

package/bin/lean/orchestrate.mjs

@@ -23,7 +23,9 @@
  * `sandbox.capacity`, #4528; `sandbox.unreachable`, #4788; `rate_limited`, #4784) stop after `maxDeferrals`.
  * Usage-limit holds (#4190) are keyed by backend identity in `limits` (the host store, shared by every batch on the
  * host; in memory when absent): admission checks the hold of `identity()`, the account the next lane would use. While held, the
- * batch re-reads the store every `pollMs` (#4446), so `forgedock limits clear` admits on the next poll, not at the reset. An `engine-error` is
+ * batch re-reads the store every `pollMs` (#4446), so `forgedock limits clear` admits on the next poll, not at the reset.
+ * #5095: `remote.identity()` names the pool's account (execution.mjs `remoteHoldId`); while it is held, a remote-placed lane
+ * runs local in hybrid (`fallbackLocal`, local account not held) or waits for the reset; admission is not held. An `engine-error` is
  * relaunched once; `breaker` ({errors, window_min}) stops admissions after a burst and lets running lanes finish, the
  * rest stay pending (outcome `held`) for a resume. `getParallel()` is read on every pass, so K can change live.
  * `getChildren()` + `autoChildren {mode, pollS, epics}` (#4965, `orchestration.auto_add_children`): with mode `epic`|`all`, at most once per `pollS`
@@ -116,6 +118,7 @@ import { laneSize, SIZES } from "./budget.mjs";
 import { requeueKey, REQUEUABLE } from "./batch.mjs";
 import { makeCapWait } from "./capwait.mjs";
 import { mapLimit } from "./pmap.mjs";
+import { quotaRequeue } from "./rotator.mjs";
 import { joinsDecomposed, addsEpicChildren, selectChildren, edgeText, DEFAULT_POLL_S } from "./autochildren.mjs";
 
 // A dependency that finished like this no longer blocks its dependents.
@@ -257,7 +260,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   classify = null, maintenance = null, limits = null, identity = () => "default", batchId = null, drift = null, integration = null, sched = null, priorityOf = null, remote = null, beforeAdmit = null, preflight = null,
   recovery = null, decide = () => {}, conflicting = null, relabelNeedsHuman = null, onExit = null, issueLabels = null, issueState = null, getCancelled = null, getHeld = null, getBlocked = null, trusted = null, getGates = null, stopLane = null,
   estimate = null, starveMs = DEFAULT_STARVE_MS, setupConcurrency = DEFAULT_SETUP_CONCURRENCY, signal = null, dispatchCheck = null, syncParked = null, syncEveryMs = DEFAULT_SYNC_EVERY_MS, lifecycle = null,
-  getChildren = null, autoChildren = null, baseWait = null }) {
+  getChildren = null, autoChildren = null, baseWait = null, rotator = null }) {
   const saved = store?.load?.() ?? null;
   const order = saved ? [...saved.order] : [];
   const set = new Set(order);
@@ -279,7 +282,18 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   let errorTimes = [...(saved?.errorTimes ?? [])];
   // A legacy batch-local `holdUntil` (pre-#4190) names no account and is ignored: a same-account lane re-sets the hold.
   const holds = limits ?? memoryLimits(now);
-  const heldUntil = () => { try { const id = identity(); const u = holds.holdUntil(id); return Number.isFinite(u) && u > now() ? u : null; } catch { return null; } };
+  // #5094: with an account rotator, admissions stop only when no account has headroom, and resume when the first one resets.
+  const rotatorHold = () => {
+    if (!rotator) return undefined;
+    try { if (rotator.headroom()) return null; const u = rotator.resumeAt(); return Number.isFinite(u) && u > now() ? u : undefined; } catch { return undefined; }
+  };
+  const heldUntil = () => {
+    const r = rotatorHold();
+    if (r !== undefined) return r;
+    try { const id = identity(); const u = holds.holdUntil(id); return Number.isFinite(u) && u > now() ? u : null; } catch { return null; }
+  };
+  // #5094: a quota pause carries its attempt's cost and minutes into the issue's next row once; the resume time labels the report row.
+  const quota = toMap(saved?.quota); // issue -> {cost_usd, minutes, resumeAt (epoch ms), rotations}
   let tripped = saved?.breaker ?? null;
   let pfAll = false, pfRemote = false, pfNoted = new Set(); // #4866: lane preflight holds
   let opHeld = new Set(); // #4592: operator-held issues this pass (the batch `hold` file is the authority)
@@ -344,7 +358,7 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   const save = () => {
     if (!store || halted) return;
     store.save({ v: 1, ...(setup ? { phase: "setup", setup: { ...setup } } : {}), order, deps: toObj(deps), lanes: toObj(lanes), crossSeen: [...crossSeen], results: toObj(results), running: toObj(runRecs),
-      pending, notBefore: toObj(notBefore), requeues: toObj(requeues), deferrals: toObj(deferrals), engineErrors: toObj(engineErrors),
+      pending, notBefore: toObj(notBefore), requeues: toObj(requeues), deferrals: toObj(deferrals), engineErrors: toObj(engineErrors), ...(quota.size ? { quota: toObj(quota) } : {}),
       prefilter: toObj(checked), errorTimes, breaker: tripped, ...(budget ? { classes: toObj(classes), dispatch: { ...dispatch } } : {}),
       ...(reg ? { priorities: toObj(priorities) } : {}), ...(sandboxUse.size ? { sandbox: toObj(sandboxUse) } : {}),
       ...(recoveries.size || recovering.size ? { recoveries: toObj(recoveries), recovering: toObj(recovering), recoveryClasses: toObj(classUsed) } : {}),
@@ -507,6 +521,15 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   const grant = (n, wanted) => {
     if (lanes.get(n)?.ok === false) return true;
     let p = placeOf(n);
+    if (p?.where === "remote" && typeof remote?.identity === "function") {
+      // #5095: the pool account is held for a usage limit: hybrid runs the lane on the host, remote-only waits for the reset
+      let poolHeld = null;
+      try { const u = holds.holdUntil(remote.identity()); poolHeld = Number.isFinite(u) && u > now() ? u : null; } catch { poolHeld = null; }
+      if (poolHeld !== null) {
+        if (!remote.fallbackLocal || heldUntil() !== null) { notBefore.set(n, poolHeld); return false; }
+        p = { where: "local", reason: `fallback to local: pool usage limit until ${new Date(poolHeld).toISOString()}` };
+      }
+    }
     if (p?.where === "remote" && reg?.holder) {
       let other = null;
       try { other = reg.holder(entryOf(n)) ?? null; } catch { other = null; }
@@ -587,11 +610,18 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
       ...(() => { const w = capWait.take(n, r?.waits); return w && typeof w === "object" ? { waits: w } : {}; })(), ...(Number.isInteger(r?.heavyQueueMax) ? { heavyQueueMax: r.heavyQueueMax } : {}),
       ...(Number.isFinite(r?.wall_ms) ? { wall_ms: r.wall_ms } : {}), ...(Number.isFinite(r?.model_ms) ? { model_ms: r.model_ms } : {}), // #4451
       ...(phasesOf(r, rec) ? { phases: phasesOf(r, rec) } : {}), // #4908
+      ...(Array.isArray(r?.followups) && r.followups.length ? { followups: r.followups } : {}), // #5078
       ...(Number.isFinite(r?.precheckMs) ? { precheck_ms: r.precheckMs } : {}), ...(Number.isInteger(r?.precheckDeferred) && r.precheckDeferred > 0 ? { precheck_deferred: r.precheckDeferred } : {}), // #4331
       ...(typeof r?.firstPass === "boolean" ? { first_pass: r.firstPass } : {}), // #4362
       ...(r?.turns && typeof r.turns === "object" ? { turns: r.turns } : {}), // #4392
       ...(r?.conformance && typeof r.conformance === "object" ? { conformance: r.conformance } : {}), // #4398
       ...(rec?.placement ? { placement: rec.placement } : {}), ...(estimates.has(n) ? { est_minutes: Math.round(estimates.get(n) * 10) / 10 } : {}) }; // #4409
+    const quotaPause = row.outcome === "deferred" && r?.code === "rate_limited" && !cancelled;
+    if (!quotaPause && quota.has(n)) { // #5094: the paused attempts' cost, added once
+      const q = quota.get(n); quota.delete(n);
+      row.cost_usd = Math.round(((Number(row.cost_usd) || 0) + (Number(q.cost_usd) || 0)) * 1e6) / 1e6;
+      row.minutes = Math.round(((Number(row.minutes) || 0) + (Number(q.minutes) || 0)) * 10) / 10;
+    }
     const depList = (Array.isArray(r?.dependencies) ? r.dependencies : []).filter((d) => Number.isSafeInteger(d) && d > 0 && d !== n);
     const subs = (Array.isArray(r?.subissues) ? r.subissues : []).filter((d) => Number.isSafeInteger(d) && d > 0 && d !== n);
     if (subs.length) row.subissues = subs; // #4396: links a decomposed parent to its sub-lanes in the report
@@ -664,10 +694,26 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
         // account runs it at once. If the hold cannot be recorded, the reset delay applies to this issue instead.
         let delayMs = pol.delayMs;
         if (pol.hold) {
-          try { holds.set(r?.backendId ?? identity(), now() + pol.delayMs, `batch ${batchId ?? "?"} #${n}`); delayMs = 0; } catch { /* fail-open */ }
+          // #5094: an account rotator with headroom means another account runs the next call, so no host hold is recorded.
+          const rq = quotaRequeue({ rotator, r, prior: quota.get(n), delayMs: pol.delayMs });
+          if (rq) {
+            delayMs = rq.delayMs;
+            // #5095 + #5094: the pool account's own hold (not the host's) still routes hybrid lanes local until its reset.
+            try { const pool = remote?.identity?.(); if (!rq.rotated && pool && r?.backendId === pool) holds.set(pool, now() + pol.delayMs, `batch ${batchId ?? "?"} #${n}`); } catch { /* fail-open */ }
+          } else try { holds.set(r?.backendId ?? identity(), now() + pol.delayMs, `batch ${batchId ?? "?"} #${n}`); delayMs = 0; } catch { /* fail-open */ }
+          const q = quota.get(n) ?? { cost_usd: 0, minutes: 0, rotations: 0 };
+          let rotAt = null;
+          if (!rq && rotator) { try { rotAt = rotator.resumeAt(); } catch { rotAt = null; } }
+          const resumeAt = Math.max(now() + (rq ? rq.delayMs : pol.delayMs), Number.isFinite(rotAt) ? rotAt : 0);
+          quota.set(n, { cost_usd: Math.round(((Number(q.cost_usd) || 0) + (Number(row.cost_usd) || 0)) * 1e6) / 1e6, minutes: Math.round(((Number(q.minutes) || 0) + (Number(row.minutes) || 0)) * 10) / 10,
+            resumeAt, rotations: (q.rotations ?? 0) + (rq?.rotated ? 1 : 0) });
+          requeue(n, delayMs); done(); save();
+          const iso = new Date(resumeAt).toISOString();
+          update({ ...row, outcome: "paused", quota: { resumeAt: iso }, detail: `paused (quota) until ${iso}: ${r?.code ?? "deferred"}${r?.detail ? ` ${r.detail}` : ""}` });
+          return;
         }
-        requeue(n, capGated && !pol.hold ? 0 : delayMs); done(); save();
-        update({ ...row, detail: `requeued in ${Math.round(pol.delayMs / 1000)}s${pol.hold ? " (admissions held)" : ""}: ${r?.code ?? "deferred"}${r?.detail ? ` ${r.detail}` : ""}` });
+        requeue(n, capGated ? 0 : delayMs); done(); save();
+        update({ ...row, detail: `requeued in ${Math.round(pol.delayMs / 1000)}s: ${r?.code ?? "deferred"}${r?.detail ? ` ${r.detail}` : ""}` });
         return;
       }
       row.detail = `gave up after ${deferrals.get(n) ?? 0} deferrals: ${r?.detail ?? r?.code ?? ""}`;
@@ -1288,7 +1334,13 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
   for (const [n, r] of results) if (r?.waiting) { const { waiting, ...rest } = r; results.set(n, rest); } // #4687: the batch ended: skipped for good
   save();
   const withRequeue = (r) => (r && requeuedInfo.has(r.issue) ? { ...r, requeued: { reason: requeuedInfo.get(r.issue).reason, by: requeuedInfo.get(r.issue).by, prior: requeuedInfo.get(r.issue).prior.map((p) => ({ outcome: p.outcome, detail: p.detail ?? null, pr: p.pr ?? null })) } } : r);
-  return order.map((n) => withRequeue(results.get(n)) ?? { issue: n, outcome: "held", pr: null, cost_usd: 0, minutes: 0, detail: heldDetail(n),
+  const quotaRow = (n) => { // #5094: still pending after a quota pause: held (resumable), labelled paused (quota), with the paused attempts' cost
+    const q = quota.get(n);
+    if (!q || cancelled || opHeld.has(n)) return {};
+    const iso = new Date(Number(q.resumeAt) || now()).toISOString();
+    return { cost_usd: Number(q.cost_usd) || 0, minutes: Number(q.minutes) || 0, quota: { resumeAt: iso }, detail: `paused (quota) until ${iso}` };
+  };
+  return order.map((n) => withRequeue(results.get(n)) ?? { issue: n, outcome: "held", pr: null, cost_usd: 0, minutes: 0, detail: heldDetail(n), ...quotaRow(n),
     ...(recovering.has(n) ? { recovery: { code: recovering.get(n).code, attempts: recoveries.get(n) ?? recovering.get(n).attempt, outcome: recovering.get(n).outcome ?? "needs-human",
       ...(recovering.get(n).result_code ? { result_code: recovering.get(n).result_code } : {}), detail: firstLine(recovering.get(n).detail ?? recovering.get(n).code) } } : {}) });
 }
@@ -1314,6 +1366,22 @@ export const OUTCOME_LINE_MAX = 200;
  * mechanical needs-human row (failed recovery or a terminal code), then one escalation list holding only human codes,
  * asked once at the end of the batch. Empty when there is nothing to list.
  */
+/**
+ * #5078: one `follow-ups appended:` line grouped by issue across rows: `#N (<class>: k item(s) from #a,#b)`, the post-deploy
+ * rollup named as such. Null when no row filed follow-ups.
+ */
+function formatFollowupsLine(rows) {
+  const by = new Map();
+  for (const r of rows ?? []) for (const f of Array.isArray(r?.followups) ? r.followups : []) {
+    if (!Number.isInteger(f?.issue) || f.issue <= 0) continue;
+    const g = by.get(f.issue) ?? { classes: new Set(), count: 0, from: new Set() };
+    if (f.class) g.classes.add(String(f.class));
+    g.count += Number(f.count) || 0; g.from.add(r.issue); by.set(f.issue, g);
+  }
+  if (!by.size) return null;
+  const name = (c) => (c === "post-deploy" ? "post-deploy rollup" : c === "external" ? "external aggregate" : c);
+  return `follow-ups appended: ${[...by].sort((a, b) => a[0] - b[0]).map(([n, g]) => `#${n} (${[...g.classes].sort().map(name).join("+") || "follow-up"}: ${g.count} item(s) from ${[...g.from].map((i) => `#${i}`).join(",")})`).join(" ")}`;
+}
 export function formatOutcomeLists(rows) {
   const out = [];
   const one = (x) => String(x ?? "").split("\n")[0].slice(0, OUTCOME_LINE_MAX);
@@ -1332,6 +1400,8 @@ export function formatOutcomeLists(rows) {
   if (rq.length) out.push(`remediation queue (/work-on:remediate): ${rq.map((r) => `#${r.issue} (parked:${r.code}${r.pr ? ` PR #${r.pr}` : ""})`).join(" ")}`);
   const parked = formatParkedLine(rows); // #4389: one line for every parked post-deploy follow-up, never an escalation
   if (parked) out.push(parked);
+  const fu = formatFollowupsLine(rows); // #5078: follow-ups appended, not "issues filed"
+  if (fu) out.push(fu);
   const decided = (rows ?? []).filter((r) => r?.decided); // #4766: settled by the decision engine, listed not hidden
   if (decided.length) out.push(["decided (north-star engine, veto with the forge:decision-veto label):", ...decided.map((r) => `- #${r.issue}: ${one(r.decided.choice)}${r.decided.shadow ? " (shadow)" : ""}`)].join("\n"));
   if (esc.length) out.push(["escalations (human decisions, asked once):", ...esc.map((r) => `- #${r.issue} (${r.code}): ${one(r.detail)}`)].join("\n"));
@@ -1342,7 +1412,7 @@ export function formatTable(rows) {
   // #4255: sandbox minutes and cost next to the token cost, only when some lane ran in a sandbox.
   const sbx = rows.some((r) => r?.sandbox);
   const head = ["issue", "outcome", "PR", "cost", ...(sbx ? ["sbx-min", "sbx-$"] : []), "min"];
-  const body = rows.map((r) => [`#${r.issue}`, (r.waiting && /^dependency #(\d+) /.test(r.detail ?? "") ? `waiting on #${/^dependency #(\d+) /.exec(r.detail)[1]}` : r.outcome) + (["skipped", "held"].includes(r.outcome) && r.detail ? ` (${r.detail})` : r.prefilter?.closed || r.prefilter?.parked ? " (pre-filter)" : ""), r.pr ? `#${r.pr}` : "-", `$${(r.cost_usd ?? 0).toFixed(2)}`,
+  const body = rows.map((r) => [`#${r.issue}`, r.quota?.resumeAt && ["held", "paused"].includes(r.outcome) ? `paused (quota) until ${r.quota.resumeAt}` : (r.waiting && /^dependency #(\d+) /.test(r.detail ?? "") ? `waiting on #${/^dependency #(\d+) /.exec(r.detail)[1]}` : r.outcome) + (["skipped", "held"].includes(r.outcome) && r.detail ? ` (${r.detail})` : r.prefilter?.closed || r.prefilter?.parked ? " (pre-filter)" : ""), r.pr ? `#${r.pr}` : "-", `$${(r.cost_usd ?? 0).toFixed(2)}`,
     ...(sbx ? (r.sandbox ? [(Number(r.sandbox.minutes) || 0).toFixed(1), `$${(Number(r.sandbox.cost_usd) || 0).toFixed(2)}`] : ["-", "-"]) : []), String(r.minutes ?? 0)]);
   const w = head.map((h, i) => Math.max(h.length, ...body.map((b) => b[i].length)));
   const line = (c) => c.map((x, i) => x.padEnd(w[i])).join("  ").trimEnd();

package/bin/lean/probe.mjs

@@ -282,7 +282,7 @@ export async function sweepProbes({ repo, cwd = process.cwd(), io, issues = null
   const rows = [];
   for (const issue of list) {
     try { rows.push(await probeIssue({ issue, repo, cwd, io, defaultBranch, dryRun, config, env, spawn })); } catch (e) {
-      rows.push({ issue, outcome: "error", detail: String(e?.message ?? e).slice(0, 160) });
+      rows.push({ issue, outcome: "error", detail: `probe #${issue}: ${String(e?.message ?? e).slice(0, 140)}` });
     }
     try { if (!dryRun) await onResult?.(rows[rows.length - 1]); } catch { /* an event sink never fails the sweep (#4630) */ }
   }
@@ -292,7 +292,9 @@ export async function sweepProbes({ repo, cwd = process.cwd(), io, issues = null
 const GROUPS = [["pass", "pass"], ["fail", "fail (reopened)"], ["awaiting-promotion", "awaiting promotion"], ["unresolved", "unresolved fix"], ["untrusted", "untrusted (not run)"], ["error", "error"]];
 /** One line, e.g. `probes: pass #A; fail (reopened) #B; awaiting promotion #C`; "" when nothing ran or waits. */
 export function formatProbeSummary(rows) {
-  const parts = GROUPS.map(([k, label]) => [label, (rows ?? []).filter((r) => r.outcome === k).map((r) => `#${r.issue}`)])
+  // #5080: an error row names its cause (the probe step and message) instead of a bare issue number
+  const ref = (r) => r.outcome === "error" && String(r.detail ?? "").trim() ? `#${r.issue} (${String(r.detail).replace(/\s+/g, " ").trim().slice(0, 120)})` : `#${r.issue}`;
+  const parts = GROUPS.map(([k, label]) => [label, (rows ?? []).filter((r) => r.outcome === k).map(ref)])
     .filter(([, l]) => l.length).map(([label, l]) => `${label} ${l.join(" ")}`);
   return parts.length ? `probes: ${parts.join("; ")}` : "";
 }

package/bin/lean/probe.test.mjs

@@ -199,6 +199,10 @@ describe("probe (#4399)", () => {
       "probes: pass #1; fail (reopened) #2; awaiting promotion #3");
     assert.equal(formatProbeSummary([{ issue: 4, outcome: "already-recorded" }]), "");
   });
+  it("#5080 an error row names the probe and the cause, not a bare issue number", () => {
+    assert.equal(formatProbeSummary([{ issue: 38074, outcome: "error", detail: "probe #38074: gh: HTTP 502" }]), "probes: error #38074 (probe #38074: gh: HTTP 502)");
+    assert.equal(formatProbeSummary([{ issue: 7, outcome: "error" }]), "probes: error #7");
+  });
 
   it("forge.yaml config defaults and a real spawn honour exit, timeout and env", async () => {
     assert.deepEqual(readProbeConfig("/nonexistent"), { env: [], timeoutS: 120, sweepDays: 30, enabled: true });

package/bin/lean/prompts.mjs

@@ -157,19 +157,21 @@ ${HOST_RULES}${toolchainRule(toolchain)}${sparseRule(sparse)}${factsRule(facts)}
 
 If the issue is already fixed or invalid, write ${RESULT_FILE} {"status":"already-fixed|invalid","summary":"one line","evidence":["file:line ..."]} and stop. If it is blocked, write {"status":"blocked","summary":"",...} with a typed "block" (rules below) and stop.
 
-2. Otherwise write ${CONTRACT_FILE}, the frozen hand-off: a developer who never saw the issue must be able to implement and verify it from this file alone.
-{"requirements":[{"id":"R1","quote":"<verbatim sentence or checklist item from the issue>","disposition":"deliver|defer|post-deploy|not-applicable","why":"<defer, post-deploy>","bucket":"<defer, post-deploy: post-deploy|verify-now|date:YYYY-MM-DD|owner:<action>|new-issue>","check":"<post-deploy: id in .forge/post-deploy-checks.json>","evidence":"<file:line, required for not-applicable>","verify":"<optional: in_lane|out_of_band>"}],
+2. Otherwise write ${CONTRACT_FILE}, the frozen hand-off: a developer who never saw the issue must be able to implement and verify from this file alone.
+{"requirements":[{"id":"R1","quote":"<verbatim sentence or checklist item from the issue>","disposition":"deliver|defer|post-deploy|not-applicable","why":"<defer, post-deploy>","bucket":"<defer, post-deploy: post-deploy|verify-now|date:YYYY-MM-DD|owner:<action>|new-issue|host>","check":"<post-deploy: id in .forge/post-deploy-checks.json>","evidence":"<file:line, required for not-applicable>","verify":"<optional: in_lane|out_of_band>"}],
  "deliverables":[{"id":"D1","path":"<file to change>","change":"<what>","requirements":["R1"]}],
  "preserve":[{"id":"P1","what":"<caller, contract or behaviour that must not change, with its path>"}],
  "validate":[{"id":"V1","command":"<exact command: the new regression test plus the existing tests that reference the files you change; a git diff compares against the merge base (origin/<lane>...HEAD), never the moving origin/<lane> tip>"}],
  "decisions":[{"id":"K1","choice":"<a non-obvious choice: a new dependency, a copied pattern, a boundary relied on>","justification":"<why, with file:line>","source":"doc|lint|precedent|spec"}]}
-Every requirement and acceptance criterion in the issue and its maintainers' comments is one requirement, quoted verbatim (others' comments are context, not requirements). Never drop or narrow one silently: "defer" (separate work) and "post-deploy" (only checkable after a deploy) are judged by the reviewer and, if accepted, filed by the engine as a tracked follow-up issue. Every defer or post-deploy row has one "bucket": post-deploy (needs a release), verify-now (parent already on the default branch), date:YYYY-MM-DD (absolute, never a relative wait), owner:<action> (credentials, spend, settings, promotion of a default-off flag; disposition defer, never post-deploy) or new-issue (future work). One sentence is one row. An outcome criterion this change can ship as a test, metric or alert is "deliver". A requirement you can do in this change is "deliver". A deliver requirement whose result is only measured outside the lane (Lighthouse, field perf, a nightly or report-only suite) is "verify":"out_of_band" with "evidence" naming the job or workflow that measures it (delivered by its instrumentation). The engine tags such quotes itself; set "verify":"in_lane" when this change can check it. List every file you will change as a deliverable; tests are always allowed.
+Every requirement and acceptance criterion in the issue and its maintainers' comments is one requirement, quoted verbatim (others' comments are context, not requirements). Never drop or narrow one silently: "defer" (separate work) and "post-deploy" (only checkable after a deploy) are judged by the reviewer and, if accepted, filed by the engine as a tracked follow-up issue. Every defer or post-deploy row has one "bucket": post-deploy (needs a release), verify-now (parent already on the default branch), date:YYYY-MM-DD (absolute, never a relative wait), owner:<action> (only credentials, spend, an account, a third party, a customer; defer, never post-deploy), host (read-only prod data: obs-psql, *-monitor) or new-issue (future work). A post-promotion check without a check id is post-deploy. One sentence is one row. An outcome criterion this change can ship as a test, metric or alert is "deliver". A deliver requirement whose result is only measured outside the lane (Lighthouse, field perf, a nightly or report-only suite) is "verify":"out_of_band" with "evidence" naming the job or workflow that measures it (delivered by its instrumentation). The engine tags such quotes itself; set "verify":"in_lane" when this change can check it. List every file you will change as a deliverable; tests are always allowed.
 A new default-off flag or rollout key needs an activation row: defer, bucket \`owner:promote:<flag>\`, why = first cohort, guard metrics, shadow evidence (an AC naming shadow/cohort/treated fails if it ships off).
 A [type:e2e] requirement needs a validate that runs a real e2e check (repo e2e set, Playwright, live stack), not a stubbed unit test; else post-deploy.
 A validate or repro command must not read a $TMPDIR file it did not create: each run gets a fresh TMPDIR.
 Scope is enforced by the engine: it checks the changed files against the deliverables plus typed amendments itself, so do not write a file-allowlist or denylist validate (git diff --name-only | grep); the engine drops such a validate at freeze.
 A new dependency between workspace packages (a workspace package added to a package.json dependencies, devDependencies or peerDependencies) must be a deliverable on that package.json whose change names the package and gives the reason, citing the architecture doc where there is one; "the lint allows it" or "there is a precedent" is not a reason on its own. Record each non-obvious choice in "decisions" with where its justification comes from (doc, lint, precedent or spec); omit the field when none. Then stop.
 
+An added route needs its production ingress rule cited in ${INVESTIGATION_FILE}. No decision may swap e2e for mocked tests without a forge-probe.
+
 ${BLOCK_RULES}`;
 }
 
@@ -177,7 +179,7 @@ ${BLOCK_RULES}`;
  * #4374: the conformance rubric, one definition shared verbatim by `reviewerPrompt` and the builder's self-review in
  * `builderImplementPrompt`, so the two cannot drift. Each question is answered yes (OK) or no; codebase-agnostic.
  */
-export const REVIEW_RUBRIC = `1. Fixed: does the diff resolve the issue as written, delivering every requirement and acceptance criterion of the issue and every contract requirement with disposition deliver? An out-of-band requirement is delivered by its instrumentation (budget test or bench committed, job configured), not its measured result. A [type:e2e] requirement is delivered only when its validate command is a real end-to-end check, not a unit test with stubbed I/O.
+export const REVIEW_RUBRIC = `1. Fixed: does the diff resolve the issue as written, delivering every requirement and acceptance criterion of the issue and every contract requirement with disposition deliver? An out-of-band requirement is delivered by its instrumentation (budget test or bench committed, job configured), not its result. A [type:e2e] requirement is delivered only by a real end-to-end validate, not a unit test with stubbed I/O. Swapping e2e for mocks without a forge-probe, or a route without ingress evidence, is not delivery.
 2. No regression: is the diff free of breakage of an existing caller, test or behaviour (a concrete path:line failure)?
 3. Contract: is every deliverable changed as described, every preserve item intact and every validate command passing?
 4. Scope: does the diff change only deliverable paths and tests?`;
@@ -201,16 +203,16 @@ ${HOST_RULES}${toolchainRule(toolchain)}${sparseRule(sparse)}${factsRule(facts)}
 The contract changes only through typed amendments in ${RESULT_FILE}, each with a why:
 - {"kind":"add-deliverable","path":"<file>","why":""}: a file not listed.
 - {"kind":"add-requirement","requirement":{"id":"R9","quote":"<verbatim from the issue>","disposition":"deliver|defer|post-deploy"},"why":""}: a missed requirement.
-- {"kind":"defer|post-deploy","requirement":"R#","why":"","check":"<id>"}: separate work or a post-deploy check, filed as a follow-up. Not "type"; unknown kinds are rejected. One requirement id per row.
+- {"kind":"defer|post-deploy","requirement":"R#","why":"","check":"<id>"}: separate work or a post-deploy check, filed as a follow-up. Not "type"; unknown kinds are rejected. One requirement id per row. An impossible deliverable is a defer, not a new kind.
 - {"kind":"amend-requirement","requirement":"R#","text":"<revised wording>","why":""}: reworded.
-- {"kind":"supersedes","guard":"#N","why":""}: overrides a guard_broken failure (e.g. new enum code).
+- {"kind":"supersedes","guard":"#N","why":""}: overrides a guard_broken failure.
 - {"kind":"decision","decision":{"choice":"","anchors":["<base path>"],"supersedes":"<id>"},"why":""}: supersedes changes an H-row.
 New keys: translate, never copy English; status entries in place.
 Never report a deliver requirement as "deferred" or "follow-up" without an amendment.
 Never name or number migration files by hand; use the generator.
 A [type:e2e] requirement needs a validate that runs a real e2e check (repo e2e set, Playwright, live stack), not a stubbed unit test; else post-deploy.
 A new workspace-package dependency in a package.json no deliverable names is blocked by the engine: add it through add-deliverable with a why naming the package, or do not add it.
-If the repository has scripts/check-devdocs-freshness.sh, a behaviour change under the paths it checks must update the matching dossier (devdocs/modules/*.md, per devdocs/index.yaml) in the same change. Run it against the base first; the engine runs it too.
+If scripts/check-devdocs-freshness.sh exists, a behaviour change under its paths must update the matching dossier (devdocs/modules/*.md, per devdocs/index.yaml) in the same change; run it against the base first.
 
 Before writing ${RESULT_FILE}, after your last edit, run \`node ${FORGEDOCK_CLI} check\` in the worktree and fix until it passes; if it cannot pass, report the problem as blocked.
 
@@ -246,7 +248,7 @@ export function contextPackNote(pack) {
 /** #4857: validate-command rules for the plan prompt (the implement session resumes it), kept out of the shared templates (their token caps are guarded). */
 export function unrunnableValidateNote(testRunners = null) {
   const map = testRunners && typeof testRunners === "object" ? Object.entries(testRunners).map(([k, v]) => `${k}/ -> ${v}`).join("; ") : "";
-  return `\n\nValidate and repro commands must pass bash -n (no prose notes), select tests that exist, and run from the right cwd${map ? ` (forge.yaml verification.test_runners: ${map})` : ""}. An unrunnable validate (missing tool, wrong cwd, no tests selected) is never a block or "human" product-decision: run an equivalent through the repo's toolchain and record {"kind":"substitute-validate","validate":"V#","command":"<runnable equivalent>","why":""} in ${RESULT_FILE} amendments. A post-deploy requirement needs a registered check id; one that is a manual or production-credential action with no runnable check is disposition "defer" with bucket "owner:<action>" (the engine also converts a check-less post-deploy to a defer to the orchestrator). forge.yaml validate.recipes rewrite matching commands at freeze.`;
+  return `\n\nValidate and repro commands must pass bash -n (no prose notes), select tests that exist, and run from the right cwd${map ? ` (forge.yaml verification.test_runners: ${map})` : ""}. An unrunnable validate (missing tool, wrong cwd, no tests selected) is never a block or "human" product-decision: run an equivalent through the repo's toolchain and record {"kind":"substitute-validate","validate":"V#","command":"<runnable equivalent>","why":""} in ${RESULT_FILE} amendments. A post-deploy requirement needs a registered check id; one that is a manual or production-credential action with no runnable check is disposition "defer" with bucket "owner:<action>" only when it needs credentials, spend, an account, a third party or a customer; read-only prod data is "host". forge.yaml validate.recipes rewrite matching commands at freeze.`;
 }
 
 export function reproPlanNote(on) {
@@ -331,6 +333,11 @@ export function contractCorrectionPrompt(problems) {
   return `Your ${CONTRACT_FILE} is not valid:\n${problems.slice(0, 20).map((p) => `- ${p}`).join("\n")}\n\nFix the contract (planning only, no code, no commit) and stop. Do not push or touch GitHub.`;
 }
 
+/** #5089: the builder's amendments name an unknown kind or miss a field; one correction before the conformance gate. */
+export function amendmentCorrectionPrompt(problems) {
+  return `The amendments in ${RESULT_FILE} are not valid:\n${problems.slice(0, 20).map((p) => `- ${p}`).join("\n")}\n\nRewrite them with a valid kind: add-deliverable, add-requirement, defer, post-deploy, amend-requirement, supersedes, decision, substitute-validate or out-of-band. A deliverable that is impossible on this platform is {"kind":"defer","requirement":"R#","why":""}, not a changed deliverable. Edit only ${RESULT_FILE} (commit nothing else) and stop. Do not push or touch GitHub.`;
+}
+
 /** The one bounded correction round, in the builder's own session. */
 export function conformanceResumePrompt(failures, mode = "local", lane = "") {
   const baseMoved = lane && failures.some((f) => f?.kind === "validate_failed")
@@ -364,11 +371,11 @@ export const HUMAN_BLOCK_REASONS = Object.freeze(["credentials", "spend", "promo
 
 const BLOCK_RULES = `"blocked" needs a typed "block" in ${RESULT_FILE}, one of:
 - {"kind":"dependency","issues":[N]}: an open upstream issue must land first. The engine requeues this issue behind it.
-- {"kind":"split-required","subissues":[{"title":"","body":"","depends_on":[0],"files":["<path>"]}],"size":{"files":N,"lines":N}}: too big for one change. The engine files the sub-issues (depends_on = indexes of earlier sub-issues; files = the files or dirs each will edit, also accepted as "paths") only when every sub-issue's files are disjoint from the others' or the whole change's size estimate exceeds ${SPLIT_MIN_FILES} files or ${SPLIT_MIN_LINES} lines; otherwise keep one lane: an ordered checklist in the contract with a validate per item. In an admitted split, when siblings would edit the same hub (a barrel or index export list, a union type, a shared test fixture, an index doc), pre-stage its slots in the earliest sub-issue and make the others depend on it, or give each sibling its own per-feature file; the engine serialises sub-issues that still share a file.
+- {"kind":"split-required","subissues":[{"title":"","body":"","depends_on":[0],"files":["<path>"]}],"size":{"files":N,"lines":N}}: too big for one change. The engine files the sub-issues (depends_on = indexes of earlier sub-issues; files = the files or dirs each will edit, also accepted as "paths") only when every sub-issue's files are disjoint from the others' or the whole change's size estimate exceeds ${SPLIT_MIN_FILES} files or ${SPLIT_MIN_LINES} lines; otherwise keep one lane: an ordered checklist in the contract with a validate per item. In an admitted split, siblings editing the same hub (barrel or index export list, union type, shared fixture, index doc) get its slots pre-staged in the earliest sub-issue, which the others depend on, or their own per-feature files; the engine serialises sub-issues still sharing a file.
 - {"kind":"human","why":"${HUMAN_BLOCK_REASONS.join("|")}"}: only an external action agents cannot take, or a product decision too critical for agents. Optional "remainder":[{"title","body"}]: the agent-doable rest, filed as its own issue.
 "An upstream issue must land first", "needs a split" and "needs prod data that read-only monitoring can read" are never "human".
-A check that times out (rc 124) is host load, never a block or "human" product-decision: run the narrowest targeted command for your changed files and say the full one could not finish in time.
-Remote sandbox lacking a host-only capability (sops, prod_monitor, ops_credentials): name it in the summary; the host reruns the lane.`;
+A check that times out (rc 124) is host load, never a block: run the narrowest targeted command for your changed files and say the full one could not finish.
+Remote sandbox lacking a host-only capability (sops, prod_monitor, ops_credentials): name it in the summary.`;
 
 export function blockCorrectionPrompt(problem) {
   return `Your ${RESULT_FILE} says "blocked", but ${String(problem).slice(0, 1000)}. That is not a block that needs a human.\n\n${BLOCK_RULES}\n\nEither do the work (fix, commit, update the stage notes and ${RESULT_FILE}) or write a valid typed "block". Do not push or touch GitHub.`;

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; }
+}