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

package/{extensions/plan/README.md → docs/extensions/plan.md}

@@ -6,13 +6,70 @@ but the only thing it may write is the plan file itself. The plan is saved under
 the agent directory; the user reviews that file, and it is the artifact the model
 executes.
 
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+### Planning lifecycle
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Read-only planning | `enter_plan_mode`, `/plan`, `Ctrl+Alt+P`, `--plan` | The session keeps only its readers, so the model investigates and proposes without touching the tree. | Shipped |
+| Confirmed model entry | `enter_plan_mode` | The model asks before it takes write access away, and the user answers first. | Shipped |
+| Read-only git shell | `bash` with the read-only git allowlist | Plan mode can inspect `git status`, `diff`, `log`, and `show`; pipes, redirects, and non-git commands are refused. | Shipped |
+| Read-only delegation | `subagent` with forced `readOnly: true` | A delegated agent can read and search but cannot write, edit, or run a shell while the plan is being researched. | Shipped |
+| Absolute-path guard | `path-guard.ts` | A path outside the project is refused unless it is a known plan-safe reader, so planning cannot write through an absolute path. | Shipped |
+| 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; 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 |
+| Plans index | `/plan list` | Every saved plan with its title, modified time, and step progress, newest first, under a header naming the store's size and its oldest plan. | Shipped |
+| Plan-store migration | `<repo>/.pi/plans` to the agent-dir store | A store left by an older version is moved in once, with a notice, so worktrees and main see the same index. | Shipped |
+| Instruction-file bootstrap | `/skill:init` | The packaged `init` skill plans and gates a project's `AGENTS.md`, writing only after approval. | Shipped |
+| Branch-following mode | the `plan-mode` session entry | `/resume` and `/tree` restore the mode and its tool set for the branch they land on. | Shipped |
+
+### Review
+
+| 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. | 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 |
+| 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 |
+
+### Collaboration
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Shared review | `/plan share`, **Share** | A reviewer link, with a QR a phone can scan, opens the same plan from another machine on this Wi-Fi. | Shipped |
+| One link per teammate | **New link**, **Revoke**, `/plan share stop` | Each teammate holds a link of their own, and one is revoked without disturbing the rest. | Shipped |
+| Two roles | the owner's `token`, a reviewer's link | Only the owner saves, approves, cancels, and manages links; a reviewer reads and comments. | Shipped |
+| Signed comments | the page's `name` control | A reviewer's name binds to her link on its first post, so her notes are hers and the file records who wrote them. | Shipped |
+
+## Quickstart
+
 ```bash
 pi --extension ./extensions/plan   # load just this extension
 pi -e .                            # load the whole @gavin-hu/my-pi-agent package
-pi --plan                          # start in plan mode
+pi install ./                      # install the package for a user
+```
+
+```text
+/plan                                       # toggle plan mode
+/plan add rate limiting to the public API   # enter plan mode and send the task
 ```
 
-## Tool rendering
+The model calls `enter_plan_mode` before a non-trivial task; `/plan` and
+`Ctrl+Alt+P` are the user's own switch.
+
+## Tools
 
 How the `write_plan` and `exit_plan_mode` calls and their results look in the transcript — the call line as a headline and the body indented under it:
 
@@ -20,207 +77,173 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
 
 <img src="../../assets/tools/exit_plan_mode.png" alt="The exit_plan_mode tool's call and result: the call line and an indented body with the approval line and the approved plan preview" width="100%">
 
