@paths.design/caws-cli 9.3.0 → 9.3.2

package/dist/commands/verify-acs.js

@@ -39,7 +39,7 @@ function detectTestRunner(projectRoot) {
       if (fs.existsSync(fp)) {
         try {
           if (fs.readFileSync(fp, 'utf8').includes(needle)) return check.runner;
-        } catch (_) {}
+        } catch (_) { /* ignore unreadable config */ }
       }
     }
   }
@@ -123,7 +123,7 @@ function runNodeid(nodeid, runner, projectRoot) {
   try {
     switch (runner) {
       case 'pytest': {
-        const out = execFileSync('python3', ['-m', 'pytest', '-x', '--tb=short', nodeid], {
+        execFileSync('python3', ['-m', 'pytest', '-x', '--tb=short', nodeid], {
           cwd: projectRoot, encoding: 'utf8', timeout: 120000, stdio: ['pipe', 'pipe', 'pipe'],
         });
         return { passed: true, detail: 'tests passed' };
@@ -215,7 +215,7 @@ function checkEvidence(evidence, projectRoot) {
         if (files) {
           return { found: true, detail: `found: ${files.split('\n')[0]}` };
         }
-      } catch (_) {}
+      } catch (_) { /* ignore unreadable config */ }
     }
   }
 
@@ -350,7 +350,7 @@ function loadSpecs(projectRoot, targetSpecId) {
       if (s && !TERMINAL_STATUSES.has(s.status)) {
         specs.push({ path: workingSpec, spec: s });
       }
-    } catch (_) {}
+    } catch (_) { /* ignore unreadable config */ }
   }
 
   if (fs.existsSync(specsDir)) {
@@ -360,7 +360,7 @@ function loadSpecs(projectRoot, targetSpecId) {
         if (s && !TERMINAL_STATUSES.has(s.status)) {
           specs.push({ path: path.join(specsDir, f), spec: s });
         }
-      } catch (_) {}
+      } catch (_) { /* ignore unreadable config */ }
     }
   }
 

package/dist/commands/worktree.js

