2026.08.26 - Chain Dashboard UI - Planning

docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui-phase-1-dependency-baseline.md

@@ -0,0 +1,66 @@
+# Phase 1: Pi Dependency Baseline Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move the project to the tested Pi/TUI `0.84.3` baseline without changing product behavior or UI.
+
+**Architecture:** Update only the three Pi development packages and the generated lockfile. Keep wildcard peer dependencies so the published extension remains compatible with its host. Make compiler-driven compatibility edits only if `0.84.3` requires them.
+
+**Tech Stack:** TypeScript, pnpm, Vitest, Biome, `@earendil-works/pi-ai@0.84.3`, `@earendil-works/pi-coding-agent@0.84.3`, `@earendil-works/pi-tui@0.84.3`.
+
+**Parent plan:** `docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui.md`
+
+**Prerequisite:** None.
+
+**Usable result:** The unchanged extension builds, tests, and packages against Pi `0.84.3`; README states Pi `0.84.3+`.
+
+## Constraints
+
+- Do not change commands, schemas, settings, rendering, or interaction behavior.
+- Leave `peerDependencies` as `"*"`; update only the three Pi `devDependencies`.
+- Do not add pi-status or any other dependency.
+- Limit source edits to errors proven by the `0.84.3` typecheck or tests.
+
+### Task 1: Update and verify the dependency baseline
+
+**Files:**
+
+- Modify: `package.json`
+- Modify: `pnpm-lock.yaml`
+- Modify: `README.md`
+- Modify only if compilation requires it: the exact source/test call site reported by `pnpm typecheck`
+
+- [ ] **Step 1: Record the baseline.**
+
+  Run `pnpm check` before editing. Expected: the current suite passes; if it does not, record the pre-existing failure and stop rather than folding an unrelated fix into this phase.
+
+- [ ] **Step 2: Update only the Pi development packages.**
+
+  Set these exact values in `package.json`:
+
+  ```json
+  "@earendil-works/pi-ai": "^0.84.3",
+  "@earendil-works/pi-coding-agent": "^0.84.3",
+  "@earendil-works/pi-tui": "^0.84.3"
+  ```
+
+  Leave TypeScript, Vitest, Biome, TypeBox, engines, and all peer dependencies unchanged. Run `pnpm install --lockfile-only` to regenerate `pnpm-lock.yaml`.
+
+- [ ] **Step 3: Document the minimum tested host.**
+
+  In `README.md`, update the Pi prerequisite/compatibility text to say `0.84.3+`. Do not document dashboard behavior yet.
+
+- [ ] **Step 4: Prove compatibility.**
+
+  Run `pnpm check`. Expected: lint, `tsc --noEmit`, and all Vitest tests pass. If the compiler identifies a Pi API change, make the smallest call-site adaptation, add or update the nearest focused test, and rerun the failing command before the full check.
+
+- [ ] **Step 5: Verify package and scope.**
+
+  Run `pnpm run pack:dry-run`, `git diff --check`, and `git diff -- package.json pnpm-lock.yaml README.md`. Expected: the package dry-run succeeds; only the three versions, their lockfile graph, and minimum-version documentation change unless Step 4 proved a required compatibility edit.
+
+- [ ] **Step 6: Commit the atomic result.**
+
+  ```bash
+  git add package.json pnpm-lock.yaml README.md
+  git commit -m "chore: update pi dependencies to 0.84.3"
+  ```

docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui-phase-2-chain-input-repair.md

