context-mode 1.0.154 → 1.0.156

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/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.
+    }
+}