residoo 0.4.14 → 0.6.0

package/README.md

@@ -40,6 +40,19 @@ Values are redacted in this report (first/last 4 characters only). Nothing
 scanned here left your machine; residoo makes no network calls.
 ```
 
+That's one snapshot. `residoo watch` runs the same engine continuously and
+alerts the moment a new secret lands, instead of waiting for you to
+remember to scan again; no other tool in the field has anything like it
+(see [Watch: continuous scanning](#watch-continuous-scanning)):
+
+```
+$ residoo watch
+watching 43 sources, 118 files · polling every 5s
+
+2026-09-03 14:02:11  [high]  AWS Access Key ID  AKIA****ABCD
+  claude-code · session-9f2c.jsonl:214 · rf1-8a3e91  Rotate: https://.../access_keys
+```
+
 > [!NOTE]
 > gitleaks and trufflehog scan **commits**. residoo scans the **conversation
 > transcripts** an AI agent leaves behind: a different, previously
@@ -113,6 +126,13 @@ reproduction; everything needed to rerun it ships in this repo.
   acknowledgement ledger. See [Rotation](#rotation-from-found-to-closed).
 - `--project <dir>` scans a repository checkout instead of the machine, for
   CI and pre-commit. See [CI and pre-commit](#ci-and-pre-commit).
+- **`residoo watch`**: continuous scanning instead of one snapshot, alerting
+  the moment a new secret lands in a transcript. See
+  [Watch: continuous scanning](#watch-continuous-scanning) below.
+- **`residoo mcp`**: query findings and manage rotation from inside Claude
+  Code itself, over a hand-rolled MCP server. See
+  [MCP: query findings from inside Claude Code](#mcp-query-findings-from-inside-claude-code)
+  below.
 
 ## Beyond transcripts: configs and planted persistence
 
@@ -285,7 +305,7 @@ As a GitHub Action (this repo doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.4.14
+  - uses: dandovdub/residoo@v0.6.0
 ```
 
 As a pre-commit hook:
@@ -293,7 +313,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.4.14
+    rev: v0.6.0
     hooks:
       - id: residoo
 ```
@@ -373,11 +393,80 @@ residoo ack <fingerprint> [--note <text>]           mark one finding rotated
 
 residoo unseal <vault-dir>                          list a vault's contents
 residoo unseal <vault-dir> --restore <n> --out <p>  restore one file, hash-verified
+
+residoo watch [options]
+
+  --interval <seconds>    how often to check for new content (default 5, minimum 1)
+  --json                  NDJSON events on stdout, one line per finding/re-exposure
+  --verify                same opt-in vendor check as scan --verify, applied to
+                          each newly found credential once
+  --include-noisy, --include-suppressed, --no-color   same meaning as scan
 ```
 
 The vault passphrase comes from `RESIDOO_PASSPHRASE` or a hidden interactive
 prompt. There is no recovery if you lose it, so pick one you keep.
 