@@ -0,0 +1,49 @@
+# Phase 2: Chain Input Repair Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make `/run-chain` and `/chain` previews respond to modern CSI-u/Kitty keyboard input and prevent failed or cancelled previews from launching a chain.
+
+**Architecture:** Replace raw byte comparisons in `ChainClarifyComponent` with Pi/TUI `matchesKey()` and native `Input`, forward focus through `Focusable`, and gate preview execution to interactive TUI mode. Preserve the current preview appearance; dashboard styling starts in Phase 3.
+
+**Tech Stack:** TypeScript, Pi/TUI `0.84.3`, Vitest.
+
+**Parent plan:** `docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui.md`
+
+**Prerequisite:** Phase 1 dependency baseline.
+
+**Usable result:** `/run-chain` works in modern terminals, remains scriptable outside TUI mode, and never launches after preview rejection, cancellation, or UI failure.
+
+## Constraints
+
+- Preserve `/run-chain`, `/chain`, `--yes`, `--bg`, schemas, and `ChainClarifyResult`.
+- Show preview only when `ctx.mode === "tui" && !bg && !yes`.
+- Do not introduce dashboard primitives or visual changes in this phase.
+- Every new input and failure branch needs a focused regression.
+
+### Task 1: Reproduce modern input failures
+
+**Files:** `tests/chain-clarify.test.ts`
+
+- [ ] Add failing tests that send `"\x1b[13u"` for Enter, `"\x1b[106u"` for `j`, and `"\x1b[98u"` for `b`. Assert Enter confirms, `j` moves selection, and `b` returns the background action. Run `pnpm vitest run tests/chain-clarify.test.ts`; expected: the new cases fail against raw string comparisons.
+
+### Task 2: Repair input and focus at the boundary
+
+**Files:** `src/tui/chain-clarify.ts`, `tests/chain-clarify.test.ts`
+
+- [ ] Make `ChainClarifyComponent` implement `Component, Focusable`; replace the hand-rolled text buffer with Pi/TUI `Input`; expose `focused` and forward it to the input.
+- [ ] Use `matchesKey(data, Key.*)` for navigation, Enter, Escape, and editing shortcuts; ignore `isKeyRelease(data)`. Retain printable-key behavior through native `Input` and preserve the existing `ChainClarifyResult` variants.
+- [ ] Run `pnpm vitest run tests/chain-clarify.test.ts`. Expected: legacy and CSI-u cases pass, focus reaches the native input, and key-release events do not act twice.
+
+### Task 3: Gate previews and fail closed
+
+**Files:** `src/core/slash-chain.ts`, `tests/slash-chain.test.ts`, `tests/core/chain-clarify-integration.test.ts`
+
+- [ ] Add failing tests for non-TUI invocation, `--yes`, `--bg`, cancelled previews, and rejected `ctx.ui.custom` promises for both `/chain` and `/run-chain`.
+- [ ] Centralize the preview condition as `ctx.mode === "tui" && !bg && !yes`. On cancellation or rejection, emit a visible `pi-subagent-result` error and return before spawning any agent. Non-TUI, `--yes`, and `--bg` paths bypass the preview according to existing semantics.
+- [ ] Run `pnpm vitest run tests/slash-chain.test.ts tests/core/chain-clarify-integration.test.ts`. Expected: every bypass and failure path has an explicit no-spawn assertion.
+
+### Task 4: Verify and commit
+
+- [ ] Run `pnpm check` and `git diff --check`. Manually run `/run-chain` in a CSI-u/Kitty-capable terminal and confirm arrows/`j`/`k`, editing, Escape, reopen, Enter, and `b` work.
+- [ ] Commit with `git add src/tui/chain-clarify.ts src/core/slash-chain.ts tests/chain-clarify.test.ts tests/slash-chain.test.ts tests/core/chain-clarify-integration.test.ts && git commit -m "fix: support modern chain preview input"`.

docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui-phase-3-dashboard-foundation.md

@@ -0,0 +1,59 @@
+# Phase 3: Dashboard Foundation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Introduce one local dashboard renderer and use it for the chain preview, establishing the visual system without changing other surfaces.
+
+**Architecture:** A dependency-free `dashboard-style.ts` owns overlay sizing, ANSI-safe frame width, selected-row viewport fitting, and the small-terminal fallback. The chain preview is the first consumer.
+
+**Tech Stack:** TypeScript, Pi/TUI `0.84.3`, Vitest.
+
+**Parent plan:** `docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui.md`
+
+**Prerequisite:** Phase 2 chain input repair.
+
+**Usable result:** The chain preview has a responsive pi-status-inspired frame and viewport while retaining all repaired interactions.
+
+## Constraints
+
+- Use only Pi's active theme; add no palettes, settings, config, pi-status dependency, or shared package.
+- Overlay options are centered, `width: "92%"`, `maxHeight: "85%"`.
+- Preserve chain behavior and readonly parallel steps.
+- ANSI-aware width/truncation must use the TUI utilities already available in Pi/TUI.
+
+### Task 1: Specify the renderer with failing tests
+
+**Files:** Create `tests/dashboard-style.test.ts`
+
+- [ ] Add exact tests for: a frame rendered at width `24`; `dashboardContentWidth(24) === 18`; a selected row scrolled into view with a stable offset; and `renderDashboardTooSmall(30, 3, theme)` containing `Esc`. Run `pnpm vitest run tests/dashboard-style.test.ts`; expected: module-not-found failure.
+
+### Task 2: Add the minimal shared renderer
+
+**Files:** Create `src/tui/dashboard-style.ts`
+
+- [ ] Export exactly:
+
+  ```ts
+  export const DASHBOARD_MAX_HEIGHT_RATIO = 0.85;
+  export const DASHBOARD_OVERLAY_OPTIONS: OverlayOptions;
+  export const MIN_DASHBOARD_FRAME_WIDTH = 7;
+  export function dashboardContentWidth(width: number): number;
+  export function renderDashboardFrame(lines: readonly string[], width: number, theme: Theme): string[];
+  export function fitDashboardViewport(lines: readonly string[], selectedLine: number | undefined, height: number, offset: number): { lines: string[]; offset: number };
+  export function renderDashboardTooSmall(width: number, height: number, theme: Theme): string[];
+  ```
+
+- [ ] Use horizontal padding `2`, heavy frame glyphs `┏ ┓ ┗ ┛ ━ ┃`, and `{ anchor: "center", width: "92%", maxHeight: "85%" }`. Clamp every width/height calculation; keep the selected line visible without unnecessary offset jumps.
+- [ ] Run `pnpm vitest run tests/dashboard-style.test.ts`; expected: all exact-width, viewport, and narrow-terminal tests pass.
+
+### Task 3: Apply it only to chain preview
+
+**Files:** `src/tui/chain-clarify.ts`, `tests/chain-clarify.test.ts`, `tests/core/chain-clarify-integration.test.ts`
+
+- [ ] Add failing render tests for the heavy frame, visible `▸` selection marker, footer hints, narrow fallback, and selected-row scrolling.
+- [ ] Render the preview through the shared frame and viewport. Keep parallel steps readonly and retain native input/focus behavior from Phase 2.
+- [ ] Run the three focused test files, then `pnpm check` and `git diff --check`.
+
+### Task 4: Commit the atomic result
+
+- [ ] Commit with `git add src/tui/dashboard-style.ts src/tui/chain-clarify.ts tests/dashboard-style.test.ts tests/chain-clarify.test.ts tests/core/chain-clarify-integration.test.ts && git commit -m "feat: add dashboard chain preview"`.

docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui-phase-4-live-widgets.md

@@ -0,0 +1,48 @@
+# Phase 4: Live Widgets Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Restyle the persistent AgentWidget and ChainWidget with the dashboard hierarchy while preserving placement and lifecycle.
+
+**Architecture:** Keep each widget's existing state and update hooks. Change only rendering to compact themed headings, status rows, activity continuations, and summaries; reuse existing truncation and active-theme roles.
+
+**Tech Stack:** TypeScript, Pi/TUI `0.84.3`, Vitest.
+
+**Parent plan:** `docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui.md`
+
+**Prerequisite:** Phase 3 dashboard foundation.
+
+**Usable result:** Running agents and chains display a consistent compact dashboard treatment above the editor.
+
+## Constraints
+
+- AgentWidget and ChainWidget remain above the editor.
+- Do not change manager state, timers, task ordering, completion behavior, or settings.
+- Use the active Pi theme and existing helpers; do not wrap persistent widgets in overlay frames.
+
+### Task 1: Lock the intended output
+
+**Files:** `tests/agent-widget.test.ts`, `tests/chain-widget.test.ts`
+
+- [ ] Replace/add focused snapshots or line assertions for this hierarchy:
+
+  ```text
+  ╭─ ✦ AGENTS
+  │ ● worker  description · metadata
+  │   ⎿ activity
+  ╰─ running/queued summary
+  ```
+
+  Apply the analogous `CHAINS` heading and chain metadata. Cover narrow truncation and empty/terminal states already supported. Run both test files; expected: visual assertions fail before implementation.
+
+### Task 2: Restyle without changing lifecycle
+
+**Files:** `src/tui/agent-widget.ts`, `src/tui/chain-widget.ts`
+
+- [ ] Replace only render composition: themed `✦` headings, semantic status dot/icon, one primary row, indented `⎿` activity, and compact summary. Preserve existing constructors, subscriptions, invalidation, data selection, and placement calls.
+- [ ] Use ANSI-safe truncation already present in the repository/Pi/TUI. Do not import pi-status or create another rendering abstraction.
+
+### Task 3: Verify and commit
+
+- [ ] Run `pnpm vitest run tests/agent-widget.test.ts tests/chain-widget.test.ts`, then `pnpm check` and `git diff --check`. Expected: behavior tests and new render assertions pass.
+- [ ] Commit with `git add src/tui/agent-widget.ts src/tui/chain-widget.ts tests/agent-widget.test.ts tests/chain-widget.test.ts && git commit -m "feat: restyle live agent and chain widgets"`.

docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui-phase-5-agents-menu.md

