tokenmaxxing 0.1.0 → 0.2.1

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);
+}

package/src/lib/decide.ts

@@ -0,0 +1,149 @@
+// Shared switch decision used by both the Stop hook and the SessionStart hook.
+// Cheap pre-check off the lock; the authoritative re-check + swap under the flock.
+//
+// Two limit families are checked, both metered against the CURRENTLY-active org:
+//   1. AGGREGATE windows (session=five_hour, week-all=seven_day) from statusLine.
+//   2. PER-MODEL weekly cap (e.g. "week (Fable)") - only when the active model is
+//      capacity-constrained (config policy.switchModels). This isn't in statusLine,
+//      so we read it from `claude -p '/usage'`, TTL-cached (not every turn).
+//
+// The org guard is load-bearing: right after a respawn, usage.json still reflects
+// the OLD account, so org != activeOrg → we correctly do nothing until fresh usage
+// for the new account arrives.
+
+import { z } from "zod";
+import { withLock } from "./lock.ts";
+import { paths } from "./paths.ts";
+import { loadAccounts, loadConfig, loadUsage, loadModelUsage, saveAccounts, saveModelUsage } from "./state.ts";
+import { readOAuthAccount } from "./claudejson.ts";
+import { chooseAndSwap, performSwap } from "./swap.ts";
+import { pickEarliestReset, usableAt } from "./picker.ts";
+import { InvalidGrantError } from "./oauth.ts";
+import { probeUsage } from "./usage.ts";
+import { log } from "./log.ts";
+import { AccountSchema, type Account, type Config, type ModelUsageState, type UsageState, type UsageWindow } from "./types.ts";
+
+const SwapDecisionSchema = z.object({
+  swapped: z.boolean(),
+  account: AccountSchema.nullable(),
+  reason: z.string(),
+  /** set when every account is depleted: epoch ms the chosen account recovers. */
+  waitUntil: z.number().optional(),
+});
+export type SwapDecision = z.infer<typeof SwapDecisionSchema>;
+
+/** Cold-start aggregate fallback when statusLine hasn't written usage.json yet. */
+async function probeAggregate(org: string | null): Promise<UsageState | null> {
+  const full = await probeUsage();
+  if (!full) return null;
+  return { fiveHour: full.session, sevenDay: full.weekAll, org, ts: Date.now(), model: null };
+}
+
+/** Ensure a fresh-enough per-model cache for the active org; poll `/usage` if stale. */
+async function ensurePerModel(cfg: Config, org: string | null): Promise<ModelUsageState | null> {
+  const cached = loadModelUsage();
+  const fresh = cached && cached.org === org && Date.now() - cached.ts < cfg.policy.usagePollTtlMs;
+  if (fresh) return cached;
+  const full = await probeUsage();
+  if (!full) return cached; // keep stale on poll failure
+  const state: ModelUsageState = { perModel: full.perModel, org, ts: Date.now() };
+  saveModelUsage(state);
+  return state;
+}
+
+function capForModel(mu: ModelUsageState | null, display: string): UsageWindow | undefined {
+  if (!mu) return undefined;
+  const key = Object.keys(mu.perModel).find((k) => k.toLowerCase() === display.toLowerCase());
+  return key ? mu.perModel[key] : undefined;
+}
+
+/** True if the active account is over the floor on ANY applicable limit. */
+function isOver(u: UsageState | null, mu: ModelUsageState | null, org: string | null, cfg: Config, floor: number): boolean {
+  if (!u || !org || u.org !== org) return false;
+  if (u.fiveHour.usedPercentage >= floor || u.sevenDay.usedPercentage >= floor) return true;
+  const display = u.model?.display;
+  if (display && cfg.policy.switchModels.includes(display.toLowerCase()) && mu && mu.org === org) {
+    const cap = capForModel(mu, display);
+    if (cap && cap.usedPercentage >= floor) return true;
+  }
+  return false;
+}
+
+/** Does the active model warrant a per-model `/usage` poll? */
+function needsPerModel(u: UsageState | null, cfg: Config): boolean {
+  const display = u?.model?.display;
+  return !!display && cfg.policy.switchModels.includes(display.toLowerCase());
+}
+
+export async function evaluateAndMaybeSwap(now = Date.now()): Promise<SwapDecision> {
+  const cfg = loadConfig();
+  const floor = cfg.threshold - cfg.policy.projectionMargin;
+  const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
+
+  let usage = loadUsage();
+  if (!usage && activeOrg) usage = await probeAggregate(activeOrg);
+
+  // per-model poll (TTL-cached) only when on a capacity-constrained model
+  const mu = needsPerModel(usage, cfg) ? await ensurePerModel(cfg, activeOrg) : null;
+
+  // cheap pre-check off the lock - the common case exits here.
+  if (!isOver(usage, mu, activeOrg, cfg, floor)) {
+    return { swapped: false, account: null, reason: "under-threshold-or-stale" };
+  }
+
+  return withLock(paths.lockFile, async () => {
+    const idx = loadAccounts();
+    const org2 = readOAuthAccount()?.organizationUuid ?? null;
+    const u2 = loadUsage() ?? usage;
+    const mu2 = needsPerModel(u2, cfg) ? loadModelUsage() ?? mu : null;
+
+    // record the active account's aggregate usage so the picker + `status` see it.
+    if (u2 && org2 && u2.org === org2) {
+      const active = idx.accounts.find((a) => a.accountUuid === idx.activeAccountUuid);
+      if (active) {
+        active.lastUsage = { fiveHour: u2.fiveHour, sevenDay: u2.sevenDay };
+        // Snapshot per-model caps too, so they still show after we switch away.
+        if (mu2 && mu2.org === org2) active.lastPerModel = mu2.perModel;
+        saveAccounts(idx);
+      }
+    }
+
+    if (!isOver(u2, mu2, org2, cfg, floor)) {
+      return { swapped: false, account: null, reason: "raced-already-swapped" };
+    }
+
+    const landed = await chooseAndSwap({ now, threshold: cfg.threshold });
+    if (landed) return { swapped: true, account: landed, reason: "swapped" };
+
+    // Every account is depleted. Wait for whichever recovers soonest (including the
+    // current one), if that reset is within the auto-wait window.
+    const fresh = loadAccounts();
+    const ctx = { now, threshold: cfg.threshold, currentAccountUuid: fresh.activeAccountUuid };
+    const current = fresh.accounts.find((a) => a.accountUuid === fresh.activeAccountUuid);
+    const currentAt = current ? usableAt(current, cfg.threshold, now) : Number.POSITIVE_INFINITY;
+    const other = pickEarliestReset(fresh.accounts, ctx);
+
+    let target: Account | null = null;
+    let waitUntil = Number.POSITIVE_INFINITY;
+    if (other && other.availableAt < currentAt) { target = other.account; waitUntil = other.availableAt; }
+    else if (current) { target = current; waitUntil = currentAt; }
+    else if (other) { target = other.account; waitUntil = other.availableAt; }
+
+    if (!target || waitUntil - now > cfg.policy.maxWaitMs) {
+      log("decide.depleted", { waitUntil: Number.isFinite(waitUntil) ? waitUntil : 0 });
+      return { swapped: false, account: null, reason: "all-depleted" };
+    }
+
+    const isCurrent = target.accountUuid === fresh.activeAccountUuid;
+    if (!isCurrent) {
+      try {
+        await performSwap(target);
+      } catch (e) {
+        if (e instanceof InvalidGrantError) return { swapped: false, account: null, reason: "all-depleted" };
+        throw e;
+      }
+    }
+    log("decide.depleted_wait", { account: target.accountUuid.slice(0, 8), waitUntil });
+    return { swapped: !isCurrent, account: target, reason: "depleted-wait", waitUntil };
+  });
+}

