monomind 2.0.2 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Monomind - Power toolkit for Claude Code. Autonomous agent orgs, codebase knowledge graph, keyword-routed specialist prompts, and 80+ slash commands. One init, then walk away.",
   "main": "dist/index.js",
   "type": "module",
@@ -60,15 +60,20 @@
     "v1:security": "npm run security:audit && npm run security:test"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.207",
     "@monoes/monobrowse": "^1.0.3",
     "@monoes/monograph": "^1.4.0",
+    "@noble/ed25519": "^2.1.0",
     "mammoth": "^1.12.0",
     "pdf-parse": "^2.4.5",
-    "semver": "^7.6.0"
+    "semver": "^7.6.0",
+    "ws": "^8.21.0",
+    "yaml": "^2.8.0",
+    "zod": "^3.25.0"
   },
   "overrides": {
     "hono": ">=4.12.21",
-    "ws": ">=8.20.1",
+    "ws": "$ws",
     "axios": ">=1.16.0",
     "qs": ">=6.15.2",
     "esbuild": ">=0.28.1",
@@ -137,8 +142,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.0.0",
     "vite": ">=8.0.16",
-    "vitest": "^4.1.4",
-    "zod": "^4.3.6"
+    "vitest": "^4.1.4"
   },
   "engines": {
     "node": ">=20.0.0"

package/packages/@monomind/cli/.claude/commands/mastermind/runorg.md

@@ -1,5 +1,9 @@
 <!-- Start a saved org as a persistent autonomous agent organization. The boss agent coordinates all roles; agents pick up tasks from a shared board and run until stopped. -->
 
+> **DEPRECATED (2026-07): superseded by `monomind org run <name>` (SDK org runtime v2).**
+> This prompt-orchestrated path has no delivery guarantees and no ground-truth event stream.
+> It remains only for orgs not yet migrated. New orgs MUST use the daemon.
+
 **If $ARGUMENTS is empty:** List saved orgs and display the following.
 
 ---

package/packages/@monomind/cli/.claude/helpers/control-start.cjs

@@ -12,6 +12,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawn } = require('child_process');
+const { claimLock, releaseLock } = require('./utils/fs-helpers.cjs');
 
 const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const STATUS_FILE = path.join(CWD, '.monomind', 'control.json');
@@ -105,6 +106,31 @@ function probeStatus(p) {
   });
 }
 
+const LOCK_FILE = path.join(CWD, '.monomind', 'control.lock');
+
+/**
+ * Atomically claim the spawn lock. Concurrent hook events (a busy session can
+ * fire dozens of control-starts at once) must not each spawn a server — the
+ * loser processes exit and let the winner's server come up. A stale lock
+ * (older than 30s) is broken and re-claimed.
+ *
+ * P2-25: previously this broke a stale lock via unlink-then-writeFileSync(wx),
+ * which is a TOCTOU race — a second process that also decided the lock was
+ * stale could unlink the FIRST process's freshly-claimed (non-stale) lock
+ * between that process's unlink and its own write, letting a third process
+ * then also claim it. `claimLock` (utils/fs-helpers.cjs) fixes this by
+ * breaking stale locks with an atomic rename-to-claim instead: only one
+ * racing process can win the rename, and a loser retries from the top
+ * rather than proceeding as if it owns the lock.
+ */
+function claimSpawnLock() {
+  return claimLock(LOCK_FILE, 30_000);
+}
+
+function releaseSpawnLock() {
+  releaseLock(LOCK_FILE);
+}
+
 async function main() {
   // If already running, do nothing
   const status = readStatus();
@@ -125,6 +151,21 @@ async function main() {
     }
   }
 
