tokenmaxxing 1.6.0 → 1.8.0

package/DESIGN.md

@@ -39,7 +39,7 @@ It is a process manager only - spawn with inherited stdio plus saved `stty -g` t
 
 - 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.
+The switching path runs no long-lived daemon. The statusline pushes usage. Hooks and the supervisor react. The periodic check job above is the only recurring process. The `claude` binary and `~/.claude` layout are untouched.
 
 ---
 
@@ -81,40 +81,12 @@ 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 **Layer 1 screening bars** - `five_hour >= 95%` OR `seven_day >= 98%`, per org (`thresholds`) - force a switch onto a fresher account 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.
 
-**Two layers - pump the last drops.** The screening bars deliberately leave headroom, so when *every* account is over them Layer 1 alone would park the pool with 2-5% of each account's quota still unspent. **Layer 2 - the wall bars** (`hardThresholds`, default `100/100`, the server's own limit) - is the fallback reached only at that point: the session **holds its seat and squeezes** while it is under the wall, else swaps onto the best still-under-wall account (the same pace-pressure ranking as every other swap - squeeze the account whose weekly quota is most about to be forfeited first), and only parks (depleted-wait) once every account has truly walled. Recovery is then measured against the wall, not the screening bar, so an account whose 5h window drops below 100 is squeezable again even while its weekly window still sits above the Layer 1 bar. The wall reading is the statusLine's own `rate_limits` feed - the same server-side figure claude's `/rate-limit-options` renders - so when an account genuinely maxes out the tee shows 100 and Layer 2 moves on; a single-turn overshoot is caught one boundary later (the periodic `check` timer, or the next Stop hook) without needing to sniff assistant text. The serve/SDK path additionally stamps an account walled the instant an *errored* turn result reports a limit (`recordObservedLimit`, gated on `is_error`), because it has no statusLine tee. Set `hardThresholds` equal to `thresholds` to disable Layer 2. **Layer 2 is Claude-only:** a swap on Claude is a hot, in-place credential adoption every concurrent session follows automatically, whereas a running Codex refuses another account's credential (restart is the switch), so a last-drop-swap there would strand any sibling still on the walled account - Codex instead keeps riding its current account to the wall (its existing all-exhausted stay-put already squeezes it).
+**Two layers - pump the last drops.** The screening bars deliberately leave headroom, so when *every* account is over them Layer 1 alone would park the pool with 2-5% of each account's quota still unspent. **Layer 2 - the wall bars** (`hardThresholds`, default `100/100`, the server's own limit) - is the fallback reached only at that point: the session **holds its seat and squeezes** while it is under the wall, else swaps onto the best still-under-wall account (the same pace-pressure ranking as every other swap - squeeze the account whose weekly quota is most about to be forfeited first), and only parks (depleted-wait) once every account has truly walled. Recovery is then measured against the wall, not the screening bar, so an account whose 5h window drops below 100 is squeezable again even while its weekly window still sits above the Layer 1 bar. The wall reading is the statusLine's own `rate_limits` feed - the same server-side figure claude's `/rate-limit-options` renders - so when an account genuinely maxes out the tee shows 100 and Layer 2 moves on; a single-turn overshoot is caught one boundary later (the periodic `check` timer, or the next Stop hook) without needing to sniff assistant text. Set `hardThresholds` equal to `thresholds` to disable Layer 2. **Layer 2 is Claude-only:** a swap on Claude is a hot, in-place credential adoption every concurrent session follows automatically, whereas a running Codex refuses another account's credential (restart is the switch), so a last-drop-swap there would strand any sibling still on the walled account - Codex instead keeps riding its current account to the wall (its existing all-exhausted stay-put already squeezes it).
 
 **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. Both layers apply the per-model gate: a burnt Fable cap screens an account out of a Layer 1 switch, and a Fable cap at the wall screens it out of the Layer 2 squeeze too.
 
 ---
 
