dsh-plugin-codegraph-tree-sitter 0.1.7 → 0.3.0

package/lib/cache.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Parse-result cache: the extraction this package computed for each file on the previous run, so a
+ * repeat index of an unchanged workspace can skip the read, the parse, and the tree walk for every
+ * file whose content did not change.
+ *
+ * The cache is an accelerator with no authority. It is read only as a hint — anything missing,
+ * unreadable, corrupt, written by another version, or shaped unexpectedly is discarded and the file
+ * is parsed again, so losing it costs time and never correctness. That is what lets
+ * {@link readParseCache} swallow every failure and {@link writeParseCache} tolerate a workspace this
+ * process may not write to.
+ * @module dsh-plugin-codegraph-tree-sitter/cache
+ */
+import type { FileExtraction } from './extract.ts';
+import type { ExtractedFile } from './resolve.ts';
+/**
+ * Version of the extraction semantics this cache records. Bump it by hand whenever `extract.ts` (or
+ * a grammar that feeds it) starts producing a different result for the same source text: a stale
+ * entry would otherwise be reused as if it were current, and the graph would silently keep the old
+ * shape.
+ */
+export declare const EXTRACTION_CACHE_VERSION = 1;
+/** Path of the parse cache, relative to a project root. */
+export declare const EXTRACTION_CACHE_RELATIVE_PATH = ".codegraph/cache/extractions.json";
+/** One file's cached extraction, together with the identity it was computed from. */
+export interface CachedFile {
+    /** Epoch milliseconds of the file's modification time when its extraction was produced. */
+    readonly modifiedAt: number;
+    /** File size in bytes at that same moment. */
+    readonly size: number;
+    /** SHA-256 of the content the extraction was produced from, hex-encoded. */
+    readonly contentHash: string;
+    /** Line count of that content, recorded so a reused file still gets a correct span. */
+    readonly lineCount: number;
+    /** Seam language label the extraction was produced for. */
+    readonly language: string;
+    /** The extraction itself. */
+    readonly extraction: FileExtraction;
+}
+/**
+ * Load the previous run's extractions for `projectRoot`.
+ *
+ * Never throws: a cache that cannot be read, parsed, or trusted yields an empty map, which makes the
+ * caller parse everything. A single malformed entry discards the whole file — an entry is either a
+ * complete record this package wrote or evidence the document was damaged, and reasoning about
+ * partial reuse is not worth the risk of a graph built from a half-written entry.
+ * @param projectRoot - absolute path of the workspace whose cache to load.
+ * @returns the cached extractions keyed by project-relative path, empty when none can be trusted.
+ */
+export declare function readParseCache(projectRoot: string): Promise<Map<string, CachedFile>>;
+/**
+ * Record this run's extractions as the next run's cache.
+ *
+ * Written through a sibling temporary name and `rename`d into place, the same way `./schema.ts`
+ * replaces its status sidecar, so a reader never sees half a document. The temporary name is fixed
+ * rather than unique: a write interrupted before its rename is overwritten by the next attempt
+ * instead of accumulating, and a torn leftover is rejected by {@link readParseCache} at the cost of
+ * one run's reuse.
+ *
+ * A failure is swallowed on purpose. A read-only workspace, a full disk, or a locked directory must
+ * still be indexable; the cache is the optimization, never the product.
+ * @param projectRoot - absolute path of the workspace to record the cache for.
+ * @param files - every file this run produced an extraction for.
+ */
+export declare function writeParseCache(projectRoot: string, files: readonly ExtractedFile[]): Promise<void>;
+//# sourceMappingURL=cache.d.ts.map

package/lib/cache.js

