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

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

@@ -6,49 +6,52 @@ exploration or parallel work does not fill the main conversation. A single run
 can also start in the background and be inspected, collected, or cancelled with
 `/agents`.
 
+## 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 |
+
+## Quickstart
+
 ```bash
 pi --extension ./extensions/subagent    # 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
+```text
+subagent({ agent: "explorer", task: "Find every place the HTTP client is retried" })
+/agents                                 # inspect, collect, or cancel background runs
+```
 
-How the `subagent` 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/subagent.png" alt="The subagent tool's call and result: the call line and an indented body with the two tasks, each agent's section rule, its summary, and the usage total" width="100%">
 
-## Screens
-
-<img src="../../assets/agents.png" alt="The /agents screen: running and finished background helpers with status, task, elapsed time, and usage" width="100%">
-
-## What it does
-
-- **Isolated context.** Each subagent is a separate `pi` process with its own
-  transcript; only its final reply is returned to the caller.
-- **Built-in agents.** `explorer`, `planner`, `reviewer`, `worker`,
-  `researcher`, `tester`, `debugger`, and `documenter` ship with the extension.
-- **External agents.** Optionally load markdown agents from `~/.pi/agents`
-  (user) and the nearest `.pi/agents` (project). They are opt-in per scope and
-  never replace the built-ins silently.
-- **Three modes, plus background.** One agent, a parallel batch, or a sequential
-  chain; a single run can also continue after the tool returns and be collected
-  from `/agents`. A running helper adds a `↳ N` footer chip, and a finish notice
-  points back at `/agents`.
-- **Streaming.** Tool calls and progress update live in the transcript while the
-  subagent runs; the `app.tools.expand` key (`ctrl+o` by default) expands the
-  full task, tool calls, Markdown output, and usage.
-- **Bounded runs.** A per-run deadline kills a child that hangs, and reports it
-  as a failed run instead of rejecting the whole call.
-- **Optional transcripts.** Opt-in per-run stream under `.pi/subagents/`,
-  written by the parent and pruned by age and count.
-- **Inherited model.** Subagents use the dispatching session's model and thinking
-  level unless an agent overrides them (none do).
-
-## Tool
-
-`subagent` takes exactly one mode. Every call also accepts `agentScope` and
-`readOnly`.
+`subagent` — `exposure: "direct"` (the default), read-write, open-world,
+destructive, and parallel across calls: only a chain orders itself. A call takes
+exactly one mode, plus `agentScope`, `readOnly`, and `cwd`. A call with no mode,
+or with two, is refused before any process starts, and an unknown agent name is
+refused with the resolved roster.
 
 | Field | Value |
 |---|---|
@@ -59,78 +62,38 @@ How the `subagent` call and its result look in the transcript — the call line
 | `cwd` | Optional working directory for the spawned process (single mode; per-step for the others). A relative path resolves against the active root. |
 | `agentScope` | `user` (default), `project`, or `both` — which external agent directories to load. |
 | `readOnly` | `true` forces every spawned agent to a reader-only tool set; plan mode sets it automatically. |
-| `exposure` | `direct`, active by default. |
-| `annotations` | `readOnlyHint: false`, `openWorldHint: true`. |
-
-## Behaviour by mode
-
-### Single
-
-```json
-{ "agent": "explorer", "task": "Find every place the HTTP client is retried", "cwd": "." }
-```
-
-### Background
-
-```json
-{ "agent": "explorer", "task": "Map the auth module", "background": true }
-```
-
-The tool returns immediately with a run id such as `a2`. `/agents` lists every
-run with its status, elapsed time, and usage; `Enter` opens the run, `c` collects
-a finished result into the conversation, and `x` cancels a running one. While a
-run is active, its detail pane follows a bounded preview of the latest output,
-and a `↳ N` chip in the footer counts running helpers. A finish notice points
-back at `/agents`; the finalized result replaces the preview when the run
-finishes. A background run is session-owned and is bounded by the same timeout
-and transcript settings as a foreground run.
-
-### Parallel
-
-Runs up to 8 tasks, at most 4 at once. Independent tasks only.
-
-```json
-{
-  "tasks": [
-    { "agent": "explorer", "task": "Map the auth module" },
-    { "agent": "explorer", "task": "Map the billing module" }
-  ]
-}
-```
 
-Each task's output is capped at 50 KiB in the model-facing reply; the complete
-output remains in the tool details.
-
-### Chain
-
-Runs steps in order. `{previous}` in a step's `task` is replaced by the prior
-step's final output. The chain stops at the first failing step, and a chain has
-at most 8 steps (like the parallel task cap).
-
-```json
-{
-  "chain": [
-    { "agent": "explorer", "task": "Find the config loader" },
-    { "agent": "planner", "task": "Using this context, plan a refactor:\n\n{previous}" },
-    { "agent": "worker", "task": "Implement the plan:\n\n{previous}" }
-  ]
-}
-```
+## Commands
 
-## Command
+<img src="../../assets/screens/agents.png" alt="The /agents screen: running and finished background helpers with status, task, elapsed time, and usage" width="100%">
 
 | Command | What it does |
 |---|---|
 | `/agents` | Open the background-run board: inspect, collect, or cancel. |
 
 The board is TUI-only for actions; RPC, print, and JSON print the run list.
-Collecting sends the result as a user message, which starts the next turn.
+`Enter` opens the run, `c` collects a finished result into the conversation, and
+`x` cancels a running one. Collecting sends the result as a user message, which
+starts the next turn. Plan mode refuses the command until the plan is approved.
+
+## Behaviour by mode
+
+The tool and its background runs work in every mode; only the run board is a
+terminal surface.
+
+- In `tui` mode `/agents` opens the board, the footer carries a `↳ N` chip while
+  helpers run, and a finish notice points back at `/agents`.
+- In RPC, print, and JSON `/agents` reports the same runs as a notification — a
+  count, then one line per run with agent, task, status, elapsed time, and usage
+  — and there is no board and no action.
+- In plan mode `subagent` stays active but every call is forced read-only, and
+  `/agents` refuses until the plan is approved.
 
 ## Configuration
 
 Read from the shared `bytefly.json` section `subagent` (global then project),
 once per session. Keys and bounds live in the
-[configuration page](../../docs/configuration.md#subagent--delegated-runs);
+[configuration page](../configuration.md#subagent--delegated-runs);
 the behaviour is here.
 
 - **`timeoutMs`** (default ten minutes, `0` disables) bounds one child run. The
@@ -186,18 +149,75 @@ confirmation before running them in an interactive session; without a UI it
 refuses instead of running them silently. The gate is driven only by the
 project's trusted state — the model cannot turn it off.
 
+## Delegation modes
+
+One mode per call, with a single `background` run available on the single-agent
+shape.
+
+### Single
+
+```json
+{ "agent": "explorer", "task": "Find every place the HTTP client is retried", "cwd": "." }
+```
+
+### Background
+
+```json
+{ "agent": "explorer", "task": "Map the auth module", "background": true }
+```
+
+The tool returns immediately with a run id such as `a2`. `/agents` lists every
+run with its status, elapsed time, and usage. While a run is active, its detail
+pane follows a bounded preview of the latest output, and a `↳ N` chip in the
+footer counts running helpers. A finish notice points back at `/agents`; the
+finalized result replaces the preview when the run finishes. A background run is
+session-owned and is bounded by the same timeout and transcript settings as a
+foreground run.
+
+### Parallel
+
+Runs up to 8 tasks, at most 4 at once. Independent tasks only.
+
+```json
+{
+  "tasks": [
+    { "agent": "explorer", "task": "Map the auth module" },
+    { "agent": "explorer", "task": "Map the billing module" }
+  ]
+}
+```
+
+Each task's output is capped at 50 KiB in the model-facing reply; the complete
+output remains in the tool details.
+
+### Chain
+
+Runs steps in order. `{previous}` in a step's `task` is replaced by the prior
+step's final output. The chain stops at the first failing step, and a chain has
+at most 8 steps (like the parallel task cap).
+
+```json
+{
+  "chain": [
+    { "agent": "explorer", "task": "Find the config loader" },
+    { "agent": "planner", "task": "Using this context, plan a refactor:\n\n{previous}" },
+    { "agent": "worker", "task": "Implement the plan:\n\n{previous}" }
+  ]
+}
+```
+
 ## Built-in agents
 
 | Agent | Tools | Purpose |
 |---|---|---|
-| `explorer` | `read, grep, find, ls` | Fast codebase recon; returns files + line ranges, key code, architecture, and where to start. |
-| `planner` | `read, grep, find, ls` | Delegated planning in an isolated context (headless/chain); never edits. |
-| `reviewer` | `read, grep, find, ls, bash` | Reviews for bugs, security, and maintainability; bash limited to read-only `git diff/log/show`. |
-| `worker` | `read, write, edit, bash, grep, find, ls` | General-purpose executor; reports what changed. |
-| `researcher` | `read, grep, find, ls, web_search, web_fetch` | Investigates external questions and returns sourced findings with confidence. |
-| `tester` | `read, write, edit, grep, find, ls, bash` | Adds or updates tests and runs them; never weakens assertions to pass. |
-| `debugger` | `read, grep, find, ls, bash` | Root-causes a failure from evidence; read-only plus running tests/builds. |
-| `documenter` | `read, write, edit, grep, find, ls, bash` | Updates READMEs, docs, and changelogs to match the code. |
+| `explorer` | `read, grep, find, ls, read_doc` | Fast codebase recon; returns files + line ranges, key code, architecture, and where to start. |
+| `planner` | `read, grep, find, ls, read_doc` | Delegated planning in an isolated context (headless/chain); never edits. |
+| `reviewer` | `read, grep, find, ls, read_doc, bash` | Reviews for bugs, security, and maintainability; bash limited to read-only `git diff/log/show`. |
+| `worker` | `read, write, edit, bash, grep, find, ls, read_doc` | General-purpose executor; reports what changed. |
+| `researcher` | `read, grep, find, ls, read_doc, web_search, web_fetch` | Investigates external questions and returns sourced findings with confidence. |
+| `tester` | `read, write, edit, grep, find, ls, read_doc, bash` | Adds or updates tests and runs them; never weakens assertions to pass. |
+| `debugger` | `read, grep, find, ls, read_doc, bash` | Root-causes a failure from evidence; read-only plus running tests/builds. |
+| `documenter` | `read, write, edit, grep, find, ls, read_doc, bash` | Updates READMEs, docs, and changelogs to match the code. |
 
 Each agent's system prompt is appended to the subprocess, and its tool list is
 passed as `--tools`. Every built-in has an explicit allowlist, so an agent never
@@ -259,9 +279,9 @@ is the safe way to delegate exploration, and plan mode sets it automatically.
 
 The child is restricted at the process boundary, not by its prompt: the tool
 list passed as `--tools` is the intersection of the agent's tools with
-`read`, `grep`, `find`, `ls`, `web_search`, and `web_fetch`. An agent with no
-reader tools (or no `tools` declaration) gets the full reader set instead. So
-`worker` cannot write under `readOnly`, and an external agent file that
+`read`, `grep`, `find`, `ls`, `read_doc`, `web_search`, and `web_fetch`. An agent
+with no reader tools (or no `tools` declaration) gets the full reader set
+instead. So `worker` cannot write under `readOnly`, and an external agent file that
 customizes a built-in cannot widen it. A short read-only note is appended to the
 child's system prompt for behavior; the tool list is the enforcement.
 
@@ -314,6 +334,19 @@ with `{previous}` left in place, rather than the substituted prior output that
 was actually sent to the child; that output is already shown as the previous
 step's `Output`.
 
+## Limitations
+
+- Background runs are single-mode only. Parallel and chain calls wait as before.
+- A background run is session-owned: `/tree` does not move it, and a process
+  restart cannot resume it. A start entry without a finish is shown as
+  `interrupted`.
+- The collected output is capped at 50 KiB; the optional transcript keeps the
+  full stream. The `/agents` detail keeps only a bounded live preview, and a
+  finished run keeps its bounded output in the session record rather than the
+  child's full result.
+- A finish notice appears in the TUI, but there is no OS notification; the run
+  remains listed in `/agents`.
+
 ## Non-goals
 
 - **No ambient external agents.** User agents load only when an explicit
@@ -340,29 +373,19 @@ step's `Output`.
   per process: a resumed session starts from zero, and a run that never produced
   an assistant message publishes nothing.
 
-## Limitations
-
-- Background runs are single-mode only. Parallel and chain calls wait as before.
-- A background run is session-owned: `/tree` does not move it, and a process
-  restart cannot resume it. A start entry without a finish is shown as
-  `interrupted`.
-- The collected output is capped at 50 KiB; the optional transcript keeps the
-  full stream. The `/agents` detail keeps only a bounded live preview, and a
-  finished run keeps its bounded output in the session record rather than the
-  child's full result.
-- A finish notice appears in the TUI, but there is no OS notification; the run
-  remains listed in `/agents`.
-
 ## Pi integration
 
 | Aspect | Detail |
 |---|---|
 | Tool | `subagent` |
 | Exposure | `direct`, active by default |
-| Annotations | `readOnlyHint: false`, `openWorldHint: true` |
+| Execution mode | none: sibling calls are independent, each spawning its own child, so they stay parallel |
+| Annotations | `readOnlyHint: false`, `destructiveHint: true`, `openWorldHint: true` |
 | Output schema | none; the full result lives in tool-result `details` |
 | Execution | spawns `pi --mode json` subprocesses; external agents discovered from `<agent-dir>/agents` and `.pi/agents` |
+| Command | `/agents` |
 | State storage | tool-result `details`; optional per-run transcripts under `.pi/subagents/`; background start/finish entries (`subagent-background`) on the session branch |
+| Event | `my-pi-agent/subagent-finished` (`SUBAGENT_FINISHED_CHANNEL` in `lib/events.ts`) once per finished child |
 | Lifecycle | `session_start` loads the config, prunes expired transcripts, and attaches the footer chip; `session_shutdown` aborts every live background child and clears the chip |
 
 ## Design notes
@@ -442,6 +465,30 @@ step's `Output`.
 | `background-tui.ts` | The `/agents` board: a `DockListScreen` with a live output pane and width-aware facts. |
 | `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). |
 | `format.ts` | Token/usage/total line and tool-call formatting (pure, money-free). |
 | `render.ts` | `renderCall` / `renderResult` transcript rendering. |
 | `types.ts` | Shared result and process types. |
