feat(diagnostics): add read-only doctor and MCP diagnose

[redxzeta]

Problem and behavior

Humans and agents need reliable diagnostics when graph queries, search, or watcher indexing behave unexpectedly. A readable graph or running watcher cannot prove freshness, and an ordinary native open can enter recovery or terminate before Rust receives an error.

Add infigraph doctor, infigraph doctor --json, and read-only MCP diagnose (path required), backed by one typed core engine. JSON remains schema version 1 with stable codes and recommendations. CLI exits remain 0 healthy, 1 degraded, 2 unhealthy. The human summary now displays freshness beside overall health:

Result: HEALTHY
Index freshness: UNKNOWN (working-tree freshness unverified)

A registry revision match also leaves working-tree freshness UNKNOWN. INDEX_STALE describes a registry revision mismatch; registry metadata can lag watcher updates. Recommendations are never executed. Optional absent watchers, persisted embeddings, and MCP binaries remain informational. Unreadable existing assets and required-state uncertainty are distinguished from optional absence.

Reuse graph statistics, existing advisory locks, registry revision metadata, the embedding-header reader, shared installer binary discovery, and the MCP worker's watcher registry. No second freshness tracker, process manager, or artifact registry. Full check definitions and limitations are in docs/DOCTOR.md. Integration/artifact expansion stays deferred to #79/#63; richer freshness belongs to #53, WAL safety to #64, watcher lifecycle to #43.

Safety and review

The complete diff was reviewed again on head 435723028002a9d294a01e113701136b4d4a954a, base cf82f5d7440d9be158e219df1ef256d6359ed1f6, for native opens/recovery, lock races, subprocess containment, remote connections, secret leakage, duplicated state logic, severity, and supported recommendations. There are no existing reviewer comments or unresolved threads.

Doctor bypasses update/watcher startup. MCP diagnosis bypasses per-call logging, compression, session changes, and focus recording. Graph probes execute before normal CLI/MCP startup and before the supervisor/reindex path. Existing locks are opened read-only and observed nonblockingly; their contents are preserved. Shared guards remain held through probing. Busy, WAL-bearing, truncated, unsafe, or unverifiable state is skipped or reported UNKNOWN. Native children have database/buffer/thread budgets and a timeout; Unix also caps address space and disables core dumps. Only the dedicated diagnostic child can be terminated on timeout.

No repairs, graph/schema writes, reindexing, client configuration edits, model loading/downloads, remote connections, watcher startup/termination, or installed-binary replacement. Output uses fixed messages and typed counts; no raw config, credentials, native errors, or private paths.

New regressions cover working changes despite a recorded revision match, stale-revision summary rendering, shared-lock retention throughout a probe, and actual direct-worker MCP initialization/discovery/diagnosis over clean stdio.

Separate prerequisites

• fix(embed): reject impossible entry counts before allocation #82: validate embedding entry counts before allocation. Clean upstream's seven-byte corrupt document fixture causes Rust to reserve 92,164,907,664 bytes before checking file length. This is an embedding-loader failure, correcting the earlier native-parser attribution in Combined docs test aborts on clean main with a 92 GB allocation request #80. Two new format regressions and all five existing combined-document tests pass with the fix.
• fix: restore strict all-feature Clippy validation #83: remove baseline strict Clippy causes (chunks_exact_to_as_chunks, redundant references to cached Postgres handles, unnecessary vectors) without disabling checks or adding lint suppressions.

Both fixes were developed and submitted separately. Their commits are included in this validation head; their separate review and upstream landing are still pending. Reassess and revalidate whenever head/base changes or those prerequisites land.

Read-only acceptance at the reviewed head

Freshly built CLI/MCP binaries were invoked directly. Human and JSON calls each exited 0 with empty stderr; MCP used a temporary home, an empty registry, local stdio, and --worker --mcp, avoiding registered-project watcher startup and supervisor recovery. Initialization, discovery, and diagnosis produced three clean JSON-RPC responses. CLI JSON and MCP diagnostics matched exactly.

