tokenmaxxing 1.21.0 → 1.23.0

package/DESIGN.md

@@ -72,7 +72,7 @@ Each terminal ran the supervisor, so each has its own child `claude` and its own
 
 - **`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. `CLAUDE_CONFIG_DIR` is SET by tokenmaxxing only for throwaway isolated stores like this one: the same harvest serves `auth`, and parked-account `/usage` sampling probes under `sample/<item>` the same way; an AMBIENT `CLAUDE_CONFIG_DIR` is refused by every CLI command and by the SDK's pooledSpawnEnv.
+- **`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. `CLAUDE_CONFIG_DIR` is SET by tokenmaxxing only for throwaway isolated stores like this one: the same harvest serves `auth`, and parked-account `/usage` sampling probes under `sample/<item>` the same way; an AMBIENT `CLAUDE_CONFIG_DIR` is refused by every CLI command.
 - **`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.
 - Both commands exercise `security` reads/writes interactively (where a macOS keychain ACL prompt is acceptable), so the first access never happens cold inside a headless hook.
 
@@ -118,7 +118,7 @@ The [wall policy](docs/content/docs/switching.mdx#the-wall) defines Layer 2 reco
 
 **v2:** projected-threshold pre-emption; a `UserPromptSubmit` guard that respawns *before* a turn starts when already over; Windows.
 
-**Shipped since (0.11.0):** a programmatic SDK surface (`src/sdk.ts`, the package's `exports["."]`) for pairing with the Claude Agent SDK - personal use across the owner's own pooled accounts. The Agent SDK reads credentials per subprocess spawn and has no statusLine, so the surface is boundary-driven: run the shared switch decision before a spawn (`ensureBestAccount`) and at Stop-hook turn boundaries (`stopHookCheck`), and hand the SDK a pinned real-claude path plus a full replacement env scrubbed of credential overrides (`pooledOptions`).
+**Removed (1.23.0):** the programmatic SDK surface, the stdio MCP server, and the Agent Plugin that shipped from 0.11.0 through 1.22.0. The CLI, the hooks, and the supervisor are the only surfaces.
 
 **Later:** tool-agnostic picker.
 

package/README.md

@@ -117,32 +117,6 @@ See [How switching decides](docs/content/docs/switching.mdx) for the policy and
 
 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`).
 
