mandrel 2.16.0 → 2.18.0

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

@@ -1,4 +1,5 @@
-import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import { createRequire, SourceMap } from 'node:module';
 import path from 'node:path';
 import { Logger } from './Logger.js';
 
@@ -39,6 +40,71 @@ function isTypeScriptPath(filePath) {
   return TS_EXTS.has(path.extname(String(filePath)).toLowerCase());
 }
 
+/**
+ * Trailing `//# sourceMappingURL=…` comment `ts.transpileModule` appends
+ * when `sourceMap: true` is requested. Stripping it makes the emitted code
+ * byte-identical to the `sourceMap: false` emit, which is what keeps the
+ * maintainability path — and every MI score in the committed baseline —
+ * untouched by the CRAP path opting into a map.
+ */
+const SOURCE_MAPPING_URL_RE = /\n?\/\/# sourceMappingURL=[^\n]*\n?$/;
+
+/**
+ * Build a `transpiledLine → originalLine` resolver over a raw
+ * `sourceMapText` payload, using Node's built-in `SourceMap` (no new
+ * runtime dependency).
+ *
+ * `SourceMap#findEntry(line, column)` is 0-based and returns the mapping at
+ * or before the requested position, so a bare `findEntry(line, 0)` can
+ * silently answer with a *previous* line's mapping when the requested line
+ * carries no mapping at column 0. The resolver therefore walks the columns
+ * of the generated line and accepts only an entry that actually originates
+ * on that generated line; a line with no mapping at all resolves to `null`
+ * and the caller falls back to the un-remapped coordinate.
+ *
+ * Results are memoised per generated line — a file's methods are looked up
+ * once each, but the same line is often probed by several callers.
+ *
+ * @param {string} sourceMapText Raw JSON source map emitted by TypeScript.
+ * @param {string} code The generated (transpiled) code the map describes.
+ * @returns {((line: number) => number|null)|null}
+ */
+function buildLineMapper(sourceMapText, code) {
+  let sourceMap;
+  try {
+    sourceMap = new SourceMap(JSON.parse(sourceMapText));
+  } catch {
+    return null;
+  }
+  const lines = String(code).split('\n');
+  const memo = new Map();
+  return function mapLine(generatedLine) {
+    if (typeof generatedLine !== 'number' || generatedLine < 1) return null;
+    if (memo.has(generatedLine)) return memo.get(generatedLine);
+    const zeroBased = generatedLine - 1;
+    const lineText = lines[zeroBased] ?? '';
+    let resolved = null;
+    for (let column = 0; column <= lineText.length; column += 1) {
+      let entry;
+      try {
+        entry = sourceMap.findEntry(zeroBased, column);
+      } catch {
+        break;
+      }
+      if (
+        entry &&
+        entry.generatedLine === zeroBased &&
+        typeof entry.originalLine === 'number'
+      ) {
+        resolved = entry.originalLine + 1;
+        break;
+      }
+    }
+    memo.set(generatedLine, resolved);
+    return resolved;
+  };
+}
+
 /**
  * Pre-transpile TypeScript or TSX sources to JavaScript that the
  * Esprima-based escomplex kernel can parse. Returns the input unchanged
@@ -54,12 +120,33 @@ function isTypeScriptPath(filePath) {
  * On transpile failure the helper returns `null` — callers treat that
  * as "skip this file" rather than crashing the scan.
  *
+ * **Line coordinates (Story #4775).** The transpile does not preserve line
+ * numbers: interface elision and the injected JSX-runtime import shift the
+ * emitted code relative to the original source. escomplex then reports each
+ * method's `lineStart` in *transpiled* coordinates while istanbul's `fnMap`
+ * is in *original source* coordinates — so a per-method coverage join keyed
+ * on the raw `lineStart` cannot match. Callers that need to join against
+ * coverage pass `{ withLineMap: true }` and receive
+ * `{ code, mapLine }`, where `mapLine(transpiledLine)` returns the original
+ * source line (or `null` when the line has no mapping).
+ *
+ * `withLineMap` is opt-in precisely so the maintainability path — which is
+ * module-level and never joins coverage — keeps paying nothing for a map it
+ * would not read, and keeps emitting byte-identical scores. A JavaScript
+ * input is a passthrough in both modes: `mapLine` is `null` because the
+ * coordinates already *are* original-source coordinates, so no remap is
+ * needed and none is computed.
+ *
  * @param {string} filePath
  * @param {string} source
- * @returns {string|null}
+ * @param {{withLineMap?: boolean}} [opts]
+ * @returns {string|null|{code: string, mapLine: ((line: number) => number|null)|null}}
  */