-## What it does
-
-- **Read-only gating, with one exception.** Tools that are not read-only are
-  removed from the active set or blocked. `write` and `edit` are hidden, raw
-  shell is limited to read-only git commands through `bash` (chained with
-  `&&`/`;`), `powershell` is blocked outright, and other mutating tools (worktree
-  mutations, MCP tools) are blocked until you exit plan mode. `subagent` stays
-  active but is forced read-only. The only permitted write is the plan control
-  tool `write_plan`, which can only create or overwrite markdown plan files
-  directly inside the plans directory — never dotfiles and never through a
-  symlink. Classification defaults to *deny* and is driven by the shared
-  [`lib/policy.ts`](../../lib/policy.ts), so unknown tools are safe by default
-  and the MCP `readOnlyHint` is the only thing that opens one up. A refused
-  shell command explains the fix: the working directory is already the project
-  root (so `cd` is unnecessary), and files belong to the `read`, `grep`, `find`,
-  and `ls` tools.
-- **Model entry point.** The model can call `enter_plan_mode` to ask for plan
-  mode before a non-trivial task; the user confirms.
-- **AGENTS.md bootstrap.** The packaged `init` skill (`/skill:init`) enters plan
-  mode, reconnoiters the repository, runs one built-in interview of at
-  most four questions, creates or updates `AGENTS.md`, gates the draft through a
-  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, 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
-  notice with each plan's path. The directory stays the index: no registry file,
-  one bounded read per plan.
-- **A shape that reads.** `write_plan` documents a canonical outline — a
-  `# <Title>`, then `## Goal`, `## Context`, `## Approach`, `## Visual`,
-  `## Steps`, `## Risks`, and `## Verification` — and the model is guided to
-  follow it. Every example in the template is the shape wanted rather than a
-  description of it, and each section has one job: the goal is one sentence, the
-  context is the facts that force the approach, the approach names the
-  alternative it rejected, and verification is a fence of the commands to run.
-  `Visual` carries the end state in an untagged fence, with one line naming what to
-  look at: the same surface before and after when the change alters one that
-  already exists, one frame when the surface is new, because a reviewer judges the
-  result before the steps that build it; a change with no visible surface drops it.
-  The description calls the shape a guide rather than a form: `Context`,
-  `Approach`, `Visual`, and `Risks` are dropped when they have nothing to say,
-  while `Steps` and `Verification` are kept, because the steps are read from that
-  section (without it, the shallowest list anywhere becomes the steps) and
-  Verification becomes the last todo item. Within `Steps` only the shallowest
-  list is tracked, so nested bullets stay notes instead of becoming todos. This
-  is guidance only: any markdown is accepted, stored, and rendered as written,
-  and a refinement is asked to keep its section headings so the review can still
-  mark only what changed.
-- **Trackable steps.** Steps are written as `- [ ]` checkboxes in the `## Steps`
-  section; approval seeds them into `todo`, with the `## Verification` section as
-  the last item so the definition of done travels with the work. A plan with more
-  than 50 top-level steps is refused rather than truncated, so approval never
-  drops a step you reviewed.
-- **A navigable review.** The review screen splits the body at its headings,
-  names the section you are in, and jumps between sections with `n`/`p`.
-- **What changed since the last review.** After a refinement, the review screen
-  names how many sections changed, marks the current one in the scroll row, and
-  the browser outline dots each changed section, so a re-review does not mean
-  re-reading the whole plan. The baseline is one digest per heading section of
-  what the previous review showed, kept as a session entry, so a resumed session
-  or a `/tree` restore marks only what changed on its own branch.
-- **Kept current.** After approval, `set_plan_steps` flips the checkboxes of
-  the steps you name in the file, so the plan mirrors what has actually been
-  done, and ticks the todo item approval seeded from that step with it, so the
-  widget and the plan do not drift apart. Pass the step's text as `expected` and
-  an update whose step number moved is refused instead of ticking the wrong line.
-- **Reviewable plan.** `exit_plan_mode` reads the plan file back and presents
-  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 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
-  comment rail in
-  the left margin, and live section and step progress — the step count comes from
-  the same `Steps` section list approval seeds. Select text to leave an
-  inline comment, and save them back into the plan file itself as
-  `> [!REVIEW]` lines. Saved comments return to the model as a refinement
-  request.
-- **The file is the source of truth.** On approval the model follows the plan
-  file's steps; refinements rewrite the same file (`write_plan` with
-  `plan_path`), so the reviewed artifact is the executed artifact.
-- **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 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
-  cap. A plan without a `Steps` heading keeps the older rule —
-  the shallowest list in the document — so prose bullets in a plan that follows the
-  outline never become todos, and its verification bullets are already covered.
-  Each seeded item is matched back to its step by text, so ticking a step with
+All five tools are `executionMode: "sequential"` and closed-world. Two are active
+in normal mode and three are `defaultActive: false`, so the plan-mode tool set
+stays small.
+
+| 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. |
+| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. |
+| `cancel_plan_mode` | plan mode | Leave plan mode without a plan file or a review. Empty schema. |
+| `set_plan_steps` | normal mode | Set the checkboxes of the given top-level steps of an approved plan in one write, and their todo items with them. |
+
+### `enter_plan_mode`
+
+No parameters. It confirms with `ctx.ui.confirm` before switching the tool set,
+because the model is changing the mode on the user's behalf; a declined confirm
+answers "stayed in normal mode" and the session keeps write access. Already
+planning, it says so. With no UI it fails with an actionable message instead of
+deciding for the user.
+
+On a remote turn the confirmation is a short consent sentence in the peer's
+language, and the notice names how to leave.
+
+### `write_plan`
+
+`title` is the file-name slug, `content` the full markdown, and `plan_path`
+overwrites an existing plan when refining. The result carries the absolute path,
+the relative path, and the byte count — the absolute path is what `exit_plan_mode`
+takes.
+
+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.
+
+The description documents a canonical outline — a `# <Title>`, then `## Goal`,
+`## Context`, `## Approach`, `## Visual`, `## Steps`, `## Risks`, and
+`## Verification` — and the model is guided to follow it. Every example in the
+template is the shape wanted rather than a description of it, and each section
+has one job: the goal is one sentence, the context is the facts that force the
+approach, the approach names the alternative it rejected, and verification is a
+fence of the commands to run. `Visual` carries the end state in an untagged
+fence, with one line naming what to look at: the same surface before and after
+when the change alters one that already exists, one frame when the surface is
+new, because a reviewer judges the result before the steps that build it; a
+change with no visible surface drops it. The description calls the shape a guide
+rather than a form: `Context`, `Approach`, `Visual`, and `Risks` are dropped when
+they have nothing to say, while `Steps` and `Verification` are kept, because the
+steps are read from that section (without it, the shallowest list anywhere
+becomes the steps) and Verification becomes the last todo item. Within `Steps`
+only the shallowest list is tracked, so nested bullets stay notes instead of
+becoming todos. This is guidance only: any markdown is accepted, stored, and
+rendered as written, and a refinement is asked to keep its section headings so
+the review can still mark only what changed.
+
+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.
+
+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 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`
+
+`plan_path` names the file `write_plan` returned; the tool reads it back and
+presents it for approval. A hand-edited or older file whose step list is over the
+cap is refused before the review screen. 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. The review also offers
+**Exit plan mode (discard)**, which leaves plan mode without approving.
+
+On approval, plan mode ends, write access returns, and the plan's steps go into
+the todo list:
+
+- Steps are the top-level numbered/bulleted items of the plan's `Steps` section,
+  and approval records them with the `todo` tool (via `ctx.executeTool`). Steps
+  marked `- [x]` (or `[DONE:n]`) seed as completed, nested sub-bullets are notes,
+  and 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 cap.
+- A plan without a `Steps` heading keeps the older rule — the shallowest list in
+  the document — so prose bullets in a plan that follows the outline never become
+  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.
-- **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 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 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.
+- 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
+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 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.
+
+### `cancel_plan_mode`
+
+Leaves plan mode without a plan file or a review. Restores write access, records
+no todo items or goal, and keeps any saved plan. Empty schema.
+
+### `set_plan_steps`
+
+Keep an approved plan current: `plan_path`, plus `updates`, each a 1-based `step`
+in the order `exit_plan_mode` listed, a `status` of `pending` or `completed`, and
+`expected` — the step's text, so an update whose step number moved is refused
+instead of ticking the wrong line. It is a single all-or-nothing write: a step out
+of range, or an `expected` text that no longer matches the file, refuses every
+entry. 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 reported as
+unmatched, and a failed todo write is reported in the result. The tool refuses
+while plan mode is on — refine the plan with `write_plan` instead.
 
-```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"] }
-  ]
-})
-```
+### Transcript
 
-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:
+The three tool rows reuse the transcript component, and `exit_plan_mode`
+separates the plan body from its header with a blank line; the collapse hint
+binds to `app.tools.expand` (`ctrl+o` by default).
 
-```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"})
+```
+enter_plan_mode requested plan mode
+✓ Plan mode enabled
 ```
 
