@paths.design/caws-cli 10.2.0 → 11.0.0

package/dist/worktree/worktree-manager.js

@@ -1,1735 +0,0 @@
-/**
- * @fileoverview CAWS Git Worktree Manager
- * Provides CRUD operations for git worktrees with scope isolation
- * @author @darianrosebrook
- */
-
-const { execFileSync } = require('child_process');
-const fs = require('fs-extra');
-const path = require('path');
-const chalk = require('chalk');
-const { createValidator, getSchemaPath } = require('../utils/schema-validator');
-const {
-  getAgentSessionId,
-  loadAgentRegistry,
-  findSessionLogs,
-  refreshAgentClaim,
-} = require('../utils/agent-session');
-const { formatClaimNotice, formatOrphanLogHint } = require('../utils/agent-display');
-const { lifecycle, EVENTS } = require('../utils/lifecycle-events');
-
-const WORKTREES_DIR = '.caws/worktrees';
-const REGISTRY_FILE = '.caws/worktrees.json';
-const BRANCH_PREFIX = 'caws/';
-
-function findFeatureSpecPath(root, specId) {
-  if (!specId) return null;
-
-  const candidates = [
-    path.join(root, '.caws', 'specs', `${specId}.yaml`),
-    path.join(root, '.caws', 'specs', `${specId}.yml`),
-  ];
-
-  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
-}
-
-/**
- * Resolve a feature spec path, preferring a worktree-local copy when cwd
- * is inside a worktree. Falls back to the main repo.
- *
- * Why two-step: `caws worktree bind` may be invoked from inside a worktree
- * that was forked off a non-main base branch (Option C fork-off-sibling
- * pattern). In that workflow the spec is committed on the worktree's own
- * branch and never lands on main. The pre-CAWSFIX-25 behavior of looking
- * only in `root/.caws/specs/` made bind unusable there (D8 ledger entry).
- *
- * @param {string} root - Main repo root (from getRepoRoot())
- * @param {string} specId - Spec identifier
- * @param {string} [cwd=process.cwd()] - Directory to resolve from
- * @returns {string|null} Absolute path to the spec file, or null
- */
-function findFeatureSpecPathFromCwd(root, specId, cwd) {
-  if (!specId) return null;
-  const effectiveCwd = cwd || process.cwd();
-
-  // Normalize both sides against symlinks before comparing. On macOS
-  // `/tmp` and `/var/folders` are symlinks under `/private`, so the literal
-  // `startsWith` check fails intermittently in the test fixture. Fall back
-  // to the pre-resolution path if realpath throws (e.g., cwd removed).
-  const resolve = (p) => {
-    try { return fs.realpathSync(p); } catch { return p; }
-  };
-  const resolvedCwd = resolve(effectiveCwd);
-  const worktreesBase = resolve(path.join(root, '.caws', 'worktrees'));
-
-  if (resolvedCwd.startsWith(worktreesBase + path.sep)) {
-    const relative = path.relative(worktreesBase, resolvedCwd);
-    const worktreeName = relative.split(path.sep)[0];
-    if (worktreeName) {
-      const worktreeRoot = path.join(worktreesBase, worktreeName);
-      const local = findFeatureSpecPath(worktreeRoot, specId);
-      if (local) return local;
-    }
-  }
-
-  return findFeatureSpecPath(root, specId);
-}
-
-function writeSpecWithWorktree(filePath, worktreeName) {
-  const yaml = require('js-yaml');
-  const content = fs.readFileSync(filePath, 'utf8');
-  const parsed = yaml.load(content);
-  if (!parsed || typeof parsed !== 'object') {
-    return content;
-  }
-
-  // CAWSFIX-24 / D10: if the on-disk spec already declares the target
-  // worktree and reloads to an equivalent object, return the original
-  // bytes untouched. js-yaml.dump re-wraps folded scalars at its own
-  // line-width preference, which otherwise produces spurious bytes-only
-  // diffs on every bind/create. That mechanical churn (a) leaves dirty
-  // files on main after worktree create, and (b) causes merge conflicts
-  // when two validator invocations wrap the same title at different
-  // widths.
-  if (parsed.worktree === worktreeName) {
-    return content;
-  }
-
-  parsed.worktree = worktreeName;
-  return yaml.dump(parsed, { lineWidth: 120, noRefs: true });
-}
-
-function hasPathChanges(root, relativePath) {
-  try {
-    const output = execFileSync(
-      'git',
-      ['status', '--porcelain', '--', relativePath],
-      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
-    ).trim();
-    return output.length > 0;
-  } catch {
-    return false;
-  }
-}
-
-function ensureCanonicalSpecCommitted(root, specPath, specId, worktreeName) {
-  const relativeSpecPath = path.relative(root, specPath);
-  const nextContent = writeSpecWithWorktree(specPath, worktreeName);
-  const currentContent = fs.readFileSync(specPath, 'utf8');
-
-  if (currentContent !== nextContent) {
-    fs.writeFileSync(specPath, nextContent);
-  }
-
-  if (!hasPathChanges(root, relativeSpecPath)) {
-    return false;
-  }
-
-  execFileSync('git', ['add', '--', relativeSpecPath], {
-    cwd: root,
-    stdio: 'pipe',
-  });
-  execFileSync(
-    'git',
-    ['commit', '-m', `chore(caws): bind spec ${specId} to worktree ${worktreeName}`, '--', relativeSpecPath],
-    {
-      cwd: root,
-      stdio: 'pipe',
-    }
-  );
-  return true;
-}
-
-function materializeWorktreeSpec(root, cawsDest, specId, worktreeName, scope) {
-  if (!specId) return;
-
-  const canonicalSpecPath = findFeatureSpecPath(root, specId);
-  const destSpecsDir = path.join(cawsDest, 'specs');
-
-  // CAWSFIX-24 / D5: never write to .caws/working-spec.yaml inside the
-  // worktree. That file is the shared project baseline and must remain
-  // byte-identical to what was checked out from HEAD. The feature spec
-  // is materialized only under .caws/specs/<id>.yaml, which is what
-  // spec-resolver and commands actually read via --spec-id / registry.
-
-  if (canonicalSpecPath) {
-    const destSpecPath = path.join(destSpecsDir, path.basename(canonicalSpecPath));
-    fs.ensureDirSync(destSpecsDir);
-
-    // Keep a canonical feature-spec copy inside the worktree.
-    const specContent = writeSpecWithWorktree(canonicalSpecPath, worktreeName);
-    // writeSpecWithWorktree is idempotent (CAWSFIX-24 / D10): if the spec
-    // already has the worktree field and reloads to equivalent YAML, the
-    // returned content matches what's on disk. Skip the write in that case
-    // so `git status` stays clean.
-    const existing = fs.existsSync(destSpecPath) ? fs.readFileSync(destSpecPath, 'utf8') : null;
-    if (existing !== specContent) {
-      fs.writeFileSync(destSpecPath, specContent);
-    }
-    return;
-  }
-
-  // specId given but no canonical spec found — generate a default feature
-  // spec at .caws/specs/<specId>.yaml so the worktree has something to
-  // resolve against. Do not touch .caws/working-spec.yaml.
-  console.warn(
-    chalk.yellow(`Warning: spec '${specId}' not found in .caws/specs/ — generating default feature spec for worktree`)
-  );
-
-  const { generateWorkingSpec } = require('../generators/working-spec');
-  let specContent = generateWorkingSpec({
-    projectId: specId,
-    projectTitle: `Worktree: ${worktreeName}`,
-    projectDescription: `Isolated worktree for ${worktreeName}`,
-    riskTier: 3,
-    projectMode: 'feature',
-    scopeIn: scope || 'src/',
-    scopeOut: 'node_modules/, dist/, build/',
-    maxFiles: 25,
-    maxLoc: 1000,
-    blastModules: scope || 'src',
-    dataMigration: false,
-    rollbackSlo: '5m',
-    projectThreats: '',
-    projectInvariants: 'System maintains data consistency',
-    acceptanceCriteria: 'Given current state, when action occurs, then expected result',
-    a11yRequirements: 'keyboard',
-    perfBudget: 250,
-    securityRequirements: 'validation',
-    contractType: '',
-    contractPath: '',
-    observabilityLogs: '',
-    observabilityMetrics: '',
-    observabilityTraces: '',
-    migrationPlan: '',
-    rollbackPlan: '',
-    needsOverride: false,
-    isExperimental: false,
-    aiConfidence: 0.8,
-    uncertaintyAreas: '',
-    complexityFactors: '',
-  });
-
-  try {
-    const yaml = require('js-yaml');
-    const parsed = yaml.load(specContent);
-    if (parsed && typeof parsed === 'object') {
-      parsed.worktree = worktreeName;
-      specContent = yaml.dump(parsed, { lineWidth: 120, noRefs: true });
-    }
-  } catch {
-    // Keep generated spec content if augmentation fails.
-  }
-
-  fs.ensureDirSync(destSpecsDir);
-  const generatedSpecPath = path.join(destSpecsDir, `${specId}.yaml`);
-  fs.writeFileSync(generatedSpecPath, specContent);
-}
-
-function parseSpecIdFromYamlFile(filePath) {
-  try {
-    const yaml = require('js-yaml');
-    const doc = yaml.load(fs.readFileSync(filePath, 'utf8'));
-    if (doc && typeof doc.id === 'string' && doc.id.trim()) {
-      return doc.id.trim();
-    }
-  } catch {
-    // Ignore malformed YAML during inference
-  }
-  return null;
-}
-
-/**
- * Scan .caws/specs/ for a spec that declares `worktree: <name>`.
- * Returns the spec's id if found, null otherwise.
- * This enables auto-binding: when a spec already names the worktree
- * it expects, the registry entry gets the specId automatically.
- * @param {string} root - Repository root
- * @param {string} worktreeName - Worktree name to match
- * @returns {string|null} Spec ID or null
- */
-function findSpecByWorktreeName(root, worktreeName) {
-  const yaml = require('js-yaml');
-  const specsDir = path.join(root, '.caws', 'specs');
-  if (!fs.existsSync(specsDir)) return null;
-
-  const specFiles = fs.readdirSync(specsDir)
-    .filter((name) => name.endsWith('.yaml') || name.endsWith('.yml'));
-
-  for (const specFile of specFiles) {
-    try {
-      const doc = yaml.load(fs.readFileSync(path.join(specsDir, specFile), 'utf8'));
-      if (doc && doc.worktree === worktreeName && typeof doc.id === 'string') {
-        return doc.id.trim();
-      }
-    } catch {
-      // Skip malformed spec files
-    }
-  }
-  return null;
-}
-
-function inferSpecIdForWorktree(worktreePath) {
-  if (!worktreePath) return null;
-
-  const specsDir = path.join(worktreePath, '.caws', 'specs');
-  if (fs.existsSync(specsDir)) {
-    const specFiles = fs.readdirSync(specsDir)
-      .filter((name) => name.endsWith('.yaml') || name.endsWith('.yml'))
-      .sort();
-
-    for (const specFile of specFiles) {
-      const inferred = parseSpecIdFromYamlFile(path.join(specsDir, specFile));
-      if (inferred) {
-        return inferred;
-      }
-    }
-  }
-
-  return parseSpecIdFromYamlFile(path.join(worktreePath, '.caws', 'working-spec.yaml'));
-}
-
-/**
- * Get the last commit info for a branch
- * @param {string} branch - Branch name
- * @param {string} root - Repository root
- * @returns {{ age: string, timestamp: Date, sha: string } | null}
- */
-function getLastCommitInfo(branch, root) {
-  try {
-    const output = execFileSync(
-      'git',
-      ['log', branch, '-1', '--format=%H%n%aI%n%ar'],
-      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
-    ).trim();
-    const [sha, iso, age] = output.split('\n');
-    return { sha, timestamp: new Date(iso), age };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check if a branch has been merged into another branch
- * @param {string} branch - Branch to check
- * @param {string} target - Target branch (e.g., "main")
- * @param {string} root - Repository root
- * @returns {boolean}
- */
-function isBranchMerged(branch, target, root) {
-  try {
-    const merged = execFileSync(
-      'git',
-      ['branch', '--merged', target, '--list', branch],
-      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
-    ).trim();
-    return merged.length > 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if a branch has divergent commits from target (commits on branch not on target).
- * @param {string} branch - Branch to check
- * @param {string} target - Target branch (e.g., "main")
- * @param {string} root - Repository root
- * @returns {boolean}
- */
-function hasDivergentCommits(branch, target, root) {
-  try {
-    const count = execFileSync(
-      'git',
-      ['rev-list', '--count', `${target}..${branch}`],
-      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
-    ).trim();
-    return parseInt(count, 10) > 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if a worktree directory has dirty (uncommitted) files.
- * @param {string} worktreePath - Path to the worktree
- * @returns {boolean}
- */
-function hasDirtyFiles(worktreePath) {
-  try {
-    const status = execFileSync(
-      'git',
-      ['status', '--porcelain'],
-      { cwd: worktreePath, encoding: 'utf8', stdio: 'pipe' }
-    ).trim();
-    return status.length > 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Get the canonical git repository root (main worktree, not a linked worktree).
- *
- * `git rev-parse --show-toplevel` returns the root of whichever worktree
- * the CWD is inside. In a linked worktree that is NOT the main repo root,
- * so CAWS would read the wrong (or missing) .caws/worktrees.json.
- *
- * `--git-common-dir` always resolves to the main repo's .git directory,
- * even from inside a linked worktree. Its parent is the canonical repo root.
- *
- * @returns {string} Absolute path to the main repo root
- */
-function getRepoRoot() {
-  const gitCommonDir = execFileSync(
-    'git',
-    ['rev-parse', '--path-format=absolute', '--git-common-dir'],
-    { encoding: 'utf8' }
-  ).trim();
-  // gitCommonDir is /path/to/main-repo/.git — parent is the repo root
-  return path.dirname(gitCommonDir);
-}
-
-/**
- * Get current branch name
- * @returns {string}
- */
-function getCurrentBranch() {
-  return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
-    encoding: 'utf8',
-  }).trim();
-}
-
-// Track whether we've already warned about schema violations this process.
-// loadRegistry() is called multiple times per command; warning every time
-// floods stderr and contributes to Claude Code context-window exhaustion.
-let _schemaWarned = false;
-
-/**
- * CAWSFIX-31: Assert that the current agent session may operate on
- * worktree `name`. The decision is purely session-id-equality based —
- * never TTL, never log freshness — because rolled-over and resumed
- * sessions should not be auto-blocked just because their registry
- * entry was pruned.
- *
- * Returns `{ allowed, warning?, priorOwner? }`. The caller decides
- * how to react:
- *
- *   - allowed=true,  no warning            → silent proceed (same session id, no claim, etc.)
- *   - allowed=true,  warning present       → soft notice (orphan session log, no block)
- *   - allowed=false, warning present       → soft-block; surface warning, exit non-zero
- *
- * On takeover (`allowTakeover: true`), the function rewrites the
- * worktree entry's owner to the current session id and appends the
- * prior owner to a `prior_owners` audit array (with lastSeen captured
- * from agents.json at takeover time, or null if pruned).
- *
- * @param {string} root - Project root
- * @param {string} name - Worktree name
- * @param {object} [opts]
- * @param {boolean} [opts.allowTakeover=false] - Apply takeover when true
- * @param {string} [opts.takeoverCommandHint] - Suggested command for the warning
- * @returns {{ allowed: boolean, warning?: string, priorOwner?: object }}
- */
-function assertWorktreeOwnership(root, name, opts = {}) {
-  const { allowTakeover = false, takeoverCommandHint } = opts;
-  const registry = loadRegistry(root);
-  const entry = registry.worktrees[name];
-  if (!entry) {
-    return { allowed: true };
-  }
-
-  const currentSession = getAgentSessionId(root);
-  const owner = entry.owner;
-
-  // No CAWS-tracked owner — surface session-log hint if present, but
-  // allow the operation to proceed.
-  if (!owner) {
-    const branch = entry.branch || null;
-    const logs = branch ? findSessionLogs(root, { branch }) : [];
-    if (logs.length > 0) {
-      return {
-        allowed: true,
-        warning: formatOrphanLogHint({ worktree: name, sessionLogs: logs, root }),
-      };
-    }
-    return { allowed: true };
-  }
-
-  // Same session id → silent proceed. Roll-over case included: an
-  // agent that resumed with the same session id is its own claimant.
-  if (currentSession && owner === currentSession) {
-    return { allowed: true };
-  }
-
-  // Foreign claim — gather context.
-  const agentRegistry = loadAgentRegistry(root);
-  const priorOwnerEntry = agentRegistry.agents[owner] || null;
-  const priorOwnerLastSeen = priorOwnerEntry ? priorOwnerEntry.lastSeen : null;
-  const priorOwnerPlatform = priorOwnerEntry ? priorOwnerEntry.platform : 'unknown';
-
-  // Surface session-log pointers (by sid OR by branch).
-  const branch = entry.branch || null;
-  const seen = new Set();
-  const sessionLogs = [];
-  for (const log of findSessionLogs(root, { sessionId: owner })) {
-    if (seen.has(log.path)) continue;
-    seen.add(log.path);
-    sessionLogs.push(log);
-  }
-  if (branch) {
-    for (const log of findSessionLogs(root, { branch })) {
-      if (seen.has(log.path)) continue;
-      seen.add(log.path);
-      sessionLogs.push(log);
-    }
-  }
-
-  const takeoverCommand =
-    takeoverCommandHint || `caws worktree claim ${name} --takeover`;
-  const warning = formatClaimNotice({
-    worktree: name,
-    priorOwnerEntry,
-    priorOwnerSessionId: owner,
-    sessionLogs,
-    root,
-    takeoverCommand,
-  });
-
-  if (!allowTakeover) {
-    return { allowed: false, warning };
-  }
-
-  // Takeover: rewrite owner, append prior_owners audit entry.
-  const priorOwners = Array.isArray(entry.prior_owners) ? entry.prior_owners : [];
-  priorOwners.push({
-    sessionId: owner,
-    platform: priorOwnerPlatform,
-    lastSeen: priorOwnerLastSeen,
-    takenOver_at: new Date().toISOString(),
-  });
-  registry.worktrees[name] = {
-    ...entry,
-    owner: currentSession || null,
-    prior_owners: priorOwners,
-  };
-  saveRegistry(root, registry);
-
-  // Heartbeat the new owner so agents.json reflects the takeover too.
-  // Without this, `caws status` and `caws agents list` would show the
-  // takeover'd worktree with an "unknown / pruned" current owner until
-  // some other lifecycle verb fires.
-  refreshAgentClaim(root, { worktree: name });
-
-  return {
-    allowed: true,
-    priorOwner: {
-      sessionId: owner,
-      platform: priorOwnerPlatform,
-      lastSeen: priorOwnerLastSeen,
-    },
-  };
-}
-
-/**
- * Load the worktree registry
- * @param {string} root - Repository root
- * @returns {Object} Registry object
- */
-function loadRegistry(root) {
-  const registryPath = path.join(root, REGISTRY_FILE);
-  try {
-    if (fs.existsSync(registryPath)) {
-      const data = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
-      try {
-        const validate = createValidator(getSchemaPath('worktrees.schema.json', root));
-        const result = validate(data);
-        if (!result.valid && !_schemaWarned) {
-          _schemaWarned = true;
-          console.warn('Worktree registry has schema violations:', result.errors);
-        }
-      } catch (schemaErr) {
-        if (!_schemaWarned) {
-          _schemaWarned = true;
-          console.warn('Could not validate worktree registry schema:', schemaErr.message);
-        }
-      }
-      return data;
-    }
-  } catch {
-    // Corrupted registry, start fresh
-  }
-  return { version: 1, worktrees: {} };
-}
-
-/**
- * Save the worktree registry
- * @param {string} root - Repository root
- * @param {Object} registry - Registry object
- */
-function saveRegistry(root, registry) {
-  // Auto-prune ghost entries: any registry entry whose path directory AND
-  // stored branch are BOTH gone. Previously this only fired for entries
-  // explicitly marked `status: destroyed`, which missed two common cases:
-  //   1. A worktree removed via `git worktree remove` (not `caws worktree
-  //      destroy`) that later had its branch manually deleted with
-  //      `git branch -D`.
-  //   2. A worktree whose create failed partway, leaving a registry entry
-  //      at `fresh`/`active` but no artifacts on disk.
-  // Both are pure ghost state — no recoverable work remains in either
-  // the directory or the branch. Pruning is safe. (CAWSFIX-25 / D7)
-  //
-  // Entries with ONE artifact intact (dir gone but branch still present,
-  // or vice versa) are preserved. The branch may still hold unmerged
-  // commits, or the directory may still hold uncommitted work — the user
-  // should merge or explicitly destroy.
-  for (const [name, entry] of Object.entries(registry.worktrees || {})) {
-    const dirGone = !fs.existsSync(entry.path);
-    let branchGone = true;
-    if (entry.branch) {
-      try {
-        execFileSync('git', ['rev-parse', '--verify', entry.branch], {
-          cwd: root, stdio: 'pipe',
-        });
-        branchGone = false;
-      } catch {
-        branchGone = true;
-      }
-    }
-    if (dirGone && branchGone) {
-      delete registry.worktrees[name];
-    }
-  }
-
-  const registryPath = path.join(root, REGISTRY_FILE);
-  fs.ensureDirSync(path.dirname(registryPath));
-  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));
-}
-
-/**
- * Discover git worktrees under .caws/worktrees/ that are not in the registry.
- * @param {string} root - Repository root
- * @param {Object} registry - Current registry object
- * @returns {Array<{ name: string, path: string, branch: string }>}
- */
-function discoverUnregisteredWorktrees(root, registry) {
-  const unregistered = [];
-  try {
-    const output = execFileSync('git', ['worktree', 'list', '--porcelain'], {
-      cwd: root,
-      encoding: 'utf8',
-      stdio: 'pipe',
-    });
-    let worktreesDir;
-    try {
-      worktreesDir = fs.realpathSync(path.resolve(root, WORKTREES_DIR));
-    } catch {
-      // Directory might not exist yet
-      worktreesDir = path.resolve(root, WORKTREES_DIR);
-    }
-
-    const blocks = output.split('\n\n').filter(Boolean);
-    for (const block of blocks) {
-      const lines = block.split('\n');
-      const wtLine = lines.find((l) => l.startsWith('worktree '));
-      const branchLine = lines.find((l) => l.startsWith('branch '));
-      if (!wtLine) continue;
-
-      const wtPath = wtLine.replace('worktree ', '');
-      let resolvedPath;
-      try {
-        resolvedPath = fs.realpathSync(wtPath);
-      } catch {
-        resolvedPath = path.resolve(wtPath);
-      }
-
-      // Only consider worktrees under .caws/worktrees/
-      if (!resolvedPath.startsWith(worktreesDir + path.sep)) continue;
-
-      const name = path.basename(resolvedPath);
-      if (registry.worktrees[name]) continue;
-
-      const branch = branchLine
-        ? branchLine.replace('branch refs/heads/', '')
-        : `${BRANCH_PREFIX}${name}`;
-      unregistered.push({ name, path: resolvedPath, branch });
-    }
-  } catch {
-    // git worktree list failed
-  }
-  return unregistered;
-}
-
-/**
- * Auto-register an unregistered worktree. Infers baseBranch via merge-base.
- * @param {string} root - Repository root
- * @param {Object} registry - Registry object (mutated in place)
- * @param {{ name: string, path: string, branch: string }} discovered
- * @returns {Object} The registered entry
- */
-function autoRegisterWorktree(root, registry, discovered) {
-  let baseBranch = 'main';
-  try {
-    execFileSync(
-      'git',
-      ['merge-base', discovered.branch, 'main'],
-      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
-    );
-  } catch {
-    try {
-      execFileSync(
-        'git',
-        ['merge-base', discovered.branch, 'master'],
-        { cwd: root, encoding: 'utf8', stdio: 'pipe' }
-      );
-      baseBranch = 'master';
-    } catch {
-      // Keep 'main' as default
-    }
-  }
-
-  const entry = {
-    name: discovered.name,
-    path: discovered.path,
-    branch: discovered.branch,
-    baseBranch,
-    scope: null,
-    specId: inferSpecIdForWorktree(discovered.path),
-    owner: null,
-    createdAt: new Date().toISOString(),
-    status: 'active',
-    autoRegistered: true,
-  };
-
-  registry.worktrees[discovered.name] = entry;
-  saveRegistry(root, registry);
-  return entry;
-}
-
-/**
- * Create a new git worktree with scope isolation
- * @param {string} name - Worktree name
- * @param {Object} options - Creation options
- * @param {string} [options.scope] - Sparse checkout pattern (e.g., "src/auth/**")
- * @param {string} [options.baseBranch] - Base branch to create from
- * @param {string} [options.specId] - Associated spec ID for standard+ modes
- * @returns {Object} Created worktree info
- */
-function createWorktree(name, options = {}) {
-  const root = getRepoRoot();
-  const { scope, baseBranch, specId } = options;
-
-  // Validate name
-  if (!name || !/^[a-zA-Z0-9_-]+$/.test(name)) {
-    throw new Error('Worktree name must contain only letters, numbers, hyphens, and underscores');
-  }
-
-  const registry = loadRegistry(root);
-
-  // Check for duplicate in registry
-  if (registry.worktrees[name]) {
-    const existing = registry.worktrees[name];
-    if (existing.status !== 'destroyed') {
-      const ownerInfo = existing.owner ? ` (owned by session ${existing.owner})` : '';
-      throw new Error(
-        `Worktree '${name}' already exists with status '${existing.status}'${ownerInfo}.\n` +
-        `Use 'caws worktree destroy ${name}' first, or choose a different name.`
-      );
-    }
-    // Destroyed entries: check if another session owns the branch
-    if (existing.owner && existing.owner !== getAgentSessionId(root)) {
-      // Branch may still be in use by the owning session for merge
-      try {
-        const branchExists = execFileSync('git', ['rev-parse', '--verify', BRANCH_PREFIX + name], {
-          cwd: root, stdio: 'pipe',
-        }).toString().trim();
-        if (branchExists) {
-          throw new Error(
-            `Worktree '${name}' was destroyed but branch '${BRANCH_PREFIX}${name}' still exists ` +
-            `(owned by session ${existing.owner}).\n` +
-            `The owning session may still need this branch for merging.\n` +
-            `Choose a different name, or delete the branch first: git branch -d ${BRANCH_PREFIX}${name}`
-          );
-        }
-      } catch (e) {
-        if (e.message.includes('owned by session')) throw e;
-        // Branch doesn't exist — safe to reuse the name
-      }
-    }
-  }
-
-  const worktreePath = path.join(root, WORKTREES_DIR, name);
-  const branchName = BRANCH_PREFIX + name;
-  const base = baseBranch || getCurrentBranch();
-
-  // CAWSFIX-27: resolve the bound specId (explicit --spec-id OR auto-bind
-  // via worktree-name match) BEFORE creating the worktree, so the
-  // draft→active flip + bind commit land on the base branch before the
-  // worktree forks. Pre-CAWSFIX-27 the auto-bind path activated the spec
-  // but never committed it, leaving main with a dirty spec after
-  // `caws worktree create <name>` (no --spec-id).
-  let resolvedSpecId = specId || null;
-  if (!resolvedSpecId) {
-    resolvedSpecId = findSpecByWorktreeName(root, name);
-    if (resolvedSpecId) {
-      console.log(chalk.gray(`   Auto-bound spec: ${resolvedSpecId}`));
-    }
-  }
-  const canonicalSpecPath = findFeatureSpecPath(root, resolvedSpecId);
-
-  // Check if the branch already exists in git (even if not in registry)
-  // This catches cases where another agent created the branch outside CAWS
-  try {
-    execFileSync('git', ['rev-parse', '--verify', branchName], {
-      cwd: root, stdio: 'pipe',
-    });
-    // Branch exists — refuse unless it's fully merged into base
-    const currentSession = getAgentSessionId(root);
-    const registryOwner = registry.worktrees[name]?.owner;
-    if (registryOwner && registryOwner !== currentSession) {
-      throw new Error(
-        `Branch '${branchName}' already exists and is owned by another session (${registryOwner}).\n` +
-        `Another agent may be using this branch. Choose a different worktree name.`
-      );
-    }
-    // Branch exists but no owner conflict — warn and reuse
-    console.warn(`Warning: Branch '${branchName}' already exists, reusing it.`);
-  } catch (e) {
-    if (e.message.includes('already exists and is owned')) throw e;
-    // Branch doesn't exist — this is the normal path
-  }
-
-  // Create the worktree directory
-  fs.ensureDirSync(path.dirname(worktreePath));
-
-  if (canonicalSpecPath && resolvedSpecId) {
-    // CAWSFIX-23: flip draft→active BEFORE the bind commit so the spec
-    // lifecycle transition lands in the same commit as the worktree field.
-    // CAWSFIX-27: this block now handles BOTH the explicit --spec-id path
-    // and the auto-bind (findSpecByWorktreeName) path — previously only
-    // the explicit path committed the flip.
-    autoActivateBoundSpec(root, resolvedSpecId);
-    ensureCanonicalSpecCommitted(root, canonicalSpecPath, resolvedSpecId, name);
-  }
-
-  // Create git worktree with new branch
-  try {
-    execFileSync('git', ['worktree', 'add', '-b', branchName, worktreePath, base], {
-      cwd: root,
-      stdio: 'pipe',
-    });
-  } catch (error) {
-    // Branch already exists (caught above and allowed) — attach to it
-    if (error.message.includes('already exists')) {
-      execFileSync('git', ['worktree', 'add', worktreePath, branchName], {
-        cwd: root,
-        stdio: 'pipe',
-      });
-    } else {
-      throw new Error(`Failed to create worktree: ${error.message}`);
-    }
-  }
-
-  // Set up sparse checkout if scope is provided
-  if (scope) {
-    try {
-      // Parse scope patterns (comma-separated)
-      const patterns = scope.split(',').map((p) => p.trim());
-
-      // Detect glob characters — cone mode only accepts directory paths,
-      // not glob patterns like "core/reasoning/**" or "*.py".
-      const hasGlobs = patterns.some((p) => /[*?[\]]/.test(p));
-      const coneFlag = hasGlobs ? '--no-cone' : '--cone';
-
-      execFileSync('git', ['sparse-checkout', 'init', coneFlag], {
-        cwd: worktreePath,
-        stdio: 'pipe',
-      });
-
-      execFileSync('git', ['sparse-checkout', 'set', ...patterns], {
-        cwd: worktreePath,
-        stdio: 'pipe',
-      });
-    } catch (error) {
-      console.warn(chalk.yellow(`Sparse checkout setup failed: ${error.message}`));
-      console.warn(chalk.blue('Worktree created but without sparse checkout'));
-    }
-  }
-
-  // Copy .caws/ config into worktree
-  const cawsSource = path.join(root, '.caws');
-  const cawsDest = path.join(worktreePath, '.caws');
-  if (fs.existsSync(cawsSource)) {
-    try {
-      fs.copySync(cawsSource, cawsDest, {
-        filter: (src) => {
-          // Don't copy worktrees directory or registry into the worktree
-          const rel = path.relative(cawsSource, src);
-          return !rel.startsWith('worktrees') && rel !== 'worktrees.json';
-        },
-      });
-    } catch {
-      // Non-fatal
-    }
-  }
-
-  // CAWSFIX-27: resolvedSpecId is now computed before the worktree is
-  // added (see block above the `fs.ensureDirSync` call). The activation
-  // and bind-commit already ran on the base branch, so the worktree forks
-  // from a base that already includes the flip commit.
-
-  // Materialize a worktree-local working spec. Prefer the canonical feature
-  // spec when it exists so isolated worktrees stay aligned with the main
-  // registry/resolver model.
-  if (resolvedSpecId) {
-    try {
-      materializeWorktreeSpec(root, cawsDest, resolvedSpecId, name, scope);
-    } catch (error) {
-      console.warn(
-        chalk.yellow(`Could not materialize spec '${resolvedSpecId}' for worktree '${name}': ${error.message}`)
-      );
-      // Non-fatal: spec generation is optional
-    }
-  }
-
-  // Register worktree
-  const entry = {
-    name,
-    path: worktreePath,
-    branch: branchName,
-    baseBranch: base,
-    scope: scope || null,
-    specId: resolvedSpecId,
-    owner: options.owner || getAgentSessionId(root) || null,
-    createdAt: new Date().toISOString(),
-    status: 'fresh',
-  };
-
-  registry.worktrees[name] = entry;
-  saveRegistry(root, registry);
-
-  // CAWSFIX-32: heartbeat the current session into agents.json so the
-  // worktree+spec context is visible to other agents and to
-  // `caws status` / `caws agents list` immediately after create.
-  refreshAgentClaim(root, { worktree: name, specId: resolvedSpecId || null });
-
-  return entry;
-}
-
-/**
- * Reconcile registry state against git worktree list and filesystem.
- *
- * Non-destructive read that classifies every known worktree entry
- * (from registry + git discovery) into one of:
- *   active       — directory exists AND in git worktree list
- *   orphaned     — directory exists but NOT in git worktree list
- *   missing      — directory gone, branch may or may not exist
- *   destroyed    — explicitly destroyed via CAWS
- *   unregistered — in git worktree list but not in registry
- *   stale-merged — missing + branch already merged to base
- *
- * Does NOT mutate the registry. Callers decide what to persist.
- *
- * @param {string} root - Repository root
- * @returns {{ entries: Array, gitWorktrees: string[] }}
- */
-function reconcileRegistry(root) {
-  const registry = loadRegistry(root);
-
-  let gitWorktrees = [];
-  try {
-    const output = execFileSync('git', ['worktree', 'list', '--porcelain'], {
-      cwd: root,
-      encoding: 'utf8',
-      stdio: 'pipe',
-    });
-    gitWorktrees = output
-      .split('\n\n')
-      .filter(Boolean)
-      .map((block) => {
-        const lines = block.split('\n');
-        const worktreeLine = lines.find((l) => l.startsWith('worktree '));
-        return worktreeLine ? worktreeLine.replace('worktree ', '') : null;
-      })
-      .filter(Boolean);
-  } catch {
-    // Git worktree list failed
-  }
-
-  const entries = Object.values(registry.worktrees).map((entry) => {
-    const exists = fs.existsSync(entry.path);
-    const inGit = gitWorktrees.some(
-      (wt) => path.resolve(wt) === path.resolve(entry.path)
-    );
-
-    const merged = entry.branch && entry.baseBranch
-      ? isBranchMerged(entry.branch, entry.baseBranch, root)
-      : false;
-    const divergent = entry.branch && entry.baseBranch
-      ? hasDivergentCommits(entry.branch, entry.baseBranch, root)
-      : false;
-    const dirty = exists ? hasDirtyFiles(entry.path) : false;
-
-    let status;
-    if (entry.status === 'destroyed') {
-      status = 'destroyed';
-    } else if (exists && inGit) {
-      // Worktree directory exists and is tracked by git
-      if (divergent || dirty) {
-        // Has commits beyond base or uncommitted work → active
-        status = 'active';
-      } else if (merged) {
-        // No divergent commits, branch aligned with base.
-        // Use stored status as history to distinguish fresh vs merged:
-        //   - stored 'fresh' → never had divergent commits → still fresh
-        //   - stored 'active' → had work that's now merged → merged
-        if (entry.status === 'active') {
-          status = 'merged';
-        } else {
-          status = 'fresh';
-        }
-      } else {
-        status = 'fresh';
-      }
-    } else if (exists) {
-      status = 'orphaned';
-    } else {
-      status = merged ? 'stale-merged' : 'missing';
-    }
-
-    const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
-
-    return { ...entry, status, lastCommit, merged, divergent, dirty };
-  });
-
-  // Append unregistered worktrees discovered from git
-  const unregistered = discoverUnregisteredWorktrees(root, registry);
-  for (const discovered of unregistered) {
-    const lastCommit = getLastCommitInfo(discovered.branch, root);
-    entries.push({
-      name: discovered.name,
-      path: discovered.path,
-      branch: discovered.branch,
-      baseBranch: null,
-      scope: null,
-      specId: null,
-      owner: null,
-      createdAt: null,
-      status: 'unregistered',
-      lastCommit,
-      merged: false,
-    });
-  }
-
-  return { entries, gitWorktrees };
-}
-
-/**
- * Repair registry drift caused by manual git operations outside CAWS.
- *
- * Scans registry vs git vs filesystem, classifies each entry, and optionally
- * prunes stale entries. Reports the delta before persisting.
- *
- * @param {Object} options
- * @param {boolean} [options.prune=false] - Remove destroyed, stale-merged, and missing entries
- * @param {boolean} [options.dryRun=false] - Report only, do not persist
- * @param {boolean} [options.force=false] - Allow pruning entries owned by other sessions
- * @returns {{ repaired: Array, pruned: Array, skipped: Array }}
- */
-function repairWorktrees(options = {}) {
-  const { prune: shouldPrune = false, dryRun = false, force = false } = options;
-  const root = getRepoRoot();
-  const registry = loadRegistry(root);
-  const { entries } = reconcileRegistry(root);
-  const currentSession = getAgentSessionId(root);
-
-  const repaired = [];
-  const pruned = [];
-  const skipped = [];
-
-  for (const entry of entries) {
-    const regEntry = registry.worktrees[entry.name];
-
-    if (entry.status === 'unregistered') {
-      if (!dryRun) {
-        autoRegisterWorktree(root, registry, entry);
-      }
-      repaired.push({ name: entry.name, action: 'registered', status: entry.status });
-      continue;
-    }
-
-    if (!regEntry) continue;
-
-    // Update registry status to match filesystem reality
-    const wasAlive = regEntry.status === 'active' || regEntry.status === 'fresh';
-    const nowDead = entry.status === 'missing' || entry.status === 'stale-merged';
-    if (wasAlive && nowDead) {
-      repaired.push({
-        name: entry.name,
-        action: 'status-updated',
-        from: regEntry.status,
-        to: entry.status,
-        owner: entry.owner || null,
-      });
-    }
-
-    // Determine if entry is prunable (destroyed, stale-merged, or missing)
-    const isPrunable = entry.status === 'destroyed' ||
-      entry.status === 'stale-merged' ||
-      entry.status === 'missing';
-
-    if (!isPrunable) continue;
-
-    // Ownership check: refuse to prune another session's entries without --force
-    const isOwnedByOther = entry.owner && currentSession && entry.owner !== currentSession;
-
-    if (shouldPrune && isPrunable) {
-      if (isOwnedByOther && !force) {
-        skipped.push({
-          name: entry.name,
-          reason: `owned by another session (${entry.owner}). Use --force to override`,
-          owner: entry.owner,
-        });
-      } else {
-        if (!dryRun) {
-          delete registry.worktrees[entry.name];
-        }
-        pruned.push({ name: entry.name, status: entry.status, owner: entry.owner || null });
-      }
-    } else if (!shouldPrune && isPrunable) {
-      skipped.push({
-        name: entry.name,
-        reason: entry.status + ' (use --prune to remove)',
-        owner: entry.owner || null,
-      });
-    }
-  }
-
-  if (!dryRun) {
-    saveRegistry(root, registry);
-    try {
-      execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
-    } catch {
-      // Non-fatal
-    }
-  }
-
-  return { repaired, pruned, skipped };
-}
-
-/**
- * List all registered worktrees with filesystem validation.
- * Delegates to reconcileRegistry() for state classification.
- * Persists status transitions (fresh → active, active → merged) so
- * future calls can distinguish "never had work" from "work was merged back".
- * @returns {Array} Worktree entries with status
- */
-function listWorktrees() {
-  const root = getRepoRoot();
-  const registry = loadRegistry(root);
-  const { entries } = reconcileRegistry(root);
-
-  // Persist status transitions so future reconcile can use stored status as history
-  let dirty = false;
-  for (const entry of entries) {
-    const regEntry = registry.worktrees[entry.name];
-    if (regEntry && regEntry.status !== entry.status &&
-        entry.status !== 'unregistered') {
-      regEntry.status = entry.status;
-      dirty = true;
-    }
-  }
-  if (dirty) {
-    saveRegistry(root, registry);
-  }
-
-  return entries;
-}
-
-/**
- * Destroy a worktree
- * @param {string} name - Worktree name
- * @param {Object} options - Destruction options
- * @param {boolean} [options.deleteBranch] - Also delete the branch
- * @param {boolean} [options.force] - Force removal even if dirty
- */
-function destroyWorktree(name, options = {}) {
-  const root = getRepoRoot();
-  // Ensure CWD is not inside the worktree we're about to destroy.
-  // If CWD is the worktree directory, removing it crashes subsequent commands.
-  try { process.chdir(root); } catch { /* non-fatal */ }
-  const registry = loadRegistry(root);
-  const { deleteBranch = false, force = false } = options;
-
-  let entry = registry.worktrees[name];
-  if (!entry) {
-    // Fallback: scan git for unregistered worktree and auto-register
-    const unregistered = discoverUnregisteredWorktrees(root, registry);
-    const discovered = unregistered.find((u) => u.name === name);
-    if (discovered) {
-      console.log(chalk.yellow(`Worktree '${name}' not in registry but found in git. Auto-registering.`));
-      entry = autoRegisterWorktree(root, registry, discovered);
-    } else {
-      throw new Error(`Worktree '${name}' not found in registry or git worktree list`);
-    }
-  }
-
-  // Ownership check: refuse to destroy another agent's worktree without --force
-  const currentSession = getAgentSessionId(root);
-  const isLiveStatus = entry.status === 'active' || entry.status === 'fresh' || entry.status === 'merged';
-  if (
-    !force &&
-    isLiveStatus &&
-    entry.owner &&
-    currentSession &&
-    entry.owner !== currentSession
-  ) {
-    const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
-    const recency = lastCommit ? ` (last commit: ${lastCommit.age})` : '';
-    throw new Error(
-      `Worktree '${name}' belongs to another session${recency}.\n` +
-        `   Owner: ${entry.owner}\n` +
-        `   You:   ${currentSession}\n` +
-        `Another agent may be actively working here.\n` +
-        `Do NOT destroy worktrees you did not create. Ask the user if cleanup is needed.`
-    );
-  }
-
-  // Even with --force, warn loudly when destroying another session's worktree
-  if (
-    force &&
-    isLiveStatus &&
-    entry.owner &&
-    currentSession &&
-    entry.owner !== currentSession
-  ) {
-    const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
-    const recency = lastCommit ? ` (last commit: ${lastCommit.age})` : '';
-    console.log(chalk.red(`\n   ⚠ WARNING: Force-destroying worktree '${name}' owned by another session${recency}`));
-    console.log(chalk.red(`   Owner: ${entry.owner}`));
-    console.log(chalk.red(`   You:   ${currentSession}`));
-    console.log(chalk.red(`   If the other agent is still running, this WILL break their work.\n`));
-  }
-
-  // Auto-force when the branch is already merged to its base branch.
-  // Dirty files in a merged worktree are definitionally stale.
-  const merged = entry.branch && entry.baseBranch
-    ? isBranchMerged(entry.branch, entry.baseBranch, root)
-    : false;
-  const effectiveForce = force || merged;
-  if (merged && !force) {
-    console.log(chalk.gray(`   Branch ${entry.branch} already merged to ${entry.baseBranch}, auto-forcing cleanup`));
-  }
-
-  // Remove git worktree — handle already-deleted directories gracefully
-  const dirExists = fs.existsSync(entry.path);
-  if (dirExists) {
-    try {
-      const args = ['worktree', 'remove'];
-      if (effectiveForce) args.push('--force');
-      args.push(entry.path);
-      execFileSync('git', args, { cwd: root, stdio: 'pipe' });
-    } catch (error) {
-      if (effectiveForce) {
-        // Force cleanup: remove directory manually
-        fs.removeSync(entry.path);
-      } else {
-        throw new Error(`Failed to remove worktree: ${error.message}. Use --force to override.`);
-      }
-    }
-  } else {
-    // Directory already gone — just clean up git's tracking
-    console.log(`   Worktree directory already removed, cleaning up registry`);
-  }
-
-  // Always prune git's worktree list to stay in sync
-  try {
-    execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
-  } catch {
-    // Non-fatal
-  }
-
-  // Optionally delete branch
-  if (deleteBranch && entry.branch) {
-    try {
-      execFileSync('git', ['branch', '-d', entry.branch], { cwd: root, stdio: 'pipe' });
-    } catch {
-      if (effectiveForce) {
-        try {
-          execFileSync('git', ['branch', '-D', entry.branch], { cwd: root, stdio: 'pipe' });
-        } catch {
-          // Non-fatal
-        }
-      }
-    }
-  }
-
-  // Update registry
-  const wasAlreadyDestroyed = registry.worktrees[name].status === 'destroyed';
-  registry.worktrees[name].status = 'destroyed';
-  registry.worktrees[name].destroyedAt = new Date().toISOString();
-  saveRegistry(root, registry);
-
-  // CAWSFIX-18: auto-commit the registry so the working tree stays clean
-  if (!wasAlreadyDestroyed) {
-    try {
-      const status = execFileSync('git', ['status', '--porcelain', '.caws/worktrees.json'], {
-        cwd: root, stdio: ['pipe', 'pipe', 'pipe'],
-      }).toString().trim();
-      if (status) {
-        const otherActive = Object.values(registry.worktrees || {}).some(
-          (e) => e.status === 'active' || e.status === 'fresh'
-        );
-        const prefix = otherActive ? 'wip(checkpoint)' : 'chore(worktree)';
-        execFileSync('git', ['add', '.caws/worktrees.json'], { cwd: root, stdio: 'pipe' });
-        execFileSync('git', ['commit', '-m', `${prefix}: record destroyed ${name}`], {
-          cwd: root, stdio: 'pipe',
-        });
-      }
-    } catch (err) {
-      console.warn(chalk.yellow(`   Warning: could not auto-commit .caws/worktrees.json: ${err.message}`));
-    }
-  }
-}
-
-/**
- * Merge a worktree branch back to base in one operation.
- * Sequence: dry-run conflict check → destroy worktree → merge → cleanup.
- * @param {string} name - Worktree name
- * @param {Object} options - Merge options
- * @param {boolean} [options.dryRun] - Preview conflicts without merging
- * @param {boolean} [options.deleteBranch] - Delete branch after merge
- * @param {string} [options.message] - Custom merge commit message
- * @returns {Object} Merge result
- */
-function mergeWorktree(name, options = {}) {
-  const root = getRepoRoot();
-  const registry = loadRegistry(root);
-  const { dryRun = false, deleteBranch = true, message, takeover = false } = options;
-
-  let entry = registry.worktrees[name];
-  if (!entry) {
-    // Fallback: scan git for unregistered worktree and auto-register
-    const unregistered = discoverUnregisteredWorktrees(root, registry);
-    const discovered = unregistered.find((u) => u.name === name);
-    if (discovered) {
-      console.log(chalk.yellow(`Worktree '${name}' not in registry but found in git. Auto-registering.`));
-      entry = autoRegisterWorktree(root, registry, discovered);
-    } else {
-      throw new Error(`Worktree '${name}' not found in registry or git worktree list`);
-    }
-  }
-
-  // CAWSFIX-32: assert ownership BEFORE any merge/git work. Foreign
-  // claim soft-blocks unless --takeover is supplied, matching the
-  // bind/claim semantics. Throws on refusal so the CLI command handler
-  // surfaces the structured warning.
-  const ownership = assertWorktreeOwnership(root, name, {
-    allowTakeover: takeover,
-    takeoverCommandHint: `caws worktree merge ${name} --takeover`,
-  });
-  if (!ownership.allowed) {
-    const err = new Error(ownership.warning);
-    err.claimWarning = true;
-    throw err;
-  }
-
-  // CAWSFIX-32: heartbeat the current session into agents.json now that
-  // ownership is confirmed. Same-session merges need this since the
-  // takeover branch only fires inside assertWorktreeOwnership when a
-  // takeover actually occurs.
-  refreshAgentClaim(root, { worktree: name, specId: entry.specId || null });
-
-  const baseBranch = entry.baseBranch || 'main';
-
-  // Check for uncommitted work in the worktree.
-  // Ignore .caws/ changes (provenance chain, registry) — these are
-  // infrastructure artifacts written by git hooks, not user work.
-  // The post-commit hook appends to .caws/provenance/chain.json after
-  // every commit, which immediately dirties the tree and blocks merges.
-  if (fs.existsSync(entry.path)) {
-    try {
-      const rawStatus = execFileSync(
-        'git',
-        ['status', '--porcelain'],
-        { cwd: entry.path, encoding: 'utf8', stdio: 'pipe' }
-      );
-      // Filter out .caws/ infrastructure changes (provenance, registry).
-      // Git porcelain format: "XY PATH" — 2 status chars, space, path.
-      // IMPORTANT: do NOT .trim() the raw output — it strips the leading
-      // space from " M file" (unstaged), corrupting the XY prefix and
-      // breaking substring(3) path extraction.
-      const statusLines = rawStatus.split('\n').filter(l => l.length > 0);
-      const userChanges = statusLines
-        .filter(line => {
-          const filePath = line.substring(3);
-          return !filePath.startsWith('.caws/');
-        }).join('\n');
-      if (userChanges) {
-        throw new Error(
-          `Worktree '${name}' has uncommitted changes:\n${userChanges}\n` +
-            `Commit or discard changes before merging.`
-        );
-      }
-    } catch (error) {
-      if (error.message.includes('uncommitted changes')) throw error;
-      // Non-fatal: status check failed, proceed cautiously
-    }
-  }
-
-  // Dry-run: check for conflicts using git merge-tree (new-style, git 2.38+)
-  let conflicts = [];
-  try {
-    // New-style merge-tree: takes two branches, computes merge-base automatically
-    execFileSync(
-      'git',
-      ['merge-tree', '--write-tree', baseBranch, entry.branch],
-      { cwd: root, encoding: 'utf8', stdio: 'pipe' }
-    );
-    // Exit 0 = clean merge, no conflicts
-  } catch (mergeTreeError) {
-    // Exit 1 = conflicts detected; parse them from output
-    const output = (mergeTreeError.stdout || '') + (mergeTreeError.stderr || '');
-    const conflictLines = output.split('\n').filter(
-      (l) => l.includes('CONFLICT') || l.includes('conflict')
-    );
-    if (mergeTreeError.status === 1 && conflictLines.length > 0) {
-      conflicts = conflictLines;
-    } else if (mergeTreeError.status === 1) {
-      conflicts = ['Merge conflicts detected (run merge manually to inspect)'];
-    }
-    // Other exit codes (e.g., merge-tree not supported) = can't detect, proceed
-  }
-
-  if (dryRun) {
-    return {
-      name,
-      branch: entry.branch,
-      baseBranch,
-      conflicts,
-      wouldMerge: conflicts.length === 0,
-    };
-  }
-
-  // Emit merge:pre event
-  try {
-    lifecycle.emit(EVENTS.MERGE_PRE, {
-      worktreeName: name, branch: entry.branch, baseBranch, conflicts,
-      timestamp: new Date().toISOString(),
-    });
-  } catch { /* non-fatal */ }
-
-  // Ensure CWD is the repo root BEFORE destroying the worktree.
-  // If the caller's CWD is inside the worktree directory, destroying it
-  // removes the CWD out from under the process, causing all subsequent
-  // git commands to fail with "Unable to read current working directory".
-  try { process.chdir(root); } catch { /* non-fatal */ }
-
-  // Destroy the worktree (auto-forces since we're about to merge)
-  destroyWorktree(name, { deleteBranch: false, force: true });
-
-  // Switch to base branch (use cwd: root since getCurrentBranch has no cwd param)
-  const currentBranch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
-    cwd: root, encoding: 'utf8', stdio: 'pipe',
-  }).trim();
-  if (currentBranch !== baseBranch) {
-    execFileSync('git', ['checkout', baseBranch], { cwd: root, stdio: 'pipe' });
-  }
-
-  // Merge
-  // Use --no-verify to skip pre-commit/commit-msg hooks during merge.
-  // The worktree commits were already validated by those hooks when originally
-  // committed. Re-running them here adds seconds of blocking time (especially
-  // in projects with heavy hooks like quality gates, YAML validation, etc.)
-  // and can trigger OAuth token expiry races in long-running sessions.
-  const mergeMessage = message || `merge(worktree): ${name}`;
-  try {
-    execFileSync(
-      'git',
-      ['merge', '--no-ff', '--no-verify', entry.branch, '-m', mergeMessage],
-      { cwd: root, stdio: 'pipe' }
-    );
-  } catch (error) {
-    const failResult = {
-      name, branch: entry.branch, baseBranch, merged: false,
-      conflicts: [`Merge failed: ${error.message}`],
-      message: 'Merge conflicts detected. Resolve with git and commit.',
-    };
-    try {
-      lifecycle.emit(EVENTS.MERGE_POST, { ...failResult, timestamp: new Date().toISOString() });
-    } catch { /* non-fatal */ }
-    return failResult;
-  }
-
-  // Delete branch after successful merge
-  if (deleteBranch) {
-    try {
-      execFileSync('git', ['branch', '-d', entry.branch], { cwd: root, stdio: 'pipe' });
-    } catch {
-      // Non-fatal
-    }
-  }
-
-  // Auto-close the bound spec if one exists. A worktree merge is the
-  // lifecycle signal that the spec's work is done; leaving the spec
-  // `active` (or `draft`, pre-CAWSFIX-23) after merge accumulates stale
-  // entries (D6). Direct YAML status flip bypasses the ownership +
-  // worktree-reference checks in `closeSpec` — the caller has already
-  // proven authority by merging.
-  let autoClose = {
-    specId: null, acsPassing: null, acsFailureCount: 0, acsTotal: 0, acsFailureIds: [],
-    didWrite: false, specPath: null,
-  };
-  if (entry.specId) {
-    autoClose = autoCloseBoundSpec(root, entry.specId);
-    if (autoClose.acsPassing === false && autoClose.acsFailureCount > 0) {
-      console.warn(chalk.yellow(
-        `   ⚠ Spec ${entry.specId} closed with ${autoClose.acsFailureCount}/${autoClose.acsTotal} failing AC(s): ${autoClose.acsFailureIds.join(', ')}`
-      ));
-      console.warn(chalk.yellow(
-        `     Merge succeeded — the spec reflects that — but follow up to address the failing ACs.`
-      ));
-    }
-
-    // CAWSFIX-24 / D6: if the auto-close flipped the status, commit the
-    // change on the base branch before returning. Leaving it uncommitted
-    // was the "dirty main" footgun: the next worktree merge would abort
-    // on "local changes would be overwritten," after the prior worktree
-    // was already destroyed. Use --no-verify to match the merge commit's
-    // hook-skip discipline (the content was verified when the merge ran).
-    if (autoClose.didWrite && autoClose.specPath) {
-      try {
-        const relPath = path.relative(root, autoClose.specPath);
-        execFileSync('git', ['add', '--', relPath], { cwd: root, stdio: 'pipe' });
-        execFileSync(
-          'git',
-          ['commit', '--no-verify', '-m', `chore(caws): close ${autoClose.specId} spec post-merge`, '--', relPath],
-          { cwd: root, stdio: 'pipe' }
-        );
-      } catch (commitErr) {
-        // Non-fatal: a failed auto-commit leaves the spec dirty but the
-        // merge itself already succeeded. Warn so the caller can clean up.
-        console.warn(chalk.yellow(
-          `   ⚠ Auto-commit of ${autoClose.specId} close flip failed: ${commitErr.message}. Commit manually.`
-        ));
-      }
-    }
-  }
-
-  const mergeResult = {
-    name, branch: entry.branch, baseBranch, merged: true, conflicts: [],
-    specId: entry.specId || null,
-    autoClosedSpecId: autoClose.specId,
-    acsPassing: autoClose.acsPassing,
-    acsFailureCount: autoClose.acsFailureCount,
-    acsTotal: autoClose.acsTotal,
-    acsFailureIds: autoClose.acsFailureIds,
-  };
-  try {
-    lifecycle.emit(EVENTS.MERGE_POST, { ...mergeResult, timestamp: new Date().toISOString() });
-  } catch { /* non-fatal */ }
-  return mergeResult;
-}
-
-/**
- * Flip a spec's status from `draft` to `active` by rewriting just the
- * `status:` line. Called on worktree-bind so specs whose work is
- * starting transition out of draft without manual intervention.
- * Idempotent: no-op when the spec is already active/closed/etc.
- * @param {string} root - Repo root
- * @param {string} specId - Spec identifier
- * @returns {string|null} specId on flip, null if no change
- */
-function autoActivateBoundSpec(root, specId, specPathOverride = null) {
-  try {
-    // CAWSFIX-25 / D8: callers that resolved a worktree-local spec path
-    // (via findFeatureSpecPathFromCwd) pass it in so the flip lands on
-    // the worktree's copy, not main's. Falls through to main resolution
-    // for backward compatibility when override is null.
-    const specPath = specPathOverride || findFeatureSpecPath(root, specId);
-    if (!specPath || !fs.existsSync(specPath)) return null;
-    const original = fs.readFileSync(specPath, 'utf8');
-    // Idempotent: already active/closed/archived → no write.
-    if (/^status:[ \t]*active[ \t]*$/m.test(original)) return specId;
-    const patched = original.replace(/^status:[ \t]*draft[ \t]*$/m, 'status: active');
-    if (patched === original) return null;
-    fs.writeFileSync(specPath, patched, 'utf8');
-    return specId;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Flip a spec's status to `closed` by rewriting just the `status:` line.
- * Accepts both `draft` and `active` as source states — merge is the
- * authoritative "work done" signal regardless of whether the spec ever
- * transitioned through active. Runs verify-acs in collect-only mode
- * before the flip and returns AC health so the caller can warn.
- * @param {string} root - Repo root
- * @param {string} specId - Spec identifier (e.g. CAWSFIX-14)
- * @returns {{specId: string|null, acsPassing: boolean|null, acsFailureCount: number, acsTotal: number, acsFailureIds: string[]}}
- */
-function autoCloseBoundSpec(root, specId) {
-  const result = {
-    specId: null,
-    acsPassing: null,
-    acsFailureCount: 0,
-    acsTotal: 0,
-    acsFailureIds: [],
-    didWrite: false,
-    specPath: null,
-  };
-  try {
-    const specPath = findFeatureSpecPath(root, specId);
-    if (!specPath || !fs.existsSync(specPath)) return result;
-    result.specPath = specPath;
-    const original = fs.readFileSync(specPath, 'utf8');
-    // Idempotent: already closed → no-op, no write, no diff.
-    if (/^status:[ \t]*closed[ \t]*$/m.test(original)) {
-      result.specId = specId;
-      return result;
-    }
-    // Run verify-acs in collect-only mode before flipping. Never throws —
-    // any error (missing tests, unavailable runner, malformed spec) leaves
-    // acsPassing: null so the caller knows verification didn't run.
-    try {
-      const yaml = require('js-yaml');
-      const { verifySpec } = require('../commands/verify-acs');
-      const parsed = yaml.load(original);
-      if (parsed && typeof parsed === 'object') {
-        const verdict = verifySpec(parsed, root, { run: false });
-        const fails = (verdict.results || []).filter((r) => r.status === 'FAIL');
-        result.acsTotal = (verdict.results || []).length;
-        result.acsFailureCount = fails.length;
-        result.acsFailureIds = fails.map((r) => r.id);
-        result.acsPassing = fails.length === 0;
-      }
-    } catch {
-      // verify-acs unavailable — don't block close
-    }
-    // Flip status. Accept both draft and active as source so specs that
-    // never transitioned through active (D6 pre-CAWSFIX-23 drift) still close.
-    const patched = original.replace(/^status:[ \t]*(?:draft|active)[ \t]*$/m, 'status: closed');
-    if (patched === original) {
-      return result; // status was archived/unknown — leave alone
-    }
-    fs.writeFileSync(specPath, patched, 'utf8');
-    result.specId = specId;
-    result.didWrite = true;
-    return result;
-  } catch {
-    return result;
-  }
-}
-
-/**
- * Prune stale worktree entries
- * @param {Object} options - Prune options
- * @param {number} [options.maxAgeDays] - Remove entries older than this many days
- * @param {number} [options.recentCommitMinutes] - Protect branches with commits newer than this (default: 60)
- * @param {boolean} [options.force] - Allow pruning entries owned by other sessions
- * @returns {{ pruned: Array, skipped: Array }} Pruned and skipped entries
- */
-function pruneWorktrees(options = {}) {
-  const root = getRepoRoot();
-  const registry = loadRegistry(root);
-  const { maxAgeDays = 30, recentCommitMinutes = 60, force = false } = options;
-  const currentSession = getAgentSessionId(root);
-
-  const now = new Date();
-  const pruned = [];
-  const skipped = [];
-
-  for (const [name, entry] of Object.entries(registry.worktrees)) {
-    const created = new Date(entry.createdAt);
-    const ageDays = (now - created) / (1000 * 60 * 60 * 24);
-    const dirExists = fs.existsSync(entry.path);
-
-    const shouldPrune =
-      // Always prune destroyed entries
-      entry.status === 'destroyed' ||
-      // Prune active/fresh entries whose directory is gone (filesystem-registry desync)
-      ((entry.status === 'active' || entry.status === 'fresh') && !dirExists) ||
-      // Prune old missing entries
-      (!dirExists && ageDays > maxAgeDays);
-
-    if (shouldPrune) {
-      // Ownership check: skip entries owned by other sessions unless --force
-      const isOwnedByOther = entry.owner && currentSession && entry.owner !== currentSession;
-      if (isOwnedByOther && entry.status !== 'destroyed' && !force) {
-        skipped.push({
-          name,
-          reason: `owned by another session (${entry.owner})`,
-          entry,
-        });
-        continue;
-      }
-
-      // Before pruning a non-destroyed entry, check for recent commits (skip if --force)
-      if (!force && entry.status !== 'destroyed' && entry.branch) {
-        const lastCommit = getLastCommitInfo(entry.branch, root);
-        if (lastCommit) {
-          const commitAgeMinutes = (now - lastCommit.timestamp) / (1000 * 60);
-          if (commitAgeMinutes < recentCommitMinutes) {
-            skipped.push({ name, reason: `recent commit (${lastCommit.age})`, entry });
-            continue;
-          }
-        }
-      }
-
-      // Clean up filesystem if still exists
-      if (dirExists) {
-        try {
-          execFileSync('git', ['worktree', 'remove', '--force', entry.path], {
-            cwd: root,
-            stdio: 'pipe',
-          });
-        } catch {
-          fs.removeSync(entry.path);
-        }
-      }
-      pruned.push(entry);
-      delete registry.worktrees[name];
-    }
-  }
-
-  // Prune git's worktree list
-  try {
-    execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
-  } catch {
-    // Non-fatal
-  }
-
-  saveRegistry(root, registry);
-  return { pruned, skipped };
-}
-
-module.exports = {
-  createWorktree,
-  listWorktrees,
-  destroyWorktree,
-  mergeWorktree,
-  autoActivateBoundSpec,
-  autoCloseBoundSpec,
-  pruneWorktrees,
-  repairWorktrees,
-  reconcileRegistry,
-  loadRegistry,
-  saveRegistry,
-  assertWorktreeOwnership,
-  getRepoRoot,
-  getLastCommitInfo,
-  isBranchMerged,
-  hasDivergentCommits,
-  hasDirtyFiles,
-  discoverUnregisteredWorktrees,
-  autoRegisterWorktree,
-  WORKTREES_DIR,
-  REGISTRY_FILE,
-  BRANCH_PREFIX,
-  findFeatureSpecPath,
-  findFeatureSpecPathFromCwd,
-  materializeWorktreeSpec,
-  inferSpecIdForWorktree,
-  findSpecByWorktreeName,
-};