forgedock 1.24.4 → 1.25.0

package/bin/engine/outcome-codes.mjs

@@ -44,13 +44,21 @@ export const OUTCOME_CODES = Object.freeze({
   INFRA_DISK_QUOTA: "infra.disk_quota",
   INFRA_CLI_SPAWN_TRANSIENT: "infra.cli_spawn_transient",
   CLI_TIMEOUT: "cli.timeout",
+  CLI_SPAWN_FAILED: "cli.spawn_failed", // forge#4129: deterministic spawn failure (E2BIG, ENOENT, EACCES, ...)
   LEASE_HELD: "lease.held",
   DEPENDENCY_OPEN: "dependency.open",
   DEPENDENCY_UNREADABLE: "dependency.unreadable",
+  DEPENDENCY_BLOCKED: "dependency.blocked",
+  // Lane resolution refusals (#4125): before any lease, comment or worktree; terminal reason `lane-refused`.
+  LANE_MISMATCH: "lane.mismatch",
+  LANE_DEFAULT_BRANCH: "lane.default_branch",
+  LANE_BRANCH_MISSING: "lane.branch_missing",
+  LANE_UNRESOLVED: "lane.unresolved",
   INVALID: "invalid",
   DECOMPOSED: "decomposed",
   // Lean core work-on (bin/lean) needs-human causes.
   BUILDER_BLOCKED: "builder.blocked",
+  BUILDER_BLOCK_UNTYPED: "builder.block_untyped",
   BUILDER_NO_EVIDENCE: "builder.no_evidence",
   BUILDER_NO_COMMIT: "builder.no_commit",
   REVIEW_FAILED: "review.failed",
@@ -106,6 +114,8 @@ export function codeForRunnerError(err) {
       return OUTCOME_CODES.INFRA_CLI_SPAWN_TRANSIENT;
     case "CLI_TIMEOUT":
       return OUTCOME_CODES.CLI_TIMEOUT;
+    case "CLI_SPAWN_FAILED":
+      return OUTCOME_CODES.CLI_SPAWN_FAILED;
     case "NO_API_KEY":
     case "NO_SDK":
     case "CLI_BACKEND_FAILED":
@@ -136,6 +146,7 @@ export function codeForTerminalReason(reason) {
     case "deferred": return OUTCOME_CODES.LEASE_HELD;
     case "dependency-open": return OUTCOME_CODES.DEPENDENCY_OPEN;
     case "dependency-unreadable": return OUTCOME_CODES.DEPENDENCY_UNREADABLE;
+    case "dependency-blocked": return OUTCOME_CODES.DEPENDENCY_BLOCKED;
     default: return UNCLASSIFIED;
   }
 }

package/bin/engine/phases.mjs

@@ -308,12 +308,29 @@ async function readIssueRecord(n, io) {
   } catch { return null; }
 }
 
+// A declaration line: optional list marker, optional bold, "Depends on" or "Blocked by" (any case), optional colon
+// inside or after the bold, then one or more `#N` separated by commas, "and", "&" or spaces (#4121).
+const DEPENDS_ON_RE = /^[ \t]*(?:[-*+][ \t]+)?(?:\*\*|__)?(?:depends on|blocked by)[ \t]*:?(?:\*\*|__)?[ \t]*:?[ \t]*(#\d+\b(?:[ \t]*(?:,|&|\band\b)?[ \t]*#\d+\b)*)/gim;
+
+/**
+ * Issue numbers an issue body declares it waits on: `**Depends on**: #X`, `**Depends on** #X, #Y`, `Depends on #X`,
+ * `- Depends on: #X and #Y`, `Blocked by #X`. Only declaration lines count; a mid-line mention is prose. Shared by the
+ * engine's admission (`openDependency`) and `forgedock orchestrate` so both agree on what blocks what.
+ * @returns {number[]} unique, positive, never `issue` itself
+ */
+export function parseDependsOn(body, issue = null) {
+  const out = new Set();
+  for (const m of String(body ?? "").replace(/\r\n/g, "\n").matchAll(DEPENDS_ON_RE)) {
+    for (const r of m[1].matchAll(/#(\d+)/g)) out.add(Number(r[1]));
+  }
+  return [...out].filter((n) => Number.isSafeInteger(n) && n > 0 && n !== Number(issue));
+}
+
 /**
- * forge#3932: does the issue declare a `**Depends on**: #N` dependency that is still OPEN?
+ * forge#3932: does the issue declare a `Depends on` / `Blocked by` dependency that is still OPEN?
  * Honoured only when the issue BODY's author is trusted (`isTrustedComment`: OWNER/MEMBER/COLLABORATOR,
- * Bot, or FORGE_TRAIL_TRUSTED_LOGINS) and only for the exact line decompose.md emits
- * (`**Depends on**: #N` at line start; loose "depends on/after" prose is ignored). A self-reference is
- * ignored. Returns `null` (nothing blocking), `{ open: [N, ...] }`, or `{ unreadable: true, detail }`
+ * Bot, or FORGE_TRAIL_TRUSTED_LOGINS) and only for a declaration line `parseDependsOn` accepts (mid-line
+ * prose is ignored). A self-reference is ignored. Returns `null` (nothing blocking), `{ open: [N, ...] }`, or `{ unreadable: true, detail }`
  * when the issue or a declared dependency cannot be read (fail closed: the caller refuses the run).
  * An empty read of the issue itself means "no body to trust" and yields `null`.
  */
@@ -324,8 +341,7 @@ export async function openDependency(issue, io) {
   }
   if (rec === null) return { unreadable: true, detail: `issue ${issue} could not be parsed for its **Depends on** line` };
   if (rec.empty || typeof rec.body !== "string" || !isTrustedComment(rec)) return null;
-  const deps = [...new Set([...rec.body.replace(/\r\n/g, "\n").matchAll(/^\*\*Depends on\*\*:[ \t]*#(\d+)\b/gm)].map((m) => Number(m[1])))]
-    .filter((n) => n > 0 && n !== Number(issue));
+  const deps = parseDependsOn(rec.body, issue);
   const open = [];
   for (const dep of deps) {
     let d;

package/bin/engine/runlog.mjs

@@ -73,7 +73,7 @@ export function scopeEvents(events, path = "full") {
 export function deriveState(allEvents, { path = "full" } = {}) {
   const events = scopeEvents(allEvents, path);
   /** @type {import("./phases.mjs").RunState} */
-  const s = { v: 0, run: null, issue: null, lane: "staging", committed: [],
+  const s = { v: 0, run: null, issue: null, lane: null, committed: [],
               phase: null, branch: null, pr: null, terminal: false,
               terminalReason: null, lease: null, lastRateLimit: null,
               remediationKind: null, outcomeCode: null };

package/bin/engine-cli.mjs

@@ -16,6 +16,8 @@ import { readLog, deriveState } from "./engine/runlog.mjs";
 import { assertOpenCodeNativeRuntime } from "./runner.mjs";
 import { parseForgeYaml } from "./forge-utils.mjs";
 import { makeEmitTelemetry } from "./engine/telemetry-seam.mjs";
+import { readBranches, resolveLane, isDefaultLane } from "./lean/lane.mjs";
+import { writeAtomic as writeResultAtomic } from "./lean/batch.mjs";
 
 /**
  * Workflow labels that mark an issue as "in the pipeline" (not yet terminal).
@@ -264,6 +266,19 @@ async function resolveDefaultRepo(io) {
   }
 }
 
+/**
+ * #4125: the default (production) branch is never a lane, on any path or entry point. Checks forge.yaml
+ * `branches.default` and GitHub's default branch (best effort here; the core path re-checks it fail-closed).
+ */
+export async function assertLaneNotDefault(io, lane, repo = null, cwd = process.cwd()) {
+  if (!lane) return;
+  let gh = null;
+  try { gh = String(await io.gh(["repo", "view", ...(repo ? [repo] : []), "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"])).trim() || null; } catch { gh = null; }
+  if (isDefaultLane(lane, [readBranches(cwd).default, gh].filter(Boolean))) {
+    throw new Error(`lane.default_branch: --lane ${lane} is the default branch. Lanes are staging or milestone/<slug>; promotion to the default branch is a human-merged release PR.`);
+  }
+}
+
 /**
  * Guards against cross-repo state confusion (forge#1593): `--repo` used to be
  * threaded into the `gh issue list` enumeration call but never into the
@@ -418,7 +433,11 @@ export function lastLocalRun(dir) {
  *   `runIssue` engine driver.
  *
  * Flags:
- *   --lane <lane>          Required — e.g. `main` or `staging`.
+ *   --lane <lane>          Core path: optional assertion. The lane is worked out from the issue (milestone →
+ *                          forge.yaml branches.feature_pattern, else branches.staging); a different --lane is refused
+ *                          (`lane-refused`, lane.mismatch) unless --lane-override. Full path: required.
+ *                          The default branch is never accepted (#4125).
+ *   --lane-override        Core path: accept a --lane that differs from the resolved lane (recorded in the trajectory).
  *   --repo <owner/repo>    Optional — must match the cwd-resolved repo (forge#1593).
  *   --backend <cli|api|auto>  Optional (forge#2028). Forwarded to every phase's
  *                          `runCommand()` call. Omit to keep runner.mjs's own
@@ -436,6 +455,8 @@ export function lastLocalRun(dir) {
  *                          expires or its same-host pid is dead, then continue.
  *                          Without it, a held lease exits `deferred` (code 75).
  *   --path <core|full|lean|auto>  Engine path; overrides forge.yaml engine.path. Default core (lean work-on); lean/auto are aliases; full is the legacy multi-phase pipeline.
+ *   --result-file <path>   Core path (#4121): write the run result as JSON to <path> (atomically, also when the run
+ *                          throws). `forgedock orchestrate` lanes report through it.
  *   --retry                Optional (forge#3511). Reopen a run that ended `engine-error`
  *                          (e.g. a session-limit hit) and resume from its last committed
  *                          phase. A run that ended `phase-complete` (multi-phase issue, phase merged,
@@ -444,15 +465,16 @@ export function lastLocalRun(dir) {
  */
 export async function runFromCli(argv, deps = {}) {
   const issue = parseInt(argv[0], 10);
-  if (!Number.isInteger(issue)) throw new Error("usage: forgedock run-issue <issue-number> --lane <lane> [--retry] [--wait-lease]");
+  if (!Number.isInteger(issue)) throw new Error("usage: forgedock run-issue <issue-number> [--lane <lane>] [--lane-override] [--retry] [--wait-lease]");
   assertOpenCodeNativeRuntime({ operation: "forgedock run-issue" });
   const lane = flag(argv, "--lane");
-  if (!lane) throw new Error("--lane is required: e.g. --lane main or --lane staging. No default to prevent accidental production targeting.");
+  if (argv.includes("--lane") && (!lane || lane.startsWith("--"))) throw new Error("--lane requires a value: staging or milestone/<slug>");
+  const laneOverride = argv.includes("--lane-override");
   const repo = flag(argv, "--repo");
   const backend = flag(argv, "--backend");
   const model = flag(argv, "--model");
   // Boolean flag: only counts at a flag position, never as another flag's value.
-  const retry = argv.some((a, i) => a === "--retry" && !["--lane", "--repo", "--backend", "--model", "--path"].includes(argv[i - 1]));
+  const retry = argv.some((a, i) => a === "--retry" && !["--lane", "--repo", "--backend", "--model", "--path", "--result-file"].includes(argv[i - 1]));
   // forge#3574: --wait-lease blocks (bounded by the lease TTL) until a live
   // holder's lease expires or becomes reclaimable. Same flag-position guard.
   const waitLease = argv.some((a, i) => a === "--wait-lease" && !["--lane", "--repo", "--backend", "--model"].includes(argv[i - 1]));
@@ -463,8 +485,11 @@ export async function runFromCli(argv, deps = {}) {
   if (enginePath !== "full" && (retry || waitLease)) {
     throw new Error("--retry and --wait-lease are not supported with the core path (a rerun resumes from the open PR or remote branch automatically); use --path full for them");
   }
+  // The full path takes the lane as given (its spec runs classify-lane), so it must be explicit; no default.
+  if (enginePath === "full" && !lane) throw new Error("--lane is required with --path full: staging or milestone/<slug>. No default to prevent accidental production targeting.");
   const io = deps.io ?? makeIo();
   await assertRepoMatchesCwd(io, repo);
+  await assertLaneNotDefault(io, lane, repo);
   const runIssueFn = deps.runIssue ?? runIssue;
   const agentId = `cli_${sanitizeLeaseHost(hostname())}_${process.pid}`;
   // Injectable for tests (forge#2175) — defaults to the real ~/.forge/runs dir.
@@ -496,10 +521,18 @@ export async function runFromCli(argv, deps = {}) {
     if (!leanRepo) throw new Error("core path needs the repo: pass --repo or run inside a checkout with a GitHub remote");
     const { runCore } = deps.leanModule ?? (await import("./lean/lean.mjs"));
     const leanIo = deps.leanIo ?? (await import("./lean/effects.mjs")).makeLeanIo({ repo: leanRepo });
-    const lres = await runCore({ issue, repo: leanRepo, lane, cwd: process.cwd(), dir, io: leanIo, path: enginePath, onProgress,
+    // #4121: a batch lane reports its result through --result-file (written atomically, also for a thrown run).
+    const resultFile = flag(argv, "--result-file");
+    const report = (r) => { if (resultFile) (deps.writeAtomic ?? writeResultAtomic)(resultFile, JSON.stringify(r) + "\n"); return r; };
+    let lres;
+    try {
+      lres = await runCore({ issue, repo: leanRepo, ...(lane ? { lane } : {}), laneOverride, branches: readBranches(), cwd: process.cwd(), dir, io: leanIo, path: enginePath, onProgress,
       emitTelemetry: deps.emitTelemetry ?? makeEmitTelemetry({ repo: leanRepo }),
       admission: readAdmission(), ...readCoreLimits(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) });
+    } catch (e) { report({ terminalReason: "engine-error", detail: String(e?.message ?? e).slice(0, 500) }); throw e; }
+    report(lres);
     if (lres.code === "host.busy") { console.log(`issue #${issue} → deferred (${lres.detail})`); return lres; }
+    if (lres.terminalReason === "lane-refused") { console.log(`issue #${issue} → lane-refused ${lres.code} (${lres.detail})`); return lres; }
     console.log(`issue #${issue} → ${lres.terminalReason}`);
     if (!["merged", "invalid"].includes(lres.terminalReason)) console.log(lres.detail ?? "");
     return lres;
@@ -565,7 +598,8 @@ export async function runFromCli(argv, deps = {}) {
  *
  * Flags:
  *   --dry-run   Print the stalled list and exit 0 without dispatching anything.
- *   --lane      Lane to pass to run-issue (required — no default to prevent accidental production targeting).
+ *   --lane      Optional lane assertion passed to run-issue. Omit it to let each issue's lane be worked out from
+ *               its milestone (#4125); the default branch is refused.
  *   --repo      GitHub repo (owner/repo). Must match the repo `gh` resolves by default
  *               (the cwd git remote) — cross-repo dispatch is refused (forge#1593),
  *               since state reads/writes are cwd-scoped and would otherwise silently
@@ -584,11 +618,12 @@ export async function runFromCli(argv, deps = {}) {
 export async function resumeStalledFromCli(argv, deps = {}) {
   const dryRun = argv.includes("--dry-run");
   const lane   = flag(argv, "--lane");
-  if (!lane) throw new Error("--lane is required for resume-stalled: e.g. --lane main or --lane staging.");
+  if (argv.includes("--lane") && (!lane || lane.startsWith("--"))) throw new Error("--lane requires a value: staging or milestone/<slug>");
   const repo   = flag(argv, "--repo");
 
   const io = deps.io ?? makeIo();
   await assertRepoMatchesCwd(io, repo);
+  await assertLaneNotDefault(io, lane, repo);
   const dispatch = deps.dispatch ?? runFromCli;
   const projector = makeProjector(io);
   const now = Date.now();
@@ -641,7 +676,7 @@ export async function resumeStalledFromCli(argv, deps = {}) {
   for (const issue of stalled) {
     console.log(`resume-stalled: dispatching #${issue} …`);
     try {
-      await dispatch([String(issue), "--lane", lane, ...(repo ? ["--repo", repo] : [])]);
+      await dispatch([String(issue), ...(lane ? ["--lane", lane] : []), ...(repo ? ["--repo", repo] : [])]);
       dispatched.push(issue);
     } catch (err) {
       const message = err?.message ?? String(err);
@@ -663,37 +698,166 @@ export async function resumeStalledFromCli(argv, deps = {}) {
 function flag(argv, name) { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }
 
 /**
- * `forgedock orchestrate <issue...> [--parallel K] [--lane L] [--repo owner/repo]`
- * Runs core work-on per issue with K concurrency (default 3), honouring `**Depends on**: #X` among the given issues.
- * Prints a compact summary table. Lane defaults to staging.
+ * `forgedock orchestrate <issue...> [--parallel K] [--lane L] [--lane-override] [--repo owner/repo] [--no-prefilter]`
+ * `forgedock orchestrate --resume <batch-id>` · `forgedock orchestrate --set-parallel <batch-id> <K>`
+ * Runs core work-on per issue with K concurrency (default 3), honouring `Depends on` / `Blocked by` among the given issues.
+ * A `dependency-open` issue is requeued behind its dependency; a `decomposed` one adds its sub-issues (#4124).
+ * The already-fixed pre-filter (#4123) runs before each lane unless `--no-prefilter`.
+ * Each issue gets its own lane, worked out from its milestone (#4125); `--lane` is an assertion checked per issue (a
+ * mismatch ends `lane-refused`). Dependency edges between lanes are printed before any lane starts. Prints a summary table.
+ * Durable (#4121): the batch is kept in `~/.forge/batches/<id>/` and each lane is a detached `run-issue` process, so
+ * `--resume <id>` continues after the dispatcher dies, re-adopting live lanes. `deferred` lanes are requeued by code,
+ * forge.yaml `orchestration.breaker` ({errors, window_min}, default 3 in 30) stops admissions on an engine-error
+ * burst, and `--set-parallel <id> K` changes K of a running batch.
  */
 export async function orchestrateFromCli(argv, deps = {}) {
-  const valued = ["--parallel", "--lane", "--repo", "--model"];
+  const batchMod = await import("./lean/batch.mjs");
+  const root = deps.batchRoot ?? batchMod.batchRoot();
+  if (argv.includes("--set-parallel")) {
+    const i = argv.indexOf("--set-parallel");
+    const b = batchMod.openBatch(root, argv[i + 1]);
+    if (!b.exists()) throw new Error(`no batch ${argv[i + 1]} in ${root}`);
+    const k = Number(argv[i + 2]);
+    b.setParallel(k);
+    console.log(`batch ${b.id}: parallel set to ${k}`);
+    return { ok: true, batch: b.id, parallel: k };
+  }
+  const resumeId = flag(argv, "--resume");
+  let batch, plan = null;
+  if (resumeId) {
+    batch = batchMod.openBatch(root, resumeId);
+    plan = batch.readPlan();
+    if (!plan) throw new Error(`no batch ${resumeId} in ${root}`);
+    argv = plan.argv;
+  }
+  const valued = ["--parallel", "--lane", "--repo", "--model", "--prefilter-model"];
   const issues = [];
   for (let i = 0; i < argv.length; i++) {
     if (valued.includes(argv[i])) { i++; continue; }
     if (/^#?\d+$/.test(argv[i])) issues.push(parseInt(argv[i].replace("#", ""), 10));
   }
-  if (!issues.length) throw new Error("usage: forgedock orchestrate <issue...> [--parallel K] [--lane L] [--repo owner/repo]");
+  if (!issues.length) throw new Error("usage: forgedock orchestrate <issue...> [--parallel K] [--lane L] [--lane-override] [--repo owner/repo] | --resume <id> | --set-parallel <id> <K>");
   const parallel = flag(argv, "--parallel") == null ? 3 : parseInt(flag(argv, "--parallel"), 10);
   if (!Number.isInteger(parallel) || parallel < 1) throw new Error("--parallel must be a positive integer");
-  const lane = flag(argv, "--lane") ?? "staging";
+  const lane = flag(argv, "--lane");
+  const laneOverride = argv.includes("--lane-override");
   const model = flag(argv, "--model");
   const io = deps.io ?? makeIo();
-  const repo = flag(argv, "--repo") ?? (await resolveDefaultRepo(io));
+  const repo = flag(argv, "--repo") ?? plan?.repo ?? (await resolveDefaultRepo(io));
   if (!repo) throw new Error("orchestrate needs the repo: pass --repo or run inside a checkout with a GitHub remote");
+  await assertLaneNotDefault(io, lane, repo);
+  const cwd = plan?.cwd ?? process.cwd();
+  if (!deps.allowTmpfs && process.env.FORGEDOCK_BATCH_ALLOW_TMPFS !== "1") batchMod.assertDiskPath(root);
+  if (!batch) {
+    const base = deps.batchId ?? batchMod.newBatchId();
+    batch = batchMod.openBatch(root, base);
+    for (let i = 2; batch.exists(); i++) batch = batchMod.openBatch(root, `${base}.${i}`); // never resume by accident
+    plan = { v: 1, id: batch.id, argv: [...argv], repo, cwd, created: new Date().toISOString() };
+    batch.writePlan(plan);
+    batch.setParallel(parallel);
+  } else {
+    // A resume is the operator's decision to continue: the breaker starts closed again.
+    const st = batch.store.load();
+    if (st) batch.store.save({ ...st, breaker: null, errorTimes: [] });
+  }
+  console.log(`batch: ${batch.id} (${batch.dir}); resume with: forgedock orchestrate --resume ${batch.id}`);
   const dir = deps.dir ?? runDir();
-  const { runCore } = deps.leanModule ?? (await import("./lean/lean.mjs"));
   const { orchestrate, formatTable } = await import("./lean/orchestrate.mjs");
   const leanIo = deps.leanIo ?? (await import("./lean/effects.mjs")).makeLeanIo({ repo });
-  const emitTelemetry = deps.emitTelemetry ?? makeEmitTelemetry({ repo });
+  const { makePrefilter, formatPrefilterSummary } = await import("./lean/prefilter.mjs");
+  const prefilter = argv.includes("--no-prefilter") ? null
+    : makePrefilter({ repo, cwd, io: leanIo, ...prefilterModel(argv) });
+  const branches = readBranches(cwd);
+  const fetched = new Set();
+  const laneOf = async (n) => {
+    const r = await resolveLane({ issue: n, repo, io: leanIo, cwd, branches, requested: lane, override: laneOverride });
+    if (r.ok && prefilter && !fetched.has(r.lane)) { fetched.add(r.lane); try { await leanIo.git(["fetch", "origin", r.lane], { cwd }); } catch { /* offline: use the local ref */ } }
+    return r;
+  };
+  // Lanes: in-process `runCore` when a lean module is injected (tests), otherwise detached `run-issue` processes.
+  let lanes;
+  if (deps.leanModule) {
+    const { runCore } = deps.leanModule;
+    const emitTelemetry = deps.emitTelemetry ?? makeEmitTelemetry({ repo });
+    lanes = { adopt: null, runOne: (n, ln) => runCore({ issue: n, repo, lane: ln, laneOverride, branches, cwd, dir, io: leanIo, agentId: `orch_${process.pid}_${n}`, emitTelemetry,
+      admission: readAdmission(cwd), ...readCoreLimits(cwd), ...(readMergeWait(cwd) ? { mergeWait: readMergeWait(cwd) } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model", cwd) ? { reviewerModel: readLeanSetting("reviewer_model", cwd) } : {}) }) };
+  } else {
+    lanes = batchMod.detachedLanes({ batch, cwd, script: deps.laneScript ?? fileURLToPath(new URL("./forgedock.mjs", import.meta.url)), bin: deps.laneBin, pollMs: deps.pollMs,
+      laneArgs: (n, ln) => ["--repo", repo, ...(ln ? ["--lane", ln] : []), ...(laneOverride ? ["--lane-override"] : []), ...(model ? ["--model", model] : [])] });
+  }
+  const orch = deps.orchestration ?? readOrchestration(cwd);
+  const crossLane = [];
   const rows = await orchestrate({
-    issues, parallel,
+    issues, parallel, prefilter, resolveLane: laneOf, store: batch.store, getParallel: batch.readParallel, ...lanes,
+    breaker: orch.breaker, maxDeferrals: orch.maxDeferrals, ...(deps.pollMs ? { pollMs: deps.pollMs } : {}),
+    onCrossLane: (e) => {
+      crossLane.push(e);
+      console.log(`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: async (n) => JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "body"])).body,
-    runOne: (n) => runCore({ issue: n, repo, lane, cwd: process.cwd(), dir, io: leanIo, agentId: `orch_${process.pid}_${n}`, emitTelemetry,
-      admission: readAdmission(), ...readCoreLimits(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) }),
-    onUpdate: (r) => console.log(`#${r.issue} → ${r.outcome}${r.detail && r.outcome !== "merged" ? ` (${r.detail})` : ""}`),
+    onUpdate: (r) => console.log(r.issue == null ? `${r.outcome}: ${r.detail}` : `#${r.issue} → ${r.outcome}${r.detail && r.outcome !== "merged" ? ` (${r.detail})` : ""}`),
   });
   console.log("\n" + formatTable(rows));
-  return { rows, ok: rows.every((r) => ["merged", "invalid"].includes(r.outcome)) };
+  const pfLine = formatPrefilterSummary(rows);
+  if (pfLine) console.log(pfLine);
+  if (crossLane.length) console.log(`cross-lane edges: ${crossLane.map((e) => `#${e.issue} (${e.lane}) → #${e.dependency} (${e.dependencyLane})`).join(", ")}`);
+  if (rows.some((r) => r.outcome === "held")) console.log(`held issues stay pending: forgedock orchestrate --resume ${batch.id}`);
+  return { rows, crossLane, batch: batch.id, ok: rows.every((r) => ["merged", "invalid", "decomposed"].includes(r.outcome)) };
+}
+
+/**
+ * forge.yaml `orchestration.breaker` ({errors, window_min}; default 3 engine-errors in 30 min; errors 0 turns it off) and
+ * `orchestration.max_deferrals` (default 3). The parser flattens one nested level, so the breaker keys arrive as
+ * `orchestration.errors|window_min` (or flat `breaker_errors|breaker_window_min`).
+ */
+export function readOrchestration(cwd = process.cwd()) {
+  let o = {};
+  try { o = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.orchestration ?? {}; } catch { o = {}; }
+  const int = (v, d) => { const n = Number(v); return v !== undefined && v !== "" && Number.isInteger(n) && n >= 0 ? n : d; };
+  const errors = int(o.breaker_errors ?? o.errors, 3), windowMin = int(o.breaker_window_min ?? o.window_min, 30);
+  return { breaker: errors > 0 && windowMin > 0 ? { errors, window_min: windowMin } : null, maxDeferrals: int(o.max_deferrals, 3) };
+}
+
+/** `--prefilter-model M`, else forge.yaml `engine.lean_prefilter_model`, else the pre-filter default. */
+function prefilterModel(argv) {
+  const m = flag(argv, "--prefilter-model") ?? readLeanSetting("prefilter_model");
+  return m ? { model: m } : {};
+}
+
+/**
+ * `forgedock triage <issue...> [--lane L] [--repo owner/repo] [--dry-run] [--prefilter-model M]` (#4123)
+ * Each issue is checked against its own lane (#4125); `--lane` is an assertion, a refused lane is reported and dropped.
+ * Runs only the already-fixed pre-filter: closes issues it proves fixed (with evidence) and prints the issues that
+ * still need a lane as the last line (`lanes: #1 #2`). `--dry-run` reports candidates without a model call or close.
+ */
+export async function triageFromCli(argv, deps = {}) {
+  const valued = ["--lane", "--repo", "--prefilter-model"];
+  const issues = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (valued.includes(argv[i])) { i++; continue; }
+    if (/^#?\d+$/.test(argv[i])) issues.push(parseInt(argv[i].replace("#", ""), 10));
+  }
+  if (!issues.length) throw new Error("usage: forgedock triage <issue...> [--lane L] [--repo owner/repo] [--dry-run]");
+  const lane = flag(argv, "--lane");
+  const io = deps.io ?? makeIo();
+  const repo = flag(argv, "--repo") ?? (await resolveDefaultRepo(io));
+  if (!repo) throw new Error("triage needs the repo: pass --repo or run inside a checkout with a GitHub remote");
+  const leanIo = deps.leanIo ?? (await import("./lean/effects.mjs")).makeLeanIo({ repo });
+  const { prefilterIssue, formatPrefilterSummary } = await import("./lean/prefilter.mjs");
+  const branches = readBranches();
+  const fetched = new Set();
+  const rows = [];
+  for (const n of [...new Set(issues)]) {
+    // #4125: each issue's own lane; `--lane` is an assertion. A refused lane never reaches the pre-filter or a lane.
+    const ln = await resolveLane({ issue: n, repo, io: leanIo, cwd: process.cwd(), branches, requested: lane, override: argv.includes("--lane-override") });
+    if (!ln.ok) { console.log(`#${n} → lane-refused (${ln.code}: ${ln.detail})`); rows.push({ issue: n, outcome: "lane-refused", cost_usd: 0, prefilter: null }); continue; }
+    if (!fetched.has(ln.lane)) { fetched.add(ln.lane); try { await leanIo.git(["fetch", "origin", ln.lane], { cwd: process.cwd() }); } catch { /* offline: use the local ref */ } }
+    const pf = await prefilterIssue({ issue: n, repo, lane: ln.lane, cwd: process.cwd(), io: leanIo, dryRun: argv.includes("--dry-run"), ...prefilterModel(argv) });
+    console.log(`#${n} → ${pf.closed ? "closed" : pf.candidate ? "candidate" : "lane"} (${pf.detail})`);
+    rows.push({ issue: n, outcome: pf.closed ? "invalid" : "pending", cost_usd: pf.cost_usd, prefilter: pf });
+  }
+  const lanes = rows.filter((r) => r.prefilter && !r.prefilter.closed).map((r) => r.issue);
+  console.log(formatPrefilterSummary(rows));
+  console.log(`lanes: ${lanes.map((n) => `#${n}`).join(" ") || "(none)"}`);
+  return { rows, lanes };
 }

package/bin/engine.mjs

@@ -381,7 +381,7 @@ export const ENGINE_VERSION = (() => {
 })();
 
 export async function runIssue(opts) {
-  const { issue, dir, agentId, lane = "staging", io, runner,
+  const { issue, dir, agentId, lane, io, runner,
           now = () => Date.now(), maxAttempts = DEFAULT_MAX_ATTEMPTS,
           commandsDir = fileURLToPath(new URL("../commands", import.meta.url)),
           // Optional execution-backend override for every phase's `runner()`
@@ -436,6 +436,8 @@ export async function runIssue(opts) {
   // any state I/O or timer creation, unchanged from the inline block this
   // replaces).
   validateRunIssueOptions({ backend, leaseTtlMs, leaseRenewIntervalMs, maxSessionLimitPauses, sessionLimitDefaultWaitMs });
+  // #4125: no silent lane default; the caller (run-issue --lane) names it, and the CLI refuses the default branch.
+  if (typeof lane !== "string" || !lane.trim()) throw new Error("runIssue: lane is required (staging or milestone/<slug>); there is no default");
 
   const projector = makeProjector(io);
 

package/bin/forgedock.mjs

@@ -3207,8 +3207,10 @@ function help() {
     ["npx forgedock disable [dir]", "Opt a directory out of ForgeDock"],
     ["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 run-issue <issue> --lane <lane> [--path core|full] [--retry] [--wait-lease]", "Run the lean core work-on on one issue (default; --path full = legacy multi-phase pipeline) (--retry reopens an engine-error run, or a needs-human run once the label is cleared; --wait-lease waits for a held lease; exit 75 = deferred, lease held)"],
-    ["npx forgedock orchestrate <issue...> [--parallel K] [--lane L]", "Run core work-on on several issues with bounded concurrency and Depends-on ordering"],
+    ["npx forgedock run-issue <issue> [--lane <lane>] [--lane-override] [--path core|full] [--retry] [--wait-lease]", "Run the lean core work-on on one issue (default; --path full = legacy multi-phase pipeline; the lane comes from the issue: milestone → milestone/<slug>, else staging; --lane is an assertion, never the default branch) (--retry reopens an engine-error run, or a needs-human run once the label is cleared; --wait-lease waits for a held lease; exit 75 = deferred, lease held)"],
+    ["npx forgedock orchestrate <issue...> [--parallel K] [--lane L]", "Run core work-on on several issues with bounded concurrency and Depends-on ordering; each issue on its own lane, cross-lane dependencies reported"],
+    ["npx forgedock orchestrate --resume <id> | --set-parallel <id> K", "Continue a batch after the dispatcher died (live lanes re-adopted), or change its concurrency live"],
+    ["npx forgedock triage <issue...> [--lane L] [--dry-run]", "Already-fixed pre-filter: close issues a merged PR or green CI already resolved; print the rest"],
     ["npx forgedock gc", "Prune stale per-run scratch dirs under ~/.forge/tmp/runs (older than 6h, owner dead)"],
     ["npx forgedock resume-stalled [--dry-run]", "Fleet stall recovery — re-dispatch expired-lease issues"],
     ["npx forgedock demo", "Set up a risk-free demo repo and print next steps"],
@@ -3783,10 +3785,10 @@ async function watch() {
 // The journey-routed commands render their own branded marks (hero/compact);
 // splash() would double-brand them. Engine-surface commands, help, and
 // unknown-command output keep the logo.
-const SPLASH_COMMANDS = new Set(["run", "run-issue", "orchestrate", "gc", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
+const SPLASH_COMMANDS = new Set(["run", "run-issue", "orchestrate", "triage", "gc", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
 const KNOWN_COMMANDS = new Set([
   "install", "init", "enable", "disable", "status", "uninstall", "update",
-  "run", "backend-check", "run-issue", "orchestrate", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "help", "--help", "-h",
+  "run", "backend-check", "run-issue", "orchestrate", "triage", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "help", "--help", "-h",
   "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
@@ -3974,7 +3976,7 @@ switch (command) {
       // an uncaught throw, which already set exitCode = 1 below. Now that
       // runIssue() resolves cleanly with a terminalReason instead of throwing,
       // preserve that same non-zero exit code for this reason too.
-      if (result && (result.terminalReason === "needs-human" || result.terminalReason === "engine-error" || result.terminalReason === "not-retryable" || result.terminalReason === "dependency-open" || result.terminalReason === "dependency-unreadable")) exitCode = 1;
+      if (result && (result.terminalReason === "needs-human" || result.terminalReason === "engine-error" || result.terminalReason === "not-retryable" || result.terminalReason === "dependency-open" || result.terminalReason === "dependency-unreadable" || result.terminalReason === "dependency-blocked" || result.terminalReason === "lane-refused")) exitCode = 1;
       // forge#3574: a lease-held deferral did NOT run the issue; exit 75
       // (EX_TEMPFAIL) so orchestrators neither count it as done nor as a failure.
       if (result && result.terminalReason === "deferred") exitCode = 75;
@@ -4002,6 +4004,16 @@ switch (command) {
     }
     break;
   }
+  case "triage": {
+    const { triageFromCli } = await import("./engine-cli.mjs");
+    try {
+      await triageFromCli(restArgs);
+    } catch (err) {
+      process.stderr.write(`${RED}${err.message}${RESET}\n`);
+      exitCode = 1;
+    }
+    break;
+  }
   case "resume-stalled": {
     const { resumeStalledFromCli } = await import("./engine-cli.mjs");
     try {

package/bin/lean/batch.mjs

@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Durable batch state and detached lanes for `forgedock orchestrate` (#4121).
+ *
+ * A batch lives in `~/.forge/batches/<id>/` (or `FORGEDOCK_BATCH_DIR`): `plan.json` (the command), `state.json` (the
+ * scheduler state, rewritten after every transition), `log.jsonl` (one line per lane update), `parallel` (live K) and
+ * `lanes/<issue>.{json,log}` (each lane's result and output). Every write is tmp + fsync + rename, and the root must be
+ * on disk, never tmpfs. A lane is its own session (`setsid` through `detached`), so killing the dispatcher leaves it
+ * running; a resumed dispatcher re-attaches to it by pid, checking `/proc/<pid>/cmdline` against its result path.
+ */
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+
+export const RAM_FS = new Set(["tmpfs", "ramfs"]);
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function batchRoot(env = process.env) {
+  return env.FORGEDOCK_BATCH_DIR || join(homedir(), ".forge", "batches");
+}
+
+/** `[{mount, type}]` from /proc/self/mounts; empty when unreadable (non-Linux). */
+export function readMounts(file = "/proc/self/mounts") {
+  try {
+    return readFileSync(file, "utf8").split("\n").filter(Boolean).map((l) => {
+      const [, mount, type] = l.split(" ");
+      return { mount: mount.replace(/\\(\d{3})/g, (_, o) => String.fromCharCode(parseInt(o, 8))), type };
+    });
+  } catch { return []; }
+}
+
+/** Filesystem type of the mount that holds `path` (longest mount-point prefix); null when unknown. */
+export function fsTypeOf(path, mounts = readMounts()) {
+  const p = resolve(path);
+  let best = null;
+  for (const m of mounts) {
+    const under = m.mount === "/" || p === m.mount || p.startsWith(m.mount.endsWith(sep) ? m.mount : m.mount + sep);
+    if (under && (!best || m.mount.length > best.mount.length)) best = m;
+  }
+  return best?.type ?? null;
+}
+
+/** Throws when `path` is on a RAM filesystem: a full tmpfs truncated an earlier state file to 0 bytes. */
+export function assertDiskPath(path, mounts = readMounts()) {
+  const type = fsTypeOf(path, mounts);
+  if (RAM_FS.has(type)) throw new Error(`batch state must be on disk, but ${path} is on ${type}; set FORGEDOCK_BATCH_DIR to a disk path`);
+}
+
+/** Write `data` to `file` atomically: a reader sees the old or the new content, never a truncated file. */
+export function writeAtomic(file, data) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  const fd = openSync(tmp, "w");
+  try { writeSync(fd, data); fsyncSync(fd); } finally { closeSync(fd); }
+  renameSync(tmp, file);
+}
+
+const readJson = (file) => { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } };
+
+export function newBatchId(now = Date.now(), pid = process.pid) {
+  return `b${new Date(now).toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15)}-${pid}`;
+}
+
+/** Handle on one batch directory. */
+export function openBatch(root, id) {
+  if (!ID_RE.test(String(id ?? ""))) throw new Error(`invalid batch id ${JSON.stringify(id)}`);
+  const dir = join(root, id);
+  const f = (name) => join(dir, name);
+  return {
+    id, dir,
+    exists: () => existsSync(f("plan.json")),
+    readPlan: () => readJson(f("plan.json")),
+    writePlan: (plan) => writeAtomic(f("plan.json"), JSON.stringify(plan, null, 2) + "\n"),
+    store: {
+      load: () => readJson(f("state.json")),
+      save: (state) => writeAtomic(f("state.json"), JSON.stringify(state) + "\n"),
+      log: (row) => { try { appendFileSync(f("log.jsonl"), JSON.stringify({ at: new Date().toISOString(), ...row }) + "\n"); } catch { /* the log is advisory */ } },
+    },
+    /** Live K: the `parallel` file, read on every scheduler pass; null when missing or invalid. */
+    readParallel: () => { try { const k = parseInt(readFileSync(f("parallel"), "utf8"), 10); return Number.isInteger(k) && k >= 1 ? k : null; } catch { return null; } },
+    setParallel: (k) => {
+      if (!Number.isInteger(k) || k < 1) throw new Error("parallel must be a positive integer");
+      writeAtomic(f("parallel"), `${k}\n`);
+    },
+    resultFile: (n) => f(join("lanes", `${n}.json`)),
+    logFile: (n) => f(join("lanes", `${n}.log`)),
+  };
+}
+
+/** True when `pid` is alive and (where /proc exists) its command line names `marker`, so a reused pid is not adopted. */
+export function isLaneAlive(pid, marker, { kill = process.kill.bind(process), procDir = "/proc" } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { kill(pid, 0); } catch (e) { if (e?.code !== "EPERM") return false; }
+  if (!existsSync(procDir)) return true;
+  let cmd;
+  try { cmd = readFileSync(join(procDir, String(pid), "cmdline"), "utf8"); } catch { return false; }
+  return !marker || cmd.split("\0").includes(marker);
+}
+
+/**
+ * Start one lane in its own session: `<bin> <script> run-issue <issue> ...args --result-file <lanes/N.json>`, output to
+ * `lanes/N.log`. A stale result from an earlier attempt is removed first. @returns {{pid:number}}
+ */
+export function launchLane({ batch, issue, args = [], bin = process.execPath, script, cwd = process.cwd(), env = process.env, spawnFn = spawn }) {
+  const rf = batch.resultFile(issue);
+  mkdirSync(dirname(rf), { recursive: true });
+  rmSync(rf, { force: true });
+  const out = openSync(batch.logFile(issue), "a");
+  try {
+    const child = spawnFn(bin, [script, "run-issue", String(issue), ...args, "--result-file", rf], { cwd, env, detached: true, stdio: ["ignore", out, out] });
+    child.on?.("error", () => { /* surfaces as a dead pid without a result */ });
+    child.unref?.();
+    return { pid: child.pid };
+  } finally { closeSync(out); }
+}
+
+/** Poll a lane until its result file appears; a lane that died without one is an engine-error. */
+export async function waitLane({ batch, issue, pid, alive = isLaneAlive, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), pollMs = 5000 }) {
+  const rf = batch.resultFile(issue);
+  for (;;) {
+    const r = readJson(rf);
+    if (r) return r;
+    if (!alive(pid, rf)) {
+      const last = readJson(rf); // it may have written the result just before exiting
+      return last ?? { terminalReason: "engine-error", detail: `lane pid ${pid} exited without a result; see ${batch.logFile(issue)}` };
+    }
+    await sleep(pollMs);
+  }
+}
+
+/** Lane seams for `orchestrate()`: `runOne` launches a detached lane, `adopt` re-attaches to a live one (else null). */
+export function detachedLanes({ batch, laneArgs, script, cwd, env, bin, alive = isLaneAlive, pollMs, spawnFn }) {
+  return {
+    runOne: async (n, lane, ctx = {}) => {
+      const { pid } = launchLane({ batch, issue: n, args: laneArgs(n, lane), script, cwd, env, bin, spawnFn });
+      ctx.onStart?.({ pid });
+      return waitLane({ batch, issue: n, pid, alive, pollMs });
+    },
+    adopt: async (n, rec) => {
+      const rf = batch.resultFile(n);
+      if (!existsSync(rf) && !alive(rec.pid, rf)) return null;
+      return waitLane({ batch, issue: n, pid: rec.pid, alive, pollMs });
+    },
+  };
+}