Continue a thread on another account when it hits a usage limit

[corneliu10]

The problem

Many of us run T3 Code with more than one subscription seat. Provider instances already let us add several Claude or Codex accounts and pick one per thread, and the new orchestrator lets us switch account mid-thread. But when a long run stops on a usage limit, the thread has two options: wait for the reset ("Resume at reset" / "Snooze until reset") or switch by hand. If you're asleep or away, the work just stops, even though another account has quota left.

This came up before in #5863 (seven Claude Max accounts; pick the account with headroom) and #2111 (link several accounts and auto-switch). Both were closed in the maintenance sweep. The manual-switch part of #2111 is solved now; switching automatically is not.

What I'd like to propose

Two pieces. The first stands on its own.

1. A Claude shadow home, like Codex's shadowHomePath

Today two Claude instances with different CLAUDE_CONFIG_DIRs get different continuation keys (claude:home:<dir>). So switching between them is always create_with_handoff: a transcript capped at 16k tokens, with no native tool or reasoning state.

Codex already solves this with shadowHomePath: each account keeps its own auth.json, the session dirs are symlinked to one shared home, and the continuation key is the shared home. The same design works for Claude:

• Setting: shadowHomePath on a Claude instance. homePath stays the shared home, and the shadow becomes this account's CLAUDE_CONFIG_DIR. The keychain item is named from that dir, so each login stays separate automatically.
• What's shared: an allowlist is symlinked: projects, file-history, tasks, todos, plans, session-env, shell-snapshots, paste-cache, agents, commands, skills, plugins, plus history.jsonl, settings.json and CLAUDE.md. Everything else stays private, including .claude.json, .credentials.json, sessions/, policy and remote settings, and anything a future CLI version adds.
• Why an allowlist: it's stricter than Codex's model of linking everything except a short private list. Claude adds account- and org-bound files often, and an allowlist can't leak a new one by accident.
• What it buys: the continuation key is the shared home, so a Claude→Claude account switch takes the existing restart_and_resume path. That's a native --resume with the full transcript.
• Evidence: I checked this with Claude Code 2.1.296. A session started on seat A, including a signed thinking block, resumed on seat B through a symlinked projects/. The link stayed intact and the transcript continued. I only had two seats of the same org; I didn't test across orgs. If the API ever refuses, the existing resume-failure fallback hands off.

2. Automatic failover on a usage limit

• Setting: a server setting, usageLimitFailover: { enabled, chain: [{ instanceId, model? }] }, edited in Settings next to auto-resume.
• The worker: a sibling of UsageLimitRecoveryWorker on the same 5-second scheduler. It looks for threads whose latest run failed with usage_limit in the last 24 hours, and walks the chain top-down. It skips the failed account, accounts already tried since the thread's last completed run, disabled or unavailable accounts, and accounts whose cached usageLimits show an exhausted window. Then it sends message.dispatch with the new modelSelection, usageLimitContinuationOfRunId and a providerFailover marker.
• The gate: the orchestrator gets a dedicated gate for that marker. Today's auto-resume path is unchanged.
  • It re-checks: the blocked run is still the latest, the failure is still usage_limit, the target isn't the failed account or an already-tried one, the thread is live, and no request is pending.
  • It clears any armed limitRecovery and snooze in the same commit.
  • It reuses the existing switch machinery (restart_and_resume or create_with_handoff).
• Pick-at-start: in ThreadLaunchService, a new thread whose selected account is in the chain and known to be exhausted starts on the first chain account with quota.
• Clients: the run carries providerFailover, and web and mobile show one quiet line on it: "Usage limit on Claude (work). Continued on Claude (personal)." Mobile follows the server setting but has no editor.
• No new polling: quota comes from the snapshots adapters already push. Every account is tried at most once per episode, so the loop is bounded. When nothing is eligible, behaviour is exactly today's banner.

Scope I'd keep out

• Ranking by "most remaining quota" (chain order wins).
• A per-thread opt-out.
• A mobile settings editor.
• An MCP tool for the setting.
• Moving data automatically when converting an existing account dir to a shadow (it's a typed error with the fix spelled out instead).
• Any change to the handoff budget.

Questions for maintainers

1. Would you take piece 1 (Claude shadowHomePath) as a focused config-option PR, given that it mirrors the existing Codex capability?
2. Is piece 2 a direction you'd want in core, or is it better left to forks?
3. If it is wanted, would you rather have the chain per environment (as drafted) or synced across environments?

Both pieces are implemented with tests in my fork: feat/claude-shadow-home (piece 1 only) and feat/usage-limit-failover (both, stacked). Happy to split, shrink or rework them to fit.