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

package/extensions/plan/README.md

@@ -3,7 +3,7 @@
 A read-only exploration mode modelled on Claude Code's `EnterPlanMode` /
 `ExitPlanMode` pair. While plan mode is on, the model investigates and proposes,
 but the only thing it may write is the plan file itself. The plan is saved under
-`.pi/plans`; the user reviews that file, and it is the artifact the model
+the agent directory; the user reviews that file, and it is the artifact the model
 executes.
 
 ```bash
@@ -44,11 +44,14 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   quality checklist, and writes only after plan approval. It supports existing and
   empty repositories, and falls back to evidence with recorded assumptions when
   the interview is unavailable or cancelled; it never invents commands.
-- **Plan files.** The model saves the plan with `write_plan`; the file lands in
-  `<repo-root>/.pi/plans/<YYYY-MM-DD-HHmm>-<slug>.md` — the entered worktree's
-  root when one is active — or `<agent-dir>/plans` outside a repository. The
-  plans directory is self-ignoring, so plan files never show up as untracked
-  files or in `rewind` snapshots.
+- **Plan files, shared by the whole repository.** The model saves the plan with
+  `write_plan`; the file lands in
+  `<agent-dir>/plans/<repo-key>/<YYYY-MM-DD-HHmm>-<slug>.md`, keyed by the
+  repository's common git directory, so a plan approved in one worktree is the
+  same plan from the main checkout and from every other session. Outside a
+  repository the store is `<agent-dir>/plans`. Plans are outside the project, so
+  they are never untracked files and never appear in a `rewind` snapshot; a store
+  an older version left in `<repo>/.pi/plans` is moved in once, with a notice.
 - **A discoverable index.** `/plan list` walks the plans directory and shows
   every plan with its title, modified time, and step progress, newest first — in
   the TUI as a docked list where `Enter` opens the plan's review, elsewhere as a
@@ -96,10 +99,10 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   it for approval. The user approves, keeps planning, asks for a refinement, or
   exits plan mode without approving; the last keeps the plan file for a later
   review and records no todo items or goal.
-  On a remote turn (WeChat) the plan file is sent first, then a digest of its
-  title, step count, and first steps, then the choices, so the review is still
-  answerable when the attachment is not opened. The choices include **Send the
-  full plan**, which posts the plan text and asks again.
+  On a remote turn (WeChat) the plan file is sent first, then one compact editor
+  prompt: the title, step count, first steps, mode status, and three actions
+  (approve, keep, exit). Any other reply is a refinement request; if the file
+  upload fails, its text is sent instead.
 - **Browser review on demand.** Press `w` on the review screen (or run
   `/plan review [path]`) to open the plan in a local browser: a reading-first
   page with the plan's H1 as its title, GitHub's Markdown content column, a
@@ -115,10 +118,11 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
 - **Steps become todos.** On approval, the top-level numbered/bulleted items of
   the plan's `Steps` section are recorded with the `todo` tool (via
   `ctx.executeTool`); steps marked `- [x]` (or `[DONE:n]`) seed as completed, and
-  nested sub-bullets are treated as notes. The list is a merge, not a
-  replacement: existing items keep their place and status, a step whose text is
-  already there is skipped, and the tool's item cap defers the rest instead of
-  dropping anything. The plan's `## Verification` section follows as the **last**
+  nested sub-bullets are treated as notes while an indented line continues its
+  step. The list is a merge, not a replacement: existing items keep their place
+  and status, a step whose text is already there is skipped, and the tool's item
+  cap defers the rest instead of dropping anything. The plan's `## Verification`
+  section follows as the **last**
   todo item, summarized on one line (`Verify: …`) — a fenced block contributes its
   commands, not its fence lines. It is not a plan step, so it is ticked in the todo
   list rather than with `set_plan_steps`, and it never counts against the 50-step
@@ -132,21 +136,87 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   instead of beside it. On approval, a goal the goal workflow left as a draft
   (`planning`) is finalized from the plan's own `## Goal` section — falling back
   to the title — through the `goal` tool, with no extra dialog, because approving
