mandrel 1.76.0 → 1.78.0

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

@@ -7,6 +7,15 @@
  *
  *   - `per-worktree`  — run the project's package-manager install inside the
  *                       worktree (lock-file aware).
+ *   - `clone`         — copy-on-write (reflink/clonefile) clone of the donor's
+ *                       `node_modules` into the worktree (`cp -c` on darwin,
+ *                       `cp --reflink=auto` on linux). Effectively free in time
+ *                       and disk on APFS / reflink-capable filesystems. Falls
+ *                       back to `per-worktree` cleanly on any failure
+ *                       (unsupported filesystem, cross-volume clone, Windows).
+ *                       When the worktree's lockfile byte-matches the donor's
+ *                       and the donor's install markers are present, the
+ *                       per-tree install is skipped.
  *   - `symlink`       — symlink (or junction on Windows) the worktree's
  *                       `node_modules` to a donor worktree's copy. Refuses on
  *                       Windows unless `allowSymlinkOnWindows=true`.
@@ -14,10 +23,11 @@
  *                       shared content-addressable store.
  *
  * The context passed to each helper carries the minimum state the strategy
- * needs: config, platform, logger, and repoRoot (for `symlink`).
+ * needs: config, platform, logger, and repoRoot (for `symlink` / `clone`).
  */
 
 import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { detectPackageManager } from '../detect-package-manager.js';
@@ -28,6 +38,21 @@ function sleepSync(ms) {
   Atomics.wait(signal, 0, 0, ms);
 }
 
