Epic: PTY execution backend and web terminal support

[geoffjay]

Overview

Add a PtyBackend as a new ExecutionBackend implementation alongside TmuxBackend and DockerBackend, using the portable-pty crate. This removes the tmux dependency for environments that lack it, enables web terminal (xterm.js) functionality in the UI, and provides direct programmatic process management.

Parent research issue: #659

Motivation

The current tmux-based approach has several limitations identified in #659:

• No way to use tmux's built-in tools/commands from the orchestrator
• Attaching to a tmux session running Claude in SDK mode shows raw NDJSON, not useful for humans
• tmux is an external binary dependency that may not be available in all environments
• No web terminal capability for the UI

Architecture

The ExecutionBackend trait in crates/wrap/src/backend.rs already abstracts session management. A PtyBackend implements this trait with:

• portable-pty for cross-platform PTY spawning
• Async adaptation via tokio::task::spawn_blocking (same pattern as TmuxBackend)
• I/O stream capture for web terminal relay
• Session lifecycle management (spawn, health check, kill)

Feature Scope

Core Backend

• Spike: validate portable-pty for agent session management #672 - Spike: validate portable-pty for agent session management
• Implement PtyBackend for ExecutionBackend trait #673 - Implement PtyBackend for ExecutionBackend trait
• PTY session I/O capture and streaming infrastructure #674 - PTY session I/O capture and streaming infrastructure

Web Terminal (UI)

• Add PTY stream relay endpoint to orchestrator #675 - Add PTY stream relay endpoint to orchestrator
• xterm.js web terminal component for agent sessions #676 - xterm.js web terminal component for agent sessions

CLI Integration

• CLI backend selection and PTY session management commands #677 - CLI backend selection and PTY session management commands

Cross-cutting

• Backend selection configuration and documentation #678 - Backend selection configuration and documentation

Dependency Graph

#659 (research consensus)
  └─► #672 (spike: validate portable-pty)
        └─► #673 (PtyBackend implementation)
              ├─► #674 (I/O capture & streaming)
              │     └─► #675 (orchestrator relay endpoint)
              │           └─► #676 (xterm.js web terminal)
              └─► #677 (CLI integration)
              └─────────────────────────────►  #678 (configuration & docs)
                                                 ▲
                    #676 ────────────────────────┘
                    #677 ────────────────────────┘

Key Decisions

1. Supplement, don't replace: tmux remains the default backend; PTY is opt-in via AGENTD_BACKEND=pty
2. Library choice: portable-pty (0.9.0) — most mature, cross-platform, actively maintained (wezterm project)
3. Web terminal supplements logs: The existing AgentLogView (structured, timestamped, searchable) stays; xterm.js is offered as an additional "Terminal" tab
4. Cost/usage tracking unchanged: Already flows through WebSocket protocol, not terminal output

Dependencies

• portable-pty crate (0.9.0)
• @xterm/xterm npm package (for UI)
• crossterm crate (for CLI attach)
• Existing ExecutionBackend trait (no changes needed to trait definition)

Acceptance Criteria

• PtyBackend passes all existing ExecutionBackend contract tests
• Agent sessions can be spawned, monitored, and terminated via PTY
• Web terminal displays live agent output in the UI
• CLI can attach to PTY sessions interactively
• tmux remains the default; PTY is opt-in
• Works on macOS and Linux
• Configuration documented with backend comparison