pi-zentui 0.29.3 → 0.30.0

package/docs/configuration.md

@@ -51,7 +51,7 @@ The interactive `/zentui` menu is split into seven component-oriented sections.
 2. **Editor** — enablement, style, colors, Codex quota, model label, border behavior, viewport indicators, settings for the selected editor style, and a static synthetic preview.
 3. **User messages** — enablement, style, colors, and a static synthetic Markdown preview.
 4. **Thinking (Experimental)** — private Rail, Tree, or Streaming rendering; active Streaming can switch live to Rail or Tree, Rail and Tree can switch live between each other, and the private renderer may break after Pi updates.
-5. **Working line** — ownership, settled Turn summary, spinner and text speeds, optional spinner-color motion, text animation, color source, custom messages, Tool/Elapsed/Thinking time/Tokens segments, and animated preview.
+5. **Working line** — ownership, settled Turn summary, spinner and text speeds, optional spinner-color motion, text animation, color source, custom messages, Tool/Elapsed/Thinking time/Tokens/Token rate segments, and animated preview.
 6. **Footer** — Native, Starship, or Hidden. Starship additionally exposes colors, Codex quota, model label, responsive layout, separator, context style, and path display.
    - **Segments →** — visibility toggles for non-Git Starship segments.
    - **Git →** — Starship Footer Git segment and probe controls, not Editor Git controls.
@@ -61,7 +61,7 @@ The two Footer child entries appear only with Starship selected. Child headings
 
 Editor, User messages, Thinking (Experimental), and Working line retain independent configuration. Editor, User-message, and Thinking previews remain visible while their component is disabled. Only the Working-line preview owns an animation timer. Footer’s Starship-specific rows are shown only while Starship is selected; Extension statuses offers the same unprefixed placement/color rows in every Footer style. Native saves dormant Starship position/color preferences without changing Pi's layout. Footer Color overrides remain available for preconfiguration under every Footer style and say **Saved for Starship** when inactive. Native and Hidden hide the two child entries without changing their saved preferences. Other dormant choices explain their scope without rewriting values. Auto icons assume a Nerd Font without detecting one; ASCII replaces icons only, not all borders or UI glyphs.
 
-Free-form values such as custom formats, Opencode metadata formats, and previously unseen, unsaved extension keys remain JSON-only. Component raw colors are editable through each component’s **Color overrides** action, with explicit **Reset / inherit**. Working-line speed accepts validated custom milliseconds in `/zentui`.
+Free-form values such as custom formats, Opencode metadata formats, and previously unseen, unsaved extension keys remain JSON-only. Component raw colors are editable through each component’s **Color overrides** action, with explicit **Reset / inherit**. Editor and Starship Footer also offer **Individual custom value colors**, listing current publishers, valid alias targets, and saved publisher overrides. Working-line speed accepts validated custom milliseconds in `/zentui`.
 
 Every section and Footer child page has a direct route and completion:
 
@@ -249,6 +249,7 @@ Reference only—not a starter file. Prefer the minimal overrides above. Optiona
       "enabled": false,
       "placement": "above",
       "turnSummary": true,
+      "turnSummaryFormat": "Turn took $turn_duration$join_sep(thought for $thought_duration)$join_sep(↑$input_tokens ↓$output_tokens)$join_sep$token_rate",
       "spinner": "star-bloom",
       "spinnerIntervalMs": 100,
       "animateSpinnerColor": false,
@@ -499,11 +500,14 @@ Empty strings and whitespace-only strings mean deliberately **unstyled**, not mi
 | --- | --- | --- |
 | `footer` | `cwd`, `sessionName`, `gitBranch`, `gitStatus`, `contextNormal`, `contextWarning`, `contextError`, `cost`, `sessionDuration`, `tokens`, `separator`, `runtimePrefix`, `extensionStatus`, `packageVersion`, `gitCommit`, `gitMetricsAdded`, `gitMetricsDeleted`, `username`, `time`, `os` | Same-named shared key |
 | `editor` | `cwd`, `sessionName`, `gitStatus`, `contextNormal`, `contextWarning`, `contextError`, `cost`, `sessionDuration` | Same-named shared key; used by Minimalist metadata and quota |
+| `editor` | `cacheHit` | Optional shared `cacheHit`, then Editor `contextNormal`; used only by Minimalist cache-hit metadata |
 | `editor` | `gitBranch` | `editorGitBranch`, then explicitly configured shared `gitBranch` / `git`; never the generated Footer branch default |
 | `editor` | `accent`, `border`, `prompt`, `rail`, `shellRail`, `model`, `provider`, `thinking`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, `thinkingMax` | `editorAccent`, `editorBorder`, `editorPrompt`, `editorRail`, `editorShellRail`, `editorModel`, `editorProvider`, `editorThinking`, and matching `editorThinking*` level keys |
 | `userMessages` | `accent`, `border` | `editorAccent`, `editorBorder` |
 | `selectorBorders` | `border` | No shared raw key: defaults to theme `borderMuted` / terminal `bright-black`; never inherits `editorBorder` |
 | `workingLine` | `low`, `mid`, `high` | `workingLineLow`, `workingLineMid`, `workingLineHigh` |
+| `editor`, `footer` | `prNumber`, `prUrl`, `ci`, `tokenRate` | No shared raw keys; existing neutral border/extension-status fallback |
+| `workingLine` | `tokenRate` | No shared raw key; Static-only override, otherwise inherits mid; Classic/KITT use whole-row tiers |
 
 Shared aliases `cwdText → cwd` and `git → gitBranch` remain accepted. Footer model/provider are plain text and the detected runtime label uses its runtime module's style, not invented Footer color keys.
 
