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

package/docs/extensions/file-browse.md

@@ -93,7 +93,6 @@ selects the root.
 | `/events` | Server-Sent Events stream of `status` frames for the open page |
 | `/app.js` | the first-party client script |
 | `/theme.js` | the pre-paint theme bootstrap |
-| `/favicon.ico` | `204` (the icon is a data URI) |
 
 ## Configuration
 
@@ -171,7 +170,10 @@ global document then project document, project wins — are in
 ## The page
 
 The page is server-rendered HTML with an inline style block and inline SVG
-icons, progressively enhanced by one first-party script (`client.ts`). A folder
+icons, progressively enhanced by one first-party script (`client.ts`). Each page
+names its own subject in the tab — `browse · <folder>`, `browse · <rel>` for a file, the
+`<page> · <subject>` shape the kit's `tabTitle` gives every served page — and links the
+brand mark as an SVG data URI, in the appearance the system is in. A folder
 folds from its twisty, and a `fold all` / `expand all` button beside the filter
 folds the whole tree at once. The tree scrolls in its own pane with quick open
 and the filter pinned above it; below 860px it collapses into a `Files`
@@ -342,10 +344,10 @@ old and new sides for `lib/highlight`.
 
 While a server is running, the extension publishes a two-tone `◉ <port>` chip
 (a green circle-dot and a blue port) under the shared `browse` status key. The
-[`bytefly`](./bytefly.md) extension routes it to line 1's right zone
-beside `⎇ branch` and `⑂ worktree`; it is cleared on stop and on
-`session_shutdown`. The chip is session-local: it reflects only this session's
-server, with no cross-session sharing.
+[`bytefly`](./bytefly.md) extension routes it to line 1's right zone, after
+`⎇ branch` and `⑂ worktree` and in the same run as the board page's port chip;
+it is cleared on stop and on `session_shutdown`. The chip is session-local: it
+reflects only this session's server, with no cross-session sharing.
 
 The page has its own live status, which is what a left-open tab reads. A `◉ live`
 chip beside `read-only` says whether status is flowing (green), still
@@ -502,12 +504,17 @@ stops at the first difference because the control, not the checker, is the fix.
 | [`../../lib/escape.ts`](../../lib/escape.ts) | `escapeHtml`, the shared HTML escaping used by every renderer |
 | [`../../lib/highlight.ts`](../../lib/highlight.ts) | First-party escape-first syntax tokenizer for the code view (shared with `plan`) |
 | [`../../lib/web/index.ts`](../../lib/web/index.ts) | The shared Bytefly web brand system: tokens, base, components, layout, runtime, and markup |
-| `files/files.ts` | Classification (incl. Markdown), text reads, and one page-level walk (`directoryView`) that returns a directory's listing and its sidebar tree |
+| `files/files.ts` | The barrel over the four reads: one surface for the callers, four modules behind it |
+| `files/classify.ts` | What a name is: kind, Markdown, image, MIME type, and the text sample |
+| `files/list.ts` | Capped directory listings and one file's bytes, over injected filesystem reads |
+| `files/tree.ts` | The sidebar tree and the page-level walk (`directoryView`) that returns it with the listing |
+| `files/index.ts` | The quick-open file index, walked once per root up to a cap |
 | `text/diff.ts` | Pure unified-diff and porcelain-status parsing for the diff view |
 | `text/fuzzy.ts` | Fuzzy path matching and ranking for the quick-open palette |
 | `view/markdown.ts` | First-party escape-first Markdown-to-HTML renderer (fenced code highlighted; raw HTML through `raw-html.ts`) |
 | `view/raw-html.ts` | Allowlisted raw-HTML sanitizer: element/attribute policy, suppressed bodies, and cross-block balancing |
 | `view/urls.ts` | Shared link/image URL policy: scheme allowlist and `/view`/`/raw` rewriting |
+| `view/emit.ts` | The anchor and image elements both renderers emit, so a link written in Markdown and the same one written as HTML are one element |
 | `git/git.ts` | Read-only branch/dirty provider for the header chip |
 | `view/icons.ts` | Inline SVG sprite and the per-language mapping |
 | `view/client.ts` | The `/app.js` source: sort, wrap, copy, hunk navigation, reading progress, and the page keymap |

package/docs/extensions/job.md

@@ -365,7 +365,7 @@ rewritten.
   cached from the stdout stream for `status`/`wait`/completion notes; only the
   `/jobs` log pane reads the file.
 - **Pure logic split from IO.** `format.ts` and the reconciliation in
-  `registry.ts` are pure; `process.ts` and the runtime take injectable
+  `registry.ts` are pure; the runtime takes injectable
   spawn/liveness/kill/clock functions, so the whole suite runs without
   launching a process.
 - **The transcript reuses the `/jobs` grammar.** `job list` renders the same
