context-mode 1.0.142 → 1.0.144

package/build/pi-extension.js

@@ -0,0 +1,451 @@
+/**
+ * Pi coding agent extension for context-mode.
+ *
+ * Follows the OpenClaw adapter pattern: imports shared session modules,
+ * registers Pi-specific hooks. NO copy-paste of session logic.
+ * NO external npm dependencies beyond what Pi runtime provides.
+ *
+ * Entry point: `export default function(pi: ExtensionAPI) { ... }`
+ *
+ * Lifecycle: session_start, tool_call, tool_result, before_agent_start,
+ * session_before_compact, session_compact, session_shutdown.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { SessionDB } from "./session/db.js";
+import { extractEvents, extractUserEvents } from "./session/extract.js";
+import { buildResumeSnapshot } from "./session/snapshot.js";
+// ── Pi Tool Name Mapping ─────────────────────────────────
+// Pi uses lowercase; shared extractors expect PascalCase (Claude Code convention).
+const PI_TOOL_MAP = {
+    bash: "Bash",
+    read: "Read",
+    write: "Write",
+    edit: "Edit",
+    grep: "Grep",
+    find: "Glob",
+    ls: "Glob",
+};
+// ── Routing patterns ─────────────────────────────────────
+// Inline HTTP client patterns to block in bash — self-contained, no routing module needed.
+const BLOCKED_BASH_PATTERNS = [
+    /\bcurl\s/,
+    /\bwget\s/,
+    /\bfetch\s*\(/,
+    /\brequests\.get\s*\(/,
+    /\brequests\.post\s*\(/,
+    /\bhttp\.get\s*\(/,
+    /\bhttp\.request\s*\(/,
+    /\burllib\.request/,
+    /\bInvoke-WebRequest\b/,
+];
+// ── Module-level DB singleton ────────────────────────────
+let _db = null;
+let _sessionId = "";
+// Per-session gate: routing block injected at most once per session_id.
+const _routingInjected = new Set();
+// Cached routing-block string (built once per process from hooks/routing-block.mjs).
+let _routingBlock = null;
+async function getRoutingBlock(pluginRoot) {
+    if (_routingBlock !== null)
+        return _routingBlock;
+    try {
+        const routingMod = await import(pathToFileURL(join(pluginRoot, "hooks", "routing-block.mjs")).href);
+        const namingMod = await import(pathToFileURL(join(pluginRoot, "hooks", "core", "tool-naming.mjs")).href);
+        const t = namingMod.createToolNamer("pi");
+        _routingBlock = String(routingMod.createRoutingBlock(t));
+    }
+    catch {
+        _routingBlock = "";
+    }
+    return _routingBlock;
+}
+// Cached buildAutoInjection (500-token cap, prioritized).
+let _buildAutoInjection = undefined;
+async function getAutoInjection(pluginRoot) {
+    if (_buildAutoInjection !== undefined)
+        return _buildAutoInjection;
+    try {
+        const mod = await import(pathToFileURL(join(pluginRoot, "hooks", "auto-injection.mjs")).href);
+        _buildAutoInjection = mod.buildAutoInjection;
+    }
+    catch {
+        _buildAutoInjection = null;
+    }
+    return _buildAutoInjection ?? null;
+}
+// ── Helpers ──────────────────────────────────────────────
+function getSessionDir() {
+    const dir = join(homedir(), ".pi", "context-mode", "sessions");
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function getDBPath() {
+    return join(getSessionDir(), "context-mode.db");
+}
+function getOrCreateDB() {
+    if (!_db) {
+        _db = new SessionDB({ dbPath: getDBPath() });
+    }
+    return _db;
+}
+/** Derive a stable session ID from Pi's session file path (SHA256, 16 hex chars). */
+function deriveSessionId(ctx) {
+    try {
+        const sessionManager = ctx.sessionManager;
+        const sessionFile = sessionManager?.getSessionFile?.();
+        if (sessionFile && typeof sessionFile === "string") {
+            return createHash("sha256").update(sessionFile).digest("hex").slice(0, 16);
+        }
+    }
+    catch {
+        // best effort
+    }
+    return `pi-${Date.now()}`;
+}
+/** Build stats text for the /ctx-stats command. */
+function buildStatsText(db, sessionId) {
+    try {
+        const events = db.getEvents(sessionId);
+        const stats = db.getSessionStats(sessionId);
+        const lines = [
+            "## context-mode stats (Pi)",
+            "",
+            `- Session: \`${sessionId.slice(0, 8)}...\``,
+            `- Events captured: ${events.length}`,
+            `- Compactions: ${stats?.compact_count ?? 0}`,
+        ];
+        // Event breakdown by category
+        const byCategory = {};
+        for (const ev of events) {
+            const key = ev.category ?? "unknown";
+            byCategory[key] = (byCategory[key] ?? 0) + 1;
+        }
+        if (Object.keys(byCategory).length > 0) {
+            lines.push("- Event breakdown:");
+            for (const [category, count] of Object.entries(byCategory)) {
+                lines.push(`  - ${category}: ${count}`);
+            }
+        }
+        // Session age
+        if (stats?.started_at) {
+            const startedMs = new Date(stats.started_at).getTime();
+            const ageMinutes = Math.round((Date.now() - startedMs) / 60_000);
+            lines.push(`- Session age: ${ageMinutes}m`);
+        }
+        return lines.join("\n");
+    }
+    catch {
+        return "context-mode stats unavailable (session DB error)";
+    }
+}
+function resolveCommandContext(argsOrCtx, ctx) {
+    if (ctx !== undefined)
+        return ctx;
+    if (argsOrCtx && typeof argsOrCtx === "object")
+        return argsOrCtx;
+    return undefined;
+}
+function handleCommandText(text, ctx) {
+    if (ctx?.hasUI) {
+        ctx.ui.notify(text, "info");
+        return;
+    }
+    return { text };
+}
+// ── Extension entry point ────────────────────────────────
+/** Pi extension default export. Called once by Pi runtime with the extension API. */
+export default function piExtension(pi) {
+    const buildDir = dirname(fileURLToPath(import.meta.url));
+    const pluginRoot = resolve(buildDir, "..");
+    const projectDir = process.env.PI_PROJECT_DIR || process.cwd();
+    const db = getOrCreateDB();
+    // ── 1. session_start — Initialize session ──────────────
+    pi.on("session_start", (ctx) => {
+        try {
+            _sessionId = deriveSessionId(ctx ?? {});
+            db.ensureSession(_sessionId, projectDir);
+            db.cleanupOldSessions(7);
+        }
+        catch {
+            // best effort — never break session start
+            if (!_sessionId) {
+                _sessionId = `pi-${Date.now()}`;
+            }
+        }
+    });
+    // ── 2. tool_call — PreToolUse routing enforcement ──────
+    // Block bash commands that contain curl/wget/fetch/requests patterns.
+    pi.on("tool_call", (event) => {
+        try {
+            const toolName = String(event?.toolName ?? "").toLowerCase();
+            if (toolName !== "bash")
+                return;
+            const command = String(event?.input?.command ?? "");
+            if (!command)
+                return;
+            const isBlocked = BLOCKED_BASH_PATTERNS.some((p) => p.test(command));
+            if (isBlocked) {
+                return {
+                    block: true,
+                    reason: "Use context-mode MCP tools (execute, fetch_and_index) instead of inline HTTP clients. " +
+                        "Raw curl/wget/fetch output floods the context window.",
+                };
+            }
+        }
+        catch {
+            // Routing failure — allow passthrough
+        }
+    });
+    // ── 3. tool_result — PostToolUse event capture ─────────
+    pi.on("tool_result", (event) => {
+        try {
+            if (!_sessionId)
+                return;
+            const rawToolName = String(event?.toolName ?? event?.tool_name ?? "");
+            const mappedToolName = PI_TOOL_MAP[rawToolName.toLowerCase()] ?? rawToolName;
+            // Normalize result to string
+            const rawResult = event?.result ?? event?.output;
+            const resultStr = typeof rawResult === "string"
+                ? rawResult
+                : rawResult != null
+                    ? JSON.stringify(rawResult)
+                    : undefined;
+            // Detect errors
+            const hasError = Boolean(event?.error || event?.isError);
+            const hookInput = {
+                tool_name: mappedToolName,
+                tool_input: event?.params ?? event?.input ?? {},
+                tool_response: resultStr,
+                tool_output: hasError ? { isError: true } : undefined,
+            };
+            const events = extractEvents(hookInput);
+            if (events.length > 0) {
+                for (const ev of events) {
+                    db.insertEvent(_sessionId, ev, "PostToolUse");
+                }
+            }
+            else if (rawToolName) {
+                // Fallback: record unrecognized tool call as generic event
+                const data = JSON.stringify({
+                    tool: rawToolName,
+                    params: event?.params ?? event?.input,
+                });
+                db.insertEvent(_sessionId, {
+                    type: "tool_call",
+                    category: "pi",
+                    data,
+                    priority: 1,
+                    data_hash: createHash("sha256")
+                        .update(data)
+                        .digest("hex")
+                        .slice(0, 16),
+                }, "PostToolUse");
+            }
+        }
+        catch {
+            // Silent — session capture must never break the tool call
+        }
+    });
+    // ── 4. before_agent_start — Routing + active_memory + resume injection ─
+    pi.on("before_agent_start", async (event) => {
+        try {
+            if (!_sessionId)
+                return;
+            const prompt = String(event?.prompt ?? "");
+            // Extract user events from the prompt text
+            if (prompt) {
+                const userEvents = extractUserEvents(prompt);
+                for (const ev of userEvents) {
+                    db.insertEvent(_sessionId, ev, "UserPromptSubmit");
+                }
+            }
+            const existingPrompt = String(event?.systemPrompt ?? "");
+            const parts = [];
+            if (existingPrompt)
+                parts.push(existingPrompt);
+            // Pi-1: Inject routing block once per session (gated by _routingInjected).
+            // v1.0.107 — visible marker so Pi users can verify the routing block
+            // reached the model (Mickey-class verification path; mirrors OpenCode).
+            if (!_routingInjected.has(_sessionId)) {
+                const routingBlock = await getRoutingBlock(pluginRoot);
+                if (routingBlock) {
+                    const marker = `<!-- context-mode: routing block injected (sessionID=${String(_sessionId).slice(0, 8)}) -->`;
+                    parts.push(marker + "\n" + routingBlock);
+                    _routingInjected.add(_sessionId);
+                }
+            }
+            // Pi-3 + Pi-4: Always build active_memory (not just post-compact),
+            // capped at 500 tokens via buildAutoInjection. Falls back to inline
+            // budget loop if the helper is unavailable.
+            const activeEvents = db.getEvents(_sessionId, {
+                minPriority: 3,
+                limit: 50,
+            });
+            if (activeEvents.length > 0) {
+                const buildAuto = await getAutoInjection(pluginRoot);
+                let memoryContext = "";
+                if (buildAuto) {
+                    memoryContext = buildAuto(activeEvents.map((e) => ({
+                        category: String(e.category ?? ""),
+                        data: String(e.data ?? ""),
+                    })));
+                }
+                // Fallback (or if helper produced empty output): inline 500-token cap.
+                if (!memoryContext) {
+                    const memoryLines = ["<active_memory>"];
+                    let budget = 2000; // ~500 tokens at 4 chars/token
+                    for (const ev of activeEvents) {
+                        const line = `  <event type="${ev.type}" category="${ev.category}">${ev.data}</event>`;
+                        if (line.length > budget)
+                            break;
+                        memoryLines.push(line);
+                        budget -= line.length;
+                    }
+                    memoryLines.push("</active_memory>");
+                    if (memoryLines.length > 2)
+                        memoryContext = memoryLines.join("\n");
+                }
+                if (memoryContext)
+                    parts.push(memoryContext);
+            }
+            // Resume snapshot (only when present and unconsumed).
+            const resume = db.getResume(_sessionId);
+            if (resume && !resume.consumed && resume.snapshot) {
+                parts.push(resume.snapshot);
+                db.markResumeConsumed(_sessionId);
+            }
+            // Return modified systemPrompt only if we added something beyond existing.
+            const baseLen = existingPrompt ? 1 : 0;
+            if (parts.length > baseLen) {
+                return { systemPrompt: parts.join("\n\n") };
+            }
+        }
+        catch {
+            // best effort — never break agent start
+        }
+    });
+    // ── 4b. before_provider_response — capture response metadata ───
+    // Pi-2: Register the missing event so providers can record latency,
+    // model, and token usage when Pi exposes them. Best-effort only;
+    // the handler must never throw or modify the response.
+    pi.on("before_provider_response", (event) => {
+        try {
+            if (!_sessionId)
+                return;
+            const meta = {
+                model: event?.model ?? event?.providerModel,
+                provider: event?.provider,
+                latencyMs: event?.latencyMs ?? event?.latency,
+                tokens: event?.usage ?? event?.tokens,
+            };
+            // Skip when Pi gives us nothing useful — avoids noise in the DB.
+            if (meta.model == null &&
+                meta.provider == null &&
+                meta.latencyMs == null &&
+                meta.tokens == null) {
+                return;
+            }
+            const data = JSON.stringify(meta);
+            db.insertEvent(_sessionId, {
+                type: "provider_response",
+                category: "pi",
+                data,
+                priority: 1,
+                data_hash: createHash("sha256").update(data).digest("hex").slice(0, 16),
+            }, "PostToolUse");
+        }
+        catch {
+            // best effort — never break provider response
+        }
+    });
+    // ── 5. session_before_compact — Build resume snapshot ──
+    pi.on("session_before_compact", () => {
+        try {
+            if (!_sessionId)
+                return;
+            const allEvents = db.getEvents(_sessionId);
+            if (allEvents.length === 0)
+                return;
+            const stats = db.getSessionStats(_sessionId);
+            const snapshot = buildResumeSnapshot(allEvents, {
+                compactCount: (stats?.compact_count ?? 0) + 1,
+            });
+            db.upsertResume(_sessionId, snapshot, allEvents.length);
+        }
+        catch {
+            // best effort — never break compaction
+        }
+    });
+    // ── 6. session_compact — Increment compact counter ─────
+    pi.on("session_compact", () => {
+        try {
+            if (!_sessionId)
+                return;
+            db.incrementCompactCount(_sessionId);
+        }
+        catch {
+            // best effort
+        }
+    });
+    // ── 7. session_shutdown — Cleanup old sessions ─────────
+    pi.on("session_shutdown", () => {
+        try {
+            if (_db) {
+                _db.cleanupOldSessions(7);
+            }
+            _db = null;
+            _routingInjected.clear();
+            _sessionId = "";
+        }
+        catch {
+            // best effort — never throw during shutdown
+        }
+    });
+    // ── 8. Slash commands ──────────────────────────────────
+    pi.registerCommand("ctx-stats", {
+        description: "Show context-mode session statistics",
+        handler: async (argsOrCtx, maybeCtx) => {
+            const ctx = resolveCommandContext(argsOrCtx, maybeCtx);
+            const text = !_db || !_sessionId
+                ? "context-mode: no active session"
+                : buildStatsText(_db, _sessionId);
+            return handleCommandText(text, ctx);
+        },
+    });
+    pi.registerCommand("ctx-doctor", {
+        description: "Run context-mode diagnostics",
+        handler: async (argsOrCtx, maybeCtx) => {
+            const ctx = resolveCommandContext(argsOrCtx, maybeCtx);
+            const dbPath = getDBPath();
+            const dbExists = existsSync(dbPath);
+            const lines = [
+                "## ctx-doctor (Pi)",
+                "",
+                `- DB path: \`${dbPath}\``,
+                `- DB exists: ${dbExists}`,
+                `- Session ID: \`${_sessionId ? _sessionId.slice(0, 8) + "..." : "none"}\``,
+                `- Plugin root: \`${pluginRoot}\``,
+                `- Project dir: \`${projectDir}\``,
+            ];
+            if (_db && _sessionId) {
+                try {
+                    const stats = _db.getSessionStats(_sessionId);
+                    const eventCount = _db.getEventCount(_sessionId);
+                    lines.push(`- Events: ${eventCount}`);
+                    lines.push(`- Compactions: ${stats?.compact_count ?? 0}`);
+                    const resume = _db.getResume(_sessionId);
+                    lines.push(`- Resume snapshot: ${resume ? (resume.consumed ? "consumed" : "available") : "none"}`);
+                }
+                catch {
+                    lines.push("- DB query error");
+                }
+            }
+            const text = lines.join("\n");
+            return handleCommandText(text, ctx);
+        },
+    });
+}

