@hienlh/ppm 0.17.43 → 0.17.45

package/src/services/fs-browse.service.ts

@@ -55,12 +55,13 @@ export function isAllowedPath(resolved: string): boolean {
   const home = homedir();
   if (resolved === home || resolved.startsWith(home + "/")) return true;
 
-  // SDK background-command output lives under the OS temp dir (e.g. macOS
-  // /var/folders/.../T/claude/<session>/tasks/*.output), outside the home/posix-root
-  // whitelist. Allow reading those specific files so the chat output panel works.
-  // Matched by structure (claude/.../tasks/*.output) to be symlink-agnostic on macOS
-  // where the temp dir may resolve as /var vs /private/var.
-  if (/[\\/]claude[\\/].+[\\/]tasks[\\/][^\\/]+\.output$/.test(resolved)) return true;
+  // SDK background-command output lives under the OS temp dir, outside the
+  // home/posix-root whitelist. Allow reading those specific files so the chat
+  // output panel works. The claude dir name varies by platform/CLI version:
+  // "claude" (Windows Temp, older macOS /var/folders/.../T) or "claude-<uid>"
+  // (macOS /tmp/claude-501, reported by lsof as /private/tmp/...). Matched by
+  // structure (claude*/…/tasks/*.output) to be symlink-agnostic.
+  if (/[\\/]claude[^\\/]*[\\/].+[\\/]tasks[\\/][^\\/]+\.output$/.test(resolved)) return true;
 
   if (process.platform === "win32") {
     return /^[A-Z]:\\/i.test(resolved);

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/supervisor.ts

@@ -23,9 +23,10 @@ import { startStoppedPage, stopStoppedPage } from "./supervisor-stopped-page.ts"
 import { sdNotify } from "./sd-notify.ts";
 import {
   killProcessTree, snapshotServerDescendants, reapTrackedDescendants,
-  findPortListenerPid, isPpmProcess,
+  findPortListenerPid, isPpmProcess, collectProcessTree, terminateTree,
 } from "./windows-process-tree.ts";
 import { reapZombiePortOrphans } from "./windows-zombie-port-reaper.ts";
+import { PLIST_LABEL } from "./autostart-generator.ts";
 
 // ─── Constants ─────────────────────────────────────────────────────────
 const MAX_RESTARTS = 10;
@@ -157,14 +158,17 @@ function isPortBindable(port: number, host: string): Promise<boolean> {
 }
 
 /**
- * Resolve a port the next server child can actually bind. After a
- * hibernate/resume the previous server's orphaned child can keep the
- * listening socket open via an inherited handle that Windows will not release
- * (a "zombie port"). Binding the same port then fails forever and the child
- * crash-loops until max_restarts → paused. Instead: reap tracked orphans, kill
- * a live PPM holder if any, and — if the socket is still wedged — fall back to
- * the nearest free port so the backend stays up (the tunnel is re-pointed by
- * the caller). Returns `preferred` unchanged on the happy path.
+ * Resolve a port the next server child can actually bind. Returns `preferred`
+ * unchanged on the happy path.
+ *
+ * Windows: after a hibernate/resume the previous server's orphaned child can
+ * keep the listening socket open via an inherited handle the OS will not
+ * release (a "zombie port"). Binding the same port then fails forever, so we
+ * reap orphans and, as a last resort, fall back to a nearby port.
+ *
+ * POSIX: no such failure mode — a busy port means a live listener. We reclaim
+ * our own orphans but NEVER fall back, because a fallback turns a duplicate
+ * launch into a second full instance instead of a visible error.
  */
 async function ensureBindablePort(preferred: number, host: string): Promise<number> {
   if (await isPortBindable(preferred, host)) return preferred;
@@ -205,16 +209,39 @@ async function ensureBindablePort(preferred: number, host: string): Promise<numb
       }
     }
     if (await isPortBindable(preferred, host)) return preferred;
-  }
 
