@zhuxixi/pi-agent-board 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pi Agent Board contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PRD.md

@@ -0,0 +1,484 @@
+# PRD: Pi Agent Board Extension
+
+**Status:** Draft  
+**Last Updated:** 2026-05-30  
+**Owner:** TBD
+
+## 1. Summary
+
+Build a Pi extension that delivers a Claude Code agent-view-like experience inside Pi, packaged as **Pi Agent Board**: a single terminal UI to dispatch, monitor, reply to, attach to, and manage multiple **background Pi sessions**.
+
+Each row in the view must represent a **real Pi session** with persisted history and resumable state, not just a transient subagent job.
+
+## 1.1 Locked product decisions
+
+These decisions were confirmed on 2026-05-30 and are part of the MVP contract:
+
+- dashboard is **global across projects** by default,
+- `/agent-board` is the required MVP entry point,
+- implementation should remain extensible for a future `/bg` flow,
+- attaching to a running background session should **interrupt with confirmation, then attach**,
+- same-repo parallel writer sessions must **require worktree isolation**,
+- MVP may use a **cheap model summarizer**,
+- returning to the dashboard via `/agent-board` is acceptable for MVP.
+
+## 2. Problem
+
+Pi has strong primitives for sessions, extensions, tools, TUI components, and subagents, but it does **not** have a first-class built-in agent board. Today, users must manually juggle sessions and subagents and cannot easily:
+
+- see all active/background work in one place,
+- know which session needs input,
+- reply inline without opening full transcripts,
+- safely run several coding sessions in parallel,
+- treat background work as first-class resumable conversations.
+
+## 3. Product Goal
+
+Provide a Pi-native “agent board” that feels behaviorally equivalent to Claude’s agent board where Pi’s extension APIs allow it.
+
+The product should let a user:
+
+1. dispatch a new background coding task,
+2. watch its state and summary live,
+3. peek and reply inline,
+4. attach to the full session when needed,
+5. detach without losing work,
+6. manage many background sessions safely.
+
+## 4. Non-Goals
+
+### V1 non-goals
+
+- Exact top-level CLI parity with `claude agents`.
+- Cloud-hosted/background remote execution.
+- Replacing `pi-subagents` as a general orchestration package.
+- Multi-user/shared dashboards.
+- Full PR integration, PR badges, or SCM review workflows.
+- Perfect parity for every Claude keyboard shortcut.
+- Full shell-job support (`! command`) in MVP.
+
+## 5. Core Product Principles
+
+1. **Session-oriented, not job-oriented**  
+   Background work is a real Pi session with a session file.
+
+2. **Dashboard first, transcript second**  
+   Most triage should happen from the dashboard or peek panel.
+
+3. **Safe parallelism**  
+   Background coding sessions must not silently trample each other’s files.
+
+4. **Resumable and durable**  
+   The dashboard should survive Pi restart/reload and be able to rehydrate rows from disk.
+
+5. **Public-API-first implementation**  
+   Build on Pi’s documented extension/session/TUI APIs, not unstable internal package imports.
+
+## 6. Users / Primary Use Cases
+
+### Primary user
+A Pi power user working on several independent coding tasks at once.
+
+### Core use cases
+
+- Dispatch a bug fix, refactor, and review task in parallel.
+- Keep coding in one attached session while other sessions continue in background.
+- Return to a dashboard to see which sessions are blocked or complete.
+- Reply to a question from a background session without reopening the full transcript.
+- Attach to a session for deep work, then return to the dashboard.
+- Safely isolate edits from concurrent tasks.
+
+## 7. User Experience
+
+## 7.1 Entry points
+
+V1 should support:
+
+- `/agent-board` — open the dashboard from within Pi.
+- CLI slash-command entrypoint such as `pi /agent-board`, if Pi supports passing slash commands at startup.
+
+Stretch goals:
+
+- `/bg [prompt]` — move current work into a managed background session, or send a follow-up prompt while backgrounding.
+- `pi agents` style entrypoint, if Pi core or packaging model allows it cleanly.
+
+## 7.2 Main dashboard
+
+The dashboard is a full-screen custom TUI component.
+
+It must include:
+
+- header with current global scope/defaults,
+- grouped session rows,
+- bottom input for dispatch/filter,
+- footer with key hints.
+
+### Row fields
+Each row should show at minimum:
+
+- session name,
+- current summary,
+- semantic state,
+- process/liveness state,
+- relative last-activity time,
+- cwd or project context,
+- pin status,
+- optional model/agent label.
+
+### Row grouping
+V1 groups:
+
+- Queued
+- Running
+- Needs input
+- In Progress
+- Done
+
+Stretch:
+
+- Group by directory/project.
+- “Ready for review” style secondary grouping.
+
+## 7.3 States
+
+Each session row needs two state dimensions.
+
+### Semantic state
+
+- `queued`
+- `working`
+- `needs_input`
+- `idle`
+- `completed`
+- `failed`
+- `stopped`
+
+### Process/liveness state
+
+- `alive`
+- `exited`
+
+This distinction is required so a session can remain resumable even when no worker process is currently alive.
+
+## 7.4 Core interactions
+
+### From dashboard
+
+- `↑ / ↓` — move selection
+- `Enter` — attach to selected session
+- `Space` — open peek panel
+- `Shift+Enter` — dispatch and attach
+- `Ctrl+R` — rename session
+- `Ctrl+T` — pin/unpin session
+- `Ctrl+X` — stop/delete flow
+- `Ctrl+S` — switch grouping mode
+- `Esc` — close/clear/back
+- `?` — help
+
+Keybindings should be extension-configurable and aligned with Pi keybinding conventions.
+
+## 7.5 Peek panel
+
+Peek panel is the lightweight triage surface.
+
+It must show:
+
+- current summary,
+- latest meaningful output,
+- current question/blocker (if any),
+- inline reply box.
+
+It should support:
+
+- sending a normal reply,
+- optional suggested reply later,
+- navigating between adjacent sessions without fully closing.
+
+## 7.6 Attach / detach
+
+### Attach
+Attaching opens the full interactive Pi session for that row’s session file.
+
+### Detach
+Detaching returns the user to agent board without losing session state.
+
+V1 requirement:
+
+- attaching must work,
+- detaching back to agent board must work at least from an idle/known-safe state.
+
+Stretch:
+
+- detach while a session is actively running by handing execution back to a headless worker.
+
+## 8. Functional Requirements
+
+### FR1. Background session model
+Each background row must map to:
+
+- a Pi session file,
+- a persisted session ID,
+- a working directory,
+- a stored dashboard record,
+- zero or one live worker processes at a time.
+
+### FR2. Background execution engine
+The extension must be able to:
+
+- create a background session,
+- append user messages to it,
+- spawn a headless Pi worker to advance it,
+- parse streaming JSON events,
+- update row state live,
+- mark the session resumable when the worker exits.
+
+### FR3. Dashboard persistence
+Agent-view state must persist across:
+
+- Pi restart,
+- `/reload`,
+- session switching,
+- worker exit.
+
+### FR4. Dispatch
+Dispatch input must:
+
+- create a new background session from a user prompt,
+- support dispatch + attach,
+- support filtering mode when input matches reserved patterns.
+
+V1 filtering support:
+
+- `s:<state>`
+- free-text substring on name/summary/cwd
+
+Stretch:
+
+- `a:<agent>`
+- `#PR` or URL mapping
+
+### FR5. Reply from peek
+A user must be able to send a reply from peek without manually opening the attached session.
+
+### FR6. Attach to session
+A user must be able to switch into the selected session’s full transcript and continue working interactively.
+
+### FR7. Rename / pin / stop / delete
+The dashboard must support:
+
+- renaming a session,
+- pinning/unpinning,
+- stopping active work,
+- deleting dashboard entries,
+- preserving transcript safety unless user explicitly chooses destructive cleanup.
+
+### FR8. Safe file isolation
+When background sessions may edit the same repository, the system must provide an isolation strategy.
+
+V1:
+
+- support optional git worktree isolation.
+
+Later:
+
+- automatically create worktree isolation before first mutation.
+
+### FR9. Session summaries
+Each row must have a short summary suitable for dashboard scanning.
+
+V1:
+
+- heuristic summary based on current tool, latest assistant text, blocker text, and terminal state.
+
+Later:
+
+- lightweight summarizer model pass with throttling.
+
+### FR10. Recovery / respawn
+If a worker process exits, the session must remain attachable and replyable.
+
+If Pi is restarted, the extension must be able to reconstruct the dashboard from persisted state and resume/respawn sessions as needed.
+
+## 9. Technical Constraints
+
+### 9.1 Runtime target
+Implementation must target the active Pi runtime:
+
+- `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent`
+
+Do **not** anchor on the stale legacy copy under `~/.pi/agent/npm/node_modules/@mariozechner/...`.
+
+### 9.2 Public API constraint
+Implementation should use Pi’s documented/public extension APIs, especially:
+
+- extension lifecycle/events,
+- `ctx.ui.custom()` and TUI components,
+- widgets/footer/header,
+- message renderers,
+- session switching / newSession / switchSession / fork APIs,
+- extension commands and shortcuts.
+
+### 9.3 No unstable internal imports
+Do **not** runtime-import `~/.pi/agent/npm/node_modules/pi-subagents/src/...` internals.
+
+Allowed:
+
+- study `pi-subagents` source as a reference,
+- copy/adapt patterns if necessary.
+
+Not allowed:
+
+- depending on its internal TS files as if they were a stable library contract.
+
+### 9.4 Headless child constraint
+Background workers will run headless.
+
+This means:
+
+- child Pi processes should run in JSON/print-style non-interactive mode,
+- child sessions do not own UI,
+- parent agent board owns all live visualization and state aggregation.
+
+## 10. Suggested Architecture
+
+### Option A — recommended
+Build a **session-oriented background engine** specifically for agent board.
+
+Components:
+
+- `dashboard.ts` — main TUI
+- `peek-panel.ts` — inline triage UI
+- `store.ts` — persisted roster/state
+- `supervisor.ts` — worker spawn/watch/respawn
+- `session-launch.ts` — create/advance background sessions
+- `session-summary.ts` — short summary generation
+- `worktree.ts` — optional edit isolation
+
+Why: this best matches Claude’s product shape.
+
+### Option B — fallback
+Fork/copy the official `examples/extensions/subagent` example and evolve it into a session-based engine.
+
+Why: uses clean public APIs, but requires more features to be built from scratch.
+
+### Option C — partial reuse
+Use `pi-subagents` only as a design reference for:
+
+- async tracking,
+- widget rendering,
+- nested progress ideas,
+- worktree patterns.
+
+Why: high leverage, lower coupling.
+
+## 11. MVP Scope
+
+### Included in MVP
+
+- `/agent-board` dashboard
+- global cross-project session view by default
+- persisted roster/store
+- create background Pi sessions
+- spawn headless workers to process prompts
+- live row updates
+- project-safe attach to full session
+- peek + reply
+- rename/pin/stop/delete
+- basic grouping
+- cheap model-backed summaries with heuristic fallback
+- required worktree isolation for same-repo parallel writer sessions
+
+### Excluded from MVP
+
+- shell job rows (`! command`)
+- PR badges / PR-aware grouping
+- full Claude-style detach semantics while actively running
+
+## 12. Phase Plan
+
+### Phase 1 — foundation
+
+- Extension scaffold
+- Persistent store format
+- Worker launcher
+- Event parser
+- `/agent-board` TUI
+- Dispatch + live updates
+
+### Phase 2 — interactive workflow
+
+- Peek panel
+- Inline reply
+- Attach flow
+- Safe detach-back path
+- Rename/pin/stop/delete polish
+- Restore dashboard after restart/reload
+
+### Phase 3 — parity improvements
+
+- Better summaries
+- Auto worktree isolation
+- Idle reap + lazy respawn
+- Shell job rows
+- Advanced filtering/grouping
+- `/bg` flow for current interactive session
+
+## 13. Acceptance Criteria
+
+The PRD is satisfied for MVP when:
+
+1. A user can open `/agent-board` and see a dashboard UI.
+2. A user can dispatch a new background coding task from the dashboard.
+3. The task creates a real persisted Pi session file.
+4. The row updates while the background worker runs.
+5. If the worker exits, the row remains in the dashboard and is still resumable.
+6. A user can open peek, read current context, and send a reply.
+7. A user can attach to the full session from the dashboard.
+8. Dashboard state survives Pi restart or `/reload`.
+9. Two tasks in the same repo can be run without silent file corruption when worktree mode is enabled.
+10. The implementation does not depend on unstable `pi-subagents/src/...` runtime imports.
+
+## 14. Success Metrics
+
+Initial success measures:
+
+- User can manage at least 3 concurrent background sessions comfortably.
+- Attach/peek/reply flows feel faster than manual `/resume` juggling.
+- Dashboard rehydration works reliably after reload/restart.
+- No known file-clobber incidents in supported isolation mode.
+
+## 15. Risks / Open Questions
+
+1. **Detach semantics**  
+   How close can we get to Claude’s “return to agent board” behavior using only extension/session APIs?
+
+2. **Top-level launch experience**  
+   Is `/agent-board` enough, or do we need a true standalone startup path?
+
+3. **Worktree timing**  
+   Should worktrees be created at dispatch time or lazily on first mutation?
+
+4. **Current session backgrounding**  
+   When `/bg` lands later, should it create a fresh managed background session from current transcript, or simply convert current session ownership?
+
+## 16. Reference Inputs
+
+Product/behavior reference:
+
+- Claude agent-view docs: https://code.claude.com/docs/en/agent-view
+
+Pi implementation references:
+
+- `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/docs/extensions.md`
+- `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/docs/tui.md`
+- `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/docs/sessions.md`
+- `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/docs/keybindings.md`
+- `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/index.ts`
+- `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/plan-mode/index.ts`
+- `~/.pi/agent/npm/node_modules/pi-subagents/README.md`
+
+## 17. Recommendation
+
+Proceed with a **session-oriented agent-board extension** as the primary implementation path.
+
+Do **not** treat this as a UI wrapper over `pi-subagents`. Use `pi-subagents` as a source of implementation ideas, but build the actual product around persisted Pi sessions, a parent-owned dashboard, and a lightweight supervisor/store.

