mandrel 1.57.0

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

@@ -0,0 +1,26 @@
+/**
+ * worktree/lifecycle/shared.js
+ *
+ * Argument validators reused by every lifecycle submodule. Pure: no fs, no
+ * git, no ctx.
+ */
+
+import { isStoryBranch } from '../../git-utils.js';
+
+export function validateStoryId(storyId) {
+  const n =
+    typeof storyId === 'number' ? storyId : Number.parseInt(storyId, 10);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`WorktreeManager: invalid storyId: ${storyId}`);
+  }
+  return n;
+}
+
+export function validateBranch(branch) {
+  if (!isStoryBranch(branch)) {
+    throw new Error(
+      `WorktreeManager: branch must match /^story-\\d+$/, got: ${branch}`,
+    );
+  }
+  return branch;
+}

package/.agents/scripts/lib/worktree/lifecycle-manager.js

@@ -0,0 +1,40 @@
+/**
+ * worktree/lifecycle-manager.js — facade (Story 15, Epic #773).
+ *
+ * Public surface preserved byte-identically. Implementations live under
+ * `lib/worktree/lifecycle/`:
+ *
+ *   - `creation.js`         — `ensure`
+ *   - `registry-sync.js`    — `pathFor`, `list`, `prune`, `getWorktreeList`,
+ *                             `invalidateWorktreeCache`, `findByPath`
+ *   - `reap.js`             — `isSafeToRemove`, `isStoryAlreadyMergedIntoEpic`,
+ *                             `removeWorktreeWithRecovery`, `reap`
+ *   - `gc.js`               — `gc`
+ *   - `drift-detection.js`  — `sweepStaleLocks`
+ *   - `pending-cleanup.js`  — `recordPendingCleanup`, `drainPendingCleanup`,
+ *                             and the `.worktrees/.pending-cleanup.json`
+ *                             manifest reader/writer
+ *
+ * Cross-submodule data flows exclusively through the explicit `ctx` bag built
+ * by `WorktreeManager` (see `lib/worktree-manager.js`). Imports between
+ * submodules are limited to pure function composition — e.g. `gc` calling
+ * `reap` and `list` — so no submodule reaches into another's state.
+ */
+
+export { ensure } from './lifecycle/creation.js';
+export { sweepStaleLocks } from './lifecycle/drift-detection.js';
+export { gc } from './lifecycle/gc.js';
+export {
+  isSafeToRemove,
+  isStoryAlreadyMergedIntoEpic,
+  reap,
+  removeWorktreeWithRecovery,
+} from './lifecycle/reap.js';
+export {
+  findByPath,
+  getWorktreeList,
+  invalidateWorktreeCache,
+  list,
+  pathFor,
+  prune,
+} from './lifecycle/registry-sync.js';

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