-  the plan *is* the decision. A session with no goal at all gets one confirm to
-  record the same objective, unless `plan.goalPrompt` is off, which records it
-  without asking. An `active` or `achieved` goal is never rewritten: a final
-  objective is the user's. No path spends a model turn.
+  the plan *is* the decision. A session with no goal at all is given the same
+  objective, also without asking. An `active` or `achieved` goal is never
+  rewritten: a final objective is the user's. No path spends a model turn.
+- **A split, when the switch is on.** With `plan.split` enabled (off by default;
+  a `/bytefly settings` row), `exit_plan_mode` also accepts `units`: the plan's
+  slices, each with a name, path prefixes, a test, and the units it depends on.
+  The split is validated *before* the review opens, so a refusal costs no review,
+  and the review screen shows it as a read-only `Split` section. On approval the
+  team is written into the plan as a `## Team` table — a sentence naming the lead's
+  unit, then one row per unit — and the result carries a roster card: the exact
+  commands for the sessions this package cannot start, the merge order, which unit
+  is the lead's own, and the lead's own label or the rename that sets it. The team
+  section is what a joining session reads, so it appears only after approval; a
+  refinement rewrites the plan, and with it the team ceases to exist until the plan
+  is approved again. Refusals name the pair: fewer than two units (with the
+  skeleton advice), overlapping prefixes, a `dependsOn` cycle, more than two owners
+  plus the lead, a unit with no test, an owner unit that claims a shared file, and a
+  value that would break the table. See [Splitting a plan](#splitting-a-plan).
 - **Branch-aware.** The enabled flag and the review baseline are custom session
   entries, so `/resume` and `/tree` restore the right mode and keep the
   changed-section markers.
 
+## Splitting a plan
+
+Off by default: enable **Split plans into slices** in `/bytefly settings`, or set
+`"plan": { "split": true }` in the project's `.pi/bytefly.json` so a repository
+switches its own team on.
+
+```text
+exit_plan_mode({
+  plan_path: "~/.pi/agent/plans/a1f9c02/2026-11-04-1802-billing.md",
+  units: [
+    { name: "contract", paths: ["src/billing/contract"], test: "bun test src/billing/contract", lead: true },
+    { name: "core", paths: ["src/billing/core"], test: "bun test src/billing/core", dependsOn: ["contract"] }
+  ]
+})
+```
+
+The result prints the roster card, which is all the package can do for the sessions
+it cannot start — and the one line it can act on for the session it is in:
+
+```text
+Split: 2 units · ~/.pi/agent/plans/a1f9c02/2026-11-04-1802-billing.md
+  You start and switch every session; nothing here can.
+  core: enter_worktree core · /sessions name core · /sessions watch wake
+    session({action:"join", team:"2026-11-04-1802-billing", unit:"core"})
+  merge order: contract → core · your unit: contract
+  your label: none — name this session: session({action:"name", label:"contract"})
+```
+
+The last line is the lead's own label. The card's other lines are for the sessions
+the user starts; this one is the lead's own, so it names the label when the session
+already has one, and otherwise prints the rename to run. Once set, it reads
+`your label: billing-lead — owners send their report there`, which is what an
+owner addresses its completion report to.
+
+What the gate enforces, and why each rule is a refusal rather than a warning:
+
+| Refusal | Why |
+|---|---|
+| fewer than two units | One path is not a split: approve as one flow, or build the thinnest end-to-end path first. |
+| overlapping prefixes | Two owners on one path is a merge conflict by construction. |
+| a `dependsOn` cycle | No unit can start. |
+| more than two owners | The user switches to every owner each round; three means the split is wrong. |
+| a unit with no test | The unit's definition of done would be undocumented. |
+| an owner unit claiming a shared file | `package.json`, the changelog, the test manifests, and the shared name modules belong to the lead. |
+| no unit marked lead | The approving session needs a unit of its own, or it is a queue. |
+
+The table itself is a wire format: [`session-bus`](../session-bus/) parses it with
+the same module that writes it, so a hand-edited or stale section is refused
+rather than half-read. The browser review cannot approve a split plan — a section
+written at approval has no source lines for its comments to anchor to — so the
+terminal review is where a split is approved.
+
 ## Tools
 
 | Tool | Active | Purpose |
 |---|---|---|
 | `enter_plan_mode` | normal mode | Ask to enter plan mode; empty schema, confirmed with `ctx.ui.confirm`. |
 | `write_plan` | plan mode | Save the plan: `title` (file-name slug), `content` (full markdown in the documented outline), optional `plan_path` to overwrite a refinement. Returns the absolute path. A plan with more than 50 top-level steps in its `Steps` section is refused, with the cap and the fix named, and nothing is written. |
-| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. The review also offers **Exit plan mode (discard)**, which leaves plan mode without approving. Refuses a file whose step list is over the cap, before the review screen. |
+| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. Optional `units` proposes a split when `plan.split` is on; it is validated before the review, written into the plan on approval, and ignored with one note while the switch is off. The review also offers **Exit plan mode (discard)**, which leaves plan mode without approving. Refuses a file whose step list is over the cap, before the review screen. |
 | `cancel_plan_mode` | plan mode | Leave plan mode without a plan file or a review. Restores write access; records no todo items or goal; keeps any saved plan. Empty schema. |
 | `set_plan_steps` | normal mode | Keep an approved plan current: set the checkboxes of the given top-level steps (`updates`, each a 1-based `step` in the order `exit_plan_mode` listed, plus `status`, and `expected` — the step's text, so a reordered plan is refused) to `pending` or `completed` in one write. Only the checkboxes change, and a reopened step drops its `[DONE:n]` marker. The todo item approval seeded from a step is ticked with it: the file is written first and is authoritative, a renamed item is left alone, and a failed todo write is reported in the result. |
 
@@ -194,15 +264,15 @@ approval. Its workflow is:
 ```text
 /skill:init
   └─> plan mode (read-only)
-        └─> recon: manifests, docs, CI, tests, existing instructions
-        └─> interview: built-in bank, one call of at most 4 questions
+        └─> recon: effective instruction file, sourced evidence, existing instructions
+        └─> interview: built-in bank, one call of at most 4 questions, minus resolved facts
               ├─ answered ───────────────> reconcile with evidence
               └─ unavailable/cancelled ──> evidence + assumptions
         └─> draft: new file, exact edits, or an honest no-op
         └─> quality gate
         └─> write_plan ──> exit_plan_mode
                              ├─ not approved ──> refine the same plan
-                             └─ approved ──────> write/edit AGENTS.md
+                             └─ approved ──────> write/edit the target
                                                  └─ read back + quality checklist
 ```
 
@@ -210,15 +280,26 @@ The interview comes from a built-in bank in
 [`skills/init/references/interview-questions.md`](../../skills/init/references/interview-questions.md):
 core questions cover purpose, verification, non-obvious rules, isolation,
 completion, sensitive paths, and dependency or network limits, with state-specific
-entries for an existing file, an empty repository, and related instruction files.
-The first call uses a deterministic four-question set for the repository state;
-a second call is allowed only for a material ambiguity. If the tool is inactive,
-there is no UI, or the user cancels, the skill records the gaps as assumptions
-and continues from repository evidence.
+entries for an existing file, an empty repository, related instruction files, and
+a shadowing override. The first call uses the bank's deterministic set for the
+state, minus every field the evidence sheet resolved; a second call is allowed
+only for a material ambiguity. If the tool is inactive, there is no UI, or the
+user cancels, the skill records the gaps as assumptions and continues from
+repository evidence.
+
+Recon resolves the effective instruction file first: a root `AGENTS.override.md`
+replaces `AGENTS.md` and becomes the target, while an override above the project
+root is reported rather than edited. Recon also builds a sourced evidence sheet —
+commands with the file that defines them, generated and vendored paths from
+`.gitignore`, workspace packages and boundaries, and purpose from the README or
+manifest — and the interview asks only what it could not resolve. The plan uses
+the canonical outline, including `## Steps` and `## Verification`, so approval
+seeds the apply actions rather than the draft's bullets.
 
 The quality reference is
 [`skills/init/references/agents-md-quality.md`](../../skills/init/references/agents-md-quality.md).
-An existing `AGENTS.md` is reviewed and updated only after approval, an accurate
+An existing instruction file is reviewed and updated only after approval, a root
+override is edited in place or removed explicitly when consolidating, an accurate
 file can produce a no-op plan, and an empty repository gets only known facts.
 The skill needs the plan extension for its review gate. It also ships with the
 package, so load the whole package (`pi -e .`) or install it; loading only
@@ -233,14 +314,15 @@ so headings, lists, inline code, code blocks, links, and quotes carry the active
 theme's colors; task items get the shared `◼` (done) or `◻` (pending) marker,
 like the bytefly screen and the question dialog. The footer colors the primary
 actions (`a approve & run` in `success`, `r refine` in `accent`).
-`a` ends plan mode, restores write access, and seeds `todo`; `r` keeps the plan
+`a` asks `y/N` in the footer, then ends plan mode, restores write access, and
+seeds `todo`; `y` or `Enter` approves and `n`, `q`, or `Esc` goes back to
+reading. `r` keeps the plan
 mounted and opens an inline editor beneath it (`Enter` submits, an empty buffer
 does nothing, `Esc` returns to the plan); `Esc` keeps planning and tells the
 model the plan was not approved; `x` leaves plan mode without approving and
-keeps the plan file. The dialog path offers the same five outcomes, including
-**Exit plan mode (discard)**. Dismissing the dialog (or a timeout) is also an
-exit, not a silent `keep`; only the explicit **Keep planning** option stays in
-plan mode. When the plan changed since the previous review
+keeps the plan file. The dialog path is one editor prompt: `1` approve, `2` full
+plan, `3` keep, `4` exit; any other text refines the plan. Dismissing or timing
+out the prompt exits without approving. When the plan changed since the previous review
 on this branch, a summary line under the title names how many sections changed
 and the scroll row appends `· changed` to the current section. Scroll with `↑`/`↓` or `j`/`k`, `space`/`b` or
 `PgUp`/`PgDn`, `d`/`u`, `g`/`G`, and the mouse wheel. Press `n`/`p` to jump to
@@ -255,14 +337,12 @@ dropped whole as the terminal narrows, and each footer leads with its safe exit
 (`Esc keep plan` in the review, `Esc back to plan` in the inline editor) so
 the exit survives even when only one hint fits.
 
-Dialog-capable non-TUI modes (RPC) show the same five choices as a select menu
-plus the refine editor; cancelling the editor returns to the select instead of
-being reported as "not approved". Dismissing the plan select is an exit. A WeChat turn takes the same dialog path and
-is answered over WeChat, even though the session is in TUI mode: the choice
-comes from `askHuman(ctx, { custom, dialogs, file, body })` in
-`lib/interaction.ts`, not from `ctx.mode`. A remote turn also receives the plan
-**file** first (falling back to the plan text if the upload fails) so the whole
-plan is reviewable there; RPC has no channel and still sees only the choices.
+Dialog-capable non-TUI modes (RPC/WeChat) use one editor prompt; a non-action
+reply is the refinement, so “select Refine, then type” is gone. A WeChat turn
+takes the same dialog path and is answered over WeChat, even though the session
+is in TUI mode: the choice comes from `askHuman(ctx, { custom, dialogs, body })`
+in `lib/interaction.ts`, not from `ctx.mode`. No plan file is attached; **full
+plan** posts the text and asks again.
 Without any UI the tools fail with an actionable message instead of deciding for
 the user.
 
@@ -289,13 +369,13 @@ enter_plan_mode requested plan mode
 
 ```
 write_plan Add rate limiting
-✓ Saved plan .pi/plans/2026-10-09-1809-add-rate-limiting.md
+✓ Saved plan ~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
 ```
 
 ```
 exit_plan_mode submitted a plan
 ✓ Plan approved
-.pi/plans/2026-10-09-1809-add-rate-limiting.md
+~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
 
 # Add rate limiting
 1. Add a token bucket …
@@ -303,16 +383,6 @@ exit_plan_mode submitted a plan
 … 12 more lines (ctrl+o to expand)
 ```
 
-## Configuration
-
-The `plan` section of the shared `bytefly.json` (global then project), or the
-**Offer the session goal** row in `/bytefly settings`. It is read when a plan is
-approved, so a change applies to the next approval without a reload.
-
-| Key | Default | Meaning |
-|---|---|---|
-| `goalPrompt` | `true` | Ask before recording an approved plan's objective as the session goal; `false` records it without asking. |
-
 ## Security
 
 Plan mode is a **guard rail, not a sandbox**: extensions run with Pi's OS
@@ -409,12 +479,13 @@ Pi's Markdown renderer with the active theme, so headings, lists, code, and
 links read as they do in the transcript; the checkboxes in `Steps` use the
 shared `◼`/`◻` vocabulary. A plan taller than the terminal scrolls under a gauge
 that names the section at the top of the viewport and the line range it shows,
-and the footer lists only the keys that apply. `Esc` keeps planning, `a` approves
-and runs, `r` refines inline, and `w` opens the browser review below.
+and the footer lists only the keys that apply. `Esc` keeps planning, `a` asks
+`y/N` and then approves and runs, `r` refines inline, and `w` opens the browser
+review below.
 
 ## Browser review
 
-<img src="../../assets/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 side panel with step progress and a section outline, and the plan as one measured column with a comment rail and an inline review thread" width="100%">
+<img src="../../assets/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
@@ -447,17 +518,26 @@ file and returns them to the model.
   labelled and indented as a thread, so it reads in place and the plan keeps one
   measure at every width. There is no separate column to reflow.
 - **Nothing typed is lost.** **Save feedback**, **Approve & run**, and **Back to
-  Pi** refuse while a composer holds text and put the cursor back in it, and a
-  deleted comment is offered back in the header for a few seconds. The page keeps
-  no draft of its own — these are the three ways an open comment could disappear.
+  Pi** refuse while a composer holds text and put the cursor back in it, a
+  deleted comment is offered back in the header for a few seconds, and this tab's
+  unsaved work survives a reload: the comments it added and the text still in its
+  composer are kept in `sessionStorage` under a digest of the plan text the page
+  rendered, then restored on the next load of that same text with the composer
+  reopened at the caret and the selection it quoted, and dropped when the plan
+  changed underneath them. A composer closed with `Esc` or **Cancel** discards its
+  text, so only an abandoned tab gets it back. Nothing is stored on the server, and
+  another writer's comment is never part of the draft.
 - **Prints as a document.** Printing uses the light palette whatever the screen
   shows, drops the header, panel, rail, and progress bar, and lets the comments
   stay with the blocks they belong to.
 - **Keyboard first.** `j`/`k` move to the next or previous block, `c` comments
   on the current block, `a` approves (the approval flow only), `s` saves, `Esc`
   closes the composer or the sheet and then the review, and `?` opens a shortcut
-  sheet; the header's `?` button opens the same sheet. Either dialog traps
-  `Tab` and hands focus back to whatever opened it.
+  sheet; the header's `?` button opens the same sheet. Adding, editing, or
+  deleting a comment rebuilds the document, so the tab stop returns to that
+  block's comment control instead of being dropped, and the status line says
+  which change landed; a repaint the stream caused never moves focus. Either
+  dialog traps `Tab` and hands focus back to whatever opened it.
 - **Decision in place.** A review opened for approval (`w` on the review screen)
   shows **Approve & run** beside Save feedback: it persists the current comments,
   ends plan mode, restores write access, seeds `todo`, and hands control back to
@@ -478,10 +558,20 @@ 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. Saving is
-  idempotent: the previous markers are stripped first, so a second save replaces
-  rather than appends. Stripping is fence-aware: a `> [!REVIEW]` line inside a
-  code block is documentation, not feedback. The browser keeps no copy of its own.
+  `> [!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
+  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
+  documentation, not feedback. The file is the only copy of a saved comment; the
+  ones this tab has not saved yet live in its own `sessionStorage` and nowhere else.
+- **A revision keeps the review.** `write_plan` passes the file it is replacing
+  through `carryFeedback`, which re-attaches each comment by the strongest evidence
+  that survived: the anchored block's text, per occurrence, so a plan that repeats
+  a step keeps the comments apart; then the same section at the same position, so a
+  reworded step keeps its note; then the end of that section. A comment whose
+  section is gone too moves to the end of the file, where the page shows it as
+  unattached, rather than disappearing.
 - **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
@@ -492,24 +582,89 @@ 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 and tokenized.** The server binds `127.0.0.1`, carries a random
-  per-session token in the URL, rejects a missing or foreign `Host` header,
-  serves only `GET`, `HEAD`, and `POST`, and caps the request body. A save or cancel
+- **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 save, cancel, a dropped event stream, or
-  `session_shutdown`; a reload reconnects inside that grace, so refreshing or
-  reloading a conflicted page does not end the review.
+  saved theme with it). 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.
 
 | Route | Result |
 |---|---|
 | `GET /?token=…` | the review page (a JSON data island plus `/theme.js` and `/client.js`) |
 | `GET /theme.js` | the shared pre-paint theme bootstrap |
 | `GET /client.js` | the first-party client script |
-| `GET /events?token=…` | Server-Sent Events stream, used only to detect a closed tab |
-| `POST /api/feedback?token=…` | validate and write the annotations into the plan |
-| `POST /api/cancel?token=…` | end the session without saving |
+| `GET /events?token=…` | Server-Sent Events stream: a `comment`, `plan`, or `share` frame when something changed, `closed` when the review ends, `revoked` when sharing stops, and a dropped stream to detect a closed tab |
+| `POST /api/comment?token=…` | reviewer only: write their own comments into the plan, replacing only their own; never ends the review |
+| `POST /api/feedback?token=…` | owner only: write the owner's comments and return to the model |
+| `POST /api/approve?token=…` | owner only: save, then approve |
+| `POST /api/cancel?token=…` | owner only: end the session without saving |
+| `POST /api/share?token=…` | owner only: mint the first reviewer link and its QR |
+| `POST /api/share/link?token=…` | owner only: mint one more reviewer link, so each teammate holds their own |
+| `POST /api/share/revoke?token=…` | owner only: revoke one link by `{ id }`, leaving the others answering |
+| `POST /api/share/stop?token=…` | owner only: revoke every reviewer link |
+
+## Shared review
+
+A review is not only the owner's. **Share** in the review header (or `/plan share`)
+mints a reviewer link, binds a second listener on the machine's first reachable
+IPv4 address, and shows the link with a QR a phone can scan. **New link** in the
+same dialog mints one more, so each teammate holds a link of their own. **Stop
+sharing** revokes every link and closes that listener; closing the review does
+both.
+
+- **Two roles, one token each.** The owner's token — the one the browser opened
+  with — decides: it may comment, save (which returns to the model), approve,
+  cancel, mint links, and revoke them. A reviewer token may read and comment, and
+  its one write route is `POST /api/comment`: `/api/feedback`, `/api/approve`,
+  `/api/cancel`, and the `/api/share` family answer `403`, and the page renders
+  only the name control and **Post comments** for it — and once that link has
+  posted, the control shows the bound name instead of offering the dialog.
+  Anything the reviewer holds is reachable only while its link is shared.
+- **One link is one person.** The dialog lists every link with the name it has
+  bound, and the two things an owner does with one: **Copy**, and **Revoke**, which
+  drops that link alone — its page is told `revoked` and its token stops
+  answering, while the others keep working. Revoking the last link stops sharing.
+  A review holds at most eight links, because each is a live credential.
+- **The owner's page is the review's lifetime.** A reviewer's tab opening or
+  closing changes nothing; the review ends when the owner saves, approves, or
+  closes it, or when the owner's own page goes away. A reviewer's post writes the
+  plan and updates every open page, and leaves the review waiting. A page that is
+  still open when the review ends is told why — `closed`, or `revoked` when its
+  link was revoked or sharing was stopped — and keeps the plan readable.
+- **Signed comments.** A reviewer names herself once, on the page, and that name
+  is bound to her link on its first post: the link stores under it from then on,
+  a second tab of the same link that picked another name is refused (`409`) rather
+  than silently re-signing, and a name another live link already holds is refused
+  when it is first claimed. A bound name is shown, not offered, so a reviewer can
+  edit or withdraw her own notes and nobody else's, and her second post replaces
+  rather than duplicates the first. The name is a label on a bearer link, not an
+  account, which is why the owner still makes the only decision.
+- **One listener, one machine.** Sharing opens exactly the address the dialog
+  printed — never `0.0.0.0` — and the `Host` allowlist becomes loopback plus that
+  address, however many links answer on it. A machine with no reachable IPv4
+  address reports why instead of printing a link that cannot work. There is no
+  tunnel, no relay, and no cross-machine sync: this is the same Wi-Fi.
+- **Live.** Every open page follows the stream, so a reviewer's post appears on the
+  owner's page without a reload. The review also polls its own plan file once a
+  second, so an edit this review did not make — the model rewriting the plan while
+  `/plan review` is open in normal mode, or a teammate's editor — repaints every
+  reader instead of waiting for the next request, and a save that changed nothing
+  but comments stays quiet. A page with a draft open refuses to repaint and says
+  what arrived instead. The owner's terminal is told too — `Plan review: @alice
+  posted 2 comments.` — because whoever is waiting in the TUI is not looking at
+  the page.
+- **What a shared link is.** A bearer credential: anyone who has it reads the plan
+  and can comment, under the one name it binds on its first post. The dialog says
+  so, `Referrer-Policy: no-referrer` keeps a click from leaking it, and **Revoke**
+  (or **Stop sharing**) is the revocation. The plan file is the record — a comment
+  arrives as an author-tagged marker, so `/resume` and the terminal show the same
+  review the page did.
 
 ## Limitations
 
@@ -536,6 +691,18 @@ file and returns them to the model.
 - Feedback stripping follows fenced code blocks; an unterminated fence makes the
   rest of the file code, so a marker-looking line after it is treated as content
   rather than stored feedback.
+- A comment is one line. Stored feedback is a single blockquote line, so newlines
+  and runs of spaces collapse before it is written; a pasted multi-line
+  instruction reaches the model as one sentence, which is what keeps the marker
+  grammar valid markdown.
+- The plan-file poll runs once a second, so an edit made elsewhere reaches an open
+  page within about that long, and a write that leaves the plan's text identical —
+  another process appending only a comment — is not announced; the next save still
+  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 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.
 
 ## Non-goals
 
@@ -551,7 +718,7 @@ file and returns them to the model.
 |---|---|
 | Tools | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps` registered with `executionMode: "sequential"`. `enter_plan_mode` is active normally with `readOnlyHint: true`; `write_plan` (`readOnlyHint: false`) and `exit_plan_mode` (`readOnlyHint: true`) are `defaultActive: false`. `set_plan_steps` is active normally (`readOnlyHint: false`, `idempotentHint: true`); the read-only policy default-denies it in plan mode. Each returns typed `details` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`), and `ExitPlanModeDetails` carries the review's `annotations` when a browser approval or save supplied comments; no `outputSchema`/`structuredContent`. |
 | Commands and flags | `/plan` (toggle, or enter and send a task), `/plan list` (plans index), `/plan review [path]` (browser review), `/skill:init` (skill-backed `AGENTS.md` bootstrap), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
-| State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })`, and each review's baseline persisted with `pi.appendEntry("plan-baseline", { path, sections })` as one digest per heading section; both rebuilt from `ctx.sessionManager.getBranch()`, so `/resume` and `/tree` restore the mode and the changed markers of the branch they land on. Plan writes a goal only at approval, through `ctx.executeTool("goal", { objective })`: a `planning` goal is promoted to the plan's `## Goal`, a session with none is offered one unless `plan.goalPrompt` is off, and an `active`/`achieved` goal is left alone. A review that shows the same content appends nothing. The last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. |
+| State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })`, and each review's baseline persisted with `pi.appendEntry("plan-baseline", { path, sections })` as one digest per heading section; both rebuilt from `ctx.sessionManager.getBranch()`, so `/resume` and `/tree` restore the mode and the changed markers of the branch they land on. Plan writes a goal only at approval, through `ctx.executeTool("goal", { objective })`: a `planning` goal is promoted to the plan's `## Goal`, a session with none is given the same objective, and an `active`/`achieved` goal is left alone — no path asks first. A review that shows the same content appends nothing. The last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. |
 | Entry requests | `pi.events` channel `PLAN_ENTER_REQUEST` from `lib/plan-entry.ts`: the `goal` workflow asks, with the shared consent sentence, and plan enables the mode on the caller's context without a second dialog. Subscribed on `session_start`, released on `session_shutdown`. |
 | Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context, with a pursued session goal read from the branch through `lib/goal-state.ts`; `context` keeps only the newest plan context while enabled and drops stale ones otherwise. |
 | Lifecycle | `session_start`/`session_tree` restore state; `session_shutdown` clears the footer status and closes any browser review server. |
