dsh-plugin-sessiongraph-sessions 0.1.9 → 0.1.11

package/lib/index.d.ts

@@ -110,6 +110,12 @@ export interface Config {
      * explicit `sessiongraph_index` / `/sessiongraph index` before anything is searchable.
      */
     autoBuild?: boolean;
+    /**
+     * Treat a write lock older than this many milliseconds as abandoned (default 300000). A crashed
+     * run leaves `index.lock` behind; without a staleness window the index would stay unwritable until
+     * someone deleted the file by hand.
+     */
+    indexLockStaleMs?: number;
     /**
      * Hand an explicit index run to the host's background-job registry once the session store holds at
      * least this many logs (default 1000). Below it the run is synchronous, because a small index is

package/lib/index.js

@@ -40,6 +40,7 @@ import { basename, join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { loadNative } from 'dsh-plugin-sessiongraph-native';
 import { INDEX_RELATIVE_PATH, SessiongraphIndexerId } from 'dsh-plugin-sessiongraph-service';
+import { acquireIndexLock } from "./lock.js";
 import { collectLiveSessions, LIVE_SOURCE_PREFIX } from "./live.js";
 import { parseSessionLog } from "./parse.js";
 import { scanSessions } from "./scan.js";
@@ -90,6 +91,7 @@ export const Config = z.object({
     maxFileBytes: z.number().default(DEFAULT_MAX_FILE_BYTES),
     autoIndex: z.boolean().default(true),
     autoBuild: z.boolean().default(true),
+    indexLockStaleMs: z.number().default(300_000),
     backgroundIndexThreshold: z.number().default(DEFAULT_BACKGROUND_INDEX_THRESHOLD),
     maxLiveSessions: z.number().default(DEFAULT_MAX_LIVE_SESSIONS),
     engine: z.union([z.const('auto'), z.const('native'), z.const('typescript')]).default(DEFAULT_ENGINE),
@@ -541,6 +543,27 @@ async function runLivePass(ctx, indexPath, config, inScope, provenance) {
  * @returns what the run did.
  */
 export async function runIndex(indexRoot, options, signal, config, ctx) {
+    // Serialize every writer of this root — the automatic refresh, the lazy refresh and an explicit
+    // `/sessiongraph index` all land here, and two engines opening the same SQLite file is how the
+    // index got corrupted before. Waiting for another run to finish is always better than rebuilding.
+    const release = await acquireIndexLock(indexRoot, { staleMs: config.indexLockStaleMs });
+    try {
+        return await runIndexUnlocked(indexRoot, options, signal, config, ctx);
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * The actual run, with the write lock already held.
+ * @param indexRoot - directory holding the index.
+ * @param options - caller switches.
+ * @param signal - aborts the run.
+ * @param config - resolved plugin configuration.
+ * @param ctx - plugin context, consulted for the optional live-session service.
+ * @returns the run's report.
+ */
+async function runIndexUnlocked(indexRoot, options, signal, config, ctx) {
     const startedAt = Date.now();
     const indexPath = join(indexRoot, INDEX_RELATIVE_PATH);
     const workspaceFilter = options.workspace;

package/lib/lock.d.ts

@@ -0,0 +1,41 @@
+/**
+ * One writer at a time per index root, across processes.
+ *
+ * Why this exists: the same `index.db` is written by two engines (the TypeScript one through
+ * `node:sqlite`, the Rust one through bundled rusqlite) and reached by three triggers (the
+ * `agent/created` background job, the lazy refresh before a query, and an explicit
+ * `sessiongraph_index`). Nothing in SQLite serializes two writers that open the file
+ * independently, and the failure mode is not a clean lock conflict — it is a corpus that later
+ * reports `database disk image is malformed` and has to be rebuilt from scratch. A lock file turns
+ * that into a short wait.
+ *
+ * The lock is a file created with `wx` (exclusive create): the winner writes its pid and proceeds,
+ * the losers poll until it disappears. A crash leaves the file behind, so a lock older than
+ * {@link STALE_LOCK_MS} is broken — the alternative is a permanently unusable index that only
+ * deleting a file by hand can fix.
+ * @module dsh-plugin-sessiongraph-sessions/lock
+ */
+/** File name of the lock inside an index root. */
+export declare const LOCK_FILE_NAME = "index.lock";
+/** How long a lock may sit untouched before another writer treats its owner as dead. */
+export declare const STALE_LOCK_MS: number;
+/** How long a writer waits for the lock before giving up. */
+export declare const LOCK_TIMEOUT_MS: number;
+/** Options for {@link acquireIndexLock}, all overridable so tests do not wait minutes. */
+export interface IndexLockOptions {
+    /** Give up after this long. */
+    timeoutMs?: number;
+    /** Treat a lock older than this as abandoned. */
+    staleMs?: number;
+}
+/**
+ * Acquire the write lock for one index root.
+ *
+ * @param indexRoot - directory holding the index the caller is about to write.
+ * @param options - timeout and staleness overrides, for tests.
+ * @returns a release function; calling it more than once is safe.
+ * @throws when the lock cannot be taken before the timeout, so the caller can skip the run instead
+ *   of writing concurrently.
+ */
+export declare function acquireIndexLock(indexRoot: string, options?: IndexLockOptions): Promise<() => void>;
+//# sourceMappingURL=lock.d.ts.map

package/lib/lock.js

@@ -0,0 +1,107 @@
+/**
+ * One writer at a time per index root, across processes.
+ *
+ * Why this exists: the same `index.db` is written by two engines (the TypeScript one through
+ * `node:sqlite`, the Rust one through bundled rusqlite) and reached by three triggers (the
+ * `agent/created` background job, the lazy refresh before a query, and an explicit
+ * `sessiongraph_index`). Nothing in SQLite serializes two writers that open the file
+ * independently, and the failure mode is not a clean lock conflict — it is a corpus that later
+ * reports `database disk image is malformed` and has to be rebuilt from scratch. A lock file turns
+ * that into a short wait.
+ *
+ * The lock is a file created with `wx` (exclusive create): the winner writes its pid and proceeds,
+ * the losers poll until it disappears. A crash leaves the file behind, so a lock older than
+ * {@link STALE_LOCK_MS} is broken — the alternative is a permanently unusable index that only
+ * deleting a file by hand can fix.
+ * @module dsh-plugin-sessiongraph-sessions/lock
+ */
+import { rmSync } from 'node:fs';
+import { mkdir, open, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** File name of the lock inside an index root. */
+export const LOCK_FILE_NAME = 'index.lock';
+/** How long a lock may sit untouched before another writer treats its owner as dead. */
+export const STALE_LOCK_MS = 5 * 60 * 1000;
+/** How long a writer waits for the lock before giving up. */
+export const LOCK_TIMEOUT_MS = 2 * 60 * 1000;
+/** Polling interval while another writer holds the lock. */
+const POLL_MS = 100;
+/**
+ * Acquire the write lock for one index root.
+ *
+ * @param indexRoot - directory holding the index the caller is about to write.
+ * @param options - timeout and staleness overrides, for tests.
+ * @returns a release function; calling it more than once is safe.
+ * @throws when the lock cannot be taken before the timeout, so the caller can skip the run instead
+ *   of writing concurrently.
+ */
+export async function acquireIndexLock(indexRoot, options = {}) {
+    const timeoutMs = options.timeoutMs ?? LOCK_TIMEOUT_MS;
+    const staleMs = options.staleMs ?? STALE_LOCK_MS;
+    const lockPath = join(indexRoot, LOCK_FILE_NAME);
+    // The index root may not exist yet — a first build creates it, and creating the lock is what has
+    // to happen first.
+    await mkdir(indexRoot, { recursive: true });
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const handle = await open(lockPath, 'wx');
+            try {
+                await handle.writeFile(`${process.pid}\n`, 'utf8');
+            }
+            finally {
+                await handle.close();
+            }
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                // Synchronous on purpose: a disposer returning a promise can be dropped by a `finally` on
+                // an async path that is already unwinding, and a leaked lock blocks every later writer
+                // until the staleness window reclaims it.
+                try {
+                    rmSync(lockPath, { force: true });
+                }
+                catch {
+                    // A lock we cannot remove is bad, but throwing from a release would mask the run's own
+                    // error. The staleness window is the backstop.
+                }
+            };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            await breakStaleLock(lockPath, staleMs);
+            if (Date.now() > deadline) {
+                throw new Error(`sessiongraph: timed out after ${timeoutMs}ms waiting for the index write lock at "${lockPath}"`);
+            }
+            await sleep(POLL_MS);
+        }
+    }
+}
+/**
+ * Remove the lock if its owner is presumed dead.
+ * @param lockPath - the lock file.
+ * @param staleMs - age past which the lock counts as abandoned.
+ */
+async function breakStaleLock(lockPath, staleMs) {
+    try {
+        const info = await stat(lockPath);
+        if (Date.now() - info.mtimeMs > staleMs)
+            await rm(lockPath, { force: true });
+    }
+    catch {
+        // The holder released it between our failed create and this stat; the next iteration wins.
+    }
+}
+/**
+ * Wait without keeping the process alive.
+ * @param ms - milliseconds to sleep.
+ */
+function sleep(ms) {
+    return new Promise(resolve => {
+        setTimeout(resolve, ms).unref?.();
+    });
+}
+//# sourceMappingURL=lock.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-sessiongraph-sessions",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Session-log indexer for DeepSeek Harness — scans ~/.dsh/sessions, decompresses the multi-frame zstd JSONL logs and writes the sessiongraph SQLite index the store reads",
   "keywords": [
     "dsh",
@@ -49,8 +49,8 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "dsh-plugin-sessiongraph-service": "^0.1.9",
-    "dsh-plugin-sessiongraph-native": "^0.1.9"
+    "dsh-plugin-sessiongraph-service": "^0.1.11",
+    "dsh-plugin-sessiongraph-native": "^0.1.11"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.1",