feat(miner): wire the batch claimer and telemetry exporter into the CLI

[nickmopen]

Summary

Three modules were fully built and unit-tested but had zero callers outside their own tests. Per #4833, this wires the two in-scope ones into real CLI commands — without changing either module's logic (the third, the inter-miner claim-conflict adjudicator, is deliberately left unwired: connecting it would let the loop act on race-resolution with no human review, which stays maintainer-only per the issue's scope note).

• WIP-cap-aware batch claimer (portfolio-queue-manager.claimNextBatch) → gittensory-miner queue claim-batch [--global-wip <n>] [--per-repo-wip <n>] [--json]. Uses the caps-aware diversified selector, and (via the manager) reclaims any lease orphaned by a crashed process before selecting.
• Anonymized telemetry batch-builder (orb-export.collectOrbExportBatch) → gittensory-miner orb export [--enable] [--json]. Opt-in — builds nothing unless --enable — and never performs the network POST; it only assembles the HMAC-anonymized batch from the local pr_outcome ledger.

Both CLI handlers open their stores inside the try/catch (per maintainer review on the prior attempt), so a bad config path / SQLite open failure returns exit code 2 instead of crashing — with ?.-guarded closes in finally; covered by new failure-path tests.

Wired at the natural dispatch points: queue claim-batch slots into the existing runQueueCli (no bin change), and orb export gets a one-line route in bin/gittensory-miner.js. No new files, so the package build manifest (package.json) is untouched.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves — Closes #4833.

Validation

• git diff --check
• npm run build:miner (node --check across the package)
• npm run test:miner-pack (tarball hygiene)
• npx vitest run test/unit/miner-*.test.ts — new miner-wire-cli-modules suite (8) + existing queue/CLI/manager suites pass; the only failure is a pre-existing, environment-specific PID-liveness test (miner-worktree-allocator-collisions) that fails identically on clean main and is untouched by this diff
• typecheck clean on the changed files

If any required check was skipped, explain why:

• Change is confined to packages/gittensory-miner/lib/** + bin/** (hand-written ESM .js + .d.ts, validated by node --check, not tsc) and test/unit/**. No src/**, UI, migration, or dependency changes — Codecov ignores this path and the backend/UI/MCP CI jobs are path-skipped.

Safety

• No secrets, wallet details, hotkeys, coldkeys, PATs, private keys, raw trust scores, private rankings, or maintainer evidence are exposed. The orb export batch HMAC-anonymizes repo/PR identifiers and emits only a low-cardinality reason bucket + decision — never raw names — and stays opt-in and local (no network POST here).
• Public GitHub text stays sanitized, low-noise, and implies no compensation guarantees or optimization tactics.
• Auth/cookie/CORS/GitHub App/Cloudflare/session changes include negative-path tests. (N/A — none touched.)
• API/OpenAPI/MCP behavior updated and tested where needed. (N/A — local CLI only.)
• No changelog edited.

Notes

• orb export builds the batch but does not send it (matching the module's stated contract — the network POST is the caller's job); this PR just gives the exporter a real invocation surface.
• The claim-conflict adjudicator remains caller-less on purpose (maintainer-only) and is out of scope here.

Closes #4833

[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.34%. Comparing base (69e8d81) to head (b2bf6bf).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5242   +/-   ##
=======================================
  Coverage   94.34%   94.34%           
=======================================
  Files         473      473           
  Lines       39982    39982           
  Branches    14576    14576           
=======================================
  Hits        37722    37722           
  Misses       1585     1585           
  Partials      675      675           

Flag	Coverage Δ
shard-1	46.29% <ø> (-0.15%)	⬇️
shard-2	34.60% <ø> (+0.01%)	⬆️
shard-3	32.10% <ø> (-0.05%)	⬇️
shard-4	31.82% <ø> (-0.21%)	⬇️
shard-5	33.72% <ø> (-0.03%)	⬇️
shard-6	45.07% <ø> (+0.19%)	⬆️

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 11:13:00 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR wires two already-tested, previously caller-less modules (portfolio-queue-manager's batch claimer and orb-export's telemetry batch-builder) into the CLI, adding `queue claim-batch` and `orb export` subcommands plus help text and a new test file. Both handlers correctly follow the established convention of opening stores inside try/catch with `?.`-guarded closes in finally, matching the pattern used by existing `withPortfolioQueue`. Logic in the underlying modules is untouched — only new thin CLI wrapper functions and dispatch wiring were added, and the wiring is traced end-to-end correctly (bin dispatch → runOrbExportCli/runQueueClaimBatch → existing initializers).

Nits — 5 non-blocking

• portfolio-queue-cli.js:runQueueClaimBatch prints only `entry.identifier` per claimed row in non-JSON mode, unlike `renderQueueTable`'s richer format elsewhere in the same file — consider noting the repo too for readability when claiming across multiple repos.
• The external brief flags a literal `4833` in a comment at portfolio-queue-cli.js — this is just an issue-number reference in a docblock, not a real magic-number code smell, so it's a non-issue.
• orb-export.js's `runOrbExportCli` and portfolio-queue-cli.js's `runQueueClaimBatch` duplicate the same open-inside-try/guarded-close-in-finally shape already factored out as `withPortfolioQueue` for the other queue commands in the same file — not required to fix, but worth considering a shared helper if a third caller shows up.
• No test asserts the `runQueueCli("claim-batch", ...)` dispatch line itself (only `runQueueClaimBatch` directly is tested) — a low-value gap given the dispatch line is one `if` clause, but worth a one-line assertion for full patch coverage.
• Consider a shared `withStores`-style helper across orb-export.js and portfolio-queue-cli.js to DRY the open-in-try/guarded-close-in-finally pattern now used in three places.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#4833
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: 140 registered-repo PR(s), 86 merged, 12 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	nickmopen; Gittensor profile; 140 PR(s), 12 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 diff cleanly wires two fully-built, already-unit-tested modules into real CLI entry points without touching their internal logic, closing a concrete 'zero callers' gap referenced by issue #4833 with new failure-path test coverage.

Linked issue satisfaction

Addressed
The PR adds real CLI call sites for both in-scope modules — `queue claim-batch` invokes `portfolio-queue-manager.claimNextBatch` and `orb export` invokes `orb-export.collectOrbExportBatch` — with tests exercising them through the CLI rather than only their own unit tests, and it explicitly and correctly leaves the claim-conflict adjudicator unwired per the scope note.

Review context

• Author: nickmopen
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, Python
• Official Gittensor activity: 140 PR(s), 12 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.