Context
packages/gittensory-miner/README.md currently has no failure-mode remediation guidance mapping specific credential-related error strings to fixes. ORB's docs.self-hosting-ai-providers.tsx already ships an equivalent troubleshooting table on the hosted side. The concrete error strings this table needs to document (e.g. a Claude Code no-oauth-token status, a Codex auth-failure string) don't exist yet in the miner's CLI-subprocess driver — they are introduced by the two error-diagnostics parsing issues in this same batch.
Dependencies
Depends on the two error-diagnostics issues in this same batch landing first: "Parse Claude Code's JSON error envelope into actionable diagnostics in the CLI-subprocess driver" and "Parse Codex's JSONL stdout for its real error object in the CLI-subprocess driver." Those two issues introduce the actual error-string vocabulary (e.g. claude_code_no_oauth_token, a Codex auth-failure string resolving to a "run codex auth" remediation) this table documents. Do not start this issue until at least one of those two has merged with a concrete, shipped error-string set — ideally both, so the table can be written complete in a single pass rather than needing a follow-up PR per parser.
Requirements
- Add a new table/section to
packages/gittensory-miner/README.md titled along the lines of "Recognizing a stale or missing coding-agent credential."
- For each known failure mode, list: the exact error string or exit-code pattern surfaced by the CLI-subprocess driver (sourced from the merged error-diagnostics issues, not invented), a plain-language symptom description, and a concrete remediation step (e.g. "run
codex auth").
- Cover at minimum: the Claude Code no-oauth-token case, the Codex auth-failure case, and the generic non-zero-exit fallback case, so operators know what to do even when neither structured parser matched.
- Mirror ORB's
docs.self-hosting-ai-providers.tsx troubleshooting-table format/columns for consistency across the two docs.
- Scope this table strictly to credential/auth failure modes — do not fold in unrelated
doctor/config-validation errors from other issues (e.g. provider-gating or offline credential-presence checks) unless they map to the same literal error strings introduced by the two parsing issues.
- Do not invent or speculate about error strings the merged parsing issues did not actually introduce — every row must be verifiable against shipped source.
Deliverables / Acceptance Criteria
Test Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Because this is a documentation-only change, add: (1) a lightweight test asserting every error string listed in the new README table has a corresponding literal string constant in the CLI-subprocess driver source (so the table can't silently drift from the code), (2) an invariant test for "the table never contains a row whose error string isn't backed by an actual code-level constant," and (3) a regression test is not applicable since this isn't itself a bug fix — state that explicitly rather than omitting the point.
Expected Outcome
An operator whose miner attempt fails on a stale or missing Claude/Codex credential can look up the exact error string in the README and get a precise remediation step, instead of guessing from a raw stderr slice.
Links & Resources
- packages/gittensory-miner/README.md
- packages/gittensory-engine/src/miner/cli-subprocess-driver.ts
- apps/gittensory-ui/src/routes/docs.self-hosting-ai-providers.tsx (format model)
- See the "Parse Claude Code's JSON error envelope" issue in this same batch
- See the "Parse Codex's JSONL stdout for its real error object" issue in this same batch
- Theme: Claude/Codex self-host operational parity
Context
packages/gittensory-miner/README.md currently has no failure-mode remediation guidance mapping specific credential-related error strings to fixes. ORB's
docs.self-hosting-ai-providers.tsxalready ships an equivalent troubleshooting table on the hosted side. The concrete error strings this table needs to document (e.g. a Claude Code no-oauth-token status, a Codex auth-failure string) don't exist yet in the miner's CLI-subprocess driver — they are introduced by the two error-diagnostics parsing issues in this same batch.Dependencies
Depends on the two error-diagnostics issues in this same batch landing first: "Parse Claude Code's JSON error envelope into actionable diagnostics in the CLI-subprocess driver" and "Parse Codex's JSONL stdout for its real error object in the CLI-subprocess driver." Those two issues introduce the actual error-string vocabulary (e.g.
claude_code_no_oauth_token, a Codex auth-failure string resolving to a "runcodex auth" remediation) this table documents. Do not start this issue until at least one of those two has merged with a concrete, shipped error-string set — ideally both, so the table can be written complete in a single pass rather than needing a follow-up PR per parser.Requirements
packages/gittensory-miner/README.mdtitled along the lines of "Recognizing a stale or missing coding-agent credential."codex auth").docs.self-hosting-ai-providers.tsxtroubleshooting-table format/columns for consistency across the two docs.doctor/config-validation errors from other issues (e.g. provider-gating or offline credential-presence checks) unless they map to the same literal error strings introduced by the two parsing issues.Deliverables / Acceptance Criteria
packages/gittensory-miner/README.mddocs.self-hosting-ai-providers.tsxtroubleshooting tableTest Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Because this is a documentation-only change, add: (1) a lightweight test asserting every error string listed in the new README table has a corresponding literal string constant in the CLI-subprocess driver source (so the table can't silently drift from the code), (2) an invariant test for "the table never contains a row whose error string isn't backed by an actual code-level constant," and (3) a regression test is not applicable since this isn't itself a bug fix — state that explicitly rather than omitting the point.
Expected Outcome
An operator whose miner attempt fails on a stale or missing Claude/Codex credential can look up the exact error string in the README and get a precise remediation step, instead of guessing from a raw stderr slice.
Links & Resources