@@ -11,6 +11,7 @@ const {
   destroyWorktree,
   mergeWorktree,
   pruneWorktrees,
+  repairWorktrees,
 } = require('../worktree/worktree-manager');
 
 /**
@@ -31,9 +32,11 @@ async function worktreeCommand(subcommand, options = {}) {
         return handleMerge(options);
       case 'prune':
         return handlePrune(options);
+      case 'repair':
+        return handleRepair(options);
       default:
         console.error(chalk.red(`Unknown worktree subcommand: ${subcommand}`));
-        console.log(chalk.blue('Available: create, list, destroy, merge, prune'));
+        console.log(chalk.blue('Available: create, list, destroy, merge, prune, repair'));
         process.exit(1);
     }
   } catch (error) {
@@ -72,18 +75,20 @@ function handleList() {
     return;
   }
 
+  const maxNameLen = Math.max(18, ...entries.map((e) => e.name.length + 2));
+  const totalWidth = maxNameLen + 12 + 20 + 16 + 10;
   console.log(chalk.bold.cyan('CAWS Worktrees'));
-  console.log(chalk.cyan('='.repeat(85)));
+  console.log(chalk.cyan('='.repeat(totalWidth)));
   console.log(
     chalk.bold(
-      'Name'.padEnd(18) +
+      'Name'.padEnd(maxNameLen) +
         'Status'.padEnd(12) +
         'Branch'.padEnd(20) +
         'Last Commit'.padEnd(16) +
         'Owner'
     )
   );
-  console.log(chalk.gray('-'.repeat(85)));
+  console.log(chalk.gray('-'.repeat(totalWidth)));
 
   for (const entry of entries) {
     const statusColor =
@@ -114,7 +119,7 @@ function handleList() {
     }
 
     console.log(
-      entry.name.padEnd(18) +
+      entry.name.padEnd(maxNameLen) +
         statusColor(statusStr.padEnd(12)) +
         (entry.branch || '').padEnd(20) +
         commitAge.padEnd(16 + 10) + // +10 for chalk color codes
@@ -225,4 +230,52 @@ function handlePrune(options) {
   }
 }
 
+
+function handleRepair(options) {
+  const dryRun = options.dryRun || false;
+  const shouldPrune = options.prune || false;
+
+  if (dryRun) {
+    console.log(chalk.cyan('Repair dry-run (no changes will be persisted)'));
+  } else {
+    console.log(chalk.cyan('Repairing worktree registry'));
+  }
+
+  const result = repairWorktrees({ prune: shouldPrune, dryRun });
+
+  if (result.repaired.length === 0 && result.pruned.length === 0 && result.skipped.length === 0) {
+    console.log(chalk.green('Registry is consistent. Nothing to repair.'));
+    return;
+  }
+
+  if (result.repaired.length > 0) {
+    console.log(chalk.green('\nRepaired ' + result.repaired.length + ' entry/entries:'));
+    for (const r of result.repaired) {
+      if (r.action === 'registered') {
+        console.log(chalk.gray('   + ' + r.name + ' (auto-registered from git)'));
+      } else {
+        console.log(chalk.gray('   ~ ' + r.name + ' (' + r.from + ' -> ' + r.to + ')'));
+      }
+    }
+  }
+
+  if (result.pruned.length > 0) {
+    console.log(chalk.green('\nPruned ' + result.pruned.length + ' stale entry/entries:'));
+    for (const p of result.pruned) {
+      console.log(chalk.gray('   - ' + p.name + ' (' + p.status + ')'));
+    }
+  }
+
+  if (result.skipped.length > 0) {
+    console.log(chalk.yellow('\nSkipped ' + result.skipped.length + ' entry/entries:'));
+    for (const s of result.skipped) {
+      console.log(chalk.yellow('   ? ' + s.name + ': ' + s.reason));
+    }
+  }
+
+  if (dryRun) {
+    console.log(chalk.blue('\nDry-run complete. Run without --dry-run to persist changes.'));
+  }
+}
+
 module.exports = { worktreeCommand };

package/dist/index.js

@@ -395,6 +395,13 @@ worktreeCmd
   .option('--max-age <days>', 'Remove entries older than N days', '30')
   .action((options) => worktreeCommand('prune', options));
 
+worktreeCmd
+  .command('repair')
+  .description('Reconcile registry with git and filesystem state')
+  .option('--dry-run', 'Report only, do not persist changes', false)
+  .option('--prune', 'Remove destroyed and stale-merged entries', false)
+  .action((options) => worktreeCommand('repair', options));
+
 // Session command group
 const sessionCmd = program
   .command('session')

package/dist/templates/.claude/hooks/worktree-guard.sh

@@ -11,6 +11,7 @@ INPUT=$(cat)
 # Extract tool info
 TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+HOOK_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
 
 # Only check Bash tool
 if [[ "$TOOL_NAME" != "Bash" ]] || [[ -z "$COMMAND" ]]; then
@@ -46,26 +47,38 @@ if echo "$COMMAND" | grep -qE 'caws\s+(worktree\s+create|parallel\s+setup).*--sc
 fi
 
 # --- Gap 5: Block cross-boundary file copies ---
+# Only block copies FROM a worktree back to the main repo (defeats isolation).
+# Copies INTO a worktree are fine — the agent is working there and the files
+# live on the worktree branch, disappearing on merge.
 WORKTREE_BASE="$PROJECT_DIR/.caws/worktrees"
 if [[ -d "$WORKTREE_BASE" ]]; then
   if echo "$COMMAND" | grep -qE '\b(cp|mv)\b'; then
-    if echo "$COMMAND" | grep -qF ".caws/worktrees/" || echo "$COMMAND" | grep -qF "$WORKTREE_BASE"; then
-      # Check if the command references both a worktree path and the main repo
-      HAS_WT_PATH=false
-      HAS_MAIN_PATH=false
-      if echo "$COMMAND" | grep -qE '\.caws/worktrees/|'"$(echo "$WORKTREE_BASE" | sed 's/[\/&]/\\&/g')"''; then
-        HAS_WT_PATH=true
-      fi
-      # Check if destination/source is outside the worktree
-      if echo "$COMMAND" | grep -qE "(^|\s)$PROJECT_DIR/[^.]|core/|src/|tests/|packages/" && [[ "$HAS_WT_PATH" == "true" ]]; then
-        HAS_MAIN_PATH=true
-      fi
-      if [[ "$HAS_WT_PATH" == "true" ]] && [[ "$HAS_MAIN_PATH" == "true" ]]; then
-        echo "BLOCKED: Copying files between a worktree and the main repo is forbidden." >&2
-        echo "This bypasses worktree isolation. Work entirely within your worktree." >&2
-        echo "If tests need the main repo's venv, activate it with:" >&2
-        echo "  source $PROJECT_DIR/.venv/bin/activate" >&2
-        exit 2
+    # If the agent is working inside a worktree, allow all copies — they're
+    # in their own workspace
+    AGENT_IN_WORKTREE=false
+    if [[ -n "$HOOK_CWD" ]] && [[ "$HOOK_CWD" == "$WORKTREE_BASE"/* ]]; then
+      AGENT_IN_WORKTREE=true
+    fi
+
+    if [[ "$AGENT_IN_WORKTREE" != "true" ]]; then
+      if echo "$COMMAND" | grep -qF ".caws/worktrees/" || echo "$COMMAND" | grep -qF "$WORKTREE_BASE"; then
+        # Check if the command references both a worktree path and the main repo
+        HAS_WT_PATH=false
+        HAS_MAIN_PATH=false
+        if echo "$COMMAND" | grep -qE '\.caws/worktrees/|'"$(echo "$WORKTREE_BASE" | sed 's/[\/&]/\\&/g')"''; then
+          HAS_WT_PATH=true
+        fi
+        # Check if destination/source is outside the worktree
+        if echo "$COMMAND" | grep -qE "(^|\s)$PROJECT_DIR/[^.]|core/|src/|tests/|packages/" && [[ "$HAS_WT_PATH" == "true" ]]; then
+          HAS_MAIN_PATH=true
+        fi
+        if [[ "$HAS_WT_PATH" == "true" ]] && [[ "$HAS_MAIN_PATH" == "true" ]]; then
+          echo "BLOCKED: Copying files from a worktree to the main repo is forbidden." >&2
+          echo "This bypasses worktree isolation. Work entirely within your worktree." >&2
+          echo "If tests need the main repo's venv, activate it with:" >&2
+          echo "  source $PROJECT_DIR/.venv/bin/activate" >&2
+          exit 2
+        fi
       fi
     fi
   fi
@@ -151,10 +164,10 @@ if echo "$COMMAND" | grep -qE 'git\s+push\s+.*(--force|-f\s)'; then
 fi
 
 # --- Base branch protections ---
-# Use the agent's actual working directory (CLAUDE_PROJECT_DIR), not the resolved
-# main repo root (PROJECT_DIR). In a worktree, PROJECT_DIR points to the main repo
-# (to find .caws/worktrees.json), but the agent's branch is in CLAUDE_PROJECT_DIR.
-AGENT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+# Use the hook input's cwd (where the git command will actually execute), not
+# CLAUDE_PROJECT_DIR (which always points to the main repo root, even when the
+# agent has cd'd into a worktree at .caws/worktrees/<name>/).
+AGENT_DIR="${HOOK_CWD:-${CLAUDE_PROJECT_DIR:-.}}"
 CURRENT_BRANCH=$(cd "$AGENT_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
 
 # Determine the base branch to protect

package/dist/templates/.claude/hooks/worktree-write-guard.sh

@@ -13,6 +13,7 @@ INPUT=$(cat)
 # Extract tool info
 TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+HOOK_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
 
 # Only check Write and Edit tools
 case "$TOOL_NAME" in
@@ -42,10 +43,10 @@ if ! command -v node >/dev/null 2>&1; then
   exit 0
 fi
 
-# Use the agent's actual working directory, not the resolved main repo root.
-# In a worktree, PROJECT_DIR points to the main repo (to find .caws/worktrees.json),
-# but the agent's branch is in CLAUDE_PROJECT_DIR.
-AGENT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+# Use the hook input's cwd (where the agent is actually working), not
+# CLAUDE_PROJECT_DIR (which always points to the main repo root, even when the
+# agent has cd'd into a worktree at .caws/worktrees/<name>/).
+AGENT_DIR="${HOOK_CWD:-${CLAUDE_PROJECT_DIR:-.}}"
 CURRENT_BRANCH=$(cd "$AGENT_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
 
 WT_INFO=$(node -e "

package/dist/utils/detection.js

@@ -203,17 +203,8 @@ function detectCAWSSetup(cwd = process.cwd()) {
  * @returns {string} Project root directory path
  */
 function findProjectRoot(startDir = process.cwd()) {
-  // Walk up looking for .caws/ directory
-  let dir = path.resolve(startDir);
-  const root = path.parse(dir).root;
-  while (dir !== root) {
-    if (fs.existsSync(path.join(dir, '.caws'))) {
-      return dir;
-    }
-    dir = path.dirname(dir);
-  }
-
-  // Fallback: try git root
+  // In a monorepo, nested packages may have their own .caws/ (scaffold debris).
+  // The git root's .caws/ is authoritative — check it first.
   try {
     const { execFileSync } = require('child_process');
     const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
@@ -225,7 +216,17 @@ function findProjectRoot(startDir = process.cwd()) {
       return gitRoot;
     }
   } catch {
-    // Not a git repo or git not available
+    // Not a git repo or git not available — fall through
+  }
+
+  // Walk up looking for .caws/ directory (non-git projects)
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, '.caws'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
   }
 
   // Final fallback: cwd

