Traceable long-session tool calls

Traceability

• Spec ID: long-session-tool-call-traces
• Status: Implemented
• Source evidence: Hyperdrive commits 5696044564b28461f36f69e7b7488d62489ee1a7, 71e4fbb0e0175052406fc2d477b696ee1b001ca2, cba186974aae61927ce4b0a853c6f14801a2d3af, and 5e616f656ad5c7979b5ed31cc9789997c55242f8 from 2026-08-10

Intent

Make bounded long-session review samples traceable without exposing raw tool inputs or outputs. Reviewers should be able to expand a session sample, inspect the ordered tool-call lanes, distinguish observed latency from missing timing, and retain enough privacy-safe session metadata to locate the supporting evidence.

Acceptance Scenarios

• AC-1: Session-efficiency candidates include a deterministic, bounded tool-call trace with stable step ids, privacy-safe tool labels, observed/failed status, at most eight tool lanes, and explicit truncation metadata.
• AC-2: Matched transcript request/result and lifecycle pre/post pairs expose a bounded observed duration and timing source; unmatched, invalid, negative, or over-24-hour durations remain explicitly unobserved rather than inferred.
• AC-3: The report projection retains only allowlisted trace and session-locator fields, validates both the previous v1 trace and the new v2 timing contract, and rejects raw or malformed timing data.
• AC-4: The Better Harness Canvas renders each long-session trace in a collapsible section, groups calls into bounded lanes, visualizes only observed latency through a repository-owned SVG component that works without the newer Canvas SDK chart export, explains incomplete timing coverage, and wraps long metadata without overflowing its cards.
• AC-5: Focused session-analysis, report-source, report-contract, and Canvas validation tests pass without changing the existing review-trigger work in the local worktree.

Non-goals

• Persisting raw tool arguments, results, prompts, transcript bodies, or unredacted session identifiers in the report.
• Estimating duration when the source does not provide a trustworthy matching lifecycle pair.
• Changing long-session thresholds, candidate ranking, report scoring, package versions, changelogs, or host support declarations.
• Copying Hyperdrive's legacy Qoder-only paths or Canvas filenames into the current Better Harness architecture.

Plan and Tasks

1. Reimplement the tool-call trace builder under the current scripts/session-analysis/ owner and attach it only to selected session-efficiency candidates.
2. Extend current lifecycle deduplication and the Qoder platform adapter so trustworthy source durations survive normalization.
3. Sanitize and project the trace through task-loop-source, then validate the versioned contract in task-loop-report.
4. Adapt the trace UI to the canonical Better Harness Canvas template and its validator, preserving current renderer ownership and embedding the smallest compatible subset of ../canvas-sdk's swimlane bubble layout locally.
5. Port behavior-focused fixtures and tests, then run focused and full validation appropriate to the touched owners.

Test and Review Evidence

• AC-1/AC-2: node --test test/session-analysis.test.mjs test/task-loop-source.test.mjs passed as part of 74 focused tests.
• AC-3/AC-4: node --test test/harness-canvas-validation.test.mjs test/task-loop-report.test.mjs passed as part of 98 focused tests.
• AC-4: A 640 px Playwright preview rendered the local SVG with 12 calls, horizontal overflow containment, no console/page errors, and successful /health and /canvas-module.js responses.
• AC-5: node --test test/doc-link-graph.test.mjs passed 6/6; npm test passed 1297/1297; npm run pack:verify passed with 469 npm entries and 491 runtime zip entries.
• Review risk: lifecycle pairing can misattribute latency when invocation ids are missing or duplicated; tests must cover unmatched and ambiguous sequences.
• Privacy risk: report and Canvas projection must remain an allowlist and must reject tool arguments, outputs, raw evidence references, and uncontrolled labels.
• Compatibility risk: existing v1 trace packets must remain valid while new packets use v2.