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

package/docs/extensions/team.md

@@ -1,6 +1,6 @@
 # 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
+`board` owns the cards. `team` owns the lead's four 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 is gone or has gone quiet. `assign` writes the card and puts
 a handoff on the session bus, `offer` writes only the moment it was made — never an owner,
@@ -11,32 +11,44 @@ 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 the owner as a chip on the row's right; 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%">
+Both halves are **opt-in**, because the board is a workflow a session either runs or does
+not. A lead names both — `PI_ENABLED_EXTENSIONS=board,team` — and a worker session that
+only works cards names neither. They stay independent at runtime: naming one never loads
+the other, and `team` is refused by `PI_DISABLED_EXTENSIONS` like every extension.
+
+Naming `team` alone is legal and stays so — the factory needs no board to register — but
+it is the crippled case: every card it moves is one no `board` tool can read. `doctor`
+reports the board row as opt-in and names the switch that adds it, which is the one place
+a reader who took that shortcut is told.
+
+<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 the owner as a chip on the row's right; on the right, a Teammates list of one-line rows, each a state dot, a label, a you chip, a mail badge, a not listening chip on a peer whose watch is off, and what that teammate holds at the row's right; 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.*
+owner whose label nothing answers to, and a teammate that is not listening. A row is one
+line; the owners a bus has no record of collapse to one row*
 
 ## 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 |
+| Join the team | `/board` as the lead, `/team join <label>` as a teammate, or the first card you claim | The session is on the team under a name peers address, listening, and `/team` and the Team tab list it |
+| Hand a feature to a running session | `team` action `assign` | The card is `plan`, 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, and it records when the offer was made, so a lead can tell an offer nobody took from a card nobody has looked at |
 | 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 line naming the cards a dead owner left behind, and one presence line for who is live, who is not listening, who has gone quiet, and who is gone. The rollup itself is capped at ten lines, then `… N more`, and the gone and presence lines follow the cap rather than counting against it — the cap is a notify's limit, not a screen's. An empty board is one line |
+| Take a card back | `team` action `reclaim` | The owner clears, the card returns to Backlog, and its notes stay |
+| Keep the round to the team | `team` | Only `assign`, `offer`, `reclaim`, and `claim`: no card is created, contracted, approved, or finished here — that is `board`'s surface, which is where a claimed card is planned and moved |
+| 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 line naming the cards a dead owner left behind, and one presence line for who is live, who is not listening, who has gone quiet, and who is gone. The owners the bus has no record of and that hold nothing are one line, `18 owners with no record · 76 done`, in the Team tab's own words — the fold is the same rule and the same sentence on both surfaces, and it keeps a long history from spending the round's cap. The rollup itself is capped at ten lines, then `… N more`, and the gone and presence lines follow the cap rather than counting against it — the cap is a notify's limit, not a screen's. An empty board is one line |
 
 ## Quickstart
 
 ```
-lead: /board                                            → on the team as team-lead, listening
+lead: /board                                            → on the team as 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:"contract", card:"4", path:"…", goal:"…", acceptance:"…", scopeOut:"…"})
+      → the card records its plan and its contract
 peer: board({action:"note", card:"4", text:"…"})        → a phase, as it happens
 later: team({action:"reclaim", card:"4"})               → #4 reclaimed from billing-core
 ```
