@hienlh/ppm 0.17.45 → 0.17.46

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,
   );
 }
 

package/src/services/subprocess-retention.ts

@@ -0,0 +1,63 @@
+/**
+ * How long a clientless session may keep its SDK subprocess alive.
+ *
+ * A disconnect is usually a tab 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 pays cache-write rates for a
+ * prefix that was already cached — the reason the subprocess is kept at all.
+ *
+ * What bounds that generosity is not the disconnect but the prompt cache: once the cache
+ * behind the prefix has expired, the subprocess protects nothing and is only holding memory.
+ * These decisions live here, apart from the WebSocket wiring, so the timing they encode can
+ * be tested without standing up a session.
+ */
+
+/**
+ * Anthropic's default prompt-cache lifetime. A prefix not re-sent within this window has to
+ * be written to the cache again, so a subprocess older than this is worth nothing.
+ *
+ * Named here rather than inlined because the retention window is *derived* from it — the two
+ * were previously equal by coincidence, which read as if the teardown delay were arbitrary.
+ */
+export const PROMPT_CACHE_TTL_MS = 5 * 60_000;
+
+/**
+ * Milliseconds until a session's prompt cache lapses.
+ *
+ * Measured from the last completed turn, because that is when the cache was last written —
+ * not from the disconnect, which says nothing about the cache. Returns 0 once the window has
+ * already passed, meaning the subprocess can go immediately.
+ */
+export function cacheReleaseDelayMs(
+  lastTurnEndedAt: number | undefined,
+  now: number,
+  ttlMs: number = PROMPT_CACHE_TTL_MS,
+): number {
+  // No completed turn means nothing has been cached, so there is nothing to protect.
+  if (lastTurnEndedAt == null) return 0;
+  return Math.max(0, lastTurnEndedAt + ttlMs - now);
+}
+
+export interface WarmIdleSession {
+  sessionId: string;
+  /** When the session's last client left. Absent is treated as "longest idle". */
+  idleSince?: number;
+}
+
+/**
+ * Which held subprocesses to release when too many sessions are holding one.
+ *
+ * The grace period costs one Claude Code process per abandoned session, and PPM is built to
+ * be reachable from several devices, so abandoned sessions accumulate. Eviction takes the
+ * longest-idle sessions first: their caches are the closest to expiring, so their
+ * subprocesses are the ones worth the least.
+ *
+ * Returns session ids in eviction order; empty when the cap is not exceeded.
+ */
+export function selectWarmIdleEvictions(sessions: WarmIdleSession[], cap: number): string[] {
+  if (cap < 0 || sessions.length <= cap) return [];
+  const byIdleAscending = [...sessions].sort(
+    (a, b) => (a.idleSince ?? 0) - (b.idleSince ?? 0),
+  );
+  return byIdleAscending.slice(0, sessions.length - cap).map((s) => s.sessionId);
+}

package/src/shared/turn-usage.ts

@@ -39,6 +39,13 @@ export interface TurnUsage {
   coldStart: boolean;
   /** Why the previous subprocess went away, when PPM knows. */
   coldReason?: string;
+  /**
+   * Account that served the turn. The prompt cache is scoped per account, so a turn's cost
+   * is only comparable to turns on the same account — a session that moved accounts shows
+   * a cold prefix here for a reason that has nothing to do with the transcript.
+   */
+  accountId?: string;
+  accountLabel?: string;
 }
 
 /** Total prefix replayed to the API this turn, cached or not. */
