claws-code 0.8.0

package/scripts/hooks/pre-tool-use-claws.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// Claws PreToolUse hook — Bash long-running enforcement.
+//
+// Default mode: long-running Bash patterns hard-block via exit 2 + stderr.
+// STRICT=1: deny via permissionDecision JSON (cleaner inline reason).
+//
+// CLAWS_STRICT=1 (env var, set in user shell or settings.json env block):
+// long-running Bash patterns return permissionDecision:"deny" via the
+// PreToolUse hookSpecificOutput. Claude Code blocks the tool call and shows
+// the reason — which tells the model exactly what to use instead.
+//
+// Lifecycle gate moved server-side in v0.6.5 — removed from this hook.
+//
+// SAFETY CONTRACT (v0.7.3): this hook MUST NEVER block, crash, or exit
+// non-zero EXCEPT when intentionally denying via permissionDecision. Any
+// internal error → silent exit 0. Avoids the "non-blocking status code"
+// error spam that breaks user workflows.
+'use strict';
+
+// M-24: gate error handlers on CLAWS_DEBUG — when CLAWS_DEBUG=1, errors
+// propagate visibly for debugging instead of being silently swallowed.
+if (!process.env.CLAWS_DEBUG) {
+  process.on('uncaughtException', () => { try { process.exit(0); } catch {} });
+  process.on('unhandledRejection', () => { try { process.exit(0); } catch {} });
+}
+
+// M-13: 5-second self-kill safety timer — hook can never hang the parent process.
+setTimeout(() => { process.exit(0); }, 5000).unref();
+
+let input = '';
+// M-13: single try block for both 'data' and 'end' — fail together or not at all.
+try {
+  process.stdin.on('data', d => { input += d; });
+  process.stdin.on('end', () => {
+    try {
+      const fs   = require('fs');
+      const path = require('path');
+
+      // Patterns that almost always indicate orchestration work — long-running
+      // servers, watchers, or background processes — where a wrapped Claws
+      // terminal is strictly better than a fire-and-forget Bash call.
+      // Conservative list: every entry should be unambiguously long-running
+      // so strict mode never blocks ordinary commands like `ls`, `git status`,
+      // or one-shot builds.
+      const LONG_RUNNING_PATTERNS = [
+        /\bnpm (run )?(start|dev|serve|watch)\b/i,
+        /\byarn (start|dev|serve|watch)\b/i,
+        /\bpnpm (run )?(start|dev|serve|watch)\b/i,
+        /\bbun (run )?(start|dev|serve|watch)\b/i,
+        /\bnode\b.*\bserver\b/i,
+        /\bpython\b.*\bserver\b/i,
+        /\b(uvicorn|gunicorn|hypercorn)\b/i,
+        /\bflask run\b/i,
+        /\brails (server|s)\b/i,
+        /\bcargo (watch|run)\b/i,
+        /\bgo run\b/i,
+        /\bmake (run|serve|start|dev)\b/i,
+        /\bnodemon\b/i,
+        /\bnohup\b/i,
+        // Always-block patterns: interactive/long-lived by nature
+        /\bclaude(?!\s+-p\b)(?!\s+--print\b)(\s|$)/,   // claude without -p/--print (interactive TUI)
+        /\bpython\s+-m\b/i,                              // python -m <module> (often servers/long-running)
+        /\bvite\b(?!\s+build\b)/i,                      // vite dev server (not vite build)
+        /\bwebpack(-dev-server|.*--watch)\b/i,           // webpack-dev-server or webpack --watch
+        /\bnode\b.*\bserver\.js\b/i,                    // node server.js
+      ];
+
+      // BUG-16: argv[0] allowlist — LONG_RUNNING_PATTERNS only run when the
+      // command name (first token, basename) is a known long-running candidate.
+      // Prevents false positives when keywords appear in arguments, not commands
+      // (e.g. `grep "node server"` or `cat node-server-config.json`).
+      const LONG_RUNNING_ARGV0 = new Set([
+        'npm', 'yarn', 'pnpm', 'bun', 'bunx', 'npx',
+        'node', 'python', 'python3',
+        'uvicorn', 'gunicorn', 'hypercorn', 'flask',
+        'rails', 'cargo', 'go', 'make',
+        'nodemon', 'nohup', 'claude',
+        'vite', 'webpack', 'webpack-dev-server',
+      ]);
+
+      const STRICT = process.env.CLAWS_STRICT === '1';
+
+      let data = {};
+      try { data = JSON.parse(input); } catch { process.exit(0); return; }
+
+      const toolName = data.tool_name || '';
+      const cwd      = data.cwd || process.cwd();
+
+      // Only act if Claws socket is present in the cwd
+      const socketPath = path.join(cwd, '.claws', 'claws.sock');
+      if (!fs.existsSync(socketPath)) { process.exit(0); return; }
+
+      // --- Edit/Write guard: block direct edits to mcp_server.js from orchestrator ---
+      if (toolName === 'Edit' || toolName === 'Write') {
+        const filePath = (data.tool_input && data.tool_input.file_path) || '';
+        if (/mcp_server\.js$/.test(filePath)) {
+          // BUG-27: workers spawned by claws_worker/fleet/dispatch_subworker carry
+          // CLAWS_WORKER=1 — allow them to edit mcp_server.js directly.
+          if (process.env.CLAWS_WORKER === '1') { process.exit(0); return; }
+          try {
+            process.stderr.write(
+              `[claws] Direct edits to mcp_server.js from orchestrator are forbidden.\n` +
+              `        Dispatch a worker via claws_worker instead.\n`
+            );
+          } catch {}
+          process.exit(2);
+          return;
+        }
+      }
+
+      // --- MCP spawn-class gate: enforce Monitor arm after grace period ---
+      // claws_create / claws_worker / claws_fleet / claws_dispatch_subworker all
+      // spawn terminals; requiring an active Monitor prevents silent orphans.
+      // BUG-28: 5 s grace window (was 60 s) — tight enough to catch any spawn call
+      // after the SessionStart reminder has been processed. Grace state lives in
+      // /tmp keyed by a hash of cwd so it survives hook restarts within a session.
+      const SPAWN_CLASS = /^mcp__claws__(claws_create|claws_worker|claws_fleet|claws_dispatch_subworker)$/;
+      if (SPAWN_CLASS.test(toolName)) {
+        const cwdKey = Buffer.from(cwd).toString('base64').replace(/[+/=]/g, '_').slice(0, 12);
+        const graceFile = `/tmp/claws-pretooluse-grace-${cwdKey}`;
+        let enforceNow = false;
+        try {
+          if (!fs.existsSync(graceFile)) {
+            fs.writeFileSync(graceFile, String(Date.now()), 'utf8');
+          } else {
+            const ts = parseInt(fs.readFileSync(graceFile, 'utf8').trim(), 10);
+            enforceNow = (Date.now() - ts) > 5000;
+          }
+        } catch { /* grace check failure → never block */ }
+
+        if (enforceNow) {
+          const { spawnSync } = require('child_process');
+          // Wave C (Task #63): accept canonical bus-stream sidecar as satisfier.
+          // stream-events.js is auto-spawned by SessionStart and never goes idle
+          // (constant heartbeat traffic) so it is never SIGURG'd. tail -F is kept
+          // as a deprecated fallback for one release. See ARCHITECTURE.md P9 + A1.
+          const pgSidecar = spawnSync('pgrep', ['-f', 'stream-events\\.js'],            { stdio: 'ignore' });
+          const pgTail    = spawnSync('pgrep', ['-f', 'tail.*\\.claws/events\\.log'], { stdio: 'ignore' });
+          if (pgSidecar.status !== 0 && pgTail.status !== 0) {
+            try {
+              process.stdout.write(JSON.stringify({
+                hookSpecificOutput: {
+                  hookEventName: 'PreToolUse',
+                  permissionDecision: 'deny',
+                  permissionDecisionReason:
+                    `Monitor not armed. The canonical satisfier is the stream-events.js sidecar ` +
+                    `(auto-spawned by SessionStart hook). If missing, arm it with: ` +
+                    `Monitor(command="node <claws>/scripts/stream-events.js | grep --line-buffered ...", ...). ` +
+                    `(Per ARCHITECTURE.md P9 — tail -F is deprecated as Monitor satisfier.)`,
+                },
+              }) + '\n');
+            } catch {}
+            process.exit(0);
+            return;
+          }
+        }
+      }
+
+      // --- Bash long-running guard ---
+      if (toolName === 'Bash') {
+        const cmd = (data.tool_input && data.tool_input.command) || '';
+        // BUG-16: extract argv[0] (basename of first token) and gate pattern
+        // matching on the argv0 allowlist — prevents false positives from
+        // keywords appearing inside arguments rather than as the command name.
+        const argv0 = path.basename((cmd.trim().split(/\s+/)[0] || ''));
+        const match = LONG_RUNNING_ARGV0.has(argv0) && LONG_RUNNING_PATTERNS.find(p => p.test(cmd));
+        if (match) {
+          const msg = [
+            `[claws] Bash command matches a long-running pattern.`,
+            `Run this in a visible, monitorable Claws terminal instead:`,
+            ``,
+            `  1. claws_create({ name: "<slug>", wrapped: true })`,
+            `  2. claws_send({ id: <N>, text: ${JSON.stringify(cmd)} })`,
+            `  3. claws_read_log({ id: <N>, lines: 50 }) — to observe`,
+            `  4. claws_close({ id: <N> }) — when done`,
+            ``,
+            `Or use claws_worker for AI-driven tasks.`,
+          ].join('\n');
+          if (STRICT) {
+            // STRICT mode: deny via permissionDecision JSON on stdout (M-16)
+            try {
+              process.stdout.write(JSON.stringify({
+                hookSpecificOutput: {
+                  hookEventName: 'PreToolUse',
+                  permissionDecision: 'deny',
+                  permissionDecisionReason: msg,
+                },
+              }) + '\n');
+            } catch {}
+            process.exit(0);
+            return;
+          }
+          // Default: hard-block via exit 2 + stderr
+          try { process.stderr.write(msg + '\n'); } catch {}
+          process.exit(2);
+          return;
+        }
+      }
+      process.exit(0);
+    } catch {
+      process.exit(0);
+    }
+  });
+} catch {
+  process.exit(0);
+}