@@ -49,6 +61,13 @@ lead: team({action:"offer", card:"5", note:"whoever is free"})
 peer: board({action:"claim", card:"5"})                 → the offer becomes work
 ```
 
+Nobody free, so the lead takes it:
+
+```
+lead: team({action:"claim", card:"5"})                  → #5 is yours, in plan.
+      → design it in plan mode, `plan` action `write`, then `board` action `contract`
+```
+
 ## Joining the team
 
 You do not configure a team; there are no members to add. The team is the session bus,
@@ -57,20 +76,22 @@ 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 |
+| The lead | `/board` | The session joins as the board's lead (`board.lead`, `lead` by default) — the name the page serves as — and listens, so a handoff or an offer is reported at its next turn |
+| A teammate | the first card it claims | The session joins under the name it already holds, or a preset teammate name (`tom`, `lily`, `ben`) when it has none, and listens; Pi's footer keeps the name it already had |
+| A teammate who wants a name | `/team join billing-core` | The session joins as `billing-core`, and Pi's footer and `/resume` show that name — the one join that renames |
+| 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 name 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 is a view: it has one name, `team-lead`, and an id
-of its own derived from it, and it writes nothing, so it holds no card for a lead to take
-back. Its cards come from the session that serves it, whose label is the same and whose id
+raised** for it, so being on the team never spends a turn. `/team join` with no name draws
+one when Pi has no name for the session — `lily` rather than the repository's basename — and
+renames nothing; a session Pi already names keeps that name. `/team` says who is live and
+who is live but not listening. `/board status` reports the team this session is on — which
+label, and whether mail reaches it — whichever door put it there, and prints no team clause
+only when this session never joined at all.
+
+**The seat is not a session.** The page is a view: it has one name — the board's lead — and
+an id of its own, `board:<lead>`, and it writes nothing, so it holds no card for a lead to
+take back. Its cards come from the session that serves it, whose label is the same and whose id
 is not: a card that session claimed is the session's, and `release` returns it.
 
 ## Tool
@@ -80,9 +101,10 @@ is not: a card that session claimed is the session's, and `release` returns it.
 
 | Action | Parameters | Behaviour |
 |---|---|---|
-| `assign` | `card`, `to`, `note?` | Checks the card's preconditions, sends the handoff as a `handoff` message, then records the owner |
+| `assign` | `card`, `to`, `note?` | Checks the card's preconditions, sends the handoff as a `handoff` message, then records the owner. `to` that names this session is refused — a card you will take yourself is `claim` |
 | `offer` | `card`, `note?` | Checks the preconditions a claim would meet, broadcasts the card as an `event` to every other live session, then records the offer on the card — the moment, and nothing else: status and owner are untouched |
-| `reclaim` | `card` | Clears the owner and returns the card to To do, keeping its notes and plan |
+| `reclaim` | `card` | Clears the owner and returns the card to Backlog, keeping its notes, contract, and plan |
+| `claim` | `card` | Takes a pool card for this session: it enters `plan`, owned by the round's session, and the claim asks to join the team once — the same operation and the same join `board`'s claim makes. A card somebody holds, one that waits on unfinished work, and a full `plan` lane are refused with the board's own sentence |
 
 `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.
@@ -108,7 +130,7 @@ the sentence, and a test holds every published parameter to an action that acts
 | 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 send | untouched — `backlog`, 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` broadcasts **before** it records, for the same reason: an offer nobody received
@@ -136,15 +158,18 @@ not name — goes back to `reclaim` if its holder renames.
 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`.
+(`assign` wrote the owner), so there is no claim step; the peer writes the contract, works,
+notes, and moves it on — into `execute` once the lead has approved the contract, and to
+`done` once the lead has spot-checked it.
 
 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 — with its age, which is the one
+`backlog`, so it keeps showing up as unassigned in the round — with its age, which is the one
 thing an event cannot carry. `board` prints it as `offered 1m ago, and nobody took it`, the
 card face says `offered 1m ago · nobody took it`, and the Team tab's queue says
 `offered 1m ago — nobody took it` in place of "nobody holds it". A lead reading that has a
-decision the plain unassigned row never offered: re-offer, `assign` it, or take it.
+decision the plain unassigned row never offered: re-offer, `assign` it, or take it with
+`claim`, which is yours then — the card sits in `plan` waiting on you, and its contract,
+moves, and finish are `board`'s in this same session.
 
 ## Security
 
@@ -159,15 +184,21 @@ decision the plain unassigned row never offered: re-offer, `assign` it, or take
 
 - **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
+- **`to` must be on the team.** A session that never opened the board, joined, or claimed 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 —
+- **A held card is not assignable.** `assign` moves a pool card; one somebody already holds
+  is refused, because a handoff cannot take work away from its owner — `reclaim` it, then
+  assign.
+- **The lead's name is a label, not a person.** The seat is not a session, so its actor id
+  `board:<lead>` answers no message; the label is the one the session serving the page joins
+  under, so a handoff to it 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.
+- **A preset name is drawn, not chosen.** An unnamed session that joins draws one of the
+  preset teammate names and Pi's footer keeps whatever it had; type `/team join <label>` to
+  pick the name and make it Pi's.
 - **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