@@ -0,0 +1,41 @@
+# Phase 5: Agents Menu Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Migrate `/agents` list and detail menus to responsive framed dashboard overlays while preserving native editing dialogs.
+
+**Architecture:** Reuse the shared overlay options, frame, and viewport around existing menu state. Keep multi-step creation and full markdown editing on Pi's native input/editor components.
+
+**Tech Stack:** TypeScript, Pi/TUI `0.84.3`, Vitest.
+
+**Parent plan:** `docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui.md`
+
+**Prerequisite:** Phase 4 live widgets.
+
+**Usable result:** `/agents` is readable and scrollable on normal and small terminals, with all create/edit/delete actions unchanged.
+
+## Constraints
+
+- Preserve `/agents`, agent definitions, validation, settings formats, and action semantics.
+- Native input/editor dialogs remain native and receive focus.
+- Center overlays at `92%` width and `85%` maximum height.
+
+### Task 1: Add failing menu regressions
+
+**Files:** `tests/agents-menu.test.ts`
+
+- [ ] Add assertions for heavy framed list/detail views, visible selected row, footer key hints, selected-row-aware scrolling, `30x3` fallback, and `DASHBOARD_OVERLAY_OPTIONS` passed to the custom UI.
+- [ ] Retain/add interaction tests for navigation, create, edit, delete confirmation, Escape, and focus transfer into native input/editor dialogs. Run `pnpm vitest run tests/agents-menu.test.ts`; expected: only new layout assertions fail.
+
+### Task 2: Apply shared layout
+
+**Files:** `src/tui/agents-menu.ts`
+
+- [ ] Render list and detail contents with `renderDashboardFrame`; calculate inner height and use `fitDashboardViewport` so selection stays visible.
+- [ ] Use `renderDashboardTooSmall` below the minimum dimensions and a clear `▸` selection marker plus compact footer hints.
+- [ ] Pass `DASHBOARD_OVERLAY_OPTIONS` to the `/agents` custom UI. Leave the creation wizard and full markdown editor implementations intact; explicitly forward focus whenever the active child is focusable.
+
+### Task 3: Verify and commit
+
+- [ ] Run `pnpm vitest run tests/agents-menu.test.ts`, then `pnpm check` and `git diff --check`. Manually open `/agents`, scroll, create/cancel an agent, and open/cancel markdown editing.
+- [ ] Commit with `git add src/tui/agents-menu.ts tests/agents-menu.test.ts && git commit -m "feat: migrate agents menu to dashboard layout"`.

docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui-phase-6-inline-renderers.md

@@ -0,0 +1,46 @@
+# Phase 6: Inline Renderers Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Give subagent calls/results, completion notifications, watchdog warnings, and intercom messages one compact status-and-metadata hierarchy.
+
+**Architecture:** Add two private formatting helpers in the existing render module and reuse them from existing inline render entry points. Preserve the native message shell, custom message types, payloads, and detail toggles.
+
+**Tech Stack:** TypeScript, Pi/TUI `0.84.3`, Vitest.
+
+**Parent plan:** `docs/superpowers/plans/2026-08-26-run-chain-dashboard-ui.md`
+
+**Prerequisite:** Phase 5 agents menu.
+
+**Usable result:** Every inline pi-subagents message is visually consistent without changing its contract or interaction.
+
+## Constraints
+
+- Preserve tool call/result data, custom message types, expanded details, watchdog logic, and intercom delivery.
+- Use active-theme semantic roles; no palettes or new public abstraction.
+- Keep helpers private and local because there is only one renderer implementation.
+
+### Task 1: Specify consistent inline output
+
+**Files:** `tests/render.test.ts`, `tests/watchdog-render.test.ts`
+
+- [ ] Add focused assertions for running/success/error subagent calls and results, collapsed/expanded metadata, completion notification, watchdog warning, and intercom message. Assert subject/status hierarchy and stable metadata separators, not terminal color escape values.
+- [ ] Run `pnpm vitest run tests/render.test.ts tests/watchdog-render.test.ts`; expected: new presentation assertions fail.
+
+### Task 2: Add the smallest shared formatting
+
+**Files:** `src/tui/render.ts`, `src/index.ts`
+
+- [ ] Add private helpers with these signatures:
+
+  ```ts
+  function statusHeader(icon: string, subject: string, status: string): string;
+  function metadataLine(parts: readonly string[]): string;
+  ```
+
+- [ ] Use them for subagent tool call/result rendering, completion messages, watchdog warnings, and intercom messages. Filter absent metadata parts before joining; retain existing native shells, payload parsing, detail expansion, and theme application.
+
+### Task 3: Verify and commit
+
+- [ ] Run `pnpm vitest run tests/render.test.ts tests/watchdog-render.test.ts`, then `pnpm check` and `git diff --check`.
+- [ ] Commit with `git add src/tui/render.ts src/index.ts tests/render.test.ts tests/watchdog-render.test.ts && git commit -m "feat: unify inline subagent status rendering"`.