Switch execution accounts automatically at usage limits without losing phone access

[shiny-code-app]

Objective

Switch CLI execution automatically to another enrolled execution account when the current one hits its usage limit or fails authentication for good. The owner stays on the fixed control identity, so phone and local access are never lost. The owner decided on 2026-09-26 that this is a remaining account need: manual switching "has already gotten in my way and will be worse when I am remote".

the remaining account needs

This builds on the #979 account router (tools/account-router, landed in #982–#991), which already provides a fixed control identity and manual per-turn selection of the execution account. It replaces #599, which was written for the retired native Lab account pool.

Finish Line

During a real session driven from the phone, an execution account that hits its usage limit or fails authentication for good is replaced at a safe turn boundary without owner action. The switch is visible in the router status and on the phone, the control identity never changes, and no in-flight work is replayed.

Current Status

State: Active; this is the first account item in "Other needs on the fresh start".
Next action: write the switching policy against the landed router: which signals trigger a switch, the turn boundary where it happens, how the next account is picked, and how a switch is reported. Get owner approval before the router changes how any credential is used.
Blocked by: none. The #979 router is on main.
Waiting for: owner approval of the policy before live credential use changes (DIRECTION.md stop boundary).
Last verified: 2026-09-26.

Scope

• In: automatic switching of the execution account inside tools/account-router, triggered by usage-limit responses and terminal authentication failures; status and notifications for switches; router tests.
• Out: the control identity and its login; new enrollment or login flows; buying credits or deliberately spending allowance to test this; any patch to upstream files unless the router cannot see the signal.

Acceptance Criteria

Safety rules carried over from #599:

• The control identity never switches automatically and is never silently re-enrolled.
• An execution account switches only before a request is sent, or on a later turn. Once output, tool calls, commands or patches have been emitted, nothing is replayed automatically.
• Only an explicit terminal refresh failure (expired, reused or revoked refresh credential) marks an account as needing a new login. A generic 401, a timeout, a 5xx, or a TLS or DNS failure gets at most one bounded same-account retry and does not condemn the account.
• A usage limit marks the account unavailable until its reported reset time, not as broken.
• Restrictions on a workspace, model or entitlement apply only to what they affect.
• Router status and the phone show the failed account, the reason, the replacement account and the turn where the switch happened, without exposing credentials.
• When every execution account is exhausted, the owner gets a clear message instead of a silent stall.
• Tests cover: usage limit, terminal refresh failure, generic 401, ambiguous transport, control-account failure, all accounts exhausted, and no replay after side effects.

Relationships

• Replaces Switch execution accounts only after terminal authentication failure #599 (closed; written for the retired native pool).
• Builds on Separate GUI and phone identity from CLI execution accounts on the fresh start #979 and its router, and supports the phone flow in Make three local CLI sessions readable and replyable from iPhone #976.
• Surface per-account Codex reset credits and reset recommendation #383 (per-account reset visibility) and Add explicit opt-in quota-window priming for enrolled accounts #600 (quota-window priming) stay separate and parked.

Validation

• Router tests for every case in the acceptance criteria.
• One real switch observed from the phone, when a usage limit happens naturally. Do not spend allowance to force one.

Decisions

• 2026-09-26, owner: automatic execution-account switching is a remaining account need ("it's already gotten in my way and will be worse when I am remote").
• The first slice of Include account switching in the remote-access milestone #980 stays manual; this issue adds the automatic path after it.

Open Questions

• Does the router see the usage-limit signal directly in the model response, or does it need a stock app-server event?
• How should the next account be picked: by order, by soonest reset, or by the most remaining allowance?

[shiny-code-app]

Direction reconciliation, 2026-09-26 (against the owner's overall DIRECTION.md)

Kept active under the overall Order's repeat-stop rule. It removes a stop that has happened at least twice: #925 (rate limit exhausted, 2026-09-15) and #974 (the owner's 2026-09-26 report of immediate usage-limit stops). The owner's approval is still required before live credential use changes.

[shiny-code-app]

Closing as not planned. Automatic switching was built on the account router, which the owner retired on 2026-09-28 (see #979). #1001, merged by the owner, parks Codex Lab and retires "switching execution accounts between turns". A future need for more model capacity would come back only through a direction change.