@@ -179,7 +210,7 @@ decision the plain unassigned row never offered: re-offer, `assign` it, or take
 - **Plan mode makes this unavailable.** Neither `team` nor `session` is a read-only tool, so
   plan mode refuses both by name and tells the model to exit and get approval; the board
   stays readable, since `list` is the one action it admits. Assign after the plan is
-  approved.
+  approved by the lead — or the person, with `/board approve`.
 - **Ownership is advisory.** `assign` does not create a path claim; the peer still claims
   the paths it edits through `session`.
 
@@ -188,7 +219,8 @@ decision the plain unassigned row never offered: re-offer, `assign` it, or take
 - **`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.
+  to assign — which is why the lead enables both, and why enabling one never loads the
+  other.
 - **`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
@@ -207,9 +239,9 @@ decision the plain unassigned row never offered: re-offer, `assign` it, or take
   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.
+  second tool to be on a team, so `/board` joins, the first claimed card 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.
@@ -221,10 +253,17 @@ decision the plain unassigned row never offered: re-offer, `assign` it, or take
   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.
+- **`reclaim` and `claim` are here, and in `board`.** Every one of them is one store
+  operation, so the lane rules, the WIP limit, the refusal a waiting card gets, and the
+  offer record cleared are the store's answer rather than a second one the round keeps in
+  step by hand. `reclaim` belongs here because it is the compensation for a dispatch that
+  did not land; `claim` belongs here because the round is where a lead sees work nobody
+  took, and a lead told to "take it" should not have to leave the tool to do it. The
+  card's *life* after a claim — plan, contract, moves, finish — stays `board`'s: the round
+  hands work out and takes it, and the card is lived in one place.
+- **Rejected: `assign` to yourself.** Handing a card to your own label records you as the
+  owner and mails your own inbox, which is a claim with an extra message and no next step;
+  it is refused, naming `claim`.
 - **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.
@@ -236,8 +275,8 @@ decision the plain unassigned row never offered: re-offer, `assign` it, or take
 
 | 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 |
+| `index.ts` | The factory: gate on the opt-in switch (`PI_ENABLED_EXTENSIONS`) and `PI_DISABLED_EXTENSIONS`, build the session, register the tool and the command |
+| `schema.ts` | The tool's four 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>]` |

package/docs/extensions/todo.md

@@ -10,21 +10,19 @@ one update when work lands without one.
 
 ## 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 |
+| Capability | How | What you get |
+|---|---|---|
+| Whole-list tracking | `todo` | One call replaces the list; an empty list clears it. |
+| Live progress rail | the `todo` widget | Progress and the active item, one line above the editor. |
+| 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. |
+| 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. |
+| 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. |
+| 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`. |
+| Full list on demand | `/todos` | A scrollable screen in the order the model submitted. |
+| Headless listing | `/todos` outside `tui` | RPC, print, and JSON modes get the same list as a notification, with no terminal screen. |
+| Branch-following state | tool-result `details` | The list survives `/resume` and `/tree`, and abandoned branches never leak in. |
+| Lag reminder | the `agent_before_settle` nudge | One hidden reminder and one forced continuation when mutating work lands without a todo update. |
+| Structured result | `structuredContent` | Codemode scripts read the list as data. |
 
 ## Quickstart
 
@@ -238,10 +236,12 @@ depends on config.
 | `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). |
-| `format.ts` | Model-facing and transcript text (pure). |
-| `tui.ts` | Widget and scrollable `/todos` components, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
+| `format.ts` | Model-facing and transcript text, plus the item row both surfaces draw (pure). |
+| `render.ts` | The `TodoResult` transcript block over the memoized rail, drawn from `lib/tui/render-cache.ts`. |
+| `widget.ts` | The persistent one-line widget and its `WIDGET_KEY`, drawn from the `lib/tui/` kit. |
+| `view/todo-screen.ts` | The scrollable `/todos` screen, loaded on first use (`titleRule`, `dockListFrame`, `emptyState`). |
 | `config.ts` | Widget config load/validation (the `todo` section of `bytefly.json`). |
 | `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`. |