-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:
+```
+write_plan Add rate limiting
+✓ Saved plan ~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
+```
 
-| 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.
+```
+exit_plan_mode submitted a plan
+✓ Plan approved
+~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
 
-## Tools
+# Add rate limiting
+1. Add a token bucket …
 
-| 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. 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. |
+… 12 more lines (ctrl+o to expand)
+```
 
-### Commands and flags
+## Commands and flags
 
 | Path | Who starts it | Confirmation |
 |---|---|---|
@@ -229,6 +252,7 @@ terminal review is where a split is approved.
 | `/plan <prompt>` | the user, with the task | immediate |
 | `/plan list` | the user, browsing the plans directory | immediate |
 | `/plan review [path]` | the user, reviewing a plan in the browser | immediate |
+| `/plan share [stop]` | the user, handing the review to a teammate | immediate |
 | `/plan cancel` | the user, leaving plan mode without approving | immediate |
 | `/skill:init` | the user, creating or updating `AGENTS.md` | enters plan mode; write waits for plan approval |
 | `Ctrl+Alt+P` | the user | immediate |
@@ -248,13 +272,29 @@ the toggle that works in every terminal (for example Zed's integrated terminal,
 which does not forward `Ctrl+Alt+P`). The footer shows `≡ plan` while plan mode
 is on, and `≡ plan · <plan-file>` once the model has written a plan.
 
