tokenmaxxing 0.19.0 → 0.21.0

package/DESIGN.md

@@ -1,10 +1,10 @@
 # tokenmaxxing - design
 
-Automatic Claude Code account switching. You run `claude` exactly as always; when the active account crosses its swap threshold (**95%** of the 5h session window, **98%** of a weekly window), tokenmaxxing swaps the credential to a fresh account at a safe turn boundary and **your running session adopts it in place - no restart**. Works across many concurrent sessions at once; a fully depleted pool pauses with a countdown and auto-resumes at the soonest reset.
+Automatic Claude Code account switching. You run `claude` exactly as always; when the active account crosses its swap threshold (**95%** of the 5h session window, **98%** of a weekly window), tokenmaxxing swaps the credential to a fresh account at a safe turn boundary and **your running session adopts it in place - no restart**. Works across many concurrent sessions at once; a fully depleted pool pauses with a countdown and auto-resumes at the soonest reset when it lands within `policy.maxWaitMs` (default 1h; further out, the session stays put rather than parking for hours).
 
-> Scope: **Claude Code only, macOS first.** Codex and other CLIs deferred (see `.memory/cc-codex-auth-mechanics.md`).
+> Scope: **Claude Code first (macOS + Linux, the latter since 2026-07-09).** Codex support landed in 0.13.0 (2026-07-16) with its own parallel state, decision engine, and supervisor; its verified internals live in AGENTS.md's Codex sections.
 >
-> Status: **implemented** (v0.1.0, 2026-07-09). TypeScript on Bun → single binary; Zod validates every external-boundary payload, JSON config, es-toolkit for utilities, `flock(2)` via `bun:ffi`. All load-bearing external facts were adversarially verified against the `2.1.204` binary + docs (OAuth token endpoint is `platform.claude.com/v1/oauth/token`, client_id `9d1c250a-...`, JSON body). What the acceptance gate actually shows is in §9.
+> Status: **implemented** (v0.1.0, 2026-07-09). TypeScript on Bun, shipped as SOURCE with a bun-shebang bin (the compiled-binary distribution was deleted in 0.2.1); Zod validates every external-boundary payload, JSON config, es-toolkit for utilities, `flock(2)` via `bun:ffi`. All load-bearing external facts were adversarially verified against the `2.1.204` binary + docs (OAuth token endpoint is `platform.claude.com/v1/oauth/token`, client_id `9d1c250a-...`, JSON body). What the acceptance gate actually shows is in §9.
 
 ---
 
@@ -17,37 +17,39 @@ So the supervisor's job is narrow: on a depleted pool it **replaces the process
 A hook can't do the pause-and-relaunch - when `claude` exits, the shell owns the terminal. So tokenmaxxing installs a **supervisor** (aliased to `claude`) that owns the process lifecycle:
 
 ```
-supervisor (you type `claude`)  →  real claude (in a PTY)  →  Stop hook
+supervisor (you type `claude`)  →  real claude (inherited stdio)  →  Stop hook
         ▲_______________ relaunch --resume <sid> ______________|
 ```
 
-It is a process/PTY manager only - spawn, forward the terminal, wait, restore terminal, relaunch. It never proxies API traffic or handles tokens. Everything else about `claude` is unchanged.
+It is a process manager only - spawn with inherited stdio plus saved `stty -g` termios (not a PTY copy), wait, restore the terminal, relaunch. It never proxies API traffic or handles tokens. Everything else about `claude` is unchanged.
 
 ---
 
 ## 2. What tokenmaxxing installs
 
 - A `claude` **supervisor** on your PATH ahead of the real binary (`~/.config/tokenmaxxing/bin/claude`), or a shell function - you invoke it identically.
-- Four `~/.claude/settings.json` entries (merged, preserving anything you already have): a transparent `statusLine` shim, a `subagentStatusLine` shim (per-subagent rows in the agents panel), a `Stop` hook, a `SessionStart` hook.
+- Four `~/.claude/settings.json` entries (merged - other settings keys are preserved, but the `statusLine` slot is taken over): the tokenmaxxing `statusLine` renderer (native since 2026-07-11; it also tees usage), a `subagentStatusLine` (per-subagent rows in the agents panel), a `Stop` hook, a `SessionStart` hook.
 - **`~/.config/tokenmaxxing/`** - the single home for config and state:
-  - `config.json` - threshold, account order/policy.
-  - `accounts.json` - non-secret index `{email, organizationUuid, accountUuid, lastUsage, resetsAt, needs_reauth}`.
+  - `config.json` - SPARSE overrides only (thresholds.session/weekly, claudeBin/codexBin pins, policy.*); defaults merge at read time, `xx config` edits it.
+  - `accounts.json` - non-secret index `{email, organizationUuid, accountUuid, label, lastUsage, lastPerModel, needsReauth, ...}` (window resets live inside lastUsage).
   - `usage.json` - live usage, written by the statusLine shim.
   - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal, depleted-pool waits only).
   - `bin/claude` - the supervisor.
 - Per-account **credentials** follow the platform's Claude Code store: macOS = login-keychain items `tokenmaxxing-cred-<accountUuid[:8]>` (never plaintext on disk); Linux = 0600 files `creds/tokenmaxxing-cred-<accountUuid[:8]>.json` (the same plaintext model claude itself uses - its Linux build has no keyring path at all, binary-verified 2.1.205). One `credstore` facade dispatches on a `{kind: keychain|file}` target; call sites never branch on platform.
 
-No background daemon - it's event-driven (statusline pushes usage; hooks + supervisor react). The `claude` binary and `~/.claude` layout are untouched.
+- A periodic check job (`com.tokenmaxxing.check` launchd agent on macOS, `tokenmaxxing-check.timer` systemd user timer on Linux) running `tokenmaxxing check` every 180s: hooks alone miss long agentic turns, so the timer is the backstop that keeps switching engaged mid-turn.
+
+The switching path runs no long-lived daemon - the statusline pushes usage and hooks + supervisor react, with the periodic check job above as its only recurring process (`xx serve`, the opt-in Slack bridge, is a separate long-lived daemon). The `claude` binary and `~/.claude` layout are untouched.
 
 ---
 
 ## 3. How a switch happens
 
 ### 3.1 Usage feed (free, push-based)
-The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}`, after every turn, 300ms debounce, zero cost). tokenmaxxing's statusLine shim tees that to `usage.json` (write-on-change, O(ms)) and passes your real statusline through unchanged. Cold-start fallback if `usage.json` is absent: `TOKENMAXXING_PROBE=1 claude -p '/usage'`, with `[ -n "$TOKENMAXXING_PROBE" ] && exit 0` as the hook's first line to stop the nested process recursing (hooks fire in `-p` too). The probe scrubs every ambient credential override claude reads before the keychain (`CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_SECURESTORAGE_CONFIG_DIR`, etc.) so it can only meter the credential in the keychain item, and retries the transient empty-footer case (claude prints local stats with no percentages when its own usage fetch throttles).
+The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}`, after every turn, 300ms debounce, zero cost). tokenmaxxing's statusLine tees that to `usage.json` (write-on-change, O(ms)) and renders its own native line (it replaced the earlier pass-through delegation on 2026-07-11: install takes the statusLine slot outright, so a pre-existing custom statusline command is overwritten). Cold-start fallback if `usage.json` is absent: `TOKENMAXXING_PROBE=1 claude -p '/usage'`, with `[ -n "$TOKENMAXXING_PROBE" ] && exit 0` as the hook's first line to stop the nested process recursing (hooks fire in `-p` too). The probe scrubs every ambient credential override claude reads before the keychain (`CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_SECURESTORAGE_CONFIG_DIR`, etc.) so it can only meter the credential in the keychain item, and retries the transient empty-footer case (claude prints local stats with no percentages when its own usage fetch throttles).
 
 ### 3.2 Detect + swap + signal (Stop hook, per turn)