+| `tools.test.ts`, `runtime.test.ts`, `view/todo-screen.test.ts` | The capability suites, declared in `test/suite-manifest.ts`. |

package/docs/extensions/watch.md

@@ -8,32 +8,30 @@ 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 |
+| Capability | How | What you get |
+|---|---|---|
+| 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. |
+| Line matching | `watch add` | An include pattern with an optional exclude list, case-insensitive unless `caseSensitive` is set. |
+| Match delivery | `watch add`, `watch matches` | Pending matches are reported to the model at the start of the next turn. |
+| Wake turn | `watch add`, the `wakeOnMatch` key | One triggered turn as soon as the agent is idle, including right after a running turn settles. |
+| Desktop alert | `my-pi-agent/watch-match`, `notify.enabled`, `notify.matchFound` | A wake match leaves the terminal as an OS notification. |
+| Live status | `watch add`, the `showStatus` key | A `⊚ N` running chip and a `! N` unreported-match chip, plus one alert per unreported burst. |
+| Command outcome | `watch status`, `watch list` | A command watcher reports its exit code or error, including the captured signal, instead of only "stopped". |
+| Liveness detail | `watch list`, `watch status` | A running watcher names its pid and elapsed time; list rows sort running watchers first, newest next. |
+| Transcript rendering | the `watch` transcript block | The outcome line, at most eight rows, and a `(ctrl+o to expand)` hint keep the transcript compact. |
+| Sanitized output | `watch matches`, `/watch matches` | Model- and remote-authored output is stripped of control characters before it reaches a terminal or a notification. |
 
 ### 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 |
+| Capability | How | What you get |
+|---|---|---|
+| Watcher inventory | `watch list`, `watch status`, `/watch list` | Each watcher's source, state, and line and match counts, singly or as a table. |
+| Matched lines | `watch matches`, `/watch matches` | The matching lines, sanitized and read from a bounded history. |
+| Raw output | `watch logs`, `/watch logs` | The merged output tail, for checking a pattern that matches nothing. |
+| Watcher screen | `/watch` | A dock screen with the watcher list, the focused watcher's detail, and its matches pane. |
+| 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. |
 
 ## Quickstart
 
@@ -224,7 +222,8 @@ The shared seams are `lib/`'s: `lib/spawn.ts` (spawn, tree-kill), `lib/lines.ts`
 `lib/tui/status-controller.ts` (chips and the alert), and
 `lib/tui/dock-screen.ts` (the `/watch` frame, navigation, and confirm layer).
 What stays here is the watcher policy: the tailer, the matcher, the source
-model, the command-child lifecycle in `child.ts`, and the watcher vocabulary.
+model, and the watcher vocabulary; the command-child lifecycle is
+`lib/child.ts`, which `job` drives too.
 
 The file tailer polls and exposes `tick()` publicly; the interval is a thin
 wrapper over `tick()`, so tests drive matching deterministically with no real
@@ -248,18 +247,19 @@ outlive the session.
 | `tools.ts` | The `watch` tool definition, execution, and transcript rendering. |
 | `schema.ts` | TypeBox parameters and pure `normalizeCall` validation. |
 | `types.ts` | `WatchAction`/`WatchStatus`, `WatchRecord`, `WatchDetails`, `PendingMatch`. |
-| `runtime.ts` | The session-scoped watcher table, matcher, poll tick, and shutdown; spawning and tree-kill come from `child.ts`, line splitting from `lib/lines.ts`. |
-| `child.ts` | A command watcher's process lifecycle: spawn, the SIGTERM → SIGKILL grace, and the shutdown drain, over the injected `SpawnFn`/`KillTreeFn` seams. |
-| `format.ts` | Pure text formatting; sanitization is `lib/format.ts`'s `sanitizeUntrustedLine`. |
+| `runtime.ts` | The session-scoped watcher table, matcher, poll tick, and shutdown; spawning and tree-kill come from `lib/child.ts`, line splitting from `lib/lines.ts`. |
+| `format.ts` | Pure text formatting, including the watcher row both surfaces draw; sanitization is `lib/format.ts`'s `sanitizeUntrustedLine`. |
 | `ui.ts` | Status chips and the match alert, over the shared `lib/tui/status-controller.ts` (chips, attached context, `notify`). |
