@gavin-hu/my-pi-agent 0.18.0 → 0.19.0

package/docs/extensions/team.md

@@ -0,0 +1,226 @@
+# team — the lead's round over the board
+
+`board` owns the cards. `team` owns the lead's three actions: `assign` hands a card to a
+session that is **already running**, `offer` hands one to whoever is free, and `reclaim`
+takes one back when its owner has gone quiet. The first two are a write on the board and a
+message on the session bus; `reclaim` writes the card alone, so it needs no bus at all. The
+report says what the peer will actually do with it.
+
+Nothing starts a process. A message lands in the peer's inbox and is reported at its next
+turn, so `assign` and `offer` are messages, not launches.
+
+<img src="../../assets/screens/team.png" alt="The Team tab as a dashboard: on the left, a Needs a decision queue of rows with a coloured kind edge, the reason on its own line, and a Reclaim or Claim action on the row edge, or no action on a card that waits; on the right, a Teammates list with a state dot, label, you chip, mail badge, a not listening chip on a peer whose watch is off, and a line of what each holds; and one muted Done line under both" width="100%">
+
+*The Team tab: the cards that need the lead, then who is on the team — including an
+owner whose label nothing answers to, and a teammate that is not listening.*
+
+## Capabilities
+
+| Capability | How | What you get |
+|---|---|---|
+| Join the team | `/board` as the lead, `/team join <label>` as a teammate, or any card you work | The session is on the team under a label peers address, listening, and `/team` and the Team tab list it |
+| Hand a feature to a running session | `team` action `assign` | The card is `doing`, owned by that session, and a handoff is in its inbox |
+| Tell the peer what to do first | `team` action `assign` with `note` | The handoff carries the card, its paths, its plan, and that line |
+| Hand a feature to whoever is free | `team` action `offer` | Every other live session gets an event naming the card; the card stays unowned until one claims it |
+| Know whether a message will be woken for | an `assign` or `offer` result, `/team`, and the Team tab | All three name the peers whose record says their next turn is when it lands: the result as `Not listening: <labels>`, `/team` as a lowercase `not listening:` inside its presence line, the Team tab as a chip |
+| Take a card back | `team` action `reclaim` | The owner clears, the card returns to To do, and its notes stay |
+| Keep the round to the team | `team` | Only `assign`, `offer`, and `reclaim`: no card is created, moved, planned, or finished here — that is `board`'s surface |
+| See the round without a browser | `/team` | `buildRound`'s summary — the one the page's Team tab is served — laid out as text by `formatRound`: what needs a decision, who holds what, then one presence line for who is live, who is not listening, and who has gone quiet. Ten lines at most, then `… N more`; an empty board is one line |
+
+## Quickstart
+
+```
+lead: /board                                            → on the team as team-lead, listening
+peer: /team join billing-core                           → on the team as billing-core, listening
+lead: team({action:"assign", card:"4", to:"billing-core", note:"start with the webhook"})
+      → #4 handed off to billing-core.
+peer: board({action:"plan", card:"4", path:"…"})        → the card records its plan
+peer: board({action:"note", card:"4", text:"…"})        → a phase, as it happens
+later: team({action:"reclaim", card:"4"})               → #4 reclaimed from billing-core
+```
+
+Work nobody has taken instead of work you are routing:
+
+```
+lead: team({action:"offer", card:"5", note:"whoever is free"})
+      → #5 offered to billing-core, billing-web.
+peer: board({action:"claim", card:"5"})                 → the offer becomes work
+```
+
+## Joining the team
+
+You do not configure a team; there are no members to add. The team is the session bus,
+the local coordination channel between Pi sessions on this repository, and staying off
+its surface is the point: `board` and `team` join this session for you.
+
+| You are | Action | What happens |
+|---|---|---|
+| The lead | `/board` | The session joins as `team-lead` — the page's own seat name — and listens, so a handoff or an offer is reported at its next turn |
+| A teammate | `/team join billing-core` | The session joins as `billing-core`, and Pi's footer and `/resume` show that name |
+| Either | any `board` action that writes | The first one joins the session under the name it already has, and listens |
+| A viewer | `/board` on a session that is not serving | The page is somebody else's to serve, so this session joins under its own label instead of the seat |
+
+Joining is listening: mail is reported at that session's next turn, and **no turn is
+raised** for it, so being on the team never spends a turn. `/team` says who is live and
+who is live but not listening. `/board status` repeats only what the last `/board` in this
+session did about the team — a join made by `/team join` or by a card write is not on that
+line, and a page that is not running prints no team clause at all.
+
+**The seat is not a session.** The page writes as `team-lead` with an id of its own, so a
+card it claimed comes back with `reclaim` rather than a `release` from the terminal. The
+label is shared with the session that serves the page; the ids are not.
+
+## Tool
+
+`team` is one action-shaped tool. `readOnlyHint: false`, `destructiveHint: true`,
+`openWorldHint: false`, `executionMode: "sequential"`.
+
+| Action | Parameters | Behaviour |
+|---|---|---|
+| `assign` | `card`, `to`, `note?` | Checks the card's preconditions, sends the handoff as a `handoff` message, then records the owner |
+| `offer` | `card`, `note?` | Checks the preconditions a claim would meet, broadcasts the card as an `event` to every other live session, and writes nothing |
+| `reclaim` | `card` | Clears the owner and returns the card to To do, keeping its notes and plan |
+
+`card` takes `4` or `#4`. `to` is a teammate's label or id, as `/team` lists them — a
+label nobody answers to cannot be handed a card, and the result says so.
+
+### The order is the point
+
+`assign` sends **before** it assigns, and each failure leaves a state the report names:
+
+| What failed | What the card is | What the lead reads |
+|---|---|---|
+| the card is missing, `done`, held by a third session, or waiting on unfinished work | untouched | the refusal, with no message sent at all |
+| the send | untouched — `todo`, no owner | `#4 was not handed off to billing-core: …`, plus `The card is unchanged.` |
+| the assignment, after a successful send | whatever the other writer left | `#4 was handed off to billing-core, but the card changed before it could be assigned: …`, and the peer is told to `board claim` it |
+
+`offer` has no order to get wrong, because it writes nothing: a refused broadcast leaves
+the card exactly as the rules just read it, and the first `board claim` is what turns an
+offer into work. Two peers claiming at once are settled by the store's compare-and-set —
+one claim wins, and the other is refused with the owner named.
+
+`delivered` in the details means a message file was written for that label — not that the
+peer read it. `notListening` names the peers it reached whose record says they are not
+listening, so the message waits for their next turn.
+
+The owner `assign` records is the **session**, not just its name: before writing the card
+it reads the team list and keeps the id of the session behind that label. Ownership is
+compared by id first (`lib/board/rules.ts`), so a peer that renames itself still holds its
+card; a card assigned by label alone — an older one, or one whose session the bus could
+not name — goes back to `reclaim` if its holder renames.
+
+### What the peer does on waking
+
+A handoff is an instruction, not a notification: the peer's notice is headlined
+`1 handoff`, carries enough of the body to be actionable, and says the work is theirs —
+read it with `session inbox`, record the plan, and start. The card is already theirs
+(`assign` wrote the owner), so there is no claim step; the peer plans, works, notes, and
+moves it to `done` or `blocked`.
+
+An offer is advice: nothing is theirs until they claim it, and a card nobody claims stays
+`todo`, so it keeps showing up as unassigned in the round.
+
+## Security
+
+- The tool writes the board store and calls one other extension's tool (`session`); it
+  starts no process, opens no socket, and reads no credential.
+- A handoff or an offer is a message to other local sessions, so it carries nothing the
+  board would not show: the card's title, paths, plan, and the lead's note. An offer names
+  every session on the repository as a recipient, so it says nothing it would not say to
+  each of them.
+
+## Limitations
+
+- **Nothing here can start a peer's turn.** A message is reported at the recipient's next
+  turn; a session that is not listening at all reads it only when it reads its inbox.
+- **`to` must be on the team.** A session that never opened the board, joined, or worked a
+  card cannot be handed a card, and an offer to nobody says so.
+- **`team-lead` is a label, not a person.** The seat is not a session, so its actor id
+  `board:team-lead` answers no message; the label is the one the session serving the page
+  joins under, so a handoff to `team-lead` reaches whoever is serving the page just now —
+  and is refused, like any other label, when nobody is. The seat's cards come back with
+  `reclaim`.
+- **A label-only owner is fragile.** If the bus could not name the session behind `to`,
+  the card records the label, and a rename would need a `reclaim` and a fresh handoff.
+- **An offer is advice.** A card can sit offered indefinitely; the round keeps counting it
+  as unassigned, which is the honest signal that nobody took it.
+- **An offer arrives as an `event`.** A burst that mixes one with ordinary messages is
+  headlined as new messages rather than named as an offer.
+- **Liveness is a heartbeat; listening is a field.** A running session rewrites its record
+  every ten seconds and the record is believed for ten minutes, so `quiet:` means the
+  record went stale rather than that the peer died, while `not listening` is the separate
+  `watching` field, written when the session joins or arms and disarms its watch.
+- **Plan mode makes this unavailable.** `session` is a mutating tool, so while plan mode is
+  active the bus call is refused. Assign after the plan is approved.
+- **Ownership is advisory.** `assign` does not create a path claim; the peer still claims
+  the paths it edits through `session`.
+
+## Pi integration
+
+- **`board`**: the same store, the same cards, the same rules — `team` calls `lib/board/`
+  directly, so a card it hands over is one `board` can see. Either extension works without
+  the other: without `team` the page still reclaims, and without `board` there is nothing
+  to assign.
+- **`session-bus`**: the transport, and the one extension `team` talks to — through
+  `lib/session-tool.ts`, whose `join` is an in-process request (a command context cannot
+  call a tool) and whose `peers` and `send` are nested tool calls. The bus's actions and
+  labels never appear on this extension's user surface — `team` and `board` are the
+  surface — but its name does, in the sentence an unloaded bus produces: `team: not on the
+  team — the session bus is not loaded`. Every call returns that sentence instead of
+  throwing, which is the "card untouched" row above.
+- **`plan`**: the handoff names the plan file when one is recorded, so the peer knows
+  whether it is executing a plan or writing one.
+- **`subagent`**: a child process is a different Pi session; hand a card to a peer
+  session, not to a child you started for one question.
+
+## Design notes
+
+- **Two extensions, not one tool with a flag.** `board` is the work list any session uses
+  and must work with the bus disabled; `team` is the lead's round and is the only thing
+  that needs the bus. If the round ever stops needing it, `team` folds back in.
+- **Joining is the bus's, wearing `board`'s clothes.** A lead should not have to learn a
+  second tool to be on a team, so `/board` joins, a card write joins, and `/team join` is
+  the one naming action. `wake` stays a bus-level choice and is never armed on a user's
+  behalf, because it spends turns.
+- **Push and pull are two verbs.** `assign` writes the owner and sends one message;
+  `offer` broadcasts and writes nothing. One verb with an optional `to` would have two
+  outcomes and one details shape, and a reader could not tell which happened.
+- **The offer's preconditions are a dry-run claim.** `applyOp` judges what a peer is about
+  to do, so a card nobody may claim is refused before anything is sent, and the refusal is
+  the rules' own sentence rather than a second copy.
+- **Listening is a record field.** The bus writes it when a session joins or stops
+  listening, so the report, `/team`, and the Team tab read one fact from disk instead of
+  guessing from the send.
+- **Send first.** A card assigned without a message is a card nobody knows about, while a
+  message for a card that then changed is one the peer can still claim.
+- **`reclaim` is here, and in `board`.** It is the compensation for a dispatch that did not
+  land, so it belongs in the lead's context — and it is the same operation `board` and its
+  page offer, because a card whose owner went away must not need a second extension to come
+  back.
+- **Rejected: `reclaim` messaging the previous owner.** A compensation path must not depend
+  on a second delivery — the reclaim is what you do when the owner is gone, so its message
+  would fail exactly when it is needed. The card is the record.
+- **Rejected: a fifth message kind for an offer.** An offer is something that happened on
+  the board, which is what `event` already means; a new kind would change the protocol, the
+  notice, and every reader for one verb.
+
+## Files
+
+| File | Responsibility |
+|---|---|
+| `index.ts` | The factory: gate on `PI_DISABLED_EXTENSIONS`, build the session, register the tool and the command |
+| `schema.ts` | The tool's three actions and their parameters |
+| `tools.ts` | The dispatch order, the refusals, and the report |
+| `dispatch.ts` | The handoff and offer text, the bus behind a seam, and who is not listening |
+| `commands.ts` | `/team` — the round, and `/team join [<label>]` |
+| `format.ts` | The model-facing text for a handoff, an offer, a failure, a race, and a reclaim |
+| `types.ts` | The tool's name, actions, and details |
+
+The store, the rules, and the session identity are `lib/board/`; the join, the peer list,
+and the message send are `lib/session-tool.ts` — see [`lib/README.md`](../../lib/README.md).
+
+## Testing
+
+`test/suite-manifest.ts` declares `team/{commands,dispatch,tools,extension}`: the handoff
+and offer text, the bus's answers behind the seam, the assign/offer/reclaim ordering
+against a recording dispatch, `/team` and `/team join`, and the factory.

