@cjhyy/code-shell 0.1.7 → 0.3.0

package/dist/tool-system/builtin/agent-transcript-translator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Translate child Engine StreamEvents into ChatEntry-shaped objects so the
+ * AgentDock detail view (which reuses App.renderEntry) can show a sub-agent's
+ * conversation in the same visual language as the main feed.
+ *
+ * The transcript is the canonical record for one background sub-agent. State
+ * (current thinking entry, currently-streaming assistant_text, in-flight
+ * tool_start map) lives in a per-agent translator. Each translator instance
+ * appends ChatEntry-shaped objects via `append` and mutates them via `update`,
+ * mirroring how App.tsx's handleStreamEvent talks to chatStore but isolated to
+ * a single agent's transcript.
+ *
+ * The output shapes intentionally match `src/ui/store.ts#ChatEntryData` so the
+ * existing renderEntry switch picks them up without code changes.
+ */
+import type { StreamEvent } from "../../types.js";
+/**
+ * Create a transcript translator scoped to one background sub-agent. Returned
+ * function is a StreamCallback drop-in: feed it the child Engine's events and
+ * it maintains the agent's transcript in `asyncAgentRegistry`.
+ */
+export declare function createTranscriptTranslator(agentId: string): (event: StreamEvent) => void;

package/dist/tool-system/builtin/skill-prompt.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Skill listing renderer for the system prompt. Mirrors Claude Code's split
+ * between scan/data layer (skills/scanner.ts) and render layer (this file),
+ * matching tools/SkillTool/prompt.ts in CC.
+ */
+import type { SkillDefinition } from "../../skills/scanner.js";
+export declare function buildSkillListing(skills: SkillDefinition[]): string;

package/dist/tool-system/builtin/skill.d.ts

@@ -1,5 +1,7 @@
 /**
- * SkillTool — invoke custom skills/plugins by name.
+ * SkillTool — load a skill's SKILL.md body and return it as the tool result.
+ * The scanner is the single source of truth; this tool never reads the disk
+ * directly. Matches Claude Code's tools/SkillTool/SkillTool.ts pattern.
  */
 import type { ToolDefinition } from "../../types.js";
 export declare const skillToolDef: ToolDefinition;

package/dist/tool-system/context.d.ts

@@ -17,6 +17,7 @@ import type { ModelPool } from "../llm/model-pool.js";
 import type { ToolRegistry } from "./registry.js";
 import type { AgentPresetName } from "../preset/index.js";
 import type { SandboxBackend } from "./sandbox/index.js";
