tokenmaxxing 0.2.0 → 0.2.1

package/src/cli/switch.ts

@@ -0,0 +1,61 @@
+// `tokenmaxxing switch [selector]` (also the bare `tokenmaxxing` / `xx`).
+// No selector → auto-pick the best available account. With a selector → switch to
+// that one. Manual/recovery tool: no threshold gate, runs under the flock. When
+// everything is depleted it still switches to the soonest-resetting account.
+
+import { withLock } from "../lib/lock.ts";
+import { paths } from "../lib/paths.ts";
+import { loadAccounts, loadConfig } from "../lib/state.ts";
+import { performSwap, chooseAndSwap } from "../lib/swap.ts";
+import { pickEarliestReset } from "../lib/picker.ts";
+import { InvalidGrantError } from "../lib/oauth.ts";
+import { findAccount } from "./rename.ts";
+import { c, fmtReset } from "./render.ts";
+
+export async function cmdSwitch(selector?: string): Promise<number> {
+  const idx0 = loadAccounts();
+  if (idx0.accounts.length < 2) {
+    console.error(c.yellow("need at least 2 accounts to switch - add one with `tokenmaxxing add`"));
+    return 1;
+  }
+  const cfg = loadConfig();
+  const now = Date.now();
+
+  return withLock(paths.lockFile, async () => {
+    const idx = loadAccounts();
+
+    if (selector) {
+      const target = findAccount(idx.accounts, selector);
+      if (!target) { console.error(c.red(`no account matches "${selector}"`)); return 1; }
+      if (target.accountUuid === idx.activeAccountUuid) { console.log(`already on ${c.bold(target.label)}`); return 0; }
+      if (target.needsReauth) { console.error(c.red(`${target.label} needs re-auth - \`tokenmaxxing add\``)); return 1; }
+      try {
+        await performSwap(target);
+      } catch (e) {
+        if (e instanceof InvalidGrantError) { console.error(c.red(`${target.label}'s refresh token is dead - re-add it`)); return 1; }
+        throw e;
+      }
+      console.log(`${c.green("↻")} switched to ${c.bold(target.label)}`);
+      return 0;
+    }
+
+    // auto: best account under threshold
+    const landed = await chooseAndSwap({ now, threshold: cfg.threshold });
+    if (landed) {
+      console.log(`${c.green("↻")} switched to ${c.bold(landed.label)}`);
+      return 0;
+    }
+
+    // everything is depleted → switch to whichever recovers soonest
+    const earliest = pickEarliestReset(idx.accounts, { now, threshold: cfg.threshold, currentAccountUuid: idx.activeAccountUuid });
+    if (!earliest) { console.error(c.yellow("no switchable account (all need re-auth?)")); return 1; }
+    try {
+      await performSwap(earliest.account);
+    } catch (e) {
+      if (e instanceof InvalidGrantError) { console.error(c.red(`${earliest.account.label}'s refresh token is dead`)); return 1; }
+      throw e;
+    }
+    console.log(`${c.yellow("↻")} all accounts at limit - switched to ${c.bold(earliest.account.label)} (${fmtReset(earliest.availableAt, now)})`);
+    return 0;
+  });
+}

package/src/entries/sessionstart.ts

@@ -0,0 +1,39 @@
+// SessionStart hook. A launch/resume backstop: if the active account is already
+// over threshold with FRESH usage (e.g. a prior session left it exhausted), swap
+// the credential before this session's first turn so it starts on a good account.
+// Right after a respawn, usage.json is stale for the new org, so the org guard in
+// evaluateAndMaybeSwap makes this correctly no-op.
+
+import { z } from "zod";
+import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { log } from "../lib/log.ts";
+
+const SessionStartStdin = z.looseObject({
+  source: z.string().optional(), // startup | resume | clear | compact
+  session_id: z.string().optional(),
+});
+
+async function readStdin(): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  for await (const c of Bun.stdin.stream()) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runSessionStart(): Promise<number> {
+  if (process.env.TOKENMAXXING_PROBE) return 0;
+
+  const raw = await readStdin();
+  const parsed = SessionStartStdin.safeParse((() => { try { return JSON.parse(raw); } catch { return {}; } })());
+  const source = parsed.success ? parsed.data.source : undefined;
+
+  try {
+    const decision = await evaluateAndMaybeSwap();
+    if (decision.swapped && decision.account) {
+      // fresh session → it will read the new credential on its first API call.
+      log("sessionstart.swapped", { source, account: decision.account.accountUuid.slice(0, 8) });
+    }
+  } catch (e) {
+    log("sessionstart.error", { err: String((e as Error).message ?? e) });
+  }
+  return 0;
+}

