mandrel 1.58.0 → 1.59.0

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

@@ -0,0 +1,93 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { Logger } from './Logger.js';
+
+const require = createRequire(import.meta.url);
+
+const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+
+let _ts = null;
+let _tsLoadFailed = false;
+
+function loadTypeScript() {
+  if (_ts) return _ts;
+  if (_tsLoadFailed) return null;
+  try {
+    _ts = require('typescript');
+    return _ts;
+  } catch {
+    _tsLoadFailed = true;
+    return 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.
+ *
+ * @returns {string}
+ */
+export function resolveTsTranspilerVersion() {
+  const ts = loadTypeScript();
+  if (ts && typeof ts.version === 'string') return ts.version;
+  return '0.0.0';
+}
+
+function isTypeScriptPath(filePath) {
+  return TS_EXTS.has(path.extname(String(filePath)).toLowerCase());
+}
+
+/**
+ * Pre-transpile TypeScript or TSX sources to JavaScript that the
+ * Esprima-based escomplex kernel can parse. Returns the input unchanged
+ * for `.js` / `.mjs` / `.cjs` paths.
+ *
+ * Type annotations introduce no control flow, so the transpiled output
+ * scores identically to the original TS for cyclomatic complexity,
+ * Halstead volume, and the maintainability index. `.tsx` uses the
+ * `react-jsx` emit so JSX expressions become function calls escomplex
+ * can read; `.preserve` would leave JSX in the output and Esprima would
+ * choke on it.
+ *
+ * On transpile failure the helper returns `null` — callers treat that
+ * as "skip this file" rather than crashing the scan.
+ *
+ * @param {string} filePath
+ * @param {string} source
+ * @returns {string|null}
+ */
+export function transpileIfNeeded(filePath, source) {
+  if (!isTypeScriptPath(filePath)) return source;
+  const ts = loadTypeScript();
+  if (!ts) {
+    Logger.warn(
+      `[Maintainability] ⚠ typescript package not resolvable; cannot score ${filePath}. ` +
+        "Install with 'npm install --save-dev typescript' (peer dep, >=5.0.0).",
+    );
+    return null;
+  }
+  try {
+    const result = ts.transpileModule(source, {
+      compilerOptions: {
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        isolatedModules: true,
+        noEmitHelpers: true,
+        importHelpers: false,
+        removeComments: false,
+        jsx: ts.JsxEmit.ReactJSX,
+        sourceMap: false,
+      },
+      fileName: path.basename(filePath),
+      reportDiagnostics: false,
+    });
+    return result.outputText;
+  } catch (err) {
+    Logger.warn(
+      `[Maintainability] ⚠ TS transpile failed for ${filePath}: ${err?.message ?? err}; skipping.`,
+    );
+    return null;
+  }
+}

package/.agents/scripts/lib/wave-runner/tick.js

@@ -36,22 +36,11 @@ import { WaveRunnerError } from './wave-runner-error.js';
  *   currentWave:    number
  *   totalWaves:     number
  *
- * When `spec` is omitted, the planner falls back to the checkpoint's
- * `state.plan` (the GH-derived dependency-DAG grouping originally seeded
- * by /epic-plan) — behaviour is byte-identical to the pre-spec path.
- * When `spec` is supplied, wave grouping is driven by `spec.stories[].wave`
- * (the declarative SSOT from `.agents/epics/<epic-id>.yaml`) and slugs are
- * resolved to GH issue numbers via the sibling `<epic-id>.state.json`
- * mapping; the checkpoint is still consulted for `currentWave`,
- * `totalWaves`, and `waves[]` history but its `plan[]` is overridden.
+ * Wave grouping comes from the checkpoint's `state.plan` (the GH-derived
+ * dependency-DAG grouping originally seeded by /epic-plan).
  *
  * @typedef {object} WaveTickArgs
  * @property {number | { id: number }} epic
- * @property {object} [spec] Parsed epic-spec (see lib/spec/loader.js). When
- *   provided, wave grouping comes from `spec.stories[].wave`.
- * @property {object} [state] Parsed epic-state (see lib/spec/loader.js).
- *   When `spec` is provided, this must be supplied so slugs can resolve to
- *   issue numbers via `state.mapping[slug].issueNumber`.
  * @property {{
  *   provider?: object,
  *   epicRunStateStore?: { read: () => Promise<object|null> },
@@ -74,8 +63,6 @@ export async function tick(args = {}) {
   } = args.collaborators ?? {};
   const ctx = args.ctx ?? {};
   const provider = collabProvider ?? ctx.provider;
-  const spec = args.spec ?? null;
-  const specState = args.state ?? null;
   if (!provider) {
     throw new WaveRunnerError('invalid-input', 'provider is required');
   }
@@ -104,7 +91,8 @@ export async function tick(args = {}) {
   }
 
   const currentWave = positiveIntOrZero(state.currentWave);
-  const { plan, totalWaves } = resolvePlan(state, spec, specState);
+  const plan = Array.isArray(state.plan) ? state.plan : [];
+  const totalWaves = positiveIntOrZero(state.totalWaves);
   const history = Array.isArray(state.waves) ? state.waves : [];
 
   if (totalWaves === 0 || currentWave >= totalWaves) {
@@ -460,143 +448,6 @@ function storyIdOf(s) {
   return s.id ?? s.storyId ?? s.number;
 }
 
-/**
- * Walk `spec.features[].stories[]` and bucket entries by their `wave`
- * value, mapping slugs → GH issue numbers via the sibling state file.
- * Returns `Story[][]` indexed by wave number; missing waves between 0 and
- * the highest declared wave are emitted as empty arrays so wave N is
- * always reachable as `plan[N]`.
- *
- * Each emitted entry is shaped to match the checkpoint plan's
- * `{ id, title }` contract that the rest of `tick()` already consumes:
- *
- *   - `id` is the GH issue number resolved from `state.mapping[slug].issueNumber`
- *     so the same provider.getTicket(id) path used by the spec-less plan
- *     keeps working unchanged.
- *   - `title` is carried through from `story.title` so the wave-start
- *     signal can include the Story's human-readable name without an
- *     extra provider round-trip.
- *   - `slug` is preserved on the entry so observability + future
- *     re-resolution paths can re-key against the spec.
- *
- * When a Story slug has no resolved `issueNumber` in `state.mapping`
- * (a fresh spec entry the reconciler has not materialised yet), the entry
- * is skipped — un-materialised Stories cannot be dispatched anyway, and
- * including them with a `null` id would surface as a `story-fetch`
- * failure inside `tick()`. The reconciler will close the loop on the
- * next apply; until then, an empty wave is a faithful reflection of
- * GitHub state.
- *
- * Pure function — does not read disk, does not call GH. Callers are
- * expected to compose it with `loadSpec` + `loadState` from
- * `lib/spec/loader.js`.
- *
- * @param {object} spec Parsed epic-spec (see lib/spec/loader.js).
- * @param {{mapping?: Record<string, {issueNumber?: number}>}|null} [state]
- *   Parsed epic-state. May be omitted; if missing, no entries can be
- *   resolved and `groupByWave` returns `[]`.
- * @returns {Array<Array<{id: number, title?: string, slug: string}>>}
- */
-export function groupByWave(spec, state = null) {
-  const mapping =
-    state && typeof state.mapping === 'object' && state.mapping !== null
-      ? state.mapping
-      : {};
-  const entries = extractValidStoryEntries(spec, mapping);
-  if (entries.length === 0) return [];
-  const byWave = new Map();
-  let maxWave = -1;
-  for (const { wave, entry } of entries) {
-    if (!byWave.has(wave)) byWave.set(wave, []);
-    byWave.get(wave).push(entry);
-    if (wave > maxWave) maxWave = wave;
-  }
-  if (maxWave < 0) return [];
-  const out = [];
-  for (let i = 0; i <= maxWave; i += 1) {
-    out.push(byWave.get(i) ?? []);
-  }
-  return out;
-}
-
-/**
- * Walk every feature/story pair in `spec` and emit only the entries that
- * survive the spec-validity cascade: the story must be a non-null object,
- * declare a non-negative integer `wave`, declare a string `slug`, and
- * resolve to a numeric `issueNumber` in `mapping`. Each surviving entry
- * is returned as `{ wave, entry }` where `entry` carries the same shape
- * (`{ id, title, slug }`) that `groupByWave` previously pushed into its
- * per-wave bucket.
- *
- * Extracted from `groupByWave` so the bucketing transform stays
- * straight-line; this predicate owns the entire defensive guard cascade
- * and is the right place to add new validation rules going forward.
- *
- * @param {object|null|undefined} spec Parsed epic-spec.
- * @param {Record<string, {issueNumber?: number}>} mapping
- *   Slug → issue-number lookup from the sibling state file.
- * @returns {Array<{wave: number, entry: {id: number, title?: string, slug: string}}>}
- */
-export function extractValidStoryEntries(spec, mapping) {
-  const out = [];
-  const features = Array.isArray(spec?.features) ? spec.features : [];
-  for (const feature of features) {
-    const stories = Array.isArray(feature?.stories) ? feature.stories : [];
-    for (const story of stories) {
-      const resolved = resolveStoryEntry(story, mapping);
-      if (resolved) out.push(resolved);
-    }
-  }
-  return out;
-}
-
-/**
- * Validate a single `story` against the spec-validity cascade and return
- * `{ wave, entry }` when every guard passes, or `null` when any guard
- * trips. Splitting the per-story cascade out keeps both
- * `extractValidStoryEntries` (which owns iteration) and `resolveStoryEntry`
- * (which owns validation) below CRAP 5 even when none of the branches are
- * exercised at runtime — the predicate's cyclomatic footprint is small
- * enough that uncovered branches do not blow the baseline budget.
- *
- * @param {*} story Candidate story from `spec.features[].stories[]`.
- * @param {Record<string, {issueNumber?: number}>} mapping Slug → issue lookup.
- * @returns {{wave: number, entry: {id: number, title?: string, slug: string}} | null}
- */
-function resolveStoryEntry(story, mapping) {
-  if (!story || typeof story !== 'object') return null;
-  if (!Number.isInteger(story.wave) || story.wave < 0) return null;
-  if (typeof story.slug !== 'string' || !story.slug) return null;
-  const mapped = mapping[story.slug];
-  if (!mapped || typeof mapped.issueNumber !== 'number') return null;
-  return {
-    wave: story.wave,
-    entry: { id: mapped.issueNumber, title: story.title, slug: story.slug },
-  };
-}
-
-/**
- * Resolve which plan + totalWaves drive this tick. When `spec` is
- * supplied, the spec-derived grouping wins (and totalWaves comes from
- * the spec since the checkpoint may lag); otherwise the checkpoint's
- * plan is used unchanged. Extracted so `tick()`'s cyclomatic complexity
- * stays inside its baseline budget — the route choice is now a single
- * call, not three ternaries inline.
- *
- * @param {object} state Checkpoint state (already validated as object).
- * @param {object|null} spec Parsed epic-spec or `null` when omitted.
- * @param {object|null} specState Parsed epic-state for slug mapping.
- * @returns {{plan: Array<Array<object>>, totalWaves: number}}
- */
-function resolvePlan(state, spec, specState) {
-  if (spec) {
-    const specPlan = groupByWave(spec, specState);
-    return { plan: specPlan, totalWaves: specPlan.length };
-  }
-  const plan = Array.isArray(state.plan) ? state.plan : [];
-  return { plan, totalWaves: positiveIntOrZero(state.totalWaves) };
-}
-
 /**
  * A Story is "done" when it carries `agent::done` OR its GitHub issue is
  * `state === 'closed'`. The closed-state arm (Story #3907) is what aligns the

package/.agents/scripts/lib/workers/crap-worker.js

@@ -29,7 +29,7 @@
 import fs from 'node:fs';
 import { parentPort } from 'node:worker_threads';
 import { calculateCrapForSource } from '../crap-engine.js';
-import { transpileIfNeeded } from '../maintainability-utils.js';
+import { transpileIfNeeded } from '../transpile.js';
 
 /**
  * Pure handler for a single inbound worker message. Exported so unit

package/.agents/scripts/lib/workers/maintainability-report-worker.js

@@ -39,7 +39,7 @@ import {
   calculateReport,
   calculateReportForFile,
 } from '../maintainability-engine.js';
-import { transpileIfNeeded } from '../maintainability-utils.js';
+import { transpileIfNeeded } from '../transpile.js';
 
 /**
  * Score a pre-sourced content string (Story #3696). Mirrors

package/.agents/scripts/lib/worktree/lifecycle/creation.js

@@ -12,6 +12,7 @@ import fs from 'node:fs';
 import {
   applyNodeModulesStrategy,
   installDependencies,
+  probeReusedInstall,
 } from '../node-modules-strategy.js';
 import {
   findByPath,
@@ -41,6 +42,23 @@ export async function ensure(ctx, storyId, branch) {
     if (typeof ctx.onPhase === 'function') ctx.onPhase(name);
   };
 
+  // Reuse must not blindly skip the install: when the prior run's install
+  // failed (or was interrupted), `skipped/worktree-reused` defeats the
+  // retry exactly when it matters — `deriveInstallAction('skipped')` skips.
+  // Probe for a completed install; on a failed probe, retry the install
+  // here and surface its real outcome.
+  const reuseInstallStatus = () => {
+    const strategy = ctx.config?.nodeModulesStrategy ?? 'per-worktree';
+    const probe = probeReusedInstall(strategy, wtPath);
+    if (probe.status !== 'failed') return probe;
+    ctx.logger.warn(
+      `worktree.reuse install probe failed (${probe.reason}) — retrying install in ${wtPath}`,
+    );
+    // `ctx.installDependencies` is a test-injection seam; production ctx
+    // bags leave it unset and get the real installer.
+    return (ctx.installDependencies ?? installDependencies)(ctx, wtPath);
+  };
+
   if (existing) {
     if (existing.branch && existing.branch !== br) {
       throw new Error(
@@ -53,7 +71,7 @@ export async function ensure(ctx, storyId, branch) {
     return {
       path: wtPath,
       created: false,
-      installStatus: { status: 'skipped', reason: 'worktree-reused' },
+      installStatus: reuseInstallStatus(),
     };
   }
 
@@ -87,7 +105,7 @@ export async function ensure(ctx, storyId, branch) {
         return {
           path: wtPath,
           created: false,
-          installStatus: { status: 'skipped', reason: 'worktree-reused' },
+          installStatus: reuseInstallStatus(),
         };
       }
     }

package/.agents/scripts/lib/worktree/lifecycle/force-drain.js

@@ -118,10 +118,89 @@ export function findHoldersInPath(wtPath, opts = {}) {
     }));
 }
 
+/**
+ * Pure: compute the set of pids that must never be killed — `selfPid` plus
+ * its full ancestor chain — from a process table of `{ pid, ppid }` rows.
+ * Cycle-guarded (a corrupt/raced table cannot loop forever). `selfPid` is
+ * always included even when the table is empty or missing its row, so the
+ * guard fails safe.
+ *
+ * @param {number} selfPid
+ * @param {Array<{ pid: number, ppid?: number }>} table
+ * @returns {Set<number>}
+ */
+export function computeProtectedPids(selfPid, table) {
+  const protectedPids = new Set([selfPid]);
+  if (!Array.isArray(table) || table.length === 0) return protectedPids;
+  const parentOf = new Map();
+  for (const row of table) {
+    if (row && typeof row.pid === 'number' && typeof row.ppid === 'number') {
+      parentOf.set(row.pid, row.ppid);
+    }
+  }
+  let cursor = selfPid;
+  while (parentOf.has(cursor)) {
+    const ppid = parentOf.get(cursor);
+    if (protectedPids.has(ppid)) break; // cycle guard
+    protectedPids.add(ppid);
+    cursor = ppid;
+  }
+  return protectedPids;
+}
+
+/**
+ * Enumerate the full Windows process table as `{ pid, ppid }` rows so the
+ * kill set can exclude the invoking shell / orchestrator ancestry.
+ * Best-effort: any failure returns `[]` (callers still protect `selfPid`).
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.spawn] Injection point for tests (default `spawnSync`).
+ * @param {string} [opts.platform] Override `process.platform` for tests.
+ * @returns {Array<{ pid: number, ppid: number }>}
+ */
+export function fetchProcessTable(opts = {}) {
+  const spawn = opts.spawn ?? spawnSync;
+  const platform = opts.platform ?? process.platform;
+  if (platform !== 'win32') return [];
+
+  const script =
+    'Get-CimInstance Win32_Process | Select-Object ProcessId, ParentProcessId | ConvertTo-Json -Compress';
+  let res;
+  try {
+    res = spawn(
+      'powershell.exe',
+      ['-NoProfile', '-NonInteractive', '-Command', script],
+      { encoding: 'utf8', timeout: 15_000 },
+    );
+  } catch {
+    return [];
+  }
+  if (!res || res.status !== 0 || !res.stdout) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(String(res.stdout).trim());
+  } catch {
+    return [];
+  }
+  const list = Array.isArray(parsed) ? parsed : [parsed];
+  return list
+    .filter((p) => p && typeof p.ProcessId === 'number')
+    .map((p) => ({
+      pid: p.ProcessId,
+      ppid: typeof p.ParentProcessId === 'number' ? p.ParentProcessId : -1,
+    }));
+}
+
 /**
  * `taskkill /T /F /PID <pid>` for each holder. Returns the pids reported
  * as terminated. Per-pid failures are logged but do not throw — caller
  * decides whether the partial kill is enough to retry.
+ *
+ * Self-preservation (Story #4018): holders are matched by command-line
+ * substring, which can select the invoking shell or the orchestrator's own
+ * ancestor chain (any ancestor whose command line mentions the worktree
+ * path). Before any `taskkill /T /F`, the kill set excludes `selfPid` and
+ * its full ancestor chain — `/T` on an ancestor would kill this process too.
  */
 export function terminateHolders(holders, opts = {}) {
   const spawn = opts.spawn ?? spawnSync;
@@ -130,9 +209,20 @@ export function terminateHolders(holders, opts = {}) {
   if (platform !== 'win32') return [];
   if (!Array.isArray(holders) || holders.length === 0) return [];
 
+  const selfPid = opts.selfPid ?? process.pid;
+  const protectedPids =
+    opts.protectedPids ??
+    computeProtectedPids(selfPid, fetchProcessTable({ spawn, platform }));
+
   const killed = [];
   for (const h of holders) {
     if (!h || typeof h.pid !== 'number') continue;
+    if (protectedPids.has(h.pid)) {
+      logger.warn(
+        `force-drain: skipping pid=${h.pid} name=${h.name ?? '?'} — self/ancestor of this process (never killed)`,
+      );
+      continue;
+    }
     let res;
     try {
       res = spawn('taskkill.exe', ['/T', '/F', '/PID', String(h.pid)], {

package/.agents/scripts/lib/worktree/lifecycle/reap.js

@@ -134,7 +134,7 @@ async function fsRmWithRetry(
       return { success: true, attempts: attempt };
     } catch (err) {
       lastErr = err;
-      if (attempt < maxRetries) {
+      if (attempt < maxRetries && retryDelay > 0) {
         await new Promise((r) => setTimeout(r, retryDelay));
       }
     }
@@ -160,8 +160,8 @@ function handleRemoveFailure(
   classification,
   attempt,
   maxAttempts,
+  { retryDelaysMs = [0, 150, 350, 700, 1200, 2000], sleepFn = sleepSync } = {},
 ) {
-  const retryDelaysMs = [0, 150, 350, 700, 1200, 2000];
   const { isLockLike, isCwdLike } = classification;
   if ((isLockLike || isCwdLike) && attempt < maxAttempts) {
     const delay = retryDelaysMs[attempt] ?? 300;
@@ -169,13 +169,13 @@ function handleRemoveFailure(
     ctx.logger.warn(
       `worktree.reap remove hit ${reasonClass} error; retrying in ${delay}ms (${attempt}/${maxAttempts})`,
     );
-    sleepSync(delay);
+    sleepFn(delay);
     return 'continue';
   }
   return 'break';
 }
 
-async function runGitWorktreeRemoveLoop(ctx, wtPath) {
+async function runGitWorktreeRemoveLoop(ctx, wtPath, retryOpts = {}) {
   const maxAttempts = ctx.platform === 'win32' ? 6 : 2;
   let lastReason = 'worktree-remove-failed';
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -193,6 +193,7 @@ async function runGitWorktreeRemoveLoop(ctx, wtPath) {
       classification,
       attempt,
       maxAttempts,
+      retryOpts,
     );
     if (action === 'break') break;
   }
@@ -205,6 +206,7 @@ function tryForceRemoveFallback(
   lastReason,
   forceRemoveBackoffMs,
   maxAttempts,
+  sleepFn = sleepSync,
 ) {
   if (!(WINDOWS_LOCK_RE.test(lastReason) || WINDOWS_CWD_RE.test(lastReason))) {
     return { handled: false, lastReason };
@@ -212,7 +214,7 @@ function tryForceRemoveFallback(
   ctx.logger.warn(
     `worktree.reap remove exhausted Windows lock retry; retrying with --force in ${forceRemoveBackoffMs}ms path=${wtPath}`,
   );
-  sleepSync(forceRemoveBackoffMs);
+  sleepFn(forceRemoveBackoffMs);
   const forced = ctx.git.gitSpawn(
     ctx.repoRoot,
     'worktree',
@@ -248,8 +250,9 @@ async function tryStage15WindowsFsRm({
   push,
   lastReason,
   priorAttempts,
+  sleepFn = sleepSync,
 }) {
-  sleepSync(forceRemoveBackoffMs);
+  sleepFn(forceRemoveBackoffMs);
   try {
     await fsRm(wtPath, {
       recursive: true,
@@ -304,6 +307,7 @@ async function handleFsRmFailure({
   lastReason,
   forceRemoveBackoffMs,
   fsRm,
+  sleepFn,
 }) {
   // Stage 1.5 — coverage-leak quiesce + extended fs.rm budget (Windows only).
   if (ctx.platform === 'win32') {
@@ -316,6 +320,7 @@ async function handleFsRmFailure({
       push,
       lastReason,
       priorAttempts: rmResult.attempts,
+      sleepFn,
     });
     if (stage15) return stage15;
   }
@@ -347,7 +352,12 @@ async function handleFsRmFailure({
 export async function removeWorktreeWithRecovery(ctx, wtPath, opts = {}) {
   const { storyId = null, branch = null, push = false } = opts;
   const forceRemoveBackoffMs = opts.forceRemoveBackoffMs ?? 3000;
-  const removeLoop = await runGitWorktreeRemoveLoop(ctx, wtPath);
+  const retryDelay = opts.retryDelay ?? 200;
+  const { retryDelaysMs, sleepFn } = opts;
+  const removeLoop = await runGitWorktreeRemoveLoop(ctx, wtPath, {
+    ...(retryDelaysMs ? { retryDelaysMs } : {}),
+    ...(sleepFn ? { sleepFn } : {}),
+  });
   if (removeLoop.removed) return { removed: true };
   let { lastReason } = removeLoop;
   if (ctx.platform === 'win32' && opts.forceRemoveFallback !== false) {
@@ -357,6 +367,7 @@ export async function removeWorktreeWithRecovery(ctx, wtPath, opts = {}) {
       lastReason,
       forceRemoveBackoffMs,
       removeLoop.maxAttempts,
+      sleepFn,
     );
     if (fallback.handled) return fallback.result;
     lastReason = fallback.lastReason;
@@ -367,7 +378,7 @@ export async function removeWorktreeWithRecovery(ctx, wtPath, opts = {}) {
   const fsRm = ctx.fsRm ?? fsPromisesRm;
   const rmResult = await fsRmWithRetry(fsRm, wtPath, {
     maxRetries: 5,
-    retryDelay: 200,
+    retryDelay,
   });
   if (!rmResult.success) {
     return handleFsRmFailure({
@@ -380,6 +391,7 @@ export async function removeWorktreeWithRecovery(ctx, wtPath, opts = {}) {
       lastReason,
       forceRemoveBackoffMs,
       fsRm,
+      sleepFn,
     });
   }
   finalizeGitWorktreeRemove(ctx);
@@ -571,6 +583,12 @@ export async function reap(ctx, storyId, opts = {}) {
     storyId: storyIdN,
     branch,
     push: opts.push === true,
+    ...(opts.retryDelaysMs ? { retryDelaysMs: opts.retryDelaysMs } : {}),
+    ...(opts.retryDelay !== undefined ? { retryDelay: opts.retryDelay } : {}),
+    ...(opts.sleepFn ? { sleepFn: opts.sleepFn } : {}),
+    ...(opts.forceRemoveBackoffMs !== undefined
+      ? { forceRemoveBackoffMs: opts.forceRemoveBackoffMs }
+      : {}),
   });
   if (!removeResult.removed) {
     return {

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

@@ -119,6 +119,80 @@ export function selectInstallCommand(strategy, wtPath, fsLike = fs) {
   return { cmd: 'npm', args: ['ci'] };
 }
 
+/**
+ * Per-package-manager "install completed" marker files written into
+ * `node_modules/` by the install command itself. Their presence (and
+ * freshness relative to the lockfile) is the cheapest reliable signal that a
+ * prior install ran to completion — a failed/interrupted install leaves
+ * `node_modules` partially populated without (or with a stale) marker.
+ */
+const INSTALL_MARKERS = [
+  '.package-lock.json', // npm ci / npm install
+  '.modules.yaml', // pnpm
+  '.yarn-state.yml', // yarn berry (node-modules linker)
+  '.yarn-integrity', // yarn classic
+];
+
+const LOCKFILES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'];
+
+function safeMtimeMs(fsLike, p) {
+  try {
+    return fsLike.statSync(p).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pure: probe whether a **reused** worktree already carries a completed,
+ * up-to-date install. Worktree reuse must not blindly report
+ * `skipped/worktree-reused` — when the prior run's install *failed*, that
+ * status defeats the install retry exactly when it matters
+ * (`deriveInstallAction('skipped')` treats it as "nothing to do").
+ *
+ * Returns the same shape as `installDependencies`:
+ *   - `{ 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.
+ *
+ * @param {string} strategy One of `per-worktree | pnpm-store | symlink`.
+ * @param {string} wtPath Absolute worktree path.
+ * @param {{ existsSync: Function, statSync: Function }} [fsLike] Injectable for tests.
+ * @returns {{ status: 'skipped' | 'failed', reason: string }}
+ */
+export function probeReusedInstall(strategy, wtPath, fsLike = fs) {
+  // `symlink` re-points node_modules at a donor — no per-tree install to probe.
+  if (strategy === 'symlink') {
+    return { status: 'skipped', reason: 'worktree-reused' };
+  }
+  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' };
+    }
+  }
+  return { status: 'skipped', reason: 'worktree-reused' };
+}
+
 /** Pure: retry policy keyed off the chosen command. pnpm gets 3× + 5min. */
 export function installRetryPolicy(cmd) {
   const isPnpm = cmd === 'pnpm';