forgedock 1.50.0 → 1.51.0

package/bin/engine/outcome-codes.mjs

@@ -36,6 +36,7 @@ export const OUTCOME_CODES = Object.freeze({
   CI_TIMEOUT: "ci.timeout",
   BASE_CONFLICT: "base.conflict",
   RATE_LIMITED: "rate_limited",
+  BACKEND_AUTH: "backend.auth", // forge#5168: the claude CLI login failed ("Failed to authenticate"); deferred under the account hold, never engine-error, never the breaker
   HOST_BUSY: "host.busy",
   GH_UNAVAILABLE: "gh.unavailable", // forge#4157: `gh` unreachable after retries during the --repo identity check; run deferred, nothing posted
   GH_AUTH: "gh.auth", // forge#4662: gh answered HTTP 401 and one token refresh did not fix it; run deferred, a rerun resumes
@@ -149,6 +150,7 @@ export function codeForRunnerError(err) {
   if (isDiskQuotaError(err)) return OUTCOME_CODES.INFRA_DISK_QUOTA;
   if (err.usageLimit === true || (typeof err.resetAtEpochMs === "number" && Number.isFinite(err.resetAtEpochMs)))
     return OUTCOME_CODES.RATE_LIMITED;
+  if (err.authFailure === true) return OUTCOME_CODES.BACKEND_AUTH; // forge#5168
   switch (err.code) {
     case "CLI_SPAWN_TRANSIENT":
       return OUTCOME_CODES.INFRA_CLI_SPAWN_TRANSIENT;

package/bin/engine-cli.mjs

@@ -14,7 +14,7 @@ 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 { decomposedSubissues, isDecomposedRecord, 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";
@@ -34,6 +34,7 @@ import { parseTurnBudgets, formatTurnSummary, TURN_BUDGET_DEFAULTS } from "./lea
 import { writeAtomic as writeResultAtomic } from "./lean/batch.mjs";
 import { parseLightConfig, LIGHT_DEFAULTS } from "./lean/light.mjs";
 import { OUTCOME_CODES } from "./engine/outcome-codes.mjs";
+import * as batchHealth from "./lean/batch-health.mjs";
 import * as _autoChildren from "./lean/autochildren.mjs";
 
 /**
@@ -1675,7 +1676,11 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
       }
       for (const [n, l] of baseWaits) sink.line(`held: #${n} waits for ${l.map((w) => `#${w.dep} (${w.sha.slice(0, 10)}) on ${w.base}`).join(", ")}; admitted once the commit lands`);
       unmet = unmet.filter((x) => x.kind !== "commit");
-      if (unmet.length) throw new Error(`parallel milestone start refused: ${unmet.map((u) => `#${u.issue} depends on #${u.dep} (${u.why}; base ${u.base})`).join("; ")}. Merge the dependencies first, or pass --force "<reason>".`);
+      if (unmet.length) {
+        const refusal = new Error(`parallel milestone start refused: ${unmet.map((u) => `#${u.issue} depends on #${u.dep} (${u.why}; base ${u.base})`).join("; ")}. Merge the dependencies first, or pass --force "<reason>".`);
+        await alertRefusal({ root, issues, repo, cwd, argv, message: refusal.message, unmet, sink, gh: gateIo.gh, deps }); // #5167: recorded for `forgedock status`
+        throw refusal;
+      }
     }
     const base = deps.batchId ?? batchMod.newBatchId();
     batch = batchMod.openBatch(root, base);
@@ -1693,6 +1698,10 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
   }
   sink.batch?.(batch);
   sink.line(`batch: ${batch.id} (${batch.dir}); resume with: forgedock orchestrate --resume ${batch.id}`);
+  // #5167: early batch health at T+15/T+60 after plan.created and at batch end; the first unhealthy result alerts once
+  const healthConf = deps.healthConfig ?? readHealthConfig(cwd), healthNow = deps.healthNow ?? (() => Date.now());
+  const healthCreated = Number.isFinite(Date.parse(plan?.created ?? "")) ? Date.parse(plan.created) : healthNow();
+  sink.line(batchHealth.scheduleLine(batch.id, healthCreated, healthConf.checksMin));
   const dir = deps.dir ?? runDir();
   migrateRunLogs(dir); // #4432: split legacy per-issue logs by repo before any lane runs (best effort, never throws)
   const { orchestrate, formatTable, formatWaitSummary, formatSandboxSummary, formatOutcomeLists, formatAlertLines, estimateLaneMinutes, laneHistory, formatEstimateSummary } = await import("./lean/orchestrate.mjs");
@@ -1836,7 +1845,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
   // #4965: --auto-children overrides forge.yaml; it is part of plan.argv, so --resume keeps it
   const autoMod = _autoChildren, yamlAuto = readAutoChildren(cwd);
   const autoChildren = { mode: argv.includes("--auto-children") ? autoMod.parseAutoModeFlag(flag(argv, "--auto-children")) : yamlAuto.mode, pollS: yamlAuto.pollS,
-    epics: argv.flatMap((a, i) => (a === "--epic" && /^#?\d+$/.test(argv[i + 1] ?? "") ? [parseInt(argv[i + 1].replace("#", ""), 10)] : [])) };
+    epics: epicsOf(argv) };
   // #4304: recovery lanes run on the core path only (run-issue throws on --recover with full), so a full-path repo gets none.
   const recoveryOn = Boolean(orch.recovery?.maxAttempts) && (deps.enginePath !== undefined ? deps.enginePath : readEnginePath(cwd)) !== "full";
   if (orch.recovery?.maxAttempts && !recoveryOn) sink.line("recovery: off (engine.path is full; recovery lanes run on the core path only)");
@@ -1957,6 +1966,10 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
     preflight = async () => (await laneCheck.runLaneChecks({ exec: execForNeeds, env, io: hostIo })).filter((c) => !c.ok);
   }
   let rows, childFields = null; // #4965: the host gh's accepted `issue list --json` fields, read once from its help
+  const healthCheck = (checkpoint) => batchHealth.runCheck({ batch, checkpoint, config: healthConf, repo, now: healthNow,
+    alert: (text, health) => batchHealth.deliverAlert({ text, batchId: batch.id, health, sink, gh: (a) => leanIo.gh(a), repo, config: healthConf, epics: epicsOf(argv), ...(deps.notify ? { notify: deps.notify } : {}) }) });
+  let healthTimers = { cancel: () => {} };
+  try { healthTimers = batchHealth.scheduleChecks({ batch, created: healthCreated, config: healthConf, now: healthNow, ...(deps.healthTimer ? { setTimer: deps.healthTimer.set, clearTimer: deps.healthTimer.clear } : {}), check: healthCheck }); } catch { /* health is advisory */ }
   try {
     rows = await orchestrate({
       ...(estimate ? { estimate } : {}),
@@ -1967,7 +1980,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
       autoChildren,
       ...(autoMod.addsEpicChildren(autoChildren.mode) ? { getChildren: async () => ({ list: await autoMod.readChildList({ gh: (a) => leanIo.gh(a), repo, fields: childFields ??= await autoMod.hostListFields((a) => leanIo.gh(a)) }), elsewhere: autoMod.liveElsewhere({ batchMod, root, self: batch.id, repo }) }) } : {}),
       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, baseWait: baseWaits.size ? baseWaitOf(baseWaits, { io, leanIo, cwd }) : null, ...lanes,
-      breaker: orch.breaker, maxDeferrals: orch.maxDeferrals, ...(deps.pollMs ? { pollMs: deps.pollMs } : {}), ...budget, limits, identity, rotator, batchId: batch.id, drift, lifecycle, integration,
+      breaker: orch.breaker, maxDeferrals: orch.maxDeferrals, ...(Number.isInteger(orch.transientRetries) ? { transientRetries: orch.transientRetries } : {}), ...(deps.pollMs ? { pollMs: deps.pollMs } : {}), ...budget, limits, identity, rotator, batchId: batch.id, drift, lifecycle, integration,
       ...(registry ? { sched: { registry, batch: batch.id, repo, cap: liveLaneCap(orch.globalParallel ?? null, { cfg: readAdmission(cwd) }), 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.
@@ -1984,7 +1997,12 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
       // #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; },
+      // #5152: a NOT_PLANNED close labelled workflow:merged, or a decomposition whose sub-issues all closed, is delivered: CLOSED
+      issueState: async (n) => {
+        const v = JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "state,stateReason,labels"]));
+        if (v.state !== "CLOSED" || String(v.stateReason ?? "COMPLETED").toUpperCase() === "COMPLETED") return v.state;
+        return ["merged", "moved"].includes(await closedScope({ gh: (a) => leanIo.gh(a), repo, issue: n, labels: v.labels })) ? "CLOSED" : "CLOSED_NOT_PLANNED";
+      },
       // #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
@@ -2012,7 +2030,7 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
         : async (n) => { const v = await viewIssue(leanIo.gh, repo, n, "body,comments,author,milestone"); if ("milestone" in v) milestoneOf.set(n, v.milestone?.title ?? null); 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); }
+  } finally { for (const [sig, f] of Object.entries(handlers)) off(sig, f); healthTimers.cancel(); }
   try { await integration?.settle?.(); } catch { /* best effort: the state block is the record */ }
   const report = ["\n" + formatTable(rows), ...formatOutcomeLists(rows)];
   const pfLine = formatPrefilterSummary(rows);
@@ -2055,9 +2073,34 @@ export async function runBatch({ argv, cwd: callerCwd = process.cwd(), env: call
   let unfinished = false;
   try { unfinished = batch.pendingIssues().length > 0 && !batch.readCancel(); } catch { unfinished = false; } // a cancel ends the batch for good
   if (!unfinished) try { batch.writeReport({ rows, crossLane, ok, reclaimed, report: report.join("\n") }); } catch { /* the report is a cache of the rows */ }
+  try { await healthCheck("end"); } catch { /* #5167: health never fails a batch */ }
   return { rows, crossLane, batch: batch.id, reclaimed, ok };
 }
 
+/**
+ * #5152: how a CLOSED issue's scope ended, read from its labels rather than its `stateReason` (a NOT_PLANNED close of
+ * delivered work, legacy or not, is never dropped scope): "merged" (`workflow:merged`), "moved" (`workflow:decomposed`
+ * whose trusted FORGE:DECOMPOSED sub-issues are all closed), "moving" (decomposed, a sub-issue open or unreadable), or null
+ * (no delivery label: `stateReason` decides). `labels` is a `gh --json labels` or REST label list. Never throws.
+ */
+export async function closedScope({ gh, repo, issue, labels }) {
+  const names = (Array.isArray(labels) ? labels : []).map((l) => String(l?.name ?? l));
+  if (names.includes("workflow:merged")) return "merged";
+  if (!isDecomposedRecord({ labels })) return null;
+  // decomposedSubissues reads `repos/{owner}/{repo}/...`: pin the placeholder to this batch's repo
+  const io = { gh: (a) => gh(a.map((x) => String(x).replace("{owner}/{repo}", repo))) };
+  let subs = null;
+  try { subs = await decomposedSubissues(issue, io); } catch { subs = null; }
+  if (!subs) return "moving";
+  for (const s of subs) {
+    try {
+      const v = JSON.parse(String(await gh(["issue", "view", String(s), "-R", repo, "--json", "state"])));
+      if (String(v?.state ?? "").toUpperCase() !== "CLOSED") return "moving";
+    } catch { return "moving"; }
+  }
+  return "moved";
+}
+
 /**
  * #4481: the dispatch-time "already done" check: `{outcome:"merged", pr}` when the issue's own lane PR
  * (`feat/issue-N-lean`) merged, `{outcome:"invalid"}` when the issue is closed without one, else null. Anything
@@ -2075,7 +2118,7 @@ export function makeDispatchCheck({ gh, repo }) {
     } catch { return null; }
   };
   return async (n) => {
-    const iss = await json(["issue", "view", String(n), "-R", repo, "--json", "state,stateReason"]);
+    const iss = await json(["issue", "view", String(n), "-R", repo, "--json", "state,stateReason,labels"]);
     const state = typeof iss?.state === "string" ? iss.state.toUpperCase() : null;
     const notPlanned = String(iss?.stateReason ?? "").toUpperCase().replace(/\s/g, "_") === "NOT_PLANNED";
     const prs = await json(["pr", "list", "-R", repo, "--head", `feat/issue-${n}-lean`, "--state", "merged", "--json", "number,mergedAt", "--limit", "1"]);
@@ -2086,7 +2129,15 @@ export function makeDispatchCheck({ gh, repo }) {
       if (reopened === null || !Number.isFinite(mergedAt) || reopened > mergedAt) return null;
     }
     if (pr !== null) return { outcome: "merged", pr, detail: `PR #${pr} already merged` };
-    if (state === "CLOSED") return notPlanned ? { outcome: "invalid", detail: "issue closed (not planned)", final: true } : { outcome: "invalid", detail: "issue closed" }; // #4687: final = its dependents stay skipped
+    if (state === "CLOSED") {
+      // #5152: workflow:merged / a fully closed decomposition is delivered whatever the stateReason; a decomposition still
+      // moving is a completed close (its dependents' lanes wait on the sub-issues); only an unlabelled NOT_PLANNED is dropped scope
+      const scope = await closedScope({ gh, repo, issue: n, labels: iss?.labels });
+      if (scope === "merged") return { outcome: "merged", detail: "issue closed, workflow:merged" };
+      if (scope === "moved") return { outcome: "merged", detail: "issue decomposed; all sub-issues closed" };
+      if (scope === "moving") return { outcome: "invalid", detail: "issue closed: decomposed, sub-issues still open" };
+      return notPlanned ? { outcome: "invalid", detail: "issue closed (not planned)", final: true } : { outcome: "invalid", detail: "issue closed" }; // #4687: final = its dependents stay skipped
+    }
     // #4920: a live lease held by another lane, read from GitHub (any batch, any host, across restarts): no lane, no sandbox.
     // Release review #4931: never the open feat/issue-N-lean PR here. That branch is this issue's own lane, which a
     // relaunch or recovery lane resumes by design; a lane still running on it holds the lease.
@@ -2430,6 +2481,7 @@ export function readAutoChildren(cwd = process.cwd()) {
  * `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.transient_retries` (#5161; default 4, 0 off): backoff retries of a transient (gateway 5xx) engine-error.
  * `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()) {
@@ -2439,13 +2491,36 @@ 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), blockedLabel: String(o.blocked_label ?? "blocked").trim(), globalParallel: gp >= 1 ? gp : null,
+  return { breaker: errors > 0 && windowMin > 0 ? { errors, window_min: windowMin } : null, maxDeferrals: int(o.max_deferrals, 3), transientRetries: int(o.transient_retries, 4), 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) } };
 }
 
+/** `--epic N` operands of an orchestrate argv (#4965, #5167). */
+const epicsOf = (argv) => argv.flatMap((a, i) => (a === "--epic" && /^#?\d+$/.test(argv[i + 1] ?? "") ? [parseInt(argv[i + 1].replace("#", ""), 10)] : []));
+
+/**
+ * #5167: a refused milestone start leaves no batch dir: record it under the batch root for `forgedock status` and send
+ * the BATCH UNHEALTHY channels. Best effort: the caller rethrows the refusal unchanged.
+ */
+async function alertRefusal({ root, issues, repo, cwd, argv, message, unmet, sink, gh, deps }) {
+  try {
+    const rec = { at: new Date((deps.healthNow ?? Date.now)()).toISOString(), issues, repo, cwd, message, unmet: unmet.map(({ issue, dep, base }) => ({ issue, dep, base })) };
+    try { batchHealth.recordRefusal(root, rec); } catch { /* the stderr line still reports it */ }
+    const config = deps.healthConfig ?? readHealthConfig(cwd);
+    const health = batchHealth.evaluateHealth(null, { refused: rec, config, repo });
+    const text = batchHealth.formatAlert({ batchId: "(refused launch)", checkpoint: "launch", health });
+    await batchHealth.deliverAlert({ text, batchId: null, health, sink, gh: gh ? (a) => gh(a) : null, repo, config, epics: epicsOf(argv), ...(deps.notify ? { notify: deps.notify } : {}) });
+  } catch { /* never mask the refusal */ }
+}
+
+/** forge.yaml `orchestrate.health.*` (flattened to `orchestrate.*`) and `notify.command` (#5167); defaults when unset. */
+export function readHealthConfig(cwd = process.cwd()) {
+  try { return batchHealth.parseHealthConfig(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))); } catch { return batchHealth.parseHealthConfig(null); }
+}
+
 /**
  * forge.yaml `orchestrate.drift` (#4161): `{pairGrowth, packageLines, fileLines, blockDispatch, generatedGlobs}` with
  * only the positive-integer thresholds set, or null when no threshold and no `block_dispatch: true` is set (summary
@@ -2580,6 +2655,12 @@ export async function milestoneSyncFromCli(argv, deps = {}) {
   return run(argv, deps);
 }
 
+/** `forgedock fix-close-reasons <owner/repo> [--milestone m] [--apply]` (#5177): re-close delivered `not planned` issues as completed (lean/fixclosereasons.mjs). Resolves the exit code. */
+export async function fixCloseReasonsFromCli(argv, deps = {}) {
+  const { runFixCloseReasonsCli: run } = await import("./lean/fixclosereasons.mjs");
+  return run(argv, deps);
+}
+
 /**
  * `forgedock milestone train` (#4658): lean/train.mjs over `orchestrateFromCli` (one batch per milestone) and the #4657 lifecycle.
  * The train reads forge.yaml (`orchestration.global_parallel`, `milestones.close_on`) and never writes it.

package/bin/forgedock.mjs

@@ -977,6 +977,18 @@ async function gatherDashboardData(cwd) {
   return result;
 }
 
+/**
+ * #5167: unhealthy batches and recent launch refusals (or one batch's health with `--batch <id>`) under
+ * `forgedock status`, read from the batch root. Any read failure prints nothing.
+ */
+async function batchHealthSection(c, batchId) {
+  try {
+    const [{ batchRoot }, { statusLines }] = await Promise.all([import("./lean/batch.mjs"), import("./lean/batch-health.mjs")]);
+    const lines = statusLines(batchRoot(), batchId ? { batch: batchId } : {});
+    if (lines.length) c.stdout.write(`  batch health\n${lines.map((l) => (batchId ? `  ${l}` : l)).join("\n")}\n\n`);
+  } catch { /* status never fails on batch health */ }
+}
+
 /** Compact status screen for configured/managed directories. */
 async function statusScreen(c) {
   const state = resolveState(c.cwd);
@@ -3375,6 +3387,7 @@ function help() {
     ["npx forgedock init --minimal", "Generate a minimal forge.yaml (required sections only)"],
     ["npx forgedock enable [dir]", "Activate ForgeDock in a directory"],
     ["npx forgedock disable [dir]", "Opt a directory out of ForgeDock"],
+    ["npx forgedock fix-close-reasons <owner/repo> [--milestone <m>] [--apply]", "Re-close issues that were closed not planned but carry workflow:merged or workflow:decomposed (delivered, not dropped) as completed, with a comment; dry run unless --apply; workflow:invalid issues are never touched"],
     ["npx forgedock status [dir]", "Show ForgeDock state for a directory"],
     ["npx forgedock run <cmd> [args]", "Run a command headlessly (local claude CLI or Anthropic API)"],
     ["npx forgedock bootstrap <idea|docs> [--dry-run] [--spike <path>] | --plan <plan.json> [--dry-run]", "Headless /bootstrap: idea to orchestrate-ready backlog (--dry-run previews milestones, titles, DAG and estimated agent cost without GitHub writes); --plan validates and creates (or previews) a plan, and re-running resumes from GitHub"],
@@ -3980,7 +3993,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", "issue-watch", "prod-watch", "selftest", "labels", "config", "stats", "limits", "decisions", "sched", "schedd", "pool", "check", "guide", "help", "--help", "-h",
+  "run", "bootstrap", "backend-check", "run-issue", "orchestrate", "milestone", "milestone-sync", "fix-close-reasons", "guards", "triage", "probe", "review-staging", "gc", "resume-stalled", "demo", "doctor", "watch", "issue-watch", "prod-watch", "selftest", "labels", "config", "stats", "limits", "decisions", "sched", "schedd", "pool", "check", "guide", "help", "--help", "-h",
   "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
@@ -4062,8 +4075,12 @@ switch (command) {
   }
   case "status": {
     const c = ctx();
-    if (positional[1]) c.cwd = resolve(positional[1]);
+    // #5167: `--batch <id>` is not the status directory
+    const statusArgs = positional.slice(1), bi = statusArgs.indexOf("--batch");
+    const statusDir = statusArgs.find((a, i) => !(bi !== -1 && (i === bi || i === bi + 1)));
+    if (statusDir) c.cwd = resolve(statusDir);
     await statusScreen(c);
+    await batchHealthSection(c, bi === -1 ? null : statusArgs[bi + 1] ?? null);
     break;
   }
   case "uninstall":
@@ -4334,6 +4351,17 @@ switch (command) {
     }
     break;
   }
+  case "fix-close-reasons": {
+    // Migration helper (#5177): delivered issues closed `not planned` are re-closed `completed`; dry run unless --apply.
+    const { fixCloseReasonsFromCli } = await import("./engine-cli.mjs");
+    try {
+      exitCode = await fixCloseReasonsFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
   case "milestone": {
     // Native unattended milestone train (#4658): `forgedock milestone train <slug...>`.
     const { trainFromCli } = await import("./engine-cli.mjs");

package/bin/lean/batch-health.mjs

@@ -0,0 +1,219 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Early batch health (#5167). A batch that fails in its first minutes (roots engine-error, the rest skipped) or is refused
+ * at launch used to look "launched" until someone read its log. The batch runner (`runBatch`, the schedd per-batch runner)
+ * evaluates the batch's `state.json` at T+15 and T+60 min after `plan.created` and once when the batch ends; the first
+ * unhealthy evaluation emits one `BATCH UNHEALTHY` alert (a runner line, a GitHub comment on `orchestrate.health.issue`
+ * or the batch's `--epic` issues, and `notify.command`) with its causes and recovery commands. `health.json` in the batch
+ * dir records the checkpoints done and the alert, so a restarted daemon re-arms only the remaining checks and never alerts
+ * twice. A refused launch has no batch dir: it is recorded in `<batch root>/refusals.json`. `forgedock status` reads both.
+ */
+import { readFileSync } from "node:fs";
+import { spawn as spawnProc } from "node:child_process";
+import { join } from "node:path";
+import { listBatches, openBatch, REQUEUABLE, writeAtomic } from "./batch.mjs";
+
+export const DEFAULT_HEALTH = Object.freeze({ rootFailed: true, terminalShare: 0.5, stalled: true, checksMin: Object.freeze([15, 60]), issue: null, notifyCommand: null });
+/** Outcomes that end a row well: never counted against the batch. */
+export const GOOD_END = new Set(["merged", "invalid", "decomposed"]);
+export const REFUSALS_FILE = "refusals.json";
+export const REFUSAL_KEEP = 20;
+export const REFUSAL_SHOW_MS = 24 * 3600 * 1000;
+export const NOTIFY_TIMEOUT_MS = 30 * 1000;
+
+const readJson = (file) => { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } };
+const list = (ns) => ns.map((n) => `#${n}`).join(", ");
+
+/** forge.yaml (parsed) → health config. The parser flattens `orchestrate.health.*` to `orchestrate.*`. */
+export function parseHealthConfig(yaml) {
+  const o = yaml?.orchestrate && typeof yaml.orchestrate === "object" ? yaml.orchestrate : {};
+  const bool = (v, d) => (v === undefined || String(v).trim() === "" ? d : String(v).trim().toLowerCase() !== "false");
+  const share = Number(o.terminal_share);
+  const issue = Number(String(o.issue ?? "").replace(/^#/, ""));
+  const checks = String(o.checks_min ?? "").replace(/^\[|\]$/g, "").split(",").map((x) => Number(x.trim())).filter((n) => Number.isFinite(n) && n > 0);
+  const cmd = String(yaml?.notify?.command ?? "").trim();
+  return { rootFailed: bool(o.root_failed, DEFAULT_HEALTH.rootFailed), terminalShare: o.terminal_share !== undefined && Number.isFinite(share) && share >= 0 && share <= 1 ? share : DEFAULT_HEALTH.terminalShare,
+    stalled: bool(o.stalled, DEFAULT_HEALTH.stalled), checksMin: checks.length ? checks : [...DEFAULT_HEALTH.checksMin], issue: Number.isSafeInteger(issue) && issue > 0 ? issue : null, notifyCommand: cmd || null };
+}
+
+/** Issues of the batch with no dependency edge to another issue of the batch. */
+export function rootsOf(state) {
+  const order = (state?.order ?? []).map(Number), inBatch = new Set(order);
+  return order.filter((n) => !(state?.deps?.[n] ?? []).some((d) => inBatch.has(Number(d)) && Number(d) !== n));
+}
+
+/**
+ * `{healthy, causes:[{code, issues, detail}], recovery:[cmd]}` for one batch state. `held`: operator-held issues (not a
+ * stall); `refused`: a refusal record (the launch never started). Pure.
+ */
+export function evaluateHealth(state, { held = [], refused = null, config = DEFAULT_HEALTH, batchId = "<id>", repo = null } = {}) {
+  const causes = [], recovery = [];
+  if (refused) {
+    causes.push({ code: "refused", issues: refused.issues ?? [], detail: refused.message ?? "launch refused" });
+    const relaunch = `forgedock orchestrate ${(refused.issues ?? []).join(" ")}${repo ? ` --repo ${repo}` : ""}`;
+    recovery.push(`merge the unmet dependencies, then: ${relaunch}`, `${relaunch} --force "<why the unmet dependencies are acceptable>"`);
+    return { healthy: false, causes, recovery };
+  }
+  const order = (state?.order ?? []).map(Number);
+  const running = new Set(Object.keys(state?.running ?? {}).map(Number));
+  const pending = new Set((state?.pending ?? []).map(Number));
+  const results = state?.results ?? {};
+  const outcomeOf = (n) => results[n]?.outcome;
+  // Terminal and not good: a final row not running and not waiting again (a held row stays pending but counts).
+  const bad = (n) => { const o = outcomeOf(n); return o !== undefined && !GOOD_END.has(o) && !running.has(n) && (!pending.has(n) || o === "held"); };
+  const merged = order.filter((n) => outcomeOf(n) === "merged").length;
+  const failedRoots = rootsOf(state).filter(bad);
+  if (config.rootFailed && failedRoots.length) causes.push({ code: "root-failed", issues: failedRoots, detail: `root ${failedRoots.map((n) => `#${n} ${outcomeOf(n)}`).join(", ")}` });
+  const badRows = order.filter(bad);
+  if (order.length && merged === 0 && badRows.length && badRows.length / order.length >= config.terminalShare) {
+    const by = {};
+    for (const n of badRows) by[outcomeOf(n)] = (by[outcomeOf(n)] ?? 0) + 1;
+    causes.push({ code: "terminal-share", issues: badRows, detail: `${badRows.length}/${order.length} rows ended non-merged (${Object.entries(by).map(([o, k]) => `${k} ${o}`).join(", ")}), 0 merged` });
+  }
+  const heldSet = new Set(held.map(Number));
+  const waiting = [...pending].filter((n) => !heldSet.has(n));
+  if (config.stalled && !running.size && waiting.length && state?.phase !== "setup" && !state?.cancelled) {
+    causes.push({ code: "stalled", issues: waiting, detail: `0 lanes running while ${waiting.length} issue${waiting.length === 1 ? "" : "s"} pending${state?.breaker ? " (breaker tripped)" : ""}` });
+  }
+  if (!causes.length) return { healthy: true, causes, recovery };
+  const failed = [...new Set(causes.filter((c) => c.code !== "stalled").flatMap((c) => c.issues))];
+  const requeue = failed.filter((n) => REQUEUABLE(outcomeOf(n))), relaunch = failed.filter((n) => !REQUEUABLE(outcomeOf(n)));
+  if (requeue.length) recovery.push(`forgedock orchestrate --requeue ${batchId} ${requeue.join(" ")} --reason "batch unhealthy"`);
+  if (relaunch.length) recovery.push(`forgedock orchestrate ${relaunch.join(" ")}${repo ? ` --repo ${repo}` : ""}   # after fixing the cause (see lanes/<n>.log)`);
+  if (pending.size) recovery.push(`forgedock orchestrate --resume ${batchId}`);
+  recovery.push(`forgedock status --batch ${batchId}`, `forgedock orchestrate --cancel ${batchId}`);
+  return { healthy: false, causes, recovery };
+}
+
+/** The `BATCH UNHEALTHY` text: top causes, then the exact recovery commands. */
+export function formatAlert({ batchId, checkpoint, health }) {
+  return [`BATCH UNHEALTHY ${batchId} (${checkpoint})`, ...health.causes.slice(0, 5).map((c) => `  cause: ${c.code}: ${c.detail}${c.issues?.length && c.code !== "refused" ? ` [${list(c.issues.slice(0, 12))}${c.issues.length > 12 ? ", …" : ""}]` : ""}`),
+    "  recovery:", ...health.recovery.map((r) => `    ${r}`)].join("\n");
+}
+
+export const healthPath = (dir) => join(dir, "health.json");
+export const readHealth = (dir) => { const h = readJson(healthPath(dir)); return h && typeof h === "object" && !Array.isArray(h) ? h : null; };
+export const writeHealth = (dir, h) => writeAtomic(healthPath(dir), JSON.stringify(h) + "\n", { private: true });
+
+/** The checkpoints `[{label, at}]` (`T+<min>`) for a batch created at `created` (ms). */
+export const checkpointsOf = (created, checksMin = DEFAULT_HEALTH.checksMin) => checksMin.map((m) => ({ label: `T+${m}`, at: created + m * 60000 }));
+
+/** `health checks: T+15 14:05Z, T+60 14:50Z; forgedock status --batch <id>` */
+export function scheduleLine(batchId, created, checksMin = DEFAULT_HEALTH.checksMin) {
+  const hhmm = (ms) => `${new Date(ms).toISOString().slice(11, 16)}Z`;
+  return `health checks: ${checkpointsOf(created, checksMin).map((c) => `${c.label} ${hhmm(c.at)}`).join(", ")}, and at batch end; forgedock status --batch ${batchId}`;
+}
+
+/**
+ * One checkpoint: evaluate the batch, persist it, and call `alert(text, health)` on the first unhealthy result only.
+ * @returns the evaluation, plus `alerted` when this call raised the alert
+ */
+export async function runCheck({ batch, checkpoint, config = DEFAULT_HEALTH, repo = null, now = () => Date.now(), alert = async () => {} }) {
+  const state = batch.store.load() ?? {};
+  let held = [];
+  try { held = batch.readHeld?.() ?? []; } catch { held = []; }
+  const health = evaluateHealth(state, { held, config, batchId: batch.id, repo });
+  const prev = readHealth(batch.dir) ?? {};
+  const at = new Date(now()).toISOString();
+  const next = { ...prev, checks: { ...(prev.checks ?? {}), [checkpoint]: at }, last: { at, checkpoint, healthy: health.healthy, causes: health.causes, recovery: health.recovery } };
+  const fire = !health.healthy && !prev.alertedAt;
+  if (fire) Object.assign(next, { alertedAt: at, alert: formatAlert({ batchId: batch.id, checkpoint, health }) });
+  try { writeHealth(batch.dir, next); } catch { /* health is advisory */ }
+  if (fire) { try { await alert(next.alert, health); } catch { /* every channel is best effort */ } }
+  return { ...health, alerted: fire };
+}
+
+/**
+ * Arm the timed checkpoints not yet done (per `health.json`); past-due ones run on the next tick. Timers are unref'd.
+ * @returns `{cancel()}`
+ */
+export function scheduleChecks({ batch, created, config = DEFAULT_HEALTH, now = () => Date.now(), setTimer = setTimeout, clearTimer = clearTimeout, check }) {
+  const done = readHealth(batch.dir)?.checks ?? {};
+  const timers = checkpointsOf(created, config.checksMin).filter((c) => !done[c.label]).map((c) => {
+    const t = setTimer(() => { Promise.resolve().then(() => check(c.label)).catch(() => {}); }, Math.max(0, c.at - now()));
+    t?.unref?.();
+    return t;
+  });
+  return { cancel: () => { for (const t of timers) clearTimer(t); } };
+}
+
+/** Run `notify.command` through the shell: alert JSON on stdin, FORGEDOCK_ALERT_* in env. Never throws. */
+export function runNotify(command, payload, { spawn = spawnProc, timeoutMs = NOTIFY_TIMEOUT_MS, env = process.env } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, { shell: true, stdio: ["pipe", "ignore", "ignore"], env: { ...env, FORGEDOCK_ALERT: "BATCH_UNHEALTHY", FORGEDOCK_ALERT_BATCH: String(payload.batch ?? ""), FORGEDOCK_ALERT_TEXT: String(payload.text ?? "") } });
+    } catch (e) { return resolve({ ok: false, error: String(e?.message ?? e) }); }
+    const timer = setTimeout(() => { try { child.kill("SIGKILL"); } catch { /* gone */ } resolve({ ok: false, error: `timed out after ${Math.round(timeoutMs / 1000)}s` }); }, timeoutMs);
+    timer.unref?.();
+    child.on("error", (e) => { clearTimeout(timer); resolve({ ok: false, error: String(e?.message ?? e) }); });
+    child.on("close", (code) => { clearTimeout(timer); resolve(code === 0 ? { ok: true } : { ok: false, error: `exit ${code}` }); });
+    try { child.stdin?.on?.("error", () => {}); child.stdin?.end?.(JSON.stringify(payload) + "\n"); } catch { /* the command ignores stdin */ }
+  });
+}
+
+/**
+ * The alert channels: a runner line, a comment on the configured issue (else the batch's epics), and notify.command.
+ * Each is best effort.
+ */
+export async function deliverAlert({ text, batchId, health, sink = { line: () => {} }, gh = null, repo = null, config = DEFAULT_HEALTH, epics = [], notify = runNotify }) {
+  sink.line(text);
+  const targets = config.issue ? [config.issue] : [...new Set(epics)];
+  if (gh && repo) for (const n of targets) {
+    try { await gh(["issue", "comment", String(n), "-R", repo, "--body", `<!-- FORGE:BATCH-HEALTH batch=${batchId} -->\n## BATCH UNHEALTHY\n\`\`\`text\n${text}\n\`\`\``]); } catch (e) { sink.line(`health: comment on #${n} failed (${String(e?.message ?? e).slice(0, 160)})`); }
+  }
+  if (config.notifyCommand) {
+    const r = await notify(config.notifyCommand, { alert: "BATCH_UNHEALTHY", batch: batchId, repo, text, causes: health?.causes ?? [], recovery: health?.recovery ?? [] });
+    if (!r?.ok) sink.line(`health: notify.command failed (${r?.error ?? "unknown"})`);
+  }
+}
+
+/** Record a refused launch under the batch root (no batch dir exists); keeps the newest `REFUSAL_KEEP`. */
+export function recordRefusal(root, rec) {
+  const prev = readRefusals(root, { maxAgeMs: Infinity });
+  writeAtomic(join(root, REFUSALS_FILE), JSON.stringify([...prev, rec].slice(-REFUSAL_KEEP)) + "\n", { private: true });
+}
+
+/** Refusals newer than `maxAgeMs`, oldest first. */
+export function readRefusals(root, { now = Date.now(), maxAgeMs = REFUSAL_SHOW_MS } = {}) {
+  const v = readJson(join(root, REFUSALS_FILE));
+  return (Array.isArray(v) ? v : []).filter((r) => r && typeof r.at === "string" && now - Date.parse(r.at) <= maxAgeMs);
+}
+
+/** Health of one batch for `forgedock status --batch <id>`. */
+export function batchStatusLines(root, id, { now = Date.now() } = {}) {
+  const b = openBatch(root, id);
+  if (!b.exists()) return [`batch ${id}: not found in ${root}`];
+  const h = readHealth(b.dir), plan = b.readPlan() ?? {};
+  const created = Date.parse(plan.created ?? "");
+  const out = [];
+  if (h?.alertedAt) out.push(`batch ${id}: UNHEALTHY since ${h.alertedAt}`, ...String(h.alert ?? "").split("\n").slice(1));
+  else if (h?.last) out.push(`batch ${id}: healthy at ${h.last.checkpoint} (${h.last.at})`);
+  else out.push(`batch ${id}: no health check yet`);
+  if (h?.alertedAt && h.last && h.last.at !== h.alertedAt) out.push(`  last check ${h.last.checkpoint} (${h.last.at}): ${h.last.healthy ? "healthy" : h.last.causes.map((c) => c.code).join(", ")}`);
+  if (Number.isFinite(created)) {
+    const due = checkpointsOf(created, DEFAULT_HEALTH.checksMin).filter((c) => !h?.checks?.[c.label]);
+    if (due.length && !b.readReport()) out.push(`  next checks: ${due.map((c) => `${c.label} ${new Date(c.at).toISOString().slice(11, 16)}Z${c.at < now ? " (due)" : ""}`).join(", ")}`);
+  }
+  return out;
+}
+
+/**
+ * `forgedock status` lines: unhealthy batches still unresolved (no report, or alerted within a day) and recent refusals;
+ * with `batch`, that one batch's health.
+ */
+export function statusLines(root, { now = Date.now(), batch = null } = {}) {
+  if (batch) return batchStatusLines(root, batch, { now });
+  const out = [];
+  for (const id of listBatches(root)) {
+    try {
+      const b = openBatch(root, id), h = readHealth(b.dir);
+      if (!h?.alertedAt || (b.readReport() && now - Date.parse(h.alertedAt) > REFUSAL_SHOW_MS)) continue;
+      const causes = (h.last?.healthy === false ? h.last.causes : null) ?? [];
+      out.push(`  BATCH UNHEALTHY ${id} (since ${h.alertedAt})${causes.length ? `: ${causes.map((c) => c.detail).join("; ")}` : ""} — forgedock status --batch ${id}`);
+    } catch { /* an unreadable batch has no line */ }
+  }
+  for (const r of readRefusals(root, { now })) out.push(`  LAUNCH REFUSED ${r.at}: ${String(r.message ?? "").slice(0, 300)}`);
+  return out;
+}