@zhuxixi/pi-agent-board 0.5.0 → 0.5.2

package/PROGRESS.md

@@ -23,6 +23,19 @@ Status legend: ☐ todo · ◐ in progress · ☑ done
 
 ## Checkpoint log
 
+### CP5 — 2026-08-30 — hot attach self-heal + safe detach ordering (issue #42)
+- Added G6 post-restore verification: if a hot session's in-flight differential frame makes
+  shrink+restore collapse to a net-zero resize, the controller re-shrinks after 900ms without
+  a clear; the retry budget remains bounded and G1–G5 behavior is preserved.
+- Restored Pi editor key compatibility: `ctrl+]` passes through to `tui.editor.jumpForward`;
+  only `←` on an empty child input detaches.
+- Fixed G3 ordering so a held PTY is restored before the runner receives `detach` and closes
+  the control socket.
+- Added hot-session PTY E2E, delayed-clear, external-resize, detach-order, minimum-size, socket-identity,
+  and failure-teardown coverage. Final pre-PR verification: `npm run verify` passed with 409/409 tests;
+  coverage 93.03% lines / 77.35% branches / 90.55% functions; pack dry-run clean. The SIGKILL escalation
+  path is proven by the ~4.1s shutdown-escalation test (SIGTERM-immune child via `trap`+`exec`).
+
 ### 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
@@ -33,12 +46,14 @@ Status legend: ☐ todo · ◐ in progress · ☑ done
   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.
+- Fixed PTY detach flow: `←` from an empty child input returns to the dashboard loop instead of
+  revealing the original session where `/agent-board` was invoked. `ctrl+]` and `ctrl+g` pass
+  through to the hosted Pi editor's native shortcuts.
 - 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.
+- Historical verification: `npm run typecheck` clean; `npm test` 55/55 green at the time of CP4.
+  Later checkpoints supersede this count.
 
 ### CP3 — 2026-05-30 — standalone-ish dashboard UX
 - Added a full-screen **session view** inside `/agent-board`: **v** opens the selected row's

package/README.md

@@ -10,126 +10,343 @@
   | <a href="https://www.npmjs.com/package/@zhuxixi/pi-agent-board">npm</a>
 </p>
 
