@gavin-hu/my-pi-agent 0.19.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,34 +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 |
-| `/favicon.ico` | `204` (the icon is a data URI) |
+| `/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
 
@@ -103,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. |
@@ -171,7 +168,10 @@ global document then project document, project wins — are in
 ## The page
 
 The page is server-rendered HTML with an inline style block and inline SVG
-icons, progressively enhanced by one first-party script (`client.ts`). A folder
+icons, progressively enhanced by one first-party script (`client.ts`). Each page
+names its own subject in the tab — `browse · <folder>`, `browse · <rel>` for a file, the
+`<page> · <subject>` shape the kit's `tabTitle` gives every served page — and links the
+brand mark as an SVG data URI, in the appearance the system is in. A folder
 folds from its twisty, and a `fold all` / `expand all` button beside the filter
 folds the whole tree at once. The tree scrolls in its own pane with quick open
 and the filter pinned above it; below 860px it collapses into a `Files`
@@ -340,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
-beside `⎇ branch` and `⑂ worktree`; it is cleared on stop and on
-`session_shutdown`. The chip is session-local: it reflects only this session's
-server, with no cross-session sharing.
+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
@@ -450,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
@@ -502,12 +499,17 @@ stops at the first difference because the control, not the checker, is the fix.
 | [`../../lib/escape.ts`](../../lib/escape.ts) | `escapeHtml`, the shared HTML escaping used by every renderer |
 | [`../../lib/highlight.ts`](../../lib/highlight.ts) | First-party escape-first syntax tokenizer for the code view (shared with `plan`) |
 | [`../../lib/web/index.ts`](../../lib/web/index.ts) | The shared Bytefly web brand system: tokens, base, components, layout, runtime, and markup |
-| `files/files.ts` | Classification (incl. Markdown), text reads, and one page-level walk (`directoryView`) that returns a directory's listing and its sidebar tree |
+| `files/files.ts` | The barrel over the four reads: one surface for the callers, four modules behind it |
+| `files/classify.ts` | What a name is: kind, Markdown, image, MIME type, and the text sample |
+| `files/list.ts` | Capped directory listings and one file's bytes, over injected filesystem reads |
+| `files/tree.ts` | The sidebar tree and the page-level walk (`directoryView`) that returns it with the listing |
+| `files/index.ts` | The quick-open file index, walked once per root up to a cap |
 | `text/diff.ts` | Pure unified-diff and porcelain-status parsing for the diff view |
 | `text/fuzzy.ts` | Fuzzy path matching and ranking for the quick-open palette |
 | `view/markdown.ts` | First-party escape-first Markdown-to-HTML renderer (fenced code highlighted; raw HTML through `raw-html.ts`) |
 | `view/raw-html.ts` | Allowlisted raw-HTML sanitizer: element/attribute policy, suppressed bodies, and cross-block balancing |
 | `view/urls.ts` | Shared link/image URL policy: scheme allowlist and `/view`/`/raw` rewriting |
+| `view/emit.ts` | The anchor and image elements both renderers emit, so a link written in Markdown and the same one written as HTML are one element |
 | `git/git.ts` | Read-only branch/dirty provider for the header chip |
 | `view/icons.ts` | Inline SVG sprite and the per-language mapping |
 | `view/client.ts` | The `/app.js` source: sort, wrap, copy, hunk navigation, reading progress, and the page keymap |
@@ -522,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/job.md

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

package/docs/extensions/plan.md

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

package/docs/extensions/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.