forgedock 1.45.0 → 1.47.0

package/bin/lean/execution.mjs

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

package/bin/lean/execution.test.mjs

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

package/bin/lean/integration.mjs

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

package/bin/lean/integration.test.mjs

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

package/bin/lean/issuewatch-decisions.mjs

@@ -0,0 +1,175 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * #4793: the north-star decision engine (#4766) as an issue-watch stage. Each round the watcher lists the open `needs-human`
+ * issues that match its selectors, reads the newest trusted `FORGE:NEEDS_HUMAN` comment of each (its comment id is the escalation
+ * id the engine is idempotent on) and the typed `terminalCode` from a trusted `FORGE:STATE`, and hands it to `settle`. Active when
+ * `decisions.mode: live`, or when the watch sets `sweep_needs_human: true`; escalations that predate the watch are a backlog and
+ * only a `sweep_needs_human` watch touches them. `--dry-run` classifies and writes nothing. Handled issues count against the
+ * watch's `max_issues`, issues sent back to a lane against `max_launches` (`claimsUsed`, shared with the watcher's own caps).
+ * Only live mode acts: a post-deploy-only escalation is folded into `postdeploy_rollup` and closed, an evidence escalation on a repo
+ * that declares `prod_watch` sources goes back to a lane with the prod monitor capability; in shadow mode each only posts.
+ * Gh, the clock, the judge, the lane launch and the rollup `fold` are injected. The judge is the only LLM call.
+ */
+import { settle, classify, tally, isVetoed, revertVeto, effectiveMode, NEEDS_HUMAN_LABEL } from "./decision-engine.mjs";
+import { codeOf } from "./context.mjs";
+import { noComments } from "./render.mjs";
+import { listAssociations } from "./gh-assoc.mjs";
+import { parseProdWatch } from "./prodwatch.mjs";
+import { resolveOwnLogins } from "./prefilter.mjs";
+
+const ROWS_MAX = 200;
+const LIST_LIMIT = "200";
+const MAX_ATTEMPTS = 3; // a judge/gh failure is retried this many rounds, then the escalation is left to a human
+const JUDGE_ROUND_MAX = 20; // judge calls per round, whether or not the watch sets max_issues
+const MS_PER_HOUR = 3600_000;
+const commentId = (c) => /#issuecomment-(\d+)/.exec(String(c?.url ?? ""))?.[1] ?? c?.id ?? null;
+const marked = (body, m) => new RegExp(`^\\s*<!--\\s*FORGE:${m}\\b`).test(String(body ?? ""));
+
+/** True when this watch runs the stage: `decisions.mode: live` (policy from loadPolicy) or `sweep_needs_human: true`. */
+export const decisionsActive = (watch, policy) => policy?.mode === "live" || watch.sweep_needs_human === true;
+
+/** What the watch has used up: `issues` (claimed or handled by the stage, for max_issues) and `launches` (claimed or sent back to a lane, for max_launches). */
+export function claimsUsed(state) {
+  const d = state.decisions;
+  return { issues: new Set([...(state.claimed ?? []), ...(d?.issues ?? [])]).size, launches: new Set([...(state.claimed ?? []), ...(d?.launched ?? [])]).size };
+}
+
+/** `{policy, hasSource}`: the repo's decisions policy and whether forge.yaml declares read-only data access (`prod_watch` sources). */
+export function decisionContext({ loadPolicy, readFile, cwd = "." }) {
+  const policy = loadPolicy({ io: { readFile }, cwd });
+  let hasSource = false;
+  try { hasSource = Object.keys(parseProdWatch(readFile(`${cwd}/forge.yaml`)).sources ?? {}).length > 0; } catch { /* no forge.yaml or no prod_watch block */ }
+  return { policy, hasSource };
+}
+
+/** The typed terminal code of the newest FORGE:STATE record (trusted comments, then the issue body, whose author the stage already vetted). */
+export function terminalCodeOf(body, comments, trusted) {
+  for (const t of [...(comments ?? []).filter(trusted).map((c) => c.body).reverse(), body]) {
+    const m = /FORGE:STATE\s*(\{[^\n]*\})/.exec(String(t ?? ""));
+    if (!m) continue;
+    try { const st = JSON.parse(m[1]); return codeOf(st.terminalCode) ?? codeOf(st.terminalReason); } catch { /* next record */ }
+  }
+  return null;
+}
+
+/** An issue's open escalation: `{id, text, at}` from its newest trusted FORGE:NEEDS_HUMAN comment, or null. */
+export function escalationOf(comments, trusted) {
+  const c = [...(comments ?? [])].reverse().find((x) => marked(x.body, "NEEDS_HUMAN") && trusted(x));
+  return c && commentId(c) ? { id: String(commentId(c)), text: noComments(c.body).replace(/^\s*## Needs human\s*/i, "").trim(), at: Date.parse(c.createdAt) || 0 } : null;
+}
+
+const dec = (state) => (state.decisions ??= { rows: [], handled: {}, attempts: {}, issues: [], launched: [], live: [], stats: { decided: 0, reversed: 0 } });
+
+/** Counts for the watcher status: decided, evidence-gathered, folded, external-kept (decision-engine `tally`). */
+export const decisionCounts = (state) => tally(state.decisions?.rows ?? []);
+
+const ghJson = async (io, args) => JSON.parse(String(await io.gh(args)));
+const poster = (io, repo) => async (_marker, body, issue) => { await io.gh(["issue", "comment", String(issue), "-R", repo, "--body", `<!-- FORGE:DECISION -->\n${body}`]); };
+const labeller = (io, repo) => async ({ issue, add = [], remove = [] }) => {
+  if (!add.length && !remove.length) return;
+  await io.gh(["issue", "edit", String(issue), "-R", repo, ...add.flatMap((l) => ["--add-label", l]), ...remove.flatMap((l) => ["--remove-label", l])]);
+};
+
+/**
+ * One round. `ctx`: `{policy, hasSource}`; `shared`: issuewatch's `{matches(issue, selectors), fold({issue, watch, repo, io, state}), labelNames, isBot, TRUSTED}`;
+ * `launch(issue)→bool` sends the issue back to a lane (the watcher's per-issue launch; false leaves it to normal selection).
+ * `io.judge(q)→answer` is the judgment call (none: every decision part escalates). Returns `{rows}`; with `dryRun` the rows are
+ * classifications and nothing is written to GitHub or `state`. Never throws on one issue: a failure is retried, then left to a human.
+ */
+export async function decisionStep({ watch, repo, io, state, ctx, shared, launch = () => false, dryRun = false }) {
+  const d = dec(state);
+  const startedAt = state.started ?? io.now();
+  if (!dryRun) state.started ??= startedAt;
+  let own = [];
+  try { own = (await resolveOwnLogins(io.gh)).logins; } catch { /* only the associations count */ }
+  const bare = (l) => String(l ?? "").trim().toLowerCase().replace(/^app\//, "").replace(/\[bot\]$/, "");
+  const trusted = (c) => shared.TRUSTED.has(c?.authorAssociation) || (bare(c?.author?.login) !== "" && own.includes(bare(c.author.login))); // never another CONTRIBUTOR
+  const round = { judged: 0 };
+  const rio = { ...io, judge: io.judge && ((q) => { if (round.judged >= JUDGE_ROUND_MAX) throw new Error("judge cap for this round reached"); round.judged++; return io.judge(q); }) };
+  const rows = [];
+  const issues = await ghJson(io, ["issue", "list", "-R", repo, "--state", "open", "--label", NEEDS_HUMAN_LABEL, "--limit", LIST_LIMIT, "--json", "number,title,body,labels,milestone,author,createdAt"]);
+  const assoc = await listAssociations(io.gh, repo);
+  const sel = { ...watch, labels: (watch.labels ?? []).filter((l) => l !== NEEDS_HUMAN_LABEL), exclude_labels: (watch.exclude_labels ?? []).filter((l) => l !== NEEDS_HUMAN_LABEL) };
+  for (const raw of issues) {
+    const i = { ...raw, authorAssociation: assoc.get(raw.number) };
+    if (!shared.TRUSTED.has(i.authorAssociation) || !shared.matches(i, sel)) continue;
+    let view; // release #5068 MAT-2: one unreadable issue is retried next round, never ends the round for the rest
+    try { view = await ghJson(io, ["issue", "view", String(i.number), "-R", repo, "--json", "comments,body,labels"]); } catch (e) { rows.push({ issue: i.number, action: "error", reason: String(e?.message ?? e).slice(0, 200) }); continue; }
+    const esc = escalationOf(view.comments, trusted);
+    if (!esc || d.handled[esc.id]) continue;
+    const backlog = esc.at < startedAt;
+    if (backlog && !watch.sweep_needs_human && !dryRun) continue;
+    const item = { issue: i.number, repo, escalationId: esc.id, text: esc.text, title: i.title, terminalCode: terminalCodeOf(view.body, view.comments, trusted), comments: (view.comments ?? []).filter(trusted) }; // release #5068 SEC-1: a forged FORGE:DECISION can neither finish nor suppress a decision
+    if (dryRun) { rows.push({ ...classify(item, ctx.policy), backlog }); continue; }
+    if (round.judged >= JUDGE_ROUND_MAX) break;
+    const used = claimsUsed(state);
+    if (watch.max_issues && used.issues >= watch.max_issues) break;
+    if (watch.max_launches && used.launches >= watch.max_launches) break;
+    const row = await handle({ item, issue: i, watch, repo, io: rio, state, ctx, shared, launch, d });
+    if (row.action === "error") { // not handled: retried next round, bounded
+      d.attempts[esc.id] = (d.attempts[esc.id] ?? 0) + 1;
+      if (d.attempts[esc.id] >= MAX_ATTEMPTS) d.handled[esc.id] = "error";
+      rows.push(row);
+      continue;
+    }
+    d.handled[esc.id] = row.action;
+    if (row.action === "skipped") continue;
+    d.rows = [...d.rows, { issue: row.issue, escalationId: esc.id, action: row.action, kept: row.kept ?? false }].slice(-ROWS_MAX);
+    if (!d.issues.includes(i.number)) d.issues.push(i.number);
+    rows.push(row);
+  }
+  if (!dryRun) await vetoes({ repo, io, ctx, d, shared });
+  return { rows };
+}
+
+async function handle({ item, issue, watch, repo, io, state, ctx, shared, launch, d }) {
+  const n = item.issue;
+  try {
+    const post = poster(io, repo), setLabels = labeller(io, repo);
+    const back = async () => { if ((await launch(issue)) && !d.launched.includes(n)) d.launched.push(n); }; // label cleared: a lane takes it again; release #5068 MAT-4: counted only when it does
+    const deps = { judge: (q) => (io.judge ? io.judge(q) : null), post, setLabels, requeue: back, records: (await io.records?.()) ?? [], stats: d.stats, emit: io.emit };
+    const row = await settle(item, ctx.policy, deps);
+    if (row.action === "error") return row;
+    if (row.action === "decided" && !row.resumed) { d.stats.decided++; if (!row.kept) d.live.push({ issue: n, escalationId: item.escalationId, at: io.now() }); }
+    const key = `Escalation: ${item.escalationId}`;
+    if (row.action !== "post-deploy-only" && row.action !== "evidence-needed") return row;
+    if (effectiveMode(ctx.policy, d.stats).mode !== "live") { // shadow: say what would happen, change nothing
+      await post(null, `## Decision (shadow)\n${key}\nWould ${row.action === "post-deploy-only" ? "fold into the release checklist and close" : "send back to a prod-monitor lane"}; nothing changed.`, n);
+      return { ...row, action: "shadow" };
+    }
+    if (row.action === "post-deploy-only") {
+      if (!watch.postdeploy_rollup) return { ...row, action: "post-deploy-kept", reason: "no postdeploy_rollup to fold into" };
+      await shared.fold({ issue: { number: n, title: item.title ?? `#${n}` }, watch, repo, io, state });
+      await post(null, `## Post-deploy only\n${key}\nEvery remaining item is post-deploy: folded into #${watch.postdeploy_rollup} (the release checklist) and closed.`, n);
+      await setLabels({ issue: n, remove: [NEEDS_HUMAN_LABEL] });
+      await io.gh(["issue", "close", String(n), "-R", repo, "--reason", "completed"]);
+      return { ...row, folded: true };
+    }
+    if (!ctx.hasSource) return { ...row, action: "evidence-kept", reason: "no read-only data access declared in forge.yaml (prod_watch.sources)" };
+    await post(null, `## Evidence needed\n${key}\nThe block is missing read-only production data and forge.yaml declares a read-only source (prod_watch.sources): back to a lane that has the prod monitor capability (placement prod_monitor), needs-human cleared.`, n);
+    await setLabels({ issue: n, remove: [NEEDS_HUMAN_LABEL] });
+    await back();
+    return row;
+  } catch (e) {
+    return { issue: n, escalationId: item.escalationId, action: "error", reason: String(e?.message ?? e).slice(0, 200) };
+  }
+}
+
+/** A live decision vetoed inside its window (label or reply) is reverted once; a window that ended retires the record. */
+async function vetoes({ repo, io, ctx, d, shared }) {
+  const keep = [];
+  for (const r of d.live) {
+    try {
+      const v = await ghJson(io, ["issue", "view", String(r.issue), "-R", repo, "--json", "comments,labels"]);
+      if (isVetoed({ labels: shared.labelNames(v), comments: v.comments, decidedAt: r.at, vetoHours: ctx.policy.vetoHours, now: io.now() })) {
+        await revertVeto({ issue: r.issue, escalationId: r.escalationId }, { setLabels: labeller(io, repo), post: poster(io, repo), emit: io.emit });
+        d.stats.reversed++;
+      } else if (io.now() < r.at + ctx.policy.vetoHours * MS_PER_HOUR) keep.push(r);
+    } catch { keep.push(r); }
+  }
+  d.live = keep;
+}
+
+/** Dry-run text: one line per escalation with its classification. */
+export const formatDecisionDryRun = (rows) => rows.length ? rows.map((r) => `#${r.issue} ${r.kind}${r.backlog ? " (backlog)" : ""}: ${r.decisions} decision part(s)${r.external.length ? `, external ${r.external.join(",")}` : ""}`).join("\n") : "no needs-human escalations to classify";