+  if (!claimSpawnLock()) {
+    process.stdout.write('[control] another control-start is already spawning the server — skipping\n');
+    process.exit(0);
+  }
+
+  // Test hook: exercise the full flow without leaving a real detached server
+  // behind (the test suite spawns this script dozens of times per run — real
+  // spawns leaked hundreds of orphan servers on isolated ports).
+  if (process.env.MONOMIND_CONTROL_NO_SPAWN === '1') {
+    writeStatus(process.pid, DEFAULT_PORT);
+    process.stdout.write(`[control] started Neural Control Room on port ${DEFAULT_PORT} (pid ${process.pid}) [no-spawn]\n`);
+    releaseSpawnLock();
+    process.exit(0);
+  }
+
   const { cmd, args, usePort } = findCliPath();
   // server.mjs accepts port as second positional arg; CLI uses 'ui --no-open --port N'
   const allArgs = usePort
@@ -159,9 +200,9 @@ async function main() {
     });
   }
 
-  // Give the server up to ~3 s to start, then confirm the actual port.
+  // Give the server up to ~10 s to start, then confirm the actual port.
   async function confirmPort() {
-    for (let attempt = 0; attempt < 6; attempt++) {
+    for (let attempt = 0; attempt < 20; attempt++) {
       await new Promise(r => setTimeout(r, 500));
       for (let delta = 0; delta <= 10; delta++) {
         const p = DEFAULT_PORT + delta;
@@ -174,11 +215,15 @@ async function main() {
         }
       }
     }
-    // Server didn't respond in time — leave control.json as-is (best-effort)
-    process.stdout.write('[control] server did not respond within 3 s — control.json may have wrong port\n');
+    // Server never became reachable on any expected port — kill the child
+    // rather than leave an orphan bound to some port nothing will ever read.
+    // The next session-start simply retries.
+    try { process.kill(child.pid, 'SIGTERM'); } catch { /* already gone */ }
+    try { fs.unlinkSync(STATUS_FILE); } catch { /* ignore */ }
+    process.stdout.write('[control] server did not respond within 10 s — killed orphan, will retry next session\n');
   }
 
-  confirmPort().catch(() => {}).finally(() => process.exit(0));
+  confirmPort().catch(() => {}).finally(() => { releaseSpawnLock(); process.exit(0); });
 }
 
 main().catch(() => process.exit(0));

package/packages/@monomind/cli/.claude/helpers/event-logger.cjs

@@ -22,15 +22,36 @@ safety.unref();
 
 const MAX_STDIN = 1024 * 1024; // 1 MiB
 
+// P3-16: mirrors hook-handler.cjs's readStdin — byte-counted, discard-whole-
+// payload-on-overflow. The old version did `if (data.length < MAX_STDIN)
+// data += c`, which silently DROPPED characters once the cap was hit instead
+// of aborting the read, so an oversized payload produced truncated, invalid
+// JSON that then failed JSON.parse downstream with the whole event (and its
+// toolName/sessionId attribution) discarded anyway — just with extra steps
+// and no signal as to why. Discarding the entire payload up front (with a
+// logged, flagged event) is equivalent in outcome but honest about it.
 function readStdin() {
   if (process.stdin.isTTY) return Promise.resolve('');
   return new Promise((resolve) => {
     let data = '';
-    const t = setTimeout(() => { process.stdin.pause(); resolve(data); }, 800);
+    let byteCount = 0;
+    let truncated = false;
+    const t = setTimeout(() => { process.stdin.pause(); resolve({ data, truncated }); }, 800);
     process.stdin.setEncoding('utf8');
-    process.stdin.on('data', c => { if (data.length < MAX_STDIN) data += c; });
-    process.stdin.on('end', () => { clearTimeout(t); resolve(data); });
-    process.stdin.on('error', () => { clearTimeout(t); resolve(data); });
+    process.stdin.on('data', c => {
+      if (truncated) return;
+      byteCount += Buffer.byteLength(c, 'utf8');
+      if (byteCount > MAX_STDIN) {
+        truncated = true;
+        process.stdin.pause();
+        clearTimeout(t);
+        resolve({ data: '', truncated: true }); // discard oversized input, same as hook-handler.cjs
+        return;
+      }
+      data += c;
+    });
+    process.stdin.on('end', () => { clearTimeout(t); resolve({ data, truncated }); });
+    process.stdin.on('error', () => { clearTimeout(t); resolve({ data, truncated }); });
     process.stdin.resume();
   });
 }
