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

package/README.md

@@ -36,7 +36,8 @@ want the agent to *think first and work safely*:
   plan file that the agent then follows step by step.
 - **Delegate and parallelize.** Run specialist subagents in their own Pi
   processes, push a long build into a background job, and let a watcher tail a
-  log until it matters — all while you keep the thread.
+  log until it matters — then run several sessions on one repository through a
+  shared bus, each owning its slice, all while you keep the thread.
 - **Never wreck the checkout.** Isolation is one command: the task moves onto its
   own branch in a `git worktree`, and every prompt is snapshotted so a bad turn
   is one `/rewind` away.
@@ -47,7 +48,7 @@ want the agent to *think first and work safely*:
   through a bridge to the live session.
 
 Everything is optional and independently toggleable. Nothing is forked, and no
-installed Pi file is modified: Pi discovers the resources through the `pi`
+installed Pi file is written to: Pi discovers the resources through the `pi`
 manifest in [`package.json`](./package.json), so the package upgrades with Pi
 like any other.
 
@@ -86,7 +87,8 @@ Then, from inside Pi:
 - `/bytefly update` re-runs the package update check now and reports the
   updateable packages, this package's version and release URL, or a skip.
 - `/plan <task>` starts a task in read-only planning mode.
-- `/skill:init` creates or updates `AGENTS.md` through a short built-in interview and a plan you review first.
+- `/skill:init` creates or updates the instruction file Pi reads through a short
+  built-in interview and a plan you review first.
 
 One thing the pack does on its own: once per interactive session, `bytefly`
 asks Pi's package manager which configured packages are behind, suppresses Pi's
@@ -99,14 +101,14 @@ and `PI_OFFLINE` skips the check;
 
 ## What you get
 
-18 extensions, 3 packaged skills, and 2 themes, grouped by what you are trying
+19 extensions, 5 packaged skills, and 2 themes, grouped by what you are trying
 to do. Each extension's own `README.md` has the full tool and command surface.
 
 ### Plan and delegate
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `cancel_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | Read-only planning: the model investigates, saves a plan under `.pi/plans`, and you approve it before anything is written. Review in the TUI, or open it in a browser to leave inline comments. The `init` skill uses the same review to create or update a project's `AGENTS.md`. |
+| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `cancel_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | Read-only planning: the model investigates, saves a plan under `~/.pi/agent/plans/<repo-key>` — one store per repository, shared by its worktrees — and you approve it before anything is written; with `plan.split` on, the approval can also split it into slices that separate sessions join by name. Review in the TUI, or open it in a browser to leave inline comments: the page follows the plan file live, and you can hand one reviewer link per teammate so each comments under their own name. The `init` skill uses the same review to create or update a project's `AGENTS.md`. |
 | [`check`](./extensions/check/) | `run_check`, `/check` | Detect the project's test, lint, or typecheck command (or take `check.command`), run it in a supervised process, and turn failures into a navigable `file:line` list. |
 | [`subagent`](./extensions/subagent/) | `subagent`, `/agents` | Delegate a task to a specialist agent (`explorer`, `planner`, `reviewer`, `worker`, `researcher`, `tester`, `debugger`, `documenter`) in its own Pi process — single, parallel, chained, or in the background, with a footer chip while it runs and a finish notice. |
 | [`todo`](./extensions/todo/) | `todo`, `/todos` | A persistent task list (`pending` / `in_progress` / `completed`) with a one-line widget. |
@@ -114,6 +116,7 @@ to do. Each extension's own `README.md` has the full tool and command surface.
 | [`question`](./extensions/question/) | `ask_user_question` | Ask you one or more structured questions (labelled options plus free-form "Other") and wait. |
 | [`job`](./extensions/job/) | `job`, `/jobs` | Run long-lived shell commands in the background; inspect logs, wait, or kill them. |
 | [`watch`](./extensions/watch/) | `watch`, `/watch` | Tail a file or command output, match lines against patterns, and alert you or hand matching lines to the agent. |
+| [`session-bus`](./extensions/session-bus/) | `session`, `/sessions` (screen) | Coordinate parallel Pi sessions on one repository: discover peers, exchange short messages/events, consume an inbox, join a slice of an approved split or claim paths before editing, with `/sessions` as a live board of peers, unread mail, and claims. Local, pull-based by default, with an opt-in inbox watch that raises this session's turn once it is idle; it never spawns an agent. |
 | [`context`](./extensions/context/) | `/context` | Show where the context window goes — system prompt, tool definitions, conversation by role, injected notes — and compact from the report with the before and after numbers. |
 
 ### Keep your work safe
@@ -129,7 +132,7 @@ to do. Each extension's own `README.md` has the full tool and command surface.
 | Extension | Tools and commands | What it does |
 |---|---|---|
 | [`web-access`](./extensions/web-access/) | `web_search`, `web_fetch` | Search the web (keyless DuckDuckGo by default, optional SearXNG or Brave) and fetch a page as readable text, with paging, `find`, per-hop SSRF checks, and optional PDF support. |
