tokenmaxxing 1.63.0 → 1.65.0

package/DESIGN.md

@@ -31,7 +31,7 @@ It is a process manager only - spawn with inherited stdio (stdin through a relay
 - Five `~/.claude/settings.json` entries (merged - other settings keys are preserved, but the `statusLine` slot is taken over): the tokenmaxxing `statusLine` renderer (native since 2026-07-11; it also tees usage), a `subagentStatusLine` (per-subagent rows in the agents panel), a `Stop` hook, a `StopFailure` hook, a `SessionStart` hook.
 - **`~/.config/tokenmaxxing/`** - the single home for config and state:
   - `config.json` - SPARSE overrides only (thresholds.session/weekly, claudeBin/codexBin/grokBin/opencodeBin pins, policy.*); defaults apply at read time, `xx config` prints the path and the effective values, and edits happen in an editor.
-  - `accounts.json` - non-secret index `{id, label, email, tier, addedAt, windows, lastUsageAt, lastProbeAt, probeFails, storeFails, enforcedUntil, needsReauth, oauthAccount}` (each cached window carries its name, duration, reset, and sample time; the same shape serves the Codex pool as `codex-accounts.json`). Neither index names an active account: the schema is `{version, accounts}`, and an older file that still carries `activeId` loads and drops the key on the next save.
+  - `accounts.json` - non-secret index `{id, label, email, tier, addedAt, windows, lastUsageAt, lastProbeAt, probeFails, storeFails, usageRetryAt, enforcedUntil, needsReauth, oauthAccount}` (each cached window carries its name, duration, reset, and sample time; the same shape serves the Codex pool as `codex-accounts.json`). Neither index names an active account: the schema is `{version, accounts}`, and an older file that still carries `activeId` loads and drops the key on the next save.
   - `stores/<uuid8>/` - one Claude Code credential store per pooled account (see below).
   - `codex-stores/<uuid8>/` - one Codex credential store per pooled account: its `auth.json`, with everything else symlinked to the shared `~/.codex` so sessions, history, and config stay shared and `codex resume` works across stores.
   - `usage/<uuid8>.json` - the statusline tee per account, written by the sessions running on it.
@@ -59,7 +59,7 @@ The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limi
 4. Write `respawn/<session-id>` (atomic temp+rename) naming the target, with `waitUntil` now for a plain move or the soonest reset when the pool is depleted. No credential is written.
 
 ### 3.3 Move and depleted-pool pause (supervisor)
-The supervisor sees `respawn/<sid>`, SIGTERMs its child at the already-committed turn boundary, deletes the marker, resets the terminal, compacts the conversation when the marker asks for it (`compact: true` from the Stop and SessionStart hooks and from the supervisor's own seat watch, `false` from StopFailure: it runs `claude -p --resume <sid> /compact` under the old seat's store, bounded at five minutes, and a failure only prints why), and (when `waitUntil` is in the future) shows an interruptible countdown to the reset; then it relaunches `claude --resume <sid>` with `CLAUDE_SECURESTORAGE_CONFIG_DIR` set to the target's store and rewrites the session's presence. The resumed process reads that store cold → runs on the target account, same conversation. The relaunch submits a first prompt that names the move (and the compaction, when it landed) and asks Claude to continue the task, so the conversation goes on without a keystroke: in a terminal session it is the positional prompt after the session id; in a stream-json session (`--input-format stream-json`, where the binary ignores a positional prompt) the supervisor owns stdin, relays the harness's lines to the child through a pipe, and writes the prompt as the first `user` line of the new process. In a terminal session the supervisor's own notices go to stderr. In a stream-json session (`--output-format stream-json`, read from the effective flags like the relay) there is no terminal and no statusline, so the supervisor writes each notice (the compaction and its failure, the move, the depleted-pool wait with its resume time, the resume) to stdout as a `system` line of subtype `informational` and level `warning`, the shape Claude Code emits for its own print-mode notices, which the harness renders in the conversation while the stream stays parseable; the per-second countdown ticks stay terminal-only, and the supervisor writes only while no child is running. The `SessionStart` hook (every source) re-runs the decision before the first turn and writes the same marker if the seat is already over its bar or the pool is depleted. The supervisor also watches its own seat every ten seconds while the child runs (account record plus tee, the same bars) and writes the marker itself when the seat is at or over a bar, so a move never depends on a hook firing: a harness session between turns whose background workflow burns the window, or a subagent refusal that stamped the wall, is moved within seconds. SIGTERM to the supervisor is forwarded to the child and the supervisor exits after it, so a harness that stops the wrapper (the Agent SDK does) never leaves an orphaned claude on the old seat. A marker whose `launchedAt` does not match the running child is discarded, and after a Ctrl-C on the countdown a later marker whose `waitUntil` falls inside the skipped wait is ignored. A marker that fails to parse is never deleted and never treated as absent: the supervisor stops the child, restores the terminal, and exits naming the marker path. In a stream-json session that fatal, the wrap-depth abort, the wrap-rate abort, and a failed presence write also go to stdout as the same `informational`/`warning` line.
+The supervisor sees `respawn/<sid>`, SIGTERMs its child at the already-committed turn boundary, deletes the marker, resets the terminal, compacts the conversation when the marker asks for it (`compact: true` from the Stop and SessionStart hooks and from the supervisor's own seat watch, `false` from StopFailure: it runs `claude -p --resume <live-id> /compact` under the old seat's store, bounded at five minutes, and a failure only prints why), and (when `waitUntil` is in the future) shows an interruptible countdown to the reset; then it relaunches `claude --resume <live-id>` (`--session-id <live-id>` when that id has no transcript yet, because `--resume` exits with `No conversation found` for it) with `CLAUDE_SECURESTORAGE_CONFIG_DIR` set to the target's store and rewrites the session's presence. The marker file is keyed by the launch id `<sid>`; the live id inside it is the session id the supervised process runs now, which `/clear` and an in-session `/resume` change. A hook adopts a differing stdin id as the live id (`current` in `sessions/<sid>.json`) only when its own process descends, through shell processes alone, from the presence record's pid; any other differing id is a nested session and writes nothing. The resumed process reads that store cold → runs on the target account, same conversation. The `--session-id` path is the exception: the cleared conversation has no prior turn, so it starts empty with no compaction and no first prompt. On the `--resume` path the relaunch submits a first prompt that names the move (and the compaction, when it landed) and asks Claude to continue the task, so the conversation goes on without a keystroke: in a terminal session it is the positional prompt after the session id; in a stream-json session (`--input-format stream-json`, where the binary ignores a positional prompt) the supervisor owns stdin, relays the harness's lines to the child through a pipe, and writes the prompt as the first `user` line of the new process. In a terminal session the supervisor's own notices go to stderr. In a stream-json session (`--output-format stream-json`, read from the effective flags like the relay) there is no terminal and no statusline, so the supervisor writes each notice (the compaction and its failure, the move, the depleted-pool wait with its resume time, the resume) to stdout as a `system` line of subtype `informational` and level `warning`, the shape Claude Code emits for its own print-mode notices, which the harness renders in the conversation while the stream stays parseable; the per-second countdown ticks stay terminal-only, and the supervisor writes only while no child is running. The `SessionStart` hook (every source) re-runs the decision before the first turn and writes the same marker if the seat is already over its bar or the pool is depleted. The supervisor also watches its own seat every ten seconds while the child runs (account record plus tee, the same bars) and writes the marker itself when the seat is at or over a bar, so a move never depends on a hook firing: a harness session between turns whose background workflow burns the window, or a subagent refusal that stamped the wall, is moved within seconds. SIGTERM to the supervisor is forwarded to the child and the supervisor exits after it, so a harness that stops the wrapper (the Agent SDK does) never leaves an orphaned claude on the old seat. A marker whose `launchedAt` does not match the running child is discarded, and after a Ctrl-C on the countdown a later marker whose `waitUntil` falls inside the skipped wait is ignored. A marker that fails to parse is never deleted and never treated as absent: the supervisor stops the child, restores the terminal, and exits naming the marker path. In a stream-json session that fatal, the wrap-depth abort, the wrap-rate abort, and a failed presence write also go to stdout as the same `informational`/`warning` line.
 
 ### 3.4 Placement (supervisor, under the pool lock)
 1. Fold every account's tee into the index.
@@ -84,7 +84,7 @@ Each terminal ran the supervisor, so each has its own child `claude`, its own `-
 The [switching policy](docs/content/docs/switching.mdx) is one rule: under both bars, hold; at or over a bar, move to the usable account that ranks first; nothing usable, wait for the soonest reset. The same ranking places a session at launch.
 
 - Ranking (decided by consult for #79): greatest remaining headroom to the session bar divided by the number of sessions after placement, `(bar - used) / (sessions + 1)`, then highest pace pressure (remaining percent of the binding gated per-model cap, or of the weekly aggregate for an account with no gated row, over time to its reset), then soonest weekly reset, then lowest weekly usage; unknown usage ranks last. Organization membership is not an input. Codex drops the headroom key, keeps the pace ordering and the weekly tie-breaks, and excludes accounts running in another codex session, because codex has no cross-process refresh lock and two sessions must never share a login.
-- Selection reads the cached figures only, after folding every account's tee. Each periodic check tick samples up to three accounts whose last sample attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`, over the direct no-spend usage read with the account's stored token, so every account is attempted about once per three ticks per pooled account, or once per `policy.usagePollTtlMs` plus a tick when that is longer, and its cached figure is as fresh as its last successful attempt or its sessions' latest push. The pool lock covers only the reservation and the result write, never the usage GET. An expired stored access token stays unmeasured until a session on that store refreshes it.
+- Selection reads the cached figures only, after folding every account's tee. Each periodic check tick samples up to three accounts whose last sample attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`, over the direct no-spend usage read with the account's stored token, so every account is attempted about once per three ticks per pooled account, or once per `policy.usagePollTtlMs` plus a tick when that is longer, and its cached figure is as fresh as its last successful attempt or its sessions' latest push. The pool lock covers only the reservation and the result write, never the usage GET. The usage endpoint rate limits each account on its own and names the time to come back in the `retry-after` of its HTTP 429; that time is stored as `usageRetryAt`, and no sampler (the tick, `status`, the seat's in-decision sample) reads the account before it. An expired stored access token stays unmeasured until a session on that store refreshes it.
 - The depleted pause happens at the bar, not at 100; Codex has no pause and rides its account until the server refuses it, because a running sibling cannot adopt another account without restarting.
 - Neither pool has a post-swap cooldown or a manual `switch`: a move is a respawn of one session under a fixed store, so nothing another session reads is invalidated by it, and placement at launch replaces the manual pick.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.63.0",
