diff --git a/docs/mcp-reference.md b/docs/mcp-reference.md index 15d11ef74..211dc8b7b 100644 --- a/docs/mcp-reference.md +++ b/docs/mcp-reference.md @@ -83,7 +83,7 @@ A local server started with `GITNEXUS_MCP_ENABLE_REFRESH=1` also lists `refresh_ - **Index-only.** The rebuild runs in the same forked analyze worker auto-sync uses, with `--skip-agents-md --skip-skills`: no `AGENTS.md`, `CLAUDE.md`, skill, hook, or other repository file is written. It is incremental where it can be and keeps existing embeddings and PDG mode. - **Local only.** `gitnexus serve` (and so the Docker `/api/mcp` surface) never lists it, whatever its environment. With `GITNEXUS_MCP_READ_ONLY=1` it is hidden from discovery and rejected before dispatch. -- **Bounded.** Before starting, the server counts the repository's working tree the way analyze scans it (same patterns and ignore rules, stopping one past the limit) and refuses it when that count exceeds `GITNEXUS_MCP_REFRESH_MAX_FILES` (default `5000`; `0` for no limit, and no count). The count is taken before size filtering, so it can exceed what analyze then indexes. `dry_run` reports it as `estimatedFiles` (`null` when over the limit or with no limit) next to the last index's `lastIndexedFiles`. After `GITNEXUS_MCP_REFRESH_TIMEOUT_MS` (default ten minutes) the call stops waiting and returns an error. The analyze worker never interrupts an analysis it has started, so it finishes in the background and keeps the index lock until then; a later refresh waits on that lock. Cancelling the request does not stop a started rebuild either: it finishes and publishes, and until it does a new call gets "already running" and `dry_run` reports `inProgress`. Only one refresh per repository runs at a time. The file limit does not bound embedding generation, which `.gitnexusrc` can request. +- **Bounded.** Before starting, the server counts the repository's working tree the way analyze scans it (same patterns and ignore rules, stopping one past the limit) and refuses it when that count exceeds `GITNEXUS_MCP_REFRESH_MAX_FILES` (default `5000`; `0` for no limit, and no count). The count is taken before size filtering, so it can exceed what analyze then indexes. `dry_run` reports it as `estimatedFiles` (`null` when over the limit or with no limit) next to the last index's `lastIndexedFiles`. After `GITNEXUS_MCP_REFRESH_TIMEOUT_MS` (default ten minutes) the call stops waiting and returns an error. The analyze worker never interrupts an analysis it has started, so it finishes and publishes in the background, holding the index lock until then. Cancelling the request does not stop a started rebuild either. After timeout or cancellation, a new call gets "already running" and `dry_run` reports `inProgress` until the worker exits. Only one refresh per repository runs at a time. The file limit does not bound embedding generation, which `.gitnexusrc` can request. - **Observable.** `dry_run: true` reports staleness, the indexed file count, whether `.gitnexusrc` makes the rebuild generate embeddings, and whether a refresh would run. A real call waits for the rebuild and returns `indexedAt`, `lastCommit`, `stats`, and `staleness`, with the values before the refresh under `previous`. A rebuild whose graph write collapsed is reported as an error, as `gitnexus analyze` and `serve` report it. Clients that send a progress token receive progress notifications; the MCP TypeScript SDK client gives up on a request after 60 seconds by default unless it resets that timeout on progress. The tool takes `repo` and `dry_run` only. Like an applied `rename`, it needs an explicit `repo` unless one repository is indexed or an MCP default is configured. diff --git a/gitnexus/src/core/auto-sync/analysis-worker-launch.ts b/gitnexus/src/core/auto-sync/analysis-worker-launch.ts index 6dc03eabb..9216754ca 100644 --- a/gitnexus/src/core/auto-sync/analysis-worker-launch.ts +++ b/gitnexus/src/core/auto-sync/analysis-worker-launch.ts @@ -38,6 +38,8 @@ export class AutoSyncAnalysisError extends Error { readonly code?: 'index-lock-timeout'; readonly retryable?: boolean; readonly abandonedWorker: boolean; + /** Resolves on actual process exit when the request stopped waiting first. */ + readonly workerExited?: Promise; constructor( message: string, @@ -45,6 +47,7 @@ export class AutoSyncAnalysisError extends Error { code?: 'index-lock-timeout'; retryable?: boolean; abandonedWorker?: boolean; + workerExited?: Promise; } = {}, ) { super(message); @@ -52,6 +55,7 @@ export class AutoSyncAnalysisError extends Error { this.code = options.code; this.retryable = options.retryable; this.abandonedWorker = options.abandonedWorker === true; + this.workerExited = options.workerExited; } } @@ -168,12 +172,15 @@ export function createAutoSyncAnalysisRunner( // child is deliberately left running rather than killed mid-write. graceTimer = deps.setTimeoutFn(() => { if (settled) return; + const workerExited = new Promise((resolveExited) => { + child.on('exit', () => resolveExited()); + }); releaseChild(); settle( new AutoSyncAnalysisError( `${error.message} The analyze worker did not exit within ${deps.cancelGraceMs}ms; ` + 'it was left running so its native work is not interrupted.', - { abandonedWorker: true, retryable: true }, + { abandonedWorker: true, retryable: true, workerExited }, ), ); }, deps.cancelGraceMs); diff --git a/gitnexus/src/mcp/local/local-backend.ts b/gitnexus/src/mcp/local/local-backend.ts index 68e9d10a8..56a732438 100644 --- a/gitnexus/src/mcp/local/local-backend.ts +++ b/gitnexus/src/mcp/local/local-backend.ts @@ -3312,6 +3312,7 @@ export class LocalBackend { this.refreshesInFlight.add(repo.storagePath); const startedAt = Date.now(); let analysis: Awaited>; + let workerExited: Promise | undefined; try { analysis = await runAutoSyncAnalysis( repo.repoPath, @@ -3329,17 +3330,23 @@ export class LocalBackend { context.onProgress, ); } catch (err) { - // After a timeout the worker is left to finish the analysis and still - // holds the index lock, so a retry waits on it rather than racing it. + const failure = err as { + abandonedWorker?: boolean; + workerExited?: Promise; + } | null; + // The request can time out before its worker releases the index lock. + if (failure?.abandonedWorker) workerExited = failure.workerExited; const leftRunning = - (err as { abandonedWorker?: unknown } | null)?.abandonedWorker === true - ? ' Its worker keeps running until the analysis finishes; a new refresh waits on its index lock.' + failure?.abandonedWorker === true + ? ' Its worker keeps running until the analysis finishes; another refresh is refused until it exits.' : ''; return { error: `Refresh of ${repo.name} failed: ${asSentence(err)}${leftRunning} Run \`gitnexus analyze\` in the repository for the full log.`, }; } finally { - this.refreshesInFlight.delete(repo.storagePath); + const releaseSlot = () => this.refreshesInFlight.delete(repo.storagePath); + if (workerExited) void workerExited.then(releaseSlot); + else releaseSlot(); } await this.refreshRepos(); diff --git a/gitnexus/test/unit/auto-sync-analysis-worker.test.ts b/gitnexus/test/unit/auto-sync-analysis-worker.test.ts index 1bb5c83e6..7c88323cf 100644 --- a/gitnexus/test/unit/auto-sync-analysis-worker.test.ts +++ b/gitnexus/test/unit/auto-sync-analysis-worker.test.ts @@ -250,7 +250,7 @@ describe('auto-sync analysis worker', () => { await expect(solo).resolves.toEqual({ stats: { files: 1 } }); }); - it('stops waiting for a worker that never exits after cancellation', async () => { + it.each([0, 1])('tracks an abandoned worker until exit (%s)', async (exitCode) => { const child = Object.assign(createChild(), { unref: vi.fn(), channel: { unref: vi.fn() }, @@ -269,7 +269,7 @@ describe('auto-sync analysis worker', () => { timers[0]!(); expect(child.send).toHaveBeenLastCalledWith({ type: 'cancel' }); - // No 'exit' ever arrives — the worker is wedged past its safe point. + // No 'exit' arrives during the grace period. timers[1]!(); await expect(result).rejects.toThrow('did not exit within'); @@ -282,6 +282,18 @@ describe('auto-sync analysis worker', () => { expect(child.channel.unref).toHaveBeenCalled(); expect(child.unref).toHaveBeenCalled(); expect(child.send).toHaveBeenCalledTimes(2); + + const failure = (await result.catch((error) => error)) as AutoSyncAnalysisError; + expect(failure.workerExited).toBeInstanceOf(Promise); + const exited = vi.fn(); + void failure.workerExited?.then(exited); + // A late completion message is not proof that the process has exited. + child.emit('message', { type: 'complete', result: { stats: { files: 1 } } }); + await Promise.resolve(); + expect(exited).not.toHaveBeenCalled(); + child.emit('exit', exitCode, null); + await failure.workerExited; + expect(exited).toHaveBeenCalledOnce(); }); it('uses the same cancellation request for an aborted watch run', async () => { diff --git a/gitnexus/test/unit/local-backend-refresh-index.test.ts b/gitnexus/test/unit/local-backend-refresh-index.test.ts index 201553bb2..18a456a97 100644 --- a/gitnexus/test/unit/local-backend-refresh-index.test.ts +++ b/gitnexus/test/unit/local-backend-refresh-index.test.ts @@ -250,16 +250,36 @@ describe('LocalBackend refresh_index (#3524)', () => { expect(list.repositories[0].lastCommit).toBe('new'); }); - it('says when a timed-out worker was left running', async () => { + it('keeps a timed-out refresh busy until its abandoned worker exits', async () => { + let finishWorker!: () => void; + const workerExited = new Promise((resolve) => { + finishWorker = resolve; + }); mocks.runAutoSyncAnalysis.mockRejectedValueOnce( Object.assign(new Error('Analysis timed out after 5ms. The analyze worker did not exit'), { abandonedWorker: true, + workerExited, }), ); const result = await backend.callTool('refresh_index', { repo: 'shop' }); + expect(result.error).toContain('Its worker keeps running until the analysis finishes'); + await expect(backend.callTool('refresh_index', { repo: 'shop' })).resolves.toMatchObject({ + error: expect.stringContaining('already running'), + }); + await expect( + backend.callTool('refresh_index', { repo: 'shop', dry_run: true }), + ).resolves.toMatchObject({ wouldRefresh: false, inProgress: true }); + expect(mocks.runAutoSyncAnalysis).toHaveBeenCalledTimes(1); + + finishWorker(); + await workerExited; + await expect(backend.callTool('refresh_index', { repo: 'shop' })).resolves.toMatchObject({ + status: 'refreshed', + }); + expect(mocks.runAutoSyncAnalysis).toHaveBeenCalledTimes(2); expect(result.error).toBe( 'Refresh of shop failed: Analysis timed out after 5ms. The analyze worker did not exit. ' + - 'Its worker keeps running until the analysis finishes; a new refresh waits on its index lock. ' + + 'Its worker keeps running until the analysis finishes; another refresh is refused until it exits. ' + 'Run `gitnexus analyze` in the repository for the full log.', ); });