+import type { HookRegistry } from "../hooks/registry.js";
 /** One choice in a multiple-choice AskUserQuestion. */
 export interface AskUserChoice {
     label: string;
@@ -55,6 +56,14 @@ export interface SubAgentSpawnRequest {
     prompt: string;
     maxTurns: number;
     signal: AbortSignal;
+    /**
+     * Per-call override for where the spawned child Engine's stream events go.
+     * Defaults to `spawner.parentStream` (the parent UI). Background sub-agents
+     * pass a transcriptSink here so per-event detail is captured in the agent's
+     * transcript instead of leaking into the main feed; the main feed still
+     * gets `agent_start` / `agent_end` markers via `spawner.parentStream`.
+     */
+    streamOverride?: StreamCallback;
 }
 export interface SubAgentSpawner {
     /** Run a sub-agent synchronously and return its text output. */
@@ -87,6 +96,13 @@ export interface ToolContext {
     askUser?: AskUserFn;
     /** Sub-agent spawner (Agent tool). Undefined → Agent tool unavailable. */
     subAgentSpawner?: SubAgentSpawner;
+    /**
+     * True when this Engine is itself a sub-agent. Set from EngineConfig.
+     * The Agent tool refuses to spawn when this is true — runtime check
+     * layered on top of the tool-list strip in Engine.spawn so a registry
+     * regression can't leak nested spawns.
+     */
+    isSubAgent?: boolean;
     /**
      * Active sandbox backend for the Bash tool. Undefined falls back to "off"
      * (plain spawn). Headless runs default to an OS-level sandbox; the REPL
@@ -95,6 +111,13 @@ export interface ToolContext {
     sandbox?: SandboxBackend;
     /** Optional cancellation signal for the whole turn. */
     signal?: AbortSignal;
+    /**
+     * Engine-owned HookRegistry. Tools that emit lifecycle hooks
+     * (notification, file_changed for non-Write/Edit paths, custom
+     * tool-defined events) use this. Undefined for legacy callers /
+     * standalone tests; tools must tolerate absence.
+     */
+    hooks?: HookRegistry;
 }
 /**
  * Per-Engine container that produces a fresh ToolContext on demand.

package/dist/tool-system/executor.d.ts

@@ -8,6 +8,7 @@ import { PermissionClassifier } from "./permission.js";
 import { logger as rootLogger } from "../logging/logger.js";
 import type { ToolContext } from "./context.js";
 import type { InvestigationGuard } from "./investigation-guard.js";
+import type { TaskGuard } from "./task-guard.js";
 type Logger = typeof rootLogger;
 export declare class ToolExecutor {
     private readonly registry;
@@ -23,9 +24,12 @@ export declare class ToolExecutor {
      */
     private log;
     private guard?;
+    private taskGuard?;
     constructor(registry: ToolRegistry, permission: PermissionClassifier, hooks: HookRegistry);
     setInvestigationGuard(guard: InvestigationGuard | undefined): void;
     getInvestigationGuard(): InvestigationGuard | undefined;
+    setTaskGuard(guard: TaskGuard | undefined): void;
+    getTaskGuard(): TaskGuard | undefined;
     /** Set the abort signal for cascading cancellation. */
     setSignal(signal?: AbortSignal): void;
     /** Set the per-Engine ToolContext (askUser, llmConfig, modelPool, etc.). */
@@ -34,7 +38,7 @@ export declare class ToolExecutor {
     setLogger(log: Logger): void;
     /** Check if a tool is safe for concurrent execution (read-only). */
     isConcurrencySafe(toolName: string): boolean;
-    executeSingle(call: ToolCall): Promise<ToolResult>;
+    executeSingle(callIn: ToolCall): Promise<ToolResult>;
     private isReadOnlyBashCommand;
     executeAll(calls: ToolCall[]): Promise<ToolResult[]>;
     /**

package/dist/tool-system/permission.d.ts

@@ -88,7 +88,7 @@ export declare class PermissionClassifier {
     reconfigure(mode: PermissionMode, approvalBackend: ApprovalBackend, rules?: PermissionRule[]): void;
     getMode(): PermissionMode;
     classify(toolName: string, args: Record<string, unknown>): PermissionDecision;
-    handleAsk(toolName: string, args: Record<string, unknown>): Promise<boolean>;
+    handleAsk(toolName: string, args: Record<string, unknown>, reason?: string): Promise<boolean>;
     /** Get denial warning message if the model keeps getting denied. */
     getDenialWarning(toolName: string): string | undefined;
     private matchesRule;

package/dist/tool-system/sandbox/index.d.ts

@@ -38,6 +38,13 @@ export interface SandboxBackend {
     }): {
         file: string;
         args: string[];
+        /**
+         * Optional callback the Bash tool calls after the child process exits.
+         * Backends that allocate per-command resources (e.g. seatbelt writes a
+         * profile file to a fresh temp dir) hang their cleanup here so a long
+         * session doesn't leak hundreds of temp dirs in /tmp.
+         */
+        cleanup?: () => void;
     };
     /**
      * If `stderr` looks like a sandbox denial, return a short hint string that

package/dist/tool-system/task-guard.d.ts

@@ -0,0 +1,30 @@
+/**
+ * TaskGuard — nudges the model to update stale in_progress tasks.
+ *
+ * Background: TaskCreate is sticky in the model's working memory only for the
+ * first few turns. After enough intervening tool_results (Read/Edit/Bash) the
+ * "I have an open task" signal gets diluted and the model finishes its work
+ * without ever calling TaskUpdate(status="completed") — so the UI spinner runs
+ * forever on a task that the model considers done.
+ *
+ * Same shape as InvestigationGuard.turnEnded: turn-loop polls at the end of
+ * each turn; if anything is in_progress and hasn't been touched in N turns,
+ * we emit a <system-reminder> that lands at the top of the next turn.
+ *
+ * Re-nag policy: don't fire more than once per (task, threshold) pair. A task
+ * stale at turn 5 fires once; if the model still ignores it, we wait for it
+ * to cross the next threshold (8, 11, …) before firing again. This keeps the
+ * reminder from drowning out everything else when the model is genuinely
+ * stuck on something unrelated.
+ */
+import type { Task } from "./builtin/task.js";
+export declare class TaskGuard {
+    private taskListSource;
+    /** Last turn we nagged about a given task id. */
+    private lastNagTurn;
+    /** Turn the task was first observed in_progress (model-time, not wall-clock). */
+    private inProgressSince;
+    constructor(taskListSource: () => Task[]);
+    turnEnded(turnNumber: number): string | undefined;
+    reset(): void;
+}

package/dist/types.d.ts

@@ -217,11 +217,14 @@ export type StreamEvent = {
 } | {
     type: "agent_start";
     agentId: string;
+    name?: string;
     description: string;
 } | {
     type: "agent_end";
     agentId: string;
+    name?: string;
     description: string;
+    text?: string;
     error?: string;
 } | {
     type: "tool_summary";
@@ -249,6 +252,19 @@ export interface LLMConfig {
     timeout?: number;
     retryMaxAttempts?: number;
     enableStreaming?: boolean;
+    /**
+     * Default thinking-mode for DeepSeek V4. Per-call `options.thinking`
+     * (e.g. summarize sub-calls) overrides this. Ignored on other providers.
+     */
+    thinking?: "enabled" | "disabled";
+    /**
+     * The provider's `kind` (deepseek/openai/zai/openrouter/...). Used by
+     * the capability layer to look up per-(kind, model) request-shape rules
+     * (token-limit field, rejected sampling params, thinking shape, etc.).
+     * Distinct from `provider` above, which is the protocol family
+     * ("openai" or "anthropic") that picks which client class to use.
+     */
+    providerKind?: string;
 }
 export interface LLMResponse {
     text: string;
@@ -275,6 +291,32 @@ export interface MCPServerConfig {
     transport?: MCPTransport;
     headers?: Record<string, string>;
 }
+/**
+ * Shell-hook configuration entry from settings.json. Each entry binds
+ * a hook event to a shell command. The command runs as a child process
+ * on every emit (filtered by `matcher` when present), receives ctx
+ * JSON on stdin, and returns a HookResult JSON on stdout. See
+ * src/hooks/shell-runner.ts for the protocol spec.
+ */
+export interface SettingsHookConfig {
+    event: string;
+    command: string;
+    /**
+     * Optional regex (matched with new RegExp(matcher).test(toolName)) to
+     * filter which tools fire this hook. Currently honored for
+     * pre_tool_use / post_tool_use / on_tool_start / on_tool_end /
+     * on_permission_check / file_changed. Ignored for events without a
+     * meaningful toolName (session/turn/prompt/notification/compact).
+     */
+    matcher?: string;
+    /** Per-hook timeout in milliseconds. Defaults to 60_000. */
+    timeout_ms?: number;
+    /**
+     * Optional working directory for the spawned command. Defaults to
+     * Engine.cwd. Useful for hooks that need to run in a sibling repo.
+     */
+    cwd?: string;
+}
 export interface Settings {
     model: {
         provider: string;
@@ -305,4 +347,10 @@ export interface Settings {
     output: {
         format: "text" | "json" | "jsonl" | "stream-json";
     };
+    /**
+     * Optional shell-hook entries. Engine reads on construction and
+     * registers a wrapper handler per entry that spawns the command and
+     * parses the HookResult. Empty / missing = no shell hooks.
+     */
+    hooks?: SettingsHookConfig[];
 }

package/dist/ui/components/AgentBlock.d.ts

@@ -11,17 +11,20 @@
  */
 import React from "react";
 interface AgentBlockStartProps {
+    name?: string;
     description: string;
     running?: boolean;
     isLast?: boolean;
 }
-export declare function AgentBlockStart({ description, running, isLast }: AgentBlockStartProps): import("react/jsx-runtime").JSX.Element;
+export declare function AgentBlockStart({ name, description, running, isLast }: AgentBlockStartProps): import("react/jsx-runtime").JSX.Element;
 interface AgentBlockEndProps {
+    name?: string;
     description: string;
+    text?: string;
     error?: string;
     isLast?: boolean;
 }
-export declare function AgentBlockEnd({ description, error, isLast }: AgentBlockEndProps): import("react/jsx-runtime").JSX.Element;
+export declare function AgentBlockEnd({ name, description, text, error, isLast }: AgentBlockEndProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Tree line prefix for nested content under an agent.
  */

package/dist/ui/components/AgentDock.d.ts

@@ -0,0 +1,36 @@
+import React from "react";
+import { type AsyncAgentEntry } from "../../tool-system/builtin/agent-registry.js";
+export declare const MAX_VISIBLE = 5;
+export type DockViewMode = {
+    kind: "main";
+} | {
+    kind: "agent";
+    agentId: string;
+};
+export interface AgentDockProps {
+    viewMode: DockViewMode;
+    /** null = dock is not the keyboard target; integer = focused row index. */
+    focusedIndex: number | null;
+}
+/**
+ * AgentDock — vertical list of running and recently-finished sub-agents,
+ * pinned at the very bottom of the UI. Updates elapsed text once per
+ * second; redraws are local to this subtree (no app-wide re-render).
+ *
+ * See docs/superpowers/specs/2026-05-18-subagent-dock-revisions-design.md.
+ */
+export declare function AgentDock({ viewMode, focusedIndex, }: AgentDockProps): React.ReactElement | null;
+/**
+ * Filter the registry snapshot down to rows the dock should show:
+ * running agents + recently-finished agents still inside the fade window.
+ * Successful completions are dropped immediately — their final text already
+ * surfaced via agent_end in the main feed, so the dock row is redundant.
+ * Failures and cancellations linger so the user can investigate.
+ *
+ * Exported so App.tsx's keyboard handler shares the same predicate.
+ */
+export declare function getVisibleAgents(all: AsyncAgentEntry[], now: number): AsyncAgentEntry[];
+/**
+ * Format an elapsed-millisecond duration as "23s" / "4m 23s" / "1h 4m 23s".
+ */
+export declare function formatElapsed(ms: number): string;

package/dist/ui/components/CommandInput.d.ts

@@ -1,6 +1,10 @@
 interface CommandDef {
     name: string;
     description: string;
+    /** Optional usage string like "/fullscreen [on|off|toggle]" — the
+     *  bracketed portion is rendered dim after the command name once the
+     *  user has finished typing it. */
+    usage?: string;
 }
 interface CommandInputProps {
     value: string;
@@ -8,6 +12,13 @@ interface CommandInputProps {
     onSubmit: (value: string) => void;
     commands: CommandDef[];
     placeholder?: string;
+    /** Fired when ↓ is pressed and input is empty and history is exhausted.
+     *  Used by App.tsx to move keyboard focus into the AgentDock.  */
+    onArrowOut?: (direction: "down") => void;
+    /** When true, skip ALL key handling. Used while another part of the UI
+     *  (e.g. the AgentDock) owns the keyboard. The text input still renders;
+     *  only the useInput body short-circuits. */
+    disabled?: boolean;
 }
-export declare function CommandInput({ value, onChange, onSubmit, commands, placeholder, }: CommandInputProps): import("react/jsx-runtime").JSX.Element;
+export declare function CommandInput({ value, onChange, onSubmit, commands, placeholder, onArrowOut, disabled, }: CommandInputProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/ui/components/MessageRow.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MessageRow — memo boundary around a single chat entry's rendered output.
+ *
+ * Why this exists: stream events fire dozens of times per second. Without
+ * a memo boundary, every entry's renderer (markdown lexing, Yoga layout,
+ * syntax-highlight token cache) re-runs on every frame, defeating ink's
+ * blit fast-path. The hand-written comparator below mirrors Claude Code
+ * 2.1.88's areMessageRowPropsEqual: bail only when we are CERTAIN the
+ * entry didn't change.
+ *
+ * Why `render` is excluded from the comparator (intentional, see CC's
+ * VirtualItem note): when entry/columns/isStreaming all match, React.memo
+ * returns the PREVIOUS rendered ReactNode — it does NOT invoke render
+ * again with the new closure, so a stale-closure-on-bail scenario is
+ * impossible. Including `render` in the comparator would defeat memo
+ * entirely (render is fresh on every parent render).
+ */
+import React, { type ReactNode } from "react";
+import type { ChatEntry } from "../store.js";
+export interface MessageRowProps {
+    entry: ChatEntry;
+    /** Terminal columns — affects text wrap inside the renderer. */
+    columns: number;
+    /**
+     * True iff this entry is the one currently receiving stream deltas.
+     * Streaming rows never memo-bail (their text grows mid-frame).
+     */
+    isStreaming: boolean;
+    /**
+     * True iff this entry is the transcript-mode cursor target. State
+     * external to the entry that affects rendering (cursor outline) must
+     * be a prop so the comparator can invalidate when it flips. CC handles
+     * cursor/hover/expanded the same way on its VirtualItem.
+     */
+    isSelected: boolean;
+    /**
+     * True when long entries should render expanded (transcript mode).
+     * Flipping this re-renders every row — low-frequency event, acceptable.
+     */
+    expanded: boolean;
+    /**
+     * Called with the entry when we actually need to render. Excluded
+     * from the memo comparator on purpose (see file header).
+     */
+    render: (entry: ChatEntry) => ReactNode;
+}
+declare function MessageRowImpl({ entry, render }: MessageRowProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Returns true when the row can safely skip re-render. False on any
+ * uncertainty — we fail safe by re-rendering.
+ */
+export declare function areMessageRowPropsEqual(prev: MessageRowProps, next: MessageRowProps): boolean;
+export declare const MessageRow: React.MemoExoticComponent<typeof MessageRowImpl>;
+export {};

package/dist/ui/components/SpinnerWithVerb.d.ts

@@ -5,9 +5,15 @@ import { type MutableRefObject } from "react";
 export type SpinnerMode = "responding" | "tool-use" | "thinking";
 interface SpinnerWithVerbProps {
     mode: SpinnerMode;
+    /**
+     * Per-turn streamed token count — used purely as a "still alive" signal so
+     * the user sees activity. NOT a measure of context size; that's in the
+     * StatusLine ctx bar.
+     */
     streamingTokensRef?: MutableRefObject<number>;
     runStartRef?: MutableRefObject<number>;
     thinkingContent?: string;
 }
-export declare function SpinnerWithVerb({ mode, streamingTokensRef, runStartRef, thinkingContent, }: SpinnerWithVerbProps): import("react/jsx-runtime").JSX.Element;
+declare function SpinnerWithVerbImpl({ mode, streamingTokensRef, runStartRef, thinkingContent, }: SpinnerWithVerbProps): import("react/jsx-runtime").JSX.Element;
+export declare const SpinnerWithVerb: import("react").MemoExoticComponent<typeof SpinnerWithVerbImpl>;
 export {};

package/dist/ui/components/StatusLine.d.ts

@@ -12,7 +12,11 @@ interface StatusLineProps {
     tokens: number;
     cost: number;
     sessionId?: string;
-    /** Last known prompt tokens from completed turn. Live streaming is added on top. */
+    /**
+     * Authoritative live context size. The engine emits `usage_update` at every
+     * message-array mutation (post-tool-result, post-compact, post-LLM), so this
+     * tracks the real prompt token count without UI-side accumulation.
+     */
     baseContextTokens?: number;
     maxContextTokens?: number;
     gitBranch?: string;

package/dist/ui/components/TextInput.d.ts

@@ -4,6 +4,14 @@ interface TextInputProps {
     onSubmit?: (value: string) => void;
     placeholder?: string;
     focus?: boolean;
+    /** Suffix rendered dim after the cursor — e.g. "on|off" arg hint for
+     *  a slash command. Not part of `value`; not editable. */
+    hint?: string;
+    /** Bumping this number snaps the cursor to value.length on the next
+     *  render. Use when the parent rewrites `value` externally (e.g. tab
+     *  completion) — the in-component cursor would otherwise stay at its
+     *  pre-rewrite offset and land in the middle of the new text. */
+    cursorResetCounter?: number;
 }
-export default function TextInput({ value, onChange, onSubmit, placeholder, focus, }: TextInputProps): import("react/jsx-runtime").JSX.Element;
+export default function TextInput({ value, onChange, onSubmit, placeholder, focus, hint, cursorResetCounter, }: TextInputProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/ui/components/VirtualMessageList.d.ts

@@ -1,24 +1,43 @@
 /**
- * VirtualMessageList — renders only visible messages for performance.
+ * VirtualMessageList — ScrollBox + viewport-windowed chat rendering.
  *
- * When message count exceeds VIRTUALIZE_THRESHOLD, only renders messages
- * within the visible viewport (plus overscan buffer). Uses height estimation
- * for off-screen items via spacer elements.
+ * Owns its own ScrollBox + useVirtualScroll. Only items in the viewport
+ * (+ overscan) are mounted as React fibers / Yoga nodes; the rest live
+ * as height-equivalent topSpacer / bottomSpacer boxes. ScrollBox handles
+ * sticky-bottom, wheel/key scroll, render-time clamping.
  *
- * For smaller conversations, renders all messages directly (no virtualization).
+ * Each rendered item is wrapped in <MessageRow> (React.memo) so historical
+ * entries skip re-render entirely on stream ticks. Cursor-outline decoration
+ * is applied OUTSIDE the memo boundary so the render closure stays cursor-
+ * agnostic.
  *
- * Also provides an unseen message divider ("── N new ──") when the user
- * scrolls away and new messages arrive.
+ * Auto-stick: when entries grow while ScrollBox is "sticky" (default + after
+ * scrollToBottom), the view follows the tail. User scrolling up breaks
+ * stickiness; clicking the "N new messages" pill should call onJumpToNew
+ * which ultimately invokes scrollToBottom (wired via the imperative handle).
  */
-import { type ReactNode } from "react";
-import type { ChatEntry } from "../store.js";
+import React, { type ReactNode } from "react";
+import { type ChatEntry } from "../store.js";
 interface VirtualMessageListProps {
     entries: ChatEntry[];
-    renderEntry: (entry: ChatEntry, key: string) => ReactNode;
+    renderEntry: (entry: ChatEntry, key: string, expanded: boolean) => ReactNode;
+    /** Terminal width — threaded into MessageRow so width changes invalidate memo. */
+    columns: number;
+    /** Id of the entry currently receiving stream deltas (null = no stream). */
+    streamingEntryId?: string | null;
+    /** Id of the entry under the transcript-mode cursor (null = no cursor). */
+    selectedEntryId?: string | null;
+    /** True when long entries should render expanded (transcript mode). */
+    expanded?: boolean;
     /** Index where "N new" divider should render (null = no divider). */
     dividerIndex?: number | null;
     /** Count of unseen messages to show in divider. */
     unseenCount?: number;
 }
-export declare function VirtualMessageList({ entries, renderEntry, dividerIndex, unseenCount, }: VirtualMessageListProps): import("react/jsx-runtime").JSX.Element;
+export interface VirtualMessageListHandle {
+    scrollToBottom: () => void;
+    scrollBy: (dy: number) => void;
+    getViewportHeight: () => number;
+}
+export declare const VirtualMessageList: React.ForwardRefExoticComponent<VirtualMessageListProps & React.RefAttributes<VirtualMessageListHandle>>;
 export {};

package/dist/ui/dev-seed.d.ts

@@ -0,0 +1 @@
+export declare function applyDevSeed(): void;

package/dist/ui/fullscreen-mode.d.ts

@@ -0,0 +1,9 @@
+export declare const TAIL_ENTRY_LIMIT = 500;
+export declare const INITIAL_FULLSCREEN_MODE: boolean;
+export interface FullscreenModeValue {
+    fullscreen: boolean;
+    setFullscreen: (next: boolean) => void;
+    toggleFullscreen: () => void;
+}
+export declare const FullscreenModeContext: import("react").Context<FullscreenModeValue>;
+export declare function useFullscreenMode(): FullscreenModeValue;

package/dist/ui/hooks/useVirtualScroll.d.ts

@@ -0,0 +1,101 @@
+import type { RefObject } from 'react';
+import type { ScrollBoxHandle } from '../../render/components/ScrollBox.js';
+import type { DOMElement } from '../../render/dom.js';
+export type VirtualScrollResult = {
+    /** [startIndex, endIndex) half-open slice of items to render. */
+    range: readonly [number, number];
+    /** Height (rows) of spacer before the first rendered item. */
+    topSpacer: number;
+    /** Height (rows) of spacer after the last rendered item. */
+    bottomSpacer: number;
+    /**
+     * Callback ref factory. Attach `measureRef(itemKey)` to each rendered
+     * item's root Box; after Yoga layout, the computed height is cached.
+     */
+    measureRef: (key: string) => (el: DOMElement | null) => void;
+    /**
+     * Attach to the topSpacer Box. Its Yoga computedTop IS listOrigin
+     * (first child of the virtualized region, so its top = cumulative
+     * height of everything rendered before the list in the ScrollBox).
+     * Drift-free: no subtraction of offsets, no dependence on item
+     * heights that change between renders (tmux resize).
+     */
+    spacerRef: RefObject<DOMElement | null>;
+    /**
+     * Cumulative y-offset of each item in list-wrapper coords (NOT scrollbox
+     * coords — logo/siblings before this list shift the origin).
+     * offsets[i] = rows above item i; offsets[n] = totalHeight.
+     * Recomputed every render — don't memo on identity.
+     */
+    offsets: ArrayLike<number>;
+    /**
+     * Read Yoga computedTop for item at index. Returns -1 if the item isn't
+     * mounted or hasn't been laid out. Item Boxes are direct Yoga children
+     * of the ScrollBox content wrapper (fragments collapse in the Ink DOM),
+     * so this is content-wrapper-relative — same coordinate space as
+     * scrollTop. Yoga layout is scroll-independent (translation happens
+     * later in renderNodeToOutput), so positions stay valid across scrolls
+     * without waiting for Ink to re-render. StickyTracker walks the mount
+     * range with this to find the viewport boundary at per-scroll-tick
+     * granularity (finer than the 40-row quantum this hook re-renders at).
+     */
+    getItemTop: (index: number) => number;
+    /**
+     * Get the mounted DOMElement for item at index, or null. For
+     * ScrollBox.scrollToElement — anchoring by element ref defers the
+     * Yoga-position read to render time (deterministic; no throttle race).
+     */
+    getItemElement: (index: number) => DOMElement | null;
+    /** Measured Yoga height. undefined = not yet measured; 0 = rendered nothing. */
+    getItemHeight: (index: number) => number | undefined;
+    /**
+     * Scroll so item `i` is in the mounted range. Sets scrollTop =
+     * offsets[i] + listOrigin. The range logic finds start from
+     * scrollTop vs offsets[] — BOTH use the same offsets value, so they
+     * agree by construction regardless of whether offsets[i] is the
+     * "true" position. Item i mounts; its screen position may be off by
+     * a few-dozen rows (overscan-worth of estimate drift), but it's in
+     * the DOM. Follow with getItemTop(i) for the precise position.
+     */
+    scrollToIndex: (i: number) => void;
+};
+/**
+ * React-level virtualization for items inside a ScrollBox.
+ *
+ * The ScrollBox already does Ink-output-level viewport culling
+ * (render-node-to-output.ts:617 skips children outside the visible window),
+ * but all React fibers + Yoga nodes are still allocated. At ~250 KB RSS per
+ * MessageRow, a 1000-message session costs ~250 MB of grow-only memory
+ * (Ink screen buffer, WASM linear memory, JSC page retention all grow-only).
+ *
+ * This hook mounts only items in viewport + overscan. Spacer boxes hold the
+ * scroll height constant for the rest at O(1) fiber cost each.
+ *
+ * Height estimation: fixed DEFAULT_ESTIMATE for unmeasured items, replaced
+ * by real Yoga heights after first layout. No scroll anchoring — overscan
+ * absorbs estimate errors. If drift is noticeable in practice, anchoring
+ * (scrollBy(delta) when topSpacer changes) is a straightforward followup.
+ *
+ * stickyScroll caveat: render-node-to-output.ts:450 sets scrollTop=maxScroll
+ * during Ink's render phase, which does NOT fire ScrollBox.subscribe. The
+ * at-bottom check below handles this — when pinned to the bottom, we render
+ * the last N items regardless of what scrollTop claims.
+ */
+export declare function useVirtualScroll(scrollRef: RefObject<ScrollBoxHandle | null>, itemKeys: readonly string[], 
+/**
+ * Terminal column count. On change, cached heights are stale (text
+ * rewraps) — SCALED by oldCols/newCols rather than cleared. Clearing
+ * made the pessimistic coverage back-walk mount ~190 items (every
+ * uncached item → PESSIMISTIC_HEIGHT=1 → walk 190 to reach
+ * viewport+2×overscan). Each fresh mount runs marked.lexer + syntax
+ * highlighting ≈ 3ms; ~600ms React reconcile on first resize with a
+ * long conversation. Scaling keeps heightCache populated → back-walk
+ * uses real-ish heights → mount range stays tight. Scaled estimates
+ * are overwritten by real Yoga heights on next useLayoutEffect.
+ *
+ * Scaled heights are close enough that the black-screen-on-widen bug
+ * (inflated pre-resize offsets overshoot post-resize scrollTop → end
+ * loop stops short of tail) doesn't trigger: ratio<1 on widen scales
+ * heights DOWN, keeping offsets roughly aligned with post-resize Yoga.
+ */
+columns: number): VirtualScrollResult;

package/dist/ui/perf-probes.d.ts

@@ -0,0 +1,22 @@
+export declare const PERF_ENABLED: boolean;
+export declare function startEventLoopMonitor(intervalMs?: number, warnThresholdMs?: number): void;
+export declare function stopEventLoopMonitor(): void;
+export declare function recordStreamEvent(type: string, agentId: string | undefined): void;
+export declare function startStreamRateReporter(windowMs?: number): void;
+export declare function stopStreamRateReporter(): void;
+export declare function recordAppRender(): void;
+export declare function startAppRenderReporter(windowMs?: number): void;
+export declare function stopAppRenderReporter(): void;
+export declare function recordInkFrame(event: {
+    durationMs: number;
+    phases: {
+        diff: number;
+        write: number;
+        yoga: number;
+        patches: number;
+    };
+}): void;
+export declare function startInkFrameReporter(windowMs?: number): void;
+export declare function stopInkFrameReporter(): void;
+export declare function startAllPerfProbes(): void;
+export declare function stopAllPerfProbes(): void;