forgedock 1.36.0 → 1.37.0

package/bin/lean/guards.test.mjs

@@ -0,0 +1,177 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildGuard, guardTests, parseHunks, renderGuard, parseGuard, guardIssue, listGuards, backfill, guardsCli, readIndex, guardAfterMerge, historyPreserve, withHistoryRows, writeIndex } from "./guards.mjs";
+import { renderContract } from "./render.mjs";
+import { tmpDir } from "../tests/_tmp.mjs";
+
+const DIFF = `diff --git a/src/a.mjs b/src/a.mjs
+--- a/src/a.mjs
++++ b/src/a.mjs
+@@ -10,2 +10,3 @@ export function fixed() {
+-x
++y
++z
+@@ -30 +31,0 @@ function other() {
+-gone
+diff --git a/test/a.test.mjs b/test/a.test.mjs
+--- a/test/a.test.mjs
++++ b/test/a.test.mjs
+@@ -1,0 +2,3 @@
++t
+`;
+const nodeContract = { repro_test: { path: "test/a.test.mjs", id: "fixed keeps x", command: "node --test test/a.test.mjs" }, validate: [{ id: "V1", command: "node --test test/a.test.mjs --test-name-pattern=\"fixed keeps x\"" }] };
+const pyContract = { repro_test: { path: "tests/test_a.py", command: "pytest -q tests/test_a.py::test_fixed" }, validate: [{ id: "V1", command: "pytest -q tests/test_a.py -k fixed" }, { id: "V2", command: "pytest -q tests/test_b.py" }] };
+
+test("node --test fixture: file and id, hunks exclude test files with symbol and deletion anchor", () => {
+  const { guard } = buildGuard({ issue: 7, title: "Fix  x\nbug", pr: 9, mergeSha: "abc", contract: nodeContract, diff: DIFF });
+  assert.deepEqual(guard.tests, [{ path: "test/a.test.mjs", ids: ["fixed keeps x"] }]);
+  assert.deepEqual(guard.hunks, [{ file: "src/a.mjs", start: 10, end: 12, symbol: "export function fixed() {" }, { file: "src/a.mjs", start: 32, end: 32, symbol: "function other() {" }]);
+  assert.equal(guard.why, "Fix x bug");
+});
+
+test("pytest fixture: ::ids and -k, every test file named", () => {
+  const t = guardTests(pyContract);
+  assert.deepEqual(t.find((x) => x.path === "tests/test_a.py").ids.sort(), ["fixed", "test_fixed"]);
+  assert.deepEqual(t.find((x) => x.path === "tests/test_b.py").ids, []); // file granularity
+});
+
+test("a contract without a test yields no guard and says why", () => {
+  assert.match(buildGuard({ issue: 1, contract: { repro_test: "none", repro_test_reason: "docs only", validate: [{ command: "npm run lint" }] } }).reason, /repro_test none \(docs only\)/);
+  assert.match(buildGuard({ issue: 1, contract: { validate: [] } }).reason, /names no test/);
+});
+
+test("render/parse round trip survives '-->', '--!>' and '<x>' in a field", () => {
+  const g = { v: 1, issue: 3, why: "a --> b --!> c <x>", tests: [{ path: "t --!> <y>", ids: ["--!>"] }], hunks: [] };
+  const body = renderGuard(g);
+  const inner = body.slice(0, -" -->".length);
+  assert.ok(body.endsWith(" -->"));
+  assert.equal(inner.includes(">"), false); // no terminator variant can appear before the closing -->
+  assert.deepEqual(parseGuard(body), g);
+});
+
+function fakeGh({ contract, comments = [], title = "Fix the thing" }) {
+  const posted = [];
+  const body = `<!-- FORGE:CONTRACT -->\n${renderContract({ requirements: [], deliverables: [], preserve: [], validate: [], ...contract }, "abcdef123456")}`;
+  const gh = async (a) => {
+    if (a[0] === "issue" && a[1] === "view") return JSON.stringify({ number: 7, title, comments: [{ body }, ...comments, ...posted.map((b) => ({ body: b }))] });
+    if (a[0] === "pr" && a[1] === "view") return JSON.stringify({ number: 9, mergeCommit: { oid: "deadbeefcafe" } });
+    if (a[0] === "issue" && a[1] === "comment") { posted.push(a[a.indexOf("--body") + 1]); return ""; }
+    throw new Error(`unexpected gh ${a.join(" ")}`);
+  };
+  return { gh, posted };
+}
+const git = async (a) => { assert.deepEqual(a.slice(0, 2), ["diff", "-U0"]); assert.ok(a.includes("deadbeefcafe^1")); return DIFF; };
+
+test("guardIssue posts exactly one FORGE:GUARD and is idempotent on rerun", async () => {
+  const f = fakeGh({ contract: nodeContract });
+  const r1 = await guardIssue({ gh: f.gh, git, repo: "o/r", issue: 7, pr: 9 });
+  assert.ok(r1.posted);
+  const r2 = await guardIssue({ gh: f.gh, git, repo: "o/r", issue: 7, pr: 9 });
+  assert.ok(r2.exists);
+  assert.equal(f.posted.length, 1);
+  assert.equal(parseGuard(f.posted[0]).merge_sha, "deadbeefcafe");
+});
+
+test("guardIssue: no test posts nothing; unavailable merge commit is a logged skip", async () => {
+  const f = fakeGh({ contract: { repro_test: "none", repro_test_reason: "n/a" } });
+  assert.ok((await guardIssue({ gh: f.gh, git, repo: "o/r", issue: 7, pr: 9 })).skipped);
+  assert.equal(f.posted.length, 0);
+  const g = fakeGh({ contract: nodeContract });
+  const r = await guardIssue({ gh: g.gh, git: async () => { throw new Error("bad object"); }, repo: "o/r", issue: 7, pr: 9 });
+  assert.match(r.reason, /not available locally/);
+});
+
+test("listGuards filters by hunk file, test file or directory", () => {
+  const gs = [buildGuard({ issue: 7, contract: nodeContract, diff: DIFF }).guard, buildGuard({ issue: 8, contract: pyContract, diff: "" }).guard];
+  assert.deepEqual(listGuards(gs, { path: "src/a.mjs" }).map((g) => g.issue), [7]);
+  assert.deepEqual(listGuards(gs, { path: "tests" }).map((g) => g.issue), [8]);
+  assert.deepEqual(listGuards(gs, { path: "nope.js" }), []);
+  assert.equal(listGuards(gs).length, 2);
+});
+
+test("backfill guards merged lanes and logs why a lane without a test yields none", async () => {
+  const withTest = fakeGh({ contract: nodeContract }), noTest = fakeGh({ contract: { validate: [] } });
+  const by = { 1: withTest, 2: noTest };
+  const gh = async (a) => {
+    if (a[0] === "issue" && a[1] === "list") return JSON.stringify([{ number: 1 }, { number: 2 }]);
+    if (a[0] === "pr" && a[1] === "list") return JSON.stringify([{ number: 9, body: `Closes #${a.join(" ").match(/#(\d+) in:body/)[1]}`, mergeCommit: { oid: "deadbeefcafe" } }]);
+    return by[a[2]].gh(a);
+  };
+  const logs = [];
+  const r = await backfill({ gh, git, repo: "o/r", since: "2026-01-01", log: (m) => logs.push(m) });
+  assert.deepEqual(r.posted, [1]);
+  assert.equal(r.skipped[0].issue, 2);
+  assert.match(logs[0], /names no test/);
+  assert.equal(withTest.posted.length, 1);
+});
+
+test("guards list prints guards for a path and caches the index; falls back to it offline", async () => {
+  const root = tmpDir("guards-");
+  {
+    const g = buildGuard({ issue: 7, title: "t", contract: nodeContract, diff: DIFF }).guard;
+    const gh = async () => JSON.stringify([{ number: 7, comments: [{ body: renderGuard(g) }] }]);
+    const out = [];
+    assert.equal(await guardsCli(["list", "--path", "src/a.mjs"], { gh, repo: "o/r", print: (m) => out.push(m), root }), 0);
+    assert.match(out[0], /#7/);
+    assert.equal(readIndex("o/r", { root }).length, 1);
+    const off = [];
+    await guardsCli(["list", "--path", "test/a.test.mjs"], { gh: async () => { throw new Error("offline"); }, repo: "o/r", print: (m) => off.push(m), root });
+    assert.match(off[0], /#7/);
+  }
+});
+test("parseHunks ignores deleted files", () => {
+  assert.deepEqual(parseHunks("--- a/x.js\n+++ /dev/null\n@@ -1,2 +0,0 @@\n"), []);
+});
+test("guardAfterMerge fetches the bare branch (not origin/<lane>) and the merge sha when absent locally", async () => {
+  const calls = [];
+  let have = false;
+  const body = `<!-- FORGE:CONTRACT -->\n${renderContract({ requirements: [], deliverables: [], preserve: [], ...nodeContract }, "abcdef123456")}`;
+  const io = {
+    gh: async (a) => a[0] === "issue" ? JSON.stringify({ number: 9, title: "t", comments: [{ body }] }) : a[0] === "pr" ? JSON.stringify({ number: 3, mergeCommit: { oid: "abc123" } }) : "",
+    git: async (a) => { calls.push(a.join(" ")); if (a[0] === "diff") { if (!have) throw new Error("bad object"); return DIFF; } if (a.join(" ") === "fetch origin abc123") have = true; return ""; },
+  };
+  const r = await guardAfterMerge({ io, repo: "o/r", issue: 9, pr: 3, cwd: "/x", base: "origin/staging" });
+  assert.ok(calls.includes("fetch origin staging"));
+  assert.ok(!calls.some((c) => c.includes("origin/staging")));
+  assert.ok(r.posted, JSON.stringify(r));
+});
+
+const G = (issue, file, over = {}) => ({ v: 1, issue, pr: issue + 100, merge_sha: "s", tests: [{ path: "test/x.test.mjs", ids: [] }], hunks: [{ file, start: 1, end: 2, symbol: null }], why: `fix ${issue}`, ...over });
+test("historyPreserve: guarded deliverable yields rows, unguarded none, own issue skipped", () => {
+  const guards = [G(5, "src/a.mjs"), G(6, "lib/other.mjs"), G(7, "src/a.mjs")];
+  const rows = historyPreserve({ guards, deliverables: [{ path: "src/a.mjs" }], issue: 7 });
+  assert.deepEqual(rows, [{ id: "H1", what: "fix 5 (#5, PR #105)", source: "guard" }]);
+  assert.deepEqual(historyPreserve({ guards, deliverables: [{ path: "src/zzz/q.mjs" }], issue: 1 }), []);
+});
+test("historyPreserve: deterministic under input order, capped at 5, proximity then recency", () => {
+  const guards = [G(1, "lib/z.mjs"), G(2, "src/a.mjs"), G(3, "src/b.mjs"), G(4, "src/c.mjs"), G(5, "src/d.mjs"), G(6, "src/e.mjs"), G(8, "x/y.mjs", { tests: [{ path: "src/a.mjs", ids: [] }] }), G(9, "src/a.mjs")];
+  const d = [{ path: "src/a.mjs" }];
+  const a = historyPreserve({ guards, deliverables: d, issue: 99 });
+  const b = historyPreserve({ guards: [...guards].reverse(), deliverables: d, issue: 99 });
+  assert.deepEqual(a, b);
+  assert.equal(a.length, 5);
+  assert.deepEqual(a.map((r) => r.what.match(/#(\d+),/)[1]), ["9", "2", "8", "6", "5"], "hunk match first, then test match, then same directory by recency");
+  assert.deepEqual(a.map((r) => r.id), ["H1", "H2", "H3", "H4", "H5"]);
+});
+test("withHistoryRows reads the local index; no index or no match returns the same contract", () => {
+  const root = tmpDir("guards-hist-");
+  const c = { requirements: [], deliverables: [{ id: "D1", path: "src/a.mjs" }], preserve: [{ id: "P1", what: "keep" }, { id: "H9", what: "old", source: "guard" }], validate: [] };
+  assert.equal(withHistoryRows(c, { repo: "o/r", issue: 1, root }), c, "no index");
+  writeIndex("o/r", [G(5, "src/a.mjs")], { root });
+  const w = withHistoryRows(c, { repo: "o/r", issue: 1, root });
+  assert.deepEqual(w.preserve.map((p) => p.id), ["P1", "H1"]);
+  const none = { ...c, deliverables: [{ id: "D1", path: "docs/q.md" }] };
+  assert.equal(withHistoryRows(none, { repo: "o/r", issue: 1, root }), none);
+});
+test("guardAfterMerge adds the posted guard to an existing local index only", async () => {
+  const root = tmpDir("guards-idx-");
+  const body = `<!-- FORGE:CONTRACT -->\n${renderContract({ requirements: [], deliverables: [], preserve: [], ...nodeContract }, "abcdef123456")}`;
+  const io = { gh: async (a) => a[0] === "issue" ? JSON.stringify({ number: 9, title: "t", comments: [{ body }] }) : a[0] === "pr" ? JSON.stringify({ number: 3, mergeCommit: { oid: "abc123" } }) : "", git: async (a) => (a[0] === "diff" ? DIFF : "") };
+  assert.ok((await guardAfterMerge({ io, repo: "o/r", issue: 9, pr: 3, cwd: "/x", root })).posted);
+  assert.equal(readIndex("o/r", { root }), null, "no index is not created from one guard");
+  writeIndex("o/r", [G(5, "src/a.mjs")], { root });
+  await guardAfterMerge({ io, repo: "o/r", issue: 9, pr: 3, cwd: "/x", root });
+  assert.deepEqual(readIndex("o/r", { root }).map((g) => g.issue), [5, 9]);
+});

package/bin/lean/heavy.mjs

@@ -14,12 +14,13 @@
  * 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).
+ * `heavy.mjs run --name <n> -- <abs-real-bin> args...` (nested calls pass through via FORGE_HEAVY_HELD). A wrapper that
+ * re-resolves the name back to the shim is cut off by FORGE_HEAVY_CHAIN (`name:cmd|...`, see `runWrapped`, #4680).
  */
 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 { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { writeAtomic } from "./batch.mjs";
 import { schedDir, pidAlive, DEFAULT_PRIORITY } from "./sched.mjs";
@@ -249,15 +250,34 @@ 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`;
+  return `${SHIM_HEADER}export FORGE_HEAVY_SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"\nexec ${q(node)} ${q(script)} run --name ${q(name)} -- ${q(real)} "$@"\n`;
 }
 
+/** True when `text` is a shell-style script that looks `name` up on PATH itself (a pass-through wrapper, #4680). */
+export function isPassThroughWrapper(text, name) {
+  const t = String(text ?? "");
+  return t.startsWith("#!") && t.includes(name) && /\b(command\s+-v|which|type\s+-p)\b/.test(t);
+}
+const head = (p) => { try { return readFileSync(p, "utf8").slice(0, 4096); } catch { return ""; } };
+
 /**
  * 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.
+ * a shim never calls itself). A target that is a pass-through wrapper is skipped for the next match past its dir, or the
+ * shim is skipped with a `warn` line when none is left (#4680). 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);
+export async function writeHeavyShims(binDir, { path = process.env.PATH ?? "", find = which, read = head, warn = (m) => process.stderr.write(`${m}\n`), node, script, mkdirp = (d) => mkdirSync(d, { recursive: true }), writeShim = (p, t) => { writeFileSync(p, t); chmodSync(p, 0o755); } } = {}) {
+  const found = [];
+  for (const n of HEAVY_BINS) {
+    const skip = [binDir];
+    let real = find(n, path, skip);
+    while (real && isPassThroughWrapper(read(real), n)) {
+      skip.push(dirname(real));
+      const next = find(n, path, skip);
+      if (!next) warn(`forgedock heavy: ${n} at ${real} is a PATH pass-through wrapper with no real binary behind it; shim skipped`);
+      real = next;
+    }
+    if (real) found.push([n, real]);
+  }
   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 } : {}) }));
@@ -277,17 +297,43 @@ export function sumWaits(text, waits = {}) {
   return { waits, queueMax };
 }
 
+export const SHIM_LOOP_MAX = 4;
+/**
+ * Re-entry guard (#4680): FORGE_HEAVY_CHAIN lists `name:cmd` per shim run. A repeat of the same name+cmd where cmd is a
+ * pass-through wrapper means it sent the call back to the shim; a repeat of a real binary is a legitimate nested call
+ * (`npm run` inside an npm script) and passes through unchanged, unrecorded. For a wrapper, resolve the next PATH match past the shim dir and every chain dir; none, or more
+ * than SHIM_LOOP_MAX entries, is a typed `env.shim_loop` error and nothing is spawned. Returns {cmd, env} or {error}.
+ */
+export function guardChain(name, cmd, env, read = head) {
+  const chain = String(env.FORGE_HEAVY_CHAIN ?? "").split("|").filter(Boolean);
+  const dirs = chain.map((e) => dirname(e.slice(e.indexOf(":") + 1)));
+  const loop = (why) => ({ error: `env.shim_loop: ${name} ${why} (PATH dirs: ${[env.FORGE_HEAVY_SHIM_DIR, ...dirs].filter(Boolean).join(", ") || "none"})` });
+  const repeat = chain.includes(`${name}:${cmd}`);
+  if (repeat && !isPassThroughWrapper(read(cmd), name)) return { cmd, env };
+  if (chain.length >= SHIM_LOOP_MAX) return loop(`re-entered the heavy shim more than ${SHIM_LOOP_MAX} times`);
+  if (repeat) {
+    const next = which(name, env.PATH ?? "", [env.FORGE_HEAVY_SHIM_DIR, ...dirs].filter(Boolean));
+    if (!next) return loop(`re-entered via ${cmd} and no other ${name} is on PATH`);
+    cmd = next;
+  }
+  return { cmd, env: { ...env, FORGE_HEAVY_CHAIN: [...chain, `${name}:${cmd}`].join("|") } };
+}
+
 /**
  * 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 } = {}) {
+export async function runWrapped(argv, { env: env0 = process.env, open = openHeavy, run = spawnInherit, host } = {}) {
+  let env = env0;
   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);
+  let [cmd, ...args] = argv.slice(sep + 1);
   const c = heavyConfig({}, env);
+  const g0 = guardChain(name, cmd, env);
+  if (g0.error) { process.stderr.write(`${g0.error}\n`); return { code: 126, signal: null }; }
+  cmd = g0.cmd; env = g0.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 });

package/bin/lean/heavy.test.mjs

@@ -2,10 +2,11 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
 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, isHeavyProcess } from "./heavy.mjs";
+import { guardChain, isPassThroughWrapper, SHIM_LOOP_MAX, classifyStep, heavyConfig, openHeavy, acquireHeavy, writeHeavyShims, heavyShimScript, sumWaits, runWrapped, HEAVY_BINS, isHeavyProcess } from "./heavy.mjs";
 import { checkAdmission, ADMISSION_DEFAULTS } from "./admission.mjs";
 import { formatAlertLines, formatWaitSummary } from "./orchestrate.mjs";
 import { readHeavy } from "../engine-cli.mjs";
@@ -235,3 +236,75 @@ describe("heavy shims and the run wrapper (#4169)", () => {
       ["ALERTS", 'deferred-to-ci: 40% (4/10 lanes, threshold 30%), e.g. "npx tsc"']);
   });
 });
+
+describe("shim re-entry through a pass-through wrapper (#4680)", () => {
+  it("shim with pass-through wrapper runs once", async () => {
+    const d = tmpDir("heavy-wrap-"), wrap = join(d, "wrap"), real = join(d, "real"), bin = join(d, "bin"), log = join(d, "log");
+    mkdirSync(wrap, { recursive: true }); mkdirSync(real, { recursive: true });
+    writeFileSync(join(wrap, "docker"), `#!/bin/sh\necho w >> ${log}\nexec "$(PATH="\${PATH#${wrap}:}" command -v docker)" "$@"\n`);
+    writeFileSync(join(real, "docker"), `#!/bin/sh\necho r >> ${log}\necho "Docker version 1"\n`);
+    for (const dir of [wrap, real]) chmodSync(join(dir, "docker"), 0o755);
+    const path = `${wrap}:${bin}:${real}`;
+    const warnings = [];
+    assert.deepEqual(await writeHeavyShims(bin, { path, warn: (m) => warnings.push(m) }), ["docker"]);
+    assert.match(readFileSync(join(bin, "docker"), "utf8"), new RegExp(`-- '${real}/docker' "\\$@"`), "wrapper skipped at write time, real binary baked");
+    assert.deepEqual(warnings, []);
+    // Force the runtime guard: bake the wrapper itself, as a shim written before the wrapper appeared would.
+    writeFileSync(join(bin, "docker"), heavyShimScript("docker", join(wrap, "docker")));
+    chmodSync(join(bin, "docker"), 0o755);
+    const r = spawnSync(join(bin, "docker"), ["--version"], { env: { ...process.env, PATH: `${bin}:${wrap}:${real}:/usr/bin:/bin`, FORGE_HEAVY_DISABLED: "1" }, encoding: "utf8", timeout: 20000 });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /Docker version 1/);
+    assert.equal(readFileSync(log, "utf8"), "w\nr\n", "wrapper and real binary each ran once (two shim node processes at most)");
+  });
+
+  it("a name+cmd seen twice resolves past the shim and chain dirs; no match or depth above the cap is env.shim_loop", () => {
+    const d = tmpDir("heavy-chain-"), a = join(d, "a"), b = join(d, "b"), s = join(d, "s");
+    for (const x of [a, b, s]) { mkdirSync(x, { recursive: true }); writeFileSync(join(x, "tsc"), '#!/bin/sh\nexec "$(command -v tsc)" "$@"\n'); chmodSync(join(x, "tsc"), 0o755); }
+    const env = { PATH: [s, a, b].join(":"), FORGE_HEAVY_SHIM_DIR: s };
+    const first = guardChain("tsc", join(a, "tsc"), env);
+    assert.equal(first.cmd, join(a, "tsc")); assert.equal(first.env.FORGE_HEAVY_CHAIN, `tsc:${join(a, "tsc")}`);
+    const again = guardChain("tsc", join(a, "tsc"), first.env);
+    assert.equal(again.cmd, join(b, "tsc"));
+    assert.equal(again.env.FORGE_HEAVY_CHAIN, `tsc:${join(a, "tsc")}|tsc:${join(b, "tsc")}`);
+    const none = guardChain("tsc", join(b, "tsc"), { ...again.env, PATH: [s, a, b].join(":") });
+    assert.match(none.error, /^env\.shim_loop: tsc .*no other tsc/);
+    const deep = guardChain("tsc", "/x/tsc", { ...env, FORGE_HEAVY_CHAIN: Array.from({ length: SHIM_LOOP_MAX }, (_, i) => `tsc:/d${i}/tsc`).join("|") });
+    assert.match(deep.error, /^env\.shim_loop: tsc re-entered .*more than 4 times.*\/d0/);
+  });
+
+  it("a nested call to the same real binary (not a wrapper) passes through at any depth, unrecorded", async () => {
+    const real = "/home/u/.nvm/bin/npm", spawned = [];
+    const run = async (cmd, a, e) => { spawned.push([cmd, e.FORGE_HEAVY_CHAIN]); return { code: 0, signal: null }; };
+    const chain = Array.from({ length: SHIM_LOOP_MAX - 1 }, (_, i) => `npm:/d${i}/npm`).concat(`npm:${real}`).join("|");
+    for (const FORGE_HEAVY_CHAIN of [`npm:${real}`, chain]) {
+      const env = { PATH: "/shim:/home/u/.nvm/bin", FORGE_HEAVY_CHAIN, FORGE_HEAVY_HELD: "1" };
+      assert.equal((await runWrapped(["run", "--name", "npm", "--", real, "run", "build"], { env, run })).code, 0);
+    }
+    assert.equal(chain.split("|").length, SHIM_LOOP_MAX);
+    assert.deepEqual(spawned, [[real, `npm:${real}`], [real, chain]]);
+  });
+
+  it("runWrapped refuses to spawn on a loop and records the chain otherwise", async () => {
+    const spawned = [];
+    const run = async (cmd, a, e) => { spawned.push([cmd, e.FORGE_HEAVY_CHAIN]); return { code: 0, signal: null }; };
+    const env = { FORGE_HEAVY_HELD: "1", FORGE_HEAVY_CHAIN: Array.from({ length: SHIM_LOOP_MAX }, (_, i) => `x:/d${i}/x`).join("|") };
+    assert.equal((await runWrapped(["run", "--name", "x", "--", "/r/x"], { env, run })).code, 126);
+    assert.deepEqual(spawned, []);
+    await runWrapped(["run", "--name", "x", "--", "/r/x"], { env: { FORGE_HEAVY_HELD: "1" }, run });
+    assert.deepEqual(spawned, [["/r/x", "x:/r/x"]]);
+  });
+
+  it("wrapper detection: PATH-lookup shell scripts only; a wrapper with nothing behind it is skipped with a warning", async () => {
+    assert.ok(isPassThroughWrapper('#!/bin/sh\nexec "$(command -v docker)" "$@"', "docker"));
+    assert.ok(!isPassThroughWrapper("#!/bin/sh\necho hi\n", "docker"));
+    assert.ok(!isPassThroughWrapper("\x7fELF command -v docker", "docker"));
+    const d = tmpDir("heavy-skip-"), wrap = join(d, "wrap"), bin = join(d, "bin");
+    mkdirSync(wrap, { recursive: true });
+    writeFileSync(join(wrap, "docker"), '#!/bin/sh\nexec "$(command -v docker)" "$@"\n'); chmodSync(join(wrap, "docker"), 0o755);
+    const warnings = [];
+    assert.deepEqual(await writeHeavyShims(bin, { path: `${bin}:${wrap}`, warn: (m) => warnings.push(m) }), []);
+    assert.equal(warnings.length, 1); assert.match(warnings[0], /docker .*wrapper/);
+    assert.ok(!existsSync(join(bin, "docker")));
+  });
+});

package/bin/lean/hostkill.mjs

@@ -3,6 +3,6 @@
  * or status 143/137 and no timer of ours fired (our own kills throw CLI_TIMEOUT / CLI_IDLE / CLI_CONTEXT / CLI_TURNS).
  */
 export function isExternalKill(e) {
-  if (e?.code !== "CLI_BACKEND_FAILED") return false;
+  if (e?.code !== "CLI_BACKEND_FAILED") return false; // #4690: a scope-limit stop is CLI_LANE_LIMIT, never a host kill
   return e.signal === "SIGTERM" || e.signal === "SIGKILL" || e.status === 143 || e.status === 137;
 }