@@ -59,7 +66,7 @@ export function uncachedPrefixTokens(u: TurnUsage): number {
  */
 export function buildTurnUsage(
   modelUsage: Record<string, ModelUsageLike> | undefined,
-  opts: { coldReason?: string } = {},
+  opts: { coldReason?: string; accountId?: string; accountLabel?: string } = {},
 ): TurnUsage | undefined {
   if (!modelUsage) return undefined;
   const entries = Object.entries(modelUsage);
@@ -104,6 +111,8 @@ export function buildTurnUsage(
     cacheHitRate: prefix > 0 ? cacheReadTokens / prefix : 0,
     coldStart: !!opts.coldReason,
     ...(opts.coldReason && { coldReason: opts.coldReason }),
+    ...(opts.accountId && { accountId: opts.accountId }),
+    ...(opts.accountLabel && { accountLabel: opts.accountLabel }),
   };
 }
 
@@ -129,6 +138,10 @@ export interface TurnCostVerdict {
 }
 
 const COLD_REASON_TEXT: Record<string, string> = {
+  cache_expired: "the session's prompt cache had already lapsed, so PPM released its subprocess",
+  idle_timeout: "the session sat idle with no tab open long enough for PPM to release its subprocess",
+  warm_idle_cap: "too many idle sessions were holding a subprocess, so this one was released early",
+  // Retained for turns recorded before the teardown moved to the idle timer.
   tab_closed: "PPM shut the session's subprocess down when the last tab disconnected",
   set_model: "the model was changed, which restarts the session",
   stream_ended: "the session's subprocess had already exited",
@@ -204,6 +217,7 @@ export function formatTurnUsageLog(u: TurnUsage): string {
     : "";
   return [
     `model=${u.model}`,
+    ...(u.accountLabel || u.accountId ? [`account=${u.accountLabel ?? u.accountId}`] : []),
     `cold=${u.coldStart ? (u.coldReason ?? "yes") : "no"}`,
     `in=${fmtTokens(u.inputTokens)}`,
     `cacheRead=${fmtTokens(u.cacheReadTokens)}`,

package/src/web/components/chat/chat-tab.tsx

@@ -68,9 +68,10 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
   const updateTab = useTabStore((s) => s.updateTab);
   const version = useSettingsStore((s) => s.version);
 
-  // Usage runs independently — auto-refreshes on interval
+  // Usage runs independently — auto-refreshes on interval. Scoped to this session so the
+  // account shown is the one bound to it, not whichever session ran most recently.
   const { usageInfo, usageLoading, lastFetchedAt, refreshUsage } =
-    useUsage(projectName, providerId);
+    useUsage(projectName, providerId, sessionId ?? undefined);
 
   // Draft auto-save/restore
   const { draft, draftLoading, saveDraft, clearDraft } = useDraft(projectName, sessionId);

package/src/web/components/chat/message-action-bar.tsx

@@ -67,13 +67,11 @@ function CopyButton({ content }: { content: string }) {
 export function MessageActionBar({
   timestamp,
   content,
-  accountLabel,
   className,
   children,
 }: {
   timestamp: string;
   content: string;
-  accountLabel?: string;
   className?: string;
   children?: ReactNode;
 }) {
@@ -87,7 +85,6 @@ export function MessageActionBar({
       <time title={fullDate(timestamp)} className="pr-1 tabular-nums">
         {formatRelativeDate(timestamp)}
       </time>
-      {accountLabel && <span className="px-1 truncate max-w-40">via {accountLabel}</span>}
       <CopyButton content={content} />
       {children}
     </div>

package/src/web/components/chat/message-list.tsx

@@ -525,7 +525,6 @@ const MessageBubble = memo(function MessageBubble({ message, isStreaming, isLast
         <TurnChangeRollup
           timestamp={message.timestamp}
           content={turnCopyText ?? assistantMessageText(message)}
-          accountLabel={message.accountLabel}
           changes={turnChanges}
           onJumpToEdit={onJumpToEdit}
         />

package/src/web/components/chat/session-debug-dialog.tsx

@@ -210,6 +210,9 @@ function TurnUsageHistory({ sessionId, projectName }: { sessionId: string; proje
   const cold = turns.filter((t) => t.usage.coldStart).length;
   const totalCost = turns.reduce((s, t) => s + t.usage.costUsd, 0);
   const wasted = turns.reduce((s, t) => s + uncachedPrefixTokens(t.usage), 0);
+  // More than one account over these turns explains cold prefixes on its own: the cache
+  // does not follow a session across accounts.
+  const accountsUsed = new Set(turns.map((t) => t.usage.accountId).filter(Boolean)).size;
 
   return (
     <div className="flex flex-col gap-2">
@@ -217,6 +220,7 @@ function TurnUsageHistory({ sessionId, projectName }: { sessionId: string; proje
       <p className="text-[11px] text-text-secondary">
         Last {turns.length} turn{turns.length === 1 ? "" : "s"} · {cold} restarted the session ·{" "}
         {fmtTokens(wasted)} of transcript re-sent uncached · ${totalCost.toFixed(2)}
+        {accountsUsed > 1 && ` · spread over ${accountsUsed} accounts`}
       </p>
 
       <div className="max-h-[30vh] overflow-y-auto rounded-md border border-border">
@@ -224,6 +228,7 @@ function TurnUsageHistory({ sessionId, projectName }: { sessionId: string; proje
           <thead className="sticky top-0 bg-surface text-text-subtle">
             <tr>
               <th className="px-2 py-1 text-left font-normal">When</th>
+              <th className="px-2 py-1 text-left font-normal">Account</th>
               <th className="px-2 py-1 text-right font-normal">Prefix</th>
               <th className="px-2 py-1 text-right font-normal">Cached</th>
               <th className="px-2 py-1 text-right font-normal">Cost</th>
@@ -239,6 +244,12 @@ function TurnUsageHistory({ sessionId, projectName }: { sessionId: string; proje
                   <td className="px-2 py-1 text-text-subtle">
                     {t.recordedAt.slice(11, 16) || t.recordedAt.slice(0, 10)}
                   </td>
+                  <td
+                    className="max-w-24 truncate px-2 py-1 text-text-subtle"
+                    title={t.usage.accountLabel ?? t.usage.accountId ?? ""}
+                  >
+                    {t.usage.accountLabel ?? t.usage.accountId?.slice(0, 8) ?? "—"}
+                  </td>
                   <td className="px-2 py-1 text-right text-text-secondary">
                     {fmtTokens(prefixTokens(t.usage))}
                   </td>
@@ -262,9 +273,10 @@ function TurnUsageHistory({ sessionId, projectName }: { sessionId: string; proje
         </table>
       </div>
       <p className="text-[11px] text-text-subtle">
-        A high "Cached" share is the cheap case. A turn marked <code>tab_closed</code> paid for the
-        whole transcript again because PPM shut the session's subprocess down when the last tab
-        disconnected.
+        A high "Cached" share is the cheap case. A turn marked <code>idle_timeout</code> paid for the
+        whole transcript again because the session sat idle with no tab open long enough for PPM to
+        release its subprocess. The cache is scoped per account, so a turn on a different account
+        starts cold no matter how the session was resumed.
       </p>
     </div>
   );

package/src/web/components/chat/turn-change-rollup.tsx

@@ -13,10 +13,9 @@ import { TurnChangePill, changeTotals } from "./turn-change-pill";
 import { TurnChangeTray } from "./turn-change-tray";
 import { TurnChangeSheet } from "./turn-change-sheet";
 
-export function TurnChangeRollup({ timestamp, content, accountLabel, changes, onJumpToEdit }: {
+export function TurnChangeRollup({ timestamp, content, changes, onJumpToEdit }: {
   timestamp: string;
   content: string;
-  accountLabel?: string;
   changes?: TurnFileChange[];
   onJumpToEdit?: (editRef: string) => void;
 }) {
@@ -35,7 +34,6 @@ export function TurnChangeRollup({ timestamp, content, accountLabel, changes, on
     <MessageActionBar
       timestamp={timestamp}
       content={content}
-      accountLabel={accountLabel}
       className="-mt-1.5"
     >
       {changes && changes.length > 0 && (

package/src/web/hooks/use-usage.ts

@@ -12,7 +12,11 @@ interface UseUsageReturn {
   refreshUsage: () => void;
 }
 
-export function useUsage(projectName: string, providerId = "claude"): UseUsageReturn {
+/**
+ * `sessionId` scopes the reported account to this session's binding. Without it the header
+ * shows whichever account ran last across every open session, which is wrong for all but one.
+ */
+export function useUsage(projectName: string, providerId = "claude", sessionId?: string): UseUsageReturn {
   const [usageInfo, setUsageInfo] = useState<UsageInfo>({});
   const [usageLoading, setUsageLoading] = useState(false);
   const [lastFetchedAt, setLastFetchedAt] = useState<string | null>(null);
@@ -22,11 +26,12 @@ export function useUsage(projectName: string, providerId = "claude"): UseUsageRe
     if (!projectName) return;
     setUsageLoading(true);
     const qs = forceRefresh ? "&refresh=1" : "";
+    const sessionQs = sessionId ? `&session=${encodeURIComponent(sessionId)}` : "";
     // Via api.get, not raw fetch: the toolbar's loading state is gated on this
     // settling, and a raw fetch has no timeout to stop it stalling forever.
     api
       .get<(UsageInfo & { lastFetchedAt?: string }) | null>(
-        `${projectUrl(projectName)}/chat/usage?providerId=${providerId}${qs}`,
+        `${projectUrl(projectName)}/chat/usage?providerId=${providerId}${sessionQs}${qs}`,
       )
       .then((data) => {
         if (!data) return;
@@ -35,7 +40,7 @@ export function useUsage(projectName: string, providerId = "claude"): UseUsageRe
       })
       .catch(() => {})
       .finally(() => setUsageLoading(false));
-  }, [projectName, providerId]);
+  }, [projectName, providerId, sessionId]);
 
   // Read cache on mount + auto-read every POLL_INTERVAL
   useEffect(() => {