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

package/README.md

@@ -108,7 +108,7 @@ document. `PI_OFFLINE` skips the check;
 
 ## What you get
 
-21 extensions, 4 packaged skills, and 2 themes, grouped by the promises the
+22 extensions, 4 packaged skills, and 2 themes, grouped by the promises the
 [roadmap](./ROADMAP.md) tracks; the [guide](./docs/user-guide/) covers the same
 ground chapter by chapter. Each extension's own page in `docs/extensions/` has
 the full tool and command surface, opening with its capabilities.
@@ -126,7 +126,8 @@ the full tool and command surface, opening with its capabilities.
 | [`job`](./docs/extensions/job.md) | `job`, `/jobs` | Run long-lived shell commands in the background; inspect logs, wait, or kill them. |
 | [`watch`](./docs/extensions/watch.md) | `watch`, `/watch` | Tail a file or command output, match lines against patterns, and alert you or hand matching lines to the agent. |
 | [`session-bus`](./docs/extensions/session-bus.md) | `session`, `/sessions` (screen) | Coordinate parallel Pi sessions on one repository: discover peers, exchange short messages/events, consume an inbox, or claim paths before editing, with `/sessions` as a live board of peers, unread mail, and claims. Local, pull-based by default, with an opt-in inbox watch that raises this session's turn once it is idle; it never spawns an agent. |
-| [`board`](./docs/extensions/board.md) | `board`, `/board` | One shared feature board per repository: a card per feature, which any session claims, moves, edits, notes, finishes, and archives — a finished card leaves the board for an `archive/` pile with its notes and landed commit still readable, so a long history stops costing every read — and one loopback page that shows the same cards live in a **Board** and a **Team** tab. The page is a read view — the tools are the only writers — served as the seat `team-lead`, so a second session opens the same page instead of starting a rival one, and handing a card to a teammate is `team`'s job because only it can message them. A card can carry a priority and name the cards it waits on. Steps stay in the owner's plan and `todo`; a card is the feature, its owner, and the history that explains it. `board.port` in `bytefly.json` pins the page's port, so a bookmarked URL survives a restart. |
+| [`serve`](./docs/extensions/serve.md) | — | The session's one loopback server. `/board`, `/browse`, and a browser plan review mount path prefixes on it instead of binding their own listeners, so a session has one port, one chip, and one close path — and a second session (a peer conversation, another worktree, another Pi) still gets its own. `serve.port` in `bytefly.json` pins that port, so a bookmarked URL survives a restart, and a shared review borrows exactly one LAN address for the one page that asked. |
+| [`board`](./docs/extensions/board.md) | `board`, `/board` | One shared feature board per repository: a card per feature, which any session claims, moves, edits, notes, finishes, and archives — a finished card leaves the board for an `archive/` pile with its notes and landed commit still readable, so a long history stops costing every read — and one loopback page that shows the same cards live in a **Board** and a **Team** tab. The page is a read view — the tools are the only writers — served as the seat `team-lead`, so a second session opens the same page instead of starting a rival one, and handing a card to a teammate is `team`'s job because only it can message them. A card can carry a priority and name the cards it waits on. Steps stay in the owner's plan and `todo`; a card is the feature, its owner, and the history that explains it. The page answers at `/board` on the session's one port, so `serve.port` is the address to bookmark. |
 | [`team`](./docs/extensions/team.md) | `team`, `/team` | The lead's round over the same board. `/team join <label>` puts a session on the team, and `/board` does it for the lead as `team-lead`; then `assign` hands a feature to a running session, `offer` hands one to whoever is free — a broadcast that writes nothing, claimed by the first taker — and `reclaim` takes a card back to To do. A result says who will be woken for it and who will read it at their next turn, `/team` prints the round in the terminal without a browser, and nothing is spawned. |
 | [`context`](./docs/extensions/context.md) | `/context` | Show where the context window goes — system prompt, tool definitions, conversation by role, injected notes — and compact from the report with the before and after numbers. |
 

package/README.zh-CN.md

@@ -92,7 +92,7 @@ Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自
 
 ## 包含内容
 
-21 个扩展、4 个随包技能，以及 2 个主题，按 [路线图](./ROADMAP.md) 追踪的承诺分组；
+22 个扩展、4 个随包技能，以及 2 个主题，按 [路线图](./ROADMAP.md) 追踪的承诺分组；
 [用户指南](./docs/user-guide/) 按章节讲述同样的内容。每个扩展在 `docs/extensions/`
 下的页面提供完整的工具与命令说明，并以能力表开头。
 
@@ -109,7 +109,8 @@ Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自
 | [`job`](./docs/extensions/job.md) | `job`, `/jobs` | 在后台运行长时 shell 命令；查看日志、等待或结束它们。 |
 | [`watch`](./docs/extensions/watch.md) | `watch`, `/watch` | 跟踪文件或命令输出，按模式匹配行，并提醒你或把匹配的行交给智能体。 |
 | [`session-bus`](./docs/extensions/session-bus.md) | `session`, `/sessions`（屏幕） | 在同一仓库的多个 Pi 会话之间协调：发现彼此、交换简短消息/事件、读取收件箱、编辑前声明路径；`/sessions` 是显示对等会话、未读邮件和路径声明的实时面板。本地、默认拉取式；收件箱监视需会话自行开启，空闲时会唤起本会话的一轮，从不创建智能体。 |