@@ -0,0 +1,142 @@
+/**
+ * Parse-result cache: the extraction this package computed for each file on the previous run, so a
+ * repeat index of an unchanged workspace can skip the read, the parse, and the tree walk for every
+ * file whose content did not change.
+ *
+ * The cache is an accelerator with no authority. It is read only as a hint — anything missing,
+ * unreadable, corrupt, written by another version, or shaped unexpectedly is discarded and the file
+ * is parsed again, so losing it costs time and never correctness. That is what lets
+ * {@link readParseCache} swallow every failure and {@link writeParseCache} tolerate a workspace this
+ * process may not write to.
+ * @module dsh-plugin-codegraph-tree-sitter/cache
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * Version of the extraction semantics this cache records. Bump it by hand whenever `extract.ts` (or
+ * a grammar that feeds it) starts producing a different result for the same source text: a stale
+ * entry would otherwise be reused as if it were current, and the graph would silently keep the old
+ * shape.
+ */
+export const EXTRACTION_CACHE_VERSION = 1;
+/** Path of the parse cache, relative to a project root. */
+export const EXTRACTION_CACHE_RELATIVE_PATH = '.codegraph/cache/extractions.json';
+/**
+ * Whether `value` is a plain JSON object. Arrays are deliberately included: every caller still
+ * validates the fields it needs, and an array simply carries none of them.
+ * @param value - the parsed JSON value to test.
+ * @returns whether it is a non-null object.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Whether `value` is a usable extraction. Deliberately shallow past the four arrays: those are what
+ * `resolveWorkspace` indexes into, and the only expected producer is this package's own writer.
+ * @param value - the value to test.
+ * @returns whether it has the four collections an extraction consists of.
+ */
+function isFileExtraction(value) {
+    return isRecord(value)
+        && Array.isArray(value.definitions)
+        && Array.isArray(value.calls)
+        && Array.isArray(value.imports)
+        && Array.isArray(value.heritage);
+}
+/**
+ * Whether `value` is a complete cache entry.
+ * @param value - the value to test.
+ * @returns whether every field is present and of the type a reader will use it as.
+ */
+function isCachedFile(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.modifiedAt === 'number'
+        && typeof value.size === 'number'
+        && typeof value.contentHash === 'string'
+        && typeof value.lineCount === 'number'
+        && typeof value.language === 'string'
+        && isFileExtraction(value.extraction);
+}
+/**
+ * Load the previous run's extractions for `projectRoot`.
+ *
+ * Never throws: a cache that cannot be read, parsed, or trusted yields an empty map, which makes the
+ * caller parse everything. A single malformed entry discards the whole file — an entry is either a
+ * complete record this package wrote or evidence the document was damaged, and reasoning about
+ * partial reuse is not worth the risk of a graph built from a half-written entry.
+ * @param projectRoot - absolute path of the workspace whose cache to load.
+ * @returns the cached extractions keyed by project-relative path, empty when none can be trusted.
+ */
+export async function readParseCache(projectRoot) {
+    const cachePath = join(projectRoot, EXTRACTION_CACHE_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = await readFile(cachePath, 'utf8');
+    }
+    catch {
+        // The ordinary first run has no cache file yet; an unreadable one is the same answer to the
+        // caller — nothing to reuse — and must not fail an index that can still parse the workspace.
+        return new Map();
+    }
+    let document;
+    try {
+        document = JSON.parse(raw);
+    }
+    catch {
+        return new Map();
+    }
+    if (!isRecord(document))
+        return new Map();
+    if (document.cacheVersion !== EXTRACTION_CACHE_VERSION)
+        return new Map();
+    const entries = document.files;
+    if (!isRecord(entries))
+        return new Map();
+    const cache = new Map();
+    for (const [path, entry] of Object.entries(entries)) {
+        if (!isCachedFile(entry))
+            return new Map();
+        cache.set(path, entry);
+    }
+    return cache;
+}
+/**
+ * Record this run's extractions as the next run's cache.
+ *
+ * Written through a sibling temporary name and `rename`d into place, the same way `./schema.ts`
+ * replaces its status sidecar, so a reader never sees half a document. The temporary name is fixed
+ * rather than unique: a write interrupted before its rename is overwritten by the next attempt
+ * instead of accumulating, and a torn leftover is rejected by {@link readParseCache} at the cost of
+ * one run's reuse.
+ *
+ * A failure is swallowed on purpose. A read-only workspace, a full disk, or a locked directory must
+ * still be indexable; the cache is the optimization, never the product.
+ * @param projectRoot - absolute path of the workspace to record the cache for.
+ * @param files - every file this run produced an extraction for.
+ */
+export async function writeParseCache(projectRoot, files) {
+    const cachePath = join(projectRoot, EXTRACTION_CACHE_RELATIVE_PATH);
+    const tempPath = `${cachePath}.tmp`;
+    try {
+        const entries = {};
+        for (const file of files) {
+            entries[file.path] = {
+                modifiedAt: file.modifiedAt,
+                size: file.size,
+                contentHash: file.contentHash,
+                lineCount: file.lineCount,
+                language: file.language,
+                extraction: file.extraction,
+            };
+        }
+        const document = { cacheVersion: EXTRACTION_CACHE_VERSION, files: entries };
+        await mkdir(dirname(cachePath), { recursive: true });
+        await writeFile(tempPath, JSON.stringify(document));
+        await rename(tempPath, cachePath);
+    }
+    catch {
+        // See above: an unusable cache location only means the next run parses everything again.
+    }
+}
+//# sourceMappingURL=cache.js.map

