@gavin-hu/my-pi-agent 0.8.1 → 0.10.0

package/extensions/bytefly/README.md

@@ -1,12 +1,13 @@
-# bytefly — the TUI header, footer, turn rule, extension screen, and notifications
+# bytefly — the TUI header, footer, user-message marker, turn rule, extension screen, and notifications
 
 `bytefly` owns the terminal chrome, configuration, and diagnostics surfaces
 this package adds: one themed startup header whose two-tone nameplate carries
 the agent and chrome identities, one compact, colorful, width-adaptive two-line
-footer, a labeled rule that marks each completed turn in the transcript, one
-keyboard-driven screen that lists every resolved Pi extension with its enable
-checkbox and its health, and an opt-in notify capability that raises an OS
-notification when a run finishes, a job finishes, or the agent asks for input.
+footer, a two-row `You` nameplate that opens each user message, a labeled rule that
+marks each completed turn in the transcript, one keyboard-driven screen that
+lists every resolved Pi extension with its enable checkbox and its health, and
+an opt-in notify capability that raises an OS notification when a run finishes,
+a job finishes, or the agent asks for input.
 DeepSeek is priced from the provider's published yuan rates and peak tariff by
 default, and any other model can be priced from your own rates when Pi's catalog
 does not match what a provider actually charges.
@@ -17,53 +18,63 @@ pi -e .                               # load the whole @gavin-hu/my-pi-agent pac
 pi install ./                         # install the package
 ```
 
+## Tool rendering
+
+How the `run_doctor` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/run_doctor.png" alt="The run_doctor tool's result: the call line and an indented body with the doctor headline and the missing and degraded findings" width="100%">
+
 ## What it does
 
-The extension owns five surfaces: the startup header, the footer, the rule
-between completed turns, the extension screen, and notifications.
+The extension owns nine surfaces: the startup header, the footer, the
+user-message marker, the rule between completed turns, the notice block for
+shared transcript notices, the tool-block frame, the live working counter, the
+extension screen, and notifications.
 
 **Header.** A nameplate: a two-tone half-block mark from the active theme's
-`accent` / `warning` tokens, the agent identity (`Pi` and its version), the
-chrome identity (`enhanced by bytefly` and the package version), a `─` rule, and
-a grouped help block. The help keys resolve live from Pi's keybindings, so a
-rebound key shows the user's chord; the identity and help text are `muted`/`dim`
-so the mark keeps the eye. It is installed only in interactive (`tui`) sessions,
-and on terminals that cannot render half blocks the mark falls back to a
-two-tone `Pi` wordmark.
+`accent` / `warn` roles, the agent identity (`Pi`, bold, and its version), the
+chrome identity (`enhanced by bytefly` and the package version), a signature
+rule whose `accent` lead sits under the mark, and a grouped help block. The help
+keys resolve live from Pi's keybindings, so a rebound key shows the user's
+chord; the identity and help text are `meta` / `faint` so the mark keeps the
+eye. It is installed only in interactive (`tui`) sessions, and on terminals that
+cannot render half blocks the mark falls back to a two-tone `Pi` wordmark.
 
 ```
  █▀█  Pi v1.2.0
- █▀ █ enhanced by bytefly v0.7.0
+ █▀ █ enhanced by bytefly v0.8.1
  ─────────────────────────────────────────────────
-  escape to interrupt · ctrl+c to clear · ctrl+d to exit (empty)
-  ctrl+o to expand tools · ctrl+t to expand thinking · ctrl+l to select model
-  / commands · ! bash · !! bash (no context) · /bytefly extensions
+   escape to interrupt · ctrl+c to clear · ctrl+d to exit (empty)
+   ctrl+o to expand tools · ctrl+t to expand thinking · ctrl+l to select model
+   / commands · ! bash · !! bash (no context) · /bytefly extensions
 ```
 
 As the terminal narrows, the identity sheds the chrome version, then the chrome
 line, then the agent name, and the help rows drop whole keys, so nothing wraps or
-clips mid-word. The mark, tokens, identity, and grouped help are tuned in
-[`header/config.ts`](./header/config.ts).
+clips mid-word. The nameplate sits on the transcript margin, which follows Pi's
+`outputPad` (the value the tool frame and the notice use too), and the help hangs
+one body indent inside it. The mark, tokens, identity, and grouped help are tuned
+in [`header/config.ts`](./header/config.ts).
 
 **Footer.** Two lines, each with a left and right zone:
 
 - **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
+  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
   always in the same place.
 
 ```
 ~/repo/my-pi-agent                                                    ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87% │ ⋮ plan    opus-4.5 · high
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87% ╎ ⋮ plan    opus-4.5 · high
 ```
 
 (The examples show the default `¥` symbol. For a model the built-in table does
 not cover, the number stays Pi's recorded USD amount — 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
@@ -76,7 +87,7 @@ 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
 ```
 
 ```
@@ -88,7 +99,7 @@ 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
@@ -107,11 +118,122 @@ rates and peak tariff built into [`footer/price/config.ts`](./footer/price/confi
 ▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥2.50 · ↑42k ↓8.0k · R96k CH 87%             opus-4.5 · high
 ```
 
