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

package/lib/cache.d.ts

@@ -3,6 +3,12 @@
  * 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 document is read and written through the host's filesystem seam (`ctx.fs`), named here as
+ * the structural {@link ParseCacheFileSystem} port — the same discipline `./watcher.ts` applies to
+ * `WatchFileSystem`. The seam is what DSH's read policy and sandbox actually gate, and it is the only
+ * way this file can follow a backend whose files live in another execution world; a path-based
+ * `node:fs` write would silently land somewhere the graph's readers are not looking.
+ *
  * 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
@@ -21,6 +27,67 @@ import type { ExtractedFile } from './resolve.ts';
 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 resolved filesystem target — the opaque identity `ctx.fs` hands back and every other call
+ * takes. Only `targetKey` is read here: the module never parses it, and a remote backend's key is as
+ * valid as a local path.
+ */
+export interface CacheTarget {
+    /** Opaque backend identity of the target. */
+    readonly targetKey: string;
+}
+/**
+ * The metadata this module consumes from a target, as `ctx.fs.stat` reports it.
+ *
+ * Deliberately narrower than the seam's own metadata: a cache document has no version to guard and no
+ * mtime to compare (the files it describes carry their own identity inside the document), so presence
+ * and kind are the whole decision. Naming the one field it reads rather than the whole `FsInfo` is
+ * also what keeps this port assignable to the host's `FileSystem`.
+ */
+export interface CacheTargetInfo {
+    /** Whether the target is a regular file, a directory, or something else. */
+    readonly type: 'file' | 'directory' | 'other';
+}
+/**
+ * The narrow slice of `ctx.fs` the parse cache consumes.
+ *
+ * Deliberately structural rather than an import of the host's `FileSystem`: the tree-sitter package
+ * declares no dependency on `@deepseek-ai/dsh-fs`, so it names the four calls it uses instead —
+ * resolve a path, ask whether it exists, read it, replace it. That keeps this module compilable and
+ * loadable across the peer range the package supports, and keeps the port small enough that a test
+ * double is a few lines.
+ */
+export interface ParseCacheFileSystem {
+    /**
+     * Resolve a path into a stable backend target.
+     * @param path - the path to resolve; absolute paths are what this module passes.
+     * @param opts - optional resolution base for a relative path.
+     * @returns the resolved target, resolvable even before the file exists.
+     */
+    resolve(path: string, opts?: {
+        readonly cwd?: string;
+    }): Promise<CacheTarget>;
+    /**
+     * Report a target's metadata.
+     * @param target - the resolved target to probe.
+     * @returns its metadata, or undefined when nothing is there.
+     */
+    stat(target: CacheTarget): Promise<CacheTargetInfo | undefined>;
+    /**
+     * Read the whole file as decoded text.
+     * @param target - the resolved target to read.
+     * @returns the file's content.
+     */
+    readText(target: CacheTarget): Promise<string>;
+    /**
+     * Atomically create or replace the whole file. The outcome is ignored: this module only needs the
+     * write to have happened, and the seam's guards are not this call's business.
+     * @param target - the resolved target to write.
+     * @param content - the full new content.
+     * @returns the publication outcome, whose details this module does not read.
+     */
+    writeText(target: CacheTarget, content: string): Promise<unknown>;
+}
 /** 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. */