@@ -0,0 +1,349 @@
+/* node:coverage ignore file -- node_modules placement strategies (symlink/copy/install); pure filesystem I/O, integration-shaped */
+
+/**
+ * worktree/node-modules-strategy.js
+ *
+ * Strategies for populating `node_modules` inside a freshly created worktree:
+ *
+ *   - `per-worktree`  — run the project's package-manager install inside the
+ *                       worktree (lock-file aware).
+ *   - `symlink`       — symlink (or junction on Windows) the worktree's
+ *                       `node_modules` to a donor worktree's copy. Refuses on
+ *                       Windows unless `allowSymlinkOnWindows=true`.
+ *   - `pnpm-store`    — run `pnpm install --frozen-lockfile` against the
+ *                       shared content-addressable store.
+ *
+ * The context passed to each helper carries the minimum state the strategy
+ * needs: config, platform, logger, and repoRoot (for `symlink`).
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function sleepSync(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return;
+  const signal = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(signal, 0, 0, ms);
+}
+
+/**
+ * Apply the configured `nodeModulesStrategy` after a fresh worktree is added.
+ * Called only during creation.
+ *
+ * @param {{ config: object, platform: NodeJS.Platform, logger: object, repoRoot: string }} ctx
+ * @param {string} wtPath Absolute worktree path.
+ */
+export function applyNodeModulesStrategy(ctx, wtPath) {
+  const strategy = ctx.config.nodeModulesStrategy ?? 'per-worktree';
+
+  switch (strategy) {
+    case 'per-worktree':
+    case 'pnpm-store':
+      return;
+
+    case 'symlink': {
+      const primeFromPath = ctx.config.primeFromPath;
+      if (!primeFromPath) {
+        throw new Error(
+          "WorktreeManager: nodeModulesStrategy='symlink' requires orchestration.worktreeIsolation.primeFromPath.",
+        );
+      }
+      if (ctx.platform === 'win32' && !ctx.config.allowSymlinkOnWindows) {
+        throw new Error(
+          "WorktreeManager: nodeModulesStrategy='symlink' refuses on Windows. " +
+            'Symlink semantics vary by Windows version and may require admin rights. ' +
+            'Set orchestration.worktreeIsolation.allowSymlinkOnWindows=true to opt in.',
+        );
+      }
+
+      const resolvedPrime = path.resolve(ctx.repoRoot, primeFromPath);
+      const primeNodeModules = path.join(resolvedPrime, 'node_modules');
+      if (!fs.existsSync(primeNodeModules)) {
+        throw new Error(
+          `WorktreeManager: primeFromPath '${primeFromPath}' has no node_modules directory. ` +
+            'Prime the donor worktree (run install there) before using the symlink strategy.',
+        );
+      }
+
+      const target = path.join(wtPath, 'node_modules');
+      try {
+        // On Windows, `junction` works without Administrator privileges
+        // (unlike `dir`/`file` symlinks) and is adequate for same-volume
+        // node_modules priming. Key off the real host OS — `ctx.platform` is a
+        // test-injection hook and does not change what the filesystem accepts.
+        const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+        fs.symlinkSync(primeNodeModules, target, linkType);
+      } catch (err) {
+        throw new Error(
+          `WorktreeManager: failed to symlink node_modules for ${wtPath}: ${err.message}`,
+        );
+      }
+      ctx.logger.info(
+        `worktree.node_modules strategy=symlink target=${target} source=${primeNodeModules}`,
+      );
+      return;
+    }
+
+    default:
+      throw new Error(
+        `WorktreeManager: unknown nodeModulesStrategy '${strategy}'. ` +
+          'Expected per-worktree | symlink | pnpm-store.',
+      );
+  }
+}
+
+/**
+ * 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`.
+ * @param {string} wtPath Absolute worktree path.
+ * @param {{ existsSync: (p: string) => boolean }} [fsLike] Injectable for tests.
+ * @returns {{ cmd: string, args: string[] } | null}
+ */
+export function selectInstallCommand(strategy, wtPath, fsLike = fs) {
+  if (strategy === 'symlink') return null;
+  if (!fsLike.existsSync(path.join(wtPath, 'package.json'))) return null;
+
+  if (strategy === 'pnpm-store') {
+    return { cmd: 'pnpm', args: ['install', '--frozen-lockfile'] };
+  }
+  if (fsLike.existsSync(path.join(wtPath, 'pnpm-lock.yaml'))) {
+    return { cmd: 'pnpm', args: ['install', '--frozen-lockfile'] };
+  }
+  if (fsLike.existsSync(path.join(wtPath, 'yarn.lock'))) {
+    return { cmd: 'yarn', args: ['install', '--frozen-lockfile'] };
+  }
+  return { cmd: 'npm', args: ['ci'] };
+}
+
+/** Pure: retry policy keyed off the chosen command. pnpm gets 3× + 5min. */
+export function installRetryPolicy(cmd) {
+  const isPnpm = cmd === 'pnpm';
+  return {
+    maxAttempts: isPnpm ? 3 : 1,
+    timeoutMs: isPnpm ? 300_000 : 120_000,
+    backoffMs: [0, 2_000, 5_000],
+  };
+}
+
+/** Pure: classify a failed `spawnSync` result for the warn-line. */
+export function describeAttemptFailure(result, timeoutMs) {
+  if (result.signal === 'SIGTERM') return `timeout after ${timeoutMs / 1000}s`;
+  return `exit ${result.status}`;
+}
+
+/** Relative path of the per-machine pnpm-store prime sentinel (under tempRoot). */
+export const PNPM_STORE_PRIME_SENTINEL = path.join(
+  'temp',
+  '.pnpm-store-primed',
+);
+
+/**
+ * Pure: one-time per-machine pnpm content-addressable-store prime.
+ *
+ * The `pnpm-store` strategy relies on a hydrated shared store. On a cold
+ * machine the first `pnpm install --frozen-lockfile` inside a worktree races
+ * other workers, and the per-tree retries can all hit the same un-populated
+ * store and exhaust without any single attempt succeeding. Priming the store
+ * once at `repoRoot` (where the lockfile lives) before any worktree install
+ * eliminates that class of transient failure.
+ *
+ * The sentinel is a zero-byte file under `<repoRoot>/temp/`. The directory
+ * lives outside Git (the project's standard scratch root) so the sentinel
+ * persists across worktrees on the same machine but never ships to commits.
+ *
+ * No-op for strategies other than `pnpm-store`.
+ *
+ * @returns {{ primed: 'primed' | 'cached' | 'failed' | 'skipped', reason?: string }}
+ */
+export function primePnpmStore({
+  strategy,
+  repoRoot,
+  logger,
+  spawnFn = spawnSync,
+  fsLike = fs,
+  shell = process.platform === 'win32',
+}) {
+  if (strategy !== 'pnpm-store') {
+    return { primed: 'skipped', reason: 'strategy-not-pnpm-store' };
+  }
+  const sentinelPath = path.join(repoRoot, PNPM_STORE_PRIME_SENTINEL);
+  if (fsLike.existsSync(sentinelPath)) {
+    logger.info(`worktree.install prime skipped (sentinel ${sentinelPath})`);
+    return { primed: 'cached', reason: 'sentinel-present' };
+  }
+  logger.info(
+    `worktree.install priming pnpm content-addressable store at ${repoRoot} (sentinel missing)`,
+  );
+  const result = spawnFn('pnpm', ['install', '--frozen-lockfile'], {
+    cwd: repoRoot,
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    shell,
+    timeout: 600_000,
+  });
+  if (result.status !== 0) {
+    logger.warn(
+      `worktree.install prime FAILED (${describeAttemptFailure(result, 600_000)}) stderr=${(result.stderr ?? '').slice(0, 500)}`,
+    );
+    return { primed: 'failed', reason: 'prime-command-nonzero' };
+  }
+  try {
+    fsLike.mkdirSync(path.dirname(sentinelPath), { recursive: true });
+    fsLike.writeFileSync(sentinelPath, '');
+  } catch (err) {
+    logger.warn(
+      `worktree.install prime succeeded but sentinel write failed: ${err.message}`,
+    );
+    return { primed: 'failed', reason: 'sentinel-write-failed' };
+  }
+  logger.info(
+    `worktree.install prime succeeded (sentinel written ${sentinelPath})`,
+  );
+  return { primed: 'primed' };
+}
+
+/**
+ * Run the package-manager install with the configured retry policy. Pure
+ * w.r.t. `spawnFn` + `sleepFn` — the CLI wires real ones; tests inject stubs.
+ *
+ * @returns {{ ok: boolean, attempts: number, lastResult: object }}
+ */
+export function runInstallWithRetry({
+  cmd,
+  args,
+  cwd,
+  shell,
+  policy,
+  spawnFn,
+  sleepFn,
+  logger,
+  strategy,
+}) {
+  let lastResult;
+  let attempt = 0;
+  for (attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
+    if (attempt > 1) {
+      const delay = policy.backoffMs[attempt - 1] ?? 5_000;
+      logger.info(
+        `worktree.install retry ${attempt}/${policy.maxAttempts} after ${delay}ms...`,
+      );
+      sleepFn(delay);
+    }
+    logger.info(
+      `worktree.install strategy=${strategy} cmd=${cmd} attempt=${attempt}/${policy.maxAttempts} path=${cwd}`,
+    );
+    lastResult = spawnFn(cmd, args, {
+      cwd,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      shell,
+      timeout: policy.timeoutMs,
+    });
+    if (lastResult.status === 0) {
+      return { ok: true, attempts: attempt, lastResult };
+    }
+    const reason = describeAttemptFailure(lastResult, policy.timeoutMs);
+    logger.warn(
+      `worktree.install attempt ${attempt} failed (${reason}) stderr=${(lastResult.stderr ?? '').slice(0, 500)}`,
+    );
+  }
+  return { ok: false, attempts: attempt - 1, lastResult };
+}
+
+/**
+ * Run the appropriate package-manager install inside a freshly created
+ * worktree. Non-fatal: logs a warning on failure so the agent can retry.
+ *
+ * Return shape:
+ *   - `{ status: 'installed' }`        — per-worktree install succeeded.
+ *   - `{ status: 'failed', reason }`   — per-worktree install attempted and
+ *                                        failed (or finished 0 but produced
+ *                                        no `node_modules/`).
+ *   - `{ status: 'skipped', reason }`  — strategy intentionally skips a
+ *                                        per-worktree install. Covers
+ *                                        `symlink` (donor `node_modules` is
+ *                                        re-pointed), `pnpm-store` (relies
+ *                                        on the shared content-addressable
+ *                                        store), and the no-`package.json`
+ *                                        case.
+ *
+ * @param {{ config: object, platform: NodeJS.Platform, logger: object }} ctx
+ * @param {string} wtPath Absolute worktree path.
+ * @returns {{ status: 'installed' | 'failed' | 'skipped', reason?: string }}
+ */
+function verifyInstallOutcome(ctx, wtPath, selection, run, policy) {
+  if (!run.ok) {
+    const errFn = ctx.logger.error ?? ctx.logger.warn;
+    errFn.call(
+      ctx.logger,
+      `worktree.install FAILED after ${policy.maxAttempts} attempt(s) of ` +
+        `${selection.cmd} ${selection.args.join(' ')} in ${wtPath}. ` +
+        `Recovery: cd "${wtPath}" ; npm ci  ` +
+        '(falls back to the npm install path; resolve any underlying registry/network issue first).',
+    );
+    return { status: 'failed', reason: 'install-command-nonzero' };
+  }
+  const nmPath = path.join(wtPath, 'node_modules');
+  if (!fs.existsSync(nmPath)) {
+    ctx.logger.warn(
+      `worktree.install cmd=${selection.cmd} exited 0 but node_modules missing at ${nmPath}`,
+    );
+    return { status: 'failed', reason: 'node-modules-missing' };
+  }
+  ctx.logger.info(
+    `worktree.install succeeded cmd=${selection.cmd} path=${wtPath}`,
+  );
+  return null;
+}
+
+export function installDependencies(ctx, wtPath) {
+  const strategy = ctx.config.nodeModulesStrategy ?? 'per-worktree';
+  // `symlink` re-points node_modules at a donor — no install command runs.
+  if (strategy === 'symlink') {
+    return { status: 'skipped', reason: 'symlink-strategy' };
+  }
+  const selection = selectInstallCommand(strategy, wtPath);
+  if (selection === null) {
+    return { status: 'skipped', reason: 'no-package-json' };
+  }
+  // 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 —
+  // the retry ladder below still gets its full budget of attempts.
+  if (strategy === 'pnpm-store' && ctx.repoRoot) {
+    primePnpmStore({
+      strategy,
+      repoRoot: ctx.repoRoot,
+      logger: ctx.logger,
+      shell: ctx.platform === 'win32',
+    });
+  }
+  const policy = installRetryPolicy(selection.cmd);
+  const run = runInstallWithRetry({
+    cmd: selection.cmd,
+    args: selection.args,
+    cwd: wtPath,
+    shell: ctx.platform === 'win32',
+    policy,
+    spawnFn: spawnSync,
+    sleepFn: sleepSync,
+    logger: ctx.logger,
+    strategy,
+  });
+  const verdict = verifyInstallOutcome(ctx, wtPath, selection, run, policy);
+  if (verdict) return verdict;
+  // `pnpm-store` runs `pnpm install --frozen-lockfile`, but the resulting
+  // node_modules is backed by a shared content-addressable store rather
+  // than a self-contained tree. Report `skipped` so the workflow treats
+  // dependency state as N/A and trusts the strategy.
+  if (strategy === 'pnpm-store') {
+    return { status: 'skipped', reason: 'pnpm-store-strategy' };
+  }
+  return { status: 'installed' };
+}
+
+export { sleepSync };