package/{extensions/todo/README.md → docs/extensions/todo.md}

@@ -1,92 +1,63 @@
 # todo — a TodoWrite-style task list for Pi
 
-A whole-list task tracker for Pi, modelled on Claude Code's `TodoWrite`. The
-model sends the complete list on every call; the previous list is discarded, so
-there are no ids to juggle and no add/toggle bookkeeping. The list follows the
-active session branch and is restored on `/resume` and `/tree`. When a run is
-about to end after mutating work without a todo update, the extension injects
-one short reminder and forces a continuation, so the list does not silently
-drift behind the work.
-
-<img src="../../assets/todo.png" alt="The /todos screen: a Todos title rule, a 3/7 completed summary, and the list with check, spinner, and circle glyphs" width="100%">
-
-```
+A whole-list task tracker for Pi, modelled on Claude Code's `TodoWrite`: the
+model sends the complete list on every call, so there are no ids to juggle and
+no add/toggle bookkeeping. The list follows the active session branch and is
+rebuilt on `/resume` and `/tree`, and the extension keeps it honest by asking for
+one update when work lands without one.
+
+<img src="../../assets/screens/todo.png" alt="The /todos screen: a Todos title rule, a 3/7 completed summary, and the list with check, spinner, and circle glyphs" width="100%">
+
+## 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 |
+|---|---|---|---|
+| Whole-list tracking | `todo` | One call replaces the list; an empty list clears it. | Shipped |
+| Live progress rail | the `todo` widget | Progress and the active item, one line above the editor. | Shipped |
+| Atomic validation | `todo` validation | At most one `in_progress`, at most 50 items, unique non-empty content, and a known status; a violation returns an error with the unchanged list. | Shipped |
+| Terminal-safe normalization | sanitized `content` and `activeForm` | Control characters, newlines, tabs, and repeated spaces collapse to one terminal-safe line before the list is stored. | Shipped |
+| Compact model result | the `todo` result | The model gets progress and the active item, not an echo of the whole list, so every update does not repeat the table. | Shipped |
+| Transcript rendering | the `todo` transcript block | The call line carries progress; the collapsed rows lead with active work, the expanded rows keep submission order, and a cap ends with `… N more`. | Shipped |
+| Full list on demand | `/todos` | A scrollable screen in the order the model submitted. | Shipped |
+| Headless listing | `/todos` outside `tui` | RPC, print, and JSON modes get the same list as a notification, with no terminal screen. | Shipped |
+| Branch-following state | tool-result `details` | The list survives `/resume` and `/tree`, and abandoned branches never leak in. | Shipped |
+| Lag reminder | the `agent_before_settle` nudge | One hidden reminder and one forced continuation when mutating work lands without a todo update. | Shipped |
+| Structured result | `structuredContent` | Codemode scripts read the list as data. | Shipped |
+
+## Quickstart
+
+```bash
 pi --extension ./extensions/todo    # load just this extension
 pi -e .                             # load the whole @gavin-hu/my-pi-agent package