package/dist/worktree/worktree-manager.js

@@ -54,13 +54,25 @@ function isBranchMerged(branch, target, root) {
 }
 
 /**
- * Get the git repository root
- * @returns {string} Absolute path to repo root
+ * 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);
 }
 
 /**
@@ -101,6 +113,106 @@ function saveRegistry(root, registry) {
   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: null,
+    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
@@ -258,19 +370,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')
@@ -290,24 +414,121 @@ 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;
+    let status;
+    if (entry.status === 'destroyed') {
+      status = 'destroyed';
+    } else if (exists && inGit) {
+      status = 'active';
+    } else if (exists) {
+      status = 'orphaned';
+    } else {
+      const merged = entry.branch && entry.baseBranch
+        ? isBranchMerged(entry.branch, entry.baseBranch, root)
+        : false;
+      status = merged ? 'stale-merged' : 'missing';
+    }
 
-    // Check if branch is already merged to base
+    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 };
   });
 
+  // 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 and stale-merged entries
+ * @param {boolean} [options.dryRun=false] - Report only, do not persist
+ * @returns {{ repaired: Array, pruned: Array, skipped: Array }}
+ */
+function repairWorktrees(options = {}) {
+  const { prune: shouldPrune = false, dryRun = false } = options;
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+  const { entries } = reconcileRegistry(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
+    if (regEntry.status === 'active' && (entry.status === 'missing' || entry.status === 'stale-merged')) {
+      repaired.push({ name: entry.name, action: 'status-updated', from: 'active', to: entry.status });
+    }
+
+    // Prune if requested and entry is dead
+    if (shouldPrune && (entry.status === 'destroyed' || entry.status === 'stale-merged')) {
+      if (!dryRun) {
+        delete registry.worktrees[entry.name];
+      }
+      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)' });
+    }
+  }
+
+  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.
+ * @returns {Array} Worktree entries with status
+ */
+function listWorktrees() {
+  const root = getRepoRoot();
+  const { entries } = reconcileRegistry(root);
   return entries;
 }
 
