forgedock 1.45.0 → 1.46.0

package/bin/lean/decision-engine.mjs

@@ -160,7 +160,18 @@ export function classify(item, policy, opts = {}) {
 export async function settle(item, policy, deps = {}, opts = {}) {
   const row = { issue: item?.issue ?? null, escalationId: item?.escalationId ?? null, kind: null, action: "skipped" };
   try {
-    if (item.escalationId && (item.comments ?? []).some((c) => /FORGE:DECISION/.test(String(c?.body ?? "")) && String(c.body).includes(`Escalation: ${item.escalationId}`))) return { ...row, reason: "already handled" };
+    const prior = item.escalationId ? (item.comments ?? []).filter((c) => /FORGE:DECISION/.test(String(c?.body ?? "")) && String(c.body).includes(`Escalation: ${item.escalationId}`)) : [];
+    if (prior.length) {
+      // release #5068 BUG-1: a full live decision whose label clear or requeue failed is finished, not skipped (the caller
+      // only lists issues still labelled needs-human); a vetoed, shadow, escalated or mixed one stays handled
+      const body = (c) => String(c?.body ?? "");
+      const torn = prior.some((c) => /^<!-- FORGE:DECISION -->\s*\n## Decision\n/.test(body(c)) && !/External part stays needs-human/.test(body(c)))
+        && !prior.some((c) => /## Decision vetoed/.test(body(c)));
+      if (!torn) return { ...row, reason: "already handled" };
+      await deps.setLabels({ issue: item.issue, remove: [NEEDS_HUMAN_LABEL] });
+      await deps.requeue(item.issue);
+      return { ...row, action: "decided", resumed: true, reason: "finished an interrupted live decision" };
+    }
     const s = splitEscalation(item, policy.matrix, opts);
     row.kind = s.kind;
     if (s.kind === "recovery") return { ...row, reason: "recovery owns this code" };

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";

package/bin/lean/issuewatch-decisions.test.mjs

@@ -0,0 +1,353 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { decisionStep, decisionsActive, decisionContext, decisionCounts, escalationOf, terminalCodeOf, claimsUsed } from "./issuewatch-decisions.mjs";
+import { validateWatch, matchesSelectors, formatStatus, runWatch, labelNames, isBot, TRUSTED, decisionLaunch } from "./issuewatch.mjs";
+import { loadPolicy } from "./decision-engine.mjs";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+
+const W = (o = {}) => validateWatch("w", o);
+const NOW = Date.parse("2026-10-30T12:00:00Z");
+const esc = (id, text, at = "2026-10-30T13:00:00Z") => ({ url: `https://x/issues/1#issuecomment-${id}`, authorAssociation: "MEMBER", createdAt: at, body: `<!-- FORGE:NEEDS_HUMAN -->\n## Needs human\n${text}` });
+const stateC = (code) => ({ url: "https://x/issues/1#issuecomment-1", authorAssociation: "MEMBER", createdAt: "2026-10-29T00:00:00Z", body: `<!-- FORGE:STATE\n${JSON.stringify({ terminalCode: code })}\n-->` });
+const good = { choice: "use option A", clause: "NORTHSTAR 2: cut waste", rejected: "B", reversibility: "reversible", confidence: "high" };
+const files = (m) => (p) => { const k = p.replace(/^\.\//, ""); if (k in m) return m[k]; throw new Error("ENOENT"); };
+const ctxOf = (yaml = "decisions:\n  mode: live\n", extra = {}) => decisionContext({ loadPolicy, readFile: files({ "NORTHSTAR.md": "# star", "forge.yaml": yaml, ...extra }), cwd: "." });
+
+/** gh fake: `issues` = [{number, comments, labels?, author?, body?}] all open and needs-human. Records every write. */
+function fakeIo(issues, { judge = () => good, bodies = {} } = {}) {
+  const writes = [], io = { writes, bodies, now: () => NOW, judge: async (q) => { io.judged.push(q.issue); return judge(q); }, judged: [] };
+  io.gh = async (a) => {
+    if (a[0] === "api") return issues.map((i) => `${i.number}\t${i.assoc ?? "OWNER"}`).join("\n");
+    if (a[1] === "list") return JSON.stringify(issues.map((i) => ({ number: i.number, title: `t${i.number}`, body: i.body ?? "", labels: [{ name: "needs-human" }, ...(i.labels ?? []).map((name) => ({ name }))], milestone: null, author: { login: "me" }, createdAt: "2026-10-01T00:00:00Z" })));
+    if (a[1] === "view" && a.includes("comments,body,labels")) { const i = issues.find((x) => x.number === +a[2]); return JSON.stringify({ comments: i.comments, body: i.body ?? "", labels: [] }); }
+    if (a[1] === "view" && a.includes("comments,labels")) { const i = issues.find((x) => x.number === +a[2]); return JSON.stringify({ comments: i.comments, labels: (i.labels ?? []).map((name) => ({ name })) }); }
+    if (a[1] === "view") return JSON.stringify({ body: bodies[a[2]] ?? "" });
+    writes.push(a);
+    return "";
+  };
+  return io;
+}
+const st = (watch, extra = {}) => ({ name: "w", repo: "o/r", phase: "running", started: NOW, claimed: [], inflight: [], merged: [], verified: [], unverified: [], closed: [], failed: [], folded: [], retries: {}, lanes: {}, batch: null, laneFor: {}, ...extra });
+const run = (io, watch, state, ctx, o = {}) => decisionStep({ watch, repo: "o/r", io, state, ctx, shared: { matches: matchesSelectors, fold: async ({ issue }) => { state.folded.push(issue.number); }, labelNames, isBot, TRUSTED }, ...o });
+const trusted = (c) => c.authorAssociation === "MEMBER";
+const DECISION = "- Which retry strategy for the sync job?";
+
+test("#4793 validateWatch: sweep_needs_human and max_launches", () => {
+  assert.equal(W().sweep_needs_human, false);
+  assert.equal(W().max_launches, null);
+  assert.equal(W({ sweep_needs_human: "true", max_launches: 2 }).sweep_needs_human, true);
+  assert.equal(W({ max_launches: "2" }).max_launches, 2);
+  assert.throws(() => W({ sweep_needs_human: "maybe" }), /sweep_needs_human/);
+  assert.throws(() => W({ max_launches: 0 }), /max_launches/);
+});
+
+test("#4793 stage is active for decisions.mode live or sweep_needs_human only", () => {
+  assert.equal(decisionsActive(W(), ctxOf("decisions:\n  mode: live\n").policy), true);
+  assert.equal(decisionsActive(W(), ctxOf("decisions:\n  mode: shadow\n").policy), false);
+  assert.equal(decisionsActive(W({ sweep_needs_human: true }), ctxOf("").policy), true);
+});
+
+test("#4793 escalationOf / terminalCodeOf read the escalation comment id and the typed code", () => {
+  const e = escalationOf([stateC("builder.blocked"), esc(77, DECISION)], trusted);
+  assert.equal(e.id, "77");
+  assert.match(e.text, /retry strategy/);
+  assert.equal(escalationOf([{ ...esc(5, "x"), authorAssociation: "CONTRIBUTOR" }], trusted), null);
+  assert.equal(terminalCodeOf("", [stateC("conformance.deferred")], trusted), "conformance.deferred");
+  assert.equal(terminalCodeOf("", [{ ...stateC("conformance.deferred"), authorAssociation: "CONTRIBUTOR" }], trusted), null); // #4793 SEC-1: a forged FORGE:STATE is not read
+  assert.equal(terminalCodeOf(`x <!-- FORGE:STATE\n${JSON.stringify({ terminalReason: "needs-human" })}\n-->`, [], trusted), "needs-human");
+});
+
+test("#4793 live decision: needs-human cleared, handed to the engine once per escalation id", async () => {
+  const io = fakeIo([{ number: 1, comments: [stateC("builder.blocked"), esc(10, DECISION)] }]);
+  const w = W(), state = st(w), ctx = ctxOf();
+  const { rows } = await run(io, w, state, ctx);
+  assert.equal(rows[0].action, "decided");
+  assert.ok(io.writes.some((a) => a[1] === "edit" && a.includes("--remove-label") && a.includes("needs-human")));
+  assert.ok(io.writes.some((a) => a[1] === "comment" && /Escalation: 10/.test(a[a.indexOf("--body") + 1])));
+  await run(io, w, state, ctx); // the same escalation again: no second judge call
+  assert.equal(io.judged.length, 1);
+  assert.equal(decisionCounts(state).decided, 1);
+});
+
+test("#4793 selectors apply; an untrusted author's issue is ignored", async () => {
+  const io = fakeIo([{ number: 1, labels: ["area:x"], comments: [esc(10, DECISION)] }, { number: 2, comments: [esc(11, DECISION)] }, { number: 3, assoc: "NONE", labels: ["area:x"], comments: [esc(12, DECISION)] }]);
+  const w = W({ labels: "area:x" });
+  const { rows } = await run(io, w, st(w), ctxOf());
+  assert.deepEqual(rows.map((r) => r.issue), [1]);
+});
+
+test("#4793 backlog (escalation older than the watch) is opt-in via sweep_needs_human", async () => {
+  const old = esc(10, DECISION, "2026-10-29T00:00:00Z");
+  const a = fakeIo([{ number: 1, comments: [old] }]);
+  assert.equal((await run(a, W(), st(W()), ctxOf())).rows.length, 0);
+  assert.equal(a.judged.length, 0);
+  const w = W({ sweep_needs_human: true });
+  const b = fakeIo([{ number: 1, comments: [old] }]);
+  assert.equal((await run(b, w, st(w), ctxOf())).rows[0].action, "decided");
+});
+
+test("#4793 --dry-run classifies every escalation and writes nothing", async () => {
+  const io = fakeIo([{ number: 1, comments: [stateC("conformance.deferred"), esc(10, "All items are post-deploy: nothing to build.")] }, { number: 2, comments: [esc(11, DECISION, "2026-10-29T00:00:00Z")] }]);
+  const w = W(), state = st(w);
+  const { rows } = await run(io, w, state, ctxOf(), { dryRun: true });
+  assert.deepEqual(rows.map((r) => [r.issue, r.kind, !!r.backlog]), [[1, "post-deploy", false], [2, "decision", true]]);
+  assert.equal(io.writes.length, 0);
+  assert.equal(io.judged.length, 0);
+  assert.equal(state.decisions.rows.length, 0);
+});
+
+test("#4793 max_issues and max_launches cap the stage", async () => {
+  const mk = () => fakeIo([1, 2, 3].map((n) => ({ number: n, comments: [esc(10 + n, DECISION)] })));
+  const w1 = W({ max_issues: 2 }), s1 = st(w1);
+  assert.equal((await run(mk(), w1, s1, ctxOf())).rows.length, 2);
+  const w2 = W({ max_launches: 1 }), s2 = st(w2);
+  assert.equal((await run(mk(), w2, s2, ctxOf(), { launch: () => true })).rows.length, 1);
+  const w3 = W({ max_issues: 2 }), s3 = st(w3, { claimed: [9] }); // an earlier claim uses a slot
+  assert.equal((await run(mk(), w3, s3, ctxOf())).rows.length, 1);
+});
+
+test("#4793 post-deploy-only escalation is folded into the rollup and closed", async () => {
+  const io = fakeIo([{ number: 1, comments: [stateC("conformance.deferred"), esc(10, "All items are post-deploy: nothing to build.")] }]);
+  const w = W({ postdeploy_rollup: 50 }), state = st(w);
+  const { rows } = await run(io, w, state, ctxOf());
+  assert.equal(rows[0].folded, true);
+  assert.deepEqual(state.folded, [1]);
+  assert.ok(io.writes.some((a) => a[1] === "close" && a[2] === "1"));
+  assert.equal(decisionCounts(state).folded, 1);
+  const none = fakeIo([{ number: 1, comments: [esc(10, "All items are post-deploy: nothing to build.")] }]);
+  const w2 = W(), s2 = st(w2); // no rollup: kept, never closed
+  assert.equal((await run(none, w2, s2, ctxOf())).rows[0].action, "post-deploy-kept");
+  assert.equal(none.writes.length, 0);
+});
+
+test("#4793 evidence escalation goes back to a prod-monitor lane only when forge.yaml declares a read-only source", async () => {
+  const text = "The check needs read-only production data we do not have.";
+  const declared = ctxOf("decisions:\n  mode: live\nprod_watch:\n  sources:\n    am: {kind: alertmanager, run: am-alerts}\n");
+  assert.equal(declared.hasSource, true);
+  const io = fakeIo([{ number: 1, comments: [esc(10, text)] }]);
+  const w = W(), state = st(w);
+  const { rows } = await run(io, w, state, declared, { launch: () => true });
+  assert.equal(rows[0].action, "evidence-needed");
+  assert.ok(io.writes.some((a) => a[1] === "comment" && /prod monitor/.test(a[a.indexOf("--body") + 1])));
+  assert.ok(io.writes.some((a) => a.includes("--remove-label")));
+  assert.deepEqual(state.decisions.launched, [1]);
+  assert.equal(decisionCounts(state).evidence, 1);
+  const io2 = fakeIo([{ number: 1, comments: [esc(10, text)] }]);
+  const none = ctxOf();
+  assert.equal(none.hasSource, false);
+  assert.equal((await run(io2, w, st(w), none)).rows[0].action, "evidence-kept");
+  assert.equal(io2.writes.length, 0);
+});
+
+test("#4793 external part keeps needs-human and counts as external-kept", async () => {
+  const io = fakeIo([{ number: 1, comments: [esc(10, "- Rotate the production API key (credentials)")] }]);
+  const w = W(), state = st(w);
+  assert.equal((await run(io, w, state, ctxOf())).rows[0].action, "external");
+  assert.equal(decisionCounts(state).external_kept, 1);
+  assert.equal(io.writes.length, 0);
+});
+
+test("#4793 shadow mode posts the decision and keeps the label", async () => {
+  const io = fakeIo([{ number: 1, comments: [esc(10, DECISION)] }]);
+  const w = W({ sweep_needs_human: true }), state = st(w);
+  assert.equal((await run(io, w, state, ctxOf("decisions:\n  mode: shadow\n"))).rows[0].action, "shadow");
+  assert.ok(!io.writes.some((a) => a.includes("--remove-label")));
+});
+
+test("#4793 shadow mode never folds, closes, clears the label or launches a post-deploy or evidence escalation", async () => {
+  const shadow = ctxOf("decisions:\n  mode: shadow\nprod_watch:\n  sources:\n    am: {kind: alertmanager, run: am-alerts}\n");
+  const io = fakeIo([{ number: 1, comments: [stateC("conformance.deferred"), esc(10, "All items are post-deploy: nothing to build.")] }, { number: 2, comments: [esc(11, "The check needs read-only production data we do not have.")] }]);
+  const w = W({ sweep_needs_human: true, postdeploy_rollup: 50 }), state = st(w), launched = [];
+  const { rows } = await run(io, w, state, shadow, { launch: (i) => launched.push(i.number) });
+  assert.deepEqual(rows.map((r) => r.action), ["shadow", "shadow"]);
+  assert.deepEqual(state.folded, []);
+  assert.deepEqual(launched, []);
+  assert.ok(!io.writes.some((a) => a[1] === "close" || a.includes("--remove-label")));
+  assert.equal(io.writes.filter((a) => a[1] === "comment").length, 2);
+});
+
+test("#4793 a live decision relaunches the issue through the launch hook", async () => {
+  const io = fakeIo([{ number: 1, comments: [esc(10, DECISION)] }]);
+  const w = W(), state = st(w), launched = [];
+  await run(io, w, state, ctxOf(), { launch: (i) => launched.push(i.number) });
+  assert.deepEqual(launched, [1]);
+  assert.deepEqual(state.decisions.launched, [1]);
+  assert.deepEqual(claimsUsed(state), { issues: 1, launches: 1 });
+});
+
+test("#4793 a judge failure is not recorded as handled: retried, then left to a human after three rounds", async () => {
+  const io = fakeIo([{ number: 1, comments: [esc(10, DECISION)] }], { judge: () => { throw new Error("claude timed out"); } });
+  const w = W(), state = st(w), ctx = ctxOf();
+  assert.equal((await run(io, w, state, ctx)).rows[0].action, "error");
+  assert.equal(state.decisions.handled["10"], undefined);
+  assert.equal(state.decisions.rows.length, 0);
+  await run(io, w, state, ctx); await run(io, w, state, ctx);
+  assert.equal(state.decisions.handled["10"], "error");
+  await run(io, w, state, ctx);
+  assert.equal(io.judged.length, 3);
+});
+
+test("#4793 a NEEDS_HUMAN comment from an untrusted author is not an escalation", async () => {
+  const io = fakeIo([{ number: 1, comments: [{ ...esc(10, DECISION), authorAssociation: "CONTRIBUTOR" }] }]);
+  const w = W();
+  assert.equal((await run(io, w, st(w), ctxOf())).rows.length, 0);
+  assert.equal(io.judged.length, 0);
+});
+
+test("#4793 a veto label reverts a live decision once", async () => {
+  const issues = [{ number: 1, comments: [esc(10, DECISION)] }];
+  const io = fakeIo(issues);
+  const w = W(), state = st(w), ctx = ctxOf();
+  await run(io, w, state, ctx);
+  issues[0].labels = ["forge:decision-veto"];
+  await run(io, w, state, ctx);
+  assert.ok(io.writes.some((a) => a[1] === "edit" && a.includes("--add-label") && a.includes("needs-human")));
+  assert.equal(state.decisions.stats.reversed, 1);
+  assert.equal(state.decisions.live.length, 0);
+});
+
+test("#4793 formatStatus shows the decision counts only once the stage ran", async () => {
+  const w = W(), plain = st(w);
+  assert.ok(!/needs-human decisions/.test(formatStatus(plain, w, NOW)));
+  const io = fakeIo([{ number: 1, comments: [esc(10, DECISION)] }]);
+  await run(io, w, plain, ctxOf());
+  assert.match(formatStatus(plain, w, NOW), /decided 1  evidence-gathered 0  folded 0  external-kept 0/);
+});
+
+test("#4793 runWatch runs the stage under decisions.mode: live, stays inert otherwise, and max_launches stops claims", async () => {
+  const mkCwd = (yaml) => { const d = tmpDir("iwc-"); writeFileSync(join(d, "NORTHSTAR.md"), "# star"); if (yaml) writeFileSync(join(d, "forge.yaml"), yaml); return d; };
+  const base = (n, i = {}) => ({ number: n, title: `t${n}`, body: "", labels: [], milestone: null, authorAssociation: "OWNER", author: { login: "me" }, createdAt: "2026-10-01T00:00:00Z", ...i });
+  const go = async (yaml, w) => {
+    const issues = [base(1, { labels: [{ name: "needs-human" }] }), base(2), base(3)], writes = [], launched = [];
+    const dir = tmpDir("iwd-");
+    const io = { env: { FORGEDOCK_WATCH_DIR: dir }, now: () => NOW, sleep: async () => {}, requiredChecks: async () => [], judge: async () => good,
+      gh: async (a) => {
+        if (a[0] === "api") return issues.map((i) => `${i.number}\tOWNER`).join("\n");
+        if (a[1] === "list") return JSON.stringify((a.includes("--label") ? issues.filter((i) => i.labels.length) : issues.filter((i) => !i.labels.length)).map(({ authorAssociation: _a, ...i }) => i));
+        if (a[1] === "view" && a.includes("comments,body,labels")) return JSON.stringify({ comments: [esc(10, DECISION)], body: "", labels: [] });
+        if (a[1] === "view") return JSON.stringify({ state: "OPEN", comments: [], labels: [] });
+        writes.push(a);
+        return "";
+      },
+      launch: (n) => { launched.push(n); return { poll: () => null }; } };
+    const state = await runWatch({ watch: w, repo: "o/r", io, dir, branches: {}, defaults: [], once: true, cwd: mkCwd(yaml) });
+    return { state, writes, launched };
+  };
+  const inert = await go("decisions:\n  mode: shadow\n", W());
+  assert.equal(inert.state.decisions, undefined);
+  assert.equal(inert.writes.length, 0);
+  const live = await go("decisions:\n  mode: live\n", W());
+  assert.equal(live.state.decisions.rows[0].action, "decided");
+  assert.ok(live.writes.some((a) => a.includes("--remove-label")));
+  assert.deepEqual(live.launched, [1, 2, 3]); // the decided issue is relaunched, then the watch claims the rest
+  const capped = await go("", W({ max_launches: 2 }));
+  assert.equal(capped.launched.length, 2);
+  assert.deepEqual(capped.state.claimed.length, 2);
+});
+
+test("#4793 the engine's own App login counts as trusted though it is a CONTRIBUTOR; another CONTRIBUTOR does not", async () => {
+  const from = (login) => ({ ...esc(10, DECISION), authorAssociation: "CONTRIBUTOR", author: { login } });
+  const w = W();
+  assert.equal((await run(fakeIo([{ number: 1, comments: [from("rapiercraft-forgedock")] }]), w, st(w), ctxOf())).rows.length, 1);
+  assert.equal((await run(fakeIo([{ number: 1, comments: [from("some-contributor")] }]), w, st(w), ctxOf())).rows.length, 0);
+});
+
+test("#4793 judge calls are capped per round even when max_issues is unset", async () => {
+  const issues = Array.from({ length: 30 }, (_, k) => ({ number: k + 1, comments: [{ ...esc(100 + k, DECISION), url: `https://x/issues/${k + 1}#issuecomment-${100 + k}` }] }));
+  const io = fakeIo(issues);
+  const w = W(), state = st(w);
+  assert.equal(w.max_issues, null);
+  await run(io, w, state, ctxOf());
+  assert.equal(io.judged.length, 20);
+  await run(io, w, state, ctxOf()); // the rest is picked up next round
+  assert.equal(io.judged.length, 30);
+});
+
+test("release #5068 MAT-1: a batch watch requeues a claimed issue into its batch; release and unclaimed issues release the claim", () => {
+  const calls = [];
+  const io = { batch: { requeue: (id, n) => { calls.push([id, n]); return true; } } };
+  const b = W({ mode: "batch" }), sb = st(b, { batch: "b1", claimed: [5], failed: [5] });
+  assert.equal(decisionLaunch({ i: { number: 5 }, watch: b, repo: "o/r", io, state: sb, handles: new Map() }), true);
+  assert.deepEqual(calls, [["b1", 5]]);
+  assert.deepEqual(sb.failed, []);
+  assert.deepEqual(sb.claimed, [5]); // still the batch's
+  const refused = { batch: { requeue: () => false } };
+  assert.equal(decisionLaunch({ i: { number: 5 }, watch: b, repo: "o/r", io: refused, state: st(b, { batch: "b1", claimed: [5] }), handles: new Map() }), false);
+  const sb2 = st(b, { batch: "b1", claimed: [] }); // a backlog issue the batch never took: the next tick adds it
+  assert.equal(decisionLaunch({ i: { number: 6 }, watch: b, repo: "o/r", io, state: sb2, handles: new Map() }), true);
+  assert.deepEqual(calls.length, 1);
+  const r = W({ mode: "release", immediate: ["priority:P0"] }), sr = st(r, { claimed: [7, 8], lanes: { 7: "staging" }, failed: [7] });
+  assert.equal(decisionLaunch({ i: { number: 7 }, watch: r, repo: "o/r", io, state: sr, handles: new Map() }), true);
+  assert.deepEqual(sr.claimed, [8]); // re-selectable by the next release pass
+  assert.deepEqual(sr.failed, []);
+  const p = W(); // per-issue: an inflight lane is never launched twice
+  assert.equal(decisionLaunch({ i: { number: 9 }, watch: p, repo: "o/r", io, state: st(p, { inflight: [9] }), handles: new Map() }), false);
+});
+
+test("release #5068 MAT-4: a launch that does not happen is not counted against max_launches", async () => {
+  const io = fakeIo([{ number: 1, comments: [esc(10, DECISION)] }]);
+  const w = W(), state = st(w);
+  await run(io, w, state, ctxOf(), { launch: () => false });
+  assert.deepEqual(state.decisions.launched, []);
+});
+
+test("release #5068 MAT-2: one unreadable issue does not end the round", async () => {
+  const io = fakeIo([1, 2].map((n) => ({ number: n, comments: [esc(10 + n, DECISION)] })));
+  const gh = io.gh;
+  io.gh = async (a) => { if (a[1] === "view" && a[2] === "1") throw new Error("HTTP 502"); return gh(a); };
+  const w = W(), state = st(w);
+  const { rows } = await run(io, w, state, ctxOf(), { launch: () => true });
+  assert.deepEqual(rows.map((r) => [r.issue, r.action]), [[1, "error"], [2, "decided"]]);
+});
+
+test("release #5068 BUG-1: a live decision whose label clear failed is finished next round, not skipped", async () => {
+  const posted = { ...esc(20, "x"), body: "<!-- FORGE:DECISION -->\n## Decision\nEscalation: 11\n### Decision 1\nuse A" };
+  const io = fakeIo([{ number: 1, comments: [{ ...esc(11, DECISION), url: "https://x/issues/1#issuecomment-11" }, posted] }]);
+  const w = W(), state = st(w), launched = [];
+  const { rows } = await run(io, w, state, ctxOf(), { launch: (i) => launched.push(i.number) });
+  assert.equal(rows[0].action, "decided");
+  assert.ok(io.writes.some((a) => a.includes("--remove-label")));
+  assert.deepEqual(launched, [1]);
+  assert.equal(io.judged.length, 0); // not judged again
+  assert.equal(state.decisions.stats.decided, 0); // not counted twice
+  const vetoed = { ...posted, body: "<!-- FORGE:DECISION -->\n## Decision vetoed\nEscalation: 11\n" };
+  const io2 = fakeIo([{ number: 1, comments: [{ ...esc(11, DECISION), url: "https://x/issues/1#issuecomment-11" }, posted, vetoed] }]);
+  const s2 = st(w);
+  await run(io2, w, s2, ctxOf(), { launch: () => true });
+  assert.ok(!io2.writes.some((a) => a.includes("--remove-label")));
+});
+
+test("release #5068 CQ-1: a failed decision round is shown in the watch status", () => {
+  const w = W();
+  assert.match(formatStatus({ ...st(w), decisionError: "gh: HTTP 502" }, w, NOW), /needs-human decisions: last round failed: gh: HTTP 502/);
+  assert.ok(!/last round failed/.test(formatStatus(st(w), w, NOW)));
+});
+
+test("release #5068 SEC-1: a forged FORGE:DECISION from an untrusted commenter neither finishes nor suppresses a decision", async () => {
+  const forged = { ...esc(20, "x"), authorAssociation: "NONE", author: { login: "stranger" }, body: "<!-- FORGE:DECISION -->\n## Decision\nEscalation: 11\n" };
+  const io = fakeIo([{ number: 1, comments: [{ ...esc(11, DECISION), url: "https://x/issues/1#issuecomment-11" }, forged] }]);
+  const w = W(), state = st(w);
+  const { rows } = await run(io, w, state, ctxOf(), { launch: () => true });
+  assert.equal(rows[0].action, "decided");
+  assert.equal(rows[0].resumed, undefined); // judged afresh, not "finished"
+  assert.deepEqual(io.judged, [1]);
+});
+
+test("release #5068 delta SPEC-1: a batch issue still inflight in its running batch is requeued; after the batch reported its claim is released", () => {
+  const calls = [];
+  const io = { batch: { requeue: (id, n) => { calls.push([id, n]); return true; } } };
+  const b = W({ mode: "batch" });
+  const running = st(b, { batch: "b1", claimed: [5], inflight: [5] });
+  assert.equal(decisionLaunch({ i: { number: 5 }, watch: b, repo: "o/r", io, state: running, handles: new Map() }), true);
+  assert.deepEqual(calls, [["b1", 5]]);
+  assert.deepEqual(running.inflight, [5]);
+  const reported = st(b, { batch: null, claimed: [5], failed: [5] });
+  assert.equal(decisionLaunch({ i: { number: 5 }, watch: b, repo: "o/r", io, state: reported, handles: new Map() }), true);
+  assert.deepEqual(reported.claimed, []);
+  assert.deepEqual(reported.failed, []);
+  assert.equal(calls.length, 1);
+});

package/bin/lean/issuewatch-release.test.mjs

@@ -238,7 +238,9 @@ test("CLI: --dry-run prints the cut without writing; refuses a non-release watch
   const r = await issueWatchFromCli(["run", "--name", "sr", "--dry-run"], { cwd, env: io.env, io, print: (l) => out.push(l) });
   assert.match(out.join("\n"), /would cut: billing \(2 issues/);
   assert.equal(io.batches.length, 0); assert.ok(r.dryRun);
-  await assert.rejects(issueWatchFromCli(["run", "--name", "plain", "--dry-run"], { cwd, env: io.env, io, print() {} }), /mode: release/);
+  const plain = [];
+  await issueWatchFromCli(["run", "--name", "plain", "--dry-run"], { cwd, env: io.env, io, print: (l) => plain.push(l) }); // #4793: a non-release watch dry-run classifies needs-human escalations
+  assert.match(plain.join("\n"), /no needs-human escalations to classify/);
   const w = loadWatches(`issue_watch:\n  watches:\n    sr:\n      mode: release\n      threshold: { min_issues: 2 }\n`).sr;
   assert.match(formatStatus({ name: "sr", repo: "o/r", phase: "running", claimed: [1], inflight: [1], merged: [], verified: [], failed: [], pool: [2, 3], llm: 2, releases: [], release: { theme: "billing", issues: [1], batch: "b1" } }, w), /pool: 2.*active: billing.*llm-classified: 2/);
 });

package/bin/lean/issuewatch.mjs

@@ -10,7 +10,7 @@
  * No LLM calls.
  */
 import { existsSync, mkdirSync, readFileSync, rmdirSync } from "node:fs";
-import { execFileSync, spawn } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { homedir, hostname } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -19,15 +19,19 @@ import { milestoneSlug, readBranches, isDefaultLane, defaultBranches, DEFAULT_ST
 import { postDeployOnly } from "./prefilter.mjs";
 import { releaseTick, formatDryRun } from "./issuewatch-release.mjs";
 import { loadPolicy } from "./decision-engine.mjs";
+import { decisionContext, decisionsActive, decisionStep, decisionCounts, formatDecisionDryRun, claimsUsed } from "./issuewatch-decisions.mjs";
 import { APP_SLUG } from "../init-repo.mjs";
 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"];
-const TRUSTED = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
+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"];
+export const TRUSTED = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
 const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const RETRIES = 3;
+const readFile = (f) => readFileSync(f, "utf8");
+const JUDGE_TIMEOUT_MS = 120_000; // a hung `claude --print` must not stall the watch round
+const CLAUDE_MAX_BUFFER = 8 * 1024 * 1024;
 const VERIFY_WAIT_MS = 60 * 60000; // how long a merge commit's CI may stay pending before verification fails
 const readJson = (f) => { try { return JSON.parse(readFileSync(f, "utf8")); } catch { return null; } };
 
@@ -74,7 +78,9 @@ 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 };
+    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" };
+  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 (!["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`);
@@ -107,7 +113,7 @@ function validateRelease(name, cfg, w, int) {
 export const loadWatches = (raw) => Object.fromEntries(Object.entries(parseWatches(raw)).map(([n, c]) => [n, validateWatch(n, c)]));
 
 // ── selectors ────────────────────────────────────────────────────────────────────────────────────────────────
-const labelNames = (i) => (i.labels ?? []).map((l) => (typeof l === "string" ? l : l?.name)).filter(Boolean);
+export const labelNames = (i) => (i.labels ?? []).map((l) => (typeof l === "string" ? l : l?.name)).filter(Boolean);
 
 /** An issue's target version: x.y from its milestone title, else from a `version:x.y` label; null when none. */
 export function issueVersion(issue) {
@@ -135,7 +141,7 @@ export const hasUnresolvedDefer = (body) => noComments(body).split("\n").some((l
 
 // 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.
-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; };
+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 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). */
@@ -270,11 +276,12 @@ export async function tick({ watch, repo, io, state, dir, branches = {}, default
   for (const n of [...(state.pendingVerify ?? [])]) if (await closed(n)) await verify(n);
   if (watch.mode === "batch" && state.batch && io.batch.reported(state.batch)) { state.inflight.forEach(fail); state.batch = null; }
 
-  const capped = (watch.max_issues && state.claimed.length >= watch.max_issues) || (watch.until && now >= Date.parse(watch.until));
+  const used = claimsUsed(state); // the decision stage (#4793) draws on the same caps
+  const capped = (watch.max_issues && used.issues >= watch.max_issues) || (watch.max_launches && used.launches >= watch.max_launches) || (watch.until && now >= Date.parse(watch.until));
   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 - state.claimed.length : Infinity);
+  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 = [];
@@ -316,7 +323,7 @@ async function releaseStep({ watch, repo, io, state, dir, branches = {}, default
     return all;
   };
   const eligible = (i) => matchesSelectors(i, watch) && classifyIssue(i, watch) === "claim" && !state.claimed.includes(i.number) && unclaimedOrOwn(registry(), i.number, watch.name); // release #4820 CONC-1: own claims stay eligible
-  const p = loadPolicy({ io: { readFile: (f) => readFileSync(f, "utf8") }, cwd });
+  const p = loadPolicy({ io: { readFile }, cwd });
   return releaseTick({ watch, repo, io, state, defaults, listOpen, eligible, claim: (n) => claimIssue(repoDir(repo, io.env), n, watch.name), laneFor: (i) => laneFor(i, watch, { branches, defaults }), dagOrder,
     policy: { path: p.policyPath, text: p.policyText }, dryRun });
 }
@@ -336,15 +343,52 @@ export function formatStatus(s, watch, now = Date.now()) {
   const left = watch.until ? `${Math.max(0, Math.round((Date.parse(watch.until) - now) / 60000))}m` : "forever";
   return [`watch ${s.name} (${s.repo}) [${s.phase}, ${watch.mode}]`, `  selector: ${sel}`,
     `  claims: ${s.claimed.length}/${watch.max_issues ?? "∞"}  inflight: ${s.inflight.length}  merged: ${s.merged.length}  verified: ${s.verified.length}  unverified: ${(s.unverified ?? []).length}  closed unmerged: ${(s.closed ?? []).length}  failed: ${s.failed.length}`, `  time remaining: ${left}`,
+    ...(s.decisions ? [(({ decided, evidence, folded, external_kept: kept }) => `  needs-human decisions: decided ${decided}  evidence-gathered ${evidence}  folded ${folded}  external-kept ${kept}`)(decisionCounts(s))] : []),
+    ...(s.decisionError ? [`  needs-human decisions: last round failed: ${s.decisionError}`] : []), // release #5068 CQ-1
     ...(watch.mode === "release" ? [`  pool: ${(s.pool ?? []).length}  releases: ${(s.releases ?? []).length + (s.release ? 1 : 0)}${s.release ? `  active: ${s.release.theme} (${s.release.issues.length} issues, batch ${s.release.batch})` : ""}  llm-classified: ${s.llm ?? 0}`] : [])].join("\n");
 }
 
+const unsettle = (state, n) => { for (const k of ["failed", "unverified", "closed", "pendingVerify"]) if (state[k]) state[k] = state[k].filter((x) => x !== n); delete state.retries[n]; };
+/**
+ * #4793: a decided or evidence-gathered issue (needs-human already cleared) goes back to a lane. Per-issue watches launch it
+ * here. Release #5068 MAT-1: batch and release watches never re-select an issue they hold in `claimed`, so a batch watch
+ * requeues it into its batch (`orchestrate --requeue`), and an issue the watch has not taken yet, or a release watch's,
+ * has its claim released so the next pass selects it. @returns {boolean} true when a lane runs or the next pass takes it.
+ */
+export function decisionLaunch({ i, watch, repo, io, state, handles, branches, defaults }) {
+  const n = i.number;
+  // release #5068 delta SPEC-1: a batch issue stays inflight until its batch reports, so a running batch is requeued
+  // whatever inflight says; once the batch reported (tick moved it to failed, state.batch null) the claim is released
+  if (watch.mode === "batch" && state.batch && state.claimed.includes(n)) {
+    if (!io.batch?.requeue?.(state.batch, n, "issue-watch decision: needs-human settled")) return false;
+    unsettle(state, n);
+    if (!state.inflight.includes(n)) state.inflight.push(n);
+    return true;
+  }
+  if (watch.mode !== "per-issue") { // the next tick / release pass re-selects it (own registry claims stay eligible)
+    state.claimed = state.claimed.filter((x) => x !== n); state.inflight = state.inflight.filter((x) => x !== n); delete state.lanes[n];
+    unsettle(state, n);
+    return true;
+  }
+  if (state.inflight.includes(n) || !claimIssue(repoDir(repo, io.env), n, watch.name)) return false;
+  const lane = laneFor(i, watch, { branches, defaults });
+  if (!state.claimed.includes(n)) state.claimed.push(n);
+  unsettle(state, n); state.inflight.push(n); state.lanes[n] = lane; handles.set(n, io.launch(n, lane));
+  return true;
+}
+
 /** Run until done (capped) or `once`; writes status.json each pass. */
 export async function runWatch({ watch, repo, io, dir, branches, defaults, once = false, intervalMs = 300000, release = () => {}, cwd }) {
   const state = readJson(join(dir, "status.json")) ?? fresh(watch, repo);
   const handles = new Map();
+  const ctx = decisionContext({ loadPolicy, readFile, cwd: cwd ?? process.cwd() });
+  const shared = { matches: matchesSelectors, fold, labelNames, isBot, TRUSTED };
+  const launch = (i) => decisionLaunch({ i, watch, repo, io, state, handles, branches, defaults });
   try {
     do {
+      if (state.phase === "running" && decisionsActive(watch, ctx.policy)) { // #4793: a failed round must not stop the watch
+        try { await decisionStep({ watch, repo, io, state, ctx, shared, launch }); state.decisionError = null; } catch (e) { state.decisionError = String(e?.message ?? e).slice(0, 200); }
+      }
       if (watch.mode === "release") await releaseStep({ watch, repo, io, state, dir, branches, defaults, cwd }); else await tick({ watch, repo, io, state, dir, branches, defaults, handles });
       writeAtomic(join(dir, "status.json"), JSON.stringify(state) + "\n");
       if (state.phase === "done" || once) break;
@@ -355,6 +399,7 @@ export async function runWatch({ watch, repo, io, dir, branches, defaults, once
 }
 
 // ── real io + CLI ───────────────────────────────────────────────────────────────────────────────────────────
+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 });
@@ -364,6 +409,10 @@ function realIo(repo, env = process.env) {
       const prompt = `Classify each GitHub issue into exactly one theme of [${themes.join(", ")}], or "general" when none fits. Reply with only a JSON object {"<number>": "<theme>"}.\n\n${issues.map((i) => `#${i.number} ${i.title}\n${String(i.body ?? "").slice(0, 600)}`).join("\n---\n")}`;
       return JSON.parse(/\{[\s\S]*\}/.exec(execFileSync("claude", ["--print"], { input: prompt, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 }))[0]);
     },
+    judge: ({ decision, options, policy, policyPath, precedent }) => { // #4793: the one LLM judgment of the decision stage
+      const prompt = judgePrompt({ decision, options, policy, policyPath, precedent });
+      return JSON.parse(/\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}/.exec(execFileSync("claude", ["--print"], { input: prompt, encoding: "utf8", maxBuffer: CLAUDE_MAX_BUFFER, timeout: JUDGE_TIMEOUT_MS }))[0]);
+    },
     launch: (n, lane) => {
       let res = null;
       const p = spawn(process.execPath, [CLI, "run-issue", String(n), "--lane", lane], { detached: true, windowsHide: true, stdio: "ignore", cwd: process.cwd(), env });
@@ -372,6 +421,8 @@ function realIo(repo, env = process.env) {
     },
     batch: {
       add: (id, issues) => openBatch(root, id).addIssues(issues),
+      // release #5068 MAT-1: the CLI path checks the label, reopens a finished batch and hosts it on the schedd
+      requeue: (id, n, reason) => (spawnSync(process.execPath, [CLI, "orchestrate", "--requeue", id, String(n), "--reason", reason], { cwd: process.cwd(), env, encoding: "utf8", timeout: 120000, windowsHide: true }).stdout ?? "").match(new RegExp(`requeued #${n}\\b`)) !== null,
       reported: (id) => existsSync(join(root, id, "report.json")),
       start: async (issues, parallel, lane) => {
         const before = new Set(listBatches(root));
@@ -403,13 +454,19 @@ export async function issueWatchFromCli(argv, deps = {}) {
     print(s ? formatStatus(s, watch, io.now()) : `watch ${name}: no status yet`);
     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 });
+    print(formatDecisionDryRun(rows));
+    return { ok: true, dryRun: { rows } };
+  }
   if (argv.includes("--dry-run")) {
-    if (watch.mode !== "release") throw new Error("--dry-run needs a watch with mode: release");
     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 r = await releaseStep({ watch, repo, io: real, state, dir, branches, defaults, dryRun: true, cwd });
     print(r.decision ? formatDryRun(r.decision, r.pool, r.themes) : "release in flight; nothing to cut");
+    if (decisionsActive(watch, ctx.policy)) print(formatDecisionDryRun((await decisionStep({ watch, repo, io: real, state, ctx, shared, dryRun: true })).rows));
     return { ok: true, dryRun: r };
   }
   mkdirSync(dir, { recursive: true });

package/bin/lean/issuewatch.test.mjs

@@ -401,3 +401,21 @@ for (const [what, bad] of [["label", (a) => a[1] === "edit" && a.includes("needs
     assert.deepEqual(state.pendingVerify, []);
   });
 }
+
+test("#4793 sweep_needs_human and max_launches are watch keys; max_launches caps the claims of a tick", async () => {
+  assert.equal(W({ sweep_needs_human: true, max_launches: 1 }).max_launches, 1);
+  assert.throws(() => W({ max_launches: "x" }), /max_launches/);
+  const env = tmp();
+  const io = fakeIo(env, [iss(1), iss(2), iss(3)]);
+  const w = W({ max_launches: 2 });
+  const state = await runWatch({ watch: w, repo: "o/r", io, dir: env, branches: {}, defaults: [], once: true, cwd: tmp() });
+  assert.equal(state.claimed.length, 2);
+  assert.equal(io.launched.length, 2);
+});
+
+test("#4793 formatStatus lists decided / evidence-gathered / folded / external-kept from the stage rows", () => {
+  const w = W();
+  const s = { name: "w", repo: "o/r", phase: "running", claimed: [], inflight: [], merged: [], verified: [], failed: [],
+    decisions: { rows: [{ action: "decided" }, { action: "evidence-needed" }, { action: "post-deploy-only" }, { action: "external", kept: true }, { action: "external", kept: true }] } };
+  assert.match(formatStatus(s, w, 0), /needs-human decisions: decided 1  evidence-gathered 1  folded 1  external-kept 2/);
+});

package/bin/lean/lean.mjs

@@ -64,6 +64,7 @@ import { buildResumeDigest } from "./resume.mjs";
 import { parsePredicate, evalPredicate, premiseAnnotation, registerAsk, registryPkgVersion, closedEdgeNote, onlyAsk, fileRemainder } from "./needs-human-premise.mjs";
 import { lightEligibility } from "./light.mjs";
 import { untrackToolState, unstageToolState, isToolState, clearLaneScratch } from "./toolstate.mjs";
+import { pickSalvage } from "./salvage-resume.mjs";
 import { ensureSignedOff, salvageBranch, dropSalvageTracking } from "./signoff.mjs";
 import { createLedger, flattenPhases } from "./phaseledger.mjs";
 import { runLightStep, runLightTests, lightBuildPrompt, upgradeNote, renderLiteReceipt } from "./lightlane.mjs";
@@ -1094,10 +1095,8 @@ export async function runCore(o) {
       const prs = JSON.parse(String(await ghc(["pr", "list", "-R", repo, "--head", branch, "--state", "open", "--json", "number,headRefOid,baseRefName"])) || "[]");
       const remote = String(await io.git(["ls-remote", "--heads", "origin", branch], { cwd })).trim();
       if (prs.length || remote) resumed = { pr: prs[0]?.number ?? null, base: prs[0]?.baseRefName ?? null };
-      if (!prs.length && !remote) { // #4958: commits the exit rescue could only push to a salvage branch resume from there
-        const salv = String(await io.git(["ls-remote", "--heads", "origin", `refs/heads/forge-salvage/${issue}-*`], { cwd })).split("\n").map((l) => l.trim().split(/\s+/)[1]).filter(Boolean).sort().at(-1);
-        if (salv) { await io.git(["fetch", "origin", `${salv}:refs/remotes/origin/${branch}`], { cwd }); resumed = { pr: null, base: null }; fromSalvage = true; ev({ event: "RESUME_FROM_SALVAGE", ref: salv }); }
-      }
+      const salv = (await pickSalvage({ io, cwd, issue, branch, hasBranch: Boolean(remote) }).catch((e) => { ev({ event: "SALVAGE_PICK_FAILED", error: String(e?.message ?? e).slice(0, 200) }); return null; }))?.ref; // release #5068 delta SPEC-2: never silent // #4958, #5063: the newest salvage ref that is not behind the lane branch
+      if (salv) { await io.git(["fetch", "origin", `${salv}:refs/remotes/origin/${branch}`], { cwd }); resumed = { pr: prs[0]?.number ?? null, base: prs[0]?.baseRefName ?? null }; fromSalvage = true; ev({ event: "RESUME_FROM_SALVAGE", ref: salv }); }
     } catch { /* no resume info: start fresh */ }
     // An open PR on another base (a hand-retargeted PR, or one opened before lane resolution) is never merged (#4125).
     // #4593: a shipped milestone lane (fully merged into staging) cannot take new work; follow the open PR's live base.
@@ -1148,7 +1147,7 @@ export async function runCore(o) {
         }
       }
     };
-    if (resumed) { try { await io.git(["fetch", "origin", branch], { cwd }); } catch { /* remote branch may not exist (PR-less resume) */ } }
+    if (resumed && !fromSalvage) { try { await io.git(["fetch", "origin", branch], { cwd }); } catch { /* remote branch may not exist (PR-less resume) */ } }
     // #4786: an open-PR-less remote branch whose only changes vs the base are tool state (.forge-lean/ scratch) holds no work: plan fresh, never resume its stale contract.
     const toolOnly = async (ref) => { const n = String(await io.git(["diff", "--name-only", `${base}...${ref}`], { cwd })).split("\n").map((x) => x.trim()).filter(Boolean); return n.every((f) => isToolState(f)); };
     let scratchOnly = false;

package/bin/lean/lean.test.mjs

@@ -3943,6 +3943,21 @@ describe("batch robustness (#4112-#4115)", () => {
     assert.ok(w.calls.some((c) => c[0] === "git" && c[1] === "worktree" && c[2] === "add" && c.includes("origin/feat/issue-7-lean")), "the worktree is built from the salvaged head");
   });
 
+  it("#5063 a rerun with an existing lane branch resumes from a newer salvage ref", async () => {
+    const w = world({ prList: [], remote: "abc\trefs/heads/feat/issue-7-lean\n" });
+    const g = w.io.git;
+    w.io.git = async (a, o2) => {
+      if (a[0] === "ls-remote" && a.at(-1) === "refs/heads/forge-salvage/7-*") return "abc\trefs/heads/forge-salvage/7-1234567890\n";
+      if (a[0] === "merge-base" && a[2] === "origin/feat/issue-7-lean") { w.calls.push(["git", ...a]); return ""; } // the lane branch is an ancestor of the salvage head
+      return g(a, o2);
+    };
+    await run(w);
+    assert.ok(w.calls.some((c) => c[0] === "git" && c[1] === "fetch" && c.includes("refs/heads/forge-salvage/7-1234567890:refs/remotes/origin/feat/issue-7-lean")), "origin/<branch> is moved to the salvage head");
+    const at = (f) => w.calls.findIndex(f);
+    const add = at((c) => c[1] === "worktree" && c[2] === "add");
+    assert.ok(add >= 0 && !w.calls.slice(0, add).some((c) => c[1] === "fetch" && c.length === 4 && c[3] === "feat/issue-7-lean"), "no refetch of the lane branch moves origin/<branch> off the salvage head before the worktree is built");
+  });
+
   it("#4118 GitHub's transient '[remote rejected] ... (failed)' and pack write errors are retried, then merge", async () => {
     for (const msg of ["To github.com:o/r.git\n ! [remote rejected] feat/issue-7-lean -> feat/issue-7-lean (failed)",
       "remote: error: unable to write file ./objects/pack/pack-1.pack: No such file or directory\n ! [remote rejected] x -> x (failed)"]) {

package/bin/lean/salvage-resume.mjs

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * #5063: pick the salvage ref a rerun resumes from. The DCO and exit rescues push to `forge-salvage/<issue>-<sha10>`
+ * (#4958, #5047). The suffix is a sha, so the newest ref is chosen by commit time, not by name. When the lane branch
+ * already exists on origin, only a ref strictly ahead of it (descending from origin/<branch>) can be resumed without
+ * losing either side; a behind or diverged ref is ignored.
+ */
+const ok = async (git, args, cwd) => { try { await git(args, { cwd }); return true; } catch { return false; } };
+
+/** @returns {Promise<{ref: string, sha: string} | null>} */
+export async function pickSalvage({ io, cwd, issue, branch, hasBranch }) {
+  const out = String(await io.git(["ls-remote", "--heads", "origin", `refs/heads/forge-salvage/${issue}-*`], { cwd }));
+  const refs = out.split("\n").map((l) => l.trim().split(/\s+/)).filter((p) => p[1]).map(([sha, ref]) => ({ sha, ref }));
+  if (!refs.length) return null;
+  if (refs.length > 1 || hasBranch) await io.git(["fetch", "origin", `+refs/heads/forge-salvage/${issue}-*:refs/remotes/origin/forge-salvage/${issue}-*`], { cwd });
+  // release #5068 BUG-2/SPEC-1: compare against the live lane branch; a missing or stale local origin/<branch> would ignore a usable salvage or resume one that is behind the remote
+  if (hasBranch) await io.git(["fetch", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`], { cwd });
+  for (const r of refs) r.ct = Number(String(await io.git(["log", "-1", "--format=%ct", r.sha], { cwd }).catch(() => "")).trim()) || 0;
+  refs.sort((a, b) => b.ct - a.ct || (a.ref < b.ref ? 1 : -1));
+  for (const r of refs) {
+    if (!hasBranch) return r;
+    if (await ok(io.git, ["merge-base", "--is-ancestor", `origin/${branch}`, r.sha], cwd) && !(await ok(io.git, ["merge-base", "--is-ancestor", r.sha, `origin/${branch}`], cwd))) return r;
+  }
+  return null;
+}

package/bin/lean/salvage-resume.test.mjs

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { pickSalvage } from "./salvage-resume.mjs";
+
+/** refs: [{ sha, name, ct }]; ahead: shas strictly ahead of origin/<branch>; behind: shas that are ancestors of it. */
+const world = ({ refs = [], ahead = [], behind = [] } = {}) => {
+  const calls = [];
+  const git = async (a) => {
+    calls.push(a);
+    if (a[0] === "ls-remote") return refs.map((r) => `${r.sha}\trefs/heads/forge-salvage/7-${r.name}`).join("\n");
+    if (a[0] === "log") return String(refs.find((r) => r.sha === a[3])?.ct ?? "");
+    if (a[0] === "merge-base") {
+      if (a[2].startsWith("origin/") ? ahead.includes(a[3]) : behind.includes(a[2])) return "";
+      throw new Error("not an ancestor");
+    }
+    return "";
+  };
+  return { io: { git }, calls };
+};
+const pick = (w, hasBranch) => pickSalvage({ io: w.io, cwd: ".", issue: 7, branch: "b", hasBranch });
+
+describe("pickSalvage (#5063)", () => {
+  it("no salvage refs: null", async () => assert.equal(await pick(world(), false), null));
+  it("newest by commit time, not by sha suffix", async () => {
+    const w = world({ refs: [{ sha: "f", name: "ffff", ct: 10 }, { sha: "a", name: "aaaa", ct: 20 }] });
+    assert.equal((await pick(w, false)).ref, "refs/heads/forge-salvage/7-aaaa");
+  });
+  it("branch exists: a salvage ref strictly ahead of it is picked", async () => {
+    const w = world({ refs: [{ sha: "a", name: "aaaa", ct: 20 }], ahead: ["a"] });
+    assert.equal((await pick(w, true)).ref, "refs/heads/forge-salvage/7-aaaa");
+  });
+  it("branch exists: behind or diverged refs are ignored, an older usable one is kept", async () => {
+    const w = world({ refs: [{ sha: "n", name: "new", ct: 30 }, { sha: "b", name: "behind", ct: 20 }, { sha: "o", name: "old", ct: 10 }], ahead: ["o"], behind: ["b"] });
+    assert.equal((await pick(w, true)).ref, "refs/heads/forge-salvage/7-old");
+    assert.equal(await pick(world({ refs: [{ sha: "d", name: "div", ct: 5 }] }), true), null);
+  });
+  it("branch exists: the lane branch is fetched before the ancestry check (release #5068 BUG-2)", async () => {
+    const w = world({ refs: [{ sha: "a", name: "aaaa", ct: 20 }], ahead: ["a"] });
+    await pick(w, true);
+    const fetchAt = w.calls.findIndex((a) => a[0] === "fetch" && a.includes("+refs/heads/b:refs/remotes/origin/b"));
+    const baseAt = w.calls.findIndex((a) => a[0] === "merge-base");
+    assert.ok(fetchAt >= 0 && fetchAt < baseAt, JSON.stringify(w.calls));
+  });
+  it("no lane branch: the lane branch is not fetched", async () => {
+    const w = world({ refs: [{ sha: "a", name: "aaaa", ct: 20 }] });
+    await pick(w, false);
+    assert.ok(!w.calls.some((a) => a[0] === "fetch" && a.includes("+refs/heads/b:refs/remotes/origin/b")));
+  });
+});

package/docs/CONFIG.md

@@ -472,7 +472,7 @@ orchestration:
 
 ## `decisions` (OPTIONAL)
 
-Decision engine (#4766, see [DECISIONS.md](DECISIONS.md)). **Not yet wired:** nothing calls `settle` in production, so `mode` (including `live`), `veto_hours` and `reversal_max` have no effect today; `policy` and `human_only` are read by prodwatch and issue-watch (`loadPolicy`) only. The parser has one nesting level and no arrays, so lists are comma-separated.
+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.
 
 | Key | Type | Description |
 |---|---|---|
@@ -718,6 +718,8 @@ issue_watch:
 | `parallel` | integer | No | K of the batch in `batch` mode. Default 4. |
 | `include_followups` | string | No | `none` (default) or `defer-only`. |
 | `postdeploy_rollup` | issue number | No | Release issue that collects post-deploy-only follow-ups as checklist lines. |
+| `sweep_needs_human` | boolean | No | Also settle `needs-human` escalations that predate the watch (the backlog). Default false; `forgedock issue-watch run --dry-run` classifies them first and writes nothing. |
+| `max_launches` | integer | No | Total lane launches (claims plus requeues by the decision engine); at N the watch drains. Default: none. Decision-stage issues also count against `max_issues`. |
 | `threshold` | map | release | `{ min_issues, min_score, max_age_days }`; any one fires a release. |
 | `immediate` | list | release | `label:<name>` or `priority:P0..P3` entries that cut a release now with only their theme. |
 | `max_release_issues` | integer | release | Cap on a release set, closure included. Default 40. |

package/docs/DECISIONS.md

@@ -1,8 +1,6 @@
 # Decision engine (#4766)
 
-> **Status: not yet wired.** No production code calls `settle` yet: the issue-watch stage does not run it, so `decisions.mode`
-> (including `live`), `veto_hours` and `reversal_max` have no effect and no `decision_engine` telemetry is emitted. Only the policy
-> and authority-matrix reads (`loadPolicy`) are used today, by prodwatch and issue-watch. The flow below describes the intended behaviour.
+> **Status: wired (#4793).** The issue-watch stage runs `settle` each round for the open `needs-human` issues that match the watch's selectors.
 
 Settles a lane's decision-only `needs-human` escalation against the target repo's own north star instead of parking it.
 Only external actions stay with a human. Code: `bin/lean/decision-engine.mjs`. Config: [`decisions:`](CONFIG.md).
@@ -30,7 +28,20 @@ Only external actions stay with a human. Code: `bin/lean/decision-engine.mjs`. C
 `decision_engine` telemetry ([TELEMETRY.md](TELEMETRY.md)): decided, escalated, vetoed, reversed, needs-human before/after. A reversal rate above
 `reversal_max` turns the engine back to shadow. The batch report lists every decision under `decided`.
 
-## Not in this module
-
-The `issue-watch` stage that lists `needs-human` issues and calls `settle` (`sweep_needs_human`, `--dry-run` via `classify`, caps, status counts)
-did not land with #4765 (merged without the sweep); a follow-up issue tracks it. Running a declared monitor query for `evidence` and folding `post-deploy` items into the release checklist are follow-ups.
+## The issue-watch stage
+
+`bin/lean/issuewatch-decisions.mjs` runs inside `forgedock issue-watch` (every mode), not as a separate entry point. It is active when `decisions.mode: live`
+or the watch sets `sweep_needs_human: true`. `decisions.mode: live` is a repo setting, so it activates the stage in every watch of the repo (also watches that never opted in); set it only when each watch's selectors are meant to settle `needs-human` issues. Each round it lists open `needs-human` issues of trusted authors that match the watch selectors, takes the newest
+`FORGE:NEEDS_HUMAN` comment (its comment id is the escalation id `settle` is idempotent on) and the typed `terminalCode` from `FORGE:STATE`, and calls `settle`.
+
+- **Backlog.** An escalation older than the watch start is only touched by a watch with `sweep_needs_human: true`. `forgedock issue-watch run --dry-run` prints the `classify` result for every escalation (backlog marked) and writes nothing.
+- **Caps.** Each handled issue counts against `max_issues`; each requeue (a live decision or an evidence hand-off) against `max_launches`, which also stops the watch claiming past it.
+- **Status.** `issue-watch status` gains `needs-human decisions: decided N  evidence-gathered N  folded N  external-kept N`.
+- **Evidence.** A block of "missing read-only production data" on a repo whose forge.yaml declares `prod_watch.sources` clears `needs-human` and goes back to a lane with a comment naming the prod monitor capability (placement `prod_monitor`); without a declared source it keeps the label.
+- **Post-deploy only.** Folded into the watch's `postdeploy_rollup` checklist, `needs-human` cleared and the issue closed; without a rollup it is kept.
+- **Shadow.** Only live mode acts: in shadow (the default) a post-deploy-only or evidence escalation posts a `FORGE:DECISION (shadow)` comment and changes nothing (no fold, close, label change or launch).
+- **Relaunch.** A live decision or evidence hand-off clears `needs-human` and launches the issue through the watcher's own lane launch (per-issue watches); batch and release watches re-select it on the next round.
+- **Trust.** Only `FORGE:NEEDS_HUMAN` and `FORGE:STATE` comments from OWNER/MEMBER/COLLABORATOR or the engine's own logins (`ownLogins`; the ForgeDock App posts as CONTRIBUTOR) count, never other CONTRIBUTORs.
+- **Failures.** A judge or gh failure is not recorded as handled: the escalation is retried for up to three rounds. The judge call has a 2 minute timeout, and a round makes at most 20 judge calls even when `max_issues` is unset; the rest wait for the next round.
+- **Veto.** A `forge:decision-veto` label or a `veto` reply inside `veto_hours` reverts a live decision (`revertVeto`) and counts toward the reversal rate that forces shadow.
+- The judge is the only LLM call (`claude --print` in the real io).

package/docs/RELEASE-NOTES.md

@@ -4,6 +4,7 @@ Operator-facing notes for behavior changes that need action or awareness. Newest
 
 ## Unreleased: `forgedock selftest`, opt-in release gate and nightly run; gate-marker check ignored
 
+- **Pre-deploy check, needs-human decision stage (#4793):** `decisions.mode: live` in forge.yaml now turns on the issue-watch decision stage in every watch of the repo, not only watches that set `sweep_needs_human`. Before upgrading, confirm each watch's selectors should settle `needs-human` issues, or leave `decisions.mode` at `shadow` (shadow only comments). Escalations are read only from OWNER/MEMBER/COLLABORATOR or the engine's own logins, with at most 20 judge calls per round. See [DECISIONS.md](DECISIONS.md).
 - **New command** `forgedock selftest [--static] | --live [--repo <owner/sandbox>] [--pr N]`. It runs a live contract harness against a disposable sandbox repo, plus a static check of every `gh --json` field list. See [SELFTEST.md](SELFTEST.md).
 - **Opt-in nightly run:** `selftest.nightly_interval_hours` makes the schedd daemon start a detached live selftest on that schedule and file one issue on failure. Restart schedd after upgrading to pick it up.
 - **Gate-marker check ignored:** the `Check for FORGE gate markers` check is no longer read as a CI failure by `review-staging`, `/review-pr-staging` or `/deploy-pr`. It only echoes the latest gate marker, so after a GATE_FAILURE it blocked its own GATE_PASS (#4941).

package/package.json

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