# workflow usability update plan Status: manual recovery plan after managed Workflow Runs `512d6c31`, `51b0c1cb`, and `ecb11e1e` failed or were interrupted before implementation. ## Locked decisions - The interactive dashboard automatically enters a fresh plan-seeded session. Tool and RPC callers receive `/workflow continue ` instead. - Startup may adopt a continuable run only when its prior owner is stale or dead. A live owner remains fail-closed. - The widget above Pi's editor shows only the newest attached active run. - Dashboard navigation, action sheets, Gates, confirmations, questions, and feedback use popup overlays in TUI mode. RPC, print, and JSON paths remain linear. - The plan reader is a full-screen overlay with an H1-H3 outline, current-section highlight, arrows, Page Up/Page Down, Home/End, and Escape. - The outline is visible at 80 columns and wider, hidden from 60 through 79 columns, and replaced by a truthful minimum-size message below 48x12. - Dirty source changes require a bounded TUI warning and explicit confirmation when `allowDirtySource` is omitted. TUI starts honor an explicit `allowDirtySource: true` without prompting. Non-TUI tool, RPC, print, and JSON starts require `allowDirtySource: true`. Approval is not tied to a later status digest recheck. - Approved host commands retain a three-minute timeout. Internal Git commands receive a 30-second timeout. Process-tree termination is bounded on every platform. - Prototype direction C, drill-down overlays with a dedicated full-screen reader, is the baseline after comparing A, B, and C. ## Failure evidence captured during this change - Run `512d6c31-5bde-4e93-8164-5d31fb684b00` reached design, described a prototype phase, but emitted no `prototype` assignment. The engine terminated with `invalid-design-output: Design must select exactly one prototype Assignment`. - Run `51b0c1cb-f5b2-47f9-8c0c-b323307b720b` was interrupted during discovery. - Run `ecb11e1e-fe38-4076-862e-739498dbe33b` completed discovery, then remained in the feature-designer assignment for nearly five minutes until interrupted. These failures are acceptance-test inputs for assignment timeout handling and designer guidance. ## Implementation phases ### 1. Prototype overlays Own only `docs/workflow/dashboard-mocks.md` and isolated prototype artifacts. Compare: - A: centered compact modal - B: near-full-screen workspace with list/detail panes - C: drill-down overlays with a dedicated full-screen plan reader Validate wide, 80x24, 60-column, and 47x11 frames. Production TypeScript remains untouched until the prototype direction is accepted. ### 2. Session lifecycle and recovery - Route the dashboard's fresh-session action through the existing `handleContinue()` and `ctx.newSession({ withSession })` path. - Add an integration test proving a dashboard result triggers session replacement without a second command. - During absent/dead startup adoption, atomically rotate both `lease.activeParentSessionId` and `implementationContext.activeParentSessionId`. - Preserve live-owner, active-assignment, and historical-session fences. Primary files: `dashboard.ts`, `context-transition.ts`, `continuation.ts`, `engine.ts`, and focused tests. ### 3. Worktree safety and command deadlines - Return bounded dirty path/status evidence instead of rejecting all ordinary source dirt. - Keep conflicts, unmerged entries, repository identity, ignored-root, branch collision, and target-path checks fail-closed. - Create the worktree from the pinned `HEAD`; warning copy states source-only changes are omitted. - Add `allowDirtySource` to tool/domain inputs and idempotency fingerprints. - Apply 30-second timeouts to every internal Git invocation. - Keep approved commands at three minutes and bound Windows `taskkill` itself. - Preserve exit `124` for timeout and `125` for termination failure. Primary files: `workspace.ts`, `domain.ts`, `tool.ts`, `engine.ts`, and focused tests. ### 4. Popup TUI and plan reader - Add reusable, modeless overlay components with one earned border, visible selection, keyboard hints, width-safe rendering, and focus propagation for embedded `Input` or `Editor` children. - Use a drill-down stack: run list to run detail to action/Gate overlay. Escape always returns one level or closes. - Parse Markdown H1-H3 headings into a pure outline model. - Render only the current plan viewport, not the entire artifact. - Sanitize untrusted transcript/plan control sequences before rendering. - Keep `ctx.ui.custom()` guarded by `ctx.mode === "tui"`. Primary files: new `tui.ts` and tests, plus orchestration changes in `dashboard.ts`. ### 5. Persistent progress widget - Add a pure projection for readable label, active stage, completed/total core stages, and open Gate. - Refresh from persisted attached runs after `afterRunPersist` and `session_start`. - Clear after terminal state and `session_shutdown`. - Render one bounded line at narrow widths. Primary files: new `progress.ts` and tests, plus registration in `index.ts`. ### 6. Design-contract and timeout regression - Strengthen the bundled feature-designer instructions so non-trivial UI plans explicitly select exactly one eligible prototype assignment with isolated ownership. - Add a focused test for the exact missing-prototype failure and guidance contract. - Ensure assignment execution cannot wait forever; surface timeout/interruption evidence without falsely reporting success. - Record any behavior that cannot be safely fixed in this slice in `docs/todo.md` with the three run IDs above. Primary files: `agents/feature-designer.md`, engine/execution tests, and related runtime code. ### 7. Documentation, verification, and review Update the README, design document, dashboard mocks, and a superseding ADR. Run focused tests, typecheck, full tests, and manual Pi validation at wide, 80x24, 60-column, and 47x11 sizes. An agent that did not implement the change performs the final standards and specification review. ## Acceptance criteria - Fresh-session selection continues automatically in interactive Pi without restart or a second command. - A new Pi process can adopt an absent/dead continuable run but cannot steal one from a live owner. - Exactly one newest active-run widget is visible above the editor and clears promptly. - Every bounded TUI interaction is an overlay; RPC/print/JSON remain usable and never call unsupported custom overlays. - The full-screen plan reader meets the locked outline, navigation, responsive, and width contracts. - Dirty source starts are warned and explicitly authorized while conflicts remain blocked. - No internal Git or approved host subprocess can wait indefinitely, and process cleanup is bounded. - The designer contract prevents the missing-prototype-assignment failure, while assignment execution has a bounded failure path. - Focused tests, typecheck, full tests, manual Pi validation, and independent review pass.