@paths.design/caws-cli 10.1.0 → 10.2.0

package/dist/gates/scope-boundary.js

@@ -21,14 +21,27 @@ function matchesAny(filePath, patterns) {
 }
 
 /**
- * Check if a file is an infrastructure file that always passes scope checks.
- * Root-level files are exempt UNLESS they match an explicit scope.out pattern.
+ * Check if a file is infrastructure or lives in a policy-declared
+ * non-governed zone. Exempt files bypass both scope.in and scope.out.
+ *
  * @param {string} filePath - File path to check
- * @returns {boolean} Whether the file is exempt from scope.in checks
+ * @param {string[]} [nonGovernedZones=[]] - Glob patterns from
+ *   policy.non_governed_zones. Paths matching any pattern are exempt
+ *   from scope enforcement entirely. (CAWSFIX-26 / D9)
+ * @returns {boolean} Whether the file is exempt from scope checks
  */
-function isExempt(filePath) {
+function isExempt(filePath, nonGovernedZones = []) {
   // .caws and .claude directories always pass (infrastructure)
   if (filePath.startsWith('.caws/') || filePath.startsWith('.claude/')) return true;
+
+  // Policy-declared non-governed zones short-circuit scope enforcement.
+  // Intentionally wins over scope.out: the contract is that these
+  // subtrees are outside the governance model, not merely excluded
+  // from one spec's scope.
+  if (nonGovernedZones.length > 0 && matchesAny(filePath, nonGovernedZones)) {
+    return true;
+  }
+
   return false;
 }
 
@@ -47,14 +60,20 @@ function isRootLevel(filePath) {
  * @param {Object} params - Gate parameters
  * @param {string[]} params.stagedFiles - Staged file paths
  * @param {Object} params.spec - Working spec with scope.in/scope.out
+ * @param {Object} [params.policy] - Optional CAWS policy. Reads
+ *   policy.non_governed_zones for path exemption (CAWSFIX-26 / D9).
+ *   When absent or the field is empty, only infra dirs are exempt.
  * @returns {Promise<Object>} Gate result with status and messages
  */
-async function run({ stagedFiles, spec }) {
+async function run({ stagedFiles, spec, policy }) {
   const messages = [];
   const violations = [];
 
   const scopeIn = spec?.scope?.in || [];
   const scopeOut = spec?.scope?.out || [];
+  const nonGovernedZones = Array.isArray(policy?.non_governed_zones)
+    ? policy.non_governed_zones
+    : [];
 
   // If no scope defined, pass
   if (scopeIn.length === 0 && scopeOut.length === 0) {
@@ -62,8 +81,8 @@ async function run({ stagedFiles, spec }) {
   }
 
   for (const file of stagedFiles) {
-    // Infrastructure dirs are always exempt
-    if (isExempt(file)) continue;
+    // Infrastructure dirs AND policy-declared non-governed zones are exempt.
+    if (isExempt(file, nonGovernedZones)) continue;
 
     // Check scope.out first (explicit exclusion) — applies to ALL files including root-level
     if (scopeOut.length > 0 && matchesAny(file, scopeOut)) {

package/dist/index.js

@@ -233,6 +233,11 @@ specsCmd
   .description('Close a completed spec (removes scope enforcement)')
   .action((id) => specsCommand('close', { id }));
 
+specsCmd
+  .command('archive <id>')
+  .description('Archive a spec — move to .caws/specs/.archive/ and flip status to archived')
+  .action((id) => specsCommand('archive', { id }));
+
 specsCmd
   .command('conflicts')
   .description('Check for scope conflicts between specs')
@@ -364,6 +369,7 @@ worktreeCmd
   .option('--dry-run', 'Preview conflicts without merging', false)
   .option('--message <msg>', 'Custom merge commit message')
   .option('--no-delete-branch', 'Keep the branch after merging')
+  .option('--takeover', 'Force takeover of a foreign worktree claim (writes prior_owners audit)', false)
   .action((name, options) => worktreeCommand('merge', { name, ...options }));
 
 worktreeCmd
@@ -385,8 +391,31 @@ worktreeCmd
   .command('bind <spec-id>')
   .description('Bind a spec to this worktree (fixes mutual reference)')
   .option('--name <name>', 'Worktree name (auto-detected from cwd if omitted)')
+  .option('--takeover', 'Force takeover of a foreign worktree claim (writes prior_owners audit)', false)
   .action((specId, options) => worktreeCommand('bind', { specId, ...options }));
 
+worktreeCmd
+  .command('claim <name>')
+  .description('Claim worktree session ownership (read-only without --takeover)')
+  .option('--takeover', 'Force takeover of a foreign claim (writes prior_owners audit)', false)
+  .action((name, options) => worktreeCommand('claim', { name, ...options }));
+
+// Agents command group
+const { agentsCommand } = require('./commands/agents');
+const agentsCmd = program
+  .command('agents')
+  .description('Inspect the agent registry and session-log pointers');
+
+agentsCmd
+  .command('list')
+  .description('List active CAWS-registered agent sessions')
+  .action(() => agentsCommand('list', {}));
+
+agentsCmd
+  .command('show <session-id>')
+  .description('Show details for a specific agent session, including session-log pointer')
+  .action((id) => agentsCommand('show', { id }));
+
 // Scope command group
 const scopeCmd = program
   .command('scope')

package/dist/policy/PolicyManager.js

@@ -356,6 +356,11 @@ class PolicyManager {
           description: 'Scan for TODO/FIXME/HACK/XXX markers',
         },
       },
+      // CAWSFIX-26 / D9: empty by default. Projects that need to opt a
+      // subtree out of scope enforcement (e.g., research/, playground/)
+      // add glob patterns here, e.g. ['research/**']. Paths matching any
+      // pattern bypass scope-boundary checks entirely.
+      non_governed_zones: [],
     };
   }
 

package/dist/templates/.caws/schemas/policy.schema.json

@@ -105,6 +105,11 @@
       },
       "additionalProperties": false,
       "description": "Quality gate configurations"
+    },
+    "non_governed_zones": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Glob patterns (picomatch, dot:true) for paths declared outside CAWS scope enforcement. Any file matching a pattern is exempt from scope-boundary checks — neither spec.scope.in nor spec.scope.out are consulted. Intended for research, playground, or experimental subtrees where governance is explicitly off by design. Example: [\"research/**\", \"playground/**\"]. (CAWSFIX-26 / D9)"
     }
   },
   "additionalProperties": false,

package/dist/templates/.caws/schemas/working-spec.schema.json

@@ -23,8 +23,8 @@
   "properties": {
     "id": {
       "type": "string",
-      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\\d+$",
-      "description": "Unique identifier for the change. Format: uppercase/digit PREFIX segments separated by dashes, final segment is one+ digits (e.g. CAWSFIX-16, P03-TRUTH-001, ALG-001A-HARDEN-01). Matches SPEC_ID_PATTERN in spec-validation.js (CAWSFIX-21 alignment)."
+      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\\d+[a-z]*$",
+      "description": "Unique identifier for the change. Format: uppercase/digit PREFIX segments separated by dashes, final segment is one+ digits with an optional lowercase suffix (e.g. CAWSFIX-16, P03-TRUTH-001, ALG-001A-HARDEN-01, APC-01a). Matches SPEC_ID_PATTERN in spec-validation.js (CAWSFIX-25 alignment)."
     },
     "title": {
       "type": "string",

package/dist/templates/.claude/rules/worktree-isolation.md

@@ -10,9 +10,27 @@ When multiple agents are working on this project, each agent MUST work in its ow
 ## Before starting work
 
 1. Check if worktrees exist: `caws worktree list` shows all active worktrees with last commit time and owner
-2. If worktrees are active and you are on the base branch, switch to your assigned worktree
-3. If no worktree exists for you, create one with `caws worktree create <name>` or `caws parallel setup <plan-file>`
-4. **Never touch a worktree you did not create.** Do not destroy, prune, stash, or "clean up" another agent's worktree — even if it looks stale. Another agent may be actively working in it. If you think a worktree is abandoned, leave it alone and let the user decide.
+2. Check who's actually working: `caws agents list` shows registered sessions and their bound worktree/spec, formatted as `<sessionId>:<platform>`
+3. If you're inside a worktree, run `caws status` — the Claim panel shows the current owner, last heartbeat, and any session-log path under `tmp/<sessionId>/`
+4. If worktrees are active and you are on the base branch, switch to your assigned worktree
+5. If no worktree exists for you, create one with `caws worktree create <name>` or `caws parallel setup <plan-file>`
+6. **Never touch a worktree you did not create.** Do not destroy, prune, stash, or "clean up" another agent's worktree — even if it looks stale. Another agent may be actively working in it. If you think a worktree is abandoned, leave it alone and let the user decide.
+
+## Foreign-claim soft-block
+
+`caws worktree bind`, `merge`, and `claim` refuse to mutate a worktree whose `worktrees.json:owner` is a session id different from the current session — unless `--takeover` is supplied. The refusal prints a structured warning naming the claimer, the heartbeat age, any session-log pointer under `tmp/<sessionId>/`, and the exact `--takeover` command:
+
+```
+Worktree 'wt-foo' is claimed by 8be65780-...:claude-code
+   Last heartbeat: 2026-04-27T17:04:00Z (23 min ago)
+   Session log:    tmp/8be65780-72e0-4fc7-a989-4ebac148c18d
+                   15 turns, last turn 2026-04-27T17:26:49Z
+   To proceed:     caws worktree claim wt-foo --takeover
+```
+
+**Decision-gating uses session-id equality only.** A stale heartbeat is NOT authorization to take over — paused sessions are not ended sessions. Read the session log under `tmp/<sessionId>/` for context first. Take over only when you have explicit user authorization.
+
+`--takeover` writes a durable `prior_owners` audit on the worktree entry (sessionId, platform, lastSeen-at-takeover, takenOver_at) so the handoff is traceable in `worktrees.json`, not just in agent memory.
 
 ## Forbidden operations when worktrees are active
 

package/dist/templates/CLAUDE.md

@@ -102,6 +102,12 @@ caws scope show
 
 # Fix a broken binding
 caws worktree bind <spec-id>
+
+# Inspect the agent registry — who is currently working what
+caws agents list
+
+# Inspect a specific worktree's claim (read-only by default)
+caws worktree claim <name>
 ```
 
 **Recovery checklist** (when the scope guard blocks you unexpectedly):
@@ -110,6 +116,22 @@ caws worktree bind <spec-id>
 3. If authoritative but still blocked: the file is genuinely outside your spec's scope. Update your spec's `scope.in` if the file should be in scope, or request a waiver
 4. Do NOT modify another spec's `scope.out` to unblock yourself — that defeats the isolation
 
+### Agent Claims & Multi-Agent Coordination
+
+Each session gets registered in `.caws/agents.json` automatically (via the session-log hook and on every CAWS lifecycle CLI invocation). Worktree session ownership is tracked in `.caws/worktrees.json:owner` as a session id.
+
+`caws worktree bind`, `merge`, and `claim` will refuse to mutate a worktree owned by a different session id without explicit `--takeover`. The refusal prints a structured warning naming the claimer as `<sessionId>:<platform>`, the heartbeat age, and any matching `tmp/<sessionId>/` session-log path so you can read context before deciding.
+
+**Decision-gating uses session-id equality only.** TTL pruning of `agents.json` is registry hygiene; it does NOT authorize takeover. A stale heartbeat doesn't mean the prior session is dead — it may be paused.
+
+`--takeover` writes a durable `prior_owners` audit on the worktree entry (sessionId, platform, lastSeen-at-takeover, takenOver_at) so handoffs are traceable in `worktrees.json`, not just in agent memory.
+
+### Spec lifecycle: archive
+
+Use `caws specs archive <id>` to move a closed spec to the canonical `.caws/specs/.archive/` directory. The directory is filesystem-authoritative — `caws specs list` reports any file under `.archive/` as `status: archived` regardless of the YAML literal. This means manually-moved legacy specs (no registry entry) are correctly classified.
+
+If you try to `caws specs create <id>` for an id that already exists in `.archive/`, the command refuses without `--force`. With `--force`, the archived YAML is removed and a fresh draft is created — useful for resurrecting an old id with new intent.
+
 > **Budget note**: `change_budget:` in a spec is informational documentation only. CAWS
 > derives the enforced budget from `policy.yaml` keyed on `risk_tier`. The field in the
 > spec is not used by `caws validate` for enforcement.

package/dist/templates/agents.md

@@ -59,6 +59,32 @@ caws worktree bind <spec-id>
 3. If authoritative but blocked: update your spec's `scope.in`
 4. Do NOT edit another spec's `scope.out` to unblock yourself
 
+## Multi-Agent Claims
+
+Each session is registered in `.caws/agents.json` automatically. Worktree session ownership is recorded in `.caws/worktrees.json:owner` as a session id. `caws worktree bind`, `merge`, and `claim` will refuse to mutate a worktree owned by a different session id without `--takeover`.
+
+```bash
+# See registered agents (composite <sessionId>:<platform> format)
+caws agents list
+
+# Inspect a worktree's claim — read-only by default
+caws worktree claim <name>
+
+# Take over a foreign claim (writes prior_owners audit)
+caws worktree claim <name> --takeover
+```
+
+When a refusal fires, the warning includes the claimer's session id, heartbeat age, and a pointer to any `tmp/<sessionId>/` session-log directory — read that log for context before deciding to take over. A stale heartbeat does NOT mean the prior session is dead; it may be paused.
+
+## Spec Lifecycle: Archive
+
+```bash
+# Move a closed spec to the canonical archive
+caws specs archive <spec-id>
+```
+
+The `.caws/specs/.archive/` directory is filesystem-authoritative — `caws specs list` reports any file under it as `archived` regardless of YAML status. `caws specs create` refuses ids that collide with archived files unless `--force` is supplied (which removes the archived copy and writes a fresh draft).
+
 ## Key Rules
 
 1. **Stay in scope** -- only edit files listed in `scope.in`, never touch `scope.out`

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,