+/**
+ * Resolve the copy-on-write clone donor directory. Defaults to the repo root
+ * (the main checkout, which is primed by the host's own install) unless the
+ * operator pinned a `primeFromPath`.
+ *
+ * @param {{ config: object, repoRoot: string }} ctx
+ * @returns {string} Absolute donor path.
+ */
+function resolveCloneDonor(ctx) {
+  const primeFromPath = ctx.config?.primeFromPath;
+  return primeFromPath
+    ? path.resolve(ctx.repoRoot, primeFromPath)
+    : path.resolve(ctx.repoRoot);
+}
+
 /**
  * Apply the configured `nodeModulesStrategy` after a fresh worktree is added.
  * Called only during creation.
@@ -43,6 +68,11 @@ export function applyNodeModulesStrategy(ctx, wtPath) {
     case 'pnpm-store':
       return;
 
+    case 'clone': {
+      cloneNodeModules(ctx, wtPath);
+      return;
+    }
+
     case 'symlink': {
       const primeFromPath = ctx.config.primeFromPath;
       if (!primeFromPath) {
@@ -89,17 +119,106 @@ export function applyNodeModulesStrategy(ctx, wtPath) {
     default:
       throw new Error(
         `WorktreeManager: unknown nodeModulesStrategy '${strategy}'. ` +
-          'Expected per-worktree | symlink | pnpm-store.',
+          'Expected per-worktree | clone | symlink | pnpm-store.',
       );
   }
 }
 
+/**
+ * Copy-on-write clone the donor's `node_modules` into the worktree. On a
+ * reflink-capable filesystem (APFS on darwin, btrfs/XFS/etc. on linux) the
+ * clone is effectively free in both time and disk; the subsequent
+ * lockfile-match probe in `installDependencies` then skips the per-tree
+ * install entirely.
+ *
+ * Non-fatal by design: any failure (unsupported filesystem, cross-volume
+ * clone, Windows, missing donor) falls back to `per-worktree` cleanly — the
+ * worktree is simply left without a cloned `node_modules`, and the regular
+ * per-tree install runs. Failure NEVER throws; the clone is a fast-path
+ * optimization, not a correctness requirement.
+ *
+ * @param {{ config: object, platform: NodeJS.Platform, logger: object, repoRoot: string }} ctx
+ * @param {string} wtPath Absolute worktree path.
+ * @param {{ spawnFn?: typeof spawnSync, fsLike?: typeof fs }} [io] Injectable for tests.
+ * @returns {{ cloned: boolean, reason?: string }}
+ */
+export function cloneNodeModules(ctx, wtPath, io = {}) {
+  const spawnFn = io.spawnFn ?? spawnSync;
+  const fsLike = io.fsLike ?? fs;
+  // Key off the real host OS, not the test-injection `ctx.platform`, for the
+  // capability decision: Windows has no `cp -c`/`--reflink` equivalent here.
+  if (process.platform === 'win32') {
+    ctx.logger.info(
+      'worktree.node_modules strategy=clone fallback=per-worktree reason=windows-unsupported',
+    );
+    return { cloned: false, reason: 'windows-unsupported' };
+  }
+
+  const donor = resolveCloneDonor(ctx);
+  const donorNodeModules = path.join(donor, 'node_modules');
+  if (!fsLike.existsSync(donorNodeModules)) {
+    ctx.logger.info(
+      `worktree.node_modules strategy=clone fallback=per-worktree reason=donor-node-modules-missing donor=${donorNodeModules}`,
+    );
+    return { cloned: false, reason: 'donor-node-modules-missing' };
+  }
+
+  const target = path.join(wtPath, 'node_modules');
+  if (fsLike.existsSync(target)) {
+    // A worktree that already carries node_modules must not be clobbered by a
+    // clone-on-top (cp would nest into the existing dir). Treat as already
+    // populated and let the install-skip probe decide freshness.
+    ctx.logger.info(
+      `worktree.node_modules strategy=clone skip reason=target-exists target=${target}`,
+    );
+    return { cloned: false, reason: 'target-exists' };
+  }
+
+  // darwin: `cp -c` requests a clonefile (APFS). linux: `cp --reflink=auto`
+  // requests a reflink, silently degrading to a full copy on non-reflink
+  // filesystems — which we deliberately reject below so a slow full-tree copy
+  // never masquerades as a free clone.
+  const cloneArgs =
+    process.platform === 'darwin'
+      ? ['-c', '-R', donorNodeModules, target]
+      : ['--reflink=always', '-R', donorNodeModules, target];
+  const result = spawnFn('cp', cloneArgs, {
+    cwd: wtPath,
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    timeout: 120_000,
+  });
+  if (result.status !== 0) {
+    // Clean up a partial copy so the per-worktree fallback install starts from
+    // a known-empty target.
+    try {
+      fsLike.rmSync(target, { recursive: true, force: true });
+    } catch {
+      // best-effort
+    }
+    ctx.logger.warn(
+      `worktree.node_modules strategy=clone fallback=per-worktree reason=clone-command-failed ` +
+        `(${describeAttemptFailure(result, 120_000)}) stderr=${(result.stderr ?? '').slice(0, 300)}`,
+    );
+    return { cloned: false, reason: 'clone-command-failed' };
+  }
+
+  ctx.logger.info(
+    `worktree.node_modules strategy=clone target=${target} source=${donorNodeModules}`,
+  );
+  return { cloned: true };
+}
+
 /**
  * Pure: pick the package-manager command + args for a given strategy and
  * worktree path. Returns `null` when the strategy is `symlink` (handled
  * elsewhere) or the worktree has no `package.json`.
  *
- * @param {string} strategy One of `per-worktree | pnpm-store | symlink`.
+ * `clone` shares `per-worktree`'s PM-detection: when the install is *not*
+ * skipped (lockfile mismatch), the worktree still installs with the project's
+ * detected package manager.
+ *
+ * @param {string} strategy One of `per-worktree | clone | pnpm-store | symlink`.
  * @param {string} wtPath Absolute worktree path.
  * @param {{ existsSync: (p: string) => boolean }} [fsLike] Injectable for tests.
  * @returns {{ cmd: string, args: string[] } | null}
@@ -112,6 +231,7 @@ export function selectInstallCommand(strategy, wtPath, fsLike = fs) {
     return { cmd: 'pnpm', args: ['install', '--frozen-lockfile'] };
   }
   // Shared lockfile probe (Story #4048 B3 — one implementation per concept).
+  // `per-worktree` and `clone` both fall through to PM detection here.
   const pm = detectPackageManager(wtPath, (p) => fsLike.existsSync(p)) ?? 'npm';
   if (pm === 'pnpm') {
     return { cmd: 'pnpm', args: ['install', '--frozen-lockfile'] };
@@ -138,14 +258,78 @@ const INSTALL_MARKERS = [
 
 const LOCKFILES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'];
 
-function safeMtimeMs(fsLike, p) {
+/**
+ * Pure: locate the first present lockfile in `dir` and return its byte-exact
+ * SHA-256 hash, or `null` when no lockfile exists / cannot be read.
+ *
+ * The hash is the load-bearing freshness key for the install-skip decision —
+ * never an mtime, which clone (clonefile/reflink) does not preserve reliably
+ * and which is trivially perturbed by a no-op `git checkout`.
+ *
+ * @param {string} dir Absolute directory containing the lockfile.
+ * @param {{ existsSync: Function, readFileSync: Function }} [fsLike]
+ * @returns {string | null}
+ */
+export function lockfileHash(dir, fsLike = fs) {
+  const lockfile = LOCKFILES.map((l) => path.join(dir, l)).find((p) =>
+    fsLike.existsSync(p),
+  );
+  if (!lockfile) return null;
   try {
-    return fsLike.statSync(p).mtimeMs;
+    const bytes = fsLike.readFileSync(lockfile);
+    return crypto.createHash('sha256').update(bytes).digest('hex');
   } catch {
     return null;
   }
 }
 
