session-orchestrator 3.16.0

package/scripts/lib/workspace.mjs

@@ -0,0 +1,198 @@
+/**
+ * workspace.mjs — workspace resolution and path-validation helpers.
+ *
+ * Extracted from worktree.mjs (issue #287) so that workspace concerns
+ * are separate from git worktree lifecycle operations.
+ *
+ * Contains:
+ *  - resolveWorkspaceRoot   — canonical repo-root resolution via git + walk-up fallback
+ *  - restoreCoordinatorCwd  — chdir guard: detects worktree drift and restores CWD
+ *  - validatePathInWorkspace — path-containment check with worktree-subtree exclusion
+ */
+
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { $ } from 'zx';
+import { listWorktrees } from './worktree.mjs';
+
+// Do not spam stdout/stderr with git command echoes.
+$.verbose = false;
+$.quiet = true;
+
+// ---------------------------------------------------------------------------
+// resolveWorkspaceRoot
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the canonical workspace root path — the directory containing the main
+ * .git/worktrees/ (i.e. the coordinator's tree), NOT any agent worktree.
+ *
+ * Resolution order:
+ *   1. `git rev-parse --git-common-dir` → parent directory (this returns the
+ *      SAME path whether called from the main tree or any worktree, unlike
+ *      --show-toplevel which returns the current worktree's tree).
+ *   2. Fallback: walk up from process.cwd() looking for `.git` (directory or file).
+ *   3. If both fail → throw Error with message starting "resolveWorkspaceRoot:".
+ *
+ * Does NOT change process.cwd(). Pure resolution.
+ *
+ * @returns {Promise<string>} absolute path
+ */
+export async function resolveWorkspaceRoot() {
+  const cwd = process.cwd();
+  const git = $({ cwd });
+
+  // Strategy 1: git rev-parse --git-common-dir
+  try {
+    const result = await git`git rev-parse --git-common-dir`;
+    const commonDir = result.stdout.trim();
+    if (commonDir) {
+      // May be relative (when inside a linked worktree) or absolute.
+      const absCommonDir = path.resolve(cwd, commonDir);
+      return path.dirname(absCommonDir);
+    }
+  } catch {
+    // Fall through to walk-up fallback.
+  }
+
+  // Strategy 2: walk up from cwd looking for .git (directory or worktree link file).
+  let p = cwd;
+  let levels = 0;
+  while (levels < 20) {
+    const gitEntry = path.join(p, '.git');
+    if (fsSync.existsSync(gitEntry)) {
+      // Check if .git is a file (worktree link) or a directory.
+      try {
+        const stat = await fs.stat(gitEntry);
+        if (stat.isDirectory()) {
+          return p;
+        }
+        // .git is a file — worktree link. Read it to find gitdir.
+        const content = await fs.readFile(gitEntry, 'utf8');
+        const match = content.match(/^gitdir:\s*(.+)$/m);
+        if (match) {
+          // gitdir points to e.g. /repo/.git/worktrees/agent1
+          // common dir would be /repo/.git — go up to /repo
+          const gitdir = path.resolve(p, match[1].trim());
+          // Walk up to find the real .git directory (not a worktrees subdir).
+          let candidate = gitdir;
+          while (path.dirname(candidate) !== candidate) {
+            const base = path.basename(candidate);
+            const parentBase = path.basename(path.dirname(candidate));
+            if (base !== 'worktrees' && parentBase !== 'worktrees' && fsSync.existsSync(path.join(candidate, 'config'))) {
+              return path.dirname(candidate);
+            }
+            candidate = path.dirname(candidate);
+          }
+        }
+      } catch {
+        // Could not stat or read — treat as found anyway.
+        return p;
+      }
+    }
+    const parent = path.dirname(p);
+    if (parent === p) break; // filesystem root
+    p = parent;
+    levels++;
+  }
+
+  throw new Error(`resolveWorkspaceRoot: could not locate workspace root from '${cwd}'`);
+}
+
+// ---------------------------------------------------------------------------
+// restoreCoordinatorCwd
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether CWD is inside a worktree (anything under .git/worktrees/ or a
+ * registered linked-worktree path), and if so, chdir back to the workspace root.
+ *
+ * Idempotent — when CWD already equals the workspace root, returns without
+ * calling process.chdir().
+ *
+ * @returns {Promise<{restored: boolean, from: string|null, to: string}>}
+ *   restored=true when chdir happened; from is the previous CWD (only when restored);
+ *   to is always the workspace root.
+ */
+export async function restoreCoordinatorCwd() {
+  const cwd = process.cwd();
+  const root = await resolveWorkspaceRoot();
+
+  // Normalize both for comparison (handles trailing slash differences, etc.)
+  const normCwd = path.resolve(cwd);
+  const normRoot = path.resolve(root);
+
+  if (normCwd === normRoot) {
+    return { restored: false, from: null, to: normRoot };
+  }
+
+  // Check if CWD is inside a worktree by listing registered worktrees.
+  let insideWorktree = false;
+  try {
+    const worktrees = await listWorktrees();
+    for (const wt of worktrees) {
+      const wtResolved = path.resolve(wt.path);
+      if (wtResolved === normRoot) continue; // skip main worktree
+      // CWD is inside this linked worktree if it equals or is a descendant.
+      const rel = path.relative(wtResolved, normCwd);
+      if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) {
+        insideWorktree = true;
+        break;
+      }
+    }
+  } catch {
+    // If listing fails, fall back to checking if CWD differs from root.
+    // Any divergence from root is treated as suspect when git-common-dir already
+    // resolved to a different root, so we still restore.
+    insideWorktree = true;
+  }
+
+  if (insideWorktree) {
+    process.chdir(normRoot);
+    return { restored: true, from: normCwd, to: normRoot };
+  }
+
+  return { restored: false, from: null, to: normRoot };
+}
+
+// ---------------------------------------------------------------------------
+// validatePathInWorkspace
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true IFF filePath resolves to a location inside the workspace root AND
+ * NOT inside any .claude/worktrees/* (or .codex/worktrees, .cursor/worktrees) subtree.
+ *
+ * Accepts absolute or relative paths. Relative paths resolve against process.cwd().
+ * Does NOT touch the filesystem beyond reading the workspace root.
+ *
+ * @param {string} filePath
+ * @param {string} [workspaceRoot] optional — if omitted, resolves via resolveWorkspaceRoot()
+ * @returns {Promise<boolean>}
+ */
+export async function validatePathInWorkspace(filePath, workspaceRoot) {
+  const root = workspaceRoot !== undefined ? workspaceRoot : await resolveWorkspaceRoot();
+  const absRoot = path.resolve(root);
+  const absFile = path.resolve(process.cwd(), filePath);
+
+  // Must be inside workspace root (descendant — not equal to root itself).
+  const relToRoot = path.relative(absRoot, absFile);
+  const isInside = relToRoot !== '' && !relToRoot.startsWith('..') && !path.isAbsolute(relToRoot);
+  if (!isInside) return false;
+
+  // Normalize separator to forward-slash for cross-platform startsWith checks.
+  const relNorm = relToRoot.split(path.sep).join('/');
+
+  // Reject paths inside known worktree subtrees.
+  const worktreeSubtrees = [
+    '.claude/worktrees/',
+    '.codex/worktrees/',
+    '.cursor/worktrees/',
+  ];
+  for (const subtree of worktreeSubtrees) {
+    if (relNorm.startsWith(subtree)) return false;
+  }
+
+  return true;
+}

package/scripts/lib/worktree/constants.mjs

@@ -0,0 +1,35 @@
+/**
+ * worktree/constants.mjs — shared constants for the worktree module.
+ *
+ * Leaf module: imports only stdlib and zx. No imports from other
+ * worktree/* submodules.
+ *
+ * Side effect: configures zx to suppress git command echoes on load.
+ */
+
+import { $ } from 'zx';
+
+// Do not spam stdout/stderr with git command echoes.
+$.verbose = false;
+$.quiet = true;
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Default list of top-level directory names to exclude from new worktrees.
+ * Issue #192 — skip build artifacts to reduce RAM spikes on memory-constrained
+ * sessions. Can be overridden per-call via options.excludePatterns or via
+ * Session Config `worktree-exclude`.
+ */
+export const DEFAULT_EXCLUDE_PATTERNS = [
+  'node_modules', 'dist', 'build', '.next', '.nuxt',
+  'coverage', '.cache', '.turbo', '.vercel', 'out',
+];
+
+/**
+ * Relative path (from repo root) where worktree meta JSON files are stored.
+ * Each file is named `<suffix>.json`.
+ */
+export const WORKTREE_META_DIR = '.orchestrator/tmp/worktree-meta';

package/scripts/lib/worktree/index.mjs

@@ -0,0 +1,17 @@
+/**
+ * worktree/index.mjs — re-export hub for all public worktree symbols.
+ *
+ * Public API (7 exports):
+ *   WORKTREE_META_DIR       (constants)
+ *   metaPathFor             (meta)
+ *   listWorktrees           (listing)
+ *   applyWorktreeExcludes   (listing)
+ *   createWorktree          (lifecycle)
+ *   removeWorktree          (lifecycle)
+ *   cleanupAllWorktrees     (lifecycle)
+ */
+
+export { WORKTREE_META_DIR } from './constants.mjs';
+export { metaPathFor } from './meta.mjs';
+export { listWorktrees, applyWorktreeExcludes } from './listing.mjs';
+export { createWorktree, removeWorktree, cleanupAllWorktrees } from './lifecycle.mjs';

package/scripts/lib/worktree/lifecycle.mjs

@@ -0,0 +1,287 @@
+/**
+ * worktree/lifecycle.mjs — git worktree lifecycle operations.
+ *
+ * Exports:
+ *   createWorktree(suffix, baseRef, options)  — create a git worktree
+ *   removeWorktree(wtPath)                    — remove a worktree + branch
+ *   cleanupAllWorktrees()                     — remove all so-worktree-* worktrees
+ *
+ * Internal:
+ *   _exists(p)                — path existence check
+ *   _worktreeInfo(suffix)     — compute branch name + tmp path
+ *
+ * Import DAG (no cycles):
+ *   lifecycle → listing (cleanupAllWorktrees calls listWorktrees)
+ *   lifecycle → meta    (_writeWorktreeMeta)
+ *   lifecycle → constants (WORKTREE_META_DIR, DEFAULT_EXCLUDE_PATTERNS)
+ *   lifecycle → config.mjs (readConfigFile, parseSessionConfig)
+ */
+
+import { $, nothrow, ProcessOutput } from 'zx';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { readConfigFile, parseSessionConfig } from '../config.mjs';
+import { WORKTREE_META_DIR, DEFAULT_EXCLUDE_PATTERNS } from './constants.mjs';
+import { _writeWorktreeMeta } from './meta.mjs';
+import { listWorktrees, applyWorktreeExcludes } from './listing.mjs';
+import { isPathInside } from '../path-utils.mjs';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true if the given path exists on disk (file or directory).
+ * Uses try/catch — no TOCTOU widening.
+ * @param {string} p
+ * @returns {Promise<boolean>}
+ */
+async function _exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Compute the standard branch name and tmp path for a given suffix.
+ * @param {string} suffix
+ * @returns {{ branch: string, wtPath: string }}
+ */
+function _worktreeInfo(suffix) {
+  const branch = `so-worktree-${suffix}`;
+  const wtPath = path.join(os.tmpdir(), 'so-worktrees', branch);
+  return { branch, wtPath };
+}
+
+// ---------------------------------------------------------------------------
+// validateWorkspacePath
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that a computed worktree path is contained within `root`.
+ *
+ * PURE function — no I/O, no side effects. Operates on string inputs only.
+ * Detects: `..` traversal, absolute paths outside root, empty/identical paths,
+ * UNC paths on Windows, and null-byte injection.
+ * Does NOT detect symlink-escape — symlinks are resolved by the filesystem at
+ * write time, not by this helper. Callers that require symlink-safety must run
+ * `fs.realpathSync(computed)` first and pass the resolved path to this helper.
+ *
+ * Delegates CWE-23 hardening to `isPathInside` from `../path-utils.mjs`, which
+ * is the single source of truth for path-traversal safety in this plugin.
+ *
+ * @param {string} computed The path that will be used as the worktree.
+ * @param {string} root The allowed root containing legitimate worktrees.
+ * @returns {boolean} true when `computed` is a strict descendant of `root`.
+ * @throws {TypeError} when either argument is not a non-empty string.
+ *
+ * Used by ADR-364 thin-slice substrate; no production call-sites in this slice.
+ * Will be wired into createWorktree in a follow-up that introduces user-controlled
+ * worktree paths.
+ */
+export function validateWorkspacePath(computed, root) {
+  // isPathInside already validates non-empty strings and throws TypeError on
+  // invalid input — propagate those errors directly to the caller.
+  return isPathInside(computed, root);
+}
+
+// ---------------------------------------------------------------------------
+// createWorktree
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a git worktree for isolated agent work.
+ *
+ * After a successful `git worktree add`, persists a meta JSON file at
+ * `.orchestrator/tmp/worktree-meta/<suffix>.json` for the base-ref freshness
+ * guard (issue #195). Meta write failures are non-fatal — they emit a warning
+ * to stderr but never block worktree creation.
+ *
+ * @param {string} suffix   Unique suffix for the branch (e.g. "wave2-agent1").
+ * @param {string} [baseRef="HEAD"]  Git ref to base the worktree on.
+ * @param {{ excludePatterns?: string[] }} [options={}]
+ *   Optional configuration.
+ *   - `excludePatterns`: list of top-level directory names to remove after
+ *     worktree creation. Overrides the Session Config `worktree-exclude` value
+ *     and the hardcoded default. Pass `[]` to disable all exclusions.
+ * @returns {Promise<string>}  Absolute path to the created worktree.
+ */
+export async function createWorktree(suffix, baseRef = 'HEAD', options = {}) {
+  const { branch, wtPath } = _worktreeInfo(suffix);
+  // Capture cwd at call time so git commands run in the correct repo even if
+  // zx's module-level default cwd differs (e.g. during tests with chdir).
+  const cwd = process.cwd();
+  const git = $({ cwd });
+
+  // Resolve baseSha BEFORE creating the worktree so we capture the exact sha used.
+  let baseSha = null;
+  try {
+    const result = await git`git rev-parse ${baseRef}`;
+    baseSha = result.stdout.trim();
+  } catch {
+    // Non-fatal: freshness guard will treat missing baseSha as no-meta.
+  }
+
+  // Ensure parent directory exists — path.join + recursive mkdir is cross-platform.
+  await fs.mkdir(path.dirname(wtPath), { recursive: true });
+
+  try {
+    await git`git worktree add -b ${branch} ${wtPath} ${baseRef}`;
+  } catch {
+    // Branch or worktree may already exist from a previous failed run — force-cleanup and retry.
+    await nothrow(git`git worktree remove ${wtPath} --force`);
+    await nothrow(git`git branch -D ${branch}`);
+
+    try {
+      await git`git worktree add -b ${branch} ${wtPath} ${baseRef}`;
+    } catch (secondErr) {
+      const msg = secondErr instanceof ProcessOutput ? secondErr.stderr.trim() : String(secondErr);
+      throw new Error(
+        `createWorktree: failed to create worktree for branch '${branch}' at '${wtPath}' (base: ${baseRef}). ` +
+        `git error: ${msg}`,
+        { cause: secondErr }
+      );
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Exclude build artifacts (issue #192)
+  // -------------------------------------------------------------------------
+
+  // Resolve exclude patterns: explicit options > Session Config > hardcoded default.
+  let excludePatterns;
+  if (options.excludePatterns !== undefined) {
+    excludePatterns = options.excludePatterns;
+  } else {
+    // Attempt to read from Session Config; fall back to hardcoded default.
+    // Semantics:
+    //   key absent (undefined)  → fall back to DEFAULT_EXCLUDE_PATTERNS
+    //   key explicit null       → empty array (disable all excludes)
+    //   key is an array         → use that array
+    try {
+      const content = await readConfigFile(process.cwd());
+      const config = parseSessionConfig(content);
+      const fromConfig = config['worktree-exclude'];
+      if (fromConfig === null) {
+        // Explicit `worktree-exclude: null` (YAML null) — user opted out of excludes.
+        excludePatterns = [];
+      } else if (Array.isArray(fromConfig)) {
+        excludePatterns = fromConfig;
+      } else {
+        // Key missing (undefined) or unrecognised value — use hardcoded default.
+        excludePatterns = DEFAULT_EXCLUDE_PATTERNS;
+      }
+    } catch {
+      excludePatterns = DEFAULT_EXCLUDE_PATTERNS;
+    }
+  }
+
+  await applyWorktreeExcludes(wtPath, excludePatterns);
+
+  // Persist meta for freshness guard (issue #195). Non-fatal on failure.
+  await _writeWorktreeMeta(suffix, { branch, wtPath, baseRef, baseSha, repoRoot: cwd }).catch((err) => {
+    console.warn(`createWorktree: meta write failed for '${suffix}' — freshness guard will be skipped: ${err.message}`);
+  });
+
+  return wtPath;
+}
+
+// ---------------------------------------------------------------------------
+// removeWorktree
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove a worktree and its associated branch.
+ * Emits a warning to stderr (does not throw) if uncommitted changes exist.
+ * Also cleans up the meta file written by createWorktree (issue #195).
+ * Always resolves — never throws.
+ *
+ * @param {string} wtPath  Absolute path to the worktree to remove.
+ * @returns {Promise<void>}
+ */
+export async function removeWorktree(wtPath) {
+  // No-op if path does not exist.
+  if (!(await _exists(wtPath))) {
+    return;
+  }
+
+  // Capture cwd at call time for the same reason as createWorktree.
+  const cwd = process.cwd();
+  const git = $({ cwd });
+
+  // Warn about uncommitted changes without throwing.
+  try {
+    const status = await git`git -C ${wtPath} status --porcelain`;
+    if (status.stdout.trim().length > 0) {
+      console.error(`WARNING: worktree at ${wtPath} has uncommitted changes`);
+    }
+  } catch {
+    // Ignore — worktree may already be partially detached.
+  }
+
+  // Resolve the branch name, but only accept so-worktree-* names.
+  let branch = '';
+  try {
+    const ref = await git`git -C ${wtPath} rev-parse --abbrev-ref HEAD`;
+    const candidate = ref.stdout.trim();
+    if (/^so-worktree-/.test(candidate)) {
+      branch = candidate;
+    }
+  } catch {
+    // Ignore — best-effort.
+  }
+
+  // Remove worktree (force so it works even with dirty state).
+  await nothrow(git`git worktree remove ${wtPath} --force`);
+
+  // Clean up the temporary branch (best-effort).
+  if (branch) {
+    await nothrow(git`git branch -D ${branch}`);
+  }
+
+  // Clean up meta file (issue #195). Derive suffix from branch name.
+  // branch is "so-worktree-<suffix>"; if branch is empty, fall back to wtPath basename.
+  const suffix = branch
+    ? branch.replace(/^so-worktree-/, '')
+    : path.basename(wtPath).replace(/^so-worktree-/, '');
+
+  if (suffix) {
+    const metaPath = path.join(cwd, WORKTREE_META_DIR, `${suffix}.json`);
+    await fs.unlink(metaPath).catch((err) => {
+      if (err.code !== 'ENOENT') {
+        console.warn(`removeWorktree: meta cleanup failed for '${suffix}': ${err.message}`);
+      }
+      // ENOENT — already gone or never written; silently ignore.
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// cleanupAllWorktrees
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove all session-orchestrator worktrees (branches matching so-worktree-*),
+ * then prune stale worktree references.
+ * Always resolves — never throws.
+ *
+ * @returns {Promise<void>}
+ */
+export async function cleanupAllWorktrees() {
+  try {
+    const worktrees = await listWorktrees();
+    const soWorktrees = worktrees.filter(wt => /^so-worktree-/.test(wt.branch));
+
+    for (const wt of soWorktrees) {
+      await removeWorktree(wt.path);
+    }
+  } catch {
+    // Best-effort — swallow any unexpected errors.
+  }
+
+  await nothrow($({ cwd: process.cwd() })`git worktree prune`);
+}

package/scripts/lib/worktree/listing.mjs

@@ -0,0 +1,118 @@
+/**
+ * worktree/listing.mjs — list and filter worktrees.
+ *
+ * Exports:
+ *   listWorktrees()                            — list all git worktrees
+ *   applyWorktreeExcludes(wtPath, patterns)    — remove top-level dirs from worktree
+ *
+ * No imports from lifecycle.mjs — this module is intentionally a leaf of the
+ * lifecycle import chain (lifecycle imports listing, not the reverse).
+ */
+
+import { $ as defaultDollar } from 'zx';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// listWorktrees
+// ---------------------------------------------------------------------------
+
+/**
+ * List all git worktrees in the current repository.
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.$]  Optional zx-compatible executor. Defaults to real zx.$.
+ *   Tests pass a mock here to avoid vi.mock('zx') under fork pool.
+ * @returns {Promise<Array<{path: string, branch: string, head: string}>>}
+ *   Array of worktree descriptors; empty array if none or on parse error.
+ */
+export async function listWorktrees(opts = {}) {
+  const dollar = opts.$ ?? defaultDollar;
+  const git = dollar({ cwd: process.cwd() });
+  let output;
+  try {
+    const result = await git`git worktree list --porcelain`;
+    output = result.stdout;
+  } catch {
+    return [];
+  }
+
+  const worktrees = [];
+  let current = null;
+
+  for (const rawLine of output.split('\n')) {
+    const line = rawLine.trimEnd();
+
+    if (line.startsWith('worktree ')) {
+      // Each new 'worktree' line starts a new record.
+      if (current !== null) {
+        worktrees.push(current);
+      }
+      current = { path: line.slice('worktree '.length), branch: '', head: '' };
+    } else if (line.startsWith('HEAD ') && current !== null) {
+      current.head = line.slice('HEAD '.length);
+    } else if (line.startsWith('branch ') && current !== null) {
+      // Branch is stored as refs/heads/<name> — strip the prefix.
+      const ref = line.slice('branch '.length);
+      current.branch = ref.replace(/^refs\/heads\//, '');
+    } else if (line === '' && current !== null) {
+      // Blank line separates records in --porcelain output.
+      worktrees.push(current);
+      current = null;
+    }
+  }
+
+  // Flush any trailing record (no trailing blank line at EOF).
+  if (current !== null) {
+    worktrees.push(current);
+  }
+
+  return worktrees;
+}
+
+// ---------------------------------------------------------------------------
+// applyWorktreeExcludes
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove top-level directories matching `patterns` from a worktree path.
+ * Pure fs operation — no git, no zx. Exported for unit testing (issue #192).
+ *
+ * @param {string} wtPath  Absolute path to the worktree root.
+ * @param {string[]} patterns  Top-level directory names to remove.
+ * @returns {Promise<void>}
+ */
+export async function applyWorktreeExcludes(wtPath, patterns) {
+  if (!patterns || patterns.length === 0) return;
+
+  let anyRemoved = false;
+  let allFailed = true;
+
+  for (const pattern of patterns) {
+    const targetPath = path.join(wtPath, pattern);
+    let dirExists;
+    try {
+      const stat = await fs.stat(targetPath);
+      dirExists = stat.isDirectory();
+    } catch {
+      // Pattern does not exist — silently skip.
+      allFailed = false; // not a failure, just absent
+      continue;
+    }
+
+    if (dirExists) {
+      try {
+        await fs.rm(targetPath, { recursive: true, force: true });
+        process.stderr.write(`[worktree] excluded: ${pattern}\n`);
+        anyRemoved = true;
+        allFailed = false;
+      } catch {
+        // Individual removal failure — continue with remaining patterns.
+      }
+    }
+  }
+
+  if (anyRemoved === false && allFailed) {
+    process.stderr.write(`[worktree] WARNING: all pattern removals failed for worktree at ${wtPath}\n`);
+  }
+}