forgedock 1.25.1 → 1.27.0

package/bin/lean/lean.mjs

@@ -10,17 +10,33 @@ import { hostname as osHostname } from "node:os";
 import { appendEvent } from "../engine/runlog.mjs";
 import { codeForTerminalReason, OUTCOME_CODES } from "../engine/outcome-codes.mjs";
 import { ciPollDelayMs, ENGINE_VERSION, DEFAULT_MAX_SESSION_LIMIT_PAUSES, DEFAULT_SESSION_LIMIT_WAIT_MS, parseLeaseHolder, sanitizeLeaseHost } from "../engine.mjs";
-import { openDependency } from "../engine/phases.mjs";
+import { openDependency, isTrustedComment, decomposedSubissues, isDecomposedRecord } from "../engine/phases.mjs";
+import { createHash } from "node:crypto";
+import { TRACKED, validateContract, applyAmendments, precheck, parseReview, decide, closePlan, followupItems, pendingTracking, reviewSkeleton, unnamedEdges, structureNote } from "./conformance.mjs";
 import { checkAdmission, ADMISSION_RETRY_SECONDS } from "./admission.mjs";
 import { resolveLane, isDefaultLane } from "./lane.mjs";
+import { dockerLabels, LEDGER_TTL_MS } from "./ledger.mjs";
 import { retrying, PUSH_TRANSIENT_RE, PUSH_PERMANENT_RE, GH_TRANSIENT_RE, MERGE_TRANSIENT_RE, MERGE_CONFLICT_RE } from "./retry.mjs";
-import { renderInvestigation, renderPlan, renderImplementation, renderReview, renderPrBody, renderTrajectory, capComment, sanitizeMd } from "./render.mjs";
-import { REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, INVESTIGATION_FILE, PLAN_FILE, IMPLEMENTATION_FILE, builderPrompt, resumeBuilderPrompt, reviewerPrompt, REVIEW_DIFF_MAX_BYTES, parseVerdict, blockCorrectionPrompt, HUMAN_BLOCK_REASONS } from "./prompts.mjs";
+import { renderInvestigation, renderImplementation, renderReview, renderPrBody, renderTrajectory, renderContract, renderAmendments, renderShadowReview, parseContractComment, contractJson, capComment, sanitizeMd, MAX_COMMENT_CHARS } from "./render.mjs";
+import { REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, INVESTIGATION_FILE, IMPLEMENTATION_FILE, CONTRACT_FILE, builderPlanPrompt, builderImplementPrompt, contractCorrectionPrompt, conformanceResumePrompt, reviewerPrompt, REVIEW_DIFF_MAX_BYTES, blockCorrectionPrompt, HUMAN_BLOCK_REASONS, structurePrompt, ciFailurePrompt, ciUnavailablePrompt, syncChecks } from "./prompts.mjs";
+import { parseVerify, runCiVerify, VERIFY_MODES } from "./verify.mjs";
 
 export const DEFAULT_REVIEWER_MODEL = "claude-sonnet-5-5";
+/** forge.yaml engine.conformance: "shadow" (default) posts and logs the gate's verdict without enforcing it; "enforce" blocks on it. */
+export const CONFORMANCE_MODES = Object.freeze(["shadow", "enforce"]);
+/** In shadow mode only what the previous two-question reviewer blocked on still blocks: a requirement not done, a regression. */
+const SHADOW_BLOCKS = [OUTCOME_CODES.CONFORMANCE_UNIMPLEMENTED, OUTCOME_CODES.CONFORMANCE_REGRESSION];
+/**
+ * Precheck failures that block in shadow mode too (#4160): the builder's own validate command failed, or it reported a
+ * contracted requirement as not done. These are the precheck's form of "a requirement not done". Missing validate results
+ * (often CI-only steps), scope creep and amendment problems stay recorded-only in shadow.
+ */
+const SHADOW_PRE_BLOCKS = ["validate_failed", "requirement_unimplemented"];
 export const REGISTER_MARKER = "FORGE:WORK-ON"; // alias marker carried by the FORGE:TRAJECTORY comment
 const num = (v) => (Number.isFinite(v) ? v : null);
 export const MAX_SUBISSUES = 8;
+/** 12-hex sha256 of the canonical contract JSON text (renderContract embeds the same text). */
+export const contractHash = (text) => createHash("sha256").update(String(text)).digest("hex").slice(0, 12);
 
 /**
  * Typed builder block (#4124), from result.json `block`. Returns {kind:"dependency", issues} | {kind:"split", subissues}
@@ -47,6 +63,15 @@ export function classifyBlock(result, issue) {
   return { kind: "untyped", problem: `block kind "${String(b.kind ?? "").slice(0, 40)}" is unknown` };
 }
 
+/**
+ * Never a branch-deletion target (#4179): anything but the issue's own `feat/issue-<n>-lean`, and never main, master,
+ * staging, the lane, forge.yaml's default/staging branch, `milestone/*` or a default branch of the repo.
+ */
+export function isProtectedLaneBranch(b, { issue, lane = null, branches = {}, defaults = [] } = {}) {
+  if (typeof b !== "string" || b !== `feat/issue-${issue}-lean`) return true;
+  return ["main", "master", "staging", lane, branches?.default, branches?.staging].includes(b) || /^milestone\//.test(b) || isDefaultLane(b, defaults);
+}
+
 /**
  * @param {object} o
  * @param {number} o.issue
@@ -60,13 +85,18 @@ export function classifyBlock(result, issue) {
  * @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
+ * @param {"shadow"|"enforce"} [o.conformance] conformance gate mode (default shadow)
+ * @param {object} [o.verify]        forge.yaml verify (verify.mjs parseVerify): mode local (default) | ci | hybrid (#4167)
  */
 export async function runCore(o) {
   const { issue, repo, lane: requestedLane = null, laneOverride = false, branches = {}, cwd, dir, io, builderModel = null, reviewerModel = DEFAULT_REVIEWER_MODEL,
-    ciMaxMinutes = 360, mergeWait = "required", maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES, cliIdleMinutes = 15, cliMaxMinutes = 180, laneLimits = null, maxMergeRetries = 5, sessionLimitMaxWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS, onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
+    ciMaxMinutes = 360, conformance = "shadow", mergeWait = "required", maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES, cliIdleMinutes = 15, cliMaxMinutes = 180, laneLimits = null, maxMergeRetries = 5, sessionLimitMaxWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS, onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
   const now = io.now ?? (() => Date.now());
+  const vcfg = { ...parseVerify({}), ...(o.verify ?? {}) };
+  if (!VERIFY_MODES.includes(vcfg.mode)) vcfg.mode = "local";
+  const remoteVerify = vcfg.mode !== "local";
   const sleep = io.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-  let lane = null, base = null, defaults = []; // set by lane resolution, before the lease
+  let lane = null, base = null, defaults = [], milestone = null; // set by lane resolution, before the lease
   const branch = `feat/issue-${issue}-lean`;
   const wt = join(o.worktreeRoot ?? join(cwd, ".claude", "worktrees"), `lean-${issue}`);
   const t0 = now();
@@ -112,7 +142,7 @@ export async function runCore(o) {
   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(leaseObj()); } catch { /* best effort */ } } };
