Prompt-cache TTL cues in idle windows

Traceability

• Spec ID: inspector-idle-cache-ttl-cues
• Status: Implemented

Intent

Help a reviewer notice when a long interval inside a tool-call idle window may have crossed the prompt-cache lifetime used by the selected model policy. The timeline must remain compact: it exposes the pricing-risk state with a thin warning-colour top border, while a separate docked policy pane owns model, retention, pricing-basis, and official-source detail.

Provider policies are mutable reference data rather than report evidence. The report selects the best matching profile from the observed provider and model, lets the reader choose another reference profile, links every row to the provider's official documentation, and explicitly tells the reader to prefer the latest official policy. A model response observed inside an idle window resets the elapsed interval used by the cue because it is evidence of another inference in that otherwise tool-free span.

Acceptance Scenarios

• AC-1: An observed-time idle window whose longest interval without an observed model response reaches the selected profile's comparable TTL displays a 3px warning-colour border on the top edge only. The idle label remains unchanged and contains no cache or pricing copy.
• AC-2: Prompt-cache policy is represented by a deterministic model containing provider/model matching, cache mode, TTL/retention, pricing basis, official documentation URL, and whether the TTL is comparable. Unknown or unpublished TTLs do not produce a timeline cue.
• AC-3: A docked policy pane below the full chart shows the current reference, three rows by default, official links for every profile, a latest-policy notice, and a disclosure for the remaining profiles. Compact Turn charts do not repeat the pane.
• AC-4: The chart description, idle tooltip, policy notice, and visible legend explain that the boundary indicates a possible loss of lower cache-read pricing. They do not claim observed cache expiry, a cache miss, a price, or billed savings.
• AC-5: Call-sequence charts, gaps below the applicable TTL, and gaps split by observed model responses into shorter intervals do not display the cue.
• AC-6: The selected-event detail, Session View action, call statistics, and chart legends occupy one non-wrapping docked status row instead of four lines. It uses bounded horizontal overflow where the viewport cannot fit every item, and shows no instructional placeholder before an event is selected.
• AC-7: The cue, policy pane, links, selector, disclosure, and status row remain usable at wide, compact, and narrow layouts with visible keyboard focus and no document-level horizontal overflow. The expanded activity disclosure keeps Open session and focus view on the same header row.

Non-goals

• Estimating provider charges, savings, or cache hit probability.
• Proving the cache write time, expiry time, cache key, hit, miss, or retention configuration used by a provider request.
• Changing prompt-caching configuration or choosing a TTL for the user.
• Adding another timeline lane or changing idle-window compression.
• Fetching or refreshing provider policy data over the network from a generated report; the links and latest-policy notice keep mutable facts reviewable.

Plan and Tasks

1. Add a portable prompt-cache profile model and deterministic resolver outside the UI renderer; embed the same serializable data and functions in the self-contained Inspector document.
2. Compare idle gaps only with the selected profile's comparable TTL and render a warning-colour SVG line on the gap's top edge without changing its label.
3. Add a docked policy pane with the observed reference, selector, compact table, disclosure, official links, and latest-policy notice.
4. Replace the existing chart inspector and multi-line legend footer with one status row that retains selection detail, Session View navigation, summary, and redundant text/icon legends.
5. Add focused behavior tests for profile resolution, provider boundaries, unpublished TTLs, response resets, generated links, and compact markup.
6. Render a real local Inspector report, exercise policy selection and Session navigation in a browser, inspect console/page errors, and capture wide, compact, and narrow evidence.

Test and Review Evidence

• AC-1 through AC-6: npx vitest run test/reporting/harness-inspector-cache-gap.test.mjs test/reporting/harness-inspector-timeline-scale.test.mjs test/reporting/harness-inspector.test.mjs test/reporting/harness-inspector-demo.test.mjs test/reporting/harness-inspector-commit-compaction.test.mjs test/skills-docs/doc-link-graph.test.mjs passed 60 tests in 6 files.
• AC-2/AC-3/AC-4/AC-6: the generated Inspector report retains all seven official policy links, shows three model rows by default, expands to seven, keeps the latest-policy notice visible, and renders one chart status row.
• AC-1/AC-3/AC-6/AC-7: npm run inspector:visual-check passed 18 surfaces at 1440 by 900, 1024 by 768, and 390 by 844. The check exercised model selection, profile disclosure, event focus, and the Session View action, with zero document overflow, clipped controls, console errors, or page errors.
• AC-7: npm run preview returned HTTP 200 for /health and /canvas-module.js.
• Risk: tool-call timing and model-response timing are observed evidence, but provider cache storage is not. All user-facing copy must preserve that distinction.