feat(miner-cli): claim-ledger commands (claim / release / list)

[kiannidev]

Summary

• Add packages/gittensory-miner/lib/claim-ledger-cli.js with runClaimCli dispatching claim, release, and list subcommands against the existing SQLite claim ledger (claimIssue, releaseClaim, listClaims).
• Wire gittensory-miner claim … into bin/gittensory-miner.js and document usage in printHelp.
• Add test/unit/miner-claim-ledger-cli.test.ts covering argv parsing, table/JSON rendering, success paths, and error handling.

Closes #4290

Test plan

• npm run build:miner
• npx vitest run test/unit/miner-claim-ledger-cli.test.ts
• CI: validate, codecov/patch (100%), codecov/project, security

[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 93.96%. Comparing base (64fb1a3) to head (5519687).
⚠️ Report is 11 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4348   +/-   ##
=======================================
  Coverage   93.96%   93.96%           
=======================================
  Files         401      401           
  Lines       36892    36892           
  Branches    13490    13490           
=======================================
  Hits        34667    34667           
  Misses       1569     1569           
  Partials      656      656           

🚀 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-09 11:41:59 UTC}

6 files · 1 AI reviewer · no blockers · readiness 82/100 · CI green · unknown

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a self-contained claim-ledger CLI (`claim`/`release`/`list` subcommands) wired into the existing `gittensory-miner` bin, closely mirroring the established `event-ledger-cli.js`/`governor-ledger-cli.js` patterns (repo-arg parsing, table rendering, injectable `openClaimLedger` for testing). I traced argv parsing, table formatting, and error paths against the test file and they match exactly (e.g. `renderClaimsTable`'s `padStart(6)` output lines up with the test's `" 7"` assertion), and the `package.json` build script and `printHelp` text were both updated in step with the new file. No schema/migration changes are involved, and I don't see a reachable correctness defect.

Nits — 5 non-blocking

• bin/gittensory-miner.js:10 — the new `import { runClaimCli } from "../lib/claim-ledger-cli.js"` breaks the existing alphabetical-by-symbol import ordering (it's inserted after `runPlanCli` instead of before `runDenyCheck`); worth a quick reorder for consistency.
• packages/gittensory-miner/lib/claim-ledger-cli.js — `parseRepoArg` and `display` are copy-pasted verbatim from event-ledger-cli.js/governor-ledger-cli.js; this is now the third copy — consider hoisting to a shared `cli-shared.js` helper if a fourth CLI ever needs it.
• The `claim claim <owner/repo> <issue#>` subcommand name reads awkwardly (top-level `claim` plus subcommand `claim`) — `claim add` or `claim start` would read more naturally, though I won't block on it.
• packages/gittensory-miner/lib/claim-ledger-cli.js:withClaimLedger uses a synchronous static import while governor-ledger-cli.js's equivalent helper dynamically imports its ledger module — worth a one-line note on why this file diverges from that pattern (or just confirm it's intentional since it matches event-ledger-cli.js instead).
• Confirm issue feat(miner-cli): claim-ledger commands (claim / release / list) for the miner CLI #4290 is the right link/scope for this CLI surface — the PR description cites it but I can't independently verify the issue content from the diff alone.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4290
Related work	⚠️ 3 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: 1438 registered-repo PR(s), 741 merged, 33 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	kiannidev; Gittensor profile; 1438 PR(s), 33 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds claim-ledger-cli.js with runClaimCli dispatching claim/release/list to claimIssue/releaseClaim/listClaims, a withClaimLedger resource-scoping helper mirroring withPortfolioQueue, and renderClaimsTable mirroring renderQueueTable, wires it into bin/gittensory-miner.js exactly as specified, adds the three usage lines to printHelp, and includes unit tests covering argument parsing, table/J

Review context

• Author: kiannidev
• 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: 1438 PR(s), 33 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (issue #4307, issue #4290)
• Related work: Titles/paths share 7 meaningful terms. (issue #4290, issue #4247)
• Related work: Titles/paths share 7 meaningful terms. (issue #4290, issue #4266)

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.

_{🟩 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.