@mxalbert/context-mode 2.0.2 → 2.0.3

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "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/.codex-plugin/plugin.json

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

package/.openclaw-plugin/package.json

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

package/README.md

@@ -1208,7 +1208,7 @@ Indexed content persists in a per-project SQLite database at `~/.context-mode/co
 - **Cache hit (within TTL):** Returns a cache hint (~0.3KB) instead of re-fetching (48KB+). Model proceeds to `ctx_search`.
 - **Cache miss (TTL expired):** Re-fetches silently. No user action needed.
 - **`ttl: 0`** or **`force: true`:** Bypasses cache and re-fetches regardless of freshness.
-- **14-day cleanup:** Content databases and sources older than 14 days are removed on startup.
+- **14-day cleanup:** Sources older than 14 days are removed from the knowledge base on startup. Content DB files themselves are never auto-deleted — an open-but-idle store is indistinguishable from an abandoned one by timestamps alone, and deleting a live store's files causes unrecoverable I/O errors. Use `ctx_purge` to reclaim disk space.
 
 This means `--continue` sessions preserve indexed docs across restarts. No re-fetching, no wasted context tokens.
 

package/build/adapters/opencode/plugin.d.ts

@@ -49,8 +49,9 @@
  *   - No routing file auto-write (avoid dirtying project trees)
  *   - Session cleanup happens at plugin init (no SessionStart)
  */
-import { type PluginGlobalState } from "./index.js";
-import { type PluginClient, type V2SetupContext } from "./v2.js";
+import { SessionDB } from "../../session/db.js";
+import { AdapterPlatformType, OpenCodeAdapter, type PluginGlobalState } from "./index.js";
+import { type PluginClient, type PluginClientAppLogBodyExtra, type V2SetupContext } from "./v2.js";
 type PluginContext = {
     client: PluginClient;
     directory: string;
@@ -192,6 +193,63 @@ export declare function __resetPluginStateForTests(): void;
 export declare function __getPluginGlobalState(): PluginGlobalState;
 /** Test-only: close the cached fd and clear the sink cache so each test gets a fresh sink. */
 export declare function __resetPluginLogSinkForTests(): void;
+type EmitLevel = "info" | "warn" | "error";
+/**
+ * Per-plugin-process state shared by the v1 `server()` path and the v2
+ * `setup()` path. Both flavors bridge to the SAME handler functions built
+ * over this runtime — logic is never duplicated across flavors.
+ */
+interface PluginRuntime {
+    ctx: PluginContext;
+    platform: AdapterPlatformType;
+    adapter: OpenCodeAdapter;
+    projectDir: string;
+    db: SessionDB;
+    routing: {
+        routePreToolUse: (...args: unknown[]) => any;
+        /** v2-native availability signal (hooks/core/routing.mjs) — optional: older routing copies lack it. */
+        setContextModeToolsAvailable?: (available: boolean) => void;
+        /**
+         * v2 permission-evaluate routing (hooks/core/routing.mjs) — optional:
+         * older routing copies lack it, and the permission bridge no-ops (fail
+         * open, host decision untouched) when absent.
+         */
+        routePermissionEvaluate?: (action: unknown, resources: unknown, projectDir: unknown, platform: unknown) => {
+            effect: "allow" | "deny" | "ask";
+            message?: string;
+        } | null;
+    };
+    routingBlock: string;
+    autoInjectionMod: {
+        buildAutoInjection: (events: unknown) => string;
+    };
+    captureAgentsMd: (sessionId: string) => void;
+    buildNativeTools: () => Promise<Record<string, NativeToolDefinition>>;
+    logger: (message?: string, extra?: PluginClientAppLogBodyExtra) => Promise<void>;
+    safeLog: (message?: string, extra?: PluginClientAppLogBodyExtra) => Promise<void>;
+    logHookError: (hookName: string, err: unknown, sessionId?: string) => void;
+    logOnce: (key: string, message: string, level?: EmitLevel) => void;
+    /**
+     * Liveness gate for v2-registered callbacks (defense-in-depth). Set to
+     * true by teardownV2 BEFORE any dispose / claim release: hosts whose
+     * registration calls succeed but return NO dispose handle cannot be fully
+     * unregistered, so their stale callbacks are neutralized instead — every
+     * v2 entry point below checks this flag and no-ops (no throw, no DB touch)
+     * once the runtime is torn down. The v1 path never tears a runtime down.
+     */
+    closed: boolean;
+}
+/**
+ * The v2 permission-evaluate bridge handler. Extracted (and exported) so the
+ * behavioral contracts are unit-testable: malformed events and a routing
+ * throw must leave the host decision untouched (fail-open), and a torn-down
+ * runtime must no-op (liveness gate). `route` is pre-bound to the runtime's
+ * projectDir/platform by the caller.
+ */
+export declare function createV2PermissionEvaluateHandler(rt: Pick<PluginRuntime, "closed" | "logHookError">, route: (action: string, resources: string[]) => {
+    effect: "allow" | "deny" | "ask";
+    message?: string;
+} | null): (event: unknown) => Promise<undefined>;
 /**
  * Plugin factory. Called once when a v1 host (KiloCode/OpenCode ≤ v1) loads
  * the plugin. Returns an object mapping hook event names to async handler

package/build/adapters/opencode/plugin.js

@@ -1283,6 +1283,85 @@ async function registerEventBusV2(ctx, rt, handlers) {
         dispose: hostDispose ? chainDisposes([abortDispose, hostDispose]) : abortDispose,
     };
 }
+/**
+ * OPTIONAL: register the v2 permission "evaluate" hook — the surface that
+ * restores true ask/confirmation semantics on OpenCode v2 (verified against
+ * opencode2 beta-19135 live probe; see .research/opencode-v2-permission-hooks.md).
+ *
+ * The host asserts every core-tool action (shell, read, …) through its
+ * permission system before execution and lets the hook MUTATE the decision
+ * (event.effect / event.message). The bridge routes the event through the
+ * shared routing engine's routePermissionEvaluate and applies its verdict:
+ *
+ *   - deny → effect "deny" — blocked with the policy reason (normally
+ *     pre-empted by the execute.before throw which fires earlier —
+ *     this is defense-in-depth for assert paths execute.before cannot see)
+ *   - ask  → effect "ask" — an interactive confirmation in TUI runs,
+ *     restoring the user's ask intent even when host allow rules would
+ *     auto-approve; under `--auto` the host auto-approves the ask too
+ *     (explicit opt-in, verified live)
+ *   - allow → effect "allow" — skips the host's default-ask prompt for
+ *     commands the user's own GLOBAL permission rules pre-approve
+ *   - null → untouched — the host decision (its rules / default ask / --auto)
+ *     stays exactly as computed
+ *
+ * Plugin-registered tools (the ctx_* tools themselves) are NOT
+ * permission-evaluated (empirically verified — see
+ * .research/opencode-v2-empirical-test-results.md), so their gating stays in
+ * tool.execute.before; this hook only covers host core-tool actions, with
+ * zero overlap or double-handling: execute.before keeps deny/modify/context,
+ * and its Stage-1 ask already falls through (opencode is not in
+ * ASK_CAPABLE_PLATFORMS), so the ask decision is expressed HERE, once.
+ *
+ * Fail-open: a routing throw leaves the event untouched (mirrors the
+ * execute.before catch — a routing failure must never brick tool calls).
+ */
+async function registerPermissionHookV2(ctx, rt) {
+    const permissionHook = ctx?.permission && typeof ctx.permission.hook === "function" ? ctx.permission.hook : undefined;
+    if (!permissionHook || !ctx?.permission)
+        return { ok: false };
+    const routePermissionEvaluate = rt.routing.routePermissionEvaluate;
+    const handler = createV2PermissionEvaluateHandler(rt, (action, resources) => {
+        if (typeof routePermissionEvaluate !== "function")
+            return null; // older routing copy — no-op
+        return routePermissionEvaluate(action, resources, rt.projectDir, rt.platform);
+    });
+    return tryRegister(permissionHook, ctx.permission, "evaluate", handler);
+}
+/**
+ * The v2 permission-evaluate bridge handler. Extracted (and exported) so the
+ * behavioral contracts are unit-testable: malformed events and a routing
+ * throw must leave the host decision untouched (fail-open), and a torn-down
+ * runtime must no-op (liveness gate). `route` is pre-bound to the runtime's
+ * projectDir/platform by the caller.
+ */
+export function createV2PermissionEvaluateHandler(rt, route) {
+    return async (event) => {
+        if (rt.closed)
+            return undefined; // torn down — silent no-op
+        const ev = (event ?? {});
+        const action = typeof ev.action === "string" ? ev.action : "";
+        const resources = Array.isArray(ev.resources)
+            ? ev.resources.filter((r) => typeof r === "string")
+            : [];
+        if (!action || resources.length === 0)
+            return undefined;
+        let routed = null;
+        try {
+            routed = route(action, resources);
+        }
+        catch (err) {
+            rt.logHookError("v2.permission.evaluate", err, v2SessionIdOf(ev));
+            return undefined; // fail-open — host decision untouched
+        }
+        if (!routed)
+            return undefined;
+        ev.effect = routed.effect;
+        if (typeof routed.message === "string")
+            ev.message = routed.message;
+        return undefined; // mutation is the contract — the return value is ignored
+    };
+}
 /**
  * MANDATORY: register the native ctx_* tools via ctx.tool.transform(editor)
  * (verified v2 API). The ToolEditor receives one ToolInfo per ctx_* tool:
@@ -1591,7 +1670,16 @@ async function setupV2(ctx) {
             missingMessage: "context-mode v2: event bus unavailable (no ctx.event.subscribe) — per-turn token/cost capture inactive",
         });
         disposes.push(...eventBus.disposes);
-        rt.logOnce("v2-setup-complete", `context-mode v2 setup complete: native tools via ctx.tool.transform; tool hooks via ${toolRegs.via}; session context: ${sessionContext.status}; prompt capture: ${promptCapture.status}; event bus: ${eventBus.status}`, "info");
+        // Optional: permission "evaluate" hook — true ask/allow security
+        // semantics on permission-evaluated actions (see registerPermissionHookV2).
+        const permissionHook = await attemptOptionalV2(activeRt, {
+            surfacePresent: typeof ctx?.permission?.hook === "function",
+            register: () => registerPermissionHookV2(ctx, activeRt),
+            logKeyMissing: "v2-permission-hook-missing",
+            missingMessage: "context-mode v2: permission evaluate hook unavailable (no ctx.permission.hook) — ask/allow security semantics inactive; deny enforcement stays on tool.execute.before",
+        });
+        disposes.push(...permissionHook.disposes);
+        rt.logOnce("v2-setup-complete", `context-mode v2 setup complete: native tools via ctx.tool.transform; tool hooks via ${toolRegs.via}; session context: ${sessionContext.status}; prompt capture: ${promptCapture.status}; event bus: ${eventBus.status}; permission hook: ${permissionHook.status}`, "info");
         return async () => {
             // Cleanup: unregister everything registered, close the runtime DB
             // handle, then release the activation claim so a reload can re-claim.

package/build/adapters/opencode/v2.d.ts

@@ -87,6 +87,17 @@ export type V2SetupContext = {
             signal?: AbortSignal;
         }) => unknown;
     };
+    /**
+     * v2 permission domain (verified against opencode2 beta-19135 live probe:
+     * ctx.permission.hook("evaluate", cb) fires for every core-tool permission
+     * assert with a MUTABLE event { action, resources, source?, effect, message? }
+     * — hook mutations of effect/message win the decision). Optional: older v2
+     * builds and all v1 hosts lack the surface; the plugin degrades to the
+     * execute.before throw-based behavior there.
+     */
+    permission?: {
+        hook?: (name: string, cb: (event: unknown) => unknown) => unknown;
+    };
 };
 /**
  * Convert a Zod (v3-classic) schema into a JSON-Schema object — the shared

package/build/server.js

@@ -21,7 +21,7 @@ import { detectRuntimes, getRuntimeSummary, getAvailableLanguages, hasBunRuntime
 import { classifyNonZeroExit } from "./exit-classify.js";
 import { startLifecycleGuard, noteMcpActivity, noteRequestStart, noteRequestEnd, attachMcpActivityTap } from "./lifecycle.js";
 import { charSafePrefix } from "./truncate.js";
-import { describeStorageDirectorySource, ensureWritableStorageDir, formatStorageDirectoryError, hashProjectDirCanonical, hashProjectDirLegacy, resolveContentStorePath, resolveContentStorageDir, resolveDefaultSessionDir, resolveSessionDbPath, resolveSessionStorageDir, resolveStatsStorageDir, SessionDB, StorageDirectoryError, } from "./session/db.js";
+import { describeStorageDirectorySource, ensureWritableStorageDir, formatStorageDirectoryError, hashProjectDirCanonical, hashProjectDirLegacy, resolveContentStorePath, resolveContentStorageDir, resolveDefaultSessionDir, resolveSessionDbPath, resolveSessionPath, resolveSessionStorageDir, resolveStatsStorageDir, SessionDB, StorageDirectoryError, } from "./session/db.js";
 import { purgeSession } from "./session/purge.js";
 import { NPM_LATEST_URL, PACKAGE_NAME, PLUGIN_KEY } from "./package-identity.js";
 import { emitCacheHitEvent, emitIndexWriteEvent, emitSandboxExecuteEvent, } from "./session/event-emit.js";
@@ -370,8 +370,19 @@ process.on("exit", () => { try {
     unlinkSync(CM_FS_PRELOAD);
 }
 catch { /* best effort */ } });
-// Lazy singleton — no DB overhead unless index/search is used
-let _store = null;
+// Lazy per-project store cache — no DB overhead unless index/search is used.
+// Keyed by resolved dbPath: multi-project hosts (opencode web serves MANY
+// projects inside ONE process, each plugin tool call arriving with its own
+// projectDir via withProjectDirOverride) get one store per project. A single
+// cached instance would funnel every project's reads/writes into whichever
+// project ran the first ctx_* tool — cross-project knowledge-base exposure
+// AND one long-lived connection whose files other processes' startup
+// cleanups may unlink (surfaces as disk I/O error, SQLITE_IOERR_VNODE).
+// Mirrors the #645 SessionDB singleton re-keying pattern applied to the
+// Pi/OMP/OpenClaw plugins.
+const _stores = new Map();
+/** True once the process-wide startup cleanups have run (see getStore). */
+let _startupCleanupsRan = false;
 /**
  * Build the FK-attribution object passed to every ContentStore.index*() call
  * in this process. CLAUDE_SESSION_ID is the only MCP-side handle we have on
@@ -434,27 +445,34 @@ export function resolveSessionIdFromSessionDB(opts) {
     }
 }
 /**
- * Auto-index session events files written by SessionStart hook.
- * Scans ~/.claude/context-mode/sessions/ for *-events.md files.
- * CLAUDE_PROJECT_DIR is NOT available to MCP servers — only to hooks —
- * so we glob-scan instead of computing a specific hash.
- * Files are consumed (deleted) after indexing to prevent double-indexing.
- * Called on every getStore() — readdirSync is sub-millisecond when no files match.
+ * Auto-index the CURRENT project's session events file written by the
+ * SessionStart hook (same per-project path derivation the hook uses —
+ * canonical hash + worktree suffix). The file is consumed (deleted) after
+ * indexing to prevent double-indexing. Called on every getStore().
+ *
+ * Scoped to this project deliberately: the events filename is per-project,
+ * and a multi-project host (opencode web) shares one sessions directory
+ * across projects. The previous implementation glob-scanned the whole
+ * directory, so whichever project ran the first ctx_* tool indexed — and
+ * consumed — every OTHER project's pending events into its own store.
  */
 function maybeIndexSessionEvents(store) {
     try {
         const sessionsDir = getSessionDir();
         if (!existsSync(sessionsDir))
             return;
-        const files = readdirSync(sessionsDir).filter(f => f.endsWith("-events.md"));
-        for (const file of files) {
-            const filePath = join(sessionsDir, file);
-            try {
-                store.index({ path: filePath, source: "session-events", attribution: currentAttribution() });
-                unlinkSync(filePath);
-            }
-            catch { /* best-effort per file */ }
+        const eventsPath = resolveSessionPath({
+            projectDir: getProjectDir(),
+            sessionsDir,
+            ext: "-events.md",
+        });
+        if (!existsSync(eventsPath))
+            return;
+        try {
+            store.index({ path: eventsPath, source: "session-events", attribution: currentAttribution() });
+            unlinkSync(eventsPath);
         }
+        catch { /* best-effort */ }
     }
     catch { /* best-effort — session continuity never blocks tools */ }
 }
@@ -632,19 +650,27 @@ function getStorePath() {
     return resolveContentStorePath({ projectDir: getProjectDir(), contentDir: dir });
 }
 function getStore() {
-    if (!_store) {
-        // Content DB cleanup on fresh start is handled by SessionStart hook.
-        // Server just opens whatever DB exists (or creates new if hook deleted it).
-        const dbPath = getStorePath();
-        _store = new ContentStore(dbPath);
+    // Opens whatever DB exists (or creates a new one). Routine retention
+    // never deletes per-platform DB FILES — it is row-level only
+    // (cleanupStaleSources below) and on-disk reclamation is ctx_purge's
+    // job (rationale in the startup block below). The only file-deleting
+    // exception is the constructor's corruption-recovery path.
+    const dbPath = getStorePath();
+    let store = _stores.get(dbPath);
+    if (!store) {
+        store = new ContentStore(dbPath);
+        _stores.set(dbPath, store);
         // Wire deny-policy hook: store re-checks the Read deny list before
         // re-reading any file_path during auto-refresh. Catches policy edits
-        // made after a file was originally indexed. See #442 round-3.
-        _store.setDenyChecker((filePath) => {
+        // made after a file was originally indexed. See #442 round-3. The
+        // project dir is pinned at creation — the store is project-scoped, so
+        // its deny policy stays this project's even when other projects make
+        // calls into the same process.
+        const storeProjectDir = getProjectDir();
+        store.setDenyChecker((filePath) => {
             try {
-                const projectDir = getProjectDir();
-                const denyGlobs = readToolDenyPatterns("Read", projectDir);
-                const r = evaluateFilePath(filePath, denyGlobs, process.platform === "win32", projectDir);
+                const denyGlobs = readToolDenyPatterns("Read", storeProjectDir);
+                const r = evaluateFilePath(filePath, denyGlobs, process.platform === "win32", storeProjectDir);
                 return r.denied;
             }
             catch {
@@ -652,22 +678,36 @@ function getStore() {
                 return true;
             }
         });
-        // One-time startup cleanup: remove stale content DBs (>14 days)
+        // Per-store: drop this project's sources untouched for 14 days.
         try {
-            const contentDir = dirname(getStorePath());
-            cleanupStaleContentDBs(contentDir, 14);
-            _store.cleanupStaleSources(14);
-            // Also clean legacy shared dir from before platform isolation
-            const legacyDir = join(homedir(), ".context-mode", "content");
-            if (existsSync(legacyDir))
-                cleanupStaleContentDBs(legacyDir, 0);
+            store.cleanupStaleSources(14);
         }
         catch { /* best-effort */ }
-        // Also clean old PID-based DBs from migration
-        cleanupStaleDBs();
+        // Process-wide, once: sweep the legacy shared content dir (pre-platform-
+        // isolation) and orphaned PID-based tmpdir DBs from the migration. Runs
+        // on FIRST store creation only — not once per project.
+        //
+        // The per-platform content dir gets NO automatic file deletion: mtime
+        // cannot distinguish a long-idle LIVE connection (a web host with a
+        // project open but untouched for weeks) from an abandoned DB, and
+        // unlinking an open store's db/-wal/-shm surfaces as unrecoverable
+        // disk I/O errors (SQLITE_IOERR_VNODE on macOS). Retention inside
+        // each store is handled logically above (cleanupStaleSources);
+        // on-disk reclamation is ctx_purge's job.
+        if (!_startupCleanupsRan) {
+            _startupCleanupsRan = true;
+            try {
+                const legacyDir = join(homedir(), ".context-mode", "content");
+                if (existsSync(legacyDir))
+                    cleanupStaleContentDBs(legacyDir, 0);
+            }
+            catch { /* best-effort */ }
+            // Also clean old PID-based DBs from migration
+            cleanupStaleDBs();
+        }
     }
-    maybeIndexSessionEvents(_store);
-    return _store;
+    maybeIndexSessionEvents(store);
+    return store;
 }
 // ─────────────────────────────────────────────────────────
 // Session stats — track context consumption per tool
@@ -4629,12 +4669,17 @@ EXAMPLE: ctx_purge(confirm: true, scope: "project")`,
         storePathForPurge = getStorePath();
     }
     catch { /* best effort — store path may be unresolvable on fresh install */ }