+  const renew = async () => { if (io.projector && leaseState && !finishing) { /* never re-take a lease a finish (or signal) released */ try { await writeLease(leaseObj()); } catch { /* best effort */ } } };
   async function releaseLease(reason) {
     if (leaseTimer) { clearInterval(leaseTimer); leaseTimer = null; }
     if (!io.projector || !leaseState) return;
@@ -122,11 +152,91 @@ export async function runCore(o) {
 
   // Pipeline trajectory (posted once at the end): phase rows, decisions, anomalies.
   const T = { issue, validate: null, plan: null, implement: null, review: null, pr: null, merge: null, close: null, decisions: [], anomalies: [] };
-  let done = null, wtCreated = false;
+  let done = null, finishing = null, wtCreated = false, salvagedRef = null;
   const runId = `${issue}-${t0}`;
   let runTmp = null;
-  async function finish(reason, detail = "", extra = {}, codeOverride = null) {
-    if (done) return done; // idempotent: exactly one RUN_TERMINAL and one telemetry emit
+  // ---- lane resource ledger (#4179): every owned resource is registered before it is created, released after its teardown ----
+  let ledger = null, deleteLocalBranch = false;
+  const ledgerDo = (fn) => { if (!ledger) return; try { fn(ledger); } catch (e) { ev({ event: "LEDGER_ERROR", error: String(e?.message ?? e).slice(0, 300) }); } };
+  const protectedBranch = (b) => isProtectedLaneBranch(b, { issue, lane, branches, defaults });
+  /** Teardown from the ledger (#4179), on every exit path: builder pids, checkpoint of unpushed work, run tmp, worktree, branch, docker. */
+  async function teardown(reason, extra) {
+    for (const p of ledger ? ledger.entries("pid") : []) {
+      try { if (await io.killGroup?.(p.value, p.marker)) ledgerDo((l) => l.release("pid", p.value)); } catch { /* keep it listed */ }
+    }
+    // Never discard work silently: an unmerged lane commits and pushes what is left before its worktree goes.
+    const saved = !wtCreated || reason === "merged" || (await checkpoint(`exit (${reason})`));
+    if (runTmp) {
+      try { if ((await io.runTmp.remove(runTmp)) !== false) ledgerDo((l) => l.release("tmp", runTmp)); } catch { /* best effort */ }
+      runTmp = null;
+    } // every terminal, including engine-error and deferred
+    if (wtCreated && saved) {
+      let removed = false;
+      try { await io.git(["worktree", "remove", "--force", wt], { cwd }); removed = true; } catch { /* best effort */ }
+      try { await io.git(["worktree", "prune"], { cwd }); } catch { /* best effort */ }
+      if (removed) ledgerDo((l) => l.release("worktree", wt));
+      let branchDone = true;
+      if ((reason === "invalid" && !extra.pr) || (reason === "merged" && deleteLocalBranch)) {
+        try { await io.git(["branch", "-D", branch], { cwd }); } catch { branchDone = reason !== "merged"; }
+      }
+      if (branchDone) ledgerDo((l) => l.release("branch", branch));
+    } else if (wtCreated) {
+      ev({ event: "TEARDOWN_KEPT", reason: "checkpoint failed: worktree and branch kept so no work is lost", worktree: wt });
+    }
+    for (const kind of ["container", "volume"]) {
+      for (const r of ledger ? ledger.entries(kind) : []) {
+        if (!io.docker) continue;
+        try { await io.docker(kind === "container" ? ["rm", "-f", String(r.value)] : ["volume", "rm", String(r.value)]); ledgerDo((l) => l.release(kind, r.value)); } catch { /* docker absent or busy: keep it listed */ }
+      }
+    }
+    ledgerDo((l) => { if (l.remove()) ev({ event: "LEDGER_CLEARED", path: l.path }); else ev({ event: "LEDGER_KEPT", path: l.path, resources: l.entries().map((r) => `${r.kind}:${r.value}`) }); });
+  }
+  /**
+   * #4162: save the worktree's uncommitted work (tracked, untracked and .forge-lean/) to refs/forge/salvage/<issue>/<ms>
+   * before an earlier run's worktree is removed at the start of this run (a run that died hard never ran its
+   * teardown checkpoint, #4179). It stages into the worktree's own index, which is discarded with the worktree, and
+   * the ref lives in the shared repo, so it survives the removal. Returns the ref, or null when there is nothing to save.
+   */
+  async function salvage(why) {
+    if (!io.fs?.exists || !(await io.fs.exists(wt))) return null;
+    const g = (a) => io.git(a, { cwd: wt });
+    try {
+      await g(["add", "-A"]);
+      if (await io.fs.exists(join(wt, LEAN_DIR))) await g(["add", "-f", "--", LEAN_DIR]);
+      const tree = String(await g(["write-tree"])).trim();
+      const headTree = String(await g(["rev-parse", "HEAD^{tree}"])).trim();
+      if (!/^[0-9a-f]{40,64}$/.test(tree) || tree === headTree) return null;
+      const commit = String(await g(["-c", "user.name=forgedock", "-c", "user.email=forgedock@localhost", "commit-tree", tree, "-p", "HEAD", "-m", `forge salvage #${issue}: ${why}`])).trim();
+      if (!/^[0-9a-f]{40,64}$/.test(commit)) return null;
+      const ref = `refs/forge/salvage/${issue}/${now()}`;
+      await io.git(["update-ref", ref, commit], { cwd });
+      ev({ event: "WORKTREE_SALVAGED", ref, why });
+      T.anomalies.push(`Uncommitted work from ${why} saved to \`${ref}\` (inspect: \`git diff HEAD ${ref} --stat\`)`);
+      return ref;
+    } catch (e) {
+      ev({ event: "WORKTREE_SALVAGE_FAILED", why, error: String(e?.message ?? e).slice(0, 300) });
+      return null;
+    }
+  }
+  /** #4162: stop processes still running inside the worktree (an orphaned runner from a dead run) before it is removed. */
+  async function stopWorktreeProcs() {
+    if (!io.proc) return;
+    const procs = await Promise.resolve(io.proc.inDir(wt)).catch(() => []);
+    if (!procs.length) return;
+    for (const p of procs) io.proc.kill(p.pid, "SIGTERM");
+    for (let i = 0; i < 10 && procs.some((p) => io.proc.alive(p.pid)); i++) await sleep(500);
+    const left = procs.filter((p) => io.proc.alive(p.pid));
+    for (const p of left) io.proc.kill(p.pid, "SIGKILL");
+    ev({ event: "WORKTREE_PROCS_STOPPED", pids: procs.map((p) => p.pid), killed: left.map((p) => p.pid) });
+    T.anomalies.push(`Stopped ${procs.length} process(es) still running in the worktree from an earlier run: ${procs.map((p) => `${p.pid} ${p.cmd ?? ""}`.trim().slice(0, 80)).join("; ")}`);
+  }
+  function finish(...args) {
+    if (done) return Promise.resolve(done);
+    finishing ??= finishOnce(...args); // a signal during a normal finish waits for the same teardown
+    return finishing;
+  }
+  async function finishOnce(reason, detail = "", extra = {}, codeOverride = null) {
+    await teardown(reason, extra); // first: unpushed work is pushed while this run still holds the lease
     const code = codeOverride ?? codeForTerminalReason(reason);
     ev({ event: "RUN_TERMINAL", reason, code });
     await emit({ event: "RUN_TERMINAL", reason, code });
@@ -141,11 +251,6 @@ export async function runCore(o) {
       try { await post(["FORGE:TRAJECTORY", REGISTER_MARKER], renderTrajectory({ ...T, usage: usageLine() })); } catch { /* best effort */ }
     }
     await releaseLease(reason);
-    if (runTmp) { try { await io.runTmp.remove(runTmp); } catch { /* best effort */ } runTmp = null; } // every terminal, including engine-error and deferred
-    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;
   }
@@ -160,7 +265,6 @@ export async function runCore(o) {
   // ---- stage notes: investigation.md, plan.md, implementation.md become their own comments ----
   const STAGES = [
     { key: "investigation", file: INVESTIGATION_FILE, marker: ["FORGE:INVESTIGATION", "FORGE:VALIDATE"], render: (md, ctx) => renderInvestigation(md, ctx.result) },
-    { key: "plan", file: PLAN_FILE, marker: ["FORGE:PLAN"], render: (md, ctx) => renderPlan(md, ctx.result, ctx.files) },
     { key: "implementation", file: IMPLEMENTATION_FILE, marker: ["FORGE:IMPLEMENTATION"], render: (md, ctx) => renderImplementation(md, ctx.result, { branch, files: ctx.files }) },
   ];
   const posted = {}; // key -> comment url (or "" when posted without a link)
@@ -176,10 +280,25 @@ export async function runCore(o) {
     const url = await post(st.marker, st.render(md, { result, files }));
     posted[st.key] = url ?? "";
   }
+  /** Re-render a stage note that changed after a resume: edit the posted comment in place; post it when it was never posted or the edit fails. */
+  async function upsertStage(key) {
+    const st = STAGES.find((x) => x.key === key);
+    const id = /#issuecomment-(\d+)/.exec(posted[key] ?? "")?.[1];
+    const res = await readResult(), md = await readStage(st);
+    if (id) {
+      const files = key === "implementation" ? await stageFiles() : [];
+      const marks = st.marker.map((m) => `<!-- ${m} -->`).join("\n");
+      try { await ghw(["api", "-X", "PATCH", `repos/${repo}/issues/comments/${id}`, "-f", `body=${capComment(`${marks}\n${st.render(usableMd(md) ? md : null, { result: res, files })}`)}`]); return; } catch { /* fall back to a new comment */ }
+    }
+    delete posted[key];
+    await flushStages(res, [key]);
+  }
   /** Post stage notes in order that exist, are stable (mtime unchanged for stableMs) and not yet posted. */
   const seen = {};
+  let liveKeys = ["investigation"]; // which stage notes the running builder call may publish live (plan: investigation; implement: implementation)
   async function livePoll() {
     for (const st of STAGES) {
+      if (!liveKeys.includes(st.key)) continue;
       if (st.key in posted) continue;
       let m = null;
       try { m = await io.fs.stat(`${wt}/${st.file}`); } catch { m = null; }
@@ -209,7 +328,9 @@ export async function runCore(o) {
   async function callRunner(args) {
     let pauses = 0;
     for (;;) {
-      try { return await io.runner({ ...args, ...(runTmp ? { env: { TMPDIR: runTmp, CLAUDE_CODE_TMPDIR: runTmp } } : {}) }); }
+      // #4181: every Docker resource the builder creates carries the lane's ownership labels (same batch/lane as the ledger).
+      const labels = dockerLabels({ batch: o.batchId ?? "adhoc", lane: `lean-${issue}`, issue, expires: now() + LEDGER_TTL_MS }).join(" ");
+      try { return await io.runner({ ...args, env: { FORGE_DOCKER_LABELS: labels, ...(runTmp ? { TMPDIR: runTmp, CLAUDE_CODE_TMPDIR: runTmp } : {}) } }); }
       catch (e) {
         const epoch = Number.isFinite(e?.resetAtEpochMs) ? e.resetAtEpochMs : null;
         if (!(e?.usageLimit === true || epoch !== null)) throw e;
@@ -241,9 +362,13 @@ export async function runCore(o) {
       const ahead = String(await git(["diff", "--name-only", `${base}...HEAD`])).trim();
       if (ahead) await gitPush(["push", "-u", "origin", branch]);
       ev({ event: "CHECKPOINT", reason, dirty: Boolean(dirty), pushed: Boolean(ahead) });
-    } catch (e) { ev({ event: "CHECKPOINT_FAILED", reason, error: String(e?.message ?? e).slice(0, 300) }); }
+      return true;
+    } catch (e) { ev({ event: "CHECKPOINT_FAILED", reason, error: String(e?.message ?? e).slice(0, 300) }); return false; }
   }
   const CONTINUE_NOTE = "\n\nThe branch already holds work from an earlier session that was interrupted (see the latest `wip(forge): checkpoint` commit). Continue from it: read `git log` and `git diff origin/BASE...HEAD`, do not start over.";
+  const PLAN_RERUN_NOTE = "\n\nThis is a rerun: the branch already holds commits from an earlier run. Read `git log` and `git diff origin/BASE...HEAD` to see what exists, but plan against the issue itself. This step is still planning only: do not edit code, do not commit, and do not write the result file unless the issue is invalid, already fixed or blocked.";
+  const SALVAGE_NOTE = "\n\nAn earlier run on this issue stopped with uncommitted work, saved at `REF` (not on the branch). Inspect it with `git diff HEAD REF --stat` and reuse what fits the contract (`git checkout REF -- <path>`) instead of rewriting it.";
+  const RERUN_NOTE = `\n\nThis is a rerun: the branch already holds commits from an earlier run. Read \`git log\` and \`git diff origin/BASE...HEAD\`, verify that work against the contract, complete what is missing, ${vcfg.mode === "ci" ? "re-run the light checks (the engine verifies on CI)" : "re-run every validate command"} and write the result file. Do not start over.`;
 
   /** Continuous admission (#4115): while the builder runs, pause its process group when the host is over the ceiling, resume when under. */
   function startGovernor(control) {
@@ -267,7 +392,9 @@ export async function runCore(o) {
     return { async stop() { stopped = true; wake?.(); clearTimeout(t); await loop; if (paused) { control.resume?.(); paused = false; } } };
   }
 
-  async function builder(n, prompt, resume, live = false) {
+  /** A timeout restart starts a fresh session; by default it continues the implementation against the frozen contract. */
+  const implementRestart = () => builderImplementPrompt(vcfg.mode) + CONTINUE_NOTE.replace("BASE", lane);
+  async function builder(n, prompt, resume, live = false, restart = implementRestart) {
     let timeoutRetries = 0, p = prompt;
     for (;;) {
       try { return await builderOnce(n, p, resume, live); } catch (e) {
@@ -279,7 +406,7 @@ export async function runCore(o) {
         if (timeoutRetries++ >= 1) { e.deferCode = idle ? OUTCOME_CODES.CLI_IDLE : OUTCOME_CODES.CLI_TIMEOUT; e.deferDetail = `builder ${reason}; work checkpointed to ${branch}; rerun resumes from it. ${String(e.message).slice(0, 300)}`; throw e; }
         T.anomalies.push(`builder ${reason}: checkpointed, retried once`);
         T.decisions.push(`Builder ${reason}: uncommitted work checkpointed to the lane branch; retrying once from the checkpoint`);
-        p = builderPrompt(issue) + CONTINUE_NOTE.replace("BASE", base); resume = null;
+        p = restart(); resume = null;
       }
     }
   }
@@ -289,8 +416,11 @@ export async function runCore(o) {
     await renew();
     const control = {};
     const governor = startGovernor(control);
-    const call = Promise.resolve(callRunner({ role: "builder", issue, cwd: wt, model: builderModel, resume, system: "", prompt, control,
+    let spawned = null;
+    const onSpawn = (child) => { if (Number.isSafeInteger(child?.pid) && !finishing) { spawned = child.pid; ledgerDo((l) => l.register("pid", child.pid, { marker: basename(String(child.spawnfile ?? "")) || null })); } };
+    const call = Promise.resolve(callRunner({ role: "builder", issue, cwd: wt, model: builderModel, resume, system: "", prompt, control, onSpawn,
       idleMs: Math.round(cliIdleMinutes * 60000), maxMs: Math.round(cliMaxMinutes * 60000), laneLimits }));
+    call.then(() => {}, () => {}).finally(() => { if (spawned) ledgerDo((l) => l.release("pid", spawned)); });
     let r;
     call.catch(() => governor.stop());
     if (live && io.fs.stat) {
@@ -307,12 +437,25 @@ export async function runCore(o) {
     } else { try { r = await call; } finally { /* governor stops below */ } }
     await governor.stop();
     await renew();
+    await registerReported();
     if (r?.sessionId) sessionId = r.sessionId;
     await attempt("implement", n, r);
     onProgress({ event: "phase_exit", phase: "build", status: "committed" });
     return r;
   }
+  const readContract = async () => { try { const j = JSON.parse(await io.fs.read(`${wt}/${CONTRACT_FILE}`)); return j && typeof j === "object" ? j : null; } catch { return null; } };
   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; } };
+  /** Containers/volumes the builder reported in result.json `resources` go into the ledger, so teardown removes them. */
+  async function registerReported() {
+    if (!ledger || finishing) return; // after teardown nothing new is owned
+    const res = (await readResult())?.resources;
+    if (!res || typeof res !== "object") return;
+    for (const [key, kind] of [["containers", "container"], ["volumes", "volume"]]) {
+      for (const v of Array.isArray(res[key]) ? res[key] : []) {
+        if (typeof v === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(v)) ledgerDo((l) => l.register(kind, v));
+      }
+    }
+  }
 
   /** Live-checks a builder block (#4124). Dependency issues are re-read, so a closed or unknown number is not a block. */
   async function resolveBlock(r) {
@@ -325,8 +468,20 @@ export async function runCore(o) {
         return { kind: "unreadable", detail: `dependency #${d} named by the builder could not be read: ${String(e?.message ?? e).slice(0, 200)}` };
       }
       if (String(v?.state).toUpperCase() !== "OPEN") continue;
-      open.push(d);
-      if ((v.labels ?? []).some((l) => (l?.name ?? l) === "needs-human")) blockers.push(d);
+      // #4153: an open decomposed parent resolves to its open sub-issues; it is satisfied once they all close.
+      const subs = isDecomposedRecord(v) ? await decomposedSubissues(d, io) : null;
+      const recs = [];
+      if (!subs) recs.push([d, v]);
+      else for (const n of subs) {
+        try { recs.push([n, JSON.parse(String(await ghc(["issue", "view", String(n), "-R", repo, "--json", "state,labels"])))]); } catch (e) {
+          return { kind: "unreadable", detail: `sub-issue #${n} of decomposed dependency #${d} could not be read: ${String(e?.message ?? e).slice(0, 200)}` };
+        }
+      }
+      for (const [n, rec] of recs) {
+        if (String(rec?.state).toUpperCase() !== "OPEN" || n === Number(issue) || open.includes(n)) continue;
+        open.push(n);
+        if ((rec.labels ?? []).some((l) => (l?.name ?? l) === "needs-human")) blockers.push(n);
+      }
     }
     if (!open.length) return { kind: "untyped", problem: `its dependencies ${b.issues.map((n) => `#${n}`).join(", ")} are not open` };
     return { kind: "dependency", issues: open, blockers };
@@ -353,7 +508,8 @@ export async function runCore(o) {
       try {
         for (const sub of b.subissues) {
           const lines = [`**Parent**: #${issue}`, ...sub.dependsOn.map((j) => `**Depends on**: #${filed[j]}`)];
-          const out = String(await ghw(["issue", "create", "-R", repo, "--title", sub.title, "--body", `${sub.body.trim()}\n\n${lines.join("\n")}`]));
+          // #4153: the parent's milestone, so each sub-issue derives the parent's lane before any lane runs.
+          const out = String(await ghw(["issue", "create", "-R", repo, "--title", sub.title, "--body", `${sub.body.trim()}\n\n${lines.join("\n")}`, ...(milestone ? ["--milestone", milestone] : [])]));
           const n = Number(/\/issues\/(\d+)/.exec(out)?.[1]);
           if (!Number.isSafeInteger(n)) throw new Error(`cannot parse the sub-issue number from: ${out.slice(0, 200)}`);
           filed.push(n);
@@ -376,7 +532,7 @@ export async function runCore(o) {
   {
     const r = await resolveLane({ issue, repo, io, cwd, branches, requested: requestedLane, override: laneOverride });
     if (!r.ok) return { terminalReason: "lane-refused", code: r.code, detail: r.detail };
-    lane = r.lane; base = `origin/${lane}`; defaults = r.defaults;
+    lane = r.lane; base = `origin/${lane}`; defaults = r.defaults; milestone = r.milestone ?? null;
     if (r.overridden) T.decisions.push(`Lane override: ${lane} instead of the resolved ${r.expected}`);
   }
   /** Last guard before a PR is created or merged: the default branch is never a lane. */
@@ -408,14 +564,22 @@ export async function runCore(o) {
     leaseTimer.unref?.();
   }
 
+  if (io.ledger) {
+    try { ledger = io.ledger({ batch: o.batchId ?? "adhoc", lane: `lean-${issue}`, owner: agentId, issue, host: myHost }); } catch { ledger = null; }
+  }
+  // A signal (engine-cli SIGTERM/SIGINT) runs the same teardown and lease release as any other exit.
+  o.onTeardown?.((signal) => finish("deferred", `interrupted by ${signal}`, { code: OUTCOME_CODES.RUN_INTERRUPTED }, OUTCOME_CODES.RUN_INTERRUPTED));
   if (io.runTmp) {
     try { await io.runTmp.prune?.(); } catch { /* best effort */ }
+    const planned = io.runTmp.path?.(runId);
+    if (planned) ledgerDo((l) => l.register("tmp", planned));
     try { runTmp = await io.runTmp.make(issue, runId); } catch { runTmp = null; }
+    if (runTmp && runTmp !== planned) ledgerDo((l) => l.register("tmp", runTmp));
   }
   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"]));
+    iss = JSON.parse(await ghc(["issue", "view", String(issue), "-R", repo, "--json", "number,title,body,state,comments"]));
   } catch (e) { return finish("engine-error", `cannot read issue: ${e.message}`); }
   if (String(iss.state).toUpperCase() === "CLOSED") return finish("invalid", "issue already closed");
 
@@ -437,6 +601,10 @@ export async function runCore(o) {
       return await needsHuman(`Open PR #${resumed.pr} targets \`${resumed.base}\`, but #${issue}'s lane is \`${lane}\`; retarget or close it before rerunning.`,
         isDefaultLane(resumed.base, defaults) ? OUTCOME_CODES.LANE_DEFAULT_BRANCH : OUTCOME_CODES.LANE_MISMATCH);
     }
+    // #4162: a run that died can leave its runner writing into this worktree, and uncommitted work in it. Stop the
+    // processes and save the work before the worktree is removed; the lease above makes this run the only one doing so.
+    await stopWorktreeProcs();
+    salvagedRef = await salvage("an earlier run");
     try { await io.git(["worktree", "remove", "--force", wt], { cwd }); } catch { /* none */ }
     try { await io.git(["worktree", "prune"], { cwd }); } catch { /* best effort */ }
     // Concurrent lanes in one repo race on .git/config.lock / index.lock during `worktree add`; retry with jitter.
@@ -476,6 +644,7 @@ export async function runCore(o) {
         keepLocal = containsRemote;
       }
     } catch { /* no local branch */ }
+    ledgerDo((l) => { l.register("branch", branch); l.register("worktree", wt); });
     if (keepLocal) {
       await addWorktree(["worktree", "add", wt, branch]);
       resumed = resumed ?? { pr: null, local: true };
@@ -490,14 +659,33 @@ export async function runCore(o) {
     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 ----
+    // ---- 3. builder: plan call -> frozen contract -> implement call in the same session ----
     let result = null, attemptN = 0, reviewN = 0;
     const lastSubject = resumed ? String(await git(["log", "-1", "--format=%s"]).catch(() => "")).trim() : "";
     const fromCheckpoint = lastSubject.startsWith("wip(forge): checkpoint");
-    if (!(resumed && (await changedFiles()).length > 0) || fromCheckpoint) {
-      await label("building");
-      await builder(++attemptN, builderPrompt(issue) + (fromCheckpoint ? CONTINUE_NOTE.replace("BASE", base) : ""), null, true);
-      result = await readResult();
+    const hasCommits = resumed ? (await changedFiles()).length > 0 : false;
+    // Requirements may only be quoted from the issue and trusted comments: an untrusted commenter cannot add a contract requirement.
+    const trustedOf = (i) => (i.comments ?? []).filter((c) => {
+      const login = String(c?.author?.login ?? c?.user?.login ?? "");
+      return isTrustedComment({ author_association: c?.authorAssociation ?? c?.author_association, user: { login, type: c?.user?.type ?? (/\[bot\]$|^app\//.test(login) ? "Bot" : "User") } });
+    });
+    const textOf = (i, tc) => [i.title, i.body ?? "", ...tc.map((c) => c?.body ?? "")].join("\n\n");
+    let trustedComments = trustedOf(iss);
+    let issueText = textOf(iss, trustedComments);
+    /** #4188: the builder reads the live issue, so quotes are checked against the current text, not the RUN_START snapshot. Best effort. */
+    async function refreshIssue(stage) {
+      let next;
+      try { next = JSON.parse(String(await ghc(["issue", "view", String(issue), "-R", repo, "--json", "number,title,body,state,comments"]))); } catch { return; }
+      if (!next || typeof next !== "object") return;
+      const tc = trustedOf(next), text = textOf(next, tc);
+      const old = contractHash(issueText), now = contractHash(text);
+      if (old === now) return;
+      iss = next; trustedComments = tc; issueText = text;
+      ev({ event: "ISSUE_EDITED", old, new: now, stage });
+      T.decisions.push(`Issue edited during the run (${old} -> ${now}); ${stage} uses the current text`);
+    }
+    /** A typed block (with one corrective resume for an untyped one) ends the run; returns the terminal or null. */
+    async function endIfBlocked() {
       let block = result?.status === "blocked" ? await resolveBlock(result) : null;
       if (block?.kind === "untyped" && sessionId) { // #4124: one corrective resume before any untyped block can reach needs-human
         T.decisions.push(`Builder block rejected (${block.problem}); resumed once`);
@@ -505,70 +693,303 @@ export async function runCore(o) {
         result = await readResult();
         block = result?.status === "blocked" ? await resolveBlock(result) : null;
       }
-      const files0 = await changedFiles();
+      return block ? await endBlocked(block, result.summary) : null;
+    }
+    /** File (or append to) the parent's one batched follow-up issue for these requirements, then verify each tracking issue is open. */
+    async function track(reqs, why) {
+      const fail = (detail) => Object.assign(new Error(detail), { deferCode: OUTCOME_CODES.FOLLOWUP_UNAVAILABLE, deferDetail: `${detail}; nothing merged, rerun to retry` });
+      if (!io.fileFollowups) throw fail("no follow-up filing effect is configured");
+      const items = followupItems(reqs);
+      let filed;
+      try { filed = await io.fileFollowups({ parent: issue, repo, items }); } catch (e) { throw fail(`filing the follow-up issue failed: ${String(e?.message ?? e).slice(0, 200)}`); }
+      for (const [i, r] of reqs.entries()) {
+        const n = Number(filed?.[items[i].key]);
+        if (!Number.isSafeInteger(n) || n <= 0) throw fail(`no tracking issue was returned for ${r.id}`);
+        let st = null;
+        try { st = JSON.parse(String(await ghc(["issue", "view", String(n), "-R", repo, "--json", "number,state"]))); } catch { st = null; }
+        if (String(st?.state).toUpperCase() !== "OPEN") throw fail(`tracking issue #${n} for ${r.id} is not open or unreadable`);
+        r.tracked = `#${n}`;
+      }
+      T.decisions.push(`Tracked ${reqs.map((r) => `${r.id} (${r.disposition})`).join(", ")} in ${[...new Set(reqs.map((r) => r.tracked))].join(", ")} (${why})`);
+    }
+    /** The frozen contract posted by an earlier run of this issue, verified against its hash; null when absent. */
+    async function readFrozenContract() {
+      let out = "";
+      try { out = String(await ghc(["api", "--paginate", `repos/${repo}/issues/${issue}/comments`, "--jq", ".[] | {body, author_association, user: {type: .user.type, login: .user.login}}"])); } catch { return null; }
+      let found = null;
+      for (const l of out.split("\n")) {
+        let c; try { c = JSON.parse(l); } catch { continue; }
+        if (!String(c?.body ?? "").startsWith("<!-- FORGE:CONTRACT -->") || !isTrustedComment(c)) continue;
+        const fc = parseContractComment(c.body);
+        if (fc && contractHash(fc.text) === fc.hash) found = fc;
+      }
+      return found;
+    }
+
+    let frozen = null, hash = null, planned = false;
+    if (resumed) {
+      const fc = await readFrozenContract();
+      if (fc) { frozen = fc.contract; hash = fc.hash; T.decisions.push(`Rerun: frozen contract ${hash} recovered from the issue`); }
+    }
+    await label("building");
+    if (!frozen) {
+      await builder(++attemptN, builderPlanPrompt(issue) + (hasCommits ? PLAN_RERUN_NOTE.replace("BASE", lane) : ""), null, true, () => builderPlanPrompt(issue));
+      planned = true;
+      result = await readResult();
       const evidence = (Array.isArray(result?.evidence) ? result.evidence : []).filter((x) => typeof x === "string" && x.trim());
-      const closing = ["invalid", "already-fixed"].includes(result?.status);
-      await flushStages(result, ["investigation"]); // first stage note: the evidence comment for invalid/already-fixed
-      T.validate = [result ? (result.status === "fixed" ? "CONFIRMED" : String(result.status).toUpperCase()) : "no result.json", `${evidence.length} evidence item(s)`];
-      T.decisions.push(`Builder verdict: ${result?.status ?? "none"}`);
-      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)"}`, OUTCOME_CODES.BUILDER_NO_EVIDENCE);
-      if (closing) {
+      const closes = ["invalid", "already-fixed"].includes(result?.status);
+      if (closes || result?.status === "blocked") await flushStages(result, ["investigation"]); // the evidence comment for invalid/already-fixed
+      T.validate = [result?.status ? String(result.status === "fixed" ? "CONFIRMED" : result.status).toUpperCase() : "CONFIRMED", `${evidence.length} evidence item(s)`];
+      if (closes && !evidence.length) return await needsHuman(`Builder reported "${result.status}" without evidence, so the issue is not closed automatically.\n\n${result.summary ?? "(no summary)"}`, OUTCOME_CODES.BUILDER_NO_EVIDENCE);
+      if (closes) {
         T.plan = "skipped"; T.implement = "skipped"; T.review = "skipped"; T.pr = "none"; T.merge = "n/a";
+        T.decisions.push(`Builder verdict: ${result.status}`);
         await ghw(["issue", "close", String(issue), "-R", repo, "--reason", "not planned"]);
         await label("invalid");
         return await finish("invalid", result.summary ?? result.status);
       }
-      if (block) return await endBlocked(block, result.summary);
-      if (!files0.length) return await needsHuman(`Builder made no commit${result ? ` (status "${result.status}")` : " and wrote no result.json"}.\n\n${result?.summary ?? ""}`, OUTCOME_CODES.BUILDER_NO_COMMIT);
-      await flushStages(result, ["plan", "implementation"]);
-      T.plan = "posted"; T.implement = [`${files0.length} file(s)`, branch];
+      const blocked = await endIfBlocked();
+      if (blocked) return blocked;
+      let contract = await readContract();
+      await refreshIssue("contract validation");
+      let vc = validateContract(contract, issueText);
+      if (!vc.ok && sessionId) {
+        T.decisions.push(`Contract rejected (${vc.problems[0]}); resumed once`);
+        await builder(++attemptN, contractCorrectionPrompt(vc.problems), sessionId, false, () => builderPlanPrompt(issue));
+        contract = await readContract();
+        await refreshIssue("contract validation");
+        vc = validateContract(contract, issueText);
+      }
+      await flushStages(result ?? { status: "fixed" }, ["investigation"]); // always posted: FORGE:INVESTIGATION/VALIDATE are read downstream
+      if (!vc.ok) return await needsHuman(`The builder's contract is still invalid after one correction:\n${vc.problems.slice(0, 12).map((x) => `- ${x}`).join("\n")}`, OUTCOME_CODES.CONTRACT_INVALID);
+      frozen = contract;
+      hash = contractHash(contractJson(frozen));
+      let body = renderContract(frozen, hash);
+      if (body.length > MAX_COMMENT_CHARS - 500) body = renderContract(frozen, hash, { compact: true }); // the JSON must survive the comment cap
+      await post(["FORGE:CONTRACT", "FORGE:PLAN"], body);
+      const deferredN = frozen.requirements.filter((r) => TRACKED.includes(r.disposition)).length;
+      ev({ event: "CONTRACT_FROZEN", hash, requirements: frozen.requirements.length, deferred: deferredN });
+      T.decisions.push(`Contract frozen (${hash}): ${frozen.requirements.length} requirement(s), ${deferredN} deferred pending review`);
     } else {
-      T.validate = "resumed (existing branch)"; T.plan = "skipped (resumed)"; T.implement = ["existing commits", branch];
-      T.decisions.push("Open PR or remote branch found: builder skipped, reviewing existing commits");
+      T.validate = "resumed (existing branch)";
+    }
+    T.plan = [`contract ${hash}`, `${frozen.requirements.length} requirement(s)`];
+    if (io.fs.write) { try { await io.fs.write(`${wt}/${CONTRACT_FILE}`, `${contractJson(frozen)}\n`); } catch { /* the prompt still names it */ } }
+    const implementPrompt = builderImplementPrompt(vcfg.mode) + (planned ? "" : (fromCheckpoint ? CONTINUE_NOTE : RERUN_NOTE).replace("BASE", lane)) + (salvagedRef ? SALVAGE_NOTE.replaceAll("REF", salvagedRef) : "");
+    liveKeys = ["implementation"];
+    await builder(++attemptN, implementPrompt, planned ? sessionId : null, true);
+    result = await readResult();
+    {
+      const blocked = await endIfBlocked();
+      if (blocked) return blocked;
+    }
+    let files = await changedFiles();
+    if (!files.length) return await needsHuman(`Builder made no commit${result ? ` (status "${result.status}")` : " and wrote no result.json"}.\n\n${result?.summary ?? ""}`, OUTCOME_CODES.BUILDER_NO_COMMIT);
+    await flushStages(result, ["implementation"]);
+    T.implement = [`${files.length} file(s)`, branch];
+    T.decisions.push(`Builder verdict: ${result?.status ?? "none"}`);
+
+    // ---- 3b. structure delta (forge#4159): deterministic, before the conformance review; no reviewer run of its own ----
+    // A package.json edge between workspace packages the contract does not name blocks (one builder resume) in either
+    // conformance mode; import-pair growth and boundary-config loosening only add one line to the reviewer prompt.
+    const structureOf = async () => {
+      if (!io.structureDelta) return null;
+      const d = await io.structureDelta({ cwd: wt, base }).catch(() => null);
+      return d && typeof d === "object" && Array.isArray(d.package_edges_added) ? d : null; // `{}`: no workspace packages
+    };
+    let structure = await structureOf();
+    if (structure) {
+      const pairs = structure.import_pairs ?? [], sum = (k) => pairs.reduce((n, p) => n + (Number(p?.[k]) || 0), 0);
+      const rec = { event: "STRUCTURE_DELTA", edges_added: structure.package_edges_added.length, edges_removed: (structure.package_edges_removed ?? []).length,
+        import_files_added: sum("files_added"), import_files_removed: sum("files_removed"), boundary_changed: Boolean(structure.boundary_config_changed?.changed), boundary_loosened: Boolean(structure.boundary_config_changed?.loosens) };
+      ev(rec);
+      await emit({ ...rec, phase: "implement" });
+      const undeclared = () => unnamedEdges(applyAmendments(frozen, result?.amendments, issueText).contract, structure);
+      let edges = undeclared();
+      if (edges.length && sessionId) {
+        T.decisions.push(`Undeclared package edge(s) ${edges.map((e) => `${e.from}→${e.to}`).join(", ")}; builder resumed once`);
+        await builder(++attemptN, structurePrompt(edges, vcfg.mode), sessionId);
+        await upsertStage("implementation");
+        result = (await readResult()) ?? result;
+        structure = (await structureOf()) ?? structure;
+        edges = undeclared();
+      }
+      if (edges.length) {
+        return await needsHuman(`The change adds dependencies between workspace packages that the frozen contract does not name${sessionId ? ", after one builder resume" : ""}; nothing merged:\n${edges.slice(0, 15).map((e) => `- ${e.from} → ${e.to} (${e.kind}, \`${e.manifest}\`)`).join("\n")}\n\nAdd each to the contract with a reason, or remove it.`, OUTCOME_CODES.STRUCTURE_UNDECLARED_EDGE);
+      }
     }
+    const structureLine = structureNote(structure);
 
-    // ---- 4. review (one retry through the same builder session) ----
+    // ---- 3c. verify by CI (#4167): ci|hybrid push the branch and run the repo's CI on GitHub runners, before review ----
+    // A red run resumes the builder with the failed jobs' logs (verify.max_rounds), slow CI ends ci-pending, and CI that
+    // cannot run falls back once to local validation. A head verified here lets the precheck accept validate ids left to CI.
+    let ciVerifiedHead = null, ciFellBack = false, ciRounds = 0;
+    const ciSeenRuns = [];
+    /** Verifies the current head; returns {done} with a terminal result, or {fixes} (builder CI-fix rounds that moved the head). */
+    async function ciVerify(trigger) {
+      let fixes = 0;
+      for (;;) {
+        const head = String(await git(["rev-parse", "HEAD"])).trim();
+        if (head === ciVerifiedHead || ciFellBack) return { fixes };
+        files = await changedFiles();
+        const v = await runCiVerify({ io, branch, head, changedFiles: files, verify: vcfg, ciMaxMinutes, now, sleep, random, exclude: ciSeenRuns,
+          push: () => gitPush(["push", "-u", "origin", branch]),
+          onPoll: async () => { await renew(); onProgress({ event: "phase_paused", phase: "verify", detail: `CI verification pending on ${branch}` }); } });
+        if (v.runId != null) ciSeenRuns.push(v.runId);
+        const rec = { event: "CI_VERIFY", trigger, mode: vcfg.mode, round: ciRounds, result: v.result, skipped: v.result === "skipped", run_url: v.runUrl ?? null, failures: v.failures.map((f) => f.job) };
+        ev(rec); await emit({ ...rec, phase: "verify" });
+        const row = (res) => { T.verify = [res, `mode ${vcfg.mode}, ${ciRounds} fix round(s)${v.runUrl ? `, ${v.runUrl}` : ""}`]; };
+        if (v.result === "pass" || v.result === "skipped") {
+          ciVerifiedHead = head;
+          row(v.result === "pass" ? `CI green at ${head.slice(0, 12)}` : "skipped (docs-only change)");
+          if (v.result === "skipped") T.decisions.push(`CI verification skipped: ${v.detail}`);
+          return { fixes };
+        }
+        if (v.result === "timeout") {
+          row("CI pending");
+          T.anomalies.push("CI verification still pending at the wait budget");
+          return { done: await finish("ci-pending", `CI verification of ${branch} still pending after ${ciMaxMinutes} min; rerun resumes the branch`) };
+        }
+        if (v.result === "unavailable") {
+          ciFellBack = true;
+          row("unavailable: local fallback");
+          T.decisions.push(`CI verification unavailable (${v.detail}); builder runs the validate commands locally`);
+          await builder(++attemptN, ciUnavailablePrompt(), sessionId ?? null);
+          await upsertStage("implementation");
+          result = (await readResult()) ?? result;
+          return { fixes: fixes + 1 };
+        }
+        // fail
+        const jobs = v.failures.map((f) => f.job).join(", ") || "unknown job";
+        row(`CI red (${jobs})`);
+        if (ciRounds >= vcfg.maxRounds || !sessionId) {
+          return { done: await needsHuman(`CI verification failed on \`${branch}\` at \`${head.slice(0, 12)}\` after ${ciRounds} fix round(s); nothing merged:\n${v.failures.slice(0, 10).map((f) => `- ${f.job}${f.url ? ` (${f.url})` : ""}`).join("\n")}`, OUTCOME_CODES.CI_RED) };
+        }
+        ciRounds++; fixes++;
+        T.decisions.push(`CI verification red (${jobs}); builder resumed with the failed logs (round ${ciRounds}/${vcfg.maxRounds})`);
+        await builder(++attemptN, ciFailurePrompt(v.failures, vcfg.mode), sessionId);
+        await upsertStage("implementation");
+        result = (await readResult()) ?? result;
+        if (String(await git(["rev-parse", "HEAD"])).trim() === head) {
+          return { done: await needsHuman(`CI verification failed on \`${branch}\` (${jobs}) and the builder made no new commit for it; nothing merged.`, OUTCOME_CODES.CI_RED) };
+        }
+      }
+    }
+
+    // ---- 4. conformance: typed amendments, deterministic precheck, structured review; the engine computes the verdict ----
+    // enforce: every failure class blocks (one builder resume, then needs-human). shadow: the verdict is computed and posted,
+    // but only what the previous reviewer enforced blocks (a review that finds a requirement not implemented, or a regression),
+    // plus the precheck's equivalent: a failed validate command or a requirement the builder reported as not done (#4160).
     await label("in-review");
-    let review = null;
-    const doReview = async () => {
+    const shadow = conformance !== "enforce";
+    let effective = frozen, review = null, lastAmend = "", resumes = 0, verdict = null;
+    async function amend() {
+      const a = applyAmendments(frozen, result?.amendments, issueText);
+      const sig = JSON.stringify(a.applied);
+      if (a.applied.length && sig !== lastAmend) {
+        lastAmend = sig;
+        await post("FORGE:AMENDMENT", renderAmendments(a.applied));
+        T.decisions.push(`Contract amended: ${a.applied.map((x) => `${x.kind} ${x.target}`).join(", ")}`);
+      }
+      effective = a.contract;
+      return a.problems.map((d) => ({ code: OUTCOME_CODES.CONFORMANCE_UNIMPLEMENTED, detail: d }));
+    }
+    const IGNORE = [`${LEAN_DIR}/`];
+    /** Up to two reviewer runs; a reply without usable rows (unparseable, incomplete, inconsistent) is re-asked, never charged to the builder. */
+    async function reviewOnce() {
+      const diff = String(await git(["diff", `${base}...HEAD`]));
+      const stat = Buffer.byteLength(diff, "utf-8") > REVIEW_DIFF_MAX_BYTES ? String(await git(["diff", "--stat=200", `${base}...HEAD`]).catch(() => "")) : "";
+      const listed = new Set(String(await git(["ls-files"]).catch(() => "")).split("\n").map((x) => x.trim()).filter(Boolean));
+      const ctx = { contract: effective, changedFiles: files, issueText, pathExists: (x) => listed.has(x), ignore: IGNORE };
+      let d = null, retry = null;
+      const skeleton = reviewSkeleton({ contract: effective, changedFiles: files, ignore: IGNORE }); // #4160: every required row, pre-filled
       for (let t = 0; t < 2; t++) {
-        const diff = String(await git(["diff", `${base}...HEAD`]));
-        // #4129: an over-budget diff is bounded in the prompt; the stat keeps every changed file visible.
-        const stat = Buffer.byteLength(diff, "utf-8") > REVIEW_DIFF_MAX_BYTES ? String(await git(["diff", "--stat=200", `${base}...HEAD`]).catch(() => "")) : "";
         await renew();
         const rr = await callRunner({ role: "reviewer", issue, cwd: wt, model: reviewerModel, resume: null, system: REVIEWER_SYSTEM, readOnly: true,
-          prompt: reviewerPrompt({ issue: iss, diff, stat, base }) });
+          prompt: reviewerPrompt({ issue: iss, comments: trustedComments, contract: effective, result, files, diff, stat, base, structure: structureLine, skeleton, retry }) });
         await renew();
         await attempt("review", ++reviewN, rr);
-        const v = parseVerdict(rr?.text);
-        if (v) return v;
+        review = parseReview(rr?.text);
+        d = decide(review, ctx);
+        ev({ event: "CONFORMANCE", round: reviewN, state: d.state, failures: d.failures.map((x) => x.code), mode: shadow ? "shadow" : "enforce" });
+        if (!d.state.startsWith("review.")) return d;
+        // #4160: the second run is told exactly what was missing, instead of getting the same prompt again
+        retry = d.state === "review.incomplete" ? { problems: d.failures.map((x) => x.detail), previous: review ? JSON.stringify(review) : String(rr?.text ?? "") } : null;
       }
-      return null;
-    };
-    review = await doReview();
-    if (!review) return await needsHuman("Reviewer returned no parseable verdict twice.", OUTCOME_CODES.REVIEW_NO_VERDICT);
-    if (review.fail) {
-      if (!sessionId) return await needsHuman(`Review FAIL and the builder session id is unknown, cannot resume: ${review.reason}`, OUTCOME_CODES.REVIEW_FAILED);
-      T.decisions.push(`Review FAIL (round 1): builder resumed with the reason: ${String(review.reason).slice(0, 200)}`);
-      await builder(++attemptN, resumeBuilderPrompt(review.reason), sessionId);
+      return d;
+    }
+    /** Precheck then review, on the current result and changed files (also the base-sync re-review). */
+    async function gate() {
+      await refreshIssue("conformance");
       result = (await readResult()) ?? result;
-      review = await doReview();
-      if (!review) return await needsHuman("Reviewer returned no parseable verdict twice (re-review).", OUTCOME_CODES.REVIEW_NO_VERDICT);
-      if (review.fail) return await needsHuman(`Review FAIL twice. Last reason: ${review.reason}`, OUTCOME_CODES.REVIEW_FAILED);
+      files = await changedFiles();
+      const amendProblems = await amend();
+      const ciVerified = remoteVerify && ciVerifiedHead !== null && ciVerifiedHead === String(await git(["rev-parse", "HEAD"])).trim();
+      const pc = precheck({ contract: effective, result, changedFiles: files, ignore: IGNORE, ciVerified });
+      const pre = [...pc.failures, ...amendProblems];
+      if (pre.length) ev({ event: "PRECHECK", failures: pre.map((f) => f.code) });
+      if (pre.length && !shadow) return { state: "nonconforming", by: "precheck", failures: pre };
+      // shadow: the builder's own failed checks block before any reviewer tokens are spent (#4160)
+      const hard = shadow ? pre.filter((f) => SHADOW_PRE_BLOCKS.includes(f.kind)) : [];
+      if (hard.length) return { state: "nonconforming", by: "precheck", failures: hard };
+      const d = await reviewOnce();
+      if (!shadow) return { ...d, by: "review" };
+      // shadow: record what enforce would have done; block only on what the previous reviewer blocked on
+      const would = d.state === "conforms" && !pre.length ? "conforms" : d.state.startsWith("review.") ? d.state : "nonconforming";
+      const wouldFail = [...pre, ...(d.state === "conforms" ? [] : d.failures)];
+      const blocking = d.state === "nonconforming" ? d.failures.filter((f) => SHADOW_BLOCKS.includes(f.code)) : [];
+      return { state: d.state === "review.unparseable" ? d.state : blocking.length ? "nonconforming" : "conforms", by: "review", failures: blocking, would, wouldFail, reviewState: d.state };
+    }
+    /** Shape the base-sync path expects: null when no usable review, else {fail, verdict, reason, failures}. */
+    const doReview = async () => {
+      const d = await gate();
+      if (d.state.startsWith("review.")) return null;
+      return { fail: d.state !== "conforms", verdict: d.state === "conforms" ? "CONFORMS" : "NONCONFORMING", reason: d.failures.map((f) => `${f.code}: ${f.detail}`).join("; "), failures: d.failures };
+    };
+    for (;;) {
+      if (remoteVerify) { const v = await ciVerify("build"); if (v.done) return v.done; }
+      const outcome = await gate();
+      verdict = outcome;
+      if (outcome.state === "conforms") break;
+      const list = outcome.failures.slice(0, 15).map((f) => `- ${f.code}: ${f.detail}`).join("\n");
+      if (outcome.state === "review.unparseable") return await needsHuman(`The conformance reviewer returned no parseable JSON twice; nothing merged.`, OUTCOME_CODES.REVIEW_NO_VERDICT);
+      if (outcome.state === "review.incomplete") return await needsHuman(`The conformance review was incomplete twice (a review without complete rows cannot pass); nothing merged:\n${list}`, OUTCOME_CODES.REVIEW_INCOMPLETE);
+      if (outcome.state === "review.inconsistent") return await needsHuman(`The conformance reviewer twice said NONCONFORMING without a failing row; nothing merged.`, OUTCOME_CODES.REVIEW_INCONSISTENT);
+      if (resumes >= 1 || !sessionId) return await needsHuman(`The change does not conform to the issue and its frozen contract after ${resumes ? "one builder resume" : "the build (no session to resume)"} (${outcome.by}); nothing merged:\n${list}`, outcome.failures[0].code);
+      resumes++;
+      T.decisions.push(`Not conforming (${outcome.by}${outcome.inconsistent ? ", reviewer verdict contradicted its rows" : ""}): ${[...new Set(outcome.failures.map((f) => f.code))].join(", ")}; builder resumed once`);
+      await builder(++attemptN, conformanceResumePrompt(outcome.failures, vcfg.mode), sessionId);
+      await upsertStage("implementation"); // the published note follows the code after every resume
+    }
+    // Deferrals the reviewer accepted are filed now, before any PR: the batched follow-up must exist and be linked.
+    const toFile = pendingTracking(effective);
+    if (!shadow && toFile.length) await track(toFile, "accepted by the conformance review");
+    if (shadow) {
+      const wf = verdict.wouldFail ?? [];
+      ev({ event: "CONFORMANCE_SHADOW", would: verdict.would, failures: wf.map((f) => f.code) });
+      await emit({ event: "CONFORMANCE_SHADOW", would: verdict.would, failures: wf.map((f) => f.code) });
+      T.review = [`shadow: would ${verdict.would === "conforms" ? "pass" : `block (${verdict.would})`}`, `${reviewN} reviewer run(s), ${resumes + 1} round(s)`];
+      await post("FORGE:REVIEW", renderShadowReview({ would: verdict.would, failures: wf, review: verdict.reviewState === "conforms" || verdict.reviewState === "nonconforming" ? review : null, contract: effective, unfiled: toFile }));
+    } else {
+      T.review = ["CONFORMS", `${reviewN} reviewer run(s), ${resumes + 1} round(s)`];
+      await post("FORGE:REVIEW", renderReview(review, effective));
     }
-    T.review = [review.verdict, `${reviewN} reviewer run(s), ${attemptN > 1 ? "2 rounds" : "1 round"}`];
-    await post("FORGE:REVIEW", renderReview(review));
     ev({ event: "PHASE_COMMIT", phase: "review" });
+    const closing = closePlan(shadow ? { requirements: [] } : effective);
 
     // ---- 5. push + PR ----
-    const files = await changedFiles();
+    files = await changedFiles();
     await gitPush(["push", "-u", "origin", branch]);
     laneGuard(lane, "open a PR");
     const prOut = resumed?.pr ? `/pull/${resumed.pr}` : String(await ghw(["pr", "create", "-R", repo, "--base", lane, "--head", branch,
-      "--title", `${iss.title} (#${issue})`, "--body", renderPrBody({ issue, investigation: await readStage(STAGES[0]), plan: await readStage(STAGES[1]), implementation: await readStage(STAGES[2]), result, gitFiles: files })])).trim();
+      "--title", `${iss.title} (#${issue})`, "--body", renderPrBody({ issue, investigation: await readStage(STAGES[0]), contract: effective, implementation: await readStage(STAGES[1]), result, gitFiles: files, tracked: closing.tracked })])).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 });
+    if (resumed?.pr && closing.tracked.length) { // an existing PR still has to link the tracking issues visibly
+      try { await ghw(["pr", "edit", String(pr), "-R", repo, "--body", renderPrBody({ issue, investigation: await readStage(STAGES[0]), contract: effective, implementation: await readStage(STAGES[1]), result, gitFiles: files, tracked: closing.tracked })]); }
+      catch (e) { e.deferCode = OUTCOME_CODES.FOLLOWUP_UNAVAILABLE; e.deferDetail = `could not link the tracking issues on PR #${pr}; nothing merged, rerun to retry`; throw e; }
+    }
     T.pr = [`#${pr}`, resumed?.pr ? "existing" : "opened"];
     const prUrl = /https?:\/\/\S+/.exec(prOut)?.[0] ?? `https://github.com/${repo}/pull/${pr}`;
     let localHead = String(await git(["rev-parse", "HEAD"])).trim();
@@ -598,6 +1019,13 @@ export async function runCore(o) {
       }
       return "unknown";
     };
+    /** #4158: MERGEABLE but BLOCKED is a base branch policy block (ruleset / required checks pending), not a conflict. */
+    const policyBlocked = async () => {
+      let j;
+      try { j = JSON.parse(String(await ghc(["pr", "view", String(pr), "-R", repo, "--json", "mergeable,mergeStateStatus"])) || "{}"); } catch { return false; }
+      return String(j.mergeable ?? "").toUpperCase() === "MERGEABLE" && String(j.mergeStateStatus ?? "").toUpperCase() === "BLOCKED";
+    };
+    let blockStartedAt = null, blockPollIndex = 0;
     const conflictFiles = async () => (await gitOut(["diff", "--name-only", "--diff-filter=U"])).split("\n").map((x) => x.trim()).filter(Boolean);
     const unresolved = async () => (await conflictFiles()).length > 0 || (await gitOut(["grep", "-n", "-e", "^<<<<<<< ", "-e", "^>>>>>>> "])) !== ""
       || (await gitOut(["diff", "--check"])) !== "" || (await gitOut(["rev-parse", "-q", "--verify", "MERGE_HEAD"])) !== "";
@@ -617,7 +1045,7 @@ export async function runCore(o) {
         how = "clean merge of the base into the branch";
       } else {
         T.decisions.push(`Base-sync ${syncs}: merging ${base} conflicts in ${files.join(", ") || "unknown files"}; builder resolves`);
-        const prompt = `Merging ${base} into this branch conflicts in: ${files.join(", ") || "(see git status)"}. Resolve the conflicts preserving both this fix's intent and the base's changes, run the relevant tests, and commit the merge. Do not push.`;
+        const prompt = `Merging ${base} into this branch conflicts in: ${files.join(", ") || "(see git status)"}. Resolve the conflicts preserving both this fix's intent and the base's changes, ${syncChecks(vcfg.mode)}, and commit the merge. Do not push.`;
         await builder(++attemptN, prompt, sessionId ?? null);
         if (await unresolved()) {
           await gitOut(["merge", "--abort"]);
@@ -630,11 +1058,13 @@ export async function runCore(o) {
       const after = await gitOut(["rev-parse", "HEAD"]);
       if (soft && clean && after === before) { syncs--; return null; } // UNKNOWN state and nothing to merge: not a conflict
       if (after !== before) await gitPush(["push", "origin", branch]); // plain push of a merge commit: never force
-      if (!clean) {
+      let ciFixes = 0;
+      if (remoteVerify && after !== before) { const v = await ciVerify("base-sync"); if (v.done) return v.done; ciFixes = v.fixes; }
+      if (!clean || ciFixes) {
         let rv = await doReview();
         if (rv?.fail) {
           T.decisions.push(`Base-sync re-review FAIL: builder resumed with the reason`);
-          await builder(++attemptN, resumeBuilderPrompt(rv.reason), sessionId ?? null);
+          await builder(++attemptN, conformanceResumePrompt(rv.failures, vcfg.mode), sessionId ?? null);
           if (await unresolved()) return await needsHuman("Base-sync re-review fix left conflict markers.", OUTCOME_CODES.BASE_CONFLICT);
           if ((await gitOut(["rev-parse", "HEAD"])) !== after) await gitPush(["push", "origin", branch]);
           rv = await doReview();
@@ -650,6 +1080,19 @@ export async function runCore(o) {
       return null;
     }
     const NR_TESTS = "not reported";
+    /** After the merge (#4179): delete the lane branch on origin; finish() deletes it locally after the worktree is gone. */
+    async function deleteMergedBranch() {
+      const skip = (why) => { ev({ event: "BRANCH_DELETE_SKIPPED", branch, why }); T.decisions.push(`Lane branch kept: ${why}`); };
+      if (protectedBranch(branch)) return skip("protected branch name");
+      for (const side of ["--head", "--base"]) {
+        let open;
+        try { open = JSON.parse(String(await ghc(["pr", "list", "-R", repo, side, branch, "--state", "open", "--json", "number"])) || "[]"); } catch { return skip("open-PR check failed"); }
+        if (open.length) return skip(`open PR #${open[0].number} uses it as ${side.slice(2)}`);
+      }
+      deleteLocalBranch = true;
+      try { await io.git(["push", "origin", "--delete", branch], { cwd }); ev({ event: "BRANCH_DELETED", branch, where: "origin" }); }
+      catch (e) { ev({ event: "BRANCH_DELETE_FAILED", branch, where: "origin", error: String(e?.stderr ?? e?.message ?? e).slice(0, 300) }); }
+    }
 
     // ---- 7. (sync) wait per policy, (sync) merge at the reviewed head ----
     // A rerun on an existing PR goes through the same conflict check, so a conflicting PR from an earlier run recovers.
@@ -704,11 +1147,31 @@ export async function runCore(o) {
           await sleepFn(Math.min(60000, 1000 * 2 ** (mergeRetries - 1)) + Math.floor(random() * 250));
           continue;
         }
+        if (await policyBlocked()) {
+          // Policy block: wait and retry at the reviewed head; never base-sync, never base.conflict (#4158).
+          if (blockStartedAt === null) {
+            blockStartedAt = now();
+            T.decisions.push("merge blocked by base branch policy (ruleset/required checks); waiting");
+            T.anomalies.push(`gh pr merge blocked by base branch policy: ${msg.split("\n")[0].slice(0, 120)}`);
+          }
+          if (now() - blockStartedAt >= ciMaxMinutes * 60000) {
+            T.merge = [policyText, "blocked by base branch policy"];
+            return await finish("ci-pending", `PR #${pr} blocked by base branch policy after ${ciMaxMinutes} min (checks pending or ruleset requirement unmet)`, { pr });
+          }
+          onProgress({ event: "phase_paused", phase: "merge", detail: `PR #${pr} blocked by base branch policy` });
+          await sleep(ciPollDelayMs(blockPollIndex++, random));
+          await renew();
+          continue;
+        }
         if (!MERGE_CONFLICT_RE.test(msg)) throw e;
         const r = await baseSync("gh pr merge reported a conflict"); if (r) return r;
       }
     }
+    await deleteMergedBranch();
     await ghw(["issue", "close", String(issue), "-R", repo, "--reason", "completed"]).catch(() => {});
+    if (closing.tracked.length) {
+      try { await post("FORGE:TRACKED", `## Remaining work tracked\nClosed as completed by PR #${pr}. The contracted deferred and post-deploy requirements are tracked in ${closing.tracked.join(", ")}.`); } catch { /* the PR body links them too */ }
+    }
     await label("merged");
     return await finish("merged", `PR #${pr}`, { pr });
   } catch (e) {