@hienlh/ppm 0.17.44 → 0.17.46

package/src/server/ws/chat.ts

@@ -13,6 +13,8 @@ import { bashOutputSpy } from "../../services/bash-output-spy.ts";
 import { backgroundShellRegistry } from "../../services/background-shell-registry.ts";
 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. */
@@ -45,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",
@@ -86,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. */
@@ -251,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();
@@ -490,8 +575,14 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
         logSessionEvent(sessionId, "ERROR", errorDetail);
       } else if (evType === "done") {
         // Turn complete — transition to idle, clear buffer for next turn
-        logSessionEvent(sessionId, "DONE", `subtype=${ev.resultSubtype ?? "none"} turns=${ev.numTurns ?? "?"} ctx=${ev.contextWindowPct ?? "?"}%`);
+        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) => {
@@ -657,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;
 
@@ -1091,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/autostart-generator.ts

@@ -88,11 +88,11 @@ ${programArgs}
     <true/>
     <key>KeepAlive</key>
     <true/>
-    <!-- Upgrades self-replace by spawning a new supervisor and exiting. Without
-         this, launchd tears down the whole process group when the old
-         supervisor exits and kills the replacement seconds after it started. -->
-    <key>AbandonProcessGroup</key>
-    <true/>
+    <!-- No AbandonProcessGroup: upgrades exit and let KeepAlive restart us, so
+         there is no replacement to protect. Letting launchd tear down the
+         process group is what reaps the server and its Claude SDK children —
+         abandoning it orphaned them holding the listening socket, which forced
+         the next supervisor onto a fallback port and left a duplicate behind. -->
     <key>StandardOutPath</key>
     <string>${escapeXml(logPath)}</string>
     <key>StandardErrorPath</key>

package/src/services/autostart-register.ts

@@ -16,6 +16,7 @@ import {
   buildSchtasksDeleteCommand,
   buildSchtasksQueryCommand,
 } from "./autostart-generator.ts";
+import { isIsolatedPpmHome } from "./ppm-dir.ts";
 
 export interface AutoStartStatus {
   enabled: boolean;
@@ -27,6 +28,17 @@ export interface AutoStartStatus {
 
 const METADATA_FILE = resolve(homedir(), ".ppm", "autostart.json");
 
+/**
+ * The launchd plist / systemd unit live under the real `$HOME` and are
+ * machine-global, so PPM_HOME does not isolate them. Registering or removing
+ * one from an isolated run would hijack the user's live service.
+ */
+function skipIsolated(action: "enable" | "disable"): string {
+  const msg = `Auto-start ${action} skipped: PPM_HOME is isolated (${process.env.PPM_HOME}) — refusing to modify the real service manager`;
+  console.warn(`  ${msg}`);
+  return msg;
+}
+
 interface AutoStartMetadata {
   enabled: boolean;
   platform: string;
@@ -325,6 +337,7 @@ function statusWindows(): AutoStartStatus {
 
 /** Enable auto-start for the current platform. skipStart=true registers without starting (when supervisor is already running). */
 export async function enableAutoStart(config: AutoStartConfig, opts?: { skipStart?: boolean }): Promise<string> {
+  if (isIsolatedPpmHome()) return skipIsolated("enable");
   const platform = process.platform;
   if (platform === "darwin") return enableMacOS(config, opts);
   if (platform === "linux") return enableLinux(config, opts);
@@ -334,6 +347,7 @@ export async function enableAutoStart(config: AutoStartConfig, opts?: { skipStar
 
 /** Disable auto-start for the current platform */
 export async function disableAutoStart(): Promise<void> {
+  if (isIsolatedPpmHome()) { skipIsolated("disable"); return; }
   const platform = process.platform;
   if (platform === "darwin") return disableMacOS();
   if (platform === "linux") return disableLinux();

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 = 38;
+export const CURRENT_SCHEMA_VERSION = 41;
 
 let db: Database | null = null;
 let dbProfile: string | null = null;
@@ -857,6 +857,48 @@ function runMigrations(database: Database): void {
     try { database.exec("ALTER TABLE session_metadata ADD COLUMN cleared_from TEXT"); } catch { /* column exists */ }
     database.exec("PRAGMA user_version = 38;");
   }
+
+  if (current < 39) {
+    // usage_history records the account-wide quota snapshot polled from the API, which
+    // cannot answer why one turn cost more than the last. Cache hit rate is per turn and
+    // per session, so it needs its own row.
+    database.exec(`
+      CREATE TABLE IF NOT EXISTS turn_usage (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL,
+        model TEXT,
+        input_tokens INTEGER NOT NULL DEFAULT 0,
+        output_tokens INTEGER NOT NULL DEFAULT 0,
+        cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+        cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+        context_window INTEGER,
+        cost_usd REAL,
+        cold_start INTEGER NOT NULL DEFAULT 0,
+        cold_reason TEXT,
+        recorded_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_turn_usage_session ON turn_usage(session_id, id);
+      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;");
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1052,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;
@@ -1266,6 +1327,64 @@ export function getUsageSince(since: string): UsageRow[] {
   ).all(since) as UsageRow[];
 }
 
+// ---------------------------------------------------------------------------
+// Per-turn token accounting
+// ---------------------------------------------------------------------------
+
+export interface TurnUsageRow {
+  id: number;
+  session_id: string;
+  model: string | null;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_write_tokens: number;
+  context_window: number | null;
+  cost_usd: number | null;
+  cold_start: number;
+  cold_reason: string | null;
+  account_id: string | null;
+  account_label: string | null;
+  recorded_at: string;
+}
+
+export function insertTurnUsage(record: {
+  sessionId: string;
+  model?: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  contextWindow?: number;
+  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,
+        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,
+  );
+}
+
+/** Most recent turns first — the debug dialog shows the tail of a session. */
+export function listTurnUsage(sessionId: string, limit = 30): TurnUsageRow[] {
+  return getDb().query(
+    "SELECT * FROM turn_usage WHERE session_id = ? ORDER BY id DESC LIMIT ?",
+  ).all(sessionId, limit) as TurnUsageRow[];
+}
+
 // ---------------------------------------------------------------------------
 // Proxy request logging helpers
 // ---------------------------------------------------------------------------

package/src/services/ppm-dir.ts

@@ -12,3 +12,19 @@ export function getPpmDir(): string {
 export function _resetPpmDir(): void {
   _dir = undefined;
 }
+
+/**
+ * True when PPM_HOME points somewhere other than the real `~/.ppm` — i.e. an
+ * isolated run, in practice an integration test.
+ *
+ * Service-manager artifacts (launchd plist, systemd unit) deliberately resolve
+ * against the real `$HOME` and are machine-global, so PPM_HOME does NOT isolate
+ * them. Anything that registers, boots out, or sweeps processes machine-wide
+ * must bail out here — otherwise an "isolated" test running `ppm stop` tears
+ * down the user's live autostart job and production supervisor.
+ */
+export function isIsolatedPpmHome(): boolean {
+  const override = process.env.PPM_HOME;
+  if (!override) return false;
+  return resolve(override) !== resolve(homedir(), ".ppm");
+}

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