@@ -513,6 +517,7 @@ Role-specific defaults and chains remain intact:
 - In shell-command mode (`!` or `!!`), Opencode's left rail and model label share `shellRail` → configured `accent` → theme `bashMode` / terminal `bright-cyan`. Normal model coloring is unchanged.
 - Accent Rail uses only `rail` / `editorRail`, then warm theme `syntaxNumber` / terminal `215`; it does not inherit `accent`.
 - Minimalist branch defaults to theme `bold syntaxKeyword` / terminal `bold blue` when no local or explicit shared branch style exists.
+- Minimalist's built-in `Cache NN%` label and `$cache_hit` use Editor `cacheHit` → optional shared `colors.cacheHit` → Editor `contextNormal` (local, then shared/default). The normal tier stays stable even at warning/error context usage. Configure it through `/zentui` → Editor → **Color overrides** → `cacheHit`; **Reset / inherit** resumes the chain. The selected Editor color source applies throughout; no cache-hit palette is generated or saved, and other owners are unchanged.
 - Thinking levels use their level key then generic `thinking`; Max uses `thinkingMax → thinkingXhigh → thinking`. Static metadata and adaptive borders retain their existing distinct fallback behavior; theme-adaptive borders still defer to Pi's thinking-border callback.
 - Working-line defaults remain theme `dim`, `muted`, `bold accent`, or terminal `bright-black`, `cyan`, `bold cyan`. Both animated rows and summaries consume local overrides. New persisted Turn summaries snapshot the effective high style; when no safe SGR prefix exists (including an unstyled high override), they retain the safe bold-cyan substitute. Existing persisted summaries keep their recorded style; legacy version-1 summaries use current high styling.
 
@@ -543,8 +548,8 @@ Zentui's generated layout; an empty string hides that slot's configurable
 metadata. No extra rows are added. Use **Editor → Metadata templates** in
 `/zentui` to edit a slot or **Reset / inherit** to delete its override.
 
-Templates use the existing `$variable`, `${variable}`, literal text, and
-conditional `( ... )` grammar. Layout is selected by the six slot names, not
+Templates use `$variable`, `${variable}`, literal text, conditional `( ... )`
+groups, and the additive `$join_sep` marker. Layout is selected by the six slot names, not
 `$fill`. Viewport counts, Bash mode, and an embedded Working line remain
 operational indicators outside the templates. Explicit templates may show
 metadata whose ordinary visibility toggle is off, but can never bypass Editor
@@ -576,7 +581,7 @@ with `variables`, then reference those names in any slot:
 **Editor → Custom variable aliases** edits the name-to-publisher-key JSON or
 resets the aliases. Names use letters, digits, and underscores, start with a
 letter or underscore, and cannot replace built-in/structural variables or
-prototype names. At most 16 aliases are accepted; keys are nonempty, at most
+prototype names, except that a valid explicit `ci` alias retains precedence over the new GitHub builtin. At most 16 aliases are accepted; keys are nonempty, at most
 64 UTF-16 code units, and contain no whitespace or terminal controls. Reset
 removes only the edited overrides. Unrelated owners/styles and unknown raw
 configuration remain untouched. These settings never enable Footer or Working
@@ -588,10 +593,15 @@ Built-ins are `$model`, `$model_id`, `$model_name`, `$provider`, `$thinking`,
 and `$output_tokens`. `$turn_duration` is current/completed interaction time,
 not total session duration. Existing path, context, separator and color
 preferences still apply. `$sep` (alias `$separator`) uses the configured
