# Ratatui TUI PTY Regression Design

audience: AI coding agents first

## Goal

Fix `bin/runplan` argument safety and add executable PTY coverage for the shipped TUI.

## Design

- Keep `bin/runplan` as the single argument-normalization boundary. Launch the TUI when invoked without arguments, and guard every positional read under `set -u`.
- Exercise the release binary through `script(1)` so crossterm receives a real PTY. Use a per-test TCP fixture implementing the control-api HTTP/SSE contract and per-child `HOME` files for port/token discovery.
- Add terminal cleanup as an owned runtime guard. Normal exit and unwinding restore raw mode, mouse capture, alternate screen, and cursor visibility; the panic path is observable through a dedicated test-only environment trigger.
- Keep model/unit tests for pure state and use PTY assertions only for terminal protocol, rendering, input, reconnect, launcher retarget, and authenticated actions.

## Acceptance

- `runplan` without arguments launches the TUI; `--tui` is not a supported launcher flag.
- PTY tests pass for launch/exit, cleanup and panic cleanup, four tabs, navigation/actions, mouse, SSE reconnect/replay, launcher retarget, and detach.
- Required cargo and root `make test` gates exit zero with no warnings or unaddressed diagnostics.

## Architecture Decisions

- Use `script(1)` rather than adding a PTY crate: it is already present on the target workstation, keeps the Rust dependency graph unchanged, and tests the actual executable boundary.
- Use one fixture server helper with per-test state; do not duplicate HTTP/SSE protocol setup across tests.