-pi install ./                       # install the package
+pi install ./                       # install the package for a user
 ```
 
-## Tool rendering
-
-How the `todo` call and its result look in the transcript — the call line as a headline and the body indented under it:
-
-<img src="../../assets/tools/todo.png" alt="The todo tool's result: the call line and an indented body with the progress line and the task rows below it, each led by a check, spinner, or circle glyph" width="100%">
-
-## What it does
-
-- Registers one model-callable tool, `todo`, that **replaces** the task list.
-  An empty list clears it. The tool result is a compact summary — progress plus
-  the current item — not an echo of the list the model just sent.
-- Each item has `content`, a `status` (`pending` | `in_progress` |
-  `completed`), and an optional `activeForm` ("Running tests") shown while the
-  item is in progress.
-- Shows a persistent widget above the editor while the list has unfinished
-  work (hidden when empty or fully completed), and a scrollable `/todos`
-  screen on demand. It is the bottom rail, below the [`goal`](../goal/) widget
-  (`Goal / Todos`).
-- Stores the list in tool-result `details`, so it follows the active session
-  branch and survives `/resume` and `/tree` — abandoned branches never leak
-  into the current list, and stored lists are re-sanitized on replay.
-- Keeps the list honest: when a run is about to settle after a successful
-  mutating tool call (`write`/`edit`/`bash`/`powershell`, or a tool declaring
-  `readOnlyHint: false`) without a todo update, it injects one hidden reminder
-  and forces a single continuation. A failed or blocked call changed nothing, so
-  it never triggers one. It fires while the list has unfinished items, and —
-  when no list exists at all — only after three such calls in one turn, at least
-  one of them a file write (`write`/`edit`, or a tool declaring
-  `readOnlyHint: false`), so repeated `bash` inspection is not mistaken for
-  unplanned work. A list the model wrote or cleared during the turn is left
-  alone. At most one reminder per user turn, and it is dropped on the next user
-  turn, so a reader can never trigger it.
-- Declares an `outputSchema` and returns matching `structuredContent`
-  (`{ todos, action, error? }`), so codemode/scripts can read the list as data.
-
-The widget is a one-line summary — progress plus the current item — so the
-active task is always visible without expanding the list:
-
-```
-Todos · 1/3 · Writing the tests
+```text
+/todos                              # show the list, and its progress
 ```
 