+
+## Testing
+
+```bash
+bun test extensions/subagent
+```
+
+Four co-located suites, declared in `test/suite-manifest.ts`:
+
+- `agents.test.ts` — the built-in registry, markdown discovery and pool
+  resolution, config normalisation, the parameter schema, `resolveMode`,
+  subprocess argument construction, invocation, and the finished event.
+- `run.test.ts` — the stream helpers, the concurrency limiter, `runSingleAgent`
+  against a scripted child, transcripts and pruning, the background runtime, and
+  the board component.
+- `render.test.ts` — the call and result blocks in every mode, collapsed and
+  expanded, the failure text, and component reuse.
+- `extension.test.ts` — registration, run settings, mode validation, all three
+  modes, the project-agent gate, accounting, `/agents`, the footer chip, and the
+  formatters.
+
+`runSingleAgent` takes an injectable `SpawnFn`, so no suite launches `pi` or
+spends tokens.

package/docs/extensions/team.md

@@ -0,0 +1,254 @@
+# 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 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,
+because the first peer to claim is what makes an offer into work — and `reclaim` writes the
+card alone, so it needs no bus.
+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%">
+
+*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, 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 |
+
+## 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 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
+is not: a card that session claimed is the session's, and `release` returns it.
+
+## 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, 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 |
+
+`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 parameters are one flat object, so a field is published to every action at once.
+An action reads only the fields in its row above, and a call carrying one that its
+action does not read is **refused**, naming the action that takes it — not ignored.
+`to` is the one that matters: an `offer` that named a peer was broadcast to every live
+session while the lead believed it had named one, and a `reclaim` that named one took
+the card back from its holder anyway.
+
+```
+offer does not act on to: `assign` takes it.
+```
+
+`ACTION_FIELDS` in `types.ts` is the table that answers this, `lib/stray-fields.ts` is
+the sentence, and a test holds every published parameter to an action that acts on it.
+
+### 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` broadcasts **before** it records, for the same reason: an offer nobody received
+must not leave a record claiming one happened. A refused broadcast leaves the card exactly
+as the rules read it, and the write that follows changes one field — when the offer was
+made. If the card changed in between, the peers already have the message, so the refusal
+says the offer stands as a message and the board is what it now says. The first `board
+claim` is what turns an offer into work, and the claim is what clears the record: every
+answer to an offer — a claim, an assignment, a release — takes it with it, so a record
+here means the offer is still open. 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 — 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.
+
+## 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.** 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.
+- **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.