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

package/extensions/bytefly/README.md

@@ -3,13 +3,14 @@
 `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,
-a job finishes, or the agent asks for input, and a published-version check that
-marks the header and posts one notice when a newer bytefly is on npm.
+a job finishes, or the agent asks for input, and a package-update check that
+replaces Pi's startup block with one notice and marks bytefly's own new version
+on the header.
 DeepSeek is priced from the provider's published yuan rates and peak tariff by
 default; set `price.currency.code` to `USD` to price it from the provider's
 published dollar table instead, under the same peak windows, with Pi's recorded
@@ -33,8 +34,8 @@ 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
-two-section control center, notifications, and the published-version check.
+shared transcript notices, the tool-block frame, the live working line, the
+two-section control center, notifications, and the package-update check.
 
 **Header.** A nameplate: a two-tone half-block mark from the active theme's
 `accent` / `warn` roles, the agent identity (`Pi`, bold, and its version), the
@@ -59,10 +60,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:
 
@@ -70,7 +76,7 @@ in [`header/config.ts`](./header/config.ts).
   (`⎇ branch · ⑂ worktree`) and the `◉` browse chip on the right.
 - **Line 2 — resources:** the context gauge and usage meters on the left, the
   child-run roll-up (`↳ 3 · ¥0.12`, present only once a subagent has finished),
-  the mode/alert slot (`⋮ plan`) trailing after a `╎` when present, and the model
+  the mode/alert slot (`≡ plan`) trailing after a `│` when present, and the model
   and thinking level on the right. The gauge is anchored at column 0, so `%` is
   always in the same place.
   The roll-up is its own number, never folded into the session's cost: a subagent
@@ -81,7 +87,7 @@ in [`header/config.ts`](./header/config.ts).
 
 ```
 ~/repo/my-pi-agent                                              ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↳ 2 · ¥0.06 · ↑42k ↓8.0k · R96k CH 87% ╎ ⋮ plan    opus-4.5 · high
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↳ 2 · ¥0.06 · ↑42k ↓8.0k · R96k CH 87% │ ≡ plan    opus-4.5 · high
 ```
 
 (The examples show the default `¥` symbol. A model that neither `rates` nor the
@@ -89,7 +95,7 @@ built-in table covers contributes nothing in `CNY` mode, so the bar shows no
 figure rather than a guessed one; `USD` mode adds Pi's recorded dollars for that
 record instead — see the currency note under [Configuration](#configuration).)
 
-With no plan mode there is no mode slot, so the `╎` is omitted:
+With no plan mode there is no mode slot, so the `│` is omitted:
 
 ```
 ~/repo/my-pi-agent                                                    ⎇ main · ⑂ smoke
@@ -102,19 +108,19 @@ fits, rather than collapsing to a bare glyph:
 
 ```
 ~/repo/project                    ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62% · ¥0.31 ╎ ⋮ plan    opus-4.5 · high
+▰▰▰▰▰▰▱▱▱▱ 62% · ¥0.31 │ ≡ plan    opus-4.5 · high
 ```
 
 ```
 project   ⎇ main
-62% ⋮   opus-4.5
+62% ≡   opus-4.5
 ```
 
 With a named session, the name follows the path and truncates before it drops:
 
 ```
 ~/repo/project · feature-refac…   ⎇ main
-▰▰▰▰▰▰▱▱▱▱ 62% ╎ ⋮ plan         opus-4.5
+▰▰▰▰▰▰▱▱▱▱ 62% │ ≡ plan         opus-4.5
 ```
 
 Zero-value meters are omitted, so a fresh session shows only `?/window` instead