-`/todos` is the expanded view and keeps the model's list order (use it to see
-the plan as written).
+The model calls `todo` with the complete list; the widget appears above the
+editor while anything is unfinished.
 
-In the transcript, the call line carries progress only (`todo → 1/4`); the
-result keeps the `✓` / `◒` / `◌` rows, directly under the call line. The item
-text lives on the rows, so the call line never repeats it. Collapsed, it leads
-with active work; expanded, it keeps the submitted order:
+## Tool
 
-```
-todo → 1/4
-  ◒ Writing tests
-  ◌ Ship it
-  ◌ Write docs
-  ✓ Write schema
-```
+<img src="../../assets/tools/todo.png" alt="The todo tool's result: the call line and an indented body with the progress line and the task rows below it, each led by a check, spinner, or circle glyph" width="100%">
 
-Progress lives on the call line, so the rows have no footer; the persistent
-widget and `/todos` still show the count. A capped collapsed rail ends with
-`… N more` and the `app.tools.expand` hint.
+`todo` — `exposure: "direct"` (the default), `executionMode: "sequential"`,
+read-write, closed-world, idempotent. It replaces the list; an empty list clears
+it. The result is a compact summary — progress plus the current item — not an
+echo of the list the model just sent.
 
-## Tool
+| Parameter | Type | Meaning |
+|---|---|---|
+| `todos` | array, required | The complete list. Pass `[]` to clear. |
+| `todos[].content` | string | Imperative description, e.g. `"Write the parser tests"`. |
+| `todos[].status` | `pending` \| `in_progress` \| `completed` | Where the item stands. |
+| `todos[].activeForm` | string | Present-continuous label, required when the item is `in_progress` ("Running tests"). |
 
