@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/worktree/worktree-manager.js

@@ -8,11 +8,215 @@ 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 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;
+  }
+
+  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 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 = writeSpecWithWorktree(canonicalSpecPath, worktreeName);
+    fs.writeFileSync(destSpecPath, specContent);
+    fs.writeFileSync(workingSpecPath, specContent);
+    return;
+  }
+
+  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(path.dirname(workingSpecPath));
+  fs.writeFileSync(workingSpecPath, 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
@@ -53,6 +257,44 @@ function isBranchMerged(branch, target, 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).
  *
@@ -85,6 +327,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
@@ -94,7 +341,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
@@ -108,6 +369,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));
@@ -201,7 +483,7 @@ function autoRegisterWorktree(root, registry, discovered) {
     branch: discovered.branch,
     baseBranch,
     scope: null,
-    specId: null,
+    specId: inferSpecIdForWorktree(discovered.path),
     owner: null,
     createdAt: new Date().toISOString(),
     status: 'active',
@@ -233,18 +515,72 @@ 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();
+  const canonicalSpecPath = findFeatureSpecPath(root, specId);
+
+  // 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) {
+    ensureCanonicalSpecCommitted(root, canonicalSpecPath, specId, name);
+  }
+
   // Create git worktree with new branch
   try {
     execFileSync('git', ['worktree', 'add', '-b', branchName, worktreePath, base], {
@@ -252,7 +588,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,
@@ -306,46 +642,27 @@ function createWorktree(name, options = {}) {
     }
   }
 
-  // Generate working spec if in standard+ mode and specId provided
-  if (specId) {
+  // Auto-bind specId: if no explicit --spec-id was passed, scan .caws/specs/
+  // for a spec that declares `worktree: <name>`. This establishes the mutual
+  // reference that the scope guard uses to treat one spec as authoritative.
+  let resolvedSpecId = specId || null;
+  if (!resolvedSpecId) {
+    resolvedSpecId = findSpecByWorktreeName(root, name);
+    if (resolvedSpecId) {
+      console.log(chalk.gray(`   Auto-bound spec: ${resolvedSpecId}`));
+    }
+  }
+
+  // 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 {
-      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, 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
     }
   }
@@ -357,10 +674,10 @@ function createWorktree(name, options = {}) {
     branch: branchName,
     baseBranch: base,
     scope: scope || null,
-    specId: specId || null,
-    owner: options.owner || process.env.CLAUDE_SESSION_ID || null,
+    specId: resolvedSpecId,
+    owner: options.owner || getAgentSessionId(root) || null,
     createdAt: new Date().toISOString(),
-    status: 'active',
+    status: 'fresh',
   };
 
   registry.worktrees[name] = entry;
@@ -415,26 +732,44 @@ function reconcileRegistry(root) {
       (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) {
-      status = 'active';
+      // 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 {
-      const merged = entry.branch && entry.baseBranch
-        ? isBranchMerged(entry.branch, entry.baseBranch, root)
-        : false;
       status = merged ? 'stale-merged' : 'missing';
     }
 
     const lastCommit = entry.branch ? getLastCommitInfo(entry.branch, root) : null;
-    const merged = entry.branch && entry.baseBranch
-      ? isBranchMerged(entry.branch, entry.baseBranch, root)
-      : false;
 
-    return { ...entry, status, lastCommit, merged };
+    return { ...entry, status, lastCommit, merged, divergent, dirty };
   });
 
   // Append unregistered worktrees discovered from git
@@ -466,15 +801,17 @@ function reconcileRegistry(root) {
  * prunes stale entries. Reports the delta before persisting.
  *
  * @param {Object} options
- * @param {boolean} [options.prune=false] - Remove destroyed and stale-merged entries
+ * @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 } = 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 = [];
@@ -494,18 +831,47 @@ function repairWorktrees(options = {}) {
     if (!regEntry) continue;
 
     // Update registry status to match filesystem reality
-    if (regEntry.status === 'active' && (entry.status === 'missing' || entry.status === 'stale-merged')) {
-      repaired.push({ name: entry.name, action: 'status-updated', from: 'active', to: entry.status });
+    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,
+      });
     }
 
