dsh-plugin-codegraph-tree-sitter 0.6.0 → 0.6.2

package/lib/index.d.ts

@@ -92,6 +92,16 @@ export declare const DEFAULT_WATCH_DEBOUNCE_MS = 2000;
 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;
+/**
+ * Default ceiling on one session-start automatic index (fifteen minutes).
+ *
+ * An automatic run nobody asked for holds its workspace in `autoIndexInFlight`, which is what keeps a
+ * burst of sessions from racing two builds over the same files. A run that never settles — a wedged
+ * parse, a backend whose abort is ignored — would therefore silence every later session in that
+ * workspace for the life of the process. The deadline is the way out: the run is aborted, the root is
+ * released, and the reason is recorded next to the graph for whoever asks next.
+ */
+export declare const DEFAULT_AUTO_INDEX_TIMEOUT_MS: number;
 /** Plugin configuration: the indexer's identity and every deployment-varying bound on a run. */
 export interface Config {
     /**
@@ -183,8 +193,10 @@ export interface Config {
      * 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.
+     * Does not need the host's `jobs` service: the build never runs synchronously inside session
+     * creation, it runs as a plain background promise, so a composition without background jobs still
+     * indexes. A failure is reported through `console.error` and recorded in
+     * `.codegraph/last-error.json` for the `status` operation to explain.
      */
     /** Cap on candidate source files a session-start scan may find before it declines to index. */
     autoIndexMaxFiles?: number;
@@ -196,6 +208,12 @@ export interface Config {
      * only ever begins after a successful index.
      */
     autoRefreshAfterMs?: number;
+    /**
+     * How long one session-start automatic index may run before it is aborted and its workspace
+     * released (default 900000, fifteen minutes). See {@link DEFAULT_AUTO_INDEX_TIMEOUT_MS} for why an
+     * unanswered run needs a deadline at all.
+     */
+    autoIndexTimeoutMs?: number;
 }
 export declare const Config: z<Config>;
 /**

package/lib/index.js

@@ -28,16 +28,15 @@
  * @module dsh-plugin-codegraph-tree-sitter
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { readdir } from 'node:fs/promises';
-import { stat } from 'node:fs/promises';
-import { join, posix } from 'node:path';
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { dirname, join, posix } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { CodegraphIndexerId, INDEX_STATUS_RELATIVE_PATH } from 'dsh-plugin-codegraph-service';
+import { CodegraphIndexerId, INDEX_FAILURE_RELATIVE_PATH, INDEX_STATUS_RELATIVE_PATH } from 'dsh-plugin-codegraph-service';
 import { LANGUAGE_TABLE, languageFor } from "./languages.js";
 import { isExcluded, walkAndExtract } from "./walk.js";
 import { writeParseCache } from "./cache.js";
 import { resolveWorkspace } from "./resolve.js";
-import { writeGraph } from "./schema.js";
+import { writeGraph, writeJsonAtomically } from "./schema.js";
 import { createWatcher } from "./watcher.js";
 import { decideWatch, readProcVersion } from "./watch-policy.js";
 export { LANGUAGE_TABLE, languageFor } from "./languages.js";
@@ -97,6 +96,16 @@ export const DEFAULT_WATCH_DEBOUNCE_MS = 2_000;
 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;
+/**
+ * Default ceiling on one session-start automatic index (fifteen minutes).
+ *
+ * An automatic run nobody asked for holds its workspace in `autoIndexInFlight`, which is what keeps a
+ * burst of sessions from racing two builds over the same files. A run that never settles — a wedged
+ * parse, a backend whose abort is ignored — would therefore silence every later session in that
+ * workspace for the life of the process. The deadline is the way out: the run is aborted, the root is
+ * released, and the reason is recorded next to the graph for whoever asks next.
+ */
+export const DEFAULT_AUTO_INDEX_TIMEOUT_MS = 15 * 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))]),
@@ -116,6 +125,7 @@ export const Config = z.object({
     autoIndexMaxFiles: z.number().default(DEFAULT_AUTO_INDEX_MAX_FILES),
     autoIndexOnSession: z.boolean().default(true),
     autoRefreshAfterMs: z.number().default(DEFAULT_AUTO_REFRESH_AFTER_MS),
+    autoIndexTimeoutMs: z.number().default(DEFAULT_AUTO_INDEX_TIMEOUT_MS),
 });
 /**
  * Register the tree-sitter indexer.
@@ -129,6 +139,7 @@ export function apply(ctx, config) {
     assertPositiveInteger('concurrency', resolved.concurrency);
     assertPositiveInteger('watchDebounceMs', resolved.watchDebounceMs);
     assertPositiveInteger('maxWatchedDirectories', resolved.maxWatchedDirectories);
+    assertPositiveInteger('autoIndexTimeoutMs', resolved.autoIndexTimeoutMs);
     // Watching and the parse cache both go through the host's filesystem seam rather than `node:fs`, so
     // they follow the same execution world the rest of the harness reads: a remote or confined backend
     // watches and caches on its own side, and the cache's read/write pass through the same policy the
@@ -146,6 +157,14 @@ export function apply(ctx, config) {
     // 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();
+    // Roots whose background run is still executing. Kept apart from `lastAutoRun`, which is a time
+    // window: a first build can outlive the window, and two builds on one root would only race the same
+    // index files.
+    const autoIndexInFlight = new Set();
+    // Controllers of the automatic runs still executing. Kept so the plugin's own unload can abort them
+    // rather than leaving a parse writing into a graph nobody is listening for any more; each run removes
+    // its own controller in `finally`.
+    const autoIndexControllers = 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.
@@ -194,15 +213,34 @@ export function apply(ctx, config) {
             }
         },
         async index(projectRoot, signal) {
-            const report = await runIndex(projectRoot, resolved, fileSystem, signal);
-            // Watching starts only after a successful index establishes the baseline it refreshes — never
-            // from a canIndex() probe or a failed run.
-            ensureWatching(projectRoot);
-            return report;
+            try {
+                const report = await runIndex(projectRoot, resolved, fileSystem, signal);
+                // Watching starts only after a successful index establishes the baseline it refreshes — never
+                // from a canIndex() probe or a failed run.
+                ensureWatching(projectRoot);
+                return report;
+            }
+            catch (error) {
+                // One entry point for every explicit build: `codegraph_index` and the `/codegraph index`
+                // command both reach the seam here. An automatic run passes through too, but records its own
+                // 'auto' label afterwards, so the final record names the path that actually asked.
+                // An abort is not a failure of the workspace: the tool's cancel and the plugin's unload both
+                // abort this signal, and a record saying "This operation was aborted" would outlive the
+                // process that wrote it and be read back as a diagnosis.
+                if (signal?.aborted !== true)
+                    await writeIndexFailure(projectRoot, 'tool', error);
+                throw error;
+            }
         },
     };
     ctx.effect(function* () {
         yield () => {
+            // Aborting goes first: a run still writing when this plugin unloads would otherwise keep the
+            // parse alive past the index it serves, and leave a graph half-written by an instance nobody
+            // asked for any more. Each run's own `finally` drops it from the set.
+            for (const controller of autoIndexControllers)
+                controller.abort();
+            autoIndexControllers.clear();
             for (const watcher of watchers.values())
                 watcher.stop();
             watchers.clear();
@@ -210,13 +248,11 @@ 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, resolved, lastAutoRun, payload, ensureWatching));
+            yield agentEvents.on('agent/created', payload => autoIndexOnSession(ctx, resolved, lastAutoRun, autoIndexInFlight, autoIndexControllers, payload, ensureWatching));
         }
         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';
 /**
  * Whether a directory is the harness's own home rather than a project checkout.
  *
@@ -235,19 +271,30 @@ function isHarnessHome(root) {
  * 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.
+ * whether a build is warranted and starts one in the background. A synchronous build here would stall
+ * agent creation for the length of a parse.
+ *
+ * The run deliberately does **not** go through the host's job registry. A registered job reports its
+ * settlement back to the owning agent: the host injects a completion notice into the next step and,
+ * under its default `wakeup` delivery, opens a turn on an idle one. An automatic index nobody asked
+ * for must not appear in the transcript or start a reply of its own, so this runs as a plain
+ * background promise. The explicit `codegraph_index` tool still registers a job — there a caller is
+ * waiting for the id.
  *
  * 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 ctx - the plugin context.
  * @param config - the resolved plugin configuration, for the staleness threshold.
  * @param lastAutoRun - when this instance last started an automatic index for each root.
+ * @param autoIndexInFlight - roots whose background run is still executing, so a slow build cannot be
+ * started twice by sessions that open past the freshness window.
+ * @param autoIndexControllers - controllers of the automatic runs this instance has in flight, so the
+ * plugin's unload can abort them.
  * @param payload - the `agent/created` dispatch payload.
+ * @param ensureWatching - starts file watching for a workspace that is already current.
  */
