@cruxy/cli 0.19.0 → 0.21.0

package/dist/mcp/transport.js

@@ -0,0 +1,188 @@
+import { spawn } from "node:child_process";
+import { killTree, registerForCleanup } from "../utils/child-tree.js";
+/**
+ * JSON-RPC 2.0 over an MCP server's stdio (C.27). Owns the child process: spawns
+ * it in its OWN process group (`detached`) so the whole tree is killable, frames
+ * messages as newline-delimited JSON (the MCP stdio wire format), correlates
+ * responses to requests by id, times out per request, and detects a crash.
+ *
+ * The process-lifecycle discipline is shared with the C.12 LSP transport via the
+ * `utils/child-tree` backstop: `detached` spawn + negative-PID `killTree` on
+ * dispose/crash, and a single process-exit kill-tree that reaps LSP and MCP
+ * trees alike. That is what makes "trusting a server runs its code" not also mean
+ * "leaking its process on exit".
+ *
+ * Security posture on the inbound side: a server MAY send us requests
+ * (`sampling/createMessage`, `roots/list`, `elicitation/create`). We answer
+ * `ping` and DECLINE everything else with a JSON-RPC "method not found" — cruxy
+ * never lets a server drive model sampling or read our roots. Server→client
+ * notifications are ignored.
+ */
+const GRACE_MS = 2000;
+const METHOD_NOT_FOUND = -32601;
+export class McpStdioTransport {
+    child;
+    nextId = 1;
+    pending = new Map();
+    crashHandler = null;
+    /** stdout parse buffer (a message may arrive across chunks). */
+    buffer = "";
+    disposed = false;
+    unregisterCleanup;
+    constructor(spec, root) {
+        // `detached` makes the child a process-group leader so the whole tree can be
+        // killed via a negative-PID signal — same discipline as run_command (C.16)
+        // and the LSP transport (C.12).
+        this.child = spawn(spec.command, spec.args, {
+            cwd: root,
+            detached: true,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, ...(spec.env ?? {}) },
+        });
+        this.unregisterCleanup = registerForCleanup(this.child.pid);
+        this.child.stdout?.on("data", (chunk) => this.onStdout(chunk));
+        // Server stderr is diagnostic only; surface nothing by default (it's noisy).
+        this.child.stderr?.on("data", () => { });
+        this.child.on("exit", (code, signal) => this.onExit(code, signal));
+        this.child.on("error", (err) => this.onSpawnError(err));
+    }
+    request(method, params, timeoutMs) {
+        if (this.disposed) {
+            return Promise.reject(new Error("transport disposed"));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`MCP request "${method}" timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            timer.unref?.();
+            this.pending.set(id, { resolve, reject, timer });
+            this.send({ jsonrpc: "2.0", id, method, params });
+        });
+    }
+    notify(method, params) {
+        if (this.disposed)
+            return;
+        this.send({ jsonrpc: "2.0", method, params });
+    }
+    onCrash(handler) {
+        this.crashHandler = handler;
+    }
+    async dispose(force = false) {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.unregisterCleanup();
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error("transport disposed"));
+        }
+        this.pending.clear();
+        // Closing stdin is MCP's shutdown signal; a well-behaved server then exits.
+        this.child.stdin?.end();
+        if (!this.child.pid || this.child.exitCode !== null)
+            return;
+        if (force) {
+            killTree(this.child.pid);
+            return;
+        }
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                killTree(this.child.pid);
+                resolve();
+            }, GRACE_MS);
+            timer.unref?.();
+            this.child.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    // ── framing (newline-delimited JSON) ──────────────────────────────────────────
+    send(message) {
+        // MCP stdio frames one JSON message per line; JSON.stringify never emits a
+        // raw newline, so a single `\n` terminator is an unambiguous delimiter.
+        this.child.stdin?.write(JSON.stringify(message) + "\n");
+    }
+    onStdout(chunk) {
+        this.buffer += chunk.toString("utf8");
+        for (;;) {
+            const nl = this.buffer.indexOf("\n");
+            if (nl === -1)
+                return;
+            const line = this.buffer.slice(0, nl);
+            this.buffer = this.buffer.slice(nl + 1);
+            const trimmed = line.trim();
+            if (trimmed !== "")
+                this.dispatch(trimmed);
+        }
+    }
+    dispatch(text) {
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            return; // ignore unparseable frames
+        }
+        // Response to one of our requests.
+        if (typeof msg.id === "number" &&
+            msg.method === undefined &&
+            (msg.result !== undefined || msg.error)) {
+            const pending = this.pending.get(msg.id);
+            if (!pending)
+                return;
+            this.pending.delete(msg.id);
+            clearTimeout(pending.timer);
+            if (msg.error)
+                pending.reject(new Error(msg.error.message ?? "MCP error"));
+            else
+                pending.resolve(msg.result);
+            return;
+        }
+        // Server → client REQUEST (has both method and id). Answer ping; decline
+        // everything else — cruxy never lets a server drive sampling/roots/elicit.
+        if (typeof msg.method === "string" && msg.id !== undefined) {
+            if (msg.method === "ping") {
+                this.send({ jsonrpc: "2.0", id: msg.id, result: {} });
+            }
+            else {
+                this.send({
+                    jsonrpc: "2.0",
+                    id: msg.id,
+                    error: {
+                        code: METHOD_NOT_FOUND,
+                        message: `cruxy does not support server-initiated "${msg.method}"`,
+                    },
+                });
+            }
+            return;
+        }
+        // Server → client notification (no id): ignored.
+    }
+    onExit(code, signal) {
+        this.unregisterCleanup();
+        if (this.disposed)
+            return; // an expected shutdown, not a crash
+        // Unexpected exit → a crash. Reap the whole group so a crash never orphans
+        // the server's own child processes.
+        killTree(this.child.pid);
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error(`MCP server exited (code ${code}, signal ${signal})`));
+        }
+        this.pending.clear();
+        this.crashHandler?.({ code, signal });
+    }
+    onSpawnError(err) {
+        if (this.disposed)
+            return;
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+        this.crashHandler?.({ code: null, signal: null });
+    }
+}

package/dist/mcp/trust-gate.d.ts

@@ -0,0 +1,35 @@
+import type { McpServerConfig } from "../config/index.js";
+import { type McpTrustStore } from "./trust.js";
+/**
+ * The connect-time trust decision (C.27). This is the gate that stands between a
+ * configured MCP server and it actually running. Its wording is deliberately
+ * blunt, because the escalation is real: a trusted stdio MCP server runs
+ * UNSANDBOXED with your full privileges. The shell sandbox (C.16) can box a
+ * command, but it cannot contain a trusted external program's own side effects —
+ * so "trust this server" literally means "run this third-party code as me".
+ *
+ * Behavior:
+ * - Already trusted (config fingerprint matches a recorded decision) → proceed.
+ * - Untrusted + interactive → show the disclosure, read one key; only `y` trusts
+ *   (records the decision) and proceeds. Anything else (incl. EOF) → declined.
+ * - Untrusted + NON-interactive → throw {@link mcpUntrusted} (CRUXY_E_MCP_UNTRUSTED)
+ *   BEFORE anything is spawned. Non-interactive NEVER auto-trusts.
+ */
+/** The minimal prompt surface — satisfied by the shared `defaultPromptIO`. */
+export interface McpTrustIO {
+    write(text: string): void;
+    /** Read a single keypress; resolves "" on EOF / Ctrl-C (→ default-deny). */
+    readKey(): Promise<string>;
+    color: boolean;
+}
+export interface EnsureMcpTrustDeps {
+    store: McpTrustStore;
+    /** Whether cruxy can actually prompt (stdin is a TTY). */
+    interactive: boolean;
+    /** Prompt I/O; required to actually prompt when interactive. */
+    io?: McpTrustIO;
+    /** ISO-timestamp source for the recorded decision (injected for tests). */
+    now?: () => string;
+}
+export type McpTrustOutcome = "trusted" | "declined";
+export declare function ensureMcpTrust(root: string, servers: Record<string, McpServerConfig>, deps: EnsureMcpTrustDeps): Promise<McpTrustOutcome>;

package/dist/mcp/trust-gate.js

@@ -0,0 +1,40 @@
+import { mcpUntrusted } from "../errors/index.js";
+import { themeForColor } from "../theme/index.js";
+import { fingerprintMcpServers, isMcpTrusted, } from "./trust.js";
+export async function ensureMcpTrust(root, servers, deps) {
+    const names = Object.keys(servers);
+    const fingerprint = fingerprintMcpServers(servers);
+    if (isMcpTrusted(deps.store, root, fingerprint))
+        return "trusted";
+    // Non-interactive: fail closed, before any spawn. Never auto-trust.
+    if (!deps.interactive || !deps.io) {
+        throw mcpUntrusted(root, names);
+    }
+    const io = deps.io;
+    io.write(disclosure(names, io.color));
+    const key = (await io.readKey()).toLowerCase();
+    io.write("\n");
+    if (key === "y") {
+        const now = deps.now ?? (() => new Date().toISOString());
+        deps.store.record({ root, fingerprint, at: now() });
+        return "trusted";
+    }
+    return "declined";
+}
+/** The explicit escalation disclosure shown before trusting any server. */
+function disclosure(names, color) {
+    const t = themeForColor(color);
+    const list = names.map((n) => `    • ${n}`).join("\n");
+    return [
+        `${t.danger(t.strong("! MCP servers want to connect"))} ${t.muted(`(${names.length})`)}`,
+        list,
+        "",
+        t.strong("  Trusting these servers runs their code on your machine with your FULL"),
+        t.strong("  privileges — they are NOT sandboxed. A trusted server can read and write"),
+        t.strong("  your files and make network calls, just like a program you ran yourself."),
+        t.muted("  Their tools are still individually approved before each call, and their"),
+        t.muted("  output is treated as untrusted data — but the process itself is not boxed."),
+        "",
+        `  ${t.muted("Trust and connect these servers for this repo?")} ${t.strong("[y/N]")} `,
+    ].join("\n");
+}

package/dist/mcp/trust.d.ts

@@ -0,0 +1,52 @@
+import type { McpServerConfig } from "../config/index.js";
+import type { McpTrust } from "./types.js";
+/**
+ * The MCP-server trust model (C.27), a near-verbatim sibling of the C.19 hook and
+ * C.29 memory trust models. Trust is recorded in the GLOBAL dir
+ * (`~/.cruxy/mcp-trust.json`) — in the user's home, NEVER inside a repo — so
+ * cloning a repo carries zero trust and an attacker cannot ship a pre-trusted
+ * marker. It is its own file, independent of hook/memory trust.
+ *
+ * Trust is bound to a {@link fingerprintMcpServers fingerprint} of the exact MCP
+ * server config seen at trust time and re-checked on every run: if the config
+ * changes (a command / args / url / env edit), the fingerprint no longer matches
+ * and trust is stale → not trusted until re-granted. This is what defeats
+ * trust-then-swap. Because trusting a server means running its code UNSANDBOXED
+ * with your privileges, that staleness check is the load-bearing defense.
+ */
+/** ~/.cruxy/mcp-trust.json */
+export declare function mcpTrustPath(): string;
+/**
+ * A stable content fingerprint of a repo's configured MCP servers. Canonical by
+ * construction so a benign reformat of the config (reindent, reordered keys)
+ * does NOT change it, while any real change to what would be executed DOES:
+ * - only the meaning-bearing fields are hashed (server id, command, args, url,
+ *   and env as sorted key=value pairs);
+ * - args/env are normalized to a fixed order;
+ * - servers are sorted by id and serialized with a fixed field order.
+ *
+ * The empty set has a fixed, stable fingerprint (trusting "no servers" is
+ * meaningful; adding the first server re-gates).
+ */
+export declare function fingerprintMcpServers(servers: Record<string, McpServerConfig>): string;
+/** The persisted trust seam — file-backed in production, injectable for tests. */
+export interface McpTrustStore {
+    /** The recorded decision for a repo root, or undefined if never trusted. */
+    get(root: string): McpTrust | undefined;
+    /** Persist a trust decision (overwrites any prior one for the same root). */
+    record(trust: McpTrust): void;
+}
+/**
+ * Is this repo's current MCP server config trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — a changed config is
+ * treated as untrusted (stale), forcing a fresh decision before any server runs.
+ */
+export declare function isMcpTrusted(store: McpTrustStore, root: string, currentFingerprint: string): boolean;
+/**
+ * The real store, persisting to `~/.cruxy/mcp-trust.json` as `{ [root]: McpTrust }`.
+ * Reads are lazy + cached; a corrupt file is treated as "no trust recorded"
+ * (fail-closed — a broken trust file must never grant trust to unsandboxed code).
+ */
+export declare function fileMcpTrustStore(file?: string): McpTrustStore;
+/** An in-memory store for tests (and any ephemeral run). */
+export declare function memoryMcpTrustStore(seed?: McpTrust[]): McpTrustStore;

package/dist/mcp/trust.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { MCP_TRUST_FILE_NAME } from "../constants.js";
+/**
+ * The MCP-server trust model (C.27), a near-verbatim sibling of the C.19 hook and
+ * C.29 memory trust models. Trust is recorded in the GLOBAL dir
+ * (`~/.cruxy/mcp-trust.json`) — in the user's home, NEVER inside a repo — so
+ * cloning a repo carries zero trust and an attacker cannot ship a pre-trusted
+ * marker. It is its own file, independent of hook/memory trust.
+ *
+ * Trust is bound to a {@link fingerprintMcpServers fingerprint} of the exact MCP
+ * server config seen at trust time and re-checked on every run: if the config
+ * changes (a command / args / url / env edit), the fingerprint no longer matches
+ * and trust is stale → not trusted until re-granted. This is what defeats
+ * trust-then-swap. Because trusting a server means running its code UNSANDBOXED
+ * with your privileges, that staleness check is the load-bearing defense.
+ */
+/** ~/.cruxy/mcp-trust.json */
+export function mcpTrustPath() {
+    return path.join(globalDir(), MCP_TRUST_FILE_NAME);
+}
+/**
+ * A stable content fingerprint of a repo's configured MCP servers. Canonical by
+ * construction so a benign reformat of the config (reindent, reordered keys)
+ * does NOT change it, while any real change to what would be executed DOES:
+ * - only the meaning-bearing fields are hashed (server id, command, args, url,
+ *   and env as sorted key=value pairs);
+ * - args/env are normalized to a fixed order;
+ * - servers are sorted by id and serialized with a fixed field order.
+ *
+ * The empty set has a fixed, stable fingerprint (trusting "no servers" is
+ * meaningful; adding the first server re-gates).
+ */
+export function fingerprintMcpServers(servers) {
+    const canonical = Object.entries(servers)
+        .map(([id, s]) => [
+        id,
+        s.command ?? "",
+        [...(s.args ?? [])],
+        s.url ?? "",
+        Object.entries(s.env ?? {})
+            .map(([k, v]) => `${k}=${v}`)
+            .sort(),
+    ])
+        .sort((a, b) => String(a[0]).localeCompare(String(b[0])));
+    return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+/**
+ * Is this repo's current MCP server config trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — a changed config is
+ * treated as untrusted (stale), forcing a fresh decision before any server runs.
+ */
+export function isMcpTrusted(store, root, currentFingerprint) {
+    const record = store.get(path.resolve(root));
+    return record !== undefined && record.fingerprint === currentFingerprint;
+}
+// ── file-backed store ─────────────────────────────────────────────────────────
+/**
+ * The real store, persisting to `~/.cruxy/mcp-trust.json` as `{ [root]: McpTrust }`.
+ * Reads are lazy + cached; a corrupt file is treated as "no trust recorded"
+ * (fail-closed — a broken trust file must never grant trust to unsandboxed code).
+ */
+export function fileMcpTrustStore(file = mcpTrustPath()) {
+    let cache = null;
+    const load = () => {
+        if (cache)
+            return cache;
+        try {
+            const raw = JSON.parse(readFileSync(file, "utf8"));
+            cache =
+                raw && typeof raw === "object" ? raw : {};
+        }
+        catch {
+            // Missing or corrupt → no trust (fail-closed).
+            cache = {};
+        }
+        return cache;
+    };
+    return {
+        get(root) {
+            return load()[path.resolve(root)];
+        },
+        record(trust) {
+            const store = load();
+            store[path.resolve(trust.root)] = {
+                ...trust,
+                root: path.resolve(trust.root),
+            };
+            mkdirSync(path.dirname(file), { recursive: true });
+            // 0600: trust records name local paths; keep them owner-only.
+            writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
+            if (existsSync(file))
+                cache = store;
+        },
+    };
+}
+/** An in-memory store for tests (and any ephemeral run). */
+export function memoryMcpTrustStore(seed = []) {
+    const store = new Map();
+    for (const t of seed)
+        store.set(path.resolve(t.root), t);
+    return {
+        get: (root) => store.get(path.resolve(root)),
+        record: (trust) => void store.set(path.resolve(trust.root), {
+            ...trust,
+            root: path.resolve(trust.root),
+        }),
+    };
+}

package/dist/mcp/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared types for the MCP client (C.27). The wire protocol is JSON-RPC 2.0; the
+ * transport seam below lets tests inject a fake peer so no real server binary is
+ * required. Every type here is deliberately small — the security-bearing logic
+ * lives in `adapter.ts` (the single seam), not in these shapes.
+ */
+/**
+ * A recorded MCP-trust decision for one repo root. Trusting a server runs its
+ * code UNSANDBOXED with your privileges, so the decision is bound to a
+ * fingerprint of the exact server config and re-checked every run. Lives ONLY in
+ * `~/.cruxy/mcp-trust.json` (never in a repo), so a clone carries zero trust.
+ */
+export interface McpTrust {
+    /** Absolute project root. */
+    root: string;
+    /** sha256 of the canonicalized MCP server config (see `fingerprintMcpServers`). */
+    fingerprint: string;
+    /** ISO timestamp the decision was recorded. */
+    at: string;
+}
+/**
+ * The transport seam — JSON-RPC over some duplex channel (stdio in production).
+ * Fake implementations back the unit tests; the real one (`McpStdioTransport`)
+ * owns a child process and reaps its whole tree on teardown.
+ */
+export interface McpTransport {
+    /** Send a request and await its correlated response (rejects on timeout/error). */
+    request(method: string, params: unknown, timeoutMs: number): Promise<unknown>;
+    /** Fire-and-forget notification (no response). */
+    notify(method: string, params: unknown): void;
+    /** Register the crash callback (unexpected child exit). */
+    onCrash(handler: (info: {
+        code: number | null;
+        signal: string | null;
+    }) => void): void;
+    /** Shut the transport (and its process tree) down. `force` skips the grace window. */
+    dispose(force?: boolean): Promise<void>;
+}
+/** One tool exactly as a server advertises it in `tools/list` (untrusted input). */
+export interface RawMcpTool {
+    name: string;
+    description?: string;
+    /** The server's own JSON Schema for the tool's arguments (untrusted). */
+    inputSchema?: Record<string, unknown>;
+}
+/** A `tools/call` outcome, normalized to flat text plus the server's error flag. */
+export interface McpCallResult {
+    /** Flattened textual content of the result (non-text blocks are summarized). */
+    text: string;
+    /** The server marked this result an error (still returned as data, demarcated). */
+    isError: boolean;
+}

package/dist/mcp/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared types for the MCP client (C.27). The wire protocol is JSON-RPC 2.0; the
+ * transport seam below lets tests inject a fake peer so no real server binary is
+ * required. Every type here is deliberately small — the security-bearing logic
+ * lives in `adapter.ts` (the single seam), not in these shapes.
+ */
+export {};

package/dist/tools/file/grep-files.d.ts

@@ -9,15 +9,15 @@ declare const parameters: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     pattern: string;
     path?: string | undefined;
+    maxResults?: number | undefined;
     glob?: string | undefined;
     ignoreCase?: boolean | undefined;
-    maxResults?: number | undefined;
 }, {
     pattern: string;
     path?: string | undefined;
+    maxResults?: number | undefined;
     glob?: string | undefined;
     ignoreCase?: boolean | undefined;
-    maxResults?: number | undefined;
 }>;
 /**
  * Search file *contents* for a regex within the project root. Read-only — no

package/dist/tools/registry.js

@@ -38,7 +38,9 @@ export class ToolRegistry {
         return this.list().map((tool) => ({
             name: tool.name,
             description: tool.description,
-            input_schema: toInputSchema(tool.parameters),
+            // A proxied tool (MCP, C.27) advertises its own bounds-capped schema
+            // verbatim; everything else is derived from its zod `parameters`.
+            input_schema: tool.rawInputSchema ?? toInputSchema(tool.parameters),
         }));
     }
 }

package/dist/tools/types.d.ts

@@ -102,11 +102,16 @@ export type ActionPreview =
  */
 export interface ApproveAction {
     /** The category of side effect being requested. */
-    kind: "write" | "edit" | "shell" | "patch" | "vcs" | "rollback" | "test";
+    kind: "write" | "edit" | "shell" | "patch" | "vcs" | "rollback" | "test" | "mcp";
     /** Absolute resolved path the action targets (write/edit). */
     path?: string;
     /** The command to run (shell / test). */
     command?: string;
+    /** MCP tool call (C.27): the server id and the tool name being invoked. The
+     * gate keys a session grant on this exact pair, so approving one MCP tool never
+     * covers another — and a server can never mark its own tool low-risk. */
+    server?: string;
+    tool?: string;
     /** Exact-change preview rendered above the prompt (write/edit/patch/vcs/rollback). */
     preview?: ActionPreview;
 }
@@ -154,6 +159,15 @@ export interface Tool<Schema extends ZodTypeAny = ZodTypeAny> {
     description: string;
     /** Zod schema for the tool's input arguments. */
     parameters: Schema;
+    /**
+     * An optional pre-rendered JSON Schema to advertise to the provider *verbatim*
+     * instead of deriving one from {@link parameters}. Used only by proxied tools
+     * whose schema originates elsewhere and cannot be reconstructed from zod — the
+     * MCP adapter (C.27) sets this to a server's own (bounds-capped) input schema
+     * while keeping a permissive `parameters` for local validation. Built-in tools
+     * leave it unset and are advertised from their zod schema as before.
+     */
+    rawInputSchema?: Record<string, unknown>;
     /** Run the tool against validated `input` and the ambient `ctx`. */
     execute(input: z.infer<Schema>, ctx: ToolContext): Promise<ToolResult>;
 }

package/dist/utils/child-tree.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared no-orphan machinery for long-lived child processes (C.12 LSP servers,
+ * C.27 MCP servers). A child is spawned `detached` so it leads its own process
+ * group; every kill here uses a **negative-PID** `SIGKILL` so the whole tree —
+ * the child AND any grandchildren it forked (gopls's `go`, an MCP server's
+ * helper) — dies together.
+ *
+ * A per-session graceful shutdown covers the normal path, but a hard exit
+ * (Ctrl-C, an uncaught throw) would otherwise orphan these trees. So every live
+ * child's pid is tracked in one process-wide set and force-killed on teardown.
+ * Handlers are installed ONCE, lazily, on the first registration — so unit tests
+ * that never spawn a real process never install them.
+ *
+ * This module is deliberately transport-agnostic: LSP (Content-Length framing)
+ * and MCP (newline-delimited JSON) share the SAME backstop, so `killTrackedTrees`
+ * on exit reaps both and there is a single source of truth for "no orphans".
+ */
+/**
+ * Kill a process's entire group (POSIX negative-PID `SIGKILL`), falling back to
+ * a direct kill when there is no group (or on win32). Swallows errors — the
+ * process may already be gone.
+ */
+export declare function killTree(pid: number | undefined): void;
+/**
+ * Force-kill the process group of every tracked-but-not-yet-shut-down child,
+ * then forget them. This is exactly what the `exit`/`SIGINT`/`SIGTERM`/`SIGHUP`
+ * handlers run — the last line against orphaned server trees on a hard exit.
+ * Exported so it is directly testable without raising real process signals.
+ * Idempotent: a second call is a no-op.
+ */
+export declare function killTrackedTrees(): void;
+/** Number of child trees currently tracked by the exit backstop (for tests). */
+export declare function trackedTreeCount(): number;
+/** Track a live child for the exit backstop; returns a deregister callback. */
+export declare function registerForCleanup(pid: number | undefined): () => void;

package/dist/utils/child-tree.js

@@ -0,0 +1,76 @@
+/**
+ * Shared no-orphan machinery for long-lived child processes (C.12 LSP servers,
+ * C.27 MCP servers). A child is spawned `detached` so it leads its own process
+ * group; every kill here uses a **negative-PID** `SIGKILL` so the whole tree —
+ * the child AND any grandchildren it forked (gopls's `go`, an MCP server's
+ * helper) — dies together.
+ *
+ * A per-session graceful shutdown covers the normal path, but a hard exit
+ * (Ctrl-C, an uncaught throw) would otherwise orphan these trees. So every live
+ * child's pid is tracked in one process-wide set and force-killed on teardown.
+ * Handlers are installed ONCE, lazily, on the first registration — so unit tests
+ * that never spawn a real process never install them.
+ *
+ * This module is deliberately transport-agnostic: LSP (Content-Length framing)
+ * and MCP (newline-delimited JSON) share the SAME backstop, so `killTrackedTrees`
+ * on exit reaps both and there is a single source of truth for "no orphans".
+ */
+/**
+ * Kill a process's entire group (POSIX negative-PID `SIGKILL`), falling back to
+ * a direct kill when there is no group (or on win32). Swallows errors — the
+ * process may already be gone.
+ */
+export function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            /* already exited */
+        }
+    }
+}
+const livePids = new Set();
+let handlersInstalled = false;
+/**
+ * Force-kill the process group of every tracked-but-not-yet-shut-down child,
+ * then forget them. This is exactly what the `exit`/`SIGINT`/`SIGTERM`/`SIGHUP`
+ * handlers run — the last line against orphaned server trees on a hard exit.
+ * Exported so it is directly testable without raising real process signals.
+ * Idempotent: a second call is a no-op.
+ */
+export function killTrackedTrees() {
+    for (const pid of livePids)
+        killTree(pid);
+    livePids.clear();
+}
+/** Number of child trees currently tracked by the exit backstop (for tests). */
+export function trackedTreeCount() {
+    return livePids.size;
+}
+function installExitHandlers() {
+    if (handlersInstalled)
+        return;
+    handlersInstalled = true;
+    process.once("exit", killTrackedTrees);
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.once(sig, () => {
+            killTrackedTrees();
+            // Restore default behavior and re-raise so the exit code is correct.
+            process.exit(130);
+        });
+    }
+}
+/** Track a live child for the exit backstop; returns a deregister callback. */
+export function registerForCleanup(pid) {
+    if (pid === undefined)
+        return () => { };
+    installExitHandlers();
+    livePids.add(pid);
+    return () => livePids.delete(pid);
+}