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

package/docs/extensions/file-browse.md

@@ -18,13 +18,13 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 |---|---|---|---|
 | One-command browsing | `/browse` | The server starts at the effective working directory, prints its URL, and opens the browser. | Shipped |
 | Read-only serving | `/browse` | Nothing is edited or written, and the server binds `127.0.0.1` only. | Shipped |
-| Two-pane page | `/`, `/browse[/<rel>]` | A collapsible tree beside the current folder's listing, with the tree, filter, and quick-open trigger pinned in their own pane. | Shipped |
+| Two-pane page | `/files/`, `/files/browse[/<rel>]` | A collapsible tree beside the current folder's listing, with the tree, filter, and quick-open trigger pinned in their own pane. | Shipped |
 | File previews | `/view/<rel>` | Text, rendered Markdown, image thumbnails, and download cards for binary or over-size files, each with a per-language icon. | Shipped |
-| Quick open | `/`, `Ctrl/Cmd+K`, `/api/files` | A fuzzy path finder over the tree opens a file without walking the tree. | Shipped |
+| Quick open | `/files/`, `Ctrl/Cmd+K`, `/files/api/files` | A fuzzy path finder over the tree opens a file without walking the tree. | Shipped |
 | Git diff view | `/diff`, `/diff/<rel>` | A change overview and one file's unified diff, scoped to `head`, `staged`, or `worktree`. | Shipped |
 | Live status | `/events`, the `◉ live` chip | An open page keeps its branch, change markers, and footer up to date without a reload. | Shipped |
 | Reload hint | `/api/dir-rev`, `⟳ reload` | A page whose folder gained or lost a file offers a reload control instead of changing its rows. | Shipped |
-| Terminal session chip | `browse` status key | The terminal footer shows `◉ <port>` while the page is served, so the session names its live server. | Shipped |
+| The session's page port | `serve`'s `◉ <port>` chip | The footer names the one port every page of the session answers on, this one included. | Shipped |
 | Listing controls | the `Name`, `Size`, and `Modified` headers | The current folder sorts by name, size, or modified time, directories first, and the choice is remembered per browser. | Shipped |
 | Keyboard navigation | the tree's keymap, `?` | The tree is one tab stop with arrow, fold, and open keys; a shortcut sheet lists the page's own keys. | Shipped |
 | Diff hunk navigation | `n`/`p` in `/diff` | Jump between changed hunks without scrolling the whole file. | Shipped |
@@ -35,7 +35,7 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 | Markdown preview | `/view/<rel>`, `/view/<rel>?raw=1` | A README renders as headings, lists, tables, code, and links, with a one-click raw view. | Shipped |
 | Copy and wrap | the page toolbar, `y`, `u` | Copy a file's path or contents or a `path:12-30` line reference, and toggle line wrapping for text and raw views. | Shipped |
 | Theme toggle | the header button, `/theme.js` | Dark and light palettes, following the system until an explicit choice is remembered per browser. | Shipped |
-| Idle stop and port reuse | `/browse stop`, the session port | The server stops when idle and reuses its port for the next session instead of leaking listeners. | Shipped |
+| Idle stop and prefix reuse | `/browse stop`, the idle grace | The page gives its prefix back when nobody is reading it, so a closed tab never holds the session's server. | Shipped |
 
 ## Quickstart
 
@@ -66,33 +66,32 @@ selects the root.
 
 - The root is the effective cwd, so an active `worktree` session serves the
   worktree. `<path>` must resolve inside it.
-- The port is fixed for the session: the first `/browse` picks a random port
-  in `4780`–`5779` and every later `/browse` in that session reuses it, so the
-  URL stays stable across roots and restarts. Set `"port"` to pin an explicit
-  port; a busy port is reported, not silently changed.
+- The port is the session's: `serve` picks one in `4780`–`5779` (and `serve.port` pins
+  it), so the origin stays stable across roots and restarts. A busy pinned port is
+  reported, not silently changed.
 - Starting while already running with the same root reprints the URL without
-  restarting; a different root (or a changed pinned port) restarts the server.
+  restarting; a different root restarts the page.
 - The server is closed when its last page has been gone for ten seconds, so
   closing the browser window ends the session's browse server and `/browse`
-  starts it again on the same port. A reload or a new tab inside that grace keeps
+  starts it again on the session's port. A reload or a new tab inside that grace keeps
   it. `session_shutdown` closes it too, and `/browse stop` closes it at once.
 
 ## Routes
 
 | Route | Result |
 |---|---|
