feat(miner): add local governor ledger CLI

[jony376]

Summary

• Add read-only gittensory-miner governor list for inspecting locally persisted governor decision events.
• Provide table and --json output with optional repo and event-type filtering.
• Cover argv parsing, table rendering, list flows, and CLI dispatch in unit tests.

Follow-up to #2328 (governor ledger storage foundation).

Scope

• The PR title follows type(scope): short summary Conventional Commit format (feat — new miner capability).
• Focused on read-only governor ledger inspection only — no MCP writes or network calls.

Validation

• npm run test:ci locally — CI will run the full gate on push.
• Unit tests cover list output, repo/type filtering, JSON shape, and invalid argv handling.

Safety

• No secrets, wallet details, hotkeys, or private scoring output in code or PR text.
• Read-only SELECT/list against local SQLite; no GitHub writes or uploads.

UI Evidence

Not applicable — miner CLI package only.

Notes

• Dispatch governor before the npm update check (same offline contract as ledger, queue, and plan).
• --type values are validated against the frozen GOVERNOR_LEDGER_EVENT_TYPES vocabulary from the engine.

[superagent-security]

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

[codecov]

❌ 3 Tests Failed:

Tests completed	Failed	Passed	Skipped
8438	3	8435	7

View the top 3 failed test(s) by shortest run time

test/unit/miner-cli.test.ts > gittensory-miner startup update check (#2331) > serves --help immediately without waiting for a slow registry check

Stack Traces | 0.175s run time

AssertionError: expected 'node:.../modules/esm/resolve:275…' to contain 'gittensory-miner --help'

- Expected
+ Received

- gittensory-miner --help
+ node:.../modules/esm/resolve:275
+     throw new ERR_MODULE_NOT_FOUND(
+           ^
+
+ Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../gittensory/gittensory/node_modules/@.../gittensory-engine/dist/index.js' imported from .../gittensory-miner/lib/governor-ledger-cli.js
+     at finalizeResolution (node:.../modules/esm/resolve:275:11)
+     at moduleResolve (node:.../modules/esm/resolve:861:10)
+     at defaultResolve (node:.../modules/esm/resolve:985:11)
+     at #cachedDefaultResolve (node:.../modules/esm/loader:747:20)
+     at ModuleLoader.resolve (node:.../modules/esm/loader:724:38)
+     at ModuleLoader.getModuleJobForImport (node:.../modules/esm/loader:320:38)
+     at ModuleJob._link (node:.../modules/esm/module_job:182:49) {
+   code: 'ERR_MODULE_NOT_FOUND',
+   url: 'file://.../gittensory/gittensory/node_modules/@.../gittensory-engine/dist/index.js'
+ }
+
+ Node.js v22.23.1
+

 ❯ test/unit/miner-cli.test.ts:319:20

test/unit/miner-cli.test.ts > gittensory-miner startup update check (#2331) > returns unknown-command errors immediately without waiting for a slow registry check

Stack Traces | 0.182s run time

AssertionError: expected 'node:.../modules/esm/resolve:275…' to contain 'Unknown command: mystery'

- Expected
+ Received

- Unknown command: mystery
+ node:.../modules/esm/resolve:275
+     throw new ERR_MODULE_NOT_FOUND(
+           ^
+
+ Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../gittensory/gittensory/node_modules/@.../gittensory-engine/dist/index.js' imported from .../gittensory-miner/lib/governor-ledger-cli.js
+     at finalizeResolution (node:.../modules/esm/resolve:275:11)
+     at moduleResolve (node:.../modules/esm/resolve:861:10)
+     at defaultResolve (node:.../modules/esm/resolve:985:11)
+     at #cachedDefaultResolve (node:.../modules/esm/loader:747:20)
+     at ModuleLoader.resolve (node:.../modules/esm/loader:724:38)
+     at ModuleLoader.getModuleJobForImport (node:.../modules/esm/loader:320:38)
+     at ModuleJob._link (node:.../modules/esm/module_job:182:49) {
+   code: 'ERR_MODULE_NOT_FOUND',
+   url: 'file://.../gittensory/gittensory/node_modules/@.../gittensory-engine/dist/index.js'
+ }
+
+ Node.js v22.23.1
+

 ❯ test/unit/miner-cli.test.ts:340:27

test/unit/miner-cli.test.ts > gittensory-miner startup update check (#2331) > serves --version without blocking when update checks are disabled

Stack Traces | 0.244s run time

AssertionError: expected 'node:.../modules/esm/resolve:275…' to contain '@jsonbored/gittensory-miner/0.1.0'

- Expected
+ Received

- @jsonbored/gittensory-miner/0.1.0
+ node:.../modules/esm/resolve:275
+     throw new ERR_MODULE_NOT_FOUND(
+           ^
+
+ Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../gittensory/gittensory/node_modules/@.../gittensory-engine/dist/index.js' imported from .../gittensory-miner/lib/governor-ledger-cli.js
+     at finalizeResolution (node:.../modules/esm/resolve:275:11)
+     at moduleResolve (node:.../modules/esm/resolve:861:10)
+     at defaultResolve (node:.../modules/esm/resolve:985:11)
+     at #cachedDefaultResolve (node:.../modules/esm/loader:747:20)
+     at ModuleLoader.resolve (node:.../modules/esm/loader:724:38)
+     at ModuleLoader.getModuleJobForImport (node:.../modules/esm/loader:320:38)
+     at ModuleJob._link (node:.../modules/esm/module_job:182:49) {
+   code: 'ERR_MODULE_NOT_FOUND',
+   url: 'file://.../gittensory/gittensory/node_modules/@.../gittensory-engine/dist/index.js'
+ }
+
+ Node.js v22.23.1
+

 ❯ test/unit/miner-cli.test.ts:306:20

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[gittensory-orb]

Caution

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

🛑 Gittensory review result - fixes required

_{Review updated: 2026-07-04 14:58:55 UTC}

6 files · no blockers · readiness 73/100 · CI failing · blocked

🛑 Suggested Action - Fix Blockers

• The AI review could not be completed for this change, so the gate is held for a human reviewer rather than passed automatically. It re-evaluates on the next update.

Review summary
AI review is already running for this PR head in another Gittensory pass. Gittensory is holding this PR for manual review until that pass completes.

Nits — 2 non-blocking

• AI review already in progress for this PR head — The gate is held for a human reviewer rather than passed automatically; it re-evaluates once the in-flight review completes or on the next update.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

CI checks failing

• validate
• validate-code

Signal	Result	Evidence
Code review	✅ No blockers	No AI review summary
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: 975 registered-repo PR(s), 693 merged, 40 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	jony376; Gittensor profile; 975 PR(s), 40 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

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: 975 PR(s), 40 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

[gittensory-orb]

Gittensory is closing this pull request on the maintainer's behalf (CI is failing (validate, validate-code)). 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.