-`/plan review` is the one reserved subcommand. 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 —
-`review the auth flow` — is still treated as a planning task, so the subcommand
+`/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 notice with each plan's
+path. The header carries the store's own footprint for this repository: the bytes
+its plans hold and how old the oldest one is, both derived from the walk that just
+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 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
+— `review the auth flow` — is still treated as a planning task, so the subcommand
 never swallows one.
 
+`/plan share` prints the reviewer link and its QR, and `/plan share stop` revokes
+every link; the page's **Share** button does the same. With no browser review open
+it says so and points at `/plan review`. `/plan cancel` leaves plan mode without
+approving, exactly like `cancel_plan_mode`: write access returns and the plan file
+stays for a later review. Both are exact words — `share the tokens` and `cancel
+that idea` stay tasks — as is `list`.
+
 ### `/skill:init`
 
 `/skill:init` loads the packaged `init` skill. The skill enters plan mode itself
@@ -300,51 +340,53 @@ The quality reference is
 [`skills/init/references/agents-md-quality.md`](../../skills/init/references/agents-md-quality.md).
 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.
+file can produce a no-op plan, and an empty repository gets only known facts. It
+never invents commands.
 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
 `./extensions/plan` leaves `/skill:init` unavailable.
 
+## Routes
+
+The browser review serves these routes on its loopback origin; `…` is the
+session token, and the owner's token is the one that opened the page.
+
+| 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: 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 |
+
 ## Behaviour by mode
 
-The review screen is TUI-only. `exit_plan_mode` opens `PlanViewComponent`: a
-scrollable, width-safe view of the plan with approve/refine/keep/exit in the footer.
-The body is rendered with Pi's own `Markdown` component and `getMarkdownTheme()`,
-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` 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 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
-the next or previous heading; the scroll row names the current section when the
-plan has more than one. When the plan overflows,
-a gauge row above the hints shows the scroll position, the percent, and the
-visible line range (the range drops first on a narrow terminal); the gauge comes
-from the design system's `gaugeBar` and stays
-visible while the refine editor is open, since the body above is still clipped.
-Hints are
-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/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.
+The review screen is TUI-only: `exit_plan_mode` opens `PlanViewComponent`, and `w`
+on it opens the browser review. RPC and other non-interactive runs get no screen.
+
+Dialog-capable non-TUI modes (RPC/WeChat) use one editor prompt instead: on a
+remote turn the plan file is sent first, then a compact prompt carrying the
+title, step count, first steps, mode status, and three actions — `1` approve,
+`2` keep planning, `3` exit. If the upload fails, the plan's text is sent
+instead. Any other reply is a 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`. Without any UI the tools fail with an actionable message instead of
+deciding for the user.
+
+`/plan list` is a docked list screen in the TUI and a notice with each plan's
+path everywhere else; both name the store's size and its oldest plan. The dock is
+the list's alone while it is open — the goal and todo rails hide, as they do for
+the other list screens — and the screen counts its own frame, so a full list keeps
+its closing rule on a short terminal.
 
 Browser review is a local-turn feature: the server binds `127.0.0.1`, so a remote
 (WeChat) turn cannot reach it and `/plan review` there refuses with a notice
@@ -356,49 +398,35 @@ Aborting the turn closes a browser review. `exit_plan_mode` forwards the call's
 abort signal to the review server, so an aborted turn returns "not approved"
 and stops listening instead of waiting on a page nobody is watching.
 
-### Transcript
-
-The three tool rows reuse the transcript component, and `exit_plan_mode`
-separates the plan body from its header with a blank line; the collapse hint
-binds to `app.tools.expand` (`ctrl+o` by default).
-
-```
-enter_plan_mode requested plan mode
-✓ Plan mode enabled
-```
-
-```
-write_plan Add rate limiting
-✓ Saved plan ~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
-```
-
-```
-exit_plan_mode submitted a plan
-✓ Plan approved
-~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
-
-# Add rate limiting
-1. Add a token bucket …
-
-… 12 more lines (ctrl+o to expand)
-```
-
 ## Security
 
 Plan mode is a **guard rail, not a sandbox**: extensions run with Pi's OS
 permissions, so it prevents accidental writes while planning, not a hostile
 command. The read-only guarantee is layered:
 
+- **Tool set at entry.** Tools that are not read-only are removed from the active
+  set or blocked. `write` and `edit` are hidden, raw shell is limited to read-only
+  git commands through `bash` (chained with `&&`/`;`), `powershell` is blocked
+  outright, and other mutating tools (worktree mutations, MCP tools) are blocked
+  until you exit plan mode. `subagent` stays active but is forced read-only. The
+  only permitted write is the plan control tool `write_plan`, which can only
+  create or overwrite markdown plan files directly inside the plans directory —
+  never dotfiles and never through a symlink.
 - **Capability policy.** A tool is allowed only when it is a known structured
   reader or declares the MCP `readOnlyHint`; `write`, `edit`, and unknown
-  mutators are denied.
+  mutators are denied. Classification defaults to *deny* and is driven by the
+  shared [`lib/policy.ts`](../../lib/policy.ts), so unknown tools are safe by
+  default and the MCP `readOnlyHint` is the only thing that opens one up.
 - **Path backstop.** A `readOnlyHint` is only a claim, so a tool that takes a
   file path is refused unless it is a known plan-safe reader. `path-guard.ts`
   scans nested arguments and path-shaped values, not just fixed top-level keys.
-- **Control-tool identity.** The `tool_call` guard exempts `write_plan` /
-  `exit_plan_mode` only when the registered tool is this extension's own,
-  matched by source path, so a same-named tool from another extension cannot
-  borrow the exemption.
+- **Control-tool identity.** The `tool_call` guard exempts plan's own tools —
+  `enter_plan_mode`, `cancel_plan_mode`, `write_plan`, and `exit_plan_mode` — only
+  when the registered tool is this extension's, matched by source path, so a
+  same-named tool from another extension cannot borrow the exemption.
+  `enter_plan_mode` is exempted so a call already in flight when plan mode came on
+  is answered with "Already in plan mode" instead of being refused as not
+  read-only; the policy still denies it, so it stays hidden while planning.
 - **Contained writes.** `write_plan` only writes markdown non-dotfiles whose
   real parent resolves inside the plans directory, and every plan write —
   create, refine, `set_plan_steps`, browser feedback — goes through a hidden
@@ -428,9 +456,10 @@ conservative allowlist in `git-bash.ts`. `powershell` is not allowed at all, so
 plan mode uses Git Bash on native Windows: the same read-only git commands work
 there, and a backslash before an ordinary character is accepted as a Windows
 path separator while a backslash that escapes a metacharacter is still refused.
-Everything else uses `read`, `grep`, `find`,
-`ls`, and the other read-only tools already available (`web_search`,
-`web_fetch`, `ask_user_question`, `todo`, `goal`).
+Everything else uses the structured readers — `read`, `grep`, `find`, `ls`, and
+`read_doc` for a PDF, Word, OpenDocument, RTF, or Excel file — and the other
+read-only tools already available (`web_search`, `web_fetch`,
+`ask_user_question`, `todo`, `goal`).
 
 ```bash
 git status && git diff --stat     # allowed: two read-only git commands