+**User message.** Every user message opens with a two-row `You` nameplate —
+the label over a rule that spans the width — above the message:
+
+```
+You
+────────────────────────────────────
+
+the message the user typed
+```
+
+It is always on in interactive sessions and has no config file. Pi renders a
+user message as Markdown and owns its colors, so bytefly's only lever is a
+`registerMarkdownTransformer`: the nameplate is a single level-2 heading whose
+text is padded so the rule wraps onto the second row, and both rows carry the
+accent because the themes point `mdHeading` at it. The block carries no fill —
+the shipped themes set `userMessageBg` to the terminal default, so it reads like
+the tool blocks. The nameplate is separated from the message by a blank line, so
+the message's own Markdown (a fence, a list, a second paragraph) parses exactly
+as it would without it, and a soft wrap of one long line stays at the margin
+because the renderer wraps it, not bytefly. The label and the rule are tuned
+in [`message/config.ts`](./message/config.ts).
+
+**Working timer.** Pi's working row shows a static `Working`, so a long run
+reads the same as a short one. While the row is up, bytefly advances its
+message once a second and hands it back to Pi when the row comes down:
+
+```
+Working… 12s
+```
+
+The count is tied to the row's visibility: it starts on `turn_start`, the event
+the host shows the working indicator on, and stops on `agent_end`, where the
+host clears it, then again on `session_shutdown`. Turns inside one run do not
+restart it — the host keeps the same row up across turns — so the count covers
+the whole run, tool calls included. A retry is a new run, so the count restarts
+when its row reappears. The word and the interval are tuned in
+[`working/config.ts`](./working/config.ts).
+
 **Turn separator.** After each completed turn the extension appends an inert
 entry and draws a centered `╌╌╌ turn N ╌╌╌` rule across the transcript; see
 [Turn separator](#turn-separator). No config file is needed and there is no
 command.
 
+**Notices.** Any extension in the package can post a transcript notice under the
+shared `my-pi-agent/notice` type; bytefly draws it at the transcript's margin —
+a `source · title` headline at the margin, then rail-led rows, each with its own
+severity glyph:
+
+```
+job · 2 background jobs finished
+╎ ✓ j1 build · exit 0
+╎ ✕ j2 test · exit 1
+```
+
+The rail is painted by the notice's worst severity, so a failure reads red at the
+edge like an errored tool result.
+
+`job` and `watch` post one when a background job finishes or a watched line
+matches, so the report the model reads is visible too. The type and the
+`NoticeDetails` shape are the shared contract in
+[`lib/notice.ts`](../../lib/notice.ts), and the severity glyphs and item cap
+are tuned in [`notice/config.ts`](./notice/config.ts). Every field is sanitized
+and clipped at the boundary, and a message without `details` keeps Pi's default
+custom-message box.
+
+**Tool blocks.** Every tool block leads with the tool's own call line as the
+headline — the tool name in the theme's tool-title colour — and its result body
+sits two columns in directly beneath it, led by the transcript rail, instead of
+Pi's filled status background:
+
+```
+read src/app.ts
+╎ const answer = 42;
+```
+
+The two tools that mutate a file, `edit` and `write`, carry their result on the
+call body — the edit diff, the written file content — so that body is railed
+like any other result. There is no status band: the diff's own red/green line
+colours, with the changed words in reverse video, and the `edit` / `write`
+headline are what mark a file change.
+
+A `registerToolRenderer` resolver switches the row to `renderShell: "self"`,
+leaves the call's own first line as the headline, and indents the rest of the
+call and the whole result under it. A shell call's `$` / `>` prompt becomes the
+tool name and the command is repainted in the body colour, and a primary subject
+(a path, URL, query, pattern) is demoted to the body colour too, so the name is
+the call line's only accent (`bash bun run check`, `read src/app.ts`). The
+tool's own
+`renderCall`/`renderResult` are passed through, so syntax highlighting, diffs,
+previews, and truncation notices are unchanged — only the frame is bytefly's.
+The body carries the transcript rail, painted by status (a running result takes
+the accent, a failure red, a finished one neutral) and drawn with the glyph from
+the `chrome.rail` setting. A result frame is always railed; a call frame is railed
+only for `edit` and `write`, whose call body carries the result — every other
+call's headline and continuation lines stay plain-indented. A call line that
+does not fit wraps, and Pi drops the tool name onto its own line when the
+subject it carries (a long path) is one unbreakable token; those continuation
+lines are still the call, so they stay unrailed and lose the accent too, and the
+rail begins with the result underneath. A tool with
+no renderer of its own is framed around a generic call/result fallback, whose
+call line reads like a built-in — the leading string argument bare, the rest as
+trailing options (`open_path src/app.ts`) — rather than dumping raw `key=value`
+pairs. A tool that draws its own shell (`edit`) is framed too:
+`renderShell: "self"` only tells Pi not to draw its box around the renderer, so
+its diff would otherwise sit at the wrong indent; the frame drops the blank
+edges its own `Box` pads itself with, and hands it a theme whose `bg` is inert so
+it never paints a band the rest of the transcript does not have.
+
+The call line is one colour grammar, shared with Pi's built-ins: the tool name is
+`toolTitle` and bold and is the line's only accent; a primary subject (a query, a
+URL, a path, a status) reads in the body role (`label`), counts and summaries are
+`muted`, trailing options are `dim`, and the result body is `toolOutput`. The
+shipped themes point `toolTitle` at the accent and `label` at the body colour, so
+the name is the call line's one accent and the subject follows as body text; a
+theme that maps `toolTitle` elsewhere is respected rather than overridden.
+
 **Extension screen.** `/bytefly [extension] [refresh]` opens a keyboard-driven
 dock list of every Pi extension the session resolves — across personal settings
 and, when trusted, the project — one row per extension with its enable checkbox
