mixdog 0.7.1

package/server-main.mjs

@@ -0,0 +1,3055 @@
+#!/usr/bin/env bun
+/**
+ * mixdog — MCP server entry point.
+ *
+ * Four modules (channels, memory, search, agent) exposed over a single
+ * MCP server. Tool routing is driven by the static manifest in tools.json,
+ * which records the owning module for every tool.
+ *
+ * Module lifecycle:
+ *   • memory — eager init right after the MCP handshake completes,
+ *     because channels depends on it for episode delivery.
+ *   • channels — eager init (runs background workers: Discord gateway,
+ *     scheduler, webhook, event pipeline). Started after memory is ready.
+ *   • search / agent — eager init after MCP handshake.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
+import { fork, spawnSync } from 'child_process'
+import { randomUUID, createHash } from 'crypto'
+
+// Per-process instance id. One server-main = one stdio MCP client = one
+// logical Claude Code session. memory.entries / trace.entries carry this id
+// in the existing session_id column so multi-terminal usage keeps recall and
+// cycle scope per-instance even though PG/memory worker are singletons.
+// Workers inherit the same id via env (MIXDOG_SESSION_ID).
+const SESSION_ID = randomUUID()
+process.env.MIXDOG_OWNER_SESSION_ID = SESSION_ID
+import { readFileSync, writeFileSync, mkdirSync, watch as fsWatch, existsSync, unlinkSync, statSync, renameSync, createWriteStream, appendFileSync } from 'fs'
+import { appendFile as appendFileAsync, writeFile as writeFileAsync } from 'fs/promises'
+import { join, resolve as pathResolve } from 'path'
+import { homedir, tmpdir } from 'os'
+import { pathToFileURL } from 'url'
+import { createRequire } from 'module'
+import { resolvePluginData } from './src/shared/plugin-paths.mjs'
+import { ensureDataSeeds } from './src/shared/seed.mjs'
+import { readSection } from './src/shared/config.mjs'
+import { withFileLockSync, writeJsonAtomicSync } from './src/shared/atomic-file.mjs'
+import { loadConfig as loadSearchConfig } from './src/search/lib/config.mjs'
+import { PROVIDER_CAPS } from './src/search/lib/backends/index.mjs'
+import { captureOriginalUserCwd, pwd, rawUserCwd, readLastSessionCwd } from './src/shared/user-cwd.mjs'
+import { resolveProjectId as _resolveProjectIdForBoot } from './src/memory/lib/project-id-resolver.mjs'
+import { configureCacheStatsSnapshot } from './src/agent/orchestrator/session/read-dedup.mjs'
+import { smartReadTruncate } from './src/agent/orchestrator/tools/builtin/read-formatting.mjs'
+import { formatToolStartProgress } from './src/agent/orchestrator/tools/progress-message.mjs'
+import { maybeRequestDefenderExclusion } from './src/setup/defender-exclusion.mjs'
+import { isHookPipeServerStarted, startHookPipeServer, stopHookPipeServer } from './src/channels/lib/hook-pipe-server.mjs'
+import { Session, SessionRegistry } from './src/daemon/session.mjs'
+import { listen as daemonListen } from './src/daemon/transport.mjs'
+import { FramedServerTransport } from './src/daemon/mcp-transport.mjs'
+
+// silent_to_agent is an INTERNAL routing flag (consumed by the daemon router /
+// agentNotify before any CC delivery). It must never cross to Claude Code,
+// whose channel-notification schema is meta: Record<string,string> — a boolean
+// would fail zod and silently drop the whole notification. Strip it from meta
+// right before a notification is delivered to CC. (Routing has already read it.)
+function channelNotifyParamsForCc(notification) {
+  const m = notification?.params?.meta
+  if (!m || typeof m !== 'object' || !('silent_to_agent' in m)) return notification
+  const { silent_to_agent, ...rest } = m
+  return { ...notification, params: { ...notification.params, meta: rest } }
+}
+
+// ── Environment ──────────────────────────────────────────────────────
+// Claude Code normally injects CLAUDE_PLUGIN_ROOT / CLAUDE_PLUGIN_DATA
+// for relative-path plugin sources. For URL-based sources it may skip
+// injection, so fall back to process.cwd() and the standard data path.
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || process.cwd()
+const PLUGIN_DATA = resolvePluginData()
+mkdirSync(PLUGIN_DATA, { recursive: true })
+captureOriginalUserCwd() // seed single-source-of-truth cwd before any tool dispatch
+// Session-cwd auto-init: when user-cwd.txt resolves to a directory that
+// belongs to a known project (resolveProjectId returns non-null) OR has
+// an ancestor `.git`, seed MIXDOG_SESSION_CWD so the cwd tool's `get`
+// reports a usable session cwd from the first call. Skipped when the
+// env var is already set (an outer supervisor / prior call already
+// chose the session cwd).
+;(() => {
+  if (typeof process.env.MIXDOG_SESSION_CWD === 'string' && process.env.MIXDOG_SESSION_CWD.length > 0) return
+  // Per-terminal restore: a dev-sync child restart drops the in-memory
+  // MIXDOG_SESSION_CWD the user chose via `cwd set` (the supervisor respawns
+  // this child with its OWN env, so the child's runtime mutation is gone).
+  // Re-seed from the supervisor-PID-keyed sentinel BEFORE the user-cwd.txt
+  // session-start default below. The key is per terminal, so this never
+  // picks up another terminal's cwd; readLastSessionCwd validates the dir
+  // still exists.
+  try {
+    const restored = readLastSessionCwd()
+    if (restored) {
+      process.env.MIXDOG_SESSION_CWD = restored
+      process.stderr.write(`[cwd-autoinit] restored MIXDOG_SESSION_CWD=${restored} (per-terminal)\n`)
+      return
+    }
+  } catch {}
+  let seed
+  try { seed = rawUserCwd() } catch { return }
+  if (!seed || typeof seed !== 'string') return
+  let qualifies = false
+  try { qualifies = _resolveProjectIdForBoot(seed) != null } catch {}
+  if (!qualifies) {
+    try {
+      let dir = seed
+      while (dir && dir !== pathResolve(dir, '..')) {
+        if (existsSync(join(dir, '.git'))) { qualifies = true; break }
+        const parent = pathResolve(dir, '..')
+        if (parent === dir) break
+        dir = parent
+      }
+    } catch {}
+  }
+  if (qualifies) {
+    process.env.MIXDOG_SESSION_CWD = seed
+    process.stderr.write(`[cwd-autoinit] seeded MIXDOG_SESSION_CWD=${seed}\n`)
+  }
+})()
+process.stderr.write(`[boot-time] tag=server-entry tMs=${Date.now()}\n`)
+try { ensureDataSeeds(PLUGIN_DATA) } catch {}
+configureCacheStatsSnapshot(PLUGIN_DATA)
+
+// Hook/statusline IPC is a singleton named pipe. In multi-terminal mode only
+// the active terminal owner may hold it; otherwise a standby process can steal
+// statusline / hook traffic from the real active-instance owner.
+let hookPipeStarted = false
+let hookPipeOwnershipTimer = null
+const HOOK_PIPE_OWNER_CHECK_MS = 1000
+const HOOK_PIPE_LEAD_PID = (() => {
+  const pid = Number(process.env.MIXDOG_SUPERVISOR_PID)
+  return Number.isFinite(pid) && pid > 0 ? pid : process.pid
+})()
+const RUNTIME_ROOT = process.env.MIXDOG_RUNTIME_ROOT
+  ? pathResolve(process.env.MIXDOG_RUNTIME_ROOT)
+  : join(tmpdir(), 'mixdog')
+const ACTIVE_INSTANCE_FILE = join(RUNTIME_ROOT, 'active-instance.json')
+
+function parsePositivePid(value) {
+  const pid = Number(value)
+  return Number.isFinite(pid) && pid > 0 ? pid : null
+}
+
+function isMemoryOwnerPidAlive(pid) {
+  if (pid == null) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    if (e && e.code === 'ESRCH') return false
+    return true
+  }
+}
+
+function resolveOwnerHostPid() {
+  const fromEnv = parsePositivePid(process.env.MIXDOG_OWNER_HOST_PID)
+  if (fromEnv) return fromEnv
+
+  if (process.platform === 'win32') {
+    try {
+      const ps = [
+        '$procs = Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name;',
+        '$map = @{};',
+        'foreach ($p in $procs) { $map[[int]$p.ProcessId] = $p }',
+        `$cur = ${Number(process.pid)};`,
+        'for ($i = 0; $i -lt 16; $i++) {',
+        '  $p = $map[$cur]; if ($null -eq $p) { break }',
+        "  if ($p.Name -ieq 'claude.exe' -or $p.Name -ieq 'claude') { [Console]::Write($p.ProcessId); exit 0 }",
+        '  $cur = [int]$p.ParentProcessId',
+        '}',
+      ].join(' ')
+      const r = spawnSync('powershell.exe', ['-NoProfile', '-Command', ps], {
+        encoding: 'utf8',
+        timeout: 1500,
+        windowsHide: true,
+      })
+      const pid = parsePositivePid(String(r.stdout || '').trim())
+      if (pid) return pid
+    } catch {}
+  }
+
+  return parsePositivePid(process.ppid)
+}
+
+const OWNER_HOST_PID = resolveOwnerHostPid()
+if (OWNER_HOST_PID) process.env.MIXDOG_OWNER_HOST_PID = String(OWNER_HOST_PID)
+
+function activeOwnerLeadPid() {
+  try {
+    const active = JSON.parse(readFileSync(ACTIVE_INSTANCE_FILE, 'utf8'))
+    return parsePositivePid(active?.ownerLeadPid)
+  } catch {
+    return null
+  }
+}
+
+function shouldOwnHookPipe(ownerPid = activeOwnerLeadPid()) {
+  if (!ownerPid) return process.env.MIXDOG_MULTI_INSTANCE !== '1'
+  return ownerPid === HOOK_PIPE_LEAD_PID
+}
+
+function reconcileHookPipeOwnership(reason = 'timer') {
+  const ownerPid = activeOwnerLeadPid()
+  const shouldOwn = shouldOwnHookPipe(ownerPid)
+  const isStarted = isHookPipeServerStarted()
+  if (shouldOwn && !isStarted) {
+    try {
+      const server = startHookPipeServer()
+      hookPipeStarted = Boolean(server)
+      process.stderr.write(`[hook-pipe] owner lead=${HOOK_PIPE_LEAD_PID} start requested reason=${reason}\n`)
+    } catch (err) {
+      hookPipeStarted = false
+      try { process.stderr.write(`[hook-pipe] parent start failed: ${err?.message || err}\n`) } catch {}
+    }
+  } else if (!shouldOwn && (hookPipeStarted || isStarted)) {
+    try { stopHookPipeServer() } catch {}
+    hookPipeStarted = false
+    process.stderr.write(`[hook-pipe] standby lead=${HOOK_PIPE_LEAD_PID} released hook IPC reason=${reason}\n`)
+  } else if (!shouldOwn && reason === 'boot') {
+    process.stderr.write(`[hook-pipe] standby lead=${HOOK_PIPE_LEAD_PID} skip hook IPC owner=${ownerPid || 'none'}\n`)
+  }
+}
+reconcileHookPipeOwnership('boot')
+hookPipeOwnershipTimer = setInterval(() => reconcileHookPipeOwnership('owner-check'), HOOK_PIPE_OWNER_CHECK_MS)
+try { hookPipeOwnershipTimer.unref?.() } catch {}
+process.once('exit', () => {
+  if (hookPipeOwnershipTimer) {
+    try { clearInterval(hookPipeOwnershipTimer) } catch {}
+    hookPipeOwnershipTimer = null
+  }
+  if (hookPipeStarted) {
+    try { stopHookPipeServer() } catch {}
+  }
+})
+
+// Singleton lock + lock-release exit handlers are owned by the prelude
+// in server.mjs. server-main.mjs assumes the lock is already held.
+
+globalThis.__tribFastEntry = true
+
+// ── Module enable flags (B6 General toggles) ──────────────────────
+// Snapshotted once at boot — toggling in the setup UI requires a full
+// plugin restart to take effect. All four default to enabled:true when
+// the `modules` section is absent (backcompat for pre-B6 configs).
+const MODULE_NAMES = ['channels', 'memory', 'search', 'agent']
+const MODULE_ENABLED = (() => {
+  const out = { channels: true, memory: true, search: true, agent: true }
+  try {
+    const raw = JSON.parse(readFileSync(join(PLUGIN_DATA, 'mixdog-config.json'), 'utf8'))
+    const mods = raw && typeof raw === 'object' ? raw.modules : null
+    if (mods && typeof mods === 'object') {
+      for (const name of MODULE_NAMES) {
+        const entry = mods[name]
+        if (entry && typeof entry === 'object' && entry.enabled === false) out[name] = false
+      }
+    }
+  } catch { /* missing / malformed — keep all enabled */ }
+  return out
+})()
+const isModuleEnabled = (name) => MODULE_ENABLED[name] !== false
+
+// ── Static manifest ─────────────────────────────────────────────────
+// Dev-only self-heal: if a TOOL_DEFS source was edited after the last
+// tools.json build, regenerate before loading so boot never serves a stale
+// manifest — even when dev-sync wasn't run. The build script lives under
+// dev/, absent from published packages (which ship a fresh prepublish
+// manifest with no drift), so existsSync gates installed users out.
+const _toolsJsonPath = join(PLUGIN_ROOT, 'tools.json')
+let _selfHealError = null
+try {
+  const _buildToolsScript = join(PLUGIN_ROOT, 'dev', 'scripts', 'build-tools-manifest.mjs')
+  if (existsSync(_buildToolsScript) && existsSync(_toolsJsonPath)) {
+    const _manifestMtime = statSync(_toolsJsonPath).mtimeMs
+    let _srcMtime = 0
+    for (const rel of [
+      'dev/scripts/build-tools-manifest.mjs',
+      'src/channels/index.mjs', 'src/channels/tool-defs.mjs',
+      'src/memory/index.mjs', 'src/memory/tool-defs.mjs',
+      'src/search/index.mjs', 'src/search/tool-defs.mjs', 'src/search/lib/providers.mjs',
+      'src/agent/index.mjs', 'src/agent/tool-defs.mjs',
+      'src/agent/orchestrator/tools/builtin.mjs', 'src/agent/orchestrator/tools/builtin/builtin-tools.mjs',
+      'src/agent/orchestrator/tools/code-graph-tool-defs.mjs',
+      'src/agent/orchestrator/tools/patch-tool-defs.mjs',
+      'src/agent/orchestrator/tools/host-input.mjs',
+      'src/agent/orchestrator/tools/cwd-tool.mjs',
+    ]) {
+      try { _srcMtime = Math.max(_srcMtime, statSync(join(PLUGIN_ROOT, rel)).mtimeMs) } catch {}
+    }
+    if (_srcMtime > _manifestMtime) {
+      const _healEnv = { ...process.env }
+      delete _healEnv.CLAUDE_PLUGIN_DATA // route the rebuild's init writes to a throwaway temp dir
+      const _r = spawnSync('bun', [_buildToolsScript], { cwd: PLUGIN_ROOT, encoding: 'utf8', env: _healEnv, windowsHide: true })
+      if (_r.status !== 0) {
+        _selfHealError = new Error(`[mixdog] tools.json self-heal failed (status=${_r.status}); refusing to load possibly-stale/tampered manifest`)
+      }
+    }
+  }
+} catch { /* missing source/manifest — fall through to load the existing file */ }
+if (_selfHealError) throw _selfHealError
+let RAW_TOOL_DEFS
+try {
+  RAW_TOOL_DEFS = JSON.parse(readFileSync(_toolsJsonPath, 'utf8'))
+} catch (e) {
+  throw new Error('[mixdog] tools.json parse failure: ' + (e && e.message))
+}
+// Boot-time schema validation + module allowlist. A malformed or
+// unknown-module entry aborts startup rather than silently shipping a
+// broken/tampered manifest into TOOL_MODULE / TOOL_BY_NAME below.
+const VALID_TOOL_MODULES = new Set([
+  ...MODULE_NAMES, 'builtin', 'code_graph', 'patch', 'host_input', 'cwd',
+])
+if (!Array.isArray(RAW_TOOL_DEFS)) {
+  throw new Error('[mixdog] tools.json: top-level value is not an array')
+}
+for (const t of RAW_TOOL_DEFS) {
+  if (!t || typeof t !== 'object' || Array.isArray(t)) {
+    throw new Error(`[mixdog] tools.json: malformed entry (not an object): ${JSON.stringify(t)}`)
+  }
+  if (typeof t.name !== 'string' || !t.name) {
+    throw new Error(`[mixdog] tools.json: entry missing string "name": ${JSON.stringify(t)}`)
+  }
+  if (typeof t.description !== 'string') {
+    throw new Error(`[mixdog] tools.json: entry "${t.name}" missing string "description"`)
+  }
+  if (!t.inputSchema || typeof t.inputSchema !== 'object' || Array.isArray(t.inputSchema)) {
+    throw new Error(`[mixdog] tools.json: entry "${t.name}" missing object "inputSchema"`)
+  }
+  if (typeof t.module !== 'string' || !t.module) {
+    throw new Error(`[mixdog] tools.json: entry "${t.name}" missing string "module"`)
+  }
+  if (!VALID_TOOL_MODULES.has(t.module)) {
+    throw new Error(`[mixdog] tools.json: entry "${t.name}" has unknown module "${t.module}" (allowed: ${[...VALID_TOOL_MODULES].join(', ')})`)
+  }
+}
+// Hide tools belonging to disabled modules from BOTH the ListTools
+// response AND the bridge's internal-tools registry. `builtin` / `lsp` /
+// `bash_session` / `patch` are not module-gated — they ride along with
+// the plugin regardless.
+// Gate host_input on MIXDOG_ALLOW_HOST_INPUT env-var or
+// modules.host_input.enabled config flag. Default: off.
+const _hostInputAllowed = (() => {
+  if (process.env.MIXDOG_ALLOW_HOST_INPUT === '1') return true
+  try {
+    const raw = JSON.parse(readFileSync(join(PLUGIN_DATA, 'mixdog-config.json'), 'utf8'))
+    return !!(raw?.modules?.host_input?.enabled)
+  } catch { return false }
+})()
+const TOOL_DEFS = RAW_TOOL_DEFS.filter(t => {
+  if (t.module === 'host_input') return _hostInputAllowed
+  // Channels worker depends on memory worker for inbound routing / recall;
+  // the spawn gate below (channels gated on memoryOn) skips spawning when
+  // memory is disabled. Mirror that gate here so we don't advertise channel
+  // tools whose backing worker will never come up — calls would otherwise
+  // wait WORKER_NO_ENTRY_GRACE_MS and then reject.
+  if (t.module === 'channels' && !isModuleEnabled('memory')) return false
+  if (MODULE_NAMES.includes(t.module)) return isModuleEnabled(t.module)
+  return true
+})
+const TOOL_MODULE = Object.fromEntries(TOOL_DEFS.map(t => [t.name, t.module]))
+const TOOL_BY_NAME = Object.fromEntries(TOOL_DEFS.map(t => [t.name, t]))
+const PLUGIN_VERSION = JSON.parse(
+  readFileSync(join(PLUGIN_ROOT, '.claude-plugin', 'plugin.json'), 'utf8'),
+).version
+
+// ── Logging ──────────────────────────────────────────────────────────
+const LOG_FILE = join(PLUGIN_DATA, 'mcp-debug.log')
+const _logOwnerLeadPidRaw = Number(process.env.MIXDOG_SUPERVISOR_PID)
+const LOG_OWNER_LEAD_PID = Number.isFinite(_logOwnerLeadPidRaw) && _logOwnerLeadPidRaw > 0
+  ? _logOwnerLeadPidRaw
+  : process.pid
+const LOG_CONTEXT = `lead=${LOG_OWNER_LEAD_PID} server=${process.pid} session=${SESSION_ID}`
+const LOG_FILE_SCOPED = join(PLUGIN_DATA, `mcp-debug.${LOG_OWNER_LEAD_PID}.${process.pid}.log`)
+// One-shot rotation: if mcp-debug.log >10 MB, rename to .1 (overwrite) and
+// open a fresh file. Runs once at module init; never repeated per log() call.
+try {
+  if (statSync(LOG_FILE).size > 10 * 1024 * 1024) renameSync(LOG_FILE, LOG_FILE + '.1')
+} catch {}
+try {
+  if (statSync(LOG_FILE_SCOPED).size > 10 * 1024 * 1024) renameSync(LOG_FILE_SCOPED, LOG_FILE_SCOPED + '.1')
+} catch {}
+
+// ── Application-level tool-error sink ────────────────────────────────────────
+// Tool functions return `Error [code N]: ...` as plain strings instead of
+// throwing — the dispatch logger therefore records them as `[dispatch] ok`
+// and the disk has no trace of read/edit invariant failures (code 6/7/8/
+// 9/10). Append one structured line per such result to tool-events.log
+// next to mcp-debug.log. Best-effort: logger never breaks the tool.
+const TOOL_EVENT_LOG = join(PLUGIN_DATA, 'tool-events.log');
+// Lazy rotation for the application-error sink. mcp-debug.log uses the
+// same 10 MiB threshold but tool-events.log is far less chatty (one line
+// per app-level edit failure + one per session close), so a 1 MiB cap is
+// roughly a month of activity. Rotation is one-step rename so callers
+// never see a half-empty file mid-write.
+const TOOL_EVENT_LOG_MAX_BYTES = 1024 * 1024;
+function _rotateToolEventLogIfLarge() {
+  try {
+    const st = statSync(TOOL_EVENT_LOG);
+    if (st.size > TOOL_EVENT_LOG_MAX_BYTES) {
+      renameSync(TOOL_EVENT_LOG, TOOL_EVENT_LOG + '.1');
+    }
+  } catch { /* missing file or stat race — append will recreate */ }
+}
+
+function _recordToolApplicationError(name, result) {
+  try {
+    let text = null;
+    if (typeof result === 'string') {
+      text = result;
+    } else if (result && typeof result === 'object' && Array.isArray(result.content)) {
+      const t = result.content.find((c) => c && c.type === 'text' && typeof c.text === 'string');
+      if (t) text = t.text;
+    }
+    if (!text) return;
+    const m = text.match(/^Error \[code (\d+)\]:\s*([^\n]+)/);
+    if (!m) return;
+    _rotateToolEventLogIfLarge();
+    const ts = new Date().toISOString();
+    const msg = m[2].slice(0, 320);
+    appendFileSync(TOOL_EVENT_LOG, `[${ts}] [tool=${name}] [code=${m[1]}] ${msg}\n`);
+  } catch { /* logger never breaks the tool */ }
+}
+
+// R14: sanitize a single log field — strip ANSI escapes and escape control
+// chars (CR, lone C0/C1) so attacker-controlled bytes from worker stderr can't
+// forge new log lines, hide payloads with \r overwrites, or smuggle ANSI
+// sequences into operator terminals tailing the log. Keep \t and \n intact:
+// \t is benign in log payloads; \n is handled by the line-splitter upstream
+// (writeWorkerLogChunk) and the writer appends its own \n.
+function sanitizeLogField(text) {
+  if (text == null) return ''
+  let s = String(text)
+  // ANSI CSI: ESC [ params intermediates final.
+  s = s.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, (m) => '\\x1b' + m.slice(1))
+  // ANSI OSC: ESC ] ... BEL | ESC \.
+  s = s.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, (m) => '\\x1b' + m.slice(1))
+  // Other single-char ESC sequences (Fe set).
+  s = s.replace(/\x1b[@-_]/g, (m) => '\\x1b' + m.slice(1))
+  // Escape lone CR — main log-injection vector (overwrites prior line in terminals).
+  s = s.replace(/\r/g, '\\r')
+  // Remaining C0 (except TAB \x09 and LF \x0A) and C1 control chars → \xNN.
+  s = s.replace(/[\x00-\x08\x0B-\x1F\x7F-\x9F]/g, (c) => {
+    const code = c.charCodeAt(0)
+    return '\\x' + code.toString(16).padStart(2, '0')
+  })
+  return s
+}
+
+// ── Buffered mcp-debug.log writer ────────────────────────────────────────────
+// Flushes every 1 s OR when buffer reaches 64 KB — whichever fires first.
+// Drains synchronously on process exit so no log lines are lost.
+let _logBuf = ''
+let _logBytes = 0
+let _logFlushTimer = null
+let _logStream = null
+let _logScopedStream = null
+function _logGetStream() {
+  if (!_logStream) _logStream = createWriteStream(LOG_FILE, { flags: 'a' })
+  return _logStream
+}
+function _logGetScopedStream() {
+  if (!_logScopedStream) _logScopedStream = createWriteStream(LOG_FILE_SCOPED, { flags: 'a' })
+  return _logScopedStream
+}
+// Async WriteStream errors are not caught by callers of write(); attach
+// 'error' listeners on lazy-create so a disk EIO/EPERM during async flush
+// can't escape as uncaughtException. Best-effort: log and fall through to
+// appendFileAsync on next write.
+function _attachLogStreamErrorListener(stream, label) {
+  if (!stream) return
+  stream.on('error', (e) => {
+    try { process.stderr.write(`[server-main] ${label} stream error: ${e && (e.message || e)}\n`) } catch {}
+  })
+}
+function _logWriteAsync(line) {
+  try {
+    const s = _logGetStream()
+    if (!s.__mxErr) { _attachLogStreamErrorListener(s, 'mcp-debug'); s.__mxErr = true }
+    s.write(line)
+  } catch (e) {
+    appendFileAsync(LOG_FILE, line).catch(() => {})
+  }
+  try {
+    const s = _logGetScopedStream()
+    if (!s.__mxErr) { _attachLogStreamErrorListener(s, 'mcp-debug-scoped'); s.__mxErr = true }
+    s.write(line)
+  } catch (e) {
+    appendFileAsync(LOG_FILE_SCOPED, line).catch(() => {})
+  }
+}
+function _logLine(msg) {
+  return `[${new Date().toISOString()}] [${LOG_CONTEXT}] ${sanitizeLogField(msg)}\n`
+}
+function _logFlush() {
+  if (_logFlushTimer) { clearTimeout(_logFlushTimer); _logFlushTimer = null }
+  if (!_logBuf) return
+  _logWriteAsync(_logBuf)
+  _logBuf = ''
+  _logBytes = 0
+}
+// Synchronous exit flush — async WriteStream.write() can be dropped before drain.
+function _logFlushSync() {
+  if (_logFlushTimer) { clearTimeout(_logFlushTimer); _logFlushTimer = null }
+  if (!_logBuf) return
+  try { appendFileSync(LOG_FILE, _logBuf) } catch {}
+  try { appendFileSync(LOG_FILE_SCOPED, _logBuf) } catch {}
+  _logBuf = ''
+  _logBytes = 0
+}
+function _logScheduleFlush() {
+  if (_logFlushTimer) return
+  _logFlushTimer = setTimeout(_logFlush, 1000)
+  if (_logFlushTimer.unref) _logFlushTimer.unref()
+}
+function _logAppend(line) {
+  _logBuf += line
+  _logBytes += Buffer.byteLength(line)
+  if (_logBytes >= 65536) { _logFlush(); return }
+  _logScheduleFlush()
+}
+process.on('exit', _logFlushSync)
+// SIGTERM is wired to graceful shutdown() below (line ~1564). A separate
+// _logFlushSync() + process.exit(0) handler used to short-circuit shutdown
+// before workers/PG could drain — graceful path is preferred and ends with
+// _logFlushSync() inside shutdown(). The 'exit' listener above stays as a
+// catch-all for non-SIGTERM exits.
+
+const log = msg => { _logAppend(_logLine(msg)) }
+
+// ── Status HTTP server (forked child) ──────────────────────────────
+// Start this before memory/channels so the terminal statusline gets its
+// advert port during the first refresh tick. The rich bridge payload may be
+// sparse until workers finish booting, but the statusline no longer waits on
+// channels ownership before it has a data source.
+const STATUS_ADVERTISE_DIR = join(homedir(), '.claude', 'mixdog-status')
+const STATUS_ADVERTISE_PATH = join(STATUS_ADVERTISE_DIR, `${SESSION_ID}.json`)
+let statusServerChild = null
+let statusServerRestartTimer = null
+let statusServerStopping = false
+let recapStatusState = { state: 'idle', running: false, startedAt: null, lastCompletedAt: null, updatedAt: null, errorMessage: null }
+
+function scheduleStatusServerRestart() {
+  if (statusServerStopping) return
+  if (statusServerChild) return
+  if (statusServerRestartTimer) return
+  statusServerRestartTimer = setTimeout(() => {
+    statusServerRestartTimer = null
+    spawnStatusServer()
+  }, 1000)
+  statusServerRestartTimer.unref?.()
+}
+
+function normalizeRecapTimestamp(value) {
+  if (value === null || value === undefined || value === '') return null
+  const n = Number(value)
+  return Number.isFinite(n) ? n : null
+}
+
+function sanitizeRecapStatusState(recap = {}) {
+  const validStates = new Set(['idle', 'running', 'injected', 'empty', 'error']);
+  const rawState = typeof recap.state === 'string' && validStates.has(recap.state) ? recap.state : 'idle';
+  return {
+    state: rawState,
+    running: recap.running === true,
+    startedAt: normalizeRecapTimestamp(recap.startedAt),
+    lastCompletedAt: normalizeRecapTimestamp(recap.lastCompletedAt),
+    updatedAt: normalizeRecapTimestamp(recap.updatedAt),
+    errorMessage: typeof recap.errorMessage === 'string' ? recap.errorMessage.slice(0, 200) : null,
+  }
+}
+
+function forwardRecapStatusToStatusServer() {
+  if (!statusServerChild || !statusServerChild.connected) return
+  try {
+    statusServerChild.send({ type: 'recap_status', recap: recapStatusState })
+  } catch (e) {
+    log(`[status-server] recap status forward failed: ${e && (e.message || e) || e}`)
+  }
+}
+
+function spawnStatusServer() {
+  if (statusServerStopping) return
+  if (statusServerChild) return
+  if (statusServerRestartTimer) {
+    clearTimeout(statusServerRestartTimer)
+    statusServerRestartTimer = null
+  }
+  try {
+    try { unlinkSync(STATUS_ADVERTISE_PATH) } catch {}
+    statusServerChild = fork(
+      join(PLUGIN_ROOT, 'src/status/server.mjs'),
+      [],
+      {
+        env: {
+          ...process.env,
+          MIXDOG_STATUS_DATA_DIR: PLUGIN_DATA,
+          MIXDOG_OWNER_SESSION_ID: SESSION_ID,
+          MIXDOG_OWNER_LEAD_PID: process.env.MIXDOG_SUPERVISOR_PID || '',
+          MIXDOG_OWNER_HOST_PID: OWNER_HOST_PID ? String(OWNER_HOST_PID) : '',
+          MIXDOG_STATUS_ADVERTISE_PATH: STATUS_ADVERTISE_PATH,
+        },
+        stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+        windowsHide: true,
+      }
+    )
+    // Split chunks on \n so a child line containing embedded newlines cannot
+    // forge unprefixed log entries via sanitizeLogField's preservation of \n.
+    const _emitStatusLines = (prefix, chunk) => {
+      const text = String(chunk)
+      if (!text) return
+      const lines = text.split(/\r?\n/)
+      // Drop a trailing empty token from a chunk that ended with \n; emit
+      // any non-empty residue too (incomplete final line still surfaces).
+      if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+      for (const line of lines) {
+        if (!line) continue
+        log(prefix ? `${prefix}${line}` : line)
+      }
+    }
+    statusServerChild.stdout?.on('data', (d) => _emitStatusLines('', d))
+    statusServerChild.stderr?.on('data', (d) => _emitStatusLines('[status-server] stderr: ', d))
+    statusServerChild.on('error', (e) => {
+      log(`[status-server] child error: ${(e && (e.stack || e.message)) || e}`)
+      statusServerChild = null
+      try { unlinkSync(STATUS_ADVERTISE_PATH) } catch {}
+      scheduleStatusServerRestart()
+    })
+    statusServerChild.on('exit', (code, signal) => {
+      log(`[status-server] child exited code=${code} signal=${signal}`)
+      statusServerChild = null
+      try { unlinkSync(STATUS_ADVERTISE_PATH) } catch {}
+      scheduleStatusServerRestart()
+    })
+    forwardRecapStatusToStatusServer()
+  } catch (e) {
+    log(`[status-server] failed to fork: ${(e && (e.stack || e.message)) || e}`)
+    scheduleStatusServerRestart()
+  }
+}
+spawnStatusServer()
+
+// ── Crash handlers ──────────────────────────────────────────────────
+// Leave a trace on silent hangs. Previously only child workers
+// (channels/memory) installed these; the main MCP entry had none, so
+// unhandled errors died without writing a stack.
+//
+// Soft net policy (0.1.73): we deliberately do NOT call process.exit()
+// from uncaughtException / unhandledRejection. A misbehaving tool path
+// (e.g. explore concatenating results past V8 max-string-length on a
+// very broad cwd) used to take the whole MCP server down; now it logs
+// a stack and the process keeps serving. Real fatal conditions still
+// bubble out via SIGTERM/SIGINT or the explicit shutdown() path.
+const CRASH_FILE = join(PLUGIN_DATA, 'crash.log')
+const logCrash = (kind, err) => {
+  const stack = err?.stack || String(err)
+  try { appendFileSync(CRASH_FILE, `[${new Date().toISOString()}] ${kind}\n${stack}\n\n`) } catch {}
+  try { log(`${kind}: ${err?.message || err}`) } catch {}
+}
+
+// Fatal classification for uncaughtException. Soft-net (log-only) is the
+// 0.1.73 default for recoverable conditions like "Invalid string length"
+// from a runaway explore concat. But genuinely fatal conditions (port
+// already bound, OOM, node assert violations, internal-assertion
+// failures) leave the process in an unrecoverable state — staying alive
+// just delays the inevitable while serving broken responses. For those,
+// log the stack and exit(1) so the supervisor restarts cleanly.
+const FATAL_CODES = new Set([
+  'EADDRINUSE',
+  'EADDRNOTAVAIL',
+  'ENOMEM',
+  // EPIPE on stdout/stdin means the MCP transport is gone — no recovery possible.
+  'EPIPE',
+  'ERR_INTERNAL_ASSERTION',
+])
+const FATAL_NAME_PATTERNS = [
+  /AssertionError/i,   // node assert violations
+]
+function isFatalUncaught(err) {
+  if (!err) return false
+  if (err.code && FATAL_CODES.has(err.code)) return true
+  const name = err.name || (err.constructor && err.constructor.name) || ''
+  if (FATAL_NAME_PATTERNS.some(rx => rx.test(name))) return true
+  return false
+}
+process.on('uncaughtException', (err) => {
+  logCrash('uncaughtException', err)
+  if (isFatalUncaught(err)) {
+    try { log(`uncaughtException classified fatal (code=${err?.code} name=${err?.name}); exiting`) } catch {}
+    process.exit(1)
+  }
+})
+process.on('unhandledRejection', (reason) => {
+  logCrash('unhandledRejection', reason)
+  if (isFatalUncaught(reason)) {
+    try { log(`unhandledRejection classified fatal (code=${reason?.code} name=${reason?.name}); exiting`) } catch {}
+    process.exit(1)
+  }
+})
+
+// Explicit stdio transport-gone handlers: if stdout errors with EPIPE or stdin
+// closes, the MCP pipe is dead — exit(1) so the host respawns on next call.
+process.stdout.on('error', e => { if (e?.code === 'EPIPE') { logCrash('stdout-epipe', e); process.exit(1) } })
+// A normal MCP host closes stdin to end the session — route that through the
+// graceful shutdown path so workers (memory/channels) and PG get a clean stop
+// and the supervisor sees exit 0 instead of a spurious crash. The fatal
+// stdout EPIPE guard above still covers the abnormal "pipe broken mid-write"
+// condition where shutdown() can't drain reliably.
+process.stdin.on('close', () => {
+  log('stdin closed — MCP transport gone, initiating graceful shutdown')
+  if (typeof shutdown === 'function') {
+    Promise.resolve()
+      .then(() => shutdown('stdin closed'))
+      .catch(e => {
+        try { logCrash('stdin-close-shutdown', e) } catch {}
+        process.exit(1)
+      })
+  } else {
+    // shutdown() not yet defined — extremely early stdin close. Treat as abnormal.
+    logCrash('stdin-close-early', new Error('stdin closed before shutdown wired'))
+    process.exit(1)
+  }
+})
+process.on('exit', (code) => {
+  if (code !== 0) {
+    try { logCrash('exit', new Error(`process exit code=${code}`)) } catch {}
+  }
+})
+
+// ── Bridge orphan cleanup ───────────────────────────────────────────
+// Non-blocking: cleanup of stale state from a previous server PID.
+// Awaiting these used to gate the boot path (memory worker spawn, agent
+// eager init) behind disk + module-load work that has no semantic
+// dependency on the rest of boot. Fire-and-forget so the critical path
+// proceeds; failures stay logged.
+import(pathToFileURL(join(PLUGIN_ROOT, 'src/shared/llm/pid-cleanup.mjs')).href)
+  .then(({ cleanupOrphanedPids }) => {
+    const killed = cleanupOrphanedPids()
+    if (killed > 0) log(`[bridge-cleanup] cleaned ${killed} orphaned processes`)
+  })
+  .catch(e => log(`[bridge-cleanup] failed: ${e && (e.stack || e.message) || e}`))
+
+// ── Session cleanup: bridge sessions from previous MCP process ─────
+// Non-blocking, same rationale as bridge-cleanup above.
+import(pathToFileURL(join(PLUGIN_ROOT, 'src/agent/orchestrator/session/manager.mjs')).href)
+  .then(({ listSessions, closeSession, startIdleCleanup }) => {
+    const sessions = listSessions()
+    // Multi-instance guard: only reap bridge sessions whose owning MCP
+    // process is actually dead. A live peer (another Claude Code window)
+    // may still be running work on its session — closing it here is what
+    // produced the "bridge worker aborted mid-run" reports when a new
+    // window booted.
+    const isPidAlive = (pid) => {
+      if (!pid) return false
+      try { process.kill(pid, 0); return true } catch (e) { return !!(e && e.code === 'EPERM') }
+    }
+    let closed = 0
+    let preserved = 0
+    for (const s of sessions) {
+      if (s.owner !== 'bridge') continue
+      if (s.mcpPid === process.pid) continue
+      if (isPidAlive(s.mcpPid)) { preserved++; continue }
+      closeSession(s.id); closed++
+    }
+    log(`[session-cleanup] closed ${closed} dead-peer bridge sessions (pid≠${process.pid}), preserved ${preserved} live-peer, ${sessions.length - closed} remaining`)
+    startIdleCleanup()
+    log(`[session-cleanup] idle sweep timer started (interval=5m)`)
+  })
+  .catch(e => log(`[session-cleanup] failed: ${e && (e.stack || e.message) || e}`))
+
+// ── MCP server ──────────────────────────────────────────────────────
+function buildSearchProviderLine() {
+  try {
+    const cfg = loadSearchConfig()
+    const provider = cfg?.provider || 'anthropic-oauth'
+    const caps = PROVIDER_CAPS[provider]
+    if (!caps) {
+      return `Search backend: \`${provider}\` (unknown capabilities — verify with \`/mixdog:config\`).`
+    }
+    const types = (caps.searchTypes || []).join('/') || 'web'
+    const lines = [
+      `Search backend: \`${provider}\` (searchTypes=${types}).`,
+      'Two-step model: `search` returns SERP snippets + URLs; follow up with `web_fetch` for raw page bodies. `web_fetch` uses local readability+puppeteer extractors (provider-independent).',
+    ]
+    if (caps.localeMode === 'none') {
+      lines.push('→ Note: `locale` parameter is ignored by this backend.')
+    }
+    return lines.join('\n')
+  } catch (e) {
+    return `Search backend: capability probe failed (${e && (e.message || e)}).`
+  }
+}
+
+const SERVER_INSTRUCTIONS = [
+  `mixdog MCP server v${PLUGIN_VERSION}.`,
+  '',
+  'Agents: delegate via `bridge` with a `role` argument (roles defined in `user-workflow.json`; active set injected as the `# Roles` rule). `Agent` / `TeamCreate` are NOT used — `bridge` is the single entry point. `TaskCreate` / `TaskUpdate` / `TaskList` are allowed for Lead progress tracking only.',
+  '',
+  'Retrieval (HIGHEST PRIORITY): choose the source family first — `explore` for unknown/open-ended codebase work, `search` for web/URL/current external docs, `recall` for past memory. Then descend for bounded code lookup: `code_graph` (esp. `mode:search` for symbol-name keywords; `find_symbol` when exact) → `glob`/`list` → `grep` (free-text / non-symbol) → `read` with `file_path` plus `offset`/`limit` or line window. Mutations descend separately: `apply_patch` for large/multi-hunk/patch-shaped changes, batched `edit` for multiple exact substitutions, scalar `edit` for one small exact substitution. `bash` is shell-only (git, build, test, run); using it for file/code lookup is a violation.',
+  '',
+  buildSearchProviderLine(),
+  '',
+  'Channels: schedule / webhook / queue events arrive in the Lead session via the built-in channel mechanism, each with its own event-class marker.',
+].join('\n')
+
+const server = new Server(
+  { name: 'mixdog', version: PLUGIN_VERSION },
+  {
+    capabilities: {
+      tools: {},
+      experimental: { 'claude/channel': {}, 'claude/channel/permission': {} },
+    },
+    instructions: SERVER_INSTRUCTIONS,
+  },
+)
+
+// ── Channel permission request forwarding ──────────────────────────
+// Claude Code's interactiveHandler races the terminal dialog against every
+// MCP channel server that declares `experimental['claude/channel/permission']`.
+// When CC fires this notification, forward it into the channels worker so it
+// can post the Discord prompt. The worker reports the outcome back through
+// the generic {type:'notify'} IPC path above, which becomes a
+// `notifications/claude/channel/permission` notification on the MCP server.
+const ChannelPermissionRequestNotificationSchema = z.object({
+  method: z.literal('notifications/claude/channel/permission_request'),
+  params: z.object({
+    request_id: z.string(),
+    tool_name: z.string(),
+    description: z.string().optional(),
+    input_preview: z.string().optional(),
+  }).passthrough(),
+})
+
+// Daemon-mode notification router. In stdio mode the single module-global
+// `server` carries every worker→host notification. In daemon mode there are N
+// per-connection servers, so worker notifications must be ROUTED: permission
+// responses go to the connection that made the request (by request_id), channel
+// events (Discord inbound / schedule / webhook) go to the designated Lead
+// connection. Stays null in stdio mode.
+let daemonNotifyRouter = null
+function createDaemonNotifyRouter() {
+  const byReq = new Map() // request_id → perConn server (permission replies)
+  const bySession = new Map() // sessionId → perConn server (worker result/status routing)
+  const sessions = new Map() // perConn server → Session (owner resolution by leadPid)
+  // Resolve a connection by its terminal's client_host_pid (insertion-order scan).
+  function resolveConnByHostPid(hostPid) {
+    const pid = Number(hostPid) || 0
+    if (pid <= 0) return null
+    for (const [conn, session] of sessions) {
+      if (Number(session?.clientHostPid) === pid) return conn
+    }
+    return null
+  }
+  // Owner terminal = the connection whose supervisor pid matches the active
+  // instance's ownerLeadPid — the SAME SSOT hook-pipe ownership trusts
+  // (activeOwnerLeadPid). Exactly one deterministic owner: no first-connection
+  // election, no broadcast guessing.
+  function ownerConn() {
+    const ownerPid = activeOwnerLeadPid()
+    if (!ownerPid) return null
+    for (const [conn, session] of sessions) {
+      if (parsePositivePid(session?.leadPid) === ownerPid) return conn
+    }
+    return null
+  }
+  async function deliver(conn, notification, label) {
+    try {
+      await conn.notification(channelNotifyParamsForCc(notification))
+      const meta = notification?.params?.meta || null
+      if (meta?.type === 'dispatch_result' || meta?.caller_session_id != null || meta?.client_host_pid != null || String(label || '').includes('worker notify')) {
+        const sid = meta?.caller_session_id != null ? ` sid=${String(meta.caller_session_id)}` : ''
+        const host = Number(meta?.client_host_pid) || 0
+        log(`[daemon] ${label} delivered${sid}${host > 0 ? ` host=${host}` : ''}`)
+      }
+      return true
+    } catch (err) {
+      log(`[daemon] ${label} failed: ${err instanceof Error ? err.message : String(err)}`)
+      return false
+    }
+  }
+  return {
+    add(conn, session) { sessions.set(conn, session) },
+    remove(conn) {
+      sessions.delete(conn)
+      for (const [k, v] of byReq) if (v === conn) byReq.delete(k)
+      for (const [k, v] of bySession) if (v === conn) bySession.delete(k)
+    },
+    registerPermissionRequest(reqId, conn) { if (reqId) byReq.set(String(reqId), conn) },
+    // Bind a session id → its connection so worker results/status (bridge +
+    // explore) route back to the dispatching terminal. Re-binding the same
+    // connection under a new id (bootstrap UUID → real MIXDOG_SESSION_ID on the
+    // control frame) drops the stale key, so a result can never route to a dead
+    // bootstrap id.
+    registerSession(sessionId, conn) {
+      if (!sessionId) return
+      const key = String(sessionId)
+      for (const [k, v] of bySession) if (v === conn && k !== key) bySession.delete(k)
+      bySession.set(key, conn)
+    },
+    async route(method, params) {
+      // 1. Permission replies are request-scoped: the channels worker emits
+      // `notifications/claude/channel/permission` with a top-level request_id.
+      // Deliver ONLY to the originating connection (handing one terminal's
+      // answer to another would be a security/UX break).
+      if (method === 'notifications/claude/channel/permission') {
+        const reqId = params?.request_id != null ? String(params.request_id) : null
+        const target = reqId != null ? byReq.get(reqId) : null
+        if (reqId != null) byReq.delete(reqId)
+        if (target) {
+          return await deliver(target, { method, params }, `permission response for request ${reqId}`)
+        }
+        log(`[daemon] permission response for unknown/closed request ${reqId} — dropped`)
+        return false
+      }
+      // 2. Worker notifications & status (bridge/explore results, lifecycle
+      // echoes) are SESSION-scoped: meta.caller_session_id pins them to the
+      // dispatching terminal. No live session → drop; recoverPending replays
+      // real results on that session's reconnect (durable path — not a
+      // broadcast guess).
+      const meta = params?.meta || null
+      // Lifecycle status pings (silent_to_agent) never enter ANY terminal's
+      // context window — drop before routing, regardless of caller_session_id.
+      // Detached workers route here directly (bypassing agentNotify's silent
+      // branch); caller-session-less emits (bridge HTTP -> owner) previously fell
+      // through to owner delivery and leaked the flag to CC. Discord forwarding
+      // for non-detached emits is handled in agentNotify. The worker-side
+      // notifyFn / sendNotifyToParent gates coerce this flag to boolean before
+      // IPC, so === true is sufficient (no string 'true' reaches here).
+      if (meta?.silent_to_agent === true) return true;
+      const sid = meta?.caller_session_id != null ? String(meta.caller_session_id) : null
+      if (sid != null) {
+        const hostPid = Number(meta?.client_host_pid) || 0
+        const target = bySession.get(sid)
+        if (target) {
+          const targetSession = sessions.get(target) || null
+          const targetHostPid = Number(targetSession?.clientHostPid) || 0
+          if (!hostPid || (targetHostPid > 0 && targetHostPid === hostPid)) {
+            return await deliver(target, { method, params }, `worker notify for session ${sid}`)
+          }
+          log(`[daemon] worker notify for session ${sid} host mismatch target=${targetHostPid || 'unknown'} meta=${hostPid} — routing by host`)
+        }
+        // The dispatching session id is stale. MIXDOG_SESSION_ID is unset in the
+        // terminal, so the control frame never swaps in a stable id and EVERY
+        // reconnect mints a fresh bootstrap UUID (serveDaemon randomUUID); the
+        // prior conn's close drops its bySession key (remove()). A detached
+        // worker that outlived a reconnect would otherwise be lost even though
+        // its terminal is still attached. The terminal IS reachable under its
+        // stable per-terminal key: client_host_pid (= CC host ppid, invariant
+        // across reconnects, stamped on both the session and the notify meta).
+        // Route by that BEFORE owner — this delivers a non-owner terminal's own
+        // worker result back to it, not misrouted to the owner.
+        if (hostPid > 0) {
+          const hconn = resolveConnByHostPid(hostPid)
+          if (hconn) return await deliver(hconn, { method, params }, `worker notify for host ${hostPid}`)
+          log(`[daemon] worker notify for session ${sid} retained — host ${hostPid} not connected`)
+          return false
+        }
+        // Host pid is unknown (legacy client without host-pid): deliver to the
+        // active-instance owner terminal — the SAME ownerLeadPid SSOT
+        // (active-instance.json) the channel branch below trusts, not a broadcast
+        // guess. Host-scoped modern results never take this fallback because that
+        // would ack-and-delete a pending result in the wrong terminal.
+        const ownerForStaleSid = ownerConn()
+        if (ownerForStaleSid) {
+          return await deliver(ownerForStaleSid, { method, params }, `legacy worker notify for session ${sid}`)
+        }
+        log(`[daemon] worker notify for session ${sid} dropped — session + host + owner not connected`)
+        return false
+      }
+      const hostPid = Number(meta?.client_host_pid) || 0
+      if (meta?.type === 'dispatch_result' && hostPid > 0) {
+        const hconn = resolveConnByHostPid(hostPid)
+        if (hconn) return await deliver(hconn, { method, params }, `dispatch result for host ${hostPid}`)
+        log(`[daemon] dispatch result retained — host ${hostPid} not connected`)
+        return false
+      }
+      // 3. Channel events (Discord inbound / schedule / webhook / queue) are
+      // OWNER-scoped: only the active-instance owner terminal handles them.
+      // Owner not connected → drop; the queue / Discord surface it on reconnect.
+      const owner = ownerConn()
+      if (owner) {
+        return await deliver(owner, { method, params }, `channel event ${method}`)
+      }
+      log(`[daemon] channel event ${method} dropped — owner terminal not connected`)
+      return false
+    },
+  }
+}
+
+// Forward a channel permission request to the channels worker, replying with an
+// explicit deny (via replyNotify) if the worker is unavailable so CC never hangs.
+function forwardChannelPermissionRequest(params, replyNotify) {
+  const entry = workers.get('channels')
+  const reqId = params?.request_id
+  const deny = (reason) => replyNotify({
+    method: 'notifications/claude/channel',
+    params: { content: JSON.stringify({ type: 'permission_response', request_id: reqId, granted: false, reason }), meta: { user: 'mixdog-agent', user_id: 'system', ts: new Date().toISOString(), type: 'permission_response' } },
+  })
+  if (!entry?.proc?.connected || !entry.ready) {
+    log(`permission_request denied: channels worker not available (request_id=${reqId})`)
+    deny('channels worker not available')
+    return false
+  }
+  try {
+    entry.proc.send({ type: 'permission_request_inbound', params })
+    return true
+  } catch (err) {
+    log(`permission_request IPC send failed: ${err instanceof Error ? err.message : String(err)}`)
+    deny('IPC send failed')
+    return false
+  }
+}
+
+server.setNotificationHandler(ChannelPermissionRequestNotificationSchema, async (notification) => {
+  forwardChannelPermissionRequest(notification.params, (n) => {
+    if (process.stdout.writable && !process.stdout.writableEnded) server.notification(n).catch(err => log(`[permission] notification dispatch failed: ${err?.message ?? err}`))
+  })
+})
+
+// ── Worker process management ──────────────────────────────────────
+const workers = new Map() // name → { proc, ready, pending }
+const WORKER_RESTART_WARN_AFTER = 3 // log [WARN] once attempt count crosses this; no hard cap
+const WORKER_MAX_BACKOFF_MS = 60_000
+const workerRestarts = new Map() // name → count (telemetry + backoff exponent + warn threshold)
+const workerIntentionalStop = new Set() // names where parent initiated shutdown; suppress respawn
+const workerPermanentlyDegraded = new Set() // worker self-declared unrecoverable (init reported degraded:true); suppress respawn
+
+// Cached bridge-llm factory import — loaded on first agent_ipc_request and
+// reused thereafter. The agent module must be loaded before the first call
+// (loadModule('agent') runs at boot, well before any memory cycle fires).
+let _bridgeLlmFactory = null
+async function _getBridgeLlmFactory() {
+  if (_bridgeLlmFactory) return _bridgeLlmFactory
+  const mod = await import(
+    pathToFileURL(join(PLUGIN_ROOT, 'src', 'agent', 'orchestrator', 'smart-bridge', 'bridge-llm.mjs')).href
+  )
+  _bridgeLlmFactory = mod.makeBridgeLlm
+  return _bridgeLlmFactory
+}
+
+// Per-callId AbortController so a worker-side timeout can plumb
+// agent_ipc_cancel through to the in-flight bridge LLM provider call,
+// stopping further token billing instead of letting the call run to
+// completion after the worker stopped waiting for the result.
+const AGENT_IPC_MAX_CONCURRENT = 2
+const _agentIpcInflight = new Map()
+/** @type {Array<{ msg: object, worker: string, proc: import('child_process').ChildProcess }>} */
+const _agentIpcQueue = []
+let _agentIpcRunning = 0
+
+function _sendAgentIpcResponse(proc, callId, body) {
+  try { proc.send({ type: 'agent_ipc_response', callId, ...body }) } catch {}
+}
+
+function _startAgentIpcJob(job) {
+  const { msg, worker, proc } = job
+  const _ctrl = new AbortController()
+  _agentIpcInflight.set(msg.callId, { ctrl: _ctrl, worker })
+  void handleAgentIpcRequest(msg, _ctrl.signal).then(res => {
+    _sendAgentIpcResponse(proc, msg.callId, res)
+  }).catch(err => {
+    try { process.stderr.write(`[agent_ipc] handler rejected callId=${msg.callId}: ${err?.stack || err?.message || err}\n`) } catch {}
+    _sendAgentIpcResponse(proc, msg.callId, { ok: false, error: err?.message || String(err) })
+  }).finally(() => {
+    _agentIpcInflight.delete(msg.callId)
+    _agentIpcRunning = Math.max(0, _agentIpcRunning - 1)
+    _drainAgentIpcQueue()
+  })
+}
+
+function _drainAgentIpcQueue() {
+  while (_agentIpcRunning < AGENT_IPC_MAX_CONCURRENT && _agentIpcQueue.length > 0) {
+    const job = _agentIpcQueue.shift()
+    _agentIpcRunning++
+    _startAgentIpcJob(job)
+  }
+}
+
+function _enqueueAgentIpcRequest(msg, worker, proc) {
+  _agentIpcQueue.push({ msg, worker, proc })
+  _drainAgentIpcQueue()
+}
+
+function _cancelQueuedAgentIpc(callId, proc) {
+  const idx = _agentIpcQueue.findIndex(j => j.msg.callId === callId)
+  if (idx === -1) return false
+  const [job] = _agentIpcQueue.splice(idx, 1)
+  _sendAgentIpcResponse(job.proc || proc, callId, { ok: false, error: 'agent_ipc cancelled before start' })
+  return true
+}
+
+function _purgeAgentIpcForWorker(workerName) {
+  for (let i = _agentIpcQueue.length - 1; i >= 0; i--) {
+    if (_agentIpcQueue[i].worker === workerName) {
+      const job = _agentIpcQueue.splice(i, 1)[0]
+      _sendAgentIpcResponse(job.proc, job.msg.callId, { ok: false, error: `worker ${workerName} exited` })
+    }
+  }
+}
+
+async function handleAgentIpcRequest(msg, signal) {
+  const params = msg?.params || {}
+  try {
+    if (msg.tool !== 'bridge_llm') {
+      return { ok: false, error: `unsupported agent_ipc tool "${msg.tool}"` }
+    }
+    if (!params.prompt) {
+      return { ok: false, error: 'bridge_llm: prompt required' }
+    }
+    const makeBridgeLlm = await _getBridgeLlmFactory()
+    const llm = makeBridgeLlm({
+      role: params.role || undefined,
+      taskType: params.taskType || undefined,
+      mode: params.mode || undefined,
+      cwd: params.cwd || undefined,
+      parentSignal: signal || undefined,
+    })
+    const raw = await llm({
+      prompt: params.prompt,
+      mode: params.mode || undefined,
+      preset: params.preset || undefined,
+      timeout: params.timeout || undefined,
+    })
+    return { ok: true, result: raw }
+  } catch (e) {
+    return { ok: false, error: e?.message || String(e) }
+  }
+}
+
+function spawnWorker(name) {
+  process.stderr.write(`[boot-time] tag=worker-spawn name=${name} tMs=${Date.now()}\n`)
+  const modulePath = join(PLUGIN_ROOT, 'src', name, 'index.mjs')
+  // Per-worker stderr files so cycle1/cycle2/embed/recap diagnostics are
+  // captured even when the worker hangs before answering an IPC call. The
+  // legacy shared log stays for compatibility; the scoped sibling makes
+  // multi-terminal analysis unambiguous.
+  const stderrPath = join(PLUGIN_DATA, `${name}-worker.log`)
+  const stderrScopedPath = join(PLUGIN_DATA, `${name}-worker.${LOG_OWNER_LEAD_PID}.${process.pid}.log`)
+  // One-shot rotation before opening: if worker log >10 MB, rename to .1 (overwrite).
+  try { if (statSync(stderrPath).size > 10 * 1024 * 1024) renameSync(stderrPath, stderrPath + '.1') } catch {}
+  try { if (statSync(stderrScopedPath).size > 10 * 1024 * 1024) renameSync(stderrScopedPath, stderrScopedPath + '.1') } catch {}
+  let stderrStream = null
+  let stderrScopedStream = null
+  let stderrRemainder = ''
+  const proc = fork(modulePath, [], {
+    // stdio idx 1 = 'ignore' so a worker stdout write (or a stdout write
+    // from any worker dependency such as bun runtime warnings, transformers,
+    // onnxruntime) cannot leak into the parent's MCP JSON-RPC stream and
+    // corrupt the frame the client sees. Worker logs are piped and written
+    // with lead/server/worker metadata; IPC carries everything functional.
+    // The supervisor (run-mcp.mjs) also quarantines any non-JSON line that
+    // does reach its stdout pipe — defense in depth against future regressions.
+    stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+    env: {
+      ...process.env,
+      CLAUDE_PLUGIN_ROOT: PLUGIN_ROOT,
+      CLAUDE_PLUGIN_DATA: PLUGIN_DATA,
+      MIXDOG_WORKER_MODE: '1',
+      MIXDOG_SESSION_ID: SESSION_ID,
+      MIXDOG_OWNER_SESSION_ID: SESSION_ID,
+      MIXDOG_SERVER_PID: String(process.pid),
+      MIXDOG_OWNER_LEAD_PID: process.env.MIXDOG_SUPERVISOR_PID || '',
+    },
+    windowsHide: true,
+  })
+  // Build a list of env values to scrub from worker log output. Workers run
+  // with the full parent env (provider keys, OAuth tokens) so those literal
+  // values can otherwise surface verbatim in stderr (stack traces, debug
+  // dumps). The env itself is left untouched — workers still need the keys
+  // to call providers; only the LOG bytes are redacted.
+  const SECRET_ENV_RE = /^(ANTHROPIC_|CLAUDE_|AWS_|OPENAI_|GH_|GITHUB_|NPM_|.*_API_KEY|.*_TOKEN|.*_SECRET)/
+  const secretEnvValues = []
+  try {
+    for (const [k, v] of Object.entries(process.env)) {
+      if (!v || typeof v !== 'string') continue
+      if (v.length < 4) continue
+      if (SECRET_ENV_RE.test(k)) secretEnvValues.push(v)
+    }
+    // Longest first so a longer secret containing a shorter one is masked whole.
+    secretEnvValues.sort((a, b) => b.length - a.length)
+  } catch {}
+  const redactSecrets = (text) => {
+    if (!text) return text
+    let s = String(text)
+    // Wrap all redaction in try/catch: a regex/replace failure must NEVER break
+    // worker logging. On error, return whatever was redacted so far (best-effort).
+    try {
+      // Authorization: Bearer <token>
+      s = s.replace(/(Bearer\s+)[A-Za-z0-9._\-]+/gi, '$1[REDACTED]')
+      // sk-/key-like long opaque tokens (provider key prefixes + generic 32+ char tokens)
+      s = s.replace(/\b(sk|sk-ant|pk|rk|gh[pousr]|xox[abprs]|ghp|ghs|ghu|ghr|github_pat)[-_][A-Za-z0-9_\-]{16,}/g, '[REDACTED]')
+      s = s.replace(/\b[A-Za-z0-9_\-]{32,}\.[A-Za-z0-9_\-]{16,}\b/g, '[REDACTED]')
+      // --password=VALUE / --password VALUE / -p VALUE
+      s = s.replace(/(--password(?:=|\s+)|--token(?:=|\s+)|--secret(?:=|\s+)|(?:^|\s)-p\s+)\S+/gi, '$1[REDACTED]')
+      // URL userinfo: scheme://user:pass@host
+      s = s.replace(/([a-zA-Z][a-zA-Z0-9+\-.]*:\/\/)([^\s/:@]+):([^\s/@]+)@/g, '$1[REDACTED]:[REDACTED]@')
+      // Literal env secret values
+      for (const v of secretEnvValues) {
+        s = s.split(v).join('[REDACTED]')
+      }
+    } catch { /* best-effort: never throw out of redactSecrets */ }
+    return s
+  }
+  const writeWorkerLogLine = (rawLine) => {
+    // R14: sanitize AFTER redactSecrets so the redaction patterns still see
+    // raw bytes (URL userinfo, Authorization headers), then strip ANSI / escape
+    // lone CR + C0/C1 so a stderr line like "foo\r[fake-log-prefix] payload"
+    // can't forge a new log entry or hide payloads behind a CR overwrite.
+    const line = sanitizeLogField(redactSecrets(rawLine))
+    const out = `[${new Date().toISOString()}] [${LOG_CONTEXT} worker=${name} workerPid=${proc.pid ?? '-'}] ${line}\n`
+    try {
+      if (!stderrStream) {
+        stderrStream = createWriteStream(stderrPath, { flags: 'a' })
+        stderrStream.on('error', () => {})
+      }
+      stderrStream.write(out)
+    } catch {
+      try { appendFileSync(stderrPath, out) } catch {}
+    }
+    try {
+      if (!stderrScopedStream) {
+        stderrScopedStream = createWriteStream(stderrScopedPath, { flags: 'a' })
+        stderrScopedStream.on('error', () => {})
+      }
+      stderrScopedStream.write(out)
+    } catch {
+      try { appendFileSync(stderrScopedPath, out) } catch {}
+    }
+  }
+  const writeWorkerLogChunk = (chunk) => {
+    const text = stderrRemainder + String(chunk)
+    const lines = text.split(/\r?\n/)
+    stderrRemainder = lines.pop() ?? ''
+    for (const line of lines) writeWorkerLogLine(line)
+  }
+  const closeWorkerLog = () => {
+    if (stderrRemainder) {
+      writeWorkerLogLine(stderrRemainder)
+      stderrRemainder = ''
+    }
+    try { stderrStream?.end() } catch {}
+    try { stderrScopedStream?.end() } catch {}
+  }
+  proc.stderr?.setEncoding?.('utf8')
+  proc.stderr?.on('data', writeWorkerLogChunk)
+  proc.stderr?.on('error', () => {})
+  proc.once('exit', closeWorkerLog)
+
+  const entry = { proc, ready: false, pending: [] }
+  // readyPromise lets callWorker await the worker's first 'ready' IPC instead
+  // of rejecting immediately on entry.ready===false. Pre-ready callers (e.g.
+  // SessionStart /cycle1) used to bounce off a 503 and rely on the hook's
+  // 200ms retry loop; now they hold a single in-flight call until the worker
+  // signals ready or the proc exits before that.
+  entry.readyPromise = new Promise((resolve, reject) => {
+    entry._resolveReady = resolve
+    entry._rejectReady = reject
+  })
+  // Attach a no-op catch so a reject before any awaiter is hooked up does not
+  // trigger unhandledRejection. The actual awaiter (callWorker) still observes
+  // the rejection because await on a rejected promise re-throws.
+  entry.readyPromise.catch(() => {})
+  workers.set(name, entry)
+
+  proc.on('message', msg => {
+    // R13: validate worker IPC frame shape before dispatch. A malformed frame
+    // (null, array, primitive, or missing string type) used to throw at the
+    // first field access or misroute into a privileged branch. Reject early.
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg) || typeof msg.type !== 'string') {
+      try { process.stderr.write(`[worker-ipc] dropped malformed frame from worker=${name}\n`) } catch {}
+      return
+    }
+    try {
+    if (msg.type === 'ready') {
+      process.stderr.write(`[boot-time] tag=worker-ready name=${name} tMs=${Date.now()}\n`)
+      if (msg.degraded) {
+        log(`worker ${name} signalled degraded on boot: ${msg.error || 'unknown'}`)
+        // Treat init failures as permanent (no retries): init errors indicate
+        // unrecoverable state (e.g. pgdata corruption, missing schema) that
+        // will not heal across restarts. Mark restart count at cap immediately
+        // so the 'exit' handler skips respawn. This avoids 3 pointless retries
+        // that each take several seconds and leave pgdata in a worse state.
+        // Transient network / port-bind errors are expected to NOT send
+        // degraded:true — they crash the worker without a 'ready' signal, so
+        // the normal restart counter handles them.
+        workerPermanentlyDegraded.add(name)  // permanent — exit handler skips respawn
+        try { entry._rejectReady(new Error(`worker ${name} degraded: ${msg.error || 'init failed'}`)) } catch {}
+        return
+      }
+      // Cache the channels worker's detected channel flag. Daemon ancestry is
+      // constant for the daemon's lifetime, so respawned workers can inherit
+      // this via the env spread and skip the (slow) ancestor-process walk.
+      if (typeof msg.channelFlag === 'boolean') {
+        process.env.MIXDOG_CHANNEL_FLAG = msg.channelFlag ? '1' : '0'
+      }
+      entry.ready = true
+      workerIntentionalStop.delete(name)
+      workerRestarts.delete(name)  // stable boot resets the backoff/warn counter
+      try { entry._resolveReady() } catch {}
+      log(`worker ${name} ready (pid=${proc.pid})`)
+      if (name === 'memory' && Number.isFinite(msg.port) && msg.port > 0) {
+        const file = ACTIVE_INSTANCE_FILE
+        const memoryServerPid = parsePositivePid(process.pid)
+        // EPERM/EBUSY/EACCES on rename means an AV scanner briefly holds
+        // the new .tmp file open while inspecting it. The lock typically
+        // clears within 100-300ms. Without retry the merge is lost and
+        // statusline / memory_port discovery falls back to stale state for
+        // the rest of the process lifetime. Async retry chain keeps the
+        // message handler unblocked while the next attempts run.
+        const _retryMerge = (attempt) => {
+          try {
+            withFileLockSync(`${file}.lock`, () => {
+              let cur = {}
+              try { cur = JSON.parse(readFileSync(file, 'utf8')) } catch {}
+              const curMemPort = Number(cur?.memory_port)
+              const curMemPid = parsePositivePid(cur?.memory_server_pid)
+              const portConflict =
+                Number.isFinite(curMemPort) && curMemPort > 0 && curMemPort !== msg.port
+              const otherOwnerAlive =
+                curMemPid != null &&
+                curMemPid !== memoryServerPid &&
+                isMemoryOwnerPidAlive(curMemPid)
+              if (portConflict && otherOwnerAlive) {
+                log(`[server-main] skip memory_port ready merge port=${msg.port} curMemPort=${curMemPort} curMemPid=${curMemPid} memoryServerPid=${memoryServerPid || 'none'}`)
+                return
+              }
+              const next = {
+                ...cur,
+                memory_port: msg.port,
+                memory_server_pid: memoryServerPid,
+                updatedAt: Date.now(),
+              }
+              writeJsonAtomicSync(file, next, { compact: true, fsyncDir: true })
+            })
+          } catch (e) {
+            const transient = e?.code === 'EPERM' || e?.code === 'EBUSY' || e?.code === 'EACCES'
+            if (transient && attempt < 3) {
+              setTimeout(() => _retryMerge(attempt + 1), 50 * (attempt + 1))
+              return
+            }
+            log(`[server-main] active-instance memory_port merge failed (attempt ${attempt + 1}): ${e?.message || e}`)
+          }
+        }
+        _retryMerge(0)
+      }
+      return
+    }
+    if (msg.type === 'result' && typeof msg.callId === 'string' &&
+        (Object.prototype.hasOwnProperty.call(msg, 'result') || typeof msg.error === 'string')) {
+      // Clear any pending force-kill timer for this callId: a late result
+      // after cooperative cancel means the worker is healthy and the
+      // 5s SIGTERM timer from callWorker's timeout path must not fire.
+      const killTimer = entry.killTimers?.get(msg.callId)
+      if (killTimer) {
+        clearTimeout(killTimer)
+        entry.killTimers.delete(msg.callId)
+      }
+      const pending = entry.pending.find(p => p.callId === msg.callId)
+      if (pending) {
+        entry.pending = entry.pending.filter(p => p.callId !== msg.callId)
+        if (msg.error) pending.reject(new Error(msg.error))
+        else pending.resolve(msg.result)
+      }
+      return
+    }
+    if (msg.type === 'recap_status' && msg.recap) {
+      recapStatusState = sanitizeRecapStatusState(msg.recap)
+      forwardRecapStatusToStatusServer()
+      return
+    }
+    if (msg.type === 'notify' && typeof msg.method === 'string') {
+      // Worker → parent notification forwarding. The worker has no MCP
+      // transport of its own; this is the single path that delivers Discord
+      // inbound, schedule injects, webhook events, and interaction events
+      // to the host (Claude Code) over the parent's connected Server.
+      if (daemonNotifyRouter) {
+        // Daemon mode: route to the request's origin connection (permission
+        // responses) or the Lead connection (channel events). No stdio.
+        daemonNotifyRouter.route(msg.method, msg.params || {})
+          .catch(err => {
+            log(`worker ${name} notify route failed (${msg.method}): ${err instanceof Error ? err.message : String(err)}`)
+          })
+      } else if (process.stdout.writableEnded || !process.stdout.writable) {
+        log(`worker ${name} notify forward skipped — stdout closed (${msg.method})`)
+      } else {
+        server.notification(channelNotifyParamsForCc({ method: msg.method, params: msg.params || {} }))
+          .catch(err => {
+            log(`worker ${name} notify forward failed (${msg.method}): ${err instanceof Error ? err.message : String(err)}`)
+          })
+      }
+      return
+    }
+    if (msg.type === 'agent_ipc_request' && typeof msg.callId === 'string' && typeof msg.tool === 'string') {
+      // Worker → parent bridge LLM request. Memory worker cannot own the
+      // provider registry / session manager (those live in the parent
+      // process via loadModule('agent')), so cycle1 / cycle2 route every
+      // LLM call here. We run the bridge call in-process, then ship the
+      // raw assistant content back to the caller.
+      _enqueueAgentIpcRequest(msg, name, proc)
+      return
+    }
+    if (msg.type === 'agent_ipc_cancel' && typeof msg.callId === 'string') {
+      // Worker timeout fired — stop the in-flight bridge LLM call before
+      // it bills further tokens. parentSignal cascade aborts the
+      // sub-session's own controller (bridge-llm.mjs:217-224).
+      const _entry = _agentIpcInflight.get(msg.callId)
+      if (_entry) {
+        try { _entry.ctrl.abort() } catch {}
+        _agentIpcInflight.delete(msg.callId)
+        return
+      }
+      _cancelQueuedAgentIpc(msg.callId, proc)
+      return
+    }
+    if (msg.type === 'memory_call_request' && msg.callId) {
+      // Worker → parent → memory worker bridge. Lets non-memory workers
+      // (e.g. channels) trigger memory tool actions like cycle1 without
+      // owning the memory worker handle directly.
+      // Worker handleToolCall only knows mcp tool names ('memory',
+      // 'search_memories'); the action ('cycle1', 'flush', ...) lives in
+      // args.action. Forwarding msg.action as the tool name made every
+      // /cycle1 hit return "unknown tool: cycle1" instantly.
+      // asyncAck: caller (e.g. channels worker chat ingest) opts in to an
+      // immediate ack so it doesn't block on long-running memory work like
+      // cycle2 / flush. Default path keeps the await semantics so cold-entry
+      // cycle1 / recap flows still get the real result before continuing.
+      if (msg.asyncAck) {
+        try { proc.send({ type: 'memory_call_response', callId: msg.callId, ok: true, result: { acked: true } }) } catch {}
+        callWorker('memory', 'memory', { action: msg.action, ...(msg.args || {}) })
+          .catch(err => process.stderr.write(`[memory_call] async ${msg.action} rejected: ${err?.message || err}\n`))
+        return
+      }
+      callWorker('memory', 'memory', { action: msg.action, ...(msg.args || {}) })
+        .then(result => {
+          try { proc.send({ type: 'memory_call_response', callId: msg.callId, ok: true, result }) } catch {}
+        })
+        .catch(err => {
+          try { proc.send({ type: 'memory_call_response', callId: msg.callId, ok: false, error: err?.message || String(err) }) } catch {}
+        })
+      return
+    }
+    } catch (err) {
+      try { process.stderr.write(`[worker-ipc] handler error worker=${name} type=${msg && msg.type}: ${err?.message || err}\n`) } catch {}
+    }
+  })
+
+  // Attach 'exit' before 'error' so a synchronous spawn-fail sees 'exit'
+  // before 'error' — prevents dangling exit handler on early-fail path.
+  proc.on('exit', (code) => {
+    log(`worker ${name} exited (code=${code})`)
+    workers.delete(name)
+    // Abort any in-flight bridge LLM provider calls owned by this worker so
+    // a dying worker stops billing tokens for results nobody is waiting on.
+    let _abortedIpc = 0
+    for (const [_cid, _e] of _agentIpcInflight) {
+      if (_e.worker === name) {
+        try { _e.ctrl.abort() } catch {}
+        _agentIpcInflight.delete(_cid)
+        _abortedIpc++
+      }
+    }
+    if (_abortedIpc > 0) log(`worker ${name} exit — aborted ${_abortedIpc} in-flight agent_ipc call(s)`)
+    _purgeAgentIpcForWorker(name)
+    // Intentional stop: parent sent shutdown IPC/SIGTERM — do not respawn.
+    if (workerIntentionalStop.has(name)) {
+      log(`worker ${name} stopped intentionally — skipping respawn`)
+      return
+    }
+    if (!entry.ready) {
+      try { entry._rejectReady(new Error(`worker ${name} exited before ready (code=${code})`)) } catch {}
+    }
+    for (const p of entry.pending) {
+      p.reject(new Error(`worker ${name} exited unexpectedly`))
+    }
+    if (workerPermanentlyDegraded.has(name)) {
+      log(`worker ${name} permanently degraded — skipping respawn`)
+      return
+    }
+    const count = (workerRestarts.get(name) || 0) + 1
+    workerRestarts.set(name, count)
+    const backoffMs = Math.min(1000 * Math.pow(2, Math.min(count - 1, 6)), WORKER_MAX_BACKOFF_MS)
+    if (count <= WORKER_RESTART_WARN_AFTER) {
+      log(`restarting worker ${name} (attempt ${count}, backoff ${backoffMs}ms)`)
+    } else {
+      log(`[WARN] worker ${name} repeated restart (attempt ${count}, backoff ${backoffMs}ms) — investigate root cause`)
+    }
+    setTimeout(() => spawnWorker(name), backoffMs)
+  })
+
+  proc.on('error', (err) => {
+    log(`worker ${name} error: ${err.message}`)
+  })
+
+  // IPC disconnect handler: if the channel drops while calls are in flight,
+  // reject pending immediately with a stable message so callers don't wait
+  // for the full WORKER_CALL_TIMEOUT before surfacing an error.
+  proc.once('disconnect', () => {
+    const snap = [...entry.pending]
+    entry.pending = []
+    for (const p of snap) {
+      p.reject(new Error(`worker ${name} disconnected`))
+    }
+    if (!entry.ready) {
+      try { entry._rejectReady(new Error(`worker ${name} disconnected before ready`)) } catch {}
+    }
+    // Abort in-flight bridge LLM provider calls owned by this worker — the
+    // IPC channel is gone so the response can never be delivered; letting
+    // the provider call run on would only burn tokens.
+    let _abortedIpc = 0
+    for (const [_cid, _e] of _agentIpcInflight) {
+      if (_e.worker === name) {
+        try { _e.ctrl.abort() } catch {}
+        _agentIpcInflight.delete(_cid)
+        _abortedIpc++
+      }
+    }
+    _purgeAgentIpcForWorker(name)
+    log(`worker ${name} IPC disconnected — rejected ${snap.length} pending call(s), aborted ${_abortedIpc} agent_ipc call(s)`)
+  })
+
+  return entry
+}
+
+let _callIdSeq = 0
+const WORKER_CALL_TIMEOUT = 600000 // 10m per tool call
+// Window for awaiting a missing worker entry. Covers the 1s exit→spawn
+// timer plus typical memory boot (~2-3s). Long enough that the entry
+// reappears under normal restart flow, short enough that a permanently
+// dead worker still surfaces within bounds.
+const WORKER_NO_ENTRY_GRACE_MS = 8000
+
+async function callWorker(name, toolName, args) {
+  let entry = workers.get(name)
+  // worker-unavailable: only restart-cap-exceeded and ipc-gone cases reject
+  // synchronously. The pre-ready and mid-restart cases hold under bounded
+  // waits so callers (e.g. SessionStart /cycle1) stop bouncing 503 across
+  // the exit→spawn gap. exit-before-ready rejects readyPromise, which
+  // surfaces here as a normal throw with the original 'exited before ready'
+  // message preserved.
+  if (!entry) {
+    if (workerPermanentlyDegraded.has(name)) {
+      throw new Error(`worker ${name} not available (permanently degraded)`)
+    }
+    const deadline = Date.now() + WORKER_NO_ENTRY_GRACE_MS
+    while (Date.now() < deadline) {
+      await new Promise(r => setTimeout(r, 100))
+      entry = workers.get(name)
+      if (entry) break
+      if (workerPermanentlyDegraded.has(name)) {
+        throw new Error(`worker ${name} not available (permanently degraded)`)
+      }
+    }
+    if (!entry) {
+      throw new Error(`worker ${name} not available (no entry after ${WORKER_NO_ENTRY_GRACE_MS}ms)`)
+    }
+  }
+  if (!entry.proc.connected) {
+    throw new Error(`worker ${name} not available (ipc disconnected)`)
+  }
+  if (!entry.ready) {
+    // Bound the readyPromise wait: a worker process can be alive (no exit
+    // event, no IPC disconnect) yet never send its 'ready' IPC if init
+    // hangs (DB connect stall, vector index rebuild). Without a deadline
+    // here, worker-to-worker calls would block indefinitely.
+    const READY_WAIT_MS = 30000
+    let readyTimer = null
+    const readyTimeout = new Promise((_, reject) => {
+      readyTimer = setTimeout(() => {
+        reject(new Error(`worker ${name} not ready within ${READY_WAIT_MS}ms`))
+      }, READY_WAIT_MS)
+      readyTimer.unref?.()
+    })
+    try {
+      await Promise.race([entry.readyPromise, readyTimeout])
+    } finally {
+      if (readyTimer) clearTimeout(readyTimer)
+    }
+    if (!entry.proc.connected) {
+      throw new Error(`worker ${name} not available (ipc disconnected)`)
+    }
+  }
+  return new Promise((resolve, reject) => {
+    const callId = String(++_callIdSeq)
+    const timer = setTimeout(() => {
+      entry.pending = entry.pending.filter(p => p.callId !== callId)
+      // Signal the worker to cancel in-flight work for this callId.
+      try {
+        if (entry.proc?.connected) {
+          entry.proc.send({ type: 'cancel', callId })
+          // Force-kill if worker doesn't ack within 5s.
+          // Track the kill timer on the entry keyed by callId so the IPC
+          // result handler can clear it when the worker delivers a late
+          // result (cooperative cancel succeeded after we gave up waiting).
+          // Without this clear, a single timed-out call always killed the
+          // whole worker even when it returned a clean result in time.
+          if (!entry.killTimers) entry.killTimers = new Map()
+          const killTimer = setTimeout(() => {
+            entry.killTimers?.delete(callId)
+            log(`worker ${name} did not ack cancel for ${callId} — force-killing`)
+            try { entry.proc.kill('SIGTERM') } catch {}
+          }, 5000)
+          if (killTimer.unref) killTimer.unref()
+          entry.killTimers.set(callId, killTimer)
+        }
+      } catch {}
+      // Persist dispatch state so recoverPending surfaces it on next boot.
+      const _dataDir = process.env.CLAUDE_PLUGIN_DATA
+      if (_dataDir) {
+        import('./src/agent/orchestrator/dispatch-persist.mjs').then(({ addPending }) => {
+          addPending(_dataDir, `timeout_${callId}_${Date.now()}`, 'bridge', [`worker ${name} call ${toolName} timed out`])
+        }).catch(() => {})
+      }
+      reject(new Error(`worker ${name} call ${toolName} timed out after ${WORKER_CALL_TIMEOUT}ms`))
+    }, WORKER_CALL_TIMEOUT)
+    entry.pending.push({ callId, resolve: v => { clearTimeout(timer); resolve(v) }, reject: e => { clearTimeout(timer); reject(e) } })
+    try {
+      // child.send() returning false means the IPC channel applied
+      // backpressure — the message is queued internally by Node and will be
+      // flushed when the channel drains; it is NOT a delivery failure.
+      // Rejecting here while the worker may still receive (and execute)
+      // the call leaves the parent waiting on a pending it just forgot
+      // about, AND lets a side-effecting tool run with the parent
+      // believing it failed. Keep the pending entry in place and let the
+      // existing WORKER_CALL_TIMEOUT bound the wait if the channel never
+      // drains; an actual transport failure surfaces through the catch
+      // below or via the 'exit'/'disconnect' handlers that reject pending.
+      entry.proc.send({ type: 'call', callId, name: toolName, args })
+    } catch (sendErr) {
+      clearTimeout(timer)
+      entry.pending = entry.pending.filter(p => p.callId !== callId)
+      reject(new Error(`worker ${name} send failed: ${sendErr.message}`))
+    }
+  })
+}
+
+// ── Module loader (cached, init+start runs once per module) ─────────
+const modules = new Map()
+
+function pushChannelNotification(content, extraMeta) {
+  // Single exit path for BOTH channel notifications (schedule / webhook /
+  // queue / bridge lifecycle) AND dispatch results (recall / search
+  // / explore merged answers tagged `meta.type: 'dispatch_result'`). Despite
+  // the name, this function is bidirectional — the `extraMeta.type` field
+  // distinguishes the two flavours for downstream routing, not this function.
+  //
+  // `silent_to_agent: true` — bridge lifecycle status pings (worker started,
+  // iter N, role-start echoes) that should surface on Discord but NOT land
+  // in the Lead agent's context window. When set we skip the Lead-notify
+  // hop entirely and ask the channels worker to post the content directly
+  // to the currently-active bridge channel. The meta flag is otherwise
+  // forwarded downstream so any future consumer that sees it can recognise
+  // and drop it. Default (flag absent/false) → legacy behaviour preserved.
+  const meta = { user: 'mixdog-agent', user_id: 'system', ts: new Date().toISOString(), ...(extraMeta || {}) }
+  const silent = meta.silent_to_agent === true
+  if (silent) {
+    const entry = workers.get('channels')
+    if (entry?.proc?.connected) {
+      try {
+        const sent = entry.proc.send({ type: 'forward_to_discord', content, channelId: meta.chat_id || null })
+        if (sent === false) {
+          log(`[agent-notify] silent forward IPC channel full or closed — dropping`)
+        }
+      } catch (err) {
+        log(`[agent-notify] silent forward IPC failed: ${err instanceof Error ? err.message : String(err)}`)
+      }
+    }
+    return Promise.resolve()
+  }
+  // Daemon mode: the module-global `server` is NOT connected (each client has
+  // its own per-connection server). Route through the daemon notify router,
+  // which delivers a session-scoped result (meta.caller_session_id) to the
+  // dispatching terminal and a channel event to the active-instance owner.
+  // Without this, the server.notification() below targets an unconnected
+  // server and the notification is silently lost.
+  //
+  // If a SESSION-scoped dispatch result could not be delivered (originating
+  // terminal not connected), reject so the persist layer's notify→removePending
+  // chain LEAVES the entry on disk; per-session recoverPending re-delivers it
+  // when that terminal reconnects (control-frame trigger in serveDaemon).
+  // Channel events (no caller_session_id) just resolve — a missing owner drop
+  // is surfaced again via the queue / Discord, not the pending file.
+  if (daemonNotifyRouter) {
+    return daemonNotifyRouter.route('notifications/claude/channel', { content, meta })
+      .then((delivered) => {
+        if (!delivered && (meta.caller_session_id != null || meta.type === 'dispatch_result')) {
+          throw new Error('dispatch result for session ' + meta.caller_session_id + ' undelivered — retained for replay')
+        }
+      })
+  }
+  // Pre-flight: if stdout is already closed, skip the write to avoid EPIPE.
+  if (process.stdout.writableEnded || !process.stdout.writable) {
+    log('[agent-notify] stdout closed; skipping notification')
+    return Promise.resolve()
+  }
+  try {
+    return server.notification(channelNotifyParamsForCc({
+      method: 'notifications/claude/channel',
+      params: { content, meta },
+    })).catch(err => {
+      log(`[agent-notify] channel failed: ${err instanceof Error ? err.message : String(err)}`)
+    })
+  } catch (err) {
+    log(`[agent-notify] sync throw (likely EPIPE): ${err instanceof Error ? err.message : String(err)}`)
+    return Promise.resolve()
+  }
+}
+
+function agentContext() {
+  return {
+    notifyFn: (text, extraMeta) => pushChannelNotification(text, extraMeta),
+    elicitFn: opts => server.elicitInput(opts),
+    // In-process tool bridge. External LLMs see the plugin's non-agent tools
+    // (search, search_memories, channels actions, etc.) and their tool_calls
+    // land back in dispatchTool, which routes to the same worker IPC /
+    // in-process module the MCP call handler uses. Replaces the MCP HTTP
+    // loopback path. agent-module tools are refused to prevent recursion.
+    toolExecutor: async (name, args, callerCtx = {}) => {
+      // agent-module tools normally refused via bridge to prevent recursion.
+      // Exception: aiWrapped retrieval wrappers (`explore`) spawn one hidden
+      // role and are guarded against re-entry in ai-wrapped-dispatch.mjs —
+      // safe to dispatch from public bridge workers for open-locate briefs.
+      if (TOOL_MODULE[name] === 'agent' && !TOOL_BY_NAME[name]?.aiWrapped) {
+        throw new Error(`tool "${name}" is agent-internal and cannot be invoked via bridge`)
+      }
+      return dispatchTool(name, args, callerCtx)
+    },
+    internalTools: TOOL_DEFS.filter(t => {
+      // Same exception as toolExecutor above: agent-module aiWrapped tools
+      // (`explore`) are surfaced to public workers; plain agent-module tools
+      // remain hidden to prevent recursion.
+      if (t.module === 'agent') return t.aiWrapped === true
+      return true
+    }),
+  }
+}
+
+async function loadModule(name) {
+  let entry = modules.get(name)
+  if (entry) return entry
+  const url = pathToFileURL(join(PLUGIN_ROOT, 'src', name, 'index.mjs')).href
+  const mod = await import(url)
+  if (mod.init) await mod.init(server)
+  if (mod.start) await mod.start()
+  entry = mod
+  modules.set(name, entry)
+  log(`module ${name} ready`)
+  return entry
+}
+
+// Tilde expansion for caller-supplied `cwd`. Mirrors the `~` branch of
+// normalizeInputPath() in builtin.mjs but kept inline so the dispatcher
+// does not have to pre-load the whole builtin module at boot.
+function _expandCwdTilde(p) {
+  if (typeof p !== 'string') return p
+  if (p === '~' || p.startsWith('~/') || p.startsWith('~\\')) return homedir() + p.slice(1)
+  return p
+}
+
+// Shared dispatcher — used by the MCP call handler AND the agent's
+// toolExecutor passed through agentContext(). Single source of tool routing.
+// Public entry wraps body with start/end/error logs so BOTH call paths
+// (MCP CallToolRequest + bridge role toolExecutor) emit complete telemetry.
+function _shortHash(value) {
+  return createHash('sha256').update(String(value || '')).digest('hex').slice(0, 8)
+}
+
+// Re-exec tracking for bash: same cmdHash arriving within TTL is recorded
+// as a marker line, so silent client-side response loss (server logged
+// start+ok but the MCP transport never delivered the result to the host)
+// surfaces as the same command being re-issued. Pure Map lookup; no
+// heuristic branch — the marker fires iff a prior entry exists within
+// TTL. Bound size; oldest-first eviction is an invariant of Map insertion
+// order.
+const _RECENT_BASH_TTL_MS = 10 * 60_000
+const _RECENT_BASH_MAX = 500
+const _recentBashCommands = new Map()
+
+function _trackBashRecurrence(cmdHash, now) {
+  if (!cmdHash) return null
+  const prev = _recentBashCommands.get(cmdHash)
+  let marker = null
+  if (prev && now - prev.ts <= _RECENT_BASH_TTL_MS) {
+    const gap = now - prev.ts
+    prev.count += 1
+    prev.ts = now
+    _recentBashCommands.delete(cmdHash)
+    _recentBashCommands.set(cmdHash, prev)
+    marker = `[bash] re-exec same-hash cmdHash=${cmdHash} gap=${gap}ms count=${prev.count}`
+  } else {
+    if (prev) _recentBashCommands.delete(cmdHash)
+    _recentBashCommands.set(cmdHash, { ts: now, count: 1 })
+  }
+  while (_recentBashCommands.size > _RECENT_BASH_MAX) {
+    const firstKey = _recentBashCommands.keys().next().value
+    if (firstKey === undefined) break
+    _recentBashCommands.delete(firstKey)
+  }
+  return marker
+}
+
+function _flatPreview(value, cap = 80) {
+  return String(value || '').replace(/\s+/g, ' ').trim().slice(0, cap).replace(/[^\x20-\x7e]/g, '?')
+}
+
+function _dispatchInputShape(name, args) {
+  try {
+    if (name === 'bash') {
+      const command = String(args?.command || '')
+      return command ? ` cmdHash=${_shortHash(command)} cmdPreview="${_flatPreview(command)}"` : ''
+    }
+    if (name === 'search') {
+      const hasUrl = args && Object.prototype.hasOwnProperty.call(args, 'url') && args.url !== undefined
+      const input = hasUrl ? args.url : (args?.query ?? args?.keywords ?? '')
+      const count = Array.isArray(input) ? input.length : input ? 1 : 0
+      const mode = hasUrl ? 'url' : 'query'
+      const site = args?.site ? ` site="${_flatPreview(args.site, 60)}"` : ''
+      const type = args?.type ? ` type=${_flatPreview(args.type, 20)}` : ''
+      return ` mode=${mode} itemCount=${count} inputHash=${_shortHash(JSON.stringify(input))}${site}${type}`
+    }
+  } catch {}
+  return ''
+}
+
+function _bashDispatchCeilingMs(args) {
+  const MAX_BASH_TIMEOUT_MS = 1_800_000
+  const DISPATCH_GRACE_MS = 30_000
+  if (!(typeof args?.timeout === 'number' && args.timeout > 0)) {
+    return null
+  }
+  const raw = args.timeout
+  const timeoutMs = raw <= 600 ? raw * 1000 : raw
+  const effectiveTimeoutMs = Math.min(Math.max(timeoutMs, 1_000), MAX_BASH_TIMEOUT_MS)
+  return effectiveTimeoutMs + DISPATCH_GRACE_MS
+}
+
+// Build the cancellation/ceiling wiring for a dispatch: ceiling timer +
+// combined abort signal that folds caller-provided abortSignal and the MCP
+// requestSignal together with the ceiling's own AbortController. Returned
+// `clearCeiling` is idempotent so both the success and error paths in
+// dispatchTool can call it. Preserves the recent fixes (killTimer/ceiling
+// clearing and combined abort signal) by routing every cleanup through
+// the same closure.
+function _buildDispatchCancellation(name, args, callerCtx) {
+  const CEILING_MS = name === 'bash' ? _bashDispatchCeilingMs(args) : 630_000
+  const _abortCtl = new AbortController()
+  let _ceilingTimer
+  let _ceilingPromise = null
+  if (typeof CEILING_MS === 'number' && CEILING_MS > 0) {
+    _ceilingPromise = new Promise((_, reject) => {
+      _ceilingTimer = setTimeout(() => {
+        try { _abortCtl.abort(new Error(`dispatch ceiling exceeded (${CEILING_MS}ms) for tool=${name}`)) } catch {}
+        reject(new Error(`dispatch ceiling exceeded (${CEILING_MS}ms) for tool=${name}`))
+      }, CEILING_MS)
+      _ceilingTimer.unref?.()
+    })
+  }
+  // Combine ceiling abort with any caller-provided abortSignal so neither
+  // masks the other. Both signals propagate to the tool impl; whichever
+  // aborts first wins. Node 20.3+ provides AbortSignal.any.
+  // Also fold in callerCtx.requestSignal (the MCP client-side cancellation
+  // forwarded from the CallTool handler) so direct MCP cancellation
+  // reaches builtins / code-graph / patch paths that only inspect
+  // callerCtx.abortSignal. Without this, the requestSignal was only
+  // visible to the agent module via the explicit ctx.requestSignal handoff.
+  const _abortSignals = []
+  if (_ceilingPromise) _abortSignals.push(_abortCtl.signal)
+  if (callerCtx.abortSignal) _abortSignals.push(callerCtx.abortSignal)
+  if (callerCtx.requestSignal && callerCtx.requestSignal !== callerCtx.abortSignal) {
+    _abortSignals.push(callerCtx.requestSignal)
+  }
+  const _combinedSignal = _abortSignals.length > 1
+    ? AbortSignal.any(_abortSignals)
+    : (_abortSignals[0] || null)
+  const _ctxWithSignal = _combinedSignal
+    ? { ...callerCtx, abortSignal: _combinedSignal }
+    : callerCtx
+  const clearCeiling = () => { if (_ceilingTimer) clearTimeout(_ceilingTimer) }
+  return { ctxWithSignal: _ctxWithSignal, ceilingPromise: _ceilingPromise, clearCeiling }
+}
+
+async function dispatchTool(name, args, callerCtx = {}) {
+  const _t0 = Date.now()
+  const _id = `${process.pid}-${_callIdSeq++}`
+  // Diagnostic logging: every dispatch emits start + ok/error unconditionally
+  // so any hang is visible as start-without-ok in mcp-debug.log. Writes go
+  // direct to _logAppend, bypassing the pair-suppression wrapper.
+  _logAppend(_logLine(`[dispatch] start id=${_id} tool=${name}${_dispatchInputShape(name, args)}`))
+  if (name === 'bash') {
+    const cmd = String(args?.command || '')
+    if (cmd) {
+      const marker = _trackBashRecurrence(_shortHash(cmd), _t0)
+      if (marker) _logAppend(_logLine(marker))
+    }
+  }
+  // Transport safety ceiling, not a tool-efficiency classifier. `bash` owns
+  // its requested timeout; the dispatcher only adds grace so bash treeKill /
+  // persistent-shell cleanup can settle before the outer race rejects. Other
+  // tools keep a fixed ceiling to avoid orphaned dispatch slots.
+  const { ctxWithSignal: _ctxWithSignal, ceilingPromise: _ceilingPromise, clearCeiling: _clearCeiling } =
+    _buildDispatchCancellation(name, args, callerCtx)
+  // Central live-progress emit: when the caller threaded a progress reporter
+  // (MCP progressToken present), fire ONE per-tool start message here and mark
+  // the downstream ctx so executeBuiltinTool's fallback emit does not double up.
+  // No-op when ctxWithSignal.progress is null (no token) — reporter is null →
+  // not a function → path stays byte-identical to the no-progress behaviour.
+  let _ctxForImpl = _ctxWithSignal
+  if (typeof _ctxWithSignal.progress === 'function') {
+    try { _ctxWithSignal.progress(formatToolStartProgress(name, args)) } catch { /* progress is best-effort */ }
+    _ctxForImpl = { ..._ctxWithSignal, progressStarted: true }
+  }
+  try {
+    const _dispatchPromise = _dispatchToolImpl(name, args, _ctxForImpl)
+    const _result = _ceilingPromise
+      ? await Promise.race([_dispatchPromise, _ceilingPromise])
+      : await _dispatchPromise
+    _clearCeiling()
+    const elapsed = Date.now() - _t0
+    _logAppend(_logLine(`[dispatch] ok id=${_id} tool=${name} elapsed=${elapsed}ms`))
+    // App-level errors travel as strings (`Error [code N]: ...`) without
+    // raising — record them in tool-events.log so cross-session audits
+    // can find read/edit invariant failures by grep.
+    _recordToolApplicationError(name, _result)
+    return _result
+  } catch (err) {
+    _clearCeiling()
+    const msg = err instanceof Error ? err.message : String(err)
+    _logAppend(_logLine(`[dispatch] error id=${_id} tool=${name} elapsed=${Date.now() - _t0}ms msg=${msg.slice(0, 200)}`))
+    throw err
+  }
+}
+
+// Schema/lookup normalisation: tilde-expand a caller-supplied cwd once at
+// dispatch entry and resolve the tool definition. Throws the same
+// disabled-module vs unknown-tool error messages the inline branch did so
+// callers see no behaviour change.
+function _resolveDispatchToolDef(name, args) {
+  // Normalise caller-supplied `cwd` once at the entry so every downstream
+  // module (builtin / lsp / code_graph / patch / bash_session /
+  // host_input / agent) receives the expanded path. Previously only the
+  // agent ingresses (the unified `bridge` tool) ran tilde
+  // expansion, so explore / list / grep / glob with a `~` cwd silently
+  // fell back to process.cwd().
+  if (args && typeof args.cwd === 'string') args.cwd = _expandCwdTilde(args.cwd)
+  const def = TOOL_BY_NAME[name]
+  if (!def) {
+    // Distinguish "disabled module" from "unknown tool" so callers (and
+    // the Lead) get an actionable message instead of a generic miss.
+    const rawDef = RAW_TOOL_DEFS.find(t => t.name === name)
+    if (rawDef && rawDef.module && MODULE_NAMES.includes(rawDef.module) && !isModuleEnabled(rawDef.module)) {
+      throw new Error(`module '${rawDef.module}' is disabled — enable it in the setup UI (General → Modules) and restart the plugin`)
+    }
+    throw new Error(`Unknown tool: ${name}`)
+  }
+  return def
+}
+
+// recall / search bypass the ai-wrapped dispatcher entirely. Both are
+// pure mechanical fan-out (array → worker handleSearch array branch /
+// search-backend Promise.allSettled), so the LLM-routing scaffolding
+// (makeBridgeLlm import, ROLE_BY_TOOL lookup, recursion guard) that
+// ai-wrapped still ships for explore adds no value here. Inlining the
+// worker / backend call also lets recall's array branch keep the
+// embedTexts pre-warm path (worker, not Lead, runs the batch ONNX call)
+// intact: previously the Lead-side dispatcher fanned out into N
+// single-query callMemoryWorker requests, which forced the worker into
+// its single-flight inference queue and re-introduced the per-query
+// stagger the embed-batch patch was meant to fix.
+//
+// search now also subsumes web_fetch: pass `url` (string or array) to
+// route to the fetch backend, `query` (string or array) to route to the
+// search backend. Exactly one of the two must be supplied; mixing them
+// is a contract violation since the two backends produce different
+// result shapes.
+function _capSyncRetrievalBody(text) {
+  const bodyStr = typeof text === 'string' ? text : String(text ?? '')
+  const bodyBytes = Buffer.byteLength(bodyStr, 'utf8')
+  let bodyLines = bodyStr.length === 0 ? 0 : 1
+  for (let i = 0; i < bodyStr.length; i += 1) {
+    if (bodyStr.charCodeAt(i) === 10) bodyLines += 1
+  }
+  return smartReadTruncate(bodyStr, bodyLines, bodyBytes).text
+}
+
+// ② completion progress (claude "Found N" parity) for recall. Counts the
+// `#<id>` entry markers in the rendered body; best-effort, no-op when
+// callerCtx.progress is absent (no progressToken). Never throws.
+function _emitRecallProgress(callerCtx, body) {
+  if (typeof callerCtx?.progress !== 'function') return
+  try {
+    const _n = (String(body).match(/#\d+\b/g) || []).length
+    callerCtx.progress(`recalled ${_n} memories`)
+  } catch { /* best-effort */ }
+}
+
+async function _dispatchRecallOrSearch(name, args, callerCtx = {}) {
+  // MCP schema-less query/url field: some clients JSON-stringify arrays
+  // when the inputSchema does not declare an explicit `type`. Parse
+  // `'["a","b"]'` back into an array so fan-out works regardless of
+  // how the caller serialized the input.
+  const _maybeParseArray = (v) => {
+    if (typeof v !== 'string') return v
+    const trimmed = v.trim()
+    if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) return v
+    try {
+      const parsed = JSON.parse(trimmed)
+      return Array.isArray(parsed) ? parsed : v
+    } catch { return v }
+  }
+  const _toList = (v) => {
+    if (v == null) return []
+    if (Array.isArray(v)) return v.map(x => String(x ?? ''))
+    return [String(v ?? '')]
+  }
+  if (name === 'recall') {
+    const queries = _toList(_maybeParseArray(args?.query))
+    // id mode (follow-up lookup): a previous recall returned `#N`
+    // markers; passing them back here fetches the entry + its chunk
+    // members directly, no ranked lookup/search. Accepts a single number or
+    // array; strings are coerced. Mutually exclusive with `query`.
+    const rawId = _maybeParseArray(args?.id)
+    const idList = rawId == null
+      ? []
+      : (Array.isArray(rawId) ? rawId : [rawId])
+          .map(v => Number(v))
+          .filter(v => Number.isFinite(v) && v > 0)
+    if (queries.length === 0 && idList.length === 0) {
+      return { content: [{ type: 'text', text: '[recall] either `query` or `id` is required' }], isError: true }
+    }
+    if (queries.length > 0 && idList.length > 0) {
+      return { content: [{ type: 'text', text: '[recall] specify either `query` or `id`, not both' }], isError: true }
+    }
+    const passThrough = {}
+    if (args.period != null) passThrough.period = args.period
+    if (args.limit != null) passThrough.limit = args.limit
+    if (args.offset != null) passThrough.offset = args.offset
+    if (args.sort != null) passThrough.sort = args.sort
+    if (args.category != null) passThrough.category = args.category
+    if (args.includeMembers != null) passThrough.includeMembers = args.includeMembers
+    if (args.includeRaw != null) passThrough.includeRaw = args.includeRaw
+    if (args.includeArchived != null) passThrough.includeArchived = args.includeArchived
+    if (typeof args.projectScope === 'string' && args.projectScope) {
+      passThrough.projectScope = args.projectScope
+    } else {
+      passThrough.cwd = (typeof args.cwd === 'string' && args.cwd) ? args.cwd : (callerCtx.callerCwd || pwd())
+    }
+    if (idList.length > 0) {
+      const result = await callWorker('memory', 'memory', { action: 'search', ids: idList, ...passThrough })
+      const body = _capSyncRetrievalBody(result?.text ?? result?.content?.[0]?.text ?? '(no response)')
+      _emitRecallProgress(callerCtx, body)
+      return { content: [{ type: 'text', text: body }] }
+    }
+    // Single-query stays a string so the worker's single branch runs;
+    // multi-query goes in as an array so the worker's array branch runs
+    // (pre-warm embedTexts + Promise.all sub-search inside one process).
+    const queryArg = queries.length > 1 ? queries : queries[0]
+    const result = await callWorker('memory', 'memory', { action: 'search', query: queryArg, ...passThrough })
+    const body = _capSyncRetrievalBody(result?.text ?? result?.content?.[0]?.text ?? '(no response)')
+    _emitRecallProgress(callerCtx, body)
+    return { content: [{ type: 'text', text: body }] }
+  }
+  // search — query (text) vs url (fetch) mutually exclusive.
+  const queries = _toList(_maybeParseArray(args?.query !== undefined ? args.query : args?.keywords))
+  const urls = _toList(_maybeParseArray(args?.url))
+  if (queries.length === 0 && urls.length === 0) {
+    return { content: [{ type: 'text', text: '[search] either `query` or `url` is required' }], isError: true }
+  }
+  if (queries.length > 0 && urls.length > 0) {
+    return { content: [{ type: 'text', text: '[search] specify either `query` or `url`, not both' }], isError: true }
+  }
+  const { loadConfig: loadSearchConfig } = await import(
+    pathToFileURL(join(PLUGIN_ROOT, 'src/search/lib/config.mjs')).href,
+  )
+  const searchConfig = loadSearchConfig()
+  if (urls.length > 0) {
+    const searchMod = await loadModule('search')
+    const urlArg = urls.length > 1 ? urls : urls[0]
+    const result = await searchMod.handleToolCall('web_fetch', {
+      url: urlArg,
+      startIndex: args?.startIndex,
+      maxLength: args?.maxLength,
+    })
+    const body = _capSyncRetrievalBody(result?.text ?? result?.content?.[0]?.text ?? '(no response)')
+    // ② completion progress (claude "Found N" parity). callerCtx.progress is
+    // the central reporter; best-effort, no-op when absent (no progressToken).
+    if (typeof callerCtx.progress === 'function') {
+      try { callerCtx.progress(urls.length > 1 ? `fetched ${urls.length} URLs` : `fetched ${urls[0]}`) } catch { /* best-effort */ }
+    }
+    return { content: [{ type: 'text', text: body }], ...(result?.isError ? { isError: true } : {}) }
+  }
+  const searchMod = await loadModule('search')
+  const queryArg = queries.length > 1 ? queries : queries[0]
+  const result = await searchMod.handleToolCall('search', {
+    keywords: queryArg,
+    // Thread the per-call provider override through to the search module so
+    // an explicit `provider:"xai-api"` etc. on the public `search` tool is
+    // honoured instead of silently falling back to the configured default
+    // (searchArgsSchema in src/search/index.mjs already accepts this field).
+    provider: args?.provider,
+    site: args?.site,
+    type: args?.type,
+    locale: args?.locale,
+    maxResults: args?.maxResults || searchConfig?.rawSearch?.maxResults || 10,
+    contextSize: args?.contextSize,
+  })
+  const body = _capSyncRetrievalBody(result?.text ?? result?.content?.[0]?.text ?? '(no response)')
+  // ② completion progress (claude "Found N" parity). Count numbered result
+  // lines in the formatted body; best-effort, no-op when progress absent.
+  if (typeof callerCtx.progress === 'function') {
+    try {
+      const _n = (body.match(/^\s*\d+\.\s/gm) || []).length
+      callerCtx.progress(`found ${_n} results`)
+    } catch { /* best-effort */ }
+  }
+  return { content: [{ type: 'text', text: body }], ...(result?.isError ? { isError: true } : {}) }
+}
+
+// ai-wrapped dispatch: explore + any other tool flagged aiWrapped in
+// tools.json. Imports the dispatcher lazily so non-aiWrapped calls don't
+// pay the cost.
+async function _dispatchAiWrappedRoute(name, args, callerCtx) {
+  const { dispatchAiWrapped } = await import(
+    pathToFileURL(join(PLUGIN_ROOT, 'src/agent/orchestrator/ai-wrapped-dispatch.mjs')).href,
+  )
+  return dispatchAiWrapped(name, args ?? {}, {
+    PLUGIN_ROOT,
+    callMemoryWorker: (n, a) => callWorker('memory', n, a),
+    // Caller session id propagates from loop.mjs → executeInternalTool →
+    // toolExecutor → dispatchTool → dispatchAiWrapped. Used there to reject
+    // recursion when a hidden-role session (explorer / cycle1 / cycle2)
+    // tries to re-enter an aiWrapped dispatcher.
+    callerSessionId: callerCtx.callerSessionId,
+    callerCwd: callerCtx.callerCwd,
+    // A2: forward the MCP request signal so the sync fan-out can detect a
+    // harness sever of the transport. callerCtx.requestSignal is extra.signal
+    // from the CallTool handler (~2038) preserved through _ctxWithSignal's
+    // spread — it is the signal that fires AT the 120s harness ceiling (the
+    // transport tear-down). We forward requestSignal specifically, NOT the
+    // combined abortSignal, because the combined signal also folds in the
+    // plugin's own 630s ceiling (a different failure mode); requestSignal
+    // alone is the precise "transport severed" event the sync path must react
+    // to by pushing its finalized result through the channel instead of
+    // returning into a dead in-turn transport.
+    requestSignal: callerCtx.requestSignal,
+    // Push merged answer into the Lead session when a dispatch
+    // (wait:false) completes, so Lead integrates the result on its next
+    // turn via a channel notification (no polling tool exposed).
+    notifyFn: pushChannelNotification,
+    // Originating MCP session id (daemon routing). Distinct from callerSessionId
+    // (which gates the orchestrator-session guard); this only tags the
+    // dispatch_result so the daemon router delivers it to the dispatching
+    // terminal instead of broadcasting.
+    routingSessionId: callerCtx.callerSession?.sessionId,
+    clientHostPid: callerCtx.callerSession?.clientHostPid,
+  })
+}
+
+// Module-routed dispatch: builtin / code_graph / patch / host_input plus
+// the worker-IPC (memory, channels) and module.handleToolCall fallback
+// paths. Same early-return order as the inline branches it replaces.
+async function _dispatchByModule(name, args, callerCtx, def) {
+  if (def.module === 'builtin') {
+    // Plugin builtin file tools exposed to external MCP clients (e.g. the
+    // Lead / Claude Code harness). Write semantics live inside executeBuiltinTool.
+    const { executeBuiltinTool } = await import(
+      pathToFileURL(join(PLUGIN_ROOT, 'src/agent/orchestrator/tools/builtin.mjs')).href,
+    )
+    const effectiveCwd = (typeof args?.cwd === 'string' && args.cwd) ? args.cwd : (callerCtx.callerCwd || pwd())
+    // Read-state / persistent-shell scope id precedence (NOT the recursion-guard
+    // callerSessionId — that must stay null for Lead-direct so the orchestrator
+    // guard does not fail closed): orchestrator session (bridge worker) > the
+    // dispatching TERMINAL's session (per-connection daemon Session) > the
+    // process-global SESSION_ID (stdio bootSession). The terminal tier is what
+    // isolates each daemon terminal's `read` snapshots and `__default__<sid>`
+    // persistent bash; without it all terminals shared one global scope and
+    // tripped cross-session "file unchanged" stubs and a shared shell.
+    const scopeSessionId = callerCtx.callerSessionId ?? callerCtx.callerSession?.sessionId ?? SESSION_ID
+    // Live-progress reporter (MCP notifications/progress). Threaded only when
+    // the client supplied a progressToken; null otherwise so the path stays
+    // byte-identical to the no-progress behaviour.
+    // Background-job completion push: the `bash` run_in_background path arms an
+    // in-process watcher that calls notifyFn once the job finishes, mirroring
+    // the explore-tool dispatch_result mechanism. Thread the same notify ctx
+    // (notifyFn + daemon-routing identity) the aiWrapped dispatcher receives so
+    // the completion result routes back to the dispatching terminal.
+    const text = await executeBuiltinTool(name, args ?? {}, effectiveCwd, {
+      sessionId: scopeSessionId,
+      abortSignal: callerCtx.abortSignal ?? null,
+      onProgress: callerCtx.progress ?? null,
+      progressStarted: callerCtx.progressStarted === true,
+      notifyFn: pushChannelNotification,
+      routingSessionId: callerCtx.callerSession?.sessionId,
+      clientHostPid: callerCtx.callerSession?.clientHostPid,
+    })
+    // Image-aware `read` returns a pre-built MCP result ({content:[{type:'image',...}]}).
+    // Pass any such object through untouched; only string results get text-wrapped
+    // (String()-flattening an object yields "[object Object]" and drops the image).
+    if (text && typeof text === 'object' && Array.isArray(text.content)) return text
+    return { content: [{ type: 'text', text: String(text) }] }
+  }
+
+  if (def.module === 'code_graph') {
+    const { executeCodeGraphTool } = await import(
+      pathToFileURL(join(PLUGIN_ROOT, 'src/agent/orchestrator/tools/code-graph.mjs')).href,
+    )
+    let resolvedName = name
+    const resolvedArgs = args ?? {}
+    if (name === 'find_symbol' && resolvedArgs.mode && resolvedArgs.mode !== 'symbol') {
+      const m = resolvedArgs.mode
+      if (m === 'callers') resolvedName = 'find_callers'
+      else if (m === 'references') resolvedName = 'find_references'
+      else if (m === 'imports') resolvedName = 'find_imports'
+      else if (m === 'dependents') resolvedName = 'find_dependents'
+      else resolvedName = 'code_graph'
+    }
+    const text = await executeCodeGraphTool(resolvedName, resolvedArgs, callerCtx.callerCwd || pwd(), callerCtx.abortSignal ?? null)
+    // ② completion progress (claude "Found N" parity). Best-effort, no-op
+    // when callerCtx.progress is absent (no progressToken). Never throws —
+    // the tool result is returned regardless.
+    if (typeof callerCtx.progress === 'function') {
+      try {
+        const _mode = String(resolvedArgs?.mode || '').trim()
+          || (resolvedName === 'find_callers' ? 'callers'
+            : resolvedName === 'find_references' ? 'references' : '')
+        const _fileArg = (typeof resolvedArgs?.file === 'string' && resolvedArgs.file.trim()) ? resolvedArgs.file.trim() : ''
+        const _countLocLines = (t) => (String(t).match(/^[^\n]*?:\d+:\d+/gm) || []).length
+        let _msg = null
+        if (_mode === 'callers') _msg = `found ${_countLocLines(text)} callers`
+        else if (_mode === 'references') _msg = `found ${_countLocLines(text)} references`
+        else if (_mode === 'search') {
+          const _m = /\bmatches=(\d+)/.exec(String(text))
+          _msg = `found ${_m ? _m[1] : 0} symbols`
+        } else if (_fileArg) _msg = `mapped ${_fileArg}`
+        if (_msg) callerCtx.progress(_msg)
+      } catch { /* best-effort */ }
+    }
+    return { content: [{ type: 'text', text: String(text) }] }
+  }
+
+  if (def.module === 'patch') {
+    // Unified-diff apply tool. One-turn multi-file
+    // edits without Read-before-Edit (the patch's context lines are the
+    // read-proof). Mtime-guarded
+    // against concurrent writes. See src/agent/orchestrator/tools/patch.mjs.
+    const { executePatchTool } = await import(
+      pathToFileURL(join(PLUGIN_ROOT, 'src/agent/orchestrator/tools/patch.mjs')).href,
+    )
+    // Same scope-id precedence as the builtin path above: orchestrator session
+    // > dispatching terminal session > process-global SESSION_ID. Keeps each
+    // terminal's mtime read-state isolated without touching the recursion-guard
+    // callerSessionId.
+    const sessionId = callerCtx.callerSessionId ?? callerCtx.callerSession?.sessionId ?? SESSION_ID
+    const text = await executePatchTool(name, args ?? {}, callerCtx.callerCwd || pwd(), {
+      sessionId,
+      readStateScope: sessionId,
+      abortSignal: callerCtx.abortSignal ?? null,
+      onProgress: callerCtx.progress ?? null,
+    })
+    return { content: [{ type: 'text', text: String(text) }] }
+  }
+
+  if (def.module === 'host_input') {
+    // Host-terminal input injection. Walks the parent chain from this Node
+    // process, finds the first ancestor matching a supported terminal host
+    // (currently powershell.exe / pwsh.exe), and replays the supplied text
+    // into its console via AttachConsole + WriteConsoleInputW. Reuses the
+    // proven dev/scripts/inject-input.ps1 helper.
+    // See src/agent/orchestrator/tools/host-input.mjs.
+    const { executeHostInputTool } = await import(
+      pathToFileURL(join(PLUGIN_ROOT, 'src/agent/orchestrator/tools/host-input.mjs')).href,
+    )
+    const text = await executeHostInputTool(name, args ?? {}, callerCtx.callerCwd || pwd())
+    return { content: [{ type: 'text', text: String(text) }] }
+  }
+
+  if (def.module === 'cwd') {
+    // Session-cwd tool. Backed by process.env.MIXDOG_SESSION_CWD, which
+    // captureOriginalUserCwd() consults first — so a successful `set`
+    // immediately changes pwd() for every downstream tool dispatch.
+    // See src/agent/orchestrator/tools/cwd-tool.mjs.
+    const { executeCwdTool } = await import(
+      pathToFileURL(join(PLUGIN_ROOT, 'src/agent/orchestrator/tools/cwd-tool.mjs')).href,
+    )
+    const text = await executeCwdTool(name, args ?? {}, callerCtx.callerCwd || pwd(), { session: callerCtx.callerSession })
+    return { content: [{ type: 'text', text: String(text) }] }
+  }
+
+  const moduleName = def.module
+
+  if (moduleName === 'memory' || moduleName === 'channels') {
+    return callWorker(moduleName, name, args ?? {})
+  }
+
+  const mod = await loadModule(moduleName)
+  if (moduleName === 'agent') {
+    // Merge shared agent context with the per-request abort signal so the
+    // bridge handler can tear down its async IIFE on client-side cancel.
+    // Forward callerCwd from the MCP dispatch frame so the bridge handler
+    // (src/agent/index.mjs:875) can resolve the worker cwd from the Lead's
+    // current working directory instead of falling back to a stale frozen
+    // user-cwd.txt or process.cwd().
+    const ctx = agentContext()
+    if (callerCtx?.requestSignal) ctx.requestSignal = callerCtx.requestSignal
+    if (callerCtx?.callerCwd) ctx.callerCwd = callerCtx.callerCwd
+    // Tag the dispatching MCP session so a detached bridge worker's result
+    // routes back to THIS terminal (daemon router), not the Lead connection.
+    if (callerCtx?.callerSession?.sessionId) ctx.routingSessionId = callerCtx.callerSession.sessionId
+    if (typeof callerCtx?.callerSession?.clientHostPid === 'number' && callerCtx.callerSession.clientHostPid > 0) {
+      ctx.clientHostPid = callerCtx.callerSession.clientHostPid
+    }
+    return mod.handleToolCall(name, args ?? {}, ctx)
+  }
+  return mod.handleToolCall(name, args ?? {})
+}
+
+async function _dispatchToolImpl(name, args, callerCtx = {}) {
+  const def = _resolveDispatchToolDef(name, args)
+  if (name === 'recall' || name === 'search') {
+    return _dispatchRecallOrSearch(name, args, callerCtx)
+  }
+  if (def.aiWrapped) {
+    return _dispatchAiWrappedRoute(name, args, callerCtx)
+  }
+  return _dispatchByModule(name, args, callerCtx, def)
+}
+
+// ── Handlers ────────────────────────────────────────────────────────
+const ALWAYS_LOAD_TOOLS = new Set([
+  'read', 'bash', 'grep', 'bridge', 'list',
+  'glob', 'recall', 'code_graph', 'explore', 'write', 'search',
+  // R1-reviewer follow-up: Decision Table first-tools that were deferred —
+  // apply_patch is the multi-file atomic edit primitive, job_wait the wait
+  // hook for run_in_background. Both deserve always-loaded status by usage.
+  'apply_patch', 'job_wait',
+  // Session-cwd controls — always loaded so a Lead can rebase the working
+  // directory without paying a manifest-fetch round trip first.
+  'cwd',
+])
+
+const COMPACT_INPUT_SCHEMA_DESCRIPTION_TOOLS = new Set([
+  'read', 'grep', 'list', 'recall', 'code_graph', 'apply_patch',
+])
+
+function stripSchemaDescriptions(value) {
+  if (!value || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map(stripSchemaDescriptions)
+  const out = {}
+  for (const [key, child] of Object.entries(value)) {
+    if (key === 'description') continue
+    out[key] = stripSchemaDescriptions(child)
+  }
+  return out
+}
+
+function toListToolDef(tool) {
+  const out = ALWAYS_LOAD_TOOLS.has(tool.name)
+    ? { ...tool, _meta: { ...(tool._meta || {}), 'anthropic/alwaysLoad': true } }
+    : tool
+  if (!COMPACT_INPUT_SCHEMA_DESCRIPTION_TOOLS.has(tool.name)) return out
+  return {
+    ...out,
+    inputSchema: stripSchemaDescriptions(out.inputSchema),
+  }
+}
+
+// Precompute ListTools response once at boot (TOOL_DEFS and ALWAYS_LOAD_TOOLS
+// are static after module init; rebuilding the spread on every request is waste).
+const LIST_TOOLS_RESPONSE = {
+  tools: TOOL_DEFS.map(toListToolDef),
+}
+server.setRequestHandler(ListToolsRequestSchema, async () => LIST_TOOLS_RESPONSE)
+
+// Lazy-loaded result-compression module so the boot path doesn't pay the
+// cost of importing bridge-trace + dependencies until the first tool call.
+let _compressionModule = null
+async function _getCompressionModule() {
+  if (!_compressionModule) {
+    _compressionModule = await import(
+      pathToFileURL(join(PLUGIN_ROOT, 'src/agent/orchestrator/tools/result-compression.mjs')).href,
+    )
+  }
+  return _compressionModule
+}
+
+let _leadDirectOutputSeq = 0
+// Skip compress/trim post-processing for small MCP tool bodies (fast path).
+const LEAD_DIRECT_POST_COMPRESS_MIN_BYTES = 4 * 1024
+function _saveLeadDirectFullOutput(toolName, text) {
+  const safeTool = String(toolName || 'tool').replace(/[^A-Za-z0-9_-]+/g, '_').slice(0, 40) || 'tool'
+  const dir = join(PLUGIN_DATA, 'tool-results', 'lead-direct')
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, `${Date.now()}-${process.pid}-${++_leadDirectOutputSeq}-${safeTool}.txt`)
+  writeFileAsync(file, text, 'utf8').catch((err) => log(`[compress] full-output save failed tool=${toolName} msg=${err?.message || err}`))
+  return file
+}
+
+// Memory-family tools carry session_id as an inline arg so the memory worker's
+// HTTP handlers can persist / filter by it without a separate IPC channel.
+// Non-memory tools see args unchanged — extra fields would noisily mismatch
+// strict schemas (e.g. bash, glob).
+const MEMORY_FAMILY_TOOLS = new Set(['memory', 'search_memories', 'recall'])
+
+// Boot session = today's single stdio client. cwdFn=pwd keeps it tracking the
+// live MIXDOG_SESSION_CWD env, so this path is behaviour-identical to the
+// pre-Session code. The daemon entry creates one Session per connection.
+const bootSession = new Session(null, {
+  sessionId: SESSION_ID,
+  cwdFn: pwd,
+  setCwdFn: (v) => { process.env.MIXDOG_SESSION_CWD = v },
+})
+
+// Shared tool-call body for both the stdio entry (bootSession) and the daemon
+// per-connection entry. Identity (sessionId) and cwd come from `session` and
+// thread through dispatchTool's callerCtx, which every route already honours.
+// Build a monotonic MCP progress reporter from a CallTool `extra`. Returns
+// null when the client did not subscribe (no progressToken) so downstream
+// tools take their existing no-progress path unchanged. The reporter is a
+// fire-and-forget async function; notifications carry no `id` and the SDK
+// stamps relatedRequestId so the daemon/run-mcp layers route the frame back
+// to the originating connection.
+function _buildProgressReporter(progressCtx) {
+  const token = progressCtx?._meta?.progressToken
+  const sendNotification = progressCtx?.sendNotification
+  if (token === undefined || token === null || typeof sendNotification !== 'function') return null
+  let _seq = 0
+  return (message) => {
+    const progress = ++_seq
+    try {
+      const r = sendNotification({
+        method: 'notifications/progress',
+        params: { progressToken: token, progress, message: String(message ?? '') },
+      })
+      if (r && typeof r.catch === 'function') r.catch(() => {})
+    } catch { /* progress is best-effort — never disturb the tool result */ }
+  }
+}
+
+async function runToolCall(session, name, rawArgs, requestSignal, progressCtx = null) {
+  const _entryT = Date.now()
+  const args = MEMORY_FAMILY_TOOLS.has(name) && rawArgs && typeof rawArgs === 'object'
+    ? { ...rawArgs, sessionId: rawArgs.sessionId ?? session.sessionId }
+    : rawArgs
+  // Log absolute entry timestamp so we can compare against the caller's
+  // emit timestamp (passed via args._mcpEmitTs if instrumented) to size the
+  // Claude-Code → plugin transport window — currently the largest opaque
+  // segment in the per-call cost stack.
+  log(`[mcp-entry] tool=${name} t=${_entryT}`)
+  // `extra.signal` is an AbortSignal that fires when the MCP client cancels
+  // this request (e.g. user rejects / interrupts a tool call in Claude Code).
+  // Thread it down so long-running tools — specifically the async IIFE the
+  // `bridge` tool spawns to run askSession — can close their session and
+  // stop hitting the provider after the user bails out.
+  //
+  // `callerCwd` defaults to the mixdog server's own working directory so
+  // tools that take a cwd fallback (notably the unified `bridge` tool) can
+  // resolve to a valid plugin path when the caller did not explicitly pass
+  // one. Callers can still override with an explicit `cwd` argument.
+  // Telemetry: dispatchTool's outer wrapper handles start/end/error logs
+  // for both this MCP call path and the in-process toolExecutor path.
+  // MCP live-progress reporter. The SDK auto-allocates extra._meta.progressToken
+  // when the client passes an onprogress callback to callTool and exposes
+  // extra.sendNotification bound to this request (relatedRequestId set). We
+  // build a monotonic-progress reporter ONLY when a token is present, so a
+  // client that did not subscribe sees byte-identical behaviour (no emits).
+  const _progressReporter = _buildProgressReporter(progressCtx)
+  const _postT0 = Date.now()
+  const result = await dispatchTool(name, args, {
+    requestSignal,
+    callerSession: session,
+    callerCwd: session.resolveCwd(),
+    progress: _progressReporter,
+  })
+  const _postT1 = Date.now()
+  // Apply the same chained safe-compression + trim passes the bridge role loop
+  // runs (loop.mjs:1105). Without this, Lead-direct tool calls bypassed every
+  // RTK-class lossless reduction (CR overwrite, NUL/BOM strip, trailing
+  // newline normalize, ANSI/whitespace/dup/separator). compressToolResult
+  // is gated on annotations.compressible per tool definition, so non-
+  // compressible tools (read/etc) pass through untouched. Final expand
+  // guard inside compressToolResult returns the original on no-shrink.
+  // tailTrimLargeOutput adds RTK-style long-line and head/tail caps so one
+  // huge minified line cannot stall the MCP stdout path.
+  // sessionId='lead-direct' (sentinel) lets traceBridgeCompress fire on
+  // this path too — without it the compress trace skipped Lead-direct
+  // entirely and PG aggregates only saw bridge role loop activity.
+  try {
+    const { compressToolResult, tailTrimLargeOutput } = await _getCompressionModule()
+    const rawText = result?.content?.[0]?.text
+    if (typeof rawText === 'string' && Buffer.byteLength(rawText, 'utf8') >= LEAD_DIRECT_POST_COMPRESS_MIN_BYTES) {
+      const _before = rawText.length
+      let nextText = compressToolResult(name, args, rawText, { sessionId: 'lead-direct', toolKind: null })
+      // `read` output is consumed sequentially — head-only trim with a
+      // continue hint instead of head+tail (which destroys the middle of a
+      // deliberately windowed read).
+      const _seq = name === 'read'
+      const trimmedCandidate = tailTrimLargeOutput(nextText, { trimLongLines: true, sequential: _seq })
+      if (trimmedCandidate !== nextText) {
+        const fullOutputPath = _saveLeadDirectFullOutput(name, rawText)
+        if (fullOutputPath) {
+          nextText = tailTrimLargeOutput(nextText, { fullOutputPath, sequential: _seq })
+        }
+      }
+      if (nextText !== rawText) {
+        result.content[0].text = nextText
+        const _saved = _before - nextText.length
+        const _pct = _before > 0 ? Math.round((_saved / _before) * 100) : 0
+        log(`[compress] tool=${name} ${_before}→${nextText.length} bytes saved=${_pct}%`)
+      }
+    }
+  } catch { /* compression best-effort — never block a tool result */ }
+  const _postT3 = Date.now()
+  log(`[mcp-post] tool=${name} dispatch=${_postT1 - _postT0}ms post=${_postT3 - _postT1}ms total=${_postT3 - _postT0}ms`)
+  return result
+}
+
+server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+  return runToolCall(bootSession, req.params.name, req.params.arguments, extra?.signal, extra)
+})
+
+// ── Memory worker — start before MCP handshake so it boots in parallel ─────
+const memoryOn = isModuleEnabled('memory')
+const channelsOn = isModuleEnabled('channels')
+if (memoryOn) spawnWorker('memory')
+else log(`module 'memory' disabled — skipping worker spawn`)
+
+// ── Daemon mode: serve N Claude Code clients over one shared pipe ───────────
+// Each connection gets its own MCP SDK Server bound to a FramedServerTransport,
+// so the SDK does protocol-correct initialize/tools negotiation per client
+// while a per-connection Session carries identity (sessionId/cwd) into
+// runToolCall. The memory/channels workers booted in this process are SINGLE
+// shared services — the point of the daemon. Replaces the per-terminal stdio
+// server + fork-proxy/election model (deleted at cutover).
+async function serveDaemon(dataDir) {
+  daemonNotifyRouter = daemonNotifyRouter || createDaemonNotifyRouter()
+  const reg = new SessionRegistry()
+  const srv = await daemonListen({
+    dataDir,
+    onConnection(conn) {
+      const session = reg.open(conn, { sessionId: randomUUID() })
+      const perConn = new Server(
+        { name: 'mixdog', version: PLUGIN_VERSION },
+        {
+          capabilities: { tools: {}, experimental: { 'claude/channel': {}, 'claude/channel/permission': {} } },
+          instructions: SERVER_INSTRUCTIONS,
+        },
+      )
+      perConn.setRequestHandler(ListToolsRequestSchema, async () => LIST_TOOLS_RESPONSE)
+      perConn.setRequestHandler(CallToolRequestSchema, async (req, extra) =>
+        runToolCall(session, req.params.name, req.params.arguments, extra?.signal, extra))
+      // Channel permission requests: forward to the shared channels worker and
+      // record request_id → this connection so the worker's response routes back
+      // here (the daemon notify router). Each connection registers its own.
+      perConn.setNotificationHandler(ChannelPermissionRequestNotificationSchema, async (notification) => {
+        const reqId = notification?.params?.request_id
+        const forwarded = forwardChannelPermissionRequest(notification.params, (n) => perConn.notification(n).catch(() => {}))
+        // Track for response routing ONLY if it reached the worker; a local
+        // deny already replied directly, so registering would leak in byReq.
+        if (forwarded && reqId) daemonNotifyRouter.registerPermissionRequest(reqId, perConn)
+      })
+      // Track the connection + its Session so the router can resolve the
+      // active-instance owner (channel events) and the dispatching session
+      // (worker results). Register the bootstrap session id now so a dispatch
+      // that completes before the control frame still routes correctly; the
+      // control-frame handler below swaps in the real MIXDOG_SESSION_ID.
+      daemonNotifyRouter.add(perConn, session)
+      daemonNotifyRouter.registerSession(session.sessionId, perConn)
+      // Register cleanup immediately after the registry/router entries exist,
+      // before any further (throwable) transport setup — otherwise an
+      // exception mid-setup leaks this session/router registration.
+      conn.onClose(() => { daemonNotifyRouter.remove(perConn); reg.close(conn) })
+      // Session identity arrives out-of-band as a `__mixdog` control frame,
+      // filtered by FramedServerTransport before the SDK (no dependency on the
+      // MCP initialize ordering).
+      const transport = new FramedServerTransport(conn, {
+        onControl(msg) {
+          if (msg.__mixdog !== 'session') return
+          let priorSid = null
+          if (msg.sessionId) {
+            priorSid = session.sessionId
+            session.sessionId = String(msg.sessionId)
+            // Register sessionId → this connection so async dispatch results
+            // (bridge/explore) route back to this terminal instead of broadcasting.
+            daemonNotifyRouter.registerSession(session.sessionId, perConn)
+          }
+          const _advertisedCwd = typeof msg.cwd === 'string' && msg.cwd ? msg.cwd : null
+          const _restoredCwd = !_advertisedCwd && Number.isFinite(msg.leadPid) ? readLastSessionCwd(msg.leadPid) : null
+          if (_advertisedCwd) session.cwd = _advertisedCwd
+          else if (_restoredCwd) session.cwd = _restoredCwd
+          if (typeof msg.transcriptPath === 'string') session.transcriptPath = msg.transcriptPath
+          if (typeof msg.clientHostPid === 'number' && msg.clientHostPid > 0) session.clientHostPid = msg.clientHostPid
+          if (Number.isFinite(msg.leadPid)) session.leadPid = msg.leadPid
+          if (msg.instanceId) session.instanceId = String(msg.instanceId)
+          // Reconnect recovery must use the same stable terminal key as
+          // notification routing. MIXDOG_SESSION_ID is often absent, so
+          // sessionId-only replay misses pending results from a prior bootstrap
+          // UUID; clientHostPid lets the reattached terminal reclaim them.
+          import('./src/agent/orchestrator/dispatch-persist.mjs')
+            .then(({ recoverPending }) => recoverPending(PLUGIN_DATA, pushChannelNotification, {
+              sessionId: session.sessionId,
+              ...(priorSid && priorSid !== session.sessionId ? { priorSessionId: priorSid } : {}),
+              ...(Number(session.clientHostPid) > 0 ? { clientHostPid: session.clientHostPid } : {}),
+            }))
+            .catch(() => {})
+        },
+      })
+      perConn.connect(transport)
+        .catch((e) => log(`[daemon] connection setup failed: ${e?.message || e}`))
+    },
+  })
+  if (!srv) {
+    // Another daemon already owns the pipe (host owner-lock handoff race).
+    log('[daemon] pipe already owned — exiting')
+    process.exit(0)
+  }
+  globalThis.__mixdogServerReady = true
+  log(`[daemon] serving pid=${process.pid} dataDir=${dataDir} tools=${TOOL_DEFS.length}`)
+}
+
+// ── Transport — connect so the MCP host can send its first tool call ────────
+if (process.argv.includes('--daemon') || process.env.MIXDOG_DAEMON_MODE === '1') {
+  await serveDaemon(process.env.MIXDOG_DAEMON_DATA_DIR || PLUGIN_DATA)
+} else {
+  await server.connect(new StdioServerTransport())
+}
+// Signal to server.mjs's prelude uncaught guards that the MCP transport is
+// live: from this point a soft-net log-only policy is safe because the
+// post-load classifier (FATAL_CODES + FATAL_NAME_PATTERNS) owns the exit
+// decision. Anything thrown before this flag flips still routes through the
+// prelude's pre-ready branch and exit(1) so the supervisor restarts.
+globalThis.__mixdogServerReady = true
+log(`connected pid=${process.pid} v${PLUGIN_VERSION} tools=${TOOL_DEFS.length}`)
+
+// ── Background hydration (fire-and-forget after connect) ────────────────────
+// Agent registry — background; handleToolCall falls back to
+// setInternalToolsProvider lazily if a call arrives before this resolves.
+;(async () => {
+  if (!isModuleEnabled('agent')) {
+    log(`module 'agent' disabled — skipping eager init, bridge tools will not register`)
+    return
+  }
+  try {
+  await loadModule('agent').then(async () => {
+    // Populate the in-process tool registry at boot so ALL session entry
+    // points (direct createSession / resumeSession, not just handleToolCall)
+    // see the bridge from the first call. handleToolCall still calls
+    // setInternalToolsProvider as an idempotent fallback, but we no longer
+    // rely on a tool call arriving first.
+    try {
+      const internalToolsMod = await import(
+        pathToFileURL(join(PLUGIN_ROOT, 'src', 'agent', 'orchestrator', 'internal-tools.mjs')).href
+      )
+      const { setInternalToolsProvider, markBootReady } = internalToolsMod
+      const ctx = agentContext()
+      setInternalToolsProvider({ executor: ctx.toolExecutor, tools: ctx.internalTools })
+
+      markBootReady()
+      log(`internal-tools registry populated tools=${ctx.internalTools.length}`)
+      // Windows-only: request Defender exclusion for hot IO paths, but keep
+      // the synchronous PowerShell preference probe out of the SessionStart
+      // boot path. The check is advisory and rate-limited; delaying it avoids
+      // holding the MCP parent event loop while cycle1/core/recap are trying
+      // to answer the startup hooks.
+      const defenderTimer = setTimeout(() => {
+        try { maybeRequestDefenderExclusion(PLUGIN_DATA, log) }
+        catch (e) { log(`[defender] check failed: ${e.message}`) }
+      }, 30_000)
+      defenderTimer.unref?.()
+    } catch (e) {
+      log(`internal-tools registry populate failed: ${e.message}`)
+    }
+  })
+  } catch (e) { log(`eager agent init failed: ${e.message}`) }
+})()
+
+// ── Spawn workers: channels (gated on memory) ───────────────────────
+// Hoisted to register at the head of the setImmediate FIFO so the
+// channels fork lands ahead of the rules-watcher and status-fork
+// setImmediates registered later in this file. `reconcileClaudeMd`
+// is a function declaration, so it's hoisted and safe to reference
+// here even though its source location is below.
+setImmediate(() => {
+  if (!channelsOn) {
+    log(`module 'channels' disabled — skipping worker spawn`)
+    // CLAUDE.md reconcile is driven by channels/injection config; when
+    // channels is off we still reconcile once so managed blocks stay in
+    // sync with the current mode.
+    reconcileClaudeMd()
+    return
+  }
+  // Channels worker issues callWorker('memory', ...) for inbound routing
+  // and recall. With memory disabled there is no memory worker entry, so
+  // those calls would hang for WORKER_NO_ENTRY_GRACE_MS then reject. Gate
+  // channels start on memory availability to match the lifecycle comment
+  // ("channels (gated on memory)") above.
+  if (!memoryOn) {
+    log(`module 'channels' enabled but 'memory' disabled — skipping channels worker spawn (channels depends on memory)`)
+    reconcileClaudeMd()
+    return
+  }
+
+  reconcileClaudeMd()
+  log('[server] channels spawn reason=parallel-with-memory')
+  spawnWorker('channels')
+})
+
+// ── Deferred: search eager-load + dispatch recovery ────────────────
+// Both are fire-and-forget after channels-spawn is enqueued so they
+// don't sit on the boot critical path. Search eager-load only avoids
+// the first-call JIT cost; dispatch recovery emits Aborted
+// notifications for orphaned handles from a prior process death.
+if (isModuleEnabled('search')) {
+  const searchWarmupTimer = setTimeout(() => {
+    loadModule('search').catch(e => log(`eager search init failed: ${e.message}`))
+  }, 15_000)
+  searchWarmupTimer.unref?.()
+} else {
+  log(`module 'search' disabled — skipping eager init`)
+}
+
+setImmediate(() => {
+  const IS_DAEMON = process.argv.includes('--daemon') || process.env.MIXDOG_DAEMON_MODE === '1'
+  if (IS_DAEMON) return
+  import('./src/agent/orchestrator/dispatch-persist.mjs')
+    .then(({ recoverPending }) => {
+      const recovered = recoverPending(PLUGIN_DATA, pushChannelNotification)
+      if (recovered > 0) log(`dispatch-recovery: emitted ${recovered} Aborted notifications`)
+    })
+    .catch((err) => {
+      log(`dispatch-recovery failed: ${err instanceof Error ? err.message : String(err)}`)
+    })
+})
+
+// ── CLAUDE.md managed block reconciliation ─────────────────────────
+// Writes static rules into the managed block. Session recap is NOT
+// written here — the SessionStart hook injects it live from the memory worker.
+// Fail-soft: any error is logged and swallowed.
+//
+//   mode === 'claude_md'  → upsert the managed block (strong enforcement)
+//   mode === 'hook' (default or missing) → remove any stale managed block
+// Shared loader for the two CLAUDE.md sites (boot-time reconcile +
+// live watcher): reads the channels section once, derives the injection
+// target, and require()s the rules-builder / writer pair. Returning the
+// same shape from a single helper avoids the duplicated readSection +
+// createRequire + require() pair at the original two call sites.
+function _readClaudeMdInjection() {
+  const mainConfig = readSection('channels')
+  const injection = (mainConfig && mainConfig.promptInjection) || {}
+  return { injection }
+}
+
+function _loadClaudeMdWriters() {
+  const req = createRequire(import.meta.url)
+  const { buildInjectionContent } = req(join(PLUGIN_ROOT, 'lib', 'rules-builder.cjs'))
+  const { upsertManagedBlock, removeManagedBlock, expandHome } = req(join(PLUGIN_ROOT, 'lib', 'claude-md-writer.cjs'))
+  return { buildInjectionContent, upsertManagedBlock, removeManagedBlock, expandHome }
+}
+
+function reconcileClaudeMd() {
+  try {
+    const { injection } = _readClaudeMdInjection()
+    if (injection.mode !== 'claude_md') {
+      // hook/non-claude_md mode: load writers lazily only to remove any
+      // stale managed block, matching original early-return semantics
+      // (no require + no targetPath derivation until after the mode check).
+      const { removeManagedBlock, expandHome } = _loadClaudeMdWriters()
+      const targetPath = injection.targetPath || '~/.claude/CLAUDE.md'
+      const removed = removeManagedBlock(targetPath)
+      if (removed) log(`hook mode: removed stale managed block from ${expandHome(targetPath)}`)
+      return
+    }
+
+    const targetPath = injection.targetPath || '~/.claude/CLAUDE.md'
+    const { buildInjectionContent, upsertManagedBlock, expandHome } = _loadClaudeMdWriters()
+    const content = buildInjectionContent({ PLUGIN_ROOT, DATA_DIR: PLUGIN_DATA })
+    upsertManagedBlock(targetPath, content)
+    log(`claude_md: wrote managed block to ${expandHome(targetPath)} (${content.length} chars)`)
+  } catch (e) {
+    log(`claude_md reconcile failed: ${e && (e.stack || e.message) || e}`)
+  }
+}
+
+// ── CLAUDE.md managed block live watcher ───────────────────────────
+// After boot-time reconcile, watch the rules/config sources and rebuild
+// the managed block in-place whenever they change. Keeps the disk copy
+// of CLAUDE.md in sync so the next session start always sees the latest
+// rules, even if the user edited mid-session.
+//
+// Only active when injection.mode === 'claude_md'. In hook mode this is
+// a no-op (hook mode regenerates on every prompt anyway).
+//
+// All errors are contained: per-watcher try/catch plus an outer try/catch
+// so watcher setup failure never crashes the MCP server.
+setImmediate(() => {
+  try {
+    const { injection } = _readClaudeMdInjection()
+    if (injection.mode !== 'claude_md') return
+
+    // Initial target snapshot used only for the watcher's own exclude
+    // check (don't recurse on our own writes). The rebuild callback
+    // re-reads mode/targetPath on every fire so a runtime config change
+    // (mode flip to hook, or targetPath move) is honored instead of
+    // upserting into the stale snapshot.
+    const initialTargetPath = injection.targetPath || '~/.claude/CLAUDE.md'
+    const { buildInjectionContent, upsertManagedBlock, expandHome } = _loadClaudeMdWriters()
+    const resolvedTarget = pathResolve(expandHome(initialTargetPath))
+
+    // Track every target path we have ever written a managed block to
+    // during this process's lifetime so an A→B→C reconfiguration removes
+    // the block from BOTH A and B before writing C. Tracking only the
+    // initial target left a stale block on intermediate hops because the
+    // watcher always compared `currentTargetPath` against `initialTargetPath`.
+    // Keyed by expandHome()-resolved absolute path so two spellings of
+    // the same file (`~/.claude/CLAUDE.md` vs the expanded form) collapse.
+    const writtenTargets = new Map() // resolvedAbs -> originalPath (for log + remove)
+    writtenTargets.set(pathResolve(expandHome(initialTargetPath)), initialTargetPath)
+
+    let debounceTimer = null
+    const rebuild = triggerFilename => {
+      if (debounceTimer) clearTimeout(debounceTimer)
+      debounceTimer = setTimeout(() => {
+        debounceTimer = null
+        try {
+          // Re-read injection on every fire so mode/target changes in
+          // mixdog-config.json take effect immediately instead of writing
+          // to the original target captured at setup time.
+          const { injection: currentInjection } = _readClaudeMdInjection()
+          const currentTargetPath = currentInjection.targetPath || '~/.claude/CLAUDE.md'
+          const resolvedCurrent = pathResolve(expandHome(currentTargetPath))
+          if (currentInjection.mode !== 'claude_md') {
+            // Mode flipped (e.g. claude_md → hook): remove any managed
+            // block from EVERY target we have ever written to during this
+            // session so we don't leave stale injection on disk at any
+            // prior hop in an A→B→C chain.
+            const { removeManagedBlock } = _loadClaudeMdWriters()
+            for (const [, prior] of writtenTargets) {
+              try {
+                const removed = removeManagedBlock(prior)
+                if (removed) log(`[rules-watcher] mode changed away from claude_md — removed managed block from ${expandHome(prior)}`)
+              } catch (e) {
+                log(`[rules-watcher] failed to remove managed block from ${expandHome(prior)}: ${e && (e.stack || e.message) || e}`)
+              }
+            }
+            return
+          }
+          // Every rebuild removes stale managed blocks from all prior targets
+          // except the current one. This covers A→B→A, where A was already
+          // seen but B still needs cleanup before A is rebuilt.
+          const { removeManagedBlock } = _loadClaudeMdWriters()
+          for (const [resolvedPrior, prior] of writtenTargets) {
+            if (resolvedPrior === resolvedCurrent) continue
+            try {
+              const removed = removeManagedBlock(prior)
+              if (removed) log(`[rules-watcher] removed stale managed block from ${expandHome(prior)} before rebuilding ${expandHome(currentTargetPath)}`)
+            } catch (e) {
+              log(`[rules-watcher] failed to remove stale managed block from ${expandHome(prior)}: ${e && (e.stack || e.message) || e}`)
+            }
+          }
+          const content = buildInjectionContent({ PLUGIN_ROOT, DATA_DIR: PLUGIN_DATA })
+          upsertManagedBlock(currentTargetPath, content)
+          writtenTargets.set(resolvedCurrent, currentTargetPath)
+          log(`[rules-watcher] rebuilt managed block (${content.length} chars) at ${expandHome(currentTargetPath)} after ${triggerFilename}`)
+        } catch (e) {
+          log(`[rules-watcher] rebuild failed: ${e && (e.stack || e.message) || e}`)
+        }
+      }, 300)
+    }
+
+    // Filenames are normalised to forward-slashes before lookup so the
+    // recursive fs.watch event (which reports e.g. `history\user.md` on
+    // Windows) lines up with this allowlist. Keep these in sync with the
+    // sources buildInjectionContent (lib/rules-builder.cjs) actually reads:
+    // mixdog-config.json + user-workflow.{json,md} at the data root and
+    // history/user.md + history/bot.md (user profile / bot persona).
+    const DATA_ALLOWLIST = new Set([
+      'mixdog-config.json', 'user-workflow.json', 'user-workflow.md',
+      'history/user.md', 'history/bot.md',
+    ])
+
+    const makeHandler = root => {
+      const isDataDir = pathResolve(root) === pathResolve(PLUGIN_DATA)
+      return (_eventType, filename) => {
+        if (!filename) return
+        if (!/\.(md|json)$/i.test(filename)) return
+        const norm = filename.replace(/\\/g, '/')
+        if (isDataDir && !DATA_ALLOWLIST.has(norm)) return
+        const abs = pathResolve(root, filename)
+        if (abs === resolvedTarget) return
+        rebuild(filename)
+      }
+    }
+
+    const roots = [
+      join(PLUGIN_ROOT, 'rules'),
+      PLUGIN_DATA,
+    ]
+    for (const root of roots) {
+      try {
+        fsWatch(root, { recursive: true, persistent: true }, makeHandler(root))
+        log(`[rules-watcher] watching ${root}`)
+      } catch (e) {
+        log(`[rules-watcher] failed to watch ${root}: ${e && (e.stack || e.message) || e}`)
+      }
+    }
+  } catch (e) {
+    log(`[rules-watcher] setup failed: ${e && (e.stack || e.message) || e}`)
+  }
+})
+
+// Channels worker spawn + reconcileClaudeMd + deferred search/dispatch
+// recovery stay after MCP connect; status-server now starts during parent
+// boot, before memory/channels workers.
+
+// ── Shutdown ────────────────────────────────────────────────────────
+const isWin = process.platform === 'win32'
+let shuttingDown = false
+const WORKER_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 8000  // child must be < parent (10s) to avoid race
+
+async function gracefulKillWorker(name, entry) {
+  const pid = entry.proc.pid
+  workerIntentionalStop.add(name)
+  // Step 1: request clean shutdown via IPC (preferred) or SIGTERM simulation.
+  // On Windows, Node child_process.kill('SIGTERM') sends a real SIGTERM only
+  // on newer Node; for reliability we prefer IPC message on win32.
+  let shutdownRequested = false
+  if (entry.proc.connected) {
+    try {
+      entry.proc.send({ type: 'shutdown' })
+      shutdownRequested = true
+      log(`shutdown: sent IPC {type:"shutdown"} to worker ${name} (pid=${pid})`)
+    } catch {}
+  }
+  if (!shutdownRequested) {
+    try {
+      entry.proc.kill('SIGTERM')
+      log(`shutdown: sent SIGTERM to worker ${name} (pid=${pid})`)
+    } catch {}
+  }
+  // Step 2: wait for clean exit (process.exit fires 'exit' which deletes from workers).
+  const exitP = new Promise(resolve => entry.proc.once('exit', resolve))
+  const timedOut = await Promise.race([
+    exitP.then(() => false),
+    new Promise(resolve => setTimeout(() => resolve(true), WORKER_GRACEFUL_SHUTDOWN_TIMEOUT_MS)),
+  ])
+  if (!timedOut) {
+    log(`shutdown: worker ${name} exited cleanly (pid=${pid}) — path=graceful`)
+    return
+  }
+  // Step 3: timeout expired — force kill as last resort.
+  log(`shutdown: worker ${name} did not exit within ${WORKER_GRACEFUL_SHUTDOWN_TIMEOUT_MS}ms — forcing kill (pid=${pid}) path=force`)
+  try {
+    if (isWin && pid) {
+      const { execSync: _ek } = await import('node:child_process')
+      _ek(`taskkill /F /PID ${pid}`, { stdio: 'ignore', windowsHide: true, timeout: 5000 })
+    } else {
+      entry.proc.kill('SIGKILL')
+    }
+  } catch {}
+}
+
+async function shutdown(reason) {
+  if (shuttingDown) return
+  shuttingDown = true
+  log(`shutdown: ${reason}`)
+  // Stop idle session sweep timer
+  try {
+    const { stopIdleCleanup } = await import(pathToFileURL(join(PLUGIN_ROOT, 'src/agent/orchestrator/session/manager.mjs')).href)
+    stopIdleCleanup()
+  } catch {}
+  // Stop status HTTP server child — parent-disconnect triggers graceful
+  // shutdown (advertisement file cleanup + server.close) in the child.
+  // On Windows, taskkill /F is the reliable fallback.
+  // Set the stop flag first so the exit handler's scheduleStatusServerRestart()
+  // is a no-op; otherwise a long shutdown can respawn the status server.
+  statusServerStopping = true
+  if (statusServerRestartTimer) {
+    clearTimeout(statusServerRestartTimer)
+    statusServerRestartTimer = null
+  }
+  if (statusServerChild) {
+    const pid = statusServerChild.pid
+    try {
+      if (isWin && pid) {
+        const { execSync: _execSync } = await import('node:child_process')
+        _execSync(`taskkill /F /T /PID ${pid}`, { stdio: 'ignore', windowsHide: true, timeout: 3000 })
+      } else {
+        // SIGTERM then bounded wait + SIGKILL escalation: the parent exits at
+        // the end of shutdown(), so without waiting a slow-to-handle child is
+        // orphaned. Race the child's 'exit' against a 3s deadline, then force
+        // kill if it hasn't exited.
+        const _child = statusServerChild
+        const _exited = new Promise(resolve => _child.once('exit', () => resolve(false)))
+        _child.kill('SIGTERM')
+        const _timedOut = await Promise.race([
+          _exited,
+          new Promise(resolve => setTimeout(() => resolve(true), 3000)),
+        ])
+        if (_timedOut) {
+          try { _child.kill('SIGKILL') } catch {}
+        }
+      }
+    } catch {}
+    // Belt-and-braces: unlink the advertisement file if child didn't.
+    try { unlinkSync(STATUS_ADVERTISE_PATH) } catch {}
+  }
+  // Graceful worker shutdown: IPC/SIGTERM → wait → force kill only as last resort.
+  // Avoids taskkill /F /T which may corrupt pgdata.
+  for (const [name, entry] of workers) {
+    await gracefulKillWorker(name, entry)
+  }
+  // Kill tracked bridge CLI processes
+  try {
+    const { cleanupOrphanedPids } = await import(pathToFileURL(join(PLUGIN_ROOT, 'src/shared/llm/pid-cleanup.mjs')).href)
+    const killed = cleanupOrphanedPids()
+    if (killed > 0) log(`shutdown: cleaned ${killed} bridge CLI processes`)
+  } catch {}
+  // Graceful PG shutdown — fires only on clean shutdown path.
+  // On supervisor-kill path (SIGTERM w/ no time for graceful stop), PG is
+  // left running; next ensurePgInstance call recovers via stale-detection.
+  try {
+    const { stopPgForShutdown } = await import(pathToFileURL(join(PLUGIN_ROOT, 'src/memory/lib/pg/supervisor.mjs')).href)
+    await stopPgForShutdown()
+  } catch {}
+  for (const mod of modules.values()) {
+    if (mod.stop) await mod.stop()
+  }
+  // Final log drain — graceful path is the only flush guarantee since the
+  // SIGTERM short-circuit handler was removed.
+  try { _logFlushSync() } catch {}
+  process.exit(0)
+}
+
+server.onclose = () => shutdown('transport closed')
+process.on('SIGTERM', () => shutdown('SIGTERM'))
+process.on('SIGINT', () => shutdown('SIGINT'))
+
+// R17 parent-watch: if the supervisor dies abruptly (no IPC, no SIGTERM),
+// server-main + forked workers would otherwise keep running across restarts.
+// Poll the supervisor pid with signal 0 every 5 s; on ESRCH (parent gone)
+// trigger the same graceful shutdown path the SIGTERM handler uses.
+{
+  const _supervisorPid = Number(process.env.MIXDOG_SUPERVISOR_PID)
+  if (Number.isFinite(_supervisorPid) && _supervisorPid > 0) {
+    const _parentWatch = setInterval(() => {
+      try {
+        process.kill(_supervisorPid, 0)
+      } catch {
+        // parent gone — fall through to graceful shutdown
+        try { clearInterval(_parentWatch) } catch {}
+        shutdown('supervisor exit (parent-watch)')
+      }
+    }, 5000)
+    if (typeof _parentWatch.unref === 'function') _parentWatch.unref()
+  }
+}
+
+// Wire prelude's supervisor-control flag (set before server-main loaded).
+globalThis.__mixdogShutdownFromSupervisor = () => shutdown('supervisor control')
+if (globalThis.__mixdogSupervisorShutdownRequested) {
+  shutdown('supervisor control (early)')
+}