@hienlh/ppm 0.19.12 → 0.20.0

package/src/services/account.service.ts

@@ -23,6 +23,12 @@ export interface Account {
   lastUsedAt: number | null;
   profileData: OAuthProfileData | null;
   createdAt: number;
+  /** When the current OAuth grant was issued. Null for rows that predate the column. */
+  grantedAt: number | null;
+  /** Refresh-token expiry as reported by the token endpoint, when it reports one. */
+  refreshExpiresAt: number | null;
+  /** The OAuth server rejected the refresh token; nothing but a fresh sign-in clears it. */
+  reauthRequired: boolean;
 }
 
 export interface AccountWithTokens extends Account {
@@ -69,6 +75,72 @@ const OAUTH_TOKEN_URL = "https://api.anthropic.com/v1/oauth/token";
 const OAUTH_SCOPE = "org:create_api_key user:profile user:inference";
 const OAUTH_PLATFORM_REDIRECT = "https://platform.claude.com/oauth/code/callback";
 
+/**
+ * Anthropic invalidates the entire refresh-token family this long after the original
+ * grant, whether or not the token kept rotating in between. Measured twice on a live
+ * install: developers@ signed in 2026-08-11 and was rejected 2026-09-08 (28d 2h);
+ * victor@ signed in 2026-08-18 and was rejected 2026-09-15 (27d 15h). Both died on the
+ * first use of a token minted hours earlier, so this is grant age, not token age.
+ *
+ * Only a fallback: if the token endpoint reports the refresh token's own expiry we use
+ * that instead, because a guessed constant silently rots if Anthropic changes it.
+ */
+const GRANT_LIFETIME_S = 28 * 86400;
+
+/**
+ * How close to expiry a token may be before use forces a refresh. Claude Code uses
+ * 5 minutes (`g0e = 300000` in its bundle) and refreshes at the point of use rather
+ * than on a timer; PPM now does the same.
+ *
+ * A buffer this small can hand a long turn a token that lapses mid-run. That is
+ * survivable here, and only here, because the 401 path in claude-agent-sdk.ts force-
+ * refreshes and retries the turn instead of failing it. Shrink that safety net and this
+ * number has to grow again.
+ */
+const PREFLIGHT_REFRESH_BUFFER_S = 300;
+
+/** Response fields we already understand; anything else is worth learning about. */
+const KNOWN_TOKEN_FIELDS = new Set([
+  "access_token", "refresh_token", "expires_in", "token_type", "scope", "account", "organization",
+  "refresh_token_expires_in", "refresh_expires_in", "refresh_token_expires_at", "refresh_expires_at",
+]);
+const loggedUnknownTokenFields = new Set<string>();
+
+/**
+ * Log response fields we do not consume, once per field name.
+ *
+ * The refresh-token expiry is the one number that would let PPM warn before a grant
+ * dies, and Claude Code stores it (`claudeAiOauth.refreshTokenExpiresAt`), but its own
+ * wire format is not public. Rather than hard-code a guess, read whichever field shows
+ * up and surface the rest so an unknown name is a log line instead of a silent miss.
+ */
+function noteUnknownTokenFields(data: Record<string, unknown>, context: string): void {
+  for (const key of Object.keys(data)) {
+    if (KNOWN_TOKEN_FIELDS.has(key) || loggedUnknownTokenFields.has(key)) continue;
+    loggedUnknownTokenFields.add(key);
+    const value = data[key];
+    const shown = typeof value === "string" && /token|secret|key/i.test(key)
+      ? `<redacted len=${value.length}>`
+      : JSON.stringify(value);
+    console.log(`[accounts] ${context} response carries unhandled field "${key}" = ${shown}`);
+  }
+}
+
+/** Pull the refresh token's own expiry out of a token response, in whatever shape it arrives. */
+function readRefreshExpiry(data: Record<string, unknown>): number | null {
+  const nowS = Math.floor(Date.now() / 1000);
+  for (const key of ["refresh_token_expires_in", "refresh_expires_in"]) {
+    const v = data[key];
+    if (typeof v === "number" && Number.isFinite(v) && v > 0) return nowS + Math.floor(v);
+  }
+  for (const key of ["refresh_token_expires_at", "refresh_expires_at"]) {
+    const v = data[key];
+    // Milliseconds if it is far past any plausible epoch-seconds value.
+    if (typeof v === "number" && Number.isFinite(v) && v > 0) return v > 1e11 ? Math.floor(v / 1000) : Math.floor(v);
+  }
+  return null;
+}
+
 // Survive Bun --hot reloads: persist timer ref across module re-evaluations
 const ACCT_HOT_KEY = "__PPM_ACCT_REFRESH__" as const;
 const acctHotState = ((globalThis as any)[ACCT_HOT_KEY] ??= {
@@ -97,9 +169,25 @@ class AccountService {
       lastUsedAt: row.last_used_at,
       profileData,
       createdAt: row.created_at,
+      grantedAt: row.granted_at,
+      refreshExpiresAt: row.refresh_expires_at,
+      reauthRequired: row.reauth_required === 1,
     };
   }
 
+  /**
+   * When this account's refresh token family is expected to die, or null if unknowable.
+   *
+   * Prefers whatever the server reported. Falls back to grant age, which is only
+   * available for accounts signed in since PPM started recording it — an older row
+   * reads as "unknown" rather than being given a fabricated date.
+   */
+  grantExpiresAt(acc: Account): number | null {
+    if (acc.refreshExpiresAt) return acc.refreshExpiresAt;
+    if (acc.grantedAt) return acc.grantedAt + GRANT_LIFETIME_S;
+    return null;
+  }
+
   private toAccountWithTokens(row: AccountRow): AccountWithTokens {
     return {
       ...this.toAccount(row),
@@ -144,18 +232,25 @@ class AccountService {
    * the two because its callers are background loops with nobody to tell; the one caller
    * that has a user in front of it (`PATCH /api/accounts/:id`) uses this.
    */
-  async ensureFreshTokenChecked(id: string): Promise<{ account: AccountWithTokens | null; rejected: boolean }> {
+  async ensureFreshTokenChecked(
+    id: string,
+    opts?: { retryRejected?: boolean },
+  ): Promise<{ account: AccountWithTokens | null; rejected: boolean }> {
     const acc = this.getWithTokens(id);
     if (!acc) return { account: null, rejected: false };
     // Only OAuth tokens need refresh
     if (!acc.accessToken.startsWith("sk-ant-oat")) return { account: acc, rejected: false };
     if (!acc.expiresAt) return { account: acc, rejected: false };
+    // A grant the server already rejected cannot come back on its own, and this method is
+    // on the usage poller's five-minute path. Callers acting on a deliberate user gesture
+    // (enable, test token) pass retryRejected so a false positive is always one click from
+    // being re-tested.
+    if (acc.reauthRequired && !opts?.retryRejected) return { account: null, rejected: true };
     const nowS = Math.floor(Date.now() / 1000);
-    const REFRESH_BUFFER_S = 3600; // 1 hour — refresh proactively before expiry
-    if (acc.expiresAt - nowS > REFRESH_BUFFER_S) return { account: acc, rejected: false }; // still fresh
+    if (acc.expiresAt - nowS > PREFLIGHT_REFRESH_BUFFER_S) return { account: acc, rejected: false }; // still fresh
     try {
-      console.log(`[accounts] Pre-flight refresh for ${acc.email ?? id} (expires in ${acc.expiresAt - nowS}s, buffer=${REFRESH_BUFFER_S}s)`);
-      await this.refreshAccessToken(id, false, false, REFRESH_BUFFER_S);
+      console.log(`[accounts] Pre-flight refresh for ${acc.email ?? id} (expires in ${acc.expiresAt - nowS}s, buffer=${PREFLIGHT_REFRESH_BUFFER_S}s)`);
+      await this.refreshAccessToken(id, false, false, PREFLIGHT_REFRESH_BUFFER_S);
       return { account: this.getWithTokens(id), rejected: false };
     } catch (e) {
       const msg = (e as Error).message ?? String(e);
@@ -186,13 +281,24 @@ class AccountService {
     accessToken: string;
     refreshToken: string;
     expiresAt: number;
+    refreshExpiresAt?: number | null;
     label?: string;
     profileData?: OAuthProfileData;
   }): Account {
+    const grantedAt = Math.floor(Date.now() / 1000);
     // Check for duplicate — update existing account tokens instead of creating new
     const dup = this.findDuplicate(params.email, params.profileData);
     if (dup) {
       this.updateTokens(dup.id, params.accessToken, params.refreshToken, params.expiresAt);
+      // Signing in again starts a brand new grant, so the 28-day clock restarts here.
+      // This is the branch that matters in practice: re-authenticating an account that
+      // already exists is how every expiry is recovered from, and it is exactly where
+      // created_at stays frozen at the row's original insert.
+      updateAccount(dup.id, {
+        granted_at: grantedAt,
+        refresh_expires_at: params.refreshExpiresAt ?? null,
+        reauth_required: 0,
+      });
       if (params.profileData) {
         updateAccount(dup.id, { profile_json: JSON.stringify(params.profileData) });
       }
@@ -217,6 +323,10 @@ class AccountService {
       total_requests: 0,
       last_used_at: null,
       profile_json: params.profileData ? JSON.stringify(params.profileData) : null,
+      granted_at: grantedAt,
+      refresh_expires_at: params.refreshExpiresAt ?? null,
+      reauth_required: 0,
+      last_refresh_attempt_at: null,
     });
     return this.toAccount(getAccountById(id)!);
   }
@@ -347,6 +457,11 @@ class AccountService {
       total_requests: 0,
       last_used_at: null,
       profile_json: info.profileData ? JSON.stringify(info.profileData) : null,
+      // An API key is not an OAuth grant: it has no family to expire and no sign-in to date.
+      granted_at: null,
+      refresh_expires_at: null,
+      reauth_required: 0,
+      last_refresh_attempt_at: null,
     });
     return this.toAccount(getAccountById(id)!);
   }
@@ -366,6 +481,10 @@ class AccountService {
       // The cooldown clears either way — a fresh token is what ends one, and leaving the
       // timestamp on a parked account would resurrect it the moment the park is lifted.
       cooldown_until: null,
+      // Holding live tokens is the only thing that clears a re-auth demand. Every door
+      // that lands here — sign-in, import, a successful refresh — has just proved the
+      // credential works, which is exactly the condition the flag was tracking.
+      reauth_required: 0,
       ...(parked ? {} : { status: "active" as const }),
     });
   }
@@ -515,6 +634,7 @@ class AccountService {
       accessToken: tokens.accessToken,
       refreshToken: tokens.refreshToken,
       expiresAt: tokens.expiresAt,
+      refreshExpiresAt: tokens.refreshExpiresAt,
       label,
       profileData,
     });
@@ -533,6 +653,7 @@ class AccountService {
       accessToken: tokens.accessToken,
       refreshToken: tokens.refreshToken,
       expiresAt: tokens.expiresAt,
+      refreshExpiresAt: tokens.refreshExpiresAt,
       profileData,
     });
   }
