tokenmaxxing 1.78.0 → 1.80.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.78.0",
+  "version": "1.80.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/cli/doctor.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { CLAUDE_BIN, verifyRealBin } from "../lib/claudebin.ts";
 import { checkSettings, installedBin } from "../lib/settings.ts";
-import { checkTimerHealthy, codexStoreHookTrust, findClaudeShadowers, hubServiceHealthy, isBinDirAhead, shellRcPath, skipImperativeHub, timerActivationHint } from "../lib/install.ts";
+import { activationHint, CHECK_JOB, codexStoreHookTrust, findClaudeShadowers, HUB_JOB, isBinDirAhead, jobHealthy, shellRcPath } from "../lib/install.ts";
 import { errorMessage } from "../lib/log.ts";
 import { claudePool, codexPool, paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
@@ -29,10 +29,10 @@ export async function cmdDoctor(): Promise<number> {
   check(s.stopOk, "Stop hook installed in settings.json", "run `tokenmaxxing init`");
   check(s.stopFailureOk, "StopFailure hook installed in settings.json", "run `tokenmaxxing init`");
   check(s.sessionStartOk, "SessionStart hook installed in settings.json", "run `tokenmaxxing init`");
-  check(checkTimerHealthy(), "periodic check timer active", timerActivationHint());
+  check(jobHealthy(CHECK_JOB), "periodic check timer active", activationHint(CHECK_JOB));
   if (existsSync(paths.supervisorLink)) {
-    if (skipImperativeHub()) note("usage hub service is owned outside init (TOKENMAXXING_SKIP_HUB set) - not verified here");
-    else check(hubServiceHealthy(), "usage hub service active", "run `tokenmaxxing init` (it writes the unit and activates it)");
+    if (HUB_JOB.skip()) note("usage hub service is owned outside init (TOKENMAXXING_SKIP_HUB set) - not verified here");
+    else check(jobHealthy(HUB_JOB), "usage hub service active", "run `tokenmaxxing init` (it writes the unit and activates it)");
   }
 
   const idx = loadAccounts(claudePool);

package/src/cli/serve.ts

@@ -7,7 +7,7 @@ import { claude } from "../lib/claude.ts";
 import { codex, observeCodex } from "../lib/codex.ts";
 import { CODEX_USAGE_URL } from "../lib/codexusage.ts";
 import { errorMessage, log } from "../lib/log.ts";
-import { hubDeactivationHint } from "../lib/install.ts";
+import { deactivationHint, HUB_JOB } from "../lib/install.ts";
 import { paths } from "../lib/paths.ts";
 import { isExhausted, thresholdBars } from "../lib/picker.ts";
 import type { Provider } from "../lib/provider.ts";
@@ -215,7 +215,7 @@ export async function cmdServe(args: string[]): Promise<number> {
       },
     });
   } catch (e) {
-    emitError({ message: `cannot bind localhost:${cfg.hub.port}: ${errorMessage(e)} (another \`tokenmaxxing serve\` or the usage hub service may already hold the port - stop it first: ${hubDeactivationHint()})` });
+    emitError({ message: `cannot bind localhost:${cfg.hub.port}: ${errorMessage(e)} (another \`tokenmaxxing serve\` or the usage hub service may already hold the port - stop it first: ${deactivationHint(HUB_JOB)})` });
     return 1;
   }
   console.log(`${c.green("✓")} serving the CLIProxyAPI-compatible usage API at http://localhost:${server.port}/v0/management`);

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/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(

package/src/lib/claude.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { z } from "zod";
 import { readItem, writeItem, deleteItem, isolatedTarget, readStore, storeTarget, claudeAiOauthOnly } from "./credstore.ts";
 import { CLAUDE_BIN, resolveRealBin, resolveVerifiedClaude } from "./claudebin.ts";
-import { ensurePathInRc, hubActivationHint, installSupervisor, managedShellRcSkipLines, shellRcPath, timerActivationHint } from "./install.ts";
+import { activationHint, CHECK_JOB, ensurePathInRc, HUB_JOB, installSupervisor, managedShellRcSkipLines, shellRcPath } from "./install.ts";
 import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { claudeTierLabel, describeIdentity, fetchTokenIdentity, isDeadCredential, InvalidGrantError } from "./oauth.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;
@@ -256,9 +256,9 @@ function install(): void {
   const out = installSupervisor();
   console.log(`${c.green("✓")} installed ${c.bold("claude")} supervisor + statusLine/Stop/StopFailure/SessionStart hooks`);
   if (out.timerLoaded) console.log(`${c.green("✓")} periodic check timer active (every ${out.checkIntervalS}s)`);
-  else console.log(c.yellow(`⚠ check timer written but not activated - run: ${timerActivationHint()}`));
+  else console.log(c.yellow(`⚠ check timer written but not activated - run: ${activationHint(CHECK_JOB)}`));
   if (out.hubLoaded) console.log(`${c.green("✓")} usage hub service active`);
-  else console.log(c.yellow(`⚠ usage hub service written but not activated - run: ${hubActivationHint()}`));
+  else console.log(c.yellow(`⚠ usage hub service written but not activated - run: ${activationHint(HUB_JOB)}`));
   if (!out.pathAhead) {
     console.log();
     ensurePathAhead();

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/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 };
@@ -36,11 +36,11 @@ export function isNixPackaged(): boolean {
   }
 }
 
-export function skipImperativeTimer(): boolean {
+function skipImperativeTimer(): boolean {
   return envFlag("TOKENMAXXING_SKIP_TIMER");
 }
 
-export function skipImperativeHub(): boolean {
+function skipImperativeHub(): boolean {
   return envFlag("TOKENMAXXING_SKIP_HUB");
 }
 
@@ -106,8 +106,8 @@ export function installSupervisor(): InstallOutcome {
     claudeWrapper: paths.supervisorLink,
     installedBin: target,
     pathAhead: isBinDirAhead(),
-    timerLoaded: installCheckTimer(checkIntervalS),
-    hubLoaded: installHubService(),
+    timerLoaded: installJob(CHECK_JOB, checkIntervalS),
+    hubLoaded: installJob(HUB_JOB, checkIntervalS),
     checkIntervalS,
   };
 }
@@ -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;
   }
@@ -205,9 +205,67 @@ export function uninstallCodexSupervisor(): void {
   if (existsSync(codexSupervisorLink())) rmSync(codexSupervisorLink(), { force: true });
 }
 
-const LAUNCHD_LABEL = "com.tokenmaxxing.check";
-const LAUNCHD_HUB_LABEL = "com.tokenmaxxing.hub";
-const HUB_UNIT = "tokenmaxxing-hub.service";
+export type UnitJob = {
+  label: string;
+  arg: string;
+  log: string;
+  skip: () => boolean;
+  unit: string;
+  launchd: (intervalS: number) => string;
+  systemd: Record<string, (exec: string, intervalS: number) => string>;
+};
+
+export const CHECK_JOB: UnitJob = {
+  label: "com.tokenmaxxing.check",
+  arg: "check",
+  log: "check.stderr.log",
+  skip: skipImperativeTimer,
+  unit: "tokenmaxxing-check.timer",
+  launchd: (intervalS) => `  <key>StartInterval</key><integer>${intervalS}</integer>\n`,
+  systemd: {
+    "tokenmaxxing-check.service": (exec) => `[Unit]
+Description=tokenmaxxing account-switch check
+
+[Service]
+Type=oneshot
+ExecStart=${exec}
+${systemdEnv()}`,
+    "tokenmaxxing-check.timer": (_exec, intervalS) => `[Unit]
+Description=tokenmaxxing periodic account-switch check
+
+[Timer]
+OnBootSec=${intervalS}
+OnUnitActiveSec=${intervalS}
+AccuracySec=${Math.max(1, Math.floor(intervalS / 12))}
+
+[Install]
+WantedBy=timers.target
+`,
+  },
+};
+
+export const HUB_JOB: UnitJob = {
+  label: "com.tokenmaxxing.hub",
+  arg: "serve",
+  log: "hub.stderr.log",
+  skip: skipImperativeHub,
+  unit: "tokenmaxxing-hub.service",
+  launchd: () => `  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n  <key>RunAtLoad</key><true/>\n`,
+  systemd: {
+    "tokenmaxxing-hub.service": (exec) => `[Unit]
+Description=tokenmaxxing usage hub
+StartLimitIntervalSec=0
+
+[Service]
+ExecStart=${exec}
+${systemdEnv()}Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`,
+  },
+};
 
 function launchdPlist(label: string): string {
   return join(paths.launchdAgentsDir, `${label}.plist`);
@@ -233,110 +291,56 @@ function launchdEnv(): string {
   return `  <key>EnvironmentVariables</key><dict><key>TOKENMAXXING_HOME</key><string>${escape(paths.home)}</string></dict>\n`;
 }
 
-function installCheckTimer(intervalS: number): boolean {
-  if (skipImperativeTimer()) return true;
+function installJob(job: UnitJob, intervalS: number): boolean {
+  if (job.skip()) return true;
 
   if (process.platform === "darwin") {
-    const plist = launchdPlist(LAUNCHD_LABEL);
+    const plist = launchdPlist(job.label);
     writeFileAtomic(
       plist,
       `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-  <key>Label</key><string>${LAUNCHD_LABEL}</string>
-  <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>check</string></array>
-  <key>StartInterval</key><integer>${intervalS}</integer>
-${launchdEnv()}  <key>StandardOutPath</key><string>/dev/null</string>
-  <key>StandardErrorPath</key><string>${escape(join(paths.home, "check.stderr.log"))}</string>
+  <key>Label</key><string>${job.label}</string>
+  <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>${job.arg}</string></array>
+${job.launchd(intervalS)}${launchdEnv()}  <key>StandardOutPath</key><string>/dev/null</string>
+  <key>StandardErrorPath</key><string>${escape(join(paths.home, job.log))}</string>
 </dict>
 </plist>
 `,
       0o644,
     );
     const domain = launchdDomain();
-    run(["launchctl", "bootout", `${domain}/${LAUNCHD_LABEL}`]);
-    return run(["launchctl", "bootstrap", domain, plist]) || checkTimerHealthy();
-  }
-
-  const exec = `"${installedBin().replaceAll("%", "%%")}" check`;
-  writeFileAtomic(
-    join(paths.systemdUserDir, "tokenmaxxing-check.service"),
-    `[Unit]
-Description=tokenmaxxing account-switch check
-
-[Service]
-Type=oneshot
-ExecStart=${exec}
-${systemdEnv()}`,
-    0o644,
-  );
-  writeFileAtomic(
-    join(paths.systemdUserDir, "tokenmaxxing-check.timer"),
-    `[Unit]
-Description=tokenmaxxing periodic account-switch check
-
-[Timer]
-OnBootSec=${intervalS}
-OnUnitActiveSec=${intervalS}
-AccuracySec=${Math.max(1, Math.floor(intervalS / 12))}
-
-[Install]
-WantedBy=timers.target
-`,
-    0o644,
-  );
-  return (
-    run(["systemctl", "--user", "daemon-reload"]) &&
-    run(["systemctl", "--user", "enable", "--now", "tokenmaxxing-check.timer"])
-  );
-}
-
-export function timerActivationHint(): string {
-  if (process.platform === "darwin") {
-    return `launchctl bootstrap gui/$(id -u) ${launchdPlist(LAUNCHD_LABEL)}`;
-  }
-  return "systemctl --user daemon-reload && systemctl --user enable --now tokenmaxxing-check.timer";
-}
-
-export function hubActivationHint(): string {
-  if (process.platform === "darwin") {
-    return `launchctl bootstrap gui/$(id -u) ${launchdPlist(LAUNCHD_HUB_LABEL)}`;
+    run(["launchctl", "bootout", `${domain}/${job.label}`]);
+    return run(["launchctl", "bootstrap", domain, plist]) || jobHealthy(job);
   }
-  return `systemctl --user daemon-reload && systemctl --user enable --now ${HUB_UNIT}`;
-}
 
-export function checkTimerHealthy(): boolean {
-  if (skipImperativeTimer()) return true;
-  if (process.platform === "darwin") {
-    return existsSync(launchdPlist(LAUNCHD_LABEL)) && run(["launchctl", "print", `${launchdDomain()}/${LAUNCHD_LABEL}`]);
-  }
-  return (
-    existsSync(join(paths.systemdUserDir, "tokenmaxxing-check.timer")) &&
-    run(["systemctl", "--user", "is-active", "--quiet", "tokenmaxxing-check.timer"])
-  );
+  const exec = `"${installedBin().replaceAll("%", "%%")}" ${job.arg}`;
+  for (const [file, text] of Object.entries(job.systemd)) writeFileAtomic(join(paths.systemdUserDir, file), text(exec, intervalS), 0o644);
+  return run(["systemctl", "--user", "daemon-reload"]) && run(["systemctl", "--user", "enable", "--now", job.unit]);
 }
 
-export function hubServiceHealthy(): boolean {
-  if (skipImperativeHub()) return true;
+export function activationHint(job: UnitJob): string {
   if (process.platform === "darwin") {
-    return existsSync(launchdPlist(LAUNCHD_HUB_LABEL)) && run(["launchctl", "print", `${launchdDomain()}/${LAUNCHD_HUB_LABEL}`]);
+    return `launchctl bootstrap gui/$(id -u) ${launchdPlist(job.label)}`;
   }
-  return existsSync(join(paths.systemdUserDir, HUB_UNIT)) && run(["systemctl", "--user", "is-active", "--quiet", HUB_UNIT]);
+  return `systemctl --user daemon-reload && systemctl --user enable --now ${job.unit}`;
 }
 
-export function timerDeactivationHint(): string {
+export function jobHealthy(job: UnitJob): boolean {
+  if (job.skip()) return true;
   if (process.platform === "darwin") {
-    return `launchctl bootout gui/$(id -u)/${LAUNCHD_LABEL}`;
+    return existsSync(launchdPlist(job.label)) && run(["launchctl", "print", `${launchdDomain()}/${job.label}`]);
   }
-  return "systemctl --user disable --now tokenmaxxing-check.timer";
+  return existsSync(join(paths.systemdUserDir, job.unit)) && run(["systemctl", "--user", "is-active", "--quiet", job.unit]);
 }
 
-export function hubDeactivationHint(): string {
+export function deactivationHint(job: UnitJob): string {
   if (process.platform === "darwin") {
-    return `launchctl bootout gui/$(id -u)/${LAUNCHD_HUB_LABEL}`;
+    return `launchctl bootout gui/$(id -u)/${job.label}`;
   }
-  return `systemctl --user disable --now ${HUB_UNIT}`;
+  return `systemctl --user disable --now ${job.unit}`;
 }
 
 function launchdJobLoaded(label: string): "loaded" | "not-loaded" | "unavailable" {
@@ -361,108 +365,42 @@ function systemdUnitActive(unit: string): "active" | "not-active" | "unavailable
   }
 }
 
-function removeTimerUnits(): void {
-  if (process.platform === "darwin") {
-    rmSync(launchdPlist(LAUNCHD_LABEL), { force: true });
-    return;
-  }
-  rmSync(join(paths.systemdUserDir, "tokenmaxxing-check.timer"), { force: true });
-  rmSync(join(paths.systemdUserDir, "tokenmaxxing-check.service"), { force: true });
+function jobFiles(job: UnitJob): string[] {
+  if (process.platform === "darwin") return [launchdPlist(job.label)];
+  return Object.keys(job.systemd).map((file) => join(paths.systemdUserDir, file));
+}
+
+function removeJobFiles(job: UnitJob): void {
+  for (const file of jobFiles(job)) rmSync(file, { force: true });
 }
 
 type UnitOutcome = "removed" | "skipped" | "still-loaded";
 
-function uninstallCheckTimer(live: boolean): UnitOutcome {
-  if (skipImperativeTimer()) return "skipped";
+function uninstallJob(job: UnitJob, live: boolean): UnitOutcome {
+  if (job.skip()) return "skipped";
   if (!live) {
-    removeTimerUnits();
+    removeJobFiles(job);
     return "removed";
   }
   if (process.platform === "darwin") {
-    const loaded = launchdJobLoaded(LAUNCHD_LABEL);
-    const deactivated = loaded === "loaded" ? run(["launchctl", "bootout", `${launchdDomain()}/${LAUNCHD_LABEL}`]) : loaded === "not-loaded";
-    removeTimerUnits();
+    const loaded = launchdJobLoaded(job.label);
+    const deactivated = loaded === "loaded" ? run(["launchctl", "bootout", `${launchdDomain()}/${job.label}`]) : loaded === "not-loaded";
+    removeJobFiles(job);
     return deactivated ? "removed" : "still-loaded";
   }
-  const active = systemdUnitActive("tokenmaxxing-check.timer");
-  const deactivated = active !== "unavailable" && (run(["systemctl", "--user", "disable", "--now", "tokenmaxxing-check.timer"]) || active === "not-active");
-  removeTimerUnits();
+  const active = systemdUnitActive(job.unit);
+  const deactivated = active !== "unavailable" && (run(["systemctl", "--user", "disable", "--now", job.unit]) || active === "not-active");
+  removeJobFiles(job);
   run(["systemctl", "--user", "daemon-reload"]);
   return deactivated ? "removed" : "still-loaded";
 }
 
-function installHubService(): boolean {
-  if (skipImperativeHub()) return true;
-
-  if (process.platform === "darwin") {
-    const plist = launchdPlist(LAUNCHD_HUB_LABEL);
-    writeFileAtomic(
-      plist,
-      `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key><string>${LAUNCHD_HUB_LABEL}</string>
-  <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>serve</string></array>
-  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
-  <key>RunAtLoad</key><true/>
-${launchdEnv()}  <key>StandardOutPath</key><string>/dev/null</string>
-  <key>StandardErrorPath</key><string>${escape(join(paths.home, "hub.stderr.log"))}</string>
-</dict>
-</plist>
-`,
-      0o644,
-    );
-    const domain = launchdDomain();
-    run(["launchctl", "bootout", `${domain}/${LAUNCHD_HUB_LABEL}`]);
-    return run(["launchctl", "bootstrap", domain, plist]) || hubServiceHealthy();
-  }
-
-  const exec = `"${installedBin().replaceAll("%", "%%")}" serve`;
-  writeFileAtomic(
-    join(paths.systemdUserDir, HUB_UNIT),
-    `[Unit]
-Description=tokenmaxxing usage hub
-StartLimitIntervalSec=0
-
-[Service]
-ExecStart=${exec}
-${systemdEnv()}Restart=on-failure
-RestartSec=5
-
-[Install]
-WantedBy=default.target
-`,
-    0o644,
-  );
-  return run(["systemctl", "--user", "daemon-reload"]) && run(["systemctl", "--user", "enable", "--now", HUB_UNIT]);
-}
-
-function removeHubUnits(): void {
-  if (process.platform === "darwin") {
-    rmSync(launchdPlist(LAUNCHD_HUB_LABEL), { force: true });
-    return;
-  }
-  rmSync(join(paths.systemdUserDir, HUB_UNIT), { force: true });
-}
-
-function uninstallHubService(live: boolean): UnitOutcome {
-  if (skipImperativeHub()) return "skipped";
-  if (!live) {
-    removeHubUnits();
-    return "removed";
-  }
-  if (process.platform === "darwin") {
-    const loaded = launchdJobLoaded(LAUNCHD_HUB_LABEL);
-    const deactivated = loaded === "loaded" ? run(["launchctl", "bootout", `${launchdDomain()}/${LAUNCHD_HUB_LABEL}`]) : loaded === "not-loaded";
-    removeHubUnits();
-    return deactivated ? "removed" : "still-loaded";
-  }
-  const active = systemdUnitActive(HUB_UNIT);
-  const deactivated = active !== "unavailable" && (run(["systemctl", "--user", "disable", "--now", HUB_UNIT]) || active === "not-active");
-  removeHubUnits();
-  run(["systemctl", "--user", "daemon-reload"]);
-  return deactivated ? "removed" : "still-loaded";
+function uninstallTarget(job: UnitJob, live: boolean): string {
+  const files = jobFiles(job).join(" and ");
+  if (!live) return files;
+  return process.platform === "darwin"
+    ? `${files} (and launchctl bootout ${launchdDomain()}/${job.label})`
+    : `${files} (and systemctl --user disable --now ${job.unit})`;
 }
 
 export function shellRcPath(): string | null {
@@ -563,20 +501,11 @@ export function onLoginHome(): boolean {
 }
 
 export function uninstallTargets(live: boolean): string[] {
-  const timer =
-    process.platform === "darwin"
-      ? `${launchdPlist(LAUNCHD_LABEL)}${live ? ` (and launchctl bootout ${launchdDomain()}/${LAUNCHD_LABEL})` : ""}`
-      : `${join(paths.systemdUserDir, "tokenmaxxing-check.timer")} and .service${live ? " (and systemctl --user disable --now tokenmaxxing-check.timer)" : ""}`;
-  const hub =
-    process.platform === "darwin"
-      ? `${launchdPlist(LAUNCHD_HUB_LABEL)}${live ? ` (and launchctl bootout ${launchdDomain()}/${LAUNCHD_HUB_LABEL})` : ""}`
-      : `${join(paths.systemdUserDir, HUB_UNIT)}${live ? ` (and systemctl --user disable --now ${HUB_UNIT})` : ""}`;
   const rc = shellRcPath();
   return [
     `${paths.claudeSettings}: the hook and statusline entries`,
     `${codexPaths.hooksJson}: the codex Stop hook entry`,
-    ...(skipImperativeTimer() ? [] : [timer]),
-    ...(skipImperativeHub() ? [] : [hub]),
+    ...[CHECK_JOB, HUB_JOB].filter((job) => !job.skip()).map((job) => uninstallTarget(job, live)),
     paths.supervisorLink,
     codexSupervisorLink(),
     join(paths.binDir, "xx"),
@@ -587,8 +516,8 @@ export function uninstallTargets(live: boolean): string[] {
 
 export function uninstallSupervisor(input: { live: boolean }): UninstallOutcome {
   uninstallSettings();
-  const timer = uninstallCheckTimer(input.live);
-  const hub = uninstallHubService(input.live);
+  const timer = uninstallJob(CHECK_JOB, input.live);
+  const hub = uninstallJob(HUB_JOB, input.live);
   uninstallCodexSupervisor();
   for (const f of [paths.supervisorLink, join(paths.binDir, "xx"), installedBin()]) {
     if (existsSync(f)) rmSync(f, { force: true });

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 {

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/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> {

package/src/main.ts

@@ -23,7 +23,7 @@ import { cmdCheck } from "./cli/check.ts";
 import { cmdConfig } from "./cli/config.ts";
 import { cmdSeat } from "./cli/seat.ts";
 import { cmdServe } from "./cli/serve.ts";
-import { hubDeactivationHint, onLoginHome, timerDeactivationHint, uninstallSupervisor, uninstallTargets } from "./lib/install.ts";
+import { CHECK_JOB, deactivationHint, HUB_JOB, onLoginHome, uninstallSupervisor, uninstallTargets } from "./lib/install.ts";
 import { errorMessage } from "./lib/log.ts";
 import { HOME } from "./lib/paths.ts";
 import { c, emitError } from "./cli/render.ts";
@@ -177,8 +177,8 @@ async function main(): Promise<number> {
         ...(out.pathLineRemoved ? ["rc PATH line"] : []),
       ];
       console.log(`removed ${removed.join(", ")}`);
-      if (out.timer === "still-loaded") console.log(c.yellow(`⚠ the check job may still be loaded - run: ${timerDeactivationHint()}`));
-      if (out.hub === "still-loaded") console.log(c.yellow(`⚠ the usage hub job may still be loaded - run: ${hubDeactivationHint()}`));
+      if (out.timer === "still-loaded") console.log(c.yellow(`⚠ the check job may still be loaded - run: ${deactivationHint(CHECK_JOB)}`));
+      if (out.hub === "still-loaded") console.log(c.yellow(`⚠ the usage hub job may still be loaded - run: ${deactivationHint(HUB_JOB)}`));
       if (!out.pathLineRemoved) console.log(c.dim("(no tokenmaxxing PATH line found in the shell rc)"));
       console.log(`kept: accounts.json, config.json, and every account credential store (claude: stores/ and its keychain items on macOS; codex: codex-stores/; grok: grok-stores/; opencode-go: opencode-go-stores/) - remove accounts with \`xx rm\` to delete their credentials`);
       return 0;