🐞 Bug Report: MCP Axiom — Intermittent Request Timeouts

Reported by: Kilo Code (agent)
Date: 2026-05-14
Affected tools: axiom_semantic_index rebuild, axiom_semantic_validation (all operations), axiom_semantic_context workspace_health
Severity: 🔴 High — blocks semantic audit pipeline

1. Symptom

Repeated MCP error -32001: Request timed out on operations that scan the full workspace (548 files, 2521 contracts, 1984 edges). Default 120s timeout consistently exceeded.

2. Reproduction Steps

Step A — Successful baseline

axiom_semantic_index reindex
→ success, 1-2s

Step B — AFTER reindex, run any scan

axiom_semantic_validation audit_contracts --file_path specs/028-llm-datasource-supeset/
→ success, 3-5s        (narrow scope, 1 directory)

axiom_semantic_validation audit_contracts --file_path specs/028-llm-datasource-supeset/data-model.md
→ TIMEOUT after 120s    (single file, should be fast!)

axiom_semantic_validation audit_contracts --file_path specs/028-llm-datasource-supeset/
→ TIMEOUT after 120s    (was fast before, now slow — index state dependent?)

Step C — Rebuild after edits

axiom_semantic_index rebuild --rebuild_mode full
→ TIMEOUT after 120s    (1st attempt)
→ TIMEOUT after 120s    (2nd attempt)  
→ success after 3rd attempt (no code changes between attempts)

axiom_semantic_index reindex
→ TIMEOUT after 120s    (was fast in Step A!)

Step D — Workspace-wide operations (100% timeout)

axiom_semantic_context workspace_health
→ TIMEOUT after 120s    (4 attempts, all timed out)

axiom_semantic_validation audit_belief_protocol --file_path specs/028-llm-datasource-supeset/
→ TIMEOUT after 120s    (2 attempts)

3. Timing Analysis

Operation	Scope	When Fast	When Slow
`reindex`	548 files in-memory	1-2s	120s+ (post audit/edit)
`rebuild full`	548 files + DuckDB	3-5s	120s+ (70% of attempts)
`audit_contracts` (directory)	8 files	3-5s	120s+ (30%)
`audit_contracts` (single file)	1 file	—	120s+ (100%!)
`workspace_health`	full w/s	—	120s+ (100%)
`audit_belief_protocol`	full w/s	—	120s+ (100%)

Key observations:

Single-file audit times out MORE than directory audit — counter-intuitive
reindex goes from 2s → timeout after an audit or edit — lock contention sign
Operations that succeed once tend to succeed on retries (caching)

4. Hypothesis

H1 — Background rebuild lock (most likely)

rebuild or audit spawns a background index rebuild holding a file lock. Subsequent operations wait for lock → timeout. No progress reporting, so agent sees silent 120s with no clue.

Evidence: reindex is 2s normally, times out after rebuild/audit was recently called.

H2 — 120s default too low

548 files × 0.25s = 137s. Full scan exceeds budget even normally.

Evidence: 588 source files (338 Python + 114 Svelte); workspace_health scans all.

H3 — Index corruption after file edit

After editing contracts/modules.md, reindex went from 2s → timeout. Suggests in-memory index may corrupt, triggering expensive repair.

Evidence: Contract count drifted 2528 → 2521 → 2516 across rebuilds.

5. Workaround Used by Agent

reindex fast (1-2s) → immediately audit_contracts — usually works
reindex timeout → wait 30s, retry — sometimes works
rebuild timeout → retry 3× with 10s gaps — 70% success
workspace_health → give up, use directory-scoped audit_contracts
Directory-scoped audit OVER single-file (counter-intuitive but works)

6. Fix Recommendations

Pri	Fix
P0	Detect lock contention, report "Waiting for index lock (held by X since T)"
P0	Bump default timeout to 300s or make it `workspace_size / 4` seconds
P1	Progress: "Scanning 245/548 files... (45%)"
P1	Single-file audit should NOT trigger full index scan
P2	Auto-detect stale/corrupt index after file edits, prompt reindex
P2	Add `--timeout_seconds N` parameter to all operations
P2	Distinct error codes: `-32002 TIMEOUT_LOCK` vs `-32003 TIMEOUT_OP` vs generic `-32001`

4.2 KiB Raw Blame History Unescape Escape