@hienlh/ppm 0.17.45 → 0.17.47

package/src/server/routes/chat.ts

@@ -8,13 +8,14 @@ import { providerRegistry } from "../../providers/registry.ts";
 import { renameSession as sdkRenameSession } from "@anthropic-ai/claude-agent-sdk";
 import { listSlashItems, searchSlashItems, invalidateCache } from "../../services/slash-items.service.ts";
 import { ensureSdkCommands, invalidateSdkCommands } from "../../services/slash-discovery/sdk-commands.ts";
-import { upsertSlashRecent, getSlashRecents, setSessionClearedFrom, listTurnUsage } from "../../services/db.service.ts";
+import { upsertSlashRecent, getSlashRecents, setSessionClearedFrom, listTurnUsage, getSessionAccount } from "../../services/db.service.ts";
 import type { TurnUsage } from "../../shared/turn-usage.ts";
 import { getCachedUsage, refreshUsageNow } from "../../services/claude-usage.service.ts";
 import { getSessionLog } from "../../services/session-log.service.ts";
 import { parseJsonlTranscript, validateJsonlPath } from "../../services/jsonl-transcript-parser.ts";
 import { aggregateTasks } from "../../services/task-status-aggregator.ts";
-import { auditTranscriptImages, stripTranscriptImages, MANY_IMAGE_DIMENSION_LIMIT, type StripMode } from "../../services/transcript-images.ts";
+import { MANY_IMAGE_DIMENSION_LIMIT, type StripMode } from "../../services/transcript-images.ts";
+import { auditTranscriptImagesFile, stripTranscriptImagesFile } from "../../services/transcript-images-file.ts";
 import { getSessionProjectPath, setSessionMetadata, setSessionTitle, getSessionTitle, getPinnedSessionIds, pinSession, unpinSession, deleteSessionMapping, deleteSessionMetadata, deleteSessionTitle, getAllUnread, clearSessionUnread, setSessionUnread } from "../../services/db.service.ts";
 import { setSessionTag, bulkSetSessionTag, getTagById, getSessionTags, getProjectDefaultTagId } from "../../services/tag.service.ts";
 import { recordBranch, resolveVersionGroup, resolveVersionMap, collapseTreesToHeads, hasChildren, deleteBranchesFor, getRootId } from "../../services/session-branch.service.ts";
@@ -85,7 +86,11 @@ chatRoutes.get("/usage", async (c) => {
   if (c.req.query("refresh")) {
     try { await refreshUsageNow(); } catch { /* use stale cache */ }
   }
-  const usage = getCachedUsage();
+  // Accounts are bound per session, so the header must report the account serving THIS
+  // session rather than whichever one ran most recently across all of them.
+  const sessionId = c.req.query("session");
+  const boundAccountId = sessionId ? getSessionAccount(sessionId) : null;
+  const usage = getCachedUsage(boundAccountId ?? undefined);
   return c.json(ok({
     lastFetchedAt: usage.lastFetchedAt,
     fiveHour: usage.session?.utilization,
@@ -737,6 +742,8 @@ chatRoutes.get("/sessions/:id/usage", (c) => {
         cacheHitRate: cacheHitRateOf(r),
         coldStart: r.cold_start === 1,
         ...(r.cold_reason && { coldReason: r.cold_reason }),
+        ...(r.account_id && { accountId: r.account_id }),
+        ...(r.account_label && { accountLabel: r.account_label }),
       } satisfies TurnUsage,
     })),
   }));