Question	Confirmed observation
Is the graph readable?	Read-only statistics succeeded: 6,553 files / 68,535 symbols.
Is a writer holding its lock?	No advisory write-lock owner observed.
Is a watcher present?	No watch-lock owner observed; process identity/progress is not established.
Are embedding headers readable?	Header readable: 68,535 recorded entries.
Can freshness be established?	UNKNOWN; empty trial registry provides no comparable revision provenance.

Final artifact replay: human 0.135 s; JSON 0.134 s; MCP initialization/discovery/diagnosis 0.141 s. The initial reviewed-head trial measured 0.137 s, 0.137 s, and 0.150 s respectively. Validation builds had replaced the MCP artifact, so both binaries were rebuilt from the unchanged reviewed head and acceptance was replayed; the final binary hashes match that replay. These are single-trial measurements, not benchmark guarantees.

Before/after recursive manifests matched index file/directory entries, inode/mode/size/mtime metadata, and SHA-256 file hashes. Git status bytes matched. No concurrent changes were observed within the trial window. Private paths, database contents, retained manifests, and developer artifacts are excluded from the PR.

Failure cases were exercised only in disposable fixtures: missing optional assets exit 0; busy lock, WAL, invalid native graph, and stale revision exit 1 with expected codes and preserved checked state. The existing project index was never mutated to induce failures.

These findings establish read-only diagnostic usefulness. They do not establish indexing of working changes, semantic-search correctness, complete embedding/model/HNSW validity, watcher liveness/progress, remote service health, or integration configuration correctness.

Final-head validation and readiness

Validation performed on 435723028002a9d294a01e113701136b4d4a954a with Rust 1.98.1:

Check	Result
cargo fmt --all -- --check; git diff --check	PASS
Direct CLI/MCP binary build from the reviewed commit	PASS
cargo clippy --all-targets --all-features -- -D warnings	PASS, no added suppressions or command allowances
Focused CLI doctor / cli_parity	PASS: 6 tests
Focused MCP diagnose / tool_parity	PASS: 14 tests
Full workspace cargo test --all -- --test-threads=1	BLOCKED: SIGILL in existing default-feature compress::tests::test_kompress_direct; Cargo exit 101
cargo test --workspace --doc	PASS; all eight targets currently contain zero doc-test cases
write_lock_perf -- --ignored	PASS: 3 tests
groups_watch_perf -- --ignored	PASS: 1 test
index_perf -- --ignored	PASS: repository hook's 1 ignored gate (8 other tests filtered)
Exact-head project and disposable-fixture acceptance	PASS

The workspace run completed 59 test executables with 1,024 tests passed and 12 existing ignored tests before reaching the fatal MCP compression test; these counts exclude the interrupted executable. It included all five previously failing combined-document tests and both embedding-format regressions. No green full-workspace result is claimed. Optional remote-provider runtime tests were not exercised by the default-feature suite; all-feature Clippy provides compilation evidence only.

The compression failure reproduces with only that one test on an additional clean upstream worktree at cf82f5d7440d9be158e219df1ef256d6359ed1f6:

cargo test -p infigraph-mcp --lib compress::tests::test_kompress_direct -- --exact --test-threads=1

It exits 101 with SIGILL. The compression source is unchanged by this PR; the clean-upstream reproduction used the already downloaded model with no additional download and disabled core dumps. The first full run's existing compression test downloaded its model as setup. Doctor/diagnose did not load or download models. This establishes an independent upstream blocker, without attributing the faulting instruction in this review. Related native/default-feature work: #78. No feature or test was disabled to manufacture a passing suite. Remaining workspace targets after the abort still require a successful full rerun after that blocker is resolved.

A final preservation check after validation still matched the project's pre-trial index manifest and Git status. No concurrent changes were observed in these before/after checks.

Required PR review approval remains absent. Hosted CI and Deploy GitHub Pages runs for the final head report action_required; both run pages explicitly say they await maintainer approval. Neither run has started any jobs, and there are no logs, so they provide no hosted build/test result. The authenticated contributor account has read-only permission on the upstream repository and cannot approve these runs. Pages deployment is gated to a push on main; this PR event only builds docs. Separate prerequisite landing and the upstream compression SIGILL blocker remain pending. This PR is not merge-ready; no automatic merge, installation, deployment, or activation is included.

Refs #48, #79, #80, #82, #83.

[redxzeta]

