@gavin-hu/my-pi-agent 0.13.1 → 0.14.0

package/README.md

@@ -31,13 +31,16 @@ want the agent to *think first and work safely*:
 - **Plan, then execute.** A read-only planning mode turns a task into a reviewed
   plan file that the agent then follows step by step.
 - **Delegate and parallelize.** Run specialist subagents in their own Pi
-  processes to explore, review, test, or implement while you keep the thread.
-- **Never wreck the checkout.** Work happens in an isolated `git worktree`, and
-  every prompt is snapshotted so a bad turn is one `/rewind` away.
+  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.
+- **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.
 - **Remember across sessions.** Durable notes live in plain markdown that you
   can read, edit, and version.
 - **Reach the web and your files.** Search, fetch, browse, open, and read
-  documents — all from inside the session.
+  documents from inside the session, and answer a WeChat chat through a bridge to
+  the live session.
 
 Everything is optional and independently toggleable. Nothing is patched or
 forked: Pi discovers the resources through the `pi` manifest in
@@ -49,13 +52,13 @@ other.
 Requires a working [Pi](https://pi.dev) installation.
 
 ```bash
-pi install npm:@gavin-hu/my-pi-agent                       # install from npm
-pi install git:github.com/gavin-hu/my-pi-agent             # install from git
-pi install git:github.com/gavin-hu/my-pi-agent@v0.13.1     # pin a release
-pi install ./ -l                                           # project-local (.pi/settings.json)
-pi -e .                                                    # try it for one run
+pi install npm:@gavin-hu/my-pi-agent
 ```
 
+[Getting started](./docs/getting-started.md) has the other sources — git, a
+pinned release, a project-local install, and a trial that writes nothing — plus
+the fit decision, the first workflows, and how to remove the pack.
+
 `git` on `PATH` is needed by [`worktree`](./extensions/worktree/) and
 [`rewind`](./extensions/rewind/); everything else degrades or disables cleanly,
 and `/bytefly doctor` names what is missing, including optional runtime pieces.
@@ -121,7 +124,7 @@ extension's own `README.md` has the full tool and command surface.
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly` (with the `doctor` and `settings` subcommands), `run_doctor` | The visible layer: a themed header with a width-adaptive footer, a live elapsed counter on Pi's working row, and a transcript where every tool block leads with its call line and rails its result under it. `/bytefly` switches extensions and holds the curated settings; opt-in `notify` raises OS notifications when a run, a job, or a question needs you. `bytefly.json` is the config document every extension reads. |
+| [`bytefly`](./extensions/bytefly/) | `/bytefly` (with the `doctor` and `settings` subcommands), `run_doctor` | The visible layer: a themed header with a width-adaptive footer, a live run line on Pi's working row (tool, tool count, and elapsed time), and a transcript where every tool block leads with its call line and rails its result under it. `/bytefly` switches extensions and holds the curated settings; opt-in `notify` raises OS notifications when a run, a job, or a question needs you. `bytefly.json` is the config document every extension reads. |
 
 ### Themes
 
@@ -184,7 +187,7 @@ stops the factories from registering; to drop the whole package, use Pi's
 
 | Guide | What it covers |
 |---|---|
-| [Getting started](./docs/getting-started.md) | Requirements, install options, verifying the load, themes. |
+| [Getting started](./docs/getting-started.md) | Whether the pack fits, a trial run, install options, verifying the load, first workflows, and removal. |
 | [Extensions](./docs/extensions.md) | The full catalog of every extension and theme. |
 | [Configuration](./docs/configuration.md) | Config-file resolution, the per-extension index, environment variables. |
 | [Configuration reference](./docs/references/bytefly-config.md) | Every `bytefly.json` section and key, with its type, default, and bounds. |

package/README.zh-CN.md

@@ -29,12 +29,13 @@ Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，
 
 - **先规划，再执行。** 只读的规划模式把一次任务变成一份可审阅的计划文件，智能体
   随后按步骤执行。
-- **委派与并行。** 在各自的 Pi 进程中运行专职子智能体来探索、审阅、测试或实现，
-  你继续把握主线。
-- **绝不搞乱检出区。** 工作发生在隔离的 `git worktree` 中，每次提示都会生成快照，
-  因此一次糟糕的回合只需一个 `/rewind` 就能回退。
+- **委派与并行。** 在各自的 Pi 进程中运行专职子智能体，把耗时构建交给后台任务，
+  让 watcher 盯住日志直到出现关键行 —— 你继续把握主线。
+- **绝不搞乱检出区。** 隔离只需一条命令：任务切到自己分支的 `git worktree` 中，
+  每次提示还会生成快照，因此一次糟糕的回合只需一个 `/rewind` 就能回退。
 - **跨会话记忆。** 持久笔记以纯 Markdown 保存，可读、可改、可纳入版本控制。
-- **连通网络与文件。** 搜索、抓取、浏览、打开和读取文档 —— 全部在会话内完成。
+- **连通网络与文件。** 在会话内搜索、抓取、浏览、打开和读取文档，还可通过桥接
+  在微信里直接回答当前会话。
 
 一切都是可选的，且可独立开关。没有任何东西被补丁或分叉：Pi 通过
 [`package.json`](./package.json) 里的 `pi` manifest 发现这些资源，因此该包能像
@@ -45,13 +46,12 @@ Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，
 需要一个可用的 [Pi](https://pi.dev) 安装。
 
 ```bash
-pi install npm:@gavin-hu/my-pi-agent                       # 从 npm 安装
-pi install git:github.com/gavin-hu/my-pi-agent             # 从 git 安装
-pi install git:github.com/gavin-hu/my-pi-agent@v0.13.1     # 固定到某个版本
-pi install ./ -l                                           # 仅项目本地（.pi/settings.json）
-pi -e .                                                    # 试运行一次
+pi install npm:@gavin-hu/my-pi-agent
 ```
 
+[快速开始](./docs/getting-started.md) 介绍其余安装方式——git、固定版本、
+仅项目本地安装，以及不写入任何内容的试用——还有适用性判断、首个工作流和移除方式。
+
 `git` 需在 `PATH` 上，供 [`worktree`](./extensions/worktree/) 与
 [`rewind`](./extensions/rewind/) 使用；其余部分会优雅降级或禁用，
 `/bytefly doctor` 会指出缺少什么，包括可选的运行时组件。
@@ -112,7 +112,7 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly`（`doctor`、`settings` 子命令）、`run_doctor` | 可见的那一层：主题化头部配宽度自适应页脚，Pi 工作行上实时计时，转录中每个工具块以调用行为标题、结果正文挂在其下方。`/bytefly` 可开关扩展并集中存放精选设置；可选的 `notify` 会在一次运行、后台任务或待回答的问题需要你时发出系统通知。`bytefly.json` 是每个扩展都会读取的配置文档。 |
+| [`bytefly`](./extensions/bytefly/) | `/bytefly`（`doctor`、`settings` 子命令）、`run_doctor` | 可见的那一层：主题化头部配宽度自适应页脚，Pi 工作行上实时显示工具、调用次数与计时，转录中每个工具块以调用行为标题、结果正文挂在其下方。`/bytefly` 可开关扩展并集中存放精选设置；可选的 `notify` 会在一次运行、后台任务或待回答的问题需要你时发出系统通知。`bytefly.json` 是每个扩展都会读取的配置文档。 |
 
 ### 主题
 
@@ -171,7 +171,7 @@ Pi 的 `--no-extensions`，或从你的设置中删除该包。
 
 | 指南 | 内容 |
 |---|---|
-| [快速开始](./docs/getting-started.md) | 环境要求、安装选项、验证加载、主题。 |
+| [快速开始](./docs/getting-started.md) | 是否适合你、试用、安装选项、验证加载、首个工作流、移除。 |
 | [扩展](./docs/extensions.md) | 所有扩展与主题的完整目录。 |
 | [配置](./docs/configuration.md) | 配置文件解析、按扩展索引、环境变量。 |
 | [配置参考](./docs/references/bytefly-config.md) | 列出 `bytefly.json` 的每个 section 与键，包括类型、默认值和取值范围。 |

package/extensions/bytefly/README.md

@@ -3,8 +3,8 @@
 `bytefly` owns the terminal chrome, configuration, and diagnostics surfaces
 this package adds: one themed startup header whose two-tone nameplate carries
 the agent and chrome identities, one compact, colorful, width-adaptive two-line
-footer, a two-row `You` nameplate that opens each user message, a labeled rule that
-marks each completed turn in the transcript, one keyboard-driven screen with two
+footer, a two-row `You` nameplate that opens each user message, a receipt rule that
+records each completed turn in the transcript, one keyboard-driven screen with two
 sections — Extensions, every resolved Pi extension with its enable checkbox and
 its health, and Settings, the common app and `bytefly.json` preferences — and
 an opt-in notify capability that raises an OS notification when a run finishes,
@@ -33,7 +33,7 @@ How the `run_doctor` call and its result look in the transcript — the call lin
 
 The extension owns ten surfaces: the startup header, the footer, the
 user-message marker, the rule between completed turns, the notice block for
-shared transcript notices, the tool-block frame, the live working counter, the
+shared transcript notices, the tool-block frame, the live working line, the
 two-section control center, notifications, and the published-version check.
 
 **Header.** A nameplate: a two-tone half-block mark from the active theme's
@@ -59,10 +59,15 @@ that cannot render half blocks the mark falls back to a two-tone `Pi` wordmark.
 
 As the terminal narrows, the identity sheds the update marker, then the chrome
 version, then the chrome line, then the agent name, and the help rows drop whole
-keys, so nothing wraps or clips mid-word. The nameplate sits on the transcript margin, which follows Pi's
-`outputPad` (the value the tool frame and the notice use too), and the help hangs
-one body indent inside it. The mark, tokens, identity, and grouped help are tuned
-in [`header/config.ts`](./header/config.ts).
+keys, so nothing wraps or clips mid-word. Height sheds the same way: at 28 rows
+all three help groups print, below 28 the middle group (the expand and model
+chords) goes first, below 22 only the `/` commands row survives, and below 16 the
+help block and the leading blank row go, leaving the nameplate and its rule. An
+unknown height keeps the full header. The nameplate sits on the transcript
+margin, which follows Pi's `outputPad` (the value the tool frame and the notice
+use too), and the help hangs one body indent inside it. The mark, tokens,
+identity, and grouped help are tuned in
+[`header/config.ts`](./header/config.ts).
 
 **Footer.** Two lines, each with a left and right zone:
 
