[teamleaderleo]

Leo, 2026-10-26: "if user picks a model they don't have api key, we offer them to add credits or add their own api key"

This PR ships the Add Credits… half of that. The Add API Key… half is split out to manaflow-ai/cmuxterm-hq#5411: no placement makes a key saved from the pane usable today, so a button for it would be a dead end (details below and in the issue).

What changed

A turn the cmux model router refused for want of credits is no longer a dead end.

• The refusal. The router answers 402 inference.plan_required or credits.insufficient, and its Messages endpoint passes only the text on to Claude Code.
  • Before: that refusal read as a quota failure ("rate-limited") with Switch model.
  • Now: it is its own failure kind, needs-credits, from the router's words or its typed code. The cause line reads " needs cmux credits or your own API key for this model." (the router's own words). The card leads with Add Credits… (filled), then Retry and Switch model, on both refusals.

Why Add Credits… fixes both refusals. In the router, resolveCaller (backend/apps/api/src/inference/route.ts) sends every caller without a paid plan (!plan.paid) down the credits path: inference.plan_required when that caller has no credits either, and credits.insufficient when a credit-funded caller's balance is short for the call. A paid-plan caller never reaches either. So the paid plan lifts both refusals. (An earlier revision of this PR assumed credits.insufficient meant "already on a plan"; that was wrong, and the card no longer treats the two differently.)

Add Credits… runs palette.pro.upgrade, the one paid-plan path from 6b30f93 (PaidPlanUpgrade: Checkout that returns to this app, else pricing), with source: inference. That source was declared for the model router's paywall but had no caller. No new pricing, no Stripe copy, no money flow. The app has no credit top-up (PLAN.md: top-ups are test mode only, refused on production), so this PR doesn't offer one.

The model picker keeps Log In alone. A signed-out local harness (Claude Code, Codex, Gemini) still lists only its own Log In in place of its models, as on base. An earlier revision also listed Add Credits… there, but cmux credits only help once the chat routes through the cmux model router: buying a plan doesn't sign the local harness in, add its key, or move the chat to the router, so after Checkout the tab would still be signed out with no models. That case is recorded on manaflow-ai/cmuxterm-hq#5411 with the key half.

Native gate. AgentPaneModel.runAction admits palette.pro.upgrade the same way it admits the existing connect actions: only on the person's fresh gesture in the pane. Its source comes from native code, never from the page. Settings > Accounts and every other app action stay out of the pane's reach.