-1. Read `usage.json`; `exit 0` fast if every window is under its threshold (metered per `organizationUuid`).
+1. Read `usage.json`; `exit 0` fast below the engagement floor (`policy.greedySessionFloor`, default 50% of the 5h window) unless a screening bar is already crossed. Engaged-but-under-every-bar runs the GREEDY convergence: stay when the current account wins or ties, else swap onto the strictly better account. A crossed bar forces the hard path (metered per `organizationUuid`).
 2. Else take a `flock` on `~/.config/tokenmaxxing/lock`, re-check under it (parallel sessions race - first winner already swapped), pick the best parked account (not rate-limited, furthest behind its own weekly pace first: highest remaining% / time-to-weekly-reset, since unused allowance is forfeited at the fixed per-account reset; tiebreak soonest expiry then lowest 7-day usage), and **swap the credential** (§3.4).
 3. Done - the running session adopts the new credential on its own within a request or two. Only when the pool is depleted (the decision returned a `waitUntil`: pre-parked on the soonest-recovering account, or staying on the current one when it recovers first) does the hook write `respawn/<session_id>` (atomic temp+rename).
 
@@ -59,7 +61,7 @@ The supervisor sees `respawn/<sid>`, SIGTERMs its child at the already-committed
 2. **Refresh B** - OAuth refresh-grant with B's parked refresh token → fresh access token; persist the rotated refresh token. On `invalid_grant`, mark B `needs_reauth`, notify, try the next account.
 3. **Install B** - `security add-generic-password -U ... 'Claude Code-credentials' ...` with B's fresh (non-expired) `claudeAiOauth` JSON.
 4. **Swap identity + mark B active** - atomically rewrite only the `oauthAccount` object in `~/.claude.json` (temp+rename) to B's, and write `activeAccountUuid = B` in the SAME critical section, so a crash can't leave the installed credential and the active label pointing at different accounts.
-5. Do steps 1, 3, 4 inside Claude's own `~/.claude.lock` so the writes can't collide with a token refresh.
+5. Do steps 1, 3, 4 inside Claude's own refresh locks - the primary `<credDir>/.oauth_refresh.lock` plus the legacy sibling `<realpath(credDir)>.lock` (`~/.claude.lock` by default), both mkdir-based proper-lockfile locks, binary-verified against 2.1.214 - so the writes can't collide with a token refresh. Contention fails the swap fast (claude itself gives up with `lock_timeout` rather than refreshing unlocked); the next check retries.
 
 ### 3.5 Multiple concurrent sessions
 Each terminal ran the supervisor, so each has its own child `claude` and its own `--session-id`. When the shared account hits a threshold, the first Stop hook to win the `flock` performs the one swap; every running session then adopts the new credential in place - no restarts. (They share one credential, so they always move together - consistent with "one current account, many windows.") Only a depleted pool fans out: each supervised session's Stop hook writes its own `respawn/<sid>` marker, and each supervisor independently pauses and later relaunches `claude --resume <its-own-sid>`.
@@ -68,7 +70,7 @@ Each terminal ran the supervisor, so each has its own child `claude` and its own
 
 ## 4. Onboarding (no `adopt`)
 
-- **`tokenmaxxing init` imports the account you're already on - automatically, no prompts, no re-login.** It reads the live `Claude Code-credentials` keychain blob plus the `oauthAccount` object in `~/.claude.json` (email, `organizationUuid`, `accountUuid`, plan tier) and writes them as **account #1** into tokenmaxxing's store (`tokenmaxxing-cred-<accountUuid[:8]>` + an `accounts.json` index entry). Nothing about your current session changes - that account stays active; it's now just also a registered pool member. After this one command you already have a working (single-account) pool. `init` also installs the supervisor + the three settings entries.
+- **`tokenmaxxing init` imports the account you're already on - automatically, no prompts, no re-login.** It reads the live `Claude Code-credentials` keychain blob plus the `oauthAccount` object in `~/.claude.json` (email, `organizationUuid`, `accountUuid`, plan tier) and writes them as **account #1** into tokenmaxxing's store (`tokenmaxxing-cred-<accountUuid[:8]>` + an `accounts.json` index entry). Nothing about your current session changes - that account stays active; it's now just also a registered pool member. After this one command you already have a working (single-account) pool. `init` also installs the supervisor + the four settings entries.
   - If the current auth is API-key mode (`ANTHROPIC_API_KEY`/`apiKeyHelper`) rather than a subscription `/login`, there's no quota-poolable subscription credential to import - `init` says so and points you to `/login` first (per-token API billing isn't what tokenmaxxing pools).
 - **`tokenmaxxing add`** - registers *additional* accounts: logs one in via a throwaway `CLAUDE_CONFIG_DIR=~/.config/tokenmaxxing/onboard` (your primary login untouched), harvests it into the store, deletes the temp dir + its namespaced item. This is the **only** time `CLAUDE_CONFIG_DIR` is ever used.
 - **`tokenmaxxing auth [sel | --all]`** - reauthenticates an *existing* pool member whose refresh token died (a needs-reauth account can never heal through a swap: the dead token is exactly what a swap would need). Same isolated-login harvest as `add`, but it states which email to sign in with and **requires the login to land on the target account** (harvested `accountUuid` must match, else nothing changes) - the credential write and the needs-reauth clear happen in one flock critical section so a concurrent swap's harvest cannot clobber the fresh backup. Bare `auth` lists the pool with emails and asks which; `--all` walks every flagged account one by one.
@@ -77,7 +79,7 @@ Each terminal ran the supervisor, so each has its own child `claude` and its own
 ---
 
 ## 5. Rotation policy
-The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from there it greedily converges on the usable account furthest behind its weekly pace, staying put whenever the current account wins or ties. The hard bars - `five_hour >= 95%` OR `seven_day >= 98%`, per org - always force a switch and also screen candidates. "Exhausted" is a **timestamped state** (`resets_at`), not a flag - an account is a candidate again after it resets. Optional projected threshold (`bar - EMA(per-turn Δ%)`) so a single large turn can't blow past 100% before the next Stop hook.
+The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from there it greedily converges on the usable account furthest behind its weekly pace, staying put whenever the current account wins or ties. The hard bars - `five_hour >= 95%` OR `seven_day >= 98%`, per org - always force a switch and also screen candidates. "Exhausted" is a **timestamped state** (`resets_at`), not a flag - an account is a candidate again after it resets. Optional projected threshold (`bar - policy.projectionMargin`, a fixed configured margin) so a single large turn is less likely to blow past 100% before the next Stop hook.
 
 **Model-aware trigger.** Claude subscriptions also enforce **per-model weekly caps** - currently only for Sonnet and Fable (there is no Opus-only quota), and Fable's tighter limit binds *before* the aggregate (e.g. 80% week-Fable at only 50% week-all-models). This cap isn't in statusLine stdin, so when the active model is in `policy.switchModels` we read it from `claude -p '/usage'` (free, 0 tokens, TTL-cached) and add `week(<activeModel>) >= threshold` to the trigger. A Fable session switches on the Fable cap; a Sonnet session rides the aggregate.
 