@@ -388,7 +388,6 @@ rewritten.
 | `schema.ts` | Parameter schema and pure validation (a `JobCall` union). |
 | `config.ts` | The `job` section of `bytefly.json`: loading and clamping. |
 | `format.ts` | Pure formatting, duration, and transcript outcome-line helpers; sanitization is `lib/format.ts`'s `sanitizeUntrustedLine`. |
-| `process.ts` | The job-only process remainder: the `LivenessFn` seam and the `ps` start-time token. Spawn, tree-kill, and liveness itself come from `lib/spawn.ts`. |
 | `paths.ts` | Session/marker/registry/status file-name helpers. |
 | `registry.ts` | Per-session registry load/merge, legacy migration, and pure reconciliation. |
 | `reservations.ts` | Atomic `O_EXCL` job-id reservation and release. |

package/docs/extensions/plan.md

@@ -22,7 +22,7 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 | One writable artifact | `write_plan` | The plan lands as markdown under the agent directory, one store per repository, shared by its worktrees. | Shipped |
 | Approval gate | `exit_plan_mode` | The plan is read back and presented; nothing is written until the user approves it. | Shipped |
 | Session goal at approval | `goal` at approval | A `planning` goal is promoted to the plan's objective, and a session with none gets it, without a second dialog; an active goal is left alone. | Shipped |
-| Steps as todos | `exit_plan_mode` | Approval seeds the plan's steps into the todo list, with the verification section as the last item. | Shipped |
+| Steps as todos | `exit_plan_mode` | Approval seeds the plan's steps into the todo list, with the verification section as the last item; approving the same plan again replaces the items its earlier approval seeded. | Shipped |
 | Plan kept current | `set_plan_steps` | Ticking a step rewrites its checkbox in the file and its todo item in one call. | Shipped |
 | Stale-step protection | `expected` in `set_plan_steps` | A step whose number moved, is out of range, or no longer matches its text refuses the whole batch instead of ticking the wrong line. | Shipped |
 | Cancel without a plan | `cancel_plan_mode`, `/plan cancel` | Write access returns, and no todo items or goal are recorded. | Shipped |
@@ -36,7 +36,7 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 | Capability | How | What you get | Status |
 |---|---|---|---|
 | Review screen | `exit_plan_mode` | A scrollable, themed plan with approve, refine, keep, browser, and exit in the footer. | Shipped |
-| Browser page | `/plan review`, `w` on the review screen | The plan opens in a local browser as a reading-first page with live section and step progress. | Shipped |
+| Browser page | `/plan review`, `w` on the review screen | The plan opens in a local browser as a reading-first page with live section and step progress. | Partial |
 | Approval in the browser | the `/plan review` page's **Approve & run** | The plan is approved without returning to the terminal, and the steps are seeded. | Shipped |
 | Inline comments | the page's `+ Comment`, **Save feedback** | Comments are saved into the plan file as `> [!REVIEW]` lines and returned to the model. | Shipped |
 | Live page | the page's `events` stream, the plan-file poll | An edit made elsewhere repaints every open page without a reload. | Shipped |
@@ -140,7 +140,15 @@ the cap and the fix named, and nothing is written.
 
 The file is the source of truth. On approval the model follows the plan file's
 steps, and refinements rewrite the same file (`write_plan` with `plan_path`), so
-the reviewed artifact is the executed artifact.
+the reviewed artifact is the executed artifact. The text a refinement replaces is
+kept beside it, as a dotfile named for the plan and the revision
+(`.2026-10-26-1008-add-rate-limiting-r001.md`), up to the newest five: that is
+what makes two revisions diffable, and what lets a comment `carryFeedback` moved
+onto another block be checked against the text the reviewer actually read. A
+revision is a dotfile, so no scan lists it as a plan, no `plan_path` opens it, and
+the review never offers it for approval — and a refinement that changed nothing
+keeps nothing, because the copy would be the plan itself. The write's result names
+the revision it kept.
 
 ### `exit_plan_mode`
 
@@ -171,6 +179,13 @@ the todo list:
   todos, and its verification bullets are already covered.
 - Each seeded item is matched back to its step by text, so ticking a step with
   `set_plan_steps` completes the item too.
+- An approval records the step texts it seeded, per plan path, as a `plan-seeded`
+  entry. A plan refined after approval is approved again — `write_plan` needs plan
+  mode, so a second round is the way back — and that second approval **replaces the
+  leftovers its own earlier approval made**: an untouched item whose step was
+  renamed or dropped goes, while one somebody started or finished is kept and
+  named, because deleting it would erase work a reader did. `write_plan` says the
+  list is stale when it refines a plan that was approved before.
 
 **Goal-aware.** While planning, the injected context restates a pursued session
 goal as one bullet, so the plan is designed against the objective instead of
@@ -265,7 +280,8 @@ its plans hold and how old the oldest one is, both derived from the walk that ju
 happened. The directory stays the index: no registry file, nothing deletes a plan,
 and one bounded read per plan.
 
