@gavin-hu/my-pi-agent 0.12.0 → 0.13.0

package/extensions/bytefly/README.md

@@ -69,13 +69,19 @@ in [`header/config.ts`](./header/config.ts).
 - **Line 1 — identity:** `pwd` and the session name on the left; git state
   (`⎇ branch · ⑂ worktree`) and the `◉` browse chip on the right.
 - **Line 2 — resources:** the context gauge and usage meters on the left, the
-  mode/alert slot (`⋮ plan`) trailing after a `╎` when present; the model and
-  thinking level on the right. The gauge is anchored at column 0, so `%` is
+  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
+  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
+  runs in its own process, and the footer prices those runs with the same rate
+  table and currency as the session so a currency change moves both. It covers
+  the last 500 child runs of the current process, and starts from zero after
+  `/resume` (the events are not session entries).
 
 ```
-~/repo/my-pi-agent                                                    ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87% ╎ ⋮ plan    opus-4.5 · high
+~/repo/my-pi-agent                                              ⎇ main · ⑂ smoke
+▰▰▰▰▰▰▱▱▱▱ 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
@@ -266,21 +272,25 @@ underneath, and `run_doctor` returns the same report as text and typed data.
 Only a missing
 *hard* requirement posts a notice at session start; everything else waits in the
 report.
-See [The bytefly screen](#the-bytefly-screen).
+See [The control center](#the-control-center).
 
 **Notify.** Off by default, one `notify` section in `bytefly.json` turns on OS
 notifications for unattended runs: when a full agent run settles, when a
-background job finishes, and when the agent opens a prompt asking for input. The
+background job finishes, when the agent opens a prompt asking for input, and when
+a `watch` wake match fires while the agent is idle. The
 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.** Once per interactive session, in the background, the loaded
+**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`. The check is skipped when `PI_OFFLINE`
-is set, makes no request outside `tui`, and a failed request is silent; see
-[Update check](#update-check).
+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).
 
 ## Commands
 
@@ -289,9 +299,10 @@ is set, makes no request outside `tui`, and a failed request is silent; see
 | `/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. |
 
 Tab completes the subcommands, extension names after `doctor`, and `refresh`;
-`/bytefly settings` takes no name.
+`/bytefly settings` and `/bytefly update` take no name.
 
 ## Behaviour by mode
 
@@ -328,7 +339,7 @@ separators, icons, status keys), and the turn separator in
 colors).
 
 Every key of every section is listed with its type, default, and bounds in the
-[configuration reference](../../docs/references/configuration-reference.md); this section
+[configuration reference](../../docs/references/bytefly-config.md); this section
 covers what that table cannot — when each section is read, and what the cost
 does when no rate matches.
 
@@ -392,7 +403,7 @@ named by `doctor`; a wrong-typed value falls back to its default, and a
 wrong-typed timezone drops the peak schedule rather than the session.
 
 The notify capability is **off by default**: `enabled: true` is the whole setup
-needed for an unattended run, and the three trigger flags then narrow what is
+needed for an unattended run, and the four trigger flags then narrow what is
 announced (see [Notifications](#notifications)).
 
 The proactive doctor check is part of the bytefly startup TUI, so it posts only
@@ -574,20 +585,25 @@ 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 ten preferences in six groups:
+switch, with its own cursor. It lists fifteen preferences in six groups:
 
 ```
 bytefly ──────────────────────────────────────────────────────────────
-  Extensions · Settings                           Global · 10 settings
+  Extensions · Settings                           Global · 15 settings
 
   Startup (1)
 ❯ ◻ Bytefly startup TUI                                            Off
-  Notifications (3)
+  Notifications (7)
   ◻ Desktop notifications                                          Off
+  ◼ Turn finished                                                   On
+  ◼ Needs input                                                     On
+  ◼ Job finished                                                    On
+  ◼ Watcher matched                                                 On
     Delivery method                                               Auto
     Notification title                                              Pi
-  Diagnostics (1)
+  Diagnostics (2)
   ◼ Proactive health check                                          On
+    Probe timeout                                                 2000
   Pricing (2)
     Currency                                                    CNY (¥)
     Cost decimals                                                    2
@@ -607,12 +623,17 @@ bytefly ────────────────────────
 |---|---|---|---|
 | Startup | Bytefly startup TUI | Pi `settings.json` (`quietStartup`) | Off, On |
 | Notifications | Desktop notifications | `notify.enabled` | Off, On |
