fix(codex): preserve permission errors across authenticated requests

[steipete]

HTTP 403 from Codex OAuth and PAT endpoints was treated as expired authentication. In Auto mode this could trigger CLI recovery for a permission denial. Preserve the status and response body as a terminal server error; HTTP 401 retains authentication recovery.

Share request status, network-error, and cancellation handling across usage, reset-credit, spend-control, and PAT requests. Requests and decoding contracts remain unchanged. Production code decreases by 64 lines.

The actual fetcher-to-pipeline regression failed before the change, including Auto selecting the CLI fallback sentinel. All 93 focused tests across five suites pass, covering OAuth/PAT endpoints, 401 controls, and terminal 403 behavior. make check and the full make test suite pass (1,028 selections across 86 groups; no retries). Independent review found no actionable P0–P2 findings. Tests use synthetic responses; no live account access is claimed.

This extracts the status distinction discussed in #3379; the broader managed credential renewal work remains open. Thanks @Yuxin-Qiao for that work. Changelog and OAuth documentation are updated.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: blocked before merge. Reviewed September 7, 2026, 2:45 AM ET / 06:45 UTC.

ClawSweeper review

What this changes

Shares Codex authenticated-request error handling across OAuth and personal access tokens, preserving HTTP 403 permission errors while retaining HTTP 401 recovery.

Merge readiness

⛔ Blocked before merge - 1 item remains

This remains a useful, bounded fix: current main and v0.56.7 still classify 403 as expired authentication. No introduced correctness defect was found. The broader credential-renewal PR remains distinct, and repository policy protects this owner-authored PR from automatic closure.

Priority: P2
Reviewed head: e18ea785698a04a970e67605ee1c3215603aaeee

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, maintainable repair with relevant regression coverage and no actionable correctness finding; reported validation was not rerun during this read-only review.
Proof confidence	🌊 off-meta tidepool	Not applicable: This owner-authored PR is exempt from the ordinary contributor proof gate. Its fetcher-to-pipeline evidence uses stub responses and a CLI sentinel, not live transport; the narrowed error handling introduces no unresolved authority expansion requiring additional final-effect proof.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This owner-authored PR is exempt from the ordinary contributor proof gate. Its fetcher-to-pipeline evidence uses stub responses and a CLI sentinel, not live transport; the narrowed error handling introduces no unresolved authority expansion requiring additional final-effect proof.
Evidence reviewed	8 items	Current main still has the defect: The pinned main usage fetcher maps both 401 and 403 to unauthorized; the existing fallback policy treats unauthorized as recoverable. Latest release also retains the old classification: The v0.56.7 OAuth fetcher contains three combined 401/403 branches, covering usage, spend controls, and reset credits. Introduced behavior and security boundary: The shared handler reserves unauthorized for 401 and preserves other status codes and response bodies. Request headers, account selection, ephemeral-session isolation, and redirect guarding remain unchanged.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar fetches account usage and credit information through authenticated provider requests. Their error classification determines whether the refresh pipeline reports a failure or tries CLI recovery.

flowchart TD
  A[OAuth or personal access token] --> B[Authenticated API request]
  B --> C{HTTP response}
  C -->|Success| D[Decode usage or credits]
  C -->|401| E[Authentication recovery policy]
  C -->|403 and other errors| F[Preserve API failure]
  D --> G[Usage display]
  E --> H[Eligible CLI fallback]

Loading

Before merge

• Resolve merge risk (P2) - Existing Auto setups that previously obtained usage through CLI fallback after HTTP 403 will now display the API failure. The owner explicitly proposes this change, with synthetic regression coverage but no live upgrade trace.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test delta	Production −64 net lines; tests +52 net lines	Shared error handling removes duplication while focused endpoint and fallback coverage grows.

Merge-risk options

Maintainer options:

1. Accept the documented terminal 403 behavior (recommended)
   Retain the owner's explicit decision that permission-denied requests must surface their error instead of entering authentication recovery.

Technical review

Best possible solution:

Keep the owner-proposed permission-error distinction, preserve 401 recovery and account isolation, and leave managed credential renewal to its separate proposal.

Do we have a high-confidence way to reproduce the issue?

Yes, from source: a 403 usage response on pinned main becomes unauthorized and permits eligible Auto fallback. The fixture pipeline exercises that path; this review did not run it.

