headquarter/openspec/changes/responsive-terminal/tasks.md

Tasks: Responsive Web Terminal

Review Workload Forecast

Task	Estimated Lines	Stack	Risk
T1: Protocol types + utilities	~120	Frontend	Low
T2: Backend heartbeat + batching	~200	Backend	Medium
T3: Backend echo detection + graceful exit	~150	Backend	Medium
T4: useTerminalConnection hook	~280	Frontend	High
T5: TerminalComponent rewrite	~250	Frontend	High
T6: Frontend tests	~180	Frontend	Low
T7: Backend tests	~120	Backend	Low
Total	~1,300

Review recommendation: This exceeds the 400-line budget. Split into 3 chained PRs:

1. PR-1 (Backend foundation): T1 protocol types + T2 heartbeat/batching + T3 echo/exit + T7 backend tests (~590 lines)
2. PR-2 (Frontend connection): T4 useTerminalConnection hook + T6 frontend hook tests (~460 lines)
3. PR-3 (Terminal UI + integration): T5 TerminalComponent rewrite + page integration + remaining tests (~250 lines)

---

Task T1: Protocol Types and Utilities

Files:

• apps/web/src/types/terminal.ts (new)
• apps/web/src/utils/terminal-protocol.ts (new)
• apps/web/package.json (add xterm-addon-serialize)

Description: Define TypeScript types for all WebSocket control messages. Implement encode/decode helpers that distinguish binary frames (raw terminal I/O) from JSON text frames (control messages). Add base64 encoding for the input control message type. Install xterm-addon-serialize dependency.

Acceptance:

• All message types from the design spec are represented as TypeScript types
• encodeControlMessage and decodeControlMessage functions handle JSON serialization
• isControlMessage helper correctly identifies text vs binary frames
• npm install completes without lockfile conflicts

Depends on: None Estimated: 2 hours

---

Task T2: Backend Heartbeat and Message Batching

Files:

• apps/api/src/services/terminal_manager.py
• apps/api/src/api/terminal.py

Description: Rewrite TerminalManager read loop to batch small reads into single WebSocket frames (max 16ms buffering). Add heartbeat tracking: server records last_client_message_at timestamp, and a background task closes WebSockets idle for 60s. Update terminal.py endpoint to accept ping control messages and respond with pong. Handle binary input frames (not just text JSON).

Acceptance:

• Backend sends batched binary frames; yes | head -n 10000 produces fewer WebSocket frames than before
• Server responds to ping with matching pong within 100ms
• Server closes idle connections after 60s of no client messages
• Backend accepts both binary and text WebSocket frames for input
• make test passes (existing backend tests still green)

Depends on: None Estimated: 3 hours

---

Task T3: Backend Echo Detection and Graceful Exit

Files:

• apps/api/src/services/terminal_session.py
• apps/api/src/services/terminal_manager.py
• apps/api/src/api/terminal.py

Description: Add termios PTY inspection to detect ECHO flag state changes. Send set_echo_state control messages to client when echo toggles. Detect container process exit (returncode set) and send session_ended JSON message before closing WebSocket with code 1000. Distinguish between normal process exit, container stop, and unexpected errors.

Acceptance:

• Running stty -echo in terminal triggers set_echo_state: false message
• Running stty echo triggers set_echo_state: true message
• Running exit in shell sends session_ended: { reason: "process_exit" } then closes with code 1000
• Stopping container sends session_ended: { reason: "container_stop" }
• Unexpected errors still close with code 4000 and error message

Depends on: T2 Estimated: 2.5 hours

---

Task T4: useTerminalConnection Hook

Files:

• apps/web/src/hooks/use-terminal-connection.ts (new)

Description: Implement the core connection hook with: WebSocket lifecycle (open/close/reconnect with exponential backoff), heartbeat (send ping every 15s, timeout after 5s), local echo (write printable ASCII to xterm immediately, deduplicate server echo), resize debouncing (200ms, max 1/500ms), scrollback serialization on disconnect, scrollback restoration on reconnect, connection quality tracking (latency, jitter), manual reconnect bypass.

Acceptance:

• Hook exposes state, sendInput, sendResize, reconnect, onData, onControl
• Reconnect backoff: 1s, 2s, 4s, 8s, then max 30s
• Max 10 reconnection attempts before giving up
• Local echo works for printable ASCII; disabled when echo state is false
• Pending echo buffer deduplicates server echo correctly
• Pending echo buffer flushes to terminal if it grows > 100 chars
• Resize sends at most 1 message per 500ms
• Ctrl+Shift+R triggers immediate reconnect when disconnected
• Scrollback serialized to sessionStorage on disconnect, restored on reconnect with divider