-| `tui.ts` | The `WatchResult` transcript block over the shared `TailResult`, and the `/watch` screen as a `DockListScreen` subclass: watcher rows, focus block, counts, verbs. |
+| `render.ts` | The `WatchResult` transcript block over the shared `TailResult`. |
+| `view/watch-screen.ts` | The `/watch` screen as a `DockListScreen` subclass: watcher rows, focus block, counts, verbs, loaded on first use. |
 | `commands.ts` | The `/watch` command and its completions. |
 | `config.ts` | The `watch` config section load and normalization. |
 
 ## Testing
 
-`runtime.test.ts` covers config, schema, the child supervisor, and the tailer
-with a fake clock and fake children; `tools.test.ts` covers the tool and command;
-`ui.test.ts` covers registration, formatting, the status chips, and the screen
-through the shared `createFakePi`/`fakeCtx` doubles. The test harness is
-`test/helpers/fixtures/watch.ts`.
+`runtime.test.ts` covers config, schema, and the tailer with a fake clock and
+fake children; `tools.test.ts` covers the tool and command; `format.test.ts` covers
+the text `format.ts` builds; `view/watch-screen.test.ts` covers registration, the status
+chips, and the screen through the shared `createFakePi`/`fakeCtx` doubles. The test
+harness is `test/helpers/fixtures/watch.ts`, which also builds the `WatchRecord` a
+test varies one field of.

package/docs/extensions/web-access.md

@@ -8,8 +8,6 @@ reads a URL as text. Both are `direct`, active on registration, and read the
 
 ## 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 |
 |---|---|---|---|
 | Web search | `web_search` | Titles, URLs, snippets, and a direct answer when the provider has one. | Shipped |
@@ -410,11 +408,11 @@ the content type and size.
 | `fetch/tool.ts` | `web_fetch` definition, activation, rendering |
 | `fetch/config.ts` | Fetch config type, defaults, clamping |
 | `fetch/schema.ts` | Params/output schema, `resolveRequest()` |
-| `fetch/page.ts` | Fetch + redirect-following + content-type routing; PDF extraction is injected via `FetchDeps` from the shared `lib/pdf.ts` |
+| `fetch/page.ts` | Fetch + redirect-following + content-type routing; PDF extraction is injected via `FetchDeps` from the shared `lib/pdf.ts`. Loaded by the tool's execute, so a session that never fetches pays nothing |
 | `fetch/structured.ts` | JSON/CSV/XML body → readable text, or `undefined` to keep the raw body |
 | `fetch/ssrf.ts` | URL/host validation and private-address blocking |
 | `fetch/extract.ts` | HTML → title + readable text |
-| `fetch/find.ts` | Passage search (exact/insensitive/fuzzy) |
+| `fetch/find.ts` | Passage search (exact/insensitive/fuzzy); loaded by the tool's execute |
 | `fetch/cache.ts` | Per-registration LRU/TTL page cache (`createPageCache`) |
 | `fetch/format.ts`, `fetch/types.ts` | Result text and data types |
 

package/docs/extensions/wechat.md

@@ -8,8 +8,6 @@ subprocess per peer.
 
 ## 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 in a tagged release, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
 ### Conversation
 
 | Capability | How | What you get | Status |
