dsh-plugin-sessiongraph-sessions 0.1.8 → 0.1.10

package/lib/index.d.ts

@@ -14,10 +14,11 @@
  * rebuilds every log into a temporary file that replaces the old index atomically. A single bad log
  * is reported in `failed` and never aborts the run.
  *
- * Every session creation also refreshes an **existing** index in the background (`agent/created`,
- * `autoIndex`): a machine that already has one stays fresh without the model remembering to ask. A
- * missing index is deliberately left alone — the first build reads every log on the machine and is
- * the caller's explicit decision (`sessiongraph_index`), not something to trigger on a session start.
+ * Every session creation also does indexing work in the background (`agent/created`, `autoIndex`):
+ * an existing index is refreshed incrementally, and a missing one is built from scratch (`autoBuild`,
+ * default true) so a fresh install becomes searchable without the user running anything. Both runs
+ * go through the host's job registry and never block session creation. `autoBuild: false` restores
+ * the stricter behaviour where nothing is indexed until the caller asks for it.
  *
  * Sessions the host still holds in memory (`ctx.sessionQuery`) are indexed as well, in a second pass
  * after the file-path transaction commits: a conversation that is still running has no log on disk
@@ -98,10 +99,23 @@ export interface Config {
     /** Logs larger than this are skipped and reported in `failed` (default 67108864). */
     maxFileBytes?: number;
     /**
-     * Refresh an existing index in the background whenever a session is created (default true). A
-     * machine with no index yet is skipped on purpose — see {@link DEFAULT_INDEX_ROOT}.
+     * Do indexing work in the background whenever a session is created (default true). With no index
+     * yet this builds the first one; with one already present it refreshes incrementally.
      */
     autoIndex?: boolean;
+    /**
+     * Build the very first index automatically in the background when a session starts (default
+     * true). The first build reads every log on the machine and can take seconds to minutes, so it
+     * runs as a host background job and never blocks session creation. Set false to require an
+     * 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

@@ -14,10 +14,11 @@
  * rebuilds every log into a temporary file that replaces the old index atomically. A single bad log
  * is reported in `failed` and never aborts the run.
  *
- * Every session creation also refreshes an **existing** index in the background (`agent/created`,
- * `autoIndex`): a machine that already has one stays fresh without the model remembering to ask. A
- * missing index is deliberately left alone — the first build reads every log on the machine and is
- * the caller's explicit decision (`sessiongraph_index`), not something to trigger on a session start.
+ * Every session creation also does indexing work in the background (`agent/created`, `autoIndex`):
+ * an existing index is refreshed incrementally, and a missing one is built from scratch (`autoBuild`,
+ * default true) so a fresh install becomes searchable without the user running anything. Both runs
+ * go through the host's job registry and never block session creation. `autoBuild: false` restores
+ * the stricter behaviour where nothing is indexed until the caller asks for it.
  *
  * Sessions the host still holds in memory (`ctx.sessionQuery`) are indexed as well, in a second pass
  * after the file-path transaction commits: a conversation that is still running has no log on disk
@@ -39,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";
@@ -88,6 +90,8 @@ export const Config = z.object({
     toolCallChars: z.number().default(DEFAULT_TOOL_CALL_CHARS),
     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),
@@ -182,9 +186,11 @@ function scheduleAutoIndex(ctx, config, autoIndexed, payload) {
         // Once per root per process: a burst of session creations must not queue a burst of index runs.
         if (autoIndexed.has(indexRoot))
             return;
-        // Only an index that already exists is refreshed: the first build reads every log on the
-        // machine, and that is the caller's explicit decision, not something a session start triggers.
-        if (!hasExistingIndex(indexRoot))
+        // A first build reads every log on the machine and can take a while, so it stays a background
+        // job like the incremental refresh. `autoBuild: false` restores the stricter behaviour where
+        // nothing becomes searchable until someone asks for it.
+        const existing = hasExistingIndex(indexRoot);
+        if (!existing && !config.autoBuild)
             return;
         // `ctx.get` rather than an `inject` entry: background jobs are a host composition choice, and
         // requiring the service would hide this whole indexer from a profile that runs none.
@@ -195,7 +201,9 @@ function scheduleAutoIndex(ctx, config, autoIndexed, payload) {
             // The registry keys a job by its owning session id, not the agent object.
             owner: agent.id,
             kind: AUTO_INDEX_JOB_KIND,
-            label: `sessiongraph refresh for ${workspace}`,
+            label: existing
+                ? `sessiongraph refresh for ${workspace}`
+                : `sessiongraph first build for ${workspace}`,
             run: handle => runIndexJob(indexRoot, {}, config, handle),
         });
         // Marked only after the registry accepted the job, so a refusal leaves the root eligible for
@@ -535,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.8",
+  "version": "0.1.10",
   "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.8",
-    "dsh-plugin-sessiongraph-native": "^0.1.8"
+    "dsh-plugin-sessiongraph-service": "^0.1.10",
+    "dsh-plugin-sessiongraph-native": "^0.1.10"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.1",