mixdog 0.9.21 → 0.9.23

package/README.md

@@ -23,7 +23,7 @@ mixdog
 ```
 
 First run walks you through onboarding: provider auth, model pick, and
-workflow setup. Re-run it anytime with `mixdog --onboarding`.
+workflow setup.
 
 ## Terminal-Bench 2.1 — 89.9% (self-reported)
 
@@ -117,9 +117,6 @@ mixdog --readonly
 
 # Enable remote/channel mode for this session
 mixdog --remote
-
-# Re-run first-run setup
-mixdog --onboarding
 ```
 
 Headless role mode is also supported:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.21",
+  "version": "0.9.23",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",

package/scripts/channel-daemon-smoke.mjs

@@ -0,0 +1,165 @@
+// Scripted two-client simulation for the machine-global channels daemon
+// transport (no Discord token needed — the channels runtime is stubbed).
+//
+// Verifies the transport + attach client contracts that later slices depend on:
+//   1. two TUIs attach to ONE daemon and each get an independent SSE stream;
+//   2. tool calls round-trip per client and carry the caller's leadPid;
+//   3. notifies are TARGETED (never broadcast) to the routing-pointer client;
+//   4. a bind-intent call (rebind_current_transcript) moves the pointer;
+//   5. once every client deregisters, the daemon self-shutdown fires.
+//
+// Run: node scripts/channel-daemon-smoke.mjs
+import os from 'node:os';
+import path from 'node:path';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createChannelDaemonTransport } from '../src/standalone/channel-daemon-transport.mjs';
+import { attachToDaemon } from '../src/standalone/channel-daemon-client.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const STUB_ENTRY = path.join(HERE, 'channel-daemon-stub.mjs');
+
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+const waitFor = async (fn, ms = 1500) => {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { if (fn()) return true; await delay(20); }
+  return fn();
+};
+let failures = 0;
+function check(label, cond) {
+  const ok = !!cond;
+  if (!ok) failures++;
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${label}`);
+}
+
+async function main() {
+  const tmp = mkdtempSync(path.join(os.tmpdir(), 'mixdog-daemon-smoke-'));
+  const discoveryPath = path.join(tmp, 'channel-daemon.json');
+  let clientsEmptyFired = false;
+  let sideEffects = 0; // counts non-idempotent 'reply' dispatches
+
+  // Stub channels runtime: echoes the call + the caller identity the transport
+  // resolved, so we can assert per-client leadPid threading.
+  const handleCall = async (name, args, ctx) => {
+    if (name === 'reply') { sideEffects++; await delay(40); } // simulate a side effect
+    return { ok: true, name, args, leadPid: ctx.leadPid };
+  };
+
+  const transport = createChannelDaemonTransport({
+    handleCall,
+    discoveryPath,
+    clientGraceMs: 250,
+    sweepMs: 1000,
+    onClientsEmpty: () => { clientsEmptyFired = true; },
+    log: (m) => process.env.DAEMON_SMOKE_VERBOSE && console.log(`[daemon] ${m}`),
+  });
+  const { port, token } = await transport.start();
+  const discovery = { port, token, pid: process.pid };
+
+  const notA = [];
+  const notB = [];
+  const clientA = await attachToDaemon({ discovery, leadPid: process.pid, cwd: 'A', onNotify: (m) => notA.push(m) });
+  const clientB = await attachToDaemon({ discovery, leadPid: process.pid, cwd: 'B', onNotify: (m) => notB.push(m) });
+  await delay(150); // let both SSE streams attach
+
+  check('two clients registered', transport._clientsForTest.size === 2);
+
+  // (2) calls round-trip per client.
+  const rA = await clientA.call('reload_config', { k: 1 });
+  check('client A call round-trips', rA?.ok === true && rA?.name === 'reload_config');
+  const rB = await clientB.call('fetch', { q: 2 });
+  check('client B call round-trips', rB?.ok === true && rB?.name === 'fetch');
+
+  // (3) notify targets the pointer client. First registrant (A) is the pointer.
+  transport.notify('notifications/claude/channel', { content: 'to-A' });
+  await delay(120);
+  check('notify #1 delivered to A only',
+    notA.length === 1 && notA[0]?.params?.content === 'to-A' && notB.length === 0);
+
+  // (4) bind-intent call moves the pointer to B.
+  await clientB.call('rebind_current_transcript', { transcriptPath: '/tmp/b.jsonl' });
+  transport.notify('notifications/claude/channel', { content: 'to-B' });
+  await delay(120);
+  check('notify #2 delivered to B only after rebind',
+    notB.length === 1 && notB[0]?.params?.content === 'to-B' && notA.length === 1);
+
+  // (fix 1) idempotent replay: two /call with the SAME callId (a retried
+  // transport failure) must run the non-idempotent side-effect exactly once.
+  const dupId = 'dup-call-1';
+  const [d1, d2] = await Promise.all([
+    clientA.call('reply', { n: 1 }, { callId: dupId }),
+    clientA.call('reply', { n: 1 }, { callId: dupId }),
+  ]);
+  check('idempotent replay: same callId → exactly one side-effect',
+    sideEffects === 1 && d1?.ok === true && d2?.ok === true);
+
+  // (5) deregister both → self-shutdown fires after the client grace window.
+  await clientA.close();
+  await clientB.close();
+  await delay(600);
+  check('daemon self-shutdown fired after last client left', clientsEmptyFired === true);
+
+  await transport.stop();
+  try { rmSync(tmp, { recursive: true, force: true }); } catch {}
+
+  await flipTest();
+
+  console.log(failures === 0 ? '\nALL PASS' : `\n${failures} FAILURE(S)`);
+  process.exit(failures === 0 ? 0 : 1);
+}
+
+// Flip coverage: two TUIs attach to ONE daemon via the REAL channel-worker.mjs
+// spawn-or-attach path (against the stub daemon entry — no Discord token). The
+// first worker spawns the daemon; the second attaches to it.
+async function flipTest() {
+  const tmp = mkdtempSync(path.join(os.tmpdir(), 'mixdog-flip-smoke-'));
+  // channel-worker.mjs resolves DAEMON_ENTRY + runtimeRoot at import/call time,
+  // so the env must be set BEFORE importing it.
+  process.env.MIXDOG_RUNTIME_ROOT = tmp;
+  process.env.MIXDOG_DATA_DIR = tmp;
+  process.env.MIXDOG_CHANNEL_DAEMON_ENTRY = STUB_ENTRY;
+  const { createStandaloneChannelWorker } = await import('../src/standalone/channel-worker.mjs');
+  const { readDaemonDiscovery } = await import('../src/standalone/channel-daemon-client.mjs');
+  const discFile = path.join(tmp, 'channel-daemon.json');
+
+  const notA = [];
+  const notB = [];
+  const mk = (onNotify) => createStandaloneChannelWorker({ entry: STUB_ENTRY, rootDir: tmp, dataDir: tmp, cwd: tmp, onNotify });
+  const wA = mk((m) => notA.push(m));
+  const wB = mk((m) => notB.push(m));
+
+  await wA.start(); // spawns the (stub) daemon then attaches
+  await wB.start(); // attaches to the SAME daemon (no second spawn)
+  check('flip: worker A call round-trips', (await wA.execute('reply', { x: 1 }))?.ok === true);
+  check('flip: worker B call round-trips', (await wB.execute('reply', { y: 2 }))?.ok === true);
+
+  // B claims the transcript → routing pointer moves to B; a notify emitted by
+  // the daemon (on A's 'fetch') must reach B only, never both TUIs.
+  await wB.execute('rebind_current_transcript', { transcriptPath: path.join(tmp, 'b.jsonl') });
+  await wA.execute('fetch', { probe: true });
+  await waitFor(() => notB.some((m) => m?.params?.content === 'ping-from-stub'), 1500);
+  check('flip: notify targets the pointer TUI (B) only',
+    notB.some((m) => m?.params?.content === 'ping-from-stub') &&
+    !notA.some((m) => m?.params?.content === 'ping-from-stub'));
+
+  // (fix 1) daemon death mid-session: SIGKILL it, then the surviving client's
+  // next call must transparently respawn + re-attach (bounded retry inside
+  // execute) — no TUI process restart.
+  const beforeKill = readDaemonDiscovery(discFile);
+  if (beforeKill?.pid) { try { process.kill(beforeKill.pid, 'SIGKILL'); } catch {} }
+  await delay(400);
+  let recovered = false;
+  try { recovered = (await wA.execute('reply', { after: 'kill' }))?.ok === true; } catch {}
+  const afterKill = readDaemonDiscovery(discFile);
+  check('flip: call transparently respawns+reattaches after daemon death',
+    recovered === true && !!afterKill?.pid && afterKill.pid !== beforeKill?.pid);
+
+  await wA.stop();
+  await wB.stop();
+  await delay(700);
+  const disc = readDaemonDiscovery(discFile);
+  check('flip: daemon self-shutdown after last TUI detaches', disc === null);
+  try { rmSync(tmp, { recursive: true, force: true }); } catch {}
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });

package/scripts/channel-daemon-stub.mjs

@@ -0,0 +1,69 @@
+// Stub channels daemon for the flip smoke: same lifecycle contract as
+// src/standalone/channel-daemon.mjs (pid-verified singleton claim, HTTP+SSE
+// transport, discovery file, ready handshake, client-grace self-shutdown) but
+// with a STUB runtime instead of worker-main — no Discord token needed. The
+// real channel-worker.mjs spawn-or-attach path forks THIS via
+// MIXDOG_CHANNEL_DAEMON_ENTRY, so the flip is exercised end to end.
+process.env.MIXDOG_WORKER_MODE = process.env.MIXDOG_WORKER_MODE || '1';
+
+import os from 'node:os';
+import path from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { claimSingletonOwner, releaseSingletonOwner } from '../src/runtime/shared/singleton-owner.mjs';
+import { createChannelDaemonTransport } from '../src/standalone/channel-daemon-transport.mjs';
+
+function runtimeRoot() {
+  return process.env.MIXDOG_RUNTIME_ROOT
+    ? path.resolve(process.env.MIXDOG_RUNTIME_ROOT)
+    : path.join(os.tmpdir(), 'mixdog');
+}
+const RUNTIME_ROOT = runtimeRoot();
+const DATA_DIR = process.env.MIXDOG_DATA_DIR ? path.resolve(process.env.MIXDOG_DATA_DIR) : RUNTIME_ROOT;
+const DISCOVERY_PATH = path.join(RUNTIME_ROOT, 'channel-daemon.json');
+const OWNER_PATH = path.join(DATA_DIR, 'channel-daemon-owner.json');
+
+function log(line) { if (process.env.DAEMON_SMOKE_VERBOSE) process.stderr.write(`[stub-daemon] ${line}\n`); }
+
+let transport = null;
+let shuttingDown = false;
+async function shutdown(reason, code = 0) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  try { await transport?.stop?.(); } catch {}
+  try { releaseSingletonOwner(OWNER_PATH, process.pid); } catch {}
+  process.exit(code);
+}
+
+async function main() {
+  try { mkdirSync(RUNTIME_ROOT, { recursive: true }); } catch {}
+  const claim = claimSingletonOwner(OWNER_PATH, { kind: 'channel-runtime-daemon', pid: process.pid, meta: { cwd: process.cwd() } });
+  if (!claim.owned) { process.exit(0); } // race loser → spawner attaches to winner
+  process.on('exit', () => { try { releaseSingletonOwner(OWNER_PATH, process.pid); } catch {} });
+
+  // Stub runtime: echo the call + caller identity, and (for 'fetch') emit a
+  // notify AFTER responding so the smoke can assert targeted routing.
+  const handleCall = async (name, args, ctx) => {
+    if (name === 'fetch') {
+      setTimeout(() => { try { transport.notify('notifications/claude/channel', { content: 'ping-from-stub' }); } catch {} }, 20);
+    }
+    return { ok: true, name, args, leadPid: ctx.leadPid };
+  };
+
+  transport = createChannelDaemonTransport({
+    handleCall,
+    discoveryPath: DISCOVERY_PATH,
+    clientGraceMs: 250,
+    sweepMs: 1000,
+    log,
+    onClientsEmpty: () => { void shutdown('no live clients'); },
+  });
+  const { port, token } = await transport.start();
+  if (process.send) { try { process.send({ type: 'ready', port, token }); } catch {} }
+  log(`ready port=${port} pid=${process.pid}`);
+}
+
+process.on('SIGTERM', () => { void shutdown('SIGTERM'); });
+process.on('SIGINT', () => { void shutdown('SIGINT'); });
+process.on('message', (msg) => { if (msg && msg.type === 'shutdown') void shutdown('IPC shutdown'); });
+
+main().catch((err) => { log(`fatal: ${err?.stack || err}`); void shutdown('fatal', 2); });

package/scripts/statusline-quota-hysteresis-test.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { acceptQuotaSnapshot } from '../src/ui/statusline.mjs';
+
+// Monotonic hysteresis for the 5H/7D usage segment: once a value has rendered,
+// an OLDER shared-cache snapshot (written by another mixdog instance) must not
+// displace it, but a NEWER one — or confirmed own-instance live data — must.
+test('older shared-cache snapshot is rejected, newer is accepted', () => {
+  const displayedOwnLive = { segments: ['5H 12%'], asOf: 2000, owned: true };
+
+  // Another instance overwrites the shared cache with an OLDER snapshot →
+  // metricsMatch flips false, source alternates to that unowned older snapshot.
+  assert.equal(
+    acceptQuotaSnapshot(displayedOwnLive, { asOf: 1000, owned: false }),
+    false,
+    'older unowned snapshot must not displace displayed own-live value',
+  );
+
+  // A strictly newer shared snapshot is allowed to advance the value.
+  assert.equal(
+    acceptQuotaSnapshot(displayedOwnLive, { asOf: 3000, owned: false }),
+    true,
+    'newer snapshot must replace the displayed value',
+  );
+});
+
+test('own-instance live data always wins; empty timestamps preserve prior behavior', () => {
+  const displayedShared = { segments: ['5H 12%'], asOf: 5000, owned: false };
+  // Own-instance live data replaces even an apparently newer shared snapshot.
+  assert.equal(acceptQuotaSnapshot(displayedShared, { asOf: 1, owned: true }), true);
+  // Nothing displayed yet → accept.
+  assert.equal(acceptQuotaSnapshot(undefined, { asOf: 1000, owned: false }), true);
+  // No comparable timestamps → accept (byte-for-byte prior behavior).
+  assert.equal(acceptQuotaSnapshot({ asOf: 0, owned: true }, { asOf: 0, owned: false }), true);
+  // Shared→shared same asOf → accept (idempotent refresh).
+  assert.equal(acceptQuotaSnapshot({ asOf: 2000, owned: false }, { asOf: 2000, owned: false }), true);
+});

package/scripts/tool-smoke.mjs

@@ -906,7 +906,7 @@ const fullDefaults = defaultDeferredToolNames(smokeCatalog, 'full');
 if (fullDefaults.size !== 10) {
   throw new Error(`full default surface should stay 10 tools, got ${fullDefaults.size}: ${[...fullDefaults].join(', ')}`);
 }
-for (const name of ['read', 'code_graph', 'grep', 'find', 'glob', 'list', 'apply_patch', 'explore', 'Skill', 'tool_search']) {
+for (const name of ['read', 'code_graph', 'grep', 'find', 'glob', 'list', 'apply_patch', 'explore', 'Skill', 'load_tool']) {
   assertHas(fullDefaults, name);
 }
 for (const name of ['shell', 'task', 'agent', 'recall', 'search', 'web_fetch', 'cwd']) {
@@ -917,7 +917,7 @@ const leadDefaults = defaultDeferredToolNames(smokeCatalog, 'lead');
 if (leadDefaults.size !== 16) {
   throw new Error(`lead default surface should stay 16 tools for this static catalog, got ${leadDefaults.size}: ${[...leadDefaults].join(', ')}`);
 }
-for (const name of ['read', 'code_graph', 'grep', 'find', 'glob', 'list', 'shell', 'task', 'apply_patch', 'explore', 'agent', 'recall', 'search', 'web_fetch', 'Skill', 'tool_search']) {
+for (const name of ['read', 'code_graph', 'grep', 'find', 'glob', 'list', 'shell', 'task', 'apply_patch', 'explore', 'agent', 'recall', 'search', 'web_fetch', 'Skill', 'load_tool']) {
   assertHas(leadDefaults, name);
 }
 if (TOOL_SEARCH_TOOL.annotations?.agentHidden !== true) {
@@ -943,7 +943,7 @@ for (const [name, cap] of [
   ['recall', 2400],
   ['search', 3200],
   ['web_fetch', 900],
-  ['tool_search', 900],
+  ['load_tool', 900],
 ]) {
   const tool = smokeCatalog.find((item) => item?.name === name);
   const size = toolSchemaSize(tool);
@@ -954,7 +954,7 @@ const readonlyDefaults = defaultDeferredToolNames(smokeCatalog, 'readonly');
 if (readonlyDefaults.size !== 9) {
   throw new Error(`readonly default surface should stay 9 tools, got ${readonlyDefaults.size}: ${[...readonlyDefaults].join(', ')}`);
 }
-for (const name of ['read', 'code_graph', 'grep', 'find', 'glob', 'list', 'explore', 'Skill', 'tool_search']) {
+for (const name of ['read', 'code_graph', 'grep', 'find', 'glob', 'list', 'explore', 'Skill', 'load_tool']) {
   assertHas(readonlyDefaults, name);
 }
 for (const name of ['apply_patch', 'agent', 'shell']) {
@@ -1359,8 +1359,8 @@ setInternalToolsProvider({
       throw new Error(`agent context must not inject environment reminder: ${visible.slice(0, 1200)}`);
     }
     const workerToolNames = (workerSession.tools || []).map((tool) => tool?.name).filter(Boolean);
-    if (workerToolNames.includes('tool_search')) {
-      throw new Error(`agent session schema must not expose deferred tool_search: ${workerToolNames.join(', ')}`);
+    if (workerToolNames.includes('load_tool')) {
+      throw new Error(`agent session schema must not expose deferred load_tool: ${workerToolNames.join(', ')}`);
     }
     for (const name of ['shell', 'task']) {
       if (!workerToolNames.includes(name)) {
@@ -1420,8 +1420,8 @@ setInternalToolsProvider({
     if (JSON.stringify(writeTools) !== JSON.stringify(expectedWriteTools)) {
       throw new Error(`read-write agent schema must be fixed allow-list: expected=${expectedWriteTools.join(', ')} actual=${writeTools.join(', ')}`);
     }
-    if (readTools.includes('tool_search') || writeTools.includes('tool_search')) {
-      throw new Error(`agent session fixed schemas must omit tool_search: read=${readTools.join(', ')} write=${writeTools.join(', ')}`);
+    if (readTools.includes('load_tool') || writeTools.includes('load_tool')) {
+      throw new Error(`agent session fixed schemas must omit load_tool: read=${readTools.join(', ')} write=${writeTools.join(', ')}`);
     }
     if (readTools.includes('shell')) {
       throw new Error(`read agent schema must omit shell: read=${readTools.join(', ')}`);
@@ -1846,25 +1846,38 @@ if (!/Use after search/i.test(webFetchTool?.description || '') || !webFetchProps
 if (!/offset/i.test(webFetchProps.startIndex?.description || '') || !/Maximum characters/i.test(webFetchProps.maxLength?.description || '')) {
   throw new Error('web_fetch schema must describe paging window fields');
 }
-if (!/deferred tools/i.test(TOOL_SEARCH_TOOL.description || '') || !TOOL_SEARCH_TOOL.inputSchema?.properties?.select) {
-  throw new Error('tool_search schema must preserve selection guidance and select field');
+if (!/deferred tools/i.test(TOOL_SEARCH_TOOL.description || '')
+  || !TOOL_SEARCH_TOOL.inputSchema?.properties?.names
+  || !TOOL_SEARCH_TOOL.inputSchema?.properties?.select) {
+  throw new Error('load_tool schema must preserve loader guidance plus names + legacy select fields');
 }
 const toolSearchSession = {
   tools: smokeCatalog.filter((tool) => fullDefaults.has(tool?.name)),
   deferredToolCatalog: smokeCatalog.slice(),
   deferredSelectedTools: [...fullDefaults],
 };
-// A plain query is a case-insensitive substring filter over name+description.
-// It lists matches only — it never auto-loads or ranks.
+// load_tool is a pure loader: a free-text query is NOT a search. It loads
+// nothing, returns an error steering to names[], and never activates tools.
 const listQueryResult = JSON.parse(__renderToolSearchForTest({ query: 'shell' }, toolSearchSession, 'full'));
-if (listQueryResult.selected) {
-  throw new Error(`tool_search plain query must not auto-load: ${JSON.stringify(listQueryResult.selected)}`);
+if (listQueryResult.selected || (Array.isArray(listQueryResult.loaded) && listQueryResult.loaded.length)) {
+  throw new Error(`load_tool free-text query must not load: ${JSON.stringify(listQueryResult)}`);
 }
-if (!listQueryResult.matches.some((row) => row.name === 'shell')) {
-  throw new Error(`tool_search plain query should list substring matches: ${JSON.stringify(listQueryResult.matches)}`);
+if (!listQueryResult.error || !/names/i.test(listQueryResult.error)) {
+  throw new Error(`load_tool free-text query must steer to names[]: ${JSON.stringify(listQueryResult)}`);
 }
 if (listQueryResult.activeTools.includes('shell') || (Array.isArray(listQueryResult.discoveredTools) && listQueryResult.discoveredTools.includes('shell'))) {
-  throw new Error(`tool_search plain query must not activate/discover tools: ${JSON.stringify(listQueryResult)}`);
+  throw new Error(`load_tool free-text query must not activate/discover tools: ${JSON.stringify(listQueryResult)}`);
+}
+// names[] is the primary loader input (aliases expand, tools activate).
+const namesLoadResult = JSON.parse(__renderToolSearchForTest({ names: ['shell', 'recall'] }, {
+  tools: smokeCatalog.filter((tool) => fullDefaults.has(tool?.name)),
+  deferredToolCatalog: smokeCatalog.slice(),
+  deferredSelectedTools: [...fullDefaults],
+}, 'full'));
+for (const name of ['shell', 'recall']) {
+  if (!namesLoadResult.activeTools.includes(name) || !namesLoadResult.loaded.includes(name)) {
+    throw new Error(`load_tool names[] must load ${name}: ${JSON.stringify(namesLoadResult)}`);
+  }
 }
 // query "select:a,b" is the explicit query-side loader (aliases expand).
 const bulkSelectResult = JSON.parse(__renderToolSearchForTest({ query: 'select:shell,recall' }, toolSearchSession, 'full'));

package/src/runtime/agent/orchestrator/mcp/child-tree.mjs

@@ -0,0 +1,187 @@
+// Full-tree shutdown for stdio MCP child processes.
+//
+// The MCP SDK's StdioClientTransport.close() closes stdin, waits ~2s, then
+// SIGTERMs / SIGKILLs the *direct* child only. On Windows that maps to
+// TerminateProcess on the spawned wrapper (uvx/npx/uv) and leaves its
+// grandchildren (uv.exe -> mcp-for-unity.exe -> python.exe) orphaned. This
+// module implements the MCP spec shutdown order over the whole process tree:
+// close stdin -> grace wait for voluntary exit -> force-kill the recorded
+// tree (taskkill /T /F on Windows, SIGTERM->SIGKILL of every descendant on
+// POSIX). No external dependencies.
+import { spawn } from 'node:child_process';
+
+const isWin = process.platform === 'win32';
+
+function delay(ms) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, ms);
+        if (t.unref) t.unref();
+    });
+}
+
+// Spawn a helper command and resolve its stdout (empty string on any error).
+function run(cmd, args) {
+    return new Promise((resolve) => {
+        let out = '';
+        let cp;
+        try {
+            cp = spawn(cmd, args, { windowsHide: true });
+        }
+        catch {
+            resolve('');
+            return;
+        }
+        cp.stdout?.on('data', (d) => { out += String(d); });
+        cp.on('error', () => resolve(out));
+        cp.on('close', () => resolve(out));
+    });
+}
+
+// Snapshot the whole process table once: parent map + a per-pid identity
+// token (Windows CreationDate, POSIX lstart) so a later kill can prove a pid
+// number was not recycled onto a different process before signalling it.
+async function enumerate() {
+    const childrenOf = new Map();
+    const tokenOf = new Map();
+    const out = isWin
+        ? await run('powershell.exe', [
+            '-NoProfile', '-NonInteractive', '-Command',
+            `Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId) $($_.CreationDate.ToString('o'))" }`,
+        ])
+        : await run('ps', ['-A', '-o', 'pid=,ppid=,lstart=']);
+    for (const line of out.split(/\r?\n/)) {
+        const m = line.trim().match(/^(\d+)\s+(\d+)(?:\s+(.+))?$/);
+        if (!m) continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        const token = (m[3] || '').trim() || null;
+        if (!childrenOf.has(ppid)) childrenOf.set(ppid, []);
+        childrenOf.get(ppid).push(pid);
+        tokenOf.set(pid, token);
+    }
+    return { childrenOf, tokenOf };
+}
+
+// BFS every descendant pid of rootPid (excludes rootPid).
+function descendantsOf(childrenOf, rootPid) {
+    const result = [];
+    const seen = new Set([rootPid]);
+    const stack = [rootPid];
+    while (stack.length) {
+        const cur = stack.pop();
+        for (const child of childrenOf.get(cur) ?? []) {
+            if (!seen.has(child)) {
+                seen.add(child);
+                result.push(child);
+                stack.push(child);
+            }
+        }
+    }
+    return result;
+}
+
+// Exposed for tests: descendant pid list captured while the tree is intact.
+export async function collectDescendants(rootPid) {
+    const { childrenOf } = await enumerate();
+    return descendantsOf(childrenOf, rootPid);
+}
+
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM => exists but not signalable by us; ESRCH => gone.
+        return Boolean(e && e.code === 'EPERM');
+    }
+}
+
+function waitExit(proc, ms) {
+    if (!proc || proc.exitCode !== null || proc.signalCode !== null) {
+        return Promise.resolve(true);
+    }
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (v) => { if (!done) { done = true; resolve(v); } };
+        const t = setTimeout(() => finish(false), ms);
+        if (t.unref) t.unref();
+        proc.once('exit', () => { clearTimeout(t); finish(true); });
+        proc.once('close', () => { clearTimeout(t); finish(true); });
+    });
+}
+
+// A pid is safe to signal only if its CURRENT identity token equals the one
+// recorded at snapshot time. Both must be present; a gone/recycled pid has a
+// missing or mismatched token and is skipped. Tokens come from batched table
+// reads (Map), so verification is O(1) with zero extra process spawns.
+function stillSame(pid, snapshotToken, currentTokens) {
+    const want = snapshotToken.get(pid);
+    const cur = currentTokens.get(pid);
+    return Boolean(want && cur && want === cur);
+}
+
+// Force-kill the given pids, identity-checked against a batched current-token
+// table captured immediately before signalling so a recycled pid is never hit.
+async function killVerified(pids, snapshotToken, currentTokens) {
+    const verified = pids.filter((pid) => stillSame(pid, snapshotToken, currentTokens));
+    if (verified.length === 0) return;
+    if (isWin) {
+        // /T also reaps any still-live children spawned since enumeration;
+        // every listed /PID was identity-checked just above.
+        const args = ['/F', '/T'];
+        for (const p of verified) args.push('/PID', String(p));
+        await run('taskkill', args);
+        return;
+    }
+    // POSIX: terminate, brief wait, then hard-kill survivors. Re-verify with a
+    // single fresh batched table read (not per-pid) before the SIGKILL pass.
+    for (const p of verified) { try { process.kill(p, 'SIGTERM'); } catch { /* ignore */ } }
+    await delay(500);
+    const { tokenOf: fresh } = await enumerate().catch(() => ({ tokenOf: new Map() }));
+    for (const p of verified) {
+        if (isAlive(p) && stillSame(p, snapshotToken, fresh)) {
+            try { process.kill(p, 'SIGKILL'); } catch { /* ignore */ }
+        }
+    }
+}
+
+/**
+ * Shut down an stdio MCP transport's child process tree per MCP spec order.
+ * Returns false when the transport has no live child (non-stdio / already
+ * exited); true once the tree has been shut down.
+ */
+export async function shutdownStdioChild(transport, { graceMs = 2000 } = {}) {
+    const proc = transport?._process;
+    const pid = (typeof transport?.pid === 'number' ? transport.pid : null) ?? proc?.pid ?? null;
+    if (!pid) return false;
+    const empty = { childrenOf: new Map(), tokenOf: new Map() };
+    const snapshotToken = new Map();
+    // Snapshot #1: tree + identity tokens while it is still fully intact.
+    // Covers children that later get re-parented/orphaned during shutdown.
+    const before = await enumerate().catch(() => empty);
+    const initial = descendantsOf(before.childrenOf, pid);
+    snapshotToken.set(pid, before.tokenOf.get(pid) ?? null);
+    for (const d of initial) snapshotToken.set(d, before.tokenOf.get(d) ?? null);
+    // 1. Close stdin to request a voluntary shutdown.
+    try { proc?.stdin?.end(); } catch { /* ignore */ }
+    // 2. Grace period for the server to exit on its own.
+    const exited = await waitExit(proc, graceMs);
+    // 3. Snapshot #2 after the grace: catches children spawned late during
+    //    shutdown that were absent from the first snapshot.
+    const after = await enumerate().catch(() => empty);
+    const fresh = descendantsOf(after.childrenOf, pid);
+    for (const d of fresh) {
+        if (!snapshotToken.has(d)) snapshotToken.set(d, after.tokenOf.get(d) ?? null);
+    }
+    // 4. Candidate set = union of both snapshots' descendants; add the root
+    //    only when it did NOT exit on its own (skip stale-root kill per spec).
+    const candidates = new Set(initial);
+    for (const d of fresh) candidates.add(d);
+    if (!exited) candidates.add(pid);
+    if (candidates.size === 0) return true;
+    // 5. Force-kill. Snapshot #2 is the pre-kill verify table (captured just
+    //    now, immediately before signalling) — no per-pid queries.
+    await killVerified([...candidates], snapshotToken, after.tokenOf);
+    return true;
+}