tokenmaxxing 1.79.0 → 1.81.0

package/DESIGN.md

@@ -36,7 +36,7 @@ It is a process manager only - spawn with inherited stdio (stdin through a relay
   - `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.
   - `live/<session-id>` - PID-validated presence per supervised session, naming its account; placement counts them.
-  - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal): the target account, the session to resume, a `waitUntil`, a `compact` flag, and the launch time the marker was written for.
+  - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal): the target account, the session to resume, a `waitUntil`, a `compact` flag, the `origin` (the hook or the seat watch that wrote it), and the launch time the marker was written for.
   - `wait-queue.json` - the depleted-pool wait claims (`{sessionId, accountId, at, waitUntil}`), so at most four sessions wait on one account; a session that arrives when every account already has four waiters takes the soonest reset anyway.
   - `bin/claude` and `bin/codex` - the supervisors, beside the `tokenmaxxing` and `xx` entry points.
   - `sessions/<sid>.json`, `onboard/`, `hub-key`, `update.json`, `spawnrate.json`, `tokenmaxxing.log`, the codex `codex-onboard/`, `codex-respawn/`, and `codex-live/`, and the `grok-*` and `opencode-go-*` state of the status-only pools: the full table is in [State directory layout](docs/content/docs/state-directory.mdx).
@@ -61,7 +61,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 assigned 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 <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.
+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 and the old seat's record carries no live `enforcedUntil` (`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; the compaction counts only when a `compact_boundary` row lands in the transcript, because a refused compaction still exits 0, 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). After a Stop move the previous turn had finished, so the prompt asks Claude to end the turn without restating it, and to relaunch any background Bash task, Monitor, or Workflow run that turn waited on, because the move ended it. After any other move the prompt asks Claude to continue the task, says the restart ended every background Bash task, Monitor, and Workflow run the session started, and asks Claude to relaunch what the task still needs; a SessionStart move is in that group because a prompt sent inside the marker poll window can already have started on the old seat. 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.

package/README.md

@@ -130,7 +130,7 @@ Two codex-specific facts worth knowing: codex does not run hooks it has not been
 
 ## Honest limitations
 
-- **A move restarts the process.** The session resumes the same transcript under the new account and continues on its own from a first prompt the supervisor submits, but the process restarts; a bar-triggered move compacts the conversation on the old account first, so the first turn on the new account uploads the summary, while a move after a refusal re-uploads the full context once (prompt cache is org-scoped).
+- **A move restarts the process.** The session resumes the same transcript under the new account and continues on its own from a first prompt the supervisor submits, but the process restarts, which ends every background Bash task, Monitor, and Workflow run the session started (the first prompt asks Claude to relaunch what the task still needs); a bar-triggered move compacts the conversation on the old account first, so the first turn on the new account uploads the summary (the full context when the compaction does not land), while a move after a refusal re-uploads the full context once (prompt cache is org-scoped).
 - **Depleted-pause hiccup.** When the whole pool is at its limit, `claude` stops for the countdown; anything typed in that split second is lost.
 - **Unsupervised sessions are not moved.** A claude started outside the supervisor runs on Claude Code's own login, which tokenmaxxing never writes; when a hard limit lands there, the StopFailure hook prints the shim command that resumes the session under the supervisor.
 - **One shared identity file.** `~/.claude.json` holds one `oauthAccount` that Claude Code rewrites after whichever session refreshed last, so `/status` can show another session's email; the statusline's `◆` marks the account a session actually uses.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.79.0",
+  "version": "1.81.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/codexsupervisor.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { codexPaths, codexPool } from "../lib/paths.ts";
@@ -10,7 +10,7 @@ import { clearPresence, livingPresences } from "../lib/presence.ts";
 import { isExhausted } from "../lib/picker.ts";
 import { exitStatus, loopGuardTripped, raceMarkerOrExit, recordPresenceOrStop, runPassthrough } from "../lib/supervise.ts";
 import { saveTermios } from "../lib/tty.ts";
-import { loadAccounts } from "../lib/state.ts";
+import { loadAccounts, readJsonFile } from "../lib/state.ts";
 import { CodexRespawnMarkerSchema, type Account } from "../lib/types.ts";
 import { errorMessage, log } from "../lib/log.ts";
 
