forgedock 1.46.0 → 1.48.0

package/bin/lean/execution.mjs

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

package/bin/lean/execution.test.mjs

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

package/bin/lean/integration.mjs

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

package/bin/lean/integration.test.mjs

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

package/bin/lean/issuewatch.mjs

@@ -25,7 +25,7 @@ import { noComments } from "./render.mjs";
 import { listAssociations } from "./gh-assoc.mjs";
 import { verifyMerge, verifyComment } from "./issuewatch-verify.mjs";
 
-const WATCH_KEYS = ["milestone", "labels", "exclude_labels", "search", "title_regex", "since", "version", "lane", "max_issues", "max_inflight", "until", "mode", "parallel", "include_followups", "postdeploy_rollup", "threshold", "immediate", "max_release_issues", "theme_map", "tracker", "sweep_needs_human", "max_launches"];
+const WATCH_KEYS = ["milestone", "labels", "exclude_labels", "search", "title_regex", "since", "version", "lane", "max_issues", "max_inflight", "until", "mode", "parallel", "include_followups", "postdeploy_rollup", "threshold", "immediate", "max_release_issues", "theme_map", "tracker", "sweep_needs_human", "max_launches", "trust_app", "trust_app_labels"];
 export const TRUSTED = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
 const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const RETRIES = 3;
@@ -79,8 +79,11 @@ export function validateWatch(name, cfg = {}) {
   const w = { name, milestone: cfg.milestone || null, labels: list(cfg.labels), exclude_labels: list(cfg.exclude_labels), search: cfg.search || null, title_regex: cfg.title_regex || null,
     since: cfg.since || null, version: cfg.version ? String(cfg.version) : null, lane: cfg.lane || null, max_issues: int("max_issues", null), max_inflight: int("max_inflight", 4),
     until: cfg.until || null, mode: cfg.mode || "per-issue", parallel: int("parallel", 4), include_followups: cfg.include_followups || "none", postdeploy_rollup: cfg.postdeploy_rollup ? Number(String(cfg.postdeploy_rollup).replace("#", "")) : null,
-    max_launches: int("max_launches", null), sweep_needs_human: cfg.sweep_needs_human === true || String(cfg.sweep_needs_human).toLowerCase() === "true" };
+    max_launches: int("max_launches", null), sweep_needs_human: cfg.sweep_needs_human === true || String(cfg.sweep_needs_human).toLowerCase() === "true",
+    trust_app: cfg.trust_app === true || String(cfg.trust_app).toLowerCase() === "true", trust_app_labels: list(cfg.trust_app_labels) };
   if (cfg.sweep_needs_human !== undefined && !/^(true|false)$/i.test(String(cfg.sweep_needs_human))) throw new Error(`watch ${name}: sweep_needs_human must be true or false`);
+  if (cfg.trust_app !== undefined && !/^(true|false)$/i.test(String(cfg.trust_app))) throw new Error(`watch ${name}: trust_app must be true or false`);
+  if (w.trust_app_labels.length && !w.trust_app) throw new Error(`watch ${name}: trust_app_labels needs trust_app: true`);
   if (!["per-issue", "batch", "release"].includes(w.mode)) throw new Error(`watch ${name}: mode must be per-issue, batch or release`);
   if (w.mode === "release") validateRelease(name, cfg, w, int);
   else for (const k of ["threshold", "immediate", "max_release_issues", "theme_map", "tracker"]) if (cfg[k] !== undefined) throw new Error(`watch ${name}: ${k} needs mode: release`);
@@ -123,37 +126,64 @@ export function issueVersion(issue) {
   return null;
 }
 