@@ -28,22 +26,22 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 
 ### Remote control
 
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Plan review over chat | automatic: an `exit_plan_mode` on a WeChat turn | The plan arrives as a file, then one compact editor prompt with three actions. | Shipped |
-| Forwarded dialogs | `remotePrompts` | A dialog raised inside a WeChat turn is asked and answered in that peer's chat. | Shipped |
-| Peer questions | `ask_user_question` | The peer answers their own question, numbered, and a reply cannot reach another peer's prompt. | Shipped |
-| Control screen | `/wechat` | Account, connection, per-peer rows, activity, and any waiting prompt on one live screen. | Shipped |
-| Prompt cancellation | `/wechat`, `c` on the control screen | One waiting question is withdrawn with a notice, without stopping the peer's turn. | Shipped |
-| Peer steering | `/wechat stop <peer>`, `/wechat reset <peer>` | One peer's running turn stops, or their conversation starts fresh. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Plan review over chat | automatic: a `plan` action `exit` on a WeChat turn | The plan arrives as a file, then one compact editor prompt with three actions. |
+| Forwarded dialogs | `remotePrompts` | A dialog raised inside a WeChat turn is asked and answered in that peer's chat. |
+| Peer questions | `ask_user_question` | The peer answers their own question, numbered, and a reply cannot reach another peer's prompt. |
+| Control screen | `/wechat` | Account, connection, per-peer rows, activity, and any waiting prompt on one live screen. |
+| Prompt cancellation | `/wechat`, `c` on the control screen | One waiting question is withdrawn with a notice, without stopping the peer's turn. |
+| Peer steering | `/wechat stop <peer>`, `/wechat reset <peer>` | One peer's running turn stops, or their conversation starts fresh. |
 
 ### Security and admission
 
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Owner-only admission | `allowedPeers`, `/wechat allow [peer]` | Only the owner who scanned the QR drives the agent until another sender is named. | Shipped |
-| Per-peer tool allowlist | `peers[<id>].tools` | An extra admitted peer can be narrowed to named tools; an empty list leaves none. | Shipped |
-| One poller per account | `poller.lock` | A second `pi` process is refused instead of stealing the account's messages. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Owner-only admission | `allowedPeers`, `/wechat allow [peer]` | Only the owner who scanned the QR drives the agent until another sender is named. |
+| Per-peer tool allowlist | `peers[<id>].tools` | An extra admitted peer can be narrowed to named tools; an empty list leaves none. |
+| One poller per account | `poller.lock` | A second `pi` process is refused instead of stealing the account's messages. |
 
 ### Delivery and reliability
 
@@ -57,23 +55,23 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 
 ### Pairing and transport
 
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| QR login | `/wechat login` | One scan stores the account and the bridge starts polling it, replacing a running poller. | Shipped |
-| Reconnect after expiry | `/wechat login`, `l` on the control screen | A fresh login clears the expired chip and starts a new worker instead of leaving a dead token. | Shipped |
-| Automatic start | `session_start`, a stored account | The bridge runs whenever credentials exist: the account is the on/off switch, so there is no start command. | Shipped |
-| Pause and resume | `/wechat pause`, `/wechat resume` | Polling stops while running turns finish, the lock is released, and resume takes it back. | Shipped |
-| Status chip | `/wechat status` | The status bar names the state — `✆ wechat`, `✆ wechat paused`, or a persistent `✆ wechat expired`. | Shipped |
-| Logout | `/wechat logout` | One confirmation discards the credentials and stops polling. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| QR login | `/wechat login` | One scan stores the account and the bridge starts polling it, replacing a running poller. |
+| Reconnect after expiry | `/wechat login`, `l` on the control screen | A fresh login clears the expired chip and starts a new worker instead of leaving a dead token. |
+| Automatic start | `session_start`, a stored account | The bridge runs whenever credentials exist: the account is the on/off switch, so there is no start command. |
+| Pause and resume | `/wechat pause`, `/wechat resume` | Polling stops while running turns finish, the lock is released, and resume takes it back. |
+| Status chip | `/wechat status` | The status bar names the state — `✆ wechat`, `✆ wechat paused`, or a persistent `✆ wechat expired`. |
+| Logout | `/wechat logout` | One confirmation discards the credentials and stops polling. |
 
 ### Upkeep
 
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Health report | `/wechat doctor` | Connection, token age, last poll, lock holder, per-peer queues, and recent failures in one read-only report. | Shipped |
-| Idle session cleanup | automatic: the 30-minute idle sweep | An idle peer's Pi session is disposed, so idle conversations do not keep costing context or memory. | Shipped |
-| Peer history | `/wechat history <peer> [n]` | That peer's recent messages, ten by default and twenty at most, without a live session. | Shipped |
-| Command help | `/wechat help` | Every subcommand with a line each, printed in the transcript. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Health report | `/wechat doctor` | Connection, token age, last poll, lock holder, per-peer queues, and recent failures in one read-only report. |
+| Idle session cleanup | automatic: the 30-minute idle sweep | An idle peer's Pi session is disposed, so idle conversations do not keep costing context or memory. |
+| Peer history | `/wechat history <peer> [n]` | That peer's recent messages, ten by default and twenty at most, without a live session. |
+| Command help | `/wechat help` | Every subcommand with a line each, printed in the transcript. |
 
 ## Quickstart
 
