# TUI Run Lifecycle Controls Design

Audience: AI coding agents first.

## Goal

Add state-aware `Start/Resume` and confirmed `Restart` actions for known F4 plan rows.

## Contract

- `POST /runs/:id/start` MUST use persisted run pointer launch fields.
- Active paused run MUST receive `resume`; active running run MUST return idempotent success.
- Idle, failed, killed, queued, degraded, or zombie run MUST submit same plan through daemon.
- `POST /runs/:id/restart` MUST kill runner plus every task process group, then submit same plan.
- Restart MUST continue when kill reports no live process or terminal run.
- Missing/incomplete launch metadata MUST fail closed; NEVER infer preset or runconfig.
- TUI F4 `S` triggers `Start/Resume`; `R` opens restart confirmation.
- Confirmation text MUST say: `Restart will kill all active agents and restart runplan.`
- TUI MUST call HTTP control API only; NEVER spawn `bin/runplan`.

## Data Flow

1. TUI sends authenticated lifecycle request for selected known run.
2. Control API resolves immutable launch payload from registry pointer.
3. Daemon applies resume/kill/submit semantics.
4. Existing fleet polling/SSE refreshes state.

## Errors

- Missing run/pointer: `404 run-not-found`.
- Missing plan path, repo root, preset, and runconfig: `409 launch-metadata-missing`.
- Kill failure other than absent/terminal process: restart aborts before submit.
- Submit failure returns daemon error; no local fallback.

## Testing

- Control API tests verify exact authenticated endpoints, state-aware commands, zombie restart, and fail-closed metadata.
- Ratatui tests verify F4 key actions and exact confirmation copy.
- Full Node tests, Cargo tests, Clippy `-D warnings`, and Cargo fmt check gate completion.

## Architecture Decisions

- Keep lifecycle orchestration in daemon/control API; deleting this boundary makes TUI own process safety.
- Reuse registry pointer launch fields; new persistence model unnecessary.
- Scope fresh start to known F4 rows; undiscovered plan-file inventory remains out of scope.