package/PROGRESS.md

@@ -0,0 +1,127 @@
+# Progress Log — Pi Agent Board Extension
+
+Living checkpoint log. Newest checkpoint at top. Records what's done, workarounds, and
+nuances future agents must know. Pairs with `docs/EXPLORATION.md` (the Pi API gist).
+
+Status legend: ☐ todo · ◐ in progress · ☑ done
+
+---
+
+## Milestone status
+
+- ☑ **M0** scaffold + primitives (paths, types, atomic IO, ids, pid)
+- ☑ **M1** detached runner (`job-runner.mjs`) + durable store + dispatch + event reduce
+- ☑ **M2** dashboard list + grouping + filters + live poll
+- ☑ **M3** peek + reply
+- ☑ **M4** attach / attach-while-running confirm / recovery (reconcile) / stop / rename / pin
+- ☑ **M5** repo safety + worktree mode (same-repo writer rule wired into dispatch)
+- ☑ tests: 45/45 green · typecheck 0 errors · extension loads in real pi
+- ⚠️ **Blocked on env:** live end-to-end (real worker producing output) needs pi provider auth
+  in this environment; see CP2 + `VERIFY.md`. Code paths validated hermetically.
+
+---
+
+## Checkpoint log
+
+### CP4 — 2026-05-31 — fast non-live attach via warm PTY hosts
+- Non-live attach now uses the same Agent Board PTY host path as live sessions. `ctx.switchSession`
+  remains only as a no-PTY fallback, with a fullscreen switching overlay so the previously
+  attached session is not visible during fallback startup.
+- Added `ensureHost()` / dashboard prewarm: selected idle/completed sessions are lazily started
+  as interactive PTY hosts with `initialPrompt: null`, without mutating row task state. Warm
+  attach should be instant; cold attach immediately swaps to the attach surface and retries the
+  socket until the host is ready.
+- Kept completed hosts warm instead of terminating them immediately. Warm pool defaults:
+  `AGENT_BOARD_MAX_WARM_HOSTS=4`, `AGENT_BOARD_WARM_HOST_TTL_MS=600000`.
+- Fixed PTY detach flow: `ctrl+]`, `ctrl+g`, or `←` from a live attach returns to the dashboard
+  loop instead of revealing the original session where `/agent-board` was invoked.
+- Added internal scrollback controls for PTY attach surfaces: mouse wheel, `pgup` / `pgdn`,
+  `home`, `end`. Scrolling uses an agent-board-owned absolute viewport and clamps at top/bottom
+  so fast wheel events cannot wrap back to the bottom. Normal arrow keys still pass through.
+- Verification: `npm run typecheck` clean; `npm test` 55/55 green.
+
+### CP3 — 2026-05-30 — standalone-ish dashboard UX
+- Added a full-screen **session view** inside `/agent-board`: **v** opens the selected row's
+  live transcript from its managed session file without interrupting the worker; **← / <**
+  returns to the dashboard. **→ / >** now attaches to the real Pi session, matching the
+  primary agent-board navigation expectation. **enter** also attaches. In an attached managed
+  session, **←** from an empty input reopens agent board directly using the command-capable
+  replacement context (no slash-command text injection).
+- Added `src/core/session-view.mjs` to parse managed Pi session JSONL files and project the
+  active branch into a readable transcript surface (messages, visible custom messages,
+  compactions, branch summaries).
+- Changed the main dashboard UX to match the Claude-style screenshot more closely: the bottom
+  input is always available, typing there and pressing **Enter** dispatches a new Pi session,
+  and **Enter** on an empty input attaches to the selected session.
+- Added a startup entrypoint; on `session_start(reason:"startup")` the extension opens the
+  dashboard **directly** from the startup event with hidden Pi header/footer chrome, so users
+  can launch with `pi /agent-board` into a cleaner fullscreen surface. Quitting that dashboard
+  exits Pi instead of dropping into a chat session.
+
+
+### CP2 — 2026-05-30 — full MVP wired (M2–M5) + ⚠️ real-worker hang found
+- Built the Pi-coupled layer: `src/runtime/service.mjs` (dispatch/reply/stop/pin/rename/
+  archive/reconcile + same-repo worktree safety), `src/ui/dashboard.ts` (one `ctx.ui.custom`
+  component: list/peek/reply/dispatch/filter/rename/confirm/help modes, live 700ms poll, scroll),
+  `src/commands/agent-board.ts` (`/agent-board` command + action loop + attach via `ctx.switchSession`),
+  `src/index.ts` (entry: command, footer status, session_start recovery),
+  root `index.ts` (re-export for auto-discovery).
+- **`npx tsc --noEmit` = 0 errors** against the real Pi `.d.ts` (path-mapped). **45/45 tests pass.**
+- **Smoke: `pi --list-models -e src/index.ts` loads the extension cleanly** (factory + all imports
+  resolve under pi's jiti, exit 0).
+- **⚠️ REAL-WORKER HANG (env auth, not a bug):** running the real `pi` worker through the runner
+  (and `pi --mode json -p` directly) **blocks at the provider request** — emits up to the *user*
+  `message_end` then nothing (no assistant reply, no `agent_end`, no exit; idle 3% CPU). Cause:
+  pi has no working provider auth/network in this non-interactive context (pi auth ≠ Claude
+  Code `/login`). The credential-scan probe was (correctly) blocked by the sandbox classifier.
+  Extension behaves correctly: row stays `working` until stopped. **To validate live dispatch,
+  pi itself must be authed** — see `VERIFY.md`. Hermetic fake-pi tests prove the runner pipeline.
+- **Change (user):** default summary model → **`gpt-4o`** (was claude-haiku-4-5). Still ON by
+  default, heuristic fallback retained. Needs OpenAI auth or it falls back.
+- **UX fix (nuance):** runner now persists the terminal state (heuristic summary) **immediately**
+  on worker close, *then* upgrades the summary via the model (15s timeout) and re-persists — so a
+  slow/unreachable summary model can't delay a row flipping to `completed`.
+
+
+### CP0 — 2026-05-30 — recon done, scaffolding started
+- Read full Pi API (extensions, tui, sessions, json, session-format) + subagent/plan-mode
+  examples + dist type defs. Findings distilled into `docs/EXPLORATION.md` (read that first).
+- **Decisions locked for impl** (see EXPLORATION §8): detached `.mjs` runner spawns
+  `pi --mode json -p --session <file> "<prompt>"`; dashboard is one `ctx.ui.custom` component;
+  heuristics are the default summarizer (model summary opt-in); attach = `ctx.switchSession`.
+- **Workaround/nuance:**
+  - Node 24 runs `.ts` directly (type-stripping) ⇒ unit tests need no build step; write
+    pure-logic modules with only `node:*` imports so `node --test` can run them.
+  - **Avoid `typebox`**: MVP has no LLM-facing tool; `/agent-board` is a command. Store schemas are
+    plain TS interfaces (erasable), not typebox — keeps modules node-testable & dep-free.
+  - Pi packages aren't in this repo's node_modules; they're resolved by Pi's jiti at runtime.
+    For local typecheck only, `tsconfig.json` path-maps `@earendil-works/*` to the global
+    install. Runtime needs no install.
+  - Verification can't use a TTY/API key here ⇒ integration test runs the real runner against
+    a **fake pi** stub (`test-support/fake-pi.mjs`) that prints canned JSON event lines.
+
+---
+
+### CP1 — 2026-05-30 — core brain + runner green (M0+M1)
+- Wrote `src/core/*.mjs`: paths, ids, atomic, types, heuristics, derive, events, pid, store,
+  repo, worktree, launch, invocation, rows. All pure node, JSDoc-typed.
+- Wrote `runner/job-runner.mjs` (detached monitor) + `test-support/fake-pi.mjs` (hermetic
+  worker stub) + 7 test files. **`node --test` → 45/45 pass.** Validates dispatch→events→
+  status/state→finalize, needs_input/failed/stopped classification, and durable artifacts,
+  all without an API key or TTY.
+- **Design fix (nuance):** `latestAssistantPreview` now stores the *full* latest assistant text
+  (truncated 240) so peek shows real output; `deriveSummary()` condenses it to a first sentence
+  (falling back to full text if the 1st sentence is <12 chars, e.g. "Done."). Don't re-conflate.
+- **Change per user:** cheap-model summary is now **ON by default** (`DEFAULT_SUMMARY_MODEL=
+  claude-haiku-4-5` in the runner), heuristic kept as graceful fallback (no-key/offline/timeout)
+  and for state detection. Disable with `AGENT_BOARD_SUMMARY_MODEL=off`; override with a model id.
+  Tests set it `off` so the fake worker's stream doesn't get re-summarized.
+- **Invocation nuance:** `src/core/invocation.mjs` resolves how to spawn pi (node+cli.js vs
+  compiled binary vs `pi` on PATH) — mirrors the subagent example. Runner runs under real `node`.
+- **pid nuance:** `pid.json` holds the *runner/monitor* pid (parent polls it for liveness);
+  `status.json.pid` holds the *worker* pid. `isAlive` treats EPERM as alive.
+
+## Known risks / open items
+- `ctx.ui.custom` full-screen height: drive off `tui.terminal.rows`; verify scrolling math.
+- Worktree edge cases (dirty repo, cleanup) — M5; ship strict single-writer rule first.
+- Model summarizer spawns a pi process per summary — must throttle; default off.