+| Notifications | Turn finished | `notify.turnFinished` | Off, On |
+| Notifications | Needs input | `notify.needsInput` | Off, On |
+| Notifications | Job finished | `notify.jobFinished` | Off, On |
+| Notifications | Watcher matched | `notify.matchFound` | Off, On |
 | Notifications | Delivery method | `notify.method` | Auto, OSC 777, OSC 99, Windows toast, macOS, Linux |
 | Notifications | Notification title | `notify.title` | Text, up to 40 characters |
 | Diagnostics | Proactive health check | `doctor.proactive` | Off, On |
+| Diagnostics | Probe timeout | `doctor.timeoutMs` | Number, 100–30000 ms |
 | Pricing | Currency | `price.currency.code` | CNY, USD |
 | Pricing | Cost decimals | `price.currency.decimals` | 0, 1, 2, 3, 4 |
-| Transcript | Rail glyph | `chrome.rail` | `╎`, `│`, `┃`, `▏` |
+| Transcript | Rail glyph | `chrome.rail` | Text, exactly one column |
 | Transcript | Output padding | Pi `settings.json` | 0, 1 |
 | Terminal | Hardware cursor | Pi `settings.json` | Off, On |
 
@@ -620,7 +641,8 @@ Choosing **Currency** also writes that currency's default precision. Both rows
 stay editable afterwards, so the footer follows the explicit values.
 
 `Space` (or `Enter`) changes the focused row: a boolean toggles, an enum cycles
-forward, and a text row opens an inline editor on its value. The detail pane names the source, describes the preference, and shows
+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
@@ -635,7 +657,7 @@ 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 six `bytefly.json` rows and a
+scope therefore lists the twelve `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
@@ -645,14 +667,19 @@ malformed document is refused with a notice instead of overwritten.
 The non-`tui` form prints the headline, the groups, and `Label: Value` rows:
 
 ```
-bytefly: Settings · Global · 9 settings
+bytefly: Settings · Global · 15 settings
 
 Startup (1)
   Bytefly startup TUI: Off
 
-Notifications (2)
+Notifications (7)
   Desktop notifications: Off
+  Turn finished: On
+  Needs input: On
+  Job finished: On
+  Watcher matched: On
   Delivery method: Auto
