forgedock 1.24.0 → 1.24.2

package/bin/engine/outcome-codes.mjs

@@ -35,6 +35,7 @@ export const OUTCOME_CODES = Object.freeze({
   CI_TIMEOUT: "ci.timeout",
   BASE_CONFLICT: "base.conflict",
   RATE_LIMITED: "rate_limited",
+  HOST_BUSY: "host.busy",
   ENGINE_ERROR: "engine.error",
   INFRA_DISK_QUOTA: "infra.disk_quota",
   INFRA_CLI_SPAWN_TRANSIENT: "infra.cli_spawn_transient",

package/bin/engine-cli.mjs

@@ -99,6 +99,20 @@ function readLeanSetting(key, cwd = process.cwd()) {
   } catch { return undefined; }
 }
 // core is the default; lean and auto are aliases of core. full is the legacy multi-phase pipeline.
+/**
+ * forge.yaml `engine.admission` (#4105). The parser flattens one nested level into `engine`, so the keys are read as
+ * `engine.enabled|min_free_mem_mb|min_free_tmp_mb|max_load_per_core`, or flat `admission_*` equivalents.
+ */
+export function readAdmission(cwd = process.cwd()) {
+  try {
+    const e = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.engine ?? {};
+    const num = (v) => { const n = Number(v); return v !== undefined && v !== "" && Number.isFinite(n) && n >= 0 ? n : undefined; };
+    const en = String(e.admission_enabled ?? e.enabled ?? "").trim().toLowerCase();
+    return { ...(en === "false" ? { enabled: false } : {}),
+      min_free_mem_mb: num(e.min_free_mem_mb ?? e.admission_min_free_mem_mb), min_free_tmp_mb: num(e.min_free_tmp_mb ?? e.admission_min_free_tmp_mb),
+      max_load_per_core: num(e.max_load_per_core ?? e.admission_max_load_per_core) };
+  } catch { return {}; }
+}
 /** forge.yaml `engine.merge_wait` (required|all|none); undefined when absent or invalid. */
 export function readMergeWait(cwd = process.cwd()) {
   try {
@@ -466,7 +480,8 @@ export async function runFromCli(argv, deps = {}) {
     const leanIo = deps.leanIo ?? (await import("./lean/effects.mjs")).makeLeanIo({ repo: leanRepo });
     const lres = await runCore({ issue, repo: leanRepo, lane, cwd: process.cwd(), dir, io: leanIo, path: enginePath, onProgress,
       emitTelemetry: deps.emitTelemetry ?? makeEmitTelemetry({ repo: leanRepo }),
-      ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) });
+      admission: readAdmission(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) });
+    if (lres.code === "host.busy") { console.log(`issue #${issue} → deferred (${lres.detail})`); return lres; }
     console.log(`issue #${issue} → ${lres.terminalReason}`);
     if (!["merged", "invalid"].includes(lres.terminalReason)) console.log(lres.detail ?? "");
     return lres;
@@ -658,7 +673,7 @@ export async function orchestrateFromCli(argv, deps = {}) {
     issues, parallel,
     readBody: async (n) => JSON.parse(await leanIo.gh(["issue", "view", String(n), "-R", repo, "--json", "body"])).body,
     runOne: (n) => runCore({ issue: n, repo, lane, cwd: process.cwd(), dir, io: leanIo, agentId: `orch_${process.pid}_${n}`, emitTelemetry,
-      ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) }),
+      admission: readAdmission(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) }),
     onUpdate: (r) => console.log(`#${r.issue} → ${r.outcome}${r.detail && r.outcome !== "merged" ? ` (${r.detail})` : ""}`),
   });
   console.log("\n" + formatTable(rows));

package/bin/forgedock.mjs