@@ -541,6 +662,7 @@ class AccountService {
     accessToken: string;
     refreshToken: string;
     expiresAt: number;
+    refreshExpiresAt: number | null;
     email: string;
   }> {
     const body: Record<string, string> = {
@@ -560,16 +682,18 @@ class AccountService {
       const text = await res.text();
       throw new Error(`OAuth token exchange failed: ${res.status} ${text}`);
     }
-    const data = await res.json() as {
+    const data = await res.json() as Record<string, unknown> & {
       access_token: string;
       refresh_token: string;
       expires_in: number;
       account?: { email_address?: string };
     };
+    noteUnknownTokenFields(data, "authorization_code");
     return {
       accessToken: data.access_token,
       refreshToken: data.refresh_token,
       expiresAt: Math.floor(Date.now() / 1000) + data.expires_in,
+      refreshExpiresAt: readRefreshExpiry(data),
       email: data.account?.email_address ?? "",
     };
   }
@@ -606,15 +730,18 @@ class AccountService {
 
   /**
    * POST the refresh grant, retrying transient failures with backoff.
-   * A network blip (e.g. waking from sleep) must not cost a whole refresh cycle: this
-   * runs at or past access-token expiry, so a dropped attempt leaves the account unable
-   * to serve a turn until the next sweep.
    *
-   * It is *not* that the refresh token is about to lapse with it. Measured against a
-   * live install's history: 324 refreshes, zero `invalid_grant`, and one that succeeded
-   * after a 58-hour gap — 50 hours past the 8-hour access-token expiry. Refresh tokens
-   * outlive their access tokens by days, which is what makes freezing a parked account
-   * (see `startAutoRefresh`) safe rather than a slow way to kill it.
+   * Retrying matters more now than it used to. This runs at the point of use, inside a
+   * five-minute window before the token is needed, so a network blip that burns the
+   * attempt costs the turn rather than merely deferring to the next sweep — there is no
+   * next sweep.
+   *
+   * An earlier version of this comment claimed refresh tokens outlive their access tokens
+   * by days, citing 324 refreshes with zero `invalid_grant`. That held only inside one
+   * grant's lifetime. Across grants it is wrong in the way that matters: the family is
+   * revoked on a fixed schedule from sign-in (GRANT_LIFETIME_S), and when it goes, the
+   * refresh token is rejected on its first use while the access token minted alongside it
+   * is still valid. No amount of retrying recovers that — only a new sign-in does.
    */
   private async postRefreshGrant(refreshToken: string, label: string): Promise<Response> {
     const backoffMs = [2_000, 6_000];
@@ -661,11 +788,13 @@ class AccountService {
       console.log(`[accounts] Token for ${account.email ?? accountId} is already fresh (expires in ${account.expiresAt - nowS}s, threshold=${freshThresholdS}s) — skipping OAuth refresh`);
       return;
     }
+    updateAccount(accountId, { last_refresh_attempt_at: nowS });
     const res = await this.postRefreshGrant(account.refreshToken, account.email ?? accountId);
     if (!res.ok) {
       const errorBody = await res.text().catch(() => "");
       console.error(`[accounts] Refresh failed for ${accountId}: ${res.status} ${errorBody}`);
-      if (errorBody.includes("invalid_grant") || errorBody.includes("invalid_request")) {
+      const rejected = errorBody.includes("invalid_grant") || errorBody.includes("invalid_request");
+      if (rejected) {
         // Another session/process may have refreshed (and rotated) the token between our read
         // and this OAuth call, making this failure stale. Detect that by comparing against the
         // expiry we read — testing "is it fresh" instead would swallow genuine rejections
@@ -680,24 +809,35 @@ class AccountService {
         // permanently with no recovery path (esp. for parked/disabled accounts). Preserve
         // it so re-enable / re-import / re-sync can restore access.
         console.warn(`[accounts] Refresh token rejected for ${account.email ?? accountId} — preserving token for recovery (not clearing)`);
+        // Anthropic ends the refresh-token family a fixed time after the grant, so a
+        // rejection here is terminal: every subsequent attempt returns the same 400.
+        // Recording it stops the retry loop that otherwise runs every few minutes for
+        // days — one live install logged 17,510 of them — and gives the UI something to
+        // show besides an account that still claims to be active.
+        updateAccount(accountId, { reauth_required: 1 });
       }
       if (disableOnFail) {
         this.setDisabled(accountId);
       }
       throw new Error(`Token refresh failed for account ${accountId}: ${res.status} ${errorBody}`);
     }
-    const data = await res.json() as {
+    const data = await res.json() as Record<string, unknown> & {
       access_token: string;
       refresh_token?: string;
       expires_in: number;
     };
-    console.log(`[accounts] Token refreshed for ${account.email ?? accountId} (expires_in=${data.expires_in}s, new_refresh=${!!data.refresh_token})`);
+    noteUnknownTokenFields(data, "refresh_token");
+    const refreshExpiresAt = readRefreshExpiry(data);
+    console.log(`[accounts] Token refreshed for ${account.email ?? accountId} (expires_in=${data.expires_in}s, new_refresh=${!!data.refresh_token}, refresh_expires_at=${refreshExpiresAt ?? "not reported"})`);
     this.updateTokens(
       accountId,
       data.access_token,
       data.refresh_token ?? account.refreshToken,
       Math.floor(Date.now() / 1000) + data.expires_in,
     );
+    // Only overwrite when the server said something. A rotation that reports nothing
+    // must not erase an expiry an earlier response did report.
+    if (refreshExpiresAt) updateAccount(accountId, { refresh_expires_at: refreshExpiresAt });
   }
 
   // ---------------------------------------------------------------------------
@@ -816,6 +956,12 @@ class AccountService {
         total_requests: row.total_requests ?? 0,
         last_used_at: row.last_used_at,
         profile_json: row.profile_json ?? null,
+        // A backup written before these columns existed has none of this; null means
+        // "unknown", which is what the import genuinely knows.
+        granted_at: row.granted_at ?? null,
+        refresh_expires_at: row.refresh_expires_at ?? null,
+        reauth_required: 0,
+        last_refresh_attempt_at: null,
       });
       imported++;
       if (hasRefresh && importedStatus !== "disabled") fullTransferIds.push(row.id);
@@ -846,43 +992,21 @@ class AccountService {
   // Auto-refresh background timer
   // ---------------------------------------------------------------------------
 
-  startAutoRefresh(): void {
+  startAccountMaintenance(): void {
     if (acctHotState.refreshTimer) return;
     const CHECK_INTERVAL_MS = 5 * 60_000;
-    // Refresh a full hour early: Anthropic's refresh token lapses soon after the access
-    // token expires, so waiting until the last minutes leaves no room to recover from a
-    // network outage. An hour of headroom gives ~12 retry ticks before the token is lost.
-    const REFRESH_BUFFER_S = 60 * 60;
 
-    const refreshExpiring = async () => {
-      const accounts = this.list();
-      const nowS = Math.floor(Date.now() / 1000);
-      for (const acc of accounts) {
-        // Skip disabled accounts: this timer exists to keep the chat rotation supplied and
-        // a parked account is not in it. Refreshing rotates the OAuth refresh token; when
-        // the same account is shared across machines the rotation races and one side gets
-        // invalid_grant, killing an account the user only meant to park.
-        //
-        // A preference, not a guarantee, and worth knowing before relying on it: the usage
-        // poller runs on the same 5-minute cadence with the same 1-hour buffer and does not
-        // skip parked accounts — deliberately, because a token nothing ever refreshes does
-        // eventually die. So while polling is on, a parked account's token still rotates
-        // here-or-there; this skip only declines to be the one that does it. Enabling the
-        // account proves the token either way (`PATCH /api/accounts/:id`).
-        if (acc.status === "disabled") continue;
-        if (!acc.expiresAt) continue;
-        if (acc.expiresAt - nowS > REFRESH_BUFFER_S) continue;
-        // Skip temporary accounts (no refresh token) — they can't be refreshed
-        const withTokens = this.getWithTokens(acc.id);
-        if (!withTokens?.refreshToken) continue;
-        console.log(`[accounts] Auto-refreshing token for ${acc.email ?? acc.id}`);
-        try {
-          await this.refreshAccessToken(acc.id, false, false, REFRESH_BUFFER_S);
-        } catch (e) {
-          console.error(`[accounts] Auto-refresh failed for ${acc.id}: ${(e as Error).message ?? e}`);
-        }
-      }
-    };
+    // There is deliberately no token-refresh sweep here any more.
+    //
+    // It used to refresh every account an hour before expiry, which rotated an idle
+    // account's token three or four times a day for nothing. That bought no safety: the
+    // refresh-token family dies on grant age (see GRANT_LIFETIME_S), not on idleness, so
+    // keeping a parked token warm never extended its life — it only widened the window in
+    // which two holders of the same credential could rotate over each other.
+    //
+    // Claude Code refreshes where the token is consumed and nowhere else, and PPM now
+    // matches: ensureFreshTokenChecked() on the turn path, the proxy, and the usage
+    // poller. What survives on this timer is the one job no request path covers.
 
     // Cleanup: auto-delete expired temporary accounts (no refresh token) after 7 days
     const TEMP_EXPIRY_DAYS = 7;
@@ -902,10 +1026,8 @@ class AccountService {
     };
 
     // Run immediately on startup, then every 5 minutes
-    refreshExpiring().catch(() => {});
     cleanupExpiredTemporary();
     acctHotState.refreshTimer = setInterval(() => {
-      refreshExpiring().catch(() => {});
       cleanupExpiredTemporary();
     }, CHECK_INTERVAL_MS);
 
@@ -914,7 +1036,7 @@ class AccountService {
     }
   }
 
-  stopAutoRefresh(): void {
+  stopAccountMaintenance(): void {
     if (acctHotState.refreshTimer) {
       clearInterval(acctHotState.refreshTimer);
       acctHotState.refreshTimer = null;

package/src/services/autostart-generator.ts

@@ -140,7 +140,18 @@ export function getServicePath(): string {
 export function generateSystemdService(config: AutoStartConfig): string {
   const cmd = buildExecCommand(config);
   const execStart = cmd.map(shellEscape).join(" ");
-  const bunDir = isCompiledBinary() ? "" : resolve(resolveBunPath(), "..");
+  // Bun is a runtime dependency even when PPM itself is a compiled binary: the extension
+  // installer spawns bare `bun add` / `bun remove` (extension-installer.ts), and a systemd
+  // user unit inherits a PATH that does not include ~/.bun/bin. Skipping this line whenever
+  // PPM was not started *by* bun left extension install/search failing with
+  // `Executable not found in $PATH: "bun"`. The launchd plist already carries a PATH through
+  // for the same reason.
+  let bunDir = "";
+  try {
+    bunDir = resolve(resolveBunPath(), "..");
+  } catch {
+    // No bun installed — there is no directory to add, and the feature that needs it says so.
+  }
 
   // Build PATH with bun directory prepended
   const envPath = bunDir

package/src/services/codex-account.service.ts

@@ -21,12 +21,16 @@ export type CodexStrategy = "round-robin" | "fill-first" | "lowest-usage";
 
 export type CodexAccountType = "apiKey" | "chatgpt";
 
+/** Two states only — nothing here parks an account in cooldown the way Claude's rotation does. */
+export type CodexAccountStatus = "active" | "disabled";
+
 export interface CodexAccount {
   id: string;
   label: string;
   type: CodexAccountType;
   home: string;
   planType?: string | null;
+  status: CodexAccountStatus;
   addedAt: string;
 }
 
@@ -38,10 +42,21 @@ export type CodexCreds =
 interface Row {
   id: string; label: string | null; type: string; home: string;
   plan_type: string | null; creds_enc: string | null; added_at: string;
+  status?: string | null;
 }
 
 function rowToAccount(r: Row): CodexAccount {
-  return { id: r.id, label: r.label ?? r.id.slice(0, 8), type: r.type as CodexAccountType, home: r.home, planType: r.plan_type, addedAt: r.added_at };
+  return {
+    id: r.id,
+    label: r.label ?? r.id.slice(0, 8),
+    type: r.type as CodexAccountType,
+    home: r.home,
+    planType: r.plan_type,
+    // A row written before the column existed reads as null; treat that as enabled, which
+    // is what it effectively was.
+    status: r.status === "disabled" ? "disabled" : "active",
+    addedAt: r.added_at,
+  };
 }
 
 /** CODEX_HOME directory for an account id. */
@@ -102,6 +117,24 @@ export function updateCodexAccountMeta(id: string, meta: { label?: string; planT
   getDb().query(`UPDATE codex_accounts SET ${sets.join(", ")} WHERE id = ?`).run(...vals as any[]);
 }
 
+/**
+ * Switch an account on or off.
+ *
+ * Deliberately no token proof on the way in, unlike the Claude path: that check exists
+ * because an Anthropic OAuth account can hold a refresh token the server has to exercise
+ * before trusting. A Codex account is a CODEX_HOME directory the app-server authenticates
+ * against when it spawns, so there is nothing here to prove in advance — copying that check
+ * across would buy a slow button and no safety.
+ *
+ * Disabling never touches credentials. Off and removed are different things, and the account
+ * has to come back exactly as it was.
+ */
+export function setCodexAccountStatus(id: string, status: CodexAccountStatus): CodexAccount | null {
+  if (!getCodexAccount(id)) return null;
+  getDb().query("UPDATE codex_accounts SET status = ? WHERE id = ?").run(status, id);
+  return getCodexAccount(id);
+}
+
 /** Remove the account row and its CODEX_HOME dir. */
 export function removeCodexAccount(id: string): void {
   const acct = getCodexAccount(id);
@@ -126,16 +159,48 @@ export function setCodexStrategy(strategy: CodexStrategy): void {
   configService.save();
 }
 
+/** Five-hour utilisation at or above which an account is skipped while others have room. */
+const FIVE_HOUR_SKIP_THRESHOLD = 0.95;
+
+/**
+ * Drop accounts with no five-hour room left, unless that would leave nothing.
+ *
+ * Soft on purpose, mirroring the Claude selector: a throttled turn beats no turn, so when
+ * every account is at its cap the caller still gets one back. `usageOf` is supplied by the
+ * caller rather than fetched here — usage lives behind an async provider layer, and pulling
+ * it inside a synchronous pick would put a network round-trip on every account selection.
+ * With no `usageOf` there is nothing to judge and every account stays a candidate.
+ */
+function withFiveHourRoom(
+  accts: CodexAccount[],
+  usageOf?: (id: string) => number,
+): CodexAccount[] {
+  if (!usageOf) return accts;
+  const room = accts.filter((a) => {
+    const util = usageOf(a.id);
+    return !Number.isFinite(util) ? true : util < FIVE_HOUR_SKIP_THRESHOLD;
+  });
+  return room.length > 0 ? room : accts;
+}
+
 /**
  * Pick an account by strategy. `usageOf` (optional, from P4) enables lowest-usage;
  * without it lowest-usage falls back to round-robin.
+ *
+ * `usageOf` also drives the five-hour skip, so a caller that supplies it gets an account
+ * with room rather than merely the least-used one among several that are all capped.
  */
 export function selectCodexAccount(opts?: { strategy?: CodexStrategy; usageOf?: (id: string) => number }): CodexAccount | null {
-  const accts = listCodexAccounts();
-  if (accts.length === 0) return null;
-  if (accts.length === 1) return accts[0]!;
+  // Disabled is a hard exclusion with no fallback, unlike the five-hour skip below. Being
+  // capped means a slower turn; being switched off is the user saying don't use this, and
+  // handing it back anyway because nothing else was left would ignore them.
+  const all = listCodexAccounts().filter((a) => a.status !== "disabled");
+  if (all.length === 0) return null;
+  if (all.length === 1) return all[0]!;
   const strategy = opts?.strategy ?? getCodexStrategy();
   const usageOf = opts?.usageOf;
+  const accts = withFiveHourRoom(all, usageOf);
+  if (accts.length === 1) return accts[0]!;
   if (strategy === "fill-first") return accts[0]!;
   if (strategy === "lowest-usage" && usageOf) {
     return accts.reduce((best, a) => (usageOf(a.id) < usageOf(best.id) ? a : best), accts[0]!);
@@ -160,7 +225,9 @@ export function selectCodexAccount(opts?: { strategy?: CodexStrategy; usageOf?:
  * null rather than guessing at one.
  */
 export function peekCodexAccount(): CodexAccount | null {
-  const accts = listCodexAccounts();
+  // Status is the one thing this can filter on without going async, so it does. Usage lives
+  // behind a fetch and stays out of reach here; the consuming pick endpoint reads it instead.
+  const accts = listCodexAccounts().filter((a) => a.status !== "disabled");
   if (accts.length === 0) return null;
   if (accts.length === 1) return accts[0]!;
   return getCodexStrategy() === "fill-first" ? accts[0]! : null;
@@ -171,14 +238,21 @@ export async function resolveCodexAccountForSession(sessionId?: string): Promise
   // Session-less callers (the model list) have nothing sticky to honour and fall
   // straight through to the configured strategy.
   const sticky = sessionId ? getSessionCodexAccount(sessionId) : null;
-  if (sticky) { const a = getCodexAccount(sticky); if (a) return a; }
-  if (getCodexStrategy() === "lowest-usage" && listCodexAccounts().length > 1) {
-    const usages = await getAllCodexUsages();
-    // A failed usage fetch (broken/expired account) yields {} → treat as +Infinity
-    // so lowest-usage de-prioritizes it instead of preferring it as "0% used".
-    return selectCodexAccount({ strategy: "lowest-usage", usageOf: (id) => usages[id]?.fiveHour ?? Number.POSITIVE_INFINITY });
-  }
-  return selectCodexAccount();
+  // A binding is held for the prompt cache, not honoured unconditionally: an account the
+  // user has switched off has to let go of the sessions sitting on it, or turning it off
+  // would do nothing for exactly the conversations already using it.
+  if (sticky) { const a = getCodexAccount(sticky); if (a && a.status !== "disabled") return a; }
+  if (listCodexAccounts().filter((a) => a.status !== "disabled").length <= 1) return selectCodexAccount();
+  // Usage is read for every strategy, not just lowest-usage: it is also what lets the
+  // selector skip an account with no five-hour room left. Reading it only for lowest-usage
+  // left that skip inert under round-robin, which is the default — sessions kept landing on
+  // accounts that were already capped. The read is served from the shared usage cache, so
+  // this costs a lookup rather than a request per session start.
+  //
+  // A failed usage fetch (broken/expired account) yields {} → treat as +Infinity so
+  // lowest-usage de-prioritizes it instead of preferring it as "0% used".
+  const usages = await getAllCodexUsages();
+  return selectCodexAccount({ usageOf: (id) => usages[id]?.fiveHour ?? Number.POSITIVE_INFINITY });
 }
 
 // ── Usage (per account) ──