@@ -133,19 +255,18 @@ the platform notifier (`osascript`, `notify-send`); see
 | Command | What it does |
 |---|---|
 | `/bytefly [extension] [refresh]` | Open the extension screen. In `tui` it mounts a docked list; every other mode prints the grouped listing, or one extension's full findings when named. |
-| `/extensions` | Alias for `/bytefly`: the same screen and the same handler. |
-| `/doctor [extension] [refresh]` | Alias for `/bytefly`: the same screen and the same handler. |
+| `/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. |
 
-Tab completes extension names and `refresh` for all three commands.
+Tab completes `doctor`, extension names, and `refresh`.
 
 ## Behaviour by mode
 
 The header, footer, and turn rule are installed only in interactive (`tui`)
 sessions and are always on; every mode loads the extension, and non-TUI modes
 change nothing. The screen is available in every mode: in `tui`, `/bytefly` and
-its `/extensions` and `/doctor` aliases mount the docked screen, while RPC,
-JSON, and print modes print the grouped listing with a per-row health suffix and
-the headline, or that extension's full findings when one is named. The
+`/bytefly doctor` mount the docked screen, while RPC, JSON, and print modes
+print the grouped listing with a per-row health suffix and the headline, or that
+extension's full findings when one is named. The
 proactive session-start warning is skipped when there is no UI. Notify runs in
 every mode and picks its method from the environment; the OSC methods need a
 TTY, so a print/JSON/RPC run gets an OS-level notification or none.
@@ -153,14 +274,19 @@ TTY, so a print/JSON/RPC run gets an OS-level notification or none.
 ## Configuration
 
 The header is tuned in [`header/config.ts`](./header/config.ts) — the mark and
-identity theme tokens, the padding and tagline, and the grouped help entries
-(each naming a Pi keybinding resolved live or a raw command prefix). The footer's
+identity theme tokens, the tagline, and the grouped help entries (each naming a
+Pi keybinding resolved live or a raw command prefix). The footer's
 content and layout are tuned in [`footer/config.ts`](./footer/config.ts) —
 thresholds, gauge
 glyphs and widths, separators, icons, and status keys. The turn separator has no
 JSON either: its glyph, label prefix, padding, and colors are tuned in
 [`separator/config.ts`](./separator/config.ts).
 
+The transcript rail's glyph is the one chrome value that is JSON-configurable:
+the `chrome` section's `rail` key (default `╎`) picks a single-column rail glyph,
+read at `session_start`/`session_tree`. Everything else about the chrome is tuned
+in code.
+
 Everything JSON-configurable lives in `bytefly.json`, one shared document with a
 top-level section per extension (see [Configuration](../../docs/configuration.md)).
 It is read from the global document, then `<cwd>/.pi/bytefly.json`. The old
@@ -354,7 +480,7 @@ 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`
 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.