-  // Still blocked — zombie socket the OS will not release. Pick a nearby port.
-  for (let p = preferred + 1; p <= preferred + 20; p++) {
-    if (await isPortBindable(p, host)) {
-      log("WARN", `Port ${preferred} unbindable (zombie socket) — falling back to ${p}`);
-      return p;
+    // Still blocked — a zombie socket Windows will not release. Pick a nearby
+    // port so the backend stays up; the caller re-points the tunnel.
+    for (let p = preferred + 1; p <= preferred + 20; p++) {
+      if (await isPortBindable(p, host)) {
+        log("WARN", `Port ${preferred} unbindable (zombie socket) — falling back to ${p}`);
+        return p;
+      }
     }
+    log("ERROR", `No bindable port in [${preferred}, ${preferred + 20}] — keeping ${preferred}`);
+    return preferred;
+  }
+
+  // ── POSIX ────────────────────────────────────────────────────────────────
+  // There is no zombie-socket failure mode here: a busy port means something is
+  // genuinely listening. Never move to another port — that is what silently
+  // turned every extra supervisor into a full duplicate instance (7 of them,
+  // each with its own public tunnel) instead of failing visibly.
+  const holderPid = findPortListenerPid(preferred);
+  if (holderPid > 0 && holderPid !== process.pid && isPpmProcess(holderPid)) {
+    // Our own leaked server/agents from a previous generation. Reap and retry.
+    log("WARN", `Port ${preferred} held by orphaned PPM process (PID ${holderPid}) — reclaiming`);
+    killProcessTree(holderPid);
+    await Bun.sleep(800);
+    if (await isPortBindable(preferred, host)) return preferred;
   }
-  log("ERROR", `No bindable port in [${preferred}, ${preferred + 20}] — keeping ${preferred}`);
+
+  log(
+    "ERROR",
+    holderPid > 0
+      ? `Port ${preferred} is held by PID ${holderPid} and could not be reclaimed. Not falling back to another port — that would start a duplicate PPM. Run 'ppm stop', or free the port.`
+      : `Port ${preferred} is unbindable and no listener could be identified. Not falling back to another port.`,
+  );
   return preferred;
 }
 
@@ -251,12 +278,30 @@ function requestServerShutdown(child: Subprocess, timeoutMs: number = 2000): Pro
       // the inherited listening-socket handle open (zombie port).
       reapTrackedDescendants((m) => log("INFO", m)).finally(() => resolve());
     } else {
+      // Snapshot the tree BEFORE signalling: the Claude SDK grandchildren are
+      // not in their own process group, so once the server exits they reparent
+      // to init and become unfindable — while still holding the inherited
+      // listening socket. That leak is what wedged the port and let a second
+      // supervisor fall back to another port and run as a duplicate.
+      const tree = collectProcessTree(pid);
+      let settled = false;
+      const finish = () => { if (!settled) { settled = true; resolve(); } };
+
       try { child.kill("SIGTERM"); } catch {}
-      setTimeout(() => {
-        killProcessTree(pid);
-        resolve();
-      }, timeoutMs).unref();
-      resolve();
+
+      const timer = setTimeout(() => {
+        terminateTree(tree, 0).finally(finish);
+      }, timeoutMs);
+
+      child.exited
+        .catch(() => {})
+        .then(() => {
+          clearTimeout(timer);
+          // Even after a clean server exit the grandchildren can survive; reap
+          // the snapshot regardless of how the parent went down.
+          return terminateTree(tree, Math.min(timeoutMs, 2000));
+        })
+        .finally(finish);
     }
   });
 }