@@ -168,26 +174,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 +235,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
@@ -294,15 +319,17 @@ method follows the terminal (OSC 777, OSC 99, a Windows toast) or falls back to
 the platform notifier (`osascript`, `notify-send`); see
 [Notifications](#notifications).
 
-**Update check.** In the background at an interactive session's start, the loaded
-version is compared with the published `@gavin-hu/my-pi-agent` on npm. A newer
-one puts `↑0.12.0` after the header's chrome version and posts one transcript
-notice naming `pi update --extensions` and its release URL. The answer is cached
-in `<agentDir>/bytefly/update.json` with the time it was read, so a session
-starting inside the 24-hour window reuses it instead of repeating the request,
-and `/bytefly update` re-runs the check on demand. The check is skipped when
-`PI_OFFLINE` is set, makes no request outside `tui`, and a failed background
-request is silent; see [Update check](#update-check).
+**Update check.** In the background at an interactive session's start, Pi's
+package manager reports which configured packages are behind. bytefly suppresses
+Pi's own startup block, caches the snapshot in `<agentDir>/bytefly/update.json`
+with the time it was read, and posts one transcript notice listing every package
+plus `pi update --extensions`. This package's new version alone puts `↑0.12.0`
+after the header's chrome version and adds its release URL to the notice. A
+session inside the 24-hour window reuses the cache without a package-manager
+call, and `/bytefly update` re-runs the check on demand. `PI_OFFLINE` uses the
+cached marker with no notice, only `tui` starts the background check, and a
+failed read is silent and not cached, so the next session tries again; see
+[Update check](#update-check).
 
 ## Commands
 
@@ -311,7 +338,7 @@ request is silent; see [Update check](#update-check).
 | `/bytefly [extension] [refresh]` | Open the control center on Extensions. In `tui` it mounts a docked list; every other mode prints the grouped listing, or one extension's full findings when named. |
 | `/bytefly settings` | Open the control center on Settings. Outside `tui` it prints the grouped settings listing with each row's value. |
 | `/bytefly doctor [extension] [refresh]` | Print the doctor report. Outside `tui` it prints `run_doctor`'s text for every extension, or one named extension's findings; in `tui` it mounts the same docked screen. |
-| `/bytefly update` | Re-run the published-version check now, ignoring the cache window, and report what it found — the newest version, an available release with its URL, `PI_OFFLINE`, or an unreadable registry. It resolves no packages and probes no extension. |
+| `/bytefly update` | Re-run the package update check now, ignoring the cache window, and report what it found — the updateable packages, this package's version and release URL when known, `PI_OFFLINE`, or an unreadable list. It resolves no packages and probes no extension. |
 
 Tab completes the subcommands, extension names after `doctor`, and `refresh`;
 `/bytefly settings` and `/bytefly update` take no name.
@@ -348,10 +375,10 @@ 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
+Every key of every section is listed with its type, default, and bounds in
+[`docs/configuration.md`](../../docs/configuration.md); this section
 covers what that table cannot — when each section is read, and what the cost
 does when no rate matches.
 
@@ -448,7 +475,10 @@ it with its own rates for the models they match:
 - **Which rate.** The most specific key wins, with the model segment outranking
   the provider one: `provider/model`, then `*/model`, then `provider/*`, then
   `*`. A segment ending in a star is a prefix match (`*/gpt-*`); equally
-  specific keys are resolved in file order.
+  specific keys are resolved in file order. A key splits at its first slash, so
+  the model segment may contain one: an OpenRouter id is
+  `anthropic/claude-fable-5` and its key is
+  `openrouter/anthropic/claude-fable-5`.
 - **Which formula.** `tokens × rate ÷ 1,000,000`, summed over the four token
   classes. Cache tokens are never billed again as fresh input.
 - **Which tariff.** Each record is dated by its session entry, so a window is
@@ -495,9 +525,9 @@ The worktree status is read from the `worktree` status key, so the
 from the `browse` status key published by [file-browse](../file-browse/) while
 its server runs, and shows the two-tone `◉ <port>` (green glyph, accent port).
 The trailing slot shows plan-style alerts when present and is omitted otherwise;
-a plan chip's trailing plan file name is dropped, so the slot reads `⋮ plan`
+a plan chip's trailing plan file name is dropped, so the slot reads `≡ plan`
 even though the built-in footer keeps the name. An alert (a failed job) sorts to
-the front of the slot. The slot trails the meters after a `╎`, so the context
+the front of the slot. The slot trails the meters after a `│`, so the context
 gauge always starts the line. It keeps each extension's own colour when it
 compacts, and it is droppable: a tight bar drops the slot rather than truncating
 the model, which sits at the end of the line.
@@ -507,32 +537,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
@@ -544,7 +588,7 @@ when the row is switched off in settings, `env disabled` when
 glyph and summary. The screen is drawn from the design system: a label-first
 `bytefly ────` title rule,
 the `Extensions · Settings` section bar beside the section's counts, one row
-grammar (`❯ ◼ ✓ name … summary`), and the shared `◼` / `◻` checkbox.
+grammar (`❯ ◼ name … summary`), and the shared `◼` / `◻` checkbox.
 `/bytefly doctor [extension] [refresh]` selects the doctor report, the same text
 the `run_doctor` tool returns; in `tui` it opens the same screen. `[extension]`
 narrows the Extensions section to one extension and `refresh` forces the first
@@ -568,12 +612,13 @@ installs or fetches a package.
   manages the list is never a selectable row; its doctor report still appears in
   the trailing `Not resolved` group.
 - Shows whether each one is enabled (`◼`) or disabled (`◻`) in settings.
-- Gives each row one verdict from the doctor's report: the worst severity (`✓`
-  ok, `!` degraded, `✕` missing) and its summary. A row that is `◻` reads `off`
-  instead, because it will not load; a row the session's
+- Gives each row one verdict from the doctor's report: the worst severity's
+  glyph (`!` degraded, `✕` missing) and its summary. A row that is `◻` reads
+  `off` instead, because it will not load; a row the session's
   `PI_DISABLED_EXTENSIONS` excludes reads `env disabled`, so the two axes cannot
-  contradict each other. An extension with no doctor report leaves the glyph
-  column and the summary blank rather than claiming `ok`.
+  contradict each other. The glyph marks what needs attention, so a row with
+  nothing to report — a clean report or none at all — leaves the glyph column
+  blank and says `ok` in words when a report exists.
 - Toggles the focused extension with `Space`, writing `+pattern` / `-pattern`
   into `extensions` (and package filter objects) in the active scope. A row in
   the trailing `Not resolved` group has no pattern to write, so `Space` says so
@@ -597,11 +642,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-nine preferences in ten groups:
 
 ```
 bytefly ──────────────────────────────────────────────────────────────
-  Extensions · Settings                           Global · 16 settings
+  Extensions · Settings                           Global · 29 settings
 
   Startup (1)
 ❯ ◻ Bytefly startup TUI                                            Off
@@ -620,16 +665,33 @@ bytefly ────────────────────────
     Currency                                                    CNY (¥)
     Cost decimals                                                    2
     Session budget                                                   0
-  Transcript (2)
+  Transcript (3)
     Rail glyph                                                       ╎
+    Achieved goal                                                  Hide
     Output padding                                                   1
-  Terminal (1)
+  Terminal (2)
+    Theme                                                       system
   ◻ 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,20 +710,54 @@ 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 | Theme | Pi `settings.json` (`theme`) | `system`, `bytefly-dark`, `bytefly-light` |
 | 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.
 
+The **Theme** row lists `system` first, then the palettes this package ships,
+`bytefly-dark` and `bytefly-light`; it cycles no further, so a bytefly screen
+never proposes a palette it cannot vouch for. It writes the personal `theme`
+setting and takes effect after reload. A value chosen elsewhere — Pi's built-in
+`dark`, another package's theme, or an automatic pair such as
+`bytefly-light/bytefly-dark` — is shown as stored (the pair with `… (automatic)`)
+and is replaced by the next choice here, so manage those in Pi's `/settings` →
+**Theme**.
+
 `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
-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.
+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 in that scope; an inherited Project value says so instead),
+`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 comes from — `Global · ~/.pi/agent/bytefly.json`, `Project ·
+.pi/bytefly.json`, `Inherited from Global · ~/.pi/agent/bytefly.json`, or
+`Default · <the active scope's file>`; an app row names the personal
+`settings.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 `bytefly.json` sections 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
@@ -671,17 +767,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 · 29 settings
 
 Startup (1)
   Bytefly startup TUI: Off
@@ -733,6 +830,9 @@ headline; a named extension prints its full findings instead.
 | `Space` | Toggle the focused extension (Extensions); change the focused setting (Settings), or open the editor on a text row. |
 | `x` | Clear the focused extension's project override (Extensions, Project scope). |
 | `Enter` | Expand or collapse the focused extension's findings (Extensions); change the focused setting, or open the editor on a text row (Settings). |
+| `u` | Delete the focused setting's key so its default applies again (Settings, `bytefly.json` rows). |
+| `J` | Show or hide the focused row's whole section as stored (Settings, `bytefly.json` rows). |
+| `[` / `]` | Jump to the previous or next group (Settings). |
 | `←` / `→`, `Home` / `End` (`Ctrl+A` / `Ctrl+E`) | Move the editor's caret while a text row is being edited. |
 | `Backspace` / `Delete`, `Ctrl+U` | Edit the buffer: delete a character, or clear it. |
 | `Enter` / `Esc` (editing) | Save the buffer, or cancel and restore the stored value. |
@@ -824,10 +924,11 @@ control-free line before it reaches an escape sequence or a shell argument.
 
 ## Update check
 
-A session can be days behind npm without anyone noticing, and Pi's own startup
-check only covers package sources it manages — a `pi -e ./`, a linked checkout,
-or a git install gets nothing. So bytefly reads its own published version and
-reports it once, in the two places it already owns:
+Pi's package manager already knows which configured packages are behind, so
+bytefly does not keep a second detector. Once per interactive session, in the
+background, it asks the captured `checkForAvailableUpdates` for the package list,
+suppresses Pi's own `Package Updates Available` block, and draws one notice for
+every row Pi returned.
 
 ```
  █▀█  Pi v1.3.0
@@ -835,47 +936,50 @@ reports it once, in the two places it already owns:
 ```
 
 ```
- bytefly · 0.12.0 is available
- ╎ ◌ current · v0.11.4
+ bytefly · 2 package updates available
+ ╎ ◌ @gavin-hu/my-pi-agent · v0.11.4 → v0.12.0
+ ╎ ◌ some-other-package · project
  ╎ ◌ update · pi update --extensions
  ╎ ◌ release · https://github.com/gavin-hu/my-pi-agent/releases/tag/v0.12.0
 ```
 
-The marker is the shared `↑` glyph and the newest version — the arrow is one cell
-wide, so the header's column math is unchanged — painted with the header's
-`accent` role: an action rather than a warning, so the muted version beside it
-stays quiet and the transcript is not turned yellow for a normal state. It is
-part of the chrome cell, so the two identity cells still line up, and it is the
-first thing the identity sheds when the terminal narrows.
+The marker is the shared `↑` glyph and this package's newest version — the arrow
+is one cell wide, so the header's column math is unchanged — painted with the
+header's `accent` role: an action rather than a warning, so the muted version
+beside it stays quiet and the transcript is not turned yellow for a normal state.
+Other packages never change the header. The marker is part of the chrome cell, so
+the two identity cells still line up, and it is the first thing the identity
+sheds when the terminal narrows.
 
 The notice is the shared transcript block: the `bytefly · title` headline at the
-margin, then the loaded version and the fixing command behind the rail, all at
+margin, one rail row per package with this package's version arrow or the other
+package's scope, then the fixing command and this package's release URL, all at
 `info` severity because nothing is broken. It stays in scrollback and the model
-reads the same sentence in plain text.
-
-The request is `GET https://registry.npmjs.org/@gavin-hu%2Fmy-pi-agent/latest`,
-fired without awaiting at `session_start` (Pi awaits handlers, and a five-second
-registry call must not hold the first prompt) with a five-second abort. Only a
-strictly newer, parseable semver announces anything: a non-ok status, a body
-that is not JSON, a missing version, a network error, or an older or equal
-version is silent. `PI_OFFLINE` (Pi's own switch) turns the check off;
-`PI_SKIP_VERSION_CHECK` only governs Pi's `pi.dev` request.
-
-The answer is cached in `<agentDir>/bytefly/update.json` as `latest` plus the
-epoch milliseconds it was read at. A session that starts inside the 24-hour
-window reuses that entry — painting the marker and posting the notice from it —
-instead of repeating the request, so a working day of sessions costs one read.
-Past the window the check runs again and rewrites the entry; a failed read writes
-nothing, so the next session tries again. Offline, the cached entry is used with
-no request and no write, because a stale version is still the best answer
-available and the marker is advisory.
-
-`/bytefly update` is the on-demand half: it ignores the window, reads the registry
-now, records and paints the result, and prints one line — `up to date — v0.12.0
-is the newest published version`, `v0.13.0 is available (current 0.12.0) —
-https://…/releases/tag/v0.13.0`, `the update check was skipped (PI_OFFLINE is
-set)`, or `could not read the published version`. It resolves no packages, probes
-no extension, and posts no second notice, so a session open for days can see a
+reads the same names, version, command, and URL in plain text.
+
+The list is Pi's decision: npm ranges, git refs, project scope, a missing
+install, and `PI_OFFLINE` all follow its package manager. The only extra read is
+`GET https://registry.npmjs.org/@gavin-hu%2Fmy-pi-agent/latest` when Pi reports
+this package, used just to name the version arrow and release URL. A failed
+version read drops those two pieces but keeps the package list and command.
+
+The answer is cached in `<agentDir>/bytefly/update.json` as the package list,
+this package's optional version, the time it was read, and a key over the cwd and
+the effective package sources. A session that starts inside the 24-hour window
+reuses that snapshot — painting the marker and posting the notice from it —
+without repeating Pi's npm/git checks, so a working day of sessions costs one
+read. A project switch or a package install/removal changes the key and forces a
+fresh read. Past the window the check runs again and rewrites the entry; a failed
+read writes nothing, so the next session tries again. Offline, the cached marker
+is used with no request and no notice, because a stale version is still the best
+answer available and the list itself is advisory.
+
+`/bytefly update` is the on-demand half: it ignores the window, asks Pi's package
+manager now, records and paints the result, and prints one line — the package
+list with this package's version and release URL when known, `up to date — no
+configured package has an update`, `the update check was skipped (PI_OFFLINE is
+set)`, or `could not check package updates`. It resolves no packages, probes no
+extension, and posts no second notice, so a session open for days can see a
 release without a restart. Opening the control center never checks: the screen has
 no update surface, and the only request paths are `session_start` and this
 command.
@@ -887,9 +991,16 @@ command.
   rule, and transcript renderers stay on. Use `PI_DISABLED_EXTENSIONS=bytefly`
   (or `pi config`) to turn off all of bytefly.
 - **App settings are Global only.** Pi's setters for preferences such as
-  `quietStartup` (the **Bytefly startup TUI** row), `outputPad`, and
-  `showHardwareCursor` write the personal `settings.json`; the screen hides
-  those rows in Project scope rather than writing a file Pi cannot manage.
+  `quietStartup` (the **Bytefly startup TUI** row), `outputPad`,
+  `showHardwareCursor`, and `theme` write the personal `settings.json`; the
+  screen hides those rows in Project scope rather than writing a file Pi cannot
+  manage.
+- **The Theme row offers only this package's palettes.** `system`,
+  `bytefly-dark`, and `bytefly-light` are the whole cycle; Pi's built-ins and any
+  user, project, or other package's theme stay in Pi's `/settings` → **Theme**,
+  and a value set there shows as stored here. An automatic pair such as
+  `bytefly-light/bytefly-dark` shows as stored but is replaced by the next single
+  choice, and the change applies after a reload like the other app rows.
 - **Project overrides of app settings are not shown.** App rows read the
   personal file; a `.pi/settings.json` override still wins at runtime, and
   `pi config` is the place to manage it.
@@ -909,19 +1020,22 @@ command.
   their authoritative names are not exposed to extensions. Use `pi config`.
 - **Packages are not installed, removed, or updated here**; use `pi install`,
   `pi remove`, and `pi update`.
-- **The update check reads npm's `latest` only.** A private registry, a version
-  published under another tag, or a checkout ahead of npm reports nothing, and
-  there is no channel or prerelease preference: `0.11.4` is behind `0.12.0`
-  whether or not a `0.12.0-beta.1` exists.
+- **The update list is Pi's.** Only packages configured in `settings.json` are
+  checked; `pi -e .`, a temporary checkout, and other unmanaged loads get no
+  update prompt. The version arrow and release URL still come from npm's
+  `latest`, so a private registry or a version published under another tag can
+  lose those two pieces while the list stays correct.
 - **The cache window is fixed at 24 hours.** It runs at `session_start` in `tui`
-  mode and reuses an entry younger than that; there is no setting for it, and
-  `/bytefly` and `doctor` do not report the version. A failed or slow background
-  request is retried by the next session, or immediately by `/bytefly update`.
+  mode and reuses a snapshot younger than that whose key matches the cwd and
+  package sources; there is no setting for it, and `/bytefly` and `doctor` do not
+  report the version. A failed or slow background request is retried by the next
+  session, or immediately by `/bytefly update`.
 - **The marker needs the bytefly startup TUI.** It lives on the custom header,
   so with `quietStartup` off the notice is the whole signal.
-- **Pi may report the same update.** An npm-installed copy can also show Pi's
-  own `Package Updates Available` block; the two checks are independent and
-  `pi update --extensions` satisfies both.
+- **Pi's block is suppressed by a host shim.** bytefly wraps
+  `DefaultPackageManager.prototype.checkForAvailableUpdates` at `session_start`
+  and restores it on shutdown. A future Pi that changes that method shape makes
+  the shim inert, and Pi's own block can come back.
 - **No auto-update, and the release URL is text only.** The notice names a
   command instead of running one, and the notice renderer cannot open a link, so
   the release row prints the URL and nothing more — no changelog body, no way to
@@ -966,6 +1080,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 +1090,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 +1118,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,26 +1131,26 @@ 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`, `setTheme`) on the global store and `flush()`, then surface `drainErrors()`; `bytefly.json` rows call `writeConfigValuesAt` 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 a row that also writes a companion leaf (the currency and its default precision) applies both in one document pass; 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. |
-| Update check | `session_start` in `tui` mode reads `<agentDir>/bytefly/update.json` and, when the entry is inside `UPDATE_CACHE_TTL_MS` (24 h), records it without a request; otherwise it fires `fetchLatestVersion()` without awaiting, so the handler never holds the prompt, and writes the answer back. The registry read is a fixed `GET` of npm's `latest` document over an injected `fetch`, bounded by an abort timeout; a strictly newer, parseable semver is recorded in the per-load `UpdateSource`, `onUpdate` re-installs the header, and `pi.sendMessage(updateNotice(...))` posts the one notice with its release URL. `PI_OFFLINE` uses the cache with no request and no write. `/bytefly update` calls the returned `UpdateHandle.recheck()`, which bypasses the window, records, paints, and returns an `UpdateOutcome`; a generation counter drops a background reply that lands after `session_shutdown`, and a per-load flag keeps it to one announcement. |
+| Update check | `session_start` in `tui` mode installs a suppression on `DefaultPackageManager.prototype.checkForAvailableUpdates`, then reads `<agentDir>/bytefly/update.json`. A fresh entry whose key matches the cwd and effective package sources is recorded without a package-manager call; otherwise bytefly fires `fetchAvailableUpdates()` without awaiting, resolves this package's version through `fetchLatestVersion()` when Pi reports it, writes the snapshot, and records it. `onUpdate` re-installs the header, and `pi.sendMessage(updateNotice(...))` posts the one notice with its version arrow and release URL. `PI_OFFLINE` paints the cached marker only. `/bytefly update` calls the returned `UpdateHandle.recheck()`, which bypasses the window and returns an `UpdateOutcome`; a generation counter drops a background reply that lands after `session_shutdown`, a per-load flag keeps it to one announcement, and shutdown restores Pi's method. |
 | Config | `bytefly.json` from the agent directory and `<cwd>/.pi`; the `price` section is read once per footer install (a new session or a session-tree change), the `notify` and `doctor` sections at `session_start`, and the `chrome` section's rail glyph at `session_start`/`session_tree`. Nothing watches the document. The update check has no section: it is on whenever `PI_OFFLINE` is off, and its 24 h window is not configurable. |
 | Data sources | `footerData.getGitBranch()`, `footerData.getAvailableProviderCount()`, `ctx.getContextUsage()`, `ctx.sessionManager.getEntries()`, `ctx.sessionManager.getSessionName()`, `ctx.model`; subscribes to `footerData.onBranchChange` to repaint. |
-| State storage | None besides the inert separator entries. The footer reads session entries and the price config (a memoized scan) and writes no tool-result `details`; it appends `bytefly-separator` entries excluded from LLM context. The screen derives its view from the picker runtime and the current reports, and persists extension toggles through `settings.json`. The Settings section derives from a snapshot of the personal `settings.json` and both `bytefly.json` documents, and persists through the same `SettingsManager` setters or the per-leaf `bytefly.json` writer. Doctor's findings are session-scoped in memory only — cached for the session, never written to the session or a file. Notify holds only the config and the run-active flag in its closure. The update check holds one version in the per-load `UpdateSource` and writes no session entry; its one file is `<agentDir>/bytefly/update.json`, the cached `latest` plus `checkedAt`, written atomically and read back on the next session. |
-| Lifecycle | `session_start` installs the header when Pi's `quietStartup` is `true` and the footer, loads the chrome rail glyph, points the doctor runtime at the session cwd, probes the extensions with hard requirements when `bytefly.json`'s `doctor.proactive` is on and `quietStartup` is `true`, loads the notify config and subscribes to the job bus, and starts the published-version check; `session_tree` reinstalls the header and footer and reloads the rail; `session_shutdown` restores Pi's built-in header and footer, disposes the branch subscription, drops doctor's cached findings, drops the notify bus subscription, and clears the recorded version. |
+| State storage | None besides the inert separator entries. The footer reads session entries and the price config (a memoized scan) and writes no tool-result `details`; it appends `bytefly-separator` entries excluded from LLM context. The screen derives its view from the picker runtime and the current reports, and persists extension toggles through `settings.json`. The Settings section derives from a snapshot of the personal `settings.json` and both `bytefly.json` documents, and persists through the same `SettingsManager` setters or the per-leaf `bytefly.json` writer. Doctor's findings are session-scoped in memory only — cached for the session, never written to the session or a file. Notify holds only the config and the run-active flag in its closure. The update check holds this package's version in the per-load `UpdateSource` and one project-scoped snapshot in `<agentDir>/bytefly/update.json`. |
+| Lifecycle | `session_start` installs the header when Pi's `quietStartup` is `true` and the footer, loads the chrome rail glyph, points the doctor runtime at the session cwd, probes the extensions with hard requirements when `bytefly.json`'s `doctor.proactive` is on and `quietStartup` is `true`, loads the notify config and subscribes to the job bus, and starts the package-update check; `session_tree` reinstalls the header and footer and reloads the rail; `session_shutdown` restores Pi's built-in header, footer, and package-update method, disposes the branch subscription, drops doctor's cached findings, drops the notify bus subscription, and clears the recorded version. |
 
 ## Design notes
 
@@ -1075,8 +1192,12 @@ rather than showing a wrong value.
   expand toggle, so no themed string outlives its theme. `indentBlockLines` only
   measures a line it cannot prove fits, and the header memoizes on the width,
   theme, shape, and the help chords it prints, so a live rebind still repaints.
-  The footer's context estimate joins its pricing scan in the leaf-keyed memo:
-  both are O(session) work the host recomputes from scratch.
+  `SeparatorComponent` uses the same memo for its full-width rule, so a long
+  session does not repaint every turn's rule each frame. The footer's context
+  estimate and session name join its pricing scan in the leaf-keyed memo: all
+  three are O(session) work the host recomputes from scratch, and
+  `createRateLookup` compiles the rate table once per config instead of once per
+  record.
 - **The frame delegates; it does not re-render.** Pi resolves tool renderers
   through the extension chain, and the resolved object is the definition the row
   reads, so a resolver can override `renderShell` and wrap `next()`'s
@@ -1110,7 +1231,8 @@ rather than showing a wrong value.
   themselves by that pad: the tool frame and the notice take it from Pi, and the
   turn separator reads the last value a sibling observed (`pad.ts`). Pi's setting
   is the only knob — bytefly adds no padding of its own. The footer's group
-  separator still draws `╎` between chips — a divider, not a rail.
+  separator draws `│` between chips — a divider, not the rail (`╎`), which stays
+  a transcript-only glyph.
 - **The header is a nameplate, not a dashboard.** Pi's built-in brand colors are
   fixed, so the mark ignores the active theme; bytefly's header draws a two-tone
   mark from the `accent`/`warn` roles, a signature rule whose accent lead sits
@@ -1118,8 +1240,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".
@@ -1129,7 +1253,7 @@ rather than showing a wrong value.
   dispatching process and the delegated work stays visible beside it.
 - **The gauge is anchored at column 0.** A leading mode slot would shift the
   context percentage left and right as plan mode came and went; trailing it
-  after a `╎` keeps the percentage in a fixed place while the mode stays
+  after a `│` keeps the percentage in a fixed place while the mode stays
   visible as the meters drop.
 - **Statuses are routed, not repeated.** The built-in footer renders every
   `setStatus` value on its own line, so the bar sorts them by meaning instead:
@@ -1147,9 +1271,9 @@ rather than showing a wrong value.
   non-zero usage, so it reads full only at 100% and a small percentage never
   disappears; unknown usage draws no gauge at all. Only at extreme widths does
   `truncateToWidth` clip the remaining text.
-- **Separators shrink to a single space.** Padded separators (` · `, ` ╎ `)
+- **Separators shrink to a single space.** Padded separators (` · `, ` │ `)
   collapse to one space before `truncateToWidth` applies, so adjacent segments
-  never collide and the ellipsis never replaces a `╎` with nothing after it.
+  never collide and the ellipsis never replaces a `│` with nothing after it.
 - **Statuses compact with their colour.** A themed status's compact icon form
   reattaches its opening and closing SGR sequences around the visible text, so a
   red `✗1` stays red instead of losing its colour exactly when the bar tightens.
@@ -1253,32 +1377,38 @@ rather than showing a wrong value.
 - **The prerequisite table is data.** No I/O, no host access, no module state:
   every probe dependency arrives as a seam, so `probeExtension` is testable with
   no process and `lib/` stays value-only.
-- **The update check is a self-report, not an update mechanism.** It answers one
-  question — is the version in this checkout current? — and answers it in the two
-  surfaces bytefly already owns, the header identity and one notice. It never
-  installs, never edits settings, and never fails a session: an unreachable
-  registry and an up-to-date one are indistinguishable to the user, which is the
-  only failure mode a background check is allowed to have.
-- **The marker is an action, the notice is information.** The same fact is drawn
-  in the accent on the header, where it sits beside a control the user can act
-  on, and at `info` severity in the transcript, where a `warn` rail would say
-  something is broken. Neither surface needs per-frame polling: the value arrives
-  once, the memo key includes it, and one `setHeader` re-install repaints.
+- **Pi owns the update list; bytefly owns the look.** There is one detector, not
+  two: `DefaultPackageManager` already resolves npm ranges, git refs, project
+  scope, and offline mode, and bytefly only carries its result to a themed
+  surface. The extra registry read only names this package's version for the
+  marker, arrow, and release URL; it never decides whether an update exists.
+- **The suppression is a host shim, not a second checker.** Pi has no setting or
+  extension event for its startup block, so bytefly replaces the public method
+  that feeds it while keeping the captured original for its own read. It is
+  installed only in `tui`, restored on shutdown, and made inert if the host
+  changes shape.
+- **The marker is an action, the notice is information.** This package's new
+  version is drawn in the accent on the header, where it sits beside a control
+  the user can act on, and every package is listed at `info` severity in the
+  transcript, where a `warn` rail would say something is broken. Neither surface
+  needs per-frame polling: the value arrives once, the memo key includes it, and
+  one `setHeader` re-install repaints.
 - **The transport stays local.** `web-access`'s runner does redirects, SSRF
   checks, HTML extraction, and caching — none of it applies to one fixed JSON
   endpoint, and an extension may not import another's modules, so the ~20-line
-  read lives beside the check with the `fetch` and timeout as seams.
+  read lives beside the check with the `fetch` and timeout as seams. The package
+  list itself is Pi's own command execution, not a second transport.
 
 ## Files
 
 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
-behind the header marker, its disk cache, and the on-demand re-check). The chrome and the screen are drawn from
+and its probe runtime), `notify/`, and `update/` (Pi's package list, the host
+suppression, the cache, and the header marker). The chrome and the screen are drawn from
 the package's [`lib/tui/`](../../lib/tui/) design system (tokens, rules, rows,
 columns, gauge), so the look follows the active theme.
 