package/lib/index.d.ts

@@ -10,6 +10,18 @@
  * runs implicitly from a query — it is a caller-initiated, potentially multi-minute operation, kept
  * out of the seam's read-only query path on purpose.
  *
+ * Watching a root runs through `ctx.fs` (see `./watcher.ts`): the package observes each in-scope
+ * directory through the host's filesystem seam rather than opening paths itself, so a workspace a
+ * backend serves from another execution world is watched where it actually lives, and a backend that
+ * cannot watch at all degrades to explicit indexing instead of failing the plugin.
+ *
+ * A workspace with no index yet is also indexed automatically the first time a session is created in
+ * it (`agent/created`), through the host's background-job registry when the composition has one. The
+ * graph is most useful on the first `codegraph` query, and a session that starts in an unindexed
+ * workspace is exactly the moment a caller would otherwise have to ask for a build by hand. This
+ * never runs synchronously inside the event dispatch: creating an agent must not wait on a
+ * multi-minute parse, and an index is an optimization, never a precondition for starting work.
+ *
  * Namespace plugin (named exports, no default export). Grammars load lazily, one per language, on
  * first sight of a matching file, and stay cached for the process — never eagerly for every grammar
  * this package ships with.
@@ -28,10 +40,12 @@ export type { ExtractedFile, GraphEdge, GraphNode, ResolvedGraph, UnresolvedRef
 export { isMinifiedName, looksMinified, measureText, MINIFIED_AVERAGE_LINE_LENGTH } from './minified.ts';
 export type { TextShape } from './minified.ts';
 export { SCHEMA_VERSION, writeGraph } from './schema.ts';
+export { EXTRACTION_CACHE_RELATIVE_PATH, EXTRACTION_CACHE_VERSION, readParseCache, writeParseCache } from './cache.ts';
+export type { CachedFile } from './cache.ts';
 export { isExcluded, walkAndExtract } from './walk.ts';
 export type { WalkConfig, WalkResult } from './walk.ts';
-export { createWatcher, nodeWatch } from './watcher.ts';
-export type { DegradeReason, WatchConfig, WatchHandle, WatchPrimitive, Watcher } from './watcher.ts';
+export { createWatcher } from './watcher.ts';
+export type { DegradeReason, WatchConfig, WatchDirEntry, WatchFileSystem, WatchTarget, Watcher, } from './watcher.ts';
 export { decideWatch, readProcVersion } from './watch-policy.ts';
 export type { WatchDecision, WatchPolicyInput } from './watch-policy.ts';
 export { detectWorktree, execGit } from './worktree.ts';
@@ -60,7 +74,7 @@ export declare const DEFAULT_MAX_FILES = 50000;
 export declare const DEFAULT_CONCURRENCY = 4;
 /** Default quiet period after the last change before a watch-triggered refresh runs. */
 export declare const DEFAULT_WATCH_DEBOUNCE_MS = 2000;
-/** Default cap on directories watched individually, on platforms without a recursive `fs.watch`. */
+/** Default cap on directories watched individually, one watch each, by the fs seam. */
 export declare const DEFAULT_MAX_WATCHED_DIRECTORIES = 4000;
 /** Plugin configuration: the indexer's identity and every deployment-varying bound on a run. */
 export interface Config {
@@ -100,6 +114,22 @@ export interface Config {
     maxFiles?: number;
     /** Files parsed concurrently (default 4). */
     concurrency?: number;
+    /**
+     * Reuse the extraction a previous run cached for every file whose content is unchanged (default
+     * true), so a repeat index — or a watch rebuild after one edit — parses only what actually changed
+     * instead of the whole workspace. The cache lives at
+     * {@link EXTRACTION_CACHE_RELATIVE_PATH} and is rewritten after each successful run. Set false to
+     * parse every file every time, at the cost of the full parse each run.
+     */
+    reuseParsedCache?: boolean;
+    /**
+     * How a cached file's unchanged content is confirmed before its extraction is reused (default
+     * `'stat'`): `stat` compares the modification time and size the cache recorded and reads nothing;
+     * `hash` re-reads the file and compares a SHA-256, which also catches a rewrite that preserved both
+     * mtime and size (a checkout restoring an older file over a newer one). Hash mode still skips the
+     * parse and the tree walk, which dominate the per-file cost.
+     */
+    cacheVerify?: 'stat' | 'hash';
     /**
      * Watch the workspace for file changes and refresh the index automatically after a successful
      * `index()` call establishes a baseline (default true). Set `watch: false` to keep indexing purely
@@ -114,16 +144,27 @@ export interface Config {
     /** Quiet period after the last change before a watch-triggered refresh runs, in ms (default 2000). */
     watchDebounceMs?: number;
     /**
-     * Hard cap on directories watched individually (default 4000). Only relevant on platforms without a
-     * recursive `fs.watch` (Linux); exceeding it degrades that root's watcher rather than covering only
-     * part of the tree.
+     * Hard cap on directories watched individually (default 4000). Watching goes through the host's
+     * filesystem seam, whose `watch` covers one directory's direct entries, so a workspace costs one
+     * watch per in-scope directory; exceeding this cap degrades that root's watcher rather than
+     * covering only part of the tree.
      */
     maxWatchedDirectories?: number;
+    /**
+     * Build a first index automatically, in the background, when a session is created in a workspace
+     * that has none (default true). A workspace is only ever auto-indexed once per process and never
+     * when its status sidecar already exists, so this cannot rebuild a graph that is already there.
+     * Set false to keep every build explicitly requested.
+     *
+     * Requires the host's `jobs` service: the build is never run synchronously inside session creation,
+     * so a composition without background jobs simply schedules nothing.
+     */
+    autoIndexOnSession?: boolean;
 }
 export declare const Config: z<Config>;
 /**
  * Register the tree-sitter indexer.
- * @param ctx - the plugin context (must inject `codegraph`).
+ * @param ctx - the plugin context (must inject `codegraph` and `fs`).
  * @param config - the resolved plugin configuration.
  */
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -10,17 +10,31 @@
  * runs implicitly from a query — it is a caller-initiated, potentially multi-minute operation, kept
  * out of the seam's read-only query path on purpose.
  *
+ * Watching a root runs through `ctx.fs` (see `./watcher.ts`): the package observes each in-scope
+ * directory through the host's filesystem seam rather than opening paths itself, so a workspace a
+ * backend serves from another execution world is watched where it actually lives, and a backend that
+ * cannot watch at all degrades to explicit indexing instead of failing the plugin.
+ *
+ * A workspace with no index yet is also indexed automatically the first time a session is created in
+ * it (`agent/created`), through the host's background-job registry when the composition has one. The
+ * graph is most useful on the first `codegraph` query, and a session that starts in an unindexed
+ * workspace is exactly the moment a caller would otherwise have to ask for a build by hand. This
+ * never runs synchronously inside the event dispatch: creating an agent must not wait on a
+ * multi-minute parse, and an index is an optimization, never a precondition for starting work.
+ *
  * Namespace plugin (named exports, no default export). Grammars load lazily, one per language, on
  * first sight of a matching file, and stay cached for the process — never eagerly for every grammar
  * this package ships with.
  * @module dsh-plugin-codegraph-tree-sitter
  */
+import { existsSync } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { CodegraphIndexerId } from 'dsh-plugin-codegraph-service';
+import { CodegraphIndexerId, INDEX_STATUS_RELATIVE_PATH } from 'dsh-plugin-codegraph-service';
 import { LANGUAGE_TABLE } from "./languages.js";
 import { walkAndExtract } from "./walk.js";
+import { writeParseCache } from "./cache.js";
 import { resolveWorkspace } from "./resolve.js";
 import { writeGraph } from "./schema.js";
 import { createWatcher } from "./watcher.js";
@@ -31,15 +45,16 @@ export { loadGitignore, matchesGitignore, parseGitignore } from "./gitignore.js"
 export { resolveWorkspace } from "./resolve.js";
 export { isMinifiedName, looksMinified, measureText, MINIFIED_AVERAGE_LINE_LENGTH } from "./minified.js";
 export { SCHEMA_VERSION, writeGraph } from "./schema.js";
+export { EXTRACTION_CACHE_RELATIVE_PATH, EXTRACTION_CACHE_VERSION, readParseCache, writeParseCache } from "./cache.js";
 export { isExcluded, walkAndExtract } from "./walk.js";
-export { createWatcher, nodeWatch } from "./watcher.js";
+export { createWatcher } from "./watcher.js";
 export { decideWatch, readProcVersion } from "./watch-policy.js";
 export { detectWorktree, execGit } from "./worktree.js";
 export { HOOK_MARKER_BEGIN, HOOK_MARKER_END, installGitHooks, uninstallGitHooks } from "./git-hooks.js";
 /** Cordis plugin name for loader diagnostics. */
 export const name = 'codegraph-tree-sitter';
 /** Services required by this plugin. */
-export const inject = ['codegraph'];
+export const inject = ['codegraph', 'fs'];
 /** Path of the on-disk graph this package writes, relative to a project root. */
 export const DATABASE_RELATIVE_PATH = '.codegraph/codegraph.db';
 /** Default branded identity this indexer reserves on the seam. */
@@ -58,7 +73,7 @@ export const DEFAULT_MAX_FILES = 50_000;
 export const DEFAULT_CONCURRENCY = 4;
 /** Default quiet period after the last change before a watch-triggered refresh runs. */
 export const DEFAULT_WATCH_DEBOUNCE_MS = 2_000;
-/** Default cap on directories watched individually, on platforms without a recursive `fs.watch`. */
+/** Default cap on directories watched individually, one watch each, by the fs seam. */
 export const DEFAULT_MAX_WATCHED_DIRECTORIES = 4_000;
 export const Config = z.object({
     indexerId: z.string().default(DEFAULT_INDEXER_ID),
@@ -69,13 +84,16 @@ export const Config = z.object({
     maxFileBytes: z.number().default(DEFAULT_MAX_FILE_BYTES),
     maxFiles: z.number().default(DEFAULT_MAX_FILES),
     concurrency: z.number().default(DEFAULT_CONCURRENCY),
+    reuseParsedCache: z.boolean().default(true),
+    cacheVerify: z.union([z.const('stat'), z.const('hash')]).default('stat'),
     watch: z.boolean().default(true),
     watchDebounceMs: z.number().default(DEFAULT_WATCH_DEBOUNCE_MS),
     maxWatchedDirectories: z.number().default(DEFAULT_MAX_WATCHED_DIRECTORIES),
+    autoIndexOnSession: z.boolean().default(true),
 });
 /**
  * Register the tree-sitter indexer.
- * @param ctx - the plugin context (must inject `codegraph`).
+ * @param ctx - the plugin context (must inject `codegraph` and `fs`).
  * @param config - the resolved plugin configuration.
  */
 export function apply(ctx, config) {
@@ -85,10 +103,25 @@ export function apply(ctx, config) {
     assertPositiveInteger('concurrency', resolved.concurrency);
     assertPositiveInteger('watchDebounceMs', resolved.watchDebounceMs);
     assertPositiveInteger('maxWatchedDirectories', resolved.maxWatchedDirectories);
+    // Watching goes through the host's filesystem seam rather than `node:fs`, so it follows the same
+    // execution world the rest of the harness reads: a remote or confined backend watches its own paths.
+    // The `fs` service is a declared dependency (see `inject`), so it is present whenever `apply` runs.
+    // It is read structurally instead of importing `@deepseek-ai/dsh-fs`: that package is not a
+    // dependency here, and its `watch` method only exists from host 0.2 onward, while this package
+    // supports older peers that have no such member to import.
+    const fileSystem = ctx.fs;
     // Keyed by project root, private to this plugin instance: never registered on `ctx`, so there is no
     // 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();
+    // `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.
+    const agentEvents = ctx;
     /** Start (or leave running) file watching for `projectRoot`, once it has a baseline to refresh. */
     function ensureWatching(projectRoot) {
         if (watchers.has(projectRoot))
@@ -115,7 +148,7 @@ export function apply(ctx, config) {
                 console.error(`codegraph-tree-sitter: file watching for "${projectRoot}" stopped permanently (${reason.code}); ` +
                     'the index will no longer refresh on its own — run codegraph_index manually to update it.');
             },
-        });
+        }, fileSystem);
         watchers.set(projectRoot, watcher);
         watcher.start();
     }
@@ -146,9 +179,92 @@ export function apply(ctx, config) {
                 watcher.stop();
             watchers.clear();
         };
+        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 ctx.codegraph.registerIndexer(indexer);
     }, 'codegraph-tree-sitter');
 }