+## Watch: continuous scanning
+
+`residoo scan` is a snapshot. `residoo watch` is the same engine run
+continuously: it polls every source `scan` already covers, and the moment a
+new secret lands in a transcript, prints an alert with the redacted value,
+the rule, the file, and the same rotation runbook a scan finding carries,
+instead of waiting for you to remember to run `scan` again.
+
+```
+$ residoo watch
+watching 43 sources, 118 files (61 tailed, 57 rescanned on change)
+polling every 5s; fs.watch is not used, every alert comes from polling
+
+2026-09-03 14:02:11  [high]  AWS Access Key ID  AKIA****ABCD
+  claude-code · session-9f2c.jsonl:214 · rf1-8a3e91  Rotate: https://.../access_keys
+```
+
+It is watch-from-**now**: run `residoo scan` first for anything already on
+disk, since a fresh `residoo watch` baselines whatever it finds on its first
+sweep silently and only alerts on content written after it starts. A finding
+already acknowledged or dismissed (`residoo ack` / `residoo dismiss`) stays
+suppressed, checked against the same `~/.residoo/rotations.json` ledger, and
+a ledger change made mid-watch takes effect within one poll interval, no
+restart needed. A findings-free sweep prints nothing at all, including to
+its own watched Claude Code session, by design: no other tool in this
+project's own benchmark ([`bench/`](bench/)) has a continuous mode at all,
+verified directly against each one's own `--help` output rather than
+assumed; see [docs/comparison.md](docs/comparison.md) for how the one
+adjacent thing, GitGuardian's `ggshield` AI hook, works differently.
+
+## MCP: query findings from inside Claude Code
+
+`residoo mcp` runs residoo as an MCP server over stdio, so Claude Code can
+query findings and manage the rotation ledger conversationally instead of
+you running the CLI in a terminal:
+
+```bash
+claude mcp add residoo -- residoo mcp
+```
+
+or add it directly to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "residoo": { "type": "stdio", "command": "residoo", "args": ["mcp"] }
+  }
+}
+```
+
+Five tools, mirroring the CLI exactly: `residoo_scan` (a fresh scan,
+merged with rotation status), `residoo_check` (only what's new since the
+last check in this conversation, backed by the same engine as `watch`),
+`residoo_explain` (a rule's rotation runbook), and `residoo_ack` /
+`residoo_dismiss` (append to the local ledger). Every value returned is
+redacted the same way the CLI's own output is; nothing here makes a
+network call or touches the transcript files themselves. Like the rest of
+residoo, this is hand-rolled against the MCP spec directly, not built on
+`@modelcontextprotocol/sdk`: zero runtime dependencies stays true here
+too.
+
 ## Sources supported today
 
 43 sources: 42 transcript stores plus the agent-config source above, in two

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.4.14",
+  "version": "0.6.0",
   "description": "Find secrets leaking through your AI coding agent's session history. Zero network calls in the scan path, zero dependencies.",
   "license": "MIT",
   "author": "CloudRoam (https://cloudroam.io)",

package/src/cli.js

@@ -10,6 +10,9 @@ const { checkIntegrity } = require("./integrity");
 const {
   ROTATION_GUIDANCE, guidanceFor, loadAcks, loadDismissed, ackFinding, dismissFinding, renderRotation,
 } = require("./rotation");
+const { startWatch, isTailable } = require("./watch");
+const { startMcpServer } = require("./mcp");
+const { buildTools } = require("./mcpTools");
 
 /**
  * A source is unavailable for the ordinary reason (not installed — nothing
@@ -126,6 +129,40 @@ Scan options:
                           with no network call at all, on by default, not
                           part of --verify.
 
+Watch:
+  residoo watch            continuous scanning instead of one snapshot:
+                          alerts the moment a new secret lands in a
+                          transcript, instead of waiting for the next
+                          "residoo scan". Covers the same sources as scan;
+                          run scan first for anything already on disk,
+                          since watch only ever looks at content written
+                          AFTER it starts. No other tool in this project's
+                          own benchmark (bench/) has anything like it.
+  --interval <seconds>   how often to check for new content (default 5,
+                          minimum 1)
+  --json                  NDJSON events on stdout instead of plain text,
+                          one line per finding/re-exposure
+  --verify                same opt-in vendor check as scan --verify,
+                          applied to each newly found credential once,
+                          never to one already seen
+  --include-noisy, --include-suppressed, --no-color   same meaning as scan
+  Ctrl+C stops cleanly and prints a session summary (skipped with --json,
+  where the same information is one final NDJSON event).
+
+MCP:
+  residoo mcp              run residoo as an MCP server over stdio, so
+                          Claude Code (or any other MCP client) can query
+                          findings and manage rotation conversationally
+                          instead of a human running the CLI. No network
+                          calls, nothing destructive: the 5 exposed tools
+                          (residoo_scan, residoo_check, residoo_explain,
+                          residoo_ack, residoo_dismiss) mirror scan/watch/
+                          explain/ack/dismiss exactly, and every value
+                          returned is redacted the same way. Register it
+                          with "claude mcp add residoo -- residoo mcp".
+                          Zero runtime dependencies: the protocol is hand-
+                          rolled, not the official SDK.
+
 Rotation:
   residoo explain <rule-id>     full rotation runbook for one detection rule
                                 (where to revoke, steps, what revocation does)
@@ -441,6 +478,153 @@ function runDismiss(args) {
   return 0;
 }
 
+/**
+ * One pass over each source's files() purely to describe what's about to
+ * be watched -- how many files will be tailed (byte-offset, only new
+ * content ever read) versus polled (whole-file rescan on any change). A
+ * separate, cheap enumeration from the watch itself; not wired into
+ * startWatch() so a banner-rendering concern never has to live inside the
+ * engine.
+ */
+function printWatchBanner(sources) {
+  process.stderr.write("residoo watch: establishing a baseline over each source (this covers NEW content only -- run `residoo scan` first for anything already on disk)...\n");
+  for (const source of sources) {
+    let tail = 0, rescan = 0;
+    try {
+      for (const entry of source.files()) {
+        if (entry.broken) continue;
+        if (isTailable(entry.file)) tail++; else rescan++;
+      }
+    } catch {
+      // A source erroring while just being counted for the banner is not
+      // fatal to the watch itself -- sweepOnce has its own try/catch
+      // around files() and reports it there instead.
+    }
+    const parts = [];
+    if (tail) parts.push(`${tail} tailed`);
+    if (rescan) parts.push(`${rescan} polled (rescanned on change)`);
+    process.stderr.write(`  ${source.label()} (${source.id()}): ${parts.join(", ") || "no files yet"}\n`);
+  }
+  process.stderr.write(
+    "fs.watch is not used; every alert comes from polling, so an alert can lag\n" +
+    "up to one --interval behind the actual write. SQLite-backed sources are\n" +
+    "always polled in full (no incremental read exists for them). Ctrl+C to stop.\n\n"
+  );
+}
+
+function printWatchSummary(stats) {
+  process.stderr.write(
+    `\nresidoo watch: stopped. ${stats.sweeps} sweep${stats.sweeps === 1 ? "" : "s"}, ` +
+    `${stats.loud} new finding${stats.loud === 1 ? "" : "s"}, ${stats.quiet} re-exposure${stats.quiet === 1 ? "" : "s"}` +
+    (stats.suppressedByLedger ? `, ${stats.suppressedByLedger} already acked or dismissed` : "") +
+    (stats.errors ? `, ${stats.errors} sweep error${stats.errors === 1 ? "" : "s"}` : "") + ".\n"
+  );
+}
+
+/**
+ * `residoo watch`: continuous scanning instead of one snapshot. See
+ * src/watch.js for the engine; this function is only argument parsing,
+ * the startup/shutdown banners, and wiring SIGINT/SIGTERM to a clean stop.
+ */
+async function runWatch(args) {
+  const wantsJson = args.includes("--json");
+  const includeNoisy = args.includes("--include-noisy");
+  const includeSuppressed = args.includes("--include-suppressed");
+  const verify = args.includes("--verify");
+  const noColor = args.includes("--no-color");
+
+  let intervalSeconds = 5;
+  const intervalArg = argValue(args, "--interval");
+  if (intervalArg !== null) {
+    const n = Number(intervalArg);
+    if (!Number.isFinite(n) || n < 1) {
+      process.stderr.write(`--interval must be a number of seconds, at least 1; got "${intervalArg}".\n`);
+      return 2;
+    }
+    intervalSeconds = n;
+  }
+
+  const sources = availableSources();
+  if (sources.length === 0) {
+    process.stderr.write(
+      "No known transcript sources found on this machine; nothing to watch.\n" +
+      `Checked: ${sourceStatusList()}.\n`
+    );
+    return 0;
+  }
+
+  if (!wantsJson) printWatchBanner(sources);
+
+  const { promise, stop } = startWatch({
+    sources,
+    options: { includeNoisy, includeSuppressed, verify, noColor, json: wantsJson, pollMs: intervalSeconds * 1000 },
+  });
+
+  const printFinalSummary = (stats) => {
+    if (wantsJson) process.stdout.write(JSON.stringify({ type: "summary", at: new Date(), ...stats }) + "\n");
+    else printWatchSummary(stats);
+  };
+
+  // A second Ctrl+C must not hang waiting on a graceful stop that already
+  // started -- stop() itself is idempotent, but the listener only needs to
+  // act once.
+  let signalled = false;
+  const onSignal = () => {
+    if (signalled) return;
+    signalled = true;
+    printFinalSummary(stop());
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+
+  const stats = await promise;
+  process.removeListener("SIGINT", onSignal);
+  process.removeListener("SIGTERM", onSignal);
+  // promise can also resolve because something ELSE called stop() (not
+  // possible from outside this function today, but the contract allows
+  // it) -- print the summary exactly once regardless of which path got here.
+  if (!signalled) printFinalSummary(stats);
+  return 0;
+}
+
+/**
+ * `residoo mcp`: run residoo as an MCP server over stdio. See src/mcp.js
+ * for the protocol engine and src/mcpTools.js for the tool catalog; this
+ * function is only the startup banner (stderr only -- see mcp.js's own
+ * doc comment on why stdout must never carry anything but protocol
+ * messages) and wiring SIGINT/SIGTERM to a clean stop, mirroring runWatch.
+ */
+async function runMcp(args) {
+  const { version } = require("../package.json");
+  const sources = availableSources();
+  process.stderr.write(
+    sources.length
+      ? `residoo mcp: ${sources.length} source(s) available on this machine: ${sources.map((s) => s.label()).join(", ")}\n`
+      : `residoo mcp: no known transcript sources found on this machine (residoo_scan will report none until one is installed and residoo mcp is restarted).\n`
+  );
+  process.stderr.write("residoo mcp: ready. Waiting for a client on stdin...\n");
+
+  const { promise, stop } = startMcpServer({
+    tools: buildTools({ sources }),
+    serverInfo: { name: "residoo", version },
+    instructions: "Find secrets leaking through this machine's AI coding agent session histories. All tool output is redacted; raw secret values are never returned. Nothing here is destructive: scanning is read-only, and ack/dismiss only append to a local audit ledger.",
+  });
+
+  let signalled = false;
+  const onSignal = () => {
+    if (signalled) return;
+    signalled = true;
+    stop();
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+
+  await promise;
+  process.removeListener("SIGINT", onSignal);
+  process.removeListener("SIGTERM", onSignal);
+  return 0;
+}
+
 async function main(argv) {
   const args = argv.slice(2);
   if (args.includes("-h") || args.includes("--help") || args.length === 0) {
@@ -453,6 +637,8 @@ async function main(argv) {
   if (cmd === "explain") return runExplain(args);
   if (cmd === "ack") return runAck(args);
   if (cmd === "dismiss") return runDismiss(args);
+  if (cmd === "watch") return runWatch(args);
+  if (cmd === "mcp") return runMcp(args);
   if (cmd !== "scan") {
     process.stderr.write(`Unknown command "${cmd}". Try "residoo --help".\n`);
     return 2;

package/src/mcp.js

@@ -0,0 +1,266 @@
+"use strict";
+
+const { createInterface } = require("readline/promises");
+
+/**
+ * `residoo mcp`: a hand-rolled MCP (Model Context Protocol) server over
+ * stdio, so Claude Code (or any other MCP client) can query residoo's
+ * findings and rotation ledger directly instead of a human running the
+ * CLI in a terminal. No `@modelcontextprotocol/sdk` dependency -- residoo
+ * has zero runtime dependencies, no exceptions (see CONTRIBUTING.md), and
+ * MCP's stdio transport is newline-delimited JSON-RPC 2.0, which Node's
+ * own `readline` already handles; every `.jsonl` source adapter in
+ * src/sources/ hand-rolls the same kind of line-delimited JSON parsing.
+ *
+ * This file is the protocol engine only: framing, dispatch, version
+ * negotiation, the outgoing writer, shutdown. It has zero domain
+ * knowledge of scanning/rotation -- see src/mcpTools.js for the actual
+ * tool catalog. `tools` here is just a `Map<name, {name, description,
+ * inputSchema, handler}>` handed in by the caller (mirrors `startWatch`'s
+ * `sources` being handed in by its caller rather than looked up itself).
+ *
+ * Implements the Legacy (initialize-handshake) MCP era only
+ * (`2025-11-25`/`2025-06-18`/`2025-03-26`), which is Claude Code's own
+ * documented DEFAULT for every stdio server -- it only probes stdio
+ * servers for the newer, per-request "Modern" era
+ * (`server/discover`-based) when a user explicitly sets
+ * `MCP_PROTOCOL_NEGOTIATION=auto`. In that opt-in case, the generic
+ * "unknown method" handler below answers `server/discover` instantly with
+ * a plain JSON-RPC -32601, which is exactly what the MCP spec defines as
+ * triggering a Dual-era client's fallback to the Legacy handshake -- so
+ * this server works either way, and implementing `server/discover` itself
+ * is a deliberate, non-blocking v1 scope decision, not an oversight.
+ *
+ * Per the spec's own words: "The server MUST NOT write anything to its
+ * stdout that is not a valid MCP message." `send()` below is the ONLY
+ * function in this file (or in mcpTools.js) allowed to touch `output`;
+ * every log line, startup banner, and shutdown summary goes to
+ * `errOutput` instead. This is the same "stdout is sacred" discipline
+ * watch.js already established, enforced even more strictly here, since
+ * a single stray byte on stdout doesn't just create noise -- it can
+ * corrupt the client's JSON-RPC stream.
+ */
+
+const JSONRPC_VERSION = "2.0";
+
+// All three are "Legacy"-era (initialize-handshake) protocol revisions;
+// none of the wire shapes this file implements (initialize result,
+// tools/list, tools/call, isError) differ across them, so supporting all
+// three costs nothing beyond this list. If the client's requested version
+// isn't one of these, DEFAULT_PROTOCOL_VERSION is what we claim instead.
+const SUPPORTED_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26"];
+const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+
+function negotiateProtocolVersion(requested) {
+  if (typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) return requested;
+  return DEFAULT_PROTOCOL_VERSION;
+}
+
+/**
+ * `startMcpServer({tools, serverInfo, instructions, input, output,
+ * errOutput})` -> `{promise, stop}`. All I/O injectable (mirrors
+ * `startWatch`'s `{sources, options, out, errOut}` contract) so this can
+ * be driven by tests with fake streams and a stub tool map, with no real
+ * scanning involved.
+ */
+function startMcpServer({
+  tools,
+  serverInfo,
+  instructions,
+  input = process.stdin,
+  output = process.stdout,
+  errOutput = process.stderr,
+} = {}) {
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  let stopped = false;
+  let requestsHandled = 0;
+
+  /**
+   * The single write path. `JSON.stringify` already escapes any raw `\n`
+   * inside a string VALUE as the two-character sequence `\` `n` (JSON's
+   * own grammar, RFC 8259, forbids a literal control character in a
+   * string) -- no per-field newline scrubbing is needed here. The only
+   * raw 0x0A byte in the whole write is the one appended below, as the
+   * stdio transport's own frame delimiter.
+   */
+  function send(message) {
+    let text;
+    try {
+      text = JSON.stringify(message);
+    } catch (err) {
+      // `message` contained something JSON.stringify can't serialize (a
+      // circular reference, a BigInt) -- a bug in a tool handler, not a
+      // reason to crash the connection or silently drop a reply the
+      // client may be blocked waiting on. `message.id`, when present,
+      // always came from JSON.parse on the client's own request and
+      // already passed the id-type check in handleLine, so it's
+      // independently safe to reserialize on its own here.
+      errOutput.write(`residoo mcp: failed to serialize outgoing message: ${err instanceof Error ? err.message : String(err)}\n`);
+      const fallbackId = message && typeof message === "object" && "id" in message ? message.id : null;
+      text = JSON.stringify({
+        jsonrpc: JSONRPC_VERSION, id: fallbackId,
+        error: { code: -32603, message: "Internal error: response could not be serialized" },
+      });
+    }
+    output.write(text + "\n");
+  }
+
+  function sendError(id, code, message, data) {
+    send({ jsonrpc: JSONRPC_VERSION, id, error: data === undefined ? { code, message } : { code, message, data } });
+  }
+
+  function sendResult(id, result) {
+    send({ jsonrpc: JSONRPC_VERSION, id, result });
+  }
+
+  function handleInitialize(params, id) {
+    const protocolVersion = negotiateProtocolVersion(params && params.protocolVersion);
+    sendResult(id, {
+      protocolVersion,
+      capabilities: { tools: {} },
+      serverInfo,
+      ...(instructions ? { instructions } : {}),
+    });
+  }
+
+  function handleToolsList(id) {
+    const list = [];
+    for (const tool of tools.values()) {
+      list.push({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema });
+    }
+    sendResult(id, { tools: list });
+  }
+
+  async function handleToolsCall(params, id) {
+    if (!params || typeof params !== "object" || typeof params.name !== "string") {
+      sendError(id, -32602, "Invalid params: 'name' (string) is required");
+      return;
+    }
+    const tool = tools.get(params.name);
+    if (!tool) {
+      sendError(id, -32602, `Unknown tool: ${params.name}`);
+      return;
+    }
+
+    const args = params.arguments && typeof params.arguments === "object" && !Array.isArray(params.arguments)
+      ? params.arguments : {};
+    let result;
+    try {
+      // The handler owns its OWN input validation and is expected to
+      // return {content, isError:true} for both a bad-argument case and a
+      // genuine execution failure -- see SEP-1303: input validation
+      // errors are Tool Execution Errors, not Protocol Errors, so the
+      // model can see the message and self-correct in the same turn.
+      // This dispatcher does not and should not try to tell those two
+      // cases apart.
+      result = await tool.handler(args);
+      if (!result || !Array.isArray(result.content)) {
+        // Defensive: a handler bug in mcpTools.js must not corrupt the
+        // wire protocol -- fail safe into a well-formed isError result.
+        result = { content: [{ type: "text", text: "Tool returned no content (internal error)." }], isError: true };
+      }
+    } catch (err) {
+      // Anything a handler THROWS still lands as a tool execution error,
+      // not -32603 -- that code is reserved for bugs in this dispatcher
+      // itself, not in a tool. errOutput gets the full detail for
+      // operator debugging; the client only ever sees the message string.
+      errOutput.write(`residoo mcp: tool "${params.name}" threw: ${err instanceof Error ? (err.stack || err.message) : String(err)}\n`);
+      result = { content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+    sendResult(id, result);
+  }
+
+  async function dispatch(method, params, hasId, id) {
+    switch (method) {
+      case "initialize":
+        if (!hasId) return;
+        return handleInitialize(params, id);
+      case "notifications/initialized":
+        // A true notification by the method's own contract: never reply,
+        // even if a client mistakenly attached an id -- nothing in v1
+        // depends on this flag anyway (no server-initiated requests).
+        return;
+      case "tools/list":
+        if (!hasId) return;
+        return handleToolsList(id);
+      case "tools/call":
+        if (!hasId) return;
+        return handleToolsCall(params, id);
+      default:
+        // Includes a `server/discover` probe from a client with
+        // MCP_PROTOCOL_NEGOTIATION=auto (see file doc comment) -- MUST
+        // reply fast (no I/O, no await, above) so that fallback resolves
+        // immediately rather than after a client-side timeout.
+        if (!hasId) return;
+        sendError(id, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  async function handleLine(line) {
+    if (line.trim() === "") return false;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      // Per JSON-RPC 2.0 section 5: if the id could not even be
+      // determined (a parse failure means we never got that far), the
+      // error response's id MUST be null.
+      sendError(null, -32700, "Parse error");
+      errOutput.write(`residoo mcp: received unparseable line (${line.length} bytes): ${line.slice(0, 200)}\n`);
+      return false;
+    }
+    if (msg === null || typeof msg !== "object" || Array.isArray(msg)) {
+      sendError(null, -32600, "Invalid Request: expected a JSON object");
+      return false;
+    }
+
+    // Deliberately `hasOwnProperty`, never `msg.id` truthiness -- id:0 is
+    // a valid, falsy request id, and conflating "id key absent" (a
+    // notification: never reply, even with an error) with "id present but
+    // falsy" is exactly the kind of one-character bug that silently
+    // breaks a client's parser.
+    const hasId = Object.prototype.hasOwnProperty.call(msg, "id");
+    const id = hasId ? msg.id : undefined;
+    const idIsValidType = id === null || typeof id === "string" || typeof id === "number";
+
+    if (msg.jsonrpc !== JSONRPC_VERSION || typeof msg.method !== "string") {
+      if (!hasId) return false; // malformed NOTIFICATION: JSON-RPC promises no reply, ever
+      sendError(idIsValidType ? id : null, -32600, "Invalid Request");
+      return false;
+    }
+    if (hasId && !idIsValidType) {
+      // id present but not string/number/null: can't trust echoing it
+      // back (and can't safely re-serialize it if it's e.g. an object).
+      sendError(null, -32600, "Invalid Request: id must be a string, number, or null");
+      return false;
+    }
+
+    try {
+      await dispatch(msg.method, msg.params, hasId, id);
+    } catch (err) {
+      errOutput.write(`residoo mcp: internal error handling "${msg.method}": ${err instanceof Error ? (err.stack || err.message) : String(err)}\n`);
+      if (hasId) sendError(id, -32603, "Internal error");
+    }
+    return hasId;
+  }
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    rl.close(); // unblocks the `for await` loop below on its next iteration
+  }
+
+  const promise = (async () => {
+    for await (const line of rl) {
+      if (stopped) break;
+      if (await handleLine(line)) requestsHandled++;
+    }
+    if (!stopped) stopped = true;
+    errOutput.write(`residoo mcp: shutting down. Handled ${requestsHandled} request(s).\n`);
+    return { requestsHandled };
+  })();
+
+  return { promise, stop };
+}
+
+module.exports = { startMcpServer, SUPPORTED_PROTOCOL_VERSIONS, DEFAULT_PROTOCOL_VERSION };