feat(miner): expose the persisted plan store via read-only MCP tools

[jaytbarimbao-collab]

Adds two read-only tools to the gittensory-miner MCP server (scaffold #5153) for the persisted plan store — net-new coverage, since AMS's plan store survives across CLI invocations (unlike ORB's stateless gittensory_plan_status, which reads the caller's in-memory plan object).

What this adds

• gittensory_miner_list_plans — wraps plan-store.js's existing listPlans, with an optional status filter (z.enum(PLAN_STATUSES) — no invented statuses). Returns { planId, plan, status, updatedAt } records.
• gittensory_miner_get_plan — wraps loadPlan(planId), returning { found: true, plan } for an existing id or an explicit { planId, found: false } for an unknown one (never throws — requirement 6).
• Both tools' descriptions explicitly distinguish this store-backed pair from ORB's stateless gittensory_plan_status (requirement 5).
• Strictly read-only: they reach only listPlans / loadPlan; never savePlan or any DAG/planning logic. The store opener is injectable (MinerMcpServerOptions.openPlanStore) for tests. No plan-store.js change, no new files or dependencies.

Validation (local)

• tsc --noEmit: 0 errors.
• vitest on the three affected files: 33/33 pass — new plan cases cover list (all + status-filtered), get for an existing id, get for an unknown id (explicit not-found), and an invariant asserting neither tool reaches savePlan (only listPlans / loadPlan are called).
• check-miner-package, docs:drift-check, git diff --check: all clean. Rebased onto latest main; overlap-free (this wraps existing readers, so it does not touch plan-store.js, which feat(miner): add schema-version migration runner across local stores #5364 is editing).

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 #5161

[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 (e8e068d) to head (88f41aa).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5371   +/-   ##
=======================================
  Coverage   94.41%   94.41%           
=======================================
  Files         551      551           
  Lines       44168    44168           
  Branches    14632    14632           
=======================================
  Hits        41702    41702           
  Misses       1791     1791           
  Partials      675      675           

Flag	Coverage Δ
shard-1	43.76% <ø> (-0.38%)	⬇️
shard-2	34.04% <ø> (-0.51%)	⬇️
shard-3	32.24% <ø> (+0.68%)	⬆️
shard-4	31.07% <ø> (-0.21%)	⬇️
shard-5	32.86% <ø> (-0.46%)	⬇️
shard-6	43.97% <ø> (+0.56%)	⬆️

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:22:47 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds two read-only MCP tools (`list_plans`, `get_plan`) that wrap `plan-store.js`'s existing `listPlans`/`loadPlan` functions, following the exact same pattern already established for the four prior read-only tools in this file (injectable store opener, own-and-close semantics, optional filters). The implementation is correct: `get_plan` explicitly handles the not-found case without throwing, `list_plans` correctly omits the filter key when `status` is undefined (matching the CLAIM_STATUSES pattern used elsewhere in the file), and tests assert an invariant that `savePlan` is never reached. Closes #5161 as claimed, and the diff is narrow and consistent with the existing scaffold's conventions.

Nits — 5 non-blocking

• The external brief flags depth-5 nesting at gittensory-miner-mcp.js:208, but this is just the standard try/finally-inside-async-callback-inside-registerTool shape already used by every other tool in this file (e.g. get_run_state, list_claims) — not new complexity introduced by this PR.
• packages/gittensory-miner/bin/gittensory-miner-mcp.js: the two new tools duplicate the `ownsStore`/open/close boilerplate verbatim from `gittensory_miner_get_run_state` just above; a shared helper could reduce repetition but isn't required to match existing file conventions.
• Consider a small `withStore(opener, override, fn)` helper to DRY up the now five near-identical open/try/finally/close blocks in this file, though this would be an orthogonal refactor beyond this PR's scope.
• nit: packages/gittensory-miner/bin/gittensory-miner-mcp.d.ts:38 should type `loadPlan` as returning `unknown | null` so the public injection seam documents the not-found sentinel that `gittensory_miner_get_plan` depends on.
• nit: test/unit/miner-mcp-scaffold.test.ts:326 only asserts the read methods are called for an injected store; consider adding a small close-behavior test for the default-owned-store path if this file already has that convention for other store-backed tools.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5161
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 — The PR closes a linked issue by adding well-tested, narrowly-scoped read-only coverage for the persisted plan store, consistent with the file's established tool pattern.

Linked issue satisfaction

Addressed
The PR adds gittensory_miner_list_plans (wrapping listPlans with optional status filter) and gittensory_miner_get_plan (wrapping loadPlan with explicit not-found handling), both described as distinct from ORB's stateless gittensory_plan_status, backed by unit tests including a savePlan-non-reachability invariant.

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.