@lenne.tech/cli 1.35.1 → 1.37.0

package/build/lib/hoist-workspace-pnpm-config.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.hoistPackageManager = hoistPackageManager;
 exports.hoistWorkspacePnpmConfig = hoistWorkspacePnpmConfig;
 const js_yaml_1 = require("js-yaml");
 const fs_utils_1 = require("./fs-utils");
@@ -26,14 +27,92 @@ const OBJECT_FIELDS = ['overrides', 'allowBuilds'];
 const ARRAY_FIELDS = ['onlyBuiltDependencies', 'ignoredOptionalDependencies', 'minimumReleaseAgeExclude'];
 const WORKSPACE_SCOPED_PNPM_FIELDS = [...OBJECT_FIELDS, ...ARRAY_FIELDS];
 const isArrayField = (field) => ARRAY_FIELDS.includes(field);
+/**
+ * Hoist the Corepack `packageManager` pin from sub-projects into the monorepo
+ * root `package.json`, keeping the highest version and stripping the pin from
+ * every sub-project.
+ *
+ * Unlike the fields above this is a TOP-LEVEL package.json field (not part of the
+ * `pnpm` block), and its destination is the root `package.json` — not
+ * `pnpm-workspace.yaml` — because Corepack, not pnpm, reads it. Hence its own pass.
+ *
+ * Why it must not stay in a sub-project: inside a workspace only the ROOT pin governs
+ * `pnpm install`. A pin left in `projects/app` is worse than inert — Corepack resolves
+ * the NEAREST package.json, so `cd projects/app && pnpm run build` (exactly what
+ * projects/app/Dockerfile does) provisions the sub-project's pnpm while the root
+ * install ran on another version. One build, two pnpm versions.
+ *
+ * Why the root needs a pin at all: without `packageManager`, Corepack silently
+ * downloads the LATEST pnpm from the registry (verified with an isolated cache, i.e.
+ * a fresh container). Together with the root `engines.pnpm: "^11.0.0"` shipped by
+ * lt-monorepo, that breaks the day pnpm 12 is released — pnpm enforces `engines.pnpm`
+ * hard (`ERR_PNPM_UNSUPPORTED_ENGINE`), so the Docker build dies without a single
+ * repo change. The starters carry an exact pin incl. integrity hash
+ * (`pnpm@11.13.1+sha512.…`, maintained via `corepack up`); hoisting it preserves both
+ * the determinism and the supply-chain check.
+ *
+ * Mixed package managers (e.g. api pinning yarn, app pinning pnpm) are left untouched
+ * rather than silently picking a winner — that is a template bug, not something to
+ * paper over.
+ *
+ * Idempotent: running twice has the same effect as running once.
+ *
+ * @param options.filesystem  Gluegun filesystem tool
+ * @param options.projectDir  Workspace root (contains the root package.json)
+ * @param options.subProjects Sub-project dirs relative to projectDir
+ */
+function hoistPackageManager(options) {
+    const { filesystem, projectDir, subProjects } = options;
+    const rootPkgPath = `${projectDir}/package.json`;
+    const rootPkg = filesystem.exists(rootPkgPath) ? filesystem.read(rootPkgPath, 'json') : null;
+    if (!rootPkg)
+        return;
+    const candidates = [];
+    const strippedSubs = [];
+    for (const subDir of subProjects) {
+        const subPath = `${projectDir}/${subDir}`;
+        if (!filesystem.exists(subPath))
+            continue;
+        // Never mutate a symlinked sub-project — it points at the user's own checkout.
+        if ((0, fs_utils_1.isSymlink)(subPath))
+            continue;
+        const subPkgPath = `${subPath}/package.json`;
+        if (!filesystem.exists(subPkgPath))
+            continue;
+        const subPkg = filesystem.read(subPkgPath, 'json');
+        if (typeof (subPkg === null || subPkg === void 0 ? void 0 : subPkg.packageManager) !== 'string')
+            continue;
+        candidates.push(subPkg.packageManager);
+        strippedSubs.push({ path: subPkgPath, pkg: subPkg });
+    }
+    if (candidates.length === 0)
+        return;
+    const rootPin = typeof rootPkg.packageManager === 'string' ? rootPkg.packageManager : undefined;
+    const all = rootPin ? [rootPin, ...candidates] : candidates;
+    // Bail out on mixed managers instead of guessing which one is authoritative.
+    const names = new Set(all.map(pmName));
+    if (names.size > 1)
+        return;
+    const winner = all.reduce((best, pin) => (comparePmVersions(pin, best) > 0 ? pin : best));
+    if (rootPin !== winner) {
+        rootPkg.packageManager = winner;
+        filesystem.write(rootPkgPath, `${JSON.stringify(rootPkg, null, 2)}\n`);
+    }
+    for (const { path, pkg } of strippedSubs) {
+        delete pkg.packageManager;
+        filesystem.write(path, `${JSON.stringify(pkg, null, 2)}\n`);
+    }
+}
 /**
  * Hoist workspace-scoped pnpm config from sub-projects into the monorepo
  * root `pnpm-workspace.yaml`. After this runs, sub-project pnpm config
  * (package.json#pnpm or a settings-only pnpm-workspace.yaml) is gone, and
  * the root pnpm-workspace.yaml carries the merged union next to `packages:`.
  *
- * Why pnpm-workspace.yaml and not package.json#pnpm: the monorepo root
- * pins pnpm 11 (via `packageManager`), and pnpm 11 SILENTLY IGNORES the
+ * Why pnpm-workspace.yaml and not package.json#pnpm: the monorepo runs
+ * pnpm 11 (lt-monorepo ships `engines.pnpm: "^11.0.0"`; the exact version
+ * comes from the `packageManager` pin that `hoistPackageManager` lifts to
+ * the root), and pnpm 11 SILENTLY IGNORES the
  * `pnpm` block in package.json — overrides/build-allowlists/etc. declared
  * there never take effect, regressing `pnpm audit` and the minimum-release
  * -age exemptions. pnpm-workspace.yaml is the pnpm-recommended home and is
@@ -93,6 +172,26 @@ function hoistWorkspacePnpmConfig(options) {
         filesystem.write(rootWsPath, (0, js_yaml_1.dump)(rootWs, { lineWidth: -1, sortKeys: false }));
     }
 }
+/**
+ * Compare the versions of two `packageManager` pins (`pnpm@11.13.1+sha512.…`).
+ * Returns >0 if `a` is newer, <0 if older, 0 if equal. Numeric segment-wise
+ * comparison; the integrity hash and any pre-release suffix are ignored, which is
+ * enough for the exact pins Corepack writes (no ranges are legal here).
+ */
+function comparePmVersions(a, b) {
+    var _a, _b;
+    const segments = (pin) => pmVersion(pin)
+        .split('.')
+        .map((s) => Number.parseInt(s, 10) || 0);
+    const av = segments(a);
+    const bv = segments(b);
+    for (let i = 0; i < Math.max(av.length, bv.length); i++) {
+        const diff = ((_a = av[i]) !== null && _a !== void 0 ? _a : 0) - ((_b = bv[i]) !== null && _b !== void 0 ? _b : 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
 /**
  * Move the workspace-scoped pnpm fields from `source` into `rootWs`,
  * deleting each moved field from `source`. Returns true if anything moved.
@@ -173,6 +272,15 @@ function mergePnpmFieldValue(field, rootValue, subValue) {
     const merged = Object.assign(Object.assign({}, rootObj), subObj);
     return Object.fromEntries(Object.entries(merged).sort(([a], [b]) => a.localeCompare(b)));
 }
+/** Extract the manager name from a pin (`pnpm@11.13.1+sha512.…` -> `pnpm`). */
+function pmName(pin) {
+    return pin.slice(0, Math.max(0, pin.lastIndexOf('@'))) || pin;
+}
+/** Extract the bare version from a pin (`pnpm@11.13.1+sha512.…` -> `11.13.1`). */
+function pmVersion(pin) {
+    const afterAt = pin.slice(pin.lastIndexOf('@') + 1);
+    return afterAt.split('+')[0];
+}
 /** Parse a YAML file into a plain object, or null on missing/malformed/non-object. */
 function readYaml(filesystem, path) {
     if (!filesystem.exists(path))

package/build/lib/workspace-integration.js

@@ -135,13 +135,17 @@ function detectWorkspaceLayout(workspaceDir, filesystem) {
 }
 /**
  * Normalize a freshly-populated workspace root after adding or removing a
- * sub-project. Runs the three idempotent workspace-hygiene steps that
+ * sub-project. Runs the four idempotent workspace-hygiene steps that
  * `fullstack init`, `add-api`, and `add-app` all need:
  *
  *   1. hoist pnpm workspace-scoped config (`overrides`, `allowBuilds`, …) out
  *      of the sub-projects into the root — pnpm only honours it at the root;
- *   2. remove nested `pnpm-lock.yaml` files the root lockfile supersedes;
- *   3. guarantee a workspace-root `.dockerignore` (Docker never reads a
+ *   2. hoist the Corepack `packageManager` pin to the root — only the root pin
+ *      governs the install, and a pin left in a sub-project makes
+ *      `cd projects/app && pnpm run build` provision a different pnpm than the
+ *      root install used;
+ *   3. remove nested `pnpm-lock.yaml` files the root lockfile supersedes;
+ *   4. guarantee a workspace-root `.dockerignore` (Docker never reads a
  *      sub-project's own `.dockerignore` when building from the root context).
  *
  * Each step is a no-op when there is nothing to do, so re-runs are safe.
@@ -151,6 +155,7 @@ function finalizeWorkspaceRoot(options) {
     const { filesystem, projectDir } = options;
     const subProjects = (_a = options.subProjects) !== null && _a !== void 0 ? _a : ['projects/api', 'projects/app'];
     (0, hoist_workspace_pnpm_config_1.hoistWorkspacePnpmConfig)({ filesystem, projectDir, subProjects });
+    (0, hoist_workspace_pnpm_config_1.hoistPackageManager)({ filesystem, projectDir, subProjects });
     (0, remove_nested_lockfiles_1.removeNestedLockfiles)({ filesystem, projectDir, subProjects });
     (0, ensure_root_dockerignore_1.ensureRootDockerignore)({ filesystem, projectDir });
 }
@@ -197,8 +202,13 @@ function findWorkspaceRoot(startDir, filesystem, maxDepth = 6) {
 function isNonInteractive(noConfirmFlag) {
     if (noConfirmFlag)
         return true;
-    // process.stdin may be undefined in some test runners — guard.
-    return Boolean(process.stdin && process.stdin.isTTY === false);
+    // Non-TTY stdin (pipes, scripts, CI, AI agents) must never sit on an
+    // interactive prompt. NOTE: Node leaves `isTTY` UNDEFINED (not false) on
+    // non-TTY streams, so the previous `isTTY === false` test classified every
+    // piped invocation as interactive — `lt ticket stop` then hung forever on its
+    // confirm prompt when run from a script. `!isTTY` treats undefined and false
+    // alike; a missing stdin (some test runners) cannot prompt either.
+    return !process.stdin || !process.stdin.isTTY;
 }
 /**
  * Reconfigure the cloned nest-base template's `.claude/upstream.json`

package/build/templates/check/check.mjs

@@ -25,7 +25,7 @@
  * Exit code: 0 when every step passed, 1 otherwise (preserves the contract the
  * lt-dev `running-check-script` skill relies on: non-zero === failed).
  */
-import { spawn } from "node:child_process";
+import { execSync, spawn } from "node:child_process";
 import { readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -66,8 +66,14 @@ function classify(cmd) {
   const c = cmd.toLowerCase();
   if (c.includes("vendor-freshness"))
     return { fatal: false, kind: "vendor", label: "vendor-freshness" };
+  // Dependency install — hoisted to ONE workspace-level run (see buildGroups):
+  // api and app chains both start with `pnpm install --frozen-lockfile`, and
+  // running those CONCURRENTLY (parallel groups) mutates the same workspace
+  // node_modules from two processes at once.
+  if (/\b(pnpm|npm|yarn|bun)\s+(install|ci)\b/.test(c))
+    return { fatal: true, kind: "install", label: "install" };
   if (c.includes("audit")) return { fatal: true, kind: "audit", label: "audit" };
-  if (c.includes("format:check") || c.includes("oxfmt") || c.includes("prettier"))
+  if (c.includes("format:check") || c.includes("oxfmt"))
     return { fatal: true, kind: "format", label: "format" };
   if (c.includes("lint")) return { fatal: true, kind: "lint", label: "lint" };
   if (/(^|&|\s)(pnpm\s+)?test(:|\s|$)|vitest|jest|test:unit|test:ci/.test(c))
@@ -86,7 +92,6 @@ function toFixCommand(kind, cmd) {
   if (kind === "format") {
     if (/\bformat:check\b/.test(cmd)) return cmd.replace(/\bformat:check\b/, "format");
     if (/\boxfmt\b/.test(cmd)) return cmd.replace(/\s--check\b/, "");
-    if (/\bprettier\b/.test(cmd)) return cmd.replace(/\s--check\b/, " --write");
     return cmd;
   }
   if (kind === "lint") {
@@ -99,16 +104,30 @@ function toFixCommand(kind, cmd) {
 }
 
 // ── metric parsers ─────────────────────────────────────────────────────────
+// Sum capture group 1 across every match of `re` (which must carry the `g` flag).
+// Returns null when nothing matched, so callers can tell "absent" from "zero".
+function sumMatches(clean, re) {
+  let total = null;
+  for (const m of clean.matchAll(re)) {
+    const n = Number(m[1]);
+    if (Number.isFinite(n)) total = (total ?? 0) + n;
+  }
+  return total;
+}
+// A single test step may invoke vitest more than once (`test` is
+// `vitest:unit && vitest`), emitting one summary block per run. Sum them all —
+// reading only the first silently under-reports every later run: the api step
+// showed "16 passed" (unit only) while its 69 e2e tests ran unseen.
 function parseVitest(out) {
   const clean = stripAnsi(out);
-  const tests = clean.match(/Tests\s+(?:(\d+)\s+failed[^\n]*?)?(\d+)\s+passed/i);
-  const files = clean.match(/Test Files\s+(?:(\d+)\s+failed[^\n]*?)?(\d+)\s+passed/i);
-  const failed = clean.match(/Tests\s+(\d+)\s+failed/i);
-  if (!tests && !files) return null;
+  const passed = sumMatches(clean, /Tests\s+(?:\d+\s+failed[^\n]*?)?(\d+)\s+passed/gi);
+  const files = sumMatches(clean, /Test Files\s+(?:\d+\s+failed[^\n]*?)?(\d+)\s+passed/gi);
+  const failed = sumMatches(clean, /Tests\s+(\d+)\s+failed/gi);
+  if (passed == null && files == null) return null;
   return {
-    failed: failed ? Number(failed[1]) : 0,
-    files: files ? Number(files[2]) : null,
-    passed: tests ? Number(tests[2]) : null,
+    failed: failed ?? 0,
+    files,
+    passed,
   };
 }
 function parseLint(out) {
@@ -142,21 +161,105 @@ async function runAudit(auditCmd) {
   return { auditCmd, blocking: code !== 0, counts, reason: counts ? null : out, total };
 }
 
+// Watchdog: kill a TEST step whose child produces NO output for this long. A
+// wedged test run (workers idle at 0% CPU — e.g. one spec file grinding through
+// retries after its app/socket state broke under load) otherwise spins the live
+// view forever: the spinner only proves the child process exists, not that it
+// progresses. Only test steps are watched: build / typecheck / audit
+// legitimately buffer all their output to the end (and go silent under a
+// non-TTY pipe), so watching them would false-kill a slow-but-progressing run.
+// Override with --idle-timeout=<seconds> or CHECK_IDLE_TIMEOUT (seconds); 0
+// disables it.
+const IDLE_TIMEOUT_MS = (() => {
+  const flag = process.argv.find((a) => a.startsWith("--idle-timeout="));
+  const raw = flag ? flag.slice("--idle-timeout=".length) : process.env.CHECK_IDLE_TIMEOUT;
+  const DEFAULT_MS = 300 * 1000;
+  if (raw === undefined || raw === "") return DEFAULT_MS;
+  const seconds = Number(raw);
+  if (seconds === 0) return 0; // explicit opt-out
+  // Invalid value (typo, unit suffix, negative) → keep the protection at its
+  // default rather than silently disabling it.
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    process.stderr.write(`[check] ignoring invalid idle-timeout "${raw}", using ${DEFAULT_MS / 1000}s\n`);
+    return DEFAULT_MS;
+  }
+  return seconds * 1000;
+})();
+
 // ── command runner ─────────────────────────────────────────────────────────
 const RUNNING = new Set();
-function capture(cmd, cwd) {
+
+// Best-effort kill of a child's whole process tree (sh → pnpm → vitest →
+// fork workers). Killing only the direct child orphans the tree — exactly the
+// zombie workers a deadlock leaves behind. Children are collected via pgrep
+// and killed leaves-first.
+function killTree(child, signal = "SIGTERM") {
+  const pids = [];
+  const collect = (pid) => {
+    pids.push(pid);
+    let out = "";
+    try {
+      out = execSync(`pgrep -P ${pid}`, { stdio: ["ignore", "pipe", "ignore"] })
+        .toString()
+        .trim();
+    } catch {
+      /* no children */
+    }
+    if (out) for (const p of out.split("\n")) collect(Number(p));
+  };
+  collect(child.pid);
+  for (const pid of pids.reverse()) {
+    try {
+      process.kill(pid, signal);
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+// idleTimeoutMs > 0 arms the no-output watchdog for this child; 0 (the default)
+// runs it unwatched. Only callers that KNOW the child streams progress (test
+// steps) should pass a timeout — see runGroup.
+function capture(cmd, cwd, idleTimeoutMs = 0) {
   return new Promise((resolve) => {
     const child = spawn(cmd, { cwd, shell: true });
     RUNNING.add(child);
     let out = "";
+    let idleTimer = null;
+    let killTimer = null;
+    let watchdogHit = false;
+    // Any output resets the watchdog — only complete silence for the full
+    // window counts as wedged. Escalate to SIGKILL for processes that ignore
+    // SIGTERM.
+    const armWatchdog = () => {
+      if (!idleTimeoutMs) return;
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => {
+        watchdogHit = true;
+        killTree(child);
+        killTimer = setTimeout(() => killTree(child, "SIGKILL"), 5000);
+        killTimer.unref();
+      }, idleTimeoutMs);
+    };
     const onData = (d) => {
       out += d;
+      armWatchdog();
       if (VERBOSE) process.stdout.write(d);
     };
+    armWatchdog();
     child.stdout.on("data", onData);
     child.stderr.on("data", onData);
     const done = (code, extra) => {
+      clearTimeout(idleTimer);
+      clearTimeout(killTimer);
       RUNNING.delete(child);
+      if (watchdogHit) {
+        const note =
+          `[watchdog] step produced no output for ${Math.round(idleTimeoutMs / 1000)}s — ` +
+          "process tree killed as deadlocked. This is a hang (workers idle at 0% CPU), " +
+          `not a slow run. Re-run the step directly to debug: \`${cmd}\``;
+        return resolve({ code: 1, out: `${out}\n${note}` });
+      }
       resolve({ code, out: extra ? `${out}\n${extra}` : out });
     };
     child.on("close", (code) => done(code ?? 1));
@@ -166,13 +269,36 @@ function capture(cmd, cwd) {
 function killAll() {
   for (const child of RUNNING) {
     try {
-      child.kill("SIGTERM");
+      killTree(child);
     } catch {
       /* already gone */
     }
   }
 }
 
+// A child killed by a signal surfaces through the package manager as a
+// "Command failed with exit code 143/137" line (SIGTERM/SIGKILL), NOT as a test
+// assertion failure — and the outer shell then reports its own generic exit 1,
+// so `code` alone never reveals it. Surface the signal so the reason isn't
+// mistaken for a real failure: the usual cause is resource pressure (parallel
+// checks/builds swapping the machine) or an external kill.
+function signalExitHint(out) {
+  const clean = stripAnsi(out);
+  // The watchdog also kills via SIGTERM, so pnpm's "exit code 143" ends up in
+  // the output — but that path already carries its own [watchdog] note with the
+  // correct (deadlock) diagnosis. Don't stack a contradictory "external kill"
+  // hint on top of it.
+  if (/\[watchdog\]/.test(clean)) return null;
+  const m = clean.match(/Command failed with exit code (137|143)\b/);
+  if (!m) return null;
+  const sig = m[1] === "143" ? "SIGTERM" : "SIGKILL";
+  return (
+    `[check] step ended via ${sig} (exit ${m[1]}) — the process was killed, not an assertion failure. ` +
+    "Usual cause: resource pressure (parallel checks/builds swapping) or an external kill. " +
+    "Re-run this project's check alone to confirm."
+  );
+}
+
 // ── live multi-line status (one line per running project) ────────────────────
 const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 let liveCount = 0;
@@ -255,9 +381,23 @@ function asProject(rel, check) {
   return { check, dir: rel === "." ? ROOT : join(ROOT, rel), name: pkg.name || rel, rel };
 }
 
-// Workspace sub-projects whose `check` is a real chain; if there are none (a
+// Workspace sub-projects and their real check chain; if there are none (a
 // single-package repo), fall back to the root project — whose real chain lives
 // in `check:raw`, because the root `check` is THIS wrapper.
+//
+// A member's `check` is frequently THIS wrapper too: the lt starters ship their
+// own scripts/check.mjs so they also work standalone (`lt server create`), and
+// `lt fullstack init` clones them verbatim into projects/*. Treating that as
+// "no real chain" silently dropped EVERY member — the run then fell back to the
+// root, whose chain is just `pnpm -r run check`, and reported the whole
+// monorepo as one opaque step with "no test step / 0 passed" while the members'
+// tests were in fact running, unseen. So resolve a member exactly like the root:
+// wrapper `check` means the real chain lives in `check:raw`.
+function realChain(pkg) {
+  if (!IS_ORCHESTRATOR(pkg.scripts?.check)) return pkg.scripts?.check ?? null;
+  return pkg.scripts?.["check:raw"] ?? null;
+}
+
 function discoverProjects() {
   const projects = [];
   for (const glob of workspaceGlobs()) {
@@ -268,7 +408,8 @@ function discoverProjects() {
       } catch {
         continue;
       }
-      if (!IS_ORCHESTRATOR(pkg.scripts?.check)) projects.push(asProject(rel, pkg.scripts.check));
+      const chain = realChain(pkg);
+      if (chain) projects.push(asProject(rel, chain));
     }
   }
   if (projects.length === 0) {
@@ -290,6 +431,7 @@ function discoverProjects() {
 // package manager) is captured so the run mirrors the chain's own audit.
 function buildGroups(projects) {
   let auditCmd = null;
+  let installCmd = null;
   const groups = projects.map((project) => {
     const steps = [];
     for (const raw of project.check
@@ -301,11 +443,19 @@ function buildGroups(projects) {
         if (!auditCmd) auditCmd = raw;
         continue;
       }
+      if (meta.kind === "install") {
+        // Hoisted like the audit: one workspace-level install BEFORE the
+        // fan-out. In a pnpm workspace every member's install resolves the
+        // whole workspace anyway, and two parallel installs race on the same
+        // node_modules.
+        if (!installCmd) installCmd = raw;
+        continue;
+      }
       steps.push({ ...meta, cmd: toFixCommand(meta.kind, raw), cwd: project.dir });
     }
     return { project, steps };
   });
-  return { auditCmd, groups };
+  return { auditCmd, groups, installCmd };
 }
 
 // ── per-project runner ───────────────────────────────────────────────────────
@@ -320,7 +470,10 @@ async function runGroup(group, states, results, abort) {
     st.current = step.label;
     st.stepStart = Date.now();
     if (!TTY) process.stdout.write(`  ${C.dim("→")} ${shortRel(rel)} · ${step.label}\n`);
-    const { code, out } = await capture(step.cmd, step.cwd);
+    // Watchdog only on test steps (see IDLE_TIMEOUT_MS): a test runner streams
+    // output continuously, so prolonged silence == deadlocked workers. Other
+    // steps buffer their output and must run unwatched.
+    const { code, out } = await capture(step.cmd, step.cwd, step.kind === "test" ? IDLE_TIMEOUT_MS : 0);
     const dur = Date.now() - st.stepStart;
     const r = { dur, kind: step.kind, label: step.label, project: rel };
     if (step.kind === "test") r.tests = parseVitest(out);
@@ -330,7 +483,12 @@ async function runGroup(group, states, results, abort) {
       st.failed = step.label;
       if (!abort.hit) {
         abort.hit = true;
-        abort.failure = { out, project: rel, step: `${shortRel(rel)} · ${step.label}` };
+        const hint = signalExitHint(out);
+        abort.failure = {
+          out: hint ? `${out}\n${hint}` : out,
+          project: rel,
+          step: `${shortRel(rel)} · ${step.label}`,
+        };
         killAll();
       }
       return;
@@ -352,8 +510,9 @@ async function main() {
     console.error(C.red("No workspace projects with a `check` script found."));
     process.exit(1);
   }
-  const { auditCmd, groups } = buildGroups(projects);
-  const stepCount = groups.reduce((n, g) => n + g.steps.length, 0) + (auditCmd ? 1 : 0);
+  const { auditCmd, groups, installCmd } = buildGroups(projects);
+  const stepCount =
+    groups.reduce((n, g) => n + g.steps.length, 0) + (auditCmd ? 1 : 0) + (installCmd ? 1 : 0);
   const mode = SEQUENTIAL ? "sequential" : "parallel";
   const pkgName = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).name;
 
@@ -367,6 +526,26 @@ async function main() {
 
   const results = [];
 
+  // Step -1 — single hoisted workspace install (before audit and fan-out).
+  // The member chains each start with their own `pnpm install --frozen-lockfile`;
+  // running it ONCE at the workspace root is equivalent and removes the race of
+  // two parallel installs mutating the same node_modules.
+  if (installCmd) {
+    const t = Date.now();
+    if (!TTY) process.stdout.write(`  ${C.dim("→")} install\n`);
+    else drawLive([`${C.cyan(FRAMES[0])} install`]);
+    const { code, out } = await capture(installCmd, ROOT);
+    const dur = Date.now() - t;
+    if (code !== 0) {
+      liveCount = 0; // the failure line must survive — nothing may overwrite it
+      console.log(`${C.red("✗")} install ${C.dim(`(${fmtDuration(dur)})`)}`);
+      return fail(`install (${installCmd})`, out, started);
+    }
+    if (!TTY) process.stdout.write(`  ${C.green("✓")} install ${C.dim(`(${fmtDuration(dur)})`)}\n`);
+    // TTY success: no permanent line — see the audit block below.
+    results.push({ dur, kind: "step", label: "install", project: "." });
+  }
+
   // Step 0 — single workspace audit (blocking gate, runs before the fan-out).
   // Mirrors the chain's own audit command (scope/level/PM); skipped only when
   // the chain has no audit step.
@@ -375,9 +554,9 @@ async function main() {
     if (!TTY) process.stdout.write(`  ${C.dim("→")} audit\n`);
     else drawLive([`${C.cyan(FRAMES[0])} audit`]);
     const audit = await runAudit(auditCmd);
-    liveCount = 0;
     const dur = Date.now() - t;
     if (audit.blocking) {
+      liveCount = 0; // the failure line must survive — nothing may overwrite it
       const summary = audit.counts
         ? `${audit.total} vuln (${renderVulnLine(audit.counts)})`
         : "failed";
@@ -388,10 +567,16 @@ async function main() {
         started,
       );
     }
-    console.log(
-      `${C.green("✓")} audit  ${audit.counts ? renderVulnLine(audit.counts) : C.dim("0")} ${C.dim(`(${fmtDuration(dur)})`)}`,
-    );
+    if (!TTY) {
+      process.stdout.write(
+        `  ${C.green("✓")} audit  ${audit.counts ? renderVulnLine(audit.counts) : C.dim("0")} ${C.dim(`(${fmtDuration(dur)})`)}\n`,
+      );
+    }
+    // TTY success: NO permanent line — the live status view overwrites the audit
+    // row (like every other step); the result lands in the report twice: the
+    // Steps list (entry below) and the Vulnerabilities section.
     results.push({ audit, kind: "audit" });
+    results.push({ dur, kind: "step", label: "audit", project: "." });
   }
 
   // Per-project steps — parallel by default, serial with --sequential.