@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/docs/extensions/question.md

@@ -8,22 +8,20 @@ Modelled on Claude Code's `AskUserQuestion`.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Mid-turn asking | `ask_user_question` | The model asks 1–4 questions and the turn waits until you answer or cancel. | Shipped |
-| Labelled options | `questions[].options` | Each question offers up to four choices, each with an optional second line describing it. | Shipped |
-| Free-form answers | the automatic `Other (type something)` row, `questions[].options` omitted | You can type an answer the options do not cover, and a question with no options asks for plain text. | Shipped |
-| Multiple selections | `questions[].multiSelect` | `Space` toggles options and `Enter` confirms the set. | Shipped |
-| Batched questions | `questions[]` | Up to four questions ride in one call and are answered in one pass. | Shipped |
-| Submit gating | the `Submit` tab | Submit refuses until every question is answered and names the missing ones; a single question submits on `Enter` without a Submit tab. | Shipped |
-| Tab headers | `questions[].header` | Each question gets a short tab label, defaulted to `Q{n}` and clipped to 12 columns. | Shipped |
-| Language-aware batch | `dialogUI.language` | A remote turn in Chinese gets the batch prompt, retry text, and format line in Chinese. | Shipped |
-| Dialog fallback | `select`, `input`, `editor` | RPC and remote turns answer the same questions without the TUI screen. | Shipped |
-| No-UI degradation | `print`, `json` | The tool returns `unavailable` with an error instead of hanging when no dialog channel exists. | Shipped |
-| Cancelling | `Esc` | The model is told you cancelled and can continue or ask in prose. | Shipped |
-| Branch-scoped answers | tool-result `details` | The answers stay with the transcript, so `/resume` and `/tree` show the same history. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Mid-turn asking | `ask_user_question` | The model asks 1–4 questions and the turn waits until you answer or cancel. |
+| Labelled options | `questions[].options` | Each question offers up to four choices, each with an optional second line describing it. |
+| Free-form answers | the automatic `Other (type something)` row, `questions[].options` omitted | You can type an answer the options do not cover, and a question with no options asks for plain text. |
+| Multiple selections | `questions[].multiSelect` | `Space` toggles options and `Enter` confirms the set. |
+| Batched questions | `questions[]` | Up to four questions ride in one call and are answered in one pass. |
+| Submit gating | the `Submit` tab | Submit refuses until every question is answered and names the missing ones; a single question submits on `Enter` without a Submit tab. |
+| Tab headers | `questions[].header` | Each question gets a short tab label, defaulted to `Q{n}` and clipped to 12 columns. |
+| Language-aware batch | `dialogUI.language` | A remote turn in Chinese gets the batch prompt, retry text, and format line in Chinese. |
+| Dialog fallback | `select`, `input`, `editor` | RPC and remote turns answer the same questions without the TUI screen. |
+| No-UI degradation | `print`, `json` | The tool returns `unavailable` with an error instead of hanging when no dialog channel exists. |
+| Cancelling | `Esc` | The model is told you cancelled and can continue or ask in prose. |
+| Branch-scoped answers | tool-result `details` | The answers stay with the transcript, so `/resume` and `/tree` show the same history. |
 
 ## Quickstart
 
@@ -183,7 +181,7 @@ UI.
   for free.
 - **A pure state machine behind the TUI.** `tui-state.ts` holds a reducer
   (`reduce(state, action) → { state, effect }`) so navigation, toggling, tab
-  movement, and submit gating are tested without a terminal; `tui.ts` only maps
+  movement, and submit gating are tested without a terminal; `view/question-screen.ts` only maps
   state to lines and forwards input. Render output is cached and cleared from
   `invalidate()`, and themed strings are never stored across renders.
 - **Claude-Code-compatible parameter shape.** `{ label, description? }` options
@@ -212,7 +210,7 @@ UI.
 | [`types.ts`](../../extensions/question/types.ts) | Shared raw/normalized types |
 | [`answers.ts`](../../extensions/question/answers.ts) | Answer normalization and model-facing formatting (pure) |
 | [`tui-state.ts`](../../extensions/question/tui-state.ts) | Pure keyboard/navigation state machine |
-| [`tui.ts`](../../extensions/question/tui.ts) | Custom terminal component (render + input), drawn from the `lib/tui/` kit (`titleRule`/`plainRule`, `checkbox`, `flowCells`, `screenHint`, `editorTheme`). |
+| [`view/question-screen.ts`](../../extensions/question/view/question-screen.ts) | Custom terminal component (render + input), loaded on first use, drawn from the `lib/tui/` kit (`titleRule`/`plainRule`, `checkbox`, `flowCells`, `screenHint`, `editorTheme`). |
 | [`dialogs.ts`](../../extensions/question/dialogs.ts) | `select`/`input`/`editor` fallback driver |
 | [`tools.ts`](../../extensions/question/tools.ts) | Tool registration and transcript renderers |
 