@@ -26,7 +26,7 @@ const PASSTHROUGH_FLAGS = new Set(["--version", "-V", "--help", "-h"]);
 
 function readCodexMarker(marker: string): z.infer<typeof CodexRespawnMarkerSchema> {
   try {
-    return CodexRespawnMarkerSchema.parse(JSON.parse(readFileSync(marker, "utf8")));
+    return readJsonFile(marker, CodexRespawnMarkerSchema);
   } catch (e) {
     log("codexsupervisor.marker_invalid", { err: errorMessage(e) });
     throw new Error(

package/src/entries/stopfailurehook.ts

@@ -82,7 +82,7 @@ export async function runStopFailureHook(): Promise<number> {
 
     const decision = await evaluateAndMaybeSwap(claude, now, canRespawn && enforced != null, enforced, { waiterId: canRespawn ? session?.sid : undefined });
     if (enforced && session && canRespawn && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
-      writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: false });
+      writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: false, origin: "stopfailure" });
       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

@@ -26,7 +26,7 @@ export async function runBoundaryHook(event: "stop" | "sessionstart"): Promise<n
     }
     const decision = await evaluateAndMaybeSwap(claude, Date.now(), session != null, null, { waiterId: session?.sid });
     if (session && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
-      writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? Date.now(), compact: true });
+      writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? Date.now(), compact: true, origin: event });
       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) {

package/src/entries/supervisor.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, readdirSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync, readdirSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { FileSink, Subprocess } from "bun";
 import { maxBy } from "es-toolkit";
@@ -16,7 +16,7 @@ import { teeObservation } from "../lib/sample.ts";
 import { exitStatus, loopGuardTripped, raceMarkerOrExit, recordPresenceOrStop, runPassthrough } from "../lib/supervise.ts";
 import { saveTermios } from "../lib/tty.ts";
 import { liveSessionId, loadSessionFlags, pruneStaleSessions, saveSessionFlags, writeRespawnMarker } from "../lib/sessions.ts";
-import { loadAccounts, loadConfig, releaseWaitClaim } from "../lib/state.ts";
+import { loadAccounts, loadConfig, readJsonFile, releaseWaitClaim } from "../lib/state.ts";
 import { gatedFamilies, modelFromFlag } from "../lib/usage.ts";
 import { RespawnMarkerSchema, type Account, type Config, type ModelInfo } from "../lib/types.ts";
 import { errorMessage, log } from "../lib/log.ts";
@@ -183,7 +183,7 @@ type MarkerGate = {
 function consumableMarker(marker: string, gate: MarkerGate): z.infer<typeof RespawnMarkerSchema> | null {
   let m: z.infer<typeof RespawnMarkerSchema>;
   try {
-    m = RespawnMarkerSchema.parse(JSON.parse(readFileSync(marker, "utf8")));
+    m = readJsonFile(marker, RespawnMarkerSchema);
   } catch (e) {
     log("supervisor.marker_invalid", { err: errorMessage(e) });
     throw new Error(
@@ -225,7 +225,7 @@ async function moveExhaustedSeat(seat: Account, sid: string, gate: MarkerGate, m
     const decision = await evaluateAndMaybeSwap(claude, now, true, null, { seatId: seat.id, sessionFamilies: families, waiterId: sid });
     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, live: liveSessionId(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, origin: "seatwatch" });
     }
   } catch (e) {
     log("supervisor.seat_watch_error", { err: errorMessage(e) });
@@ -264,11 +264,14 @@ async function countdownWait(acct: string, until: number, out: { stream: boolean
   return aborted;
 }
 
-function resumePrompt(compacted: boolean): string {
-  const moved = compacted
+function resumePrompt(input: { compacted: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"] }): string {
+  const moved = input.compacted
     ? "tokenmaxxing compacted this conversation and resumed the session on an account with quota headroom."
     : "tokenmaxxing resumed this session on an account with quota headroom.";
-  return `${moved} Continue the task from where the previous turn left off. If the previous turn ended waiting on the user, restate what you need and wait.`;
+  if (input.origin === "stop") {
+    return `${moved} The previous turn finished before the move. If it waited on the user or completed the task, end this turn without restating it. If it waited on a background Bash task, Monitor, or Workflow run, relaunch that work, because the move ended it.`;
+  }
+  return `${moved} Continue the task from where the previous turn left off. If the previous turn ended waiting on the user, restate what you need and wait. The move restarted Claude Code, which ended every background Bash task, Monitor, and Workflow run this session started. Relaunch what the task still needs.`;
 }
 
 function userLine(text: string): string {
@@ -504,17 +507,20 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       rmSync(marker, { force: true });
       respawns++;
       noticeSid = m.sessionId;
-      const label = loadAccounts(claudePool).accounts.find((a) => a.id === m.accountId)?.label ?? m.accountId.slice(0, 8);
-      const resumable = existsSync(transcriptPath(m.sessionId));
+      const accounts = loadAccounts(claudePool).accounts;
+      const label = accounts.find((a) => a.id === m.accountId)?.label ?? m.accountId.slice(0, 8);
+      const walled = accounts.some((a) => a.id === seat?.id && a.enforcedUntil != null && a.enforcedUntil > Date.now());
+      const transcript = transcriptPath(m.sessionId);
+      const resumable = existsSync(transcript);
       let compacted = false;
-      if (m.compact && seat && resumable) {
+      if (m.compact && seat && resumable && !walled) {
         say(`\n\x1b[36m↻ tokenmaxxing: compacting the conversation on ${seat.label} before the move...\x1b[0m\n`, `tokenmaxxing: compacting the conversation on ${seat.label} before the move.`);
         const compactEnv: Record<string, string | undefined> = { ...childEnv, TOKENMAXXING_PROBE: "1", CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(seat.id) };
         delete compactEnv.TOKENMAXXING_SUPERVISED;
         delete compactEnv.TOKENMAXXING_SESSION_ID;
         delete compactEnv.TOKENMAXXING_LAUNCHED_AT;
         delete compactEnv.TOKENMAXXING_MODEL;
-        const outcome = await compactClaudeSession({ real, sid: m.sessionId, env: compactEnv });
+        const outcome = await compactClaudeSession({ real, sid: m.sessionId, transcript, env: compactEnv });
         log("supervisor.compact", { sid: m.sessionId.slice(0, 8), seat: seat.id.slice(0, 8), ok: outcome.ok, reason: outcome.ok ? undefined : outcome.reason });
         if (!outcome.ok) say(`\x1b[33m   compaction did not land (${outcome.reason}) - resuming with the full context\x1b[0m\n`, `tokenmaxxing: compaction did not land; resuming with the full context. (${outcome.reason})`);
         compacted = outcome.ok;
@@ -525,7 +531,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       await releaseClaim();
       wanted = m.accountId;
       saveSessionFlags(m.sessionId, persistable, process.cwd());
-      const prompt = resumable ? resumePrompt(compacted) : null;
+      const prompt = resumable ? resumePrompt({ compacted, origin: m.origin }) : null;
       firstLine = relay !== null && prompt !== null ? userLine(prompt) : null;
       launchArgs = [resumable ? "--resume" : "--session-id", m.sessionId, ...(relay === null && prompt !== null ? [prompt] : []), ...persistable];
       continue;

package/src/lib/claude.ts

@@ -12,7 +12,7 @@ import { pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./pick
 import { seatCounts } from "./presence.ts";
 import { StoreUnusableError, type Observation, type Provider, type SampleReport } from "./provider.ts";
 import { foldTee, sampleAccountUsage, teeObservation, usageBlockedUntil } from "./sample.ts";
-import { clearUsageSnapshot, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, saveAccounts, type Harvest } from "./state.ts";
+import { clearUsageSnapshot, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, readJsonFile, saveAccounts, type Harvest } from "./state.ts";
 import { saveTermios, restoreTermios } from "./tty.ts";
 import { fetchUsageDirect, gatedFamilies, mergeWindows, modelFromFlag, scrubCredentialEnv, windowsOf } from "./usage.ts";
 import { CredentialBlobSchema, JsonTextSchema, OAuthAccountSchema, type Account, type Config, type ModelInfo } from "./types.ts";
@@ -185,7 +185,7 @@ async function login(): Promise<Harvest | null> {
     let blob, oauthAccount;
     try {
       blob = CredentialBlobSchema.parse(JSON.parse(blobRaw));
-      oauthAccount = OAuthAccountSchema.parse(JSON.parse(readFileSync(cjPath, "utf8")).oauthAccount);
+      oauthAccount = readJsonFile(cjPath, z.object({ oauthAccount: OAuthAccountSchema })).oauthAccount;
     } catch {
       console.error(c.red("could not parse the onboarded account's credential/identity."));
       return null;

package/src/lib/codexauth.ts

@@ -1,22 +1,23 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, rmSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { writeFileAtomic } from "./atomic.ts";
 import { codexAuthJsonFor, codexPaths, codexStoreDirFor } from "./paths.ts";
+import { readJsonFile } from "./state.ts";
 import { CodexAuthJsonSchema, ErrnoSchema, type CodexAuthJson } from "./types.ts";
 
+const CodexAuthFileSchema = z
+  .looseObject({ tokens: z.unknown().optional() })
+  .transform((auth) => (auth.tokens === undefined || auth.tokens === null ? null : auth))
+  .pipe(CodexAuthJsonSchema.nullable());
+
 export function readCodexAuthAt(input: { path: string }): CodexAuthJson | null {
-  let raw: string;
   try {
-    raw = readFileSync(input.path, "utf8");
+    return readJsonFile(input.path, CodexAuthFileSchema);
   } catch (e) {
     if (ErrnoSchema.safeParse(e).data?.code === "ENOENT") return null;
     throw e;
   }
-  const parsed = JSON.parse(raw);
-  const probe = z.looseObject({ tokens: z.unknown().optional() }).parse(parsed);
-  if (probe.tokens === undefined || probe.tokens === null) return null;
-  return CodexAuthJsonSchema.parse(parsed);
 }
 
 export function readCodexStoreAuth(accountId: string): CodexAuthJson | null {

package/src/lib/compact.ts

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import { delay } from "es-toolkit";
 import { z } from "zod";
 import pkg from "../../package.json" with { type: "json" };
@@ -10,7 +11,10 @@ export type CompactOutcome = { ok: true } | { ok: false; reason: string };
 export const CLAUDE_COMPACT_KILL_MS = 300_000;
 const PIPE_GRACE_MS = 2_000;
 
-export async function compactClaudeSession(input: { real: string; sid: string; env: Record<string, string | undefined> }): Promise<CompactOutcome> {
+const CompactBoundarySchema = z.looseObject({ type: z.literal("system"), subtype: z.literal("compact_boundary") });
+
+export async function compactClaudeSession(input: { real: string; sid: string; transcript: string; env: Record<string, string | undefined> }): Promise<CompactOutcome> {
+  const offset = statSync(input.transcript).size;
   const p = Bun.spawn([input.real, "-p", "--resume", input.sid, "/compact"], {
     env: input.env,
     stdin: "ignore",
@@ -22,11 +26,13 @@ export async function compactClaudeSession(input: { real: string; sid: string; e
   const reads = Promise.all([p.stdout.text(), p.stderr.text()]);
   const settled = await Promise.race([reads, p.exited.then(() => delay(PIPE_GRACE_MS)).then(() => null)]);
   await p.exited;
+  const appended = await Bun.file(input.transcript).slice(offset).text();
+  if (appended.split("\n").some((line) => CompactBoundarySchema.safeParse(JsonTextSchema.safeParse(line).data).success)) return { ok: true };
   if (settled === null) return { ok: false, reason: "output pipes still open after child exit (leaked descendant)" };
   const [stdout, stderr] = settled;
-  if (p.exitCode === 0) return { ok: true };
   if (p.exitCode === null) return { ok: false, reason: `killed after ${CLAUDE_COMPACT_KILL_MS / 1000}s` };
-  return { ok: false, reason: `exit ${p.exitCode}: ${(stderr.trim() || stdout.trim()).slice(0, 200)}` };
+  const output = (stderr.trim() || stdout.trim()).slice(0, 200);
+  return { ok: false, reason: output ? `no compact boundary (exit ${p.exitCode}): ${output}` : `no compact boundary (exit ${p.exitCode})` };
 }
 
 export const CODEX_COMPACT_KILL_MS = 180_000;

package/src/lib/install.ts

@@ -7,7 +7,7 @@ import { codexPaths, codexStoreDirFor, HOME, optionalEnv, paths } from "./paths.
 import { writeFileAtomic } from "./atomic.ts";
 import { installedBin, installSettings, isOurHookCommand, uninstallSettings } from "./settings.ts";
 import { CLAUDE_BIN, resolveRealBin } from "./claudebin.ts";
-import { loadConfig } from "./state.ts";
+import { loadConfig, readJsonFile } from "./state.ts";
 import { ErrnoSchema } from "./types.ts";
 
 export type InstallOutcome = { claudeWrapper: string; installedBin: string; pathAhead: boolean; timerLoaded: boolean; hubLoaded: boolean; checkIntervalS: number };
@@ -134,7 +134,7 @@ function withoutOurCodexStopHooks(groups: { hooks: { type?: string; command?: st
 
 export function installCodexStopHook(): void {
   const current = existsSync(codexPaths.hooksJson)
-    ? CodexHooksFileSchema.parse(JSON.parse(readFileSync(codexPaths.hooksJson, "utf8")))
+    ? readJsonFile(codexPaths.hooksJson, CodexHooksFileSchema)
     : CodexHooksFileSchema.parse({});
   const next = {
     ...current,
@@ -151,7 +151,7 @@ export function installCodexStopHook(): void {
 
 export function uninstallCodexStopHook(): void {
   if (!existsSync(codexPaths.hooksJson)) return;
-  const current = CodexHooksFileSchema.parse(JSON.parse(readFileSync(codexPaths.hooksJson, "utf8")));
+  const current = readJsonFile(codexPaths.hooksJson, CodexHooksFileSchema);
   const next = {
     ...current,
     hooks: {
@@ -166,7 +166,7 @@ export function codexStopHookGroupIndex(): number | null {
   if (!existsSync(codexPaths.hooksJson)) return null;
   let parsed: z.infer<typeof CodexHooksFileSchema>;
   try {
-    parsed = CodexHooksFileSchema.parse(JSON.parse(readFileSync(codexPaths.hooksJson, "utf8")));
+    parsed = readJsonFile(codexPaths.hooksJson, CodexHooksFileSchema);
   } catch {
     return null;
   }

package/src/lib/presence.ts

@@ -4,7 +4,8 @@ import { countBy } from "es-toolkit";
 import { z } from "zod";
 import { writeFileAtomic } from "./atomic.ts";
 import { pidExists, pidStartTime } from "./proc.ts";
-import { ErrnoSchema } from "./types.ts";
+import { readJsonFile } from "./state.ts";
+import { ErrnoSchema, JsonTextSchema } from "./types.ts";
 
 const PresenceSchema = z.object({
   accountId: z.string(),
@@ -19,14 +20,12 @@ export function writePresence(input: { dir: string; id: string; accountId: strin
 }
 
 export function presencePid(input: { dir: string; id: string }): number | null {
-  let raw: string;
   try {
-    raw = readFileSync(join(input.dir, input.id), "utf8");
+    return readJsonFile(join(input.dir, input.id), PresenceSchema).pid;
   } 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 {
@@ -47,13 +46,7 @@ export function livingPresences(dir: string): LivingPresence[] {
       if (ErrnoSchema.safeParse(e).data?.code === "ENOENT") continue;
       throw e;
     }
-    const parsed = PresenceSchema.safeParse((() => {
-      try {
-        return JSON.parse(raw);
-      } catch {
-        return null;
-      }
-    })());
+    const parsed = PresenceSchema.safeParse(JsonTextSchema.safeParse(raw).data);
     if (!parsed.success) {
       throw new Error(`${file} is not a readable presence record - it may belong to a RUNNING session, refusing to treat it as absent; remove the file (or respawn that session) to proceed`);
     }

package/src/lib/sessions.ts

@@ -1,10 +1,11 @@
-import { existsSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, type Dirent } from "node:fs";
+import { existsSync, readdirSync, realpathSync, rmSync, statSync, type Dirent } from "node:fs";
 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 { readJsonFile } from "./state.ts";
 import { spawnedThroughShellsBy } from "./proc.ts";
 import type { RespawnMarkerSchema } from "./types.ts";
 
@@ -25,7 +26,7 @@ export function saveSessionFlags(sid: string, flags: string[], cwd: string): voi
 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")));
+  return readJsonFile(f, SessionSchema);
 }
 
 export function loadSessionFlags(sid: string): string[] | null {
@@ -123,13 +124,14 @@ export function adoptLiveSession(session: SupervisedSession, stdinSid: string |
   return { ...session, live: stdinSid };
 }
 
-export function writeRespawnMarker(input: { session: SupervisedSession; accountId: string; waitUntil: number; compact: boolean }): void {
+export function writeRespawnMarker(input: { session: SupervisedSession; accountId: string; waitUntil: number; compact: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"] }): void {
   const payload: z.infer<typeof RespawnMarkerSchema> = {
     accountId: input.accountId,
     ts: Date.now(),
     waitUntil: input.waitUntil,
     sessionId: input.session.live,
     compact: input.compact,
+    origin: input.origin,
     ...(input.session.launchedAt != null ? { launchedAt: input.session.launchedAt } : {}),
   };
   writeFileAtomic(join(paths.respawnDir, input.session.sid), JSON.stringify(payload));

package/src/lib/settings.ts

@@ -1,8 +1,10 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { paths } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
+import { readJsonFile } from "./state.ts";
+import { JsonTextSchema } from "./types.ts";
 
 export function installedBin(): string {
   return join(paths.binDir, "tokenmaxxing");
@@ -31,7 +33,7 @@ const STOP_FAILURE_MATCHER = "rate_limit";
 
 function readSettings(): Settings {
   if (!existsSync(paths.claudeSettings)) return {};
-  return SettingsSchema.parse(JSON.parse(readFileSync(paths.claudeSettings, "utf8")));
+  return readJsonFile(paths.claudeSettings, SettingsSchema);
 }
 
 function writeSettings(s: Settings): void {
@@ -71,13 +73,7 @@ export function isOurHookCommand(cmd: string, sub: string): boolean {
   if (!cmd.endsWith(` ${sub}`)) return false;
   const quotedPath = cmd.slice(0, cmd.length - (sub.length + 1));
   if (!quotedPath.startsWith('"') || !quotedPath.endsWith('"')) return false;
-  let path: unknown;
-  try {
-    path = JSON.parse(quotedPath);
-  } catch {
-    return false;
-  }
-  const parsed = z.string().safeParse(path);
+  const parsed = z.string().safeParse(JsonTextSchema.safeParse(quotedPath).data);
   return parsed.success && parsed.data.endsWith("/tokenmaxxing");
 }
 

package/src/lib/state.ts

@@ -7,6 +7,7 @@ import {
   AccountsIndexSchema,
   ConfigSchema,
   ErrnoSchema,
+  JsonTextSchema,
   UsageStateSchema,
   WaitQueueSchema,
   type Account,
@@ -17,21 +18,19 @@ import {
   type Window,
 } from "./types.ts";
 
-export function loadConfig(): Config {
-  let raw: unknown = {};
-  if (existsSync(paths.configJson)) {
-    try {
-      raw = JSON.parse(readFileSync(paths.configJson, "utf8"));
-    } catch {
-      throw new Error(`${paths.configJson} is corrupt (unparsable JSON) - fix or remove it`);
-    }
-  }
-  const parsed = ConfigSchema.safeParse(raw);
+export function readJsonFile<T extends z.ZodType>(path: string, schema: T): z.output<T> {
+  const json = JsonTextSchema.safeParse(readFileSync(path, "utf8"));
+  if (!json.success) throw new Error(`${path} is corrupt (unparsable JSON) - repair or remove the file`);
+  const parsed = schema.safeParse(json.data);
   if (!parsed.success) {
     const fields = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join(", ");
-    throw new Error(`${paths.configJson} is invalid (${fields}) - fix or remove the offending values`);
+    throw new Error(`${path} does not match its schema (${fields}) - repair or remove the file`);
   }
-  const cfg = parsed.data;
+  return parsed.data;
+}
+
+export function loadConfig(): Config {
+  const cfg = existsSync(paths.configJson) ? readJsonFile(paths.configJson, ConfigSchema) : ConfigSchema.parse({});
   cfg.claudeBin = optionalEnv("TOKENMAXXING_CLAUDE_BIN") ?? cfg.claudeBin;
   cfg.codexBin = optionalEnv("TOKENMAXXING_CODEX_BIN") ?? cfg.codexBin;
   cfg.grokBin = optionalEnv("TOKENMAXXING_GROK_BIN") ?? cfg.grokBin;
@@ -42,10 +41,7 @@ export function loadConfig(): Config {
 export type BinKey = "claudeBin" | "codexBin" | "grokBin" | "opencodeBin";
 
 export function pinBinOverride(input: { key: BinKey; bin: string }): void {
-  let raw: Record<string, unknown> = {};
-  if (existsSync(paths.configJson)) {
-    raw = z.record(z.string(), z.unknown()).parse(JSON.parse(readFileSync(paths.configJson, "utf8")));
-  }
+  const raw: Record<string, unknown> = existsSync(paths.configJson) ? readJsonFile(paths.configJson, z.record(z.string(), z.unknown())) : {};
   raw[input.key] = input.bin;
   writeFileAtomic(paths.configJson, JSON.stringify(raw, null, 2) + "\n");
 }
@@ -54,17 +50,7 @@ const emptyIndex = (): AccountsIndex => ({ version: 2, accounts: [] });
 
 export function loadAccounts(pool: PoolPaths): AccountsIndex {
   if (!existsSync(pool.accountsJson)) return emptyIndex();
-  let json: unknown;
-  try {
-    json = JSON.parse(readFileSync(pool.accountsJson, "utf8"));
-  } catch {
-    throw new Error(`${pool.accountsJson} is corrupt (unparsable JSON) - refusing to treat a damaged pool as empty; repair or remove the file`);
-  }
-  const parsed = AccountsIndexSchema.safeParse(json);
-  if (!parsed.success) {
-    throw new Error(`${pool.accountsJson} does not match the accounts schema - refusing to treat a damaged pool as empty; repair or remove the file`);
-  }
-  return parsed.data;
+  return readJsonFile(pool.accountsJson, AccountsIndexSchema);
 }
 
 export function saveAccounts(pool: PoolPaths, idx: AccountsIndex): void {
@@ -73,17 +59,7 @@ export function saveAccounts(pool: PoolPaths, idx: AccountsIndex): void {
 
 function loadWaitQueue(): WaitClaim[] {
   if (!existsSync(claudePool.waitQueueJson)) return [];
-  let json: unknown;
-  try {
-    json = JSON.parse(readFileSync(claudePool.waitQueueJson, "utf8"));
-  } catch {
-    throw new Error(`${claudePool.waitQueueJson} is corrupt (unparsable JSON) - refusing to treat a damaged wait queue as empty; repair or remove the file`);
-  }
-  const parsed = WaitQueueSchema.safeParse(json);
-  if (!parsed.success) {
-    throw new Error(`${claudePool.waitQueueJson} does not match the wait-queue schema - refusing to treat a damaged wait queue as empty; repair or remove the file`);
-  }
-  return parsed.data.claims;
+  return readJsonFile(claudePool.waitQueueJson, WaitQueueSchema).claims;
 }
 
 function saveWaitQueue(claims: WaitClaim[]): void {

package/src/lib/types.ts

@@ -147,6 +147,7 @@ export const RespawnMarkerSchema = z.object({
   waitUntil: z.number(),
   sessionId: z.string(),
   compact: z.boolean(),
+  origin: z.enum(["stop", "sessionstart", "stopfailure", "seatwatch"]),
   launchedAt: z.number().optional(),
 });
 

package/src/lib/update.ts

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { z } from "zod";
 import { writeFileAtomic } from "./atomic.ts";
@@ -8,6 +8,7 @@ import { isNixPackaged } from "./install.ts";
 import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { env, HOME, optionalEnv, paths } from "./paths.ts";
+import { readJsonFile } from "./state.ts";
 
 const UPDATE_INTERVAL_MS = 24 * 60 * 60 * 1000;
 const INSTALL_DEADLINE_MS = 60_000;
@@ -67,18 +68,12 @@ function detectGlobalRoot(): string | null {
 }
 
 function installedVersion(root: string): string {
-  return VersionSchema.parse(JSON.parse(readFileSync(join(packageDir(root), "package.json"), "utf8"))).version;
+  return readJsonFile(join(packageDir(root), "package.json"), VersionSchema).version;
 }
 
 function isDue(now: number): boolean {
   if (!existsSync(updateJson)) return true;
-  let json: unknown;
-  try {
-    json = JSON.parse(readFileSync(updateJson, "utf8"));
-  } catch {
-    throw new Error(`${updateJson} is corrupt (unparsable JSON) - repair or remove the file`);
-  }
-  return now - AttemptSchema.parse(json).attemptedAt >= UPDATE_INTERVAL_MS;
+  return now - readJsonFile(updateJson, AttemptSchema).attemptedAt >= UPDATE_INTERVAL_MS;
 }
 
 async function updateToLatest(root: string): Promise<void> {