droid-mode 0.0.2 → 0.0.4

package/README.md

@@ -22,6 +22,61 @@ Droid Mode lets you:
 2. Access them **on-demand** through progressive discovery
 3. Run procedural workflows that call MCP tools **outside** the LLM loop
 
+## Performance: Daemon Mode
+
+Droid Mode includes an optional daemon that maintains persistent MCP connections, dramatically reducing latency for repeated operations.
+
+### Benchmark Results
+
+| Mode | 10 Operations | Per-Call (warm) | Speedup |
+|------|---------------|-----------------|---------|
+| Without Daemon | 29.9s | ~2,900ms | baseline |
+| **With Daemon** | **10.2s** | **~620ms** | **4.7x faster** |
+
+### How It Works
+
+Each `dm call` normally spawns a new process, initializes the MCP connection, executes the tool, and exits. This adds ~2.5s overhead per call.
+
+The daemon maintains a connection pool. After the first call to a server, subsequent calls reuse the existing connection:
+
+```
+┌──────────────────────────────────────────────────┐
+│            dm daemon (background)                │
+│  Connection Pool:                                │
+│  ├── context-repo: connected (15 calls)         │
+│  ├── convex: idle                               │
+│  └── firecrawl: connected (3 calls)             │
+└──────────────────────────────────────────────────┘
+                    │
+            dm call --server X
+                    ↓
+         ~620ms instead of ~2,900ms
+```
+
+### Usage
+
+```bash
+# Start daemon (runs in background)
+dm daemon start
+
+# All dm call commands automatically use daemon
+dm call list_collections --server context-repo  # ~620ms
+
+# Check connection status
+dm daemon status
+
+# Stop daemon when done
+dm daemon stop
+```
+
+### When to Use Daemon
+
+- **Multi-operation workflows** — Running several tool calls in sequence
+- **Interactive development** — Testing and iterating with MCP tools
+- **Benchmarking** — Accurate timing without spawn overhead
+
+The daemon is optional. Without it, Droid Mode works exactly as before.
+
 ## Installation
 
 ```bash
@@ -113,6 +168,9 @@ dm run --server context-repo \
 | `dm call <tool> --server <name>` | Call a tool directly |
 | `dm run --workflow <file> --tools <a,b> --server <name>` | Execute workflow |
 | `dm doctor --server <name>` | Diagnose connection |
+| `dm daemon start` | Start background daemon |
+| `dm daemon stop` | Stop daemon |
+| `dm daemon status` | Show connection pool status |
 
 ## Design Philosophy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-mode",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Progressive Code-Mode MCP integration for Factory.ai Droid - access MCP tools without context bloat",
   "type": "module",
   "main": "dist/cli.js",

package/templates/skills/droid-mode/README.md

@@ -150,6 +150,40 @@ All artifacts written to `.factory/droid-mode/`:
 
 ---
 
+## Daemon Mode (Performance)
+
+The daemon maintains persistent MCP connections, reducing call latency by ~5x.
+
+### Benchmark Results
+
+| Mode | Per-Call (warm) | 10 Operations |
+|------|-----------------|---------------|
+| Without Daemon | ~2,900ms | 29.9s |
+| **With Daemon** | **~620ms** | **10.2s** |
+
+### Usage
+
+```bash
+# Start daemon (runs in background)
+dm daemon start
+
+# All dm call commands automatically use daemon
+dm call list_collections --server context-repo
+
+# Check connection status
+dm daemon status
+
+# Stop daemon
+dm daemon stop
+
+# Bypass daemon for a single call
+dm call tool --server X --no-daemon
+```
+
+The daemon is optional—without it, everything works as before.
+
+---
+
 ## Security Posture
 
 - Credentials remain in `mcp.json` env/headers, not in prompts

package/templates/skills/droid-mode/SKILL.md

@@ -35,6 +35,15 @@ Servers with `disabled: true` in `mcp.json` are **fully available** to droid-mod
 
 This is the entire point of the skill.
 
+## Idempotency
+
+All droid-mode commands are safe to rerun:
+- `dm servers` / `dm index` — read-only discovery
+- `dm hydrate` — overwrites previous hydration (timestamped)
+- `dm run` — each run creates a new timestamped trace
+
+No cleanup required between invocations.
+
 ## Workflow Example
 
 ```js
