@smartmemory/compose 0.1.0

package/scripts/wire-orphans.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+
+/**
+ * Wire 66 orphaned vision tracker items into the feature/track hierarchy
+ * by creating `implements` connections (fromId=item, toId=track).
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { v4 as uuidv4 } from 'uuid';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const dataPath = resolve(__dirname, '..', 'data', 'vision-state.json');
+
+// The 66 orphaned items mapped to their tracks (item semanticId -> track semanticId)
+const MAPPINGS = [
+  ['FORGE-DEC-1',   'FORGE-TRK-1'],
+  ['FORGE-DEC-2',   'FORGE-TRK-5'],
+  ['FORGE-DEC-5',   'FORGE-TRK-5'],
+  ['FORGE-DEC-6',   'FORGE-TRK-5'],
+  ['FORGE-DEC-4',   'FORGE-TRK-5'],
+  ['FORGE-DEC-3',   'FORGE-TRK-5'],
+  ['FORGE-DEC-7',   'FORGE-TRK-3'],
+  ['FORGE-DEC-8',   'FORGE-TRK-10'],
+  ['FORGE-DEC-9',   'FORGE-TRK-1'],
+  ['FORGE-IDEA-8',  'FORGE-TRK-5'],
+  ['FORGE-IDEA-9',  'FORGE-TRK-13'],
+  ['FORGE-IDEA-2',  'FORGE-TRK-14'],
+  ['FORGE-IDEA-3',  'FORGE-TRK-5'],
+  ['FORGE-IDEA-1',  'FORGE-TRK-1'],
+  ['FORGE-IDEA-4',  'FORGE-TRK-5'],
+  ['FORGE-Q-3',     'FORGE-TRK-5'],
+  ['FORGE-Q-4',     'FORGE-TRK-1'],
+  ['FORGE-Q-5',     'FORGE-TRK-5'],
+  ['FORGE-Q-1',     'FORGE-TRK-5'],
+  ['FORGE-THR-3',   'FORGE-TRK-1'],
+  ['FORGE-THR-1',   'FORGE-TRK-5'],
+  ['FORGE-THR-2',   'FORGE-TRK-5'],
+  ['FORGE-THR-4',   'FORGE-TRK-5'],
+  ['FORGE-ART-1',   'FORGE-TRK-3'],
+  ['FORGE-DEC-10',  'FORGE-TRK-1'],
+  ['FORGE-DEC-11',  'FORGE-TRK-5'],
+  ['FORGE-DEC-12',  'FORGE-TRK-3'],
+  ['FORGE-DEC-13',  'FORGE-TRK-3'],
+  ['FORGE-IDEA-5',  'FORGE-TRK-8'],
+  ['FORGE-IDEA-6',  'FORGE-TRK-9'],
+  ['FORGE-IDEA-7',  'FORGE-TRK-11'],
+  ['FORGE-IDEA-10', 'FORGE-TRK-14'],
+  ['FORGE-THR-5',   'FORGE-TRK-1'],
+  ['FORGE-Q-2',     'FORGE-TRK-11'],
+  ['FORGE-SPEC-1',  'FORGE-TRK-3'],
+  ['FORGE-SPEC-2',  'FORGE-TRK-3'],
+  ['FORGE-SPEC-3',  'FORGE-TRK-3'],
+  ['FORGE-SPEC-4',  'FORGE-TRK-3'],
+  ['FORGE-TASK-1',  'FORGE-TRK-3'],
+  ['FORGE-TASK-2',  'FORGE-TRK-3'],
+  ['FORGE-TASK-3',  'FORGE-TRK-14'],
+  ['FORGE-TASK-4',  'FORGE-TRK-6'],
+  ['FORGE-TASK-5',  'FORGE-TRK-14'],
+  ['FORGE-TASK-6',  'FORGE-TRK-3'],
+  ['FORGE-DEC-14',  'FORGE-TRK-5'],
+  ['FORGE-DEC-15',  'FORGE-TRK-5'],
+  ['FORGE-DEC-16',  'FORGE-TRK-5'],
+  ['FORGE-ART-2',   'FORGE-TRK-5'],
+  ['FORGE-ART-3',   'FORGE-TRK-1'],
+  ['FORGE-DEC-17',  'FORGE-TRK-12'],
+  ['FORGE-DEC-18',  'FORGE-TRK-13'],
+  ['FORGE-SPEC-5',  'FORGE-TRK-6'],
+  ['FORGE-SPEC-6',  'FORGE-TRK-6'],
+  ['FORGE-DEC-19',  'FORGE-TRK-6'],
+  ['FORGE-DEC-20',  'FORGE-TRK-6'],
+  ['FORGE-DEC-21',  'FORGE-TRK-5'],
+  ['FORGE-DEC-22',  'FORGE-TRK-5'],
+  ['FORGE-DEC-23',  'FORGE-TRK-13'],
+  ['FORGE-DEC-24',  'FORGE-TRK-6'],
+  ['FORGE-DEC-25',  'FORGE-TRK-6'],
+  ['FORGE-DEC-26',  'FORGE-TRK-6'],
+  ['FORGE-DEC-27',  'FORGE-TRK-6'],
+  ['FORGE-IDEA-11', 'FORGE-TRK-7'],
+  ['FORGE-SPEC-7',  'FORGE-TRK-7'],
+  ['FORGE-DEC-28',  'FORGE-TRK-13'],
+  ['FORGE-DEC-29',  'FORGE-TRK-13'],
+];
+
+// Read the state file
+const state = JSON.parse(readFileSync(dataPath, 'utf-8'));
+
+// Build a lookup: semanticId -> item UUID
+const semanticToId = new Map();
+for (const item of state.items) {
+  if (item.semanticId) {
+    semanticToId.set(item.semanticId, item.id);
+  }
+}
+
+// Build a set of existing connections for dedup: "fromId->toId->type"
+const existingConnections = new Set();
+for (const conn of state.connections) {
+  existingConnections.add(`${conn.fromId}->${conn.toId}->${conn.type}`);
+}
+
+let created = 0;
+let skippedDuplicate = 0;
+let skippedMissing = 0;
+const summary = { byTrack: {} };
+
+for (const [itemSemantic, trackSemantic] of MAPPINGS) {
+  const fromId = semanticToId.get(itemSemantic);
+  const toId = semanticToId.get(trackSemantic);
+
+  if (!fromId) {
+    console.warn(`  SKIP: item ${itemSemantic} not found in vision-state.json`);
+    skippedMissing++;
+    continue;
+  }
+  if (!toId) {
+    console.warn(`  SKIP: track ${trackSemantic} not found in vision-state.json`);
+    skippedMissing++;
+    continue;
+  }
+
+  const key = `${fromId}->${toId}->implements`;
+  if (existingConnections.has(key)) {
+    skippedDuplicate++;
+    continue;
+  }
+
+  const connection = {
+    id: uuidv4(),
+    fromId,
+    toId,
+    type: 'implements',
+    createdAt: new Date().toISOString(),
+  };
+
+  state.connections.push(connection);
+  existingConnections.add(key);
+  created++;
+
+  // Track summary
+  if (!summary.byTrack[trackSemantic]) {
+    summary.byTrack[trackSemantic] = [];
+  }
+  summary.byTrack[trackSemantic].push(itemSemantic);
+}
+
+// Save
+writeFileSync(dataPath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+
+// Print summary
+console.log(`\n=== Wire Orphans Summary ===`);
+console.log(`Total mappings:     ${MAPPINGS.length}`);
+console.log(`Connections created: ${created}`);
+console.log(`Skipped (duplicate): ${skippedDuplicate}`);
+console.log(`Skipped (missing):   ${skippedMissing}`);
+console.log(`\nBy track:`);
+
+for (const [track, items] of Object.entries(summary.byTrack).sort()) {
+  console.log(`  ${track} (${items.length} items):`);
+  for (const item of items) {
+    console.log(`    - ${item}`);
+  }
+}

package/server/activity-routes.js

@@ -0,0 +1,123 @@
+/**
+ * activity-routes.js — POST /api/agent/activity and POST /api/agent/error route handlers.
+ *
+ * These stay separate from vision-routes because they depend on resolveItems,
+ * which lives on VisionServer. Both deps are injected.
+ */
+
+import { detectError } from './vision-utils.js';
+
+// NOTE: Duplicated in vision-server.js and src/components/Terminal.jsx — keep in sync
+const TOOL_CATEGORIES = {
+  Read: 'reading', Glob: 'searching', Grep: 'searching',
+  Write: 'writing', Edit: 'writing', NotebookEdit: 'writing',
+  Bash: 'executing', Task: 'delegating', Skill: 'delegating',
+  WebFetch: 'fetching', WebSearch: 'searching',
+  TodoRead: 'reading', TodoWrite: 'writing',
+};
+
+/**
+ * @param {object} app
+ * @param {{ store, sessionManager, scheduleBroadcast, broadcastMessage, resolveItems }} deps
+ */
+export function attachActivityRoutes(app, { store, sessionManager, scheduleBroadcast, broadcastMessage, resolveItems }) {
+  // POST /api/agent/activity — receive tool use events from hooks
+  app.post('/api/agent/activity', (req, res) => {
+    const { tool, input, response, timestamp } = req.body || {};
+    if (!tool) return res.status(400).json({ error: 'tool is required' });
+
+    let detail = null;
+    let filePath = null;
+    if (input) {
+      filePath = input.file_path || null;
+      detail = filePath || input.command || input.pattern || input.query || input.url || input.prompt || null;
+      if (detail && detail.length > 120) detail = detail.slice(0, 117) + '...';
+    }
+
+    const items = filePath ? resolveItems(filePath) : [];
+
+    // Auto-status: Write/Edit on planned items → in_progress
+    if (['Write', 'Edit'].includes(tool) && filePath) {
+      for (const item of items) {
+        if (item.status === 'planned') {
+          try {
+            store.updateItem(item.id, { status: 'in_progress' });
+            scheduleBroadcast();
+          } catch { /* ignore */ }
+        }
+      }
+    }
+
+    const category = TOOL_CATEGORIES[tool] || 'thinking';
+
+    if (sessionManager) {
+      sessionManager.recordActivity(tool, category, filePath, input, items);
+    }
+
+    let error = null;
+    if (response && typeof response === 'string') {
+      error = detectError(tool, input, response);
+    }
+
+    if (error) {
+      if (sessionManager) {
+        sessionManager.recordError(tool, filePath, error.type, error.severity, error.message, items);
+      }
+      broadcastMessage({
+        type: 'agentError',
+        errorType: error.type,
+        severity: error.severity,
+        message: error.message,
+        tool,
+        detail,
+        items: items.map(i => ({ id: i.id, title: i.title })),
+        timestamp: timestamp || new Date().toISOString(),
+      });
+    }
+
+    broadcastMessage({
+      type: 'agentActivity',
+      tool,
+      category,
+      detail,
+      error: error ? { type: error.type, severity: error.severity } : null,
+      items: items.map(i => ({ id: i.id, title: i.title, status: i.status, phase: i.lifecycle?.currentPhase || null })),
+      timestamp: timestamp || new Date().toISOString(),
+    });
+
+    res.json({ ok: true });
+  });
+
+  // POST /api/agent/error — receive PostToolUseFailure events from hooks
+  app.post('/api/agent/error', (req, res) => {
+    const { tool, input, error: errorMsg } = req.body || {};
+    if (!tool) return res.status(400).json({ error: 'tool is required' });
+
+    const filePath = input?.file_path || null;
+    const items = filePath ? resolveItems(filePath) : [];
+
+    const detected = detectError(tool, input, errorMsg || '') || {
+      type: 'runtime_error',
+      severity: 'error',
+      message: errorMsg || 'Tool use failed',
+    };
+
+    if (sessionManager) {
+      sessionManager.recordError(tool, filePath, detected.type, detected.severity, detected.message, items);
+    }
+
+    broadcastMessage({
+      type: 'agentError',
+      errorType: detected.type,
+      severity: detected.severity,
+      message: detected.message,
+      tool,
+      detail: filePath || input?.command || null,
+      items: items.map(i => ({ id: i.id, title: i.title })),
+      timestamp: new Date().toISOString(),
+    });
+
+    console.log(`[vision] Error detected: ${detected.type} (${detected.severity}) from ${tool}: ${detected.message.slice(0, 80)}`);
+    res.json({ ok: true, detected });
+  });
+}

