dsh-plugin-codegraph-tree-sitter 0.5.0 → 0.5.1

package/lib/index.d.ts

@@ -79,6 +79,8 @@ export declare const DEFAULT_CONCURRENCY = 4;
 export declare const DEFAULT_WATCH_DEBOUNCE_MS = 2000;
 /** Default cap on directories watched individually, one watch each, by the fs seam. */
 export declare const DEFAULT_MAX_WATCHED_DIRECTORIES = 4000;
+/** Default age past which a session-open refreshes an existing index (ten minutes). */
+export declare const DEFAULT_AUTO_REFRESH_AFTER_MS: number;
 /** Plugin configuration: the indexer's identity and every deployment-varying bound on a run. */
 export interface Config {
     /**
@@ -174,6 +176,13 @@ export interface Config {
      * so a composition without background jobs simply schedules nothing.
      */
     autoIndexOnSession?: boolean;
+    /**
+     * How stale an existing index may be before a new session refreshes it in the background (default
+     * 600000, ten minutes). An index older than this is rebuilt on session start using the parse cache,
+     * which is milliseconds — and rebuilding is also what restarts the file watcher, since watching
+     * only ever begins after a successful index.
+     */
+    autoRefreshAfterMs?: number;
 }
 export declare const Config: z<Config>;
 /**

package/lib/index.js

@@ -27,7 +27,7 @@
  * this package ships with.
  * @module dsh-plugin-codegraph-tree-sitter
  */
