feat(miner): expose per-repo run-state as a read-only MCP tool

[jaytbarimbao-collab]

Adds gittensory_miner_get_run_state to the gittensory-miner MCP server (scaffold #5153) — remote/agent-facing, read-only visibility into what an autonomously-running miner is currently doing on a given repo, without inspecting local state by hand.

What this adds

• A new tool that reads via packages/gittensory-miner/lib/run-state.js's existing accessors — no duplicated state logic:
  • pass repoFullName → { repoFullName, state } for that repo, where state is idle / discovering / planning / preparing, or null when no state has been recorded yet (explicit, never throws — requirement 6);
  • omit repoFullName → { states: [...] } listing every repo (listRunStates).
• The MCP description states it's the read-only analog of ORB's gittensory_get_automation_state (requirement 7).
• Strictly read-only: reaches only getRunState / listRunStates; adds no state set / mutation tool. The store opener is injectable (MinerMcpServerOptions.initRunStateStore) so tests need no on-disk state.
• No new files or dependencies — extends the existing bin.

Validation (local)

• tsc --noEmit: 0 errors.
• vitest on the three affected files (miner-mcp-scaffold, miner-package-skeleton, check-miner-package): 28/28 pass — new run-state cases cover single-repo known state, unknown/no-state-yet repo (null, no throw), list-all mode, and an invariant asserting the tool never triggers a state transition (only getRunState is called; never setRunState).
• node scripts/check-miner-package.mjs, docs:drift-check, git diff --check: all clean. Rebased onto latest main.

Note: packages/gittensory-miner/** sits outside vitest's coverage.include, so codecov/patch cannot measure it yet (closed separately by #4864/#4865); the tests above enforce full behavioral coverage regardless.

Closes #5160

[superagent-security]

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.41%. Comparing base (dc94169) to head (a4e9645).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5363   +/-   ##
=======================================
  Coverage   94.41%   94.41%           
=======================================
  Files         550      550           
  Lines       44143    44143           
  Branches    14632    14632           
=======================================
  Hits        41677    41677           
  Misses       1791     1791           
  Partials      675      675           

Flag	Coverage Δ
shard-1	43.74% <ø> (-0.25%)	⬇️
shard-2	34.02% <ø> (-0.61%)	⬇️
shard-3	32.21% <ø> (+0.61%)	⬆️
shard-4	31.26% <ø> (+0.01%)	⬆️
shard-5	33.09% <ø> (-0.21%)	⬇️
shard-6	43.60% <ø> (+0.21%)	⬆️

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

🚀 New features to boost your workflow:

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

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-12 15:08:19 UTC}

4 files · 2 AI reviewers · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Adds a new read-only `gittensory_miner_get_run_state` MCP tool that follows the exact same injection-seam/try-finally pattern as the sibling tools in this file, reading through the existing `run-state.js` accessors (`getRunState`/`listRunStates`) with no new state logic. The implementation is correct: `repoFullName` undefined -> list-all branch, defined -> single-repo branch with explicit null-safe lookup, and store-ownership/close semantics match the other tools exactly. Tests cover both branches, the unknown-repo null case, and an explicit invariant that `setRunState` is never reached; README and tool inventory comments are updated consistently.

Nits — 5 non-blocking

• The single-repo branch calls `store.getRunState(repoFullName)` directly and trusts it to return `null` for an unknown repo (packages/gittensory-miner/bin/gittensory-miner-mcp.js:157) — worth a one-line comment or a defensive `?? null` if the real on-disk implementation's return contract isn't guaranteed identical to the fake used in tests.
• The `.d.ts` types `getRunState`/`listRunStates` return values as `unknown`/`unknown[]` (packages/gittensory-miner/bin/gittensory-miner-mcp.d.ts:29-30), which is looser than neighboring seams like `listClaims` — consider narrowing if `run-state.js` already exports a concrete state type.
• Consider exporting and reusing the real run-state type (e.g. `RunState | null`) from `lib/run-state.js` in the `.d.ts` injection seam instead of `unknown`, matching the specificity of the `openClaimLedger` seam above it.
• nit: packages/gittensory-miner/README.md:151 has an extra blank line between MCP tool bullets; remove it so the rendered list stays consistent with the surrounding tool docs.
• nit: packages/gittensory-miner/bin/gittensory-miner-mcp.d.ts:29 types the run-state payloads as unknown even though the public tool contract documents a small fixed state set plus null, so the declaration is looser than the API it exposes.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5160
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: 20 registered-repo PR(s), 9 merged, 1 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	jaytbarimbao-collab; Gittensor profile; 20 PR(s), 1 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — This is a narrow, well-scoped extension of an existing MCP scaffold that closes a specific linked issue (#5160) by reusing existing accessors with no new state logic, matching the pattern of prior tools in the same file.

Linked issue satisfaction

Addressed
The diff adds gittensory_miner_get_run_state to the AMS MCP server, sourcing state via run-state.js's getRunState/listRunStates, supporting both single-repo and list-all modes, explicitly returning null for unknown repos, cross-referencing ORB's gittensory_get_automation_state in the description, and includes tests for known-state, unknown-repo, list-all, and a no-mutation invariant. No state-set/

Review context

• Author: jaytbarimbao-collab
• 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: 20 PR(s), 1 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

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.