Depends on: T1 Estimated: 4 hours

---

Task T5: TerminalComponent Rewrite

Files:

• apps/web/src/components/terminal.tsx (rewrite)
• apps/web/src/pages/terminal.tsx (minor)
• apps/web/src/styles.css (add terminal status styles)

Description: Rewrite TerminalComponent to use useTerminalConnection. Integrate xterm.js with the hook's onData and onControl callbacks. Add status bar with connection quality indicator (green/yellow/red/gray dot, latency tooltip, attempt counter). Add reconnect overlay when disconnected. Wire xterm onData to hook's sendInput. Use ResizeObserver for container-level resize detection. Apply xterm-addon-serialize for scrollback. Update page to pass instance ID and handle close.

Acceptance:

• Terminal renders and connects on mount
• Status bar shows correct dot color based on connection state
• Hovering dot shows latency tooltip
• Reconnect overlay appears when max retries exceeded
• ResizeObserver triggers fit + resize message (debounced)
• Theme colors adapt to dark/light mode
• Close button works

Depends on: T4 Estimated: 3 hours

---

Task T6: Frontend Tests

Files:

• apps/web/src/utils/terminal-protocol.test.ts (new)
• apps/web/src/hooks/use-terminal-connection.test.ts (new)

Description: Write Vitest tests for protocol utilities (encode/decode all message types, base64 round-trip, frame type detection). Write tests for the connection hook using a mock WebSocket server (or manual mock). Test: reconnect backoff timing, heartbeat timeout detection, local echo deduplication, resize throttling, scrollback serialization round-trip.

Acceptance:

• Protocol tests cover all message types and edge cases
• Hook tests cover connection lifecycle without real WebSocket
• All tests pass: cd apps/web && npm test
• Coverage for new code > 80%

Depends on: T1, T4 Estimated: 3 hours

---

Task T7: Backend Tests

Files:

• apps/api/tests/unit/test_terminal_session.py (new)
• apps/api/tests/unit/test_terminal_manager.py (new)

Description: Write pytest unit tests for TerminalSession (PTY creation, resize, echo detection, process exit detection). Write tests for TerminalManager (session creation, batching logic, heartbeat tracking). Use mocks for os, pty, termios, and asyncio where appropriate.

Acceptance:

• TerminalSession tests: start, resize, write, read, echo detection, close
• TerminalManager tests: create session, read loop batching, heartbeat timeout
• All tests pass: make test

Depends on: T2, T3 Estimated: 2.5 hours

---

Task Order and Dependencies

T1 ──► T4 ──► T5 ──► PR-3 (Frontend UI)
        │
        └──► T6 (Frontend tests)

T2 ──► T3 ──► PR-1 (Backend foundation)
        │
        └──► T7 (Backend tests)

Parallel work possible:

• T1 and T2 can be done in parallel (no dependencies)
• T3 and T4 can be done in parallel (T3 depends on T2, T4 depends on T1)
• T5 depends on T4
• T6 depends on T4
• T7 depends on T3

Chained PR Plan

PR-1: Backend Foundation

Scope: T1 (protocol types only) + T2 + T3 + T7 Files touched: apps/api/src/services/terminal_manager.py, apps/api/src/services/terminal_session.py, apps/api/src/api/terminal.py, new test files, apps/web/src/types/terminal.ts, apps/web/src/utils/terminal-protocol.ts Estimated diff: ~590 lines Review focus: Protocol correctness, heartbeat logic, batching efficiency

PR-2: Frontend Connection Hook

Scope: T4 + T6 Files touched: apps/web/src/hooks/use-terminal-connection.ts, new test files Estimated diff: ~460 lines Review focus: State machine correctness, local echo algorithm, reconnection logic

PR-3: Terminal UI Integration

Scope: T5 Files touched: apps/web/src/components/terminal.tsx, apps/web/src/pages/terminal.tsx, apps/web/src/styles.css Estimated diff: ~250 lines Review focus: UX, accessibility, visual polish, integration with hook

Note: PR-2 and PR-3 can be developed in parallel if PR-1's protocol types are stable. The hook can be tested against mock protocol types before the backend is merged.