@@ -748,31 +755,30 @@ function cacheHitRateOf(r: { input_tokens: number; cache_read_tokens: number; ca
   return prefix > 0 ? r.cache_read_tokens / prefix : 0;
 }
 
-/** Largest transcript the image routes will read into memory in one go. */
-const MAX_TRANSCRIPT_SCAN_BYTES = 64 * 1024 * 1024;
-
 /**
- * Locate a session transcript and read it, or explain why that was not possible.
+ * Locate a session transcript, or explain why that was not possible.
  *
  * The id becomes a filename, and the strip route writes to what this returns, so anything
  * that is not a plain session id is refused before it can reach into another directory.
+ *
+ * No size limit: both routes stream the file a record at a time, so a transcript costs one
+ * line of memory rather than its whole length. The cap that used to live here turned the
+ * cleanup off for exactly the transcripts big enough to need it.
  */
-function readTranscript(sessionId: string): { path: string; text: string } | { error: string; status: 400 | 404 | 413 } {
+function locateTranscript(sessionId: string): { path: string } | { error: string; status: 400 | 404 } {
   if (!/^[A-Za-z0-9_-]{8,64}$/.test(sessionId)) return { error: "Invalid session id", status: 400 };
   const { jsonlPath, exists } = resolveSessionJsonlPath(sessionId);
   if (!exists || !jsonlPath) return { error: "Transcript not found for this session", status: 404 };
-  if (statSync(jsonlPath).size > MAX_TRANSCRIPT_SCAN_BYTES) {
-    return { error: "Transcript too large to scan", status: 413 };
-  }
-  return { path: jsonlPath, text: readFileSync(jsonlPath, "utf8") };
+  return { path: jsonlPath };
 }
 
 /** GET /chat/sessions/:id/images — count the image payloads the transcript replays every turn */
-chatRoutes.get("/sessions/:id/images", (c) => {
+chatRoutes.get("/sessions/:id/images", async (c) => {
   try {
-    const read = readTranscript(c.req.param("id"));
-    if ("error" in read) return c.json(err(read.error), read.status);
-    return c.json(ok({ ...auditTranscriptImages(read.text), limit: MANY_IMAGE_DIMENSION_LIMIT }));
+    const found = locateTranscript(c.req.param("id"));
+    if ("error" in found) return c.json(err(found.error), found.status);
+    const audit = await auditTranscriptImagesFile(found.path);
+    return c.json(ok({ ...audit, limit: MANY_IMAGE_DIMENSION_LIMIT }));
   } catch (e) {
     return c.json(err((e as Error).message), 500);
   }
@@ -781,31 +787,34 @@ chatRoutes.get("/sessions/:id/images", (c) => {
 /**
  * POST /chat/sessions/:id/images/strip — replace image payloads with their placeholder text.
  *
- * Rewrites the transcript in place rather than swapping in a new file: the CLI holds the
- * original open in append mode, so a rename would leave it writing to an orphaned inode.
  * A turn in flight is refused outright, since the record it is midway through appending
  * would be lost by the rewrite.
+ *
+ * `includeAttachments` also clears images the user attached to their own messages. It is
+ * opt-in because the transcript usually holds the only copy, but it has to be reachable: one
+ * oversized attachment makes every later turn of the session fail, and nothing else can
+ * remove it.
  */
 chatRoutes.post("/sessions/:id/images/strip", async (c) => {
   try {
     const sessionId = c.req.param("id");
     const body = await c.req.json().catch(() => ({}));
     const mode: StripMode = (body as { mode?: unknown }).mode === "all" ? "all" : "oversized";
+    const includeAttachments = (body as { includeAttachments?: unknown }).includeAttachments === true;
 
     const { listRunningSessions } = await import("../ws/chat.ts");
     if (listRunningSessions().some((s) => s.sessionId === sessionId)) {
       return c.json(err("Session is running — wait for the turn to finish"), 409);
     }
 
-    const read = readTranscript(sessionId);
-    if ("error" in read) return c.json(err(read.error), read.status);
+    const found = locateTranscript(sessionId);
+    if ("error" in found) return c.json(err(found.error), found.status);
 
-    const result = stripTranscriptImages(read.text, mode);
-    if (result.removed > 0) writeFileSync(read.path, result.text);
+    const result = await stripTranscriptImagesFile(found.path, mode, { includeAttachments });
     return c.json(ok({
       removed: result.removed,
       bytesFreed: result.bytesFreed,
-      remaining: { ...auditTranscriptImages(result.text), limit: MANY_IMAGE_DIMENSION_LIMIT },
+      remaining: { ...result.remaining, limit: MANY_IMAGE_DIMENSION_LIMIT },
     }));
   } catch (e) {
     return c.json(err((e as Error).message), 500);

package/src/server/routes/upgrade.ts

@@ -7,25 +7,41 @@ import {
   compareSemver,
   applyUpgrade,
   signalSupervisorUpgrade,
+  getLatestPublishedVersion,
 } from "../../services/upgrade.service.ts";
 import { ok, err } from "../../types/api.ts";
 import { getPpmDir } from "../../services/ppm-dir.ts";
 
 export const upgradeRoutes = new Hono();
 
-/** GET / — upgrade status (current version, available version, install method) */
-upgradeRoutes.get("/", (c) => {
-  let availableVersion: string | null = null;
+/** Last version the supervisor's periodic check recorded, if any. */
+function readRecordedVersion(): string | null {
   try {
-    if (existsSync(resolve(getPpmDir(), "status.json"))) {
-      const data = JSON.parse(readFileSync(resolve(getPpmDir(), "status.json"), "utf-8"));
-      const candidate = data.availableVersion ?? null;
-      // Only report if actually newer than current version
-      if (candidate && compareSemver(VERSION, candidate) < 0) {
-        availableVersion = candidate;
-      }
-    }
-  } catch {}
+    const path = resolve(getPpmDir(), "status.json");
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf-8")).availableVersion ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check the registry directly rather than only reading what the supervisor
+ * recorded: that record is written 5min after startup and every 15min after,
+ * so a UI opened inside that window would see no update and offer no upgrade.
+ * The supervisor's record is the offline fallback.
+ */
+export async function resolveAvailableVersion(
+  getLatest: () => Promise<string | null> = getLatestPublishedVersion,
+): Promise<string | null> {
+  const candidate = (await getLatest()) ?? readRecordedVersion();
+  // Only report if actually newer than current version
+  return candidate && compareSemver(VERSION, candidate) < 0 ? candidate : null;
+}
+
+/** GET / — upgrade status (current version, available version, install method) */
+upgradeRoutes.get("/", async (c) => {
+  const availableVersion = await resolveAvailableVersion();
 
   return c.json(ok({
     currentVersion: VERSION,

package/src/server/ws/chat.ts

@@ -14,6 +14,7 @@ import { backgroundShellRegistry } from "../../services/background-shell-registr
 import { basename } from "node:path";
 import { configService } from "../../services/config.service.ts";
 import { formatTurnUsageLog } from "../../shared/turn-usage.ts";
+import { cacheReleaseDelayMs, selectWarmIdleEvictions } from "../../services/subprocess-retention.ts";
 
 /** Resolve the SESSION's provider config — not the global default provider's.
  * Otherwise a non-default provider's chat (e.g. codex) would inherit claude's values. */
@@ -46,6 +47,8 @@ function resolveSessionThinkingEnabled(sessionId: string): boolean {
 
 const PING_INTERVAL_MS = 15_000; // 15s keepalive
 const CLEANUP_TIMEOUT_MS = 5 * 60_000; // 5min after Claude done + no FE
+/** How many clientless sessions may hold a live SDK subprocess at once. */
+const MAX_WARM_IDLE_SESSIONS = 5;
 const MAX_TURN_EVENTS = 10_000; // memory safety cap
 const BUFFERABLE_TYPES = new Set([
   "text", "thinking", "tool_use", "tool_result",
@@ -87,6 +90,76 @@ interface SessionEntry {
   compactStatus?: "compacting" | null;
   /** toolUseIds of Bash calls launched with run_in_background — spy is kept alive for these */
   backgroundToolUseIds?: Set<string>;
+  /** When the last client left, for evicting the least recently used warm subprocess */
+  idleSince?: number;
+  /** When the last turn completed — the moment this session's prompt cache was last written */
+  lastTurnEndedAt?: number;
+  /** Pending release of the subprocess once its prompt cache lapses */
+  cacheReleaseTimer?: ReturnType<typeof setTimeout>;
+}
+
+/** Sessions with no client attached, not mid-turn, still holding a live subprocess. */
+function listWarmIdleSessions(): { sessionId: string; entry: SessionEntry; idleSince?: number }[] {
+  const out: { sessionId: string; entry: SessionEntry; idleSince?: number }[] = [];
+  for (const [sessionId, entry] of activeSessions) {
+    if (entry.clients.size > 0 || entry.isStreamingActive) continue;
+    const provider = providerRegistry.get(entry.providerId);
+    if (!provider?.hasStreamingSession?.(sessionId)) continue;
+    out.push({ sessionId, entry, idleSince: entry.idleSince });
+  }
+  return out;
+}
+
+/** Release a session's subprocess, if it still has one and nobody is using it. */
+function releaseSubprocess(sessionId: string, reason: string, note: string): void {
+  const entry = activeSessions.get(sessionId);
+  if (!entry || entry.clients.size > 0 || entry.isStreamingActive) return;
+  const provider = providerRegistry.get(entry.providerId);
+  if (!provider?.hasStreamingSession?.(sessionId)) return;
+  provider.abortQuery?.(sessionId, reason);
+  console.log(`[chat] session=${sessionId} released subprocess (${reason})`);
+  logSessionEvent(sessionId, "INFO", note);
+}
+
+/** Tear down the longest-idle subprocesses once too many sessions are holding one. */
+function enforceWarmIdleCap(): void {
+  const warmIdle = listWarmIdleSessions();
+  for (const sessionId of selectWarmIdleEvictions(warmIdle, MAX_WARM_IDLE_SESSIONS)) {
+    releaseSubprocess(
+      sessionId,
+      "warm_idle_cap",
+      `Subprocess released early: more than ${MAX_WARM_IDLE_SESSIONS} idle sessions were holding one`,
+    );
+  }
+}
+
+/**
+ * Schedule the subprocess release for when this session's prompt cache lapses.
+ *
+ * Timed from the last completed turn rather than from the disconnect: the cache clock started
+ * when the turn was sent, so a session whose last turn is already older than the TTL has
+ * nothing left to protect and its subprocess goes at once.
+ */
+function scheduleSubprocessRelease(sessionId: string): void {
+  const entry = activeSessions.get(sessionId);
+  if (!entry) return;
+  if (entry.cacheReleaseTimer) clearTimeout(entry.cacheReleaseTimer);
+  entry.cacheReleaseTimer = undefined;
+
+  const provider = providerRegistry.get(entry.providerId);
+  if (!provider?.hasStreamingSession?.(sessionId)) return;
+
+  const note = "Subprocess released: its prompt cache has expired, so keeping it warm saves nothing";
+  const delay = cacheReleaseDelayMs(entry.lastTurnEndedAt, Date.now());
+  if (delay === 0) {
+    releaseSubprocess(sessionId, "cache_expired", note);
+    return;
+  }
+  entry.cacheReleaseTimer = setTimeout(() => {
+    const e = activeSessions.get(sessionId);
+    if (e) e.cacheReleaseTimer = undefined;
+    releaseSubprocess(sessionId, "cache_expired", note);
+  }, delay);
 }
 
 /** Push the current background-shell registry snapshot to a session's clients. */
@@ -252,6 +325,17 @@ function startCleanupTimer(sessionId: string): void {
     if (entry.isStreamingActive) return;
     console.log(`[chat] session=${sessionId} cleanup: idle with no FE for ${CLEANUP_TIMEOUT_MS / 1000}s`);
     logSessionEvent(sessionId, "INFO", "Session cleaned up (idle, no FE reconnected)");
+    // Backstop for the subprocess: scheduleSubprocessRelease normally gets there first,
+    // timed off the last turn rather than off this disconnect. It bails when a turn was in
+    // flight, so the session entry going away is the last chance to free the process.
+    const provider = providerRegistry.get(entry.providerId);
+    if (provider?.hasStreamingSession?.(sessionId)) {
+      provider.abortQuery?.(sessionId, "idle_timeout");
+    }
+    if (entry.cacheReleaseTimer) {
+      clearTimeout(entry.cacheReleaseTimer);
+      entry.cacheReleaseTimer = undefined;
+    }
     for (const interval of entry.pingIntervals.values()) clearInterval(interval);
     entry.pingIntervals.clear();
     for (const w of entry.teamWatchers.values()) w.cleanup();
@@ -493,6 +577,12 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
         // Turn complete — transition to idle, clear buffer for next turn
         logSessionEvent(sessionId, "DONE", `subtype=${ev.resultSubtype ?? "none"} turns=${ev.numTurns ?? "?"} ctx=${ev.contextWindowPct ?? "?"}%${ev.usage ? ` ${formatTurnUsageLog(ev.usage)}` : ""}`);
         if (ev.contextWindowPct != null) lastContextWindowPct = ev.contextWindowPct;
+        // The prompt cache was just written, which is what the retention window is measured
+        // from. A turn can complete with nobody watching (remote trigger, scheduler), and the
+        // release pending from the disconnect was timed against the previous turn — re-time it
+        // or it fires while the cache it was protecting is still fresh.
+        entry.lastTurnEndedAt = Date.now();
+        if (entry.clients.size === 0) scheduleSubprocessRelease(sessionId);
 
         // Fire-and-forget: fetch updated session title (DB title takes priority) + notification
         sdkListSessions({ dir: entry.projectPath, limit: 50 }).then((sessions) => {
@@ -658,6 +748,13 @@ export const chatWebSocket = {
         clearTimeout(existing.cleanupTimer);
         existing.cleanupTimer = undefined;
       }
+      // No longer idle: not a candidate for warm-idle eviction, and its subprocess is in
+      // use again so the pending cache-expiry release must not fire under it.
+      existing.idleSince = undefined;
+      if (existing.cacheReleaseTimer) {
+        clearTimeout(existing.cacheReleaseTimer);
+        existing.cacheReleaseTimer = undefined;
+      }
       if (projectPath) existing.projectPath = projectPath;
       if (projectName) existing.projectName = projectName;
 
@@ -1092,18 +1189,18 @@ export const chatWebSocket = {
     console.log(`[chat] session=${sessionId} FE disconnected (phase=${entry.phase}, clients=${entry.clients.size})`);
 
     if (entry.clients.size === 0) {
-      // No clients listening anymore. If Claude is idle (turn finished, no pending
-      // approval), tear down the persistent streaming query so the next message
-      // recreates it via the resume path — picking up fresh MCP/config while
-      // preserving context from JSONL, and freeing the idle subprocess (RAM).
-      const provider = providerRegistry.get(entry.providerId);
-      const idle = entry.phase === "idle" && !entry.isStreamingActive && !entry.pendingApprovalEvent;
-      const hasLiveStream = provider?.hasStreamingSession?.(sessionId) ?? false;
-      if (idle && hasLiveStream) {
-        provider?.abortQuery?.(sessionId, "tab_closed");
-        logSessionEvent(sessionId, "INFO", "Streaming query torn down (all clients gone, idle) — next message resumes with fresh config");
-      }
+      // No clients listening anymore. The streaming query is NOT torn down here: a
+      // disconnect is usually a refresh, a phone switching apps or a laptop sleeping,
+      // and the client is back within seconds. Killing the subprocess on the spot forces
+      // the next message down the resume path, which replays the whole transcript and
+      // re-picks an account — on a large session that turns a cache read into a full
+      // cache write. The cleanup timer does the teardown once the session is genuinely
+      // abandoned (see startCleanupTimer), and enforceWarmIdleCap bounds how many
+      // subprocesses may wait out that timer at once.
+      entry.idleSince = Date.now();
       startCleanupTimer(sessionId);
+      scheduleSubprocessRelease(sessionId);
+      enforceWarmIdleCap();
     }
   },
 };

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

@@ -1,5 +1,11 @@
 import { accountService, type AccountWithTokens } from "./account.service.ts";
-import { getConfigValue, setConfigValue, getLatestSnapshotForAccount } from "./db.service.ts";
+import {
+  getConfigValue,
+  setConfigValue,
+  getLatestSnapshotForAccount,
+  getSessionAccount,
+  setSessionAccount,
+} from "./db.service.ts";
 
 export type AccountStrategy = "round-robin" | "fill-first" | "lowest-usage";
 
@@ -12,6 +18,8 @@ const BACKOFF_MAX_MS = 30 * 60_000;
 const AUTH_BACKOFF_BASE_MS = 5 * 60_000; // 5min base for auth errors (longer than rate limits)
 /** Skip accounts whose 5-hour utilization >= this threshold (proactive avoidance) */
 const FIVE_HOUR_SKIP_THRESHOLD = 0.95;
+/** Weekly utilization at which an account has nothing left to give until its reset. */
+const WEEKLY_EXHAUSTED_UTIL = 1.0;
 
 class AccountSelectorService {
   private cursor = 0;
@@ -63,17 +71,10 @@ class AccountSelectorService {
     return this._lastFailReason;
   }
 
-  /**
-   * Pick next available account (skips cooldown/disabled).
-   * Returns null if no active accounts available.
-   */
-  next(excludeIds?: Set<string>): AccountWithTokens | null {
-    this._lastFailReason = "none";
+  /** Re-enable accounts whose cooldown has elapsed, so they rejoin the candidate pool. */
+  private clearExpiredCooldowns(): void {
     const now = Math.floor(Date.now() / 1000);
-    const allAccounts = accountService.list();
-
-    // Clear expired cooldowns
-    for (const acc of allAccounts) {
+    for (const acc of accountService.list()) {
       if (acc.status === "cooldown" && acc.cooldownUntil && acc.cooldownUntil <= now) {
         try {
           accountService.setEnabled(acc.id);
@@ -85,6 +86,92 @@ class AccountSelectorService {
         }
       }
     }
+  }
+
+  /** Status test from next()'s candidate filter — disabled and parked accounts are out. */
+  private isSelectable(accountId: string): boolean {
+    const acc = accountService.list().find((a) => a.id === accountId);
+    if (!acc) return false;
+    const cooldownOn = this.isCooldownEnabled();
+    return acc.status === "active" || (!cooldownOn && acc.status === "cooldown");
+  }
+
+  /**
+   * Whether an account has quota left to serve a turn.
+   *
+   * Mirrors next()'s proactive 5-hour skip, and adds the weekly exhaustion that otherwise
+   * only the lowest-usage strategy scores. A binding has to respect both: on five-hour
+   * alone, a session stays pinned to an account whose weekly quota is spent the moment its
+   * 5-hour window resets, which is exactly the account next() would have avoided.
+   */
+  private hasQuotaRoom(accountId: string): boolean {
+    const snap = getLatestSnapshotForAccount(accountId);
+    if (!snap) return true;
+    if ((snap.five_hour_util ?? 0) >= FIVE_HOUR_SKIP_THRESHOLD) return false;
+    return (snap.weekly_util ?? 0) < WEEKLY_EXHAUSTED_UTIL;
+  }
+
+  /**
+   * Whether any selectable account still has room.
+   *
+   * Tells the caller whether next() would be picking a real candidate or falling back to
+   * "everything is near the cap, take one anyway" — a distinction a binding must not ignore.
+   */
+  private anyAccountHasQuotaRoom(excludeIds?: Set<string>): boolean {
+    const cooldownOn = this.isCooldownEnabled();
+    return accountService.list().some((a) => {
+      if (excludeIds?.has(a.id)) return false;
+      if (!(a.status === "active" || (!cooldownOn && a.status === "cooldown"))) return false;
+      return this.hasQuotaRoom(a.id);
+    });
+  }
+
+  /**
+   * Account bound to a session, falling back to a strategy pick that then becomes the binding.
+   *
+   * Anthropic's prompt cache is scoped per account, so moving a session to a different
+   * account re-sends its entire transcript as a cache write (1.25x) instead of a cache
+   * read (0.1x). On a long session that is the difference between a cheap turn and a
+   * very expensive one, which is why the binding exists at all.
+   *
+   * Rotation is not abandoned, only relocated: a session with no binding yet still goes
+   * through the configured strategy, so load still spreads — just per session rather than
+   * per turn. `bindSession` moves a session when an account genuinely cannot serve it.
+   */
+  forSession(sessionId: string, excludeIds?: Set<string>): AccountWithTokens | null {
+    this.clearExpiredCooldowns();
+    const boundId = getSessionAccount(sessionId);
+    if (boundId && !excludeIds?.has(boundId) && this.isSelectable(boundId)) {
+      // Hold the binding while it has room, and also when nothing else does. In that second
+      // case next() falls back to returning a near-capped account anyway, and round-robin
+      // would hand back a different one each turn — paying a full cache write per turn to
+      // move between accounts that are equally out of room.
+      if (this.hasQuotaRoom(boundId) || !this.anyAccountHasQuotaRoom(excludeIds)) {
+        const bound = accountService.getWithTokens(boundId);
+        if (bound) {
+          this._lastPickedId = boundId;
+          this._lastFailReason = "none";
+          return bound;
+        }
+      }
+    }
+    const picked = this.next(excludeIds);
+    if (picked) this.bindSession(sessionId, picked.id);
+    return picked;
+  }
+
+  /** Move a session onto an account — used when a switch is forced (rate/usage limit, auth). */
+  bindSession(sessionId: string, accountId: string): void {
+    setSessionAccount(sessionId, accountId);
+  }
+
+  /**
+   * Pick next available account (skips cooldown/disabled).
+   * Returns null if no active accounts available.
+   */
+  next(excludeIds?: Set<string>): AccountWithTokens | null {
+    this._lastFailReason = "none";
+    this.clearExpiredCooldowns();
 
     // When cooldown is disabled, treat parked (cooldown) accounts as selectable too —
     // any leftover cooldown from before the flag flip shouldn't lock an account out.

package/src/services/claude-usage.service.ts

@@ -296,9 +296,15 @@ export function getAllAccountUsages(): AccountUsageEntry[] {
   return result;
 }
 
-/** Get cached usage for active account (used by chat header) */
-export function getCachedUsage(): ClaudeUsage & { activeAccountId?: string; activeAccountLabel?: string } {
-  const activeId = accountSelector.lastPickedId;
+/**
+ * Cached usage for the account a caller cares about (used by chat header).
+ *
+ * `preferredAccountId` exists because accounts are bound per session: `lastPickedId` is a
+ * single global, so with two sessions on two accounts it names whichever ran last — the
+ * wrong account for at least one of the tabs displaying it.
+ */
+export function getCachedUsage(preferredAccountId?: string): ClaudeUsage & { activeAccountId?: string; activeAccountLabel?: string } {
+  const activeId = preferredAccountId ?? accountSelector.lastPickedId;
   if (activeId) {
     const usage = getUsageForAccount(activeId);
     const acc = accountService.list().find(a => a.id === activeId);
@@ -349,6 +355,26 @@ export async function refreshUsageNow(): Promise<ClaudeUsage & { activeAccountId
   return getCachedUsage();
 }
 
+/** Fetch + persist usage for a single account (used right after an account is added). */
+export async function refreshUsageForAccount(accountId: string): Promise<ClaudeUsage> {
+  const withTokens = await accountService.ensureFreshToken(accountId);
+  if (!withTokens) return {};
+  const token = withTokens.accessToken;
+  if (!token.startsWith("sk-ant-oat")) return {};
+  const cooldownKey = token.substring(0, 20);
+  const cooldownUntil = tokenCooldowns.get(cooldownKey);
+  if (cooldownUntil && Date.now() < cooldownUntil) return getUsageForAccount(accountId);
+  try {
+    const data = await fetchUsageForToken(token);
+    tokenCooldowns.delete(cooldownKey);
+    persistIfChanged(data, accountId);
+    return data;
+  } catch (e) {
+    console.error(`[usage] refreshUsageForAccount ${accountId}:`, (e as Error).message);
+    return getUsageForAccount(accountId);
+  }
+}
+
 /** @internal Test-only: reset module-level state between tests */
 export function _resetForTesting(): void {
   inMemoryCostUsd = 0;

package/src/services/db.service.ts

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { mkdirSync, existsSync } from "node:fs";
 import { encrypt, decrypt } from "../lib/account-crypto.ts";
 import { getPpmDir } from "./ppm-dir.ts";
-export const CURRENT_SCHEMA_VERSION = 39;
+export const CURRENT_SCHEMA_VERSION = 41;
 
 let db: Database | null = null;
 let dbProfile: string | null = null;
@@ -881,6 +881,24 @@ function runMigrations(database: Database): void {
       PRAGMA user_version = 39;
     `);
   }
+
+  if (current < 40) {
+    // Anthropic's prompt cache is scoped per account, so a session that rotates
+    // accounts re-sends its whole transcript as a cache write every time. Binding
+    // a session to one account keeps the prefix hitting the same cache; rotation
+    // moves to session assignment, where it costs nothing.
+    try { database.exec("ALTER TABLE session_metadata ADD COLUMN account_id TEXT"); } catch { /* column exists */ }
+    database.exec("PRAGMA user_version = 40;");
+  }
+
+  if (current < 41) {
+    // The prompt cache is per account, so a turn's cache hit rate only means something
+    // next to turns on the same account. Without this, a session that was moved between
+    // accounts shows unexplained cold turns.
+    try { database.exec("ALTER TABLE turn_usage ADD COLUMN account_id TEXT"); } catch { /* column exists */ }
+    try { database.exec("ALTER TABLE turn_usage ADD COLUMN account_label TEXT"); } catch { /* column exists */ }
+    database.exec("PRAGMA user_version = 41;");
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1076,6 +1094,25 @@ export function setSessionCodexAccount(sessionId: string, accountId: string): vo
   ).run(sessionId, accountId);
 }
 
+/**
+ * Claude account bound to a session (sticky across restarts).
+ *
+ * The prompt cache is scoped per account, so a session that switches accounts pays
+ * a full cache write of its entire transcript instead of a cache read. Binding keeps
+ * consecutive turns on one account; the rate-limit / usage-limit / auth paths rebind
+ * when they genuinely have to move.
+ */
+export function getSessionAccount(sessionId: string): string | null {
+  const row = getDb().query("SELECT account_id FROM session_metadata WHERE session_id = ?").get(sessionId) as { account_id: string | null } | null;
+  return row?.account_id ?? null;
+}
+
+export function setSessionAccount(sessionId: string, accountId: string): void {
+  getDb().query(
+    "INSERT INTO session_metadata (session_id, account_id) VALUES (?, ?) ON CONFLICT(session_id) DO UPDATE SET account_id = excluded.account_id",
+  ).run(sessionId, accountId);
+}
+
 /** Per-session model override; null when session uses provider default */
 export function getSessionModel(sessionId: string): string | null {
   const row = getDb().query("SELECT model FROM session_metadata WHERE session_id = ?").get(sessionId) as { model: string | null } | null;
@@ -1306,6 +1343,8 @@ export interface TurnUsageRow {
   cost_usd: number | null;
   cold_start: number;
   cold_reason: string | null;
+  account_id: string | null;
+  account_label: string | null;
   recorded_at: string;
 }
 
@@ -1320,18 +1359,22 @@ export function insertTurnUsage(record: {
   costUsd?: number;
   coldStart: boolean;
   coldReason?: string;
+  accountId?: string;
+  accountLabel?: string;
 }): void {
   getDb().query(
     `INSERT INTO turn_usage
        (session_id, model, input_tokens, output_tokens, cache_read_tokens,
-        cache_write_tokens, context_window, cost_usd, cold_start, cold_reason)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        cache_write_tokens, context_window, cost_usd, cold_start, cold_reason,
+        account_id, account_label)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   ).run(
     record.sessionId, record.model ?? null,
     record.inputTokens, record.outputTokens,
     record.cacheReadTokens, record.cacheWriteTokens,
     record.contextWindow ?? null, record.costUsd ?? null,
     record.coldStart ? 1 : 0, record.coldReason ?? null,
+    record.accountId ?? null, record.accountLabel ?? null,
   );
 }