context-mode 1.0.131 → 1.0.132

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.131"
+    "version": "1.0.132"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.131",
+      "version": "1.0.132",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.131",
+  "version": "1.0.132",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.131",
+  "version": "1.0.132",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.131",
+  "version": "1.0.132",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/README.md

@@ -124,7 +124,7 @@ This gives you all 11 MCP tools without automatic routing. The model can still u
 <details>
 <summary><strong>Gemini CLI</strong> — one config file, hooks included</summary>
 
-**Prerequisites:** Node.js 18+, Gemini CLI installed.
+**Prerequisites:** Node.js >= 22.5 (or Bun), Gemini CLI installed.
 
 **Install:**
 
@@ -197,7 +197,7 @@ Full config reference: [`configs/gemini-cli/settings.json`](configs/gemini-cli/s
 <details>
 <summary><strong>VS Code Copilot</strong> — hooks with SessionStart</summary>
 
-**Prerequisites:** Node.js 18+, VS Code with Copilot Chat v0.32+.
+**Prerequisites:** Node.js >= 22.5 (or Bun), VS Code with Copilot Chat v0.32+.
 
 **Install:**
 
@@ -254,7 +254,7 @@ Full hook config including PreCompact: [`configs/vscode-copilot/hooks.json`](con
 <details>
 <summary><strong>JetBrains Copilot</strong> — hooks with SessionStart</summary>
 
-**Prerequisites:** Node.js 18+, JetBrains IDE with GitHub Copilot plugin v1.5.57+.
+**Prerequisites:** Node.js >= 22.5 (or Bun), JetBrains IDE with GitHub Copilot plugin v1.5.57+.
 
 **Install:**
 
@@ -305,7 +305,7 @@ Full setup guide: [`docs/jetbrains-copilot.md`](docs/jetbrains-copilot.md)
 <details>
 <summary><strong>Cursor</strong> — hooks with stop support</summary>
 
-**Prerequisites:** Node.js 18+, Cursor with agent mode.
+**Prerequisites:** Node.js >= 22.5 (or Bun), Cursor with agent mode.
 
 > **🚧 Work in progress** — the Marketplace plugin is **awaiting Cursor team review**. Until it's listed, install via the local-folder path described in Option A. Tracking in [#485](https://github.com/mksglu/context-mode/issues/485) / [#489](https://github.com/mksglu/context-mode/pull/489).
 
@@ -406,7 +406,7 @@ Full configs: [`configs/cursor/hooks.json`](configs/cursor/hooks.json) | [`confi
 <details>
 <summary><strong>OpenCode</strong> — TypeScript plugin with hooks</summary>
 
-**Prerequisites:** Node.js 18+, OpenCode installed.
+**Prerequisites:** Node.js >= 22.5 (or Bun), OpenCode installed.
 
 **Install:**
 
@@ -456,7 +456,7 @@ Full configs: [`configs/opencode/opencode.json`](configs/opencode/opencode.json)
 <details>
 <summary><strong>KiloCode</strong> — TypeScript plugin with hooks</summary>
 
-**Prerequisites:** Node.js 18+, KiloCode installed.
+**Prerequisites:** Node.js >= 22.5 (or Bun), KiloCode installed.
 
 **Install:**
 
@@ -541,7 +541,7 @@ Full documentation: [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md)
 <details>
 <summary><strong>Codex CLI</strong> — MCP + hooks</summary>
 
-**Prerequisites:** Node.js 18+, Codex CLI installed.
+**Prerequisites:** Node.js >= 22.5 (or Bun), Codex CLI installed.
 
 **Install:**
 
@@ -606,7 +606,7 @@ Full documentation: [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md)
 <details>
 <summary><strong>Qwen Code</strong> — MCP + hooks (identical wire protocol to Claude Code)</summary>
 
-**Prerequisites:** Node.js 18+, Qwen Code installed (`npm install -g @qwen-code/qwen-code`).
+**Prerequisites:** Node.js >= 22.5 (or Bun), Qwen Code installed (`npm install -g @qwen-code/qwen-code`).
 
 1. Install context-mode:
 
@@ -660,7 +660,7 @@ Full documentation: [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md)
 <details>
 <summary><strong>Antigravity</strong> — MCP-only, no hooks</summary>
 
-**Prerequisites:** Node.js 18+, Antigravity installed.
+**Prerequisites:** Node.js >= 22.5 (or Bun), Antigravity installed.
 
 **Install:**
 
@@ -701,7 +701,7 @@ Full configs: [`configs/antigravity/mcp_config.json`](configs/antigravity/mcp_co
 <details>
 <summary><strong>Kiro</strong> — hooks with steering file</summary>
 
-**Prerequisites:** Node.js 18+, Kiro with MCP enabled (Settings > search "MCP").
+**Prerequisites:** Node.js >= 22.5 (or Bun), Kiro with MCP enabled (Settings > search "MCP").
 
 **Install:**
 
@@ -759,7 +759,7 @@ Full configs: [`configs/kiro/mcp.json`](configs/kiro/mcp.json) | [`configs/kiro/
 <details>
 <summary><strong>Zed</strong> — MCP-only, no hooks</summary>
 
-**Prerequisites:** Node.js 18+, Zed installed.
+**Prerequisites:** Node.js >= 22.5 (or Bun), Zed installed.
 
 **Install:**
 
@@ -802,7 +802,7 @@ Full configs: [`configs/kiro/mcp.json`](configs/kiro/mcp.json) | [`configs/kiro/
 <details>
 <summary><strong>Pi Coding Agent</strong> — extension with full hook support</summary>
 
-**Prerequisites:** Node.js 18+, Pi Coding Agent installed.
+**Prerequisites:** Node.js >= 22.5 (or Bun), Pi Coding Agent installed.
 
 **Install:**
 
@@ -849,7 +849,7 @@ Full configs: [`configs/kiro/mcp.json`](configs/kiro/mcp.json) | [`configs/kiro/
 <details>
 <summary><strong>OMP (Oh My Pi)</strong> — plugin with full hook support</summary>
 
-**Prerequisites:** Node.js 18+, Oh My Pi installed.
+**Prerequisites:** Node.js >= 22.5 (or Bun), Oh My Pi installed.
 
 **Install — plugin path (recommended):**
 
@@ -924,7 +924,7 @@ Full configs: [`configs/omp/mcp.json`](configs/omp/mcp.json) | [`configs/omp/SYS
 
 Context Mode uses [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) on Node.js, which ships prebuilt native binaries for most platforms. On glibc >= 2.31 systems (Ubuntu 20.04+, Debian 11+, Fedora 34+, macOS, Windows), `npm install` works without any build tools.
 
-**Linux + Node.js >= 22.13:** Context Mode automatically uses the built-in `node:sqlite` module instead of `better-sqlite3`. This eliminates the native addon entirely, avoiding [sporadic SIGSEGV crashes](https://github.com/nodejs/node/issues/62515) caused by V8's `madvise(MADV_DONTNEED)` corrupting the addon's `.got.plt` section on Linux. No configuration needed — detection is automatic. Falls back to `better-sqlite3` on older Node.js versions.
+**Linux + Node.js >= 22.5:** Context Mode automatically uses the built-in `node:sqlite` module instead of `better-sqlite3`. This eliminates the native addon entirely, avoiding [sporadic SIGSEGV crashes](https://github.com/nodejs/node/issues/62515) caused by V8's `madvise(MADV_DONTNEED)` corrupting the addon's `.got.plt` section on Linux. No configuration needed — detection is automatic. **Linux + Node < 22.5 is unsupported** ([#564](https://github.com/mksglu/context-mode/issues/564)) — `npm install` will fail with remediation instructions.
 
 **Bun users:** No native compilation needed. Context Mode automatically detects Bun and uses the built-in `bun:sqlite` module via a compatibility adapter. `better-sqlite3` and all its build dependencies are skipped entirely.
 
@@ -986,7 +986,7 @@ When output exceeds 5 KB and an `intent` is provided, Context Mode switches to i
 
 ## How the Knowledge Base Works
 
-The `ctx_index` tool chunks markdown content by headings while keeping code blocks intact, then stores them in a **SQLite FTS5** (Full-Text Search 5) virtual table. The SQLite backend is selected automatically at runtime: `bun:sqlite` on Bun, `node:sqlite` on Linux + Node.js >= 22.13, and `better-sqlite3` everywhere else. Search uses **BM25 ranking** — a probabilistic relevance algorithm that scores documents based on term frequency, inverse document frequency, and document length normalization. **Porter stemming** is applied at index time so "running", "runs", and "ran" match the same stem. Titles and headings are weighted **5x** in BM25 scoring for precise navigational queries.
+The `ctx_index` tool chunks markdown content by headings while keeping code blocks intact, then stores them in a **SQLite FTS5** (Full-Text Search 5) virtual table. The SQLite backend is selected automatically at runtime: `bun:sqlite` on Bun, `node:sqlite` on Node.js >= 22.5, and `better-sqlite3` everywhere else. Search uses **BM25 ranking** — a probabilistic relevance algorithm that scores documents based on term frequency, inverse document frequency, and document length normalization. **Porter stemming** is applied at index time so "running", "runs", and "ran" match the same stem. Titles and headings are weighted **5x** in BM25 scoring for precise navigational queries.
 
 When you call `ctx_search`, it returns relevant content snippets focused around matching query terms — not full documents, not approximations, the actual indexed content with smart extraction around what you're looking for. `ctx_fetch_and_index` extends this to URLs: fetch, convert HTML to markdown, chunk, index. The raw page never enters context. Use the `contentType` parameter to filter results by type (e.g. `code` or `prose`).
 
@@ -1361,6 +1361,17 @@ That blocks loopback + RFC1918 + ULA in addition to the always-blocked ranges. U
 
 `tool_input` for any `mcp__*` tool call is also redacted before persistence — keys matching `authorization`, `token`, `secret`, `password`, `api_key`, `cookie`, `signature`, `private_key` get masked to `[REDACTED]` so credentials in MCP arguments don't end up in the session DB.
 
+### Lifecycle environment variables
+
+Two runtime knobs control how MCP server processes self-manage. Defaults are safe — only set these to opt-out of the leak-fix introduced in v1.0.132 ([#565](https://github.com/mksglu/context-mode/issues/565) / [#568](https://github.com/mksglu/context-mode/pull/568)).
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CONTEXT_MODE_IDLE_TIMEOUT_MS` | `900000` (15 min) | An MCP child self-exits cleanly after this many milliseconds of stdin/request inactivity. Hosts like OpenCode and KiloCode open one MCP child per session and per subagent — without this, idle children accumulate to 25+ processes / 1.6 GB RSS in long-lived shells. Set to `0` to disable self-shutdown (rarely needed; useful only for daemons that must outlive their parent). |
+| `CONTEXT_MODE_STARTUP_SWEEP` | `1` (enabled) | At boot, a newly-spawned MCP child reaps any other context-mode MCP server pids that share its parent process (`sameParentOnly: true` — never touches MCP children of a different host). This reclaims accumulated siblings immediately instead of waiting for each idle timer to fire. Set to `0` or `false` to disable (useful when you intentionally want multiple concurrent MCP children under the same host, e.g. multi-tenant test runners). |
+
+Both vars are read fresh at MCP server start — no restart of the host CLI is required, just spawn a new MCP child (open a new session) for changes to take effect. Invalid values (non-numeric `CONTEXT_MODE_IDLE_TIMEOUT_MS`, unrecognized `CONTEXT_MODE_STARTUP_SWEEP`) fall back to defaults silently.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and TDD guidelines.

package/build/cli.js

@@ -28,6 +28,8 @@ import { discoverSiblingMcpPids, killSiblingMcpServers } from "./util/sibling-mc
 // mcpServers args. Single source of truth shared with start.mjs HEAL block + postinstall.
 // @ts-expect-error — JS module, no TS declarations
 import { healPluginJsonMcpServers, healMcpJsonArgs } from "../scripts/heal-installed-plugins.mjs";
+// @ts-expect-error — JS module, no TS declarations
+import { detectWindowsVsYear } from "../scripts/heal-better-sqlite3.mjs";
 // Private 16-LOC copy of browserOpenArgv. Canonical version lives in src/server.ts;
 // duplicated here so the cli bundle does not pull server.ts top-level boot side effects.
 // Keep in sync — pure data, no I/O.
@@ -300,6 +302,34 @@ async function doctor() {
     s.stop("Diagnostics complete");
     // Runtime check
     p.note(getRuntimeSummary(runtimes), "Runtimes");
+    // ── Issue #564 — Linux + Node < 22.5 + no Bun is unsafe ────────────
+    // V8's madvise(MADV_DONTNEED) can corrupt better-sqlite3's native addon
+    // `.got.plt` on Linux, causing sporadic SIGSEGV (1-4/hour). The 22.5
+    // gate (`hasModernSqlite()` in src/db-base.ts:226-244) is the contract:
+    // at or above it we use node:sqlite (built-in, no native addon, no
+    // .got.plt to corrupt); below it we fall through to better-sqlite3
+    // which WILL crash. engines.node + a hard-fail postinstall guard this
+    // at install time, but doctor() surfaces it for already-installed users
+    // (and for adapters whose MCP host swallows stderr during install).
+    // Refs:
+    //   - https://github.com/nodejs/node/issues/62515
+    //   - https://github.com/mksglu/context-mode/issues/564
+    {
+        const { hasModernSqlite } = await import("./db-base.js");
+        if (process.platform === "linux" &&
+            !hasModernSqlite() &&
+            !hasBunRuntime()) {
+            criticalFails++;
+            p.log.error(color.red("Node version: FAIL") +
+                ` — Linux + Node ${process.versions.node} is unsafe (SIGSEGV)` +
+                color.dim("\n  context-mode requires Node.js >= 22.5 (or Bun) on Linux to avoid the" +
+                    "\n  V8 madvise(MADV_DONTNEED) SIGSEGV in better-sqlite3 (1-4/hour)." +
+                    "\n  Refs: https://github.com/nodejs/node/issues/62515" +
+                    "\n        https://github.com/mksglu/context-mode/issues/564" +
+                    "\n  Fix:  nvm install 22.5 && nvm use 22.5 && npm install -g context-mode" +
+                    "\n  Or:   curl -fsSL https://bun.sh/install | bash && bun add -g context-mode"));
+        }
+    }
     // Speed tier
     if (hasBunRuntime()) {
         p.log.success(color.green("Performance: FAST") +
@@ -736,10 +766,12 @@ async function upgrade(opts) {
             catch { /* never block upgrade on discovery/kill failure */ }
             // Step 2: Install dependencies + build
             s.start("Installing dependencies & building");
+            const vsYear = detectWindowsVsYear();
             npmExecFile(["install", "--no-audit", "--no-fund"], {
                 cwd: srcDir,
                 stdio: "pipe",
                 timeout: 120000,
+                ...(vsYear ? { env: { ...process.env, npm_config_msvs_version: vsYear } } : {}),
             });
             npmExecFile(["run", "build"], {
                 cwd: srcDir,

package/build/lifecycle.d.ts

@@ -20,7 +20,54 @@ export interface LifecycleGuardOptions {
     onShutdown: () => void;
     /** Injectable parent-alive check (for testing). Default: ppid-based check. */
     isParentAlive?: () => boolean;
+    /**
+     * Idle shutdown threshold in ms (#565). When the server has handled no
+     * MCP activity for this long, `onShutdown` fires. `0` disables.
+     * Default: env `CONTEXT_MODE_IDLE_TIMEOUT_MS`, else 15 minutes.
+     * Skipped on TTY stdin (interactive dev / OpenCode ts-plugin standalone).
+     *
+     * Pair with the returned `recordActivity()` callback — call it on every
+     * MCP request the server handles so genuinely busy servers never trip.
+     */
+    idleTimeoutMs?: number;
+    /** Test injection — defaults to `Date.now`. */
+    now?: () => number;
 }
+/**
+ * Hybrid return type: callable like the original `() => void` cleanup (kept
+ * for backwards compatibility with #103/#236/#311/#388/#534 test suites),
+ * and additionally exposes `recordActivity` for the idle-timeout path (#565)
+ * and `stop` as an explicit alias.
+ */
+export interface LifecycleGuardHandle {
+    /** Stop the guard. Calling the handle directly is equivalent. */
+    (): void;
+    /** Bumps the "last activity" timestamp so the idle timer doesn't fire. */
+    recordActivity: () => void;
+    /** Stop the guard. Alias for invoking the handle. */
+    stop: () => void;
+}
+/**
+ * Resolve the idle-shutdown threshold (#565).
+ *
+ * OpenCode + KiloCode open a fresh MCP client per session AND per subagent
+ * task, but never tear them down for the host's lifetime. A host alive for
+ * a working day accumulates one stdio child per session — observed live at
+ * 26 children / 1.6 GB RSS under a single `opencode serve` parent.
+ *
+ * None of the existing exit paths (ppid poll, grandparent reparent, stdin
+ * EOF, SIGTERM) fire while the host stays alive. Idle shutdown is the
+ * structural fix: a server with no work to do should release its memory.
+ *
+ * Default 15 min strikes a balance — long enough that a paused
+ * conversation does not pay a cold-start on every resume, short enough
+ * that 8 hours of unused sessions do not pin GB of RAM.
+ *
+ * Set env to `0` to disable entirely.
+ *
+ * Exported for unit-testing.
+ */
+export declare function idleTimeoutForEnv(env?: NodeJS.ProcessEnv): number;
 /** Injectable dependencies for {@link makeDefaultIsParentAlive}. */
 export interface IsParentAliveDeps {
     /** Read the current ppid. Default: `() => process.ppid`. */
@@ -60,7 +107,9 @@ export declare function makeDefaultIsParentAlive(deps?: IsParentAliveDeps): () =
  */
 export declare function lifecycleGuardIntervalForEnv(env?: NodeJS.ProcessEnv): number;
 /**
- * Start the lifecycle guard. Returns a cleanup function.
+ * Start the lifecycle guard. Returns a handle with `recordActivity` (call
+ * on every MCP request to keep idle timer from firing) and `stop`.
+ *
  * Skipped automatically when stdin is a TTY (e.g. OpenCode ts-plugin).
  */
-export declare function startLifecycleGuard(opts: LifecycleGuardOptions): () => void;
+export declare function startLifecycleGuard(opts: LifecycleGuardOptions): LifecycleGuardHandle;

package/build/lifecycle.js

@@ -14,6 +14,35 @@
  * Cross-platform: macOS, Linux, Windows.
  */
 import { execFileSync } from "node:child_process";
+/**
+ * Resolve the idle-shutdown threshold (#565).
+ *
+ * OpenCode + KiloCode open a fresh MCP client per session AND per subagent
+ * task, but never tear them down for the host's lifetime. A host alive for
+ * a working day accumulates one stdio child per session — observed live at
+ * 26 children / 1.6 GB RSS under a single `opencode serve` parent.
+ *
+ * None of the existing exit paths (ppid poll, grandparent reparent, stdin
+ * EOF, SIGTERM) fire while the host stays alive. Idle shutdown is the
+ * structural fix: a server with no work to do should release its memory.
+ *
+ * Default 15 min strikes a balance — long enough that a paused
+ * conversation does not pay a cold-start on every resume, short enough
+ * that 8 hours of unused sessions do not pin GB of RAM.
+ *
+ * Set env to `0` to disable entirely.
+ *
+ * Exported for unit-testing.
+ */
+export function idleTimeoutForEnv(env = process.env) {
+    const raw = env.CONTEXT_MODE_IDLE_TIMEOUT_MS;
+    if (raw === undefined)
+        return 15 * 60 * 1000;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0)
+        return 15 * 60 * 1000;
+    return n;
+}
 /** Read grandparent PID via `ps -o ppid= -p $PPID`. Returns NaN on failure or Windows. */
 function readGrandparentPpidImpl() {
     if (process.platform === "win32")
@@ -95,25 +124,52 @@ export function lifecycleGuardIntervalForEnv(env = process.env) {
     return 1000;
 }
 /**
- * Start the lifecycle guard. Returns a cleanup function.
+ * Start the lifecycle guard. Returns a handle with `recordActivity` (call
+ * on every MCP request to keep idle timer from firing) and `stop`.
+ *
  * Skipped automatically when stdin is a TTY (e.g. OpenCode ts-plugin).
  */
 export function startLifecycleGuard(opts) {
     const interval = opts.checkIntervalMs ?? lifecycleGuardIntervalForEnv();
     const check = opts.isParentAlive ?? defaultIsParentAlive;
+    const idleTimeoutMs = opts.idleTimeoutMs ?? idleTimeoutForEnv();
+    const now = opts.now ?? Date.now;
     let stopped = false;
+    let lastActivity = now();
     const shutdown = () => {
         if (stopped)
             return;
         stopped = true;
         opts.onShutdown();
     };
-    // P0: Periodic parent liveness check
+    const recordActivity = () => {
+        lastActivity = now();
+    };
+    // P0: Periodic parent liveness check.
     const timer = setInterval(() => {
         if (!check())
             shutdown();
     }, interval);
     timer.unref();
+    // P0+: Idle shutdown (#565). Runs on its OWN tick — distinct from the
+    // 30 s parent-liveness poll — so a 15 min idle timeout actually reacts
+    // close to 15 min instead of "next 30 s tick after 15 min". Pick the
+    // tick as min(idleTimeoutMs / 6, 30 s) so a short timeout (e.g. 3 s in
+    // e2e tests, 60 s in dev) reacts within ~16 % of its window while a
+    // production 15 min timeout still polls every 30 s (cheap).
+    //
+    // Skipped on TTY because interactive dev sessions are expected to
+    // sit idle between commands, and also when idleTimeoutMs is 0 (env
+    // opt-out via CONTEXT_MODE_IDLE_TIMEOUT_MS=0).
+    let idleTimer = null;
+    if (idleTimeoutMs > 0 && !process.stdin.isTTY) {
+        const idleTick = Math.max(50, Math.min(Math.floor(idleTimeoutMs / 6), 30_000));
+        idleTimer = setInterval(() => {
+            if (now() - lastActivity > idleTimeoutMs)
+                shutdown();
+        }, idleTick);
+        idleTimer.unref();
+    }
     // P0: OS signals — terminal close, kill, ctrl+c
     const signals = ["SIGTERM", "SIGINT"];
     if (process.platform !== "win32")
@@ -142,11 +198,19 @@ export function startLifecycleGuard(opts) {
     if (!process.stdin.isTTY) {
         process.stdin.on("end", onStdinEnd);
     }
-    return () => {
+    const cleanup = () => {
         stopped = true;
         clearInterval(timer);
+        if (idleTimer)
+            clearInterval(idleTimer);
         for (const sig of signals)
             process.removeListener(sig, shutdown);
         process.stdin.removeListener("end", onStdinEnd);
     };
+    // Hybrid: callable for legacy `const cleanup = startLifecycleGuard(...)`
+    // sites, with `.recordActivity` / `.stop` properties for the new contract.
+    const handle = cleanup;
+    handle.recordActivity = recordActivity;
+    handle.stop = cleanup;
+    return handle;
 }

package/build/server.js

@@ -78,6 +78,20 @@ const CM_FS_PRELOAD = join(tmpdir(), `cm-fs-preload-${process.pid}.js`);
 writeFileSync(CM_FS_PRELOAD, `(function(){var __cm_fs=0;process.on('exit',function(){if(__cm_fs>0)try{process.stderr.write('__CM_FS__:'+__cm_fs+'\\n')}catch(e){}});try{var f=require('fs');var ors=f.readFileSync;f.readFileSync=function(){var r=ors.apply(this,arguments);if(Buffer.isBuffer(r))__cm_fs+=r.length;else if(typeof r==='string')__cm_fs+=Buffer.byteLength(r);return r;};}catch(e){}})();\n`);
 // Lazy singleton — no DB overhead unless index/search is used
 let _store = null;
+/**
+ * Build the FK-attribution object passed to every ContentStore.index*() call
+ * in this process. CLAUDE_SESSION_ID is the only MCP-side handle we have on
+ * the current session — eventId stays undefined because MCP tool invocations
+ * are not paired with PostToolUse event rows at index time (the hook fires
+ * AFTER the tool returns). Empty-string fallback inside #insertChunks keeps
+ * legacy unattributed rows readable.
+ */
+function currentAttribution() {
+    const sessionId = process.env.CLAUDE_SESSION_ID;
+    if (!sessionId)
+        return undefined;
+    return { sessionId };
+}
 /**
  * Auto-index session events files written by SessionStart hook.
  * Scans ~/.claude/context-mode/sessions/ for *-events.md files.
@@ -95,7 +109,7 @@ function maybeIndexSessionEvents(store) {
         for (const file of files) {
             const filePath = join(sessionsDir, file);
             try {
-                store.index({ path: filePath, source: "session-events" });
+                store.index({ path: filePath, source: "session-events", attribution: currentAttribution() });
                 unlinkSync(filePath);
             }
             catch { /* best-effort per file */ }
@@ -1153,7 +1167,7 @@ __cm_main().catch(e=>{console.error(e);process.exitCode=1});${background ? '\nse
 function indexStdout(stdout, source) {
     const store = getStore();
     trackIndexed(Buffer.byteLength(stdout));
-    const indexed = store.index({ content: stdout, source });
+    const indexed = store.index({ content: stdout, source, attribution: currentAttribution() });
     return {
         content: [
             {
@@ -1173,7 +1187,7 @@ function intentSearch(stdout, intent, source, maxResults = 5) {
     const totalBytes = Buffer.byteLength(stdout);
     // Index into the PERSISTENT store so user can ctx_search() later
     const persistent = getStore();
-    const indexed = persistent.indexPlainText(stdout, source);
+    const indexed = persistent.indexPlainText(stdout, source, undefined, currentAttribution());
     // Search the persistent store directly (porter → trigram → fuzzy)
     let results = persistent.searchWithFallback(intent, maxResults, source);
     // Extract distinctive terms as vocabulary hints for the LLM
@@ -1407,7 +1421,7 @@ server.registerTool("ctx_index", {
             catch { /* ignore — file read errors handled by store */ }
         }
         const store = getStore();
-        const result = store.index({ content, path: resolvedPath, source: source ?? resolvedPath });
+        const result = store.index({ content, path: resolvedPath, source: source ?? resolvedPath, attribution: currentAttribution() });
         return trackResponse("ctx_index", {
             content: [
                 {
@@ -2145,15 +2159,16 @@ function indexFetched(f) {
     // `source` label do not overwrite each other (commit 1f1243e). ctx_search()
     // still finds both via LIKE-mode source filter on the `source` substring.
     const storageLabel = composeFetchCacheKey(f.source, f.url);
+    const attribution = currentAttribution();
     let indexed;
     if (f.header === "__CM_CT__:json") {
-        indexed = store.indexJSON(f.markdown, storageLabel);
+        indexed = store.indexJSON(f.markdown, storageLabel, undefined, attribution);
     }
     else if (f.header === "__CM_CT__:text") {
-        indexed = store.indexPlainText(f.markdown, storageLabel);
+        indexed = store.indexPlainText(f.markdown, storageLabel, undefined, attribution);
     }
     else {
-        indexed = store.index({ content: f.markdown, source: storageLabel });
+        indexed = store.index({ content: f.markdown, source: storageLabel, attribution });
     }
     // Track AFTER the FTS5 write succeeds — failed indexes shouldn't inflate the counter.
     trackIndexed(Buffer.byteLength(f.markdown));
@@ -2460,7 +2475,7 @@ server.registerTool("ctx_batch_execute", {
             .map((c) => c.label)
             .join(",")
             .slice(0, 80)}`;
-        const indexed = store.index({ content: stdout, source });
+        const indexed = store.index({ content: stdout, source, attribution: currentAttribution() });
         // Build section inventory — direct query by source_id (no FTS5 MATCH needed)
         const allSections = store.getChunksBySource(indexed.sourceId);
         const inventory = ["## Indexed Sections", ""];
@@ -2865,7 +2880,12 @@ server.registerTool("ctx_upgrade", {
 // files (events.md, FTS5 store file, stats file) are preserved.
 // Passing both sessionId AND scope:"project" is ambiguous (does the
 // caller want a per-session wipe or a project-wide one?) and is
-// rejected by the schema's refine().
+// rejected by an explicit check in the handler body — NOT a schema-level
+// .refine(). MCP SDK's normalizeObjectSchema() reads `.shape` to project
+// inputSchema → JSON Schema for tools/list; a ZodEffects (refine wrapper)
+// has no `.shape`, so the SDK silently emits `properties: {}`, and Claude
+// Code's strict-input-validation gate then rejects EVERY call to this
+// tool with "input_schema does not support fields". Issue #563.
 server.registerTool("ctx_purge", {
     title: "Purge Knowledge Base",
     description: "DESTRUCTIVE — permanently delete indexed content. CANNOT be undone.\n\n" +
@@ -2886,6 +2906,9 @@ server.registerTool("ctx_purge", {
         "Use sessionId when the user asks to clear a specific conversation's data.\n" +
         "Use scope:'project' ONLY when the user explicitly asks to reset everything.\n" +
         "NEVER call with bare {confirm:true} — always specify the scope.",
+    // NOTE: schema MUST be a plain z.object — no .refine()/.transform()/
+    // .superRefine() wrapper. See block comment above & issue #563. The
+    // cross-field ambiguity check lives in the handler body below.
     inputSchema: z.object({
         confirm: z.boolean().describe("MUST be true. Destructive operation; false returns 'purge cancelled'."),
         sessionId: z.string().optional().describe("UUID of a single session. Pairs with confirm:true to wipe only that " +
@@ -2894,12 +2917,22 @@ server.registerTool("ctx_purge", {
         scope: z.enum(["session", "project"]).optional().describe("Explicit scope selector. 'session' REQUIRES sessionId. 'project' wipes " +
             "the entire project (FTS5 + every session + stats). Omit only for the " +
             "deprecated bare-{confirm:true} back-compat path."),
-    }).refine((v) => !(v.sessionId && v.scope === "project"), {
-        message: "Ambiguous purge: sessionId implies scope:'session', cannot combine with scope:'project'. " +
-            "Use scope:'project' WITHOUT sessionId for the legacy whole-project wipe.",
-        path: ["scope"],
     }),
 }, async ({ confirm, sessionId, scope }) => {
+    // Cross-field ambiguity check — formerly a schema .refine(), moved
+    // into the handler so the inputSchema stays a plain ZodObject and
+    // the MCP SDK can serialize `.shape` into JSON Schema (issue #563).
+    // Same human-readable message as the original refine() preserved.
+    if (sessionId && scope === "project") {
+        return trackResponse("ctx_purge", {
+            content: [{
+                    type: "text",
+                    text: "Ambiguous purge: sessionId implies scope:'session', cannot combine with scope:'project'. " +
+                        "Use scope:'project' WITHOUT sessionId for the legacy whole-project wipe.",
+                }],
+            isError: true,
+        });
+    }
     if (!confirm) {
         return trackResponse("ctx_purge", {
             content: [{
@@ -3365,6 +3398,20 @@ server.registerTool("ctx_insight", {
 // Server startup
 // ─────────────────────────────────────────────────────────
 async function main() {
+    // Startup sibling sweep (#565). OpenCode/KiloCode spawn one MCP child
+    // per session/subagent and never reap them. When a new MCP child boots
+    // under a host that already has N stale idle siblings (sharing OUR
+    // ppid), reclaim them before opening our own DB / sentinel / stdio.
+    // Best effort — never blocks startup.
+    try {
+        const { startupSiblingSweep } = await import("./util/sibling-mcp.js");
+        const report = await startupSiblingSweep();
+        if (report.totalKilled > 0) {
+            console.error(`Reaped ${report.totalKilled} stale sibling MCP server(s) ` +
+                `(SIGTERM: ${report.terminatedBySigterm}, SIGKILL: ${report.terminatedBySigkill})`);
+        }
+    }
+    catch { /* best effort */ }
     // Clean up stale DB files from previous sessions
     const cleaned = cleanupStaleDBs();
     if (cleaned > 0) {
@@ -3414,7 +3461,38 @@ async function main() {
     process.on("SIGINT", () => { gracefulShutdown(); });
     process.on("SIGTERM", () => { gracefulShutdown(); });
     // Lifecycle guard: detect parent death + stdin close to prevent orphaned processes (#103)
-    startLifecycleGuard({ onShutdown: () => gracefulShutdown() });
+    // Also: idle self-shutdown (#565) — OpenCode/KiloCode open one MCP child per
+    // session AND per subagent and never tear them down for the host's lifetime,
+    // accumulating one stdio child per session (observed: 26 children / 1.6 GB
+    // RSS under a single `opencode serve` parent). Idle timeout reaps quiescent
+    // servers; live ones bump `recordActivity()` on every JSON-RPC request via
+    // the MCP SDK's `_onrequest` hook wrapped below.
+    const lifecycle = startLifecycleGuard({ onShutdown: () => gracefulShutdown() });
+    // Wrap the SDK's internal request entry so every JSON-RPC `tools/call`,
+    // `tools/list`, etc. resets the idle timer. We intercept at this layer
+    // rather than per-tool because (a) it covers ALL requests, including
+    // listTools / listPrompts / listResources / ping, and (b) it survives
+    // future tool additions without each handler needing to remember to opt in.
+    //
+    // The cast is necessary because `_onrequest` is intentionally undocumented
+    // in the SDK's public types. Best effort — if the field shape changes in
+    // a future SDK release the lifecycle still works, idle reset just degrades
+    // to "untriggered" which simply means the server lives until the next
+    // ppid/signal-based exit path fires. We never block the request path.
+    try {
+        const inner = server.server;
+        const origOnRequest = inner._onrequest;
+        if (typeof origOnRequest === "function") {
+            inner._onrequest = function (...args) {
+                try {
+                    lifecycle.recordActivity();
+                }
+                catch { /* never break request path */ }
+                return origOnRequest.apply(this, args);
+            };
+        }
+    }
+    catch { /* best effort — see comment above */ }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Write MCP readiness sentinel (#230)

package/build/session/extract.d.ts

@@ -15,6 +15,13 @@ export interface SessionEvent {
     data: string;
     /** 1=critical (rules, files, tasks) … 5=low */
     priority: number;
+    /**
+     * Optional — bytes context-mode prevented from entering the model context
+     * window for this event. Currently populated by external_ref when a
+     * ctx_fetch_and_index tool_response carries the
+     * `Fetched and indexed N sections (XKB)` preamble.
+     */
+    bytes_avoided?: number;
 }
 export interface ToolCall {
     toolName: string;