forgedock 1.19.0 → 1.21.0

package/README.md

@@ -303,6 +303,8 @@ If you're carrying an older `--global` habit in scripts or CI, it's harmless to
 
 </details>
 
+**After upgrading**: run `npx forgedock labels setup` once per repo. Repos created before the `workflow:remediating` state (forge#3541) lack that label; the pipeline now creates it on demand (best-effort), but the setup command is the supported way to sync all labels.
+
 ---
 
 ## For companies

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.`]);

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,21 @@ export function readCiPendingMaxMinutes(cwd = process.cwd()) {
   } catch { return undefined; }
 }
 
+/** forge.yaml `engine.path` (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; }
+}
+export const ENGINE_PATHS = ["full", "lean", "auto"];
+
 export function runDir() { return join(homedir(), ".forge", "runs"); }
 
 /**
@@ -380,6 +395,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 <full|lean|auto>  Optional (#4081). Engine path; overrides forge.yaml engine.path. Default full.
  *   --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 +412,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() ?? "full";
+  if (enginePath !== "full" && (retry || waitLease)) {
+    throw new Error("--retry and --wait-lease are not supported with the lean 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 +450,22 @@ 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") {
+    // #4081: lean path. `auto` escalates to the full pipeline only when the change is risky AND large.
+    const leanRepo = repo ?? (await resolveDefaultRepo(io));
+    if (!leanRepo) throw new Error("lean path needs the repo: pass --repo or run inside a checkout with a GitHub remote");
+    const { runLean } = deps.leanModule ?? (await import("./lean/lean.mjs"));
+    const leanIo = deps.leanIo ?? (await import("./lean/effects.mjs")).makeLeanIo({ repo: leanRepo });
+    const lres = await runLean({ issue, repo: leanRepo, lane, cwd: process.cwd(), dir, io: leanIo, path: enginePath, onProgress,
+      emitTelemetry: deps.emitTelemetry ?? makeEmitTelemetry({ repo: leanRepo }),
+      ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) });
+    if (lres.terminalReason !== "route-full") {
+      console.log(`issue #${issue} → ${lres.terminalReason}`);
+      if (lres.terminalReason !== "merged") console.log(formatTerminalDiagnostics(dir, issue));
+      return lres;
+    }
+    console.log(`issue #${issue} → routing to the full pipeline (${lres.detail})`);
+  }
   const res = await runIssueFn({ issue, dir, agentId, lane, io,
     ...(repo ? { repo } : {}),
     runner: (await import("./runner.mjs")).runCommand, now: () => Date.now(),

package/bin/engine.mjs

@@ -4,7 +4,8 @@
  * GitHub state (phase.detectOutcome). All effects are injected → fully testable.
  */
 import { fileURLToPath } from "node:url";
-import { readFileSync, rmSync } from "node:fs";
+import { readFileSync, rmSync, readdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { createHash, scryptSync } from "node:crypto";
 import { hostname as osHostname, homedir } from "node:os";
 import { appendEvent, readLog, deriveState, rewriteLog } from "./engine/runlog.mjs";
@@ -268,6 +269,46 @@ export function isLeaseHolderDead({ by, host = osHostname(), killFn = process.ki
   }
 }
 
+/**
+ * forge#3724: a dead lease-holder pid proves the engine is dead, not that its phase child is. The runner
+ * stamps every phase child with `FORGE_LEASE_HOLDER=<by>` (inherited by grandchildren), so a surviving
+ * orphan is found by scanning process environments. Returns FALSE only when the probe affirmatively finds
+ * no live process carrying the marker; unsupported platform, unreadable /proc, a failed `ps`, or any thrown
+ * error returns TRUE (fail-safe: the caller keeps waiting for `lease.until`). Per-process EACCES/ENOENT is
+ * skipped (exited, or another uid). Residual: a child that scrubs its env (`env -i`) is not detected.
+ */
+export function leaseChildAlive({ by, platform = process.platform, procRoot = "/proc", ownPid = process.pid,
+  readdirFn = readdirSync, readFileFn = readFileSync, psFn } = {}) {
+  try {
+    const marker = `FORGE_LEASE_HOLDER=${by}`;
+    if (!parseLeaseHolder(by)) return true;
+    if (platform === "linux") {
+      for (const name of readdirFn(procRoot)) {
+        if (!/^[0-9]+$/.test(name) || Number(name) === ownPid) continue;
+        let env;
+        try { env = readFileFn(`${procRoot}/${name}/environ`, "latin1"); }
+        catch (e) { if (e?.code === "EACCES" || e?.code === "ENOENT" || e?.code === "ESRCH" || e?.code === "EPERM") continue; return true; }
+        if (String(env).split("\0").includes(marker)) return true;
+      }
+      return false;
+    }
+    if (platform === "darwin") {
+      const run = psFn || (() => execFileSync("ps", ["eww", "-Ao", "pid,command"], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: 10000 }));
+      const out = run();
+      if (typeof out !== "string" || !out.trim()) return true;
+      for (const line of out.split("\n")) {
+        const m = /^\s*(\d+)\s/.exec(line);
+        if (!m || Number(m[1]) === ownPid) continue;
+        if (line.split(/\s+/).includes(marker)) return true;
+      }
+      return false;
+    }
+    return true;
+  } catch {
+    return true;
+  }
+}
+
 /** Max startup wait for a persisted rate-limit reset (guards a corrupt far-future resetAt). */
 export const MAX_RESUME_RATE_LIMIT_WAIT_MS = 6 * 60 * 60 * 1000;
 
@@ -330,7 +371,8 @@ export const MAX_RESUME_RATE_LIMIT_WAIT_MS = 6 * 60 * 60 * 1000;
  *   the lease, poll (via `sleep`, bounded by `leaseTtlMs`) until it expires or
  *   its holder is reclaimable, then continue; `deferred` on timeout.
  * @param {string} [opts.hostname] - injectable host name (tests).
- * @param {Function} [opts.killFn] - injectable `process.kill` (tests).
+  * @param {Function} [opts.killFn] - injectable `process.kill` (tests).
+ * @param {Function} [opts.childAliveFn] - forge#3724: injectable `leaseChildAlive` (orphaned phase-child probe; tests).
  */
 // forge#3824: stamped on RUN_START for per-release cost attribution; null when unreadable.
 export const ENGINE_VERSION = (() => {
@@ -368,6 +410,8 @@ export async function runIssue(opts) {
           waitLease = false,
           hostname = osHostname(),
           killFn = process.kill.bind(process),
+          // forge#3724: injectable orphaned-phase-child probe (tests).
+          childAliveFn = leaseChildAlive,
           onProgress = () => {},
           // forge#3696: per-attempt telemetry seam (FORGE:TELEMETRY emitter, #3834). No-op by
           // default; failures are swallowed so telemetry can never fail a phase.
@@ -400,7 +444,7 @@ export async function runIssue(opts) {
   let remote = await projector.readState(issue);
   let { state, action } = reconcileState(local, remote);
   const leaseHeld = (r) => !!(r?.lease && r.lease.until > now() && r.lease.by !== agentId &&
-    !isLeaseHolderDead({ by: r.lease.by, host: hostname, killFn }));
+    !(isLeaseHolderDead({ by: r.lease.by, host: hostname, killFn }) && !childAliveFn({ by: r.lease.by })));
   const deferredResult = (r) => ({
     terminalReason: "deferred",
     code: OUTCOME_CODES.LEASE_HELD,
@@ -1233,6 +1277,7 @@ async function runPhaseWithRetry(phase, state, ctx) {
     try {
       result = await runner({
         commandsDir, commandName: phase.command, args: phaseArgs,
+        leaseHolder: agentId,
         // Only forwarded when explicitly provided — omitting them preserves
         // runner.mjs's existing default ("auto" backend / DEFAULT_MODEL).
         ...(backend ? { backend } : {}),

package/bin/forgedock.mjs

@@ -3207,7 +3207,7 @@ 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 full|lean|auto] [--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 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)"],

package/bin/lean/effects.mjs

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Lean path (#4081): the real effects behind runLean'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 warm 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: `lean-${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" };
+  };
+}
+
+/** A missing or unparseable CI_LOCAL_RESULT means the gate itself is broken (BROKEN); only an explicit DEGRADED passes. */
+export function parseCiLocalResult(out) {
+  return /CI_LOCAL_RESULT:\s*(PASS|FAIL|DEGRADED)\b/.exec(String(out))?.[1] ?? "BROKEN";
+}
+
+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,
+    async ciLocal({ cwd, base: baseRef }) {
+      let out = "";
+      try { out = (await pexec("bash", [script("ci-local.sh"), "run", "--repo", cwd, "--base", baseRef], { maxBuffer: 50 * 1024 * 1024, timeout: 3600000 })).stdout; }
+      catch (e) { out = String(e.stdout ?? "") + String(e.stderr ?? ""); }
+      return { result: parseCiLocalResult(out), tail: out.split("\n").slice(-60).join("\n") };
+    },
+    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,352 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Lean path (#4081): validate -> architect -> implement in ONE warm builder session, deterministic gates,
+ * one independent reviewer (plus a security reviewer on risky paths), then deterministic merge and close.
+ * Every stage is posted to the issue as a structured FORGE:* comment. All effects are injected through `io`
+ * (gh, git, runner, ciLocal, waitCiGreen, transitionLabel, fs, sleep) so the module is fully unit-testable.
+ */
+import { join } from "node:path";
+import { appendEvent } from "../engine/runlog.mjs";
+import { codeForTerminalReason } from "../engine/outcome-codes.mjs";
+import { ciPollDelayMs, ENGINE_VERSION } from "../engine.mjs";
+import { openDependency } from "../engine/phases.mjs";
+import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
+import { riskTier, isDocsOnly, isTestFile, isLargeDiff, isBlocking, parseFindings } from "./risk.mjs";
+import { BUILDER_SYSTEM, REVIEWER_SYSTEM, SECURITY_REVIEWER_SYSTEM, LEAN_DIR, builderPrompt, resumeGatePrompt, resumeReviewPrompt, reviewerPrompt } from "./prompts.mjs";
+
+export const MAX_ROUNDS = 2;
+export const DEFAULT_REVIEWER_MODEL = "claude-sonnet-5-5";
+const NS = "lean";
+
+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
+ * @param {"lean"|"auto"} [o.path]
+ * @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 runLean(o) {
+  const { issue, repo, lane, cwd, dir, io, path = "lean", builderModel = null, reviewerModel = DEFAULT_REVIEWER_MODEL,
+    ciMaxMinutes = 360, 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 links = {};
+  let sessionId = null;
+  const usageTotal = { cost_usd: 0 };
+
+  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 });
+  const file = (n) => `${wt}/${LEAN_DIR}/${n}`;
+
+  async function attempt(phase, n, r, extra = {}) {
+    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), ...extra };
+    ev(rec); await emit(rec);
+    usageTotal.cost_usd += r?.costUsd ?? 0;
+  }
+  async function commit(phase) { ev({ event: "PHASE_COMMIT", phase }); onProgress({ event: "phase_exit", phase, status: "committed" }); }
+
+  async function post(marker, title, body, attrs = "") {
+    const text = `<!-- ${marker} ${NS} v1${attrs} -->\n## ${marker}\n${title ? `${title}\n\n` : ""}${body}`;
+    const out = String(await ghc(["issue", "comment", String(issue), "-R", repo, "--body", text])).trim();
+    const url = /https?:\/\/\S+/.exec(out)?.[0] ?? null;
+    if (url) (links[marker] ??= []).push(url);
+    return url;
+  }
+
+  let done = null, wtCreated = false;
+  const WORKFLOW = ["investigating", "building", "in-review"].map((x) => `workflow:${x}`).join(",");
+  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 });
+    // A run that did not reach a success/handoff state must not leave a stale in-progress label behind.
+    if (["needs-human", "engine-error"].includes(reason)) {
+      try { await ghc(["issue", "edit", String(issue), "-R", repo, "--remove-label", WORKFLOW]); } catch { /* best effort */ }
+    }
+    await releaseLease(reason);
+    // The worktree is scratch; the branch stays when a PR (or a human) may need it.
+    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: usageTotal.cost_usd, wall_ms: now() - t0, ...extra };
+    return done;
+  }
+  async function needsHuman(why) {
+    try { await post("FORGE:NEEDS_HUMAN", "", why); await ghc(["issue", "edit", String(issue), "-R", repo, "--add-label", "needs-human"]); } catch { /* best effort */ }
+    return finish("needs-human", why);
+  }
+  async function label(state) { try { await io.transitionLabel(issue, state); } catch { /* labels are best effort */ } }
+
+  async function builder(phase, n, prompt, resume) {
+    onProgress({ event: "phase_enter", phase });
+    await renew();
+    const r = await io.runner({ role: "builder", issue, cwd: wt, model: builderModel, resume,
+      system: resume ? "" : BUILDER_SYSTEM, prompt });
+    await renew();
+    if (r?.sessionId) sessionId = r.sessionId;
+    return r;
+  }
+  const readJson = async (n) => { try { return JSON.parse(await io.fs.read(file(n))); } catch { return null; } };
+
+  // Same issue lease the full path uses (FORGE:STATE lease via the projector): two runs cannot race.
+  const agentId = o.agentId ?? `lean_${process.pid}`;
+  // 25 min: below the projector's 30 min honour cap. The CLI is spawned synchronously (no timer can fire), so the
+  // lease is also renewed immediately before and after every builder/reviewer/ci-local call and each CI poll.
+  const leaseTtlMs = o.leaseTtlMs ?? 25 * 60000;
+  let leaseState = null, leaseTimer = null;
+  const writeLease = (lease, extra = {}) => io.projector.writeState(issue, { ...leaseState, ...extra, lease });
+  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 */ }
+  }
+  const renew = async () => { if (io.projector && leaseState) { try { await writeLease({ by: agentId, until: now() + leaseTtlMs }); } catch { /* best effort */ } } };
+  // Same Depends-on admission as the full path, before any state write or worktree.
+  {
+    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, the write below is best effort */ }
+    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: `lean_${issue}`, issue, lane, committed: [], phase: null, branch: null, pr: null, terminal: false, terminalReason: null };
+    leaseState = { ...leaseState, 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: `lean_${issue}_${t0}`, issue, lane, path: "lean", 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 {
+    await label("investigating");
+    try { await io.git(["fetch", "origin", lane], { cwd }); } catch { /* offline: use the local ref */ }
+    // Reruns resume: an open PR or a remote branch for this issue means earlier work exists (e.g. ci-pending).
+    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`);
+
+    let planMd = null, validate = null, implRound = 1, gateRounds = 0;
+    const postImpl = async () => {
+      const impl = await readJson("implement.json");
+      await post("FORGE:IMPLEMENT", impl ? `**Round:** ${implRound}` : "**implement.json missing**", "```json\n" + JSON.stringify(impl ?? {}, null, 2) + "\n```", ` round=${implRound}`);
+      return impl;
+    };
+    const diffStats = async () => {
+      const files = String(await git(["diff", "--name-only", `${base}...HEAD`])).split("\n").map((s) => s.trim()).filter(Boolean);
+      let lines = 0;
+      for (const l of String(await git(["diff", "--numstat", `${base}...HEAD`])).split("\n")) {
+        const [a, d] = l.split("\t"); lines += (Number(a) || 0) + (Number(d) || 0);
+      }
+      return { files, lines };
+    };
+    const gateFailure = async () => {
+      const { files } = await diffStats();
+      if (files.length === 0) return { kind: "no-commit", tail: "No commit on the branch relative to the base. Commit your change." };
+      if (!(await readJson("implement.json"))) return { kind: "implement-json", tail: `${LEAN_DIR}/implement.json is missing or invalid JSON.` };
+      if (!isDocsOnly(files) && !files.some(isTestFile)) {
+        return { kind: "missing-test", tail: "No test file changed. Add a regression test that fails without the fix (and passes with it)." };
+      }
+      await renew();
+      const ci = await io.ciLocal({ cwd: wt, base });
+      await renew();
+      if (ci.result === "BROKEN") return { kind: "ci-local-broken", fatal: true, tail: ci.tail ?? "ci-local reported no result" };
+      if (ci.result === "FAIL") return { kind: "ci-local", tail: ci.tail ?? "" };
+      return null;
+    };
+    const runGates = async () => {
+      for (;;) {
+        const f = await gateFailure();
+        if (!f) return null;
+        if (f.fatal) return needsHuman(`gate ${f.kind}: the local CI gate could not report a result, so the change is unverified.\n\n${String(f.tail).slice(-2000)}`);
+        if (gateRounds >= MAX_ROUNDS) return needsHuman(`gate ${f.kind} still failing after ${MAX_ROUNDS} resume rounds:\n\n${String(f.tail).slice(-3000)}`);
+        gateRounds++; implRound++;
+        if (!sessionId) return needsHuman(`gate ${f.kind} failed and the builder session id is unknown, cannot resume`);
+        const rr = await builder("implement", implRound, resumeGatePrompt(f), sessionId);
+        await attempt("implement", implRound, rr, {});
+        await postImpl();
+      }
+    };
+
+    let approvedHead = null;
+    if (resumed) {
+      // Resume from the knowledge graph: plan and last review verdict come from the issue comments.
+      const bodies = (JSON.parse(String(await ghc(["issue", "view", String(issue), "-R", repo, "--json", "comments"])) || "{}").comments ?? []).map((c) => String(c.body ?? ""));
+      const lastOf = (m) => bodies.filter((b) => b.includes(`<!-- ${m} ${NS}`)).pop();
+      const planC = lastOf("FORGE:PLAN");
+      planMd = planC ? planC.replace(/^[\s\S]*?## FORGE:PLAN\n/, "") : "";
+      const rev = lastOf("FORGE:REVIEW");
+      const m = rev && /\*\*Verdict:\*\* APPROVED[^\n]*reviewed ([0-9a-f]{7,40})/.exec(rev);
+      const curHead = String(await git(["rev-parse", "HEAD"])).trim();
+      if (m && curHead.startsWith(m[1])) approvedHead = curHead;
+      ev({ event: "RUN_RESUMED", pr: resumed.pr, approved: Boolean(approvedHead) });
+    } else {
+    // ---- builder: validate + architect + implement in one session ----
+    const r = await builder("validate", 1, builderPrompt({ issue: iss, base: lane, branch }), null);
+    validate = await readJson("validate.json");
+    await attempt("implement", 1, r, { stages: "validate,architect,implement" });
+    if (!validate) return await needsHuman("builder did not write validate.json");
+    await post("FORGE:VALIDATE", `**Status:** ${validate.status}`, "```json\n" + JSON.stringify(validate, null, 2) + "\n```");
+    if (validate.status !== "valid") {
+      const evidence = (Array.isArray(validate.evidence) ? validate.evidence : []).filter((x) => typeof x === "string" && x.trim());
+      if (!["invalid", "already-fixed"].includes(validate.status) || evidence.length === 0) {
+        return await needsHuman(`validate returned status "${validate.status}" ${evidence.length ? "" : "without evidence "}so the issue is not closed automatically.\n\nBuilder reasoning: ${validate.summary ?? "(none)"}`);
+      }
+      await commit("validate");
+      await ghc(["issue", "close", String(issue), "-R", repo, "--reason", "not planned"]);
+      await label("invalid");
+      return await finish("invalid", validate.summary ?? validate.status);
+    }
+    await commit("validate");
+    await label("building");
+
+    planMd = await io.fs.read(file("plan.md")).catch(() => null);
+    if (!planMd) return await needsHuman("builder did not write plan.md");
+    await post("FORGE:PLAN", "", planMd);
+    await commit("architect");
+
+    await postImpl();
+    await commit("implement");
+
+    const g0 = await runGates();
+    if (g0) return g0;
+    }
+
+    // ---- auto path: risky AND large escalates to the full pipeline ----
+    const st = await diffStats();
+    const risk = riskTier(st.files, `${iss.title}\n${iss.body ?? ""}`);
+    if (!resumed && path === "auto" && risk.tier === "high" && isLargeDiff({ files: st.files.length, lines: st.lines })) {
+      await post("FORGE:ROUTE", "", `Risk tier high (${risk.reasons.slice(0, 5).join(", ")}) and diff large (${st.files.length} files, ${st.lines} lines): routing to the full pipeline.`);
+      return await finish("route-full", "risk high and diff large");
+    }
+
+    // ---- review loop ----
+    await label("in-review");
+    let reviewRound = 0, reviewedHead = null, prior = null, reviewAttempt = 0;
+    const review = async (role, system, delta) => {
+      for (let tryN = 0; tryN < 2; tryN++) {
+        const diff = String(await git(["diff", delta ? `${reviewedHead}..HEAD` : `${base}...HEAD`]));
+        await renew();
+        const rr = await io.runner({ role, issue, cwd: wt, model: reviewerModel, resume: null, system, readOnly: true,
+          prompt: reviewerPrompt({ issue: iss, plan: planMd, diff, prior, delta }) });
+        await renew();
+        await attempt("review", ++reviewAttempt, rr);
+        const f = parseFindings(rr?.text);
+        if (f) return f.map((x) => ({ ...x, reviewer: role }));
+      }
+      return null;
+    };
+    for (;!approvedHead;) {
+      const head = String(await git(["rev-parse", "HEAD"])).trim();
+      const delta = reviewedHead !== null;
+      const roles = [["reviewer", REVIEWER_SYSTEM]];
+      if (risk.tier === "high") roles.push(["security-reviewer", SECURITY_REVIEWER_SYSTEM]);
+      const all = [];
+      for (const [role, system] of roles) {
+        const f = await review(role, system, delta);
+        if (f === null) return await needsHuman(`${role} returned no parseable findings twice`);
+        all.push(...f);
+      }
+      reviewedHead = head;
+      const blocking = all.filter(isBlocking);
+      const notes = all.filter((x) => !isBlocking(x));
+      const row = (x) => `- **${x.severity}/${x.confidence}** ${x.file ?? "?"}:${x.line ?? "?"} (${x.scope ?? "introduced"}, ${x.reviewer}) ${x.title ?? ""}${x.failure_scenario ? ` — ${x.failure_scenario}` : ""}`;
+      await post("FORGE:REVIEW", `**Verdict:** ${blocking.length ? "BLOCKING" : "APPROVED"} | round ${reviewRound + 1} | reviewed ${head.slice(0, 12)}${delta ? " (delta)" : ""} | risk ${risk.tier}`,
+        `### Blocking (${blocking.length})\n${blocking.map(row).join("\n") || "none"}\n\n### Notes (${notes.length}, not filed as issues)\n${notes.map(row).join("\n") || "none"}\n\n\`\`\`json\n${JSON.stringify(all, null, 2)}\n\`\`\``);
+      await commit("review");
+      if (!blocking.length) break;
+      if (reviewRound >= MAX_ROUNDS) return await needsHuman(`${blocking.length} blocking finding(s) after ${MAX_ROUNDS} fix rounds`);
+      if (!sessionId) return await needsHuman("blocking findings and the builder session id is unknown, cannot resume");
+      reviewRound++; implRound++; prior = blocking;
+      const rr = await builder("implement", implRound, resumeReviewPrompt({ findings: blocking }), sessionId);
+      await attempt("implement", implRound, rr);
+      await postImpl();
+      const g1 = await runGates();
+      if (g1) return g1;
+    }
+
+    // ---- merge and close (no model) ----
+    await git(["push", "-u", "origin", branch]);
+    const final = await diffStats();
+    const linkLines = Object.entries(links).map(([k, v]) => `- ${k}: ${v.join(", ")}`).join("\n");
+    const prOut = resumed?.pr ? `/pull/${resumed.pr}` : String(await ghc(["pr", "create", "-R", repo, "--base", lane, "--head", branch,
+      "--title", `${(validate?.title ?? iss.title)} (#${issue})`,
+      "--body", `Closes #${issue}\n\nLean path run. Knowledge graph:\n${linkLines}\n\nFiles: ${final.files.length}, lines: ${final.lines}`])).trim();
+    const pr = Number(/\/pull\/(\d+)/.exec(prOut)?.[1] ?? /(\d+)\s*$/.exec(prOut)?.[1]);
+    if (!Number.isInteger(pr)) return await needsHuman(`could not parse PR number from: ${prOut.slice(0, 200)}`);
+    ev({ event: "PR_OPENED", pr });
+
+    const startedAt = now();
+    let pollIndex = 0, gateHead = null;
+    for (;;) {
+      await renew();
+      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)}`);
+      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));
+    }
+    const localHead = String(await git(["rev-parse", "HEAD"])).trim();
+    if (gateHead && !(localHead.startsWith(gateHead) || gateHead.startsWith(localHead))) {
+      return await needsHuman(`CI gate 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 post("FORGE:CLOSE", "", `Merged PR #${pr} at ${localHead.slice(0, 12)}.\n\n- Review rounds: ${reviewRound}\n- Gate rounds: ${gateRounds}\n- Cost: $${usageTotal.cost_usd.toFixed(4)}\n- Wall: ${Math.round((now() - t0) / 1000)}s\n${linkLines}`);
+    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));
+  }
+}