@@ -394,10 +520,13 @@ it:
 extension Pi resolves for the session, so the list matches what actually loads.
 It merges the former extensions picker and doctor report into one row per
 extension: the picker's enable checkbox and label, the doctor's worst-severity
-glyph and summary. `/extensions` and `/doctor [extension] [refresh]` are
-registered against the same handler, so all three names open the same screen;
-`[extension]` narrows it to one extension and `refresh` re-probes the doctor
-before it opens. Tab completes extension names and `refresh`.
+glyph and summary. The screen is drawn from the design system: a label-first
+`bytefly ────` title rule, one row 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 either surface to one extension and `refresh`
+re-probes the doctor before it opens. Tab completes `doctor`, extension names,
+and `refresh`.
 
 The screen reuses Pi's own settings and package resolution (`SettingsManager`
 plus `DefaultPackageManager` with `onMissing: "skip"`), so opening it never
@@ -408,7 +537,7 @@ installs or fetches a package.
 - Omits `bytefly`'s own entrypoint from the picker groups, so the tool that
   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 (`[x]`) or disabled (`[ ]`).
+- Shows whether each one is enabled (`◼`) or disabled (`◻`).
 - Shows the worst severity for a reported extension (`✓` ok, `!` degraded, `✕`
   missing, `∅` disabled) and its summary; an extension with no doctor report
   leaves the glyph column and the summary blank rather than claiming `ok`.
@@ -524,6 +653,9 @@ control-free line before it reaches an escape sequence or a shell argument.
 
 ## Limitations
 
+- **`doctor` is a reserved first argument.** `/bytefly doctor` always selects the
+  report, so an extension literally named `doctor` cannot be narrowed to by
+  name.
 - **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`, …):
@@ -567,6 +699,11 @@ control-free line before it reaches an escape sequence or a shell argument.
 - **An explicit `method` is honored blindly.** Point `method` at a notifier the
   host lacks (or an OSC method off a TTY) and the notification is silently
   dropped; only `auto` inspects the environment.
+- **The working counter is one global row.** `setWorkingMessage` drives the
+  single working row, so bytefly and any other extension setting it race — last
+  writer wins — and the message is reset to Pi's default at `agent_end`. If the
+  row is hidden (`ctx.ui.setWorkingVisible(false)`) the counter has no surface,
+  and a reload mid-run does not resume it until the next turn.
 
 ## Non-goals
 
@@ -590,6 +727,9 @@ control-free line before it reaches an escape sequence or a shell argument.
   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
+  Pi when the working row comes down, because the extension API exposes no hook
+  to keep a finished run's total.
 
 The built-in footer's `(auto)` auto-compact indicator and `(sub)`
 subscription-cost marker are not reachable from `ExtensionContext` (there is no
@@ -600,35 +740,100 @@ rather than showing a wrong value.
 
 | Integration point | Details |
 |---|---|
-| Header | `ctx.ui.setHeader` with a custom component, replacing Pi's built-in header; installed only when `ctx.mode === "tui"`. The mark and text are drawn from the active theme's tokens, the help keys resolve live through `keyText`, and the mark falls back to a wordmark on Apple Terminal (`isAppleTerminalSession`), mirroring Pi's built-in. |
+| Header | `ctx.ui.setHeader` with a custom component, replacing Pi's built-in header; installed only when `ctx.mode === "tui"`. The nameplate insets by Pi's `outputPad` (read through `pi.getSettings()`), so it sits on the transcript margin, and the help hangs one body indent inside it. The mark and text are drawn from the active theme's tokens, the help keys resolve live through `keyText`, and the mark falls back to a wordmark on Apple Terminal (`isAppleTerminalSession`), mirroring Pi's built-in. |
 | Footer | `ctx.ui.setFooter` with a custom component, replacing Pi's built-in footer; installed only when `ctx.mode === "tui"`. |
-| Screen command | `pi.registerCommand("bytefly"`, `"extensions"`, and `"doctor"`) share one handler: `tui` mounts a dock screen via `ctx.ui.custom()` with the rails suppressed, other modes print through `ctx.ui.notify()`. Tab completes extension names and `refresh`. |
+| User message | `pi.registerMarkdownTransformer` puts a two-row `You` nameplate (the label over a full-width rule) above each user message; one padded level-2 heading carries the accent through `mdHeading` for both rows, and the shipped themes set `userMessageBg` to the terminal default, so the block has no fill. Pi renders the result as Markdown, so the surface adds no component or color of its own. |
+| Notice | `registerMessageRenderer(NOTICE_TYPE)` draws every shared transcript notice at the margin from its `details`; the headline stays at the margin and its rows hang from the transcript rail, painted by the notice's worst severity, whose glyph comes from the shared `RailSource`. The type and shape come from `lib/notice.ts`. A message without `details` falls back to Pi's default custom-message box. |
+| Tool blocks | `registerToolRenderer` returns, for every tool, `renderShell: "self"`; `renderCall` leaves the tool's own first line as the block's headline (a shell prompt shown as the tool name, its command repainted in the body colour, and a primary subject demoted to the body colour) and indents the rest of the call two columns under it, `renderResult` indents its body the same and leads it with the status-coloured rail, and each wraps the tool's own renderer (or a generic fallback). `edit` and `write` carry their result on the call body, so that body is railed too. |
+| Screen command | `pi.registerCommand("bytefly")` takes `[doctor] [extension] [refresh]`: `tui` mounts a dock screen via `ctx.ui.custom()` with the rails suppressed; other modes print through `ctx.ui.notify()` — the grouped listing, or `run_doctor`'s report for `doctor`. Tab completes `doctor`, extension names, and `refresh`. |
 | Turn separator | `registerEntryRenderer("bytefly-separator")` draws each rule; `agent_settled` appends `pi.appendEntry("bytefly-separator", { turn })` in `tui` mode only. |
+| Working timer | `turn_start` starts a 1s tick that drives `ctx.ui.setWorkingMessage("Working… Ns")` in `tui` mode; `agent_end` restores Pi's default and cancels the tick (also on `session_shutdown`). No config file and no stored state. |
 | 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. |
 | Doctor tool | `pi.registerTool("run_doctor")`, read-only (`readOnlyHint: true`), `exposure: "direct"`, active by default, 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`; `/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. |
-| 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), and the `notify` and `doctor` sections at `session_start`. Nothing watches the document. |
+| 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. |
 | 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 only through `settings.json`. 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. |
-| Lifecycle | `session_start` installs the header and footer, points the doctor runtime at the session cwd, probes the extensions with hard requirements when `bytefly.json`'s `doctor.proactive` is on, and loads the notify config and subscribes to the job bus; `session_tree` reinstalls the header and footer; `session_shutdown` restores Pi's built-in header and footer, disposes the branch subscription, drops doctor's cached findings, and drops the notify bus subscription. |
+| Lifecycle | `session_start` installs the header and 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 loads the notify config and subscribes to the job bus; `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, and drops the notify bus subscription. |
 
 ## Design notes
 
+- **One kit, one look.** Every bytefly surface is drawn from the package's
+  `lib/tui/` design system: a role is resolved by the active theme, a rule comes
+  from `rules.ts`, a list row from `rows.ts`, a meter from `gauge.ts`, and a
+  width from `columns.ts`. Nothing in bytefly names a literal color, and a
+  theme swap re-skins the whole chrome.
+- **The user message is shaped, not painted.** Pi renders a user message as
+  Markdown and owns its colors, so bytefly's only lever is a Markdown
+  transformer: the two-row nameplate is one level-2 heading whose text is padded
+  to the width so the rule wraps below the label, and both rows take the accent
+  from the theme's `mdHeading`, because no extension API can color it directly.
+  Markdown has no multi-line heading and Pi inserts a blank line after a
+  heading block, so a single wrapped heading is the only way to keep the two
+  rows adjacent and in the accent. The block has no fill: the shipped themes set
+  `userMessageBg` to the terminal default, so it matches the tool blocks. The
+  nameplate is separated from the message by a blank line, so the message's own
+  Markdown parses unchanged and a soft wrap stays at the margin; hard-wrapping
+  Markdown here would corrupt a break inside an inline construct.
+- **A notice is one shared contract, not a foreign type.** Pi resolves a
+  custom-message renderer by exact type with no wildcard, so `lib/notice.ts`
+  owns the type and the `NoticeDetails` shape: a producer states model text and
+  renderer details once, and bytefly owns only the look. One type for every
+  producer also lets `job` and `watch` share one prune
+  (`pruneStaleNotices`) keyed on `details.source`, so neither drops the other's
+  note from context.
+- **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
+  `renderCall`/`renderResult`. bytefly replaces only the frame — Pi's filled
+  status box for an indent — and keeps every built-in's diff, syntax
+  highlighting, and truncation. The call and result are sibling components with
+  no spacer between them, so the call's headline and the result read as one
+  block; the result body hangs from the rail, and `edit`/`write` rail their call
+  body because it carries the result, except for the lines of a call line that
+  wrapped onto the body — a 121-column path under a bare `edit` is still the
+  call, not diff content, and the rail starts at the diff. A tool that renders
+  its own shell (`edit`)
+  is framed too: its blank edge lines are trimmed so the body starts under the
+  call, and it is handed a theme whose `bg` is inert so it paints no band. Each base renderer is handed its own
+  previous component (tracked in the row's `state`), never the frame: Pi gives a
+  renderer the component it returned last time, and a built-in calls `setText` on
+  it, so handing back the frame would break it. A base renderer that throws is
+  caught here too, and the frame falls back to its own call/result line at the
+  frame's pad; letting the throw reach Pi would swap in Pi's generic call line,
+  which sits a column to the left of the framed one.
+- **One frame, one left edge.** Every transcript block that is not prose shares
+  the same frame (`lib/tui/indent.ts`): a tool block, a notice, and a subagent's
+  quoted output take one indent, so they hang from one left edge instead of four,
+  and a tool result's body sits `BODY_INDENT` columns in under its headline. A
+  body and a notice row lead that body with the transcript rail, whose
+  glyph is the one configurable part (`chrome.rail`, default `╎`); a result frame
+  is always railed, and a call frame only for `edit`/`write`, whose call body
+  carries the result. Pi pads its own messages and hands the value to tool renderers
+  (`context.outputPad`) and message renderers (`options.outputPad`), but gives an
+  entry renderer none and adds its component raw, so bytefly's blocks inset
+  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.
 - **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 `accent`/`warning` and pairs it with the agent identity, the chrome
-  identity, and a grouped help block. It adds no session or model data — that is
-  the footer's job — and it stays a fixed four-plus rows so the startup
-  transcript never reflows.
+  mark from the `accent`/`warn` roles, a signature rule whose accent lead sits
+  under the mark, and pairs them with the agent identity, the chrome identity,
+  and a grouped help block. It takes its margin from Pi's `outputPad`, like the
+  tool frame and the notice, and hangs the help one body indent inside it, so the
+  header follows a non-default pad instead of assuming a column. It adds no
+  session or model data — that is the footer's job — and it stays a fixed
+  four-plus rows so the startup transcript never reflows.
 - **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".
 - **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; the bar splits them by meaning (`worktree`
@@ -648,19 +853,23 @@ 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.
   A two-token `icon count` badge (for `rewind`: `↺ 2`) compacts to `↺2`, keeping
   the count. The slot sorts an alert (a failed job) ahead of the modes and is
   droppable, so it goes before the model is clipped.
-- **Neutral by default; color means something.** Only the context gauge carries
-  status color, and it stays `muted` below 70%; cost is `muted`, the session and
-  branch are `muted`, and tokens/cache/window are `dim`, so yellow and red are
-  reserved for the gauge crossing a threshold rather than always on.
+- **Neutral by default; color means something.** A tool block carries no status
+  colour except the accent tool name and the status-coloured result rail; an
+  informational notice leads with `muted`; a failure is red only where the
+  tool's own output says so, so the transcript is not a wall of green.
+  The context gauge is the other coloured surface: it stays `muted` below 70%,
+  cost is `muted`, the session and branch are `muted`, and tokens/cache/window are
+  `dim`, so yellow and red are reserved for a threshold or a failure rather than
+  always on.
 - **Data is read fresh, except the usage scan.** The component resolves the
   theme through a getter and reads a fresh snapshot each render. The expensive
   part — summing token/cost totals across the session — is memoized by
@@ -722,7 +931,7 @@ rather than showing a wrong value.
   reads the same command whether a tool failed or the report named it.
 - **The doctor is quiet by default at startup.** Only `missing` findings warn,
   only for enabled extensions, only with a UI, and only once per session;
-  `degraded` findings — including a malformed config — wait in `/doctor`, because
+  `degraded` findings — including a malformed config — wait in `/bytefly doctor`, because
   a session that nags about an optional package is worse than one that never
   mentions it.
 - **Probe the real thing.** `subagent`'s requirement resolves through the same
@@ -735,15 +944,22 @@ rather than showing a wrong value.
 ## Files
 
 The surfaces are folders: `header/`, `footer/` (the status bar and its price
-calculation), `separator/`, `panel/` (the unified screen and its merged model),
+calculation), `message/` (the user-message marker), `notice/` (the shared notice),
+`block/` (the tool-block frame), `separator/`, `working/` (the live
+elapsed counter on Pi's working row), `panel/` (the
+unified screen and its merged model),
 `picker/` (discovery and the settings store), `doctor/` (the `run_doctor` tool
-and its probe runtime), and `notify/`.
+and its probe runtime), and `notify/`. 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.
 
 | File | Responsibility |
 |---|---|
-| `index.ts` | Composition root: the disable guard and the six `register*` calls. |
-| `header/config.ts` | Header tuning (`HEADER_CONFIG`): mark and identity tokens, padding, tagline, and the grouped help entries. |
-| `header/component.ts` | `ByteflyHeader`: the mark, identity rows, rule, and grouped help, plus its factory. |
+| `index.ts` | Composition root: the disable guard, the eleven `register*` calls, the one shared output-pad store, and the rail source. |
+| `pad.ts` | `PadSource` and `createPadStore`: one record of Pi's output pad, so the tool frame, the notice, and the turn separator inset by the same margin. |
+| `chrome.ts` | The transcript rail (`RAIL_ROLES`, `railGlyph`), the `chrome` section's normalizer and loader, and the `RailSource` that `registerChrome` keeps current on `session_start`/`session_tree`. |
+| `header/config.ts` | Header tuning (`HEADER_CONFIG`): mark and identity roles, tagline, and the grouped help entries. |
+| `header/component.ts` | `ByteflyHeader`: the mark, identity rows, signature rule, and grouped help, plus its factory. |
 | `header/register.ts` | Installs/restores the header and owns its session lifecycle. |
 | `footer/register.ts` | Installs/restores the footer and owns its session lifecycle. |
 | `footer/config.ts` | Bar tuning (`CONFIG`): thresholds, gauge, separators, icons, status keys, labels. |
@@ -755,22 +971,35 @@ and its probe runtime), and `notify/`.
 | `footer/price/rates.ts` | Model-key matching: exact and wildcard, most specific first. |
 | `footer/price/schedule.ts` | Peak-window parsing and evaluation in a configured zone. |
 | `footer/price/price.ts` | Records → totals: rates, peak multiplier, recorded-cost fallback. |
