@maxiaochao/pi-toolkit 0.13.6 → 0.13.8

package/packages/cache-export/src/render.ts

@@ -9,8 +9,8 @@ import { USAGE_STYLES, USAGE_SCRIPT } from "./tau-assets.ts";
 // ---------------------------------------------------------------------------
 
 function hhmmss(ts) {
-  const iso = String(ts || "");
-  if (!iso) return "";
+  const iso = ts ?? "";
+  if (iso === "") return "";
   const d = new Date(iso);
   if (isNaN(d)) return "";
   // render in the machine's local timezone (Asia/Shanghai here -> Beijing time)
@@ -26,13 +26,20 @@ export function tzLabel() {
   return `${tz} (UTC${off})`;
 }
 
+function timeMs(value) {
+  const result = typeof value === "number" ? value : typeof value === "string" && value ? Date.parse(value) : NaN;
+  return Number.isFinite(result) ? result : null;
+}
+
 export function parseEntries(entries) {
   const requests = [];
   const events = [];
   const toolCounts = {};
   let compactions = 0;
   let prevKey = null;
-  const longCacheUntilByKey = new Map();
+  const auxiliary = [];
+  const warmByKey = new Map();
+  let observedPolicy;
   let gapTools = []; // tool results accumulated since the previous request
 
   const addEvent = (num, kind, label, ts) =>
@@ -41,7 +48,26 @@ export function parseEntries(entries) {
   for (const e of entries || []) {
     const t = e?.type;
     const ts = e?.timestamp;
+    if (t === "custom" && e.customType === "cache-export-request") {
+      observedPolicy = e.data;
+      continue;
+    }
+    if (t === "usage" || ((t === "compaction" || t === "branch_summary") && e.usage)) {
+      const kind = t === "usage" ? e.kind : t;
+      auxiliary.push({ kind, timestamp: hhmmss(ts), beforeRequest: requests.length + 1,
+        provider: e.provider ?? "Unknown", model: e.model ?? "Unknown", usage: e.usage ?? {} });
+      if (kind === "cache_warm" && ((e.usage?.cacheRead ?? 0) + (e.usage?.cacheWrite ?? 0)) > 0) {
+        warmByKey.set(`${e.provider}/${e.model}`, timeMs(ts));
+      }
+      if (t === "usage") continue;
+    }
+    if (t === "context_edit" || t === "branch_summary") {
+      addEvent(requests.length + 1, "context", t === "context_edit" ? "Context edit" : "Branch summary", ts);
+      warmByKey.clear();
+      continue;
+    }
     if (t === "compaction") {
+      warmByKey.clear();
       compactions += 1;
       addEvent(requests.length + 1, "compaction", "Compaction", ts);
       continue;
@@ -98,25 +124,33 @@ export function parseEntries(entries) {
     }
     prevKey = key;
 
-    const tsMs = Date.parse(String(ts || ""));
-    let longCacheUntil = longCacheUntilByKey.get(key) || 0;
-    if (u.cacheRead === 0 && u.cacheWrite > 0 && !u.cacheWrite1h) {
-      longCacheUntil = 0;
-      longCacheUntilByKey.delete(key);
-    }
-    if (u.cacheWrite1h > 0 && Number.isFinite(tsMs)) {
-      longCacheUntil = Math.max(longCacheUntil, tsMs + LONG_TTL_MINUTES * 60000);
-      longCacheUntilByKey.set(key, longCacheUntil);
-    }
-    const cacheTtlMinutes = Number.isFinite(tsMs) && tsMs <= longCacheUntil
-      ? LONG_TTL_MINUTES
-      : DEFAULT_TTL_MINUTES;
+    const startMs = timeMs(m.timestamp);
+    const durationMs = Number.isFinite(m.durationMs) && m.durationMs >= 0 ? m.durationMs : null;
+    const previous = requests.at(-1);
+    const startGapMs = startMs !== null && previous?.startMs !== null && previous?.startMs !== undefined
+      ? startMs - previous.startMs : null;
+    const idleMs = startMs !== null && previous?.endMs !== null && previous?.endMs !== undefined
+      ? Math.max(0, startMs - previous.endMs) : null;
+    const policy = observedPolicy?.messageTimestamp === m.timestamp && observedPolicy?.provider === provider && observedPolicy?.model === model && observedPolicy?.api === api
+      ? observedPolicy.policy : null;
+    observedPolicy = undefined;
+    const references = new Set((Array.isArray(policy?.explicitTtlsSeconds) ? policy.explicitTtlsSeconds : [])
+      .filter((seconds) => Number.isFinite(seconds) && seconds > 0));
+    // A reported one-hour write is a policy reference, not a server expiry time.
+    // Never propagate a guessed expiry or downgrade historical hits to five minutes.
+    if (u.cacheWrite1h > 0) references.add(3600);
+    const mixedWrites = u.cacheWrite1h > 0 && u.cacheWrite > u.cacheWrite1h;
+    const policyReferenceSeconds = !mixedWrites && references.size === 1 ? [...references][0] : null;
 
     const cost = u.cost && typeof u.cost.total === "number" ? u.cost.total : null;
     requests.push({
       number: num,
       isoTs: String(ts || ""),
-      timestamp: hhmmss(ts),
+      timestamp: hhmmss(startMs) || "Unknown",
+      startMs, durationMs, startGapMs, idleMs,
+      endMs: startMs !== null && durationMs !== null ? startMs + durationMs : null,
+      lastWarmAt: warmByKey.get(key) ?? null,
+      policy, policyReferenceSeconds,
       provider,
       model,
       api,
@@ -125,9 +159,8 @@ export function parseEntries(entries) {
       cached,
       cacheWrite,
       cacheWrite1h: u.cacheWrite1h || 0,
-      cacheTtlMinutes,
       output,
-      reasoning: u.reasoning || 0,
+      reasoning: Number.isFinite(u.reasoning) ? u.reasoning : null,
       stopReason: m.stopReason || "",
       estimatedCost: cost,
       gapTools,
@@ -138,7 +171,7 @@ export function parseEntries(entries) {
   }
 
   const toolCalls = Object.entries(toolCounts).sort((a, b) => b[1] - a[1]);
-  return { requests, events, toolCalls, compactions };
+  return { requests, events, toolCalls, compactions, auxiliary };
 }
 
 // ---------------------------------------------------------------------------
@@ -160,7 +193,7 @@ const SERIES_COLORS = {
   "cache writes": ["#9cffb1", "#166534"],
   fresh: ["#ff4f4f", "#b91c1c"],
   request: ["#ff4f4f", "#b91c1c"],
-  cumulative: ["#93c5fd", "#2563eb"],
+  "segment cumulative": ["#93c5fd", "#2563eb"],
   output: ["#c084fc", "#9333ea"],
   reasoning: ["#9cffb1", "#166534"],
   event: ["#a7f3f0", "#0f766e"],
@@ -181,6 +214,27 @@ function fmtCost(v) {
 
 const fmtInt = (n) => n.toLocaleString("en-US");
 const fmtPct1 = (x) => (x * 100).toFixed(1) + "%";
+const fmtDuration = (ms) => Number.isFinite(ms) ? `${(ms / 1000).toFixed(1)}s` : "Unknown";
+
+function policyLabel(request) {
+  const reference = request.policyReferenceSeconds;
+  const model = request.policy?.modelReference;
+  const modelText = model && Object.keys(model).length
+    ? `; model reference ${Object.entries(model).map(([tier, seconds]) => `${tier}=${seconds}s`).join(", ")}` : "";
+  const retention = request.policy?.retention ? `; observed retention=${request.policy.retention}` : "";
+  return `${Number.isFinite(reference) ? `${reference}s recorded reference` : "Unknown"}${retention}${modelText}; server expiry Unknown`;
+}
+
+function renderAuxiliaryUsage(auxiliary = []) {
+  const count = (value) => Number.isFinite(value) ? fmtInt(value) : "Unknown";
+  const rows = auxiliary.map((entry) => `<tr><td>${esc(entry.kind)}</td><td>${esc(entry.timestamp)}</td>` +
+    `<td>${esc(entry.provider)}</td><td>${esc(entry.model)}</td>` +
+    ["input", "cacheRead", "cacheWrite", "output"].map((field) => `<td>${count(entry.usage[field])}</td>`).join("") + "</tr>").join("");
+  return `<div class="usage-panel"><h2>Auxiliary usage (whole branch)</h2>` +
+    `<p class="usage-note">Completed usage records only: cache warming, compaction and other auxiliary calls. Excluded from main-request charts and totals. A completed warm call is not proof that the next main prefix will hit. Planned warming is not counted.</p>` +
+    `<div class="usage-table-wrap"><table><thead><tr><th>Kind</th><th>Recorded completion</th><th>Provider</th><th>Model</th><th>Fresh</th><th>Cached</th><th>Written</th><th>Output</th></tr></thead>` +
+    `<tbody>${rows || '<tr><td colspan="8">No auxiliary usage recorded.</td></tr>'}</tbody></table></div></div>`;
+}
 
 // ---------------------------------------------------------------------------
 // _line_chart port
@@ -271,7 +325,7 @@ function lineChart(title, series, opts = {}) {
     // every index while the visible broken polylines still draw the gaps.
     const full = `<polyline class="series-line" data-dark="${dark}" data-light="${light}" visibility="hidden" fill="none" stroke="${dark}" stroke-width="3" ` +
       `points="${values.map((v, i) => point(i, Number.isFinite(v) ? v : 0).map((c) => c.toFixed(1)).join(",")).join(" ")}"/>`;
-    const labels = values.map((v) => !Number.isFinite(v) ? "N/A" : (percent ? `${(v * 100).toFixed(1)}%` : fmtInt(Math.trunc(v)))).join("|");
+    const labels = values.map((v) => !Number.isFinite(v) ? "Unknown" : (percent ? `${(v * 100).toFixed(1)}%` : fmtInt(Math.trunc(v)))).join("|");
     parts.push(
       `<g class="series" data-series-id="${seriesIndex}" data-name="${esc(name, true)}" data-labels="${esc(labels, true)}">` +
         full +
@@ -291,7 +345,7 @@ function lineChart(title, series, opts = {}) {
     );
   });
   parts.push(
-    `<text class="axis-label" x="${(left + plotWidth / 2).toFixed(1)}" y="${height - 4}" text-anchor="middle">Model request</text></svg>`,
+    `<text class="axis-label" x="${(left + plotWidth / 2).toFixed(1)}" y="${height - 4}" text-anchor="middle">Main request sequence (not time)</text></svg>`,
   );
   return parts.join("");
 }
@@ -309,8 +363,6 @@ const figure = (chart) =>
 
 const MISS_THRESHOLD = 0.5; // hit rate below this gets an explanation row
 const PREFIX_REUSE_THRESHOLD = 0.5;
-const DEFAULT_TTL_MINUTES = 5;
-const LONG_TTL_MINUTES = 60;
 
 function reusablePrefix(request) {
   const prompt = request.fresh + request.cached + request.cacheWrite;
@@ -319,10 +371,6 @@ function reusablePrefix(request) {
   return explicitlyCached > 0 ? explicitlyCached : prompt;
 }
 
-function ttlMinutesAfter(request) {
-  return request.cacheTtlMinutes ?? (request.cacheWrite1h > 0 ? LONG_TTL_MINUTES : DEFAULT_TTL_MINUTES);
-}
-
 export function analyzeMisses(requests, events) {
   const evByReq = new Map();
   for (const ev of events) {
@@ -347,30 +395,34 @@ export function analyzeMisses(requests, events) {
     const prefixReuse = expectedPrefix > 0 ? Math.min(1, r.cached / expectedPrefix) : 0;
 
     if (i === 0) {
-      causes.push(["first request", "cold session: nothing cached yet; the prefix can only be reused by a later request"]);
+      causes.push(r.number === 1
+        ? ["first request", "first recorded main request; earlier server cache state is unknown, so a cold start is not established"]
+        : ["segment boundary", "first request in this view, not the first request of the session"]);
     }
     if (prev && (prev.provider !== r.provider || prev.model !== r.model)) {
-      causes.push(["model switch", `${prev.provider}/${prev.model} -> ${r.provider}/${r.model}: prefix invalidated by provider/model change`]);
+      causes.push(["model switch", `${prev.provider}/${prev.model} -> ${r.provider}/${r.model}: provider/model changed; cache reuse across routes is unknown`]);
     }
     for (const ev of evByReq.get(r.number) || []) {
       if (ev.kind === "compaction") {
-        causes.push(["compaction", "context was rewritten by compaction; cache rebuilds on the new prefix"]);
+        causes.push(["compaction", "observed compaction rewrote context; a cache rebuild is possible, not proven"]);
+      } else if (ev.kind === "context") {
+        causes.push(["context edit", `${ev.label}: recorded context transformation; cache impact is unknown`]);
       } else if (ev.kind === "model" && r.number > 1 && !causes.some(([c]) => c === "model switch")) {
-        causes.push(["model switch", `${ev.label}: prefix invalidated by provider/model change`]);
+        causes.push(["model switch", `${ev.label}: provider/model changed; cache reuse across routes is unknown`]);
       } else if (ev.kind === "thinking" && r.number > 1) {
         causes.push(["thinking change", `${ev.label}: request parameters changed`]);
       }
     }
-    if (prev && r.isoTs && prev.isoTs) {
-      const gapMin = (Date.parse(r.isoTs) - Date.parse(prev.isoTs)) / 60000;
-      const ttlMinutes = ttlMinutesAfter(prev);
-      if (gapMin > ttlMinutes && prefixReuse < PREFIX_REUSE_THRESHOLD && !causes.some(([c]) => c === "compaction" || c === "model switch")) {
-        causes.push(["possible TTL expiry", `idle gap ${gapMin.toFixed(0)}min > ${ttlMinutes}min heuristic; actual retention depends on the provider`]);
+    if (prev && r.startMs !== null && prev.startMs !== null && r.startMs > prev.startMs) {
+      const warmed = r.lastWarmAt !== null && r.lastWarmAt > prev.startMs && r.lastWarmAt <= r.startMs;
+      const reference = prev.policyReferenceSeconds;
+      if (!warmed && reference > 0 && (r.startMs - prev.startMs) / 1000 > reference && prefixReuse < PREFIX_REUSE_THRESHOLD && !causes.length) {
+        causes.push(["possible TTL expiry", `request-start gap ${((r.startMs - prev.startMs) / 60000).toFixed(1)}min crosses a recorded ${(reference / 60).toFixed(0)}min policy reference; not an idle gap or a server expiry measurement`]);
       }
     }
     if (prev && prefixReuse < PREFIX_REUSE_THRESHOLD && !causes.length) {
-      const writeDetail = r.cacheWrite > 0 ? `; provider also reported ${r.cacheWrite.toLocaleString("en-US")} tokens written for the replacement prefix` : "";
-      causes.push(["cache rebuild", `only ${(prefixReuse * 100).toFixed(1)}% of the prior reusable prefix was read; the cache was likely lost or invalidated${writeDetail}`]);
+      const writeDetail = r.cacheWrite > 0 ? `; provider also reported ${r.cacheWrite.toLocaleString("en-US")} tokens written (prefix identity unknown)` : "";
+      causes.push(["cache rebuild", `cache reads equal ${(prefixReuse * 100).toFixed(1)}% of the prior reported prompt reference; possible rebuild or changed prefix; actual server state and cause are unknown${writeDetail}`]);
     }
     if (r.cacheWrite > 0 && !causes.length) {
       causes.push(["cache write", `provider reported ${r.cacheWrite.toLocaleString("en-US")} tokens written; a low read-hit rate is expected while a prefix is created or extended`]);
@@ -379,10 +431,10 @@ export function analyzeMisses(requests, events) {
       const toolChars = (r.gapTools || []).reduce((sum, tool) => sum + tool.chars, 0);
       const toolTokens = Math.round(toolChars / 4);
       const toolDetail = toolTokens > 0 ? `, including ~${toolTokens.toLocaleString("en-US")} estimated tool-output tokens` : "";
-      causes.push(["new input", `reused ${(prefixReuse * 100).toFixed(1)}% of the prior prefix; ${r.fresh.toLocaleString("en-US")} fresh tokens were newly appended${toolDetail}`]);
+      causes.push(["new input", `cache reads equal ${(prefixReuse * 100).toFixed(1)}% of the prior reported prompt reference; ${r.fresh.toLocaleString("en-US")} fresh tokens were reported; appended content is a possible explanation${toolDetail}`]);
     }
     if (!causes.length) {
-      causes.push(["unclassified", "no rule matched; usually new content appended beyond the cached prefix (large tool results / long user input)"]);
+      causes.push(["unclassified", "no causal evidence matched; the server cache state is unknown"]);
     }
 
     for (const [cause] of causes) {
@@ -395,8 +447,7 @@ export function analyzeMisses(requests, events) {
   }
 
   const summaryArr = [...summary.entries()].sort((a, b) => b[1].fresh - a[1].fresh);
-  return { misses, summary: summaryArr, noCacheReporting, threshold: MISS_THRESHOLD,
-    ttlMinutes: DEFAULT_TTL_MINUTES, longTtlMinutes: LONG_TTL_MINUTES };
+  return { misses, summary: summaryArr, noCacheReporting, threshold: MISS_THRESHOLD };
 }
 
 // Streak detection: many consecutive requests stuck in a mid hit-rate band.
@@ -419,7 +470,7 @@ export function analyzeStreaks(requests, events = []) {
   let gaps = 0; // consecutive non-member requests inside the current run
   let prevKey = null;
   const resetBefore = new Set(events
-    .filter((event) => event.kind === "compaction" || event.kind === "model")
+    .filter((event) => event.kind === "compaction" || event.kind === "model" || event.kind === "context")
     .map((event) => event.requestNumber));
   const close = () => {
     if (cur && cur.hits.length >= STREAK_MIN_LEN) streaks.push(cur);
@@ -479,13 +530,13 @@ function renderStreakPanel(streaks) {
       const pct = (x) => (x * 100).toFixed(1) + "%";
       return `<tr><td>#${s.from}–#${s.to}</td><td>${s.hits.length}</td><td>${pct(s.avgHit)}</td>` +
         `<td>${fmtInt(s.fresh)}</td>` +
-        `<td style="white-space:normal">tool outputs: ${tools || "-"} · assistant replies: ${fmtInt(s.replyTokens)} · trace explains ~${pct(s.coverage)} of fresh</td></tr>`;
+        `<td style="white-space:normal">tool outputs: ${tools || "-"} · assistant replies: ${fmtInt(s.replyTokens)} · trace estimate / fresh ~${pct(s.coverage)} of fresh</td></tr>`;
     })
     .join("");
   return `<div class="usage-panel"><h2>Hit-rate streak analysis</h2>` +
     `<p class="usage-note">Rule-based, no LLM. A streak is ${STREAK_MIN_LEN}+ requests (single healthy outlier tolerated) with hit rate ` +
     `${(STREAK_LOW * 100).toFixed(0)}–${(STREAK_HIGH * 100).toFixed(1)}% (requests reporting cacheWrite break the streak; fresh ≥ ${STREAK_MIN_FRESH} tok, prefix ≥ ${STREAK_MIN_PROMPT}): ` +
-    `usually each turn appends large fresh content (big tool outputs / long replies), not a cache failure. ` +
+    `appended tool outputs or replies are possible contributors, not proof of cache health or failure. ` +
     `Below ${(MISS_THRESHOLD * 100).toFixed(0)}% see the miss panel above. Tool tokens estimated at 4 chars/token.</p>` +
     `<div class="usage-table-wrap" style="max-height:260px"><table>` +
     `<thead><tr><th>Requests</th><th>Turns</th><th>Avg hit</th><th>Total fresh</th><th>Trace (fresh composition)</th></tr></thead>` +
@@ -508,9 +559,9 @@ function renderMissPanel(miss) {
     .join("");
   return `<div class="usage-panel"><h2>Cache miss analysis</h2>` +
     `<p class="usage-note">Rule-based attribution, no LLM. Rows are requests below ${(miss.threshold * 100).toFixed(0)}% hit rate. ` +
-    `TTL attribution uses a ${miss.ttlMinutes}min idle-gap heuristic, or ${miss.longTtlMinutes}min after a reported 1h cache write; actual retention is provider-specific.</p>` +
+    `Observed usage and context events are facts; causes are possibilities. Policy references are not measured expiry times. Without historical request parameters, retention is unknown. No universal TTL is assumed.</p>` +
     `<div class="usage-table-wrap" style="max-height:340px"><table>` +
-    `<thead><tr><th>#</th><th>Time</th><th>Hit rate</th><th>Fresh</th><th>Cause</th></tr></thead>` +
+    `<thead><tr><th>#</th><th>Time</th><th>Hit rate</th><th>Fresh</th><th>Evidence / possible cause</th></tr></thead>` +
     `<tbody>${rows || `<tr><td colspan="5" class="empty">None</td></tr>`}</tbody></table></div>` +
     `<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:8px;margin-top:12px">${summaryHtml}</div></div>`;
 }
@@ -521,7 +572,7 @@ function renderMissPanel(miss) {
 
 export function buildContextSegments(requests, events) {
   const starts = new Set(events
-    .filter((event) => (event.kind === "compaction" || event.kind === "model") && event.requestNumber >= 1 && event.requestNumber <= requests.length)
+    .filter((event) => (event.kind === "compaction" || event.kind === "model" || event.kind === "context") && event.requestNumber >= 1 && event.requestNumber <= requests.length)
     .map((event) => event.requestNumber));
   const segments = [];
   let start = 0;
@@ -571,7 +622,7 @@ function renderDashboardView(requests, events, toolCalls, compactions, scopeLabe
   const contextBreakBefore = new Set();
   const cacheBreakBefore = new Set();
   const resetBefore = new Set(events
-    .filter((event) => event.kind === "compaction" || event.kind === "model")
+    .filter((event) => event.kind === "compaction" || event.kind === "model" || event.kind === "context")
     .map((event) => event.requestNumber));
   const cumulativeRates = [];
   let runCached = 0, runPrompt = 0;
@@ -581,7 +632,7 @@ function renderDashboardView(requests, events, toolCalls, compactions, scopeLabe
   for (let index = 0; index < requests.length; index++) {
     const r = requests[index];
     const key = `${r.provider}/${r.model}`;
-    const contextReset = index > 0 && events.some((event) => (event.kind === "compaction" || event.kind === "model") && event.requestNumber === r.number);
+    const contextReset = index > 0 && events.some((event) => (event.kind === "compaction" || event.kind === "model" || event.kind === "context") && event.requestNumber === r.number);
     const cacheReset = index > 0 && (resetBefore.has(r.number) || (previousKey !== null && key !== previousKey));
     if (contextReset) contextBreakBefore.add(index);
     if (cacheReset) {
@@ -633,7 +684,7 @@ function renderDashboardView(requests, events, toolCalls, compactions, scopeLabe
   ];
   if (cacheHitRate !== null) {
     charts.push(figure(lineChart("Cache hit rate",
-      [["request", rates], ["cumulative", cumulativeRates]],
+      [["request", rates], ["segment cumulative", cumulativeRates]],
       { yMax: 1.0, percent: true, timestamps, requestNumbers, events: eventMarkers, breakBefore: cacheBreakBefore })));
   }
   charts.push(figure(lineChart("Output and reasoning tokens",
@@ -647,7 +698,10 @@ function renderDashboardView(requests, events, toolCalls, compactions, scopeLabe
       `<td>${esc(r.model)}</td><td>${fmtInt(r.fresh)}</td><td>${fmtInt(r.cached)}</td>` +
       `<td>${fmtInt(r.cacheWrite)}</td><td>${fmtInt(r.fresh + r.cached + r.cacheWrite)}</td>` +
       `<td>${showHit ? fmtPct1(r.cached / Math.max(1, r.fresh + r.cached + r.cacheWrite)) : "N/A"}</td>` +
-      `<td>${fmtInt(r.output)}</td><td>${esc(r.stopReason, true)}</td></tr>`,
+      `<td>${fmtInt(r.output)}</td><td>${Number.isFinite(r.reasoning) ? fmtInt(r.reasoning) : "Unknown"}</td>` +
+      `<td>${fmtDuration(r.durationMs)}</td><td>${fmtDuration(r.startGapMs)}</td><td>${fmtDuration(r.idleMs)}</td>` +
+      `<td>${esc(hhmmss(r.isoTs))}</td><td>${esc(policyLabel(r))}</td>` +
+      `<td>${r.lastWarmAt === null ? "Unknown" : esc(hhmmss(r.lastWarmAt))}</td><td>${esc(r.stopReason, true)}</td></tr>`,
     )
     .join("");
 
@@ -657,15 +711,16 @@ function renderDashboardView(requests, events, toolCalls, compactions, scopeLabe
 
   return (
     `<div class="usage-cards">${cardsHtml}</div>` +
-    `<p class="usage-note">Prompt and output lines break at a Context segment boundary (compaction or model change). Cache-window cumulative hit rate also resets at a model change. ` +
-    `TTL and service interruptions are shown only when recorded or inferred by the miss analysis; they do not create a Context segment.</p>` +
+    `<p class="usage-note">Prompt and output lines break at a Context segment boundary (compaction, context edit, or model change). Segment cumulative hit rate resets at each such boundary. ` +
+    `The x-axis is request sequence, not elapsed time. Cache hit rate = cacheRead / (input + cacheRead + cacheWrite). These are provider/Pi-reported usage values, not server cache telemetry. Auxiliary calls are separate; unreported reasoning is Unknown.</p>` +
     `<div class="usage-charts">${charts.join("")}</div>` +
     renderMissPanel(analyzeMisses(requests, events)) +
     renderStreakPanel(analyzeStreaks(requests, events)) +
     `<div class="usage-details">` +
     `<div class="usage-panel"><h2>Requests</h2><div class="usage-table-wrap"><table>` +
-    `<thead><tr><th>#</th><th>Time</th><th>Provider</th><th>Response Provider</th><th>Model</th>` +
+    `<thead><tr><th>#</th><th>Request start</th><th>Provider</th><th>Response Provider</th><th>Model</th>` +
     `<th>Fresh</th><th>Cached</th><th>Written</th><th>Prompt</th><th>Hit rate</th><th>Output</th>` +
+    `<th>Reasoning</th><th>Response duration</th><th>Start-to-start</th><th>Gap after response</th><th>Recorded at</th><th>Policy reference (not expiry)</th><th>Last completed warm with cache usage</th>` +
     `<th>Stop</th></tr></thead><tbody>${rows}</tbody></table></div></div>` +
     `<div class="usage-panel"><h2>Tool calls</h2>${toolRows}</div>` +
     `</div>`
@@ -675,7 +730,7 @@ function renderDashboardView(requests, events, toolCalls, compactions, scopeLabe
 export function renderDashboard(data) {
   const { requests, events, toolCalls, compactions } = data;
   if (!requests.length) {
-    return `<p class="empty">No assistant responses with token usage were found in this session.</p>`;
+    return `<p class="empty">No main assistant responses with token usage were found in this session.</p>` + renderAuxiliaryUsage(data.auxiliary);
   }
 
   const segments = buildContextSegments(requests, events);
@@ -716,7 +771,7 @@ export function renderDashboard(data) {
   return `<div class="usage-view-controls"><label for="context-segment-select">View</label>` +
     `<select id="context-segment-select" data-context-segment-select>${options}</select>` +
     `<span>Default: latest Context segment. All-history values remain available; cache metrics reset where compaction rewrites the prefix or the model changes.</span></div>` +
-    views +
+    views + renderAuxiliaryUsage(data.auxiliary) +
     `<div class="usage-tooltip" role="status" aria-live="polite"></div>`;
 }
 
@@ -778,6 +833,12 @@ document.querySelectorAll(".usage-chart").forEach((chart) => {
     if (!tooltip) return;
     const m = tooltip.textContent.match(/^Request (\\d+)/);
     if (!m) return;
+    const index = Number(m[1]) - 1;
+    chart.querySelectorAll(".series").forEach((series) => {
+      if ((series.dataset.labels || "").split("|")[index] === "Unknown") {
+        series.querySelector(".hover-point")?.setAttribute("visibility", "hidden");
+      }
+    });
     const global = nums[Number(m[1]) - 1];
     if (global && global !== Number(m[1])) {
       tooltip.textContent = tooltip.textContent.replace(/^Request \\d+/, "Request " + global);

package/packages/cache-export/tests/e2e-browser.mjs

@@ -11,7 +11,7 @@
 // Run: node tests/e2e-browser.mjs        (from packages/cache-export)
 
 import { spawn, execFileSync } from "node:child_process";
-import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import net from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -183,6 +183,8 @@ async function run() {
   }
   const usesWindowsChrome = IS_WSL && /\.exe$/i.test(chrome);
   let windowsPid = 0;
+  let chromeProcess;
+  let cdp;
   const port = await freePort();
   const userDataDir = usesWindowsChrome
     ? commandOutput("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command",
@@ -202,7 +204,8 @@ async function run() {
       `$p = Start-Process -FilePath '${winPath}' -ArgumentList @(${quoted}) -PassThru; $p.Id`]);
     windowsPid = Number(out.trim());
   } else {
-    spawn(chrome, chromeArgs, { stdio: "ignore", detached: true }).unref();
+    chromeProcess = spawn(chrome, chromeArgs, { stdio: "ignore", detached: true });
+    chromeProcess.unref();
   }
 
   try {
@@ -212,7 +215,7 @@ async function run() {
     }
     const list = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json();
     const page = list.find((t) => t.type === "page");
-    const cdp = await cdpConnect(page.webSocketDebuggerUrl);
+    cdp = await cdpConnect(page.webSocketDebuggerUrl);
     await cdp.send("Page.enable");
     await cdp.send("Emulation.setDeviceMetricsOverride", { width: 1600, height: 1200, deviceScaleFactor: 1, mobile: false });
     await cdp.send("Page.navigate", { url: "data:text/html;charset=utf-8," + encodeURIComponent(html) });
@@ -304,11 +307,48 @@ async function run() {
       ev && ev.dataRequest === "1" && ev.info.includes("before request 25"),
       JSON.stringify(ev));
 
-    cdp.close();
+    // Exercise the actual native selector with CDP input, not a synthetic change.
+    const selectBox = await evalJs(`(() => {
+      const select = document.querySelector("[data-context-segment-select]");
+      select.scrollIntoView(); const r = select.getBoundingClientRect();
+      return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+    })()`);
+    for (const type of ["mousePressed", "mouseReleased"]) await cdp.send("Input.dispatchMouseEvent", { type, ...selectBox, button: "left", clickCount: 1 });
+    for (const [key, code] of [["Home", 36], ["Enter", 13]]) {
+      for (const type of ["keyDown", "keyUp"]) await cdp.send("Input.dispatchKeyEvent", { type, key, windowsVirtualKeyCode: code });
+    }
+    check("e2e real click/keyboard selects all-history", await evalJs(`document.querySelector("[data-context-segment-select]").value === "all"`));
+    check("e2e scope, formula, auxiliary and segment cumulative labels", await evalJs(`document.body.textContent.includes("cacheRead / (input + cacheRead + cacheWrite)") && document.body.textContent.includes("Auxiliary usage") && !!document.querySelector('[data-name="segment cumulative"]')`));
+    const plot = await evalJs(`(() => {
+      const chart = document.querySelector('[data-context-view="all"] [aria-label="Output and reasoning tokens"]');
+      chart.scrollIntoView({ block: "center" }); const r = chart.getBoundingClientRect();
+      return { x: r.x + r.width * 0.6, y: r.y + r.height * 0.6 };
+    })()`);
+    await cdp.send("Input.dispatchMouseEvent", { type: "mouseMoved", ...plot });
+    check("e2e unknown reasoning is neither a zero line nor a zero hover point", await evalJs(`(() => {
+      const series = document.querySelector('[data-context-view="all"] [data-name="reasoning"]');
+      return series.dataset.labels.split("|").every(value => value === "Unknown") &&
+        !series.querySelector(".series-line:not([visibility])") &&
+        series.querySelector(".hover-point").getAttribute("visibility") === "hidden" &&
+        document.querySelector(".usage-tooltip").textContent.includes("Unknown");
+    })()`));
+    if (process.env.CACHE_EXPORT_SCREENSHOT_DIR) {
+      mkdirSync(process.env.CACHE_EXPORT_SCREENSHOT_DIR, { recursive: true });
+      const { data } = await cdp.send("Page.captureScreenshot", { format: "png" });
+      writeFileSync(join(process.env.CACHE_EXPORT_SCREENSHOT_DIR, "unknown-reasoning.png"), Buffer.from(data, "base64"));
+      await evalJs("window.scrollTo(0, 0)");
+      const overview = await cdp.send("Page.captureScreenshot", { format: "png" });
+      writeFileSync(join(process.env.CACHE_EXPORT_SCREENSHOT_DIR, "screenshot.png"), Buffer.from(overview.data, "base64"));
+    }
+  } finally {
+    if (cdp) { await cdp.send("Browser.close").catch(() => {}); cdp.close(); }
     if (usesWindowsChrome && windowsPid) {
       try { execFileSync("taskkill.exe", ["/PID", String(windowsPid), "/T", "/F"]); } catch { /* best effort */ }
     }
-  } finally {
+    if (chromeProcess?.pid) {
+      try { process.kill(-chromeProcess.pid, "SIGTERM"); } catch (error) { if (error.code !== "ESRCH") throw error; }
+    }
+    await new Promise((resolve) => setTimeout(resolve, 300));
     if (!usesWindowsChrome) rmSync(userDataDir, { recursive: true, force: true });
   }
 }

package/packages/cache-export/tests/evidence.mjs

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import register from "../extensions/cache-export.ts";
+import { parseEntries, analyzeMisses, buildContextSegments, renderDashboard } from "../src/render.ts";
+
+const origin = Date.parse("2026-01-01T00:00:00Z");
+const iso = (seconds) => new Date(origin + seconds * 1000).toISOString();
+const usage = (read = 0, write = 0) => ({ input: 10000, cacheRead: read, cacheWrite: write, output: 100 });
+const request = (start, duration, read = 0, extraUsage = {}) => ({
+  type: "message", timestamp: iso(start + duration),
+  message: { role: "assistant", provider: "p", model: "m", api: "openai-codex-responses", timestamp: origin + start * 1000, durationMs: duration * 1000, content: [], usage: { ...usage(read), ...extraUsage } },
+});
+const misses = (data) => analyzeMisses(data.requests, data.events).misses;
+const hasTtl = (data) => misses(data).some((miss) => miss.causes.some(([cause]) => cause === "possible TTL expiry"));
+{
+  const data = parseEntries([request(0, 6, 50000), request(12, 408)]);
+  assert.equal(data.requests[1].startGapMs, 12000, "response persistence times are not request starts");
+  assert.equal(data.requests[1].idleMs, 6000);
+  assert.equal(data.requests[1].durationMs, 408000);
+  assert.equal(hasTtl(data), false);
+  assert.equal(data.requests[0].policyReferenceSeconds, null, "never assign Codex a generic five-minute TTL");
+  assert.equal(data.requests[0].reasoning, null, "unreported reasoning is unknown, not zero");
+  const html = renderDashboard(data);
+  assert.match(html, /Unknown/);
+  assert.match(html, /segment cumulative/);
+  assert.match(html, /request sequence/);
+}
+{
+  const data = parseEntries([
+    request(0, 1, 0, { cacheWrite: 50000, cacheWrite1h: 50000 }),
+    request(59 * 60, 1, 50000), request(61 * 60, 1, 50000), request(70 * 60, 1),
+  ]);
+  assert.equal(data.requests[0].policyReferenceSeconds, 3600);
+  assert.equal(data.requests[2].policyReferenceSeconds, null, "do not invent a five-minute expiry after an old one-hour write");
+  assert.equal(hasTtl(data), false, "reported reads do not reveal the server's next expiry time");
+}
+{
+  const warm = { type: "usage", kind: "cache_warm", timestamp: iso(480), provider: "p", model: "m", usage: usage(50000) };
+  const data = parseEntries([request(0, 1, 50000), warm, { type: "compaction", timestamp: iso(540), usage: usage(10) }, request(600, 1)]);
+  assert.equal(data.requests.length, 2);
+  assert.equal(data.auxiliary.length, 2);
+  assert.match(renderDashboard(data), /Auxiliary usage/);
+  const warmed = parseEntries([request(0, 1, 50000), warm, request(600, 1)]);
+  assert.equal(warmed.requests[1].lastWarmAt, origin + 480000);
+  const planned = parseEntries([request(0, 1, 50000), { type: "custom", customType: "cache_warming_decision", timestamp: iso(480) }, request(600, 1)]);
+  assert.equal(planned.auxiliary.length, 0, "preparing a warm request is not completed usage");
+  assert.equal(planned.requests[1].lastWarmAt, null);
+}
+{
+  const data = parseEntries([request(0, 1, 50000), { type: "context_edit", timestamp: iso(30) }, request(60, 1)]);
+  const segments = buildContextSegments(data.requests, data.events);
+  assert.equal(segments.length, 2);
+  const segmentMiss = analyzeMisses(segments[1].requests, data.events).misses[0];
+  assert.ok(segmentMiss.causes.some(([cause]) => cause === "context edit"));
+  assert.ok(!segmentMiss.causes.some(([cause]) => cause === "first request"), "a segment is not the session's first request");
+}
+{
+  const root = mkdtempSync(join(tmpdir(), "cache-evidence-"));
+  try {
+    const handlers = new Map(), entries = [], saved = [];
+    let command;
+    register({
+      on: (name, handler) => handlers.set(name, handler),
+      appendEntry: (customType, data) => { saved.push(data); entries.push({ type: "custom", customType, data }); },
+      registerCommand: (_name, value) => { command = value; },
+    });
+    const ctx = { cwd: root, model: { provider: "p", id: "m", api: "openai-responses", promptCache: { short: 300, long: 86400 } }, sessionManager: { getBranch: () => entries }, ui: { notify() {} } };
+    const message = request(0, 1, 50000);
+    message.message.api = "openai-responses";
+    await handlers.get("turn_start")({}, ctx);
+    await handlers.get("before_provider_request")({ payload: { prompt_cache_retention: "24h", prompt_cache_key: "PRIVATE_KEY", input: "PRIVATE_PROMPT", headers: { Authorization: "PRIVATE_TOKEN" } } }, ctx);
+    await handlers.get("message_end")({ message: message.message }, ctx);
+    entries.push(message);
+    assert.equal(saved.length, 1);
+    assert.doesNotMatch(JSON.stringify(saved), /PRIVATE|Authorization|prompt_cache_key/);
+    assert.equal(parseEntries(entries).requests[0].policyReferenceSeconds, 86400);
+    await command.handler("report.html", ctx);
+    assert.ok(readFileSync(join(root, "report.html"), "utf8").includes("cache export"));
+    assert.equal(parseEntries([message]).requests[0].policyReferenceSeconds, null, "current model configuration must never backfill old entries");
+    const longGap = request(90000, 1);
+    const crossed = parseEntries([...entries, longGap]);
+    assert.equal(hasTtl(crossed), true, "crossing an observed reference may be labeled possible, never proven");
+    assert.match(JSON.stringify(misses(crossed)), /not an idle gap or a server expiry measurement/);
+    const warm = { type: "usage", kind: "cache_warm", timestamp: iso(89990), provider: "p", model: "m", usage: usage(10000) };
+    assert.equal(hasTtl(parseEntries([...entries, warm, longGap])), false, "do not use the main-request gap as if completed warming did not occur");
+    const mixedMessage = request(100000, 1, 50000, { cacheWrite: 10000, cacheWrite1h: 5000 });
+    mixedMessage.message.api = "anthropic-messages";
+    ctx.model.api = "anthropic-messages";
+    await handlers.get("turn_start")({}, ctx);
+    await handlers.get("before_provider_request")({ payload: { messages: [{ content: [
+      { text: "PRIVATE_TEXT", cache_control: { type: "ephemeral", ttl: "5m" } },
+      { cache_control: { type: "ephemeral", ttl: "1h" } },
+    ] }] } }, ctx);
+    await handlers.get("message_end")({ message: mixedMessage.message }, ctx);
+    const mixedEvidence = entries.at(-1);
+    const later = request(104001, 1);
+    later.message.api = "anthropic-messages";
+    const mixedData = parseEntries([mixedEvidence, mixedMessage, later]);
+    assert.deepEqual(mixedData.requests[0].policy.explicitTtlsSeconds, [300, 3600]);
+    assert.equal(mixedData.requests[0].policyReferenceSeconds, null, "a partial one-hour write cannot override known mixed TTLs");
+    assert.equal(hasTtl(mixedData), false, "do not attribute the later miss to an invented whole-request TTL");
+    assert.equal(parseEntries([mixedMessage]).requests[0].policyReferenceSeconds, null, "mixed write counters alone also preclude a whole-request TTL");
+    for (const oneHourWrite of [0, 10000]) {
+      const variant = structuredClone(mixedMessage);
+      variant.message.usage.cacheWrite1h = oneHourWrite;
+      assert.equal(parseEntries([mixedEvidence, variant]).requests[0].policyReferenceSeconds, null, "known mixed policy remains unknown regardless of this response's write mix");
+    }
+    assert.doesNotMatch(JSON.stringify(saved), /PRIVATE/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+}
+console.log("PASS cache evidence: timing, unknown retention/reasoning, auxiliary usage, context edits, safe history, session cwd");