@@ -441,6 +470,10 @@ git status | sh                   # blocked: pipes are never allowed
 git diff > out.patch              # blocked: redirection is a write
 ```
 
+A refused shell command explains the fix: the working directory is already the
+project root (so `cd` is unnecessary), and files belong to the `read`, `grep`,
+`find`, and `ls` tools.
+
 A string parser can never be the boundary, so capability gating replaced the
 earlier segment-based command allowlist. The git shell guard is a narrow,
 deliberate exception — an allowlist over read-only git command shapes, not a
@@ -452,7 +485,7 @@ first or wait for approval.
 While planning, `subagent` stays available but every call is **forced
 read-only**. Plan mode sets `readOnly: true` on the call in the `tool_call`
 guard, and `subagent` in turn gives each spawned agent a reader-only `--tools`
-list (`read`, `grep`, `find`, `ls`, `web_search`, `web_fetch`). The child
+list (`read`, `grep`, `find`, `ls`, `read_doc`, `web_search`, `web_fetch`). The child
 process enforces it, so a delegated `explorer`, `researcher`, or even `worker`
 cannot write, edit, or run a shell — regardless of its prompt or an external
 agent file that overrides it.
@@ -472,24 +505,54 @@ agent file that overrides it.
 
 ## Review screen
 
-<img src="../../assets/plan.png" alt="The terminal plan review: a Plan Review title rule, a notice that one section changed since the last review, the plan body with its headings and ◼/◻ task checkboxes, a scroll gauge naming the current section and the visible line range, and the Esc/a/r/w, scroll, and section-jump hints" width="100%">
+<img src="../../assets/screens/plan.png" alt="The terminal plan review: a Plan Review title rule, a notice that one section changed since the last review, the plan body with its headings and ◼/◻ task checkboxes, a scroll gauge naming the current section and the visible line range, and the Esc/a/r/w, scroll, and section-jump hints" width="100%">
 
 `exit_plan_mode` opens this screen on the plan file it just wrote. The body is
-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` asks
-`y/N` and then approves and runs, `r` refines inline, and `w` opens the browser
-review below.
+rendered with Pi's own `Markdown` component and `getMarkdownTheme()`, so
+headings, lists, inline code, code blocks, links, and quotes carry the active
+theme's colours; task items get the shared `◼` (done) or `◻` (pending) marker,
+like the bytefly screen and the question dialog. 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.
+
+- **Actions.** The footer colours the primary actions (`a approve & run` in
+  `success`, `r refine` in `accent`). `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; `w` opens the browser review.
+- **Sections.** The screen splits the body at its headings, names the section you
+  are in, and jumps between sections with `n`/`p`; the scroll row names the
+  current section when the plan has more than one.
+- **What changed since the last review.** After a refinement, the screen names
+  how many sections changed, marks the current one in the scroll row, and the
+  browser outline dots each changed section, so a re-review does not mean
+  re-reading the whole plan. The baseline is one digest per heading section of
+  what the previous review showed, kept as a session entry, so a resumed session
+  or a `/tree` restore marks only what changed on its own branch.
+- **Scrolling.** `↑`/`↓` or `j`/`k`, `space`/`b` or `PgUp`/`PgDn`, `d`/`u`,
+  `g`/`G`, and the mouse wheel. When the plan overflows, a gauge row above the
+  hints shows the scroll position, the percent, and the visible line range (the
+  range drops first on a narrow terminal); the gauge comes from the design
+  system's `gaugeBar` and stays visible while the refine editor is open, since the
+  body above is still clipped.
+- **Narrow widths.** Hints are 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.
 
 ## 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 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%">
+<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
@@ -500,7 +563,7 @@ text first to quote it. **Save feedback** writes the comments into the plan
 file and returns them to the model.
 
 - **Shared theme.** The page uses the same Bytefly tokens, base rules, and
-  syntax-token colors as `file-browse` (`lib/web/`), follows the system light/dark
+  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
   choice under the shared `pi-web-theme` key.
 - **One content column, one rail.** The document is GitHub's Markdown content
@@ -556,10 +619,11 @@ file and returns them to the model.
 - **Highlighted code.** Fenced code is tokenized by the shared
   `lib/highlight.ts`; the client copies only text and `tok-*` spans through
   `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
