fix(mcp): keep an explicit projectPath project in sync (#1835)

[danusha2345]

Symptom

A single MCP server started in an un-indexed workspace whose children each have their own .codegraph/ (the multiple-indexed-children case from #1606/#1607) can query each child through projectPath, but those projects were opened read-only: no catch-up sync on open and no file watcher. Renaming or adding an exported function in a child and querying it again after the debounce window returned the old index until someone ran codegraph sync by hand. The same applied to any projectPath other than the server's default project.

Fix

The engine now owns the lifecycle of every project the ToolHandler opens for an explicit projectPath, mirroring what the default project already gets:

• Writer lock first (Concurrent codegraph serve --mcp instances on one project block auto-sync and fail codegraph index with EPERM #1740 single-writer rule). The project's writer.pid is acquired; if another live process (its own shared daemon, another direct-mode session) holds it, that process keeps syncing and this session only reads — no contention on codegraph.lock, and stop() leaves the foreign lock untouched.
• Catch-up sync on open. sync() runs when the project is first opened, and the first tool call that names that project awaits it, time-boxed exactly like the default project's gate (v1.0.1, serve --mcp --no-watch -p <monorepo>, after container restart, the first tools/call is unresponsive; CODEGRAPH_NO_DAEMON=1 can reproduce the recovery process. #905). Edits made while no server was running are visible on the first call.
• Watcher while cached. watch() runs for as long as the project stays in the cache, with the same debounce / degraded handling as the default project (the callbacks are now one shared watchOptions() in the engine).

Nothing changes for un-indexed paths: they still get the success-shaped "not indexed" guidance, never isError, and are never indexed.

Bounds

• The cache is keyed by the canonical (realpath) root, so a symlinked spelling or a sub-path of a project shares one connection, one watcher and one lock.
• LRU, MAX_CACHED_PROJECTS = 8. Opening a ninth distinct project closes the least recently used one: watcher stopped, writer lock released, DB closed. Many projectPath values leak nothing; a re-visit pays a reopen plus a catch-up.
• MCPEngine.stop() closes every cached project and releases every lock it took.
• The CLI's and the worker-thread handlers set no lifecycle, so they behave as before (read-only, no watcher).

Verification

• npx tsc --noEmit -p tsconfig.json — exit 0.
• New __tests__/mcp-projectpath-lifecycle.test.ts (3 tests, engine at an un-indexed workspace with two indexed children, driven through MCPEngine.getToolHandler().execute): a pre-start edit is caught up on the first projectPath call and a later edit is picked up by the watcher; three spellings of one root (direct, symlink, sub-path) open one watched instance whose writer.pid exists and is gone after stop(); a project whose lock a foreign live PID holds is served read-only and its lock is left in place.
• Targeted suites, all green: mcp-unindexed (8), mcp-stale-slice (6), mcp-roots (3), watcher (36), mcp-catchup-gate (7), mcp-staleness-banner (7), writer-lock (6), mcp-writer-lock (2).

Fixes #1835

🤖 Generated with Claude Code