@huseynsnmz/pi-board 0.15.3 → 0.16.0

package/VERIFY.md

@@ -1,115 +0,0 @@
-# Manual Verification
-
-Steps you can run yourself to check the extension. Grouped from "no auth needed" to
-"needs pi provider auth". Commands assume you're in the repo root.
-
----
-
-## 0. Static checks (no auth, fast)
-
-```bash
-npm install          # dev + runtime deps
-npm run typecheck    # expect: 0 errors
-npm run test:perf    # expect: `burst:`/`paced:` value lines, pass 3 / skipped 0 — the ONLY path that measures perf assertions; they skip under npm test (issue #121)
-npm test             # expect: 0 failures (the 3 A11 perf tests skip here, reason points at `npm run test:perf`)
-npm run pack:dry     # expect: pi-agent-board-<version>.tgz contents only include deploy files
-```
-
-`npm test` includes a hermetic integration test that runs the **real detached runner** against
-a fake pi worker (`test-support/fake-pi.mjs`) — it proves dispatch → events → status/state →
-finalize (completed / needs_input / failed / stopped) without any model/network.
-
-## 1. Does the extension load in pi? (no auth)
-
-```bash
-pi --list-models -e "$(pwd)/src/index.ts"
-```
-Expect a normal model table and **exit 0** (the extension factory ran without throwing). If you
-see an error mentioning `index.ts` / jiti / a missing import, that's a load problem.
-
-## 2. CRITICAL: can pi reach a model at all? (needs pi auth)
-
-This is the thing that was blocked in the dev sandbox. The background worker is just
-`pi --mode json -p --session <file> "<prompt>"`, so first confirm a plain one-shot works:
-
-```bash
-# Should print a JSON event stream that ENDS WITH a line of type "agent_end", then exit
-# within a few seconds. Watch for an "assistant" message_end before agent_end.
-pi --mode json -p --no-session "Reply with exactly: DONE" | tail -n 20
-```
-- ✅ **Healthy:** you see `...message_end (assistant)...`, then `agent_end`, and the command exits.
-- ❌ **Hang:** it prints up to a `message_end` for the **user** message then sits idle (no
-  assistant reply, never exits). That means pi has no working provider auth / network here.
-  Fix pi's auth first:
-  ```bash
-  pi            # then run /login inside pi, or set the provider key pi expects, e.g.
-  # export ANTHROPIC_API_KEY=...   (or OPENAI_API_KEY=... for gpt-4o summaries)
-  ```
-  Re-run the one-shot above until it ends in `agent_end`. The dashboard cannot show live results
-  until this works — it's a pi setup step, independent of this extension.
-
-## 3. Install the extension for normal use
-
-For a local checkout, install it as a Pi package:
-```bash
-pi install "$(pwd)"
-```
-Or symlink the repo into pi's global extensions dir (auto-discovered via the top-level `index.ts`):
-```bash
-ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board
-```
-After publish, install with:
-```bash
-pi install npm:@zhuxixi/pi-agent-board
-```
-Then start pi normally:
-```bash
-pi
-```
-
-## 4. Drive the dashboard
-
-Inside pi:
-1. Type `/agent-board`, or start with `pi /agent-board` → the full-screen dashboard opens.
-   - With `pi /agent-board`, quitting the dashboard exits Pi instead of dropping you into a normal chat session.
-   - The startup path should feel cleaner than `/agent-board`: no normal Pi header/footer chrome and no dispatch notifications above the dashboard.
-2. Press **i** to enter INSERT mode, then type a task in the bottom input (e.g. `list the files in this repo and summarize the README`) and press **Enter**.
-   - A **Start session** dialog opens with **Start session** focused by default.
-   - Press **Enter** again to launch immediately, or move with **↑/↓** to change **cwd**, **model**, or **thinking** first.
-   - With automatic Done disabled by default, a successful run settles in **Needs instructions** until you review it and press **d** to confirm **Done**. Set `AGENT_BOARD_AUTO_STATE_NO_DONE=0` to restore automatic Done classification for this verification path.
-3. **space** = peek when the input is empty (summary, blocker, latest output); in peek **r** = reply, **a** = attach.
-   **→** / **>** = open a full-screen live session view without interrupting; **←** / **<** returns.
-4. **enter** on an empty input = attach to the selected full session (confirms first if it's still running).
-   You're now in the real Pi session; run `/agent-board` again to return.
-5. Other keys: **/** filter (`s:running`, or free text), **Ctrl+R** rename, **Ctrl+T** pin, **Ctrl+S** stop,
-   **x** then **y** delete (confirm prompt; archives the row, keeps the session file), **Ctrl+X** ×2 quick delete (no confirm),
-   **?** help, **Esc** clears input / quits when empty.
-
-## 5. Inspect the durable store on disk
-
-```bash
-ls -R ~/.pi/agent/agent-board
-cat ~/.pi/agent/agent-board/roster.json
-cat ~/.pi/agent/agent-board/views/*/state.json
-cat ~/.pi/agent/agent-board/views/*/runs/*/status.json
-# raw worker event stream for a run:
-cat ~/.pi/agent/agent-board/views/*/runs/*/events.jsonl
-```
-
-## 6. Recovery / persistence
-
-- Start a dispatch, then quit pi (or `/reload`). Re-open pi and `/agent-board` — the row is still
-  there with its last state (rehydrated from disk). If a run's runner died without finishing,
-  the dashboard reconciles it to `failed (runner exited)` on open.
-
-## 7. Same-repo session launches
-
-- Dispatch one task in a git repo, then (while it's running) dispatch a second in the
-  **same repo**. Both launches should be allowed. The extension never creates a git worktree on
-  its own.
-
-## 8. Summary model
-
-Default summary model is **gpt-4o** (override `AGENT_BOARD_SUMMARY_MODEL=<model>`, disable with
-`AGENT_BOARD_SUMMARY_MODEL=off`; legacy `AGENT_VIEW_SUMMARY_MODEL` is also honored). It needs OpenAI auth; without it the row keeps its heuristic
-summary (e.g. the first sentence of the agent's last message or the active tool).

package/docs/BATCH_SELECTION_READ_FLOW.md

@@ -1,277 +0,0 @@
-# Batch Selection + Read/Unread Flow
-
-**Status:** Proposed  
-**Context:** Pi Agent Board dashboard  
-**Created:** 2026-06-02
-
-## Assumption
-
-"Move to done to delete that batch" is treated as a **safe 2-step cleanup flow**:
-
-1. bulk-select sessions,
-2. move them to **Done**,
-3. optionally delete that same batch from **Done** with a second explicit confirmation.
-
-This keeps "done" non-destructive and makes deletion intentional.
-
----
-
-## 1. Goals
-
-### A. Multi-session selection
-- Let users select multiple rows from the board.
-- Let users batch-mark them as **Done**.
-- Let users immediately clean up that same batch from the **Done** group.
-
-### B. Read / Unread
-- Mark a session as **Read** once the user has actually visited it via attach / transcript-style deep view.
-- Show a **subtle unread hint** on rows with unseen activity.
-- If new activity happens after a visit, the row becomes **Unread** again.
-
----
-
-## 2. UX overview
-
-### Normal mode
-- Board behaves exactly like today: single active row, peek, attach, done, delete.
-
-### Selection mode
-- User enters a temporary **multi-select mode**.
-- Selection count appears in header/footer: `3 selected`.
-- Rows show a subtle selected marker.
-- Actions become batch-oriented:
-  - **Mark selected done**
-  - **Delete selected** (only from Done, with confirm)
-  - **Clear selection**
-
-### Read state
-- Rows can be either:
-  - **Unread** = new activity since last visit
-  - **Read** = user has already visited the latest activity
-- Unread should not overpower semantic state; it is a secondary signal.
-
----
-
-## 3. Multi-session selection flow
-
-## 3.1 Enter selection mode
-
-**Trigger**
-- User presses a dedicated shortcut from board list view.
-- Suggested shortcut: `m` for **multi-select**.
-
-**Result**
-- Footer changes to selection hints.
-- Selection starts empty; the current row stays focused but is **not** auto-selected.
-- Header shows selection count.
-
----
-
-## 3.2 Build the selection
-
-While in selection mode:
-- `↑ / ↓` moves cursor
-- `space` toggles current row in selection
-- `a` selects all visible rows in current filter/group
-- `u` clears the current selection without leaving selection mode
-- `esc` clears selection and exits selection mode
-
-Optional later:
-- `A` = select all rows in current state group
-- `u` = unselect all
-
----
-
-## 3.3 Move selected rows to Done
-
-**Trigger**
-- User presses `d` while in selection mode.
-
-**Confirmation copy**
-- `Mark 5 selected sessions as done? (y/N)`
-
-**Rules**
-- Running/live rows are skipped.
-- Needs-input / idle / failed / stopped rows may be moved to Done.
-- Confirmation should mention skipped rows if any.
-
-**Result**
-- Matching rows are moved to `Done`.
-- The same rows remain selected.
-- Board auto-scrolls/focuses to the `Done` section.
-- Toast example: `Moved 5 to Done · skipped 2 live`
-
-This preserves the batch as a temporary working set for cleanup.
-
----
-
-## 3.4 Delete the same batch from Done
-
-**Trigger**
-- With the same batch still selected, user presses `ctrl+x` or a batch delete key.
-
-**Guardrail**
-- Deletion is only enabled when all selected rows are already in `Done`.
-- If selection includes non-Done rows, show: `Only Done sessions can be batch deleted`.
-
-**Confirmation copy**
-- `Delete 5 done sessions? Session files are preserved. (y/N)`
-
-**Result**
-- Selected rows are archived from dashboard.
-- Selection clears.
-- Toast example: `Deleted 5 done sessions`
-
----
-
-## 4. Read / Unread flow
-
-## 4.1 What counts as Read
-
-A session becomes **Read** when the user intentionally opens that session in a deeper way:
-- attach via `enter` / `→`
-- transcript/full-session view
-
-**Not read by default:**
-- merely highlighting a row
-- passive polling updates
-- quick list navigation
-- optional: peek can remain non-read to preserve signal
-
----
-
-## 4.2 When a row becomes Unread again
-
-A previously read row becomes **Unread** when a new assistant reply lands after the last visit, for example:
-- new assistant message
-- new blocker/question raised in that message
-- session re-enters `needs_input` because of that message
-
-User-authored actions alone should not create unread state, and intermediate tool churn alone should not flip unread.
-
----
-
-## 4.3 Recommended subtle hint
-
-Use the **stage icon itself** as the unread signal:
-- **Unread:** stronger/heavier variant of that stage icon
-- **Read:** lighter/default variant of that stage icon
-
-Examples:
-- queued: `○` → `◎`
-- needs input: `◇` → `◆`
-- done: `✓` → `✔`
-
-Optional secondary treatment:
-- unread row title slightly brighter
-- read row title normal
-
-Avoid:
-- loud badges like `UNREAD`
-- full-row highlight
-- strong color conflict with semantic states like Failed / Needs input
-
-### Priority of signals
-1. semantic state (Running, Needs input, Done, Failed)
-2. selection state
-3. unread hint
-
-Unread should help scanning, not dominate the board.
-
----
-
-## 5. State model
-
-## 5.1 Batch selection
-
-Selection can stay **ephemeral UI state** in the dashboard component:
-- `selectedIds: Set<string>`
-- `selectionMode: boolean`
-
-No persistence needed for V1.
-
-## 5.2 Read state
-
-Recommended durable fields:
-- `lastVisitedAt: number | null`
-- `lastAgentActivityAt: number | null`
-
-Derived flag:
-- `isUnread = lastAgentActivityAt > lastVisitedAt`
-
-This is simpler and more reliable than storing a raw boolean.
-
----
-
-## 6. Edge cases
-
-### Live rows inside a batch
-- Cannot be batch-done or batch-deleted.
-- Skip and report counts.
-
-### Mixed-state selection
-- Batch done: allowed for inactive non-done rows.
-- Batch delete: only allowed if every selected row is already Done.
-
-### New activity during selection
-- Keep row selected.
-- If it receives new output, unread hint can appear even while selected.
-
-### Re-attaching to a row
-- Refresh `lastVisitedAt`.
-- Any prior unread marker clears.
-
-### Peek behavior
-- Recommend: peek does **not** mark read.
-- Reason: peek is triage, attach/transcript is actual visit.
-
----
-
-## 7. Suggested implementation slices
-
-### Dashboard (`src/ui/dashboard.ts`)
-- add selection mode
-- add `selectedIds`
-- batch confirm flows
-- render selected marker + unread marker
-
-### Service (`src/runtime/service.mjs`)
-- add `markCompletedMany(viewIds)`
-- add `archiveMany(viewIds)`
-- add `markVisited(viewId)`
-
-### Store/types (`src/core/types.mjs`, `src/core/store.mjs`)
-- add read-tracking timestamps
-- expose unread derivation on rows
-
-### Attach / session view entry points
-- mark row visited when attach or transcript view opens
-
----
-
-## 8. Recommended default interaction summary
-
-### Batch
-- `m` enter multi-select
-- `space` toggle row
-- `a` select all visible
-- `u` clear selection
-- `d` move selected to Done
-- `ctrl+x` delete selected Done batch
-- `esc` clear/exit
-
-### Read state
-- attach / transcript => mark read
-- new assistant reply => unread again
-- unread indicator => subtle left dot/bar
-
----
-
-## 9. Acceptance criteria
-
-- User can select multiple sessions from the board.
-- User can mark that selection Done in one action.
-- User can immediately delete that same batch from Done with explicit confirmation.
-- A session becomes Read after attach/transcript visit.
-- New agent activity turns a previously read row back to Unread.
-- Unread is visible through a subtle row hint, not a loud badge.

package/docs/EXPLORATION.md

@@ -1,187 +0,0 @@
-# Exploration & Decisions — Pi Agent Board Extension
-
-**For future agents.** This is the distilled gist of the codebase recon done before
-implementing `IMPLEMENTATION_PLAN.md`. Read this first; it saves re-deriving the Pi API.
-
-Runtime target: `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent` (v0.75.5).
-`pi` binary is on PATH at `/opt/homebrew/bin/pi` → `dist/cli.js`.
-
----
-
-## 1. How a Pi extension is loaded & shaped
-
-- An extension is a TS module: `export default function (pi: ExtensionAPI) { ... }`
-  (may be `async`; Pi awaits it before `session_start`).
-- Auto-discovered from `~/.pi/agent/extensions/*.ts` or `<name>/index.ts` (global) and
-  `.pi/extensions/...` (project). `/reload` hot-reloads them. `pi -e ./path.ts` for quick tests.
-- Pi's loader (jiti) resolves `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`,
-  `@earendil-works/pi-tui`, `typebox` **for you at runtime** — you do not bundle them.
-  For local typechecking we path-map those to the global install (see `tsconfig.json`).
-- Loaded TS runs via jiti. **Detached external processes (our runner) must NOT rely on
-  jiti** → the runner is a plain `.mjs` that we spawn with `node`.
-
-## 2. ExtensionAPI surface we actually use
-
-- `pi.registerCommand(name, { description, handler(args, ctx), getArgumentCompletions? })`
-  — handler `ctx` is `ExtensionCommandContext` (adds `newSession/fork/switchSession/
-  navigateTree/reload/waitForIdle`). Session-switch methods deadlock from event handlers,
-  so they exist only on command ctx.
-- `pi.registerShortcut(KeyId, { description, handler(ctx) })`.
-- `pi.registerFlag(name, { description, type:"boolean"|"string", default })` + `pi.getFlag`.
-- `pi.exec(cmd, args, { signal, timeout })` → `{ stdout, stderr, code, killed }`.
-- `pi.appendEntry(customType, data)` persists extension state into the session JSONL
-  (custom entry, not sent to LLM). Restore by scanning `ctx.sessionManager.getEntries()`.
-- `ctx.ui.*`: `select/confirm/input/editor/notify`, `setStatus/setWidget/setFooter`,
-  and **`custom<T>(factory, opts?) => Promise<T>`** (the dashboard surface).
-- `ctx.switchSession(path, { withSession })` — attach = switch the interactive session to
-  a managed session file. `withSession(ctx)` runs **after** the old runtime is torn down;
-  only use the fresh `ctx` passed in, never captured old `pi`/`ctx`/`sessionManager`.
-
-### `ctx.ui.custom` (the important one)
-```ts
-const result = await ctx.ui.custom<T>((tui, theme, keybindings, done) => {
-  // return a Component: { render(width): string[]; invalidate(); handleInput?(data) }
-  // call tui.requestRender() after state changes to repaint
-  // call done(value) to close the surface and resolve the promise
-});
-```
-- It **replaces the editor** with your component until `done()` (full-screen-ish surface).
-- It returns a `Promise`, NOT a handle. Live updates: hold a `tui` ref, call
-  `tui.requestRender()` from a `setInterval`/file-watch/poll loop. Terminal height =
-  `tui.terminal.rows`, width comes in as the `render(width)` arg.
-- `{ overlay: true, overlayOptions }` renders a floating modal instead (used for peek/dialogs
-  if we want; MVP keeps peek as an internal mode of the dashboard component).
-
-## 3. TUI building blocks (`@earendil-works/pi-tui`)
-
-Components implement `{ render(width:number):string[]; invalidate():void; handleInput?(data):void }`
-— each rendered line **must not exceed `width`** (use `truncateToWidth`).
-Exports we use: `Text, Box, Container, Spacer, Markdown, SelectList, SettingsList,
-matchesKey, Key, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component`.
-From coding-agent: `DynamicBorder, BorderedLoader, getMarkdownTheme, getSettingsListTheme,
-keyHint`. Theme: `theme.fg(color, text)`, `theme.bold/italic/strikethrough`.
-Key input: `matchesKey(data, Key.up)` etc. After state change in `handleInput`, call
-`tui.requestRender()`.
-
-## 4. Sessions & the headless worker (the core mechanism)
-
-- Session files are JSONL trees (`id`/`parentId`); first line is a header
-  `{"type":"session","version":3,"id":"<uuid>","timestamp":"<iso>","cwd":"<cwd>"}`.
-- **Launching a managed run:**
-  `pi --mode json -p --session <file> "<prompt>"`, spawned with `cwd: <repo|worktree>`.
-  - `--session <path>` with a path that contains `/` or ends `.jsonl` → `SessionManager.open(path)`.
-    If the file **doesn't exist**, Pi creates a fresh session and persists to that **exact path**
-    (verified in `dist/core/session-manager.ts` `open()` → `setSessionFile` else-branch).
-    The header `cwd` becomes the spawn `cwd`, so always set `cwd` correctly.
-  - `--mode json` = one-shot: it `session.subscribe((e)=>stdout(JSON.stringify(e)+"\n"))`,
-    runs the single prompt to completion (a full agent loop, many turns/tools), then exits
-    **with `agent_end` as the last event** — `worker.on("close")` is the run-finished signal.
-  - **⚠️ AUTH/NETWORK CAVEAT (verified 2026-05-30):** the one-shot exits cleanly *only when the
-    worker can actually reach the model provider*. With no/blocked pi provider auth (or a
-    network/proxy stall), `pi --mode json -p` records `session → agent_start → turn_start →
-    message_start(user) → message_end(user)` and then **blocks indefinitely at the provider
-    request** (idle, ~3% CPU) — **no assistant reply, no `agent_end`, no process exit**. This is
-    a pi/runtime condition, NOT an extension bug. The runner handles it correctly: the row stays
-    `working/alive` until the user stops it (`s` in the dashboard → SIGTERM → finalized `stopped`).
-    Note: pi's own provider auth is separate from Claude Code's `/login`. Validate with
-    `pi --mode json -p --no-session "say hi"` — it must print events ending in `agent_end` and exit.
-  - `-p` forces non-interactive. `--model <m>`, `--tools a,b`, `--append-system-prompt <file>`
-    are available. `--no-session` = ephemeral (we do NOT use it for managed rows; we want persistence).
-- Reply / resume = launch another run against the **same** `--session <file>`; Pi appends to it.
-
-### JSON event vocabulary actually emitted (parse these in the runner)
-First line: the session header `{type:"session",...}`. Then per `AgentSessionEvent`:
-`agent_start`, `agent_end`, `turn_start`, `turn_end`,
-`message_start` / `message_update` / `message_end` (each has `.message`: an AgentMessage),
-`tool_execution_start` `{toolCallId,toolName,args}`,
-`tool_execution_update` `{...,partialResult}`,
-`tool_execution_end` `{toolCallId,toolName,result,isError}`,
-`tool_call`, `tool_result`, plus `queue_update`, `compaction_*`, `auto_retry_*`,
-`model_select`, `thinking_level_*`, `session_*`.
-> NOTE: the subagent example reads `tool_result_end` — that string is **never emitted** (dead
-> defensive code). Use `message_end` (role assistant → text/toolCalls/usage/stopReason/errorMessage)
-> and `tool_execution_start/end` for live state. `agent_end` ⇒ run finished.
-
-AssistantMessage shape: `{ role:"assistant", content:(TextContent|ThinkingContent|ToolCall)[],
-model, usage, stopReason:"stop"|"length"|"toolUse"|"error"|"aborted", errorMessage? }`.
-ToolCall content block: `{ type:"toolCall", id, name, arguments }`.
-
-## 5. Architecture chosen (matches plan §3.3) — file-backed detached runner
-
-```
-Pi extension (parent, interactive)         runner/job-runner.mjs (detached, 1 per run)
-  /agent-board dashboard (ctx.ui.custom)   ─►   spawns: pi --mode json -p --session <file> <prompt>
-  store reader/writer                       parses JSON event lines from worker stdout
-  launches runner via child_process         writes runs/<runId>/{status.json,events.jsonl,
-  polls store files to repaint                stdout.log,stderr.log,pid.json}
-                                            updates views/<id>/state.json on progress/exit
-```
-Why detached `.mjs` runner (not spawn pi directly from the extension, not a daemon):
-survives parent `/reload`/exit, durable status, no socket/daemon complexity. Each run is the
-durable monitor for one worker.
-
-### Store layout (user-scoped) — `~/.pi/agent/agent-board/`
-```
-roster.json                      { version, views: [viewId...] }
-views/<viewId>/meta.json         stable: id,name,cwd,sessionFile,createdAt,pinned,kind,
-                                 worktreeMode,worktreePath,defaultModel,source,archived
-views/<viewId>/state.json        derived: currentRunId,semanticState,processState,summary,
-                                 needsInput,hasError,latestAssistantPreview,latestTool,lastActivityAt
-views/<viewId>/runs/<runId>/status.json   per-run durable snapshot (pid,startedAt,endedAt,
-                                 exitCode,semanticState,currentTool,latestAssistantPreview,question,error)
-views/<viewId>/runs/<runId>/{events.jsonl,stdout.log,stderr.log,pid.json}
-sessions/<viewId>.jsonl          the managed Pi session file (Pi creates/persists it)
-```
-- One row = one real Pi session file. One run = one detached worker against it.
-- Both `state.json` (row, long-lived) and `status.json` (run, single attempt) exist so
-  reply/resume/attach stay clean.
-- Atomic writes: write tmp + `rename`. Liveness: `pid.json` + `process.kill(pid,0)`.
-
-## 6. State derivation rules (plan §9)
-
-Semantic: `queued`→`working` (alive, once assistant/tool activity); on clean exit
-`needs_input` (assistant ends asking) | `completed` | `idle`; on bad exit `failed`;
-user-stopped `stopped`. Process: `alive` if pid live else `exited`.
-Summary priority: model-summary(opt-in) → active tool (`Editing x`,`Running tests`) →
-blocker/question → first sentence of latest assistant → stderr/error → fallback status.
-Needs-input heuristic: assistant text ends in `?` or contains `need your input`/
-`which option`/`should I`/`please confirm`.
-
-## 7. Safety / worktree (plan §11)
-
-Same-repo parallel **writers** require git worktree isolation (locked decision). MVP:
-explicit `worktreeMode:"worktree"` per dispatch → `git worktree add` under
-`~/.pi/agent/agent-board/worktrees/<viewId>`; persist `worktreePath`; block a 2nd active
-writer in the same repo if not isolated. Delete row ≠ delete data: archive row, keep
-session file; worktree removal needs explicit confirm.
-
-## 8. Decisions made for this implementation
-
-1. **Runner is `runner/job-runner.mjs` (plain ESM)**, spawned with `node`. It imports only
-   `node:*`. The pi binary it spawns is passed in via run-config (`piBin`, default `"pi"`).
-2. **Extension code is TS**, loaded by Pi via jiti. We add `package.json` + `tsconfig.json`
-   only for local typecheck/tests (path-mapped to the global pi install); not needed at runtime.
-3. **Summaries: cheap model is the DEFAULT** (`DEFAULT_SUMMARY_MODEL = "gpt-4o"` in the runner;
-   user choice 2026-05-30), with the **heuristic kept as a graceful fallback** (no API key /
-   offline / timeout) and still used for live state detection (needs-input, semantic state).
-   Override with `AGENT_BOARD_SUMMARY_MODEL=<model>`, disable with `=off`. The summary call has a
-   15s safety timeout and runs *after* the heuristic terminal state is already persisted, so a
-   slow/unreachable summary model never stalls the dashboard (row flips to final state at once,
-   summary upgrades a few seconds later). gpt-4o needs OpenAI auth; without it → heuristic.
-4. **Dashboard = single `ctx.ui.custom` component** owning list + peek + dispatch input as
-   internal modes (plan §10.4 recommendation). Live updates via a poll loop calling
-   `tui.requestRender()` (store files are the source of truth; cheap to re-read).
-5. **Attach = `ctx.switchSession(sessionFile, { withSession })`** from the `/agent-board` command
-   handler. If the row's run is alive → confirm interrupt (stop run) then attach (locked decision).
-6. **Verification without a TTY/API key:** unit tests for all pure logic + an integration test
-   that runs the real `.mjs` runner against a **fake `pi`** stub script emitting canned JSON
-   event lines, asserting the durable store artifacts. (`test-support/fake-pi.mjs`.)
-
-## 9. Gotchas
-
-- `ctx.ui.custom` callback's component must return lines ≤ width; always `truncateToWidth`.
-- Rebuild themed content on `invalidate()` (theme change) if you pre-bake `theme.fg(...)`.
-- Don't import `pi-subagents/src/...` internals (unstable) — reference only.
-- Session-switch `withSession` runs post-teardown; capture only plain strings/ids.
-- The runner must update `status.json` atomically and frequently but throttled (avoid fs thrash).
-- `process.kill(pid, 0)` throws ESRCH if dead, EPERM if alive-but-not-ours → treat EPERM as alive.