package/scripts/hooks/session-start-claws.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Claws SessionStart hook — detects Claws socket and emits lifecycle reminder.
+//
+// SAFETY CONTRACT: this hook MUST NEVER block, crash, or exit non-zero.
+// Any internal error → silent exit 0. Hooks are advisory; failing loud
+// blocks the user's tool calls and creates the very "hook errors" we're
+// trying to eliminate. v0.7.3 hardening.
+'use strict';
+
+// M-24: gate error handlers on CLAWS_DEBUG — when CLAWS_DEBUG=1, errors
+// propagate visibly for debugging instead of being silently swallowed.
+if (!process.env.CLAWS_DEBUG) {
+  process.on('uncaughtException', () => { try { process.exit(0); } catch {} });
+  process.on('unhandledRejection', () => { try { process.exit(0); } catch {} });
+}
+
+// M-13: 5-second self-kill safety timer — hook can never hang the parent process.
+// .unref() so the timer doesn't prevent normal early exit.
+setTimeout(() => { process.exit(0); }, 5000).unref();
+
+let input = '';
+// M-13: single try block wrapping both 'data' and 'end' listeners — if either
+// registration throws (pathological stdin state), both fail together cleanly.
+try {
+  process.stdin.on('data', d => { input += d; });
+  process.stdin.on('end', () => {
+    try {
+      const fs   = require('fs');
+      const path = require('path');
+
+      let cwd = process.cwd();
+      try {
+        const parsed = JSON.parse(input);
+        if (parsed.cwd) cwd = parsed.cwd;
+      } catch { /* use process.cwd() */ }
+
+      const socketPath = path.join(cwd, '.claws', 'claws.sock');
+      if (!fs.existsSync(socketPath)) { process.exit(0); return; }
+
+      // events.log: bus push events from the sidecar are piped here so the
+      // orchestrator can arm a Monitor on it and receive real-time notifications.
+      const logPath = path.join(cwd, '.claws', 'events.log');
+
+      // Spawn stream-events.js sidecar daemon if not already running (idempotent).
+      // SIM2B-P2b: include socket path in pgrep pattern so per-project sidecars are
+      // distinct — a stale sidecar from a different project won't block this session.
+      // pgrep exit 0 = found (running), non-zero = not found.
+      try {
+        const { spawnSync, spawn } = require('child_process');
+        const sidecarPath = path.join(__dirname, '..', 'stream-events.js');
+        if (fs.existsSync(sidecarPath)) {
+          // Escape regex metacharacters in the socket path for the pgrep pattern.
+          const escapedSocket = socketPath.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+          const pg = spawnSync('pgrep', ['-f', `stream-events\\.js.*--auto-sidecar.*${escapedSocket}`], { stdio: 'ignore' });
+          if (pg.status !== 0) {
+            // Pre-create events.log so 'tail -F' has a file to watch immediately
+            // (sidecar writes the first event only after the first publish arrives).
+            fs.mkdirSync(path.dirname(logPath), { recursive: true });
+            try { fs.writeFileSync(logPath, '', { flag: 'a' }); } catch {}
+            let logFd = null;
+            try { logFd = fs.openSync(logPath, 'a'); } catch {}
+            const sidecar = spawn(process.execPath, [sidecarPath, '--auto-sidecar', socketPath], {
+              detached: true,
+              stdio: ['ignore', logFd !== null ? logFd : 'ignore', 'ignore'],
+              cwd,
+            });
+            sidecar.unref();
+            // Close the fd in the parent — the child has its own copy after fork.
+            if (logFd !== null) { try { fs.closeSync(logFd); } catch {} }
+          }
+        }
+      } catch { /* sidecar spawn failure must never block the hook */ }
+
+      // BUG-29: lifecycle-bound Monitor description — include session start timestamp
+      // so stale Monitors from prior sessions are visually distinguishable.
+      // Format: "claws bus | sess=<ISO-hour>" — add plan slug once lifecycle plan is active.
+      const sessTs = new Date().toISOString().slice(0, 13); // "2026-05-02T04"
+
+      const reminder = [
+        '## Claws active in this project',
+        '',
+        `Bus events stream to ${logPath}. Server enforces lifecycle (sess=${sessTs}).`,
+        '',
+        'Spawn-class MCP tools (claws_create / claws_worker / claws_fleet / claws_dispatch_subworker)',
+        'require an active Monitor on the bus stream — server refuses spawn without it.',
+        'See docs/ENFORCEMENT.md for the architectural contract.',
+      ].join('\n');
+
+      try { process.stdout.write(JSON.stringify({ type: 'system', content: reminder }) + '\n'); } catch {}
+      process.exit(0);
+    } catch {
+      process.exit(0);
+    }
+  });
+} catch {
+  process.exit(0);
+}

