0024 — A session changes accounts by its file, not by dying

• Status: Accepted (the decision). The mechanism is in flight; this ADR is written at decision time per ADR-0004, not on merge. It corrects ccswitch/PITFALLS.md §1, which is rewritten in the same change rather than left to be rediscovered.
• Date: 2026-09-11
• Deciders: Gera — "Okay, go ahead and do B" — after asking the question that decided it: "I don't want you to give me vague answers. I want you to tell me the concreteness. Why they can do it and we can't. Or maybe they can't and we assume they can't." We assumed they can't. They can, and so can we.
• Scope. How a running session moves between accounts. It does not change which account is chosen (that is pick_best/score, and the eligibility half is its own change), and it does not change the hold rule for live subagents beyond what §4 states.

The failure

A session whose account is capped had exactly one remedy: kill the process and re-exec it on a new bearer. tmux respawn-pane -k kills the whole process group, so every subagent died with the parent — subagents are sidechains carrying the parent's sessionId with isSidechain: true, so no resume surface in Claude Code applies to them. They cannot be resumed, only re-dispatched.

We built a great deal of machinery to survive that kill: capture what the respawn is about to destroy, hand the successor a brief plus a transcript pointer, hold the switch while lanes are live. On 2026-09-11 that machinery was measured against the thing it exists for, and the result is the reason this ADR is not a refinement of it:

The hold worked and was pointless. It protected those lanes for up to 13 minutes against a wall with ~80 minutes left to run, and every lane was rate-limited out before the respawn fired. The kill found nothing to kill.

Two consequences follow, and both are defects of the capture design rather than bugs in it:

1. The capture never fires in the real case. It records lanes live at the kill, but the true sequence is wall → lanes die → respawn. Every capture on disk is from an earlier forced respawn, not from a real one.
2. respawn-losses/<sid>.json is one file per session, overwritten. So it preserved a stale set (21:03) while the set that mattered was never written, and rotation.log truncates its lane list at +1 more — one of 228a617c's four lane names now exists nowhere.

Why we believed the kill was necessary, and what is actually true

PITFALLS.md §1 recorded an "exec-pinning invariant": the credential is fixed at exec time, therefore moving accounts requires a re-exec. §1 is true of the CLAUDE_CODE_OAUTH_TOKEN environment path, which is the path this fleet uses, by three carriers: cmd_exec's env[...] = tok before execvpe, the tmux set-environment -g that herds ~50 sessions onto one bearer, and the session-scoped _tmux_set_session_token. A process holding that variable ignores the credential file entirely.

§1 is false of the file. Measured on the mini, 2026-09-12 03:40–03:46Z, on a throwaway session since cleaned up, launched with env -u CLAUDE_CODE_OAUTH_TOKEN -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN CLAUDE_CONFIG_DIR=… (env token count verified 0 on every run):

• The process re-reads the file per request. os.replace of a different account's bearer at 03:42:16.135Z moved the live session with no re-exec. PID 43302 unchanged across the swap (etime 5:52).
• The session's own /usage flipped account identity: 3% · resets 3:00am · week 66% (A, josegerag) → 1% · resets 12:20am · week 81% (B, propflow.test). 81% weekly is a value only B has.
• A live subagent crossed the swap intact: iterations 8–30 (03:42:20 → 03:44:48Z) were all post-swap — 23 separate API requests on B's bearer, cadence unchanged at ~6.7s — and it returned its result normally.
• The file is hot, not cached: pointed at a capped account, the running session reported that account's window ("resets 11:10pm") 2 seconds after the write.

A detector that failed its own control, recorded so nobody rebuilds it: per-account 5h utilization from the anthropic-ratelimit-unified-* headers cannot attribute a single turn — the API reports 2 decimals, and a large run provably served by an account left its util_5h at "0.0". Account identity is verified by the identity signature (per-account reset timestamps and weekly totals), never by watching a meter tick.

The decision

1. The credential file is the seam

A swappable session carries no bearer in its environment and reads $CLAUDE_CONFIG_DIR/.credentials.json. All three env carriers are suppressed for it. The launching shell does carry the token, so unsetting is load-bearing; inheriting is the default failure.

2. The write is atomic, and that is a correctness requirement