Self-review and read-only acceptance update for 435723028002a9d294a01e113701136b4d4a954a (base cf82f5d):

• Human summaries now display index freshness beside overall health. HEALTHY with no revision provenance prints Index freshness: UNKNOWN; a registry revision match also explicitly leaves working-tree freshness unverified. JSON schema version 1, diagnostic codes, and exit semantics are unchanged.
• Regression coverage now checks a matched revision with working changes, stale revision rendering, retention of the shared advisory lock throughout the graph probe, and real direct-worker MCP initialization/discovery/diagnosis over stdio.
• The complete diff was reviewed again for native opens/recovery, WAL preflight, lock races, subprocess/resource containment, remote connections, secret-free output, and reuse of existing state APIs. Optional missing watcher/embeddings/MCP binary remain informational. Existing unreadable assets and selected-backend uncertainty are reported separately from absent optional features. Native counts and embedding headers do not establish semantic-search correctness or working-tree freshness.
• Separate prerequisites: fix(embed): reject impossible entry counts before allocation #82 fixes the independently reproduced document test abort by checking the embedding count before reserving memory. The seven-byte corrupt fixture caused Rust (not the native graph parser) to request 92,164,907,664 bytes. fix: restore strict all-feature Clippy validation #83 removes baseline Clippy causes without suppressions. Their commits are included in this validation head; separate review/landing remains pending.

An existing project was inspected only through the freshly built binaries, invoked directly. Nothing was installed, reindexed, or configured. Human and JSON calls each exited 0 with empty stderr in 0.135 seconds (human) and 0.134 seconds (JSON). MCP used local stdio, --worker --mcp, a temporary home, and an empty registry; initialization, discovery, and diagnose completed in 0.141 seconds with three clean JSON-RPC responses and the identical diagnostic report.

Confirmed at trial time: graph statistics readable (6,553 files / 68,535 symbols); advisory write lock free; no watcher lock owner observed; embedding header readable (68,535 recorded entries). Freshness remained UNKNOWN. The empty trial registry intentionally supplies no revision provenance. This does not establish indexing of the project's working changes, watcher process identity/progress, complete embedding/model/HNSW validity, or semantic-search correctness.

Before/after recursive index manifests matched directory entries, inode/mode/size/mtime metadata and SHA-256 file hashes. Git status bytes also matched; no concurrent changes were observed within the trial window. Retained manifests, database contents, developer artifacts, and private paths are excluded from this PR.

Disposable fixtures passed: missing optional assets exit 0; busy lock, WAL, invalid native graph, and stale revision each exit 1 with the expected codes. Diagnostics preserved each fixture's checked state. No project index mutation was used to induce failures.

Final-head formatting, strict all-feature Clippy, focused CLI/MCP tests (20 total), the fixed document suite, doc-test target check, and all three repository performance gates pass. The full workspace run exits 101 at unchanged compress::tests::test_kompress_direct with SIGILL. An isolated one-test run on clean upstream cf82f5d also SIGILLs; the faulting instruction is not attributed here. No successful full-suite result is claimed. The final project index manifest and Git status still match the pre-trial snapshots. Required approval and final-head hosted CI remain absent, so this is not a merge-ready claim. No automatic merge, deployment, activation, or integration-artifact expansion.

After validation replaced the MCP executable artifact, both binaries were rebuilt from the unchanged reviewed head and the final CLI/MCP plus fixture acceptance was replayed. Final binary hashes match the replay artifacts; earlier trial evidence was retained. Both trials confirmed identical findings and preserved project state.

[redxzeta]

Investigated both action_required runs on final head 435723028002a9d294a01e113701136b4d4a954a:

• CI: the run page explicitly reports awaiting maintainer approval; the API reports zero jobs/check runs, and no logs are available.
• Deploy GitHub Pages: the same approval gate, with zero jobs/check runs and no logs. The workflow's deploy job only runs on pushes to main; the pull-request event builds the docs.

An upstream maintainer must approve the workflow runs. The authenticated contributor account has read-only upstream permissions. No repository changes, check suppression, rerun, or deployment were performed for this gate. These run conclusions provide no hosted validation result; required PR review, the separately reproduced upstream compression SIGILL, and prerequisite landing remain blockers. T3 watching remains enabled for subsequent feedback and CI events.