package/scripts/hooks/stop-claws.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Claws Stop hook — enforce CLEANUP and REFLECT before session ends.
+//
+// SAFETY CONTRACT (v0.7.3): never crash, never block, never exit non-zero.
+// Hooks are advisory; failure to load lifecycle-state.js (e.g. file missing
+// after partial install) must not surface as "hook error" in Claude Code.
+'use strict';
+
+// M-24: gate error handlers on CLAWS_DEBUG — when CLAWS_DEBUG=1, errors
+// propagate visibly for debugging instead of being silently swallowed.
+if (!process.env.CLAWS_DEBUG) {
+  process.on('uncaughtException', () => { try { process.exit(0); } catch {} });
+  process.on('unhandledRejection', () => { try { process.exit(0); } catch {} });
+}
+
+// M-13: 5-second self-kill safety timer — hook can never hang the parent process.
+setTimeout(() => { process.exit(0); }, 5000).unref();
+
+let input = '';
+// M-13: single try block for both 'data' and 'end' — fail together or not at all.
+try {
+  process.stdin.on('data', d => { input += d; });
+  process.stdin.on('end', () => {
+    try {
+      const fs   = require('fs');
+      const path = require('path');
+      // LH-9: lifecycle-state is no longer read by the Stop hook. The
+      // extension's TTL watchdog + reconcile-on-boot are the deterministic
+      // close mechanism. This hook is now responsible only for cleaning up
+      // sidecar/tail processes and the pre-tool-use grace file.
+
+      let cwd = process.cwd();
+      try {
+        const parsed = JSON.parse(input);
+        if (parsed.cwd) cwd = parsed.cwd;
+      } catch { /* use process.cwd() */ }
+
+      const socketPath = path.join(cwd, '.claws', 'claws.sock');
+      if (!fs.existsSync(socketPath)) { process.exit(0); return; }
+
+      // Kill stream-events.js sidecar daemon spawned by session-start-claws.js
+      try {
+        const { spawnSync } = require('child_process');
+        const pg = spawnSync('pgrep', ['-f', 'stream-events\\.js.*--auto-sidecar'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        if (pg.status === 0 && pg.stdout) {
+          const pids = pg.stdout.trim().split('\n').filter(Boolean);
+          for (const pid of pids) {
+            try { spawnSync('kill', ['-TERM', pid.trim()], { stdio: 'ignore' }); } catch {}
+          }
+        }
+      } catch { /* sidecar kill failure must never block the hook */ }
+
+      // Kill orphan tail -F processes monitoring events.log spawned this session.
+      try {
+        const { spawnSync } = require('child_process');
+        const pg2 = spawnSync('pgrep', ['-f', 'tail.*\\.claws/events\\.log'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        if (pg2.status === 0 && pg2.stdout) {
+          const pids = pg2.stdout.trim().split('\n').filter(Boolean);
+          for (const pid of pids) {
+            try { spawnSync('kill', ['-TERM', pid.trim()], { stdio: 'ignore' }); } catch {}
+          }
+        }
+      } catch { /* tail kill failure must never block the hook */ }
+
+      // Remove the pre-tool-use grace file so the next session starts with a
+      // fresh 60 s window and the Monitor-arm enforcement resets cleanly.
+      try {
+        const cwdKey = Buffer.from(cwd).toString('base64').replace(/[+/=]/g, '_').slice(0, 12);
+        const graceFile = `/tmp/claws-pretooluse-grace-${cwdKey}`;
+        if (fs.existsSync(graceFile)) fs.unlinkSync(graceFile);
+      } catch { /* grace file removal must never block the hook */ }
+
+      // LH-9: force-close removed. The Stop hook fires at the end of every
+      // assistant turn (Anthropic semantics) — not at session shutdown — so
+      // closing detached workers here killed long-running missions between
+      // turns. Worker lifetime is now governed by the TTL watchdog inside
+      // the extension (default 10min idle, 4h hard ceiling), and stale
+      // entries in lifecycle-state.json self-heal via reconcile-on-boot in
+      // ClawsServer's constructor. The hook keeps only the sidecar/tail
+      // cleanup above.
+      process.exit(0);
+    } catch {
+      process.exit(0);
+    }
+  });
+} catch {
+  process.exit(0);
+}

package/scripts/inject-claude-md.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// Inject the dynamic Claws block into a project's CLAUDE.md.
+// Usage: node inject-claude-md.js <project-root>
+//
+// Behavior:
+// 1. Migrates legacy v0.1–v0.3 "## CLAWS — Terminal Orchestration Active"
+//    section if present.
+// 2. Inserts or replaces the fenced block:
+//    <!-- CLAWS:BEGIN [v<X.Y.Z>] --> ... <!-- CLAWS:END [v<X.Y.Z>] -->
+//    Sentinel match is regex-based so any prior version is cleanly replaced.
+// 3. Tool list, lifecycle phase list, and version are derived from code at
+//    inject time — see readToolList(), readPhases(), readVersion(). This makes
+//    drift between the server and the user-facing CLAUDE.md structurally
+//    impossible.
+// 4. If CLAUDE.md doesn't exist, creates a minimal stub with a placeholder for
+//    project-specific context above the block.
+// 5. Preserves every non-Claws line of the file byte-for-byte.
+
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+// M-27: atomic write helper (tmp + renameSync) — mirrors atomic-file.mjs writeAtomic.
+function writeAtomic(filePath, content) {
+  const tmp = filePath + '.claws-tmp.' + process.pid + '-' + (++writeAtomic._nonce);
+  let _fd;
+  try {
+    _fd = fs.openSync(tmp, 'w', 0o644);
+    fs.writeSync(_fd, content);
+    fs.fsyncSync(_fd);
+    fs.closeSync(_fd);
+    _fd = null;
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    if (_fd != null) { try { fs.closeSync(_fd); } catch { /* ignore */ } }
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+writeAtomic._nonce = 0;
+
+const TARGET = process.argv[2];
+if (!TARGET) {
+  console.error('usage: inject-claude-md.js <project-root>');
+  process.exit(2);
+}
+
+const REPO_ROOT = path.join(__dirname, '..');
+const CLAUDE_MD = path.join(TARGET, 'CLAUDE.md');
+const CMD_DIR = path.join(TARGET, '.claude', 'commands');
+
+// ── Source-of-truth readers ────────────────────────────────────────────────
+// Tool list: parse mcp_server.js dispatch handlers. Pattern: `name === 'claws_xxx'`.
+// One unique entry per tool. Sorted alphabetically for stable diffs.
+function readToolList() {
+  const mcpPath = path.join(REPO_ROOT, 'mcp_server.js');
+  try {
+    const src = fs.readFileSync(mcpPath, 'utf8');
+    const re = /name === '(claws_[a-z_]+)'/g;
+    const set = new Set();
+    let m;
+    while ((m = re.exec(src)) !== null) set.add(m[1]);
+    return Array.from(set).sort();
+  } catch (err) {
+    return [];
+  }
+}
+
+// Phase enum: parse extension/src/lifecycle-store.ts `export type Phase = ...`.
+// Returned in declaration order (which is also lifecycle order).
+function readPhases() {
+  const ltPath = path.join(REPO_ROOT, 'extension', 'src', 'lifecycle-store.ts');
+  try {
+    const src = fs.readFileSync(ltPath, 'utf8');
+    const m = src.match(/export type Phase\s*=([^;]+);/);
+    if (!m) return [];
+    return Array.from(m[1].matchAll(/'([A-Z][A-Z0-9-]+)'/g)).map((x) => x[1]);
+  } catch (err) {
+    return [];
+  }
+}
+
+function readVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8'));
+    return pkg.version || 'unknown';
+  } catch (err) {
+    return 'unknown';
+  }
+}
+
+const TOOLS = readToolList();
+const PHASES = readPhases();
+const VERSION = readVersion();
+
+// Versioned sentinels — emitted with current version, matched with regex
+// so prior-version blocks are replaced cleanly on upgrade.
+const BEGIN_LITERAL = `<!-- CLAWS:BEGIN v${VERSION} -->`;
+const END_LITERAL   = `<!-- CLAWS:END v${VERSION} -->`;
+const BEGIN_RE = /<!-- CLAWS:BEGIN(?: v[\d.]+(?:-[\w.]+)?)? -->/;
+const END_RE   = /<!-- CLAWS:END(?: v[\d.]+(?:-[\w.]+)?)? -->/;
+
+let cmds = [];
+try {
+  cmds = fs.readdirSync(CMD_DIR)
+    .filter((f) => f.startsWith('claws') && f.endsWith('.md'))
+    .map((f) => '/' + f.replace(/\.md$/, ''))
+    .sort();
+} catch { /* ignore */ }
+
+function buildBlock(target, cmds) {
+  const tpl = path.join(REPO_ROOT, 'templates', 'CLAUDE.project.md');
+  try {
+    const raw = fs.readFileSync(tpl, 'utf8');
+    const toList = (arr) => arr.map((t) => '`' + t + '`').join(', ');
+    const phaseChain = PHASES.length ? PHASES.join(' → ') : '(unavailable)';
+    return raw
+      .trimEnd()
+      // Replace literal BEGIN/END sentinels in template with versioned ones.
+      .replace(/<!-- CLAWS:BEGIN(?: v[\d.]+(?:-[\w.]+)?)? -->/g, BEGIN_LITERAL)
+      .replace(/<!-- CLAWS:END(?: v[\d.]+(?:-[\w.]+)?)? -->/g, END_LITERAL)
+      .replace(/\{PROJECT_NAME\}/g, path.basename(target))
+      .replace(/\{SOCKET_PATH\}/g, '.claws/claws.sock')
+      .replace(/\{VERSION\}/g, VERSION)
+      .replace(/\{TOOLS_COUNT\}/g, String(TOOLS.length))
+      .replace(/\{TOOLS_LIST\}/g, TOOLS.length ? toList(TOOLS) : '_(no tools detected — mcp_server.js missing?)_')
+      .replace(/\{LIFECYCLE_PHASES\}/g, phaseChain)
+      .replace(/\{CMDS_COUNT\}/g, String(cmds.length))
+      .replace(/\{CMDS_LIST\}/g, cmds.length ? toList(cmds) : '_(none installed)_');
+  } catch (err) {
+    return [
+      BEGIN_LITERAL,
+      '<!-- ERROR: templates/CLAUDE.project.md not found: ' + err.message + ' -->',
+      '## Claws — Terminal Orchestration (MANDATORY)',
+      '',
+      'You are a Claws orchestrator. Use claws_create + claws_send for long-lived processes.',
+      'Always close every terminal you create. Never touch terminals you did not create.',
+      END_LITERAL,
+    ].join('\n');
+  }
+}
+
+const block = buildBlock(TARGET, cmds);
+
+let md = '';
+let existed = false;
+try { md = fs.readFileSync(CLAUDE_MD, 'utf8'); existed = true; } catch { /* ignore */ }
+
+// ── Migrate legacy v0.1–v0.3 section ─────────────────────────────────────
+let migrated = false;
+const legacyStart = md.indexOf('## CLAWS — Terminal Orchestration Active');
+if (legacyStart !== -1) {
+  const rest = md.slice(legacyStart);
+  const legacyEndPhrase = 'Type `/claws-help` for the full prompt guide.';
+  const phraseIdx = rest.indexOf(legacyEndPhrase);
+  let legacyEndAbs;
+  if (phraseIdx !== -1) {
+    const after = legacyStart + phraseIdx + legacyEndPhrase.length;
+    const nlAfter = md.indexOf('\n', after);
+    legacyEndAbs = nlAfter === -1 ? md.length : nlAfter + 1;
+  } else {
+    const lines = rest.split('\n');
+    let consumed = lines[0].length + 1;
+    for (let i = 1; i < lines.length; i++) {
+      if (lines[i].startsWith('## ')) {
+        legacyEndAbs = legacyStart + consumed;
+        break;
+      }
+      consumed += lines[i].length + 1;
+    }
+    if (legacyEndAbs === undefined) legacyEndAbs = md.length;
+  }
+  let trimStart = legacyStart;
+  if (trimStart >= 2 && md.slice(trimStart - 2, trimStart) === '\n\n') {
+    trimStart -= 1;
+  }
+  md = md.slice(0, trimStart) + md.slice(legacyEndAbs);
+  migrated = true;
+}
+
+// ── Insert or replace fenced block (regex match — handles any prior version) ──
+const beginMatch = md.match(BEGIN_RE);
+const endMatch   = md.match(END_RE);
+
+let next;
+if (beginMatch && endMatch && endMatch.index > beginMatch.index) {
+  next = md.slice(0, beginMatch.index) + block + md.slice(endMatch.index + endMatch[0].length);
+} else if (existed) {
+  const sep = md.endsWith('\n\n') ? '' : md.endsWith('\n') ? '\n' : '\n\n';
+  next = md + sep + block + '\n';
+} else {
+  next = '# Project\n\n<!-- Add your project-specific Claude Code context above this line -->\n\n' + block + '\n';
+}
+
+let orig = '';
+try { orig = fs.readFileSync(CLAUDE_MD, 'utf8'); } catch { /* ignore */ }
+
+if (next !== orig) {
+  writeAtomic(CLAUDE_MD, next);
+  const prefix = migrated ? 'legacy section migrated; ' : '';
+  const action = beginMatch ? 'Claws block updated' : 'Claws block inserted';
+  console.log(`CLAUDE.md ${prefix}${existed ? action : 'created with Claws block'} (v${VERSION}, ${TOOLS.length} tools, ${PHASES.length} phases)`);
+} else {
+  console.log(`CLAUDE.md already has the current Claws block (v${VERSION})`);
+}