-| `footer/render/format.ts` | Generic formatters (tokens, cost in the configured currency, cwd, gauge, colors). |
+| `footer/render/format.ts` | Generic formatters (tokens, cost in the configured currency, cwd, the context role, truncation). |
 | `footer/render/status.ts` | Status-chip transforms: `compactStatus` and `dropStatusDetail`. |
-| `footer/render/segments.ts` | The segment builders: forms, weights, separators, colors. |
+| `footer/render/segments.ts` | The segment builders: forms, weights, separators, roles. |
 | `footer/render/lines.ts` | Snapshot → two `LineSpec`s; status routing. |
 | `footer/render/layout.ts` | Width reduction and right-zone folding. |
 | `footer/render/footer.ts` | `StatusBar` component and footer factory. |
-| `separator/config.ts` | Turn-rule tuning: `customType`, glyph, label prefix, padding, and colors. |
+| `message/config.ts` | Nameplate tuning (`MESSAGE_CONFIG`): the label and the rule. |
+| `message/format.ts` | Pure `nameplate` and `styleUserMessage`: the two-row nameplate (label over a full-width rule) and its placement above the message. |
+| `message/register.ts` | Registers the Markdown transformer. |
+| `notice/config.ts` | Notice tuning (`NOTICE_CONFIG`): source/title/detail roles, the severity glyphs and roles, the shared rail roles, and the item cap. |
+| `notice/component.ts` | Pure `noticeLines` and `NoticeComponent`: the headline at the margin, the rail-led severity rows, sanitized and width-clipped. |
+| `notice/register.ts` | Registers the message renderer for the shared notice type and hands it the rail source. |
+| `block/config.ts` | `BlockStatus` and `BLOCK_CONFIG.roles`: the design role a result's rail takes for each state. |
+| `block/component.ts` | Pure `toolBlockLines`, `headlineWithToolName`, `recolorShellCall`, `recolorCallHeadline`, and `ToolBlock`: the headline, the body's two-column indent (optionally rail-led), the reduced-width inner render, the leading-blank trim, the shell-prompt rewrite (the name keeps the accent, the command reopens in `label`), the subject demotion (a path, URL, query, or pattern reads in `label` so the name is the line's only accent, including the tail a bare `edit <path>` headline wraps onto the body), and the image-line passthrough. |
+| `block/fallback.ts` | Generic `callFallback` / `resultFallback` for a tool with no renderer: the subject in the body colour, its options faint, and a capped result preview. |
+| `block/register.ts` | The `registerToolRenderer` resolver that frames every tool; it recolours a shell call's string before the frame wraps it, rails the result body by status, and rails the call body for `edit`/`write` (the two whose call body carries the result). |
+| `separator/config.ts` | Turn-rule tuning: `customType`, glyph, label prefix, padding, and roles. |
 | `separator/register.ts` | Registers the entry renderer and appends a separator on `agent_settled`. |
 | `separator/component.ts` | `SeparatorComponent`: the stateless entry renderer. |