@@ -1294,10 +1424,10 @@ columns, gauge), so the look follows the active theme.
 | `footer/config.ts` | Bar tuning (`CONFIG`): thresholds, gauge, separators, icons, status keys, labels. |
 | `footer/types.ts` | `StatusSnapshot`, `Segment`, `LineSpec`, `UsageRecord`, and footer/TUI shapes. |
 | `footer/collect/entries.ts` | Session entries → usage records, each resolved to the model in effect. |
-| `footer/collect/snapshot.ts` | Snapshot assembly; memoized pricing scan per branch leaf. |
+| `footer/collect/snapshot.ts` | Snapshot assembly; memoized pricing scan, context estimate, and session name per branch leaf. |
 | `footer/price/types.ts` | `Currency`, `ModelRates`, `PeakWindow`/`PeakSchedule`, `ByteflyConfig`. |
 | `footer/price/config.ts` | The `price` section of `bytefly.json`: schema, defaults, built-in DeepSeek rates/tariff, currency defaults, normalizer, loader. |
-| `footer/price/rates.ts` | Model-key matching: exact and wildcard, most specific first. |
+| `footer/price/rates.ts` | Model-key matching: `createRateLookup` splits every key once, splits a key at its first slash (so an OpenRouter model id may contain one), matches exact and wildcard most-specific-first, and remembers the last record's model. |
 | `footer/price/schedule.ts` | Peak-window parsing and evaluation in a configured zone. |
 | `footer/price/price.ts` | Records → totals: rated cost in both modes, Pi's recorded cost as USD's fallback, and the peak multiplier. |
 | `footer/render/format.ts` | Generic formatters (tokens, cost in the configured currency, cwd, the context role, truncation). |