@@ -595,8 +762,9 @@ file and returns them to the model.
   `ctx`, so a listener could not refresh the todo widget; calling the real tool
   runs its validation and widget sync and needs no change to `todo`. Only the
   top-level list items of the `Steps` section become steps (the whole document
-  is the fallback when that heading is absent), so the outline's prose lists
-  never seed the list. The list is whole-list replacement, so the current items
+  is the fallback when that heading is absent), and an indented line continues
+  its step, so the outline's prose lists never seed the list. The list is
+  whole-list replacement, so the current items
   are read back from the branch's last `todo` result (the published state
   channel; no import from that extension) and the steps are merged into them.
   A rejected seed reports the nested tool's own reason in the approval message
@@ -668,6 +836,25 @@ file and returns them to the model.
   so annotating never moves the text. That removes the two-column grid, the
   `bf-review--no-rail` collapse, and the breakpoint ladder, and matches the TUI,
   where neither review header carries a progress counter.
+- **A poll, not a file watcher.** An open review re-reads its plan once a second
+  and announces when the text stopped matching what the page rendered, because the
+  review owns the page and not the file: `/plan review` runs in normal mode, so the
+  model can rewrite the plan underneath it. The house rule is a poll (see
+  `file-browse`'s note): `fs.watch` is the one part of `node:fs` whose availability
+  and event semantics differ per platform, and it would add a long-lived resource
+  to start and release. The check only announces — it never writes `pageText`,
+  which stays the anchor a save is validated against — so a save through the routes
+  says nothing, and an announced edit can be announced once more by the read that
+  repaints: that read is what updates `pageText`, so it converges instead of
+  looping, at the cost of one extra refetch.
+- **One link is one person, and the token table is the roster.** A shared review's
+  unit of access is a link, not a room: a token names a role and binds the name its
+  owner posts under, so two people on one link are one writer and the second name
+  is refused. The owner hands out one link per teammate and takes one back without
+  disturbing the rest, and the exit of a link is the exit of one token, one stream,
+  and one marker author — which is why the streams are addressed by token rather
+  than by role, and why the link table is pure and separate from the listener that
+  answers on it.
 
 ## Files
 
@@ -675,7 +862,6 @@ file and returns them to the model.
 |---|---|
 | `index.ts` | Wiring: tools, command, flag, shortcut, events, context injection. |
 | `types.ts` | `PlanModeEntry`, `EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`. |
-| `config.ts` | The `plan` section loader: `goalPrompt`, default on. |
 | `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`. |
@@ -687,22 +873,30 @@ file and returns them to the model.
 | `tools.ts` | Registration entry: composes the four tool registrations in the order the session sees them. |
 | `tools/` | One module per tool (`enter.ts`, `write.ts`, `exit.ts`, `steps.ts`), plus `todo-seed.ts` (the two nested `todo` writes) and `nested.ts` (reading a nested result). |
 | `review.ts` | The review gate: one decision from the TUI screen, a dialog, or the browser, the shared browser lifecycle, and the "mark what was shown" baseline rule. |
-| `commands.ts` | `/plan` (enter, optional task) and the `/plan review [path]` browser subcommand. |
-| `tui.ts` | `PlanViewComponent` (sectioned Markdown body, changed-section summary and marker, section jump, scroll gauge, approve/refine/browser/keep). |
+| `commands.ts` | `/plan` (enter, optional task), `/plan review [path]`, and `/plan share [stop]`. |
+| `tui.ts` | `PlanViewComponent` (sectioned Markdown body, changed-section summary and marker, section jump, scroll gauge, the approve `y/N` question, approve/refine/browser/keep). |
 | `plan-index.ts` | `/plan list`: the notice text and the docked index screen (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). |
-| `feedback.ts` | Browser-comment codec: `stripFeedback`, `parseFeedback`, `formatFeedback`, `feedbackSummary`, and payload validation. |
-| `web.ts` | `createPlanWebReview`: the review session (SSE close detection, the body cap, settle-after-flush, abort) over the shared loopback bind, writer, and close. |
-| `web-router.ts` | Pure request handler: token/`Host`/method checks and the review routes, over the shared page and JSON header sets. |
-| `web-page.ts` | The review page shell (header, reading progress, review facts, section outline, shortcut sheet, approve confirmation), its data island, and inline CSS. |
-| `web-client.ts` | The `/client.js` source: state and wiring (comment rail, comments, selection quotes, save/approve/back, keyboard nav) over the two fragments below. |
+| `feedback.ts` | Comment codec: authored markers, `stripFeedback`, `parseFeedback`, `formatFeedback` (writer-scoped), `displayFeedback`, `carryFeedback`, `resolveAnchor`, `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 the shared bind, writer, and close. |
+| `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-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's lifecycle: 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-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, reading progress, and the stream's lifetime (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`). |
 | `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. |
 | [`../../lib/shell.ts`](../../lib/shell.ts) | The shell-escape rule the read-only git guard shares with the worktree isolation guard. |
 | [`../../lib/highlight.ts`](../../lib/highlight.ts) | First-party escape-first syntax tokenizer (shared with `file-browse`). |
+| [`../../lib/qr.ts`](../../lib/qr.ts) | QR matrix, terminal half-blocks, and inline SVG for the share link (shared with `wechat`). |
+| [`../../lib/http/`](../../lib/http/) | The bind, `Host` allowlist, header sets, and response kit both browser surfaces serve through. |
 | [`../../lib/web/index.ts`](../../lib/web/index.ts) | Shared Bytefly web brand system: tokens, base rules, `tok-*` colors, layout, the bootstrap, the toggle wiring, the shortcut sheet (`keysSheet`, `keysDialogScript`), and shared markup. |
 | [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `file-browse`: the page policy and header sets, `ServeResponse`, the request-envelope helpers, bind/respond/close. |
 | `../../lib/policy.ts` | Shared read-only capability policy (default-deny + `readOnlyHint`). |