context-mode 1.0.126 → 1.0.128

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.126"
+    "version": "1.0.128"
   },
   "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.126",
+      "version": "1.0.128",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.126",
+  "version": "1.0.128",
   "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.126",
+  "version": "1.0.128",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.126",
+  "version": "1.0.128",
   "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/build/cli.js

@@ -22,6 +22,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { detectRuntimes, getRuntimeSummary, hasBunRuntime, getAvailableLanguages, } from "./runtime.js";
 import { getHookScriptPaths } from "./util/hook-config.js";
 import { resolveClaudeConfigDir } from "./util/claude-config.js";
+// v1.0.128 — Issue #559 sibling MCP kill helpers (see PR-559-560-FIX-DESIGN.md).
+import { discoverSiblingMcpPids, killSiblingMcpServers } from "./util/sibling-mcp.js";
 // v1.0.119 — Issue #523 Layer 5 heal: post-bump assertion on .claude-plugin/plugin.json
 // mcpServers args. Single source of truth shared with start.mjs HEAL block + postinstall.
 // @ts-expect-error — JS module, no TS declarations
@@ -703,6 +705,35 @@ async function upgrade(opts) {
         }
         else {
             p.log.info(`Update available: ${color.yellow("v" + localVersion)} → ${color.green("v" + newVersion)}`);
+            // v1.0.128 — Issue #559: terminate sibling MCP servers BEFORE installing
+            // new files. Historically /ctx-upgrade rsynced new code over the old
+            // tree but never signalled the running MCP server, so the previous
+            // version stayed alive holding stdio + DB handles. Across enough
+            // upgrades users observed 5+ context-mode start.mjs processes pinned
+            // to RAM. Discovery + kill must happen before npm install to avoid
+            // racing against the EXCLUSIVE lock the new server claims on first
+            // ctx_search (see #560 fix). Wrapped in try/catch so a missing pgrep
+            // (stripped Linux distro) or unavailable PowerShell (weird Windows)
+            // can never block the upgrade itself.
+            try {
+                const siblingPids = discoverSiblingMcpPids({
+                    ownPid: process.pid,
+                    ownPpid: process.ppid,
+                });
+                if (siblingPids.length > 0) {
+                    const killReport = await killSiblingMcpServers({ pids: siblingPids });
+                    if (killReport.totalKilled > 0) {
+                        // Concise summary only — no PIDs in the user-facing log to keep
+                        // the line readable. Plural-aware so "1 sibling MCP server" reads
+                        // naturally alongside "3 sibling MCP servers".
+                        const noun = killReport.totalKilled === 1
+                            ? "sibling MCP server"
+                            : "sibling MCP servers";
+                        p.log.info(color.dim(`Stopped ${killReport.totalKilled} ${noun} (SIGTERM: ${killReport.terminatedBySigterm}, SIGKILL: ${killReport.terminatedBySigkill})`));
+                    }
+                }
+            }
+            catch { /* never block upgrade on discovery/kill failure */ }
             // Step 2: Install dependencies + build
             s.start("Installing dependencies & building");
             npmExecFile(["install", "--no-audit", "--no-fund"], {

package/build/db-base.js

@@ -9,6 +9,12 @@ import { createRequire } from "node:module";
 import { existsSync, unlinkSync, renameSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+// v1.0.128 — Issue #560 single-writer enforcement.
+// Lockfile is the PRIMARY defense (clean UX with conflicting PID),
+// `locking_mode = EXCLUSIVE` (applied in applyWALPragmas below) is the
+// SECONDARY defense for the narrow race window between lockfile claim
+// and the actual `new Database(...)` open. Both skip-gate on tmpdir paths.
+import { acquireDbLock, releaseDbLock } from "./util/db-lock.js";
 // ─────────────────────────────────────────────────────────
 // bun:sqlite adapter (#45)
 // ─────────────────────────────────────────────────────────
@@ -310,6 +316,18 @@ export function applyWALPragmas(db) {
         db.pragma("mmap_size = 268435456");
     }
     catch { /* unsupported runtime */ }
+    // v1.0.128 — Issue #560 SECONDARY defense for single-writer enforcement.
+    // The .lock file (acquireDbLock in SQLiteBase ctor) is PRIMARY — it
+    // surfaces the conflicting PID with a clear UX message. EXCLUSIVE locking
+    // closes the narrow race window between lockfile claim + the actual
+    // `new Database(...)` open: a parallel process passing the lockfile
+    // check would still get SQLITE_BUSY from this pragma. Wrapped in
+    // try/catch identical to mmap_size — backends that don't expose
+    // locking_mode (or pragma at all) still get the lockfile floor.
+    try {
+        db.pragma("locking_mode = EXCLUSIVE");
+    }
+    catch { /* unsupported runtime */ }
 }
 // ─────────────────────────────────────────────────────────
 // DB file helpers
@@ -450,14 +468,26 @@ export function renameCorruptDB(dbPath) {
  * re-imports within the same fork process (ESM isolate mode clears
  * module-level state but globalThis persists).
  */
-const _kLiveDBs = Symbol.for("__context_mode_live_dbs__");
+// v1.0.128 — symbol name versioned because the value type changed from
+// Set<DatabaseInstance> to Map<DatabaseInstance, string> (issue #560).
+// A persistent global slot from a pre-v128 module would deserialize as
+// the wrong shape and crash the exit hook iteration.
+const _kLiveDBs = Symbol.for("__context_mode_live_dbs_v2__");
+// v1.0.128 — issue #560: pair each DatabaseInstance with the dbPath that
+// owns its lockfile. The exit hook needs both — closeDB(db) handles the
+// WAL checkpoint, releaseDbLock(dbPath) drops the .lock file. We use a
+// Map keyed by DatabaseInstance to keep API call sites unchanged.
 const _liveDBs = (() => {
     const g = globalThis;
     if (!g[_kLiveDBs]) {
-        g[_kLiveDBs] = new Set();
+        g[_kLiveDBs] = new Map();
         process.on("exit", () => {
-            for (const db of g[_kLiveDBs]) {
+            for (const [db, dbPath] of g[_kLiveDBs]) {
                 closeDB(db);
+                // Release lock AFTER close so the WAL checkpoint inside closeDB
+                // runs while we still own the writer slot (no second-opener can
+                // race in mid-checkpoint).
+                releaseDbLock({ dbPath });
             }
             g[_kLiveDBs].clear();
         });
@@ -470,6 +500,13 @@ export class SQLiteBase {
     constructor(dbPath) {
         const Database = loadDatabase();
         this.#dbPath = dbPath;
+        // v1.0.128 — Issue #560 PRIMARY single-writer guard. Must claim
+        // BEFORE `new Database(...)` so a contending opener gets the clean
+        // DatabaseLockedError UX (PID + verbatim message) instead of the
+        // SQLITE_BUSY surfaced by EXCLUSIVE locking. Skip-gate via
+        // tmpdir-prefix check inside the helper — defaultDBPath() output
+        // (per-process tmp DBs) does not contend, so it never claims a lock.
+        acquireDbLock({ dbPath });
         cleanOrphanedWALFiles(dbPath);
         let db;
         try {
@@ -486,15 +523,19 @@ export class SQLiteBase {
                     applyWALPragmas(db);
                 }
                 catch (retryErr) {
+                    // Free the lock before bubbling — caller can never reach
+                    // close()/cleanup() if the ctor throws.
+                    releaseDbLock({ dbPath });
                     throw new Error(`Failed to create fresh DB after renaming corrupt file: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
                 }
             }
             else {
+                releaseDbLock({ dbPath });
                 throw err;
             }
         }
         this.#db = db;
-        _liveDBs.add(this.#db);
+        _liveDBs.set(this.#db, dbPath);
         this.initSchema();
         this.prepareStatements();
     }
@@ -510,6 +551,10 @@ export class SQLiteBase {
     close() {
         _liveDBs.delete(this.#db);
         closeDB(this.#db);
+        // v1.0.128 — Issue #560: drop the .lock file AFTER closeDB so the
+        // WAL checkpoint inside closeDB completes while we still own the
+        // writer slot. releaseDbLock is no-op for tmpdir paths (skip-gate).
+        releaseDbLock({ dbPath: this.#dbPath });
     }
     withRetry(fn) {
         return withRetry(fn);
@@ -522,5 +567,9 @@ export class SQLiteBase {
         _liveDBs.delete(this.#db);
         closeDB(this.#db);
         deleteDBFiles(this.#dbPath);
+        // v1.0.128 — Issue #560: also drop the lockfile during cleanup. Per-
+        // process tmp DBs (defaultDBPath()) skip-gate inside the helper, so
+        // this is only a side-effect for shared on-disk content stores.
+        releaseDbLock({ dbPath: this.#dbPath });
     }
 }

package/build/server.js

@@ -198,6 +198,12 @@ function getProjectDir() {
     // path on detected platform so non-Claude hosts skip the heuristic and
     // fall through to PWD/cwd cleanly.
     //
+    // The Claude heuristic must also be fresh. Hosts such as Pi can be
+    // misdetected as Claude Code solely because ~/.claude exists; without a
+    // freshness guard an old Claude transcript can globally hijack ctx shell cwd
+    // after reboot. Active Claude sessions update their transcript as the user
+    // interacts, so stale transcripts should fall through to PWD/cwd.
+    //
     // Issue #545 (v1.0.124): pass strictPlatform for ALL adapters so the
     // env-var cascade is built ALGORITHMICALLY from the platform's own
     // workspace vars + universal escape hatch — foreign workspace vars (e.g.
@@ -220,6 +226,7 @@ function getProjectDir() {
         cwd: process.cwd(),
         pwd: process.env.PWD,
         transcriptsRoot,
+        transcriptMaxAgeMs: 5 * 60 * 1000,
         strictPlatform,
     });
 }

package/build/util/db-lock.d.ts

@@ -0,0 +1,65 @@
+/**
+ * db-lock — Per-DB lockfile primitive for single-writer enforcement (#560).
+ *
+ * Issue #560: multiple context-mode MCP servers writing the same on-disk
+ * SQLite content store unbounded the WAL — readers held shared locks
+ * indefinitely so `wal_checkpoint(TRUNCATE)` never fired, and the only
+ * existing truncation path is `closeDB`'s checkpoint on graceful exit
+ * (which #559's zombie servers never reach). Result: 238MB+ WAL files
+ * and ctx_search hangs.
+ *
+ * This module provides a tiny atomic-write primitive sitting in front of
+ * `new Database(...)`. The first opener writes its PID into
+ * `<dbPath>.lock` via O_EXCL (`flag: 'wx'`). Subsequent openers either:
+ *
+ *   - find the lockfile + see the PID is alive → throw
+ *     DatabaseLockedError with the reporter's verbatim message;
+ *   - find the lockfile + see the PID is dead → claim it, with a re-read
+ *     check to resolve a same-instant race between two stale-claimers.
+ *
+ * The lockfile is the PRIMARY single-writer defense. The SQLiteBase ctor
+ * also applies `locking_mode = EXCLUSIVE` as a SECONDARY defense
+ * (belt-and-braces) — the lockfile owns the user-facing UX, EXCLUSIVE
+ * catches the narrow race window between the lockfile check and the
+ * actual `Database(...)` open.
+ *
+ * Per-process tmp DBs (those under `os.tmpdir()`) skip the lockfile
+ * entirely — those are the existing `defaultDBPath()` shape and embed
+ * `process.pid` already, so cross-instance contention is impossible.
+ *
+ * `isProcessAlive` is COPIED from `store.ts:187` — not imported — to
+ * keep `db-base.ts` (which imports this module) free of any dependency
+ * on `store.ts` (which itself imports from `db-base.ts`). See
+ * PR-559-560-FIX-DESIGN.md regression risks #4.
+ */
+/** User-facing failure used by SQLiteBase to surface the contention. */
+export declare class DatabaseLockedError extends Error {
+    readonly pid: number;
+    readonly dbPath: string;
+    constructor(pid: number, dbPath: string);
+}
+export interface AcquireOptions {
+    dbPath: string;
+}
+export interface AcquireResult {
+    /** True when the lockfile was skipped because dbPath is under tmpdir. */
+    skipped: boolean;
+}
+/**
+ * Atomically claim the lockfile for `dbPath`. Throws `DatabaseLockedError`
+ * if another live process holds it. Silently claims stale lockfiles whose
+ * owning PID is dead.
+ */
+export declare function acquireDbLock(opts: AcquireOptions): AcquireResult;
+export interface ReleaseOptions {
+    dbPath: string;
+}
+/**
+ * Drop the lockfile for `dbPath`. Swallows all errors so callers can
+ * always invoke this in a finally / cleanup path without try/catch —
+ * mirrors the shape of `db-base.ts closeDB`.
+ *
+ * Skipped (no-op) when `dbPath` is under tmpdir — symmetric with
+ * `acquireDbLock`'s skip-gate.
+ */
+export declare function releaseDbLock(opts: ReleaseOptions): void;

package/build/util/db-lock.js

@@ -0,0 +1,166 @@
+/**
+ * db-lock — Per-DB lockfile primitive for single-writer enforcement (#560).
+ *
+ * Issue #560: multiple context-mode MCP servers writing the same on-disk
+ * SQLite content store unbounded the WAL — readers held shared locks
+ * indefinitely so `wal_checkpoint(TRUNCATE)` never fired, and the only
+ * existing truncation path is `closeDB`'s checkpoint on graceful exit
+ * (which #559's zombie servers never reach). Result: 238MB+ WAL files
+ * and ctx_search hangs.
+ *
+ * This module provides a tiny atomic-write primitive sitting in front of
+ * `new Database(...)`. The first opener writes its PID into
+ * `<dbPath>.lock` via O_EXCL (`flag: 'wx'`). Subsequent openers either:
+ *
+ *   - find the lockfile + see the PID is alive → throw
+ *     DatabaseLockedError with the reporter's verbatim message;
+ *   - find the lockfile + see the PID is dead → claim it, with a re-read
+ *     check to resolve a same-instant race between two stale-claimers.
+ *
+ * The lockfile is the PRIMARY single-writer defense. The SQLiteBase ctor
+ * also applies `locking_mode = EXCLUSIVE` as a SECONDARY defense
+ * (belt-and-braces) — the lockfile owns the user-facing UX, EXCLUSIVE
+ * catches the narrow race window between the lockfile check and the
+ * actual `Database(...)` open.
+ *
+ * Per-process tmp DBs (those under `os.tmpdir()`) skip the lockfile
+ * entirely — those are the existing `defaultDBPath()` shape and embed
+ * `process.pid` already, so cross-instance contention is impossible.
+ *
+ * `isProcessAlive` is COPIED from `store.ts:187` — not imported — to
+ * keep `db-base.ts` (which imports this module) free of any dependency
+ * on `store.ts` (which itself imports from `db-base.ts`). See
+ * PR-559-560-FIX-DESIGN.md regression risks #4.
+ */
+import { writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+/** User-facing failure used by SQLiteBase to surface the contention. */
+export class DatabaseLockedError extends Error {
+    pid;
+    dbPath;
+    constructor(pid, dbPath) {
+        super(`Another context-mode server is already running (PID: ${pid}). ` +
+            `Stop it before starting a new instance.`);
+        this.name = "DatabaseLockedError";
+        this.pid = pid;
+        this.dbPath = dbPath;
+    }
+}
+/**
+ * Liveness probe — a 6-line copy of `store.ts:187 isProcessAlive`.
+ * Sends signal 0 (no-op kill) which only verifies that the kernel
+ * recognizes the PID + that the caller has permission to signal it.
+ *
+ * Copied (not imported) so this module stays leaf-level and `db-base.ts`
+ * does not pick up a transitive dependency on `store.ts` — `store.ts`
+ * already imports from `db-base.ts`, so the reverse would create a
+ * circular dep that breaks under bun:sqlite's lazy load path.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function lockPathFor(dbPath) {
+    return `${dbPath}.lock`;
+}
+/**
+ * tmpdir skip-gate — per-process DBs (e.g. defaultDBPath() output) embed
+ * `process.pid` so cross-instance contention is impossible by
+ * construction. We never want to install a lockfile on the test runner's
+ * tmp scratch path either.
+ */
+function isUnderTmpdir(dbPath) {
+    // Trailing-slash normalize — tmpdir() may or may not include it on the
+    // current platform, and dbPath may be exactly tmpdir() when callers
+    // join() with no separator (rare but cheap to guard).
+    const tmp = tmpdir();
+    return dbPath === tmp || dbPath.startsWith(tmp + "/") || dbPath.startsWith(tmp + "\\");
+}
+/**
+ * Atomically claim the lockfile for `dbPath`. Throws `DatabaseLockedError`
+ * if another live process holds it. Silently claims stale lockfiles whose
+ * owning PID is dead.
+ */
+export function acquireDbLock(opts) {
+    const { dbPath } = opts;
+    if (isUnderTmpdir(dbPath))
+        return { skipped: true };
+    const lockPath = lockPathFor(dbPath);
+    const ownPid = String(process.pid);
+    // Fast path: O_EXCL atomic create — succeeds iff the lockfile did not
+    // exist. This is the single race-free moment that grants ownership.
+    try {
+        writeFileSync(lockPath, ownPid, { flag: "wx" });
+        return { skipped: false };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== "EEXIST")
+            throw err;
+        // Fall through to liveness check.
+    }
+    // Slow path: lockfile exists. Read the PID, probe liveness.
+    let existingPidStr;
+    try {
+        existingPidStr = readFileSync(lockPath, "utf-8").trim();
+    }
+    catch {
+        // Lockfile vanished between EEXIST and read — race won by another
+        // claimer that already finished cleanup. Retry once via the fast
+        // path; if even that fails, surface as locked (best-effort).
+        try {
+            writeFileSync(lockPath, ownPid, { flag: "wx" });
+            return { skipped: false };
+        }
+        catch {
+            throw new DatabaseLockedError(0, dbPath);
+        }
+    }
+    const existingPid = Number.parseInt(existingPidStr, 10);
+    if (Number.isFinite(existingPid) && existingPid > 0 && isProcessAlive(existingPid)) {
+        throw new DatabaseLockedError(existingPid, dbPath);
+    }
+    // Stale lockfile — owning PID is dead (or unparseable). Claim it.
+    // We do NOT use { flag: 'wx' } here because we deliberately want to
+    // overwrite the dead-PID record. Then re-read to confirm we won the
+    // race against any other process also seeing the same stale lock.
+    writeFileSync(lockPath, ownPid, { flag: "w" });
+    let writtenPid;
+    try {
+        writtenPid = Number.parseInt(readFileSync(lockPath, "utf-8").trim(), 10);
+    }
+    catch {
+        // Vanished again — extremely unlikely. Surface as locked rather than
+        // proceeding with no guarantee.
+        throw new DatabaseLockedError(0, dbPath);
+    }
+    if (writtenPid !== process.pid) {
+        // Lost the stale-claim race to another concurrent claimer.
+        throw new DatabaseLockedError(writtenPid, dbPath);
+    }
+    return { skipped: false };
+}
+/**
+ * Drop the lockfile for `dbPath`. Swallows all errors so callers can
+ * always invoke this in a finally / cleanup path without try/catch —
+ * mirrors the shape of `db-base.ts closeDB`.
+ *
+ * Skipped (no-op) when `dbPath` is under tmpdir — symmetric with
+ * `acquireDbLock`'s skip-gate.
+ */
+export function releaseDbLock(opts) {
+    const { dbPath } = opts;
+    if (isUnderTmpdir(dbPath))
+        return;
+    try {
+        unlinkSync(lockPathFor(dbPath));
+    }
+    catch {
+        // Already gone, permission denied, etc. — best-effort.
+    }
+}

package/build/util/project-dir.d.ts

@@ -50,6 +50,15 @@ export declare function isPluginInstallPath(p: string): boolean;
  */
 export declare function resolveProjectDirFromTranscript(opts: {
     projectsRoot: string;
+    /**
+     * Optional freshness guard. Claude Code updates the active transcript while
+     * the session is being used; stale transcripts from previous days must not
+     * become a global project-dir signal for other hosts that merely have
+     * ~/.claude on disk.
+     */
+    maxAgeMs?: number;
+    /** Test seam for maxAgeMs. Defaults to Date.now(). */
+    nowMs?: number;
 }): string | undefined;
 /**
  * Pure project-dir resolver. Mirror of the env-var chain inside
@@ -77,6 +86,10 @@ export declare function resolveProjectDir(opts: {
     pwd: string | undefined;
     /** Optional override; production code passes `~/.claude/projects`. */
     transcriptsRoot?: string;
+    /** Optional freshness guard for Claude Code transcript project recovery. */
+    transcriptMaxAgeMs?: number;
+    /** Test seam for transcriptMaxAgeMs. Defaults to Date.now(). */
+    nowMs?: number;
     /**
      * Issue #545 — opt-in tightening. When set, the candidate list is built
      * algorithmically from `workspaceEnvVarsFor(strictPlatform)` plus the

package/build/util/project-dir.js

@@ -124,6 +124,11 @@ export function resolveProjectDirFromTranscript(opts) {
     }
     if (!bestPath)
         return undefined;
+    if (typeof opts.maxAgeMs === "number") {
+        const nowMs = opts.nowMs ?? Date.now();
+        if (nowMs - bestMtime > opts.maxAgeMs)
+            return undefined;
+    }
     // Read first ~10 lines until we find a cwd field. The jsonl is
     // append-only and can be huge (60+ MB on long sessions) — never load it
     // into memory; stream a small head buffer.
@@ -172,7 +177,7 @@ export function resolveProjectDirFromTranscript(opts) {
  *      operation of project-independent tools (sandbox execute, fetch).
  */
 export function resolveProjectDir(opts) {
-    const { env, cwd, pwd, transcriptsRoot, strictPlatform } = opts;
+    const { env, cwd, pwd, transcriptsRoot, transcriptMaxAgeMs, nowMs, strictPlatform } = opts;
     // Build candidate list. Strict path: own workspace vars + universal escape
     // hatch — NO foreign workspace vars, in any order, can win. Non-strict
     // path: frozen legacy literal order for backwards compatibility.
@@ -185,7 +190,11 @@ export function resolveProjectDir(opts) {
             return v;
     }
     if (transcriptsRoot) {
-        const fromTranscript = resolveProjectDirFromTranscript({ projectsRoot: transcriptsRoot });
+        const fromTranscript = resolveProjectDirFromTranscript({
+            projectsRoot: transcriptsRoot,
+            maxAgeMs: transcriptMaxAgeMs,
+            nowMs,
+        });
         if (fromTranscript && !isPluginInstallPath(fromTranscript))
             return fromTranscript;
     }

package/build/util/sibling-mcp.d.ts

@@ -0,0 +1,79 @@
+/**
+ * sibling-mcp — discover & terminate previous-version MCP servers.
+ *
+ * Issue #559: `/ctx-upgrade` historically left the running MCP server
+ * alive after copying new files in-place + updating npm global. The next
+ * Claude Code launch spawned a fresh process from the new version, but
+ * the old one kept its open stdio + DB handles. Across enough upgrades
+ * users observed 5+ context-mode `start.mjs` processes pinned to RAM.
+ *
+ * This module provides two pure helpers:
+ *
+ *   1. `discoverSiblingMcpPids({ ownPid, ownPpid, platform, runCommand })`
+ *      — enumerates node processes whose argv mentions the plugin
+ *      `start.mjs` path under `~/.claude/plugins/{cache,marketplaces}/`.
+ *      Excludes the caller's own pid + parent pid (Claude Code or the
+ *      shell that spawned `/ctx-upgrade`). Cross-platform: POSIX uses
+ *      `pgrep -f`, Windows uses PowerShell + Get-CimInstance.
+ *
+ *   2. `killSiblingMcpServers({ pids, ... })` — sends SIGTERM, polls
+ *      liveness, escalates to SIGKILL after `timeoutMs` (default 1500
+ *      ms) on stragglers. Returns a kill report so callers can surface
+ *      a concise summary without leaking PIDs to user-facing logs.
+ *
+ * Both helpers accept dependency-injected `runCommand`, `isAlive`, and
+ * `sendSignal` parameters so tests can exercise the full behavior tree
+ * cross-platform without spawning real processes.
+ */
+/** Inject `child_process.execFileSync` for tests. Must return stdout as utf-8. */
+export type RunCommand = (cmd: string, args: readonly string[]) => string;
+/** Inject `process.kill(pid, 0)` for tests. */
+export type IsAlive = (pid: number) => boolean;
+/** Inject `process.kill(pid, signal)` for tests. */
+export type SendSignal = (pid: number, signal: NodeJS.Signals) => void;
+export interface DiscoverOptions {
+    ownPid: number;
+    ownPpid: number;
+    /** `process.platform` injection. Defaults to live process.platform. */
+    platform?: NodeJS.Platform;
+    /** Test injection point — defaults to `child_process.execFileSync`. */
+    runCommand?: RunCommand;
+}
+export interface KillOptions {
+    pids: readonly number[];
+    /** Time to wait for SIGTERM to take effect before escalating. */
+    timeoutMs?: number;
+    /** Poll interval while waiting for SIGTERM. */
+    pollIntervalMs?: number;
+    isAlive?: IsAlive;
+    sendSignal?: SendSignal;
+}
+export interface KillReport {
+    /** PIDs that died after SIGTERM within `timeoutMs`. */
+    terminatedBySigterm: number;
+    /** PIDs that required SIGKILL escalation. */
+    terminatedBySigkill: number;
+    /** Sum of the two — used by the cli summary line. */
+    totalKilled: number;
+}
+/**
+ * Enumerate node MCP-server processes spawned from this plugin's
+ * start.mjs. Always returns an empty array on tool absence — never
+ * throws — so an upgrade is never blocked by a missing pgrep/PowerShell.
+ */
+export declare function discoverSiblingMcpPids(opts: DiscoverOptions): number[];
+/**
+ * Send SIGTERM to each PID, then poll for liveness. PIDs still alive
+ * after `timeoutMs` receive SIGKILL. Returns a per-signal report.
+ *
+ * Algorithm:
+ *   1. Fire SIGTERM at every pid (swallow ESRCH — already dead).
+ *   2. Poll every `pollIntervalMs` until either all pids are dead
+ *      OR `timeoutMs` elapses.
+ *   3. For survivors: SIGKILL (swallow ESRCH).
+ *   4. Count via "died-while-we-watched": only PIDs that were observed
+ *      alive at any point and then died are reported. PIDs that were
+ *      already dead before SIGTERM (ESRCH on first send) are not
+ *      counted — they were not ours to kill.
+ */
+export declare function killSiblingMcpServers(opts: KillOptions): Promise<KillReport>;