-export function transpileIfNeeded(filePath, source) {
-  if (!isTypeScriptPath(filePath)) return source;
+export function transpileIfNeeded(filePath, source, opts = {}) {
+  const withLineMap = opts?.withLineMap === true;
+  if (!isTypeScriptPath(filePath)) {
+    return withLineMap ? { code: source, mapLine: null } : source;
+  }
   const ts = loadTypeScript();
   if (!ts) {
     Logger.warn(
@@ -78,12 +165,18 @@ export function transpileIfNeeded(filePath, source) {
         importHelpers: false,
         removeComments: false,
         jsx: ts.JsxEmit.ReactJSX,
-        sourceMap: false,
+        sourceMap: withLineMap,
       },
       fileName: path.basename(filePath),
       reportDiagnostics: false,
     });
-    return result.outputText;
+    if (!withLineMap) return result.outputText;
+    const code = result.outputText.replace(SOURCE_MAPPING_URL_RE, '\n');
+    const mapLine =
+      typeof result.sourceMapText === 'string'
+        ? buildLineMapper(result.sourceMapText, code)
+        : null;
+    return { code, mapLine };
   } catch (err) {
     Logger.warn(
       `[Maintainability] ⚠ TS transpile failed for ${filePath}: ${err?.message ?? err}; skipping.`,
@@ -91,3 +184,37 @@ export function transpileIfNeeded(filePath, source) {
     return null;
   }
 }
+
+/**
+ * Prepare a source file for scoring: read it, transpile TS/TSX with a
+ * line map, and hand back the JavaScript escomplex will parse alongside the
+ * transpiled → original-source line resolver the coverage join needs
+ * (Story #4775).
+ *
+ * Failure is reported as `{error: 'read'}` or `{error: 'transpile'}` rather
+ * than a bare null: CRAP drops the file either way, but the combined MI path
+ * distinguishes them (a read failure drops the MI score, a transpile failure
+ * scores it 0 — matching `calculateForFile`).
+ *
+ * @param {string} abs Absolute path of the source file.
+ * @param {{readFile?: (p: string) => string, transpile?: Function}} [deps]
+ * @returns {{code: string, mapLine: ((line: number) => number|null)|null}
+ *   | {error: 'read'|'transpile'}}
+ */
+export function prepareSourceForScoring(abs, deps = {}) {
+  const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
+  const transpile = deps.transpile ?? transpileIfNeeded;
+  let source;
+  try {
+    source = readFile(abs);
+  } catch {
+    return { error: 'read' };
+  }
+  const prepared = transpile(abs, source, { withLineMap: true });
+  if (prepared === null || prepared === undefined)
+    return { error: 'transpile' };
+  // Tolerate a `deps.transpile` stub that still returns a bare string.
+  if (typeof prepared === 'string') return { code: prepared, mapLine: null };
+  if (typeof prepared.code !== 'string') return { error: 'transpile' };
+  return { code: prepared.code, mapLine: prepared.mapLine ?? null };
+}

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

@@ -32,6 +32,9 @@
  *           skippedFileNoCoverage: boolean,
  *           crapRows: Array<{ method, startLine, cyclomatic, coverage, crap }> | null,
  *           skippedMethodsNoCoverage: number,
+ *           hasCoverageEntry: boolean,
+ *           resolvedMethods: number,
+ *           totalMethods: number,
  *         } }
  *
  * A read/transpile/parse failure surfaces as `crapRows: null` so the host
@@ -40,10 +43,10 @@
  * `miScore` is `null`; on a transpile/parse failure `miScore` is `0`.
  */
 
-import fs from 'node:fs';
 import { parentPort } from 'node:worker_threads';
+import { finalizeMethodRows } from '../crap-engine.js';
 import { analyzeOnce } from '../crap-utils.js';