@@ -383,7 +381,7 @@ plan file is sent before one compact editor prompt with the title, first steps,
 mode status, and three actions. Reply 2 to keep planning or 3 to exit; any other
 text is a refinement. If the upload fails, the plan text is sent instead. The
 plan file stays on disk. After a Keep decision the user can say “exit plan mode”; the model
-calls `cancel_plan_mode`, which needs no plan path and records no todo or goal.
+calls `plan` action `cancel`, which needs no plan path and records no todo or goal.
 The flow mirrors the
 reference client: `getuploadurl` → AES-128-ECB encrypt → `POST` the ciphertext
 (`Content-Type: application/octet-stream`) → read `x-encrypted-param` → send a
@@ -415,7 +413,7 @@ The same run answers a second question: every message it receives is printed wit
 the `group_id` and `session_id` the protocol supplied, when it supplied them.
 Nothing in the bridge routes on either — a conversation is keyed by sender — so a
 message posted in a group is the only way to learn whether rooms are delivered at
-all, which is what the roadmap's group-chat item turns on.
+all, a question a group-chat design would have to answer first.
 
 ## Troubleshooting
 
@@ -520,7 +518,7 @@ in-process).
 | Peer dialogs | `bindExtensions({ mode: "rpc", uiContext })` on each peer session, with `createPeerUIContext(channel)` routing `select`/`confirm`/`input`/`editor` to that peer and marking the context for `askHuman`'s file/text preface. The terminal's shared `ctx.ui` is deliberately not adapted: a host turn is never answered remotely, so its dialogs stay local even while a peer turn runs. |
 | Status | The bridge's connection state (`running` / `paused` / `expired` / `stopped`) is published through `onStateChange` to `ctx.ui.setStatus(STATUS_KEYS.wechat, …)`; an expiry keeps a persistent error chip, pause keeps a warning chip, and the status bar renders it on line 2. |
 | State | Files under `<agent-dir>/wechat/`; the bridge is not authoritative UI, so nothing is stored in the transcript. |
-| Lifecycle | The factory only registers. The poll loop starts on `session_start` when an account is stored (and after `/wechat login`); `session_shutdown` closes it. One bridge per extension runtime: it is built once, `open()` is a no-op while running or paused (so the RPC double `session_start` on a session switch cannot start a second poller or resume a paused one), and shutdown is idempotent, so the reload and replacement paths (`/reload`, `/new`, resume, fork — all of which re-run the factory and emit shutdown before the new start) each end with exactly one poller. `pause()` stops the loop and releases the lock while keeping the worker, so a running turn can finish; `resume()` reacquires the lock and starts a new loop. Pause is runtime-local, so a reload or restart starts a fresh running bridge. `/wechat` screens use `ctx.ui.custom`, so they degrade (status) or decline (login, logout) while a peer turn runs. |
+| Lifecycle | The factory only registers, and the bridge module itself loads on that start: the import is deferred behind the account check, so a session with no account never evaluates the bridge, the peer worker, the transport or the lock. The poll loop starts on `session_start` when an account is stored (and after `/wechat login`); `session_shutdown` closes it. One bridge per extension runtime: it is built once, `open()` is a no-op while running or paused (so the RPC double `session_start` on a session switch cannot start a second poller or resume a paused one), and shutdown is idempotent, so the reload and replacement paths (`/reload`, `/new`, resume, fork — all of which re-run the factory and emit shutdown before the new start) each end with exactly one poller. `pause()` stops the loop and releases the lock while keeping the worker, so a running turn can finish; `resume()` reacquires the lock and starts a new loop. Pause is runtime-local, so a reload or restart starts a fresh running bridge. `/wechat` screens use `ctx.ui.custom`, so they degrade (status) or decline (login, logout) while a peer turn runs. |
 
 ## Design notes
 
