Skip to content

[Feature]: Safe Codex account failover with conversation handoff #10137

Open

Description

@kazu-42

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:

  1. recognize an authoritative Codex usage-limit failure;
  2. select and revalidate one eligible account on the same runtime target;
  3. hand off the existing conversation into that account's isolated CODEX_HOME;
  4. 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 usageLimitExceeded turn error and fresh rateLimitReachedType from 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:

  1. stop accepting source input and reap the source TUI/app-server writer;
  2. validate the source rollout path, ownership/containment, thread identity, and single-writer invariant;
  3. persist and fsync a prepared transition containing source account/thread, target account, and lineage metadata;
  4. start the target account's app-server and fork/import the source rollout into the target CODEX_HOME;
  5. verify exactly one target-local fork, expected lineage, an unchanged source rollout, and the target account identity;
  6. 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_HOME mutation under a live process
  • thread/fork has 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

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

  1. kazu-42 commented on Jul 31, 2026

    @kazu-42
    ContributorAuthor

    Follow-up after checking the merged prerequisites, the current Orca seams, and a separate local supervisor prototype.

    Current prerequisite state

    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:

    • one isolated CODEX_HOME per credential profile; never hot-swap global auth under a live process;
    • official app-server usage probes only, with authentication/network/protocol/unknown states treated as non-switchable failures;
    • an active/busy profile is unknown, not a candidate to probe concurrently;
    • explicit leases prevent two writers from owning the same profile;
    • exact thread IDs are automation-safe; --last and prompt replay are not;
    • displayed/rounded percentages are presentation data, not failover authority.

    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 prepared transition before a non-idempotent thread/fork.

    Smallest safe next contribution

    I recommend making the first implementation PR read-only signal plumbing only:

    1. capture a fixture-backed, supported Codex live-session/app-server exhaustion event;
    2. normalize it into a narrow session-scoped signal containing provenance, the recognized reached reason/window kind, and freshness;
    3. preserve it through Orca's agent-status path;
    4. return no signal for unknown reached types, missing fields, stale quota snapshots, auth/network/protocol errors, PTY text, assistant prose, or a displayed 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:

    • no account switch or candidate selection;
    • no reset-credit redemption;
    • no mobile mutation;
    • no fork/import/handoff;
    • no prompt replay through the existing continuation helpers;
    • no host/WSL/SSH expansion.

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions