claws-code 0.8.0

package/mcp_server.js

@@ -0,0 +1,3529 @@
+#!/usr/bin/env node
+/**
+ * Claws MCP Server — expose terminal control as native Claude Code tools.
+ * Zero dependencies. Node.js stdlib only.
+ *
+ * Powered by Claude Opus.
+ *
+ * Install Claws (auto-registers this MCP server globally):
+ *     bash <(curl -fsSL https://raw.githubusercontent.com/neunaha/claws/main/scripts/install.sh)
+ *
+ * Or register manually (use FULL absolute path):
+ *     "mcpServers": {
+ *         "claws": {
+ *             "command": "node",
+ *             "args": ["/home/YOUR_USER/.claws-src/mcp_server.js"]
+ *         }
+ *     }
+ *
+ * Tools: claws_list, claws_create, claws_send, claws_exec,
+ *        claws_read_log, claws_poll, claws_close, claws_worker,
+ *        claws_hello, claws_subscribe, claws_publish, claws_broadcast,
+ *        claws_ping, claws_peers
+ */
+
+const net = require('net');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { randomUUID } = require('crypto');
+
+// Resolve stream-events.js path at load time — correct across all install layouts:
+//   .claws-bin install:  __dirname === <project>/.claws-bin  → candidates[0]
+//   dev source tree:     __dirname === <repo-root>           → candidates[2]
+const STREAM_EVENTS_JS = (() => {
+  const candidates = [
+    path.join(__dirname, 'stream-events.js'),
+    path.join(__dirname, '.claws-bin', 'stream-events.js'),
+    path.join(__dirname, 'scripts', 'stream-events.js'),
+  ];
+  for (const p of candidates) {
+    try { if (fs.existsSync(p)) return p; } catch (_) {}
+  }
+  return candidates[0];
+})();
+
+// Forward-slash form for embedding in Monitor command strings — single backslashes in the path
+// are eaten by shell quoting at the Monitor tool receiver on Windows; Node accepts forward slashes.
+const STREAM_EVENTS_JS_FOR_CMD = process.platform === 'win32'
+  ? STREAM_EVENTS_JS.replace(/\\/g, '/')
+  : STREAM_EVENTS_JS;
+
+// Guard: schemas/mcp-tools.json is generated by `npm run schemas` in extension/.
+// If missing, fail fast with a clear message rather than a confusing crash.
+const _mcpToolsPath = path.join(__dirname, 'schemas', 'mcp-tools.json');
+if (!fs.existsSync(_mcpToolsPath)) {
+  process.stderr.write(
+    '[claws-mcp] ERROR: schemas/mcp-tools.json not found.\n' +
+    '  Run: cd extension && npm run schemas\n',
+  );
+  process.exit(1);
+}
+
+// ─── MCP protocol (stdio, newline-delimited JSON) ──────────────────────────
+// MCP spec: each JSON-RPC message is a single line on stdin/stdout, terminated
+// by '\n'. (NOT LSP-style Content-Length framing — that was the prior bug.)
+
+let inputBuf = '';
+
+function readMessage() {
+  return new Promise((resolve) => {
+    const tryParse = () => {
+      const nl = inputBuf.indexOf('\n');
+      if (nl === -1) return false;
+      const line = inputBuf.slice(0, nl).replace(/\r$/, '');
+      inputBuf = inputBuf.slice(nl + 1);
+      if (line.trim() === '') return tryParse();
+      try {
+        resolve(JSON.parse(line));
+        return true;
+      } catch {
+        return tryParse();
+      }
+    };
+    if (tryParse()) return;
+    const onData = (chunk) => {
+      inputBuf += chunk.toString('utf8');
+      if (tryParse()) process.stdin.removeListener('data', onData);
+    };
+    process.stdin.on('data', onData);
+  });
+}
+
+function writeMessage(msg) {
+  process.stdout.write(JSON.stringify(msg) + '\n');
+}
+
+function respond(id, result) {
+  writeMessage({ jsonrpc: '2.0', id, result });
+}
+
+function respondError(id, code, message) {
+  writeMessage({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+function log(msg) {
+  process.stderr.write('[claws-mcp] ' + msg + '\n');
+}
+
+// Keep the bridge alive on unexpected async failures.
+// Under Node ≥ 15 the default for unhandled rejections is throw → process exit,
+// which causes the "MCP error -32000: Connection closed" symptom. These handlers
+// log the cause and keep the process running so Claude Code receives a per-tool
+// JSON-RPC error instead of a disconnected bridge.
+process.on('unhandledRejection', (reason, _p) => {
+  process.stderr.write('[claws-mcp][FATAL] unhandledRejection: ' + (reason && reason.stack || String(reason)) + '\n');
+});
+process.on('uncaughtException', (err) => {
+  process.stderr.write('[claws-mcp][FATAL] uncaughtException: ' + (err && err.stack || String(err)) + '\n');
+});
+
+// L2 investigation helper — writes to stderr AND .claws/l2-debug.log for file-based capture.
+function _logL2File(sockPath, msg) {
+  // Named pipes are kernel objects with no filesystem directory — skip on win32.
+  if (sockPath && sockPath.startsWith('\\\\.\\pipe\\')) return;
+  try {
+    const logPath = path.join(path.dirname(path.resolve(sockPath)), 'l2-debug.log');
+    fs.appendFileSync(logPath, new Date().toISOString() + ' ' + msg + '\n');
+  } catch (_e) { /* non-fatal */ }
+}
+
+function toolError(message) {
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+// ─── Claws socket client ───────────────────────────────────────────────────
+
+let counter = 0;
+
+// Per-call socket — stateless claws/1 commands (list, create, send, close,
+// readLog, poll, exec, introspect, ping, lifecycle.*). Each call opens a
+// fresh socket, sends one frame, receives one response, destroys the socket.
+function clawsRpc(sockPath, req, timeout = 30000) {
+  return new Promise((resolve) => {
+    counter++;
+    req = { id: counter, ...req };
+    const sock = net.createConnection(sockPath);
+    sock.setTimeout(timeout);
+    let buf = '';
+    sock.on('connect', () => {
+      sock.write(JSON.stringify(req) + '\n');
+    });
+    sock.on('data', (data) => {
+      buf += data.toString('utf8');
+      const nl = buf.indexOf('\n');
+      if (nl !== -1) {
+        try { resolve(JSON.parse(buf.slice(0, nl))); }
+        catch { resolve({ ok: false, error: 'bad json from extension' }); }
+        sock.destroy();
+      }
+    });
+    sock.on('error', (err) => {
+      log('socket error [' + req.cmd + ']: ' + err.message);
+      resolve({ ok: false, error: `socket error: ${err.message}` });
+      sock.destroy();
+    });
+    sock.on('timeout', () => {
+      log('socket timeout [' + req.cmd + '] after ' + timeout + 'ms');
+      resolve({ ok: false, error: 'socket timeout' });
+      sock.destroy();
+    });
+  });
+}
+
+// ─── Worker binary resolution (project-scoped override) ─────────────────────
+// Returns the claude binary name to spawn for workers. Lookup order:
+//   1. <cwd>/.claws/claude-bin file (per-project override, gitignored) — read
+//      first line, trimmed. Used by Claws-on-Claws development to spawn workers
+//      under a different Claude account (e.g. 'claude-neu' shell alias).
+//   2. CLAWS_CLAUDE_BIN env var (per-shell override).
+//   3. Default: 'claude' (end-user default — no behavior change for downstream).
+// File-based override is preferred because .claws/ is project-local and survives
+// MCP restarts without requiring shell-env propagation through Claude Code.
+function getClaudeBin(cwd) {
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const f = path.join(cwd || process.cwd(), '.claws', 'claude-bin');
+    if (fs.existsSync(f)) {
+      const v = fs.readFileSync(f, 'utf8').trim().split(/\r?\n/)[0];
+      if (v) return v;
+    }
+  } catch (_e) { /* fall through */ }
+  return process.env.CLAWS_CLAUDE_BIN || 'claude';
+}
+
+// ─── Persistent connection for stateful claws/2 commands ─────────────────────
+// claws/2 peer state (registered by hello, consumed by publish/subscribe/
+// broadcast/task.*) is bound to a single TCP connection on the server. Per-call
+// sockets break multi-step flows: hello registers on socket A, then A is
+// destroyed; the next call opens socket B which has no peer, and publish fails
+// with "call hello first". One persistent socket is shared across all stateful
+// tool calls for the lifetime of this MCP server process.
+
+const _pconn = {
+  socket: null,           // net.Socket | null
+  pending: new Map(),     // rid → { resolve, reject, timer }
+  buf: '',                // line-buffered receive buffer
+  nextRid: 1_000_000,    // high range avoids collision with per-call counter
+  peerId: null,           // allocated by server after successful hello
+  role: null,             // cached for reconnect re-registration
+  peerName: null,
+  capabilities: null,
+  sockPath: null,         // set on first successful connect
+  connected: false,
+  socketId: 0,            // monotonic counter incremented per _pconnConnect; identifies current socket
+  helloSocketId: null,    // socketId of the socket on which hello last succeeded; null if none
+};
+
+// ─── Push-frame ring buffer ───────────────────────────────────────────────────
+// Captures every push frame delivered on the persistent socket so the
+// orchestrator can drain them via claws_drain_events without needing an active
+// subscription loop.
+const _eventBuffer = {
+  ring: [],             // { absoluteIndex, topic, from, payload, sentAt, sequence }
+  maxSize: 1000,        // evict oldest when full
+  totalReceived: 0,     // monotonically increasing; used as cursor by callers
+  waiters: [],          // { resolve, timer } registered by drain with wait_ms > 0
+  maxWaiters: 10,       // cap: reject new wait_ms requests beyond this
+  subscribed: false,    // true once we've sent hello + subscribe("**") on _pconn
+  subscribeCursor: null, // event-log cursor at moment of subscription (Fix-D late-join detection)
+  _overflowPending: false, // guards single system.bus.ring-overflow per eviction batch
+  seenSequences: new Set(), // BUG-01: dedup frames delivered twice by overlapping subscriptions
+};
+
+let _pconnConnecting = null; // Promise | null — guards concurrent connect attempts
+let _pconnSocketSeq  = 0;   // PCONN-DEBUG: monotonic socket ID for tracing socket identity
+
+// Wave D — terminal IDs (strings) for which system.worker.terminated was received.
+// Populated by _pconnHandleData; read by detectCompletion as 4th completion signal.
+const _workerTerminatedSet = new Set();
+
+// AF-AC Phase 1 — terminal IDs (strings) for which system.worker.process_exited was received.
+// Populated by _pconnHandleData; checked by _setupDetachWatcher as the new primary completion signal.
+// Keyed by termId string; value is { exitCode, correlationId, ts }.
+const _workerProcessExitedSet = new Map();
+
+// LH-9 hygiene: VS Code extension reload restarts the terminal id counter,
+// so a fresh spawn can legitimately reuse an id that lives in the stale
+// _workerTerminatedSet / _workerCompletedViaBusSet from a prior session.
+// Without this clear, the very first watcher tick after spawn fires the
+// terminated/completed branch in detectCompletion and instantly auto-closes
+// the new terminal (~1.5s lifespan). Every spawn handler must call this
+// before entering its watcher loop.
+function _clearStaleCompletionSignals(termId) {
+  const key = String(termId);
+  _workerTerminatedSet.delete(key);
+  _workerCompletedViaBusSet.delete(key);
+  _workerProcessExitedSet.delete(key);
+}
+// True once _pconn has subscribed to system.worker.terminated.
+let _workerTerminatedSubscribed = false;
+// AF-AC Phase 1: true once _pconn has subscribed to system.worker.process_exited.
+let _workerProcessExitedSubscribed = false;
+// Phase 4a — bus-based completion: termId -> { payload, ts } for workers that published
+// worker.<termId>.complete directly to the bus. Checked first in detectCompletion,
+// bypassing pty scraping entirely. Map is append-only; entries survive until the MCP server exits.
+const _workerCompletedViaBusSet = new Map();
+let _workerBusCompletedSubscribed = false;
+// W8ac-2: one-shot listeners for _waitForWorkerReady, keyed by "${topic}:${corrId}".
+const _workerReadyWaiters = new Map();
+let _workerPeerConnectedSubscribed = false;
+let _workerTerminalReadySubscribed = false;
+// AE-7: submit event waiters. Keys:
+//   'vehicle-content:<termId>'           — fires on vehicle.<termId>.content bus event
+//   'tool-invoked:<corrId>'              — fires on tool.+.invoked from matching worker peer
+//   'system.terminal.closed:<corrId>'   — lifecycle abort
+//   'system.worker.terminated:<corrId>' — lifecycle abort
+const _submitWaiters = new Map();
+// AE-7: peerId → corrId map, populated on system.peer.connected for tool.invoked routing.
+const _peerIdToCorrId = new Map();
+let _vehicleContentSubscribed = false;
+let _toolInvokedSubscribed = false;
+let _helloInFlight   = null; // Promise | null — deduplicates concurrent hello sends
+
+// Circuit breaker for _pconnEnsureRegistered and _scanAndPublishCLAWSPUB.
+// Prevents repeated expensive reconnect attempts when the extension socket is down.
+const _circuitBreaker = {
+  lastFailureTs: 0,       // epoch ms of most recent connect failure
+  scanConsecutiveErrors: 0, // consecutive _scanAndPublishCLAWSPUB socket failures
+  scanDisabled: false,    // true after 3 consecutive scan errors; reset on explicit reconnect
+};
+
+function _pconnHandleData(data) {
+  _pconn.buf += data.toString('utf8');
+  let nl;
+  while ((nl = _pconn.buf.indexOf('\n')) !== -1) {
+    const line = _pconn.buf.slice(0, nl);
+    _pconn.buf = _pconn.buf.slice(nl + 1);
+    if (!line.trim()) continue;
+    try {
+      const msg = JSON.parse(line);
+      // Server encodes both `id` and `rid`; match on `rid` first.
+      const rid = msg.rid != null ? msg.rid : msg.id;
+      if (rid != null && _pconn.pending.has(rid)) {
+        const { resolve, timer } = _pconn.pending.get(rid);
+        clearTimeout(timer);
+        _pconn.pending.delete(rid);
+        resolve(msg);
+      } else if (rid == null && (msg.push === 'message' || msg.topic != null)) {
+        // BUG-01: skip duplicate delivery caused by overlapping subscriptions sharing a sequence.
+        if (msg.sequence != null) {
+          if (_eventBuffer.seenSequences.has(msg.sequence)) continue;
+          _eventBuffer.seenSequences.add(msg.sequence);
+          if (_eventBuffer.seenSequences.size > 2000) {
+            const _seqArr = [..._eventBuffer.seenSequences];
+            _eventBuffer.seenSequences = new Set(_seqArr.slice(-1000));
+          }
+        }
+        // Push frame (no rid) — buffer for claws_drain_events.
+        const entry = {
+          absoluteIndex: ++_eventBuffer.totalReceived,
+          topic: msg.topic || '',
+          from: msg.from || '',
+          payload: msg.payload != null ? msg.payload : null,
+          sentAt: msg.sentAt || null,
+          sequence: msg.sequence != null ? msg.sequence : null,
+        };
+        _eventBuffer.ring.push(entry);
+        // Wave D: track terminated terminals so detectCompletion can use them.
+        if (entry.topic === 'system.worker.terminated' && entry.payload && entry.payload.terminal_id) {
+          _workerTerminatedSet.add(String(entry.payload.terminal_id));
+        }
+        // AF-AC Phase 1: track process_exited events so detach watcher can resolve completion.
+        if (entry.topic === 'system.worker.process_exited' && entry.payload && entry.payload.terminal_id) {
+          const _pexTermId = String(entry.payload.terminal_id);
+          _workerProcessExitedSet.set(_pexTermId, {
+            exitCode: entry.payload.exit_code,
+            correlationId: entry.payload.correlation_id || null,
+            ts: Date.now(),
+          });
+          log(`AF-AC: system.worker.process_exited received termId=${_pexTermId} corrId=${entry.payload.correlation_id || 'none'} exitCode=${entry.payload.exit_code}`);
+        }
+        // Phase 4a: bus-based completion — worker.<termId>.complete wildcard.
+        if (entry.topic && /^worker\.[^.]+\.complete$/.test(entry.topic) && entry.payload) {
+          const _busTermId = entry.topic.split('.')[1];
+          _workerCompletedViaBusSet.set(String(_busTermId), { payload: entry.payload, ts: Date.now() });
+          log(`Phase 4a: received worker.${_busTermId}.complete via bus, payload: ${JSON.stringify(entry.payload).slice(0, 120)}`);
+        }
+        // W8ac-2: resolve _waitForWorkerReady listeners keyed by topic + correlation_id.
+        if ((entry.topic === 'system.peer.connected' || entry.topic === 'system.terminal.ready')
+            && entry.payload && entry.payload.correlation_id) {
+          const waiterKey = `${entry.topic}:${entry.payload.correlation_id}`;
+          const waiterResolve = _workerReadyWaiters.get(waiterKey);
+          if (waiterResolve) {
+            _workerReadyWaiters.delete(waiterKey);
+            waiterResolve(entry.payload);
+          }
+        }
+        // AE-7: populate peerId→corrId map on system.peer.connected for tool.invoked routing.
+        if (entry.topic === 'system.peer.connected' && entry.payload
+            && entry.payload.peer_id && entry.payload.correlation_id) {
+          _peerIdToCorrId.set(entry.payload.peer_id, entry.payload.correlation_id);
+        }
+        // AE-6.b: fire cancel-key listeners when worker lifecycle ends before boot signal.
+        if ((entry.topic === 'system.terminal.closed' || entry.topic === 'system.worker.terminated')
+            && entry.payload && entry.payload.correlation_id) {
+          const cancelKey = `${entry.topic}:${entry.payload.correlation_id}`;
+          const cancelFn = _workerReadyWaiters.get(cancelKey);
+          if (cancelFn) cancelFn();
+          // AE-7: also fire submit waiters keyed by lifecycle-end topic + corrId.
+          const submitCancelFn = _submitWaiters.get(cancelKey);
+          if (submitCancelFn) submitCancelFn();
+        }
+        // AE-7: dispatch vehicle.<termId>.content → _submitWaiters for submit confirmation.
+        if (entry.topic && /^vehicle\.[^.]+\.content$/.test(entry.topic)) {
+          const _vcTermId = entry.topic.split('.')[1];
+          const fn = _submitWaiters.get(`vehicle-content:${_vcTermId}`);
+          if (fn) fn(entry.payload);
+        }
+        // AF-3 Layer 2: dispatch system.terminal.paste_complete → _submitWaiters.
+        if (entry.topic === 'system.terminal.paste_complete' && entry.payload && entry.payload.terminalId) {
+          const fn = _submitWaiters.get(`paste-complete:${entry.payload.terminalId}`);
+          if (fn) fn(entry.payload);
+        }
+        // AE-7: dispatch tool.+.invoked → _submitWaiters via peerId→corrId lookup.
+        // AF-3 Layer 4: prefer payload.correlation_id (race-immune) over map lookup.
+        if (entry.topic && /^tool\.[^.]+\.invoked$/.test(entry.topic)) {
+          const _fromPeer = (entry.payload && entry.payload.peerId) || entry.from;
+          const _toolCorrId = (entry.payload && entry.payload.correlation_id)
+            || (_fromPeer ? _peerIdToCorrId.get(_fromPeer) : null);
+          if (_fromPeer && _toolCorrId && !_peerIdToCorrId.has(_fromPeer)) {
+            _peerIdToCorrId.set(_fromPeer, _toolCorrId);
+          }
+          if (_toolCorrId) {
+            const fn = _submitWaiters.get(`tool-invoked:${_toolCorrId}`);
+            if (fn) fn(entry.payload);
+          }
+        }
+        if (_eventBuffer.ring.length > _eventBuffer.maxSize) {
+          _eventBuffer.ring.shift();
+          // Emit ring-overflow once per eviction so callers know events were dropped.
+          if (!_eventBuffer._overflowPending) {
+            _eventBuffer._overflowPending = true;
+            setImmediate(() => {
+              _eventBuffer._overflowPending = false;
+              const overflowEntry = {
+                absoluteIndex: ++_eventBuffer.totalReceived,
+                topic: 'system.bus.ring-overflow',
+                from: 'mcp-server',
+                payload: { droppedAt: new Date().toISOString(), ringSize: _eventBuffer.maxSize },
+                sentAt: new Date().toISOString(),
+                sequence: null,
+              };
+              _eventBuffer.ring.push(overflowEntry);
+            });
+          }
+        }
+        const woke = _eventBuffer.waiters.splice(0);
+        for (const w of woke) { clearTimeout(w.timer); w.resolve(); }
+      }
+    } catch { /* ignore malformed frames */ }
+  }
+}
+
+function _pconnHandleClose() {
+  _pconn.connected = false;
+  _pconn.socket = null;
+  _pconn.buf = '';
+  _pconn.peerId = null;
+  _pconn.helloSocketId = null;  // invalidate hello state — new socket requires fresh hello
+  _eventBuffer.subscribed = false; // reconnect requires fresh auto-subscribe
+  _workerTerminatedSubscribed = false; // reconnect requires re-subscribe
+  _workerBusCompletedSubscribed = false; // reconnect requires re-subscribe
+  _workerPeerConnectedSubscribed = false;
+  _workerTerminalReadySubscribed = false;
+  _vehicleContentSubscribed = false;
+  _toolInvokedSubscribed = false;
+  for (const [, { reject, timer }] of _pconn.pending) {
+    clearTimeout(timer);
+    reject(new Error('persistent socket closed'));
+  }
+  _pconn.pending.clear();
+  // Schedule reconnect; on success, re-issue hello if we had a prior identity.
+  if (_pconn.sockPath) {
+    const sp = _pconn.sockPath;
+    setTimeout(async () => {
+      try {
+        await _pconnEnsure(sp);
+        log(`PCONN-DEBUG: reconnect-ensure-done | peerId=${_pconn.peerId} | role=${_pconn.role}`);
+        if (_pconn.role && !_pconn.peerId) {
+          log(`PCONN-DEBUG: reconnect-about-to-hello | role=${_pconn.role}`);
+          const resp = await _pconnWriteOrThrow({
+            cmd: 'hello', protocol: 'claws/2',
+            role: _pconn.role, peerName: _pconn.peerName,
+            capabilities: _pconn.capabilities || undefined,
+          }, 5000);
+          log(`PCONN-DEBUG: reconnect-hello-ack | ok=${resp && resp.ok} | peerId=${resp && resp.peerId}`);
+          _pconn.peerId = resp.peerId;
+          _pconn.helloSocketId = _pconn.socketId;  // bind hello to this socket
+          log(`reconnected and re-registered as ${resp.peerId} role=${_pconn.role}`);
+        }
+      } catch (e) { log(`PCONN-DEBUG: reconnect-failed | err=${e && e.message || e}`); }
+    }, 1000);
+  }
+}
+
+function _pconnConnect(sockPath) {
+  return new Promise((resolve, reject) => {
+    const sock = net.createConnection(sockPath);
+    const _sockId = ++_pconnSocketSeq;
+    log(`PCONN-DEBUG: connect-attempt | sockId=${_sockId} | socket=${sockPath}`);
+    // M-50: 5s connect timeout — prevents _pconnConnect from hanging forever
+    // when the extension socket exists but VS Code is reloading (ECONNREFUSED
+    // can take arbitrarily long on some platforms without a ceiling).
+    sock.setTimeout(5000);
+    sock.on('timeout', () => sock.destroy(new Error('persistent socket connect timed out')));
+    sock.on('connect', () => {
+      sock.setTimeout(0); // clear connect-phase timeout once connected
+      _pconn.socket = sock;
+      _pconn.sockPath = sockPath;
+      _pconn.connected = true;
+      _pconn.socketId = _sockId;  // record which socket is now active
+      sock._pconnSocketId = _sockId; // attach for event correlation in close/error handlers
+      log(`PCONN-DEBUG: connected | sockId=${_sockId}`);
+      resolve();
+    });
+    sock.on('data', _pconnHandleData);
+    sock.on('error', (err) => {
+      if (!_pconn.connected) {
+        log(`PCONN-DEBUG: connect-error | sockId=${_sockId} | err=${err.message}`);
+        reject(err);
+      } else {
+        log(`PCONN-DEBUG: socket-event | type=error | sockId=${_sockId} | err=${err.message}`);
+        log('persistent socket error: ' + err.message);
+      }
+    });
+    sock.on('close', () => {
+      log(`PCONN-DEBUG: socket-event | type=close | sockId=${_sockId} | peerId=${_pconn.peerId}`);
+      _pconnHandleClose();
+    });
+  });
+}
+
+function _pconnEnsure(sockPath) {
+  if (_pconn.connected) return Promise.resolve();
+  if (_pconnConnecting) return _pconnConnecting;
+  _pconnConnecting = _pconnConnect(sockPath).finally(() => { _pconnConnecting = null; });
+  return _pconnConnecting;
+}
+
+function _pconnWrite(req, timeout) {
+  return new Promise((resolve, reject) => {
+    if (!_pconn.socket || !_pconn.connected) {
+      return reject(new Error('persistent socket not connected'));
+    }
+    const rid = _pconn.nextRid++;
+    const ms = timeout || 30000;
+    const _topic = req.topic || '';
+    log(`PCONN-DEBUG: write-start | rid=${rid} | cmd=${req.cmd} | topic=${_topic} | peerId=${_pconn.peerId}`);
+    const timer = setTimeout(() => {
+      _pconn.pending.delete(rid);
+      reject(new Error('stateful socket timeout'));
+    }, ms);
+    _pconn.pending.set(rid, {
+      resolve: (resp) => {
+        log(`PCONN-DEBUG: write-response | rid=${rid} | cmd=${req.cmd} | ok=${resp && resp.ok} | error=${resp && resp.error || ''}`);
+        if (resp && resp.ok === false) {
+          log(`PCONN-DEBUG: write-failed-silently | rid=${rid} | cmd=${req.cmd} | topic=${_topic} | error=${resp.error}`);
+        }
+        resolve(resp);
+      },
+      reject,
+      timer,
+    });
+    try {
+      // Stateful commands route via taskId/assignee/subscriptionId/peerId — never 'id'.
+      // Explicitly drop any user-supplied 'id' before stamping the RPC correlation id,
+      // so a future command carrying 'id' as a routing field cannot be silently misrouted.
+      const { id: _discarded, ...reqBody } = req;
+      _pconn.socket.write(JSON.stringify({ ...reqBody, id: rid }) + '\n');
+    } catch (err) {
+      clearTimeout(timer);
+      _pconn.pending.delete(rid);
+      reject(err);
+    }
+  });
+}
+
+// Like _pconnWrite but throws if the response has ok !== true. Use at every
+// call site that publishes or does stateful work so silent ok:false failures
+// surface to the nearest catch block instead of being logged as success.
+async function _pconnWriteOrThrow(req, timeout) {
+  const resp = await _pconnWrite(req, timeout);
+  if (!resp || resp.ok !== true) {
+    throw new Error(`pconn write failed: ${resp && resp.error || 'no response'} (cmd=${req.cmd}${req.topic ? ' topic=' + req.topic : ''})`);
+  }
+  return resp;
+}
+
+// Persistent-socket RPC for stateful claws/2 commands. Connects the persistent
+// socket on first call; reuses it for all subsequent calls.
+async function clawsRpcStateful(sockPath, req, timeout) {
+  try {
+    await _pconnEnsure(sockPath);
+  } catch (err) {
+    return { ok: false, error: `persistent socket connect failed: ${err.message}` };
+  }
+  try {
+    return await _pconnWrite(req, timeout);
+  } catch (err) {
+    return { ok: false, error: `persistent socket error: ${err.message}` };
+  }
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+async function fileExec(sockPath, termId, command, timeoutMs = 180000) {
+  const execId = randomUUID().slice(0, 10);
+  const base = path.join(os.tmpdir(), 'claws-exec');
+  fs.mkdirSync(base, { recursive: true });
+  const outPath = path.join(base, `${execId}.out`);
+  const donePath = path.join(base, `${execId}.done`);
+  const wrapper = process.platform === 'win32'
+    ? `& { ${command} } *> '${outPath}' ; $LASTEXITCODE | Out-File -FilePath '${donePath}' -Encoding ascii`
+    : `{ ${command}; } > ${outPath} 2>&1; echo $? > ${donePath}`;
+  await clawsRpc(sockPath, { cmd: 'send', id: termId, text: wrapper, newline: true });
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(donePath)) break;
+    await sleep(150);
+  }
+  if (!fs.existsSync(donePath)) {
+    const partial = fs.existsSync(outPath) ? fs.readFileSync(outPath, 'utf8') : '';
+    return { ok: false, error: `timeout after ${timeoutMs}ms`, partial };
+  }
+  const exitRaw = fs.readFileSync(donePath, 'utf8').trim();
+  const exitCode = /^\d+$/.test(exitRaw) ? parseInt(exitRaw, 10) : null;
+  const output = fs.existsSync(outPath) ? fs.readFileSync(outPath, 'utf8') : '';
+  try { fs.unlinkSync(outPath); } catch {}
+  try { fs.unlinkSync(donePath); } catch {}
+  return { ok: true, terminal_id: termId, command, output, exit_code: exitCode };
+}
+
+// ─── Tool definitions (generated — run: cd extension && npm run schemas) ──────
+
+const TOOLS = require('./schemas/mcp-tools.json');
+
+// ─── Blocking worker lifecycle ─────────────────────────────────────────────
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// LH-15: server-side auto-wrap for claws_worker(command=...) shell missions.
+// Appends bus-event publish + canonical __CLAWS_DONE__ marker. Idempotent —
+// if user's command already contains the marker or [CLAWS_PUB] line, the
+// suffix is harmless (first occurrence triggers close, later ones ignored).
+function wrapShellCommand(rawCommand, terminalId) {
+  if (!rawCommand || typeof rawCommand !== 'string') return rawCommand;
+  const trimmed = rawCommand.trim();
+  const sep = (trimmed.endsWith(';') || trimmed.endsWith('&')) ? ' ' : ' ; ';
+  const tid = String(terminalId);
+  // Use semicolons (not &&) so wrapping fires even if user's command exits non-zero.
+  const suffix = process.platform === 'win32'
+    ? `${sep}Write-Output '[CLAWS_PUB] topic=worker.${tid}.complete data={"ok":true}' ; Write-Output '__CLAWS_DONE__'`
+    : `${sep}printf '[CLAWS_PUB] topic=worker.${tid}.complete data={"ok":true}\\n' ; printf '%s\\n' '__CLAWS_DONE__'`;
+  return `${rawCommand}${suffix}`;
+}
+
+// Find marker only when it appears in tool/output context — never in prose.
+// Real Claude pty patterns the matcher MUST accept:
+//   • bare-shell printf:        "MARKER\n"
+//   • Claude text response:     "⏺MARKER<trailing-spaces>\r…"
+//   • Claude tool-result line:  "  ⎿  MARKER\r…"
+//   • shell worker (LH-15):     "\MARKER\n"  (zsh wrap artifact)
+// Prose collisions the matcher MUST reject:
+//   • mission restatement:      "step 4. Echo MARKER on its own line."
+//   • shell command echo:       "% echo MARKER"
+//   • Claude action header:     "⏺Bash(echo 'MARKER')" — wait for the actual
+//                                tool result instead, never false-complete on
+//                                a Bash command that hasn't run yet.
+// Anchor: line start → optional whitespace OR backslash (zsh wrap artifact) →
+//         optional ⏺/⎿ indicator → optional whitespace → exact marker →
+//         whitespace/newline/EOT.
+function findStandaloneMarker(text, marker) {
+  if (!marker || typeof marker !== 'string' || !text) return null;
+  // Leading class tolerates zsh's `\` line-wrap artifact (emitted when prompt/echo wraps near
+  // right margin in long bracketed-paste commands). Without this, shell workers with long command
+  // lines miss marker detection. Verified live LH-15 (term 18 in v0.7.13).
+  const re = new RegExp(
+    '(?:^|[\\r\\n])[\\t \\\\]*[⏺⎿]?[\\t ]*' + escapeRegex(marker) + '(?=[\\t \\r\\n]|$)'
+  );
+  const m = re.exec(text);
+  if (m === null) return null;
+  const ls = text.lastIndexOf('\n', m.index);
+  const lineStart = ls === -1 ? 0 : ls + 1;
+  const lineEnd = text.indexOf('\n', lineStart);
+  return text.slice(lineStart, lineEnd === -1 ? text.length : lineEnd).trim();
+}
+
+// Backward-compat alias — internal callsites should prefer findStandaloneMarker.
+function findMarkerLine(text, marker) {
+  return findStandaloneMarker(text, marker);
+}
+
+// ─── [CLAWS_PUB] line scanner ─────────────────────────────────────────────────
+// SDK-less workers print [CLAWS_PUB] topic=<topic> key=val ... lines to stdout.
+// The MCP server scans new pty output for these markers each poll tick and
+// publishes on the worker's behalf — no socket, peerId, or SDK required.
+// Grammar:  [CLAWS_PUB] topic=<topic> key1=val key2="quoted val" key3=42
+// Values:   "..." → string  |  true/false → boolean  |  digits → number
+async function _scanAndPublishCLAWSPUB(newText, sockPath) {
+  // Circuit breaker: if 3 consecutive socket errors, stop scanning until reconnect.
+  if (_circuitBreaker.scanDisabled) return;
+  const MARKER_RE = /^\[CLAWS_PUB\]\s+topic=(\S+)\s*(.*)?$/;
+  const KV_RE = /(\w+)=("([^"]*)"|(\S+))/g;
+  for (const line of newText.split('\n')) {
+    const m = MARKER_RE.exec(line);
+    if (!m) continue;
+    const topic = m[1];
+    const rest = m[2] || '';
+    const payload = {};
+    KV_RE.lastIndex = 0;
+    let kv;
+    while ((kv = KV_RE.exec(rest)) !== null) {
+      const key = kv[1];
+      const rawVal = kv[3] !== undefined ? kv[3] : kv[4];
+      if (rawVal === 'true') payload[key] = true;
+      else if (rawVal === 'false') payload[key] = false;
+      else if (/^-?\d+(\.\d+)?$/.test(rawVal)) payload[key] = parseFloat(rawVal);
+      else payload[key] = rawVal;
+    }
+    try {
+      await _pconnEnsureRegistered(sockPath);
+      await _pconnWriteOrThrow({ cmd: 'publish', protocol: 'claws/2', topic, payload }, 3000);
+      _circuitBreaker.scanConsecutiveErrors = 0;
+    } catch (e) {
+      _circuitBreaker.scanConsecutiveErrors++;
+      log('[CLAWS_PUB] publish failed topic=' + topic + ': ' + (e && e.message || e));
+      if (_circuitBreaker.scanConsecutiveErrors >= 3) {
+        _circuitBreaker.scanDisabled = true;
+        log('[CLAWS_PUB] circuit breaker tripped after 3 consecutive socket errors — scan disabled until reconnect');
+        return;
+      }
+    }
+  }
+}
+
+// ─── HB-L1: Heartbeat parser primitives (pure functions, no side effects) ────
+// Per docs/heartbeat-architecture.md §V.E (TUI parsing patterns).
+// These are pure input→output helpers. They are NOT wired to any watcher yet;
+// integration comes in HB-L4. All functions operate on ANSI-stripped pty text.
+
+/**
+ * Parse Claude TUI tool indicators (⏺ Tool(args)) from new bytes.
+ * @param {string} text — full pty log (ANSI-stripped)
+ * @param {number} sinceOffset — start parsing from this byte offset
+ * @returns {Array<{tool: string, target: string, summary: string, atOffset: number}>}
+ */
+function parseToolIndicators(text, sinceOffset) {
+  if (!text || typeof text !== 'string') return [];
+  const slice = text.slice(sinceOffset || 0);
+  if (!slice) return [];
+
+  // Maps tool name → human-readable verb for summary field
+  const VERB = {
+    Read: 'reading', Edit: 'editing', Write: 'writing', Bash: 'running',
+    Grep: 'searching', Glob: 'globbing', Task: 'delegating',
+    TodoWrite: 'planning', WebFetch: 'fetching', WebSearch: 'searching web',
+    NotebookEdit: 'editing notebook',
+  };
+
+  // ⏺ ToolName(args) — Claude Code's standard indicator line
+  // \s* not \s+: TUI renders ⏺Bash( with zero whitespace (audit 6c1bd43)
+  const RE = /⏺\s*([\w]+)\(([^)]*)\)/g;
+  const results = [];
+  let m;
+  while ((m = RE.exec(slice)) !== null) {
+    const tool = m[1];
+    const rawArgs = (m[2] || '').trim();
+    const atOffset = (sinceOffset || 0) + m.index;
+
+    let target = rawArgs;
+    let summary;
+    if (tool === 'Bash') {
+      // Truncate long bash commands for readability
+      summary = 'running: ' + (rawArgs.length > 60 ? rawArgs.slice(0, 57) + '…' : rawArgs);
+      target = rawArgs;
+    } else if (tool === 'TodoWrite') {
+      summary = 'planning: tasks';
+      target = '';
+    } else if (tool === 'Task') {
+      summary = 'delegating to subagent';
+      target = rawArgs;
+    } else if (tool === 'WebSearch') {
+      summary = 'searching web';
+      target = rawArgs;
+    } else if (tool === 'NotebookEdit') {
+      summary = 'editing notebook';
+      target = rawArgs;
+    } else {
+      // For file-path tools (Read/Edit/Write/Grep/Glob/WebFetch) use basename
+      const basename = rawArgs.split('/').pop() || rawArgs;
+      const verb = VERB[tool] || tool.toLowerCase();
+      summary = verb + ' ' + basename;
+      target = rawArgs;
+    }
+    results.push({ tool, target, summary, atOffset });
+  }
+  return results;
+}
+
+/**
+ * Parse the latest cost/tokens footer line from Claude TUI render.
+ * Pattern: [████░░░░░░] 51%  in:2.6k  out:26.3k  cost:$2369.32
+ * @param {string} text — full pty log (ANSI-stripped)
+ * @returns {{tokens_in: number, tokens_out: number, cost_usd: number, percent: number} | null}
+ */
+function parseCostFooter(text) {
+  if (!text || typeof text !== 'string') return null;
+  // Match the last occurrence of the footer pattern (most up-to-date)
+  const RE = /\[\S+\]\s+(\d+)%\s+in:([\d.]+)([kKmM]?)\s+out:([\d.]+)([kKmM]?)\s+cost:\$([\d.]+)/g;
+  let last = null;
+  let m;
+  while ((m = RE.exec(text)) !== null) {
+    last = m;
+  }
+  if (!last) return null;
+
+  function expandK(num, suffix) {
+    const n = parseFloat(num);
+    const s = (suffix || '').toLowerCase();
+    if (s === 'k') return Math.round(n * 1000);
+    if (s === 'm') return Math.round(n * 1000000);
+    return n;
+  }
+
+  return {
+    percent:    parseInt(last[1], 10),
+    tokens_in:  expandK(last[2], last[3]),
+    tokens_out: expandK(last[4], last[5]),
+    cost_usd:   parseFloat(last[6]),
+  };
+}
+
+/**
+ * Detect spinner activity (✻/✶/✳/✢/✽/✺/· prefix with "X for Ns" pattern).
+ * @param {string} text — full pty log
+ * @param {number} sinceOffset
+ * @returns {{lastSpinnerAt: number | null, isActive: boolean}}
+ *   lastSpinnerAt is byte offset of the last spinner indicator found
+ */
+function parseSpinnerActivity(text, sinceOffset) {
+  if (!text || typeof text !== 'string') return { lastSpinnerAt: null, isActive: false };
+  const slice = text.slice(sinceOffset || 0);
+  if (!slice) return { lastSpinnerAt: null, isActive: false };
+
+  // Claude's spinner: one of these unicode chars followed by a word and "for Ns"
+  const RE = /[✻✶✳✢✽✺·]\s+\w[\w\s]*for\s+\d+s/g;
+  let lastMatch = null;
+  let m;
+  while ((m = RE.exec(slice)) !== null) {
+    lastMatch = m;
+  }
+
+  if (!lastMatch) return { lastSpinnerAt: null, isActive: false };
+
+  const lastSpinnerAt = (sinceOffset || 0) + lastMatch.index;
+  // "active" means the spinner appeared near the end of the captured slice
+  // (within the last 200 chars — roughly one TUI render frame)
+  const isActive = lastMatch.index >= slice.length - 200;
+  return { lastSpinnerAt, isActive };
+}
+
+/**
+ * Parse TodoWrite tool blocks for the planned tasks.
+ * @param {string} text — full pty log
+ * @param {number} sinceOffset
+ * @returns {{todoItems: string[], atOffset: number} | null}
+ */
+function parseTodoWrite(text, sinceOffset) {
+  if (!text || typeof text !== 'string') return null;
+  const slice = text.slice(sinceOffset || 0);
+  if (!slice) return null;
+
+  // TodoWrite indicator followed by a todo block (lines prefixed with ☐/☑/□/✓/- /• or numbered)
+  // Claude renders TodoWrite then shows the task list indented under the tool call
+  const todoCallIdx = slice.indexOf('⏺ TodoWrite');
+  if (todoCallIdx === -1) return null;
+
+  // Collect lines after the TodoWrite indicator
+  const afterCall = slice.slice(todoCallIdx);
+  const lines = afterCall.split(/\r?\n/);
+  const items = [];
+
+  // Skip the first line (the ⏺ TodoWrite(…) line itself) and collect task items
+  for (let i = 1; i < lines.length; i++) {
+    const raw = lines[i].trim();
+    if (!raw) continue;
+    // Stop if we hit a new tool indicator or ANSI reset / empty block
+    if (/^[⏺⎿]/.test(raw)) break;
+    // Match common list markers: ☐ ☑ □ ✓ ✗ - • * or "N." numbered
+    const itemMatch = raw.match(/^(?:[☐☑□✓✗•\-*]|\d+\.)\s+(.+)$/);
+    if (itemMatch) {
+      items.push(itemMatch[1].trim());
+    }
+  }
+
+  if (items.length === 0) return null;
+  return { todoItems: items, atOffset: (sinceOffset || 0) + todoCallIdx };
+}
+
+/**
+ * Detect error indicators in tool results (⎿ Error: ... or non-zero exit codes).
+ * Conservative — only fires on unambiguous patterns to avoid false positives.
+ * @param {string} text — full pty log
+ * @param {number} sinceOffset
+ * @returns {Array<{kind: 'error' | 'exit_nonzero', detail: string, atOffset: number}>}
+ */
+function parseErrorIndicators(text, sinceOffset) {
+  if (!text || typeof text !== 'string') return [];
+  const slice = text.slice(sinceOffset || 0);
+  if (!slice) return [];
+
+  const results = [];
+
+  // Pattern 1: ⎿ Error: <message>  — Claude's tool result error prefix (unambiguous)
+  const ERR_RE = /⎿\s+Error:\s*([^\n\r]+)/g;
+  let m;
+  while ((m = ERR_RE.exec(slice)) !== null) {
+    results.push({
+      kind: 'error',
+      detail: m[1].trim().slice(0, 200),
+      atOffset: (sinceOffset || 0) + m.index,
+    });
+  }
+
+  // Pattern 2: ⎿ … exit code N (N ≠ 0) — bash non-zero exits via tool result
+  const EXIT_RE = /⎿[^\n\r]*exit\s+code\s+(\d+)/g;
+  while ((m = EXIT_RE.exec(slice)) !== null) {
+    const code = parseInt(m[1], 10);
+    if (code !== 0) {
+      results.push({
+        kind: 'exit_nonzero',
+        detail: 'exit code ' + code,
+        atOffset: (sinceOffset || 0) + m.index,
+      });
+    }
+  }
+
+  // Sort by offset so results are in source order
+  results.sort((a, b) => a.atOffset - b.atOffset);
+  return results;
+}
+
+// ─── HB-L3: WorkerHeartbeatStateMachine ──────────────────────────────────────
+// Per docs/heartbeat-architecture.md §V.C and docs/heartbeat-action-plan.md
+// §II.A3 Layer 3. Pure state-tracking logic — uses L1 parsers, derives
+// transitions, but does NOT publish anything (that's HB-L4+).
+
+/**
+ * Heartbeat state machine for one worker terminal. Observes pty bytes,
+ * derives state transitions, surfaces transition events. Does NOT publish
+ * to the bus (that's HB-L4+). Pure logic.
+ *
+ * States: BOOTING → READY → WORKING (observability only; completion via external signals)
+ *
+ * Per docs/heartbeat-architecture.md §V.C.
+ */
+class WorkerHeartbeatStateMachine {
+  constructor({ terminalId, correlationId }) {
+    this.terminalId = terminalId;
+    this.correlationId = correlationId;
+    this.state = 'BOOTING';
+    this.scanOffset = 0;
+    this.firstActivityAt = null;    // first time we saw any tool
+    this.lastSpinnerAt = null;      // last timestamp spinner was active
+    this.lastToolAt = null;         // last timestamp a tool indicator was seen
+    this.lastNewBytesAt = null;     // last timestamp new pty bytes arrived
+    this.toolCount = 0;             // total tools observed (mission_complete gate requires ≥1)
+    this.postWorkEnteredAt = null;  // when POST_WORK conditions first held
+    this.startedAt = Date.now();
+    this.cumulative = { tokens_in: 0, tokens_out: 0 };
+    this.todoItems = null;          // last TodoWrite seen
+    this.lastErrors = [];           // accumulator for error events
+    this.transitions = [];          // log of all state transitions for inspection
+  }
+
+  /**
+   * Observe new pty content. Updates state, returns transitions detected this tick.
+   * @param {string} text — full pty log (ANSI-stripped)
+   * @param {number} [now] — current timestamp (injectable for deterministic testing)
+   * @returns {Array<{from: string, to: string, reason: string, at: number}>}
+   */
+  observe(text, now = Date.now()) {
+    if (!text || typeof text !== 'string') return [];
+
+    const prevOffset = this.scanOffset;
+    const detected = [];
+
+    // 1. Track new bytes
+    if (text.length > prevOffset) {
+      this.lastNewBytesAt = now;
+    }
+
+    // 2. Run L1 parsers on new bytes since prevOffset
+
+    const spinnerResult = parseSpinnerActivity(text, prevOffset);
+    if (spinnerResult.lastSpinnerAt !== null) {
+      this.lastSpinnerAt = now;
+    }
+
+    const tools = parseToolIndicators(text, prevOffset);
+    if (tools.length > 0) {
+      if (this.firstActivityAt === null) this.firstActivityAt = now;
+      this.lastToolAt = now;
+      this.toolCount += tools.length;
+    }
+
+    const footer = parseCostFooter(text);
+    if (footer) {
+      this.cumulative.tokens_in = footer.tokens_in;
+      this.cumulative.tokens_out = footer.tokens_out;
+    }
+
+    const todo = parseTodoWrite(text, prevOffset);
+    if (todo) {
+      this.todoItems = todo.todoItems;
+    }
+
+    const errors = parseErrorIndicators(text, prevOffset);
+    for (const err of errors) {
+      this.lastErrors.push(err);
+    }
+
+    // 3. State machine transitions (one transition per observe() tick max per branch)
+    if (this.state === 'BOOTING') {
+      // BOOTING → READY: bypass permissions text is the unambiguous boot signal
+      if (text.includes('bypass permissions')) {
+        detected.push(this._transition('BOOTING', 'READY', 'bypass-permissions-detected', now));
+      }
+
+    } else if (this.state === 'READY') {
+      // READY → WORKING: first tool call observed (cumulative so cascade tick still fires)
+      if (this.toolCount > 0) {
+        detected.push(this._transition('READY', 'WORKING', 'first-tool-call', now));
+      }
+
+    }
+
+    // 4. Advance scan offset to avoid re-parsing seen bytes
+    this.scanOffset = text.length;
+
+    return detected;
+  }
+
+  _transition(from, to, reason, at) {
+    this.state = to;
+    const t = { from, to, reason, at };
+    this.transitions.push(t);
+    return t;
+  }
+
+  /** Snapshot current state for debugging / tests. */
+  snapshot() {
+    return {
+      state: this.state,
+      toolCount: this.toolCount,
+      lastSpinnerAt: this.lastSpinnerAt,
+      lastToolAt: this.lastToolAt,
+      lastNewBytesAt: this.lastNewBytesAt,
+      firstActivityAt: this.firstActivityAt,
+      postWorkEnteredAt: this.postWorkEnteredAt,
+      durationMs: Date.now() - this.startedAt,
+      cumulative: { ...this.cumulative },
+      todoItems: this.todoItems,
+      errorsCount: this.lastErrors.length,
+    };
+  }
+}
+
+// ─── Multi-signal completion detector (Task #58 — idle-timeout removed) ──────
+// Pure function. Returns { status, line, signal } if an event-driven signal
+// fires, else null. signal in {'marker','error','pub_complete'}.
+// Priority: marker > error > pub_complete.
+//
+// idle_timeout (polling-based) was removed in v0.7.10 — it killed Claude TUI
+// workers mid-thinking and contradicted the pub/sub event-driven architecture.
+// Proper completion fallback will come from VS Code's onDidCloseTerminal →
+// system.worker.terminated bus event (planned).
+function detectCompletion(text, opt, termId, terminatedSet, busCompletedSet) {
+  // 1. Phase 4a: bus completion — highest priority, bypasses pty scraping entirely.
+  if (busCompletedSet && busCompletedSet.has(String(termId))) {
+    const _busEntry = busCompletedSet.get(String(termId));
+    const _busStatus = _busEntry.payload && _busEntry.payload.status === 'failed' ? 'failed' : 'completed';
+    return { status: _busStatus, line: _busEntry.payload && _busEntry.payload.summary || null, signal: 'pub_complete_v2' };
+  }
+  // 2. marker
+  const m = findStandaloneMarker(text, opt.complete_marker);
+  if (m !== null) return { status: 'completed', line: m, signal: 'marker' };
+  // 3. error
+  for (const em of (opt.error_markers || [])) {
+    const e = em ? findStandaloneMarker(text, em) : null;
+    if (e !== null) return { status: 'failed', line: e, signal: 'error' };
+  }
+  // 4. explicit pub-complete: [CLAWS_PUB] topic=worker.<termId>.complete
+  const pubTopic = `worker.${termId}.complete`;
+  const pubLine = findStandaloneMarker(text, `[CLAWS_PUB] topic=${pubTopic}`);
+  if (pubLine !== null) return { status: 'completed', line: pubLine, signal: 'pub_complete' };
+  // 5. terminated: VS Code onDidCloseTerminal → system.worker.terminated bus event.
+  //    Belt-and-suspenders for workers that succeed but skip the printf marker.
+  if (terminatedSet && terminatedSet.has(String(termId))) {
+    return { status: 'terminated', line: null, signal: 'terminated' };
+  }
+  return null;
+}
+
+// ─── Shared detach-watcher factory ───────────────────────────────────────────
+// _fpTick (claws_worker fast-path) and _dswTick (claws_dispatch_subworker)
+// were near-identical ~150-line implementations that drifted: BUG-26 was
+// applied asymmetrically; _dswCwd (Bug 11) lived undetected for the same
+// reason. Single implementation below; applied at both sites.
+// tick (runBlockingWorker detach) is structurally different (no HB state
+// machine, dead _msState tracking, different timeout behavior) and is kept
+// in place.
+//
+// Params:
+//   sock            — Claws socket path
+//   termId          — terminal ID
+//   corrId          — correlation UUID for this worker
+//   opt             — { complete_marker, error_markers, timeout_ms, poll_interval_ms, close_on_complete }
+//   markerScanFrom  — log offset to start scanning for completion markers (0 for Claude TUI workers)
+//   hbState         — WorkerHeartbeatStateMachine instance (required — always pass one)
+//   startedAt       — spawn timestamp (ms)
+//   extraPayload    — extra fields merged into system.worker.completed payload
+//                     fp: { booted: launchClaude }  dsw: { waveId, role }
+//   closeOnTimeout  — if true, close terminal + mark closed on timeout (dsw behavior; fp=false)
+function _setupDetachWatcher({ sock, termId, corrId, opt, markerScanFrom, hbState, startedAt, extraPayload, closeOnTimeout = false }) {
+  let pubScanOffset = 0;
+  let hbLastPublishedAt = Date.now();
+  let progressBurst = [];
+  let progressBurstStart = 0;
+  let lastPublishedToolCount = 0;
+  let lastTodoSig = '';
+  let lastPublishedErrorsCount = 0;
+
+  const tick = async () => {
+    try {
+      if (Date.now() > startedAt + opt.timeout_ms) {
+        clearInterval(intervalId);
+        _detachWatchers.delete(termId);
+        try {
+          await _pconnEnsureRegistered(sock);
+          await _pconnWriteOrThrow({ cmd: 'publish', protocol: 'claws/2', topic: 'system.worker.completed',
+            payload: { terminal_id: termId, status: 'timeout', duration_ms: Date.now() - startedAt, marker_line: null, detach: true, correlation_id: corrId, completion_signal: null, ...extraPayload } });
+        } catch (e) { log('detach watcher publish failed: ' + (e && e.message || e)); }
+        try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status: 'timeout' }); } catch (e) { /* non-fatal */ }
+        if (closeOnTimeout) {
+          try { await clawsRpc(sock, { cmd: 'close', id: termId, close_origin: 'timeout' }); } catch {}
+          try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status: 'closed' }); } catch {}
+        }
+        return;
+      }
+      const snap = await clawsRpc(sock, { cmd: 'readLog', id: termId, strip: true, limit: 64 * 1024 });
+      const text = snap.ok && typeof snap.bytes === 'string' ? snap.bytes : '';
+      try {
+        hbState.observe(text);
+        const hbNow = Date.now();
+        if (hbNow - hbLastPublishedAt >= 30000) {
+          const hbSnap = hbState.snapshot();
+          const elapsedSec = Math.floor(hbSnap.durationMs / 1000);
+          await _pconnEnsureRegistered(sock);
+          await _pconnWriteOrThrow({
+            cmd: 'publish', protocol: 'claws/2',
+            topic: `worker.${termId}.heartbeat`,
+            payload: {
+              kind: 'heartbeat',
+              summary: `still active · ${elapsedSec}s elapsed`,
+              current_action: hbSnap.state,
+              duration_ms: hbSnap.durationMs,
+              tokens_in: hbSnap.cumulative.tokens_in || undefined,
+              tokens_out: hbSnap.cumulative.tokens_out || undefined,
+              captured_at: new Date().toISOString(),
+              correlation_id: corrId,
+            },
+          });
+          hbLastPublishedAt = hbNow;
+        }
+        // HB-L5: progress event burst aggregation (5s window)
+        const l5Snap = hbState.snapshot();
+        const newTools = l5Snap.toolCount - lastPublishedToolCount;
+        if (newTools > 0) {
+          progressBurst.push({ kind: 'tools', count: newTools, ts: Date.now() });
+          if (progressBurstStart === 0) progressBurstStart = Date.now();
+          lastPublishedToolCount = l5Snap.toolCount;
+        }
+        if (progressBurst.length > 0 && (Date.now() - progressBurstStart) >= 5000) {
+          const burstTotal = progressBurst.reduce((a, e) => a + e.count, 0);
+          const burstElapsed = Math.round((Date.now() - progressBurstStart) / 1000);
+          try {
+            await _pconnEnsureRegistered(sock);
+            await _pconnWriteOrThrow({
+              cmd: 'publish', protocol: 'claws/2',
+              topic: `worker.${termId}.heartbeat`,
+              payload: {
+                kind: 'progress',
+                summary: `${burstTotal} tool call${burstTotal !== 1 ? 's' : ''} in last ${burstElapsed}s`,
+                current_action: l5Snap.state,
+                duration_ms: l5Snap.durationMs,
+                total_tool_calls: l5Snap.toolCount,
+                tokens_in: l5Snap.cumulative.tokens_in || undefined,
+                tokens_out: l5Snap.cumulative.tokens_out || undefined,
+                captured_at: new Date().toISOString(),
+                correlation_id: corrId,
+              },
+            });
+          } catch (e) { log('hb-l5 progress publish failed: ' + (e && e.message || e)); }
+          progressBurst = [];
+          progressBurstStart = 0;
+        }
+        // HB-L6: kind=approach (TodoWrite changes) — single-fire per distinct todoItems content
+        const l6Snap = hbState.snapshot();
+        const todoSig = l6Snap.todoItems ? JSON.stringify(l6Snap.todoItems) : '';
+        if (todoSig && todoSig !== lastTodoSig) {
+          lastTodoSig = todoSig;
+          try {
+            await _pconnEnsureRegistered(sock);
+            await _pconnWriteOrThrow({
+              cmd: 'publish', protocol: 'claws/2',
+              topic: `worker.${termId}.heartbeat`,
+              payload: {
+                kind: 'approach',
+                summary: `planning: ${l6Snap.todoItems.length} task${l6Snap.todoItems.length !== 1 ? 's' : ''}`,
+                approach_detail: l6Snap.todoItems,
+                current_action: l6Snap.state,
+                duration_ms: l6Snap.durationMs,
+                captured_at: new Date().toISOString(),
+                correlation_id: corrId,
+              },
+            });
+          } catch (e) { log('hb-l6 approach publish failed: ' + (e && e.message || e)); }
+        }
+        // HB-L6: kind=error (new error indicators) — single-fire per new batch
+        if (l6Snap.errorsCount > lastPublishedErrorsCount) {
+          const newErrors = hbState.lastErrors.slice(lastPublishedErrorsCount);
+          lastPublishedErrorsCount = l6Snap.errorsCount;
+          try {
+            await _pconnEnsureRegistered(sock);
+            await _pconnWriteOrThrow({
+              cmd: 'publish', protocol: 'claws/2',
+              topic: `worker.${termId}.heartbeat`,
+              payload: {
+                kind: 'error',
+                summary: `${newErrors.length} error${newErrors.length !== 1 ? 's' : ''} detected`,
+                error_detail: newErrors.map(e => e.detail || e.summary || String(e)).slice(0, 5).join('; '),
+                current_action: l6Snap.state,
+                duration_ms: l6Snap.durationMs,
+                captured_at: new Date().toISOString(),
+                correlation_id: corrId,
+              },
+            });
+          } catch (e) { log('hb-l6 error publish failed: ' + (e && e.message || e)); }
+        }
+      } catch (e) { log('hb backstop publish failed: ' + (e && e.message || e)); }
+      if (text.length > pubScanOffset) await _scanAndPublishCLAWSPUB(text.slice(pubScanOffset), sock);
+      pubScanOffset = text.length;
+      // AF-AC Phase 1: check process_exited event (highest priority — OS-authoritative signal).
+      if (_workerProcessExitedSet.has(String(termId))) {
+        const _pexEntry = _workerProcessExitedSet.get(String(termId));
+        clearInterval(intervalId);
+        _detachWatchers.delete(termId);
+        log(`AF-AC: detach watcher resolving via process_exited termId=${termId} exitCode=${_pexEntry && _pexEntry.exitCode}`);
+        try {
+          await _pconnEnsureRegistered(sock);
+          await _pconnWriteOrThrow({ cmd: 'publish', protocol: 'claws/2', topic: 'system.worker.completed',
+            payload: { terminal_id: termId, status: 'completed', duration_ms: Date.now() - startedAt, marker_line: null, detach: true, correlation_id: corrId, completion_signal: 'process_exited', completion_source: 'process_exited', ...extraPayload } });
+        } catch (e) { log('AF-AC detach watcher publish failed: ' + (e && e.message || e)); }
+        try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status: 'completed' }); } catch (_e) { /* non-fatal */ }
+        if (opt.close_on_complete !== false) {
+          try { await clawsRpc(sock, { cmd: 'close', id: termId, close_origin: 'process_exit' }); } catch {}
+          try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status: 'closed' }); } catch {}
+        }
+        return;
+      }
+      const scanText = text.length > markerScanFrom ? text.slice(markerScanFrom) : '';
+      const det = detectCompletion(scanText, opt, String(termId), _workerTerminatedSet, _workerCompletedViaBusSet);
+      const detStatus = det ? det.status : null;
+      const markerLine = det ? det.line : null;
+      const signal = det ? det.signal : null;
+      if (detStatus !== null) {
+        clearInterval(intervalId);
+        _detachWatchers.delete(termId);
+        try {
+          await _pconnEnsureRegistered(sock);
+          await _pconnWriteOrThrow({ cmd: 'publish', protocol: 'claws/2', topic: 'system.worker.completed',
+            payload: { terminal_id: termId, status: detStatus, duration_ms: Date.now() - startedAt, marker_line: markerLine, detach: true, correlation_id: corrId, completion_signal: signal, ...extraPayload } });
+        } catch (e) { log('detach watcher publish failed: ' + (e && e.message || e)); }
+        try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status: detStatus }); } catch (e) { /* non-fatal */ }
+        if (opt.close_on_complete !== false) {
+          const closeOrigin = detStatus === 'completed' ? 'marker' : detStatus === 'failed' ? 'error' : detStatus === 'timeout' ? 'timeout' : 'orchestrator';
+          try { await clawsRpc(sock, { cmd: 'close', id: termId, close_origin: closeOrigin }); } catch {}
+          try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status: 'closed' }); } catch {}
+        }
+      }
+    } catch (e) { log('detach watcher tick error: ' + (e && e.message || e)); }
+  };
+  const intervalId = setInterval(tick, opt.poll_interval_ms);
+  _detachWatchers.set(termId, { intervalId, opt, startedAt });
+  return intervalId;
+}
+
+// W8k-1: shared mission-delivery helper used by both runBlockingWorker (fleet path)
+// and the claws_worker fast path. Guarantees identical send timing on Mac pty and
+// Windows ConPTY. Proven sequence (line 1380):
+//   bracketed-paste (newline:false) → 300ms gap → explicit \r → SUBMITS ✓
+// Using newline:true (internal 30ms CR) fails on Windows ConPTY — mission sits
+// unsubmitted in the prompt buffer until the user manually presses Enter.
+// AE-7: escalating submit keystroke strategies — tried in order when the event-driven
+// submit confirmation doesn't arrive within RETRY_INTERVAL_MS. strat 0 ('\r') is sent
+// first and covers Mac + Windows nominal path. strats 1-4 handle edge cases (sticky
+// bracketed-paste mode, Ink readline alt-paths, ConPTY flush variants).
+// Zero platform branches — the same array is used on darwin/linux/win32.
+const SUBMIT_STRATEGIES = [
+  '\r',           // strat 0: baseline CR — correct universal submit key
+  '\r\n',         // strat 1: Windows CRLF variant
+  '\x1b[201~\r',  // strat 2: paste-end marker + CR (unstick stuck bracketed-paste mode)
+  '\n\r',         // strat 3: LF then CR (Ink readline alt-path)
+  '\x1b\r',       // strat 4: ESC + CR (force exit any input mode before submit)
+];
+const RETRY_INTERVAL_MS = 3000;  // wait this long for a bus event before escalating strategy
+const SUBMIT_CEILING_MS = 60000; // true-hang safety net — NOT a submit budget
+
+// AE-7: wait for bus evidence that the worker received and started processing the mission.
+// Returns { kind: 'submitted', signal } | { kind: 'lifecycle_ended' } | { kind: 'timeout' }.
+//
+// 'submitted' signals:
+//   - 'tool.invoked': a tool.+.invoked event from the worker's peer (strongest — mission executing)
+//   - 'vehicle.content': vehicle.<termId>.content fired AND pty log grew past sizeThreshold
+//
+// 'lifecycle_ended': terminal closed or worker terminated — no point retrying.
+// 'timeout': RETRY_INTERVAL_MS elapsed with no event — caller escalates to next strategy.
+async function _waitForSubmitEvent(sock, termId, corrId, sizeThreshold, timeoutMs) {
+  const contentKey      = `vehicle-content:${termId}`;
+  const pasteCompleteKey = `paste-complete:${termId}`;
+  const toolKey         = `tool-invoked:${corrId}`;
+  const termClosedKey   = `system.terminal.closed:${corrId}`;
+  const workerTermKey   = `system.worker.terminated:${corrId}`;
+
+  return new Promise((resolve) => {
+    let resolved = false;
+
+    const finish = (result) => {
+      if (resolved) return;
+      resolved = true;
+      cleanup();
+      resolve(result);
+    };
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      _submitWaiters.delete(contentKey);
+      _submitWaiters.delete(pasteCompleteKey);
+      _submitWaiters.delete(toolKey);
+      _submitWaiters.delete(termClosedKey);
+      _submitWaiters.delete(workerTermKey);
+    };
+
+    const timer = setTimeout(() => finish({ kind: 'timeout' }), timeoutMs);
+
+    // vehicle.content: async size check; re-register on miss so it's effectively multi-fire
+    // within the window. Only resolves "submitted" if pty log actually grew past threshold.
+    const handleContent = () => {
+      clawsRpc(sock, { cmd: 'readLog', id: termId, strip: true, limit: 1024 }).then(snap => {
+        if (resolved) return;
+        const size = (snap.ok && typeof snap.totalSize === 'number') ? snap.totalSize
+          : (snap.ok && typeof snap.bytes === 'string' ? snap.bytes.length : 0);
+        if (size > sizeThreshold) {
+          finish({ kind: 'submitted', signal: 'vehicle.content' });
+        } else {
+          if (!resolved) _submitWaiters.set(contentKey, handleContent);
+        }
+      }).catch(() => { if (!resolved) _submitWaiters.set(contentKey, handleContent); });
+    };
+    _submitWaiters.set(contentKey, handleContent);
+    // AF-3 Layer 2: paste_complete fires from extension when captureStore grows (Windows fix).
+    // AF-3 Layer 1: eager check — on Windows vehicle.content already fired before this listener
+    // was installed; run handleContent immediately so the size check resolves without waiting.
+    _submitWaiters.set(pasteCompleteKey, handleContent);
+    handleContent();
+
+    // tool.invoked: strongest confirmation — worker's inner claude is calling MCP tools
+    _submitWaiters.set(toolKey, () => finish({ kind: 'submitted', signal: 'tool.invoked' }));
+
+    // lifecycle ended — terminal died before submission confirmed; no point retrying
+    _submitWaiters.set(termClosedKey, () => finish({ kind: 'lifecycle_ended' }));
+    _submitWaiters.set(workerTermKey, () => finish({ kind: 'lifecycle_ended' }));
+  });
+}
+
+async function _sendAndSubmitMission(sock, termId, corrId, payload, launchClaude) {
+  let markerScanFrom = 0;
+  if (!payload) return markerScanFrom;
+
+  if (launchClaude) {
+    // BUG-C: record log offset BEFORE mission send so detectCompletion never
+    // false-positives on marker strings embedded in the mission body itself.
+    const _preSnap = await clawsRpc(sock, { cmd: 'readLog', id: termId, strip: true, limit: 32 * 1024 });
+    const _preLen = (_preSnap.ok && typeof _preSnap.totalSize === 'number') ? _preSnap.totalSize
+      : (_preSnap.ok && typeof _preSnap.bytes === 'string' ? _preSnap.bytes.length : 0);
+
+    await clawsRpc(sock, { cmd: 'send', id: termId, text: payload, newline: false, paste: true });
+    await sleep(300);
+    // AE-6 (reverts AE-4): '\r' is the correct universal submit key.
+    // AE-7: strat 0 of SUBMIT_STRATEGIES — subsequent strategies escalate on timeout.
+    await clawsRpc(sock, { cmd: 'send', id: termId, text: SUBMIT_STRATEGIES[0], newline: false });
+
+    // AE-7: event-driven submit confirmation with escalating retry.
+    // Waits up to RETRY_INTERVAL_MS for a bus event proving Claude received the mission.
+    // On timeout, escalates to the next strategy. Safety ceiling prevents true-hang.
+    // No fixed-cadence polling, no pty-content regex — bus events only.
+    const _submitDeadline = Date.now() + SUBMIT_CEILING_MS;
+    let _stratIdx = 0;
+    let _submitVerified = false;
+
+    while (Date.now() < _submitDeadline && !_submitVerified) {
+      const evt = await _waitForSubmitEvent(
+        sock, termId, corrId,
+        _preLen + payload.length + 200,
+        RETRY_INTERVAL_MS,
+      );
+      if (evt.kind === 'submitted') { _submitVerified = true; break; }
+      if (evt.kind === 'lifecycle_ended') { break; }
+      // timeout — escalate to next strategy (cycle through if exhausted)
+      _stratIdx = (_stratIdx + 1) % SUBMIT_STRATEGIES.length;
+      await clawsRpc(sock, { cmd: 'send', id: termId, text: SUBMIT_STRATEGIES[_stratIdx], newline: false });
+    }
+
+    if (!_submitVerified) {
+      log(`_sendAndSubmitMission: submit ceiling hit (${SUBMIT_CEILING_MS}ms) — true hang or all strategies exhausted`);
+    }
+    // Snapshot post-mission log size for markerScanFrom.
+    try {
+      const _postSnap = await clawsRpc(sock, { cmd: 'readLog', id: termId, strip: true, limit: 1024 });
+      markerScanFrom = (_postSnap.ok && typeof _postSnap.totalSize === 'number')
+        ? _postSnap.totalSize
+        : (_postSnap.ok && typeof _postSnap.bytes === 'string' ? _postSnap.bytes.length : 0);
+    } catch (e) { /* non-fatal — defaults to 0, degraded but safe */ }
+  } else {
+    // Bare shell command: no paste needed; trailing \n submits via the prompt.
+    // BUG-26 analog: markerScanFrom stays 0 so the watcher scans the full log —
+    // the marker fires synchronously after the command exits.
+    await clawsRpc(sock, { cmd: 'send', id: termId, text: payload, newline: true });
+  }
+
+  return markerScanFrom;
+}
+
+// W8ac-2 + AE-6.b: event-driven boot signal. Resolves when the matching bus event fires
+// for corrId. Uses _workerReadyWaiters populated by _pconnHandleData as the one-shot listener store.
+// AE-6.b: ceilingMs is a SAFETY CEILING for true hangs, NOT a boot budget. Default 120s —
+// generous enough that no real device (slow VMs, ARM laptops, first-boot cold caches) races
+// against it. We abort early if the worker's lifecycle ends (terminated/closed) before the
+// ready event arrives.
+async function _waitForWorkerReady(sock, corrId, opts) {
+  const topic = opts.type === 'claude' ? 'system.peer.connected' : 'system.terminal.ready';
+  const ceilingMs = opts.timeoutMs || 120000;
+  return new Promise((resolve, reject) => {
+    const waiterKey = `${topic}:${corrId}`;
+    const cancelKeys = [
+      `system.terminal.closed:${corrId}`,
+      `system.worker.terminated:${corrId}`,
+    ];
+    const cleanup = () => {
+      clearTimeout(timer);
+      _workerReadyWaiters.delete(waiterKey);
+      for (const k of cancelKeys) _workerReadyWaiters.delete(k);
+    };
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error(`worker ready ceiling hit (${opts.type}, ${ceilingMs}ms) — likely worker hung pre-boot`));
+    }, ceilingMs);
+    _workerReadyWaiters.set(waiterKey, (event) => { cleanup(); resolve(event); });
+    for (const k of cancelKeys) {
+      _workerReadyWaiters.set(k, () => {
+        cleanup();
+        reject(new Error(`worker lifecycle ended before ready signal (${k})`));
+      });
+    }
+  });
+}
+
+// AD-1 + AE-1: gate mission paste on event-driven pty-claim signal.
+// The signal is system.peer.connected{correlation_id} — published by the
+// extension when the worker's child mcp_server.js hellos (now eagerly at
+// startup; see AE-1 block in main()). On timeout, we abort cleanly and
+// publish system.worker.boot_failed. NO regex / pty-log fallback (rejected
+// by user 2026-05-16 as fragile across platforms — see audit
+// .local/audits/peer-connected-blackout-root-cause.md).
+async function _gatePasteOnClaudeClaim(sock, termId, corrId, opts) {
+  const ceilingMs = (opts && opts.timeoutMs) || 120000;
+  try {
+    await _waitForWorkerReady(sock, corrId, { type: 'claude', timeoutMs: opts && opts.timeoutMs });
+    await sleep(200); // event fires before paste pipeline is fully open
+    return { booted: true, source: 'event' };
+  } catch (e) {
+    log(`paste-gate term=${termId} corr=${corrId}: BOOT FAILED — ${(e && e.message) || ('no event in ' + ceilingMs + 'ms')}`);
+    try {
+      await _pconnEnsureRegistered(sock);
+      await _pconnWriteOrThrow({
+        cmd: 'publish', protocol: 'claws/2',
+        topic: 'system.worker.boot_failed',
+        payload: {
+          terminal_id: String(termId),
+          correlation_id: corrId,
+          cause: 'event_driven_boot_timeout',
+          timeout_ms: ceilingMs,
+          ts: new Date().toISOString(),
+        },
+      });
+    } catch (_pe) { /* best-effort */ }
+    return { booted: false, source: 'aborted', cause: 'event_driven_boot_timeout' };
+  }
+}
+
+async function runBlockingWorker(sock, args) {
+  const DEFAULTS = {
+    timeout_ms: 5 * 60 * 1000,
+    // AE-6.b: boot_wait_ms intentionally absent from DEFAULTS. _waitForWorkerReady uses a
+    // 120s safety ceiling — not a boot budget. Callers may pass explicit boot_wait_ms to override.
+    // v0.7.9: was 'Claude Code' (with a space) — never matched the ANSI-stripped
+    // Claude Code v2.x banner ("ClaudeCodev2.1.123" — no space). Worker burned the
+    // full boot_wait_ms on every spawn before falling through. 'bypass permissions'
+    // is in the bypass-mode footer/banner and matches reliably.
+    boot_marker: 'bypass permissions',
+    complete_marker: '__CLAWS_DONE__',
+    error_markers: ['MISSION_FAILED'],
+    poll_interval_ms: 1500,
+    harvest_lines: 200,
+    close_on_complete: true,
+    model: 'claude-sonnet-4-6',
+  };
+  const opt = { ...DEFAULTS, ...args };
+  if (!/^[a-zA-Z0-9._-]+$/.test(opt.model)) {
+    return { status: 'error', error: `invalid model name '${opt.model}' — must match /^[a-zA-Z0-9._-]+$/` };
+  }
+  const hasMission = typeof args.mission === 'string' && args.mission.length > 0;
+  const hasCommand = typeof args.command === 'string' && args.command.length > 0;
+  const launchClaude = args.launch_claude !== undefined
+    ? !!args.launch_claude
+    : hasMission;
+  // Default cwd to the MCP server's working directory (project root) so workers
+  // never land in $HOME — which would trigger the trust dialog and break the
+  // project MCP socket walk-up. Caller may override.
+  const workerCwd = typeof args.cwd === 'string' && args.cwd.length > 0
+    ? args.cwd
+    : process.cwd();
+
+  // 1. Create wrapped terminal
+  const _bCorrId = randomUUID();
+  const cr = await clawsRpc(sock, {
+    cmd: 'create', name: args.name || 'claws-worker', wrapped: true, show: true,
+    cwd: workerCwd, env: { CLAWS_WORKER: '1' }, correlation_id: _bCorrId,
+  });
+  if (!cr.ok) return { status: 'error', error: `create failed: ${_lifecycleErrMsg(cr.error)}` };
+  const termId = cr.id;
+  _clearStaleCompletionSignals(termId);
+  const startedAt = Date.now();
+
+  // Publish system.worker.spawned — best-effort, never aborts on failure.
+  log(`runBlockingWorker: publishing system.worker.spawned for terminal ${termId}`);
+  try {
+    await _pconnEnsureRegistered(sock);
+    await _pconnWriteOrThrow({
+      cmd: 'publish', protocol: 'claws/2',
+      topic: 'system.worker.spawned',
+      payload: { terminal_id: termId, name: args.name || 'claws-worker', wrapped: true, started_at: new Date(startedAt).toISOString(), correlation_id: _bCorrId },
+    });
+    log(`runBlockingWorker: system.worker.spawned published ok for terminal ${termId}`);
+  } catch (e) { log('runBlockingWorker: system.worker.spawned publish FAILED: ' + (e && e.message || e)); }
+
+  // D+F: register spawn + monitor atomically before proceeding. Best-effort (lifecycle may not be in active mission).
+  try { await clawsRpc(sock, { cmd: 'lifecycle.register-spawn', terminalId: String(termId), correlationId: _bCorrId, name: args.name || 'claws-worker' }); } catch (e) { /* non-fatal */ }
+  const _bMonitorCmd = `Monitor(command="node ${STREAM_EVENTS_JS_FOR_CMD} --wait ${_bCorrId} --keep-alive-on ${termId}", description="claws monitor | term=${termId} | corr=${_bCorrId.slice(0,8)} | sess=${new Date().toISOString().slice(0,13)}", timeout_ms=3600000, persistent=false)`;
+  try { await clawsRpc(sock, { cmd: 'lifecycle.register-monitor', terminalId: String(termId), correlationId: _bCorrId, command: _bMonitorCmd }); } catch (e) { /* non-fatal */ }
+  try { await clawsRpc(sock, { cmd: 'monitors.register-intent', correlation_id: _bCorrId }); } catch (_e) { /* non-fatal */ }
+  // T4: monitor-arm grace warning — 5s after spawn, warn if no monitor registered in lifecycle.
+  const _bMonitorGraceMs = 5000;
+  const _bTermIdStr = String(termId);
+  setTimeout(async () => {
+    try {
+      const snap = await clawsRpc(sock, { cmd: 'lifecycle.snapshot' });
+      if (snap.ok && snap.state) {
+        const hasMonitor = (snap.state.monitors || []).some(m => m.terminal_id === _bTermIdStr);
+        if (!hasMonitor) {
+          log(`T4-warn: runBlockingWorker term=${_bTermIdStr} corr=${_bCorrId} — no monitor registered within ${_bMonitorGraceMs}ms grace. Orchestrator may be flying blind. Use monitor_arm_command from spawn response.`);
+        }
+      }
+    } catch (_e) { /* non-fatal */ }
+  }, _bMonitorGraceMs);
+  // Layer 2 (Bug-6 / Bug-13): 30s first check — true orphan vs arm-in-flight (two-stage state machine).
+  setTimeout(async () => {
+    const _l2f = (m) => { log(m); _logL2File(sock, m); };
+    _l2f(`L2-DEBUG: callback-entered | site=runBlockingWorker | corrId=${_bCorrId} | termId=${_bTermIdStr}`);
+    try {
+      const armResp = await clawsRpc(sock, { cmd: 'monitors.is-corr-armed', correlation_id: _bCorrId });
+      _l2f(`L2-DEBUG: rpc-result | site=runBlockingWorker | ok=${armResp.ok} | armed=${armResp.armed} | claimed=${armResp.claimed} | pending=${armResp.pending} | peerId=${armResp.peerId}`);
+      if (!armResp.ok) return;  // RPC error, can't decide
+      if (armResp.claimed) {
+        _l2f(`L2-DEBUG: skip-publish | site=runBlockingWorker | reason=claimed | corrId=${_bCorrId}`);
+        return;
+      }
+      if (!armResp.pending) {
+        // True orphan — neither intent nor execution registered.
+        log(`L2-warn: runBlockingWorker term=${_bTermIdStr} corr=${_bCorrId} — no intent or execution at 30s. True orphan.`);
+        _l2f(`L2-DEBUG: about-to-publish | site=runBlockingWorker | corrId=${_bCorrId} | reason=no-intent`);
+        try {
+          await _pconnEnsureRegistered(sock);
+          _l2f(`L2-DEBUG: pconn-registered | site=runBlockingWorker`);
+          await _pconnWriteOrThrow({
+            cmd: 'publish', protocol: 'claws/2',
+            topic: 'system.monitor.unarmed',
+            payload: { terminal_id: _bTermIdStr, correlation_id: _bCorrId, layer: 2,
+              detected_at: new Date().toISOString(), grace_ms: 30000, reason: 'no-intent' },
+          });
+          _l2f(`L2-DEBUG: publish-succeeded | site=runBlockingWorker | corrId=${_bCorrId}`);
+        } catch (_pe) {
+          _l2f(`L2-DEBUG: publish-failed | site=runBlockingWorker | err=${_pe && _pe.message || _pe}`);
+        }
+        return;
+      }
+      // pending=true, claimed=false — arm in flight. Re-check at +60s.
+      _l2f(`L2-DEBUG: arm-in-flight | site=runBlockingWorker | corrId=${_bCorrId} | scheduling-recheck-60s`);
+      setTimeout(async () => {
+        _l2f(`L2-DEBUG: recheck-entered | site=runBlockingWorker | corrId=${_bCorrId} | termId=${_bTermIdStr}`);
+        try {
+          const r2 = await clawsRpc(sock, { cmd: 'monitors.is-corr-armed', correlation_id: _bCorrId });
+          _l2f(`L2-DEBUG: recheck-rpc-result | site=runBlockingWorker | ok=${r2.ok} | armed=${r2.armed} | claimed=${r2.claimed} | pending=${r2.pending} | peerId=${r2.peerId}`);
+          if (!r2.ok || r2.claimed) {
+            _l2f(`L2-DEBUG: recheck-skip | site=runBlockingWorker | reason=${!r2.ok ? 'rpc-error' : 'claimed'}`);
+            return;
+          }
+          const reason = r2.pending ? 'pending-timeout' : 'pending-vacated';
+          log(`L2-warn: runBlockingWorker term=${_bTermIdStr} corr=${_bCorrId} — ${reason} at 90s. Publishing unarmed.`);
+          _l2f(`L2-DEBUG: about-to-publish | site=runBlockingWorker | corrId=${_bCorrId} | reason=${reason}`);
+          try {
+            await _pconnEnsureRegistered(sock);
+            _l2f(`L2-DEBUG: pconn-registered | site=runBlockingWorker`);
+            await _pconnWriteOrThrow({
+              cmd: 'publish', protocol: 'claws/2',
+              topic: 'system.monitor.unarmed',
+              payload: { terminal_id: _bTermIdStr, correlation_id: _bCorrId, layer: 2,
+                detected_at: new Date().toISOString(), grace_ms: 90000, reason },
+            });
+            _l2f(`L2-DEBUG: publish-succeeded | site=runBlockingWorker | corrId=${_bCorrId}`);
+          } catch (_pe) {
+            _l2f(`L2-DEBUG: publish-failed | site=runBlockingWorker | err=${_pe && _pe.message || _pe}`);
+          }
+        } catch (_e) { _l2f(`L2-DEBUG: recheck-error | site=runBlockingWorker | err=${_e && _e.message || _e}`); }
+      }, 60000);
+    } catch (_e) { _l2f(`L2-DEBUG: outer-error | site=runBlockingWorker | err=${_e && _e.message || _e}`); }
+  }, 30000);
+
+  // 2. Give shell a moment to emit prompt
+  await sleep(400);
+
+  // 3. Optional claude boot + detection — single attempt, event-driven.
+  // Sends the launch command ONCE, waits for system.peer.connected event keyed
+  // by _bCorrId. AE-6.b: 120s safety ceiling, early-abort on terminal.closed/terminated.
+  let booted = !launchClaude;
+  if (launchClaude) {
+    await clawsRpc(sock, {
+      cmd: 'send', id: termId,
+      text: `${getClaudeBin(args && args.cwd)} --dangerously-skip-permissions --model ${opt.model}`, newline: true,
+    });
+    // AD-1 + AE-1: gate mission paste on confirmed event-driven pty-claim.
+    const _gate = await _gatePasteOnClaudeClaim(sock, termId, _bCorrId, { timeoutMs: opt.boot_wait_ms });
+    if (!_gate.booted) {
+      if (opt.close_on_complete) { try { await clawsRpc(sock, { cmd: 'close', id: termId }); } catch {} }
+      return { status: 'error', error: `boot failed: ${_gate.cause}`, terminal_id: termId, correlation_id: _bCorrId };
+    }
+    booted = true;
+    // BUG-07: secondary MCP auth check — bypass banner can appear before /mcp auth resolves.
+    if (booted) {
+      const _authSnap = await clawsRpc(sock, { cmd: 'readLog', id: termId, strip: true, limit: 32 * 1024 });
+      if (_authSnap.ok && typeof _authSnap.bytes === 'string' &&
+          (_authSnap.bytes.includes('MCP server need') || _authSnap.bytes.includes(' /mcp'))) {
+        if (opt.close_on_complete) try { await clawsRpc(sock, { cmd: 'close', id: termId }); } catch {}
+        return { status: 'error', error: `boot_marker seen but MCP auth banner active on terminal ${termId} — prompt is blocked. Spawn with minimal MCP config or pre-auth.` };
+      }
+    }
+  }
+
+  // 4. Send the mission AS A USER PROMPT — direct, the way it works in v0.7.4.
+  // ──────────────────────────────────────────────────────────────────────────
+  // No file abstractions. The user's mission text becomes Claude Code's input
+  // exactly as if a human typed it, because that's what users expect.
+  //
+  // DO NOT add a file-referrer pattern here. If a future contributor is tempted
+  // to write the mission to /tmp and send a "Read <file>..." referrer to dodge
+  // some pty quirk, the answer is NO. The mission is a user prompt. Period.
+  // Strip bracketed-paste escape sequences so a crafted mission cannot break out of paste mode.
+  // Phase 4a: one-line completion hint — claws_done() handles the rest.
+  const _phase4Header = hasMission ? `When you're finished, call \`claws_done()\`. That's it.\n\n---\n` : '';
+  const safeMission = hasMission
+    ? (_phase4Header + args.mission).replace(/\x1b\[200~/g, '').replace(/\x1b\[201~/g, '')
+    : args.mission;
+  // ROOT CAUSE FIX (2026-05-02): mission augmentation with CLAWS_PUB preamble was
+  // breaking Claude TUI multi-line submission. Preamble added ~5 extra lines +
+  // special chars (single quotes around topics), pushing total text past Claude's
+  // paste-collapse threshold. Multi-line input rendered expanded; single \r
+  // treated as newline-within-input, never submitted.
+  // Verified: identical mission via claws_send (no augmentation) submits ✓.
+  // Send mission DIRECTLY, no preamble.
+  const payload = hasMission ? safeMission
+                : hasCommand ? wrapShellCommand(args.command, termId)
+                : '';
+
+  // W8k-1: delegate to shared helper — same proven sequence as claws_worker fast path.
+  // newline:false + 300ms + explicit \r submits reliably on Mac pty and Windows ConPTY;
+  // the old newline:true (internal 30ms CR) left fleet missions unsubmitted on ConPTY.
+  const markerScanFrom = await _sendAndSubmitMission(sock, termId, _bCorrId, payload, launchClaude);
+
+  // 5. Detach shortcut — register background watcher that runs the SAME poll
+  // body as the blocking path so [CLAWS_PUB] scanner, system.worker.completed
+  // publish, and auto-close all keep working in detach mode. Server-side only,
+  // never holds the MCP socket.
+  if (args.detach === true) {
+    let pubScanOffset = markerScanFrom;
+    let status = 'timeout';
+    let markerLine = null;
+    let completionSignal = null;
+    const _msState = { firstActivityAt: null, lastLen: 0, lastGrowthAt: Date.now(), startedAt };
+    const timeoutDeadline = startedAt + opt.timeout_ms;
+    const tick = async () => {
+      try {
+        if (Date.now() > timeoutDeadline) {
+          clearInterval(intervalId);
+          _detachWatchers.delete(termId);
+          try {
+            await _pconnEnsureRegistered(sock);
+            await _pconnWriteOrThrow({
+              cmd: 'publish', protocol: 'claws/2',
+              topic: 'system.worker.completed',
+              payload: { terminal_id: termId, status, duration_ms: Date.now() - startedAt, marker_line: markerLine, booted, detach: true, correlation_id: _bCorrId, completion_signal: completionSignal },
+            });
+          } catch (e) { log('detach watcher publish failed: ' + (e && e.message || e)); }
+          try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status: 'timeout' }); } catch (e) { /* non-fatal */ }
+          return;
+        }
+        const snap = await clawsRpc(sock, { cmd: 'readLog', id: termId, strip: true, limit: 64 * 1024 });
+        const text = snap.ok && typeof snap.bytes === 'string' ? snap.bytes : '';
+        const scanText = text.length > markerScanFrom ? text.slice(markerScanFrom) : '';
+        const scanStart = Math.min(pubScanOffset, text.length);
+        if (text.length > scanStart) await _scanAndPublishCLAWSPUB(text.slice(scanStart), sock);
+        pubScanOffset = text.length;
+        const _now = Date.now();
+        if (text.length > _msState.lastLen) {
+          if (_msState.firstActivityAt === null) _msState.firstActivityAt = _now;
+          _msState.lastGrowthAt = _now;
+          _msState.lastLen = text.length;
+        }
+        const _det = detectCompletion(scanText, opt, String(termId), _workerTerminatedSet, _workerCompletedViaBusSet);
+        if (_det !== null) {
+          status = _det.status;
+          markerLine = _det.line;
+          completionSignal = _det.signal;
+        }
+        if (status !== 'timeout') {
+          clearInterval(intervalId);
+          _detachWatchers.delete(termId);
+          try {
+            await _pconnEnsureRegistered(sock);
+            await _pconnWriteOrThrow({
+              cmd: 'publish', protocol: 'claws/2',
+              topic: 'system.worker.completed',
+              payload: { terminal_id: termId, status, duration_ms: Date.now() - startedAt, marker_line: markerLine, booted, detach: true, correlation_id: _bCorrId, completion_signal: completionSignal },
+            });
+          } catch (e) { log('detach watcher publish failed: ' + (e && e.message || e)); }
+          try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status }); } catch (e) { /* non-fatal */ }
+          if (opt.close_on_complete !== false) {
+            const _bCloseOrigin = status === 'completed' ? 'marker' : status === 'failed' ? 'error' : status === 'timeout' ? 'timeout' : 'orchestrator';
+            try { await clawsRpc(sock, { cmd: 'close', id: termId, close_origin: _bCloseOrigin }); } catch {}
+            // BUG-B fix: notify lifecycle store so workers[].closed flips to true.
+            try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status: 'closed' }); } catch {}
+          }
+        }
+      } catch (e) { log('detach watcher tick error: ' + (e && e.message || e)); }
+    };
+    const intervalId = setInterval(tick, opt.poll_interval_ms);
+    _detachWatchers.set(termId, { intervalId, opt, startedAt });
+    return { status: 'spawned', terminal_id: termId, booted, duration_ms: Date.now() - startedAt, correlation_id: _bCorrId };
+  }
+
+  // 6. Poll for completion / errors / timeout
+  const timeoutDeadline = startedAt + opt.timeout_ms;
+  let status = 'timeout';
+  let markerLine = null;
+  let completionSignal = null;
+  let pubScanOffset = markerScanFrom; // start CLAWS_PUB scan from the same offset
+
+  while (Date.now() < timeoutDeadline) {
+    const snap = await clawsRpc(sock, {
+      cmd: 'readLog', id: termId, strip: true, limit: 64 * 1024,
+    });
+    const text = snap.ok && typeof snap.bytes === 'string' ? snap.bytes : '';
+
+    // Only scan bytes produced AFTER the payload was sent + echoed. This
+    // prevents the marker substring from false-matching on the input echo
+    // of the user's mission text.
+    const scanText = text.length > markerScanFrom ? text.slice(markerScanFrom) : '';
+
+    // Scan lines added since the last poll tick for [CLAWS_PUB] publish markers.
+    const scanStart = Math.min(pubScanOffset, text.length);
+    if (text.length > scanStart) {
+      await _scanAndPublishCLAWSPUB(text.slice(scanStart), sock);
+    }
+    pubScanOffset = text.length;
+
+    const _bNow = Date.now();
+    const _bDet = detectCompletion(scanText, opt, String(termId), _workerTerminatedSet, _workerCompletedViaBusSet);
+    if (_bDet !== null) {
+      status = _bDet.status;
+      markerLine = _bDet.line;
+      completionSignal = _bDet.signal;
+      break;
+    }
+
+    await sleep(opt.poll_interval_ms);
+  }
+
+  // Publish system.worker.completed — best-effort, never aborts on failure.
+  try {
+    await _pconnEnsureRegistered(sock);
+    await _pconnWriteOrThrow({
+      cmd: 'publish', protocol: 'claws/2',
+      topic: 'system.worker.completed',
+      payload: { terminal_id: termId, status, duration_ms: Date.now() - startedAt, marker_line: markerLine, booted, correlation_id: _bCorrId, completion_signal: completionSignal },
+    });
+  } catch (e) { log('system.worker.completed publish failed: ' + (e && e.message || e)); }
+  try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status }); } catch (e) { /* non-fatal */ }
+
+  // 7. Harvest final output
+  const final = await clawsRpc(sock, {
+    cmd: 'readLog', id: termId, strip: true, limit: 256 * 1024,
+  });
+  const allLines = (final.ok && typeof final.bytes === 'string' ? final.bytes : '').split('\n');
+  const harvest = allLines.slice(-opt.harvest_lines).join('\n');
+
+  // 8. Auto-close
+  let cleanedUp = false;
+  if (opt.close_on_complete) {
+    const _rbCloseOrigin = status === 'completed' ? 'marker' : status === 'failed' ? 'error' : status === 'timeout' ? 'timeout' : 'orchestrator';
+    const cl = await clawsRpc(sock, { cmd: 'close', id: termId, close_origin: _rbCloseOrigin });
+    cleanedUp = !!cl.ok;
+    // BUG-B fix: notify lifecycle store so workers[].closed flips to true.
+    try { await clawsRpc(sock, { cmd: 'lifecycle.mark-worker-status', terminalId: String(termId), status: 'closed' }); } catch {}
+  }
+
+  return {
+    status,
+    terminal_id: termId,
+    booted,
+    duration_ms: Date.now() - startedAt,
+    marker_line: markerLine,
+    cleaned_up: cleanedUp,
+    harvest,
+    correlation_id: _bCorrId,
+    completion_signal: completionSignal,
+  };
+}
+
+// ─── Sidecar auto-spawn ───────────────────────────────────────────────────────
+let _sidecarPid        = null;
+let _sidecarSubscribed = false; // true only after sidecar.subscribed JSON confirmed
+let _sidecarStdout     = null;  // kept open to prevent SIGPIPE
+let _sidecarEnsureInFlight = null; // singleton in-flight Promise dedup
+
+function _isSidecarAlive() {
+  if (!_sidecarPid || !_sidecarSubscribed) return false;
+  try { process.kill(_sidecarPid, 0); return true; } catch { return false; }
+}
+
+async function _spawnAndVerifySidecar(maxWaitMs = 3000) {
+  const { spawn, spawnSync } = require('child_process');
+  // BUG-19 fix: __dirname resolves to repo root when .claws-bin/mcp_server.js is symlinked
+  // back to ../mcp_server.js (Wave A's dedup). Try multiple candidate locations.
+  const sidecarCandidates = [
+    path.join(__dirname, 'stream-events.js'),                  // .claws-bin layout (non-symlinked install)
+    path.join(__dirname, '.claws-bin', 'stream-events.js'),    // repo root + .claws-bin
+    path.join(__dirname, 'scripts', 'stream-events.js'),       // repo root + scripts (dev source)
+  ];
+  const sidecarPath = sidecarCandidates.find(p => fs.existsSync(p));
+  if (!sidecarPath) throw new Error('stream-events.js not found in any candidate: ' + sidecarCandidates.join(', '));
+
+  // GAP-A1: detect existing auto-sidecar (spawned by session-start hook) to avoid
+  // two concurrent sidecars both writing to events.log, causing 4x event duplication.
+  const socketPath = getSocket();
+
+  // W8Q3-3: on win32 pgrep is unavailable (ENOENT); use a pid-file instead.
+  const pidFile = process.platform === 'win32'
+    ? path.join(
+        process.env.CLAWS_WORKSPACE_ROOT
+          || _findWorkspaceRoot(process.cwd())
+          || _findWorkspaceRoot(__dirname)
+          || os.tmpdir(),
+        '.claws', 'sidecar.pid')
+    : null;
+  if (process.platform === 'win32' && pidFile && fs.existsSync(pidFile)) {
+    try {
+      const existingPid = parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
+      process.kill(existingPid, 0); // signal 0: liveness probe — throws if dead
+      log('[sidecar] adopting via pid-file pid=' + existingPid + ' (W8Q3-3 dedup)');
+      _sidecarPid        = existingPid;
+      _sidecarSubscribed = true;
+      return;
+    } catch {
+      // stale pidfile — remove and fall through to spawn
+      try { fs.unlinkSync(pidFile); } catch {}
+    }
+  }
+
+  const escapedSocket = socketPath.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  const pgResult = spawnSync('pgrep', ['-f', `stream-events\\.js.*--auto-sidecar.*${escapedSocket}`], { encoding: 'utf8' });
+  if (pgResult.status === 0) {
+    const existingPid = parseInt((pgResult.stdout || '').trim().split('\n')[0], 10);
+    if (!isNaN(existingPid)) {
+      log(`[sidecar] adopting existing auto-sidecar pid=${existingPid} (GAP-A1 dedup)`);
+      _sidecarPid        = existingPid;
+      _sidecarSubscribed = true;
+      return;
+    }
+  }
+
+  // Open events.log for appending — after verification confirmed, stdout is
+  // piped here so every sidecar push frame is persisted for tail-F monitoring.
+  const eventsLogFilePath = _eventsLogPath(socketPath);
+  const eventsLogStream = fs.createWriteStream(eventsLogFilePath, { flags: 'a' });
+
+  // GAP-A1: pass --auto-sidecar + socketPath as args so session-start pgrep can detect us.
+  const child = spawn(process.execPath, [sidecarPath, '--auto-sidecar', socketPath], {
+    detached: true,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    env: { ...process.env, CLAWS_TOPIC: '**', CLAWS_PEER_NAME: 'auto-sidecar', CLAWS_ROLE: 'observer' },
+  });
+
+  if (!child.pid) throw new Error('sidecar spawn returned no pid (ENOENT or permission denied)');
+  _sidecarPid    = child.pid;
+  _sidecarStdout = child.stdout;
+  if (process.platform === 'win32' && pidFile) {
+    try { fs.mkdirSync(path.dirname(pidFile), { recursive: true }); } catch {}
+    fs.writeFileSync(pidFile, String(child.pid));
+  }
+
+  // Named drain — removed after verification so stdout can be piped to events.log.
+  function drainHandler() {}
+  child.stdout.on('data', drainHandler);
+  child.on('exit', (code) => {
+    log(`[sidecar] exited code=${code}`);
+    eventsLogStream.end();
+    if (process.platform === 'win32' && pidFile) { try { fs.unlinkSync(pidFile); } catch {} }
+    _sidecarPid        = null;
+    _sidecarSubscribed = false;
+    _sidecarStdout     = null;
+  });
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      child.stdout.removeListener('data', verifyHandler);
+      reject(new Error(`sidecar did not reach SUBSCRIBED within ${maxWaitMs}ms`));
+    }, maxWaitMs);
+
+    let buf = '';
+    function verifyHandler(chunk) {
+      buf += chunk.toString('utf8');
+      let nl;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl); buf = buf.slice(nl + 1);
+        try {
+          const obj = JSON.parse(line);
+          if (obj.type === 'sidecar.subscribed' && obj.ok !== false) {
+            clearTimeout(timer);
+            child.stdout.removeListener('data', verifyHandler);
+            child.stdout.removeListener('data', drainHandler);
+            child.stdout.pipe(eventsLogStream);
+            child.unref();
+            _sidecarSubscribed = true;
+            log(`[sidecar] SUBSCRIBED confirmed — piping stdout to ${eventsLogFilePath}`);
+            resolve();
+            return;
+          }
+          if (obj.type === 'sidecar.error') {
+            clearTimeout(timer);
+            child.stdout.removeListener('data', verifyHandler);
+            reject(new Error('sidecar error: ' + obj.error));
+            return;
+          }
+        } catch { /* incomplete JSON line, skip */ }
+      }
+    }
+    child.stdout.on('data', verifyHandler);
+
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      child.stdout.removeListener('data', verifyHandler);
+      if (code !== 0) reject(new Error(`sidecar crashed (exit ${code}) before reaching SUBSCRIBED`));
+    });
+  });
+}
+
+async function _ensureSidecarOrThrow(maxWaitMs = 3000) {
+  if (_isSidecarAlive()) return;
+  if (!_sidecarEnsureInFlight) {
+    _sidecarEnsureInFlight = _spawnAndVerifySidecar(maxWaitMs)
+      .finally(() => { _sidecarEnsureInFlight = null; });
+  }
+  await _sidecarEnsureInFlight;
+}
+
+// ─── Persistent-socket identity helper ────────────────────────────────────────
+// Ensures the persistent socket is connected AND this process has a peerId.
+// If not yet registered, sends hello with role=orchestrator, peerName=mcp-orchestrator.
+// Called once per process lifetime in practice (peerId cached on _pconn).
+async function _pconnEnsureRegistered(sockPath) {
+  // 30s failure cache: skip reconnect attempt entirely if we failed recently.
+  if (!_pconn.connected && _circuitBreaker.lastFailureTs > 0) {
+    if (Date.now() - _circuitBreaker.lastFailureTs < 30_000) {
+      throw new Error('circuit-breaker: last connect failed < 30s ago, skipping');
+    }
+  }
+  try {
+    await _pconnEnsure(sockPath);
+  } catch (err) {
+    _circuitBreaker.lastFailureTs = Date.now();
+    throw err;
+  }
+  // Reset failure timestamp on successful connect.
+  _circuitBreaker.lastFailureTs = 0;
+  // Socket identity guard: skip hello ONLY if peerId is set AND it was negotiated on
+  // the current socket. If the socket disconnected and reconnected, socketId changes
+  // but helloSocketId does not — the mismatch forces a re-hello on the new socket.
+  if (_pconn.peerId && _pconn.helloSocketId === _pconn.socketId) {
+    // valid registration on the current socket — skip hello
+  } else {
+    // Either no peerId, or hello was on a previous (now-closed) socket — re-hello required.
+    _pconn.peerId = null;
+    _pconn.helloSocketId = null;
+    log(`PCONN-DEBUG: about-to-hello | socketId=${_pconn.socketId} | helloSocketId=${_pconn.helloSocketId}`);
+    if (!_helloInFlight) {
+      _helloInFlight = _pconnWrite({
+        cmd: 'hello', protocol: 'claws/2',
+        role: 'orchestrator', peerName: 'mcp-orchestrator',
+        ...(process.env.CLAWS_TERMINAL_CORR_ID ? { correlation_id: process.env.CLAWS_TERMINAL_CORR_ID } : {}),
+      }, 5000).finally(() => { _helloInFlight = null; });
+    }
+    let hr = await _helloInFlight;
+    log(`PCONN-DEBUG: hello-ack | ok=${hr && hr.ok} | peerId=${hr && hr.peerId} | error=${hr && hr.error}`);
+    // Retry-on-already-registered: extension may still have the old peer in its Map
+    // if the closed socket's FIN hasn't been processed by its event loop yet.
+    // Exponential backoff gives the extension time to delete the stale peer before each retry.
+    let _helloRetries = 0;
+    while (hr && hr.ok === false && /already registered/i.test(hr.error || '') && _helloRetries < 3) {
+      _helloRetries++;
+      const _retryDelay = 100 * Math.pow(2, _helloRetries - 1); // 100, 200, 400 ms
+      log(`PCONN-DEBUG: hello-retry | attempt=${_helloRetries} | delay=${_retryDelay}ms | last_error=${hr.error}`);
+      await new Promise(r => setTimeout(r, _retryDelay));
+      if (!_helloInFlight) {
+        _helloInFlight = _pconnWrite({
+          cmd: 'hello', protocol: 'claws/2', role: 'orchestrator', peerName: 'mcp-orchestrator',
+          ...(process.env.CLAWS_TERMINAL_CORR_ID ? { correlation_id: process.env.CLAWS_TERMINAL_CORR_ID } : {}),
+        }, 5000).finally(() => { _helloInFlight = null; });
+      }
+      hr = await _helloInFlight;
+      log(`PCONN-DEBUG: hello-ack | ok=${hr && hr.ok} | peerId=${hr && hr.peerId} | error=${hr && hr.error}`);
+    }
+    // Verify hello actually succeeded — silent failure is the root cause of Bug 12.
+    // If the extension returned ok:false (e.g., 'root orchestrator already registered' race),
+    // throw so callers see the failure instead of proceeding with peerId=null.
+    if (!hr || hr.ok !== true) {
+      const err = (hr && hr.error) || 'no response';
+      throw new Error(`pconn hello failed: ${err}${_helloRetries > 0 ? ` (after ${_helloRetries} retries)` : ''}`);
+    }
+    // Capture identity and bind it to the current socket.
+    _pconn.peerId = hr.peerId;
+    _pconn.helloSocketId = _pconn.socketId;  // hello succeeded on THIS socket
+    _pconn.role = 'orchestrator';
+    _pconn.peerName = 'mcp-orchestrator';
+    // Re-enable scan if it was disabled — explicit reconnect counts as resume.
+    _circuitBreaker.scanDisabled = false;
+    _circuitBreaker.scanConsecutiveErrors = 0;
+    log('auto-registered as peer ' + hr.peerId + ' role=orchestrator socketId=' + _pconn.socketId);
+  }
+  // Wave D: subscribe to system.worker.terminated once registered so push frames
+  // arrive and populate _workerTerminatedSet for the terminated completion signal.
+  if (_pconn.peerId && !_workerTerminatedSubscribed) {
+    try {
+      await _pconnWriteOrThrow({ cmd: 'subscribe', protocol: 'claws/2', topic: 'system.worker.terminated' }, 5000);
+      _workerTerminatedSubscribed = true;
+    } catch { /* non-fatal; watcher falls back to marker/error/pub_complete signals */ }
+  }
+  // AF-AC Phase 1: subscribe to system.worker.process_exited — new primary completion signal.
+  if (_pconn.peerId && !_workerProcessExitedSubscribed) {
+    try {
+      await _pconnWriteOrThrow({ cmd: 'subscribe', protocol: 'claws/2', topic: 'system.worker.process_exited' }, 5000);
+      _workerProcessExitedSubscribed = true;
+    } catch { /* non-fatal; existing detach watcher layers remain active */ }
+  }
+  // Phase 4a: subscribe to worker.+.complete wildcard so bus-published completions
+  // populate _workerCompletedViaBusSet for the highest-priority completion signal.
+  if (_pconn.peerId && !_workerBusCompletedSubscribed) {
+    try {
+      await _pconnWriteOrThrow({ cmd: 'subscribe', protocol: 'claws/2', topic: 'worker.+.complete' }, 5000);
+      _workerBusCompletedSubscribed = true;
+    } catch { /* non-fatal */ }
+  }
+  // W8ac-2: subscribe to boot-readiness events so _waitForWorkerReady listeners resolve.
+  if (_pconn.peerId && !_workerPeerConnectedSubscribed) {
+    try {
+      await _pconnWriteOrThrow({ cmd: 'subscribe', protocol: 'claws/2', topic: 'system.peer.connected' }, 5000);
+      _workerPeerConnectedSubscribed = true;
+    } catch { /* non-fatal */ }
+  }
+  if (_pconn.peerId && !_workerTerminalReadySubscribed) {
+    try {
+      await _pconnWriteOrThrow({ cmd: 'subscribe', protocol: 'claws/2', topic: 'system.terminal.ready' }, 5000);
+      _workerTerminalReadySubscribed = true;
+    } catch { /* non-fatal */ }
+  }
+  // AE-7: subscribe to submit confirmation event topics.
+  if (_pconn.peerId && !_vehicleContentSubscribed) {
+    try {
+      await _pconnWriteOrThrow({ cmd: 'subscribe', protocol: 'claws/2', topic: 'vehicle.+.content' }, 5000);
+      _vehicleContentSubscribed = true;
+    } catch { /* non-fatal */ }
+  }
+  if (_pconn.peerId && !_toolInvokedSubscribed) {
+    try {
+      await _pconnWriteOrThrow({ cmd: 'subscribe', protocol: 'claws/2', topic: 'tool.+.invoked' }, 5000);
+      _toolInvokedSubscribed = true;
+    } catch { /* non-fatal */ }
+  }
+}
+
+// ─── Tool handlers ─────────────────────────────────────────────────────────
+
+// Compute a named pipe path from a workspace root path (win32 only).
+// Same algorithm as extension/src/transport.ts getServerEndpoint().
+function _winPipeName(workspaceRoot) {
+  const hash = require('crypto')
+    .createHash('sha256')
+    .update(workspaceRoot.toLowerCase())
+    .digest('hex')
+    .slice(0, 8);
+  return `\\\\.\\pipe\\claws-${hash}`;
+}
+
+// Walk up from a starting directory looking for a .claws/ directory.
+// Used on win32 to locate the workspace root (pipes have no filesystem presence).
+function _findWorkspaceRoot(startDir) {
+  let dir = startDir;
+  while (dir) {
+    try { if (fs.statSync(path.join(dir, '.claws')).isDirectory()) return dir; } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// Return the filesystem path to .claws/events.log regardless of platform.
+// On win32 sock is a named pipe (\\.\pipe\...), not a filesystem path, so we
+// derive the workspace root via env var or directory walk instead.
+function _eventsLogPath(sock) {
+  if (process.platform === 'win32') {
+    const root = process.env.CLAWS_WORKSPACE_ROOT
+      || _findWorkspaceRoot(process.cwd())
+      || _findWorkspaceRoot(__dirname)
+      || process.cwd();
+    return path.join(root, '.claws', 'events.log');
+  }
+  return path.join(path.dirname(path.resolve(sock)), 'events.log');
+}
+
+function getSocket() {
+  // Absolute override wins immediately.
+  const envSock = process.env.CLAWS_SOCKET;
+  if (envSock && path.isAbsolute(envSock)) return envSock;
+
+  if (process.platform === 'win32') {
+    // Named pipes have no filesystem presence — derive the name from the
+    // workspace root path using the same sha256[0:8] algorithm as transport.ts.
+    const workspaceRoot = process.env.CLAWS_WORKSPACE_ROOT
+      || _findWorkspaceRoot(process.cwd())
+      || _findWorkspaceRoot(__dirname)
+      || process.cwd();
+    return _winPipeName(workspaceRoot);
+  }
+
+  // Mac / Linux: walk up from CWD to find .claws/claws.sock.
+  // Works when Claude Code chdir'd to the workspace root before spawning the MCP server.
+  for (let dir = process.cwd();;) {
+    const candidate = path.join(dir, '.claws', 'claws.sock');
+    try { if (fs.statSync(candidate).isSocket()) return candidate; } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Walk up from __dirname — self-locating regardless of CWD.
+  // Project install: .claws-bin/mcp_server.js -> parent = project root -> .claws/claws.sock
+  // Global install: ~/.claws-src/mcp_server.js -> walks up, finds nothing, falls through.
+  for (let dir = __dirname;;) {
+    const candidate = path.join(dir, '.claws', 'claws.sock');
+    try { if (fs.statSync(candidate).isSocket()) return candidate; } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Fall back to env var (may be relative) or the conventional default.
+  return envSock || '.claws/claws.sock';
+}
+
+const _detachWatchers = new Map(); // termId -> { intervalId, opt, startedAt }
+
+// Safety guard: cap any single blocking tool response to 8 s over MCP stdio.
+async function withMaxHold(promise, maxMs = 8000, partialBuilder) {
+  let timer;
+  const timeout = new Promise(r => { timer = setTimeout(() => r({ __maxHold: true }), maxMs); });
+  const winner = await Promise.race([promise, timeout]);
+  clearTimeout(timer);
+  if (winner && winner.__maxHold) return partialBuilder();
+  return winner;
+}
+
+// BUG-12: translate opaque lifecycle gate codes into actionable messages.
+function _lifecycleErrMsg(rawErr) {
+  if (typeof rawErr === 'string' && rawErr.startsWith('lifecycle:')) {
+    return `lifecycle gate active (${rawErr}) — call claws_lifecycle_plan to start a new cycle before spawning new terminals`;
+  }
+  return rawErr;
+}
+
+// Per-tool error boundary: converts a thrown exception into a JSON-RPC error
+// response so one handler bug cannot propagate and kill the bridge process.
+// Applied at the handleTool dispatch level, covering all 41 tools uniformly.
+async function safeInvoke(handler, args) {
+  try {
+    return await handler(args);
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: '[claws-mcp][error] ' + (err && err.stack || String(err)) }],
+      isError: true,
+    };
+  }
+}
+
+async function handleTool(name, args) {
+  const sock = getSocket();
+  _ensureSidecarOrThrow(2000).catch(() => {}); // best-effort warm-up
+  const _t0 = Date.now();
+  try {
+    await _pconnEnsureRegistered(sock);
+    await _pconnWriteOrThrow({ cmd: 'publish', protocol: 'claws/2', topic: `tool.${name}.invoked`, payload: { peerId: _pconn.peerId, correlation_id: process.env.CLAWS_TERMINAL_CORR_ID || null, args_keys: Object.keys(args) } });
+  } catch (_pe) { /* best-effort */ }
+  let _r;
+  try {
+    _r = await _dispatchTool(name, args, sock);
+  } catch (_te) {
+    try {
+      await _pconnEnsureRegistered(sock);
+      await _pconnWriteOrThrow({ cmd: 'publish', protocol: 'claws/2', topic: `tool.${name}.failed`, payload: { duration_ms: Date.now() - _t0, error: _te && _te.message || String(_te) } });
+    } catch (_pe) { /* best-effort */ }
+    // Return error response instead of re-throwing so the bridge stays alive.
+    // process.on('unhandledRejection') is the outer safety net; this is the
+    // per-tool net that converts handler exceptions to proper JSON-RPC errors.
+    _r = await safeInvoke(() => { throw _te; });
+  }
+  try {
+    await _pconnEnsureRegistered(sock);
+    await _pconnWriteOrThrow({ cmd: 'publish', protocol: 'claws/2', topic: `tool.${name}.completed`, payload: { duration_ms: Date.now() - _t0 } });
+  } catch (_pe) { /* best-effort */ }
+  return _r;
+}
+
+async function _dispatchTool(name, args, sock) {
+
+  if (name === 'claws_list') {
+    const resp = await clawsRpc(sock, { cmd: 'list' });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    const terms = resp.terminals || [];
+    if (!terms.length) return { content: [{ type: 'text', text: '[no terminals open]' }] };
+    const lines = terms.map(t => {
+      // R4: trust the `wrapped` boolean. Old code keyed off `logPath` which is
+      // always null in the Pseudoterminal capture model — every wrapped
+      // terminal was misreported as unwrapped.
+      // Annotate pipe-mode degradation explicitly so the user sees it at a glance.
+      let wrap;
+      if (!t.wrapped) {
+        wrap = 'unwrapped';
+      } else if (t.ptyMode === 'pipe') {
+        wrap = 'WRAPPED-DEGRADED-pipe-mode';
+      } else if (t.ptyMode === 'pty') {
+        wrap = 'WRAPPED';
+      } else if (t.ptyMode === 'none') {
+        wrap = 'WRAPPED-pending'; // pty.open() not called yet (panel hidden?)
+      } else {
+        wrap = 'WRAPPED';
+      }
+      const marker = t.active ? '*' : ' ';
+      // R7: Pseudoterminal terminals report pid=-1 from VS Code's API
+      // (VS Code didn't spawn the shell — we did). Prefer ptyPid.
+      const realPid = (typeof t.ptyPid === 'number' && t.ptyPid > 0) ? t.ptyPid : t.pid;
+      return `${marker} ${t.id}  ${(t.name || '').padEnd(25)} pid=${realPid}  [${wrap}]`;
+    });
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  }
+
+  if (name === 'claws_create') {
+    try { await _ensureSidecarOrThrow(); } catch (e) { return toolError('SPAWN REFUSED: sidecar unavailable — ' + e.message); }
+    const _createCorrId = (typeof args.correlation_id === 'string' && args.correlation_id) ? args.correlation_id : randomUUID();
+    const resp = await clawsRpc(sock, {
+      cmd: 'create', name: args.name || 'claws',
+      cwd: (typeof args.cwd === 'string' && args.cwd.length > 0) ? args.cwd : process.cwd(), wrapped: args.wrapped !== false, show: true,
+      correlation_id: _createCorrId,
+    });
+    if (!resp.ok) return toolError(`ERROR: ${_lifecycleErrMsg(resp.error)}`);
+    const eventsLogPath = _eventsLogPath(sock);
+    const _createTermId = resp.id;
+    const _createMonitorCmd = `Monitor(command="node ${STREAM_EVENTS_JS_FOR_CMD} --wait ${_createCorrId} --keep-alive-on ${_createTermId}", description="claws monitor | term=${_createTermId} | corr=${_createCorrId.slice(0,8)} | sess=${new Date().toISOString().slice(0,13)}", timeout_ms=3600000, persistent=false)`;
+    // D+F: register spawn + monitor atomically before returning. Best-effort (lifecycle may not be in active mission).
+    try { await clawsRpc(sock, { cmd: 'lifecycle.register-spawn', terminalId: String(_createTermId), correlationId: _createCorrId, name: args.name || 'claws' }); } catch (e) { /* lifecycle not initialized — non-fatal for claws_create */ }
+    try { await clawsRpc(sock, { cmd: 'lifecycle.register-monitor', terminalId: String(_createTermId), correlationId: _createCorrId, command: _createMonitorCmd }); } catch (e) { /* non-fatal */ }
+    try { await clawsRpc(sock, { cmd: 'monitors.register-intent', correlation_id: _createCorrId }); } catch (_e) { /* non-fatal */ }
+    // Layer 2 (Bug-6 / Bug-13): 30s first check — true orphan vs arm-in-flight (two-stage state machine).
+    const _createTermIdStr = String(_createTermId);
+    setTimeout(async () => {
+      const _l2f = (m) => { log(m); _logL2File(sock, m); };
+      _l2f(`L2-DEBUG: callback-entered | site=claws_create | corrId=${_createCorrId} | termId=${_createTermIdStr}`);
+      try {
+        const armResp = await clawsRpc(sock, { cmd: 'monitors.is-corr-armed', correlation_id: _createCorrId });
+        _l2f(`L2-DEBUG: rpc-result | site=claws_create | ok=${armResp.ok} | armed=${armResp.armed} | claimed=${armResp.claimed} | pending=${armResp.pending} | peerId=${armResp.peerId}`);
+        if (!armResp.ok) return;  // RPC error, can't decide
+        if (armResp.claimed) {
+          _l2f(`L2-DEBUG: skip-publish | site=claws_create | reason=claimed | corrId=${_createCorrId}`);
+          return;
+        }
+        if (!armResp.pending) {
+          // True orphan — neither intent nor execution registered.
+          log(`L2-warn: claws_create term=${_createTermIdStr} corr=${_createCorrId} — no intent or execution at 30s. True orphan.`);
+          _l2f(`L2-DEBUG: about-to-publish | site=claws_create | corrId=${_createCorrId} | reason=no-intent`);
+          try {
+            await _pconnEnsureRegistered(sock);
+            _l2f(`L2-DEBUG: pconn-registered | site=claws_create`);
+            await _pconnWriteOrThrow({
+              cmd: 'publish', protocol: 'claws/2',
+              topic: 'system.monitor.unarmed',
+              payload: { terminal_id: _createTermIdStr, correlation_id: _createCorrId, layer: 2,
+                detected_at: new Date().toISOString(), grace_ms: 30000, reason: 'no-intent' },
+            });
+            _l2f(`L2-DEBUG: publish-succeeded | site=claws_create | corrId=${_createCorrId}`);
+          } catch (_pe) {
+            _l2f(`L2-DEBUG: publish-failed | site=claws_create | err=${_pe && _pe.message || _pe}`);
+          }
+          return;
+        }
+        // pending=true, claimed=false — arm in flight. Re-check at +60s.
+        _l2f(`L2-DEBUG: arm-in-flight | site=claws_create | corrId=${_createCorrId} | scheduling-recheck-60s`);
+        setTimeout(async () => {
+          _l2f(`L2-DEBUG: recheck-entered | site=claws_create | corrId=${_createCorrId} | termId=${_createTermIdStr}`);
+          try {
+            const r2 = await clawsRpc(sock, { cmd: 'monitors.is-corr-armed', correlation_id: _createCorrId });
+            _l2f(`L2-DEBUG: recheck-rpc-result | site=claws_create | ok=${r2.ok} | armed=${r2.armed} | claimed=${r2.claimed} | pending=${r2.pending} | peerId=${r2.peerId}`);
+            if (!r2.ok || r2.claimed) {
+              _l2f(`L2-DEBUG: recheck-skip | site=claws_create | reason=${!r2.ok ? 'rpc-error' : 'claimed'}`);
+              return;
+            }
+            const reason = r2.pending ? 'pending-timeout' : 'pending-vacated';
+            log(`L2-warn: claws_create term=${_createTermIdStr} corr=${_createCorrId} — ${reason} at 90s. Publishing unarmed.`);
+            _l2f(`L2-DEBUG: about-to-publish | site=claws_create | corrId=${_createCorrId} | reason=${reason}`);
+            try {
+              await _pconnEnsureRegistered(sock);
+              _l2f(`L2-DEBUG: pconn-registered | site=claws_create`);
+              await _pconnWriteOrThrow({
+                cmd: 'publish', protocol: 'claws/2',
+                topic: 'system.monitor.unarmed',
+                payload: { terminal_id: _createTermIdStr, correlation_id: _createCorrId, layer: 2,
+                  detected_at: new Date().toISOString(), grace_ms: 90000, reason },
+              });
+              _l2f(`L2-DEBUG: publish-succeeded | site=claws_create | corrId=${_createCorrId}`);
+            } catch (_pe) {
+              _l2f(`L2-DEBUG: publish-failed | site=claws_create | err=${_pe && _pe.message || _pe}`);
+            }
+          } catch (_e) { _l2f(`L2-DEBUG: recheck-error | site=claws_create | err=${_e && _e.message || _e}`); }
+        }, 60000);
+      } catch (_e) { _l2f(`L2-DEBUG: outer-error | site=claws_create | err=${_e && _e.message || _e}`); }
+    }, 30000);
+    const createResult = {
+      ok: true, terminal_id: _createTermId,
+      correlation_id: _createCorrId,
+      ...(resp.logPath ? { log_path: resp.logPath } : {}),
+      monitor_arm_required: true,
+      monitor_arm_command: _createMonitorCmd,
+      events_log_path: eventsLogPath,
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(createResult, null, 2) }] };
+  }
+
+  if (name === 'claws_send') {
+    // Auto-enable bracketed paste for multi-line text. Matches the documented
+    // tool behavior and ensures the trailing CR registers as Enter in TUIs
+    // like Claude Code (the extension splits the CR into a separate write
+    // when bracketed paste is used; see claws-pty.ts:writeInjected).
+    const text = args.text ?? '';
+    const isMultiLine = text.includes('\n') || text.includes('\r');
+    const resp = await clawsRpc(sock, {
+      cmd: 'send', id: args.id, text,
+      newline: args.newline !== false,
+      paste: isMultiLine,
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    return { content: [{ type: 'text', text: 'sent' }] };
+  }
+
+  if (name === 'claws_exec') {
+    const timeoutMs = args.timeout_ms || 180000;
+    return withMaxHold(
+      fileExec(sock, args.id, args.command, timeoutMs).then((result) => {
+        if (!result.ok) {
+          let text = `ERROR: ${result.error}`;
+          if (result.partial) text += `\n[partial output]\n${result.partial}`;
+          return toolError(text);
+        }
+        return { content: [{ type: 'text', text: `exit ${result.exit_code}\n${result.output}` }] };
+      }),
+      8000,
+      () => ({ content: [{ type: 'text', text: JSON.stringify({ ok: true, partial: true, hint: 'use claws_workers_wait to monitor' }) }] }),
+    );
+  }
+
+  if (name === 'claws_read_log') {
+    const resp = await clawsRpc(sock, { cmd: 'readLog', id: args.id, strip: true });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    const allLines = (resp.bytes || '').split('\n');
+    const n = args.lines || 50;
+    const tail = allLines.length > n ? allLines.slice(-n) : allLines;
+    const header = `[term ${args.id} · ${resp.totalSize || 0} bytes · showing last ${tail.length} of ${allLines.length} lines]`;
+    return { content: [{ type: 'text', text: header + '\n' + tail.join('\n') }] };
+  }
+
+  if (name === 'claws_poll') {
+    const resp = await clawsRpc(sock, { cmd: 'poll', since: args.since || 0 });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    const events = resp.events || [];
+    if (!events.length) return { content: [{ type: 'text', text: `[no events · cursor ${resp.cursor || 0}]` }] };
+    const lines = events.map(e => {
+      let line = `[seq ${e.seq} · ${e.terminalName} · exit ${e.exitCode}] $ ${e.commandLine || ''}`;
+      if (e.output) {
+        const out = e.output.length > 500 ? e.output.slice(0, 500) + '...' : e.output;
+        line += '\n' + out;
+      }
+      return line;
+    });
+    return { content: [{ type: 'text', text: lines.join('\n') + `\n[cursor ${resp.cursor}]` }] };
+  }
+
+  if (name === 'claws_close') {
+    const resp = await clawsRpc(sock, { cmd: 'close', id: args.id });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    // BUG-B-close: cancel matching _detachWatcher when the orchestrator explicitly
+    // closes a worker terminal. Without this, the watcher keeps polling for up to
+    // 10 min then logs a spurious 'timeout'/'user-closed' result.
+    const _bugBCloseTermId = String(args.id);
+    const _bugBCloseWatcher = _detachWatchers.get(_bugBCloseTermId);
+    if (_bugBCloseWatcher) {
+      log(`BUG-B-close: cancelling _detachWatcher for orchestrator-closed term=${_bugBCloseTermId}`);
+      if (_bugBCloseWatcher.intervalId) clearInterval(_bugBCloseWatcher.intervalId);
+      _detachWatchers.delete(_bugBCloseTermId);
+    }
+    return { content: [{ type: 'text', text: `closed terminal ${args.id}` }] };
+  }
+
+  /**
+   * claws_hello — register this Claude session with the Claws server.
+   * Calls the claws/2 `hello` command. Must be invoked before any
+   * subscribe/publish/task/broadcast call so the server can allocate a
+   * stable peerId for this connection.
+   * Role requirements: none (any role may hello).
+   * Returns: peerId, serverCapabilities, rootOrchestratorPresent.
+   */
+  if (name === 'claws_hello') {
+    // Connect the persistent socket if not already connected. All subsequent
+    // stateful calls (publish, subscribe, broadcast) share this socket so that
+    // the server's per-connection peer state survives across tool calls.
+    try {
+      await _pconnEnsure(sock);
+    } catch (err) {
+      return toolError(`ERROR: cannot connect to Claws server: ${err.message}`);
+    }
+    const resp = await _pconnWrite({
+      cmd: 'hello',
+      protocol: 'claws/2',
+      role: args.role,
+      peerName: args.peerName,
+      terminalId: args.terminalId,
+      capabilities: Array.isArray(args.capabilities) ? args.capabilities : undefined,
+      waveId: args.waveId || undefined,
+      subWorkerRole: args.subWorkerRole || undefined,
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'hello failed'}`);
+    // Cache identity so we can re-register after a socket reconnect.
+    _pconn.peerId = resp.peerId;
+    _pconn.role = args.role;
+    _pconn.peerName = args.peerName;
+    _pconn.capabilities = Array.isArray(args.capabilities) ? args.capabilities : null;
+    log(`registered as peer ${resp.peerId} role=${args.role}`);
+    const out = {
+      peerId: resp.peerId,
+      serverCapabilities: resp.serverCapabilities || [],
+      rootOrchestratorPresent: !!resp.rootOrchestratorPresent,
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] };
+  }
+
+  /**
+   * claws_subscribe — subscribe this client to a topic pattern on the bus.
+   * Calls the claws/2 `subscribe` command. Server-pushed frames for matching
+   * topics will be delivered on this socket thereafter.
+   * Role requirements: none (orchestrator, worker, and observer may all subscribe).
+   * Returns: subscriptionId (opaque string used with unsubscribe).
+   */
+  if (name === 'claws_subscribe') {
+    const resp = await clawsRpcStateful(sock, { cmd: 'subscribe', topic: args.topic });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'subscribe failed'}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ subscriptionId: resp.subscriptionId, resumeCursor: resp.resumeCursor ?? null }, null, 2) }] };
+  }
+
+  /**
+   * claws_publish — publish a payload to a topic on the Claws message bus.
+   * Calls the claws/2 `publish` command. Delivered to every peer whose
+   * subscription pattern matches the topic; the sender receives the message
+   * too only when `echo: true`.
+   * Role requirements: none (any peer may publish).
+   * Returns: deliveredTo (number of subscribers who received the frame).
+   */
+  if (name === 'claws_publish') {
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'publish',
+      topic: args.topic,
+      payload: args.payload || {},
+      echo: !!args.echo,
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'publish failed'}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ deliveredTo: resp.deliveredTo || 0 }, null, 2) }] };
+  }
+
+  /**
+   * claws_broadcast — orchestrator-only fan-out to all workers (or all peers).
+   * Calls the claws/2 `broadcast` command. With `inject: true` the server also
+   * sends the text into each target peer's associated terminal via bracketed
+   * paste — this is the kill-switch path for workers that are deep in a tool
+   * call and not reading their socket.
+   * Role requirements: caller must have handshaked with role='orchestrator'.
+   * Returns: deliveredTo (number of peers the broadcast reached).
+   */
+  /**
+   * claws_done — zero-arg completion signal. Reads CLAWS_TERMINAL_ID from env,
+   * publishes system.worker.completed, then closes the terminal. Workers call
+   * this as their final action; no payload or schema required.
+   */
+  if (name === 'claws_done') {
+    const termId = process.env.CLAWS_TERMINAL_ID;
+    if (!termId) return toolError('ERROR: CLAWS_TERMINAL_ID not set — claws_done must be called from inside a Claws worker terminal (wrapped=true).');
+    try {
+      await _pconnEnsureRegistered(sock);
+      await _pconnWriteOrThrow({
+        cmd: 'publish', protocol: 'claws/2',
+        topic: 'system.worker.completed',
+        payload: { terminal_id: termId, status: 'completed', completion_signal: 'claws_done', marker: '__CLAWS_DONE__' },
+      }, 3000);
+    } catch (_e) { /* non-fatal — still close */ }
+    try { await clawsRpc(sock, { cmd: 'close', id: termId, close_origin: 'claws_done' }); } catch (_e) { /* non-fatal */ }
+    return { content: [{ type: 'text', text: JSON.stringify({ ok: true, terminalId: termId }) }] };
+  }
+
+  /**
+   * claws_reload_window — trigger VS Code window reload from MCP.
+   * Sends reload_window cmd to the extension, which calls
+   * workbench.action.reloadWindow. The response may not arrive (reload kills
+   * the extension host) — that is expected. Bootstrap requires one final manual
+   * reload+reconnect; thereafter zero-friction.
+   */
+  if (name === 'claws_reload_window') {
+    try {
+      await clawsRpc(sock, { cmd: 'reload_window' });
+    } catch (_e) { /* non-fatal — reload kills the socket */ }
+    return { content: [{ type: 'text', text: JSON.stringify({ ok: true, reloading: true }) }] };
+  }
+
+  /**
+   * claws_reload_mcp — restart the MCP server process.
+   * Returns ok:true immediately, then calls setImmediate(() => process.exit(0))
+   * so the response flushes before exit. Trusts the MCP supervisor to respawn.
+   */
+  if (name === 'claws_reload_mcp') {
+    setImmediate(() => process.exit(0));
+    return { content: [{ type: 'text', text: JSON.stringify({ ok: true }) }] };
+  }
+
+  if (name === 'claws_broadcast') {
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'broadcast',
+      text: args.text,
+      targetRole: args.targetRole || 'worker',
+      inject: !!args.inject,
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'broadcast failed'}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ deliveredTo: resp.deliveredTo || 0 }, null, 2) }] };
+  }
+
+  /**
+   * claws_ping — liveness check.
+   * Calls the claws/2 `ping` command. Also acts as an implicit heartbeat —
+   * the server refreshes the caller's `lastSeen` so it is not reaped as
+   * offline.
+   * Role requirements: none.
+   * Returns: serverTime (ms since epoch as reported by the server).
+   */
+  if (name === 'claws_ping') {
+    const resp = await clawsRpc(sock, { cmd: 'ping' });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'ping failed'}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ serverTime: resp.serverTime }, null, 2) }] };
+  }
+
+  /**
+   * claws_peers — list all registered claws/2 peers.
+   * There is no dedicated `peers` command on the server yet, so this tool
+   * calls `introspect` and surfaces whatever peer info is included in the
+   * snapshot (claws/2 Phase A exposes a peers map on the connection server).
+   * Role requirements: none.
+   * Returns: an array of peer records with { peerId, role, peerName, terminalId, lastSeen }.
+   *
+   * TODO: server-side 'peers' command needed in claws/2 Phase C — until then
+   * we synthesise the list from `introspect` output. If the server already
+   * has a `peers` command available we fall back to that first.
+   */
+  if (name === 'claws_peers') {
+    // Prefer a direct `peers` command via the persistent socket (requires hello).
+    // Fall back to `introspect` via a per-call socket for Phase C parity.
+    let resp = await clawsRpcStateful(sock, { cmd: 'peers' });
+    if (!resp.ok) {
+      resp = await clawsRpc(sock, { cmd: 'introspect' });
+    }
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'peers lookup failed'}`);
+    const peers = resp.peers || (resp.snapshot && resp.snapshot.peers) || [];
+    return { content: [{ type: 'text', text: JSON.stringify({ peers }, null, 2) }] };
+  }
+
+  if (name === 'claws_worker') {
+    try { await _ensureSidecarOrThrow(); } catch (e) { return toolError('SPAWN REFUSED: sidecar unavailable — ' + e.message); }
+    const hasCommand = typeof args.command === 'string' && args.command.length > 0;
+    const detach = args.detach !== undefined
+      ? args.detach !== false
+      : !hasCommand;  // mission-mode default: detach=true; command-mode default: detach=false
+    // Blocking mode: explicit wait:true OR detach:false (command-mode default) are both treated as blocking.
+    if (args.wait === true || !detach) {
+      // Legacy blocking path — guarded at 8 s to protect MCP stdio.
+      return withMaxHold(
+        runBlockingWorker(sock, args).then((result) => {
+          if (result.status === 'error') return toolError(`ERROR: ${result.error}`);
+          const header = [
+            `worker '${args.name}' ${result.status.toUpperCase()}`,
+            `  terminal:   ${result.terminal_id}`,
+            `  duration:   ${(result.duration_ms / 1000).toFixed(1)}s`,
+            `  booted:     ${result.booted}`,
+            `  cleaned_up: ${result.cleaned_up}`,
+          ];
+          if (result.marker_line) header.push(`  marker:     ${result.marker_line}`);
+          if (result.status === 'spawned') {
+            header.push('', `detached mode — use claws_read_log id=${result.terminal_id} and claws_close when done`);
+            return { content: [{ type: 'text', text: header.join('\n') }] };
+          }
+          const body = result.harvest || '';
+          return { content: [{ type: 'text', text: header.join('\n') + '\n\n── harvest (last lines) ──\n' + body }] };
+        }),
+        8000,
+        () => ({ content: [{ type: 'text', text: JSON.stringify({ ok: true, partial: true, hint: 'use claws_workers_wait to monitor' }) }] }),
+      );
+    }
+
+    // Non-blocking fast path (default) — boots terminal, sends mission, returns terminal_id immediately.
+    const model = args.model || 'claude-sonnet-4-6';
+    if (!/^[a-zA-Z0-9._-]+$/.test(model)) {
+      return toolError(`ERROR: invalid model name '${model}' — must match /^[a-zA-Z0-9._-]+$/`);
+    }
+    const hasMission = typeof args.mission === 'string' && args.mission.length > 0;
+    const launchClaude = args.launch_claude !== undefined ? !!args.launch_claude : hasMission;
+    const workerCwd = typeof args.cwd === 'string' && args.cwd.length > 0 ? args.cwd : process.cwd();
+
+    const _fpCorrId = randomUUID();
+    const cr = await clawsRpc(sock, {
+      cmd: 'create', name: args.name || 'claws-worker', wrapped: true, show: true, cwd: workerCwd,
+      env: { CLAWS_WORKER: '1' }, correlation_id: _fpCorrId,
+    });
+    if (!cr.ok) return toolError(`ERROR: create failed: ${_lifecycleErrMsg(cr.error)}`);
+    const termId = cr.id;
+    _clearStaleCompletionSignals(termId);
+    const _fpStartedAt = Date.now();
+
+    // BUG-23: publish system.worker.spawned on non-blocking fast path — best-effort.
+    try {
+      await _pconnEnsureRegistered(sock);
+      await _pconnWriteOrThrow({
+        cmd: 'publish', protocol: 'claws/2',
+        topic: 'system.worker.spawned',
+        payload: { terminal_id: termId, name: args.name || 'claws-worker', wrapped: true, started_at: new Date(_fpStartedAt).toISOString(), correlation_id: _fpCorrId },
+      });
+    } catch (e) { log('system.worker.spawned publish failed: ' + (e && e.message || e)); }
+
+    // D+F: register spawn + monitor atomically. Best-effort (lifecycle may not be in active mission).
+    try { await clawsRpc(sock, { cmd: 'lifecycle.register-spawn', terminalId: String(termId), correlationId: _fpCorrId, name: args.name || 'claws-worker' }); } catch (e) { /* non-fatal */ }
+    const _fpMonitorCmd = `Monitor(command="node ${STREAM_EVENTS_JS_FOR_CMD} --wait ${_fpCorrId} --keep-alive-on ${termId}", description="claws monitor | term=${termId} | corr=${_fpCorrId.slice(0,8)} | sess=${new Date().toISOString().slice(0,13)}", timeout_ms=3600000, persistent=false)`;
+    try { await clawsRpc(sock, { cmd: 'lifecycle.register-monitor', terminalId: String(termId), correlationId: _fpCorrId, command: _fpMonitorCmd }); } catch (e) { /* non-fatal */ }
+    try { await clawsRpc(sock, { cmd: 'monitors.register-intent', correlation_id: _fpCorrId }); } catch (_e) { /* non-fatal */ }
+    // T4: monitor-arm grace warning — 5s after spawn, warn if no monitor registered in lifecycle.
+    const _fpMonitorGraceMs = 5000;
+    const _fpTermIdStr = String(termId);
+    setTimeout(async () => {
+      try {
+        const snap = await clawsRpc(sock, { cmd: 'lifecycle.snapshot' });
+        if (snap.ok && snap.state) {
+          const hasMonitor = (snap.state.monitors || []).some(m => m.terminal_id === _fpTermIdStr);
+          if (!hasMonitor) {
+            log(`T4-warn: claws_worker term=${_fpTermIdStr} corr=${_fpCorrId} — no monitor registered within ${_fpMonitorGraceMs}ms grace. Orchestrator may be flying blind. Use monitor_arm_command from spawn response.`);
+          }
+        }
+      } catch (_e) { /* non-fatal */ }
+    }, _fpMonitorGraceMs);
+    // Layer 2 (Bug-6 / Bug-13): 30s first check — true orphan vs arm-in-flight (two-stage state machine).
+    setTimeout(async () => {
+      const _l2f = (m) => { log(m); _logL2File(sock, m); };
+      _l2f(`L2-DEBUG: callback-entered | site=claws_worker-fast-path | corrId=${_fpCorrId} | termId=${_fpTermIdStr}`);
+      try {
+        const armResp = await clawsRpc(sock, { cmd: 'monitors.is-corr-armed', correlation_id: _fpCorrId });
+        _l2f(`L2-DEBUG: rpc-result | site=claws_worker-fast-path | ok=${armResp.ok} | armed=${armResp.armed} | claimed=${armResp.claimed} | pending=${armResp.pending} | peerId=${armResp.peerId}`);
+        if (!armResp.ok) return;  // RPC error, can't decide
+        if (armResp.claimed) {
+          _l2f(`L2-DEBUG: skip-publish | site=claws_worker-fast-path | reason=claimed | corrId=${_fpCorrId}`);
+          return;
+        }
+        if (!armResp.pending) {
+          // True orphan — neither intent nor execution registered.
+          log(`L2-warn: claws_worker term=${_fpTermIdStr} corr=${_fpCorrId} — no intent or execution at 30s. True orphan.`);
+          _l2f(`L2-DEBUG: about-to-publish | site=claws_worker-fast-path | corrId=${_fpCorrId} | reason=no-intent`);
+          try {
+            await _pconnEnsureRegistered(sock);
+            _l2f(`L2-DEBUG: pconn-registered | site=claws_worker-fast-path`);
+            await _pconnWriteOrThrow({
+              cmd: 'publish', protocol: 'claws/2',
+              topic: 'system.monitor.unarmed',
+              payload: { terminal_id: _fpTermIdStr, correlation_id: _fpCorrId, layer: 2,
+                detected_at: new Date().toISOString(), grace_ms: 30000, reason: 'no-intent' },
+            });
+            _l2f(`L2-DEBUG: publish-succeeded | site=claws_worker-fast-path | corrId=${_fpCorrId}`);
+          } catch (_pe) {
+            _l2f(`L2-DEBUG: publish-failed | site=claws_worker-fast-path | err=${_pe && _pe.message || _pe}`);
+          }
+          return;
+        }
+        // pending=true, claimed=false — arm in flight. Re-check at +60s.
+        _l2f(`L2-DEBUG: arm-in-flight | site=claws_worker-fast-path | corrId=${_fpCorrId} | scheduling-recheck-60s`);
+        setTimeout(async () => {
+          _l2f(`L2-DEBUG: recheck-entered | site=claws_worker-fast-path | corrId=${_fpCorrId} | termId=${_fpTermIdStr}`);
+          try {
+            const r2 = await clawsRpc(sock, { cmd: 'monitors.is-corr-armed', correlation_id: _fpCorrId });
+            _l2f(`L2-DEBUG: recheck-rpc-result | site=claws_worker-fast-path | ok=${r2.ok} | armed=${r2.armed} | claimed=${r2.claimed} | pending=${r2.pending} | peerId=${r2.peerId}`);
+            if (!r2.ok || r2.claimed) {
+              _l2f(`L2-DEBUG: recheck-skip | site=claws_worker-fast-path | reason=${!r2.ok ? 'rpc-error' : 'claimed'}`);
+              return;
+            }
+            const reason = r2.pending ? 'pending-timeout' : 'pending-vacated';
+            log(`L2-warn: claws_worker term=${_fpTermIdStr} corr=${_fpCorrId} — ${reason} at 90s. Publishing unarmed.`);
+            _l2f(`L2-DEBUG: about-to-publish | site=claws_worker-fast-path | corrId=${_fpCorrId} | reason=${reason}`);
+            try {
+              await _pconnEnsureRegistered(sock);
+              _l2f(`L2-DEBUG: pconn-registered | site=claws_worker-fast-path`);
+              await _pconnWriteOrThrow({
+                cmd: 'publish', protocol: 'claws/2',
+                topic: 'system.monitor.unarmed',
+                payload: { terminal_id: _fpTermIdStr, correlation_id: _fpCorrId, layer: 2,
+                  detected_at: new Date().toISOString(), grace_ms: 90000, reason },
+              });
+              _l2f(`L2-DEBUG: publish-succeeded | site=claws_worker-fast-path | corrId=${_fpCorrId}`);
+            } catch (_pe) {
+              _l2f(`L2-DEBUG: publish-failed | site=claws_worker-fast-path | err=${_pe && _pe.message || _pe}`);
+            }
+          } catch (_e) { _l2f(`L2-DEBUG: recheck-error | site=claws_worker-fast-path | err=${_e && _e.message || _e}`); }
+        }, 60000);
+      } catch (_e) { _l2f(`L2-DEBUG: outer-error | site=claws_worker-fast-path | err=${_e && _e.message || _e}`); }
+    }, 30000);
+
+    await sleep(400);
+
+    if (launchClaude) {
+      await clawsRpc(sock, {
+        cmd: 'send', id: termId,
+        text: `${getClaudeBin(args && args.cwd)} --dangerously-skip-permissions --model ${model}`, newline: true,
+      });
+      // AD-1: gate mission paste on confirmed pty-claim.
+      const _gate = await _gatePasteOnClaudeClaim(sock, termId, _fpCorrId, { timeoutMs: args.boot_wait_ms });
+      if (!_gate.booted) {
+        if (args.close_on_complete !== false) { try { await clawsRpc(sock, { cmd: 'close', id: termId }); } catch {} }
+        return toolError(`boot failed: ${_gate.cause} | terminal_id=${termId} | corr=${_fpCorrId}`);
+      }
+    }
+
+    // Phase 4a: one-line completion hint — claws_done() handles the rest.
+    const _fpPhase4Header = hasMission ? `When you're finished, call \`claws_done()\`. That's it.\n\n---\n` : '';
+    const payload = hasMission
+      ? (_fpPhase4Header + args.mission).replace(/\x1b\[200~/g, '').replace(/\x1b\[201~/g, '')
+      : hasCommand ? wrapShellCommand(args.command, termId) : '';
+    // W8k-1: delegate to shared helper — this fast path proved the sequence;
+    // runBlockingWorker (fleet path) now reuses it verbatim. Returns markerScanFrom.
+    const _fpMarkerScanFrom = await _sendAndSubmitMission(sock, termId, _fpCorrId, payload, launchClaude);
+
+    // BUG-24+25: register detach watcher so system.worker.completed is published
+    // and auto-close fires when complete_marker is detected — mirrors the
+    // runBlockingWorker(detach:true) watcher but without boot-polling overhead.
+    const _fpOpt = {
+      complete_marker: typeof args.complete_marker === 'string' ? args.complete_marker : '__CLAWS_DONE__',
+      error_markers: Array.isArray(args.error_markers) ? args.error_markers : ['MISSION_FAILED'],
+      timeout_ms: typeof args.timeout_ms === 'number' ? args.timeout_ms : 5 * 60 * 1000,
+      poll_interval_ms: typeof args.poll_interval_ms === 'number' ? args.poll_interval_ms : 1500,
+      close_on_complete: args.close_on_complete !== false,
+    };
+    const _fpHbState = new WorkerHeartbeatStateMachine({ terminalId: termId, correlationId: _fpCorrId });
+    _setupDetachWatcher({
+      sock, termId, corrId: _fpCorrId, opt: _fpOpt,
+      markerScanFrom: _fpMarkerScanFrom, hbState: _fpHbState,
+      startedAt: _fpStartedAt, extraPayload: { booted: launchClaude },
+    });
+
+    const run_token = randomUUID().slice(0, 12);
+    const workerEventsLogPath = _eventsLogPath(sock);
+    return {
+      content: [{ type: 'text', text: JSON.stringify({
+        ok: true, terminal_id: termId,
+        name: args.name || 'claws-worker',
+        correlation_id: _fpCorrId,
+        run_token,
+        hint: 'use claws_workers_wait to poll completion',
+        monitor_arm_required: true,
+        monitor_arm_command: _fpMonitorCmd,
+        events_log_path: workerEventsLogPath,
+      }, null, 2) }],
+    };
+  }
+
+  if (name === 'claws_fleet') {
+    try { await _ensureSidecarOrThrow(); } catch (e) { return toolError('SPAWN REFUSED: sidecar unavailable — ' + e.message); }
+    const fleetWorkers = Array.isArray(args.workers) ? args.workers : [];
+    if (fleetWorkers.length === 0) {
+      return toolError('ERROR: workers must be a non-empty array of worker configs');
+    }
+    // detach default flipped to true in v0.7.10 — blocking mode unsafe over MCP stdio
+    const detach = args.detach !== false;
+    log(`fleet: enter workers=${fleetWorkers.length} detach=${detach}`);
+    const sharedDefaults = {};
+    for (const k of ['cwd', 'model', 'timeout_ms', 'boot_wait_ms', 'poll_interval_ms', 'harvest_lines', 'close_on_complete']) {
+      if (args[k] !== undefined) sharedDefaults[k] = args[k];
+    }
+    const fleetStartedAt = Date.now();
+    const fleetPromise = Promise.allSettled(
+      fleetWorkers.map((w, _fi) => {
+        const wClean = {};
+        for (const [k, v] of Object.entries(w)) {
+          if (v !== undefined) wClean[k] = v;
+        }
+        log(`fleet: worker[${_fi}] spawn-begin name=${wClean.name || 'unnamed'} mission-len=${(wClean.mission || '').length}`);
+        return runBlockingWorker(sock, { ...sharedDefaults, ...wClean, ...(detach ? { detach: true } : {}) })
+          .then((r) => {
+            log(`fleet: worker[${_fi}] spawn-ok terminal=${r && r.terminal_id} status=${r && r.status}`);
+            return r;
+          })
+          .catch((e) => {
+            log(`fleet: worker[${_fi}] spawn-error ${e && e.message || String(e)}`);
+            throw e;
+          });
+      }),
+    ).then((settled) => {
+      const results = settled.map((s) => s.status === 'fulfilled'
+        ? s.value
+        : { status: 'error', error: String(s.reason && s.reason.message || s.reason || 'unknown') });
+      const fleetEventsLogPath = _eventsLogPath(sock);
+      const summary = {
+        fleet_size: results.length,
+        detach,
+        wall_clock_ms: Date.now() - fleetStartedAt,
+        max_individual_ms: Math.max(...results.map((r) => r.duration_ms || 0), 0),
+        sum_individual_ms: results.reduce((a, r) => a + (r.duration_ms || 0), 0),
+        workers: results.map((r, i) => {
+          const _fTermId = r.terminal_id;
+          const _fCorrId = r.correlation_id;
+          return {
+            name: fleetWorkers[i] && fleetWorkers[i].name,
+            status: r.status,
+            terminal_id: _fTermId,
+            correlation_id: _fCorrId,
+            duration_ms: r.duration_ms,
+            marker_line: r.marker_line,
+            monitor_arm_command: (_fTermId && _fCorrId)
+              ? `Monitor(command="node ${STREAM_EVENTS_JS_FOR_CMD} --wait ${_fCorrId} --keep-alive-on ${_fTermId}", description="claws monitor | term=${_fTermId} | corr=${_fCorrId.slice(0,8)} | sess=${new Date().toISOString().slice(0,13)}", timeout_ms=3600000, persistent=false)`
+              : null,
+          };
+        }),
+        monitor_arm_required: true,
+        monitor_arm_command: 'arm one monitor_arm_command per worker entry above',
+        events_log_path: fleetEventsLogPath,
+      };
+      log(`fleet: exit wall=${summary.wall_clock_ms}ms workers=${results.length}`);
+      return { content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }] };
+    });
+    // Detach:true (default) returns quickly; detach:false legacy path gets the guard.
+    log(`fleet: dispatched detach=${detach}`);
+    return detach
+      ? fleetPromise
+      : withMaxHold(fleetPromise, 8000, () => ({
+          content: [{ type: 'text', text: JSON.stringify({ ok: true, partial: true, hint: 'use claws_workers_wait to monitor' }) }],
+        }));
+  }
+
+  if (name === 'claws_workers_wait') {
+    const ids = Array.isArray(args.terminal_ids) ? args.terminal_ids : [];
+    if (ids.length === 0) {
+      return toolError('ERROR: terminal_ids must be a non-empty array');
+    }
+    const completeMarker = typeof args.complete_marker === 'string' && args.complete_marker.length > 0
+      ? args.complete_marker : '__CLAWS_DONE__';
+    const errorMarkers = Array.isArray(args.error_markers) ? args.error_markers : ['MISSION_FAILED'];
+    const timeoutMs = typeof args.timeout_ms === 'number' && args.timeout_ms > 0 ? args.timeout_ms : 5 * 60 * 1000;
+    const pollIntervalMs = typeof args.poll_interval_ms === 'number' && args.poll_interval_ms > 0 ? args.poll_interval_ms : 1500;
+    const minComplete = (typeof args.min_complete === 'number' && args.min_complete > 0)
+      ? Math.min(args.min_complete, ids.length) : ids.length;
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
+    const detectOpt = { complete_marker: completeMarker, error_markers: errorMarkers };
+    const state = ids.map((id) => ({
+      id: String(id), status: 'pending', signal: null, marker_line: null, duration_ms: null, scanFrom: 0,
+    }));
+    for (const s of state) {
+      try {
+        const snap = await clawsRpc(sock, { cmd: 'readLog', id: s.id, strip: true, limit: 64 * 1024 });
+        if (snap.ok && typeof snap.bytes === 'string') s.scanFrom = snap.bytes.length;
+      } catch (e) { /* keep 0 */ }
+    }
+    const countDone = () => state.filter((s) => s.status !== 'pending').length;
+    while (Date.now() < deadline) {
+      for (const s of state) {
+        if (s.status !== 'pending') continue;
+        try {
+          const snap = await clawsRpc(sock, { cmd: 'readLog', id: s.id, strip: true, limit: 64 * 1024 });
+          const text = snap.ok && typeof snap.bytes === 'string' ? snap.bytes : '';
+          const scanText = text.length > s.scanFrom ? text.slice(s.scanFrom) : '';
+          const det = detectCompletion(scanText, detectOpt, s.id, _workerTerminatedSet, _workerCompletedViaBusSet);
+          if (det !== null) {
+            s.status = det.status;
+            s.signal = det.signal;
+            s.marker_line = det.line;
+            s.duration_ms = Date.now() - startedAt;
+          }
+        } catch (e) { /* terminal vanished — leave pending; will time out */ }
+      }
+      if (countDone() >= minComplete) break;
+      await sleep(pollIntervalMs);
+    }
+    for (const s of state) {
+      if (s.status === 'pending') {
+        s.status = 'timeout';
+        s.duration_ms = Date.now() - startedAt;
+      }
+    }
+    const pendingIds = state.filter((s) => s.status === 'timeout').map((s) => s.id);
+    return { content: [{ type: 'text', text: JSON.stringify({
+      ok: true,
+      complete: state.filter((s) => s.status !== 'timeout').length,
+      target: minComplete,
+      total: state.length,
+      wall_clock_ms: Date.now() - startedAt,
+      pending: pendingIds,
+      results: state.map((s) => ({ terminal_id: s.id, status: s.status, signal: s.signal, marker_line: s.marker_line, duration_ms: s.duration_ms })),
+    }, null, 2) }] };
+  }
+
+  /**
+   * claws_drain_events — drain buffered push frames from the persistent socket.
+   * On first call, auto-subscribes to "**" (all topics) via the persistent socket
+   * so subsequent frames are captured automatically. Returns events received since
+   * since_index, with a dropped count for events that aged out of the ring buffer.
+   * Set wait_ms > 0 to block until at least one new event arrives or the timer fires.
+   */
+  if (name === 'claws_drain_events') {
+    const sinceIndex = typeof args.since_index === 'number' ? args.since_index : 0;
+    const waitMs = typeof args.wait_ms === 'number' ? args.wait_ms : 0;
+    const maxEvents = typeof args.max === 'number' ? args.max : 100;
+
+    // Auto-subscribe on first call.
+    if (!_eventBuffer.subscribed) {
+      try {
+        await _pconnEnsureRegistered(sock);
+        const sr = await _pconnWriteOrThrow({ cmd: 'subscribe', topic: '**' }, 5000);
+        _eventBuffer.subscribed = true;
+        _eventBuffer.subscribeCursor = sr.resumeCursor ?? null;
+      } catch (err) {
+        log('claws_drain_events: auto-subscribe failed: ' + (err && err.message || err));
+      }
+    }
+
+    // If wait_ms > 0 and no new events yet, register a waiter.
+    // Cap waiters at maxWaiters to prevent unbounded accumulation.
+    const hasNew = () => _eventBuffer.ring.some(e => e.absoluteIndex > sinceIndex);
+    if (waitMs > 0 && !hasNew()) {
+      if (_eventBuffer.waiters.length >= _eventBuffer.maxWaiters) {
+        return toolError('ERROR: drain waiter queue full (max 10 concurrent wait_ms requests)');
+      }
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, waitMs);
+        _eventBuffer.waiters.push({ resolve, timer });
+      });
+    }
+
+    const ring = _eventBuffer.ring;
+    const totalReceived = _eventBuffer.totalReceived;
+    const filtered = ring.filter(e => e.absoluteIndex > sinceIndex).slice(0, maxEvents);
+
+    // dropped = events in [sinceIndex+1, ring[0].absoluteIndex - 1] that were evicted.
+    let dropped = 0;
+    if (ring.length > 0) {
+      const firstInRing = ring[0].absoluteIndex;
+      if (firstInRing > sinceIndex + 1) dropped = firstInRing - sinceIndex - 1;
+    }
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({ events: filtered, total_received: totalReceived, dropped, subscribe_cursor: _eventBuffer.subscribeCursor }, null, 2),
+      }],
+    };
+  }
+
+  if (name === 'claws_lifecycle_plan') {
+    const _planMode = (typeof args.worker_mode === 'string') ? args.worker_mode : 'single';
+    const _planExpected = (Number.isInteger(args.expected_workers) && args.expected_workers > 0) ? args.expected_workers : 1;
+    const resp = await clawsRpc(sock, { cmd: 'lifecycle.plan', plan: args.plan, workerMode: _planMode, expectedWorkers: _planExpected });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}\n${resp.message || ''}`);
+    const out = { state: resp.state, idempotent: !!resp.idempotent };
+    return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] };
+  }
+
+  if (name === 'claws_lifecycle_advance') {
+    const resp = await clawsRpc(sock, { cmd: 'lifecycle.advance', to: args.to, reason: args.reason });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}\n${resp.message || ''}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ state: resp.state }, null, 2) }] };
+  }
+
+  if (name === 'claws_lifecycle_snapshot') {
+    const resp = await clawsRpc(sock, { cmd: 'lifecycle.snapshot' });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    const text = resp.state
+      ? JSON.stringify(resp.state, null, 2)
+      : '[no lifecycle state — call claws_lifecycle_plan first]';
+    return { content: [{ type: 'text', text }] };
+  }
+
+  if (name === 'claws_lifecycle_reflect') {
+    const resp = await clawsRpc(sock, { cmd: 'lifecycle.reflect', reflect: args.reflect });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}\n${resp.message || ''}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ state: resp.state }, null, 2) }] };
+  }
+
+  if (name === 'claws_wave_create') {
+    const resp = await clawsRpc(sock, {
+      cmd: 'wave.create',
+      waveId: args.waveId,
+      layers: args.layers,
+      manifest: args.manifest,
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ waveId: resp.waveId, created: resp.created }, null, 2) }] };
+  }
+
+  if (name === 'claws_wave_status') {
+    const resp = await clawsRpc(sock, { cmd: 'wave.status', waveId: args.waveId });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    const tree = {
+      waveId:              resp.waveId,
+      complete:            resp.complete,
+      lead:                resp.lead,
+      subWorkers:          resp.subWorkers,
+      subWorkerTerminals:  resp.subWorkerTerminals,
+      orphanedTerminals:   resp.orphanedTerminals,
+      harvestedAt:         resp.harvestedAt,
+      layers:              resp.layers,
+      createdAt:           resp.createdAt,
+      completedAt:         resp.completedAt,
+      summary:             resp.summary,
+      commits:             resp.commits,
+      regressionClean:     resp.regressionClean,
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(tree, null, 2) }] };
+  }
+
+  if (name === 'claws_wave_complete') {
+    const resp = await clawsRpc(sock, {
+      cmd: 'wave.complete',
+      waveId: args.waveId,
+      summary: args.summary,
+      commits: args.commits,
+      regressionClean: args.regressionClean,
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ waveId: resp.waveId, completedAt: resp.completedAt }, null, 2) }] };
+  }
+
+  if (name === 'claws_deliver_cmd') {
+    const payload = typeof args.payload === 'string' ? JSON.parse(args.payload) : args.payload;
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'deliver-cmd',
+      protocol: 'claws/2',
+      targetPeerId: args.targetPeerId,
+      cmdTopic: args.cmdTopic,
+      payload,
+      idempotencyKey: args.idempotencyKey,
+    });
+    if (!resp.ok && !resp.duplicate) return toolError(`ERROR: ${resp.error}`);
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          ok: resp.ok,
+          seq: resp.seq,
+          duplicate: resp.duplicate ?? false,
+        }, null, 2),
+      }],
+    };
+  }
+
+  if (name === 'claws_cmd_ack') {
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'cmd.ack',
+      protocol: 'claws/2',
+      seq: args.seq,
+      status: args.status,
+      ...(args.correlation_id ? { correlation_id: args.correlation_id } : {}),
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ ok: true }, null, 2) }] };
+  }
+
+  if (name === 'claws_pipeline_create') {
+    const steps = typeof args.steps === 'string' ? JSON.parse(args.steps) : args.steps;
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'pipeline.create',
+      name: args.name || 'pipeline',
+      steps,
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({ pipelineId: resp.pipelineId, pipeline: resp.pipeline }, null, 2),
+      }],
+    };
+  }
+
+  if (name === 'claws_pipeline_list') {
+    const resp = await clawsRpc(sock, { cmd: 'pipeline.list' });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    return { content: [{ type: 'text', text: JSON.stringify(resp.pipelines, null, 2) }] };
+  }
+
+  if (name === 'claws_pipeline_close') {
+    const resp = await clawsRpcStateful(sock, { cmd: 'pipeline.close', pipelineId: args.pipelineId }); // BUG-04: stateful socket carries peerId
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ ok: true, pipelineId: resp.pipelineId }, null, 2) }] };
+  }
+
+  if (name === 'claws_dispatch_subworker') {
+    try { await _ensureSidecarOrThrow(); } catch (e) { return toolError('SPAWN REFUSED: sidecar unavailable — ' + e.message); }
+    // FIX 3: Verify wave was created via claws_wave_create before spawning sub-worker.
+    const waveCheck = await clawsRpc(sock, { cmd: 'wave.status', waveId: args.waveId });
+    if (!waveCheck.ok && typeof waveCheck.error === 'string' && waveCheck.error.includes('not-found')) {
+      return toolError(`SPAWN REFUSED: wave.not-registered — call claws_wave_create({waveId:'${args.waveId}', manifest:[...]}) first`);
+    }
+    const workerName = `wave-${args.waveId}-${args.role}`;
+    const _dswCorrId = randomUUID();
+    const cr = await clawsRpc(sock, {
+      cmd: 'create', name: workerName, wrapped: true, show: true,
+      cwd: typeof args.cwd === 'string' && args.cwd.length > 0 ? args.cwd : process.cwd(),
+      waveId: args.waveId, waveRole: args.role, env: { CLAWS_WORKER: '1' }, correlation_id: _dswCorrId,
+    });
+    if (!cr.ok) return toolError(`ERROR: create failed: ${_lifecycleErrMsg(cr.error)}`);
+    const termId = cr.id;
+    _clearStaleCompletionSignals(termId);
+
+    // BUG-A: publish system.worker.spawned for sub-workers — best-effort.
+    log(`dispatch_subworker: publishing system.worker.spawned for terminal ${termId}`);
+    try {
+      await _pconnEnsureRegistered(sock);
+      await _pconnWriteOrThrow({
+        cmd: 'publish', protocol: 'claws/2',
+        topic: 'system.worker.spawned',
+        payload: { terminal_id: termId, waveId: args.waveId, role: args.role, name: workerName, wrapped: true, started_at: new Date().toISOString(), correlation_id: _dswCorrId },
+      });
+      log(`dispatch_subworker: system.worker.spawned published ok for terminal ${termId}`);
+    } catch (e) { log('dispatch_subworker: system.worker.spawned publish FAILED: ' + (e && e.message || e)); }
+
+    // D+F: register spawn + monitor atomically. Best-effort (lifecycle may not be in active mission).
+    try { await clawsRpc(sock, { cmd: 'lifecycle.register-spawn', terminalId: String(termId), correlationId: _dswCorrId, name: workerName }); } catch (e) { /* non-fatal */ }
+    const _dswMonitorCmd = `Monitor(command="node ${STREAM_EVENTS_JS_FOR_CMD} --wait ${_dswCorrId} --keep-alive-on ${termId}", description="claws monitor | term=${termId} | corr=${_dswCorrId.slice(0,8)} | sess=${new Date().toISOString().slice(0,13)}", timeout_ms=3600000, persistent=false)`;
+    try { await clawsRpc(sock, { cmd: 'lifecycle.register-monitor', terminalId: String(termId), correlationId: _dswCorrId, command: _dswMonitorCmd }); } catch (e) { /* non-fatal */ }
+    try { await clawsRpc(sock, { cmd: 'monitors.register-intent', correlation_id: _dswCorrId }); } catch (_e) { /* non-fatal */ }
+    // T4: monitor-arm grace warning — 5s after spawn, warn if no monitor registered in lifecycle.
+    const _dswMonitorGraceMs = 5000;
+    const _dswTermIdStr = String(termId);
+    setTimeout(async () => {
+      try {
+        const snap = await clawsRpc(sock, { cmd: 'lifecycle.snapshot' });
+        if (snap.ok && snap.state) {
+          const hasMonitor = (snap.state.monitors || []).some(m => m.terminal_id === _dswTermIdStr);
+          if (!hasMonitor) {
+            log(`T4-warn: claws_dispatch_subworker term=${_dswTermIdStr} corr=${_dswCorrId} — no monitor registered within ${_dswMonitorGraceMs}ms grace. Orchestrator may be flying blind. Use monitor_arm_command from spawn response.`);
+          }
+        }
+      } catch (_e) { /* non-fatal */ }
+    }, _dswMonitorGraceMs);
+    // Layer 2 (Bug-6 / Bug-13): 30s first check — true orphan vs arm-in-flight (two-stage state machine).
+    setTimeout(async () => {
+      const _l2f = (m) => { log(m); _logL2File(sock, m); };
+      _l2f(`L2-DEBUG: callback-entered | site=claws_dispatch_subworker | corrId=${_dswCorrId} | termId=${_dswTermIdStr}`);
+      try {
+        const armResp = await clawsRpc(sock, { cmd: 'monitors.is-corr-armed', correlation_id: _dswCorrId });
+        _l2f(`L2-DEBUG: rpc-result | site=claws_dispatch_subworker | ok=${armResp.ok} | armed=${armResp.armed} | claimed=${armResp.claimed} | pending=${armResp.pending} | peerId=${armResp.peerId}`);
+        if (!armResp.ok) return;  // RPC error, can't decide
+        if (armResp.claimed) {
+          _l2f(`L2-DEBUG: skip-publish | site=claws_dispatch_subworker | reason=claimed | corrId=${_dswCorrId}`);
+          return;
+        }
+        if (!armResp.pending) {
+          // True orphan — neither intent nor execution registered.
+          log(`L2-warn: claws_dispatch_subworker term=${_dswTermIdStr} corr=${_dswCorrId} — no intent or execution at 30s. True orphan.`);
+          _l2f(`L2-DEBUG: about-to-publish | site=claws_dispatch_subworker | corrId=${_dswCorrId} | reason=no-intent`);
+          try {
+            await _pconnEnsureRegistered(sock);
+            _l2f(`L2-DEBUG: pconn-registered | site=claws_dispatch_subworker`);
+            await _pconnWriteOrThrow({
+              cmd: 'publish', protocol: 'claws/2',
+              topic: 'system.monitor.unarmed',
+              payload: { terminal_id: _dswTermIdStr, correlation_id: _dswCorrId, layer: 2,
+                detected_at: new Date().toISOString(), grace_ms: 30000, reason: 'no-intent' },
+            });
+            _l2f(`L2-DEBUG: publish-succeeded | site=claws_dispatch_subworker | corrId=${_dswCorrId}`);
+          } catch (_pe) {
+            _l2f(`L2-DEBUG: publish-failed | site=claws_dispatch_subworker | err=${_pe && _pe.message || _pe}`);
+          }
+          return;
+        }
+        // pending=true, claimed=false — arm in flight. Re-check at +60s.
+        _l2f(`L2-DEBUG: arm-in-flight | site=claws_dispatch_subworker | corrId=${_dswCorrId} | scheduling-recheck-60s`);
+        setTimeout(async () => {
+          _l2f(`L2-DEBUG: recheck-entered | site=claws_dispatch_subworker | corrId=${_dswCorrId} | termId=${_dswTermIdStr}`);
+          try {
+            const r2 = await clawsRpc(sock, { cmd: 'monitors.is-corr-armed', correlation_id: _dswCorrId });
+            _l2f(`L2-DEBUG: recheck-rpc-result | site=claws_dispatch_subworker | ok=${r2.ok} | armed=${r2.armed} | claimed=${r2.claimed} | pending=${r2.pending} | peerId=${r2.peerId}`);
+            if (!r2.ok || r2.claimed) {
+              _l2f(`L2-DEBUG: recheck-skip | site=claws_dispatch_subworker | reason=${!r2.ok ? 'rpc-error' : 'claimed'}`);
+              return;
+            }
+            const reason = r2.pending ? 'pending-timeout' : 'pending-vacated';
+            log(`L2-warn: claws_dispatch_subworker term=${_dswTermIdStr} corr=${_dswCorrId} — ${reason} at 90s. Publishing unarmed.`);
+            _l2f(`L2-DEBUG: about-to-publish | site=claws_dispatch_subworker | corrId=${_dswCorrId} | reason=${reason}`);
+            try {
+              await _pconnEnsureRegistered(sock);
+              _l2f(`L2-DEBUG: pconn-registered | site=claws_dispatch_subworker`);
+              await _pconnWriteOrThrow({
+                cmd: 'publish', protocol: 'claws/2',
+                topic: 'system.monitor.unarmed',
+                payload: { terminal_id: _dswTermIdStr, correlation_id: _dswCorrId, layer: 2,
+                  detected_at: new Date().toISOString(), grace_ms: 90000, reason },
+              });
+              _l2f(`L2-DEBUG: publish-succeeded | site=claws_dispatch_subworker | corrId=${_dswCorrId}`);
+            } catch (_pe) {
+              _l2f(`L2-DEBUG: publish-failed | site=claws_dispatch_subworker | err=${_pe && _pe.message || _pe}`);
+            }
+          } catch (_e) { _l2f(`L2-DEBUG: recheck-error | site=claws_dispatch_subworker | err=${_e && _e.message || _e}`); }
+        }, 60000);
+      } catch (_e) { _l2f(`L2-DEBUG: outer-error | site=claws_dispatch_subworker | err=${_e && _e.message || _e}`); }
+    }, 30000);
+
+    // BUG-08: fire-and-forget — return after create so parallel dispatch_subworker calls don't serialize.
+    const _dswSock = sock;
+    // GAP-D1: strip bracketed-paste escapes from mission to prevent keystroke injection.
+    // Phase 4a: one-line completion hint — claws_done() handles the rest.
+    const _dswPhase4Header = `When you're finished, call \`claws_done()\`. That's it.\n\n---\n`;
+    const _dswMission = (_dswPhase4Header + (args.mission || '')).replace(/\x1b\[200~/g, '').replace(/\x1b\[201~/g, '');
+    const _dswWid = args.waveId;
+    const _dswRole = args.role;
+    // BUG-09: capture watcher options for auto-close watcher registered after mission send.
+    const _dswCompleteMarker = typeof args.complete_marker === 'string' ? args.complete_marker : '__CLAWS_DONE__';
+    const _dswErrorMarkers = Array.isArray(args.error_markers) ? args.error_markers : ['MISSION_FAILED'];
+    const _dswTimeoutMs = typeof args.timeout_ms === 'number' ? args.timeout_ms : 5 * 60 * 1000;
+    const _dswPollMs = typeof args.poll_interval_ms === 'number' ? args.poll_interval_ms : 1500;
+    const _dswCloseOnComplete = args.close_on_complete !== false;
+    const _dswCwd = typeof args.cwd === 'string' && args.cwd.length > 0 ? args.cwd : null;
+    setImmediate(async () => {
+      try {
+        await sleep(400);
+        await clawsRpc(_dswSock, {
+          cmd: 'send', id: termId,
+          text: `${getClaudeBin(_dswCwd)} --model claude-sonnet-4-6 --dangerously-skip-permissions`, newline: true,
+        });
+        // AD-1: gate mission paste on confirmed pty-claim.
+        const _gate = await _gatePasteOnClaudeClaim(_dswSock, termId, _dswCorrId, { timeoutMs: args.boot_wait_ms });
+        if (!_gate.booted) {
+          if (_dswCloseOnComplete) { try { await clawsRpc(_dswSock, { cmd: 'close', id: termId }); } catch {} }
+          return; // abort — L2 grace will publish unarmed naturally
+        }
+        // GAP-D1: _dswMission already sanitized above — send as-is.
+        // W8k-2: delegate to shared helper — pre-snapshot (BUG-C), bracketed-paste (newline:false),
+        // 300ms gap, AE-7 event-driven submit confirmation with escalating retry.
+        // Restores parity with claws_worker / fleet; newline:true failed on Windows ConPTY.
+        const _dswMarkerScanFrom = await _sendAndSubmitMission(_dswSock, termId, _dswCorrId, _dswMission, true);
+
+        // BUG-09: register auto-close watcher via shared _setupDetachWatcher helper.
+        const _dswStartedAt = Date.now();
+        const _dswOpt = { complete_marker: _dswCompleteMarker, error_markers: _dswErrorMarkers, timeout_ms: _dswTimeoutMs, poll_interval_ms: _dswPollMs, close_on_complete: _dswCloseOnComplete };
+        const _dswHbState = new WorkerHeartbeatStateMachine({ terminalId: termId, correlationId: _dswCorrId });
+        _setupDetachWatcher({
+          sock: _dswSock, termId, corrId: _dswCorrId, opt: _dswOpt,
+          markerScanFrom: _dswMarkerScanFrom, hbState: _dswHbState,
+          startedAt: _dswStartedAt, extraPayload: { waveId: _dswWid, role: _dswRole },
+          closeOnTimeout: _dswCloseOnComplete,
+        });
+      } catch (e) { log('claws_dispatch_subworker background boot error: ' + (e && e.message || e)); }
+    });
+
+    const dswEventsLogPath = _eventsLogPath(sock);
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          terminal_id: termId, waveId: _dswWid, role: _dswRole, name: workerName,
+          correlation_id: _dswCorrId,
+          monitor_arm_required: true,
+          monitor_arm_command: _dswMonitorCmd,
+          events_log_path: dswEventsLogPath,
+        }, null, 2),
+      }],
+    };
+  }
+
+  if (name === 'claws_schema_list') {
+    const resp = await clawsRpc(sock, { cmd: 'schema.list', protocol: 'claws/2' });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ schemas: resp.schemas }, null, 2) }] };
+  }
+
+  if (name === 'claws_schema_get') {
+    const resp = await clawsRpc(sock, { cmd: 'schema.get', protocol: 'claws/2', name: args.name });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ name: resp.name, schema: resp.schema }, null, 2) }] };
+  }
+
+  if (name === 'claws_rpc_call') {
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'rpc.call',
+      protocol: 'claws/2',
+      targetPeerId: args.targetPeerId,
+      method: args.method,
+      ...(args.params ? { params: args.params } : {}),
+      ...(args.timeoutMs ? { timeoutMs: args.timeoutMs } : {}),
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ requestId: resp.requestId, result: resp.result }, null, 2) }] };
+  }
+
+  if (name === 'claws_task_assign') {
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'task.assign', protocol: 'claws/2',
+      title: args.title,
+      assignee: args.assignee,
+      prompt: args.prompt,
+      ...(args.timeoutMs != null ? { timeoutMs: args.timeoutMs } : {}),
+      ...(args.deliver ? { deliver: args.deliver } : {}),
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'task.assign failed'}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ taskId: resp.taskId, assignedAt: resp.assignedAt }, null, 2) }] };
+  }
+
+  if (name === 'claws_task_update') {
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'task.update', protocol: 'claws/2',
+      taskId: args.taskId,
+      status: args.status,
+      ...(args.progressPct != null ? { progressPct: args.progressPct } : {}),
+      ...(args.note != null ? { note: args.note } : {}),
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'task.update failed'}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ ok: true }, null, 2) }] };
+  }
+
+  if (name === 'claws_task_complete') {
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'task.complete', protocol: 'claws/2',
+      taskId: args.taskId,
+      status: args.status,
+      ...(args.result != null ? { result: args.result } : {}),
+      ...(args.artifacts != null ? { artifacts: args.artifacts } : {}),
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'task.complete failed'}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ ok: true }, null, 2) }] };
+  }
+
+  if (name === 'claws_task_cancel') {
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'task.cancel', protocol: 'claws/2',
+      taskId: args.taskId,
+      ...(args.reason != null ? { reason: args.reason } : {}),
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'task.cancel failed'}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ ok: true }, null, 2) }] };
+  }
+
+  if (name === 'claws_task_list') {
+    const resp = await clawsRpcStateful(sock, {
+      cmd: 'task.list', protocol: 'claws/2',
+      ...(args.assignee ? { assignee: args.assignee } : {}),
+      ...(args.status ? { status: args.status } : {}),
+      ...(args.since != null ? { since: args.since } : {}),
+    });
+    if (!resp.ok) return toolError(`ERROR: ${resp.error || 'task.list failed'}`);
+    return { content: [{ type: 'text', text: JSON.stringify({ tasks: resp.tasks || [] }, null, 2) }] };
+  }
+
+  if (name === 'claws_set_bin') {
+    try {
+      const clawsDir = path.dirname(path.resolve(sock));
+      const file = path.join(clawsDir, 'claude-bin');
+      if (args && typeof args.name === 'string' && args.name.trim()) {
+        fs.mkdirSync(clawsDir, { recursive: true });
+        fs.writeFileSync(file, args.name.trim() + '\n', 'utf8');
+        return { content: [{ type: 'text', text: `Worker binary set to: ${args.name.trim()}\n  → wrote ${file}\n  → next claws_worker / claws_fleet spawn will use this binary.` }] };
+      }
+      try { fs.unlinkSync(file); } catch (_e) { /* file didn't exist */ }
+      return { content: [{ type: 'text', text: 'Worker binary cleared. Spawns will use the default ("claude") or CLAWS_CLAUDE_BIN env var if set.' }] };
+    } catch (e) {
+      return toolError(`claws_set_bin failed: ${e.message}`);
+    }
+  }
+
+  if (name === 'claws_get_bin') {
+    try {
+      const projectRoot = path.resolve(path.dirname(path.resolve(sock)), '..');
+      const bin = getClaudeBin(projectRoot);
+      const clawsFile = path.join(projectRoot, '.claws', 'claude-bin');
+      let source;
+      if (fs.existsSync(clawsFile) && fs.readFileSync(clawsFile, 'utf8').trim().split(/\r?\n/)[0]) {
+        source = `file:${clawsFile}`;
+      } else if (process.env.CLAWS_CLAUDE_BIN) {
+        source = 'env:CLAWS_CLAUDE_BIN';
+      } else {
+        source = 'default';
+      }
+      return { content: [{ type: 'text', text: `Worker binary: ${bin}\n  source: ${source}` }] };
+    } catch (e) {
+      return toolError(`claws_get_bin failed: ${e.message}`);
+    }
+  }
+
+  return toolError(`unknown tool: ${name}`);
+}
+
+// ─── MCP server main loop ──────────────────────────────────────────────────
+
+async function main() {
+  process.stdin.resume();
+  log('MCP server started, socket: ' + getSocket());
+
+  // AE-1: Eager hello when running as a worker's child mcp_server.js.
+  // CLAWS_TERMINAL_CORR_ID is set by the extension when creating the wrapped pty
+  // (claws-pty.ts:256). Its presence in our env means we are inside a worker
+  // terminal, not the user's root orchestrator. Eagerly hello so the bus
+  // confirms we are alive and so system.peer.connected{correlation_id} fires
+  // for the parent orchestrator's _gatePasteOnClaudeClaim to release on.
+  // Without this, hello is lazy (first tool call only) — an idle Claude TUI
+  // at the empty prompt never hellos and event-driven boot detection times out.
+  //
+  // AE-1.1: do NOT pre-check fs.existsSync(socket) — on win32 the bus is a
+  // named pipe (\\.\pipe\...) which has no filesystem presence and existsSync
+  // always returns false, silently skipping the eager hello on Windows.
+  // _pconnEnsureRegistered already handles connect failures gracefully via the
+  // circuit breaker; a missing/down bus produces one logged warning, no crash.
+  if (process.env.CLAWS_TERMINAL_CORR_ID) {
+    const _aeSock = getSocket();
+    if (_aeSock) {
+      setImmediate(() => {
+        _pconnEnsureRegistered(_aeSock).catch((e) => {
+          log(`AE-1: eager hello failed (will retry lazily): ${e && e.message || e}`);
+        });
+      });
+    }
+  }
+
+  while (true) {
+    const msg = await readMessage();
+    if (!msg) break;
+
+    const { method, id, params = {} } = msg;
+
+    if (method === 'initialize') {
+      log('client connected: ' + ((params && params.clientInfo && params.clientInfo.name) || 'unknown'));
+      respond(id, {
+        protocolVersion: '2024-11-05',
+        // Version must match extension/package.json — bump both together on release.
+        serverInfo: { name: 'claws', version: '0.7.14' },
+        capabilities: { tools: {} },
+      });
+    } else if (method === 'notifications/initialized') {
+      // no response needed
+    } else if (method === 'tools/list') {
+      respond(id, { tools: TOOLS });
+    } else if (method === 'tools/call') {
+      // CONCURRENT TOOL DISPATCH (v0.7.10).
+      // Do NOT await handleTool here — that would block the main loop and
+      // serialize every tool call (the v0.7.4-through-v0.7.9 behavior).
+      // When a long-running tool like claws_worker is in flight, fan-out
+      // patterns (3 parallel workers, wave armies with 4 sub-workers, etc.)
+      // would queue up behind it for up to timeout_ms each, defeating the
+      // entire point of concurrent orchestration.
+      //
+      // Instead: dispatch the handler as a fire-and-forget Promise and let
+      // the main loop immediately read the next message from stdin. Multiple
+      // tool calls now interleave on the JS event loop, each progressing
+      // whenever it await's I/O. State sharing is safe because:
+      //   - _pconn requests use unique rids (nextRid++ is atomic in JS event loop)
+      //   - _eventBuffer push is single-statement, never interleaved mid-write
+      //   - _circuitBreaker fields are simple read/write, racy but benign
+      //
+      // respond() is called from the .then/.catch — JSON-RPC responses can
+      // arrive out-of-order relative to the requests, which is allowed by
+      // the spec (each response carries the matching id).
+      handleTool(params.name || '', params.arguments || {})
+        .then((result) => respond(id, result))
+        .catch((e) => respond(id, {
+          content: [{ type: 'text', text: `ERROR: ${e.message || e}` }],
+          isError: true,
+        }));
+    } else if (method === 'ping') {
+      respond(id, {});
+    } else if (id != null) {
+      respondError(id, -32601, `unknown method: ${method}`);
+    }
+  }
+}
+
+main().catch(console.error);
+
+// Export pure helpers for unit testing (Task #58 + HB-L3).
+if (typeof module !== 'undefined') {
+  module.exports = { detectCompletion, findStandaloneMarker, WorkerHeartbeatStateMachine };
+}