tokenmaxxing 0.1.0 → 0.2.1

package/src/lib/oauth.ts

@@ -0,0 +1,117 @@
+// The two OAuth calls tokenmaxxing makes:
+//   1. the refresh_token grant that turns a parked account's (possibly expired)
+//      access token into a fresh one before we install it. Verified against
+//      Claude Code 2.1.204: POST platform.claude.com, JSON body, public PKCE
+//      client (no secret), no auth/beta headers on this call.
+//   2. the roles lookup that reports which org a token ACTUALLY belongs to.
+//      Endpoint string extracted from the Claude Code 2.1.205 binary; verified
+//      live to answer HTTP 200 with plain Bearer auth (with or without the
+//      oauth beta header - we send it to match the CLI's OAuth convention).
+
+import { http } from "./http.ts";
+import { RefreshResponseSchema, RolesResponseSchema, type OAuthCreds, type RolesResponse } from "./types.ts";
+
+const TOKEN_URL = process.env.TOKENMAXXING_OAUTH_TOKEN_URL ?? "https://platform.claude.com/v1/oauth/token";
+const CLIENT_ID = process.env.TOKENMAXXING_OAUTH_CLIENT_ID ?? "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+const ROLES_URL = process.env.TOKENMAXXING_OAUTH_ROLES_URL ?? "https://api.anthropic.com/api/oauth/claude_cli/roles";
+
+const DEFAULT_SCOPES = [
+  "user:profile",
+  "user:inference",
+  "user:sessions:claude_code",
+  "user:mcp_servers",
+  "user:file_upload",
+];
+
+/** Refresh token is dead / revoked - caller should mark needs_reauth and skip. */
+export class InvalidGrantError extends Error {
+  constructor(public readonly detail: string) {
+    super(`invalid_grant: ${detail}`);
+    this.name = "InvalidGrantError";
+  }
+}
+
+/**
+ * Exchange `creds.refreshToken` for a fresh access token. Returns a NEW OAuthCreds
+ * with the fresh access token, the rotated refresh token (or the old one if the
+ * server omitted it), and recomputed absolute expiries. Non-token fields are
+ * preserved. Throws InvalidGrantError on a dead refresh token.
+ */
+export async function refreshCredential(creds: OAuthCreds, now = Date.now()): Promise<OAuthCreds> {
+  const scope = (creds.scopes?.length ? creds.scopes : DEFAULT_SCOPES).join(" ");
+  const body = {
+    grant_type: "refresh_token",
+    refresh_token: creds.refreshToken,
+    client_id: CLIENT_ID,
+    scope,
+  };
+
+  let res: Response;
+  try {
+    res = await http.post(TOKEN_URL, {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    throw new Error(`token endpoint unreachable: ${String((e as Error).message ?? e)}`);
+  }
+
+  const text = await res.text();
+  if (!res.ok) {
+    // invalid_grant → dead refresh token; anything else is transient/unknown.
+    if (res.status === 400 && /invalid_grant/.test(text)) {
+      throw new InvalidGrantError(text.slice(0, 200));
+    }
+    throw new Error(`token refresh failed (HTTP ${res.status}): ${text.slice(0, 200)}`);
+  }
+
+  const parsed = RefreshResponseSchema.safeParse((() => {
+    try { return JSON.parse(text); } catch { return null; }
+  })());
+  if (!parsed.success) {
+    throw new Error(`token endpoint returned unexpected body: ${text.slice(0, 120)}`);
+  }
+  const json = parsed.data;
+
+  const expiresIn = json.expires_in ?? 8 * 3600;
+  const refreshExpiresIn = json.refresh_token_expires_in;
+
+  return {
+    ...creds,
+    accessToken: json.access_token,
+    refreshToken: json.refresh_token ?? creds.refreshToken, // server may omit → reuse
+    expiresAt: now + expiresIn * 1000,
+    refreshTokenExpiresAt:
+      refreshExpiresIn != null ? now + refreshExpiresIn * 1000 : creds.refreshTokenExpiresAt,
+    scopes: json.scope ? json.scope.split(" ").filter(Boolean) : creds.scopes,
+  };
+}
+
+/** True if the access token is within `skewMs` of expiry (or already expired). */
+export function isAccessTokenExpiring(creds: OAuthCreds, skewMs = 120_000, now = Date.now()): boolean {
+  return !creds.expiresAt || creds.expiresAt - now <= skewMs;
+}
+
+/**
+ * Ask the API which org `accessToken` ACTUALLY belongs to. Stored labels
+ * (accounts.json, oauthAccount) can drift from the credential they describe;
+ * the token itself cannot lie. Requires a non-expired access token. Read-only:
+ * never rotates anything.
+ */
+export async function fetchTokenOrg(accessToken: string): Promise<RolesResponse> {
+  let res: Response;
+  try {
+    res = await http.get(ROLES_URL, {
+      headers: { Authorization: `Bearer ${accessToken}`, "anthropic-beta": "oauth-2025-04-20" },
+    });
+  } catch (e) {
+    throw new Error(`roles endpoint unreachable: ${String((e as Error).message ?? e)}`);
+  }
+  const text = await res.text();
+  if (!res.ok) throw new Error(`roles check failed (HTTP ${res.status}): ${text.slice(0, 140)}`);
+  const parsed = RolesResponseSchema.safeParse((() => {
+    try { return JSON.parse(text); } catch { return null; }
+  })());
+  if (!parsed.success) throw new Error(`roles endpoint returned unexpected body: ${text.slice(0, 120)}`);
+  return parsed.data;
+}

package/src/lib/paths.ts

@@ -0,0 +1,90 @@
+// Central path resolution. EVERY externally-observable path is overridable via an
+// env var so the whole tool can run hermetically in tests without touching the
+// user's real ~/.config, ~/.claude, or login keychain.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const HOME = homedir();
+
+function env(name: string, fallback: string): string {
+  const v = process.env[name];
+  return v && v.length > 0 ? v : fallback;
+}
+
+/** Root of all tokenmaxxing config + state. Default ~/.config/tokenmaxxing. */
+export const TM_HOME = env("TOKENMAXXING_HOME", join(HOME, ".config", "tokenmaxxing"));
+
+export const paths = {
+  home: TM_HOME,
+  configJson: join(TM_HOME, "config.json"),
+  accountsJson: join(TM_HOME, "accounts.json"),
+  usageJson: join(TM_HOME, "usage.json"),
+  modelUsageJson: join(TM_HOME, "model-usage.json"),
+  respawnDir: join(TM_HOME, "respawn"),
+  binDir: join(TM_HOME, "bin"),
+  supervisorLink: join(TM_HOME, "bin", "claude"),
+  lockFile: join(TM_HOME, "lock"),
+  logFile: join(TM_HOME, "tokenmaxxing.log"),
+  onboardDir: join(TM_HOME, "onboard"),
+  sampleDir: join(TM_HOME, "sample"),
+  /** linux only: parked credential .json files (0700 dir, 0600 files). */
+  credsDir: join(TM_HOME, "creds"),
+
+  /** ~/.claude.json - holds the active `oauthAccount` identity object. */
+  claudeJson: env("TOKENMAXXING_CLAUDE_JSON", join(HOME, ".claude.json")),
+  /** ~/.claude/settings.json - user-owned; we merge three entries into it. */
+  claudeSettings: env(
+    "TOKENMAXXING_CLAUDE_SETTINGS",
+    join(env("CLAUDE_CONFIG_DIR", join(HOME, ".claude")), "settings.json"),
+  ),
+  /** ~/.claude - for the credential-refresh lock and projects/ transcripts. */
+  claudeDir: env("CLAUDE_CONFIG_DIR", join(HOME, ".claude")),
+} as const;
+
+/** Claude's own credential-refresh lock (verified path filled from facts). */
+export function claudeLockPath(): string {
+  return env("TOKENMAXXING_CLAUDE_LOCK", join(HOME, ".claude.lock"));
+}
+
+/** The macOS login-keychain generic-password the live `claude` reads. */
+export const keychain = {
+  service: env("TOKENMAXXING_KEYCHAIN_SERVICE", "Claude Code-credentials"),
+  account: env("TOKENMAXXING_KEYCHAIN_ACCOUNT", process.env.USER ?? "unknown"),
+} as const;
+
+/** Per-account parked credential item name: tokenmaxxing-cred-<accountUuid[:8]>. */
+export function credItemFor(accountUuid: string): string {
+  return `tokenmaxxing-cred-${accountUuid.slice(0, 8)}`;
+}
+
+/**
+ * The dir whose `.credentials.json` is claude's live credential on linux -
+ * mirrors claude's own resolution (verified 2.1.205 `Wde()`): the
+ * CLAUDE_SECURESTORAGE_CONFIG_DIR override is checked FIRST when defined
+ * (defined-but-empty falls to ~/.claude, NFC-normalized), else the config dir.
+ */
+export function credDir(): string {
+  const secure = process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR;
+  if (secure !== undefined) return (secure || join(HOME, ".claude")).normalize("NFC");
+  return paths.claudeDir;
+}
+
+/**
+ * The keychain service claude uses when CLAUDE_CONFIG_DIR is set:
+ * `Claude Code-credentials-<first 8 hex of sha256(NFC(raw dir string))>`.
+ * Hash is over the RAW string, so the dir must be byte-stable.
+ */
+export function namespacedCredService(configDirRaw: string): string {
+  const h = new Bun.CryptoHasher("sha256");
+  h.update(configDirRaw.normalize("NFC"));
+  return `Claude Code-credentials-${h.digest("hex").slice(0, 8)}`;
+}
+
+/** Resolve the REAL claude binary (never our shim). Order: explicit env, config, PATH scan. */
+export function realClaudeBinFromEnv(): string | undefined {
+  const v = process.env.TOKENMAXXING_CLAUDE_BIN;
+  return v && v.length > 0 ? v : undefined;
+}
+
+export { HOME };

package/src/lib/picker.ts

@@ -0,0 +1,63 @@
+// Choose the best account to switch TO when the active one crosses threshold.
+// Policy: exclude the current account and any that need reauth or are still
+// rate-limited (usage >= threshold and not yet past resets_at). Among the rest,
+// prefer lowest 7-day usage; tiebreak on soonest resets_at.
+
+import { minBy, sortBy } from "es-toolkit";
+import { z } from "zod";
+import { AccountSchema, type Account } from "./types.ts";
+
+const PickCtxSchema = z.object({
+  now: z.number(),
+  threshold: z.number(),
+  currentAccountUuid: z.string().nullable(),
+});
+export type PickCtx = z.infer<typeof PickCtxSchema>;
+
+/** An account is "exhausted" if a window is >= threshold and hasn't reset yet. */
+export function isExhausted(a: Account, ctx: PickCtx): boolean {
+  const u = a.lastUsage;
+  if (!u) return false;
+  const blocked = (w: { usedPercentage: number; resetsAt: number | null }) =>
+    w.usedPercentage >= ctx.threshold && (w.resetsAt == null || w.resetsAt > ctx.now);
+  return blocked(u.fiveHour) || blocked(u.sevenDay);
+}
+
+export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
+  const candidates = accounts.filter(
+    (a) =>
+      a.accountUuid !== ctx.currentAccountUuid &&
+      !a.needsReauth &&
+      !isExhausted(a, ctx),
+  );
+  if (candidates.length === 0) return null;
+
+  // lowest 7-day usage first; tiebreak on soonest 5h reset.
+  return sortBy(candidates, [
+    (a) => a.lastUsage?.sevenDay.usedPercentage ?? 0,
+    (a) => a.lastUsage?.fiveHour.resetsAt ?? Number.POSITIVE_INFINITY,
+  ])[0]!;
+}
+
+/** When an account becomes usable again: the latest reset among its over-threshold
+ *  windows (all must reset), or `now` if nothing is over. */
+export function usableAt(a: Account, threshold: number, now: number): number {
+  const u = a.lastUsage;
+  if (!u) return now;
+  const blocking = [u.fiveHour, u.sevenDay]
+    .filter((w) => w.usedPercentage >= threshold && w.resetsAt != null)
+    .map((w) => w.resetsAt as number);
+  return blocking.length ? Math.max(...blocking) : now;
+}
+
+const EarliestResetSchema = z.object({ account: AccountSchema, availableAt: z.number() });
+export type EarliestReset = z.infer<typeof EarliestResetSchema>;
+
+/** For the all-depleted case: the account (not current, not reauth) that becomes
+ *  usable soonest. */
+export function pickEarliestReset(accounts: Account[], ctx: PickCtx): EarliestReset | null {
+  const mapped = accounts
+    .filter((a) => a.accountUuid !== ctx.currentAccountUuid && !a.needsReauth)
+    .map((a) => ({ account: a, availableAt: usableAt(a, ctx.threshold, ctx.now) }));
+  return minBy(mapped, (x) => x.availableAt) ?? null;
+}

package/src/lib/sample.ts

@@ -0,0 +1,144 @@
+// Live-sample a PARKED account's `/usage` without disturbing the live login.
+// `/usage` is free (0 tokens), so `status` can show every account's real usage.
+// We install the account's parked credential into a throwaway CLAUDE_CONFIG_DIR
+// (the isolated credential claude reads for that dir), run `claude -p /usage`
+// against it, then tear the item down.
+//
+// Contamination guards (the incident that motivated these):
+//   1. probeUsage scrubs every ambient credential-override env var, so an
+//      inherited CLAUDE_CODE_OAUTH_TOKEN can't hijack the isolated probe.
+//   2. before trusting a backup we verify (roles endpoint) that its token really
+//      belongs to this account - a mislabeled backup (drifted harvest) surfaces
+//      as an explicit error, never as another account's bars.
+//
+// Refresh tokens rotate single-use, so the one hazard is a rotation we fail to
+// capture. Two guards: refresh an expiring token OURSELVES up front, and
+// capture-before-delete the isolated item in case claude rotated it anyway.
+//
+// The caller MUST hold the tokenmaxxing flock so a parked refresh cannot collide
+// with an in-flight performSwap refreshing the same account.
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { readItem, writeItem, deleteItem, liveTarget, parkedTarget, isolatedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
+import { credItemFor, paths } from "./paths.ts";
+import { withClaudeRefreshLock } from "./claudelock.ts";
+import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg, InvalidGrantError } from "./oauth.ts";
+import { FullUsageSchema, probeUsage } from "./usage.ts";
+import { CredentialBlobSchema, type Account, type OAuthCreds, type RolesResponse } from "./types.ts";
+
+/** Result of a live sample: the fresh usage, or why it could not be taken. */
+export const SampleOutcomeSchema = z.discriminatedUnion("ok", [
+  z.object({ ok: z.literal(true), usage: FullUsageSchema }),
+  z.object({ ok: z.literal(false), reason: z.string() }),
+]);
+export type SampleOutcome = z.infer<typeof SampleOutcomeSchema>;
+
+/** Verify `creds` belongs to `account`; null on match, else the mismatch reason. */
+async function identityMismatch(creds: OAuthCreds, account: Account): Promise<string | null> {
+  let org: RolesResponse;
+  try {
+    org = await fetchTokenOrg(creds.accessToken);
+  } catch (e) {
+    return `credential identity check failed: ${String((e as Error).message ?? e)}`;
+  }
+  if (org.organization_uuid === account.organizationUuid) return null;
+  return `credential actually belongs to ${org.organization_name} (org ${org.organization_uuid.slice(0, 8)})`;
+}
+
+/**
+ * Live-sample `account`'s `/usage` in isolation. On a dead refresh token or a
+ * mislabeled credential it sets `account.needsReauth` in place (the caller
+ * persists accounts.json). Mutates only the passed object and keychain items.
+ */
+export async function probeParkedUsage(account: Account): Promise<SampleOutcome> {
+  const backup = parkedTarget(account.keychainItem);
+  const parkedRaw = await readItem(backup);
+  if (!parkedRaw) return { ok: false, reason: "no parked credential - re-add with `tokenmaxxing add`" };
+
+  let creds: OAuthCreds;
+  try {
+    creds = CredentialBlobSchema.parse(JSON.parse(parkedRaw)).claudeAiOauth;
+  } catch (e) {
+    return { ok: false, reason: `parked credential unreadable (${String((e as Error).message ?? e).slice(0, 80)}) - re-add with \`tokenmaxxing add\`` };
+  }
+
+  // Hand claude a token with comfortable headroom so it won't run its own refresh
+  // (which claude does within 120s of expiry). Refresh + persist ourselves first.
+  if (isAccessTokenExpiring(creds, 300_000)) {
+    try {
+      creds = await refreshCredential(creds);
+      await writeItem(backup, JSON.stringify({ claudeAiOauth: creds }));
+    } catch (e) {
+      if (e instanceof InvalidGrantError) {
+        account.needsReauth = true;
+        return { ok: false, reason: "refresh token dead - re-auth with `tokenmaxxing add`" };
+      }
+      return { ok: false, reason: `token refresh failed: ${String((e as Error).message ?? e)}` };
+    }
+  }
+
+  const mismatch = await identityMismatch(creds, account);
+  if (mismatch) {
+    account.needsReauth = true;
+    return { ok: false, reason: `${mismatch} - this account's own credential is gone; re-auth with \`tokenmaxxing add\`` };
+  }
+
+  const dir = join(paths.sampleDir, credItemFor(account.accountUuid));
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const isoTarget = isolatedTarget(dir);
+  const installed = JSON.stringify({ claudeAiOauth: creds });
+
+  try {
+    await writeItem(isoTarget, installed);
+    writeFileSync(join(dir, ".claude.json"), JSON.stringify({ oauthAccount: account.oauthAccount, hasCompletedOnboarding: true }));
+    const usage = await probeUsage(dir);
+    return usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+  } finally {
+    // capture-before-delete: never discard a rotation claude may have performed.
+    const afterIso = await readItem(isoTarget);
+    if (afterIso && afterIso !== installed) await writeItem(backup, claudeAiOauthOnly(afterIso));
+    await deleteItem(isoTarget);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Live-sample the ACTIVE account off the live login, verifying the live
+ * credential belongs to it. `/usage` with no CLAUDE_CONFIG_DIR meters the live
+ * keychain item. A drifted active label surfaces as an error, not another
+ * account's bars.
+ */
+export async function probeActiveUsage(account: Account): Promise<SampleOutcome> {
+  const liveRaw = await readItem(liveTarget());
+  if (!liveRaw) return { ok: false, reason: "no live credential - run `claude` and `/login`" };
+  let creds: OAuthCreds;
+  try {
+    creds = CredentialBlobSchema.parse(JSON.parse(liveRaw)).claudeAiOauth;
+  } catch (e) {
+    return { ok: false, reason: `live credential blob unreadable (${String((e as Error).message ?? e).slice(0, 80)})` };
+  }
+
+  // A running claude keeps the live token fresh; after long idle it may not have.
+  if (isAccessTokenExpiring(creds, 300_000)) {
+    try {
+      await withClaudeRefreshLock(async () => {
+        const raw2 = (await readItem(liveTarget())) ?? liveRaw;
+        const current = CredentialBlobSchema.parse(JSON.parse(raw2)).claudeAiOauth;
+        creds = isAccessTokenExpiring(current, 300_000) ? await refreshCredential(current) : current;
+        if (creds !== current) await writeItem(liveTarget(), mergeIntoLive(raw2, creds));
+      });
+    } catch (e) {
+      if (e instanceof InvalidGrantError) return { ok: false, reason: "live refresh token dead - run `claude` and `/login`" };
+      return { ok: false, reason: `token refresh failed: ${String((e as Error).message ?? e)}` };
+    }
+  }
+
+  const mismatch = await identityMismatch(creds, account);
+  if (mismatch) return { ok: false, reason: `live ${mismatch} - active label drifted; run \`tokenmaxxing switch\`` };
+
+  const usage = await probeUsage();
+  return usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+}

package/src/lib/sessions.ts

@@ -0,0 +1,27 @@
+// Persist the flags a managed session was launched with, so any later relaunch
+// of that session id (a fresh supervisor invocation, or the depleted-pool
+// recovery in #20) re-applies them instead of dropping --dangerously-skip-
+// permissions / --model / etc.
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { paths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+
+const SessionSchema = z.object({ flags: z.array(z.string()), cwd: z.string() });
+
+function sessionFile(sid: string): string {
+  return join(paths.home, "sessions", `${sid}.json`);
+}
+
+export function saveSessionFlags(sid: string, flags: string[], cwd: string): void {
+  mkdirSync(join(paths.home, "sessions"), { recursive: true });
+  writeFileAtomic(sessionFile(sid), JSON.stringify({ flags, cwd }));
+}
+
+export function loadSessionFlags(sid: string): string[] | null {
+  const f = sessionFile(sid);
+  if (!existsSync(f)) return null;
+  return SessionSchema.parse(JSON.parse(readFileSync(f, "utf8"))).flags;
+}

package/src/lib/settings.ts

@@ -0,0 +1,141 @@
+// Idempotent merge of tokenmaxxing's three entries into the user-owned
+// ~/.claude/settings.json: a statusLine shim, a Stop hook, a SessionStart hook.
+// We APPEND to existing hook arrays and WRAP the existing statusLine - never clobber.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { paths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+
+/** Absolute path to the installed tokenmaxxing binary the settings entries call. */
+export function installedBin(): string {
+  return join(paths.binDir, "tokenmaxxing");
+}
+
+const HookCmdSchema = z.looseObject({ type: z.string(), command: z.string() });
+const HookGroupSchema = z.looseObject({ matcher: z.string().optional(), hooks: z.array(HookCmdSchema).default([]) });
+const StatusLineSchema = z.looseObject({ type: z.string(), command: z.string() });
+const SettingsSchema = z.looseObject({
+  statusLine: StatusLineSchema.optional(),
+  hooks: z.record(z.string(), z.array(HookGroupSchema)).optional(),
+});
+type Settings = z.infer<typeof SettingsSchema>;
+type HookGroup = z.infer<typeof HookGroupSchema>;
+
+const PRIOR_STATUSLINE_FILE = join(paths.home, "prior-statusline.json");
+
+const SUBCMD = {
+  statusline: "__statusline",
+  stop: "__stop-hook",
+  sessionStart: "__session-start",
+} as const;
+
+function readSettings(): Settings {
+  if (!existsSync(paths.claudeSettings)) return {};
+  return SettingsSchema.parse(JSON.parse(readFileSync(paths.claudeSettings, "utf8")));
+}
+
+function writeSettings(s: Settings): void {
+  writeFileAtomic(paths.claudeSettings, JSON.stringify(s, null, 2) + "\n", 0o644);
+}
+
+/** True if a hook/statusline command string is one tokenmaxxing installed. */
+export function isOurCommand(cmd: string | undefined): boolean {
+  if (!cmd) return false;
+  return (
+    cmd.includes(SUBCMD.statusline) ||
+    cmd.includes(SUBCMD.stop) ||
+    cmd.includes(SUBCMD.sessionStart) ||
+    // also match the installed bin path even if the subcommand text changes
+    cmd.includes(installedBin())
+  );
+}
+
+function ourHookGroup(sub: string): HookGroup {
+  return { hooks: [{ type: "command", command: `${JSON.stringify(installedBin())} ${sub}` }] };
+}
+
+function appendHook(s: Settings, event: string, sub: string): void {
+  s.hooks ??= {};
+  s.hooks[event] ??= [];
+  const arr = s.hooks[event]!;
+  const present = arr.some((g) => g.hooks?.some((h) => h.command?.includes(sub)));
+  if (!present) arr.push(ourHookGroup(sub));
+}
+
+function removeHook(s: Settings, event: string, sub: string): void {
+  const arr = s.hooks?.[event];
+  if (!arr) return;
+  s.hooks![event] = arr.filter((g) => !g.hooks?.some((h) => h.command?.includes(sub)));
+  if (s.hooks![event]!.length === 0) delete s.hooks![event];
+}
+
+const InstallResultSchema = z.object({ priorStatusLine: z.string().nullable() });
+export type InstallResult = z.infer<typeof InstallResultSchema>;
+
+/**
+ * Install the three entries. Returns the prior statusLine command that was
+ * wrapped (stored to disk so the shim can chain to it and uninstall can restore).
+ */
+export function installSettings(): InstallResult {
+  const s = readSettings();
+
+  // ---- statusLine: capture prior (unless it's already ours), then wrap.
+  let prior: string | null;
+  if (s.statusLine && !isOurCommand(s.statusLine.command)) {
+    prior = s.statusLine.command;
+    writeFileAtomic(PRIOR_STATUSLINE_FILE, JSON.stringify({ command: prior }) + "\n", 0o644);
+  } else {
+    prior = readPriorStatusLine();
+  }
+  s.statusLine = {
+    type: "command",
+    command: `${JSON.stringify(installedBin())} ${SUBCMD.statusline}`,
+  };
+
+  // ---- hooks: append ours if absent.
+  appendHook(s, "Stop", SUBCMD.stop);
+  appendHook(s, "SessionStart", SUBCMD.sessionStart);
+
+  writeSettings(s);
+  return { priorStatusLine: prior };
+}
+
+/** Remove our three entries and restore the prior statusLine if we have it. */
+export function uninstallSettings(): void {
+  const s = readSettings();
+  removeHook(s, "Stop", SUBCMD.stop);
+  removeHook(s, "SessionStart", SUBCMD.sessionStart);
+  if (s.statusLine && isOurCommand(s.statusLine.command)) {
+    const prior = readPriorStatusLine();
+    if (prior) s.statusLine = { type: "command", command: prior };
+    else delete s.statusLine;
+  }
+  writeSettings(s);
+}
+
+const PriorStatusLineSchema = z.object({ command: z.string() });
+
+export function readPriorStatusLine(): string | null {
+  if (!existsSync(PRIOR_STATUSLINE_FILE)) return null;
+  return PriorStatusLineSchema.parse(JSON.parse(readFileSync(PRIOR_STATUSLINE_FILE, "utf8"))).command;
+}
+
+const SettingsCheckSchema = z.object({
+  statusLineOk: z.boolean(),
+  stopOk: z.boolean(),
+  sessionStartOk: z.boolean(),
+});
+export type SettingsCheck = z.infer<typeof SettingsCheckSchema>;
+
+export function checkSettings(): SettingsCheck {
+  const s = readSettings();
+  const has = (event: string, sub: string) =>
+    !!s.hooks?.[event]?.some((g) => g.hooks?.some((h) => h.command?.includes(sub)));
+  return {
+    statusLineOk: isOurCommand(s.statusLine?.command),
+    stopOk: has("Stop", SUBCMD.stop),
+    sessionStartOk: has("SessionStart", SUBCMD.sessionStart),
+  };
+}