fix: robust MCP startup root resolution and deferred scan fallback

[idea404]

Linked Issues

Closes #502

Related (already closed): #384, #371, #278

Summary

codedb mcp was fragile when launched by MCP clients (opencode, Claude Code, etc.) from an unexpected cwd or without usable roots. The server entered scan=loading_snapshot with files=0 and never recovered, producing a functionally empty MCP server. codedb mcp --help also started the server instead of printing help, and unknown flags like --snapshot were silently ignored.

Root Resolution Order (after fix)

1. Explicit path: codedb mcp /path/to/repo or codedb /path mcp
2. CODEDB_ROOT env var
3. Git root from cwd (new — git rev-parse --show-toplevel)
4. MCP client roots via roots/list handshake
5. cwd fallback (after 3s timeout or if client has no roots capability)

Files Changed

File	Change
src/git.zig	Added getGitRoot() function (+24 lines)
src/main.zig	MCP arg parsing (--help, [path], flag rejection), git root detection, flush before exit, terminal ready state when no indexable root (+65 lines)
src/mcp.zig	Fallback to cwd on roots/list error, missing result, or malformed roots array (+40 lines)
src/test_mcp.zig	7 new unit tests (+164 lines)
scripts/e2e_mcp_test.py	4 new E2E scenarios / 13 tests (+219 lines)

Total: 506 lines (over 500-line guideline due to comprehensive test coverage)

Tests Run

zig build test
# 626/626 pass

python3 scripts/e2e_mcp_test.py --binary zig-out/bin/codedb --project /Users/dennis/Projects/codedb
# 30/30 pass

Before (failing behavior)

cd /Users/dennis/Projects/personal
codedb snapshot        # snapshot has 17 files
codedb mcp             # files=0 scan=loading_snapshot (stuck)
codedb mcp --help      # starts MCP server instead of showing help
codedb mcp --snapshot  # silently ignored, starts server

After (fixed behavior)

codedb mcp --help      # prints usage, exits 0
codedb mcp --snapshot  # ✗ unknown flag for mcp: --snapshot (exits 1)
codedb mcp             # resolves git root from cwd, scans correctly
codedb mcp /path       # indexes explicit path immediately

Non-Regression

• All existing E2E scenarios (S1-S3) still pass
• Existing unit tests for ScanState, root_policy, deferred scan, bundle, telemetry all pass
• codedb <root> mcp (positional root before command) still works as before

Rebase

Rebased onto current upstream/main (commit 6317fe8).

Generated Files

No generated files committed. codedb.snapshot was restored to its original state.

Confirmation

This submission matches CONTRIBUTING.md requirements:

• Tied to issue fix: codedb mcp stuck in loading_snapshot with files=0 when launched from unexpected cwd #502
• Rebased onto current main
• Tightly scoped (one bug fix)
• No generated artifacts
• Tests included and passing

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 265de894e3

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[idea404]

Good catch — fixed in 35cc057.

The issue was that triggerDeferredScanWithFallback returns false in two distinct cases:

1. Already triggered — ds.triggered.swap() returns true (a roots response fired the scan just before the 3s timeout)
2. No usable path — both roots and cwd fallback are empty/denied

The original code treated both the same way, prematurely marking scan_done = true and scan_state = .ready even when a background scan was already in-flight.

Fix: Check ds.triggered.load(.acquire) before calling the trigger function. Only transition to ready when both conditions hold:

• triggerDeferredScanWithFallback returned false
• ds.triggered was not already true

If already_triggered is true, the scan thread is running and will set ready when it finishes — the loop continues waiting on ctx.scan_done as before.

Added a regression test (triggerDeferredScanWithFallback returns false when already triggered (race)) that pre-sets ds.triggered = true and verifies the function returns false without firing a second scan.

All 30/30 E2E tests and 626/626 unit tests pass.

[justrach]

Hey @idea404, thanks for the very thorough PR — fully verified locally and security-clean. Wanted to flag something + ask how you'd like to proceed.

Status

Most of what this PR fixes shipped in v0.2.5821 (merged via #509 / #510). The 2026-05-28 release closed #502 along with six other issues triaged the same day. The MCP arg-parser overhaul, mcp --help, unknown-flag rejection, git-root detection, and the deferred-scan terminal-ready transition all landed there — implemented slightly differently (pure-Zig .git walk vs git rev-parse, factored parsePositional, Out.exitWithFlush helper) but with the same observable behavior.

What's genuinely additive in this PR

Your handleResponse changes in src/mcp.zig cover four roots/list error paths I missed in v0.2.5821:

1. Client replies with error field → cwd fallback
2. Client replies without result field → cwd fallback
3. result present but not an object → cwd fallback
4. roots field missing or not an array → cwd fallback

My version only handled the post-timeout cwd fallback in watcherDeferredLoop, which means a fast-but-malformed client reply would still leave the server in deferred mode until the 13 s timeout fires. Your path catches those cases immediately. This part is worth shipping.

How would you like to proceed?

• (a) Close this PR as superseded by v0.2.5821, and I'll open a follow-up that cherry-picks just the mcp.zig roots/list error-path fallbacks. Credits you in the commit.
• (b) You trim this PR down to just the mcp.zig changes (drop git.zig, main.zig, test_mcp.zig, e2e_mcp_test.py since those are now redundant with what's on main) and we merge that.
• (c) Something else — happy to hear what works for you.

Either way, thanks for the careful test coverage — the new e2e scenarios are nice; we may want to keep S6 ("empty roots/list falls back to cwd") and S7 ("stdout stays clean") in some form.