token-pilot 0.30.0 → 0.30.1

package/dist/ast-index/client.js

@@ -1,12 +1,12 @@
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { findBinary, installBinary } from './binary-manager.js';
-import { parseFileCount, parseOutlineText, parseImportsText, parseImplementationsText, parseHierarchyText, parseAgrepText, parseTodoText, parseDeprecatedText, parseAnnotationsText, parseModuleListText, parseModuleDepText, parseUnusedDepsText, parseModuleApiText, } from './parser.js';
-import { buildFileStructure } from './enricher.js';
-import { parseTypeScriptRegex } from './regex-parser.js';
-import { parsePythonRegex } from './regex-parser-python.js';
-const TS_JS_EXTENSIONS = new Set(['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs']);
-const PYTHON_EXTENSIONS = new Set(['py', 'pyw']);
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { findBinary, installBinary } from "./binary-manager.js";
+import { parseFileCount, parseOutlineText, parseImportsText, parseImplementationsText, parseHierarchyText, parseAgrepText, parseTodoText, parseDeprecatedText, parseAnnotationsText, parseModuleListText, parseModuleDepText, parseUnusedDepsText, parseModuleApiText, } from "./parser.js";
+import { buildFileStructure } from "./enricher.js";
+import { parseTypeScriptRegex } from "./regex-parser.js";
+import { parsePythonRegex } from "./regex-parser-python.js";
+const TS_JS_EXTENSIONS = new Set(["ts", "tsx", "js", "jsx", "mjs", "cjs"]);
+const PYTHON_EXTENSIONS = new Set(["py", "pyw"]);
 const execFileAsync = promisify(execFile);
 export class AstIndexClient {
     static MAX_INDEX_FILES = 50_000;
@@ -21,6 +21,9 @@ export class AstIndexClient {
     autoInstall;
     astGrepAvailable = null;
     astGrepBinDir = null;
+    // Periodic-update timer and overlap guard (see startPeriodicUpdate below)
+    periodicTimer = null;
+    periodicUpdateInFlight = false;
     constructor(projectRoot, timeout = 5000, options) {
         this.projectRoot = projectRoot;
         this.timeout = timeout;
@@ -37,7 +40,7 @@ export class AstIndexClient {
         }
         // 2. Auto-install if enabled
         if (this.autoInstall) {
-            console.error('[token-pilot] ast-index not found, downloading...');
+            console.error("[token-pilot] ast-index not found, downloading...");
             try {
                 const installed = await installBinary((msg) => console.error(`[token-pilot] ${msg}`));
                 this.binaryPath = installed.path;
@@ -47,20 +50,20 @@ export class AstIndexClient {
                 console.error(`[token-pilot] Auto-install failed: ${err instanceof Error ? err.message : err}`);
             }
         }
-        throw new Error('ast-index binary not found and auto-install failed.\n' +
-            'Install manually: npx token-pilot install-ast-index\n' +
-            'Or: cargo install ast-index');
+        throw new Error("ast-index binary not found and auto-install failed.\n" +
+            "Install manually: npx token-pilot install-ast-index\n" +
+            "Or: cargo install ast-index");
     }
     async ensureIndex() {
         if (this.indexed)
             return;
         if (this.indexDisabled) {
-            throw new Error('ast-index: index build disabled — project root is too broad (e.g. /). ' +
+            throw new Error("ast-index: index build disabled — project root is too broad (e.g. /). " +
                 'Configure mcpServers with "args": ["/path/to/project"] to set the correct project root.');
         }
         if (this.indexOversized) {
-            throw new Error('ast-index disabled: previous build indexed >50k files (likely node_modules). ' +
-                'Ensure node_modules is in .gitignore, then restart the MCP server.');
+            throw new Error("ast-index disabled: previous build indexed >50k files (likely node_modules). " +
+                "Ensure node_modules is in .gitignore, then restart the MCP server.");
         }
         // Deduplicate concurrent calls — all waiters share one build
         if (this.indexPromise)
@@ -76,26 +79,32 @@ export class AstIndexClient {
     async buildIndex() {
         let existingFileCount = 0;
         try {
-            const stats = await this.exec(['--format', 'json', 'stats']);
+            const stats = await this.exec(["--format", "json", "stats"]);
             existingFileCount = parseFileCount(stats);
         }
-        catch { /* no index yet */ }
+        catch {
+            /* no index yet */
+        }
         if (existingFileCount > AstIndexClient.MAX_INDEX_FILES) {
             console.error(`[token-pilot] ast-index: existing index has ${existingFileCount} files (>${AstIndexClient.MAX_INDEX_FILES}) — likely includes node_modules. Clearing.`);
             try {
-                await this.exec(['clear']);
+                await this.exec(["clear"]);
+            }
+            catch {
+                /* best effort */
             }
-            catch { /* best effort */ }
             existingFileCount = 0;
         }
         if (existingFileCount > 0) {
             console.error(`[token-pilot] ast-index: updating index (${existingFileCount} files)...`);
             try {
-                await this.exec(['update'], 30000);
+                await this.exec(["update"], 30000);
                 try {
-                    existingFileCount = parseFileCount(await this.exec(['--format', 'json', 'stats']));
+                    existingFileCount = parseFileCount(await this.exec(["--format", "json", "stats"]));
+                }
+                catch {
+                    /* keep previous count */
                 }
-                catch { /* keep previous count */ }
                 if (existingFileCount > AstIndexClient.MAX_INDEX_FILES) {
                     return this.handleOversizedIndex(existingFileCount);
                 }
@@ -107,10 +116,10 @@ export class AstIndexClient {
                 console.error(`[token-pilot] ast-index: update failed, falling back to rebuild — ${updateErr instanceof Error ? updateErr.message : updateErr}`);
             }
         }
-        console.error('[token-pilot] ast-index: building index (this may take a moment)...');
+        console.error("[token-pilot] ast-index: building index (this may take a moment)...");
         try {
-            await this.exec(['rebuild'], 120000);
-            const fileCount = parseFileCount(await this.exec(['--format', 'json', 'stats']).catch(() => ''));
+            await this.exec(["rebuild"], 120000);
+            const fileCount = parseFileCount(await this.exec(["--format", "json", "stats"]).catch(() => ""));
             if (fileCount > AstIndexClient.MAX_INDEX_FILES) {
                 return this.handleOversizedIndex(fileCount);
             }
@@ -119,8 +128,8 @@ export class AstIndexClient {
         }
         catch (buildErr) {
             const errMsg = buildErr instanceof Error ? buildErr.message : String(buildErr);
-            if (errMsg.includes('lock') || errMsg.includes('already running')) {
-                const count = parseFileCount(await this.exec(['--format', 'json', 'stats']).catch(() => ''));
+            if (errMsg.includes("lock") || errMsg.includes("already running")) {
+                const count = parseFileCount(await this.exec(["--format", "json", "stats"]).catch(() => ""));
                 if (count > 0 && count <= AstIndexClient.MAX_INDEX_FILES) {
                     this.indexed = true;
                     console.error(`[token-pilot] ast-index: using existing index (${count} files, rebuild skipped due to lock)`);
@@ -138,9 +147,11 @@ export class AstIndexClient {
         this.indexOversized = true;
         this.indexed = false;
         try {
-            await this.exec(['clear']);
+            await this.exec(["clear"]);
+        }
+        catch {
+            /* best effort */
         }
-        catch { /* best effort */ }
         console.error(`[token-pilot] ast-index: ${fileCount} files indexed (>${AstIndexClient.MAX_INDEX_FILES}) — ` +
             `likely includes node_modules. Index cleared.\n` +
             `  → Ensure node_modules is in .gitignore\n` +
@@ -149,7 +160,7 @@ export class AstIndexClient {
     }
     async outline(filePath) {
         try {
-            const result = await this.exec(['outline', filePath]);
+            const result = await this.exec(["outline", filePath]);
             const entries = parseOutlineText(result);
             if (entries.length === 0)
                 return null;
@@ -160,7 +171,7 @@ export class AstIndexClient {
                 return this.regexFallback(filePath);
             try {
                 await this.ensureIndex();
-                const result = await this.exec(['outline', filePath]);
+                const result = await this.exec(["outline", filePath]);
                 const entries = parseOutlineText(result);
                 if (entries.length === 0)
                     return null;
@@ -174,15 +185,17 @@ export class AstIndexClient {
     }
     /** Regex-based fallback for TS/JS/Python when ast-index binary is unavailable. */
     async regexFallback(filePath) {
-        const ext = filePath.split('.').pop()?.toLowerCase() ?? '';
-        const parser = TS_JS_EXTENSIONS.has(ext) ? parseTypeScriptRegex
-            : PYTHON_EXTENSIONS.has(ext) ? parsePythonRegex
+        const ext = filePath.split(".").pop()?.toLowerCase() ?? "";
+        const parser = TS_JS_EXTENSIONS.has(ext)
+            ? parseTypeScriptRegex
+            : PYTHON_EXTENSIONS.has(ext)
+                ? parsePythonRegex
                 : null;
         if (!parser)
             return null;
         try {
-            const { readFile } = await import('node:fs/promises');
-            const content = await readFile(filePath, 'utf-8');
+            const { readFile } = await import("node:fs/promises");
+            const content = await readFile(filePath, "utf-8");
             const entries = parser(content);
             if (entries.length === 0)
                 return null;
@@ -194,24 +207,38 @@ export class AstIndexClient {
     }
     async symbol(name) {
         try {
-            const result = await this.exec(['symbol', name, '--format', 'json']);
+            const result = await this.exec(["symbol", name, "--format", "json"]);
             const raw = JSON.parse(result);
             if (Array.isArray(raw) && raw.length > 0) {
                 const first = raw[0];
-                return { name: first.name, kind: first.kind, file: first.path, start_line: first.line, signature: first.signature };
+                return {
+                    name: first.name,
+                    kind: first.kind,
+                    file: first.path,
+                    start_line: first.line,
+                    signature: first.signature,
+                };
             }
         }
-        catch { /* fall through to ensureIndex path */ }
+        catch {
+            /* fall through to ensureIndex path */
+        }
         if (this.indexDisabled || this.indexOversized)
             return null;
         try {
             await this.ensureIndex();
-            const result = await this.exec(['symbol', name, '--format', 'json']);
+            const result = await this.exec(["symbol", name, "--format", "json"]);
             const raw = JSON.parse(result);
             if (!Array.isArray(raw) || raw.length === 0)
                 return null;
             const first = raw[0];
-            return { name: first.name, kind: first.kind, file: first.path, start_line: first.line, signature: first.signature };
+            return {
+                name: first.name,
+                kind: first.kind,
+                file: first.path,
+                start_line: first.line,
+                signature: first.signature,
+            };
         }
         catch (err) {
             console.error(`[token-pilot] ast-index symbol failed: ${err instanceof Error ? err.message : err}`);
@@ -220,41 +247,51 @@ export class AstIndexClient {
     }
     async search(query, options) {
         await this.ensureIndex();
-        const args = ['search', query, '--format', 'json'];
+        const args = ["search", query, "--format", "json"];
         if (options?.inFile)
-            args.push('--in-file', options.inFile);
+            args.push("--in-file", options.inFile);
         if (options?.type)
-            args.push('--type', options.type);
+            args.push("--type", options.type);
         if (options?.maxResults)
-            args.push('--limit', String(options.maxResults));
+            args.push("--limit", String(options.maxResults));
         if (options?.fuzzy)
-            args.push('--fuzzy');
+            args.push("--fuzzy");
         try {
             const result = await this.exec(args);
             const parsed = JSON.parse(result);
             // ast-index returns { content_matches: [], symbols: [], files: [], references: [] }
             // Merge all result types — content_matches alone is often empty
             const all = [
-                ...(Array.isArray(parsed.content_matches) ? parsed.content_matches : []),
-                ...(Array.isArray(parsed.symbols) ? parsed.symbols.map((s) => ({
-                    path: s.path ?? s.file, line: s.line, content: s.signature ?? s.name,
-                })) : []),
-                ...(Array.isArray(parsed.files) ? parsed.files.map((f) => ({
-                    path: f.path ?? f.file, line: f.line ?? 1, content: f.path ?? f.file,
-                })) : []),
+                ...(Array.isArray(parsed.content_matches)
+                    ? parsed.content_matches
+                    : []),
+                ...(Array.isArray(parsed.symbols)
+                    ? parsed.symbols.map((s) => ({
+                        path: s.path ?? s.file,
+                        line: s.line,
+                        content: s.signature ?? s.name,
+                    }))
+                    : []),
+                ...(Array.isArray(parsed.files)
+                    ? parsed.files.map((f) => ({
+                        path: f.path ?? f.file,
+                        line: f.line ?? 1,
+                        content: f.path ?? f.file,
+                    }))
+                    : []),
                 ...(Array.isArray(parsed.references) ? parsed.references : []),
             ];
-            const matches = all.length > 0 ? all : (Array.isArray(parsed) ? parsed : []);
+            const matches = all.length > 0 ? all : Array.isArray(parsed) ? parsed : [];
             const mapped = matches
                 .map((m) => ({
-                file: m.path ?? m.file ?? '',
-                line: typeof m.line === 'number' ? m.line : 0,
-                text: m.content ?? m.text ?? m.signature ?? '',
+                file: m.path ?? m.file ?? "",
+                line: typeof m.line === "number" ? m.line : 0,
+                text: m.content ?? m.text ?? m.signature ?? "",
             }))
-                .filter(r => r.file !== '' && r.text !== '');
+                .filter((r) => r.file !== "" && r.text !== "");
             // Deduplicate by file:line
             const seen = new Set();
-            return mapped.filter(r => {
+            return mapped.filter((r) => {
                 const key = `${r.file}:${r.line}`;
                 if (seen.has(key))
                     return false;
@@ -270,11 +307,21 @@ export class AstIndexClient {
     async usages(symbolName) {
         await this.ensureIndex();
         try {
-            const result = await this.exec(['usages', symbolName, '--format', 'json']);
+            const result = await this.exec([
+                "usages",
+                symbolName,
+                "--format",
+                "json",
+            ]);
             const raw = JSON.parse(result);
             if (!Array.isArray(raw))
                 return [];
-            return raw.map(u => ({ file: u.path, line: u.line, text: u.context, kind: 'reference' }));
+            return raw.map((u) => ({
+                file: u.path,
+                line: u.line,
+                text: u.context,
+                kind: "reference",
+            }));
         }
         catch (err) {
             console.error(`[token-pilot] ast-index usages failed: ${err instanceof Error ? err.message : err}`);
@@ -284,7 +331,12 @@ export class AstIndexClient {
     async implementations(name) {
         await this.ensureIndex();
         try {
-            const result = await this.exec(['implementations', name, '--format', 'json']);
+            const result = await this.exec([
+                "implementations",
+                name,
+                "--format",
+                "json",
+            ]);
             try {
                 return JSON.parse(result);
             }
@@ -300,11 +352,11 @@ export class AstIndexClient {
     async hierarchy(name, options) {
         await this.ensureIndex();
         try {
-            const args = ['hierarchy', name, '--format', 'json'];
+            const args = ["hierarchy", name, "--format", "json"];
             if (options?.inFile)
-                args.push('--in-file', options.inFile);
+                args.push("--in-file", options.inFile);
             if (options?.module)
-                args.push('--module', options.module);
+                args.push("--module", options.module);
             const result = await this.exec(args);
             try {
                 return JSON.parse(result);
@@ -320,7 +372,7 @@ export class AstIndexClient {
     }
     async stats() {
         try {
-            return await this.exec(['stats']);
+            return await this.exec(["stats"]);
         }
         catch {
             return null;
@@ -329,8 +381,11 @@ export class AstIndexClient {
     async listFiles() {
         try {
             await this.ensureIndex();
-            const result = await this.exec(['files'], 15000);
-            return result.split('\n').map(l => l.trim()).filter(l => l.length > 0);
+            const result = await this.exec(["files"], 15000);
+            return result
+                .split("\n")
+                .map((l) => l.trim())
+                .filter((l) => l.length > 0);
         }
         catch (err) {
             console.error(`[token-pilot] ast-index files failed: ${err instanceof Error ? err.message : err}`);
@@ -340,7 +395,14 @@ export class AstIndexClient {
     async refs(symbolName, limit = 20) {
         await this.ensureIndex();
         try {
-            const result = await this.exec(['refs', symbolName, '--limit', String(limit), '--format', 'json']);
+            const result = await this.exec([
+                "refs",
+                symbolName,
+                "--limit",
+                String(limit),
+                "--format",
+                "json",
+            ]);
             return JSON.parse(result);
         }
         catch (err) {
@@ -351,11 +413,11 @@ export class AstIndexClient {
     async map(options) {
         await this.ensureIndex();
         try {
-            const args = ['map', '--format', 'json'];
+            const args = ["map", "--format", "json"];
             if (options?.module)
-                args.push('--module', options.module);
+                args.push("--module", options.module);
             if (options?.limit)
-                args.push('--limit', String(options.limit));
+                args.push("--limit", String(options.limit));
             const result = await this.exec(args, 15000);
             return JSON.parse(result);
         }
@@ -367,7 +429,7 @@ export class AstIndexClient {
     async conventions() {
         await this.ensureIndex();
         try {
-            const result = await this.exec(['conventions', '--format', 'json']);
+            const result = await this.exec(["conventions", "--format", "json"]);
             return JSON.parse(result);
         }
         catch (err) {
@@ -378,7 +440,14 @@ export class AstIndexClient {
     async callers(functionName, limit = 50) {
         await this.ensureIndex();
         try {
-            const result = await this.exec(['callers', functionName, '--limit', String(limit), '--format', 'json']);
+            const result = await this.exec([
+                "callers",
+                functionName,
+                "--limit",
+                String(limit),
+                "--format",
+                "json",
+            ]);
             const parsed = JSON.parse(result);
             return Array.isArray(parsed) ? parsed : [];
         }
@@ -390,7 +459,14 @@ export class AstIndexClient {
     async callTree(functionName, depth = 3) {
         await this.ensureIndex();
         try {
-            const result = await this.exec(['call-tree', functionName, '--depth', String(depth), '--format', 'json']);
+            const result = await this.exec([
+                "call-tree",
+                functionName,
+                "--depth",
+                String(depth),
+                "--format",
+                "json",
+            ]);
             return JSON.parse(result);
         }
         catch (err) {
@@ -401,9 +477,9 @@ export class AstIndexClient {
     async changed(base) {
         await this.ensureIndex();
         try {
-            const args = ['changed', '--format', 'json'];
+            const args = ["changed", "--format", "json"];
             if (base)
-                args.push('--base', base);
+                args.push("--base", base);
             const result = await this.exec(args, 15000);
             const parsed = JSON.parse(result);
             return Array.isArray(parsed) ? parsed : [];
@@ -416,13 +492,13 @@ export class AstIndexClient {
     async unusedSymbols(options) {
         await this.ensureIndex();
         try {
-            const args = ['unused-symbols', '--format', 'json'];
+            const args = ["unused-symbols", "--format", "json"];
             if (options?.module)
-                args.push('--module', options.module);
+                args.push("--module", options.module);
             if (options?.exportOnly)
-                args.push('--export-only');
+                args.push("--export-only");
             if (options?.limit)
-                args.push('--limit', String(options.limit));
+                args.push("--limit", String(options.limit));
             const result = await this.exec(args, 15000);
             const parsed = JSON.parse(result);
             return Array.isArray(parsed) ? parsed : [];
@@ -435,7 +511,7 @@ export class AstIndexClient {
     async fileImports(filePath) {
         await this.ensureIndex();
         try {
-            const result = await this.exec(['imports', filePath]);
+            const result = await this.exec(["imports", filePath]);
             return parseImportsText(result);
         }
         catch (err) {
@@ -448,19 +524,26 @@ export class AstIndexClient {
         if (this.astGrepAvailable !== null)
             return this.astGrepAvailable;
         try {
-            await execFileAsync('sg', ['--version'], { timeout: 3000 });
+            await execFileAsync("sg", ["--version"], { timeout: 3000 });
             this.astGrepAvailable = true;
             return true;
         }
-        catch { /* not in PATH */ }
+        catch {
+            /* not in PATH */
+        }
         try {
-            const localBinDir = new URL('../../node_modules/.bin', import.meta.url).pathname;
-            await execFileAsync(localBinDir + '/sg', ['--version'], { timeout: 3000 });
+            const localBinDir = new URL("../../node_modules/.bin", import.meta.url)
+                .pathname;
+            await execFileAsync(localBinDir + "/sg", ["--version"], {
+                timeout: 3000,
+            });
             this.astGrepBinDir = localBinDir;
             this.astGrepAvailable = true;
             return true;
         }
-        catch { /* not found locally either */ }
+        catch {
+            /* not found locally either */
+        }
         this.astGrepAvailable = false;
         return false;
     }
@@ -470,14 +553,14 @@ export class AstIndexClient {
         await this.ensureIndex();
         const available = await this.checkAstGrep();
         if (!available) {
-            throw new Error('ast-grep (sg) not installed — required for structural pattern search.\n' +
-                'Install: brew install ast-grep  OR  npm i -g @ast-grep/cli\n' +
-                'Alternative: use Grep/ripgrep for text-based pattern search.');
+            throw new Error("ast-grep (sg) not installed — required for structural pattern search.\n" +
+                "Install: brew install ast-grep  OR  npm i -g @ast-grep/cli\n" +
+                "Alternative: use Grep/ripgrep for text-based pattern search.");
         }
         const limit = options?.limit ?? 50;
-        const args = ['agrep', pattern];
+        const args = ["agrep", pattern];
         if (options?.lang)
-            args.push('--lang', options.lang);
+            args.push("--lang", options.lang);
         try {
             const result = await this.exec(args, 15000);
             return parseAgrepText(result).slice(0, limit);
@@ -492,7 +575,7 @@ export class AstIndexClient {
             return [];
         await this.ensureIndex();
         try {
-            const result = await this.exec(['todo'], 15000);
+            const result = await this.exec(["todo"], 15000);
             return parseTodoText(result);
         }
         catch (err) {
@@ -505,7 +588,7 @@ export class AstIndexClient {
             return [];
         await this.ensureIndex();
         try {
-            const result = await this.exec(['deprecated'], 15000);
+            const result = await this.exec(["deprecated"], 15000);
             return parseDeprecatedText(result);
         }
         catch (err) {
@@ -518,7 +601,7 @@ export class AstIndexClient {
             return [];
         await this.ensureIndex();
         try {
-            const result = await this.exec(['annotations', name], 15000);
+            const result = await this.exec(["annotations", name], 15000);
             return parseAnnotationsText(result, name);
         }
         catch (err) {
@@ -530,19 +613,51 @@ export class AstIndexClient {
         if (!this.indexed || this.indexDisabled || this.indexOversized)
             return;
         try {
-            await this.exec(['update'], 15000);
+            await this.exec(["update"], 15000);
         }
         catch (err) {
             console.error(`[token-pilot] ast-index incremental update failed: ${err instanceof Error ? err.message : err}`);
         }
     }
+    /**
+     * Periodic safety-net so long sessions don't drift when FileWatcher misses
+     * events (Docker bind mounts, NFS, files changed by sibling tools). We
+     * explicitly avoid spawning `ast-index watch` as a daemon — it duplicates
+     * our FileWatcher, needs PID/lifecycle management, and goes zombie if the
+     * MCP server is killed with SIGKILL.
+     *
+     * Default cadence is 5 minutes. `unref()` lets the process exit naturally
+     * even if a tick is pending. An in-flight guard prevents overlapping runs
+     * when a single update exceeds the interval (rare — timeout is 15 s).
+     */
+    startPeriodicUpdate(intervalMs = 5 * 60 * 1000) {
+        if (this.periodicTimer)
+            return;
+        this.periodicTimer = setInterval(() => {
+            if (this.periodicUpdateInFlight)
+                return;
+            if (!this.indexed || this.indexDisabled || this.indexOversized)
+                return;
+            this.periodicUpdateInFlight = true;
+            void this.incrementalUpdate().finally(() => {
+                this.periodicUpdateInFlight = false;
+            });
+        }, intervalMs);
+        this.periodicTimer.unref?.();
+    }
+    stopPeriodicUpdate() {
+        if (this.periodicTimer) {
+            clearInterval(this.periodicTimer);
+            this.periodicTimer = null;
+        }
+    }
     // --- Module analysis methods ---
     async modules(pattern) {
         if (this.indexDisabled || this.indexOversized)
             return [];
         await this.ensureIndex();
         try {
-            const cmdArgs = pattern ? ['module', pattern] : ['module'];
+            const cmdArgs = pattern ? ["module", pattern] : ["module"];
             const result = await this.exec(cmdArgs, 15000);
             return parseModuleListText(result);
         }
@@ -556,7 +671,7 @@ export class AstIndexClient {
             return [];
         await this.ensureIndex();
         try {
-            const result = await this.exec(['deps', module], 15000);
+            const result = await this.exec(["deps", module], 15000);
             return parseModuleDepText(result);
         }
         catch (err) {
@@ -569,7 +684,7 @@ export class AstIndexClient {
             return [];
         await this.ensureIndex();
         try {
-            const result = await this.exec(['dependents', module], 15000);
+            const result = await this.exec(["dependents", module], 15000);
             return parseModuleDepText(result);
         }
         catch (err) {
@@ -582,7 +697,7 @@ export class AstIndexClient {
             return [];
         await this.ensureIndex();
         try {
-            const result = await this.exec(['unused-deps', module], 15000);
+            const result = await this.exec(["unused-deps", module], 15000);
             return parseUnusedDepsText(result);
         }
         catch (err) {
@@ -595,7 +710,7 @@ export class AstIndexClient {
             return [];
         await this.ensureIndex();
         try {
-            const result = await this.exec(['api', module], 15000);
+            const result = await this.exec(["api", module], 15000);
             return parseModuleApiText(result);
         }
         catch (err) {
@@ -625,16 +740,27 @@ export class AstIndexClient {
     }
     async exec(args, timeoutMs) {
         if (!this.binaryPath) {
-            throw new Error('ast-index not initialized. Call init() first.');
+            throw new Error("ast-index not initialized. Call init() first.");
+        }
+        // ast-index v3.39+ honours AST_INDEX_WALK_UP=1 — read-commands then
+        // traverse past nested VCS markers (submodule .git, inner Cargo.toml,
+        // nested settings.gradle) to reuse a parent-level index if one exists.
+        // Without this, running `search`/`outline` from a monorepo subdir stops
+        // at the nearest marker and finds nothing when the subdir has no DB.
+        // Safe default: pure-additive, no effect when projectRoot already sits
+        // at the index root.
+        const env = {
+            ...process.env,
+            AST_INDEX_WALK_UP: "1",
+        };
+        if (this.astGrepBinDir) {
+            env.PATH = `${this.astGrepBinDir}:${process.env.PATH ?? ""}`;
         }
-        const env = this.astGrepBinDir
-            ? { ...process.env, PATH: `${this.astGrepBinDir}:${process.env.PATH ?? ''}` }
-            : undefined;
         const { stdout, stderr } = await execFileAsync(this.binaryPath, args, {
             timeout: timeoutMs ?? this.timeout,
             maxBuffer: 10 * 1024 * 1024, // 10MB
             cwd: this.projectRoot,
-            ...(env && { env }),
+            env,
         });
         if (stderr) {
             console.error(`[token-pilot] ast-index stderr (${args[0]}): ${stderr.trim()}`);