# Ratatui TUI PTY Regression Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use `/ship` or `/executing-plans` task-by-task. Steps use checkbox syntax.

**Goal:** Fix launcher argument safety and verify the real TUI terminal contract end to end.

**Architecture:** Normalize launcher flags before command dispatch. Add a Rust integration harness that starts the compiled binary under `script(1)` against an isolated mock control API, then asserts captured terminal output, cleanup sequences, requests, and exit status.

**Tech Stack:** Bash, Rust integration tests, crossterm/ratatui, `script(1)`, std TCP.

## Wave Plan

| Wave | Tasks | Files touched | Safe to parallelize? |
|---|---|---|---|
| 1 | Task 1 | `bin/runplan`, `tui/tests/launcher.rs` | single task |
| 2 | Task 2 | `tui/src/main.rs`, `tui/tests/pty.rs`, `tui/Cargo.lock` if needed | single task |
| 3 | Task 3 | no source changes | single verification task |

### Task 1: Harden launcher parsing

**Wave:** 1
**Blocks:** Task 2
**Blocked by:** —

**Files:**
- Modify: `bin/runplan` — guard positional reads and normalize supported `--tui` placements.
- Test: `tui/tests/launcher.rs` — executable shell argument regression checks.

**Contract:** `set -u` must not permit an unbound positional expansion. `--tui` is accepted before or after a run plan argument and is removed before runner dispatch; subcommands retain their existing validation.

**Acceptance:** run the launcher regression test and verify no unbound-variable failure for bare, leading-flag, and trailing-flag forms.

### Task 2: Add real-PTY functional regression suite

**Wave:** 2
**Blocks:** Task 3
**Blocked by:** Task 1

**Files:**
- Modify: `tui/src/main.rs` — panic-safe terminal cleanup only if PTY test exposes the missing behavior.
- Create: `tui/tests/pty.rs` — fixture control API, PTY driver, and requirement-specific tests.
- Modify: `tui/Cargo.toml`/`Cargo.lock` only if a dependency is proven necessary.

**Contract:** Tests invoke `runplan-tui` through `script(1)` with isolated `HOME`, capture terminal bytes, drive keyboard and mouse sequences, and assert fixture-backed UI behavior and HTTP/SSE protocol events. Any impossible behavior must be named in the test/report rather than skipped.

**Acceptance:** `cargo test --locked --test pty -- --test-threads=1` passes and covers every requested requirement with a named test.

### Task 3: Full verification

**Wave:** 3
**Blocks:** —
**Blocked by:** Task 2

**Acceptance:** run `cd tui && cargo build --release --locked && cargo clippy --all-targets --locked -- -D warnings && cargo test --locked`, then `make test`; record exact exit/results.

## Self-review

- All requested behaviors map to Task 2; launcher crash maps to Task 1.
- No same-wave file overlap exists.
- Tests use real input/output at the binary boundary; pure model behavior remains in existing unit tests.