package/src/entries/statusline.ts

@@ -0,0 +1,52 @@
+// statusLine shim. Reads Claude's statusLine stdin, tees the rate-limit data to
+// usage.json (write-on-change, O(ms)), then transparently delegates to the user's
+// prior statusLine command (same stdin) and passes its stdout through unchanged.
+// Must NEVER break the user's status line: every step is best-effort.
+
+import { readOAuthAccount } from "../lib/claudejson.ts";
+import { readPriorStatusLine } from "../lib/settings.ts";
+import { writeUsage } from "../lib/state.ts";
+import { parseStatusLineStdin, parseStatusLineModel } from "../lib/usage.ts";
+import type { UsageState } from "../lib/types.ts";
+
+async function readStdin(): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  for await (const c of Bun.stdin.stream()) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runStatusline(): Promise<number> {
+  const raw = await readStdin();
+
+  // 1) tee usage - best effort, never throws out.
+  try {
+    const obj = JSON.parse(raw);
+    const windows = parseStatusLineStdin(obj);
+    if (windows) {
+      const org = readOAuthAccount()?.organizationUuid ?? null;
+      const state: UsageState = { ...windows, org, ts: Date.now(), model: parseStatusLineModel(obj) };
+      writeUsage(state);
+    }
+  } catch {
+    // malformed stdin - skip usage, still delegate below
+  }
+
+  // 2) delegate to the prior statusLine, feeding it the same stdin.
+  const prior = readPriorStatusLine();
+  if (prior) {
+    try {
+      const p = Bun.spawn(["/bin/sh", "-c", prior], {
+        stdin: new TextEncoder().encode(raw),
+        stdout: "pipe",
+        stderr: "inherit",
+      });
+      const out = await new Response(p.stdout).text();
+      await p.exited;
+      if (out) process.stdout.write(out);
+      return p.exitCode ?? 0;
+    } catch {
+      // fall through to no-op
+    }
+  }
+  return 0;
+}

package/src/entries/stophook.ts

@@ -0,0 +1,48 @@
+// Stop hook. Fires when claude finishes a turn (transcript already committed).
+// If the active account crossed the threshold, swap the credential and - when
+// running under the supervisor - drop a respawn marker keyed by this session id.
+// The supervisor watches for the marker and SIGTERMs its child at this clean
+// boundary, then relaunches `--resume`. We never kill claude ourselves.
+
+import { join } from "node:path";
+import { z } from "zod";
+import { paths } from "../lib/paths.ts";
+import { writeFileAtomic } from "../lib/atomic.ts";
+import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { RespawnMarkerSchema } from "../lib/types.ts";
+import { log } from "../lib/log.ts";
+
+const StopStdin = z.looseObject({ session_id: z.string().optional() });
+
+async function readStdin(): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  for await (const c of Bun.stdin.stream()) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runStopHook(): Promise<number> {
+  // recursion guard - our own `-p '/usage'` probe re-enters hooks.
+  if (process.env.TOKENMAXXING_PROBE) return 0;
+
+  const raw = await readStdin();
+  const parsed = StopStdin.safeParse((() => { try { return JSON.parse(raw); } catch { return {}; } })());
+  const sessionId =
+    (parsed.success ? parsed.data.session_id : undefined) ?? process.env.TOKENMAXXING_SESSION_ID;
+
+  try {
+    const decision = await evaluateAndMaybeSwap();
+    // Respawn on a swap, or on a depleted-pool wait (relaunch after the reset).
+    if (decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
+      log(decision.swapped ? "stop.swapped" : "stop.wait", { account: decision.account.accountUuid.slice(0, 8), waitUntil: decision.waitUntil });
+      if (process.env.TOKENMAXXING_SUPERVISED === "1" && sessionId) {
+        const marker = join(paths.respawnDir, sessionId);
+        const payload = RespawnMarkerSchema.parse({ account: decision.account.label, ts: Date.now(), waitUntil: decision.waitUntil });
+        writeFileAtomic(marker, JSON.stringify(payload));
+        log("stop.marker", { session: sessionId.slice(0, 8) });
+      }
+    }
+  } catch (e) {
+    log("stop.error", { err: String((e as Error).message ?? e) });
+  }
+  return 0; // never block the stop
+}