@@ -3209,6 +3209,7 @@ function help() {
     ["npx forgedock run <cmd> [args]", "Run a command headlessly (local claude CLI or Anthropic API)"],
     ["npx forgedock run-issue <issue> --lane <lane> [--path core|full] [--retry] [--wait-lease]", "Run the lean core work-on on one issue (default; --path full = legacy multi-phase pipeline) (--retry reopens an engine-error run, or a needs-human run once the label is cleared; --wait-lease waits for a held lease; exit 75 = deferred, lease held)"],
     ["npx forgedock orchestrate <issue...> [--parallel K] [--lane L]", "Run core work-on on several issues with bounded concurrency and Depends-on ordering"],
+    ["npx forgedock gc", "Prune stale per-run scratch dirs under ~/.forge/tmp/runs (older than 6h, owner dead)"],
     ["npx forgedock resume-stalled [--dry-run]", "Fleet stall recovery — re-dispatch expired-lease issues"],
     ["npx forgedock demo", "Set up a risk-free demo repo and print next steps"],
     ["npx forgedock labels [setup] [--repo owner/repo]", "Bootstrap ForgeDock-managed labels on a GitHub repo (idempotent)"],
@@ -3782,10 +3783,10 @@ async function watch() {
 // The journey-routed commands render their own branded marks (hero/compact);
 // splash() would double-brand them. Engine-surface commands, help, and
 // unknown-command output keep the logo.
-const SPLASH_COMMANDS = new Set(["run", "run-issue", "orchestrate", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
+const SPLASH_COMMANDS = new Set(["run", "run-issue", "orchestrate", "gc", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
 const KNOWN_COMMANDS = new Set([
   "install", "init", "enable", "disable", "status", "uninstall", "update",
-  "run", "backend-check", "run-issue", "orchestrate", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "help", "--help", "-h",
+  "run", "backend-check", "run-issue", "orchestrate", "gc", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "stats", "help", "--help", "-h",
   "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
@@ -3983,6 +3984,13 @@ switch (command) {
     }
     break;
   }
+  case "gc": {
+    // Best-effort prune of core-run scratch dirs (older than 6h, owner pid dead). Never touches dirs we did not create.
+    const { makeRunTmp } = await import("./lean/effects.mjs");
+    const removed = await makeRunTmp().prune();
+    process.stdout.write(`gc: removed ${removed.length} stale run tmp dir(s)\n`);
+    break;
+  }
   case "orchestrate": {
     const { orchestrateFromCli } = await import("./engine-cli.mjs");
     try {

package/bin/lean/admission.mjs

@@ -0,0 +1,32 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Host-resource admission for the core work-on (#4105): refuse to start a run when the host is out of headroom, so a
+ * batch of lanes does not push the machine into OOM or a full /tmp. Every probe is injected through `host`.
+ */
+export const ADMISSION_DEFAULTS = Object.freeze({ enabled: true, min_free_mem_mb: 2048, min_free_tmp_mb: 1024, max_load_per_core: 4 });
+export const ADMISSION_RETRY_SECONDS = 60;
+
+const gb = (mb) => { const g = mb / 1024; return `${Number.isInteger(g) ? g : g.toFixed(1)}G`; };
+
+/**
+ * @param {{cfg?: object, host: {memAvailableMb?: Function, freeMb?: Function, loadAvg1?: Function, cores?: Function, tmpPaths?: Function}}} p
+ * @returns {Promise<{ok: boolean, reasons: string[], detail: string}>}
+ */
+export async function checkAdmission({ cfg = {}, host }) {
+  const c = { ...ADMISSION_DEFAULTS, ...Object.fromEntries(Object.entries(cfg ?? {}).filter(([, v]) => v !== undefined && v !== null)) };
+  if (c.enabled === false || !host) return { ok: true, reasons: [], detail: "" };
+  const reasons = [];
+  const safe = async (fn, ...a) => { try { const v = await fn?.(...a); return Number.isFinite(v) ? v : null; } catch { return null; } };
+  const mem = await safe(host.memAvailableMb);
+  if (mem !== null && mem < c.min_free_mem_mb) reasons.push(`mem ${gb(mem)} < ${gb(c.min_free_mem_mb)}`);
+  let paths = [];
+  try { paths = (await host.tmpPaths?.()) ?? []; } catch { paths = []; }
+  for (const p of paths) {
+    const free = await safe(host.freeMb, p);
+    if (free !== null && free < c.min_free_tmp_mb) reasons.push(`tmp ${p} ${gb(free)} < ${gb(c.min_free_tmp_mb)}`);
+  }
+  const load = await safe(host.loadAvg1), cores = await safe(host.cores);
+  if (load !== null && cores && load / cores > c.max_load_per_core) reasons.push(`load ${(load / cores).toFixed(1)}/core > ${c.max_load_per_core}`);
+  return { ok: reasons.length === 0, reasons, detail: reasons.length ? `host busy: ${reasons.join(", ")}; retry in ${ADMISSION_RETRY_SECONDS}s` : "" };
+}

package/bin/lean/effects.mjs

@@ -3,8 +3,10 @@
 /** Core work-on: the real effects behind runCore's injected `io`. Argv only, no shell. */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { readFileSync, appendFileSync, mkdirSync, statSync } from "node:fs";
-import { dirname } from "node:path";
+import { readFileSync, appendFileSync, mkdirSync, statSync, existsSync, rmSync, writeFileSync, readdirSync, lstatSync } from "node:fs";
+import { homedir, hostname, freemem, loadavg, cpus, tmpdir } from "node:os";
+import { promises as fsp } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runCliBackendAsync, resolveClaudeCliBinary, getClaudeCliCapabilities, buildLeanSessionFlags, buildReadOnlyToolFlags } from "../runner.mjs";
 import { makeIo } from "../engine-cli.mjs";
@@ -15,22 +17,87 @@ const script = (n) => fileURLToPath(new URL(`../../scripts/${n}`, import.meta.ur
 
 /** Claude CLI session runner: fresh session, or `--resume <id>` for the builder. Resolves usage + session_id. */
 export function makeLeanRunner({ runCli = runCliBackendAsync } = {}) {
-  return async ({ role, issue, cwd, model, resume, system, prompt, readOnly = false }) => {
+  return async ({ role, issue, cwd, model, resume, system, prompt, readOnly = false, env = null }) => {
     const bin = resolveClaudeCliBinary(cwd) || "claude";
     const caps = getClaudeCliCapabilities(cwd);
     const flags = [...buildLeanSessionFlags(caps), ...(readOnly ? buildReadOnlyToolFlags(caps) : [])];
     const r = await runCli({ spec: { name: `core-${role}` }, userMessage: prompt, systemPrompt: resume ? "" : system,
-      args: [String(issue)], cwd, bin, model, sessionFlags: flags, extraArgs: resume ? ["--resume", resume] : [],
+      args: [String(issue)], cwd, bin, model, env, sessionFlags: flags, extraArgs: resume ? ["--resume", resume] : [],
       logger: { log() {} } });
     return { text: r.text, sessionId: r.sessionId, usage: r.usage, costUsd: r.costUsd, durationMs: r.durationMs, turns: r.turns, model: r.cliModel ?? "default" };
   };
 }
 
+export const RUN_TMP_MAX_AGE_MS = 6 * 3600 * 1000;
+export const runTmpRoot = () => join(homedir(), ".forge", "tmp", "runs");
+const OWNER = ".forge-run-owner";
+const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e?.code !== "ESRCH"; } };
+
+/** Per-run scratch dirs under ~/.forge/tmp/runs/<issue>-<run>/. Only dirs carrying our owner marker are ever removed. */
+export function makeRunTmp({ root = runTmpRoot(), now = () => Date.now(), alive = pidAlive, host = hostname() } = {}) {
+  const inside = (d) => { const r = resolve(d); return r.startsWith(resolve(root) + sep) && !r.slice(resolve(root).length + 1).includes(sep); };
+  return {
+    async make(issue, runId) {
+      const dir = join(root, String(runId));
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      writeFileSync(join(dir, OWNER), JSON.stringify({ issue, pid: process.pid, host, created: now() }));
+      return dir;
+    },
+    /** Remove a dir this module created (marker present, direct child of the runs root). */
+    async remove(dir) {
+      if (!dir || !inside(dir) || !existsSync(join(dir, OWNER))) return false;
+      rmSync(dir, { recursive: true, force: true });
+      return true;
+    },
+    /** Best-effort: dirs older than 6h whose owner pid is dead on this host. Never touches dirs without our marker. */
+    async prune({ maxAgeMs = RUN_TMP_MAX_AGE_MS } = {}) {
+      const removed = [];
+      let names = [];
+      try { names = readdirSync(root); } catch { return removed; }
+      for (const n of names) {
+        const dir = join(root, n);
+        try {
+          if (!lstatSync(dir).isDirectory()) continue;
+          const own = JSON.parse(readFileSync(join(dir, OWNER), "utf8"));
+          if (now() - Number(own.created) < maxAgeMs) continue;
+          if (own.host === host && Number.isSafeInteger(own.pid) && alive(own.pid)) continue;
+          if (own.host !== host) continue;
+          rmSync(dir, { recursive: true, force: true });
+          removed.push(n);
+        } catch { /* not ours or unreadable: leave it */ }
+      }
+      return removed;
+    },
+  };
+}
+
+/** Real host probes for admission (#4105). MemAvailable from /proc/meminfo (fallback os.freemem), statfs for tmp. */
+export function makeHostProbe() {
+  return {
+    memAvailableMb() {
+      try {
+        const m = /^MemAvailable:\s+(\d+)\s+kB/m.exec(readFileSync("/proc/meminfo", "utf8"));
+        if (m) return Math.floor(Number(m[1]) / 1024);
+      } catch { /* not Linux */ }
+      return Math.floor(freemem() / 1048576);
+    },
+    async freeMb(p) {
+      let dir = p;
+      while (dir && !existsSync(dir) && dirname(dir) !== dir) dir = dirname(dir);
+      const s = await fsp.statfs(dir);
+      return Math.floor((Number(s.bavail) * Number(s.bsize)) / 1048576);
+    },
+    loadAvg1: () => loadavg()[0],
+    cores: () => cpus().length || 1,
+    tmpPaths: () => [...new Set([join(homedir(), ".forge", "tmp"), tmpdir(), "/tmp"].filter((x) => existsSync(x) || x === join(homedir(), ".forge", "tmp")))],
+  };
+}
+
 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,
+    gh: run("gh"), git: run("git"), runTmp: makeRunTmp(), host: makeHostProbe(), projector: makeProjector({ gh: base.gh }), runner: makeLeanRunner(), waitCiGreen: base.waitCiGreen,
     /** Names of the checks the base branch requires (contexts + checks). [] on 404 / no protection. */
     async requiredChecks(lane) {
       try {
@@ -50,6 +117,8 @@ export function makeLeanIo({ repo }) {
     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"),
+      exists: async (p) => existsSync(p),
+      rmdir: async (p) => rmSync(p, { recursive: true, force: true }),
       stat: async (p) => { try { return { mtimeMs: statSync(p).mtimeMs }; } catch { return null; } },
       append: async (p, t) => { mkdirSync(dirname(p), { recursive: true }); appendFileSync(p, t); },
     },

package/bin/lean/lean.mjs

@@ -5,11 +5,13 @@
  * ForgeDock registers everything on GitHub (labels, one register comment, PR, merge). No investigation, synthesis,
  * severity taxonomy, risk tiers or local CI gates. All effects are injected through `io` so it is unit-testable.
  */
-import { join } from "node:path";
+import { join, dirname, basename } from "node:path";
+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 } from "../engine.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 { checkAdmission, ADMISSION_RETRY_SECONDS } from "./admission.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, parseVerdict } from "./prompts.mjs";
 
@@ -31,7 +33,7 @@ const num = (v) => (Number.isFinite(v) ? v : null);
  */
 export async function runCore(o) {
   const { issue, repo, lane, cwd, dir, io, builderModel = null, reviewerModel = DEFAULT_REVIEWER_MODEL,
-    ciMaxMinutes = 360, mergeWait = "required", onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
+    ciMaxMinutes = 360, mergeWait = "required", maxSessionLimitPauses = DEFAULT_MAX_SESSION_LIMIT_PAUSES, sessionLimitMaxWaitMs = DEFAULT_SESSION_LIMIT_WAIT_MS, 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}`;
@@ -65,10 +67,19 @@ export async function runCore(o) {
 
   // ---- lease (same FORGE:STATE lease the full path uses) ----
   const agentId = o.agentId ?? `core_${process.pid}`;
+  const myHost = o.hostName ?? osHostname();
+  const leaseObj = () => ({ by: agentId, until: now() + leaseTtlMs, host: myHost, pid: o.pid ?? process.pid });
+  /** Provably dead: same host and `kill(pid, 0)` throws ESRCH. A different host keeps the TTL behaviour. */
+  const holderDead = (l) => {
+    const parsed = parseLeaseHolder(l?.by);
+    const h = l?.host ?? parsed?.host, pid = l?.pid ?? parsed?.pid;
+    if (!h || !Number.isSafeInteger(pid) || pid <= 0 || sanitizeLeaseHost(h) !== sanitizeLeaseHost(myHost)) return false;
+    try { (o.killFn ?? process.kill.bind(process))(pid, 0); return false; } catch (e) { return e?.code === "ESRCH"; }
+  };
   const leaseTtlMs = o.leaseTtlMs ?? 25 * 60000; // below the projector's 30 min honour cap
   let leaseState = null, leaseTimer = null;
   const writeLease = (lease, extra = {}) => io.projector.writeState(issue, { ...leaseState, ...extra, lease });
-  const renew = async () => { if (io.projector && leaseState) { try { await writeLease({ by: agentId, until: now() + leaseTtlMs }); } catch { /* best effort */ } } };
+  const renew = async () => { if (io.projector && leaseState) { try { await writeLease(leaseObj()); } catch { /* best effort */ } } };
   async function releaseLease(reason) {
     if (leaseTimer) { clearInterval(leaseTimer); leaseTimer = null; }
     if (!io.projector || !leaseState) return;
@@ -79,6 +90,8 @@ 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;
+  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
     const code = codeOverride ?? codeForTerminalReason(reason);
@@ -95,6 +108,7 @@ 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 */ } }
@@ -158,10 +172,28 @@ export async function runCore(o) {
     }
   }
 
+  /** Runner call with the per-run TMPDIR; a usage limit pauses and resumes the same step, or defers past the cap (#4101). */
+  async function callRunner(args) {
+    let pauses = 0;
+    for (;;) {
+      try { return await io.runner({ ...args, ...(runTmp ? { env: { 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;
+        const waitMs = epoch !== null && epoch > now() ? epoch - now() : DEFAULT_SESSION_LIMIT_WAIT_MS;
+        if (pauses >= maxSessionLimitPauses || waitMs > sessionLimitMaxWaitMs) { e.deferUsageLimit = true; throw e; }
+        pauses++;
+        ev({ event: "PHASE_RATE_LIMITED", phase: args.role, resetAt: epoch, resetAtDisplay: e.resetAt ?? null, waitMs });
+        onProgress({ event: "phase_paused", phase: args.role, reason: "session-limit", detail: `session limit hit; pausing until ${e.resetAt || new Date(now() + waitMs).toISOString()}` });
+        await sleep(waitMs);
+      }
+    }
+  }
+
   async function builder(n, prompt, resume, live = false) {
     onProgress({ event: "phase_enter", phase: "build" });
     await renew();
-    const call = Promise.resolve(io.runner({ role: "builder", issue, cwd: wt, model: builderModel, resume, system: "", prompt }));
+    const call = Promise.resolve(callRunner({ role: "builder", issue, cwd: wt, model: builderModel, resume, system: "", prompt }));
     let r;
     if (live && io.fs.stat) {
       let settled = false;
@@ -183,6 +215,11 @@ export async function runCore(o) {
   }
   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; } };
 
+  // ---- host admission (#4105): before the lease, the worktree or any GitHub call ----
+  if (io.host && o.admission?.enabled !== false) {
+    const a = await checkAdmission({ cfg: o.admission, host: io.host });
+    if (!a.ok) return { terminalReason: "deferred", code: OUTCOME_CODES.HOST_BUSY, detail: a.detail, retryInSeconds: ADMISSION_RETRY_SECONDS };
+  }
   // ---- admission: Depends-on refusal, then lease ----
   {
     let dep = null;
@@ -196,15 +233,22 @@ export async function runCore(o) {
   if (io.projector) {
     let st = null;
     try { st = await io.projector.readState(issue); } catch { /* unreadable: proceed */ }
-    if (st?.lease && st.lease.until > now() && st.lease.by !== agentId) {
+    if (st?.lease && st.lease.until > now() && st.lease.by !== agentId && holderDead(st.lease)) {
+      ev({ event: "LEASE_TAKEOVER", from: st.lease.by, host: st.lease.host ?? null, pid: st.lease.pid ?? null });
+      onProgress({ event: "lease_takeover", detail: `taking over the lease of dead holder ${st.lease.by} (pid ${st.lease.pid ?? "?"} gone)` });
+    } else if (st?.lease && st.lease.until > now() && st.lease.by !== agentId) {
       return { terminalReason: "deferred", code: "lease-held", detail: `issue ${issue} leased by ${st.lease.by} until ${new Date(st.lease.until).toISOString()}`, branch, worktree: wt };
     }
     leaseState = { ...(st ?? { v: 1, run: `core_${issue}`, issue, lane, committed: [], phase: null, branch: null, pr: null, terminalReason: null }), terminal: false };
-    try { await writeLease({ by: agentId, until: now() + leaseTtlMs }); } catch { /* best effort */ }
-    leaseTimer = setInterval(() => { writeLease({ by: agentId, until: now() + leaseTtlMs }).catch(() => {}); }, o.leaseRenewMs ?? 120000);
+    try { await writeLease(leaseObj()); } catch { /* best effort */ }
+    leaseTimer = setInterval(() => { writeLease(leaseObj()).catch(() => {}); }, o.leaseRenewMs ?? 120000);
     leaseTimer.unref?.();
   }
 
+  if (io.runTmp) {
+    try { await io.runTmp.prune?.(); } catch { /* best effort */ }
+    try { runTmp = await io.runTmp.make(issue, runId); } catch { runTmp = null; }
+  }
   ev({ event: "RUN_START", run: `core_${issue}_${t0}`, issue, lane, path: "core", version: ENGINE_VERSION, forge_version: ENGINE_VERSION, repo });
   let iss;
   try {
@@ -227,11 +271,36 @@ export async function runCore(o) {
     } 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 */ }
+    // Concurrent lanes in one repo race on .git/config.lock / index.lock during `worktree add`; retry with jitter.
+    // A leftover dir that git no longer lists as a worktree blocks `worktree add`. Remove ONLY this issue's lean dir under the lean root.
+    const wtRoot = o.worktreeRoot ?? join(cwd, ".claude", "worktrees");
+    const leftoverDir = async () => {
+      if (!io.fs.exists || !io.fs.rmdir || dirname(wt) !== wtRoot || basename(wt) !== `lean-${issue}`) return false;
+      if (!(await io.fs.exists(wt))) return false;
+      const listed = String(await io.git(["worktree", "list", "--porcelain"], { cwd }).catch(() => "")).split("\n").some((l) => l === `worktree ${wt}`);
+      if (listed) return false;
+      await io.fs.rmdir(wt);
+      ev({ event: "WORKTREE_LEFTOVER_REMOVED", path: wt });
+      return true;
+    };
+    await leftoverDir();
+    const LOCK_RE = /could not lock|cannot lock ref|\.lock'?: File exists|Unable to create .*\.lock|index\.lock|packed-refs\.lock/i;
+    const addWorktree = async (args) => {
+      let cleaned = false;
+      for (let i = 0; ; i++) {
+        try { return await io.git(args, { cwd }); } catch (e) {
+          const msg = String(e?.stderr ?? e?.message ?? e);
+          if (!cleaned && /already exists/i.test(msg) && (await leftoverDir())) { cleaned = true; continue; }
+          if (i >= 4 || !LOCK_RE.test(msg)) throw e;
+          await sleep(500 * (i + 1) + Math.floor(random() * 500));
+        }
+      }
+    };
     if (resumed) {
       await io.git(["fetch", "origin", branch], { cwd });
-      await io.git(["worktree", "add", "-B", branch, wt, `origin/${branch}`], { cwd });
+      await addWorktree(["worktree", "add", "-B", branch, wt, `origin/${branch}`]);
     } else {
-      await io.git(["worktree", "add", "-B", branch, wt, base], { cwd });
+      await addWorktree(["worktree", "add", "-B", branch, wt, base]);
     }
     wtCreated = true;
     const excl = String(await git(["rev-parse", "--git-path", "info/exclude"])).trim();
@@ -273,7 +342,7 @@ export async function runCore(o) {
       for (let t = 0; t < 2; t++) {
         const diff = String(await git(["diff", `${base}...HEAD`]));
         await renew();
-        const rr = await io.runner({ role: "reviewer", issue, cwd: wt, model: reviewerModel, resume: null, system: REVIEWER_SYSTEM, readOnly: true,
+        const rr = await callRunner({ role: "reviewer", issue, cwd: wt, model: reviewerModel, resume: null, system: REVIEWER_SYSTEM, readOnly: true,
           prompt: reviewerPrompt({ issue: iss, diff }) });
         await renew();
         await attempt("review", ++reviewN, rr);
@@ -307,10 +376,9 @@ export async function runCore(o) {
     ev({ event: "PR_OPENED", pr });
     T.pr = [`#${pr}`, resumed?.pr ? "existing" : "opened"];
     const prUrl = /https?:\/\/\S+/.exec(prOut)?.[0] ?? `https://github.com/${repo}/pull/${pr}`;
-    const localHead = String(await git(["rev-parse", "HEAD"])).trim();
+    let localHead = String(await git(["rev-parse", "HEAD"])).trim();
 
-    // ---- 6. the register comment ----
-    // merge policy: required (default) | all | none
+    // ---- 6. merge policy: required (default) | all | none ----
     let policy = mergeWait, required = [];
     if (mergeWait === "required") {
       try { required = (await io.requiredChecks?.(lane)) ?? []; } catch { required = []; }
@@ -319,46 +387,131 @@ export async function runCore(o) {
     T.merge = [policyText, "waiting"];
     T.decisions.push(`merge_wait=${mergeWait}: ${policyText}`);
 
-    // ---- 7. wait per policy, merge at the reviewed head ----
-    if (policy === "none" || (policy === "required" && !required.length)) {
-      // merge right after review
-      T.merge = [policyText, "merged right after review"];
-    } else {
-      const startedAt = now();
-      let pollIndex = 0, gateHead = null;
-      for (;;) {
-        await renew();
-        if (policy === "all") {
-          const w = await io.waitCiGreen(pr, repo, 0).catch(() => ({ rc: 2, text: "" }));
-          if (w.rc === 0) { gateHead = /CI_GATE_HEAD:\s*([0-9a-f]{7,40})/.exec(w.text ?? "")?.[1] ?? null; break; }
-          if (w.rc === 1) return await needsHuman(`Remote CI failed on PR #${pr}:\n${String(w.text).slice(-2000)}`, OUTCOME_CODES.CI_RED);
-        } else {
-          let states = [];
-          try { states = (await io.checkStates(pr)) ?? []; } catch { states = []; }
-          const st = (n) => states.find((x) => x.name === n)?.state ?? "pending";
-          const failed = required.filter((n) => st(n) === "failure");
-          if (failed.length) return await needsHuman(`Required check(s) failed on PR #${pr}: ${failed.join(", ")}`, OUTCOME_CODES.CI_RED);
-          if (required.every((n) => st(n) === "success")) break;
+    // ---- base-sync (#4100): merge the lane into the branch when the PR conflicts; merge only, never rebase or force-push ----
+    let syncs = 0;
+    const MAX_SYNCS = 2;
+    const gitOut = async (args) => { try { return String(await git(args)).trim(); } catch { return ""; } };
+    /** CONFLICTING / DIRTY, or UNKNOWN after one short re-poll. Unreadable state counts as not conflicting. */
+    const prConflicting = async () => {
+      for (let i = 0; i < 2; i++) {
+        let j;
+        try { j = JSON.parse(String(await ghc(["pr", "view", String(pr), "-R", repo, "--json", "mergeable,mergeStateStatus"])) || "{}"); } catch { return false; }
+        const m = String(j.mergeable ?? "").toUpperCase(), st = String(j.mergeStateStatus ?? "").toUpperCase();
+        if (m === "CONFLICTING" || st === "DIRTY") return "conflict";
+        if (m !== "UNKNOWN") return false;
+        if (i === 0) await sleep(2000);
+      }
+      return "unknown";
+    };
+    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"])) !== "";
+    const syncRow = [];
+    /** Returns null to continue with the merge flow, or a terminal result. */
+    async function baseSync(trigger, soft = false) {
+      if (syncs >= MAX_SYNCS) return await needsHuman(`PR #${pr} still conflicts with ${lane} after ${MAX_SYNCS} base-syncs (${trigger}).`, OUTCOME_CODES.BASE_CONFLICT);
+      syncs++;
+      await renew();
+      try { await git(["fetch", "origin", lane]); } catch { /* offline: use the local ref */ }
+      const baseSha = (await gitOut(["rev-parse", base])).slice(0, 12);
+      const before = await gitOut(["rev-parse", "HEAD"]);
+      let clean = true, files = [];
+      try { await git(["merge", "--no-edit", base]); } catch { clean = false; files = await conflictFiles(); }
+      let how, tests = "not required (clean merge)", rereview = "not required (conflict-free base merge)";
+      if (clean) {
+        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.`;
+        await builder(++attemptN, prompt, sessionId ?? null);
+        if (await unresolved()) {
+          await gitOut(["merge", "--abort"]);
+          return await needsHuman(`Base-sync could not resolve the conflicts in ${files.join(", ")} (conflict markers or an unfinished merge remain).`, OUTCOME_CODES.BASE_CONFLICT);
         }
-        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" });
-          T.anomalies.push("CI still pending at the wait budget");
-          return await finish("ci-pending", `PR #${pr} still waiting on CI after ${ciMaxMinutes} min`, { pr });
+        how = `builder resolved ${files.length} conflicted file(s) and committed the merge`;
+        const r2 = await readResult();
+        tests = Array.isArray(r2?.tests) && r2.tests.length ? r2.tests.map((t) => (typeof t === "string" ? t : `${t.command}: ${t.result}`)).join("; ") : NR_TESTS;
+      }
+      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 git(["push", "origin", branch]); // plain push of a merge commit: never force
+      if (!clean) {
+        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);
+          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 git(["push", "origin", branch]);
+          rv = await doReview();
         }
-        onProgress({ event: "phase_paused", phase: "merge", detail: `CI pending on PR #${pr}` });
-        await sleep(ciPollDelayMs(pollIndex++, random));
+        if (!rv) return await needsHuman("Reviewer returned no parseable verdict after base-sync.", OUTCOME_CODES.REVIEW_NO_VERDICT);
+        if (rv.fail) return await needsHuman(`Review FAIL after base-sync: ${rv.reason}`, OUTCOME_CODES.REVIEW_FAILED);
+        rereview = `${rv.verdict}: ${rv.reason || "no concrete failure"}`;
       }
-      if (gateHead && !(localHead.startsWith(gateHead) || gateHead.startsWith(localHead))) {
-        return await needsHuman(`CI passed for ${gateHead.slice(0, 12)} but the reviewed head is ${localHead.slice(0, 12)}; refusing to merge an unreviewed head.`, OUTCOME_CODES.MERGE_HEAD_MISMATCH);
+      localHead = await gitOut(["rev-parse", "HEAD"]);
+      syncRow.push(`${trigger}: ${clean ? "clean" : "conflicts"} (${baseSha})`);
+      T.baseSync = [`${syncs} sync(s)`, syncRow.join("; ")];
+      await post("FORGE:BASE_SYNC", `## Base Sync\n**Trigger:** ${trigger}\n**Base merged:** \`${base}\` at \`${baseSha}\`\n**Result:** ${clean ? "clean merge" : `conflicts in ${files.map((f) => `\`${f}\``).join(", ") || "unknown files"}`}\n**Resolution:** ${how}\n**Tests run:** ${tests}\n**Re-review:** ${rereview}\n**New head:** \`${localHead.slice(0, 12)}\``);
+      return null;
+    }
+    const NR_TESTS = "not reported";
+
+    // ---- 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.
+    for (;;) {
+      const c0 = await prConflicting();
+      if (c0) { const r = await baseSync(c0 === "unknown" ? "PR mergeability unknown" : "PR is conflicting", c0 === "unknown"); if (r) return r; }
+      if (policy === "none" || (policy === "required" && !required.length)) {
+        // merge right after review
+        T.merge = [policyText, "merged right after review"];
+      } else {
+        const startedAt = now();
+        let pollIndex = 0, gateHead = null;
+        for (;;) {
+          await renew();
+          if (policy === "all") {
+            const w = await io.waitCiGreen(pr, repo, 0).catch(() => ({ rc: 2, text: "" }));
+            if (w.rc === 0) { gateHead = /CI_GATE_HEAD:\s*([0-9a-f]{7,40})/.exec(w.text ?? "")?.[1] ?? null; break; }
+            if (w.rc === 1) return await needsHuman(`Remote CI failed on PR #${pr}:\n${String(w.text).slice(-2000)}`, OUTCOME_CODES.CI_RED);
+          } else {
+            let states = [];
+            try { states = (await io.checkStates(pr)) ?? []; } catch { states = []; }
+            const st = (n) => states.find((x) => x.name === n)?.state ?? "pending";
+            const failed = required.filter((n) => st(n) === "failure");
+            if (failed.length) return await needsHuman(`Required check(s) failed on PR #${pr}: ${failed.join(", ")}`, OUTCOME_CODES.CI_RED);
+            if (required.every((n) => st(n) === "success")) break;
+          }
+          if (now() - startedAt >= ciMaxMinutes * 60000) {
+            // Slow CI is never a needs-human: leave the PR open and resumable.
+            ev({ event: "CI_PENDING_WAIT", state: "end", pr, result: "timeout" });
+            T.anomalies.push("CI still pending at the wait budget");
+            return await finish("ci-pending", `PR #${pr} still waiting on CI after ${ciMaxMinutes} min`, { pr });
+          }
+          onProgress({ event: "phase_paused", phase: "merge", detail: `CI pending on PR #${pr}` });
+          await sleep(ciPollDelayMs(pollIndex++, random));
+        }
+        if (gateHead && !(localHead.startsWith(gateHead) || gateHead.startsWith(localHead))) {
+          return await needsHuman(`CI passed for ${gateHead.slice(0, 12)} but the reviewed head is ${localHead.slice(0, 12)}; refusing to merge an unreviewed head.`, OUTCOME_CODES.MERGE_HEAD_MISMATCH);
+        }
+      }
+      if (syncs > 0 && (await prConflicting()) === "conflict") continue; // the base moved again while waiting
+      T.merge = [policyText, `merged at ${localHead.slice(0, 12)}`];
+      try {
+        await ghc(["pr", "merge", String(pr), "-R", repo, "--merge", "--match-head-commit", localHead]);
+        break;
+      } catch (e) {
+        if (!/not mergeable|merge conflict|conflict/i.test(String(e?.stderr ?? "") + String(e?.message ?? ""))) throw e;
+        const r = await baseSync("gh pr merge reported a conflict"); if (r) return r;
       }
     }
-    T.merge = [policyText, `merged at ${localHead.slice(0, 12)}`];
-    await ghc(["pr", "merge", String(pr), "-R", repo, "--merge", "--match-head-commit", localHead]);
     await ghc(["issue", "close", String(issue), "-R", repo, "--reason", "completed"]).catch(() => {});
     await label("merged");
     return await finish("merged", `PR #${pr}`, { pr });
   } catch (e) {
+    if (e?.deferUsageLimit) {
+      const when = e.resetAt || (Number.isFinite(e.resetAtEpochMs) ? new Date(e.resetAtEpochMs).toISOString() : "unknown");
+      return finish("deferred", `usage limit hit; resets at ${when}`, { code: OUTCOME_CODES.RATE_LIMITED, resetAt: when, resetAtEpochMs: Number.isFinite(e.resetAtEpochMs) ? e.resetAtEpochMs : null }, OUTCOME_CODES.RATE_LIMITED);
+    }
     return finish("engine-error", e?.message ?? String(e));
   }
 }

package/bin/lean/lean.test.mjs

@@ -9,6 +9,10 @@ import { orchestrate, parseDeps, formatTable } from "./orchestrate.mjs";
 import { REVIEWER_SYSTEM, approxTokens, builderPrompt, reviewerPrompt, parseVerdict } from "./prompts.mjs";
 import { mapRecord } from "../engine/telemetry-seam.mjs";
 import { readLog } from "../engine/runlog.mjs";
+import { makeRunTmp } from "./effects.mjs";
+import { checkAdmission } from "./admission.mjs";
+import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
+import { readAdmission } from "../engine-cli.mjs";
 import { runFromCli, orchestrateFromCli, ENGINE_PATHS } from "../engine-cli.mjs";
 
 const WT = "/wt/lean-7";
@@ -26,7 +30,7 @@ function world(o = {}) {
     comments: [], labels: [], closed: [], edits: [], prs: [], merges: [], calls: [], telemetry: [], files: {}, head: "aaaa1111aaaa1111",
     changed: o.changed ?? ["src/foo.js", "test/foo.test.js"], reviews: [...(o.reviews ?? [])], waits: [...(o.waits ?? [])], clock: 0,
     result: o.result ?? { status: "fixed", summary: "fixed foo", evidence: [], tests: ["test/foo.test.js"] },
-    prList: o.prList ?? [], remote: o.remote ?? "", resumeResult: o.resumeResult, seq: [], mtimes: {},
+    prList: o.prList ?? [], remote: o.remote ?? "", resumeResult: o.resumeResult, seq: [], mtimes: {}, envs: [], prView: [...(o.prView ?? [])], mergeResults: [...(o.mergeResults ?? [])], mergeErrors: [...(o.mergeErrors ?? [])], conflictFiles: [], mergeInProgress: false, markers: false, mergeAttempts: 0,
     stages: { ...STAGE_MD, ...(o.stages ?? {}) },
   };
   const put = (name, text) => { const p = `${WT}/.forge-lean/${name}`; if (w.files[p] !== text) w.mtimes[p] = Date.now(); w.files[p] = text; };
@@ -43,12 +47,28 @@ function world(o = {}) {
       if (k === "issue close") { w.closed.push(a); w.seq.push("close"); return ""; }
       if (k === "issue edit") { w.edits.push(a); return ""; }
       if (k === "pr create") { w.prs.push(a); w.seq.push("pr"); return "https://github.com/o/r/pull/77\n"; }
+      if (k === "pr view" && a.includes("mergeable,mergeStateStatus")) { const v = w.prView.length > 1 ? w.prView.shift() : (w.prView[0] ?? { mergeable: "MERGEABLE", mergeStateStatus: "CLEAN" }); return JSON.stringify(v); }
+      if (k === "pr merge" && w.mergeErrors.length) { w.mergeAttempts++; throw new Error(w.mergeErrors.shift()); }
+      if (k === "pr merge") { w.mergeAttempts++; }
       if (k === "pr merge") { w.merges.push(a); w.seq.push("merge"); return ""; }
       throw new Error(`unexpected gh ${a.join(" ")}`);
     },
     git: async (a) => {
       w.calls.push(["git", ...a]);
+      if (a[0] === "worktree" && a[1] === "add" && (w.lockFails ?? 0) > 0) {
+        w.lockFails--; const e = new Error("git failed"); e.stderr = "error: could not lock config file .git/config: File exists"; throw e;
+      }
       if (a[0] === "rev-parse" && a[1] === "--git-path") return "/repo/.git/info/exclude";
+      if (a[0] === "merge" && a[1] === "--no-edit") {
+        const r = w.mergeResults.shift() ?? "clean";
+        if (r === "clean") { w.head = `cccc${w.calls.length}`.padEnd(16, "0"); return ""; }
+        w.conflictFiles = o.conflictFiles ?? ["src/foo.js"]; w.mergeInProgress = true; throw new Error("CONFLICT (content): Merge conflict in src/foo.js");
+      }
+      if (a[0] === "rev-parse" && a.includes("MERGE_HEAD")) return w.mergeInProgress ? "deadbeef" : "";
+      if (a[0] === "diff" && a.includes("--diff-filter=U")) return w.conflictFiles.join("\n");
+      if (a[0] === "diff" && a[1] === "--check") return "";
+      if (a[0] === "grep") return w.markers ? "src/foo.js:3:<<<<<<< HEAD" : "";
+      if (a[0] === "merge" && a[1] === "--abort") { w.mergeInProgress = false; return ""; }
       if (a[0] === "rev-parse") return w.head;
       if (a[0] === "diff" && a[1] === "--name-only") return w.changed.join("\n");
       if (a[0] === "diff") return "diff --git a/src/foo.js b/src/foo.js\n+fix";
@@ -59,12 +79,13 @@ function world(o = {}) {
     runner: async (c) => {
       w.calls.push(["runner", c.role, c.resume ?? null, c.model ?? null, c.prompt, c.readOnly ?? false, c.system]);
       w.seq.push(c.role + (c.resume ? "-resume" : ""));
+      w.envs.push(c.env ?? null);
       if (c.role === "builder") {
         const r = c.resume ? (w.resumeResult ?? w.result) : w.result;
         if (o.live) await o.live(w, put);
         else if (!c.resume && !o.noStages) writeStages(["investigation", "plan", "implementation"]);
         if (r) put("result.json", JSON.stringify(r));
-        if (c.resume) w.head = `bbbb${w.calls.length}`.padEnd(16, "0");
+        if (c.resume || /Merging origin\//.test(c.prompt)) { w.head = `bbbb${w.calls.length}`.padEnd(16, "0"); if (!o.leaveConflicts) { w.conflictFiles = []; w.mergeInProgress = false; } }
         return { text: "done", sessionId: "sess-1", usage: { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 100 }, costUsd: 0.1, durationMs: 1000, turns: 3, model: "default" };
       }
       return { text: w.reviews.length ? w.reviews.shift() : ok(), sessionId: "rev", usage: { input_tokens: 4, output_tokens: 2 }, costUsd: 0.05, durationMs: 500, turns: 2, model: c.model };
@@ -215,6 +236,15 @@ describe("core work-on", () => {
     assert.equal((await run(world({ changed: [] }))).terminalReason, "needs-human");
   });
 
+  it("worktree add retries a concurrent .git lock collision, then gives up after 5 tries", async () => {
+    const w = world(); w.lockFails = 2;
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.equal(w.calls.filter((c) => c[1] === "worktree" && c[2] === "add").length, 3);
+    const w2 = world(); w2.lockFails = 99;
+    assert.notEqual((await run(w2)).terminalReason, "merged");
+    assert.equal(w2.calls.filter((c) => c[1] === "worktree" && c[2] === "add").length, 5);
+  });
+
   it("needs-human terminals carry a specific outcome code, never unclassified", async () => {
     const code = async (w, extra) => {
       const dir = tmpDir("lean-code-");
@@ -622,3 +652,330 @@ describe("runCliBackendAsync", () => {
     await assert.rejects(runCliBackendAsync({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: d, bin: `${d}/bad`, logger: { log() {} } }), (e) => e.code === "CLI_BACKEND_FAILED" && /boom/.test(e.message));
   });
 });
+
+describe("base-sync (#4100)", () => {
+  const CONFLICTING = { mergeable: "CONFLICTING", mergeStateStatus: "DIRTY" };
+  const OKSTATE = { mergeable: "MERGEABLE", mergeStateStatus: "CLEAN" };
+  const gitCalls = (w) => w.calls.filter((c) => c[0] === "git").map((c) => c.slice(1));
+  const noRebaseNoForce = (w) => {
+    for (const g of gitCalls(w)) {
+      assert.notEqual(g[0], "rebase");
+      if (g[0] === "push") assert.ok(!g.some((x) => /^(--force|-f$|\+)/.test(x)), `force push: ${g.join(" ")}`);
+    }
+  };
+  const syncComment = (w) => w.comments.find((c) => c.includes("<!-- FORGE:BASE_SYNC -->"));
+
+  it("conflicting PR, clean merge: fetch, merge, push, merge the PR at the new head; no re-review", async () => {
+    const w = world({ prView: [CONFLICTING, OKSTATE], mergeResults: ["clean"] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(reviewers(w).length, 1, "no re-review for a conflict-free base merge");
+    assert.equal(builders(w).length, 1);
+    const g = gitCalls(w);
+    assert.ok(g.some((x) => x[0] === "fetch" && x[1] === "origin" && x[2] === "staging"));
+    assert.ok(g.some((x) => x[0] === "merge" && x[1] === "--no-edit" && x[2] === "origin/staging"));
+    assert.equal(g.filter((x) => x[0] === "push").length, 2, "initial push plus the sync push");
+    assert.match(syncComment(w), /## Base Sync[\s\S]*clean merge[\s\S]*not required \(conflict-free base merge\)/);
+    assert.deepEqual(w.merges[0].slice(-2), ["--match-head-commit", w.head]);
+    assert.match(traj(w)[0], /\| Base Sync \| 1 sync\(s\) \|/);
+    noRebaseNoForce(w);
+  });
+
+  it("no conflict: no Base Sync row detail and no sync comment", async () => {
+    const w = world();
+    await run(w);
+    assert.ok(!syncComment(w));
+    assert.match(traj(w)[0], /\| Base Sync \| not needed \| - \|/);
+  });
+
+  it("conflicting PR, real conflict: builder resumed with the files, reviewer PASS on the full diff, merge", async () => {
+    const w = world({ prView: [CONFLICTING, OKSTATE], mergeResults: ["conflict"], reviews: [ok(), ok()] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    const b = builders(w);
+    assert.equal(b.length, 2);
+    assert.equal(b[1][2], "sess-1", "same session resumed");
+    assert.match(b[1][4], /Merging origin\/staging into this branch conflicts in: src\/foo\.js\. 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\./);
+    assert.equal(reviewers(w).length, 2, "re-review after the conflict resolution");
+    assert.match(syncComment(w), /conflicts in `src\/foo\.js`[\s\S]*builder resolved 1 conflicted file[\s\S]*Re-review:\*\* PASS/);
+    assert.equal(w.merges.length, 1);
+    assert.deepEqual(w.merges[0].slice(-2), ["--match-head-commit", w.head]);
+    noRebaseNoForce(w);
+  });
+
+  it("conflict resolution that the re-review FAILs gets one retry then merges on PASS", async () => {
+    const w = world({ prView: [CONFLICTING, OKSTATE], mergeResults: ["conflict"], reviews: [ok(), bad("src/foo.js:4 lost base change"), ok()] });
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.equal(reviewers(w).length, 3);
+    assert.equal(builders(w).length, 3);
+  });
+
+  it("still conflicting after 2 base-syncs ends needs-human with base.conflict, never engine-error", async () => {
+    const w = world({ prView: [CONFLICTING], mergeResults: ["clean", "clean", "clean"] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "needs-human");
+    assert.equal(r.code, "base.conflict");
+    assert.equal(gitCalls(w).filter((x) => x[0] === "merge" && x[1] === "--no-edit").length, 2, "at most 2 base-syncs");
+    assert.equal(w.merges.length, 0);
+    assert.ok(w.edits.some((e) => e.includes("needs-human")));
+  });
+
+  it("unresolved conflict markers after the builder ends needs-human with base.conflict", async () => {
+    const w = world({ prView: [CONFLICTING], mergeResults: ["conflict"] });
+    w.markers = true;
+    const r = await run(w);
+    assert.equal(r.terminalReason, "needs-human"); assert.equal(r.code, "base.conflict");
+    assert.equal(w.merges.length, 0);
+    assert.ok(gitCalls(w).some((x) => x[0] === "merge" && x[1] === "--abort"));
+  });
+
+  it("a gh pr merge conflict error triggers base-sync, then the merge is retried", async () => {
+    const w = world({ prView: [OKSTATE], mergeErrors: ["GraphQL: Pull request is not mergeable (mergePullRequest)"], mergeResults: ["clean"] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.equal(w.mergeAttempts, 2);
+    assert.match(syncComment(w), /gh pr merge reported a conflict/);
+    noRebaseNoForce(w);
+  });
+
+  it("an unrelated gh pr merge error is not a base-sync", async () => {
+    const w = world({ mergeErrors: ["HTTP 500 boom"] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "engine-error");
+    assert.ok(!syncComment(w));
+  });
+
+  it("a resumed run with a conflicting PR syncs (fresh builder when the conflict needs resolving)", async () => {
+    const w = world({ prList: [{ number: 77, headRefOid: "x" }], remote: "abc\trefs/heads/feat/issue-7-lean", prView: [CONFLICTING, OKSTATE], mergeResults: ["conflict"], reviews: [ok(), ok()] });
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    const b = builders(w);
+    assert.equal(b.length, 1);
+    assert.equal(b[0][2], null, "no session id on resume: a fresh builder");
+    assert.match(b[0][4], /Merging origin\/staging into this branch conflicts in: src\/foo\.js/);
+    assert.equal(w.prs.length, 0);
+    noRebaseNoForce(w);
+  });
+
+  it("UNKNOWN mergeability with nothing to merge is not treated as a conflict", async () => {
+    const w = world({ prView: [{ mergeable: "UNKNOWN", mergeStateStatus: "UNKNOWN" }, { mergeable: "UNKNOWN", mergeStateStatus: "UNKNOWN" }, OKSTATE], mergeResults: ["clean"] });
+    // a clean merge that changes head would count; here make the merge a no-op by pinning the head
+    const orig = w.io.git;
+    w.io.git = async (a, o2) => { const r = await orig(a, o2); if (a[0] === "merge" && a[1] === "--no-edit") w.head = "aaaa1111aaaa1111"; return r; };
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.ok(!syncComment(w));
+  });
+});
+
+describe("usage limit, lease takeover, worktree setup, run tmp (#4101-#4104)", () => {
+  const limitErr = (extra) => Object.assign(new Error("claude CLI exited with status 1. You've hit your session limit"), { code: "CLI_BACKEND_FAILED", usageLimit: true, ...extra });
+  const failFirstBuilder = (w, err, times = 1) => { const orig = w.io.runner; let n = 0; w.io.runner = async (c) => { if (c.role === "builder" && n++ < times) throw err; return orig(c); }; };
+  const projector = (w, lease) => { w.leaseWrites = []; w.io.projector = { readState: async () => (lease ? { v: 1, lease } : null), writeState: async (_i, st) => { w.leaseWrites.push(st); } }; };
+
+  it("#4101 a usage limit with a near reset pauses until the reset, then resumes the same step", async () => {
+    const w = world(); const sleeps = [];
+    const s0 = w.io.sleep; w.io.sleep = async (ms) => { sleeps.push(ms); return s0(ms); };
+    failFirstBuilder(w, limitErr({ resetAtEpochMs: 90000, resetAt: "8:30pm" }));
+    const r = await run(w);
+    assert.equal(r.terminalReason, "merged");
+    assert.ok(sleeps.includes(90000), `slept until the reset: ${sleeps}`);
+    assert.equal(builders(w).length, 1);
+  });
+
+  it("#4101 a usage limit with a far reset ends deferred/rate_limited with the reset time, lease released, no needs-human", async () => {
+    const w = world(); projector(w, null);
+    failFirstBuilder(w, limitErr({ resetAtEpochMs: 3 * 3600 * 1000, resetAt: "8:30pm (Asia/Kolkata)" }));
+    const r = await run(w);
+    assert.equal(r.terminalReason, "deferred");
+    assert.equal(r.code, "rate_limited");
+    assert.match(r.detail, /resets at 8:30pm \(Asia\/Kolkata\)/);
+    assert.equal(w.edits.some((e) => e.includes("needs-human")), false);
+    assert.equal(traj(w).length, 0, "no trajectory comment for a deferral");
+    assert.equal(w.leaseWrites.at(-1).lease, null, "lease released");
+    assert.equal(w.merges.length, 0);
+  });
+
+  it("#4101 unknown reset pauses a bounded number of times, then defers", async () => {
+    const w = world(); let sleeps = 0;
+    const s0 = w.io.sleep; w.io.sleep = async (ms) => { sleeps++; return s0(ms); };
+    failFirstBuilder(w, limitErr(), 99);
+    const r = await run(w, { maxSessionLimitPauses: 2 });
+    assert.equal(r.terminalReason, "deferred"); assert.equal(r.code, "rate_limited");
+    assert.equal(sleeps, 2);
+    assert.match(r.detail, /resets at unknown/);
+  });
+
+  it("#4101 a non-limit runner error is still engine-error", async () => {
+    const w = world(); failFirstBuilder(w, new Error("boom"));
+    assert.equal((await run(w)).terminalReason, "engine-error");
+  });
+
+  it("#4102 a same-host holder whose pid is gone is taken over immediately; a live one or another host is not", async () => {
+    const future = Date.now() + 1e6;
+    const dead = Object.assign(new Error("no such process"), { code: "ESRCH" });
+    const w = world(); projector(w, { by: "core_4242", until: future, host: "h1", pid: 4242 });
+    const r = await run(w, { hostName: "h1", killFn: () => { throw dead; } });
+    assert.equal(r.terminalReason, "merged");
+    assert.ok(w.leaseWrites.some((x) => x.lease?.host === "h1" && Number.isSafeInteger(x.lease?.pid)), "lease records host and pid");
+    const w2 = world(); projector(w2, { by: "core_4242", until: 1e12, host: "h1", pid: 4242 });
+    assert.equal((await run(w2, { hostName: "h1", killFn: () => true })).terminalReason, "deferred");
+    const w3 = world(); projector(w3, { by: "core_4242", until: 1e12, host: "other-host", pid: 4242 });
+    assert.equal((await run(w3, { hostName: "h1", killFn: () => { throw dead; } })).terminalReason, "deferred");
+    assert.equal(builders(w3).length, 0);
+  });
+
+  it("#4103 a leftover unregistered worktree dir is removed (only this issue's lean dir) before add", async () => {
+    const w = world(); const removed = [];
+    w.io.fs.exists = async (p) => p === "/wt/lean-7"; w.io.fs.rmdir = async (p) => { removed.push(p); };
+    await run(w);
+    assert.deepEqual(removed, ["/wt/lean-7"]);
+    // a registered worktree dir is left to `git worktree remove`
+    const w2 = world(); const removed2 = [];
+    w2.io.fs.exists = async () => true; w2.io.fs.rmdir = async (p) => { removed2.push(p); };
+    const g = w2.io.git; w2.io.git = async (a, o2) => (a[0] === "worktree" && a[1] === "list" ? "worktree /wt/lean-7\nHEAD abc\n" : g(a, o2));
+    await run(w2);
+    assert.deepEqual(removed2, []);
+    // a worktree root that is not the lean root never deletes anything
+    const w3 = world(); const removed3 = [];
+    w3.io.fs.exists = async () => true; w3.io.fs.rmdir = async (p) => { removed3.push(p); };
+    await run(w3, { worktreeRoot: "/wt" , issue: 7 });
+    assert.ok(removed3.every((p) => p === "/wt/lean-7"));
+  });
+
+  it("#4103 'already exists' on add cleans the leftover and retries; index.lock and packed-refs.lock are retried", async () => {
+    for (const msg of ["fatal: '/wt/lean-7' already exists", "fatal: Unable to create '/r/.git/index.lock': File exists.", "error: cannot lock ref: Unable to create '/r/.git/packed-refs.lock': File exists", "fatal: could not lock config file /r/.git/config: File exists"]) {
+      const w = world(); let failed = false; const removed = [];
+      w.io.fs.exists = async (p) => failed && p === "/wt/lean-7"; w.io.fs.rmdir = async (p) => { removed.push(p); };
+      const g = w.io.git;
+      w.io.git = async (a, o2) => { if (a[0] === "worktree" && a[1] === "add" && !failed) { failed = true; throw Object.assign(new Error(msg), { stderr: msg }); } return g(a, o2); };
+      const r = await run(w);
+      assert.equal(r.terminalReason, "merged", msg);
+      if (/already exists/.test(msg)) assert.deepEqual(removed, ["/wt/lean-7"]);
+    }
+  });
+
+  it("#4104 the builder and reviewer run with a per-run TMPDIR that is removed on every terminal", async () => {
+    const mk = (w) => { w.tmpMade = []; w.tmpRemoved = []; w.io.runTmp = { prune: async () => { w.pruned = true; }, make: async (i, id) => { const d = `/home/x/.forge/tmp/runs/${id}`; w.tmpMade.push(d); return d; }, remove: async (d) => { w.tmpRemoved.push(d); } }; };
+    const cases = {
+      merged: (w) => w,
+      "needs-human": (w) => { w.reviews.push(bad(), bad()); return w; },
+      "engine-error": (w) => { failFirstBuilder(w, new Error("boom")); return w; },
+      deferred: (w) => { failFirstBuilder(w, limitErr({ resetAtEpochMs: 3 * 3600 * 1000 })); return w; },
+    };
+    for (const [reason, prep] of Object.entries(cases)) {
+      const w = world(); mk(w); prep(w);
+      const r = await run(w);
+      assert.equal(r.terminalReason, reason);
+      assert.equal(w.pruned, true);
+      assert.equal(w.tmpMade.length, 1);
+      assert.match(w.tmpMade[0], /\/\.forge\/tmp\/runs\/7-/);
+      assert.deepEqual(w.tmpRemoved, w.tmpMade, `${reason}: removed`);
+      for (const e of w.envs) assert.equal(e?.TMPDIR, w.tmpMade[0]);
+      if (["merged", "needs-human"].includes(reason)) assert.ok(w.envs.length >= 1);
+    }
+  });
+
+  it("#4104 makeRunTmp: removes only its own dirs; prune takes only old dirs with a dead owner and our marker", async () => {
+    const { mkdirSync, writeFileSync, existsSync, utimesSync } = await import("node:fs");
+    const root = tmpDir("core-runs-");
+    let t = 1_000_000_000_000;
+    const rt = makeRunTmp({ root, now: () => t, host: "h", alive: (pid) => pid === 111 });
+    const mine = await rt.make(7, "7-1");
+    assert.ok(existsSync(mine));
+    assert.equal(await rt.remove(mine), true); assert.ok(!existsSync(mine));
+    assert.equal(await rt.remove(`${root}/not-made`), false);
+    const outside = tmpDir("core-outside-"); writeFileSync(`${outside}/f`, "x");
+    assert.equal(await rt.remove(outside), false); assert.ok(existsSync(outside));
+    const own = (name, o2) => { mkdirSync(`${root}/${name}`); writeFileSync(`${root}/${name}/.forge-run-owner`, JSON.stringify({ host: "h", ...o2 })); };
+    own("old-dead", { pid: 999, created: t - 7 * 3600 * 1000 });
+    own("old-alive", { pid: 111, created: t - 7 * 3600 * 1000 });
+    own("fresh-dead", { pid: 999, created: t - 3600 * 1000 });
+    own("old-otherhost", { pid: 999, host: "zzz", created: t - 7 * 3600 * 1000 });
+    mkdirSync(`${root}/foreign`); writeFileSync(`${root}/foreign/data`, "not ours");
+    t += 1;
+    const removed = await rt.prune();
+    assert.deepEqual(removed.sort(), ["old-dead"]);
+    for (const keep of ["old-alive", "fresh-dead", "foreign"]) assert.ok(existsSync(`${root}/${keep}`), keep);
+  });
+
+  it("#4104 runCliBackend applies the per-run env to the child", async () => {
+    const { runCliBackend } = await import("../runner.mjs");
+    let seen;
+    runCliBackend({ spec: { name: "t" }, userMessage: "go", args: ["1"], cwd: tmpDir("core-env-"), logger: { log() {} }, env: { TMPDIR: "/x/run-tmp", CLAUDE_CODE_TMPDIR: "/x/run-tmp" },
+      spawnFn: (_b, _a, o2) => { seen = o2.env; return { status: 0, stdout: "{}", stderr: "" }; } });
+    assert.equal(seen.TMPDIR, "/x/run-tmp"); assert.equal(seen.CLAUDE_CODE_TMPDIR, "/x/run-tmp");
+    assert.equal(seen.ANTHROPIC_API_KEY, undefined);
+  });
+});
+
+describe("host admission (#4105)", () => {
+  const host = (o = {}) => ({ memAvailableMb: () => o.mem ?? 8192, freeMb: async (p) => (o.free ?? { "/tmp": 8192, "/home/x/.forge/tmp": 8192 })[p], loadAvg1: () => o.load ?? 1, cores: () => o.cores ?? 8, tmpPaths: () => ["/home/x/.forge/tmp", "/tmp"] });
+  const withHost = (w, h) => { w.io.host = h; w.ghCalls = 0; w.leaseWrites = []; w.io.projector = { readState: async () => { w.leaseReads = (w.leaseReads ?? 0) + 1; return null; }, writeState: async (_i, st) => { w.leaseWrites.push(st); } };
+    const g = w.io.gh; w.io.gh = async (a) => { w.ghCalls++; return g(a); }; return w; };
+
+  it("the outcome code is registered", async () => {
+    assert.equal(OUTCOME_CODES.HOST_BUSY, "host.busy");
+    const { readFileSync } = await import("node:fs");
+    assert.match(readFileSync(new URL("../../docs/OUTCOME-CODES.md", import.meta.url), "utf8"), /`host\.busy`/);
+  });
+
+  it("passes with headroom and runs normally", async () => {
+    const w = withHost(world(), host());
+    assert.equal((await run(w)).terminalReason, "merged");
+    assert.ok(w.ghCalls > 0);
+  });
+
+  it("low memory: deferred host.busy, no lease, no GitHub call, no worktree", async () => {
+    const w = withHost(world(), host({ mem: 1228 }));
+    const r = await run(w);
+    assert.equal(r.terminalReason, "deferred"); assert.equal(r.code, "host.busy");
+    assert.equal(r.detail, "host busy: mem 1.2G < 2G; retry in 60s");
+    assert.equal(w.ghCalls, 0); assert.equal(w.leaseWrites.length, 0); assert.equal(w.leaseReads ?? 0, 0);
+    assert.equal(w.calls.length, 0, "no git or runner calls");
+    assert.deepEqual(w.labels, []);
+  });
+
+  it("low tmp space on the run TMPDIR filesystem or on /tmp is deferred host.busy", async () => {
+    for (const free of [{ "/tmp": 8192, "/home/x/.forge/tmp": 512 }, { "/tmp": 100, "/home/x/.forge/tmp": 8192 }]) {
+      const w = withHost(world(), host({ free }));
+      const r = await run(w);
+      assert.equal(r.code, "host.busy"); assert.match(r.detail, /tmp \S+ \S+G < 1G/);
+      assert.equal(w.ghCalls, 0);
+    }
+  });
+
+  it("high load per core is deferred; disabled admission runs even on a starved host", async () => {
+    const wl = withHost(world(), host({ load: 40, cores: 8 }));
+    assert.match((await run(wl)).detail, /load 5\.0\/core > 4/);
+    const wd = withHost(world(), host({ mem: 1, free: { "/tmp": 1, "/home/x/.forge/tmp": 1 }, load: 99 }));
+    assert.equal((await run(wd, { admission: { enabled: false } })).terminalReason, "merged");
+  });
+
+  it("thresholds are configurable; a failing probe does not block", async () => {
+    assert.equal((await checkAdmission({ cfg: { min_free_mem_mb: 100 }, host: host({ mem: 500 }) })).ok, true);
+    assert.equal((await checkAdmission({ cfg: { min_free_mem_mb: 1000 }, host: host({ mem: 500 }) })).ok, false);
+    assert.equal((await checkAdmission({ host: { memAvailableMb: () => { throw new Error("x"); }, tmpPaths: () => { throw new Error("y"); } } })).ok, true);
+  });
+
+  it("forge.yaml engine.admission is read (nested or flat) and the CLI prints the deferral as the last line", async () => {
+    const { writeFileSync } = await import("node:fs");
+    const d = tmpDir("core-adm-");
+    writeFileSync(`${d}/forge.yaml`, "engine:\n  admission:\n    enabled: false\n    min_free_mem_mb: 4096\n");
+    const a = readAdmission(d);
+    assert.equal(a.enabled, false); assert.equal(a.min_free_mem_mb, 4096);
+    const lines = []; const l = console.log; console.log = (x) => lines.push(String(x));
+    try {
+      await runFromCli(["7", "--lane", "staging", "--repo", "o/r"], { dir: tmpDir("core-adm-"), emitTelemetry: async () => {}, leanIo: {}, io: { gh: async () => "o/r\n" },
+        leanModule: { runCore: async () => ({ terminalReason: "deferred", code: "host.busy", detail: "host busy: mem 1.2G < 2G; retry in 60s" }) } });
+    } finally { console.log = l; }
+    assert.equal(lines.at(-1), "issue #7 → deferred (host busy: mem 1.2G < 2G; retry in 60s)");
+  });
+
+  it("/orchestrate spec requeues host-busy lanes with a lower K and pauses on rate_limited", async () => {
+    const { readFileSync } = await import("node:fs");
+    const spec = readFileSync(new URL("../../commands/orchestrate.md", import.meta.url), "utf8");
+    assert.match(spec, /host busy[\s\S]*lower the effective K by\s+1 for the next 5 minutes, never below 1/);
+    assert.match(spec, /rate_limited[\s\S]*stop launching\s+new lanes until that reset time/);
+  });
+});

package/bin/lean/render.mjs

@@ -96,7 +96,7 @@ export function renderPrBody({ issue, investigation, plan, implementation, resul
 
 // ---- trajectory ----
 export function renderTrajectory(T) {
-  const rows = [["Validate", T.validate], ["Plan", T.plan], ["Implement", T.implement], ["Review", T.review], ["PR", T.pr], ["Merge", T.merge], ["Close", T.close]];
+  const rows = [["Validate", T.validate], ["Plan", T.plan], ["Implement", T.implement], ["Review", T.review], ["PR", T.pr], ["Base Sync", T.baseSync ?? "not needed"], ["Merge", T.merge], ["Close", T.close]];
   const cellPair = (v) => {
     const [res, notes] = Array.isArray(v) ? v : [v, ""];
     return `${cell(res ?? "not reached")} | ${notes ? cell(notes) : "-"}`;

package/bin/runner.mjs

@@ -1507,6 +1507,8 @@ export function runCliBackend({
   sessionFlags = [],
   // #4081: extra argv (e.g. ["--resume", id]) appended verbatim, never dropped by FORGEDOCK_FULL_SESSION.
   extraArgs = [],
+  // Core work-on: extra child env (e.g. a per-run TMPDIR) applied last.
+  env: extraEnv = null,
 }) {
   // forge#3589: opt-in flags, validated again here as defence in depth. Callers
   // (runCommand) are responsible for the version gate. Unset -> argv unchanged.
@@ -1581,6 +1583,9 @@ export function runCliBackend({
     // intact — only the Anthropic key is removed.
     const childEnv = withLeaseHolder(withRunTmpdir(withForgedockHome({ ...process.env }), { issue: issueFromArgs(args), cwd }), leaseHolder);
     delete childEnv.ANTHROPIC_API_KEY;
+    if (extraEnv && typeof extraEnv === "object") {
+      for (const [k, v] of Object.entries(extraEnv)) if (typeof v === "string" && k !== "ANTHROPIC_API_KEY") childEnv[k] = v;
+    }
 
     // No `shell` option (defaults to false): argv is passed as discrete,
     // unparsed elements — see the SECURITY note above. `bin` is expected to

package/commands/orchestrate.md

@@ -36,7 +36,8 @@ Do this yourself from issue text and the code. Spawn no sub-agents here.
      `git grep` of the symbols it names. Keep this to a few greps per issue, not an investigation.
    - **Size.** S, M or L, from the scope the issue describes.
 3. **Build the DAG.** Edge X → N means N waits until X merges:
-   - **Explicit:** `Depends on #X` / `Blocked by #X` where X is in the set. An open X outside the set
+   - **Explicit:** `Depends on #X` / `Blocked by #X` where X is in the set. Match it case-insensitively and
+     also in bold or list form (`**Depends on** #X`, `- Depends on: #X, #Y`). An open X outside the set
      means N is skipped as blocked.
    - **Conflict:** two issues that will edit the same file or the same function run one after the
      other (smaller first), so their PRs don't conflict. Different files run in parallel.
@@ -46,7 +47,9 @@ Do this yourself from issue text and the code. Spawn no sub-agents here.
 4. **Show the plan** as one table: issue, title, size, likely files, waits-on. There are no waves. Then proceed
    without asking.
 
-`K` = `--parallel` (default 3). `L` = `--lane` if given, otherwise the repo's base lane from forge.yaml.
+`K` = `--parallel` if given, otherwise `orchestration.max_concurrent` from the repo's `forge.yaml`
+(`yq '.orchestration.max_concurrent' forge.yaml`), otherwise 3. State the value of K and where it came
+from in the plan. `L` = `--lane` if given, otherwise the repo's base lane from forge.yaml.
 
 ## 3. Launch lanes
 
@@ -55,8 +58,10 @@ waits on nothing). Keep at most K lanes running. Whenever a lane is free, start
 issue right away (priority label first, then the smaller size). Never hold a ready issue back until other
 lanes finish.
 
-- **Shell lane (default, when `forgedock` is on PATH).** One `Bash` call per issue with
-  `run_in_background: true`:
+- **Shell lane (default, when `forgedock` is on PATH).** Each lane is its own `Bash` call with
+  `run_in_background: true`, so every running lane appears as its own background shell in this session.
+  Do NOT write a scheduler, wrapper or queue script that launches lanes for you. You are the scheduler:
+  start a lane, and when a lane's completion notification arrives, start the next ready issue.
 
   ```bash
   forgedock run-issue <N> --lane <L>
@@ -74,6 +79,15 @@ lanes finish.
   The agent does not merge.
 
 When a lane finishes:
+- `deferred` (lease held by another or a dead session): put it back in the queue and retry after the
+  lease time printed in its output.
+- `deferred` with "host busy" (code `host.busy`: the host is short of memory, tmp space or CPU headroom;
+  no lease was taken and nothing was posted): put the issue back in the queue and lower the effective K by
+  1 for the next 5 minutes, never below 1. Before raising K back, start one lane and check that it is not
+  host busy again.
+- `deferred` with `rate_limited` (usage limit; the last output line carries the reset time): stop launching
+  new lanes until that reset time, let running lanes finish, then resume the queue.
+- `dependency-open`: the engine found a dependency you missed. Add the edge and requeue the issue behind it.
 - `merged` or `invalid`: start the next ready issue.
 - `needs-human`: read the issue's last comment for the reason, and mark its dependents skipped.
 - `engine-error`: relaunch it once.

package/commands/review-pr.md

@@ -655,7 +655,7 @@ bash "$RF" classify --pr "$PR_NUMBER" --repo "$REPO" --context "$CTX" --out-dir
 cat "$OUT_DIR/note-list.txt" 2>/dev/null
 ```
 
-`extract` reads the trusted synthesized block for the head, else its trusted agent bodies (`BASE_SYNC_ONLY`: the carried head; `DELTA`: this head plus the earlier reviewed one), parses every `<!-- FINDING:... -->` marker (an unparseable marker blocks the review), dedupes by file + line range ±5 and by title (3+ shared keywords, higher confidence wins), and applies the **§6B.4 gates** in order, each keeping the finding when its input is unreadable: (1) **head-SHA**: a cited line past the end of the file at `REVIEW_SHA` is stale and DROPPED (`findings_dropped_stale`); (2) **introduced-line**: a MEDIUM-or-lower finding whose range (±5) misses the PR's added lines is `pre-existing` (**CRITICAL/HIGH are never routed as pre-existing**, whatever their confidence, `protocols.md` §5; input comes from the diff, never a reviewer's `**Scope**` tag; deleted, renamed and patch-less files always intersect); (3) **concrete-failure**: a MEDIUM-or-lower finding without a `**Failure scenario**` becomes a NOTE (`notes_demoted_no_scenario`).
+`extract` reads the trusted synthesized block for the head, else its trusted agent bodies (`BASE_SYNC_ONLY`: the carried head; `DELTA`: this head plus the earlier reviewed one), parses every `<!-- FINDING:... -->` marker (an unparseable marker blocks the review), dedupes by file + line range ±5 and by title (3+ shared keywords, higher confidence wins), and applies the **§6B.4 gates** in order, each keeping the finding when its input is unreadable: (1) **head-SHA**: a cited line past the end of the file at `REVIEW_SHA` is stale and DROPPED (`findings_dropped_stale`); (2) **introduced-line**: a MEDIUM-or-lower finding whose range (±5) misses the PR's added lines is `pre-existing` (**CRITICAL/HIGH are never routed as pre-existing**, whatever their confidence, `protocols.md` §5; input comes from the diff, never a reviewer's `**Scope**` tag; removed files, old names of renames and patch-less files are scope `unknown`, never pre-existing and never introduced; a renamed file with a patch is scored by its added lines); (3) **concrete-failure**: a MEDIUM-or-lower finding without a `**Failure scenario**` becomes a NOTE (`notes_demoted_no_scenario`).
 
 Read `STRUCTURED_FINDINGS`, `FINDINGS_KEPT`, `FINDINGS_DROPPED_STALE`, `FINDINGS_PREEXISTING` and `NOTES_DEMOTED_NO_SCENARIO` for the record and summary. The caller's part of 6A: add the Phase 2.5 `INTEG-N` findings no reviewer covered (CONFIRMED HIGH, so ISSUE, filed in 6C); findings come only from `FINDING:` markers, never from free text. If `AGENTS_WITHOUT_BLOCK` is non-empty those agents are undelivered: re-dispatch them once (Phase 4 rule), else take the degraded-panel path; `CLEAN_STRUCTURED` is withheld while it is non-empty. On `CLEAN_STRUCTURED=true` and no `INTEG-N` the review is clean: skip to Phase 7. A finding that somehow has no marker is classified with `classify-finding.sh --unstructured` (empty or unparseable severity gives `NOTE unstructured`, never ISSUE). **Pre-existing route**: a pre-existing finding (MEDIUM or lower) is never filed as `review-finding`/`needs-validation` nor linked to this PR (it stays out of findings-per-PR and the amplification ratio); it still passes the §6B.5 classifier, is listed once in the summary, and at most 3 per review (highest severity first) are filed with the `pre-existing` label plus `priority:*`, citing this PR (`preexisting_filed`, not `findings_filed`).
 

package/docs/CONFIG.md

@@ -482,6 +482,7 @@ engine:
 | `<key>_max_turns` | integer | No | Positive integer passed as `--max-turns`. Invalid values are ignored. |
 
 | `path` | string | No | `core` (default), `full`, `lean` or `auto`. `core` is the lean work-on (`bin/lean/`): one plain builder session, one read-only two-question reviewer, GitHub as the register (see RELEASE-NOTES v1.22). `lean` and `auto` are aliases of `core`; `full` runs the legacy multi-phase pipeline and is required for `--retry` and `--wait-lease`. The `--path` flag overrides. `lean_reviewer_model` sets the reviewer model (default `claude-sonnet-5-5`); the builder uses `--model` or the CLI default. `forgedock orchestrate <issues...> [--parallel K] [--lane L]` runs the core per issue (K default 3, lane default `staging`) and honours `**Depends on**` ordering among the given issues. |
+| `admission` | map | No | Host-resource admission for the core work-on (#4105), checked before the lease, worktree or any GitHub call. When a check fails the run ends `deferred` (code `host.busy`, exit 75) with a last line such as `issue #N → deferred (host busy: mem 1.2G < 2G; retry in 60s)`; no lease is taken and nothing is posted. Keys: `enabled` (default `true`; `false` disables admission), `min_free_mem_mb` (default 2048; `MemAvailable` from `/proc/meminfo`, else `os.freemem()`), `min_free_tmp_mb` (default 1024; free space of the run TMPDIR filesystem, `~/.forge/tmp`, and of `/tmp`, via `statfs`), `max_load_per_core` (default 4; 1-minute load average divided by cores). Write it nested (`engine:` then `admission:` with the keys indented) or flat as `admission_enabled`, `admission_min_free_mem_mb`, `admission_min_free_tmp_mb`, `admission_max_load_per_core`; the parser reads one nested level into `engine`. `/orchestrate` requeues a host-busy lane and lowers K by 1 for 5 minutes. |
 | `merge_wait` | string | No | Core work-on merge gate. `required` (default): wait only for the status checks the base branch requires under branch protection (`gh api repos/{o}/{r}/branches/{base}/protection/required_status_checks`, contexts and checks); with no protection or no required checks (404 or empty) merge right after review PASS. A failing required check is `needs-human`; a pending one is polled with backoff and never `needs-human`. `all`: wait for every check (`scripts/wait-ci-green.sh`). `none`: merge right after review. Always `--match-head-commit` at the reviewed head. The policy used is recorded in the `FORGE:WORK-ON` comment. |
 | `ci_pending_max_minutes` | integer | No | Minutes the engine waits for CI when the review phase ends BLOCKED with "checks still pending", or the remediate phase holds at its M7 re-gate on "CI pending" (the merge gate's wait window ended while CI was still running). Default: 90. Invalid values are ignored. This key is flat like the others but is not part of the `<key>_model` / `<key>_max_turns` pattern. |
 

package/docs/OUTCOME-CODES.md

@@ -33,6 +33,7 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `ci.red` | CI failed | reserved | `REVIEW_RESULT` carries no CI field yet |
 | `ci.timeout` | CI timed out | reserved | `REVIEW_RESULT` carries no CI field yet |
 | `base.conflict` | Base-branch conflict blocked the PR | reserved | `REVIEW_RESULT` carries no conflict field yet |
+| `host.busy` | Core run deferred at admission: free memory, free tmp space or load per core outside `engine.admission` limits; no lease taken, nothing posted | lean | `bin/lean/admission.mjs` |
 | `rate_limited` | Session or usage limit outlasted the pause budget | engine | `err.usageLimit` / `err.resetAtEpochMs` |
 | `engine.error` | Engine or tool failure (missing key/SDK, CLI crash, max turns, unresolved args, runner threw every attempt) | engine | `err.code` |
 | `infra.disk_quota` | Disk full or quota exhausted (EDQUOT/ENOSPC, errno -28/-122); retryable infra failure, never `needs-human` | engine | Runner error text |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.24.0",
+  "version": "1.24.2",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/review-finalize.sh

@@ -417,9 +417,12 @@ EOF
         /^\+/{print f":"n; print f "\t" substr($(0),2) > tf; n++;next}
         /^-/{next}
         {n++}' > "$ADDED_LINES_FILE" || { : > "$ADDED_LINES_FILE"; : > "$ADDED_TEXT_FILE"; }
-    # Files the PR deleted or renamed (the old name too): findings on them always intersect.
+    # Files the PR deleted or renamed (the old name too): Gate 1 never drops findings on them as stale.
     GONE_FILES_FILE="$WORKDIR/gone-files"
     jq -r '.[] | select(.status=="removed" or .status=="renamed") | .filename, (.previous_filename // empty)' "$FILES_JSON" > "$GONE_FILES_FILE" 2>/dev/null || : > "$GONE_FILES_FILE"
+    # Removed files and old names of renames: no head line to score, so Gate 2 scope stays unknown (#3985).
+    NOSCOPE_FILES_FILE="$WORKDIR/noscope-files"
+    jq -r '.[] | (select(.status=="removed") | .filename), (.previous_filename // empty)' "$FILES_JSON" > "$NOSCOPE_FILES_FILE" 2>/dev/null || : > "$NOSCOPE_FILES_FILE"
     # Files present with no `patch` (large/truncated diff): their added lines are UNKNOWN, so findings on them are always kept.
     NOPATCH_FILES_FILE="$WORKDIR/nopatch-files"
     jq -r '.[] | select(.patch == null and .status != "removed") | .filename' "$FILES_JSON" > "$NOPATCH_FILES_FILE" 2>/dev/null || : > "$NOPATCH_FILES_FILE"
@@ -494,8 +497,9 @@ SYMEOF
         ROUTE="file"
         # Validate before any arithmetic: never expand reviewer text in $(( )).
         case "$LINE" in ""|*[!0-9]*) LINE="" ;; esac
-        GONE=0; NOPATCH=0
+        GONE=0; NOPATCH=0; NOSCOPE=0
         grep -qxF -- "$FILE" "$GONE_FILES_FILE" && GONE=1
+        grep -qxF -- "$FILE" "$NOSCOPE_FILES_FILE" && NOSCOPE=1
         grep -qxF -- "$FILE" "$NOPATCH_FILES_FILE" && NOPATCH=1
         # Gate 1 (head-SHA): the cited line must exist at REVIEW_SHA. A file the PR deleted or renamed is kept (checked first).
         if [ "$GONE" -eq 0 ] && [ -n "$LINE" ]; then
@@ -509,13 +513,12 @@ SYMEOF
             esac
             if [ "$STALE" -eq 1 ]; then N_STALE=$((N_STALE + 1)); continue; fi
         fi
-        # Gate 2 (introduced-line): scope is computed for every finding (any severity) from the added-line map. A file the PR deleted or renamed is introduced;
-        # a patch-less file, an empty map or a missing line is unknown. MEDIUM or lower with no added line within +-5 is routed pre-existing.
+        # Gate 2 (introduced-line): scope is computed for every finding (any severity) from the added-line map. A removed file, the old name
+        # of a rename, a patch-less file (a pure rename too), an empty map or a missing line is unknown: never introduced, never pre-existing (#3985).
+        # A renamed file with a patch is scored like any other. MEDIUM or lower with no added line within +-5 is routed pre-existing.
         # CRITICAL/HIGH and unknown severities never are (their scope is still recorded).
         SCOPE="unknown"
-        if [ "$GONE" -eq 1 ]; then
-            SCOPE="introduced"
-        elif [ -n "$LINE" ] && [ "$NOPATCH" -eq 0 ] && [ -s "$ADDED_LINES_FILE" ]; then
+        if [ -n "$LINE" ] && [ "$NOSCOPE" -eq 0 ] && [ "$NOPATCH" -eq 0 ] && [ -s "$ADDED_LINES_FILE" ]; then
             LO=$((LINE > 5 ? LINE - 5 : 1)); INTRODUCED=0; L="$LO"
             while [ "$L" -le $((LINE + 5)) ]; do
                 if grep -qxF -- "${FILE}:${L}" "$ADDED_LINES_FILE"; then INTRODUCED=1; break; fi

package/scripts/review-finalize.test.sh

@@ -294,9 +294,9 @@ cm MEMBER User "$(agent_body security "$SHA" '### P-1 pre
 run "$GOOD" extract; want "unreadable diff keeps" '.findings[0].route' findings.json "file"
 want "unreadable diff: scope unknown" '.findings[0].scope' findings.json "unknown"
 
-# gate 2 route table (ported from the retired spec sketch test): severity normalisation, deleted/renamed/patch-less files, files absent from the diff
+# gate 2 route table (ported from the retired spec sketch test): severity normalisation, deleted/renamed/patch-less files (scope unknown unless a patch shows an added line, #3985), files absent from the diff
 reset
-printf '%s\n' '[{"filename":"a.sh","status":"modified","patch":"@@ -9,2 +9,3 @@\n ctx\n+added\n ctx"},{"filename":"big.txt","status":"modified"},{"filename":"gone.txt","status":"removed"},{"filename":"new.sh","status":"renamed","previous_filename":"old.sh","patch":"@@ -1,1 +1,1 @@\n+x"}]' > "$FIX/pr-files.json"
+printf '%s\n' '[{"filename":"a.sh","status":"modified","patch":"@@ -9,2 +9,3 @@\n ctx\n+added\n ctx"},{"filename":"big.txt","status":"modified"},{"filename":"gone.txt","status":"removed"},{"filename":"new.sh","status":"renamed","previous_filename":"old.sh","patch":"@@ -1,1 +1,1 @@\n+x"},{"filename":"mv.sh","status":"renamed","previous_filename":"was.sh"}]' > "$FIX/pr-files.json"
 G2_PROSE=""; G2_MARKS=""
 g2() {   # g2 <id> <severity> <file:line> <title words>
     G2_PROSE="${G2_PROSE}### $1 finding
@@ -309,12 +309,14 @@ g2 G-1 MEDIUM a.sh:10 "alpha one"; g2 G-2 MEDIUM a.sh:100 "bravo two"; g2 G-3 CR
 g2 G-5 high a.sh:140 "echo five"; g2 G-6 "HIGH " a.sh:160 "foxtrot six"; g2 G-7 "" a.sh:180 "golf seven"; g2 G-8 SEVERE a.sh:200 "hotel eight"
 g2 G-9 medium a.sh:220 "india nine"; g2 G-10 INFO a.sh:240 "juliet ten"; g2 G-11 MEDIUM old.sh:3 "kilo eleven"; g2 G-12 LOW a.sh:260 "lima twelve"
 g2 G-13 LOW gone.txt:3 "mike thirteen"; g2 G-14 MEDIUM other.sh:5 "november fourteen"
+# #3985: a pure rename (no patch) is unknown; a renamed file with a patch is scored by its added lines like any other
+g2 G-15 MEDIUM mv.sh:3 "oscar fifteen"; g2 G-16 MEDIUM new.sh:1 "papa sixteen"; g2 G-17 MEDIUM new.sh:40 "quebec seventeen"
 cm MEMBER User "$(agent_body security "$SHA" "$G2_PROSE" "$G2_MARKS")"; flush
 run "$GOOD" extract; rc_is "gate2 table" "$RC" 0
-for pair in G-1:file G-2:pre-existing G-3:file G-4:file G-5:file G-6:file G-7:file G-8:file G-9:pre-existing G-10:pre-existing G-11:file G-12:pre-existing G-13:file; do
+for pair in G-1:file G-2:pre-existing G-3:file G-4:file G-5:file G-6:file G-7:file G-8:file G-9:pre-existing G-10:pre-existing G-11:file G-12:pre-existing G-13:file G-15:file G-16:file G-17:pre-existing; do
     want "gate2 table: ${pair%%:*}" ".findings[] | select(.id == \"${pair%%:*}\") | .route" findings.json "${pair#*:}"
 done
-for pair in G-1:introduced G-2:pre-existing G-3:pre-existing G-4:unknown G-7:pre-existing G-13:introduced G-12:pre-existing; do
+for pair in G-1:introduced G-2:pre-existing G-3:pre-existing G-4:unknown G-7:pre-existing G-12:pre-existing G-11:unknown G-13:unknown G-15:unknown G-16:introduced G-17:pre-existing; do
     want "scope table: ${pair%%:*}" ".findings[] | select(.id == \"${pair%%:*}\") | .scope" findings.json "${pair#*:}"
 done
 want "gate2 table: a file absent from the PR and from the head is stale (gate 1), not pre-existing" '[.findings[].id] | contains(["G-14"]) | not' findings.json "true"