-Minimalist dash/dot separator. Prefer optional groups such as
-`$model($sep$thinking)` to avoid separators around empty values.
-
-OMP additionally supports the [host template data](#omp-template-data) built-ins
+Minimalist dash/dot separator. `$join_sep` (or `${join_sep}`) joins only populated
+fields with that same styled separator. For example, set `bottomLeft` to
+`"$session_name$join_sep($git_branch $git_status)"` for a session-only, Git-only,
+combined, or empty label; explicit references work even with `showSessionName`
+off. Do not add padding around the marker. Legacy `$sep` and optional-group
+formatting remain unchanged; see [conditional joining](./footer-format.md#conditional-joining)
+for chains, nested scopes, preserved ANSI/link styling, and boundaries.
+
+Pi and OMP support `$pr_number`, `$pr_url`, `$ci`, and `$token_rate` (see [live metadata](#live-metadata)). OMP additionally supports the [host template data](#omp-template-data) built-ins
 in all six slots and both Opencode metadata formats. These are separate from
 publisher aliases and are not included in `$extensions`.
 
@@ -674,6 +684,15 @@ Tip: with `opencode-copy-friendly`, set Pi's `editorPaddingX` to `1` for a small
 
 Each Opencode variant owns an independent `metadataFormat`:
 
+Both support `$join_sep` / `${join_sep}` to join populated fields with neutral
+border-styled ` · `, for example `$model$join_sep$provider$join_sep$thinking`.
+Missing middle fields leave exactly one separator; single fields have none.
+Do not pad the marker: it owns its spaces. Joins are local to groups and never
+cross `$fill` zones. Legacy `$sep` / `$separator` still render empty in Opencode.
+See [shared conditional-joining semantics](./footer-format.md#conditional-joining).
+The marker is reserved (not a custom alias or data demand), requires a supporting
+version, and does not rewrite defaults, saved templates, or other components.
+
 ```json
 {
   "components": {
@@ -712,6 +731,7 @@ The configured right zone and Pi's operational right status are right-aligned to
 | `$tokens` | cumulative session input/output tokens only, for example `↑76k ↓1.6k` |
 | `$cache_hit` | latest assistant prompt cache-hit rate to one decimal; `0.0%` when unavailable |
 | `$codex_quota` | remaining 5-hour/weekly account quota; requires Editor quota consent and active `openai-codex` |
+| `$join_sep` | conditional join with neutral border-styled ` · ` |
 
 `$context` uses Pi's current context snapshot and the live assistant context override, refreshing on the existing 250 ms streaming render cadence. `$tokens` and `$cache_hit` use authoritative persisted session snapshots, so they update at normal session synchronization boundaries rather than estimating in-progress totals. These variables are independent of Footer visibility, style, color source, and configuration.
 
@@ -791,17 +811,158 @@ Streaming keeps the reviewed host-rendered behavior: while open it shows the lat
 
 The exact all-mode private matrix covers Pi 0.85.0 and 0.87.1 under dark, light, and current themes, narrow/wide widths and resize; both versions also have fullscreen live-transition PTY coverage. Thinking (Experimental) never owns or writes the Working line, including its unchanged **Thinking time** option, and does not own Footer, Editor, widgets, statuses, or model behavior.
 
+## Individual custom value colors
+
+Sparse `components.editor.customValueColors` and `components.footer.customValueColors`
+are keyed by **publisher ID**, not template alias. All aliases for that publisher
+and Minimalist's supported `$extensions` aggregate share the override within the
+owner, across its styles. Footer's `$extensions` remains the existing status
+protocol and is not affected. Working-line publisher segments are a separate
+protocol and do not consume these maps.
+
+```json
+{
+  "components": {
+    "editor": { "customValueColors": { "vendor.package/value": "bold fg:202" } },
+    "footer": { "customValueColors": { "vendor.package/value": "" } }
+  }
+}
+```
+
+Missing overrides retain the style's Original/Zentui behavior exactly. Explicit
+styles strip publisher SGR and hyperlinks before styling through the selected
+owner color source; empty/whitespace deliberately means unstyled. Reset deletes
+one leaf and restores inheritance. Theme tokens, hex/256-color values and
+Starship-style modifiers are supported. Normalization accepts up to 1024 own
+properties and styles up to 4096 UTF-16 units; invalid keys/styles inherit.
+Saves preserve unrelated raw JSON, invalid/future leaves and the other owner;
+ordinary selection saves and `/zentui migrate` never snapshot these maps or
+rewrite templates.
+
+## Live metadata
+
+Minimalist's six slots, both Opencode metadata formats, and Starship wide and
+responsive compact templates support these explicit opt-in references:
+
+| Variable | Pi | OMP |
+| --- | --- | --- |
+| `$pr_number`, `$pr_url` | Open PR number and safe plain HTTPS URL for a non-default branch | Same shared collector |
+| `$ci` | `CI passing`, `CI running`, `CI failed`, `CI no checks`, or `CI stale` | Same shared collector |
+| `$token_rate` | Completed model-work average for the current interaction, e.g. `48 tok/s avg`; unknown is `— tok/s avg` | Existing native last-assistant / streaming worker rate unchanged |
+
+No default or saved template is rewritten. For example:
+
+```json
+{
+  "components": {
+    "editor": {
+      "colors": { "ci": "bold blue", "tokenRate": "fg:202" },
+      "styles": { "opencode": { "metadataFormat": "$model( · PR #$pr_number)( · $ci)( · $token_rate)" } }
+    },
+    "footer": {
+      "styles": { "starship": {
+        "format": "$cwd( · PR #$pr_number)( · $ci)$fill$context",
+        "compactFormat": "$cwd$wrap(PR #$pr_number)$wrap($ci)$wrap($token_rate)"
+      } }
+    }
+  }
+}
+```
+
+A valid owner/style-local `variables.ci` mapping **wins over the builtin** and
+creates only publisher demand. Remove that mapping to opt into GitHub CI. Other
+builtin reservations are unchanged. Builtin colors use independent owner-local
+`prNumber`, `prUrl`, `ci`, and `tokenRate` roles, not publisher color maps; CI has
+one role, not an automatic severity palette.
+
+GitHub collection is read-only via `gh`, asynchronous and outside render. It
+runs immediately, then refreshes at the completed result's 30-second cache
+expiry, only while an owned, enabled, supported consumer references PR/CI.
+Expiry repaints CI as stale before awaiting the next fetch; failures without a
+cache deadline retry after 30 seconds. Editor and Footer share one neutral snapshot but keep
+independent settings/appearance. Each refresh verifies repository, branch,
+remotes and local HEAD identity, including cache hits; observed project/tool and
+host branch changes invalidate immediately. External changes are discovered on
+the next demanded refresh, not instantaneously. Valid repo metadata lasts five
+minutes; PR successes and negative results last 30 seconds. Identity/context
+changes, demand loss and shutdown abort outstanding work. No auth commands,
+credential reads, forge mutations or other forges are supported.
+
+CI is qualified by the PR head: a local commit different from the remote PR head
+is **stale**, never green. Dirty files alone do not change commit identity.
+Expired CI is stale while refreshing; errors clear earlier results. Zero checks
+or only skipped/neutral checks are **no checks**, not passing. Unknown/malformed
+checks are never proof of success. No PR, closed/default/detached branches,
+missing `gh`/read access or lookup errors are empty; optional groups hide labels.
+
+Pi Editor/Footer `$token_rate` is a **completed model-work average**: sum of
+provider-reported final output tokens divided by the sum of observed model-call
+durations in the current interaction. Each interval starts when Zentui observes
+public `turn_start` and ends at its matching accepted assistant `message_end`,
+using a monotonic clock. This includes initial wait **and client preparation
+before the provider call**; it is not pure backend decode speed. Tool execution,
+between-call gaps and idle are excluded. For example, 120 output tokens over 4s
+(including 2s initial wait), then 180 over 2s after a 10s tool gap, gives
+`300 / 6 = 50 tok/s avg`, not an average of call rates or `300 / 16`.
+
+The slot shows `— tok/s avg` before a trustworthy completed sample, never a
+live-rate substitute. After each completed call it shows **completed calls so
+far**, retaining the previous aggregate while another call in the same interaction
+is in flight, through tools, `agent_end` and settlement. Continuation/retry
+`agent_start` does not reset it; a genuinely new interaction does. If non-idle
+settlement partitions an already-started run into a new interaction, only that
+surviving run's completed work and any open call's original start are retained;
+unknown coverage from settled runs is discarded, but surviving unknown coverage
+remains unknown. Only accepted,
+deduplicated finals contribute per-message output, never cumulative interaction
+totals, last streaming usage or character estimates. Successful reported zero
+output is included with its duration. Positive provider-reported partial/error
+usage is included with a matching interval; all-zero error/abort placeholders
+are unknown. Missing/invalid final usage or timing for any included call makes
+the aggregate unknown until reset rather than silently showing a partial exact
+average. This reflects final usage visible to Zentui's event handler, not a
+history scan or independent verification of provider accounting.
+
+Working line keeps its separate **recent live rate**, with `~` for estimates
+and `— tok/s` before a usable measurement. It uses a bounded three-second
+observation window and needs advancing output spanning at least 500ms, excluding
+pre-output silence. The measurement expires after two seconds without advancing
+output, but its display holds the last observed window rate while the Working row
+remains active: between chunks, through response end, tools, between-call pauses,
+continuations/retries and subsequent model turns in the same interaction. A fresh
+usable live sample replaces it; a retained value is historical, not ongoing generation.
+Text, thinking and tool-call argument deltas use the existing Unicode estimator;
+source/usage corrections rebaseline rather than producing spikes. Final usage
+never creates an instantaneous live sample. Working rate is independently opt-in;
+a genuinely new interaction starts at `— tok/s` until its first usable measurement.
+If non-idle settlement promotes an already-started run into a new interaction,
+only that surviving run's observation is retained; an older run's value becomes
+`— tok/s`. The whole Working row still disappears normally at idle/settlement.
+
+Compaction, session/model/tree changes and loss of all rate demand clear both
+metrics. After a mid-run model change, the next properly observed turn can
+establish a new current-model aggregate without another `agent_start`. Repaint
+polling is active only while streaming and demanded; retained rates and averages
+need no idle timer. These live metrics add no latency measurement; persisted summaries have their own snapshot schema.
+OMP's native `$token_rate` semantics are unchanged.
+
 ## Working line
 
 When enabled, Zentui owns Pi's complete working-row message and indicator. Five fixed-width spinner presets are available: Braille Orbit, Star Bloom, ASCII Pinwheel, Claude-inspired, and three-cell Pulse.
 
-`messages.custom` defaults on and selects once per model turn from an editable, materialized 16-message list. Turning it off keeps the row owned and displays animated `Working…`; an empty or invalid list uses the same fallback. Optional segments show the latest active Tool, interaction-wide Elapsed time, cumulative wall-clock Thinking time, and whole-interaction Tokens.
+`messages.custom` defaults on and selects once per model turn from an editable, materialized 16-message list. Turning it off keeps the row owned and displays animated `Working…`; an empty or invalid list uses the same fallback. Optional segments show the latest active Tool, interaction-wide Elapsed time, cumulative wall-clock Thinking time, and whole-interaction Tokens. **Token rate** is separately optional and default-off (`segments.tokenRate: false`); enable it without adopting Editor or Footer: `{"components":{"workingLine":{"enabled":true,"segments":{"tokenRate":true},"colors":{"tokenRate":"fg:202"}}}}`. It holds the last observed recent live Pi rate through tools and subsequent calls in the same interaction, not the completed average in Editor/Footer `$token_rate`. The row disappears normally at idle, and identity changes such as compaction clear the observation; see [live metadata](#live-metadata).
 
 Committed totals stay provider-reported across tool loops, retries, compaction retries, and queued continuations. During a response, live output follows Pi's `↓N` convention whether usage is provider-reported or temporarily estimated. Final usage reconciles atomically; input is never estimated. Labels are sanitized and width-bounded.
 
-When Pi settles, the default-on **Turn summary** appends a persistent context-free row such as `Turn took 56s · thought for 10s · ↑7.1k ↓779`. Thought is cumulative wall-clock time from Pi's public thinking stream; overlaps count once and zero is omitted. Output already includes reasoning tokens, so reasoning is not added separately. Summaries always include both token totals, even when live Tokens or **Thinking time** is hidden or zero, and can be disabled without changing historical rows. They use the fixed high style and are inactive while Working line is disabled.
+When Pi settles, the default-on boolean **Turn summary** (`turnSummary`) appends a persistent context-free row such as `Turn took 56s · thought for 10s · ↑7.1k ↓779 · 42 tok/s avg`. Thought is cumulative wall-clock time from Pi's public thinking stream; overlaps count once and zero is omitted. Output already includes reasoning tokens, so reasoning is not added separately. The default template includes both token totals even when live Tokens or **Thinking time** is hidden or zero. Summaries are inactive while Working line is disabled.
+
+`turnSummaryFormat` is a terminal-safe single-line template (maximum 2048 code units and eight nested optional groups). Missing, invalid, empty or whitespace-only values use the default shown above; use `turnSummary: false` to hide new summaries. Supported variables are `$turn_duration`, `$thought_duration`, `$input_tokens`, `$output_tokens`, and `$token_rate`. Braced variables and optional `(groups)` use the existing format grammar; unknown names are empty. `$sep`/`$separator` emit ` · `; `$join_sep` joins only nonempty fields. Zero thought is empty; known-zero counts remain `0`.
+
+Summary `$token_rate` is a complete label such as `42 tok/s avg`, or empty when exact final usage/timing coverage is unavailable (never an unknown dash). It sums provider-reported final assistant output divided by summed observed `turn_start` → accepted `message_end` durations, including initial wait/client preparation and excluding tools/gaps, across the **whole settled interaction**, including model selections and continuations. Non-idle settlement includes only settled runs, not an already-running successor. Summary-only collection is passive: it does not enable live Token rate, Editor/Footer slots or sampling timers. Enabling collection late cannot claim a partial exact average.
+
+`components.workingLine.colors.turnSummary` styles only new static transcript summaries. Missing/invalid values inherit effective Working **high** (local then shared fallback); explicit empty/whitespace means unstyled. `/zentui` → Working line offers **Turn summary format** Edit/Reset and **Color overrides** → `turnSummary`; Reset deletes only that override. Format and resolved style are snapshotted in new entries, so changes never rewrite history. Legacy v1/v2/v3 entries retain their original output without fabricated historical TPS. OMP remains native.
 
-Classic and KITT move color across message and segments. **Animate spinner color** optionally includes spinner cells and separator. Static colors the full row uniformly and ignores text speed/spinner-color participation without changing saved values. Spinner glyph motion always remains active.
+Classic and KITT sweep across the entire row: Message, Tool, Elapsed, Thought, Tokens, Token rate (including `— tok/s`), and extension segments. A saved `colors.tokenRate` override never creates a fixed-color segment in animated modes; it applies only in Static (`textAnimation: "disabled"`). **Animate spinner color** optionally includes spinner cells and separator. Static uses the mid tier except for an explicit Token rate override; an omitted or invalid override inherits mid, while an empty style deliberately leaves Token rate unstyled. Static ignores text speed/spinner-color participation without changing saved values. Spinner glyph motion always remains active.
 
 | Setting | Default | Presets | Applies to |
 | --- | ---: | --- | --- |
@@ -810,7 +971,7 @@ Classic and KITT move color across message and segments. **Animate spinner color
 
 Both speeds accept `30..1000` ms. Classic/KITT combine both cadences through one Pi Loader interval; exact cycles are used within 1024-frame/512-KiB limits. Pathological custom pairs use a bounded evenly distributed schedule with at most half a spinner-cycle and half a text-step rounding. Legacy `intervalMs` is accepted only as migration input for `spinnerIntervalMs` when the canonical field is absent.
 
-Content reserves the complete Tokens label and active extension segments first, then Message, Thought, Elapsed, and Tool allocation, while preserving visual order **Message · Tool · Elapsed · Thought · Tokens · Extensions** within the 80-column Loader-row contract. Active thought starts as `thinking 0s`; completed positive thought becomes `thought for Ns`. Rebuilds preserve spinner and visible color phase.
+Content reserves the complete Tokens and optional Token rate labels and active extension segments first, then Message, Thought, Elapsed, and Tool allocation, while preserving visual order **Message · Tool · Elapsed · Thought · Tokens · Token rate · Extensions** within the 80-column Loader-row contract. Active thought starts as `thinking 0s`; completed positive thought becomes `thought for Ns`. Rebuilds preserve spinner and visible color phase.
 
 Pi's working-row APIs are global and unkeyed. While owning the row, Zentui reasserts its blank message on owned refreshes/reconciles (even with unchanged frames) and before a Border fallback reveals the Above row. A later external message write or reset can still win until the next such boundary; native spinner ticks alone do not repair it, and there is no added polling. Separate multiline widgets are unaffected; extensions sharing the working-message slot should use keyed segments below instead.
 
@@ -965,13 +1126,14 @@ OMP has no public editor-factory getter. Zentui observes public setter descripto
 The following explicit Zentui names are available in Opencode/copy-friendly
 `metadataFormat`, all Minimalist slots, and Starship `format`/`compactFormat`.
 OMP segment IDs are not automatically template variables. These names are
-reserved built-ins, not custom publisher aliases; `$extensions` is unchanged.
-Pi and unavailable OMP capabilities render these host values empty.
+reserved built-ins, except the explicit `ci` alias compatibility rule; `$extensions` is unchanged.
+Pi supplies the [shared PR/CI and live rate variables](#live-metadata); other host-only or unavailable capabilities render empty.
 
 | Variable | Data and distinctions |
 | --- | --- |
 | `$session_id` | Current session's full ID, not its human-readable `$session_name`. |
 | `$pr_number`, `$pr_url` | Current non-default branch's GitHub PR number and safe plain HTTPS URL. |
+| `$ci` | Shared GitHub PR-head CI state; see [live metadata](#live-metadata). |
 | `$subagent_count` | Native active subagent badge count; background Bash/Eval jobs are not subagents. A known zero renders `0`. |
 | `$token_rate` | Output tokens/second, for example `42.5 tok/s`. Uses OMP's last-assistant average; observed live Vibe workers add the current streaming main rate, not an idle previous reply. Unknown timings remain empty. |
 | `$active_time` | Native accumulated active-processing time, including the open interval and excluding idle time, for example `1m 5s`. Not wall-clock `$session_duration` or current/completed `$turn_duration`; a known zero renders `0s`. |
@@ -1010,9 +1172,7 @@ with optional groups around labels:
 }
 ```
 
-PR data requires a matching GitHub remote, `gh`, and read access. Read-only lookups
-capture and recheck repository/branch identity, cache for up to 30 seconds, and
-invalidate on native project/branch changes. No PR, default/detached branches,
+PR/CI data uses the [shared demand-controlled collector](#live-metadata), requiring a matching GitHub remote, `gh`, and read access. It captures and rechecks full repository/branch/remote/HEAD identity, caches PR results for 30 seconds and successful repo metadata for five minutes, and invalidates on observed project/branch changes. No PR, default/detached branches,
 unavailable tooling, or lookup failure renders empty rather than a placeholder.
 
 **`$usage_quota` is opt-in by explicit template reference.** It uses the current

package/docs/footer-format.md

@@ -7,6 +7,7 @@ Set `components.footer.styles.starship.format` for complete control over the Sta
 - `$variable` and `${variable}` tokens
 - literal text and spaces
 - conditional groups `( ... )` that disappear when every nested variable is empty
+- `$join_sep` conditional field joining
 - `$fill` layout boundaries
 
 A custom format overrides `components.footer.styles.starship.segments` for the wide layout. Empty or omitted format uses the segment layout. Responsive mode first reflows wide content, then uses the independent `compactFormat` template; compact variables do not follow built-in segment toggles. `compactMaxLines` limits compact rows, not segment selection. No settings toggle rewrites either template. `$codex_quota` is an exception to segment-toggle bypass: it always requires the independent Footer quota consent toggle and active `openai-codex` provider.
@@ -112,18 +113,21 @@ The released flat `footerFormat` and `footerSegments` keys remain accepted only
 | `$subscription` | | `(sub)` in subscription mode; otherwise empty |
 | `$auto_compaction` | | `(auto)` when automatic compaction is enabled |
 | `$sep` | `$separator` | themed `|` using `colors.separator` |
+| `$join_sep` | — | join populated sibling fields with the styled surface separator |
 | `$fill` | — | wide or compact layout boundary |
 
 Each variable renders its core value without prose prefixes such as `on` or `via`; add those words as literals.
 
-### OMP host data
+### Shared live metadata and OMP host data
 
-OMP also supplies `$session_id`, `$pr_number`, `$pr_url`, `$subagent_count`,
+Pi and OMP supply `$pr_number`, `$pr_url`, and `$ci` through one passive, demand-controlled GitHub snapshot. Pi also supplies `$token_rate`: the current interaction’s completed model-work average (`48 tok/s avg`, or `— tok/s avg` when unknown), retained until a new interaction. It uses final output divided by summed observed call durations, including initial wait and client preparation but excluding tools/gaps; an in-flight call keeps the completed-calls-so-far aggregate, never a live estimate. Working line retains its separate recent live rate. OMP retains its native rate semantics. See [live metadata](./configuration.md#live-metadata) for identity/head qualification, TTLs, empty/stale/no-checks behavior and lifecycle limits. Templates opt in without rewriting defaults; disabled/native/unowned surfaces do not poll.
+
+OMP additionally supplies `$session_id`, `$subagent_count`,
 `$token_rate`, `$active_time`, `$hostname`, `$usage_quota`, `$collaboration`,
 `$stream_state`, `$vim_mode`, `$plan_mode`, `$prewalk_mode`, `$goal_mode`,
 `$vibe_mode`, and `$loop_mode`. These explicit built-ins also work in Opencode
 metadata and Minimalist slots; they are not aliases for OMP's segment IDs or
-third-party `$extensions`. Pi and unsupported/inactive capabilities render empty.
+third-party `$extensions`. Other Pi host-only and unsupported/inactive capabilities render empty.
 See the [data/source reference](./configuration.md#omp-template-data).
 
 For example:
@@ -217,7 +221,7 @@ template:
 ```
 
 These JSON-only aliases cannot replace built-in variables, aliases such as
-`branch`, structural tokens, or prototype names. Missing values are empty;
+`branch`, structural tokens, or prototype names, except a valid explicit `ci` alias takes precedence over GitHub CI and does not demand GitHub. Missing values are empty;
 conditional groups remove associated optional text. No custom value is appended
 outside an explicit template. A compact-only reference creates demand only
 while responsive mode is enabled. Native and Hidden never acquire this registry
@@ -227,7 +231,7 @@ Editor.
 Original is the default color mode and preserves permitted publisher SGR and
 HTTP(S) hyperlinks. Zentui strips incoming styling and uses Footer's own
 `colors.extensionStatus` role and color source. These choices are independent of
-Editor and of the existing `extensionStatuses.colorModes` preferences.
+Editor and of the existing `extensionStatuses.colorModes` preferences. Sparse `components.footer.customValueColors` overrides style individual publisher IDs across aliases in both templates. Explicit styles replace publisher styling; empty is unstyled, Reset deletes one leaf. `/zentui` → Footer → **Individual custom value colors** offers current, aliased and saved keys. See [individual custom value colors](./configuration.md#individual-custom-value-colors).
 
 Values are kept whole through wide alignment, reflow, and compact packing.
 When a value would be partially cropped or split, Footer recomposes without it
@@ -270,6 +274,51 @@ $cwd( on $git_branch)($git_status)$fill($context)
 
 If every variable inside a group is empty, the group and its literal text are dropped. `$session_name` is available whenever a custom format is set, independently of segment visibility; use a group such as `($sep$session_name)` so unnamed sessions leave no separator.
 
+## Conditional joining
+
+Use `$join_sep` (or `${join_sep}`) between fields to insert a separator only
+between populated fields:
+
+```text
+$session_name$join_sep($git_branch $git_status)
+$a$join_sep$b$join_sep$c
+```
+
+The first example shows just the session, just the Git field, both with one
+separator, or nothing. Git status can populate its field even without a branch.
+The chain renders `a SEP c` when the middle field is missing, never two gaps.
+Leading, trailing, or consecutive markers cannot create orphan separators.
+Literal-only visible fields count; unknown/unsupported variables are empty.
+Whitespace-only fields, SGR resets, and OSC hyperlink wrappers do not count as
+content. Retained fields keep their ANSI styles, hyperlinks, Unicode and icons.
+
+**Do not pad the marker with spaces:** the surface's already styled separator
+owns its spacing. Retained field output is not implicitly trimmed; any literal
+padding inside a populated field remains template-owned. Footer uses its existing
+styled ` | `, Minimalist its configured ` – ` or ` · `, and both Opencode variants
+use neutral border-styled ` · ` for this marker only.
+
+Each parenthesized group is a local sibling scope. For example,
+`$a$join_sep($b$join_sep$c)` joins the group as a whole to `a`, while
+`$a($join_sep$b)` cannot borrow `a` to insert a separator inside the group.
+Existing optional-group liveness rules still apply: the marker is not content,
+and join-only or whitespace-only marker groups disappear. Top-level `$fill`
+zones and compact `$wrap`/`$wrap_sep` chunks are hard boundaries: joins cannot
+cross zones, chunks, or rows. Nested fills remain nonstructural. For example,
+`$a$join_sep$fill$join_sep$b` renders separate `a` and `b` zones, and
+`$a$join_sep$wrap_sep$join_sep$b` leaves any same-row separator to the compact
+packer. `$wrap_sep` is not an alias for `$join_sep`.
+
+This is additive: templates without the marker keep their old behavior,
+including whitespace-only values, `$sep`/`$separator`, and Footer's existing
+pipe-orphan cleanup. No defaults or saved templates are migrated. Joining happens
+before width fitting; narrow displays still may truncate or omit fields.
+`join_sep` is now reserved and cannot be a custom alias on any template owner;
+rename a previously configured alias with that name. The marker does not resolve
+publisher data or create host/Git/quota demand; the joined fields still do.
+Older installed versions treat it as unknown/empty and cannot conditionally join;
+load or upgrade to a version supporting the marker before using it.
+
 ## Formatting rules
 
 - Literal text, pipes, and spaces render verbatim; the template owns spacing.
@@ -279,4 +328,4 @@ If every variable inside a group is empty, the group and its literal text are dr
 - `DEFAULT_COMPACT_FOOTER_FORMAT` omits model/provider, thinking level, and atomic telemetry. Add variables to `components.footer.styles.starship.compactFormat` to opt in at narrow widths. The flat `compactFooterFormat` key remains migration-only input.
 - Auto-compaction settings refresh at the next normal Footer synchronization. Unsupported Pi capabilities or read errors omit optional markers.
 - Unknown variables render empty.
-- `$fill`, `$wrap`, and `$wrap_sep` are structural and never render visible text.
+- `$fill`, `$wrap`, and `$wrap_sep` are structural and never render visible text. `$join_sep` emits a separator only between populated sibling fields.

package/extensions/zentui/average-token-rate.ts

@@ -0,0 +1,146 @@
+import { type MessageEndResult, parseAssistantMessageTokens } from "./interaction-summary";
+import type { TokenRateMessage } from "./token-rate";
+
+type FinalMessage = TokenRateMessage & { stopReason?: unknown };
+type CompletedWork = { output: number; elapsedMs: number; unknown: boolean };
+
+function emptyCompletedWork(): CompletedWork {
+	return { output: 0, elapsedMs: 0, unknown: false };
+}
+
+function combineCompletedWork(prior: CompletedWork, current: CompletedWork): CompletedWork {
+	const output = prior.output + current.output;
+	const elapsedMs = prior.elapsedMs + current.elapsedMs;
+	if (
+		!Number.isSafeInteger(output) ||
+		!Number.isFinite(elapsedMs) ||
+		elapsedMs > Number.MAX_SAFE_INTEGER
+	)
+		return { ...prior, unknown: true };
+	return { output, elapsedMs, unknown: prior.unknown || current.unknown };
+}
+
+function averageCompletedWork(completed: CompletedWork): number | undefined {
+	return !completed.unknown && completed.elapsedMs > 0
+		? (completed.output * 1000) / completed.elapsedMs
+		: undefined;
+}
+
+/** Provider final output / summed turn_start -> accepted message_end observations.
+ * Includes initial wait and client preparation, not just backend decoding. No tool/gap time.
+ * Acceptance and response identity belong to InteractionMetricsTracker, not this accumulator.
+ */
+export class AverageTokenRateTracker {
+	/** Only the latest run can survive non-idle settlement; older runs fold in constant space. */
+	private priorRuns = emptyCompletedWork();
+	private currentRun = emptyCompletedWork();
+	private enabled = false;
+	private startedAt?: number;
+	private clock?: number;
+	private priorClock?: number;
+
+	constructor(private readonly now: () => number = () => performance.now()) {}
+
+	agentStart(interactionStarted: boolean): void {
+		if (interactionStarted) this.reset();
+		else {
+			this.suspend();
+			this.priorRuns = combineCompletedWork(this.priorRuns, this.currentRun);
+			this.currentRun = emptyCompletedWork();
+			this.priorClock = this.clock ?? this.priorClock;
+			this.clock = undefined;
+		}
+		this.enabled = true;
+	}
+
+	turnStart(at = this.now()): void {
+		this.suspend();
+		this.enabled = true;
+		this.observeTime(at);
+		this.startedAt = at;
+	}
+
+	observeTime(at = this.now()): void {
+		if (!this.enabled) return;
+		// Cross-run clock ordering is relevant only while those prior runs remain included.
+		if (this.clock === undefined && this.priorClock !== undefined && at < this.priorClock)
+			this.priorRuns.unknown = true;
+		if (
+			!Number.isFinite(at) ||
+			at < 0 ||
+			at > Number.MAX_SAFE_INTEGER ||
+			(this.clock !== undefined && at < this.clock)
+		)
+			this.currentRun.unknown = true;
+		this.clock = at;
+	}
+
+	messageEnd(message: FinalMessage, result: MessageEndResult, at = this.now()): void {
+		if (result.status !== "accepted" || !this.enabled) return;
+		this.observeTime(at);
+		const elapsed = this.startedAt === undefined ? NaN : at - this.startedAt;
+		this.startedAt = undefined;
+		const usage = result.source === "final" ? parseAssistantMessageTokens(message) : undefined;
+		const failedPlaceholder =
+			(message.stopReason === "error" || message.stopReason === "aborted") &&
+			usage?.input === 0 &&
+			usage.output === 0;
+		if (
+			!usage ||
+			failedPlaceholder ||
+			!Number.isFinite(elapsed) ||
+			elapsed <= 0 ||
+			!Number.isSafeInteger(this.currentRun.output + usage.output) ||
+			!Number.isFinite(this.currentRun.elapsedMs + elapsed) ||
+			this.currentRun.elapsedMs + elapsed > Number.MAX_SAFE_INTEGER
+		) {
+			this.currentRun.unknown = true;
+			return;
+		}
+		this.currentRun.output += usage.output;
+		this.currentRun.elapsedMs += elapsed;
+	}
+
+	/** An unclosed observed call cannot be silently omitted from an exact aggregate. */
+	suspend(): void {
+		if (this.startedAt !== undefined) this.currentRun.unknown = true;
+		this.startedAt = undefined;
+	}
+
+	/** Drop settled runs without disturbing surviving completed work or an open call's anchor. */
+	partition(): void {
+		this.priorRuns = emptyCompletedWork();
+		this.priorClock = undefined;
+	}
+
+	/** Summary settlement reads the removed side before dropping it, never combined or surviving work. */
+	settle(idle: boolean): number | undefined {
+		if (idle) this.suspend();
+		const rate = idle ? this.snapshot() : averageCompletedWork(this.priorRuns);
+		if (idle) this.reset();
+		else this.partition();
+		return rate;
+	}
+
+	markIncomplete(): void {
+		this.currentRun.unknown = true;
+	}
+
+	reset(): void {
+		this.priorRuns = emptyCompletedWork();
+		this.currentRun = emptyCompletedWork();
+		this.enabled = false;
+		this.startedAt = undefined;
+		this.clock = undefined;
+		this.priorClock = undefined;
+	}
+
+	snapshot(): number | undefined {
+		const completed = combineCompletedWork(this.priorRuns, this.currentRun);
+		return averageCompletedWork(completed);
+	}
+}
+
+export function formatAverageTokenRate(rate: number | undefined): string {
+	return `${rate !== undefined && Number.isFinite(rate) && rate >= 0 ? Math.round(rate) : "—"} tok/s avg`;
+}

package/extensions/zentui/component-colors.ts

@@ -7,6 +7,10 @@ import {
 
 export const componentColorKeys = {
 	footer: [
+		"prNumber",
+		"prUrl",
+		"ci",
+		"tokenRate",
 		"cwd",
 		"sessionName",
 		"gitBranch",
@@ -29,6 +33,10 @@ export const componentColorKeys = {
 		"os",
 	],
 	editor: [
+		"prNumber",
+		"prUrl",
+		"ci",
+		"tokenRate",
 		"cwd",
 		"sessionName",
 		"gitBranch",
@@ -36,6 +44,7 @@ export const componentColorKeys = {
 		"contextNormal",
 		"contextWarning",
 		"contextError",
+		"cacheHit",
 		"cost",
 		"sessionDuration",
 		"accent",
@@ -55,7 +64,7 @@ export const componentColorKeys = {
 	],
 	userMessages: ["accent", "border"],
 	selectorBorders: ["border"],
-	workingLine: ["low", "mid", "high"],
+	workingLine: ["low", "mid", "high", "tokenRate", "turnSummary"],
 } as const;
 export type ColorOwner = keyof typeof componentColorKeys;
 export type ComponentColorKey<O extends ColorOwner> = (typeof componentColorKeys)[O][number];
@@ -103,7 +112,7 @@ export function componentColor(
 export function componentColor(
 	config: ZentuiConfig,
 	owner: "editor",
-	key: Exclude<ComponentColorKey<"editor">, keyof typeof editorLegacyKeys>,
+	key: Exclude<ComponentColorKey<"editor">, keyof typeof editorLegacyKeys | "cacheHit">,
 ): string;
 export function componentColor<O extends ColorOwner>(
 	config: ZentuiConfig,
@@ -119,7 +128,10 @@ export function componentColor<O extends ColorOwner>(
 		key
 	];
 	if (typeof local === "string" && isSupportedColorSpec(local)) return local;
-	if (owner === "selectorBorders") return undefined;
+	if (owner === "workingLine" && key === "turnSummary")
+		return componentColor(config, "workingLine", "high");
+	if (owner === "selectorBorders" || ["prNumber", "prUrl", "ci", "tokenRate"].includes(key))
+		return undefined;
 	const legacy =
 		owner === "editor"
 			? (editorLegacyKeys[key as keyof typeof editorLegacyKeys] ?? key)
@@ -140,6 +152,8 @@ export function workingLineColor(
 ): string | undefined {
 	const local = config.colors?.[tier];
 	if (typeof local === "string" && isSupportedColorSpec(local)) return local;
+	if (tier === "tokenRate") return undefined;
+	if (tier === "turnSummary") return workingLineColor(config, colors, "high");
 	return colors[
 		tier === "low" ? "workingLineLow" : tier === "mid" ? "workingLineMid" : "workingLineHigh"
 	];