package/src/lib/http.ts

@@ -0,0 +1,19 @@
+// Shared HTTP client. Sampling every account at once, or swapping right at a
+// limit, can trip an endpoint's burst throttle, so GETs retry a bounded number
+// of times, honoring the server's Retry-After (capped). throwHttpErrors is off
+// so callers read the body and shape their own fail-fast error; retry still runs.
+
+import ky from "ky";
+
+export const http = ky.create({
+  timeout: 15_000,
+  throwHttpErrors: false,
+  retry: {
+    limit: 2,
+    methods: ["get"],
+    statusCodes: [429, 500, 502, 503, 504],
+    afterStatusCodes: [429, 503],
+    maxRetryAfter: 10_000,
+    backoffLimit: 3000,
+  },
+});

package/src/lib/install.ts

@@ -0,0 +1,87 @@
+// Install/uninstall the on-PATH `claude` supervisor wrapper + settings entries.
+// The wrapper is a 2-line `exec … __supervise "$@"` shim so dispatch never
+// depends on argv0 semantics.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { z } from "zod";
+import { HOME, paths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+import { installedBin, installSettings, uninstallSettings } from "./settings.ts";
+import { resolveRealClaude } from "./claudebin.ts";
+
+const InstallOutcomeSchema = z.object({
+  claudeWrapper: z.string(),
+  installedBin: z.string(),
+  priorStatusLine: z.string().nullable(),
+  pathAhead: z.boolean(),
+});
+export type InstallOutcome = z.infer<typeof InstallOutcomeSchema>;
+
+/** True if our binDir comes before the real claude's dir on PATH. */
+export function isBinDirAhead(): boolean {
+  const dirs = (process.env.PATH ?? "").split(":");
+  const ourIdx = dirs.indexOf(paths.binDir);
+  if (ourIdx < 0) return false;
+  try {
+    const realDir = dirname(resolveRealClaude());
+    const realIdx = dirs.indexOf(realDir);
+    return realIdx < 0 || ourIdx < realIdx;
+  } catch {
+    return ourIdx >= 0;
+  }
+}
+
+export function installSupervisor(): InstallOutcome {
+  mkdirSync(paths.binDir, { recursive: true });
+  const target = installedBin(); // binDir/tokenmaxxing
+  // Resolve the entry through the global-bin symlink (bun add -g links
+  // ~/.bun/bin/tokenmaxxing → the package's src/main.ts) so the shim points
+  // into the installed package tree, where its imports resolve.
+  const entry = realpathSync(Bun.main);
+  writeFileAtomic(target, `#!/bin/sh\nexec ${JSON.stringify(process.execPath)} run ${JSON.stringify(entry)} "$@"\n`, 0o755);
+
+  // the on-PATH `claude` wrapper
+  writeFileAtomic(paths.supervisorLink, `#!/bin/sh\nexec ${JSON.stringify(target)} __supervise "$@"\n`, 0o755);
+  // the `xx` short alias → tokenmaxxing
+  writeFileAtomic(join(paths.binDir, "xx"), `#!/bin/sh\nexec ${JSON.stringify(target)} "$@"\n`, 0o755);
+
+  const { priorStatusLine } = installSettings();
+  return {
+    claudeWrapper: paths.supervisorLink,
+    installedBin: target,
+    priorStatusLine,
+    pathAhead: isBinDirAhead(),
+  };
+}
+
+/** The rc file of the user's login shell, or null when the shell is unknown.
+ *  Overridable for hermetic tests. */
+export function shellRcPath(): string | null {
+  const override = process.env.TOKENMAXXING_SHELL_RC;
+  if (override && override.length > 0) return override;
+  const shell = basename(process.env.SHELL ?? "");
+  if (shell === "zsh") return join(process.env.ZDOTDIR || HOME, ".zshrc");
+  if (shell === "bash") return join(HOME, ".bashrc");
+  return null;
+}
+
+const PATH_LINE_MARK = "# tokenmaxxing PATH";
+
+/** Idempotently append the supervisor-bin PATH line to `rc` (created if absent).
+ *  A pre-existing hand-added line for the bin dir also counts as present. */
+export function ensurePathInRc(rc: string): "added" | "present" {
+  const dir = paths.binDir.startsWith(`${HOME}/`) ? `$HOME${paths.binDir.slice(HOME.length)}` : paths.binDir;
+  const current = existsSync(rc) ? readFileSync(rc, "utf8") : "";
+  if (current.includes(PATH_LINE_MARK) || current.includes(`${paths.binDir}:`) || current.includes(`${dir}:`)) return "present";
+  const sep = current === "" || current.endsWith("\n") ? "" : "\n";
+  appendFileSync(rc, `${sep}export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`);
+  return "added";
+}
+
+export function uninstallSupervisor(): void {
+  uninstallSettings();
+  for (const f of [paths.supervisorLink, join(paths.binDir, "xx"), installedBin()]) {
+    if (existsSync(f)) rmSync(f, { force: true });
+  }
+}

package/src/lib/keychain.ts

@@ -0,0 +1,84 @@
+// macOS login-keychain generic-password I/O, ps-safe. The darwin backend of
+// credstore.ts - construct targets there, not here.
+//   READ  : `security find-generic-password -w`  → secret only ever in stdout.
+//   WRITE : pipe an `add-generic-password -U … -w <secret>` line into `security -i`
+//           over STDIN - the secret never appears in any process's argv (verified).
+// The service/account are non-secret and may sit in argv.
+
+import { z } from "zod";
+
+const KeychainTargetSchema = z.object({ service: z.string(), account: z.string() });
+export type KeychainTarget = z.infer<typeof KeychainTargetSchema>;
+
+const SECURITY = "/usr/bin/security";
+// security(1) interactive mode has a ~4KB line buffer; above this we must use argv.
+const INTERACTIVE_MAX = 3800;
+
+/** Double-quote + backslash-escape for security(1)'s interactive tokenizer. */
+function quoteDouble(s: string): string {
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** Wrap a value for the `-i` line. Single-quote when possible (blob has no `'`). */
+function quoteValue(s: string): string {
+  return s.includes("'") ? quoteDouble(s) : `'${s}'`;
+}
+
+/** Read an item's password blob. Returns null if the item does not exist. */
+export async function readItem(t: KeychainTarget): Promise<string | null> {
+  const p = Bun.spawn([SECURITY, "find-generic-password", "-s", t.service, "-a", t.account, "-w"], {
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  const out = await new Response(p.stdout).text();
+  await p.exited;
+  if (p.exitCode !== 0) return null; // 44 = not found
+  return out.replace(/\n$/, ""); // security appends exactly one trailing newline
+}
+
+/** ps-safe write: the command line + secret arrive on stdin, never in argv.
+ *  Bounded by security(1)'s ~4KB interactive line buffer. */
+async function writeViaInteractive(t: KeychainTarget, secret: string): Promise<void> {
+  const line =
+    `add-generic-password -U -a ${quoteDouble(t.account)} -s ${quoteDouble(t.service)} ` +
+    `-w ${quoteValue(secret)}\n`;
+  const p = Bun.spawn([SECURITY, "-i"], {
+    stdin: new TextEncoder().encode(line),
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const err = await new Response(p.stderr).text();
+  await p.exited;
+  if (p.exitCode !== 0) throw new Error(`keychain write (interactive) failed (exit ${p.exitCode}): ${err.trim()}`);
+}
+
+/** Fallback for blobs over the interactive line limit. The secret is briefly
+ *  visible in `ps` for this one short-lived process - used only when the payload
+ *  (e.g. a live blob with lots of MCP OAuth state) exceeds ~4KB. */
+async function writeViaArgv(t: KeychainTarget, secret: string): Promise<void> {
+  const p = Bun.spawn([SECURITY, "add-generic-password", "-U", "-a", t.account, "-s", t.service, "-w", secret], {
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const err = await new Response(p.stderr).text();
+  await p.exited;
+  if (p.exitCode !== 0) throw new Error(`keychain write (argv) failed (exit ${p.exitCode}): ${err.trim()}`);
+}
+
+/** Create-or-update an item (`-U`) with `secret` as its password. Prefers the
+ *  ps-safe stdin path; falls back to argv only when the blob exceeds the ~4KB
+ *  interactive line limit. Throws on failure. */
+export async function writeItem(t: KeychainTarget, secret: string): Promise<void> {
+  if (secret.length <= INTERACTIVE_MAX) return writeViaInteractive(t, secret);
+  return writeViaArgv(t, secret);
+}
+
+/** Delete an item. Returns true if it existed and was removed. */
+export async function deleteItem(t: KeychainTarget): Promise<boolean> {
+  const p = Bun.spawn([SECURITY, "delete-generic-password", "-s", t.service, "-a", t.account], {
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  await p.exited;
+  return p.exitCode === 0;
+}

package/src/lib/lock.ts

@@ -0,0 +1,78 @@
+// Cross-process advisory locking via flock(2) through bun:ffi on a real file
+// descriptor (macOS ships no flock(1) binary, and one codepath serves both
+// platforms). The lock is released when we close the fd (explicitly or on
+// process exit).
+
+import { closeSync, mkdirSync, openSync } from "node:fs";
+import { dirname } from "node:path";
+import { dlopen, FFIType, suffix } from "bun:ffi";
+
+// sys/file.h (identical on darwin + linux): LOCK_SH=1 LOCK_EX=2 LOCK_NB=4 LOCK_UN=8
+const LOCK_EX = 2;
+const LOCK_UN = 8;
+
+let _flock: ((fd: number, op: number) => number) | null = null;
+
+function flockFn(): (fd: number, op: number) => number {
+  if (_flock) return _flock;
+  // darwin: flock(2) is in libSystem; the bare name resolves via the dyld shared
+  // cache even though no physical .dylib exists on disk (verified 2026-07-08).
+  // linux: glibc's libc.so.6 (verified in-container 2026-07-09, arm64).
+  const candidates =
+    process.platform === "darwin"
+      ? ["libSystem.B.dylib", "/usr/lib/libSystem.B.dylib", `libc.${suffix}`]
+      : [`libc.so.6`, `libc.${suffix}`];
+  let lib: ReturnType<typeof dlopen> | null = null;
+  let lastErr: unknown;
+  for (const path of candidates) {
+    try {
+      lib = dlopen(path, {
+        flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+      });
+      break;
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  if (!lib) throw new Error(`could not load flock(2): ${String(lastErr)}`);
+  const sym = lib.symbols.flock as unknown as (fd: number, op: number) => number;
+  _flock = sym;
+  return _flock;
+}
+
+/**
+ * Acquire an exclusive advisory lock on `lockPath`, blocking until available.
+ * Returns a handle whose release() drops the lock. The lock is process-scoped
+ * (held via an open fd) so racing hooks in separate processes serialize.
+ */
+export function acquireLock(lockPath: string): { release: () => void } {
+  mkdirSync(dirname(lockPath), { recursive: true });
+  const fd = openSync(lockPath, "a", 0o600);
+  const flock = flockFn();
+  const rc = flock(fd, LOCK_EX);
+  if (rc !== 0) {
+    closeSync(fd);
+    throw new Error(`flock LOCK_EX failed on ${lockPath} (rc=${rc})`);
+  }
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    try {
+      flock(fd, LOCK_UN);
+    } finally {
+      closeSync(fd);
+    }
+  };
+  return { release };
+}
+
+/** Run `fn` while holding `lockPath`; always releases, even on throw. */
+export async function withLock<T>(lockPath: string, fn: () => Promise<T> | T): Promise<T> {
+  const held = acquireLock(lockPath);
+  try {
+    return await fn();
+  } finally {
+    held.release();
+  }
+}

package/src/lib/log.ts

@@ -0,0 +1,28 @@
+// Append-only logging. NEVER logs secret material - callers must pass only
+// non-secret context (account uuids/emails, percentages, status strings).
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { paths } from "./paths.ts";
+
+/** Redact anything that looks like a token so an accidental pass-through can't leak. */
+export function redact(s: string): string {
+  return s
+    // JWT-ish / long opaque tokens
+    .replace(/\b(sk-ant-[A-Za-z0-9._-]{6,})/g, "sk-ant-***")
+    .replace(/\b([A-Za-z0-9_-]{40,})\b/g, (m) => `${m.slice(0, 4)}…(${m.length})`);
+}
+
+export function log(event: string, fields: Record<string, unknown> = {}): void {
+  try {
+    mkdirSync(dirname(paths.logFile), { recursive: true });
+    const parts = Object.entries(fields).map(([k, v]) => {
+      const str = z.string().safeParse(v);
+      return `${k}=${redact(str.success ? str.data : JSON.stringify(v))}`;
+    });
+    appendFileSync(paths.logFile, `${new Date().toISOString()} ${event} ${parts.join(" ")}\n`);
+  } catch {
+    // logging must never throw into a hook / supervisor path
+  }
+}