forgedock 1.37.0 → 1.38.1

package/bin/lean/decision-engine.mjs

@@ -0,0 +1,217 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * #4766: north-star decision engine. Settles a lane's decision-only `needs-human` escalation from the target repo's own
+ * policy file (forge.yaml `decisions.policy`, default NORTHSTAR.md, then CLAUDE.md, AGENTS.md) and the anchored decisions
+ * register (#4695); external actions (the authority matrix, `decisions.human_only`) stay with a human.
+ *
+ * Deterministic first: `loadPolicy` and `splitEscalation` are pure facts (terminal code, block type, matrix hints). The only
+ * judgment is one injected `judge()` call per decision part. A one-way, low-confidence or clause-less answer escalates with the
+ * analysis attached, never a guess. Shadow mode (the default) posts `FORGE:DECISION (shadow)` and keeps the label; live mode
+ * records the decision, clears needs-human and requeues. A veto (`forge:decision-veto` label, or a reply within
+ * `veto_hours`) reverts it; a reversal rate above `reversal_max` forces shadow. Never throws: an error is an `error` row.
+ * The issue-watch stage (#4765) calls `settle` once per escalation (key: the escalation comment id).
+ */
+import { parseForgeYaml } from "../forge-utils.mjs";
+import { foldDecisions, recordDecisions as recordToRegister } from "./decisions.mjs";
+
+export const VETO_LABEL = "forge:decision-veto";
+export const NEEDS_HUMAN_LABEL = "needs-human";
+export const POLICY_FALLBACKS = ["NORTHSTAR.md", "CLAUDE.md", "AGENTS.md"];
+export const VETO_HOURS_DEFAULT = 24;
+export const REVERSAL_MAX_DEFAULT = 0.2;
+export const REVERSAL_MIN_SAMPLE = 5;
+const PARTS_MAX = 5;
+const POLICY_TEXT_MAX = 12000;
+
+/** The authority matrix: typed classes with built-in match hints (a forge.yaml `hint_<class>` list replaces them). */
+export const DEFAULT_CLASSES = {
+  spend: /\b(spend|spending|paid|purchase|billing|invoice|budget increase|buy)\b/i,
+  credentials: /\b(credentials?|secrets?|api[ _-]?keys?|passwords?|tokens?|oauth)\b/i,
+  "external-publish": /\b(publish|npm publish|public announcement|tweet|press release)\b/i,
+  "customer-send": /\b(customer[- ]facing|customer sends?|newsletter)\b|\b(send|e?mail|notify|message)\b[^.\n]{0,40}\bcustomers?\b/i,
+  "prod-write": /\b(production (write|database|db|data change)|prod write|as root|\broot\b|sudo)\b/i,
+  promotion: /\b(promot(e|ion)|staging\s*(→|->|to)\s*main|release to (production|main))\b/i,
+  legal: /\b(legal|licen[cs]e change|gdpr|terms of service|contract signature)\b/i,
+};
+
+const csv = (v) => String(v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+const hintRe = (words) => new RegExp(`\\b(${words.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b`, "i");
+
+/**
+ * The decisions policy of a repo: `{policyPath, policyText, mode, matrix:[{class, re}], vetoHours, reversalMax, warnings}`.
+ * forge.yaml keys (one nesting level, comma lists): `decisions:` `policy`, `mode` (shadow|live, default shadow),
+ * `human_only` (class names, default all of DEFAULT_CLASSES), `hint_<class>` (match words), `veto_hours`, `reversal_max`.
+ * `io.readFile(path)` returns the text or throws.
+ */
+export function loadPolicy({ io, cwd = "." } = {}) {
+  const read = (p) => { try { return String(io.readFile(`${cwd}/${p}`)); } catch { return null; } };
+  const warnings = [];
+  const raw = read("forge.yaml");
+  let d = {};
+  if (raw != null) { try { d = parseForgeYaml(raw)?.decisions; } catch { d = {}; } }
+  d = d && typeof d === "object" ? d : {};
+  let policyPath = null, policyText = "";
+  for (const p of [String(d.policy ?? "").trim(), ...POLICY_FALLBACKS].filter(Boolean)) {
+    const t = read(p);
+    if (t != null) { policyPath = p; policyText = t.slice(0, POLICY_TEXT_MAX); break; }
+    if (p === String(d.policy ?? "").trim()) warnings.push(`decisions.policy ${p} not readable`);
+  }
+  const names = csv(d.human_only).length ? csv(d.human_only) : Object.keys(DEFAULT_CLASSES);
+  const matrix = [];
+  for (const name of names) {
+    const own = csv(d[`hint_${name}`]);
+    if (own.length) matrix.push({ class: name, re: hintRe(own) });
+    else if (DEFAULT_CLASSES[name]) matrix.push({ class: name, re: DEFAULT_CLASSES[name] });
+    else warnings.push(`human_only class ${name} has no hint_${name} and is not built in: dropped`);
+  }
+  const hours = Number(d.veto_hours), rev = Number(d.reversal_max);
+  return {
+    policyPath, policyText, matrix, warnings,
+    mode: d.mode === "live" ? "live" : "shadow",
+    vetoHours: Number.isFinite(hours) && hours >= 0 ? hours : VETO_HOURS_DEFAULT,
+    reversalMax: Number.isFinite(rev) && rev >= 0 && rev <= 1 ? rev : REVERSAL_MAX_DEFAULT,
+  };
+}
+
+const EVIDENCE_RE = /\b(missing|needs?|requires?|no)\b[^.\n]{0,60}\bread[- ]only\b[^.\n]{0,40}\b(prod|production)\b|\bread[- ]only (prod|production) data\b/i;
+const POSTDEPLOY_RE = /\b(all (remaining )?(items|checks|criteria) (are|is) post[- ]deploy|post[- ]deploy[- ]only)\b/i;
+
+/**
+ * Splits an escalation into decision and external parts from facts. `{terminalCode, blockType, text}`, `matrix` from
+ * loadPolicy, `retryable` a set of codes recovery owns. Returns `{kind, decisions:[text], external:[{class, text}]}` with
+ * kind `recovery | evidence | post-deploy | external | decision | mixed`.
+ */
+export function splitEscalation({ terminalCode = null, blockType = null, text = "" } = {}, matrix = [], { retryable = [] } = {}) {
+  const body = String(text ?? "");
+  const out = (kind, decisions = [], external = []) => ({ kind, decisions, external });
+  if (terminalCode && new Set(retryable).has(terminalCode)) return out("recovery");
+  if (terminalCode === "conformance.unimplemented" || EVIDENCE_RE.test(body)) return out("evidence");
+  if (POSTDEPLOY_RE.test(body)) return out("post-deploy");
+  const klass = (t) => matrix.find((m) => m.re.test(t))?.class ?? null;
+  if (blockType === "credentials" && matrix.some((m) => m.class === "credentials")) return out("external", [], [{ class: "credentials", text: body.slice(0, 200) }]);
+  const lines = body.split("\n").map((l) => l.replace(/^\s*(?:[-*]|\d+[.)])\s+/, "").trim()).filter(Boolean);
+  const bulleted = body.split("\n").some((l) => /^\s*(?:[-*]|\d+[.)])\s+/.test(l));
+  const parts = bulleted ? lines : [body.trim()].filter(Boolean);
+  const decisions = [], external = [];
+  for (const p of parts) { const c = klass(p); if (c) external.push({ class: c, text: p.slice(0, 200) }); else decisions.push(p.slice(0, 400)); }
+  return out(external.length && decisions.length ? "mixed" : external.length ? "external" : "decision", decisions.slice(0, PARTS_MAX), external);
+}
+
+/** A judge answer that may be applied: a clause, reversible, not low confidence. Otherwise the reason it must escalate. */
+export function admissible(a) {
+  if (!a || typeof a !== "object") return { ok: false, why: "no answer" };
+  if (!String(a.choice ?? "").trim()) return { ok: false, why: "no choice" };
+  if (!String(a.clause ?? "").trim()) return { ok: false, why: "no applicable policy clause or precedent" };
+  if (a.reversibility !== "reversible") return { ok: false, why: `${a.reversibility ?? "unknown"} reversibility (only reversible decisions are settled)` };
+  if (!["high", "medium"].includes(a.confidence)) return { ok: false, why: `${a.confidence ?? "no"} confidence` };
+  return { ok: true, why: "" };
+}
+
+/**
+ * Whether a settled decision was vetoed: the `forge:decision-veto` label, or a comment after `decidedAt` (ms) within
+ * `vetoHours` whose first word is `veto`. `comments` is `[{body, createdAt}]`.
+ */
+export function isVetoed({ labels = [], comments = [], decidedAt = 0, vetoHours = VETO_HOURS_DEFAULT, now = Date.now() } = {}) {
+  if ((labels ?? []).includes(VETO_LABEL)) return true;
+  const end = decidedAt + vetoHours * 3600_000;
+  return (comments ?? []).some((c) => {
+    const t = Date.parse(c?.createdAt);
+    return Number.isFinite(t) && t > decidedAt && t <= Math.min(end, now) && /^\s*\/?veto\b/i.test(String(c?.body ?? ""));
+  });
+}
+
+/** Mode in force: a reversal rate above the cap (with a minimum sample) turns live back to shadow. */
+export function effectiveMode(policy, { decided = 0, reversed = 0 } = {}) {
+  if (policy.mode !== "live") return { mode: "shadow", gated: false };
+  const rate = decided >= REVERSAL_MIN_SAMPLE ? reversed / decided : 0;
+  return rate > policy.reversalMax ? { mode: "shadow", gated: true, rate } : { mode: "live", gated: false, rate };
+}
+
+/** Counts for the watcher status and telemetry from settle rows. */
+export function tally(rows) {
+  const t = { decided: 0, evidence: 0, folded: 0, external_kept: 0, escalated: 0, vetoed: 0, shadow: 0 };
+  for (const r of rows ?? []) {
+    if (r?.action === "decided") t.decided++;
+    else if (r?.action === "shadow") t.shadow++;
+    else if (r?.action === "escalated") t.escalated++;
+    else if (r?.action === "vetoed") t.vetoed++;
+    else if (r?.action === "evidence-needed") t.evidence++;
+    else if (r?.action === "post-deploy-only") t.folded++;
+    else if (r?.action === "external" || r?.kept) t.external_kept++;
+  }
+  return t;
+}
+
+const oneLine = (v, n = 300) => String(v ?? "").replace(/\s+/g, " ").trim().slice(0, n);
+const render = (a, policy) => `**What**: ${oneLine(a.choice)}\n**Clause**: ${oneLine(a.clause)} (${policy.policyPath ?? "no policy file"})\n**Rejected**: ${oneLine(a.rejected) || "-"}\n**Reversibility**: ${a.reversibility ?? "-"}\n**Confidence**: ${a.confidence ?? "-"}`;
+
+/** Classification only (`--dry-run`): what `settle` would do, no judge call and no write. */
+export function classify(item, policy, opts = {}) {
+  const s = splitEscalation(item, policy.matrix, opts);
+  return { issue: item.issue, escalationId: item.escalationId ?? null, kind: s.kind, decisions: s.decisions.length, external: s.external.map((e) => e.class) };
+}
+
+/**
+ * Settles one escalation. `item`: `{issue, repo, escalationId, text, terminalCode, blockType, options, anchors, comments}`;
+ * `deps`: `{judge, post(marker, body, issue), setLabels({issue, add, remove}), requeue(issue), records, stats, emit}`.
+ * Idempotent on `escalationId` (a prior engine comment carries `Escalation: <id>`). Returns one row, never throws.
+ */
+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 s = splitEscalation(item, policy.matrix, opts);
+    row.kind = s.kind;
+    if (s.kind === "recovery") return { ...row, reason: "recovery owns this code" };
+    if (s.kind === "external") return { ...row, action: "external", kept: true, class: s.external[0]?.class, reason: `skip: external (${s.external[0]?.class})` };
+    if (s.kind === "evidence") return { ...row, action: "evidence-needed" };
+    if (s.kind === "post-deploy") return { ...row, action: "post-deploy-only" };
+    const key = `Escalation: ${item.escalationId ?? "-"}`;
+    const precedent = foldDecisions(deps.records ?? []).filter((d) => d.status !== "superseded");
+    const answers = [];
+    for (const part of s.decisions) {
+      const a = await deps.judge({ issue: item.issue, decision: part, options: item.options ?? [], policy: policy.policyText, policyPath: policy.policyPath, precedent });
+      const v = admissible(a);
+      if (!v.ok) {
+        await deps.post("FORGE:DECISION (escalated)", `## Escalated, not decided\n${key}\n**Part**: ${oneLine(part)}\n**Why**: ${v.why}\n${a?.choice ? `**Analysis**: leaning ${oneLine(a.choice)}\n` : ""}needs-human is kept.`, item.issue);
+        deps.emit?.({ event: "DECISION_ENGINE", issue: item.issue, decided: 0, escalated: 1, vetoed: 0, mode: policy.mode });
+        return { ...row, action: "escalated", reason: v.why };
+      }
+      answers.push(a);
+    }
+    const { mode, gated } = effectiveMode(policy, deps.stats ?? {});
+    const body = answers.map((a, i) => `### Decision ${i + 1}\n${render(a, policy)}`).join("\n\n");
+    if (mode === "shadow") {
+      await deps.post("FORGE:DECISION (shadow)", `## Decision (shadow${gated ? ", reversal rate above cap" : ""})\n${key}\n${body}\n\nWould clear needs-human and requeue; the label is kept.`, item.issue);
+      deps.emit?.({ event: "DECISION_ENGINE", issue: item.issue, decided: 0, escalated: 0, vetoed: 0, mode: "shadow" });
+      return { ...row, action: "shadow", gated };
+    }
+    await deps.post("FORGE:DECISION", `## Decision\n${key}\n${body}${s.external.length ? `\n\nExternal part stays needs-human: ${s.external.map((e) => e.class).join(", ")}.` : ""}`, item.issue);
+    const anchors = item.anchors ?? [];
+    const registered = anchors.length ? await (deps.recordDecisions ?? recordToRegister)(answers.map((a) => ({ choice: a.choice, why: a.clause, anchors: a.anchors?.length ? a.anchors : anchors })), { issue: item.issue, repo: item.repo, post: deps.post }) : [];
+    if (s.external.length) { // mixed: the decision part is settled, the external part keeps the label
+      deps.emit?.({ event: "DECISION_ENGINE", issue: item.issue, decided: answers.length, escalated: 0, vetoed: 0, mode: "live" });
+      return { ...row, action: "decided", kept: true, choice: answers[0].choice, registered: registered.length };
+    }
+    await deps.setLabels({ issue: item.issue, remove: [NEEDS_HUMAN_LABEL] });
+    await deps.requeue(item.issue);
+    deps.emit?.({ event: "DECISION_ENGINE", issue: item.issue, decided: answers.length, escalated: 0, vetoed: 0, mode: "live" });
+    return { ...row, action: "decided", choice: answers[0].choice, registered: registered.length };
+  } catch (e) {
+    return { ...row, action: "error", reason: oneLine(e?.message) };
+  }
+}
+
+/** Reverts a vetoed live decision: needs-human back, the requeue undone, the veto label cleared. One row, never throws. */
+export async function revertVeto(item, deps = {}) {
+  try {
+    await deps.setLabels({ issue: item.issue, add: [NEEDS_HUMAN_LABEL], remove: [VETO_LABEL] });
+    await deps.unrequeue?.(item.issue);
+    await deps.post("FORGE:DECISION (vetoed)", `## Decision vetoed\nEscalation: ${item.escalationId ?? "-"}\nThe owner vetoed the decision: needs-human restored and the requeue reverted.`, item.issue);
+    deps.emit?.({ event: "DECISION_ENGINE", issue: item.issue, decided: 0, escalated: 0, vetoed: 1, reversed: 1 });
+    return { issue: item.issue, action: "vetoed" };
+  } catch (e) {
+    return { issue: item?.issue ?? null, action: "error", reason: oneLine(e?.message) };
+  }
+}

