heyspex 0.1.0 → 0.2.0

package/dev-factory/engine/worktree.mjs

@@ -0,0 +1,740 @@
+#!/usr/bin/env node
+// dev-factory/engine/worktree.mjs
+// ENGINE — per-task git worktree isolation + deterministic gate.
+// Task: HS-OBJC-W6AD-TASK-per-task-git-worktree-isolation-baseline (epic HS-UB1R).
+//
+// Lifted from the proven dev-factory/phase2-loop.mjs so the loop controller (controller.mjs) can run each
+// task's build + gate inside an ISOLATED worktree: the gate sees ONLY that task's diff, the live tree / dev
+// server / Neon DB are never touched, and the net-new tsc/test baseline is captured in the clean tree.
+//
+// Windows-safe (the hard-won lessons):
+//   - node_modules is JUNCTIONED to the monorepo root (hoisted toolchain — Node resolution walks up) AND the
+//     workspace — never copied.
+//   - git runs with core.longpaths=true so deep specs/ filenames don't trip MAX_PATH (260).
+//   - teardown removes the junction LINKS first, THEN `git worktree remove` — NEVER recurse through a junction
+//     (that would delete the real node_modules).
+//
+// API:
+//   const ctx = makeCtx({ repo?, spex?, worktreeRoot? });
+//   const wt   = setupWorktree(ctx, label);                       // → abs worktree path (node_modules junctioned)
+//   const base = baselineTsc(ctx, wt);                            // → { count } net-new-error baseline (clean tree)
+//   const tbase = baselineTest(ctx, wt, testRel);                 // → { pass } RED-BASELINE pre-check (HS-AY5K):
+//                                                                  //   runs testRel (auto-routed node:test/vitest) against
+//                                                                  //   the UNMODIFIED tree — pass:false means the gate can
+//                                                                  //   never go green regardless of the candidate code.
+//   const res  = runGate(ctx, wt, { target, test }, code, base);  // target/test REPO-ROOT-relative; write→tsc(≤baseline)→
+//                                                                  //   test(auto-routed node:test / plain self-test script / vitest)→restore
+//   teardownWorktree(ctx, wt);                                    // links-first, then git worktree remove
+//
+// Self-test (NO models — proves the isolation plumbing, the deterministic gate's foundation):
+//   node dev-factory/engine/worktree.mjs --self-test
+
+import { symlinkSync, existsSync, lstatSync, rmdirSync, rmSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
+
+// Liveness marker written into every worktree at setup. The startup sweep uses it to tell an
+// ACTIVE concurrent worktree (owner process still alive → leave it) from a STRANDED one an
+// interrupted run left behind (owner dead, or no marker at all → safe to reclaim). Without this,
+// a blanket sweep would delete a sibling build's live worktree.
+export const OWNER_FILE = ".hsewt-owner.json";
+
+// Is a process still running? process.kill(pid, 0) sends no signal — it throws ESRCH if the pid
+// is gone, and succeeds (or throws EPERM, which still means "exists") if it is alive. Works on win32.
+export function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === "EPERM"; }
+}
+
+/** Build the context the worktree functions thread through. All paths absolute. */
+export function makeCtx(opts = {}) {
+  const repo = resolve(opts.repo || join(__dirname, "..", ".."));
+  const spex = opts.spex || "spex-console";
+  const worktreeRoot = resolve(opts.worktreeRoot
+    || (process.env.USERPROFILE ? join(process.env.USERPROFILE, ".hsewt") : join(repo, ".hsewt")));
+  return {
+    repo, spex, worktreeRoot,
+    tscTimeout: opts.tscTimeout ?? 180000,
+    testTimeout: opts.testTimeout ?? 120000,
+    gitTimeout: opts.gitTimeout ?? 180000,
+  };
+}
+
+export function makeLink(link, target) {
+  symlinkSync(resolve(target), link, process.platform === "win32" ? "junction" : "dir");
+}
+// Remove ONLY the junction/symlink reparse point — never recurse into (and delete) the real target.
+function removeLink(link) {
+  if (!existsSync(link)) return true;
+  try {
+    const st = lstatSync(link);
+    if (st.isSymbolicLink() || process.platform === "win32") { rmdirSync(link); return !existsSync(link); }
+    rmSync(link, { force: true }); return !existsSync(link);
+  } catch (e) {
+    console.error(`  ⚠ could NOT remove link ${link}: ${e.message} — leaving worktree in place (refusing to risk node_modules).`);
+    return false;
+  }
+}
+
+/** git with core.longpaths=true so a full checkout's deep filenames don't trip Windows MAX_PATH. */
+export function git(ctx, cwd, ...a) {
+  return spawnSync("git", ["-c", "core.longpaths=true", ...a], { cwd, encoding: "utf8", timeout: ctx.gitTimeout });
+}
+
+/** Count `tsc --noEmit` errors in <worktree>/<spex>. Returns { count, status, output, timedOut }. */
+export function runTsc(ctx, worktree) {
+  const r = spawnSync("npx --no-install tsc --noEmit -p tsconfig.json", {
+    cwd: join(worktree, ctx.spex), shell: true, encoding: "utf8", timeout: ctx.tscTimeout,
+  });
+  const out = ((r.stdout || "") + (r.stderr || ""));
+  return { count: (out.match(/error TS\d+/g) || []).length, status: r.status, output: out.trim().slice(0, 1200), timedOut: r.error?.code === "ETIMEDOUT" };
+}
+
+/** Run a scoped vitest file in <worktree>/<spex>. Returns { pass, output, timedOut }. */
+export function runVitest(ctx, worktree, testRel) {
+  const r = spawnSync(`npx --no-install vitest run ${testRel}`, {
+    cwd: join(worktree, ctx.spex), shell: true, encoding: "utf8", timeout: ctx.testTimeout,
+  });
+  const out = ((r.stdout || "") + (r.stderr || ""));
+  return { pass: r.status === 0 && !r.error, output: out.trim().slice(-1200), timedOut: r.error?.code === "ETIMEDOUT" };
+}
+
+// HS-AY5K: the deterministic gate used to run EVERY test file through scoped
+// vitest, no matter what test framework it was actually written against. Every
+// vendor/heyspex-mcp/*.test.mjs imports describe/it/test from node:test — under vitest
+// they either execute on import and register with nothing ("no test suite found") or,
+// once vitest.config's `include` glob excludes the path, never even get picked up ("no
+// test files found") — a permanently red gate for code that is fully green under the
+// correct runner (`node --test`, 18/18). Detect the runner from the test file's own
+// imports (cheap — one regex over the source, no execution) and dispatch to the correct
+// one instead of hardcoding vitest.
+const NODE_TEST_IMPORT_RE = /\bfrom\s+['"]node:test['"]|\brequire\(\s*['"]node:test['"]\s*\)/;
+
+/** Does this test file import node:test (vs vitest/jest/etc.)? `testAbsPath` is read
+ *  directly off disk. Never throws — an unreadable/missing file is simply "not
+ *  node:test" and falls through to the existing vitest path (the pre-HS-XCCE-DIAG
+ *  default), so a caller still using the old spex-relative test-path convention (which
+ *  resolves to nothing under this REPO-ROOT-relative check) degrades safely rather than
+ *  misrouting. */
+export function isNodeTestFile(testAbsPath) {
+  try {
+    return NODE_TEST_IMPORT_RE.test(readFileSync(testAbsPath, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/** Run a node:test file via `node --test <file>`. `testRel` is REPO-ROOT-relative
+ *  (same convention as `task.target`, HS-W2F6) and resolved against the WORKTREE
+ *  ROOT — not under ctx.spex, since vendor/ and other non-spex-console directories have
+ *  no spex-console project to run inside, and `node --test` needs no project at all.
+ *  Mirrors runVitest's { pass, output, timedOut } contract so runGate/baselineTest can
+ *  dispatch to either interchangeably. */
+export function runNodeTest(ctx, worktree, testRel) {
+  const abs = join(worktree, testRel);
+  const r = spawnSync(`node --test "${abs}"`, {
+    cwd: worktree, shell: true, encoding: "utf8", timeout: ctx.testTimeout,
+  });
+  const out = ((r.stdout || "") + (r.stderr || ""));
+  return { pass: r.status === 0 && !r.error, output: out.trim().slice(-1200), timedOut: r.error?.code === "ETIMEDOUT" };
+}
+
+// HS-AY5K edge (c): a THIRD gate convention alongside node:test and vitest — a
+// plain script with NO test framework at all, verified by running it and checking its
+// raw exit code (0 = green, non-zero = red). Two shapes exist in this repo today:
+//   1. Inline argv guard: `if (process.argv.includes("--self-test")) { ...; process.exit(ok?0:1); }`
+//      — the SAME convention controller.mjs's `detectSelfTestGate` already detects for
+//      dev-factory/*.mjs TARGETS (Diagram 5a); this mirrors that regex so `--test`
+//      arguments pointing at such a file route the same way.
+//   2. Companion `<name>.selftest.mjs` file: running the file directly (no flag) IS the
+//      self-test — e.g. scripts/validate-vault-ids.selftest.mjs. Before this branch
+//      existed, a `--test` pointing at either shape fell through to vitest, which found
+//      no describe/it and reported a permanently red gate unrelated to the candidate.
+const SELF_TEST_ARGV_GUARD_RE = /(?:process\.)?argv\.includes\(\s*["']--self-test["']\s*\)/;
+const SELF_TEST_COMPANION_FILE_RE = /\.selftest\.[cm]?js$/;
+
+/** Does `testAbsPath` verify via a plain exit-code self-test (no node:test/vitest
+ *  import)? Never throws — mirrors {@link isNodeTestFile}'s safe-degrade contract. */
+export function isPlainSelfTestScript(testAbsPath) {
+  if (SELF_TEST_COMPANION_FILE_RE.test(testAbsPath)) return true;
+  try {
+    return SELF_TEST_ARGV_GUARD_RE.test(readFileSync(testAbsPath, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/** Run a plain exit-code self-test script. `testRel` is REPO-ROOT-relative (same
+ *  convention as {@link runNodeTest} — these scripts live outside spex-console, e.g.
+ *  scripts/ or dev-factory/, and need no project to run inside). The companion-file
+ *  convention (`*.selftest.mjs`) runs bare — invoking the file IS the check; the
+ *  inline-argv-guard convention needs `--self-test` appended so the guarded branch
+ *  actually fires. Mirrors runNodeTest/runVitest's { pass, output, timedOut } contract. */
+export function runPlainSelfTestScript(ctx, worktree, testRel) {
+  const abs = join(worktree, testRel);
+  const needsFlag = !SELF_TEST_COMPANION_FILE_RE.test(abs);
+  const r = spawnSync(`node "${abs}"${needsFlag ? " --self-test" : ""}`, {
+    cwd: worktree, shell: true, encoding: "utf8", timeout: ctx.testTimeout,
+  });
+  const out = ((r.stdout || "") + (r.stderr || ""));
+  return { pass: r.status === 0 && !r.error, output: out.trim().slice(-1200), timedOut: r.error?.code === "ETIMEDOUT" };
+}
+
+/** Dispatch to the correct runner for `testRel` (auto-detected) — the single seam
+ *  runGate and baselineTest both call through, so the routing rule lives in exactly
+ *  one place. Order matters: node:test and the plain-self-test conventions are both
+ *  narrow, cheap-to-check positives; vitest is the default fallback for everything else. */
+function runScopedTest(ctx, worktree, testRel) {
+  const abs = join(worktree, testRel);
+  if (isNodeTestFile(abs)) return runNodeTest(ctx, worktree, testRel);
+  if (isPlainSelfTestScript(abs)) return runPlainSelfTestScript(ctx, worktree, testRel);
+  return runVitest(ctx, worktree, testRel);
+}
+
+/** Capture the net-new-error baseline in the CLEAN worktree (before any task code is written). */
+export function baselineTsc(ctx, worktree) {
+  const t = runTsc(ctx, worktree);
+  return { count: t.count, timedOut: t.timedOut };
+}
+
+// HS-2HK7: the deterministic gate only knew the spex-console TS toolchain (tsc +
+// scoped vitest) or a .mjs self-test — a companion C# task (dotnet build + dotnet
+// test) had no fleet-gateable path and fell out of the free local build seat entirely.
+// A LANGUAGE-PROFILE gate lets a caller (controller.mjs, keyed off `--gate-build-cmd`/
+// `--gate-test-cmd`, or a per-task checks manifest) supply its own build/test commands
+// instead of the hardcoded pair — same worktree isolation, same write→run→restore
+// contract as `runGate`.
+
+/** Run an arbitrary shell command in `cwd`. Same `{ pass, output, timedOut }` shape as
+ *  runVitest/runNodeTest, so a language-profile command slots into the same dispatch
+ *  contract as the TS toolchain. */
+export function runShellCmd(cmd, cwd, timeoutMs) {
+  const r = spawnSync(cmd, { cwd, shell: true, encoding: "utf8", timeout: timeoutMs });
+  const out = ((r.stdout || "") + (r.stderr || ""));
+  return { pass: r.status === 0 && !r.error, output: out.trim().slice(-1200), timedOut: r.error?.code === "ETIMEDOUT" };
+}
+
+/** Baseline for a language-profile gate: run `buildCmd` (and `testCmd`, if given)
+ *  against the UNMODIFIED worktree. Mirrors baselineTsc/baselineTest's "red-before-any-
+ *  candidate" contract — a command already red on the clean tree is a gate/environment
+ *  fault, not a code defect. `cwdRel` is worktree-root-relative (e.g. "companion" for a
+ *  .sln that lives at `<repo>/companion/*.sln`); omit for the worktree root. */
+export function baselineLanguageGate(ctx, worktree, { buildCmd, testCmd, cwdRel = "" } = {}) {
+  if (!buildCmd) return { pass: true, output: "", timedOut: false };
+  const cwd = cwdRel ? join(worktree, cwdRel) : worktree;
+  const b = runShellCmd(buildCmd, cwd, ctx.tscTimeout);
+  if (!b.pass || b.timedOut) return b;
+  if (!testCmd) return { pass: true, output: "", timedOut: false };
+  return runShellCmd(testCmd, cwd, ctx.testTimeout);
+}
+
+/** Run a LANGUAGE-PROFILE gate instead of the hardcoded tsc+vitest pair (HS-2HK7) —
+ *  e.g. a companion C# task: `buildCmd: "dotnet build companion/HeySpex.Companion.sln"`,
+ *  `testCmd: "dotnet test companion/HeySpex.Companion.sln"`. Returns
+ *  `{ pass, tscOk, testOk, output }` — the SAME field NAMES `runGate` returns (`tscOk`/
+ *  `testOk` repurposed here as build-ok/test-ok) so a caller's existing best-of-N
+ *  scoring (`errorCount` derived from tscOk/testOk) works unmodified for either gate.
+ *  ALWAYS restores the target via `git checkout`, same as `runGate`. */
+export function runLanguageGate(ctx, worktree, task, code, { buildCmd, testCmd, cwdRel = "" } = {}) {
+  const abs = join(worktree, task.target);
+  let result = { pass: false, tscOk: false, testOk: false, output: "" };
+  try {
+    // HS-HECA: a genuinely new file's parent dir may exist neither at HEAD nor in the
+    // dirty working tree the overlay copied from — writeFileSync then threw ENOENT
+    // before the build/test command ever ran, reporting a gate/environment fault for
+    // work the builder had actually produced. Mirrors overlayIntoWorktree's own
+    // mkdirSync(dirname(to), { recursive: true }) before its writeFileSync.
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, code);
+    const cwd = cwdRel ? join(worktree, cwdRel) : worktree;
+    const b = runShellCmd(buildCmd, cwd, ctx.tscTimeout);
+    const tscOk = b.pass && !b.timedOut;
+    let testOk = false, testOut = "";
+    if (tscOk && testCmd) { const t = runShellCmd(testCmd, cwd, ctx.testTimeout); testOk = t.pass && !t.timedOut; testOut = t.output; }
+    else if (tscOk) testOk = true; // build-only gate when no test command is specified
+    result = {
+      pass: tscOk && testOk, tscOk, testOk,
+      output: (tscOk ? "" : `BUILD (${buildCmd}):\n${b.output}\n`)
+            + (tscOk && testCmd ? `TEST (${testCmd}):\n${testOut}` : "").slice(0, 1000),
+    };
+  } catch (e) {
+    // Environmental (bad path, missing dotnet SDK, permissions) — NOT a candidate defect.
+    // Mirrors runGate's gateException contract (HS-W2F6).
+    result = { pass: false, tscOk: false, testOk: false, gateException: true, output: `gate exception: ${e.message}` };
+  } finally {
+    git(ctx, worktree, "checkout", "--", task.target);
+  }
+  return result;
+}
+
+/** Capture the TEST HALF of the gate's baseline (HS-AY5K): run the correctly-routed
+ *  test (auto-detected node:test vs vitest) against the UNMODIFIED target in the clean
+ *  worktree, before any candidate code is written. If this is already red, no candidate
+ *  can ever pass the gate — the fault is the runner/environment, not the generated code
+ *  — so the caller should abort before spending any best-of-N attempts on it. Mirrors
+ *  baselineTsc's pattern. `testRel` falsy → nothing to baseline, trivially green (a
+ *  tsc-only gate has no test half). */
+// HS-AY5K edge (a): a NEW-FILE task's test doesn't exist yet at baseline — the
+// builder is EXPECTED to create it alongside the target. Without this check, the
+// missing file made runScopedTest's underlying runner report "red" (file not found /
+// no test files found), which the caller then wrongly treated as a genuine
+// gate/environment fault and aborted before the builder ever ran. Check BOTH path
+// conventions runScopedTest's runners use (node:test resolves testRel repo-root-
+// relative against `worktree`; vitest resolves it spex-relative against
+// `worktree/ctx.spex`) — a NEW-FILE test could land under either once the builder
+// creates it.
+function testExistsAtBaseline(ctx, worktree, testRel) {
+  return existsSync(join(worktree, testRel)) || existsSync(join(worktree, ctx.spex, testRel));
+}
+
+export function baselineTest(ctx, worktree, testRel) {
+  if (!testRel) return { pass: true, output: "", timedOut: false };
+  if (!testExistsAtBaseline(ctx, worktree, testRel)) {
+    return {
+      pass: true, notFound: true, timedOut: false,
+      output: `test file does not exist at baseline (${testRel}) — expected NEW-FILE condition, not a gate/environment fault`,
+    };
+  }
+  return runScopedTest(ctx, worktree, testRel);
+}
+
+// HS-L9BX: `setupWorktree` builds the gate's worktree from `git worktree add --detach
+// <path> HEAD` — committed content only. A wave-N+1 task importing a wave-N module that
+// is still `review_pending`/untracked (agents don't commit; the human reviewer commits
+// on Pass) is structurally invisible to the worktree: TS2307 fires even though the
+// builder's code is correct and the file exists in the main tree. Detect exactly that
+// shape and let the caller classify it as `gate_environment_fault` instead of spending
+// the retry/replan budget "fixing" code that already imports a real file correctly.
+const TS2307_RE = /^(.+?)\(\d+,\d+\): error TS2307: Cannot find module '([^']+)'/gm;
+const RELATIVE_IMPORT_EXTS = [".ts", ".tsx", ".mts", ".cts", ".d.ts", "/index.ts", "/index.tsx", ""];
+
+/** Resolve a relative import specifier from `fromFileAbs` to a file on disk, trying the
+ *  extensions TS allows an extensionless relative specifier to resolve to. Returns the
+ *  absolute path if found, else null. Never throws. */
+function resolveRelativeImport(fromFileAbs, specifier) {
+  const base = resolve(dirname(fromFileAbs), specifier);
+  for (const ext of RELATIVE_IMPORT_EXTS) {
+    const candidate = base + ext;
+    try { if (existsSync(candidate)) return candidate; } catch { /* ignore */ }
+  }
+  return null;
+}
+
+/** Does `tscOutput` contain a TS2307 on a RELATIVE import (bare/package specifiers are a
+ *  different bug class) that fails to resolve inside `worktree` but DOES resolve to a
+ *  real file at the same relative location in `ctx.repo` (the main tree)? Returns
+ *  `{ specifier, relMissing }` on a match, else `null`. `tscOutput` is tsc's raw stdout+
+ *  stderr, cwd `<worktree>/<ctx.spex>` (see `runTsc`), so reported file paths are
+ *  relative to that cwd. */
+function detectMissingWorktreeDependency(ctx, worktree, tscOutput) {
+  const tscCwd = join(worktree, ctx.spex);
+  let m;
+  TS2307_RE.lastIndex = 0;
+  while ((m = TS2307_RE.exec(tscOutput))) {
+    const [, filePart, specifier] = m;
+    if (!specifier.startsWith(".")) continue; // bare/package specifiers: not this bug
+    const fileAbsInWorktree = resolve(tscCwd, filePart.trim());
+    if (resolveRelativeImport(fileAbsInWorktree, specifier)) continue; // genuinely resolves — not this bug
+    const relFromWorktreeRoot = fileAbsInWorktree.slice(worktree.length).replace(/^[\\/]/, "");
+    const fileAbsInMain = join(ctx.repo, relFromWorktreeRoot);
+    const foundInMain = resolveRelativeImport(fileAbsInMain, specifier);
+    if (foundInMain) {
+      return { specifier, relMissing: foundInMain.slice(ctx.repo.length).replace(/^[\\/]/, "") };
+    }
+  }
+  return null;
+}
+
+// The deterministic gate on a worktree: write code → tsc (no NEW errors vs baseline) AND scoped vitest → restore.
+// Returns { pass, tscOk, testOk, output }. ALWAYS restores the target via `git checkout` so the tree stays pristine.
+//
+// `task.target` is REPO-ROOT-relative (e.g. "spex-console/src/x.ts" OR a repo-root path
+// like "schemas/foo.json") and is resolved against the WORKTREE ROOT. It used to be joined
+// under ctx.spex, which fabricated a non-existent path for any target outside spex-console/
+// — the gate then threw an ENOENT before tsc/vitest ran, and the caller mistook that
+// environmental failure for a red gate (HS-W2F6). tsc/vitest still run in ctx.spex (the
+// only TS/test project); a repo-root edit leaves the spex-console baseline untouched, so a
+// tsc-only gate on such a target correctly passes.
+export function runGate(ctx, worktree, task, code, baseline) {
+  const abs = join(worktree, task.target);
+  let result = { pass: false, tscOk: false, testOk: false, output: "" };
+  try {
+    // HS-HECA: same greenfield gap as runLanguageGate — a brand-new file in a
+    // brand-new subdirectory has no parent dir at HEAD or in the overlay, so
+    // writeFileSync ENOENTs before tsc/vitest ever runs. Create it first.
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, code);
+    const tsc = runTsc(ctx, worktree);
+    const tscOk = !tsc.timedOut && tsc.count <= baseline;
+    if (!tscOk && !tsc.timedOut) {
+      const missing = detectMissingWorktreeDependency(ctx, worktree, tsc.output);
+      if (missing) {
+        result = {
+          pass: false, tscOk: false, testOk: false, gateException: true,
+          output: `gate environment fault (HS-L9BX): worktree is missing '${missing.relMissing}' — imported via '${missing.specifier}'. The file exists in the main tree but the gate worktree is built from HEAD (committed content only), so an untracked wave-N dependency is structurally invisible to it. Commit the dependency's output, or overlay it into the worktree before gating — not a defect in this candidate's code.`,
+        };
+        return result;
+      }
+    }
+    let testOk = false, testOut = "";
+    if (tscOk && task.test) { const v = runScopedTest(ctx, worktree, task.test); testOk = v.pass; testOut = v.output; }
+    else if (tscOk) testOk = true; // tsc-only gate when no test is specified
+    result = {
+      pass: tscOk && testOk, tscOk, testOk,
+      output: (tscOk ? "" : `TSC (${tsc.count} err vs baseline ${baseline})${tsc.timedOut ? " [TIMEOUT]" : ""}:\n${tsc.output}\n`)
+            + (tscOk && task.test ? `VITEST:\n${testOut}` : "").slice(0, 1000),
+    };
+  } catch (e) {
+    // An exception here is ENVIRONMENTAL (bad path, permissions, missing toolchain) — NOT a
+    // defect in the candidate code. `gateException: true` lets the caller escalate it as
+    // such instead of self-repairing it or burning no-progress iterations on it (HS-W2F6).
+    result = { pass: false, tscOk: false, testOk: false, gateException: true, output: `gate exception: ${e.message}` };
+  } finally {
+    git(ctx, worktree, "checkout", "--", task.target);
+  }
+  return result;
+}
+
+/**
+ * Reclaim STRANDED worktrees an interrupted run left in ctx.worktreeRoot — links-first, so a
+ * later recursive delete can never follow a live junction into the real node_modules (root cause
+ * of HS-QSQX). Skips any worktree whose owner process is still alive (an active concurrent
+ * build). A worktree with no owner marker is treated as stranded (legacy / pre-marker strays).
+ * Returns { swept: string[], skipped: string[] }.
+ */
+export function sweepStaleWorktrees(ctx, { quiet = false } = {}) {
+  const swept = [], skipped = [];
+  if (!existsSync(ctx.worktreeRoot)) return { swept, skipped };
+  for (const entry of readdirSync(ctx.worktreeRoot)) {
+    const path = join(ctx.worktreeRoot, entry);
+    let st; try { st = lstatSync(path); } catch { continue; }
+    if (!st.isDirectory() || st.isSymbolicLink()) continue;
+    // Owner still alive? Leave the live worktree untouched.
+    let owner = null;
+    try { owner = JSON.parse(readFileSync(join(path, OWNER_FILE), "utf8")); } catch { /* no/invalid marker → stranded */ }
+    if (owner && isPidAlive(owner.pid)) { skipped.push(entry); continue; }
+    // HS-L4Q5: claim-bound SESSION worktrees are owned by the allocator (dev-factory/lib/
+    // worktree-allocator.mjs) and are reaped ONLY by reapWorktrees, which additionally checks
+    // releasedAt / claim liveness / dirtiness. A dead-pid session worktree still holds a human
+    // agent's uncommitted work, so the build-side sweep must never reclaim it.
+    if (owner && owner.kind === "session") { skipped.push(entry); continue; }
+    // teardownWorktree removes the junction LINKS first and refuses if any survives — never a raw
+    // recursive delete. For strays git can't recognise it then prunes; sweep the leftover plain
+    // (now junction-free) checkout tree.
+    const clean = teardownWorktree(ctx, path, quiet);
+    if (existsSync(path)) {
+      // Only reachable once both known junctions are confirmed gone (teardownWorktree refuses
+      // otherwise), so the remaining tree is ordinary files — safe to remove recursively.
+      if (clean || !existsSync(join(path, "node_modules"))) { try { rmSync(path, { recursive: true, force: true }); } catch { /* best-effort */ } }
+    }
+    if (!existsSync(path)) swept.push(entry);
+    else if (!quiet) console.error(`  ⚠ sweep left ${path} in place (a node_modules link survived) — inspect manually.`);
+  }
+  if (!quiet && (swept.length || skipped.length)) {
+    console.log(`  worktree sweep: reclaimed ${swept.length} stranded [${swept.join(", ")}]${skipped.length ? `, left ${skipped.length} live [${skipped.join(", ")}]` : ""}`);
+  }
+  return { swept, skipped };
+}
+
+/** Create a fresh detached worktree with node_modules junctioned (root + workspace). → abs path. */
+export function setupWorktree(ctx, label) {
+  const path = join(ctx.worktreeRoot, slug(label));
+  mkdirSync(ctx.worktreeRoot, { recursive: true });
+  // Reclaim any stranded worktrees (dead owners) BEFORE `git worktree add` — the prevention for
+  // HS-QSQX: an interrupted prior run must never leave a live junction for a later delete to
+  // follow. Live sibling worktrees (owner alive) are preserved.
+  sweepStaleWorktrees(ctx, { quiet: true });
+  if (existsSync(path)) teardownWorktree(ctx, path, true);
+  const add = git(ctx, ctx.repo, "worktree", "add", "--detach", path, "HEAD");
+  if (add.status !== 0) throw new Error(`git worktree add failed: ${(add.stderr || add.stdout || "").trim()}`);
+  // HS-OM28 multi-repo builds: ctx.repo may now be a SIBLING checkout (e.g. heyspex-com),
+  // which has its own root node_modules but no spex-console workspace. Junction only what
+  // actually exists — the missing-workspace symlink used to throw ENOENT and take the whole
+  // worktree setup down to critic-only fidelity. Vault behavior is unchanged (both exist).
+  const rootNM = join(ctx.repo, "node_modules");
+  if (existsSync(rootNM)) makeLink(join(path, "node_modules"), rootNM);
+  const spexNM = join(ctx.repo, ctx.spex, "node_modules");
+  if (existsSync(spexNM) && existsSync(join(path, ctx.spex))) makeLink(join(path, ctx.spex, "node_modules"), spexNM);
+  writeFileSync(join(path, OWNER_FILE), JSON.stringify({ kind: "build", pid: process.pid, startedAt: new Date().toISOString(), label }));
+  return path;
+}
+
+// HS-6NFD follow-on (the HS-L9BX fix, not just its detector): `setupWorktree` builds the
+// gate tree from `git worktree add --detach HEAD` — COMMITTED CONTENT ONLY. Agents don't
+// commit (the human reviewer commits on Pass), so a wave-N+1 task whose dependency is a
+// wave-N task sitting at in_review/review_pending compiles against a HEAD where that
+// dependency DOES NOT EXIST. Proven live on epic HS-4UU2: HEAD's GatherOutcome.cs contains
+// zero occurrences of `GatherRegion` while the working tree contains 8, so every wave-2
+// extractor candidate would fail with CS0246 and burn its whole retry+replan budget on code
+// that is in fact correct. HS-L9BX detects exactly this for TypeScript (TS2307) and can only
+// REPORT it ("commit the dependency's output, or overlay it into the worktree") — this is
+// that overlay.
+//
+// Deliberately NARROW: only paths the caller passes (the task's own DECLARED context files),
+// and only when the main tree's content actually differs from the worktree's. Everything else
+// stays HEAD-pure, so the gate still sees essentially one task's diff. Every overlaid file is
+// returned so the caller can log it and put it in the run record — this weakens isolation, so
+// it must never be silent.
+
+/** Every DIRTY (modified or untracked) path in the main tree under `subdirRel`, repo-root-
+ *  relative with forward slashes. Uses `git status --porcelain`, so .gitignore'd build output
+ *  (bin/, obj/, node_modules/) is excluded for free. Deleted paths are omitted — there is
+ *  nothing to overlay. Returns [] on any git failure (the caller degrades to declared-only).
+ *
+ *  Why a whole subtree and not just declared dependencies (HS-6NFD, proven on HS-YUGJ): a
+ *  declared-only overlay is TRANSITIVELY INCOMPLETE. HS-YUGJ declared GatherEngine.cs, so it
+ *  was overlaid — but the working-tree GatherEngine.cs references `ICrawlGate`, declared in
+ *  PolitenessGate.cs, which is ALSO uncommitted and which HS-YUGJ never declared. The baseline
+ *  went red with CS0246 on code that is perfectly correct in the real tree. Chasing that
+ *  closure per-language is a compiler's job, not a gate's; overlaying the project's dirty set
+ *  is the honest answer, because "HEAD" is not a state this repo is ever actually in — agents
+ *  never commit, the human commits on review Pass. */
+export function dirtyPathsUnder(ctx, subdirRel = "") {
+  // `-uall` is load-bearing: plain --porcelain COLLAPSES a fully-untracked directory into one
+  // entry with a trailing slash ("companion/src/.../Voice/"). Overlaying that path hits EISDIR
+  // and silently drops the entire subsystem — which is exactly how the HS-YUGJ baseline still
+  // failed on WorkspaceWatcher/GhostPredictor after the first overlay fix. -uall enumerates the
+  // individual files instead.
+  const r = git(ctx, ctx.repo, "status", "--porcelain", "-uall", "--", subdirRel || ".");
+  if (r.status !== 0) return [];
+  const out = [];
+  for (const line of String(r.stdout ?? "").split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const code = line.slice(0, 2);
+    if (code.includes("D")) continue;                 // deleted — nothing to copy
+    let p = line.slice(3).trim();
+    if (p.startsWith('"') && p.endsWith('"')) p = p.slice(1, -1);   // git quotes odd paths
+    const arrow = p.indexOf(" -> ");                  // renames: take the destination
+    if (arrow !== -1) p = p.slice(arrow + 4);
+    if (p) out.push(p.replace(/\\/g, "/"));
+  }
+  return out;
+}
+
+/** Copy the MAIN-TREE working content of `relPaths` (repo-root-relative) into `worktree`,
+ *  but only where it differs from what the worktree already has. Returns
+ *  `{ overlaid: [{path, bytes}], unchanged: string[], missing: string[] }`. Never throws —
+ *  an unreadable/unwritable path lands in `missing` and the gate proceeds without it. */
+export function overlayIntoWorktree(ctx, worktree, relPaths = []) {
+  const overlaid = [], unchanged = [], missing = [];
+  for (const rel of relPaths) {
+    const from = join(ctx.repo, rel);
+    const to = join(worktree, rel);
+    try {
+      if (!existsSync(from)) { missing.push(rel); continue; }
+      // Defensive: a caller-supplied path may still name a directory (a hand-authored
+      // `context_files:` entry, or a git output shape we did not anticipate). Skip it
+      // explicitly instead of throwing EISDIR into `missing`, where it reads like a real fault.
+      if (lstatSync(from).isDirectory()) { unchanged.push(rel); continue; }
+      const src = readFileSync(from, "utf8");
+      let dst = null;
+      try { dst = readFileSync(to, "utf8"); } catch { /* absent in the worktree — a NEW dependency */ }
+      if (dst === src) { unchanged.push(rel); continue; }
+      mkdirSync(dirname(to), { recursive: true });
+      writeFileSync(to, src);
+      overlaid.push({ path: rel, bytes: src.length, reason: dst == null ? "absent at HEAD" : "differs from HEAD" });
+    } catch (e) {
+      missing.push(`${rel} (${e.message})`);
+    }
+  }
+  return { overlaid, unchanged, missing };
+}
+
+/** Teardown: remove junction LINKS first, THEN git worktree remove. Returns true on a clean teardown. */
+export function teardownWorktree(ctx, path, quiet = false) {
+  const a = removeLink(join(path, ctx.spex, "node_modules"));
+  const b = removeLink(join(path, "node_modules"));
+  if (!a || !b) { if (!quiet) console.error(`  ⚠ refusing to git-remove ${path} — a node_modules link survived.`); return false; }
+  const rm = git(ctx, ctx.repo, "worktree", "remove", "--force", path);
+  if (rm.status !== 0) git(ctx, ctx.repo, "worktree", "prune");
+  return !existsSync(path);
+}
+
+// ── self-test (no models): prove the isolation plumbing — the deterministic gate's foundation ─────────
+// Guard on MAIN-entry too (not just the flag) so importing this module from the loop
+// controller doesn't fire the self-test when the controller is run with --self-test.
+if (process.argv.includes("--self-test") && import.meta.url.endsWith("/" + (process.argv[1]?.split(/[\\/]/).pop() ?? ""))) {
+  const ctx = makeCtx();
+  let ok = true;
+  const check = (name, cond) => { console.log(`  ${cond ? "✓" : "✗"} ${name}`); if (!cond) ok = false; };
+  console.log("== engine/worktree.mjs self-test ==");
+  console.log(`repo=${ctx.repo}\nspex=${ctx.spex}\nworktreeRoot=${ctx.worktreeRoot}\n`);
+  let wt;
+  try {
+    wt = setupWorktree(ctx, "selftest");
+    check("worktree dir created", existsSync(wt));
+    check("root node_modules junctioned", existsSync(join(wt, "node_modules")));
+    check("workspace node_modules junctioned", existsSync(join(wt, ctx.spex, "node_modules")));
+    const base = baselineTsc(ctx, wt);
+    check(`baseline tsc runs through the junctioned toolchain (count=${base.count}${base.timedOut ? ", TIMEOUT" : ""})`, !base.timedOut && typeof base.count === "number");
+
+    // HS-W2F6 regression: a REPO-ROOT target (a dir that exists at repo root but NOT
+    // under spex-console/, e.g. dev-factory/) must resolve to <worktree>/<target>. The old
+    // join-under-ctx.spex fabricated <worktree>/spex-console/dev-factory/… whose parent does
+    // not exist → ENOENT gate exception before tsc/vitest ran. A tsc-only gate on a repo-root
+    // JSON edit leaves the spex-console baseline untouched, so it must PASS (no gate exception).
+    const probe = { target: "dev-factory/.hsewt-gate-probe.json", test: null };
+    const probeAbs = join(wt, probe.target);
+    const g = runGate(ctx, wt, probe, "{}\n", base.count);
+    check("repo-root target resolves under the worktree root (no gate exception)", !g.gateException);
+    check("repo-root target gate ran tsc-only and passed (HS-JZBI path fixed)", g.pass === true && g.tscOk === true);
+    try { if (existsSync(probeAbs)) rmSync(probeAbs, { force: true }); } catch { /* best-effort cleanup of the untracked probe */ }
+
+    // HS-HECA regression: a target in a brand-new subdirectory (absent at HEAD AND in
+    // the dirty working tree — the overlay never creates it) used to ENOENT before the
+    // gate ever ran, misreporting a real builder output as a gate/environment fault.
+    // `mkdirSync(dirname(abs), { recursive: true })` in both runGate and runLanguageGate
+    // must create the whole missing chain (two nested new dirs, not just one level).
+    const greenfieldRoot = "dev-factory/.hsewt-greenfield-probe";
+    const greenfieldTarget = `${greenfieldRoot}/nested/probe.json`;
+    check("greenfield probe precondition: neither dir exists yet", !existsSync(join(wt, greenfieldRoot)));
+    try {
+      const greenfieldGate = runGate(ctx, wt, { target: greenfieldTarget, test: null }, "{}\n", base.count);
+      check("new file in a brand-new nested subdirectory reaches a real verdict (no gate exception / ENOENT)", !greenfieldGate.gateException);
+      check("new file in a brand-new nested subdirectory gate ran tsc-only and passed", greenfieldGate.pass === true && greenfieldGate.tscOk === true);
+    } finally {
+      try { if (existsSync(join(wt, greenfieldRoot))) rmSync(join(wt, greenfieldRoot), { recursive: true, force: true }); } catch { /* best-effort */ }
+    }
+
+    // HS-AY5K regression: the gate must DETECT node:test vs vitest from the test
+    // file's own imports and dispatch to the correct runner — vitest reports every
+    // vendor/heyspex-mcp/*.test.mjs FAILED (they import describe/it/test from node:test,
+    // not vitest) even though the same file is 18/18 green under `node --test`. Proven
+    // end-to-end against the REAL fixture that motivated the diagnosis (unmodified
+    // content — this proves runner ROUTING, not the builder).
+    const mcpTarget = "vendor/heyspex-mcp/capture-console-client.mjs";
+    const mcpTest = "vendor/heyspex-mcp/capture-console-client.test.mjs";
+    check("isNodeTestFile detects the real vendor/heyspex-mcp node:test fixture", isNodeTestFile(join(wt, mcpTest)) === true);
+    const vitestProbePath = join(tmpdir(), `hsewt-vitest-probe-${process.pid}.test.ts`);
+    writeFileSync(vitestProbePath, "import { describe, it, expect } from \"vitest\";\ndescribe(\"probe\", () => { it(\"passes\", () => { expect(1).toBe(1); }); });\n");
+    check("isNodeTestFile returns false for a vitest-authored file (not a blanket route-everything-to-node--test)", isNodeTestFile(vitestProbePath) === false);
+    try { rmSync(vitestProbePath, { force: true }); } catch { /* best-effort */ }
+
+    const mcpOriginal = readFileSync(join(wt, mcpTarget), "utf8");
+    const testBaseGreen = baselineTest(ctx, wt, mcpTest);
+    check("baselineTest: GREEN on the unmodified vendor/heyspex-mcp fixture (pass=true)", testBaseGreen.pass === true);
+    const mcpGate = runGate(ctx, wt, { target: mcpTarget, test: mcpTest }, mcpOriginal, base.count);
+    check("node:test file routed to `node --test` → GREEN gate on unmodified vendor/heyspex-mcp code (HS-AY5K)",
+      mcpGate.pass === true && mcpGate.tscOk === true && mcpGate.testOk === true);
+
+    // A vitest-authored fixture must still route through vitest (detection is not a
+    // blanket switch to node --test for every test file). `target` stays REPO-ROOT-
+    // relative (runGate's own convention, HS-W2F6); `test` stays SPEX-RELATIVE —
+    // the pre-existing runVitest contract (cwd = <worktree>/<spex>) that every real
+    // spex-console --test caller already relies on. The two conventions differing is
+    // exactly why a repo-root-relative test path safely falls through to "not found →
+    // not node:test → vitest" instead of misrouting: see isNodeTestFile's doc comment.
+    const vitestFixtureTargetRel = "spex-console/src/__hsewt_selftest_vitest_fixture__.test.ts";
+    const vitestFixtureTestRel = "src/__hsewt_selftest_vitest_fixture__.test.ts";
+    const vitestFixtureAbs = join(wt, vitestFixtureTargetRel);
+    const vitestFixtureContent = "import { describe, it, expect } from \"vitest\";\n\ndescribe(\"hsewt selftest vitest fixture\", () => {\n  it(\"passes\", () => {\n    expect(1 + 1).toBe(2);\n  });\n});\n";
+    writeFileSync(vitestFixtureAbs, vitestFixtureContent);
+    try {
+      const vitestGate = runGate(ctx, wt, { target: vitestFixtureTargetRel, test: vitestFixtureTestRel }, vitestFixtureContent, base.count);
+      check("vitest-authored file is still routed to vitest (green gate)", vitestGate.pass === true && vitestGate.tscOk === true && vitestGate.testOk === true);
+    } finally {
+      try { if (existsSync(vitestFixtureAbs)) rmSync(vitestFixtureAbs, { force: true }); } catch { /* best-effort */ }
+    }
+
+    // Red-baseline pre-check (HS-AY5K AC2/AC3): a test that is red BEFORE any
+    // candidate code is written must be reported red by baselineTest, so the caller can
+    // abort before spending any best-of-N attempts on a fault that has nothing to do
+    // with the generated code.
+    const alwaysFailRel = "dev-factory/.hsewt-selftest-alwaysfail.test.mjs";
+    const alwaysFailAbs = join(wt, alwaysFailRel);
+    writeFileSync(alwaysFailAbs, "import { test } from \"node:test\";\nimport assert from \"node:assert/strict\";\ntest(\"always fails\", () => { assert.equal(1, 2); });\n");
+    try {
+      const redBaseline = baselineTest(ctx, wt, alwaysFailRel);
+      check("baselineTest: RED on an always-failing node:test fixture (pass=false)", redBaseline.pass === false);
+    } finally {
+      try { if (existsSync(alwaysFailAbs)) rmSync(alwaysFailAbs, { force: true }); } catch { /* best-effort */ }
+    }
+
+    // HS-AY5K edge (a): a NEW-FILE task's test doesn't exist yet at baseline —
+    // must report pass:true + notFound:true (expected-new), NEVER a red baseline.
+    const newFileTestRel = "dev-factory/.hsewt-selftest-newfile.test.mjs";
+    const newFileTestAbs = join(wt, newFileTestRel);
+    check("precondition: the NEW-FILE test fixture truly doesn't exist at baseline", !existsSync(newFileTestAbs));
+    const newFileBaseline = baselineTest(ctx, wt, newFileTestRel);
+    check("baselineTest: a NEW-FILE test (missing at baseline) reports pass:true + notFound:true (never red)",
+      newFileBaseline.pass === true && newFileBaseline.notFound === true);
+
+    // HS-AY5K edge (c): a plain exit-code self-test script (no node:test/vitest
+    // import) must route to runPlainSelfTestScript, not fall through to vitest (which
+    // would report "no test files found" — a permanently red gate unrelated to the
+    // candidate). Both real-repo conventions: inline `--self-test` argv guard, and the
+    // bare `<name>.selftest.mjs` companion-file convention (scripts/validate-vault-ids
+    // .selftest.mjs is the real fixture that motivated this).
+    const argvGuardRel = "dev-factory/.hsewt-selftest-argvguard.mjs";
+    const argvGuardAbs = join(wt, argvGuardRel);
+    const argvGuardPassSrc = "if (process.argv.includes(\"--self-test\")) {\n  console.log(\"self-test PASS\");\n  process.exit(0);\n}\n";
+    writeFileSync(argvGuardAbs, argvGuardPassSrc);
+    try {
+      check("isPlainSelfTestScript detects the inline --self-test argv-guard convention", isPlainSelfTestScript(argvGuardAbs) === true);
+      check("isNodeTestFile does NOT misclassify a plain argv-guard script", isNodeTestFile(argvGuardAbs) === false);
+      const argvGuardGreen = baselineTest(ctx, wt, argvGuardRel);
+      check("baselineTest: argv-guard script routed correctly → GREEN (exit 0)", argvGuardGreen.pass === true);
+      writeFileSync(argvGuardAbs, "if (process.argv.includes(\"--self-test\")) {\n  console.log(\"self-test FAIL\");\n  process.exit(1);\n}\n");
+      const argvGuardRed = baselineTest(ctx, wt, argvGuardRel);
+      check("baselineTest: argv-guard script exit 1 → RED", argvGuardRed.pass === false);
+    } finally {
+      try { if (existsSync(argvGuardAbs)) rmSync(argvGuardAbs, { force: true }); } catch { /* best-effort */ }
+    }
+
+    const companionRel = "dev-factory/.hsewt-selftest-fixture.selftest.mjs";
+    const companionAbs = join(wt, companionRel);
+    writeFileSync(companionAbs, "console.log(\"self-test PASS\");\nprocess.exit(0);\n");
+    try {
+      check("isPlainSelfTestScript detects the *.selftest.mjs companion-file convention", isPlainSelfTestScript(companionAbs) === true);
+      const companionGreen = baselineTest(ctx, wt, companionRel);
+      check("baselineTest: companion .selftest.mjs runs BARE (no flag) → GREEN (exit 0)", companionGreen.pass === true);
+      writeFileSync(companionAbs, "console.log(\"self-test FAIL\");\nprocess.exit(1);\n");
+      const companionRed = baselineTest(ctx, wt, companionRel);
+      check("baselineTest: companion .selftest.mjs exit 1 → RED", companionRed.pass === false);
+      // Restore green content — runGate writes `code` to `task.target`, not `task.test`;
+      // the .selftest.mjs file on disk is what actually gets EXECUTED as the gate's test.
+      writeFileSync(companionAbs, "console.log(\"self-test PASS\");\nprocess.exit(0);\n");
+      const companionTargetRel = companionRel.replace(/\.selftest\.mjs$/, ".mjs");
+      const companionGate = runGate(ctx, wt, { target: companionTargetRel, test: companionRel }, "// candidate target content\n", base.count);
+      check("runGate routes a .selftest.mjs test through the plain self-test runner (green)", companionGate.pass === true && companionGate.testOk === true);
+    } finally {
+      try { if (existsSync(companionAbs)) rmSync(companionAbs, { force: true }); } catch { /* best-effort */ }
+      try {
+        const companionTargetAbs = join(wt, companionRel.replace(/\.selftest\.mjs$/, ".mjs"));
+        if (existsSync(companionTargetAbs)) rmSync(companionTargetAbs, { force: true });
+      } catch { /* best-effort */ }
+    }
+
+    // HS-QSQX regression: the stranded-worktree sweep must reclaim a dead-owner worktree
+    // links-first (never following its junction into the real node_modules) AND preserve a
+    // live-owner worktree. Canary the real root node_modules count across the whole sweep.
+    const rootNM = join(ctx.repo, "node_modules");
+    const canaryBefore = readdirSync(rootNM).length;
+    // Create the LIVE one first — setupWorktree sweeps on entry, so a stranded worktree made first
+    // would be reclaimed by the next setup before the explicit sweep could see it.
+    const live = setupWorktree(ctx, "sweep-live");                 // owner = this live process
+    const stranded = setupWorktree(ctx, "sweep-stranded");         // real worktree + live junctions
+    writeFileSync(join(stranded, OWNER_FILE), JSON.stringify({ pid: 999999999, startedAt: "x", label: "sweep-stranded" })); // fake a DEAD owner
+    const sweep = sweepStaleWorktrees(ctx, { quiet: true });
+    check("sweep reclaimed the dead-owner worktree", !existsSync(stranded) && sweep.swept.includes("sweep-stranded"));
+    check("sweep PRESERVED the live-owner worktree", existsSync(live) && sweep.skipped.includes("sweep-live"));
+    check(`sweep left the real root node_modules intact (canary ${canaryBefore})`, readdirSync(rootNM).length === canaryBefore);
+    teardownWorktree(ctx, live, true);
+  } catch (e) {
+    check(`setup/baseline threw: ${e.message}`, false);
+  } finally {
+    if (wt) {
+      const clean = teardownWorktree(ctx, wt);
+      check("teardown removed the worktree (no stray dir/junction)", clean && !existsSync(wt));
+    }
+  }
+  console.log(`\n${ok ? "✓ self-test PASS — worktree isolation + baseline + clean teardown verified." : "✗ self-test FAIL"}`);
+  process.exit(ok ? 0 : 1);
+}