-| [`board`](./docs/extensions/board.md) | `board`、`/board` | 每个仓库一块共享看板：一张卡片代表一个 feature，任何 session 都可以认领、移动、编辑、加注、完成、归档——已完成的卡片会离开看板进入 `archive/`，其注记与落地 commit 仍可读，长历史不再拖累每次读取——同一个看板在浏览器里以 **Board** 和 **Team** 两个 tab 实时显示。页面只读——写入只走工具——并以固定席位 `team-lead` 对外服务，因此第二个 session 打开的是同一张页面，而不是另起一个；把卡片交给队友由 `team` 负责，因为只有它能给对端发消息。卡片可以带上优先级、声明自己在等待哪几张卡片。步骤留在 owner 的 plan 和 `todo` 里，卡片就是 feature、它的 owner，以及解释它的历史。在 `bytefly.json` 里设置 `board.port` 可以固定看板端口，收藏的地址在重启后依然有效。 |
+| [`serve`](./docs/extensions/serve.md) | — | 每个 session 一个 loopback 服务。`/board`、`/browse` 和浏览器里的 plan review 都在它上面挂载路径前缀，而不是各自监听端口，因此一个 session 只有一个端口、一个 chip、一条关闭路径——而第二个 session（peer 会话、另一个 worktree、另一个 Pi）依然有自己的端口。`bytefly.json` 里的 `serve.port` 可以固定该端口，收藏的地址在重启后依然有效；共享 review 只为发起共享的那一个页面借用同一个网段上的一个地址。 |
+| [`board`](./docs/extensions/board.md) | `board`、`/board` | 每个仓库一块共享看板：一张卡片代表一个 feature，任何 session 都可以认领、移动、编辑、加注、完成、归档——已完成的卡片会离开看板进入 `archive/`，其注记与落地 commit 仍可读，长历史不再拖累每次读取——同一个看板在浏览器里以 **Board** 和 **Team** 两个 tab 实时显示。页面只读——写入只走工具——并以固定席位 `team-lead` 对外服务，因此第二个 session 打开的是同一张页面，而不是另起一个；把卡片交给队友由 `team` 负责，因为只有它能给对端发消息。卡片可以带上优先级、声明自己在等待哪几张卡片。步骤留在 owner 的 plan 和 `todo` 里，卡片就是 feature、它的 owner，以及解释它的历史。页面以 `/board` 挂在该 session 唯一的端口上，所以收藏时用 `serve.port`。 |
 | [`team`](./docs/extensions/team.md) | `team`、`/team` | 同一块看板上的 lead 轮次。`/team join <label>` 让一个 session 加入团队，lead 打开 `/board` 时则以 `team-lead` 自动加入；随后 `assign` 把一个 feature 交给运行中的 session，`offer` 交给谁有空谁接——广播而不写卡片，由第一个认领的人拿走——`reclaim` 把卡片收回 To do。结果会说明谁会因此被叫醒、谁会在下一轮才读到；`/team` 在终端里打印同一份轮次，不用开浏览器，也不启动任何进程。 |
 | [`context`](./docs/extensions/context.md) | `/context` | 显示上下文窗口的去向 —— 系统提示、工具定义、按角色拆分的对话、注入的笔记 —— 并从报告中触发压缩，给出压缩前后的数字。 |
 

package/docs/extensions/README.md

@@ -17,6 +17,7 @@ sections behind them.
 | `job` | Long-lived shell commands in the background, with logs and a wait | [`job.md`](./job.md) |
 | `watch` | Tailing a file or command and matching new lines | [`watch.md`](./watch.md) |
 | `session-bus` | Coordination between parallel Pi sessions on one repository | [`session-bus.md`](./session-bus.md) |
+| `serve` | The session's one loopback server: every page mounts a path prefix on it | [`serve.md`](./serve.md) |
 | `board` | One shared feature board per repository, written by the tools and shown by one page a lead serves | [`board.md`](./board.md) |
 | `team` | The lead's round: hand a card to a running session, take one back, or print it with `/team` | [`team.md`](./team.md) |
 | `context` | Where the context window went, and compacting from the report | [`context.md`](./context.md) |

package/docs/extensions/board.md

@@ -27,11 +27,11 @@ decision.
 |---|---|---|
 | A shared feature list for one repository | `board` action `list` | Every open card in lane order — `todo`, `doing`, `blocked` — or one card, or one lane; the `done` cards are left out with a count of how many, and `status: "done"` reads them |
 | The lead's rollup | `board` action `list` with `round: true` | Every owner with its live cards and, beside the count, what it has finished — an owner whose last card is done stays listed — then unassigned, unplanned, blocked, idle, and done |
-| Publish a feature | `board` action `add` | A `todo` card with path hints and a first note |
+| Publish a feature | `board` action `add` | A `todo` card with path hints and a first note (one line, at most 1000 characters) |
 | Take a feature | `board` action `claim` | The card is `doing` and owned by this session |
 | Hand it back | `board` action `release` | The card is `todo` again, with no owner |
 | Change lane | `board` action `move` | Wherever the owner moves it: `doing`, `blocked`, `done` |
-| Record what happened | `board` action `note` | A note appended to the card's history, attributed and stamped |
+| Record what happened | `board` action `note` | A note appended to the card's history, attributed and stamped — one line, at most 1000 characters |
 | Record the plan | `board` action `plan` | The plan file the card is executing, so "unplanned" work is visible |
 | Fix what a card says | `board` action `edit` | A new title, path hints, priority, or the cards it waits for — by its holder, or by anyone while nobody holds it |
 | Say how urgent it is | `board` action `add` or `edit` with `priority` | `high` sorts first inside its lane, and the card says so |
@@ -43,11 +43,11 @@ decision.
 | Set a finished card aside | `board` action `archive` | A `done` card's file moves into an `archive/` pile beside the board with its notes, plan, owner, and landed commit still readable, and the board stops reading it: the card named by `card`, or every finished card when none is named. It is a decision a person makes, never a threshold in the background, and nothing un-archives |
 | Delete a card | `board` action `drop` | The card and its notes are gone, and its id is spent: a record of the title, the lane, who ended it, and when stays in `ended/`, so a note or a handoff that names that id cannot come to mean a different feature. A `todo` or `done` card is anyone's to drop, an archived one included, one in flight only its holder's, and one that a card waits on cannot leave at all |
 | One page per repository | `/board` | Serves a loopback page as `team-lead` with a **Board** and a **Team** tab, following the store live; a page already served is opened instead |
