[yeseoLee]

Summary

Fixes #4613.

On Linux, Claude CLI Auto went from an unavailable Web source straight to the interactive Claude CLI PTY. That took
~9 seconds even when OAuth credentials were readable.

This change adds OAuth between Web and CLI on non-macOS platforms.

Changes

• Linux CLI Auto: web → oauth → cli.
• OAuth availability reuses the existing noninteractive credential check (allowKeychainPrompt: false). Without
  usable credentials, the OAuth step is skipped and CLI remains the fallback.
• OAuth request failures, including 401 and 429, fall back to the CLI.
• Cancellation stays terminal.
• Preserved: macOS CLI Auto (web → cli, same attempt list), explicit source modes, and app runtime behavior.

Credential safety: the new path does not refresh or rewrite CLI-owned credentials. In the tested expired
CLI-owned credential cases, OAuth was skipped and no OAuth or token-refresh request was sent, so refresh stays with
Claude Code. This avoids reintroducing the refresh-token ownership issue in #1161.

The change reuses the CLI-runtime OAuth isolation from #1776 and adds no new subprocess.

Tests added

• ClaudeSourcePlannerTests: the CLI Auto plan includes OAuth only when the input requests it.
• ClaudeBaselineCharacterizationTests (macOS): with readable OAuth credentials, CLI Auto still resolves to
  claude.web, claude.cli.
• ClaudeCLIAutoOAuthLinuxTests:
  • OAuth is ordered before CLI.
  • notFound, 401, 429 and 503 fall back to the CLI.
  • Cancellation does not fall back.
  • Explicit OAuth stays terminal.
• PlatformGatingTests and ClaudeWebManualCookieLinuxTests: updated attempt lists.

The new ordering and fallback tests fail on unpatched main and pass with this change. The cancellation test passes
on both, because it guards existing behavior.

Verification

Real WSL2 account

Ubuntu 24.04.4, x86_64, Swift 6.3.3.

Command	Before	After
--provider both	9.63s	1.26s
Claude source	claude	oauth

87% faster, with matching usage windows.

Test suites

Environment	Result
macOS 15.7.9, M2 Pro	Focused Claude planner, characterization, web-deadline and OAuth suites pass; CLI Auto unchanged
Linux Docker, aarch64, Swift 6.3.3	swift test --parallel: 1,105 tests / 149 suites. One failure, ProcessOwnershipReaperTests, reproduces on unpatched main in the same container.
Linux regression tests	Fail on unpatched main; pass with this fix

Offline E2E

Ubuntu Docker, with synthetic credentials, a local HTTPS mock for the OAuth endpoints and a stub Claude CLI.

Scenario	Result
Valid OAuth	8.31s → 0.06s; CLI not launched
OAuth 429 / 401	Falls back to CLI
No credentials	OAuth skipped; CLI fallback
Expired CLI-owned token (with/without refresh token)	OAuth skipped; CLI fallback

Each scenario ran 5 times, except the expired-token variants, which ran 3 times each. In the expired-token cases, no
OAuth or token-refresh request reached the mock, and the credentials file stayed byte-identical.

Compatibility and limitations

• Frequent OAuth polling can receive HTTP 429, which falls back to the existing CLI path.
• make check reports an unrelated SwiftLint line-length violation in TypeSafeWebFetchStrategy.swift:175 that
  already exists on main.

Related: #4241, #1776, #1161.

🤖 Generated with Claude Code

