Skip to content

Add a 'recognizing a stale or missing coding-agent credential' troubleshooting table to the miner docs #5175

Description

@JSONbored

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

  1. Add a new table/section to packages/gittensory-miner/README.md titled along the lines of "Recognizing a stale or missing coding-agent credential."
  2. 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").
  3. 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.
  4. Mirror ORB's docs.self-hosting-ai-providers.tsx troubleshooting-table format/columns for consistency across the two docs.
  5. 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.
  6. 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

  • New table/section added to packages/gittensory-miner/README.md
  • Table covers the Claude Code no-oauth-token case, the Codex auth-failure case, and the generic fallback case
  • Each row has: error string/pattern, symptom, remediation step
  • Table format mirrors ORB's docs.self-hosting-ai-providers.tsx troubleshooting table
  • No invented/speculative error strings — every entry verified against the actually-shipped parser output

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.help wantedExtra attention is needed

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions