forgedock 1.20.0 → 1.22.0

package/bin/engine/phases.mjs

@@ -913,12 +913,14 @@ export const PHASES = [
         // forge#3542: only a full-line marker in a trusted comment counts.
         // forge#4021: an in-PR fix re-armed by the re-gate (the newest trail after the newest marker reports
         // INPR-FIX-REQUESTED) needs a FRESH marker, or M0's per-kind guard sees the first trail as this dispatch's
-        // and returns ALREADY_DONE. The marker count is also the bound (detectOutcome allows one re-arm).
+        // and returns ALREADY_DONE. The marker count is also the bound (detectOutcome allows one re-arm); it is
+        // enforced here too, where the marker is posted, so a crash-resume after round 2 never posts marker 3.
         const sentinel = `FORGE:${boundMarker}: pr=${pr}`;
         let markerAt = -1;
         comments.forEach((b, i) => { if (hasSentinelLine(b, sentinel)) markerAt = i; });
         const trailAfter = markerAt < 0 ? null : latestMarked(comments.slice(markerAt + 1), PHASE_MARKERS.remediate.header, PHASE_MARKERS.remediate.completionMarker);
-        const rearmed = kind === "inpr-fix" && trailAfter !== null && INPR_REQUESTED_RE.test(trailAfter);
+        const priorMarkers = comments.filter((b) => hasSentinelLine(b, sentinel)).length;
+        const rearmed = kind === "inpr-fix" && trailAfter !== null && INPR_REQUESTED_RE.test(trailAfter) && priorMarkers < 2;
         if (markerAt < 0 || rearmed) {
           await io.gh(["issue", "comment", String(state.issue), "--body",
             `${marker}\nReview handed PR #${pr} to remediation (${kind}); the engine is dispatching it once.`]);
@@ -975,6 +977,18 @@ export const PHASES = [
       };
       // forge#3685: a resume that ends HELD posts a non-terminal FORGE:REMEDIATION_HELD record (no COMPLETE).
       // Newest-wins between the held record and COMPLETE, by position in the (trusted, scoped) comment list.
+      // forge#3947: a trail posted after THIS dispatch's marker is this run's outcome; a push that moved the PR
+      // head after it was posted must not reclassify it. Only an older trail is judged against the live head.
+      const headStale = async () => {
+        let dispatchAt = -1, trailAt = -1;
+        const dispatchSentinel = `${REMEDIATION_DISPATCH_MARKER}: pr=${state.pr}`;
+        scoped.forEach((b, i) => {
+          if (state.pr != null && hasSentinelLine(b, dispatchSentinel)) dispatchAt = i;
+          if (startsWithHeader(b, PHASE_MARKERS.remediate.header) && hasSentinelLine(b, completion)) trailAt = i;
+        });
+        if (dispatchAt >= 0 && trailAt > dispatchAt) return false;
+        return remediationHeadStale(state, io);
+      };
       const isHeld = (b) => startsWithHeader(b, REMEDIATION_HELD_MARKER) && hasSentinelLine(b, REMEDIATION_HELD_MARKER);
       let heldAt = -1, completeAt = -1;
       scoped.forEach((b, i) => {
@@ -1037,7 +1051,7 @@ export const PHASES = [
         case "RE-ESCALATED":
         case "UNFIXABLE":
           // forge#3931: a trail recorded against an older PR head must not be replayed as this run's outcome.
-          if (await remediationHeadStale(state, io))
+          if (await headStale())
             return { status: "failed", code: OC.REMEDIATE_NO_MARKER, detail: `stale ${completion} trail: PR head moved since it was recorded` };
           // Both leave the issue at needs-human (a fresh escalation, or a
           // policy judgment call respectively) — reuse the existing
@@ -1051,7 +1065,7 @@ export const PHASES = [
         case "INPR-FIX-REQUESTED": {
           // forge#4021: the re-review approved but posted a FORGE:INPR_FIX work order. One further in-PR fix
           // remediation is allowed (never needs-human on the first request); the bound marker count caps it.
-          if (await remediationHeadStale(state, io))
+          if (await headStale())
             return { status: "failed", code: OC.REMEDIATE_NO_MARKER, detail: `stale ${completion} trail: PR head moved since it was recorded` };
           if (await prMerged()) return mergedResult(reGateOutcome);
           const round = /\*\*INPR round\*\*:\s*(\d+)/.exec(latest)?.[1] ?? null;
@@ -1063,7 +1077,7 @@ export const PHASES = [
           return { status: "committed", code: OC.REMEDIATE_INPR_REQUESTED, outputs: { ...outputs, remediation: "inpr-fix" } };
         }
         case "REREVIEW-REQUIRED":
-          if (await remediationHeadStale(state, io))
+          if (await headStale())
             return { status: "failed", code: OC.REMEDIATE_NO_MARKER, detail: `stale ${completion} trail: PR head moved since it was recorded` };
           return { status: "committed", terminalReason: "needs-human", code: OC.REMEDIATE_RE_ESCALATED, outputs: { reGateOutcome } };
         default:

package/bin/engine/telemetry-seam.mjs

@@ -28,7 +28,7 @@ export function mapRecord(rec, wallMs) {
   if (!rec || typeof rec !== "object") return null;
   if (rec.event === "PHASE_ATTEMPT_USAGE") {
     return { event: "phase_attempt", phase: rec.phase, payload: compact({
-      attempt: rec.attempt, model: rec.model, turns: rec.turns, duration_ms: rec.duration_ms,
+      attempt: rec.attempt, model: rec.model, stages: rec.stages, turns: rec.turns, duration_ms: rec.duration_ms,
       cost_usd: Number.isFinite(rec.cost_usd) ? Math.round(rec.cost_usd * 1e6) / 1e6 : undefined,
       input_tokens: tok(rec.usage, "input_tokens"), output_tokens: tok(rec.usage, "output_tokens"),
       cache_read_tokens: tok(rec.usage, "cache_read_input_tokens"), cache_creation_tokens: tok(rec.usage, "cache_creation_input_tokens"),

package/bin/engine-cli.mjs

@@ -85,6 +85,29 @@ export function readCiPendingMaxMinutes(cwd = process.cwd()) {
   } catch { return undefined; }
 }
 
+/** forge.yaml `engine.path` (core|full|lean|auto) from the cwd checkout; undefined when absent or invalid. */
+export function readEnginePath(cwd = process.cwd()) {
+  try {
+    const v = String(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.engine?.path ?? "").trim();
+    return ENGINE_PATHS.includes(v) ? v : undefined;
+  } catch { return undefined; }
+}
+function readLeanSetting(key, cwd = process.cwd()) {
+  try {
+    const v = String(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.engine?.[`lean_${key}`] ?? "").trim();
+    return /^[A-Za-z0-9._:[\]-]+$/.test(v) ? v : undefined;
+  } catch { return undefined; }
+}
+// core is the default; lean and auto are aliases of core. full is the legacy multi-phase pipeline.
+/** forge.yaml `engine.merge_wait` (required|all|none); undefined when absent or invalid. */
+export function readMergeWait(cwd = process.cwd()) {
+  try {
+    const v = String(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.engine?.merge_wait ?? "").trim();
+    return ["required", "all", "none"].includes(v) ? v : undefined;
+  } catch { return undefined; }
+}
+export const ENGINE_PATHS = ["core", "full", "lean", "auto"];
+
 export function runDir() { return join(homedir(), ".forge", "runs"); }
 
 /**
@@ -380,6 +403,7 @@ export function lastLocalRun(dir) {
  *                          run's lease, wait (bounded by the lease TTL) until it
  *                          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.
  *   --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,
@@ -396,10 +420,17 @@ export async function runFromCli(argv, deps = {}) {
   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"].includes(argv[i - 1]));
+  const retry = argv.some((a, i) => a === "--retry" && !["--lane", "--repo", "--backend", "--model", "--path"].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]));
+  const pathFlag = flag(argv, "--path");
+  if (argv.includes("--path") && (!pathFlag || pathFlag.startsWith("--"))) throw new Error(`--path requires a value: ${ENGINE_PATHS.join("|")}`);
+  if (pathFlag && !ENGINE_PATHS.includes(pathFlag)) throw new Error(`--path must be one of ${ENGINE_PATHS.join("|")}`);
+  const enginePath = pathFlag ?? readEnginePath() ?? "core";
+  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");
+  }
   const io = deps.io ?? makeIo();
   await assertRepoMatchesCwd(io, repo);
   const runIssueFn = deps.runIssue ?? runIssue;
@@ -427,6 +458,19 @@ export async function runFromCli(argv, deps = {}) {
     // from "phase actually failed".
     else if (e.event === "phase_paused") console.log(`⏸ phase ${e.phase} paused: ${e.detail ?? "session limit"}`);
   };
+  if (enginePath !== "full") {
+    // Core work-on (lean): one builder session, one reviewer, GitHub as the register.
+    const leanRepo = repo ?? (await resolveDefaultRepo(io));
+    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,
+      emitTelemetry: deps.emitTelemetry ?? makeEmitTelemetry({ repo: leanRepo }),
+      ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) });
+    console.log(`issue #${issue} → ${lres.terminalReason}`);
+    if (!["merged", "invalid"].includes(lres.terminalReason)) console.log(lres.detail ?? "");
+    return lres;
+  }
   const res = await runIssueFn({ issue, dir, agentId, lane, io,
     ...(repo ? { repo } : {}),
     runner: (await import("./runner.mjs")).runCommand, now: () => Date.now(),
@@ -584,3 +628,39 @@ 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.
+ */
+export async function orchestrateFromCli(argv, deps = {}) {
+  const valued = ["--parallel", "--lane", "--repo", "--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]");
+  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 model = flag(argv, "--model");
+  const io = deps.io ?? makeIo();
+  const repo = flag(argv, "--repo") ?? (await resolveDefaultRepo(io));
+  if (!repo) throw new Error("orchestrate needs the repo: pass --repo or run inside a checkout with a GitHub remote");
+  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 rows = await orchestrate({
+    issues, parallel,
+    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,
+      ...(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})` : ""}`),
+  });
+  console.log("\n" + formatTable(rows));
+  return { rows, ok: rows.every((r) => ["merged", "invalid"].includes(r.outcome)) };
+}

package/bin/forgedock.mjs

@@ -3207,7 +3207,8 @@ 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> [--retry] [--wait-lease]", "Drive one issue through the durable engine (--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 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 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"],
     ["npx forgedock labels [setup] [--repo owner/repo]", "Bootstrap ForgeDock-managed labels on a GitHub repo (idempotent)"],
@@ -3781,10 +3782,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", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
+const SPLASH_COMMANDS = new Set(["run", "run-issue", "orchestrate", "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", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "help", "--help", "-h",
+  "run", "backend-check", "run-issue", "orchestrate", "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);
@@ -3982,6 +3983,17 @@ switch (command) {
     }
     break;
   }
+  case "orchestrate": {
+    const { orchestrateFromCli } = await import("./engine-cli.mjs");
+    try {
+      const result = await orchestrateFromCli(restArgs);
+      if (result && !result.ok) exitCode = 1;
+    } 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/effects.mjs

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Core work-on: the real effects behind runCore's injected `io`. Argv only, no shell. */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFileSync, appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runCliBackend, resolveClaudeCliBinary, getClaudeCliCapabilities, buildLeanSessionFlags, buildReadOnlyToolFlags } from "../runner.mjs";
+import { makeIo } from "../engine-cli.mjs";
+import { makeProjector } from "../engine/projector.mjs";
+
+const pexec = promisify(execFile);
+const script = (n) => fileURLToPath(new URL(`../../scripts/${n}`, import.meta.url));
+
+/** Claude CLI session runner: fresh session, or `--resume <id>` for the builder. Resolves usage + session_id. */
+export function makeLeanRunner({ runCli = runCliBackend } = {}) {
+  return async ({ role, issue, cwd, model, resume, system, prompt, readOnly = false }) => {
+    const bin = resolveClaudeCliBinary(cwd) || "claude";
+    const caps = getClaudeCliCapabilities(cwd);
+    const flags = [...buildLeanSessionFlags(caps), ...(readOnly ? buildReadOnlyToolFlags(caps) : [])];
+    const r = runCli({ spec: { name: `core-${role}` }, userMessage: prompt, systemPrompt: resume ? "" : system,
+      args: [String(issue)], cwd, bin, model, sessionFlags: flags, extraArgs: resume ? ["--resume", resume] : [],
+      logger: { log() {} } });
+    return { text: r.text, sessionId: r.sessionId, usage: r.usage, costUsd: r.costUsd, durationMs: r.durationMs, turns: r.turns, model: r.cliModel ?? "default" };
+  };
+}
+
+export function makeLeanIo({ repo }) {
+  const base = makeIo();
+  const run = (bin) => async (args, opts = {}) => (await pexec(bin, args, { cwd: opts.cwd, maxBuffer: 100 * 1024 * 1024, timeout: 120000 })).stdout;
+  return {
+    gh: run("gh"), git: run("git"), projector: makeProjector({ gh: base.gh }), runner: makeLeanRunner(), waitCiGreen: base.waitCiGreen,
+    /** Names of the checks the base branch requires (contexts + checks). [] on 404 / no protection. */
+    async requiredChecks(lane) {
+      try {
+        const j = JSON.parse(await run("gh")(["api", `repos/${repo}/branches/${lane}/protection/required_status_checks`]));
+        return [...new Set([...(j.contexts ?? []), ...(j.checks ?? []).map((c) => c.context)].filter(Boolean))];
+      } catch { return []; }
+    },
+    /** [{name, state: success|failure|pending}] for the PR's checks. */
+    async checkStates(pr) {
+      const j = JSON.parse(await run("gh")(["pr", "view", String(pr), "-R", repo, "--json", "statusCheckRollup"]));
+      return (j.statusCheckRollup ?? []).map((c) => {
+        const v = String(c.conclusion || c.state || "").toUpperCase();
+        const state = ["SUCCESS", "NEUTRAL", "SKIPPED"].includes(v) ? "success" : ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE"].includes(v) ? "failure" : "pending";
+        return { name: c.name ?? c.context, state };
+      });
+    },
+    async transitionLabel(issue, state) { await pexec("bash", [script("transition-label.sh"), String(issue), "-R", repo, state], { timeout: 60000 }); },
+    fs: {
+      read: async (p) => readFileSync(p, "utf8"),
+      append: async (p, t) => { mkdirSync(dirname(p), { recursive: true }); appendFileSync(p, t); },
+    },
+  };
+}

package/bin/lean/lean.mjs

@@ -0,0 +1,284 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Core work-on: ONE plain builder session does the work, ONE read-only reviewer answers two questions, and
+ * ForgeDock registers everything on GitHub (labels, one register comment, PR, merge). No investigation, synthesis,
+ * severity taxonomy, risk tiers or local CI gates. All effects are injected through `io` so it is unit-testable.
+ */
+import { join } from "node:path";
+import { appendEvent } from "../engine/runlog.mjs";
+import { codeForTerminalReason, OUTCOME_CODES } from "../engine/outcome-codes.mjs";
+import { ciPollDelayMs, ENGINE_VERSION } from "../engine.mjs";
+import { openDependency } from "../engine/phases.mjs";
+import { renderValidate, renderPlan, renderReview, renderRegister, renderPrBody } from "./render.mjs";
+import { REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, builderPrompt, resumeBuilderPrompt, reviewerPrompt, parseVerdict } from "./prompts.mjs";
+
+export const DEFAULT_REVIEWER_MODEL = "claude-sonnet-5-5";
+export const REGISTER_MARKER = "FORGE:WORK-ON";
+const num = (v) => (Number.isFinite(v) ? v : null);
+
+/**
+ * @param {object} o
+ * @param {number} o.issue
+ * @param {string} o.repo            "owner/repo"
+ * @param {string} o.lane            base branch (staging|main)
+ * @param {string} o.cwd             main checkout (worktrees are added from here)
+ * @param {string} o.dir             run-log dir
+ * @param {object} o.io              injected effects: gh, git, runner, waitCiGreen, transitionLabel, fs, projector?, now?, sleep?
+ * @param {string} [o.builderModel]  default: CLI default
+ * @param {string} [o.reviewerModel] default claude-sonnet-5-5
+ * @param {number} [o.ciMaxMinutes]  remote-CI wait budget (default 360); exhaustion is NOT needs-human
+ */
+export async function runCore(o) {
+  const { issue, repo, lane, cwd, dir, io, builderModel = null, reviewerModel = DEFAULT_REVIEWER_MODEL,
+    ciMaxMinutes = 360, mergeWait = "required", onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
+  const now = io.now ?? (() => Date.now());
+  const sleep = io.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const base = `origin/${lane}`;
+  const branch = `feat/issue-${issue}-lean`;
+  const wt = join(o.worktreeRoot ?? join(cwd, ".claude", "worktrees"), `lean-${issue}`);
+  const t0 = now();
+  const usage = { cost_usd: 0, input: 0, output: 0, cache: 0 };
+  let sessionId = null;
+
+  const ev = (e) => appendEvent(dir, issue, e);
+  const emit = async (rec) => { try { await emitTelemetry?.({ ...rec, issue }); } catch { /* never fails a run */ } };
+  const ghc = (args) => io.gh(args);
+  const git = (args) => io.git(args, { cwd: wt });
+
+  async function attempt(phase, n, r) {
+    const rec = { event: "PHASE_ATTEMPT_USAGE", phase, attempt: n, usage: r?.usage ?? null, duration_ms: num(r?.durationMs) ?? 0,
+      cost_usd: num(r?.costUsd), model: r?.model ?? null, turns: num(r?.turns) };
+    ev(rec); await emit(rec);
+    const u = r?.usage ?? {};
+    usage.cost_usd += r?.costUsd ?? 0;
+    usage.input += u.input_tokens ?? 0; usage.output += u.output_tokens ?? 0;
+    usage.cache += (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+  }
+  const post = async (marker, body) => {
+    const out = String(await ghc(["issue", "comment", String(issue), "-R", repo, "--body", `<!-- ${marker} -->\n${body}`])).trim();
+    return /https?:\/\/\S+/.exec(out)?.[0] ?? null;
+  };
+  const label = async (state) => { try { await io.transitionLabel(issue, state); } catch { /* labels are best effort */ } };
+  const usageLine = () => `cost $${usage.cost_usd.toFixed(4)}, tokens ${usage.input} in / ${usage.output} out / ${usage.cache} cache, wall ${Math.round((now() - t0) / 60000 * 10) / 10} min`;
+
+  // ---- lease (same FORGE:STATE lease the full path uses) ----
+  const agentId = o.agentId ?? `core_${process.pid}`;
+  const leaseTtlMs = o.leaseTtlMs ?? 25 * 60000; // below the projector's 30 min honour cap
+  let leaseState = null, leaseTimer = null;
+  const writeLease = (lease, extra = {}) => io.projector.writeState(issue, { ...leaseState, ...extra, lease });
+  const renew = async () => { if (io.projector && leaseState) { try { await writeLease({ by: agentId, until: now() + leaseTtlMs }); } catch { /* best effort */ } } };
+  async function releaseLease(reason) {
+    if (leaseTimer) { clearInterval(leaseTimer); leaseTimer = null; }
+    if (!io.projector || !leaseState) return;
+    const terminal = ["merged", "invalid", "needs-human", "engine-error"].includes(reason);
+    try { await writeLease(null, terminal ? { terminal: true, terminalReason: reason } : {}); } catch { /* best effort */ }
+  }
+
+  let done = null, wtCreated = false;
+  async function finish(reason, detail = "", extra = {}) {
+    if (done) return done; // idempotent: exactly one RUN_TERMINAL and one telemetry emit
+    const code = codeForTerminalReason(reason);
+    ev({ event: "RUN_TERMINAL", reason, code });
+    await emit({ event: "RUN_TERMINAL", reason, code });
+    if (["needs-human", "engine-error"].includes(reason)) {
+      const wf = ["investigating", "building", "in-review"].map((x) => `workflow:${x}`).join(",");
+      try { await ghc(["issue", "edit", String(issue), "-R", repo, "--remove-label", wf]); } catch { /* best effort */ }
+    }
+    await releaseLease(reason);
+    if (wtCreated) {
+      try { await io.git(["worktree", "remove", "--force", wt], { cwd }); } catch { /* best effort */ }
+      if (reason === "invalid" && !extra.pr) { try { await io.git(["branch", "-D", branch], { cwd }); } catch { /* best effort */ } }
+    }
+    done = { terminalReason: reason, detail, branch, worktree: wt, cost_usd: usage.cost_usd, tokens: { input: usage.input, output: usage.output, cache: usage.cache }, wall_ms: now() - t0, ...extra };
+    return done;
+  }
+  async function needsHuman(why) {
+    try {
+      await post("FORGE:NEEDS_HUMAN", `## Needs human\n${why}\n\n_${usageLine()}_`);
+      await ghc(["issue", "edit", String(issue), "-R", repo, "--add-label", "needs-human"]);
+    } catch { /* best effort */ }
+    return finish("needs-human", why);
+  }
+
+  async function builder(n, prompt, resume) {
+    onProgress({ event: "phase_enter", phase: "build" });
+    await renew();
+    const r = await io.runner({ role: "builder", issue, cwd: wt, model: builderModel, resume, system: "", prompt });
+    await renew();
+    if (r?.sessionId) sessionId = r.sessionId;
+    await attempt("implement", n, r);
+    onProgress({ event: "phase_exit", phase: "build", status: "committed" });
+    return r;
+  }
+  const readResult = async () => { try { const j = JSON.parse(await io.fs.read(`${wt}/${RESULT_FILE}`)); return j && typeof j === "object" ? j : null; } catch { return null; } };
+
+  // ---- admission: Depends-on refusal, then lease ----
+  {
+    let dep = null;
+    try { dep = await openDependency(issue, io); } catch (e) { dep = { unreadable: true, detail: `issue ${issue} **Depends on** check failed: ${e?.message || e}` }; }
+    if (dep?.unreadable) return { terminalReason: "dependency-unreadable", code: OUTCOME_CODES.DEPENDENCY_UNREADABLE, detail: dep.detail };
+    if (dep?.open?.length) {
+      return { terminalReason: "dependency-open", code: OUTCOME_CODES.DEPENDENCY_OPEN, dependencies: dep.open,
+        detail: `issue ${issue} **Depends on** ${dep.open.map((n) => `#${n}`).join(", ")} which is still open; re-run once it is closed` };
+    }
+  }
+  if (io.projector) {
+    let st = null;
+    try { st = await io.projector.readState(issue); } catch { /* unreadable: proceed */ }
+    if (st?.lease && st.lease.until > now() && st.lease.by !== agentId) {
+      return { terminalReason: "deferred", code: "lease-held", detail: `issue ${issue} leased by ${st.lease.by} until ${new Date(st.lease.until).toISOString()}`, branch, worktree: wt };
+    }
+    leaseState = { ...(st ?? { v: 1, run: `core_${issue}`, issue, lane, committed: [], phase: null, branch: null, pr: null, terminalReason: null }), terminal: false };
+    try { await writeLease({ by: agentId, until: now() + leaseTtlMs }); } catch { /* best effort */ }
+    leaseTimer = setInterval(() => { writeLease({ by: agentId, until: now() + leaseTtlMs }).catch(() => {}); }, o.leaseRenewMs ?? 120000);
+    leaseTimer.unref?.();
+  }
+
+  ev({ event: "RUN_START", run: `core_${issue}_${t0}`, issue, lane, path: "core", version: ENGINE_VERSION, forge_version: ENGINE_VERSION, repo });
+  let iss;
+  try {
+    iss = JSON.parse(await ghc(["issue", "view", String(issue), "-R", repo, "--json", "number,title,body,state"]));
+  } catch (e) { return finish("engine-error", `cannot read issue: ${e.message}`); }
+  if (String(iss.state).toUpperCase() === "CLOSED") return finish("invalid", "issue already closed");
+
+  try {
+    // ---- 1. claim ----
+    await label("investigating");
+    await post("FORGE:STARTED", `Started work on #${issue} (base \`${lane}\`).`);
+
+    // ---- 2. worktree (resume an open PR / remote branch) ----
+    try { await io.git(["fetch", "origin", lane], { cwd }); } catch { /* offline: use the local ref */ }
+    let resumed = null;
+    try {
+      const prs = JSON.parse(String(await ghc(["pr", "list", "-R", repo, "--head", branch, "--state", "open", "--json", "number,headRefOid"])) || "[]");
+      const remote = String(await io.git(["ls-remote", "--heads", "origin", branch], { cwd })).trim();
+      if (prs.length || remote) resumed = { pr: prs[0]?.number ?? null };
+    } catch { /* no resume info: start fresh */ }
+    try { await io.git(["worktree", "remove", "--force", wt], { cwd }); } catch { /* none */ }
+    try { await io.git(["worktree", "prune"], { cwd }); } catch { /* best effort */ }
+    if (resumed) {
+      await io.git(["fetch", "origin", branch], { cwd });
+      await io.git(["worktree", "add", "-B", branch, wt, `origin/${branch}`], { cwd });
+    } else {
+      await io.git(["worktree", "add", "-B", branch, wt, base], { cwd });
+    }
+    wtCreated = true;
+    const excl = String(await git(["rev-parse", "--git-path", "info/exclude"])).trim();
+    await io.fs.append(excl.startsWith("/") ? excl : `${wt}/${excl}`, `\n${LEAN_DIR}/\n`);
+    const changedFiles = async () => String(await git(["diff", "--name-only", `${base}...HEAD`])).split("\n").map((s) => s.trim()).filter(Boolean);
+
+    // ---- 3. builder ----
+    let result = null, attemptN = 0, validateUrl = null, planUrl = null, reviewUrl = null;
+    if (!(resumed && (await changedFiles()).length > 0)) {
+      await label("building");
+      await builder(++attemptN, builderPrompt(issue), null);
+      result = await readResult();
+      const files0 = await changedFiles();
+      const evidence = (Array.isArray(result?.evidence) ? result.evidence : []).filter((x) => typeof x === "string" && x.trim());
+      const verdict = result ? (result.status === "fixed" ? "valid" : result.status) : null;
+      const closing = ["invalid", "already-fixed"].includes(result?.status);
+      if (closing && !evidence.length) return await needsHuman(`Builder reported "${result.status}" without evidence, so the issue is not closed automatically.\n\n${result.summary ?? "(no summary)"}`);
+      // The validation comment (no model call): verdict, evidence, one-line summary. For invalid/already-fixed it IS the evidence comment.
+      if (verdict) validateUrl = await post("FORGE:VALIDATE", renderValidate(result, verdict));
+      if (closing) {
+        await ghc(["issue", "close", String(issue), "-R", repo, "--reason", "not planned"]);
+        await label("invalid");
+        return await finish("invalid", result.summary ?? result.status);
+      }
+      if (result?.status === "blocked") return await needsHuman(`Builder is blocked: ${result.summary ?? "(no summary)"}`);
+      if (!files0.length) return await needsHuman(`Builder made no commit${result ? ` (status "${result.status}")` : " and wrote no result.json"}.\n\n${result?.summary ?? ""}`);
+      planUrl = await post("FORGE:PLAN", renderPlan(result, files0));
+    }
+
+    // ---- 4. review (one retry through the same builder session) ----
+    await label("in-review");
+    let review = null, reviewN = 0;
+    const doReview = async () => {
+      for (let t = 0; t < 2; t++) {
+        const diff = String(await git(["diff", `${base}...HEAD`]));
+        await renew();
+        const rr = await io.runner({ role: "reviewer", issue, cwd: wt, model: reviewerModel, resume: null, system: REVIEWER_SYSTEM, readOnly: true,
+          prompt: reviewerPrompt({ issue: iss, diff }) });
+        await renew();
+        await attempt("review", ++reviewN, rr);
+        const v = parseVerdict(rr?.text);
+        if (v) return v;
+      }
+      return null;
+    };
+    review = await doReview();
+    if (!review) return await needsHuman("Reviewer returned no parseable verdict twice.");
+    if (review.fail) {
+      if (!sessionId) return await needsHuman(`Review FAIL and the builder session id is unknown, cannot resume: ${review.reason}`);
+      await builder(++attemptN, resumeBuilderPrompt(review.reason), sessionId);
+      result = (await readResult()) ?? result;
+      review = await doReview();
+      if (!review) return await needsHuman("Reviewer returned no parseable verdict twice (re-review).");
+      if (review.fail) return await needsHuman(`Review FAIL twice. Last reason: ${review.reason}`);
+    }
+    reviewUrl = await post("FORGE:REVIEW", renderReview(review));
+    ev({ event: "PHASE_COMMIT", phase: "review" });
+
+    // ---- 5. push + PR ----
+    const files = await changedFiles();
+    await git(["push", "-u", "origin", branch]);
+    const prOut = resumed?.pr ? `/pull/${resumed.pr}` : String(await ghc(["pr", "create", "-R", repo, "--base", lane, "--head", branch,
+      "--title", `${iss.title} (#${issue})`, "--body", renderPrBody({ issue, result, gitFiles: files })])).trim();
+    const pr = Number(/\/pull\/(\d+)/.exec(prOut)?.[1] ?? /(\d+)\s*$/.exec(prOut)?.[1]);
+    if (!Number.isInteger(pr)) return await needsHuman(`Could not parse the PR number from: ${prOut.slice(0, 200)}`);
+    ev({ event: "PR_OPENED", pr });
+    const prUrl = /https?:\/\/\S+/.exec(prOut)?.[0] ?? `https://github.com/${repo}/pull/${pr}`;
+    const localHead = String(await git(["rev-parse", "HEAD"])).trim();
+
+    // ---- 6. the register comment ----
+    // merge policy: required (default) | all | none
+    let policy = mergeWait, required = [];
+    if (mergeWait === "required") {
+      try { required = (await io.requiredChecks?.(lane)) ?? []; } catch { required = []; }
+    }
+    const policyText = mergeWait === "required" ? (required.length ? `required (${required.join(", ")})` : "required (no required checks: merged right after review)") : mergeWait;
+    await post(REGISTER_MARKER, renderRegister({ result, gitFiles: files, review, links: { validate: validateUrl, plan: planUrl, review: reviewUrl }, prUrl, usage: usageLine(), policy: policyText }));
+
+    // ---- 7. wait per policy, merge at the reviewed head ----
+    if (policy === "none" || (policy === "required" && !required.length)) {
+      // merge right after review
+    } else {
+      const startedAt = now();
+      let pollIndex = 0, gateHead = null;
+      for (;;) {
+        await renew();
+        if (policy === "all") {
+          const w = await io.waitCiGreen(pr, repo, 0).catch(() => ({ rc: 2, text: "" }));
+          if (w.rc === 0) { gateHead = /CI_GATE_HEAD:\s*([0-9a-f]{7,40})/.exec(w.text ?? "")?.[1] ?? null; break; }
+          if (w.rc === 1) return await needsHuman(`Remote CI failed on PR #${pr}:\n${String(w.text).slice(-2000)}`);
+        } else {
+          let states = [];
+          try { states = (await io.checkStates(pr)) ?? []; } catch { states = []; }
+          const st = (n) => states.find((x) => x.name === n)?.state ?? "pending";
+          const failed = required.filter((n) => st(n) === "failure");
+          if (failed.length) return await needsHuman(`Required check(s) failed on PR #${pr}: ${failed.join(", ")}`);
+          if (required.every((n) => st(n) === "success")) break;
+        }
+        if (now() - startedAt >= ciMaxMinutes * 60000) {
+          // Slow CI is never a needs-human: leave the PR open and resumable.
+          ev({ event: "CI_PENDING_WAIT", state: "end", pr, result: "timeout" });
+          return await finish("ci-pending", `PR #${pr} still waiting on CI after ${ciMaxMinutes} min`, { pr });
+        }
+        onProgress({ event: "phase_paused", phase: "merge", detail: `CI pending on PR #${pr}` });
+        await sleep(ciPollDelayMs(pollIndex++, random));
+      }
+      if (gateHead && !(localHead.startsWith(gateHead) || gateHead.startsWith(localHead))) {
+        return await needsHuman(`CI passed for ${gateHead.slice(0, 12)} but the reviewed head is ${localHead.slice(0, 12)}; refusing to merge an unreviewed head.`);
+      }
+    }
+    await ghc(["pr", "merge", String(pr), "-R", repo, "--merge", "--match-head-commit", localHead]);
+    await ghc(["issue", "close", String(issue), "-R", repo, "--reason", "completed"]).catch(() => {});
+    await label("merged");
+    return await finish("merged", `PR #${pr}`, { pr });
+  } catch (e) {
+    return finish("engine-error", e?.message ?? String(e));
+  }
+}
+
+export const runLean = runCore;