+  Notification title: Pi
 ...
 ```
 
@@ -664,6 +691,14 @@ means reduced capability — an optional package that is absent, a config file
 that fails to parse, a login that has not happened. Doctor never changes
 anything and never installs anything.
 
+`web-access` publishes what it resolved at `session_start`, so the report names
+the search provider and why it won (an explicit choice, the `auto` rule, or the
+keyless default), and — when the provider takes a key and no literal `apiKey` is
+set — its API-key variable and whether that variable is set. The key value is
+never part of the report, only its variable name. Reachability is the one check
+that touches the network, so it runs only on an explicit `/bytefly refresh`:
+a session-start check stays offline.
+
 `/bytefly <extension>` narrows the same screen to that extension; `Enter`
 expands its findings, including the checks that passed, into the free height.
 `/bytefly refresh` ignores the findings cached earlier in the session. Every
@@ -718,7 +753,7 @@ the same entry in `lib/requirements.ts`, so the two cannot drift.
 
 The notify capability exists for unattended runs: start a long turn, leave the
 terminal, and get a desktop notification when Pi needs you — or when it is done.
-It fires on three events, each independently switchable in the `notify` section
+It fires on four events, each independently switchable in the `notify` section
 of `bytefly.json` (see [Configuration](#configuration)):
 
 - **A run settled** (`agent_settled`). Pi finished the turn and waits for the
@@ -731,6 +766,12 @@ of `bytefly.json` (see [Configuration](#configuration)):
 - **A background job finished.** The [job](../job/) extension announces each
   terminal transition on the shared `pi.events` bus
   (`my-pi-agent/job-finished`); bytefly listens and never imports it.
+- **A watcher matched.** A [watch](../watch/) whose `wake` is on matched while the
+  agent was idle, and announced it on `my-pi-agent/watch-match` with the cycle's
+  count, the watcher, and its newest line. The body names that line, sanitized and
+  clipped to 80 characters, because the line is the alert: a watch usually tails a
+  build or an error log. A match the agent was busy for does not notify — it is
+  collected for the next turn instead.
 
 ### Delivery method
 
@@ -777,6 +818,7 @@ reports it once, in the two places it already owns:
  bytefly · 0.12.0 is available
  ╎ ◌ current · v0.11.4
  ╎ ◌ 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
@@ -796,10 +838,27 @@ 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. Nothing is cached to disk and nothing is retried, so a
-session that starts offline simply sees no marker. `PI_OFFLINE` (Pi's own
-switch) turns the check off; `PI_SKIP_VERSION_CHECK` only governs Pi's
-`pi.dev` request.
+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
+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.
 
 ## Limitations
 
@@ -814,15 +873,16 @@ switch) turns the check off; `PI_SKIP_VERSION_CHECK` only governs Pi's
 - **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.
-- **The rail glyph picker is curated.** Four one-column glyphs are offered; a
-  custom glyph is still a `bytefly.json` edit.
-- **Settings cover scalars only.** A row is a boolean, a short enum, or a short
-  string. The per-trigger notify flags (`notify.turnFinished`, `needsInput`,
-  `jobFinished`), arrays (`doctor.skip`), a numeric range (`doctor.timeoutMs`),
-  the `rates` table, and `price.peak` are still `bytefly.json` edits.
-- **`doctor` is a reserved first argument.** `/bytefly doctor` always selects the
-  report, so an extension literally named `doctor` cannot be narrowed to by
-  name. `settings` is reserved the same way.
+- **Arrays and tables stay JSON.** A row is one boolean, enum, string, or number.
+  `doctor.skip` (an array), the `rates` table, and `price.peak` (a nested object)
+  are still `bytefly.json` edits; every scalar preference has a row.
+- **A custom rail glyph must be one column.** The editor refuses anything else,
+  because a two-column glyph would push every railed body one cell right; the
+  former four-glyph menu is now the description's example list.
+- **`doctor`, `settings`, and `update` are reserved first arguments.**
+  `/bytefly doctor` always selects the report, so an extension literally named
+  `doctor` cannot be narrowed to by name; `settings` and `update` are reserved
+  the same way.
 - **The picker manages only the `extensions` resource type.** Skills, prompts,
   and themes are handled by Pi's own `pi config`.
 - **Built-in extensions are not listed** (`builtin:mcp`, `builtin:codemode`, …):
@@ -833,17 +893,19 @@ switch) turns the check off; `PI_SKIP_VERSION_CHECK` only governs Pi's
   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.
-- **One check per session, with no refresh.** It runs at `session_start` in
-  `tui` mode; `/bytefly` and `doctor` do not report it, nothing is cached to
-  disk, and a failed or slow request is simply not retried that session.
+- **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`.
 - **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.
-- **No auto-update and no release notes.** The notice names a command instead
-  of running one, and the notice renderer has no link support, so there is no
-  changelog URL.
+- **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
+  click through from the transcript.
 - **Project toggles are two-state per press** (`enable`/`disable`). `x` clears
   the override, which is the third state; a resource with no project entry in
   `pi config` is still managed there.
@@ -915,8 +977,8 @@ switch) turns the check off; `PI_SKIP_VERSION_CHECK` only governs Pi's
 - No status chip for the doctor report: it is on demand plus one notice, not a
   permanent footer segment.
 - No notification for individual tool calls, message turns, or subagent steps:
-  the three triggers — a settled run, a prompt mid-run, a finished job — are the
-  whole surface.
+  the four triggers — a settled run, a prompt mid-run, a finished job, a watcher
+  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
@@ -947,10 +1009,10 @@ rather than showing a wrong value.
 | 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, when `PI_OFFLINE` is off, fires `fetchLatestVersion()` without awaiting, so the handler never holds the prompt. 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. A generation counter drops a reply that lands after `session_shutdown`, and a per-load flag keeps it to one announcement. |
-| 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. |
+| 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. |
+| 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 nothing to the session or a file. |
+| 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. |
 
 ## Design notes
@@ -1041,6 +1103,10 @@ rather than showing a wrong value.
 - **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".
+- **Child spend is a second figure.** The footer never adds a subagent's tokens to
+  the session's; it prices the `my-pi-agent/subagent-finished` events with the
+  same pricer and renders them as `↳`, so "this session" keeps meaning the
+  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
@@ -1137,16 +1203,18 @@ rather than showing a wrong value.
 - **The install hint has one home.** `document` and `web-access` format their
   tool errors from the same `REQUIREMENTS` entries `doctor` prints, so a user
   reads the same command whether a tool failed or the report named it.