-| Watch somebody else's page | `/board` on a session that is not serving | The same page, because there is one: every page is a read view, so a second session gets exactly what the first one sees instead of a writable rival. It joins the team under its own label, so a handoff can still reach it |
+| Watch somebody else's page | `/board` on a session that is not serving | The same page, because there is one: every page is a read view, so a second session gets exactly what the first one sees instead of a writable rival. It joins the team under its own name, so a handoff can still reach it |
 | Read a board at its real size | the `Done` fold, an empty lane's rail | `Done` starts folded at six cards or more, its count in the head, and a reader's toggle decides from then on. A lane holding no cards narrows to its head, word, and count, so the lanes carrying work keep the width |
 | Open a card | the card's title, or `Enter` on a focused one | The title is the only door, because it is the only one needed: it opens the dialog holding the card whole — its lane, its owner, its paths, what it waits for, its plan, and every note |
 | See the lead's round at a glance | `/board team`, or `/team` with no browser | A queue of cards that need a decision, each with the reason and its way out, then who is on the team and what they hold |
-| Join the team | `/board`, or any card you work | Opening the page joins this session to the team — as `team-lead` when it serves the page, under its own name when it opens one somebody else serves — and the first card a tool writes joins it too, so nothing has to be armed by hand. `/board status` says which team a `/board` in this session put you on |
+| Join the team | `/board`, or the first card you claim | Opening the page joins this session to the team — as `team-lead` when it serves the page, under its own `team-agent-…` name when it opens one somebody else serves — and so does the first card it claims, so nothing has to be armed by hand. Joining never renames Pi's session: the footer keeps the name you gave it. `/board status` reports the team this session is on, whichever door it used |
 | See who is around | `/board team` | The Teammates list: every session this repository's bus has recorded, plus every owner a card names, each stating `live`, `quiet`, `no record`, or `—` when no bus is loaded |
 
 ## Quickstart
@@ -69,9 +69,9 @@ lead: board list round: true
 
 | Command | Who | Effect |
 |---|---|---|
-| `/board` | lead | Serves the page as `team-lead`, or opens the one another session already serves — and opens it again when it is already up, so a closed tab is one command away. The line it prints names the address |
+| `/board` | lead | Serves the page as `team-lead`, or opens the one another session already serves — and opens it again when it is already up, so a closed tab is one command away. The line it prints names the repository and the address |
 | `/board team` | lead | The same, opened on the Team tab |
-| `/board status` | both | One line: the seat, the port, how many tabs are watching, the store, and the team the last `/board` joined — or the page being watched, and whether the note behind it still answers |
+| `/board status` | both | One line: the seat, the repository, the port, how many tabs are watching, the store's path, and the team the last `/board` joined — or the page being watched, and whether the note behind it still answers |
 | `/board stop` | lead | Stops the page this session serves; a watched page that has stopped answering is dropped instead, and a watched page that is alive is its owner's to stop |
 | `/team` | both | The round in the terminal: the rollup, the work a dead owner left behind, then who is live, who has gone quiet, and who is gone |
 
@@ -89,11 +89,19 @@ keeps its own note) instead of waiting for the next `/board` to trip over it.
 
 **Joining.** One thing, done for you: `/board` puts this session on the team — as
 `team-lead` when it serves the page, under its own name when it watches one — and so does
-the first card you work. The join is also the listening: mail is reported at that
-session's next turn, and no turn is raised, so being on the team never spends a turn. A
-session that has neither opened the board nor touched a card is not on it. `/board
-status` reports the join `/board` made itself: a session that joined by writing a card
-is on the team, and its status line does not say so.
+the first card it claims. A read, a new card, a note, a plan, or an edit enlists nobody: a
+teammate is a session that holds work. The join is also the listening: mail is reported at
+that session's next turn, and no turn is raised, so being on the team never spends a turn.
+A session that has neither opened the board nor claimed a card is not on it.
+
+**The two names.** A session's team name is the seat — `team-lead` — while it serves the
+page, and `team-agent-` plus the last six characters of its session id otherwise, so
+`billing-core` on this machine is `team-agent-9f21ac` to the team. The name is derived from
+the id and not from Pi's session name, which means a rename cannot strand a card, two
+sessions cannot settle on one name, and nothing here ever renames your session: `/team join
+<label>` is the one door that does. A card records that name as its owner, so the chip, the
+roster, and the bus record are one word — and `/board status` says it whichever door put
+this session on the team, including a claim made with no page open.
 
 The page still serves as a seat: `/board status` names `team-lead`, the toolbar chip says
 so, and a card a browser claimed **before** the page stopped writing still names
@@ -154,7 +162,7 @@ path the board does not serve.
 GET    /theme.js             the theme script — no token
 GET    /app.js               the client script — no token
 GET    /                     the document (?view=board|team), whose tab reads
-                             board · <store key> · <N> open
+                             board · <repo> · <N> open
 GET    /index.html           the same document, for a link that names it
 GET    /api/ping             whether the page answers, and nothing else: a session
                              deciding whether to attach reads this, not the snapshot
@@ -169,13 +177,18 @@ answering its browser would otherwise be declared dead and taken over.
 ## Layout
 
 One page, two tabs, one lifecycle. The kit shell keeps the toolbar and the footer
