feat(miner-hands): parse Claude Code's JSON error envelope in the CLI-subprocess driver (#5168)

[joaovictor91123]

Summary

• Today, when createCliSubprocessCodingAgentDriver sees a non-zero exit from the claude CLI, the only error shape it produces is ${command}_exit_${code}: ${stderr.slice(0,500)} -- it never inspects Claude Code's own structured JSON error envelope ({is_error, api_error_status}).
• Ports a claudeErrorStatus-style parser from src/selfhost/ai.ts into packages/gittensory-engine/src/miner/cli-subprocess-driver.ts (redeclared, not imported -- this package stays standalone per the file's own header comment).
• When options.command === "claude" and the exit is non-zero, the driver now parses stdout for the envelope. If found (is_error === true), it folds a precise claude_code_error_<status> into the returned error (falling back to subtype then "unknown" when api_error_status is absent), instead of the generic exit-code string.
• When the envelope is absent, malformed, or the command isn't claude, the existing raw ${command}_exit_${code}: <stderr slice> behavior is unchanged.
• The folded error passes through the same redactSecrets call every other error path in this driver already uses.
• No attempt/governor control-flow, retry logic, or state outside the error-message construction is touched.

Test plan

• npx vitest run test/unit/cli-subprocess-driver.test.ts -- 17/17 passing, including the new describe("Claude Code JSON error-envelope diagnostics (#5168)", ...) block: valid envelope folded into a precise status, subtype fallback, "unknown" fallback when both are absent, no-envelope regression (today's raw stderr-slice behavior preserved), valid-JSON-but-is_error: false falls through unchanged, non-claude command never inspects the envelope, and an invariant that a folded error is never left unredacted when it contains a known secret value.
• npx vitest run test/contract/coding-agent-driver-parity.test.ts -- 18/18 passing (unaffected).
• npx vitest run test/unit/coding-agent-miner.test.ts -- 57/57 passing (unaffected).
• npm --workspace @jsonbored/gittensory-engine run build -- clean.
• npm run typecheck -- clean.
• Isolated coverage via COVERAGE_NO_THRESHOLDS=1 npx vitest run test/unit/cli-subprocess-driver.test.ts --coverage --coverage.include="packages/gittensory-engine/src/miner/cli-subprocess-driver.ts" -- 100% statements/branches/functions/lines.
• npm run docs:drift-check -- clean.
• Did not run the full unsharded npm run test:coverage locally (shared/resource-contended machine); relying on CI's Codecov patch-coverage gate plus the isolated-coverage check above.

Fixes #5168.

[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.36%. Comparing base (73a0912) to head (91479cf).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5256   +/-   ##
=======================================
  Coverage   94.36%   94.36%           
=======================================
  Files         474      474           
  Lines       40081    40089    +8     
  Branches    14614    14617    +3     
=======================================
+ Hits        37821    37829    +8     
  Misses       1585     1585           
  Partials      675      675           

Flag	Coverage Δ
shard-1	46.40% <100.00%> (-0.13%)	⬇️
shard-2	34.72% <50.00%> (+0.06%)	⬆️
shard-3	32.11% <0.00%> (+0.07%)	⬆️
shard-4	32.04% <0.00%> (-0.09%)	⬇️
shard-5	33.77% <0.00%> (+0.05%)	⬆️
shard-6	44.77% <0.00%> (-0.03%)	⬇️

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

Files with missing lines	Coverage Δ
...ttensory-engine/src/miner/cli-subprocess-driver.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

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

[gittensory-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-12 12:09:46 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This ports a `claudeErrorStatus`-style JSON envelope parser into the CLI-subprocess driver, redeclaring rather than importing per the file's own standalone-package convention, and folds a precise `claude_code_error_<status>` message (with subtype/`unknown` fallback) into the returned error when Claude Code exits non-zero with a structured `{is_error, api_error_status}` envelope on stdout. The change is scoped correctly: it only branches for `command === "claude"`, falls through untouched for non-claude commands and malformed/absent envelopes, and reuses the existing `redactSecrets` call so the new path stays consistent with every other error path in this driver. Tests cover both branches of the `??` fallback chain (api_error_status present, subtype present, neither present), the is_error:false pass-through, the non-claude bypass, and a redaction invariant — solid, non-fabricated coverage of the new logic.

Nits — 5 non-blocking

• cli-subprocess-driver.ts:95-102 assumes `stdout.trim()` is a single clean JSON document; if Claude Code ever interleaves the JSON envelope with other stdout lines (e.g. streaming partial output before the final envelope), `JSON.parse` will throw and silently fall back to the generic exit-code error — worth a comment or a follow-up if that's a real CLI behavior, otherwise fine as-is.
• The JSDoc comment on `claudeErrorStatus` (cli-subprocess-driver.ts:91-96) is a solid multi-line explanation but slightly long relative to the repo's terser inline-comment style elsewhere in this file — consider trimming to the essential 'ported, not imported' rationale.
• Consider adding one more test case where stdout contains valid JSON but is an array or non-object (e.g. `"[]"` or `"null"`) to confirm `parsed.is_error` access doesn't throw on unexpected shapes — currently only 'not json at all' and well-formed objects are exercised.
• If Claude Code's `--output-format json` can emit trailing newlines or multiple JSON lines under `--output-format stream-json`, document that this parser intentionally only supports the single-envelope non-streaming case.
• nit: `packages/gittensory-engine/src/miner/cli-subprocess-driver.ts:96` accepts any JSON value for `api_error_status`/`subtype`, so an object or array becomes `claude_code_error_[object Object]`; constrain the parsed status to a non-empty string if Claude’s envelope contract is string-only.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5168
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: 117 registered-repo PR(s), 68 merged, 11 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	joaovictor91123; Gittensor profile; 117 PR(s), 11 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 change replaces an uninformative generic exit-code error with a precise, actionable diagnostic for a real Claude Code failure mode, is narrowly scoped to the stated issue (#5168), and is fully covered by well-targeted tests.

Linked issue satisfaction

Addressed
The diff adds a claudeErrorStatus-style parser gated on options.command === "claude", folds a precise claude_code_error_<status> value into the returned error when the {is_error, api_error_status} envelope is found, falls back to the original raw stderr-slice shape otherwise, and routes the folded value through the existing redactSecrets call, matching all stated requirements.

Review context

• Author: joaovictor91123
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, JavaScript, MDX, C++, CSS, Rust, TypeScript
• Official Gittensor activity: 117 PR(s), 11 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