forgedock 1.49.0 → 1.51.0

package/bin/lean/prefilter.test.mjs

@@ -73,7 +73,7 @@ describe("pre-filter (#4123)", () => {
     const call = w.runner[0];
     assert.equal(call.model, DEFAULT_PREFILTER_MODEL); assert.equal(call.readOnly, true); assert.equal(call.resume, null); assert.equal(call.cwd, "/repo");
     assert.match(call.prompt, /merged PR #90/); assert.doesNotMatch(call.prompt, /PR #91/);
-    assert.deepEqual(w.closed, [[12, "not planned"]]);
+    assert.deepEqual(w.closed, [[12, "completed"]]); // #5152: ALREADY-FIXED is delivered
     assert.deepEqual(w.labels, [[12, "invalid"]]);
     assert.match(w.comments[0][1], /FORGE:PREFILTER/); assert.match(w.comments[0][1], /src\/foo\.js:3 null guard/); assert.match(w.comments[0][1], /PR #90/);
   });
@@ -120,7 +120,7 @@ describe("pre-filter (#4123)", () => {
     assert.equal(r.closed, true); assert.equal(r.kind, "ci-green");
     assert.equal(w.runner.length, 0);
     assert.match(w.comments[0][1], /actions\/runs\/600/); assert.match(w.comments[0][1], /actions\/runs\/500/);
-    assert.deepEqual(w.closed, [[34, "not planned"]]);
+    assert.deepEqual(w.closed, [[34, "completed"]]); // #5152: CI green again is delivered
   });
 
   it("#4305 the CI-green shortcut is skipped for intermittent, reopened and same-SHA-flaky CI failures", async () => {
@@ -204,7 +204,7 @@ describe("pre-filter (#4123)", () => {
     assert.equal(r2.closed, true); assert.equal(tiny.comments.length, 1); assert.match(tiny.comments[0][1], /^<!-- FORGE:PREFILTER -->/);
     assert.match(flakyReason({ comments: [{ body: tiny.comments[0][1], author: { login: "forgedock-app[bot]" }, authorAssociation: "NONE" }] }, ["forgedock-app"])?.reason ?? "", /reopened/);
     const dead = flaky(99); const r3 = await pf(dead, 34);
-    assert.equal(r3.closed, true); assert.equal(dead.runner.length, 0); assert.deepEqual(dead.closed, [[34, "not planned"]]); assert.match(r3.detail, /no marker comment/);
+    assert.equal(r3.closed, true); assert.equal(dead.runner.length, 0); assert.deepEqual(dead.closed, [[34, "completed"]]); assert.match(r3.detail, /no marker comment/);
   });
 
   it("a CI-failure issue whose workflow is still red (or whose latest run is the failing one) goes to a lane", async () => {
@@ -224,6 +224,7 @@ describe("pre-filter (#4123)", () => {
     assert.deepEqual(namedPaths("fix lib/a.js <!-- x/hidden.js --!> visible/e.js and <!-- unclosed c/d.js"), ["lib/a.js", "visible/e.js"]);
     const gone = world({ issues: { 5: { body: "crash in src/old/foo.js:12" } }, verdict: { verdict: "INVALID", evidence: ["src/old/foo.js removed in abc123"] } });
     assert.equal((await pf(gone, 5)).closed, true);
+    assert.deepEqual(gone.closed, [[5, "not planned"]], "#5152: only an INVALID verdict closes not planned");
     assert.match(gone.runner[0].prompt, /do not exist on origin\/staging: src\/old\/foo\.js/);
     const kept = world({ issues: { 5: { body: "crash in src/old/foo.js:12 and src/new.js/x.ts" } }, paths: ["src/old/foo.js"] });
     const r = await pf(kept, 5);
@@ -300,7 +301,7 @@ describe("orchestrate with the pre-filter (#4123)", () => {
     assert.deepEqual(res.lanes, [13]);
     assert.equal(logs.at(-1), "lanes: #13");
     assert.ok(logs.some((s) => /^pre-filter: 2 checked, 1 candidate\(s\), 1 closed/.test(s)));
-    assert.deepEqual(w.closed, [[12, "not planned"]]);
+    assert.deepEqual(w.closed, [[12, "completed"]]); // #5152: ALREADY-FIXED is delivered
     await assert.rejects(triageFromCli([], {}), /usage/);
   });
 

package/bin/lean/prompts.mjs

@@ -488,8 +488,10 @@ export function reviewerPrompt({ issue, comments = [], contract, result, files =
  * #4160: the targeted re-ask after an incomplete or inconsistent reply. Only the missing or invalid ids are asked
  * for, with the exact problems and the reviewer's previous reply; no diff is re-sent (the worktree still holds the change).
  */
-export function reviewerRepairPrompt({ missing = [], problems = [], rows = null }) {
-  return `Your conformance review is incomplete. The engine keeps your other rows; answer ONLY for these ids or sections: ${missing.join(", ") || "(see the problems)"}.\n\n<previous_reply_problems>\nYour previous reply was rejected as incomplete. Fix exactly these:\n${problems.slice(0, 60).map((p) => `- ${String(p).slice(0, 300)}`).join("\n")}\n</previous_reply_problems>\n\n<previous_reply>\n${cap(JSON.stringify(rows ?? {}), 20000)}\n</previous_reply>\n\nRead the changed files in your worktree as needed. Output ONLY a JSON object in a json code fence with just the rows for those ids (requirements rows by id, preserve rows by id, scope rows by file, issue_coverage in full if it is listed) plus "verdict":"CONFORMS|NONCONFORMING" consistent with all rows. Evidence is a backtick-quoted repo-relative path:line copied verbatim (e.g. \`apps/web/app/(console)/layout.tsx:12\`); for an evidence path reported as not existing, give the full repo-relative path of that file from the changed files or the repository.`;
+export function reviewerRepairPrompt({ missing = [], problems = [], rows = null, criteria = [] }) {
+  // #5164: a coverage misquote is re-asked with the issue's criterion lines verbatim, so the quote is copied, not retyped
+  const crit = (criteria ?? []).length ? `\n\n<issue_criteria>\nCopy every issue_coverage quote exactly (character for character, including #numbers and plurals) from one of these issue lines:\n${criteria.slice(0, 80).map((c) => `- ${String(c).slice(0, 400)}`).join("\n")}\n</issue_criteria>` : "";
+  return `Your conformance review is incomplete. The engine keeps your other rows; answer ONLY for these ids or sections: ${missing.join(", ") || "(see the problems)"}.\n\n<previous_reply_problems>\nYour previous reply was rejected as incomplete. Fix exactly these:\n${problems.slice(0, 60).map((p) => `- ${String(p).slice(0, 300)}`).join("\n")}\n</previous_reply_problems>${crit}\n\n<previous_reply>\n${cap(JSON.stringify(rows ?? {}), 20000)}\n</previous_reply>\n\nRead the changed files in your worktree as needed. Output ONLY a JSON object in a json code fence with just the rows for those ids (requirements rows by id, preserve rows by id, scope rows by file, issue_coverage in full if it is listed) plus "verdict":"CONFORMS|NONCONFORMING" consistent with all rows. Evidence is a backtick-quoted repo-relative path:line copied verbatim (e.g. \`apps/web/app/(console)/layout.tsx:12\`); for an evidence path reported as not existing, give the full repo-relative path of that file from the changed files or the repository.`;
 }
 
 /** Pre-filter (#4123): one read-only, single-turn check of an issue a cheap signal flagged as possibly already fixed. */

package/bin/lean/recovery.test.mjs

@@ -65,9 +65,9 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
     assert.equal(calls.filter((c) => c.n === 1).length, 2, "the first run plus exactly one recovery");
     assert.equal(r[1].outcome, "needs-human");
     assert.deepEqual(r[1].recovery, { code: "ci.red", attempts: 1, outcome: "needs-human", result_code: "ci.red", detail: "CI verification failed again" });
-    assert.equal(r[2].outcome, "skipped"); assert.ok(!calls.some((c) => c.n === 2));
+    assert.equal(r[2].outcome, "held"); assert.ok(!calls.some((c) => c.n === 2));
     const lines = formatOutcomeLists(rows);
-    assert.equal(lines.length, 1); assert.match(lines[0], /^unrecovered: #1 \(ci\.red: recovery ci\.red ended needs-human: CI verification failed again\)$/);
+    assert.equal(lines.length, 2); assert.match(lines[0], /^held subtree: #1 \(needs-human\) holds #2; release: forgedock orchestrate --requeue <batch> 1$/); assert.match(lines[1], /^unrecovered: #1 \(ci\.red: recovery ci\.red ended needs-human: CI verification failed again\)$/);
   });
 
   it("#4505 budget-exceeded: one recovery lane from the checkpoint at the next size; dependents stay queued; no relabel while it recovers", async () => {
@@ -92,7 +92,7 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
     assert.equal(calls.filter((c) => c.n === 1).length, 1);
     assert.equal(r[1].outcome, "budget-exceeded");
     assert.equal(relabels.length, 1); assert.equal(relabels[0].issue, 1); assert.match(relabels[0].evidence, /budget\.exceeded[\s\S]*size S/);
-    assert.equal(r[2].outcome, "skipped"); assert.ok(!calls.some((c) => c.n === 2));
+    assert.equal(r[2].outcome, "held"); assert.ok(!calls.some((c) => c.n === 2));
     assert.ok(formatOutcomeLists(rows).some((l) => /^unrecovered: #1 \(budget\.exceeded: Implement turn budget spent/.test(l)));
   });
 
@@ -124,7 +124,7 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
     assert.equal(calls.filter((c) => c.n === 1).length, 1); assert.equal(calls.filter((c) => c.n === 3).length, 1);
     assert.equal(calls.filter((c) => c.n === 4).length, 1, "terminal mechanical codes are not recovered either");
     assert.ok(!decisions.some((d) => [1, 3].includes(d.issue)));
-    assert.equal(r[2].outcome, "skipped"); assert.equal(r[5].outcome, "merged");
+    assert.equal(r[2].outcome, "held"); assert.equal(r[5].outcome, "merged");
     const lines = formatOutcomeLists(rows);
     assert.equal(lines.filter((l) => l.startsWith("escalations")).length, 1, "one escalation list");
     const esc = lines.find((l) => l.startsWith("escalations"));
@@ -187,7 +187,7 @@ describe("in-batch recovery of mechanical needs-human (#4267)", () => {
     const calls = [];
     const rows = await orchestrate({ issues: [1, 2], readBody: async (n) => (n === 2 ? "**Depends on**: #1" : ""),
       runOne: async (n) => { calls.push(n); return NH("ci.red"); } });
-    assert.deepEqual(calls, [1]); assert.deepEqual(rows.map((r) => r.outcome), ["needs-human", "skipped"]);
+    assert.deepEqual(calls, [1]); assert.deepEqual(rows.map((r) => r.outcome), ["needs-human", "held"]);
   });
 
   it("the attempt count survives a resume: a persisted recovery lane is launched with ctx.recover and is not retried again", async () => {

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

@@ -9,7 +9,7 @@ import { dirname, join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
 import { containerProvider, parseExecution, providerByName, providerLanes, remoteTransportFor } from "./execution.mjs";
 import { remoteProvider, httpTransport, isActionsEndpoint, redact } from "./sandbox-remote.mjs";
-import { resolveCredential } from "./credentials.mjs";
+import { memoKeychain, resolveCredential } from "./credentials.mjs";
 import { makeLedger } from "./ledger.mjs";
 import { openBatch } from "./batch.mjs";
 import { orchestrate } from "./orchestrate.mjs";
@@ -208,6 +208,27 @@ describe("remote adapter (#4254)", () => {
     await assert.rejects(r.status("x"), /router auth/);
   });
 
+  it("5144 httpTransport: a function token is resolved per call", async () => {
+    let cur = null;
+    const seen = [];
+    const t = httpTransport({ endpoint: "https://pool.example", token: () => cur, fetchFn: async (url, init) => { seen.push(init.headers.authorization ?? null); return { status: 200, ok: true, text: async () => JSON.stringify({ state: "running" }), headers: { get: () => null } }; } });
+    await t.status("x"); cur = "tok-new"; await t.status("x"); cur = "tok-rotated"; await t.status("x"); cur = null; await t.status("x");
+    assert.deepEqual(seen, [null, "Bearer tok-new", "Bearer tok-rotated", null]);
+  });
+
+  it("5144 remoteProvider: a token rotated after construction is redacted from pulled logs", async () => {
+    const batch = openBatch(join(tmpDir("remote-5144-"), "batches"), "bt");
+    const transport = fakeTransport();
+    let tok = null;
+    const p = remoteProvider({ batch, repo: "o/r", settings: { tokenEnv: "FD_TOKEN" }, transport, env: {}, credentials: (n) => (n === "FD_TOKEN" ? tok : null), gitIdentity: () => ({}) });
+    tok = "rotated-secret-789";
+    const h = await p.start({ issue: 3, args: [], env: {}, secrets: [] });
+    transport.boxes.get(h.id).log = `leak ${tok}\n`;
+    await p.status(h);
+    const log = readFileSync(batch.logFile(3), "utf8");
+    assert.equal(log.includes(tok), false);
+  });
+
   it("httpTransport: bearer token, JSON protocol, 404 = gone/destroyed, 429 retryable; the token never in errors", async () => {
     const calls = [];
     const reply = (status, body, headers = {}) => ({ status, ok: status >= 200 && status < 300, text: async () => (body === undefined ? "" : JSON.stringify(body)), headers: { get: (k) => headers[k] ?? null } });
@@ -265,6 +286,20 @@ describe("remote config and the Actions constraint (#4254)", () => {
     assert.equal(resolveCredential("FD_T", { env: {}, keychain: () => { throw new Error("locked"); } }), null);
     assert.equal(resolveCredential("bad name", { env: { "bad name": "x" } }), null);
   });
+
+  it("5159 memoKeychain: one lookup per name per TTL, misses and failures cached as null", () => {
+    let t = 0;
+    const calls = [];
+    const kc = memoKeychain({ keychain: (n) => { calls.push(n); if (n === "BAD") throw new Error("locked"); return n === "HIT" ? "v" : null; }, ttlMs: 1000, now: () => t });
+    assert.equal(kc("HIT"), "v"); assert.equal(kc("HIT"), "v");
+    assert.equal(kc("MISS"), null); assert.equal(kc("MISS"), null);
+    assert.equal(kc("BAD"), null); assert.equal(kc("BAD"), null);
+    assert.deepEqual(calls, ["HIT", "MISS", "BAD"]);
+    t = 1000;
+    assert.equal(kc("MISS"), null);
+    assert.deepEqual(calls, ["HIT", "MISS", "BAD", "MISS"], "re-read after the TTL");
+    assert.equal(resolveCredential("MISS", { env: { MISS: "e" }, keychain: kc }), "e", "the env still wins");
+  });
 });
 
 describe("gc reaps a remote sandbox left by a dead dispatcher (#4254)", () => {

package/bin/lean/sandbox-remote.mjs

@@ -43,7 +43,8 @@ export function isActionsEndpoint(endpoint) {
 /**
  * Generic HTTP transport: POST {endpoint}/sandboxes (body = launch spec), GET /sandboxes/:id -> {state},
  * GET /sandboxes/:id/logs?cursor=N -> {text, cursor}, GET /sandboxes/:id/result -> lane result (404 = none yet),
- * GET /sandboxes/:id/usage -> {minutes, agent?} (agent: the pool agent that ran it, #4549), DELETE /sandboxes/:id (404 = gone). `Authorization: Bearer <token>`.
+ * GET /sandboxes/:id/usage -> {minutes, agent?} (agent: the pool agent that ran it, #4549), DELETE /sandboxes/:id (404 = gone). `Authorization: Bearer <token>`
+ * (`token` is a string, or a function called per request, #5144).
  * 429/503 on launch is a retryable capacity error (`Retry-After` seconds). Error text never carries the token.
  * Optional `POST /sandboxes/:id/stop` (#4612) asks the pool to SIGTERM the lane so its teardown checkpoints and it reports `deferred run.interrupted`; 2xx = sent, 404/405 = unsupported or gone (never a DELETE fallback).
  * Optional relay (#4778): `GET /sandboxes/:id/relay -> {requests: [{rid, argv}]}` lists a sandbox's pending read-only capability
@@ -53,7 +54,9 @@ export function isActionsEndpoint(endpoint) {
 export function httpTransport({ endpoint, token = null, fetchFn = globalThis.fetch }) {
   const root = String(endpoint ?? "").replace(/\/+$/, "");
   const call = async (method, path, body) => {
-    const res = await fetchFn(`${root}${path}`, { method, headers: { accept: "application/json", ...(body ? { "content-type": "application/json" } : {}), ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    // #5144: `token` may be a function, resolved on every request so a token fixed or rotated mid-batch is the next bearer.
+    const bearer = typeof token === "function" ? token() : token;
+    const res = await fetchFn(`${root}${path}`, { method, headers: { accept: "application/json", ...(body ? { "content-type": "application/json" } : {}), ...(bearer ? { authorization: `Bearer ${bearer}` } : {}) },
       ...(body ? { body: JSON.stringify(body) } : {}) });
     let data = null;
     try { const t = await res.text(); data = t ? JSON.parse(t) : null; } catch { data = null; }
@@ -195,6 +198,7 @@ export function remoteProvider({ batch, repo, settings = {}, name = "remote", tr
       const id = idFor(issue);
       // Each allowlisted secret from the env, else the keychain (#4254); nothing else from the host.
       const resolved = {};
+      if (settings.tokenEnv) remember(credentials(settings.tokenEnv)); // #5144: a token rotated since construction is redacted too
       for (const k of secrets) { const v = laneEnv?.[k] !== undefined && laneEnv[k] !== "" ? String(laneEnv[k]) : credentials(k); if (v) { resolved[k] = v; remember(v); } }
       const li = args.indexOf("--lane");
       const resultFile = `/result/${issue}.json`;

package/bin/lean/schedd.mjs

@@ -11,6 +11,7 @@
  *   {op:"attach", id, resume?}    → (`resume` also clears a pending cancel, #4592) log.jsonl rows replayed, then live rows/lines and done; a finished batch replays report.json
  *                                   ({type:"done", replay:true}) unless it has unrun added issues; a batch nobody hosts is resumed here
  *   {op:"set-parallel", id, k}    → {type:"ok", parallel}
+ *   {op:"set-execution", id, maxRemote?, mode?} → {type:"ok", execution} (#5138): live max_remote / placement (remote|hybrid|local); remote/hybrid refused for a batch with no provider
  *   {op:"requeue", id, issues, reason, by} → {type:"ok", requeued, refused, hosted, reopened} (#4550): see batch.requeue; a finished batch is hosted again
  *   {op:"add", id, issues}        → {type:"ok", added, skipped, hosted} (#4408): merged into the batch's `add` file, which a
  *                                   hosted runner reads on its next pass and an unhosted batch on its next resume
@@ -42,6 +43,7 @@ import { fileURLToPath } from "node:url";
 import { schedDir, pidAlive } from "./sched.mjs";
 import { HEARTBEAT_MS, writeHeartbeat, clearHeartbeat } from "./schedd-health.mjs";
 import { batchRoot, listBatches, openBatch, SECRET_ENV } from "./batch.mjs";
+import { applySetExecution } from "./live-execution.mjs";
 
 export const IDLE_MS = 10 * 60 * 1000;
 export const STOP_MS = 10 * 1000;
@@ -250,6 +252,13 @@ export async function startDaemon({ dir = schedDir(), runBatch, idleMs = Number(
       b.setParallel(Number(req.k));
       return send({ type: "ok", parallel: Number(req.k) }, true);
     }
+    if (req.op === "set-execution") {
+      // #5138: live max_remote / placement mode; the hosted runner re-reads the batch's `execution` file on every admission.
+      const b = openBatch(root, req.id);
+      if (!b.exists()) throw new Error(`no batch ${req.id} in ${root}`);
+      const execution = applySetExecution(b, { ...(req.maxRemote !== undefined ? { maxRemote: req.maxRemote } : {}), ...(req.mode !== undefined ? { mode: req.mode } : {}) });
+      return send({ type: "ok", execution }, true);
+    }
     if (req.op === "add") {
       const b = openBatch(root, req.id);
       if (!b.exists()) throw new Error(`no batch ${req.id} in ${root}`);

package/bin/pool/agent.mjs

@@ -245,6 +245,8 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
     const c = credCache[kind];
     if (!c || now() - c.at > CRED_TTL[kind]) {
       const x = await call(cfg.router_url, "GET", `/agent/creds/${kind}`, { token: cfg.token, timeoutMs: 20000 });
+      // #5165: every router login at its usage ceiling -> pass the typed 429 (reason, reset) through, uncached, so the lane defers.
+      if (x.status === 429 && x.data && typeof x.data === "object") return { status: 429, body: x.data, retryAfter: x.retryAfter };
       if (!x.ok || !x.data?.token) return { status: 502, body: { error: `router credentials (${kind}): HTTP ${x.status}` } };
       credCache[kind] = { token: x.data.token, at: now() };
     }
@@ -397,7 +399,7 @@ export function createAgent(cfg, { docker, now = () => Date.now(), log = console
     const url = new URL(req.url, "http://agent");
     try {
       const cred = req.method === "GET" && /^\/sandboxes\/([^/]+)\/creds\/([a-z]+)$/.exec(url.pathname);
-      if (cred) { const r = await sandboxCred(decodeURIComponent(cred[1]), cred[2], req); return send(res, r.status, r.body); }
+      if (cred) { const r = await sandboxCred(decodeURIComponent(cred[1]), cred[2], req); return send(res, r.status, r.body, r.retryAfter ? { "retry-after": String(r.retryAfter) } : {}); }
       const relay = (req.method === "POST" && /^\/sandboxes\/([^/]+)\/relay$/.exec(url.pathname)) || (req.method === "GET" && /^\/sandboxes\/([^/]+)\/relay\/([^/]+)$/.exec(url.pathname));
       if (relay) { const r = await sandboxRelay(decodeURIComponent(relay[1]), relay[2] ? decodeURIComponent(relay[2]) : null, req); return send(res, r.status, r.body ?? {}); }
       if (url.pathname !== "/health" && !bearerOk(req, cfg.token)) return send(res, 401, { error: "unauthorized", hop: "agent", reason: "agent auth: router token rejected by agent" });

package/bin/pool/router.mjs

@@ -93,19 +93,28 @@ export function createRouter(cfg, { fetchFn = globalThis.fetch, now = () => Date
     }
     return gh.token;
   }
-  // Claude access token for sandboxes: the logged-in account on this host with the most validity left. Only the
-  // short-lived access token is shared; refresh tokens stay here, so this host keeps refreshing its own sessions.
+  // Claude access token for sandboxes (#5165): among the logins with 30+ minutes left, the one with the lowest tokenbaton
+  // usage (validity breaks ties). Only the short-lived access token is shared; refresh tokens stay here, so this host
+  // keeps refreshing its own sessions.
   function claudeToken() {
     const dirs = cfg.claude_config_dirs ?? readdirSync(homedir()).filter((d) => /^\.claude(-\d+)?$/.test(d)).map((d) => join(homedir(), d));
-    let best = null;
+    const logins = [];
     for (const d of dirs) {
       try {
         const o = JSON.parse(readFileSync(join(d, ".credentials.json"), "utf8")).claudeAiOauth;
-        if (o?.accessToken && o.expiresAt > now() + 30 * 60000 && (!best || o.expiresAt > best.expiresAt)) best = o;
+        const n = /\.claude-(\d+)$/.exec(d)?.[1];
+        if (o?.accessToken) logins.push({ n: n ? Number(n) : null, accessToken: o.accessToken, expiresAt: o.expiresAt });
       } catch { /* no login in this dir */ }
     }
-    if (!best) throw Object.assign(new Error("no Claude login on the router host with 30+ minutes left"), { status: 503 });
-    return { token: best.accessToken, expires_at: new Date(best.expiresAt).toISOString() };
+    const src = usageSource(cfg);
+    const usage = readUsage(src, logins.map((l) => l.n).filter((n) => n !== null));
+    const pick = pickClaudeLogin({ logins, usage, ceilingPct: cfg.usage_ceiling_pct ?? 95, now: now() });
+    if (pick.status === 503) throw Object.assign(new Error("no Claude login on the router host with 30+ minutes left"), { status: 503 });
+    if (pick.status === 429) { log.warn?.(`claude login: every account at or above the usage ceiling; ${pick.body.reason}`); return pick; }
+    if (pick.fallback) log.warn?.(`claude login: no usage source (${src}), falling back to longest validity`);
+    const { login, pct } = pick;
+    log.info?.(`claude login selected: account=${login.n ?? "default"} usage=${pct ?? "unknown"}% expires_at=${new Date(login.expiresAt).toISOString()}`);
+    return { status: 200, body: { token: login.accessToken, expires_at: new Date(login.expiresAt).toISOString() } };
   }
   const agentCall = (a, method, path, body, timeoutMs) => call(a.url, method, path, { body, token: a.token, timeoutMs, fetchFn });
 
@@ -285,7 +294,7 @@ export function createRouter(cfg, { fetchFn = globalThis.fetch, now = () => Date
     [route("GET", "/agents"), fd(async () => ({ status: 200, body: { agents: await capacities(), sandboxes: sbx() } }))],
     [route("POST", "/codes"), fd(async () => ({ status: 200, body: issueCode() }))],
     [route("GET", "/agent/creds/github"), { fn: async () => ({ status: 200, body: { token: await githubToken() } }), auth: "agent" }],
-    [route("GET", "/agent/creds/claude"), { fn: async () => ({ status: 200, body: claudeToken() }), auth: "agent" }],
+    [route("GET", "/agent/creds/claude"), { fn: async () => claudeToken(), auth: "agent" }],
     [route("POST", "/agent/relay/:id"), { fn: async (p, body, _u, req) => relayPost(req, p, body), auth: "agent" }], // #4778
     [route("GET", "/agent/relay/:id/:rid"), { fn: async (p, _b, _u, req) => relayPoll(req, p), auth: "agent" }],
     [route("GET", "/agent/bundle"), { fn: async () => ({ bundle: true }), auth: "agent" }],
@@ -355,6 +364,62 @@ export function createRouter(cfg, { fetchFn = globalThis.fetch, now = () => Date
   return { handle, launch, claim, tick, enroll, issueCode, capacities, status, store };
 }
 
+/** tokenbaton's usage dir (#5165): router.json `usage_source`, else `$TOKENBATON_HOME`, else `~/.tokenbaton`. */
+export function usageSource(cfg, env = process.env) {
+  return cfg.usage_source ?? env.TOKENBATON_HOME ?? join(homedir(), ".tokenbaton");
+}
+
+/** One tokenbaton `live.<n>` line (`<5h %> <5h reset s> <weekly %> <weekly reset s> [updated s]`), or null; the format of bin/lean/rotator.mjs parseLive. */
+export function parseLiveUsage(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 };
+}
+
+/** Map account n -> parsed `live.<n>` for the given accounts; unreadable or malformed files are left out. */
+export function readUsage(dir, ns, readFile = (p) => readFileSync(p, "utf8")) {
+  const out = new Map();
+  for (const n of ns) { try { const u = parseLiveUsage(readFile(join(dir, `live.${n}`))); if (u) out.set(n, u); } catch { /* no usage for n */ } }
+  return out;
+}
+
+/**
+ * Pick the Claude login to hand out (#5165). Candidates have 30+ minutes of validity. A login with known usage is
+ * excluded at or above `ceilingPct` 5-hour use or 100% weekly use (a passed reset counts as 0, like the local rotator);
+ * the rest rank by 5-hour use, then validity. Logins with unknown usage follow. No usage at all: longest validity,
+ * `fallback: true`. Every candidate excluded: a typed 429 carrying the earliest reset.
+ * @returns {{status: 200, login, pct, fallback} | {status: 429, retryAfter, body} | {status: 503}}
+ */
+export function pickClaudeLogin({ logins, usage, ceilingPct = 95, now }) {
+  const valid = logins.filter((l) => l.accessToken && l.expiresAt > now + 30 * 60000);
+  if (!valid.length) return { status: 503 };
+  const used = (pct, resetMs) => (resetMs <= now ? 0 : pct);
+  const byValidity = (a, b) => b.expiresAt - a.expiresAt;
+  const known = [], unknown = [], blocked = [];
+  for (const l of valid) {
+    const u = l.n !== null && l.n !== undefined ? usage.get(l.n) : undefined;
+    if (!u) { unknown.push(l); continue; }
+    const five = used(u.fiveHourPct, u.fiveHourResetMs), week = used(u.weeklyPct, u.weeklyResetMs);
+    if (five >= ceilingPct || week >= 100) {
+      const r = [];
+      if (five >= ceilingPct) r.push(u.fiveHourResetMs);
+      if (week >= 100) r.push(u.weeklyResetMs);
+      blocked.push(Math.max(...r));
+    } else known.push({ l, pct: five });
+  }
+  if (known.length) {
+    known.sort((a, b) => a.pct - b.pct || byValidity(a.l, b.l));
+    return { status: 200, login: known[0].l, pct: known[0].pct, fallback: false };
+  }
+  if (unknown.length) {
+    unknown.sort(byValidity);
+    return { status: 200, login: unknown[0], pct: null, fallback: !blocked.length };
+  }
+  const resetMs = Math.min(...blocked), at = new Date(resetMs).toISOString();
+  return { status: 429, retryAfter: Math.max(1, Math.ceil((resetMs - now) / 1000)),
+    body: { error: "usage limit", code: "rate_limited", reason: `usage limit hit; resets at ${at}`, reset_at: at } };
+}
+
 export function startRouter(cfg, deps) {
   const router = createRouter(cfg, deps);
   const server = createServer(router.handle);

package/bin/review-staging.mjs

@@ -385,6 +385,8 @@ async function finalize(a, io) {
   // Incomplete-panel guard + 6.75 delivery
   const d = await bash(io, "review-staging-post.sh", ["delivery", ...common], env);
   relay(io, d);
+  // Exit 2 = the comments could not be listed on any attempt (forge#5166): rerun, never re-dispatch reviewers that may have posted.
+  if (d.code === 2) throw new Stop(1, ["REVIEW_RESULT: status: BLOCKED, blocker: reviewer delivery could not be verified (GitHub comment listing failed); rerun --finalize, do not re-dispatch reviewers", BLOCK_DEPLOY]);
   if (d.code !== 0) throw new Stop(1, [`REVIEW_RESULT: status: BLOCKED, blocker: reviewer delivery incomplete (exit ${d.code}); re-dispatch each missing reviewer once with the note "structured findings block required", else the panel is degraded`, BLOCK_DEPLOY]);
 
   // 6.5 verdict handling (override, posture, test-gate markers)

package/bin/runner.mjs

@@ -1352,6 +1352,27 @@ export function detectUsageLimit(stdout, output = "") {
   return hasUsageLimitResetClause(output || "");
 }
 
+// forge#5168: the claude CLI's own login/authentication failure texts. Literal
+// alternatives only (linear on untrusted input).
+const AUTH_FAILURE_RE = /Failed to authenticate|authentication_error|OAuth token (?:has )?expired|reached its time limit and cannot be renewed|Invalid API key|Please run \/login/i;
+
+/**
+ * Detects whether a failed CLI run was an authentication failure of the claude
+ * login (forge#5168): an expired or invalid login is an account condition, not
+ * a transient engine error. With an envelope on stdout, it must be
+ * `is_error: true` with a `result` naming the failure; without one, the plain
+ * combined output must. `stdout` is parsed ALONE (forge#2422); never throws.
+ *
+ * @param {string} stdout - raw stdout of the CLI run
+ * @param {string} [output] - combined stdout+stderr, for the plain-text fallback
+ * @returns {boolean}
+ */
+export function detectAuthFailure(stdout, output = "") {
+  const env = parseCliEnvelope(stdout);
+  if (env) return env.is_error === true && typeof env.result === "string" && AUTH_FAILURE_RE.test(env.result);
+  return typeof output === "string" && AUTH_FAILURE_RE.test(output);
+}
+
 /**
  * Best-effort extraction of a Claude CLI session-limit reset time from
  * captured stdout/stderr (forge#2241). The CLI's own session-limit message
@@ -1844,6 +1865,9 @@ export function runCliBackend({
       // default when the reset time itself is missing or unparseable. The
       // engine, not the runner, owns that default — no epoch is fabricated here.
       if (isUsageLimit) err.usageLimit = true;
+      // forge#5168: a failed login (never when the usage limit already matched,
+      // which keeps precedence) lets the lane defer as `backend.auth`.
+      else if (detectAuthFailure(stdout, output)) err.authFailure = true;
       if (resetAt) {
         err.resetAt = resetAt;
         // forge#2524: also attach a machine-usable epoch-ms timestamp so

package/commands/orchestrate.md

@@ -100,7 +100,8 @@ remaining maintenance once no feature is pending; otherwise the rest ends `held
   (live lanes are re-adopted, nothing is launched twice). The runner is hosted by the detached `forgedock schedd` daemon,
   which resumes every daemon-hosted batch that has no report yet when it starts, so a closed session needs no manual
   `--resume`; a batch started without the daemon still needs `forgedock orchestrate --resume <id>`. Change K of a running batch with
-  `forgedock orchestrate --set-parallel <id> K`. Issues filed while a batch runs join it with
+  `forgedock orchestrate --set-parallel <id> K`. Change its remote lane cap or placement with `forgedock orchestrate --set-max-remote <id> N` and
+  `--set-placement <id> remote|hybrid|local` (remote/hybrid only for a batch started with a remote provider; running lanes keep running). Issues filed while a batch runs join it with
   `forgedock orchestrate --add <id> N...` (or `--resume <id> N...`), under its K and DAG; never start a second batch
   for them. After a decision (a `FORGE:DECISION` posted and `needs-human` removed), a blocked issue that already ended in the batch
   (`needs-human`, `invalid`, `skipped`, `dependency-*`, `ci-pending`, `deferred`) returns to it with

package/commands/review-pr-staging.md

@@ -401,14 +401,14 @@ node "$FD_ROOT/bin/forgedock.mjs" review-staging "$PR_NUMBER" --finalize --test-
 ```
 
 The call runs these steps in order:
-1. The incomplete-panel guard and Phase 6.75 delivery verification. A launched reviewer without a trusted current-head comment that carries a findings block is a delivery failure. An empty or unreadable launched-agent list also fails, and is never evidence that nothing needed verifying.
+1. The incomplete-panel guard and Phase 6.75 delivery verification. A launched reviewer without a trusted current-head comment that carries a findings block is a delivery failure. An empty or unreadable launched-agent list also fails, and is never evidence that nothing needed verifying. The PR comments are listed once per attempt. A missing reviewer or a GitHub API error is re-listed with backoff (5 s, 15 s, 45 s) before any verdict, and each domain is reported with the attempt it was found on.
 2. The Phase 6.5 verdict handling.
 3. `scripts/review-finalize.sh`:
    - `extract`: trusted comments only, dedup, and the `commands/review-pr.md` §6B.4 provenance and concreteness gates. **CRITICAL/HIGH are never routed as pre-existing**, whatever their confidence.
    - `classify --dry-run`, then `classify` for real. This passes `--scope-files` (the 0B.1 scoped set when `SCOPE_MODE=scoped`) and `--prior-prs` (the bundle members), and posts `FORGE:NOTE_DISPOSITION`.
    - `file-prepare`.
 
-Findings come only from `FINDING:` markers, never from free text. **Exit 1 is a stop**: a `REVIEW DELIVERY FAILURE`, `RESULT: BLOCK DEPLOY` or `REVIEW_RESULT: status: BLOCKED` line names the cause. File nothing and emit no deploy approval. On a delivery failure, re-dispatch each missing reviewer once with the note "structured findings block required". A second miss is a degraded panel. Then rerun 7A.
+Findings come only from `FINDING:` markers, never from free text. **Exit 1 is a stop**: a `REVIEW DELIVERY FAILURE`, `RESULT: BLOCK DEPLOY` or `REVIEW_RESULT: status: BLOCKED` line names the cause. File nothing and emit no deploy approval. On a delivery failure, re-dispatch each missing reviewer once with the note "structured findings block required". A second miss is a degraded panel. Then rerun 7A. `REVIEW DELIVERY UNVERIFIED` means GitHub could not list the comments on the last attempt. It stops the run, but nothing is labelled or posted. Do not re-dispatch anyone: rerun 7A once GitHub answers.
 
 Exit 0 prints the following:
 - `TEST_GATE:`, `SCOPE_MODE=`.

package/docs/CONFIG.md

@@ -438,6 +438,7 @@ orchestration:
 | `max_concurrent` | integer | No | Max concurrent top-level `/work-on` dispatches. It does not bound cascade growth; under `policy: all` it raises drain and spawn throughput together. Default: 12. |
 | `breaker.errors` / `breaker.window_min` | integer | No | `forgedock orchestrate` circuit breaker (#4121): after `errors` engine-errors within `window_min` minutes the batch stops admitting lanes, lets running lanes finish, and keeps the rest pending for `--resume`. `errors: 0` turns it off. Default: 3 in 30 |
 | `max_deferrals` | integer | No | `forgedock orchestrate`: requeues of one issue after a non-host `deferred` (usage limit, merge/push transient, CLI idle, lease held, gh unavailable) before its row is final. `host.busy` and `sandbox.capacity` (sandbox pool full) deferrals are not capped. Default: 3 |
+| `transient_retries` | integer | No | `forgedock orchestrate` (#5161): backoff retries of an issue whose lane ended `engine-error` with a transport or gateway failure in its detail (curl `returned error: 5xx`, `HTTP/1.1 5xx`, `Bad Gateway`, `Service Unavailable`, `overloaded`, connection reset/refused/timeout). Delays 30s, 2m, 8m, then 15m each; dependents stay pending meanwhile. Not counted against the single engine-error relaunch; once spent, the row ends `engine-error`. Every such error still counts toward the breaker. `0` turns transient retries off. Default: 4 |
 | `blocked_label` | string | No | `forgedock orchestrate` (#4773): an open issue carrying this label is admitted to the batch but not dispatched; removing the label releases it on the next scheduler pass. A `Blocked by #N` / `Depends on #N` line in the body of a trusted author (OWNER, MEMBER, COLLABORATOR or a bot) is a DAG edge to #N, and `--add` prints the edges it created. Empty turns the label off. Default: `blocked` |
 | `auto_add_children` | string | No | `forgedock orchestrate` (#4965): which children a running batch adds by itself. `off` (no auto-adds; a decomposed lane's sub-issues stay out too), `decomposed` (a decomposed lane's sub-issues join, as before), `epic` (also the open children of every batch issue and of each `--epic N`, found by a `**Parent**: #P` line, the `parent` field or GitHub sub-issues, including children filed after the batch started) or `all`. Only children whose author is trusted (an owner, member or collaborator, or a bot, the `Blocked by` rule) are auto-added; any other is skipped with a logged row. Children labelled `needs-human` and children another live batch of the repo still holds are not added. Each pass that adds posts one batch decision and one `added` row listing the children and edges. `forgedock orchestrate --auto-children <mode>` overrides it per batch and `--resume` keeps it. Default: `decomposed` |
 | `auto_add_children_poll_s` | integer | No | Seconds between child scans for `epic`/`all` (one `gh issue list` per scan). Default: `120` |
@@ -470,6 +471,43 @@ orchestration:
 
 ---
 
+## `orchestrate.health` and `notify` (OPTIONAL)
+
+Early batch health (#5167). `forgedock orchestrate` checks each batch at T+15 and T+60 minutes after it was created (`plan.json` `created`), and once more when the batch ends. When the batch starts, it prints the schedule: `health checks: T+15 14:05Z, T+60 14:50Z, and at batch end; forgedock status --batch <id>`. The first unhealthy check raises one `BATCH UNHEALTHY <id>` alert, which lists the top causes and the exact recovery commands (`--requeue`, a relaunch, `--resume`, `--cancel`). `health.json` in the batch dir records the checkpoints already done and the alert, so a daemon restart arms only the remaining checks and a batch never alerts twice. Checks and alerts never fail, delay or change the batch.
+
+Causes: `root-failed` (a root issue, meaning one with no dependency inside the batch, ended non-merged); `terminal-share` (the share of rows ended `skipped`/`held`/`engine-error`/`needs-human` or another non-merged outcome except `invalid`/`decomposed` is at or above the threshold, with nothing merged); `stalled` (0 lanes running while issues are pending, operator-held issues excepted); `refused` (the launch was refused).
+
+```yaml
+orchestrate:
+  health:
+    root_failed: true      # any root ended non-merged is unhealthy (default true)
+    terminal_share: 0.5    # 0..1, terminal-non-merged share with 0 merged (default 0.5)
+    stalled: true          # 0 running while pending > 0 (default true)
+    issue: 123             # comment target; default: the batch's --epic issue(s); a milestone gets no comment
+    checks_min: [15, 60]   # minutes after launch (default [15, 60])
+notify:
+  command: "curl -fsS -H 'content-type: application/json' -d @- https://hooks.example/forge"
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `orchestrate.health.root_failed` | `true` | Raise `root-failed`. |
+| `orchestrate.health.terminal_share` | `0.5` | Threshold for `terminal-share`. |
+| `orchestrate.health.stalled` | `true` | Raise `stalled`. |
+| `orchestrate.health.issue` | none | Issue to comment on. When unset, the alert comments on each `--epic` issue. |
+| `orchestrate.health.checks_min` | `[15, 60]` | Timed checkpoints, in minutes after launch. |
+| `notify.command` | none | Shell command run once per alert. It gets the alert JSON (`{alert, batch, repo, text, causes, recovery}`) on stdin and `FORGEDOCK_ALERT=BATCH_UNHEALTHY`, `FORGEDOCK_ALERT_BATCH` and `FORGEDOCK_ALERT_TEXT` in its env. It is killed after 30 s. A failure only prints a `health: notify.command failed` line. |
+
+The keys are flattened one level by the parser, the same as `orchestrate.drift.*`. Health keys alone do not turn drift on.
+
+Every channel is best effort: the runner line, the GitHub comment (marker `FORGE:BATCH-HEALTH`), `notify.command`, and the `forgedock status` line. `forgedock status` lists the unhealthy batches that are unresolved (no report yet, or alerted within the last day) and the launch refusals from the last day. `forgedock status --batch <id>` shows that batch's health (healthy, or unhealthy with causes and recovery) and its pending checkpoints.
+
+A refused milestone start (#4659, `parallel milestone start refused: …`) still exits 1 with the error on stderr and creates no batch dir. It is also recorded in `<batch root>/refusals.json` (the newest 20 are kept) and sends the same alert, with the merge-the-dependency or `--force "<reason>"` relaunch.
+
+**Commands that use this section**: `forgedock orchestrate`, `forgedock status`
+
+---
+
 ## `decisions` (OPTIONAL)
 
 Decision engine (#4766, see [DECISIONS.md](DECISIONS.md)). The issue-watch stage (#4793) calls `settle` for the open `needs-human` issues a watch selects: it runs when `mode: live` (a repo setting: every watch of the repo runs the stage), or when the watch sets `sweep_needs_human: true`; `policy` and `human_only` are also read by prodwatch (`loadPolicy`). The parser has one nesting level and no arrays, so lists are comma-separated.
@@ -1185,7 +1223,7 @@ decomposition:
 
 **With `close_parent: false`** (default): unchanged. The parent stays open and is closed by C3 when the last child closes.
 
-The lean (core) path reads the same key (#4337): with `close_parent: true` it closes the parent at decomposition as `not planned`, keeps `workflow:decomposed` and lists the sub-issues in the closing comment; dependents still wait on the sub-issues, and a trusted `FORGE:DECOMPOSED:REVOKED` reopens it. With the default `false` the lean parent stays open.
+The lean (core) path reads the same key (#4337): with `close_parent: true` it closes the parent at decomposition as `completed` (#5152; scope moved to the sub-issues, not dropped), keeps `workflow:decomposed` and lists the sub-issues in the closing comment; dependents still wait on the sub-issues, and a trusted `FORGE:DECOMPOSED:REVOKED` reopens it. With the default `false` the lean parent stays open.
 
 **Limitation**: `--retry` and engine resume refuse closed issues, so a closed decomposed parent cannot be re-run. It has nothing left to run; work on its open children instead.
 

package/docs/OUTCOME-CODES.md

@@ -44,6 +44,7 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `gh.unavailable` | `run-issue --repo` could not verify the cwd repo because `gh repo view` kept failing after 3 attempts with backoff (typically a timeout under host load); the core or full run is `deferred` (exit 75, retry in 60s) before any lease, nothing posted | engine CLI | `bin/engine-cli.mjs` |
 | `gh.auth` | A `gh` call in a core run answered HTTP 401 (expired or revoked bot token) and one run of `scripts/refresh-bot-token.sh` plus a retry did not fix it; the run is `deferred` (retry in 120s), never `engine-error`. See `docs/CONFIG.md` "Bot token refresh" | lean | `bin/lean/retry.mjs` |
 | `rate_limited` | Session or usage limit outlasted the pause budget | engine | `err.usageLimit` / `err.resetAtEpochMs` |
+| `backend.auth` | The claude CLI login failed ("Failed to authenticate", expired or invalid login); the lane is `deferred` (retry in 900s) under a per-account hold like a usage limit, never `engine-error`, never relaunched or counted by the breaker (#5168) | lean | `bin/runner.mjs` `err.authFailure` |
 | `engine.error` | Engine or tool failure (missing key/SDK, CLI crash, max turns, unresolved args, runner threw every attempt) | engine | `err.code` |
 | `engine.dco_rewrite` | Core work-on (forge#4997): the DCO sign-off rewrite (`git filter-branch`) of the lane's unpushed commits failed, or the lane's uncommitted changes could not be restored after it (kept on `refs/forgedock/dco-stash`). A mechanical engine step, not a human block: the lane ends `engine-error` (never `needs-human`), which `forgedock orchestrate` relaunches like any engine-error | lean | `bin/lean/signoff.mjs` `ensureSignedOff` |
 | `engine.validate_result_lost` | Core work-on (forge#4708): a validate result recorded before a merge-time CI fix round is missing from the fix session's result file and could not be carried forward; an engine bookkeeping error, not an unimplemented requirement | lean | `bin/lean/lean.mjs` `mergeFixRound` |
@@ -70,7 +71,7 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `lane.branch_missing` | Core work-on: the lane branch (e.g. `milestone/<slug>`) does not exist on origin; fail closed | lean | `git ls-remote --heads origin` |
 | `lane.unresolved` | Core work-on: the lane could not be worked out (milestone or default branch unreadable, empty milestone slug, bad `feature_pattern`); fail closed | lean | Failed `gh` read or config |
 | `invalid` | Issue is invalid or in a divergent closed state | investigate, engine | `INVESTIGATION:INVALID` marker, or live snapshot |
-| `decomposed` | Issue was decomposed into sub-issues. In core work-on, the builder reported `block.kind: "split-required"`; the engine files the sub-issues (`**Parent**` and `**Depends on**` lines) and returns them as `subissues` for `forgedock orchestrate` to run. With `decomposition.close_parent: true` the parent is then closed `not planned` (label kept) and its dependents wait on the sub-issues | investigate, decompose, lean | `FORGE:DECOMPOSED` or the decomposition assessment; `result.json` `block.subissues` |
+| `decomposed` | Issue was decomposed into sub-issues. In core work-on, the builder reported `block.kind: "split-required"`; the engine files the sub-issues (`**Parent**` and `**Depends on**` lines) and returns them as `subissues` for `forgedock orchestrate` to run. With `decomposition.close_parent: true` the parent is then closed `completed` (label kept; #5152: its scope moved, it was not dropped) and its dependents wait on the sub-issues | investigate, decompose, lean | `FORGE:DECOMPOSED` or the decomposition assessment; `result.json` `block.subissues` |
 | `builder.blocked` | Core work-on: the builder reported an external action agents cannot take, or a product decision too critical for agents: `block.kind: "human"` with `why` one of `credentials`, `spend`, `promotion`, `customer`, `product-decision`. An upstream issue, a needed split, or prod data that monitoring access can read never count | lean | `result.json` status `blocked` + typed `block` |
 | `builder.block_untyped` | Core work-on: the builder stayed `blocked` without a valid typed reason (missing `block`, a non-human `why` such as prod data, or a dependency that is not open) after one corrective resume | lean | `result.json` status `blocked`, twice |
 | `builder.no_evidence` | Core work-on: the builder reported invalid/already-fixed without file:line evidence, so the issue was not closed | lean | `result.json` with empty `evidence` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.49.0",
+  "version": "1.51.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/pool/README.md

@@ -10,4 +10,6 @@ ForgeDock's built-in remote compute pool (imported from computeshare; AGPL-3.0-o
 
 The module boundary is the ForgeDock HTTP sandbox protocol: the router speaks it to the dispatcher and relays to agents over HTTP. Sandboxes receive only short-lived GitHub and Claude access tokens; refresh tokens stay on the router host.
 
+Claude login choice (#5165): among the router host's logins with 30+ minutes left, the router hands out the one with the lowest 5-hour use in tokenbaton's `live.<n>` (account `n` = `~/.claude-<n>`), read from router.json `usage_source` (default `$TOKENBATON_HOME`, else `~/.tokenbaton`); validity only breaks ties. An account at or above `usage_ceiling_pct` (default 95) or at 100% weekly use is skipped; when every login is, `/agent/creds/claude` answers a typed 429 (`code: rate_limited`, `reset_at` = the earliest reset, `retry-after`), which the agent passes through and `cs-cred` prints as `usage limit hit; resets at <ISO>` so the lane defers. Without readable usage it falls back to the longest validity and logs a warning. The selected account index and usage are logged, never the token.
+
 The `forgedock pool` CLI wiring is tracked separately (#4544).

package/pool/image/cs-cred

@@ -7,6 +7,13 @@ kind="${1:?kind}"; ttl=240; [ "$kind" = claude ] && ttl=600
 cache="/tmp/.cs-cred-$kind"
 if [ -s "$cache" ] && [ $(( $(date +%s) - $(stat -c %Y "$cache") )) -lt $ttl ]; then cat "$cache"; exit 0; fi
 [ -n "${CS_CRED_BASE:-}" ] || { echo "no credential relay (CS_CRED_BASE)" >&2; exit 1; }
-tok=$(curl -fsS --max-time 30 -H "authorization: Bearer ${CS_CRED_TOKEN}" "$CS_CRED_BASE/$kind" | jq -r .token)
+body=$(mktemp); trap 'rm -f "$body"' EXIT
+code=$(curl -sS --max-time 30 -o "$body" -w '%{http_code}' -H "authorization: Bearer ${CS_CRED_TOKEN}" "$CS_CRED_BASE/$kind") || code=000
+if [ "$code" = 429 ]; then
+  # #5165: every router login is at its usage ceiling; this line is what the lane's log tail defers on.
+  why=$(jq -r '.reason // empty' "$body" 2>/dev/null || true)
+  echo "${why:-usage limit hit; resets at unknown}" >&2; exit 1
+fi
+tok=""; [ "$code" = 200 ] && tok=$(jq -r .token "$body" 2>/dev/null || true)
 [ -n "$tok" ] && [ "$tok" != null ] || { echo "credential fetch failed ($kind)" >&2; exit 1; }
 umask 077; printf '%s' "$tok" > "$cache"; printf '%s' "$tok"