-Pi Agent Board is a full-screen TUI dashboard for [Pi](https://github.com/earendil-works/pi-mono). It lets you dispatch, monitor, peek/reply to, attach to, and clean up multiple background Pi sessions from one place.
+Pi Agent Board is a full-screen TUI dashboard for [Pi](https://github.com/earendil-works/pi-mono) that manages durable background Pi sessions. Use one global board to dispatch work across projects, watch progress, triage summaries and evidence, reply without opening a transcript, and attach to a real interactive session when hands-on work is needed.
 
-## Problems It Solves
+## What It Does
 
-- Run several Pi tasks at once without losing track of which are queued, running, needs answer, needs instructions, done, failed, or stopped.
-- Keep real Pi sessions durable and resumable after `/reload`, closing Pi, or restarting the terminal.
-- Check the latest output and answer follow-up questions without interrupting a running session.
-- Attach to the full interactive Pi session only when hands-on work is needed.
-- Manage work across multiple projects in one global board.
+- Run several Pi tasks at once without losing track of their current state.
+- Keep each task as a real, resumable Pi session that survives `/reload`, closing Pi, or restarting the terminal.
+- Triage the latest output, blockers, evidence, and diagnostics before opening a full transcript.
+- Reply to a session without attaching; replies sent while a session is busy are preserved for later delivery.
+- Fall back to a JSON runner for eligible background work when live PTY support is unavailable.
 
-## Install
+> **Write-safety note:** Worktree isolation is currently disabled. Multiple sessions in the same repository may run concurrently, so avoid overlapping writes or provide your own isolation.
+
+## Requirements
+
+- [Pi](https://github.com/earendil-works/pi-mono) installed and working.
+- Node.js 20 or newer.
+- Working Pi provider authentication for real model execution. Agent Board does not have a separate login or credential store.
+- PTY support from `node-pty` for live attach and **start & attach**. Background work can use a JSON-runner fallback when PTY support is unavailable.
 
-From npm:
+If rows remain in `Running`, first verify that Pi itself can complete a one-shot model call:
 
 ```bash
-pi install npm:@zhuxixi/pi-agent-board
-pi /agent-board
+pi --mode json -p --no-session "Reply with exactly: DONE"
 ```
 
-You can also start Pi normally and run `/agent-board`.
+A healthy command emits an assistant `message_end`, then an `agent_end` event, and exits. See [VERIFY.md](VERIFY.md) for the complete no-auth, provider-auth, and PTY checks.
+
+## Install
 
-Pi Agent Board requires Node 20+ and working Pi provider auth. If rows stay in `Running`, first confirm Pi can complete a one-shot model call:
+### Published package
 
 ```bash
-pi --mode json -p --no-session "Reply with exactly: DONE"
+pi install npm:@zhuxixi/pi-agent-board
 ```
 
-That command should produce an assistant reply and finish with an `agent_end` event.
+Start Pi normally and run `/agent-board`, or use one of the startup entry points below.
 
-From a local checkout:
+### Local checkout
 
 ```bash
 npm install
 pi install "$(pwd)"
-pi /agent-board
 ```
 
-For auto-discovery while developing:
+This installs the current checkout as a Pi package. Remove that path installation with:
+
+```bash
+pi remove "$(pwd)"
+```
+
+### Development auto-discovery
+
+To have Pi load the checkout directly while developing:
 
 ```bash
 ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board
 pi
 ```
 
-Remove that symlink when you no longer want Pi to auto-load the checkout. If you installed by path, remove it with `pi remove "$(pwd)"`.
+Remove the symlink when you no longer want Pi to auto-load the checkout:
+
+```bash
+rm ~/.pi/agent/extensions/agent-board
+```
 
-## Use
+## Quick Start
 
-Open the board with `pi /agent-board` or `/agent-board` inside Pi.
+Open the board with `/agent-board` inside Pi, then:
 
-- Type a task in the bottom input, then press `enter`.
-- Confirm **Start session**, or adjust `cwd`, model, and thinking level first.
-- Watch rows move through `Queued`, `Running`, `Needs answer`, `Needs instructions`, `Done`, `Failed`, and `Stopped`.
-- Press `space` to peek at the selected row's summary, blocker, and latest output.
-- Press `r` to reply inline without attaching.
-- Press `enter`, `right`, or `>` to attach to the real Pi session.
-- Press `v` for a read-only live transcript.
-- Press `/` to filter by text or state, such as `s:running`.
-- Press `ctrl+r` rename, `ctrl+t` pin, `ctrl+s` stop, `d` mark done, `m` multi-select, `ctrl+x` delete/archive, `X` delete inactive rows in the selected state, and `?` for help.
+1. Press `i` to enter INSERT mode.
+2. Type a task.
+3. Press `Enter` to open the **Start session** dialog.
+4. Review or change the working directory (`cwd`), model, thinking level, and action.
+5. Press `Enter` on **Start session** to launch the task.
 
-Rows are stored under `~/.pi/agent/agent-board/` by default. Deleting a row archives it from the board; it does not remove the underlying Pi session file.
+With a draft in the input, `Enter` opens **Start session**; with an empty input, `Enter` attaches/resumes the selected session. The row starts in `Queued`, then moves through `Running` to a terminal state such as `Needs answer`, `Needs instructions`, `Done`, `Failed`, or `Stopped`.
 
-## Configuration
+From the board:
+
+- Press `Space` to peek at the selected session's summary, blocker, and latest output.
+- In Peek, press `r` to reply without attaching.
+- Press `v` for a read-only transcript, or `e` for evidence and diagnostics.
+- Press `Enter`, `Right`, or `>` to attach to the real Pi session.
+- In PTY attach mode, press `Left` on an empty child input line to return to the board. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. When the host is disconnected, `Left` always exits.
+
+## Dashboard Workflow
+
+The dashboard has two input modes:
+
+- **Normal mode** owns dashboard shortcuts such as navigation, peek, attach, and filtering.
+- **INSERT mode** owns text editing. Press `i` before typing or pasting a task; `/` is literal while editing a prompt.
+
+When you submit a task, the **Start session** dialog lets you review:
 
-Useful environment variables:
+- `cwd`: an existing-directory picker with usage-ranked favorites, filesystem browsing, and Tab completion;
+- `model`: models available to Pi, including models scoped by the current directory's Pi settings;
+- `thinking`: a level supported by the selected model;
+- `action`: **start in background** or **start & attach**.
 
-| Variable | Use |
+Launch preferences are persisted and reused for later sessions. **Start & attach** requires PTY support; if PTY is unavailable, Agent Board launches the session in the background and shows a warning instead.
+
+Session actions are deliberately confirmation-aware:
+
+- `d` confirms moving an inactive session to **Done**. Manual completion is the default.
+- Press `Ctrl+X` twice quickly to archive/delete the selected row. Archiving removes the row from the board but preserves its underlying Pi session file.
+- `X` archives inactive rows in the selected state; live work is skipped.
+- `m` enters multi-select mode. Use `Space` to toggle rows, `a` to select all visible rows, `u` to clear the selection, `d` to mark inactive rows Done, or `Ctrl+X` to delete selected Done rows.
+
+## Views and Actions
+
+Shortcuts are scoped to the view where they are available:
+
+### Main list
+
+| Key | Action |
 | --- | --- |
-| `AGENT_BOARD_ROOT` | Store location. Defaults to `~/.pi/agent/agent-board/`. |
-| `AGENT_BOARD_AUTO_STATE=off` | Disable automatic terminal-state moves. |
-| `AGENT_BOARD_AUTO_STATE_MODEL=<model>` | Model for classifying finished turns. Defaults to `gpt-4o`; use `off` for heuristic-only. |
-| `AGENT_BOARD_AUTO_STATE_NO_DONE` | Disables automatic `completed` classification (default: enabled). Set to `0`/`false`/`off`/`no` to restore auto-done. |
-| `AGENT_BOARD_CODE_REFS=off` | Disable issue/PR badge extraction from session evidence. |
-| `AGENT_BOARD_SUMMARY_MODEL=<model>` | Model for short row summaries. Defaults to `gpt-4o`; use `off` to disable. |
-| `AGENT_BOARD_TITLE_MODEL=<model>` | Model for generated session titles. Defaults to `openai-codex/gpt-5.5`; use `off` to disable. |
-| `AGENT_BOARD_TITLE_THINKING_LEVEL=<level>` | Thinking level for title generation. Defaults to `low`; use `off` to omit it. |
-| `AGENT_BOARD_DISABLE_PTY=1` | Disable PTY attach mode. |
-| `AGENT_BOARD_IME_FIX=0` | Disable the IME cursor-rect coalescer (issue #28). The coalescer folds pi-tui's per-frame cursor-park writes into the frame's synchronized-output block so terminals report one stable IME cursor position per frame instead of two (candidate-window flicker in busy sessions). |
-| `AGENT_BOARD_FORCE_PTY=1` | Force PTY attach mode. |
-| `AGENT_BOARD_ATTACH_MOUSE=0` | Disable attach-view mouse handling and use terminal-native selection. |
-| `AGENT_BOARD_WHEEL_LINES=<1-50>` | Lines scrolled per mouse-wheel event in attach view. Defaults to `1`. |
-
-Legacy `AGENT_VIEW_*` variables are still honored for migration.
-
-If the board reports `node-pty unavailable`, press `!` in the dashboard for diagnosis and fix steps.
-
-## Develop
+| `Up` / `Down` | Move the selection. |
+| `i` | Enter INSERT mode for a new task. |
+| `Enter` | Open Start session for a draft, or attach/resume when the input is empty. |
+| `Right` / `>` | Attach to the selected session. |
+| `Space` | Open Peek. |
+| `v` | Open the read-only transcript. |
+| `e` | Open Evidence / Diagnostics. |
+| `/` | Enter filter mode. |
+| `Ctrl+N` | Enter INSERT mode with a pre-filled `hello` prompt; press `Enter` to open the Start session dialog. |
+| `Ctrl+R` | Rename the selected session. |
+| `Ctrl+T` | Pin or unpin the selected session. |
+| `Ctrl+S` | Stop the selected active session. |
+| `d` | Confirm marking the selected inactive session Done. |
+| `Ctrl+X` twice quickly | Archive/delete the selected row. |
+| `X` | Delete inactive rows in the selected state. |
+| `m` | Enter multi-select mode. |
+| `!` | Open node-pty diagnostics and repair hints. |
+| `?` | Open the help overlay. |
+| `Esc` | Clear a draft, or exit when the input is empty. |
+
+### Peek
+
+Peek shows the selected session's summary, blocker or question, latest output, and available issue/PR references.
+
+| Key | Action |
+| --- | --- |
+| `r` or `Enter` | Enter reply mode; type a follow-up and press `Enter` to send it without attaching. |
+| `a`, `Right`, or `>` | Attach to the session. |
+| `v` | Open the read-only transcript. |
+| `e` | Open Evidence / Diagnostics. |
+| `Up` / `Down` | Move to the previous or next session. |
+| `Esc` | Return to the main list. |
 
-```bash
-npm install
-npm run typecheck
-npm test
-npm run test:coverage
-npm run pack:dry
+When a Pi question or questionnaire tool is pending, inline reply is rejected; attach to answer that interactive question in the real Pi session.
+
+### Transcript
+
+The `v` view is a read-only projection of the durable Pi session JSONL. It does not interrupt a running worker.
+
+| Key | Action |
+| --- | --- |
+| `Up` / `Down` | Scroll one line. |
+| `PageUp` / `PageDown` | Scroll one page. |
+| `Space` | Open Peek. |
+| `r` | Enter reply mode. |
+| `Enter` or `a` | Attach to the session. |
+| `e` | Open Evidence / Diagnostics. |
+| `d` | Confirm marking the inactive session Done. |
+| `Left` / `Esc` / `<` | Return to the main list. |
+
+### Evidence / Diagnostics
+
+The `e` view shows durable session evidence, including changed files, commands and their outcomes, command output previews, assistant evidence, errors, diagnostics, and artifact paths. Press `x` to clear diagnostics while preserving the evidence artifacts.
+
+| Key | Action |
+| --- | --- |
+| `Up` / `Down` | Scroll one line. |
+| `PageUp` / `PageDown` | Scroll one page. |
+| `r` | Enter reply mode. |
+| `v` | Open the read-only transcript. |
+| `Enter`, `a`, or `Right` | Attach to the session. |
+| `x` | Clear diagnostics; evidence is preserved. |
+| `Left` / `Esc` / `<` | Return to the main list. |
+
+### PTY attach
+
+PTY attach opens the real interactive Pi session. On an empty child input line, use `Left` to detach and return to the board; while you are editing text, `Left` is forwarded to the Pi editor, and a disconnected host can always be exited with `Left`. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. While attached, `PageUp`, `PageDown`, `Home`, `End`, and the mouse wheel scroll local scrollback. Mouse drag or double-click selects and copies text, clicks open detected links, and middle-click paste is available on systems with the required X11 tooling.
+
+The attach surface can forward terminal clipboard and image/file passthrough sequences. These behaviors can be disabled individually in [Configuration](#configuration). Cold hosts may briefly show a loading/reconnect surface while their PTY becomes ready.
+
+## States, Grouping, and Filters
+
+Agent Board separates a session's semantic task state from whether a worker process is currently alive. An exited worker can therefore leave a durable row that is still resumable or attachable.
+
+| Display state | Meaning |
+| --- | --- |
+| **Queued** | A run has been scheduled but has not started processing. |
+| **Running** | The session is actively processing. |
+| **Needs answer** | The session is waiting for user input or an answer to a question. |
+| **Needs instructions** | The run ended without being marked complete and needs the next directive. |
+| **Done** | The user marked the inactive session complete; this is the default completion path. |
+| **Failed** | The worker or host ended with an error. |
+| **Stopped** | The user stopped the active work. |
+
+Rows are grouped by state. When a state contains sessions from multiple directories, rows are grouped by folder within that state. Pinned rows and folders come first, then creation order remains stable; activity does not reshuffle the list. New agent activity is marked unread with stronger row glyphs and header/footer counts. Replies sent while a session is busy enter a durable FIFO follow-up queue and are delivered when the session is ready; a `qN` badge shows queued follow-ups.
+
+Press `/` to enter filter mode. Filter tokens are case-insensitive and can be combined with free-text terms:
+
+```text
+s:running
+review:ready
+diag:stalled
+evidence:error
+queued:true
+steer:awaiting-approval
 ```
 
-Run all checks with:
+- `s:<state>` matches a state prefix, including display-label aliases such as `needs-answer`.
+- `review:ready` finds sessions with review-ready evidence.
+- `evidence:error` finds sessions whose evidence contains errors.
+- `queued:true` (also `yes` or `1`) finds sessions with queued follow-ups.
+- `steer:<state>` filters by a persisted steering state.
+- Bare words match name, summary, and working directory; multiple words use AND matching.
+
+`diag:stalled` can consume persisted stalled diagnostics, but the current runner does not provide a general provider-stall detector. It should not be read as a complete automatic stall-detection feature.
+
+## Evidence and Code References
+
+Evidence is collected locally from session events. Agent Board can extract issue and pull-request references from that evidence and show badges such as `#40` or `▸#45` on rows; Peek includes the provider, confidence, source, and URL when available. Built-in GitHub/GitLab-style providers are available, and an optional per-store `providers.json` can extend the provider rules. The `AGENT_BOARD_CODE_REFS=off` setting disables extraction.
+
+## Attach and Fallback Behavior
+
+When PTY support is healthy, Agent Board uses an interactive PTY host for attach and start-and-attach. If PTY support is unavailable, eligible managed sessions can still run in the background through the JSON runner; start-and-attach falls back to background launch with a warning. Adopted external foreground sessions require PTY to continue safely. Press `!` in the dashboard for diagnosis and repair hints.
+
+On Windows, PTY host control uses a named pipe and spawned child console windows are hidden. Terminal behavior can still vary between terminal emulators.
+
+## Entry Points
+
+| Entry point | What it does |
+| --- | --- |
+| `/agent-board` | Opens the dashboard from an interactive Pi session. Use this command path to attach to managed sessions. |
+| `pi /agent-board` | Starts Pi by invoking the dashboard command. Quitting the standalone dashboard shuts down Pi instead of dropping into a normal chat session. |
+| `pi --agent-board` | Opens the dashboard through the extension startup flag. This startup path cannot attach to a managed session; use `/agent-board` from a normal Pi session for attach. |
+| `/bg [prompt]` | Adopts the current interactive Pi session into Agent Board. An optional prompt is added to its follow-up queue before the dashboard opens. |
+
+The board is global across projects by default. Rows are stored under `~/.pi/agent/agent-board/`; archiving a row removes it from the board but preserves the underlying Pi session file.
+
+## Persistence, Safety, and Limitations
+
+Agent Board stores its durable roster and per-session artifacts under `~/.pi/agent/agent-board/` by default. Set `AGENT_BOARD_ROOT` to use another location. The store includes the roster, launch preferences, per-session metadata and state, Pi session JSONL, run status/events, evidence, diagnostics, and (for PTY hosts) a replayable screen log.
+
+Rows and session history survive Pi reloads, Pi restarts, and worker exits. When the dashboard opens, it reconciles stale runner or host records and keeps resumable sessions visible. Archiving a row removes it from the board but does not delete its underlying Pi session file.
+
+> **Worktree isolation is currently disabled.** Agent Board does not automatically create or manage Git worktrees. Multiple sessions in the same repository may run concurrently, so avoid overlapping writes or provide your own isolation before starting parallel coding tasks.
+
+Other current limitations:
+
+- Agent Board runs locally; it does not provide cloud execution, multi-user coordination, or shared dashboards.
+- Real model output still depends on Pi provider authentication and network access.
+- The `--agent-board` startup path opens the dashboard but cannot attach to a managed session; use `/agent-board` from a normal Pi session for attach.
+- Pending Pi question or questionnaire tools must be answered in the attached interactive session; inline reply is rejected while one is pending.
+- PTY-dependent features require a working `node-pty` installation. Background work can use the JSON-runner fallback when PTY is unavailable, but start & attach then becomes background-only.
+
+## Configuration
+
+Set these variables before starting Pi. Model-backed features fall back gracefully where noted, so disabling them does not prevent the core dashboard from working.
+
+| Variable | Default / values | Purpose |
+| --- | --- | --- |
+| `AGENT_BOARD_ROOT` | `~/.pi/agent/agent-board/` | Override the durable store location. |
+| `AGENT_BOARD_AUTO_STATE` | enabled; `off` disables | Enable automatic terminal-state refinement after a turn. |
+| `AGENT_BOARD_AUTO_STATE_MODEL` | `gpt-4o`; `off` uses heuristics | Model for classifying the terminal state of a finished turn. |
+| `AGENT_BOARD_AUTO_STATE_NO_DONE` | unset = manual Done; `0`, `false`, `off`, or `no` restores auto-Done | Keep completion manual by default, or restore automatic `Done` classification. |
+| `AGENT_BOARD_SUMMARY_MODEL` | `gpt-4o`; `off` disables | Generate short row summaries. Heuristic summaries remain available as a fallback. |
+| `AGENT_BOARD_TITLE_MODEL` | `openai-codex/gpt-5.5`; `off` disables | Generate a short session title after dispatch. The initial slug remains if generation fails. |
+| `AGENT_BOARD_TITLE_THINKING_LEVEL` | `low`; `off` omits the option | Thinking level used by title generation. |
+| `AGENT_BOARD_CODE_REFS` | enabled; `off` disables | Extract issue/PR badges from session evidence. |
+| `AGENT_BOARD_DISABLE_PTY` | unset; `1` disables | Disable PTY host and attach mode. |
+| `AGENT_BOARD_FORCE_PTY` | unset; `1` forces the PTY path | Force the PTY availability path when diagnosing or controlling fallback behavior. |
+| `AGENT_BOARD_ATTACH_MOUSE` | enabled; `0`, `off`, or `false` disables | Disable attach-view mouse handling and use terminal-native selection instead. |
+| `AGENT_BOARD_ENABLE_MOUSE_SCROLL` | enabled; `0` disables | Compatibility switch to disable attach-view mouse scrolling. |
+| `AGENT_BOARD_WHEEL_LINES` | `1`, clamped to `1..50` | Lines scrolled per mouse-wheel event in attach view. |
+| `AGENT_BOARD_MAX_WARM_HOSTS` | `4`, clamped to `0..50` | Maximum number of idle PTY hosts retained for faster attach. |
+| `AGENT_BOARD_WARM_HOST_TTL_MS` | `600000` (10 minutes); `0` disables TTL eviction | How long an idle warm host may remain before it is evicted. |
+| `AGENT_BOARD_ATTACH_NATIVE_PASTE` | enabled; `0` disables | Disable X11 PRIMARY selection copy and middle-click paste integration. |
+| `AGENT_BOARD_FORWARD_OSC52` | enabled; `0` disables | Disable OSC 52 clipboard sequence forwarding from an attached session. |
+| `AGENT_BOARD_FORWARD_IMAGES` | enabled; `0` disables | Disable terminal image/file passthrough forwarding from an attached session. |
+| `AGENT_BOARD_IME_FIX` | enabled; `0` disables | Disable the attach-view IME cursor coalescer if your terminal has compatibility problems. |
+
+Older `AGENT_VIEW_*` names are still read in selected compatibility paths. Prefer `AGENT_BOARD_*` for new setups. Internal child markers are managed by Agent Board and are not user settings.
+
+The `providers.json` file under the configured store root can extend the built-in issue/PR reference providers; see the [Evidence and Code References](#evidence-and-code-references) section for the feature overview.
+
+## Troubleshooting
+
+### Rows stay in `Running`
+
+First verify that Pi itself can complete a one-shot model call:
 
 ```bash
-npm run verify
+pi --mode json -p --no-session "Reply with exactly: DONE"
 ```
 
-`npm run verify` runs typecheck, tests, coverage, and a dry npm pack.
+The command should emit an assistant reply, then an `agent_end` event, and exit. If it hangs before the assistant reply, fix Pi provider authentication or network access first. Agent Board cannot produce live model results until Pi works independently.
+
+### `node-pty unavailable`
+
+Press `!` in the dashboard to open the diagnostic panel and follow its repair hints. Common causes include a missing native `node-pty` binary, a Node/architecture mismatch, a missing or non-executable macOS `spawn-helper`, or macOS quarantine. You can temporarily set `AGENT_BOARD_DISABLE_PTY=1` to use background JSON-runner behavior where supported.
+
+### Attach is slow or keeps reconnecting
+
+A cold PTY host may briefly show a loading or reconnecting surface while it starts. Check the PTY status in the dashboard with `!`; stale hosts are diagnosed separately from active task workers. If the host never becomes healthy, repair `node-pty` or use background mode for eligible managed sessions.
+
+### Start & attach falls back to background
+
+Start & attach requires PTY support. When PTY is unavailable, the task is still dispatched in the background and the dashboard displays a warning. Repair PTY and retry attach from the normal `/agent-board` command path.
+
+### Inline reply is rejected
 
-### QA baseline
+A pending Pi question or questionnaire requires the real interactive session. Attach to the row and answer it there; ordinary replies can be sent from Peek and are queued while a session is busy.
 
-Every push and PR runs the same checks in CI (`.github/workflows/ci.yml`, Node 22 + 24),
-and `main` branch protection requires both CI checks to pass before merging.
+### Sessions in the same repository conflict
 
-Coverage is enforced by `c8` with thresholds configured in `.c8rc.json`
-(lines ≥ 85%, functions ≥ 80%, branches ≥ 70%). The TS UI layer
-(`src/ui/*.ts`, `src/commands/*.ts`) is covered by a smoke test
-(`test/ui-smoke.test.mjs`) that constructs and renders the real entrypoints;
-it is excluded from the coverage thresholds by design.
+Worktree isolation is not enabled. Stop overlapping writers, separate their working directories, or create and manage Git worktrees yourself before running concurrent coding tasks.
 
-Current baseline: 300+ tests, ~92% line coverage on the core modules.
+See [VERIFY.md](VERIFY.md) for no-auth checks, extension loading checks, provider checks, persistence checks, and the manual dashboard flow.
 
-## Publish
+## Development
 
-Before publishing a new release, bump the package version, run verification, then publish:
+For local development:
+
+```bash
+npm install
+npm run verify
+```
+
+`npm run verify` runs typecheck, tests, coverage, and a package dry-run. The same checks run in CI on Node 22 and Node 24. See [VERIFY.md](VERIFY.md) for the full verification checklist and known environment-dependent limitations.
+
+## Publishing
+
+Before publishing a release, verify the package, bump the version, and publish it:
 
 ```bash
 npm run verify
@@ -137,12 +354,17 @@ npm version patch
 npm publish
 ```
 
-If the version is already bumped, skip `npm version patch`.
-
-Use `npm version minor` or `npm version major` instead when the release warrants it. After publish, users install with:
+Use `npm version minor` or `npm version major` when appropriate. If the version is already bumped, skip `npm version patch`. After publishing, users install the scoped package with:
 
 ```bash
 pi install npm:@zhuxixi/pi-agent-board
 ```
 
 The Pi package gallery uses the `pi.video` and `pi.image` URLs from `package.json`.
+
+## Further Reading
+
+- [Manual verification](VERIFY.md) — static checks, Pi loading, provider authentication, persistence, and dashboard flows.
+- [Product requirements](PRD.md) — original product scope and design context.
+- [Progress log](PROGRESS.md) — implementation checkpoints and known environment notes.
+- [Exploration notes](docs/EXPLORATION.md) — Pi API and integration research.

package/VERIFY.md

@@ -59,7 +59,7 @@ ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board
 ```
 After publish, install with:
 ```bash
-pi install npm:pi-agent-board
+pi install npm:@zhuxixi/pi-agent-board
 ```
 Then start pi normally:
 ```bash
@@ -72,10 +72,10 @@ 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. Type a task in the bottom input (e.g. `list the files in this repo and summarize the README`), then press **Enter**.
+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.
-   - A row appears and moves `Queued → Running → Done` (needs step 2 healthy).
+   - 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).

package/docs/PTY_ATTACH_IMPLEMENTATION_PLAN.md

@@ -280,9 +280,9 @@ Runner → client:
 {"type":"error","message":"..."}
 ```
 
-For attach, the parent sends raw input bytes through `input`. The only intercepted key should be the detach chord.
+For attach, the parent sends raw input bytes through `input`. The attach surface intercepts only `←` when the child input line appears empty; all other keys, including Pi's native `ctrl+]` editor shortcut, pass through to the child.
 
-Recommended detach chord for spike: `ctrl+]`, because it is already an editor jump key but less commonly needed than arrows/escape/enter. Make it configurable later.
+The detach chord is `←` because it is already the board navigation key and preserves Pi editor keybindings.
 
 ## 6. Attach UI design
 
@@ -560,7 +560,7 @@ MVP live attach is accepted when:
 | child Pi extension recursion | medium | `AGENT_BOARD_CHILD=1`; skip dashboard auto-open/footer in child |
 | host liveness conflated with agent activity | high | add `host.json`; separate `hostAlive` from `row.alive` |
 | worktree safety too conservative with idle hosts | low/medium | conservative MVP, later refine with activity state |
-| detach chord conflicts with Pi keybindings | low | configurable later; start with `ctrl+]` |
+| `←` is also a child-editor cursor key | low | detach only when the child input line appears empty; keep all other editor shortcuts, including `ctrl+]`, pass-through |
 | terminal images/OSC links not perfect in virtual renderer | medium | document limitation; raw takeover/core API if needed |
 
 ## 13. Confidence