Repository navigation
Description
Problem or use case
When the active Codex subscription reaches a usage limit, Orca can manage multiple Codex accounts, but changing the selected account restarts a fresh codex process. The user can continue working only by manually reconstructing context, and a naive retry of the last prompt could repeat external side effects.
#9394 proposes the mobile-side prerequisite: select an exact host/WSL managed account and consume an earned reset credit with durable idempotency. It intentionally does not automate account selection or preserve the current conversation across accounts.
The desired behavior is an opt-in Orca-managed account pool that can:
- recognize an authoritative Codex usage-limit failure;
- select and revalidate one eligible account on the same runtime target;
- hand off the existing conversation into that account's isolated
CODEX_HOME; - continue without replaying a prompt that may already have performed side effects.
This should not be driven by scraped TUI text or a displayed 100% value. Rate snapshots can be rounded, stale, absent, or shaped differently for weekly-only plans (see openai/codex#24445 and openai/codex#32707). Each Orca-managed account also has an intentionally separate CODEX_HOME, so codex resume <thread-id> cannot safely cross the account boundary by itself.
Proposed solution
I would like maintainer feedback on a staged, feature-flagged design before attempting the supervisor/handoff implementation.
1. Authoritative exhaustion state
- carry the structured Codex
usageLimitExceededturn error and freshrateLimitReachedTypefrom app-server into Orca's account state - require both a structured exhaustion error and a fresh, recognized reached reason before automatic failover
- fail closed for stale/null/unknown snapshots, authentication failures, network failures, and unsupported app-server versions
- never infer automatic failover from a rounded percentage alone
- keep reset-credit redemption a separate explicit user action
#10136 is a small prerequisite that classifies 5-hour and weekly windows by windowDurationMins; it prevents a weekly-only primary window from being shown as a 5-hour bucket.
2. Explicit account pool and bounded selection
- let the user opt exact managed accounts into a same-trust-domain pool for one host or one WSL target
- never mix native, WSL distro, or SSH targets implicitly
- serialize candidate selection with account mutations and revalidate the target account's identity, revision, authentication, and fresh capacity inside the lease
- visit each candidate at most once per exhaustion event, with a cooldown/circuit breaker to prevent account ping-pong
- expose the selected reason and next candidate on desktop/mobile; begin with a manual Switch and continue action before enabling automatic mode
3. Durable conversation handoff
Use an app-server-backed supervisor instead of hot-swapping credentials under a running PTY:
- stop accepting source input and reap the source TUI/app-server writer;
- validate the source rollout path, ownership/containment, thread identity, and single-writer invariant;
- persist and fsync a
preparedtransition containing source account/thread, target account, and lineage metadata; - start the target account's app-server and fork/import the source rollout into the target
CODEX_HOME; - verify exactly one target-local fork, expected lineage, an unchanged source rollout, and the target account identity;
- attach the target TUI/session, then atomically commit the transition before accepting new input.
Important constraints:
- no prompt replay: the exhausted turn may already have changed files or external systems
- no in-place
auth.json/CODEX_HOMEmutation under a live process thread/forkhas no idempotency key, so crash recovery should adopt only one unique matching target fork and otherwise fail closed for manual recovery- the cross-home rollout-path input is currently experimental, so support needs an exact app-server version/schema gate plus a startup smoke test; a stable thread-ID-only fork is not sufficient across isolated homes
- source and target rollout files must never have concurrent writers
4. Rollout and observability
- prototype local-host accounts first behind an off-by-default feature flag
- add WSL and SSH only behind explicit runtime capabilities and separate integration tests
- journal transition phases (
prepared,forked,attached,committed) and record bounded, privacy-safe diagnostics without prompts, tokens, or auth material - preserve a rollback/manual-recovery path: if handoff cannot be proven safe, keep the source transcript intact and offer normal manual account selection
Acceptance criteria
- automatic mode triggers only for a structured usage-limit error plus a fresh recognized reached reason
- stale/unknown/auth/network failures never rotate accounts
- a weekly-only plan is classified correctly and cannot cause false rotation
- no candidate is attempted more than once per exhaustion event
- a crash at every transition phase recovers deterministically without replaying the prompt or silently creating multiple forks
- the source rollout remains unchanged; the target rollout has verified lineage and exactly one writer
- if no candidate is safe, the user retains the transcript and gets a clear manual recovery action
- desktop and mobile show the exact runtime target/account involved; reset credits remain explicit
- tests cover reordered/null rate windows, app-server version mismatch, target/account revision changes, concurrent mutations, crash recovery, and host/WSL/SSH isolation
Alternatives or additional context
- #9365 fixes restart-command delivery with shell frameworks such as Starship, but it does not preserve a Codex conversation across account homes.
- #9394 provides manual mobile account selection/reset-credit controls and deliberately excludes automatic failover.
- [Feature] Managed Codex account switching for SSH remote worktrees #4387 is related multi-account work for SSH and should remain a separate capability boundary.
- Codex rate-limit reset banking: display banked resets per account and trigger manual reset #5494 covers earned reset-credit redemption, which should not be conflated with automatic account rotation.
- Codex app-server overview: https://developers.openai.com/codex/app-server/
- Codex CLI resume/fork reference: https://developers.openai.com/codex/cli/reference/
The narrow implementation order I recommend is: authoritative exhaustion metadata -> opt-in pool/manual handoff -> crash-tested local supervisor -> optional automatic mode -> WSL/SSH expansion.
Activity
kazu-42 commentedon Jul 31, 2026
Follow-up after checking the merged prerequisites, the current Orca seams, and a separate local supervisor prototype.
Current prerequisite state
primary/secondaryposition.account/rateLimits/readenvelopes and nested windows fail over instead of being accepted as empty usage.These close important prerequisites, but Orca still has no authoritative live-session exhaustion event, candidate lease/cooldown, or cross-account conversation handoff supervisor.
What the prototype comparison established
The useful implemented patterns are:
CODEX_HOMEper credential profile; never hot-swap global auth under a live process;unknown, not a candidate to probe concurrently;--lastand prompt replay are not;The automatic account pool and cross-profile handoff in that prototype are still design work, not production-proven implementation. The strongest reusable design points are a one-pass candidate pool plus cooldown, separating credential profile from conversation lineage, and a durable
preparedtransition before a non-idempotentthread/fork.Smallest safe next contribution
I recommend making the first implementation PR read-only signal plumbing only:
100%.If the currently supported app-server surface does not expose a stable structured event, that PR should stop at fixture/protocol evidence rather than infer exhaustion from text or quota percentages.
Out of scope for that first PR:
Once that signal is accepted, the next stage can be an advisory Switch and continue candidate on the same exact host/WSL target. Candidate capacity should be re-read with PTY fallback disabled, account identity/revision revalidated inside the serialized account mutation, each candidate visited once, and reset credits kept as a separate explicit action. Automatic mode and durable conversation handoff should remain later, separately reviewable stages.
This ordering gives Orca a trustworthy trigger before adding side effects. I can open the narrow signal-plumbing PR after maintainer confirmation of the supported event surface/raw reached values; otherwise the safest current contribution is to keep this issue at design/protocol-validation stage.