v0.2.1 — automatic handoff, on by default

headroom v0.2.1 — automatic handoff, on by default

The headline: headroom claude can now continue a capped conversation on a fresh
account by itself, in the same terminal, with no commands to type. This is the thing
headroom was built for — never babysit a capped session again.

Automatic handoff (on by default)

Launch your session with headroom claude as usual — that's it. When that exact session hits a subscription
cap, headroom:

1. Confirms the cap with three independent proofs — a StopFailure hook matched as
   rate_limit, a narrow session/weekly-limit message, and a fresh identity-bound
   usage read showing the account is actually capped. Missing or ambiguous evidence
   leaves your session running, untouched.
2. Derives the model you were actually on (from the transcript, so an in-session
   /model switch is respected), and picks a different account with proven headroom
   for that same model family.
3. Sends Claude one SIGTERM, waits for its own clean shutdown, copies the conversation
   into the target account (byte-for-byte; the source is never modified), and relaunches
   claude --resume … --fork-session in the same terminal.

Your session pauses for a few seconds and continues on the fresh account. What carries:
the conversation, model-family routing, and the working directory. What does not:
background tasks, live MCP connections, pending permission approvals, and permission
mode. Three automatic handoffs in any ten minutes trips a loop guard.

It is on by default, because uninterrupted continuation is the point. Every step
is fail-closed — any doubt and headroom leaves your session alone — and
routing.auto_handoff: false (or --headroom-no-auto-handoff per run) turns it off.

Also in this release

• headroom handoff is now fully transactional: a global lock, no-clobber publication,
  and crash-recoverable staging. New flags: --yes (confirmed non-interactive handoff)
  and --model FAMILY (when the session model can't be inferred). Manual handoff of an
  interrupted tool call requires --force.
• Model-family–aware routing everywhere: a session capped on one model is never handed
  to an account whose scoped weekly cap for that model is exhausted.

Platform note

The automatic-handoff path is proven end-to-end on Linux (Claude Code 2.1.x): a real
cap was detected, the session was stopped, moved, and resumed on another account with
full history intact. The one-SIGTERM stop contract has not yet been validated on
macOS; see docs/KNOWN-LIMITS.md. Usage tracking, the dashboard, manual handoff, and
rotation are unaffected and work on both platforms.