+  "version": "1.65.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts, start each session on its own account, and resume a session on a fresher account when quota fills.",
   "type": "module",
   "license": "MIT",

package/src/entries/stopfailurehook.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { claude } from "../lib/claude.ts";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
 import { readStdin } from "../lib/proc.ts";
-import { supervisedSession, writeRespawnMarker } from "../lib/sessions.ts";
+import { adoptLiveSession, supervisedSession, writeRespawnMarker } from "../lib/sessions.ts";
 import { loadConfig } from "../lib/state.ts";
 import { classifyEnforcedLimit, findEnforcedRow, parseErrorBody, readTranscriptTail, type TranscriptRow } from "../lib/usage.ts";
 import { paths } from "../lib/paths.ts";
@@ -39,15 +39,16 @@ export async function runStopFailureHook(): Promise<number> {
   if (stdin.error !== undefined && stdin.error !== "rate_limit") return 0;
 
   const stdinSid = stdin.session_id;
-  const session = supervisedSession();
   const mainLoop = stdin.agent_id === undefined;
-  if (stdinSid != null && session != null && stdinSid !== session.sid) {
-    log("stopfailure.nested_session", { stdin: stdinSid.slice(0, 8), supervised: session.sid.slice(0, 8) });
-    return 0;
-  }
-  const canRespawn = session != null && mainLoop;
 
   try {
+    const supervised = supervisedSession();
+    const session = supervised == null ? null : adoptLiveSession(supervised, stdinSid);
+    if (supervised != null && session == null) {
+      log("stopfailure.nested_session", { stdin: stdinSid?.slice(0, 8), supervised: supervised.live.slice(0, 8) });
+      return 0;
+    }
+    const canRespawn = session != null && mainLoop;
     const cfg = loadConfig();
     const row = stdin.transcript_path
       ? await awaitEnforcedRow({ transcriptPath: stdin.transcript_path, lastAssistantMessage: stdin.last_assistant_message, now })
@@ -81,8 +82,8 @@ export async function runStopFailureHook(): Promise<number> {
 
     const decision = await evaluateAndMaybeSwap(claude, now, canRespawn && enforced != null, enforced);
     if (enforced && session && canRespawn && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
-      writeRespawnMarker({ session, sessionId: stdinSid ?? session.sid, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: false });
-      log("stopfailure.marker", { session: session.sid.slice(0, 8), account: decision.account.id.slice(0, 8), waitUntil: decision.waitUntil ?? now });
+      writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: false });
+      log("stopfailure.marker", { session: session.sid.slice(0, 8), live: session.live.slice(0, 8), account: decision.account.id.slice(0, 8), waitUntil: decision.waitUntil ?? now });
     } else {
       log("stopfailure.decision", { reason: decision.reason, swapped: decision.swapped, account: decision.account?.id.slice(0, 8), waitUntil: decision.waitUntil });
     }

package/src/entries/stophook.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { claude } from "../lib/claude.ts";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
 import { readStdin } from "../lib/proc.ts";
-import { supervisedSession, writeRespawnMarker } from "../lib/sessions.ts";
+import { adoptLiveSession, supervisedSession, writeRespawnMarker } from "../lib/sessions.ts";
 import { JsonTextSchema } from "../lib/types.ts";
 import { errorMessage, log } from "../lib/log.ts";
 
@@ -16,18 +16,18 @@ export async function runBoundaryHook(event: "stop" | "sessionstart"): Promise<n
 
   const parsed = BoundaryStdin.safeParse(JsonTextSchema.safeParse(await readStdin()).data);
   const stdin = parsed.success ? parsed.data : {};
-  const session = supervisedSession();
-  const nested = stdin.session_id != null && session != null && stdin.session_id !== session.sid;
-  if (nested) {
-    log(`${event}.nested_session`, { stdin: stdin.session_id?.slice(0, 8), supervised: session?.sid.slice(0, 8) });
-    return 0;
-  }
 
   try {
+    const supervised = supervisedSession();
+    const session = supervised == null ? null : adoptLiveSession(supervised, stdin.session_id);
+    if (supervised != null && session == null) {
+      log(`${event}.nested_session`, { stdin: stdin.session_id?.slice(0, 8), supervised: supervised.live.slice(0, 8), source: stdin.source });
+      return 0;
+    }
     const decision = await evaluateAndMaybeSwap(claude, Date.now(), session != null);
     if (session && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
-      writeRespawnMarker({ session, sessionId: stdin.session_id ?? session.sid, accountId: decision.account.id, waitUntil: decision.waitUntil ?? Date.now(), compact: true });
-      log(`${event}.${decision.waitUntil !== undefined ? "wait" : "move"}`, { source: stdin.source, account: decision.account.id.slice(0, 8), waitUntil: decision.waitUntil, session: session.sid.slice(0, 8) });
+      writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? Date.now(), compact: true });
+      log(`${event}.${decision.waitUntil !== undefined ? "wait" : "move"}`, { source: stdin.source, account: decision.account.id.slice(0, 8), waitUntil: decision.waitUntil, session: session.sid.slice(0, 8), live: session.live.slice(0, 8) });
     }
   } catch (e) {
     log(`${event}.error`, { err: errorMessage(e) });

package/src/entries/supervisor.ts

@@ -15,7 +15,7 @@ import { readLines } from "../lib/proc.ts";
 import { teeObservation } from "../lib/sample.ts";
 import { exitStatus, loopGuardTripped, raceMarkerOrExit, recordPresenceOrStop, runPassthrough } from "../lib/supervise.ts";
 import { saveTermios } from "../lib/tty.ts";
-import { loadSessionFlags, pruneStaleSessions, saveSessionFlags, writeRespawnMarker } from "../lib/sessions.ts";
+import { liveSessionId, loadSessionFlags, pruneStaleSessions, saveSessionFlags, writeRespawnMarker } from "../lib/sessions.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
 import { gatedFamilies, modelFromFlag } from "../lib/usage.ts";
 import { RespawnMarkerSchema, type Account, type Config, type ModelInfo } from "../lib/types.ts";
@@ -225,7 +225,7 @@ async function moveExhaustedSeat(seat: Account, sid: string, gate: MarkerGate, m
     const decision = await evaluateAndMaybeSwap(claude, now, true, null, seat.id, families);
     log("supervisor.seat_exhausted", { seat: seat.id.slice(0, 8), until, reason: decision.reason, account: decision.account?.id.slice(0, 8), waitUntil: decision.waitUntil });
     if (decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
-      writeRespawnMarker({ session: { sid, launchedAt: gate.launchedAt }, sessionId: sid, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: true });
+      writeRespawnMarker({ session: { sid, launchedAt: gate.launchedAt, live: liveSessionId(sid) }, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: true });
     }
   } catch (e) {
     log("supervisor.seat_watch_error", { err: errorMessage(e) });
@@ -508,7 +508,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       saveSessionFlags(m.sessionId, persistable, process.cwd());
       const prompt = resumable ? resumePrompt(compacted) : null;
       firstLine = relay !== null && prompt !== null ? userLine(prompt) : null;
-      launchArgs = ["--resume", m.sessionId, ...(relay === null && prompt !== null ? [prompt] : []), ...persistable];
+      launchArgs = [resumable ? "--resume" : "--session-id", m.sessionId, ...(relay === null && prompt !== null ? [prompt] : []), ...persistable];
       continue;
     }
     clearPresence({ dir: paths.presenceDir, id: sid });

package/src/lib/claude.ts

@@ -12,7 +12,7 @@ import { claudePool, env, paths, seatFromEnv, storeDirFor } from "./paths.ts";
 import { pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./picker.ts";
 import { seatCounts } from "./presence.ts";
 import type { Observation, Provider, SampleReport } from "./provider.ts";
-import { foldTee, sampleAccountUsage, teeObservation } from "./sample.ts";
+import { foldTee, sampleAccountUsage, teeObservation, usageBlockedUntil } from "./sample.ts";
 import { clearUsageSnapshot, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, saveAccounts, type Harvest } from "./state.ts";
 import { loadSetupTokens, saveSetupTokens } from "./setuptokens.ts";
 import { saveTermios, restoreTermios } from "./tty.ts";
@@ -43,7 +43,7 @@ async function observeLive(account: Account, cfg: Config, now: number, opts: { p
   const probeAttempted = account.lastProbeAt != null && now - account.lastProbeAt <= interval;
   const snap = loadUsageSnapshot(account.id);
   const fresh = snap != null && now - snap.at <= ttl;
-  if (opts.probe && !probeAttempted && (!fresh || opts.perModel)) {
+  if (opts.probe && !probeAttempted && usageBlockedUntil(account, now) == null && (!fresh || opts.perModel)) {
     const startedAt = Date.now();
     const outcome = await sampleAccountUsage(account);
     await withLock(claudePool.lockFile, () => {
@@ -61,6 +61,7 @@ async function observeLive(account: Account, cfg: Config, now: number, opts: { p
         }
       } else {
         a.probeFails = (a.probeFails ?? 0) + 1;
+        if (outcome.retryAt != null) a.usageRetryAt = outcome.retryAt;
       }
       saveAccounts(claudePool, idx);
     });
@@ -82,6 +83,7 @@ async function samplePool(accounts: Account[]): Promise<Map<string, SampleReport
       }
       const outcome = await sampleAccountUsage(a);
       if (!outcome.ok) {
+        if (outcome.retryAt != null) a.usageRetryAt = outcome.retryAt;
         reports.set(a.id, { ok: false, reason: outcome.reason });
         return;
       }
@@ -215,7 +217,7 @@ async function login(): Promise<Harvest | null> {
 
     console.log(c.dim("sampling usage..."));
     const sampled = await fetchUsageDirect(blob.claudeAiOauth.accessToken);
-    if (!sampled) console.log(c.yellow("could not sample usage now - it will fill in on first use."));
+    if (!sampled.ok) console.log(c.yellow("could not sample usage now - it will fill in on first use."));
     const at = Date.now();
     const id = oauthAccount.accountUuid;
     return {
@@ -223,7 +225,8 @@ async function login(): Promise<Harvest | null> {
       email: oauthAccount.emailAddress,
       tier: claudeTierLabel(blob.claudeAiOauth),
       oauthAccount,
-      sample: sampled ? { windows: windowsOf(sampled, at), at } : null,
+      sample: sampled.ok ? { windows: windowsOf(sampled.usage, at), at } : null,
+      ...(!sampled.ok && sampled.retryAt != null ? { usageRetryAt: sampled.retryAt } : {}),
       park: () => writeItem(storeTarget(id), claudeAiOauthOnly(blobRaw)),
     };
   } finally {

package/src/lib/presence.ts

@@ -18,6 +18,17 @@ export function writePresence(input: { dir: string; id: string; accountId: strin
   writeFileAtomic(join(input.dir, input.id), JSON.stringify(PresenceSchema.parse({ accountId: input.accountId, pid: input.pid, startedAt })));
 }
 
+export function presencePid(input: { dir: string; id: string }): number | null {
+  let raw: string;
+  try {
+    raw = readFileSync(join(input.dir, input.id), "utf8");
+  } catch (e) {
+    if (ErrnoSchema.safeParse(e).data?.code === "ENOENT") return null;
+    throw e;
+  }
+  return PresenceSchema.parse(JSON.parse(raw)).pid;
+}
+
 export function clearPresence(input: { dir: string; id: string }): void {
   rmSync(join(input.dir, input.id), { force: true });
 }

package/src/lib/proc.ts

@@ -1,5 +1,30 @@
+import { basename } from "node:path";
 import { ErrnoSchema } from "./types.ts";
 
+const SHELLS = new Set(["sh", "bash", "dash", "zsh", "ksh", "fish"]);
+const MAX_SHELL_HOPS = 4;
+
+function parentAndName(pid: number): { ppid: number; comm: string } | null {
+  const res = Bun.spawnSync(["ps", "-p", String(pid), "-o", "ppid=", "-o", "comm="], { env: { ...process.env, LC_ALL: "C" } });
+  if (res.exitCode !== 0) return null;
+  const row = res.stdout.toString().trim();
+  const cut = row.indexOf(" ");
+  if (cut === -1) return null;
+  const ppid = Number(row.slice(0, cut));
+  return Number.isInteger(ppid) ? { ppid, comm: row.slice(cut).trim() } : null;
+}
+
+export function spawnedThroughShellsBy(ancestor: number): boolean {
+  let cur = process.ppid;
+  for (let hop = 0; hop <= MAX_SHELL_HOPS; hop++) {
+    if (cur === ancestor) return true;
+    const proc = parentAndName(cur);
+    if (proc == null || !SHELLS.has(basename(proc.comm))) return false;
+    cur = proc.ppid;
+  }
+  return false;
+}
+
 export function pidStartTime(pid: number): string | null {
   const res = Bun.spawnSync(["ps", "-p", String(pid), "-o", "lstart="], { env: { ...process.env, LC_ALL: "C" } });
   if (res.exitCode !== 0) return null;

package/src/lib/sample.ts

@@ -9,7 +9,7 @@ import { loadAccounts, loadUsageSnapshot, saveAccounts } from "./state.ts";
 import { fetchUsageDirect, mergeWindows, windowsOf } from "./usage.ts";
 import type { Account, Config, UsageWindows } from "./types.ts";
 
-export type SampleOutcome = { ok: true; usage: UsageWindows; via: "get" } | { ok: false; reason: string };
+export type SampleOutcome = { ok: true; usage: UsageWindows; via: "get" } | { ok: false; reason: string; retryAt?: number };
 
 type PreparedSample = { ok: true; token: string | null } | { ok: false; reason: string };
 
@@ -48,13 +48,26 @@ export async function prepareSample(account: Account): Promise<PreparedSample> {
   return { ok: true, token: creds.accessToken };
 }
 
+export function usageBlockedUntil(account: Account, now: number): number | null {
+  return account.usageRetryAt != null && account.usageRetryAt > now ? account.usageRetryAt : null;
+}
+
+function rateLimitedReason(retryAt: number, now: number): string {
+  return `the usage endpoint rate limited this account, next read in ${Math.ceil((retryAt - now) / 60_000)}m`;
+}
+
 export async function runSample(account: Account, token: string | null): Promise<SampleOutcome> {
   if (!token) return { ok: false, reason: "no usable access token in the store - run `tokenmaxxing auth`" };
-  const usage = await fetchUsageDirect(token);
-  return usage ? { ok: true, usage, via: "get" } : { ok: false, reason: "usage read failed (see log)" };
+  const read = await fetchUsageDirect(token);
+  if (read.ok) return { ok: true, usage: read.usage, via: "get" };
+  if (read.retryAt == null) return { ok: false, reason: "usage read failed (see log)" };
+  return { ok: false, reason: rateLimitedReason(read.retryAt, Date.now()), retryAt: read.retryAt };
 }
 
 export async function sampleAccountUsage(account: Account): Promise<SampleOutcome> {
+  const now = Date.now();
+  const blockedUntil = usageBlockedUntil(account, now);
+  if (blockedUntil != null) return { ok: false, reason: rateLimitedReason(blockedUntil, now) };
   const prepared = await prepareSample(account);
   return prepared.ok ? runSample(account, prepared.token) : prepared;
 }
@@ -89,7 +102,7 @@ export async function sampleOldest(cfg: Config): Promise<void> {
         continue;
       }
       target.storeFails = 0;
-      batch.push({ account: target, token: prepared.token });
+      if (usageBlockedUntil(target, now) == null) batch.push({ account: target, token: prepared.token });
     }
     saveAccounts(claudePool, idx);
     return batch;
@@ -106,6 +119,10 @@ export async function sampleOldest(cfg: Config): Promise<void> {
           stored.needsReauth = true;
           dirty = true;
         }
+        if (stored && !outcome.ok && outcome.retryAt != null) {
+          stored.usageRetryAt = outcome.retryAt;
+          dirty = true;
+        }
         if (stored && outcome.ok && (stored.lastUsageAt == null || startedAt > stored.lastUsageAt)) {
           stored.windows = mergeWindows(windowsOf(outcome.usage, startedAt), stored.windows);
           stored.lastUsageAt = startedAt;

package/src/lib/sessions.ts

@@ -1,12 +1,14 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, type Dirent } from "node:fs";
-import { join, sep } from "node:path";
+import { basename, join, sep } from "node:path";
 import { z } from "zod";
 import { errorMessage, log } from "./log.ts";
 import { codexPaths, grokPaths, opencodeGoPaths, paths } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
+import { presencePid } from "./presence.ts";
+import { spawnedThroughShellsBy } from "./proc.ts";
 import type { RespawnMarkerSchema } from "./types.ts";
 
-const SessionSchema = z.object({ flags: z.array(z.string()), cwd: z.string() });
+const SessionSchema = z.object({ flags: z.array(z.string()), cwd: z.string(), current: z.uuid().optional() });
 
 const SESSION_RETENTION_MS = 30 * 24 * 3600 * 1000;
 
@@ -21,10 +23,24 @@ export function saveSessionFlags(sid: string, flags: string[], cwd: string): voi
   writeFileAtomic(sessionFile(sid), JSON.stringify({ flags, cwd }));
 }
 
-export function loadSessionFlags(sid: string): string[] | null {
+function loadSession(sid: string): z.infer<typeof SessionSchema> | null {
   const f = sessionFile(sid);
   if (!existsSync(f)) return null;
-  return SessionSchema.parse(JSON.parse(readFileSync(f, "utf8"))).flags;
+  return SessionSchema.parse(JSON.parse(readFileSync(f, "utf8")));
+}
+
+export function loadSessionFlags(sid: string): string[] | null {
+  return loadSession(sid)?.flags ?? null;
+}
+
+export function liveSessionId(sid: string): string {
+  return loadSession(sid)?.current ?? sid;
+}
+
+function recordLiveSession(sid: string, current: string): void {
+  const session = loadSession(sid);
+  mkdirSync(sessionsDir(), { recursive: true });
+  writeFileAtomic(sessionFile(sid), JSON.stringify({ flags: session?.flags ?? [], cwd: session?.cwd ?? process.cwd(), current }));
 }
 
 const DEAD_STATE_ENTRIES = [
@@ -101,13 +117,14 @@ export function pruneStaleSessions(now: number): void {
   for (const f of listDir(dir, root)) {
     const p = join(dir, f.name);
     try {
+      if (existsSync(join(paths.presenceDir, basename(f.name, ".json")))) continue;
       if (now - statSync(p).mtimeMs > SESSION_RETENTION_MS) rmSync(p, { force: true });
     } catch {
     }
   }
 }
 
-export type SupervisedSession = { sid: string; launchedAt: number | null };
+export type SupervisedSession = { sid: string; launchedAt: number | null; live: string };
 
 const LaunchedAtSchema = z.coerce.number().finite().optional().catch(undefined);
 
@@ -115,16 +132,28 @@ export function supervisedSession(env: Record<string, string | undefined> = proc
   if (env.TOKENMAXXING_SUPERVISED !== "1") return null;
   const sid = env.TOKENMAXXING_SESSION_ID;
   if (sid == null || sid === "") return null;
-  return { sid, launchedAt: LaunchedAtSchema.parse(env.TOKENMAXXING_LAUNCHED_AT) ?? null };
+  return { sid, launchedAt: LaunchedAtSchema.parse(env.TOKENMAXXING_LAUNCHED_AT) ?? null, live: liveSessionId(sid) };
+}
+
+export function adoptLiveSession(session: SupervisedSession, stdinSid: string | undefined): SupervisedSession | null {
+  if (stdinSid == null || stdinSid === session.live) return session;
+  const child = presencePid({ dir: paths.presenceDir, id: session.sid });
+  if (child == null || !spawnedThroughShellsBy(child)) {
+    log("session.live_id_refused", { reason: child == null ? "no-presence" : "not-descendant", stdin: stdinSid.slice(0, 8), live: session.live.slice(0, 8), session: session.sid.slice(0, 8) });
+    return null;
+  }
+  recordLiveSession(session.sid, stdinSid);
+  log("session.live_id", { from: session.live.slice(0, 8), to: stdinSid.slice(0, 8), session: session.sid.slice(0, 8) });
+  return { ...session, live: stdinSid };
 }
 
-export function writeRespawnMarker(input: { session: SupervisedSession; sessionId: string; accountId: string; waitUntil: number; compact: boolean }): void {
+export function writeRespawnMarker(input: { session: SupervisedSession; accountId: string; waitUntil: number; compact: boolean }): void {
   mkdirSync(paths.respawnDir, { recursive: true });
   const payload: z.infer<typeof RespawnMarkerSchema> = {
     accountId: input.accountId,
     ts: Date.now(),
     waitUntil: input.waitUntil,
-    sessionId: input.sessionId,
+    sessionId: input.session.live,
     compact: input.compact,
     ...(input.session.launchedAt != null ? { launchedAt: input.session.launchedAt } : {}),
   };

package/src/lib/state.ts

@@ -73,6 +73,7 @@ export type Harvest = {
   tier: string | null;
   oauthAccount?: Account["oauthAccount"];
   sample: { windows: Window[]; at: number } | null;
+  usageRetryAt?: number;
   park: () => Promise<void>;
 };
 
@@ -92,6 +93,7 @@ export function upsertAccount(
     lastUsageAt: h.sample ? h.sample.at : existing?.lastUsageAt,
     needsReauth: false,
     ...(h.oauthAccount ? { oauthAccount: h.oauthAccount } : {}),
+    usageRetryAt: h.sample ? undefined : (h.usageRetryAt ?? existing?.usageRetryAt),
   };
   if (existing) Object.assign(existing, fresh);
   else idx.accounts.push(fresh);

package/src/lib/types.ts

@@ -69,6 +69,7 @@ export const AccountSchema = z.object({
   lastProbeAt: z.number().optional(),
   probeFails: z.number().optional(),
   storeFails: z.number().optional(),
+  usageRetryAt: z.number().optional(),
   enforcedUntil: z.number().optional(),
   needsReauth: z.boolean().optional(),
   oauthAccount: OAuthAccountSchema.optional(),

package/src/lib/usage.ts

@@ -208,7 +208,11 @@ function scopedRows(limits: unknown[]): Record<string, UsageWindow> {
   return perModel;
 }
 
-export async function fetchUsageDirect(accessToken: string): Promise<UsageWindows | null> {
+const RetryAfterSecondsSchema = z.coerce.number().int().positive();
+
+export type UsageRead = { ok: true; usage: UsageWindows } | { ok: false; retryAt: number | null };
+
+export async function fetchUsageDirect(accessToken: string): Promise<UsageRead> {
   let res: Response;
   try {
     res = await http.get(USAGE_URL, {
@@ -218,17 +222,18 @@ export async function fetchUsageDirect(accessToken: string): Promise<UsageWindow
     });
   } catch (e) {
     log("usage.get_failed", { err: errorMessage(e) });
-    return null;
+    return { ok: false, retryAt: null };
   }
   if (!res.ok) {
-    log("usage.get_failed", { status: res.status });
-    return null;
+    const retryAfter = res.status === 429 ? RetryAfterSecondsSchema.safeParse(res.headers.get("retry-after")).data : undefined;
+    log("usage.get_failed", { status: res.status, retryAfter });
+    return { ok: false, retryAt: retryAfter != null ? Date.now() + retryAfter * 1000 : null };
   }
   const parsed = UsageResponseSchema.safeParse(JsonTextSchema.safeParse(await res.text()).data);
   if (!parsed.success || !parsed.data.five_hour || !parsed.data.seven_day) {
     log("usage.get_incomplete", { ok: parsed.success, issue: parsed.success ? undefined : z.prettifyError(parsed.error).slice(0, 200) });
-    return null;
+    return { ok: false, retryAt: null };
   }
   const win = (w: z.infer<typeof UsageLimitSchema>): UsageWindow => ({ usedPercentage: w.utilization, resetsAt: w.resets_at ?? null });
-  return { fiveHour: win(parsed.data.five_hour), sevenDay: win(parsed.data.seven_day), perModel: scopedRows(parsed.data.limits ?? []) };
+  return { ok: true, usage: { fiveHour: win(parsed.data.five_hour), sevenDay: win(parsed.data.seven_day), perModel: scopedRows(parsed.data.limits ?? []) } };
 }