-import { existsSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
@@ -83,6 +83,8 @@ export const DEFAULT_CONCURRENCY = 4;
 export const DEFAULT_WATCH_DEBOUNCE_MS = 2_000;
 /** Default cap on directories watched individually, one watch each, by the fs seam. */
 export const DEFAULT_MAX_WATCHED_DIRECTORIES = 4_000;
+/** Default age past which a session-open refreshes an existing index (ten minutes). */
+export const DEFAULT_AUTO_REFRESH_AFTER_MS = 10 * 60 * 1000;
 export const Config = z.object({
     indexerId: z.string().default(DEFAULT_INDEXER_ID),
     languages: z.array(z.string()).default([...new Set(LANGUAGE_TABLE.map(spec => spec.language))]),
@@ -99,6 +101,7 @@ export const Config = z.object({
     watchDebounceMs: z.number().default(DEFAULT_WATCH_DEBOUNCE_MS),
     maxWatchedDirectories: z.number().default(DEFAULT_MAX_WATCHED_DIRECTORIES),
     autoIndexOnSession: z.boolean().default(true),
+    autoRefreshAfterMs: z.number().default(DEFAULT_AUTO_REFRESH_AFTER_MS),
 });
 /**
  * Register the tree-sitter indexer.
@@ -124,10 +127,11 @@ export function apply(ctx, config) {
     // cross-plugin relation here for an invariant to describe — just process-local bookkeeping this
     // effect's cleanup below tears down on unload.
     const watchers = new Map();
-    // Roots this plugin instance has already started an automatic index for. The set is only a guard
-    // against a burst of agents opened on one workspace each scheduling the same rebuild; what a
-    // previous *process* indexed is recorded by the status sidecar `autoIndexOnSession` reads instead.
-    const autoIndexed = new Set();
+    // When this instance last started an automatic index, keyed by root. This is not a "already done"
+    // set: an index goes stale while the process runs, so a later session in the same workspace may
+    // legitimately trigger another refresh. The map only keeps a burst of sessions opened at once from
+    // queueing the same rebuild repeatedly; the freshness decision itself reads the status sidecar.
+    const lastAutoRun = new Map();
     // `agent/created` is typed by `@deepseek-ai/dsh-agent`'s module augmentation. Reading the event
     // through a local structural face keeps this package's host dependencies unchanged: it needs one
     // event name and one payload shape, not the whole agent package.
@@ -192,7 +196,7 @@ export function apply(ctx, config) {
         if (resolved.autoIndexOnSession) {
             // Registered inside this effect so the listener follows the plugin's lifetime: unloading the
             // plugin must stop new sessions from scheduling work this instance can no longer run.
-            yield agentEvents.on('agent/created', payload => autoIndexOnSession(ctx, autoIndexed, payload));
+            yield agentEvents.on('agent/created', payload => autoIndexOnSession(ctx, resolved, lastAutoRun, payload));
         }
         yield ctx.codegraph.registerIndexer(indexer);
     }, 'codegraph-tree-sitter');
@@ -200,30 +204,39 @@ export function apply(ctx, config) {
 /** Stable job kind of an automatic session-start index, used for retention and diagnostics. */
 const AUTO_INDEX_JOB_KIND = 'codegraph-index';
 /**
- * Index a new session's workspace in the background, when nothing has indexed it yet.
+ * Index a new session's workspace in the background — when nothing has indexed it yet, or when what
+ * is there has gone stale.
  *
  * Runs synchronously inside `agent/created` dispatch, so it must never block or throw: it only decides
  * whether a build is warranted and hands one to the host's job registry. A synchronous build here
  * would stall agent creation for the length of a parse, which is why a composition without background
  * jobs does nothing instead.
+ *
+ * Refreshing a stale index is what restarts the file watcher after a host restart: watching only
+ * begins once a successful index has established a baseline, so a workspace whose index is minutes
+ * old would otherwise stay frozen at whatever the last process left behind.
  * @param ctx - the plugin context, consulted for the optional job registry.
- * @param autoIndexed - roots this process has already started an automatic index for.
+ * @param config - the resolved plugin configuration, for the staleness threshold.
+ * @param lastAutoRun - when this instance last started an automatic index for each root.
  * @param payload - the `agent/created` dispatch payload.
  */
-function autoIndexOnSession(ctx, autoIndexed, payload) {
+function autoIndexOnSession(ctx, config, lastAutoRun, payload) {
     try {
         const agent = payload.agent;
         const root = agent?.session?.header?.cwd;
         // No workspace means no root to claim: an agent created without a `cwd` has nothing to index.
         if (agent === undefined || !root)
             return;
-        // Once per root per process. A second agent opened on the same workspace must not queue a second
-        // full rebuild of a graph the first one is already building.
-        if (autoIndexed.has(root))
+        const now = Date.now();
+        // A burst of sessions opened on one workspace must not queue the same rebuild repeatedly.
+        const previous = lastAutoRun.get(root);
+        if (previous !== undefined && now - previous < config.autoRefreshAfterMs)
             return;
-        // An existing status sidecar means a previous run already indexed this workspace. Checked before
-        // the job lookup so a composition without background jobs never pays for a filesystem probe.
-        if (existsSync(join(root, INDEX_STATUS_RELATIVE_PATH)))
+        // A fresh sidecar means a recent run is already describing this workspace; an absent, unreadable
+        // or old one means the graph is missing or behind. Checked before the job lookup so a composition
+        // without background jobs never pays for the probe.
+        const indexedAt = readStatusIndexedAt(root);
+        if (indexedAt !== undefined && now - indexedAt < config.autoRefreshAfterMs)
             return;
         // `ctx.get` rather than an `inject` entry: `jobs` is a host composition choice, and requiring it in
         // `inject` would hide this whole indexer from a profile that runs no background jobs.
@@ -239,7 +252,7 @@ function autoIndexOnSession(ctx, autoIndexed, payload) {
         });
         // Marked only after the registry accepted the job, so a transient refusal leaves the workspace
         // eligible for the next session that opens in it.
-        autoIndexed.add(root);
+        lastAutoRun.set(root, now);
     }
     catch (error) {
         // The host treats a throwing listener as vetoing publication. Losing an index is a degradation,
@@ -247,6 +260,24 @@ function autoIndexOnSession(ctx, autoIndexed, payload) {
         console.error(`codegraph-tree-sitter: automatic indexing for a new session failed: ${String(error)}`);
     }
 }
+/**
+ * When the workspace's sidecar says its index was built.
+ * @param root - the workspace root.
+ * @returns the epoch-millisecond timestamp, or `undefined` when the sidecar is absent or unreadable —
+ *   either way the graph cannot be trusted to be current.
+ */
+function readStatusIndexedAt(root) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(root, INDEX_STATUS_RELATIVE_PATH), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return undefined;
+        const indexedAt = parsed.indexedAt;
+        return typeof indexedAt === 'number' && Number.isFinite(indexedAt) ? indexedAt : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * The producer body of one automatic indexing job.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-codegraph-tree-sitter",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Self-built code-graph indexer for DeepSeek Harness — parses a workspace with web-tree-sitter and writes schema version 4 to .codegraph/codegraph.db, the same on-disk format the codegraph CLI writes, so no external indexer is required",
   "keywords": [
     "dsh",
@@ -51,7 +51,7 @@
     "@deepseek-ai/schemastery": "^3.18.1",
     "tree-sitter-wasms": "^0.1.13",
     "web-tree-sitter": "^0.25.10",
-    "dsh-plugin-codegraph-service": "^0.5.0"
+    "dsh-plugin-codegraph-service": "^0.5.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.1",