@@ -168,26 +173,36 @@ as it would without it, and a soft wrap of one long line stays at the margin
 because the renderer wraps it, not bytefly. The label and the rule are tuned
 in [`message/config.ts`](./message/config.ts).
 
-**Working timer.** Pi's working row shows a static `Working`, so a long run
+**Working line.** Pi's working row shows a static `Working`, so a long run
 reads the same as a short one. While the row is up, bytefly advances its
-message once a second and hands it back to Pi when the row comes down:
+message once a second and hands it back to Pi when the row comes down. Before
+the first tool starts it is a count:
 
 ```
 Working… 12s
 ```
 
-The count is tied to the row's visibility: it starts on `turn_start`, the event
-the host shows the working indicator on, and stops on `agent_end`, where the
-host clears it, then again on `session_shutdown`. Turns inside one run do not
-restart it — the host keeps the same row up across turns — so the count covers
-the whole run, tool calls included. A retry is a new run, so the count restarts
-when its row reappears. The word and the interval are tuned in
-[`working/config.ts`](./working/config.ts).
+Once a top-level tool starts, the row becomes a live run line: the tool, how
+many top-level tools this run has started, and the elapsed time.
+
+```
+edit · 3 tools · 12s
+```
+
+A nested tool call (one carrying `parentToolCallId`, such as a codemode script's
+inner call) neither counts nor takes over the line, so the number matches the
+tool blocks in the transcript. The line keeps the last tool name while the
+model streams after it, and a tool event repaints the row immediately instead
+of waiting for the next tick. The line covers the whole run, tool calls
+included. It is tied to the row's visibility: it starts on `turn_start`, stops
+on `agent_end`, and is reset on `session_shutdown`; turns inside one run do not
+restart it, and a retry starts a new run. The words and the interval are tuned
+in [`working/config.ts`](./working/config.ts).
 
 **Turn separator.** After each completed turn the extension appends an inert
