mandrel 2.35.0 → 2.37.0

package/.agents/scripts/lib/test-tiers.js

@@ -23,6 +23,46 @@ export const INTEGRATION_INCLUDE = [
 
 const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
 
+/**
+ * Globs for the `e2e` tier — real-binary suites under `tests/e2e/` that pack
+ * this repository, install it into a temp consumer and drive the shipped
+ * `mandrel` binary end to end.
+ *
+ * They are the most expensive files the repository owns by an order of
+ * magnitude: one `npm pack` plus real `npm install` spawns per file, measured
+ * (Story #5111) at ~7 s of system time and ~17 s of summed install wall clock
+ * for `update-chain.integration.test.js` alone. Every one of those seconds was
+ * charged to `npm test` — i.e. to every pre-push hook and every local
+ * iteration — for a signal that only changes when the release-shaped install
+ * path changes.
+ *
+ * So they get their own tier and leave every other one: `full` (`npm test`),
+ * `quick` and `integration` all exclude them, and `npm run test:e2e` is how
+ * they run. CI runs that tier as its own job on every PR, so the
+ * release-shaped path keeps its per-PR signal.
+ *
+ * Deliberately not exported: a second reader of this list is a second place
+ * for the tier definition to drift. `listTestFilesForTier('e2e', root)` is the
+ * public answer to "which files are e2e", and the tests assert through it.
+ */
+const E2E_INCLUDE = ['tests/e2e/**/*.test.js'];
+
+const matchesE2E = picomatch(E2E_INCLUDE, { dot: true });
+
+/** Tier names `parseTierArgv` accepts, in the order `--help` lists them. */
+const TIERS = ['full', 'quick', 'integration', 'e2e'];
+
+/**
+ * `node --test` flags the runner forwards verbatim to the child.
+ *
+ * Everything else that looks like a flag is a mistake — a typo, a retired
+ * option, or a flag meant for `npm` that landed after the `--` separator —
+ * and `parseTierArgv` rejects it rather than passing it to `node --test`,
+ * which reads an unknown `--flag` as a *file pattern* and silently runs a
+ * suite that matches nothing while exiting 0.
+ */
+const PASSTHROUGH_FLAGS = ['--test-name-pattern', '--test-only'];
+
 /**
  * Repo-relative roots the tier walker scans for test files (names ending in
  * `.test.js`).
@@ -47,12 +87,22 @@ const TEST_WALK_ROOTS = ['tests', 'lib', '.agents/scripts'];
  * globs are scoped to `__tests__` subtrees so they only match colocated
  * tests, never the shipped source modules themselves.
  *
- * Exported because the full tier has two runners, not one: `run-tests.js`
- * (via `listTestFilesForTier`) and `run-coverage.js`. Story #4922 — the
- * coverage runner used to restate `tests/**` on its own, so the 47 colocated
- * `__tests__` files ran under `npm test` but were absent from the measured
- * surface, leaving the coverage and CRAP numbers computed over code the
- * measuring run never executed. Consume this constant; never restate a glob.
+ * Exported because it is the **measured surface**: `run-coverage.js` — the
+ * required CI job, and the run every coverage / CRAP baseline is scored from —
+ * consumes it directly. Story #4922: the coverage runner used to restate
+ * `tests/**` on its own, so the 47 colocated `__tests__` files ran under
+ * `npm test` but were absent from the measured surface, leaving the coverage
+ * and CRAP numbers computed over code the measuring run never executed.
+ * Consume this constant; never restate a glob.
+ *
+ * Story #5111 made this a strict **superset** of the `full` runner tier: the
+ * measured surface still includes `tests/e2e/**`, while `npm test` no longer
+ * runs it. That asymmetry is deliberate and load-bearing. The e2e suites drive
+ * the shipped binary through `bin/mandrel.js` and `lib/cli/update.js` in real
+ * child processes, and c8's `NODE_V8_COVERAGE` is inherited by those children —
+ * so dropping them from the measured run would deflate exactly the CLI files
+ * they exist to exercise and red the coverage ratchet on code nobody touched.
+ * Cheapening the pre-push loop must not cost the measurement its subject.
  */
 export const FULL_TIER_GLOBS = [
   'tests/**/*.test.js',
@@ -81,10 +131,47 @@ function walkTestFiles(dir, prefix, fsLike) {
   return out;
 }
 
+/**
+ * Split the walked set into the `e2e` tier and the remainder every other tier
+ * is drawn from, so an e2e file belongs to exactly one tier and `npm test`
+ * never pays for it.
+ *
+ * @param {string[]} all
+ * @returns {{ e2e: string[], rest: string[] }}
+ */
+function partitionE2E(all) {
+  const e2e = all.filter((file) => matchesE2E(file));
+  const e2eSet = new Set(e2e);
+  return { e2e, rest: all.filter((file) => !e2eSet.has(file)) };
+}
+
+/**
+ * Split the non-e2e remainder into the slow `integration` tier and the `quick`
+ * complement — the historical partition, unchanged.
+ *
+ * @param {string[]} rest
+ * @param {'quick' | 'integration'} tier
+ * @returns {string[]}
+ */
+function splitBySpeed(rest, tier) {
+  const integration = rest.filter((file) => matchesIntegration(file));
+  if (tier === 'integration') {
+    return integration;
+  }
+  const integrationSet = new Set(integration);
+  return rest.filter((file) => !integrationSet.has(file));
+}
+
 /**
  * List repo-relative test file paths for a tier.
  *
- * @param {'full' | 'quick' | 'integration'} tier
+ * `full` used to return {@link FULL_TIER_GLOBS} verbatim and let `node --test`
+ * expand them. It enumerates files instead since Story #5111, because the one
+ * thing a glob list cannot express is an exclusion: `node --test` has no
+ * negative pattern, so "everything except `tests/e2e/**`" is only sayable as
+ * a file set. The measured surface keeps the globs (see `FULL_TIER_GLOBS`).
+ *
+ * @param {'full' | 'quick' | 'integration' | 'e2e'} tier
  * @param {string} repoRoot
  * @param {typeof fs} [fsLike]
  * @returns {string[]}
@@ -93,34 +180,64 @@ export function listTestFilesForTier(tier, repoRoot, fsLike = fs) {
   const all = TEST_WALK_ROOTS.flatMap((root) =>
     walkTestFiles(path.join(repoRoot, root), root, fsLike),
   ).sort();
-  if (tier === 'full') {
-    return [...FULL_TIER_GLOBS];
+  const { e2e, rest } = partitionE2E(all);
+  if (tier === 'e2e') {
+    return e2e;
   }
-  const integration = all.filter((file) => matchesIntegration(file));
-  if (tier === 'integration') {
-    return integration;
+  if (tier === 'full') {
+    return rest;
   }
-  const integrationSet = new Set(integration);
-  return all.filter((file) => !integrationSet.has(file));
+  return splitBySpeed(rest, tier);
+}
+
+/**
+ * Reject argv tokens that look like flags but are neither `--tier` (already
+ * consumed) nor a sanctioned `node --test` pass-through.
+ *
+ * Silence was the old behaviour and the reason this exists: the runner
+ * forwarded every unrecognized token verbatim, and `node --test` treats an
+ * unknown `--flag` as another **file pattern**. A typo therefore produced a
+ * run that matched nothing, printed a plausible-looking summary and exited 0 —
+ * a green that proved nothing.
+ *
+ * @param {string[]} rest
+ * @throws {Error} naming both the accepted tiers and the accepted flags.
+ */
+function assertKnownFlags(rest) {
+  const unknown = rest.filter(
+    (arg) =>
+      arg.startsWith('--') &&
+      !PASSTHROUGH_FLAGS.includes(arg) &&
+      !PASSTHROUGH_FLAGS.some((flag) => arg.startsWith(`${flag}=`)),
+  );
+  if (unknown.length === 0) return;
+  throw new Error(
+    `[run-tests] unrecognized argument(s): ${unknown.join(', ')}. ` +
+      `Accepted: --tier <${TIERS.join('|')}>, ${PASSTHROUGH_FLAGS.join(', ')}, --help. ` +
+      'Unrecognized flags are not forwarded: `node --test` would read them as ' +
+      'file patterns and exit 0 having run nothing.',
+  );
 }
 
 /**
- * Parse `--tier <name>` from argv. Unknown tiers throw.
+ * Parse `--tier <name>` from argv. Unknown tiers and unknown flags throw.
  *
  * @param {string[]} argv
- * @returns {{ tier: 'full' | 'quick' | 'integration', rest: string[] }}
+ * @returns {{ tier: 'full' | 'quick' | 'integration' | 'e2e', rest: string[] }}
  */
 export function parseTierArgv(argv) {
   const tierIdx = argv.indexOf('--tier');
   if (tierIdx === -1) {
+    assertKnownFlags(argv);
     return { tier: 'full', rest: argv };
   }
   const tier = argv[tierIdx + 1];
-  if (!tier || !['full', 'quick', 'integration'].includes(tier)) {
+  if (!tier || !TIERS.includes(tier)) {
     throw new Error(
-      `[run-tests] --tier requires one of: full, quick, integration (got ${JSON.stringify(tier)})`,
+      `[run-tests] --tier requires one of: ${TIERS.join(', ')} (got ${JSON.stringify(tier)})`,
     );
   }
   const rest = argv.filter((_, i) => i !== tierIdx && i !== tierIdx + 1);
+  assertKnownFlags(rest);
   return { tier, rest };
 }

package/.agents/scripts/lib/transpile.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { createRequire, SourceMap } from 'node:module';
 import path from 'node:path';
+import { resolveDependencyVersion } from './dependency-version.js';
 import { Logger } from './Logger.js';
 
 const require = createRequire(import.meta.url);
@@ -22,18 +23,30 @@ function loadTypeScript() {
   }
 }
 
+let _tsVersion = null;
+
 /**
  * Resolve the `typescript` package version, used to stamp baselines so
  * consumers can detect transpiler drift. Returns `'0.0.0'` when the
  * dependency is unresolvable — callers treat that sentinel as "unknown
  * environment" and may refuse to persist a baseline that includes TS rows.
  *
+ * **The version is read from the package manifest, never by evaluating the
+ * compiler** (Story #5109) — see
+ * [`dependency-version.js`](dependency-version.js) for how, and for what it
+ * cost to do it the other way. The manifest returns the identical string, so
+ * the stamp (and therefore every committed baseline envelope) is
+ * byte-identical either way. The compiler itself is still loaded — lazily, by
+ * `transpileIfNeeded` — the first time a `.ts`/`.tsx` input is actually
+ * transpiled.
+ *
  * @returns {string}
  */
 export function resolveTsTranspilerVersion() {
-  const ts = loadTypeScript();
-  if (ts && typeof ts.version === 'string') return ts.version;
-  return '0.0.0';
+  if (_tsVersion === null) {
+    _tsVersion = resolveDependencyVersion('typescript', require) ?? '0.0.0';
+  }
+  return _tsVersion;
 }
 
 function isTypeScriptPath(filePath) {

package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js

@@ -15,14 +15,39 @@
  *
  * The manifest itself lives under `.worktrees/`, which is already
  * git-ignored; no tracked state is mutated.
+ *
+ * **Story #5112 — the manifest is shared mutable state.** `recordPendingCleanup`
+ * runs from the close reap and `drainPendingCleanup` runs from the `/plan`
+ * boot, so two concurrent delivery sessions can read-modify-write the same
+ * file. Three properties close that:
+ *
+ *   1. **Atomic write.** Every write lands in a pid-scoped temp file and is
+ *      then `rename`d over the manifest, so a reader never observes a half-
+ *      written array (`readManifest` treats a torn or absent file as empty,
+ *      which used to silently *drop* the backlog).
+ *   2. **Mutual exclusion.** Read-modify-write runs under the shared
+ *      `acquireSweepLock` primitive on a manifest-adjacent lockfile.
+ *   3. **Merge before write.** The drain holds its snapshot across awaited
+ *      removals, so it re-reads and merges by `storyId` before its final
+ *      write — an entry recorded mid-drain survives instead of being erased
+ *      by a stale snapshot.
  */
 
 import fs from 'node:fs';
 import { rm as fsPromisesRm } from 'node:fs/promises';
 import path from 'node:path';
 import { NOOP_LOGGER } from '../../Logger.js';
+import { acquireSweepLock } from '../../single-story-sweep/sweep-lock.js';
 
 const MANIFEST_FILENAME = '.pending-cleanup.json';
+const MANIFEST_LOCK_FILENAME = '.pending-cleanup.lock';
+
+/**
+ * Staleness threshold for the manifest lock. Deliberately short: the guarded
+ * section is a read, an in-memory merge and a rename — milliseconds — so a
+ * lockfile older than this is a crashed holder, not a slow one.
+ */
+const MANIFEST_LOCK_TIMEOUT_MS = 5_000;
 /**
  * After a reap hands off to the manifest, `attempts` counts failed
  * `drainPendingCleanup` passes (initial hand-off uses `attempts: 0`). The entry
@@ -35,6 +60,49 @@ export function manifestPath(worktreeRoot) {
   return path.join(worktreeRoot, MANIFEST_FILENAME);
 }
 
+/**
+ * Path of the lockfile guarding manifest read-modify-write. Manifest-adjacent
+ * (same gitignored `.worktrees/` directory) so it needs no extra config and
+ * shares the manifest's lifetime. Module-private: the lock is internal to
+ * this manifest's read-modify-write, and callers only ever observe that a
+ * mutation completed and left nothing behind.
+ *
+ * @param {string} worktreeRoot
+ * @returns {string}
+ */
+function manifestLockPath(worktreeRoot) {
+  return path.join(worktreeRoot, MANIFEST_LOCK_FILENAME);
+}
+
+/**
+ * Run `fn` under the manifest lock. Best-effort in the same sense as every
+ * other use of this primitive: on contention the work still runs (the
+ * merge-before-write below is what makes a lost race non-destructive), so a
+ * stuck lockfile can never wedge a reap. Always releases.
+ *
+ * @template T
+ * @param {string} worktreeRoot
+ * @param {() => T} fn
+ * @returns {T}
+ */
+function withManifestLock(worktreeRoot, fn) {
+  const lock = acquireSweepLock({
+    lockPath: manifestLockPath(worktreeRoot),
+    timeoutMs: MANIFEST_LOCK_TIMEOUT_MS,
+  });
+  try {
+    return fn();
+  } finally {
+    if (lock.acquired) {
+      try {
+        lock.release();
+      } catch {
+        // Release is best-effort; a stale lockfile expires on its own.
+      }
+    }
+  }
+}
+
 export function readManifest(worktreeRoot) {
   const p = manifestPath(worktreeRoot);
   if (!fs.existsSync(p)) return [];
@@ -47,6 +115,13 @@ export function readManifest(worktreeRoot) {
   }
 }
 
+/**
+ * Write the manifest atomically: serialize into a pid-scoped temp file in the
+ * same directory (so `rename` stays within one filesystem and is therefore
+ * atomic), then rename it over the manifest. A concurrent reader sees either
+ * the whole previous manifest or the whole new one — never a truncated array
+ * that `readManifest`'s catch would silently turn into "no pending cleanups".
+ */
 function writeManifest(worktreeRoot, entries) {
   const p = manifestPath(worktreeRoot);
   if (!Array.isArray(entries) || entries.length === 0) {
@@ -58,7 +133,37 @@ function writeManifest(worktreeRoot, entries) {
     return;
   }
   fs.mkdirSync(worktreeRoot, { recursive: true });
-  fs.writeFileSync(p, `${JSON.stringify(entries, null, 2)}\n`, 'utf8');
+  writeFileAtomic(p, `${JSON.stringify(entries, null, 2)}\n`);
+}
+
+/**
+ * Write `contents` to `targetPath` atomically: serialize into a pid-scoped
+ * temp file beside it (same directory, so the rename stays within one
+ * filesystem and is therefore atomic), then rename it into place. On failure
+ * the temp file is reaped and the error propagates — a half-written file is
+ * never left where a reader could pick it up.
+ *
+ * @param {string} targetPath
+ * @param {string} contents
+ */
+function writeFileAtomic(targetPath, contents) {
+  const tmp = `${targetPath}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, contents, 'utf8');
+    fs.renameSync(tmp, targetPath);
+  } catch (err) {
+    reapTempFile(tmp);
+    throw err;
+  }
+}
+
+/** Best-effort removal of an abandoned atomic-write temp file. */
+function reapTempFile(tmp) {
+  try {
+    fs.unlinkSync(tmp);
+  } catch {
+    // Temp file already gone (or never created) — nothing to reap.
+  }
 }
 
 /**
@@ -71,38 +176,45 @@ export function recordPendingCleanup(
   worktreeRoot,
   { storyId, branch, path: wtPath, push = false },
 ) {
-  const now = new Date().toISOString();
-  const entries = readManifest(worktreeRoot);
-  const idx = entries.findIndex((e) => e.storyId === storyId);
-  if (idx >= 0) {
-    entries[idx] = {
-      ...entries[idx],
-      branch,
-      path: wtPath,
-      push,
-      lastFailedAt: now,
-      attempts: (entries[idx].attempts ?? 0) + 1,
-    };
-  } else {
-    entries.push({
-      storyId,
-      branch,
-      path: wtPath,
-      push,
-      firstFailedAt: now,
-      lastFailedAt: now,
-      attempts: 0,
-    });
-  }
-  writeManifest(worktreeRoot, entries);
-  return entries.find((e) => e.storyId === storyId);
+  // The read, the merge and the write are one critical section: without the
+  // lock a concurrent drain's write can land between our read and our write
+  // and erase this hand-off entirely.
+  return withManifestLock(worktreeRoot, () => {
+    const now = new Date().toISOString();
+    const entries = readManifest(worktreeRoot);
+    const idx = entries.findIndex((e) => e.storyId === storyId);
+    if (idx >= 0) {
+      entries[idx] = {
+        ...entries[idx],
+        branch,
+        path: wtPath,
+        push,
+        lastFailedAt: now,
+        attempts: (entries[idx].attempts ?? 0) + 1,
+      };
+    } else {
+      entries.push({
+        storyId,
+        branch,
+        path: wtPath,
+        push,
+        firstFailedAt: now,
+        lastFailedAt: now,
+        attempts: 0,
+      });
+    }
+    writeManifest(worktreeRoot, entries);
+    return entries.find((e) => e.storyId === storyId);
+  });
 }
 
 export function removePendingCleanup(worktreeRoot, storyId) {
-  const entries = readManifest(worktreeRoot).filter(
-    (e) => e.storyId !== storyId,
-  );
-  writeManifest(worktreeRoot, entries);
+  withManifestLock(worktreeRoot, () => {
+    const entries = readManifest(worktreeRoot).filter(
+      (e) => e.storyId !== storyId,
+    );
+    writeManifest(worktreeRoot, entries);
+  });
 }
 
 async function removeStuckWorktreePath(wtPath, { git, repoRoot, fsRm }) {
@@ -176,6 +288,32 @@ async function retryStage1ForEntry(entry, ctx) {
   return { success: true, ...cleanup };
 }
 
+/**
+ * Write the drain's result, merged against whatever the manifest holds *now*.
+ *
+ * The drain awaits a removal per entry, so its `entries` snapshot can be
+ * minutes old by the time it writes. Writing that snapshot back wholesale
+ * erased any entry a concurrent `recordPendingCleanup` added mid-drain — the
+ * exact hand-off that reap had just decided it could not complete. Merging by
+ * `storyId` keeps it: rows this pass re-computed win, rows it successfully
+ * drained are dropped, and everything else the manifest has gained survives.
+ *
+ * @param {string} worktreeRoot
+ * @param {object[]} next          Rows this drain re-computed (still pending).
+ * @param {Set<number|string>} drainedIds Story ids this drain cleared.
+ */
+function commitDrainedManifest(worktreeRoot, next, drainedIds) {
+  withManifestLock(worktreeRoot, () => {
+    const byId = new Map(next.map((entry) => [entry.storyId, entry]));
+    for (const entry of readManifest(worktreeRoot)) {
+      if (byId.has(entry.storyId)) continue;
+      if (drainedIds.has(entry.storyId)) continue;
+      byId.set(entry.storyId, entry);
+    }
+    writeManifest(worktreeRoot, [...byId.values()]);
+  });
+}
+
 /**
  * Drain the pending-cleanup manifest: for each entry, retry Stage 1
  * cleanup. Successful entries are removed; failing entries have their
@@ -252,7 +390,7 @@ export async function drainPendingCleanup({
     next.push(updated);
   }
 
-  writeManifest(worktreeRoot, next);
+  commitDrainedManifest(worktreeRoot, next, new Set(drained));
   return {
     drained,
     drainedDetails,

package/.agents/scripts/lib/worktree/node-modules-strategy.js

@@ -401,10 +401,7 @@ export function describeAttemptFailure(result, timeoutMs) {
 }
 
 /** Relative path of the per-machine pnpm-store prime sentinel (under tempRoot). */
-export const PNPM_STORE_PRIME_SENTINEL = path.join(
-  'temp',
-  '.pnpm-store-primed',
-);
+const PNPM_STORE_PRIME_SENTINEL = path.join('temp', '.pnpm-store-primed');
 
 /**
  * Pure: one-time per-machine pnpm content-addressable-store prime.
@@ -424,7 +421,7 @@ export const PNPM_STORE_PRIME_SENTINEL = path.join(
  *
  * @returns {{ primed: 'primed' | 'cached' | 'failed' | 'skipped', reason?: string }}
  */
-export function primePnpmStore({
+function primePnpmStore({
   strategy,
   repoRoot,
   logger,

package/.agents/scripts/notify.js

@@ -7,16 +7,10 @@
  * Single dispatch entry point for runtime notifications across two
  * independent channels.
  *
- * Lifecycle-bus integration (Epic #2172): under the Wave-7+ runtime,
- * `notify()` is invoked from the `NotifyDispatcher` listener
- * (`lib/orchestration/lifecycle/listeners/notify-dispatcher.js`),
- * which subscribes to lifecycle events and maps `event.severity` →
- * `notify()` payload. Direct inline calls at phase boundaries are no
- * longer the canonical path — listeners on the bus are. See
- * [`docs/LIFECYCLE.md`](../docs/LIFECYCLE.md) for the bus contract,
- * event taxonomy, and the dispatcher's wiring. Direct CLI / library
- * invocations remain supported for one-shot operator commands and the
- * structured-comment back-channel.
+ * Direct inline calls at phase boundaries are the only path: `notify()`
+ * is invoked from the caller that has something to say. Direct CLI /
+ * library invocations are equally supported, for one-shot operator
+ * commands and the structured-comment back-channel.
  *
  * Channels:
  *