-| `separator/format.ts` | Pure `separatorLabel` / `separatorParts` / `separatorLine`. |
-| `separator/types.ts` | `TurnSeparatorData`, `SeparatorParts`. |
+| `separator/format.ts` | Pure `separatorLine`: the centered turn rule, drawn by the kit's `centeredRule`. |
+| `separator/types.ts` | `TurnSeparatorData`. |
+| `working/config.ts` | Counter tuning (`WORKING_CONFIG`): the word, the ellipsis, and the tick interval. |
+| `working/format.ts` | Pure `formatElapsed` (whole seconds) and the working-message shape. |
+| `working/register.ts` | Starts the tick on `turn_start` and cancels it on `agent_end`/`session_shutdown`. |
 | `panel/types.ts` | `PanelRow` and `PanelModel`, the merged row model. |
 | `panel/join.ts` | The item/report union with the unambiguous-name health rule and unique row keys, groups, and ordering. |
 | `panel/format.ts` | Non-TUI text: the headline and the grouped listing with a per-row health suffix. |
-| `panel/tui.ts` | `PanelComponent`, the unified dock screen. |
-| `panel/commands.ts` | `/bytefly`, `/extensions`, and `/doctor`: one runner for the screen and its text modes. |
+| `panel/tui.ts` | `PanelComponent`, the unified dock screen, drawn from the `lib/tui/` kit. |
+| `panel/commands.ts` | `/bytefly`: one command for the screen, the `doctor` report, and their text modes. |
 | `picker/types.ts` | Picker host seams (`SettingsStore`, `ExtensionResolver`, `Discovery`) and row types. |
 | `picker/resources.ts` | Pure grouping, labels, display names, and pattern helpers. |
 | `picker/toggle.ts` | Pure next-settings transforms for global and project toggles. |
@@ -781,7 +1010,7 @@ and its probe runtime), and `notify/`.
 | `doctor/tools.ts` | The `run_doctor` tool and its renderers. |
 | `doctor/schema.ts` | Tool parameters and the structured output schema. |
 | `doctor/config.ts` | `DEFAULT_CONFIG`, `normalizeConfig`, `loadConfig` for the `doctor` section of `bytefly.json`. |
-| `doctor/format.ts` | Pure report text, summary, glyphs, detail lines, and the proactive warning sentence. |
+| `doctor/format.ts` | Pure report text, summary, severity roles and glyphs, detail lines, and the proactive warning sentence. |
 | `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. |
@@ -825,3 +1054,12 @@ 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 three triggers,
 reload, and shutdown through `registerNotify` (`notify/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`.
+The notice surface is covered by its pure rows (`notice/component`), its
+renderer registration (`notice/register`), and the shared contract
+(`lib/notice`), plus the factory check in `extension`.
+The tool-block frame is covered by its pure `toolBlockLines` (`block/component`)
+and its generic fallback (`block/fallback`), plus the resolver's shell override,
+self-shell carve-out, and fallback framing (`block/register`).