-entry and draws a centered `╌╌╌ turn N ╌╌╌` rule across the transcript; see
-[Turn separator](#turn-separator). No config file is needed and there is no
-command.
+entry and draws a centered receipt rule — `╌╌╌ turn N · duration · N tools ╌╌╌`
+— across the transcript; see [Turn separator](#turn-separator). No config file is
+needed and there is no command.
 
 **Notices.** Any extension in the package can post a transcript notice under the
 shared `my-pi-agent/notice` type; bytefly draws it at the transcript's margin —
@@ -219,6 +234,15 @@ are tuned in [`notice/config.ts`](./notice/config.ts). Every field is sanitized
 and clipped at the boundary, and a message without `details` keeps Pi's default
 custom-message box.
 
+**Compaction.** `/compact` is Pi's own surface: its summary block is a built-in
+message component, so bytefly cannot replace, hide, or shorten it. The shipped
+themes only remove its fill — `customMessageBg` is the terminal default — and
+paint the `[compaction]` label in the accent, so the block sits on the canvas
+like the rest of the transcript. Pi's branch summaries and skill invocations
+share the same tokens.
+
+<img src="../../assets/compaction.png" alt="The /compact summary block: a [compaction] label, the compacted token count, and the summary Markdown on the terminal canvas, with no background band" width="100%">
+
 **Tool blocks.** Every tool block leads with the tool's own call line as the
 headline — the tool name in the theme's tool-title colour — and its result body
 sits two columns in directly beneath it, led by the transcript rail, instead of
@@ -348,7 +372,7 @@ identity tokens, tagline, grouped help), the footer in
 [`footer/config.ts`](./footer/config.ts) (thresholds, gauge glyphs and widths,
 separators, icons, status keys), and the turn separator in
 [`separator/config.ts`](./separator/config.ts) (glyph, label prefix, padding,
-colors).
+minimum duration, outcome wording, colors).
 
 Every key of every section is listed with its type, default, and bounds in the
 [configuration reference](../../docs/references/bytefly-config.md); this section
@@ -507,32 +531,46 @@ the model, which sits at the end of the line.
 `agent_settled` fires once after an agent run fully settles — exactly one user
 turn — which is why it is used instead of `turn_end` (that fires once per
 assistant message, so tool-calling rounds would each get a line). On each
-settled run the extension appends an inert custom entry and a renderer draws
-it:
+settled run the extension appends an inert custom entry and a renderer draws it
+as a receipt: the turn number, then the run's duration, top-level tool count,
+and outcome as the width allows.
 
 ```
-╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ turn 3 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
+╌╌╌╌╌╌╌╌╌╌╌╌ turn 3 · 1m12s · 7 tools ╌╌╌╌╌╌╌╌╌╌╌╌
 ```
 
 - The turn number is `count(separators on the current branch) + 1`, so a
   resumed or forked session continues the parent's numbering and abandoned
   branches do not leak counts.
