Repository navigation
v4.9.1 — Critical hotfix: reindex loop on Windows stdio MCP
Critical hotfix for #216 — Windows stdio MCP reindex loop
Diagnosis and validated patch by @HillsCloud in the #216 comment thread — thank you for the forensic-level reproduction and the working diffs.
Who should upgrade
- Anyone on Windows using knowledge-rag through a stdio MCP client (Claude Code, Claude Desktop, etc.)
- Anyone with 5k+ documents / ~150k+ chunks on any OS — the initial-index blocking bug is cross-platform, Windows only made it critical
What was broken
On Windows/stdio, an initial full index (or any startup after a Chroma preflight hiccup) blocked the MCP initialize handshake past client timeout. The client killed the server, restarted it into a half-written index, preflight quarantined the entire chroma_db/ after a single failed probe, and the server started full-corpus reindexing from zero — every restart. Users reported tens of GB of auto-repair-* backups accumulating over the loop.
What was fixed
fix(preflight)
run_preflightnow retriesPROBE_ATTEMPTS=3×PROBE_RETRY_DELAY_SECONDS=5before quarantining — transient file-lock, cold GPU init, or slow disk failures no longer trigger destructive moves.subprocess.TimeoutExpiredis caught and treated as inconclusive (keeps the index).- Quarantine uses
os.rename(atomic on same volume) instead ofshutil.move(whose copy-tree + rmtree fallback left partial copies AND a partially deleted livechroma_db/on WinError 32). os.renamefailures exit withEX_TEMPFAIL(75) instead of crashing halfway.- Every probe attempt appended to
data/preflight.log— stdio MCP clients hide stderr, so file logs are the only way to post-mortem.
fix(server)
main()now uses the existingorchestrator.start_reindex_background("incremental")(v4.3.0+) for the initial index. Transport starts serving immediately; client pollsget_reindex_statusfor progress.- Migration path (
nuclear_rebuildafter embedding-model change) intentionally left synchronous — follow-up issue will add a guarded async path with a "reindex in progress" error envelope.
Regression coverage
7 new tests locked against future refactors:
- 4 in
tests/test_preflight.py— transient recovery, timeout inconclusive, rename-failure exit code,PROBE_ATTEMPTScount guard - 3 in
tests/test_main_startup.py—start_reindex_background(notindex_all) called for empty collections, no indexing when collection is populated, transport starts BEFORE indexing completes
Compatibility
- Zero API surface changes (
check_api_surface --check→ OK) - Forward-compatible with 4.9.0 — no config migration, no data migration
- 9-cell CI matrix green: Linux + Windows + macOS × Python 3.11 + 3.12 + 3.13