monomind 2.0.3 → 2.1.3

package/README.md

@@ -5,8 +5,8 @@
 <h1 align="center">Monomind</h1>
 
 <p align="center">
-  <strong>Hire an AI team. Set a goal. Walk away.</strong><br/>
-  Autonomous Claude Code orchestration with persistent memory, self-coordinating agent orgs, and a codebase knowledge graph.
+  <strong>An open-source MCP server that extends Claude Code with a codebase knowledge graph, persistent memory, and multi-agent coordination.</strong><br/>
+  MIT licensed &middot; Fully local &middot; No data leaves your machine
 </p>
 
 <p align="center">
@@ -30,126 +30,105 @@
 
 ## What is Monomind?
 
-Claude Code is already powerful. Monomind makes it **run itself**.
+Monomind is an **open-source CLI and MCP server** that plugs into Claude Code via the standard [Model Context Protocol](https://modelcontextprotocol.io/). It adds capabilities that Claude Code doesn't ship with out of the box:
 
-Install once. Wire it into Claude Code. Then instead of prompting Claude to do individual tasks, you tell Monomind what outcome you want — and it assembles a team, coordinates the work, and delivers.
+- **Codebase knowledge graph** — tree-sitter parses your code into a SQLite-backed graph of files, functions, classes, and their relationships. Query imports, callers, and blast radius before making changes.
+- **Persistent memory** — a JSON pattern store with episodic recall that survives across sessions. Agents and orgs share context without re-prompting.
+- **Multi-agent coordination** — in-session, spawn ad-hoc agent teams via Claude Code's Task tool; for persistent background work, `monomind org run` starts a real SDK-backed daemon with policy-gated role agents and a live dashboard.
+- **Reusable slash commands** — 30+ development workflows (build, review, debug, TDD, architecture) available as `/mastermind:*` commands inside Claude Code.
 
 ```bash
-# Assemble an AI content team and let it run
-/mastermind:createorg content-team "publish 3 SEO-optimized posts per week"
-/mastermind:runorg --org content-team
-
-# Or run the autonomous code improvement loop
-/mastermind:autodev --tillend --focus security
+npm install -g monomind        # MIT licensed, 0 external API calls
+cd your-project && monomind init
+claude mcp add monomind npx monomind mcp start
 ```
 
-That's it. Come back later.
+### Trust & Security
+
+| Concern | Answer |
+|---|---|
+| **License** | [MIT](LICENSE) — use it however you want |
+| **Data privacy** | Everything runs locally. No telemetry, no phone-home, no external API calls from Monomind itself. Your code stays on your machine. |
+| **Dependencies** | Standard npm packages (tree-sitter, sql.js, zod). No native binaries. No post-install scripts that download code. |
+| **Permissions** | Registers as an MCP server — Claude Code controls what tools are available and prompts you before executing anything sensitive. |
+| **Source** | Fully open. Read every line at [github.com/monoes/monomind](https://github.com/monoes/monomind). |
+| **Maintenance** | Active development, regular releases on npm. |
 
 ---
 
 ## 🏢 Autonomous Organizations
 
-> **This is the headline feature.** Build a persistent AI organization — roles, hierarchy, shared task board — and start it as a background daemon that runs without you.
+> **This is the headline feature.** `monomind org run` starts a persistent, SDK-backed daemon that runs an autonomous agent organization — roles, hierarchy, policy-gated tool access, a live dashboard — until you stop it.
 
 ### The idea
 
-Every business function needs a team. Monomind lets you design that team in one command, then run it forever. The org persists across sessions. It checkpoints, recovers from failures, and coordinates its agents through a shared task board — all automatically.
+Every business function needs a team. Define the org once as a JSON file — goal, roles, who reports to whom, per-role tool/file/budget policy — then run it as a real background daemon backed by the Claude Agent SDK. It persists across sessions, serves a live WebSocket dashboard, and can discover and message other Monomind orgs running on the same machine.
 
 ```mermaid
 flowchart TD
     U(["You"])
-    CO["/mastermind:createorg\nDefine goal + roles"]
-    RO["/mastermind:runorg\nStart daemon"]
-    BOSS["Boss Agent\ncoordinator"]
-    W["Writer\nContent Creator"]
+    DEF["org.json\nGoal + roles + policy"]
+    RUN["monomind org run\nStart SDK daemon"]
+    BOSS["Boss Agent\nAgent SDK session"]
+    W["Writer"]
     S["SEO Specialist"]
     R["Reviewer"]
-    M["Growth Marketer"]
-    BOARD[("Shared\nTask Board")]
-    MEM[("Persistent\nMemory")]
+    DASH[("Live Dashboard\n:4243")]
+    XORG[("Other orgs\ncross-process")]
 
-    U --> CO --> RO --> BOSS
+    U --> DEF --> RUN --> BOSS
     BOSS -->|spawns| W
     BOSS -->|spawns| S
     BOSS -->|spawns| R
-    BOSS -->|spawns| M
-    BOSS <-->|claims + reports| BOARD
-    W <-->|stores output| MEM
-    S <-->|reads context| MEM
+    RUN <-->|serves| DASH
+    RUN <-.->|--cross-process| XORG
 
     style BOSS fill:#00D2AA22,stroke:#00D2AA
-    style BOARD fill:#F59E0B22,stroke:#F59E0B
-    style MEM fill:#8B5CF622,stroke:#8B5CF6
-```
-
-### Two commands to a running org
-
-**Step 1 — Design it:**
-
+    style DASH fill:#F59E0B22,stroke:#F59E0B
+    style XORG fill:#8B5CF622,stroke:#8B5CF6
 ```
-/ mastermind:createorg content-team
-  "Build and publish 3 blog posts per week on AI dev tools"
-
-Deriving roles from goal...
-
-╔ ORG: content-team
-║ TOPOLOGY: star (5 roles)
 
-  boss      → coordinator
-  writer    → Content Creator
-  reviewer  → reviewer
-  marketer  → Growth Hacker
-  seo       → SEO Specialist
+### Run one
 
-Type "go" to save, or describe changes.
-→ go
+```bash
+# .monomind/orgs/<name>.json defines the org: goal, roles, policy.
+# See .monomind/orgs/sample-team.json in a fresh `monomind init` for a working example.
 
-✓ Saved .monomind/orgs/content-team.json
-  → Run: /mastermind:runorg --org content-team
-```
+monomind org run content-team --task "Build and publish 3 blog posts per week"
 
-**Step 2 — Start it:**
+# ✓ Live dashboard: http://localhost:4243
+# ✓ Boss agent (Claude Agent SDK session) spawns, reads the org goal,
+#   assigns work to role agents, coordinates until the task completes
+#   or you stop it.
 
-```bash
-/mastermind:runorg --org content-team
-
-# Boss agent spawns in background
-# Coordinates all roles via shared task board
-# Checkpoints every 30 minutes
-# Loops until you stop it
+monomind org status content-team    # runtime state
+monomind org stop content-team      # request a graceful stop
+monomind org list                   # every org + status
 ```
 
 ### What runs under the hood
 
 | What | How |
 |---|---|
-| **Boss agent** | Coordinator type, no supervisor — owns the goal |
-| **Role agents** | Spawned on demand, specialized by task type |
-| **Task board** | Todo → Doing → Done, shared across all agents |
-| **Memory** | All output stored in an org-scoped memory namespace |
-| **Checkpoint** | State saved every 30 min — survives crashes and restarts |
-| **Governance** | `auto` (free), `board` (approve sensitive), `strict` (approve all external actions) |
-
-### Topology is auto-derived
-
-```mermaid
-graph LR
-    A["1-3 roles"] -->|mesh| B["All-to-all\ndirect comms"]
-    C["4-6 roles"] -->|star| D["Boss to workers\nfan-out"]
-    E["7+ roles"] -->|hierarchical| F["Boss to leads to workers\nmiddle management"]
-```
+| **OrgDaemon** | Hosts one or more orgs in a single process; real Claude Agent SDK sessions per role, not simulated |
+| **PolicyEngine** | Per-role gates on tool access, file read/write scope, web access, token budget — enforced, with a full audit trail |
+| **Live dashboard** | WebSocket-served at `:4243` by default (`--port` to change, `--serve=false` to disable) |
+| **Cross-process comms** | `--cross-process` (default on) lets orgs on different `monomind` processes/projects discover and message each other |
+| **Scheduling** | `monomind org serve` hosts orgs whose definition has a `schedule` field, running them on interval |
 
 ### Org management commands
 
 ```bash
-/mastermind:createorg <name> "<goal>"   # design org from a goal
-/mastermind:runorg --org <name>         # start as background daemon
-/mastermind:orgs                        # list all orgs + status
-/mastermind:orgstatus --org <name>      # detailed status for one org
-/mastermind:stoporg --org <name>        # stop a running org
-/mastermind:approve                     # review pending approval requests
+monomind org run <name> [--task "..."] [--port N] [--cross-process]  # start a daemon
+monomind org stop <name>            # request a running org to stop
+monomind org status [name]          # runtime state for one or all orgs
+monomind org list                   # list every org + status
+monomind org serve [--port N]       # host-only mode, runs scheduled orgs
+monomind org delete <name>          # remove an org
 ```
 
+> **Note:** the older `/mastermind:createorg` + `/mastermind:runorg` prompt-orchestrated flow is deprecated — it has no delivery guarantees or ground-truth event stream. It still runs for orgs not yet migrated, but new orgs should use `monomind org run` directly against a hand-authored `.monomind/orgs/<name>.json`.
+
 ---
 
 ## ⚡ The Autonomous Build Loop
@@ -206,11 +185,11 @@ claude mcp add monomind npx monomind mcp start
 monomind doctor --fix
 ```
 
-Open Claude Code. You now have 80+ slash commands available:
+Open Claude Code. You now have 60+ slash commands available:
 
 ```bash
 /mastermind:autodev --tillend     # start autonomous code loop
-/mastermind:createorg my-team     # create your first AI org
+monomind org run my-team          # run your first AI org (see .monomind/orgs/sample-team.json)
 /mastermind:help                  # show all commands
 ```
 
@@ -262,7 +241,7 @@ Before touching any file, Monomind queries **Monograph** — a SQLite-backed kno
 
 ## 🎣 Hooks & Workers
 
-Monomind wires 22 hook events into Claude Code. Every edit, task, command, and session fires hooks that log patterns, route agents, and train the intelligence system.
+Monomind wires 29 hook subcommands into Claude Code across edit, task, command, and session lifecycle events — logging patterns, routing agents, and feeding the intelligence system.
 
 ```mermaid
 flowchart LR
@@ -296,7 +275,7 @@ const result = await fence.detect(userInput);
 
 ---
 
-## 📋 80+ Slash Commands
+## 📋 60+ Slash Commands
 
 Everything runs from inside Claude Code via slash commands. Here's the highlight reel:
 
@@ -315,9 +294,9 @@ Everything runs from inside Claude Code via slash commands. Here's the highlight
 ### Organizations
 | Command | What it does |
 |---|---|
-| `/mastermind:createorg` | Design an autonomous agent org |
-| `/mastermind:runorg` | Start it as a background daemon |
-| `/mastermind:orgs` | List all orgs + status |
+| `monomind org run <name>` | Start an org as a real SDK-backed daemon |
+| `monomind org status` / `list` | Runtime state for one or all orgs |
+| `monomind org stop <name>` | Request a graceful stop |
 | `/mastermind:approve` | Action pending approval requests |
 
 ### Business Domains
@@ -329,7 +308,7 @@ Everything runs from inside Claude Code via slash commands. Here's the highlight
 | `/mastermind:finance` | Budgets, invoicing, modeling |
 | `/mastermind:ops` | Operations and workflow automation |
 
-**[→ Full reference (80+ commands)](https://monoes.github.io/monomind/#slash)**
+**[→ Full reference (60+ commands)](https://monoes.github.io/monomind/#slash)**
 
 ---
 
@@ -351,24 +330,27 @@ graph TD
     CC["Claude Code"]
     MCP["MCP Server\nmonomind mcp start"]
     D["Background Workers\n(@monomind/hooks, in-process)"]
+    ORG["OrgDaemon\nmonomind org run\nreal SDK sessions"]
 
-    CC <-->|"MCP tools: monograph, memory, swarm"| MCP
+    CC <-->|"MCP tools: monograph, memory"| MCP
     MCP <--> D
 
     D --> ADB[("Memory store\npatterns + episodes")]
     D --> MG[("Monograph\ncode graph")]
-    D --> HK["Hooks\n22 event types"]
-    D --> SW["Swarm\n4 topologies\n3 consensus strategies"]
+    D --> HK["Hooks\n29 subcommands"]
 
-    CC -->|"Task tool - spawns agents"| AG["Agent Swarm\narchitect, coder\ntester, reviewer\nsecurity, perf"]
+    CC -->|"Task tool - spawns agents"| AG["In-session agents\narchitect, coder\ntester, reviewer\nsecurity, perf"]
     AG <-->|reads and writes| ADB
+    ORG -->|"spawns, policy-gated"| RA["Role agents"]
+    ORG <-->|reads and writes| ADB
 
     style CC fill:#00D2AA22,stroke:#00D2AA
     style AG fill:#8B5CF622,stroke:#8B5CF6
     style ADB fill:#F59E0B22,stroke:#F59E0B
+    style ORG fill:#F59E0B22,stroke:#F59E0B
 ```
 
-**Claude Code handles all execution.** MCP tools only coordinate. Your data never leaves your machine.
+**Claude Code's Task tool drives in-session multi-agent work; `monomind org run` drives persistent background orgs.** Your data never leaves your machine.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "monomind",
-  "version": "2.0.3",
-  "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.",
+  "version": "2.1.3",
+  "description": "Open-source CLI extension for Claude Code. Adds an MCP server with a codebase knowledge graph, persistent memory, multi-agent coordination, and reusable slash commands. MIT licensed, runs locally, no data leaves your machine.",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -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",
@@ -135,10 +140,9 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.0.0",
+    "typescript": "^7.0.2",
     "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/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');
@@ -111,31 +112,23 @@ 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
- * (dead pid or older than 30s) is broken and re-claimed.
+ * (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() {
-  try { fs.mkdirSync(path.dirname(LOCK_FILE), { recursive: true }); } catch { /* ignore */ }
-  try {
-    fs.writeFileSync(LOCK_FILE, String(process.pid), { flag: 'wx' });
-    return true;
-  } catch {
-    try {
-      const stat = fs.statSync(LOCK_FILE);
-      const holder = Number(fs.readFileSync(LOCK_FILE, 'utf-8'));
-      if (Date.now() - stat.mtimeMs < 30_000 && isPidAlive(holder)) return false;
-      fs.unlinkSync(LOCK_FILE);
-      fs.writeFileSync(LOCK_FILE, String(process.pid), { flag: 'wx' });
-      return true;
-    } catch {
-      return false;
-    }
-  }
+  return claimLock(LOCK_FILE, 30_000);
 }
 
 function releaseSpawnLock() {
-  try {
-    if (Number(fs.readFileSync(LOCK_FILE, 'utf-8')) === process.pid) fs.unlinkSync(LOCK_FILE);
-  } catch { /* ignore */ }
+  releaseLock(LOCK_FILE);
 }
 
 async function main() {

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 {