-## 5b. The Slack bridge (`xx serve`, 0.18.0)
-
-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, 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` (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.
-- **Steering (2026-07-27, owner decision: steering is the default for a mid-turn reply)**: the per-turn query takes STREAMING input (`prompt` as an AsyncIterable of stream-json user messages) instead of a one-shot string, so a relayable reply landing while the turn runs is written onto the live child's stdin. The CLI folds it into the running turn at the next tool boundary (the same queued-message injection interactive Claude Code uses; a message that misses the last fold window runs as its own turn in the same child before exit, so nothing drops - both verified against claude 2.1.220). serve-side: `relayThread` exposes a per-attempt `steer()` via `onSteer`, refused once the attempt's result arrives (stdin ends then, and the SDK silently drops writes to an ended stdin); `buildServeRuntime` keeps one acceptor per live thread and tries it per arriving message - refusals (idle thread, parked pool, a non-empty inbox or waiting turn for ordering, an out-of-order late arrival, drain) fall back to the inbox path. Steered text appends to the durable `activeTurn.prompt` (kill-replays and limit-resumes carry it) and folds into retry prompts; steered message ids ride the marker (`steeredMessageIds`) wearing the same hourglass-to-terminal reaction lifecycle; an inbound takeover of a deferred turn adopts the held turn's unsettled ids so no hourglass is orphaned, and a steer answers a resumed turn's pending ask (attention cleared) like a queued turn would. SUCCESS IS STICKY per attempt: a post-fold-window steer's own drained turn can emit a second, errored result after the primary answer already succeeded, and marking the turn failed then would re-run completed work through the retry machinery - the steer is announced lost in-thread instead, `outcome.steerLost` settles the steered messages' reactions as failed (a lost instruction must never read green; attribution is per-turn, a documented tradeoff on TurnOutcomeSchema), a limit classification stays sticky across a child's errored results (a drained turn's generic death must not declassify the primary turn's recoverable limit), and each turn's result-only answer is flushed AT its result so a trailing turn's notice or result can neither suppress nor clobber a tool-only answer (all adversarial-review catches). Two CLI gotchas are load-bearing: steered messages carry NO uuid (the CLI dedupes by uuid and silently swallows a reuse) and NO priority (default "next" folds politely; "now" is a hard interrupt).
-- **Arrival dispatch (2026-07-27, replacing the chat queue strategy)**: Chat runs `concurrency: {strategy: "concurrent"}` - every message reaches `onMessage` the moment Slack delivers it. The queue strategy's 30s dispatch-lock lease made mid-turn messages invisible until the turn ended and could REORDER them (a reply enqueued behind a live lease was released only when a later message took the expired lock, newest dispatched first - adversarial-review catch on the steering redesign, present at any TTL). The daemon owns everything the queue provided: per-thread turn ordering via the serialized chain (`serializedTurn` counts only TURN-producing work, so reaction notes and nudges can never gate steering - a second review catch); mid-turn folding via steering; and batching via a per-thread INBOX - un-steered messages accumulate and drain as ONE folded turn, sorted by Slack ts (ids are timestamps), so an upstream arrival race cannot reorder the prompt and a burst behind a long turn costs one metered spawn, not N. Per-thread arrival decisions are themselves chained (steer-or-inbox for one message completes before the next begins), and chat's message-id dedupe runs before its concurrency branch, so the app_mention + message.channels double-delivery stays deduped.
-- **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; per-thread turn serialization is owned by the daemon itself (a promise chain per thread id), and message batching by the daemon's inbox (see the arrival-dispatch bullet; the chat queue strategy and its skipped/TTL machinery were retired with the 2026-07-27 steering redesign, though `context.skipped` is still merged defensively when present); 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 after an undocumented window: `message_not_in_streaming_state`), relayThread salvages the dead segment in TEXT space: proven-delivered text is a mirror StreamingMarkdownRenderer's committable prefix over the confirmed chunks (each pull proves the previous append landed; the adapter's renderer holds back the trailing unterminated line until its post-iteration forced flush, so chunk-granular salvage would miss a final reply with no trailing newline - the live 2026-07-21 incident), and the remainder re-posts as a fresh message split at line boundaries, plus unconfirmed cards, bounded by a futility budget that refills on delivery progress; the textLost diagnostic remains only for exhausted salvage, and ambiguous failures duplicate a tail line rather than lose it.
-- **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. 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.
-- **Usage-limit auto-resume** (2026-07-21, superseding the drop-beats-false-promise rule for the known-wake case): a turn that ends at a usage limit with a KNOWN recovery time defers instead of dropping. relayThread reports `deferUntil`, the thread's durable activeTurn marker keeps a `resumeAt`, and a per-thread daemon timer (cancelled on drain, re-armed from the record at startup: future wakes schedule, past wakes recover immediately) fires the same interrupted-turn recovery path - serialized chain, fresh-reload supersede check, pool-recovery notice, `resumeDecision` capping total resumes. The defer triggers: known recovery past the parking deadline or recovery budget, retries exhausted while a post-burn pool probe reports a wake, and an unclassifiable child failure (no limit phrase in the error) converted by a pool probe reporting exhaustion - the pool state is the evidence the error text did not carry. Only an unknown recovery time still posts the honest re-send drop.
-- **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).
-- **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) that Slack groups into ONE collapsible plan block per turn (the serve edge wraps every posted segment in a `StreamingPlan` with `groupTasks: "plan"`, Slack's `task_display_mode: "plan"`; user ask 2026-07-20 "squash them into one dropdown", superseding the 2026-07-18 separate-messages shape), and reply text as native markdown with rendered code fences - so one turn streams as a single Slack message: the reply plus one dropdown of its activity. Reply text also splits at `SEGMENT_TEXT_MAX` (10,000 chars): Slack rejects an over-long message with `msg_too_long` (the streamed message accumulates server-side toward the documented 12,000-char `markdown_text` envelope) and nothing in the chat stack bounds or splits text, so one over-cap append used to reject the whole post and lose the reply (live incident 2026-07-20); a break forced inside a code fence closes and reopens the fence, fence parity is tracked over the segment's accumulated text (SDK deltas do not respect markdown token boundaries), and a cut never slices through a backtick run. A later main text block (typically post-tool prose) opens on a `\n\n` paragraph break (`textStreamed`), restoring the separation the per-tool message split used to provide; whitespace-only deltas do not arm it. Notices still post as their own messages, and a rejected append (Slack's message cap, a finalized idle stream) carries its undelivered chunks into a follow-on message via the dead-segment salvage.
-- **One Slack app per daemon** (live incident 2026-07-20): Slack Socket Mode delivers each event envelope to exactly one of an app's open connections, so two serve daemons sharing one Slack app steal each other's events - mentions usually survive (Slack emits `app_mention` plus `message.channels` for one mention and the Chat SDK dedupes them per-process), but a non-mention thread follow-up rides a single envelope and silently dies when the wrong daemon receives it. No code can route Slack's load-balancing (the hello frame's `num_connections` is discarded by `@slack/socket-mode` before any event fires), so the constraint is documented (docs limitations page) and diagnosed: `serve.unlinked_channel` logs once per channel per run with the shared-app explanation. Every host needs its own Slack app with its own tokens.
-- **Todo checklist card**: TodoWrite is bookkeeping, not a real tool run, so it never opens a generic card. 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 messages, so a TodoWrite after a dead-segment recovery starts a fresh card in the follow-on 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, in a live workspace channel): 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.
-
----
-
 ## 6. Honest papercuts
 - **Respawn hiccup (depleted pause only).** Plain swaps never restart the session. When the whole pool is depleted you see `claude` stop, a countdown, and a resume; anything typed in the split second before the SIGTERM is lost, and the supervisor resets terminal mode so nothing is left garbled.
 - **Adoption lag.** macOS reads the keychain through a raw 30s cache, so at most the first turn after a swap can still meter the old account. The bars' headroom absorbs it.
@@ -139,7 +111,9 @@ A local Socket Mode daemon (no public URL) that turns Slack threads into Claude
 
 **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.
+**Shipped since (relay companion):** `tokenmaxxing relay` hosts durable tmux workers for cheap host subagents. Claude `--permission-mode` vocabulary (default `auto`), Codex sandbox mapping, per-session flock + registry under `relay/`, additive turn-done markers (never `respawn/`), and `permission-needed` stdout pings decided by main. Host finish hooks still run on every return including pings. Skill + agents live under `agent-plugin/` (`relay-session`, `tokenmaxxing-claude`, `tokenmaxxing-codex`). Docs: `docs/content/docs/commands.mdx`, `state-directory.mdx`, `agent-plugin.mdx`.
+
+**Non-goals:** an API/MITM proxy; reimplementing OAuth beyond the single refresh-grant call in the swap; Slack serve as the relay bus; soft concurrency caps; Cloud Agents without local tmux.
 
 ---
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anaclumos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -73,7 +73,6 @@ 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 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 [--codex] <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) |
@@ -159,7 +158,7 @@ Two codex-specific facts worth knowing: codex does not run hooks it has not been
 
 ## How it's built
 
-TypeScript on Bun: one multi-call entry (`src/main.ts`) serves the CLI, the `claude` supervisor, and the hook/statusLine shims, and runs directly under bun. [Zod](https://zod.dev) validates every external-boundary payload (credential blobs, hook/statusLine stdin, OAuth responses, config), [es-toolkit](https://es-toolkit.dev) for utilities. The supervisor is process/terminal-only - it never proxies API traffic or touches tokens in flight. Cross-process coordination uses `flock(2)` via `bun:ffi` (macOS has no `flock(1)`; one codepath serves both platforms). Credential I/O goes through one platform-selected store: `security(1)` generic-passwords on macOS, atomic 0600 file writes on Linux.
+TypeScript on Bun. One multi-call entry (`src/main.ts`) runs the CLI, the `claude` supervisor, and the hook/statusLine shims. [Zod](https://zod.dev) validates every external-boundary payload (credential blobs, hook/statusLine stdin, OAuth responses, config). [es-toolkit](https://es-toolkit.dev) for utilities. The supervisor is process/terminal-only. It never proxies API traffic or touches tokens in flight. Cross-process coordination uses `flock(2)` via `bun:ffi` (macOS has no `flock(1)`; one codepath for both platforms). Credential I/O goes through one platform-selected store: `security(1)` generic-passwords on macOS, atomic 0600 file writes on Linux.
 
 ## License
 

package/agent-plugin/agents/tokenmaxxing-claude.md

@@ -0,0 +1,43 @@
+---
+name: tokenmaxxing-claude
+description: Cheap shell-only relay to a durable Claude Code worker via tokenmaxxing relay. Use for long-running Claude sessions with permission pings back to main.
+model: inherit
+readonly: false
+is_background: false
+---
+
+# Tokenmaxxing Claude relay
+
+You are a thin shell. Do not edit files yourself. Do not spawn nested Task/Agent children. Only call `tokenmaxxing relay` (alias `xx relay`).
+
+## Commands
+
+```bash
+tokenmaxxing relay turn --worker claude --permission-mode auto --cwd <dir> --session <uuid-or-omit> "<prompt>"
+tokenmaxxing relay decide --session <uuid> --approve
+tokenmaxxing relay decide --session <uuid> --deny
+tokenmaxxing relay set-permission-mode --session <uuid> --permission-mode <mode>
+tokenmaxxing relay status --session <uuid>
+tokenmaxxing relay destroy --session <uuid>
+```
+
+Default permission mode is `auto`. Modes: `default` (alias `manual`), `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`.
+
+## Stdout protocol
+
+```
+session: <id>
+permission-mode: <mode>
+# turn output OR:
+permission-needed: <requestId>
+summary: <one line>
+detail: <flagged action>
+session: <id>
+permission-mode: auto
+```
+
+On `permission-needed`, return that block to main and stop. Main decides (or auto-approves when Cursor Run Mode is Run Everything, or when Claude main is `bypassPermissions`). Then you run `relay decide` and wait.
+
+## Finish hooks
+
+Your host finish hook (`subagentStop` / `SubagentStop`) must run on every return, including permission-needed. A permission park is not a worker Stop.

package/agent-plugin/agents/tokenmaxxing-codex.md

@@ -0,0 +1,40 @@
+---
+name: tokenmaxxing-codex
+description: Cheap shell-only relay to a durable Codex worker via tokenmaxxing relay. Claude permission-mode names map to Codex sandbox flags.
+model: inherit
+readonly: false
+is_background: false
+---
+
+# Tokenmaxxing Codex relay
+
+You are a thin shell. Do not edit files yourself. Do not spawn nested Task/Agent children. Only call `tokenmaxxing relay` (alias `xx relay`).
+
+## Commands
+
+```bash
+tokenmaxxing relay turn --worker codex --permission-mode auto --cwd <dir> --session <uuid-or-omit> "<prompt>"
+tokenmaxxing relay decide --session <uuid> --approve
+tokenmaxxing relay decide --session <uuid> --deny
+tokenmaxxing relay set-permission-mode --session <uuid> --permission-mode <mode>
+tokenmaxxing relay status --session <uuid>
+tokenmaxxing relay destroy --session <uuid>
+```
+
+CLI still speaks Claude permission-mode names. Codex mapping:
+
+| Mode | Codex flags |
+|---|---|
+| `plan` / `default` | `--sandbox read-only` + ask-for-approval on |
+| `acceptEdits` | `--sandbox workspace-write` |
+| `auto` | workspace-write + ask-for-approval |
+| `dontAsk` | read-only + approval never |
+| `bypassPermissions` | `--sandbox danger-full-access` + approval off |
+
+## Stdout protocol
+
+Same as the Claude relay agent. On `permission-needed`, return the block to main; then `relay decide`.
+
+## Finish hooks
+
+Host finish hooks run on every return including permission-needed. Worker Stop still runs only on real turn finish.

package/agent-plugin/bin/tokenmaxxing-mcp

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+import { main } from "../../src/entries/mcp.ts";
+
+main().catch((e: unknown) => {
+  console.error(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+});

package/agent-plugin/hooks/cursor-relay.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "hooks": {
+    "tokenmaxxingRelay": {
+      "description": "tokenmaxxing-owned Cursor hook group for relay finish behavior. Host finish hooks must still run on every subagent return including permission-needed.",
+      "subagentStop": [
+        {
+          "type": "command",
+          "command": "/usr/bin/true"
+        }
+      ]
+    }
+  }
+}

package/agent-plugin/mcp.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "tokenmaxxing": {
+      "type": "stdio",
+      "command": "./bin/tokenmaxxing-mcp",
+      "cwd": "${PLUGIN_ROOT}"
+    }
+  }
+}

package/agent-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "tokenmaxxing",
+  "version": "1.8.0",
+  "description": "Pool Claude Code and Codex logins, switch on pace pressure, and expose safe ops tools to agent clients.",
+  "author": {
+    "name": "anaclumos",
+    "url": "https://github.com/anaclumos"
+  },
+  "homepage": "https://github.com/anaclumos/tokenmaxxing",
+  "repository": "https://github.com/anaclumos/tokenmaxxing",
+  "license": "MIT",
+  "keywords": [
+    "claude",
+    "codex",
+    "quota",
+    "account-switching",
+    "mcp"
+  ]
+}

package/agent-plugin/skills/codex-pool/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: codex-pool
+description: Operate the Codex side of the pool (restart-is-switch, no Layer 2, never target a running sibling). Use for codex init/switch/status questions or MCP pool_switch with codex=true.
+---
+
+# Codex pool
+
+## Mechanics
+
+- No hot-swap: restart IS the switch (`codex resume <sid>`). A credential write takes effect on the next codex start.
+- Auto-switching needs trusted hooks (`/hooks`). Do not clobber the user's `notify` key in `config.toml`.
+- Refresh-token reuse is punished; a superseded token can kill the grant family. Persist every rotation immediately.
+- An account running in another supervised session is never a swap target and never sampler-refreshed. Parked does not mean idle.
+- Classify windows by DURATION, never by position. Some plans have no 5h window.
+- Layer 2 wall squeeze is Claude-only. Do not extend it to Codex.
+
+## Agent actions
+
+- Read: `pool_ls` / `pool_status` (Codex section included when present).
+- Mutate: MCP `pool_switch` with `codex=true`, `confirm=true`, and `TOKENMAXXING_AGENT_MUTATIONS=1` after user approval.
+- Interactive `init --codex` / `add --codex` / reauth stay human-driven.
+
+See [references/codex.md](references/codex.md).

package/agent-plugin/skills/codex-pool/references/codex.md

@@ -0,0 +1,5 @@
+# Codex references
+
+- `docs/content/docs/codex.mdx`
+- `src/lib/codexdecide.ts`, `src/lib/codexpick.ts`, `src/lib/codexswap.ts`
+- `.memory/cc-codex-auth-mechanics.md`

package/agent-plugin/skills/credentials-hygiene/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: credentials-hygiene
+description: Credential and identity rules for tokenmaxxing (fetchTokenOrg identity, flock, no blob compare, never print secrets). Use before any auth, swap, or credential-touching change.
+---
+
+# Credentials hygiene
+
+## Identity
+
+- Identity is whatever `fetchTokenOrg` reports, never a stored label and never a blob byte compare. Two rotations of one account differ byte-for-byte.
+- Park a credential under its token's real owner. Commit the active label in the same critical section as credential writes.
+- Every live-store write goes through `withClaudeRefreshLock` (Claude). Near-expiry sessions can rotate into the live store at any moment.
+
+## Isolation
+
+- Refuse ambient `CLAUDE_CONFIG_DIR` / `CLAUDE_SECURESTORAGE_CONFIG_DIR` in CLI, SDK, and MCP.
+- A missing namespaced keychain item never falls back to the live one.
+- Same accounts pooled on several hosts race on refresh (documented limitation).
+
+## Agent hard stops
+
+- No tool may return keychain blobs, `.credentials.json`, `auth.json`, or OAuth access/refresh tokens.
+- Do not bypass Claude `/usage` with direct `GET /api/oauth/usage` (owner-rejected; 429s on the active session).
+- Prefer MCP read tools; never `cat` credential paths into the transcript.
+
+See [references/credentials.md](references/credentials.md).

package/agent-plugin/skills/credentials-hygiene/references/credentials.md

@@ -0,0 +1,6 @@
+# Credential references
+
+- `docs/content/docs/credentials.mdx`
+- `DESIGN.md` sections on install and swap
+- `.memory/cc-codex-auth-mechanics.md`
+- `src/lib/credstore.ts`, `src/lib/oauth.ts`

package/agent-plugin/skills/doctor-diagnostics/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: doctor-diagnostics
+description: Diagnose a broken or incomplete tokenmaxxing install (supervisor, hooks, timer, credential identity). Use when doctor fails, PATH looks wrong, or identity drift is suspected. Prefer the MCP doctor tool.
+---
+
+# Doctor and diagnostics
+
+## Prefer MCP
+
+Call `doctor`. It checks the supervisor wrapper, settings hooks, periodic timer, live/parked credential presence, and org identity match. Output is pass/fail plus labels.
+
+Also useful: `config_get` (no key) for effective config sources, and `pool_ls` for needs-reauth.
+
+## Hard stops
+
+- Never dump keychain items, `.credentials.json`, `auth.json`, or OAuth tokens into chat.
+- Doctor never refreshes tokens. Expired access tokens show as unverifiable identity, not as a prompt to paste secrets.
+- Do not run `init` / `add` / `auth` from an agent session without the user present for interactive login.
+
+## Common repairs (ask before mutating)
+
+- Missing wrapper or hooks: user runs `tokenmaxxing init` (or `init --codex`).
+- needs-reauth: user runs `tokenmaxxing auth <label>` (or `--all`).
+- PATH: `binDir` must precede the real claude.
+
+See [references/troubleshooting.md](references/troubleshooting.md).

package/agent-plugin/skills/doctor-diagnostics/references/troubleshooting.md

@@ -0,0 +1,5 @@
+# Troubleshooting pointers
+
+- `docs/content/docs/troubleshooting.mdx`
+- `docs/content/docs/state-directory.mdx` for where state lives under `~/.config/tokenmaxxing` (or `TOKENMAXXING_HOME`)
+- Ambient `CLAUDE_CONFIG_DIR` / `CLAUDE_SECURESTORAGE_CONFIG_DIR` must be unset for CLI, SDK, and this MCP server

package/agent-plugin/skills/pool-status/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: pool-status
+description: Read the Claude and Codex account pool safely (list, usage bars, watch). Use when checking quota, which account is active, needs-reauth, or before any switch. Prefer MCP pool_ls and pool_status over raw shell.
+---
+
+# Pool status (safe reads)
+
+## Prefer MCP
+
+- `pool_ls` for labels, active marker, needs-reauth
+- `pool_status` for 5h / weekly / per-model bars (free `/usage` path)
+
+If MCP is unavailable, run `tokenmaxxing ls` or `tokenmaxxing status` (alias `xx`). Never add `--force`.
+
+## Hard stops
+
+- Do not run `status --force` or bare `xx --force`. That pings every account with a real request and opens each 5h window.
+- Do not print credential files, keychain blobs, or OAuth tokens. Labels and status only.
+- Do not kill sessions or supervisors to "free" an account.
+
+## Notes
+
+- Active Claude usage often comes from the statusLine tee; parked accounts are probed in isolation.
+- `watch` re-renders status on an interval and never force-pings.
+- Hermetic agents: set `TOKENMAXXING_HOME` to a throwaway directory.
+
+See [references/commands.md](references/commands.md).

package/agent-plugin/skills/pool-status/references/commands.md

@@ -0,0 +1,8 @@
+# Status and list commands
+
+- `tokenmaxxing` / `tokenmaxxing status`: sample and show bars; persists cached usage for the picker.
+- `tokenmaxxing status --force`: DENIED for agents without explicit user approval. Meters every account.
+- `tokenmaxxing ls`: compact list.
+- `tokenmaxxing watch [seconds]`: live re-render (default 120), never `--force`.
+
+Docs: `docs/content/docs/commands.mdx`.

package/agent-plugin/skills/relay-session/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: relay-session
+description: Run durable Claude Code or Codex workers through tokenmaxxing relay (tmux). Use when a host agent needs a long-lived pooled worker, permission pings to main, or tokenmaxxing-claude / tokenmaxxing-codex agents.
+---
+
+# Relay session
+
+Host agents stay cheap. They shell into `tokenmaxxing relay`, which owns a durable tmux worker (Claude Code or Codex via tokenmaxxing). High-churn concurrent sessions are expected.
+
+Install templates: `tokenmaxxing relay install --target cursor|claude|all`.
+
+## Claude worker permission modes
+
+CLI: `claude --permission-mode <mode>` / `relay set-permission-mode --permission-mode <mode>`.
+
+| Mode | What runs without asking |
+|---|---|
+| `default` (alias `manual`) | Reads only |
+| `acceptEdits` | Reads, file edits, common filesystem cmds in cwd |
+| `plan` | Reads (+ classifier-approved cmds when auto available) |
+| `auto` | Everything with background safety classifier (**relay default**) |
+| `dontAsk` | Only pre-approved tools; else deny |
+| `bypassPermissions` | Everything (needs allow-dangerously flags) |
+
+Claude `auto` is classifier-assisted autonomy, not "defer to main". Relay pings main only when the worker would still prompt.
+
+## Cursor Run Modes (main only)
+
+| Run Mode | Role for relay |
+|---|---|
+| Auto-review | Main decides each ping or escalates to the user |
+| Allowlist | Main decides / escalates |
+| Run Everything | Main auto-`relay decide --approve` on worker pings |
+
+Do not probe undocumented APIs for main's Run Mode. Main states or infers it.
+
+If Claude main is itself in `bypassPermissions`, auto-approve worker pings the same way.
+
+## Codex mapping
+
+| Claude mode | Codex flags |
+|---|---|
+| `plan` / `default` | `--sandbox read-only` + ask-for-approval on |
+| `acceptEdits` | `--sandbox workspace-write` |
+| `auto` | workspace-write + ask-for-approval |
+| `dontAsk` | read-only + approval never |
+| `bypassPermissions` | `--sandbox danger-full-access` + approval off |
+
+## Shared stdout protocol
+
+```
+session: <id>
+permission-mode: <mode>
+# turn output OR:
+permission-needed: <requestId>
+summary: <one line>
+detail: <flagged action>
+session: <id>
+permission-mode: auto
+```
+
+## Commands
+
+| Command | Job |
+|---|---|
+| `relay turn` | Ensure session, send prompt, wait until turn-done or permission-needed |
+| `relay decide` | Approve/deny pending ping; resume worker |
+| `relay set-permission-mode` | Change live worker mode |
+| `relay status` / `destroy` / `gc` | Inspect, tear down, reap |
+| `relay install` / `relay config` | Host templates + relay.json |
+
+Flags: `--worker claude|codex`, `--session`, `--cwd`, `--permission-mode`, prompt via argv/stdin.
+
+## Finish hooks
+
+1. Cheap relay host finish hooks (`subagentStop` / `SubagentStop`) fire on every return, including `permission-needed`.
+2. Worker Stop / Codex Stop still run on real turn finish (pool logic unchanged).
+3. Relay turn-done markers are additive under `$TOKENMAXXING_HOME/relay/turn-done/`. Permission park is not a fake worker Stop. Never write into `respawn/`.
+
+## Cursor IPC matrix
+
+| Contract | Relay support |
+|---|---|
+| Task / custom agent prompt | Primary in |
+| Task final message | Primary out (delta or permission-needed) |
+| Task resume / interrupt | Continue with decide / set-permission-mode / next turn |
+| Foreground / background + completion notify | Prefer foreground under modes that still prompt |
+| Frontmatter model / readonly / is_background / tools | Shell-only templates; configurable cheap model |
+| `/name` delegate | Same agents |
+| subagentStart / subagentStop (+ followup_message) | Optional hooks; finish hooks always run |
+| Task preToolUse / postToolUse | Optional |
+| UpdateCurrentStep | UI phases only, not permission channel |
+| Nesting | Relay must not spawn Task children |
+
+## Claude IPC matrix
+
+| Contract | Relay support |
+|---|---|
+| Agent tool prompt / final result | Primary |
+| SendMessage resume / mid-run | Primary continue path |
+| Background + completion notify | Supported |
+| Fork / `/subtask` | Supported if host uses it |
+| Permission UI bubble | Orthogonal; do not suppress |
+| PermissionRequest / Notification | Optional hooks; worker pings stay stdout protocol |
+| SubagentStart / SubagentStop | Finish hooks always run on every return including pings |
+| Pre/PostToolUse (incl. on Agent) | Optional |
+| Agent teams mailbox / task list | Same stdout contract over team delivery |
+| Cross-session SendMessage | Supported; peer messages never carry user authority |
+| subagentStatusLine | UI only |
+
+## Hard stops
+
+- Never pattern-kill tmux. Destroy by exact session name only.
+- Never print credentials or OAuth tokens.
+- Never spawn nested Task/Agent from the cheap relay agent.
+- Prefer `tokenmaxxing-claude` / `tokenmaxxing-codex` agents over ad-hoc shells.
+
+See [references/ipc.md](references/ipc.md).

package/agent-plugin/skills/relay-session/references/ipc.md

@@ -0,0 +1,23 @@
+# Relay IPC checklist
+
+## Cursor
+
+- In: Task prompt, `/tokenmaxxing-claude`, `/tokenmaxxing-codex`
+- Out: final message with stdout protocol
+- Continue: Task resume after `relay decide` or `relay set-permission-mode`
+- Finish: `subagentStop` always (including permission-needed returns)
+- Optional: `subagentStart`, Task `preToolUse` / `postToolUse`
+- Not a permission channel: `UpdateCurrentStep`, transcripts
+
+## Claude Code
+
+- In: Agent tool prompt
+- Out: Agent final result with stdout protocol
+- Continue: SendMessage / next Agent turn after decide
+- Finish: `SubagentStop` always (including permission-needed returns)
+- Optional: `PermissionRequest` / `Notification` on main; worker pings still use relay stdout
+- UI only: `subagentStatusLine`
+
+## Finish-hook rule
+
+Permission park returns to main without faking a worker Stop. Worker Stop hooks still run when the worker actually finishes a turn and write additive `relay/turn-done/<session>` markers only.

package/agent-plugin/skills/safe-contribution/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: safe-contribution
+description: Safely change and ship tokenmaxxing (tests, PR window, Mac vs Linux skew, public-repo hygiene). Use when editing this repo, opening PRs, or verifying decision-path changes.
+---
+
+# Safe contribution
+
+## Verify
+
+- Default suite: `bun test`.
+- After decision-path changes, also run `bun test/e2e/swap-concurrency.ts` by hand (not part of `bun test`).
+- Hermetic CLI: `TOKENMAXXING_HOME=/tmp/xx-test bun run src/main.ts ...`.
+- Ask before any run that meters real quota (`status --force`, live-pool inference). Free `/usage` / plain status is fine.
+
+## Ship
+
+- Work on a branch; bump `package.json` in the same PR; open PR; wait the full review window; handle every review; merge; `gh release create v<version>`; verify npm publish.
+- Never push directly to main. npm trusted publishing is bound to workflow filename `ci.yml`.
+
+## Machine gotchas
+
+- The owner's Mac may run this working tree live. Do not kill sessions or supervisors without asking.
+- Linux boxes often run an older npm global: compare installed version before "works on Mac not Linux" debugging.
+- Repo is PUBLIC: no Slack IDs, device info, or secrets in commits, PRs, docs, or `.memory`.
+- Do not reintroduce banned patterns listed in `AGENTS.md` (Stop text-sniff failsafe, rejected statusline formats, old-state shims).
+
+See [references/ship.md](references/ship.md).

package/agent-plugin/skills/safe-contribution/references/ship.md

@@ -0,0 +1,5 @@
+# Ship and testing references
+
+- `AGENTS.md` (Release and CI, Testing, Do not reintroduce)
+- `.memory/shipping-pr-based.md`
+- `.memory/review-window-is-mandatory-full-length.md`