@@ -800,6 +845,12 @@ async function reapOrphanedTunnels(keepPid: number | null): Promise<void> {
 async function selfReplace(): Promise<{ success: boolean; error?: string }> {
   log("INFO", "Starting self-replace for upgrade");
   const underSystemd = !!process.env.INVOCATION_ID && process.platform === "linux";
+  // launchd sets XPC_SERVICE_NAME to the job label. Same situation as systemd:
+  // spawning a detached replacement is invisible to the service manager, so
+  // when we exit it respawns its OWN supervisor on top of the replacement —
+  // two live instances per upgrade, which is how 7 accumulated.
+  const underLaunchd =
+    process.platform === "darwin" && process.env.XPC_SERVICE_NAME === PLIST_LABEL;
   const currentSupervisorPid = process.pid;
 
   try {
@@ -838,33 +889,35 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
     // Kill server child to free the port; keep tunnel alive for domain continuity
     log("INFO", "Stopping server before upgrade (tunnel kept alive)");
     if (serverChild) {
-      const pid = serverChild.pid;
+      // requestServerShutdown reaps the whole descendant tree on both platforms.
+      // The old `kill(-pid)` here never worked: the server is not a process
+      // group leader, so the group kill hit ESRCH and the agents survived.
       await requestServerShutdown(serverChild, 2000);
-      // Process group kill on Unix (catches grandchildren like Claude SDK subprocesses)
-      if (process.platform !== "win32") {
-        try { process.kill(-pid, "SIGKILL"); } catch {}
-      }
       serverChild = null;
     }
     if (healthTimer) { clearInterval(healthTimer); healthTimer = null; }
 
-    // ── systemd path: exit cleanly, let Restart=always bring us back ────
-    // The old approach (Bun.spawn new supervisor + sd_notify MAINPID) causes
-    // systemd to lose track ("not our child"), leading to service death on
-    // daemon-reload. Instead, just exit — systemd restarts us with new code.
-    if (underSystemd) {
-      log("INFO", "Under systemd: exiting for automatic restart with updated code");
+    // ── Service-manager path: exit cleanly, let the manager bring us back ──
+    // The old approach (spawn a detached replacement + hand off) makes the
+    // manager lose track of us: systemd reports "not our child" and dies on
+    // daemon-reload, launchd's KeepAlive respawns a second supervisor on top of
+    // the replacement. Instead, just exit — the manager restarts us with the
+    // new code, as exactly one process.
+    if (underSystemd || underLaunchd) {
+      log("INFO", `Under ${underSystemd ? "systemd" : "launchd"}: exiting for automatic restart with updated code`);
       if (heartbeatTimer) clearInterval(heartbeatTimer);
       if (upgradeCheckTimer) clearInterval(upgradeCheckTimer);
       if (upgradeDelayTimer) clearTimeout(upgradeDelayTimer);
       if (cloudMonitorTimer) clearInterval(cloudMonitorTimer);
       // Disconnect Cloud WS so new supervisor can reconnect cleanly
       try { const { disconnect } = await import("./cloud-ws.service.ts"); disconnect(); } catch {}
-      // Don't kill tunnel — it lives in its own systemd-run scope and survives cgroup teardown
+      // Don't kill the tunnel — it lives in its own systemd-run scope / detached
+      // session, so it survives teardown and the restarted supervisor adopts it
+      // (status.json still says "upgrading", which preserves the public URL).
       process.exit(0);
     }
 
-    // ── Non-systemd path: spawn new supervisor directly (macOS/Windows) ─
+    // ── Unmanaged path: spawn new supervisor directly (bare `ppm start`) ─
     // Poll until port is actually free (max 10s) — never guess with fixed sleep.
     // The tree-kill above already reaped the server's grandchildren, so the
     // listening socket is released; this loop just waits for the OS to finish

package/src/services/windows-process-tree.ts

@@ -1,5 +1,13 @@
 /**
- * Windows-only process-tree utilities shared by supervisor / stop / server.
+ * Process-tree utilities shared by supervisor / stop / server.
+ *
+ * Most of this file is Windows-specific (see below), but the kill/collect
+ * helpers are cross-platform: on POSIX the server's children are NOT in their
+ * own process group (Bun.spawn does not setsid), so a `kill(-pid)` group kill
+ * targets a group that does not exist and silently no-ops. Descendants must be
+ * enumerated from `ps` and signalled individually, and the enumeration has to
+ * happen BEFORE the parent dies — once it exits, its children reparent to init
+ * and the tree is unrecoverable.
  *
  * The server's listening socket handle is inheritable on Windows, so every
  * descendant the server spawns (Claude SDK node processes, their bash/python
@@ -24,7 +32,22 @@ import { getPpmDir } from "./ppm-dir.ts";
  * — the holder may bind a different address than the one we configured.
  */
 export function findPortListenerPid(port: number): number {
-  if (process.platform !== "win32") return 0;
+  if (process.platform !== "win32") {
+    // lsof, not pgrep/pkill: on a memory-pressured box `sysmond` can be
+    // jetsam-killed, after which pgrep/pkill fail with a misleading error.
+    try {
+      const out = execFileSync(
+        "lsof",
+        ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"],
+        { encoding: "utf-8", timeout: 5000 },
+      );
+      for (const line of out.split("\n")) {
+        const pid = parseInt(line.trim(), 10);
+        if (!isNaN(pid) && pid > 0) return pid;
+      }
+    } catch {}
+    return 0;
+  }
   try {
     const out = execFileSync("netstat", ["-ano"], {
       encoding: "utf-8",
@@ -50,7 +73,17 @@ export function findPortListenerPid(port: number): number {
  * (a stale PPM orphan) vs. an unrelated app we must not kill.
  */
 export function isPpmProcess(pid: number): boolean {
-  if (process.platform !== "win32") return false;
+  if (process.platform !== "win32") {
+    try {
+      const out = execFileSync("ps", ["-p", String(pid), "-o", "command="], {
+        encoding: "utf-8",
+        timeout: 5000,
+      }).toLowerCase();
+      return out.includes("__serve__") || out.includes("__supervise__");
+    } catch {
+      return false;
+    }
+  }
   try {
     const out = execFileSync(
       "powershell.exe",
@@ -136,8 +169,89 @@ export function killProcessTree(pid: number): void {
       try { process.kill(pid, "SIGKILL"); } catch {}
     }
   } else {
-    try { process.kill(-pid, "SIGKILL"); } catch { try { process.kill(pid, "SIGKILL"); } catch {} }
+    killPids(collectProcessTree(pid), "SIGKILL");
+  }
+}
+
+/**
+ * POSIX: `pid` plus every descendant, parents before children. Windows: `[pid]`
+ * (taskkill /T walks the tree itself).
+ *
+ * Must be called while `pid` is still alive — descendants are found by walking
+ * ppid links, and a dead parent's children have already reparented to init.
+ */
+export function collectProcessTree(pid: number): number[] {
+  if (process.platform === "win32") return [pid];
+
+  const childrenOf = new Map<number, number[]>();
+  try {
+    const out = execFileSync("ps", ["-Ao", "pid=,ppid="], {
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+    for (const line of out.split("\n")) {
+      const [pidStr, ppidStr] = line.trim().split(/\s+/);
+      const p = parseInt(pidStr ?? "", 10);
+      const pp = parseInt(ppidStr ?? "", 10);
+      if (isNaN(p) || isNaN(pp)) continue;
+      const arr = childrenOf.get(pp);
+      if (arr) arr.push(p);
+      else childrenOf.set(pp, [p]);
+    }
+  } catch {
+    return [pid];
+  }
+
+  // BFS with visited guard — PID reuse can produce bogus parent cycles.
+  const visited = new Set<number>([pid]);
+  const order = [pid];
+  const queue = [pid];
+  while (queue.length > 0) {
+    const cur = queue.shift()!;
+    for (const child of childrenOf.get(cur) ?? []) {
+      if (visited.has(child)) continue;
+      visited.add(child);
+      order.push(child);
+      queue.push(child);
+    }
   }
+  return order;
+}
+
+/** Never signal init or ourselves, whatever the caller passes in. */
+function killable(pids: number[]): number[] {
+  return pids.filter((p) => p > 1 && p !== process.pid);
+}
+
+function isAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+/** Signal `pids` deepest-first so a parent cannot respawn a child mid-teardown. */
+export function killPids(pids: number[], signal: NodeJS.Signals = "SIGKILL"): void {
+  for (const p of killable(pids).reverse()) {
+    try { process.kill(p, signal); } catch {}
+  }
+}
+
+/**
+ * Graceful tree teardown: SIGTERM everything, wait up to `graceMs` for the tree
+ * to drain, then SIGKILL whatever is left. Callers must pass a tree collected
+ * before the root exited (see `collectProcessTree`).
+ */
+export async function terminateTree(pids: number[], graceMs: number = 2000): Promise<void> {
+  const targets = killable(pids);
+  if (targets.length === 0) return;
+
+  killPids(targets, "SIGTERM");
+
+  const deadline = Date.now() + graceMs;
+  while (Date.now() < deadline) {
+    if (!targets.some(isAlive)) return;
+    await Bun.sleep(100);
+  }
+
+  killPids(targets, "SIGKILL");
 }
 
 /**

package/src/shared/turn-usage.ts

@@ -0,0 +1,216 @@
+/**
+ * Per-turn token accounting.
+ *
+ * A resumed session re-sends its entire transcript on every turn, so the bill for a turn is
+ * dominated by that replayed prefix rather than by anything the user typed. Cached prefix
+ * tokens cost a fraction of fresh ones, which makes the cache hit rate — not the message
+ * length — the number that decides whether a turn was cheap or expensive.
+ *
+ * That is the whole reason this module exists: the SDK already reports the split, PPM was
+ * throwing it away, and a session whose prefix stops being cached gets an order of magnitude
+ * more expensive with nothing in the UI to show why.
+ */
+
+/** Shape of one entry in the SDK result's `modelUsage`, narrowed to the fields used here. */
+export interface ModelUsageLike {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+  contextWindow?: number;
+  costUSD?: number;
+}
+
+export interface TurnUsage {
+  /** Model that carried the largest share of the prefix (subagents report separately). */
+  model: string;
+  /** Fresh, uncached input tokens. */
+  inputTokens: number;
+  outputTokens: number;
+  /** Prefix served from cache — an order of magnitude cheaper than `inputTokens`. */
+  cacheReadTokens: number;
+  /** Prefix written into the cache, billed above the fresh-input rate. */
+  cacheWriteTokens: number;
+  contextWindow: number;
+  costUsd: number;
+  /** Share of the replayed prefix served from cache, 0–1. */
+  cacheHitRate: number;
+  /** The turn re-sent an existing transcript on a subprocess spawned for it. */
+  coldStart: boolean;
+  /** Why the previous subprocess went away, when PPM knows. */
+  coldReason?: string;
+}
+
+/** Total prefix replayed to the API this turn, cached or not. */
+export function prefixTokens(u: TurnUsage): number {
+  return u.inputTokens + u.cacheReadTokens + u.cacheWriteTokens;
+}
+
+/** Prefix tokens paid for at full rate — what a warm cache would have discounted. */
+export function uncachedPrefixTokens(u: TurnUsage): number {
+  return u.inputTokens + u.cacheWriteTokens;
+}
+
+/**
+ * Aggregate the SDK's per-model usage into one turn.
+ *
+ * Token counts are summed because every model in the map is billed, while the label takes the
+ * model holding the largest prefix so a turn is not attributed to a subagent's cheap helper.
+ */
+export function buildTurnUsage(
+  modelUsage: Record<string, ModelUsageLike> | undefined,
+  opts: { coldReason?: string } = {},
+): TurnUsage | undefined {
+  if (!modelUsage) return undefined;
+  const entries = Object.entries(modelUsage);
+  if (entries.length === 0) return undefined;
+
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheWriteTokens = 0;
+  let costUsd = 0;
+  let model = "";
+  let contextWindow = 0;
+  let topPrefix = -1;
+
+  for (const [name, u] of entries) {
+    const input = u.inputTokens ?? 0;
+    const read = u.cacheReadInputTokens ?? 0;
+    const write = u.cacheCreationInputTokens ?? 0;
+    inputTokens += input;
+    outputTokens += u.outputTokens ?? 0;
+    cacheReadTokens += read;
+    cacheWriteTokens += write;
+    costUsd += u.costUSD ?? 0;
+
+    const prefix = input + read + write;
+    if (prefix > topPrefix) {
+      topPrefix = prefix;
+      model = name;
+      contextWindow = u.contextWindow ?? 0;
+    }
+  }
+
+  const prefix = inputTokens + cacheReadTokens + cacheWriteTokens;
+  return {
+    model,
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    contextWindow,
+    costUsd,
+    cacheHitRate: prefix > 0 ? cacheReadTokens / prefix : 0,
+    coldStart: !!opts.coldReason,
+    ...(opts.coldReason && { coldReason: opts.coldReason }),
+  };
+}
+
+/**
+ * A prefix smaller than this is cheap however it is billed, so a poor hit rate on it is not
+ * worth interrupting the user over. Short sessions legitimately start cold.
+ */
+export const PREFIX_WARN_TOKENS = 20_000;
+
+/** Below this share of the prefix cached, the turn cost materially more than a warm one. */
+const HIT_RATE_BAD = 0.5;
+/** Above `HIT_RATE_BAD` but under this, part of the prefix was still re-sent at full price. */
+const HIT_RATE_WARN = 0.9;
+
+export type TurnCostLevel = "ok" | "warn" | "bad";
+
+export interface TurnCostVerdict {
+  level: TurnCostLevel;
+  /** Prefix tokens that a warm cache would have discounted. */
+  wastedTokens: number;
+  /** Why this turn cost more than it had to, phrased for the user. */
+  reason: string;
+}
+
+const COLD_REASON_TEXT: Record<string, string> = {
+  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",
+  resume: "the session was resumed on a new subprocess",
+};
+
+/**
+ * Judge a turn on the only thing the user can act on: how much of an *existing* transcript
+ * was paid for twice.
+ *
+ * A turn is only wasteful if there was a warm prefix to reuse. The first turn of a session
+ * writes its system prompt and instruction files into the cache with nothing to read back,
+ * which looks identical to the expensive case in the raw numbers but is unavoidable — so
+ * `coldStart`, not the hit rate alone, gates the warning. The cost of that choice is that
+ * mid-turn retries, which rebuild without recording a reason, go unflagged here; they remain
+ * visible in the per-turn history and the server log.
+ */
+export function assessTurnCost(u: TurnUsage): TurnCostVerdict {
+  const wastedTokens = uncachedPrefixTokens(u);
+  const prefix = prefixTokens(u);
+
+  if (!u.coldStart || prefix < PREFIX_WARN_TOKENS) {
+    return { level: "ok", wastedTokens, reason: "" };
+  }
+
+  const level: TurnCostLevel =
+    u.cacheHitRate < HIT_RATE_BAD ? "bad" : u.cacheHitRate < HIT_RATE_WARN ? "warn" : "ok";
+  if (level === "ok") return { level, wastedTokens, reason: "" };
+
+  const cause = u.coldReason ? COLD_REASON_TEXT[u.coldReason] ?? `the session restarted (${u.coldReason})` : null;
+  const reason = cause
+    ? `${fmtTokens(wastedTokens)} of this session's transcript was re-sent uncached because ${cause}.`
+    : `${fmtTokens(wastedTokens)} of this session's transcript was re-sent uncached.`;
+
+  return { level, wastedTokens, reason };
+}
+
+/**
+ * Billing weights relative to a fresh input token, used only to compare a turn against
+ * itself. Absolute cost comes from the SDK's `costUSD`; these exist to answer "how much
+ * cheaper would this turn have been with a warm cache", which no reported field covers.
+ */
+const CACHE_READ_WEIGHT = 0.1;
+const CACHE_WRITE_WEIGHT = 1.25;
+
+/**
+ * How many times more the turn's prefix cost than the same prefix fully cached.
+ *
+ * Returns 1 when there is nothing to compare — a fully cached prefix is already the floor.
+ */
+export function prefixCostMultiplier(u: TurnUsage): number {
+  const prefix = prefixTokens(u);
+  if (prefix === 0) return 1;
+  const actual =
+    u.inputTokens + u.cacheWriteTokens * CACHE_WRITE_WEIGHT + u.cacheReadTokens * CACHE_READ_WEIGHT;
+  const floor = prefix * CACHE_READ_WEIGHT;
+  return floor > 0 ? Math.max(1, actual / floor) : 1;
+}
+
+/** Compact token count for logs and dense UI. */
+export function fmtTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(n >= 10_000 ? 0 : 1)}k`;
+  return String(n);
+}
+
+/** One-line summary for the server log. */
+export function formatTurnUsageLog(u: TurnUsage): string {
+  const verdict = assessTurnCost(u);
+  const pct = Math.round(u.cacheHitRate * 100);
+  const ctx = u.contextWindow > 0
+    ? ` ctx=${Math.min(100, Math.round((prefixTokens(u) + u.outputTokens) / u.contextWindow * 100))}%`
+    : "";
+  return [
+    `model=${u.model}`,
+    `cold=${u.coldStart ? (u.coldReason ?? "yes") : "no"}`,
+    `in=${fmtTokens(u.inputTokens)}`,
+    `cacheRead=${fmtTokens(u.cacheReadTokens)}`,
+    `cacheWrite=${fmtTokens(u.cacheWriteTokens)}`,
+    `out=${fmtTokens(u.outputTokens)}`,
+    `hit=${pct}%${ctx}`,
+    `cost=$${u.costUsd.toFixed(4)}`,
+    `verdict=${verdict.level}`,
+  ].join(" ");
+}

package/src/types/chat.ts

@@ -162,7 +162,7 @@ export type ChatEvent =
   | { type: "tool_result"; output: string; isError?: boolean; toolUseId?: string; parentToolUseId?: string }
   | { type: "approval_request"; requestId: string; tool: string; input: unknown }
   | { type: "error"; message: string }
-  | { type: "done"; sessionId: string; resultSubtype?: ResultSubtype; numTurns?: number; contextWindowPct?: number; costUsd?: number; lastMessageUuid?: string }
+  | { type: "done"; sessionId: string; resultSubtype?: ResultSubtype; numTurns?: number; contextWindowPct?: number; costUsd?: number; lastMessageUuid?: string; usage?: import("../shared/turn-usage").TurnUsage }
   | { type: "account_info"; accountId: string; accountLabel: string }
   | { type: "account_retry"; reason: string; accountId?: string; accountLabel?: string }
   | { type: "status_update"; phase: "routing" | "refreshing" | "switching" | "retrying"; message: string; accountLabel?: string }
@@ -188,4 +188,6 @@ export interface ChatMessage {
   accountLabel?: string;
   /** SDK message UUID — used for fork/rewind (maps to JSONL message IDs) */
   sdkUuid?: string;
+  /** Token split for the turn that produced this message; drives the cost warning. */
+  usage?: import("../shared/turn-usage").TurnUsage;
 }

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

@@ -12,6 +12,7 @@ import {
   type TurnFileChange,
 } from "@/lib/aggregate-turn-file-changes";
 import { TurnChangeRollup } from "./turn-change-rollup";
+import { TurnCostWarning } from "./turn-cost-warning";
 import { TaskTracker } from "./task-tracker";
 import { extractJsonlPath } from "./pre-compact-button";
 // Kick off the markdown chunk fetch at module load (not first render): Suspense
@@ -515,6 +516,10 @@ const MessageBubble = memo(function MessageBubble({ message, isStreaming, isLast
               <MarkdownContent content={message.content} projectName={projectName} />
             </div>
           )}
+      {/* Cost notice sits above the action bar so it reads as part of the finished turn */}
+      {!isStreaming && isLastAssistantInTurn && message.usage && (
+        <TurnCostWarning usage={message.usage} />
+      )}
       {/* Action bar: only on the last assistant message of the turn, after streaming ends */}
       {!isStreaming && isLastAssistantInTurn && (
         <TurnChangeRollup