Pipeline Execution Time-Travel Debugger with Event Replay and State Inspector

[github-actions]

Strategic Improvement

When pipelines fail, developers need to understand what happened. Build replay debugger that reconstructs pipeline execution from events.jsonl, allows stepping through stages, inspecting context/state at any point, and comparing successful vs failed runs. Reduces MTTR from 2h → <30min target.

Acceptance Criteria

• CLI command shipwright replay <pipeline-id> loads event stream and reconstructs execution timeline
• Interactive TUI shows: stage progression, context window state, decisions made, git state snapshots
• Step forward/backward through events, inspect variables/files at each point
• Diff mode compares two pipeline runs (e.g., successful vs failed) side-by-side
• Export mode generates markdown execution narrative for sharing/debugging
• Integration with dashboard for web-based replay viewer

Context

• Priority: P1
• Complexity: standard
• Generated by: Strategic Intelligence Agent
• Strategy alignment: P1: Developer Experience + P4: Observability & Metrics

[github-actions]

⚓ Shipwright Pipeline Starting

Field	Value
Template	standard
Complexity	standard
Max Iterations	20
Triage	Directly advances observability/DX mission; extends existing sw-replay.sh infrastructure with TUI interactivity, diff comparison, and dashboard integration—moderate architectural scope with clear acceptance criteria.
Runner	ubuntu-latest
Risk Level	unknown
Workflow	25594975553

The autonomous pipeline is processing this issue. Updates will be posted as stages complete.

[github-actions]

[github-actions]

[github-actions]

[github-actions]

📋 Implementation Plan

Click to expand full plan (34 lines)

Here is the implementation plan for the Pipeline Execution Time-Travel Debugger:

---

Plan Summary

What exists: sw-replay.sh has batch CLI subcommands (list/show/narrative/diff/export/compare) but no interactive mode. The dashboard has WebSocket + REST infrastructure but no replay tab.

What we build:

Shell Script (scripts/sw-replay.sh)

1. cmd_step() — New interactive TUI with stty raw mode + arrow key navigation. Loads events for a pipeline, renders them one at a time with stage progression bar, event payload details, token counts. Arrow keys / n/p / g/G for navigation; q to quit; e to export current event. TTY guard prevents misuse in CI.
2. Bare <id> routing — shipwright replay 487 routes to the new interactive TUI
3. Enhanced cmd_diff() — True stage-by-stage side-by-side comparison (replaces the current git-log stub)
4. Enhanced cmd_export() — Adds --output <file> flag with atomic write (mktemp + mv)

Dashboard (dashboard/server.ts + frontend)

5. GET /api/replay/:issue — Sorted event stream (up to 1000 events, ts_epoch ASC)
6. GET /api/replay/compare/:issue1/:issue2 — Stage events for both runs
7. New replay tab — TypeScript view with issue input, scrubber/playhead, stage-chip progression bar, event JSON viewer, play/pause auto-advance, browser-side Markdown export

Tests (scripts/sw-replay-test.sh + sw-server-api-test.sh)

8. New bash tests for step, enhanced diff, export-to-file, bare-id routing
9. New API endpoint tests for replay endpoints

Key Design Decision

Bash TUI over TypeScript TUI (ink/blessed) — consistent with all other scripts, zero new dependencies, blast radius limited to 6 files.

Risk Mitigations

• TTY detection before stty -g to prevent CI breakage
• trap 'stty "$old_tty"' EXIT INT TERM always restores terminal
• /api/replay/compare/... checked before /api/replay/:issue in server routing to prevent regex collision
• escapeHtml() on all user data in innerHTML to prevent XSS
• Event loading capped at 1000 to prevent memory pressure

---

Generated by shipwright pipeline at 2026-05-09T07:24:40Z

[github-actions]

[github-actions]

📐 Architecture Decision Record

Click to expand ADR (596 lines)

Design: Pipeline Execution Time-Travel Debugger with Event Replay and State Inspector

Context

Problem Statement:
Developers need to understand what happened in a pipeline execution—why did stage X fail? What was the system state at point Y? Currently, sw-replay.sh has batch commands but no interactive way to step through events, inspect state at each point, or compare runs side-by-side. This makes debugging slow, especially for 100+ event logs.

Constraints:

1. Consistency: All Shipwright tools are bash scripts. No new runtime dependencies (no Node.js TUI frameworks like Ink/Blessed).
2. Terminal Safety: Must work in CI/CD (no TTY), local dev (TTY present), and piped contexts without corruption.
3. Performance: 1000-event logs must navigate with <100ms latency per step.
4. Schema Evolution: Old event logs with missing fields must remain readable. Forward/backward compatibility required.
5. Security: Dashboard ingest event JSON—all rendering must prevent XSS.
6. Isolation: Changes confined to replay module; minimal integration with core pipeline/daemon.

Existing Assets:

• scripts/sw-replay.sh (batch commands: list, show, narrative, diff, export, compare)
• Event log at ~/.shipwright/events.jsonl (newline-delimited JSON)
• Database layer (sw-db.sh) with SQLite
• Dashboard infrastructure (TypeScript React, WebSocket ready)

---

Decision

Chosen Architecture

┌──────────────────────────────────────────────────────┐
│  User Interaction Layer                              │
│  ├─ CLI: Interactive TUI (stty raw mode + bash)     │
│  └─ Web: Dashboard tab (React TypeScript)            │
├──────────────────────────────────────────────────────┤
│  Command/Endpoint Layer                              │
│  ├─ Shell: cmd_step(), cmd_diff(), cmd_export()    │
│  └─ REST: GET /api/replay/:issue, /compare, POST   │
├──────────────────────────────────────────────────────┤
│  Event Processing Layer                              │
│  ├─ Event Stream Loader (query DB/JSONL)            │
│  ├─ Event Deserializer (parse JSON + version)       │
│  └─ State Reconstructor (rebuild @ any index)       │
├──────────────────────────────────────────────────────┤
│  Persistence Layer                                   │
│  └─ ~/.shipwright/events.jsonl + SQLite (existing)  │
└──────────────────────────────────────────────────────┘

Data Flow (TUI):

User: "shipwright replay 487"
  ↓ [cmd_step routes bare ID]
  ↓ load_events(487) → Event[]
  ↓ reconstruct_state(events, 0) → State
  ↓ render_event(state) → screen
  ↓ [User presses 'j']
  ↓ update current_index++
  ↓ reconstruct_state(events, 2) → State
  ↓ render_event(state) → screen

---

Generated by shipwright pipeline design stage at 2026-05-09T07:27:59Z

[github-actions]

[github-actions]

🔨 Build started — shipwright loop with 20 max iterations, 1 agent(s), model: haiku

[github-actions]

[github-actions]