-| `/`, `/browse[/<rel>]` | tree + directory listing |
-| `/view/<rel>` | tree + file page (text, Markdown, image, binary, or over-size) |
-| `/view/<rel>?raw=1` | raw Markdown/text source instead of the rendered view |
-| `/raw/<rel>` | raw bytes, streamed; downloads and image sources |
-| `/diff[?mode=head\|staged\|worktree]` | changed-file overview with `--stat` |
-| `/diff/<rel>[?mode=…]` | one file's unified diff |
-| `/api/tree?path=<rel>` | JSON children for lazy tree expansion |
-| `/api/files?q=<query>` | JSON fuzzy path matches for the quick-open palette |
-| `/api/dir-rev?path=<rel>` | JSON listing revision for the reload check |
-| `/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 |
+| `/files/`, `/files/browse[/<rel>]` | tree + directory listing |
+| `/files/view/<rel>` | tree + file page (text, Markdown, image, binary, or over-size) |
+| `/files/view/<rel>?raw=1` | raw Markdown/text source instead of the rendered view |
+| `/files/raw/<rel>` | raw bytes, streamed; downloads and image sources |
+| `/files/diff[?mode=head\|staged\|worktree]` | changed-file overview with `--stat` |
+| `/files/diff/<rel>[?mode=…]` | one file's unified diff |
+| `/files/api/tree?path=<rel>` | JSON children for lazy tree expansion |
+| `/files/api/files?q=<query>` | JSON fuzzy path matches for the quick-open palette |
+| `/files/api/dir-rev?path=<rel>` | JSON listing revision for the reload check |
+| `/files/events` | Server-Sent Events stream of `status` frames for the open page |
+| `/files/app.js` | the first-party client script |
+| `/files/theme.js` | the pre-paint theme bootstrap |
 
 ## Configuration
 
@@ -102,7 +101,6 @@ global document then project document, project wins — are in
 
 | Key | Default | Meaning |
 |---|---|---|
-| `port` | `0` | `0` picks one random port fixed for the session; a positive value pins it. |
 | `autoOpen` | `true` | Open the browser on start; `false` for headless. |
 | `maxFileBytes` | `1048576` | Larger files show a download card only. |
 | `maxThumbBytes` | `5242880` | Larger images get an icon, not a thumbnail. |
@@ -342,12 +340,11 @@ old and new sides for `lib/highlight`.
 
 ## Live status
 
-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, 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 answers at `/files` on the session's one server, so the footer's one
+`◉ <port>` chip is the session's, not this page's: [`serve`](./serve.md) publishes it
+while anything is mounted, and [`bytefly`](./bytefly.md) routes it to line 1's right
+zone, after `⎇ branch` and `⑂ worktree`. It is cleared when the session's server closes,
+so a session with no page open shows nothing at all.
 
 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
@@ -452,22 +449,20 @@ stops at the first difference because the control, not the checker, is the fix.
 | Integration point | How |
 |---|---|
 | Command | `/browse` registers a single command from the factory; no tools are exposed. |
-| State | The running server, its root, and the session port live in a module-local closure; nothing is persisted and no session entries are written. |
+| State | The running mount, its root, and the session id live in a module-local closure; nothing is persisted and no session entries are written. The port is `serve`'s, not this extension's. |
 | Lifecycle | The factory opens no socket; the server is created on `/browse` and closed idempotently by `/browse stop`, by `session_shutdown`, and once its last page has been gone for the idle grace, which also ends every attached status stream. |
 
 ## Design notes
 
 - **Lifecycle.** `/browse` resolves `resolveEffectiveCwd(ctx.cwd)`, loads config,
-  selects the port, parses args, and `await createFileServer(...)`: `realpath`
-  the root, bind `127.0.0.1`, await `listening`, return `{ url, port, root,
-  close }`. The port is chosen once for the session: a pinned config `port`
-  wins, otherwise a random port is drawn and cached after the first successful
-  bind, so later starts reuse it (a conflict is reported and the next `/browse`
-  rolls another). `/browse stop` and `session_shutdown` await the idempotent
-  `close()`; `session_shutdown` also clears the cached port. The page is the
-  server's only reader, so the channel reports the last page's departure after
-  `IDLE_STOP_MS` and the command closes the server and clears the chip — the
-  cached port survives, so the next `/browse` binds the same one.
+  parses args, and mounts the page through `requestMount`: `realpath` the root, claim
+  `/files` on the session's server, return `{ url, port, root, close }`. The
+  port belongs to `serve` — `serve.port` pins the session's origin — so nothing here
+  picks or retries one. `/browse stop` and `session_shutdown` await the idempotent
+  `close()`, which gives the prefix back. The page is the mount's only reader, so the
+  channel reports the last page's departure after `IDLE_STOP_MS` and the command
+  releases the prefix — and the session's port is `serve`'s, remembered per session,
+  so the next `/browse` answers on the same origin.
 - **Pure routing.** `handleRequest(context, method, rawUrl, headers)` validates
   method and `Host`, parses the URL, matches a route, and runs every path
   through `paths.ts`. It returns a plain `ServeResponse`, so routing is tested
@@ -529,7 +524,7 @@ stops at the first difference because the control, not the checker, is the fix.
 | `view/diff-html.ts` | The unified-diff body: the gutter, the sign, the hunk sections, and per-hunk highlighting |
 | `transport/router.ts` | Pure request handler: routes, the `/raw` sandbox policy, and the error page |
 | `transport/server.ts` | This extension's routes over `lib/http`'s loopback server: the request count, the stream cap, and the idle policy |
-| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `plan`: one server entry (`serveLoopback`), page/script/JSON/event-stream headers, `ServeResponse`, the request-envelope helpers, the event-stream sink and its idle grace |
+| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `plan`: one server entry (`serveHttp`) and the mount contract a page claims a prefix with (`requestMount`), page/script/JSON/event-stream headers, `ServeResponse`, the request-envelope helpers, the event-stream sink and its idle grace |
 | [`../../lib/browser.ts`](../../lib/browser.ts) | Cross-platform browser opener (shared with `plan`) |
 
 ## Testing

package/docs/extensions/plan.md

@@ -41,6 +41,8 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 | 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 |
 | Changed sections | the `exit_plan_mode` review screen, the `/plan review` outline | After a refinement, only the sections that changed are marked. | Shipped |
+| Block-level change marks | the `/plan review` page's **Changed** view | After a refinement, each block that is new or edited is marked — an inserted step marks itself and leaves the rest of its section alone — and a section that lost blocks says how much shorter it became. **All** / **Changed** / **Comments** switch what the page shows, `v` cycles them, `n`/`N` walk the blocks that carry a comment, and a printed review is always the whole plan. | Unreleased |
+| Settled comments | the page's `Resolve` / `Reopen` on a note you wrote | The note keeps its place, its quote and its history and is written `> [!REVIEW resolved]`, where a later review and the model read it as closed; the panel counts `2 open · 1 resolved`, and every card names who wrote it. | Unreleased |
 | Section navigation | the review screen, `n`/`p` | The screen names the section you are in and jumps between headings. | Shipped |
 | Remote review | `exit_plan_mode` on a WeChat turn | The plan file is sent, then one compact prompt to approve, keep planning, or exit. | Shipped |
 
@@ -562,6 +564,12 @@ reveals a **+ Comment** action on hover; select
 text first to quote it. **Save feedback** writes the comments into the plan
 file and returns them to the model.
 
+- **A comment can be settled.** **Resolve** (on your own note) keeps it — its place, its
+  quote, its history — and marks it `> [!REVIEW resolved]` in the file, where a later review
+  and the model both read it as closed; **Reopen** puts it back. The panel counts
+  `2 open · 1 resolved`. A note you wrote is labelled **You** on your page and **The owner**
+  on somebody else's, a reviewer's is `@name`, and one sentence beside the facts says what
+  **Approve & run** and **Save feedback** each do.
 - **Shared theme.** The page uses the same Bytefly tokens, base rules, and
   syntax-token colours as `file-browse` (`lib/web/`), follows the system light/dark
   preference until the header toggle sets an explicit choice, and remembers that
@@ -654,14 +662,15 @@ file and returns them to the model.
   save that carries no comments asks for nothing, so the review screen comes back
   instead. `/plan review` sends them as a user message (a plan-mode revision or a
   plain update, depending on the mode).
-- **Loopback first, tokenized.** The server binds `127.0.0.1`, carries a random
-  per-session token in the URL, rejects a `Host` header it was not bound on,
-  refuses a cross-origin POST, serves only `GET`, `HEAD`, and `POST`, and caps the
-  request body. Sharing adds a second listener (below); it never widens the first. A save or cancel
-  resolves the session only after its HTTP response is delivered, so the browser
-  never sees a false "Failed to fetch". The last bound port is remembered per
-  plan, so reviewing the same plan again reuses the origin (and the browser's
-  saved theme with it). It is closed on the owner's save or cancel, on the owner's
+- **Loopback first, tokenized.** The review mounts `/plan/<id>` on the session's one
+  server, which binds `127.0.0.1`; the URL carries a random per-session token, a `Host`
+  header the server was not bound on is rejected, a cross-origin POST is refused, only
+  `GET`, `HEAD`, and `POST` are served, and the request body is capped. Sharing asks that
+  mount for one LAN listener (below); it never widens the loopback socket. A save or
+  cancel resolves the session only after its HTTP response is delivered, so the browser
+  never sees a false "Failed to fetch". The prefix is the review's, on the session's one
+  origin, so the browser's saved theme survives a review. It is closed on the owner's
+  save or cancel, on the owner's
   page going away, or on `session_shutdown`; a reload reconnects inside that grace,
   so refreshing or reloading a conflicted page does not end the review. A
   reviewer's tab opening or closing is not the review's lifetime.
@@ -766,6 +775,10 @@ both.
   refuses a file it did not render (`409`). It is a poll rather than a file
   watcher, so a change on a filesystem that reports nothing at all is still seen
   at the next request, because every page read re-compares the file.
+- **A settled note is a flag in the marker.** `> [!REVIEW resolved]` (and
+  `moved resolved`) is read as open when absent; a build from before this one does not know
+  the flag and shows the marker line as body text, so a file reviewed on both sides of the
+  upgrade reads differently there.
 - A shared review holds at most eight links. Each is a live bearer credential, so
   a ninth is refused with the cap named rather than minted.
 
@@ -946,14 +959,16 @@ both.
 | `plan-index.ts` | `/plan list`: the notice text and the docked index screen (store size and oldest plan, title, step progress, age, focused path; Enter reviews). |
 | `blocks.ts` | Source-line block model (fence-aware headings, paragraphs, list items, code, quotes, tables, rules, blanks), and `contentBlockAt`: the block with content a comment beside blank space belongs to. |
 | `feedback.ts` | Comment codec: authored markers, `stripFeedback`, `readFeedback`/`parseFeedback` (body, blocks, and comments out of one parse), `formatFeedback` (writer-scoped), `displayFeedback`, `carryFeedback`, `feedbackSummary`, and payload validation. |
-| `web.ts` | `createPlanWebReview`: the review session (per-token roles, the change stream, the plan-file poll, the body cap, settle-after-flush, abort) over `lib/http`'s one loopback server. |
+| `web.ts` | `createPlanWebReview`: the review session (per-token roles, the change stream, the plan-file poll, the body cap, settle-after-flush, abort) over `lib/http`'s one loopback server, and the router wiring — the island is `web-payload.ts` and the writes are `web-write.ts`. |
 | `web-tokens.ts` | The token table: the role each token names, the collision rule that keeps two roles off one token, and the names the other live links have bound. |
 | `web-streams.ts` | The event streams: who is listening, what a frame is addressed to, and the closed-tab grace that ends the review when the owner's page goes away. |
 | `web-router.ts` | Pure request handler: token role, `Host` allowlist, origin, and method checks through one POST-and-role guard, then the page, comment, owner-save, approve, cancel, and the four share routes. |
-| `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-page.ts` | The review page shell (header, reading progress, review facts, section outline, shortcut sheet, approve confirmation, share and name dialogs) and inline CSS. |
+| `web-payload.ts` | The page's data island: `ReviewPageData` and `reviewPageData`, which builds every fact the browser renders — the blocks, the stored comments, the outline and its change marks, the step progress, the highlighted code, the caps, and who is asking — from one read of the plan, with no server or socket in sight. |
+| `web-write.ts` | The review's two write paths over the plan store: `saveOwnerAnnotations` (the owner's save, which returns the plan it wrote) and `postReviewerAnnotations` (a reviewer's post, signed and scoped to its link), sharing one 404/409 check so a comment can never land beside text nobody read. |
 | `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-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-keys.ts` | The client's keyboard as typed source (`WEB_KEYS_JS`), and the one table the page's keys come from: `webKeys()` gives each binding its keys, the shortcut sheet's sentence, the sidebar hint's words and whether the page offers it — a function rather than a constant, because the bundle carries a body and `String()` of a table would drop the closures — read by `handleKey` (Esc peels the composer before closing, a field and the sheet own their keys, `s` is the write the page offers) and by the sheet and hint line the page renders; plus `rememberSelection`, which keeps the text a reader selected as the next comment's quote, and the `keyRows`/`surfaceOf` the handler and the page's own sheet both read, spliced with them for the same reason. |
 | `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`. |
@@ -995,9 +1010,11 @@ Twelve co-located suites, declared in `test/suite-manifest.ts`:
   `todo`, the session goal, and the call/result renderings.
 - `review-prompt.test.ts` — the compact remote prompt and its reply parser
   against one action table.
-- `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-*.test.ts` — the browser review, one capability per suite: the comment
+  codec and the router (`web-router`), the page roles and its shell (`web-page`),
+  the client script's rules (`web-client`, `web-outline`, `web-composer`,
+  `web-settlement`), the stream and the plan-file poll (`web-stream`), the
+  loopback session (`web-session`), and the share rules (`web-shared-review`).
 - `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

