mixdog 0.7.1

package/scripts/run-mcp.mjs

@@ -0,0 +1,1547 @@
+#!/usr/bin/env bun
+/**
+ * MCP server launcher for mixdog (bun-only) — proxy supervisor.
+ *
+ * Boot sequence:
+ *   1. Resolve the shared data directory via plugin-paths.cjs.
+ *   2. Copy package.json + bun.lock there and run `bun install --frozen-lockfile`
+ *      into <dataDir>/node_modules/ (only when the lockfile / dep-keys change).
+ *   3. Symlink pluginRoot/node_modules → dataDir/node_modules so all plugin
+ *      code resolves deps from the shared install.
+ *   4. Spawn server.mjs with bun and proxy MCP stdio between Claude Code and
+ *      the child. The proxy caches the client's initialize/initialized so a
+ *      child kill (dev-sync --restart, crash) can be silently re-handshaken
+ *      against a fresh child without forcing the client to reconnect.
+ *
+ * Single-runtime path: any failure throws — no node fallback.
+ */
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import { dirname, join } from 'path';
+import * as fs from 'fs';
+import { createHash, randomUUID } from 'crypto';
+import { execSync, spawn, spawnSync } from 'child_process';
+import * as os from 'os';
+import { assertSafeOwnedDir } from '../src/shared/user-data-guard.mjs';
+
+// Stable per-terminal session id for this proxy supervisor's lifetime. The
+// child server.mjs is respawned on crash / dev-sync restart, but THIS
+// supervisor process survives, so a once-minted id stays constant across
+// child reconnects. thin-client.mjs advertises it on the daemon control
+// frame; a constant id keeps the daemon's bySession map pinned to the LIVE
+// connection instead of minting a fresh bootstrap UUID per reconnect — which
+// stranded detached worker results on stale (dead) connections. Honor an
+// upstream-provided id if one already exists.
+const STABLE_TERMINAL_SESSION_ID = process.env.MIXDOG_SESSION_ID || randomUUID();
+
+const RENAME_RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY', 'EEXIST']);
+const RENAME_BACKOFFS_MS = Object.freeze([25, 50, 100, 200, 400, 800, 1200, 1600]);
+function sleepSync(ms) {
+  try {
+    const buf = new SharedArrayBuffer(4);
+    Atomics.wait(new Int32Array(buf), 0, 0, Math.max(1, Number(ms) || 1));
+  } catch {}
+}
+function renameWithRetrySync(src, dst) {
+  let lastErr = null;
+  for (let attempt = 0; attempt <= RENAME_BACKOFFS_MS.length; attempt++) {
+    try {
+      fs.renameSync(src, dst);
+      return true;
+    } catch (err) {
+      lastErr = err;
+      if (!RENAME_RETRY_CODES.has(err?.code) || attempt >= RENAME_BACKOFFS_MS.length) break;
+      sleepSync(RENAME_BACKOFFS_MS[attempt] + Math.floor(Math.random() * 50));
+    }
+  }
+  throw lastErr;
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const __localRoot = join(__dirname, '..');
+
+// Read installed_plugins.json each boot so dev-sync --restart picks up new code
+// without forcing client reconnect. Falls back to own cache dir on any error.
+function _resolveLatestPluginRoot() {
+  try {
+    const manifestPath = join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
+    const data = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    if (!data || typeof data !== 'object' || !data.plugins) {
+      process.stderr.write('[run-mcp] WARN: installed_plugins.json has unexpected shape — using fallback\n')
+      return __localRoot
+    }
+    const entry = data?.plugins?.['mixdog@trib-plugin']?.[0];
+    if (entry?.installPath) {
+      const latest = entry.installPath.replace(/\\/g, '/');
+      if (fs.existsSync(latest)) {
+        return latest
+      }
+    }
+  } catch {}
+  process.stderr.write('[run-mcp] manifest-lock-fallback: manifest read failed — using boot pluginRoot as-is\n')
+  return __localRoot;
+}
+const pluginRoot = _resolveLatestPluginRoot();
+if (pluginRoot !== __localRoot) {
+  process.stderr.write(`[run-mcp] supervisor proxying to latest cache: ${pluginRoot} (own=${__localRoot})\n`);
+}
+const serverPath = join(pluginRoot, 'server.mjs');
+const pluginPkg  = join(pluginRoot, 'package.json');
+const pluginLock = join(pluginRoot, 'bun.lock');
+const pluginNm   = join(pluginRoot, 'node_modules');
+
+process.stderr.write(`[boot-time] tag=run-mcp-entry tMs=${Date.now()}\n`);
+
+// Surface plugin.json/package.json version drift at boot — warn-only.
+try {
+  const pluginVer  = JSON.parse(fs.readFileSync(join(pluginRoot, '.claude-plugin', 'plugin.json'), 'utf8')).version;
+  const packageVer = JSON.parse(fs.readFileSync(pluginPkg, 'utf8')).version;
+  if (pluginVer && packageVer && pluginVer !== packageVer) {
+    process.stderr.write(
+      `[run-mcp] WARN: version mismatch — plugin.json=${pluginVer} package.json=${packageVer}\n`
+      + `         Update package.json/.claude-plugin/plugin.json so both fields match.\n`,
+    );
+  }
+} catch { /* missing manifest — not run-mcp's concern */ }
+// Note: the supervisor cache-version advert (read by dev-sync) is written
+// by server.mjs at child boot, NOT here. Keeping advert/diagnostic writes
+// out of run-mcp.mjs means future updates to that logic land via
+// child-only restart and never sever the stdio bridge to Claude Code.
+// server.mjs reads MIXDOG_SUPERVISOR_PID + MIXDOG_SUPERVISOR_CACHE_DIR
+// from its env (set in spawnChild below) to identify the supervisor.
+
+const requiredDepNames = [
+  ['@modelcontextprotocol', 'sdk', 'package.json'],
+  ['zod', 'package.json'],
+  ['zod-to-json-schema', 'package.json'],
+  ['openai', 'package.json'],
+];
+
+function hasRequiredDeps(nmDir) {
+  return requiredDepNames.every((parts) => fs.existsSync(join(nmDir, ...parts)));
+}
+
+// ── Lightweight JSON-RPC line scanner ────────────────────────────────────────
+// Extracts `id` and `method` from a JSON-RPC line without a full JSON.parse.
+// Returns { id, method } (each may be undefined), or null on scan failure.
+
+// Returns true when the line must be fully parsed (initialize / negative-id).
+function _lineNeedsFullParse(line) {
+  if (/"id"\s*:\s*-/.test(line)) return true;             // internal negative-id
+  if (/"method"\s*:\s*"initializ/.test(line)) return true; // initialize / initialized
+  return false;
+}
+
+const _JSON_STRING_RE = '"(?:\\\\.|[^"\\\\])*"';
+const _JSON_NUMBER_RE = '-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?';
+const _JSON_STRING_ONLY_RE = new RegExp(`^${_JSON_STRING_RE}$`);
+
+function _parseJsonRpcScalar(raw) {
+  if (raw === 'null') return null;
+  if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(raw)) return Number(raw);
+  if (raw && raw[0] === '"') {
+    try { return JSON.parse(raw); } catch { return undefined; }
+  }
+  return undefined;
+}
+
+function _skipJsonWs(s, i) {
+  while (i < s.length && /\s/.test(s[i])) i++;
+  return i;
+}
+
+function _readJsonStringLiteral(s, i) {
+  if (s[i] !== '"') return null;
+  let escaped = false;
+  for (let j = i + 1; j < s.length; j++) {
+    const ch = s[j];
+    if (escaped) { escaped = false; continue; }
+    if (ch === '\\') { escaped = true; continue; }
+    if (ch === '"') return { raw: s.slice(i, j + 1), end: j + 1 };
+  }
+  return null;
+}
+
+function _skipJsonValue(s, i) {
+  i = _skipJsonWs(s, i);
+  const ch = s[i];
+  if (ch === '"') return _readJsonStringLiteral(s, i)?.end ?? -1;
+  if (ch === '{' || ch === '[') {
+    const close = ch === '{' ? '}' : ']';
+    const open = ch;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let j = i; j < s.length; j++) {
+      const c = s[j];
+      if (inString) {
+        if (escaped) { escaped = false; continue; }
+        if (c === '\\') { escaped = true; continue; }
+        if (c === '"') inString = false;
+        continue;
+      }
+      if (c === '"') { inString = true; continue; }
+      if (c === open) depth++;
+      else if (c === close) {
+        depth--;
+        if (depth === 0) return j + 1;
+      }
+    }
+    return -1;
+  }
+  while (i < s.length && s[i] !== ',' && s[i] !== '}' && s[i] !== ']') i++;
+  return i;
+}
+
+// Cheap extraction of `id` + `method` for the common single-message JSON-RPC
+// hot path. Batch payloads are rare and still use JSON.parse so per-item
+// errors stay exact. Non-RPC/noise lines return null and are quarantined.
+function _scanIdMethod(line) {
+  try {
+    const s = String(line || '').trim();
+    if (!s) return null;
+    if (s[0] === '[') {
+      const obj = JSON.parse(s);
+      if (!Array.isArray(obj)) return null;
+      return obj.map(item => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+          return { id: null, _malformed: true };
+        }
+        return { id: item.id, method: item.method, _malformed: false };
+      });
+    }
+    if (s[0] !== '{' || s[s.length - 1] !== '}') return null;
+    let id;
+    let method;
+    let sawId = false;
+    let sawMethod = false;
+    let i = 1;
+    while (i < s.length - 1) {
+      i = _skipJsonWs(s, i);
+      if (s[i] === ',') { i++; continue; }
+      if (s[i] === '}') break;
+      const keyLit = _readJsonStringLiteral(s, i);
+      if (!keyLit) return null;
+      let key;
+      try { key = JSON.parse(keyLit.raw); } catch { return null; }
+      i = _skipJsonWs(s, keyLit.end);
+      if (s[i] !== ':') return null;
+      i = _skipJsonWs(s, i + 1);
+      const valueStart = i;
+      const valueEnd = _skipJsonValue(s, valueStart);
+      if (valueEnd < 0) return null;
+      if (key === 'id') {
+        const raw = s.slice(valueStart, valueEnd).trim();
+        id = _parseJsonRpcScalar(raw);
+        if (id === undefined) return null;
+        sawId = true;
+      } else if (key === 'method') {
+        const raw = s.slice(valueStart, valueEnd).trim();
+        if (!_JSON_STRING_ONLY_RE.test(raw)) return null;
+        try { method = JSON.parse(raw); } catch { return null; }
+        sawMethod = true;
+      }
+      i = valueEnd;
+    }
+    if (!sawId && !sawMethod) return null;
+    return { id: sawId ? id : undefined, method: sawMethod ? method : undefined, _malformed: false };
+  } catch {
+    // Return null so handleChildLine's `if (scanned === null)` branch
+    // catches non-JSON noise and quarantines it via supLog instead of
+    // forwarding to the client. Previously this returned a malformed
+    // sentinel that fell through to writeToClient, leaking non-JSON
+    // bytes into the JSON-RPC frame stream (the "all tools hang"
+    // regression vector).
+    return null;
+  }
+}
+
+const LOCK_POLL_MS  = 250;
+const LOCK_MAX_MS   = 15 * 60 * 1000;
+const LOCK_XHOST_MS = 10 * 60 * 1000;
+
+function acquireLock(lockFile) {
+  const start = Date.now();
+  while (Date.now() - start < LOCK_MAX_MS) {
+    try {
+      const body = JSON.stringify({
+        pid:       process.pid,
+        hostname:  os.hostname(),
+        startedAt: Date.now(),
+      });
+      // 'wx' = O_CREAT | O_EXCL — fails atomically if file already exists.
+      fs.writeFileSync(lockFile, body, { flag: 'wx' });
+      return;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      try {
+        const raw  = fs.readFileSync(lockFile, 'utf8');
+        const body = JSON.parse(raw);
+        const st   = fs.statSync(lockFile);
+        const sameHost = body.hostname === os.hostname();
+        let dead = false;
+        if (sameHost) {
+          try { process.kill(body.pid, 0); }
+          catch (ke) { if (ke.code === 'ESRCH') dead = true; }
+        } else {
+          if (Date.now() - st.mtimeMs > LOCK_XHOST_MS) dead = true;
+        }
+        if (dead) fs.unlinkSync(lockFile);
+      } catch { /* lock may have been released between read and stat — retry */ }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_POLL_MS);
+    }
+  }
+  throw new Error(
+    `timed out waiting for dependency install lock after ${LOCK_MAX_MS / 60000} minutes`
+  );
+}
+
+function releaseLock(lockFile) {
+  try { fs.unlinkSync(lockFile); } catch {}
+}
+
+function ensureNmSymlink(linkPath, targetPath) {
+  const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+  // EPERM/EBUSY here is almost always a transient AV / indexer lock on the
+  // freshly-created junction. Retry with bounded backoff (~750ms) before
+  // giving up so a healthy boot doesn't have to wait for the next start.
+  const trySymlink = () => {
+    for (let attempt = 0; attempt < 5; attempt++) {
+      try { fs.symlinkSync(targetPath, linkPath, linkType); return; }
+      catch (e) {
+        if ((e.code === 'EBUSY' || e.code === 'EPERM') && attempt < 4) {
+          const end = Date.now() + 50 * (attempt + 1);
+          while (Date.now() < end) {}
+          continue;
+        }
+        if (e.code === 'EBUSY' || e.code === 'EPERM') {
+          process.stderr.write(`[run-mcp] WARN: symlinkSync ${e.code} (${linkPath}) after retries — next boot retry\n`);
+          return;
+        }
+        throw e;
+      }
+    }
+  };
+  let stat;
+  try { stat = fs.lstatSync(linkPath); } catch { stat = null; }
+  if (stat === null) { trySymlink(); return; }
+  if (stat.isSymbolicLink()) {
+    try {
+      const current = fs.readlinkSync(linkPath);
+      if (current === targetPath) return;
+    } catch {}
+    try { fs.unlinkSync(linkPath); }
+    catch (e) {
+      if (e.code === 'EBUSY' || e.code === 'EPERM') {
+        process.stderr.write(`[run-mcp] WARN: unlinkSync ${e.code} (${linkPath}) — next boot retry\n`);
+        return;
+      }
+      throw e;
+    }
+    trySymlink();
+    return;
+  }
+  try {
+    fs.rmSync(linkPath, { recursive: true, force: true });
+  } catch (e) {
+    if (e.code === 'EBUSY' || e.code === 'EPERM') {
+      process.stderr.write(`[run-mcp] WARN: cache node_modules locked by live process (${e.code}), skipping symlink replacement — next boot retry\n`);
+      return;
+    }
+    throw e;
+  }
+  trySymlink();
+}
+
+function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * SHA-256 hash that changes iff the resolved dep tree changes.
+ * Primary: bun.lock. Fallback: dep-key objects from package.json (so the very
+ * first install — before bun.lock exists — still hashes deterministically).
+ */
+function computeDepHash(pkgJsonPath, pkgLockPath) {
+  if (fs.existsSync(pkgLockPath)) {
+    return sha256(fs.readFileSync(pkgLockPath));
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+  const depKeys = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+  const depObj = {};
+  for (const k of depKeys) {
+    if (pkg[k]) {
+      depObj[k] = Object.fromEntries(
+        Object.entries(pkg[k]).sort(([a], [b]) => a.localeCompare(b))
+      );
+    }
+  }
+  return sha256(Buffer.from(JSON.stringify(depObj)));
+}
+
+const require = createRequire(import.meta.url);
+const { resolvePluginData } = require('../lib/plugin-paths.cjs');
+const dataDir = resolvePluginData();
+
+fs.mkdirSync(dataDir, { recursive: true });
+
+// ── Supervisor self-cleanup on stdio loss ──────────────────────────────────
+// Lifecycle invariant: this supervisor is owned by exactly one Claude Code
+// MCP client (the process that spawned us). When that client tears down its
+// end of stdio — IDE quit, mcp server toggle, restart — our stdin closes.
+// Without a handler we'd linger forever (the comment near killChild
+// historically defended this on grounds of "transient stdin events", but
+// stdio close is not transient: it's the OS reporting EOF). Lingering
+// supervisors accumulate as zombies and confuse Claude Code's routing layer
+// on the next reconnect (it spawns a new supervisor; the old one stays
+// alive answering nothing).
+//
+// Multi-session safety: each Claude Code session spawns its own supervisor
+// with its own stdio. EOF on our stdin only signals OUR client going away.
+// Nothing here touches another session's supervisor — they have their own
+// pipe and their own EOF.
+//
+// Light diagnostic lock: record our PID in supervisor.lock for ps-style
+// visibility, but never kill a PID found there. Stale entries are harmless;
+// the stdin-EOF handler is the actual liveness mechanism.
+const SUPERVISOR_LOCK = join(dataDir, 'supervisor.lock');
+try {
+  fs.writeFileSync(SUPERVISOR_LOCK, String(process.pid));
+  const _releaseSupervisorLock = () => {
+    try {
+      const recorded = parseInt(fs.readFileSync(SUPERVISOR_LOCK, 'utf8').trim(), 10);
+      // Only unlink if the lock still names us — another supervisor may have
+      // overwritten it (multi-session, restart). Don't clobber theirs.
+      if (recorded === process.pid) fs.unlinkSync(SUPERVISOR_LOCK);
+    } catch {}
+  };
+  process.on('exit', _releaseSupervisorLock);
+  // SIGINT/SIGTERM are handled cooperatively by killChild (registered
+  // later in this file). killChild gracefully shuts down the child and
+  // then calls process.exit(code), which fires the 'exit' listener
+  // above to release the lock. Do NOT register a separate signal
+  // handler here that calls process.exit(0) — it short-circuits the
+  // killChild listener and orphans the MCP child. SIGHUP has no
+  // killChild listener, so handle it terminally here.
+  try {
+    process.on('SIGHUP', () => process.exit(0));
+  } catch { /* SIGHUP unsupported on Windows — ignore */ }
+} catch (e) {
+  process.stderr.write(`[run-mcp] supervisor lock write failed: ${e?.message || e}\n`);
+}
+
+// Install runtime deps into a DEDICATED <dataDir>/.deps/ subdir — NEVER the
+// data root, which holds user data (mixdog-config.json, user-workflow.*,
+// roles/). Running `bun install` with cwd=dataDir would wipe that state.
+const depsDir    = join(dataDir, '.deps');
+const sharedPkg  = join(depsDir, 'package.json');
+const sharedLock = join(depsDir, 'bun.lock');
+const sharedNm   = join(depsDir, 'node_modules');
+const stamp      = join(depsDir, '.deps-stamp');
+const stampTmp   = join(depsDir, '.deps-stamp.tmp');
+const lockFile   = join(depsDir, '.install.lock');
+
+const currentHash = computeDepHash(pluginPkg, pluginLock);
+let storedHash = '';
+try { storedHash = fs.readFileSync(stamp, 'utf8').trim(); } catch {}
+
+const needsInstall = (currentHash !== storedHash) || !hasRequiredDeps(sharedNm);
+
+if (needsInstall) {
+  // Hard guard: refuse to install anywhere that would clobber user data.
+  // assertSafeOwnedDir throws unless depsDir is an owned subdir (.deps).
+  assertSafeOwnedDir(depsDir, dataDir, 'bun install');
+  fs.mkdirSync(depsDir, { recursive: true });
+  acquireLock(lockFile);
+  try {
+    fs.copyFileSync(pluginPkg, sharedPkg);
+    if (fs.existsSync(pluginLock)) fs.copyFileSync(pluginLock, sharedLock);
+
+    const args = fs.existsSync(sharedLock)
+      ? ['install', '--frozen-lockfile']
+      : ['install'];
+    process.stderr.write(`[run-mcp] installing shared deps: bun ${args.join(' ')}\n`);
+
+    // First install on a clean machine downloads + extracts all deps, which
+    // routinely exceeds 30s; too low a ceiling times out into an empty
+    // node_modules and aborts the very first boot. 3 minutes covers a cold
+    // network fetch while still bounding a genuinely stuck install.
+    const INSTALL_TIMEOUT_MS = 180_000;
+    const result = spawnSync(process.env.BUN_EXEC_PATH || process.execPath, args, {
+      cwd: depsDir,
+      stdio: 'inherit',
+      timeout: INSTALL_TIMEOUT_MS,
+      windowsHide: true,
+    });
+    if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') {
+      process.stderr.write(
+        `[run-mcp] WARN: bun install timed out after ${INSTALL_TIMEOUT_MS}ms — ` +
+        `continuing with existing node_modules (stale lock removed)\n`
+      );
+      try { fs.unlinkSync(lockFile); } catch {}
+    } else if (result.status !== 0) {
+      const detail = result.status ?? result.signal ?? 'unknown';
+      process.stderr.write(
+        `[run-mcp] WARN: bun install exited with status ${detail} — ` +
+        `continuing with existing node_modules if available\n`
+      );
+    } else {
+      // Atomic stamp write: tmp + rename so a crash cannot leave it half-written.
+      fs.writeFileSync(stampTmp, currentHash);
+      renameWithRetrySync(stampTmp, stamp);
+    }
+  } finally {
+    releaseLock(lockFile);
+  }
+}
+
+ensureNmSymlink(pluginNm, sharedNm);
+
+const probe = join(pluginNm, '@modelcontextprotocol', 'sdk', 'package.json');
+if (!fs.existsSync(probe)) {
+  // Probe failed: node_modules may be stale or install failed.
+  // If any required dep is present the env may still be usable — warn and continue.
+  // If ALL required deps are missing (fresh env + install failure), abort with guidance.
+  const anyPresent = hasRequiredDeps(sharedNm) || hasRequiredDeps(pluginNm);
+  if (anyPresent) {
+    process.stderr.write(
+      `[run-mcp] WARN: @modelcontextprotocol/sdk not found at expected path after install — ` +
+      `continuing with available node_modules\n`
+    );
+  } else {
+    process.stderr.write(
+      `[run-mcp] ERROR: node_modules is incomplete and bun install did not succeed.\n` +
+      `  Run \`bun install\` manually in ${pluginRoot} and retry.\n`
+    );
+    process.exit(1);
+  }
+}
+
+const isWin = process.platform === 'win32';
+
+// Proxy supervisor: parses NDJSON JSON-RPC, caches initialize so child kills
+// are silent to the client; in-flight requests get a retry-able error on child death.
+
+const CRASH_WINDOW_MS    = 10_000;
+const CRASH_MAX_RESTARTS = 5;
+const CRASH_BACKOFF_MS   = 500;
+// Dev-sync respawn gate. dev-sync writes this lock (pid + ts) BEFORE killing
+// the daemon/child and removes it AFTER the marketplace→cache copy completes.
+// The respawn path below waits while the lock is present so the fresh child
+// loads post-sync code instead of racing the copy and getting SIGTERMed (the
+// "one wasted respawn" race). Hard mtime staleness cutoff so a crashed
+// dev-sync can never deadlock respawns. Poll cadence mirrors the kill-delay
+// granularity used elsewhere.
+const DEV_SYNC_LOCK = join(dataDir, 'dev-sync-cache-write.lock');
+const DEV_SYNC_GATE_POLL_MS  = 100;
+const DEV_SYNC_GATE_STALE_MS = 30_000;
+// Hung-dev-sync escape hatch: even a live PID stops gating past this age, so a
+// wedged dev-sync can never deadlock respawns forever.
+const DEV_SYNC_GATE_HARD_CAP_MS = 5 * 60_000;
+// True while dev-sync is mid cache-copy. runSync() is synchronous (spawnSync,
+// bun install) so the lock mtime cannot heartbeat during long work — decide by
+// PID LIVENESS: a live lock owner keeps gating (up to the 5min hard cap),
+// regardless of mtime age. If the PID is dead or the lock is unparseable, fall
+// back to the 30s mtime cutoff so a crashed dev-sync still clears.
+function devSyncCacheWriteInProgress() {
+  let st;
+  try {
+    st = fs.statSync(DEV_SYNC_LOCK);
+  } catch {
+    return false; // missing lock → not syncing
+  }
+  const mtimeFresh = (Date.now() - st.mtimeMs) <= DEV_SYNC_GATE_STALE_MS;
+  let pid = null;
+  let ts = null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(DEV_SYNC_LOCK, 'utf8'));
+    pid = Number(parsed?.pid) || null;
+    ts = Number(parsed?.ts) || null;
+  } catch {
+    return mtimeFresh; // unparseable lock → mtime cutoff fallback
+  }
+  if (!pid) return mtimeFresh;
+  let alive;
+  try {
+    process.kill(pid, 0); // liveness probe (works on Windows too)
+    alive = true;
+  } catch (err) {
+    alive = err && err.code === 'EPERM'; // ESRCH = dead; EPERM = alive (foreign owner)
+  }
+  // Dead owner = crashed dev-sync; its copy is never going to finish, so
+  // unblock IMMEDIATELY rather than burning up to 30s of mtime cutoff. The
+  // mtime fallback above stays only for locks with no readable pid.
+  if (!alive) return false;
+  // Live owner: keep gating unless the lock is older than the hard cap.
+  const age = Date.now() - (ts ?? st.mtimeMs);
+  return age <= DEV_SYNC_GATE_HARD_CAP_MS;
+}
+// child stderr ring-buffer cap. 16 KB carries the last progress lines plus
+// any final throw/abort stack without flooding supervisor.log on a runaway
+// error loop.
+const STDERR_TAIL_BYTES  = 16 * 1024;
+// Inbound frame guardrail. JSON-RPC lines are newline-terminated; an
+// unterminated line that grows past this cap signals a runaway producer
+// (corrupted child stdout, hostile client stdin). 4 MB comfortably fits
+// any legitimate tool result while preventing unbounded memory growth.
+const MAX_LINE_BYTES     = 4 * 1024 * 1024;
+
+let proc = null;
+let shuttingDown = false;
+let respawnTimer = null;
+const recentRestarts = [];
+
+// Handshake-readiness gate. A spawned child accepts stdin immediately but may
+// be stuck in module-init (singleton lock contention, malformed cache, etc.)
+// and never emit a response. Without this gate the supervisor forwarded
+// requests into a black hole and the MCP layer either timed out or hung
+// indefinitely. Invariant: forward only initialize-class traffic until the
+// child has produced ≥1 stdout line; reply retry-able to anything else.
+let childHasResponded    = false;
+// Respawn-orphan guard. When a child is replaced (crash/dev-sync), the client
+// must re-fetch tools — but ONLY once the NEW child can answer tools/list.
+// Firing notifications/tools/list_changed before the child has responded races
+// the client's follow-up tools/list into the closed handshake gate, where it
+// gets a -32603 "retry" the client may never re-issue — leaving the session
+// with an empty tool list ("connected but no tools"). Deferred until
+// childHasResponded flips true post-respawn (see handleChildLine).
+let announceListChangedOnReady = false;
+let cachedInitRequest    = null; // { id, params } from client's first initialize
+let cachedInitDone       = false; // initialized notification observed from client
+let internalIdSeq        = -1;    // negative ids reserved for supervisor-internal requests
+const pendingFromClient  = new Map(); // request id (from client) → { method }
+const pendingInternal    = new Set(); // internal ids (init replay) — drop responses
+let stdinBuf  = '';
+let stdoutBuf = '';
+let childStderrBuf = '';
+let currentChildPluginRoot = pluginRoot;
+
+// Supervisor diagnostic log. Distinct from mcp-debug.log (which is the
+// child's own log via server-main.mjs:LOG_FILE). Captures transport-level
+// events that previously had no audit trail: quarantined non-JSON lines,
+// write errors, backpressure drain pauses. First place to inspect when
+// "all tools hang" — supervisor stays alive even when the JSON-RPC stream
+// to the client is wedged.
+const SUPERVISOR_LOG = join(dataDir, 'supervisor.log');
+const SUPERVISOR_LOG_SCOPED = join(dataDir, `supervisor.${process.pid}.log`);
+const SUPERVISOR_CONTEXT = `lead=${process.pid} supervisor=${process.pid}`;
+function _rotateSupervisorLog(file) {
+  try {
+    const st = fs.statSync(file);
+    if (st.size > 10 * 1024 * 1024) fs.renameSync(file, file + '.1');
+  } catch {}
+}
+_rotateSupervisorLog(SUPERVISOR_LOG);
+_rotateSupervisorLog(SUPERVISOR_LOG_SCOPED);
+// R14: sanitize a single log field — strip ANSI escapes and escape control
+// chars (CR, lone C0/C1) so attacker-controlled bytes from the child's stderr
+// can't forge new log lines, hide payloads with \r overwrites, or smuggle
+// ANSI sequences into operator terminals tailing supervisor.log. Keep \t and
+// \n: callers either pass single-line msgs or pre-split on \n.
+function sanitizeLogField(text) {
+  if (text == null) return '';
+  let s = String(text);
+  s = s.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, (m) => '\\x1b' + m.slice(1));
+  s = s.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, (m) => '\\x1b' + m.slice(1));
+  s = s.replace(/\x1b[@-_]/g, (m) => '\\x1b' + m.slice(1));
+  s = s.replace(/\r/g, '\\r');
+  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;
+}
+function supLog(msg) {
+  const line = `[${new Date().toISOString()}] [${SUPERVISOR_CONTEXT} child=${proc?.pid ?? '-'}] ${sanitizeLogField(msg)}\n`;
+  try { fs.appendFileSync(SUPERVISOR_LOG, line); } catch {}
+  try { fs.appendFileSync(SUPERVISOR_LOG_SCOPED, line); } catch {}
+}
+
+function _envPositiveInt(name, fallback) {
+  const n = Number(process.env[name]);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+const CLIENT_QUEUE_MAX_CHARS = _envPositiveInt('MIXDOG_SUPERVISOR_CLIENT_QUEUE_MAX_CHARS', 8 * 1024 * 1024);
+const CHILD_QUEUE_MAX_CHARS = _envPositiveInt('MIXDOG_SUPERVISOR_CHILD_QUEUE_MAX_CHARS', 4 * 1024 * 1024);
+const BACKPRESSURE_STALL_MS = _envPositiveInt('MIXDOG_SUPERVISOR_BACKPRESSURE_STALL_MS', 60_000);
+
+// Liveness watchdog. A client request can sit in pendingFromClient forever
+// when the child is ALIVE but the response path is wedged — a half-open daemon
+// pipe, or a dead-but-not-closed socket after an ungraceful multi-terminal
+// teardown. handleChildGone only fires on child PROCESS death and
+// flushPendingClientErrors only on supervisor death; neither covers
+// "alive but mute", so those requests never get answered → Claude Code's
+// silent hang ("tool call, no response"). We probe with an MCP `ping`, which
+// round-trips the SAME path as a tools/call: a healthy child's event loop
+// answers in well under a second even while a genuinely long tool runs async,
+// so this never aborts a slow-but-healthy call — only a dead path misses
+// repeated pings. After STALL_MAX_MISSES consecutive misses we SIGTERM the
+// child (NOT killChild, which tears down the whole supervisor) so
+// handleChildGone flushes pending with a retry error and respawns a fresh
+// thin client that re-attaches to the shared daemon.
+const STALL_PROBE_AFTER_MS = _envPositiveInt('MIXDOG_SUPERVISOR_STALL_PROBE_MS', 30_000);
+const PING_TIMEOUT_MS      = _envPositiveInt('MIXDOG_SUPERVISOR_PING_TIMEOUT_MS', 10_000);
+const STALL_MAX_MISSES     = _envPositiveInt('MIXDOG_SUPERVISOR_STALL_MAX_MISSES', 2);
+let _livenessPingId = null;     // internal id of the in-flight liveness ping
+let _livenessPingSentAt = 0;    // when it was written to the child
+let _livenessMisses = 0;        // consecutive unanswered pings
+let _livenessQuietUntil = 0;    // suppress re-probe until here after a good pong
+
+function _fatalSupervisor(reason) {
+  const msg = `[supervisor-fatal] ${reason}`;
+  try { process.stderr.write(msg + '\n'); } catch {}
+  supLog(msg);
+  flushPendingClientErrors(`fatal: ${reason}`);
+  try { proc?.kill('SIGTERM'); } catch {}
+  process.exit(1);
+}
+
+// Backpressure-aware writers. process.stdout.write / proc.stdin.write both
+// return false when the stream's internal buffer crosses its high-water
+// mark. Previously the return value was ignored, so the supervisor kept
+// piling writes onto an already-pressured pipe. On Windows pipes this can
+// stall the event loop when the peer (Claude Code or the child) falls
+// behind reading — manifesting as "every tool hangs for many minutes,
+// then suddenly all responses arrive" because the queue eventually drains
+// in one burst. Track drain state and queue further writes until the
+// 'drain' event fires, so we never push past a known backpressure
+// boundary. Order is preserved because the queue is a single string.
+let _clientQueue = '';
+let _clientDraining = false;
+let _clientDrainTimer = null;
+function writeToClient(line) {
+  if (_clientQueue.length + line.length + 1 > CLIENT_QUEUE_MAX_CHARS) {
+    _fatalSupervisor(`client queue overflow queued=${_clientQueue.length} incoming=${line.length} max=${CLIENT_QUEUE_MAX_CHARS}`);
+    return;
+  }
+  _clientQueue += line + '\n';
+  _flushClient();
+}
+function _flushClient() {
+  if (_clientDraining || !_clientQueue) return;
+  const chunk = _clientQueue;
+  _clientQueue = '';
+  let writeOk;
+  try { writeOk = process.stdout.write(chunk); }
+  catch (e) { supLog(`[client-write-error] ${e && e.message || e}`); return; }
+  if (writeOk === false) {
+    _clientDraining = true;
+    const pausedAt = Date.now();
+    _clientDrainTimer = setTimeout(() => {
+      _fatalSupervisor(`client backpressure stuck after ${BACKPRESSURE_STALL_MS}ms queued=${_clientQueue.length}b`);
+    }, BACKPRESSURE_STALL_MS);
+    _clientDrainTimer.unref?.();
+    process.stdout.once('drain', () => {
+      _clientDraining = false;
+      if (_clientDrainTimer) { clearTimeout(_clientDrainTimer); _clientDrainTimer = null; }
+      const dur = Date.now() - pausedAt;
+      // Only record meaningful stalls. Fast pause/drain cycles (<100ms)
+      // happen normally under burst writes and aren't useful in the audit
+      // trail; the sync appendFileSync per event was a non-trivial tax.
+      if (dur >= 100) supLog(`[client-backpressure] paused/drained ${dur}ms queued=${_clientQueue.length}b`);
+      _flushClient();
+    });
+  }
+}
+
+let _childQueue = '';
+let _childDraining = false;
+let _childDrainTimer = null;
+function writeToChild(line) {
+  if (!proc || !proc.stdin || !proc.stdin.writable) return false;
+  if (_childQueue.length + line.length + 1 > CHILD_QUEUE_MAX_CHARS) {
+    supLog(`[child-queue-overflow] queued=${_childQueue.length} incoming=${line.length} max=${CHILD_QUEUE_MAX_CHARS}; killing child`);
+    _childQueue = '';
+    try { proc.kill('SIGTERM'); } catch {}
+    return false;
+  }
+  _childQueue += line + '\n';
+  _flushChild();
+  return true;
+}
+function _flushChild() {
+  if (_childDraining || !_childQueue) return;
+  if (!proc || !proc.stdin || !proc.stdin.writable) {
+    // Child gone — handleChildGone will surface retry errors to the
+    // client. Drop queued writes here so a stale partial line cannot
+    // concatenate with the new child's first stdin chunk after respawn.
+    if (_childQueue) supLog(`[child-write-dropped] proc unavailable, dropped=${_childQueue.length}b`);
+    _childQueue = '';
+    return;
+  }
+  const chunk = _childQueue;
+  _childQueue = '';
+  let writeOk;
+  try { writeOk = proc.stdin.write(chunk); }
+  catch (e) { supLog(`[child-write-error] ${e && e.message || e}`); return; }
+  if (writeOk === false) {
+    _childDraining = true;
+    const pausedAt = Date.now();
+    _childDrainTimer = setTimeout(() => {
+      supLog(`[child-backpressure-stuck] after ${BACKPRESSURE_STALL_MS}ms queued=${_childQueue.length}b; killing child`);
+      try { proc?.kill('SIGTERM'); } catch {}
+    }, BACKPRESSURE_STALL_MS);
+    _childDrainTimer.unref?.();
+    proc.stdin.once('drain', () => {
+      _childDraining = false;
+      if (_childDrainTimer) { clearTimeout(_childDrainTimer); _childDrainTimer = null; }
+      const dur = Date.now() - pausedAt;
+      if (dur >= 100) supLog(`[child-backpressure] paused/drained ${dur}ms queued=${_childQueue.length}b`);
+      _flushChild();
+    });
+  }
+}
+
+function sendErrorToClient(id, code, message) {
+  // Only skip for notifications (no id field at all). JSON-RPC allows id:null.
+  if (id === undefined) return;
+  writeToClient(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }));
+}
+
+// Invariant: if the SUPERVISOR itself goes down (uncaught exception, fatal
+// rejection, fatal backpressure) while client tool calls are still
+// outstanding, every outstanding request MUST receive a terminal JSON-RPC
+// error — never silence. Claude Code does NOT auto-reconnect a stdio MCP
+// server, so without this the client waits on a dead supervisor until a manual
+// /mcp reconnect (the "silent hang"). handleChildGone covers CHILD death; this
+// covers the supervisor's own death paths, which previously exited without
+// answering pending ids. Frames go DIRECT to stdout (bypassing the
+// backpressure queue) because the process is exiting and the async queue may
+// never drain; best-effort under try/catch since a broken pipe can't be
+// helped. Distinct "supervisor ..." tag (vs handleChildGone's "mcp child ...")
+// keeps the two death classes separable in logs.
+function flushPendingClientErrors(tag) {
+  if (pendingFromClient.size === 0) return;
+  const _n = pendingFromClient.size;
+  for (const [id] of pendingFromClient) {
+    if (id === undefined) continue;
+    const frame = JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32603, message: `[run-mcp] supervisor ${tag}; retry` } });
+    try { process.stdout.write(frame + '\n'); } catch {}
+  }
+  pendingFromClient.clear();
+  try { supLog(`[supervisor-flush-pending] tag=${tag} flushed=${_n}`); } catch {}
+}
+
+function replayInitToChild() {
+  if (!cachedInitRequest) return;
+  const internalId = internalIdSeq--;
+  pendingInternal.add(internalId);
+  writeToChild(JSON.stringify({
+    jsonrpc: '2.0',
+    id: internalId,
+    method: 'initialize',
+    params: cachedInitRequest.params,
+  }));
+  if (cachedInitDone) {
+    // Notification — no id, no response expected.
+    writeToChild(JSON.stringify({
+      jsonrpc: '2.0',
+      method: 'notifications/initialized',
+    }));
+  }
+}
+
+function handleClientLine(line) {
+  if (!line.trim()) return;
+  // Fast-path: skip full JSON.parse on every tool call; only parse when the
+  // supervisor needs the full payload (initialize/initialized or negative-id).
+  const needsFullParse = _lineNeedsFullParse(line);
+  let msg = needsFullParse ? null : _scanIdMethod(line);
+  if (needsFullParse || msg === null) {
+    try { msg = JSON.parse(line); } catch {
+      // Non-JSON line from client stdin. Forwarding to the child would
+      // corrupt its JSON-RPC parser and drop subsequent valid requests
+      // until the parser realigns. Quarantine to supervisor.log and drop.
+      supLog(`[client-stdin-noise] ${line.slice(0, 500)}`);
+      return;
+    }
+  }
+  if (msg && typeof msg === 'object') {
+    const items = Array.isArray(msg) ? msg : [msg];
+    for (const item of items) {
+      if (!item || typeof item !== 'object') continue;
+      if (item.method === 'initialize') {
+        cachedInitRequest = { id: item.id, params: item.params };
+      } else if (item.method === 'notifications/initialized' || item.method === 'initialized') {
+        cachedInitDone = true;
+      }
+      if (item.id !== undefined && item.method) {
+        pendingFromClient.set(item.id, { method: item.method, ts: Date.now() });
+      }
+    }
+  }
+  // Handshake gate: hold back non-init traffic until child proves liveness
+  // with a response. Init/initialized are always forwarded since they are
+  // the only payload that can advance the gate.
+  if (!childHasResponded && msg && typeof msg === 'object') {
+    const _isInit = (it) => it && typeof it === 'object'
+      && (it.method === 'initialize'
+          || it.method === 'notifications/initialized'
+          || it.method === 'initialized');
+    const items = Array.isArray(msg) ? msg : [msg];
+    const allInit = items.every(_isInit);
+    if (!allInit) {
+      for (const item of items) {
+        if (!_isInit(item) && item && item.id !== undefined) {
+          sendErrorToClient(item.id, -32603, '[run-mcp] mcp child handshake pending; retry');
+          pendingFromClient.delete(item.id);
+        }
+      }
+      return;
+    }
+  }
+  if (!writeToChild(line)) {
+    // Child not yet ready (e.g. mid-respawn). For requests with an id, surface
+    // a retry-able error; notifications are dropped (clients re-emit on
+    // demand — list_changed will re-trigger).
+    if (Array.isArray(msg)) {
+      // Batch: send per-item errors and clean up pendingFromClient.
+      for (const item of msg) {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+          // Non-object batch item — spec requires id:null -32600.
+          sendErrorToClient(null, -32600, '[run-mcp] Invalid Request: batch item is not an object');
+          continue;
+        }
+        const hasValidMethod = typeof item.method === 'string' && item.method.length > 0;
+        if (item.id !== undefined || !hasValidMethod) {
+          const id = item.id !== undefined ? item.id : null;
+          const code = hasValidMethod ? -32603 : -32600;
+          const message = hasValidMethod
+            ? '[run-mcp] mcp child unavailable; retry'
+            : '[run-mcp] Invalid Request: missing or invalid method';
+          sendErrorToClient(id, code, message);
+          pendingFromClient.delete(item.id);
+        }
+      }
+    } else if (msg && msg.id !== undefined && msg.method) {
+      sendErrorToClient(msg.id, -32603, '[run-mcp] mcp child unavailable; retry');
+      pendingFromClient.delete(msg.id);
+    }
+  }
+}
+
+function handleChildLine(line) {
+  if (!line.trim()) return;
+  // Fast-path: only internal negative-id replies need full parse; everything
+  // else is forwarded after a lightweight id scan.
+  const scanned = _lineNeedsFullParse(line)
+    ? (() => { try { return JSON.parse(line); } catch { return null; } })()
+    : _scanIdMethod(line);
+  if (scanned === null) {
+    // Non-JSON noise must NOT flip childHasResponded — if it did, runtime
+    // warnings during module init would prematurely open the handshake
+    // gate and let regular tool requests reach a child that hadn't yet
+    // replied to MCP `initialize` ("all tools hang" regression).
+  } else if (!childHasResponded) {
+    // Valid JSON response — child has completed module-init.
+    childHasResponded = true;
+    // A respawn deferred its tools/list_changed until the child could serve
+    // tools/list. The gate is now open — announce so the client re-fetches
+    // into a child that will actually answer (not the closed-gate -32603).
+    // Gate on cachedInitDone: tools/list_changed is only valid AFTER the
+    // client has completed MCP initialization (notifications/initialized).
+    // A respawn that lands mid-handshake (before init completes) must NOT
+    // emit it — doing so would drive the client to tools/list before init
+    // finishes. In that pre-init case the client's own initialize→tools/list
+    // flow already covers tool discovery, so dropping the announce is safe.
+    if (announceListChangedOnReady) {
+      announceListChangedOnReady = false;
+      if (cachedInitDone) {
+        writeToClient(JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'notifications/tools/list_changed',
+        }));
+      }
+    }
+  }
+  if (scanned === null) {
+    // Non-JSON line from the child stdout. Worker stdout used to be
+    // inherited (server-main.mjs stdio idx 1) so a bun runtime warning
+    // or dependency stdout write could leak here and corrupt the
+    // JSON-RPC frame stream the client sees. Worker stdout is now
+    // /dev/null but server-main.mjs itself or future regressions could
+    // still emit a non-JSON line — quarantine instead of forwarding so
+    // the client parser never sees a malformed frame.
+    supLog(`[child-stdout-noise] ${line.slice(0, 500)}`);
+    return;
+  }
+  if (Array.isArray(scanned)) {
+    const internalIds = new Set();
+    for (const item of scanned) {
+      if (item && item.id !== undefined) {
+        if (pendingInternal.has(item.id)) { internalIds.add(item.id); pendingInternal.delete(item.id); _maybeResolveLivenessPong(item.id); }
+        else { pendingFromClient.delete(item.id); }
+      }
+    }
+    if (internalIds.size) {
+      // A batch carrying an internal reply (init replay / liveness pong) must
+      // not surface those negative ids to the client. The thin-client emits one
+      // object per line so a mixed batch isn't expected — strip defensively and
+      // forward only genuine client replies (swallow if none remain).
+      const forward = scanned.filter((item) => !(item && item.id !== undefined && internalIds.has(item.id)));
+      if (forward.length === 0) return;
+      writeToClient(JSON.stringify(forward));
+      return;
+    }
+  } else if (scanned.id !== undefined) {
+    if (pendingInternal.has(scanned.id)) {
+      // Supervisor-internal reply (initialize replay or liveness ping pong) —
+      // swallow it: the client never issued this id. A liveness pong also
+      // clears the stall probe so a slow-but-healthy call is not recycled.
+      pendingInternal.delete(scanned.id);
+      _maybeResolveLivenessPong(scanned.id);
+      return;
+    }
+    if (!pendingFromClient.has(scanned.id)) {
+      // Unknown id — neither an internal replay nor an outstanding client
+      // request. Forwarding it would let a stale/rogue child line surface
+      // as a spurious response. Drop with a supLog anchor instead.
+      supLog(`[child-stdout-unknown-id] ${line.slice(0, 500)}`);
+      return;
+    }
+    pendingFromClient.delete(scanned.id);
+  }
+  writeToClient(line);
+}
+
+function drainBuffer(buf, onLine) {
+  let lastIndex = 0;
+  let idx;
+  while ((idx = buf.indexOf('\n', lastIndex)) !== -1) {
+    const line = buf.slice(lastIndex, idx).replace(/\r$/, '');
+    lastIndex = idx + 1;
+    onLine(line);
+  }
+  return lastIndex === 0 ? buf : buf.slice(lastIndex);
+}
+
+// Shared child-gone cleanup. Every path that leaves `proc` non-runnable
+// (normal exit, crash, spawn-error) must invalidate pending requests,
+// reset stdoutBuf (stale partial line from the dead child must not
+// concatenate with the new child's first response), and schedule a
+// respawn. Invariant: `proc` is never left as an orphaned handle
+// without a recovery path.
+function handleChildGone(why) {
+  if (proc === null) return;
+  proc = null;
+  if (shuttingDown) {
+    process.exit(why.exitCode ?? 0);
+    return;
+  }
+  // Exit-cause diagnostics: drain the child stderr ring buffer NOW (before
+  // anything else can overwrite it) so post-mortem analysis has the last
+  // bytes the dying child emitted — progress lines, native error, throw stack.
+  // Cleared after capture so the next child boots with a fresh buffer.
+  const _stderrTail = childStderrBuf;
+  childStderrBuf = '';
+  if (_stderrTail) {
+    const _trimmed = _stderrTail.slice(-STDERR_TAIL_BYTES);
+    // R14: prefix EACH physical line so an attacker can't forge a fake
+    // supervisor.log entry by emitting bytes like "\n[timestamp] [...] evil"
+    // from the child's stderr — every embedded line now starts with the
+    // marker, and per-line sanitize strips ANSI / escapes lone CR + C0/C1.
+    const _prefixed = _trimmed
+      .split(/\r?\n/)
+      .map((ln) => '[stderr-tail] ' + sanitizeLogField(ln))
+      .join('\n');
+    supLog(`[child-stderr-tail exitCode=${why.exitCode ?? 'n/a'} signal=${why.signal ?? 'n/a'} bytes=${_trimmed.length}]\n${_prefixed}`);
+  } else {
+    supLog(`[child-stderr-tail exitCode=${why.exitCode ?? 'n/a'} signal=${why.signal ?? 'n/a'} bytes=0] (empty)`);
+  }
+  const _pendingClientAtGone = pendingFromClient.size;
+  const _pendingInternalAtGone = pendingInternal.size;
+  for (const [id] of pendingFromClient) {
+    sendErrorToClient(id, -32603, `[run-mcp] mcp child ${why.tag}; retry`);
+  }
+  pendingFromClient.clear();
+  pendingInternal.clear();
+  // Fresh child = fresh response path; discard any in-flight liveness probe.
+  _livenessPingId = null;
+  _livenessMisses = 0;
+  _livenessQuietUntil = 0;
+  stdoutBuf = '';
+  // Drop any stdin queue tied to the dead proc.stdin handle. The new
+  // child gets a fresh writable stream from spawnChild; replaying queued
+  // lines into it could break ordering (init replay must come first) or
+  // leak requests the client already received an error for above.
+  if (_childQueue) supLog(`[child-write-dropped] child gone, dropped=${_childQueue.length}b`);
+  _childQueue = '';
+  _childDraining = false;
+  if (_childDrainTimer) { clearTimeout(_childDrainTimer); _childDrainTimer = null; }
+
+  const now = Date.now();
+  recentRestarts.push(now);
+  while (recentRestarts.length && now - recentRestarts[0] > CRASH_WINDOW_MS) {
+    recentRestarts.shift();
+  }
+  const crashLoop = recentRestarts.length > CRASH_MAX_RESTARTS;
+  if (crashLoop) {
+    // Don't tear down the supervisor — staying alive lets a follow-up
+    // dev-sync replace the broken child without losing the MCP stdio
+    // session. Surface the diagnostic and back off; new client requests
+    // will get a retry-able error until a clean child boots.
+    const _crashMsg = `[run-mcp] child crash loop (${recentRestarts.length} ${why.tag} in ${CRASH_WINDOW_MS}ms) — backing off ${CRASH_BACKOFF_MS * 4}ms; supervisor stays up`;
+    process.stderr.write(_crashMsg + '\n');
+    supLog(_crashMsg);
+  } else {
+    const _respawnMsg = `[run-mcp] ${why.log} — respawning (#${recentRestarts.length}); pendingClient=${_pendingClientAtGone} pendingInternal=${_pendingInternalAtGone} shuttingDown=${shuttingDown}`;
+    process.stderr.write(_respawnMsg + '\n');
+    supLog(_respawnMsg);
+  }
+  const delay = crashLoop ? CRASH_BACKOFF_MS * 4 : CRASH_BACKOFF_MS;
+  // Gate the respawn behind the dev-sync cache-write lock. When dev-sync kills
+  // the child to deploy fresh code it holds DEV_SYNC_LOCK across the
+  // marketplace→cache copy; respawning before the copy finishes loads STALE
+  // code that dev-sync then SIGTERMs (the wasted-respawn race this gate fixes).
+  // While the lock is present (and not stale) we re-poll every
+  // DEV_SYNC_GATE_POLL_MS instead of spawning; devSyncCacheWriteInProgress's
+  // mtime staleness cutoff guarantees a crashed dev-sync can never deadlock.
+  const doRespawn = () => {
+    if (shuttingDown) return;
+    if (devSyncCacheWriteInProgress()) {
+      respawnTimer = setTimeout(doRespawn, DEV_SYNC_GATE_POLL_MS);
+      return;
+    }
+    spawnChild();
+    if (cachedInitRequest) {
+      replayInitToChild();
+    } else if (crashLoop) {
+      process.stderr.write('[run-mcp] WARN: crash-loop respawn before initialize landed — skipping init replay\n');
+    }
+    // Defer the tools/list_changed announcement until the fresh child proves
+    // it can respond (handleChildLine flips childHasResponded → fires it).
+    // Announcing now would race the client's tools/list into the closed
+    // handshake gate and risk a permanently-empty tool list on reconnect.
+    announceListChangedOnReady = true;
+  };
+  respawnTimer = setTimeout(doRespawn, delay);
+}
+
+function spawnChild() {
+  // Re-resolve pluginRoot on EVERY child spawn so dev-sync --restart
+  // (kills only child) picks up the new cache path. Boot-time pluginRoot
+  // is used for one-shot install / symlink / version warn; everything
+  // child-facing must come from the live manifest each spawn.
+  const childPluginRoot = _resolveLatestPluginRoot();
+  currentChildPluginRoot = childPluginRoot;
+  const childServerPath = join(childPluginRoot, 'server.mjs');
+  if (childPluginRoot !== pluginRoot) {
+    process.stderr.write(`[run-mcp] child spawn path refreshed: ${childPluginRoot} (boot=${pluginRoot})\n`);
+  }
+  // Reset the readiness gate every spawn — respawned child must re-prove
+  // it can respond before it inherits "ready" from the previous instance.
+  childHasResponded = false;
+  // Reset the stdout parse buffer too. A partial JSON line left in the
+  // buffer by the previous child must not concatenate with the new
+  // child's first response and corrupt JSON.parse.
+  stdoutBuf = '';
+  process.stderr.write(`[boot-time] tag=run-mcp-spawn-server tMs=${Date.now()}\n`);
+  proc = spawn(process.env.BUN_EXEC_PATH || process.execPath, [childServerPath], {
+    cwd: childPluginRoot,
+    // child stderr piped (not inherited) so supervisor can ring-buffer the
+    // tail and surface it on unexpected exit. handleChildGone reads the
+    // last STDERR_TAIL_BYTES on death to anchor exit-cause diagnostics
+    // (e.g. crash loop, native crash, unhandledRejection final line).
+    stdio: ['pipe', 'pipe', 'pipe', 'pipe'],
+    // The supervisor itself can be console-less (hidden respawn via
+    // launch.mjs); without CREATE_NO_WINDOW each child respawn allocates a
+    // visible console that flashes on screen.
+    windowsHide: true,
+    env: {
+      ...process.env,
+      UV_THREADPOOL_SIZE: '2',
+      CLAUDE_PLUGIN_ROOT: childPluginRoot,
+      CLAUDE_PLUGIN_DATA: dataDir,
+      MIXDOG_SUPERVISOR_CONTROL_FD: '3',
+      // Identity passed to the child so server.mjs can write the supervisor
+      // advert (consumed by dev-sync's cleanupOldCacheVersions). Owning the
+      // write site in server.mjs keeps run-mcp.mjs change-free for future
+      // advert tweaks → no stdio-severing full-restart needed.
+      MIXDOG_SUPERVISOR_PID: String(process.pid),
+      MIXDOG_SUPERVISOR_CACHE_DIR: __localRoot,
+      // Stable routing id (see STABLE_TERMINAL_SESSION_ID): pins the daemon's
+      // bySession map to this terminal's LIVE connection across child
+      // reconnects so detached worker results are never delivered to a stale
+      // connection.
+      MIXDOG_SESSION_ID: STABLE_TERMINAL_SESSION_ID,
+    },
+    ...(isWin ? { windowsHide: true } : {}),
+  });
+
+  if (isWin && proc.pid) {
+    try {
+      const ps = `$p = Get-Process -Id ${Number(proc.pid)} -ErrorAction SilentlyContinue; if ($p) { $p.PriorityClass = 'BelowNormal' }`;
+      const encoded = Buffer.from(ps, 'utf16le').toString('base64');
+      execSync(`powershell.exe -NoProfile -EncodedCommand ${encoded}`, {
+        stdio: 'ignore',
+        windowsHide: true,
+        timeout: 3000,
+      });
+    } catch {}
+  }
+
+  proc.stdout.setEncoding('utf8');
+  proc.stdout.on('data', (chunk) => {
+    stdoutBuf += chunk;
+    stdoutBuf = drainBuffer(stdoutBuf, handleChildLine);
+    // Unbounded-line guard: if the residual unterminated tail exceeds the
+    // cap, the child is producing a frame too large to be legitimate (or
+    // never emitting a newline). Kill the child so handleChildGone can
+    // respawn it cleanly, and drop the corrupted buffer.
+    if (Buffer.byteLength(stdoutBuf, 'utf8') > MAX_LINE_BYTES) {
+      supLog(`[child-stdout-overflow] bytes=${Buffer.byteLength(stdoutBuf, 'utf8')} cap=${MAX_LINE_BYTES} — killing child`);
+      stdoutBuf = '';
+      try { proc?.kill(); } catch {}
+    }
+  });
+
+  // child stderr ring buffer — capped at STDERR_TAIL_BYTES; older bytes
+  // are dropped from the head. Each chunk is mirrored to supervisor's own
+  // stderr so the user-visible inherit-equivalent passthrough is preserved.
+  childStderrBuf = '';
+  proc.stderr.setEncoding('utf8');
+  proc.stderr.on('data', (chunk) => {
+    try { process.stderr.write(chunk); } catch {}
+    childStderrBuf += chunk;
+    if (childStderrBuf.length > STDERR_TAIL_BYTES) {
+      childStderrBuf = childStderrBuf.slice(-STDERR_TAIL_BYTES);
+    }
+  });
+
+  proc.on('exit', (code, signal) => {
+    handleChildGone({
+      tag: `exit code=${code}`,
+      log: `child exit code=${code} signal=${signal}`,
+      exitCode: code || 0,
+      signal,
+    });
+  });
+
+  proc.on('error', (err) => {
+    handleChildGone({
+      tag: 'spawn failed',
+      log: `child spawn error: ${err && err.message}`,
+      exitCode: 1,
+      signal: null,
+    });
+  });
+
+  // Async write failures to a dying child's stdin (EPIPE/EOF) surface as a
+  // stream 'error' event, NOT via the synchronous try/catch in _flushChild.
+  // Without this handler the supervisor crashes (uncaught) during dev-sync
+  // full-restart when a queued client line is flushed to the just-killed
+  // child. handleChildGone (exit/error) owns respawn; here we only swallow.
+  proc.stdin.on('error', (err) => {
+    supLog(`[child-stdin-error] ${err && err.message || err}`);
+  });
+}
+
+function killChild(fast = false) {
+  supLog(`[supervisor-killChild] entered shuttingDown=${shuttingDown} fast=${fast}`);
+  if (shuttingDown) return;
+  shuttingDown = true;
+  clearTimeout(respawnTimer);
+  respawnTimer = null;
+  if (!proc) {
+    process.exit(0);
+    return;
+  }
+  // Graceful shutdown: write "shutdown\n" to fd-3 control pipe → child detects the command and
+  // shuts down gracefully. fd-3 is dedicated to lifecycle control and independent of MCP stdio
+  // transport — so transient stdin events from the MCP host can never trigger shutdown.
+  // fast=true (stdin-EOF/dev-sync path): replacement child is identical, no flush owed —
+  // shrink the two-children respawn window. Full timeout retained for SIGTERM.
+  const GRACEFUL_TIMEOUT_MS = fast ? 2000 : 10000;
+  const pid = proc.pid;
+  try {
+    const ctrlFd = proc.stdio && proc.stdio[3];
+    if (ctrlFd && typeof ctrlFd.end === 'function') {
+      ctrlFd.end('shutdown\n');
+      process.stderr.write(`[run-mcp] sent shutdown to control fd (pid=${pid}) — signalling graceful shutdown\n`);
+    } else {
+      process.stderr.write(`[run-mcp] WARN: control fd unavailable (pid=${pid}) — falling back to SIGTERM\n`);
+      try { proc.kill('SIGTERM'); } catch {}
+    }
+  } catch (e) {
+    process.stderr.write(`[run-mcp] control fd write failed (pid=${pid}): ${e && e.message}\n`);
+  }
+  // Also send SIGINT (Ctrl+C simulation) on non-Windows; on Windows skip (no reliable delivery)
+  if (!isWin) {
+    try { proc.kill('SIGINT'); } catch {}
+  }
+  // Wait up to GRACEFUL_TIMEOUT_MS for clean exit; force-kill only if timeout expires.
+  let exited = false;
+  const forceTimer = setTimeout(() => {
+    if (exited) return;
+    process.stderr.write(`[run-mcp] child did not exit within ${GRACEFUL_TIMEOUT_MS}ms — forcing kill (pid=${pid}) path=force\n`);
+    try {
+      if (isWin && pid) {
+        execSync(`taskkill /F /T /PID ${pid}`, { stdio: 'ignore', windowsHide: true, timeout: 5000 });
+      } else {
+        proc.kill('SIGKILL');
+      }
+    } catch {}
+  }, GRACEFUL_TIMEOUT_MS);
+  proc.once('exit', (code, signal) => {
+    exited = true;
+    clearTimeout(forceTimer);
+    process.stderr.write(`[run-mcp] child exited cleanly (pid=${pid} code=${code} signal=${signal}) path=graceful\n`);
+    process.exit(code || 0);
+  });
+  // process.exit is called by the proc 'exit' handler above once the child terminates.
+}
+
+process.on('SIGTERM', killChild);
+process.on('SIGINT', killChild);
+// stdin EOF = our MCP client closed its end of the pipe (IDE quit, mcp
+// server toggled off, Claude Code restart). The historical fear of
+// "transient stdin events" doesn't apply: stdio close is a hard OS EOF,
+// not a wobble. Letting the supervisor linger past EOF is exactly what
+// produces zombie supervisors across reconnects — the new client spawns
+// a fresh supervisor while the old one keeps running, holding no client,
+// answering nothing. Hook EOF into the existing graceful-shutdown path so
+// the child gets the proper shutdown signal too.
+process.stdin.once('end', () => {
+  process.stderr.write('[run-mcp] stdin EOF — client disconnected; initiating graceful shutdown\n');
+  try { killChild(true); } catch { process.exit(0); }
+});
+process.stdin.once('close', () => {
+  process.stderr.write('[run-mcp] stdin closed — initiating graceful shutdown\n');
+  try { killChild(true); } catch { process.exit(0); }
+});
+let _HEARTBEAT_FILE = null;
+process.on('exit', (code) => {
+  try { supLog(`[supervisor-exit] code=${code} shuttingDown=${shuttingDown}`); } catch {}
+  try { if (_HEARTBEAT_FILE) fs.unlinkSync(_HEARTBEAT_FILE); } catch {}
+});
+process.on('uncaughtException', (err) => {
+  try { supLog(`[supervisor-uncaught] ${err?.stack || err?.message || err}`); } catch {}
+  flushPendingClientErrors('uncaught exception');
+  try { killChild(); } catch {}
+  process.exit(1);
+});
+function _isSupervisorFatal(err) {
+  const code = err?.code;
+  return code === 'EPIPE' || code === 'EADDRINUSE' || code === 'ENOMEM';
+}
+process.on('unhandledRejection', (reason) => {
+  try { supLog(`[supervisor-unhandled-rejection] ${reason?.stack || reason?.message || reason}`); } catch {}
+  if (_isSupervisorFatal(reason)) {
+    try { supLog(`[supervisor-unhandled-rejection-fatal] code=${reason?.code} — exiting code=1`); } catch {}
+    flushPendingClientErrors('fatal rejection');
+    try { killChild(); } catch {}
+    process.exit(1);
+  }
+});
+
+const _HEARTBEAT_MS = 5000;
+const _HEARTBEAT_DIR = join(os.tmpdir(), 'mixdog');
+_HEARTBEAT_FILE = join(_HEARTBEAT_DIR, `supervisor-heartbeat.${process.pid}.json`);
+const _HEARTBEAT_INDEX_FILE = join(_HEARTBEAT_DIR, 'supervisor-heartbeats.json');
+const _HEARTBEAT_INDEX_LOCK = `${_HEARTBEAT_INDEX_FILE}.lock`;
+let _heartbeatWarnedMultiAt = 0;
+function _heartbeatPidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}
+function _writeJsonAtomic(file, value) {
+  const tmp = `${file}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value));
+  try { return renameWithRetrySync(tmp, file); }
+  catch (err) {
+    try { fs.unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+function _readJsonSafe(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+function _withHeartbeatIndexLock(fn) {
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline) {
+    let fd = null;
+    try {
+      fd = fs.openSync(_HEARTBEAT_INDEX_LOCK, 'wx');
+      try { fs.writeSync(fd, `${process.pid} ${Date.now()}\n`); } catch {}
+      try { return fn(); }
+      finally {
+        try { if (fd !== null) fs.closeSync(fd); } catch {}
+        try { fs.unlinkSync(_HEARTBEAT_INDEX_LOCK); } catch {}
+      }
+    } catch (err) {
+      try { if (fd !== null) fs.closeSync(fd); } catch {}
+      if (!RENAME_RETRY_CODES.has(err?.code)) throw err;
+      try {
+        const st = fs.statSync(_HEARTBEAT_INDEX_LOCK);
+        if (Date.now() - st.mtimeMs > _HEARTBEAT_MS * 3) {
+          try { fs.unlinkSync(_HEARTBEAT_INDEX_LOCK); } catch {}
+          continue;
+        }
+      } catch {}
+      sleepSync(25 + Math.floor(Math.random() * 35));
+    }
+  }
+  return false;
+}
+function _writeSupervisorHeartbeat() {
+  try {
+    fs.mkdirSync(_HEARTBEAT_DIR, { recursive: true });
+    const now = Date.now();
+    const payload = {
+      pid: process.pid,
+      ownerLeadPid: process.pid,
+      childPid: proc?.pid ?? null,
+      pendingClientCount: pendingFromClient.size,
+      pendingInternalCount: pendingInternal.size,
+      pendingClientMethods: [...pendingFromClient.values()].map(v => v?.method || 'unknown').slice(0, 8),
+      ts: now,
+      cacheDir: __localRoot,
+      pluginRoot: currentChildPluginRoot,
+      dataDir,
+      ppid: process.ppid,
+    };
+    _writeJsonAtomic(_HEARTBEAT_FILE, payload);
+
+    const supervisors = [];
+    for (const ent of fs.readdirSync(_HEARTBEAT_DIR, { withFileTypes: true })) {
+      if (!ent.isFile()) continue;
+      if (!/^supervisor-heartbeat\.\d+\.json$/.test(ent.name)) continue;
+      const file = join(_HEARTBEAT_DIR, ent.name);
+      const entry = _readJsonSafe(file);
+      const pid = Number(entry?.ownerLeadPid ?? entry?.pid);
+      const fresh = Number.isFinite(entry?.ts) && now - Number(entry.ts) <= _HEARTBEAT_MS * 6;
+      if (!_heartbeatPidAlive(pid) || !fresh) {
+        try { fs.unlinkSync(file); } catch {}
+        continue;
+      }
+      supervisors.push({ ...entry, pid, ownerLeadPid: pid });
+    }
+    supervisors.sort((a, b) => Number(a.pid) - Number(b.pid));
+    _withHeartbeatIndexLock(() => _writeJsonAtomic(_HEARTBEAT_INDEX_FILE, { updatedAt: now, supervisors }));
+    if (supervisors.length > 1 && now - _heartbeatWarnedMultiAt > 60000) {
+      _heartbeatWarnedMultiAt = now;
+      const pids = supervisors.map(s => s.pid).join(',');
+      const msg = `[heartbeat] multi-supervisor active count=${supervisors.length} pids=${pids}`;
+      supLog(msg);
+      try { process.stderr.write(`[run-mcp] ${msg}\n`); } catch {}
+    }
+  } catch (e) { supLog(`[heartbeat-error] ${e?.message || e}`); }
+}
+const _heartbeatTimer = setInterval(_writeSupervisorHeartbeat, _HEARTBEAT_MS);
+_heartbeatTimer.unref?.();
+_writeSupervisorHeartbeat();
+
+// Liveness pong handler. Returns true when `id` is the in-flight liveness
+// ping's reply: the response path is proven healthy, so reset the miss
+// counter and back off re-probing for one STALL_PROBE_AFTER_MS window (a
+// genuinely long tool keeps the call pending but the path is fine).
+function _maybeResolveLivenessPong(id) {
+  if (_livenessPingId === null || id !== _livenessPingId) return false;
+  _livenessPingId = null;
+  _livenessMisses = 0;
+  _livenessQuietUntil = Date.now() + STALL_PROBE_AFTER_MS;
+  return true;
+}
+
+// Record one unanswered/failed liveness probe. On STALL_MAX_MISSES in a row the
+// response path is dead: SIGTERM the child ONLY (not killChild, which exits the
+// supervisor and severs the unrecoverable stdio bridge) so proc 'exit' →
+// handleChildGone flushes pending with a retry error and respawns a fresh thin
+// client. Both miss sources — an unanswered pong AND an unwritable child stdin
+// while the process lingers alive — funnel here so neither can hang pending
+// calls forever.
+function _recordLivenessMiss(reason) {
+  _livenessMisses += 1;
+  supLog(`[liveness] ${reason} — miss ${_livenessMisses}/${STALL_MAX_MISSES} (pendingClient=${pendingFromClient.size})`);
+  if (_livenessMisses < STALL_MAX_MISSES) return;
+  const _n = pendingFromClient.size;
+  _livenessMisses = 0;
+  const m = `[liveness] response path dead (${STALL_MAX_MISSES} missed pings) — recycling child to unblock ${_n} pending client call(s)`;
+  supLog(m);
+  try { process.stderr.write(`[run-mcp] ${m}\n`); } catch {}
+  try { proc?.kill('SIGTERM'); } catch {}
+}
+
+// Stall watchdog tick (shares the heartbeat cadence). Invariant: a live child
+// answers an MCP `ping` promptly. When a client call has been pending past
+// STALL_PROBE_AFTER_MS, send one ping down the same path; if it goes
+// unanswered STALL_MAX_MISSES times in a row, the response path is dead —
+// SIGTERM the child so handleChildGone flushes pending (retry error) and
+// respawns. Never aborts a healthy call: async tools don't block the child's
+// event loop, so the pong still round-trips while the tool runs.
+function _livenessTick() {
+  if (shuttingDown) return;
+  const now = Date.now();
+  // Resolve an outstanding ping verdict first.
+  if (_livenessPingId !== null) {
+    if (now - _livenessPingSentAt < PING_TIMEOUT_MS) return; // still waiting
+    pendingInternal.delete(_livenessPingId);
+    _livenessPingId = null;
+    _recordLivenessMiss(`ping unanswered after ${now - _livenessPingSentAt}ms`);
+    return;
+  }
+  // Arm a probe only when a client call has genuinely waited too long.
+  if (pendingFromClient.size === 0) { _livenessMisses = 0; return; }
+  if (!proc || !childHasResponded || _childDraining || _clientDraining) return;
+  if (now < _livenessQuietUntil) return;
+  let oldest = Infinity;
+  for (const v of pendingFromClient.values()) {
+    const t = Number(v?.ts);
+    if (Number.isFinite(t) && t < oldest) oldest = t;
+  }
+  if (!Number.isFinite(oldest) || now - oldest < STALL_PROBE_AFTER_MS) return;
+  const id = internalIdSeq--;
+  pendingInternal.add(id);
+  _livenessPingId = id;
+  _livenessPingSentAt = now;
+  const ok = writeToChild(JSON.stringify({ jsonrpc: '2.0', id, method: 'ping' }));
+  if (ok) {
+    supLog(`[liveness] probing child — oldest pending client call ${now - oldest}ms (pendingClient=${pendingFromClient.size})`);
+  } else {
+    // Write path itself unusable (child stdin gone/non-writable while the
+    // process lingers): count it as a miss so repeated failures recycle.
+    pendingInternal.delete(id);
+    _livenessPingId = null;
+    _recordLivenessMiss('ping write rejected');
+  }
+}
+const _livenessTimer = setInterval(_livenessTick, _HEARTBEAT_MS);
+_livenessTimer.unref?.();
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  stdinBuf += chunk;
+  stdinBuf = drainBuffer(stdinBuf, handleClientLine);
+  // Unbounded-line guard: a client never legitimately sends a single
+  // JSON-RPC frame larger than the cap. Drop the buffer (cannot kill the
+  // client) and surface an anchor in supervisor.log.
+  if (Buffer.byteLength(stdinBuf, 'utf8') > MAX_LINE_BYTES) {
+    supLog(`[client-stdin-overflow] bytes=${Buffer.byteLength(stdinBuf, 'utf8')} cap=${MAX_LINE_BYTES} — dropping buffer`);
+    stdinBuf = '';
+  }
+});
+spawnChild();
+
+// Parent (Claude Code) death watchdog — replaces the old stdin-EOF
+// lifecycle signal that was prone to transient close during boot.
+// process.kill(pid, 0) probes liveness without sending a signal.
+const initialPpid = process.ppid;
+if (initialPpid && initialPpid !== 1) {
+  const parentWatch = setInterval(() => {
+    try {
+      process.kill(initialPpid, 0);
+    } catch {
+      process.stderr.write(`[run-mcp] parent pid=${initialPpid} no longer alive — initiating graceful shutdown\n`);
+      clearInterval(parentWatch);
+      killChild();
+    }
+  }, 5000);
+  parentWatch.unref();
+}