# Replay retained session evidence

## Traceability

- Spec ID: inspector-session-replay
- Status: Draft

## Intent

Let a reviewer play through one retained coding-agent session without leaving
the Inspector's existing evidence model. Session View should keep its current
chronological Trace and add a Replay mode that synchronizes a current-event
stage, an event/file index, a compact timeline, and playback controls.

Replay is a read-only presentation of the sanitized report projection. It does
not rerun tools, restore a worktree, resume a native host session, or invent
timestamps for content whose time was not observed.

## Acceptance Scenarios

- AC-1: `Open session` exposes semantic `Trace` and `Replay` tabs. Trace remains
  the default, and a URL with `view=session&session-mode=replay` restores Replay
  for the named session.
- AC-2: Each projected session owns a `SessionReplay` model, without a version
  suffix in its name. It deterministically projects retained prompts,
  intermediate responses, tool calls, final responses, and directly linked
  commits from the already-sanitized report model.
- AC-3: Every replay event declares its timing basis. Observed prompt, tool, and
  commit timestamps may appear on the wall-clock rail; response boundaries may
  be labelled as Turn-bound; intermediate responses and other untimed content
  remain `sequence-only` and are never assigned an invented clock time.
- AC-4: Selecting an event updates the current-event stage, the event index, the
  compact timeline cursor when timing exists, and the Inspector selection when
  the event has a Story, Session, Turn, Tool Call, File, or Commit descriptor.
  Existing Evidence Drawer relationships and limitations remain authoritative.
- AC-5: Replay provides previous, play/pause, and next controls plus 1x, 2x, 4x,
  and 8x event pacing. Playback advances by retained event order, compresses
  long unobserved gaps instead of making multi-hour sessions wait in real time,
  stops at the end, and never invokes a host tool.
- AC-6: Replay exposes `Events` and `Files` index tabs. Choosing a file selects
  that repository-relative path and moves to the first retained replay event
  that names it, without claiming the event authored a commit.
- AC-7: The mode tabs, index tabs, event rows, file rows, playback buttons, and
  speed controls are keyboard operable; the current event uses non-color state
  cues, playback respects reduced-motion preference, and controls do not steal
  shortcuts from form inputs.
- AC-8: The self-contained HTML retains no raw tool input/output, hidden
  reasoning, absolute home path, or credential. Missing content and unavailable
  timing stay explicit in the model and UI.
- AC-9: Focused behavior tests cover `SessionReplay` ordering and timing bases,
  direct-commit inclusion, untimed fallbacks, mode restoration, playback
  controls, and final HTML privacy. A real multi-hour local session is verified
  in desktop and narrow browser layouts with no page or console errors.

## Non-goals

- Adding Replay as a top-level Inspector scope beside Delivery Tree and Date.
- Executing, retrying, resuming, or mutating a tool call, Git state, worktree,
  feature-tree mapping, checkpoint, or native host session.
- Human annotations, pinned notes, author identity, or report persistence.
- Fabricating cost, token, test-result, response, or timing evidence that the
  source projection did not retain.
- Replacing Trace, the Evidence Drawer, or the existing wall-clock activity
  chart with a second relationship model.

## Plan and Tasks

1. Extend `scripts/harness-inspector/report-model.mjs` with a bounded
   `SessionReplay` projection built only after Session/Commit links exist.
   Preserve explicit timing bases and direct-commit limitations.
2. Extend `scripts/harness-inspector/ui/workbench.js` with a session-local
   playback owner separate from evidence selection and chart zoom. Render
   Trace/Replay tabs, the event stage, Events/Files index, compact rail, and
   playback controls from the projected model.
3. Extend `scripts/harness-inspector/ui/workbench.css` with responsive Replay
   layout and accessible selected/focus treatments that reuse current Inspector
   tokens and typography.
4. Extend focused Inspector tests with behavior assertions over the model and
   rendered interactions. Preserve unrelated working-tree changes in the same
   files and keep the report self-contained.
5. Render a real report, exercise mode switching, event/file selection,
   playback, speed, URL restoration, Trace return, keyboard behavior, desktop
   and narrow layouts, then inspect console/page errors.

## Test and Review Evidence

- AC-2/AC-3/AC-8: `npx vitest run test/reporting/harness-inspector.test.mjs`
  asserts the parsed model shape, event ordering, timing bases, direct commits,
  and sanitized projection rather than matching implementation source text.
- AC-1/AC-4..AC-7: browser behavior against a real self-contained report,
  including a copied Replay deep link and an event with no observed timestamp.
- AC-9 regression: `npm test`, `npm run pack:verify`, documentation link graph,
  and a Review Readiness Check over the final local/staged split.
- Privacy risk: Replay consumes only projected safe text and repository-relative
  paths; final HTML is checked for private-path and credential leakage.
- Correlation risk: only explicit or observed-commit relationships enter the
  replay stream. Same-path and contextual commits stay in Trace/Evidence.
- Scale risk: the index is event-driven and the compact rail renders timed
  events only; playback advances by event pace so long idle windows do not block
  review.
- Interaction risk: Replay state is session-local and URL-addressable, while
  Evidence selection and activity zoom remain separate owners.

## Replay Legibility Follow-up

Deep-linking to a mid-session event (`replay-event=call:A179`) exposed six
legibility defects, since fixed and verified in-browser against a real
multi-hour local session with no console or page errors:

- AC-4 follow-up: `updateReplayPresentation` now keeps the current event row in
  view inside the index's own scroller only, so following playback never scrolls
  Session View or the Workbench underneath it, and a tab return re-reveals it.
- AC-7 follow-up: the current row uses a stronger non-color cue (heavier bar,
  bold title) in addition to background, and the mode tabs (filled) read
  distinctly from the index tabs (underlined).
- Layout: the index column tracks layout width instead of the viewport and keeps
  its own readable height, so a narrow window or open Drawer narrows the column
  rather than stacking it where the sticky transport would cover the list. The
  event card no longer reserves a tall fixed height that dwarfed short evidence.
- AC-8 follow-up: a bounded (clipped) projection body is flagged `bodyExcerpt`
  and shown as an `Excerpt` badge instead of a silently truncated command.
- Orientation: the timeline rail gains a type legend, and duplicated position and
  timing text collapses to one `Event N / total` label plus the card's Turn line.
- Overlay: the root scroller locks while Session View is open so wheel gestures
  cannot scroll the hidden Workbench.