@paths.design/caws-cli 10.1.0 → 10.2.0

package/dist/commands/agents.js

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview CAWSFIX-31 — caws agents command.
+ *
+ * Surfaces the agent registry (`.caws/agents.json`) so operators and
+ * other agents can see who is currently registered, what they are
+ * working on, and where their session logs live. Reads only — write
+ * paths are owned by the session-log hook and the lifecycle ops in
+ * specs/worktree.
+ *
+ * Subcommands:
+ *   - list                — table of all live entries (no platform filter)
+ *   - show <session-id>   — full detail for one entry, including session-log pointer
+ *
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+
+const { findProjectRoot } = require('../utils/detection');
+const {
+  loadAgentRegistry,
+  findSessionLogs,
+} = require('../utils/agent-session');
+const {
+  formatAgentRef,
+  formatHeartbeatAge,
+  formatSessionLogPointer,
+} = require('../utils/agent-display');
+
+/**
+ * Top-level dispatcher.
+ * @param {string} subcommand
+ * @param {Object} options
+ */
+function agentsCommand(subcommand, options = {}) {
+  switch (subcommand) {
+    case 'list':
+      return handleList(options);
+    case 'show':
+      return handleShow(options);
+    default:
+      console.error(chalk.red(`Unknown agents subcommand: ${subcommand}`));
+      console.log(chalk.blue('Available: list, show'));
+      process.exit(1);
+  }
+}
+
+function handleList() {
+  const root = findProjectRoot();
+  const registry = loadAgentRegistry(root);
+  const entries = Object.values(registry.agents || {});
+
+  console.log(chalk.bold.cyan('CAWS Agents'));
+  console.log(chalk.cyan('='.repeat(80)));
+
+  if (entries.length === 0) {
+    console.log(chalk.gray('No active agents.'));
+    return;
+  }
+
+  // Sort by lastSeen desc so most recent appears first.
+  entries.sort((a, b) => new Date(b.lastSeen || 0) - new Date(a.lastSeen || 0));
+
+  for (const entry of entries) {
+    const ref = formatAgentRef(entry.sessionId, entry.platform);
+    const age = formatHeartbeatAge(entry.lastSeen);
+    console.log(chalk.bold(ref));
+    console.log(chalk.gray(`   Heartbeat: ${entry.lastSeen || 'unknown'} (${age})`));
+    if (entry.specId) {
+      console.log(chalk.gray(`   Spec:      ${entry.specId}`));
+    }
+    if (entry.worktree) {
+      console.log(chalk.gray(`   Worktree:  ${entry.worktree}`));
+    }
+    if (entry.model) {
+      console.log(chalk.gray(`   Model:     ${entry.model}`));
+    }
+    console.log('');
+  }
+}
+
+function handleShow(options) {
+  const id = options.id;
+  if (!id) {
+    console.error(chalk.red('Session ID is required'));
+    console.log(chalk.blue('Usage: caws agents show <session-id>'));
+    process.exit(1);
+  }
+
+  const root = findProjectRoot();
+  const registry = loadAgentRegistry(root);
+  const entry = registry.agents[id];
+  if (!entry) {
+    console.error(chalk.red(`No agent registered with session id: ${id}`));
+    console.log(
+      chalk.blue('Run `caws agents list` to see active sessions, or `tmp/<id>/.meta.json` for archived ones.')
+    );
+    process.exit(1);
+  }
+
+  const ref = formatAgentRef(entry.sessionId, entry.platform);
+  console.log(chalk.bold.cyan(ref));
+  console.log(chalk.cyan('='.repeat(70)));
+  console.log(chalk.gray(`First seen: ${entry.firstSeen || 'unknown'}`));
+  console.log(
+    chalk.gray(`Last seen:  ${entry.lastSeen || 'unknown'} (${formatHeartbeatAge(entry.lastSeen)})`)
+  );
+  if (entry.specId) console.log(chalk.gray(`Spec:       ${entry.specId}`));
+  if (entry.worktree) console.log(chalk.gray(`Worktree:   ${entry.worktree}`));
+  if (entry.model) console.log(chalk.gray(`Model:      ${entry.model}`));
+  if (entry.ttl) console.log(chalk.gray(`TTL:        ${Math.round(entry.ttl / 1000 / 60)} min`));
+
+  // Surface any session-log pointers for this id.
+  const logs = findSessionLogs(root, { sessionId: id });
+  if (logs.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Session logs:'));
+    for (const log of logs) {
+      console.log(formatSessionLogPointer(log, root));
+    }
+  }
+}
+
+module.exports = { agentsCommand };

