Skip to content

v4.9.1 — Critical hotfix: reindex loop on Windows stdio MCP

Choose a tag to compare

@lyonzin lyonzin released this 28 Sep 21:29
· 48 commits to master since this release
9ae3d09

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_preflight now retries PROBE_ATTEMPTS=3 × PROBE_RETRY_DELAY_SECONDS=5 before quarantining — transient file-lock, cold GPU init, or slow disk failures no longer trigger destructive moves.
  • subprocess.TimeoutExpired is caught and treated as inconclusive (keeps the index).
  • Quarantine uses os.rename (atomic on same volume) instead of shutil.move (whose copy-tree + rmtree fallback left partial copies AND a partially deleted live chroma_db/ on WinError 32).
  • os.rename failures exit with EX_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 existing orchestrator.start_reindex_background("incremental") (v4.3.0+) for the initial index. Transport starts serving immediately; client polls get_reindex_status for progress.
  • Migration path (nuclear_rebuild after 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_ATTEMPTS count guard
  • 3 in tests/test_main_startup.py — start_reindex_background (not index_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

Full changelog

See CHANGELOG.md → v4.9.1

Related PRs

  • #217 — code fix + tests
  • #218 — release packaging