tokenmaxxing 0.19.1 → 0.21.0

package/src/lib/types.ts

@@ -7,7 +7,7 @@ import { z } from "zod";
 
 /** OAuth object inside the keychain blob (`claudeAiOauth`). Loose: preserve any
  *  extra fields claude may add so a harvest→install round-trip is lossless. */
-export const OAuthCredsSchema = z.looseObject({
+const OAuthCredsSchema = z.looseObject({
   accessToken: z.string(),
   refreshToken: z.string(),
   expiresAt: z.number(),
@@ -22,7 +22,6 @@ export type OAuthCreds = z.infer<typeof OAuthCredsSchema>;
  *  sibling state (e.g. per-MCP-server OAuth tokens), which we must preserve when
  *  swapping - we only ever replace `claudeAiOauth`. */
 export const CredentialBlobSchema = z.looseObject({ claudeAiOauth: OAuthCredsSchema });
-export type CredentialBlob = z.infer<typeof CredentialBlobSchema>;
 
 /** The `oauthAccount` identity object in ~/.claude.json. Loose: preserve every
  *  key so we can reinstall it verbatim on activation. Only the three ids are
@@ -48,13 +47,13 @@ export const UsageWindowSchema = z.object({
 });
 export type UsageWindow = z.infer<typeof UsageWindowSchema>;
 
-export const UsageWindowsSchema = z.object({
+const UsageWindowsSchema = z.object({
   fiveHour: UsageWindowSchema,
   sevenDay: UsageWindowSchema,
 });
 export type UsageWindows = z.infer<typeof UsageWindowsSchema>;
 
-export const ModelInfoSchema = z.object({ id: z.string(), display: z.string() });
+const ModelInfoSchema = z.object({ id: z.string(), display: z.string() });
 export type ModelInfo = z.infer<typeof ModelInfoSchema>;
 
 /** usage.json - written by the statusLine shim, read by the Stop hook. Carries
@@ -73,6 +72,12 @@ export const ModelUsageStateSchema = z.object({
   perModel: z.record(z.string(), UsageWindowSchema).default({}),
   org: z.string().nullable(),
   ts: z.number(),
+  /** when the rows were actually MEASURED. `ts` is the write time and drives
+   *  the probe-TTL anti-storm, so a failed probe re-stamps it while carrying
+   *  the OLD rows forward - dating those rows by ts rolled the null-reset
+   *  self-bound forward on every failed probe (closing-review catch). Absent
+   *  on records predating this field: readers fall back to ts. */
+  sampledAt: z.number().optional(),
 });
 export type ModelUsageState = z.infer<typeof ModelUsageStateSchema>;
 
@@ -87,9 +92,17 @@ export const AccountSchema = z.object({
   addedAt: z.string(),
   lastUsage: UsageWindowsSchema.optional(),
   lastPerModel: z.record(z.string(), UsageWindowSchema).optional(),
-  /** epoch ms of the sample behind lastUsage/lastPerModel. Their resetsAt
-   *  values are absolute epochs (UTC-anchored), so even an old snapshot still
-   *  resolves to correct resets - display it as a dated cache, never discard. */
+  /** epoch ms of the sample behind lastPerModel SPECIFICALLY: the aggregate
+   *  stamp (lastUsageAt) advances on every engaged evaluation while the
+   *  per-model rows refresh only when a gated family is measured, so dating
+   *  the rows by lastUsageAt inflated the null-reset self-bound by days
+   *  (closing-review catch). Absent on records predating this field: readers
+   *  fall back to lastUsageAt, the previous (over-)approximation. */
+  lastPerModelAt: z.number().optional(),
+  /** epoch ms of the sample behind the AGGREGATE lastUsage windows (per-model
+   *  rows date by lastPerModelAt above). resetsAt values are absolute epochs
+   *  (UTC-anchored), so even an old snapshot still resolves to correct
+   *  resets - display it as a dated cache, never discard. */
   lastUsageAt: z.number().optional(),
   needsReauth: z.boolean().optional(),
   subscriptionType: z.string().optional(),
@@ -120,43 +133,61 @@ export type AccountsIndex = z.infer<typeof AccountsIndexSchema>;
  *  trigger is the greedy pace-pressure convergence (policy.greedySessionFloor). */
 export const ThresholdsSchema = z.object({
   /** 5h session window. */
-  session: z.number(),
+  session: z.number().min(0).max(100),
   /** 7-day aggregate AND per-model weekly caps. */
-  weekly: z.number(),
+  weekly: z.number().min(0).max(100),
 });
 export type Thresholds = z.infer<typeof ThresholdsSchema>;
 
-export const ConfigSchema = z.object({
-  thresholds: ThresholdsSchema,
-  claudeBin: z.string(),
-  /** the real codex binary (empty = resolve from PATH); pinned by `init --codex`. */
-  codexBin: z.string(),
-  policy: z.object({
-    projectionMargin: z.number(),
-    /** session-used % at which the greedy convergence engages: from here on,
-     *  every evaluation swaps to the usable account furthest behind its weekly
-     *  pace whenever that beats the current one (idempotent; current keeps its
-     *  seat on ties). Below the floor a fresh session rides its account. */
-    greedySessionFloor: z.number(),
-    /** models whose PER-MODEL weekly cap should trigger a switch (display names, lowercased). */
-    switchModels: z.array(z.string()),
-    /** how long a `/usage` per-model poll stays fresh before we re-poll (ms). */
-    usagePollTtlMs: z.number(),
-    /** when every account is depleted, auto-wait for a reset only if it is within this window (ms). */
-    maxWaitMs: z.number(),
-  }),
-});
+export const ConfigSchema = z
+  .object({
+    thresholds: ThresholdsSchema,
+    claudeBin: z.string(),
+    /** the real codex binary (empty = resolve from PATH); pinned by `init --codex`. */
+    codexBin: z.string(),
+    policy: z.object({
+      /** percent margin subtracted from every bar (effectiveBars); above 100 the
+       *  effective bars go negative and everything reads exhausted, so bounded. */
+      projectionMargin: z.number().min(0).max(100),
+      /** session-used % at which the greedy convergence engages: from here on,
+       *  every evaluation swaps to the usable account furthest behind its weekly
+       *  pace whenever that beats the current one (idempotent; current keeps its
+       *  seat on ties). Below the floor a fresh session rides its account. */
+      greedySessionFloor: z.number().min(0).max(100),
+      /** models whose PER-MODEL weekly cap should trigger a switch (display names, lowercased). */
+      switchModels: z.array(z.string()),
+      /** how long a `/usage` per-model poll stays fresh before we re-poll (ms). */
+      usagePollTtlMs: z.number().int().positive(),
+      /** when every account is depleted, auto-wait for a reset only if it is within this window (ms). */
+      maxWaitMs: z.number().int().positive(),
+    }),
+  })
+  // Cross-field (review catch, PR #31): effectiveBars subtracts the margin
+  // from each threshold, and a bar at or below zero makes EVERY nonnegative
+  // usage percentage read as exhausted - the whole pool looks depleted and the
+  // switch path churns. Per-field bounds alone cannot see this.
+  .refine((cfg) => cfg.policy.projectionMargin < Math.min(cfg.thresholds.session, cfg.thresholds.weekly), {
+    message: "policy.projectionMargin must be strictly below both thresholds (effectiveBars would hit zero and every account would read as exhausted)",
+  });
 export type Config = z.infer<typeof ConfigSchema>;
 
-/** The hook -> supervisor respawn marker at respawn/<session-id>. Written only
- *  for a depleted-pool wait (plain swaps adopt in place, no respawn). */
+/** The hook -> supervisor respawn marker. Written only for a depleted-pool
+ *  wait (plain swaps adopt in place, no respawn). The marker FILE is keyed by
+ *  the supervisor's PINNED session id (the path it watches - stable for the
+ *  process's whole life), while `sessionId` carries the CURRENT transcript to
+ *  resume: after /clear claude mints a new session id, and keying the file by
+ *  the stdin sid orphaned every marker while the anticipatory pre-park still
+ *  fired (closing-review HIGH catch; the codex marker was immune by exactly
+ *  this construction). */
 export const RespawnMarkerSchema = z.object({
   account: z.string(),
   ts: z.number(),
   /** the supervisor waits until this epoch ms before relaunching. */
   waitUntil: z.number(),
+  /** the transcript to `--resume`: the hook-stdin session id, which drifts
+   *  from the pinned id after /clear. */
+  sessionId: z.string(),
 });
-export type RespawnMarker = z.infer<typeof RespawnMarkerSchema>;
 
 /** rate_limits + model as they appear in statusLine stdin (epoch-seconds resets). */
 export const RateLimitsStdinSchema = z.looseObject({
@@ -227,7 +258,6 @@ export const RefreshResponseSchema = z.looseObject({
   scope: z.string().optional(),
   token_type: z.string().optional(),
 });
-export type RefreshResponse = z.infer<typeof RefreshResponseSchema>;
 
 /** Success body of GET /api/oauth/claude_cli/roles - the org a token ACTUALLY
  *  belongs to, independent of any stored label. */
@@ -242,13 +272,12 @@ export type RolesResponse = z.infer<typeof RolesResponseSchema>;
 /** `tokens` inside $CODEX_HOME/auth.json (verified against a live 0.144.4
  *  auth.json). Loose: preserve unknown siblings so a harvest and reinstall
  *  round-trip is lossless. */
-export const CodexTokensSchema = z.looseObject({
+const CodexTokensSchema = z.looseObject({
   id_token: z.string(),
   access_token: z.string(),
   refresh_token: z.string(),
   account_id: z.string().optional(),
 });
-export type CodexTokens = z.infer<typeof CodexTokensSchema>;
 
 /** The whole auth.json. Loose: auth_mode, OPENAI_API_KEY (may be null), and
  *  future siblings ride along verbatim. */
@@ -263,7 +292,7 @@ export type CodexAuthJson = z.infer<typeof CodexAuthJsonSchema>;
  *  duration-driven (the weekly window is PRIMARY on plans whose 5h window was
  *  removed in July 2026), so classification must go by windowSeconds, never
  *  by primary/secondary position. */
-export const CodexWindowSchema = z.object({
+const CodexWindowSchema = z.object({
   usedPercentage: z.number(),
   resetsAt: z.number().nullable(),
   windowSeconds: z.number().nullable(),
@@ -322,4 +351,17 @@ export const CodexRespawnMarkerSchema = z.object({
   sessionId: z.string().nullable(),
   ts: z.number(),
 });
-export type CodexRespawnMarker = z.infer<typeof CodexRespawnMarkerSchema>;
+
+/** A cross-session reconcile signal (owner decisions 2026-07-20): the
+ *  deciding actor saw the addressed supervisor's session running on this
+ *  pooled NON-LIVE account - healthy or not (a non-live session cannot
+ *  refresh cross-account and wedges at token expiry) - while the live seat
+ *  is usable. The session's OWN Stop hook consumes it at its next turn
+ *  boundary - the only safe respawn point - promoting it into a respawn
+ *  marker with the session id its stdin alone carries. `accountId` doubles
+ *  as the staleness guard: a session that already moved accounts drops the
+ *  signal instead of respawning. */
+export const CodexReconcileMarkerSchema = z.object({
+  accountId: z.string(),
+  ts: z.number(),
+});

package/src/lib/usage.ts

@@ -9,8 +9,11 @@ import { join } from "node:path";
 import { delay } from "es-toolkit";
 import { z } from "zod";
 import { MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, resolveRealClaude } from "./claudebin.ts";
+import { readOAuthAccount } from "./claudejson.ts";
+import { withLock } from "./lock.ts";
 import { log } from "./log.ts";
 import { paths } from "./paths.ts";
+import { loadUsage, writeUsage } from "./state.ts";
 import { RateLimitsStdinSchema, UsageWindowSchema, type ModelInfo, type UsageWindow, type UsageWindows } from "./types.ts";
 
 /** Normalize a resets_at value (epoch s, epoch ms, or ISO string) to epoch ms. */
@@ -29,17 +32,19 @@ export function normalizeResetsAt(v: unknown): number | null {
   return null;
 }
 
-const win = (w?: { used_percentage: number; resets_at?: number | null }): UsageWindow => ({
-  usedPercentage: w?.used_percentage ?? 0,
-  resetsAt: normalizeResetsAt(w?.resets_at),
+const win = (w: { used_percentage: number; resets_at?: number | null }): UsageWindow => ({
+  usedPercentage: w.used_percentage,
+  resetsAt: normalizeResetsAt(w.resets_at),
 });
 
-/** Extract the two AGGREGATE windows from statusLine stdin. null if absent. */
+/** Extract the two AGGREGATE windows from statusLine stdin. null if absent.
+ *  All-or-nothing on the aggregates (mirrors the /usage parser): fabricating
+ *  0% for a missing window would make unmeasured read as safe. */
 export function parseStatusLineStdin(obj: unknown): UsageWindows | null {
   const parsed = RateLimitsStdinSchema.safeParse(obj);
   if (!parsed.success) return null;
   const rl = parsed.data.rate_limits;
-  if (!rl || (!rl.five_hour && !rl.seven_day)) return null;
+  if (!rl?.five_hour || !rl.seven_day) return null;
   return { fiveHour: win(rl.five_hour), sevenDay: win(rl.seven_day) };
 }
 
@@ -153,11 +158,105 @@ export function parseResetClock(clock: string, now = Date.now()): number | null
   return best;
 }
 
+/** Compact time-until-reset: the largest unit only ("6d", "2h", "45m"),
+ *  floored to "1m" so a live window never reads as zero, and "" once the reset
+ *  has passed (the window is simply empty again). Non-empty output always ends
+ *  in a unit letter, so the statusLine's digit-leading used-percent glued
+ *  after it stays parseable. Lives here (not cli/render.ts) so headless lib
+ *  consumers stay off the terminal-rendering module. */
+export function fmtResetShort(epochMs: number | null | undefined, now = Date.now()): string {
+  if (epochMs == null) return "";
+  const dsec = Math.round((epochMs - now) / 1000);
+  if (dsec <= 0) return "";
+  const d = Math.floor(dsec / 86400);
+  const h = Math.floor((dsec % 86400) / 3600);
+  const m = Math.floor((dsec % 3600) / 60);
+  if (d > 0) return `${d}d`;
+  if (h > 0) return `${h}h`;
+  return `${Math.max(m, 1)}m`;
+}
+
+/** The reset epoch a limit result announces ("Claude AI usage limit
+ *  reached|<epoch>", 10-digit seconds or 13-digit ms). Structural scan, no
+ *  regex: everything after the pipe up to the first non-digit. Null when the
+ *  text is a phrase-only limit with no epoch. */
+export function parseUsageLimitEpoch(input: { text: string }): number | null {
+  const marker = "usage limit reached|";
+  const at = input.text.toLowerCase().indexOf(marker);
+  if (at < 0) return null;
+  let digits = "";
+  for (const ch of input.text.slice(at + marker.length)) {
+    if (ch < "0" || ch > "9") break;
+    digits += ch;
+  }
+  // exactly the two real encodings: 10-digit seconds or 13-digit ms. An 11-
+  // or 12-digit run is malformed and must stay an unknown reset, not become
+  // a far-future one via the seconds branch.
+  if (digits.length !== 10 && digits.length !== 13) return null;
+  const n = Number(digits);
+  return digits.length === 13 ? n : n * 1000;
+}
+
+/**
+ * Persist a limit observed in a turn RESULT into usage.json so the next
+ * decision sees the depleted account immediately. A headless serve/SDK process
+ * has no statusLine tee and `loadFreshSnapshots` skips re-probing inside the
+ * poll TTL (and `/usage` is fail-silent against the just-limited active token
+ * anyway), so without this write a post-limit retry re-decides off the stale
+ * pre-limit snapshot and respawns the same depleted account. The session
+ * window is stamped 100% with the announced reset: whichever window actually
+ * tripped, the account is unusable until then, and the hard path swaps away.
+ * `org` is the identity captured AT THE SPAWN BOUNDARY of the turn that
+ * failed; the write happens only when that identity is known and still live,
+ * so a concurrent thread's mid-turn swap can never get its fresh account
+ * stamped depleted by this turn's failure (review catch, PR #18). Without a
+ * same-org prior snapshot there is nothing safe to write (a synthetic weekly
+ * value would flow into `account.lastUsage` and poison the picker's ranking;
+ * unmeasured must not look fresh), so the observation is dropped and the
+ * retry stays merely bounded.
+ *
+ * INTENTIONAL TRADEOFF (closing-review critic gap, 2026-07-20): the statusline
+ * tee (writeUsage) is deliberately UNLOCKED - the shim stays off flock/oauth -
+ * so it can interleave with this locked check-then-write. Last-writer-wins is
+ * semantically safe in both orderings: a tee landing after this stamp replaces
+ * it with a FRESHER live measurement (truth wins), and this stamp landing
+ * after a tee replaces pre-limit figures with the observed limit the server
+ * just enforced (also truth). Neither writer can write a stale fabrication
+ * over the other; locking the shim to close the interleave would buy nothing.
+ */
+export async function recordObservedLimit(input: { text: string; now: number; org: string | null }): Promise<void> {
+  if (!input.org) return;
+  // the whole check-then-write runs under the swap flock: a concurrent
+  // performSwap clears the snapshots and flips the live org, and a stale
+  // depleted write must not land for the wrong org right after that
+  // (review catch, PR #18).
+  await withLock(paths.lockFile, () => {
+    const live = readOAuthAccount()?.organizationUuid ?? null;
+    if (live !== input.org) return;
+    const prior = loadUsage();
+    if (!prior || prior.org !== input.org) return;
+    const resetsAt = parseUsageLimitEpoch({ text: input.text });
+    // a weekly-phrased limit exhausts the WEEKLY window: stamping only the 5h
+    // window would let the picker re-seat this account in 5h while the weekly
+    // cap stays dead for days (review catch, PR #18). Unknown-reset blocked
+    // windows self-bound at the window's own duration either way.
+    const weekly = input.text.toLowerCase().includes("weekly");
+    writeUsage({
+      fiveHour: weekly ? prior.fiveHour : { usedPercentage: 100, resetsAt },
+      sevenDay: weekly ? { usedPercentage: 100, resetsAt } : prior.sevenDay,
+      org: input.org,
+      ts: input.now,
+      model: prior.model,
+    });
+    log("usage.observed_limit", { resetsAt, weekly });
+  });
+}
+
 /**
  * Parse `claude -p '/usage'` .result text into all three limit kinds:
- *   Current session: N% used · resets <clock>      → session (5h)
- *   Current week (all models): N% used · resets ...   → weekAll (7d aggregate)
- *   Current week (<Model>): N% used · resets ...      → perModel[<Model>]
+ *   Current session: N% used ... resets <clock>        → session (5h)
+ *   Current week (all models): N% used ... resets ...  → weekAll (7d aggregate)
+ *   Current week (<Model>): N% used ... resets ...     → perModel[<Model>]
  */
 export function parseUsageTextFull(text: string, now = Date.now()): FullUsage | null {
   if (!text) return null;
@@ -179,12 +278,11 @@ export function parseUsageTextFull(text: string, now = Date.now()): FullUsage |
     else if (/^all models$/i.test(m[2]!.trim())) weekAll = window;
     else perModel[m[2]!.trim()] = window;
   }
-  if (!session && !weekAll && Object.keys(perModel).length === 0) return null;
-  return {
-    session: session ?? { usedPercentage: 0, resetsAt: null },
-    weekAll: weekAll ?? { usedPercentage: 0, resetsAt: null },
-    perModel,
-  };
+  // All-or-nothing on the aggregates: every captured /usage output shows both
+  // rows, so a missing one is format drift, and fabricating 0% for it would
+  // make an unmeasured window read as safe (the one thing it must never do).
+  if (!session || !weekAll) return null;
+  return { session, weekAll, perModel };
 }
 
 /** Aggregate windows only (session→5h, week-all→7d), for the cold-start fallback. */
@@ -269,7 +367,7 @@ async function probeUsageOnce(env: Record<string, string>, now: number): Promise
     }
     out = r.stdout;
   } catch (e) {
-    log("usage.probe_failed", { err: String((e as Error).message ?? e) });
+    log("usage.probe_failed", { err: e instanceof Error ? e.message : String(e) });
     return null;
   }
 
@@ -368,7 +466,7 @@ export async function pingSession(configDir?: string): Promise<string | null> {
     mkdirSync(cwd, { recursive: true });
     r = await spawnClaudeBounded([resolveRealClaude(), ...PING_ARGS], probeEnv(configDir), cwd);
   } catch (e) {
-    return fail(String((e as Error).message ?? e));
+    return fail(e instanceof Error ? e.message : String(e));
   }
   if (r === null) return fail("output pipes still open after child exit (leaked descendant)");
   if (r.exitCode !== 0) return fail(`claude exited ${r.exitCode ?? "on signal"}: ${(r.stderr.trim() || r.stdout.trim()).slice(0, 160)}`);

package/src/main.ts

@@ -3,7 +3,9 @@
 // `claude` (or `__supervise`), routes hook/statusLine subcommands, and otherwise
 // dispatches the `tokenmaxxing` CLI.
 
+import { existsSync } from "node:fs";
 import { basename } from "node:path";
+import { paths } from "./lib/paths.ts";
 import { runSupervisor } from "./entries/supervisor.ts";
 import { runStatusline } from "./entries/statusline.ts";
 import { runSubagentStatusline } from "./entries/subagentstatusline.ts";
@@ -27,7 +29,7 @@ import { cmdSwitch } from "./cli/switch.ts";
 import { cmdCheck } from "./cli/check.ts";
 import { cmdConfig } from "./cli/config.ts";
 import { cmdServe } from "./cli/serve.ts";
-import { uninstallSupervisor } from "./lib/install.ts";
+import { timerDeactivationHint, uninstallSupervisor } from "./lib/install.ts";
 import { c } from "./cli/render.ts";
 
 function printHelp(): void {
@@ -47,7 +49,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing status --force")}  ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh; ${c.cyan("xx --force")} works too
   ${c.cyan("tokenmaxxing watch")} [seconds]  live status: re-render every N seconds (default 120, never pings)
   ${c.cyan("tokenmaxxing config")} [get|set|unset|tidy]  inspect and edit config.json (bare = effective config with sources)
-  ${c.cyan("tokenmaxxing serve")} [setup|link|unlink|links]  Slack bridge daemon: mention the bot in a linked channel to open a claude session per thread (worktree by default)
+  ${c.cyan("tokenmaxxing serve")} [setup|link|unlink|links]  Slack bridge daemon: mention the bot in a linked channel to open a claude session per thread in the repo checkout
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} [--codex] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} <sel>
@@ -73,6 +75,28 @@ async function main(): Promise<number> {
     return runCodexSupervisor({ argv: sub === "__supervise-codex" ? args.slice(1) : args });
   }
 
+  // CLI commands refuse an ambient claude store override (closing-review
+  // catch): with CLAUDE_CONFIG_DIR set, claude reads a hash-namespaced
+  // keychain item and a relocated .claude.json while this tool's identity,
+  // swap, and sampling machinery target the default store - `xx init` would
+  // silently import whatever stale login lives in the default location. The
+  // SDK's pooledSpawnEnv fails fast on exactly this; the CLI now matches.
+  // Scoped to COMMANDS only: the __-entries (hooks/statusline) and the
+  // supervisor arms above must never break a session claude itself launched
+  // with that env - sessions run under an ambient override are outside the
+  // managed envelope, like claude's bg-daemon bypass.
+  if (!(sub != null && sub.startsWith("__")) && !process.env.TOKENMAXXING_PROBE) {
+    // first NONEMPTY value, secure-storage first (claude's own precedence):
+    // `??` alone let an empty CLAUDE_CONFIG_DIR mask a set SECURESTORAGE
+    // override (cubic review catch, PR #35).
+    const nonEmpty = (v: string | undefined) => (v != null && v !== "" ? v : null);
+    const ambient = nonEmpty(process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR) ?? nonEmpty(process.env.CLAUDE_CONFIG_DIR);
+    if (ambient != null) {
+      console.error(c.red(`CLAUDE_CONFIG_DIR / CLAUDE_SECURESTORAGE_CONFIG_DIR is set (${ambient}): claude uses a namespaced credential store there that tokenmaxxing does not manage - unset it (or run from a clean shell) and retry.`));
+      return 1;
+    }
+  }
+
   switch (sub) {
     case "__statusline": return runStatusline();
     case "__subagent-statusline": return runSubagentStatusline();
@@ -81,7 +105,13 @@ async function main(): Promise<number> {
     case "__codex-stop-hook": return runCodexStopHook();
     case undefined: return cmdStatus(); // bare `tokenmaxxing` / `xx` → status
     case "--force": return cmdStatus(true); // bare `xx --force` → status --force
-    case "switch": return args[1] === "--codex" ? cmdCodexSwitch(args[2]) : cmdSwitch(args[1]);
+    // --codex accepted anywhere, like init/add/status: the old args[1]-only
+    // check made `xx switch <sel> --codex` silently run a real CLAUDE swap
+    // (one email can hold both pools' accounts - closing-review catch).
+    case "switch": {
+      const rest = args.slice(1).filter((a) => a !== "--codex");
+      return args.includes("--codex") ? cmdCodexSwitch(rest[0]) : cmdSwitch(rest[0]);
+    }
     case "check": return cmdCheck();
     case "config": return cmdConfig(args.slice(1));
     case "serve": return cmdServe(args.slice(1));
@@ -94,10 +124,23 @@ async function main(): Promise<number> {
     case "doctor": return cmdDoctor();
     case "rm": return cmdRm(args[1]);
     case "rename": return cmdRename(args.slice(1));
-    case "uninstall":
-      uninstallSupervisor();
-      console.log("removed supervisor wrapper + settings entries (accounts/credentials kept)");
+    case "uninstall": {
+      const out = uninstallSupervisor();
+      // the headline lists only what verifiably happened - claiming the timer
+      // or PATH line gone while the outcome flags say otherwise would
+      // contradict the warnings below (bugbot review catch, PR #33).
+      const removed = [
+        "supervisor wrapper",
+        "settings entries",
+        ...(out.timerDeactivated ? ["check timer"] : []),
+        ...(out.pathLineRemoved ? ["rc PATH line"] : []),
+      ];
+      console.log(`removed ${removed.join(", ")}`);
+      if (!out.timerDeactivated) console.log(c.yellow(`⚠ the check job may still be loaded - run: ${timerDeactivationHint()}`));
+      if (!out.pathLineRemoved) console.log(c.dim("(no tokenmaxxing PATH line found in the shell rc)"));
+      console.log(`kept: accounts.json, config.json${existsSync(paths.slackJson) ? ", slack.json (Slack tokens)" : ""}, and every parked credential (claude - macOS: keychain items, Linux: creds/; codex: codex-creds/) - remove accounts with \`xx rm\` to delete their credentials`);
       return 0;
+    }
     case "help":
     case "-h":
     case "--help":
@@ -110,4 +153,15 @@ async function main(): Promise<number> {
   }
 }
 
-process.exit(await main());
+// The CLI's error boundary: operational failures that deliberately THROW deep
+// in the libs (a locked keychain failing readItem loudly, codexinit's
+// changed-mid-init abort, corrupt state files) must reach the user as one
+// clean red line with the recovery hint the throw site wrote - not a raw
+// stack trace (bugbot review catch, PR #35). The __-entry subcommands keep
+// their own never-throw contracts and normally never reach this.
+try {
+  process.exit(await main());
+} catch (e) {
+  console.error(c.red(e instanceof Error ? e.message : String(e)));
+  process.exit(1);
+}

package/src/serve-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "tokenmaxxing",
+  "description": "Skills for Claude Code sessions relayed through tokenmaxxing serve (the Slack bridge)"
+}

package/src/serve-plugin/skills/ask-the-user/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: ask-the-user
+description: Use when you need the requesting user's decision, approval, or missing information to proceed, when you are blocked, or when long-running work they asked about is done, in a Slack-relayed tokenmaxxing serve session. Explains how to ask so the user actually gets notified.
+---
+
+# Asking the user from a serve session
+
+This session is relayed into a Slack thread. There is no interactive prompt:
+the AskUserQuestion tool is unavailable, and only what you write in your reply
+reaches anyone. A plain reply does not notify the user; a mention does.
+
+## How to ask
+
+1. Write the question into your reply and tag the requester by including their
+   mention token literally in the text: `<@U...>`, using the requester id from
+   the "Slack relay context" note in this turn. Slack renders it as @name and
+   notifies them.
+2. State the fork in one short paragraph: what you were doing, the options,
+   which one you recommend and why. One question at a time.
+3. End the turn after asking. Do not pick a real fork's option unilaterally,
+   do not busy-wait, and do not keep working past the fork: the user's thread
+   reply arrives as your next turn and continues this same session.
+
+## When to ask (and tag)
+
+- A real decision fork: destructive or irreversible actions, spending money or
+  metering account quota, a policy or design choice the user would want to
+  make, missing credentials or facts only they have.
+- You are blocked and cannot proceed.
+- You finished long-running work they asked to be told about.
+
+## When not to tag
+
+- Routine replies and progress: the user reads the thread, and a mention that
+  is not actionable trains them to ignore the real ones.
+- Never mention @here, @channel, or @everyone.

package/src/serve-plugin/skills/serve-session/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: serve-session
+description: How a tokenmaxxing serve session runs - the shared repo checkout, session resume across turns, when to cut your own git worktree, and how to hand finished work back. Use when deciding where to work, commit, push, or open a PR, or before any operation that moves, deletes, or switches the working directory.
+---
+
+# How a serve session runs
+
+tokenmaxxing serve bridges a Slack thread to this Claude Code session. Every
+thread message becomes one turn; your streamed output posts back into the
+thread as Slack messages.
+
+## Working directory
+
+- This session runs directly IN the linked repo checkout, and it is SHARED:
+  the repo's owner and other Slack threads work in the same checkout at the
+  same time. Read-only work (answering questions, reviewing code, reading
+  logs or history) happens here freely and in parallel. Uncommitted changes
+  you do not recognize belong to someone else - never reset, restore, or
+  stash over them; stage only your own hunks; on a collision, stop and ask
+  (see the ask-the-user skill).
+- MUTATING work cuts its own worktree FIRST (`git worktree add`). If the
+  task will edit, create, move, or delete files - or run anything that
+  writes into the tree - do it from a fresh worktree by default: other
+  threads and the owner share this checkout, and two agents editing one tree
+  corrupt each other silently. Say in the thread that you cut one, do the
+  task's whole life there (follow-ups included), and remove it once the work
+  is merged. Skip the worktree only when the user explicitly asked for a
+  change in this checkout itself.
+- Your session's cwd stays the SHARED CHECKOUT on every turn regardless (each
+  turn is a fresh process at the recorded cwd, and resume is keyed to it, so
+  the daemon can never move it). Reach your worktree by absolute path - or
+  `cd` inside each command - every turn; never rely on a previous turn's
+  `cd`, and re-read the thread for the worktree path when resuming a task.
+- Session resume is keyed to the session's cwd. Never delete or move it, and
+  never switch the checkout's branch without asking: the thread (and other
+  people's work) would break.
+
+## Turns
+
+- Each turn is a fresh claude process resumed by session id: the conversation
+  transcript carries over, but background processes and unsaved in-memory
+  state do not. Persist anything a later turn needs to files.
+- Nothing can answer an interactive dialog mid-turn. To get the user's input,
+  follow the ask-the-user skill.
+
+## Handing work back
+
+- Follow the repo's own shipping conventions (its AGENTS.md or CLAUDE.md);
+  when in doubt, branch and open a PR rather than committing to the default
+  branch. Push or merge only when the user asks.