@@ -1316,20 +1446,21 @@ 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/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/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 entry renderer, memoized on the width so a repeat frame does not rebuild the rule. |
+| `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. |
 | `panel/settings.ts` | The curated Settings catalogue: descriptors, snapshot views and origins, value cycling, stored-value mapping, validation, and grouping, plus the per-section readers that resolve a row's leaf over the global and project documents. |
 | `panel/settings-runtime.ts` | The Settings runtime: snapshot cache, scope guards, app setters, per-leaf `bytefly.json` writes, dirty state, and change listeners. |
-| `panel/tui.ts` | `PanelComponent`, the two-section dock screen (Extensions list and Settings list), drawn from the `lib/tui/` kit. |
+| `panel/themes.ts` | Which themes the Theme row offers: the host's resolved list narrowed to the palettes under this package's `themes/`, identified by directory rather than name. |
+| `panel/tui.ts` | `PanelComponent`, the two-section dock screen (Extensions list and Settings list) and its section composition; the editing key map is `tui/editing.ts` and the shared frame is `tui/frame.ts`. |
 | `panel/commands.ts` | `/bytefly`: one command for the screen sections, the `doctor` report, the settings listing, and their text modes. |
 | `picker/types.ts` | Picker host seams (`SettingsStore`, `ExtensionResolver`, `Discovery`), the app-settings setters, and row types. |
 | `picker/resources.ts` | Pure grouping, labels, display names, and pattern helpers. |
@@ -1347,12 +1478,14 @@ columns, gauge), so the look follows the active theme.
 | `notify/dispatch.ts` | Method selection and delivery: OSC 777/99, Windows toast, `osascript`, `notify-send`, over injected seams. |
 | `notify/format.ts` | Pure notification text: session label and the turn / input / job / watch bodies. |
 | `notify/register.ts` | Registers the four triggers, loads the config at `session_start`, and owns the job- and watch-bus subscriptions. |
-| `update/check.ts` | The one registry read: the `latest` URL, the abort timeout, the `FetchLike` seam, and the failure-to-`undefined` mapping. |
+| `update/types.ts` | `PackageUpdate`, derived from Pi's public manager method, and `PackageUpdateCheck`. |
+| `update/suppress.ts` | The host shim: capture Pi's `checkForAvailableUpdates`, replace it with an empty result, and restore it on shutdown. |
+| `update/check.ts` | Pi's package list through `DefaultPackageManager`, plus the registry `GET` that names this package's version for the marker, arrow, and release URL. |
 | `update/version.ts` | Pure semver parsing and `isNewerVersion`, including prerelease precedence. |
-| `update/state.ts` | `UpdateSource` and `createUpdateState` (the newest known version, one record per load), plus `UpdateOutcome`, the four answers an explicit re-check can give. |
-| `update/cache.ts` | The disk cache: `<agentDir>/bytefly/update.json`, the 24 h window in `isFresh`, a validated read that degrades to a miss, and the atomic write. |
-| `update/format.ts` | `updateMarker`, `updateNotice`, `releaseUrl`, and `updateOutcomeText`: the header's `↑0.12.0`, the transcript notice with its release row, and the one line `/bytefly update` prints. |
-| `update/register.ts` | The lifecycle: the cache-first session-start read, the async registry call, the `PI_OFFLINE` and `tui` gates, the once-per-load announcement, the shutdown generation guard, and the `recheck()` handle `/bytefly update` calls. |
+| `update/state.ts` | `UpdateSource` and `createUpdateState` (this package's known version, one record per load), plus `UpdateOutcome`, the four answers an explicit re-check can give. |
+| `update/cache.ts` | The project-scoped snapshot: `<agentDir>/bytefly/update.json`, the cwd/package key, the 24 h window in `isFresh`, a validated read that degrades to a miss, and the atomic write. |
+| `update/format.ts` | `updateMarker`, `updateNotice`, `releaseUrl`, and `updateOutcomeText`: the header's `↑0.12.0`, the multi-package notice, and the one line `/bytefly update` prints. |
+| `update/register.ts` | The lifecycle: suppression, the cache-first session-start read, the async package-manager call, this package's version lookup, the `PI_OFFLINE` and `tui` gates, the once-per-load announcement, the shutdown generation guard, and the `recheck()` handle `/bytefly update` calls. |
 
 ## Testing
 
@@ -1375,17 +1508,18 @@ 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
 formatter (`panel/format`), the settings catalogue and its cycling
 (`panel/settings`), the scope-aware settings runtime (`panel/settings-runtime`,
 including a nested leaf write that keeps its siblings),
-the screen's rendering and key handling (`panel/tui`), and the command through
+the screen's rendering (`panel/tui`), its editing key map (`tui/editing`),
+the shared frame (`tui/frame`), and the command through
 the bytefly factory (`panel/commands`).
 The doctor surface is covered by its pure report
 formatting (`doctor/format`), its config loader (`doctor/config`), and
@@ -1394,14 +1528,15 @@ through the factory (`doctor/register`). The notify capability is covered by its
 (`notify/config`), the pure text builders (`notify/format`), method selection and
 delivery over recording seams (`notify/dispatch`), and its four triggers,
 reload, and shutdown through `registerNotify` (`notify/register`). The update
-check is covered by the version-ordering table (`update/version`), the transport
-with an injected fetch (`update/check`), the per-load store (`update/state`), the
-marker, notice, and release-URL wording (`update/format`), the cache read, write,
-and window (`update/cache`), and its lifecycle — a fresh entry reused without a
-request, a stale one re-read and rewritten, silent on failure or an older version,
-cache-only offline, skipped outside `tui`, an explicit `recheck()` that ignores
-the window, and immunity to a reply that lands after shutdown
-(`update/register`).
+surface is covered by the version-ordering table (`update/version`), Pi's package
+list and the injected registry read (`update/check`), the host shim and its
+idempotent restore (`update/suppress`), the per-load store (`update/state`), the
+marker, multi-package notice, release URL, and recheck wording (`update/format`),
+the project-scoped snapshot and its window (`update/cache`), and its lifecycle —
+a fresh matching entry reused without a package-manager call, a stale one re-read
+and rewritten, silent on failure or an empty list, cache-only offline, skipped
+outside `tui`, an explicit `recheck()` that ignores the window, and immunity to a
+reply that lands after shutdown (`update/register`).
 The user-message nameplate is covered by its pure transform
 (`message/format`, including a render through pi-tui's real `Markdown`) and its
 registration (`message/register`), plus the factory check in `extension`.