# TUI Run Lifecycle Controls Implementation Plan

> **For agentic workers:** execute tasks locally in order; repository session forbids subagent dispatch.

**Goal:** Add daemon-owned Start/Resume and confirmed Restart controls to F4 plan rows.

**Architecture:** Control API resolves persisted launch payload and invokes daemon commands. Rust TUI only requests lifecycle actions and renders confirmation.

**Tech Stack:** Node.js control API/daemon, Rust ratatui/crossterm.

---

## Wave Plan

| Wave | Tasks | Files touched | Safe to parallelize? |
|---|---|---|---|
| 1 | Task 1 | `src/control-api.js`, `src/daemon.js`, `src/test/control-api.test.js` | single task |
| 2 | Task 2 | `tui/src/lib.rs`, `tui/src/main.rs` | single task |
| 3 | Task 3 | lifecycle spec/docs | single task |

### Task 1: Lifecycle API

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

**Files:**
- Modify: `src/daemon.js` — state-aware start and restart commands.
- Modify: `src/control-api.js` — authenticated lifecycle routes.
- Test: `src/test/control-api.test.js`.

**Contract:** `POST /runs/:id/start|restart`; persisted pointer launch payload; fail closed on missing metadata; restart kill-before-submit.

**Acceptance:** `node --test src/test/control-api.test.js` passes.

- [ ] Write failing lifecycle route tests.
- [ ] Implement minimal daemon/control API behavior.
- [ ] Run acceptance.

### Task 2: TUI Actions

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

**Files:**
- Modify: `tui/src/lib.rs` — restart confirmation state.
- Modify: `tui/src/main.rs` — F4 keys, modal, HTTP actions, mouse-safe rendering.

**Contract:** F4 `S` sends `start`; F4 `R` confirms exact restart warning, then sends `restart`.

**Acceptance:** `cargo test --manifest-path tui/Cargo.toml` passes.

- [ ] Write failing key/modal tests.
- [ ] Implement minimal UI behavior.
- [ ] Run acceptance.

### Task 3: Contract Sync and Gate

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

**Files:**
- Modify: `docs/plans/2026-07-12-runplan-tui-spec.md` — lifecycle control contract.

**Acceptance:** `cargo fmt --manifest-path tui/Cargo.toml --check && cargo clippy --manifest-path tui/Cargo.toml --all-targets -- -D warnings` passes.

- [ ] Update canonical TUI contract.
- [ ] Run full lint, typecheck/build, and tests.