+/** 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.
+ *
+ * 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.
+ * @param ctx - the plugin context, consulted for the optional job registry.
+ * @param autoIndexed - roots this process has already started an automatic index for.
+ * @param payload - the `agent/created` dispatch payload.
+ */
+function autoIndexOnSession(ctx, autoIndexed, 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))
+            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)))
+            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.
+        const jobs = ctx.get('jobs');
+        if (jobs === undefined)
+            return;
+        jobs.start({
+            // The registry keys a job by its owning session id, not the agent object.
+            owner: agent.id,
+            kind: AUTO_INDEX_JOB_KIND,
+            label: `codegraph auto index ${root}`,
+            run: handle => runAutoIndexJob(ctx, root, handle),
+        });
+        // 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);
+    }
+    catch (error) {
+        // The host treats a throwing listener as vetoing publication. Losing an index is a degradation,
+        // never a reason to stop a session from starting.
+        console.error(`codegraph-tree-sitter: automatic indexing for a new session failed: ${String(error)}`);
+    }
+}
+/**
+ * The producer body of one automatic indexing job.
+ *
+ * Both halves of the host's job contract are mandatory: `cancel` aborts the run, and `done` settles
+ * even on failure — a rejected `done` breaks the registry's bookkeeping and leaves the job looking
+ * stuck forever.
+ * @param ctx - the plugin context.
+ * @param root - the workspace to index.
+ * @param handle - the job's producer face, for the job's live log.
+ * @returns the job's cancellation hook and settlement promise.
+ */
+function runAutoIndexJob(ctx, root, handle) {
+    const controller = new AbortController();
+    const done = (async () => {
+        try {
+            const report = await ctx.codegraph.index(root, controller.signal);
+            handle.append(`Indexed ${root}: ${report.filesIndexed} files, ${report.nodeCount} symbols, ` +
+                `${report.edgeCount} relationships.\n`);
+            return { status: 'completed' };
+        }
+        catch (error) {
+            const message = String(error);
+            handle.append(`codegraph auto index failed for ${root}: ${message}\n`);
+            return { status: 'failed', detail: message };
+        }
+    })();
+    return { cancel: () => controller.abort(), done };
+}
 /**
  * Run one watch-triggered reindex. Always a full rebuild in this version — `runIndex` has no notion of
  * a file subset — so the watcher's own collected paths are not consulted here.
@@ -169,7 +285,7 @@ async function runSync(projectRoot, config) {
  * @returns the run's report.
  */
 async function runIndex(projectRoot, config, signal) {
-    const { files, filesSkipped, filesMinified } = await walkAndExtract(projectRoot, {
+    const { files, filesSkipped, filesMinified, filesReused } = await walkAndExtract(projectRoot, {
         exclude: config.exclude,
         respectGitignore: config.respectGitignore,
         skipMinified: config.skipMinified,
@@ -177,13 +293,21 @@ async function runIndex(projectRoot, config, signal) {
         maxFiles: config.maxFiles,
         concurrency: config.concurrency,
         languages: config.languages,
+        reuseParsedCache: config.reuseParsedCache,
+        cacheVerify: config.cacheVerify,
     }, signal);
     signal?.throwIfAborted();
     const indexedAt = Date.now();
     const graph = resolveWorkspace(files, indexedAt);
     signal?.throwIfAborted();
     const databasePath = join(projectRoot, DATABASE_RELATIVE_PATH);
-    await writeGraph(databasePath, { files, nodes: graph.nodes, edges: graph.edges, unresolved: graph.unresolved, indexedAt });
+    await writeGraph(databasePath, {
+        files, nodes: graph.nodes, edges: graph.edges, unresolved: graph.unresolved, filesMinified, indexedAt,
+    });
+    // Only after the graph is in place: the cache records the extractions this run actually committed,
+    // so a run that failed before writing its graph leaves the previous cache — and the mtimes it was
+    // built from — alone instead of vouching for a graph that was never written.
+    await writeParseCache(projectRoot, files);
     const languageCounts = new Map();
     for (const file of files)
         languageCounts.set(file.language, (languageCounts.get(file.language) ?? 0) + 1);
@@ -195,6 +319,7 @@ async function runIndex(projectRoot, config, signal) {
         filesIndexed: files.length,
         filesSkipped,
         filesMinified,
+        filesReused,
         nodeCount: graph.nodes.length,
         edgeCount: graph.edges.length,
         unresolvedCount: graph.unresolved.length,

package/lib/schema.d.ts

@@ -19,6 +19,8 @@ export interface WriteInput {
     readonly nodes: readonly GraphNode[];
     readonly edges: readonly GraphEdge[];
     readonly unresolved: readonly UnresolvedRef[];
+    /** Generated artifacts this run left out of the graph, carried into the status sidecar. */
+    readonly filesMinified: number;
     readonly indexedAt: number;
 }
 /**

package/lib/schema.js

@@ -10,10 +10,11 @@
  * naive "delete then recreate" leaves open between `CREATE TABLE` and the first `COMMIT`.
  * @module dsh-plugin-codegraph-tree-sitter/schema
  */
-import { mkdir, rename, rm } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { randomUUID } from 'node:crypto';
+import { INDEX_STATUS_RELATIVE_PATH } from 'dsh-plugin-codegraph-service';
 /** The schema version this package writes, matching the format `dsh-codegraph-sqlite` reads. */
 export const SCHEMA_VERSION = 4;
 /**
@@ -122,5 +123,29 @@ export async function writeGraph(databasePath, input) {
     // rename() only moves the main file; the temp name's own sidecars (should the driver have left any)
     // never travel with it and would otherwise linger under the temp name forever.
     await removeGraphFiles(tempPath);
+    await writeStatusFile(dirname(databasePath), {
+        indexedAt: input.indexedAt,
+        filesIndexed: input.files.length,
+        filesMinified: input.filesMinified,
+        nodeCount: input.nodes.length,
+        edgeCount: input.edges.length,
+        unresolvedCount: input.unresolved.length,
+        unresolvedLikelyInternalCount: input.unresolved.filter(ref => !ref.likelyExternal).length,
+    });
+}
+/**
+ * Write the prompt-time status sidecar beside the graph, replacing it atomically.
+ *
+ * Deliberately after the graph's own rename: a reader that sees this file can trust that the graph it
+ * summarizes is already in place, which is what lets a prompt line report "336 files, built 12s ago"
+ * without opening SQLite on every model request.
+ * @param directory - the graph's directory (`.codegraph`).
+ * @param status - this run's summary.
+ */
+async function writeStatusFile(directory, status) {
+    const target = join(directory, basename(INDEX_STATUS_RELATIVE_PATH));
+    const temp = `${target}.tmp`;
+    await writeFile(temp, JSON.stringify(status));
+    await rename(temp, target);
 }
 //# sourceMappingURL=schema.js.map

package/lib/walk.d.ts

@@ -46,6 +46,21 @@ export interface WalkConfig {
      * workspace-wide name wins" call resolution would pick between them arbitrarily.
      */
     readonly respectGitignore: boolean;
+    /**
+     * Reuse the extraction a previous run cached for every file whose content is unchanged, instead of
+     * reading and parsing it again. The cache lives under `<projectRoot>/.codegraph/cache` and is
+     * written by the indexer after a run succeeds; a missing or unusable cache simply means every file
+     * is parsed.
+     */
+    readonly reuseParsedCache: boolean;
+    /**
+     * How a cached file is confirmed unchanged before its extraction is reused. `'stat'` compares the
+     * modification time and size the cache recorded — no read at all, and enough for a watcher rebuild,
+     * whose changes always move mtime. `'hash'` reads the file and compares a SHA-256, which also
+     * catches a rewrite that preserved both mtime and size (a checkout restoring an old file) at the
+     * cost of the read it would otherwise save.
+     */
+    readonly cacheVerify: 'stat' | 'hash';
 }
 /** What the walk produced. */
 export interface WalkResult {
@@ -55,13 +70,21 @@ export interface WalkResult {
     readonly filesSkipped: number;
     /** Candidates skipped because they are generated output — see {@link WalkConfig.skipMinified}. */
     readonly filesMinified: number;
+    /**
+     * Files whose extraction came from the parse cache instead of a fresh parse. These are still
+     * present in {@link files} and still indexed — the count says how much work the cache saved, not
+     * how much of the workspace was left out.
+     */
+    readonly filesReused: number;
 }
 /**
- * Walk `projectRoot` and parse every candidate file it finds.
+ * Walk `projectRoot` and parse every candidate file it finds — or reuse the extraction a previous
+ * run cached for it.
  * @param projectRoot - absolute path of the workspace to index.
  * @param config - the walk's bounds.
  * @param signal - aborts the walk.
- * @returns the parsed files and how many candidates were skipped (over size, or past `maxFiles`).
+ * @returns the parsed files, how many candidates were skipped (over size, or past `maxFiles`), and
+ *   how many files reused a cached extraction.
  */
 export declare function walkAndExtract(projectRoot: string, config: WalkConfig, signal?: AbortSignal): Promise<WalkResult>;
 //# sourceMappingURL=walk.d.ts.map