fix(mcp): resolve ${CLAUDE_PROJECT_DIR} in overlay paths at runtime (#57, #58)

[basicScandal]

Fixes the root-cause bug where private overlays wired with ${CLAUDE_PROJECT_DIR} silently returned public-only results, plus the doctor blind spot that couldn't catch it. Closes #57 and #58.

Root cause (#57)

starlog init bakes ${CLAUDE_PROJECT_DIR}/.starlog/{private-facts,private-corpus,policy}.json into the MCP server's env block. But Claude Code does not expand ${CLAUDE_PROJECT_DIR} there — ${VAR} expansion runs at config-parse time from Claude Code's own environment, where CLAUDE_PROJECT_DIR is unset, so the token reaches the server literal. The loaders then failed readFileSync, warned only to stderr (which the MCP stdio channel discards), and degraded to public-only. Completely silent; search just returned public packages.

Verified against the live MCP server processes on this machine — every one carries the literal token, e.g.:

CLAUDE_PROJECT_DIR=/Users/scandal/ai/whoisgenius      ← injected into process.env at runtime
STARLOG_PRIVATE_FACTS=${CLAUDE_PROJECT_DIR}/.starlog/private-facts.json   ← literal, unexpanded

So facts and policy are affected too, not just corpus.

Fix

CLAUDE_PROJECT_DIR is injected into the spawned server's process.env (the documented pattern), so the server can resolve the token itself. New src/engine/overlay-path.ts → resolveOverlayPath():

• expands ${VAR} / ${VAR:-default} from process.env (CLAUDE_PROJECT_DIR falls back to cwd, never a bogus /.starlog/…)
• expands a leading ~
• resolves project-relative paths against CLAUDE_PROJECT_DIR || cwd
• idempotent on absolute paths (existing loader tests untouched)

loadPrivateCorpus, loadPrivateFacts, and loadPolicy call it at read time. This repairs already-wired installs with no re-init — the init env format is unchanged, so there's no migration. The misleading init.ts comment (claimed parse-time expansion) is corrected.

doctor (#58)

checkPrivateOverlays reported Private overlays wired: [ok] on mere presence of the env keys — it never checked they resolved, so a stale absolute path or cross-project leak passed as healthy. It's the tool you'd run to catch #57, and it structurally couldn't. It now resolves each wired path exactly as the server will (resolveOverlayPath(value, projectDir)) and warns when it doesn't land on this project's .starlog/.

Tests

TDD throughout (RED verified before each GREEN):

• overlay-path.test.ts — 8 cases (token expansion, cwd fallback, ~, relative, :-default, idempotence, explicit projectDir override)
• token-resolution cases added to private-corpus.test.ts and facts/service.test.ts
• doctor.test.ts — misrouted/cross-project path now warns

Full suite green: 577/577, typecheck clean.

Notes for the reviewer

• No package.json version bump — left for the release step per RELEASING.md. CHANGELOG entry staged under ## 0.7.2; adjust the number if you prefer.
• Follow-up (CLI search doesn't auto-detect ./.starlog/ private corpus (CLI ≠ MCP parity) #59, separate PR): give the CLI the same project-local overlay auto-detection so search/facts match MCP behavior.

🤖 Generated with Claude Code