package/build/server.d.ts

@@ -21,6 +21,41 @@ export declare function emitSuppressionDiagnostic(opts?: {
 }): void;
 /** Test-only: reset the one-shot emission flag so suites can re-exercise. */
 export declare function __resetSuppressionDiagnosticForTests(): void;
+/**
+ * Issue #637 — register an explicit empty `tools/list` handler on the McpServer.
+ *
+ * Background: when `suppressMcpToolsForNativePluginHost` is true, every
+ * `server.registerTool()` call is short-circuited (returns `undefined` above).
+ * The MCP SDK only installs the SDK-default `tools/list` handler when at least
+ * one `registerTool()` reaches `setToolRequestHandlers()` internally
+ * (mcp.js:56-67). Suppressing every registration leaves `tools/list`
+ * unregistered, and the framework's RPC layer answers it with
+ * `-32601 "Method not found"`.
+ *
+ * The reporter of #637 (SquirrelRat) inspected the suppressed child via
+ * `tools/list` and read the JSON-RPC error as "the plugin never registers any
+ * ctx_* tools" — when in fact the plugin DOES register all 11 tools natively
+ * (verified at `src/adapters/opencode/plugin.ts:469` and
+ * `tests/opencode-plugin.test.ts:88`). The misleading -32601 is the seed of
+ * the #637 perception.
+ *
+ * This helper installs an explicit handler that returns `{tools: []}` — a
+ * spec-compliant empty list. Paired with the existing #623 stderr diagnostic,
+ * an operator now sees:
+ *   - wire response: `{tools: []}` (matches expectation, no JSON-RPC error)
+ *   - stderr: `[context-mode] ctx_* tools/list intentionally empty… (#623)`
+ *
+ * Idempotent: throws inside SDK if called twice on the same server because
+ * `assertCanSetRequestHandler` (mcp.js:60) rejects duplicate registrations;
+ * we therefore install the SDK's default tool handlers FIRST (via a no-op
+ * registerTool of a fake tool, immediately removed) only if needed. To keep
+ * the public surface minimal, we just call `server.server.setRequestHandler`
+ * directly — that is the same low-level call used for prompts/resources at
+ * server.ts:259-261 and avoids the SDK guard entirely.
+ *
+ * Exported for test (#637 in-memory regression guard).
+ */
+export declare function registerEmptyToolsListHandler(target?: McpServer): void;
 type ToolContextOverride = {
     projectDir: string;
     sessionId?: string;

package/build/server.js

@@ -186,6 +186,44 @@ export function emitSuppressionDiagnostic(opts = {}) {
 export function __resetSuppressionDiagnosticForTests() {
     __suppressionDiagnosticEmitted = false;
 }
+/**
+ * Issue #637 — register an explicit empty `tools/list` handler on the McpServer.
+ *
+ * Background: when `suppressMcpToolsForNativePluginHost` is true, every
+ * `server.registerTool()` call is short-circuited (returns `undefined` above).
+ * The MCP SDK only installs the SDK-default `tools/list` handler when at least
+ * one `registerTool()` reaches `setToolRequestHandlers()` internally
+ * (mcp.js:56-67). Suppressing every registration leaves `tools/list`
+ * unregistered, and the framework's RPC layer answers it with
+ * `-32601 "Method not found"`.
+ *
+ * The reporter of #637 (SquirrelRat) inspected the suppressed child via
+ * `tools/list` and read the JSON-RPC error as "the plugin never registers any
+ * ctx_* tools" — when in fact the plugin DOES register all 11 tools natively
+ * (verified at `src/adapters/opencode/plugin.ts:469` and
+ * `tests/opencode-plugin.test.ts:88`). The misleading -32601 is the seed of
+ * the #637 perception.
+ *
+ * This helper installs an explicit handler that returns `{tools: []}` — a
+ * spec-compliant empty list. Paired with the existing #623 stderr diagnostic,
+ * an operator now sees:
+ *   - wire response: `{tools: []}` (matches expectation, no JSON-RPC error)
+ *   - stderr: `[context-mode] ctx_* tools/list intentionally empty… (#623)`
+ *
+ * Idempotent: throws inside SDK if called twice on the same server because
+ * `assertCanSetRequestHandler` (mcp.js:60) rejects duplicate registrations;
+ * we therefore install the SDK's default tool handlers FIRST (via a no-op
+ * registerTool of a fake tool, immediately removed) only if needed. To keep
+ * the public surface minimal, we just call `server.server.setRequestHandler`
+ * directly — that is the same low-level call used for prompts/resources at
+ * server.ts:259-261 and avoids the SDK guard entirely.
+ *
+ * Exported for test (#637 in-memory regression guard).
+ */
+export function registerEmptyToolsListHandler(target = server) {
+    target.server.registerCapabilities({ tools: { listChanged: false } });
+    target.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [] }));
+}
 const originalRegisterTool = server.registerTool.bind(server);
 server.registerTool = (...args) => {
     const [name, config, handler] = args;
@@ -196,6 +234,16 @@ server.registerTool = (...args) => {
     REGISTERED_CTX_TOOLS.push({ name, config, handler });
     return originalRegisterTool(...args);
 };
+// Issue #637 — when suppression is active, install the empty tools/list handler
+// once at module-init time so the suppressed MCP child responds with
+// `{tools: []}` instead of JSON-RPC `-32601 Method not found`. Pair with the
+// #623 stderr diagnostic that explains WHY the list is empty. Skipped for the
+// embedded plugin-import path because the embedded process is not the stdio
+// MCP child an operator would inspect — it lives inside the OpenCode/Kilo
+// host and never speaks JSON-RPC over stdio.
+if (suppressMcpToolsForNativePluginHost && process.env.CONTEXT_MODE_EMBEDDED_PLUGIN_TOOLS !== "1") {
+    registerEmptyToolsListHandler(server);
+}
 const projectDirOverride = new AsyncLocalStorage();
 export async function withProjectDirOverride(projectDir, fn) {
     const ctx = typeof projectDir === "string" ? { projectDir } : projectDir;
@@ -204,7 +252,7 @@ export async function withProjectDirOverride(projectDir, fn) {
 // Register empty prompts/resources handlers so MCP clients don't get -32601 (#168).
 // OpenCode calls listPrompts()/listResources() unconditionally — the error can poison
 // the SDK transport layer, causing subsequent listTools() calls to fail permanently.
-import { ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 server.server.registerCapabilities({ prompts: { listChanged: false }, resources: { listChanged: false } });
 server.server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] }));
 server.server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [] }));

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;