-pinned and makes the main pane the only scroll box; the page adds no second one.
+pinned and makes the main pane the only scroll box; the page adds no second one. The
+footer is one line about the board itself: the repository's name, the store's path, the
+count of cards, and the size they occupy — plus the files this build could not read —
+with the repository root's whole path on the hover title, which is what tells two
+clones of one repository apart. The tab carries the repository's name for the same
+reason: a store key is a hash, and no reader can say it out loud.
 
 | Band | What it holds |
 |---|---|
 | Toolbar | the mark, the seat the page is served as, as a chip, a live badge (`connecting…`, `live` or `live · 3m`, `reconnecting…`), then one group: the Board\|Team switch, done-of-total progress, a filter, the keys button, and the theme toggle |
 | Lanes | trays, not a bare list: one column per lane, sized by the work it holds — a lane with two cards is wider than one with a single card, and a lane showing nothing, because it holds no cards or because it is folded, narrows to a rail of dot, word, and count — so the lanes carrying work keep the width. Three or four across above 1180px, two at 1180px or narrower, one lane plus the lane switch at 860px or narrower — where it opens on the first lane that holds a card. Each head sticks while the pane scrolls, carries its count as a pill, and folds its cards away: `Done` starts folded at six cards or more, since finished work is history, and a reader's toggle decides from then on |
