forgedock 1.26.0 → 1.28.0

package/bin/lean/heavy.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Phase-aware host admission (#4169): lanes run their LLM phases freely (bounded only by the host lane cap, #4191),
+ * and only `heavy` steps (installs, type checks, linters, test runners, containers) take a slot of one host semaphore.
+ * State is one file, `heavy.json` in `schedDir()` (next to the lane registry): `{v, seq, maxQueued, holders:{key:{pid,
+ * issue, phase, priority, mb, at}}, waiters:{key:{pid, issue, phase, priority, seq, at}}}`, mutated under an exclusive
+ * lock file (`heavy.lock`, owner pid; a dead owner's lock is taken over) with `writeAtomic`, like `sched.mjs`.
+ *
+ * A grant needs: live holders < max (default max(1, cores - 1)); the caller first among waiters (priority, then FIFO);
+ * and MemAvailable − Σ mb of holders granted within the ramp window ≥ step_mem_mb + reserve_mb. Swap never counts as
+ * free memory. With no holder, one grant is allowed while MemAvailable ≥ reserve_mb, so a step is never starved by a
+ * host whose memory is used by something else. Fail-open: an unreadable registry or a lock timeout grants.
+ *
+ * Builder-run commands are gated by per-run PATH shims (`writeHeavyShims`) that call this file as a CLI:
+ * `heavy.mjs run --name <n> -- <abs-real-bin> args...` (nested calls pass through via FORGE_HEAVY_HELD).
+ */
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync, appendFileSync, writeFileSync, chmodSync } from "node:fs";
+import { cpus, freemem } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { writeAtomic } from "./batch.mjs";
+import { schedDir, pidAlive, DEFAULT_PRIORITY } from "./sched.mjs";
+import { which } from "./toolchain.mjs";
+import { hostParallelism } from "./admission.mjs";
+
+export const HEAVY_DEFAULTS = Object.freeze({ enabled: true, max: null, step_mem_mb: 2048, reserve_mb: 1024, ramp_s: 60, max_wait_s: 1800 });
+export const HEAVY_POLL_MS = 2000;
+const LOCK_WAIT_MS = 2000, EMPTY_LOCK_STALE_MS = 5000;
+
+const PMS = new Set(["npm", "pnpm", "yarn", "bun"]);
+/** Package-manager subcommands that only read metadata (everything else installs or runs scripts/tools). */
+const PM_LIGHT = new Set(["version", "help", "view", "info", "show", "ls", "list", "why", "outdated", "config", "get", "set", "whoami", "root", "bin", "prefix", "store", "cache", "pack", "publish", "login", "logout", "search", "owner", "dist-tag"]);
+const PM_VALUE_FLAGS = new Set(["-w", "-C", "-F", "--filter", "--dir", "--cwd", "--prefix", "--workspace"]);
+const RUNNERS = new Set(["npx", "bunx", "pnpx"]);
+const TOOLS = new Set(["tsc", "eslint", "jest", "vitest", "playwright", "pytest", "mypy", "pyright", "tox", "gradle", "gradlew", "mvn"]);
+const SUBTOOLS = {
+  cargo: new Set(["build", "b", "test", "t", "check", "c", "clippy", "run", "r", "bench", "doc", "install"]),
+  go: new Set(["build", "test", "vet", "run", "install", "generate"]),
+  docker: new Set(["run", "build", "compose", "buildx"]),
+  "docker-compose": new Set(["up", "run", "build", "create", "start"]),
+};
+/** Every command name a heavy shim is written for (only those found on the lane PATH get one). */
+export const HEAVY_BINS = Object.freeze([...PMS, ...RUNNERS, ...TOOLS, ...Object.keys(SUBTOOLS)]);
+const INFO = new Set(["-v", "-V", "--version", "version", "-h", "--help", "help"]);
+
+/** 'heavy' | 'llm' for one command line (`name` is the basename, `args` its argv). Unknown commands are llm. */
+export function classifyStep(name, args = []) {
+  const n = String(name ?? "").split("/").pop();
+  const a = (args ?? []).map(String);
+  const onlyInfo = a.length > 0 && a.every((x) => INFO.has(x));
+  if (PMS.has(n)) {
+    // A pm flag-with-value prefix (`pnpm --filter x test`, `npm -w a run`) is skipped to find the subcommand.
+    let i = 0;
+    while (i < a.length && a[i].startsWith("-") && !INFO.has(a[i])) i += PM_VALUE_FLAGS.has(a[i]) ? 2 : 1;
+    const sub = a[i];
+    if (sub === undefined) return n === "yarn" && a.length === 0 ? "heavy" : "llm"; // bare `yarn` installs
+    return PM_LIGHT.has(sub) || INFO.has(sub) ? "llm" : "heavy";
+  }
+  if (RUNNERS.has(n) || TOOLS.has(n)) return a.length === 0 && RUNNERS.has(n) ? "llm" : onlyInfo ? "llm" : "heavy";
+  if (SUBTOOLS[n]) { const sub = a.find((x) => !x.startsWith("-")); return sub && SUBTOOLS[n].has(sub) ? "heavy" : "llm"; }
+  return "llm";
+}
+
+/** Merged heavy config: defaults ← cfg (forge.yaml engine.heavy_*) ← env (FORGE_HEAVY_MAX|STEP_MEM_MB|RESERVE_MB). */
+export function heavyConfig(cfg = {}, env = {}) {
+  const pos = (v) => { const x = Number(v); return v !== undefined && v !== null && String(v).trim() !== "" && Number.isFinite(x) && x > 0 ? x : null; };
+  const c = { ...HEAVY_DEFAULTS };
+  for (const k of ["max", "step_mem_mb", "reserve_mb", "ramp_s", "max_wait_s"]) { const v = pos(cfg?.[k]); if (v !== null) c[k] = k === "max" ? Math.floor(v) : v; }
+  if (cfg?.enabled === false) c.enabled = false;
+  const e = { max: env.FORGE_HEAVY_MAX, step_mem_mb: env.FORGE_HEAVY_STEP_MEM_MB, reserve_mb: env.FORGE_HEAVY_RESERVE_MB };
+  for (const [k, v] of Object.entries(e)) { const x = pos(v); if (x !== null) c[k] = k === "max" ? Math.floor(x) : x; }
+  return c;
+}
+
+/** MemAvailable (MB) from /proc/meminfo, else os.freemem; never swap. */
+export function 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);
+}
+const defaultHost = () => ({ memAvailableMb, cores: () => cpus().length || 1 });
+
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const byRank = ([ka, a], [kb, b]) => (a.priority - b.priority) || (a.seq - b.seq) || (ka < kb ? -1 : ka > kb ? 1 : 0);
+
+/**
+ * Handle on the heavy semaphore. `host` gives {memAvailableMb, cores}; `alive(pid)` the liveness probe (tests inject).
+ * @returns {{dir, file, max, tryAcquire, withdraw, release, stats}}
+ */
+export function openHeavy(dir = schedDir(), { cfg = {}, env = {}, host = defaultHost(), now = () => Date.now(), pid = process.pid, alive = pidAlive, lockWaitMs = LOCK_WAIT_MS } = {}) {
+  const c = heavyConfig(cfg, env);
+  const file = join(dir, "heavy.json"), lockFile = join(dir, "heavy.lock");
+  const num = (f) => { try { const v = f?.(); return Number.isFinite(v) ? v : null; } catch { return null; } };
+  const max = () => c.max ?? Math.max(1, (num(host.cores) ?? 1) - 1);
+
+  const lock = () => {
+    mkdirSync(dir, { recursive: true });
+    const end = Date.now() + lockWaitMs;
+    for (;;) {
+      try { const fd = openSync(lockFile, "wx"); try { writeSync(fd, String(pid)); } finally { closeSync(fd); } return; } catch (e) { if (e?.code !== "EEXIST") throw e; }
+      let owner = NaN;
+      try { owner = parseInt(readFileSync(lockFile, "utf8"), 10); } catch { /* released meanwhile */ }
+      let empty = false;
+      if (Number.isNaN(owner)) { try { empty = Date.now() - statSync(lockFile).mtimeMs < EMPTY_LOCK_STALE_MS; } catch { continue; } }
+      if (!empty && (Number.isNaN(owner) || !alive(owner))) {
+        const aside = `${lockFile}.stale-${pid}`;
+        try {
+          renameSync(lockFile, aside);
+          let got = NaN;
+          try { got = parseInt(readFileSync(aside, "utf8"), 10); } catch { /* gone */ }
+          if (!Number.isNaN(got) && got !== owner && alive(got)) { try { renameSync(aside, lockFile); } catch { /* best effort */ } }
+          else rmSync(aside, { force: true });
+        } catch { /* someone else took it over */ }
+        continue;
+      }
+      if (Date.now() >= end) throw new Error(`heavy registry lock held by pid ${Number.isNaN(owner) ? "?" : owner}`);
+      pause(10);
+    }
+  };
+  const unlock = () => { try { rmSync(lockFile, { force: true }); } catch { /* best effort */ } };
+  const read = () => {
+    let o;
+    try { o = JSON.parse(readFileSync(file, "utf8")); } catch (e) {
+      if (e?.code !== "ENOENT") throw new Error(`heavy registry ${file} unreadable: ${e?.message ?? e}`);
+      o = {};
+    }
+    const obj = (x) => (x && typeof x === "object" && !Array.isArray(x) ? x : {});
+    return { v: 1, seq: Number.isInteger(o?.seq) ? o.seq : 0, maxQueued: Number.isInteger(o?.maxQueued) ? o.maxQueued : 0, holders: obj(o?.holders), waiters: obj(o?.waiters) };
+  };
+  const mutate = (fn) => {
+    lock();
+    try {
+      const s = read();
+      for (const [k, e] of Object.entries(s.holders)) if (!alive(e.pid)) delete s.holders[k];
+      for (const [k, e] of Object.entries(s.waiters)) if (!alive(e.pid)) delete s.waiters[k];
+      const r = fn(s);
+      writeAtomic(file, JSON.stringify(s, null, 2) + "\n");
+      return r;
+    } finally { unlock(); }
+  };
+
+  return {
+    dir, file, max, config: c,
+    /**
+     * Grant `key` a slot or queue it. entry: {issue, phase, priority, mb}.
+     * @returns {{ok:boolean, fallback?:true, reason?:string, holders?:number}}
+     */
+    tryAcquire: (key, entry = {}) => {
+      try {
+        return mutate((s) => {
+          if (s.holders[key]) return { ok: true, holders: Object.keys(s.holders).length, queued: Object.keys(s.waiters).length };
+          const priority = Number.isFinite(Number(entry.priority)) ? Number(entry.priority) : DEFAULT_PRIORITY;
+          if (!s.waiters[key]) s.waiters[key] = { pid, issue: entry.issue ?? null, phase: entry.phase ?? null, priority, seq: ++s.seq, at: now() };
+          const queued = Object.keys(s.waiters).length;
+          s.maxQueued = Math.max(s.maxQueued, queued);
+          const held = Object.values(s.holders);
+          const order = Object.entries(s.waiters).sort(byRank);
+          if (order[0][0] !== key) return { ok: false, queued, reason: `queued behind ${order.findIndex(([k]) => k === key)} heavy step(s)` };
+          if (held.length >= max()) return { ok: false, queued, reason: `heavy cap ${max()} reached` };
+          const mem = num(host.memAvailableMb);
+          if (mem !== null) {
+            if (held.length === 0 ? mem < c.reserve_mb : (() => {
+              const ramping = held.filter((h) => now() - (h.at ?? 0) < c.ramp_s * 1000).reduce((t, h) => t + (Number(h.mb) || c.step_mem_mb), 0);
+              return mem - ramping < c.step_mem_mb + c.reserve_mb;
+            })()) return { ok: false, queued, reason: `free memory ${mem} MB below the heavy-step reservation` };
+          }
+          const w = s.waiters[key];
+          delete s.waiters[key];
+          s.holders[key] = { pid, issue: w.issue, phase: w.phase, priority: w.priority, mb: Number(entry.mb) > 0 ? Number(entry.mb) : c.step_mem_mb, at: now() };
+          return { ok: true, holders: held.length + 1, queued };
+        });
+      } catch (e) { return { ok: true, fallback: true, reason: e?.message ?? String(e) }; }
+    },
+    withdraw: (key) => { try { mutate((s) => { delete s.waiters[key]; }); } catch { /* fail-open */ } },
+    release: (key) => { try { mutate((s) => { delete s.holders[key]; delete s.waiters[key]; }); } catch { /* fail-open */ } },
+    /** {holders, queued, maxQueued, max} of live entries, read-only (no lock, no write); null when unreadable. */
+    stats: () => {
+      try {
+        const s = read(), live = (o) => Object.values(o).filter((e) => alive(e.pid)).length;
+        return { holders: live(s.holders), queued: live(s.waiters), maxQueued: s.maxQueued, max: max() };
+      } catch { return null; }
+    },
+  };
+}
+
+let keySeq = 0;
+/**
+ * Wait for a slot (polling), giving up after `max_wait_s` (the step then runs ungated: never stall a lane forever).
+ * `queued` is the longest heavy queue (this step included) seen while waiting.
+ * @returns {Promise<{key:string, waitMs:number, holders:number, queued:number, fallback?:true, timedOut?:true, release:Function}>}
+ */
+export async function acquireHeavy(h, entry = {}, { pollMs = HEAVY_POLL_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = () => Date.now(), pid = process.pid } = {}) {
+  const key = `${pid}:${++keySeq}:${entry.phase ?? "step"}`;
+  const t0 = now(), limit = (h.config?.max_wait_s ?? HEAVY_DEFAULTS.max_wait_s) * 1000;
+  let queued = 0;
+  const done = (extra) => ({ key, waitMs: now() - t0, holders: 1, queued, ...extra, release: () => h.release(key) });
+  for (;;) {
+    const r = h.tryAcquire(key, entry);
+    if (Number.isInteger(r.queued)) queued = Math.max(queued, r.queued);
+    if (r.ok) return done({ holders: r.holders ?? 1, ...(r.fallback ? { fallback: true } : {}) });
+    if (now() - t0 >= limit) { h.withdraw(key); return done({ timedOut: true, release: () => {} }); }
+    await sleep(pollMs);
+  }
+}
+
+/** Default lane effect: `acquire(entry, cfg)` → {waitMs, queued, release()} (cfg = the lane's forge.yaml heavy keys); `stats()`. */
+export function makeHeavyIo({ dir = schedDir(), env = process.env, host } = {}) {
+  const open = (cfg) => openHeavy(dir, { cfg, env, ...(host ? { host } : {}) });
+  return { acquire: (entry, cfg = {}) => acquireHeavy(open(cfg), entry), stats: () => open({}).stats() };
+}
+
+const SHIM_HEADER = "#!/bin/sh\n# forgedock heavy-step shim (#4169): waits for a host heavy-step slot, then runs the real command; do not edit.\n";
+const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+/** Shim script for one command: exec node heavy.mjs run --name <n> -- <real> "$@". */
+export function heavyShimScript(name, real, { node = process.execPath, script = fileURLToPath(import.meta.url) } = {}) {
+  return `${SHIM_HEADER}exec ${q(node)} ${q(script)} run --name ${q(name)} -- ${q(real)} "$@"\n`;
+}
+
+/**
+ * Write 0755 shims into `binDir` for every HEAVY_BINS name found on `path` (binDir excluded, real path resolved now, so
+ * a shim never calls itself). Returns the names written.
+ */
+export async function writeHeavyShims(binDir, { path = process.env.PATH ?? "", find = which, node, script, mkdirp = (d) => mkdirSync(d, { recursive: true }), writeShim = (p, t) => { writeFileSync(p, t); chmodSync(p, 0o755); } } = {}) {
+  const found = HEAVY_BINS.map((n) => [n, find(n, path, [binDir])]).filter(([, r]) => r);
+  if (!found.length) return [];
+  await mkdirp(binDir);
+  for (const [n, real] of found) await writeShim(join(binDir, n), heavyShimScript(n, real, { ...(node ? { node } : {}), ...(script ? { script } : {}) }));
+  return found.map(([n]) => n);
+}
+
+/** Parse heavy-wait jsonl lines into {waits: {phase: ms}, queueMax} (bad lines ignored). */
+export function sumWaits(text, waits = {}) {
+  let queueMax = 0;
+  for (const line of String(text ?? "").split("\n")) {
+    if (!line.trim()) continue;
+    let j; try { j = JSON.parse(line); } catch { continue; }
+    const ms = Number(j?.waitMs);
+    if (Number.isFinite(ms) && ms >= 0) { const p = String(j.phase || "step"); waits[p] = (waits[p] ?? 0) + ms; }
+    if (Number.isInteger(j?.queued)) queueMax = Math.max(queueMax, j.queued);
+  }
+  return { waits, queueMax };
+}
+
+/**
+ * CLI body: `run --name <n> -- <real> args...`. Pass-through when FORGE_HEAVY_HELD is set or the step is llm; else
+ * acquire, run with FORGE_HEAVY_HELD=1 and FORGE_HOST_PARALLELISM from live holders, release, propagate the exit.
+ */
+export async function runWrapped(argv, { env = process.env, open = openHeavy, run = spawnInherit, host } = {}) {
+  const sep = argv.indexOf("--");
+  if (argv[0] !== "run" || sep < 0 || !argv[sep + 1]) throw new Error("usage: heavy.mjs run --name <name> -- <command> [args...]");
+  const ni = argv.indexOf("--name");
+  const name = ni >= 0 && ni < sep ? argv[ni + 1] : argv[sep + 1];
+  const [cmd, ...args] = argv.slice(sep + 1);
+  const c = heavyConfig({}, env);
+  if (env.FORGE_HEAVY_HELD || env.FORGE_HEAVY_DISABLED === "1" || classifyStep(name, args) === "llm") return run(cmd, args, env);
+  const hostP = host ?? defaultHost();
+  const h = open(env.FORGEDOCK_SCHED_DIR || schedDir(env), { env, host: hostP });
+  const priority = Number.isFinite(Number(env.FORGE_LANE_PRIORITY)) && String(env.FORGE_LANE_PRIORITY).trim() !== "" ? Number(env.FORGE_LANE_PRIORITY) : DEFAULT_PRIORITY;
+  const phase = env.FORGE_LANE_PHASE || "step";
+  const g = await acquireHeavy(h, { issue: Number(env.FORGE_LANE_ISSUE) || null, phase, priority, mb: c.step_mem_mb });
+  if (env.FORGE_HEAVY_WAITS) { try { appendFileSync(env.FORGE_HEAVY_WAITS, JSON.stringify({ phase, name, waitMs: g.waitMs, queued: g.queued }) + "\n"); } catch { /* metrics are best effort */ } }
+  let cores = 1; try { cores = hostP.cores() || 1; } catch { /* 1 */ }
+  const childEnv = { ...env, FORGE_HEAVY_HELD: "1",
+    ...(env.FORGE_HEAVY_PARALLELISM_PINNED === "1" ? {} : { FORGE_HOST_PARALLELISM: String(hostParallelism({ cores, lanes: g.holders })) }) };
+  try { return await run(cmd, args, childEnv); } finally { g.release(); }
+}
+
+/** Spawn with inherited stdio; resolves {code, signal}; forwards termination signals to the child. */
+export function spawnInherit(cmd, args, env) {
+  return new Promise((done) => {
+    const child = spawn(cmd, args, { stdio: "inherit", env });
+    const fwd = (sig) => { try { child.kill(sig); } catch { /* gone */ } };
+    const sigs = ["SIGTERM", "SIGINT", "SIGHUP"];
+    for (const s of sigs) process.on(s, fwd);
+    const off = () => { for (const s of sigs) process.off(s, fwd); };
+    child.on("error", (e) => { off(); process.stderr.write(`${cmd}: ${e.message}\n`); done({ code: e.code === "ENOENT" ? 127 : 126, signal: null }); });
+    child.on("exit", (code, signal) => { off(); done({ code, signal }); });
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runWrapped(process.argv.slice(2)).then(({ code, signal }) => {
+    if (signal) { process.kill(process.pid, signal); return; }
+    process.exit(code ?? 1);
+  }, (e) => { process.stderr.write(`forgedock heavy: ${e?.message ?? e}\n`); process.exit(2); });
+}

package/bin/lean/heavy.test.mjs

@@ -0,0 +1,207 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, readFileSync, mkdirSync, chmodSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { classifyStep, heavyConfig, openHeavy, acquireHeavy, writeHeavyShims, heavyShimScript, sumWaits, runWrapped, HEAVY_BINS } from "./heavy.mjs";
+import { checkAdmission, ADMISSION_DEFAULTS } from "./admission.mjs";
+import { formatWaitSummary } from "./orchestrate.mjs";
+import { readHeavy } from "../engine-cli.mjs";
+
+// Injected pids, clock and host: `live` is the set of pids the registry sees as alive; `mem` the MemAvailable in MB.
+const world = ({ mem = 12000, cores = 4, swapFree = 0 } = {}) => {
+  const live = new Set(), clock = { t: 1_000_000 }, h = { mem, cores, swapFree };
+  const dir = tmpDir("heavy-");
+  const host = { memAvailableMb: () => h.mem, cores: () => h.cores, swapFreeMb: () => h.swapFree };
+  const handle = (pid, cfg = {}) => { live.add(pid); return openHeavy(dir, { pid, alive: (p) => live.has(p), now: () => clock.t, host, cfg }); };
+  return { dir, live, clock, h, handle };
+};
+
+describe("step classes (#4169)", () => {
+  it("installs, checkers, test runners and containers are heavy across ecosystems; metadata calls and the rest are llm", () => {
+    const heavy = [["pnpm", ["install"]], ["npm", ["ci"]], ["yarn", []], ["pnpm", ["--filter", "web", "test"]], ["npm", ["run", "typecheck"]], ["bun", ["test"]],
+      ["npx", ["tsc", "--noEmit"]], ["tsc", ["-p", "."]], ["eslint", ["."]], ["vitest", ["run"]], ["jest", []], ["pytest", ["-q"]], ["mypy", ["src"]],
+      ["cargo", ["test"]], ["cargo", ["--locked", "clippy"]], ["go", ["test", "./..."]], ["docker", ["run", "--rm", "pg"]], ["docker", ["compose", "up"]],
+      ["docker-compose", ["up"]], ["mvn", ["verify"]], ["gradle", ["build"]], ["/usr/bin/tsc", ["-b"]]];
+    for (const [n, a] of heavy) assert.equal(classifyStep(n, a), "heavy", `${n} ${a.join(" ")}`);
+    const llm = [["pnpm", ["--version"]], ["npm", ["ls"]], ["pnpm", []], ["npm", ["view", "x"]], ["tsc", ["--version"]], ["eslint", ["-v"]], ["npx", []],
+      ["cargo", ["--version"]], ["go", ["env"]], ["docker", ["ps"]], ["docker", ["logs", "x"]], ["git", ["status"]], ["node", ["x.js"]], ["claude", ["--print"]]];
+    for (const [n, a] of llm) assert.equal(classifyStep(n, a), "llm", `${n} ${a.join(" ")}`);
+  });
+
+  it("load average is no longer a default admission signal; an explicit max_load_per_core still is", async () => {
+    assert.equal(ADMISSION_DEFAULTS.max_load_per_core, null);
+    const host = { memAvailableMb: () => 8000, freeMb: async () => 8000, tmpPaths: () => ["/tmp"], loadAvg1: () => 17, cores: () => 4 };
+    assert.equal((await checkAdmission({ host })).ok, true, "load 4.25/core does not refuse a lane by default");
+    const r = await checkAdmission({ cfg: { max_load_per_core: 4 }, host });
+    assert.equal(r.ok, false); assert.match(r.detail, /load 4\.3\/core > 4/);
+  });
+
+  it("config: defaults, forge.yaml keys, env overrides; readHeavy parses engine.heavy_*", () => {
+    assert.deepEqual(heavyConfig(), { enabled: true, max: null, step_mem_mb: 2048, reserve_mb: 1024, ramp_s: 60, max_wait_s: 1800 });
+    const c = heavyConfig({ max: 2, step_mem_mb: 3000, enabled: false }, { FORGE_HEAVY_MAX: "5", FORGE_HEAVY_RESERVE_MB: "bad" });
+    assert.equal(c.max, 5); assert.equal(c.step_mem_mb, 3000); assert.equal(c.reserve_mb, 1024); assert.equal(c.enabled, false);
+    const d = tmpDir("heavy-yaml-");
+    writeFileSync(join(d, "forge.yaml"), "engine:\n  heavy_max: 2\n  heavy_step_mem_mb: 2500\n  heavy_enabled: false\n");
+    assert.deepEqual(readHeavy(d), { enabled: false, max: 2, step_mem_mb: 2500 });
+    assert.deepEqual(readHeavy(tmpDir("heavy-none-")), {});
+  });
+});
+
+describe("heavy-step semaphore (#4169)", () => {
+  it("caps live holders at max(1, cores-1) and frees a slot on release or holder death", () => {
+    const { handle, live } = world({ mem: 64000, cores: 4 });
+    const hs = [1, 2, 3, 4].map((p) => handle(100 + p));
+    assert.deepEqual(hs.map((h, i) => h.tryAcquire(`k${i}`, { issue: i }).ok), [true, true, true, false]);
+    assert.match(hs[3].tryAcquire("k3").reason, /heavy cap 3 reached/);
+    hs[0].release("k0");
+    assert.equal(hs[3].tryAcquire("k3").ok, true);
+    live.delete(102); // a holder whose process died is reaped
+    const h5 = handle(105);
+    assert.equal(h5.tryAcquire("k5").ok, true);
+    assert.equal(handle(106, { max: 1 }).max(), 1);
+  });
+
+  it("adapts to free memory: ramping steps count at their reservation, then live MemAvailable decides; swap never counts", () => {
+    const w = world({ mem: 7000, cores: 16, swapFree: 32000 });
+    const a = w.handle(1), b = w.handle(2), c = w.handle(3);
+    assert.equal(a.tryAcquire("a").ok, true);
+    assert.equal(b.tryAcquire("b").ok, true, "7000 − 2048 = 4952 ≥ 3072");
+    const r = c.tryAcquire("c");
+    assert.equal(r.ok, false, "7000 − 4096 = 2904 < 3072; 32 GB of free swap does not help");
+    assert.match(r.reason, /free memory 7000 MB/);
+    w.clock.t += 61_000; // a and b are past the ramp window: their real use is in MemAvailable now
+    w.h.mem = 2500;
+    assert.equal(c.tryAcquire("c").ok, false, "2500 < 3072 with holders: never push the host into swap");
+    w.h.mem = 3100;
+    assert.equal(c.tryAcquire("c").ok, true);
+  });
+
+  it("with no holder one step may run while MemAvailable ≥ reserve, so a step is not starved; below the reserve it waits", () => {
+    const w = world({ mem: 1500, cores: 4 });
+    assert.equal(w.handle(1).tryAcquire("a").ok, true);
+    const w2 = world({ mem: 900, cores: 4 });
+    assert.equal(w2.handle(1).tryAcquire("a").ok, false);
+  });
+
+  it("queues by priority then FIFO: a P0 offered last is granted before queued P2s", () => {
+    const { handle } = world({ mem: 64000, cores: 2 }); // max 1
+    const hold = handle(1), p2a = handle(2), p2b = handle(3), p0 = handle(4);
+    assert.equal(hold.tryAcquire("hold").ok, true);
+    assert.equal(p2a.tryAcquire("p2a", { priority: 2 }).ok, false);
+    assert.equal(p2b.tryAcquire("p2b", { priority: 2 }).ok, false);
+    assert.equal(p0.tryAcquire("p0", { priority: 0 }).ok, false);
+    hold.release("hold");
+    assert.match(p2a.tryAcquire("p2a", { priority: 2 }).reason, /queued behind 1/);
+    assert.equal(p0.tryAcquire("p0", { priority: 0 }).ok, true);
+    p0.release("p0");
+    assert.equal(p2b.tryAcquire("p2b", { priority: 2 }).ok, false, "FIFO within P2: p2a first");
+    assert.equal(p2a.tryAcquire("p2a", { priority: 2 }).ok, true);
+    const st = hold.stats();
+    assert.equal(st.holders, 1); assert.equal(st.queued, 1); assert.equal(st.maxQueued, 3);
+  });
+
+  it("fails open on a corrupt registry; stats is read-only and null when unreadable", () => {
+    const w = world();
+    mkdirSync(w.dir, { recursive: true });
+    writeFileSync(join(w.dir, "heavy.json"), "{not json");
+    const r = w.handle(1).tryAcquire("a");
+    assert.equal(r.ok, true); assert.equal(r.fallback, true);
+    assert.equal(w.handle(1).stats(), null);
+  });
+
+  it("acquireHeavy polls until granted, reports the wait and the longest queue seen; gives up after max_wait_s (ungated)", async () => {
+    const w = world({ mem: 64000, cores: 2 });
+    const holder = w.handle(1);
+    holder.tryAcquire("hold");
+    const h = w.handle(2);
+    let polls = 0;
+    const g = await acquireHeavy(h, { phase: "precheck" }, { pid: 2, now: () => w.clock.t, sleep: async (ms) => { w.clock.t += ms; if (++polls === 3) holder.release("hold"); } });
+    assert.equal(g.waitMs, 6000); assert.equal(g.queued, 1); assert.equal(h.stats().holders, 1);
+    g.release();
+    assert.equal(h.stats().holders, 0);
+    holder.tryAcquire("hold2");
+    const h2 = w.handle(3, { max_wait_s: 10 });
+    const t = await acquireHeavy(h2, {}, { pid: 3, now: () => w.clock.t, sleep: async (ms) => { w.clock.t += ms; } });
+    assert.equal(t.timedOut, true); assert.equal(h2.stats().queued, 0, "a timed-out waiter is withdrawn");
+  });
+
+  it("R4 simulation: 20 lanes on a 4-core/16 GB host at load 17 are all admitted, none deferred on load; ≤3 heavy steps at once", async () => {
+    const w = world({ mem: 16384, cores: 4 });
+    const lanes = 20, laneRss = 265, tscRss = 2048;
+    const admitHost = { memAvailableMb: () => w.h.mem, freeMb: async () => 50000, tmpPaths: () => ["/tmp"], loadAvg1: () => 17, cores: () => 4 };
+    w.h.mem = 16384 - lanes * laneRss; // every lane's agent is resident: 11084 MB left
+    const admitted = await Promise.all(Array.from({ length: lanes }, () => checkAdmission({ host: admitHost })));
+    assert.equal(admitted.filter((a) => a.ok).length, lanes, "all 20 lanes admitted into their LLM phases");
+    // Each lane runs one heavy step; a granted step consumes its tsc RSS once past the ramp window.
+    const hs = Array.from({ length: lanes }, (_, i) => w.handle(1000 + i));
+    const holding = new Set();
+    let peak = 0, done = 0;
+    for (let tick = 0; done < lanes && tick < 1000; tick++) {
+      for (let i = 0; i < lanes; i++) {
+        if (holding.has(i) || hs[i].done) continue;
+        if (hs[i].tryAcquire(`s${i}`, { issue: i }).ok) holding.add(i);
+      }
+      peak = Math.max(peak, holding.size);
+      w.clock.t += 61_000;
+      w.h.mem = 16384 - lanes * laneRss - holding.size * tscRss;
+      for (const i of [...holding].slice(0, 1)) { hs[i].release(`s${i}`); hs[i].done = true; holding.delete(i); done++; }
+      w.h.mem = 16384 - lanes * laneRss - holding.size * tscRss;
+    }
+    assert.equal(done, lanes, "every heavy step eventually ran");
+    assert.ok(peak <= 3 && peak >= 2, `2-3 heavy steps at once on 4 cores (peak ${peak})`);
+    // Less free memory shrinks heavy concurrency to what fits.
+    const w2 = world({ mem: 5000, cores: 4 });
+    const g = [1, 2, 3].map((p) => w2.handle(p).tryAcquire(`k${p}`).ok);
+    assert.deepEqual(g, [true, false, false], "5000 MB fits one 2 GB step plus the 1 GB reserve, not two");
+  });
+});
+
+describe("heavy shims and the run wrapper (#4169)", () => {
+  it("shims are written only for heavy names on PATH and never resolve to themselves", async () => {
+    const d = tmpDir("heavy-shim-"), real = join(d, "real"), bin = join(d, "bin");
+    mkdirSync(real, { recursive: true });
+    for (const n of ["tsc", "pnpm", "git"]) { writeFileSync(join(real, n), "#!/bin/sh\n"); chmodSync(join(real, n), 0o755); }
+    const names = await writeHeavyShims(bin, { path: `${bin}:${real}` });
+    assert.deepEqual(names.sort(), ["pnpm", "tsc"]);
+    assert.ok(!existsSync(join(bin, "git")));
+    const s = readFileSync(join(bin, "tsc"), "utf8");
+    assert.match(s, new RegExp(`-- '${real}/tsc' "\\$@"`));
+    assert.ok(!s.includes(`'${bin}/tsc'`));
+    assert.deepEqual(await writeHeavyShims(join(d, "none"), { path: join(d, "empty") }), []);
+    assert.ok(HEAVY_BINS.includes("docker") && HEAVY_BINS.includes("pytest"));
+    assert.match(heavyShimScript("x", "/r/x", { node: "/n", script: "/s" }), /^#!\/bin\/sh\n[\s\S]*exec '\/n' '\/s' run --name 'x' -- '\/r\/x' "\$@"\n$/);
+  });
+
+  it("run: heavy steps hold a slot for their duration, get FORGE_HEAVY_HELD and per-holder parallelism, record the wait; llm and nested pass through", async () => {
+    const w = world({ mem: 64000, cores: 8 });
+    const waitsFile = join(w.dir, "waits.jsonl");
+    const calls = [];
+    const env = { FORGEDOCK_SCHED_DIR: w.dir, FORGE_HEAVY_WAITS: waitsFile, FORGE_LANE_PHASE: "implement", FORGE_LANE_PRIORITY: "1", FORGE_LANE_ISSUE: "7" };
+    const open = (dir, o) => { w.live.add(process.pid); return openHeavy(dir, { ...o, alive: (p) => w.live.has(p) }); };
+    const host = { memAvailableMb: () => 64000, cores: () => 8 };
+    const run = async (cmd, args, e) => { calls.push({ cmd, args, held: e.FORGE_HEAVY_HELD, par: e.FORGE_HOST_PARALLELISM, holders: openHeavy(w.dir, { host }).stats().holders }); return { code: 3, signal: null }; };
+    assert.deepEqual(await runWrapped(["run", "--name", "tsc", "--", "/r/tsc", "--noEmit"], { env, open, run, host }), { code: 3, signal: null });
+    assert.deepEqual(calls[0], { cmd: "/r/tsc", args: ["--noEmit"], held: "1", par: "8", holders: 1 });
+    assert.equal(openHeavy(w.dir, { host }).stats().holders, 0, "released after the step");
+    assert.deepEqual(sumWaits(readFileSync(waitsFile, "utf8")), { waits: { implement: JSON.parse(readFileSync(waitsFile, "utf8")).waitMs }, queueMax: 1 });
+    await runWrapped(["run", "--name", "tsc", "--", "/r/tsc", "--version"], { env, open, run, host });
+    await runWrapped(["run", "--name", "pnpm", "--", "/r/pnpm", "install"], { env: { ...env, FORGE_HEAVY_HELD: "1" }, open, run, host });
+    assert.deepEqual(calls.slice(1).map((c) => [c.held, c.holders]), [[undefined, 0], ["1", 0]], "llm and nested calls take no slot");
+    await runWrapped(["run", "--name", "tsc", "--", "/r/tsc"], { env: { ...env, FORGE_HOST_PARALLELISM: "2", FORGE_HEAVY_PARALLELISM_PINNED: "1" }, open, run, host });
+    assert.equal(calls.at(-1).par, "2", "an operator-set FORGE_HOST_PARALLELISM wins");
+    await assert.rejects(runWrapped(["run", "--name", "x"], { env, open, run, host }), /usage/);
+  });
+
+  it("sumWaits sums per phase and ignores bad lines; formatWaitSummary renders the batch-report line", () => {
+    assert.deepEqual(sumWaits('{"phase":"implement","waitMs":1000,"queued":2}\nnot json\n{"phase":"implement","waitMs":500}\n{"phase":"fix","waitMs":60000,"queued":4}\n'),
+      { waits: { implement: 1500, fix: 60000 }, queueMax: 4 });
+    const rows = [{ issue: 1, waits: { implement: 180000, setup: 6000 }, heavyQueueMax: 2 }, { issue: 2, waits: { implement: 12000 }, heavyQueueMax: 5 }, { issue: 3 }];
+    assert.equal(formatWaitSummary(rows, { queued: 1, maxQueued: 9 }), "waits by phase: implement 3.2m, setup 0.1m; heavy queue: now 1, max 5");
+    assert.equal(formatWaitSummary([{ issue: 3 }], null), null);
+    assert.equal(formatWaitSummary([{ issue: 3 }], { queued: 0 }), null, "no waits and an empty queue print no line");
+    assert.equal(formatWaitSummary([{ issue: 3 }], { queued: 2 }), "waits by phase: none; heavy queue: now 2, max 0");
+  });
+});