@@ -57,13 +66,27 @@ After using droid-mode, verify:
 - [ ] Artifacts exist in `.factory/droid-mode/` (cache, hydrated, runs)
 - [ ] Workflow trace shows no errors (`runs/<server>/<ts>/run.json`)
 
+## Proof Artifacts
+
+After completing a workflow, produce evidence:
+
+- **Discovery proof**: Screenshot or paste of `dm index --server X` output
+- **Hydration proof**: Confirm `types.d.ts` exists and compiles (`tsc --noEmit`)
+- **Execution proof**: Link to `run.json` trace showing `error: false`
+- **For PRs**: Include trace file or summary in PR description
+
 ## Success Criteria
 
-The skill completes successfully when:
+The skill completes successfully when these artifacts exist:
 
-- Tool discovery returned results (`dm index` shows tools)
-- Hydrated schemas are valid (`types.d.ts` generated)
-- Workflow executed without sandbox errors (trace shows `error: false`)
+| Artifact | Path | Content |
+|----------|------|---------|
+| Tool cache | `.factory/droid-mode/cache/<server>/tools.json` | Array of tool objects |
+| Hydrated schemas | `.factory/droid-mode/hydrated/<server>/<ts>/schemas.json` | Full JSON schemas |
+| TypeScript types | `.factory/droid-mode/hydrated/<server>/<ts>/types.d.ts` | Generated type definitions |
+| Execution trace | `.factory/droid-mode/runs/<server>/<ts>/run.json` | `{ error: false, result: ... }` |
+
+Verify with: `dm doctor --server X` (should exit 0)
 
 ## Fallbacks
 
@@ -88,6 +111,8 @@ All outputs written to `.factory/droid-mode/`:
 - `hydrated/<server>/<ts>/` — schemas + types
 - `runs/<server>/<ts>/run.json` — execution trace
 
+All JSON artifacts are machine-parseable for downstream skill chaining. Workflows can read `tools.json` or `run.json` to inform subsequent steps.
+
 ## Supporting Files
 
 - `bin/dm` — CLI entry point
@@ -95,3 +120,14 @@ All outputs written to `.factory/droid-mode/`:
 - `examples/workflows/` — sample workflow files
 - `examples/hooks/` — PreToolUse hook examples
 - `README.md` — full documentation
+
+## References
+
+For project-specific conventions, see:
+- `AGENTS.md` — project-wide agent guidance (if present)
+- `mcp.json` — MCP server configuration
+- `.factory/skills/*/SKILL.md` — related skills that may chain with droid-mode
+
+For droid-mode internals:
+- `README.md` — full CLI documentation
+- `examples/` — sample workflows and hooks

package/templates/skills/droid-mode/bin/dm

@@ -8,6 +8,7 @@ import { getToolsCached, compactToolSummaries } from "../lib/tool_index.mjs";
 import { searchTools } from "../lib/search.mjs";
 import { hydrateTools } from "../lib/hydrate.mjs";
 import { createToolApi, executeWorkflow, writeRunArtifact } from "../lib/run.mjs";
+import { isDaemonRunning, callViaDaemon, getDaemonStatus, shutdownDaemon, startDaemon } from "../lib/daemon_client.mjs";
 
 function usage() {
   return `
@@ -20,7 +21,12 @@ Usage:
   dm search  "<query>" --server <name> [--limit 8] [--refresh] [--json]
   dm hydrate <tool1> <tool2> ... --server <name> [--out <dir>] [--refresh] [--json]
   dm run     --workflow <file.js> --tools <a,b,...> --server <name> [--retries 3] [--timeout-ms 300000] [--json]
-  dm call    <tool> --server <name> [--args-json '{...}'] [--args-file path.json] [--json]
+  dm call    <tool> --server <name> [--args-json '{...}'] [--args-file path.json] [--json] [--no-daemon]
+
+Daemon (persistent connections for faster calls):
+  dm daemon start            → Start background daemon
+  dm daemon stop             → Stop daemon
+  dm daemon status [--json]  → Show connection pool status
 
 Progressive Disclosure Flow:
   1. dm servers              → Discover available MCP servers
@@ -37,6 +43,7 @@ Notes:
 - Servers with 'disabled: true' in mcp.json are fully available here.
   That flag only prevents Droid from loading tools into context.
 - Tool inventory is cached under .factory/droid-mode/cache/<server>/tools.json
+- When daemon is running, 'dm call' uses it automatically (~5x faster).
 `.trim();
 }
 
