feat(miner): expose the portfolio-queue dashboard as a read-only MCP tool

[jaytbarimbao-collab]

Adds gittensory_miner_get_portfolio_dashboard to the gittensory-miner MCP server (scaffold #5153, merged in #5254) — remote/agent-facing, read-only introspection into per-repo backlog health.

What this adds

• A new tool on the MCP server that wraps the existing collectPortfolioDashboard() aggregator (packages/gittensory-miner/lib/portfolio-dashboard.js) — no new aggregation logic. Returns exactly what the aggregator already produces: per-repo status counts (queued / in_progress / done), totals, and the oldest-queued age in ms — the same data gittensory-miner queue dashboard --json prints locally.
• Strictly read-only: opens the portfolio-queue store only when the tool is invoked, closes any store it opened, and mutates nothing. The store opener and clock are injectable (MinerMcpServerOptions) so tests drive it without on-disk AMS state — mirroring runPortfolioDashboard's own seam.
• No new files or dependencies — extends the existing bin (bin/gittensory-miner-mcp.js + its .d.ts) and documents the tool in the README.

Validation (local)

• tsc --noEmit: 0 errors.
• vitest on the three affected files (miner-mcp-scaffold, miner-package-skeleton, check-miner-package): 19/19 pass — including new cases for a multi-repo backlog (status counts / totals / oldest-queued age), the empty-queue edge, and an invariant asserting the tool output is structurally identical to collectPortfolioDashboard() (the wrapper adds no drift).
• node scripts/check-miner-package.mjs, docs:drift-check, git diff --check: all clean.

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

[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.37%. Comparing base (183e655) to head (e30b11a).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5298   +/-   ##
=======================================
  Coverage   94.37%   94.37%           
=======================================
  Files         474      474           
  Lines       40114    40114           
  Branches    14627    14627           
=======================================
  Hits        37856    37856           
  Misses       1583     1583           
  Partials      675      675           

Flag	Coverage Δ
shard-1	46.27% <ø> (-0.15%)	⬇️
shard-2	34.73% <ø> (+0.01%)	⬆️
shard-3	32.05% <ø> (-0.05%)	⬇️
shard-4	31.82% <ø> (-0.26%)	⬇️
shard-5	33.59% <ø> (-0.07%)	⬇️
shard-6	45.06% <ø> (+0.30%)	⬆️

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.

[gittensory-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-12 13:22:05 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This wraps the existing `collectPortfolioDashboard()` aggregator as a new read-only MCP tool `gittensory_miner_get_portfolio_dashboard`, with injectable store/clock seams mirroring `runPortfolioDashboard`'s existing pattern. The wrapper adds no new aggregation logic, correctly closes the store only when it opened it (via the `ownsQueue` check), and the test suite includes a direct invariant test asserting output equals `collectPortfolioDashboard()` directly. Straightforward, well-scoped follow-up to the #5153 scaffold that closes #5155.

Nits — 5 non-blocking

• gittensory-miner-mcp.js: the ownsQueue check `options.initPortfolioQueue === undefined` means passing `initPortfolioQueue: undefined` explicitly (vs omitting the key) is indistinguishable from not injecting — fine in practice but worth a one-line note if that's intentional.
• test file: the `fakeQueue` helper's `close()` is a no-op, so a test asserting the tool actually calls `close()` on an owned store (production path) isn't present — only the injected/non-owning path is exercised.
• Consider a small test verifying the finally-block close() is invoked when `ownsQueue` is true, e.g. by spying on a fake `initPortfolioQueue` factory's returned store's close method.
• nit: packages/gittensory-miner/bin/gittensory-miner-mcp.js:27 says the dashboard tool closes any store it opened, but lines 48 and 55 intentionally skip closing stores returned by an injected initPortfolioQueue, so tighten the comment or close injected stores too if that is the intended contract.
• nit: packages/gittensory-miner/bin/gittensory-miner-mcp.js:52 uses options.nowMs ?? Date.now(), which differs from runPortfolioDashboard's finite-number guard; consider matching the existing Number.isFinite pattern so a bad injected clock cannot silently suppress oldestQueuedAgeMs.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5155
Related work	⚠️ 2 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High 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 — Adds one well-tested, read-only MCP tool that surfaces existing aggregator data with no new business logic, directly closing the linked issue #5155.

Linked issue satisfaction

Addressed
The PR adds gittensory_miner_get_portfolio_dashboard to the MCP server, wrapping collectPortfolioDashboard() directly with no new aggregation logic, keeps the tool read-only via an injectable, closed store, and adds unit tests, an edge case, an invariant test against the direct aggregator output, and a README pointer.

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).
• Related work: Titles/paths share 3 meaningful terms. (issue #5213, issue #642)
• Related work: Titles/paths share 3 meaningful terms. (issue #642, issue #2013)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Check active issues and PRs before submitting.

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

[gittensory-orb]

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