pi-gortex 0.2.0 → 0.3.0

package/README.md

@@ -66,6 +66,7 @@ environment -> `<cwd>/.pi/gortex.json` -> `<agent dir>/extensions/gortex.json`
 | `hook_mode`    | `GORTEX_HOOK_MODE` | `deny`             | Posture: `deny`, `enrich`, `consult-unlock`, `nudge`. |
 | `enforce`      | `GORTEX_ENFORCE`   | `true`             | `false` keeps the graph tools and the briefing, and wires no enforcement. |
 | `tools_preset` | `GORTEX_TOOLS`     | `core`             | Eager MCP surface. `core`/`full` use the daemon's default; `edit`/`nav`/`readonly` narrow it. |
+| `native_mcp`   | `GORTEX_NATIVE_MCP` | `true`            | On Pi 0.99+, register `gortex mcp` with Pi's built-in MCP. `false` keeps the extension's own client. |
 
 ```json
 {
@@ -75,6 +76,17 @@ environment -> `<cwd>/.pi/gortex.json` -> `<agent dir>/extensions/gortex.json`
 }
 ```
 
+The extension reads its configuration when Pi loads it, so a change takes
+effect after `/reload`.
+
+**Pi's own `mcp.json` wins.** With `native_mcp` on, the extension registers a
+server named `gortex`. A `gortex` entry in `~/.pi/agent/mcp.json` or
+`.pi/mcp.json` replaces it, including its exposure, and Pi's default exposure
+there is `codemode`, which keeps the tools out of the model's tool list. Leave
+Gortex out of `mcp.json`, or set `"exposure": "direct"` on that entry. A
+Gortex server configured under another name runs as a second connection, and
+read discipline treats its tools as non-graph calls.
+
 **If the graph tools go missing**, the first turn of the session says so and
 names `/reload` as the retry. The bridge fails open, always: an absent binary or
 a daemon that is down costs the session its graph tools, never the session.

package/docs/architecture.md

@@ -4,20 +4,55 @@ How the bridge is built, and why each piece is shaped the way it is.
 
 ## The problem
 
-Pi has no MCP support, by design; its extension API covers the ground MCP would.
 Gortex speaks MCP and owns a hook protocol that every agent it integrates with
