harness-tools/docs/adr/0002-workflow-interaction-and-recovery-25AUG2026.md

status, supersedes, superseded-by

status	supersedes	superseded-by
superseded	0001-workflow-architecture-24AUG2026.md	0006-skill-led-development-workflow-04SEP2026.md

Use drill-down overlays and bounded recovery

Superseded by ADR 0006. Retained as legacy custom-engine UI and recovery evidence.

This decision supersedes the dashboard, dirty-source, execution-timeout, and startup-ownership assumptions in ADR 0001. The persisted gated pipeline, worktree isolation, and independent-review decisions from ADR 0001 remain accepted.

Context

Three managed runs exposed usability and liveness gaps:

• 512d6c31-5bde-4e93-8164-5d31fb684b00 reached Design, described prototype work, but emitted no prototype Assignment. The engine failed with invalid-design-output: Design must select exactly one prototype Assignment.
• 51b0c1cb-f5b2-47f9-8c0c-b323307b720b was interrupted during Discovery.
• ecb11e1e-fe38-4076-862e-739498dbe33b completed Discovery, then remained in the feature-designer Assignment for nearly five minutes before interruption.

The prior focused dashboard did not scale cleanly from run selection through Gate decisions and long verified artifacts. Fresh-session selection returned instructions instead of entering the already implemented continuation path. A dirty source checkout blocked all starts even when the user understood that a new worktree starts from HEAD. Internal Git calls and child Assignments lacked complete deadlines.

Static prototypes compared a centered compact modal, a near-full-screen workspace, and shallow drill-down overlays with a dedicated reader. Direction C provided the clearest responsive behavior without a permanent side pane.

Decision

• TUI run selection, actions, Gates, confirmations, questions, and feedback use shallow popup overlays. Escape returns one level.
• Verified plans, reports, prototype evidence, and Assignment transcripts use a sanitized full-screen reader. It shows an H1-H3 outline at 80 columns and wider, uses one document pane from 60 through 79 columns, and reports a 48x12 minimum below either boundary.
• RPC, print, and JSON interfaces remain linear and never invoke custom TUI overlays.
• A dashboard fresh-session action immediately calls the existing /workflow continue handler and newSession() flow. Noninteractive callers continue with an explicit run ID.
• One widget above Pi's editor shows the newest active run attached to the current session. Persisted state drives refresh and terminal state clears it.
• Startup may adopt a continuable run when its recorded process is dead or its lease is absent. Adoption atomically rotates the lease and Implementation Context active-parent IDs. Live processes and live Assignments remain fail-closed.
• Worktrees continue to start from a pinned source HEAD. Ordinary staged, unstaged, and untracked changes produce bounded path/status evidence and require explicit authorization because those changes are omitted. Unmerged paths remain blocked.
• Internal Git calls have a 30-second timeout. Approved host commands retain their three-minute timeout. Process-tree termination has a separate deadline and distinguishes command timeout exit 124 from cleanup failure exit 125.
• Child Assignment execution has a five-minute deadline and persists timeout/interruption evidence.
• The feature-designer contract requires exactly one eligible, isolated prototype Assignment for non-trivial UI work, plus explicit implementation, verification, and independent-review Assignments.

Consequences

• Dashboard behavior is easier to reason about because each overlay has one local task and the verified reader owns long-document navigation.
• Interactive continuation no longer requires a second command, while the persisted handoff and revision fences remain authoritative.
• Dead ownership can recover without manual state surgery. A running process or Assignment cannot be displaced based only on an old heartbeat.
• Users may proceed from a dirty source checkout without copying local changes into the worktree. Persisted evidence records what was knowingly omitted.
• Git, host-command cleanup, and child execution now have bounded failure paths rather than indefinite waits.
• Direction C has automated renderer and orchestration coverage. Its completed manual application validation is recorded below. The static frames in docs/workflow/dashboard-mocks.md remain labeled prototype evidence, not production screenshots.

Manual application validation

An actual Pi TUI session driven through a PTY passed these checks:

• Plan reader at 120x30, 80x24, 60x24, and 47x11.
• Selection popup at 60x24.
• Input popup at 80x24.

This record does not claim manual validation of other dashboard or workflow paths.