package/src/entries/supervisor.ts

@@ -0,0 +1,202 @@
+// The `claude` supervisor. Invoked in place of claude (via ~/.config/tokenmaxxing/
+// bin/claude on PATH). Runs the REAL claude with inherited stdio (claude owns the
+// real terminal exactly as if run directly), pins a session id, and watches for a
+// respawn marker dropped by the Stop/SessionStart hook. When the marker appears it
+// SIGTERMs its own child at the (already-committed) turn boundary and relaunches
+// `claude --resume <id>` on the freshly-swapped account. Process/terminal manager
+// only - it never reads or proxies tokens.
+
+import { existsSync, mkdirSync, rmSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { maxBy } from "es-toolkit";
+import { z } from "zod";
+import { paths } from "../lib/paths.ts";
+import { resolveRealClaude } from "../lib/claudebin.ts";
+import { saveTermios, restoreTermios } from "../lib/tty.ts";
+import { loadSessionFlags, saveSessionFlags } from "../lib/sessions.ts";
+import { RespawnMarkerSchema } from "../lib/types.ts";
+import { log } from "../lib/log.ts";
+
+const NONINTERACTIVE_SUBCMDS = new Set([
+  "mcp", "config", "doctor", "update", "install", "migrate-installer",
+  "setup-token", "plugin", "agents", "completion", "help",
+]);
+
+const isUuid = (s: string) => z.uuid().safeParse(s).success;
+
+const AnalysisSchema = z.object({
+  manage: z.boolean(),
+  sessionId: z.string().nullable(),
+  resumeId: z.string().nullable(),
+  continueLatest: z.boolean(),
+});
+type Analysis = z.infer<typeof AnalysisSchema>;
+
+export function analyzeArgs(argv: string[]): Analysis {
+  let sessionId: string | null = null;
+  let resumeId: string | null = null;
+  let continueLatest = false;
+  let printMode = false;
+  let firstPositional: string | null = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "-p" || a === "--print") printMode = true;
+    else if (a === "--version" || a === "-v" || a === "--help" || a === "-h") printMode = true;
+    else if (a === "--session-id") sessionId = argv[++i] ?? null;
+    else if (a === "-c" || a === "--continue") continueLatest = true;
+    else if (a === "-r" || a === "--resume") {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("-") && isUuid(next)) { resumeId = next; i++; }
+    } else if (!a.startsWith("-") && firstPositional === null) {
+      firstPositional = a;
+    }
+  }
+
+  const isSubcmd = firstPositional !== null && NONINTERACTIVE_SUBCMDS.has(firstPositional);
+  const manage = !printMode && !isSubcmd && !process.env.TOKENMAXXING_PROBE;
+  return { manage, sessionId, resumeId, continueLatest };
+}
+
+/** Remove session-selecting flags so we can inject our own on respawn. */
+export function stripSessionFlags(argv: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--session-id") { i++; continue; }
+    if (a === "-c" || a === "--continue") continue;
+    if (a === "-r" || a === "--resume") {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("-") && isUuid(next)) i++;
+      continue;
+    }
+    out.push(a);
+  }
+  return out;
+}
+
+/** Newest transcript session id for the current cwd (for `-c`/`-r`-without-id). */
+function latestSessionForCwd(): string | null {
+  const slug = process.cwd().replace(/[/.]/g, "-");
+  const projDir = join(paths.claudeDir, "projects", slug);
+  if (!existsSync(projDir)) return null;
+  try {
+    const files = readdirSync(projDir)
+      .filter((f) => f.endsWith(".jsonl"))
+      .map((f) => ({ f, m: statSync(join(projDir, f)).mtimeMs }));
+    const newest = maxBy(files, (x) => x.m);
+    return newest ? newest.f.replace(/\.jsonl$/, "") : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Interruptible countdown until `until`, shown in the terminal (claude is dead,
+ *  so the statusLine can't render it). Ctrl-C resumes immediately. */
+async function countdownWait(acct: string, until: number): Promise<void> {
+  let aborted = false;
+  const onInt = () => { aborted = true; };
+  process.on("SIGINT", onInt);
+  process.stdout.write(`\n\x1b[36m⏳ tokenmaxxing: all accounts at their limit. Resuming on ${acct} when it resets (Ctrl-C to resume now).\x1b[0m\n`);
+  while (!aborted && Date.now() < until) {
+    const left = until - Date.now();
+    const m = Math.floor(left / 60000);
+    const s = Math.floor((left % 60000) / 1000);
+    process.stdout.write(`\r\x1b[36m   resuming in ${m}m ${String(s).padStart(2, "0")}s \x1b[0m`);
+    await Bun.sleep(1000);
+  }
+  process.removeListener("SIGINT", onInt);
+  process.stdout.write(`\n\x1b[36m↻ resuming on ${acct}…\x1b[0m\n`);
+}
+
+/** Entry point: `claude ...args`. */
+export async function runSupervisor(argv: string[]): Promise<number> {
+  const real = resolveRealClaude();
+  const info = analyzeArgs(argv);
+
+  // Pass-through: no session management, no respawn - exact stock behavior.
+  if (!info.manage) {
+    const p = Bun.spawn([real, ...argv], { stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+    await p.exited;
+    return p.exitCode ?? (p.signalCode ? 1 : 0);
+  }
+
+  // Decide the managed session id + whether we're resuming an existing one.
+  let base = stripSessionFlags(argv);
+  let sid: string;
+  let resuming = false;
+  if (info.sessionId) {
+    sid = info.sessionId;
+  } else if (info.resumeId) {
+    sid = info.resumeId;
+    resuming = true;
+  } else if (info.continueLatest) {
+    const latest = latestSessionForCwd();
+    if (latest) { sid = latest; resuming = true; } else sid = crypto.randomUUID();
+  } else {
+    sid = crypto.randomUUID();
+  }
+
+  // Restore the original launch flags when resuming a session with none given
+  // this time (a bare `claude --resume <id>`, or the depleted-pool recovery).
+  if (resuming && base.length === 0) {
+    const persisted = loadSessionFlags(sid);
+    if (persisted) base = persisted;
+  }
+  saveSessionFlags(sid, base, process.cwd());
+
+  let launchArgs = resuming ? ["--resume", sid, ...base] : ["--session-id", sid, ...base];
+
+  mkdirSync(paths.respawnDir, { recursive: true });
+  const marker = join(paths.respawnDir, sid);
+  const savedTermios = saveTermios();
+
+  // Supervisor survives the SIGINT/SIGHUP that flow to the foreground group;
+  // claude (the child, same pgrp) receives and handles them itself.
+  process.on("SIGINT", () => {});
+  process.on("SIGHUP", () => {});
+
+  let respawns = 0;
+  while (true) {
+    if (existsSync(marker)) rmSync(marker, { force: true });
+    log("supervisor.launch", { sid, respawns, args: launchArgs.join(" ") });
+
+    const child = Bun.spawn([real, ...launchArgs], {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: { ...process.env, TOKENMAXXING_SUPERVISED: "1", TOKENMAXXING_SESSION_ID: sid },
+    });
+
+    // Race the child's own exit against the appearance of a respawn marker.
+    let done = false;
+    const markerWatch = (async () => {
+      while (!done) {
+        if (await Bun.file(marker).exists()) return true;
+        await Bun.sleep(150);
+      }
+      return false;
+    })();
+    const exited = child.exited.then(() => { done = true; return "exit" as const; });
+    const winner = await Promise.race([exited, markerWatch.then((m) => (m ? "marker" : "exit"))]);
+
+    if (winner === "marker") {
+      child.kill(); // SIGTERM at the committed turn boundary
+    }
+    await child.exited;
+    done = true;
+    await markerWatch.catch(() => {});
+    restoreTermios(savedTermios);
+
+    if (existsSync(marker)) {
+      const m = RespawnMarkerSchema.parse(await Bun.file(marker).json());
+      rmSync(marker, { force: true });
+      respawns++;
+      if (m.waitUntil && m.waitUntil > Date.now()) await countdownWait(m.account, m.waitUntil);
+      else process.stdout.write(`\n\x1b[36m↻ tokenmaxxing: switched to ${m.account} - resuming…\x1b[0m\n`);
+      launchArgs = ["--resume", sid, ...base];
+      continue;
+    }
+    return child.exitCode ?? (child.signalCode ? 1 : 0);
+  }
+}

package/src/lib/atomic.ts

@@ -0,0 +1,24 @@
+// Atomic file writes (temp + rename on the same filesystem) and small fs utils.
+
+import { closeSync, mkdirSync, openSync, renameSync, writeSync, fsyncSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Write `data` to `file` atomically: write a sibling temp file, fsync it, then
+ * rename over the target. A concurrent reader sees either the old or new file,
+ * never a partial one.
+ */
+export function writeFileAtomic(file: string, data: string | Uint8Array, mode = 0o600): void {
+  const dir = dirname(file);
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${file}.tmp.${process.pid}.${Math.floor(Math.random() * 1e9).toString(36)}`;
+  const bytes = data instanceof Uint8Array ? data : new TextEncoder().encode(data);
+  const fd = openSync(tmp, "wx", mode);
+  try {
+    writeSync(fd, bytes);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, file);
+}

package/src/lib/claudebin.ts

@@ -0,0 +1,21 @@
+// Resolve the REAL claude binary (never our shim on PATH).
+
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { paths } from "./paths.ts";
+import { loadConfig } from "./state.ts";
+
+export function resolveRealClaude(): string {
+  const cfg = loadConfig();
+  if (cfg.claudeBin && existsSync(cfg.claudeBin)) return cfg.claudeBin;
+  if (process.env.TOKENMAXXING_CLAUDE_BIN && existsSync(process.env.TOKENMAXXING_CLAUDE_BIN))
+    return process.env.TOKENMAXXING_CLAUDE_BIN;
+  for (const d of (process.env.PATH ?? "").split(":")) {
+    if (!d || d === paths.binDir) continue;
+    const cand = join(d, "claude");
+    try {
+      if (existsSync(cand) && statSync(cand).isFile()) return cand;
+    } catch { /* ignore */ }
+  }
+  throw new Error("could not locate the real `claude` binary (set claudeBin in config.json)");
+}

package/src/lib/claudejson.ts

@@ -0,0 +1,40 @@
+// Read/replace the `oauthAccount` identity object in ~/.claude.json.
+// We touch ONLY oauthAccount and preserve every other key verbatim.
+
+import { existsSync, readFileSync } from "node:fs";
+import { z } from "zod";
+import { paths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+import { OAuthAccountSchema, type OAuthAccount } from "./types.ts";
+
+export function readClaudeJson(): Record<string, unknown> {
+  if (!existsSync(paths.claudeJson)) return {};
+  return JSON.parse(readFileSync(paths.claudeJson, "utf8")) as Record<string, unknown>;
+}
+
+export function readOAuthAccount(): OAuthAccount | null {
+  const parsed = OAuthAccountSchema.safeParse(readClaudeJson()["oauthAccount"]);
+  return parsed.success ? parsed.data : null;
+}
+
+/** Detect API-key / helper auth mode (no poolable subscription credential). */
+export function isApiKeyMode(): boolean {
+  if (process.env.ANTHROPIC_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN) return true;
+  const j = readClaudeJson();
+  // apiKeyHelper is configured in settings, but a persisted flag may appear here too.
+  if (z.string().min(1).safeParse(j["apiKeyHelper"]).success) return true;
+  return false;
+}
+
+/**
+ * Atomically replace ONLY oauthAccount, preserving all other keys and their
+ * insertion order. Reads fresh from disk so we never clobber concurrent edits
+ * to unrelated keys with a stale in-memory copy.
+ */
+export function swapOAuthAccount(next: OAuthAccount): void {
+  const j = existsSync(paths.claudeJson)
+    ? (JSON.parse(readFileSync(paths.claudeJson, "utf8")) as Record<string, unknown>)
+    : {};
+  j["oauthAccount"] = next;
+  writeFileAtomic(paths.claudeJson, JSON.stringify(j, null, 2) + "\n", 0o600);
+}

package/src/lib/claudelock.ts

@@ -0,0 +1,54 @@
+// Best-effort interlock with Claude Code's OWN credential-refresh lock so our
+// keychain write can't collide with a concurrent token refresh. Claude uses the
+// npm `proper-lockfile` (mkdir-based) at <claudeDir>/.oauth_refresh.lock - the
+// lock is the DIRECTORY itself. We mkdir it; on contention we wait briefly, then
+// proceed anyway (our own flock already serializes tokenmaxxing swaps, and claude
+// only refreshes near token expiry / on 401, rarely at the 95% usage trigger).
+
+import { mkdirSync, rmdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { paths } from "./paths.ts";
+import { log } from "./log.ts";
+
+const STALE_MS = 20_000; // proper-lockfile default stale is 10s; be generous
+
+export async function withClaudeRefreshLock<T>(
+  fn: () => Promise<T> | T,
+  opts: { timeoutMs?: number } = {},
+): Promise<T> {
+  const lockDir = join(paths.claudeDir, ".oauth_refresh.lock");
+  const timeoutMs = opts.timeoutMs ?? 3000;
+  const start = Date.now();
+  let held = false;
+
+  while (Date.now() - start < timeoutMs) {
+    try {
+      mkdirSync(lockDir); // atomic; EEXIST means someone holds it
+      held = true;
+      break;
+    } catch (e) {
+      const code = (e as { code?: string }).code;
+      if (code === "EEXIST") {
+        try {
+          if (Date.now() - statSync(lockDir).mtimeMs > STALE_MS) {
+            rmdirSync(lockDir); // reclaim a stale lock
+            continue;
+          }
+        } catch { /* raced away */ }
+        await Bun.sleep(150);
+        continue;
+      }
+      // parent dir missing or other error → skip the interlock entirely
+      break;
+    }
+  }
+  if (!held) log("claudelock.proceed_without", {});
+
+  try {
+    return await fn();
+  } finally {
+    if (held) {
+      try { rmdirSync(lockDir); } catch { /* already gone */ }
+    }
+  }
+}

package/src/lib/credstore.ts

@@ -0,0 +1,97 @@
+// Platform credential store - ONE backend per platform, selected when a target
+// is constructed:
+//   darwin : login-keychain generic-password via security(1)  (keychain.ts)
+//   linux  : plaintext files, matching claude's own Linux store
+//            (live = <configDir>/.credentials.json, mode 0600; verified 2.1.205:
+//            the Linux build has no keyring path at all)
+// Parked backups live in the keychain (darwin) or ~/.config/tokenmaxxing/creds
+// (linux). Call sites never branch on platform - they pass targets around.
+
+import { mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "./atomic.ts";
+import * as kc from "./keychain.ts";
+import { credDir, keychain as kcNames, namespacedCredService, paths } from "./paths.ts";
+import { CredentialBlobSchema } from "./types.ts";
+
+const CredTargetSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("keychain"), service: z.string(), account: z.string() }),
+  z.object({ kind: z.literal("file"), path: z.string() }),
+]);
+export type CredTarget = z.infer<typeof CredTargetSchema>;
+
+const darwin = process.platform === "darwin";
+
+function isEnoent(e: unknown): boolean {
+  return (e as { code?: string }).code === "ENOENT";
+}
+
+/** Read a target's credential blob. Returns null if it does not exist. */
+export async function readItem(t: CredTarget): Promise<string | null> {
+  if (t.kind === "keychain") return kc.readItem(t);
+  try {
+    return readFileSync(t.path, "utf8");
+  } catch (e) {
+    if (isEnoent(e)) return null;
+    throw e;
+  }
+}
+
+/** Create-or-update a target with `secret` as its blob. Throws on failure. */
+export async function writeItem(t: CredTarget, secret: string): Promise<void> {
+  if (t.kind === "keychain") return kc.writeItem(t, secret);
+  mkdirSync(dirname(t.path), { recursive: true, mode: 0o700 });
+  writeFileAtomic(t.path, secret, 0o600);
+}
+
+/** Delete a target. Returns true if it existed and was removed. */
+export async function deleteItem(t: CredTarget): Promise<boolean> {
+  if (t.kind === "keychain") return kc.deleteItem(t);
+  try {
+    unlinkSync(t.path);
+    return true;
+  } catch (e) {
+    if (isEnoent(e)) return false;
+    throw e;
+  }
+}
+
+/** The live default credential claude reads (`Claude Code-credentials` / $USER
+ *  on darwin, `<credDir()>/.credentials.json` on linux). */
+export function liveTarget(): CredTarget {
+  return darwin
+    ? { kind: "keychain", service: kcNames.service, account: kcNames.account }
+    : { kind: "file", path: join(credDir(), ".credentials.json") };
+}
+
+/** A parked account's backup (`tokenmaxxing-cred-<uuid8>` item / .json file). */
+export function parkedTarget(itemName: string): CredTarget {
+  return darwin
+    ? { kind: "keychain", service: itemName, account: kcNames.account }
+    : { kind: "file", path: join(paths.credsDir, `${itemName}.json`) };
+}
+
+/** The credential claude uses under CLAUDE_CONFIG_DIR=`configDirRaw`: a
+ *  hash-namespaced keychain service on darwin, the file inside the dir on linux.
+ *  The dir string must be byte-stable on darwin (hash is over the RAW string). */
+export function isolatedTarget(configDirRaw: string): CredTarget {
+  return darwin
+    ? { kind: "keychain", service: namespacedCredService(configDirRaw), account: kcNames.account }
+    : { kind: "file", path: join(configDirRaw, ".credentials.json") };
+}
+
+/** Reduce a full credential blob to just `{claudeAiOauth}` - what parked items
+ *  store (small → always the ps-safe keychain write path on darwin). */
+export function claudeAiOauthOnly(fullBlobRaw: string): string {
+  const b = CredentialBlobSchema.parse(JSON.parse(fullBlobRaw));
+  return JSON.stringify({ claudeAiOauth: b.claudeAiOauth });
+}
+
+/** Merge a fresh `claudeAiOauth` into the CURRENT live blob, preserving every
+ *  sibling key (MCP OAuth state, etc.). Returns the full blob string to install. */
+export function mergeIntoLive(currentLiveRaw: string | null, freshClaudeAiOauth: unknown): string {
+  const base = currentLiveRaw ? (JSON.parse(currentLiveRaw) as Record<string, unknown>) : {};
+  base["claudeAiOauth"] = freshClaudeAiOauth;
+  return JSON.stringify(base);
+}