package/.agents/scripts/lib/worktree-manager.js

@@ -0,0 +1,243 @@
+/**
+ * WorktreeManager — single authority over per-story git worktrees.
+ *
+ * This file is a thin facade over `lib/worktree/*`:
+ *   - `lib/worktree/lifecycle-manager.js` — ensure / reap / list / gc / prune.
+ *   - `lib/worktree/node-modules-strategy.js` — per-worktree / symlink / pnpm-store.
+ *   - `lib/worktree/bootstrapper.js` — bootstrap-file copy.
+ *   - `lib/worktree/inspector.js` — pure path + porcelain parsing helpers.
+ *
+ * External callers import `WorktreeManager` and `parseWorktreePorcelain` from
+ * this module path; those exports are preserved verbatim so no other file in
+ * the repo needs to change.
+ *
+ * No other script may call `git worktree` directly. All git calls flow
+ * through the injected `ctx.git` (defaults to `./git-utils.js`). Paths are
+ * resolved and asserted to live inside `repoRoot`, and callers cannot request
+ * force removal; bounded internal fallbacks live in the lifecycle module.
+ */
+
+import path from 'node:path';
+import * as defaultGit from './git-utils.js';
+import { Logger } from './Logger.js';
+import { assertPathContainment } from './path-security.js';
+import {
+  DEFAULT_WORKSPACE_FILES,
+  provision as provisionWorkspace,
+} from './workspace-provisioner.js';
+import {
+  maybeWarnWindowsPath,
+  parseWorktreePorcelain,
+} from './worktree/inspector.js';
+import {
+  ensure,
+  gc,
+  isSafeToRemove,
+  list,
+  pathFor,
+  prune,
+  reap,
+  sweepStaleLocks,
+} from './worktree/lifecycle-manager.js';
+
+export { parseWorktreePorcelain };
+
+export class WorktreeManager {
+  /**
+   * @param {object} opts
+   * @param {string} opts.repoRoot        Absolute path to the main repo.
+   * @param {object} [opts.config]        Resolved `orchestration.worktreeIsolation` config.
+   * @param {object} [opts.logger]        Logger with info/warn/error (defaults to console-style).
+   * @param {object} [opts.git]           Injected `{ gitSync, gitSpawn }` (defaults to git-utils).
+   * @param {NodeJS.Platform} [opts.platform]  Defaults to `process.platform`.
+   * @param {(phase: 'worktree-create'|'bootstrap'|'install') => void} [opts.onPhase]
+   *   Optional phase-boundary callback fired from `ensure()` just before each
+   *   internal phase (git worktree add, bootstrap-file copy, dependency
+   *   install). Consumed by `story-init` to drive `phase-timer.mark()`
+   *   so `[phase-timing]` log lines attribute wall-clock correctly to the
+   *   sub-phases of worktree provisioning.
+   */
+  constructor({
+    repoRoot,
+    config = {},
+    logger,
+    git = defaultGit,
+    platform = process.platform,
+    fsRm,
+    onPhase,
+  }) {
+    if (!repoRoot || typeof repoRoot !== 'string') {
+      throw new Error('WorktreeManager: repoRoot is required');
+    }
+    this.repoRoot = path.resolve(repoRoot);
+    this.config = {
+      root: '.worktrees',
+      nodeModulesStrategy: 'per-worktree',
+      bootstrapFiles: DEFAULT_WORKSPACE_FILES.slice(),
+      ...config,
+    };
+    this.logger = logger ?? {
+      info: (m) => Logger.info(`[WorktreeManager] ${m}`),
+      warn: (m) => Logger.warn(`[WorktreeManager] ⚠️ ${m}`),
+      error: (m) => Logger.error(`[WorktreeManager] ❌ ${m}`),
+    };
+    this.git = git;
+    this.platform = platform;
+    this.fsRm = fsRm;
+    this.onPhase = typeof onPhase === 'function' ? onPhase : null;
+
+    const resolvedRoot = path.resolve(this.repoRoot, this.config.root);
+    try {
+      assertPathContainment(this.repoRoot, resolvedRoot, 'worktreeRoot');
+    } catch {
+      throw new Error(
+        `WorktreeManager: worktreeRoot escapes repoRoot (root=${this.config.root})`,
+      );
+    }
+    this.worktreeRoot = resolvedRoot;
+
+    /** @type {{ list: Array|null, ts: number }} */
+    this._worktreeListCache = { list: null, ts: 0 };
+  }
+
+  /**
+   * Build the context bag shared by every lifecycle helper. Regenerated on
+   * each call so mutating `this.config` between calls is respected, but the
+   * cache slot is a stable object so all helpers see the same list.
+   */
+  _ctx() {
+    return {
+      repoRoot: this.repoRoot,
+      config: this.config,
+      logger: this.logger,
+      git: this.git,
+      platform: this.platform,
+      worktreeRoot: this.worktreeRoot,
+      listCache: this._worktreeListCache,
+      fsRm: this.fsRm,
+      onPhase: this.onPhase,
+      maybeWarnWindowsPath: (wtPath) =>
+        maybeWarnWindowsPath(
+          {
+            platform: this.platform,
+            // Hardcoded post-reshape (Epic #1720 Story #1739). The value
+            // tracks Windows MAX_PATH minus headroom for the worktree's own
+            // path overhead — not a domain knob operators tune.
+            threshold: 240,
+            logger: this.logger,
+          },
+          wtPath,
+        ),
+      copyBootstrapFiles: (wtPath) => {
+        const files = this.config?.bootstrapFiles;
+        if (!Array.isArray(files) || files.length === 0) return;
+        const wrapped = {
+          info: (m) =>
+            this.logger.info(
+              String(m).replace(
+                /^workspace-provisioner:/,
+                'worktree.bootstrap',
+              ),
+            ),
+          warn: (m) =>
+            this.logger.warn(
+              String(m).replace(
+                /^workspace-provisioner:/,
+                'worktree.bootstrap',
+              ),
+            ),
+          error: (m) =>
+            this.logger.error(
+              String(m).replace(
+                /^workspace-provisioner:/,
+                'worktree.bootstrap',
+              ),
+            ),
+        };
+        return provisionWorkspace({
+          sourceRoot: this.repoRoot,
+          targetWorktree: wtPath,
+          files,
+          logger: wrapped,
+        });
+      },
+    };
+  }
+
+  /** Absolute path for a given storyId. */
+  pathFor(storyId) {
+    return pathFor(this._ctx(), storyId);
+  }
+
+  /**
+   * True when this manager was constructed with `config.enabled === false`.
+   * The mutating lifecycle methods (`ensure`, `reap`, `gc`, `sweepStaleLocks`)
+   * short-circuit to no-op shapes in that case so the off-branch never
+   * touches fs or git regardless of caller-side gating drift.
+   */
+  _isDisabled() {
+    return this.config?.enabled === false;
+  }
+
+  /**
+   * Idempotently ensure a worktree exists at `.worktrees/story-<id>/` on `branch`.
+   *
+   * @param {number|string} storyId
+   * @param {string} branch
+   */
+  ensure(storyId, branch) {
+    if (this._isDisabled()) {
+      return {
+        path: null,
+        created: false,
+        skipped: true,
+        reason: 'isolation-disabled',
+      };
+    }
+    return ensure(this._ctx(), storyId, branch);
+  }
+
+  /** Enumerate all worktrees known to git. */
+  list() {
+    return list(this._ctx());
+  }
+
+  /** Check whether a worktree is safe to remove. */
+  isSafeToRemove(wtPath, opts) {
+    return isSafeToRemove(this._ctx(), wtPath, opts);
+  }
+
+  /** Prune stale git worktree registrations for directories that no longer exist. */
+  prune() {
+    return prune(this._ctx());
+  }
+
+  /** Remove the worktree for a given storyId. Rejects caller-requested force. */
+  reap(storyId, opts) {
+    if (this._isDisabled()) {
+      return {
+        removed: false,
+        skipped: true,
+        reason: 'isolation-disabled',
+        path: null,
+      };
+    }
+    return reap(this._ctx(), storyId, opts);
+  }
+
+  /** Sweep abandoned worktrees not in `openStoryIds`. */
+  gc(openStoryIds, opts) {
+    if (this._isDisabled()) {
+      return { reaped: [], skipped: [], skippedReason: 'isolation-disabled' };
+    }
+    return gc(this._ctx(), openStoryIds, opts);
+  }
+
+  /** Sweep stale `*.lock` files under the shared `.git/` dir. */
+  sweepStaleLocks(opts) {
+    if (this._isDisabled()) {
+      return { removed: [], skipped: [], skippedReason: 'isolation-disabled' };
+    }
+    return sweepStaleLocks(this._ctx(), opts);
+  }
+}