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

package/extensions/bytefly/README.md

@@ -8,8 +8,9 @@ records each completed turn in the transcript, one keyboard-driven screen with t
 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
@@ -34,7 +35,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 line, the
-two-section control center, notifications, and the published-version check.
+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
@@ -75,7 +76,7 @@ identity, and grouped help are tuned in
   (`⎇ 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
@@ -86,7 +87,7 @@ identity, and grouped help are tuned in
 
 ```
 ~/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
@@ -94,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
@@ -107,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
@@ -318,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
 
@@ -335,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.
@@ -374,8 +377,8 @@ separators, icons, status keys), and the turn separator in
 [`separator/config.ts`](./separator/config.ts) (glyph, label prefix, padding,
 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.
 
@@ -472,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
@@ -519,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.
@@ -582,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
@@ -606,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
@@ -635,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 twenty-eight preferences in ten groups:
+switch, with its own cursor. It lists twenty-nine preferences in ten groups:
 
 ```
 bytefly ──────────────────────────────────────────────────────────────
-  Extensions · Settings                           Global · 28 settings
+  Extensions · Settings                           Global · 29 settings
 
   Startup (1)
 ❯ ◻ Bytefly startup TUI                                            Off
@@ -662,7 +669,8 @@ bytefly ────────────────────────
     Rail glyph                                                       ╎
     Achieved goal                                                  Hide
     Output padding                                                   1
-  Terminal (1)
+  Terminal (2)
+    Theme                                                       system
   ◻ Hardware cursor                                                Off
   Worktree (4)
     ◼ Fetch remote                                                 On
@@ -704,6 +712,7 @@ bytefly ────────────────────────
 | 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 |
@@ -720,24 +729,35 @@ bytefly ────────────────────────
 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, 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
+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 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.
+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
@@ -758,7 +778,7 @@ 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 · 28 settings
+bytefly: Settings · Global · 29 settings
 
 Startup (1)
   Bytefly startup TUI: Off
@@ -810,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. |
@@ -901,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
@@ -912,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.
@@ -964,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.
@@ -986,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
@@ -1105,15 +1142,15 @@ rather than showing a wrong value.
 | 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, 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. |
+| 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
 
@@ -1155,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
@@ -1190,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
@@ -1211,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:
@@ -1229,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.
@@ -1335,21 +1377,27 @@ 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
 
@@ -1359,8 +1407,8 @@ calculation), `message/` (the user-message marker), `notice/` (the shared notice
 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.
 
@@ -1376,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). |
@@ -1400,7 +1448,7 @@ columns, gauge), so the look follows the active theme.
 | `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, 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/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. |
@@ -1411,7 +1459,8 @@ columns, gauge), so the look follows the active theme.
 | `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. |
@@ -1429,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
 
@@ -1467,7 +1518,8 @@ 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
@@ -1476,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`.