@smartmemory/compose 0.1.0

package/server/vision-store.js

@@ -0,0 +1,360 @@
+/**
+ * Vision Store — JSON-file-backed storage for vision surface items and connections.
+ * Loads from disk on startup, saves after every mutation.
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const VALID_TYPES = ['feature', 'track', 'idea', 'decision', 'question', 'thread', 'artifact', 'task', 'spec', 'evaluation'];
+export const VALID_STATUSES = ['planned', 'ready', 'in_progress', 'review', 'complete', 'blocked', 'parked', 'killed'];
+export const VALID_CONNECTION_TYPES = ['informs', 'blocks', 'supports', 'contradicts', 'implements'];
+export const VALID_PHASES = ['vision', 'specification', 'planning', 'implementation', 'verification', 'release'];
+
+import { getDataDir as getDefaultDataDir } from './project-root.js';
+
+const DATA_FILE = path.join(getDefaultDataDir(), 'vision-state.json');
+
+function slugify(title) {
+  return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+const PREFIX_RE = /^([A-Z]+\d*(?:-[A-Z]+\d*)*)(?=-\d|$)/;
+function deriveGroup(title, featureCode) {
+  const titleMatch = (title || '').match(PREFIX_RE);
+  if (titleMatch) return titleMatch[1];
+  const fcMatch = (featureCode || '').match(PREFIX_RE);
+  if (fcMatch) return fcMatch[1];
+  return null;
+}
+
+export class VisionStore {
+  constructor(dataDir) {
+    this._dataDir = dataDir || getDefaultDataDir();
+    this._dataFile = dataDir ? path.join(dataDir, 'vision-state.json') : DATA_FILE;
+    this.items = new Map();
+    this.connections = new Map();
+    this.gates = new Map();
+    this._load();
+  }
+
+  /**
+   * Re-target the store at a different data directory.
+   * Clears all in-memory state and reloads from the new location.
+   */
+  reloadFrom(dataDir) {
+    this._dataDir = dataDir;
+    this._dataFile = path.join(dataDir, 'vision-state.json');
+    this.items.clear();
+    this.connections.clear();
+    this.gates.clear();
+    this._load();
+  }
+
+  /** Load state from disk */
+  _load() {
+    try {
+      const raw = fs.readFileSync(this._dataFile, 'utf-8');
+      const data = JSON.parse(raw);
+      let migrated = false;
+      if (Array.isArray(data.items)) {
+        for (const item of data.items) {
+          // Migration: legacy featureCode → lifecycle.featureCode
+          if (item.featureCode && item.featureCode.startsWith('feature:') && !item.lifecycle?.featureCode) {
+            const bare = item.featureCode.replace(/^feature:/, '');
+            item.lifecycle = item.lifecycle || {};
+            item.lifecycle.featureCode = bare;
+            delete item.featureCode;
+            migrated = true;
+          }
+          if (!item.slug && item.title) item.slug = slugify(item.title);
+          if (!item.files) item.files = [];
+          if (!item.group) {
+            item.group = deriveGroup(item.title, item.featureCode || item.lifecycle?.featureCode);
+            if (item.group) migrated = true;
+          }
+          this.items.set(item.id, item);
+        }
+      }
+      if (Array.isArray(data.connections)) {
+        for (const conn of data.connections) this.connections.set(conn.id, conn);
+      }
+      if (Array.isArray(data.gates)) {
+        const seenGateIds = new Set();
+        const seenPendingKeys = new Set();
+        for (const gate of data.gates) {
+          if (seenGateIds.has(gate.id)) { migrated = true; continue; }
+          seenGateIds.add(gate.id);
+          // Dedup pending gates by itemId+stepId
+          if (gate.status === 'pending' && gate.itemId && gate.stepId) {
+            const key = `${gate.itemId}:${gate.stepId}`;
+            if (seenPendingKeys.has(key)) { migrated = true; continue; }
+            seenPendingKeys.add(key);
+          }
+          // Migration: normalize legacy gate outcomes
+          if (gate.outcome) {
+            const map = { approved: 'approve', killed: 'kill', revised: 'revise' };
+            if (map[gate.outcome]) { gate.outcome = map[gate.outcome]; migrated = true; }
+          }
+          this.gates.set(gate.id, gate);
+        }
+      }
+      if (migrated) this._save();
+      console.log(`[vision] Loaded ${this.items.size} items, ${this.connections.size} connections from ${this._dataFile}`);
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        console.log('[vision] No saved state found, starting fresh');
+      } else {
+        console.error('[vision] Failed to load state, starting fresh:', err.message);
+      }
+    }
+  }
+
+  /** Save state to disk atomically (temp file + rename) */
+  _save() {
+    try {
+      fs.mkdirSync(this._dataDir, { recursive: true });
+      const data = JSON.stringify(this.getState(), null, 2) + '\n';
+      const tmp = path.join(this._dataDir, `vision-state.json.tmp.${Date.now()}`);
+      fs.writeFileSync(tmp, data, 'utf-8');
+      fs.renameSync(tmp, this._dataFile);
+    } catch (err) {
+      console.error('[vision] Failed to save state:', err.message);
+    }
+  }
+
+  /** Get full state snapshot */
+  getState() {
+    return {
+      items: Array.from(this.items.values()),
+      connections: Array.from(this.connections.values()),
+      gates: Array.from(this.gates.values()),
+    };
+  }
+
+  /** Create a new vision item */
+  createItem({ type, title, description = '', confidence = 0, status = 'planned', phase, position, parentId, files, priority, assignedTo, governance, featureCode, group }) {
+    if (!VALID_TYPES.includes(type)) throw new Error(`Invalid type: ${type}`);
+    if (!title) throw new Error('title required');
+    if (!VALID_STATUSES.includes(status)) throw new Error(`Invalid status: ${status}`);
+    if (confidence < 0 || confidence > 4) throw new Error('confidence must be 0-4');
+    if (phase && !VALID_PHASES.includes(phase)) throw new Error(`Invalid phase: ${phase}`);
+    if (parentId && !this.items.has(parentId)) throw new Error(`Parent not found: ${parentId}`);
+
+    const now = new Date().toISOString();
+    const item = {
+      id: uuidv4(),
+      type,
+      title,
+      description,
+      confidence,
+      status,
+      phase: phase || null,
+      parentId: parentId || null,
+      files: Array.isArray(files) ? files : [],
+      priority: priority || null,
+      assignedTo: assignedTo || null,
+      governance: governance || null,
+      featureCode: featureCode || null,
+      group: group || deriveGroup(title, featureCode),
+      slug: slugify(title),
+      position: position || { x: 100 + Math.random() * 400, y: 100 + Math.random() * 300 },
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    this.items.set(item.id, item);
+    this._save();
+    return item;
+  }
+
+  /** Update an existing item (partial) */
+  updateItem(id, updates) {
+    const item = this.items.get(id);
+    if (!item) throw new Error(`Item not found: ${id}`);
+
+    if (updates.type !== undefined && !VALID_TYPES.includes(updates.type)) {
+      throw new Error(`Invalid type: ${updates.type}`);
+    }
+    if (updates.status !== undefined && !VALID_STATUSES.includes(updates.status)) {
+      throw new Error(`Invalid status: ${updates.status}`);
+    }
+    if (updates.confidence !== undefined && (updates.confidence < 0 || updates.confidence > 4)) {
+      throw new Error('confidence must be 0-4');
+    }
+    if (updates.phase !== undefined && updates.phase !== null && !VALID_PHASES.includes(updates.phase)) {
+      throw new Error(`Invalid phase: ${updates.phase}`);
+    }
+
+    const allowed = ['type', 'title', 'description', 'confidence', 'status', 'phase', 'position', 'parentId', 'summary', 'files', 'featureCode', 'stratumFlowId', 'evidence', 'group'];
+    for (const key of allowed) {
+      if (updates[key] !== undefined) {
+        item[key] = updates[key];
+      }
+    }
+    // Regenerate slug when title changes
+    if (updates.title !== undefined) {
+      item.slug = slugify(updates.title);
+    }
+    // Re-derive group when title or featureCode changes (unless group was explicitly set)
+    if ((updates.title !== undefined || updates.featureCode !== undefined) && updates.group === undefined) {
+      item.group = deriveGroup(item.title, item.featureCode || item.lifecycle?.featureCode);
+    }
+    // Ensure files is always an array
+    if (updates.files !== undefined) {
+      item.files = Array.isArray(updates.files) ? updates.files : [];
+    }
+    item.updatedAt = new Date().toISOString();
+
+    this.items.set(id, item);
+    this._save();
+    return item;
+  }
+
+  /** Update the lifecycle field on an item — bypasses the generic allowlist.
+   *  Only callable by LifecycleManager. */
+  updateLifecycle(id, lifecycle) {
+    const item = this.items.get(id);
+    if (!item) throw new Error(`Item not found: ${id}`);
+    item.lifecycle = lifecycle;
+    // Re-derive group when lifecycle gains a featureCode
+    if (lifecycle?.featureCode && !item.group) {
+      item.group = deriveGroup(item.title, lifecycle.featureCode);
+    }
+    item.updatedAt = new Date().toISOString();
+    this.items.set(id, item);
+    this._save();
+    return item;
+  }
+
+  /** Delete an item and all its connections and gates */
+  deleteItem(id) {
+    if (!this.items.has(id)) throw new Error(`Item not found: ${id}`);
+    this.items.delete(id);
+
+    // Remove connections referencing this item
+    for (const [connId, conn] of this.connections) {
+      if (conn.fromId === id || conn.toId === id) {
+        this.connections.delete(connId);
+      }
+    }
+
+    // Remove gates associated with this item
+    for (const [gateId, gate] of this.gates) {
+      if (gate.itemId === id) {
+        this.gates.delete(gateId);
+      }
+    }
+
+    this._save();
+    return { ok: true };
+  }
+
+  /** Create a connection between two items */
+  createConnection({ fromId, toId, type }) {
+    if (!this.items.has(fromId)) throw new Error(`Item not found: ${fromId}`);
+    if (!this.items.has(toId)) throw new Error(`Item not found: ${toId}`);
+    if (!VALID_CONNECTION_TYPES.includes(type)) throw new Error(`Invalid connection type: ${type}`);
+
+    const conn = {
+      id: uuidv4(),
+      fromId,
+      toId,
+      type,
+      createdAt: new Date().toISOString(),
+    };
+
+    this.connections.set(conn.id, conn);
+    this._save();
+    return conn;
+  }
+
+  /** Delete a connection */
+  deleteConnection(id) {
+    if (!this.connections.has(id)) throw new Error(`Connection not found: ${id}`);
+    this.connections.delete(id);
+    this._save();
+    return { ok: true };
+  }
+
+  // ── Gate methods ──────────────────────────────────────────────────────
+
+  /** Create a gate record */
+  createGate(gate) {
+    gate.policyMode = gate.policyMode ?? 'gate';
+    gate.artifactSnapshot = gate.artifactSnapshot ?? null;
+    this.gates.set(gate.id, gate);
+    this._save();
+    return gate;
+  }
+
+  /** Resolve a pending gate */
+  resolveGate(gateId, { outcome, comment, resolvedBy } = {}) {
+    const gate = this.gates.get(gateId);
+    if (!gate) throw new Error(`Gate not found: ${gateId}`);
+    if (gate.status !== 'pending') throw new Error(`Gate ${gateId} is not pending (status: ${gate.status})`);
+    gate.status = 'resolved';
+    gate.outcome = outcome;
+    gate.resolvedAt = new Date().toISOString();
+    gate.resolvedBy = resolvedBy ?? 'human';
+    gate.comment = comment || null;
+    this.gates.set(gateId, gate);
+    this._save();
+    return gate;
+  }
+
+  /** Get a gate by flow/step/round composite key */
+  getGateByFlowStep(flowId, stepId, round) {
+    const id = `${flowId}:${stepId}:${round}`;
+    return this.gates.get(id) || null;
+  }
+
+  /** Get a gate by its ID */
+  getGateById(gateId) {
+    return this.gates.get(gateId) || null;
+  }
+
+  /** Find an existing pending gate for the same item+step */
+  findPendingGate(itemId, stepId) {
+    for (const gate of this.gates.values()) {
+      if (gate.status === 'pending' && gate.itemId === itemId && gate.stepId === stepId) {
+        return gate;
+      }
+    }
+    return null;
+  }
+
+  /** Get all gates (any status) as an array */
+  getAllGates() {
+    return Array.from(this.gates.values());
+  }
+
+  /** Get pending gates, optionally filtered by item */
+  getPendingGates(itemId) {
+    const pending = [];
+    for (const gate of this.gates.values()) {
+      if (gate.status !== 'pending') continue;
+      if (itemId && gate.itemId !== itemId) continue;
+      pending.push(gate);
+    }
+    return pending;
+  }
+
+  /** Get all gates for an item (any status) */
+  getGatesForItem(itemId) {
+    const result = [];
+    for (const gate of this.gates.values()) {
+      if (gate.itemId === itemId) result.push(gate);
+    }
+    return result;
+  }
+
+  /** Find an item by its lifecycle featureCode */
+  getItemByFeatureCode(featureCode) {
+    for (const item of this.items.values()) {
+      if (item.lifecycle?.featureCode === featureCode) return item;
+    }
+    return null;
+  }
+}