package/docs/extensions/serve.md

@@ -0,0 +1,129 @@
+# serve — the session's one loopback server
+
+## Capabilities
+
+| Capability | How | What you get |
+|---|---|---|
+| One port for every page of a session | automatic: the first page that opens binds it | the file browser at `/files/`, the board at `/board/`, and a review at `/plan/<id>/` answer on one origin, so a bookmark, a firewall rule, and a port to remember are one thing |
+| One chip for that port | `◉ <port>` in the status bar | the session's port while anything is served on it, and nothing when no page is open |
+| A port that survives a restart | `serve.port` in `bytefly.json` | the same address after `/resume`, so a saved URL still opens the page it names |
+| A second session on its own port | automatic: servers are keyed by Pi session | a WeChat peer conversation never answers on this session's port |
+| One page reachable on the LAN, on request | the asking page calls `mount.share()` | a teammate's link names exactly one address, and only that page answers there |
+
+## Quickstart
+
+There is nothing to run: `serve` is infrastructure, and the pages that use it are
+`/board`, `/browse`, and `/plan review`.
+
+```bash
+/board          # http://127.0.0.1:4780/board/?token=…
+/browse         # http://127.0.0.1:4780/files/
+/plan review    # http://127.0.0.1:4780/plan/3f9c21aa/?token=…
+```
+
+All three answer on `:4780`; the footer shows `◉ 4780` while any of them is open
+and drops the chip when the last one closes.
+
+## Routes
+
+The server holds prefixes, not pages. Each one is claimed by the extension that
+serves it, and a request reaches that extension with its prefix stripped:
+
+| Prefix | Served by | Note |
+|---|---|---|
+| `/files/` | `file-browse` | the file browser: its tree, its file pages, its own script, and the links it rewrites out of Markdown, all built from this prefix; `/files/browse/<path>` is one directory |
+| `/board/` | `board` | the read-only board page, with its token in the query |
+| `/plan/<id>/` | `plan` | one review; the id is the review's, so two reviews never share a namespace |
+
+Anything else is a `404` with a plain-text body, and a prefix named without its
+trailing slash (`/board`) is redirected to the slashed form, because a page's own
+links are relative to its directory. A prefix another page already holds is
+refused by name rather than served twice.
+
+## Behaviour by mode
+
+The server runs in every mode, but the chip needs a UI: RPC and JSON sessions serve
+their pages and skip it. Nothing here reads or writes the transcript.
+
+## Configuration
+
+The `serve` section of the shared `bytefly.json` (global, then project, project wins:
+
+| Key | Default | What it does |
+|---|---|---|
+| `port` | `0` | `0` takes one free port in `4780`–`5779` for the session and remembers it; a positive value pins the session's server so a bookmarked address survives a restart |
+
+The pin belongs to the first session in a process that binds: a second session — a
+WeChat peer conversation loads every extension except the bridge itself — takes an
+OS-chosen port instead of failing on a port the host already holds. A second
+*process* that finds the pinned port taken is told so rather than moved silently off
+the address a bookmark names.
+
+## Security
+
+The server binds `127.0.0.1`. The unit of exposure is the mount: a prefix answers
+only what its page routes, and each page keeps its own `Host` allowlist, its own
+token, and its own method list in `lib/http`.
+
+A shared review is the one exception, and it is the reviewing page's own: it asks
+for a listener on a single LAN address, and that listener carries only the prefixes
+that asked for it. `file-browse` and `board` are never reachable that way, and a page
+that stops sharing leaves the listener at once — the socket closes with the last page
+that was still sharing it.
+
+## Limitations
+
+- A page needs `serve` loaded. Without it every page refuses with a sentence naming
+  the extension, instead of binding a rival socket.
+- One pin is one port for the whole session: two repositories running pages on this
+  machine at once need a project-level `serve.port` each, or neither pinned.
+- The port moves to an OS-chosen one when the pinned port is taken, so an old
+  bookmark keeps failing until the setting or the other process is dealt with.
+
+## Non-goals
+
+- It serves no page of its own, and registers no tool and no command.
+- It is not a general web server: loopback, a page's own routes, one optional LAN
+  address per shared page, and nothing else.
+- It does not proxy or rewrite; a page's paths are its own, under its prefix.
+
+## Pi integration
+
+- Registers `pi.events.on(HTTP_MOUNT_CHANNEL, …)` in the factory — registration only.
+  Binding happens on the first mount, never at load and never on `session_start`.
+- `session_start` records the session's working directory and its context, so the
+  pin is read from that session's config and the chip is drawn in its UI.
+- `session_shutdown` closes the session's socket, its LAN listener, and its chip.
+  It is idempotent.
+
+## Design notes
+
+A session has one port, so the socket cannot belong to a page. The page asks for a
+prefix over `pi.events` — the mechanism the repository already uses for a
+cross-extension request that must be answered — and `lib/http` owns the socket, the
+dispatch, the body cap per mount, and the idle grace per mount.
+
+The handshake is *claimed*, not awaited: `server.listen` cannot answer synchronously,
+so the owner responds with the pending bind and only a request nobody claimed is
+refused. Without that distinction a bind that is still starting looks exactly like a
+session with no server.
+
+## Files
+
+| Path | Responsibility |
+|---|---|
+| [`../../extensions/serve/index.ts`](../../extensions/serve/index.ts) | The Pi wiring: the bus listener, the per-session directory and context, the port chip, and the shutdown |
+| [`../../extensions/serve/registry.ts`](../../extensions/serve/registry.ts) | The session's servers: binding on first mount, the pin's owner, the remembered port, prefix refusals, the LAN listener a shared page borrows, and closing with the last mount |
+| [`../../extensions/serve/config.ts`](../../extensions/serve/config.ts) | The `serve` section: `port`, its clamp, and the two documents it resolves over |
+
+## Testing
+
+`config.test.ts`, `registry.test.ts`, and `extension.test.ts`, declared under
+`serve` in `test/suite-manifest.ts`.
+
+The registry cases bind real sockets on `127.0.0.1`: one port for two pages of a
+session, a second session on its own port, a refused duplicate prefix, the socket
+closing with its last page and reopening where it was, the pin belonging to the
+first session that binds, and a LAN share reaching one page only. The extension
+cases drive the shipped bus path through `requestMount`, including the chip and the
+shutdown.

package/docs/extensions/session-bus.md

@@ -16,7 +16,7 @@ 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>]`, `/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 |
+| Membership | `session join [label]`, `/team join [<label>]`, `/board`, the first `board` claim, 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 `team-agent-<id>` name; the first `board` claim joins under that same name, and renames nothing; `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 |

package/docs/extensions/team.md

@@ -20,7 +20,7 @@ owner whose label nothing answers to, and a teammate that is not listening.*
 
 | Capability | How | What you get |
 |---|---|---|
-| Join the team | `/board` as the lead, `/team join <label>` as a teammate, or any card you work | The session is on the team under a label peers address, listening, and `/team` and the Team tab list it |
+| Join the team | `/board` as the lead, `/team join <label>` as a teammate, or the first card you claim | The session is on the team under a name peers address, listening, and `/team` and the Team tab list it |
 | Hand a feature to a running session | `team` action `assign` | The card is `doing`, owned by that session, and a handoff is in its inbox |
 | Tell the peer what to do first | `team` action `assign` with `note` | The handoff carries the card, its paths, its plan, and that line |
 | Hand a feature to whoever is free | `team` action `offer` | Every other live session gets an event naming the card; the card stays unowned until one claims it, and it records when the offer was made, so a lead can tell an offer nobody took from a card nobody has looked at |
@@ -58,15 +58,15 @@ its surface is the point: `board` and `team` join this session for you.
 | You are | Action | What happens |
 |---|---|---|
 | The lead | `/board` | The session joins as `team-lead` — the page's own seat name — and listens, so a handoff or an offer is reported at its next turn |
-| A teammate | `/team join billing-core` | The session joins as `billing-core`, and Pi's footer and `/resume` show that name |
-| Either | any `board` action that writes | The first one joins the session under the name it already has, and listens |
-| A viewer | `/board` on a session that is not serving | The page is somebody else's to serve, so this session joins under its own label instead of the seat |
+| A teammate | the first card it claims | The session joins as its own `team-agent-<id>` name and listens, and Pi's footer keeps the name it already had |
+| A teammate who wants a name | `/team join billing-core` | The session joins as `billing-core`, and Pi's footer and `/resume` show that name — the one join that renames |
+| A viewer | `/board` on a session that is not serving | The page is somebody else's to serve, so this session joins under its own name instead of the seat |
 
 Joining is listening: mail is reported at that session's next turn, and **no turn is
 raised** for it, so being on the team never spends a turn. `/team` says who is live and
-who is live but not listening. `/board status` repeats only what the last `/board` in this
-session did about the team — a join made by `/team join` or by a card write is not on that
-line, and a page that is not running prints no team clause at all.
+who is live but not listening. `/board status` reports the team this session is on — which
+label, and whether mail reaches it — whichever door put it there, and prints no team clause
+only when this session never joined at all.
 
 **The seat is not a session.** The page is a view: it has one name, `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
