gitnexus 1.6.10 → 1.6.11-rc.10

package/dist/cli/i18n/resources.d.ts

@@ -33,6 +33,14 @@ export declare const cliResources: {
         readonly 'status.detached': "(detached HEAD)";
         readonly 'status.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run gitnexus analyze to follow the current branch)";
         readonly 'status.status': "Status";
+        readonly 'status.indexContentCurrent': "Index content: matches all {{count}} covered file(s)";
+        readonly 'status.indexContentDrifted': "Index content: {{changed}} changed, {{added}} added, {{deleted}} deleted";
+        readonly 'status.indexContentMore': "  ...and {{count}} more {{label}}";
+        readonly 'status.indexContentUnmeasurable': "Index content: not comparable ({{reason}}); fell back to the working-tree check";
+        readonly 'status.indexContentScanFailed': "Index content: coverage scan failed; treating the index as stale";
+        readonly 'status.driftChanged': "changed";
+        readonly 'status.driftAdded': "added";
+        readonly 'status.driftDeleted': "deleted";
         readonly 'status.upToDate': "✅ up-to-date";
         readonly 'status.stale': "⚠️ stale (re-run gitnexus analyze)";
         readonly 'clean.deleteAll': "This will delete GitNexus indexes for {{count}} repo(s):";
@@ -172,6 +180,8 @@ export declare const cliResources: {
         readonly 'help.option.analyze.embeddingBatchSize': "Number of nodes per embedding batch";
         readonly 'help.option.analyze.embeddingSubBatchSize': "Number of chunks per embedding model call";
         readonly 'help.option.analyze.embeddingDevice': "Embedding device: auto, cpu, dml, cuda, or wasm";
+        readonly 'help.option.analyze.watch': "Keep the index current with serialized incremental refreshes";
+        readonly 'help.option.analyze.debounce': "Watch quiet period before refreshing (milliseconds)";
         readonly 'help.option.index.force': "Register even if index metadata is missing (stats will be empty)";
         readonly 'help.option.index.allowNonGit': "Allow registering folders that are not Git repositories";
         readonly 'help.option.port': "Port number";
@@ -185,7 +195,7 @@ export declare const cliResources: {
         readonly 'help.option.clean.branch': "Delete only the named branch index (not the workspace index)";
         readonly 'help.option.clean.lbugSidecars': "Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)";
         readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
-        readonly 'help.option.wiki.provider': "LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: minimax)";
+        readonly 'help.option.wiki.provider': "LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)";
         readonly 'help.option.wiki.model': "LLM model or deployment name (default: MiniMax-M3)";
         readonly 'help.option.wiki.baseUrl': "LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1";
         readonly 'help.option.wiki.apiKey': "LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)";
@@ -287,6 +297,14 @@ export declare const cliResources: {
         'status.detached': string;
         'status.workspaceIndexLabel': string;
         'status.status': string;
+        'status.indexContentCurrent': string;
+        'status.indexContentDrifted': string;
+        'status.indexContentMore': string;
+        'status.indexContentUnmeasurable': string;
+        'status.indexContentScanFailed': string;
+        'status.driftChanged': string;
+        'status.driftAdded': string;
+        'status.driftDeleted': string;
         'status.upToDate': string;
         'status.stale': string;
         'clean.deleteAll': string;
@@ -426,6 +444,8 @@ export declare const cliResources: {
         'help.option.analyze.embeddingBatchSize': string;
         'help.option.analyze.embeddingSubBatchSize': string;
         'help.option.analyze.embeddingDevice': string;
+        'help.option.analyze.watch': string;
+        'help.option.analyze.debounce': string;
         'help.option.index.force': string;
         'help.option.index.allowNonGit': string;
         'help.option.port': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -32,6 +32,14 @@ export declare const zhCN: {
     'status.detached': string;
     'status.workspaceIndexLabel': string;
     'status.status': string;
+    'status.indexContentCurrent': string;
+    'status.indexContentDrifted': string;
+    'status.indexContentMore': string;
+    'status.indexContentUnmeasurable': string;
+    'status.indexContentScanFailed': string;
+    'status.driftChanged': string;
+    'status.driftAdded': string;
+    'status.driftDeleted': string;
     'status.upToDate': string;
     'status.stale': string;
     'clean.deleteAll': string;
@@ -171,6 +179,8 @@ export declare const zhCN: {
     'help.option.analyze.embeddingBatchSize': string;
     'help.option.analyze.embeddingSubBatchSize': string;
     'help.option.analyze.embeddingDevice': string;
+    'help.option.analyze.watch': string;
+    'help.option.analyze.debounce': string;
     'help.option.index.force': string;
     'help.option.index.allowNonGit': string;
     'help.option.port': string;

package/dist/cli/i18n/zh-CN.js

@@ -32,6 +32,14 @@ export const zhCN = {
     'status.detached': '（分离 HEAD）',
     'status.workspaceIndexLabel': "工作区索引：最近在 '{{primary}}' 分支上分析（重新运行 gitnexus analyze 以跟随当前分支）",
     'status.status': '状态',
+    'status.indexContentCurrent': '索引内容：与覆盖的全部 {{count}} 个文件一致',
+    'status.indexContentDrifted': '索引内容：{{changed}} 个已修改，{{added}} 个新增，{{deleted}} 个已删除',
+    'status.indexContentMore': '  ……另有 {{count}} 个 {{label}}',
+    'status.indexContentUnmeasurable': '索引内容：无法比对（{{reason}}），已回退到工作区检查',
+    'status.indexContentScanFailed': '索引内容：覆盖扫描失败，按过期处理',
+    'status.driftChanged': '已修改',
+    'status.driftAdded': '新增',
+    'status.driftDeleted': '已删除',
     'status.upToDate': '✅ 已是最新',
     'status.stale': '⚠️ 已过期（重新运行 gitnexus analyze）',
     'clean.deleteAll': '将删除 {{count}} 个仓库的 GitNexus 索引：',
@@ -171,6 +179,8 @@ export const zhCN = {
     'help.option.analyze.embeddingBatchSize': '每个嵌入批次的节点数',
     'help.option.analyze.embeddingSubBatchSize': '每次嵌入模型调用的分块数',
     'help.option.analyze.embeddingDevice': '嵌入设备：auto、cpu、dml、cuda 或 wasm',
+    'help.option.analyze.watch': '监视本地源文件变更并串行执行增量刷新',
+    'help.option.analyze.debounce': '刷新前的静默等待时间（毫秒）',
     'help.option.index.force': '即使缺少索引元数据也注册（统计为空）',
     'help.option.index.allowNonGit': '允许注册非 Git 仓库文件夹',
     'help.option.port': '端口号',
@@ -184,7 +194,7 @@ export const zhCN = {
     'help.option.clean.branch': '仅删除指定分支的索引（不影响工作区索引）',
     'help.option.clean.lbugSidecars': '清理已暂存的 LadybugDB 恢复 sidecar（missing-shadow WAL 隔离文件与 dirty-recovery 暂存文件）',
     'help.option.wiki.force': '即使已是最新也强制完整重新生成',
-    'help.option.wiki.provider': 'LLM 提供商：minimax、openai、openrouter、azure、custom、cursor、claude、codex 或 opencode（默认：minimax）',
+    'help.option.wiki.provider': 'LLM 提供商：minimax、openai、openrouter、azure、custom、cursor、claude、codex、opencode 或 grok（默认：minimax）',
     'help.option.wiki.model': 'LLM 模型或 deployment 名称（默认：MiniMax-M3）',
     'help.option.wiki.baseUrl': 'LLM API base URL。Azure v1：https://{resource}.openai.azure.com/openai/v1',
     'help.option.wiki.apiKey': 'LLM API key 或 Azure api-key（保存到 ~/.gitnexus/config.json）',

package/dist/cli/index.js

@@ -36,6 +36,8 @@ let dimsEnvCaptured = false;
 program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')
+    .option('--watch', 'Keep the index current with serialized incremental refreshes')
+    .option('--debounce <ms>', 'Watch quiet period before refreshing (default: 300 milliseconds)')
     .option('-f, --force', 'Force full re-index even if up to date')
     .option('--repair-fts', 'Repair/rebuild search FTS indexes without full re-analysis')
     .option('--embeddings [limit]', 'Enable embedding generation for semantic search (off by default). ' +
@@ -84,6 +86,11 @@ program
     'Must match what the index was built with. Overrides GITNEXUS_EMBEDDING_DIMS.')
     .addHelpText('after', () => t('help.analyze.environment'))
     .hook('preAction', (thisCommand) => {
+    const analyzeOpts = thisCommand.opts();
+    if (analyzeOpts['debounce'] !== undefined && analyzeOpts['watch'] !== true) {
+        process.stderr.write('\n  --debounce requires --watch\n\n');
+        process.exit(1);
+    }
     // ONLY GITNEXUS_EMBEDDING_DIMS must be set here: schema.ts reads it at
     // module-load time during the lazy import('./analyze.js') below (via the
     // static chain analyze.ts → run-analyze.ts → schema.ts), so deferring to
@@ -91,7 +98,7 @@ program
     // lazily at runtime (readConfig), so analyzeCommandImpl is their sole
     // setter — keeping them out of this hook means they fall under the impl's
     // env snapshot/restore and don't leak across in-process invocations.
-    const dimsOpt = thisCommand.opts()['embeddingDims'];
+    const dimsOpt = analyzeOpts['embeddingDims'];
     if (dimsOpt !== undefined) {
         // Validate + normalize BEFORE writing the env var: schema.ts throws on a
         // bad value at module-load, which — on the synchronous program.parse()
@@ -122,7 +129,7 @@ program
         process.env.GITNEXUS_EMBEDDING_DIMS = dimsEnvBaseline;
     }
 })
-    .action(createAnalyzerLbugLazyAction(() => import('../core/analyzer-identity.js'), () => import('./analyze.js'), 'analyzeCommandWithRunnerIdentity', import.meta.url));
+    .action(createAnalyzerLbugLazyAction(() => import('../core/analyzer-identity.js'), () => import('./analyze.js'), 'analyzeOrWatchCommandWithRunnerIdentity', import.meta.url));
 program
     .command('index [path...]')
     .description('Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)')
@@ -187,7 +194,7 @@ program
     .command('wiki [path]')
     .description('Generate repository wiki from knowledge graph')
     .option('-f, --force', 'Force full regeneration even if up to date')
-    .option('--provider <provider>', 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: minimax)')
+    .option('--provider <provider>', 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)')
     .option('--model <model>', 'LLM model or deployment name (default: MiniMax-M3)')
     .option('--base-url <url>', 'LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1')
     .option('--api-key <key>', 'LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)')

package/dist/cli/status.js

@@ -8,7 +8,64 @@ import { findRepo, getStoragePaths, loadMeta, hasKuzuIndex } from '../storage/re
 import { getCurrentCommit, getCurrentBranch, isGitRepo, getGitRoot, isWorkingTreeDirty, } from '../storage/git.js';
 import { analyzerRunnerIdentitiesEqual, resolveAnalyzerRunnerIdentity, } from '../core/analyzer-identity.js';
 import { getIndexIncompleteReasons } from '../core/index-freshness.js';
+import { detectIndexContentDrift } from '../core/index-content-drift.js';
 import { t } from './i18n/index.js';
+/** How many drifted paths the report names before summarizing the rest. */
+const DRIFT_SAMPLE_LIMIT = 10;
+/**
+ * Machine-readable form of the per-file comparison. `'not-checked'` is its own
+ * value rather than a silent omission: it says the index was already stale on
+ * metadata alone, so the scan was skipped, which is not the same claim as a
+ * scan that ran and found nothing.
+ */
+const describeContentDrift = (drift) => {
+    if (!drift)
+        return { status: 'not-checked' };
+    if (drift.kind === 'current') {
+        return { status: 'current', coveredFiles: drift.coveredFileCount };
+    }
+    if (drift.kind === 'unmeasurable') {
+        return { status: 'unmeasurable', reason: drift.reason };
+    }
+    return {
+        status: 'drifted',
+        counts: {
+            changed: drift.changed.length,
+            added: drift.added.length,
+            deleted: drift.deleted.length,
+        },
+        changed: drift.changed.slice(0, DRIFT_SAMPLE_LIMIT),
+        added: drift.added.slice(0, DRIFT_SAMPLE_LIMIT),
+        deleted: drift.deleted.slice(0, DRIFT_SAMPLE_LIMIT),
+        truncated: {
+            changed: drift.changed.length > DRIFT_SAMPLE_LIMIT,
+            added: drift.added.length > DRIFT_SAMPLE_LIMIT,
+            deleted: drift.deleted.length > DRIFT_SAMPLE_LIMIT,
+        },
+    };
+};
+/** Escape control characters in repo-relative paths before printing. */
+const formatDriftPath = (rel) => /[\u0000-\u001f\u007f]/.test(rel) ? JSON.stringify(rel) : rel;
+const printDriftDetail = (drift) => {
+    console.log(t('status.indexContentDrifted', {
+        changed: drift.changed.length,
+        added: drift.added.length,
+        deleted: drift.deleted.length,
+    }));
+    const labelled = [
+        [t('status.driftChanged'), drift.changed],
+        [t('status.driftAdded'), drift.added],
+        [t('status.driftDeleted'), drift.deleted],
+    ];
+    for (const [label, paths] of labelled) {
+        for (const p of paths.slice(0, DRIFT_SAMPLE_LIMIT)) {
+            console.log(`  ${label}: ${formatDriftPath(p)}`);
+        }
+        const remaining = paths.length - DRIFT_SAMPLE_LIMIT;
+        if (remaining > 0)
+            console.log(t('status.indexContentMore', { count: remaining, label }));
+    }
+};
 export const statusCommand = async (options = {}) => {
     const cwd = process.cwd();
     if (!isGitRepo(cwd)) {
@@ -63,13 +120,26 @@ export const statusCommand = async (options = {}) => {
     const currentRunnerIdentity = resolveAnalyzerRunnerIdentity(import.meta.url);
     const runnerIdentityIsCurrent = analyzerRunnerIdentitiesEqual(activeMeta.runnerIdentity, currentRunnerIdentity);
     const incompleteReasons = getIndexIncompleteReasons(activeMeta);
-    // A matching HEAD is not enough: `analyze` re-indexes a dirty working tree,
-    // so a repo with uncommitted source changes is stale even at the same commit.
-    // Skip the check for non-git folders (currentCommit === '') to match analyze.
-    const isUpToDate = currentCommit === activeMeta.lastCommit &&
+    const metadataIsCurrent = currentCommit === activeMeta.lastCommit &&
         runnerIdentityIsCurrent &&
-        incompleteReasons.length === 0 &&
-        (currentCommit === '' || !isWorkingTreeDirty(repo.repoPath));
+        incompleteReasons.length === 0;
+    // A matching HEAD is not enough: `analyze` re-indexes changed content at the
+    // same commit, so the files the index covers must still be compared against
+    // disk. Only worth the scan once the cheap metadata checks agree, and skipped
+    // for non-git folders (currentCommit === '') to match analyze.
+    const contentDrift = metadataIsCurrent && currentCommit !== ''
+        ? await detectIndexContentDrift(repo.repoPath, activeMeta.fileHashes, activeMeta.indexCoverage)
+        : undefined;
+    // The repo-wide dirty flag survives only as the fallback for metadata written
+    // before `fileHashes` existed. Where the per-file comparison can run it
+    // decides, so a file the index does not cover no longer pins a byte-current
+    // index to a "stale" verdict that `analyze` is powerless to clear (#3077).
+    const contentIsCurrent = contentDrift === undefined ||
+        contentDrift.kind === 'current' ||
+        (contentDrift.kind === 'unmeasurable' &&
+            contentDrift.reason === 'no-file-hashes' &&
+            !isWorkingTreeDirty(repo.repoPath));
+    const isUpToDate = metadataIsCurrent && contentIsCurrent;
     if (options.json) {
         console.log(JSON.stringify({
             schemaVersion: 1,
@@ -87,6 +157,7 @@ export const statusCommand = async (options = {}) => {
                 commit: currentCommit,
                 runnerIdentity: currentRunnerIdentity,
             },
+            contentDrift: describeContentDrift(contentDrift),
             status: isUpToDate ? 'up-to-date' : 'stale',
         }));
         return;
@@ -107,5 +178,19 @@ export const statusCommand = async (options = {}) => {
         console.log(`Index incomplete reasons: ${JSON.stringify(incompleteReasons)}`);
     }
     console.log(`${t('status.currentRunnerIdentity')}: ${JSON.stringify(currentRunnerIdentity)}`);
+    if (contentDrift?.kind === 'current') {
+        console.log(t('status.indexContentCurrent', { count: contentDrift.coveredFileCount }));
+    }
+    else if (contentDrift?.kind === 'drifted') {
+        printDriftDetail(contentDrift);
+    }
+    else if (contentDrift?.kind === 'unmeasurable') {
+        if (contentDrift.reason === 'scan-failed') {
+            console.log(t('status.indexContentScanFailed'));
+        }
+        else if (!isUpToDate) {
+            console.log(t('status.indexContentUnmeasurable', { reason: contentDrift.reason }));
+        }
+    }
     console.log(`${t('status.status')}: ${isUpToDate ? t('status.upToDate') : t('status.stale')}`);
 };

package/dist/cli/watch-queue.d.ts

@@ -0,0 +1,41 @@
+export type WatchRefresh = (paths: readonly string[]) => Promise<void>;
+export type WatchRefreshError = (error: unknown, paths: readonly string[]) => void;
+export declare const WATCH_FULL_REFRESH_PATH = "*";
+export interface WatchRefreshQueueOptions {
+    readonly maxWaitMs?: number;
+    readonly maxPendingPaths?: number;
+    readonly retryBaseDelayMs?: number;
+    readonly retryMaxDelayMs?: number;
+    readonly holdEventsUntilInitialRefresh?: boolean;
+    readonly isPriorityPath?: (filePath: string) => boolean;
+}
+/** Debounces filesystem events and guarantees that refreshes never overlap. */
+export declare class WatchRefreshQueue {
+    private readonly refresh;
+    private readonly onError;
+    private readonly debounceMs;
+    private readonly options;
+    private readonly pending;
+    private readonly idleWaiters;
+    private timer;
+    private active;
+    private closed;
+    private initialPending;
+    private firstPendingAt;
+    private overflowed;
+    private consecutiveFailures;
+    private retryNotBefore;
+    constructor(refresh: WatchRefresh, onError: WatchRefreshError, debounceMs: number, options?: WatchRefreshQueueOptions);
+    enqueue(filePath: string): void;
+    private addPendingPath;
+    /** Run the initial refresh while still queueing events that arrive during it. */
+    runInitial(): Promise<void>;
+    waitForIdle(): Promise<void>;
+    close(): Promise<void>;
+    private schedule;
+    private drain;
+    private runBatch;
+    private hasPendingWork;
+    private isIdle;
+    private resolveIdleWaiters;
+}

package/dist/cli/watch-queue.js

@@ -0,0 +1,184 @@
+export const WATCH_FULL_REFRESH_PATH = '*';
+/** Debounces filesystem events and guarantees that refreshes never overlap. */
+export class WatchRefreshQueue {
+    refresh;
+    onError;
+    debounceMs;
+    options;
+    pending = new Set();
+    idleWaiters = new Set();
+    timer;
+    active;
+    closed = false;
+    initialPending = false;
+    firstPendingAt;
+    overflowed = false;
+    consecutiveFailures = 0;
+    retryNotBefore;
+    constructor(refresh, onError, debounceMs, options = {}) {
+        this.refresh = refresh;
+        this.onError = onError;
+        this.debounceMs = debounceMs;
+        this.options = options;
+        this.initialPending = options.holdEventsUntilInitialRefresh === true;
+    }
+    enqueue(filePath) {
+        if (this.closed)
+            return;
+        this.addPendingPath(filePath);
+        this.firstPendingAt ??= Date.now();
+        if (!this.initialPending && this.active === undefined)
+            this.schedule();
+    }
+    addPendingPath(filePath) {
+        const maxPendingPaths = this.options.maxPendingPaths ?? 1_000;
+        const priority = this.options.isPriorityPath?.(filePath) === true;
+        if (this.pending.has(filePath)) {
+            // A duplicate does not increase memory use or imply that paths were dropped.
+        }
+        else if (this.pending.size < maxPendingPaths) {
+            this.pending.add(filePath);
+        }
+        else {
+            this.overflowed = true;
+            if (priority) {
+                const evictable = [...this.pending].find((pendingPath) => this.options.isPriorityPath?.(pendingPath) !== true);
+                if (evictable !== undefined) {
+                    this.pending.delete(evictable);
+                    this.pending.add(filePath);
+                }
+            }
+        }
+    }
+    /** Run the initial refresh while still queueing events that arrive during it. */
+    async runInitial() {
+        if (this.closed)
+            return;
+        if (this.active !== undefined)
+            throw new Error('Watch refresh is already running');
+        try {
+            await this.runBatch([], true);
+        }
+        finally {
+            this.initialPending = false;
+            if (!this.closed && this.hasPendingWork())
+                this.schedule();
+            else
+                this.resolveIdleWaiters();
+        }
+    }
+    async waitForIdle() {
+        if (this.isIdle())
+            return;
+        await new Promise((resolve) => this.idleWaiters.add(resolve));
+    }
+    async close() {
+        this.closed = true;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.pending.clear();
+        this.firstPendingAt = undefined;
+        this.overflowed = false;
+        this.consecutiveFailures = 0;
+        this.retryNotBefore = undefined;
+        // A refresh rejection is already surfaced through `onError` (or through
+        // runInitial). Closing from that handler can race the runBatch `finally`,
+        // so consume the same rejection here instead of reporting it twice.
+        await this.active?.catch(() => { });
+        this.resolveIdleWaiters();
+    }
+    schedule(retryDelayMs) {
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        const maxWaitMs = this.options.maxWaitMs ?? Math.max(this.debounceMs, 2_000);
+        const now = Date.now();
+        if (retryDelayMs !== undefined)
+            this.retryNotBefore = now + retryDelayMs;
+        const elapsed = this.firstPendingAt === undefined ? 0 : now - this.firstPendingAt;
+        const debounced = Math.max(0, Math.min(this.debounceMs, maxWaitMs - elapsed));
+        // An event arriving mid-backoff merges into the pending batch but must not
+        // pull the retry earlier than the deadline the backoff already committed to.
+        const delay = retryDelayMs ??
+            (this.retryNotBefore === undefined
+                ? debounced
+                : Math.max(debounced, this.retryNotBefore - now));
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.drain();
+        }, delay);
+    }
+    async drain() {
+        if (this.closed || this.active !== undefined || !this.hasPendingWork())
+            return;
+        const paths = [
+            ...(this.overflowed ? [WATCH_FULL_REFRESH_PATH] : []),
+            ...[...this.pending].sort(),
+        ];
+        this.pending.clear();
+        this.firstPendingAt = undefined;
+        this.overflowed = false;
+        this.retryNotBefore = undefined;
+        await this.runBatch(paths, false);
+    }
+    async runBatch(paths, propagateError) {
+        let work;
+        try {
+            work = this.refresh(paths);
+        }
+        catch (error) {
+            work = Promise.reject(error);
+        }
+        this.active = work;
+        let retryDelayMs;
+        try {
+            await work;
+            this.consecutiveFailures = 0;
+        }
+        catch (error) {
+            if (propagateError)
+                throw error;
+            try {
+                await this.onError(error, paths);
+            }
+            catch {
+                // Refresh failures are already handled here; a reporter must not
+                // reject the detached drain promise and become an unhandled rejection.
+            }
+            if (!this.closed) {
+                if (paths.includes(WATCH_FULL_REFRESH_PATH))
+                    this.overflowed = true;
+                for (const filePath of paths) {
+                    if (filePath !== WATCH_FULL_REFRESH_PATH)
+                        this.addPendingPath(filePath);
+                }
+                this.firstPendingAt = Date.now();
+                this.consecutiveFailures++;
+                const base = this.options.retryBaseDelayMs ?? Math.max(250, this.debounceMs);
+                const maximum = this.options.retryMaxDelayMs ?? 30_000;
+                retryDelayMs = Math.min(maximum, base * 2 ** (this.consecutiveFailures - 1));
+            }
+        }
+        finally {
+            if (this.active === work)
+                this.active = undefined;
+            if (!this.closed && !this.initialPending && this.hasPendingWork())
+                this.schedule(retryDelayMs);
+            else
+                this.resolveIdleWaiters();
+        }
+    }
+    hasPendingWork() {
+        return this.overflowed || this.pending.size > 0;
+    }
+    isIdle() {
+        return this.active === undefined && this.timer === undefined && !this.hasPendingWork();
+    }
+    resolveIdleWaiters() {
+        if (!this.isIdle() && !this.closed)
+            return;
+        for (const resolve of this.idleWaiters)
+            resolve();
+        this.idleWaiters.clear();
+    }
+}

package/dist/cli/watch.d.ts

@@ -0,0 +1,20 @@
+import { type AnalyzeOptions as CoreAnalyzeOptions } from '../core/run-analyze.js';
+import type { AnalyzerRunnerIdentity } from '../storage/repo-manager.js';
+import type { AnalyzeOptions } from './analyze-options.js';
+import { type WatchRefreshError } from './watch-queue.js';
+export type WatchCliOptions = AnalyzeOptions;
+export declare function isRelevantWatchPath(filePath: string): boolean;
+export interface WatchEnvironmentBaseline {
+    readonly maxFileSize: string | undefined;
+    readonly workerTimeout: string | undefined;
+    readonly verbose: string | undefined;
+}
+export declare function resolveWatchOptions(repoPath: string, cli: WatchCliOptions, baseline: WatchEnvironmentBaseline, reportIgnoredConfig?: (names: readonly string[]) => void): Promise<CoreAnalyzeOptions>;
+export interface WatchFileLoop {
+    readonly waitForIdle: () => Promise<void>;
+    readonly close: () => Promise<void>;
+}
+export declare function shouldStopAfterWatchRefreshFailure(error: unknown, paths: readonly string[]): boolean;
+/** Start the real filesystem watcher with bounded, serialized refreshes. */
+export declare function startWatchFileLoop(repoPath: string, debounceMs: number, refresh: (paths: readonly string[]) => Promise<void>, onError: WatchRefreshError, onWatcherError?: (error: unknown) => void): Promise<WatchFileLoop>;
+export declare function watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap: AnalyzerRunnerIdentity, inputPath?: string, cliOptions?: WatchCliOptions): Promise<void>;