-| [`file-browse`](./extensions/file-browse/) | `/browse` | Start a loopback, read-only file browser rooted at the working directory, with Markdown preview, a fuzzy quick-open palette, and live status for a page left open. |
+| [`file-browse`](./extensions/file-browse/) | `/browse` | Start a loopback, read-only file browser rooted at the working directory, with Markdown preview, a fuzzy quick-open palette, a `path:12-30` reference copied from a selection, live status for a page left open, and a reload hint when the folder it lists changes. |
 | [`file-read`](./extensions/file-read/) | `read_doc` | Extract text from a local PDF, DOCX, DOC, ODT, RTF, or XLSX in process, paged. |
 | [`file-open`](./extensions/file-open/) | `/open`, `open_path` | Open or reveal a file or directory in the OS-native application. |
 | [`wechat`](./extensions/wechat/) | `/wechat`, `send_wechat` | Bridge a WeChat chat to the live session over the Weixin iLink bot API; inbound text, images, and files become turns. |
@@ -148,10 +151,11 @@ advertised to the model, and its instructions load only when the task matches
 
 | Skill | What it does |
 |---|---|
-| [`init`](./skills/init/SKILL.md) | Creates or updates a project's `AGENTS.md` through a built-in interactive interview and plan review, from repository evidence. |
+| [`init`](./skills/init/SKILL.md) | Creates or updates the instruction file Pi actually reads (`AGENTS.md`, or `AGENTS.override.md` when it shadows it) through a built-in interactive interview and plan review, deriving commands, generated paths, packages, and purpose from repository evidence. |
 | [`refactor`](./skills/refactor/SKILL.md) | Audits a project or path for refactoring opportunities: duplication, oversized modules, coupling, drift, and high-churn code with weak tests. Returns a ranked shortlist with evidence and verification commands; discovery is read-only. |
 | [`changelog`](./skills/changelog/SKILL.md) | Records one user-visible bullet in the same commit as the change, audits commits since the last tag for missing or weak entries, and curates a release section from the project's own rules. |
-| [`next`](./skills/next/SKILL.md) | Triages what to do next — loose work, a broken or unfinished promise — from the tree or from this conversation (`/skill:next session`), with the words and a path after the command saying what to ask and where to look. Read-only, and capped at a short ranked list with evidence and the command that starts each. |
+| [`parallel-dev`](./skills/parallel-dev/SKILL.md) | Runs parallel development as a lead and a team: a lead accountable for the contract, shared files, merge order and a green baseline who also owns a workstream, one owner per disjoint workstream, a walking skeleton first, advisory path claims, a turn-boundary protocol, and independent verification. |
+| [`next`](./skills/next/SKILL.md) | Suggests the next todos by priority — loose work, a broken or unfinished promise — from this conversation once it has done work, and from the tree only when it is empty, with the words and a path after the command saying what to ask and where to look. Read-only, and capped at a short numbered list with evidence and the command that starts each. |
 
 ### Themes
 
@@ -174,6 +178,10 @@ README use `bytefly-dark`.
 <td width="50%"><img src="assets/job.png" alt="The /jobs screen: a summary line, the job rows with status glyphs and elapsed times, and the focused job's command, cwd, and last output line" width="100%"></td>
 <td width="50%"><img src="assets/rewind.png" alt="The /rewind screen: prompt rows newest first, a diamond marking prompts with a code snapshot, and the focused prompt's snapshot detail" width="100%"></td>
 </tr>
+<tr>
+<td width="50%"><img src="assets/session.png" alt="The /sessions screen: a counts summary, session rows with unread and claim counts, the focused session's cwd, claims, and identity, and the Tab scope and watch hints" width="100%"></td>
+<td width="50%"><img src="assets/watch.png" alt="The /watch screen: a summary line and watcher rows with live match counts and the focused watcher's pattern and source" width="100%"></td>
+</tr>
 </table>
 
 ### Tool renderings
@@ -184,7 +192,7 @@ each tool's own renderer (or bytefly's generic fallback): the user nameplate and
 a notice, Pi's built-ins, and every tool this package registers. The rail glyph
 is the `chrome.rail` setting.
 