@@ -159,7 +159,7 @@ decision the plain unassigned row never offered: re-offer, `assign` it, or take
 
 - **Nothing here can start a peer's turn.** A message is reported at the recipient's next
   turn; a session that is not listening at all reads it only when it reads its inbox.
-- **`to` must be on the team.** A session that never opened the board, joined, or worked a
+- **`to` must be on the team.** A session that never opened the board, joined, or claimed a
   card cannot be handed a card, and an offer to nobody says so.
 - **`team-lead` is a label, not a person.** The seat is not a session, so its actor id
   `board:team-lead` answers no message; the label is the one the session serving the page
@@ -207,9 +207,9 @@ decision the plain unassigned row never offered: re-offer, `assign` it, or take
   and must work with the bus disabled; `team` is the lead's round and is the only thing
   that needs the bus. If the round ever stops needing it, `team` folds back in.
 - **Joining is the bus's, wearing `board`'s clothes.** A lead should not have to learn a
-  second tool to be on a team, so `/board` joins, a card write joins, and `/team join` is
-  the one naming action. `wake` stays a bus-level choice and is never armed on a user's
-  behalf, because it spends turns.
+  second tool to be on a team, so `/board` joins, the first claimed card joins, and
+  `/team join` is the one naming action. `wake` stays a bus-level choice and is never
+  armed on a user's behalf, because it spends turns.
 - **Push and pull are two verbs.** `assign` writes the owner and sends one message;
   `offer` broadcasts and writes nothing. One verb with an optional `to` would have two
   outcomes and one details shape, and a reader could not tell which happened.