os.replace or equivalent. Not stylistic. With the file deliberately invalid, a subagent was dead 7.7 seconds later — Please run /login · API Error: 401 (authentication_failed), hard terminate, no retry, despite its prompt instructing it to retry and never stop — while account A's own bearer was still returning 200, which rules out a coincidental outage. The parent survived only because it happened to be parked in a shell command. A subagent has zero tolerance for a momentarily-unusable credential.

3. preflight becomes authoritative

Today it is a cache-only warning. It becomes a live gate with distinct exit codes (0 ok / 1 warn / 2 refuse), and no swap proceeds without it. The sibling branch fede/local-rotation-snapshot-2026-09-11 already has this shape and is the reference.

4. Live subagents raise the bar; they are not a blanket block

A clean swap to a healthy account demonstrably does not harm subagents (23 post-swap requests). A swap to a dead or capped one kills them in under 8 seconds. The distinction that matters is the destination's health, not the presence of lanes — which is the opposite of what the hold rule assumed.

5. Respawn is demoted, not deleted

Every session launched before this change is still env-pinned and still needs respawn, capture, handoff and re-dispatch. tests/respawn-holds-for-live-subagents.py records a real incident (five Workers killed, two of them twice) and keeps passing. Which kind a session is must be derived — read the process's actual environment — never a remembered flag or a maintained list. The standing rule: if a fact has to be remembered to stay true, it will be false.

6. ccswitch auto must stop respawning what it can swap

It runs on UserPromptSubmit. For a swappable session it swaps in place and does not respawn. For a pinned one, today's behaviour exactly.

What this does NOT fix

Changing accounts voids the prompt cache, and no mechanism avoids it. Cache is per-account. One toy swap re-created 68,045 tokens at creation price (parent 46,201 + subagent 21,844) on a five-minute session. The cost scales context × live agents, because every live sidechain pays its own full re-creation on its next request. A 15-lane session at 400K context pays a great deal to move, and a swap made to save a hot account can spend more of the destination than the turn would have. A swap therefore needs a budget check, which this change does not provide. Naming it here so it is not discovered as a surprise.

Also unfixed, and deliberately separate: walled_heal refusing a usable seat (it demands an account clear on all axes while the switch path correctly accepts one whose needed axis is free). That is why both sessions above were freed not by the healer but by coincidence — an unrelated mail wake at 22:52:20 and a post-compact nudge at 22:54:55, each injecting a prompt that fired the hook. Its own change; not this one.

Rejected alternative: the proxy

ANTHROPIC_BASE_URL pointed at a local relay that strips the client's Authorization and injects the chosen bearer. It works — proven the same night: swap at 03:21:54Z verified by account email, 11 requests 100% account A before, 21 requests 100% account B after, bearer fingerprint and reset epochs flipping at the boundary and never mixing; a live subagent's heartbeats crossed it (1–5 A, 6–14 B) and returned; streaming survived unbuffered; and the negative control proved stripping, since two probes carrying a bogus client bearer both returned 200.

Rejected anyway, because it buys nothing the file does not and costs:

• a relay process every session depends on — a single point of failure where today there is none;
• the bearer in a relay's memory as plaintext Authorization, a new place for a credential to live;
• no ability to choose a destination (/_ccproxy/swap takes next-best);
• one unexplained 429 we never accounted for.

The file path needs no new process, no traffic interception, and no new credential location. It is also, concretely, what the sibling snapshot branch already does — the answer to "why can they and we can't" is that they were never env-pinned.

Consequences

• Sessions become movable while working, which is the point: the wall stops costing every lane a session is running.
• Two capture defects (§1, §2 of The failure) dissolve rather than needing fixes — there is nothing to capture if nothing is killed.
• Each swappable session needs its own config dir. A bare one is fully functional (.credentials.json plus three keys in .claude.json: hasCompletedOnboarding, theme, and projects[<realpath of cwd>].hasTrustDialogAccepted — the realpath, not the symlinked path, which cost the experiment a launch). No settings.json, hooks, plugins or symlinks into ~/.claude were required.
• The fleet keeps two kinds of session, pinned and swappable, until the pinned ones age out. Two kinds is a cost; pretending there is one is worse.