Document Claude multi-account architecture

[steipete]

Summary

• audit the current Claude OAuth, token-account, snapshot, and status-item architecture
• recommend an opt-in, read-only claude-swap v0.15 adapter for durable multi-subscription usage
• define a provider-neutral account snapshot and bounded per-account status-item behavior
• include a rendered UI decision mock and redacted packaged synthetic sign-in proof

This is a decision document only. It intentionally does not add credential storage, account switching, an external dependency, or product behavior.

Recommendation

1. Approve display-only cswap --list --json integration as Phase 1.
2. Defer --switch-to until a separate explicit-action product/auth review.
3. Normalize account usage before status-item work.
4. Make selected account items opt-in, capped at four, and mutually exclusive with Merge Icons.

Architecture and overlap evidence

• [codex] Scope Claude OAuth history by Keychain identity #1800 and [codex] Isolate Claude OAuth usage from CLI refresh #1776 are merged and improve single-active-Claude-account correctness; neither enumerates subscriptions.
• [codex] Refine Claude stacked account menu #1707 is closed and should not be revived because it mixed credential discovery, routing, menus, and prompt behavior.
• The current ProviderTokenAccount model has one token and no refresh/expiry fields.
• StatusItemIdentity and status-item storage remain provider-scoped.
• claude-swap v0.15.0 documents a credential-free, versioned --list --json output contract.

Validation

• make check
• structured Codex autoreview: clean, no findings
• SVG XML validation and local render inspection
• packaged synthetic-account screenshot inspection; no real credential, browser session, or provider call

Refs #1756
Refs #1268
Follow-up to #1811

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 1, 2026, 7:12 AM ET / 11:12 UTC.

Summary
Adds a Claude multi-account/status-item decision document, an SVG UI decision mock, and a packaged synthetic sign-in proof image under docs.

Reproducibility: not applicable. this is a docs-only decision proposal rather than a broken runtime behavior report. Source inspection is sufficient to verify the architecture statements it makes.

Review metrics: 2 noteworthy metrics.

• Changed surface: 3 docs files added, 0 source files changed. This confirms the PR should be reviewed as architecture documentation, not as a runtime behavior change.
• Prior review finding: 1 docs finding addressed. The re-review specifically checks that the OAuth isolation wording was corrected in the latest commit.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

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

Risk before merge

• [P1] Merging this records a recommended product/auth direction but does not implement the linked multi-account or per-account status-item behavior; maintainers should be comfortable treating the read-only claude-swap boundary as accepted architecture before landing it.

Maintainer options:

1. Decide the mitigation before merge
   Land this as a decision record if maintainers accept the read-only claude-swap Phase 1 boundary, then implement Support multiple Claude accounts OR support account swapping with claude-swap #1756 and Allow multiple account in the status bar for same provider. #1268 in narrow follow-up PRs.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• No automated repair is needed; the remaining action is maintainer/product acceptance of the owner-authored decision record.

Security
Cleared: No concrete security or supply-chain issue was found in the docs-only diff; it adds no executable dependency, and the SVG mock has no script or external-reference surface in the inspected markup.

Review details

Best possible solution:

Land this as a decision record if maintainers accept the read-only claude-swap Phase 1 boundary, then implement #1756 and #1268 in narrow follow-up PRs.

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

Not applicable; this is a docs-only decision proposal rather than a broken runtime behavior report. Source inspection is sufficient to verify the architecture statements it makes.

Is this the best way to solve the issue?

Yes; after the OAuth-scope correction, a docs-first decision record is the narrowest maintainable way to settle the auth/status-item direction without changing runtime behavior.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 129f6962e6c3.

Label changes

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P3: This is low-risk documentation and product-direction work with no runtime implementation in the diff.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

What I checked:

• AGENTS policy read: Read the full repository AGENTS.md; its provider-data siloing, no-live-Keychain-probe, and menu-test guidance shaped this source-only docs review. (AGENTS.md:1, 129f6962e6c3)
• PR changed surface: The PR adds three docs files and no source files, so this should be reviewed as an architecture/product decision record rather than a runtime implementation. (docs/claude-multi-account-and-status-items.md:1, 11838a8a490b)
• Prior finding addressed: The current document now says the merged OAuth isolation applies to CLI-runtime refreshes while app and user-initiated repair remain available, matching current source and the referenced merged PR. (docs/claude-multi-account-and-status-items.md:45, 11838a8a490b)
• Current OAuth boundary: Current main still allows delegated Claude OAuth refresh only in app runtime, supporting the corrected CLI/app wording in the decision document. (Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift:121, 129f6962e6c3)
• Token account limitation: ProviderTokenAccount stores one token plus metadata and has no refresh-token or expiry fields, matching the document's durable OAuth-account gap. (Sources/CodexBarCore/TokenAccounts.swift:3, 129f6962e6c3)
• Status item scope: StatusItemIdentity currently has only merged and provider cases, and statusItems is keyed by UsageProvider, matching the document's provider-scoped status-item audit. (Sources/CodexBar/StatusItemController.swift:47, 129f6962e6c3)

Likely related people:

• steipete: Blame/log history points to this handle for the provider-scoped status item identity/storage, much of the token-account baseline, and recent Claude OAuth/history and sign-in decisions referenced by the document. (role: recent area contributor and product-direction owner; confidence: high; commits: f380287041b8, 92bbb7a67073, c57de22c9ffe; files: Sources/CodexBar/StatusItemController.swift, Sources/CodexBarCore/TokenAccounts.swift, Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift)
• derekszen: The merged CLI OAuth isolation PR and blame on ClaudeUsageFetcher are the source of the CLI/app refresh boundary summarized by this decision record. (role: introduced referenced OAuth isolation behavior; confidence: high; commits: 3bc978114747, 24490b6434d4; files: Sources/CodexBarCore/Providers/Claude/ClaudeUsageFetcher.swift, Sources/CodexBarCLI/CLIUsageCommand.swift)
• BAKEZQ: Recent token-account metadata work touched the shared ProviderTokenAccount model that this proposal audits for durable multi-account limitations. (role: recent adjacent contributor; confidence: medium; commits: 2435c93453fe; files: Sources/CodexBarCore/TokenAccounts.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.

[steipete]

Addressed the OAuth isolation finding in commit 11838a8a4.

The decision record now states that #1776 prevents CLI-runtime usage refreshes from delegating credential repair, while app and user-initiated repair remain available: docs/claude-multi-account-and-status-items.md:45.

Validation: git diff --check, make check, and local autoreview clean (0.94).

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

[steipete]

Exact-head CI proof for the decision record:

• Head: 11838a8a490b9ddaf9f2f9f6dcb61ed514200878
• Run: https://github.com/steipete/CodexBar/actions/runs/28509810342
• Final attempt 4: completed successfully
• Passed: changes, lint, Linux x64, Linux arm64, macOS shards 0/4 through 3/4, aggregate lint-build-test, and GitGuardian

Attempts 2 and 3 were externally cancelled while macOS jobs were queued/running; their logs contained no test assertion failure. The cancelled-job-only rerun completed the same frozen head without a source change.

The PR remains open intentionally: CI and automated review are clean, but the read-only claude-swap boundary and per-account status-item policy require maintainer/product acceptance before merge.