-| Field | Value |
-|---|---|
-| `name` | `todo` |
-| `todos` | The complete list. Pass `[]` to clear. |
-| `todos[].content` | Imperative description, e.g. `"Write the parser tests"`. |
-| `todos[].status` | `pending`, `in_progress`, or `completed`. |
-| `todos[].activeForm` | Present-continuous label, required when the item is `in_progress`. |
+Result (`details` / `structuredContent`): `{ todos, action, error? }`.
 
 Validation rules (a violation leaves the list unchanged):
 
@@ -108,20 +79,45 @@ unknown `status` or a wrong argument type is rejected by Pi before `execute`
 runs, so the host's validation message is returned instead; the list is still
 unchanged.
 
-```
+```text
 todo({ todos: [{ content: "Write the parser tests", status: "in_progress", activeForm: "Writing the parser tests" }] })
 todo({ todos: [] })   // clear
 ```
 
-### `/todos` command
+The widget is a one-line summary — progress plus the current item — so the
+active task is always visible without expanding the list:
+
+```text
+Todos · 1/3 · Writing the tests
+```
+
+In the transcript, the call line carries progress only (`todo → 1/4`); the
+result keeps the `✓` / `◒` / `◌` rows, directly under the call line. The item
+text lives on the rows, so the call line never repeats it. Collapsed, it leads
+with active work; expanded, it keeps the submitted order:
+
+```text
+todo → 1/4
+  ◒ Writing tests
+  ◌ Ship it
+  ◌ Write docs
+  ✓ Write schema
+```
+
+Progress lives on the call line, so the rows have no footer; the persistent
+widget and `/todos` still show the count. A capped collapsed rail ends with
+`… N more` and the `app.tools.expand` hint.
+
+## Commands
 
 | Command | What it does |
 |---|---|
 | `/todos` | Show the current list. An interactive, scrollable screen in `tui` mode; a notification elsewhere. |
 
-On the `/todos` screen: `↑`/`↓` or `j`/`k` scroll one row, `PgUp`/`PgDn` page,
-`g`/`G` or `Home`/`End` jump to the ends, and `Esc` (or `Ctrl-C`) closes. The
-window grows and shrinks with the terminal height, so the footer hint stays
+`/todos` is the expanded view and keeps the model's list order, so it shows the
+plan as written. On the screen: `↑`/`↓` or `j`/`k` scroll one row, `PgUp`/`PgDn`
+page, `g`/`G` or `Home`/`End` jump to the ends, and `Esc` (or `Ctrl-C`) closes.
+The window grows and shrinks with the terminal height, so the footer hint stays
 visible.
 
 The TUI label is status-dependent: an `in_progress` row shows its `activeForm`
@@ -135,13 +131,14 @@ The tool works in every mode. The persistent widget and the `/todos` screen
 require interactive (`tui`) mode; RPC and non-interactive runs simply get the
 tool result. The lag reminder is mode-independent, because it rides the agent
 boundary and not the terminal UI. While any dock screen is open (`/todos`,
-`/jobs`, `/rewind`, or the `question` questionnaire), the above-editor
-rails are hidden and return on close.
+`/jobs`, `/rewind`, or the `question` questionnaire), the above-editor rails are
+hidden and return on close.
 
 ## Configuration
 
-The widget presentation is configurable from the `todo` section of the shared
-`bytefly.json` (global document, then project document, project wins):
+One key, in the `todo` section of the shared `bytefly.json` (global document,
+then project document, project wins; resolution rules in
+[`../configuration.md`](../configuration.md#todo--the-todo-widget)):
 
 | Key | Default | Meaning |
 |---|---|---|
@@ -201,7 +198,7 @@ depends on config.
   a goal update would sink the list; the list subscribes on `pi.events` and
   re-runs `setWidget` whenever a rail above it changes, keeping the stack
   `Goal / Todos`. It never announces, so the chain cannot ping-pong. See
-  [`lib/rails.ts`](../../lib/rails.ts) and [`goal`](../goal/).
+  [`lib/rails.ts`](../../lib/rails.ts) and [`goal`](./goal.md).
 - **The reminder is a bounded nudge, not a nag.** A prompt guideline cannot
   guarantee a timely update, so the extension backs it with one forced
   continuation. `tool_execution_end` counts a successful call by an explicit
@@ -237,8 +234,7 @@ depends on config.
 | File | Responsibility |
 |---|---|
 | `index.ts` | Factory: wire the runtime, tool, command, reminder events, and session events. |
-| `types.ts` | `Todo`, `TodoStatus`, `TodoDetails`. |
-| `types.ts` | `Todo` and `TodoDetails`; re-exports `TodoStatus` / `TODO_STATUSES` from `lib/todo-state.ts`. |
+| `types.ts` | `Todo`, `TodoDetails`; re-exports `TodoStatus` / `TODO_STATUSES` from `lib/todo-state.ts`. |
 | `schema.ts` | TypeBox parameters; the parser and limits live in `lib/todo-state.ts`. |
 | `state.ts` | Status queries over the replayed list (pure). |
 | `nudge.ts` | Lag detection: mutating and file-write classification, due check, reminder text (pure). |
@@ -248,3 +244,4 @@ depends on config.
 | `runtime.ts` | Session-scoped state, lag tracking, and widget synchronization. |
 | `tools.ts` | `todo` tool registration and rendering. |
 | `commands.ts` | `/todos`. |
+| `tools.test.ts`, `runtime.test.ts`, `ui.test.ts` | The capability suites, declared in `test/suite-manifest.ts`. |

package/{extensions/watch/README.md → docs/extensions/watch.md}

@@ -6,41 +6,56 @@ the TUI, reported to the model at the next turn, or — when a watcher opts into
 `wake` — raise one triggered turn as soon as the agent is idle, including right
 after a running turn settles.
 
-```
+## 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.
+
+### Watching
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Tail a source | `watch add` | A file is followed from its current end unless `fromStart` is set, and a shrinking file is re-read from the start; a command's merged stdout/stderr is streamed. | Shipped |
+| Line matching | `watch add` | An include pattern with an optional exclude list, case-insensitive unless `caseSensitive` is set. | Shipped |
+| Match delivery | `watch add`, `watch matches` | Pending matches are reported to the model at the start of the next turn. | Shipped |
+| Wake turn | `watch add`, the `wakeOnMatch` key | One triggered turn as soon as the agent is idle, including right after a running turn settles. | Shipped |
+| Desktop alert | `my-pi-agent/watch-match`, `notify.enabled`, `notify.matchFound` | A wake match leaves the terminal as an OS notification. | Shipped |
+| Live status | `watch add`, the `showStatus` key | A `⊚ N` running chip and a `! N` unreported-match chip, plus one alert per unreported burst. | Shipped |
+| Command outcome | `watch status`, `watch list` | A command watcher reports its exit code or error, including the captured signal, instead of only "stopped". | Shipped |
+| Liveness detail | `watch list`, `watch status` | A running watcher names its pid and elapsed time; list rows sort running watchers first, newest next. | Shipped |
+| Transcript rendering | the `watch` transcript block | The outcome line, at most eight rows, and a `(ctrl+o to expand)` hint keep the transcript compact. | Shipped |
+| Sanitized output | `watch matches`, `/watch matches` | Model- and remote-authored output is stripped of control characters before it reaches a terminal or a notification. | Shipped |
+
+### Reading and managing
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Watcher inventory | `watch list`, `watch status`, `/watch list` | Each watcher's source, state, and line and match counts, singly or as a table. | Shipped |
+| Matched lines | `watch matches`, `/watch matches` | The matching lines, sanitized and read from a bounded history. | Shipped |
+| Raw output | `watch logs`, `/watch logs` | The merged output tail, for checking a pattern that matches nothing. | Shipped |
+| Watcher screen | `/watch` | A dock screen with the watcher list, the focused watcher's detail, and its matches pane. | Shipped |
+| Stopping and cleanup | `watch stop`, `watch clear`, `/watch stop`, `/watch clear` | A running watcher stops, stopped ones are removed, and `all` takes the running ones too. | Shipped |
+
+## Quickstart
+
+```bash
 pi --extension ./extensions/watch    # load just this extension
 pi -e .                              # load the whole @gavin-hu/my-pi-agent package
 pi install ./                        # install the package
 ```
 