@@ -87,14 +89,23 @@ The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from the
 
 A local Socket Mode daemon (no public URL) that turns Slack threads into Claude Code sessions on the pooled accounts. Stack (user decision 2026-07-18): Vercel's Chat SDK (`chat` + `@chat-adapter/slack`) for the Slack side; the Claude Agent SDK driven through `src/sdk.ts`'s pooled surface for the claude side - `xx serve` is that surface's first in-repo consumer. EVE (Vercel's agent framework) was researched and explicitly dropped: it owns its own model loop via AI Gateway, so it would replace Claude Code rather than drive it.
 
-- **Config**: `slack.json` (0600 - it holds the xoxb-/xapp- tokens) with per-channel links `{channel, repo, worktree, permissionMode, model?}`. `serve setup` prints the app manifest (minimal scopes: app_mentions:read, channels:history, groups:history, chat:write, files:write, users:read + socket mode) and prompts for the tokens; `serve link <channel-id> <repo>` manages links (channel IDs only - names drift, ids don't).
-- **Thread = session**: a bot mention in a linked channel subscribes the thread, creates `slack-worktrees/<threadKey>` (branch `tm-slack-<threadKey>` cut from the repo's HEAD; `--no-worktree` links run in the repo itself), and records `{threadId, cwd, sessionId}` under `slack-threads/`. Resume is cwd-keyed in claude, so the cwd stays byte-stable for the thread's life; worktrees are never auto-deleted (they hold the thread's work).
+- **Config**: `slack.json` (0600 - it holds the xoxb-/xapp- tokens) with per-channel links `{channel, repo, permissionMode, model?}`. `serve setup` prints the app manifest (bot scopes: app_mentions:read, assistant:write, channels:history, groups:history, chat:write, files:write, im:history, users:read; agent_view enabled; events incl. app_mention, message.channels/groups/im, app_home_opened, app_context_changed; socket mode) and prompts for the tokens; `serve link <channel-id> <repo>` manages links (channel IDs only - names drift, ids don't).
+- **Thread = session**: a bot mention in a linked channel subscribes the thread and opens the session in the linked repo checkout (normal mode, user decision 2026-07-18 superseding the same-day worktree-per-thread default; a later same-day decision: the agent cuts its own worktree FIRST for any mutating task - read-only turns stay parallel in the shared checkout - taught by the serve-session skill, since the recorded cwd can never move), and records `{threadId, cwd, sessionId}` under `slack-threads/`. Resume is cwd-keyed in claude, so the cwd stays byte-stable for the thread's life; records from the worktree era pin their old `slack-worktrees/<threadKey>` cwd and keep working (those worktrees are never auto-deleted - they hold the thread's work).
+- **Thread close-out (finish_thread)**: when the user says the work is finished, the model calls the in-process MCP tool `finish_thread` (a per-turn `createSdkMcpServer` in relayThread, `alwaysLoad: true`, granted via `allowedTools` since nobody can answer a permission prompt over Slack). The handler runs in the daemon but only flags the turn outcome; after the turn ends (claude subprocess gone, segments posted) serve.ts runs `cleanupThread`: delete the `slack-threads/` record, `thread.unsubscribe()`, and post one confirmation line. Threads run in the shared repo checkout, so there is nothing on disk to collect and the checkout is never touched; a fresh mention after close-out starts a new session.
 - **Turn = spawn**: each thread message runs ONE `query()` with `resume: sessionId` (never a persistent streaming query - the SDK subprocess reads credentials at spawn, so per-turn spawns are what let `ensureBestAccount()` land each turn on the freshest account, and the daemon can restart without losing threads). `stopHookCheck` rides along as the SDK Stop hook. Streamed `text_delta`s feed `thread.post(AsyncIterable)` (the adapter debounces edits); tool-only turns post the final result text.
-- **Safety posture**: per-link `permissionMode`, default `acceptEdits`; `--yolo` (alias `--dangerous`) opts a link into `bypassPermissions`, and relayThread pairs it with the SDK's mandatory `allowDangerouslySkipPermissions: true` opt-in. `AskUserQuestion` is disallowed (unanswerable over Slack; the model asks in prose instead). Turn failures post a trimmed message-only diagnostic (never a raw error body).
+- **Safety posture**: per-link `permissionMode`, default `acceptEdits`; `--yolo` (alias `--dangerous`) opts a link into `bypassPermissions`, and relayThread pairs it with the SDK's mandatory `allowDangerouslySkipPermissions: true` opt-in. `AskUserQuestion` is disallowed (unanswerable over Slack; the model asks in prose instead). Turn failures post a trimmed message-only diagnostic (never a raw error body). Outsiders must not drive sessions (harvested from Slaude at its 2026-07-18 shutdown): `isOutsideAuthor` fail-closed rejects any message whose team-origin fields disagree with the home workspace's `workspaceTeamId` (captured via auth.test at setup and re-captured at every daemon start, so the reference can never go stale against a rotated token), so Slack Connect externals and cross-workspace guests are silently ignored and can never open a session.
+- **Serve skills** (`src/serve-plugin/`, ships in the package via `files: ["src"]`): a Claude Code plugin loaded per turn (`plugins: [{type: "local", path}]`; discovered skills are enabled by default, so no `skills` option). `tokenmaxxing:ask-the-user` teaches the decision protocol - when input is needed, tag the requester with the raw Slack mention token `<@U...>`, ask compactly, END the turn (the thread reply is the next turn); `tokenmaxxing:serve-session` documents how the session runs (shared repo checkout, resume across turns, worktree-by-default for mutating tasks, handoff). The one dynamic fact skills cannot carry - who asked - rides in per turn via a `UserPromptSubmit` hook whose `additionalContext` ("Slack relay context: ...", built by `serveTurnContext`) names the triggering message author's mention token. The mention survives the pipeline because streamed `markdown_text` deltas pass verbatim and the post-and-edit fallback's `finalize` only linkifies bare `@U...`, never escaping an already-formed `<@U...>`. Skills are independent of the system prompt choice (probe-verified 2026-07-18 under the custom-string `SLACK_SYSTEM_PROMPT`: the init message lists the plugin + both skills + the Skill tool; the skill listing arrives as a conversation system-reminder, and CLAUDE.md loads via settingSources).
 - **Socket lifecycle**: `bot.initialize()` starts the persistent auto-reconnecting SocketModeClient; the daemon then just stays alive. The leased `startSocketModeListener` API must never be looped: it returns instantly without `waitUntil` and the loop starves the event loop (live incident 2026-07-18 - connected but silent).
-- **Id mapping**: Chat SDK ids are adapter-prefixed (`thread.channelId` = `slack:C0123`, `thread.id` = `slack:C0123:<threadTs>`) while links store bare Slack ids - lookups strip the prefix via `bareChannelId`. Subscriptions live in the daemon's memory state, so every mention re-subscribes its thread (a restarted daemon revives an old thread on the next mention); queue-skipped messages (`context.skipped`) fold into the next prompt, with the queue-entry TTL raised to 900s; unlinked-channel traffic logs `serve.unlinked_channel` and stays silent in Slack.
+- **Id mapping**: Chat SDK ids are adapter-prefixed (`thread.channelId` = `slack:C0123`, `thread.id` = `slack:C0123:<threadTs>`) while links store bare Slack ids - lookups strip the prefix via `bareChannelId`. Subscriptions live in the daemon's memory state, so every mention re-subscribes its thread; queue-skipped messages (`context.skipped`) fold into the next prompt, with the queue-entry TTL raised to 1h (expiry is silent - no app callback in chat 4.34.0 - so it must outlast a depleted-pool park plus a long turn); per-thread turn serialization is owned by the daemon itself (a promise chain per thread id), because the SDK's queue dispatch lock has a 30s TTL extended only between dispatches and every claude turn outlives it; unlinked-channel traffic logs `serve.unlinked_channel` and stays silent in Slack.
+- **Restart resilience** (0.19.0, from the 2026-07-18 dead-thread incident: a deploy restart cut a turn mid-answer and left the thread deaf to follow-ups): startup re-subscribes every `slack-threads/` record straight on the state adapter (`state.subscribe(threadId)`; message routing checks `stateAdapter.isSubscribed`, verified in chat 4.34.0), so open threads survive restarts without needing a fresh mention. SIGTERM/SIGINT drains instead of dying: new turns are dropped loudly (`serve.drain_dropped` plus a tracked in-thread notice - a log-only drop reads as the bot thinking), tracked in-flight turns get up to 300s to finish (a re-snapshotting wait, so late-added notices still flush), then `Chat.shutdown()`; a second signal forces exit; the drain also aborts any depleted-pool park so a countdown never delays a restart. The claude child spawns detached in its own process group (`detachedClaudeSpawn` via the SDK's `spawnClaudeCodeProcess` hook), because a terminal Ctrl-C signals the whole foreground group and a non-detached child died with the daemon before the drain could save the turn; the signal handlers register before `bot.initialize()` so no turn can start while the process still has default signal disposition, and a rejecting `Chat.shutdown()` is caught so the drain always reaches its exit. When a `thread.post` rejects mid-turn (e.g. Slack finalizes an idle stream: `message_not_in_streaming_state`), relayThread drops the dead segment so the rest of the turn opens fresh messages instead of vanishing.
+- **Interrupted-turn recovery** (from the second 2026-07-18 restart incident: a redeploy killed a ship turn 8 minutes in with zero notice - drain cannot save a long turn, and a group-wide kill can take the claude child even detached): the thread record persists the claude session id the moment the init message assigns it, and every turn is wrapped in a durable `activeTurn` marker (original prompt, start time, resume count) written before the spawn and cleared when the turn returns - except that a turn failing DURING a drain keeps its marker, since that failure is presumed to be the shutdown signal killing the child. On startup, a surviving marker means a restart killed that turn: the daemon posts a notice into the thread (the chat-sdk's documented proactive handle, rebuilt with the thread's newest human message as streaming recipient context so the resumed turn keeps its native task cards, that message's author becoming the turn's requester) and auto-resumes the work - resuming the recorded session with a continuation prompt, or replaying the original prompt fresh when the kill landed before the session opened; resumed turns settle like inbound ones (outcome log + finish_thread GC). Retries cap at 3 (each spends real quota) with a loud give-up notice posted before its marker clears; a per-thread turn lock keeps a startup resume from ever racing an inbound message turn in the same cwd, every recovery branch recomputes its decision from a fresh record reload under that lock (so a resume superseded by a faster inbound turn no-ops instead of double-running), and a blocking singleton flock makes a new daemon generation wait for the previous one - drain included - to fully exit before touching any thread record. Uncatchable deaths cannot leak a working child either: SIGHUP drains like SIGTERM (its default disposition skips the exit hook that kills the detached group), and the marker records the child's group pid plus its C-locale ps start-time token at spawn, so recovery kills only an exactly-identified SIGKILL-orphaned claude (never a recycled pid) before resuming its turn.
+- **Depleted-pool recovery** (harvested from Slaude, reshaped around the pool): relayThread consumes the spawn-boundary switch decision instead of discarding it - a depleted pool with a known recovery inside the message's one 14min parking deadline (shared across chained parks, so the thread's queue slot is never held longer in total) posts a park notice and retries at the reset; unknown or past-deadline recovery posts an honest drop notice (dropping beats a false will-resume promise). A mid-turn limit - detected ONLY on errored results, since `is_error` can ride subtype `"success"` (`Claude AI usage limit reached|<epoch>`) and a successful answer discussing limits must never be re-run - is persisted into usage.json first (`recordObservedLimit`: the serve process has no statusLine tee, and the snapshot TTL would otherwise feed the retry the stale pre-limit state), then retried silently after a short beat, so a pool swap makes the hiccup invisible. Bounded recoveries; every drop the relay performs is announced in-thread.
+- **Slack-native output hygiene**: relayed turns run a small standalone `systemPrompt` telling the model replies render as Slack markdown, never HTML (a live turn once answered with a literal `<br>`; the SDK's default system prompt is minimal since 0.1.0, so the string replaces nothing), and whitespace-only text deltas do not count as reply text for segment breaking (no stranded near-blank messages).
+- **Slash commands** (2026-07-18): a mention-stripped thread message that starts with `/` runs as a claude slash command - the SDK delivers a string prompt as one stream-json user message and the CLI routes a leading-slash prompt through its command table, on fresh and resumed sessions alike (live-verified with free `/usage` and `/context` reads). Local command output (`num_turns` 0) arrives as a non-streamed assistant message plus `result.result`, which relayThread's no-text fallback posts; `slackstream` also maps the documented `system/local_command_output` wire subtype in case a claude update flips the emitter. `/goal` (built-in since 2.1.139) works headless and its active goal is restored on resume, so it survives the per-message resume pattern. Slack gotcha: the composer eats ANY message whose first character is `/` client-side (channels and thread replies; registered app commands cannot even dispatch from threads), so the supported forms are `@bot /usage` (mention-first) and ` /usage` (leading space, Slack's own documented workaround) - both normalize to a position-0 command via `stripLeadingMention`.
 - **Agent representation** (`src/lib/slackstream.ts`): turns stream natively (`chat.startStream`, which works in channel threads regardless of the assistant:write scope): thinking and tool calls as task cards ("Thinking"/tool name/"Turn", input summary + truncated output), reply text as native markdown with rendered code fences, and a segment break whenever a tool starts after streamed text, so one turn posts as separate ordered Slack messages around its tool runs.
-- **Live-verified end-to-end** (2026-07-18, #tokenmaxxing-dogfooding): mention opens worktree + session, replies stream, thread follow-ups resume with context, cards + fenced code render, segmentation and queue folding behave. Plus the hermetic suite: schemas/links, worktree idempotency, stream mapping, fail-fast paths.
+- **Todo checklist card**: TodoWrite is bookkeeping, not a real tool run, so it never opens a generic card and never breaks a segment. Instead each stream gets one stable-id "Todos" card (id `todos`, subagents `todos-<parent_tool_use_id>`) that updates in place on every TodoWrite: `✅ content` for completed, `🔄 activeForm` for the in-progress item (live narration), `⬜ content` for pending (the Chat SDK Plan object's own iconography); card status goes complete only when every item is completed. The "Todos have been modified successfully" tool_result is suppressed, but a FAILED TodoWrite flips the card to error (the optimistic checklist must not claim a state that never took effect). Card ids do not carry across segments, so a post-break TodoWrite starts a fresh card in the new message: accepted, the latest state is always in the newest message. claude >= 2.1.142 defaults to the structured Task tools and never emits TodoWrite, so relayThread sets `CLAUDE_CODE_ENABLE_TASKS: "0"` in the spawn env (the documented opt-out; without it the checklist card is inert).
+- **Terminal echo** (2026-07-18): the daemon registers a `log()` echo (`setLogEcho` in log.ts, off by default so hooks and the statusline keep their stdout protocols clean), so every event while it runs - serve.* plus the in-process swap/decision events from `ensureBestAccount()`/`stopHookCheck` - also prints one colored line in the foreground terminal (`formatLogLine`: dim HH:MM:SS, event painted red/yellow/cyan by structural endsWith severity, redacted fields). `serve.turn_done`/`serve.turn_failed` (with seconds) close every relayed turn, so a foreground `xx serve` is observable without tailing `tokenmaxxing.log`.
+- **Live-verified end-to-end** (2026-07-18, #tokenmaxxing-dogfooding): mention opens a session (worktree-per-thread at the time), replies stream, thread follow-ups resume with context, cards + fenced code render, segmentation and queue folding behave. Plus the hermetic suite: schemas/links, stream mapping, fail-fast paths.
 
 ---
 
@@ -105,9 +116,9 @@ A local Socket Mode daemon (no public URL) that turns Slack threads into Claude
 - **Single-turn overshoot.** If one turn jumps from under the threshold straight past the wall, that turn can end rate-limited before the Stop hook swaps; the swap then still recovers the session (its next turn adopts the fresh account). Projected threshold reduces this.
 - **Shared blast radius.** All default-profile sessions share one keychain item, so a swap moves them all (each adopts in place). The `flock` + re-check is mandatory or racing hooks burn two accounts at once.
 - **Refresh-token rotation / parked-token rot.** Step 1 re-harvest is mandatory; a parked refresh token can be invalidated by logging in elsewhere → picker must catch `invalid_grant`, mark `needs_reauth`, fall through.
-- **statusLine fragility.** The shim is the most visible surface - a bug flickers or breaks your real status line. Keep it O(ms), write-on-change.
+- **statusLine fragility.** The native statusline is the most visible surface - a bug flickers or blanks the line for every session (and install takes the slot outright, replacing any custom statusline you had). Keep it O(ms), write-on-change.
 - **Keychain blob size & ps-safety.** The live `Claude Code-credentials` item also holds per-MCP-server OAuth state, so it can exceed `security -i`'s ~4KB interactive line buffer (verified on a real machine - a 4.3KB blob truncated). tokenmaxxing therefore stores parked backups as **`claudeAiOauth`-only** (small → always the ps-safe stdin write) and, on a swap, **merges** the fresh `claudeAiOauth` into the *current* live blob so MCP tokens survive the switch - using the argv write path (secret briefly visible in `ps` on your own machine) only for that one oversized live write.
-- **settings.json is user-owned.** Install by merge; ship `tokenmaxxing doctor` to verify the supervisor + 3 entries survive a `/config` edit or update.
+- **settings.json is user-owned.** Install by merge; ship `tokenmaxxing doctor` to verify the supervisor + 4 entries survive a `/config` edit or update.
 
 ---
 
@@ -120,14 +131,14 @@ A local Socket Mode daemon (no public URL) that turns Slack threads into Claude
 
 **Later:** tool-agnostic picker.
 
-**Shipped since (0.13.0):** Codex as a second pool, parallel state (`codex-accounts.json`, `codex-creds/`, own flock), same pace-pressure policy. Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (harvest-by-true-owner, persist every rotation), and codex's new Stop-hook system drives the auto-swap through a codex supervisor shim that respawns `codex resume <session-id>` (hooks must be trusted once via `/hooks`).
+**Shipped since (0.13.0):** Codex as a second pool, parallel state (`codex-accounts.json`, `codex-creds/`, own flock), same pace-pressure policy. Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (harvest-by-true-owner, persist every rotation), and codex's new Stop-hook system drives the auto-swap through a codex supervisor shim that respawns `codex resume <session-id>` (hooks must be trusted once via `/hooks`). Sibling sessions left on ANY non-live account are reconciled cross-session (owner decisions 2026-07-20; a non-live session cannot refresh cross-account and would wedge at token expiry, healthy or not): the deciding actor drops a reconcile marker addressed to the sibling's supervisor, and the sibling's own Stop hook promotes it into a respawn onto the live account at its next turn boundary - the only safe respawn point - while a blocked live seat never receives a signal.
 
 **Non-goals:** an API/MITM proxy; reimplementing OAuth beyond the single refresh-grant call in the swap.
 
 ---
 
 ## 8. Stack
-TypeScript on Bun, shipped as source: one multi-call entry (`src/main.ts`, `#!/usr/bin/env bun`) serves the CLI, the `claude` supervisor, the statusLine shim, and the hooks; `init` installs a 2-line shim that `exec`s bun on the installed package's entry (the Stop path runs every turn; bun's start-up stays low-millisecond). Published to npm as `tokenmaxxing` (source, platform-independent - a compiled binary was tried and shipped one architecture's Mach-O to every platform). Shipping is PR-based since 2026-07-18: work reaches main only through a pull request (branch, PR, CI green, review handled, merge), and a release is a PR-landed version bump followed by `gh release create` (details in AGENTS.md "Release and CI"). The supervisor needs a real PTY layer (spawn claude on a pty, forward resize/signals, restore mode between runs).
+TypeScript on Bun, shipped as source: one multi-call entry (`src/main.ts`, `#!/usr/bin/env bun`) serves the CLI, the `claude` supervisor, the statusLine shim, and the hooks; `init` installs a 2-line shim that `exec`s bun on the installed package's entry (the Stop path runs every turn; bun's start-up stays low-millisecond). Published to npm as `tokenmaxxing` (source, platform-independent - a compiled binary was tried and shipped one architecture's Mach-O to every platform). Shipping is PR-based since 2026-07-18: work reaches main only through a pull request (branch, PR, CI green, a 10-minute review wait, every review handled, merge, teardown), and a release is a PR-landed version bump followed by `gh release create` (details in AGENTS.md "Release and CI"). The supervisor spawns claude with inherited stdio and restores saved `stty -g` termios between runs - no PTY layer; resize and signals flow through the shared foreground process group.
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # tokenmaxxing
 
-**Automatic Claude Code account switching.** Run `claude` exactly as you always do; when the active account nears its usage limit, tokenmaxxing swaps the credential to a fresher account at a safe turn boundary and your session keeps running on it - no restart, same conversation. Works across many concurrent sessions. Only when the whole pool is at its limit does anything visible happen: a countdown that auto-resumes at the soonest reset.
+**Automatic Claude Code account switching.** Run `claude` exactly as you always do; when the active account nears its usage limit, tokenmaxxing swaps the credential to a fresher account at a safe turn boundary and your session keeps running on it - no restart, same conversation. Works across many concurrent sessions. Only when the whole pool is at its limit does anything visible happen: a countdown that auto-resumes at the soonest reset, when that reset falls within `policy.maxWaitMs` (default 1h - a longer wait stays put rather than parking your terminal for hours).
 
 > **Scope:** Claude Code only, macOS and Linux. It pools **subscription** accounts (Pro/Max), not API keys.
 
@@ -23,7 +23,7 @@ bun add -g tokenmaxxing
 tokenmaxxing init
 ```
 
-`init` imports the account you're already on, installs the `claude` supervisor + three `settings.json` entries (the tokenmaxxing statusLine, a Stop hook, a SessionStart hook), and adds the supervisor's bin dir to PATH in your shell rc (idempotent; it must sit ahead of the real `claude` to intercept it). Restart your shell, then add more accounts and go:
+`init` imports the account you're already on, installs the `claude` supervisor + four `settings.json` entries (the tokenmaxxing statusLine, a subagentStatusLine, a Stop hook, a SessionStart hook), and adds the supervisor's bin dir to PATH in your shell rc (idempotent; it must sit ahead of the real `claude` to intercept it). Restart your shell, then add more accounts and go:
 
 ```sh
 tokenmaxxing add        # logs one in, in isolation, and pools it
@@ -45,7 +45,7 @@ claude                  # use claude as always
 | `tokenmaxxing status --force` | additionally ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh |
 | `tokenmaxxing watch [seconds]` | live status: re-render every N seconds (default 120, floor 30; never pings) |
 | `tokenmaxxing config` | effective config with sources; `get`/`set`/`unset` dotted keys, `tidy` prunes unknown keys |
-| `tokenmaxxing serve` | Slack bridge daemon (Socket Mode, no public URL): `setup` prints the app manifest and stores the two tokens, `link <channel-id> <repo>` ties a channel to a repo (`--yolo` for full-autonomy bypassPermissions sessions), then mentioning the bot in that channel opens a Claude Code session per thread (own git worktree by default) and thread messages relay in and out |
+| `tokenmaxxing serve` | Slack bridge daemon (Socket Mode, no public URL): `setup` prints the app manifest and stores the two tokens, `link <channel-id> <repo>` ties a channel to a repo (`--yolo` for full-autonomy bypassPermissions sessions), then mentioning the bot in that channel opens a Claude Code session per thread in the repo checkout (the session cuts its own git worktree only when a task needs isolation) and thread messages relay in and out |
 | `tokenmaxxing doctor` | verify the supervisor + settings entries survived |
 | `tokenmaxxing rename [--codex] <sel> <label>` / `rm <sel>` | manage the pool (`--codex` targets the codex pool: one email can hold both a claude and a codex account) |
 | `tokenmaxxing uninstall` | remove supervisor + settings entries (accounts/credentials kept) |
@@ -77,7 +77,7 @@ The **target** is chosen greedily off each account's cached windows: among usabl
 }
 ```
 
-`projectionMargin` subtracts an EMA of per-turn Δ% for pre-emption; `greedySessionFloor` is the session-used % at which the greedy convergence engages; `switchModels` names the models whose per-model cap triggers a switch; `usagePollTtlMs` is how long a `/usage` per-model poll stays fresh.
+`projectionMargin` is a fixed safety margin subtracted from each threshold bar (effective bar = threshold - margin), so a large turn is less likely to blow past a bar between checks; `greedySessionFloor` is the session-used % at which the greedy convergence engages; `switchModels` names the models whose per-model cap triggers a switch; `usagePollTtlMs` is how long a `/usage` per-model poll stays fresh; `maxWaitMs` bounds the depleted-pool countdown - a soonest reset further out than this does not pause the session (no respawn marker is written and the session simply keeps hitting its limit until an account recovers).
 
 State lives entirely in `~/.config/tokenmaxxing/`. Per-account credentials follow the platform's Claude Code store: the login keychain on macOS (`tokenmaxxing-cred-<uuid8>` items, never plaintext on disk), 0600 files under `~/.config/tokenmaxxing/creds/` on Linux (the same plaintext model claude itself uses for `~/.claude/.credentials.json`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts and hot-swap when quota fills, resuming your session on the fresh account.",
   "type": "module",
   "license": "MIT",

package/src/cli/add.ts

@@ -42,6 +42,7 @@ export async function cmdAdd(): Promise<number> {
       needsReauth: false,
       lastUsage: sampled ? { fiveHour: sampled.session, sevenDay: sampled.weekAll } : existing?.lastUsage,
       lastPerModel: sampled && Object.keys(sampled.perModel).length > 0 ? sampled.perModel : existing?.lastPerModel,
+      lastPerModelAt: sampled && Object.keys(sampled.perModel).length > 0 ? Date.now() : existing?.lastPerModelAt,
       lastUsageAt: sampled ? Date.now() : existing?.lastUsageAt,
     };
     if (existing) Object.assign(existing, fresh);

package/src/cli/auth.ts

@@ -19,7 +19,7 @@ import type { Account, AccountsIndex } from "../lib/types.ts";
 
 const AUTH_USAGE = "usage: tokenmaxxing auth [<email|label|id> | --all]";
 
-export const AuthPlanSchema = z.discriminatedUnion("kind", [
+const AuthPlanSchema = z.discriminatedUnion("kind", [
   /** malformed argv: print AUTH_USAGE, exit 2. */
   z.object({ kind: z.literal("usage") }),
   /** unresolvable state (empty pool, unknown selector): exit 1. */
@@ -105,25 +105,36 @@ async function reauthOne(target: Account): Promise<boolean> {
   // land in one critical section (else a swap-away harvest of the live blob
   // could overwrite this fresh backup right before it is marked healthy).
   const isActive = await withLock(paths.lockFile, async () => {
-    await writeItem(parkedTarget(target.keychainItem), claudeAiOauthOnly(blobRaw));
+    // The account must still be pooled BEFORE anything is written: the
+    // interactive login can sit open for minutes, and a concurrent `xx rm`
+    // completing in that window used to get its parked item recreated as an
+    // orphan no pool entry tracks - plus a false "reauthed" success
+    // (closing-review catch).
     const idx = loadAccounts();
     const account = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
-    if (account) {
-      account.email = oauthAccount.emailAddress;
-      account.organizationUuid = oauthAccount.organizationUuid;
-      account.oauthAccount = oauthAccount;
-      account.subscriptionType = blob.claudeAiOauth.subscriptionType;
-      account.rateLimitTier = blob.claudeAiOauth.rateLimitTier;
-      account.needsReauth = false;
-      if (sampled) {
-        account.lastUsage = { fiveHour: sampled.session, sevenDay: sampled.weekAll };
-        if (Object.keys(sampled.perModel).length > 0) account.lastPerModel = sampled.perModel;
-        account.lastUsageAt = Date.now();
+    if (!account) {
+      console.error(c.red(`${target.label} was removed from the pool while the login was open - nothing written; re-add it with \`tokenmaxxing add\` if wanted`));
+      return null;
+    }
+    await writeItem(parkedTarget(target.keychainItem), claudeAiOauthOnly(blobRaw));
+    account.email = oauthAccount.emailAddress;
+    account.organizationUuid = oauthAccount.organizationUuid;
+    account.oauthAccount = oauthAccount;
+    account.subscriptionType = blob.claudeAiOauth.subscriptionType;
+    account.rateLimitTier = blob.claudeAiOauth.rateLimitTier;
+    account.needsReauth = false;
+    if (sampled) {
+      account.lastUsage = { fiveHour: sampled.session, sevenDay: sampled.weekAll };
+      account.lastUsageAt = Date.now();
+      if (Object.keys(sampled.perModel).length > 0) {
+        account.lastPerModel = sampled.perModel;
+        account.lastPerModelAt = account.lastUsageAt;
       }
-      saveAccounts(idx);
     }
+    saveAccounts(idx);
     return idx.activeAccountUuid === target.accountUuid;
   });