-/** AND of every set selector. `search` is applied by gh, not here. */
-export function matchesSelectors(issue, sel) {
+/** The first selector `issue` fails, as a reason (`missing label x`, `excluded label x`, ...), or null when all match. `search` is applied by gh, not here. */
+export function selectorMiss(issue, sel) {
   const names = labelNames(issue);
-  if (sel.milestone === "none" ? issue.milestone : sel.milestone && milestoneSlug(issue.milestone?.title) !== milestoneSlug(sel.milestone)) return false;
-  if ((sel.labels ?? []).some((l) => !names.includes(l))) return false;
-  if ((sel.exclude_labels ?? []).some((l) => names.includes(l))) return false;
-  if (sel.title_regex && !new RegExp(sel.title_regex).test(issue.title ?? "")) return false;
-  if (sel.since && !(Date.parse(issue.createdAt) >= Date.parse(sel.since))) return false;
-  if (sel.version && issueVersion(issue) !== sel.version) return false;
-  return true;
+  if (sel.milestone === "none" ? issue.milestone : sel.milestone && milestoneSlug(issue.milestone?.title) !== milestoneSlug(sel.milestone)) return "milestone";
+  const missing = (sel.labels ?? []).find((l) => !names.includes(l));
+  if (missing !== undefined) return `missing label ${missing}`;
+  const excluded = (sel.exclude_labels ?? []).find((l) => names.includes(l));
+  if (excluded !== undefined) return `excluded label ${excluded}`;
+  if (sel.title_regex && !new RegExp(sel.title_regex).test(issue.title ?? "")) return "title_regex";
+  if (sel.since && !(Date.parse(issue.createdAt) >= Date.parse(sel.since))) return "since";
+  if (sel.version && issueVersion(issue) !== sel.version) return "version";
+  return null;
 }
 
+/** AND of every set selector. `search` is applied by gh, not here. */
+export const matchesSelectors = (issue, sel) => !selectorMiss(issue, sel);
+
 const CHECK_RE = /^\s*[-*]\s+\[ \]\s+(.*)$/;
 /** True when the body has an unchecked `— defer` checklist item. */
 export const hasUnresolvedDefer = (body) => noComments(body).split("\n").some((l) => { const t = CHECK_RE.exec(l)?.[1]; return t != null && /\s[—-]+\s*defer\b/.test(t); });
 
 // Bot authorship comes from the author only, never the body: a `FORGE:DEFERRED` marker in an outsider's issue is not
 // the App. `gh` reports the ForgeDock App as a bare login with no `[bot]` suffix (#4467), so it is matched by slug.
-export const isBot = (i) => { const l = String(i.author?.login ?? ""); return /\[bot\]$|^app\//i.test(l) || i.author?.is_bot === true || l.toLowerCase().replace(/^app\//, "").replace(/\[bot\]$/, "") === APP_SLUG; };
+const bareLogin = (i) => String(i.author?.login ?? "").trim().toLowerCase().replace(/^app\//, "").replace(/\[bot\]$/, "");
+export const isBot = (i) => { const l = String(i.author?.login ?? ""); return /\[bot\]$|^app\//i.test(l) || i.author?.is_bot === true || bareLogin(i) === APP_SLUG; };
+/** #5088: the issue's author is this repo's ForgeDock App (`app/<slug>`, `<slug>[bot]` or the bare slug); never another bot. */
+// Release review of #5123 (AUTH-1): the slug alone is a username anyone could register. Require a bot signal too: the
+// REST/gh forms `<slug>[bot]` / `app/<slug>`, or `is_bot: true` (gh --json author) for the bare GraphQL login.
+export const isOwnApp = (i) => {
+  if (bareLogin(i) !== APP_SLUG) return false;
+  const l = String(i.author?.login ?? "").trim();
+  return /\[bot\]$|^app\//i.test(l) || i.author?.is_bot === true;
+};
 const isFollowup = (i) => /^follow-up\b/i.test(i.title ?? "");
 
-/** `claim` (a lane/batch takes it), `fold` (post-deploy-only follow-up for the rollup), or null (not for this watch). */
-export function classifyIssue(issue, watch) {
+/** {kind, reason}: `kind` as classifyIssue returns it; `reason` says why (shown by the per-issue/batch `--dry-run`). */
+function classifyWhy(issue, watch) {
+  const login = issue.author?.login ?? "unknown";
   if (isBot(issue)) {
-    if (!isFollowup(issue) || watch.include_followups !== "defer-only") return null;
-    if (postDeployOnly(issue.body)) return watch.postdeploy_rollup ? "fold" : null;
-    return hasUnresolvedDefer(issue.body) ? "claim" : null;
+    if (isFollowup(issue)) { // trust_app never overrides the follow-up rules: a post-deploy-only follow-up folds, never claims (#5088 K3)
+      if (watch.include_followups !== "defer-only") return { kind: null, reason: `bot follow-up by ${login} (include_followups: none)` };
+      if (postDeployOnly(issue.body)) return watch.postdeploy_rollup ? { kind: "fold", reason: "post-deploy-only follow-up" } : { kind: null, reason: "post-deploy-only follow-up (no postdeploy_rollup)" };
+      return hasUnresolvedDefer(issue.body) ? { kind: "claim", reason: "defer follow-up" } : { kind: null, reason: "bot follow-up without an unchecked defer item" };
+    }
+    if (!watch.trust_app || !isOwnApp(issue)) return { kind: null, reason: `bot author ${login}` };
+    const want = watch.trust_app_labels ?? [];
+    if (want.length && !labelNames(issue).some((l) => want.includes(l))) return { kind: null, reason: `bot author ${login} (trust_app_labels not matched)` };
+    return { kind: "claim", reason: "ForgeDock App author (trust_app)" };
   }
-  return TRUSTED.has(issue.authorAssociation) ? "claim" : null;
+  return TRUSTED.has(issue.authorAssociation) ? { kind: "claim", reason: `trusted author (${issue.authorAssociation})` } : { kind: null, reason: `untrusted author ${login} (${issue.authorAssociation ?? "unknown"})` };
 }
 
+/**
+ * `claim` (a lane/batch takes it), `fold` (post-deploy-only follow-up for the rollup), or null (not for this watch).
+ * #5088: with `trust_app: true` an issue the repo's own ForgeDock App authored is claimed (narrowed by `trust_app_labels`).
+ */
+export const classifyIssue = (issue, watch) => classifyWhy(issue, watch).kind;
+
 /** `milestone/<slug>` (forge.yaml feature pattern) for a milestone issue, else staging; a pinned `lane:` wins but is never a default branch. Throws on a default-branch lane. */
 export function laneFor(issue, watch, { branches = {}, defaults = [] } = {}) {
   const staging = branches.staging || DEFAULT_STAGING_BRANCH;
@@ -281,21 +311,11 @@ export async function tick({ watch, repo, io, state, dir, branches = {}, default
   if (capped && state.phase === "running") state.phase = "draining";
   if (state.phase === "draining") { if (!state.inflight.length && !Object.keys(state.verifyFrom ?? {}).length) state.phase = "done"; return state; } // a merge mid-verification holds the drain
 
-  const room = Math.min(watch.max_inflight - state.inflight.length, watch.max_issues ? watch.max_issues - used.issues : Infinity, watch.max_launches ? watch.max_launches - used.launches : Infinity);
-  const args = ["issue", "list", "-R", repo, "--state", "open", "--limit", "200", "--json", "number,title,body,labels,milestone,author,createdAt"];
-  if (watch.search) args.push("--search", watch.search);
-  const candidates = [];
-  const assoc = await listAssociations(io.gh, repo); // #4859: not a `gh issue list` field
-  for (const raw of await ghJson(args)) {
-    const i = { ...raw, authorAssociation: assoc.get(raw.number) };
-    if (!matchesSelectors(i, watch)) continue;
-    const kind = classifyIssue(i, watch);
-    if (kind === "fold") { await fold({ issue: i, watch, repo, io, state }); continue; }
-    if (kind === "claim" && !state.claimed.includes(i.number)) candidates.push(i);
-  }
-  const ordered = watch.mode === "batch" ? dagOrder(candidates) : candidates;
+  const room = roomFor(watch, state);
+  const plan = await planClaims({ watch, repo, io, state, branches, defaults, room });
+  for (const i of plan.folds) await fold({ issue: i, watch, repo, io, state });
   const taken = [];
-  for (const i of ordered) {
+  for (const i of plan.candidates) {
     if (taken.length >= room) break;
     const lane = laneFor(i, watch, { branches, defaults });
     if (!claimIssue(repoDir(repo, io.env), i.number, watch.name)) continue;
@@ -308,6 +328,50 @@ export async function tick({ watch, repo, io, state, dir, branches = {}, default
   return state;
 }
 
+const roomFor = (watch, state) => { const used = claimsUsed(state); return Math.min(watch.max_inflight - state.inflight.length, watch.max_issues ? watch.max_issues - used.issues : Infinity, watch.max_launches ? watch.max_launches - used.launches : Infinity); };
+
+/**
+ * #5088: what one pass would take, without writing anything. `candidates` are the issues `tick` tries to claim (in order);
+ * `claim` [{number, lane, reason}] and `skip` [{number, reason}] are the read-only forecast (registry read, never written;
+ * `room` caps the claims), `fold` the post-deploy-only follow-up numbers (`folds` the issues).
+ */
+export async function planClaims({ watch, repo, io, state, branches = {}, defaults = [], room = Infinity }) {
+  const args = ["issue", "list", "-R", repo, "--state", "open", "--limit", "200", "--json", "number,title,body,labels,milestone,author,createdAt"];
+  if (watch.search) args.push("--search", watch.search);
+  const found = [], folds = [], skip = [], why = new Map();
+  const assoc = await listAssociations(io.gh, repo); // #4859: not a `gh issue list` field
+  for (const raw of JSON.parse(String(await io.gh(args)))) {
+    const i = { ...raw, authorAssociation: assoc.get(raw.number) };
+    const miss = selectorMiss(i, watch);
+    if (miss) { skip.push({ number: i.number, reason: miss }); continue; }
+    const c = classifyWhy(i, watch);
+    if (c.kind === "fold") { folds.push(i); continue; }
+    if (c.kind !== "claim") { skip.push({ number: i.number, reason: c.reason }); continue; }
+    if (state.claimed.includes(i.number)) { skip.push({ number: i.number, reason: "already claimed by this watch" }); continue; }
+    found.push(i); why.set(i.number, c.reason);
+  }
+  const candidates = watch.mode === "batch" ? dagOrder(found) : found;
+  const registry = readJson(join(repoDir(repo, io.env), "claims.json")) ?? {};
+  const claim = [];
+  for (const i of candidates) {
+    const owner = registry[i.number];
+    if (owner && owner !== watch.name) { skip.push({ number: i.number, reason: `already claimed by watch ${owner}` }); continue; }
+    let lane;
+    try { lane = laneFor(i, watch, { branches, defaults }); } catch (e) { skip.push({ number: i.number, reason: String(e?.message ?? e) }); continue; }
+    if (claim.length >= room) { skip.push({ number: i.number, reason: `over capacity (room ${Math.max(0, room)})` }); continue; }
+    claim.push({ number: i.number, lane, reason: why.get(i.number) });
+  }
+  return { candidates, claim, fold: folds.map((i) => i.number), folds, skip };
+}
+
+/** The per-issue/batch `--dry-run` lines of a planClaims result. */
+export function formatClaimPlan(plan) {
+  const out = plan.claim.length ? plan.claim.map((c) => `would claim #${c.number} -> ${c.lane}: ${c.reason}`) : ["would claim: none"];
+  for (const n of plan.fold) out.push(`would fold #${n}`);
+  for (const s of plan.skip) out.push(`skip #${s.number}: ${s.reason}`);
+  return out.join("\n");
+}
+
 /** True when the registry leaves issue `n` to watch `name`: unclaimed, or already this watch's own claim (crash-safe re-claim, #4825). */
 export const unclaimedOrOwn = (registry, n, name) => !registry?.[n] || registry[n] === name;
 
@@ -402,7 +466,7 @@ export async function runWatch({ watch, repo, io, dir, branches, defaults, once
 const judgePrompt = ({ decision, options, policy, policyPath, precedent }) => `You settle one decision for a repository from its own policy file (${policyPath ?? "none"}) and prior decisions. Reply with only a JSON object {"choice","clause","rejected","reversibility":"reversible|one-way","confidence":"high|medium|low","anchors":[]}. "clause" quotes the policy clause or precedent that supports the choice; leave it empty when none applies.\n\nPolicy:\n${policy}\n\nPrior decisions:\n${JSON.stringify((precedent ?? []).slice(0, 20))}\n\nDecision needed:\n${decision}\n${(options ?? []).length ? `Options: ${options.join(" | ")}\n` : ""}`;
 const CLI = join(dirname(fileURLToPath(import.meta.url)), "..", "forgedock.mjs");
 function realIo(repo, env = process.env) {
-  const gh = (args) => execFileSync("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  const gh = ghRunner(execFileSync, (l) => console.error(l));
   const root = batchRoot(env);
   return { env, gh, now: () => Date.now(), sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
     classify: (issues, themes) => { // the one LLM judgment of release mode: issues no theme_map rule classifies
@@ -433,9 +497,37 @@ function realIo(repo, env = process.env) {
     } };
 }
 
+/** #5088: what a failed gh call does to the watch pass, from its argv (the callers that swallow it degrade; the rest fail). */
+export function ghFailureEffect(args) {
+  const a = (args ?? []).map(String), s = a.join(" ");
+  if (a[0] === "api" && /(^| )repos\/[^ ]+\/issues\?state=open/.test(s)) return "pass degraded: author associations unknown, every author untrusted (nothing claimed or settled this pass)";
+  if (a[0] === "api" && (a[1] === "user" || a[1] === "app")) return "no effect: the App slug stands in for the engine's own login";
+  if (/\/protection\/required_status_checks|\/rules\/branches\//.test(s)) return "verification degraded: required checks unknown, a merge is verified without them";
+  if (/\/check-runs|\/commits\/[^ /]+\/status/.test(s)) return "verification degraded: check states unread";
+  if (/\/compare\//.test(s)) return "verification pending: merge placement unknown";
+  return "the error is raised to its caller (that step fails)";
+}
+
+/**
+ * #5088: `gh(args)→stdout` over `exec` (execFileSync's signature) with gh's stderr captured instead of leaked. A failure
+ * throws an Error naming the call (`.status`, `.stderr` kept); an HTTP 401/403 first `warn`s one line with the call and
+ * its effect on the pass (ghFailureEffect).
+ */
+export function ghRunner(exec, warn = () => {}) {
+  return (args) => {
+    try { return exec("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }); } catch (e) {
+      const call = args.slice(0, 3).join(" "), stderr = String(e?.stderr ?? "");
+      const first = stderr.split("\n").map((l) => l.trim()).find(Boolean) ?? String(e?.message ?? e).split("\n")[0];
+      const code = /HTTP (40[13])\b/.exec(stderr)?.[1];
+      if (code) warn(`issue-watch: gh ${call} -> HTTP ${code}: ${first}; effect: ${ghFailureEffect(args)}`);
+      throw Object.assign(new Error(`gh ${call} failed: ${first}`), { status: e?.status, stderr });
+    }
+  };
+}
+
 const flag = (argv, f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : null; };
 
-/** `forgedock issue-watch run [--name w] [--repo o/r] [--once] [--interval s] | status [--name w] [--repo o/r]`; `--dry-run` (mode release) prints the would-cut set and writes nothing. */
+/** `forgedock issue-watch run [--name w] [--repo o/r] [--once] [--interval s] | status [--name w] [--repo o/r]`; `--dry-run` writes nothing: mode release prints the would-cut set, per-issue/batch the would-claim/fold/skip plan (#5088) and the needs-human classification. */
 export async function issueWatchFromCli(argv, deps = {}) {
   const [op] = argv;
   const usage = "usage: forgedock issue-watch run [--name <w>] [--repo owner/repo] [--once] [--interval <s>] [--dry-run] | status [--name <w>] [--repo owner/repo]";
@@ -455,10 +547,15 @@ export async function issueWatchFromCli(argv, deps = {}) {
     return { ok: true };
   }
   const ctx = decisionContext({ loadPolicy, readFile, cwd }), shared = { matches: matchesSelectors, fold, labelNames, isBot, TRUSTED };
-  if (argv.includes("--dry-run") && watch.mode !== "release") { // #4793: classification of the needs-human escalations, nothing written
-    const { rows } = await decisionStep({ watch, repo, io, state: readJson(join(dir, "status.json")) ?? fresh(watch, repo), ctx, shared, dryRun: true });
+  if (argv.includes("--dry-run") && watch.mode !== "release") { // #5088 would-claim/skip with reasons, then #4793 the needs-human classification; nothing written
+    const real = deps.io ?? realIo(repo, env), branches = readBranches(cwd);
+    const defaults = await defaultBranches({ repo, io: { gh: async (a) => real.gh(a) }, branches });
+    const state = readJson(join(dir, "status.json")) ?? fresh(watch, repo);
+    const { claim, fold: folded, skip } = await planClaims({ watch, repo, io: real, state, branches, defaults, room: roomFor(watch, state) });
+    print(formatClaimPlan({ claim, fold: folded, skip }));
+    const { rows } = await decisionStep({ watch, repo, io: real, state, ctx, shared, dryRun: true });
     print(formatDecisionDryRun(rows));
-    return { ok: true, dryRun: { rows } };
+    return { ok: true, dryRun: { rows, claim, fold: folded, skip } };
   }
   if (argv.includes("--dry-run")) {
     const real = deps.io ?? realIo(repo, env), branches = readBranches(cwd);