-    // Prune if requested and entry is dead
-    if (shouldPrune && (entry.status === 'destroyed' || entry.status === 'stale-merged')) {
-      if (!dryRun) {
-        delete registry.worktrees[entry.name];
+    // 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 });
       }
-      pruned.push({ name: entry.name, status: entry.status });
-    } else if (!shouldPrune && (entry.status === 'destroyed' || entry.status === 'stale-merged')) {
-      skipped.push({ name: entry.name, reason: entry.status + ' (use --prune to remove)' });
+    } else if (!shouldPrune && isPrunable) {
+      skipped.push({
+        name: entry.name,
+        reason: entry.status + ' (use --prune to remove)',
+        owner: entry.owner || null,
+      });
     }
   }
 
@@ -524,11 +890,29 @@ function repairWorktrees(options = {}) {
 /**
  * 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;
 }
 
@@ -541,6 +925,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;
 
@@ -557,11 +944,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
@@ -580,7 +968,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
@@ -647,9 +1035,31 @@ function destroyWorktree(name, options = {}) {
   }
 
   // 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}`));
+    }
+  }
 }
 
 /**
@@ -682,17 +1092,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.`
         );
       }
@@ -736,32 +1161,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
@@ -773,13 +1220,48 @@ function mergeWorktree(name, options = {}) {
     }
   }
 
-  return {
-    name,
-    branch: entry.branch,
-    baseBranch,
-    merged: true,
-    conflicts: [],
+  // 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` after merge accumulates stale-active entries (D6). Direct
+  // YAML status flip bypasses the ownership + worktree-reference checks
+  // in `closeSpec` — the caller has already proven authority by merging.
+  let autoClosedSpecId = null;
+  if (entry.specId) {
+    autoClosedSpecId = autoCloseBoundSpec(root, entry.specId);
+  }
+
+  const mergeResult = {
+    name, branch: entry.branch, baseBranch, merged: true, conflicts: [],
+    specId: entry.specId || null, autoClosedSpecId,
   };
+  try {
+    lifecycle.emit(EVENTS.MERGE_POST, { ...mergeResult, timestamp: new Date().toISOString() });
+  } catch { /* non-fatal */ }
+  return mergeResult;
+}
+
+/**
+ * Flip a spec's status to `closed` by rewriting just the `status:` line.
+ * Idempotent: no-op when the spec is already closed or the file is missing.
+ * Returns the spec ID on success, null if skipped or failed.
+ * @param {string} root - Repo root
+ * @param {string} specId - Spec identifier (e.g. CAWSFIX-14)
+ * @returns {string|null}
+ */
+function autoCloseBoundSpec(root, specId) {
+  try {
+    const specPath = findFeatureSpecPath(root, specId);
+    if (!specPath || !fs.existsSync(specPath)) return null;
+    const original = fs.readFileSync(specPath, 'utf8');
+    // Idempotent: already closed → no-op, no write, no diff.
+    if (/^status:\s*closed\s*$/m.test(original)) return specId;
+    const patched = original.replace(/^status:\s*active\s*$/m, 'status: closed');
+    if (patched === original) return null; // status was e.g. draft/archived
+    fs.writeFileSync(specPath, patched, 'utf8');
+    return specId;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -787,12 +1269,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 = [];
@@ -806,14 +1290,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);
@@ -856,16 +1351,24 @@ module.exports = {
   listWorktrees,
   destroyWorktree,
   mergeWorktree,
+  autoCloseBoundSpec,
   pruneWorktrees,
   repairWorktrees,
   reconcileRegistry,
   loadRegistry,
+  saveRegistry,
   getRepoRoot,
   getLastCommitInfo,
   isBranchMerged,
+  hasDivergentCommits,
+  hasDirtyFiles,
   discoverUnregisteredWorktrees,
   autoRegisterWorktree,
   WORKTREES_DIR,
   REGISTRY_FILE,
   BRANCH_PREFIX,
+  findFeatureSpecPath,
+  materializeWorktreeSpec,
+  inferSpecIdForWorktree,
+  findSpecByWorktreeName,
 };