package/docs/extensions/rewind.md

@@ -12,24 +12,22 @@ file, a selection, or the whole turn.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Automatic snapshots | the `autoSnapshots` key | One snapshot per prompt, taken before its first mutating call, so every task has a restore point. | Shipped |
-| Durable snapshots | `refNamespace` | Snapshots survive the session and are listed from git rather than from session state. | Shipped |
-| Prompt timeline | `/rewind` | Every user prompt on the active branch, newest first, marked `⬥` where a code snapshot was captured. | Shipped |
-| Scoped restore | `/rewind` | Code, conversation, or both, from the prompt you pick. | Shipped |
-| Undoable restore | the `safetySnapshot` key | A code restore snapshots the state it replaces first, so it can itself be undone. | Shipped |
-| Partial restore | `/rewind` | The changed paths grouped by directory, chosen with a checklist, and previewed as the subset you selected. | Shipped |
-| Latest-turn review | `/review` | The changed files of the latest prompt, with `M`/`A`/`D`/`R` marks and line counts. | Shipped |
-| File, batch, and hunk revert | `/review` | Revert one file, a selection, the whole turn, or chosen hunks, each with its own safety snapshot. | Shipped |
-| Busy-git refusal | `/rewind`, `/review` | A merge, rebase, cherry-pick, revert, or bisect in progress refuses the restore instead of fighting it. | Shipped |
-| Root-scoped snapshots | `refs/pi/rewind` | Worktrees share the ref store, while another root's snapshot is filtered out and refused. | Shipped |
-| Untracked capture | `autoSnapshots` | Non-ignored untracked files are captured, and a restore removes the ones that appeared after the snapshot. | Shipped |
-| Ref cap and auto-prune | `max`, `autoPrune` | The snapshot store is bounded and pruned instead of growing without limit. | Shipped |
-| Review plan guard | `/review` in plan mode | Review refuses while plan mode is on, matching the read-only planning rule. | Shipped |
-| Prompt-count chip | `↺ N`, the `showStatus` key | The status bar counts the prompts on the active branch, whether or not each has a snapshot. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Automatic snapshots | the `autoSnapshots` key | One snapshot per prompt, taken before its first mutating call, so every task has a restore point. |
+| Durable snapshots | `refNamespace` | Snapshots survive the session and are listed from git rather than from session state. |
+| Prompt timeline | `/rewind` | Every user prompt on the active branch, newest first, marked `⬥` where a code snapshot was captured. |
+| Scoped restore | `/rewind` | Code, conversation, or both, from the prompt you pick. |
+| Undoable restore | the `safetySnapshot` key | A code restore snapshots the state it replaces first, so it can itself be undone. |
+| Partial restore | `/rewind` | The changed paths grouped by directory, chosen with a checklist, and previewed as the subset you selected. |
+| Latest-turn review | `/review` | The changed files of the latest prompt, with `M`/`A`/`D`/`R` marks and line counts. |
+| File, batch, and hunk revert | `/review` | Revert one file, a selection, the whole turn, or chosen hunks, each with its own safety snapshot. |
+| Busy-git refusal | `/rewind`, `/review` | A merge, rebase, cherry-pick, revert, or bisect in progress refuses the restore instead of fighting it. |
+| Root-scoped snapshots | `refs/pi/rewind` | Worktrees share the ref store, while another root's snapshot is filtered out and refused. |
+| Untracked capture | `autoSnapshots` | Non-ignored untracked files are captured, and a restore removes the ones that appeared after the snapshot. |
+| Ref cap and auto-prune | `max`, `autoPrune` | The snapshot store is bounded and pruned instead of growing without limit. |
+| Review plan guard | `/review` in plan mode | Review refuses while plan mode is on, matching the read-only planning rule. |
+| Prompt-count chip | `↺ N`, the `showStatus` key | The status bar counts the prompts on the active branch, whether or not each has a snapshot. |
 
 ## Quickstart
 
@@ -278,7 +276,7 @@ commit. These refs are not branches and are not touched by `git push --all`.
 | `transport/store.ts` | Versioned metadata encoding and ref-backed listing/pruning. |
 | `state/policy.ts` | Which tool calls are worth a snapshot. |
 | `transport/temp-index.ts` | Per-process `GIT_INDEX_FILE` paths: create, release, and sweep stale files. |