-import { transpileIfNeeded } from '../transpile.js';
+import { prepareSourceForScoring } from '../transpile.js';
 
 /**
  * Pure handler for a single inbound worker message. Exported so unit tests
@@ -58,8 +61,9 @@ import { transpileIfNeeded } from '../transpile.js';
  * @param {unknown} msg
  * @param {{
  *   readFile?: (abs: string) => string,
- *   transpile?: (abs: string, source: string) => string | null,
- *   analyze?: (source: string, entry: object|null) => {
+ *   transpile?: (abs: string, source: string, opts?: object) => unknown,
+ *   prepare?: (abs: string, deps: object) => object,
+ *   analyze?: (source: string, entry: object|null, mapLine: Function|null) => {
  *     miScore: number,
  *     crapRows: Array<object>,
  *     parseError: boolean,
@@ -85,8 +89,7 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
     };
   }
   const { abs, relPath, requireCoverage } = item;
-  const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
-  const transpile = deps.transpile ?? transpileIfNeeded;
+  const prepare = deps.prepare ?? prepareSourceForScoring;
   const analyze = deps.analyze ?? analyzeOnce;
 
   // Coverage entry is pre-resolved on the host and attached to the item.
@@ -94,47 +97,33 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
   // coverage, or `undefined` when the caller did not supply it (treat as null).
   const entry = item.coverageEntry ?? null;
 
-  // Read the source once. A read failure means neither MI nor CRAP can be
-  // computed — MI drops (null), CRAP drops (rows null) — matching the two
-  // passes' read-failure contracts (calculateAll → score null; crap worker
-  // → rows null).
-  let source;
-  try {
-    source = readFile(abs);
-  } catch {
-    return {
-      kind: 'reply',
-      message: {
-        ok: true,
-        result: {
-          relPath,
-          miScore: null,
-          skippedFileNoCoverage: false,
-          crapRows: null,
-          skippedMethodsNoCoverage: 0,
-        },
+  const reply = (result) => ({
+    kind: 'reply',
+    message: {
+      ok: true,
+      result: {
+        relPath,
+        skippedFileNoCoverage: false,
+        skippedMethodsNoCoverage: 0,
+        hasCoverageEntry: entry !== null,
+        resolvedMethods: 0,
+        totalMethods: 0,
+        ...result,
       },
-    };
-  }
+    },
+  });
 
-  // TS/TSX → strip-then-analyze. A transpile failure yields miScore 0
-  // (calculateForFile returns 0 when transpileIfNeeded returns null) and a
-  // null CRAP contribution (crap worker returns rows: null).
-  const prepared = transpile(abs, source);
-  if (prepared === null) {
-    return {
-      kind: 'reply',
-      message: {
-        ok: true,
-        result: {
-          relPath,
-          miScore: 0,
-          skippedFileNoCoverage: false,
-          crapRows: null,
-          skippedMethodsNoCoverage: 0,
-        },
-      },
-    };
+  // Read + transpile once, carrying the transpiled -> original-source line
+  // map the per-method coverage join needs (Story #4775). A read failure
+  // means neither MI nor CRAP can be computed (MI drops as null, matching
+  // `calculateAll`'s filter); a transpile failure scores MI 0 (matching
+  // `calculateForFile`). CRAP drops the file either way.
+  const prepared = prepare(abs, deps);
+  if (prepared.error) {
+    return reply({
+      miScore: prepared.error === 'read' ? null : 0,
+      crapRows: null,
+    });
   }
 
   // ONE parse: analyzeOnce derives both the module MI score and the raw
@@ -144,24 +133,12 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
     miScore,
     crapRows: rawCrapRows,
     parseError,
-  } = analyze(prepared, entry);
+  } = analyze(prepared.code, entry, prepared.mapLine);
   if (parseError) {
-    // Parse error: MI scores 0 (parity with calculateForSource's catch →
+    // Parse error: MI scores 0 (parity with calculateForSource's catch ->
     // returns 0), CRAP drops the file (rows null, parity with the crap
     // worker's calculateCrap-throw branch).
-    return {
-      kind: 'reply',
-      message: {
-        ok: true,
-        result: {
-          relPath,
-          miScore: 0,
-          skippedFileNoCoverage: false,
-          crapRows: null,
-          skippedMethodsNoCoverage: 0,
-        },
-      },
-    };
+    return reply({ miScore: 0, crapRows: null });
   }
 
   // CRAP coverage gate runs AFTER the parse so the MI score is always
@@ -169,49 +146,18 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
   // pass would have skipped it at the file level (no rows, counted) — but the
   // MI pass would still have scored it, so miScore is returned regardless.
   if (requireCoverage && entry === null) {
-    return {
-      kind: 'reply',
-      message: {
-        ok: true,
-        result: {
-          relPath,
-          miScore,
-          skippedFileNoCoverage: true,
-          crapRows: [],
-          skippedMethodsNoCoverage: 0,
-        },
-      },
-    };
+    return reply({ miScore, skippedFileNoCoverage: true, crapRows: [] });
   }
 
-  const crapRows = [];
-  let skippedMethodsNoCoverage = 0;
-  for (const mr of rawCrapRows) {
-    if (mr.crap === null || mr.coverage === null) {
-      skippedMethodsNoCoverage += 1;
-      continue;
-    }
-    crapRows.push({
-      method: mr.method,
-      startLine: mr.startLine,
-      cyclomatic: mr.cyclomatic,
-      coverage: mr.coverage,
-      crap: mr.crap,
-    });
-  }
-  return {
-    kind: 'reply',
-    message: {
-      ok: true,
-      result: {
-        relPath,
-        miScore,
-        skippedFileNoCoverage: false,
-        crapRows,
-        skippedMethodsNoCoverage,
-      },
-    },
-  };
+  const { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods } =
+    finalizeMethodRows(rawCrapRows, { requireCoverage });
+  return reply({
+    miScore,
+    crapRows: rows,
+    skippedMethodsNoCoverage,
+    resolvedMethods,
+    totalMethods,
+  });
 }
 
 if (parentPort) {

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

@@ -18,6 +18,9 @@
  *           skippedFileNoCoverage: boolean,
  *           rows: Array<{ method, startLine, cyclomatic, coverage, crap }>,
  *           skippedMethodsNoCoverage: number,
+ *           hasCoverageEntry: boolean,
+ *           resolvedMethods: number,
+ *           totalMethods: number,
  *         } }
  *
  * A truly unrecoverable per-file failure (read error, transpile null)
@@ -26,10 +29,9 @@
  * aborts the whole scan.
  */
 