[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.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-19T03:15:29.040887Z	e2f1ff0	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[clawsweeper]

Codex review: needs real behavior proof before merge.

What this changes

This PR inserts OAuth between Web and Claude CLI in Linux CLI Auto mode, retaining CLI fallback and terminal cancellation.

Example: WSL2 Ubuntu 24.04.4 with usable Claude Code OAuth credentials and no manual Web cookie.

• Before: Auto launches the Claude CLI PTY; the contributor reports 9.63 seconds for --provider both.
• After: Auto selects OAuth; the contributor reports 1.26 seconds with matching usage windows.

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	The patch is focused and has no definite correctness finding, but reported runtime results are not backed by inspectable proof and the default-selection decision remains open.
Proof confidence	🧂 unranked krab (1/6)	Real behavior proof is necessary before merge. See Before merge.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Performance · Worth it: Needs a maintainer decision · Fix scope: Complete
User problem: Linux Auto usage commands can spend roughly nine seconds starting Claude CLI despite having usable OAuth credentials.
Reason: The implementation is bounded and the reported gain is substantial, but automatically selecting another authentication source changes an existing documented default.

Merge readiness

⛔ Blocked before merge - 3 items remain

Keep open: this PR offers a focused Linux performance improvement that current main lacks, with no definite introduced code defect found; changing the documented authentication-source default needs an owner decision.

Priority: P2
Reviewed head: e302b060adfea4a8d75393851b9a9276fd7d2844
Owner decision: Required. See Decision needed.

Decision needed

• Question: Should Linux CLI Auto automatically try OAuth credentials before launching Claude CLI?
• Recommendation: Approve the Linux order: Adopt Web → OAuth → CLI using the existing credential-isolation rules.
• Why: The latency improvement is useful, but current documentation deliberately specifies Web then CLI, and no owner has approved changing that authentication-source default on this PR or its linked issue.

Before merge

• Add real behavior proof - The body reports WSL2 usage through the shipped CLI and offline OAuth/fallback checks, but only supplies summary tables without inspectable command output, logs, screenshots, or linked artifacts; attach those results for the changed Auto path, including credential-file integrity and absence of token-refresh requests for expired CLI-owned credentials, redacting keys, IPs, and non-public endpoints. After adding proof, update the PR body, then request a new review with @clawsweeper re-review. The PR author or someone with repository write access can request it.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.
• Add data-model compatibility proof - The review found that existing stored data may not work after upgrade. Show that existing data still loads and works with this change.

Findings

None.

Tests

• Low-value test TestsLinux/ClaudeCLIAutoOAuthLinuxTests.swift: Remove the added 'explicit CLI OAuth stays terminal' helper-only test: it checks shouldAttemptCLIAutoOAuth rather than terminal fallback behavior, so it does not establish its stated contract.
• Missing end-to-end proof: Provide redacted shipped-CLI output showing Linux OAuth selection, failed-request fallback, cancellation, and expired-token isolation, plus a v0.77.0 upgrade run with existing settings and credentials intact.

Agent review details

How this fits together

The shared Claude provider planner converts runtime, source selection, and credential availability into fetch strategies that return usage snapshots to the CLI or app.

flowchart TD
A[Linux CLI Auto] --> B[Claude source planner]
B --> C[Web strategy]
C --> D[OAuth strategy]
D --> E[Claude CLI fallback]
C --> F[Usage snapshot]
D --> F
E --> F

Loading

Technical review

Best possible solution:

Use the existing shared OAuth strategy for an owner-approved Linux Auto order, preserving credential ownership, CLI fallback, cancellation, and explicit-source behavior.

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

Current-main planner, documentation, and Linux tests establish that Auto omits OAuth; the PTY latency and improvement are contributor-reported, and no target code was executed during this read-only review.

Is this the best way to solve the issue?

Reusing the existing planner and OAuth strategy is a focused approach; explicit --source oauth already provides the fast path, but does not provide the requested automatic selection and fallback.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 6480977b47f6.

Provenance checked

• CLI Auto source order changes intended behavior with a stated reason (468950d: Refactor Claude provider planning foundations #494 centralized source planning while explicitly preserving existing behavior; it carried the Web → CLI order forward rather than establishing its original introduction.)
• Planned-strategy availability keeps the original intent (57d09ce: Guard logged-out Claude CLI usage #2070 delegated planned CLI availability to the underlying strategy to prevent logged-out interactive launches; this patch retains that check and adds OAuth delegation.)
• Credential ownership and OAuth fallback keeps the original intent (e17ba24: Stop direct Claude Keychain reads and route owner CLI by profile (lands #2380) #2585 established profile-scoped credential ownership and owner-CLI routing; the patch reuses those implementations without adding a refresh path.)

Testing

Proof path: unit tests only.

Security

None.

Evidence

What I checked:

• Introduced patch: The pinned diff adds platform-scoped OAuth planning, invokes existing OAuth availability checks, and permits Auto fallback after OAuth failures while preserving the existing cancellation guard. (Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift:374, e302b060adfe)
• Current-main contract: Current main explicitly documents CLI Auto as Web followed by CLI PTY; the proposed Linux order changes that contract rather than repairing an implementation that diverges from it. (docs/claude.md:40, 6480977b47f6)
• Credential isolation: The existing fetcher makes ProviderRuntime authoritative for delegated refresh, and the credential store routes expired Claude-CLI-owned credentials away from direct token refresh; this PR reuses those owners. (Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift:141, e302b060adfe)
• Prior isolation decision: The maintainer discussion in [codex] Isolate Claude OAuth usage from CLI refresh #1776 confirms intentional CLI OAuth isolation from delegated refresh and version subprocesses; it does not approve this new Auto default. (24490b6434d4)
• Related Linux capability: The maintainer merge discussion in Support Claude web usage on Linux with manual cookies #4241 confirms manual-cookie Linux Web support while automatic browser import remains macOS-only. (e254a5dbb76e)
• Supplied verification: The complete PR body reports real WSL2 timings and offline credential/fallback scenarios, but provides result tables without terminal traces, logs, or linked runtime artifacts; discussion adds no such artifacts. Captured body source identity: 07549081fcbe94d25dafa5e08f1b5d941ff45d219f641207af0a308430e15be9. (e302b060adfe)

Likely related people:

• Ratul Sarna: Raw commit 468950d adds Sources/CodexBarCore/Providers/Claude/ClaudeSourcePlanner.swift:169 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 468950d5b8f8; files: Sources/CodexBarCore/Providers/Claude/ClaudeSourcePlanner.swift)
• Derek Zeng: Raw commit 3bc9781 adds Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift:369 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 3bc978114747; files: Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift)

Labels

Label changes:

• add P2: The reported Linux startup overhead affects repeated usage commands, but commands still succeed and explicit OAuth is an available workaround.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Label justifications:

• P2: The reported Linux startup overhead affects repeated usage commands, but commands still succeed and explicit OAuth is an available workaround.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Attach redacted shipped-CLI runtime evidence for the reported Linux scenarios.
• Demonstrate upgrading from v0.77.0 with existing settings and credentials preserved.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 18, 2026, 9:09 AM ET / 13:09 UTC.

[steipete]

Merged in 7f7977b, thanks @yeseoLee! Linux CLI Auto now tries Claude OAuth before falling back to the slow PTY session.

We kept your routing fix, trimmed a few redundant predicates and source labels, strengthened the explicit-OAuth test, removed a stale help sentence, and added the changelog credit. It will ship in the next release.