feat: stream replay viewer runs live

[osolmaz]

Summary

• add a filesystem-backed replay viewer live source plus a WebSocket snapshot/patch transport for the recent-runs index and active recent-run bundle
• keep live run state close to the existing loaded bundle shape, merge live.json over stale run.json, and preserve rewind behavior while new steps append
• document the live transport design and add replay viewer tests for live summaries, live patch streaming, and live-edge playback following

Validation

• pnpm run format:check
• pnpm run typecheck
• pnpm run lint
• pnpm run build
• pnpm run viewer:typecheck
• pnpm run viewer:build
• pnpm run test
• pnpm run check:docs
• pnpm run build:test && node --test dist-test/test/replay-viewer-run-bundles.test.js dist-test/test/replay-viewer-view-model.test.js dist-test/test/replay-viewer-live-sync.test.js
• pnpm run build:test && node --test dist-test/test/replay-viewer-live-sync.test.js && pnpm run viewer:typecheck
• smoke checks: pnpm run viewer:preview, curl http://127.0.0.1:4173/api/runs, and a Node ws client against ws://127.0.0.1:4173/api/live

Local caveat

• pnpm run check still fails only at test:coverage under local Node v24.1.0 because the built-in coverage runner reports the same bogus global coverage percentages this repo already sees locally even when all 444 tests pass. CI remains the real coverage gate because the repo’s coverage lane runs on Node 22.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2ef109f1f1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[osolmaz]

Final report:

• Added live replay viewer sync over /api/live with WebSocket runs_snapshot/run_snapshot plus JSON Patch+ updates, so the recent-runs sidebar and the selected recent run now update while a run is still in progress.
• Kept the live browser state close to the existing loaded bundle shape so rewind still works while new steps, trace, and ACP session content arrive.
• Streamed selected-run ACP conversation growth through the same transport, including JSON Patch+ append updates for growing assistant text.
• Removed the old replay viewer footer buttons and changed the empty state so the viewer now waits for real recent runs and auto-opens the first one that appears.
• Added first-class local viewer scripts: pnpm viewer, pnpm viewer:open, pnpm viewer:status, and pnpm viewer:stop.
• Hardened the viewer against the review findings and follow-on races:
  • fixed bootstrap churn from live recent-runs updates
  • preserved live ACP turn context after reconnect/resync
  • rejected reusing a running viewer when --runs-dir points somewhere else
  • ignored stale recent-run loads when a newer live selection wins
  • refreshed runs snapshots from source so a new sidebar subscriber does not get a stale cached snapshot after idle periods

Validation run locally:

• export PATH=/Users/onur/.nvm/versions/node/v24.1.0/bin:$PATH && pnpm install ✅
• export PATH=/Users/onur/.nvm/versions/node/v24.1.0/bin:$PATH && pnpm run build:test && node --test dist-test/test/replay-viewer-loader.test.js dist-test/test/replay-viewer-live-run-state.test.js dist-test/test/replay-viewer-live-sync.test.js dist-test/test/replay-viewer-server.test.js ✅
• export PATH=/Users/onur/.nvm/versions/node/v24.1.0/bin:$PATH && pnpm run build:test && node --test dist-test/test/replay-viewer-live-sync.test.js dist-test/test/replay-viewer-loader.test.js dist-test/test/replay-viewer-live-run-state.test.js dist-test/test/replay-viewer-server.test.js ✅
• export PATH=/Users/onur/.nvm/versions/node/v24.1.0/bin:$PATH && pnpm run viewer:typecheck ✅
• export PATH=/Users/onur/.nvm/versions/node/v24.1.0/bin:$PATH && pnpm run format:check ✅
• export PATH=/Users/onur/.nvm/versions/node/v24.1.0/bin:$PATH && pnpm run test ✅ (460 passing, 0 failing)
• real websocket smoke against the live viewer transport ✅
  • verified runs_snapshot/run_snapshot
  • verified run_patch with JSON Patch+ append ops for live ACP text
• real viewer smoke with a running example flow ✅
  • started pnpm viewer
  • ran examples/flows/two-turn.flow.ts
  • confirmed new run auto-appeared in the left sidebar as running
  • confirmed selected run updated through completion
• simulated live updates against an existing saved run bundle shape ✅
  • cloned a real run bundle
  • mutated live.json / steps.json
  • verified sidebar and selected-run updates over /api/live

Codex review:

• The original Codex GitHub P1 about refreshRuns churn was fixed and its thread is resolved.
• I reran local codex review --base main multiple times on the latest branch head. Those reruns surfaced the stale recent-run load race and the stale idle snapshot problem, both fixed on this branch.
• After those fixes, the local reviewer did not emit any further P0/P1 findings, but the tool itself hit an internal router/test-invocation bug (write_stdin failed: stdin is closed plus bad focused-test commands like pnpm test -- replay-viewer). No new GitHub review comments were posted on the current head.

CI:

• GitHub checks on 9c72a55df4142c19d975558778e53d2a0fb7c4b6 are green: Build, Conformance Smoke, Docs, Format, Lint, Test, Typecheck, and scope ✅

What I could not fully test locally:

• no staging or production verification
• no split-server deployment verification yet
• pnpm viewer:open was not exercised from automation to avoid forcing a browser launch

This PR is ready for merge from my side.

[osolmaz]

The Blacksmith failure note at #205 (comment) is outdated now. That websocket test failure was fixed on this branch and the current PR head 9c72a55df4142c19d975558778e53d2a0fb7c4b6 is green across Build, Conformance Smoke, Docs, Format, Lint, Test, Typecheck, and scope.