feat(miner): add local claims ledger CLI

[james3773]

Summary

Adds an operator-facing gittensory-miner claims CLI for the existing local soft-claim ledger. The SQLite store (claim-ledger.js) and expiry helper (claim-ledger-expiry.js) already existed, but unlike ledger, governor, and plan there was no command-line surface to list, record, release, or sweep claims from a laptop.

New subcommands:

• claims list [--repo <owner/repo>] [--status active|released|expired] [--json]
• claims claim <owner/repo> <issue#> [--note <text>] [--json]
• claims release <owner/repo> <issue#> [--json]
• claims sweep [--max-age-days <n>] [--json]

Commands dispatch before the npm update check (offline/local, same as ledger/governor).

No upstream issue was filed: jony376 lacks CreateIssue permission on this repository. This PR is self-contained against that gap.

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• 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 an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run typecheck
• npx vitest run test/unit/miner-claim-ledger-cli.test.ts (9/9 passed)
• npm --workspace @jsonbored/gittensory-miner run build
• npm run test:coverage locally; codecov/patch requires ≥99% coverage of the lines AND branches you changed (aim for 100% on your diff so CI variance does not fail near the threshold). Global coverage is a non-blocking trend with a loose 90% backstop, not the gate.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• Remaining full-repo gate steps will run in CI on this PR.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails. SVG screenshots are not used as review evidence. Review-only screenshots or recordings are not committed to the repository.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

UI Evidence

Not applicable — miner CLI only.

Notes

• release is idempotent for already-released rows; missing/non-active releases fail closed with claim_not_found_or_not_active.
• Help text preserves the existing hooks check entry and all prior commands.

Made with Cursor

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[superagent-security]

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

[loopover-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - reject/close recommended

_{Review updated: 2026-07-05 08:09:31 UTC}

6 files · 1 AI reviewer · 3 blockers · readiness 73/100 · CI green · clean

🛑 Suggested Action - Reject/Close

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.
• AI reviewers agree on a likely critical defect: PR description: this external-contributor feature explicitly says no upstream issue was filed, so it must either close or clearly link an eligible maintainer-authorized open issue before I can mark it merge-ready. — Resolve the flagged defect, or override if the AI reviewers are mistaken, then re-run the gate.

Review summary
This adds a local `claims` command surface over the existing claim ledger and wires it before the opportunistic update check, matching the offline behavior of the adjacent local commands. The parser and runners are covered against the real SQLite ledger path, and the release/sweep behavior is grounded in the existing `claim-ledger.js` API. I do not see a reachable code correctness defect in the changed implementation, but the PR does not satisfy the repository's required issue-scope convention.

Blockers

• PR description: this external-contributor feature explicitly says no upstream issue was filed, so it must either close or clearly link an eligible maintainer-authorized open issue before I can mark it merge-ready.

Nits — 6 non-blocking

• packages/gittensory-miner/lib/claim-ledger-cli.js:170 uses inline table widths repeatedly; nit: extract named column-width constants so future table changes do not have to keep header and row padding in sync.
• packages/gittensory-miner/lib/claim-ledger-cli.js:303 treats `claims --help` as an unknown subcommand even though the usage text says to run help for details; nit: either handle `--help` here or remove that hint from `CLAIMS_USAGE`.
• test/unit/miner-claim-ledger-cli.test.ts:39 references `feat(miner-foundation): local claim-ledger SQLite schema + CRUD in packages/gittensory-miner #2314/feat(miner-foundation): claim-ledger staleness/expiry sweep #2316` in the suite name while the PR description says no upstream issue exists; nit: make the issue reference consistent with the PR scope record.
• Link the eligible issue in the PR description using the repository's normal closing syntax, or ask a maintainer to create/authorize one and then point this PR at it.
• In `packages/gittensory-miner/lib/claim-ledger-cli.js`, add a small help branch in `runClaimsCli` for `undefined`, `--help`, and `-h` so the command's own usage text matches the advertised CLI behavior.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

Why this is blocked

• PR description: this external-contributor feature explicitly says no upstream issue was filed, so it must either close or clearly link an eligible maintainer-authorized open issue before I can mark it merge-ready.
• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Signal	Result	Evidence
Code review	❌ 3 blockers	1 reviewer
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.
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 (no linked issue context).
Validation posture	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 1013 registered-repo PR(s), 707 merged, 41 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	jony376; Gittensor profile; 1013 PR(s), 41 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.

Review context

• Author: jony376
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 1013 PR(s), 41 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Explain no-issue PR.
• Await review-lane availability.
• Refresh registry data or choose a registered active repo.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.73%. Comparing base (1e9284b) to head (0dfa60a).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3314   +/-   ##
=======================================
  Coverage   93.73%   93.73%           
=======================================
  Files         276      276           
  Lines       30381    30381           
  Branches    11073    11073           
=======================================
  Hits        28479    28479           
  Misses       1257     1257           
  Partials      645      645           

🚀 New features to boost your workflow:

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

[JSONbored]

Please link this to the corresponding issues/sub-issues, as there's an open issue/task for working on the claims ledger stuff:

#2291

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (No linked issue detected; Maintainer requires a linked issue; AI reviewers agree on a likely critical defect: PR description: this external-contributor feature explicitly says no upstream issue was filed, so it must either close or clearly link an eligible maintainer-authorized open issue before I can mark it merge-ready.). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.