-shares. This extension is the adapter between the two, and it does two separate
-jobs over two separate channels.
-
-## Channel 1: graph tools over an MCP stdio bridge
+shares. Pi 0.99 added built-in MCP support; earlier Pi has none. This extension
+is the adapter between the two, and it does two separate jobs over two separate
+channels.
+
+## Channel 1 on Pi 0.99+: Pi's built-in MCP
+
+On a Pi that offers `pi.registerMcpServer()`, the extension registers
+`gortex mcp` as a stdio server named `gortex` and leaves the tool channel to Pi.
+Pi spawns and connects the server, registers its tools as `mcp__gortex__<tool>`,
+follows `tools/list_changed`, renders the calls and stops the child on reload
+and quit. `gortex mcp` starts the shared daemon itself, so the extension starts
+nothing.
+
+- **Exposure.** The server is registered with `direct` exposure, so its tools
+  are declared to the model like built-in tools and Pi holds the first prompt
+  until the server connects. Pi's default, codemode, would hand scripts the
+  compact text results to parse.
+- **Timeout.** The per-request timeout matches the tool-call cap of the
+  extension's own client. Pi's default is a minute, short for some analyzers.
+- **Wire format.** Pi's client identifies itself as `pi` and declares no
+  capabilities the extension can extend. The daemon picks the compact format
+  from that client name.
+- **Readiness.** Pi reports neither a connection nor a failure to extensions. The
+  first turn waits briefly beyond Pi's own wait for an `mcp__gortex__` tool to
+  appear, and a binary that does not resolve is caught before registering,
+  because it would otherwise read as a server still connecting.
+- **Version skew.** Pi keeps the handshake to itself, so the daemon version is
+  read from the readiness line of the session briefing and checked against the
+  same floor.
+- **Precedence.** A `gortex` entry in Pi's own `mcp.json` replaces the
+  extension's registration, exposure included.
+
+The extension keeps its own client below when Pi lacks `registerMcpServer`, when
+the binary does not resolve (its spawn failure is what reaches the model), when
+Pi refuses the registration (the user is warned with Pi's reason), and when
+`native_mcp` is off. It also switches to it on session start when no loaded
+extension connects MCP servers, as with `--no-mcp`: it withdraws the
+registration then. Pi's MCP extension and the extensions that replace it
+register the `/mcp` command, which is what the check looks for.
+
+## Channel 1 on older Pi: the extension's own MCP client
 
 One Gortex MCP child process per session, spoken to over newline-delimited
 JSON-RPC on stdio. Every tool the daemon offers becomes a native Pi tool whose
 implementation forwards the call down that channel.
 
-- **Handshake.** The client identifies itself as Pi and advertises which compact
-  wire formats it can decode, so list-shaped results arrive compact without the
-  daemon needing a per-client allowlist entry. One retry after a short backoff
+- **Handshake.** The client identifies itself as Pi, which is the name the
+  daemon picks the compact wire format from. One retry after a short backoff
   absorbs a daemon that is still warming up.
 - **Version skew.** The handshake reply carries `serverInfo.version` and the
   protocol the daemon settled on. A daemon below the supported floor, or one
@@ -64,6 +99,11 @@ own way, while Gortex's classifier switches on canonical tool names and input
 keys. That translation lives on this side of the bridge, so the Go side keeps
 one vocabulary for every agent it serves.
 
+A call to a Gortex tool is flagged as a graph call and sent under the daemon's
+own tool name, which is what the postures key off. It skips the translation, so
+Gortex's `read` never passes for Pi's. On Pi's built-in MCP the same hook also
+sees each tool a codemode script calls.
+
 Postures are resolved by Gortex. Keeping that decision there is what keeps the
 behaviour identical across hosts.
 
@@ -98,9 +138,13 @@ matter:
 If the cap expires first, that turn is told the tools may not be callable yet
 and pointed at a reload. Exactly one turn reports it.
 
+On Pi's built-in MCP the session hook registers nothing, and the turn waits for
+the server's tools instead (see Channel 1 on Pi 0.99+).
+
 ## Session state
 
-The live bridge, the last bridge error and the registered tool names live at
+This applies to the extension's own client; on Pi's built-in MCP, Pi owns the
+child. The live bridge, the last bridge error and the registered tool names live at
 module scope, and that is load bearing. A reload re-imports the module, so the
 state resets with it. A new session, a resume and a fork re-invoke the extension
 factory against the cached module, and the new invocation stops the previous
@@ -110,6 +154,12 @@ invocation that overlaps it stops that bridge instead of leaving the child
 behind. State held per instance would leak a Gortex child on every new
 session.
 
+Process exit has no next invocation, so the extension also stops the bridge
+from Pi's `session_shutdown` event, which fires on quit and on every
+replacement path. The child is spawned unref'd, pipes included: they must
+never be what holds the host's event loop open, or a print or JSON run that
+finished its work hangs at exit instead of draining.
+
 ## Failure posture
 
 Fail open, everywhere. A missing binary, a daemon that is down, a handshake that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gortex",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Gortex for Pi: high-performance code-intelligence engine for AI agents, based on graph. Exposes only the information the agent needs, cutting token usage up to 50x. 100% local.",
   "keywords": [
     "pi-package",
@@ -35,9 +35,10 @@
     "prepublishOnly": "npm run check"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "~0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
-    "@types/node": "^26.4.1",
+    "@earendil-works/pi-coding-agent": "~1.0.2",
+    "@earendil-works/pi-tui": "^1.0.2",
+    "@types/node": "^24.19.1",
+    "jiti": "^2.7.0",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {

package/src/config.ts

@@ -19,6 +19,8 @@ export interface SidecarConfig {
   enforce?: boolean;
   /** Eager MCP tool preset: core | full | edit | nav | readonly. */
   tools_preset?: string;
+  /** false keeps the extension's own MCP client on a Pi that has built-in MCP. */
+  native_mcp?: boolean;
 }
 
 /** Everything the extension needs to run, fully resolved. */
@@ -31,6 +33,8 @@ export interface GortexConfig {
   enforce: boolean;
   /** Eager tool preset; the daemon's default applies when this is core/full. */
   toolsPreset: string;
+  /** Whether to hand the tool channel to Pi's built-in MCP when Pi has one. */
+  nativeMcp: boolean;
 }
 
 /** Seams for tests; every one defaults to the real environment. */
@@ -154,5 +158,11 @@ export function resolveConfig(opts: ResolveConfigOptions = {}): GortexConfig {
   const toolsPreset =
     firstString(env.GORTEX_TOOLS, project?.tools_preset, global?.tools_preset) ?? DEFAULT_TOOLS_PRESET;
 
-  return { bin, hookArgv, enforce, toolsPreset };
+  const nativeMcp =
+    parseBoolean(env.GORTEX_NATIVE_MCP) ??
+    (typeof project?.native_mcp === "boolean" ? project.native_mcp : undefined) ??
+    (typeof global?.native_mcp === "boolean" ? global.native_mcp : undefined) ??
+    true;
+
+  return { bin, hookArgv, enforce, toolsPreset, nativeMcp };
 }

package/src/index.ts

@@ -20,6 +20,18 @@ import {
   ensureDaemon,
   isBelowVersion,
 } from "./mcp-client.ts";
+import {
+  NATIVE_READY_WAIT_MS,
+  bareToolName,
+  binaryResolves,
+  daemonVersionFromBriefing,
+  isNativeGortexTool,
+  mcpConnectorLoaded,
+  registerNativeServer,
+  unregisterNativeServer,
+  supportsNativeMcp,
+  waitForNativeTools,
+} from "./native.ts";
 import { nodeProcessDeps } from "./runtime.ts";
 import type { ProcessDeps } from "./runtime.ts";
 import {
@@ -82,12 +94,18 @@ function reportVersionSkew(
         `run \`gortex upgrade\`.`,
   );
 
-  // A Pi build without a UI (print/JSON mode) or without notify must not take
-  // the session down over an advisory message.
+  notifyUser(ctx, user);
+}
+
+/**
+ * A warning for the user only. A Pi build without a UI (print/JSON mode) or
+ * without notify must not take the session down over an advisory message.
+ */
+function notifyUser(ctx: ExtensionContext | undefined, message: string): void {
   try {
-    if (ctx?.hasUI) ctx.ui.notify(user, "warning");
+    if (ctx?.hasUI) ctx.ui.notify(message, "warning");
   } catch {
-    // the model still gets the orientation line above
+    // advisory only
   }
 }
 
@@ -99,6 +117,8 @@ export interface GortexExtensionOptions {
   deps?: ProcessDeps;
   /** Readiness cap override. */
   readyWaitMs?: number;
+  /** Override for the wait on Pi's built-in MCP connecting the gortex server. */
+  nativeReadyWaitMs?: number;
 }
 
 export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensionOptions = {}): void {
@@ -109,6 +129,18 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
   const piCwd = (): string => (pi as { cwd?: string })?.cwd ?? process.cwd();
   const deps = options.deps ?? nodeProcessDeps;
   const readyWaitMs = options.readyWaitMs ?? READY_WAIT_MS;
+  const nativeReadyWaitMs = options.nativeReadyWaitMs ?? NATIVE_READY_WAIT_MS;
+
+  // On a Pi with built-in MCP, Pi owns the tool channel: it spawns `gortex mcp`
+  // (which starts the daemon itself), registers the tools and renders them.
+  // A binary that does not resolve, or a registration Pi refuses, falls back to
+  // the extension's own client, which reports its failure to the model.
+  let nativeRefusal = "";
+  let native = ((): boolean => {
+    if (!config.nativeMcp || !supportsNativeMcp(pi) || !binaryResolves(config.bin)) return false;
+    nativeRefusal = registerNativeServer(pi, config);
+    return nativeRefusal === "";
+  })();
 
   // Latched for the whole session once the first turn has run the
   // session_start hook, whether or not it produced anything to inject.
@@ -178,17 +210,29 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     }
   });
 
