proffesor-for-testing__agentic-qe/docs/releases/v3.9.3.md

v3.9.3 Release Notes

Release Date: 2026-04-06

Highlights

Proper long-lasting fix for the aqe init --auto hang and cascade of errors introduced in the v3.9.1 / v3.9.2 series. v3.9.2 only closed one of the deadlocks; this release addresses the remaining root causes across five independent failure modes and preserves all v3.9.1 feature benefits (RVF pattern store, unified HNSW, agent memory branching, KG semantic search).

What was broken

Running aqe init --auto on real projects produced one of three symptoms depending on the codebase:

1. Hang in phase 06 code-intelligence pre-scan — A single pathological source file or a native-layer stall (e.g. @ruvector/rvf-node fsync on a Codespace overlay filesystem) could block the indexer indefinitely with no diagnostic. The v3.9.2 fix was for a different deadlock and did not cover this path.
2. Cascade of cosmetic errors — [RVF] Shared adapter init failed: FsyncFailed, VectorDb creation failed: Database already open. Cannot acquire lock., Error: Could not find MCP server entry point. All emitted by a spawned MCP daemon child process racing the parent for file locks it could never acquire.
3. Every CLI command opened patterns.rvf and memory.db at startup — aqe --version, aqe --help, and aqe init all grabbed exclusive file locks before commander had even parsed argv, holding them for the entire lifetime of the command. This was the root cause of the lock contention in (2).

Fixes

Fix 1 — HnswAdapter dispose plumbing

Added the dispose() contract to IHnswIndexProvider and wired it through NativeHnswBackend (nulls nativeDb) and ProgressiveHnswBackend (no-op). HnswAdapter.close(name) now disposes the backend before removing the registry entry. The UnifiedMemoryManager.close() path continues to keep the qe-memory adapter alive across resets (the native VectorDb is process-global and cannot be re-created in the same process), but tests and explicit shutdowns can now release native resources cleanly via HnswAdapter.close().

Fix 2 — Lazy TokenOptimizerService lifecycle

TokenOptimizerServiceImpl.initialize() is now a lazy registration: it stores the memory backend reference and config but defers pattern-store creation until the first checkEarlyExit() or storePattern() call. ensurePatternStoreReady() is race-safe (shared readyPromise) and degrades to session-cache-only mode on failure.

Consequences: aqe --version, aqe --help, aqe init, aqe status, aqe health, aqe hooks, and aqe daemon no longer open patterns.rvf or memory.db at CLI startup. The bootstrap noise lines ([PatternStore] Using RVF-backed store (ADR-066), [RvfPatternStore] Initialized, [UnifiedMemory] Migrating from v0 to v9, [SQLitePatternStore] Using unified storage) are gone from command output unless the command actually uses pattern search.

Fix 3 — Phase 10 Workers no longer spawns MCP daemon

The startDaemon() / findMcpCommand() helpers have been removed. The canonical path for starting the MCP server is .mcp.json (written by phase 08) — Claude Code reads it and starts aqe mcp on demand when a user actually opens the project. Users who want to run the daemon manually can still use the generated .agentic-qe/workers/start-daemon.cjs helper script or the aqe daemon subcommand. Phase 10 now completes in ~1 ms instead of ~1500 ms.

Fix 4 — findMcpEntry() robustness for bundled/global installs

v3.9.0's esbuild code-splitting placed CLI chunks under dist/cli/chunks/, breaking the fixed __dirname + '..' paths the aqe mcp command used to locate dist/mcp/bundle.js. findMcpEntry() now walks up to the nearest package.json with name=agentic-qe via the existing findPackageRoot() helper, with legacy sibling-path fallback for dev mode and an extra chunk-split candidate.

Fix 5 — Phase 06 watchdog + per-file progress

The biggest reliability improvement. Phase 06 now drives indexing file-by-file with:

• Per-file timeout: 30 seconds. A single pathological file is skipped with a warning; the rest of the codebase still indexes.
• Phase-level timeout: 180 seconds. Partial results are preserved (all entries indexed so far are kept) and the warning names the file that was being processed when the cap fired. Users paste that filename into an issue and the underlying native-layer cause can be fixed in a targeted follow-up.
• Progress logs: Indexed X/Y files every 100 files. No more silent hangs.

All KG semantic-search features (vector embeddings, knowledge graph, hypergraph) remain fully enabled. The watchdog is a reliability guarantee, not a feature reduction.

Verification

Scenario	v3.9.2	v3.9.3
Empty project fresh init	1787 ms, Error: Could not find MCP server entry point	436 ms, exit 0, clean
200-file TS fixture	not timed (similar)	621 ms, exit 0, progress logs
15 k-entity heavy fixture	3401 ms	2167 ms, exit 0
Pre-existing .agentic-qe/ + aqe --version	6+ lines bootstrap noise, opens patterns.rvf	1 line 3.9.3, no file opened
aqe mcp --help	Error: Could not find MCP server entry point	Prints usage, exit 0

Targeted test results:

• token-optimizer-service: 17/17 pass
• native-hnsw-backend / hnsw-legacy-bridge / hnsw-unification: 99/99 pass
• unified-memory: 53/53 pass
• pattern-store / rvf-pattern-store: 65/65 pass
• init/orchestrator / init/phases/database-phase: 32/32 pass

What we deliberately did NOT change

• useRVFPatternStore / useUnifiedHnsw / useAgentMemoryBranching feature flag defaults. These stay true. v3.9.1's RVF features are load-bearing for ADR-066/067/071 and flipping them would defeat the v3.9.1 rollout.
• Any .db or .rvf files on disk. Per CLAUDE.md data-protection rules.
• The v3.9.2 fix itself. The createPatternStore → getSharedRvfAdapter routing still applies; this release adds to it rather than replacing it.

Upgrading

# Claude Code users:
claude mcp add agentic-qe -- npx -y agentic-qe@3.9.3
aqe init --auto

# Global install:
npm install -g agentic-qe@3.9.3
aqe init --auto

No manual migration needed. If aqe init --auto was hanging in v3.9.1 or v3.9.2, the upgrade resolves it. If the phase 06 watchdog fires on your project, it will name the exact file responsible — please open an issue with that filename at https://github.com/proffesor-for-testing/agentic-qe/issues so we can fix the underlying cause.

User-perspective verification

Run any of these on your project to confirm the fix:

# 1. The ruview hang scenario — must complete within 180 seconds.
cd /path/to/your/project
rm -rf .agentic-qe CLAUDE.md .claude .mcp.json
time aqe init --auto

# 2. No more bootstrap noise on --version.
aqe --version   # Must print exactly one line: 3.9.3

# 3. MCP command works.
aqe mcp --help  # Must print usage, exit 0

# 4. No cascade errors on fresh projects.
cd /tmp && mkdir fresh && cd fresh && echo "export const x = 1;" > a.ts
aqe init --auto 2>&1 | grep -E "Error:|ERROR|FsyncFailed|Database already open|Could not find MCP"
# ^ Must print nothing.