package/server/vision-utils.js

@@ -0,0 +1,179 @@
+/**
+ * vision-utils.js — Pure/standalone utilities extracted from VisionServer.
+ *
+ * Functions here have no dependency on the VisionServer class instance and
+ * can be unit-tested or reused independently.
+ */
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getTargetRoot, loadProjectConfig } from './project-root.js';
+
+const PROJECT_ROOT = getTargetRoot();
+
+// ---------------------------------------------------------------------------
+// Error detection
+// ---------------------------------------------------------------------------
+
+const ERROR_PATTERNS = [
+  { type: 'build_error', severity: 'error', patterns: [/SyntaxError/i, /TypeError/i, /Cannot find module/i, /Build failed/i, /npm ERR!/i, /error TS\d/i, /ReferenceError/i] },
+  { type: 'test_failure', severity: 'error', patterns: [/FAIL /,  /failures?:/i, /AssertionError/i, /tests? failed/i, /\u2715/, /\u2717/] },
+  { type: 'git_conflict', severity: 'error', patterns: [/CONFLICT/i, /merge conflict/i, /rebase failed/i] },
+  { type: 'permission_error', severity: 'error', patterns: [/EACCES/i, /EPERM/i, /permission denied/i] },
+  { type: 'not_found', severity: 'warning', patterns: [/ENOENT/i, /No such file/i, /command not found/i] },
+  { type: 'lint_error', severity: 'warning', patterns: [/eslint.*error/i, /prettier.*error/i] },
+  { type: 'runtime_error', severity: 'error', patterns: [/Unhandled/i, /FATAL/i, /panic:/i, /Traceback/i] },
+];
+
+/**
+ * Pattern-match known error signatures in tool responses or error strings.
+ * Returns { type, severity, message } or null.
+ *
+ * @param {string} tool
+ * @param {object} input
+ * @param {string} responseText
+ * @returns {{ type: string, severity: string, message: string } | null}
+ */
+export function detectError(tool, input, responseText) {
+  if (!responseText || typeof responseText !== 'string') return null;
+
+  const text = responseText;
+
+  for (const { type, severity, patterns } of ERROR_PATTERNS) {
+    for (const pattern of patterns) {
+      const match = text.match(pattern);
+      if (match) {
+        const idx = text.indexOf(match[0]);
+        const lineStart = text.lastIndexOf('\n', idx) + 1;
+        const lineEnd = text.indexOf('\n', idx);
+        const line = text.slice(lineStart, lineEnd === -1 ? undefined : lineEnd).trim();
+        const message = line.length > 150 ? line.slice(0, 147) + '...' : line;
+        return { type, severity, message };
+      }
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Journal agent
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn a hidden agent to write a journal entry from session data.
+ *
+ * @param {object} session — serialized session object
+ * @param {string} transcriptPath
+ * @param {string} [projectRoot] — defaults to PROJECT_ROOT
+ */
+export function spawnJournalAgent(session, transcriptPath, projectRoot = PROJECT_ROOT) {
+  const config = loadProjectConfig();
+  const journalRel = config.paths?.journal || 'docs/journal';
+
+  const itemSummaries = Object.entries(session.items || {})
+    .map(([_id, data]) => `- ${data.title}: ${data.writes} writes, ${data.reads} reads. ${(data.summaries || []).map(s => s.summary || '').filter(Boolean).join('. ')}`)
+    .join('\n');
+  const blockSummaries = (session.blocks || [])
+    .map((b, i) => `- Block ${i + 1}: ${b.itemIds.length} items, ${b.toolCount} tool uses`)
+    .join('\n');
+
+  const startMs = new Date(session.startedAt).getTime();
+  const endMs = session.endedAt ? new Date(session.endedAt).getTime() : Date.now();
+  const durationSec = Math.round((endMs - startMs) / 1000);
+
+  const today = new Date().toISOString().slice(0, 10);
+  let sessionNum = 0;
+  try {
+    const entries = fs.readdirSync(path.join(projectRoot, journalRel));
+    for (const f of entries) {
+      const m = f.match(new RegExp(`^${today}-session-(\\d+)`));
+      if (m) sessionNum = Math.max(sessionNum, parseInt(m[1]) + 1);
+    }
+  } catch { /* journal dir might not exist */ }
+
+  const prompt = `You are writing a developer journal entry for the Compose project.
+Read the transcript at: ${transcriptPath}
+Write a journal entry at ${journalRel}/${today}-session-${sessionNum}-<slug>.md following the exact format of existing entries in ${journalRel}/. Use first person plural ("we"). Be honest about failures.
+Session data:
+- Duration: ${durationSec}s (${Math.round(durationSec / 60)} minutes)
+- Tool uses: ${session.toolCount}
+- Items worked on:\n${itemSummaries || '(none resolved)'}
+- Work blocks:\n${blockSummaries || '(single block)'}
+- Commits: ${(session.commits || []).join(', ') || '(none)'}
+After writing the entry, update ${journalRel}/README.md with the new entry row.
+Then commit both files.`;
+
+  const cleanEnv = { ...process.env, NO_COLOR: '1' };
+  delete cleanEnv.CLAUDECODE;
+  const proc = spawn('claude', ['-p', prompt, '--dangerously-skip-permissions'], {
+    cwd: projectRoot,
+    env: cleanEnv,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  proc.on('close', (code) => {
+    console.log(`[session] Journal agent exited (code ${code})`);
+  });
+  proc.on('error', (err) => {
+    console.error(`[session] Journal agent spawn error:`, err.message);
+  });
+  console.log(`[session] Journal agent spawned (PID ${proc.pid})`);
+}
+
+// ---------------------------------------------------------------------------
+// File path extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract slug from a docs/ file path.
+ *
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+export function extractSlugFromPath(filePath) {
+  const filename = filePath.split('/').pop().replace(/\.md$/, '');
+  const noDate = filename.replace(/^\d{4}-\d{2}-\d{2}-/, '');
+  const noSession = noDate.replace(/^session-\d+-/, '');
+  const noSuffix = noSession.replace(/-(roadmap|plan|design|spec|eval|review)$/, '');
+  return noSuffix || null;
+}
+
+/**
+ * Extract file paths from plan/spec markdown content.
+ *
+ * @param {string} markdown
+ * @returns {string[]}
+ */
+export function extractFilePaths(markdown) {
+  const paths = new Set();
+  const lines = markdown.split('\n');
+  const extRe = /\.(jsx?|tsx?|mjs|css|json|md|sh|py)$/;
+  const skipRe = /node_modules|dist\/|\.git\/|example|foo|bar|^node |^npm |^npx |test\.\w+$/;
+
+  let inCodeFence = false;
+  for (const line of lines) {
+    if (line.trim().startsWith('```')) { inCodeFence = !inCodeFence; continue; }
+    if (inCodeFence) continue;
+
+    const backtickMatches = line.matchAll(/`([^`]+)`/g);
+    for (const m of backtickMatches) {
+      const p = m[1].replace(/^\*\*|\*\*$/g, '').trim();
+      if (p.includes('/') && extRe.test(p) && !skipRe.test(p)) {
+        paths.add(p.replace(/^\.\//, ''));
+      }
+    }
+
+    const markerMatch = line.match(/[-*]\s+`?([^\s`]+)`?\s+\((?:new|existing)\)/);
+    if (markerMatch) {
+      const p = markerMatch[1].replace(/^\*\*|\*\*$/g, '').trim();
+      if (p.includes('/') && !skipRe.test(p)) {
+        paths.add(p.replace(/^\.\//, ''));
+      }
+    }
+  }
+
+  return Array.from(paths);
+}

package/server/worktree-gc.js

@@ -0,0 +1,137 @@
+/**
+ * worktree-gc.js — Garbage collector for orphan worktree directories.
+ *
+ * Scans `.compose/par/` for directories whose owner process has died.
+ * Uses `.owner` file (contains PID) to check liveness via process.kill(pid, 0).
+ * Directories without an owner or with a dead owner that are older than maxAgeMs
+ * are removed via `git worktree remove --force`, with fallback to rm -rf + prune.
+ */
+
+import { readdirSync, readFileSync, statSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const DEFAULT_SCAN_INTERVAL_MS = 15 * 60_000; // 15min
+const DEFAULT_MAX_AGE_MS       = 3600_000;     // 1h
+
+export class WorktreeGC {
+  #projectRoot;
+  #parDir;
+  #scanIntervalMs;
+  #maxAgeMs;
+  #timer = null;
+
+  /**
+   * @param {object} opts
+   * @param {string} opts.projectRoot — git repo root (for git worktree commands)
+   * @param {string} opts.parDir — path to .compose/par/ directory
+   * @param {number} [opts.scanIntervalMs]
+   * @param {number} [opts.maxAgeMs]
+   */
+  constructor({ projectRoot, parDir, scanIntervalMs, maxAgeMs }) {
+    this.#projectRoot    = projectRoot;
+    this.#parDir         = parDir;
+    this.#scanIntervalMs = scanIntervalMs ?? DEFAULT_SCAN_INTERVAL_MS;
+    this.#maxAgeMs       = maxAgeMs       ?? DEFAULT_MAX_AGE_MS;
+  }
+
+  /** Start periodic scanning. Also runs an initial scan. */
+  start() {
+    this.runNow().catch(() => {}); // fire-and-forget initial scan
+    this.#timer = setInterval(() => {
+      this.runNow().catch(() => {});
+    }, this.#scanIntervalMs);
+  }
+
+  /** Stop periodic scanning. */
+  stop() {
+    if (this.#timer) {
+      clearInterval(this.#timer);
+      this.#timer = null;
+    }
+  }
+
+  /**
+   * Run a single GC scan. Returns list of removed directory names.
+   * @returns {Promise<string[]>}
+   */
+  async runNow() {
+    if (!existsSync(this.#parDir)) return [];
+
+    let entries;
+    try {
+      entries = readdirSync(this.#parDir, { withFileTypes: true })
+        .filter(e => e.isDirectory());
+    } catch {
+      return [];
+    }
+
+    const removed = [];
+
+    for (const entry of entries) {
+      const dirPath = join(this.#parDir, entry.name);
+      const ownerFile = join(dirPath, '.owner');
+
+      // Check owner liveness
+      if (existsSync(ownerFile)) {
+        try {
+          const pid = parseInt(readFileSync(ownerFile, 'utf-8').trim(), 10);
+          if (pid > 0 && _isPidAlive(pid)) continue; // owner alive, skip
+        } catch {
+          // Can't read owner file — treat as orphan
+        }
+      }
+
+      // Check age
+      try {
+        const stat = statSync(dirPath);
+        const ageMs = Date.now() - stat.mtimeMs;
+        if (ageMs < this.#maxAgeMs) continue; // too fresh
+      } catch {
+        continue; // stat failed, skip
+      }
+
+      // Remove
+      if (this._removeWorktree(dirPath)) {
+        removed.push(entry.name);
+      }
+    }
+
+    return removed;
+  }
+
+  /**
+   * Attempt to remove a worktree directory. Returns true if successfully removed.
+   */
+  _removeWorktree(dirPath) {
+    // Try git worktree remove first
+    try {
+      execSync(`git worktree remove "${dirPath}" --force`, {
+        cwd: this.#projectRoot, encoding: 'utf-8', timeout: 30_000, stdio: 'pipe',
+      });
+      return true;
+    } catch {
+      // Fallback: rm -rf + prune
+      try {
+        rmSync(dirPath, { recursive: true, force: true });
+        try {
+          execSync('git worktree prune', {
+            cwd: this.#projectRoot, encoding: 'utf-8', timeout: 15_000, stdio: 'pipe',
+          });
+        } catch { /* prune is best-effort */ }
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  }
+}
+
+function _isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}