package/extensions/board/commands.ts

@@ -9,21 +9,25 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { plural } from "../../lib/board/round-text.ts";
+import type { BoardTeam } from "../../lib/board/session.ts";
 import type { JoinResult } from "../../lib/session-tool.ts";
 import { createTeamJoin, type TeamJoin } from "../../lib/session-tool.ts";
-import { joinLabel, teamLine } from "./join.ts";
+import { teamLine } from "./join.ts";
 import type { BoardPage, BoardPageStatus } from "./page.ts";
 
 /** The command's name, which is also the word a user types. */
 export const BOARD_COMMAND = "board";
 
 /** The words the command accepts, in the order a user is likely to want them. */
-export const BOARD_WORDS = ["status", "stop", "team"] as const;
+const BOARD_WORDS = ["status", "stop", "team"] as const;
 
-export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team?: TeamJoin } = {}): void {
+export function registerCommands(
+	pi: ExtensionAPI,
+	session: BoardTeam,
+	page: BoardPage,
+	deps: { team?: TeamJoin } = {},
+): void {
 	const team = deps.team ?? createTeamJoin(pi);
-	/** What the last `/board` did about the team, for the status line. */
-	let joined: JoinResult | undefined;
 	pi.registerCommand(BOARD_COMMAND, {
 		description: "Open the shared board in a local browser: /board [team | status | stop]",
 		getArgumentCompletions: (prefix: string) => {
@@ -35,7 +39,7 @@ export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const word = args.trim().toLowerCase();
 			if (word === "status") {
-				ctx.ui.notify(statusLine(await page.status(), joined), "info");
+				ctx.ui.notify(statusLine(await page.status(), session.team.last()), "info");
 				return;
 			}
 			if (word === "stop") {
@@ -60,7 +64,11 @@ export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team
 					);
 					return;
 				}
-				ctx.ui.notify((await page.stop(ctx)) ? "board: stopped" : "board: not running", "info");
+				const stopped = await page.stop();
+				// The word is this session saying it serves nothing now: the page clears the seat too
+				// when it closes itself (the idle grace), and both writes are the same fact.
+				session.serve(undefined);
+				ctx.ui.notify(stopped ? "board: stopped" : "board: not running", "info");
 				return;
 			}
 			if (word !== "" && word !== "team") {
@@ -71,18 +79,21 @@ export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team
 				return;
 			}
 			const started = await page.start(ctx, word === "team" ? "team" : "board");
-			// A failed start has already said why. Otherwise the join happens here, because
-			// opening the page is the lead's one action: the seat when this session serves it,
-			// this session's own label when it watches a page somebody else serves.
+			// A failed start has already said why. Otherwise the seat is set from the page's own
+			// answer — the page a session serves is a role, and every name this session writes and
+			// is addressed by follows from it — and the join happens here, because opening the page
+			// is the lead's one action.
 			if (started.kind === "failed") return;
-			joined = await team.join(ctx, joinLabel(started.kind === "served"));
+			session.serve(started.kind === "served" ? started.seat : undefined);
+			const joined = await team.join(ctx, { label: session.who(ctx, ctx.cwd).label });
+			session.team.record(joined);
 			// The address is on the line because the browser is not the only way in: a machine
 			// with no default browser prints it here, and a tab closed by mistake is one
 			// command from being opened again.
 			ctx.ui.notify(
 				started.kind === "attached"
 					? `board: ${started.seat} is serving this repository on :${started.port} — viewing · open ${started.url}${teamLine(joined)}`
-					: `board: ${started.seat} serving ${started.where} on :${started.port} · open ${started.url}${teamLine(joined)}`,
+					: `board: ${started.seat} serving ${started.repo} on :${started.port} · open ${started.url}${teamLine(joined)}`,
 				"info",
 			);
 		},
@@ -93,7 +104,7 @@ export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team
 export function statusLine(status: BoardPageStatus, team?: JoinResult): string {
 	if (status.running) {
 		const watching = plural(status.watchers ?? 0, "tab");
-		return `board: ${status.seat} serving on :${status.port} · ${watching} watching · ${status.where}${teamLine(team)}`;
+		return `board: ${status.seat} serving ${status.repo} on :${status.port} · ${watching} watching · ${status.where}${teamLine(team)}`;
 	}
 	if (status.stale === true) {
 		return `board: watching ${status.seat} on :${status.port} — that note answers nobody; /board stop drops it${teamLine(team)}`;
@@ -101,5 +112,7 @@ export function statusLine(status: BoardPageStatus, team?: JoinResult): string {
 	if (status.attached === true) {
 		return `board: watching ${status.seat} on :${status.port} — nothing to stop here${teamLine(team)}`;
 	}
-	return "board: not running — /board opens it";
+	// The team outlives the page: a session that claimed a card is on it with no page open, so
+	// the line says which team this session is on whichever door put it there.
+	return `board: not running — /board opens it${teamLine(team)}`;
 }

package/extensions/board/index.ts

@@ -15,6 +15,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
+import { requestMount } from "../../lib/http/index.ts";
 import { registerCommands } from "./commands.ts";
 import { type BoardPage, createBoardPage } from "./page.ts";
 import { type BoardSession, openBoardSession } from "../../lib/board/session.ts";
@@ -30,9 +31,20 @@ export interface BoardDeps {
 export default function board(pi: ExtensionAPI, deps: BoardDeps = {}): void {
 	if (!isExtensionEnabled("board")) return;
 	const session = deps.session ?? openBoardSession(pi);
-	const page = deps.page ?? createBoardPage(session);
+	/** The session the page serves as; the mount lands on this session's one server. */
+	let sessionId = "";
+	const page =
+		deps.page ??
+		createBoardPage(session, {
+			mount: (spec) => requestMount(pi, spec),
+			session: () => sessionId,
+		});
 	registerTools(pi, session);
-	registerCommands(pi, page);
+	registerCommands(pi, session, page);
+
+	pi.on("session_start", async (_event, ctx) => {
+		sessionId = ctx.sessionManager.getSessionId();
+	});
 
 	pi.on("session_shutdown", async () => {
 		await page.closeAll();