@@ -60,7 +81,14 @@ function forwardToDashboard(entry) {
 }
 
 async function main() {
-  const raw = await readStdin();
+  const stdinResult = await readStdin();
+  const raw = stdinResult.data;
+  const stdinTruncated = stdinResult.truncated;
+  if (stdinTruncated) {
+    // Oversized payload was discarded whole (see readStdin) — log it so the
+    // drop is visible instead of silently vanishing as a JSON.parse failure.
+    console.error('[event-logger] stdin payload exceeded ' + MAX_STDIN + ' bytes; discarded (event=' + eventType + ')');
+  }
   let payload = {};
   try { payload = JSON.parse(raw); } catch {}
 
@@ -80,6 +108,7 @@ async function main() {
     toolResult: payload.toolResult || payload.tool_result || undefined,
     message: payload.message || payload.notification || payload.prompt || undefined,
     raw: (raw.length < 4096) ? payload : undefined,
+    truncated: stdinTruncated || undefined,
   };
 
   // Remove undefined keys
@@ -113,6 +142,13 @@ async function main() {
     fs.appendFileSync(allLog, JSON.stringify(entry) + '\n');
   } catch {}
 
+  // Rotation — event logs (daily + per-session) accumulate forever with no
+  // cleanup otherwise. Cheap: single readdir + stat pass, only on session-start
+  // (once per session, not per-event) so normal hook latency is unaffected.
+  if (eventType === 'session-start') {
+    rotateEventLogs(eventsDir);
+  }
+
   // Write to per-session log
   if (sessionId !== 'unknown') {
     try {
@@ -148,8 +184,75 @@ async function main() {
     forwardToDashboard(entry);
   }
 
+  // Detect route changes and worker metric updates by mtime and forward them too.
+  // These aren't Claude Code hook events — they're file writes from route-handler.cjs
+  // and the @monomind/hooks workers respectively — so we poll cheaply on every hook invocation.
+  forwardFileChanges(monoDir, CWD);
+
   clearTimeout(safety);
   process.exit(0);
 }
 
-main().catch(() => process.exit(0));
+function forwardFileChanges(monoDir, workDir) {
+  try {
+    const cachePath = path.join(monoDir, 'dashboard-watch-cache.json');
+    let cache = {};
+    try { cache = JSON.parse(fs.readFileSync(cachePath, 'utf8')); } catch {}
+    let changed = false;
+
+    // Route changes (.monomind/last-route.json, written every prompt by route-handler.cjs)
+    const routePath = path.join(workDir, '.monomind', 'last-route.json');
+    try {
+      const routeMtime = fs.statSync(routePath).mtimeMs;
+      if (routeMtime !== cache.routeMtime) {
+        cache.routeMtime = routeMtime;
+        changed = true;
+        let route = null;
+        try { route = JSON.parse(fs.readFileSync(routePath, 'utf8')); } catch {}
+        forwardToDashboard({ hookType: 'route-change', ts: Date.now(), route });
+      }
+    } catch {}
+
+    // Worker-complete: newest mtime among .monomind/metrics/*.json (written by @monomind/hooks workers)
+    const metricsDir = path.join(workDir, '.monomind', 'metrics');
+    try {
+      const files = fs.readdirSync(metricsDir).filter(f => f.endsWith('.json') && !f.startsWith('.'));
+      let latestFile = null;
+      let latestMtime = cache.metricsMtime || 0;
+      for (const f of files) {
+        const mtime = fs.statSync(path.join(metricsDir, f)).mtimeMs;
+        if (mtime > latestMtime) { latestMtime = mtime; latestFile = f; }
+      }
+      if (latestFile) {
+        cache.metricsMtime = latestMtime;
+        changed = true;
+        forwardToDashboard({ hookType: 'daemon-complete', ts: Date.now(), metric: latestFile.replace(/\.json$/, '') });
+      }
+    } catch {}
+
+    if (changed) fs.writeFileSync(cachePath, JSON.stringify(cache));
+  } catch {}
+}
+
+// Delete any daily or per-session event log whose mtime is older than
+// maxAgeMs (default 14 days). Single readdir + stat pass — no recursion.
+function rotateEventLogs(eventsDir, maxAgeMs) {
+  maxAgeMs = maxAgeMs || 14 * 24 * 60 * 60 * 1000;
+  try {
+    const cutoff = Date.now() - maxAgeMs;
+    const entries = fs.readdirSync(eventsDir).filter(f => !f.startsWith('._'));
+    for (const f of entries) {
+      if (!f.endsWith('.jsonl')) continue;
+      const full = path.join(eventsDir, f);
+      try {
+        if (fs.statSync(full).mtimeMs < cutoff) fs.unlinkSync(full);
+      } catch {}
+    }
+  } catch {}
+}
+
+module.exports = { rotateEventLogs };
+
+if (require.main === module) {
+  main().catch(() => process.exit(0));
+}

package/packages/@monomind/cli/.claude/helpers/graphify-freshen.cjs

@@ -5,6 +5,7 @@ const path = require('path');
 const fs = require('fs');
 const { spawn } = require('child_process');
 const { pathToFileURL } = require('url');
+const { claimLock } = require('./utils/fs-helpers.cjs');
 
 const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const graphDir = path.join(projectDir, '.monomind', 'graph');
@@ -91,20 +92,18 @@ if (fs.existsSync(dbPath)) {
 }
 
 // Skip if another build is already in progress (avoids SQLite BUSY on concurrent init + session-start)
+// P2-24: claim atomically (wx-create) instead of statSync-then-writeFileSync
+// — two concurrent freshen triggers can both cross the same write-count
+// threshold from parallel hook events, and a plain read-check-write lets
+// both pass the check and both spawn a detached rebuild child. claimLock
+// uses the same TOCTOU-safe stale-lock-break (atomic rename-to-claim) as
+// control-start.cjs's spawn lock (see P2-25) — a lock older than 5 minutes
+// is treated as abandoned and safely reclaimed.
 const lockPath = path.join(graphDir, 'build.lock');
-const now = Date.now();
-try {
-  const stat = fs.statSync(lockPath);
-  // Stale lock older than 5 minutes — remove it and proceed
-  if (now - stat.mtimeMs < 5 * 60 * 1000) {
-    console.log('[graph] build already in progress — skipping');
-    process.exit(0);
-  }
-  fs.unlinkSync(lockPath);
-} catch { /* lock does not exist — proceed */ }
-
-// Write lock file; the build process removes it on completion
-try { fs.writeFileSync(lockPath, String(process.pid)); } catch { /* non-fatal */ }
+if (!claimLock(lockPath, 5 * 60 * 1000)) {
+  console.log('[graph] build already in progress — skipping');
+  process.exit(0);
+}
 
 // Spawn a detached node process to run buildAsync from @monoes/monograph (ESM).
 // After the build, VACUUM the DB if it has >50% bloat (reclaim space from
@@ -113,18 +112,21 @@ const dbPathStr = JSON.stringify(path.join(projectDir, '.monomind', 'monograph.d
 const script = `
 import { buildAsync } from ${JSON.stringify(pathToFileURL(entryPoint).href)};
 import { unlinkSync, statSync } from 'fs';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 try {
   await buildAsync(${JSON.stringify(projectDir)});
   // Vacuum if bloat ratio is high — keeps openDb fast over time.
   try {
     const dbPath = ${dbPathStr};
     const fileMB = statSync(dbPath).size / 1024 / 1024;
+    // execFileSync with array argv — no shell involved, so a project
+    // directory name containing '"' or '$(...)' cannot break out and
+    // execute arbitrary commands (P3-8).
     const liveMB = parseInt(
-      execSync('sqlite3 "' + dbPath + '" "SELECT SUM(pgsize)/1024/1024 FROM dbstat;"',
-        { encoding: 'utf-8' }).trim(), 10);
+      execFileSync('sqlite3', [dbPath, 'SELECT SUM(pgsize)/1024/1024 FROM dbstat;'],
+        { encoding: 'utf-8', timeout: 30000 }).trim(), 10);
     if (fileMB > 100 && liveMB / fileMB < 0.5) {
-      execSync('sqlite3 "' + dbPath + '" "VACUUM;"', { timeout: 120000 });
+      execFileSync('sqlite3', [dbPath, 'VACUUM;'], { timeout: 120000 });
     }
   } catch (_) {}
 } finally {

package/packages/@monomind/cli/.claude/helpers/handlers/agent-start-handler.cjs

@@ -4,6 +4,8 @@
 
 const path = require('path');
 const fs = require('fs');
+const { purgeStaleRegistrations } = require('../utils/agent-registrations.cjs');
+const { cleanEntries, atomicWriteFileSync, withLock } = require('../utils/fs-helpers.cjs');
 
 module.exports = {
   handle: async function(hCtx) {
@@ -18,41 +20,65 @@ module.exports = {
       fs.mkdirSync(regDir, { recursive: true });
       const id = Date.now() + '-' + Math.random().toString(36).slice(2, 6);
       const regFile = path.join(regDir, 'agent-' + id + '.json');
+      // P3-15: also stamp the agent's type/slug so handlePostTask (task-handler.cjs)
+      // can correlate a completion event back to THIS registration instead of
+      // blindly popping the oldest file — the registration previously carried no
+      // identity beyond a random id, so post-task had nothing to match against.
+      // Same field precedence as the last-dispatch.json write below, computed
+      // early so both writers agree on the agent's identity.
+      const MAX_TYPE_LEN = 128;
+      const agentType = String(hookInput.subagent_type || hookInput.agentType || hookInput.agent_type || hookInput.agentSlug || 'unknown').slice(0, MAX_TYPE_LEN);
       fs.writeFileSync(regFile, JSON.stringify({
         agentId: id,
+        agentType: agentType,
         startedAt: new Date().toISOString(),
         pid: process.pid,
       }));
+      // Purge stragglers older than 30 min on every agent-start too — not just
+      // on TeammateIdle/TaskCompleted (task-handler.cjs) — since sessions that
+      // never emit those events would otherwise leak registrations forever.
+      const activeAfterPurge = purgeStaleRegistrations(regDir);
       // Refresh swarm-activity.json within the 5-min staleness window.
       const activityDir = path.join(CWD, '.monomind', 'metrics');
       fs.mkdirSync(activityDir, { recursive: true });
       const activityPath = path.join(activityDir, 'swarm-activity.json');
       const MAX_AGENTS = 1000;
-      const active = Math.min(fs.readdirSync(regDir).filter(f => f.endsWith('.json')).length, MAX_AGENTS);
-      // Preserve lastActive (peak) so statusline shows non-zero after completion.
-      let prevLastActive = 0;
-      try {
-        const MAX_ACTIVITY = 64 * 1024; // 64 KiB
-        var actStat = fs.statSync(activityPath);
-        if (actStat.size <= MAX_ACTIVITY) {
-          prevLastActive = (JSON.parse(fs.readFileSync(activityPath, 'utf-8'))?.swarm?.lastActive) || 0;
-        }
-      } catch { /* ignore */ }
-      fs.writeFileSync(activityPath, JSON.stringify({
-        timestamp: new Date().toISOString(),
-        swarm: {
-          active: active > 0,
-          agent_count: active,
-          coordination_active: active > 0,
-          lastActive: Math.max(active, prevLastActive),
-        },
-      }));
+      const active = Math.min(
+        activeAfterPurge != null ? activeAfterPurge : cleanEntries(regDir, f => f.endsWith('.json')).length,
+        MAX_AGENTS
+      );
+      // P2-21: swarm-activity.json is written by both this handler and
+      // task-handler.cjs's handlePostTask, concurrently (Claude Code fires
+      // hook events for parallel tool calls in one message). The old
+      // read-prevLastActive-then-write was a lost-update race — two
+      // processes could both read the same prevLastActive before either
+      // wrote, so whichever wrote last silently erased the other's peak.
+      // Share one lock file with task-handler.cjs so the read-merge-write
+      // cycle is a single critical section across both writers.
+      withLock(activityPath + '.lock', function() {
+        // Preserve lastActive (peak) so statusline shows non-zero after completion.
+        let prevLastActive = 0;
+        try {
+          const MAX_ACTIVITY = 64 * 1024; // 64 KiB
+          var actStat = fs.statSync(activityPath);
+          if (actStat.size <= MAX_ACTIVITY) {
+            prevLastActive = (JSON.parse(fs.readFileSync(activityPath, 'utf-8'))?.swarm?.lastActive) || 0;
+          }
+        } catch { /* ignore */ }
+        atomicWriteFileSync(activityPath, JSON.stringify({
+          timestamp: new Date().toISOString(),
+          swarm: {
+            active: active > 0,
+            agent_count: active,
+            coordination_active: active > 0,
+            lastActive: Math.max(active, prevLastActive),
+          },
+        }));
+      }, 5000);
 
       // Write last-dispatch.json so the route handler can suppress redundant
       // suggestions on the next turn when the same agent type is recommended.
-      const MAX_TYPE_LEN = 128;
       const MAX_DESC_LEN = 500;
-      const agentType = String(hookInput.subagent_type || hookInput.agentType || hookInput.agent_type || hookInput.agentSlug || 'unknown').slice(0, MAX_TYPE_LEN);
       const agentDesc = String(hookInput.description || hookInput.prompt_description || '').slice(0, MAX_DESC_LEN);
       fs.writeFileSync(
         path.join(CWD, '.monomind', 'last-dispatch.json'),
@@ -87,13 +113,19 @@ module.exports = {
       if (_hooksModule && _hooksModule.executeHooks && _hooksModule.HookEvent) {
         var agentTypeBridge = String(hookInput.subagent_type || hookInput.agentType || hookInput.agent_type || hookInput.agentSlug || 'unknown');
         var agentDescBridge = String(hookInput.description || hookInput.prompt_description || '');
-        _hooksModule.executeHooks(_hooksModule.HookEvent.AgentSpawn, {
-          agent: {
-            id: hookInput.agentId || hookInput.agent_id || (agentTypeBridge + '-' + Date.now()),
-            type: agentTypeBridge,
-            description: agentDescBridge.slice(0, 500),
-          },
-        }, { continueOnError: true, timeout: 1500 }).catch(function() {});
+        // Must be awaited (bounded by runWithTimeout, 1500ms) — hook-handler.cjs's
+        // main().finally(() => process.exit(...)) reaps any unawaited fire-and-forget
+        // promise before it does real I/O. See session-restore-handler.cjs's
+        // SessionStart bridge for the reference pattern this mirrors.
+        await hCtx.runWithTimeout(function() {
+          return _hooksModule.executeHooks(_hooksModule.HookEvent.AgentSpawn, {
+            agent: {
+              id: hookInput.agentId || hookInput.agent_id || (agentTypeBridge + '-' + Date.now()),
+              type: agentTypeBridge,
+              description: agentDescBridge.slice(0, 500),
+            },
+          }, { continueOnError: true, timeout: 1500 });
+        }, '@monomind/hooks.AgentSpawn');
       }
     } catch (e) { /* non-fatal */ }
   },

package/packages/@monomind/cli/.claude/helpers/handlers/capture-handler.cjs

@@ -21,9 +21,39 @@ const fs = require('fs');
 const path = require('path');
 const http = require('http');
 const os = require('os');
+const crypto = require('crypto');
+const { appendJsonlWithRotation } = require('../utils/fs-helpers.cjs');
 
 const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const CAPTURE_DIR = path.join(CWD, '.monomind', 'capture');
+const SNAP_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour — orphaned snapshots are cleaned up this old
+
+// P2-23: derive a stable key for a subagent invocation from whatever
+// identifying info Claude Code actually gives us in the hook payload.
+// `transcript_path` is the one field that's both present on SubagentStart
+// and SubagentStop AND unique per-subagent (each subagent gets its own
+// transcript file, distinct from the parent session's) — session_id alone
+// is shared by every concurrently-running subagent in the same team, so it
+// can't disambiguate which stop event belongs to which start.
+function subagentKey(hookInput) {
+  var raw = hookInput && (hookInput.transcript_path || hookInput.transcriptPath);
+  if (!raw) return null;
+  return crypto.createHash('md5').update(String(raw)).digest('hex').slice(0, 16);
+}
+
+// Delete snap-*.json files older than SNAP_MAX_AGE_MS — orphaned when a
+// SubagentStop never arrived (crash, forced-stop) or was matched to a
+// different snapshot before keyed matching existed.
+function cleanupStaleSnaps() {
+  try {
+    var files = fs.readdirSync(CAPTURE_DIR).filter(f => f.startsWith('snap-') && f.endsWith('.json') && !f.startsWith('._'));
+    var now = Date.now();
+    for (var i = 0; i < files.length; i++) {
+      var p = path.join(CAPTURE_DIR, files[i]);
+      try { if (now - fs.statSync(p).mtimeMs > SNAP_MAX_AGE_MS) fs.unlinkSync(p); } catch { /* ignore */ }
+    }
+  } catch { /* CAPTURE_DIR may not exist yet */ }
+}
 
 // ─── Helpers ────────────────────────────────────────────────────────────────
 
@@ -46,7 +76,7 @@ function snapshotJSONLFiles() {
   if (!fs.existsSync(claudeDir)) return [];
   try {
     return fs.readdirSync(claudeDir)
-      .filter(f => f.endsWith('.jsonl'))
+      .filter(f => f.endsWith('.jsonl') && !f.startsWith('._'))
       .map(f => {
         try { return { name: f, size: fs.statSync(path.join(claudeDir, f)).size }; }
         catch { return { name: f, size: 0 }; }
@@ -170,6 +200,7 @@ function emitEvent(event) {
 
 async function handleSubagentStart(hookInput) {
   fs.mkdirSync(CAPTURE_DIR, { recursive: true });
+  cleanupStaleSnaps();
 
   const snapshot = snapshotJSONLFiles();
   const agentType = String(
@@ -190,10 +221,19 @@ async function handleSubagentStart(hookInput) {
   }
   const activeSess = getActiveSession(activeRun);
 
-  // Write snapshot to FIFO queue — subagent-stop pops the oldest
+  // P2-23: key the snapshot filename by transcript_path when available so
+  // SubagentStop can look up the EXACT matching snapshot instead of
+  // FIFO-popping the lexicographically-oldest one — under real concurrency
+  // (multiple subagents stopping in close succession) FIFO pop can match a
+  // stop event to the wrong subagent's snapshot. Falls back to the old
+  // timestamp+random naming when transcript_path isn't present in the
+  // payload, so SubagentStop's FIFO fallback path still has something to
+  // match against.
+  const subKey = subagentKey(hookInput);
   const snapFile = path.join(
     CAPTURE_DIR,
-    'snap-' + Date.now() + '-' + Math.random().toString(36).slice(2, 6) + '.json'
+    subKey ? 'snap-' + subKey + '.json'
+           : 'snap-' + Date.now() + '-' + Math.random().toString(36).slice(2, 6) + '.json'
   );
   const leanModePath = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), '.monomind/state/monolean-mode');
   let leanMode = null;
@@ -235,18 +275,31 @@ async function handleSubagentStart(hookInput) {
 
 async function handleSubagentStop(hookInput) {
   fs.mkdirSync(CAPTURE_DIR, { recursive: true });
-
-  // Pop oldest snapshot (FIFO — matches the agent that just finished)
-  const snapFiles = fs.readdirSync(CAPTURE_DIR)
-    .filter(f => f.startsWith('snap-') && f.endsWith('.json'))
-    .sort(); // lexicographic = timestamp order
-
-  if (snapFiles.length === 0) {
-    console.log('[CAPTURE:stop] No snapshot to diff — skipping');
-    return;
+  cleanupStaleSnaps();
+
+  // P2-23: prefer the exact keyed snapshot (see subagentKey/handleSubagentStart)
+  // over FIFO-popping the oldest snap-*.json — FIFO misattributes the stop
+  // event to the wrong subagent whenever multiple subagents stop in close
+  // succession. Fall back to FIFO only when this event's payload carries no
+  // transcript_path (older Claude Code versions / unexpected payload shape).
+  const subKey = subagentKey(hookInput);
+  let snapPath = null;
+  if (subKey) {
+    const keyedPath = path.join(CAPTURE_DIR, 'snap-' + subKey + '.json');
+    if (fs.existsSync(keyedPath)) snapPath = keyedPath;
+  }
+  if (!snapPath) {
+    const snapFiles = fs.readdirSync(CAPTURE_DIR)
+      .filter(f => f.startsWith('snap-') && f.endsWith('.json') && !f.startsWith('._'))
+      .sort(); // lexicographic = timestamp order (FIFO fallback)
+    if (snapFiles.length === 0) {
+      console.log('[CAPTURE:stop] No snapshot to diff — skipping');
+      return;
+    }
+    snapPath = path.join(CAPTURE_DIR, snapFiles[0]);
+    console.log('[CAPTURE:stop] no transcript_path/keyed snapshot — falling back to FIFO match');
   }
 
-  const snapPath = path.join(CAPTURE_DIR, snapFiles[0]);
   let snap;
   try { snap = JSON.parse(fs.readFileSync(snapPath, 'utf8')); } catch {
     try { fs.unlinkSync(snapPath); } catch {}
@@ -294,11 +347,13 @@ async function handleSubagentStop(hookInput) {
 
   if (!org && !session) {
     // No active org or session — log to general capture file only
+    // P2-26: rotate — was a pure appendFileSync with no cap, unlike
+    // intelligence-outcomes.jsonl (500-line cap).
     const genLog = path.join(CAPTURE_DIR, 'unattributed.jsonl');
-    fs.appendFileSync(genLog, JSON.stringify({
+    appendJsonlWithRotation(genLog, JSON.stringify({
       ts: Date.now(), agentType, tokens_in: totalTin, tokens_out: totalTout,
       cost_usd: costUsd, capturedFiles, summary: summary.slice(0, 200),
-    }) + '\n');
+    }), 500);
     return;
   }
 
@@ -355,9 +410,11 @@ async function handleSubagentStop(hookInput) {
   // ── Persist transcript reference to run directory ─────────────────────────
   if (capturedFiles.length > 0 && org && runId) {
     const runDir = path.join(CWD, '.monomind', 'orgs', org, 'runs');
-    fs.mkdirSync(runDir, { recursive: true });
     const capLog = path.join(runDir, runId + '-captures.jsonl');
-    fs.appendFileSync(capLog, JSON.stringify({
+    // P2-26: rotate — was a pure appendFileSync with no cap. A long-running
+    // org loop can spawn far more than 500 agents over its lifetime, so
+    // this uses the same 500-line cap convention as the other JSONL logs.
+    appendJsonlWithRotation(capLog, JSON.stringify({
       type: 'agent:capture',
       org, runId, session,
       agentType,
@@ -368,7 +425,7 @@ async function handleSubagentStop(hookInput) {
       capturedFiles,
       claudeProjectDir: claudeDir,
       ts: Date.now(),
-    }) + '\n');
+    }), 500);
   }
 
   // ── Wire captured interaction into EpisodicStore ────