forgedock 1.37.0 → 1.38.1

package/bin/engine/outcome-codes.mjs

@@ -81,6 +81,7 @@ export const OUTCOME_CODES = Object.freeze({
   REVIEW_NO_VERDICT: "review.no_verdict",
   // Core work-on conformance gate (bin/lean/conformance.mjs).
   CONTRACT_INVALID: "contract.invalid",
+  CONTRACT_INVALID_COMMAND: "contract.invalid_command",
   REVIEW_INCOMPLETE: "review.incomplete",
   REVIEW_INCONSISTENT: "review.inconsistent",
   CONFORMANCE_OMISSION: "conformance.omission",
@@ -194,14 +195,14 @@ export function codeForTerminalReason(reason) {
  * Batch recovery classes of a lane result (forge#4267). The batch runner recovers `recoverable` rows once
  * (`orchestration.recovery.max_attempts`) and re-queues them; only `human` rows are escalations.
  */
-export const RECOVERABLE_CODES = Object.freeze([OUTCOME_CODES.CI_RED, OUTCOME_CODES.BASE_CONFLICT, OUTCOME_CODES.BUILDER_BLOCK_UNTYPED, OUTCOME_CODES.CONTRACT_INVALID, OUTCOME_CODES.ENV_TOOL_MISSING, OUTCOME_CODES.ENV_REPRO_UNRUNNABLE, OUTCOME_CODES.ENV_CAPABILITY_REMOTE, OUTCOME_CODES.BUDGET_EXCEEDED]);
+export const RECOVERABLE_CODES = Object.freeze([OUTCOME_CODES.CI_RED, OUTCOME_CODES.BASE_CONFLICT, OUTCOME_CODES.BUILDER_BLOCK_UNTYPED, OUTCOME_CODES.CONTRACT_INVALID, OUTCOME_CODES.CONTRACT_INVALID_COMMAND, OUTCOME_CODES.ENV_TOOL_MISSING, OUTCOME_CODES.ENV_REPRO_UNRUNNABLE, OUTCOME_CODES.ENV_CAPABILITY_REMOTE, OUTCOME_CODES.BUDGET_EXCEEDED]);
 /** `builder.blocked` is only reached by a typed human block: credentials, spend, promotion, customer, product-decision. */
 export const HUMAN_CODES = Object.freeze([OUTCOME_CODES.BUILDER_BLOCKED]);
 
 /**
  * `recoverable` | `human` | `terminal` for a lane result row ({outcome|terminalReason, code, issueEdited?, conflicting?}).
  * Recoverable: needs-human `ci.red`, `base.conflict`, `builder.block_untyped`, `env.tool_missing`, `env.repro_unrunnable`, `env.capability_remote`, `budget.exceeded`, `contract.invalid` after a mid-run issue
- * edit (`issueEdited`), `ci-pending` on a conflicting PR (`conflicting`), and the non-human `budget-exceeded` turn-overrun end (forge#4505). Human: `builder.blocked`. Anything else
+ * edit (`issueEdited`) or when every problem was an unmatched quote (`quoteMismatch`), `ci-pending` on a conflicting PR (`conflicting`), and the non-human `budget-exceeded` turn-overrun end (forge#4505). Human: `builder.blocked`. Anything else
  * (another code, or not a needs-human/ci-pending row) is terminal. Pure, never throws.
  */
 export function classifyNeedsHuman(row, { parked = false } = {}) {
@@ -221,10 +222,18 @@ function classifyNeedsHumanBase(row) {
   if (outcome === "budget-exceeded") return "recoverable";
   if (outcome !== "needs-human") return "terminal";
   if (HUMAN_CODES.includes(row.code)) return "human";
-  if (row.code === OUTCOME_CODES.CONTRACT_INVALID) return row.issueEdited === true ? "recoverable" : "terminal";
+  if (row.code === OUTCOME_CODES.CONTRACT_INVALID) return row.issueEdited === true || row.quoteMismatch === true ? "recoverable" : "terminal";
   return RECOVERABLE_CODES.includes(row.code) ? "recoverable" : "terminal";
 }
 
+/** forge#4725: mechanical/environment codes recover on their own budget (`recovery.mechanicalMaxAttempts`), apart from conformance failures. */
+export const MECHANICAL_CODES = Object.freeze([OUTCOME_CODES.BASE_CONFLICT, OUTCOME_CODES.CONTRACT_INVALID_COMMAND, OUTCOME_CODES.ENV_TOOL_MISSING, OUTCOME_CODES.ENV_REPRO_UNRUNNABLE, OUTCOME_CODES.ENV_CAPABILITY_REMOTE]);
+
+/** `mechanical` | `conformance`: the recovery budget class of a lane result row (a conflicting `ci-pending` is a base conflict). */
+export function recoveryClassOf(row) {
+  return MECHANICAL_CODES.includes(recoveryCodeOf(row)) ? "mechanical" : "conformance";
+}
+
 /** The code a recovery lane works on: a conflicting `ci-pending` is recovered as a base conflict. */
 export function recoveryCodeOf(row) {
   return (row?.outcome ?? row?.terminalReason) === "ci-pending" ? OUTCOME_CODES.BASE_CONFLICT : normalizeCode(row?.code);

package/bin/engine/telemetry-seam.mjs

@@ -8,6 +8,7 @@
  *   RUN_TERMINAL        -> `run_terminal`  (reason, code, wall_ms; lean adds milestone, conformance_mode, shadow_would, the pr and
  *                          builder_tier/class/model/escalated 0|1, forge#4394)
  *   SANDBOX_USAGE       -> `sandbox_usage` (provider, sandbox_id, minutes, cost_usd, batch; one per settled remote lane, forge#4255)
+ *   DECISION_ENGINE     -> `decision_engine` (decided, escalated, vetoed, reversed, mode, needs_human_before/after; forge#4766)
  *   STRUCTURE_DELTA     -> `structure_delta` (edges_added/removed, import_files_added/removed, boundary_changed/loosened 0|1; forge#4159)
  *                          lean's merge-time record (forge#4165) adds milestone, the pr and string lists: deps_added and
  *                          new_edges / removed_edges as "from:to" comma-joined, top_growth "file+N", decisions "K1:lint",
@@ -79,6 +80,10 @@ export function mapRecord(rec, wallMs) {
       import_files_added: rec.import_files_added, import_files_removed: rec.import_files_removed, boundary_changed: bit(rec.boundary_changed), boundary_loosened: bit(rec.boundary_loosened),
       ...structureLists(rec) }) };
   }
+  if (rec.event === "DECISION_ENGINE") { // #4766
+    return { event: "decision_engine", phase: null, payload: compact({ decided: rec.decided, escalated: rec.escalated, vetoed: rec.vetoed, reversed: rec.reversed, mode: rec.mode,
+      needs_human_before: rec.needs_human_before, needs_human_after: rec.needs_human_after }) };
+  }
   if (rec.event === "CI_PENDING_WAIT") {
     return { event: "ci_pending_wait", phase: rec.phase ?? "review", payload: compact({ pr: rec.pr, minutes_waited: rec.minutes_waited, result: rec.result, polls: rec.polls, rate_limit_sleeps: rec.rate_limit_sleeps }) };
   }

package/bin/engine-cli.mjs

@@ -8,10 +8,13 @@ import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import { readdirSync, statSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { homedir, hostname } from "node:os";
+import { homedir, hostname, cpus } from "node:os";
+import { localLaneCap } from "./lean/admission.mjs";
+import { memAvailableMb } from "./lean/heavy.mjs";
 import { join, resolve as resolvePath } from "node:path";
 import { runIssue, DEFAULT_MAX_ATTEMPTS, sanitizeLeaseHost } from "./engine.mjs";
 import { makeProjector } from "./engine/projector.mjs";
+import { isTrustedActor, parseDependsOn } from "./engine/phases.mjs";
 import { readLog, readLogFile, deriveState, runLogPath, migrateRunLogs } from "./engine/runlog.mjs";
 import { assertOpenCodeNativeRuntime } from "./runner.mjs";
 import { parseForgeYaml } from "./forge-utils.mjs";
@@ -20,7 +23,8 @@ import { makeEventEmitter, probeSweepEvents, experimentEvent } from "./engine/ev
 import { readExperiment } from "./experiment.mjs";
 import { readBranches, resolveLane, isDefaultLane } from "./lean/lane.mjs";
 import { parseVerify } from "./lean/verify.mjs";
-import { parseExecution, detectNeeds } from "./lean/execution.mjs";
+import { parseExecution, detectNeeds, placementText } from "./lean/execution.mjs";
+import { relayPrefetchCommands } from "./lean/relay.mjs";
 import { parseTurnBudgets, formatTurnSummary, TURN_BUDGET_DEFAULTS } from "./lean/budget.mjs";
 import { writeAtomic as writeResultAtomic } from "./lean/batch.mjs";
 import { parseLightConfig, LIGHT_DEFAULTS } from "./lean/light.mjs";
@@ -284,6 +288,13 @@ export async function readPostDeployMinAge(cwd = process.cwd()) {
 export function readMilestoneCloseOn(cwd = process.cwd()) {
   try { return String(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.milestones?.close_on ?? "").trim().toLowerCase() === "staging" ? "staging" : "default"; } catch { return "default"; }
 }
+/** forge.yaml `agents.subagent_model` (#4843): the default model of subagents in sessions ForgeDock launches; null when unset or invalid. */
+export function readSubagentModel(cwd = process.cwd()) {
+  try {
+    const v = String(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.agents?.subagent_model ?? "").trim();
+    return /^[A-Za-z0-9._:[\]-]+$/.test(v) ? v : null;
+  } catch { return null; }
+}
 /** forge.yaml `lean.explore` (on|off) and `lean.explore_model` (#4391): the builder's explorer subagent; undefined when neither is set or valid. */
 export function readExplore(cwd = process.cwd()) {
   try {
@@ -308,14 +319,24 @@ function readLeanSetting(key, cwd = process.cwd()) {
  * forge.yaml `engine.admission` (#4105). The parser flattens one nested level into `engine`, so the keys are read as
  * `engine.enabled|min_free_mem_mb|min_free_tmp_mb|max_load_per_core`, or flat `admission_*` equivalents.
  */
+/** #4777: `sched.cap` as a function: min(global_parallel, the host-derived local lane cap), re-probed at every admission attempt. */
+export function liveLaneCap(globalParallel, { cfg = readAdmission(), host = { cores: () => cpus().length, memAvailableMb } } = {}) {
+  return () => {
+    let derived = null;
+    try { derived = localLaneCap({ cfg, cores: host.cores(), memAvailableMb: host.memAvailableMb() }); } catch { derived = null; }
+    return derived === null ? globalParallel : globalParallel === null ? derived : Math.min(globalParallel, derived);
+  };
+}
 export function readAdmission(cwd = process.cwd()) {
   try {
     const e = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.engine ?? {};
     const num = (v) => { const n = Number(v); return v !== undefined && v !== "" && Number.isFinite(n) && n >= 0 ? n : undefined; };
+    const pos = (v) => { const n = num(v); return n > 0 ? n : undefined; };
     const en = String(e.admission_enabled ?? e.enabled ?? "").trim().toLowerCase();
     return { ...(en === "false" ? { enabled: false } : {}),
       min_free_mem_mb: num(e.min_free_mem_mb ?? e.admission_min_free_mem_mb), min_free_tmp_mb: num(e.min_free_tmp_mb ?? e.admission_min_free_tmp_mb),
-      max_load_per_core: num(e.max_load_per_core ?? e.admission_max_load_per_core) };
+      max_load_per_core: num(e.max_load_per_core ?? e.admission_max_load_per_core),
+      lane_cpu_reservation: pos(e.lane_cpu_reservation ?? e.admission_lane_cpu_reservation), lane_mem_mb: pos(e.lane_mem_mb ?? e.admission_lane_mem_mb) };
   } catch { return {}; }
 }
 /**
@@ -382,6 +403,11 @@ export function readHostCaps(cwd = process.cwd()) {
   const e = readExecution(cwd);
   return e?.hostCapabilities?.length ? { hostCapabilities: e.hostCapabilities, ...(e.hostCapabilityPatterns ? { hostCapabilityPatterns: e.hostCapabilityPatterns } : {}) } : undefined;
 }
+/** #4778: the capabilities the dispatching host relays to this sandbox lane (`CS_RELAY_CAPS`, set by the remote provider); `{}` when none. */
+export function readRelayCaps(env = process.env) {
+  const caps = String(env.CS_RELAY_CAPS ?? "").split(",").map((x) => x.trim().toLowerCase()).filter((x) => /^[a-z][a-z0-9_-]*$/.test(x));
+  return caps.length ? { relayCaps: [...new Set(caps)] } : {};
+}
 /**
  * forge.yaml `execution:` section (#4253, block style: `execution:` then `  mode: remote`, `  max_remote: 4`,
  * `  provider: container`, `  image`, `  secrets` comma-separated env names; remote provider #4254: `  endpoint`,
@@ -913,7 +939,7 @@ export async function runFromCli(argv, deps = {}) {
       lres = await runCore({ issue, repo: leanRepo, ...(lane ? { lane } : {}), laneOverride, branches: readBranches(), cwd: process.cwd(), dir, io: leanIo, path: enginePath, onProgress,
       onTeardown: (fn) => { teardown = fn; }, ...(env.FORGEDOCK_BATCH_ID ? { batchId: env.FORGEDOCK_BATCH_ID } : {}), ...(placement ? { placement } : {}), ...(recover ? { recover } : {}),
       emitTelemetry: deps.emitTelemetry ?? composeEmit(makeEmitTelemetry({ repo: leanRepo }), makeEventEmitter({ repo: leanRepo, config: readEvents() }).emit),
-      admission: readAdmission(), heavy: readHeavy(), ...readCoreLimits(), ...readEnvConfig(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(readConformanceMode() ? { conformance: readConformanceMode() } : {}), ...(readContextPack() ? { contextPack: readContextPack() } : {}), ...(readReviewIncomplete() ? { reviewIncomplete: readReviewIncomplete() } : {}), ...(readLaneInstructions() ? { laneInstructions: readLaneInstructions() } : {}), ...(readReproTest() ? { reproTest: readReproTest() } : {}), ...(readExplore() ? { explore: readExplore() } : {}), ...(readExperiment() ? { experiment: readExperiment() } : {}), light: readLight(), ...(readCloseParent() ? { closeParent: true } : {}), ...(readReviewTrigger() ? { reviewTrigger: readReviewTrigger() } : {}), ...(readVerify() ? { verify: readVerify() } : {}), ...readPrecheckOptions(), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}), ...(readFixModel() ? { fixModel: readFixModel() } : {}), ...(readBuilderRouting() ? { builderRouting: readBuilderRouting() } : {}), ...(readVerifier() ? { verifier: readVerifier() } : {}), ...(readHostCaps() ? { hostCaps: readHostCaps() } : {}) , ...(readSequenceRegenerate() ? { sequenceRegenerate: readSequenceRegenerate() } : {}), ...(readBaseMerge() ? { baseMerge: readBaseMerge() } : {}), ...(readFollowupsDefaultMilestone() ? { followupsDefaultMilestone: readFollowupsDefaultMilestone() } : {}) });
+      admission: readAdmission(), heavy: readHeavy(), ...readCoreLimits(), ...readEnvConfig(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(readConformanceMode() ? { conformance: readConformanceMode() } : {}), ...(readContextPack() ? { contextPack: readContextPack() } : {}), ...(readReviewIncomplete() ? { reviewIncomplete: readReviewIncomplete() } : {}), ...(readLaneInstructions() ? { laneInstructions: readLaneInstructions() } : {}), ...(readReproTest() ? { reproTest: readReproTest() } : {}), ...(readExplore() ? { explore: readExplore() } : {}), ...(readExperiment() ? { experiment: readExperiment() } : {}), light: readLight(), ...(readCloseParent() ? { closeParent: true } : {}), ...(readReviewTrigger() ? { reviewTrigger: readReviewTrigger() } : {}), ...(readVerify() ? { verify: readVerify() } : {}), ...readPrecheckOptions(), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}), ...(readFixModel() ? { fixModel: readFixModel() } : {}), ...(readBuilderRouting() ? { builderRouting: readBuilderRouting() } : {}), ...(readVerifier() ? { verifier: readVerifier() } : {}), ...(readHostCaps() ? { hostCaps: readHostCaps() } : {}), ...readRelayCaps(), ...(readSequenceRegenerate() ? { sequenceRegenerate: readSequenceRegenerate() } : {}), ...(readBaseMerge() ? { baseMerge: readBaseMerge() } : {}), ...(readFollowupsDefaultMilestone() ? { followupsDefaultMilestone: readFollowupsDefaultMilestone() } : {}) });
     } catch (e) { if (!interrupted) report({ terminalReason: "engine-error", detail: String(e?.message ?? e).slice(0, 500) }); throw e; }
     finally { if (!interrupted) for (const [sig, f] of Object.entries(handlers)) off(sig, f); }
     if (interrupted) return lres; // the signal handler reported and exits
@@ -1141,6 +1167,7 @@ async function envBatch({ argv, root, print = (l) => console.log(l) }) {
   const i = argv.indexOf(op), id = argv[i + 1], arg = argv[i + 2];
   if (!id || id.startsWith("--") || (op !== "--show-env" && !arg)) throw new Error(ORCH_USAGE);
   const batchMod = await import("./lean/batch.mjs"), { redactEnv } = await import("./lean/schedd.mjs");
+  if (op === "--set-env" && batchMod.SECRET_ENV.test(arg.split("=")[0])) throw new Error(`--set-env: ${arg.split("=")[0]} looks like a secret and is never stored in batch state; set it in the daemon's environment (or keychain) instead`);
   const b = batchMod.openBatch(root, id);
   const plan = b.readPlan();
   if (!plan) throw new Error(`no batch ${id} in ${root}`);
@@ -1188,6 +1215,27 @@ const parallelOf = (argv) => {
   return parallel;
 };
 
+/**
+ * #4773: the `Blocked by` / `Depends on` edges the added issues imply: declaration lines of a trusted body whose target is still open
+ * (a closed or unreadable target is a no-op, the scheduler skips it too). @returns {{from:number,to:number}[]}
+ */
+async function addedEdges({ added, records, io, repo }) {
+  const edges = [], seen = new Map();
+  for (const n of added) {
+    const rec = records.get(n);
+    if (!rec || !bodyTrusted(rec)) continue;
+    for (const d of parseDependsOn(rec.body, n)) {
+      if (!seen.has(d)) {
+        let st = null;
+        try { st = JSON.parse(await io.gh(["issue", "view", String(d), ...(repo ? ["-R", repo] : []), "--json", "state"]))?.state ?? null; } catch { st = null; }
+        seen.set(d, st);
+      }
+      if (seen.get(d) === "OPEN") edges.push({ from: n, to: d });
+    }
+  }
+  return edges;
+}
+
 /**
  * #4408: add `tokens` to batch `id`. Not a plain integer: skipped; not OPEN on the batch's repo (`gh issue view --json
  * state`): skipped `closed` (`unreadable` when the read fails); the rest go to the batch's `add` file, through the daemon
@@ -1198,15 +1246,16 @@ async function addToBatch({ id, tokens, root, io, viaDaemon = null, print = (l)
   const b = batchMod.openBatch(root, id);
   if (!b.exists()) throw new Error(`no batch ${id} in ${root}`);
   const repo = b.readPlan()?.repo ?? null;
-  const skipped = [], ints = [], state = new Map();
+  const skipped = [], ints = [], state = new Map(), records = new Map();
   for (const t of tokens) {
     if (/^#?\d+$/.test(String(t))) ints.push(parseInt(String(t).replace("#", ""), 10));
     else skipped.push({ issue: t, reason: "not an integer" });
   }
   for (const n of new Set(ints)) {
     let st = null;
-    try { st = JSON.parse(await io.gh(["issue", "view", String(n), ...(repo ? ["-R", repo] : []), "--json", "state"]))?.state ?? null; } catch { st = null; }
-    state.set(n, st);
+    let v = null;
+    try { v = JSON.parse(await io.gh(["issue", "view", String(n), ...(repo ? ["-R", repo] : []), "--json", "state,body,author,authorAssociation"])); st = v?.state ?? null; } catch { st = null; }
+    state.set(n, st); records.set(n, v);
   }
   const open = [];
   for (const n of ints) {
@@ -1220,7 +1269,9 @@ async function addToBatch({ id, tokens, root, io, viaDaemon = null, print = (l)
     if (res.reopened === undefined && res.requeued?.length && b.readReport()) b.clearReport(); // #4687: no daemon: the next --resume reruns it
   }
   const out = { ok: true, batch: id, added: res.added ?? [], requeued: res.requeued ?? [], skipped: [...(res.skipped ?? []), ...skipped] };
+  out.edges = await addedEdges({ added: out.added, records, io, repo }); // #4773
   print(`batch ${id}: added ${out.added.map((n) => `#${n}`).join(" ") || (out.requeued.length ? "" : "(none)")}${out.requeued.length ? `${out.added.length ? " " : ""}${out.requeued.map((n) => `requeued #${n}`).join(" ")}` : ""}${out.skipped.length ? `; skipped ${out.skipped.map((x) => `${/^\d+$/.test(String(x.issue)) ? "#" : ""}${x.issue} (${x.reason})`).join(", ")}` : ""}`);
+  if (out.edges.length) print(`batch ${id}: edges ${out.edges.map((e) => `#${e.from} blocked by #${e.to}`).join(", ")}`);
   return out;
 }
 
@@ -1469,6 +1520,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
   let batch, plan = null;
   if (resumeId) {
     batch = batchMod.openBatch(root, resumeId);
+    batch.scrubPlan(); // #4787: a pre-fix plan.json keeps no secret; the lanes re-read it from the environment
     plan = batch.readPlan();
     if (!plan) throw new Error(`no batch ${resumeId} in ${root}`);
     argv = plan.argv;
@@ -1548,7 +1600,9 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
   // Lanes: in-process `runCore` when a lean module is injected (tests), otherwise detached `run-issue` processes, or
   // sandboxes when forge.yaml `execution` places them remote (#4253).
   const labelsOf = new Map(); // issue -> label names, filled by readBody (one gh call per issue)
+  const trustedOf = new Map(); // #4773: issue -> its body author is trusted (a `Blocked by` line is an edge only then), filled by readBody
   const needsOf = new Map(); // issue -> host-only capabilities its body names (#4542), filled by readBody
+  const prefetchOf = new Map(); // issue -> the frozen contract's relayable read-only commands (#4778), filled by readBody
   let execForNeeds = null;
   let lanes, remote = null, execBudget = null, execConf = null, hybrid = false;
   const execMode = () => (deps.execution !== undefined ? deps.execution : readExecution(cwd))?.mode ?? "local";
@@ -1556,7 +1610,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
     const { runCore } = deps.leanModule;
     const emitTelemetry = deps.emitTelemetry ?? makeEmitTelemetry({ repo });
     lanes = { adopt: null, runOne: (n, ln, ctx = {}) => runCore({ issue: n, repo, lane: ln, laneOverride, ...(ctx.placement ? { placement: { ...ctx.placement, mode: execMode() } } : {}), ...(ctx.recover ? { recover: ctx.recover } : {}), branches, cwd, dir, io: leanIo, agentId: `orch_${process.pid}_${n}`, emitTelemetry, batchId: batch.id,
-      admission: readAdmission(cwd), heavy: readHeavy(cwd), ...readCoreLimits(cwd), ...readEnvConfig(cwd), ...(readMergeWait(cwd) ? { mergeWait: readMergeWait(cwd) } : {}), ...(readConformanceMode(cwd) ? { conformance: readConformanceMode(cwd) } : {}), ...(readContextPack(cwd) ? { contextPack: readContextPack(cwd) } : {}), ...(readReviewIncomplete(cwd) ? { reviewIncomplete: readReviewIncomplete(cwd) } : {}), ...(readLaneInstructions(cwd) ? { laneInstructions: readLaneInstructions(cwd) } : {}), ...(readReproTest(cwd) ? { reproTest: readReproTest(cwd) } : {}), ...(readExplore(cwd) ? { explore: readExplore(cwd) } : {}), ...(readExperiment(cwd) ? { experiment: readExperiment(cwd) } : {}), light: readLight(cwd), ...(readCloseParent(cwd) ? { closeParent: true } : {}), ...(readReviewTrigger(cwd) ? { reviewTrigger: readReviewTrigger(cwd) } : {}), ...(readVerify(cwd) ? { verify: readVerify(cwd) } : {}), ...readPrecheckOptions(cwd), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model", cwd) ? { reviewerModel: readLeanSetting("reviewer_model", cwd) } : {}), ...(readFixModel(cwd) ? { fixModel: readFixModel(cwd) } : {}), ...(readBuilderRouting(cwd) ? { builderRouting: readBuilderRouting(cwd) } : {}), ...(readVerifier(cwd) ? { verifier: readVerifier(cwd) } : {}), ...(readHostCaps(cwd) ? { hostCaps: readHostCaps(cwd) } : {}), ...(readSequenceRegenerate(cwd) ? { sequenceRegenerate: readSequenceRegenerate(cwd) } : {}), ...(readBaseMerge(cwd) ? { baseMerge: readBaseMerge(cwd) } : {}), ...(readFollowupsDefaultMilestone(cwd) ? { followupsDefaultMilestone: readFollowupsDefaultMilestone(cwd) } : {}) }) };
+      admission: readAdmission(cwd), heavy: readHeavy(cwd), ...readCoreLimits(cwd), ...readEnvConfig(cwd), ...(readMergeWait(cwd) ? { mergeWait: readMergeWait(cwd) } : {}), ...(readConformanceMode(cwd) ? { conformance: readConformanceMode(cwd) } : {}), ...(readContextPack(cwd) ? { contextPack: readContextPack(cwd) } : {}), ...(readReviewIncomplete(cwd) ? { reviewIncomplete: readReviewIncomplete(cwd) } : {}), ...(readLaneInstructions(cwd) ? { laneInstructions: readLaneInstructions(cwd) } : {}), ...(readReproTest(cwd) ? { reproTest: readReproTest(cwd) } : {}), ...(readExplore(cwd) ? { explore: readExplore(cwd) } : {}), ...(readExperiment(cwd) ? { experiment: readExperiment(cwd) } : {}), light: readLight(cwd), ...(readCloseParent(cwd) ? { closeParent: true } : {}), ...(readReviewTrigger(cwd) ? { reviewTrigger: readReviewTrigger(cwd) } : {}), ...(readVerify(cwd) ? { verify: readVerify(cwd) } : {}), ...readPrecheckOptions(cwd), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model", cwd) ? { reviewerModel: readLeanSetting("reviewer_model", cwd) } : {}), ...(readFixModel(cwd) ? { fixModel: readFixModel(cwd) } : {}), ...(readBuilderRouting(cwd) ? { builderRouting: readBuilderRouting(cwd) } : {}), ...(readVerifier(cwd) ? { verifier: readVerifier(cwd) } : {}), ...(readHostCaps(cwd) ? { hostCaps: readHostCaps(cwd) } : {}), ...readRelayCaps(), ...(readSequenceRegenerate(cwd) ? { sequenceRegenerate: readSequenceRegenerate(cwd) } : {}), ...(readBaseMerge(cwd) ? { baseMerge: readBaseMerge(cwd) } : {}), ...(readFollowupsDefaultMilestone(cwd) ? { followupsDefaultMilestone: readFollowupsDefaultMilestone(cwd) } : {}) }) };
   } else {
     const laneScript = deps.laneScript ?? fileURLToPath(new URL("./forgedock.mjs", import.meta.url));
     // #4690: lanes learn K (the default MemoryMax is derived from it); one line says so when no scope caps them.
@@ -1589,7 +1643,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
       // #4253: lanes run in sandboxes, ledger-tracked per lane, admitted against max_remote instead of the host cap.
       let gitDir = null;
       try { gitDir = resolvePath(cwd, String(await leanIo.git(["rev-parse", "--git-common-dir"], { cwd })).trim()); } catch { gitDir = null; }
-      const provider = deps.sandboxProvider ?? execMod.providerByName(exec.provider, { batch, repo, cwd, image: exec.image, gitDir, script: laneScript, bin: deps.laneBin, exec, env });
+      const provider = deps.sandboxProvider ?? execMod.providerByName(exec.provider, { batch, repo, cwd, image: exec.image, gitDir, script: laneScript, bin: deps.laneBin, exec, env, prefetch: (n) => prefetchOf.get(n) ?? [] });
       const { makeLedger } = await import("./lean/ledger.mjs");
       const ledgerFor = deps.sandboxLedger ?? ((n) => makeLedger({ batch: batch.id, lane: `sandbox-${n}`, owner: `orch_${process.pid}`, issue: n }));
       const bud = exec.budget ?? {};
@@ -1763,9 +1817,11 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
     rows = await orchestrate({
       ...(estimate ? { estimate } : {}),
       beforeAdmit,
+      ...(orch.blockedLabel ? { getBlocked: async () => JSON.parse(await leanIo.gh(["issue", "list", "-R", repo, "--label", orch.blockedLabel, "--state", "open", "--limit", "200", "--json", "number"])).map((x) => x.number) } : {}), // #4773
+      trusted: (n) => trustedOf.get(n) === true,
       issues, parallel, prefilter, resolveLane: laneOf, store: batch.store, getParallel: batch.readParallel, getAdded: batch.readAdded, getRequeued: batch.readRequeued, getCancelled: batch.readCancel, getHeld: batch.readHeld, getGates: batch.readGates, ...lanes,
       breaker: orch.breaker, maxDeferrals: orch.maxDeferrals, ...(deps.pollMs ? { pollMs: deps.pollMs } : {}), ...budget, limits, identity, batchId: batch.id, drift, lifecycle, integration,
-      ...(registry ? { sched: { registry, batch: batch.id, repo, cap: orch.globalParallel ?? null, exclusive: true }, priorityOf: async (n) => schedMod.priorityFromLabels(await labelNames(n)) } : {}),
+      ...(registry ? { sched: { registry, batch: batch.id, repo, cap: liveLaneCap(orch.globalParallel ?? null), exclusive: true }, priorityOf: async (n) => schedMod.priorityFromLabels(await labelNames(n)) } : {}),
       ...(remote ? { remote } : {}),
       // #4267: mechanical needs-human outcomes are recovered in the batch; every runner decision is a FORGE:DECISION.
       ...(recoveryOn ? { recovery: orch.recovery } : {}),
@@ -1780,6 +1836,8 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
       dispatchCheck: deps.dispatchCheck !== undefined ? deps.dispatchCheck : makeDispatchCheck({ gh: (a) => leanIo.gh(a), repo }),
       // #4387: an out-of-set dependency labelled needs-human is not pulled into the batch
       issueLabels: labelNames,
+      // #4725: a closed (completed) dependency is satisfied even when it still carries a stale needs-human label
+      issueState: async (n) => { const v = JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "state,stateReason"])); return v.state === "CLOSED" && String(v.stateReason ?? "COMPLETED").toUpperCase() !== "COMPLETED" ? "CLOSED_NOT_PLANNED" : v.state; },
       // #4318: a dispatcher signal relabels the queued recoveries before it exits (the daemon resumes its batches instead)
       ...(daemon ? {} : { onExit: (fn) => { exitRelabel = fn; } }),
       // #4454: the daemon's shutdown stop; orchestrate throws batch.stopped, so no report is written and a resume adopts the lanes
@@ -1803,8 +1861,8 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
         sink.line(`cross-lane: #${e.issue} (${e.lane}) depends on #${e.dependency} (${e.dependencyLane}); its fix will not be on ${e.lane}: re-milestone #${e.dependency} or wait for a milestone sync`);
       },
       readBody: maint || registry || hybrid
-        ? async (n) => { const v = JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "body,labels"])); labelsOf.set(n, (v.labels ?? []).map((x) => x.name)); needsOf.set(n, detectNeeds(v.body, execForNeeds)); return v.body; }
-        : async (n) => { const b = JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "body"])).body; needsOf.set(n, detectNeeds(b, execForNeeds)); return b; },
+        ? async (n) => { const v = JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "body,labels,comments,author,authorAssociation"])); trustedOf.set(n, bodyTrusted(v)); labelsOf.set(n, (v.labels ?? []).map((x) => x.name)); needsOf.set(n, detectNeeds(placementText(v), execForNeeds)); if (execForNeeds?.relay) prefetchOf.set(n, relayPrefetchCommands(v, execForNeeds.relay)); return v.body; }
+        : async (n) => { const v = JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "body,comments,author,authorAssociation"])); trustedOf.set(n, bodyTrusted(v)); needsOf.set(n, detectNeeds(placementText(v), execForNeeds)); if (execForNeeds?.relay) prefetchOf.set(n, relayPrefetchCommands(v, execForNeeds.relay)); return v.body; }, // #4785: decisions and the frozen contract's validate commands too
       onUpdate: (r) => sink.row(r),
     });
   } finally { for (const [sig, f] of Object.entries(handlers)) off(sig, f); }
@@ -1911,10 +1969,16 @@ export function makeRelabelNeedsHuman({ gh, repo, now = () => Date.now() }) {
     {
       const external = { owner: "", unblock: "" }; // the default non-parked relabel is a human-owned wait
       const { NEEDS_HUMAN_EXTERNAL_LABEL } = await import("./engine/outcome-codes.mjs");
+      // #4725: a recorded premise that already holds is not a blocker; an identical owner ask links to its entry instead of a new one.
+      const prem = await import("./lean/needs-human-premise.mjs");
+      const predicate = prem.parsePredicate(evidence);
+      if (predicate && await prem.evalPredicate(predicate, { repo, io: { gh, pkgVersion: prem.registryPkgVersion }, now: now() }) === true) return "skipped";
+      const reg = await prem.registerAsk({ repo, io: { gh }, issue, ask: String(evidence ?? "") });
+      const extra = [prem.premiseAnnotation(predicate), reg.existing ? `Same owner ask as #${reg.existing} (one ask, linked): answering it unblocks this issue too.` : ""].filter(Boolean).join("\n");
       try { await gh(["issue", "edit", String(issue), "-R", repo, "--add-label", `needs-human,${NEEDS_HUMAN_EXTERNAL_LABEL}`]); } catch { return "failed"; }
       try {
         const { capComment } = await import("./lean/render.mjs");
-        await gh(["issue", "comment", String(issue), "-R", repo, "--body", capComment(`<!-- FORGE:NEEDS_HUMAN external=true -->\n## Needs human (external)\nOwner: ${external.owner || "unassigned (name an owner)"}\nUnblock condition: ${external.unblock || "unstated (name the condition that unblocks this issue)"}\n${evidence}`)]);
+        await gh(["issue", "comment", String(issue), "-R", repo, "--body", capComment(`<!-- FORGE:NEEDS_HUMAN external=true -->\n## Needs human (external)\nOwner: ${external.owner || "unassigned (name an owner)"}\nUnblock condition: ${external.unblock || "unstated (name the condition that unblocks this issue)"}\n${extra ? `${extra}\n` : ""}${evidence}${!reg.existing && reg.entry ? `\n\n${reg.entry}` : ""}`)]);
       } catch { /* best effort */ }
       return true;
     }
@@ -1937,6 +2001,7 @@ async function scheddDue() {
   const leanIo = (await import("./lean/effects.mjs")).makeLeanIo({ repo });
   await sweepDue({ repo, cwd: process.cwd(), io: leanIo, onResult: probeEventSink(repo) });
   await sweepParkedFollowups({ repo, io: leanIo }); // #4689: re-queue parked post-deploy follow-ups on the same pass
+  try { const prem = await import("./lean/needs-human-premise.mjs"); await prem.sweepPremises({ repo, io: { gh: (a) => leanIo.gh(a), pkgVersion: prem.registryPkgVersion } }); } catch { /* best effort (#4725) */ } // clear needs-human whose recorded premise now holds
 }
 
 /** #4689: re-evaluate the parked post-deploy follow-ups of the repo (promotion, due date, check now defined); never throws. */
@@ -1958,10 +2023,17 @@ export async function scheddFromCli(argv, deps = {}) {
     let sock;
     try { sock = await schedd.connectDaemon({ dir, spawnDaemon: null }); } catch { console.log("schedd: not running"); return { running: false }; }
     const st = await schedd.request(sock, { op: "status" });
-    console.log(`schedd: pid ${st.pid}, ${st.batches.length} batch(es)${st.batches.length ? ": " + st.batches.map((b) => b.id).join(", ") : ""}`);
+    console.log(`schedd: pid ${st.pid}, ${st.batches.length} batch(es)${st.batches.length ? ": " + st.batches.map((b) => b.id).join(", ") : ""}${Number.isFinite(st.lastTick) ? `, last tick ${Math.round((Date.now() - st.lastTick) / 1000)} s ago` : ""}`);
     return { running: true, ...st };
   }
-  if (argv.length) throw new Error("usage: forgedock schedd [status]");
+  if (argv[0] === "watchdog") { // #4780: run by the schedd watchdog timer; signals a live daemon whose heartbeat went stale
+    const health = await import("./lean/schedd-health.mjs");
+    const i = argv.indexOf("--stall-sec"), sec = i >= 0 ? Number(argv[i + 1]) : NaN;
+    if (i >= 0 && !(sec > 0)) throw new Error("usage: forgedock schedd watchdog [--stall-sec N]");
+    return (deps.watchdog ?? health.watchdog)({ dir, ...(sec > 0 ? { stallMs: sec * 1000 } : {}) });
+  }
+  if (argv.length) throw new Error("usage: forgedock schedd [status | watchdog [--stall-sec N]]");
+  (deps.renice ?? (await import("./lean/schedd-health.mjs")).bestEffortRenice)(); // #4780: lanes must not starve the scheduler
   process.title = "forgedock-schedd"; // distinctive name for OOM-killer avoid lists and ps (#4673)
   const d = await schedd.startDaemon({ dir, runBatch: (a) => runBatch({ ...a, daemon: true, deps: deps.batchDeps ?? {} }), ...(deps.due !== undefined ? { due: deps.due } : { due: scheddDue }) });
   if (!d.running) return d;
@@ -2120,11 +2192,13 @@ export async function checkFromCli(argv, deps = {}) {
 export async function schedFromCli(argv, deps = {}) {
   const schedMod = await import("./lean/sched.mjs");
   const reg = deps.sched ?? schedMod.openSched(schedMod.schedDir());
+  const health = await import("./lean/schedd-health.mjs");
   const usage = "usage: forgedock sched show | forgedock sched cap <N>|--clear | forgedock sched weight <owner/repo> <N>|--clear";
   const [sub, arg, arg2] = argv;
   if (!sub || sub === "show") {
     const st = reg.list();
     const who = (e) => `#${e.issue} ${e.repo ?? "-"} batch ${e.batch ?? "-"} P${e.priority}`;
+    console.log(deps.tick ?? health.tickText(health.stallCheck({ dir: schedMod.schedDir() })));
     console.log(`host cap: ${st.cap ?? "none set here (each batch's orchestration.global_parallel applies)"}; running ${st.slots.length}, queued ${st.queue.length}`);
     const ws = Object.entries(st.weights ?? {});
     console.log(`repo weights: ${ws.length ? ws.map(([r, n]) => `${r}=${n}`).join(", ") : "equal (none set)"}`);
@@ -2152,14 +2226,19 @@ export async function schedFromCli(argv, deps = {}) {
   throw new Error(usage);
 }
 
+/** #4773: is the author of a `gh issue view --json author,authorAssociation` record trusted (the engine admission's `isTrustedActor`)? */
+const bodyTrusted = (v) => isTrustedActor({ association: v?.authorAssociation, type: v?.author?.is_bot ? "Bot" : "User", login: v?.author?.login });
+
 /**
  * forge.yaml `orchestration.breaker` ({errors, window_min}; default 3 engine-errors in 30 min; errors 0 turns it off),
  * `orchestration.max_deferrals` (default 3) and `orchestration.global_parallel` (#4191: host-wide lane cap; unset = none). The parser flattens one nested level, so the breaker keys arrive as
  * `orchestration.errors|window_min` (or flat `breaker_errors|breaker_window_min`).
  * `orchestration.recovery.max_attempts` (#4267; arrives as `max_attempts`, or flat `recovery_max_attempts`): recovery lanes per
- * issue for a mechanical needs-human, default 1, 0 turns recovery off.
+ * issue for a mechanical needs-human, default 1, 0 turns recovery off. `orchestration.recovery.mechanical_max_attempts` (#4725; or
+ * `mechanical_max_attempts`): the separate budget of env.*, base.conflict and conflicting-PR rows, default 2, never below `max_attempts`.
  * `orchestration.base_sync.enabled` (#4525; default true, false opts out) and `base_sync.union_globs` (comma list of globs of
  * append-only files whose two-sided line additions a parked PR's base sync keeps both of).
+ * `orchestration.blocked_label` (#4773; default `blocked`, empty turns it off): an open issue carrying it is admitted but not dispatched.
  */
 export function readOrchestration(cwd = process.cwd()) {
   let o = {};
@@ -2168,8 +2247,8 @@ export function readOrchestration(cwd = process.cwd()) {
   const errors = int(o.breaker_errors ?? o.errors, 3), windowMin = int(o.breaker_window_min ?? o.window_min, 30);
   const gp = int(o.global_parallel, null);
   const recoveryMax = int(o.recovery_max_attempts ?? o.max_attempts, 1);
-  return { breaker: errors > 0 && windowMin > 0 ? { errors, window_min: windowMin } : null, maxDeferrals: int(o.max_deferrals, 3), globalParallel: gp >= 1 ? gp : null,
-    recovery: { maxAttempts: recoveryMax },
+  return { breaker: errors > 0 && windowMin > 0 ? { errors, window_min: windowMin } : null, maxDeferrals: int(o.max_deferrals, 3), blockedLabel: String(o.blocked_label ?? "blocked").trim(), globalParallel: gp >= 1 ? gp : null,
+    recovery: { maxAttempts: recoveryMax, mechanicalMaxAttempts: Math.max(int(o.recovery_mechanical_max_attempts ?? o.mechanical_max_attempts, 2), recoveryMax) }, // #4725: env/base/sequence codes have their own budget
     // #4525: parked-PR base sync. The parser flattens one level, so `base_sync.enabled|union_globs` arrive as `enabled|union_globs` (or flat `base_sync_*`).
     baseSync: { enabled: String(o.base_sync_enabled ?? o.enabled ?? "true").trim().toLowerCase() !== "false",
       unionGlobs: String(o.base_sync_union_globs ?? o.union_globs ?? "").replace(/^\[|\]$/g, "").split(",").map((x) => x.trim().replace(/^["']|["']$/g, "")).filter(Boolean) } };

package/bin/forgedock.mjs

@@ -3359,10 +3359,11 @@ function help() {
     ["npx forgedock check [--base REF] [--json]", "Run the lane's frozen validate commands and change-scoped pre-PR checks locally in this worktree, as the engine will (no GitHub, no Actions)"],
     ["npx forgedock milestone train <slug...> [--parallel-milestones N] | --resume <id> | --insert <id> <slug> [--before s|--after s] | --show <id>", "Unattended multi-milestone train: one durable state file (order, active set, lifecycle), typed STOP reasons, resumable; never edits forge.yaml"],
     ["npx forgedock guards list [--path p] [--json] | backfill --since <date> [--dry-run]", "Fix guards: list the FORGE:GUARD records (test files + protected hunks of merged fixes) covering a path, or build them for already-merged lean lanes"],
+    ["npx forgedock issue-watch run [--name <w>] [--repo owner/repo] [--once] [--dry-run] | status [--name <w>]", "Named, scoped, capped watches (forge.yaml issue_watch.watches) that claim matching open issues into lanes or one long-lived orchestrate batch, or (mode: release) pool them and cut themed releases; see docs/ISSUE-WATCH.md"],
     ["npx forgedock limits show | clear <id>|--all", "Show or clear per-account usage-limit holds shared by orchestrate batches"],
     ["npx forgedock decisions list [--stale] [--refresh]", "List anchored decisions (FORGE:DECISION); --stale shows those with an anchor missing on the base"],
     ["npx forgedock sched show | cap <N>|--clear | weight <owner/repo> <N>|--clear", "Show the host lane registry, set the host-wide lane cap shared by orchestrate batches, or set a repo's share of slots within a priority (default equal)"],
-    ["npx forgedock schedd [status]", "Host scheduler daemon hosting every orchestrate batch (auto-spawned by orchestrate; run in the foreground for a systemd-user unit); status shows its pid and batches"],
+    ["npx forgedock schedd [status | watchdog]", "Host scheduler daemon hosting every orchestrate batch (auto-spawned by orchestrate; run in the foreground for a systemd-user unit); status shows its pid, batches and last tick; watchdog restarts a stalled daemon"],
     ["npx forgedock pool router [install] | enroll [--cpus N --mem GB] | status | upgrade [agent] | remove <agent>", "Built-in remote compute pool: run the router (foreground, or install it as a user service), print the one-time install command for a host, list agents, upgrade or remove them"],
     ["npx forgedock gc [--apply] [--older-than 6h] [--docker] [--worktrees] [--branches] [--tmp] [--processes] [--sandboxes]", "Report (dry-run default) and reclaim ForgeDock-owned leftovers: stale lane ledgers, forgedock-labelled containers/volumes, lean-*/agent-* worktrees, abandoned lane branches, ~/.forge/tmp scratch, orphaned lane processes, orphaned lane sandboxes; unowned resources and unpushed work are only reported"],
     ["npx forgedock resume-stalled [--dry-run]", "Fleet stall recovery — re-dispatch expired-lease issues"],
@@ -3945,7 +3946,7 @@ async function watch() {
 const SPLASH_COMMANDS = new Set(["run", "bootstrap", "run-issue", "orchestrate", "triage", "probe", "gc", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
 const KNOWN_COMMANDS = new Set([
   "install", "init", "enable", "disable", "status", "uninstall", "update",
-  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "milestone", "milestone-sync", "guards", "triage", "probe", "review-staging", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "limits", "decisions", "sched", "schedd", "pool", "check", "help", "--help", "-h",
+  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "milestone", "milestone-sync", "guards", "triage", "probe", "review-staging", "gc", "resume-stalled", "demo", "doctor", "watch", "issue-watch", "labels", "config", "stats", "limits", "decisions", "sched", "schedd", "pool", "check", "help", "--help", "-h",
   "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
@@ -4206,6 +4207,16 @@ switch (command) {
     }
     break;
   }
+  case "issue-watch": {
+    const { issueWatchFromCli } = await import("./lean/issuewatch.mjs");
+    try {
+      await issueWatchFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
   case "limits": {
     const { limitsFromCli } = await import("./engine-cli.mjs");
     try {

package/bin/lean/activation.mjs

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4769: default-off rollouts must not ship dormant. Pure helpers: detect new off-by-default keys in a diff of a repo-declared
+// rollout registry, require an activation row for them, check mode-naming acceptance criteria, and report dormant flags.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseForgeYaml } from "../forge-utils.mjs";
+
+export const DEFAULT_DORMANT_DAYS = 14;
+const OFF = String.raw`(?:false|False|FALSE|0|off|OFF|null|None|""|''|"(?:false|off|0)"|'(?:false|off|0)')`;
+const ENTRY_RE = new RegExp(String.raw`^["']?([A-Za-z_][\w.-]*)["']?\s*[:=]\s*${OFF}\s*,?;?\s*(?:#.*|//.*)?$`);
+const MODE_RE = /\b(shadow|cohort|treated)\b/i;
+const flagRe = (flag) => new RegExp(`(^|[^\\w])${String(flag).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}($|[^\\w])`);
+
+/** forge.yaml `rollouts: files: "a.json,b.py"` (comma-separated paths of the registry or env flag list) and `dormant_days`; null when absent. */
+export function readRollouts(cwd, read = (p) => readFileSync(p, "utf8")) {
+  let sec;
+  try { sec = parseForgeYaml(read(join(cwd, "forge.yaml")))?.rollouts; } catch { return null; }
+  const files = String(sec?.files ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+  if (!files.length) return null;
+  const days = Number(sec?.dormant_days);
+  return { files, days: Number.isFinite(days) && days > 0 ? days : DEFAULT_DORMANT_DAYS };
+}
+
+const inRegistry = (cfg, path) => (cfg?.files ?? []).some((f) => path === f || path.startsWith(f.endsWith("/") ? f : `${f}/`));
+
+/** The keys a unified diff adds to a registry file with a default of off/false/0 (a key that is only changed, not new, is excluded). */
+export function detectNewOffKeys(cfg, diffText) {
+  if (!cfg?.files?.length) return [];
+  const added = new Set(), seen = new Set();
+  let path = null;
+  for (const line of String(diffText ?? "").split("\n")) {
+    const m = /^\+\+\+ (?:b\/)?(.+)$/.exec(line);
+    if (m) { path = m[1].trim(); continue; }
+    if (!path || !inRegistry(cfg, path) || !/^[+-][^+-]|^[+-]$/.test(line)) continue;
+    const e = ENTRY_RE.exec(line.slice(1).trim());
+    if (line[0] === "-") { const k = /^["']?([A-Za-z_][\w.-]*)["']?\s*[:=]/.exec(line.slice(1).trim()); if (k) seen.add(k[1]); }
+    else if (e) added.add(e[1]);
+  }
+  return [...added].filter((k) => !seen.has(k)).sort();
+}
+
+const matches = (pattern, flag) => (pattern.endsWith("*") ? flag.startsWith(pattern.slice(0, -1)) : pattern === flag);
+/** Whether a requirement is an activation row for `flag`: a defer `owner:promote:<flag>` bucket, or a deliver row whose why/evidence names it. */
+export function coversFlag(r, flag) {
+  const b = String(r?.bucket ?? "");
+  if (r?.disposition === "defer" && b.startsWith("owner:promote:")) return matches(b.slice("owner:promote:".length), flag);
+  return r?.disposition === "deliver" && flagRe(flag).test(`${r?.why ?? ""} ${r?.evidence ?? ""}`);
+}
+const uncovered = (contract, keys) => keys.filter((k) => !(contract?.requirements ?? []).some((r) => coversFlag(r, k)));
+
+/** Conformance failures: every new off key needs an activation row; a requirement naming shadow/cohort/treated fails while its flag ships off uncovered. */
+export function activationFailures(contract, keys) {
+  const miss = uncovered(contract, keys ?? []);
+  if (!miss.length) return [];
+  const out = [{ kind: "activation_missing", detail: `default-off ${miss.join(", ")} added with no activation row: add a requirement with bucket owner:promote:<flag> (first cohort, guard metrics, shadow evidence) or a deliver row naming the flag` }];
+  for (const r of contract?.requirements ?? []) {
+    if (MODE_RE.test(String(r?.quote ?? "")) && r.disposition === "deliver") out.push({ kind: "mode_unreachable", detail: `${r.id} names ${MODE_RE.exec(r.quote)[1].toLowerCase()} mode but ${miss.join(", ")} ships off and no activation row covers it` });
+  }
+  return out;
+}
+
+/**
+ * Dormancy report: introduced `[{flag, parent, since}]` (since: ms or ISO) that `flagState(flag)` (injected, read-only) says are still
+ * "off" after `days`, minus flags with a recorded keep-off decision (`decisions`: `[{flag, decision:"keep-off"}]`, flag may end in `*`).
+ */
+export async function dormancyReport({ introduced = [], flagState, decisions = [], now = Date.now(), days = DEFAULT_DORMANT_DAYS }) {
+  const kept = decisions.filter((d) => d?.decision === "keep-off").map((d) => String(d.flag));
+  const out = [];
+  for (const i of introduced) {
+    const age = Math.floor((now - new Date(i.since).getTime()) / 86400e3);
+    if (!(age >= days) || kept.some((k) => matches(k, i.flag))) continue;
+    if (String(await flagState(i.flag)).toLowerCase() === "off") out.push({ flag: i.flag, parent: i.parent ?? null, days: age });
+  }
+  return out.sort((a, b) => b.days - a.days);
+}

package/bin/lean/activation.test.mjs

@@ -0,0 +1,75 @@
+// 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 { readRollouts, detectNewOffKeys, activationFailures, dormancyReport, coversFlag } from "./activation.mjs";
+import { precheck } from "./conformance.mjs";
+
+const cfg = { files: ["config/rollouts.json"], days: 14 };
+const DIFF = [
+  "diff --git a/config/rollouts.json b/config/rollouts.json", "--- a/config/rollouts.json", "+++ b/config/rollouts.json", "@@ -1,3 +1,5 @@",
+  '+  "clearance_exit_routing": false,', '+  "already_on": true,', '-  "old_flag": true', '+  "old_flag": false,',
+  "diff --git a/src/other.json b/src/other.json", "--- a/src/other.json", "+++ b/src/other.json", '+  "elsewhere": false,',
+].join("\n");
+const Q_SHADOW = "Hit > 0 and unbound < 5% in shadow within a week";
+const contract = (reqs) => ({ requirements: reqs, deliverables: [], preserve: [], validate: [] });
+const pre = (c, newOffKeys) => precheck({ contract: c, result: { requirements: c.requirements.map((r) => ({ id: r.id, status: "implemented" })) }, changedFiles: [], newOffKeys });
+
+describe("activation rows (#4769)", () => {
+  it("reads the forge.yaml rollouts registry", () => {
+    assert.deepEqual(readRollouts("/x", () => 'rollouts:\n  files: "a.json, b.py"\n  dormant_days: 30\n'), { files: ["a.json", "b.py"], days: 30 });
+    assert.equal(readRollouts("/x", () => "engine:\n  path: core\n"), null);
+    assert.equal(readRollouts("/x", () => { throw new Error("none"); }), null);
+  });
+
+  it("a registry diff yields only new off keys in declared files", () => {
+    assert.deepEqual(detectNewOffKeys(cfg, DIFF), ["clearance_exit_routing"]);
+    assert.deepEqual(detectNewOffKeys(null, DIFF), []);
+  });
+
+  it("a contract without an activation row fails; an owner:promote row or a named deliver row passes", () => {
+    const base = { id: "R1", quote: "Ship the clearance routing change", disposition: "deliver" };
+    const keys = detectNewOffKeys(cfg, DIFF);
+    const bad = pre(contract([base]), keys);
+    assert.equal(bad.ok, false); assert.ok(bad.failures.some((f) => f.kind === "activation_missing"));
+    const owner = { id: "R2", quote: "Turn it on after shadow", disposition: "defer", bucket: "owner:promote:clearance_exit_routing", why: "w" };
+    assert.equal(pre(contract([base, owner]), keys).ok, true);
+    assert.equal(pre(contract([base, { ...owner, bucket: "owner:promote:clearance_*" }]), keys).ok, true);
+    assert.equal(pre(contract([{ ...base, why: "also flips clearance_exit_routing to the first cohort" }]), keys).ok, true);
+    assert.equal(coversFlag({ disposition: "defer", bucket: "owner:promote:other" }, "clearance_exit_routing"), false);
+  });
+
+  it("no new off key leaves precheck unchanged", () => {
+    assert.equal(pre(contract([{ id: "R1", quote: Q_SHADOW, disposition: "deliver" }]), []).ok, true);
+    assert.equal(pre(contract([{ id: "R1", quote: Q_SHADOW, disposition: "deliver" }]), null).ok, true);
+  });
+
+  it("an 'in shadow' AC fails when the change ships off with no activation row, and passes with one", () => {
+    const ac = { id: "R1", quote: Q_SHADOW, disposition: "deliver" };
+    const fails = activationFailures(contract([ac]), ["clearance_exit_routing"]);
+    assert.ok(fails.some((f) => f.kind === "mode_unreachable" && /R1 names shadow/.test(f.detail)));
+    const row = { id: "R2", quote: "Promote it", disposition: "defer", bucket: "owner:promote:clearance_exit_routing", why: "w" };
+    assert.deepEqual(activationFailures(contract([ac, row]), ["clearance_exit_routing"]), []);
+  });
+});
+
+describe("dormancy report (#4769)", () => {
+  const now = Date.parse("2026-10-29T00:00:00Z");
+  const introduced = [
+    { flag: "EXTRACTION_V2_CANARY_PCT", parent: 21002, since: "2026-06-17" },
+    { flag: "clearance_exit_routing", parent: 36817, since: "2026-10-10" },
+    { flag: "recent_flag", parent: 1, since: "2026-10-25" },
+    { flag: "now_on", parent: 2, since: "2026-01-01" },
+    { flag: "egress_country_exploration", parent: 36623, since: "2026-09-01" },
+  ];
+  const flagState = async (f) => (f === "now_on" ? "on" : "off");
+  it("lists still-off flags past N days with days dormant and parent", async () => {
+    const r = await dormancyReport({ introduced, flagState, now });
+    assert.deepEqual(r.map((x) => [x.flag, x.parent, x.days]), [["EXTRACTION_V2_CANARY_PCT", 21002, 134], ["egress_country_exploration", 36623, 58], ["clearance_exit_routing", 36817, 19]]);
+    assert.deepEqual((await dormancyReport({ introduced, flagState, now, days: 60 })).map((x) => x.flag), ["EXTRACTION_V2_CANARY_PCT"]);
+  });
+  it("a keep-off decision (exact or wildcard) silences the entry", async () => {
+    const r = await dormancyReport({ introduced, flagState, now, decisions: [{ flag: "EXTRACTION_V2_*", decision: "keep-off" }, { flag: "egress_country_exploration", decision: "promote" }] });
+    assert.deepEqual(r.map((x) => x.flag), ["egress_country_exploration", "clearance_exit_routing"]);
+  });
+});