-  // startSession holds the body of session_start so the readiness promise
-  // above settles on every exit path, early returns included.
-  async function startSession(ctx?: ExtensionContext): Promise<void> {
-    ensureDaemon(config.bin, deps);
-    gortexToolNames.clear();
+  // Stops the live bridge, if any, and clears the slot. Shared by
+  // session_start and session_shutdown so both paths stay in sync.
+  function stopBridge(): void {
     clearSyncTimer();
     const previous = getClient();
     if (previous) {
       previous.stop();
       setClient(null);
     }
+  }
+
+  // startSession holds the body of session_start so the readiness promise
+  // above settles on every exit path, early returns included.
+  async function startSession(ctx?: ExtensionContext): Promise<void> {
+    if (native && !mcpConnectorLoaded(pi)) {
+      unregisterNativeServer(pi);
+      native = false;
+    }
+    if (native) return;
+    if (nativeRefusal) notifyUser(ctx, `Pi refused the gortex MCP server (${nativeRefusal}), so the extension runs its own client.`);
+    ensureDaemon(config.bin, deps);
+    gortexToolNames.clear();
+    stopBridge();
     const c = new MCPStdioClient({ bin: config.bin, toolsPreset: config.toolsPreset, deps });
     // Claim the slot before the first await: an overlapping
     // session_start (rapid /new or /reload) then sees and stops THIS
@@ -216,16 +260,22 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
 
   // Fires before the agent loop's first LLM call. It can't mutate messages
   // itself, so it just parks the orientation for the `context` hook.
-  pi.on("before_agent_start", async () => {
+  pi.on("before_agent_start", async (_event, ctx) => {
     if (startupHookRan) return;
     startupHookRan = true; // before the first await, so a second turn can't race in
     // Pi awaits each listener, so this holds the turn until the tools are
     // registered and bridgeError reflects the handshake (or the cap expires).
-    const ready = await waitForSession(readyWaitMs);
+    // session_start settles `native` first: it falls back when nothing connects MCP.
+    const sessionDone = await waitForSession(readyWaitMs);
+    const ready = native ? await waitForNativeTools(pi, nativeReadyWaitMs) : sessionDone;
     const decision = callHook(config.hookArgv, deps, {
       event: "session_start",
-      cwd: piCwd(),
+      cwd: ctx?.cwd ?? piCwd(),
     });
+    // Pi's MCP keeps the handshake to itself, so the version comes from the briefing.
+    if (native && decision.orientation) {
+      reportVersionSkew(ctx, daemonVersionFromBriefing(decision.orientation), "");
+    }
     const parts: string[] = [];
     const bridgeError = getBridgeError();
     if (bridgeError) {
@@ -276,15 +326,23 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     return;
   });
 
+  // Never let the bridge child outlive the session.
+  pi.on("session_shutdown", async () => {
+    stopBridge();
+  });
+
   if (!config.enforce) return;
 
   // Enforcement: every non-Gortex tool call is checked against the Go hook.
   pi.on("tool_call", async (event: ToolCallEvent, ctx: ExtensionContext): Promise<ToolCallEventResult | void> => {
     const piName: string = (event as { toolName?: string })?.toolName ?? "";
     const piInput: Record<string, unknown> = (event?.input as Record<string, unknown>) ?? {};
-    const isGortexTool = gortexToolNames.has(piName);
+    const isGortexTool = native ? isNativeGortexTool(piName) : gortexToolNames.has(piName);
 
-    const norm = normalizeToolCall(piName, piInput);
+    // A graph tool keeps its own name: Gortex's `read` is no Pi `read`.
+    const norm = isGortexTool
+      ? { tool_name: bareToolName(piName), tool_input: piInput }
+      : normalizeToolCall(piName, piInput);
     const decision = callHook(config.hookArgv, deps, {
       event: "tool_call",
       tool_name: norm.tool_name,

package/src/mcp-client.ts

@@ -53,6 +53,24 @@ export function isBelowVersion(actual: string, floor: string): boolean {
 // session. Fail open to the daemon's default surface instead.
 const FORWARDED_PRESETS = new Set(["edit", "nav", "readonly"]);
 
+/**
+ * The variables `gortex mcp` needs on top of `env` to serve `toolsPreset`.
+ * The daemon's own default surface already IS core/defer; only a recognised
+ * non-default preset needs the proxy-side narrowing.
+ */
+export function presetEnv(
+  toolsPreset: string,
+  env: Record<string, string | undefined>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const preset = toolsPreset.trim().toLowerCase();
+  const tools = env.GORTEX_TOOLS || (FORWARDED_PRESETS.has(preset) ? preset : "");
+  if (tools && !env.GORTEX_TOOLS) out.GORTEX_TOOLS = tools;
+  // Never let a preset hide-block tools promoted later by tools_search.
+  if (tools && !env.GORTEX_TOOLS_MODE) out.GORTEX_TOOLS_MODE = "defer";
+  return out;
+}
+
 export interface MCPStdioClientOptions {
   bin: string;
   toolsPreset: string;
@@ -137,16 +155,7 @@ export class MCPStdioClient {
   }
 
   private childEnv(): Record<string, string | undefined> {
-    const env: Record<string, string | undefined> = { ...this.env };
-    const preset = this.toolsPreset.trim().toLowerCase();
-    // The daemon's own default surface already IS core/defer; only a
-    // recognised non-default preset needs the proxy-side narrowing.
-    if (!env.GORTEX_TOOLS && FORWARDED_PRESETS.has(preset)) {
-      env.GORTEX_TOOLS = preset;
-    }
-    // Never let a preset hide-block tools promoted later by tools_search.
-    if (env.GORTEX_TOOLS && !env.GORTEX_TOOLS_MODE) env.GORTEX_TOOLS_MODE = "defer";
-    return env;
+    return { ...this.env, ...presetEnv(this.toolsPreset, this.env) };
   }
 
   private spawnChild(): void {
@@ -165,6 +174,11 @@ export class MCPStdioClient {
     child.stdin?.on("error", () => {}); // EPIPE race: child may exit before stdin.write() finishes
     child.on("error", () => this.markExited(new Error("gortex mcp spawn failed")));
     child.on("exit", () => this.markExited(new Error("gortex mcp exited")));
+    // The child and its pipes must never keep the event loop alive.
+    child.unref?.();
+    child.stdin?.unref?.();
+    child.stdout?.unref?.();
+    child.stderr?.unref?.();
   }
 
   private markExited(err: Error): void {

package/src/native.ts

@@ -0,0 +1,141 @@
+// The tool channel on Pi's built-in MCP (Pi >= 0.99): the extension registers
+// `gortex mcp` with pi.registerMcpServer() and Pi owns the connection, the tool
+// registry and the rendering. See docs/architecture.md.
+
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { GortexConfig } from "./config.ts";
+import { CALL_TIMEOUT_MS, presetEnv } from "./mcp-client.ts";
+
+export const MCP_SERVER_NAME = "gortex";
+/** Pi names a server's tools `mcp__<server>__<tool>`. */
+export const MCP_TOOL_PREFIX = `mcp__${MCP_SERVER_NAME}__`;
+
+const SERVER_DESCRIPTION =
+  "Gortex code graph of the indexed repositories: symbol search, source reads, usages, " +
+  "call chains, change impact and graph-aware edits.";
+
+// Pi 0.87 declares none of the MCP members, so they are read structurally.
+type NativeMcpApi = Pick<ExtensionAPI, "registerMcpServer" | "unregisterMcpServer" | "getAllTools" | "getCommands">;
+
+export function supportsNativeMcp(pi: ExtensionAPI): boolean {
+  return typeof (pi as Partial<NativeMcpApi>).registerMcpServer === "function";
+}
+
+export function nativeServerConfig(
+  config: GortexConfig,
+  env: Record<string, string | undefined> = process.env,
+): Parameters<ExtensionAPI["registerMcpServer"]>[1] {
+  return {
+    command: config.bin,
+    args: ["mcp"],
+    env: presetEnv(config.toolsPreset, env),
+    // Declared to the model like built-in tools, and the first prompt waits
+    // for the connection. Codemode would hand scripts gcx text to parse.
+    exposure: "direct",
+    timeout: CALL_TIMEOUT_MS / 1000,
+    description: SERVER_DESCRIPTION,
+  };
+}
+
+/** Registers the server; returns why it failed, or "" on success. */
+export function registerNativeServer(pi: ExtensionAPI, config: GortexConfig): string {
+  try {
+    (pi as NativeMcpApi).registerMcpServer(MCP_SERVER_NAME, nativeServerConfig(config));
+    return "";
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
+/**
+ * Whether `bin` names an executable file, directly or through PATH. Pi reports
+ * no connection failure to extensions, so a server that cannot spawn would
+ * read as one still connecting.
+ */
+export function binaryResolves(bin: string, env: Record<string, string | undefined> = process.env): boolean {
+  const exts = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")] : [""];
+  const candidates = /[\\/]/.test(bin)
+    ? [bin]
+    : (env.PATH ?? "").split(delimiter).filter(Boolean).map((dir) => join(dir, bin));
+  return candidates.some((path) =>
+    exts.some((ext) => {
+      try {
+        accessSync(path + ext, constants.X_OK);
+        return statSync(path + ext).isFile();
+      } catch {
+        return false;
+      }
+    }),
+  );
+}
+
+/**
+ * The daemon version the session_start briefing reports, or "" when it names
+ * none. The briefing is the only place it reaches the extension on Pi's MCP.
+ */
+export function daemonVersionFromBriefing(briefing: string): string {
+  return /Gortex daemon [^(\n]*\(v(\d[^,\s)]*)/.exec(briefing)?.[1] ?? "";
+}
+
+/**
+ * Whether an extension that connects MCP servers is loaded. Pi's own MCP
+ * extension and the ones that replace it register `/mcp`; `--no-mcp` and
+ * `-ne` without `builtin:mcp` leave a registration with nothing to connect it.
+ * Read on session_start, once every extension has loaded. A Pi that cannot
+ * list commands is trusted to connect the server.
+ */
+export function mcpConnectorLoaded(pi: ExtensionAPI): boolean {
+  try {
+    return (pi as NativeMcpApi).getCommands().some((command) => command.name === "mcp");
+  } catch {
+    return true;
+  }
+}
+
+/** Withdraws the registration, which also keeps Pi from reporting it as unconnected. */
+export function unregisterNativeServer(pi: ExtensionAPI): void {
+  try {
+    (pi as NativeMcpApi).unregisterMcpServer(MCP_SERVER_NAME);
+  } catch {
+    // already gone, or this instance has been invalidated
+  }
+}
+
+export function isNativeGortexTool(name: string): boolean {
+  return name.startsWith(MCP_TOOL_PREFIX);
+}
+
+/** The daemon's own name for a native tool, as Gortex guidance spells it. */
+export function bareToolName(name: string): string {
+  return isNativeGortexTool(name) ? name.slice(MCP_TOOL_PREFIX.length) : name;
+}
+
+/** True once Pi has registered at least one tool from the gortex server. */
+export function nativeToolsReady(pi: ExtensionAPI): boolean {
+  try {
+    return (pi as NativeMcpApi).getAllTools().some((tool) => isNativeGortexTool(tool.name));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * How long the first turn waits for the gortex tools on top of Pi's own wait.
+ * Pi's MCP extension already holds the first prompt for up to 10s on a direct
+ * server, so this only covers a daemon still warming up after that.
+ */
+export const NATIVE_READY_WAIT_MS = 5_000;
+
+/** Resolves true once the gortex tools are registered, false when `ms` passes first. */
+export async function waitForNativeTools(pi: ExtensionAPI, ms: number, pollMs = 100): Promise<boolean> {
+  const deadline = Date.now() + ms;
+  while (!nativeToolsReady(pi)) {
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+  return true;
+}

package/src/runtime.ts

@@ -8,11 +8,15 @@ import type { SpawnOptions } from "node:child_process";
 
 export interface ChildStream {
   on(event: string, listener: (chunk: unknown) => void): unknown;
+  /** Drops the event-loop reference; I/O keeps working. */
+  unref?(): unknown;
 }
 
 export interface ChildStdin {
   on(event: string, listener: (err: unknown) => void): unknown;
   write(chunk: string): unknown;
+  /** Drops the event-loop reference; I/O keeps working. */
+  unref?(): unknown;
 }
 
 /** The subset of ChildProcess the MCP bridge and the daemon launcher touch. */

package/src/state.ts

@@ -3,7 +3,9 @@
 // Shared at module level on purpose: a new invocation's session_start stops the
 // previous invocation's bridge child, which works only while both invocations
 // see the same `client`. Move this into the factory closure and every `/new`
-// leaks a `gortex mcp` process.
+// leaks a `gortex mcp` process. Reload is the exception: Pi re-imports the
+// extension with a fresh module graph, so there the old instance's
+// session_shutdown handler is what stops its bridge.
 
 import type { MCPStdioClient } from "./mcp-client.ts";