-`/plan review` is the only subcommand that takes an argument. Bare `/plan review`
+`/plan review` is the only subcommand that takes a path; `/plan share` takes the
+one word `stop` after it, and `list` and `cancel` take nothing. Bare `/plan review`
 reviews the plan this session wrote, or, in a later session, the newest plan file
 in the plans directory (newest modification time); `/plan review <path>.md` (or a
 path with a separator) reviews that plan. A line that merely starts with the word
@@ -531,8 +547,12 @@ line range it shows, and the footer lists only the keys that apply.
 <img src="../../assets/screens/plan-review.png" alt="The browser-based plan review: a sticky header with the plan title, a status chip, and the Approve & run, Save feedback, and Back to Pi actions, a Share action, a side panel with step progress and a section outline, and the plan as one measured column with a comment rail holding the owner's own comment and a teammate's @priya comment" width="100%">
 
 Press `w` on the review screen — or run `/plan review [path]` — to open the plan
-in the default browser on `127.0.0.1`. The page is a reading-first review
-surface: a sticky header carrying the plan's H1 (falling back to the file-name
+in the default browser on `127.0.0.1`. Its tab reads `plan review · <the plan's
+title>` — the page's name as the header's lockup says it, then the subject, the shape
+`lib/web/markup.ts`'s `tabTitle` gives every served page — rendered with the document
+rather than set by a script, so a strip of tabs names the plan before the page has
+finished loading. The page is a
+reading-first review surface: a sticky header carrying the plan's H1 (falling back to the file-name
 slug), a live status chip (connection, comment count, and unsaved changes), the
 theme toggle, and the review actions, over a hairline reading-progress bar. A
 sticky side panel shows the plan's `Steps` section progress and comment count above a
@@ -601,7 +621,9 @@ file and returns them to the model.
   `DOMParser`, so a code line is never parsed as markup.
 - **The file is the store.** Each comment is written as
   `> [!REVIEW] <comment>` on the line after the block it anchors to, tagged with
-  its author when a teammate wrote it (`> [!REVIEW] @alice: <comment>`). Saving is
+  its author when a teammate wrote it (`> [!REVIEW] @alice: <comment>`), and
+  marked `> [!REVIEW moved]` when a refinement carried it off the text it was
+  written on. Saving is
   idempotent per writer: that writer's previous markers are replaced and everyone
   else's are kept, so two people reviewing the same plan cannot erase each other.
   Stripping is fence-aware: a `> [!REVIEW]` line inside a code block is
@@ -617,7 +639,11 @@ file and returns them to the model.
   comment whose section is gone too moves to the plan's last block rather than
   disappearing, and every one of those placements lands beside a block, never after
   a blank line, so the page keeps the thread under its block. Only a plan with no
-  block at all leaves a comment in the unattached list.
+  block at all leaves a comment in the unattached list. Everything past the first
+  step is a guess, so a placement that is not the anchored text itself is marked:
+  the card carries a `moved` chip whose tooltip says the block changed and the
+  note was placed here, and the marker records it in the file, so the fact
+  survives a reload, a hand-off, and a save by its own author.
 - **Anchored to source.** `blocks.ts` splits the plan (fence-aware) into
   source-line ranges; a comment is placed after the whole anchored block, so a
   fenced code block is never split. A save re-checks the file against what the
