Resolves #13464
This hardens the Knowledge Base MCP health/gate path for unified Chroma. A stale resolved KB collection handle now gets invalidated and retried once when count() returns a Chroma not-found/resource-not-found error; connected Chroma with unavailable corpus now reports degraded instead of a daemon-level unhealthy; provider readiness is still evaluated; and manage_knowledge_base is exempted from the full corpus-health gate so recovery/sync can run.
Evidence: L2 (focused unit tests for stale-handle retry, degraded health payload, and recovery-tool exemption) -> L2 required (close-target ACs are service/MCP contract behavior covered by unit tests). No residuals.
Deltas from ticket
- Kept the payload shape compatible and documented the revised health semantics in
openapi.yaml.
- Did not implement a cross-process invalidation bus or restore/rebuild the KB corpus; those remain explicitly out of scope.
Test Evidence
npm run test-unit -- test/playwright/unit/ai/services/knowledge-base/HealthService.providerReady.spec.mjs test/playwright/unit/ai/services/knowledge-base/ChromaManager.spec.mjs test/playwright/unit/ai/mcp/server/knowledge-base/Server.spec.mjs -> 20 passed.
git diff --check -> passed.
- Commit hook passed whitespace, shorthand, AiConfig mutation, JSDoc types, and ticket archaeology checks.
Post-Merge Validation
Commits
90171b499 — fix(ai): recover KB stale collection handles (#13464)
Authored by Euclid (GPT-5 Codex, Codex Desktop). Session 4ce60429-2986-4543-be2d-741957c75b6c.
Resolves #13464
This hardens the Knowledge Base MCP health/gate path for unified Chroma. A stale resolved KB collection handle now gets invalidated and retried once when
count()returns a Chroma not-found/resource-not-found error; connected Chroma with unavailable corpus now reportsdegradedinstead of a daemon-levelunhealthy; provider readiness is still evaluated; andmanage_knowledge_baseis exempted from the full corpus-health gate so recovery/sync can run.Evidence: L2 (focused unit tests for stale-handle retry, degraded health payload, and recovery-tool exemption) -> L2 required (close-target ACs are service/MCP contract behavior covered by unit tests). No residuals.
Deltas from ticket
openapi.yaml.Test Evidence
npm run test-unit -- test/playwright/unit/ai/services/knowledge-base/HealthService.providerReady.spec.mjs test/playwright/unit/ai/services/knowledge-base/ChromaManager.spec.mjs test/playwright/unit/ai/mcp/server/knowledge-base/Server.spec.mjs-> 20 passed.git diff --check-> passed.Post-Merge Validation
healthcheckto confirm live diagnostics use the updated degraded/healthy semantics against the current corpus state.Commits
90171b499—fix(ai): recover KB stale collection handles (#13464)Authored by Euclid (GPT-5 Codex, Codex Desktop). Session 4ce60429-2986-4543-be2d-741957c75b6c.