-- **Settings are a curated table, not a schema walker.** Eleven rows prove the
-  row types — a boolean, an enum, and a short string with its own rule — both
-  scopes, both write paths, and one nested leaf (`price.currency.decimals`). A row states its section and the path to its
-  leaf, and one reader per section resolves it project-over-global-over-defaults
-  through the same normalizer the extension loads with, so the screen and the
-  runtime cannot disagree about a value. A generic walker would expose keys the
-  screen cannot edit safely yet — arrays, nested tariffs, free text,
-  credentials — so the catalogue grows one proven family at a time. App rows are
-  Global-only because Pi's setters write the personal file; Project scope lists
-  only the `bytefly.json` rows it can actually write.
+- **Settings are a curated table, not a schema walker.** The rows cover every
+  scalar preference across four kinds — a boolean, an enum, a string with
+  its own rule, and a number — both scopes, both write paths, and one nested leaf
+  (`price.currency.decimals`). A row states its section and the path to its leaf,
+  and one reader per section resolves it project-over-global-over-defaults through
+  the same normalizer the extension loads with, so the screen and the runtime
+  cannot disagree about a value; a text row's rule calls the same predicate the
+  loader uses, so an accepted value is never replaced on the next read. A generic
+  walker would expose keys the screen cannot edit safely — arrays, nested
+  tariffs, credentials — so the catalogue grows one proven family at a time. App
+  rows are Global-only because Pi's setters write the personal file; Project
+  scope lists only the `bytefly.json` rows it can actually write.
 - **The doctor is quiet unless the bytefly startup TUI is on.** Only `missing`
   findings post a notice, only for enabled extensions, only with a UI, only once
   per session, and only when Pi's `quietStartup` is `true` — the same state that
@@ -1190,7 +1258,7 @@ elapsed counter 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). The chrome and the screen are drawn from
+behind the header marker, its disk cache, and the on-demand re-check). 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.
 
@@ -1257,13 +1325,14 @@ columns, gauge), so the look follows the active theme.
 | `notify/types.ts` | `NotifyConfig`, `NotifyMethod`, and the method list. |
 | `notify/config.ts` | The `notify` section of `bytefly.json`: defaults, validation, loader. |
 | `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 bodies. |
-| `notify/register.ts` | Registers the three triggers, loads the config at `session_start`, and owns the job-bus subscription. |
+| `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/version.ts` | Pure semver parsing and `isNewerVersion`, including prerelease precedence. |
-| `update/state.ts` | `UpdateSource` and `createUpdateState`: the newest known version, one record per load. |
-| `update/format.ts` | `updateMarker` and `updateNotice`: the header's `↑0.12.0` and the two-row transcript notice. |
-| `update/register.ts` | The session-start check: the async read, the `PI_OFFLINE` and `tui` gates, the once-per-load announcement, and the shutdown generation guard. |
+| `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. |
 
 ## Testing
 
@@ -1303,13 +1372,16 @@ formatting (`doctor/format`), its config loader (`doctor/config`), and
 registration, the proactive notice, the session cache, and `run_doctor`
 through the factory (`doctor/register`). The notify capability is covered by its section loader
 (`notify/config`), the pure text builders (`notify/format`), method selection and
-delivery over recording seams (`notify/dispatch`), and its three triggers,
+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 and notice wording (`update/format`), and its lifecycle — once per load,
-silent on failure or an older version, skipped offline and outside `tui`, and
-immune to a reply that lands after shutdown (`update/register`).
+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`).
 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`.

package/extensions/bytefly/chrome.ts

@@ -50,8 +50,13 @@ export const DEFAULT_RAIL_GLYPH: string = GLYPHS.divider;
 
 export const DEFAULT_CHROME_CONFIG: ChromeConfig = { rail: DEFAULT_RAIL_GLYPH };
 