-import fs from 'node:fs';
 import { parentPort } from 'node:worker_threads';
-import { calculateCrapForSource } from '../crap-engine.js';
-import { transpileIfNeeded } from '../transpile.js';
+import { calculateCrapForSource, finalizeMethodRows } from '../crap-engine.js';
+import { prepareSourceForScoring } from '../transpile.js';
 
 /**
  * Pure handler for a single inbound worker message. Exported so unit
@@ -42,7 +44,10 @@ import { transpileIfNeeded } from '../transpile.js';
  *   - `{ kind: 'reply', message }`   — caller should `postMessage(message)`.
  *
  * Side effects (fs, transpile, escomplex) are wired through `deps` so
- * tests pass deterministic stubs.
+ * tests pass deterministic stubs. `readFile` / `transpile` are forwarded to
+ * `prepareSourceForScoring`, which also derives the transpiled →
+ * original-source line map the coverage join needs (Story #4775); a
+ * `transpile` stub that still returns a bare string is tolerated.
  *
  * Coverage is supplied via `item.coverageEntry` (pre-resolved on the host),
  * not via a whole-map `coverage` argument. The second parameter is kept as
@@ -52,8 +57,9 @@ import { transpileIfNeeded } from '../transpile.js';
  * @param {object|null} _coverage - Unused. Coverage is in `item.coverageEntry`.
  * @param {{
  *   readFile?: (abs: string) => string,
- *   transpile?: (abs: string, source: string) => string | null,
- *   calculateCrap?: (source: string, entry: object|null) => Array<object>,
+ *   transpile?: (abs: string, source: string, opts?: object) => unknown,
+ *   prepare?: (abs: string, deps: object) => object,
+ *   calculateCrap?: (source: string, entry: object|null, mapLine: Function|null) => Array<object>,
  * }} [deps]
  * @returns {{kind: 'exit'} | {kind: 'reply', message: object}}
  */
@@ -75,9 +81,6 @@ export function handleCrapWorkerMessage(msg, _coverage, deps = {}) {
     };
   }
   const { abs, relPath, requireCoverage } = item;