-function autoIndexOnSession(ctx, config, lastAutoRun, payload, ensureWatching) {
+function autoIndexOnSession(ctx, config, lastAutoRun, autoIndexInFlight, autoIndexControllers, payload, ensureWatching) {
     try {
         const agent = payload.agent;
         const root = agent?.session?.header?.cwd;
@@ -266,9 +313,12 @@ function autoIndexOnSession(ctx, config, lastAutoRun, payload, ensureWatching) {
         const previous = lastAutoRun.get(root);
         if (previous !== undefined && now - previous < config.autoRefreshAfterMs)
             return;
+        // A build already running for this root is the one the window would have deduplicated had it been
+        // slow enough to straddle it; starting a second would only race the same index files.
+        if (autoIndexInFlight.has(root))
+            return;
         // 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.
+        // or old one means the graph is missing or behind.
         const indexedAt = readStatusIndexedAt(root);
         if (indexedAt !== undefined && now - indexedAt < config.autoRefreshAfterMs) {
             // The graph is current, so no build is warranted — but watching is process-local state and
@@ -278,28 +328,98 @@ function autoIndexOnSession(ctx, config, lastAutoRun, payload, ensureWatching) {
             ensureWatching(root);
             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, config, 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.
         lastAutoRun.set(root, now);
+        autoIndexInFlight.add(root);
+        // Never rejects: a lost index is a degradation, not an error the session can act on. The in-flight
+        // entry is released by the run itself rather than here, because only that run knows whether a
+        // deadline has already replaced it — see `runAutomaticIndex`.
+        void runAutomaticIndex(ctx, root, config, autoIndexInFlight, autoIndexControllers);
     }
     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.
+        // Nothing in the block above throws for a payload-shaped agent: the only ways here are the host's
+        // own event bus or a path helper, which a unit test cannot arrange without mocking `node:fs`.
+        /* v8 ignore next */
         console.error(`codegraph-tree-sitter: automatic indexing for a new session failed: ${String(error)}`);
     }
 }
+/**
+ * Run one automatic index to completion, reporting a failure instead of propagating it.
+ *
+ * The size guard stays: parsing a workspace past `autoIndexMaxFiles` would exhaust the WASM heap and
+ * take the desktop down with it, and an automatic index is a convenience. Skipping it is a decision,
+ * not a failure, so it is logged once and the session continues untouched.
+ *
+ * A run that fails now also leaves {@link INDEX_FAILURE_RELATIVE_PATH} beside the graph, and a run that
+ * exceeds {@link Config.autoIndexTimeoutMs} is aborted and recorded as such. Both exist for the same
+ * reason: the user's only view of an automatic run is `codegraph status`, and "no index" without a
+ * reason sent them looking for a bug in their workspace rather than in the run.
+ * @param ctx - the plugin context.
+ * @param root - absolute workspace path.
+ * @param config - the resolved plugin configuration.
+ * @param autoIndexInFlight - roots whose background run is still executing; a timed-out run releases
+ * its own entry because a run that ignores its signal may never settle.
+ * @param autoIndexControllers - controllers of the automatic runs in flight, for the plugin's unload
+ * to abort.
+ */
+async function runAutomaticIndex(ctx, root, config, autoIndexInFlight, autoIndexControllers) {
+    const controller = new AbortController();
+    autoIndexControllers.add(controller);
+    const timeoutMs = config.autoIndexTimeoutMs;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        // The record is written here rather than left to the `catch` below: a run that ignores its signal
+        // may never settle, and then the failure this deadline is describing would never be recorded.
+        void writeIndexFailure(root, 'auto', `automatic index timed out after ${String(timeoutMs)}ms`);
+        // Released here for the same reason: the promise's own `finally` is exactly what a run that never
+        // settles never reaches, and every later session in this workspace would skip indexing forever.
+        autoIndexInFlight.delete(root);
+        // The controller is dropped here too: `finally` is what would normally release it, and this is the
+        // path a run that ignores its signal never reaches. Leaving it in the set would make the plugin's
+        // own unload abort a run that already gave up — and keep it alive, with the workspace it holds, for
+        // the life of the process.
+        autoIndexControllers.delete(controller);
+        controller.abort();
+    }, timeoutMs);
+    // A pending deadline must not be the reason a short-lived host process stays up.
+    timer.unref();
+    try {
+        const oversized = await exceedsAutoIndexLimit(root, config, controller.signal);
+        if (oversized !== undefined) {
+            console.error(`codegraph-tree-sitter: skipped automatic indexing of ${root}: it holds at least ${String(oversized)} ` +
+                `candidate source files, past the ${String(config.autoIndexMaxFiles)}-file session-start limit. ` +
+                'Run codegraph_index yourself if you want a graph for it.');
+            return;
+        }
+        // A successful index is what starts file watching, inside `indexer.index`.
+        await ctx.codegraph.index(root, controller.signal);
+    }
+    catch (error) {
+        // An abort that did not come from the deadline is the plugin unloading: nobody is waiting for this
+        // graph any more, so it is not a workspace failure and gets neither a log line nor a record.
+        if (controller.signal.aborted && !timedOut)
+            return;
+        // One message either way, but "timed out" and "the indexer threw" are different diagnoses: the
+        // first says the workspace is too large or too slow, the second names what actually broke.
+        const message = timedOut
+            ? `automatic index timed out after ${String(timeoutMs)}ms`
+            : describeFailure(error);
+        console.error(`codegraph-tree-sitter: automatic index for ${root} failed: ${message}`);
+        await writeIndexFailure(root, 'auto', message);
+    }
+    finally {
+        clearTimeout(timer);
+        autoIndexControllers.delete(controller);
+        // Only while this run still owns the entry. A run that passed its deadline released the root in the
+        // timer callback — that release is what lets a later session retry at all, because a run that
+        // ignores its signal may never reach this line — and deleting here by root alone would then take
+        // away whichever newer run has claimed the same workspace since.
+        if (!timedOut)
+            autoIndexInFlight.delete(root);
+    }
+}
 /**
  * How many candidate source files `root` holds, when that is past the session-start limit.
  *
@@ -365,46 +485,6 @@ function readStatusIndexedAt(root) {
         return undefined;
     }
 }
-/**
- * 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, config, handle) {
-    const controller = new AbortController();
-    const done = (async () => {
-        try {
-            const oversized = await exceedsAutoIndexLimit(root, config, controller.signal);
-            if (oversized !== undefined) {
-                // Declining here is the whole point of the check: parsing this workspace would exhaust the
-                // WASM heap and take the desktop down with it, and an automatic index is a convenience.
-                handle.append(`Skipped automatic indexing of ${root}: it holds at least ${String(oversized)} candidate ` +
-                    `source files, past the ${String(config.autoIndexMaxFiles)}-file session-start limit. ` +
-                    `Run codegraph_index yourself if you want a graph for it.\n`);
-                // `completed`, not `failed`: nothing went wrong. The guard decided this workspace is not a
-                // candidate for an automatic run, and a user reading the job list must be able to tell that
-                // apart from a build that actually broke.
-                return { status: 'completed', detail: 'skipped: workspace too large for automatic indexing' };
-            }
-            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.
@@ -415,8 +495,16 @@ function runAutoIndexJob(ctx, root, config, handle) {
  */
 async function runSync(projectRoot, config, fs) {
     const startedAt = Date.now();
-    const report = await runIndex(projectRoot, config, fs);
-    return { filesChanged: report.filesIndexed, durationMs: Date.now() - startedAt };
+    try {
+        const report = await runIndex(projectRoot, config, fs);
+        return { filesChanged: report.filesIndexed, durationMs: Date.now() - startedAt };
+    }
+    catch (error) {
+        // A watch rebuild has no caller to fail: the debounce already returned, so the only trace of a
+        // failed refresh used to be one console line in a process nobody reads interactively.
+        await writeIndexFailure(projectRoot, 'watch', error);
+        throw error;
+    }
 }
 /**
  * One indexing run: walk, parse, resolve, and write.
@@ -447,6 +535,10 @@ async function runIndex(projectRoot, config, fs, signal) {
     await writeGraph(databasePath, {
         files, nodes: graph.nodes, edges: graph.edges, unresolved: graph.unresolved, filesMinified, indexedAt,
     });
+    // The graph is back, so the recorded reason for its absence is no longer true. Cleared here rather
+    // than in `index()` because the watch path reaches this function without going through it; the
+    // deletion tolerates absence, which is the common case on a healthy workspace.
+    await rm(join(projectRoot, INDEX_FAILURE_RELATIVE_PATH), { force: true });
     // 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.
@@ -470,6 +562,48 @@ async function runIndex(projectRoot, config, fs, signal) {
         languages,
     };
 }
+/**
+ * Record why a run failed beside the graph, so a later `codegraph status` can explain an absent index.
+ *
+ * Best-effort by design: the run has already failed, and a diagnostic that cannot be written must not
+ * replace that failure with a different one. `mkdir` is recursive because `.codegraph` itself may not
+ * exist yet — a run that failed early never got as far as creating it. The record itself goes through
+ * {@link writeJsonAtomically}: `status` reads this file synchronously while another run may be
+ * rewriting it, and a reader must never see a half-written record.
+ * @param root - absolute workspace path.
+ * @param source - which path started the run.
+ * @param reason - whatever the run threw, stringified; a non-Error rejection is still worth recording.
+ */
+async function writeIndexFailure(root, source, reason) {
+    const failure = { failedAt: Date.now(), message: describeFailure(reason), source };
+    try {
+        // A root that does not exist is not a workspace: writing the record there would create the very
+        // directory the failed run reported as missing. Only the console line covers that case.
+        if (!existsSync(root))
+            return;
+        const target = join(root, INDEX_FAILURE_RELATIVE_PATH);
+        await mkdir(dirname(target), { recursive: true });
+        await writeJsonAtomically(target, failure);
+    }
+    catch (error) {
+        // A read-only workspace, or a file where `.codegraph` belongs. The caller still sees the original
+        // failure — this record was only ever a diagnostic, never a precondition for reporting anything —
+        // but a diagnostic that could not be written is itself worth one line rather than silence.
+        console.error(`codegraph-tree-sitter: could not record the indexing failure for ${root}: ${describeFailure(error)}`);
+    }
+}
+/**
+ * The text of one failed run, as a reader of the record should see it.
+ *
+ * An `Error`'s own message is the whole diagnosis; its `String()` form adds a `"Error: "` prefix that
+ * only makes the sidecar harder to read. A rejection that is not an `Error` — a provider that throws a
+ * string — is still worth recording verbatim.
+ * @param reason - whatever the run threw.
+ * @returns the message to persist.
+ */
+function describeFailure(reason) {
+    return reason instanceof Error ? reason.message : String(reason);
+}
 /** Reject a non-positive-integer config value at load, so misconfiguration fails loud. */
 function assertPositiveInteger(field, value) {
     if (!Number.isInteger(value) || value < 1) {

package/lib/resolve.js

@@ -192,14 +192,60 @@ export function resolveWorkspace(files, now) {
             updatedAt: now,
         };
         nodes.push(fileNode);
+        // `RawDefinition.key` is `row:column` with no discriminator, and two captured definitions can
+        // genuinely share one source position: C/C++'s `struct X { … } y;` captures both the enclosing
+        // `declaration`/`field_declaration` (`y`, the whole statement, which starts at the same `struct`
+        // keyword) and the nested `struct_specifier` (`X`) there. The second and later definition with the
+        // same base id therefore gets a `#N` suffix; the first keeps the bare id, so a file whose keys are
+        // all distinct — i.e. essentially every file outside that C/C++ shape — resolves to exactly the
+        // same ids (and therefore the same graph) it did before.
+        const idCounts = new Map();
+        // `keyToId` stays last-write-wins: duplicate keys can only ever be *nested* (a source position
+        // identifies exactly one node, so two definitions sharing one must be ancestor and descendant),
+        // and the definitions are in DFS pre-order, so the last write is the innermost declaration — which
+        // is what a call or heritage reference inside it must attribute to.
         const keyToId = new Map();
+        // Parent resolution deliberately does NOT go through `keyToId`: with a shared key, the map's last
+        // write would make the inner definition its own `contains` parent (a self-loop on a node with
+        // itself as target). The open definitions form a stack instead, so the outer and inner
+        // definitions of one position are two distinct nodes and the nesting is what it is in the source.
+        const openStack = [];
         const fileNodes = [];
         for (const def of file.extraction.definitions) {
             const qualifiedName = def.container.length === 0
                 ? `${file.path}::${def.name}`
                 : `${file.path}::${[...def.container, def.name].join('.')}`;
-            const nodeId = `${file.path}:${def.startLine}:${def.startColumn}`;
+            const baseId = `${file.path}:${def.startLine}:${def.startColumn}`;
+            const occurrence = (idCounts.get(baseId) ?? 0) + 1;
+            idCounts.set(baseId, occurrence);
+            const nodeId = occurrence === 1 ? baseId : `${baseId}#${occurrence}`;
             keyToId.set(def.key, nodeId);
+            // A top-level definition's parent is the file node, and it also closes every definition still
+            // open at that point. Otherwise pop until the definition named by `parentKey` is on top; an
+            // unresolvable `parentKey` (a shape `extract.ts` does not produce, since a parent key is taken
+            // from the live container stack) falls back to the file node rather than throwing.
+            let parentId = id;
+            if (def.parentKey === null) {
+                openStack.length = 0;
+            }
+            else {
+                while (openStack.length > 0 && openStack[openStack.length - 1]?.key !== def.parentKey)
+                    openStack.pop();
+                const parent = openStack[openStack.length - 1];
+                if (parent === undefined) {
+                    // The file node is a true ancestor, so the edge stays usable — but a `parentKey` that is not
+                    // open means extraction and resolution disagree, and silently reshaping that into a
+                    // plausible-looking edge is how a nesting bug survives unnoticed. Record it with the exact
+                    // position, which is what a reader needs to find the declaration.
+                    console.error(`codegraph-tree-sitter: ${file.path}:${String(def.startLine)}:${String(def.startColumn)} `
+                        + `${def.name} names a parentKey (${String(def.parentKey)}) that is not open; `
+                        + 'falling back to the file node');
+                }
+                else {
+                    parentId = parent.id;
+                }
+            }
+            openStack.push({ key: def.key, id: nodeId });
             fileNodes.push({
                 id: nodeId,
                 kind: def.kind,
@@ -217,14 +263,11 @@ export function resolveWorkspace(files, now) {
                 decorators: def.decorators,
                 updatedAt: now,
             });
+            edges.push({ source: parentId, target: nodeId, kind: 'contains', provenance: 'tree-sitter' });
         }
         nodes.push(...fileNodes);
         nodesByFile.set(file.path, fileNodes);
         defIdByKey.set(file.path, keyToId);
-        for (const def of file.extraction.definitions) {
-            const source = def.parentKey === null ? id : mustGet(keyToId, def.parentKey);
-            edges.push({ source, target: mustGet(keyToId, def.key), kind: 'contains', provenance: 'tree-sitter' });
-        }
     }
     const nameIndex = buildNameIndex(nodesByFile);
     const typeNameIndex = buildTypeNameIndex(nodesByFile);

package/lib/schema.d.ts

@@ -34,4 +34,18 @@ export interface WriteInput {
  * @param input - the run's resolved graph and per-file metadata.
  */
 export declare function writeGraph(databasePath: string, input: WriteInput): Promise<void>;
+/**
+ * Replace one JSON document atomically: serialize to a unique staging file beside `target`, then
+ * `rename` it over `target`.
+ *
+ * The staging name is unique (`pid` plus a random UUID) and lives in the target's own directory, for
+ * two reasons. Two runs on one workspace are allowed to overlap — a session-start build and an
+ * explicit `codegraph_index`, or a watcher rebuild — and a shared fixed-name `.tmp` makes the loser's
+ * `rename` fail with ENOENT after the winner moved it, turning a harmless duplicate run into a failed
+ * call. Same-directory is what makes the `rename` atomic: it is a metadata operation on one
+ * filesystem, so a reader sees either the previous document or the new one, never a half-written one.
+ * @param target - absolute path of the file to replace.
+ * @param value - the value to serialize as JSON.
+ */
+export declare function writeJsonAtomically(target: string, value: unknown): Promise<void>;
 //# sourceMappingURL=schema.d.ts.map

package/lib/schema.js

@@ -133,6 +133,24 @@ export async function writeGraph(databasePath, input) {
         unresolvedLikelyInternalCount: input.unresolved.filter(ref => !ref.likelyExternal).length,
     });
 }
+/**
+ * Replace one JSON document atomically: serialize to a unique staging file beside `target`, then
+ * `rename` it over `target`.
+ *
+ * The staging name is unique (`pid` plus a random UUID) and lives in the target's own directory, for
+ * two reasons. Two runs on one workspace are allowed to overlap — a session-start build and an
+ * explicit `codegraph_index`, or a watcher rebuild — and a shared fixed-name `.tmp` makes the loser's
+ * `rename` fail with ENOENT after the winner moved it, turning a harmless duplicate run into a failed
+ * call. Same-directory is what makes the `rename` atomic: it is a metadata operation on one
+ * filesystem, so a reader sees either the previous document or the new one, never a half-written one.
+ * @param target - absolute path of the file to replace.
+ * @param value - the value to serialize as JSON.
+ */
+export async function writeJsonAtomically(target, value) {
+    const temp = `${target}.tmp-${process.pid}-${randomUUID()}`;
+    await writeFile(temp, JSON.stringify(value));
+    await rename(temp, target);
+}
 /**
  * Write the prompt-time status sidecar beside the graph, replacing it atomically.
  *
@@ -143,9 +161,6 @@ export async function writeGraph(databasePath, input) {
  * @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);
+    await writeJsonAtomically(join(directory, basename(INDEX_STATUS_RELATIVE_PATH)), status);
 }
 //# sourceMappingURL=schema.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-codegraph-tree-sitter",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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.6.0"
+    "dsh-plugin-codegraph-service": "^0.6.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.1",
@@ -59,11 +59,11 @@
     "@deepseek-ai/dsh-invariants": ">=0.1.0-rc.6"
   },
   "optionalDependencies": {
-    "dsh-plugin-codegraph-indexer-darwin-arm64": "0.6.0",
-    "dsh-plugin-codegraph-indexer-darwin-x64": "0.6.0",
-    "dsh-plugin-codegraph-indexer-linux-x64-gnu": "0.6.0",
-    "dsh-plugin-codegraph-indexer-linux-arm64-gnu": "0.6.0",
-    "dsh-plugin-codegraph-indexer-win32-x64-msvc": "0.6.0"
+    "dsh-plugin-codegraph-indexer-darwin-arm64": "0.6.2",
+    "dsh-plugin-codegraph-indexer-darwin-x64": "0.6.2",
+    "dsh-plugin-codegraph-indexer-linux-x64-gnu": "0.6.2",
+    "dsh-plugin-codegraph-indexer-linux-arm64-gnu": "0.6.2",
+    "dsh-plugin-codegraph-indexer-win32-x64-msvc": "0.6.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",