tokenmaxxing 0.19.1 → 1.0.0

package/src/lib/claudelock.ts

@@ -1,54 +1,129 @@
-// 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 98% usage trigger).
+// Interlock with Claude Code's OWN credential-refresh locks so our live-store
+// writes can't interleave with a concurrent token refresh. Binary-verified
+// against 2.1.214's embedded refresh code: claude takes TWO proper-lockfile
+// (mkdir-based) locks rooted at its credentials dir - the primary
+// <credDir>/.oauth_refresh.lock plus a legacy sibling <realpath(credDir)>.lock
+// (~/.claude.lock by default, kept for coordination with older versions) -
+// with stale: 60s, a 5s lock-mtime heartbeat while held, and on contention it
+// retries 5x with 1-2s jitter then FAILS the refresh (lock_timeout) instead of
+// proceeding unlocked. We mirror all of that, including the failure: a lock
+// still held past the retries means a refresh is mid-flight, which is exactly
+// when a live-store write could clobber a rotation. Callers retry next tick.
+//
+// Theft is detected the way proper-lockfile does it: the heartbeat re-stats
+// each lock and compares against the mtime WE last stored - a deviation or a
+// vanished dir means someone reclaimed the lock (only possible if this process
+// stalled past the 60s stale bar). fn gets a `compromised()` probe to check
+// before persisting, release skips dirs we no longer own, and the wrapper
+// throws terminally so no caller trusts work done on a stolen lock.
 
-import { mkdirSync, rmdirSync, statSync } from "node:fs";
+import { mkdirSync, realpathSync, rmdirSync, statSync, utimesSync } from "node:fs";
 import { join } from "node:path";
-import { paths } from "./paths.ts";
+import { delay } from "es-toolkit";
+import { z } from "zod";
+import { credDir } from "./paths.ts";
 import { log } from "./log.ts";
 
-const STALE_MS = 20_000; // proper-lockfile default stale is 10s; be generous
+const STALE_MS = 60_000; // claude's own proper-lockfile `stale`
+const HEARTBEAT_MS = 5_000; // claude's own `update` cadence
+const ATTEMPTS = 5; // claude's own ELOCKED retry budget
+const RETRY_MS = 1_000; // claude sleeps 1000 + rand(1000) between attempts
+
+/** mkdir-take one lock dir, reclaiming it when older than claude's stale bar. */
+function tryAcquire(lockDir: string): boolean {
+  try {
+    mkdirSync(lockDir);
+    return true;
+  } catch (e) {
+    const errno = z.object({ code: z.string() }).safeParse(e);
+    if (!errno.success || errno.data.code !== "EEXIST") throw e;
+  }
+  try {
+    if (Date.now() - statSync(lockDir).mtimeMs > STALE_MS) {
+      rmdirSync(lockDir);
+      mkdirSync(lockDir);
+      return true;
+    }
+  } catch { /* raced: another actor reclaimed it first */ }
+  return false;
+}
 
 export async function withClaudeRefreshLock<T>(
-  fn: () => Promise<T> | T,
-  opts: { timeoutMs?: number } = {},
+  fn: (lock: { compromised: () => boolean }) => Promise<T> | T,
+  opts: { attempts?: number; retryMs?: number; heartbeatMs?: number } = {},
 ): Promise<T> {
-  const lockDir = join(paths.claudeDir, ".oauth_refresh.lock");
-  const timeoutMs = opts.timeoutMs ?? 3000;
-  const start = Date.now();
-  let held = false;
+  const attempts = opts.attempts ?? ATTEMPTS;
+  const retryMs = opts.retryMs ?? RETRY_MS;
+  const dir = credDir();
+  mkdirSync(dir, { recursive: true }); // claude mkdirs it before locking too
+  const primary = join(dir, ".oauth_refresh.lock");
+  let legacyRoot = dir;
+  try { legacyRoot = realpathSync(dir); } catch { /* unresolvable: lock the raw path, like claude */ }
+  const legacy = `${legacyRoot}.lock`;
 
-  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;
+  const held: string[] = []; // in release order: legacy first, then primary (claude's order)
+  for (let attempt = 1; held.length === 0; attempt++) {
+    if (tryAcquire(primary)) {
+      try {
+        if (tryAcquire(legacy)) {
+          held.push(legacy, primary);
+          break;
+        }
+      } catch (e) {
+        // claude proceeds on a legacy acquire ERROR; only contention aborts.
+        log("claudelock.legacy_error", { err: e instanceof Error ? e.message : String(e) });
+        held.push(primary);
+        break;
       }
-      // parent dir missing or other error → skip the interlock entirely
-      break;
+      rmdirSync(primary); // legacy contested: release and re-take both, like claude
     }
+    if (attempt >= attempts) {
+      log("claudelock.contested", { attempts: attempt });
+      throw new Error(
+        "claude's credential-refresh lock is contested (a token refresh is likely mid-flight) - not touching the live credential store; retry shortly",
+      );
+    }
+    await delay(retryMs + Math.random() * retryMs);
   }
-  if (!held) log("claudelock.proceed_without", {});
+
+  // the mtime we last stored per lock; a deviation means the lock was stolen.
+  const ours = new Map<string, number>();
+  for (const d of held) ours.set(d, statSync(d).mtimeMs);
+  let compromised = false;
+  const markCompromised = () => {
+    if (!compromised) {
+      compromised = true;
+      log("claudelock.compromised", {});
+    }
+  };
+  const heartbeat = setInterval(() => {
+    const now = new Date();
+    for (const d of held) {
+      try {
+        if (statSync(d).mtimeMs !== ours.get(d)) {
+          markCompromised(); // someone re-took it; stop touching their lock
+          continue;
+        }
+        utimesSync(d, now, now);
+        ours.set(d, statSync(d).mtimeMs);
+      } catch {
+        markCompromised(); // dir vanished: stolen or force-cleaned
+      }
+    }
+  }, opts.heartbeatMs ?? HEARTBEAT_MS);
 
   try {
-    return await fn();
+    const result = await fn({ compromised: () => compromised });
+    if (compromised) {
+      throw new Error("claude's credential-refresh lock was reclaimed while held (this process stalled past the 60s stale bar) - treat this critical section as failed");
+    }
+    return result;
   } finally {
-    if (held) {
-      try { rmdirSync(lockDir); } catch { /* already gone */ }
+    clearInterval(heartbeat);
+    for (const d of held) {
+      try {
+        if (statSync(d).mtimeMs === ours.get(d)) rmdirSync(d); // release only what is still ours
+      } catch { /* already gone */ }
     }
   }
 }

package/src/lib/codexauth.ts

@@ -4,7 +4,7 @@
 // rust-v0.144.5 manager.rs), so every mutation here runs under tokenmaxxing's
 // own codex flock, held by the caller.
 
-import { readFileSync } from "node:fs";
+import { readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { writeFileAtomic } from "./atomic.ts";
@@ -17,7 +17,12 @@ function isEnoent(e: unknown): boolean {
 
 /** auth.json at an explicit path (the live file, or an onboard dir's), or null
  *  when absent. Throws on a present-but-unparsable file: that is drift to
- *  surface, not to paper over. */
+ *  surface, not to paper over. One valid-but-unpoolable state maps to null
+ *  instead of throwing: `codex login --with-api-key` writes auth.json with
+ *  `tokens` OMITTED (serde skip_serializing_if, verified rust-v0.144.5) - the
+ *  real binary runs fine on it, so the shim and status must too, and with no
+ *  ChatGPT tokens there is nothing tokenmaxxing can pool (closing-review
+ *  catch). */
 export function readCodexAuthAt(input: { path: string }): CodexAuthJson | null {
   let raw: string;
   try {
@@ -26,7 +31,10 @@ export function readCodexAuthAt(input: { path: string }): CodexAuthJson | null {
     if (isEnoent(e)) return null;
     throw e;
   }
-  return CodexAuthJsonSchema.parse(JSON.parse(raw));
+  const parsed = JSON.parse(raw);
+  const probe = z.looseObject({ tokens: z.unknown().optional() }).parse(parsed);
+  if (probe.tokens === undefined || probe.tokens === null) return null;
+  return CodexAuthJsonSchema.parse(parsed);
 }
 
 /** The live auth.json, or null when codex has no login here. */
@@ -57,6 +65,13 @@ export function writeParkedCodexAuth(input: { credFile: string; auth: CodexAuthJ
   writeFileAtomic(parkedPath(input), JSON.stringify(CodexAuthJsonSchema.parse(input.auth), null, 2), 0o600);
 }
 
+/** `rm --codex` uses this so the path shape (.json suffix) has one owner:
+ *  a hand-built path without the suffix silently missed the real file under
+ *  rmSync force (PR #37 review catch). */
+export function deleteParkedCodexAuth(input: { credFile: string }): void {
+  rmSync(parkedPath(input), { force: true });
+}
+
 /** Identity claims inside the id_token JWT payload (verified against a live
  *  0.144.4 token: the chatgpt fields sit under the api.openai.com/auth claim). */
 const IdClaimsSchema = z.looseObject({

package/src/lib/codexbin.ts

@@ -10,7 +10,7 @@ import { loadConfig } from "./state.ts";
 import { paths } from "./paths.ts";
 
 /** First PATH entry with a `codex` that is not us. null when PATH has none. */
-export function scanPathForCodex(): string | null {
+function scanPathForCodex(): string | null {
   for (const d of (process.env.PATH ?? "").split(":")) {
     if (!d) continue;
     const cand = join(d, "codex");

package/src/lib/codexdecide.ts

@@ -6,8 +6,11 @@
 // depleted pre-park (a swap only lands where a window is usable NOW; a
 // depleted pool stays put and recovers when a cached reset passes).
 
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
 import { z } from "zod";
 import { withLock } from "./lock.ts";
+import { writeFileAtomic } from "./atomic.ts";
 import { codexPaths } from "./paths.ts";
 import { loadConfig } from "./state.ts";
 import { loadCodexAccounts, loadCodexLastSwapAt, saveCodexAccounts } from "./codexstate.ts";
@@ -15,12 +18,12 @@ import { codexCurrentWins, isCodexEngaged, isCodexExhausted, pickBestCodex } fro
 import { performCodexSwap } from "./codexswap.ts";
 import { CodexInvalidGrantError, refreshCodexAuth } from "./codexoauth.ts";
 import { fetchCodexUsage } from "./codexusage.ts";
-import { isCodexAccessExpiring, readLiveCodexAuth, writeLiveCodexAuth, writeParkedCodexAuth } from "./codexauth.ts";
+import { codexIdentityOf, isCodexAccessExpiring, readLiveCodexAuth, writeLiveCodexAuth, writeParkedCodexAuth } from "./codexauth.ts";
 import { liveCodexAccountId } from "./codexsample.ts";
-import { targetableCodexAccounts } from "./codexpresence.ts";
+import { livingCodexPresences, presentCodexAccountIds, targetableCodexAccounts } from "./codexpresence.ts";
 import { effectiveBars } from "./picker.ts";
 import { log } from "./log.ts";
-import { CodexAccountSchema } from "./types.ts";
+import { CodexAccountSchema, CodexReconcileMarkerSchema, type CodexAccount } from "./types.ts";
 
 const CodexSwapDecisionSchema = z.object({
   swapped: z.boolean(),
@@ -33,26 +36,48 @@ const POST_SWAP_COOLDOWN_MS = 45_000;
 
 /**
  * Sample the LIVE credential's usage and stamp it onto its TRUE owner in the
- * pool (the usage read echoes the token's own account id: labels drift, the
- * token cannot lie). Refreshes the live blob first when it is near expiry,
- * persisting the rotation to both the live file and the owner's parked copy.
- * Returns the owner, or null when the live credential is absent or unpooled.
+ * pool (the id_token's own identity: labels drift, the token cannot lie).
+ * Refreshes the live blob first when it is near expiry (and no supervised
+ * session is running it - see the presence guard below), persisting the
+ * rotation to the live file AND the owner's parked copy in the same step -
+ * before the usage fetch, so a failed fetch can never strand the parked copy
+ * on the reuse-punished superseded refresh token. A dead live grant marks the
+ * owner needs-reauth and keeps the cached snapshot, so the decision below can
+ * still swap AWAY from it. Returns the owner id, or null when the live
+ * credential is absent or unpooled.
  */
 async function sampleLiveOntoOwner(input: { now: number }): Promise<string | null> {
   const { now } = input;
   let live = readLiveCodexAuth();
   if (!live) return null;
+  const index = loadCodexAccounts();
+  const identity = codexIdentityOf({ auth: live });
+  const owner = index.accounts.find((account) => account.accountId === identity.accountId);
+  if (!owner) return null;
 
-  if (isCodexAccessExpiring({ auth: live, now })) {
-    live = await refreshCodexAuth({ auth: live, now });
+  // The near-expiry refresh is skipped while any supervised session RUNS the
+  // live account: a sibling's Stop hook (or the timer) can land mid-turn of
+  // that session, and two concurrent POSTs of the same rotating refresh token
+  // reuse-punish the loser into a dead grant family (closing-review catch).
+  // The unrotated token stays valid within the margin, so the fetch below
+  // still samples; once expired it fails loudly and the next cycle, after the
+  // running session's own refresh, recovers.
+  if (isCodexAccessExpiring({ auth: live, now }) && !presentCodexAccountIds().has(identity.accountId)) {
+    try {
+      live = await refreshCodexAuth({ auth: live, now });
+    } catch (e) {
+      if (e instanceof CodexInvalidGrantError) {
+        owner.needsReauth = true;
+        saveCodexAccounts({ index });
+        log("codexdecide.live_invalid_grant", { account: owner.accountId.slice(0, 8) });
+        return owner.accountId;
+      }
+      throw e;
+    }
     writeLiveCodexAuth({ auth: live });
+    writeParkedCodexAuth({ credFile: owner.credFile, auth: live });
   }
   const usage = await fetchCodexUsage({ auth: live });
-
-  const index = loadCodexAccounts();
-  const owner = index.accounts.find((account) => account.accountId === usage.accountId);
-  if (!owner) return null;
-  writeParkedCodexAuth({ credFile: owner.credFile, auth: live });
   owner.lastUsage = { aggregate: usage.aggregate, perLimit: usage.perLimit };
   owner.lastUsageAt = now;
   if (usage.email != null) owner.email = usage.email;
@@ -61,13 +86,86 @@ async function sampleLiveOntoOwner(input: { now: number }): Promise<string | nul
   return owner.accountId;
 }
 
-export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promise<CodexSwapDecision> {
-  const now = input.now ?? Date.now();
-  const lastSwapAt = loadCodexLastSwapAt();
-  if (lastSwapAt != null && now - lastSwapAt < POST_SWAP_COOLDOWN_MS) {
-    return { swapped: false, account: null, reason: "post-swap-cooldown" };
+/**
+ * OWNER-APPROVED sibling reconcile (option b 2026-07-20, widened to ALL
+ * non-live siblings by the in-session owner ruling later that day): codex
+ * cannot hot-swap, so a pool swap respawns only the deciding session -
+ * siblings keep running whatever account they started on, cannot refresh it
+ * cross-account, and would wedge at token expiry. The deciding actor
+ * therefore SIGNALS every pooled non-live supervisor cross-session: a
+ * reconcile marker addressed by supervisorId (presence filenames carry it).
+ * The signal is a marker, never a kill: the only safe respawn point is the
+ * sibling's own turn boundary, so its Stop hook promotes the marker into a
+ * respawn marker there, adding the session id its stdin alone knows. No
+ * respawn-cost margin applies - the alternative to a respawn is a guaranteed
+ * eventual wedge - and no signal is ever sent while the LIVE seat is itself
+ * unusable (the no-depleted-pre-park analog: never move a session onto a
+ * blocked account). Orphaned markers (their supervisor exited before
+ * promoting) are garbage-collected here. Idempotent per supervisor: an
+ * existing marker is left alone.
+ *
+ * There is deliberately NO self-exclusion (bugbot/pullfrog/cubic review
+ * catches, PR #34): a session whose presence names a non-live account IS the
+ * stranded sibling even inside its own hook - its "normal decision" evaluates
+ * only the live seat and would never rescue it. A signal the sweep writes for
+ * the calling session is consumed by the promote pass its own hook runs right
+ * after the evaluation, same boundary. The deciding session that just swapped
+ * away leaves a self-addressed signal behind too; the promote staleness guard
+ * (presence rewritten at respawn) drops it as moot.
+ */
+function reconcileNonLiveSiblings(input: {
+  index: { accounts: CodexAccount[] };
+  liveAccountId: string;
+  bars: { session: number; weekly: number };
+  now: number;
+}): void {
+  const { index, liveAccountId, bars, now } = input;
+  const unusable = (account: CodexAccount): boolean =>
+    account.needsReauth === true || isCodexExhausted({ account, thresholds: bars, now });
+  const liveAccount = index.accounts.find((account) => account.accountId === liveAccountId);
+  if (!liveAccount || unusable(liveAccount)) return;
+  const living = livingCodexPresences();
+  // gc signals addressed to supervisors that no longer live (exited before
+  // promoting): nothing would ever consume them.
+  if (existsSync(codexPaths.reconcileDir)) {
+    const alive = new Set(living.map((presence) => presence.supervisorId));
+    for (const name of readdirSync(codexPaths.reconcileDir)) {
+      if (!alive.has(name)) rmSync(join(codexPaths.reconcileDir, name), { force: true });
+    }
+  }
+  for (const presence of living) {
+    if (presence.accountId === liveAccountId) continue; // riding the live seat: fine
+    const seated = index.accounts.find((account) => account.accountId === presence.accountId);
+    // OWNER RULING (2026-07-20, in-session, superseding the exhausted-only
+    // scope of option b): EVERY pooled non-live sibling is signaled, healthy
+    // included. Codex's guarded reload refuses a cross-account auth.json
+    // refresh, so a non-live session WILL wedge with "Please sign in again"
+    // at its access token's expiry (hours) - the safe-boundary respawn onto
+    // the live seat costs one visible restart, keeps the transcript
+    // (`codex resume <sid>`), and makes the whole pool follow the seat.
+    // Unpooled seats stay untouched: not ours to move.
+    if (!seated) continue;
+    const markerPath = join(codexPaths.reconcileDir, presence.supervisorId);
+    if (existsSync(markerPath)) continue;
+    mkdirSync(codexPaths.reconcileDir, { recursive: true });
+    writeFileAtomic(markerPath, JSON.stringify(CodexReconcileMarkerSchema.parse({ accountId: presence.accountId, ts: now })));
+    log("codexdecide.reconcile_signal", { supervisorId: presence.supervisorId.slice(0, 8), account: presence.accountId.slice(0, 8) });
+  }
+}
+
+/** The re-sweep after a PERSISTED swap: failures are logged, never thrown -
+ *  the caller must still report swapped:true so the Stop hook writes the
+ *  deciding session's own respawn marker. */
+function postSwapResweep(input: { liveAccountId: string; bars: { session: number; weekly: number }; now: number }): void {
+  try {
+    reconcileNonLiveSiblings({ index: loadCodexAccounts(), liveAccountId: input.liveAccountId, bars: input.bars, now: input.now });
+  } catch (e) {
+    log("codexdecide.resweep_failed", { err: e instanceof Error ? e.message : String(e) });
   }
+}
 
+export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promise<CodexSwapDecision> {
+  const now = input.now ?? Date.now();
   const cfg = loadConfig();
   const bars = effectiveBars(cfg);
 
@@ -86,6 +184,19 @@ export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promis
       return { swapped: false, account: null, reason: "live-credential-not-in-pool" };
     }
 
+    // Cross-session sibling reconcile runs on EVERY evaluation, BEFORE both
+    // the cooldown return and the engagement gate: a swap strands siblings at
+    // exactly the moment the cooldown starts (bugbot/cubic review catch,
+    // PR #34), and a sibling can be dead while the live seat is healthy and
+    // disengaged. Cached windows are enough here - the promote pass
+    // revalidates the destination's usability at consumption time.
+    reconcileNonLiveSiblings({ index, liveAccountId: activeId, bars, now });
+
+    const lastSwapAt = loadCodexLastSwapAt();
+    if (lastSwapAt != null && now - lastSwapAt < POST_SWAP_COOLDOWN_MS) {
+      return { swapped: false, account: null, reason: "post-swap-cooldown" };
+    }
+
     // Freshness: re-sample the live credential once its owner's cached
     // snapshot ages past the poll TTL (there is no push feed in between).
     const activeEntry = index.accounts.find((account) => account.accountId === activeId);
@@ -101,7 +212,11 @@ export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promis
     const active = index.accounts.find((account) => account.accountId === activeId) ?? null;
     if (!active) return { swapped: false, account: null, reason: "no-active-account" };
 
+    // A dead live grant always engages: the seat is unusable regardless of
+    // cached usage, and codexCurrentWins/pickBestCodex already exclude
+    // needs-reauth accounts, so both branches route onto a healthy target.
     const engaged =
+      active.needsReauth === true ||
       isCodexEngaged({ account: active, floor: cfg.policy.greedySessionFloor, now }) ||
       isCodexExhausted({ account: active, thresholds: bars, now });
     if (!engaged) return { swapped: false, account: null, reason: "under-threshold-or-stale" };
@@ -128,6 +243,17 @@ export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promis
           throw e;
         }
         log("codexdecide.greedy_swap", { account: best.accountId.slice(0, 8) });
+        // Re-sweep with the NEW live seat: siblings on the account this swap
+        // just departed were invisible to the entry sweep (their account WAS
+        // the live seat then), and the cooldown blocks the next evaluation's
+        // sweep-entry for 45s (pullfrog review catch, PR #34). GUARDED: the
+        // swap is already persisted, so a sweep failure (e.g. a corrupt
+        // presence file, which livingCodexPresences throws on by design) must
+        // not eat the swapped:true return - the Stop hook needs it to write
+        // THIS session's respawn marker (bugbot/cubic P0 catch, PR #34). The
+        // entry sweep stays fail-loud: there nothing irreversible has
+        // happened yet.
+        postSwapResweep({ liveAccountId: best.accountId, bars, now });
         return { swapped: true, account: best, reason: "swapped" };
       }
     }
@@ -151,6 +277,10 @@ export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promis
         throw e;
       }
       log("codexdecide.hard_swap", { account: best.accountId.slice(0, 8) });
+      // Same guarded post-swap re-sweep as the greedy branch: the departed
+      // account's siblings become signalable only once it stops being the
+      // live seat, and a sweep failure must not eat the swapped:true return.
+      postSwapResweep({ liveAccountId: best.accountId, bars, now });
       return { swapped: true, account: best, reason: "swapped" };
     }
   });

package/src/lib/codexpick.ts

@@ -11,9 +11,18 @@ import { nextWeeklyReset } from "./picker.ts";
 import { isSessionWindow, weeklyWindowOf } from "./codexusage.ts";
 import type { CodexAccount, CodexWindow, Thresholds } from "./types.ts";
 
-function liveUsed(input: { window: CodexWindow; now: number }): number {
-  const { window, now } = input;
-  return window.resetsAt != null && window.resetsAt <= now ? 0 : window.usedPercentage;
+/** A window whose reset has passed reads as empty. A NULL reset self-bounds
+ *  at sampledAt + the window's own duration (mirroring the claude picker's
+ *  blockedUntil, closing-review catch): the wire schema allows reset_at null,
+ *  and without the bound an over-bar null-reset window benched the account
+ *  FOREVER on a headless box where nothing re-samples parked accounts - the
+ *  no-permanent-bench invariant. No duration or sample time = trust the
+ *  reading (unmeasured recovery must not look safe). */
+function liveUsed(input: { window: CodexWindow; now: number; sampledAt: number | null }): number {
+  const { window, now, sampledAt } = input;
+  if (window.resetsAt != null) return window.resetsAt <= now ? 0 : window.usedPercentage;
+  if (sampledAt != null && window.windowSeconds != null && now >= sampledAt + window.windowSeconds * 1000) return 0;
+  return window.usedPercentage;
 }
 
 function allWindows(account: CodexAccount): CodexWindow[] {
@@ -29,8 +38,9 @@ function barFor(input: { window: CodexWindow; thresholds: Thresholds }): number
 /** A window at/over its bar whose reset has not passed blocks the account. */
 export function isCodexExhausted(input: { account: CodexAccount; thresholds: Thresholds; now: number }): boolean {
   const { account, thresholds, now } = input;
+  const sampledAt = account.lastUsageAt ?? null;
   return allWindows(account).some(
-    (window) => liveUsed({ window, now }) >= barFor({ window, thresholds }),
+    (window) => liveUsed({ window, now, sampledAt }) >= barFor({ window, thresholds }),
   );
 }
 
@@ -43,7 +53,7 @@ export function codexPacePressure(input: { account: CodexAccount; now: number })
   if (!weekly) return 0;
   const reset = nextWeeklyReset(weekly.resetsAt, now);
   if (reset == null) return 0;
-  return Math.max(0, 100 - liveUsed({ window: weekly, now })) / Math.max(1, reset - now);
+  return Math.max(0, 100 - liveUsed({ window: weekly, now, sampledAt: account.lastUsageAt ?? null })) / Math.max(1, reset - now);
 }
 
 function weeklyExpiryOf(input: { account: CodexAccount; now: number }): number {
@@ -102,5 +112,6 @@ export function codexCurrentWins(input: {
  *  rather than the session window alone. */
 export function isCodexEngaged(input: { account: CodexAccount; floor: number; now: number }): boolean {
   const { account, floor, now } = input;
-  return allWindows(account).some((window) => liveUsed({ window, now }) >= floor);
+  const sampledAt = account.lastUsageAt ?? null;
+  return allWindows(account).some((window) => liveUsed({ window, now, sampledAt }) >= floor);
 }

package/src/lib/codexpresence.ts

@@ -6,26 +6,39 @@
 // installing it as live would yank the running session's grant. Supervisors
 // therefore declare their session's account in a presence file at every
 // (re)spawn; the picker refuses to target present accounts and the sampler
-// refuses to refresh their parked blobs. Staleness is PID-based: a presence
-// whose supervisor died is ignored and cleaned up.
+// refuses to refresh their parked blobs. Staleness is checked by process
+// IDENTITY (pid + ps lstart), not bare pid-aliveness: after a supervisor
+// crash a recycled pid would otherwise keep its account benched forever.
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { codexPaths } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
+import { pidExists, pidStartTime } from "./proc.ts";
 
 const PresenceSchema = z.object({
   accountId: z.string(),
   pid: z.number(),
-  ts: z.number(),
+  startedAt: z.string(),
 });
 
-export function writeCodexPresence(input: { supervisorId: string; accountId: string }): void {
+/** `pid` should be the CODEX CHILD's pid when known (the supervisor passes
+ *  it): the session IS the child, and pinning the supervisor's own pid let a
+ *  SIGKILLed supervisor prune the presence while its orphaned codex kept
+ *  running and rotating the account's token - un-benching a live account for
+ *  samplers and the picker (closing-review catch). Defaults to process.pid
+ *  for callers that ARE the session-owning process (tests, future uses). */
+export function writeCodexPresence(input: { supervisorId: string; accountId: string; pid?: number }): void {
+  const pid = input.pid ?? process.pid;
+  const startedAt = pidStartTime(pid);
+  // The pid must be ps-visible; a null here means ps broke or the process
+  // already died - corrupt state to fail loudly on, never a masked placeholder.
+  if (startedAt == null) throw new Error(`could not read pid ${pid}'s start time (ps lstart) - refusing to write an unverifiable presence file`);
   mkdirSync(codexPaths.presenceDir, { recursive: true });
   writeFileAtomic(
     join(codexPaths.presenceDir, input.supervisorId),
-    JSON.stringify(PresenceSchema.parse({ accountId: input.accountId, pid: process.pid, ts: Date.now() })),
+    JSON.stringify(PresenceSchema.parse({ accountId: input.accountId, pid, startedAt })),
   );
 }
 
@@ -33,35 +46,60 @@ export function clearCodexPresence(input: { supervisorId: string }): void {
   rmSync(join(codexPaths.presenceDir, input.supervisorId), { force: true });
 }
 
-function pidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
+const LivingPresenceSchema = z.object({ supervisorId: z.string(), accountId: z.string() });
+export type LivingPresence = z.infer<typeof LivingPresenceSchema>;
 
-/** Account ids with a LIVING supervisor. Dead supervisors' files are removed. */
-export function presentCodexAccountIds(): Set<string> {
-  const present = new Set<string>();
-  if (!existsSync(codexPaths.presenceDir)) return present;
+/** Every LIVING supervised session (pid + start-time identity match), as
+ *  {supervisorId, accountId} pairs - the reconcile sweep needs to address a
+ *  specific supervisor, not just know which accounts are busy. Dead or
+ *  recycled-pid presences are removed. A file that exists but fails to parse
+ *  THROWS (review catch, PR #31): a presence file is what keeps a RUNNING
+ *  session's account from being swapped out from under it, so damaged state
+ *  must fail the decision loudly, never silently drop the protection. */
+export function livingCodexPresences(): LivingPresence[] {
+  const living: LivingPresence[] = [];
+  if (!existsSync(codexPaths.presenceDir)) return living;
   for (const name of readdirSync(codexPaths.presenceDir)) {
     const file = join(codexPaths.presenceDir, name);
+    let raw: string;
+    try {
+      raw = readFileSync(file, "utf8");
+    } catch (e) {
+      // a supervisor exiting between readdir and read clears its own file
+      const errno = z.object({ code: z.string() }).safeParse(e);
+      if (errno.success && errno.data.code === "ENOENT") continue;
+      throw e;
+    }
     const parsed = PresenceSchema.safeParse((() => {
       try {
-        return JSON.parse(readFileSync(file, "utf8"));
+        return JSON.parse(raw);
       } catch {
         return null;
       }
     })());
-    if (!parsed.success || !pidAlive(parsed.data.pid)) {
+    if (!parsed.success) {
+      throw new Error(`${file} is not a readable presence record - it may belong to a RUNNING codex session, refusing to treat it as absent; remove the file (or respawn that session) to proceed`);
+    }
+    const observed = pidStartTime(parsed.data.pid);
+    if (observed !== parsed.data.startedAt) {
+      // A null lstart is ambiguous: dead pid, or ps itself failing. Deleting
+      // on a ps failure would silently unbench a RUNNING session's account
+      // (review catch, PR #31), so only a confirmed-dead pid - or a live pid
+      // with a DIFFERENT start time, a recycle - may clear the file.
+      if (observed == null && pidExists(parsed.data.pid)) {
+        throw new Error(`ps could not read the start time of live pid ${parsed.data.pid} (${file}) - refusing to clear a presence file that may guard a RUNNING codex session`);
+      }
       rmSync(file, { force: true });
       continue;
     }
-    present.add(parsed.data.accountId);
+    living.push(LivingPresenceSchema.parse({ supervisorId: name, accountId: parsed.data.accountId }));
   }
-  return present;
+  return living;
+}
+
+/** Account ids with a LIVING supervisor - the picker/sampler exclusion view. */
+export function presentCodexAccountIds(): Set<string> {
+  return new Set(livingCodexPresences().map((presence) => presence.accountId));
 }
 
 /** The accounts a swap may target: running accounts are off limits, except the