-![A full-page reference of every tool block: the user nameplate, a notice, the turn rule, Pi's read, write, edit, bash, grep, find, and ls renderers, and every package tool — todo, goal, memory, job, watch, subagent, web_search, web_fetch, read_doc, open_path, run_doctor, run_check, send_wechat, ask_user_question, the plan tools, and the worktree tools](assets/tool-renderings.png)
+![A full-page reference of every tool block: the user nameplate, a notice, the turn rule, Pi's read, write, edit, bash, grep, find, and ls renderers, and every package tool — todo, goal, memory, job, watch, subagent, web_search, web_fetch, read_doc, open_path, run_doctor, run_check, send_wechat, ask_user_question, session, the plan tools, and the worktree tools](assets/tool-renderings.png)
 
 `bun run screenshot:tools` regenerates it; `bun run screenshot:tool-pngs` writes
 one image per tool under [`assets/tools/`](./assets/tools).

package/README.zh-CN.md

@@ -33,14 +33,15 @@ Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，
 - **先规划，再执行。** 只读的规划模式把一次任务变成一份可审阅的计划文件，智能体
   随后按步骤执行。
 - **委派与并行。** 在各自的 Pi 进程中运行专职子智能体，把耗时构建交给后台任务，
-  让 watcher 盯住日志直到出现关键行 —— 你继续把握主线。
+  让 watcher 盯住日志直到出现关键行，还能让同一仓库上的多个会话通过共享总线协作、
+  各自负责自己的一摊 —— 你继续把握主线。
 - **绝不搞乱检出区。** 隔离只需一条命令：任务切到自己分支的 `git worktree` 中，
   每次提示还会生成快照，因此一次糟糕的回合只需一个 `/rewind` 就能回退。
 - **跨会话记忆。** 持久笔记以纯 Markdown 保存，可读、可改、可纳入版本控制。
 - **连通网络与文件。** 在会话内搜索、抓取、浏览、打开和读取文档与表格，还可通过桥接
   在微信里直接回答当前会话。
 
-一切都是可选的，且可独立开关。没有任何东西被分叉，也没有修改已安装的 Pi 文件：
+一切都是可选的，且可独立开关。没有任何东西被分叉，也没有写入任何已安装的 Pi 文件：
 Pi 通过 [`package.json`](./package.json) 里的 `pi` manifest 发现这些资源，因此
 该包能像其他包一样随 Pi 一起升级。
 
@@ -74,7 +75,7 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 - `/bytefly update` 立即重跑包更新检查，报告可更新的包、本包版本与 release URL，
   或跳过原因。
 - `/plan <任务>` 以只读规划模式开始一个任务。
-- `/skill:init` 通过内置的简短访谈和先审阅的计划创建或更新 `AGENTS.md`。
+- `/skill:init` 通过内置的简短访谈和先审阅的计划创建或更新 Pi 实际读取的指令文件。
 
 还有一件包会自行做的事：每次交互式会话启动时，`bytefly` 询问 Pi 的包管理器
 哪些已配置的包有更新，抑制 Pi 自己的启动更新块，并用主题化 notice 列出它们
@@ -85,14 +86,14 @@ changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不
 
 ## 包含内容
 
-18 个扩展、4 个随包技能，以及 2 个主题，按你想达成的目标分组。每个扩展自己的 `README.md`
+19 个扩展、5 个随包技能，以及 2 个主题，按你想达成的目标分组。每个扩展自己的 `README.md`
 提供完整的工具与命令说明。
 
 ### 规划与委派
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `cancel_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | 只读规划：模型先调研，把计划保存到 `.pi/plans` 下，你在写入任何内容前先批准。可在 TUI 中审阅，或在浏览器中打开以留下行内评论。`init` 技能复用同一审阅流程来创建或更新项目的 `AGENTS.md`。 |
+| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `cancel_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | 只读规划：模型先调研，把计划保存到 `~/.pi/agent/plans/<repo-key>` 下（每个仓库一份，各 worktree 共享），你在写入任何内容前先批准；开启 `plan.split` 后，批准时还可以把计划拆成切片，由独立会话按名字加入。可在 TUI 中审阅，或在浏览器中打开以留下行内评论：页面会跟随计划文件实时更新，你也可以给每位同事各一个审阅链接，各自以绑定的名义评论。`init` 技能复用同一审阅流程来创建或更新项目的 `AGENTS.md`。 |
 | [`check`](./extensions/check/) | `run_check`, `/check` | 检测项目的测试、lint 或类型检查命令（或使用 `check.command`），在受监管的进程中运行，并把失败整理成可导航的 `file:line` 列表。 |
 | [`subagent`](./extensions/subagent/) | `subagent`, `/agents` | 把任务委派给专职智能体（`explorer`、`planner`、`reviewer`、`worker`、`researcher`、`tester`、`debugger`、`documenter`），运行在它自己的 Pi 进程中 —— 单个、并行、链式或在后台运行；后台运行时在页脚显示数量，完成后发出提示。 |
 | [`todo`](./extensions/todo/) | `todo`, `/todos` | 持久任务列表（`pending` / `in_progress` / `completed`），配一行式 widget。 |
@@ -100,6 +101,7 @@ changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不
 | [`question`](./extensions/question/) | `ask_user_question` | 向你提出一个或多个结构化问题（带标签的选项外加自由填写的“其他”）并等待回答。 |
 | [`job`](./extensions/job/) | `job`, `/jobs` | 在后台运行长时 shell 命令；查看日志、等待或结束它们。 |
 | [`watch`](./extensions/watch/) | `watch`, `/watch` | 跟踪文件或命令输出，按模式匹配行，并提醒你或把匹配的行交给智能体。 |
+| [`session-bus`](./extensions/session-bus/) | `session`, `/sessions`（屏幕） | 在同一仓库的多个 Pi 会话之间协调：发现彼此、交换简短消息/事件、读取收件箱、加入已批准拆分中的一个切片或编辑前声明路径；`/sessions` 是显示对等会话、未读邮件和路径声明的实时面板。本地、默认拉取式；会话可以自行开启收件箱监视，在空闲时唤起本会话的一轮，从不创建智能体。 |
 | [`context`](./extensions/context/) | `/context` | 显示上下文窗口的去向 —— 系统提示、工具定义、按角色拆分的对话、注入的笔记 —— 并从报告中触发压缩，给出压缩前后的数字。 |
 
 ### 保护你的工作
@@ -115,7 +117,7 @@ changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
 | [`web-access`](./extensions/web-access/) | `web_search`, `web_fetch` | 搜索网络（默认无密钥的 DuckDuckGo，可选 SearXNG 或 Brave），并把页面抓取为可读文本，支持分页、`find`、逐跳 SSRF 检查以及可选的 PDF 支持。 |
-| [`file-browse`](./extensions/file-browse/) | `/browse` | 启动一个以工作目录为根的本地回环、只读文件浏览器，带 Markdown 预览、模糊快速打开面板，以及为常开页面提供的实时状态。 |
+| [`file-browse`](./extensions/file-browse/) | `/browse` | 启动一个以工作目录为根的本地回环、只读文件浏览器，带 Markdown 预览、模糊快速打开面板、从选区复制 `path:12-30` 引用、为常开页面提供的实时状态，以及所列目录变化时的重新加载提示。 |
 | [`file-read`](./extensions/file-read/) | `read_doc` | 在进程内从本地 PDF、DOCX、DOC、ODT、RTF 或 XLSX 提取文本，支持分页。 |
 | [`file-open`](./extensions/file-open/) | `/open`, `open_path` | 用操作系统原生应用打开或定位文件/目录。 |
 | [`wechat`](./extensions/wechat/) | `/wechat`, `send_wechat` | 通过微信 iLink 机器人 API 把微信聊天桥接到实时会话；入站文本、图片和文件会变成回合。 |
@@ -132,10 +134,11 @@ changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不
 
 | 技能 | 说明 |
 |---|---|
-| [`init`](./skills/init/SKILL.md) | 基于仓库证据，通过内置的交互式访谈和计划审阅创建或更新项目的 `AGENTS.md`。 |
+| [`init`](./skills/init/SKILL.md) | 通过内置的交互式访谈和计划审阅，基于仓库证据创建或更新 Pi 实际读取的指令文件（`AGENTS.md`；存在覆盖它的 `AGENTS.override.md` 时则是该文件），并从仓库推导命令、生成路径与包范围。 |
 | [`refactor`](./skills/refactor/SKILL.md) | 审计项目或路径中的重构机会：重复代码、过大的模块、耦合、结构漂移，以及测试薄弱且改动频繁的代码。返回带证据和验证命令的排序清单；发现阶段只读。 |
 | [`changelog`](./skills/changelog/SKILL.md) | 在变更的同一次提交中记录一条用户可见的条目，审计上一个 tag 以来缺失或薄弱的条目，并按项目自己的规则整理发布段落。 |
-| [`next`](./skills/next/SKILL.md) | 梳理接下来该做什么——未收尾的工作、已破坏或未兑现的承诺——可基于代码树或本次会话（`/skill:next session`），命令后的文字说明问什么、路径说明看哪里。只读，输出带证据和启动命令的简短排序清单。 |
+| [`parallel-dev`](./skills/parallel-dev/SKILL.md) | 以“负责人加团队”的方式组织并行开发：负责人对契约、共享文件、合并顺序和绿色基线负责，同时自己承担一个工作流；每个互不重叠的工作流各有一名所有者，先做可运行的纵向骨架，声明路径，在每个回合的边界协作，并由他人独立验证。 |
+| [`next`](./skills/next/SKILL.md) | 按优先级建议接下来的待办——未收尾的工作、已破坏或未兑现的承诺——会话已有工作时基于本次会话，仅当会话为空时才基于代码树；命令后的文字说明问什么、路径说明看哪里。只读，输出带证据和启动命令的简短编号清单。 |
 
 ### 主题
 
@@ -157,6 +160,10 @@ changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不
 <td width="50%"><img src="assets/job.png" alt="/jobs 屏幕：摘要行、带状态字形和耗时的任务行，以及焦点任务的命令、工作目录和最后一行输出" width="100%"></td>
 <td width="50%"><img src="assets/rewind.png" alt="/rewind 屏幕：从新到旧的提示行、标记有代码快照的菱形，以及焦点提示的快照详情" width="100%"></td>
 </tr>
+<tr>
+<td width="50%"><img src="assets/session.png" alt="/sessions 屏幕：计数摘要、带未读数和路径声明数的会话行、焦点会话的工作目录、声明和身份，以及 Tab 范围与监视提示" width="100%"></td>
+<td width="50%"><img src="assets/watch.png" alt="/watch 屏幕：摘要行和带实时匹配数的监视行，以及焦点监视的模式与来源" width="100%"></td>
+</tr>
 </table>
 
 ### 工具渲染
@@ -166,7 +173,7 @@ changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不
 （每个工具自身的渲染器或 bytefly 的通用回退）——用户铭牌与通知、Pi 内置工具，以及本包注册的每个工具。
 侧栏字形由 `chrome.rail` 设置。
 
-![每个工具块的全页参考图：用户铭牌、通知、回合分隔线，Pi 的 read、write、edit、bash、grep、find、ls 渲染器，以及每个包内工具——todo、goal、memory、job、watch、subagent、web_search、web_fetch、read_doc、open_path、run_doctor、send_wechat、ask_user_question、plan 工具与 worktree 工具](assets/tool-renderings.png)
+![每个工具块的全页参考图：用户铭牌、通知、回合分隔线，Pi 的 read、write、edit、bash、grep、find、ls 渲染器，以及每个包内工具——todo、goal、memory、job、watch、subagent、web_search、web_fetch、read_doc、open_path、run_doctor、send_wechat、ask_user_question、session、plan 工具与 worktree 工具](assets/tool-renderings.png)
 
 `bun run screenshot:tools` 重新生成它；`bun run screenshot:tool-pngs` 在
 [`assets/tools/`](./assets/tools) 下为每个工具输出一张图。

package/extensions/bytefly/README.md

@@ -327,7 +327,7 @@ See [The control center](#the-control-center).
 **Notify.** Off by default, one `notify` section in `bytefly.json` turns on OS
 notifications for unattended runs: when a full agent run settles, when a
 background job finishes, when the agent opens a prompt asking for input, and when
-a `watch` wake match fires while the agent is idle. The
+an armed `watch` wake match fires as the agent becomes idle. The
 method follows the terminal (OSC 777, OSC 99, a Windows toast) or falls back to
 the platform notifier (`osascript`, `notify-send`); see
 [Notifications](#notifications).
@@ -674,6 +674,12 @@ it. There is nothing to probe, so `r` is not offered here; the metadata is read
 once when the section first appears, so an edited `SKILL.md` shows on the next
 open.
 
+Themes and prompts have no section of their own, by decision rather than by
+omission: a theme is one active selection — a scalar, global setting — and a
+prompt template is a file Pi discovers from a directory, so neither is a scoped
+enable list this screen's checkbox rows can write. Themes stay with `pi config`;
+`ROADMAP.md` carries the reason under *Deliberately left thin*.
+
 **Settings.** The third section uses the same frame and the same `Tab` scope
 switch, with its own cursor. It is the shortlist a session changes: thirteen
 preferences on one flat line each, the value beside its label, and no group
@@ -692,7 +698,6 @@ Bytefly ────────────────────────
   ◼ Job finished  On
   ◼ Watcher matched  On
   ◻ Wake when a job finishes  Off
-  ◼ Offer the session goal  On
   ◼ Automatic snapshots  On
   ◼ Proactive health check  On
     Currency  CNY (¥)
@@ -718,7 +723,6 @@ Bytefly ────────────────────────
 | Job finished | `notify.jobFinished` | Off, On |
 | Watcher matched | `notify.matchFound` | Off, On |
 | Wake when a job finishes | `job.wakeOnFinish` | Off, On |
-| Offer the session goal | `plan.goalPrompt` | Off, On |
 | Automatic snapshots | `rewind.autoSnapshots` | Off, On |
 | Proactive health check | `doctor.proactive` | Off, On |
 | Currency | `price.currency.code` | CNY, USD |
@@ -756,15 +760,15 @@ terminal: adding a setting means removing one (`panel/panel.test.ts` holds the
 ceiling). Everything else stays in `bytefly.json` — the tuning numbers, the
 cosmetic labels, and the Pi preferences Pi's own `/settings` owns — and
 `test/settings-coverage.test.ts` keeps the split honest: every loader key is
-either a row or a declared JSON-only edit with the reason it left. Five
-`bytefly.json` sections therefore have no row at all (`chrome`, `goal`, `watch`,
-`worktree`, `memory`), as do `notify.title`, `doctor.timeoutMs`,
+either a row or a declared JSON-only edit with the reason it left. Six
+`bytefly.json` sections therefore have no row at all (`chrome`, `goal`, `plan`,
+`watch`, `worktree`, `memory`), as do `notify.title`, `doctor.timeoutMs`,
 `price.currency.decimals`, `rewind.max`, `rewind.safetySnapshot`,
 `job.detachedByDefault`, and `watch.wakeOnMatch` inside sections that do. Each is
 documented in [`docs/configuration.md`](../../docs/configuration.md).
 
-Three of the six sections belong to other extensions (`rewind`, `job`, and
-`plan`). The screen cannot import their normalizers, so it reports the leaf as
+Two of the five sections belong to other extensions (`rewind` and `job`). The
+screen cannot import their normalizers, so it reports the leaf as
 the file states it and declares the loader's default; the same test holds the
 catalogue to every loader's defaults and bounds in both directions.
 
@@ -788,16 +792,19 @@ The non-`tui` form prints the headline and one `Label: Value` row per line, in
 screen order:
 
 ```
-bytefly: Settings · Global · 14 settings
+bytefly: Settings · Global · 13 settings
   Bytefly startup TUI: Off
-  Theme: system
-  Desktop notifications: Off
+  Theme: bytefly-dark
+  Desktop notifications: On
   Turn finished: On
   Needs input: On
   Job finished: On
   Watcher matched: On
-  Delivery method: Auto
-  ...
+  Wake when a job finishes: On
+  Automatic snapshots: On
+  Proactive health check: On
+  Currency: CNY (¥)
+  Session budget: 5
 ```
 
 The doctor side probes every declared extension and reports each check as `ok`,
@@ -860,7 +867,7 @@ has a keyboard path.
 | rewind | `git` | — |
 | document | — | — |
 | subagent | a runnable nested `pi` | project-local agents need a trusted project |
-| plan | — | `git` for project-local `.pi/plans`; an interactive UI |
+| plan | — | an interactive UI |
 | memory | — | `git` for the project-scope root |
 | file-browse | — | `git` for the branch chip; the browser opener is best-effort |
 | web-access | — | `unpdf` |
@@ -892,12 +899,12 @@ of `bytefly.json` (see [Configuration](#configuration)):
 - **A background job finished.** The [job](../job/) extension announces each
   terminal transition on the shared `pi.events` bus
   (`my-pi-agent/job-finished`); bytefly listens and never imports it.
-- **A watcher matched.** A [watch](../watch/) whose `wake` is on matched while the
-  agent was idle, and announced it on `my-pi-agent/watch-match` with the cycle's
+- **A watcher matched.** A [watch](../watch/) whose `wake` is on matched, and
+  announced it on `my-pi-agent/watch-match` with the cycle's
   count, the watcher, and its newest line. The body names that line, sanitized and
   clipped to 80 characters, because the line is the alert: a watch usually tails a
-  build or an error log. A match the agent was busy for does not notify — it is
-  collected for the next turn instead.
+  build or an error log. A match the agent was busy for notifies once that run
+  settles, when its wake is raised.
 
 ### Delivery method
 

package/extensions/bytefly/notify/types.ts

@@ -21,7 +21,7 @@ export interface NotifyConfig {
 	needsInput: boolean;
 	/** Notify when a background `job` finishes. */
 	jobFinished: boolean;
-	/** Notify when a `watch` wake match fires while the agent is idle. */
+	/** Notify when a `watch` wake match fires, once the agent is idle. */
 	matchFound: boolean;
 	/** Delivery method; `auto` chooses by terminal and platform. */
 	method: NotifyMethod;

package/extensions/bytefly/panel/settings.ts

@@ -9,7 +9,7 @@
  * The catalogue is the shortlist a session changes, not the whole document: every
  * row is one a workflow differs on, and each states its own rule so a value the
  * screen accepts is a value the loader keeps. The catalogue order is the screen's
- * order, and it is capped so the section fits a 24-row terminal (`settings.test.ts`
+ * order, and it is capped so the section fits a 24-row terminal (`panel.test.ts`
  * holds the ceiling); a new row has to displace one. Everything else stays
  * `bytefly.json` — a list (`doctor.skip`), a table (`price.rates`), a schedule
  * (`price.peak`), and the tuning numbers and labels this screen deliberately does
@@ -17,14 +17,15 @@
  * pane of any row whose section is still on the list.
  *
  * Three sections have a normalizer here, so the screen shows what the notifier,
- * the doctor, and the footer keep. The three owned by other extensions (`rewind`,
- * `job`, `plan`) are read as the file states them, because importing their
+ * the doctor, and the footer keep. The two owned by other extensions (`rewind`
+ * and `job`) are read as the file states them, because importing their
  * normalizer would be one extension importing another's module; each such row
  * declares the loader's default, and `test/settings-coverage.test.ts` holds the
  * pair together.
  */
 
 import { configSection, configValueAt } from "../../../lib/config.ts";
+import { SPLIT_KEY, SPLIT_SECTION, SPLIT_SETTING_ID, SPLIT_SETTING_LABEL } from "../../../lib/plans/setting.ts";
 import { DEFAULT_CONFIG as DEFAULT_DOCTOR_CONFIG, normalizeConfig as normalizeDoctorConfig } from "../doctor/config.ts";
 import {
 	CURRENCY_DEFAULTS,
@@ -38,7 +39,7 @@ import { DEFAULT_NOTIFY_CONFIG, normalizeNotifyConfig } from "../notify/config.t
 import type { Settings, WriteScope } from "../picker/types.ts";
 
 /** Where a preference is stored. */
-type SettingSource = "app" | "bytefly";
+type SettingSource = "app" | "bytefly" | "plan";
 
 /** The row control a preference uses. */
 type SettingKind = "boolean" | "enum" | "text";
@@ -220,7 +221,7 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	{
 		id: "notify.matchFound",
 		label: "Watcher matched",
-		description: "Announce it when a `watch` whose `wake` is on matches while the agent is idle.",
+		description: "Announce it when a `watch` whose `wake` is on matches, once the agent is idle.",
 		source: "bytefly",
 		kind: "boolean",
 		fallback: "true",
@@ -239,17 +240,6 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		options: ON_OFF,
 		config: { section: "job", path: ["wakeOnFinish"] },
 	},
-	{
-		id: "plan.goalPrompt",
-		label: "Offer the session goal",
-		description: "Ask before recording an approved plan as the session goal; off records it without asking.",
-		source: "bytefly",
-		kind: "boolean",
-		fallback: "true",
-		json: "boolean",
-		options: ON_OFF,
-		config: { section: "plan", path: ["goalPrompt"] },
-	},
 	{
 		id: "rewind.autoSnapshots",
 		label: "Automatic snapshots",
@@ -306,14 +296,31 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		text: amountRule(0, MAX_BUDGET),
 		config: { section: "price", path: ["budget"] },
 	},
+	{
+		// The split's switch, with the label, id, and default taken from the module
+		// that reads it, so this row cannot describe a key nothing honours.
+		id: SPLIT_SETTING_ID,
+		label: SPLIT_SETTING_LABEL,
+		description:
+			"Let an approved plan carry a team of slices, which separate sessions join by name. Off keeps every plan one flow.",
+		source: "plan",
+		kind: "boolean",
+		fallback: "false",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: SPLIT_SECTION, path: [SPLIT_KEY] },
+	},
 ];
 
 /** The one refusal for a Project write while the project is untrusted. */
 export const UNTRUSTED_SETTINGS_NOTE = "Project is not trusted; settings can only be changed in Global scope.";
 
-/** The rows a scope can write: app rows are personal-file only. */
+/**
+ * The rows a scope can write: app rows are personal-file only, and Project shows
+ * the rows backed by `bytefly.json` — whichever extension owns the section.
+ */
 export function rowsForScope(scope: WriteScope): readonly SettingDescriptor[] {
-	return scope === "global" ? SETTING_ROWS : SETTING_ROWS.filter((row) => row.source === "bytefly");
+	return scope === "global" ? SETTING_ROWS : SETTING_ROWS.filter((row) => row.config !== undefined);
 }
 
 /**

package/extensions/file-browse/README.md

@@ -56,8 +56,9 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   external images are shown as links rather than fetched.
 - **Sortable listings.** The Name / Size / Modified headers sort the current
   directory, directories first, and the choice is remembered per browser.
-- **Copy and wrap.** Copy a file's root-relative path or its contents, and
-  toggle line wrapping for text and raw views.
+- **Copy and wrap.** Copy a file's root-relative path or its contents, copy a
+  `path:12-30` reference for the lines you selected, and toggle line wrapping for
+  text and raw views.
 - **Theme toggle.** A header button switches between the dark and light
   palettes and remembers the choice per browser; until it is used, the palette
   follows the system `prefers-color-scheme`.
@@ -66,7 +67,8 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   highlighted match; Enter opens the file.
 - **Keyboard.** `/` or `Ctrl/Cmd+K` opens quick open, `-` folds or expands
   every folder in the tree, `u` toggles line wrapping, `r` switches rendered and
-  raw Markdown, `n`/`p` step between a diff's hunks, and `?` opens a shortcut
+  raw Markdown, `y` copies a reference to the selected lines, `n`/`p` step
+  between a diff's hunks, and `?` opens a shortcut
   sheet. A diff's hunk headers pin to the top of the code viewport while its
   body scrolls.
 - **Read-only and loopback-scoped.** No editing, no writing, no LAN exposure.
@@ -88,11 +90,13 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   connecting (accent), stalled (amber, after three missed frames), or offline
   (red); the branch chip, the `● N changes +A −D` chip, and the change markers in
   the tree and the listing update in place; and the footer line reports `up 2m
-  14s · 37 requests`. The chip names its state and never counts, so nothing is
-  repainted between frames. One Server-Sent Events stream per page carries it, on
-  the same loopback server, so nothing extra is opened and nothing is written;
-  that stream is also how the server notices the last page closing its window,
-  after which it stops listening.
+  14s · 37 requests`. The chip names its state and never counts, and a frame
+  whose change set did not move repaints nothing at all. One Server-Sent Events
+  stream per page carries it, on the same loopback server, so nothing extra is
+  opened and nothing is written; that stream is also how the server notices the
+  last page closing its window, after which it stops listening. A page that lists
+  a folder also checks that folder, and offers a `⟳ reload` control when a file
+  has appeared or gone on disk since it drew its rows.
 - **No dependencies.** `node:http` plus the inline sprite, CSS, and client
   script.
 
@@ -136,10 +140,24 @@ errors. The chip names its state rather than counting, so it is repainted only
 when that state changes. The same frame carries the branch (or detached head), the
 uncommitted-change totals and paths, the server's uptime, and the requests it
 has answered, so the branch chip, the changes chip, the markers, and the footer
-line are painted from one snapshot rather than four requests. Losing the stream
-leaves everything the page last showed in place: it is read-only, so a stale
-label is never a stale action. `"live": false` turns the whole surface off — no
-chip, no stream, no `/events` route — and so does JavaScript off.
+line are painted from one snapshot rather than four requests. Each change set
+also carries a short revision, and a frame whose revision the page already
+painted does no work at all — so an idle tree costs no DOM, however many rows the
+page drew. Losing the stream leaves everything the page last showed in place: it
+is read-only, so a stale label is never a stale action. `"live": false` turns the
+whole surface off — no chip, no stream, no `/events` route — and so does
+JavaScript off.
+
+A page that lists a folder carries the revision of the names it drew, and asks
+`/api/dir-rev` for the folder's current one on the frame cadence — one directory
+read every five seconds by default, skipped while the tab is hidden and stopped
+for good once it has an answer. A difference reveals `⟳ reload` beside the live
+chip, which reloads the page; the rows themselves are never touched, because a
+page that could grow a row is a page that writes. A folder whose listing was
+truncated, and a file, `/diff`, or error page, has nothing to compare and shows
+no control. At most eight pages may hold the stream at once: a ninth is refused
+and its chip reads `offline`, which keeps one local page from pinning the server
+— and the git read behind each frame — alive.
 
 The stream is also how the server knows a page is still there: when the last one
 leaves, the port is released after ten seconds and the chip is cleared, because
@@ -212,7 +230,7 @@ document and the project document (project wins):
   "diffContext": 3,          // unified diff context lines
   "maxDiffLines": 4000,      // diff lines rendered before truncation
   "live": true,              // stream live status to open pages
-  "liveIntervalMs": 3000     // ms between status frames while a page is connected
+  "liveIntervalMs": 5000     // ms between status frames while a page is connected
 }
 ```
 
@@ -249,11 +267,18 @@ document and the project document (project wins):
   attributes; only the fixed `tok-*` class names reach the page.
 - **Event stream.** `/events` is a `GET` on the same loopback server, behind
   the same method and `Host` checks, and it only reads: the frame is the branch,
-  the change paths, an uptime, and a request count, all of which the page it
-  feeds already renders. It carries no page policy (`text/event-stream` is not a
-  document), sends `Cache-Control: no-store`, and cannot be cached or replayed.
-  A tick runs only while a page is attached, and the timer is `unref`ed, so an
-  idle server does no work and a forgotten tab cannot hold the process open.
+  the change paths and their revision, an uptime, and a request count, all of
+  which the page it feeds already renders. It carries no page policy
+  (`text/event-stream` is not a document), sends `Cache-Control: no-store`, and
+  cannot be cached or replayed. A tick runs only while a page is attached, and
+  the timer is `unref`ed, so an idle server does no work and a forgotten tab
+  cannot hold the process open. At most eight pages may attach; a ninth is
+  answered `204`, the one status an event source never reconnects after.
+- **Directory check.** `/api/dir-rev` answers one folder's listing revision, so
+  the page can tell whether its rows are stale. It goes through the same path
+  guard as every other route and reads one directory; its answer is a hash of the
+  names, not the names themselves, so it discloses nothing the page above it does
+  not already show.
 - **Caps.** `maxFileBytes` (inline rendering), `maxTextLines` (rendered lines),
   `maxThumbBytes` (thumbnails), and `maxDirEntries` (listings) bound every read.
 - **Git reads.** The header chip and the diff view run read-only git
@@ -271,9 +296,11 @@ document and the project document (project wins):
   approximated rather than parsed.
 - Live status updates what the page already contains: the header chips, the
   markers on the rows it rendered, and the footer line. A file that appears on
-  disk joins the listing on the next reload, the `/diff` table and a file page's
-  `changes` action stay page-load snapshots, and the branch chip is only patched
-  when the page was served inside a repository.
+  disk does not join the listing by itself — the page offers `⟳ reload` instead —
+  and the check covers the folder the page lists, by name, not the folders inside
+  it, a listed file's contents, the `/diff` table, or a file page's `changes`
+  action, which stay page-load snapshots. The branch chip is only patched when
+  the page was served inside a repository.
 - `/browse` has no auth; a malicious local page could probe the port. The `Host`
   allowlist and the absence of CORS headers mitigate reads, and the server is
   read-only.
@@ -314,6 +341,18 @@ document and the project document (project wins):
   method and `Host`, parses the URL, matches a route, and runs every path
   through `paths.ts`. It returns a plain `ServeResponse`, so routing is tested
   without a socket; `server.ts` is the only part that binds a port.
+- **One snapshot, one frame.** The status source is shared by every attached
+  page, so a tick costs one `git status`, one `git diff --stat`, and one
+  serialization however many tabs are open. The frame carries a revision of the
+  change set, and the client compares it before painting, which is why an idle
+  page does no DOM work. The cadence is what bounds those reads, so the default
+  is five seconds rather than matching the providers' two-second render cache.
+- **A poll, not a watcher.** The folder check is one request from the page to
+  `/api/dir-rev`, not an `fs.watch`: recursive watching 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 around `close()`. The
+  check compares names, so it is a directory read rather than a stat pass, and it
+  stops at the first difference because the control, not the checker, is the fix.
 - **Progressive UI.** The page is server-rendered HTML with an inline style
   block and inline SVG icons. `client.ts` enhances it: the filter hides
   non-matching rows while keeping ancestors, disclosure triangles lazily