Why no Add API Key… here (manaflow-ai/cmuxterm-hq#5411)

Two review findings:

• A key saved from the pane never reaches a built-in harness. acpmux spawns Claude Code, Codex and Gemini itself. Its per-session env (_meta.acpmux.env) passes only allow-listed keys (session_env.rs ALLOWED_KEYS), and _acpmux/harness/secret/set writes a ${keychain:…} reference only into user profile files; for the built-in profiles it edits nothing. The app's ProviderKeyStore item is read only by CodeRouter Connect.
• The cmux model router has no BYOK path. It calls providers with server keys only (INFERENCE_*_KEY, plans/cmux-next/paid-plan.md §2), so a person's key has nowhere to go there either.

The issue names the two ways to make it real: a key sheet whose key reaches the harness env through acpmux, or a router BYOK path.

Gallery (agent-pane.access-offer)

Variants: a refused turn with no credits (inference.plan_required), one short of credits (credits.insufficient), and a pane that cannot run app actions (no buttons, the cause line still names the way out). There are no arms: with one action there is no order to pick.

Before / after

No capture: the Swift side adds no native UI. It only lets the agent pane run the existing paid-plan Checkout (palette.pro.upgrade) on the person's click, and that Checkout surface is unchanged. The visible change is the agent pane webview, captured below.

Gallery entry agent-pane.access-offer, rendered in Chromium on Linux at the same fixture and size.

A turn the cmux model router refused for want of credits

	Light	Dark
Before: "ran into a problem", Retry only
After, either refusal (inference.plan_required or credits.insufficient; the two render the same card)

Risk

Low.

• Webview: adds a failure kind and its card action. The model picker is unchanged from base. The needs-credits match is narrow ("cmux credits" or the router's two codes), so other quota failures read as before.
• Native: widens action.run by one id behind the existing gesture gate, with a fixed native argument. palette.pro.upgrade keeps its behavior when invoked without arguments (palette, menu, CLI).
• Chief paths: none touched.
• Known limits: no Add API Key… yet (Custom sidebars beta toggle missing from Settings → Beta features on v0.64.13 #5411 in cmuxterm-hq); no pick-time credit pre-check for the cmux router harness, so the turn offer shows on its first refused turn.
• Overlap: none. This PR no longer changes picker source (only a test in signed-out-rail.test.tsx).

Tests

Red first, then green, at this scope:

• Webview, on Linux via cmux-ci: test/access-offer.test.tsx (classification from text and typed code; ACCESS_ACTIONS is only Add Credits…; on both refusals the card is Add Credits…, Retry, Switch model with one filled button and no Add API Key…; no buttons without the pane's actions; no offer on other failures) and test/signed-out-rail.test.tsx (a signed-out harness's picker tab lists its own Log In alone: no Add Credits…, no Add API Key…, even where the pane can run Add Credits…). Red at 52b6851 (3 fail: the old card offered Add API Key… and a "ran out / top-ups" line): run 41115963774. Green with the fix, plus turn-error-card, signed-out-harness, failure-copy-team-account, vp fmt (no changes) and bun run check (0 warnings, 0 errors): 41 pass, 0 fail, run 41116488039. Picker: red at 66a7ab8 (the tab listed "Add Credits…"): run 41120778276; green with the fix, the same suites and bun run check: 41 pass, 0 fail, run 41121779463, and at the head 45b5e31 (format check, the same suites and bun run check): 41 pass, 0 fail, run 41122952653. After merging feat-cmux-next (head b8bfe52): webview suites and bun run check 41 pass, 0 fail, run 41125914318; Swift AgentPaneAccessActionTests 2/2, AgentPaneConnectActionTests 14/14, PaidPlanUpgradeTests 10/10.
• Swift, on the Mac fleet (package-test-lane): AgentPaneAccessActionTests: Add Credits… needs a gesture and passes the fixed source: inference; accounts.show and accounts.remove stay refused even with a gesture. Red at 52b6851 (accounts.show still reachable). Green at 96baf37 with AgentPaneConnectActionTests and PaidPlanUpgradeTests: 2/2, 13/13 and 10/10 passed (Xcode 26.6).
• Strings: two new strings in all 21 languages (needs_review outside English).

Observed / Not run

• Observed: the red and green runs above, on fleet Linux (webview) and a fleet Mac (Swift), and the gallery stills of the turn card.
• Not run: no tagged app build and no live Checkout. The Swift change is a gate-list entry covered by AgentPaneAccessActionTests; the last picker commit changes no Swift, and the Swift suites were rerun at the merged head.

Agent session: agent session

🤖 Generated with Claude Code

[teamleaderleo]

Owned by an agent session · took over from an earlier session · session

[teamleaderleo]

Bead cx-kvtg2l created for this PR by the cmux coordinator.

[github-actions]

Default changes

This pull request changes 1 default at b8bfe52c90fd (what everyone gets without configuring anything):

• tunable-source.CmuxNextApp/Handlers/UpgradeToPro.swift:bind: "1e6f92fe2c9008a2d992a59b1e775ef8aa00bb149cc9d9f40ac5eb43ed8b40ae" -> "c4ef8132f360a5366f78cc961778b2674d6cdfd53ee151164349f40924ab230c"

Signed off on this commit by review (codex gpt-6-astra high fast, review-router).

Merge receipt: merged as 81085d96467e with these defaults changed, signed off by review (codex gpt-6-astra high fast, review-router).

Regenerate the snapshot with python3 scripts/ci/defaults_guard.py snapshot.

[github-actions]

cmux status _{(one comment, edited in place; each line is updated by the job that owns it)}

Review b8bfe52: HQ feed card · gallery before/after runs · checks

App of this head (app.zip, kept 1 day)

gh workflow run reload-build.yml -R manaflow-ai/cmux --ref feat-cmux-next -f tag=pr27058 -f ref=model-key-offer -f platform=macos -f backend_mode=local

Unclear: web / react-apps-base-check (4) failed: no known signature; failed step: Run base reds and compare. This PR merged before its CI finished: fix forward on main.

CI failed on b8bfe52c90 (run 41125849407 attempt 1): 2 unknown.
macOS jobs did not run: compile and app tests were skipped: Fast static checks skipped.

Job	Verdict	Why
web / react-apps-base-check (4)	unknown	no known signature; failed step: Run base reds and compare
web / react-apps-check	unknown	no known signature; failed step: Check webview test shards

Not re-run automatically: web / react-apps-base-check (4), web / react-apps-check are not machine failures.

Written by scripts/ci/classify_failures.py (ci-failure-attribution.yml); signatures are its SIGNATURES table. A machine verdict is the runner's fault, not this PR's; yours means the failing file is one this PR changes, also red on main that main's latest full suite fails the same way, seen on other PRs that it failed on another pull request's run lately.

web and size checks: green

Gallery before/after for b8bfe52: 16 states rendered, 6 images differ, 1417 more touched states not rendered. Images are in the run's artifact, not on this public PR.

gh run download 41125848825 -R manaflow-ai/cmux -n gallery-advisory-27058-b8bfe52c90fd6d1a927132566ab4e224a8091bea (then read gallery-review.json)

States

State	Theme	Status	Diff	Picked by
agent-pane.access-offer/turn-no-credits	Apple System Colors Light	new	0%	own accessOffer.ts
agent-pane.access-offer/turn-no-credits	Apple System Colors	new	0%	own accessOffer.ts
agent-pane.access-offer/turn-low-credits	Apple System Colors Light	new	0%	own accessOffer.ts
agent-pane.access-offer/turn-low-credits	Apple System Colors	new	0%	own accessOffer.ts
agent-pane.access-offer/turn-no-offer	Apple System Colors Light	new	0%	own accessOffer.ts
agent-pane.access-offer/turn-no-offer	Apple System Colors	new	0%	own accessOffer.ts
agent-pane.chat-width/standard	Apple System Colors Light	unchanged	0%	own App.tsx
agent-pane.chat-width/standard	Apple System Colors	unchanged	0%	own App.tsx
agent-pane.chat-width/wide	Apple System Colors Light	unchanged	0%	own App.tsx
agent-pane.chat-width/wide	Apple System Colors	unchanged	0%	own App.tsx
agent-pane.chat-width/wide-blocks	Apple System Colors Light	unchanged	0%	own App.tsx
agent-pane.chat-width/wide-blocks	Apple System Colors	unchanged	0%	own App.tsx
agent-pane.coderouter-offer/claude-key	Apple System Colors Light	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/claude-key	Apple System Colors	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/deepseek-key	Apple System Colors Light	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/deepseek-key	Apple System Colors	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/sign-in	Apple System Colors Light	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/sign-in	Apple System Colors	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/rate-limited	Apple System Colors Light	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/rate-limited	Apple System Colors	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/on-coderouter	Apple System Colors Light	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/on-coderouter	Apple System Colors	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/moving	Apple System Colors Light	unchanged	0%	own TurnRows.tsx
agent-pane.coderouter-offer/moving	Apple System Colors	unchanged	0%	own TurnRows.tsx
agent-pane.composer-edge/short-edge	Apple System Colors Light	unchanged	0%	own App.tsx
agent-pane.composer-edge/short-edge	Apple System Colors	unchanged	0%	own App.tsx
agent-pane.composer-edge/wide-edge	Apple System Colors Light	unchanged	0%	own App.tsx
agent-pane.composer-edge/wide-edge	Apple System Colors	unchanged	0%	own App.tsx
agent-pane.composer-edge/no-edge	Apple System Colors Light	unchanged	0%	own App.tsx
agent-pane.composer-edge/no-edge	Apple System Colors	unchanged	0%	own App.tsx
agent-pane.composer-floats/scrolled-to-end	Apple System Colors Light	unchanged	0%	own App.tsx
agent-pane.composer-floats/scrolled-to-end	Apple System Colors	unchanged	0%	own App.tsx

_{Pick other states with a Gallery: entry.id, entry.id/variant line in the PR body.}

[teamleaderleo]

Review (codex gpt-6-astra): SHIP at f77d043

Codex gpt-6-astra, high effort, fast mode, reviewed the full diff and all changed files over five rounds; every finding was settled before this SHIP:

• Round 1 (FIX): the router's typed errorCode (inference.plan_required, credits.insufficient) was not classified. Fixed, with tests.
• Round 2: SHIP (before a formatting-only commit).
• Round 3 (FIX): matching any mention of "cmux credits" was too broad. Narrowed to the router's two exact sentences plus its codes, with a negative test.
• Round 4 (FIX), answered rather than changed:
  • "Enum cases cannot have default associated values": Swift allows them since 5.1. The line compiled and its tests passed on the Mac fleet.
  • "Typed credits.insufficient needs a route check": these are the router's own namespaced codes, and a route check would drop the offer for Claude Code chats bound to the cmux route.
• Round 5: SHIP with those answers.

Checks at this head:

• Linux via cmux-ci: 46 webview tests pass, 0 fail; vp fmt --check, vp lint (0 warnings, 0 errors), vp check and check:catalog-keys pass.
• Swift on the Mac fleet: AgentPaneAccessActionTests 5/5, AgentPaneConnectActionTests 6/6 and PaidPlanUpgradeTests 10/10 passed at e56d855, which has the same Swift tree as this head.

[teamleaderleo]

Review (codex gpt-6-astra): SHIP at f77d043

Codex gpt-6-astra, high effort, fast mode, reviewed the full diff and all changed files over five rounds; every finding was settled before this SHIP:

• Round 1 (FIX): the router's typed errorCode (inference.plan_required, credits.insufficient) was not classified. Fixed, with tests.
• Round 2: SHIP (before a formatting-only commit).
• Round 3 (FIX): matching any mention of "cmux credits" was too broad. Narrowed to the router's two exact sentences plus its codes, with a negative test.
• Round 4 (FIX), answered rather than changed:
  • "Enum cases cannot have default associated values": Swift allows them since 5.1. The line compiled and its tests passed on the Mac fleet.
  • "Typed credits.insufficient needs a route check": these are the router's own namespaced codes, and a route check would drop the offer for Claude Code chats bound to the cmux route.
• Round 5: SHIP with those answers.

Checks at this head:

• Linux via cmux-ci: 46 webview tests pass, 0 fail; vp fmt --check, vp lint (0 warnings, 0 errors), vp check and check:catalog-keys pass.
• Swift on the Mac fleet: AgentPaneAccessActionTests 5/5, AgentPaneConnectActionTests 6/6 and PaidPlanUpgradeTests 10/10 passed at e56d855, which has the same Swift tree as this head.

[teamleaderleo]

Review (codex gpt-6-astra): SHIP at a178851

[blacksmith-sh]

Found 1 test failure on Blacksmith runners:

Failure

Test	View Logs
test_every_listed_hook_is_one_glaeda_released_with_the_check (main.SigningHooksInSt epWithGlaedaTests.test_every_listed_hook_is_one_glaeda_released_with_the_check)/ test_every_listed_hook_is_one_glaeda_released_with_the_check (main.SigningHooksInSt epWithGlaedaTests.test_every_listed_hook_is_one_glaeda_released_with_the_check)	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[teamleaderleo]

Orphaned: no activity for 14 h, and no lane holds a lease on it. The orphan sweep could not merge feat-cmux-next in: conflicts in webviews/src/agent-session/acpmux/Localizable.xcstrings. Listed for a lane to resolve.

[teamleaderleo]

Review (codex gpt-6-astra high fast, review-router): BLOCK at 8f2a0d6

• P2 — Adding an Accounts key cannot resolve the router refusal. webviews/src/agent-session/acpmux/App.tsx:5154 routes Add API Key to Accounts, whose Connect operation adds credentials to CodeRouter. The inference router checks plan/credit eligibility separately and reads upstream keys from Worker secrets; it never consumes those Accounts credentials. Adding a key and retrying therefore produces the same 402.

• P2 — The insufficient-credit card hides a valid upgrade path. webviews/src/agent-session/acpmux/conversation/TurnRows.tsx:546 assumes credits.insufficient means the caller already has a paid plan. Backend inference/route.ts creates credit-funded callers specifically when !plan.paid; insufficient reservation funds produce this error. These users can resolve it by upgrading, but this condition removes that action.

VERDICT: BLOCK

(Repair note, checked against the code: both hold. In backend/apps/api/src/inference/route.ts, resolveCaller returns kind: "credits" only when !plan.paid, and only that caller gets credits.insufficient, so the paid-plan upgrade does fix it; the P2 at 579c00f rested on the opposite premise. The router reads only its Worker provider keys (INFERENCE_*_KEY, plans/cmux-next/paid-plan.md §2), so no key saved in Accounts, or sent to CodeRouter, reaches it. With the picker's local-harness row already removed at 579c00f, Add API Key… has no placement left where a key it saves is used.)

[teamleaderleo]

Review (codex gpt-6-astra high fast, review-router): BLOCK at 96baf37

• P2 — Add Credits… in the picker is a dead end for a signed-out local harness. QuickModelMenu.tsx:722, ModelPicker.tsx:932 and ModelPicker.tsx:1580 offer Add Credits… for every signed-out local Claude/Codex/Gemini harness, but it only invokes palette.pro.upgrade (accessOffer.ts:15). That buys the cmux paid plan without signing in the selected local harness, adding its provider key, or switching to the cmux router. After checkout the same harness is still signed out with no models.

The turn card's Add Credits… on the router's two refusals drew no finding.

[cursor]

Bugbot needs on-demand usage enabled

Bugbot uses usage-based billing for this team and requires on-demand usage to be enabled.

A team admin can enable on-demand usage in the Cursor dashboard.

[teamleaderleo]

Review (codex gpt-6-astra high fast, review-router): SHIP at 45b5e31

No findings. The reviewer's output at this head was the verdict alone.

VERDICT: SHIP

[teamleaderleo]

Review (codex gpt-6-astra high fast, review-router): SHIP at b8bfe52

No findings. This head is 45b5e31 (SHIP above) merged with feat-cmux-next; the only hand-resolved conflicts were the runAction guard in AgentPaneModel+Actions.swift (base's new paletteActions plus this PR's accessActions) and two string-catalog lines. Reviewer: "No concrete defects found in the supplied diff. Exact-head surrounding source and runtime validation were unavailable." The full-source review is the SHIP at 45b5e31 above; the merged head passed the webview suites and bun run check on Linux (run 41125914318).

VERDICT: SHIP

[github-actions]

Shipped in:

• cmux NEXT nightly 1.0.0-nightly.4112983685701 (81085d9646)
• cmux NEXT nightly 1.0.0-nightly.4113159963901 (9408230f7a)
• cmux NEXT nightly 1.0.0-nightly.4113304608001 (567d1434e3)
• cmux NEXT nightly 1.0.0-nightly.4113454748501 (a94df426d7)