+- The receipt opens on the run's first `agent_start` and closes on
+  `agent_settled`, so a retry stays inside one duration. It counts only
+  top-level tool calls; a nested call (one carrying `parentToolCallId`) is an
+  implementation detail of its parent and does not inflate the number.
+- The outcome is part of the receipt: a failed tool adds `✕N`, and an aborted
+  run adds `aborted` instead of the failure count. A sub-second run prints no
+  duration, so quick turns stay quiet. Entries written before the receipt
+  existed have only a turn number and still render as `turn N`.
+- The label sheds fields rather than overflowing: the tool count first, then
+  the duration, then the outcome. When even the turn number does not fit, the
+  line becomes a plain dashed rule instead of clipping.
+- A clean turn paints the label `meta`, a turn with a failed tool paints it
+  `bad`, and an aborted turn paints it `warn`.
 - The entry is excluded from LLM context, so it costs no tokens, and it
   survives resume and fork. It is drawn under the `bytefly-separator` custom
   entry type.
-- The line is centered and width-adaptive: the label is filled out with the
-  glyph, and when it cannot fit the line becomes a plain dashed rule rather
-  than overflowing.
 - The rule is installed only in interactive (`tui`) sessions; RPC, JSON, and
   print sessions append nothing.
 - Separators recorded by the retired `turn-separator` extension are not
   rendered, and `PI_DISABLED_EXTENSIONS=turn-separator` no longer affects the
   rule; disable the whole extension with `bytefly` instead.
-- There is no runtime command; the glyph, label prefix, padding, and colors are
-  tuned in [`separator/config.ts`](./separator/config.ts).
+- There is no runtime command; the glyph, label prefix, padding, colors, and
+  minimum duration are tuned in
+  [`separator/config.ts`](./separator/config.ts).
 
 ## The control center
 
+<img src="../../assets/bytefly.png" alt="The /bytefly control center: the Extensions and Settings section bar with the `Global · 10 extensions · 2 off · 1 missing` counts, one checkbox row per extension with its verdict, the focused extension's report, and the key hints" width="100%">
+
 `/bytefly [extension] [refresh]` opens the control center on **Extensions**: a
 keyboard-driven dock list of every extension Pi resolves for the session, so the
 list matches what actually loads. `←`/`→` switch to **Settings**, where the same
@@ -597,11 +635,11 @@ installs or fetches a package.
   without leaving the session.
 
 **Settings.** The second section uses the same frame and the same `Tab` scope
-switch, with its own cursor. It lists sixteen preferences in six groups:
+switch, with its own cursor. It lists twenty-eight preferences in ten groups:
 
 ```
 bytefly ──────────────────────────────────────────────────────────────
-  Extensions · Settings                           Global · 16 settings
+  Extensions · Settings                           Global · 28 settings
 
   Startup (1)
 ❯ ◻ Bytefly startup TUI                                            Off
@@ -620,16 +658,32 @@ bytefly ────────────────────────
     Currency                                                    CNY (¥)
     Cost decimals                                                    2
     Session budget                                                   0
-  Transcript (2)
+  Transcript (3)
     Rail glyph                                                       ╎
+    Achieved goal                                                  Hide
     Output padding                                                   1
   Terminal (1)
   ◻ Hardware cursor                                                Off
+  Worktree (4)
+    ◼ Fetch remote                                                 On
+    Base ref                                                    Fresh
+    Branch prefix                                          worktree-
+    Prune after (days)                                             7
+  Snapshots (3)
+    ◼ Automatic snapshots                                          On
+    Snapshots kept                                               20
+    ◼ Safety snapshot                                               On
+  Jobs and watchers (3)
+    ◻ Wake when a job finishes                                     Off
+    ◻ Keep jobs after exit                                         Off
+    ◻ Wake on a match                                              Off
+  Memory (1)
+    ◼ Inject notes                                                  On
   Bytefly startup TUI — Pi setting
   Use bytefly's startup header in place of Pi's startup TUI.
   Default · ~/.pi/agent/settings.json
 
-  Esc close · ←/→ · Space change · Tab scope · ↑/↓ select
+  Esc close · ←/→ · Space change · Tab scope · u reset · J JSON · [ ] group
 ```
 
 | Group | Row | Source | Values |
@@ -648,21 +702,43 @@ bytefly ────────────────────────
 | Pricing | Cost decimals | `price.currency.decimals` | 0, 1, 2, 3, 4 |
 | Pricing | Session budget | `price.budget` | Number, `0` = off |
 | Transcript | Rail glyph | `chrome.rail` | Text, exactly one column |
+| Transcript | Achieved goal | `goal.achieved` | Show, Hide |
 | Transcript | Output padding | Pi `settings.json` | 0, 1 |
 | Terminal | Hardware cursor | Pi `settings.json` | Off, On |
