feat(miner-mcp): expose status/doctor diagnostics tool (#5154)

[andriypolanski]

Closes #5154

Summary

Adds gittensory_miner_status, a read-only MCP tool on gittensory-miner-mcp that returns the same diagnostics as gittensory-miner status and doctor --json, via a new shared collectMinerDiagnostics() helper in status.js. No duplicated logic — the MCP tool and future callers share one snapshot builder.

Driver-info fields (MINER_CODING_AGENT_PROVIDER, model-env-var name, provider CLI presence) are deferred until #5164 lands, per the issue dependency note.

Changes

Area	Change
packages/gittensory-miner/lib/status.js	collectMinerDiagnostics() — merges collectStatus() + runDoctorChecks() with derived presence booleans
packages/gittensory-miner/bin/gittensory-miner-mcp.js	Register gittensory_miner_status tool
packages/gittensory-miner/bin/gittensory-miner-mcp.d.ts	Injection seams for status tool tests
packages/gittensory-miner/lib/status.d.ts	MinerDiagnostics type
packages/gittensory-miner/README.md	Document new MCP tool
test/unit/miner-mcp-status.test.ts	MCP tool success/failure/invariant tests
test/unit/miner-status.test.ts	Unit tests for collectMinerDiagnostics()
test/unit/miner-mcp-scaffold.test.ts	Updated tool list assertion

Response shape

{
  "package": { "name": "@jsonbored/gittensory-miner", "version": "…" },
  "engine": { "name": "@jsonbored/gittensory-engine", "version": "…" },
  "node": "v22.x.x",
  "stateDir": "/path/to/state",
  "configFile": "/path/to/.gittensory-miner.yml",
  "configValid": true,
  "engineVersionSkew": { "ok": true, "detail": "…" },
  "presence": { "docker": false, "claudeCli": false, "codexCli": false },
  "doctor": { "ok": true, "checks": [ … ] }
}

• configValid: config file readable (or absent — defaults OK). Full schema validation follows Make doctor validate config content, not just its path #4873.
• presence.*: binary on PATH, independent of doctor pass/fail (Gate doctor's claude/codex CLI-presence checks by the configured MINER_CODING_AGENT_PROVIDER #5165 gating).
• No secret values: env-var names may appear in doctor detail strings; values never do.

Follow-ups

• #5164 — add driver section to status --json, then wire into collectMinerDiagnostics() / MCP tool
• #4873 — deepen configValid with schema validation

Test plan

• collectMinerDiagnostics merges status + doctor without drift
• gittensory_miner_status matches collectMinerDiagnostics() (invariant)
• Output never contains secret-shaped strings or configured token values
• configValid: false when config path is unreadable
• Injection seam covers doctor failure path
• npx vitest run test/unit/miner-mcp-status.test.ts test/unit/miner-status.test.ts test/unit/miner-mcp-scaffold.test.ts
• npm run test:ci

Notes

• Issue labels: help wanted, gittensor:feature — confirm contributor eligibility before opening.
• Strictly read-only: no state/config/ledger writes beyond doctor's existing transient write-probe.
• Depends on MCP scaffold (Scaffold a minimal gittensory-miner mcp stdio server (bin entry, one health-check tool) #5153) — already on main.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[gittensory-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - reject/close recommended

_{Review updated: 2026-07-12 14:35:27 UTC}

8 files · 2 AI reviewers · 1 blocker · readiness 100/100 · CI green · unstable

🛑 Suggested Action - Reject/Close

• AI reviewers agree on a likely critical defect: packages/gittensory-miner/bin/gittensory-miner-mcp.js:101 and packages/gittensory-miner/lib/status.js:339 make `gittensory_miner_status` call `runDoctorChecks()`, whose `checkStateDirWritable()` path creates the state directory and writes a probe file, so the supposedly read-only MCP diagnostics tool mutates disk on a reachable request
• change the MCP/status snapshot to use a non-mutating writability check or explicitly separate the mutating doctor probe from the read-only MCP path. — Resolve the flagged defect, or override if the AI reviewers are mistaken, then re-run the gate.

Review summary
This PR adds `collectMinerDiagnostics()` in status.js merging `collectStatus()` + `runDoctorChecks()` into one snapshot, and wires it into a new read-only `gittensory_miner_status` MCP tool with the standard injection-seam pattern already used by the other tools. Tests cover the happy path, config-unreadable path, the secret-shaped-value invariant, and structural parity between the tool output and the direct function call, which is the right coverage shape for a read-only wrapper. One notable detail: `status.js:342` quietly changes `checkDockerPresent()` to `checkDockerPresent({ env })`, making the docker-presence doctor check respect the injected env/PATH instead of always reading `process.env` — a real behavior change that isn't called out in the PR description but is required for the new tests to pass deterministically.

Blockers

• packages/gittensory-miner/bin/gittensory-miner-mcp.js:101 and packages/gittensory-miner/lib/status.js:339 make `gittensory_miner_status` call `runDoctorChecks()`, whose `checkStateDirWritable()` path creates the state directory and writes a probe file, so the supposedly read-only MCP diagnostics tool mutates disk on a reachable request; change the MCP/status snapshot to use a non-mutating writability check or explicitly separate the mutating doctor probe from the read-only MCP path.

Nits — 5 non-blocking

• PR description says driver-info fields (provider/model-env-var/CLI presence) are deferred until Surface the resolved coding-agent-driver provider and CLI presence in gittensory-miner status --json #5164, but `collectMinerDiagnostics()` at status.js:277 spreads `driver: status.driver` straight through, so the tool already returns them — worth correcting the description since the code (correctly, per the linked issue) already includes this data.
• The CI Orb Review Agent flagged a possible leaked secret in test/unit/miner-mcp-status.test.ts's runtime-assembled `ghp_` + `'a'.repeat(36)` token; even though it's synthetic, consider pulling it from a shared non-secret-shaped test fixture so scanners stop flagging it.
• The silent `checkDockerPresent()` → `checkDockerPresent({ env })` behavior change at packages/gittensory-miner/lib/status.js:342 isn't mentioned in the PR description — worth a one-line callout since it changes doctor's real-world docker check to honor an injected env rather than always reading `process.env`.
• Add a changelog/description note for the `checkDockerPresent({ env })` behavior change so reviewers of `doctor --json` output know PATH resolution is now env-driven.
• Consider asserting in miner-mcp-status.test.ts that `presence.docker` reflects a truthy PATH the same way the driver CLI-presence tests already do for claude/codex, to lock in the new `{ env }` wiring end-to-end.

Why this is blocked

• packages/gittensory-miner/bin/gittensory-miner-mcp.js:101 and packages/gittensory-miner/lib/status.js:339 make `gittensory_miner_status` call `runDoctorChecks()`, whose `checkStateDirWritable()` path creates the state directory and writes a probe file, so the supposedly read-only MCP diagnostics tool mutates disk on a reachable request; change the MCP/status snapshot to use a non-mutating writability check or explicitly separate the mutating doctor probe from the read-only MCP path.

Signal	Result	Evidence
Code review	❌ 1 blocker	2 reviewers, synthesized
Linked issue	✅ Linked	#5154
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 148 registered-repo PR(s), 100 merged, 29 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 148 PR(s), 29 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — Exposing status and doctor diagnostics through the miner MCP server is a targeted operator-facing improvement tied to the stated issue, but its value depends on preserving the read-only contract.

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 148 PR(s), 29 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.40%. Comparing base (97707b8) to head (8e5768e).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5313   +/-   ##
=======================================
  Coverage   94.40%   94.40%           
=======================================
  Files         550      550           
  Lines       44116    44128   +12     
  Branches    14631    14631           
=======================================
+ Hits        41649    41661   +12     
  Misses       1792     1792           
  Partials      675      675           

Flag	Coverage Δ
shard-1	43.76% <0.00%> (-0.25%)	⬇️
shard-2	34.02% <0.00%> (-0.62%)	⬇️
shard-3	32.21% <0.00%> (+0.61%)	⬆️
shard-4	31.27% <0.00%> (-0.15%)	⬇️
shard-5	33.06% <100.00%> (-0.09%)	⬇️
shard-6	43.62% <0.00%> (+0.26%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/gittensory-miner/lib/status.js	93.80% <100.00%> (+0.73%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gittensory-orb]

An AI reviewer flagged a likely defect, but its confidence was below this repository's configured close-confidence floor, so this is held for a maintainer to confirm instead of closing automatically. Resolve the flagged defect (see the review notes), or ask a maintainer to override.

[JSONbored]

Please fix + resubmit:

packages/gittensory-miner/bin/gittensory-miner-mcp.js:101 and packages/gittensory-miner/lib/status.js:339 make `gittensory_miner_status` call `runDoctorChecks()`, whose `checkStateDirWritable()` path creates the state directory and writes a probe file, so the supposedly read-only MCP diagnostics tool mutates disk on a reachable request; change the MCP/status snapshot to use a non-mutating writability check or explicitly separate the mutating doctor probe from the read-only MCP path.