@linxiraos/pi-tui 1.1.26 → 1.2.0

package/dist/types/keybindings.d.ts

@@ -107,7 +107,7 @@ export declare const TUI_KEYBINDINGS: {
         readonly description: "Delete word backward";
     };
     readonly "tui.editor.deleteWordForward": {
-        readonly defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"];
+        readonly defaultKeys: ["alt+delete", "alt+d", "ctrl+delete", "super+alt+delete", "super+alt+d"];
         readonly description: "Delete word forward";
     };
     readonly "tui.editor.deleteToLineStart": {

package/dist/types/kitty-graphics.d.ts

@@ -30,8 +30,8 @@ export interface KittyGraphicsFeatures {
  * cannot use cursor-positioned placements because the outer terminal does not
  * know pane scroll/reflow state. An explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
  * opts into placeholders under any multiplexer — matching `timg -pk`.
- * Automatic Herdr fallback stays off because its pane marker does not prove
- * that the experimental Kitty renderer is enabled.
+ * Automatic fallback stays off inside multiplexers whose pane marker does not
+ * prove that a Kitty renderer is enabled (Herdr's is experimental).
  *
  * `PI_NO_KITTY_PLACEHOLDERS=1` and `PI_KITTY_PLACEHOLDERS=0` remain hard
  * opt-outs; `PI_KITTY_PLACEHOLDERS=1` explicitly opts in anywhere else.

package/dist/types/loop-watchdog.d.ts

@@ -21,13 +21,14 @@ interface LoopWatchdogTimer {
     cancel?(): void;
 }
 /**
- * Always-on event-loop lag probe. Each tick is scheduled `intervalMs` ahead of
- * a recorded deadline; a tick that fires `thresholdMs` past its deadline means
- * the loop was blocked that long. The overshoot is logged once on the rising
- * edge (one block ⇒ one line, deduped via `#wasBlocked`), tagged with the phase
- * active during the elapsed interval via {@link takeRecentLoopPhase} — which
- * survives the synchronous push/pop the instrumented hot paths do before this
- * delayed tick can run — so the stall names its cause instead of "unknown".
+ * Always-on event-loop lag probe. Each tick is scheduled `intervalMs` ahead,
+ * with that target recorded as its deadline; a tick that fires `thresholdMs`
+ * past its deadline means the loop was blocked that long. The overshoot is
+ * logged once on the rising edge (one block ⇒ one line, deduped via
+ * `#wasBlocked`). Attribution via
+ * {@link takeLoopPhaseAttribution} totals each innermost phase only after the tick's
+ * deadline. A phase is named, with `phaseMs`, only when its total outweighs all
+ * unlabeled time in that late window; otherwise the block remains "unknown".
  *
  * The handle is `unref`'d so the probe never keeps the process alive, and stop()
  * cancels the armed timer when the handle exposes `cancel` (the default

package/dist/types/multiplexers/cmux.d.ts

@@ -0,0 +1,16 @@
+export declare const cmuxMultiplexer: {
+    readonly id: "cmux";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["CMUX_WORKSPACE_ID", "CMUX_SURFACE_ID", "CMUX_REMOTE_TRANSPORT"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    /**
+     * Workspace/socket state alone is not enough: only the injected surface UUID
+     * identifies the pane that should receive the notification. Without a valid
+     * surface, or without the binary, delivery falls through unchanged.
+     */
+    readonly notifier: {
+        readonly tier: "surface";
+        readonly send: ({ message, env }: import("./types.js").TerminalMultiplexerNotificationRequest) => boolean;
+    };
+};

package/dist/types/multiplexers/herdr.d.ts

@@ -0,0 +1,26 @@
+export declare const herdrMultiplexer: {
+    readonly id: "herdr";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["HERDR_ENV", "HERDR_PANE_ID", "HERDR_TAB_ID", "HERDR_WORKSPACE_ID"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    /**
+     * Herdr multiplexes panes like tmux but swallows bare OSC 9 / OSC 99 and has
+     * no DCS passthrough envelope, and its bell relay does not flag a
+     * backgrounded tab — so without its CLI a backgrounded pane gets no signal
+     * at all that the agent finished or is waiting for input.
+     *
+     * `sound` maps the notification kind onto what Herdr offers: a question
+     * waiting on the user and a turn that stopped with an error both need the
+     * human and ring `request`, a settled turn rings `done`, anything else stays
+     * silent. The exact pane ID addresses the CLI call; without a valid one, or
+     * without the binary, delivery falls through.
+     */
+    readonly notifier: {
+        readonly tier: "pane";
+        readonly send: ({ message, env }: import("./types.js").TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly hyperlinks: "render";
+    readonly honorsSynchronizedOutput: true;
+    readonly imagesRequireOverride: true;
+};

package/dist/types/multiplexers/notify.d.ts

@@ -0,0 +1,13 @@
+import type { TerminalNotification } from "../terminal-capabilities.js";
+/** Title for out-of-band multiplexer notifications that carry none of their own. */
+export declare const DEFAULT_NOTIFICATION_TITLE = "omp";
+/** Title and body for an out-of-band multiplexer notification (cmux, Herdr). */
+export declare function notificationTitleAndBody(message: string | TerminalNotification): {
+    title: string;
+    body: string;
+};
+/**
+ * Start a notifier CLI without waiting for or pinning it. Returns false when
+ * the binary cannot be spawned, which leaves delivery to the terminal fallback.
+ */
+export declare function spawnNotifier(cmd: string[]): boolean;

package/dist/types/multiplexers/orca.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Orca is an xterm.js-based IDE whose terminals expose paired pane/worktree IDs.
+ * It is recognized for launches, but it ranks below nested multiplexers and keeps
+ * the direct-terminal render path it used before it was recognized.
+ */
+export declare const orcaMultiplexer: {
+    readonly id: "orca";
+    readonly precedence: "outerApp";
+    readonly sessionEnvKeys: readonly ["ORCA_PANE_KEY", "ORCA_WORKTREE_ID"];
+    readonly ownsScreenGrid: false;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+};

package/dist/types/multiplexers/screen.d.ts

@@ -0,0 +1,9 @@
+export declare const screenMultiplexer: {
+    readonly id: "screen";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["STY"];
+    readonly termPrefix: "screen";
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly hyperlinks: "drop";
+};

package/dist/types/multiplexers/tmux.d.ts

@@ -0,0 +1,29 @@
+/** Wrap a control sequence in tmux's DCS passthrough envelope. */
+export declare function wrapTmuxPassthrough(payload: string): string;
+export declare const tmuxMultiplexer: {
+    readonly id: "tmux";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["TMUX"];
+    readonly termPrefix: "tmux";
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "inBand";
+        readonly send: ({ sequence, write }: import("./types.js").TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly hyperlinks: {
+        readonly forward: {
+            readonly termProgram: "tmux";
+            readonly major: 3;
+            readonly minor: 4;
+        };
+    };
+    readonly backgroundColorCache: {
+        readonly passthrough: typeof wrapTmuxPassthrough;
+        readonly settleMs: 100;
+    };
+    readonly expandsRepPadding: true;
+    readonly expiresSynchronizedOutput: true;
+    readonly altRestoreEndsSynchronizedOutput: true;
+    readonly growsBeforeSigwinch: true;
+};

package/dist/types/multiplexers/types.d.ts

@@ -0,0 +1,100 @@
+import type { TerminalNotification } from "../terminal-capabilities.js";
+/**
+ * Classification tier. `session` markers outrank the TERM fallback; `outerApp`
+ * hosts rank below it so a multiplexer nested inside them still wins.
+ */
+export type TerminalMultiplexerPrecedence = "session" | "outerApp";
+/**
+ * Notification delivery tier, tried in this order so the innermost target wins:
+ * a `pane` notifier addresses the exact pane through the multiplexer's CLI, a
+ * `surface` notifier addresses the containing app surface, and an `inBand`
+ * notifier rewrites the terminal's own notification sequence.
+ */
+export type TerminalMultiplexerNotificationTier = "pane" | "surface" | "inBand";
+/** One notification offered to a multiplexer notifier. */
+export interface TerminalMultiplexerNotificationRequest {
+    readonly message: string | TerminalNotification;
+    readonly env: NodeJS.ProcessEnv;
+    /** The host terminal's formatted OSC notification, or `null` when it notifies with a bare BEL. */
+    readonly sequence: string | null;
+    /** Write a sequence through the active terminal. */
+    write(data: string): void;
+}
+export interface TerminalMultiplexerNotifier {
+    readonly tier: TerminalMultiplexerNotificationTier;
+    /** Deliver the notification. `false` leaves it to the next notifier and then the terminal fallback. */
+    send(request: TerminalMultiplexerNotificationRequest): boolean;
+}
+/**
+ * OSC 8 handling inside a multiplexer session:
+ * - `render`: the multiplexer draws and opens links itself, so links work
+ *   whatever the outer terminal supports, unless another session with a
+ *   hyperlink policy sits in the path.
+ * - `drop`: never forwards OSC 8; its session anywhere in the path disables links.
+ * - `forward`: forwards OSC 8 once it self-reports (`TERM_PROGRAM`/`TERM_PROGRAM_VERSION`)
+ *   at least `major.minor`; older or unreported versions stay off.
+ */
+export type TerminalMultiplexerHyperlinks = "render" | "drop" | {
+    readonly forward: {
+        /** Lowercase `TERM_PROGRAM` the multiplexer sets inside its panes. */
+        readonly termProgram: string;
+        readonly major: number;
+        readonly minor: number;
+    };
+};
+/** A multiplexer that answers OSC 11 from a cached copy of the outer terminal's background color. */
+export interface TerminalMultiplexerBackgroundColorCache {
+    /** Wrap a query so it reaches the outer terminal and refreshes the cache. */
+    passthrough(query: string): string;
+    /** How long the multiplexer needs to store the outer reply before the cache is re-read. */
+    readonly settleMs: number;
+}
+/** Everything omp needs to recognize one terminal multiplexer and adapt to it. */
+export interface TerminalMultiplexerModule<Id extends string = string> {
+    readonly id: Id;
+    readonly precedence: TerminalMultiplexerPrecedence;
+    /** Every environment variable `isInside()` reads. */
+    readonly sessionEnvKeys: readonly string[];
+    /** Lowercase TERM prefix that identifies the multiplexer when its session markers were stripped. */
+    readonly termPrefix?: string;
+    /**
+     * Whether the multiplexer owns the screen grid. When true, rendering takes the
+     * multiplexer path (no scrollback rebuild, anchored resize, skipped probes).
+     */
+    readonly ownsScreenGrid: boolean;
+    isInside(env?: NodeJS.ProcessEnv): boolean;
+    /** Routes notifications the multiplexer would otherwise swallow. */
+    readonly notifier?: TerminalMultiplexerNotifier;
+    /** OSC 8 policy inside a session; unset defers to the outer terminal. */
+    readonly hyperlinks?: TerminalMultiplexerHyperlinks;
+    /**
+     * The pane's VTE honors DEC 2026 even when DECRQM is unanswered or reports
+     * the mode unrecognized (status 0): synchronized output starts on inside a
+     * session, and an unrecognized report does not turn it off.
+     */
+    readonly honorsSynchronizedOutput?: boolean;
+    /**
+     * The session does not reveal whether its client renders graphics while
+     * outer-terminal identity variables leak in, so images and Kitty
+     * placeholders stay off unless the user forces them.
+     */
+    readonly imagesRequireOverride?: boolean;
+    /** Platforms where the multiplexer breaks OSC 11 passthrough, so host appearance is used instead. */
+    readonly backgroundQueryBrokenOn?: readonly NodeJS.Platform[];
+    /** Present when OSC 11 replies come from a cache an explicit refresh must update first. */
+    readonly backgroundColorCache?: TerminalMultiplexerBackgroundColorCache;
+    /** Expands REP into identical styled cells, so destructive replays REP-encode their padding. */
+    readonly expandsRepPadding?: boolean;
+    /** Expires a synchronized update after a deadline, so large rebuild replays renew DEC 2026 as they stream. */
+    readonly expiresSynchronizedOutput?: boolean;
+    /**
+     * Restoring the alternate buffer schedules a redraw that ends a synchronized
+     * update early, so a synchronized resize rebuild stays on the main buffer.
+     */
+    readonly altRestoreEndsSynchronizedOutput?: boolean;
+    /**
+     * May grow its grid before SIGWINCH reaches the app, so a rebuild-mode grow
+     * whose full viewport no longer reaches the bottom replays history.
+     */
+    readonly growsBeforeSigwinch?: boolean;
+}

package/dist/types/multiplexers/wmux.d.ts

@@ -0,0 +1,12 @@
+/**
+ * wmux is a Windows multiplexer (Electron + xterm.js) modeled on cmux/herdr that
+ * repaints its pane in place. WMUX_CLI / WMUX_PIPE are CLI path overrides and can
+ * be set outside a wmux terminal.
+ */
+export declare const wmuxMultiplexer: {
+    readonly id: "wmux";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["WMUX", "WMUX_SURFACE_ID"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+};

package/dist/types/multiplexers/zellij.d.ts

@@ -0,0 +1,12 @@
+export declare const zellijMultiplexer: {
+    readonly id: "zellij";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["ZELLIJ"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "inBand";
+        readonly send: ({ sequence, write }: import("./types.js").TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly backgroundQueryBrokenOn: readonly ["darwin"];
+};

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

@@ -1,8 +1,9 @@
 /**
  * Reference document applier: applies TSP frames to a node tree the way the
- * spec says the terminal does (§5.1). Ops are validated and applied one by
- * one; a rejected op is reported and skipped without affecting the rest of
- * the frame. `settle` is recorded as a hint and never restricts later ops.
+ * spec says the terminal does (Tern SDK, `protocol/documents.md`, frame ops).
+ * Ops are validated and applied one by one; a rejected op is reported and
+ * skipped without affecting the rest of the frame. `settle` is recorded as a
+ * hint and never restricts later ops.
  *
  * Used by tests, the debug server's `doc` op, and the TSP test harness.
  */

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

@@ -48,8 +48,9 @@ export interface NativeBackendOptions {
 /**
  * The reply a v1 terminal is assumed to give before its real `hello` arrives
  * (the `TERM_PROGRAM=tern` optimistic start): the whole vocabulary, the
- * default APC limit and credits, the terminal's width, the appearance zeta
- * already detected, and full motion.
+ * default APC limit and credits, the terminal's width, the appearance omp
+ * already detected, full motion, and `blobs`, so a resumed session's images
+ * are asked about rather than resent before the reply comes.
  */
 export declare function assumedTspHello(terminal: Terminal): TspHello;
 export declare class NativeBackend {
@@ -83,8 +84,8 @@ export declare class NativeBackend {
      * The terminal's real `hello` reply after an optimistic start: adopt its
      * APC limit, credits, cell size, kinds, appearance and motion preference.
      * A width the terminal already reported in a `resize` event wins over the
-     * reply's. A different vocabulary or motion preference re-describes every
-     * component, so kinds the terminal lacks fall back.
+     * reply's. A different vocabulary, motion preference or clock re-describes
+     * every component, so kinds the terminal lacks fall back.
      */
     confirm(hello: TspHello): void;
     /** SIGWINCH: refresh the width used for `rows` fallback until the terminal reports one. */

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

@@ -2,8 +2,10 @@
  * Content-addressed binary blobs (images) for `image` nodes.
  *
  * `describe()` registers the bytes and puts the returned id in `image.p.blob`;
- * the native backend uploads each referenced blob once per surface with verb
- * `b` before the frame that first references it.
+ * the native backend delivers each referenced blob once per terminal
+ * connection (asking the terminal first which it holds, or through its blob
+ * cache), else uploads it with verb `b` before the frame that first
+ * references it.
  */
 import type { TspProps } from "@linxiraos/pi-wire";
 import type { NativeNode } from "./node.js";
@@ -12,10 +14,12 @@ export interface NativeBlob {
     readonly mime: string;
     readonly bytes: Uint8Array;
 }
-/** Register `bytes` and return their content address (sha256 hex) for `image.p.blob`. */
+/** Register bytes for process-lifetime, id-only use. Prefer {@link nativeImageNode} for owned images. */
 export declare function registerNativeBlob(bytes: Uint8Array, mime: string): string;
 /** A registered blob by id. */
 export declare function getNativeBlob(id: string): NativeBlob | undefined;
+/** An image whose props own its bytes, including while hidden, unmounted, or awaiting upload. */
+export declare function nativeImageNode(bytes: Uint8Array, mime: string, p?: Omit<TspProps<"image">, "blob" | "builtin">, key?: string): NativeNode;
 /**
  * An `image` node for a base64 payload: the bytes are registered as a blob and
  * the pixel size probed from the header. Decoding and hashing cost real time,

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

@@ -15,19 +15,21 @@ export type TspIncoming = {
 };
 /** Message parameters (`k=v`, ASCII, never containing `;`). */
 export type TspParams = Readonly<Record<string, string | number>>;
-/** Split `body` into pieces of at most `limit` UTF-8 bytes, never inside a code point. */
-export declare function splitUtf8(body: string, limit: number): string[];
 /**
- * Encode one logical message, chunked when `body` exceeds `limit` UTF-8 bytes.
- * Returns the complete byte string to write (all chunks, in order).
+ * Encode one logical message, chunked when `body` exceeds `limit` UTF-8 bytes:
+ * the first chunk carries `params`, every chunk `c=<id>` and all but the last
+ * `m=1`. Returns the complete byte string to write (all chunks, in order).
  */
 export declare function encodeTspMessage(verb: TspVerb, body: string, params?: TspParams, limit?: number): string;
 /** Encode a JSON message body. */
 export declare function encodeTspJson(verb: TspVerb, value: unknown, params?: TspParams, limit?: number): string;
 /**
  * The `hello` query; callers follow it with a DA1 sentinel. `features: ["edit"]`
- * tells the terminal that zeta applies its `edit` events (TSP §8.5), so it may keep a
- * native selection in zeta's editors; without it, every key stays zeta's.
+#1:  * tells the terminal that zeta applies its `edit` events (Tern SDK,
+ * `protocol/input.md`), so it may keep a native selection in zeta's editors;
+ * without it, every key stays zeta's. `"undo"` says zeta applies `undo` events,
+ * so the terminal may turn ⌃Z in a field into one.
+ * `"send"` accepts an explicit prompt for a live composer without simulating keys.
  */
 export declare function encodeTspHelloQuery(version?: string): string;
 /** One decoded APC message: verb, parameters and raw body. */

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

@@ -11,7 +11,8 @@
  * `rows` fallback node rendered through `render(cx.cols)`.
  *
  * See `packages/wire/src/tsp.ts` for the wire vocabulary and
- * `crates/tern/SURFACE_PROTOCOL.md` (Stencil repository) for the spec.
+ * the Tern SDK's Surface Protocol reference (`docs/sdk/src/protocol` in the
+ * Stencil repository, https://docs.stencil.so/tern/protocol/) for the spec.
  */
 import type { TspEvent, TspKind, TspProps, TspScrollBy, TspSpan } from "@linxiraos/pi-wire";
 import type { Component } from "../tui.js";
@@ -28,10 +29,12 @@ export type NativeNode = {
          */
         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.
+         * Scroll the node into view, placed like the `reveal` op. A placement
+         * reveals it when it is added: key a node by what it points at to
+         * reveal it again on a move. A {@link NativeReveal} reveals it whenever
+         * its `n` differs from the previous description of the same node.
          */
-        readonly reveal?: "start" | "end" | "nearest";
+        readonly reveal?: NativeRevealAt | NativeReveal;
         /**
          * Keyboard scrolling forwarded to the terminal (PgUp/PgDn/End reach the
          * program): moves the scroller at or above the node by `by` whenever
@@ -42,6 +45,17 @@ export type NativeNode = {
         readonly scroll?: NativeScroll;
     };
 }[TspKind];
+/** Where a revealed node lands in its scroller. */
+export type NativeRevealAt = "start" | "end" | "nearest";
+/**
+ * A repeatable {@link NativeNode.reveal}: bump `n` to bring an existing node
+ * into view again (a Contents entry jumping to its section). A freshly added
+ * node is not revealed.
+ */
+export interface NativeReveal {
+    readonly at: NativeRevealAt;
+    readonly n: number;
+}
 /** A {@link NativeNode.scroll} request. */
 export interface NativeScroll {
     readonly by: TspScrollBy;
@@ -57,6 +71,12 @@ export interface DescribeContext {
     readonly reduceMotion: boolean;
     /** The terminal's appearance is dark. */
     readonly dark: boolean;
+    /**
+     * The user's system reads a 12-hour clock (`false`: 24-hour); `undefined`
+     * when the terminal doesn't say. Pass it as `hour12` when formatting times:
+     * the process's own default locale may not know.
+     */
+    readonly hour12?: boolean;
     /** Whether the terminal renders `kind` natively (else describe something simpler or let it fall back). */
     supports(kind: TspKind): boolean;
     /**
@@ -117,7 +137,18 @@ export type NativeUiEvent = {
  | ({
     readonly type: "edit";
     readonly key: string;
-} & NativeTextEdit);
+} & NativeTextEdit)
+/** Undo the last change to an `editor`/`input` node's text (the terminal's ⌃Z); a no-op with no history. */
+ | {
+    readonly type: "undo";
+    readonly key: string;
+}
+/** Submit an explicit prompt through the composer's normal path, preserving the previous draft for recall. */
+ | {
+    readonly type: "send";
+    readonly key: string;
+    readonly text: string;
+};
 /**
  * A primitive edit the terminal made over its own text selection (cut,
  * typing, Backspace/Delete or paste over it, or collapsing it). Offsets are

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

@@ -7,7 +7,7 @@
  * component's root is a `card` whose `head` carries the title.
  */
 import type { TspProps, TspSpan, TspText } from "@linxiraos/pi-wire";
-import type { KeyName } from "../key-hint-format.js";
+import { type KeyName } from "../key-hint-format.js";
 import { type Keybinding } from "../keybindings.js";
 import type { NativeChild, NativeNode } from "./node.js";
 /** One footer hint: the keys that trigger it and what it does. */
@@ -44,10 +44,10 @@ export interface ActionButtonOptions {
     /** Sibling identity key (defaults to the action id); `leafKey(event.key)` reports it back. */
     readonly key?: string;
     /** Key id of the keyboard path the button mirrors, drawn as a keycap inside it (`"r"`, `"ctrl+g"`). */
-    readonly keys?: string;
+    readonly keys?: KeyName;
     /** `accent` = the view's hero action, `error` = destructive. */
     readonly tone?: "accent" | "error";
-    /** Tooltip; defaults to the label plus the keycap (`"Refresh  r"`). */
+    /** Tooltip; defaults to the label plus the keycap (`"Refresh  r"`, see {@link formatTooltipKey}). */
     readonly title?: string;
     /** Target of an `open` action (URL or `file://` path). */
     readonly href?: string;
@@ -58,6 +58,11 @@ export interface ActionButtonOptions {
  * which the component routes to the same code path as the key.
  */
 export declare function actionButton(label: string, act: string, options?: ActionButtonOptions): NativeNode;
+/**
+ * A bare `esc` keycap button for a view's top-right corner: a click sends
+ * `act` (default `close`), which the component routes to its Esc path.
+ */
+export declare function escCloseButton(act?: string, key?: string): NativeNode;
 /** A row of {@link actionButton}s (role `zeta.actions`); `null` entries become the spacer that end-aligns what follows. */
 export declare function actionBar(buttons: readonly (NativeNode | null)[], key?: string): NativeNode;
 /** Spans of an annotation callout: a dim `label:` then the note. */

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

@@ -1,8 +1,9 @@
 /**
  * Settling: the frame provider marks finalized transcript blocks so the
- * native reconciler stops keeping their description (spec §12 "Settling and
- * program memory"). A settled block stays editable: a later change is sent as
- * targeted ops by id, followed by a fresh `settle` hint.
+ * native reconciler stops keeping their description (Tern SDK,
+ * `protocol/operations.md`, "Settling"). A settled block stays editable: a
+ * later change is sent as targeted ops by id, followed by a fresh `settle`
+ * hint.
  */
 import type { Component } from "../tui.js";
 /** Mark `component` (and everything it describes) as finalized. Idempotent; a no-op outside a TSP terminal. */

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

@@ -15,11 +15,12 @@ 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. */
+/** Live session used to cache a row's direct assistant usage, including with observer progress. */
 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}).
+ * Preserve progress/history for non-cost metrics, overlaying cumulative direct-session cost.
+ * Persisted `history.metrics.cost` is a leaf-scoped snapshot, so it never overrides live
+ * progress; only the cumulative direct-cost sources do.
  */
 export declare function hubRowMetrics<TRecord extends AgentRecordLike>(ref: TRecord, observed: ObservableSession | undefined, sessionMetrics: WeakMap<object, {
     metrics: AgentMetrics | undefined;
@@ -37,6 +38,6 @@ export declare function aggregateMetrics<TRecord extends AgentRecordLike>(args:
     metrics: AggregateMetrics;
     hasFallbackLiveSessions: boolean;
 };
-/** Parent-before-child projection preserving the roster's stable sibling order. */
-export declare function projectAgentTree<TRecord extends AgentRecordLike>(refs: readonly TRecord[]): AgentTreeProjection<TRecord>;
+/** Parent-before-child projection preserving initial subtree rank and prepending new siblings. */
+export declare function projectAgentTree<TRecord extends AgentRecordLike>(refs: readonly TRecord[], rosterRank: ReadonlyMap<TRecord, number> | undefined): AgentTreeProjection<TRecord>;
 export {};

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

@@ -28,6 +28,13 @@ export interface AgentHubSession {
             messages: AgentMessage[];
         };
     };
+    /** Existing session ledger includes off-transcript model usage and nested-task attribution. */
+    readonly sessionManager?: {
+        getUsageStatistics(): {
+            cost: number;
+            subagentCost: number;
+        };
+    };
     getSessionStats(): {
         tokens: {
             input: number;
@@ -64,6 +71,8 @@ export interface AgentRecordLike {
         resolvedModel?: string;
         resolvedModelIsFallback?: boolean;
         metrics?: AgentMetricsSummary;
+        /** Cumulative own-session assistant and model_usage cost, excluding nested task results. */
+        directCost?: number;
         readOnly?: boolean;
         outputPath?: string;
         patchPath?: string;

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

@@ -73,6 +73,7 @@ export interface AgentHubDeps<TRecord extends AgentRecordLike = AgentRecordLike>
     /** Mirrors the main transcript's thinking-block visibility. */
     hideThinkingBlock?: () => boolean;
     proseOnlyThinking?: () => boolean;
+    expandThinkingBlocks?: () => boolean;
     /** Keys toggling tool output expansion (app.tools.expand). */
     expandKeys?: KeyId[];
     /** Focus the main view on this agent's live session (ctx.focusAgentSession). When absent (collab guest, tests), Enter opens the in-hub chat view instead. */
@@ -113,6 +114,8 @@ export declare class AgentHubOverlayComponent<TRecord extends AgentRecordLike =
      * was raised by that gesture.
      */
     armCloseTap(): void;
+    /** Show `section`, as a slash-command deep link into an already-open hub does. */
+    showSection(section: AgentHubSection): void;
     /**
      * Open the fullscreen transcript viewer for an agent id (public for table Enter
      * and tests). Mounts {@link AgentTranscriptViewer} as a `fullscreen` overlay so it

package/dist/types/overlays/agent-transcript-viewer.d.ts

@@ -23,7 +23,7 @@ import type { AgentHubRegistry } from "./agent-hub-types.js";
 import type { SessionMessageEntryLike } from "../chat/transcript-entry.js";
 import type { SessionObserverRegistry } from "./session-observer-registry.js";
 import type { AgentHubRemote } from "./agent-hub.js";
-import type { DescribeContext, NativeNode } from "../native/node.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /** Parsed message and model metadata relevant to a transcript viewer. */
 export type AgentTranscriptEntry = SessionMessageEntryLike | {
     type: "model_change";
@@ -31,7 +31,14 @@ export type AgentTranscriptEntry = SessionMessageEntryLike | {
 };
 /** Local filesystem and session parsing capabilities supplied by the host. */
 export interface AgentTranscriptSource {
-    fs: Pick<typeof fs, "openSync" | "closeSync" | "readSync" | "readFileSync" | "statSync">;
+    /**
+     * Sync primitives drive the first paint and the incremental tail. When the
+     * host also supplies `promises.readFile` (e.g. passes `node:fs` itself), full
+     * reloads after rotation/rewrite read the file off the UI thread.
+     */
+    fs: Pick<typeof fs, "openSync" | "closeSync" | "readSync" | "readFileSync" | "statSync"> & {
+        promises?: Pick<typeof fs.promises, "readFile">;
+    };
     parseEntries(text: string): AgentTranscriptEntry[];
 }
 export interface AgentTranscriptViewerDeps {
@@ -54,6 +61,7 @@ export interface AgentTranscriptViewerDeps {
     cwd: string;
     hideThinkingBlock?: () => boolean;
     proseOnlyThinking?: () => boolean;
+    expandThinkingBlocks?: () => boolean;
     expandKeys: KeyId[];
     /** Keys that toggle the whole hub closed (app.agents.hub + app.session.observe). */
     hubKeys: KeyId[];
@@ -69,6 +77,8 @@ export declare class AgentTranscriptViewer implements Component {
     dispose(): void;
     handleInput(data: string): void;
     render(width: number): readonly string[];
+    /** The top-right `esc` runs Esc. */
+    handleNativeEvent(event: NativeUiEvent): void;
     /**
      * Header, transcript body (the builder's container, which describes its own
      * blocks), notice, message editor, stats and key hints. Scrolling is the

package/dist/types/overlays/agents-hub.d.ts

@@ -60,6 +60,15 @@ export interface AgentsHubDeps {
 export interface AgentsHubCallbacks {
     onCancel: () => void;
 }
+/**
+ * Parse model output into a {@link GeneratedAgentSpec}. Accepts a bare JSON object
+ * (tried first) or one wrapped in a code fence. Returns the spec with trimmed fields.
+ * Throws if the output is not valid JSON or not an object, if `identifier`, `whenToUse`
+ * or `systemPrompt` is missing or not a string, if the identifier is not lowercase
+ * kebab-case with 2+ words, if `whenToUse` does not start with "Use this agent when",
+ * or if `systemPrompt` is empty.
+ */
+export declare function parseGeneratedAgentSpec(raw: string): GeneratedAgentSpec;
 /**
  * The fullscreen agents hub component. Hosted via
  * `ui.showOverlay(..., { fullscreen: true })`; the host must call