@paths.design/caws-cli 10.0.1 → 10.2.0

package/dist/utils/agent-display.js

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview CAWSFIX-31 — agent claim display formatters.
+ *
+ * Single-purpose helpers for rendering agent / claim information so the
+ * format ("<sessionId>:<platform>", claim panels, soft-block warnings)
+ * is consistent across `caws status`, `caws agents`, and the
+ * worktree-manager soft-block surface.
+ *
+ * Display only — no I/O of its own beyond the small loaders it needs.
+ *
+ * @author @darianrosebrook
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const {
+  loadAgentRegistry,
+  findSessionLogs,
+} = require('./agent-session');
+
+/**
+ * Composite identifier used in every visible reference to an agent.
+ * Format: `<sessionId>:<platform>`. Lets readers trace provenance to
+ * platform-specific transcript directories.
+ *
+ * @param {string} sessionId
+ * @param {string} platform - 'claude-code' | 'cursor' | 'unknown'
+ * @returns {string}
+ */
+function formatAgentRef(sessionId, platform) {
+  const sid = sessionId || 'unknown';
+  const plat = platform || 'unknown';
+  return `${sid}:${plat}`;
+}
+
+/**
+ * Compute a short human-readable age for a heartbeat timestamp.
+ * @param {string|null} iso
+ * @returns {string}
+ */
+function formatHeartbeatAge(iso) {
+  if (!iso) return 'unknown';
+  const t = Date.parse(iso);
+  if (isNaN(t)) return 'unknown';
+  const ms = Date.now() - t;
+  if (ms < 0) return 'in the future';
+  const sec = Math.round(ms / 1000);
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.round(sec / 60);
+  if (min < 60) return `${min} min ago`;
+  const hr = Math.round(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const days = Math.round(hr / 24);
+  return `${days}d ago`;
+}
+
+/**
+ * Format a single session-log pointer for inclusion in a warning.
+ * Path is project-relative when possible.
+ *
+ * @param {object} log - Result from findSessionLogs
+ * @param {string} root - Project root (for relative path)
+ * @returns {string}
+ */
+function formatSessionLogPointer(log, root) {
+  const rel = path.relative(root, log.path) || log.path;
+  const parts = [`tmp/${path.basename(log.path)}`, `${log.turnCount} turns`];
+  if (log.lastTurn) parts.push(`last turn ${log.lastTurn}`);
+  return `   Session log: ${rel}\n                ${parts.join(', ')}`;
+}
+
+/**
+ * Build the structured warning printed when a foreign claim is
+ * detected on a worktree (for `assertWorktreeOwnership` soft-block,
+ * `caws worktree claim` read-only mode, etc.).
+ *
+ * @param {object} args
+ * @param {string} args.worktree - Worktree name
+ * @param {object|null} args.priorOwnerEntry - The agents.json entry for the
+ *   prior owner, or null when TTL-pruned.
+ * @param {string} args.priorOwnerSessionId - Sid from worktrees.json:owner
+ * @param {Array} args.sessionLogs - findSessionLogs() result
+ * @param {string} args.root - Project root for relative paths
+ * @param {string} args.takeoverCommand - Exact command to suggest
+ * @returns {string}
+ */
+function formatClaimNotice(args) {
+  const {
+    worktree,
+    priorOwnerEntry,
+    priorOwnerSessionId,
+    sessionLogs = [],
+    root,
+    takeoverCommand,
+  } = args;
+
+  const platform = priorOwnerEntry ? priorOwnerEntry.platform : 'unknown';
+  const ref = formatAgentRef(priorOwnerSessionId, platform);
+
+  const lines = [
+    `Worktree '${worktree}' is claimed by ${ref}`,
+  ];
+
+  if (priorOwnerEntry) {
+    const age = formatHeartbeatAge(priorOwnerEntry.lastSeen);
+    lines.push(`   Last heartbeat: ${priorOwnerEntry.lastSeen} (${age})`);
+  } else {
+    lines.push(`   Last heartbeat: no live agent registry entry (pruned or stale)`);
+  }
+
+  for (const log of sessionLogs) {
+    lines.push(formatSessionLogPointer(log, root));
+  }
+
+  if (takeoverCommand) {
+    lines.push(`   To proceed:    ${takeoverCommand}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build a softer hint when a worktree has no CAWS-tracked owner but a
+ * matching session-log directory exists (the "may still be active"
+ * scenario from AC A8).
+ *
+ * @param {object} args
+ * @param {string} args.worktree
+ * @param {Array} args.sessionLogs
+ * @param {string} args.root
+ * @returns {string}
+ */
+function formatOrphanLogHint(args) {
+  const { worktree, sessionLogs = [], root } = args;
+  const lines = [
+    `No active CAWS claim on worktree '${worktree}', but a session log exists.`,
+    `   The previous session may still be active — read for context before continuing:`,
+  ];
+  for (const log of sessionLogs) {
+    lines.push(formatSessionLogPointer(log, root));
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Render the Claim panel that `caws status` includes when cwd is
+ * inside a worktree. Returns a multi-line string (caller prints it).
+ *
+ * @param {string} root - Project root
+ * @param {string} worktreeName - Worktree to inspect
+ * @returns {string}
+ */
+function renderClaimPanel(root, worktreeName) {
+  let entry = null;
+  try {
+    const wtRegistryPath = path.join(root, '.caws', 'worktrees.json');
+    if (fs.existsSync(wtRegistryPath)) {
+      const reg = JSON.parse(fs.readFileSync(wtRegistryPath, 'utf8'));
+      entry = reg.worktrees && reg.worktrees[worktreeName];
+    }
+  } catch {
+    // Best-effort.
+  }
+
+  if (!entry || !entry.owner) {
+    return `Claim: no active claim on worktree '${worktreeName}'`;
+  }
+
+  const agentRegistry = loadAgentRegistry(root);
+  const ownerEntry = agentRegistry.agents[entry.owner] || null;
+  const platform = ownerEntry ? ownerEntry.platform : 'unknown';
+  const ref = formatAgentRef(entry.owner, platform);
+
+  const lines = [`Claim: worktree '${worktreeName}' owned by ${ref}`];
+  if (ownerEntry) {
+    lines.push(
+      `   Last heartbeat: ${ownerEntry.lastSeen} (${formatHeartbeatAge(ownerEntry.lastSeen)})`
+    );
+    if (ownerEntry.specId) {
+      lines.push(`   Spec:           ${ownerEntry.specId}`);
+    }
+  } else {
+    lines.push(`   Last heartbeat: no live agent registry entry (pruned)`);
+  }
+
+  // Surface session-log pointers if present (filter by branch when known).
+  const branch = entry.branch || null;
+  const logs = findSessionLogs(root, { sessionId: entry.owner }).concat(
+    branch ? findSessionLogs(root, { branch }) : []
+  );
+  // Dedupe by path
+  const seen = new Set();
+  for (const log of logs) {
+    if (seen.has(log.path)) continue;
+    seen.add(log.path);
+    lines.push(formatSessionLogPointer(log, root));
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  formatAgentRef,
+  formatHeartbeatAge,
+  formatSessionLogPointer,
+  formatClaimNotice,
+  formatOrphanLogHint,
+  renderClaimPanel,
+};

package/dist/utils/agent-session.js

@@ -122,18 +122,26 @@ function saveAgentRegistry(root, registry) {
  * @param {string} agent.platform - 'claude-code' | 'cursor' | 'unknown'
  * @param {string} [agent.model] - Model name if known
  * @param {string} [agent.specId] - Active spec ID if known
+ * @param {string|null} [agent.worktree] - Active worktree name if known
  * @param {number} [agent.ttl] - Custom TTL in ms (default 30 min)
  */
 function heartbeatAgent(root, agent) {
   const registry = loadAgentRegistry(root);
   const existing = registry.agents[agent.sessionId] || {};
 
+  // CAWSFIX-31: `worktree` is allowed to be set to null explicitly (e.g.,
+  // refreshing a spec-only operation). Distinguish "not provided" from
+  // "explicitly null" using `in` so the previous worktree binding isn't
+  // silently preserved when the caller intends to clear it.
+  const worktreeProvided = Object.prototype.hasOwnProperty.call(agent, 'worktree');
+
   registry.agents[agent.sessionId] = {
     ...existing,
     sessionId: agent.sessionId,
     platform: agent.platform || existing.platform || 'unknown',
     model: agent.model || existing.model || null,
     specId: agent.specId || existing.specId || null,
+    worktree: worktreeProvided ? agent.worktree : (existing.worktree || null),
     ttl: agent.ttl || existing.ttl || DEFAULT_TTL_MS,
     firstSeen: existing.firstSeen || new Date().toISOString(),
     lastSeen: new Date().toISOString(),
@@ -142,6 +150,138 @@ function heartbeatAgent(root, agent) {
   saveAgentRegistry(root, registry);
 }
 
+/**
+ * Refresh the current agent session's claim with the operation's specId
+ * and (optionally) worktree context.
+ *
+ * CAWSFIX-31: every CAWS lifecycle CLI op (specs create/close/archive/
+ * delete, worktree create/bind/merge) calls this so agents.json stays
+ * fresh even when the IDE session-log hook hasn't fired (e.g., between
+ * SessionStart and PreCompact, or in non-Claude-Code environments).
+ *
+ * Best-effort: silently no-ops when no session id can be determined or
+ * when the project root has no .caws/ directory. Never throws.
+ *
+ * @param {string} root - Project root
+ * @param {object} ctx - Refresh context
+ * @param {string|null} [ctx.specId] - Spec the operation touched
+ * @param {string|null} [ctx.worktree] - Worktree the operation touched
+ */
+function refreshAgentClaim(root, ctx = {}) {
+  try {
+    const sessionId = getAgentSessionId(root);
+    if (!sessionId) return;
+    const platform = getAgentPlatform();
+    heartbeatAgent(root, {
+      sessionId,
+      platform,
+      specId: ctx.specId || null,
+      worktree: ctx.worktree !== undefined ? ctx.worktree : null,
+    });
+  } catch {
+    // Best-effort: a failure here must never break the lifecycle op.
+  }
+}
+
+/**
+ * Find session-log directories under `tmp/` whose `.meta.json` matches
+ * the given session id or branch.
+ *
+ * CAWSFIX-31: the CLI surfaces these paths as pointers when a foreign
+ * claim is detected. It does not interpret the contents — the agent
+ * reads them and decides whether to take over.
+ *
+ * Returns an array of `{ sessionId, path, branch, turnCount, lastTurn }`.
+ * Tolerates missing/malformed `.meta.json`. Refuses to follow symlinks
+ * outside `<root>/tmp/` for safety.
+ *
+ * @param {string} root - Project root
+ * @param {object} [filters] - Optional filters
+ * @param {string} [filters.sessionId] - Only return logs for this id
+ * @param {string} [filters.branch] - Only return logs whose meta.branch matches
+ * @returns {Array<object>}
+ */
+function findSessionLogs(root, filters = {}) {
+  const results = [];
+  const tmpDir = path.join(root, 'tmp');
+  if (!fs.existsSync(tmpDir)) return results;
+
+  let realTmp;
+  try {
+    realTmp = fs.realpathSync(tmpDir);
+  } catch {
+    return results;
+  }
+
+  let entries;
+  try {
+    entries = fs.readdirSync(tmpDir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const sid = entry.name;
+    if (filters.sessionId && sid !== filters.sessionId) continue;
+
+    const dirPath = path.join(tmpDir, sid);
+    let realDir;
+    try {
+      realDir = fs.realpathSync(dirPath);
+    } catch {
+      continue;
+    }
+    // Symlink-escape guard: realpath must remain under realTmp.
+    if (!realDir.startsWith(realTmp + path.sep) && realDir !== realTmp) continue;
+
+    const metaPath = path.join(dirPath, '.meta.json');
+    if (!fs.existsSync(metaPath)) continue;
+
+    let meta = {};
+    try {
+      meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+    } catch {
+      // Malformed .meta.json — skip but don't crash.
+      continue;
+    }
+
+    if (filters.branch && meta.branch !== filters.branch) continue;
+
+    // Count turn files and capture latest turn timestamp.
+    let turnCount = 0;
+    let lastTurn = null;
+    try {
+      const files = fs.readdirSync(dirPath);
+      const turnFiles = files
+        .filter((f) => /^turn-\d+\.json$/.test(f))
+        .sort();
+      turnCount = turnFiles.length;
+      if (turnFiles.length > 0) {
+        const latest = turnFiles[turnFiles.length - 1];
+        try {
+          const turnData = JSON.parse(fs.readFileSync(path.join(dirPath, latest), 'utf8'));
+          lastTurn = turnData.ts_end || turnData.ts_start || null;
+        } catch {
+          lastTurn = null;
+        }
+      }
+    } catch {
+      // best-effort; leave defaults
+    }
+
+    results.push({
+      sessionId: sid,
+      path: dirPath,
+      branch: meta.branch || null,
+      turnCount,
+      lastTurn,
+    });
+  }
+
+  return results;
+}
+
 /**
  * Remove an agent session from the registry.
  * Called on session stop.
@@ -194,6 +334,8 @@ module.exports = {
   loadAgentRegistry,
   saveAgentRegistry,
   heartbeatAgent,
+  refreshAgentClaim,
+  findSessionLogs,
   removeAgent,
   findActiveAgent,
   listActiveAgents,