@@ -705,6 +731,12 @@ both.
   Git Bash (`bash`), which must be installed for any shell command to run.
 - The read-only guarantee is a guard rail against accidental writes, not a
   security boundary (see [Security](#security)).
+- **A carried comment's new home is a guess, and only the page says so.** A note a
+  refinement could not pin to surviving text is placed by wording overlap, by the
+  gap it left, or at the plan's last block; the `moved` chip is what tells a
+  reviewer that. A reader of the plan file alone sees `> [!REVIEW moved]`, and the
+  terminal review shows the comment as a quote with no chip, so the marker is the
+  fact and the chip is one reader's way of showing it.
 - The plans directory is the only index. `/plan list` walks it on every open and
   keeps no registry, so it sees an external edit or a hand-copied plan
   immediately; it lists a file over the 256 KiB plan limit without reading it,
@@ -897,7 +929,8 @@ both.
 | `types.ts` | `PlanModeEntry`, `EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `CancelPlanModeDetails`, `SetPlanStepsDetails`. |
 | `policy.ts` | Plan mode's read-only policy, the shared prompt summary, and the bash-refusal guidance. |
 | `git-bash.ts` | `checkReadOnlyGit`: the pure allowlist that restricts `bash` to read-only git commands. |
-| `plans.ts` | Plan-file store: slug/stamp naming, directory resolution (repository, active worktree, or agent directory), containment, atomic `write`/`setSteps`/`saveFeedback`, and `read`/`latest`. |
+| `plans.ts` | Plan-file store: slug/stamp naming, directory resolution (repository, active worktree, or agent directory), containment, `write`/`setSteps`/`saveFeedback`, and `read`/`latest`. |
+| `plan-files.ts` | How a plan file reaches the disk: `writeAtomic` (a dotfile temp, then a rename, so a crash cannot truncate the plan a review is reading) and `keepRevision`, which keeps the text a refinement replaces beside it, numbered, up to the newest five. |
 | `todos.ts` | Approval-time todo merge (pure): the last list replayed from the branch, and the merge of the plan's steps into it with the cap respected. |
 | `steps.ts` | Plan-document structure: the outline, step extraction and the `Steps`-section scope, the plan's own goal (`goalSection`), and the checkbox edit. |
 | `sections.ts` | The one fence-aware heading scan: `extractSections`, `sectionKeys` (the key that tells two identically titled sections apart), and the `HEADING` / `FENCE` / `normalizeHeadingText` vocabulary `blocks.ts` reads a heading through. |
@@ -920,11 +953,18 @@ both.
 | `web-page.ts` | The review page shell (header, reading progress, review facts, section outline, shortcut sheet, approve confirmation, share and name dialogs), its data island, and inline CSS. |
 | `web-share.ts` | Pure sharing rules: the reachable LAN addresses from an injected snapshot, one tokenized URL, the link table (mint, find, revoke, list, state) with its cap, and the reasons a share is unavailable. |
 | `web-share-session.ts` | The shared listener: its bound address, the link table over the session's tokens, `ShareState`, and invite/revoke/stop/close, injected with the request handler, role map, and frame hooks. |
-| `web-client.ts` | The `/client.js` source: state and wiring (comment rail, save/approve/back, keyboard nav, the stream's lifetime) over the three fragments below. |
+| `web-keys.ts` | The client's keyboard as typed source (`WEB_KEYS_JS`): `handleKey` — Esc peels the composer before closing, a field and the shortcut sheet own their keys, and `s` is the write the page offers — and `rememberSelection`, which keeps the text a reader selected as the next comment's quote. |
+| `web-settle.ts` | The client's settlement as typed source (`WEB_SETTLE_JS`): `submitAnnotations` — one POST shape whose 409 disables the writes, offers a reload and says the server's own sentence — and the four ways a review ends, of which only the owner's save, approve and close settle it. |
+| `web-plan.ts` | The client's frame as typed source (`WEB_PLAN_JS`, `renderPlanFrame`): it draws every block and its comment rail, then puts the reader back — focus only when it was inside the plan, the active block in place rather than by scrolling. Reads arrive as getters, mutations leave as callbacks, so the bundle keeps every variable. |
+| `web-composer.ts` | The client's composer lifecycle as typed source (`WEB_COMPOSER_JS`): `closeComposer` (over one `ComposerDeps` the client builds where the state is), `reopenComposer` for the draft a reload interrupted, and `commentOnActive`, which returns the index so the client keeps its one `activeIndex`. |
+| `web-draft.ts` | The client's draft guard as typed source (`WEB_DRAFT_JS`): `draftTextarea` answers the open composer's textarea when it holds text, and `guardDraft` refuses the ways off the page, names the reason once, and puts the cursor back in it. |
+| `web-blocks.ts` | The client's block navigation as typed source (`WEB_BLOCKS_JS`): `blockElements`, `setActive` and `moveActive` — which return the index they computed, so the client keeps the one `activeIndex` — and `blockAtLine`, which needs both the rendered block and its island entry. |
+| `web-client.ts` | The `/client.js` source: the composition root, and nothing else by decision — the element handles, the state each rule is handed, one zero-argument adapter per rule, the listeners that attach them, the `EventSource` that keeps a tab's presence known, and the boot order. Every rule it used to hold lives in the `web-*.ts` modules below, where it can be typed and driven. |
 | `web-comments.ts` | The client's comment half: selection quotes, the composer, authored cards and who may edit them, delete-with-undo. |
 | `web-collab.ts` | The client's collaboration half: the link list with copy and per-link revoke, the reviewer's name, and the island refetch a stream frame triggers. |
 | `web-markdown.ts` | The client's document half: `safeHref` and the inline/table/code/list rendering (interpolated into `web-client.ts`). |
 | `web-chrome.ts` | The client's chrome half: the state chip, the status line, the header, and reading progress (interpolated into `web-client.ts`). |
+| `web-outline.ts` | The client's outline as typed source (`WEB_OUTLINE_JS`): `sectionFor` — the last heading at or before a line — `renderOutline`, which builds the list and hands back the counters it made, `observeSections`, which watches the blocks and returns the one watcher the client keeps, and `renderFacts`, which paints the step progress and counts each comment under its heading. |
 | `path-guard.ts` | Recursive path-argument detection for the read-only backstop. |
 | [`../../lib/browser.ts`](../../lib/browser.ts) | Cross-platform default-browser opener (shared with `file-browse`). |
 | [`../../lib/plan-entry.ts`](../../lib/plan-entry.ts) | Plan-mode entry shared with `goal`: the read-only summary, the consent sentence, and the `pi.events` request `plan` answers by enabling the mode. |
@@ -943,7 +983,7 @@ both.
 bun test extensions/plan
 ```
 
-Eleven co-located suites, declared in `test/suite-manifest.ts`:
+Twelve co-located suites, declared in `test/suite-manifest.ts`:
 
 - `plans.test.ts` — the plan-file store: naming, directory resolution, atomic
   writes, `read`/`latest`/`index`, containment, `setSteps`, `saveFeedback`, and
@@ -958,6 +998,11 @@ Eleven co-located suites, declared in `test/suite-manifest.ts`:
 - `web.test.ts` — the browser review: the comment codec, the router, the page
   roles and page shell, the client script, the stream, the plan-file poll, the
   share rules, and a real loopback session.
+- `web-behaviour.test.ts` — the served review, driven in a real browser through
+  the router: the blocks and the plan's name, a block's comment control opening the
+  composer with Escape peeling it before the review, a stored comment in its block's
+  rail and the header's count, and the outline jumping to the section it names. It
+  skips where no browser is installed, naming `PI_CHROME`.
 - `web-share.test.ts` — the LAN address selector, `shareUrl`, the link table with
   its cap, and the reasons a share is unavailable.
 - `commands.test.ts` — `/plan review`, `/plan list`, `/plan share`, and the one

package/docs/extensions/session-bus.md

@@ -16,15 +16,15 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 
 | Capability | How | What you get | Status |
 |---|---|---|---|
-| Membership | `session join [label]`, `/team join [<label>]`, the board's `w` | The join: this session is on the bus under a stable label peers address, and listens for mail unless told not to. A label given to `session join` or `/team join` is also Pi's session name, so the footer and `/resume` agree with the record; `w` joins under the name the bus derives and writes nothing to Pi. | Unreleased |
-| Peer discovery | `session status` | Every active session with its unread count and claims, plus this session's identity, in one read. | Shipped |
+| Membership | `session join [label]`, `/team join [<label>]`, `/board`, any `board` action that writes, the board's `w` | The join: this session is on the bus under a stable label peers address, and listens for mail unless told not to. A label given to `session join` or `/team join` is also Pi's session name, so the footer and `/resume` agree with the record; `/board` joins as the page's seat (`team-lead`) or, on a page it is only watching, under its own label; the first `board` action that writes joins under the name the session already has; `w` joins under the name the bus derives and writes nothing to Pi. | Shipped |
+| Peer discovery | `session status` | Every active session with its unread count and claims, plus this session's identity, in one read — and a session whose process is gone says so, its paths free from that read on. | Unreleased |
 | Live board | `/sessions` | Sessions, this session's unread mail, and every claim held on the repository, on one screen. | Shipped |
 | Board actions | `/sessions` (`w`, `x`) | Start or stop listening from the board, or release an own claim behind a confirmation, without leaving it. | Shipped |
 | Short messages | `session send` | One message per recipient, addressed by label or id, with a broadcast for events. | Shipped |
 | Message kinds | `session send` with `kind` | A `message`, `event`, `ask`, or `handoff` keeps its meaning; `ask` does not block the sender, and a `handoff` is named as the work it assigns. | Shipped |
 | Message paths | `session send` with `paths` | A message can name the repository paths it concerns, echoed in the inbox row. | Shipped |
 | Inbox on demand | `session inbox` | Up to `limit` messages, oldest first, consumed only when the model asks. | Shipped |
-| Listening | `session join` | New mail reported at the next turn; `join({wake: true})` raises one turn once the agent is idle, and `join({listen: false})` stops it. | Unreleased |
+| Listening | `session join` | New mail reported at the next turn; `join({wake: true})` raises one turn once the agent is idle, and `join({listen: false})` stops it. The record carries whether this session listens, so a peer's status read answers it without asking. | Shipped |
 | Path claims | `session claim`, `session release` | A file or directory prefix held by one session at a time. | Shipped |
 
 ## Quickstart
@@ -55,12 +55,12 @@ collapsed line that expands to the board's rows.
 
 | Action | Inputs | Result |
 |---|---|---|
-| `status` | — | Active sessions with unread counts, claims, and this session's identity. Prunes stale records. A read: it never adds this session to the bus. |
+| `status` | — | Active sessions with unread counts, their state, claims, and this session's identity. A session whose process is gone is listed as `gone` until its heartbeat ages out, and its claims are not listed at all. Prunes stale records. A read: it never adds this session to the bus. |
 | `send` | `to`, `text`, optional `kind`, optional `paths` | Writes one message per recipient. `to: "*"` is only valid with `kind: "event"`. |
 | `inbox` | optional `limit` | Returns and deletes up to `limit` messages, oldest first (default 20, max 50). |
 | `claim` | `paths` | Claims repository-relative files or directory prefixes; returns conflicts with their owner. |
 | `release` | `paths` | Removes claims owned by this session; reports paths owned by someone else. |
-| `join` | optional `label`, `wake`, `listen` | Joins the bus, names this session on it and in Pi when a label is given — the same path and uniqueness rule as `/team join`, so the footer and `/resume` agree with the record peers address — and starts listening for mail. `wake: true` raises one turn per burst once the agent is idle; `wake: false` reports at the next turn; `listen: false` joins without listening. A label a live session holds is refused with its owner named, and the refusal leaves both names and the watch alone. The result reports the label the bus settled on and whether mail will reach this session. |
+| `join` | optional `label`, `wake`, `listen` | Joins the bus, names this session on it and in Pi when a label is given — the same path and uniqueness rule as `/team join`, so the footer and `/resume` agree with the record peers address — and starts listening for mail. `wake: true` raises one turn per burst once the agent is idle; `wake: false` reports at the next turn; `listen: false` joins without listening. A label a live session holds is refused, naming the session that holds it — its id, since the label it holds is the one you asked for — and the refusal leaves both names and the watch alone. The result reports the label the bus settled on and whether mail will reach this session. |
 
 A claim is all-or-nothing: if one path conflicts, nothing is claimed. A claim on
 a directory conflicts with claims below it and above it, so `src/api` and
@@ -167,8 +167,11 @@ listening watch is what raises the turn.
   session to the bus, so an unjoined session reads a board it is not on until it
   joins or acts.
 - **Membership is per session and session-only.** It survives neither a resume nor a
-  new process; unread mail is previewed once more after `/resume`, and the record
-  goes when the session stops.
+  new process: the record and every claim it held go when the session stops, and a
+  resumed pane is off the bus until it joins again. What does survive is everything
+  stored as a file — unread mail is previewed once more after `/resume`, and the
+  label a rejoining session takes is the same one, because it derives from Pi's
+  session name (`runtime.test.ts`, *a resume*).
 - **The board acts on your own state only.** `w` starts or stops listening and `x`
   releases a claim it holds. Mail is a preview, not a consume: the board never
   deletes a message, never marks one reported, and never touches a peer's inbox or
@@ -178,8 +181,18 @@ listening watch is what raises the turn.
   both sides to keep replying; the answer is to stop listening on one of them.
 - **No broadcast history.** A broadcast reaches the sessions active at send time;
   a session that joins later does not receive it.
-- **No forced claims.** A crashed owner blocks its paths until the session TTL
-  expires. This is deliberate; stealing a claim is worse than waiting.
+- **No forced claims.** There is no takeover while an owner can still answer: a
+  claim is released by its owner, or by the next bus call once the owner's process
+  is gone. A *hung* owner still blocks its paths until the session TTL expires,
+  because a running process is not evidence of a working one.
+- **A dead process is named, not waited out.** A record carries its `pid` and, where
+  the host can name one, that process's start time. A pid that is no longer running,
+  or one whose start time is not the record's (a reused pid), reads `gone` at once:
+  its label is free, the paths it held are nobody's, and `session status` and
+  `/sessions` count it. It keeps its row until its heartbeat ages out, so a lead can
+  see what died and reclaim it. A record with no `pid` — and a platform without
+  `ps`, such as Windows — falls back to the heartbeat rather than being called dead
+  on no evidence.
 - **Bounded by TTL.** An idle session with a stopped heartbeat is pruned after
   ten minutes; its record, its claims, and an inbox directory left empty go with
   it, and its unread mail expires after 24 hours. A claim belongs to a record
@@ -202,7 +215,7 @@ listening watch is what raises the turn.
 | Tools | `session` — one action-shaped tool; `readOnlyHint: false`, `destructiveHint: true`, `openWorldHint: false`, `executionMode: "sequential"`. |
 | Commands | `/sessions` — the board in `tui`, the listing elsewhere; no arguments and no sub-commands. |
 | UI | `tui` mounts `SessionListComponent` through `withPolledScreen` (rails suppressed, a 1 s read-only poll of `snapshot()` + `peek()`); every other mode prints through `ctx.ui.notify`. No status chip, so listening never changes the footer. |
-| Events | `session_start` resolves the repository and arms the mail trigger, without joining; `before_agent_start` reports queued non-wake mail at the next turn, `agent_settled` retries a wake the run suppressed, and `context` prunes stale notices; `session_shutdown` clears the heartbeat, the watch ticker, and the record. The seven hooks are `lib/report.ts`'s `registerPendingChannel`, not a local copy. |
+| Events | `session_start` resolves the repository and arms the mail trigger, without joining; `session_tree` only repaints, since navigating the tree changes no pending record; `agent_start` marks the run busy; `before_agent_start` reports queued non-wake mail at the next turn; `agent_settled` retries a wake the run suppressed; `context` prunes stale notices; `session_shutdown` clears the heartbeat, the watch ticker, and the record. The seven hooks are `lib/report.ts`'s `registerPendingChannel`, not a local copy. |
 | State | Files under `<agent-dir>/session-bus/<repo-key>/`; nothing in the session branch. Listening is session-only. `/resume` re-registers the same session id. |
 | Lifecycle | The factory only registers. The runtime starts on `session_start`; heartbeat, watch ticker, and cleanup belong to it. Disabling `session-bus` through `PI_DISABLED_EXTENSIONS` registers nothing. |
 | Mode | Uses `ctx.mode` to decide whether `/sessions` mounts the board and how a label is derived; nothing joins at start in any mode; `askHuman` is not involved and no status chip is published. |

package/docs/extensions/team.md

@@ -2,14 +2,16 @@
 
 `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.
+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 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%">
+<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.*
@@ -21,11 +23,11 @@ owner whose label nothing answers to, and a teammate that is not listening.*
 | 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 |
+| 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 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 |
+| 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
 
@@ -66,9 +68,10 @@ who is live but not listening. `/board status` repeats only what the last `/boar
 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.
+**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
 
@@ -78,12 +81,26 @@ label is shared with the session that serves the page; the ids are not.
 | 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 |
+| `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:
@@ -94,10 +111,15 @@ label nobody answers to cannot be handed a card, and the result says so.
 | 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.
+`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
@@ -118,7 +140,11 @@ read it with `session inbox`, record the plan, and start. The card is already th
 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.
+`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
 
@@ -150,8 +176,10 @@ An offer is advice: nothing is theirs until they claim it, and a card nobody cla
   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.
+- **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`.
 

package/docs/extensions/wechat.md

@@ -594,7 +594,8 @@ 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, slash dispatch, 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`. |
+| `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. |
 | `types.ts` | Wire and domain types. |

package/docs/extensions/worktree.md

@@ -65,7 +65,7 @@ four are `executionMode: "sequential"`, and only `list_worktrees` is read-only.
 | Tool | Usage |
 |---|---|
 | `enter_worktree` | `name` to create a worktree, or `path` to enter an existing one. Errors if already isolated. |
-| `exit_worktree` | optional `remove` and `keepBranch`. Returns the clean/keep/remove decision and a `handoff` (`branch`, `base`, `ahead`, `merged`). |
+| `exit_worktree` | optional `remove` and `keepBranch`. Returns the clean/keep/remove decision and a `handoff` (`branch`, `base`, `ahead`, `commits`, `merged`). |
 | `prune_worktrees` | no parameters. Removes eligible managed worktrees and reports the rest. |
 | `list_worktrees` | no parameters. Read-only status: active root, inactive overrides, isolation gaps, managed worktrees. |
 
@@ -77,11 +77,14 @@ it.
 `exit_worktree` returns to the main checkout. A clean worktree is removed
 automatically; one with uncommitted changes or new commits prompts (or is kept
 in non-interactive mode). Its result ends with a **handoff**: the branch, how
-many commits it holds beyond the merge target, whether that target already
-contains them, and the `git merge --no-ff` and `gh pr create` commands that
-finish the task. The tool never commits, merges, pushes, or opens the PR. A
-branch that still holds work (uncommitted changes, or commits not reachable from
-the recorded base) is never force-deleted, even with `remove: true`.
+many commits it holds beyond the merge target, how many it made since it was
+created, whether that target already contains them, and the `git merge --no-ff`
+and `gh pr create` commands that finish the task. A branch with no commits of its
+own says so rather than claiming a merge — a worktree that never committed is an
+ancestor of its base, and "merged" would read as work that landed. The tool
+never commits, merges, pushes, or opens the PR. A branch that still holds work
+(uncommitted changes, or commits not reachable from the recorded base) is never
+force-deleted, even with `remove: true`.
 
 While isolated, `read`/`write`/`edit`/`bash`/`grep`/`find`/`ls` all resolve
 relative paths inside the worktree, and:
@@ -113,6 +116,12 @@ instead, so there is no gap to report. `unverifiable` appears only while
 reset at session start. `doctor` reports the `powershell` switch as `degraded`
 when it is off and notes the two structural gaps, which no setting closes.
 
+Managed worktrees follow the header, one row each, as `path`, branch, and the
+marks in brackets: `current`, `missing`, `dirty (2)`, `ahead 3`, `behind 1`, `no
+commits`, `commits 4  merged`, `locked`, `used 2d ago`. A row with nothing else to
+report says `clean` — the same word the `/worktree` screen prints, because both
+read `statusMarks` rather than each deciding what an empty row means.
+
 ## Commands and flags
 
 | Command / flag | What it does |
@@ -136,10 +145,14 @@ being ignored.
 <img src="../../assets/screens/worktree.png" alt="The /worktree screen: a Worktrees title rule with a `4 worktrees · 1 dirty · 1 ahead` summary, the current dark-mode row carrying its ahead count, a dirty row, a merged row, and a stale-locked row, the focused row's path and base with the Not isolated gap under it, and the key hints" width="100%">
 
 `/worktree` on its own opens a list screen: one row per managed worktree with its
-state (current, dirty, ahead, behind, merged, locked, last used), the active
-worktree's base and isolation gaps under the focused row, and a detail pane for
-the selected one. Outside a terminal — print, RPC, JSON — the same facts print as
-text instead, which is also what the model's `list_worktrees` reads.
+state (current, dirty, ahead, behind, commits, merged, locked, last used), the
+active worktree's base and isolation gaps under the focused row, and a detail
+pane for the selected one. A worktree that has not committed since it was created
+says `no commits` instead of `merged`: it is an ancestor of its base, which git
+alone cannot tell from a branch that landed. When work did land, the row says how
+much — `commits 2  merged`. Outside a terminal — print, RPC, JSON — the same
+facts print as text instead, which is also what the model's `list_worktrees`
+reads.
 
 | Key | What it does |
 |---|---|
@@ -298,10 +311,11 @@ use, falling back to directory mtime for a worktree with no record.
   writes are guarded (relative paths are not isolated), and `list_worktrees`
   reports it. `skipOverrides` is read at load time, from the process working
   directory.
-- `git branch --merged main` calls a worktree branch merged whenever it matches
-  its base, so a worktree that never committed looks landed while its
-  uncommitted work is still there. Read `git -C <path> status` before removing
-  one; `list_worktrees` reports the same clean/merged flags.
+- The commit count behind `no commits` comes from the commit a worktree was
+  created at, which the registry records. A worktree this package did not create
+  has no fork point on record, so it falls back to what `git branch --merged`
+  says: for one of those, a worktree that never committed still reads as merged.
+  Read `git -C <path> status` before removing one.
 - The guard is best-effort at the shell level: command substitution, `eval`, and
   `sh -c` are only covered when `blockUnparsableCommands` is enabled, and real
   isolation of arbitrary shell writes needs an OS sandbox. `/worktree` names the
@@ -330,7 +344,7 @@ use, falling back to directory mtime for a worktree with no record.
 | Contract | Detail |
 |---|---|
 | Registration | The default export calls `registerWorktree`: root-tool overrides, the `--worktree` flag, lifecycle listeners, model tools, and the `/worktree` command. Nothing long-lived starts at load. |
-| Tools | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees` via `registerTool`. All `executionMode: "sequential"`. Annotations: `enter_worktree` destructive + open-world; `exit_worktree`/`prune_worktrees` destructive; `list_worktrees` read-only. No `outputSchema`; structured state is returned in tool-result `details` — `exit_worktree` carries `{ state, removed, handoff }`, where `handoff` is `{ branch, base, ahead, merged }`. |
+| Tools | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees` via `registerTool`. All `executionMode: "sequential"`. Annotations: `enter_worktree` destructive + open-world; `exit_worktree`/`prune_worktrees` destructive; `list_worktrees` read-only. No `outputSchema`; structured state is returned in tool-result `details` — `exit_worktree` carries `{ state, removed, handoff }`, where `handoff` is `{ branch, base, ahead, commits, merged }` (`commits` absent when the worktree has no recorded base commit). |
 | Built-in overrides | `read`/`write`/`edit`/`bash`/`grep`/`find`/`ls` are re-registered under the same names with `defaultActive: false`; each spreads the built-in definition and replaces only `execute`. `skipOverrides` is applied at load time. `powershell` is deliberately not overridden: it cannot be re-rooted without a guard, so the `tool_call` handler refuses it (see `guard.blockPowershell`). |
 | Commands | `/worktree` via `registerCommand`, with argument completions for `enter`, `exit`, and `prune`. The bare command mounts `screen.ts` in a terminal and prints the status text otherwise; `enter`/`exit`/`prune` refuse while plan mode is read-only. |
 | Flags | `--worktree` via `registerFlag`. |
@@ -407,6 +421,7 @@ one read and two renderings.
 | `root-tools.ts` | Load-time built-in overrides bound to the active root |
 | `git.ts` | Git plumbing (shared runner + read helpers) |
 | `guard.ts` | Path, shell, and git-redirect isolation checks, plus the `powershell` refusal |
+| `shell.ts` | The command-line reader those checks ask: words, segments, and redirection targets |
 | `gaps.ts` | The isolation gaps a session carries, and how they read (pure) |
 | `include.ts` | `.worktreeinclude` matcher and copy |
 | `config.ts` / `state.ts` / `status.ts` | Config, session entry shape, status text and the shared snapshot |