-  const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
-  const transpile = deps.transpile ?? transpileIfNeeded;
-  const calculateCrap = deps.calculateCrap ?? calculateCrapForSource;
 
   // Coverage entry is pre-resolved on the host and attached to the item.
   // `item.coverageEntry` may be explicitly `null` when the file has no
@@ -93,84 +96,54 @@ export function handleCrapWorkerMessage(msg, _coverage, deps = {}) {
           skippedFileNoCoverage: true,
           rows: [],
           skippedMethodsNoCoverage: 0,
+          hasCoverageEntry: false,
+          resolvedMethods: 0,
+          totalMethods: 0,
         },
       },
     };
   }
 
-  let source;
-  try {
-    source = readFile(abs);
-  } catch {
-    return {
-      kind: 'reply',
-      message: {
-        ok: true,
-        result: {
-          relPath,
-          skippedFileNoCoverage: false,
-          rows: null,
-          skippedMethodsNoCoverage: 0,
-        },
+  const dropped = (error) => ({
+    kind: 'reply',
+    message: {
+      ok: true,
+      result: {
+        relPath,
+        skippedFileNoCoverage: false,
+        rows: null,
+        skippedMethodsNoCoverage: 0,
+        hasCoverageEntry: entry !== null,
+        resolvedMethods: 0,
+        totalMethods: 0,
+        ...(error ? { error } : {}),
       },
-    };
-  }
+    },
+  });
 
-  // TS/TSX → strip-then-analyze. Coverage lookup above used the original
-  // source path (vitest's coverage-final.json keys on the .ts file, not
-  // transpiled output); the transpile is purely about making the code
-  // parseable by the Esprima-based escomplex kernel.
-  const prepared = transpile(abs, source);
-  if (prepared === null) {
-    return {
-      kind: 'reply',
-      message: {
-        ok: true,
-        result: {
-          relPath,
-          skippedFileNoCoverage: false,
-          rows: null,
-          skippedMethodsNoCoverage: 0,
-        },
-      },
-    };
-  }
+  // TS/TSX -> transpile-then-analyze, carrying the source map. The coverage
+  // lookup above used the ORIGINAL source path (vitest's coverage-final.json
+  // keys on the .ts file, not transpiled output) and the per-method join
+  // below uses ORIGINAL source *lines*, remapped from escomplex's transpiled
+  // coordinates via `prepared.mapLine` (Story #4775).
+  const prepare = deps.prepare ?? prepareSourceForScoring;
+  const prepared = prepare(abs, deps);
+  if (prepared.error) return dropped(null);
 
   let methodRows;
   try {
-    methodRows = calculateCrap(prepared, entry);
+    methodRows = (deps.calculateCrap ?? calculateCrapForSource)(
+      prepared.code,
+      entry,
+      prepared.mapLine,
+    );
   } catch (err) {
-    return {
-      kind: 'reply',
-      message: {
-        ok: true,
-        result: {
-          relPath,
-          skippedFileNoCoverage: false,
-          rows: null,
-          skippedMethodsNoCoverage: 0,
-          error:
-            err && typeof err.message === 'string' ? err.message : String(err),
-        },
-      },
-    };
+    return dropped(
+      err && typeof err.message === 'string' ? err.message : String(err),
+    );
   }
 
-  const rows = [];
-  let skippedMethodsNoCoverage = 0;
-  for (const mr of methodRows) {
-    if (mr.crap === null || mr.coverage === null) {
-      skippedMethodsNoCoverage += 1;
-      continue;
-    }
-    rows.push({
-      method: mr.method,
-      startLine: mr.startLine,
-      cyclomatic: mr.cyclomatic,
-      coverage: mr.coverage,
-      crap: mr.crap,
-    });
-  }
+  const finalized = finalizeMethodRows(methodRows, { requireCoverage });
   return {
     kind: 'reply',
     message: {
@@ -178,8 +151,8 @@ export function handleCrapWorkerMessage(msg, _coverage, deps = {}) {
       result: {
         relPath,
         skippedFileNoCoverage: false,
-        rows,
-        skippedMethodsNoCoverage,
+        hasCoverageEntry: entry !== null,
+        ...finalized,
       },
     },
   };

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

@@ -15,6 +15,7 @@
 
 import fs from 'node:fs';
 import { rm as fsPromisesRm } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
 import { isInsideWorktree, samePath } from '../inspector.js';
 import { sleepSync } from '../node-modules-strategy.js';
 import { checkMergeReachability } from './merge-reachability.js';
@@ -493,20 +494,92 @@ async function deleteBranchAfterReap(ctx, { branch, push }) {
   return { branchDeleted, remoteBranchDeleted };
 }
 
+/**
+ * The on-disk paths of the code currently executing: the entry script and
+ * this module itself.
+ *
+ * @returns {string[]}
+ */
+function runningCodePaths() {
+  const paths = [];
+  const entry = process.argv[1];
+  if (typeof entry === 'string' && entry !== '') paths.push(entry);
+  try {
+    paths.push(fileURLToPath(import.meta.url));
+  } catch {
+    // A non-file module URL cannot be inside a worktree; nothing to add.
+  }
+  return paths;
+}
+
+/**
+ * Return the running-code path that lives inside `wtPath`, or `null`.
+ *
+ * `escapeWorktreeCwd` already handles the *cwd* being inside the doomed
+ * tree; this is the other half — the **code** being inside it. An agent that
+ * invokes `node .agents/scripts/single-story-close.js` with its shell cwd set
+ * to the Story worktree runs the WORKTREE's copy of the script, and reaping
+ * the tree then deletes the running program out from under itself. Node has
+ * already loaded the static module graph, so the process does not die on the
+ * spot — it dies later, at the first lazy read or dynamic `import()`, in
+ * whatever phase happens to need one. That is how a close whose PR merged,
+ * whose Story flipped to `agent::done`, and whose post-land tail was green
+ * still exited non-zero with no terminal envelope.
+ *
+ * Refusing the reap is cheap: the tree survives one extra cycle and the next
+ * boot sweep takes it. Reaping it costs the run's return contract.
+ *
+ * @param {object} ctx
+ * @param {string} wtPath
+ * @returns {string|null}
+ */
+function findRunningCodeInside(ctx, wtPath) {
+  return (
+    runningCodePaths().find((p) => isInsideWorktree(p, wtPath, ctx.platform)) ??
+    null
+  );
+}
+
+/**
+ * The refusals that disqualify a tree before any git work happens, in the
+ * order they are checked. Returns the refusal envelope, or `null` when the
+ * tree is eligible for the safety checks that follow.
+ *
+ * @param {object} ctx
+ * @param {object} opts
+ * @param {string} wtPath
+ * @returns {object|null}
+ */
+function firstReapRefusal(ctx, opts, wtPath) {
+  const known = opts.worktrees
+    ? opts.worktrees.some((r) => samePath(r.path, wtPath, ctx.platform))
+    : findByPath(ctx, wtPath) !== null;
+  if (!known) return { removed: false, reason: 'not-a-worktree', path: wtPath };
+
+  const selfPath = findRunningCodeInside(ctx, wtPath);
+  if (!selfPath) return null;
+  ctx.logger.warn(
+    `reap-skipped reason=running-from-target-tree path=${wtPath} selfPath=${selfPath} — ` +
+      `the running process was loaded from this worktree; removing it would break every ` +
+      `later lazy read and dynamic import in this run. Left for the next sweep. ` +
+      `Invoke the script by its MAIN-checkout path to reap in-run.`,
+  );
+  return {
+    removed: false,
+    reason: 'running-from-target-tree',
+    path: wtPath,
+    selfPath,
+  };
+}
+
 function checkReapPreconditions(ctx, _storyId, opts, wtPath) {
   if (opts.force) {
     throw new Error(
       'WorktreeManager.reap: --force is not permitted by the framework',
     );
   }
-  const known = opts.worktrees
-    ? opts.worktrees.some((r) => samePath(r.path, wtPath, ctx.platform))
-    : findByPath(ctx, wtPath) !== null;
-  if (!known)
-    return {
-      ok: false,
-      result: { removed: false, reason: 'not-a-worktree', path: wtPath },
-    };
+  const refusal = firstReapRefusal(ctx, opts, wtPath);
+  if (refusal) return { ok: false, result: refusal };
   // Story #4539 removed an `epic-branch-required` gate here: a
   // `story-<id>` worktree used to be unreapable unless the caller supplied
   // an Epic integration branch. v2 has no Epic branch, and the only v2