+| Worktree | Base ref | `worktree.baseRef` | Fresh, Head |
+| Worktree | Branch prefix | `worktree.branchPrefix` | Text, trimmed, required |
+| Worktree | Fetch remote | `worktree.fetchRemote` | Off, On |
+| Worktree | Prune after (days) | `worktree.pruneAfterDays` | Number, 0–3650 |
+| Snapshots | Automatic snapshots | `rewind.autoSnapshots` | Off, On |
+| Snapshots | Snapshots kept | `rewind.max` | Number, 0–1000 |
+| Snapshots | Safety snapshot | `rewind.safetySnapshot` | Off, On |
+| Jobs and watchers | Wake when a job finishes | `job.wakeOnFinish` | Off, On |
+| Jobs and watchers | Keep jobs after exit | `job.detachedByDefault` | Off, On |
+| Jobs and watchers | Wake on a match | `watch.wakeOnMatch` | Off, On |
+| Memory | Inject notes | `memory.inject` | Off, On |
 
 Choosing **Currency** also writes that currency's default precision. Both rows
 stay editable afterwards, so the footer follows the explicit values.
 
 `Space` (or `Enter`) changes the focused row: a boolean toggles, an enum cycles
 forward, and a text row opens an inline editor on its value — the notification
-title, the probe timeout, and the rail glyph. The detail pane names the source, describes the preference, and shows
+title, the probe timeout, the branch prefix, and the rail glyph. `u` deletes the
+focused row's key so its default applies again (`Already at its default.` when
+nothing is stored), `J` swaps the detail pane for the focused row's whole section
+as the active scope stores it — the only view of the keys this screen leaves to
+JSON — and `[` / `]` jump to the previous or next group. The detail pane names
+the source, describes the preference, and shows
 where the value is written — `Global · ~/.pi/agent/settings.json`, `Project ·
 .pi/bytefly.json`, or `Inherited from Global · .pi/bytefly.json`. A successful
 change marks the screen `Saved · reload to apply` — even when the terminal is too
 short for the detail body — and closing offers the same
 reload confirm as an extension toggle.
 