@@ -386,6 +393,23 @@ async function cmdCall(args) {
     }
   }
 
+  // Try daemon first (unless --no-daemon flag is set)
+  const useDaemon = !args.flags["no-daemon"] && await isDaemonRunning();
+
+  if (useDaemon) {
+    const res = await callViaDaemon({ server: serverName, tool, args: argObj });
+    if (!res.ok) {
+      fail(`Daemon call failed: ${res.error}`);
+    }
+    if (args.flags.json) {
+      process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+      return;
+    }
+    process.stdout.write(JSON.stringify(res.result, null, 2) + "\n");
+    return;
+  }
+
+  // Direct call (no daemon)
   const out = await withClient(serverName, entry, async (client) => {
     const res = await client.callTool({ name: tool, arguments: argObj, timeoutMs: 60_000 });
     return res;
@@ -398,6 +422,75 @@ async function cmdCall(args) {
   process.stdout.write(JSON.stringify(out.structured ?? out.text ?? out.raw, null, 2) + "\n");
 }
 
+async function cmdDaemon(args) {
+  const subcmd = args._[1];
+
+  if (subcmd === "start") {
+    const running = await isDaemonRunning();
+    if (running) {
+      process.stdout.write("Daemon is already running.\n");
+      return;
+    }
+    try {
+      const { pid } = await startDaemon();
+      process.stdout.write(`Daemon started (PID: ${pid})\n`);
+    } catch (err) {
+      fail(`Failed to start daemon: ${err.message}`);
+    }
+    return;
+  }
+
+  if (subcmd === "stop") {
+    const running = await isDaemonRunning();
+    if (!running) {
+      process.stdout.write("Daemon is not running.\n");
+      return;
+    }
+    await shutdownDaemon();
+    process.stdout.write("Daemon stopped.\n");
+    return;
+  }
+
+  if (subcmd === "status") {
+    const running = await isDaemonRunning();
+    if (!running) {
+      if (args.flags.json) {
+        process.stdout.write(JSON.stringify({ running: false }, null, 2) + "\n");
+      } else {
+        process.stdout.write("Daemon is not running.\n");
+      }
+      return;
+    }
+
+    const status = await getDaemonStatus();
+    if (args.flags.json) {
+      process.stdout.write(JSON.stringify({ running: true, ...status }, null, 2) + "\n");
+      return;
+    }
+
+    const uptimeMin = Math.floor((status.uptime || 0) / 60000);
+    process.stdout.write(`Daemon running (uptime: ${uptimeMin}m)\n\n`);
+
+    if (status.connections?.length) {
+      printTable(
+        status.connections.map((c) => ({
+          server: c.name,
+          type: c.type,
+          state: c.state,
+          uptime: c.uptime || "-",
+          calls: c.callCount,
+        })),
+        ["server", "type", "state", "uptime", "calls"]
+      );
+    } else {
+      process.stdout.write("No server connections.\n");
+    }
+    return;
+  }
+
+  fail(`Unknown daemon subcommand: ${subcmd}\nUsage: dm daemon start|stop|status`);
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const cmd = args._[0];
@@ -415,6 +508,7 @@ async function main() {
     if (cmd === "hydrate") return await cmdHydrate(args);
     if (cmd === "run") return await cmdRun(args);
     if (cmd === "call") return await cmdCall(args);
+    if (cmd === "daemon") return await cmdDaemon(args);
     fail(`Unknown command: ${cmd}\n\n${usage()}`);
   } catch (err) {
     fail(err.message || err);

package/templates/skills/droid-mode/lib/daemon.mjs

@@ -0,0 +1,293 @@
+import net from "node:net";
+import fs from "node:fs";
+import path from "node:path";
+import { McpClient } from "./mcp_client.mjs";
+import { resolveServer, listAllServers } from "./config.mjs";
+
+const SOCKET_PATH = process.env.DM_DAEMON_SOCKET || "/tmp/dm-daemon.sock";
+const IDLE_TIMEOUT_MS = parseInt(process.env.DM_DAEMON_IDLE_MS || "600000", 10); // 10 minutes default
+
+/**
+ * Connection pool managing lazy-initialized MCP clients.
+ */
+class ConnectionPool {
+  constructor() {
+    /** @type {Map<string, { client: McpClient, connectedAt: Date, lastUsed: Date, callCount: number }>} */
+    this.connections = new Map();
+    this.idleCheckInterval = null;
+  }
+
+  /**
+   * Get or create a client for the given server.
+   * @param {string} serverName
+   * @returns {Promise<McpClient>}
+   */
+  async getClient(serverName) {
+    const existing = this.connections.get(serverName);
+    if (existing) {
+      existing.lastUsed = new Date();
+      existing.callCount++;
+      return existing.client;
+    }
+
+    // Lazy init: resolve from mcp.json, connect, cache
+    const { entry } = resolveServer({ server: serverName });
+    const client = new McpClient({ serverName, entry });
+    await client.init();
+
+    this.connections.set(serverName, {
+      client,
+      connectedAt: new Date(),
+      lastUsed: new Date(),
+      callCount: 1,
+    });
+
+    return client;
+  }
+
+  /**
+   * Get status of all connections.
+   */
+  getStatus() {
+    const servers = listAllServers();
+    const status = [];
+
+    for (const server of servers) {
+      const conn = this.connections.get(server.name);
+      if (conn) {
+        const uptimeMs = Date.now() - conn.connectedAt.getTime();
+        const uptimeMin = Math.floor(uptimeMs / 60000);
+        status.push({
+          name: server.name,
+          type: server.type,
+          state: "connected",
+          uptime: `${uptimeMin}m`,
+          callCount: conn.callCount,
+        });
+      } else {
+        status.push({
+          name: server.name,
+          type: server.type,
+          state: "idle",
+          uptime: null,
+          callCount: 0,
+        });
+      }
+    }
+
+    return status;
+  }
+
+  /**
+   * Close idle connections that haven't been used recently.
+   */
+  async pruneIdle() {
+    const now = Date.now();
+    for (const [name, conn] of this.connections.entries()) {
+      const idleMs = now - conn.lastUsed.getTime();
+      if (idleMs > IDLE_TIMEOUT_MS) {
+        try {
+          await conn.client.close();
+        } catch {}
+        this.connections.delete(name);
+        if (process.env.DM_DEBUG === "1") {
+          process.stderr.write(`[daemon] Closed idle connection: ${name}\n`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Start periodic idle checking.
+   */
+  startIdleCheck() {
+    if (this.idleCheckInterval) return;
+    this.idleCheckInterval = setInterval(() => this.pruneIdle(), 60000); // Check every minute
+  }
+
+  /**
+   * Close all connections.
+   */
+  async closeAll() {
+    if (this.idleCheckInterval) {
+      clearInterval(this.idleCheckInterval);
+      this.idleCheckInterval = null;
+    }
+    for (const [name, conn] of this.connections.entries()) {
+      try {
+        await conn.client.close();
+      } catch {}
+    }
+    this.connections.clear();
+  }
+}
+
+/**
+ * Daemon server that listens on Unix socket and handles requests.
+ */
+export class DaemonServer {
+  constructor() {
+    this.pool = new ConnectionPool();
+    this.server = null;
+    this.startedAt = null;
+  }
+
+  /**
+   * Handle a single request.
+   * @param {object} req
+   * @returns {Promise<object>}
+   */
+  async handleRequest(req) {
+    const { action, server, tool, args } = req;
+
+    if (action === "ping") {
+      return { ok: true, pong: true, uptime: Date.now() - this.startedAt };
+    }
+
+    if (action === "status") {
+      return {
+        ok: true,
+        uptime: Date.now() - this.startedAt,
+        connections: this.pool.getStatus(),
+      };
+    }
+
+    if (action === "call") {
+      if (!server || !tool) {
+        return { ok: false, error: "Missing server or tool" };
+      }
+
+      const start = Date.now();
+      try {
+        const client = await this.pool.getClient(server);
+        const result = await client.callTool({
+          name: tool,
+          arguments: args || {},
+          timeoutMs: 60000,
+        });
+        const durationMs = Date.now() - start;
+        return {
+          ok: true,
+          server,
+          tool,
+          result: result.structured ?? result.text ?? result.raw,
+          durationMs,
+          fromPool: this.pool.connections.has(server),
+        };
+      } catch (err) {
+        return {
+          ok: false,
+          server,
+          tool,
+          error: err.message || String(err),
+          durationMs: Date.now() - start,
+        };
+      }
+    }
+
+    if (action === "shutdown") {
+      // Graceful shutdown
+      setImmediate(() => this.stop());
+      return { ok: true, message: "Shutting down" };
+    }
+
+    return { ok: false, error: `Unknown action: ${action}` };
+  }
+
+  /**
+   * Start the daemon server.
+   */
+  async start() {
+    // Remove stale socket
+    if (fs.existsSync(SOCKET_PATH)) {
+      fs.unlinkSync(SOCKET_PATH);
+    }
+
+    this.startedAt = Date.now();
+    this.pool.startIdleCheck();
+
+    return new Promise((resolve, reject) => {
+      this.server = net.createServer((socket) => {
+        let buffer = "";
+
+        socket.on("data", async (data) => {
+          buffer += data.toString();
+
+          // Handle newline-delimited JSON
+          let idx;
+          while ((idx = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, idx);
+            buffer = buffer.slice(idx + 1);
+
+            if (!line.trim()) continue;
+
+            try {
+              const req = JSON.parse(line);
+              const res = await this.handleRequest(req);
+              socket.write(JSON.stringify(res) + "\n");
+            } catch (err) {
+              socket.write(JSON.stringify({ ok: false, error: err.message }) + "\n");
+            }
+          }
+        });
+
+        socket.on("error", () => {});
+      });
+
+      this.server.on("error", reject);
+
+      this.server.listen(SOCKET_PATH, () => {
+        // Set socket permissions (user only)
+        fs.chmodSync(SOCKET_PATH, 0o600);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Stop the daemon server.
+   */
+  async stop() {
+    await this.pool.closeAll();
+
+    if (this.server) {
+      this.server.close();
+      this.server = null;
+    }
+
+    if (fs.existsSync(SOCKET_PATH)) {
+      fs.unlinkSync(SOCKET_PATH);
+    }
+  }
+}
+
+/**
+ * Run daemon as main process.
+ */
+export async function runDaemon() {
+  const daemon = new DaemonServer();
+
+  process.on("SIGTERM", async () => {
+    await daemon.stop();
+    process.exit(0);
+  });
+
+  process.on("SIGINT", async () => {
+    await daemon.stop();
+    process.exit(0);
+  });
+
+  try {
+    await daemon.start();
+    process.stdout.write(`Daemon started on ${SOCKET_PATH}\n`);
+    process.stdout.write(`PID: ${process.pid}\n`);
+  } catch (err) {
+    process.stderr.write(`Failed to start daemon: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+// Allow running directly: node daemon.mjs
+if (process.argv[1]?.endsWith("daemon.mjs") && process.argv[2] === "run") {
+  runDaemon();
+}

package/templates/skills/droid-mode/lib/daemon_client.mjs

@@ -0,0 +1,165 @@
+import net from "node:net";
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SOCKET_PATH = process.env.DM_DAEMON_SOCKET || "/tmp/dm-daemon.sock";
+
+/**
+ * Check if daemon is running by pinging the socket.
+ * @returns {Promise<boolean>}
+ */
+export async function isDaemonRunning() {
+  if (!fs.existsSync(SOCKET_PATH)) {
+    return false;
+  }
+
+  try {
+    const res = await sendRequest({ action: "ping" }, { timeoutMs: 2000 });
+    return res?.ok === true && res?.pong === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Send a request to the daemon.
+ * @param {object} req
+ * @param {{ timeoutMs?: number }} opts
+ * @returns {Promise<object>}
+ */
+export async function sendRequest(req, opts = {}) {
+  const timeoutMs = opts.timeoutMs || 65000; // Slightly longer than tool timeout
+
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(SOCKET_PATH);
+    let buffer = "";
+    let resolved = false;
+
+    const timeout = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        socket.destroy();
+        reject(new Error("Daemon request timed out"));
+      }
+    }, timeoutMs);
+
+    socket.on("connect", () => {
+      socket.write(JSON.stringify(req) + "\n");
+    });
+
+    socket.on("data", (data) => {
+      buffer += data.toString();
+      const idx = buffer.indexOf("\n");
+      if (idx !== -1) {
+        const line = buffer.slice(0, idx);
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timeout);
+          socket.end();
+          try {
+            resolve(JSON.parse(line));
+          } catch (err) {
+            reject(new Error(`Invalid daemon response: ${line}`));
+          }
+        }
+      }
+    });
+
+    socket.on("error", (err) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        reject(err);
+      }
+    });
+
+    socket.on("close", () => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        reject(new Error("Daemon connection closed unexpectedly"));
+      }
+    });
+  });
+}
+
+/**
+ * Call a tool through the daemon.
+ * @param {{ server: string, tool: string, args?: object }} opts
+ * @returns {Promise<object>}
+ */
+export async function callViaDaemon(opts) {
+  return sendRequest({
+    action: "call",
+    server: opts.server,
+    tool: opts.tool,
+    args: opts.args || {},
+  });
+}
+
+/**
+ * Get daemon status.
+ * @returns {Promise<object>}
+ */
+export async function getDaemonStatus() {
+  return sendRequest({ action: "status" });
+}
+
+/**
+ * Request daemon shutdown.
+ * @returns {Promise<object>}
+ */
+export async function shutdownDaemon() {
+  try {
+    return await sendRequest({ action: "shutdown" }, { timeoutMs: 5000 });
+  } catch {
+    // Daemon may have already exited
+    return { ok: true, message: "Daemon stopped" };
+  }
+}
+
+/**
+ * Start the daemon as a background process.
+ * @returns {Promise<{ pid: number }>}
+ */
+export async function startDaemon() {
+  // Check if already running
+  if (await isDaemonRunning()) {
+    throw new Error("Daemon is already running");
+  }
+
+  // Find daemon.mjs path
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const daemonPath = path.join(__dirname, "daemon.mjs");
+
+  // Spawn fully detached process with no stdio connection
+  // This prevents the daemon from exiting when the parent exits
+  const child = spawn(process.execPath, [daemonPath, "run"], {
+    detached: true,
+    stdio: "ignore", // Fully detach stdio
+    env: { ...process.env },
+  });
+
+  // Immediately unref so parent can exit
+  child.unref();
+
+  // Wait for daemon to be ready by polling the socket
+  const maxWait = 10000;
+  const pollInterval = 100;
+  const start = Date.now();
+
+  while (Date.now() - start < maxWait) {
+    await new Promise((r) => setTimeout(r, pollInterval));
+    if (await isDaemonRunning()) {
+      return { pid: child.pid };
+    }
+  }
+
+  // If we get here, daemon didn't start
+  try {
+    child.kill();
+  } catch {}
+  throw new Error("Daemon failed to start within timeout");
+}

package/templates/skills/droid-mode/lib/mcp_stdio.mjs

@@ -45,20 +45,38 @@ export class McpStdioTransport {
       // Avoid noisy output; keep it available for debugging.
       // You can enable by setting DM_DEBUG=1.
       if (process.env.DM_DEBUG === "1") {
-        process.stderr.write(String(buf));
+        process.stderr.write(`[dm:stderr] ${String(buf)}`);
       }
     });
 
+    // Handle stdout closing unexpectedly (e.g., server crashes or exits without response)
+    this.proc.stdout.on("close", () => {
+      if (process.env.DM_DEBUG === "1" && this.pending.size > 0) {
+        process.stderr.write(`[dm:stdio] stdout closed with ${this.pending.size} pending request(s)\n`);
+      }
+      for (const [id, p] of this.pending.entries()) {
+        clearTimeout(p.timeout);
+        p.reject(new Error(`MCP stdio stdout closed while waiting for response id=${id}`));
+      }
+      this.pending.clear();
+    });
+
     this.rl = readline.createInterface({ input: this.proc.stdout });
 
     this.rl.on("line", (line) => {
       if (!line) return;
+      if (process.env.DM_DEBUG === "1") {
+        process.stderr.write(`[dm:stdio] << ${line.slice(0, 500)}${line.length > 500 ? '...' : ''}\n`);
+      }
       let msg;
       try {
         msg = JSON.parse(line);
       } catch (err) {
-        if (process.env.DM_DEBUG === "1") {
-          process.stderr.write(`[dm] Failed to parse JSON from server: ${line}\n`);
+        // Log parse failures even without DM_DEBUG if we have pending requests
+        if (this.pending.size > 0) {
+          process.stderr.write(`[dm:stdio] JSON parse error with ${this.pending.size} pending: ${line.slice(0, 200)}\n`);
+        } else if (process.env.DM_DEBUG === "1") {
+          process.stderr.write(`[dm:stdio] Ignoring non-JSON line: ${line.slice(0, 100)}\n`);
         }
         return;
       }