-    if (_store) {
-        try {
-            _store.cleanup();
+    if (storePathForPurge) {
+        // Close ONLY the calling project's store — other projects' stores in a
+        // multi-project host (opencode web) are neither purged nor disturbed.
+        const openStore = _stores.get(storePathForPurge);
+        if (openStore) {
+            try {
+                openStore.cleanup();
+            }
+            catch { /* best effort */ }
+            _stores.delete(storePathForPurge);
         }
-        catch { /* best effort */ }
-        _store = null;
     }
     // FTS5 store: pass contentDir so purgeSession sweeps BOTH canonical
     // and legacy raw-casing variants (dual-hash, mirrors session events).
@@ -4906,8 +4951,15 @@ async function main() {
     // Clean up own DB + backgrounded processes + preload script on shutdown
     const shutdown = () => {
         executor.cleanupBackgrounded();
-        if (_store)
-            _store.close(); // persist DB for --continue sessions
+        // Persist every open per-project DB for --continue sessions. Cleared
+        // after close so a repeated shutdown call cannot double-close a store.
+        for (const openStore of _stores.values()) {
+            try {
+                openStore.close();
+            }
+            catch { /* best effort */ }
+        }
+        _stores.clear();
         try {
             unlinkSync(CM_FS_PRELOAD);
         }

package/build/session/purge.js

@@ -131,7 +131,8 @@ export function purgeSession(opts) {
         //
         // Caller is responsible for closing any persistent ContentStore
         // handle BEFORE invoking purgeSession (Windows file lock). The
-        // ctx_purge handler does this via _store?.cleanup() before delegating.
+        // ctx_purge handler does this via the per-project store cache's
+        // cleanup() before delegating.
         const ftsTargets = [];
         if (storePath && existsSync(storePath))
             ftsTargets.push(storePath);

package/build/store.d.ts

@@ -19,9 +19,28 @@ export declare function sanitizeTrigramQuery(query: string, mode?: "AND" | "OR")
 export declare function cleanupStaleDBs(): number;
 /**
  * Clean up stale per-project content store DBs older than maxAgeDays.
- * Scans the given directory for *.db files and checks mtime.
- * Also detects zombie processes holding WAL locks — if a WAL file exists
- * but the owning PID is dead, the DB files are cleaned up regardless of age.
+ * Scans the given directory for *.db files and unlinks each (plus its
+ * -wal/-shm sidecars) when its EFFECTIVE last-write time — the newer of the
+ * main .db mtime and a non-empty -wal mtime — exceeds the cutoff.
+ *
+ * Why the -wal mtime participates: in WAL mode commits touch only the -wal
+ * file; the main .db mtime advances at checkpoint. A main-only check can
+ * delete an actively-used store that simply hasn't checkpointed within the
+ * window. Conversely, a non-empty -wal older than some threshold is NOT
+ * proof the owning process is dead — a live-but-idle connection (a session
+ * quiet over lunch) is indistinguishable from a crashed process by mtime
+ * alone. The pre-fix heuristic deleted such DBs unconditionally after 1h,
+ * which on macOS unlinks the files under an open connection and surfaces
+ * as disk I/O error (SQLITE_IOERR_VNODE) on every later write — no amount
+ * of retrying recovers an invalidated fd.
+ *
+ * Contract: a -wal can only EXTEND a DB's life (its mtime counts as the
+ * latest write), never shorten it. A WAL never triggers deletion on its
+ * own — the way the old 1-hour zombie rule did — and once the whole DB
+ * (main + non-empty wal) is beyond maxAgeDays, the caller's retention
+ * policy owns the consequences. Callers that cannot tolerate deleting a
+ * possibly-live DB (the per-platform content dir — see getStore() in
+ * src/server.ts) must not call this with a nonzero maxAgeDays.
  */
 export declare function cleanupStaleContentDBs(contentDir: string, maxAgeDays: number): number;
 export declare class ContentStore {

package/build/store.js

@@ -158,24 +158,30 @@ export function cleanupStaleDBs() {
     catch { /* ignore readdir errors */ }
     return cleaned;
 }
-/**
- * Check if a PID is still alive (not a zombie holding a WAL lock).
- * Returns true if the process exists, false if it's dead.
- */
-function isProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Clean up stale per-project content store DBs older than maxAgeDays.
- * Scans the given directory for *.db files and checks mtime.
- * Also detects zombie processes holding WAL locks — if a WAL file exists
- * but the owning PID is dead, the DB files are cleaned up regardless of age.
+ * Scans the given directory for *.db files and unlinks each (plus its
+ * -wal/-shm sidecars) when its EFFECTIVE last-write time — the newer of the
+ * main .db mtime and a non-empty -wal mtime — exceeds the cutoff.
+ *
+ * Why the -wal mtime participates: in WAL mode commits touch only the -wal
+ * file; the main .db mtime advances at checkpoint. A main-only check can
+ * delete an actively-used store that simply hasn't checkpointed within the
+ * window. Conversely, a non-empty -wal older than some threshold is NOT
+ * proof the owning process is dead — a live-but-idle connection (a session
+ * quiet over lunch) is indistinguishable from a crashed process by mtime
+ * alone. The pre-fix heuristic deleted such DBs unconditionally after 1h,
+ * which on macOS unlinks the files under an open connection and surfaces
+ * as disk I/O error (SQLITE_IOERR_VNODE) on every later write — no amount
+ * of retrying recovers an invalidated fd.
+ *
+ * Contract: a -wal can only EXTEND a DB's life (its mtime counts as the
+ * latest write), never shorten it. A WAL never triggers deletion on its
+ * own — the way the old 1-hour zombie rule did — and once the whole DB
+ * (main + non-empty wal) is beyond maxAgeDays, the caller's retention
+ * policy owns the consequences. Callers that cannot tolerate deleting a
+ * possibly-live DB (the per-platform content dir — see getStore() in
+ * src/server.ts) must not call this with a nonzero maxAgeDays.
  */
 export function cleanupStaleContentDBs(contentDir, maxAgeDays) {
     let cleaned = 0;
@@ -187,26 +193,18 @@ export function cleanupStaleContentDBs(contentDir, maxAgeDays) {
         for (const file of files) {
             try {
                 const filePath = join(contentDir, file);
-                const mtime = statSync(filePath).mtimeMs;
-                let shouldClean = mtime < cutoff;
-                // Detect zombie processes holding WAL locks:
-                // If a WAL file exists, try to read the WAL header to extract the PID.
-                // WAL files from dead processes can block new connections.
-                if (!shouldClean) {
-                    const walPath = filePath + "-wal";
-                    if (existsSync(walPath)) {
-                        try {
-                            const walStat = statSync(walPath);
-                            // If WAL file is non-empty and DB hasn't been modified in >1 hour,
-                            // the owning process may be dead — check via mtime staleness
-                            if (walStat.size > 0 && (Date.now() - walStat.mtimeMs) > 3600_000) {
-                                shouldClean = true;
-                            }
-                        }
-                        catch { /* ignore WAL check errors */ }
+                // Effective last-write: newer of main .db and non-empty -wal. A fresh
+                // WAL is evidence of a live (or recently-live) connection — it can
+                // only push the cutoff later, never mark a fresh DB stale.
+                let effectiveMs = statSync(filePath).mtimeMs;
+                try {
+                    const walStat = statSync(filePath + "-wal");
+                    if (walStat.size > 0 && walStat.mtimeMs > effectiveMs) {
+                        effectiveMs = walStat.mtimeMs;
                     }
                 }
-                if (shouldClean) {
+                catch { /* no -wal — main mtime stands */ }
+                if (effectiveMs < cutoff) {
                     for (const suffix of ["", "-wal", "-shm"]) {
                         try {
                             unlinkSync(filePath + suffix);