+Six of the ten groups belong to other extensions. The screen cannot import their
+normalizers, so it reports the leaf as the file states it and declares the
+loader's default; `test/settings-coverage.test.ts` holds the catalogue to every
+loader's defaults and bounds in both directions.
+
 **Bytefly startup TUI** is the one row whose label differs from the Pi key it
 writes: On writes `"quietStartup": true` (bytefly's header replaces Pi's startup
 detail), and Off writes `false` (Pi's built-in header stays). A hand-set
@@ -671,17 +747,18 @@ with `true` or `false`.
 
 App rows are **Global only**: Pi's setters for them write the personal
 `settings.json`, and only resource paths have public project setters. Project
-scope therefore lists the thirteen `bytefly.json` rows and a
+scope therefore lists the twenty-five `bytefly.json` rows and a
 `App settings are Global only.` note rather than promising a write that cannot
 happen. A `bytefly.json` row writes one leaf in the selected scope (a depth-1
 key, or a nested one such as `price.currency.decimals`) through a per-key
 writer, so every sibling key, section, `$schema`, and `version` is preserved. A
-malformed document is refused with a notice instead of overwritten.
+malformed document is refused with a notice instead of overwritten, and `u`
+removes that one leaf through the same writer's `unsetConfigValueAt`.
 
 The non-`tui` form prints the headline, the groups, and `Label: Value` rows:
 
 ```
-bytefly: Settings · Global · 16 settings
+bytefly: Settings · Global · 28 settings
 
 Startup (1)
   Bytefly startup TUI: Off
@@ -966,6 +1043,9 @@ command.
 - **Notifications are not focus-aware.** They fire whether or not the terminal
   has focus, and once per trigger rather than once per unseen event. There is
   no focus API to consult.
+- **`/compact` is Pi's block.** The summary component is built in, so bytefly
+  cannot render, hide, or shorten it; the themes only choose its fill and label
+  color. Branch summaries and skill invocations share the same theme tokens.
 - **A background job cannot ask for input.** The `needsInput` trigger is a
   prompt raised during a run, not a process waiting on stdin: jobs are
   fire-and-observe, so that state does not exist.
@@ -973,11 +1053,11 @@ command.
   host lacks (or an OSC method off a TTY) and the notification is dropped; only
   `auto` inspects the environment. `doctor` now reports the mismatch as a
   `degraded` finding, which says what to change but does not fix it for you.
-- **The working counter is one global row.** `setWorkingMessage` drives the
+- **The working line is one global row.** `setWorkingMessage` drives the
   single working row, so bytefly and any other extension setting it race — last
   writer wins — and the message is reset to Pi's default at `agent_end`. If the
-  row is hidden (`ctx.ui.setWorkingVisible(false)`) the counter has no surface,
-  and a reload mid-run does not resume it until the next turn.
+  row is hidden (`ctx.ui.setWorkingVisible(false)`) the line has no surface,
+  and a reload mid-run does not resume the count until the next turn.
 
 ## Non-goals
 
@@ -1001,7 +1081,7 @@ command.
   match — are the whole surface.
 - No sound, action buttons, notification history, or de-duplication; a
   notification is a fire-and-forget message, not an inbox.
-- No frozen per-run working duration: the counter is live and is handed back to
+- No frozen per-run working duration: the line is live and is handed back to
   Pi when the working row comes down, because the extension API exposes no hook
   to keep a finished run's total.
 
@@ -1014,18 +1094,18 @@ rather than showing a wrong value.
 
 | Integration point | Details |
 |---|---|
-| Header | `ctx.ui.setHeader` with a custom component, replacing Pi's built-in header; installed only when `ctx.mode === "tui"` and `pi.getSettings().quietStartup === true` (the **Bytefly startup TUI** row). `false`, `"header"`, and unset call `setHeader(undefined)`, leaving Pi's built-in header in place. The nameplate insets by Pi's `outputPad` (read through `pi.getSettings()`), so it sits on the transcript margin, and the help hangs one body indent inside it. The mark and text are drawn from the active theme's tokens, the help keys resolve live through `keyText`, and the mark falls back to a wordmark on Apple Terminal (`isAppleTerminalSession`), mirroring Pi's built-in. The chrome version gains `↑<latest>` from the `UpdateSource`, and `registerHeader` returns a `refresh()` handle that re-installs the last context's header when that value arrives. |
+| Header | `ctx.ui.setHeader` with a custom component, replacing Pi's built-in header; installed only when `ctx.mode === "tui"` and `pi.getSettings().quietStartup === true` (the **Bytefly startup TUI** row). `false`, `"header"`, and unset call `setHeader(undefined)`, leaving Pi's built-in header in place. The nameplate insets by Pi's `outputPad` (read through `pi.getSettings()`), so it sits on the transcript margin, and the help hangs one body indent inside it. The mark and text are drawn from the active theme's tokens, the help keys resolve live through `keyText`, and the mark falls back to a wordmark on Apple Terminal (`isAppleTerminalSession`), mirroring Pi's built-in. The factory reads `tui.terminal.rows` on every render, so the height ladder in `header/config.ts` sheds help groups and then the leading blank row as the terminal shortens (unknown height keeps the full header). The chrome version gains `↑<latest>` from the `UpdateSource`, and `registerHeader` returns a `refresh()` handle that re-installs the last context's header when that value arrives. |
 | Footer | `ctx.ui.setFooter` with a custom component, replacing Pi's built-in footer; installed only when `ctx.mode === "tui"`. |
 | User message | `pi.registerMarkdownTransformer` puts a two-row `You` nameplate (the label over a full-width rule) above each user message; one padded level-2 heading carries the accent through `mdHeading` for both rows, and the shipped themes set `userMessageBg` to the terminal default, so the block has no fill. Pi renders the result as Markdown, so the surface adds no component or color of its own. |
 | Notice | `registerMessageRenderer(NOTICE_TYPE)` draws every shared transcript notice at the margin from its `details`; the headline stays at the margin and its rows hang from the transcript rail, painted by the notice's worst severity, whose glyph comes from the shared `RailSource`. `job` and `watch` post one when their work settles, and `doctor` posts one at `session_start` for a missing hard requirement. The type and shape come from `lib/notice.ts`. A message without `details` falls back to Pi's default custom-message box. |
 | Tool blocks | `registerToolRenderer` returns, for every tool, `renderShell: "self"`; `renderCall` leaves the tool's own first line as the block's headline (a shell prompt shown as the tool name, its command repainted in the body colour, and a primary subject demoted to the body colour) and indents the rest of the call two columns under it, `renderResult` indents its body the same and leads it with the status-coloured rail, and each wraps the tool's own renderer (or a generic fallback). `edit` and `write` carry their result on the call body, so that body is railed too. |
 | Screen command | `pi.registerCommand("bytefly")` takes `[doctor] [settings] [extension] [refresh]`: `tui` mounts a dock screen via `ctx.ui.custom()` with the rails suppressed; other modes print through `ctx.ui.notify()` — the grouped listing, `run_doctor`'s report for `doctor`, or the grouped settings listing with values for `settings`. A named extension is checked against the discovered set before any probe. Tab completes the subcommands, extension names after `doctor`, and `refresh`; `/bytefly settings` rejects a name. |
-| Turn separator | `registerEntryRenderer("bytefly-separator")` draws each rule; `agent_settled` appends `pi.appendEntry("bytefly-separator", { turn })` in `tui` mode only. |
-| Working timer | `turn_start` starts a 1s tick that drives `ctx.ui.setWorkingMessage("Working… Ns")` in `tui` mode; `agent_end` restores Pi's default and cancels the tick (also on `session_shutdown`). No config file and no stored state. |
+| Turn separator | `registerEntryRenderer("bytefly-separator")` draws each stored receipt; `agent_start` opens it, top-level `tool_execution_start`/`tool_execution_end` count tools and failures, and `agent_settled` appends `pi.appendEntry("bytefly-separator", { turn, durationMs, tools, failures, aborted })` in `tui` mode only. The receipt fields are omitted when no `agent_start` was seen, so an older or partially observed entry stays `{ turn }`. |
+| Working line | `turn_start` starts a 1s tick that drives `ctx.ui.setWorkingMessage` in `tui` mode; before a tool runs the message is `Working… Ns`, and each top-level `tool_execution_start` repaints it as `tool · N tools · Ns` (nested calls carrying `parentToolCallId` are skipped). `agent_end` restores Pi's default and cancels the tick (also on `session_shutdown`). No config file and no persisted state; the count lives in the register's closure. |
 | Notifications | `agent_settled` (skipped when aborted), `ui_prompt_start` only while `agent_start`…`agent_settled` marks a run active, and `my-pi-agent/job-finished` on `pi.events`; the `notify` section of `bytefly.json` gates each. Delivery writes an OSC 777/99 sequence to stdout or spawns `osascript`, `notify-send`, or `powershell.exe`. The bus subscription is created in `session_start` and released in `session_shutdown`, and the `job` extension never imports bytefly. |
 | Picker discovery | `SettingsManager.create(...)` plus `DefaultPackageManager.resolve({ onMissing: "skip" })`, both public exports; both views drop `bytefly`'s own entrypoint. |
 | Picker writes | `SettingsManager` setters (`setExtensionPaths`, `setPackages`, `setProjectExtensionPaths`, `setProjectPackages`) then `flush()`; `ctx.reload()` after the screen closes when changes are pending. |
-| Settings writes | App rows call `SettingsManager` setters (`setQuietStartup`, `setOutputPad`, `setShowHardwareCursor`) on the global store and `flush()`, then surface `drainErrors()`; `bytefly.json` rows call `writeConfigValueAt` on the selected scope's document with the row's leaf path, so a nested key (`price.currency.decimals`) and a flat one (`notify.method`) share one writer. A failed or refused write shows a notice in the screen's hint row and leaves the displayed value unchanged; a successful one marks the screen dirty. |
+| Settings writes | App rows call `SettingsManager` setters (`setQuietStartup`, `setOutputPad`, `setShowHardwareCursor`) on the global store and `flush()`, then surface `drainErrors()`; `bytefly.json` rows call `writeConfigValueAt` on the selected scope's document with the row's leaf path, so a nested key (`price.currency.decimals`) and a flat one (`notify.method`) share one writer, and `u` calls `unsetConfigValueAt` with the same path. A failed or refused write shows a notice in the screen's hint row and leaves the displayed value unchanged; a successful one marks the screen dirty. |
 | Doctor tool | `pi.registerTool("run_doctor")`, read-only (`readOnlyHint: true`, `openWorldHint: false`), direct exposure and active on registration (the defaults, so not declared), with a typed `outputSchema` mirroring `structuredContent`. Its `readOnlyHint` is what the shared default-deny policy in `lib/policy.ts` reads to allow it in plan mode. |
 | Doctor probes | `run_doctor` and the screen share the session cache created by `registerDoctor`; the screen mounts on that cache and probes on the first Extensions view (the command's `refresh` forces it), while the text modes probe before printing, and `/bytefly refresh` and `refresh: true` re-probe. Probes spawn `<binary> --version`, lazily import optional packages, and read config files through `lib/requirements.ts`; nothing is ever written. |
 | Status routing | Reads `footerData.getExtensionStatuses()` (a custom footer replaces the built-in one entirely); `worktree` routes to line 1, plan/alert statuses to line 2's trailing slot. |
@@ -1118,8 +1198,10 @@ rather than showing a wrong value.
   and a grouped help block. It takes its margin from Pi's `outputPad`, like the
   tool frame and the notice, and hangs the help one body indent inside it, so the
   header follows a non-default pad instead of assuming a column. It adds no
-  session or model data — that is the footer's job — and it stays a fixed
-  four-plus rows so the startup transcript never reflows.
+  session or model data — that is the footer's job — and its shape follows the
+  terminal: the height ladder drops whole help groups, then the leading blank
+  row, before the nameplate gives up anything, so a short pane spends its rows
+  on the transcript instead of chrome.
 - **Two lines, four zones.** Line 1 is identity (`pwd` left, branch + worktree
   right); line 2 is resources (meters left, model + level right). This keeps
   "where am I / what state" separate from "how much am I burning".
@@ -1274,7 +1356,7 @@ rather than showing a wrong value.
 The surfaces are folders: `header/`, `footer/` (the status bar and its price
 calculation), `message/` (the user-message marker), `notice/` (the shared notice),
 `block/` (the tool-block frame), `separator/`, `working/` (the live
-elapsed counter on Pi's working row), `panel/` (the
+run line on Pi's working row), `panel/` (the
 unified screen and its merged model),
 `picker/` (discovery and the settings store), `doctor/` (the `run_doctor` tool
 and its probe runtime), `notify/`, and `update/` (the published-version check
@@ -1316,14 +1398,14 @@ columns, gauge), so the look follows the active theme.
 | `block/component.ts` | Pure `toolBlockLines`, `headlineWithToolName`, `recolorShellCall`, `recolorCallHeadline`, and `ToolBlock`: the headline, the body's two-column indent (optionally rail-led), the reduced-width inner render, the leading-blank trim, the shell-prompt rewrite (the name keeps the accent, the command reopens in `label`), the subject demotion (a path, URL, query, or pattern reads in `label` so the name is the line's only accent, including the tail a bare `edit <path>` headline wraps onto the body), and the image-line passthrough. |
 | `block/fallback.ts` | Generic `callFallback` / `resultFallback` for a tool with no renderer: the subject in the body colour, its options faint, and a capped result preview. |
 | `block/register.ts` | The `registerToolRenderer` resolver that frames every tool; it recolours a shell call's string before the frame wraps it, rails the result body by status, and rails the call body for `edit`/`write` (the two whose call body carries the result). |
-| `separator/config.ts` | Turn-rule tuning: `customType`, glyph, label prefix, padding, and roles. |
-| `separator/register.ts` | Registers the entry renderer and appends a separator on `agent_settled`. |
+| `separator/config.ts` | Turn-rule tuning: `customType`, glyph, label prefix, padding, receipt minimum duration and outcome wording, and roles. |
+| `separator/register.ts` | Registers the entry renderer, tracks the run's tools and failures, and appends the receipt on `agent_settled`. |
 | `separator/component.ts` | `SeparatorComponent`: the stateless entry renderer. |
-| `separator/format.ts` | Pure `separatorLine`: the centered turn rule, drawn by the kit's `centeredRule`. |
-| `separator/types.ts` | `TurnSeparatorData`. |
-| `working/config.ts` | Counter tuning (`WORKING_CONFIG`): the word, the ellipsis, and the tick interval. |
-| `working/format.ts` | Pure `formatElapsed` (whole seconds) and the working-message shape. |
-| `working/register.ts` | Starts the tick on `turn_start` and cancels it on `agent_end`/`session_shutdown`. |
+| `separator/format.ts` | Pure `receiptLabel` (the width ladder), `receiptRole`, and `separatorLine`, drawn by the kit's `centeredRule`. |
+| `separator/types.ts` | `TurnSeparatorData`: the turn plus the optional receipt fields. |
+| `working/config.ts` | Counter tuning (`WORKING_CONFIG`): the words, the tool singular/plural, and the tick interval. |
+| `working/format.ts` | Pure `formatElapsed` (whole seconds) and the working-message shape: the plain count and the `tool · N tools · elapsed` run line. |
+| `working/register.ts` | Starts the tick on `turn_start`, tracks top-level tools on `tool_execution_start`, and cancels on `agent_end`/`session_shutdown`. |
 | `panel/types.ts` | `PanelSection` (`extensions` | `settings`), `PanelRow`, and `PanelModel`, the merged row model. |
 | `panel/join.ts` | The item/report union with the unambiguous-name health rule and unique row keys, groups, and ordering. |
 | `panel/format.ts` | Non-TUI text: the extension headline and grouped listing with a per-row health suffix, plus the section segments, the Settings counts/headline, and the grouped Settings listing. |
@@ -1375,10 +1457,10 @@ folding across a width sweep from 6 to 120 plus wide characters
 (`footer/render/layout`), exact
 golden output at fixed widths (`footer/render/render`), and the install/skip/
 restore/toggle lifecycle plus a config-driven price (`extension`). The turn
-separator
-is covered by its pure formatting (`separator/format`) and its
-register/append/render/disable lifecycle (`separator/register`). The picker
-helpers are covered by the pure helpers (`picker/resources`), the toggle
+separator is covered by its pure formatting (`separator/format`, including the
+receipt's width ladder), its register/append/render/disable lifecycle
+(`separator/register`), and the run stats it records. The picker helpers are
+covered by the pure helpers (`picker/resources`), the toggle
 transforms (`picker/toggle`), discovery with an injected factory
 (`picker/discovery`), and the runtime state machine (`picker/runtime`). The
 unified screen is covered by its pure model merge (`panel/join`), its text

package/extensions/bytefly/doctor/config.ts

@@ -14,6 +14,9 @@ import { clampInteger, loadConfigSection } from "../../../lib/config.ts";
 /** How long a single probe may take before it counts as unusable. */
 const DEFAULT_TIMEOUT_MS = 2_000;
 
+/** The probe deadline range, in milliseconds; the panel's editor offers the same bounds. */
+export const TIMEOUT_MS_RANGE = { min: 100, max: 30_000 } as const;
+
 export interface DoctorConfig {
 	/** Probe enabled extensions at session start and warn when one is broken. */
 	proactive: boolean;
@@ -34,7 +37,7 @@ export function normalizeConfig(raw: Record<string, unknown> | undefined, base:
 	if (!raw) return base;
 	return {
 		proactive: typeof raw.proactive === "boolean" ? raw.proactive : base.proactive,
-		timeoutMs: clampInteger(raw.timeoutMs, base.timeoutMs, 100, 30_000),
+		timeoutMs: clampInteger(raw.timeoutMs, base.timeoutMs, TIMEOUT_MS_RANGE.min, TIMEOUT_MS_RANGE.max),
 		skip: Array.isArray(raw.skip)
 			? raw.skip.filter((name): name is string => typeof name === "string" && name.trim().length > 0)
 			: base.skip,

package/extensions/bytefly/footer/price/config.ts

@@ -101,9 +101,10 @@ export const DEFAULT_BYTEFLY_CONFIG: ByteflyConfig = {
 	budget: 0,
 };
 
-const MAX_DECIMALS = 4;
+/** The highest `currency.decimals` the screen and the loader both accept. */
+export const MAX_DECIMALS = 4;
 /** Upper bound for `budget`; large enough for any real session, small enough to clamp a typo. */
-const MAX_BUDGET = 10_000_000;
+export const MAX_BUDGET = 10_000_000;
 const MAX_RATE = 1_000_000;
 const MAX_RATE_KEYS = 200;
 const MAX_WINDOWS = 16;