feat(miner): respect --json on CLI error paths

[RealDiligent]

Summary

• Add shared cli-error helper (reportCliFailure, argsWantJson, describeCliError) so miner CLI failure paths emit { ok: false, error } on stdout when --json is set.
• Wire the helper across miner subcommands; wrap calibration ledger open in try/catch for structured --json failures.
• Unit tests cover helper behavior, per-command --json failure paths, and a dedicated coverage test for parse/runtime error branches (codecov patch).

Closes #4836

Test plan

• npx vitest run test/unit/miner-cli-error.test.ts test/unit/miner-cli-json-error-coverage.test.ts
• npx vitest run test/unit/miner-portfolio-queue-cli.test.ts test/unit/miner-plan-store-cli.test.ts test/unit/miner-cli-run-state.test.ts test/unit/miner-claim-ledger-cli.test.ts test/unit/miner-governor-ledger-cli.test.ts test/unit/miner-loop-cli.test.ts test/unit/miner-manage-poll.test.ts test/unit/miner-calibration-cli.test.ts

[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.87%. Comparing base (4b609eb) to head (7ad9a70).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5541      +/-   ##
==========================================
+ Coverage   94.79%   94.87%   +0.07%     
==========================================
  Files         567      568       +1     
  Lines       45090    45033      -57     
  Branches    14675    14675              
==========================================
- Hits        42743    42724      -19     
+ Misses       1613     1575      -38     
  Partials      734      734              

Flag	Coverage Δ
shard-1	43.80% <15.38%> (-0.38%)	⬇️
shard-2	35.44% <28.20%> (-0.02%)	⬇️
shard-3	32.15% <21.79%> (+0.16%)	⬆️
shard-4	31.37% <7.69%> (-0.48%)	⬇️
shard-5	33.36% <17.94%> (+0.45%)	⬆️
shard-6	44.39% <60.25%> (+0.90%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/gittensory-miner/lib/attempt-cli.js	96.73% <100.00%> (-0.09%)	⬇️
packages/gittensory-miner/lib/calibration-cli.js	100.00% <100.00%> (ø)
packages/gittensory-miner/lib/claim-ledger-cli.js	99.28% <100.00%> (+2.68%)	⬆️
packages/gittensory-miner/lib/cli-error.js	100.00% <100.00%> (ø)
packages/gittensory-miner/lib/cli.js	100.00% <100.00%> (ø)
packages/gittensory-miner/lib/deny-check.js	87.80% <100.00%> (-0.30%)	⬇️
packages/gittensory-miner/lib/discover-cli.js	100.00% <100.00%> (ø)
packages/gittensory-miner/lib/event-ledger-cli.js	98.27% <100.00%> (+1.58%)	⬆️
packages/gittensory-miner/lib/feasibility-cli.js	100.00% <100.00%> (ø)
...ckages/gittensory-miner/lib/governor-ledger-cli.js	98.48% <100.00%> (+2.83%)	⬆️
... and 10 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]

Caution

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

🛑 Gittensory review result - reject/close recommended

_{Review updated: 2026-07-13 03:36:10 UTC}

36 files · 2 AI reviewers · 1 blocker · readiness 100/100 · CI green · clean

🛑 Suggested Action - Reject/Close

Review summary
This PR adds a shared cli-error.js helper (reportCliFailure/argsWantJson/describeCliError) and threads it through every miner CLI subcommand so parse-error, not-found, and runtime-exception paths emit `{ ok: false, error }` JSON when `--json` is set instead of always writing to stderr. The refactor is mechanical and consistent across ~18 files, correctly using `argsWantJson(args)` for pre-parse failures (where `parsed.json` doesn't exist yet) and `parsed.json` post-parse, and the new tests directly exercise the JSON-vs-stderr branches per command. The main gap is codecov/patch failing at 94.87% against a 99% target, so some added branch is under-tested.

Blockers

• packages/gittensory-miner/lib/discover-cli.js:165 opens the required portfolio queue before the try/catch, so `gittensory-miner discover ... --json` still throws directly instead of emitting `{ ok: false, error }` when `initPortfolioQueueStore()` fails; move that open into the existing try and keep the close in `finally`.

Nits — 5 non-blocking

• packages/gittensory-miner/lib/attempt-cli.js:155 and :230 reuse the literal exit code `3` for two different failure reasons (paused mode vs. dependency-build failure); a named constant would make the exit-code contract clearer, especially since this file's exit codes are otherwise enumerated via the `switch` at the bottom.
• codecov/patch is at 94.87% vs the 99% target — worth checking which branch (likely a `describeCliError`/`reportCliFailure` call site or an edge in `parseCliJson`-adjacent code) is still uncovered before merge.
• packages/gittensory-miner/lib/attempt-cli.js and loop-cli.js are already flagged as long files (471/476 lines); this PR adds import lines to both but doesn't grow them meaningfully, so it's pre-existing size debt rather than something this diff should be blocked on.
• Run `npx vitest run --coverage` locally (or check the codecov patch report) to find the specific uncovered branch dragging patch coverage below 99% and add one targeted test for it.
• Consider giving `reportCliFailure`'s exit-code parameter named constants (e.g. `EXIT_PAUSED = 3`) in the two attempt-cli.js/loop-cli.js call sites that reuse `3` for distinct failure reasons.

Why this is blocked

• packages/gittensory-miner/lib/discover-cli.js:165 opens the required portfolio queue before the try/catch, so `gittensory-miner discover ... --json` still throws directly instead of emitting `{ ok: false, error }` when `initPortfolioQueueStore()` fails; move that open into the existing try and keep the close in `finally`.

📋 Copy for AI agents — paste into your coding agent

Fix the following blocker(s) from this PR review:

1. packages/gittensory-miner/lib/discover-cli.js:165 opens the required portfolio queue before the try/catch, so \`gittensory-miner discover ... --json\` still throws directly instead of emitting \`\{ ok: false, error \}\` when \`initPortfolioQueueStore\(\)\` fails; move that open into the existing try and keep the close in \`finally\`.

Signal	Result	Evidence
Code review	❌ 1 blocker	2 reviewers, synthesized
Linked issue	✅ Linked	#4836
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: 310 registered-repo PR(s), 142 merged, 25 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	RealDiligent; Gittensor profile; 310 PR(s), 25 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — The change closes issue #4836 by making every miner CLI failure path honor `--json` consistently via one shared helper, which is a real, well-scoped correctness fix for scripting/automation consumers of this CLI rather than speculative feature work.

Review context

• Author: RealDiligent
• 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: 310 PR(s), 25 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 is closing this pull request on the maintainer's behalf (AI reviewers agree on a likely critical defect: packages/gittensory-miner/lib/discover-cli.js:165 opens the required portfolio queue before the try/catch, so `gittensory-miner discover ... --json` still throws directly instead of emitting `{ ok: false, error }` when `initPortfolioQueueStore()` fails; move that open into the existing try and keep the close in `finally`.). 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.