@paths.design/caws-cli 9.3.1 → 10.0.1

package/dist/worktree/worktree-manager.js

@@ -8,11 +8,88 @@ 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 } = require('../utils/agent-session');
+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;
+}
+
+function materializeWorktreeSpec(root, cawsDest, specId, worktreeName, scope) {
+  if (!specId) return;
+
+  const canonicalSpecPath = findFeatureSpecPath(root, specId);
+  const workingSpecPath = path.join(cawsDest, 'working-spec.yaml');
+
+  if (!canonicalSpecPath) {
+    console.warn(
+      chalk.yellow(`Warning: spec '${specId}' not found in .caws/specs/ — generating default working spec for worktree`)
+    );
+  }
+
+  if (canonicalSpecPath) {
+    const destSpecsDir = path.join(cawsDest, 'specs');
+    const destSpecPath = path.join(destSpecsDir, path.basename(canonicalSpecPath));
+    fs.ensureDirSync(destSpecsDir);
+
+    // Keep a canonical feature-spec copy inside the worktree and align
+    // working-spec.yaml to that exact content for legacy-compatible commands.
+    const specContent = fs.readFileSync(canonicalSpecPath, 'utf8');
+    fs.writeFileSync(destSpecPath, specContent);
+    fs.writeFileSync(workingSpecPath, specContent);
+    return;
+  }
+
+  const { generateWorkingSpec } = require('../generators/working-spec');
+  const 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: '',
+  });
+
+  fs.ensureDirSync(path.dirname(workingSpecPath));
+  fs.writeFileSync(workingSpecPath, specContent);
+}
+
 /**
  * Get the last commit info for a branch
  * @param {string} branch - Branch name
@@ -54,13 +131,63 @@ function isBranchMerged(branch, target, root) {
 }
 
 /**
- * Get the git repository root
- * @returns {string} Absolute path to repo root
+ * 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() {
-  return execFileSync('git', ['rev-parse', '--show-toplevel'], {
-    encoding: 'utf8',
-  }).trim();
+  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);
 }
 
 /**
@@ -73,6 +200,11 @@ function getCurrentBranch() {
   }).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;
+
 /**
  * Load the worktree registry
  * @param {string} root - Repository root
@@ -82,7 +214,21 @@ function loadRegistry(root) {
   const registryPath = path.join(root, REGISTRY_FILE);
   try {
     if (fs.existsSync(registryPath)) {
-      return JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      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
@@ -96,6 +242,27 @@ function loadRegistry(root) {
  * @param {Object} registry - Registry object
  */
 function saveRegistry(root, registry) {
+  // Auto-prune destroyed entries whose branch and directory are both gone.
+  // This prevents the registry from accumulating ghost entries over time.
+  for (const [name, entry] of Object.entries(registry.worktrees || {})) {
+    if (entry.status !== 'destroyed') continue;
+    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));
@@ -221,15 +388,64 @@ function createWorktree(name, options = {}) {
 
   const registry = loadRegistry(root);
 
-  // Check for duplicate
+  // Check for duplicate in registry
   if (registry.worktrees[name]) {
-    throw new Error(`Worktree '${name}' already exists. Use 'caws worktree destroy ${name}' first.`);
+    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();
 
+  // 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));
 
@@ -240,7 +456,7 @@ function createWorktree(name, options = {}) {
       stdio: 'pipe',
     });
   } catch (error) {
-    // Branch might already exist
+    // Branch already exists (caught above and allowed) — attach to it
     if (error.message.includes('already exists')) {
       execFileSync('git', ['worktree', 'add', worktreePath, branchName], {
         cwd: root,
@@ -294,46 +510,16 @@ function createWorktree(name, options = {}) {
     }
   }
 
-  // Generate working spec if in standard+ mode and specId provided
+  // 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 (specId) {
     try {
-      const { generateWorkingSpec } = require('../generators/working-spec');
-      const specContent = generateWorkingSpec({
-        projectId: specId,
-        projectTitle: `Worktree: ${name}`,
-        projectDescription: `Isolated worktree for ${name}`,
-        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: '',
-      });
-      const specPath = path.join(cawsDest, 'working-spec.yaml');
-      fs.ensureDirSync(path.dirname(specPath));
-      fs.writeFileSync(specPath, specContent);
-    } catch {
+      materializeWorktreeSpec(root, cawsDest, specId, name, scope);
+    } catch (error) {
+      console.warn(
+        chalk.yellow(`Could not materialize spec '${specId}' for worktree '${name}': ${error.message}`)
+      );
       // Non-fatal: spec generation is optional
     }
   }
@@ -346,9 +532,9 @@ function createWorktree(name, options = {}) {
     baseBranch: base,
     scope: scope || null,
     specId: specId || null,
-    owner: options.owner || process.env.CLAUDE_SESSION_ID || null,
+    owner: options.owner || getAgentSessionId(root) || null,
     createdAt: new Date().toISOString(),
-    status: 'active',
+    status: 'fresh',
   };
 
   registry.worktrees[name] = entry;
@@ -358,19 +544,31 @@ function createWorktree(name, options = {}) {
 }
 
 /**
- * List all registered worktrees with filesystem validation
- * @returns {Array} Worktree entries with status
+ * 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 listWorktrees() {
-  const root = getRepoRoot();
+function reconcileRegistry(root) {
   const registry = loadRegistry(root);
 
-  // Get actual git worktrees for validation
   let gitWorktrees = [];
   try {
     const output = execFileSync('git', ['worktree', 'list', '--porcelain'], {
       cwd: root,
       encoding: 'utf8',
+      stdio: 'pipe',
     });
     gitWorktrees = output
       .split('\n\n')
@@ -390,22 +588,45 @@ function listWorktrees() {
     const inGit = gitWorktrees.some(
       (wt) => path.resolve(wt) === path.resolve(entry.path)
     );
-    const status = exists && inGit ? 'active' : exists ? 'orphaned' : 'missing';
-
-    // Enrich with commit recency
-    const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
 
-    // Check if branch is already merged to base
     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';
+    }
 
-    return {
-      ...entry,
-      status,
-      lastCommit,
-      merged,
-    };
+    const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
+
+    return { ...entry, status, lastCommit, merged, divergent, dirty };
   });
 
   // Append unregistered worktrees discovered from git
@@ -427,6 +648,128 @@ function listWorktrees() {
     });
   }
 
+  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;
 }
 
@@ -439,6 +782,9 @@ function listWorktrees() {
  */
 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;
 
@@ -455,11 +801,12 @@ function destroyWorktree(name, options = {}) {
     }
   }
 
-  // Ownership check: refuse to destroy another agent's active worktree without --force
-  const currentSession = process.env.CLAUDE_SESSION_ID || null;
+  // 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 &&
-    entry.status === 'active' &&
+    isLiveStatus &&
     entry.owner &&
     currentSession &&
     entry.owner !== currentSession
@@ -478,7 +825,7 @@ function destroyWorktree(name, options = {}) {
   // Even with --force, warn loudly when destroying another session's worktree
   if (
     force &&
-    entry.status === 'active' &&
+    isLiveStatus &&
     entry.owner &&
     currentSession &&
     entry.owner !== currentSession
@@ -580,17 +927,32 @@ function mergeWorktree(name, options = {}) {
 
   const baseBranch = entry.baseBranch || 'main';
 
-  // Check for uncommitted work in the worktree
+  // 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 status = execFileSync(
+      const rawStatus = execFileSync(
         'git',
         ['status', '--porcelain'],
         { cwd: entry.path, encoding: 'utf8', stdio: 'pipe' }
-      ).trim();
-      if (status) {
+      );
+      // 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${status}\n` +
+          `Worktree '${name}' has uncommitted changes:\n${userChanges}\n` +
             `Commit or discard changes before merging.`
         );
       }
@@ -634,32 +996,54 @@ function mergeWorktree(name, options = {}) {
     };
   }
 
+  // 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
-  const currentBranch = getCurrentBranch();
+  // 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', entry.branch, '-m', mergeMessage],
+      ['merge', '--no-ff', '--no-verify', entry.branch, '-m', mergeMessage],
       { cwd: root, stdio: 'pipe' }
     );
   } catch (error) {
-    return {
-      name,
-      branch: entry.branch,
-      baseBranch,
-      merged: false,
+    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
@@ -671,13 +1055,11 @@ function mergeWorktree(name, options = {}) {
     }
   }
 
-  return {
-    name,
-    branch: entry.branch,
-    baseBranch,
-    merged: true,
-    conflicts: [],
-  };
+  const mergeResult = { name, branch: entry.branch, baseBranch, merged: true, conflicts: [] };
+  try {
+    lifecycle.emit(EVENTS.MERGE_POST, { ...mergeResult, timestamp: new Date().toISOString() });
+  } catch { /* non-fatal */ }
+  return mergeResult;
 }
 
 /**
@@ -685,12 +1067,14 @@ function mergeWorktree(name, options = {}) {
  * @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)
- * @returns {Array} Pruned entries
+ * @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 } = options;
+  const { maxAgeDays = 30, recentCommitMinutes = 60, force = false } = options;
+  const currentSession = getAgentSessionId(root);
 
   const now = new Date();
   const pruned = [];
@@ -704,14 +1088,25 @@ function pruneWorktrees(options = {}) {
     const shouldPrune =
       // Always prune destroyed entries
       entry.status === 'destroyed' ||
-      // Prune active entries whose directory is gone (filesystem-registry desync)
-      (entry.status === 'active' && !dirExists) ||
+      // 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) {
-      // Before pruning a non-destroyed entry, check for recent commits
-      if (entry.status !== 'destroyed' && entry.branch) {
+      // 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);
@@ -755,13 +1150,19 @@ module.exports = {
   destroyWorktree,
   mergeWorktree,
   pruneWorktrees,
+  repairWorktrees,
+  reconcileRegistry,
   loadRegistry,
   getRepoRoot,
   getLastCommitInfo,
   isBranchMerged,
+  hasDivergentCommits,
+  hasDirtyFiles,
   discoverUnregisteredWorktrees,
   autoRegisterWorktree,
   WORKTREES_DIR,
   REGISTRY_FILE,
   BRANCH_PREFIX,
+  findFeatureSpecPath,
+  materializeWorktreeSpec,
 };