Plan `plan-1.6.2-server-lazy-db-deps` — Daemon-code patch eliminating the structural bug where every MCP tool/call eagerly opened both CodeGraph + Data SQLite DBs at the top-level dispatcher.

Plan plan-1.6.2-server-lazy-db-deps — Daemon-code patch eliminating the structural bug where every MCP tool/call eagerly opened both CodeGraph + Data SQLite DBs at the top-level dispatcher. In any repo without .codegraph/codegraph.db, ALL tools failed — even memory/audit/knowledge tools with no logical codegraph dependency. The error surfaced as JSON-RPC code -32700 ("Parse error", spec-reserved for actual JSON parse failures) with id:null. Bug class is now structurally impossible via a typed per-tool DB-needs manifest + AST drift-guard + pattern-scanner Check 14. CR-46 / Rule 0 — replaces an implicit "every tool gets both DBs" coupling with explicit, typed, lazy resolution.

End-users on 1.5.x / 1.6.0 / 1.6.1 are unaffected in repos where .codegraph/codegraph.db is present (the prior eager-load happened to find the file). Users in fresh installs without codegraph (which became more common as 1.5.0 → 1.6.0 expanded the user base) now see correct behavior: memory tools work; codegraph-dependent tools return a structured -32001 error with remedy hint pointing at npx @colbymchenry/codegraph init.

Added

• packages/core/src/tool-db-needs.ts — typed TOOL_DB_NEEDS manifest covering all ~70 MCP tools. DbNeed = 'codegraph' | 'data' | 'memory' | 'knowledge'. getToolDbNeeds(toolName, prefix) is the single source of truth; throws UnknownToolError for tools not in the manifest. toolNeedsCodegraph() convenience predicate.
• packages/core/src/tests/server-lazy-db-deps.test.ts — 12-assertion behavior test: manifest shape, prefix-strip + UnknownToolError, toolNeedsCodegraph for codegraph-dependent vs codegraph-independent tools, CodegraphDbNotInitializedError class shape.
• packages/core/src/tests/tool-db-needs-completeness.test.ts — 19-assertion drift-guard using TypeScript Compiler API (ts.createSourceFile). Walks every *-tools.ts and listed handler module, identifies which getCodeGraphDb/getDataDb/getMemoryDb/getKnowledgeDb references the module actually uses, cross-references against TOOL_DB_NEEDS. Aliasing/destructuring rename does NOT bypass an AST walk (the structural win over grep-based completeness checks). Uses Map (not plain object) for the DB-fn lookup to prevent Object.prototype identifier matches (toLocaleString, hasOwnProperty, etc.).
• scripts/massu-pattern-scanner.sh Check 14 — grep-level safety net before tests run. Every tool registered via name: p('...') or name: \${prefix}_...\` in packages/core/src/*.ts MUST have a matching entry in TOOL_DB_NEEDS. Runs in pre-push-light.sh` step 1.
• CodegraphDbNotInitializedError in packages/core/src/db.ts — internal error class (not thrown to clients raw). Carries the resolved DB path for the dispatcher to relay.

Changed

• packages/core/src/server.ts — eliminated module-level codegraphDb/dataDb singletons + getDb() helper. New resolveDbsForTool(toolName) opens ONLY the DBs the manifest declares. tools/call handler catches CodegraphDbNotInitializedError → structured -32001 JSON-RPC error with data.remedy (verbatim codegraph init command), data.codegraphDbPath, data.tool. Catches UnknownToolError → -32602 (Invalid params). Stdio handler is now two-phase try/catch: JSON-parse failures emit spec-correct -32700 id:null; request-processing failures emit -32603 Internal error preserving the request id (was incorrectly null in 1.6.1 and prior).
• packages/core/src/tools.ts:

Removed

• Module-level eager-init of CodeGraph + Data DBs at server startup. Connections are cached lazily after first need.

Verification

• cd packages/core && PATH="/opt/homebrew/opt/node@22/bin:$PATH" npx tsc --noEmit: 0 errors
• cd packages/core && npm test: 2144 passed / 12 skipped (was 2113 baseline; +31 new tests across the 2 new vitest files: 12 in server-lazy-db-deps.test.ts + 19 in tool-db-needs-completeness.test.ts)
• bash scripts/pre-push-light.sh (Node 22): ALL 7 GATES PASS (including new Check 14 — Tool DB-needs manifest completeness)
• End-to-end reproducer from /tmp/repro-fixed/ (NO .codegraph/codegraph.db):
• bash scripts/massu-plan-status-validator.sh: PASS
• bash scripts/massu-plan-commit-drift.sh: PASS

Closes

• Plan plan-1.6.2-server-lazy-db-deps audit converged at 0 gaps after 3 iterations (16 → 2 → 0).
• The root cause of the 2026-05-10 in-session "MCP tools hanging" investigation (see feedback_mcp_pin_version_in_mcp_json.md). The hang turned out to be a stale 1.4.0-soak.0 global install (separately fixed by .mcp.json pin in commit f6fa6ff), but THIS plan eliminates the underlying server bug that would have caused identical symptoms in any clean install without codegraph.