package/bin/lean/decision-engine.test.mjs

@@ -0,0 +1,159 @@
+// 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 { loadPolicy, splitEscalation, settle, admissible, isVetoed, effectiveMode, revertVeto, classify, tally, VETO_LABEL } from "./decision-engine.mjs";
+import { mapRecord } from "../engine/telemetry-seam.mjs";
+import { formatOutcomeLists } from "./orchestrate.mjs";
+
+const files = (m) => ({ readFile: (p) => { const k = p.replace(/^\.\//, ""); if (k in m) return m[k]; throw new Error("ENOENT"); } });
+const policy = () => loadPolicy({ io: files({ "NORTHSTAR.md": "# star\n1. cheap first", "forge.yaml": "decisions:\n  mode: live\n" }), cwd: "." });
+const good = { choice: "use option A", clause: "NORTHSTAR 2: cut waste", rejected: "option B", reversibility: "reversible", confidence: "high" };
+
+// Fixtures modelled on the six AlterLab escalations (#37240, #37119, #36969, #36694, #37264, #37276).
+const FIX = {
+  37240: { text: "- Which retry strategy for the sync job?\n- Rotate the production API key (credentials)", terminalCode: "builder.blocked", want: "mixed" },
+  37119: { text: "- Choose the pagination style\n- Send the announcement email to customers", terminalCode: "builder.blocked", want: "mixed" },
+  36969: { text: "- Pick the cache TTL\n- Which naming for the new table", terminalCode: "builder.blocked", want: "decision" },
+  36694: { text: "- Keep the legacy endpoint or drop it?\n- Promote staging to main after the change", terminalCode: "builder.blocked", want: "mixed" },
+  37264: { text: "The check needs read-only production data we do not have.", terminalCode: "conformance.unimplemented", want: "evidence" },
+  37276: { text: "All items are post-deploy: nothing to build before release.", terminalCode: "conformance.deferred", want: "post-deploy" },
+};
+
+test("#4766 loadPolicy: defaults, fallback order, matrix schema", () => {
+  const p = loadPolicy({ io: files({ "AGENTS.md": "a" }) });
+  assert.equal(p.policyPath, "AGENTS.md");
+  assert.equal(p.mode, "shadow");
+  assert.equal(p.vetoHours, 24);
+  assert.deepEqual(p.matrix.map((m) => m.class), ["spend", "credentials", "external-publish", "customer-send", "prod-write", "promotion", "legal"]);
+  const q = loadPolicy({ io: files({ "forge.yaml": "decisions:\n  policy: STAR.md\n  human_only: spend, gdpr, bogus\n  hint_gdpr: gdpr, dpa\n  veto_hours: 6\n  reversal_max: 0.5\n", "STAR.md": "s", "NORTHSTAR.md": "n" }) });
+  assert.equal(q.policyPath, "STAR.md");
+  assert.deepEqual(q.matrix.map((m) => m.class), ["spend", "gdpr"]);
+  assert.ok(q.warnings.some((w) => /bogus/.test(w)));
+  assert.equal(q.vetoHours, 6);
+  assert.equal(q.reversalMax, 0.5);
+  assert.equal(loadPolicy({ io: files({}) }).policyPath, null);
+});
+
+test("#4766 splitEscalation: the six AlterLab fixtures", () => {
+  const { matrix } = policy();
+  for (const [n, f] of Object.entries(FIX)) assert.equal(splitEscalation(f, matrix).kind, f.want, `#${n}`);
+  const s = splitEscalation(FIX[37240], matrix);
+  assert.equal(s.decisions.length, 1);
+  assert.equal(s.external[0].class, "credentials");
+  assert.equal(splitEscalation({ text: "x", terminalCode: "ci.red" }, matrix, { retryable: ["ci.red"] }).kind, "recovery");
+  assert.equal(splitEscalation({ text: "need the token", blockType: "credentials" }, matrix).kind, "external");
+});
+
+test("#4766 admissible: one-way, low confidence and no clause escalate", () => {
+  assert.equal(admissible(good).ok, true);
+  assert.equal(admissible({ ...good, reversibility: "one-way" }).ok, false);
+  assert.equal(admissible({ ...good, confidence: "low" }).ok, false);
+  assert.equal(admissible({ ...good, clause: "" }).ok, false);
+  assert.equal(admissible(null).ok, false);
+});
+
+function harness(over = {}) {
+  const posts = [], labels = [], requeued = [], events = [], registered = [];
+  return {
+    posts, labels, requeued, events, registered,
+    deps: {
+      judge: async () => good,
+      post: async (m, b, i) => { posts.push({ m, b, i }); },
+      setLabels: async (x) => { labels.push(x); },
+      requeue: async (i) => { requeued.push(i); },
+      recordDecisions: async (list) => { registered.push(...list); return list; },
+      emit: (r) => events.push(r), ...over,
+    },
+  };
+}
+const item = (n, extra = {}) => ({ issue: n, repo: "o/r", escalationId: `c${n}`, anchors: ["bin/x.mjs"], ...FIX[n], ...extra });
+
+test("#4766 shadow posts FORGE:DECISION (shadow), keeps the label, no requeue", async () => {
+  const h = harness();
+  const p = { ...policy(), mode: "shadow" };
+  const r = await settle(item(36969), p, h.deps);
+  assert.equal(r.action, "shadow");
+  assert.equal(h.posts[0].m, "FORGE:DECISION (shadow)");
+  assert.deepEqual([h.labels, h.requeued, h.registered], [[], [], []]);
+});
+
+test("#4766 live clears needs-human, requeues, writes the register", async () => {
+  const h = harness();
+  const r = await settle(item(36969), policy(), h.deps);
+  assert.equal(r.action, "decided");
+  assert.deepEqual(h.labels, [{ issue: 36969, remove: ["needs-human"] }]);
+  assert.deepEqual(h.requeued, [36969]);
+  assert.equal(h.registered.length, 2);
+  assert.equal(h.events[0].decided, 2);
+  assert.match(h.posts[0].b, /Escalation: c36969/);
+});
+
+test("#4766 mixed keeps needs-human; external-only untouched; evidence and post-deploy only classified", async () => {
+  const h = harness();
+  const m = await settle(item(37240), policy(), h.deps);
+  assert.equal(m.action, "decided");
+  assert.equal(m.kept, true);
+  assert.deepEqual([h.labels, h.requeued], [[], []]);
+  const e = await settle({ issue: 1, text: "rotate the credentials", escalationId: "x" }, policy(), h.deps);
+  assert.equal(e.action, "external");
+  assert.equal(e.reason, "skip: external (credentials)");
+  assert.equal((await settle(item(37264), policy(), h.deps)).action, "evidence-needed");
+  assert.equal((await settle(item(37276), policy(), h.deps)).action, "post-deploy-only");
+  assert.deepEqual(classify(item(37240), policy()), { issue: 37240, escalationId: "c37240", kind: "mixed", decisions: 1, external: ["credentials"] });
+});
+
+test("#4766 an inadmissible answer escalates with analysis and never changes labels", async () => {
+  const h = harness({ judge: async () => ({ ...good, reversibility: "one-way" }) });
+  const r = await settle(item(36969), policy(), h.deps);
+  assert.equal(r.action, "escalated");
+  assert.match(h.posts[0].b, /one-way/);
+  assert.deepEqual([h.labels, h.requeued], [[], []]);
+});
+
+test("#4766 idempotent on the escalation comment id; errors become rows", async () => {
+  const h = harness();
+  const seen = [{ body: "<!-- FORGE:DECISION -->\nEscalation: c36969" }];
+  assert.equal((await settle(item(36969, { comments: seen }), policy(), h.deps)).action, "skipped");
+  assert.equal(h.posts.length, 0);
+  const bad = harness({ post: async () => { throw new Error("boom"); } });
+  assert.equal((await settle(item(36969), policy(), bad.deps)).action, "error");
+});
+
+test("#4766 veto: label or reply within the window; revertVeto restores needs-human", async () => {
+  const t0 = Date.parse("2026-10-30T00:00:00Z");
+  assert.equal(isVetoed({ labels: [VETO_LABEL] }), true);
+  const c = (h, body) => ({ body, createdAt: new Date(t0 + h * 3600_000).toISOString() });
+  const base = { decidedAt: t0, vetoHours: 24, now: t0 + 48 * 3600_000 };
+  assert.equal(isVetoed({ ...base, comments: [c(2, "veto: wrong")] }), true);
+  assert.equal(isVetoed({ ...base, comments: [c(30, "veto")] }), false);
+  assert.equal(isVetoed({ ...base, comments: [c(2, "looks good")] }), false);
+  const h = harness({ unrequeue: async (i) => h.requeued.push(`un${i}`) });
+  const r = await revertVeto({ issue: 5, escalationId: "c5" }, h.deps);
+  assert.equal(r.action, "vetoed");
+  assert.deepEqual(h.labels, [{ issue: 5, add: ["needs-human"], remove: [VETO_LABEL] }]);
+  assert.deepEqual(h.requeued, ["un5"]);
+  assert.equal(h.events[0].reversed, 1);
+});
+
+test("#4766 a reversal rate above the cap forces shadow", async () => {
+  const p = policy();
+  assert.equal(effectiveMode(p, { decided: 10, reversed: 1 }).mode, "live");
+  assert.equal(effectiveMode(p, { decided: 10, reversed: 5 }).mode, "shadow");
+  assert.equal(effectiveMode(p, { decided: 2, reversed: 2 }).mode, "live");
+  const h = harness();
+  const r = await settle(item(36969), p, { ...h.deps, stats: { decided: 10, reversed: 5 } });
+  assert.equal(r.action, "shadow");
+  assert.equal(r.gated, true);
+});
+
+test("#4766 tally, telemetry mapping and the batch report 'decided' section", () => {
+  assert.deepEqual(tally([{ action: "decided" }, { action: "shadow" }, { action: "escalated" }, { action: "external" }, { action: "evidence-needed" }, { action: "post-deploy-only" }]),
+    { decided: 1, evidence: 1, folded: 1, external_kept: 1, escalated: 1, vetoed: 0, shadow: 1 });
+  const m = mapRecord({ event: "DECISION_ENGINE", issue: 1, decided: 2, escalated: 0, vetoed: 1, reversed: 1, mode: "live" }, 0);
+  assert.equal(m.event, "decision_engine");
+  assert.deepEqual(m.payload, { decided: 2, escalated: 0, vetoed: 1, reversed: 1, mode: "live" });
+  const lines = formatOutcomeLists([{ issue: 7, outcome: "merged", decided: { choice: "use option A" } }]);
+  assert.match(lines.join("\n"), /decided .*\n- #7: use option A/);
+  assert.deepEqual(formatOutcomeLists([{ issue: 7, outcome: "merged" }]), []);
+});

package/bin/lean/effects.mjs

@@ -8,8 +8,8 @@ import { homedir, hostname, freemem, loadavg, cpus, tmpdir } from "node:os";
 import { promises as fsp } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { runCliBackendAsync, resolveClaudeCliBinary, getClaudeCliCapabilities, buildLeanSessionFlags, buildReadOnlyToolFlags } from "../runner.mjs";
-import { makeIo } from "../engine-cli.mjs";
+import { runCliBackendAsync, resolveClaudeCliBinary, getClaudeCliCapabilities, buildLeanSessionFlags, buildReadOnlyToolFlags, sanitizeCliModel } from "../runner.mjs";
+import { makeIo, readSubagentModel } from "../engine-cli.mjs";
 import { makeProjector } from "../engine/projector.mjs";
 import { makeLedger, countLiveLanes, ledgerRoot } from "./ledger.mjs";
 import { makeDepCache } from "./depcache.mjs";
@@ -18,7 +18,7 @@ import { gatherContextFacts } from "./context.mjs";
 import { makePitfallStore } from "./pitfalls.mjs";
 import { enumeratingTests, missingEntries } from "./enumerating.mjs";
 import { resolveBaseConflicts } from "./conflictres.mjs";
-import { sequenceCollisions, snapshotLane, verifyRenumber, renumberLane, resolveSequenceConflicts, generatorProblems, journalOrderProblems } from "./sequence.mjs";
+import { seqNumber, sequenceCollisions, snapshotLane, verifyRenumber, renumberLane, resolveSequenceConflicts, generatorProblems, journalOrderProblems } from "./sequence.mjs";
 import { duplicateExports } from "./postmerge.mjs";
 import { englishCopies } from "./i18n.mjs";
 import { scopedChecks } from "./checks.mjs";
@@ -76,21 +76,39 @@ export const noToolFlags = (caps) => (caps?.strictMcp ? ["--tools", ""]
 
 /** #4456: `--settings` registering the re-read nudge (bin/hooks/reread-nudge.mjs) as a PostToolUse hook on Read and Bash. */
 export const REREAD_HOOK = fileURLToPath(new URL("../hooks/reread-nudge.mjs", import.meta.url));
-export const rereadNudgeFlags = (node = process.execPath, hook = REREAD_HOOK) => {
+export const rereadHooks = (node = process.execPath, hook = REREAD_HOOK) => {
   const hooks = [{ type: "command", command: `${JSON.stringify(node)} ${JSON.stringify(hook)}` }];
   // #4580: the same script denies a full-file Read of an unchanged path already read twice (PreToolUse)
-  return ["--settings", JSON.stringify({ hooks: { PostToolUse: [{ matcher: "Read|Bash", hooks }], PreToolUse: [{ matcher: "Read", hooks }] } })];
+  return { PostToolUse: [{ matcher: "Read|Bash", hooks }], PreToolUse: [{ matcher: "Read", hooks }] };
 };
+export const rereadNudgeFlags = (node = process.execPath, hook = REREAD_HOOK) => ["--settings", JSON.stringify({ hooks: rereadHooks(node, hook) })];
 
-export function makeLeanRunner({ runCli = runCliBackendAsync, probe = systemdRunAvailable } = {}) {
+/**
+ * #4843: ForgeDock owns the subagent model of the sessions it launches. An operator settings.json `env` such as
+ * CLAUDE_CODE_SUBAGENT_MODEL=sonnet + _FORCE=1 would otherwise override every subagent, the #4391 Haiku explorer
+ * included, and a child env var cannot undo it (settings env wins); a `--settings` flag does. FORCE=0 lets a
+ * ForgeDock-defined agent's own `model` win. CLAUDE_CODE_SUBAGENT_MODEL (the default for agents without one) is
+ * set only from forge.yaml `agents.subagent_model`; unset leaves the operator's own default alone (#4849).
+ */
+export const ownedModelEnv = (subagentModel = null) => {
+  const m = sanitizeCliModel(subagentModel);
+  return { ...(m ? { CLAUDE_CODE_SUBAGENT_MODEL: m } : {}), CLAUDE_CODE_SUBAGENT_MODEL_FORCE: "0" };
+};
+/** The one `--settings` of a lean session: the owned model env, plus the re-read hooks for builder sessions (#4456). */
+export const leanSettingsFlags = ({ subagentModel = null, reread = false } = {}) =>
+  ["--settings", JSON.stringify({ env: ownedModelEnv(subagentModel), ...(reread ? { hooks: rereadHooks() } : {}) })];
+
+export function makeLeanRunner({ runCli = runCliBackendAsync, probe = systemdRunAvailable, subagentModel = null } = {}) {
   return async ({ role, issue, cwd, model, resume, system, prompt, readOnly = false, noTools = false, rereadNudge = false, maxTurns = null, agents = null, env = null, idleMs = 0, maxMs = 0, laneLimits = null, control = null, onSpawn = null, contextMax = 0, turnMax = 0, busy = null, busyMs = 0, onIdleExtend = null }) => {
     const bin = resolveClaudeCliBinary(cwd) || "claude";
     const caps = getClaudeCliCapabilities(cwd);
     // #4391: custom subagents (the explorer) for the builder session; null leaves argv unchanged
-    const flags = [...buildLeanSessionFlags(caps), ...(noTools ? noToolFlags(caps) : readOnly ? buildReadOnlyToolFlags(caps) : []), ...(agents ? ["--agents", JSON.stringify(agents)] : []),
-      ...(rereadNudge && !readOnly && !noTools ? rereadNudgeFlags() : [])]; // #4456: builder sessions only
+    const flags = [...buildLeanSessionFlags(caps), ...(noTools ? noToolFlags(caps) : readOnly ? buildReadOnlyToolFlags(caps) : []), ...(agents ? ["--agents", JSON.stringify(agents)] : [])];
+    // #4843 owned models, in extraArgs so FORGEDOCK_FULL_SESSION=1 (which drops sessionFlags) keeps them (#4848 BUG-1);
+    // #4456 re-read hooks: builder sessions only, and like the other session flags not in a full session
+    const settings = leanSettingsFlags({ subagentModel, reread: rereadNudge && !readOnly && !noTools && process.env.FORGEDOCK_FULL_SESSION !== "1" });
     const r = await runCli({ spec: { name: `core-${role}` }, userMessage: prompt, systemPrompt: resume ? "" : system,
-      args: [String(issue)], cwd, bin, model, maxTurns: caps?.maxTurns ? maxTurns : null, env, sessionFlags: flags, extraArgs: resume ? ["--resume", resume] : [],
+      args: [String(issue)], cwd, bin, model, maxTurns: caps?.maxTurns ? maxTurns : null, env, sessionFlags: flags, extraArgs: [...(resume ? ["--resume", resume] : []), ...settings],
       logger: { log() {} },
       idleMs, maxMs, stream: idleMs > 0, control, onSpawn, busy, busyMs, onIdleExtend, ...(contextMax > 0 ? { contextMax } : {}), ...(turnMax > 0 ? { turnMax } : {}), wrap: probe() ? (b, a) => wrapLaneLimits(b, a, laneLimits) : null });
     // #4395: a resumed session's first turn carries the prior history, so only a fresh session reports a baseline.
@@ -275,12 +293,12 @@ export function makeGhCache({ root = null, tmp = tmpdir() } = {}) {
   };
 }
 
-export function makeLeanIo({ repo }) {
+export function makeLeanIo({ repo, subagentModel = readSubagentModel() }) {
   const base = makeIo();
   const run = (bin) => async (args, opts = {}) => (await pexec(bin, args, { cwd: opts.cwd, maxBuffer: 100 * 1024 * 1024, timeout: 120000, ...(opts.env ? { env: { ...process.env, ...opts.env } } : {}) })).stdout;
   return {
     ghCache: (root) => makeGhCache({ root }),
-    gh: run("gh"), git: run("git"), docker: run("docker"), killGroup: async (pid, marker) => killLedgerPid(pid, marker), ledger: (opts) => makeLedger(opts), runTmp: makeRunTmp(), host: makeHostProbe(), heavy: makeHeavyIo({ host: makeHostProbe() }), projector: makeProjector({ gh: base.gh }), runner: makeLeanRunner(), waitCiGreen: base.waitCiGreen,
+    gh: run("gh"), git: run("git"), docker: run("docker"), killGroup: async (pid, marker) => killLedgerPid(pid, marker), ledger: (opts) => makeLedger(opts), runTmp: makeRunTmp(), host: makeHostProbe(), heavy: makeHeavyIo({ host: makeHostProbe() }), projector: makeProjector({ gh: base.gh }), runner: makeLeanRunner({ subagentModel }), waitCiGreen: base.waitCiGreen,
     /** Shared dependency cache (#4220): the repo's own package manager, argv only, bounded by the cache's timeout. */
     deps: makeDepCache({ exec: async (cmd, args, { cwd, env, timeoutMs } = {}) => String((await pexec(cmd, args, { cwd, env: { ...process.env, ...(env ?? {}) }, timeout: timeoutMs ?? 0, maxBuffer: 100 * 1024 * 1024 })).stdout) }),
     /** Names of the checks the base branch requires: classic protection plus rulesets (#4158). [] when neither has any. */
@@ -389,8 +407,16 @@ export function makeLeanIo({ repo }) {
     sequenceSnapshot: ({ cwd, base }) => snapshotLane({ git: (a) => run("git")(a, { cwd }), base }),
     sequenceVerify: ({ cwd, base, before, moves }) => verifyRenumber({ git: (a) => run("git")(a, { cwd }), base, before, moves }),
     /** #4386: the deterministic renumber, sequence-only base-sync resolution, and the host sequence lease at the merge gate. */
-    sequenceRenumber: ({ cwd, base, laneRef, regenerate, reserve }) => renumberLane({ git: (a) => run("git")(a, { cwd }), base, cwd, laneRef, regenerate, reserve }),
-    sequenceResolve: ({ cwd, files }) => resolveSequenceConflicts({ git: (a) => run("git")(a, { cwd }), files }),
+    sequenceRenumber: ({ cwd, base, laneRef, regenerate, reserve, openNumbers }) => renumberLane({ git: (a) => run("git")(a, { cwd }), base, cwd, laneRef, regenerate, reserve, openNumbers }),
+    sequenceResolve: ({ cwd, files, partial }) => resolveSequenceConflicts({ git: (a) => run("git")(a, { cwd }), files, partial }),
+    /** #4732: numbers the other open PRs on `lane` already carry in `dir` (gh only, no fetch); [] on any failure. */
+    async sequenceOpenNumbers({ cwd, lane, dir }) {
+      try {
+        const me = String(await run("git")(["rev-parse", "--abbrev-ref", "HEAD"], { cwd })).trim();
+        const prs = JSON.parse(await run("gh")(["pr", "list", "--state", "open", "--base", lane, "--limit", "100", "--json", "headRefName,files"], { cwd }));
+        return prs.filter((p) => p?.headRefName !== me).flatMap((p) => (p?.files ?? []).map((f) => String(f?.path ?? ""))).filter((f) => dirname(f) === dir).map((f) => Number(seqNumber(f))).filter(Number.isFinite);
+      } catch { return []; }
+    },
     /** #4588: deterministic base-merge resolution of union / JSON-map / generated files (bin/lean/conflictres.mjs). */
     conflictResolve: ({ cwd, files, cfg }) => resolveBaseConflicts({ git: (a) => run("git")(a, { cwd }), cwd, files, cfg }),
     sequenceLease: makeSequenceLeaseIo(),

package/bin/lean/execution.mjs

@@ -34,9 +34,14 @@
  * orchestrate runs a remote-placed lane locally when `max_remote` or the execution budget is exhausted.
  *
  * Host capabilities (#4542): a lane that needs something only the dispatching host has (the SOPS/age key, scoped ops
- * credentials, read-only prod monitor SSH) is placed local in `remote` and `hybrid` mode, because a sandbox relays none of
- * them (`detectNeeds`, `placeLane` `needs`). forge.yaml `execution.host_capabilities` declares which the host has; a
+ * credentials, read-only prod monitor SSH) is placed local in `remote` and `hybrid` mode unless the provider relays it
+ * (`detectNeeds`, `placeLane` `needs`/`relays`). #4778: a remote provider relays the capabilities of forge.yaml
+ * `execution.relay_commands` (allowlisted read-only wrappers the host runs for the sandbox, relay.mjs). forge.yaml `execution.host_capabilities` declares which the host has; a
  * remote lane that blocks on one of them ends `env.capability_remote` and is recovered locally (`hostCapabilityBlock`).
+ * #4785: needs are read from the body, FORGE:DECISION comments and the frozen contract's validate commands
+ * (`placementText`); a remote lane whose frozen validate commands name a declared one ends before building (`contractHostNeeds`).
+ * #4776: the body is read without its quoted material (comments, code, quotes, evidence sections) and the frozen
+ * `repro_test` command counts like a validate command, so a quoted evidence query no longer pins a lane to the host.
  */
 import { execFile } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
@@ -53,6 +58,8 @@ import { httpTransport, isActionsEndpoint, remoteProvider } from "./sandbox-remo
 import { ADMISSION_DEFAULTS } from "./admission.mjs";
 import { classifyStep, heavyConfig, memAvailableMb } from "./heavy.mjs";
 import { detectPins } from "./toolchain.mjs";
+import { parseContractComment, noComments } from "./render.mjs";
+import { parseRelayCommands } from "./relay.mjs";
 
 export const EXECUTION_MODES = Object.freeze(["local", "remote", "hybrid"]);
 export const SANDBOX_PROVIDERS = Object.freeze(["local", "container", "remote", "pool"]);
@@ -108,9 +115,10 @@ export function parseExecution(sec = {}) {
   const patRaw = Array.isArray(s.host_capability_patterns) ? s.host_capability_patterns : str(s.host_capability_patterns) ? str(s.host_capability_patterns).split(",") : [];
   const hostCapabilityPatterns = patRaw.map((x) => { const t = str(x), i = t.indexOf(":"); return { name: t.slice(0, i).trim().toLowerCase(), pattern: t.slice(i + 1).trim() }; })
     .filter((x) => CAPABILITY_RE.test(x.name) && x.pattern && safeRegExp(x.pattern));
+  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 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 } : {}) };
+  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 } : {}) };
 }
 
 const round1 = (x) => Math.round(x * 10) / 10;
@@ -211,6 +219,66 @@ export function hostCapabilityBlock(summary, caps = null) {
   return named.length && named.every((n) => have.has(n)) ? named : [];
 }
 
+const EVIDENCE_HEADING = /^(#{1,6})\s*(?:evidence|logs?|data|observations?|measurements?|quer(?:y|ies)|samples?|findings?)\b/i;
+
+/**
+ * An issue body without its quoted material (#4776), pure: HTML comments (FORGE:STATE too), fenced code blocks, evidence-like
+ * sections (heading to the next heading of the same or higher level), blockquote lines and inline code spans. What is left is
+ * prose the author wrote as an instruction, not evidence they pasted.
+ */
+function proseOf(body) {
+  const kept = [];
+  let fence = null, skip = 0;
+  for (const line of noComments(body).split("\n")) {
+    const f = /^\s*(`{3,}|~{3,})/.exec(line);
+    if (fence) { if (f && f[1][0] === fence[0] && f[1].length >= fence.length) fence = null; continue; }
+    if (f) { fence = f[1]; continue; }
+    const h = /^(#{1,6})\s/.exec(line);
+    if (h && skip && h[1].length <= skip) skip = 0;
+    if (!skip) { const e = EVIDENCE_HEADING.exec(line); if (e) skip = e[1].length; }
+    if (skip || /^\s*>/.test(line)) continue;
+    kept.push(line.replace(/`[^`\n]*`/g, ""));
+  }
+  return kept.join("\n");
+}
+
+/** The validate and repro_test commands of a frozen contract (#4776). */
+function contractCommands(contract) {
+  const cmds = (Array.isArray(contract?.validate) ? contract.validate : []).map((x) => String(x?.command ?? "")).filter(Boolean);
+  const r = contract?.repro_test;
+  if (r && typeof r === "object" && typeof r.command === "string" && r.command) cmds.push(r.command);
+  return cmds;
+}
+
+/**
+ * The text host-capability placement reads (#4785, #4776), pure: the issue body without quoted material (`proseOf`), every
+ * `<!-- FORGE:DECISION` comment (prose or JSON, unstripped) and the validate and repro_test commands of the last parseable
+ * `<!-- FORGE:CONTRACT -->` comment. `comments` are gh comment objects (`{body}`) or strings; anything else is ignored.
+ */
+export function placementText({ body = "", comments = [] } = {}) {
+  const bodies = (Array.isArray(comments) ? comments : []).map((c) => String((typeof c === "string" ? c : c?.body) ?? "").trimStart());
+  let validate = [];
+  for (const b of bodies) {
+    if (!b.startsWith("<!-- FORGE:CONTRACT -->")) continue;
+    const c = parseContractComment(b)?.contract;
+    if (c && typeof c === "object") validate = contractCommands(c);
+  }
+  return [proseOf(body), ...bodies.filter((b) => b.startsWith("<!-- FORGE:DECISION")), ...validate].join("\n");
+}
+
+/** Declared host capabilities a contract's validate and repro_test commands name (#4785, #4776): `{caps, ids}`, both empty when none. */
+export function contractHostNeeds(contract, caps = null) {
+  const have = new Set(caps?.hostCapabilities ?? []);
+  const ids = [], found = new Set();
+  const rows = (Array.isArray(contract?.validate) ? contract.validate : []).map((v) => [String(v?.id ?? ""), v?.command]);
+  if (typeof contract?.repro_test?.command === "string") rows.push(["repro_test", contract.repro_test.command]);
+  for (const [id, command] of rows) {
+    const named = detectNeeds(command, caps).filter((n) => have.has(n));
+    if (named.length) { ids.push(id); for (const n of named) found.add(n); }
+  }
+  return { caps: [...found].sort(), ids };
+}
+
 const DOCS_LABELS = new Set(["docs", "documentation", "type:docs"]);
 
 /**
@@ -429,7 +497,7 @@ export function providerByName(name, opts) {
   if (name === "remote") {
     const exec = opts?.exec ?? {};
     const env = opts?.env ?? process.env;
-    return remoteProvider({ batch: opts.batch, repo: opts.repo, settings: exec, env, transport: remoteTransportFor(exec, { transport: opts?.transport, env }), ...(opts?.now ? { now: opts.now } : {}) });
+    return remoteProvider({ batch: opts.batch, repo: opts.repo, settings: { ...exec, ...(typeof opts?.prefetch === "function" ? { prefetch: opts.prefetch } : {}) }, env, transport: remoteTransportFor(exec, { transport: opts?.transport, env }), ...(opts?.now ? { now: opts.now } : {}) });
   }
   if (name === "pool") {
     // #4546: `remote` with the endpoint and token defaulted to the local router, and the repo's forge.yaml sent along.
@@ -443,7 +511,8 @@ export function providerByName(name, opts) {
     const tokenEnv = exec.tokenEnv ?? (router?.token ? "FORGEDOCK_POOL_TOKEN" : undefined);
     // #4685: an empty env/keychain lookup of a configured token_env falls back to the router's token file.
     const credentials = (n) => (n === "FORGEDOCK_POOL_TOKEN" && !exec.tokenEnv ? router?.token ?? null : resolveCredential(n, { env }) ?? router?.token ?? null);
-    const settings = { ...exec, ...(exec.endpoint ? {} : router ? { endpoint: router.endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(forgeYaml ? { forgeYaml } : {}) };
+    const settings = { ...exec, ...(exec.endpoint ? {} : router ? { endpoint: router.endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(forgeYaml ? { forgeYaml } : {}),
+      ...(typeof opts?.prefetch === "function" ? { prefetch: opts.prefetch } : {}) }; // #4778: dispatch-time relay pre-fetch
     return remoteProvider({ batch: opts.batch, repo: opts.repo, settings, name: "pool", env, credentials, transport: remoteTransportFor(settings, { transport: opts?.transport, env, credentials }), ...(opts?.now ? { now: opts.now } : {}) });
   }
   const e = new Error(`unknown execution.provider ${JSON.stringify(name)} (known: ${SANDBOX_PROVIDERS.join(", ")})`);