-## Pairing with the Claude Agent SDK
-
-For agents you build on the [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) against **your own** pooled accounts, `tokenmaxxing` is importable as a library (your agent app must run under Bun: tokenmaxxing ships TypeScript source and uses `bun:ffi`):
-
-```ts
-import { query } from "@anthropic-ai/claude-agent-sdk";
-import { ensureBestAccount, pooledOptions, stopHookCheck } from "tokenmaxxing";
-
-await ensureBestAccount();
-
-for await (const message of query({
-  prompt: "...",
-  options: {
-    ...pooledOptions(),
-    hooks: { Stop: [{ hooks: [stopHookCheck] }] },
-  },
-})) {
-}
-```
-
-The loop body receives the message stream; keep the session id from the init message if you want `resume` across swaps.
-
-The SDK reads credentials when it spawns the claude subprocess and has no statusLine, so none of the CLI-side supervisor machinery applies; the integration is boundary-driven instead. `ensureBestAccount()` runs the exact greedy decision the CLI hooks and timer run (screening bars, pace-pressure target, post-swap cooldown - all shared code); like them, it deliberately does nothing until the decision engages (the active session past `policy.greedySessionFloor`, or a bar crossed), so a fresh account rides instead of churning. `pooledOptions()` pins `pathToClaudeCodeExecutable` to the real claude binary and supplies a full replacement `env` with every ambient credential override (`ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, ...) scrubbed, so the subprocess resolves the pool's live credential and nothing else. The pooled surface requires the default Claude Code credential store: it fails fast if `CLAUDE_CONFIG_DIR` or `CLAUDE_SECURESTORAGE_CONFIG_DIR` is set in your app's environment, because a swap would write the live credential where those point while the spawned subprocess reads the default store. `stopHookCheck` re-runs the decision at turn boundaries; a swap it lands takes effect on the next subprocess spawn (it never yanks a mid-query token). If your app loads user settings (see the SDK's `settingSources`), the Stop hook `tokenmaxxing init` installed may already fire in SDK sessions too - `stopHookCheck` makes the check explicit and works when settings are restricted.
-
-This is for pooling **your own** subscription accounts in agents you run yourself - the same personal-use posture as the CLI. Anthropic does not allow third-party products to offer claude.ai login or rate limits, including agents built on the Agent SDK; don't ship this surface to third parties.
-
 ## Codex support
 
 The same pooling works for OpenAI's Codex CLI (your own ChatGPT-subscription accounts):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.21.0",
+  "version": "1.23.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",
@@ -13,13 +13,8 @@
   "bin": {
     "tokenmaxxing": "./src/main.ts"
   },
-  "exports": {
-    ".": "./src/sdk.ts",
-    "./package.json": "./package.json"
-  },
   "files": [
     "src",
-    "agent-plugin",
     "README.md",
     "DESIGN.md"
   ],
@@ -41,7 +36,6 @@
     "typescript": "^5.6.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0",
     "es-toolkit": "^1.49.0",
     "ky": "^2.0.2",
     "zod": "^4.4.3"

package/agent-plugin/bin/tokenmaxxing-mcp

@@ -1,7 +0,0 @@
-#!/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/mcp.json

@@ -1,10 +0,0 @@
-{
-  "$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

@@ -1,20 +0,0 @@
-{
-  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
-  "name": "tokenmaxxing",
-  "version": "1.21.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

@@ -1,23 +0,0 @@
----
-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

@@ -1,5 +0,0 @@
-# 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

@@ -1,27 +0,0 @@
----
-name: credentials-hygiene
-description: Credential and identity rules for tokenmaxxing (fetchTokenIdentity account-uuid identity, flock, no blob compare, never print secrets). Use before any auth, swap, or credential-touching change.
----
-
-# Credentials hygiene
-
-## Identity
-
-- Identity is the `accountUuid` that `fetchTokenIdentity` reports for a token (`GET /api/oauth/profile`), never the organization, never a stored label, and never a blob byte compare. Every seat of a Team plan shares one `organizationUuid`, so an org-keyed lookup collapses the seats onto one account. 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.
-- A refresh rotation revokes the previous access token at once, so refreshing any copy of a credential that is live elsewhere kills those sessions' token.
-
-## 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

@@ -1,6 +0,0 @@
-# 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

@@ -1,26 +0,0 @@
----
-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

@@ -1,5 +0,0 @@
-# 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

@@ -1,27 +0,0 @@
----
-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 --json` or `tokenmaxxing status --json` (alias `xx`) and parse the document. Never add `--ping`.
-
-## Hard stops
-
-- Do not run `status --ping` or bare `xx --ping`. 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 pings.
-- Hermetic agents: set `TOKENMAXXING_HOME` to a throwaway directory. That isolates state files only: `init`, `uninstall`, and the codex hook install still write settings.json, codex `hooks.json`, the shell rc, and the timer unit under `HOME`, so never run them from an agent.
-
-See [references/commands.md](references/commands.md).

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

@@ -1,9 +0,0 @@
-# Status and list commands
-
-- `tokenmaxxing` / `tokenmaxxing status`: sample and show bars; persists cached usage for the picker.
-- `tokenmaxxing status --ping [--count N]`: DENIED for agents without explicit user approval. Meters every account, or N random ones under `--count`.
-- `tokenmaxxing ls`: compact list.
-- `tokenmaxxing watch [seconds]`: live re-render (default 120), never `--ping`.
-- `--json` on any of these: one JSON document on stdout (`ok` mirrors the exit code); parse it instead of scraping the bars. `watch --json` prints one document per tick and never exits on its own.
-
-Docs: `docs/content/docs/commands.mdx`.

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

@@ -1,27 +0,0 @@
----
-name: safe-contribution
-description: Safely change and ship tokenmaxxing (verification without a test suite, PR window, Mac vs Linux skew, public-repo hygiene). Use when editing this repo, opening PRs, or verifying decision-path changes.
----
-
-# Safe contribution
-
-## Verify
-
-- The repo carries no test code and no comments (owner ruling 2026-09-02). Never add tests, a test script, or comments.
-- Verify with `bun run typecheck`, then hermetic CLI runs: `TOKENMAXXING_HOME=/tmp/xx-test bun run src/main.ts ...` (for decision-path changes, write accounts.json, usage.json, config.json, and a claude.json under that root and run `check`; point `TOKENMAXXING_KEYCHAIN_SERVICE` and `TOKENMAXXING_KEYCHAIN_ACCOUNT` at throwaway names and `TOKENMAXXING_CLAUDE_JSON` at that claude.json, because the CLI resolves claude.json from HOME, not from `TOKENMAXXING_HOME`).
-- Ask before any run that meters real quota (`status --ping`, live-pool inference). Free `/usage` / plain status is fine.
-
-## Ship
-
-- Work on a branch; bump `package.json` and `agent-plugin/plugin.json` to the same version in the same PR; open PR; wait the full review window; handle every review; merge; `gh release create v<version>`; verify npm publish.
-- A PR that changes no packed file skips the bump and the release, and merging it is shipping it. Check membership with `npm pack --dry-run`, not the `files` array: the tarball is `src`, `agent-plugin`, `README.md`, `DESIGN.md`, `LICENSE`, and `package.json`, the last two always packed though `files` never names them. So a `docs/`, `.memory/`, or AGENTS.md change is exempt, while a LICENSE or metadata change is not. Everything else, the full review window included, still applies.
-- 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

@@ -1,5 +0,0 @@
-# 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`

package/agent-plugin/skills/sdk-pairing/SKILL.md

@@ -1,34 +0,0 @@
----
-name: sdk-pairing
-description: Pair tokenmaxxing with the Claude Agent SDK (ensureBestAccount, pooledOptions, stopHookCheck). Use when building or debugging Bun agents that spawn Claude through the pooled credential store.
----
-
-# SDK pairing
-
-Import from the package root (`tokenmaxxing` → `src/sdk.ts`). Bun only.
-
-```ts
-import { query } from "@anthropic-ai/claude-agent-sdk";
-import { ensureBestAccount, pooledOptions, stopHookCheck } from "tokenmaxxing";
-
-await ensureBestAccount();
-for await (const message of query({
-  prompt: "...",
-  options: {
-    ...pooledOptions(),
-    hooks: { Stop: [{ hooks: [stopHookCheck] }] },
-  },
-})) {
-}
-```
-
-The loop body receives the message stream; keep the session id from the init message for `resume` across swaps.
-
-## Rules
-
-- Call `ensureBestAccount()` before each `query()` spawn (no mid-query hot-swap).
-- `pooledOptions()` pins the real claude binary and a full replacement env with credential overrides scrubbed. It throws if `CLAUDE_CONFIG_DIR` or `CLAUDE_SECURESTORAGE_CONFIG_DIR` is set.
-- `stopHookCheck` re-decides at turn boundaries; errors are swallowed so a broken check does not abort the turn.
-- Own-accounts only (see terms docs). Offering pooled subscription logins to third parties is a ToS problem.
-
-See [references/sdk.md](references/sdk.md).

package/agent-plugin/skills/sdk-pairing/references/sdk.md

@@ -1,6 +0,0 @@
-# SDK references
-
-- `src/sdk.ts` (self-documenting header)
-- `docs/content/docs/sdk.mdx`
-- `docs/content/docs/terms.mdx`
-- `.memory/agent-sdk-auth-surface.md`

package/agent-plugin/skills/switching-policy/SKILL.md

@@ -1,34 +0,0 @@
----
-name: switching-policy
-description: Explain and apply tokenmaxxing switch policy (greedy vs hard path, pace pressure, Layer 2 wall squeeze Claude-only, model-family matching). Use before pool_switch, pool_check, or when changing thresholds.
----
-
-# Switching policy
-
-## Vocabulary
-
-- **Engaged**: session used >= `policy.greedySessionFloor` (default 80) or any screening bar crossed.
-- **GREEDY path** permits lateral moves only within the incumbent organization and retains `greedySwapMargin` hysteresis.
-- **HARD path** starts at a crossed screening bar and may cross organizations, with Layer 2 as its fallback.
-- **Organization preference** requires measured headroom in session, aggregate weekly and gated model windows under the [policy](references/policy.md).
-- **Verification** attempts at most two stale candidates per evaluation, with a 12-second deadline covering identity reads and the CLI for each candidate.
-- **Probe results** are persisted and re-ranked, while screening exhaustion remains eligible for the wall squeeze and reset selection.
-- **Unavailable verification** leaves cached figures in force, and verification never spends a parked refresh grant.
-- **Manual switch** retains pure pace ranking with no organization preference or incumbent margin.
-- **Pace pressure**: remaining weekly percent / time to weekly reset (highest first). Not most-remaining.
-- **Effective bars**: `effectiveBars(cfg, pool)` = the active rung of the 5h ladder (`thresholds.session`, default `[90]`, a single rung: the lowest rung some pooled account, the current one included, still clears) and the weekly bar, each minus `policy.projectionMargin`. Trigger and screening must share these bars or swaps ping-pong. Codex reads `terminalBars(cfg)`, the top rung only. The check cadence is capped one band per rung climbed, and every band is a multiple of the tick `policy.checkIntervalMs` (default 60000).
-
-## Layer 2 (Claude only)
-
-When the hard path finds no usable target, judge against the wall (`hardThresholds` minus margin). Under-wall seat HOLDS; walled seat swaps to best under-wall sibling. Codex has no Layer 2 last-drop swap (cannot hot-adopt).
-
-## Model matching
-
-Match model families by exact token after splitting id/display on spaces, dots, and hyphens (`familyTokens` / `matchedFamily` in `src/lib/usage.ts`). Never exact full display strings (names drift: "Fable" / "Fable 5"). Unmeasured usage is unknown and ranks last, never 0 / first. Per-model weekly caps: Sonnet and Fable exist; only Fable gates a switch by default (`policy.switchModels`).
-
-## Agent actions
-
-- Explain with this skill; mutate only via MCP `pool_switch` / `pool_check` with user approval, `confirm=true`, and `TOKENMAXXING_AGENT_MUTATIONS=1`.
-- Do not reintroduce Stop-hook text-sniffing limit failsafes.
-
-See [references/policy.md](references/policy.md).

package/agent-plugin/skills/switching-policy/references/policy.md

@@ -1,9 +0,0 @@
-# Policy sources
-
-- `docs/content/docs/switching.mdx`
-- `src/lib/decide.ts`, `src/lib/picker.ts`
-- `.cursor/rules/switch-verification.md`
-
-Automatic organization preference requires session usage below `greedySessionFloor` and more than `max(1, session bar - greedySessionFloor)` points below every applicable bar.
-
-The exact policy, defaults, verification limits and manual-switch behavior live in `docs/content/docs/switching.mdx`.

package/src/entries/mcp.ts

@@ -1,277 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { cmdLs } from "../cli/ls.ts";
-import { cmdStatus } from "../cli/status.ts";
-import { cmdDoctor } from "../cli/doctor.ts";
-import { cmdConfig } from "../cli/config.ts";
-import { cmdSwitch } from "../cli/switch.ts";
-import { cmdCodexSwitch } from "../cli/codexswitch.ts";
-import { cmdCheck } from "../cli/check.ts";
-
-const MUTATIONS_ENV = "TOKENMAXXING_AGENT_MUTATIONS";
-const PACKAGE_ROOT = join(import.meta.dir, "../..");
-
-function packageVersion(): string {
-  try {
-    const raw = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")) as { version?: string };
-    return raw.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
-
-export function refuseAmbientStoreEnv(): string | null {
-  const nonEmpty = (v: string | undefined) => (v != null && v !== "" ? v : null);
-  return nonEmpty(process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR) ?? nonEmpty(process.env.CLAUDE_CONFIG_DIR);
-}
-
-export function scrubSecrets(text: string): string {
-  return text
-    .replace(/\b(Bearer\s+)[A-Za-z0-9._\-+/=]+/gi, "$1[redacted]")
-    .replace(/\b(sk-ant-[A-Za-z0-9_-]+)\b/g, "[redacted]")
-    .replace(/\b(accessToken|refreshToken|claudeAiOauth)\b\s*[:=]\s*["']?[^"'}\s,]+/gi, "$1=[redacted]");
-}
-
-type CaptureResult = { code: number; stdout: string; stderr: string };
-
-let captureChain: Promise<unknown> = Promise.resolve();
-
-export async function captureCli(run: () => number | Promise<number>): Promise<CaptureResult> {
-  const job = async (): Promise<CaptureResult> => {
-    const out: string[] = [];
-    const err: string[] = [];
-    const joinArgs = (args: unknown[]) => args.map((a) => (typeof a === "string" ? a : String(a))).join(" ");
-    const log = console.log;
-    const error = console.error;
-    console.log = (...args: unknown[]) => { out.push(joinArgs(args)); };
-    console.error = (...args: unknown[]) => { err.push(joinArgs(args)); };
-    try {
-      const code = await run();
-      return { code, stdout: out.join("\n"), stderr: err.join("\n") };
-    } finally {
-      console.log = log;
-      console.error = error;
-    }
-  };
-  const next = captureChain.then(job, job);
-  captureChain = next.then(
-    () => undefined,
-    () => undefined,
-  );
-  return next;
-}
-
-function textResult(input: { text: string; isError?: boolean }) {
-  return {
-    content: [{ type: "text" as const, text: scrubSecrets(input.text) }],
-    ...(input.isError ? { isError: true } : {}),
-  };
-}
-
-function formatCapture(cap: CaptureResult): string {
-  const parts: string[] = [];
-  if (cap.stdout) parts.push(cap.stdout);
-  if (cap.stderr) parts.push(cap.stderr);
-  parts.push(`exit ${cap.code}`);
-  return parts.join("\n").trimEnd();
-}
-
-export function mutationsEnabled(): boolean {
-  return process.env[MUTATIONS_ENV] === "1";
-}
-
-function mutationDenied(confirm: boolean): string | null {
-  if (!confirm) {
-    return `Mutating tools require confirm=true. Also set ${MUTATIONS_ENV}=1 in the MCP server environment after the user approves.`;
-  }
-  if (!mutationsEnabled()) {
-    return `Mutations are disabled. Set ${MUTATIONS_ENV}=1 in the MCP server environment only after the user explicitly approves a pool mutation.`;
-  }
-  return null;
-}
-
-const HELP_TEXT = `tokenmaxxing agent MCP
-
-Read tools (always available):
-  pool_ls       list pooled Claude and Codex accounts (labels/status only)
-  pool_status   sample usage bars (free /usage path; never --ping)
-  doctor        verify install health (labels/status only)
-  config_get    read effective config, or one key when provided
-  help          this catalog
-
-Mutating tools (confirm=true AND ${MUTATIONS_ENV}=1):
-  pool_switch   Claude greedy/forced switch, or Codex when codex=true
-  pool_check    one evaluate-and-maybe-swap pass
-  config_set    write a config.json override
-  config_unset  remove a config.json override
-
-Hard deny (no tools):
-  status --ping / metered pings
-  init / add / auth / rm / uninstall
-  credential blobs or token values
-  killing sessions or supervisors
-
-Prefer these tools over raw shell for pool ops. Honor TOKENMAXXING_HOME for hermetic use.
-`;
-
-export function createTokenmaxxingMcpServer(): McpServer {
-  const server = new McpServer({
-    name: "tokenmaxxing",
-    version: packageVersion(),
-  });
-
-  server.registerTool(
-    "help",
-    {
-      description: "Catalog of tokenmaxxing MCP tools and hard safety rules. Use when deciding which pool tool to call.",
-      inputSchema: {},
-    },
-    async () => textResult({ text: HELP_TEXT }),
-  );
-
-  server.registerTool(
-    "pool_ls",
-    {
-      description: "List pooled Claude and Codex accounts with active and needs-reauth flags. Labels and status only; never credential material.",
-      inputSchema: {},
-    },
-    async () => {
-      const cap = await captureCli(() => cmdLs());
-      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
-    },
-  );
-
-  server.registerTool(
-    "pool_status",
-    {
-      description: "Show pool usage bars via the free /usage path. Never opens 5h windows. Do not request --ping; that tool does not exist.",
-      inputSchema: {},
-    },
-    async () => {
-      const cap = await captureCli(() => cmdStatus());
-      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
-    },
-  );
-
-  server.registerTool(
-    "doctor",
-    {
-      description: "Verify supervisor, hooks, timer, and credential identity health. Reports labels and pass/fail only; never returns credential blobs.",
-      inputSchema: {},
-    },
-    async () => {
-      const cap = await captureCli(() => cmdDoctor());
-      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
-    },
-  );
-
-  server.registerTool(
-    "config_get",
-    {
-      description: "Read effective config with sources, or one dotted key when key is set (e.g. thresholds.session).",
-      inputSchema: {
-        key: z.string().optional().describe("Optional dotted config key; omit for the full effective table"),
-      },
-    },
-    async ({ key }) => {
-      const args = key ? ["get", key] : [];
-      const cap = await captureCli(() => cmdConfig(args));
-      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
-    },
-  );
-
-  server.registerTool(
-    "pool_switch",
-    {
-      description: "Switch the Claude pool (or Codex when codex=true). Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1. Hot-swaps live Claude; Codex takes effect on next start.",
-      inputSchema: {
-        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
-        selector: z.string().optional().describe("Optional account selector; omit for greedy best"),
-        codex: z.boolean().optional().describe("When true, run the Codex pool switch instead"),
-      },
-    },
-    async ({ confirm, selector, codex }) => {
-      const denied = mutationDenied(confirm);
-      if (denied) return textResult({ text: denied, isError: true });
-      const cap = await captureCli(() => (codex ? cmdCodexSwitch(selector) : cmdSwitch(selector)));
-      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
-    },
-  );
-
-  server.registerTool(
-    "pool_check",
-    {
-      description: "Run one evaluate-and-maybe-swap pass (the periodic timer path). Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1.",
-      inputSchema: {
-        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
-      },
-    },
-    async ({ confirm }) => {
-      const denied = mutationDenied(confirm);
-      if (denied) return textResult({ text: denied, isError: true });
-      const cap = await captureCli(() => cmdCheck());
-      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
-    },
-  );
-
-  server.registerTool(
-    "config_set",
-    {
-      description: "Write a config.json override. Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1.",
-      inputSchema: {
-        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
-        key: z.string().describe("Dotted config key"),
-        value: z.string().describe("JSON or literal string value"),
-      },
-    },
-    async ({ confirm, key, value }) => {
-      const denied = mutationDenied(confirm);
-      if (denied) return textResult({ text: denied, isError: true });
-      const cap = await captureCli(() => cmdConfig(["set", key, value]));
-      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
-    },
-  );
-
-  server.registerTool(
-    "config_unset",
-    {
-      description: "Remove a config.json override. Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1.",
-      inputSchema: {
-        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
-        key: z.string().describe("Dotted config key"),
-      },
-    },
-    async ({ confirm, key }) => {
-      const denied = mutationDenied(confirm);
-      if (denied) return textResult({ text: denied, isError: true });
-      const cap = await captureCli(() => cmdConfig(["unset", key]));
-      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
-    },
-  );
-
-  return server;
-}
-
-export async function main(): Promise<void> {
-  const ambient = refuseAmbientStoreEnv();
-  if (ambient != null) {
-    console.error(
-      `CLAUDE_CONFIG_DIR / CLAUDE_SECURESTORAGE_CONFIG_DIR is set (${ambient}): the pooled MCP surface requires the default Claude Code credential store. Unset it and retry.`,
-    );
-    process.exit(1);
-  }
-  const server = createTokenmaxxingMcpServer();
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error("tokenmaxxing MCP server running on stdio");
-}
-
-if (import.meta.main) {
-  main().catch((e) => {
-    console.error(e instanceof Error ? e.message : String(e));
-    process.exit(1);
-  });
-}

package/src/sdk.ts

@@ -1,55 +0,0 @@
-import { z } from "zod";
-import { UNMANAGED_ENV, resolveRealClaude } from "./lib/claudebin.ts";
-import { evaluateAndMaybeSwap, type SwapDecision } from "./lib/decide.ts";
-import { CRED_ENV_OVERRIDES } from "./lib/usage.ts";
-import { log } from "./lib/log.ts";
-
-export { evaluateAndMaybeSwap };
-export type { SwapDecision };
-
-export async function ensureBestAccount(now = Date.now()): Promise<SwapDecision> {
-  return evaluateAndMaybeSwap(now, false);
-}
-
-export function claudeExecutablePath(): string {
-  return resolveRealClaude();
-}
-
-const AMBIENT_STORE_VARS = ["CLAUDE_SECURESTORAGE_CONFIG_DIR", "CLAUDE_CONFIG_DIR"] as const;
-
-export function pooledSpawnEnv(): Record<string, string> {
-  for (const k of AMBIENT_STORE_VARS) {
-    if (process.env[k]) {
-      throw new Error(
-        `${k} is set: the pooled SDK surface requires the default Claude Code credential store (a swap writes the live credential where ${k} points, while the spawned subprocess reads the default store). Unset it in the process running tokenmaxxing.`,
-      );
-    }
-  }
-  const env: Record<string, string> = { ...process.env, [UNMANAGED_ENV]: "1" };
-  for (const k of CRED_ENV_OVERRIDES) delete env[k];
-  return env;
-}
-
-const PooledOptionsSchema = z.object({
-  pathToClaudeCodeExecutable: z.string(),
-  env: z.record(z.string(), z.string()),
-});
-export type PooledOptions = z.infer<typeof PooledOptionsSchema>;
-
-export function pooledOptions(): PooledOptions {
-  return PooledOptionsSchema.parse({
-    pathToClaudeCodeExecutable: claudeExecutablePath(),
-    env: pooledSpawnEnv(),
-  });
-}
-
-export async function stopHookCheck(): Promise<Record<string, never>> {
-  try {
-    await evaluateAndMaybeSwap(Date.now(), false);
-  } catch (e) {
-    const err = e instanceof Error ? e.message : String(e);
-    console.error(`tokenmaxxing: switch check failed at turn boundary: ${err}`);
-    log("sdk.stop_error", { err });
-  }
-  return {};
-}