-| Cards | the id and a two-line title (the page's loudest text and its only door), an owner chip and an age, a muted priority chip when it is not `normal`, path chips, and one reason line in one voice — what a card waits for, a blocked card's recorded reason or else its last note (or `blocked, with nothing recorded`), `no plan recorded`, `planned`, `✓ done by <owner>` with the commit it landed as, and the last note of a card that is none of those — up to two lines at the Team tab's size, with the whole sentence as its tooltip, because the reason is the reason to act on the card. A card draws **no button**: claiming, moving, editing, and annotating are the tools' work, and a face that offered them would be offering a refusal. A hovered card lifts a pixel; a finished one recedes, title and owner chip muted |
+| Cards | the id and a two-line title (the page's loudest text and its only door), an owner chip and an age, a muted priority chip when it is not `normal`, path chips, and one reason line in one voice — what a card waits for, a blocked card's recorded reason or else its last note (or `blocked, with nothing recorded`), `no plan recorded`, `planned`, `✓ done by <owner>` with the commit it landed as, and the last note of a card that is none of those — up to two lines at the Team tab's size, with the whole sentence as its tooltip, because the reason is the reason to act on the card. A title and a path chip elide **inside** the card: a chip is one line by design, so a path or a label longer than the card is clipped rather than crossing into the lane beside it, and its whole value is the hover title. A card draws **no button**: claiming, moving, editing, and annotating are the tools' work, and a face that offered them would be offering a refusal. A hovered card lifts a pixel; a finished one recedes, title and owner chip muted |
 | Team | two panels and a strip. **Needs a decision** is one row per card — a card that is both idle and unplanned arrives once, keeping its strongest reason — laid out as two lines: the id, title and owner chip on the first, the reason on the second — a blocked card's recorded `blockedBy`, else its last note, and `offered 2h ago — nobody took it` for a card whose offer went unanswered — with the whole sentence as its tooltip, and its kind as a left edge (`--danger` blocked, `--warn` idle, `--dim` unplanned or waiting, the same `--dim` dashed for nobody's). The row is a reason to pick the card up in the terminal, and it draws no button: claiming and reclaiming are the tools' work. An unassigned card that waits on unfinished work is a row of its own kind, ranked just under a blocker. Above 1180px the queue stops at one screen's height and scrolls inside its panel, so the roster and the Done strip stay on the same page as its top. **Teammates** is one row per person — a state dot, the label, a `you` chip, a `not listening` chip on a live peer whose inbox watch is off, a mail badge, then `live · 3 held · 1 done · oldest 21m` (a quiet session reads `quiet for 2h`, because a word without an age is no reason to reclaim) — sorted you, live, quiet, no record, and an owner whose label nothing answers to keeps its row. Done is one quiet strip whose ids open their cards. Both panels honour the toolbar's filter, and their headings read `shown/total` the way a lane head does. Below 1180px the queue comes first and the roster follows |
 | Card dialog | the record of one card, in two named sections. The head carries the id, the title, and the lane as a dot and a word. **The card** is a ladder — one fact per row, labels sized to the longest of them so the values line up: owner, priority when it is not `normal`, updated, in lane, last edited, landed, waits on, waited on by, plan, paths. `in lane` is the lane the card is in and how long it has held it, read from the card's transitions rather than from `updatedAt`, which a note or an edit moves; a card whose history does not say omits the row. The plan and each path are one line that elides, with the whole value on the hover title; what it waits for reads `#2 (doing)`, the lanes that make the id a decision. Empty rows take their labels with them. **Notes · N** is the cargo at body size on a 68ch measure, each sentence with its attribution under it and a rule between notes, and `M earlier notes dropped` when the store capped them. The body is the only scroll, so the head and `Close` stay put. Nothing in it writes, every field is a set as `textContent`, and the title underneath every card is the way in. `j`/`k` walk to the next or previous card without closing it, and an `sr-only` live region announces `card 2 of 3: <title>` — a title that changes inside an open modal is not announced on its own |
 (feat(team): an offer leaves a record, so its age can be read)
@@ -292,17 +305,14 @@ it always meant: when the card was last touched, which is not when it last chang
 - **The page stops a minute after its last tab leaves, or two minutes after it starts
   with no tab at all.** Closing the tab to run a command and coming back is fine, and a
   teammate's watching tab counts as one. The second grace covers the page a browser never
-  opened — `openInBrowser` swallows a failure, and a port held by a page nobody saw is a
-  port held for the session. Either way `/board` starts it again, on the same port, and
-  prints the address it reopened.
-- **The port is found, or pinned.** With no setting the page prefers a free port in
-  4780–5779, falls back to whatever free port the OS gives it if that one is taken, and
-  remembers the answer for the session; `board.port` in `bytefly.json` pins it, so a
-  bookmarked URL survives a restart. A pinned port that is already taken fails the start —
-  `port 4780 is in use — change "port" in the bytefly.json board section, or stop what
-  answers on it` — because a quiet fallback would move the page out from under the
-  bookmark. A live note still wins: one repository has one page, so this session attaches to
-  the port that note names rather than serving a second one.
+  opened — `openInBrowser` swallows a failure, and a prefix held by a page nobody saw is a
+  prefix held for the session. Either way `/board` starts it again, on the session's port,
+  and prints the address it reopened.
+- **The prefix is `/board` on the session's one server.** The port belongs to `serve`, so
+  `/board`, `/browse`, and a browser plan review answer on one origin; `serve.port` in
+  `bytefly.json` pins that origin, so a bookmarked URL survives a restart. A live note still
+  wins: one repository has one page, so this session attaches to the page that note names
+  rather than serving a second one — and a session that attaches binds nothing at all.
 - **The note is believed only while it answers.** A page that crashed leaves its note
   behind; the next `/board` probes it, takes it over when nothing replies, and attaches to
   the page that won when two sessions start in the same instant. A clean exit — `/board
@@ -310,16 +320,22 @@ it always meant: when the card was last touched, which is not when it last chang
   is the one a crash left. A note it cannot read at
   all is named with its path — "another session is serving" is only said of a page that was
   seen answering.
+- **A page that cannot read the board says so once.** A snapshot is built on every tick, and
+  a read can fail under a running page — the board's directory removed, or replaced by
+  something that is not one. The frame is dropped rather than raised, the session is told
+  once, and the next tick tries again, so a board that comes back is followed again without
+  a second `/board`; a notice per tick would be a transcript nobody reads.
 
 ## Pi integration
 
-- **`session-bus`**: a card's owner is the bus label, so a card names a session a
+- **`session-bus`**: a card's owner is the session's team name, so a card names a session a
   peer can be addressed by. The board calls one thing on it — the join, through
   `lib/session-tool.ts`, because a command context cannot call a tool and the request
   therefore travels on `pi.events` — and reads its records otherwise, which is why the
-  page works with the bus disabled. A failed join is a clause on the `/board` line, not
-  a failed page. The seat is the name the page is served and reported under, and `/board
-  status` says which session is on the team through it.
+  page works with the bus disabled. The join asks for the name the board already writes
+  and never renames the session, so the footer stays the user's. A failed join is a clause
+  on the `/board` line, not a failed page. The seat is the name the page is served and
+  reported under, and `/board status` says which session is on the team through it.
 - **`plan`**: `board plan` records a plan file's path; the plan extension owns the
   file. The board stays available while planning, and only `list` works: the same tool
   writes, so its read-only hint cannot say that, and plan mode reads the action in the
@@ -330,9 +346,9 @@ it always meant: when the card was last touched, which is not when it last chang
   forces a todo update, while `add` or `claim` counts as work like any other write.
 - **`worktree`**: the store is keyed by the repository's common git directory, so
   every worktree shares one board.
-- **`bytefly`**: the page's port appears as a `board` status chip, and `doctor`
-  reports nothing new — the board needs no binary and no per-machine setup; its one
-  setting, `board.port`, is a `bytefly.json` edit.
+- **`serve`**: the page mounts `/board` on the session's one server, which draws the
+  single `◉ <port>` chip. **`bytefly`**: the bar shows that chip, and `doctor` reports
+  nothing new — the board needs no binary and no per-machine setup.
 
 ## Design notes
 
@@ -417,8 +433,7 @@ it always meant: when the card was last touched, which is not when it last chang
   seat, and the token; it is created exclusively, so two sessions starting at
   once cannot both serve, and the loser attaches to the winner. The alternative —
   a setting that names the lead — was rejected: the role moves, the seat's name does
-  not. The port is the one thing a file may pin: `board.port` states where the page
-  listens, never who serves it.
+  not. The port in the note is the session's, never a number this page chose.
 - **The page is a view because a browser is not an identity.** Every page write was made
   as the seat, so a page `assign` had to write down that nobody had been told, and the
   client's copy of the card rules drifted from `lib/board/rules.ts` — it offered a drop
@@ -464,7 +479,6 @@ it always meant: when the card was last touched, which is not when it last chang
 | File | Responsibility |
 |---|---|
 | `index.ts` | The factory: gate on `PI_DISABLED_EXTENSIONS`, build the runtime and the page, register both, close on shutdown |
-| `config.ts` | The board's one setting: the port its page is pinned to, clamped, from the `bytefly.json` `board` section |
 | `schema.ts` | The tool's parameters |
 | `types.ts` | The shapes the tool registers and reports — the actions and the fields each acts on, the card an action produced, the cards a list read, the rollup when it was asked for, and the card a refusal carries |
 | `tools.ts` | Action dispatch and the refusal shape |
@@ -472,13 +486,13 @@ it always meant: when the card was last touched, which is not when it last chang
 | `format.ts` | The model-facing text |
 | `rows.ts` | The transcript row grammar |
 | `result.ts` | The transcript block |
-| `page.ts` | The page's lifecycle: the port it remembers or is pinned to, the chip that names it, the three closes (`/board stop`, the idle grace, and shutdown — each taking the note with it), and the probe behind `/board status` |
-| `snapshot.ts` | The page's snapshot: the cards, the bus's records, and the store's size, handed to `buildView` |
+| `page.ts` | The page's lifecycle: the `/board` prefix it holds on the session's server, the three closes (`/board stop`, the idle grace, and shutdown — each taking the note with it), and the probe behind `/board status` |
+| `snapshot.ts` | The page's snapshot: the cards, the bus's records, the store's size and path, and the repository's own name, handed to `buildView` |
 | `commands.ts` | `/board`, its three words and their refusals, and the one line `/board status` prints |
 | `seat.ts` | The seat the page is served as: one name, and an id derived from it. The page cannot write, so it is a label now — but the id is still what a card claimed from an older page names |
-| `join.ts` | The board's side of the team: the one request that joins for the user, the label it lands on, and how the outcome reads on a `/board` line |
+| `join.ts` | The board's side of the team: when it asks (the page, or the first claimed card), the name it asks for, and how the outcome reads on a `/board` line |
 | `transport/router.ts` | The five reads — the document, the client script, the theme script, the snapshot, and the frame stream — with the token gate and the guards in front of them |
-| `transport/server.ts` | The loopback listener, the frame push, and the close |
+| `transport/server.ts` | The loopback listener, the frame push — one read of the board per frame, and a failed read reported rather than thrown — and the close |
 | `view/page.ts` | The document: an inert shell the client fills, with no form on it |
 | `view/styles.ts` | The page's `board-*` layout rules |
 | `view/render.ts` | The client's snapshot → DOM renderer: toolbar, lanes, cards, the dialog's contents |
@@ -499,9 +513,10 @@ The store, the rules, the rollup, and the snapshot are `lib/board/` — see
 record, the dependency graph, the note a page leaves, the rollup and its text, the card's
 transitions, the store a call opens and the identity it writes as, the files that store
 keeps, and the snapshot, and
-`extensions/board/{input,seat,tools,page,commands,config,extension,transport/router,view/pages,view/behaviour}`
+`extensions/board/{input,seat,tools,page,commands,extension,transport/router,view/pages,view/behaviour}`
 for the card body, the seat, every action, the page's lifecycle over a real socket (a page
-served, attached to, and taken over, and a write refused on the wire), the command, the
-`board.port` setting, the factory, the routes, the document and client bundle, and the
+served, attached to, and taken over, a board that stops being readable, and a write refused
+on the wire), the command, the
+factory, the routes, the document and client bundle, and the
 page driven in a browser — a card opened from its title, the filter, the fold, a live
 frame, and the dialog's ladder.

package/docs/extensions/bytefly.md

@@ -263,9 +263,8 @@ Two lines, each with a left and right zone:
 
 - **Line 1 — identity:** `pwd` and the session name on the left; on the right the
   alert, then the mode chips (`≡ plan`), then `⎇ branch · ⑂ worktree`, then the
-  ports (`⊞ 5043 · ◉ 4909`) while a page is being served. The board page and the
-  file browser each publish one status key, and the bar reads both as a single
-  segment, so they share a weight, a position, and a floor.
+  session's page port (`◉ 4780`) while anything is served on it. One server serves
+  every page of a session, so it is one number from one status key.
 - **Line 2 — resources:** the context gauge and usage meters on the left, the
   child-run roll-up (`↳ 3 · ¥0.12`, present only once a subagent has finished),
   and the model and thinking level on the right. The gauge is anchored at column
@@ -293,11 +292,10 @@ With no plan mode the mode slot is simply absent:
 ▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87%                               opus-4.5 · high
 ```
 
-While a page is served, its port joins the run beside the worktree — both pages as
-one cluster, in a fixed order, so the pair reads as a pair:
+While a page is served, the session's port joins the run beside the worktree:
 
 ```
-~/repo/my-pi-agent                                                          ⎇ main · ⊞ 5043 · ◉ 4909
+~/repo/my-pi-agent                                                                 ⎇ main · ◉ 4780
 ▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87%                               opus-4.5 · high
 ```
 
@@ -315,12 +313,12 @@ fits, rather than collapsing to a bare glyph:
 ▰▰▰▰▰▰▱▱▱▱ 62%  opus-4.5
 ```
 
-A port is dropped before the pages it names are: the cluster compacts to
-`⊞ ◉` once the digits no longer fit, so the narrowest bar that fits the location
-chips still says a page is up.
+The port drops the digits before the page they name: it compacts to `◉` once
+the number no longer fits, so the narrowest bar that fits the location chips still
+says a page is up.
 
 ```
-~/repo/my-pi-agent          ⎇ main · ⊞ ◉
+~/repo/my-pi-agent            ⎇ main · ◉
 ▰▰▰▰▰▰▱▱▱▱ 62% · ¥0.31   opus-4.5 · high
 ```
 
@@ -346,7 +344,7 @@ Each segment reads a theme role and carries its own drop order:
 | session | 1 left | muted, bracketed | after worktree |
 | branch | 1 right | muted (warning when detached) | last |
 | worktree | 1 right | success | first |
-| ports `⊞ 5043 · ◉ 4909` | 1 right | success glyphs + accent ports | first, in one step |
+| port `◉ 4780` | 1 right | success glyph + accent port | first |
 | context gauge + `%` | 2 left | muted ≤70 · warning 71–90 · error >90 | never |
 | `/window` | 2 left | dim | before cost |
 | cost | 2 left | muted | after tokens |
@@ -357,15 +355,12 @@ Each segment reads a theme role and carries its own drop order:
 | thinking level | 2 right | thinking token | before cost |
 
 The worktree status is read from the `worktree` status key, so the
-[worktree](./worktree.md) extension and the bar agree. The ports are the `board`
-and `browse` status keys, published by [board](./board.md) and
-[file-browse](./file-browse.md) while their pages are served. One segment reads
-both, in a fixed order (board, then browse), each a two-tone `<glyph> <port>`
-with a green glyph and an accent port. That is one fact — "a page is up on this
-port" — so it gets one weight and one floor: the pair compacts from
-`⊞ 5043 · ◉ 4909` to `⊞ 5043 ◉ 4909` to `⊞ ◉`, and it drops as a unit, where
-separate chips once let the board port outlive the browse one by four columns
-for no reason a reader could see.
+[worktree](./worktree.md) extension and the bar agree. The port is the `http`
+status key, published by [serve](./serve.md) while anything is mounted on the
+session's server — one number, because one socket serves every page a session
+opens. It is a two-tone `<glyph> <port>` with a green glyph and an accent port,
+and it compacts from `◉ 4780` to `◉` before it drops, so a bar too narrow for
+the number still says a page is up.
 
 The mode slot holds everything else an extension publishes: a plan chip, a
 job count, a rewind timeline, the `✆` bridge, and an alert's front position. A
@@ -1474,11 +1469,10 @@ rather than showing a wrong value.
   segment, so the percentage cannot move at all.
 - **Statuses are routed, not repeated.** The built-in footer renders every
   `setStatus` value on its own line, so the bar sorts them by meaning instead:
-  `worktree` and `browse` are location, so the `◉ <port>` chip sits behind `⎇`
-  branch and `⑂` worktree; the `board` key is location too, and the two ports
-  are one segment because they are one fact, so they share a weight and a floor;
-  a plan is a mode, so it leads the state line beside them; a failed job is an
-  alert, so it is its own segment ahead of both. The
+  `worktree` is location, so the `◉ <port>` chip sits behind `⎇`
+  branch and `⑂` worktree, and it is the session's one page port, so it keeps a
+  weight and a floor of its own; a plan is a mode, so it leads the state line
+  beside them; a failed job is an alert, so it is its own segment ahead of both. The
   [wechat](./wechat.md) extension publishes `✆ wechat` while its bridge runs,
   which is why the bar has to render `getExtensionStatuses()` at all.
 - **A state chip leads its zone, so the zone does not move under it.** The right
@@ -1661,6 +1655,8 @@ columns, gauge), so the look follows the active theme.
 | `footer/register.ts` | Installs/restores the footer and owns its session lifecycle. |
 | `footer/config.ts` | Bar tuning (`CONFIG`): thresholds, gauge, separators, icons, alert and plan status keys, labels. |
 | `footer/types.ts` | `StatusSnapshot`, `Segment`, `LineSpec`, `UsageRecord`, and footer/TUI shapes. |
+| `footer/budget.ts` | The session spend guardrail: whether the configured ceiling has been crossed and the one notice that says so — an alert, never a limit. |
+| `footer/delegation.ts` | The child-run ledger: the pricing inputs of the last delegated runs, versioned so the footer re-prices when a subagent finishes. |
 | `footer/collect/entries.ts` | Session entries → usage records, each resolved to the model in effect. |
 | `footer/collect/snapshot.ts` | Snapshot assembly; memoized pricing scan, context estimate, and session name per branch leaf. |
 | `footer/price/types.ts` | `Currency`, `ModelRates`, `PeakWindow`/`PeakSchedule`, `ByteflyConfig`. |
@@ -1675,6 +1671,7 @@ columns, gauge), so the look follows the active theme.
 | `footer/render/lines.ts` | Snapshot → two `LineSpec`s; status routing. |
 | `footer/render/layout.ts` | Width reduction and right-zone folding. |
 | `footer/render/footer.ts` | `StatusBar` component and footer factory. |
+| `footer/render/key.ts` | `snapshotKey`: the bar's repaint key, derived from the snapshot's own shape — sorted object keys, a map as sorted entries, a primitive by value — so a field added to `StatusSnapshot` is in the key the day it is added. |
 | `message/config.ts` | Nameplate tuning (`MESSAGE_CONFIG`): the label and the rule. |
 | `message/format.ts` | Pure `nameplate` and `styleUserMessage`: the two-row nameplate (label over a full-width rule) and its placement above the message. |
 | `message/register.ts` | Registers the Markdown transformer (the nameplate). |
@@ -1744,67 +1741,66 @@ columns, gauge), so the look follows the active theme.
 
 ## Testing
 
-`extensions/bytefly/` covers the install/restore/toggle lifecycle
-(`extension`), the header's rendering, width shedding, and live theme
-(`header/component`), its quiet-startup lifecycle (`header/register`),
-the formatters (`footer/render/format`), the status-chip transforms
-(`footer/render/status`), entry
-reduction and model inheritance (`footer/collect/entries`), snapshot assembly
-and its memoization (`footer/collect/snapshot`), rate matching
-(`footer/price/rates`), window parsing
-and peak evaluation in two zones (`footer/price/schedule`), the pricing formula,
-the off-peak multiplier, the built-in DeepSeek table with no config file, and the
-fallback (`footer/price/price`), the config schema, its clamping, the built-in
-defaults and their replacement, and the two file layers
-(`footer/price/config`), zone/priority
-assignment
-(`footer/render/lines`), the reduction, separator collapse, and right-zone
-folding across a width sweep from 6 to 120 plus wide characters
-(`footer/render/layout`), exact
-golden output at fixed widths (`footer/render/render`), and the install/skip/
-restore/toggle lifecycle plus a config-driven price (`extension`). The turn
-separator is covered by its pure formatting (`separator/format`, including the
-receipt's width ladder), its register/append/render/disable lifecycle
-(`separator/register`), and the run stats it records. The picker helpers are
-covered by the pure helpers (`picker/resources`), the toggle
-transforms (`picker/toggle`), discovery with an injected factory
-(`picker/discovery`), and the runtime state machine (`picker/runtime`). The
-unified screen is covered by its pure model merge (`panel/join`), its two
-filters and their chips (`panel/filter`), its text formatter (`panel/format`),
-the settings catalogue and its cycling (`panel/settings`), the scope-aware
-settings runtime (`panel/settings-runtime`, including a nested leaf write that
-keeps its siblings), the skill metadata join and loader (`panel/skills`, on real
-`SKILL.md` files), the key table whose hints and help it holds to one source
-(`panel/keys`), the frame and the one height all three sections agree on
-(`panel/layout`), the row grammar and the focused-row block beside and under the
-list (`panel/views`), the two-pane split and its `… N more lines` clip
-(`panel/panes`), the editing key map (`tui/editing`), the component's frames,
-keys, sections, settings, and probe lifecycle (`panel/component`,
-`panel/component-input`, `panel/component-sections`,
-`panel/component-settings`, `panel/component-probing`), and the command through
-the bytefly factory (`panel/commands`) — eighteen suites in all.
-The doctor surface is covered by its pure report
-formatting (`doctor/format`), its config loader (`doctor/config`), and
-registration, the proactive notice, the session cache, and `run_doctor`
-through the factory (`doctor/register`). The notify capability is covered by its section loader
-(`notify/config`), the pure text builders (`notify/format`), method selection and
-delivery over recording seams (`notify/dispatch`), and its four triggers,
-reload, and shutdown through `registerNotify` (`notify/register`). The update
-surface is covered by the version-ordering table (`update/version`), Pi's package
-list and the injected registry read (`update/check`), the host shim and its
-idempotent restore (`update/suppress`), the per-load store (`update/state`), the
-marker, multi-package notice, release URL, and recheck wording (`update/format`),
-the project-scoped snapshot and its window (`update/cache`), and its lifecycle —
-a fresh matching entry reused without a package-manager call, a stale one re-read
-and rewritten, silent on failure or an empty list, cache-only offline, skipped
-outside `tui`, an explicit `recheck()` that ignores the window, and immunity to a
-reply that lands after shutdown (`update/register`).
-The user-message nameplate is covered by its pure transform
-(`message/format`, including a render through pi-tui's real `Markdown`) and its
-registration (`message/register`), plus the factory check in `extension`.
-The notice surface is covered by its pure rows (`notice/component`), its
-renderer registration (`notice/register`), and the shared contract
-(`lib/notice`), plus the factory check in `extension`.
-The tool-block frame is covered by its pure `toolBlockLines` (`block/component`)
-and its generic fallback (`block/fallback`), plus the resolver's shell override,
-self-shell carve-out, and fallback framing (`block/register`).
+Every suite sits beside the code it covers, so a slash-prefixed stem below
+resolves to `extensions/bytefly/<stem>.test.ts`.
+
+`extension` covers the registration, the interactive surfaces, and the command
+wiring through the factory.
+
+`chrome` covers the chrome that frames a session: the config and its pad store;
+the header's frames, width shedding, identity ladder, update marker, live theme,
+quiet-startup lifecycle, and terminal-height shapes; the transcript notice's rows
+and registration; the turn separator's formatting (including the receipt's width
+ladder), component, and register/append/render/disable lifecycle with the run
+stats it records; and the user-message nameplate's transform — through pi-tui's
+real `Markdown` — and its registration.
+
+`footer/footer` covers the bar end to end: the price config, its schema, clamping,
+and defaults; rate matching, window parsing and peak evaluation in two zones, the
+pricing formula with its off-peak multiplier, the built-in DeepSeek table and the
+fallback, the usage records, and the delegation ledger; the snapshot reader and its
+memo, the unpriced notice, and the budget; the formatters, the status-chip
+transforms, the segment builders, line composition, and the repaint key that
+spares an unchanged frame a rebuild; the reduction, separator collapse, and
+right-zone folding across a width sweep from 6 to 120 plus wide characters; and the
+component with its install/skip/restore/toggle lifecycle and a config-driven price.
+
+`block/block` covers the tool-block frame: `toolBlockLines`, the call-headline
+rewrites, `ToolBlock`'s memo, the generic and call fallbacks, and the resolver's
+shell override and self-shell carve-out.
+
+`picker/picker` covers discovery with an injected factory, the resolver and its
+entries, the pattern helpers, and the runtime's toggling, scope, and project
+override across the four list operations.
+
+`panel/…` covers the control centre, one suite per capability: `panel/model` (the
+two panes' merged model and the text formatter), `panel/filter` and its chips, the settings
+catalogue and its cycling (`panel/settings`), the scope-aware runtime
+(`panel/settings-runtime`, including a nested leaf write that keeps its siblings),
+the skill metadata join and loader (`panel/skills`, on real `SKILL.md` files), the
+key table whose hints and help it holds to one source (`panel/keys`), the frame and
+the one height all three sections agree on (`panel/layout`), the row grammar and the
+focused-row block beside and under the list (`panel/views`), the two-pane split and
+its `… N more lines` clip (`panel/panes`), the editing key map (`panel/editing`),
+the update section's view (`panel/update`), the discovery probe (`panel/probe`), the
+component's frames, keys, sections, settings, and probe lifecycle
+(`panel/component`, `panel/component-input`, `panel/component-sections`,
+`panel/component-settings`, `panel/component-probing`), and the command through the
+bytefly factory (`panel/commands`) — eighteen suites in all.
+
+`doctor/doctor` covers the report counts and text, the config loader, the notify
+seam, the published search provider, the proactive probe, the session state,
+`run_doctor`, and the tool wiring.
+
+`notify/notify` covers its config loader, method selection, delivery over recording
+seams, the text builders, and its four triggers plus the handle.
+
+`update/update` covers the cache path and key, the cache read and write with its
+window, the check and the injected registry read, the version ordering, the
+formatters and the release notice, the prototype suppression with its idempotent
+restore, the per-load state, the lifecycle — a fresh matching entry reused without
+a package-manager call, a stale one re-read and rewritten, silent on failure or an
+empty list, cache-only offline, skipped outside `tui`, a `recheck()` that ignores
+the window, and a reply that lands after shutdown — and the `update` action.
+
+`working/working` covers the elapsed format, the counter, and the timer registration.