+  if (isActive === null) return false;
 
   const usageNote = sampled ? ` (session ${sampled.session.usedPercentage}% / week ${sampled.weekAll.usedPercentage}%)` : "";
   const tier = claudeTierLabel(blob.claudeAiOauth) ?? "?";

package/src/cli/check.ts

@@ -14,8 +14,9 @@ export async function cmdCheck(): Promise<number> {
     d = await evaluateAndMaybeSwap();
   } catch (e) {
     // unattended under the timer: the log is the only place anyone will look.
-    log("check.error", { err: String((e as Error).message ?? e) });
-    console.error(c.red(`check failed: ${String((e as Error).message ?? e)}`));
+    const detail = e instanceof Error ? e.message : String(e);
+    log("check.error", { err: detail });
+    console.error(c.red(`check failed: ${detail}`));
     return 1;
   }
   if (d.swapped && d.account) {

package/src/cli/codexadd.ts

@@ -28,7 +28,7 @@ export async function cmdCodexAdd(): Promise<number> {
   // Same rationale at the end-of-run cleanup below.
   rmSync(onboardDir, { recursive: true, force: true });
   mkdirSync(onboardDir, { recursive: true });
-  writeFileAtomic(join(onboardDir, "config.toml"), 'cli_auth_credentials_store_mode = "file"\n');
+  writeFileAtomic(join(onboardDir, "config.toml"), 'cli_auth_credentials_store = "file"\n');
 
   console.log(c.cyan("Opening an isolated codex login - your primary login is untouched."));
   console.log(c.dim("Complete the browser sign-in with the account to add; the command exits once you're in."));
@@ -49,49 +49,53 @@ export async function cmdCodexAdd(): Promise<number> {
   await p.exited;
   restoreTermios(savedTermios);
 
-  const cleanup = () => rmSync(onboardDir, { recursive: true, force: true });
-
-  const auth = readCodexAuthAt({ path: join(onboardDir, "auth.json") });
-  if (p.exitCode !== 0 || !auth) {
-    console.error(c.red("no codex login landed in the isolated home - nothing added."));
-    cleanup();
-    return 1;
-  }
-
-  const identity = codexIdentityOf({ auth });
-  console.log(c.dim("sampling usage..."));
-  let usage: CodexUsage | null = null;
+  // The finally guarantees the plaintext onboard home is destroyed on every
+  // non-signal exit; an exception mid-registration must not strand it. (An
+  // interactive Ctrl-C is reaped by the next run's rmSync-first.)
+  let account: CodexAccount;
+  let poolSize: number;
   try {
-    usage = await fetchCodexUsage({ auth });
-  } catch (e) {
-    if (!(e instanceof CodexUsageReadError)) throw e;
-    console.log(c.yellow("could not sample usage now - it will fill in on first use."));
-  }
+    const auth = readCodexAuthAt({ path: join(onboardDir, "auth.json") });
+    if (p.exitCode !== 0 || !auth) {
+      console.error(c.red("no codex login landed in the isolated home - nothing added."));
+      return 1;
+    }
 
-  const credFile = codexCredItemFor(identity.accountId);
-  writeParkedCodexAuth({ credFile, auth });
+    const identity = codexIdentityOf({ auth });
+    console.log(c.dim("sampling usage..."));
+    let usage: CodexUsage | null = null;
+    try {
+      usage = await fetchCodexUsage({ auth });
+    } catch (e) {
+      if (!(e instanceof CodexUsageReadError)) throw e;
+      console.log(c.yellow("could not sample usage now - it will fill in on first use."));
+    }
 
-  const { account, poolSize } = await withLock(codexPaths.lockFile, () => {
-    const index = loadCodexAccounts();
-    const existing = index.accounts.find((entry) => entry.accountId === identity.accountId);
-    const fresh: CodexAccount = {
-      accountId: identity.accountId,
-      email: usage?.email ?? identity.email,
-      label: existing?.label ?? usage?.email ?? identity.email ?? identity.accountId.slice(0, 8),
-      planType: usage?.planType ?? identity.planType,
-      credFile,
-      addedAt: existing?.addedAt ?? new Date().toISOString(),
-      needsReauth: false,
-      lastUsage: usage ? { aggregate: usage.aggregate, perLimit: usage.perLimit } : existing?.lastUsage,
-      lastUsageAt: usage ? Date.now() : existing?.lastUsageAt,
-    };
-    if (existing) Object.assign(existing, fresh);
-    else index.accounts.push(fresh);
-    saveCodexAccounts({ index });
-    return { account: fresh, poolSize: index.accounts.length };
-  });
+    const credFile = codexCredItemFor(identity.accountId);
+    writeParkedCodexAuth({ credFile, auth });
 
-  cleanup();
+    ({ account, poolSize } = await withLock(codexPaths.lockFile, () => {
+      const index = loadCodexAccounts();
+      const existing = index.accounts.find((entry) => entry.accountId === identity.accountId);
+      const fresh: CodexAccount = {
+        accountId: identity.accountId,
+        email: usage?.email ?? identity.email,
+        label: existing?.label ?? usage?.email ?? identity.email ?? identity.accountId.slice(0, 8),
+        planType: usage?.planType ?? identity.planType,
+        credFile,
+        addedAt: existing?.addedAt ?? new Date().toISOString(),
+        needsReauth: false,
+        lastUsage: usage ? { aggregate: usage.aggregate, perLimit: usage.perLimit } : existing?.lastUsage,
+        lastUsageAt: usage ? Date.now() : existing?.lastUsageAt,
+      };
+      if (existing) Object.assign(existing, fresh);
+      else index.accounts.push(fresh);
+      saveCodexAccounts({ index });
+      return { account: fresh, poolSize: index.accounts.length };
+    }));
+  } finally {
+    rmSync(onboardDir, { recursive: true, force: true });
+  }
 
   console.log();
   console.log(`${c.green("✓")} added codex account ${c.bold(account.label)} (${account.planType ?? "?"}) - codex pool now has ${count({ n: poolSize, noun: "account" })}`);

package/src/cli/codexinit.ts

@@ -10,41 +10,56 @@ import { resolveRealCodex, verifyRealCodex } from "../lib/codexbin.ts";
 import { codexIdentityOf, readLiveCodexAuth, writeParkedCodexAuth } from "../lib/codexauth.ts";
 import { CodexUsageReadError, fetchCodexUsage } from "../lib/codexusage.ts";
 import { loadCodexAccounts, saveCodexAccounts } from "../lib/codexstate.ts";
-import { loadConfig, saveConfig } from "../lib/state.ts";
+import { loadConfig, pinBinOverride } from "../lib/state.ts";
 import { installCodexSupervisor, codexSupervisorLink, ensurePathInRc, shellRcPath } from "../lib/install.ts";
 import { withLock } from "../lib/lock.ts";
+import { presentCodexAccountIds } from "../lib/codexpresence.ts";
 import { codexCredItemFor, codexPaths } from "../lib/paths.ts";
 import type { CodexAccount, CodexUsage } from "../lib/types.ts";
 import { c } from "./render.ts";
 
 /** Fail fast when config.toml pins the credential store away from the plain
  *  file tokenmaxxing swaps (structural line scan: the repo ships no TOML
- *  parser, and this single key is the only one we ever inspect). */
-function keyringStoreConfigured(): boolean {
+ *  parser, and this single key is the only one we ever inspect). The real key
+ *  is `cli_auth_credentials_store` (binary-verified 0.144.5; an earlier
+ *  verification misread the enum TYPE name as a `_mode` key). An ABSENT key is
+ *  allowed: the DEFAULT at 0.144.5 is `file` itself (source-verified:
+ *  AuthCredentialsStoreMode derives Default on the File variant), and init
+ *  separately verifies a harvestable auth.json.
+ *  Any EXPLICIT non-file pin (keyring, auto, ephemeral) is a deliberate store
+ *  choice tokenmaxxing cannot honor. */
+function storePinnedAwayFromFile(): boolean {
   const configToml = `${codexPaths.home}/config.toml`;
   if (!existsSync(configToml)) return false;
   for (const rawLine of readFileSync(configToml, "utf8").split("\n")) {
     const line = rawLine.trim();
-    if (!line.startsWith("cli_auth_credentials_store_mode")) continue;
-    return line.includes("keyring");
+    if (!line.startsWith("cli_auth_credentials_store")) continue;
+    const rest = line.slice("cli_auth_credentials_store".length).trimStart();
+    if (!rest.startsWith("=")) continue;
+    // Value only: strip an inline TOML comment and the quotes structurally so
+    // a comment mentioning "keyring" never false-positives the fail-fast.
+    const beforeComment = rest.slice(1).split("#", 1)[0]!;
+    const value = beforeComment.replaceAll('"', "").replaceAll("'", "").trim();
+    return value !== "file";
   }
   return false;
 }
 
 export async function cmdCodexInit(): Promise<number> {
+  // Fail fast on a broken merged config before installing (see cmdInit).
+  loadConfig();
   const real = resolveRealCodex();
   const fail = verifyRealCodex({ bin: real });
   if (fail !== null) {
     console.error(c.red(`codex binary failed verification: ${real}: ${fail}`));
     return 1;
   }
-  const cfg = loadConfig();
-  cfg.codexBin = real;
-  saveConfig(cfg);
+  // Sparse write: only the pin lands in the file, never the merged config.
+  pinBinOverride({ key: "codexBin", bin: real });
 
-  if (keyringStoreConfigured()) {
-    console.error(c.red("codex config.toml pins cli_auth_credentials_store_mode to keyring - tokenmaxxing swaps the plain auth.json file."));
-    console.error(c.dim('recovery: set cli_auth_credentials_store_mode = "file" in ~/.codex/config.toml, run `codex login`, then re-run this.'));
+  if (storePinnedAwayFromFile()) {
+    console.error(c.red("codex config.toml pins cli_auth_credentials_store away from the plain auth.json file tokenmaxxing swaps."));
+    console.error(c.dim('recovery: set cli_auth_credentials_store = "file" in ~/.codex/config.toml, run `codex login`, then re-run this.'));
     return 1;
   }
 
@@ -65,9 +80,41 @@ export async function cmdCodexInit(): Promise<number> {
   }
 
   const credFile = codexCredItemFor(identity.accountId);
-  writeParkedCodexAuth({ credFile, auth: live });
+
+  // A RUNNING supervised session on this account can rotate auth.json at any
+  // moment (codex persists rotations instantly, and the flock serializes only
+  // tokenmaxxing actors) - a snapshot parked now could hold an already-
+  // superseded refresh token whose next refresh is reuse-punished (cubic
+  // review catch, PR #35). Refuse loudly, like the sampler's present-account
+  // rule; sessions launched around the shim are the same accepted gap as
+  // everywhere presence is the signal.
+  if (presentCodexAccountIds().has(identity.accountId)) {
+    console.error(c.red("a live supervised codex session is running this account - its token rotates under us, so parking a snapshot now could poison the backup."));
+    console.error(c.dim("close that codex session (or let it exit) and re-run `tokenmaxxing init --codex`."));
+    return 1;
+  }
 
   const account = await withLock(codexPaths.lockFile, () => {
+    // Re-check presence INSIDE the critical section (pullfrog review catch,
+    // PR #35): supervisor spawns are flock-serialized too, so one can start -
+    // check passed, presence written, session live - entirely between the
+    // friendly pre-lock check above and this lock acquisition. The throw
+    // routes through the CLI error boundary as a clean failure.
+    if (presentCodexAccountIds().has(identity.accountId)) {
+      throw new Error("a live supervised codex session started running this account mid-init - close it and re-run `tokenmaxxing init --codex`");
+    }
+    // Park INSIDE the flock, from a blob RE-READ inside it (closing-review
+    // catch): the pre-lock snapshot is seconds stale (a network usage GET sits
+    // in between), and parking it unlocked could clobber a concurrent swap's
+    // just-harvested newest rotation with a superseded refresh token - whose
+    // next refresh is reuse-punished into a dead grant family. An identity
+    // that changed since the pre-lock read means a swap landed mid-init:
+    // abort rather than file the wrong account.
+    const fresh2 = readLiveCodexAuth();
+    if (!fresh2 || codexIdentityOf({ auth: fresh2 }).accountId !== identity.accountId) {
+      throw new Error("the live codex login changed while init was running (a concurrent swap?) - re-run `tokenmaxxing init --codex`");
+    }
+    writeParkedCodexAuth({ credFile, auth: fresh2 });
     const index = loadCodexAccounts();
     const existing = index.accounts.find((entry) => entry.accountId === identity.accountId);
     const fresh: CodexAccount = {

package/src/cli/codexswitch.ts

@@ -49,7 +49,21 @@ export async function cmdCodexSwitch(sel?: string): Promise<number> {
         console.error(c.red(`${target.label} is running in a live codex session - swapping onto it would break that session's credential`));
         return 1;
       }
-      await performCodexSwap({ target });
+      if (target.needsReauth) {
+        console.error(c.red(`${target.label} needs re-auth - run \`codex login\` in an isolated home and \`tokenmaxxing add --codex\``));
+        return 1;
+      }
+      try {
+        await performCodexSwap({ target });
+      } catch (e) {
+        // a dead grant is an expected operational state, not a stack trace
+        // (closing-review catch; mirrors the claude selector path).
+        if (e instanceof CodexInvalidGrantError) {
+          console.error(c.red(`${target.label}'s refresh token is dead - re-add it with \`tokenmaxxing add --codex\``));
+          return 1;
+        }
+        throw e;
+      }
       console.log(`${c.green("✓")} switched codex to ${c.bold(target.label)} (takes effect on the next codex start)`);
       return 0;
     }

package/src/cli/config.ts

@@ -10,7 +10,7 @@ import { isPlainObject } from "es-toolkit";
 import { get, set, unset } from "es-toolkit/compat";
 import { z } from "zod";
 import { paths, realClaudeBinFromEnv, realCodexBinFromEnv } from "../lib/paths.ts";
-import { ConfigFileSchema, loadConfig } from "../lib/state.ts";
+import { ConfigFileSchema, loadConfig, mergeConfigFile } from "../lib/state.ts";
 import { writeFileAtomic } from "../lib/atomic.ts";
 import { c } from "./render.ts";
 
@@ -115,6 +115,15 @@ function cmdSet(key: string, valueText: string): number {
     console.error(c.red(`rejected: ${validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`));
     return 1;
   }
+  // The per-field gate passed; the MERGED whole must too, or this write makes
+  // every later loadConfig throw (the projectionMargin-vs-thresholds refine),
+  // silently disabling status/switch/hooks/statusline until the file is
+  // hand-repaired (closing-review catch).
+  const mergedCheck = mergeConfigFile(validated.data);
+  if (!mergedCheck.ok) {
+    console.error(c.red(`rejected: ${mergedCheck.detail}`));
+    return 1;
+  }
   writeRawFile({ raw: next });
   // Report the FILE-level change: with an env override in place, the effective
   // value would not move, and an unchanged-looking arrow would misrepresent