context-mode 1.0.127 → 1.0.129

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.127",
+  "version": "1.0.129",
   "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/adapters/detect.d.ts

@@ -34,12 +34,20 @@ export declare function __seedClaudeCodePluginCacheMissForTests(): void;
  *     `resolveProjectDir({ strictPlatform })` to form the candidate list,
  *     and by Pi's bridge to scrub foreign workspace vars on child spawn.
  *   - `identification`: env var only signals which host is running; carries
- *     no project path. NEVER scrubbed (some are load-bearing, e.g.
- *     CLAUDE_PLUGIN_ROOT for hook integrations).
+ *     no project path. PRESERVED in normal operation (some are load-bearing
+ *     for hook integrations on the host that owns them, e.g. CLAUDE_PLUGIN_ROOT
+ *     for Claude Code's hook context).
  *
  * Issue #545 — algorithmic env-leak fix. The split allows resolveProjectDir
  * to derive ALLOW (own workspace vars) and BAN (other platforms' workspace
  * vars) sets from a single registry, satisfying MUST-3 (15 adapters equal).
+ *
+ * Issue #561 — FOREIGN identification vars MUST be scrubbed when spawning a
+ * child under a different host (e.g. Pi spawning context-mode child must
+ * scrub Claude Code identification vars CLAUDE_CODE_ENTRYPOINT /
+ * CLAUDE_PLUGIN_ROOT to prevent detectPlatform() in the child from
+ * misidentifying the host as claude-code and writing Pi's data into
+ * ~/.claude/context-mode/). See `foreignIdentificationEnv()` below.
  */
 export type EnvVarRole = "workspace" | "identification";
 export interface PlatformEnvEntry {
@@ -78,6 +86,26 @@ export declare function workspaceEnvVarsFor(platform: PlatformId): string[];
  * workspace vars from spawned MCP child) and by the matrix regression test.
  */
 export declare function foreignWorkspaceEnv(platform: PlatformId): Set<string>;
+/**
+ * Issue #561 — return the union of identification env vars from ALL
+ * platforms EXCEPT the given one. Sibling of `foreignWorkspaceEnv`,
+ * filtered on `role === "identification"` instead of "workspace".
+ *
+ * Consumed by Pi's bridge env scrub: when Pi spawns the context-mode
+ * MCP child, the child inherits the host shell env including any
+ * identification vars set by a co-resident Claude Code session
+ * (CLAUDE_CODE_ENTRYPOINT / CLAUDE_PLUGIN_ROOT). Without scrubbing,
+ * `detectPlatform()` in the child falls through env priority order and
+ * resolves to claude-code first — Pi's session data then writes into
+ * `~/.claude/context-mode/` instead of Pi's own dir. Scrubbing FOREIGN
+ * identification vars (everyone else's) preserves Pi's OWN identification
+ * vars (PI_CONFIG_DIR / PI_SESSION_FILE / PI_COMPILED) so the child still
+ * detects pi correctly.
+ *
+ * Algorithmic, registry-driven — adding adapter #16 grows the scrub
+ * automatically (no edit to mcp-bridge.ts).
+ */
+export declare function foreignIdentificationEnv(platform: PlatformId): Set<string>;
 /**
  * Sync map from platform identifier → home-relative path segments where that
  * platform stores its config. Mirrors the `super([...])` argument passed by

package/build/adapters/detect.js

@@ -222,6 +222,37 @@ export function foreignWorkspaceEnv(platform) {
     }
     return ban;
 }
+/**
+ * Issue #561 — return the union of identification env vars from ALL
+ * platforms EXCEPT the given one. Sibling of `foreignWorkspaceEnv`,
+ * filtered on `role === "identification"` instead of "workspace".
+ *
+ * Consumed by Pi's bridge env scrub: when Pi spawns the context-mode
+ * MCP child, the child inherits the host shell env including any
+ * identification vars set by a co-resident Claude Code session
+ * (CLAUDE_CODE_ENTRYPOINT / CLAUDE_PLUGIN_ROOT). Without scrubbing,
+ * `detectPlatform()` in the child falls through env priority order and
+ * resolves to claude-code first — Pi's session data then writes into
+ * `~/.claude/context-mode/` instead of Pi's own dir. Scrubbing FOREIGN
+ * identification vars (everyone else's) preserves Pi's OWN identification
+ * vars (PI_CONFIG_DIR / PI_SESSION_FILE / PI_COMPILED) so the child still
+ * detects pi correctly.
+ *
+ * Algorithmic, registry-driven — adding adapter #16 grows the scrub
+ * automatically (no edit to mcp-bridge.ts).
+ */
+export function foreignIdentificationEnv(platform) {
+    const ban = new Set();
+    for (const [p, vars] of PLATFORM_ENV_VARS) {
+        if (p === platform)
+            continue;
+        for (const v of vars) {
+            if (v.role === "identification")
+                ban.add(v.name);
+        }
+    }
+    return ban;
+}
 /**
  * Sync map from platform identifier → home-relative path segments where that
  * platform stores its config. Mirrors the `super([...])` argument passed by

package/build/adapters/pi/mcp-bridge.js

@@ -22,7 +22,7 @@
  */
 import { spawn, execSync } from "node:child_process";
 import { detectRuntimes } from "../../runtime.js";
-import { foreignWorkspaceEnv } from "../detect.js";
+import { foreignWorkspaceEnv, foreignIdentificationEnv } from "../detect.js";
 // ── Fork-bomb prevention (#516) ──────────────────────────────────────
 //
 // Original bug: `spawn(process.execPath, [serverScript])` recursively
@@ -154,12 +154,27 @@ export class MCPStdioClient {
         // and Pi's sessions write into the wrong project. The ban list is
         // derived ALGORITHMICALLY from PLATFORM_ENV_VARS (every other adapter's
         // workspace-role vars), so adding adapter #16 grows the scrub
-        // automatically — no edit to this file. Identification vars
-        // (CLAUDE_PLUGIN_ROOT etc.) and the universal escape hatch
-        // (CONTEXT_MODE_PROJECT_DIR) are NEVER scrubbed.
+        // automatically — no edit to this file. Pi's own workspace vars and
+        // the universal escape hatch (CONTEXT_MODE_PROJECT_DIR) are NEVER
+        // scrubbed.
         for (const banned of foreignWorkspaceEnv("pi")) {
             delete childEnv[banned];
         }
+        // Issue #561 — scrub foreign IDENTIFICATION env vars before spawn.
+        //
+        // Foreign identification vars hijack detectPlatform() — must scrub
+        // when spawning child under a different host (#561). When Pi runs
+        // co-resident with Claude Code, the inherited shell env carries
+        // CLAUDE_CODE_ENTRYPOINT and CLAUDE_PLUGIN_ROOT; the spawned MCP
+        // child's detectPlatform() then walks PLATFORM_ENV_VARS in priority
+        // order (claude-code first), returns claude-code, and Pi's session
+        // data lands in ~/.claude/context-mode/ instead of Pi's own dir.
+        // Pi's OWN identification vars (PI_CONFIG_DIR / PI_SESSION_FILE /
+        // PI_COMPILED) are excluded from the ban set so the child still
+        // detects pi correctly.
+        for (const banned of foreignIdentificationEnv("pi")) {
+            delete childEnv[banned];
+        }
         this._spawnEnv = childEnv;
         this.child = spawn(runtime, [this.serverScript], {
             // Pipe stderr (#472 round-3): swallowing it via "ignore" hides

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,15 @@ export function applyWALPragmas(db) {
         db.pragma("mmap_size = 268435456");
     }
     catch { /* unsupported runtime */ }
+    // NOTE: `locking_mode = EXCLUSIVE` is intentionally NOT applied here.
+    // Multi-writer scenarios are valid: `ContentStore` (FTS5 shared
+    // knowledge base) is opened concurrently from multiple sessions on the
+    // SAME db file by design — applying EXCLUSIVE here would deadlock the
+    // second instance and break documented `withRetry`-based BUSY handling.
+    // Single-writer enforcement (lockfile + EXCLUSIVE) lives in
+    // `SQLiteBase` ctor which is opted into by per-project DBs (SessionDB).
+    // Different DB paths from different worktrees/sessions ARE concurrent
+    // by design — the lockfile is per-dbPath, not per-process.
 }
 // ─────────────────────────────────────────────────────────
 // DB file helpers
@@ -450,14 +465,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,11 +497,42 @@ 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 });
+        // v1.0.129 — single source of truth for skip decision. Both lockfile
+        // (above) and EXCLUSIVE pragma (below) MUST share the same skip-gate:
+        // tests open SessionDB twice on the same tmpdir path to exercise
+        // multi-writer scenarios; if EXCLUSIVE fires here when lockfile didn't,
+        // the second open hits SQLITE_BUSY on its FIRST pragma call inside
+        // applyWALPragmas — caused 82 test failures during v1.0.128 verification.
+        const skipExclusive = dbPath.startsWith(tmpdir());
         cleanOrphanedWALFiles(dbPath);
         let db;
         try {
             db = new Database(dbPath, { timeout: 30000 });
             applyWALPragmas(db);
+            // v1.0.128 — Issue #560 SECONDARY defense for SQLiteBase callers (single-writer
+            // DBs like SessionDB). The .lock file (acquireDbLock above) 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 —
+            // backends that don't expose locking_mode (or pragma at all) still get the
+            // lockfile floor. NOTE: NOT applied in `applyWALPragmas` because multi-writer
+            // callers (ContentStore — FTS5 shared knowledge base across sessions) rely
+            // on the default SHARED locking mode + withRetry to handle SQLITE_BUSY.
+            // Skip on tmpdir paths to match acquireDbLock's skip-gate.
+            if (!skipExclusive) {
+                try {
+                    db.pragma("locking_mode = EXCLUSIVE");
+                }
+                catch { /* unsupported runtime */ }
+            }
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -484,17 +542,27 @@ export class SQLiteBase {
                 try {
                     db = new Database(dbPath, { timeout: 30000 });
                     applyWALPragmas(db);
+                    if (!skipExclusive) {
+                        try {
+                            db.pragma("locking_mode = EXCLUSIVE");
+                        }
+                        catch { /* unsupported runtime */ }
+                    }
                 }
                 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 +578,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 +594,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/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.
+    }
+}