Is this the best way to solve the issue?

Yes. Centralizing the repeated HTTP classification is a narrow repair that preserves request construction, decoding, cancellation, and existing 401 recovery.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 02c073a22ab8.

Labels

Label changes:

• add P2: This is a bounded correction to Codex permission-error classification and recovery behavior.
• add merge-risk: 🚨 auth-provider: Merging intentionally removes automatic authentication recovery after a 403 for existing Auto configurations.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This owner-authored PR is exempt from the ordinary contributor proof gate. Its fetcher-to-pipeline evidence uses stub responses and a CLI sentinel, not live transport; the narrowed error handling introduces no unresolved authority expansion requiring additional final-effect proof.

Label justifications:

• P2: This is a bounded correction to Codex permission-error classification and recovery behavior.
• merge-risk: 🚨 auth-provider: Merging intentionally removes automatic authentication recovery after a 403 for existing Auto configurations.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This owner-authored PR is exempt from the ordinary contributor proof gate. Its fetcher-to-pipeline evidence uses stub responses and a CLI sentinel, not live transport; the narrowed error handling introduces no unresolved authority expansion requiring additional final-effect proof.

Evidence

What I checked:

• Current main still has the defect: The pinned main usage fetcher maps both 401 and 403 to unauthorized; the existing fallback policy treats unauthorized as recoverable. (Sources/CodexBarCore/Providers/Codex/CodexOAuth/CodexOAuthUsageFetcher.swift:440, 02c073a22ab8)
• Latest release also retains the old classification: The v0.56.7 OAuth fetcher contains three combined 401/403 branches, covering usage, spend controls, and reset credits. (Sources/CodexBarCore/Providers/Codex/CodexOAuth/CodexOAuthUsageFetcher.swift:440, d8f4cec19b82)
• Introduced behavior and security boundary: The shared handler reserves unauthorized for 401 and preserves other status codes and response bodies. Request headers, account selection, ephemeral-session isolation, and redirect guarding remain unchanged. (Sources/CodexBarCore/Providers/Codex/CodexAuthenticatedHTTPTransport.swift:18, e18ea785698a)
• Fallback and optional-enrichment boundaries: OAuth and PAT strategies reject fallback for serverError. Optional spend-control and reset-credit enrichment still contain non-cancellation failures; this patch does not turn those optional requests into mandatory refresh failures. (Sources/CodexBarCore/Providers/Codex/CodexProviderDescriptor.swift:472, e18ea785698a)
• Focused regression coverage and validation claims: Eight new endpoint/status combinations check 401 versus 403, response-body preservation, and request counts. The existing pipeline matrix now checks terminal 403 behavior across Auto, OAuth, and managed contexts. The captured PR body reports 93 focused tests plus make check and make test passing, explicitly using synthetic responses. This read-only review did not execute tests. (Tests/CodexBarTests/CodexOAuthExpiryPipelineTests.swift:7, e18ea785698a)
• Related work remains broader: The supplied discussion identifies Refresh managed Codex credentials without losing workspace scope #3379 as an open credential-renewal proposal. This PR extracts its 403 distinction without adopting native renewal, refresh coalescing, or new managed-workspace recovery. Its positive 401 account-renewal evidence does not establish live 403 behavior for this patch.

Likely related people:

• Harjoth Khara: Raw commit b079e9b adds Sources/CodexBarCore/Providers/Codex/CodexAuthenticatedHTTPTransport.swift:19 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: b079e9bcd946; files: Sources/CodexBarCore/Providers/Codex/CodexAuthenticatedHTTPTransport.swift)
• Oleksiy Akimov: Raw commit 814a5d5 adds Sources/CodexBarCore/Providers/Codex/CodexPAT/CodexPATUsageFetcher.swift:62 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 814a5d5e94dc; files: Sources/CodexBarCore/Providers/Codex/CodexPAT/CodexPATUsageFetcher.swift)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

The changed Auto behavior is intentional: an API permission denial is terminal, whereas expired authentication (401) remains eligible for recovery. Falling back after 403 obscures the selected API/account failure. This distinction is documented and exercised through the actual fetcher-to-pipeline path, including the CLI sentinel and 401 controls. The review found no introduced correctness or authority defect; the reported behavior change is the fix rather than an unresolved implementation issue. Broader credential renewal remains in #3379.