package/server/agent-health.js

@@ -0,0 +1,197 @@
+/**
+ * agent-health.js — HealthMonitor for spawned subagents.
+ *
+ * Tracks stdout/stderr activity to detect silent agents.
+ * Enforces wall-clock timeout and memory RSS limits.
+ * Broadcasts agentSilent / agentKilled events via the vision WS.
+ *
+ * Terminal reasons: manual_stop | silence_timeout | wall_clock_timeout | memory_exceeded | normal
+ */
+
+import { execSync } from 'node:child_process';
+
+const GRACEFUL_KILL_MS = 5000; // 5s grace before SIGKILL
+
+/**
+ * Send SIGTERM, then escalate to SIGKILL after a grace period.
+ * Cleans up the escalation timer when the process exits on its own.
+ */
+export function gracefulKill(proc, graceMs = GRACEFUL_KILL_MS) {
+  try { proc.kill('SIGTERM'); } catch { /* already dead */ }
+  const killTimer = setTimeout(() => {
+    try { proc.kill('SIGKILL'); } catch { /* already dead */ }
+  }, graceMs);
+  proc.once('close', () => clearTimeout(killTimer));
+}
+
+const DEFAULT_SILENCE_WARNING_MS = 60_000;       // 60s silence → warning
+const DEFAULT_SILENCE_KILL_MS    = 5 * 60_000;   // 5min silence → kill
+const DEFAULT_TIMEOUT_MS         = 10 * 60_000;  // 10min wall-clock
+const DEFAULT_MEMORY_LIMIT_MB   = 0;             // 0 = disabled
+const MEMORY_POLL_INTERVAL_MS   = 30_000;        // 30s
+
+export class HealthMonitor {
+  #broadcastMessage;
+  #silenceWarningMs;
+  #silenceKillMs;
+  #defaultTimeoutMs;
+  #memoryLimitMB;
+
+  /** @type {Map<string, TrackedAgent>} */
+  #agents = new Map();
+
+  /**
+   * @param {object} opts
+   * @param {function} opts.broadcastMessage
+   * @param {number}   [opts.silenceWarningMs]
+   * @param {number}   [opts.silenceKillMs]
+   * @param {number}   [opts.defaultTimeoutMs]
+   * @param {number}   [opts.memoryLimitMB]
+   */
+  constructor({ broadcastMessage, silenceWarningMs, silenceKillMs, defaultTimeoutMs, memoryLimitMB }) {
+    this.#broadcastMessage = broadcastMessage;
+    this.#silenceWarningMs = silenceWarningMs ?? DEFAULT_SILENCE_WARNING_MS;
+    this.#silenceKillMs    = silenceKillMs    ?? DEFAULT_SILENCE_KILL_MS;
+    this.#defaultTimeoutMs = defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#memoryLimitMB    = memoryLimitMB    ?? DEFAULT_MEMORY_LIMIT_MB;
+  }
+
+  /**
+   * Start monitoring an agent process.
+   * @param {string} agentId
+   * @param {import('node:child_process').ChildProcess} proc
+   */
+  track(agentId, proc) {
+    // Clean up any prior tracking for same id
+    if (this.#agents.has(agentId)) this.untrack(agentId);
+
+    const entry = {
+      proc,
+      pid: proc.pid,
+      startedAt: Date.now(),
+      lastActivity: Date.now(),
+      terminalReason: null,
+      silenceWarningTimer: null,
+      silenceKillTimer: null,
+      wallClockTimer: null,
+      memoryPollTimer: null,
+      stdoutHandler: null,
+      stderrHandler: null,
+    };
+
+    // Activity listeners
+    const onActivity = () => { entry.lastActivity = Date.now(); this._resetSilenceTimers(agentId); };
+    entry.stdoutHandler = onActivity;
+    entry.stderrHandler = onActivity;
+    if (proc.stdout) proc.stdout.on('data', entry.stdoutHandler);
+    if (proc.stderr) proc.stderr.on('data', entry.stderrHandler);
+
+    this.#agents.set(agentId, entry);
+
+    // Start silence timers
+    this._resetSilenceTimers(agentId);
+
+    // Wall-clock timeout
+    entry.wallClockTimer = setTimeout(() => this._kill(agentId, 'wall_clock_timeout'), this.#defaultTimeoutMs);
+
+    // Memory polling
+    if (this.#memoryLimitMB > 0) {
+      entry.memoryPollTimer = setInterval(() => this._checkMemory(agentId), MEMORY_POLL_INTERVAL_MS);
+    }
+  }
+
+  /**
+   * Stop monitoring an agent (does NOT kill the process).
+   */
+  untrack(agentId) {
+    const entry = this.#agents.get(agentId);
+    if (!entry) return;
+    this._clearTimers(entry);
+    // Remove listeners
+    if (entry.proc.stdout && entry.stdoutHandler) entry.proc.stdout.removeListener('data', entry.stdoutHandler);
+    if (entry.proc.stderr && entry.stderrHandler) entry.proc.stderr.removeListener('data', entry.stderrHandler);
+    this.#agents.delete(agentId);
+  }
+
+  isTracked(agentId) {
+    return this.#agents.has(agentId);
+  }
+
+  getTerminalReason(agentId) {
+    return this.#agents.get(agentId)?.terminalReason ?? null;
+  }
+
+  setTerminalReason(agentId, reason) {
+    const entry = this.#agents.get(agentId);
+    if (entry) entry.terminalReason = reason;
+  }
+
+  /** Clean up all tracked agents and timers. */
+  destroy() {
+    for (const agentId of [...this.#agents.keys()]) {
+      this.untrack(agentId);
+    }
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────
+
+  _resetSilenceTimers(agentId) {
+    const entry = this.#agents.get(agentId);
+    if (!entry) return;
+
+    if (entry.silenceWarningTimer) clearTimeout(entry.silenceWarningTimer);
+    if (entry.silenceKillTimer) clearTimeout(entry.silenceKillTimer);
+
+    entry.silenceWarningTimer = setTimeout(() => {
+      this.#broadcastMessage({
+        type: 'agentSilent',
+        agentId,
+        silentSinceMs: Date.now() - entry.lastActivity,
+        timestamp: new Date().toISOString(),
+      });
+    }, this.#silenceWarningMs);
+
+    entry.silenceKillTimer = setTimeout(() => {
+      this._kill(agentId, 'silence_timeout');
+    }, this.#silenceKillMs);
+  }
+
+  _kill(agentId, reason) {
+    const entry = this.#agents.get(agentId);
+    if (!entry || entry.terminalReason) return; // already killed
+
+    entry.terminalReason = reason;
+    this._clearTimers(entry);
+
+    gracefulKill(entry.proc);
+
+    this.#broadcastMessage({
+      type: 'agentKilled',
+      agentId,
+      reason,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  _clearTimers(entry) {
+    if (entry.silenceWarningTimer) { clearTimeout(entry.silenceWarningTimer); entry.silenceWarningTimer = null; }
+    if (entry.silenceKillTimer) { clearTimeout(entry.silenceKillTimer); entry.silenceKillTimer = null; }
+    if (entry.wallClockTimer) { clearTimeout(entry.wallClockTimer); entry.wallClockTimer = null; }
+    if (entry.memoryPollTimer) { clearInterval(entry.memoryPollTimer); entry.memoryPollTimer = null; }
+  }
+
+  _checkMemory(agentId) {
+    const entry = this.#agents.get(agentId);
+    if (!entry || !entry.pid || entry.terminalReason) return;
+
+    try {
+      const rssKB = parseInt(execSync(`ps -o rss= -p ${entry.pid}`, { encoding: 'utf-8', timeout: 5000 }).trim(), 10);
+      const rssMB = rssKB / 1024;
+      if (rssMB > this.#memoryLimitMB) {
+        this._kill(agentId, 'memory_exceeded');
+      }
+    } catch {
+      // Process may have already exited — ignore
+    }
+  }
+}

package/server/agent-hooks.js

@@ -0,0 +1,102 @@
+/**
+ * SDK hook callbacks for the Agent Server.
+ *
+ * These are in-process JavaScript functions passed to query() — not shell
+ * scripts. They POST structured events to the api-server (port 3001), which
+ * feeds SessionManager and VisionServer, preserving all Phase 3 monitoring.
+ *
+ * Single source of truth for TOOL_CATEGORIES (previously duplicated in
+ * Terminal.jsx and vision-server.js).
+ */
+
+const API_SERVER = `http://127.0.0.1:${process.env.PORT || 3001}`;
+
+/** Semantic category for each Claude Code tool */
+export const TOOL_CATEGORIES = {
+  Read: 'reading', Glob: 'searching', Grep: 'searching',
+  Write: 'writing', Edit: 'writing', NotebookEdit: 'writing',
+  Bash: 'executing', Task: 'delegating', Skill: 'delegating',
+  WebFetch: 'fetching', WebSearch: 'searching',
+  TodoRead: 'reading', TodoWrite: 'writing',
+};
+
+async function post(path, body) {
+  try {
+    const res = await fetch(`${API_SERVER}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(5000),
+    });
+    return res;
+  } catch {
+    // api-server might not be ready yet — swallow silently
+  }
+}
+
+/**
+ * PostToolUse — fires after each successful tool execution.
+ * Sends tool name, input, and response to /api/agent/activity.
+ */
+export async function postToolUseHook(input) {
+  const response = input.tool_response;
+  const responseStr = typeof response === 'string'
+    ? response
+    : JSON.stringify(response);
+
+  await post('/api/agent/activity', {
+    tool: input.tool_name,
+    input: input.tool_input,
+    response: responseStr,
+    timestamp: new Date().toISOString(),
+  });
+
+  return { continue: true };
+}
+
+/**
+ * PostToolUseFailure — fires when a tool execution fails.
+ * Sends error details to /api/agent/error for severity classification.
+ */
+export async function postToolUseFailureHook(input) {
+  await post('/api/agent/error', {
+    tool: input.tool_name,
+    input: input.tool_input,
+    error: input.error,
+  });
+
+  return { continue: true };
+}
+
+/**
+ * SessionStart — fires at session startup or resume.
+ * Triggers SessionManager.startSession() via api-server.
+ */
+export async function sessionStartHook(input) {
+  await post('/api/session/start', {
+    source: input.source || 'startup',
+  });
+
+  return { continue: true };
+}
+
+/**
+ * SessionEnd — fires when Claude Code exits.
+ * Triggers SessionManager.endSession() and potentially journal generation.
+ */
+export async function sessionEndHook(input) {
+  await post('/api/session/end', {
+    reason: input.reason || 'completed',
+    transcriptPath: input.transcript_path || null,
+  });
+
+  return { continue: true };
+}
+
+/** Hook configuration object for query() options.hooks */
+export const HOOK_OPTIONS = {
+  PostToolUse: [{ matcher: '.*', hooks: [postToolUseHook] }],
+  PostToolUseFailure: [{ matcher: '.*', hooks: [postToolUseFailureHook] }],
+  SessionStart: [{ hooks: [sessionStartHook] }],
+  SessionEnd: [{ hooks: [sessionEndHook] }],
+};

package/server/agent-mcp.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// T2-F5 retirement shim. The agent_run capability moved to stratum-mcp's
+// stratum_agent_run tool. This file exists only to fail fast with a clear
+// message for users whose .mcp.json still references it. Re-running
+// `compose init` removes the stale entry.
+process.stderr.write(
+  'agent-mcp.js is retired (T2-F5). Use stratum_agent_run on the stratum MCP server.\n'
+  + 'Re-run `compose init` to remove the legacy entry from .mcp.json.\n'
+);
+process.exit(1);

package/server/agent-registry.js

@@ -0,0 +1,95 @@
+/**
+ * AgentRegistry — persistent tracker for spawned subagents.
+ *
+ * Tracks parent-child relationships between the main Claude Code session
+ * and spawned agents (compose-explorer, compose-architect, etc.).
+ * JSON file-backed, same pattern as SettingsStore.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+export class AgentRegistry {
+  #agents;
+  #file;
+
+  constructor(dataDir) {
+    this.#file = join(dataDir, 'agents.json');
+    this.#agents = new Map();
+    this._load();
+  }
+
+  register(agentId, { parentSessionId, agentType, prompt, pid }) {
+    const record = {
+      agentId,
+      parentSessionId: parentSessionId ?? null,
+      agentType: agentType ?? 'unknown',
+      prompt: (prompt ?? '').slice(0, 200),
+      status: 'running',
+      pid: pid ?? null,
+      startedAt: new Date().toISOString(),
+      completedAt: null,
+      exitCode: null,
+    };
+    this.#agents.set(agentId, record);
+    this._save();
+    return record;
+  }
+
+  complete(agentId, { status, exitCode }) {
+    const record = this.#agents.get(agentId);
+    if (!record) return null;
+    record.status = status;
+    record.exitCode = exitCode ?? null;
+    record.completedAt = new Date().toISOString();
+    this._save();
+    return record;
+  }
+
+  getChildren(parentSessionId) {
+    return [...this.#agents.values()].filter(a => a.parentSessionId === parentSessionId);
+  }
+
+  getAll() { return [...this.#agents.values()]; }
+  get(agentId) { return this.#agents.get(agentId) ?? null; }
+
+  /** COMP-AGT-1: Return all agents with status 'running'. */
+  getRunning() {
+    return [...this.#agents.values()].filter(a => a.status === 'running');
+  }
+
+  /** COMP-AGT-1: Update status and optional terminal reason for an agent. */
+  updateStatus(agentId, status, terminalReason) {
+    const record = this.#agents.get(agentId);
+    if (!record) return null;
+    record.status = status;
+    if (terminalReason) record.terminalReason = terminalReason;
+    if (status !== 'running') record.completedAt = new Date().toISOString();
+    this._save();
+    return record;
+  }
+
+  prune(keep = 50) {
+    const all = [...this.#agents.values()]
+      .sort((a, b) => new Date(b.startedAt) - new Date(a.startedAt));
+    const pruned = all.slice(keep);
+    for (const r of pruned) this.#agents.delete(r.agentId);
+    if (pruned.length > 0) this._save();
+  }
+
+  _load() {
+    try {
+      const data = JSON.parse(readFileSync(this.#file, 'utf-8'));
+      for (const r of data) this.#agents.set(r.agentId, r);
+    } catch { /* fresh start */ }
+  }
+
+  _save() {
+    try {
+      mkdirSync(dirname(this.#file), { recursive: true });
+      writeFileSync(this.#file, JSON.stringify([...this.#agents.values()], null, 2));
+    } catch (err) {
+      console.error('[agent-registry] Save failed:', err.message);
+    }
+  }
+}