-/** Whether `value` is a single, unstyled terminal column. */
-function isRailGlyph(value: string): boolean {
+/**
+ * Whether `value` is a single, unstyled terminal column.
+ *
+ * The Settings row validates with this same function, so the editor cannot save
+ * a glyph the next read would replace.
+ */
+export function isRailGlyph(value: string): boolean {
 	// Control characters first: a bare ESC confuses a width measurement.
 	if (/[\u0000-\u001f\u007f]/.test(value)) return false;
 	return [...value].length === 1 && visibleWidth(value) === 1;

package/extensions/bytefly/doctor/register.ts

@@ -16,6 +16,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { WEB_SEARCH_PROVIDER_CHANNEL } from "../../../lib/events.ts";
 import { missingFindings } from "../../../lib/requirements.ts";
 import { loadConfig } from "./config.ts";
 import { warningNotice } from "./format.ts";
@@ -39,6 +40,11 @@ export function registerDoctor(pi: ExtensionAPI, deps: DoctorDeps = {}): DoctorR
 
 	registerTools(pi, runtime);
 
+	// `web-access` publishes what it resolved at session start; the doctor reports
+	// the provider, its key variable, and (on a refresh) its endpoint from that,
+	// without importing the extension.
+	pi.events.on(WEB_SEARCH_PROVIDER_CHANNEL, (facts) => runtime.noteSearchFacts(facts));
+
 	pi.on("session_start", async (_event, ctx) => {
 		const config = loadConfig(ctx.cwd);
 		runtime.configure({ cwd: ctx.cwd, config });

package/extensions/bytefly/doctor/runtime.ts

@@ -9,6 +9,7 @@
  */
 
 import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { WebSearchProviderEvent } from "../../../lib/events.ts";
 import { readJsonResult } from "../../../lib/config.ts";
 import { isExtensionEnabled } from "../../../lib/env.ts";
 import {
@@ -47,10 +48,28 @@ export interface DoctorRuntime {
 	probeAll(options?: { refresh?: boolean }): Promise<ExtensionReport[]>;
 	/** The cached reports from the last probe, if any. */
 	peek(): ExtensionReport[] | undefined;
-	/** Drop the cached reports; the configured cwd is kept. */
+	/** Remember the search provider `web-access` published for this session. */
+	noteSearchFacts(facts: unknown): void;
+	/** Drop the cached reports and the published facts; the configured cwd is kept. */
 	reset(): void;
 }
 
+/** How long a reachability probe may take; a doctor refresh is not a fetch. */
+const REACH_TIMEOUT_MS = 3_000;
+
+/**
+ * Probe a URL's reachability. Any HTTP answer proves the host is there; a 5xx is
+ * reported because it usually means the server is up but broken.
+ */
+async function probeReach(url: string): Promise<{ ok: boolean; error?: string }> {
+	try {
+		const response = await fetch(url, { method: "GET", signal: AbortSignal.timeout(REACH_TIMEOUT_MS) });
+		return response.status < 500 ? { ok: true } : { ok: false, error: `HTTP ${response.status}` };
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
 /** Build a runtime over the host's `exec`, with `deps.seams` for tests. */
 export function createDoctorRuntime(
 	pi: Pick<ExtensionAPI, "exec">,
@@ -59,9 +78,11 @@ export function createDoctorRuntime(
 	let cwd = process.cwd();
 	let config: DoctorConfig = DEFAULT_CONFIG;
 	let cached: ExtensionReport[] | undefined;
+	/** What `web-access` published at session start; absent when it did not load. */
+	let searchProvider: WebSearchProviderEvent | undefined;
 
-	/** The full seam set for the current session. */
-	const seams = (): ProbeSeams => ({
+	/** The full seam set for the current session; `refresh` is the caller's. */
+	const seams = (refresh: boolean): ProbeSeams => ({
 		exec: async (command, args) => {
 			const result = await pi.exec(command, args, { timeout: config.timeoutMs });
 			return { code: result.code };
@@ -72,6 +93,9 @@ export function createDoctorRuntime(
 		isEnabled: (extension) => isExtensionEnabled(extension) && !config.skip.includes(extension),
 		notify: notifySeam(cwd),
 		isTTY: process.stdout.isTTY === true,
+		searchProvider: () => searchProvider,
+		reach: probeReach,
+		refresh,
 		...deps.seams,
 	});
 
@@ -84,20 +108,26 @@ export function createDoctorRuntime(
 
 		async probeRequired() {
 			// Concurrent: a probe is a short-lived process, and session start must
-			// not wait on the sum of every timeout.
-			return Promise.all(hardRequirementExtensions().map((name) => probeExtension(name, seams())));
+			// not wait on the sum of every timeout. Never a refresh: this runs before
+			// anyone asked, so no probe may touch the network.
+			return Promise.all(hardRequirementExtensions().map((name) => probeExtension(name, seams(false))));
 		},
 
 		async probeAll(options = {}) {
 			if (cached && !options.refresh) return cached;
-			cached = await probeDeclared(seams(), Object.keys(REQUIREMENTS));
+			cached = await probeDeclared(seams(options.refresh === true), Object.keys(REQUIREMENTS));
 			return cached;
 		},
 
 		peek: () => cached,
 
+		noteSearchFacts(facts) {
+			searchProvider = facts && typeof facts === "object" ? (facts as WebSearchProviderEvent) : undefined;
+		},
+
 		reset() {
 			cached = undefined;
+			searchProvider = undefined;
 		},
 	};
 }

package/extensions/bytefly/footer/collect/snapshot.ts

@@ -7,9 +7,14 @@
  * hold thousands of entries and the footer renders on every frame. The config is
  * captured when the reader is built, so re-reading the file means building a new
  * reader (which is what installing the footer does).
+ *
+ * The child-run ledger's version joins the memo key: a finished subagent invalidates
+ * the same way an appended entry does, so the roll-up appears on the next frame
+ * without re-pricing every frame.
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { DelegationLedger } from "../delegation.ts";
 import { createPricer } from "../price/price.ts";
 import type { ByteflyConfig } from "../price/types.ts";
 import type { ContextInfo, FooterData, StatusSnapshot } from "../types.ts";
@@ -23,22 +28,26 @@ import { emptyUsage, usageRecords } from "./entries.ts";
  * are stale; this avoids copying the full entry list and rebuilding the session
  * projection per frame. Pi's own footer memoizes its stats on the same idea.
  */
-export function createSnapshotReader(config: ByteflyConfig) {
+export function createSnapshotReader(config: ByteflyConfig, delegation: DelegationLedger) {
 	const price = createPricer(config);
 	let key: string | null = null;
 	let usage = emptyUsage();
+	let delegationTotals = { runs: 0, usage: emptyUsage() };
 	let cacheHitRate: number | null = null;
 	let context: ContextInfo = { tokens: null, contextWindow: 0, percent: null };
 
 	return (ctx: ExtensionContext, footerData: FooterData): StatusSnapshot => {
 		const session = ctx.sessionManager;
 		const current = ctx.model;
-		const nextKey = `${session.getSessionId()}:${session.getLeafId() ?? ""}:${current?.provider ?? ""}/${current?.id ?? ""}`;
+		const nextKey = `${session.getSessionId()}:${session.getLeafId() ?? ""}:${current?.provider ?? ""}/${current?.id ?? ""}:${delegation.version()}`;
 		if (nextKey !== key) {
 			const active = current ? { provider: current.provider, model: current.id } : undefined;
 			const scanned = usageRecords(session.getEntries(), active);
 			usage = price(scanned.records);
 			cacheHitRate = scanned.cacheHitRate;
+			// The child runs are priced by the same pricer, so a currency or rate
+			// change moves both numbers together — and neither is folded into the other.
+			delegationTotals = { runs: delegation.runs(), usage: price(delegation.records()) };
 
 			const usageInfo = ctx.getContextUsage();
 			context = {
@@ -65,6 +74,7 @@ export function createSnapshotReader(config: ByteflyConfig) {
 			currency: config.currency,
 			cacheHitRate,
 			providerCount: footerData.getAvailableProviderCount(),
+			delegation: delegationTotals,
 		};
 	};
 }

package/extensions/bytefly/footer/config.ts

@@ -16,7 +16,13 @@ export const CONFIG = {
 	gauge: { full: GLYPHS.gaugeFull, empty: GLYPHS.gaugeEmpty, widths: [10, 5, 3, 0] as const },
 	/** Separators printed before grouped and other segments. */
 	separators: { group: SEPARATORS.group, item: SEPARATORS.item },
-	icons: { branch: GLYPHS.branch, detached: GLYPHS.detached, worktree: GLYPHS.worktree, browse: GLYPHS.browse },
+	icons: {
+		branch: GLYPHS.branch,
+		detached: GLYPHS.detached,
+		worktree: GLYPHS.worktree,
+		browse: GLYPHS.browse,
+		delegation: GLYPHS.delegation,
+	},
 	/** Status key the worktree extension uses; routed to line 1's right zone. */
 	worktreeStatusKey: STATUS_KEYS.worktree,
 	/** Status key the file-browse extension uses; routed to line 1's right zone. */