@@ -568,10 +632,18 @@ file and returns them to the model.
 - **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.
+  a step keeps the comments apart; then the block whose wording still overlaps it —
+  half the longer block's words — so a reworded step keeps its note, and a step
+  that shifted down under an inserted one keeps it too; then the gap it left
+  between the steps that survived; then the last block that section still has. A
+  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. 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
@@ -594,20 +666,7 @@ file and returns them to the model.
   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: 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 |
+The routes it serves are in [Routes](#routes).
 
 ## Shared review
 
@@ -672,6 +731,12 @@ both.
   Git Bash (`bash`), which must be installed for any shell command to run.
 - The read-only guarantee is a guard rail against accidental writes, not a
   security boundary (see [Security](#security)).
+- **A carried comment's new home is a guess, and only the page says so.** A note a
+  refinement could not pin to surviving text is placed by wording overlap, by the
+  gap it left, or at the plan's last block; the `moved` chip is what tells a
+  reviewer that. A reader of the plan file alone sees `> [!REVIEW moved]`, and the
+  terminal review shows the comment as a quote with no chip, so the marker is the
+  fact and the chip is one reader's way of showing it.
 - The plans directory is the only index. `/plan list` walks it on every open and
   keeps no registry, so it sees an external edit or a hand-copied plan
   immediately; it lists a file over the 256 KiB plan limit without reading it,
@@ -716,9 +781,9 @@ both.
 
 | Integration point | How |
 |---|---|
-| 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 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. |
+| Tools | `enter_plan_mode` (active; `readOnlyHint: true`), `write_plan` (`defaultActive: false`; `readOnlyHint: false`, `destructiveHint: true`), `exit_plan_mode` (`defaultActive: false`; `readOnlyHint: true`), `cancel_plan_mode` (`defaultActive: false`; `readOnlyHint: true`), `set_plan_steps` (active; `readOnlyHint: false`, `idempotentHint: true`). All five are `executionMode: "sequential"` and closed-world, and the read-only policy default-denies `set_plan_steps` while planning. Each returns typed `details` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `CancelPlanModeDetails`, `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), `/plan share [stop]` (reviewer link), `/plan cancel` (leave without approving), `/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 })` when the `goal` tool is registered: 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. |
@@ -861,43 +926,96 @@ both.
 | File | Responsibility |
 |---|---|
 | `index.ts` | Wiring: tools, command, flag, shortcut, events, context injection. |
-| `types.ts` | `PlanModeEntry`, `EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`. |
+| `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 (pure): the outline, step extraction and the `Steps`-section scope, heading sections, the plan's own goal (`goalSection`), and the checkbox edit. |
+| `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. |
 | `format.ts` | Pure result/approval text: the plan preview, the step-cap diagnosis, step labels, the merge summary, and the verification note. |
-| `plan-text.ts` | The plan text a review shows and compares: `sanitizePlanText`, the one normalization both sides use, the per-section `sectionDigests`, and `changedSections`. |
+| `plan-text.ts` | The plan text a review shows and compares: `sanitizePlanText`, the one normalization both sides use, the per-section `sectionDigests`, and `changedSections`, which hands each section back with its flag. |
 | `runtime.ts` | Enabled state, tool gating, persistence (mode and review baseline), control-tool identity, footer status. |
-| `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). |
+| `tools.ts` | Registration entry: composes the five tool registrations in the order the session sees them. |
+| `tools/` | One module per tool (`enter.ts`, `write.ts`, `exit.ts`, `cancel.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), `/plan review [path]`, and `/plan share [stop]`. |
+| `review-prompt.ts` | Pure rendering and parsing for the compact remote review: one action table behind both the prompt and the reply parser. |
+| `commands.ts` | `/plan` (enter, optional task), `/plan review [path]`, `/plan list`, `/plan share [stop]`, and `/plan cancel`. |
 | `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` | 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. |
+| `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-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-share-session.ts` | The shared listener: its bound address, the link table over the session's tokens, `ShareState`, and invite/revoke/stop/close, injected with the request handler, role map, and frame hooks. |
+| `web-keys.ts` | The client's keyboard as typed source (`WEB_KEYS_JS`): `handleKey` — Esc peels the composer before closing, a field and the shortcut sheet own their keys, and `s` is the write the page offers — and `rememberSelection`, which keeps the text a reader selected as the next comment's quote. |
+| `web-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. |
 | [`../../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/http/`](../../lib/http/) | The one loopback server entry, 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`). |
 | `../../lib/tui/chrome.ts` | Shared screen header, viewport-row helper, and styled key-hint footer. |
+
+## Testing
+
+```bash
+bun test extensions/plan
+```
+
+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
+  step extraction.
+- `feedback.test.ts` — the comment codec: authored markers, stripping and
+  parsing, who a reviewer's write is signed by, carrying feedback onto a
+  revision, and displaying stored comments.
+- `tools.test.ts` — registration and all five tools, the approval merge into
+  `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-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
+  review gate shared by `exit_plan_mode` and the browser, including the abort and
+  baseline rules.
+- `runtime.test.ts` — tool gating, persistence and status, control-tool identity,
+  the review baseline, branch restore, the read-only git allowlist, and the
+  path-argument scan.
+- `tui.test.ts` — the review screen at fixed widths: Markdown body, scrolling,
+  section navigation, the gauge, footer hints, the approve question, the inline
+  refine editor, and the changed-section markers.
+- `sections.test.ts` — the fence-aware scan: heading shape, fences, the preamble,
+source lines and levels, and the occurrence key.
+- `extension.test.ts` — the Pi wiring: registration, the entry request, the
+  session lifecycle, the tool-call guard, injected context, the command, and the
+  shortcut.