@@ -323,9 +544,17 @@ function destroyWorktree(name, options = {}) {
   const registry = loadRegistry(root);
   const { deleteBranch = false, force = false } = options;
 
-  const entry = registry.worktrees[name];
+  let entry = registry.worktrees[name];
   if (!entry) {
-    throw new Error(`Worktree '${name}' not found in registry`);
+    // 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 active worktree without --force
@@ -438,9 +667,17 @@ function mergeWorktree(name, options = {}) {
   const registry = loadRegistry(root);
   const { dryRun = false, deleteBranch = true, message } = options;
 
-  const entry = registry.worktrees[name];
+  let entry = registry.worktrees[name];
   if (!entry) {
-    throw new Error(`Worktree '${name}' not found in registry`);
+    // 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`);
+    }
   }
 
   const baseBranch = entry.baseBranch || 'main';
@@ -469,7 +706,7 @@ function mergeWorktree(name, options = {}) {
   let conflicts = [];
   try {
     // New-style merge-tree: takes two branches, computes merge-base automatically
-    const mergeTreeResult = execFileSync(
+    execFileSync(
       'git',
       ['merge-tree', '--write-tree', baseBranch, entry.branch],
       { cwd: root, encoding: 'utf8', stdio: 'pipe' }
@@ -620,10 +857,14 @@ module.exports = {
   destroyWorktree,
   mergeWorktree,
   pruneWorktrees,
+  repairWorktrees,
+  reconcileRegistry,
   loadRegistry,
   getRepoRoot,
   getLastCommitInfo,
   isBranchMerged,
+  discoverUnregisteredWorktrees,
+  autoRegisterWorktree,
   WORKTREES_DIR,
   REGISTRY_FILE,
   BRANCH_PREFIX,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "9.3.0",
+  "version": "9.3.2",
   "description": "CAWS CLI - Coding Agent Workflow System command-line tools for spec management, quality gates, and AI-assisted development",
   "main": "dist/index.js",
   "bin": {

package/templates/.claude/hooks/worktree-guard.sh

@@ -11,6 +11,7 @@ INPUT=$(cat)
 # Extract tool info
 TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+HOOK_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
 
 # Only check Bash tool
 if [[ "$TOOL_NAME" != "Bash" ]] || [[ -z "$COMMAND" ]]; then
@@ -46,26 +47,38 @@ if echo "$COMMAND" | grep -qE 'caws\s+(worktree\s+create|parallel\s+setup).*--sc
 fi
 
 # --- Gap 5: Block cross-boundary file copies ---
+# Only block copies FROM a worktree back to the main repo (defeats isolation).
+# Copies INTO a worktree are fine — the agent is working there and the files
+# live on the worktree branch, disappearing on merge.
 WORKTREE_BASE="$PROJECT_DIR/.caws/worktrees"
 if [[ -d "$WORKTREE_BASE" ]]; then
   if echo "$COMMAND" | grep -qE '\b(cp|mv)\b'; then
-    if echo "$COMMAND" | grep -qF ".caws/worktrees/" || echo "$COMMAND" | grep -qF "$WORKTREE_BASE"; then
-      # Check if the command references both a worktree path and the main repo
-      HAS_WT_PATH=false
-      HAS_MAIN_PATH=false
-      if echo "$COMMAND" | grep -qE '\.caws/worktrees/|'"$(echo "$WORKTREE_BASE" | sed 's/[\/&]/\\&/g')"''; then
-        HAS_WT_PATH=true
-      fi
-      # Check if destination/source is outside the worktree
-      if echo "$COMMAND" | grep -qE "(^|\s)$PROJECT_DIR/[^.]|core/|src/|tests/|packages/" && [[ "$HAS_WT_PATH" == "true" ]]; then
-        HAS_MAIN_PATH=true
-      fi
-      if [[ "$HAS_WT_PATH" == "true" ]] && [[ "$HAS_MAIN_PATH" == "true" ]]; then
-        echo "BLOCKED: Copying files between a worktree and the main repo is forbidden." >&2
-        echo "This bypasses worktree isolation. Work entirely within your worktree." >&2
-        echo "If tests need the main repo's venv, activate it with:" >&2
-        echo "  source $PROJECT_DIR/.venv/bin/activate" >&2
-        exit 2
+    # If the agent is working inside a worktree, allow all copies — they're
+    # in their own workspace
+    AGENT_IN_WORKTREE=false
+    if [[ -n "$HOOK_CWD" ]] && [[ "$HOOK_CWD" == "$WORKTREE_BASE"/* ]]; then
+      AGENT_IN_WORKTREE=true
+    fi
+
+    if [[ "$AGENT_IN_WORKTREE" != "true" ]]; then
+      if echo "$COMMAND" | grep -qF ".caws/worktrees/" || echo "$COMMAND" | grep -qF "$WORKTREE_BASE"; then
+        # Check if the command references both a worktree path and the main repo
+        HAS_WT_PATH=false
+        HAS_MAIN_PATH=false
+        if echo "$COMMAND" | grep -qE '\.caws/worktrees/|'"$(echo "$WORKTREE_BASE" | sed 's/[\/&]/\\&/g')"''; then
+          HAS_WT_PATH=true
+        fi
+        # Check if destination/source is outside the worktree
+        if echo "$COMMAND" | grep -qE "(^|\s)$PROJECT_DIR/[^.]|core/|src/|tests/|packages/" && [[ "$HAS_WT_PATH" == "true" ]]; then
+          HAS_MAIN_PATH=true
+        fi
+        if [[ "$HAS_WT_PATH" == "true" ]] && [[ "$HAS_MAIN_PATH" == "true" ]]; then
+          echo "BLOCKED: Copying files from a worktree to the main repo is forbidden." >&2
+          echo "This bypasses worktree isolation. Work entirely within your worktree." >&2
+          echo "If tests need the main repo's venv, activate it with:" >&2
+          echo "  source $PROJECT_DIR/.venv/bin/activate" >&2
+          exit 2
+        fi
       fi
     fi
   fi
@@ -151,10 +164,10 @@ if echo "$COMMAND" | grep -qE 'git\s+push\s+.*(--force|-f\s)'; then
 fi
 
 # --- Base branch protections ---
-# Use the agent's actual working directory (CLAUDE_PROJECT_DIR), not the resolved
-# main repo root (PROJECT_DIR). In a worktree, PROJECT_DIR points to the main repo
-# (to find .caws/worktrees.json), but the agent's branch is in CLAUDE_PROJECT_DIR.
-AGENT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+# Use the hook input's cwd (where the git command will actually execute), not
+# CLAUDE_PROJECT_DIR (which always points to the main repo root, even when the
+# agent has cd'd into a worktree at .caws/worktrees/<name>/).
+AGENT_DIR="${HOOK_CWD:-${CLAUDE_PROJECT_DIR:-.}}"
 CURRENT_BRANCH=$(cd "$AGENT_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
 
 # Determine the base branch to protect

package/templates/.claude/hooks/worktree-write-guard.sh

@@ -13,6 +13,7 @@ INPUT=$(cat)
 # Extract tool info
 TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+HOOK_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
 
 # Only check Write and Edit tools
 case "$TOOL_NAME" in
@@ -42,10 +43,10 @@ if ! command -v node >/dev/null 2>&1; then
   exit 0
 fi
 
-# Use the agent's actual working directory, not the resolved main repo root.
-# In a worktree, PROJECT_DIR points to the main repo (to find .caws/worktrees.json),
-# but the agent's branch is in CLAUDE_PROJECT_DIR.
-AGENT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+# Use the hook input's cwd (where the agent is actually working), not
+# CLAUDE_PROJECT_DIR (which always points to the main repo root, even when the
+# agent has cd'd into a worktree at .caws/worktrees/<name>/).
+AGENT_DIR="${HOOK_CWD:-${CLAUDE_PROJECT_DIR:-.}}"
 CURRENT_BRANCH=$(cd "$AGENT_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
 
 WT_INFO=$(node -e "