-## Tool rendering
+```text
+watch add { "path": "server.log", "pattern": "ERROR|FATAL", "label": "server" }
+/watch
+```
 
-How the `watch` call and its result look in the transcript — the call line as a headline and the body indented under it:
+## Tool
 
 <img src="../../assets/tools/watch.png" alt="The watch tool's result: the call line and an indented body with a running file watcher and an exited command watcher" width="100%">
 
-## What it does
-
-- Registers one model-callable tool, `watch`, with actions `add`, `list`,
-  `status`, `matches`, `logs`, `stop`, and `clear`.
-- Tails a text file by polling it, or a shell command by streaming its merged
-  stdout/stderr. A file is followed from its current end unless `fromStart` is
-  set; a shrinking file (rotation/truncation) is re-read from the start.
-- Matches with a regular expression and an optional exclude list,
-  case-insensitive by default and case-sensitive with `caseSensitive: true`.
-- Shows a `⊚ N` running-watcher chip and a `! N` unreported-match chip, raises a
-  `ctx.ui.notify` alert once per unreported burst, and offers a `/watch` screen.
-- Reports pending matches to the model at the start of the next turn, or wakes a
-  turn for a watcher added with `wake: true` as soon as the agent is idle. A wake
-  that arrives mid-turn is raised once that run settles. A wake also leaves the
-  terminal: the
-  match is announced on `my-pi-agent/watch-match`, which bytefly's
-  [notify](../bytefly/README.md#notifications) capability turns into a desktop
-  notification when `notify.enabled` and `notify.matchFound` are on.
-- Watchers are session-only: `shutdown` flushes a partial line, sends SIGTERM to
-  every command's process tree (escalating to SIGKILL after a short grace), and
-  clears the chips.
-
-## Tool
+`watch` — `exposure: "direct"` (the default), `executionMode: "sequential"`,
+read-write, destructive, open-world, not idempotent. One tool with seven
+actions; a watcher outlives the call, so `add` returns an id immediately and the
+rest read it back.
 
 | Field | Value |
 |---|---|
@@ -104,15 +119,10 @@ capped at eight rows, minus the selection-marker column (`listRow`'s
 render the tail of the sanitized lines, with the hidden count noted above and
 `(ctrl+o to expand)`.
 
-### Command: /watch
-
-<img src="../../assets/watch.png" alt="The /watch screen: a Watch title rule, a `2 watchers · 1 running · 3 matches` summary, a selected file watcher and a finished command watcher, the focused watcher's path and pattern with its line and match counts, and the key hints" width="100%">
+## Commands
 
-A bare `/watch` opens a dock screen listing watchers. `j`/`k` (and the wheel)
-move, `Enter`/`l` opens a watcher's matches, `x`/`K` stops a running watcher
-behind a `y/N` confirm, `d` clears stopped ones behind a `y/N` confirm, `Esc`
-closes, and `g`/`G` and PgUp/PgDn scroll the matches pane. Subcommands work in
-every mode:
+`/watch` manages watchers in every mode; a bare `/watch` opens the screen in the
+TUI and prints the list everywhere else.
 
 | Command | Effect |
 |---|---|
@@ -123,6 +133,13 @@ every mode:
 | `/watch stop <id>` | Stop a watcher. |
 | `/watch clear [all]` | Remove stopped watchers, or every watcher with `all`. |
 
+<img src="../../assets/screens/watch.png" alt="The /watch screen: a Watch title rule, a `2 watchers · 1 running · 3 matches` summary, a selected file watcher and a finished command watcher, the focused watcher's path and pattern with its line and match counts, and the key hints" width="100%">
+
+A bare `/watch` opens a dock screen listing watchers. `j`/`k` (and the wheel)
+move, `Enter`/`l` opens a watcher's matches, `x`/`K` stops a running watcher
+behind a `y/N` confirm, `d` clears stopped ones behind a `y/N` confirm, `Esc`
+closes, and `g`/`G` and PgUp/PgDn scroll the matches pane.
+
 ## Behaviour by mode
 
 - **tui** — the status chips, the match alert, and the `/watch` dock screen.
@@ -132,8 +149,9 @@ every mode:
 
 ## Configuration
 
-The `watch` section of the shared `bytefly.json` (global then project). Every
-value is clamped; a missing or malformed document is ignored.
+The `watch` section of the shared `bytefly.json`; resolution rules in
+[`../configuration.md`](../configuration.md#watch--file-and-command-watchers).
+Every value is clamped; a missing or malformed document is ignored.
 
 | Key | Default | Meaning |
 |---|---|---|