-| `view/status.ts` | The `↺ N` status chip. |
+| `status.ts` | The `↺ N` status chip. |
 | `transport/queue.ts` | The serialized git operation queue for staging calls (`GIT_INDEX_FILE`). |
 | `state/runtime.ts` | Root/config caches and the snapshot/list/plan/patch/numstat/restore/hunk-revert operations. |
 | `state/timeline.ts` | Pure: prompts on the branch, paired with their snapshots. |

package/docs/extensions/serve.md

@@ -0,0 +1,145 @@
+# serve — the session's one loopback server
+
+## Capabilities
+
+| Capability | How | What you get |
+|---|---|---|
+| One port for every page of a session | automatic: the first page that opens binds it | the file browser at `/files/`, the board at `/board/`, and a review at `/plan/<id>/` answer on one origin, so a bookmark, a firewall rule, and a port to remember are one thing |
+| One chip for that port | `◉ <port>` in the status bar | the session's port while anything is served on it, and nothing when no page is open |
+| A port that survives a restart | automatic: the project's own port | a session that starts again lands where a bookmark already points, so a saved URL still opens the page it names; `serve.port` overrides it |
+| Two projects on one machine | automatic: the port is the repository's, hashed into the band | neither needs a setting to avoid the other, and a worktree of one repository keeps the number the main checkout uses |
+| A second session on its own port | automatic: servers are keyed by Pi session | a WeChat peer conversation never answers on this session's port |
+| One page reachable on the LAN, on request | the asking page calls `mount.share()` | a teammate's link names exactly one address, and only that page answers there |
+
+## Quickstart
+
+There is nothing to run: `serve` is infrastructure, and the pages that use it are
+`/board`, `/browse`, and `/plan review`.
+
+```bash
+/board          # http://127.0.0.1:<port>/board/?token=…
+/browse         # http://127.0.0.1:<port>/files/
+/plan review    # http://127.0.0.1:<port>/plan/3f9c21aa/?token=…
+```
+
+All three answer on that one port — the project's own, in `4780`–`5779` — and the
+footer shows `◉ <port>` while any of them is open, dropping the chip when the last
+one closes.
+
+## Routes
+
+The server holds prefixes, not pages. Each one is claimed by the extension that
+serves it, and a request reaches that extension with its prefix stripped:
+
+| Prefix | Served by | Note |
+|---|---|---|
+| `/files/` | `file-browse` | the file browser: its tree, its file pages, its own script, and the links it rewrites out of Markdown, all built from this prefix; `/files/browse/<path>` is one directory |
+| `/board/` | `board` | the read-only board page, with its token in the query |
+| `/plan/<id>/` | `plan` | one review; the id is the review's, so two reviews never share a namespace |
+
+Anything else is a `404` with a plain-text body, and a prefix named without its
+trailing slash (`/board`) is redirected to the slashed form, because a page's own
+links are relative to its directory. A prefix another page already holds is
+refused by name rather than served twice.
+
+## Behaviour by mode
+
+The server runs in every mode, but the chip needs a UI: RPC and JSON sessions serve
+their pages and skip it. Nothing here reads or writes the transcript.
+
+## Configuration
+
+The `serve` section of the shared `bytefly.json` (global, then project, project wins:
+
+| Key | Default | What it does |
+|---|---|---|
+| `port` | `0` | `0` takes the project's own port — its repository key hashed into `4780`–`5779` — and falls back to an OS-chosen one when that port is taken; a positive value pins the session's server so a bookmarked address survives a restart, and a taken pin is reported by name instead of moved |
+
+The default is the repository's, so two repositories take two numbers without a
+setting and a restart lands where the bookmark was. A second session of one
+repository — a WeChat peer, or another checkout — prefers the same number and takes
+an OS-chosen port when the first one holds it.
+
+The pin belongs to the first session in a process that binds: a second session takes
+an OS-chosen port instead of failing on a port the host already holds. A second
+*process* that finds the pinned port taken is told so rather than moved silently off
+the address a bookmark names.
+
+## Security
+
+The server binds `127.0.0.1`. The unit of exposure is the mount: a prefix answers
+only what its page routes, and each page keeps its own `Host` allowlist, its own
+token, and its own method list in `lib/http`.
+
+A shared review is the one exception, and it is the reviewing page's own: it asks
+for a listener on a single LAN address, and that listener carries only the prefixes
+that asked for it. `file-browse` and `board` are never reachable that way, and a page
+that stops sharing leaves the listener at once — the socket closes with the last page
+that was still sharing it.
+
+## Limitations
+
+- A page needs `serve` loaded. Without it every page refuses with a sentence naming
+  the extension, instead of binding a rival socket.
+- Two projects can hash into the same port, and the second start takes an OS-chosen one
+  instead: its bookmark moves until that project sets `serve.port`.
+- Two checkouts of one repository at once prefer one number, so the second takes an
+  OS-chosen port each session and only the first keeps the address a bookmark names.
+- The default is a guess: a port another process holds moves the session to an
+  OS-chosen one without a word — the chip shows the number — while a pinned port that is
+  taken is refused by name.
+
+## Non-goals
+
+- It serves no page of its own, and registers no tool and no command.
+- It is not a general web server: loopback, a page's own routes, one optional LAN
+  address per shared page, and nothing else.
+- It does not proxy or rewrite; a page's paths are its own, under its prefix.
+
+## Pi integration
+
+- Registers `pi.events.on(HTTP_MOUNT_CHANNEL, …)` in the factory — registration only.
+  Binding happens on the first mount, never at load and never on `session_start`.
+- `session_start` records the session's working directory and its context, so the
+  pin is read from that session's config and the chip is drawn in its UI.
+- `session_shutdown` closes the session's socket, its LAN listener, and its chip.
+  It is idempotent.
+
+## Design notes
+
+A session has one port, so the socket cannot belong to a page. The page asks for a
+prefix over `pi.events` — the mechanism the repository already uses for a
+cross-extension request that must be answered — and `lib/http` owns the socket, the
+dispatch, the body cap per mount, and the idle grace per mount.
+
+The handshake is *claimed*, not awaited: `server.listen` cannot answer synchronously,
+so the owner responds with the pending bind and only a request nobody claimed is
+refused. Without that distinction a bind that is still starting looks exactly like a
+session with no server.
+
+The default is the repository key hashed into the band rather than a fresh draw. The
+key is the one identity this repository already has — `session-bus` files sessions by
+it, `plan` files plans by it — and every worktree of a repository resolves the same
+one, so a bookmark saved in the main checkout opens the worktree's page. A draw was
+the reason a bookmark only worked until the next start.
+
+## Files
+
+| Path | Responsibility |
+|---|---|
+| [`../../extensions/serve/index.ts`](../../extensions/serve/index.ts) | The Pi wiring: the bus listener, the per-session directory and context, the port chip, and the shutdown |
+| [`../../extensions/serve/registry.ts`](../../extensions/serve/registry.ts) | The session's servers: binding on first mount, the pin's owner, the remembered port, prefix refusals, the LAN listener a shared page borrows, and closing with the last mount |
+| [`../../extensions/serve/config.ts`](../../extensions/serve/config.ts) | The `serve` section: `port`, its clamp, and the two documents it resolves over |
+
+## Testing
+
+`config.test.ts`, `registry.test.ts`, and `extension.test.ts`, declared under
+`serve` in `test/suite-manifest.ts`.
+
+The registry cases bind real sockets on `127.0.0.1`: one port for two pages of a
+session, a second session on its own port, a refused duplicate prefix, the socket
+closing with its last page and reopening where it was, the project's port taken by the
+first bind and the OS-chosen fallback when another listener holds it, the pin belonging
+to the first session that binds, and a LAN share reaching one page only. The extension
+cases drive the shipped bus path through `requestMount`, including the project's port
+surviving a restart, the chip, and the shutdown.

package/docs/extensions/session-bus.md

@@ -12,11 +12,9 @@ a running turn settles. There is no network service and no hidden context.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
 | Capability | How | What you get | Status |
 |---|---|---|---|
-| Membership | `session join [label]`, `/team join [<label>]`, `/board`, any `board` action that writes, the board's `w` | The join: this session is on the bus under a stable label peers address, and listens for mail unless told not to. A label given to `session join` or `/team join` is also Pi's session name, so the footer and `/resume` agree with the record; `/board` joins as the page's seat (`team-lead`) or, on a page it is only watching, under its own label; the first `board` action that writes joins under the name the session already has; `w` joins under the name the bus derives and writes nothing to Pi. | Shipped |
+| Membership | `session join [label]`, `/team join [<label>]`, `/board`, the first `board` claim, the board's `w` | The join: this session is on the bus under a stable label peers address, and listens for mail unless told not to. That label is what the footer draws; a label given to `session join` or `/team join` is also Pi's session name, so `/resume` agrees with the record; `/board` joins as the board's lead (`board.lead`, `lead` by default) or, on a page it is only watching, under its own preset teammate name (`tom`, `lily`, … — `team-agent-<id>` once every preset name is held); the first `board` claim joins under that same name, and renames nothing; `w` joins under the name the bus derives and writes nothing to Pi. | Shipped |
 | Peer discovery | `session status` | Every active session with its unread count and claims, plus this session's identity, in one read — and a session whose process is gone says so, its paths free from that read on. | Unreleased |
 | Live board | `/sessions` | Sessions, this session's unread mail, and every claim held on the repository, on one screen. | Shipped |
 | Board actions | `/sessions` (`w`, `x`) | Start or stop listening from the board, or release an own claim behind a confirmation, without leaving it. | Shipped |
@@ -56,11 +54,11 @@ collapsed line that expands to the board's rows.
 | Action | Inputs | Result |
 |---|---|---|
 | `status` | — | Active sessions with unread counts, their state, claims, and this session's identity. A session whose process is gone is listed as `gone` until its heartbeat ages out, and its claims are not listed at all. Prunes stale records. A read: it never adds this session to the bus. |
-| `send` | `to`, `text`, optional `kind`, optional `paths` | Writes one message per recipient. `to: "*"` is only valid with `kind: "event"`. |
+| `send` | `to`, `text`, optional `kind`, optional `paths` | Writes one message per recipient. `to: "*"` is only valid with `kind: "event"`. A session whose process is gone is not a recipient: naming it is refused, and a broadcast skips it. |
 | `inbox` | optional `limit` | Returns and deletes up to `limit` messages, oldest first (default 20, max 50). |
 | `claim` | `paths` | Claims repository-relative files or directory prefixes; returns conflicts with their owner. |
 | `release` | `paths` | Removes claims owned by this session; reports paths owned by someone else. |
-| `join` | optional `label`, `wake`, `listen` | Joins the bus, names this session on it and in Pi when a label is given — the same path and uniqueness rule as `/team join`, so the footer and `/resume` agree with the record peers address — and starts listening for mail. `wake: true` raises one turn per burst once the agent is idle; `wake: false` reports at the next turn; `listen: false` joins without listening. A label a live session holds is refused, naming the session that holds it — its id, since the label it holds is the one you asked for — and the refusal leaves both names and the watch alone. The result reports the label the bus settled on and whether mail will reach this session. |
+| `join` | optional `label`, `wake`, `listen` | Joins the bus, names this session on it and in Pi when a label is given — the same path and uniqueness rule as `/team join`, so `/resume` agrees with the record peers address — and starts listening for mail. The footer draws the label either way, so a plain join changes the name on the bar without renaming the session. `wake: true` raises one turn per burst once the agent is idle; `wake: false` reports at the next turn; `listen: false` joins without listening. A label a live session holds is refused, naming the session that holds it — its id, since the label it holds is the one you asked for — and the refusal leaves both names and the watch alone. The result reports the label the bus settled on and whether mail will reach this session. |
 
 A claim is all-or-nothing: if one path conflicts, nothing is claimed. A claim on
 a directory conflicts with claims below it and above it, so `src/api` and
@@ -68,7 +66,10 @@ a directory conflicts with claims below it and above it, so `src/api` and
 takeover; wait for the owner, ask it to release, or let the session expire.
 
 Paths resolve against the caller's working directory and are stored relative to
-its repository root; a path outside the repository is refused.
+its repository root; a path outside the repository is refused, and so is one that
+resolves to the repository itself — `path "." is the repository, not a path in
+it.` — because a claim on the root would own every file in it. Below the root,
+the same `.` claims the directory the session is in.
 
 `wake` is the mode, not an arm-time switch: `join({ wake: true })` raises a turn
 for a session that was reporting at the next turn, and `join({ wake: false })` —
@@ -91,9 +92,12 @@ Labels are how another session addresses you. Name one by the outcome it owns
 (`billing-core`, `integrator`, `verify-billing`), not by a layer or a role;
 duplicate labels get a short id suffix automatically.
 
-A label is also Pi's session name, so the footer's `[label]` and `/resume` agree
-with the bus. Because the bus derives a joining session's label from that name, a
-named session comes back under the same label after a resume.
+A label is what the footer's `[label]` draws: bytefly reads this session's own record
+and follows the `session-label` event, so the bar names the session the way a card, a
+handoff, and `/team` do. `/team join <label>` makes the label Pi's session name too, so
+`/resume` agrees with the bus; any other join leaves Pi's name alone and only the bar
+moves. Because the bus derives a joining session's label from that name, a named session
+comes back under the same label after a resume.
 
 The tool's `join` action is the same join from the model's side, so a `board` or a
 `team` call can put a session on the bus without the user naming it, and
@@ -181,6 +185,11 @@ listening watch is what raises the turn.
   both sides to keep replying; the answer is to stop listening on one of them.
 - **No broadcast history.** A broadcast reaches the sessions active at send time;
   a session that joins later does not receive it.
+- **Mail to a gone session is refused, not queued.** A record whose process has
+  exited is not a recipient: `send` naming it answers `no active session`, and a
+  broadcast skips it. Its inbox outlives a `/resume`, but a sender is never told a
+  message arrived at a process that has exited — the bus's rule for a claim, and
+  for `status`, is the same one.
 - **No forced claims.** There is no takeover while an owner can still answer: a
   claim is released by its owner, or by the next bus call once the owner's process
   is gone. A *hung* owner still blocks its paths until the session TTL expires,
@@ -203,9 +212,10 @@ listening watch is what raises the turn.
   pane's shutdown leaves the record and the claims to the newer one instead of
   releasing them. Listening is still per process, so the survivor's watch is the
   survivor's.
-- **A message file that does not parse is dropped.** The board's read never
-  consumes mail, but it does delete a file it cannot validate, so a truncated
-  message cannot linger on the bus.
+- **A message file that does not parse is skipped, and left to `inbox` and the TTL.** The
+  board's read never consumes mail, so it deletes nothing — not even a file it cannot
+  validate, which may be mail this build cannot read and the next one can. Consuming it
+  or the 24-hour expiry is what clears the file.
 - **No network.** It is not a distributed bus and does not synchronize machines.
 
 ## Pi integration
@@ -214,7 +224,7 @@ listening watch is what raises the turn.
 |---|---|
 | Tools | `session` — one action-shaped tool; `readOnlyHint: false`, `destructiveHint: true`, `openWorldHint: false`, `executionMode: "sequential"`. |
 | Commands | `/sessions` — the board in `tui`, the listing elsewhere; no arguments and no sub-commands. |
-| UI | `tui` mounts `SessionListComponent` through `withPolledScreen` (rails suppressed, a 1 s read-only poll of `snapshot()` + `peek()`); every other mode prints through `ctx.ui.notify`. No status chip, so listening never changes the footer. |
+| UI | `tui` mounts `SessionListComponent` through `withPolledScreen` (rails suppressed, a 1 s read-only poll of `snapshot()` + `peek()`); every other mode prints through `ctx.ui.notify`. No status chip: the watch state changes no footer segment, and the label is the bus's own `session-label` event rather than a chip. |
 | Events | `session_start` resolves the repository and arms the mail trigger, without joining; `session_tree` only repaints, since navigating the tree changes no pending record; `agent_start` marks the run busy; `before_agent_start` reports queued non-wake mail at the next turn; `agent_settled` retries a wake the run suppressed; `context` prunes stale notices; `session_shutdown` clears the heartbeat, the watch ticker, and the record. The seven hooks are `lib/report.ts`'s `registerPendingChannel`, not a local copy. |
 | State | Files under `<agent-dir>/session-bus/<repo-key>/`; nothing in the session branch. Listening is session-only. `/resume` re-registers the same session id. |
 | Lifecycle | The factory only registers. The runtime starts on `session_start`; heartbeat, watch ticker, and cleanup belong to it. Disabling `session-bus` through `PI_DISABLED_EXTENSIONS` registers nothing. |
@@ -233,7 +243,11 @@ listening watch is what raises the turn.
   started through a link named differently is named after the directory it is
   actually in. An absolute path argument that sits outside the repository is
   refused before it is re-keyed, and a relative one whose target leaves the
-  repository is refused by the re-keying itself.
+  repository is refused by the re-keying itself. A path whose target is the
+  repository root is refused there too, and by that one rule: the spelling check
+  hands the root on rather than pre-empting it, so the sentence a caller reads
+  says what happened (`is the repository, not a path in it`) instead of claiming
+  a path inside the repository is outside it.
 - **One file per item.** Sessions never append to a shared registry: each session
   writes its own record, each message is its own file, and a claim is a temp file
   hard-linked into place — an exclusive create no reader can see half-written.
@@ -252,6 +266,14 @@ listening watch is what raises the turn.
   with one `readdir` every 2 s, the same trade `watch` makes for a file tail, so
   it does not depend on a platform's event API or a filename in the event. Only
   a listening session polls.
+- **The poll reads the mail it has not announced, and its queue by what is on disk.** That one
+  read returns up to 50 messages from the front of the inbox whose ids the watch does not have,
+  plus the ids of everything still unread, so where a message's id sorts cannot hide it: a
+  backlog deeper than one page arrives a page at a time, and a peer whose clock lags writes an id
+  before every other and is announced just the same. The queue and the watch's memory are pruned
+  by what is still on disk rather than by a count of ids, so mail already queued keeps the place
+  it held and nothing is announced twice. `inbox` still consumes oldest first, and a limit never
+  starves.
 - **Read the board, prune on the next call.** The open board polls a read-only
   `snapshot()` and `peek()` that hide a session past the TTL, a claim held by one,
   and consume nothing. The physical prune, and the claim release that goes with
@@ -274,14 +296,14 @@ listening watch is what raises the turn.
 |---|---|
 | `index.ts` | Disable guard, registration, the pending-report channel, and the session hooks. |
 | `join-request.ts` | The `board`/`team` join request: one `bus.join` answer, and the label it settles becomes Pi's session name. |
-| `runtime.ts` | Lifecycle, repo key, joining, heartbeat, and the session's own reads and writes. |
+| `runtime.ts` | Lifecycle, repo key (`<agent-dir>/session-bus/<repo-key>/`), joining, heartbeat, and the session's own reads and writes. |
 | `mail-watch.ts` | The armed inbox watch: the poll, the not-yet-reported queue, and its state. |
 | `store.ts` | Atomic JSON files, inbox, peek, claims, pruning, and the one release loop. |
 | `protocol.ts` | Pure labels, targets, paths, validation, conflict rules. |
 | `overlap.ts` | The one "do these paths collide?" predicate: `claimsConflict`, which normalizes both spellings of a claim path first. |
 | `resolve.ts` | `resolveClaimPaths` and `claimPathMessage`: a claim path made repository-relative, posix, and canonical through its real target, or the refusal naming why. |
 | `types.ts` | The stored shapes — session record, message, claim — and the tool's `details`. |
-| `tui.ts` | The `/sessions` board, its scopes, and the pane over one row; the row grammar is in `rows.ts`. |
+| `view/session-list.ts` | The `/sessions` board, its scopes, and the pane over one row, loaded on first use; the row grammar is in `rows.ts`. |
 | `rows.ts` | The session/claim/message row builders and summaries shared by the board and the transcript. |
 | `result.ts` | The `session` tool's expanded result block and its collapsed line. |
 | `notice.ts` | The mail notice's model text and renderer details. |

package/docs/extensions/subagent.md

@@ -8,27 +8,25 @@ can also start in the background and be inspected, collected, or cancelled with
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Isolated context | `subagent` | Each task runs in its own process with its own transcript, and only its final reply returns to the caller. | Shipped |
-| Explicit tool allowlist | `--tools` for every child | An agent gets only its declared tools, not the parent's ambient extensions; `worker` cannot recurse into `subagent`. | Shipped |
-| Read-only delegation | `subagent` (`readOnly: true`) | Every spawned agent runs with a reader-only tool set, enforced at the process boundary. | Shipped |
-| Plan-mode guard | `subagent`, plan mode | Plan mode forces every call read-only and refuses `/agents` until the plan is approved. | Shipped |
-| Project-agent trust gate | `agentScope` with the trust gate | A `.pi/agents` file loads only when the project is trusted or confirmed, so a repository cannot inject a prompt by adding a file. | Shipped |
-| Three delegation modes | `subagent` (`agent` + `task`, `tasks[]`, `chain[]`) | One agent, an independent batch, or an ordered chain whose steps receive `{previous}`. | Shipped |
-| Parallel and chain bounds | `tasks[]`, `chain[]` | Parallel accepts up to 8 tasks with 4 running at once; a chain accepts up to 8 steps and stops at the first failure. | Shipped |
-| Per-step working directory | `cwd` | A single run, each parallel task, or each chain step can name its working directory; a relative path resolves against the active root. | Shipped |
-| Built-in agents | `subagent` (`agent`) | Recon, planning, review, implementation, research, testing, debugging, and docs work without writing an agent file. | Shipped |
-| External agents | `subagent` (`agentScope`) | Markdown agents from the user directory and the nearest `.pi/agents`, opt-in per scope and never replacing a built-in silently. | Shipped |
-| Background runs | `subagent` (`background: true`), `/agents` | A single run continues after the call returns and is inspected, collected, or cancelled from the board. | Shipped |
-| Background concurrency cap | `backgroundMax` | At most four background children run at once; finished runs release their slot. | Shipped |
-| Session-owned background run | `background: true` | `/tree` does not move the run and a restart cannot resume it; an unfinished start shows as `interrupted`. | Shipped |
-| Live progress | `subagent` | Tool calls and progress update in the transcript while the child runs, with a `↳ N` footer chip and a finish notice. | Shipped |
-| Bounded runs | `timeoutMs` | A child that hangs is killed at the deadline and reported as a failed run rather than rejecting the whole call. | Shipped |
-| Optional transcripts | `transcripts` | Per-run streams under `.pi/subagents/`, written by the parent and pruned by age and count. | Shipped |
-| Inherited model | `subagent` | Children use the dispatching session's model and thinking level unless an agent overrides them. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Isolated context | `subagent` | Each task runs in its own process with its own transcript, and only its final reply returns to the caller. |
+| Explicit tool allowlist | `--tools` for every child | An agent gets only its declared tools, not the parent's ambient extensions; `worker` cannot recurse into `subagent`. |
+| Read-only delegation | `subagent` (`readOnly: true`) | Every spawned agent runs with a reader-only tool set, enforced at the process boundary. |
+| Plan-mode guard | `subagent`, plan mode | Plan mode forces every call read-only and refuses `/agents` until the plan is approved. |
+| Project-agent trust gate | `agentScope` with the trust gate | A `.pi/agents` file loads only when the project is trusted or confirmed, so a repository cannot inject a prompt by adding a file. |
+| Three delegation modes | `subagent` (`agent` + `task`, `tasks[]`, `chain[]`) | One agent, an independent batch, or an ordered chain whose steps receive `{previous}`. |
+| Parallel and chain bounds | `tasks[]`, `chain[]` | Parallel accepts up to 8 tasks with 4 running at once; a chain accepts up to 8 steps and stops at the first failure. |
+| Per-step working directory | `cwd` | A single run, each parallel task, or each chain step can name its working directory; a relative path resolves against the active root. |
+| Built-in agents | `subagent` (`agent`) | Recon, planning, review, implementation, research, testing, debugging, and docs work without writing an agent file. |
+| External agents | `subagent` (`agentScope`) | Markdown agents from the user directory and the nearest `.pi/agents`, opt-in per scope and never replacing a built-in silently. |
+| Background runs | `subagent` (`background: true`), `/agents` | A single run continues after the call returns and is inspected, collected, or cancelled from the board. |
+| Background concurrency cap | `backgroundMax` | At most four background children run at once; finished runs release their slot. |
+| Session-owned background run | `background: true` | `/tree` does not move the run and a restart cannot resume it; an unfinished start shows as `interrupted`. |
+| Live progress | `subagent` | Tool calls and progress update in the transcript while the child runs, with a `↳ N` footer chip and a finish notice. |
+| Bounded runs | `timeoutMs` | A child that hangs is killed at the deadline and reported as a failed run rather than rejecting the whole call. |
+| Optional transcripts | `transcripts` | Per-run streams under `.pi/subagents/`, written by the parent and pruned by age and count. |
+| Inherited model | `subagent` | Children use the dispatching session's model and thinking level unless an agent overrides them. |
 
 ## Quickstart
 
@@ -229,7 +227,7 @@ picks up ambient extensions and `worker` cannot recurse into `subagent`.
 for another agent (typically `worker`) to execute, and it works headlessly. It
 returns the plan as text and writes nothing. For **interactive** planning where
 the user reviews and approves a saved plan, use the plan-mode extension instead
-(`enter_plan_mode` / `write_plan` / `exit_plan_mode`), which operates on the
+(`plan` actions `enter` / `write` / `exit`), which operates on the
 main session and persists to the agent directory. Plan mode keeps `subagent` available
 for exploration but forces it read-only, so delegated recon is safe mid-plan.
 
@@ -454,15 +452,15 @@ step's `Output`.
 |---|---|
 | `index.ts` | Registers the `subagent` tool and assembles the mode context. |
 | `orchestrate.ts` | The `single`/`parallel`/`chain` mode runners. |
-| `agents.ts` | Built-in agent definitions, external markdown discovery, and pool resolution. |
+| `agents.ts` | Built-in agent definitions, external markdown discovery (`<agent-dir>/agents`, and the nearest `<repo>/.pi/agents`), and pool resolution. |
 | `schema.ts` | TypeBox params, limits, and `resolveMode`. |
 | `invocation.ts` | `pi` subprocess invocation and argument construction. |
 | `stream.ts` | JSON-event parsing, guarded usage accounting, output helpers (pure). |
-| `transcripts.ts` | Per-run transcript buffer, run ids, the store directory, and pruning. |
+| `transcripts.ts` | Per-run transcript buffer, run ids, the store directory (`<agent-dir>/subagents/`), and pruning. |
 | `config.ts` | The `subagent` section of `bytefly.json`: deadline, transcripts, retention. |
 | `run.ts` | Runs one subagent process and captures its result (including the background abort-as-result path). |
 | `background.ts` | Background run entries, replay, capacity, cancel, collect, and shutdown. |
-| `background-tui.ts` | The `/agents` board: a `DockListScreen` with a live output pane and width-aware facts. |
+| `view/agents-board.ts` | The `/agents` board: a `DockListScreen` with a live output pane and width-aware facts, loaded on first use. |
 | `commands.ts` | The `/agents` command. |
 | `ui.ts` | The running-count footer chip and finish notices. |
 | `accounting.ts` | The `subagent-finished` event payload built from a result (pure). |