+/**
+ * Pure: the single shared "is the per-tree install skippable?" predicate
+ * (generalized from `probeReusedInstall`). The install is safe to skip iff:
+ *
+ *   1. the worktree carries a completed-install marker
+ *      (`node_modules/<INSTALL_MARKERS>`), AND
+ *   2. the worktree's lockfile byte-exactly matches the donor's lockfile.
+ *
+ * The lockfile match is keyed on a byte-exact SHA-256 hash, NEVER mtime: a
+ * reflink/clonefile clone does not preserve mtime relationships, so an mtime
+ * comparison would either mis-skip a real change or force a redundant install
+ * on every clone. When the donor is omitted (reuse path, no clone donor), the
+ * worktree's own lockfile is hashed against itself — i.e. the lockfile-match
+ * leg is vacuously satisfied and only the marker presence gates the skip.
+ *
+ * @param {object} opts
+ * @param {string} opts.wtPath Absolute worktree path.
+ * @param {string} [opts.donorPath] Absolute donor path (the clone source).
+ * @param {{ existsSync: Function, readFileSync: Function }} [opts.fsLike]
+ * @returns {{ skippable: boolean, reason: string }}
+ */
+export function isInstallSkippable({ wtPath, donorPath, fsLike = fs }) {
+  const nmPath = path.join(wtPath, 'node_modules');
+  if (!fsLike.existsSync(nmPath)) {
+    return { skippable: false, reason: 'node-modules-missing' };
+  }
+  const marker = INSTALL_MARKERS.map((m) => path.join(nmPath, m)).find((p) =>
+    fsLike.existsSync(p),
+  );
+  if (!marker) {
+    return { skippable: false, reason: 'install-incomplete' };
+  }
+  const wtHash = lockfileHash(wtPath, fsLike);
+  if (wtHash === null) {
+    // No lockfile in the worktree — nothing to pin freshness against. The
+    // marker alone is the signal (matches a lockfile-less project).
+    return { skippable: true, reason: 'marker-present-no-lockfile' };
+  }
+  if (donorPath) {
+    const donorHash = lockfileHash(donorPath, fsLike);
+    if (donorHash !== null && donorHash !== wtHash) {
+      return { skippable: false, reason: 'lockfile-mismatch' };
+    }
+  }
+  return { skippable: true, reason: 'lockfile-match' };
+}
+
 /**
  * Pure: probe whether a **reused** worktree already carries a completed,
  * up-to-date install. Worktree reuse must not blindly report
@@ -157,12 +341,17 @@ function safeMtimeMs(fsLike, p) {
  *   - `{ status: 'skipped', reason: 'worktree-reused' }` — a completed
  *     install was detected (or the strategy never installs per-tree);
  *     safe to skip.
- *   - `{ status: 'failed', reason }` — missing/incomplete/stale install
- *     detected; callers should retry the install.
+ *   - `{ status: 'failed', reason }` — missing/incomplete install detected;
+ *     callers should retry the install.
  *
- * @param {string} strategy One of `per-worktree | pnpm-store | symlink`.
+ * Thin wrapper over the shared `isInstallSkippable` predicate (Story #4249 —
+ * one freshness predicate, keyed on a byte-exact lockfile hash, never mtime).
+ * The reuse path has no separate donor, so freshness reduces to marker
+ * presence (the worktree's own lockfile is its own baseline).
+ *
+ * @param {string} strategy One of `per-worktree | clone | pnpm-store | symlink`.
  * @param {string} wtPath Absolute worktree path.
- * @param {{ existsSync: Function, statSync: Function }} [fsLike] Injectable for tests.
+ * @param {{ existsSync: Function, readFileSync: Function }} [fsLike] Injectable for tests.
  * @returns {{ status: 'skipped' | 'failed', reason: string }}
  */
 export function probeReusedInstall(strategy, wtPath, fsLike = fs) {
@@ -173,34 +362,33 @@ export function probeReusedInstall(strategy, wtPath, fsLike = fs) {
   if (!fsLike.existsSync(path.join(wtPath, 'package.json'))) {
     return { status: 'skipped', reason: 'no-package-json' };
   }
-  const nmPath = path.join(wtPath, 'node_modules');
-  if (!fsLike.existsSync(nmPath)) {
-    return { status: 'failed', reason: 'reuse-node-modules-missing' };
-  }
-  const marker = INSTALL_MARKERS.map((m) => path.join(nmPath, m)).find((p) =>
-    fsLike.existsSync(p),
-  );
-  if (!marker) {
-    return { status: 'failed', reason: 'reuse-install-incomplete' };
-  }
-  const markerMtime = safeMtimeMs(fsLike, marker);
-  const lockfile = LOCKFILES.map((l) => path.join(wtPath, l)).find((p) =>
-    fsLike.existsSync(p),
-  );
-  if (lockfile && markerMtime !== null) {
-    const lockMtime = safeMtimeMs(fsLike, lockfile);
-    if (lockMtime !== null && lockMtime > markerMtime) {
-      return { status: 'failed', reason: 'reuse-node-modules-stale' };
-    }
+  const probe = isInstallSkippable({ wtPath, fsLike });
+  if (probe.skippable) {
+    return { status: 'skipped', reason: 'worktree-reused' };
   }
-  return { status: 'skipped', reason: 'worktree-reused' };
+  return {
+    status: 'failed',
+    reason:
+      probe.reason === 'node-modules-missing'
+        ? 'reuse-node-modules-missing'
+        : 'reuse-install-incomplete',
+  };
 }
 
-/** Pure: retry policy keyed off the chosen command. pnpm gets 3× + 5min. */
+/**
+ * Pure: retry policy keyed off the chosen command. pnpm gets 3× + 5min.
+ *
+ * Story #4249: npm/yarn now get a real `maxAttempts` of 2 (was 1). The
+ * formerly hardcoded `npm ci` retry inside `runStoryInitPrepare` was deleted
+ * in the same change; this in-`ensure` retry budget is what compensates so
+ * npm install reliability does not regress — a transient first-attempt
+ * failure now retries here, with the correct (PM-detected) command, instead
+ * of an unconditional `npm ci` re-run after init.
+ */
 export function installRetryPolicy(cmd) {
   const isPnpm = cmd === 'pnpm';
   return {
-    maxAttempts: isPnpm ? 3 : 1,
+    maxAttempts: isPnpm ? 3 : 2,
     timeoutMs: isPnpm ? 300_000 : 120_000,
     backoffMs: [0, 2_000, 5_000],
   };
@@ -387,6 +575,26 @@ export function installDependencies(ctx, wtPath) {
   if (selection === null) {
     return { status: 'skipped', reason: 'no-package-json' };
   }
+  // `clone` reflink-clones the donor's node_modules in `applyNodeModulesStrategy`.
+  // When the cloned tree carries a completed-install marker AND the worktree's
+  // lockfile byte-matches the donor's, the per-tree install is pure waste —
+  // skip it. The freshness predicate is the single shared `isInstallSkippable`
+  // (byte-exact lockfile hash, never mtime). On a lockfile mismatch (donor
+  // drifted, or no clone happened) this returns false and the install below
+  // runs normally.
+  if (strategy === 'clone') {
+    const donor = resolveCloneDonor(ctx);
+    const probe = isInstallSkippable({ wtPath, donorPath: donor });
+    if (probe.skippable) {
+      ctx.logger.info(
+        `worktree.install strategy=clone skip reason=${probe.reason} path=${wtPath}`,
+      );
+      return { status: 'skipped', reason: `clone-${probe.reason}` };
+    }
+    ctx.logger.info(
+      `worktree.install strategy=clone install reason=${probe.reason} path=${wtPath}`,
+    );
+  }
   // Prime the pnpm content-addressable store once per machine before the
   // worktree's own install runs. No-op for non-pnpm-store strategies. Prime
   // failures are surfaced as warnings but do not short-circuit the install —

package/.agents/scripts/providers/github/branch-protection.js

@@ -13,8 +13,8 @@
  * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
  */
 
+import { withTransientRetry } from './errors.js';
 import { parseApiJson } from './request-helpers.js';
-import { withTransientRetry } from './transient-retry.js';
 
 /**
  * Detect a 404 across both error surfaces:

package/.agents/scripts/providers/github/errors.js

@@ -48,6 +48,40 @@ const TRANSIENT_MESSAGES = [
 
 const PERMISSION_MESSAGES = ['unauthorized', 'forbidden', 'permission'];
 
+// Network/connectivity blips that the gh-CLI path surfaces on `err.stderr`
+// (Go HTTP errors, e.g. `dial tcp ...: i/o timeout`) and the direct `fetch`
+// path surfaces as `TypeError: fetch failed` with the real reason on
+// `err.cause` (e.g. `ETIMEDOUT`, `ENOTFOUND`). Folded in from the former
+// `transient-retry.js` predicate (Story #4298) so the single canonical
+// classifier retries the **union** of transient HTTP statuses/codes AND
+// transient network errors. The `\b50[234]\b` alternative also catches a
+// bare 502/503/504 surfaced only in an error message string (no `.status`).
+const TRANSIENT_NETWORK_RE =
+  /i\/o timeout|dial tcp|TLS handshake timeout|connection reset|connection refused|temporary failure|could not resolve host|no such host|network is unreachable|socket hang up|fetch failed|ConnectTimeoutError|UND_ERR_CONNECT_TIMEOUT|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|\b50[234]\b/i;
+
+/**
+ * True when an error looks like a retryable network/connectivity blip.
+ * Scans the union of fields both transport paths populate (`stderr`,
+ * `message`, `code`, and the nested `cause.message` / `cause.code` the
+ * `fetch` path uses). Module-private — folded in from the former
+ * `transient-retry.js` predicate (Story #4298) and consumed only by
+ * `classifyGithubError` below; its behavior is exercised through that public
+ * classifier rather than as a standalone export (keeps the dead-export gate
+ * green — nothing outside this module imports it).
+ */
+function isTransientNetworkError(err) {
+  const hay = [
+    err?.stderr,
+    err?.message,
+    err?.code,
+    err?.cause?.message,
+    err?.cause?.code,
+  ]
+    .filter(Boolean)
+    .join(' ');
+  return TRANSIENT_NETWORK_RE.test(hay);
+}
+
 function matchesAny(haystack, needles) {
   for (const n of needles) if (haystack.includes(n)) return true;
   return false;
@@ -97,19 +131,36 @@ export function classifyGithubError(err) {
   if (matchesAny(lower, FEATURE_DISABLED_MESSAGES)) return 'feature-disabled';
   if (isTransientStatus(status)) return 'transient';
   if (isTransientByCodeOrMessage(code, lower)) return 'transient';
+  // Union with the former `transient-retry.js` predicate (Story #4298):
+  // retry on network/connectivity blips the status/code checks above miss
+  // (e.g. a `dial tcp ... i/o timeout` on `err.stderr` from the gh-CLI path,
+  // or `ECONNREFUSED` / `ENETUNREACH`). Checked before the permission rule so
+  // a transient network failure never masquerades as a permanent denial.
+  if (isTransientNetworkError(err)) return 'transient';
   if (isPermissionSignal(status, lower)) return 'permission';
   return 'permanent';
 }
 
 // ---------------------------------------------------------------------------
-// Transient-retry helper (Story #2852)
+// Transient-retry helper (Story #2852; unified in Story #4298)
 // ---------------------------------------------------------------------------
 //
+// The single canonical `withTransientRetry` for the GitHub provider. Story
+// #4298 collapsed the former two divergent same-named implementations (this
+// one + the network-only one in the deleted `transient-retry.js`) into this
+// one primitive. Its default classifier (`classifyGithubError`) is the
+// **union** predicate — it retries on transient HTTP statuses/codes AND on
+// transient network/connectivity errors — so every former consumer of either
+// module keeps (or gains) its prior retry coverage with no shim.
+//
 // Mirrors the addSubIssue retry contract in `sub-issues.js` so read-path
 // callers (paginateRest, getTicket, getNativeSubIssues, …) absorb the same
 // jittered exponential backoff on transient GitHub errors instead of
 // bubbling a one-shot 502/429/ECONNRESET that kills a longer pipeline
-// (e.g. the /deliver Phase E retro).
+// (e.g. the /deliver Phase E retro). The network consumers repointed here
+// (branch-protection, labels, projects-v2-graphql) call with no opts, so
+// they adopt these defaults; their retry *classes* (the network blips) are
+// preserved via the unified classifier above.
 
 export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
   maxAttempts: 6,

package/.agents/scripts/providers/github/labels.js

@@ -16,7 +16,7 @@
  * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
  */
 
-import { withTransientRetry } from './transient-retry.js';
+import { withTransientRetry } from './errors.js';
 
 /**
  * Detect the "label already exists" signal across the surfaces `gh label

package/.agents/scripts/providers/github/projects-v2-graphql.js

@@ -7,7 +7,7 @@
  * `unavailable:true` envelopes. Wave 3 deletes the old submodules.
  */
 import { execSync } from 'node:child_process';
-import { withTransientRetry } from './transient-retry.js';
+import { withTransientRetry } from './errors.js';
 
 // Resolve an owner node id per-scope. Querying `user` and `organization`
 // together in one request makes GitHub return a NOT_FOUND error for whichever

package/.agents/scripts/resync-status-column.js

@@ -127,6 +127,7 @@ export function buildReassertOptions({
   logger,
   pollAttempts,
   pollDelayMs,
+  config,
 }) {
   const opts = {
     provider,
@@ -135,6 +136,9 @@ export function buildReassertOptions({
   };
   if (pollAttempts !== undefined) opts.pollAttempts = pollAttempts;
   if (pollDelayMs !== undefined) opts.pollDelayMs = pollDelayMs;
+  // Story #4252 — forward the resolved config so ColumnSync's on-disk
+  // board-metadata cache lands under the project's configured tempRoot.
+  if (config !== undefined) opts.config = config;
   return opts;
 }
 
@@ -168,6 +172,7 @@ export async function main(argv = process.argv.slice(2)) {
       logger: Logger,
       pollAttempts,
       pollDelayMs,
+      config: effectiveConfig,
     }),
   );
   process.stdout.write(`${JSON.stringify({ ticketId, ...result })}\n`);

package/.agents/scripts/run-coverage.js

@@ -27,6 +27,14 @@
  * `c8 report` path is ~19% faster end-to-end on a Windows dev host
  * while producing an identical `coverage-final.json` artifact for the
  * CRAP gate.
+ *
+ * Test-runner concurrency: the suite spawn reuses `TEST_RUNNER_FLAGS`
+ * from `run-tests.js` — the single source of truth for the
+ * `--test-concurrency` value, derived at startup from the host's
+ * available parallelism and clamped to `[TEST_CONCURRENCY_MIN,
+ * TEST_CONCURRENCY_MAX]`. This keeps the coverage gate (which runs the
+ * suite at every story close on both delivery paths) host-aware instead
+ * of pinned to the historical literal of 8.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -37,6 +45,7 @@ import { fileURLToPath } from 'node:url';
 
 import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
 import { C8_CLI } from './lib/c8-cli-path.js';
+import { TEST_RUNNER_FLAGS } from './run-tests.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..', '..');
@@ -45,59 +54,90 @@ const require = createRequire(import.meta.url);
 const C8_CONFIG = require('../../.c8rc.cjs');
 const V8_TMP = path.join(COVERAGE_DIR, 'tmp');
 
-rmSync(COVERAGE_DIR, { recursive: true, force: true });
-mkdirSync(V8_TMP, { recursive: true });
+/**
+ * Build the `node --test` argv for the coverage suite spawn.
+ *
+ * Reuses the shared `TEST_RUNNER_FLAGS` (the single source of truth for
+ * the host-aware, clamped `--test-concurrency` value) so the coverage
+ * path never drifts from `run-tests.js`. The `runnerFlags` parameter is
+ * injected in tests so the argv can be asserted without touching the OS.
+ *
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.runnerFlags]
+ * @param {string} [opts.testGlob]
+ * @returns {string[]}
+ */
+export function buildCoverageTestArgs({
+  runnerFlags = TEST_RUNNER_FLAGS,
+  testGlob = 'tests/**/*.test.js',
+} = {}) {
+  return [...runnerFlags, testGlob];
+}
+
+/**
+ * Execute the coverage pipeline: run the suite under `NODE_V8_COVERAGE`,
+ * post-process the dumps with `c8 report`, then gate on the coverage
+ * baseline. Returns the first non-zero exit code across the three stages
+ * (or the baseline check's status when both prior stages pass).
+ *
+ * @returns {number}
+ */
+function runCoveragePipeline() {
+  rmSync(COVERAGE_DIR, { recursive: true, force: true });
+  mkdirSync(V8_TMP, { recursive: true });
 
-const testRun = spawnSync(
-  process.execPath,
-  [
-    '--experimental-test-module-mocks',
-    '--test',
-    '--test-concurrency=8',
-    'tests/**/*.test.js',
-  ],
-  {
+  const testRun = spawnSync(process.execPath, buildCoverageTestArgs(), {
     cwd: ROOT,
     stdio: 'inherit',
     env: { ...process.env, NODE_V8_COVERAGE: V8_TMP },
-  },
-);
+  });
 
-cleanupRepoTestTempArtifacts({ repoRoot: ROOT });
+  cleanupRepoTestTempArtifacts({ repoRoot: ROOT });
 
-const includeArgs = (C8_CONFIG.include ?? []).flatMap((p) => ['--include', p]);
-const excludeArgs = (C8_CONFIG.exclude ?? []).flatMap((p) => ['--exclude', p]);
+  const includeArgs = (C8_CONFIG.include ?? []).flatMap((p) => [
+    '--include',
+    p,
+  ]);
+  const excludeArgs = (C8_CONFIG.exclude ?? []).flatMap((p) => [
+    '--exclude',
+    p,
+  ]);
 
-const reportRun = spawnSync(
-  process.execPath,
-  [
-    C8_CLI,
-    'report',
-    '--reporter=json',
-    '--reporter=text',
-    '--temp-directory',
-    V8_TMP,
-    ...includeArgs,
-    ...excludeArgs,
-  ],
-  { cwd: ROOT, stdio: 'inherit', shell: false },
-);
+  const reportRun = spawnSync(
+    process.execPath,
+    [
+      C8_CLI,
+      'report',
+      '--reporter=json',
+      '--reporter=text',
+      '--temp-directory',
+      V8_TMP,
+      ...includeArgs,
+      ...excludeArgs,
+    ],
+    { cwd: ROOT, stdio: 'inherit', shell: false },
+  );
 
-const checkRun = spawnSync(
-  process.execPath,
-  [
-    path.join(ROOT, '.agents', 'scripts', 'check-baselines.js'),
-    '--gate',
-    'coverage',
-  ],
-  { cwd: ROOT, stdio: 'inherit' },
-);
+  const checkRun = spawnSync(
+    process.execPath,
+    [
+      path.join(ROOT, '.agents', 'scripts', 'check-baselines.js'),
+      '--gate',
+      'coverage',
+    ],
+    { cwd: ROOT, stdio: 'inherit' },
+  );
 
-const exitCode =
-  testRun.status !== 0
-    ? testRun.status
+  return testRun.status !== 0
+    ? (testRun.status ?? 1)
     : reportRun.status !== 0
-      ? reportRun.status
-      : checkRun.status;
+      ? (reportRun.status ?? 1)
+      : (checkRun.status ?? 1);
+}
 
-process.exit(exitCode ?? 1);
+// Run the pipeline only when invoked directly as a CLI; importing the
+// module (e.g. from a test asserting the spawn argv) must not spawn the
+// real suite.
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+  process.exit(runCoveragePipeline());
+}

package/.agents/scripts/run-lint.js

@@ -78,6 +78,17 @@ const tasks = [
     cmd: 'node',
     args: ['.agents/scripts/check-arch-cycles.js'],
   },
+  {
+    // Loop-unit frontmatter gate (Story #4288, Epic #4284). Validates
+    // every `.agents/workflows/loops/*.md` loop unit against
+    // `.agents/schemas/loop-unit.schema.json`. An absent/empty loops
+    // directory is a clean pass; a malformed unit (e.g. a self-paced
+    // cadence missing its required `verify`) fails the lint gate with a
+    // message naming the offending file + field.
+    name: 'loop-units',
+    cmd: 'node',
+    args: ['.agents/scripts/check-loop-units.js'],
+  },
 ];
 
 function runTask({ name, cmd, args }) {