@@ -39,27 +106,37 @@ export interface CachedFile {
 /**
  * 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.
+ * Never throws: a cache that cannot be resolved, 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 fs - the filesystem seam to resolve, probe, and read through.
  * @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>>;
+export declare function readParseCache(fs: ParseCacheFileSystem, 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.
+ * Publication is the backend's contract, not this module's. `writeText` is specified as an atomic
+ * create-or-replace — the local backend stages a temporary sibling and renames it into place — so the
+ * previous implementation's own `.tmp` write plus `rename` is gone. That is not a shortcut taken for
+ * its own sake: a path-based rename has no meaning for a backend whose files live in another
+ * execution world, which is exactly the backend this module moved onto the seam to follow. The seam
+ * also has no `mkdir`, so this write relies on the backend creating a missing parent directory (the
+ * local one does, before staging); a backend that did not would make this write fail, which the
+ * swallow below already treats as "no cache this run".
+ *
+ * Should a backend ever publish non-atomically, or a crash interrupt it, the worst case is a torn
+ * document: {@link readParseCache} rejects it as unparseable and the next run parses everything.
+ * Losing one run's reuse is the acceptable side of that trade, because the cache has no authority to
+ * lose — a corrupted graph would be the unacceptable one, and no torn cache can produce it.
  *
  * 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 fs - the filesystem seam to resolve and write through.
  * @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>;
+export declare function writeParseCache(fs: ParseCacheFileSystem, projectRoot: string, files: readonly ExtractedFile[]): Promise<void>;
 //# sourceMappingURL=cache.d.ts.map

package/lib/cache.js

@@ -3,6 +3,12 @@
  * 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 document is read and written through the host's filesystem seam (`ctx.fs`), named here as
+ * the structural {@link ParseCacheFileSystem} port — the same discipline `./watcher.ts` applies to
+ * `WatchFileSystem`. The seam is what DSH's read policy and sandbox actually gate, and it is the only
+ * way this file can follow a backend whose files live in another execution world; a path-based
+ * `node:fs` write would silently land somewhere the graph's readers are not looking.
+ *
  * 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
@@ -10,8 +16,7 @@
  * 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';
+import { 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
@@ -61,22 +66,31 @@ function isCachedFile(value) {
 /**
  * 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.
+ * Never throws: a cache that cannot be resolved, 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 fs - the filesystem seam to resolve, probe, and read through.
  * @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) {
+export async function readParseCache(fs, projectRoot) {
     const cachePath = join(projectRoot, EXTRACTION_CACHE_RELATIVE_PATH);
     let raw;
     try {
-        raw = await readFile(cachePath, 'utf8');
+        const target = await fs.resolve(cachePath);
+        // The seam reports an absent target as `undefined` from `stat` but as a thrown error from
+        // `readText`. Probing first keeps the ordinary first run — no cache document written yet — a plain
+        // return instead of exception control flow, and rejects a directory or special file that took the
+        // document's place before asking a reader to decode it.
+        const info = await fs.stat(target);
+        if (info === undefined || info.type !== 'file')
+            return new Map();
+        raw = await fs.readText(target);
     }
     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.
+        // An unreadable document is the same answer to the caller as an absent one — nothing to reuse —
+        // and must not fail an index that can still parse the workspace.
         return new Map();
     }
     let document;
@@ -104,20 +118,27 @@ export async function readParseCache(projectRoot) {
 /**
  * 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.
+ * Publication is the backend's contract, not this module's. `writeText` is specified as an atomic
+ * create-or-replace — the local backend stages a temporary sibling and renames it into place — so the
+ * previous implementation's own `.tmp` write plus `rename` is gone. That is not a shortcut taken for
+ * its own sake: a path-based rename has no meaning for a backend whose files live in another
+ * execution world, which is exactly the backend this module moved onto the seam to follow. The seam
+ * also has no `mkdir`, so this write relies on the backend creating a missing parent directory (the
+ * local one does, before staging); a backend that did not would make this write fail, which the
+ * swallow below already treats as "no cache this run".
+ *
+ * Should a backend ever publish non-atomically, or a crash interrupt it, the worst case is a torn
+ * document: {@link readParseCache} rejects it as unparseable and the next run parses everything.
+ * Losing one run's reuse is the acceptable side of that trade, because the cache has no authority to
+ * lose — a corrupted graph would be the unacceptable one, and no torn cache can produce it.
  *
  * 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 fs - the filesystem seam to resolve and write through.
  * @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`;
+export async function writeParseCache(fs, projectRoot, files) {
     try {
         const entries = {};
         for (const file of files) {
@@ -131,9 +152,8 @@ export async function writeParseCache(projectRoot, files) {
             };
         }
         const document = { cacheVersion: EXTRACTION_CACHE_VERSION, files: entries };
-        await mkdir(dirname(cachePath), { recursive: true });
-        await writeFile(tempPath, JSON.stringify(document));
-        await rename(tempPath, cachePath);
+        const target = await fs.resolve(join(projectRoot, EXTRACTION_CACHE_RELATIVE_PATH));
+        await fs.writeText(target, JSON.stringify(document));
     }
     catch {
         // See above: an unusable cache location only means the next run parses everything again.

package/lib/index.d.ts

@@ -41,7 +41,7 @@ export { isMinifiedName, looksMinified, measureText, MINIFIED_AVERAGE_LINE_LENGT
 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 type { CachedFile, CacheTarget, CacheTargetInfo, ParseCacheFileSystem } from './cache.ts';
 export { isExcluded, walkAndExtract } from './walk.ts';
 export type { WalkConfig, WalkResult } from './walk.ts';
 export { createWatcher } from './watcher.ts';
@@ -49,7 +49,7 @@ export type { DegradeReason, WatchConfig, WatchDirEntry, WatchFileSystem, WatchT
 export { decideWatch, readProcVersion } from './watch-policy.ts';
 export type { WatchDecision, WatchPolicyInput } from './watch-policy.ts';
 export { detectWorktree, execGit } from './worktree.ts';
-export type { GitExec, WorktreeInfo } from './worktree.ts';
+export type { GitExec, GitSpawnHandle, GitSpawnOutcome, GitSpawnPort, GitSpawnReader, GitSpawnSpec, WorktreeInfo, } from './worktree.ts';
 export { HOOK_MARKER_BEGIN, HOOK_MARKER_END, installGitHooks, uninstallGitHooks } from './git-hooks.ts';
 export type { GitHooksOptions } from './git-hooks.ts';
 /** Cordis plugin name for loader diagnostics. */

package/lib/index.js

@@ -49,6 +49,10 @@ export { EXTRACTION_CACHE_RELATIVE_PATH, EXTRACTION_CACHE_VERSION, readParseCach
 export { isExcluded, walkAndExtract } from "./walk.js";
 export { createWatcher } from "./watcher.js";
 export { decideWatch, readProcVersion } from "./watch-policy.js";
+// Git diagnostics stay library functions rather than plugin wiring: nothing in `apply` runs git, so
+// `inject` deliberately omits `subprocess` — requiring it would hide this whole indexer from a
+// composition that provides none. A caller that wants worktree diagnostics passes `ctx.subprocess`
+// to `execGit` itself; installing the git hooks touches no subprocess at all.
 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. */
@@ -103,12 +107,13 @@ 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.
+    // 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
+    // graph's readers do. The `fs` service is a declared dependency (see `inject`), so it is present
+    // whenever `apply` runs. Both ports are 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
@@ -141,7 +146,7 @@ export function apply(ctx, config) {
             respectGitignore: resolved.respectGitignore,
             debounceMs: resolved.watchDebounceMs,
             maxWatchedDirectories: resolved.maxWatchedDirectories,
-            sync: () => runSync(projectRoot, resolved),
+            sync: () => runSync(projectRoot, resolved, fileSystem),
             // No diagnostics service is wired into this package's dependencies; this is the floor for
             // "degradation must be visible" until one is, per NOTES.local.md.
             onDegraded: (reason) => {
@@ -166,7 +171,7 @@ export function apply(ctx, config) {
             }
         },
         async index(projectRoot, signal) {
-            const report = await runIndex(projectRoot, resolved, 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);
@@ -270,21 +275,23 @@ function runAutoIndexJob(ctx, root, handle) {
  * a file subset — so the watcher's own collected paths are not consulted here.
  * @param projectRoot - absolute path of the workspace to refresh.
  * @param config - the resolved plugin configuration.
+ * @param fs - the filesystem seam the parse cache is read and written through.
  * @returns how many files the rebuild indexed, and how long it took.
  */
-async function runSync(projectRoot, config) {
+async function runSync(projectRoot, config, fs) {
     const startedAt = Date.now();
-    const report = await runIndex(projectRoot, config);
+    const report = await runIndex(projectRoot, config, fs);
     return { filesChanged: report.filesIndexed, durationMs: Date.now() - startedAt };
 }
 /**
  * One indexing run: walk, parse, resolve, and write.
  * @param projectRoot - absolute path of the workspace to index.
  * @param config - the resolved plugin configuration.
+ * @param fs - the filesystem seam the parse cache is read and written through.
  * @param signal - aborts the run.
  * @returns the run's report.
  */
-async function runIndex(projectRoot, config, signal) {
+async function runIndex(projectRoot, config, fs, signal) {
     const { files, filesSkipped, filesMinified, filesReused } = await walkAndExtract(projectRoot, {
         exclude: config.exclude,
         respectGitignore: config.respectGitignore,
@@ -295,7 +302,7 @@ async function runIndex(projectRoot, config, signal) {
         languages: config.languages,
         reuseParsedCache: config.reuseParsedCache,
         cacheVerify: config.cacheVerify,
-    }, signal);
+    }, fs, signal);
     signal?.throwIfAborted();
     const indexedAt = Date.now();
     const graph = resolveWorkspace(files, indexedAt);
@@ -307,7 +314,7 @@ async function runIndex(projectRoot, config, signal) {
     // 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);
+    await writeParseCache(fs, projectRoot, files);
     const languageCounts = new Map();
     for (const file of files)
         languageCounts.set(file.language, (languageCounts.get(file.language) ?? 0) + 1);

package/lib/walk.d.ts

@@ -8,6 +8,7 @@
  * package's `Config` exposes.
  * @module dsh-plugin-codegraph-tree-sitter/walk
  */
+import type { ParseCacheFileSystem } from './cache.ts';
 import type { GitignoreRule } from './gitignore.ts';
 import type { ExtractedFile } from './resolve.ts';
 /**
@@ -48,9 +49,10 @@ export interface WalkConfig {
     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.
+     * reading and parsing it again. The cache lives under `<projectRoot>/.codegraph/cache`, is read
+     * through the host's filesystem seam (the `fs` argument to {@link walkAndExtract}), and is written
+     * by the indexer after a run succeeds; a missing or unusable cache simply means every file is
+     * parsed.
      */
     readonly reuseParsedCache: boolean;
     /**
@@ -80,11 +82,18 @@ export interface WalkResult {
 /**
  * Walk `projectRoot` and parse every candidate file it finds — or reuse the extraction a previous
  * run cached for it.
+ *
+ * `fs` is a parameter rather than a `WalkConfig` field on purpose: the walk's own directory scan and
+ * file reads still go straight to `node:fs` — they compare the mtime and size it stats itself, which
+ * is the identity every cache entry is recorded under — and the only seam-mediated work here is the
+ * parse cache's read. A capability is not a bound, so it does not belong in the config that mirrors
+ * this package's `Config`.
  * @param projectRoot - absolute path of the workspace to index.
  * @param config - the walk's bounds.
+ * @param fs - the filesystem seam the parse cache is read through.
  * @param signal - aborts the walk.
  * @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>;
+export declare function walkAndExtract(projectRoot: string, config: WalkConfig, fs: ParseCacheFileSystem, signal?: AbortSignal): Promise<WalkResult>;
 //# sourceMappingURL=walk.d.ts.map

package/lib/walk.js

@@ -190,15 +190,22 @@ async function mapWithConcurrency(items, concurrency, task) {
 /**
  * Walk `projectRoot` and parse every candidate file it finds — or reuse the extraction a previous
  * run cached for it.
+ *
+ * `fs` is a parameter rather than a `WalkConfig` field on purpose: the walk's own directory scan and
+ * file reads still go straight to `node:fs` — they compare the mtime and size it stats itself, which
+ * is the identity every cache entry is recorded under — and the only seam-mediated work here is the
+ * parse cache's read. A capability is not a bound, so it does not belong in the config that mirrors
+ * this package's `Config`.
  * @param projectRoot - absolute path of the workspace to index.
  * @param config - the walk's bounds.
+ * @param fs - the filesystem seam the parse cache is read through.
  * @param signal - aborts the walk.
  * @returns the parsed files, how many candidates were skipped (over size, or past `maxFiles`), and
  *   how many files reused a cached extraction.
  */
-export async function walkAndExtract(projectRoot, config, signal) {
+export async function walkAndExtract(projectRoot, config, fs, signal) {
     const { candidates, overflow } = await discover(projectRoot, config, signal);
-    const cache = config.reuseParsedCache ? await readParseCache(projectRoot) : new Map();
+    const cache = config.reuseParsedCache ? await readParseCache(fs, projectRoot) : new Map();
     const parsed = await mapWithConcurrency(candidates, config.concurrency, candidate => parseCandidate(candidate, config, cache, signal));
     const files = [];
     let filesSkipped = overflow;

package/lib/worktree.d.ts

@@ -9,15 +9,115 @@
  * never looks outside the `projectRoot` it was given. If a caller ever *does* end up pointed at the
  * wrong root, the bug is almost certainly in how the host resolves a session's working directory, not
  * in this package — this module exists to make that distinction diagnosable, not to route around it.
+ *
+ * Git runs through the host's subprocess seam (`ctx.subprocess`) instead of `node:child_process`.
+ * That seam is where executable resolution, environment scrubbing, bounded output collection,
+ * termination grace, timeouts, and sandbox containment live: a child started here inherits a parent
+ * environment with ambient credentials and `DSH_*` deployment facts removed, its stdout/stderr are
+ * capped before they can exhaust this process, and the host may satisfy the request by running the
+ * command in another execution world entirely. `execFileSync` would bypass all of that, so the module
+ * takes the seam as a structural port and the caller supplies `execGit(ctx.subprocess)`.
  * @module dsh-plugin-codegraph-tree-sitter/worktree
  */
+/** Exit facts a spawned child settles with, as `handle.done` reports them. */
+export interface GitSpawnOutcome {
+    /** Exit status of the direct child; `null` when a signal terminated it instead. */
+    readonly exitCode: number | null;
+    /** Name of the signal that terminated the child; `null` when it exited on its own. */
+    readonly signal: string | null;
+}
+/** One collected output stream, read in whole-stream byte offsets. */
+export interface GitSpawnReader {
+    /**
+     * Read everything the collector still retains from `fromByte` onward.
+     * @param fromByte - whole-stream byte offset to resume from; `0` for a first read.
+     * @returns the collected text, and whether bytes before `fromByte` had already been dropped.
+     */
+    readFrom(fromByte: number): {
+        readonly text: string;
+        readonly lossy: boolean;
+    };
+}
+/** One live child returned by {@link GitSpawnPort.spawn}. */
+export interface GitSpawnHandle {
+    /**
+     * Settles with the direct child's exit facts. Rejects when the child never started — a missing
+     * executable, a refused spawn, or a failing provider — and carries no collected output then.
+     */
+    readonly done: Promise<GitSpawnOutcome>;
+    /** Buffered output, one entry per stream the spec asked to have collected. */
+    readonly collected: {
+        /** Collected stdout, present because {@link GitSpawnSpec.stdio} always asks for it. */
+        readonly stdout?: GitSpawnReader;
+        /** Collected stderr, present because {@link GitSpawnSpec.stdio} always asks for it. */
+        readonly stderr?: GitSpawnReader;
+    };
+}
+/** How one child is launched: fully explicit, never shell-interpreted. */
+export interface GitSpawnSpec {
+    /** Program and arguments; `argv[0]` is the program itself, never a shell command line. */
+    readonly argv: readonly string[];
+    /** Working directory the child starts in. */
+    readonly cwd: string;
+    /** One disposition per standard stream. */
+    readonly stdio: {
+        /** stdin stays closed: none of these probes wants input, and a prompt would hang the run. */
+        readonly stdin: 'ignore';
+        /** Collect stdout, retaining at most this many bytes. */
+        readonly stdout: {
+            readonly maxBytes: number;
+        };
+        /** Collect stderr, retaining at most this many bytes. */
+        readonly stderr: {
+            readonly maxBytes: number;
+        };
+    };
+    /** Milliseconds the host may take to terminate the child once termination has started. */
+    readonly graceMs: number;
+    /** Cancels the child; aborting runs the host's own termination procedure, not a bare kill. */
+    readonly signal: AbortSignal;
+    /** Environment overrides, merged over the host's scrubbed parent environment. */
+    readonly env: {
+        readonly [name: string]: string;
+    };
+}
 /**
- * Runs one git command and returns its stdout, throwing on any non-zero exit, missing `git` binary,
- * or timeout. Indirection over `execFileSync` so tests never fork a real process.
+ * The narrow slice of `ctx.subprocess` this module consumes.
+ *
+ * Deliberately structural rather than an import of `@deepseek-ai/dsh-subprocess`: the tree-sitter
+ * package declares no dependency on the subprocess family, and only three members of a spawn are
+ * read here (argv, stdio, exit facts). Naming those keeps the port small enough that a test double
+ * is a few lines, and keeps the module loadable across the host versions this package supports.
+ */
+export interface GitSpawnPort {
+    /**
+     * Start one managed child.
+     * @param spec - program, arguments, cwd, stdio, termination grace, cancellation, environment.
+     * @returns the live handle whose `done` reports the child's exit facts.
+     */
+    spawn(spec: GitSpawnSpec): GitSpawnHandle;
+}
+/**
+ * Runs one git command and returns its stdout, rejecting on any non-zero exit, timeout, output
+ * overflow, or spawn failure.
+ *
+ * Async, because the host owns the child's lifetime: a synchronous exec cannot express the seam's
+ * cancellation, and blocking this process for the length of a git probe is exactly what the
+ * subprocess service exists to avoid. Callers inject this instead of forking a real process.
+ */
+export type GitExec = (args: readonly string[], cwd: string) => Promise<string>;
+/**
+ * The real `git`-backed {@link GitExec}, running through the host's subprocess port.
+ *
+ * Every failure is a rejection, never an empty string: the callers here parse git's output
+ * positionally, so a silent empty answer would be read as "truncated output" rather than "the probe
+ * failed", and the module's "a failed probe is a negative answer" contract lives above this layer.
+ * Environment overrides are git's own hardening — no user config, no terminal prompt, no optional
+ * locks — copied from the host's own git consumer so both behave identically.
+ * @param port - the spawn port; normally the host's `ctx.subprocess`.
+ * @returns a git runner whose rejections describe the command and git's stderr tail.
  */
-export type GitExec = (args: readonly string[], cwd: string) => string;
-/** The real `git`-backed {@link GitExec}. Array arguments, no shell, a hard timeout. */
-export declare const execGit: GitExec;
+export declare function execGit(port: GitSpawnPort): GitExec;
 /** What `detectWorktree` learned about one root. */
 export interface WorktreeInfo {
     /** Whether `root` is a linked worktree rather than the main working tree (or a lone clone). */
@@ -34,8 +134,8 @@ export interface WorktreeInfo {
  * way as "not a worktree" — `undefined`, never a thrown error — matching this package's existing
  * `canIndex`/`indexes` idiom of "a failed probe is a negative answer, not a failure to report."
  * @param root - absolute path to probe.
- * @param exec - the git-invoking primitive; defaults to the real `git` binary.
+ * @param exec - the git-invoking primitive; pass `execGit(ctx.subprocess)` for a real probe.
  * @returns worktree diagnostics, or `undefined` when `root` isn't inside a (usable) git repository.
  */
-export declare function detectWorktree(root: string, exec?: GitExec): WorktreeInfo | undefined;
+export declare function detectWorktree(root: string, exec: GitExec): Promise<WorktreeInfo | undefined>;
 //# sourceMappingURL=worktree.d.ts.map

package/lib/worktree.js

@@ -9,13 +9,86 @@
  * never looks outside the `projectRoot` it was given. If a caller ever *does* end up pointed at the
  * wrong root, the bug is almost certainly in how the host resolves a session's working directory, not
  * in this package — this module exists to make that distinction diagnosable, not to route around it.
+ *
+ * Git runs through the host's subprocess seam (`ctx.subprocess`) instead of `node:child_process`.
+ * That seam is where executable resolution, environment scrubbing, bounded output collection,
+ * termination grace, timeouts, and sandbox containment live: a child started here inherits a parent
+ * environment with ambient credentials and `DSH_*` deployment facts removed, its stdout/stderr are
+ * capped before they can exhaust this process, and the host may satisfy the request by running the
+ * command in another execution world entirely. `execFileSync` would bypass all of that, so the module
+ * takes the seam as a structural port and the caller supplies `execGit(ctx.subprocess)`.
  * @module dsh-plugin-codegraph-tree-sitter/worktree
  */
-import { execFileSync } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
-/** The real `git`-backed {@link GitExec}. Array arguments, no shell, a hard timeout. */
-export const execGit = (args, cwd) => execFileSync('git', [...args], { cwd, encoding: 'utf8', timeout: 2_000 });
-/** Memoized per root: git diagnostics are cheap to answer wrong (a stale worktree list) but not free. */
+/** Bound on one git probe's lifetime; the same ceiling the sync implementation used. */
+const GIT_TIMEOUT_MS = 2_000;
+/**
+ * Ceiling on collected stdout. `git rev-parse` answers in tens of bytes; the limit exists so a
+ * pathological repository cannot push unbounded output through this call, not because an answer
+ * of this size is expected.
+ */
+const GIT_MAX_OUTPUT_BYTES = 64 * 1024;
+/**
+ * The real `git`-backed {@link GitExec}, running through the host's subprocess port.
+ *
+ * Every failure is a rejection, never an empty string: the callers here parse git's output
+ * positionally, so a silent empty answer would be read as "truncated output" rather than "the probe
+ * failed", and the module's "a failed probe is a negative answer" contract lives above this layer.
+ * Environment overrides are git's own hardening — no user config, no terminal prompt, no optional
+ * locks — copied from the host's own git consumer so both behave identically.
+ * @param port - the spawn port; normally the host's `ctx.subprocess`.
+ * @returns a git runner whose rejections describe the command and git's stderr tail.
+ */
+export function execGit(port) {
+    return async (args, cwd) => {
+        const handle = port.spawn({
+            argv: ['git', ...args],
+            cwd,
+            stdio: {
+                stdin: 'ignore',
+                stdout: { maxBytes: GIT_MAX_OUTPUT_BYTES },
+                stderr: { maxBytes: GIT_MAX_OUTPUT_BYTES },
+            },
+            graceMs: GIT_TIMEOUT_MS,
+            // The host drives termination from this signal, so a hung git is stopped the same way a
+            // cancelled tool call is, and `done` settles with a signal exit instead of blocking forever.
+            signal: AbortSignal.timeout(GIT_TIMEOUT_MS),
+            env: {
+                GIT_CONFIG_COUNT: '0',
+                GIT_TERMINAL_PROMPT: '0',
+                GIT_OPTIONAL_LOCKS: '0',
+                LC_ALL: 'C',
+            },
+        });
+        const outcome = await handle.done;
+        if (outcome.exitCode !== 0) {
+            const stderr = handle.collected.stderr;
+            const detail = stderr === undefined ? '' : stderr.readFrom(0).text.trim();
+            // A signal exit carries no code, so name the signal instead of printing `null`.
+            const how = outcome.exitCode === null
+                ? `was terminated${outcome.signal === null ? '' : ` by ${outcome.signal}`}`
+                : `exited with code ${outcome.exitCode}`;
+            throw new Error(`git ${args.join(' ')} ${how}${detail === '' ? '' : `: ${detail}`}`);
+        }
+        const stdout = handle.collected.stdout;
+        if (stdout === undefined)
+            throw new Error(`git ${args.join(' ')} produced no collected stdout`);
+        const collected = stdout.readFrom(0);
+        // A lossy first read means the child wrote past the collection limit before exiting. What
+        // survived is a tail, not an answer — and a first line read off it would be a fragment of the
+        // real path or hash, so this is a failure rather than a truncated success.
+        if (collected.lossy) {
+            throw new Error(`git ${args.join(' ')} wrote more than ${GIT_MAX_OUTPUT_BYTES} bytes of stdout`);
+        }
+        return collected.text;
+    };
+}
+/**
+ * Memoized per root: git diagnostics are cheap to answer wrong (a stale worktree list) but not free.
+ * The promise itself is cached so two concurrent probes of one root share a single child process
+ * instead of racing two; `probeWorktree` resolves every failure to `undefined`, so this map never
+ * holds a rejection.
+ */
 const cache = new Map();
 /**
  * Whether `root` sits inside a linked `git worktree`, and the main repository's root when it does.
@@ -24,22 +97,23 @@ const cache = new Map();
  * way as "not a worktree" — `undefined`, never a thrown error — matching this package's existing
  * `canIndex`/`indexes` idiom of "a failed probe is a negative answer, not a failure to report."
  * @param root - absolute path to probe.
- * @param exec - the git-invoking primitive; defaults to the real `git` binary.
+ * @param exec - the git-invoking primitive; pass `execGit(ctx.subprocess)` for a real probe.
  * @returns worktree diagnostics, or `undefined` when `root` isn't inside a (usable) git repository.
  */
-export function detectWorktree(root, exec = execGit) {
-    if (cache.has(root))
-        return cache.get(root);
-    const info = probeWorktree(root, exec);
-    cache.set(root, info);
-    return info;
+export function detectWorktree(root, exec) {
+    const cached = cache.get(root);
+    if (cached !== undefined)
+        return cached;
+    const pending = probeWorktree(root, exec);
+    cache.set(root, pending);
+    return pending;
 }
-function probeWorktree(root, exec) {
+async function probeWorktree(root, exec) {
     let output;
     try {
         // One call, not three: `git rev-parse` answers every query in the order given, so a single
         // process fork either answers all three questions or fails all three the same way.
-        output = exec(['rev-parse', '--show-toplevel', '--git-dir', '--git-common-dir'], root);
+        output = await exec(['rev-parse', '--show-toplevel', '--git-dir', '--git-common-dir'], root);
     }
     catch {
         return undefined;
@@ -48,8 +122,9 @@ function probeWorktree(root, exec) {
     const toplevelLine = lines[0];
     const gitDirLine = lines[1];
     const commonDirLine = lines[2];
-    if (toplevelLine === undefined || gitDirLine === undefined || commonDirLine === undefined)
+    if (toplevelLine === undefined || gitDirLine === undefined || commonDirLine === undefined) {
         return undefined;
+    }
     // `git rev-parse` reports these relative to `root` (the cwd it ran in) unless they point outside
     // that tree entirely, as `--git-common-dir` does from inside a linked worktree — `resolve` is a
     // no-op on an already-absolute path either way.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-codegraph-tree-sitter",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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.3.0"
+    "dsh-plugin-codegraph-service": "^0.4.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.1",