Visualize long-session tool calls in Codex HTML

Traceability

• Spec ID: codex-long-session-tool-traces
• Status: Implemented
• Depends on: docs/specs/2026-08-11-long-session-tool-call-traces.md

Intent

Give Codex users the same reviewable long-session tool-call evidence available in the Better Harness Canvas while preserving the portable HTML runtime. The HTML report should expose the privacy-safe initial request, session locator, ordered tool lanes, failures, and observed latency without requiring Canvas SDK packages, remote assets, or a host bridge.

Acceptance Scenarios

• AC-1: Codex function_call and function_call_output events with the same invocation id produce a v2 tool trace with observed transcript-pair latency.
• AC-2: Portable HTML renders each retained long-session sample as a compact metadata card with a native collapsed disclosure containing a repository-owned inline SVG swimlane bubble chart.
• AC-3: The SVG groups calls by privacy-safe tool name, orders them by step, distinguishes failures, scales bubble area by observed latency, explains missing timing, remains horizontally scrollable, and exposes accessible chart and point labels.
• AC-4: The HTML renderer keeps the initial user request and bounded session locator readable, but does not add Codex deep links, Canvas imports, raw transcript data, tool arguments, outputs, or absolute evidence paths.
• AC-5: HTML contract validation, focused renderer/session tests, full tests, packaging, and a narrow-browser Playwright preview pass.

Non-goals

• Adding a Codex Canvas runtime, native Codex panel, host bridge, or codex:// deep link.
• Changing the shared tool-trace schema, long-session selection, duration pairing rules, privacy projection, report scoring, or recommendation logic.
• Making the HTML visual byte-for-byte identical to the Qoder Canvas component.
• Adding remote JavaScript, CSS, fonts, dependencies, or runtime file reads.

Plan and Tasks

1. Add pure HTML/SVG long-session render helpers to the portable HTML renderer, reusing the existing reviewed summary.usageEfficiency.longSessions.samples projection.
2. Insert the trace cards into Project usage and add responsive, print-safe, no-JavaScript-compatible CSS for disclosure and horizontal overflow.
3. Extend HTML validation so retained trace samples require accessible, self-contained chart output with exact call counts and no host-only routes.
4. Add Codex lifecycle and HTML behavior regressions, then verify the rendered report in a narrow browser viewport.

Test and Review Evidence

• AC-1/AC-2/AC-3/AC-4: node --test test/session-analysis.test.mjs test/harness-report-render-cli.test.mjs passed 80/80 focused tests.
• AC-2/AC-3/AC-4: A real Better Harness Codex census analyzed 40 eligible sessions and retained four complete traces with 1,154, 529, 324, and 261 tool calls. The 2,268-point HTML was 725,247 bytes, rendered in 82.6 ms, passed the HTML contract, and retained all calls without truncation.
• AC-5: Headless Chrome at 640 px loaded the real report in 68.7 ms and expanded the 1,154-point chart in 82.3 ms; the 14,068 px SVG scrolled inside a 518 px card while the document stayed 640 px wide, with no console or page errors. Desktop width also had no document overflow or browser errors.
• AC-5: node --test test/doc-link-graph.test.mjs passed 6/6, npm test passed 1,313/1,313, and npm run pack:verify passed with 473 npm entries and 495 runtime zip entries.
• Privacy risk: renderer output must remain a projection of already validated fields and must escape every visible or accessible label.
• Compatibility risk: reports without samples or with legacy samples lacking a trace must remain readable and valid.
• Layout risk: complete traces can be wide; overflow must stay inside each trace card and must not widen the report viewport.