@@ -594,7 +592,7 @@ status, which is what the old start/stop guidance used to do.
 | File | Responsibility |
 |---|---|
 | `index.ts` | Factory: gate, register the command and tool, wire the lifecycle events, build the bridge, open peer sessions from the host context. |
-| `bridge.ts` | The composition root: wires the poll loop, delivery, presence, admission, and inbound modules to the live client/account/cursor/state; owns the connection lifecycle, the status snapshot, and `sendToOwner`. |
+| `bridge.ts` | The composition root: wires the poll loop, delivery, presence, admission, and inbound modules to the live client/account/cursor/state; owns the connection lifecycle, the status snapshot, and `sendToOwner`. Loaded on `session_start` when an account is stored, never at registration, so a session with no account evaluates none of it. |
 | `intake.ts` | The inbound path: who is refused, what is a replay, what is a command, what answers a pending prompt, and what is queued or turned away; the admission predicates live here too. |
 | `tools.ts` | The `send_wechat` tool: owner-only proactive text or one image, with the neither-or-both refusal. |
 | `config.ts` | The `wechat` section of `bytefly.json` loading and normalization. |
@@ -608,7 +606,7 @@ status, which is what the old start/stop guidance used to do.
 | `transport/inbound.ts` | Inbound media resolution (download, decrypt, save, attach) and the hand-off to a peer's session. |
 | `transport/media.ts` | Media key/encrypt/decrypt, padded size, upload/download URL, image MIME sniff (undefined when the bytes are no image), filename sanitize, and save helpers. |
 | `state/state.ts` | `state.json` (cursor, owner, per-peer tokens, recent message ids). |
-| `state/credentials.ts` | `credentials.json` (`0600`, every stored account and the active one). |
+| `state/credentials.ts` | `<agent-dir>/wechat/` and its `credentials.json` (`0600`, every stored account and the active one). |
 | `state/lock.ts` | Poller lockfile. |
 | `peer/peer-session.ts` | One SDK `AgentSession` per peer: workspace, model, history under the state dir, dialogs bound to that peer, this bridge excluded from its resources, and the channel prompt appended. |
 | `peer/peer-worker.ts` | Per-peer queue, two peers' turns at once (`PEER_CONCURRENCY`), the fair slot hand-off, prompt/abort/reset, streamed reply parts, idle-session sweep, and the notice an abandoning close sends. |
@@ -628,7 +626,8 @@ status, which is what the old start/stop guidance used to do.
 | `dialog/prompt.ts` | Pure prompt formatting and reply parsing. |
 | `dialog/remote-ui.ts` | The peer session's UI context: dialogs and notices bound to that peer, the `askHuman` marker that delivers the file/text preface, and the `remotePrompts` switch. |
 | `view/login-screen.ts` | The `/wechat login` screen (`ctx.ui.custom`), drawn from the `lib/tui/` kit (`titleRule`, `clip`, `isCloseKey`). |
-| `view/status-screen.ts` | The `/wechat` control screen (`ctx.ui.custom`): live facts, a focusable peer list with stop/reset/history keys, and the pure one-line/body renderers, drawn from the `lib/tui/` kit (`titleRule`, `keyValueRow`, `listRow`, `paint`, `IdCursor`). |
+| `text/status.ts` | The status facts (`statusView`) and the one-line summary (`statusLine`) the text modes print. |
+| `view/status-screen.ts` | The `/wechat` control screen (`ctx.ui.custom`): live facts, a focusable peer list with stop/reset/history keys and the body renderer, loaded on first use, drawn from the `lib/tui/` kit (`titleRule`, `keyValueRow`, `listRow`, `paint`, `IdCursor`). |
 
 Modules are grouped by the role they play: `transport/` is the only place that talks to iLink, `state/` owns the three files a session leaves on disk, `peer/` runs one peer's session and its queue, `commands/` holds a slash verb, `text/` words everything a peer reads, `dialog/` asks a question over WeChat, and `view/` draws a full-screen surface. `index.ts`, `bridge.ts`, `tools.ts`, `config.ts`, `types.ts`, `errors.ts`, and `timer.ts` stay at the root — the factory, the composition root, the public surface, and the seams the directories import.