@oh-my-pi/pi-tui 18.4.5 → 18.4.8

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 ## [Unreleased]
 
+## [18.4.8] - 2026-10-01
+
+### Fixed
+
+- Fixed native-terminal (TSP) frames held back by unacknowledged credits waiting for an unrelated render after the 5-second stall fallback expired; a credit-blocked change now renders as soon as the oldest frame counts as stalled.
+
+## [18.4.7] - 2026-10-01
+
+### Added
+
+- Added an optional `terminal` section to theme JSON (`background`, `foreground`, `chrome`, `widget`, 16 `ansi` colors) naming the terminal a theme was made for, for hosts that paint the terminal themselves; the built-in themes ported from known schemes (GitHub, Nord, Dracula, Catppuccin, Solarized, Gruvbox, Tokyo Night, One, Monokai, Rosé Pine, Poimandres, Celestial) carry their scheme's.
+
+## [18.4.6] - 2026-10-01
+
+### Added
+
+- Added a full-page transcript replay experience for Rewind in native terminals, with branching navigation through the conversation.
+- Added agent lineage navigation, including headers and links for moving between a subagent and its ancestors or returning to the main session.
+- Added a Jobs overlay for viewing background jobs.
+- Added OSC 877 protocol support for native TUI surfaces in Windows ConPTY environments.
+- Added customizable native screen layouts through Component.describeScreen and programmatic scrolling for native nodes.
+- Added native-terminal text editing support for selections in the composer and single-line inputs, including undoable host edits and safe handling of stale or token-spanning ranges.
+- Added optional dismissal handling for error banners, including a Dismiss button in native terminal strips.
+
+### Changed
+
+- Notebook evaluation cells now use dedicated input and output gutters with clearer status indicators.
+- Streaming file operations now remain expanded while running and collapse after execution completes.
+- Improved native-terminal effort indicators, using terminal glyphs where available and block meters as a fallback.
+- Updated native composer navigation when viewing a subagent to show the agent lineage and provide a direct return to the main session.
+- Native `/resume` picker sheets drop the "Resume session" heading and the This folder / All projects tabs: the search placeholder names the scope ("Search sessions in app…", "Search all sessions…") and Tab (the footer's All projects / This folder action) switches it. Picker `title` is now optional on the wire.
+- Updated the native composer's context display to span the window and provide clearer context usage and session-cost information, with shortcuts to the context and usage views.
+- Updated status-line billing summaries to show subagent spend separately from session spend and avoid repeating the same currency or subscription marker for subsequent amounts.
+
+### Fixed
+
+- Fixed search results so gaps between non-adjacent context runs are displayed correctly.
+- Fixed custom-answer and note prompts in native terminals so questions are shown completely with the correct titles and are no longer truncated or incorrectly wrapped.
+- Fixed text fields in native dialogs to render without a duplicate prompt indicator.
+- Fixed native TUI surfaces falling back to plain text rendering in Tern on Windows by accepting OSC 877 messages received through ConPTY.
+- Fixed streaming edit, patch, and write operation cards so they remain fully visible while running and collapse only after completion.
+
 ## [18.4.5] - 2026-09-30
 
 ### Added

package/dist/types/apps/git/sidebar.d.ts

@@ -152,8 +152,8 @@ export declare class Sidebar {
      * Pointer actions on the changes sheet: list clicks select (a folder also
      * folds, a second click on the selected file stages it, as the ANSI click
      * does), double clicks activate, the segmented control switches Path/Tree,
-     * and the quiet buttons run their row's action. False when not the
-     * sidebar's event.
+     * and the quiet buttons run their row's action; selection edits go to the
+     * text field being edited. False when not the sidebar's event.
      */
     handleNativeEvent(event: NativeUiEvent): boolean;
     /** Wheel scroll over the sidebar. */

package/dist/types/chat/recap-notice.d.ts

@@ -0,0 +1,13 @@
+import type { NativeNode } from "../native/node.js";
+import { Container } from "../tui.js";
+/**
+ * The idle recap (`recap.*`): where the session stands, written while the user
+ * was away. Stays in the transcript like a thought: a dim italic `※ recap:`
+ * line in ANSI, a history icon beside the italic thought-coloured text in a
+ * native terminal (`omp.recap`).
+ */
+export declare class RecapNotice extends Container {
+    #private;
+    constructor(recap: string);
+    describe(): NativeNode;
+}

package/dist/types/components/editor.d.ts

@@ -1,6 +1,6 @@
 import { type AutocompleteProvider } from "../autocomplete.js";
 import type { TspEditorDecoration, TspTone } from "@oh-my-pi/pi-wire";
-import type { DescribeContext, NativeChild, NativeNode } from "../native/node.js";
+import { type DescribeContext, type NativeChild, type NativeNode, type NativeTextEdit, type NativeUiEvent } from "../native/node.js";
 import type { SymbolTheme } from "../symbols.js";
 import { type Component, type Focusable } from "../tui.js";
 import { type VimMode } from "../vim.js";
@@ -102,11 +102,12 @@ export declare class Editor implements Component, Focusable {
      * TSP chrome around the `editor` node (the prompt composer's chips, mode
      * chip, send/stop): the root role, the children with `input` placed where
      * the layout wants it, and the input's keypath for the caret-anchored
-     * autocomplete. Unset: a plain `omp.editor` column over the input.
+     * autocomplete. Unset: a plain `omp.field` column over the input (a
+     * dialog's text field; only the prompt composer claims `omp.editor`).
      */
     describeLayout: ((input: NativeNode, cx: DescribeContext) => NativeEditorLayout) | undefined;
     /** TSP placeholder for the empty buffer; natively it replaces the rotating ANSI {@link placeholder} hints. */
-    nativePlaceholder: string | undefined;
+    describePlaceholder: (() => string) | undefined;
     /** Called with the selected text when Visual mode yanks, so hosts can reach the system
      *  clipboard — `packages/tui` deliberately has no clipboard dependency of its own. */
     onYank?: (text: string) => void;
@@ -295,6 +296,17 @@ export declare class Editor implements Component, Focusable {
     submit(): void;
     /** Insert text at the current cursor position */
     insertText(text: string): void;
+    /** Terminal-side selection edits on the `editor` node (see {@link applyHostEdit}). */
+    handleNativeEvent(event: NativeUiEvent): void;
+    /**
+     * Apply an edit the terminal made over its own selection (TSP `edit`):
+     * replace `[from, to)` of the described text with `text` and put the caret
+     * at `cursor`, as one undo unit that leaves history browsing and updates
+     * autocomplete like typing. A range cutting through an atomic placeholder
+     * token takes the whole token. Stale edits (`len` no longer the text's
+     * length) are dropped; a pure caret move only moves the caret.
+     */
+    applyHostEdit(edit: NativeTextEdit): void;
     /** Delete up to `count` characters immediately before the cursor on the current line.
      *  Used to "track back" the auto-repeat spaces that the space-hold push-to-talk gesture
      *  optimistically inserts before it recognizes the hold. Capped at the cursor column so it

package/dist/types/components/input.d.ts

@@ -1,4 +1,4 @@
-import type { DescribeContext, NativeNode } from "../native/node.js";
+import { type DescribeContext, type NativeNode, type NativeTextEdit, type NativeUiEvent } from "../native/node.js";
 import { SpaceHoldGesture } from "../space-hold.js";
 import { type Component, type Focusable } from "../tui.js";
 /**
@@ -39,6 +39,16 @@ export declare class Input implements Component, Focusable {
     /** Apply terminal paste semantics to text from non-bracketed paste transports
      *  (e.g. kitty's OSC 5522 enhanced clipboard read). Mirrors `Editor.pasteText`. */
     pasteText(text: string): void;
+    /** Terminal-side selection edits on the `input` node (see {@link applyHostEdit}). */
+    handleNativeEvent(event: NativeUiEvent): void;
+    /**
+     * Apply an edit the terminal made over its own selection (TSP `edit`):
+     * replace `[from, to)` with `text` (newlines stripped, as a paste) and put
+     * the caret at `cursor`, as one undo unit. Offsets are in the described
+     * text, so a masked field's count bullets, one per grapheme. Stale edits
+     * (`len` no longer the described length) are dropped.
+     */
+    applyHostEdit(edit: NativeTextEdit): void;
     /** Programmatically trigger submission (e.g. for voice submit). */
     submit(): void;
     /** Delete up to `count` characters immediately before the cursor. */

package/dist/types/native/backend.d.ts

@@ -1,6 +1,6 @@
 import { type TspFrame, type TspNode } from "@oh-my-pi/pi-wire";
 import type { Terminal } from "../terminal.js";
-import type { Component, OverlayOptions } from "../tui.js";
+import type { Component, OverlayOptions, RenderScheduler } from "../tui.js";
 import { type TspHello } from "./encode.js";
 import type { DescribeContext, NativeSurface } from "./node.js";
 /** A visible TUI overlay, bottom to top. */
@@ -34,7 +34,8 @@ export interface NativeBackendOptions {
     readonly recordPath?: string;
     /** Log the `rows` fallback count per frame. Defaults to `PI_TUI_NATIVE_STATS=1`. */
     readonly stats?: boolean;
-    readonly now?: () => number;
+    /** Clock and timers (stall wake-up); defaults to `Date.now` and unref'd `setTimeout`. */
+    readonly scheduler?: RenderScheduler;
 }
 /**
  * The reply a v1 terminal is assumed to give before its real `hello` arrives

package/dist/types/native/blobs.d.ts

@@ -21,7 +21,7 @@ export declare function getNativeBlob(id: string): NativeBlob | undefined;
  * the pixel size probed from the header. Decoding and hashing cost real time,
  * so callers cache the node per payload ({@link NativeImageCache}).
  */
-export declare function base64ImageNode(data: string, mimeType: string, p?: Omit<TspProps<"image">, "blob" | "w" | "h">, key?: string): NativeNode;
+export declare function base64ImageNode(data: string, mimeType: string, p?: Omit<TspProps<"image">, "blob" | "builtin" | "w" | "h">, key?: string): NativeNode;
 /** `image` nodes for base64 payloads, one per slot key, rebuilt only when the slot's payload changes. */
 export declare class NativeImageCache {
     #private;

package/dist/types/native/node.d.ts

@@ -27,6 +27,11 @@ export type NativeNode = {
          * or reordered so their ids and terminal-side view state survive.
          */
         readonly key?: string;
+        /**
+         * Scroll the node into view, placed like the `reveal` op, when it is
+         * added. Key a node by what it points at to reveal it again on a move.
+         */
+        readonly reveal?: "start" | "end" | "nearest";
     };
 }[TspKind];
 /** A child slot: a described node, or a component that describes itself. */
@@ -55,6 +60,14 @@ export interface NativeSurface {
     /** Sticky bottom chrome while live (editor, status line, HUDs). */
     readonly dock: readonly NativeChild[];
 }
+/**
+ * The screen surface a fullscreen overlay fills as a page of its own (see
+ * `Component.describeScreen`): its regions plus the surface `role`, which the
+ * terminal exposes to styling.
+ */
+export interface NativeScreen extends NativeSurface {
+    readonly role: string;
+}
 /**
  * A user action on a node a component described, routed back to that
  * component. `key` is the node's key path inside the component (`""` for the
@@ -86,7 +99,56 @@ export type NativeUiEvent = {
     readonly key: string;
     readonly item: string;
     readonly value: boolean | number | string | readonly string[] | null;
-};
+}
+/** An edit over the terminal's own selection in an `editor`/`input` node (see {@link NativeTextEdit}). */
+ | ({
+    readonly type: "edit";
+    readonly key: string;
+} & NativeTextEdit);
+/**
+ * A primitive edit the terminal made over its own text selection (cut,
+ * typing, Backspace/Delete or paste over it, or collapsing it). Offsets are
+ * UTF-16 code units into the text last described (lines joined with `"\n"`),
+ * the coordinates of the node's `cursor`: replace `[from, to)` with `text`,
+ * then put the caret at `cursor` in the resulting text. `from == to` with an
+ * empty `text` is a pure caret move. `len` is the length of the text the
+ * terminal saw: when the current text differs (keys in flight changed it) the
+ * edit is stale and ignored.
+ */
+export interface NativeTextEdit {
+    readonly from: number;
+    readonly to: number;
+    readonly text: string;
+    readonly cursor: number;
+    readonly len: number;
+}
+/** A {@link NativeTextEdit} checked against the current text and clamped, ready to apply. */
+export interface ResolvedTextEdit {
+    /** Replaced range in the current text, widened by the caller's `widen`. */
+    readonly from: number;
+    readonly to: number;
+    /** The cleaned replacement. */
+    readonly insert: string;
+    /** The whole text after the edit. */
+    readonly text: string;
+    /** Caret in {@link text}. */
+    readonly cursor: number;
+    /** Whether the text changes (false: a pure caret move). */
+    readonly changed: boolean;
+}
+/** `value` as an integer offset in `[0, max]` (anything non-finite is 0). */
+export declare function clampTextOffset(value: number, max: number): number;
+/**
+ * Check `edit` against `current` and resolve it: null when stale (`len`
+ * differs), else the range clamped (reversed ends swapped, never splitting a
+ * surrogate pair), widened by `widen` when non-empty, the replacement passed
+ * through `clean`, and the caret mapped from the text the terminal expects
+ * onto the text the edit actually produces.
+ */
+export declare function resolveTextEdit(current: string, edit: NativeTextEdit, clean: (text: string) => string, widen?: (from: number, to: number) => {
+    from: number;
+    to: number;
+}): ResolvedTextEdit | null;
 /** The expanded state a `toggle` on the component's root node asks for, else undefined. */
 export declare function rootToggleExpanded(event: NativeUiEvent): boolean | undefined;
 /** The last segment of an event keypath (`"split/sidebar/toc"` → `"toc"`). */

package/dist/types/overlays/agent-hub-projection.d.ts

@@ -15,6 +15,15 @@ interface AgentTreeProjection<TRecord extends AgentRecordLike> {
 export declare const STATUS_ORDER: Record<AgentStatus, number>;
 /** Exact observer usage for one roster entry. */
 export declare function progressMetrics(observed: ObservableSession | undefined): AgentMetrics | undefined;
+/** Live session whose own messages back a row's metrics when no observer progress exists. */
+export declare function hubFallbackStatsSession<TRecord extends AgentRecordLike>(ref: TRecord, observed: ObservableSession | undefined): NonNullable<TRecord["session"]> | undefined;
+/**
+ * One roster row's usage: live observer progress, then persisted history, then
+ * the cached fallback read of a live session (populated by {@link aggregateMetrics}).
+ */
+export declare function hubRowMetrics<TRecord extends AgentRecordLike>(ref: TRecord, observed: ObservableSession | undefined, sessionMetrics: WeakMap<object, {
+    metrics: AgentMetrics | undefined;
+}>): AgentMetrics | undefined;
 export declare function aggregateMetrics<TRecord extends AgentRecordLike>(args: {
     rows: readonly TRecord[];
     observedById: ReadonlyMap<string, ObservableSession>;

package/dist/types/overlays/ask-dialog.d.ts

@@ -45,15 +45,19 @@ export interface ExtensionAskDialogChatResult {
 /** Completed dialog action, distinct from cancellation. */
 export type ExtensionAskDialogResult = ExtensionAskDialogSubmitResult | ExtensionAskDialogChatResult;
 import { type DescribeContext, type NativeNode, type NativeUiEvent } from "../native/node.js";
-/** Bound a prompt editor title to a fixed row/width budget so long or
- *  multi-line questions stay usable inside the small prompt overlay. */
-export declare function boundPromptTitle(prefix: string, question: string): string;
+/** What a custom-answer or note prompt asks: the host shows `title` over `question` (`HookEditorOptions.question`). */
+export interface AskDialogPrompt {
+    /** `Custom answer`, `Note for <option>`. */
+    title: string;
+    /** The question being answered, verbatim. */
+    question: string;
+}
 interface AskDialogCallbacks {
     onSubmit(result: ExtensionAskDialogSubmitResult): void;
     onCancel(): void;
-    onPrompt(title: string, prefill?: string): Promise<string | undefined>;
+    onPrompt(prompt: AskDialogPrompt, prefill?: string): Promise<string | undefined>;
     /** Prompt that accepts pasted images; without it, prompts use `onPrompt`. */
-    onImagePrompt?(title: string, prefill: AskDialogPromptValue | undefined): Promise<AskDialogPromptValue | undefined>;
+    onImagePrompt?(prompt: AskDialogPrompt, prefill: AskDialogPromptValue | undefined): Promise<AskDialogPromptValue | undefined>;
 }
 interface AskDialogInputGuard {
     isBlocked(): boolean;

package/dist/types/overlays/copy-selector.d.ts

@@ -15,36 +15,13 @@
  * mouse selection nor cmd-click.
  */
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
-import type { TspPickerColumn, TspPickerItem, TspText } from "@oh-my-pi/pi-wire";
 import { type Component, type TUI } from "../index.js";
 import type { MessageRenderer } from "../chat/extension-types.js";
 import { type TranscriptEntryLike as TranscriptEntry } from "../chat/transcript-entry.js";
 import { type OutlineTarget } from "../chat/transcript-outline.js";
 import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
-/** Key of the leading list item that replays the history older than the startup tail. */
-export declare const EARLIER_TURNS_KEY = "earlier";
-/** Leading item of a truncated transcript list; selecting it loads the older turns. */
-export declare const earlierTurnsItem: NativeNode;
-/**
- * One list item per outline target, keyed by the turn's opening entry id:
- * the plain turn summary as label, `detail` (or the entry time) on the right.
- */
-export declare function turnItem(target: OutlineTarget, detail?: TspText): NativeNode;
 /** Preview of a turn's text: prose as markdown, command/tool output as a plain code block. */
 export declare function turnPreview(target: OutlineTarget, content: string): NativeNode;
-/** The timeline pickers' one fact column: a user turn's clock time. */
-export declare const TIMELINE_COLUMNS: readonly TspPickerColumn[];
-/**
- * The `timeline` picker item of one outline target (rewind, copy), keyed by
- * the turn's opening entry id: user turns carry their `HH:MM`, pure tool turns
- * the tool's role and a `name target` label.
- */
-export declare function timelineItem(target: OutlineTarget): TspPickerItem;
-/** Timeline picker items for `targets`, reused while `targets` is the same array. */
-export declare class TimelineItems {
-    #private;
-    of(targets: readonly OutlineTarget[]): TspPickerItem[];
-}
 export interface CopySelectorDeps {
     ui: TUI;
     getTool?: (name: string) => AgentTool | undefined;

package/dist/types/overlays/error-banner.d.ts

@@ -8,14 +8,17 @@ import type { NativeNode, NativeUiEvent } from "../native/node.js";
  * be missed. It is cleared when the next turn starts. The message wraps to the
  * render width and keeps {@link MAX_BANNER_ROWS} rows; the expand hint on the
  * overflow row reveals the full body inline in the transcript.
+ *
+ * Natively the transcript's error frame always shows the full message, so the
+ * strip is only a reminder and offers a Dismiss button that calls `onDismiss`.
  */
 export declare class ErrorBannerComponent extends Container {
     #private;
-    constructor(message: string);
+    constructor(message: string, onDismiss?: () => void);
     /**
      * An error-tinted strip pinned above the composer: the message's first line
      * (the transcript's error frame keeps the full message and its actions)
-     * and a Details button that unfolds the rest here.
+     * and a Details button that unfolds the rest here, then Dismiss.
      */
     describe(): NativeNode;
     handleNativeEvent(event: NativeUiEvent): void;

package/dist/types/overlays/hook-editor.d.ts

@@ -11,11 +11,23 @@ import type { ImageContent } from "@oh-my-pi/pi-ai";
 import { type Focusable, type TUI } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
 import type { DescribeContext, NativeNode } from "../native/node.js";
+/**
+ * `prefix` and `question` flattened onto one line, wrapped to the terminal's width and cut to
+ * {@link MAX_PROMPT_TITLE_ROWS} rows (the last ends in `…` when cut). For terminal rendering only:
+ * native hosts get the question whole ({@link HookEditorOptions.question}).
+ */
+export declare function boundPromptTitle(prefix: string, question: string): string;
 export interface HookEditorOptions {
     /** Edit text with the host's configured external editor. */
     externalEditor?: (text: string) => Promise<string | null>;
     /** When true, use prompt-style keybindings with the legacy ask prompt chrome. */
     promptStyle?: boolean;
+    /**
+     * The question the text answers (the ask tool's custom answers and notes). The terminal
+     * shows it after `<title>: `, wrapped and cut to three rows; native hosts put it whole,
+     * as markdown, under the title.
+     */
+    question?: string;
     /** Allow clipboard images to be attached to this prompt. */
     acceptImages?: boolean;
     /** Images already represented by markers in the prefilled text. */

package/dist/types/overlays/jobs-panel.d.ts

@@ -1,5 +1,5 @@
 import { type Component, Container } from "../tui.js";
-import type { DescribeContext, NativeNode } from "../native/node.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /** One async job as the session snapshots it. */
 export interface JobsPanelJob {
     readonly id: string;
@@ -22,3 +22,27 @@ export declare class JobsPanel extends Container {
     constructor(snapshot: JobsPanelSnapshot, nowMs: number, ansi: readonly Component[]);
     describe(cx: DescribeContext): NativeNode;
 }
+/**
+ * The jobs pill's sheet: a centred `md` glass sheet titled Background jobs
+ * that re-reads the session's jobs on every frame, so rows start, settle and
+ * move to Recent while it is open. Esc or Close dismisses it; nothing enters
+ * the transcript.
+ */
+export declare class JobsSheet implements Component {
+    #private;
+    readonly nativeOverlay: {
+        readonly role: "omp.overlay.jobs";
+        readonly size: "md";
+        readonly anchor: "center";
+        readonly head: "Background jobs";
+    };
+    /** `load` returns the current jobs; it runs once per frame. */
+    constructor(load: () => JobsPanelSnapshot, onClose: () => void);
+    describe(cx: DescribeContext): NativeNode;
+    /** Rows for a terminal without the native surface: status, label, type and age per job. */
+    render(width: number): readonly string[];
+    invalidate(): void;
+    handleInput(data: string): void;
+    /** Close runs what Esc runs. */
+    handleNativeEvent(event: NativeUiEvent): void;
+}

package/dist/types/overlays/rewind-selector.d.ts

@@ -24,12 +24,16 @@
  * filter with the selection kept), Enter rewinds to the outlined item, A loads
  * earlier turns without changing selection (stepping above the oldest replayed
  * turn loads them too), Esc cancels.
+ *
+ * In a TSP terminal (Tern) the same replay is a page, not a sheet: a screen
+ * surface of the transcript's own blocks with `pick`/`drop` marks in place of
+ * the dotted outline (see `describeScreen`).
  */
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import { type Component, type TUI } from "../index.js";
 import type { MessageRenderer } from "../chat/extension-types.js";
 import { type TranscriptEntryLike as TranscriptEntry } from "../chat/transcript-entry.js";
-import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
+import type { DescribeContext, NativeNode, NativeScreen, NativeUiEvent } from "../native/node.js";
 /** One alternate branch at a divergence: its root and message path root → most-recent leaf. */
 export interface BranchVariantPath {
     rootId: string;
@@ -61,9 +65,18 @@ export declare class RewindSelectorComponent implements Component {
     invalidate(): void;
     dispose(): void;
     handleInput(data: string): void;
-    /** A `picker` is its own sheet: the backend mounts it in `layer`, over the transcript. */
-    nativeSheet(cx: DescribeContext): boolean;
+    /**
+     * The rewind page: the replayed transcript fills a screen surface block by
+     * block, as the live one reads, the outlined turn marked `pick` under a
+     * "Continue from here" caption (revealed as the outline moves) and what the
+     * rewind drops marked `drop`. At a fork the region below it becomes a strip
+     * of branch columns, the current path first. The bar is this component's
+     * own node, docked under the page, so the filter field keeps the caret.
+     */
+    describeScreen(_cx: DescribeContext): NativeScreen;
+    /** The bar docked under the page: position, key hints, Cancel and Rewind; the filter field while filtering. */
+    describe(_cx: DescribeContext): NativeNode;
+    /** The bar's buttons run their keys' paths; everything else belongs to the blocks. */
     handleNativeEvent(event: NativeUiEvent): void;
-    describe(cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/prompt/custom-editor.d.ts

@@ -20,6 +20,8 @@ export interface ComposerNativeState {
     readonly thinking?: string;
     /** A turn is running: the send keycap becomes a Stop button. */
     readonly running: boolean;
+    /** The viewed subagent's lineage, outermost first and the viewed agent last; undefined on the main session. */
+    readonly viewing?: readonly string[];
 }
 /** Independently switchable prose-assistance features of the composer. */
 export interface SpellingFeatures extends MacOSSpellingFeatures {
@@ -211,7 +213,8 @@ export declare class CustomEditor extends Editor {
      *  once after construction (and again after `setEditorComponent` swaps the
      *  editor). Passing `undefined` clears any pending frame. */
     setShimmerRepaintHandler(handler: (() => void) | undefined): void;
-    nativePlaceholder: string | undefined;
+    /** Viewing a subagent, the draft goes to it: the placeholder names it. */
+    describePlaceholder: () => string;
     /** A shell-mode draft highlights as its language. */
     describeLanguage: () => string | undefined;
     /** Host-owned live state for the TSP composer (shell mode, effort chip, send/stop). */
@@ -222,16 +225,19 @@ export declare class CustomEditor extends Editor {
     composerFacts: ComposerFactsSource | undefined;
     /**
      * The TSP composer: role `omp.editor[.bash|.python]` (tone `pending` while
-     * a turn runs) over the context hairline, the attachment chips, a `line`
-     * row of the shell-mode chip and the input, and the `bar`: model chip,
-     * effort chip, the other status facts, usage, then send (Stop while a turn
-     * runs). Clicks come back as `status.model`, `thinking.cycle`, `submit`
-     * and `interrupt` actions.
+     * a turn runs) over the context hairline, the viewing header while a
+     * subagent is focused, the attachment chips, a `line` row of the
+     * shell-mode chip and the input, and the `bar`: model chip, effort chip,
+     * the other status facts, usage, then send (Stop while a turn runs).
+     * Clicks come back as `status.model`, `thinking.cycle`, `submit`,
+     * `interrupt` and `focus:<id>` actions.
      */
-    describeLayout: (input: NativeNode, _cx: DescribeContext) => NativeEditorLayout;
+    describeLayout: (input: NativeNode, cx: DescribeContext) => NativeEditorLayout;
     /**
      * Clicks on the composer's controls take the same paths as their keys: ⇧⇥,
-     * ⏎ and Esc; the status facts' clicks (`status.*`) go to their source.
+     * ⏎ and Esc; the viewing header's links (`focus:<id>`) go to the host,
+     * the status facts' clicks (`status.*`) to their source. Selection edits
+     * go to the buffer.
      */
     handleNativeEvent(event: NativeUiEvent): void;
     onEscape?: () => void;
@@ -260,6 +266,8 @@ export declare class CustomEditor extends Editor {
     onCapsLock?: () => void;
     /** Called when left-arrow is pressed while the editor is empty (cursor necessarily at start). */
     onLeftAtStart?: () => void;
+    /** Called when the viewing header asks to view agent `id` ({@link MAIN_AGENT_ID}: the main session). */
+    onFocusAgent?: (id: string) => void;
     /** Space-bar push-to-talk; set its `handler` to enable it. It is a text-composition gesture, so it
      *  stays out of Vim's Normal/Visual modes (where the space bar is the `l` motion) and away from an
      *  open autocomplete menu. */

package/dist/types/prompt/welcome.d.ts

@@ -44,9 +44,9 @@ export declare class WelcomeComponent implements Component {
     invalidate(): void;
     /**
      * A `card` (`omp.welcome`) titled with the app version. The brand column
-     * (`omp.welcome.brand`: greeting, the animated SVG mark, model, provider) sits
-     * beside the info column (`omp.welcome.info`: prompt-sigil keycaps, LSP
-     * servers, recent sessions); the tip of the session closes the card. Roles
+     * (`omp.welcome.brand`: greeting and the terminal's builtin `omp` mark, which
+     * it animates) sits beside the info column (`omp.welcome.info`: prompt-sigil
+     * keycaps, LSP servers, recent sessions); the tip of the session closes the card. Roles
      * carry the look (gradient logo, type scale, column hairline); a "[NEW]" tip
      * carries a terminal-clocked shimmering tag.
      */

package/dist/types/status-line/component.d.ts

@@ -31,6 +31,8 @@ export declare class StatusLineComponent<TSession extends StatusLineSession = St
     getEffectiveSettingsForTest(): EffectiveStatusLineSettings;
     setAutoCompactEnabled(enabled: boolean): void;
     setRunningSubagents(agentIds: readonly string[]): void;
+    /** Host-computed spend of the main session's whole subagent tree (Agent Hub projection). */
+    setSubagentTreeCost(cost: number): void;
     /**
      * Compatibility shim for callers predating the simplified subagent badge.
      * The status line now intentionally shows only the active count.

package/dist/types/status-line/host.d.ts

@@ -51,6 +51,8 @@ export interface StatusLineSession {
             orchestrationCacheRead: number;
             premiumRequests: number;
             cost: number;
+            /** Portion of `cost` carried by completed subagent task results. */
+            subagentCost?: number;
         };
     };
     modelRegistry: {

package/dist/types/status-line/metrics.d.ts

@@ -7,6 +7,8 @@ export interface BillingSummaryOptions {
     readonly premiumRequests: number;
     readonly fractionDigits: number;
     readonly pricingPeriod?: "peak" | "off-peak";
+    /** Subagent-tree spend, rendered `(+…)` after the session's own spend; `cost` excludes it. */
+    readonly subagentCost?: number;
     readonly advisor?: {
         readonly cost: number;
         readonly usingSubscription: boolean;
@@ -15,5 +17,7 @@ export interface BillingSummaryOptions {
 /**
  * Shared billing metric presentation. Callers select precision explicitly so
  * the legacy footer keeps three decimals while current status segments keep two.
+ * A unit symbol (`$` or the subscription mark) is printed at most once; later
+ * amounts billed the same way render bare.
  */
 export declare function formatBillingSummary(options: BillingSummaryOptions, uiTheme: Theme): string | undefined;

package/dist/types/status-line/types.d.ts

@@ -137,6 +137,8 @@ export interface SegmentContext {
         orchestrationCacheRead: number;
         premiumRequests: number;
         cost: number;
+        /** Portion of `cost` carried by completed subagent task results. */
+        subagentCost?: number;
         tokensPerSecond: number | null;
     };
     /** Context usage percent, or null when unknown (e.g. right after compaction). */
@@ -149,6 +151,11 @@ export interface SegmentContext {
     /** Blink phase for the running-speculation pulse; toggled by the component's timer. */
     speculationBlinkOn: boolean;
     subagentCount: number;
+    /**
+     * Spend of every subagent under the main session (descendants included),
+     * from the Agent Hub projection; 0 while a subagent is focused or unknown.
+     */
+    subagentTreeCost?: number;
     /**
      * Active processing time accumulated this session, in ms — the union of
      * every `agent_start`→`agent_end` window plus the currently-streaming
@@ -242,7 +249,11 @@ export interface SegmentView {
  * and branch, and the composer the rest.
  */
 export interface ComposerFacts {
-    /** `meter` (role `omp.composer.context`): context usage along the composer's top edge. */
+    /**
+     * `meter` (role `omp.composer.context`): context usage along the composer's top edge,
+     * the whole window wide, with the speculation and compaction points as icon marks,
+     * the share as `label` and the window as `total`.
+     */
     readonly context: NativeNode;
     /** The model chip's label: name plus the advisor, fast-mode and slow-mode marks. */
     readonly model: SegmentView;
@@ -251,7 +262,7 @@ export interface ComposerFacts {
      * segments as `seg`s; the bar's flexible space, so present even when empty.
      */
     readonly extras: NativeNode;
-    /** `text` (role `omp.composer.usage`): the context share of the window and the session cost. */
+    /** `text` (role `omp.composer.usage`): the session cost (empty when there is none). */
     readonly usage: NativeNode;
 }
 /** Supplies {@link ComposerFacts} and takes the clicks on them (`status.*` actions). */