package/dist/commands/specs.js

@@ -16,7 +16,7 @@ const { SPEC_TYPES } = require('../constants/spec-types');
 const { suggestFeatureBreakdown } = require('../utils/spec-resolver');
 const { findProjectRoot } = require('../utils/detection');
 const { loadRegistry: loadWorktreeRegistry, getRepoRoot } = require('../worktree/worktree-manager');
-const { getAgentSessionId } = require('../utils/agent-session');
+const { getAgentSessionId, refreshAgentClaim } = require('../utils/agent-session');
 const { initializeState, saveState, deleteState } = require('../utils/working-state');
 const { appendEvent } = require('../utils/event-log');
 
@@ -224,6 +224,17 @@ function normalizeSpecForValidation(spec = {}) {
  * List all spec files in the specs directory
  * @returns {Promise<Array>} Array of spec file info
  */
+// Files under this subdir of `.caws/specs/` are treated as archived,
+// regardless of what the YAML's `status` field says (CAWSFIX-29 invariant:
+// directory location is authoritative for archive state).
+const ARCHIVE_SUBDIR = '.archive';
+
+function isArchivePath(relPath) {
+  if (!relPath) return false;
+  const normalized = relPath.replace(/\\/g, '/');
+  return normalized === ARCHIVE_SUBDIR || normalized.startsWith(`${ARCHIVE_SUBDIR}/`);
+}
+
 async function listSpecFiles() {
   const specsDir = getSpecsDir();
   if (!(await fs.pathExists(specsDir))) {
@@ -239,13 +250,14 @@ async function listSpecFiles() {
     try {
       const content = await fs.readFile(filePath, 'utf8');
       const spec = yaml.load(content);
+      const inArchive = isArchivePath(file);
 
       specs.push({
         id: spec.id || path.basename(file, path.extname(file)),
         path: file,
         type: spec.type || 'feature',
         title: spec.title || 'Untitled',
-        status: spec.status || 'draft',
+        status: inArchive ? 'archived' : spec.status || 'draft',
         risk_tier: spec.risk_tier || 'T3',
         mode: spec.mode || 'development',
         created_at: spec.created_at || new Date().toISOString(),
@@ -289,6 +301,40 @@ async function createSpec(id, options = {}) {
   const existingSpecPath = path.join(specsDir, `${id}.yaml`);
   const specExists = await fs.pathExists(existingSpecPath);
 
+  // CAWSFIX-30: archive-collision guard. An id that lives in `.archive/`
+  // is still a taken id — surface it before going further. Detection is
+  // filesystem-driven (not registry-driven) so manually-moved legacy
+  // specs are also caught.
+  const archivedSpecPath = path.join(specsDir, ARCHIVE_SUBDIR, `${id}.yaml`);
+  const archivedExists = !specExists && (await fs.pathExists(archivedSpecPath));
+  if (archivedExists && !force) {
+    console.error(
+      chalk.red(
+        `Spec '${id}' already exists in archive: ${path.relative(findProjectRoot(), archivedSpecPath)}`
+      )
+    );
+    console.error(
+      chalk.yellow(
+        `Use --force to remove the archived copy and resurrect the id, ` +
+          `or pick a different id.`
+      )
+    );
+    throw new Error(
+      `Spec '${id}' collides with archived spec at .archive/${id}.yaml. ` +
+        `Use --force to resurrect or choose another id.`
+    );
+  }
+  if (archivedExists && force) {
+    // Resurrection: drop the archived YAML and any registry pointer so
+    // the rest of createSpec can write a fresh draft cleanly.
+    await fs.remove(archivedSpecPath);
+    const registry = await loadSpecsRegistry();
+    if (registry.specs[id]) {
+      delete registry.specs[id];
+      await saveSpecsRegistry(registry);
+    }
+  }
+
   // Handle conflict resolution
   let answer = null;
 
@@ -544,10 +590,14 @@ async function createSpec(id, options = {}) {
     );
   } catch (err) {
     // Surface on stderr but don't propagate — the spec is already created.
-     
+
     console.error(`event-log: failed to record spec_created for ${id}: ${err.message}`);
   }
 
+  // CAWSFIX-31: refresh the current agent's claim so agents.json reflects
+  // the current spec context. Best-effort — failures must not break the op.
+  refreshAgentClaim(findProjectRoot(), { specId: id });
+
   return {
     id,
     path: fileName,
@@ -818,10 +868,14 @@ async function deleteSpec(id) {
       { projectRoot: findProjectRoot() }
     );
   } catch (err) {
-     
+
     console.error(`event-log: failed to record spec_deleted for ${id}: ${err.message}`);
   }
 
+  // CAWSFIX-31: every lifecycle verb refreshes for consistency, even
+  // delete (no other cleanup runs on delete; this is signal-of-presence).
+  refreshAgentClaim(findProjectRoot(), { specId: id });
+
   return true;
 }
 
@@ -911,14 +965,143 @@ async function closeSpec(id) {
         { projectRoot: findProjectRoot() }
       );
     } catch (err) {
-       
+
       console.error(`event-log: failed to record spec_closed for ${id}: ${err.message}`);
     }
+
+    // CAWSFIX-31: refresh agent claim — also fires on no-op closes
+    // (already-closed specs return ok=true after an early exit) only
+    // when the status actually flipped, since this is the signal that
+    // matters: the agent is currently working on this spec.
+    refreshAgentClaim(findProjectRoot(), { specId: id });
   }
 
   return ok;
 }
 
+/**
+ * Archive a spec: move its YAML to `.caws/specs/.archive/<id>.yaml`,
+ * flip status to `archived`, update the registry, and emit a `spec_archived`
+ * event. The archive directory is the canonical truth for archive state —
+ * the listing layer (listSpecFiles) treats any file under `.archive/` as
+ * archived regardless of the YAML literal.
+ *
+ * @param {string} id - Spec identifier
+ * @returns {Promise<boolean>} true on success (including idempotent no-ops),
+ *   false on validation/lookup failure.
+ */
+async function archiveSpec(id) {
+  // Path-traversal guard: ids must be plain filenames, not paths.
+  // Reject before touching any filesystem state.
+  if (!id || typeof id !== 'string' || path.basename(id) !== id || id.includes('..')) {
+    console.error(chalk.red(`Invalid spec id '${id}': must be a plain identifier`));
+    return false;
+  }
+
+  const registry = await loadSpecsRegistry();
+  const entry = registry.specs[id];
+  if (!entry) {
+    console.error(chalk.red(`Spec '${id}' not found`));
+    return false;
+  }
+
+  // Block if owned by another session (mirror closeSpec/deleteSpec).
+  const currentSession = getAgentSessionId(findProjectRoot());
+  if (entry.owner && currentSession && entry.owner !== currentSession) {
+    console.error(
+      chalk.red(
+        `Cannot archive spec '${id}': owned by another session (${entry.owner}). ` +
+          `Only the creator session can archive a spec.`
+      )
+    );
+    return false;
+  }
+
+  // Block if active worktrees still reference the spec — archiving removes
+  // scope enforcement and would invalidate in-flight work.
+  const referencingWorktrees = getWorktreesReferencingSpec(id);
+  if (referencingWorktrees.length > 0) {
+    const names = referencingWorktrees.join(', ');
+    console.error(
+      chalk.red(
+        `Cannot archive spec '${id}': active worktree(s) [${names}] reference it. ` +
+          `Destroy the worktree(s) first with 'caws worktree destroy <name>'.`
+      )
+    );
+    return false;
+  }
+
+  const specsDir = getSpecsDir();
+  const priorPath = entry.path;
+  const currentSpecPath = path.join(specsDir, priorPath);
+
+  // If the file is already in the archive directory, the canonical
+  // location is satisfied — just ensure the registry status agrees and exit.
+  if (isArchivePath(priorPath)) {
+    if (entry.status !== 'archived') {
+      registry.specs[id] = { ...entry, status: 'archived' };
+      await saveSpecsRegistry(registry);
+    }
+    console.log(chalk.yellow(`Spec '${id}' is already archived.`));
+    return true;
+  }
+
+  if (!(await fs.pathExists(currentSpecPath))) {
+    console.error(
+      chalk.red(`Cannot archive spec '${id}': file missing at ${currentSpecPath}`)
+    );
+    return false;
+  }
+
+  // CAWSFIX-15-style targeted rewrite: only `status:` and `updated_at:`
+  // lines move. Comments, ordering, and YAML aliases survive untouched.
+  const original = await fs.readFile(currentSpecPath, 'utf8');
+  const priorStatus = entry.status || 'draft';
+  const nowIso = new Date().toISOString();
+  let patched = original.replace(/^status:\s*\S+\s*$/m, 'status: archived');
+  patched = patched.replace(/^updated_at:.*$/m, `updated_at: '${nowIso}'`);
+
+  const archiveDir = path.join(specsDir, ARCHIVE_SUBDIR);
+  await fs.ensureDir(archiveDir);
+  const newRelPath = `${ARCHIVE_SUBDIR}/${id}.yaml`;
+  const newAbsPath = path.join(specsDir, newRelPath);
+
+  // Write the patched content to the archive location, then remove the
+  // original. fs-extra's writeFile is atomic-enough for single-file moves
+  // on the same filesystem; we avoid `move` because we already mutated content.
+  await fs.writeFile(newAbsPath, patched);
+  await fs.remove(currentSpecPath);
+
+  registry.specs[id] = {
+    ...entry,
+    path: newRelPath,
+    status: 'archived',
+    updated_at: nowIso,
+  };
+  await saveSpecsRegistry(registry);
+
+  // Best-effort event emission, matching spec_closed/spec_deleted policy:
+  // event-log failure does not roll back the archive operation.
+  try {
+    await appendEvent(
+      {
+        actor: 'cli',
+        event: 'spec_archived',
+        spec_id: id,
+        data: { id, prior_status: priorStatus, prior_path: priorPath },
+      },
+      { projectRoot: findProjectRoot() }
+    );
+  } catch (err) {
+    console.error(`event-log: failed to record spec_archived for ${id}: ${err.message}`);
+  }
+
+  // CAWSFIX-31: refresh agent claim after a successful archive transition.
+  refreshAgentClaim(findProjectRoot(), { specId: id });
+
+  return true;
+}
+
 /**
  * Display specs in a formatted table
  * @param {Array} specs - Array of spec objects
@@ -1402,6 +1585,28 @@ async function specsCommand(action, options = {}) {
           });
         }
 
+        case 'archive': {
+          if (!options.id) {
+            throw new Error('Spec ID is required. Usage: caws specs archive <id>');
+          }
+
+          const archived = await archiveSpec(options.id);
+          if (!archived) {
+            throw new Error(`Could not archive spec '${options.id}'`);
+          }
+
+          console.log(
+            chalk.green(
+              `Archived spec: ${options.id} -- moved to .caws/specs/.archive/`
+            )
+          );
+
+          return outputResult({
+            command: 'specs archive',
+            spec: options.id,
+          });
+        }
+
         case 'types': {
           console.log(chalk.bold.cyan('\nAvailable Spec Types'));
           console.log(chalk.cyan('==============================================\n'));
@@ -1420,7 +1625,7 @@ async function specsCommand(action, options = {}) {
 
         default:
           throw new Error(
-            `Unknown specs action: ${action}. Use: list, create, show, update, delete, close, conflicts, migrate, types`
+            `Unknown specs action: ${action}. Use: list, create, show, update, delete, close, archive, conflicts, migrate, types`
           );
       }
     },
@@ -1439,10 +1644,13 @@ module.exports = {
   updateSpec,
   deleteSpec,
   closeSpec,
+  archiveSpec,
   displaySpecsTable,
   displaySpecDetails,
   askConflictResolution,
+  isArchivePath,
   SPECS_DIR,
   SPECS_REGISTRY,
+  ARCHIVE_SUBDIR,
   SPEC_TYPES,
 };

package/dist/commands/status.js

@@ -363,6 +363,27 @@ function displayStatus(data) {
   console.log(chalk.bold.cyan('\nCAWS Project Status'));
   console.log(chalk.cyan('==============================================\n'));
 
+  // CAWSFIX-31: Surface worktree claim if cwd is inside a worktree.
+  // Best-effort — failures (no .caws, no registry, etc.) are silent.
+  try {
+    const path = require('path');
+    const { findProjectRoot } = require('../utils/detection');
+    const { renderClaimPanel } = require('../utils/agent-display');
+    const root = findProjectRoot();
+    const cwd = process.cwd();
+    const worktreesBase = path.join(root, '.caws', 'worktrees');
+    if (cwd.startsWith(worktreesBase + path.sep)) {
+      const worktreeName = path.relative(worktreesBase, cwd).split(path.sep)[0];
+      const panel = renderClaimPanel(root, worktreeName);
+      if (panel) {
+        console.log(chalk.green(panel));
+        console.log('');
+      }
+    }
+  } catch {
+    // best-effort
+  }
+
   // Working Spec Status
   if (spec) {
     console.log(chalk.green('Working Spec'));

package/dist/commands/worktree.js

@@ -14,10 +14,12 @@ const {
   repairWorktrees,
   loadRegistry,
   saveRegistry,
+  assertWorktreeOwnership,
   getRepoRoot,
-  findFeatureSpecPath,
+  findFeatureSpecPathFromCwd,
+  autoActivateBoundSpec,
 } = require('../worktree/worktree-manager');
-const { getAgentSessionId } = require('../utils/agent-session');
+const { getAgentSessionId, refreshAgentClaim } = require('../utils/agent-session');
 
 /**
  * Handle worktree subcommands
@@ -41,9 +43,11 @@ async function worktreeCommand(subcommand, options = {}) {
         return handleRepair(options);
       case 'bind':
         return handleBind(options);
+      case 'claim':
+        return handleClaim(options);
       default:
         console.error(chalk.red(`Unknown worktree subcommand: ${subcommand}`));
-        console.log(chalk.blue('Available: create, list, destroy, merge, prune, repair, bind'));
+        console.log(chalk.blue('Available: create, list, destroy, merge, prune, repair, bind, claim'));
         process.exit(1);
     }
   } catch (error) {
@@ -175,7 +179,7 @@ function handleDestroy(options) {
 }
 
 function handleMerge(options) {
-  const { name, dryRun, deleteBranch = true, message } = options;
+  const { name, dryRun, deleteBranch = true, message, takeover = false } = options;
 
   if (!name) {
     console.error(chalk.red('Worktree name is required'));
@@ -193,7 +197,7 @@ function handleMerge(options) {
     console.log(chalk.cyan(`Merging worktree: ${name}`));
   }
 
-  const result = mergeWorktree(name, { dryRun, deleteBranch, message });
+  const result = mergeWorktree(name, { dryRun, deleteBranch, message, takeover });
 
   if (dryRun) {
     if (result.conflicts.length > 0) {
@@ -313,11 +317,11 @@ function handleBind(options) {
   const path = require('path');
   const fs = require('fs-extra');
   const yaml = require('js-yaml');
-  const { specId, name } = options;
+  const { specId, name, takeover } = options;
 
   if (!specId) {
     console.error(chalk.red('Spec ID is required'));
-    console.log(chalk.blue('Usage: caws worktree bind <spec-id> [--name <worktree-name>]'));
+    console.log(chalk.blue('Usage: caws worktree bind <spec-id> [--name <worktree-name>] [--takeover]'));
     process.exit(1);
   }
 
@@ -341,19 +345,41 @@ function handleBind(options) {
   }
 
   const root = getRepoRoot();
-  const registry = loadRegistry(root);
-
-  // Find the worktree entry in the registry
-  if (!registry.worktrees || !registry.worktrees[worktreeName]) {
+  // CAWSFIX-32: probe the registry for existence first, but do NOT load
+  // the full registry into a variable yet — assertWorktreeOwnership may
+  // mutate it on takeover, and we'd overwrite the takeover write later
+  // with our stale in-memory copy. Re-load after the ownership check.
+  const probe = loadRegistry(root);
+  if (!probe.worktrees || !probe.worktrees[worktreeName]) {
     console.error(chalk.red(`Worktree '${worktreeName}' not found in registry.`));
     console.log(chalk.blue('Run: caws worktree list  to see available worktrees'));
     process.exit(1);
+    return;
   }
 
-  // Load the spec file
-  const specPath = findFeatureSpecPath(root, specId);
+  // CAWSFIX-32: assert ownership BEFORE any registry/spec mutation.
+  // Foreign claim soft-blocks unless --takeover is supplied, mirroring
+  // `caws worktree claim`.
+  const ownership = assertWorktreeOwnership(root, worktreeName, {
+    allowTakeover: !!takeover,
+    takeoverCommandHint: `caws worktree bind ${specId} --name ${worktreeName} --takeover`,
+  });
+  if (!ownership.allowed) {
+    console.error(chalk.yellow(ownership.warning));
+    process.exit(1);
+    return;
+  }
+
+  // Now load the registry fresh — assertWorktreeOwnership may have
+  // rewritten owner + appended prior_owners on takeover.
+  const registry = loadRegistry(root);
+
+  // Load the spec file. CAWSFIX-25 / D8: when bind runs from inside a
+  // worktree, prefer the worktree's own .caws/specs/ copy so specs that
+  // live only on a feature branch (never mirrored to main) can be bound.
+  const specPath = findFeatureSpecPathFromCwd(root, specId, process.cwd());
   if (!specPath) {
-    console.error(chalk.red(`Spec '${specId}' not found in .caws/specs/`));
+    console.error(chalk.red(`Spec '${specId}' not found in .caws/specs/ (checked worktree-local first, then main)`));
     console.log(chalk.blue('Run: caws specs list  to see available specs'));
     process.exit(1);
   }
@@ -371,16 +397,106 @@ function handleBind(options) {
   registry.worktrees[worktreeName].specId = specId;
   saveRegistry(root, registry);
 
-  // Update spec side: set worktree field
-  specData.worktree = worktreeName;
-  const updatedYaml = yaml.dump(specData, { lineWidth: 120, noRefs: true });
-  fs.writeFileSync(specPath, updatedYaml, 'utf8');
+  // Update spec side: set worktree field. CAWSFIX-24 / D10: skip the write
+  // if the parsed spec already declares the target worktree — yaml.dump
+  // would otherwise re-wrap folded scalars with no semantic change.
+  if (specData.worktree !== worktreeName) {
+    specData.worktree = worktreeName;
+    const updatedYaml = yaml.dump(specData, { lineWidth: 120, noRefs: true });
+    fs.writeFileSync(specPath, updatedYaml, 'utf8');
+  }
+
+  // CAWSFIX-23: activate the spec if it's still at draft — bind is the
+  // lifecycle signal that work is starting. CAWSFIX-25 / D8: pass the
+  // resolved specPath so the flip lands on whichever copy (worktree-local
+  // or main) was actually bound.
+  const activated = autoActivateBoundSpec(root, specId, specPath);
+
+  // CAWSFIX-32: heartbeat the current session into agents.json so the
+  // bound worktree+spec context is visible to other agents and to
+  // `caws status` / `caws agents list`.
+  refreshAgentClaim(root, { worktree: worktreeName, specId });
 
   console.log(chalk.green(`Binding established`));
   console.log(chalk.gray(`   Worktree: ${worktreeName} -> spec: ${specId}`));
   console.log(chalk.gray(`   Spec: ${specId} -> worktree: ${worktreeName}`));
+  if (activated) {
+    console.log(chalk.gray(`   Status: draft -> active`));
+  }
   console.log(chalk.gray(`   Registry: ${path.join(root, '.caws', 'worktrees.json')}`));
   console.log(chalk.gray(`   Spec file: ${specPath}`));
 }
 
+/**
+ * CAWSFIX-31: caws worktree claim <name> [--takeover]
+ *
+ * Without --takeover: read-only context surface. Prints the current
+ * claim (owner, heartbeat, session-log pointers) and exits 1 when the
+ * worktree is owned by a different session id. Modifies nothing.
+ *
+ * With --takeover: rewrites the owner to the current session id,
+ * appends the prior owner to the worktree entry's prior_owners audit
+ * array (including their lastSeen-at-takeover from agents.json), and
+ * exits 0.
+ *
+ * Same session-id silent-proceed: if the current session already owns
+ * the worktree, the command is a successful no-op (exit 0, brief
+ * confirmation).
+ */
+function handleClaim(options) {
+  const { name, takeover } = options;
+
+  if (!name) {
+    console.error(chalk.red('Worktree name is required'));
+    console.log(chalk.blue('Usage: caws worktree claim <name> [--takeover]'));
+    process.exit(1);
+  }
+
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+  if (!registry.worktrees || !registry.worktrees[name]) {
+    console.error(chalk.red(`Worktree '${name}' not found in registry.`));
+    console.log(chalk.blue('Run: caws worktree list  to see available worktrees'));
+    process.exit(1);
+  }
+
+  const result = assertWorktreeOwnership(root, name, {
+    allowTakeover: !!takeover,
+    takeoverCommandHint: `caws worktree claim ${name} --takeover`,
+  });
+
+  if (!result.allowed) {
+    // Foreign claim, no --takeover. Print the structured warning that
+    // assertWorktreeOwnership built (claimer, heartbeat, session-log
+    // pointers, takeover hint) and exit 1. Modifies nothing.
+    console.error(chalk.yellow(result.warning));
+    process.exit(1);
+  }
+
+  // allowed = true. Three sub-cases:
+  //   1. takeover happened (priorOwner present)
+  //   2. orphan-log soft notice (warning present, no priorOwner)
+  //   3. clean / same-session (no warning)
+  if (result.priorOwner) {
+    console.log(
+      chalk.green(`Took over worktree '${name}'.`)
+    );
+    console.log(
+      chalk.gray(
+        `   Prior owner ${result.priorOwner.sessionId}:${result.priorOwner.platform || 'unknown'} recorded in prior_owners audit.`
+      )
+    );
+  } else if (result.warning) {
+    console.log(chalk.yellow(result.warning));
+    console.log(chalk.green(`Proceeding — no CAWS-tracked claim on '${name}'.`));
+  } else {
+    const entry = registry.worktrees[name];
+    if (entry.owner === getAgentSessionId(root)) {
+      console.log(chalk.green(`Worktree '${name}' is already claimed by the current session.`));
+    } else {
+      console.log(chalk.green(`Worktree '${name}' has no active claim.`));
+    }
+  }
+}
+
 module.exports = { worktreeCommand };