tokenmaxxing 0.19.1 → 1.0.0

package/src/lib/codexsample.ts

@@ -35,16 +35,25 @@ export async function sampleCodexAccount(input: { account: CodexAccount; liveAcc
     let auth = isLive ? readLiveCodexAuth() : readParkedCodexAuth({ credFile: account.credFile });
     if (!auth) return { ok: false, reason: isLive ? "live auth.json vanished" : "no parked credential", deadGrant: false };
     if (isCodexAccessExpiring({ auth, now })) {
-      // A parked blob whose account is RUNNING in another supervised session
-      // is superseded by that session's live rotations: refreshing it would
-      // trip the server's reuse punishment and kill the running session's
-      // grant family. Skip the refresh and report a miss instead.
-      if (!isLive && presentCodexAccountIds().has(account.accountId)) {
+      // NEVER refresh a PRESENT account's token, live or parked. A parked
+      // blob whose account is RUNNING in another supervised session is
+      // superseded by that session's live rotations, and the LIVE blob's
+      // running session can be mid-turn refreshing the same rotating token
+      // concurrently (both actors share the 300s margin): either way the
+      // loser of the race is reuse-punished into a dead grant family
+      // (closing-review catch; the idle-turn-boundary safety argument covers
+      // only the invoking session's own account). Parked reports a miss; live
+      // fetches on the unrotated token, still valid within the margin, and
+      // degrades to an honest miss once it expires.
+      const running = presentCodexAccountIds().has(account.accountId);
+      if (running && !isLive) {
         return { ok: false, reason: "running in a live codex session (parked token refresh unsafe)", deadGrant: false };
       }
-      auth = await refreshCodexAuth({ auth, now });
-      if (isLive) writeLiveCodexAuth({ auth });
-      writeParkedCodexAuth({ credFile: account.credFile, auth });
+      if (!running) {
+        auth = await refreshCodexAuth({ auth, now });
+        if (isLive) writeLiveCodexAuth({ auth });
+        writeParkedCodexAuth({ credFile: account.credFile, auth });
+      }
     }
     const usage = await fetchCodexUsage({ auth });
     return { ok: true, usage };

package/src/lib/codexswap.ts

@@ -78,7 +78,16 @@ export async function performCodexSwap(input: { target: CodexAccount }): Promise
   writeParkedCodexAuth({ credFile: target.credFile, auth: fresh });
 
   if (live && liveOwner) {
-    writeParkedCodexAuth({ credFile: liveOwner.credFile, auth: live });
+    // Last-moment re-read: a running codex (the Apps surface) can rotate the
+    // live token outside our flock between the identity resolution above and
+    // this harvest, and parking the earlier snapshot would strand the newest
+    // rotation of a reuse-punished grant family. A mid-swap identity change
+    // refuses rather than harvesting under a stale owner.
+    const liveNow = readLiveCodexAuth();
+    if (!liveNow || codexIdentityOf({ auth: liveNow }).accountId !== liveOwner.accountId) {
+      throw new Error("live codex credential changed mid-swap - refusing to harvest under a stale identity; retry");
+    }
+    writeParkedCodexAuth({ credFile: liveOwner.credFile, auth: liveNow });
     log("codexswap.harvest", { account: liveOwner.accountId.slice(0, 8) });
   }
 

package/src/lib/credstore.ts

@@ -23,8 +23,10 @@ export type CredTarget = z.infer<typeof CredTargetSchema>;
 
 const darwin = process.platform === "darwin";
 
+const BlobRecordSchema = z.record(z.string(), z.unknown());
+
 function isEnoent(e: unknown): boolean {
-  return (e as { code?: string }).code === "ENOENT";
+  return e instanceof Error && "code" in e && e.code === "ENOENT";
 }
 
 /** Read a target's credential blob. Returns null if it does not exist. */
@@ -91,7 +93,9 @@ export function claudeAiOauthOnly(fullBlobRaw: string): string {
 /** 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>) : {};
+  // null-check, not falsiness: an EXISTING-but-empty blob is corruption and
+  // must surface (JSON.parse throws), never be silently replaced as "missing".
+  const base = currentLiveRaw == null ? {} : BlobRecordSchema.parse(JSON.parse(currentLiveRaw));
   base["claudeAiOauth"] = freshClaudeAiOauth;
   return JSON.stringify(base);
 }

package/src/lib/decide.ts

@@ -27,7 +27,7 @@ import { maxBy } from "es-toolkit";
 import { z } from "zod";
 import { withLock } from "./lock.ts";
 import { paths } from "./paths.ts";
-import { loadAccounts, loadConfig, loadLastSwapAt, loadUsage, loadModelUsage, saveAccounts, saveModelUsage, usageTeeAt, writeUsage } from "./state.ts";
+import { loadAccounts, loadConfig, loadDepletedWait, loadLastSwapAt, loadUsage, loadModelUsage, saveAccounts, saveDepletedWait, saveModelUsage, usageTeeAt, writeUsage } from "./state.ts";
 import { readOAuthAccount } from "./claudejson.ts";
 import { chooseAndSwap, performSwap } from "./swap.ts";
 import { currentWins, effectiveBars, pickBest, pickEarliestReset, usableAt } from "./picker.ts";
@@ -40,15 +40,30 @@ 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. */
+  /** set when every account is depleted and the soonest recovery is known:
+   *  epoch ms that account recovers. The wait target on depleted-wait;
+   *  informational on a bare all-depleted (callers like `xx serve` park on
+   *  it - nothing here waits). */
   waitUntil: z.number().optional(),
 });
 export type SwapDecision = z.infer<typeof SwapDecisionSchema>;
 
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
+
 /** A window's usable-against percentage NOW: one whose cached reset has passed
- *  is empty again, never a switch reason. */
-function liveUsed(w: UsageWindow, now: number): number {
-  return w.resetsAt != null && w.resetsAt <= now ? 0 : w.usedPercentage;
+ *  is empty again, never a switch reason. A NULL-reset window (reset clock
+ *  failed to parse) self-bounds at sampledAt + the window's own duration,
+ *  mirroring the picker's blockedUntil and the codex liveUsed: without the
+ *  bound the trigger side kept reading a long-stale over-bar row as live while
+ *  the screening side had already released it - the two halves of one decision
+ *  disagreed, forcing hard-path swaps (or waitUntil=now respawn churn) off a
+ *  healthy account (adversarial-review catch). */
+function liveUsed(input: { window: UsageWindow; windowMs: number; sampledAt: number; now: number }): number {
+  const { window: w, windowMs, sampledAt, now } = input;
+  if (w.resetsAt != null) return w.resetsAt <= now ? 0 : w.usedPercentage;
+  if (now >= sampledAt + windowMs) return 0;
+  return w.usedPercentage;
 }
 
 /** The family's weekly cap among the `/usage` rows; when several rows match the
@@ -58,7 +73,7 @@ function capForFamily(mu: ModelUsageState, family: string, now: number): UsageWi
   const rows = Object.entries(mu.perModel)
     .filter(([k]) => familyTokens(k).includes(family))
     .map(([, w]) => w);
-  return maxBy(rows, (w) => liveUsed(w, now));
+  return maxBy(rows, (w) => liveUsed({ window: w, windowMs: WEEK_MS, sampledAt: mu.sampledAt ?? mu.ts, now }));
 }
 
 /** True if the active account is over its floor on ANY screening bar: the 5h
@@ -68,11 +83,14 @@ function capForFamily(mu: ModelUsageState, family: string, now: number): UsageWi
 function isOver(u: UsageState | null, mu: ModelUsageState | null, org: string | null, cfg: Config, now: number): boolean {
   if (!u || !org || u.org !== org) return false;
   const bars = effectiveBars(cfg);
-  if (liveUsed(u.fiveHour, now) >= bars.session || liveUsed(u.sevenDay, now) >= bars.weekly) return true;
+  if (
+    liveUsed({ window: u.fiveHour, windowMs: FIVE_HOURS_MS, sampledAt: u.ts, now }) >= bars.session ||
+    liveUsed({ window: u.sevenDay, windowMs: WEEK_MS, sampledAt: u.ts, now }) >= bars.weekly
+  ) return true;
   if (mu && mu.org === org) {
     for (const family of gatedFamilies(u.model, cfg.policy.switchModels)) {
       const cap = capForFamily(mu, family, now);
-      if (cap && liveUsed(cap, now) >= bars.weekly) return true;
+      if (cap && liveUsed({ window: cap, windowMs: WEEK_MS, sampledAt: mu.sampledAt ?? mu.ts, now }) >= bars.weekly) return true;
     }
   }
   return false;
@@ -88,7 +106,7 @@ function needsPerModel(u: UsageState | null, cfg: Config): boolean {
  *  a fresh session rides its account - no churn. */
 function isEngaged(u: UsageState | null, mu: ModelUsageState | null, org: string | null, cfg: Config, now: number): boolean {
   if (!u || !org || u.org !== org) return false;
-  return liveUsed(u.fiveHour, now) >= cfg.policy.greedySessionFloor || isOver(u, mu, org, cfg, now);
+  return liveUsed({ window: u.fiveHour, windowMs: FIVE_HOURS_MS, sampledAt: u.ts, now }) >= cfg.policy.greedySessionFloor || isOver(u, mu, org, cfg, now);
 }
 
 const SnapshotsSchema = z.object({
@@ -140,10 +158,14 @@ async function loadFreshSnapshots(cfg: Config, org: string | null, now: number):
           u = { fiveHour: full.session, sevenDay: full.weekAll, org, ts, model: null };
           writeUsage(u);
         }
-        mu = { perModel: full.perModel, org, ts };
+        mu = { perModel: full.perModel, org, ts, sampledAt: ts };
         saveModelUsage(mu);
       } else {
-        mu = { perModel: mu?.org === org ? (mu?.perModel ?? {}) : {}, org, ts };
+        // the anti-storm stamp: ts=now suppresses re-probing, but the carried
+        // rows keep their ORIGINAL sample time - dating them by ts rolled the
+        // null-reset self-bound forward on every failed probe (closing-review
+        // catch).
+        mu = { perModel: mu?.org === org ? (mu?.perModel ?? {}) : {}, org, ts, sampledAt: mu?.org === org ? (mu?.sampledAt ?? mu?.ts) : undefined };
         saveModelUsage(mu);
       }
     }
@@ -156,7 +178,7 @@ async function loadFreshSnapshots(cfg: Config, org: string | null, now: number):
  *  sooner runs model-blind on data the swap itself invalidated - that is how a
  *  model-aware swap got immediately undone into an A<->B respawn loop. Manual
  *  `switch` is unaffected. */
-const POST_SWAP_COOLDOWN_MS = 45_000;
+export const POST_SWAP_COOLDOWN_MS = 45_000;
 
 /**
  * `anticipatory` allows the depleted path to swap onto an account that is still
@@ -170,7 +192,7 @@ const POST_SWAP_COOLDOWN_MS = 45_000;
 export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = false): Promise<SwapDecision> {
   const lastSwapAt = loadLastSwapAt();
   if (lastSwapAt != null && now - lastSwapAt < POST_SWAP_COOLDOWN_MS) {
-    return { swapped: false, account: null, reason: "post-swap-cooldown" };
+    return depletedReplay(now) ?? { swapped: false, account: null, reason: "post-swap-cooldown" };
   }
 
   const cfg = loadConfig();
@@ -178,8 +200,16 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
 
   const { u: usage, mu } = await loadFreshSnapshots(cfg, activeOrg, now);
 
-  // cheap pre-check off the lock - the common case exits here.
+  // cheap pre-check off the lock - the common case exits here. When there is
+  // NO measurement for the live org (a pre-park just cleared the snapshots),
+  // a recorded depleted-wait still replays; a fresh measurement that reads
+  // under-threshold never does - measured-healthy must win over a stale wait.
   if (!isEngaged(usage, mu, activeOrg, cfg, now)) {
+    const measured = usage != null && activeOrg != null && usage.org === activeOrg;
+    if (!measured) {
+      const replay = depletedReplay(now);
+      if (replay) return replay;
+    }
     return { swapped: false, account: null, reason: "under-threshold-or-stale" };
   }
 
@@ -189,24 +219,57 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
     const u2 = loadUsage() ?? usage;
     const mu2 = needsPerModel(u2, cfg) ? loadModelUsage() ?? mu : null;
 
+    // A live login whose org is KNOWN but outside the pool: do nothing - the
+    // codex org-guard analog. performSwap would refuse any swap over it (an
+    // unpooled credential's only copy must never be overwritten), and the
+    // seat fallback below must not stand in a stale pooled label for it: the
+    // depleted path could then park a supervised session against the LABELED
+    // account's reset while the running login is someone else entirely
+    // (pullfrog review catch, PR #33).
+    if (org2 != null && !idx.accounts.some((a) => a.organizationUuid === org2)) {
+      return { swapped: false, account: null, reason: "live-credential-not-in-pool" };
+    }
+
     // record the active account's aggregate usage so the picker + `status` see it.
+    // Resolved by the LIVE org the guard just verified, never the
+    // activeAccountUuid label: after a manual /login the label drifts (the
+    // surviving drift source, see cli/switch.ts), and a label-keyed write
+    // would stamp the live account's windows onto whichever account the label
+    // still names (closing-review catch, mirrors the codex live-identity rule).
     if (u2 && org2 && u2.org === org2) {
-      const active = idx.accounts.find((a) => a.accountUuid === idx.activeAccountUuid);
+      const active = idx.accounts.find((a) => a.organizationUuid === org2);
       if (active) {
         active.lastUsage = { fiveHour: u2.fiveHour, sevenDay: u2.sevenDay };
         active.lastUsageAt = u2.ts;
         // Snapshot per-model caps too, so they still show after we switch away.
         // An empty map is a failed probe's anti-storm stamp, not a measurement -
         // it must not erase the burnt-cap snapshot the picker screens on.
-        if (mu2 && mu2.org === org2 && Object.keys(mu2.perModel).length > 0) active.lastPerModel = mu2.perModel;
+        if (mu2 && mu2.org === org2 && Object.keys(mu2.perModel).length > 0) {
+          active.lastPerModel = mu2.perModel;
+          // the rows' TRUE sample time, not the write time: an anti-storm
+          // stamp re-writes ts while carrying old rows (closing-review catch).
+          active.lastPerModelAt = mu2.sampledAt ?? mu2.ts;
+        }
         saveAccounts(idx);
       }
     }
 
     if (!isEngaged(u2, mu2, org2, cfg, now)) {
-      return { swapped: false, account: null, reason: "raced-already-swapped" };
+      return depletedReplay(now) ?? { swapped: false, account: null, reason: "raced-already-swapped" };
     }
 
+    // The SEAT every path below evaluates and excludes: the live org's pooled
+    // account when resolvable, the stored label only as fallback - the same
+    // identity rule as the usage stamp above and depletedReplay. Trusting the
+    // label here let the greedy convergence judge a stale account as "the
+    // seat" after a manual /login, ranking against the wrong cached windows
+    // and even offering the LIVE account as a swap target (bugbot review
+    // catch, PR #33).
+    const seatOf = (idx2: { activeAccountUuid: string | null; accounts: Account[] }): Account | null =>
+      idx2.accounts.find((a) => a.organizationUuid === org2) ??
+      idx2.accounts.find((a) => a.accountUuid === idx2.activeAccountUuid) ??
+      null;
+
     // Candidates are screened by the same families that drove this decision, so
     // the pool cannot ping-pong onto an account the gate would immediately flag.
     const switchFamilies = gatedFamilies(u2?.model ?? null, cfg.policy.switchModels);
@@ -224,11 +287,11 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
       const ctxAll = { now, thresholds: effectiveBars(cfg), currentAccountUuid: null, switchFamilies };
       while (true) {
         const cur = loadAccounts();
-        const active = cur.accounts.find((a) => a.accountUuid === cur.activeAccountUuid) ?? null;
+        const active = seatOf(cur);
         if (currentWins(active, cur.accounts, ctxAll)) {
           return { swapped: false, account: null, reason: "current-best" };
         }
-        const best = pickBest(cur.accounts, { ...ctxAll, currentAccountUuid: cur.activeAccountUuid });
+        const best = pickBest(cur.accounts, { ...ctxAll, currentAccountUuid: active?.accountUuid ?? null });
         if (!best) return { swapped: false, account: null, reason: "no-usable-target" };
         try {
           await performSwap(best);
@@ -241,42 +304,66 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
       }
     }
 
-    const landed = await chooseAndSwap({ now, thresholds: effectiveBars(cfg), switchFamilies });
+    const landed = await chooseAndSwap({ now, thresholds: effectiveBars(cfg), switchFamilies, currentAccountUuid: seatOf(loadAccounts())?.accountUuid ?? null });
     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, thresholds: effectiveBars(cfg), currentAccountUuid: fresh.activeAccountUuid, switchFamilies };
-    const current = fresh.accounts.find((a) => a.accountUuid === fresh.activeAccountUuid);
-    const currentAt = current ? usableAt(current, ctx) : Number.POSITIVE_INFINITY;
-    const other = pickEarliestReset(fresh.accounts, ctx);
+    // Every account is depleted. Wait for whichever recovers soonest (including
+    // the current one), if that reset is within the auto-wait window. A dead
+    // grant on the chosen pre-park target must not abort the wait: performSwap
+    // persists needs-reauth before throwing, so each retry re-ranks without the
+    // dead account and the loop terminates (mirrors the greedy loop above).
+    while (true) {
+      const fresh = loadAccounts();
+      const current = seatOf(fresh);
+      const ctx = { now, thresholds: effectiveBars(cfg), currentAccountUuid: current?.accountUuid ?? null, switchFamilies };
+      const currentAt = current ? usableAt(current, ctx) : 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; }
+      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" };
-    }
+      if (!target || waitUntil - now > cfg.policy.maxWaitMs) {
+        log("decide.depleted", { waitUntil: Number.isFinite(waitUntil) ? waitUntil : 0 });
+        return { swapped: false, account: null, reason: "all-depleted", ...(Number.isFinite(waitUntil) ? { waitUntil } : {}) };
+      }
 
-    const isCurrent = target.accountUuid === fresh.activeAccountUuid;
-    if (!isCurrent && !anticipatory) {
-      log("decide.depleted_no_park", { account: target.accountUuid.slice(0, 8), waitUntil });
-      return { swapped: false, account: null, reason: "all-depleted" };
-    }
-    if (!isCurrent) {
-      try {
-        await performSwap(target);
-      } catch (e) {
-        if (e instanceof InvalidGrantError) return { swapped: false, account: null, reason: "all-depleted" };
-        throw e;
+      const isCurrent = target.accountUuid === (current?.accountUuid ?? null);
+      if (!isCurrent && !anticipatory) {
+        log("decide.depleted_no_park", { account: target.accountUuid.slice(0, 8), waitUntil });
+        return { swapped: false, account: null, reason: "all-depleted", waitUntil };
+      }
+      if (!isCurrent) {
+        try {
+          await performSwap(target);
+        } catch (e) {
+          if (e instanceof InvalidGrantError) continue; // dead grant - re-rank without it
+          throw e;
+        }
       }
+      // Persist the wait so sibling hooks arriving through the cooldown / raced
+      // / cleared-snapshot exits replay it and write their OWN respawn markers.
+      saveDepletedWait({ waitUntil, accountUuid: target.accountUuid, ts: now });
+      log("decide.depleted_wait", { account: target.accountUuid.slice(0, 8), waitUntil });
+      return { swapped: !isCurrent, account: target, reason: "depleted-wait", waitUntil };
     }
-    log("decide.depleted_wait", { account: target.accountUuid.slice(0, 8), waitUntil });
-    return { swapped: !isCurrent, account: target, reason: "depleted-wait", waitUntil };
   });
 }
+
+/** The recorded depleted-wait, iff still standing: unexpired and still naming
+ *  the LIVE seat. The check reads claude's own oauthAccount, not the
+ *  accounts.json label: a tokenmaxxing swap rewrites oauthAccount inside its
+ *  critical section and a manual /login rewrites it too, while the label lags
+ *  a manual /login and would replay a wait for an account no longer live
+ *  (review catch, PR #31). A real swap elsewhere, a manual /login, or the
+ *  reset passing all kill the record. */
+function depletedReplay(now: number): SwapDecision | null {
+  const rec = loadDepletedWait();
+  if (!rec || rec.waitUntil <= now) return null;
+  const account = loadAccounts().accounts.find((a) => a.accountUuid === rec.accountUuid) ?? null;
+  if (!account) return null;
+  if (account.organizationUuid !== (readOAuthAccount()?.organizationUuid ?? null)) return null;
+  return { swapped: false, account, reason: "depleted-wait", waitUntil: rec.waitUntil };
+}

package/src/lib/install.ts

@@ -2,13 +2,13 @@
 // 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 { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { escape } from "es-toolkit";
 import { z } from "zod";
 import { codexPaths, HOME, paths } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
-import { installedBin, installSettings, uninstallSettings } from "./settings.ts";
+import { installedBin, installSettings, isOurHookCommand, uninstallSettings } from "./settings.ts";
 import { resolveRealClaude } from "./claudebin.ts";
 
 const InstallOutcomeSchema = z.object({
@@ -84,19 +84,27 @@ function codexStopHookCommand(): string {
  *  preserving every other declaration. Codex skips new hooks until the user
  *  trusts them via /hooks (trust is recorded against the hook's hash), so the
  *  caller must surface that step. */
+/** Surgical WITHIN groups, ownership verified structurally (closing-review
+ *  catch, mirroring settings.ts's removeHook fix): the old whole-group filter
+ *  deleted a foreign hook the user had appended into our group - the natural
+ *  edit, since install writes exactly one group - and its includes() match
+ *  claimed any command merely mentioning the subcommand. */
+function withoutOurCodexStopHooks(groups: { hooks: { type?: string; command?: string }[] }[]): typeof groups {
+  return groups
+    .map((group) => ({ ...group, hooks: group.hooks.filter((hook) => !isOurHookCommand(hook.command ?? "", CODEX_STOP_HOOK_SUBCOMMAND)) }))
+    .filter((group) => group.hooks.length > 0);
+}
+
 export function installCodexStopHook(): void {
   const current = existsSync(codexPaths.hooksJson)
     ? CodexHooksFileSchema.parse(JSON.parse(readFileSync(codexPaths.hooksJson, "utf8")))
     : CodexHooksFileSchema.parse({});
-  const foreign = current.hooks.Stop.filter(
-    (group) => !group.hooks.some((hook) => hook.command?.includes(CODEX_STOP_HOOK_SUBCOMMAND)),
-  );
   const next = {
     ...current,
     hooks: {
       ...current.hooks,
       Stop: [
-        ...foreign,
+        ...withoutOurCodexStopHooks(current.hooks.Stop),
         { hooks: [{ type: "command", command: codexStopHookCommand(), timeout: 120, statusMessage: "tokenmaxxing switch check" }] },
       ],
     },
@@ -112,7 +120,7 @@ export function uninstallCodexStopHook(): void {
     ...current,
     hooks: {
       ...current.hooks,
-      Stop: current.hooks.Stop.filter((group) => !group.hooks.some((hook) => hook.command?.includes(CODEX_STOP_HOOK_SUBCOMMAND))),
+      Stop: withoutOurCodexStopHooks(current.hooks.Stop),
     },
   };
   writeFileAtomic(codexPaths.hooksJson, JSON.stringify(next, null, 2) + "\n");
@@ -165,7 +173,7 @@ function run(cmd: string[]): boolean {
 /** Install + activate the periodic check job. False means the unit files are in
  *  place but activation failed (e.g. systemd user session absent over ssh) -
  *  the caller prints the manual activation step. */
-export function installCheckTimer(): boolean {
+function installCheckTimer(): boolean {
   if (process.platform === "darwin") {
     const plist = launchdPlist();
     writeFileAtomic(
@@ -245,17 +253,71 @@ export function checkTimerHealthy(): boolean {
   );
 }
 
-export function uninstallCheckTimer(): void {
+/** The manual deactivation command for a still-loaded timer, per platform. */
+export function timerDeactivationHint(): string {
+  if (process.platform === "darwin") {
+    return `launchctl bootout gui/$(id -u)/${LAUNCHD_LABEL}`;
+  }
+  return "systemctl --user disable --now tokenmaxxing-check.timer";
+}
+
+/** Is the launchd check job loaded? Exit contract verified on this machine
+ *  (macOS 26, 2026-07-20): `launchctl print` exits 0 for a loaded job and 113
+ *  for a missing one. Anything else - including a spawn failure or timeout -
+ *  is "unavailable": an unanswerable probe must never read as "not loaded". */
+function launchdJobLoaded(): "loaded" | "not-loaded" | "unavailable" {
+  const domain = launchdDomain();
+  if (domain == null) return "unavailable";
+  try {
+    const { exitCode } = Bun.spawnSync(["launchctl", "print", `${domain}/${LAUNCHD_LABEL}`], { stdout: "ignore", stderr: "ignore", timeout: 10_000 });
+    if (exitCode === 0) return "loaded";
+    return exitCode === 113 ? "not-loaded" : "unavailable";
+  } catch {
+    return "unavailable";
+  }
+}
+
+/** Is the systemd check timer active? Classification goes by the state
+ *  string, never the exit code: systemctl(1) documents only "0 if at least
+ *  one is active, non-zero otherwise" for is-active, but guarantees "unless
+ *  --quiet is specified, this will also print the current unit state to
+ *  standard output" (verified against the systemd manpage 2026-07-20). The
+ *  failure mode is container-verified (ubuntu:24.04 systemd, no user bus,
+ *  2026-07-20): a dead session bus prints NOTHING to stdout ("Failed to
+ *  connect to bus" goes to stderr, exit 1), so an empty or unrecognized
+ *  stdout is "unavailable" - "cannot ask" never reads as "inactive". */
+function systemdTimerActive(): "active" | "not-active" | "unavailable" {
+  try {
+    const proc = Bun.spawnSync(["systemctl", "--user", "is-active", "tokenmaxxing-check.timer"], { stdout: "pipe", stderr: "ignore", timeout: 10_000 });
+    const state = proc.stdout.toString().trim();
+    if (state === "active" || state === "activating" || state === "reloading") return "active";
+    if (state === "inactive" || state === "failed" || state === "deactivating" || state === "unknown" || state === "maintenance") return "not-active";
+    return "unavailable";
+  } catch {
+    return "unavailable";
+  }
+}
+
+/** True when the job is verifiably no longer loaded. A swallowed bootout
+ *  failure once meant a half-uninstalled state kept firing `tokenmaxxing
+ *  check` every 180s against a package that may be gone, silently
+ *  (closing-review catch): deactivation is checked, not assumed - a job seen
+ *  loaded must deactivate successfully, and an unanswerable probe (service
+ *  manager unusable) reports false rather than pretending it is gone. */
+function uninstallCheckTimer(): boolean {
   if (process.platform === "darwin") {
     const domain = launchdDomain();
-    if (domain != null) run(["launchctl", "bootout", `${domain}/${LAUNCHD_LABEL}`]);
+    const loaded = launchdJobLoaded();
+    const deactivated = loaded === "loaded" && domain != null ? run(["launchctl", "bootout", `${domain}/${LAUNCHD_LABEL}`]) : loaded === "not-loaded";
     rmSync(launchdPlist(), { force: true });
-    return;
+    return deactivated;
   }
-  run(["systemctl", "--user", "disable", "--now", "tokenmaxxing-check.timer"]);
+  const active = systemdTimerActive();
+  const deactivated = active === "active" ? run(["systemctl", "--user", "disable", "--now", "tokenmaxxing-check.timer"]) : active === "not-active";
   rmSync(join(paths.systemdUserDir, "tokenmaxxing-check.timer"), { force: true });
   rmSync(join(paths.systemdUserDir, "tokenmaxxing-check.service"), { force: true });
   run(["systemctl", "--user", "daemon-reload"]);
+  return deactivated;
 }
 
 /** The rc file of the user's login shell, or null when the shell is unknown.
@@ -275,10 +337,33 @@ const PATH_LINE_MARK = "# tokenmaxxing PATH";
  *  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";
+  // Write through a dotfile-managed symlink, never over it: writeFileAtomic
+  // renames a sibling temp over its target, which would replace the link with
+  // a plain file while the dotfiles target keeps the stale line (PR #36
+  // second-round catch).
+  const target = existsSync(rc) ? realpathSync(rc) : rc;
+  const current = existsSync(target) ? readFileSync(target, "utf8") : "";
+  const isCurrentExport = (line: string) => line.includes(`${paths.binDir}:`) || line.includes(`${dir}:`);
+  const lines = current === "" ? [] : current.split("\n");
+  // A marked line for a DIFFERENT dir is removed even when the current dir is
+  // also exported: PATH prepends stack, so a stale marked line BELOW the
+  // current one would still win resolution - the recursion incident's exact
+  // vector (closing-review catch + PR #36 second-round catch). A bare marker
+  // check alone once kept such a line alive after a TOKENMAXXING_HOME
+  // relocation.
+  const kept = lines.filter((line) => isCurrentExport(line) || !line.includes(PATH_LINE_MARK));
+  if (kept.length !== lines.length) {
+    const body = kept.join("\n");
+    const sep0 = body === "" || body.endsWith("\n") ? "" : "\n";
+    const addition = kept.some(isCurrentExport) ? "" : `export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`;
+    // preserve the rc's own mode: writeFileAtomic defaults to 0600, which
+    // would silently tighten a normally 0644 shell rc (PR #36 review catch)
+    writeFileAtomic(target, `${body}${sep0}${addition}`, statSync(target).mode & 0o777);
+    return "added";
+  }
+  if (lines.some(isCurrentExport)) return "present";
   const sep = current === "" || current.endsWith("\n") ? "" : "\n";
-  appendFileSync(rc, `${sep}export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`);
+  appendFileSync(target, `${sep}export PATH="${dir}:$PATH" ${PATH_LINE_MARK}\n`);
   return "added";
 }
 
@@ -318,11 +403,34 @@ export function findClaudeShadowers(rcText: string): ShellShadower[] {
   return out;
 }
 
-export function uninstallSupervisor(): void {
+/** Remove ONLY the marker-tagged PATH line this tool added; a hand-added
+ *  PATH entry without the marker is the user's own. A stale `# tokenmaxxing
+ *  PATH` line pointing at an emptied binDir is exactly how the supervisor
+ *  recursion incident started (see AGENTS.md), so uninstall must not leave
+ *  one behind (closing-review catch). Returns true when a line was removed. */
+export function removePathFromRc(rc: string): boolean {
+  if (!existsSync(rc)) return false;
+  // same symlink + mode treatment as ensurePathInRc: write through a
+  // dotfile-managed link, keep the rc's own permissions (PR #36 catches)
+  const target = realpathSync(rc);
+  const lines = readFileSync(target, "utf8").split("\n");
+  const kept = lines.filter((line) => !line.includes(PATH_LINE_MARK));
+  if (kept.length === lines.length) return false;
+  writeFileAtomic(target, kept.join("\n"), statSync(target).mode & 0o777);
+  return true;
+}
+
+const UninstallOutcomeSchema = z.object({ timerDeactivated: z.boolean(), pathLineRemoved: z.boolean() });
+export type UninstallOutcome = z.infer<typeof UninstallOutcomeSchema>;
+
+export function uninstallSupervisor(): UninstallOutcome {
   uninstallSettings();
-  uninstallCheckTimer();
+  const timerDeactivated = uninstallCheckTimer();
   uninstallCodexSupervisor();
   for (const f of [paths.supervisorLink, join(paths.binDir, "xx"), installedBin()]) {
     if (existsSync(f)) rmSync(f, { force: true });
   }
+  const rc = shellRcPath();
+  const pathLineRemoved = rc != null && removePathFromRc(rc);
+  return { timerDeactivated, pathLineRemoved };
 }