Fix #1844: block background Claude delegated refresh and mcpOAuth-only keychain touch

[Yuxin-Qiao]

Summary

Fixes the background browser-launch regression in #1844: when Claude Code stores only MCP OAuth state in Claude Code-credentials (no claudeAiOauth), CodexBar no longer runs background delegated claude /status refresh—which can launch the default browser via /usr/bin/open.

Scope: fail-closed safety guard for both keychain readers. Discovery of Claude Code 2.1.x's primary OAuth storage location remains tracked by #1823.

Problem

On Claude Code 2.1.x, the Claude Code-credentials keychain item may contain only mcpOAuth. CodexBar then fails to parse Claude OAuth credentials, treats the session as expired, and may periodically attempt delegated CLI refresh. That path can open the user's default browser from the background.

Contributing issues on main:

1. Delegated refresh used ClaudeOAuthKeychainPromptPreference.current(), which becomes .always when the experimental security CLI reader is active—so onlyOnUserAction did not suppress background repair.
2. Delegated refresh could still invoke claude /status even when the keychain shape could not succeed.

Changes

1. Honor stored keychain prompt mode for delegated refresh across all keychain read strategies (including securityCLIExperimental). Background refresh with onlyOnUserAction fails closed with existing user-action guidance instead of calling claude /status.
2. Detect MCP-only keychain payloads through both keychain readers via ClaudeOAuthCredentialsError.mcpOAuthOnlyKeychain, skip delegated CLI touch, and fail fast during expired Claude CLI credential load.
3. Split security CLI read paths: readRawClaudeKeychainPayloadViaSecurityCLIIfEnabled vs parsed credential load.
4. Isolated verification helper: the production /usr/bin/security reader can target a disposable keychain only while all general keychain access is disabled. Scripts/verify_1844_live.sh combines that keychain with disposable HOME, CFFIXED_USER_HOME, credentials, config, and a synthetic claude fixture that distinguishes benign CLI discovery from /status touch.

Tests

• Updated: background delegated-refresh suppression with experimental reader
• Added: MCP-only parse/shape detection
• Added: coordinator test—background MCP-only guard plus explicit Refresh recovery
• Added: store test—expired CLI owner fails closed in background and delegates on explicit Refresh
• Added: fail-closed tests for the isolated-keychain argument seam
• Added: standard Security.framework reader regression—background fails closed while explicit Refresh delegates

Verification

• Focused macOS integration tests (2026-07-03) — details in docs/verify-1844-proof.md
• Release-built CodexBar.app and packaged CodexBarCLI isolated live proof
• Real Claude-tab Refresh click against the isolated built app
• Final make check, 45-shard make test, and autoreview on the local port

Commands

make check
swift test --filter ClaudeOAuthTests
swift test --filter ClaudeUsageTests
swift test --filter ClaudeOAuthDelegatedRefreshCoordinatorTests
swift test --filter 'expired claude CLI owner blocks background'
swift test --filter ClaudeOAuthCredentialsStoreMCPOnlyGuardTests
./Scripts/verify_1844_live.sh

Fixes #1844. Primary OAuth storage discovery remains tracked by #1823.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 3, 2026, 3:32 PM ET / 19:32 UTC.

Summary
The PR detects MCP-only Claude keychain payloads, blocks background delegated Claude CLI refresh while preserving explicit Refresh recovery, and adds focused tests, docs, and an isolated live verifier.

Reproducibility: yes. The current-main failure path is source-reproducible from an expired Claude-CLI-owned OAuth cache plus an MCP-only Claude Code-credentials payload, and the PR adds focused tests for the fail-closed behavior and explicit Refresh recovery.

Review metrics: 3 noteworthy metrics.

• Changed surface: 19 files changed, +1231/-81. The diff spans Claude OAuth/keychain source, focused tests, docs, changelog, and a live verifier, so maintainers should treat it as auth-sensitive rather than routine cleanup.
• Reported verification: 105 focused tests plus packaged CLI/app proof. The PR body, proof doc, and owner comment report coverage for both reader strategies, background suppression, and explicit Refresh recovery.
• Open review comments resolved: 5 prior findings answered by final-head owner comments. The earlier actionable concerns around user Refresh, standard-reader coverage, payload leakage, fixture pinning, and browser canaries have explicit final-head fixes.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #1844
Summary: This PR is the candidate fix for the linked Claude background browser-launch report; the broader Claude OAuth storage-location problem remains separate.

Members:

• canonical: Claude provider: Claude Code-credentials keychain item holds only mcpOAuth entries on Claude Code 2.1.x → ClaudeOAuthCredentialsError + hourly "delegated CLI refresh" opens the default browser #1844 - The PR body uses closing syntax for the issue and implements the MCP-only keychain/background refresh guard it requested.
• partial_overlap: Claude constantly looses token for access #1823 - That open issue covers the broader Claude Code 2.1.x primary OAuth storage discovery that this PR explicitly leaves out of scope.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] This intentionally changes Claude auth/keychain behavior by failing closed for MCP-only keychain payloads in background, so affected users will need explicit Refresh, Web, CLI, or restored OAuth keychain state rather than silent background repair.
• [P1] The broader Claude Code 2.1.x primary OAuth storage discovery remains unresolved and is intentionally left to Claude constantly looses token for access #1823.
• [P1] The branch is behind current main by an unrelated landing-page commit, so maintainers should rely on the final merge result and normal checks before landing.

Maintainer options:

1. Accept the fail-closed guard (recommended)
   Merge after final branch checks if maintainers accept background fail-closed behavior for MCP-only Claude keychain state while preserving explicit Refresh recovery.
2. Hold for broader provider direction
   Pause this PR only if maintainers want the Claude Code 2.1.x primary OAuth storage discovery solved together instead of separately on the existing tracking issue.

Next step before merge

• No automated repair remains; maintainers should accept or decline the fail-closed Claude auth/keychain behavior and run normal final merge checks.

Security
Cleared: No concrete security or supply-chain regression was found; the patch reduces background keychain/CLI/browser exposure and keeps the live verifier on synthetic isolated credentials.

Review details

Best possible solution:

Land this narrow fail-closed guard for the background browser-launch regression, and keep primary Claude Code OAuth storage discovery tracked separately.

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

Yes. The current-main failure path is source-reproducible from an expired Claude-CLI-owned OAuth cache plus an MCP-only Claude Code-credentials payload, and the PR adds focused tests for the fail-closed behavior and explicit Refresh recovery.

Is this the best way to solve the issue?

Yes. The PR is the narrowest maintainable fix for the reported browser-launch regression because it blocks background delegation on a known-unsuccessful keychain shape while leaving user-initiated recovery intact.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 289ae204fa6b.

Label changes

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (logs): Contributor and owner comments provide after-fix macOS proof for the final candidate head, including isolated keychain fixture, packaged CLI/app behavior, and real menu Refresh recovery.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P1: The PR fixes an urgent Claude auth regression where background refresh can repeatedly launch the user's browser.
• merge-risk: 🚨 compatibility: Fail-closed MCP-only handling changes existing background refresh behavior for affected Claude OAuth users.
• merge-risk: 🚨 auth-provider: The patch changes Claude OAuth credential parsing, keychain reader behavior, and delegated refresh routing.
• merge-risk: 🚨 security-boundary: The patch intentionally gates keychain access and CLI/browser-triggering behavior, which are security-sensitive boundaries.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (logs): Contributor and owner comments provide after-fix macOS proof for the final candidate head, including isolated keychain fixture, packaged CLI/app behavior, and real menu Refresh recovery.
• proof: sufficient: Contributor real behavior proof is sufficient. Contributor and owner comments provide after-fix macOS proof for the final candidate head, including isolated keychain fixture, packaged CLI/app behavior, and real menu Refresh recovery.

Evidence reviewed

Acceptance criteria:

• [P1] make check.
• [P1] make test.
• [P1] swift test --filter ClaudeOAuthTests.
• [P1] swift test --filter ClaudeUsageTests.
• [P1] swift test --filter ClaudeOAuthDelegatedRefreshCoordinatorTests.

What I checked:

• Repository policy read: AGENTS.md was read in full and its keychain-safe validation, Claude provider isolation, and focused-test guidance apply to this review. (AGENTS.md:1, 289ae204fa6b)
• PR branch still carries live work: Current main does not contain the PR head; the PR diverges from 61ff932 and adds the Claude OAuth/keychain guard across 19 files. (42890113e4fa)
• Background delegated refresh honors stored prompt mode: The delegated refresh policy now uses the stored keychain prompt mode and remains applicable for the security CLI strategy, so background only-on-user-action refresh is suppressed before delegation. (Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift:200, 42890113e4fa)
• MCP-only keychain shape is explicit: The parser detects payloads with mcpOAuth and no claudeAiOauth, then raises the dedicated MCP-only credential error instead of treating the shape as a generic parse miss. (Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthCredentialModels.swift:90, 42890113e4fa)
• Expired Claude CLI owner fails closed in background: When cached Claude-CLI-owned credentials are expired and the keychain is MCP-only, background loads throw mcpOAuthOnlyKeychain before delegated CLI refresh. (Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthCredentials.swift:1177, 42890113e4fa)
• Explicit Refresh recovery is preserved: The coordinator skips the MCP-only guard for user-initiated interaction, and the regression test proves background suppression records zero touches while explicit user retry succeeds. (Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthDelegatedRefreshCoordinator.swift:416, 42890113e4fa)

Likely related people:

• Peter Steinberger: Current-main blame anchors the Claude OAuth/keychain paths to Peter, and the final PR head includes owner follow-up commits that fixed review comments around Refresh recovery, standard-reader coverage, and verifier isolation. (role: recent area contributor and reviewer; confidence: high; commits: 913b1a6412b5, 7f7f5863c58d, 5bb54dfb7993; files: Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthCredentials.swift, Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthDelegatedRefreshCoordinator.swift, Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthCredentials+SecurityCLIReader.swift)
• Ratul Sarna: Feature-history search shows multiple prior commits in the Claude security CLI/delegated refresh area, including account pinning, baseline observation, prompt-mode handling, and coordinator tests. (role: earlier Claude security CLI and delegated-refresh contributor; confidence: medium; commits: bca44feb76a0, 54120b9c4a67, 59f071088305; files: Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthCredentials+SecurityCLIReader.swift, Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthDelegatedRefreshCoordinator.swift, Tests/CodexBarTests/ClaudeOAuthDelegatedRefreshCoordinatorTests.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

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

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[Yuxin-Qiao]

macOS verification (2026-07-03)

Contributor verification for the Phase 1 guard in this PR. Full write-up: docs/verify-1844-proof.md on the PR branch.

Environment: macOS arm64, Claude Code 2.1.193, branch cursor/fix-claude-oauth-background-refresh-1114 @ 7befb637

Integration tests

swift test --filter 'mcp O auth|delegated retry experimental|load with auto refresh expired claude CLI owner throws mcp'

Result: 5/5 passed on macOS release-linked binaries.

Behavior	Result
Background onlyOnUserAction suppresses delegated refresh (securityCLIExperimental)	Pass
Coordinator skips claude /status when keychain is MCP-only	Pass
Expired Claude CLI owner fails fast with mcpOAuthOnlyKeychain	Pass

Representative logs:

Claude OAuth delegated refresh skipped: Claude keychain has MCP OAuth state only
Claude OAuth credentials expired; Claude keychain has MCP OAuth state only

No delegated CLI touch or /usr/bin/open activity is exercised in these tests.

Keychain fixture E2E

Not completed in unattended automation (macOS Keychain write requires interactive approval). Optional follow-up on a machine with the reporter's keychain shape, or locally via:

./Scripts/verify_1844_live.sh

Conclusion

Phase 1 code paths are covered by macOS integration tests and demonstrate fail-closed behavior for MCP-only keychain payloads without background delegated CLI refresh.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[Yuxin-Qiao]

Keychain E2E verification (2026-07-03)

Ran ./Scripts/verify_1844_live.sh on macOS arm64 after approving the Keychain fixture prompt.

Phase	Result
Integration tests	5/5 passed
Keychain fixture E2E	Passed

Background CodexBarCLI usage --provider claude --source oauth with MCP-only Keychain fixture + expired credentials file:

• stdout: fail-closed provider error (Claude OAuth token expired. CodexBar CLI does not launch Claude to refresh credentials.)
• No /usr/bin/open or browser child processes in proc log
• Fixture installed via security add-generic-password (account codexbar-verify-1844)

@clawsweeper re-review

[Yuxin-Qiao]

Verifier hardening (2026-07-04)

Polished ./Scripts/verify_1844_live.sh per review feedback:

• Isolated HOME under $TMPDIR/codexbar-1844-verify/home — never reads/writes real ~/.claude/.credentials.json
• Keychain preflight — unpinned security find-generic-password must return the MCP fixture before the background probe runs (skips cleanly when another Claude Code-credentials item takes precedence)
• Trust CodexBarCLI + /usr/bin/security on the fixture ACL
• Stricter Phase 2 assertions — require MCP OAuth state only diagnostics; reject background delegated refresh without the guard

Docs: docs/verify-1844-proof.md, PR body checklist updated.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0551c7963c

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2d3830ae0b

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[steipete]

Maintainer exact-head verification (2026-07-03)

Exact candidate: 42890113e4fa93870b2ededc81027659c85b5d95

• make check: pass
• make test: all 45 shards pass
• focused Claude OAuth regression matrix: 105 tests pass
• ./Scripts/verify_1844_live.sh: pass against a release-built app and packaged CLI using a disposable HOME, config, credentials file, and isolated keychain
• background MCP-only path: packaged CLI exits 3 with recovery guidance; no delegated /status, /usr/bin/open, or browser child
• packaged-app background smoke: only synthetic Claude --version discovery; app remains running for five seconds; no /status or browser child
• real menu proof: selecting Claude and clicking Refresh invokes synthetic /status; browser/open canary remains untouched
• default keychain search list unchanged; real ~/.claude/.credentials.json never referenced
• autoreview: no accepted/actionable findings
• source-blind behavior contract: pass

This lands the browser-launch regression fix from #1844. Discovery of Claude Code 2.1.x's primary OAuth storage remains separately tracked by #1823.