@opengeni/react 0.13.0 → 0.20.0

package/dist/index.d.ts

@@ -1,21 +1,30 @@
-import { C as ClientOverride, S as SessionClientLike } from './machines-CnlMb7E-.js';
-export { a as CONNECTION_STATUS_META, b as ConnectionDot, c as ConnectionDotProps, d as ConnectionStatus, e as ConnectionStatusMeta, f as ConnectionStatusPill, g as ConnectionStatusPillProps, D as DeviceFlowPhase, E as EnrollmentConsent, h as EnrollmentConsentMachine, i as EnrollmentConsentPhase, j as EnrollmentConsentProps, k as EnrollmentDeviceFlow, l as EnrollmentDeviceFlowProps, M as MACHINE_STATE_BADGE_META, m as MachineCard, n as MachineCardProps, o as MachineDockBar, p as MachineDockBarProps, q as MachineMetrics, r as MachineMetricsProps, s as MachineStateBadgeMeta, t as MachineStatusPill, u as MachineStatusPillProps, v as MachinesClientLike, w as MachinesDashboard, x as MachinesDashboardProps, O as OpenGeniContextValue, y as OpenGeniProvider, z as OpenGeniProviderProps, A as SharedMachineDisclosure, B as SharedMachineDisclosureProps, U as UseMachinesOptions, F as UseMachinesResult, G as connectionStatusForState, H as useMachines, I as useOpenGeni, J as useOpenGeniClient } from './machines-CnlMb7E-.js';
-import { SessionEvent, Session, ResourceRef, ToolRef, SessionStatus as SessionStatus$1, GitFileDiff, StreamConnectionState, SendMessageInput, FileAsset, FileResourceRef, SessionQueueSnapshot, SessionTurn, SessionGoal, ScheduledTask, SessionLineageResponse, VariableSet, CreateVariableSetRequest, UpdateVariableSetRequest, VariableSetVariableMetadata, RigChange, Rig, UpdateRigRequest, RigVersion, ProposeRigChangeRequest, CreateRigRequest, CapabilityPack, PackInstallation, RegisterCapabilityPackRequest, WorkspaceRegisteredPack, EnablePackRequest, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, BillingBalance, UsageEvent, ClientModel, SessionCapabilities, DesktopStreamCapability, DesktopConnectionState, DesktopRfbFactory, TerminalCapability, FsReadResponse, FsWriteResponse, WorkspaceCaptureManifest, WorkspaceCaptureDegradedReason, MachineState, Permission, CapabilityUnavailableReason, MachineView, CodexAccountsResponse, CodexAccount, CodexRotationSettings } from '@opengeni/sdk';
+import { S as SessionClientLike, C as ClientOverride } from './session-context-DIFFlXKc.js';
+export { a as EmbeddedHumanInputSessionClientLike, b as EmbeddedSessionClientLike, O as OpenGeniContextValue, u as useOpenGeni, c as useOpenGeniClient } from './session-context-DIFFlXKc.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { WorkspaceControlEvent, Session, SessionEvent, EffectiveSessionControl, ClientModel, SessionGoal, ScheduledTask, SessionLineageResponse, VariableSet, CreateVariableSetRequest, UpdateVariableSetRequest, VariableSetVariableMetadata, RigChange, Rig, UpdateRigRequest, RigVersion, ProposeRigChangeRequest, CreateRigRequest, CapabilityPack, PackInstallation, RegisterCapabilityPackRequest, WorkspaceRegisteredPack, EnablePackRequest, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, BillingBalance, UsageEvent, SessionCapabilities, DesktopStreamCapability, DesktopConnectionState, DesktopRfbFactory, TerminalCapability, OpenGeniRequestOptions, FsReadResponse, FsWriteResponse, WorkspaceCaptureManifest, GitFileDiff, WorkspaceCaptureDegradedReason, MachineState, SessionHumanInputRequest, SubmitHumanInputResponseRequest, HumanInputQuestion, HumanInputAnswer, Permission, SessionStatus as SessionStatus$1, CapabilityUnavailableReason, MachineView, CodexAccountsResponse, CodexAccount, CodexRotationSettings } from '@opengeni/sdk';
 export { MachineKind, MachineMetricsSeriesResponse, MachineState, MachineView, MachinesResponse, MetricSample } from '@opengeni/sdk';
 import * as react from 'react';
-import { ComponentType, ReactNode, RefObject, KeyboardEvent, ClipboardEvent } from 'react';
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ClipboardEvent, RefObject, ComponentType } from 'react';
+import { S as SessionEventFeedOptions, C as ComposerState } from './use-composer-BCfm4mzX.js';
+export { a as ComposerSendExtras, F as FILE_ONLY_MESSAGE_TEXT, U as UseComposerOptions, c as composeSendInput, s as shouldSteerOnKey, b as shouldSubmitOnKey, u as useComposer } from './use-composer-BCfm4mzX.js';
+import { U as UseTurnQueueResult, P as PendingApproval, T as ToolCallItem, A as ActivityItem, a as TurnOutcome, b as TimelineItem, c as AgentMessageItem, d as UserMessageItem, e as AuthNeededItem } from './session-Gd4iVPYw.js';
+export { B as BrowserSessionEventWindow, G as GoalItem, N as NoticeItem, f as PendingHumanInputRequest, Q as QueueMutationKind, R as ReasoningItem, S as SESSION_EVENT_BROWSER_MAX_BYTES, g as SESSION_EVENT_BROWSER_MAX_COUNT, h as SESSION_EVENT_BROWSER_PENDING_MAX_BYTES, i as SESSION_EVENT_BROWSER_PENDING_MAX_COUNT, j as SESSION_EVENT_BROWSER_SINGLE_EVENT_MAX_BYTES, k as SandboxItem, l as SessionEventsConnectionState, m as SessionStatusItem, n as TimelineGroup, o as TurnEndItem, p as UseHumanInputRequestsOptions, q as UseHumanInputRequestsResult, r as UseSessionControlOptions, s as UseSessionControlResult, t as UseSessionEventsOptions, u as UseSessionEventsResult, v as UseTurnQueueOptions, W as WorkerItem, w as approvalsFromRequiresAction, x as boundBrowserSessionEventWindow, y as buildTimeline, z as creditExhaustedFromEvents, C as extractSessionRef, D as groupTimeline, E as humanInputRequestFromEvent, F as isHumanInputEvent, H as isTurnQueueEvent, I as projectPendingApprovals, J as projectPendingHumanInputRequests, K as sessionStatusFromEvents, L as toolDisplayName, M as useHumanInputRequests, O as useSessionControl, V as useSessionEvents, X as useTurnQueue } from './session-Gd4iVPYw.js';
+import { C as ComposerControlLinks, a as ComposerTranscriptionControlProps, U as UseFileAttachmentsResult, S as SlashCommand, b as SlashCommandContext, c as ChatComposerMessages, d as SlashArg, e as CommandContext } from './composer-DvUaa5ki.js';
+export { f as CommandResult, g as ComposerTranscriptionControl, h as ComposerTranscriptionMessages, i as ConfirmState, F as FileAttachment, I as INITIAL_TRANSCRIPTION_CONTROL_STATE, N as Notice, O as OPEN_WORKSTREAM_CONTROL_EVENT, j as SlashCommandHandlers, T as TranscriptionControlAction, k as TranscriptionControlState, l as TranscriptionControlTransition, m as UseFileAttachmentsOptions, n as UseSlashCommandsOptions, o as UseSlashCommandsResult, p as UseTranscriptionOptions, q as UseTranscriptionResult, r as appendFinalTranscript, s as defaultChatComposerMessages, t as transitionTranscriptionControl, u as useFileAttachments, v as useSlashCommands, w as useTranscription } from './composer-DvUaa5ki.js';
+export { CONNECTION_STATUS_META, ConnectionDot, ConnectionDotProps, ConnectionStatus, ConnectionStatusMeta, ConnectionStatusPill, ConnectionStatusPillProps, DeviceFlowPhase, EnrollmentConsent, EnrollmentConsentMachine, EnrollmentConsentPhase, EnrollmentConsentProps, EnrollmentDeviceFlow, EnrollmentDeviceFlowProps, HEALTH_TOKEN, HealthLevel, HealthVerdict, MACHINE_STATE_BADGE_META, METRICS, METRIC_WINDOWS, MachineCard, MachineCardProps, MachineDetail, MachineDetailProps, MachineDockBar, MachineDockBarProps, MachineHealthPill, MachineHealthPillProps, MachineMetrics, MachineMetricsProps, MachineStateBadgeMeta, MachineStatusPill, MachineStatusPillProps, MachinesClientLike, MachinesDashboard, MachinesDashboardProps, MetricDef, MetricHistoryChart, MetricHistoryChartProps, MetricKey, MetricSparkline, MetricSparklineProps, MetricWindow, SeriesPoint, SharedMachineDisclosure, SharedMachineDisclosureProps, UseMachinesOptions, UseMachinesResult, WINDOW_LABEL, connectionStatusForState, deriveHealth, healthPulses, pointsFor, useMachines } from './machines.js';
 import { ClassValue } from 'clsx';
 
-type SessionEventFeedOptions = {
-    /**
-     * Share an existing event log (from `useSessionEvents`) instead of opening
-     * a second stream. When omitted the hook tails the session's event stream
-     * itself, starting at the current `lastSequence`.
-     */
-    events?: SessionEvent[] | undefined;
-    enabled?: boolean | undefined;
+type OpenGeniProviderProps = {
+    client: SessionClientLike;
+    workspaceId: string;
+    onWorkspaceControlEvent?: ((event: WorkspaceControlEvent) => void) | undefined;
+    children?: ReactNode;
 };
+/**
+ * Supplies the OpenGeni client + workspace to all hooks below it. Hooks also
+ * accept `{ client, workspaceId }` overrides per call for multi-workspace UIs.
+ */
+declare function OpenGeniProvider({ client, workspaceId, onWorkspaceControlEvent, children, }: OpenGeniProviderProps): react_jsx_runtime.JSX.Element;
 
 type UseSessionOptions = ClientOverride & SessionEventFeedOptions & {
     /** Re-fetch on an interval (ms). Off by default — pair with `useSessionEvents` for live status. */
@@ -38,752 +47,66 @@ declare function isTitleEvent(event: Pick<SessionEvent, "type">): boolean;
 /** Fetch one session (with optional polling), live-patching its title on `session.title_set`. */
 declare function useSession(sessionId: string | null | undefined, options?: UseSessionOptions): UseSessionResult;
 
-type UserMessageItem = {
-    kind: "user-message";
-    id: string;
-    text: string;
-    /** Resources attached to this message (file uploads, repositories). */
-    resources: ResourceRef[];
-    /** Tools requested for the turn this message starts. */
-    tools: ToolRef[];
-    occurredAt: string;
-};
-type AgentMessageItem = {
-    kind: "agent-message";
-    id: string;
-    turnId: string | null;
-    text: string;
-    /** Still receiving deltas (no completed/turn-end seen yet). */
-    streaming: boolean;
-    occurredAt: string;
-};
-type ReasoningItem = {
-    kind: "reasoning";
-    id: string;
-    turnId: string | null;
-    text: string;
-    streaming: boolean;
-    occurredAt: string;
-};
-type ToolCallItem = {
-    kind: "tool-call";
-    id: string;
-    turnId: string | null;
-    callId: string | null;
-    name: string;
-    arguments: unknown;
-    output: unknown;
-    /**
-     * The provider-native tool item (`agent.toolCall.created.payload.raw`). Carries
-     * `type` (e.g. `apply_patch_call`, `computer_call`, `hosted_tool_call`) and the
-     * tool-specific fields the per-tool renderers read (`operation`, `action`,
-     * `providerData`, …). `undefined` for first-party MCP tools, which carry their
-     * payload in `arguments`/`output` instead.
-     */
-    raw: unknown;
-    status: "running" | "complete" | "failed" | "cancelled";
-    occurredAt: string;
-};
-/**
- * An orchestration call against another session — the manager spawning or
- * messaging a worker. Rendered as a first-class "worker" row, not a generic
- * tool call.
- */
-type WorkerItem = {
-    kind: "worker";
-    id: string;
-    turnId: string | null;
-    callId: string | null;
-    action: "spawn" | "message";
-    /** The worker's initial message / the message sent to it, when parseable. */
-    prompt: string | null;
-    /** The target/spawned worker session id, when parseable from args/output. */
-    workerSessionId: string | null;
-    status: "running" | "complete" | "failed" | "cancelled";
-    occurredAt: string;
-};
-type WorkerCompletionItem = {
-    kind: "worker-completion";
-    id: string;
-    turnId: string | null;
-    occurredAt: string;
-    childSessionId: string;
-    childStatus: string;
-    goalStatus: string | null;
-    goalText: string | null;
-    evidence: string | null;
-    pausedReason: string | null;
-    text: string;
-};
-type SandboxItem = {
-    kind: "sandbox";
-    id: string;
-    turnId: string | null;
-    name: string;
-    command: string | null;
-    output: string;
-    origin?: "created" | "restored" | "resumed" | null;
-    status: "running" | "complete" | "failed" | "cancelled";
-    occurredAt: string;
-};
-/**
- * A first-party workspace-memory write the agent made mid-turn — a `memory.saved`
- * (it committed a new preference / fact / procedure / decision / history) or a
- * `memory.corrected` (it updated or archived an existing one). A settled save is
- * ordinary progress, not an exceptional state, so it renders as a calm NEUTRAL
- * step on the rail (never accent/color). When the host app supplies an
- * `onMemoryClick` handler the row also deep-links to the record in its memory
- * pane; without one it is non-interactive rich content.
- */
-type MemoryItem = {
-    kind: "memory";
-    id: string;
-    turnId: string | null;
-    variant: "saved" | "corrected";
-    /** The memory's kind enum (`"preference" | "semantic" | …`); mapped to a human label at render. */
-    memoryKind: string;
-    /** The memory text, ellipsized to ≤120 chars server-side. For a supersede this is the OLD text. */
-    preview: string;
-    /** The save collapsed into an existing memory (no new row was written). Saved variant only. */
-    deduped?: boolean;
-    /** The NEW text when a correction superseded the memory with a replacement; absent = updated-in-place or archived. */
-    replacementPreview?: string;
-    /**
-     * What a `memory.corrected` did: `"superseded"` (replaced by a new record, see
-     * `replacementPreview`), `"updated"` (edited in place — the record lives on), or
-     * `"archived"` (retired). Distinguishes updated-in-place from archived when there
-     * is no replacement. Corrected variant only; read defensively (may be absent).
-     */
-    action?: string;
-    /** The saved / corrected memory's id — the deep-link target for a save. */
-    memoryId: string;
-    /** The replacement memory's id when a correction produced one — the LIVE record the deep-link targets. */
-    replacementMemoryId?: string;
-    occurredAt: string;
-};
-type SessionStatusItem = {
-    kind: "session-status";
-    id: string;
-    status: SessionStatus$1;
-    occurredAt: string;
-};
-type GoalItem = {
-    kind: "goal";
-    id: string;
-    action: "set" | "updated" | "completed" | "paused" | "resumed" | "cleared" | "continuation";
-    text: string | null;
-    occurredAt: string;
-};
-type NoticeItem = {
-    kind: "notice";
-    id: string;
-    tone: "waiting" | "cancelled" | "failed";
-    text: string;
-    /** Optional evidence kept inspectable without overwhelming the main rail. */
-    details?: {
-        label: string;
-        value: unknown;
-    };
-    action?: {
-        label: string;
-        url: string;
-    };
-    occurredAt: string;
-};
-/**
- * A tool call hit a connection whose credential lapsed — the broker asked the
- * user to reconnect the provider before the turn can continue. Carries the
- * structured `tool.auth_needed` payload so the renderer can draw a clean inline
- * reconnect affordance (provider logo + one human line + a Reconnect button)
- * and the app can start the right recovery flow (OAuth reconnect for the
- * surviving connection, or credential re-entry for an api-key one). The `reason`
- * shapes the human copy but is never shown raw.
- */
-type AuthNeededItem = {
-    kind: "auth-needed";
-    id: string;
-    turnId: string | null;
-    /** The connection's registrable domain, e.g. "linear.app". */
-    providerDomain: string;
-    /** The lapsed connection to reconnect, when the row survived. */
-    connectionId: string | null;
-    reason: "missing_connection" | "expired" | "insufficient_scope" | "refresh_failed" | null;
-    /** Scopes the provider now needs; may inform the copy, never shown as a raw label. */
-    scopes: string[];
-    /** The OAuth `resource` (RFC 8707) the reconnect should target, when supplied. */
-    resource: string | null;
-    /** The tool whose call triggered the reauth, for context. */
-    toolName: string | null;
-    /** A pre-minted authorization URL, when the broker already produced one. */
-    authorizationUrl: string | null;
-    occurredAt: string;
-};
-type TurnOutcome = "complete" | "failed" | "cancelled";
-type TurnEndItem = {
-    kind: "turn-end";
-    id: string;
-    turnId: string | null;
-    outcome: TurnOutcome;
-    failureText: string | null;
-    occurredAt: string;
-};
-type TimelineItem = UserMessageItem | AgentMessageItem | ReasoningItem | ToolCallItem | WorkerItem | WorkerCompletionItem | SandboxItem | SessionStatusItem | GoalItem | NoticeItem | AuthNeededItem | MemoryItem | TurnEndItem;
-/** Activity items cluster between chat messages (reasoning, tools, workers, sandbox, memory). */
-type ActivityItem = ReasoningItem | ToolCallItem | WorkerItem | SandboxItem | MemoryItem;
-type TimelineGroup = {
-    kind: "item";
-    item: TimelineItem;
-} | {
-    kind: "activity";
-    id: string;
-    items: ActivityItem[];
-    outcome?: TurnOutcome;
-    failureText?: string;
-} | {
-    kind: "turn";
-    id: string;
-    outcome: TurnOutcome;
-    failureText?: string;
-    startedAt: string;
-    endedAt: string;
-    groups: TimelineGroup[];
+/** The sole human prompt queue: compact above Goal, Agents, and composer. */
+type QueueSurfaceCommonProps = {
+    /** Focus the composer owned by this queue after checkout/removal. */
+    onRequestComposerFocus?: (() => void) | undefined;
 };
+type QueueSurfaceProps = (QueueSurfaceCommonProps & {
+    queue: UseTurnQueueResult;
+    composer: ComposerState;
+    readOnly?: false | undefined;
+}) | (QueueSurfaceCommonProps & {
+    queue: UseTurnQueueResult;
+    composer?: undefined;
+    readOnly: true;
+});
 
-declare function buildTimeline(events: SessionEvent[]): TimelineItem[];
-/**
- * Whether the session's most recent turn ended in credit exhaustion — the
- * terminal credit state apps key their "add credits" affordances on. Derived
- * from the LAST turn-end event (completed/failed/cancelled): a later turn that
- * settles any other way (someone topped up and kept working) clears it.
- */
-declare function creditExhaustedFromEvents(events: SessionEvent[]): boolean;
-/** The latest session status carried in the event log, if any. */
-declare function sessionStatusFromEvents(events: SessionEvent[]): SessionStatus$1 | null;
-declare function groupTimeline(items: TimelineItem[]): TimelineGroup[];
-/**
- * Find a session id in orchestration tool arguments or output. Handles raw
- * objects, JSON strings, and MCP tool results (`{ content: [{ type: "text",
- * text: "{...}" }], structuredContent? }`).
- */
-declare function extractSessionRef(value: unknown, depth?: number): string | null;
-/**
- * Readable label for a tool call ("session_create" -> "session create").
- *
- * MCP tools are namespaced `<serverId>__<toolName>` (see prefixedMcpToolName),
- * and for catalog-imported servers that serverId is an opaque slug+hash
- * ("mcp-integrations-sh-supabase-com-34ed9dcf1390-0i6tcf8"). De-slugging the
- * whole thing leaked that id into the timeline; strip the server prefix and show
- * just the tool ("list organizations"). Names without the `__` boundary (plain
- * built-ins like "session_create") are unaffected.
- */
-declare function toolDisplayName(name: string): string;
-
-type ToolRendererProps = {
-    item: ToolCallItem;
-};
-type ToolRenderer = ComponentType<ToolRendererProps>;
-/** A registry entry: which key it matches and the component that renders it. */
-type ToolRegistryEntry = {
-    match: "rawType";
-    type: string;
-    render: ToolRenderer;
-} | {
-    match: "name";
-    name: string;
-    render: ToolRenderer;
-};
-type ToolRegistry = {
-    /** Resolve the renderer for a call (never null — falls back to generic). */
-    resolve: (item: ToolCallItem) => ToolRenderer;
-    /** The generic fallback renderer. */
-    fallback: ToolRenderer;
-};
-type CreateToolRegistryOptions = {
-    /**
-     * Entries that take precedence over the built-ins. Earlier entries win, so a
-     * consumer can shadow a default renderer for the same key.
-     */
-    entries?: ToolRegistryEntry[] | undefined;
-    /** Replace the generic fallback used for unmatched tools. */
-    fallback?: ToolRenderer | undefined;
-};
-/** The `raw.type` of a projected tool call, when the provider item carries one. */
-declare function rawTypeOf(item: ToolCallItem): string | null;
-/**
- * Build a tool registry from a set of entries and a fallback. The returned
- * registry resolves in priority order: `raw.type` entries first, then `name`
- * entries, then the fallback. Consumer `entries` are consulted before the
- * built-in `baseEntries`, so they shadow defaults cleanly.
- */
-declare function createToolRegistry(baseEntries: ToolRegistryEntry[], baseFallback: ToolRenderer, options?: CreateToolRegistryOptions): ToolRegistry;
-
-/** The built-in tool renderer registry: every first-party tool plus a fallback. */
-declare const defaultToolRegistry: ToolRegistry;
-/** Build a registry that extends the built-ins with consumer entries/fallback. */
-declare function createDefaultToolRegistry(options?: Parameters<typeof createToolRegistry>[2]): ToolRegistry;
-
-type ActivityRailProps = {
-    items: ActivityItem[];
-    /** Renderer registry for tool calls. Defaults to {@link defaultToolRegistry}. */
-    toolRegistry?: ToolRegistry | undefined;
-    /** Drill into a spawned worker session. */
-    onOpenSession?: ((sessionId: string) => void) | undefined;
-    /**
-     * Deep-link a memory row to its record in the host's memory pane. Opt-in: the
-     * library draws no "View in memory" affordance without a handler (the memory
-     * row is then non-interactive rich content). See {@link MessageTimelineProps}.
-     */
-    onMemoryClick?: ((memoryId: string) => void) | undefined;
-    /** Drop the left rule + indent (used inside a folded turn summary). */
-    bare?: boolean | undefined;
-    className?: string | undefined;
-};
-declare function ActivityRail({ items, toolRegistry, onOpenSession, onMemoryClick, bare, className, }: ActivityRailProps): react_jsx_runtime.JSX.Element;
-
-/**
- * A subtle settle signal — see the CHIP DOCTRINE above. The closed tone set.
- * `"interrupted"` is a calm neutral tone for cancelled items — no dot, same
- * quiet weight as `"muted"`, but semantically distinct from metadata.
- */
-type DisclosureChip = {
-    tone: "ok" | "bad" | "muted" | "interrupted";
-    text: string;
-};
-type ActivityDisclosureProps = {
-    icon: ReactNode;
-    /** Icon tint. Defaults to the muted foreground; renderers pass accent/failed. */
-    iconTone?: "accent" | "failed" | "running" | "muted" | undefined;
-    title: ReactNode;
-    /** Render the title in the mono face (commands, paths). */
-    titleMono?: boolean | undefined;
-    /** Shimmer the title while the tool is in-flight. */
-    running?: boolean | undefined;
-    /**
-     * Quiet single-line secondary text (truncated). It is detail-on-demand: hidden
-     * when a media preview is set, AND hidden once the row is expanded (the body
-     * then owns the detail), so a stat/path never appears twice at once.
-     */
-    preview?: ReactNode | undefined;
-    /** A small inline media preview (a screenshot thumbnail) shown in place of `preview`. */
-    media?: ReactNode | undefined;
-    /** At most one quiet settle chip, right-aligned to the gutter. */
-    chip?: DisclosureChip | undefined;
-    /**
-     * When true the row carries the standard failure affordance: the icon is tinted
-     * red and a "failed" bad-chip appears in the right gutter (unless an explicit
-     * `chip` is already supplied — the caller's chip wins). Output is still visible
-     * on expand; this is a quiet status signal, not a blocking banner.
-     *
-     * Renderers should pass `failed={item.status === "failed"}` on their settled
-     * (non-running) paths so any tool with a failed status shows a consistent
-     * affordance without each renderer having to duplicate the logic.
-     */
-    failed?: boolean | undefined;
-    /**
-     * When true the row carries a calm "interrupted" affordance: the icon stays
-     * muted (no red) and a quiet "interrupted" chip appears in the right gutter
-     * (unless an explicit `chip` is already supplied — the caller's chip wins).
-     * This is the cancelled-status analogue of `failed`, but deliberately calm
-     * and neutral — it is NOT an error; the user chose to stop.
-     *
-     * Renderers should pass `cancelled={item.status === "cancelled"}` so any
-     * in-flight item that was interrupted on turn.cancelled reads consistently.
-     * `cancelled` is ignored when `failed` is also true (failure takes precedence).
-     */
-    cancelled?: boolean | undefined;
-    /** When false the row is a static line (no expand affordance). */
-    expandable?: boolean | undefined;
-    children?: ReactNode | undefined;
-};
-/**
- * The one disclosure row shape every activity row reuses (tool calls, reasoning,
- * sandbox ops): a chevron, a tinted icon, a title, an optional muted preview or
- * inline media, and at most one right-gutter settle chip. Compact by default;
- * the body mounts only when expanded.
- */
-declare function ActivityDisclosure({ icon, iconTone: iconToneProp, title, titleMono, running, preview, media, chip: chipProp, failed, cancelled, expandable, children, }: ActivityDisclosureProps): react_jsx_runtime.JSX.Element;
-declare function TermBlock({ command, workdir, output, live, tailLines, failed, }: {
-    /**
-     * The command shown in the prompt header. Pass `null` when the row title
-     * already carries it (e.g. an exec row titled `$ cmd`): the header then drops
-     * the command — and the whole prompt line if there is no workdir either — so
-     * the command never reads twice, stacked, above the output.
-     */
-    command: string | null;
-    workdir?: string | null | undefined;
-    /** The FULL output. TermBlock owns the tail/full slicing internally. */
-    output: string;
-    live?: boolean | undefined;
-    /** A non-zero exit / failed call — tints the left accent red (the one hue). */
-    failed?: boolean | undefined;
-    /**
-     * When the output exceeds the tail window, only the last `tailLines` are shown
-     * with a "show full output" toggle. The component holds the full text, so the
-     * toggle reveals the rest (never a dead affordance). Defaults to 12.
-     */
-    tailLines?: number | undefined;
-}): react_jsx_runtime.JSX.Element;
-declare function PayloadBlock({ label, value, failed, }: {
-    label: string;
-    value: unknown;
-    failed?: boolean | undefined;
-}): react_jsx_runtime.JSX.Element | null;
-/** A quiet inline note inside an expanded body (lost output, empty frame, …). */
-declare function BodyNote({ children, tone, }: {
-    children: ReactNode;
-    tone?: "error" | "muted" | undefined;
-}): react_jsx_runtime.JSX.Element;
-/**
- * A loading screenshot placeholder. A faint camera glyph over a shimmering box,
- * so a still frame of the running state reads unambiguously as "capturing" — not
- * a broken thumbnail.
- */
-declare function MediaSkeleton(): react_jsx_runtime.JSX.Element;
-/** A standardized "tool ran, produced no image" placeholder in the media slot. */
-declare function MediaEmpty(): react_jsx_runtime.JSX.Element;
-/**
- * A small inline screenshot thumbnail that opens the app lightbox on click.
- *
- * Requires a `LightboxProvider` ancestor for the click-to-expand affordance.
- * Outside one it degrades to a plain, non-interactive image — never a dead
- * "Expand" button that announces an action it cannot perform.
- */
-declare function Thumbnail({ src, caption, alt, }: {
-    src: string;
-    caption?: string | undefined;
-    alt?: string;
-}): react_jsx_runtime.JSX.Element;
-/**
- * The expanded screenshot inside a tool body: a contained, clickable preview
- * (opens the lightbox) with a quiet caption. Constrained height + object-contain
- * so it never breaks the row layout. Like {@link Thumbnail}, it degrades to a
- * plain image outside a `LightboxProvider`.
- */
-declare function ScreenshotFigure({ src, caption, alt, }: {
-    src: string;
-    caption?: string | undefined;
-    alt?: string;
-}): react_jsx_runtime.JSX.Element;
-
-type LightboxController = {
-    open: (src: string, caption?: string) => void;
-};
-/** Open the app-level screenshot lightbox. No-op outside a `LightboxProvider`. */
-declare function useLightbox(): LightboxController;
-/**
- * The lightbox controller when one is mounted, or `null` outside a
- * `LightboxProvider`. Lets a media primitive degrade to a non-interactive image
- * (rather than a dead "Expand" button that announces an action it cannot do).
- */
-declare function useLightboxOptional(): LightboxController | null;
-/**
- * The app-level screenshot lightbox. Render once near the timeline; renderers
- * call `useLightbox().open(src)`.
- *
- * Idempotent by design: when an ancestor `LightboxProvider` already exists (e.g.
- * a `MessageTimeline` mounted inside an app that already wraps its shell), this
- * one becomes a pass-through and does NOT mount a second focus-trapping Dialog.
- * That keeps `MessageTimeline` self-sufficient (it owns its own provider) while
- * composing cleanly when nested.
- */
-declare function LightboxProvider({ children }: {
-    children: ReactNode;
-}): react_jsx_runtime.JSX.Element;
-
-/**
- * Seed the initial open state of every timeline collapsible below this node.
- * Intended for screenshot/test instrumentation only; absent by default.
- */
-declare function DisclosureDefaultsProvider({ defaultOpen, children, }: {
-    defaultOpen: boolean;
-    children: ReactNode;
-}): react_jsx_runtime.JSX.Element;
-
-type TurnSummaryProps = {
-    /** The activity items in the turn (used only to compute the facet counts). */
-    items: ActivityItem[];
-    /**
-     * The settled verdict — or absent for a completed CLUSTER of a still-running
-     * turn, which folds neutrally: no verdict glyph (the turn has none yet), a
-     * quiet pulse dot in its place so alignment and the running feel both hold.
-     */
-    outcome?: TurnOutcome | undefined;
-    /** A short failure reason shown inline on a failed chip (never hidden). */
-    failureText?: string | undefined;
-    /** Elapsed turn duration; shown as a trailing facet when at least 1s. */
-    durationMs?: number | undefined;
-    /** Start expanded. */
-    defaultOpen?: boolean | undefined;
-    /**
-     * A nested fold — a cluster or sub-turn INSIDE an already-expanded turn. It
-     * drops the bordered/filled chip and renders as a plain disclosure node on the
-     * parent's rail (chevron + glyph + facets), so expanding a turn reveals a thread
-     * of nodes, never a stack of boxes-in-boxes. The top-level fold stays a chip.
-     */
-    bare?: boolean | undefined;
-    /** The rendered activity rail revealed on expand. */
-    children: React.ReactNode;
-};
-declare function TurnSummary({ items, outcome, failureText, durationMs, defaultOpen, bare, children, }: TurnSummaryProps): react_jsx_runtime.JSX.Element;
-
-/** Recover the exit code from a sandbox exec banner (`Process exited with code N`). */
-declare function sandboxCommandExitCode(out: unknown): number | null;
-/**
- * Recover the numeric exec-session id the sandbox embeds for a STILL-RUNNING
- * (backgrounded) process (`Process running with session ID N`). A finished
- * command emits `Process exited with code N` instead, which yields `null`.
- */
-declare function parseExecBannerSessionId(out: unknown): number | null;
-/** Strip the exec banner (`Chunk ID ...\n...\nOutput:\n`) down to the command's stdout. */
-declare function stripExecBanner(out: unknown): string;
-/** The sandbox clamped the output (token/line truncation markers in the banner). */
-declare function execTruncated(out: unknown): boolean;
-/** A `write_stdin` whose target PTY vanished (`write_stdin failed: session not found: N`). */
-declare function isExecSessionLostBanner(out: unknown): boolean;
-/** True when the exec stdout looks binary/garbled (a NUL byte or ELF magic). */
-declare function looksBinary(text: string): boolean;
-/**
- * Render unprintable control characters as caret notation (0x03 -> `^C`) so a
- * `write_stdin` keystroke payload reads cleanly in the row title.
- */
-declare function controlCaret(printable: string): string;
-/** One operation inside an `apply_patch_call` (a V4A file edit). */
-type ApplyPatchOperation = {
-    /**
-     * The V4A op kind. The three canonical values are `create_file`,
-     * `update_file`, and `delete_file`; the open `string` tail tolerates a
-     * forward-compatible/unknown op kind from the provider without a type error
-     * (it falls through to the "Edited" treatment).
-     */
-    type: "create_file" | "update_file" | "delete_file" | (string & {});
-    path: string;
-    /** Rename target -- when present the op is a move/rename. */
-    moveTo?: string | null | undefined;
-    /** The V4A hunk string (`@@ ...` lines with `+`/`-`/context prefixes). */
-    diff?: string | undefined;
-};
-/**
- * Parse a single V4A `apply_patch` operation into the SDK's `GitFileDiff` shape
- * so it can flow into the SAME `DiffView` / `PierreDiff` the Files tab uses.
- * Throws on a hunk string it cannot structure (no `@@` anchor on an update); the
- * renderer catches and falls back to a raw-patch view.
- */
-declare function v4aToGitFileDiff(op: ApplyPatchOperation): GitFileDiff;
-/**
- * Extract the `apply_patch` operations from a provider-native tool item's `raw`
- * payload, normalizing the two wire shapes (`raw.operations[]` for a multi-file
- * patch, `raw.operation` for a single op). The single owner of this shape so the
- * renderer and the turn-summary facet counter never drift.
- */
-declare function applyPatchOps(raw: unknown): ApplyPatchOperation[];
-/**
- * True when a tool item is an `apply_patch_call` — by its provider-native
- * `raw.type` (the live-wire source of truth) or by tool `name` (first-party
- * replays that omit `raw`). Centralizes the rawType-or-name check.
- */
-declare function isApplyPatch(item: {
-    name: string;
-    raw: unknown;
-}): boolean;
-/** Deep-redact secret-looking values so arguments never leak a key into the UI. */
-declare function redactSecrets(value: unknown): unknown;
-/** Parse tool arguments that may arrive as a JSON string or an object. */
-declare function parseToolArgs(args: unknown): Record<string, unknown>;
-/** The last non-empty line of a string -- the compact "what happened" peek. */
-declare function tailPeek(text: string): string;
-/**
- * Unwrap an MCP tool result (`{ content: [{ type: "text", text }], isError? }`)
- * into a flat `{ text, isError }`. Non-MCP outputs pass through as their string
- * form.
- */
-declare function unwrapMcpOutput(output: unknown): {
-    text: string;
-    isError: boolean;
-};
-
-type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
-type UseSessionEventsOptions = ClientOverride & {
-    /** Resume after this sequence (exclusive). Nonzero keeps full replay/resume semantics. */
-    after?: number | undefined;
-    /** Load a bounded tail by default, or opt back into full replay from `after`. */
-    replay?: "windowed" | "full" | undefined;
-    /** Pause the stream without unmounting (e.g. hidden tab). Defaults to true. */
-    enabled?: boolean | undefined;
-};
-type UseSessionEventsResult = {
-    /** Replayed + live events, ordered by sequence, no gaps, no duplicates. */
-    events: SessionEvent[];
-    /** Projected, renderable timeline (memoized over `events`). */
-    timeline: TimelineItem[];
-    /** Latest session status observed in the event log, if any. */
-    sessionStatus: SessionStatus$1 | null;
-    connectionState: SessionEventsConnectionState;
-    /** Highest sequence seen so far (0 before the first event). */
-    lastSequence: number;
-    /** True until the initial tail window has been applied (windowed mode). */
-    initialLoading: boolean;
-    /** Whether older durable events are available before the current window. */
-    hasOlder: boolean;
-    /** True while an older window is being fetched. */
-    loadingOlder: boolean;
-    /** Prepend an older density-bounded window; resolves true when more remain. */
-    loadOlder: () => Promise<boolean>;
-    error: Error | null;
-};
-/**
- * Live-stream a session's event log with replay-by-sequence, reconnect, and
- * batched React updates. Fresh loads default to a bounded tail window; pass
- * `replay: "full"` or a nonzero `after` for the previous full replay path.
- */
-declare function useSessionEvents(sessionId: string | null | undefined, options?: UseSessionEventsOptions): UseSessionEventsResult;
-
-type ComposerSendExtras = Omit<SendMessageInput, "text" | "clientEventId">;
-/**
- * Enter appends a prompt; Cmd/Ctrl+Enter steers it to the head and supersedes
- * the current inference.
- */
-type ComposerMode = "queue" | "steer";
-type UseComposerOptions = ClientOverride & {
-    /** Called with the accepted text after a successful send. */
-    onSent?: ((text: string) => void) | undefined;
-    /**
-     * Extra message fields (resources, tools, model, reasoningEffort) merged
-     * into every send. A function is evaluated at send time so it can read the
-     * surrounding UI state (attachment pickers, model selectors, ...).
-     */
-    sendExtras?: ComposerSendExtras | (() => ComposerSendExtras) | undefined;
-};
-type ComposerState = {
-    value: string;
-    setValue: (value: string) => void;
-    /** Send the draft (or explicit text). Queue is the default; steer is explicit. */
-    send: (text?: string, mode?: ComposerMode) => Promise<boolean>;
-    sending: boolean;
-    canSend: boolean;
-    /** Pause the session without deleting its prompt queue. */
-    pause: (reason?: string) => Promise<void>;
-    pausing: boolean;
-    resume: (reason?: string) => Promise<void>;
-    resuming: boolean;
-    error: Error | null;
-    clearError: () => void;
-};
-/**
- * Draft + send + Pause/Resume state for the chat composer — the only
- * human-to-agent input surface. The draft survives a failed send (nothing is
- * more hostile than losing a typed message); each send carries a generated
- * `clientEventId` so retries stay idempotent server-side.
- */
-declare function useComposer(sessionId: string | null | undefined, options?: UseComposerOptions): ComposerState;
-/**
- * Default text for a file-only message (attachment(s) present, no typed draft).
- * Kept non-empty so the wire contract (`text: z.string().min(1)`) and the
- * worker's non-whitespace guard accept it; the attached files still ride in
- * `resources`. Exported for tests.
- */
-declare const FILE_ONLY_MESSAGE_TEXT = "(see attached files)";
-/**
- * Merge the draft text + idempotency key with caller-provided extras. The
- * text and clientEventId always win over extras. Exported for tests.
- */
-declare function composeSendInput(text: string, clientEventId: string, extras: ComposerSendExtras | (() => ComposerSendExtras) | undefined): SendMessageInput;
-/** Submit on plain Enter; Shift+Enter inserts a newline. Exported for tests. */
-declare function shouldSubmitOnKey(event: {
-    key: string;
-    shiftKey: boolean;
-    metaKey?: boolean;
-    ctrlKey?: boolean;
-    nativeEvent?: {
-        isComposing?: boolean;
-    };
-}): boolean;
-
-type UseFileAttachmentsOptions = ClientOverride & {
-    /**
-     * Only files matching this predicate are accepted by {@link
-     * UseFileAttachmentsResult.addFromPaste} (the clipboard path). Defaults to
-     * `image/*` — the console's historical paste filter. {@link
-     * UseFileAttachmentsResult.addFiles} (the explicit picker / drop path)
-     * bypasses it.
-     */
-    pasteFilter?: ((file: File) => boolean) | undefined;
-};
-type FileAttachment = {
-    id: string;
-    name: string;
-    contentType: string;
-    sizeBytes: number;
-    status: "uploading" | "ready" | "failed";
-    /** The SDK `FileAsset` once the upload finishes. */
-    file?: FileAsset | undefined;
-    /** Object-URL for an inline preview; minted for `image/*` files only. */
-    previewUrl?: string | undefined;
-    error?: string | undefined;
-};
-type UseFileAttachmentsResult = {
-    attachments: FileAttachment[];
-    /**
-     * `FileResourceRef[]` for every attachment that finished uploading — feed
-     * straight into `useComposer`'s `sendExtras.resources`.
-     */
-    readyResources: FileResourceRef[];
-    /** True while any attachment is still uploading (drives the send-gate). */
-    uploading: boolean;
-    /** Explicit picker / drop path — uploads every file, no filter. */
-    addFiles: (files: Iterable<File>) => void;
-    /** Clipboard path — applies `pasteFilter` (default `image/*`) then uploads. */
-    addFromPaste: (event: {
-        clipboardData: DataTransfer | null;
-    }) => void;
-    /**
-     * Re-run the upload for a `failed` attachment, in place (same id, same
-     * source file). No-op for an id that isn't a known failed upload.
-     */
-    retry: (id: string) => void;
-    /** Remove one attachment; revokes its object-URL. */
-    remove: (id: string) => void;
-    /** Remove all; revokes every object-URL. Call from `useComposer`'s `onSent`. */
-    clear: () => void;
-};
-/**
- * Upload-and-track state for files attached to the next message. Owns the
- * full client-side upload layer: a per-file `uploading | ready | failed`
- * status machine driven by the SDK's `client.uploadFile`, object-URL image
- * previews with create/revoke lifecycle, the `image/*` clipboard paste filter,
- * and a `FileResourceRef[]` projection that drops straight into a message's
- * `resources`. Workspace-scoped, so it resolves both client and workspace from
- * the {@link OpenGeniProvider} (or a per-call `{ client, workspaceId }`).
- */
-declare function useFileAttachments(options?: UseFileAttachmentsOptions): UseFileAttachmentsResult;
+/** The sole human prompt queue: compact above Goal, Agents, and composer. */
+declare const QueueSurface: (props: QueueSurfaceProps) => react_jsx_runtime.JSX.Element | null;
 
-/** Events that can change the authoritative prompt queue or its pause gates. */
-declare function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean;
-type UseTurnQueueOptions = ClientOverride & SessionEventFeedOptions & {
-    pollIntervalMs?: number | undefined;
-};
-type UseTurnQueueResult = {
-    snapshot: SessionQueueSnapshot | null;
-    /** Human/API prompts exactly in server execution order. Never client-sorted. */
-    queue: SessionTurn[];
-    controlState: SessionQueueSnapshot["controlState"] | null;
-    controlGeneration: number | null;
-    workspaceInferenceState: SessionQueueSnapshot["workspaceInferenceState"] | null;
-    workspaceInferenceGeneration: number | null;
-    workspaceRunExceptionGeneration: number | null;
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
-    /** Delete a waiting prompt before the worker claims it. */
-    removeTurn: (turnId: string) => Promise<boolean>;
-    mutating: boolean;
-    mutationError: Error | null;
-    clearMutationError: () => void;
+type ChatComposerProps = {
+    composer: ComposerState;
+    /** Canonical workstream control, separate from lifecycle status. */
+    effectiveControl?: EffectiveSessionControl | null | undefined;
+    /** Waiting prompts already ahead of a normal Send. */
+    queuedAheadCount?: number | undefined;
+    /** Whether broader Workspace Resume is authorized for this viewer. */
+    canControlWorkspace?: boolean | undefined;
+    /** Optional host routes used to navigate from effective Pause blockers. */
+    controlLinks?: ComposerControlLinks | undefined;
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    autoFocus?: boolean | undefined;
+    /** Replaces the default keyboard hint under the field. */
+    hint?: string | undefined;
+    /** App controls in the footer row, replacing the hint. */
+    controlsStart?: ReactNode | undefined;
+    /** Provider-neutral speech capability. Provider configuration stays in workspace settings. */
+    transcription?: ComposerTranscriptionControlProps | undefined;
+    /** Content rendered above the textarea, inside the field chrome. */
+    header?: ReactNode | undefined;
+    /** Paste hook composed with the attachment paste path. */
+    onPaste?: ((event: ClipboardEvent<HTMLTextAreaElement>) => void) | undefined;
+    /** Opt-in file attachment state, typically from `useFileAttachments`. */
+    attachments?: UseFileAttachmentsResult | undefined;
+    /** Opt-in model picker choices. */
+    models?: ClientModel[] | undefined;
+    selectedModel?: string | undefined;
+    onSelectModel?: ((modelId: string) => void) | undefined;
+    className?: string | undefined;
+    commands?: readonly SlashCommand[] | undefined;
+    commandContext?: SlashCommandContext | undefined;
+    onClearView?: (() => void) | undefined;
+    /** Partial overrides for all composer-owned visible and accessible copy. */
+    messages?: Partial<ChatComposerMessages> | undefined;
 };
 /**
- * The single authoritative waiting-prompt queue. The server owns ordering; the
- * client renders the returned array verbatim and supports deletion only.
+ * Batteries-included chat composer. This preset is assembled exclusively from
+ * the public controller and compound primitives exported by the composer
+ * subpath, so custom and default layouts share one behavioral implementation.
  */
-declare function useTurnQueue(sessionId: string | null | undefined, options?: UseTurnQueueOptions): UseTurnQueueResult;
+declare function ChatComposer({ composer, effectiveControl, queuedAheadCount, canControlWorkspace, controlLinks, placeholder, disabled, autoFocus, hint, controlsStart, transcription, header, onPaste, attachments, models, selectedModel, onSelectModel, className, commands, commandContext, onClearView, messages, }: ChatComposerProps): react_jsx_runtime.JSX.Element;
 
 /** Event types that change the session goal (set/updated/completed/paused/...). */
 declare function isGoalEvent(event: Pick<SessionEvent, "type">): boolean;
@@ -822,27 +145,6 @@ type UseGoalResult = {
  */
 declare function useGoal(sessionId: string | null | undefined, options?: UseGoalOptions): UseGoalResult;
 
-type UseSessionControlOptions = ClientOverride;
-type UseSessionControlResult = {
-    pause: (reason?: string) => Promise<SessionEvent | null>;
-    resume: (reason?: string) => Promise<SessionEvent | null>;
-    controlling: boolean;
-    /** Approve a pending `requires_action` approval. */
-    approve: (approvalId: string, message?: string) => Promise<SessionEvent | null>;
-    /** Reject a pending `requires_action` approval. */
-    reject: (approvalId: string, message?: string) => Promise<SessionEvent | null>;
-    /** True while an approval decision is in flight. */
-    responding: boolean;
-    error: Error | null;
-    clearError: () => void;
-};
-/**
- * Session pause/resume and approval decisions. Pair with
- * `useSessionEvents` (for `session.requiresAction` payloads carrying the
- * `approvalId`) to render an approval bar.
- */
-declare function useSessionControl(sessionId: string | null | undefined, options?: UseSessionControlOptions): UseSessionControlResult;
-
 type UseScheduledTasksOptions = ClientOverride & {
     limit?: number | undefined;
     pollIntervalMs?: number | undefined;
@@ -874,6 +176,8 @@ type UseWorkspaceSessionsResult = {
     sessions: Session[];
     /** The complete personal pinned section, also present in `sessions`. */
     pinned: Session[];
+    /** True when the server omitted older pins from its bounded pinned section. */
+    pinnedTruncated: boolean;
     nextCursor: string | null;
     loading: boolean;
     error: Error | null;
@@ -1396,6 +700,30 @@ declare function useSandboxTerminal(sessionId: string | null | undefined, option
 
 /** The git-status overlay a file row may carry (tints modified files in the tree). */
 type FileTreeStatus = "added" | "modified" | "deleted" | "renamed" | "untracked";
+type CapturedFileUnavailableReason = "not-captured" | "too-large" | "content-missing";
+/** A cold capture can index a path without retaining its contents. Components
+ *  use this typed result to offer an explicit wake action instead of silently
+ *  turning passive review into a live sandbox read. */
+declare class CapturedFileUnavailableError extends Error {
+    readonly path: string;
+    readonly reason: CapturedFileUnavailableReason;
+    readonly code = "captured_file_unavailable";
+    constructor(path: string, reason: CapturedFileUnavailableReason);
+}
+declare class FileWriteConflictError extends Error {
+    readonly path: string;
+    readonly expectedContent: string;
+    readonly liveContent: string;
+    readonly code = "file_write_conflict";
+    constructor(path: string, expectedContent: string, liveContent: string);
+}
+type SandboxWriteFileOptions = {
+    /** Exact text loaded into the editor. The live file is re-read before write;
+     *  divergence fails closed with FileWriteConflictError. */
+    expectedContent?: string | undefined;
+    /** Deliberately bypass the expected-content guard after a visible conflict. */
+    force?: boolean | undefined;
+};
 /** A node in the Pierre file tree. `children === undefined` ⇒ an unexpanded dir
  *  (lazy treeMode); `children: []` ⇒ an expanded-but-empty dir. */
 type FileTreeNode = {
@@ -1424,11 +752,10 @@ type UseSandboxFilesOptions = ClientOverride & {
      *  (with no `fs.changed` event) never re-lists. Passing liveness re-lists when
      *  the box first becomes warm, so the tree populates as soon as the box is up. */
     liveness?: string | undefined;
-    /** The latest turn-end workspace capture (from `useWorkspaceCapture`). When the
-     *  box is NOT warm, the tree paints INSTANTLY from this capture's tree index (the
-     *  <200ms cold first paint) instead of blocking on a Channel-A list. A warm box
-     *  always wins (live path unchanged). On the cold→warm transition the live list
-     *  is merged in place — no remount, no flash (dossier §10.4 / §12-A1/D1). */
+    /** The latest turn-end workspace capture (from `useWorkspaceCapture`). The tree
+     *  paints immediately from this durable index, then a warm box reconciles live
+     *  in place. If that live read fails, the capture remains a truthful read-only
+     *  fallback instead of turning into an empty error surface. */
     capture?: WorkspaceCaptureManifest | null | undefined;
     /** Called when an OPTIMISTIC mutation is reverted because its background
      *  Channel-A op failed (e.g. a 409 rename collision). The host wires this to a
@@ -1444,11 +771,11 @@ type UseSandboxFilesResult = {
      *  spinner on these nodes so a 2-3s Channel-A list never looks frozen. */
     expandingPaths: Set<string>;
     /** Read a file for the preview pane (text or base64-for-binary, size-capped). */
-    readFile: (path: string) => Promise<FsReadResponse>;
+    readFile: (path: string, options?: OpenGeniRequestOptions) => Promise<FsReadResponse>;
     /** Write a file (overwrite, last-writer-wins) — the editor save path.
      *  Optimistic: a brand-new file is spliced into the tree immediately and the
      *  Channel-A write runs in the background; on failure the splice is reverted. */
-    writeFile: (path: string, content: string) => Promise<FsWriteResponse>;
+    writeFile: (path: string, content: string, options?: SandboxWriteFileOptions) => Promise<FsWriteResponse>;
     /** Create a new empty file (refuses to clobber an existing path: overwrite=false). */
     createFile: (path: string) => Promise<void>;
     /** Create a directory (recursive by default). */
@@ -1484,6 +811,9 @@ type UseSandboxGitOptions = ClientOverride & {
     events?: SessionEvent[] | undefined;
     /** Repo root within the workspace (multi-repo). Default: workspace root. */
     repoPath?: string | undefined;
+    /** All repository roots in the workspace. When supplied, status and diff are
+     *  aggregated into one workspace-wide result and paths are workspace-relative. */
+    repoPaths?: readonly string[] | undefined;
     /** Diff the staged index vs HEAD (`--cached`) instead of the working tree. */
     staged?: boolean | undefined;
     /** Hold off the initial fetch. Default true. */
@@ -1491,19 +821,29 @@ type UseSandboxGitOptions = ClientOverride & {
     /** Lease liveness ("warm" | "draining" | "cold"). When NOT warm, the diff is
      *  served from the capture (cold/offline) instead of a live `gitDiff` RPC. */
     liveness?: string | undefined;
-    /** The latest turn-end capture (from `useWorkspaceCapture`). Supplies the cold
-     *  diff for this repo. A warm box always wins (live `gitDiff` unchanged). */
+    /** The latest turn-end capture (from `useWorkspaceCapture`). Seeds the diff
+     *  immediately; a warm box reconciles live and leaves this durable review
+     *  surface in place if the live request is temporarily unavailable. */
     capture?: WorkspaceCaptureManifest | null | undefined;
 };
+/** A Git diff qualified into workspace scope. `repoRoot` is present for the
+ *  workspace-wide path and lets review UI group real repositories without
+ *  guessing from the first path segment. */
+type SandboxGitFileDiff = GitFileDiff & {
+    repoRoot?: string | undefined;
+};
 type UseSandboxGitResult = {
     /** Working-tree (or staged) diff vs HEAD — the structured hunks the Pierre
      *  diff view renders. */
-    diff: GitFileDiff[];
+    diff: SandboxGitFileDiff[];
     branch: string | null;
     /** Whether a repo is actually mounted (drives "no repository" vs "no changes"). */
     isRepo: boolean;
     ahead: number;
     behind: number;
+    /** Number and workspace-relative roots of repositories represented here. */
+    repoCount: number;
+    repoRoots: string[];
     refresh: () => Promise<void>;
     /** Which source the diff is served from: the live box or the turn-end capture. */
     source: "live" | "capture" | null;
@@ -1517,7 +857,7 @@ type UseSandboxGitResult = {
  * `GitFileDiff[]` (per-file hunks with per-line old/new numbers, rename
  * detection, binary flag, add/del counts) plus branch + ahead/behind. When the
  * box is warm the `git diff` runs in-box (API-direct); when it is cold/offline the
- * diff is served from the turn-end capture instead (dossier §10.4). Refreshes on
+ * diff is served from the turn-end capture instead. Refreshes on
  * `git.changed`; reconciles live in place on the cold→warm transition.
  */
 declare function useSandboxGit(sessionId: string | null | undefined, options?: UseSandboxGitOptions): UseSandboxGitResult;
@@ -1560,7 +900,7 @@ type UseWorkspaceCaptureResult = {
 /**
  * The cold-paint data source: fetch the latest turn-end workspace capture with a
  * SINGLE api round-trip on mount (no machine, no Channel-A — this is the <200ms
- * first paint, dossier §10.4/§12-A1). The manifest is served inline in the common
+ * first paint). The manifest is served inline in the common
  * case; a rare >2MB manifest comes back as a short-TTL signed URL we follow.
  *
  * Subscribes to the live event log: a `workspace.revision.captured` for a revision
@@ -1571,8 +911,8 @@ type UseWorkspaceCaptureResult = {
 declare function useWorkspaceCapture(sessionId: string | null | undefined, options?: UseWorkspaceCaptureOptions): UseWorkspaceCaptureResult;
 
 /**
- * The wake-on-edit state machine (dossier §3 #5 / §10.4 / §12-C). M3 OWNS this
- * logic; M5 renders it. States are explicit and exhaustive:
+ * The wake-on-edit state machine. This hook owns the logic and the UI renders
+ * its result. States are explicit and exhaustive:
  *
  *   viewing-cold      — cold snapshot open, no local edits (editable, cloud).
  *   buffering         — local edits buffered; the box is not warm and no warm is
@@ -1634,164 +974,462 @@ type UseWorkspaceEditResult = {
  * Cold-editing without a spinner: the editor opens instantly from the capture,
  * the first keystroke buffers locally AND signals the host to warm the box, and on
  * warm the buffer flushes IF the live file still matches the captured base — else a
- * non-blocking conflict is surfaced and nothing is overwritten (dossier §12-C2).
+ * non-blocking conflict is surfaced and nothing is overwritten.
+ *
+ * The base guard compares the live content at flush time against `baseContent`
+ * (the exact bytes the editor loaded). This is equivalent to the sha256 compare
+ * the design specifies — M1 leaves `baseHash` null, so the loaded content IS the
+ * authoritative base — and avoids async Web Crypto in the render path.
+ */
+declare function useWorkspaceEdit(sessionId: string | null | undefined, options?: UseWorkspaceEditOptions): UseWorkspaceEditResult;
+
+/** The one truthful machine indicator. Honest staleness beats
+ *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
+type MachineChipState = "live" | "waking" | "offline";
+type MachineChip = {
+    state: MachineChipState;
+    /** A ready-to-render label ("Live" / "Waking…" / "Offline — as of 3m ago"). */
+    label: string;
+    /** The capture time backing an offline/stale label (ISO), or null. M4 may
+     *  reformat this; `label` already embeds a relative form. */
+    asOf: string | null;
+};
+type DeriveMachineChipInput = {
+    /** `capabilities.liveness` — "warm" | "draining" | "cold" (or null pre-negotiation). */
+    liveness?: string | null | undefined;
+    /** `useSessionCapabilities().state` — drives the "waking" (negotiating) read. */
+    capabilitiesState?: SessionCapabilitiesState | null | undefined;
+    /** The ACTIVE machine's connection state (from `useMachines`), when known. A
+     *  self-hosted machine that is `offline` cannot be remotely woken. */
+    activeMachineState?: MachineState | null | undefined;
+    /** Whether the active sandbox is a user-owned self-hosted machine (no remote wake). */
+    activeIsSelfhosted?: boolean | undefined;
+    /** An interaction (wake-on-edit, terminal focus) is actively warming the box. */
+    wantsWarm?: boolean | undefined;
+    /** The latest capture's `capturedAt` (ISO) — the "as of <time>" backing. */
+    capturedAt?: string | null | undefined;
+    /** Injectable clock for deterministic relative labels (defaults to Date.now). */
+    now?: number | undefined;
+};
+/** Compact relative-time for the "as of" label. Pure, no Intl dependency. */
+declare function formatAsOf(capturedAt: string, now: number): string;
+/**
+ * Derive the machine-state chip from the live capability/liveness surface, the
+ * active machine's connection state, and the latest capture time. PURE (M4 renders
+ * it; the whole point is a deterministic, testable projection).
+ *
+ * Precedence:
+ *   1. warm/draining lease → **live** (a warm box always wins).
+ *   2. actively warming (negotiating, wake-on-edit, or a reconnecting/enrolling
+ *      machine) → **waking**.
+ *   3. everything else (a cold/asleep box, a self-hosted machine that's offline,
+ *      an error) → **offline**, labelled "as of <capture time>".
+ */
+declare function deriveMachineChip(input: DeriveMachineChipInput): MachineChip;
+type UseMachineChipOptions = DeriveMachineChipInput;
+/**
+ * Thin memoized wrapper over `deriveMachineChip` for the dock header (M4). The
+ * dock already runs `useSessionCapabilities` + `useMachines` + `useWorkspace
+ * capture`; it feeds their `liveness` / `state` / active-machine state /
+ * `capturedAt` here. Pass a periodically-updated `now` if you want the relative
+ * "as of" label to tick.
+ */
+declare function useMachineChip(input: UseMachineChipOptions): MachineChip;
+
+type ApprovalSurfaceMessages = {
+    title: string;
+    description: string;
+    approve: string;
+    reject: string;
+    approving: string;
+    rejecting: string;
+    formatToolName: (name: string) => string;
+};
+declare const defaultApprovalSurfaceMessages: ApprovalSurfaceMessages;
+type ApprovalSurfaceProps = {
+    approvals: PendingApproval[];
+    onApprove: (approval: PendingApproval) => void | Promise<void>;
+    onReject: (approval: PendingApproval) => void | Promise<void>;
+    responding?: boolean | undefined;
+    error?: string | Error | null | undefined;
+    messages?: Partial<ApprovalSurfaceMessages> | undefined;
+    renderApproval?: ((approval: PendingApproval) => ReactNode) | undefined;
+    className?: string | undefined;
+};
+/**
+ * Host-neutral approval presentation backed by the native pending-approval
+ * projection and control callbacks. It owns only presentation and duplicate
+ * click fencing; OpenGeni remains the authority for approval state.
+ */
+declare function ApprovalSurface({ approvals, onApprove, onReject, responding, error, messages: overrides, renderApproval, className, }: ApprovalSurfaceProps): react_jsx_runtime.JSX.Element | null;
+
+type HumanInputAnswerDraft = {
+    values: string[];
+    other: string;
+    otherSelected: boolean;
+};
+type HumanInputFormMessages = {
+    title: string;
+    description: string;
+    submit: string;
+    skip: string;
+    submitting: string;
+    other: string;
+    deadlineLabel: string;
+    formatDeadline: (value: string) => string;
+    required: string;
+    minLength: (count: number) => string;
+    maxLength: (count: number) => string;
+    otherRequired: string;
+    minSelections: (count: number) => string;
+    maxSelections: (count: number) => string;
+};
+declare const defaultHumanInputFormMessages: HumanInputFormMessages;
+type HumanInputFormProps = {
+    request: Pick<SessionHumanInputRequest, "id" | "questions" | "allowSkip" | "expiresAt">;
+    onSubmit: (response: SubmitHumanInputResponseRequest) => void | Promise<void>;
+    submitting?: boolean | undefined;
+    error?: string | null | undefined;
+    title?: ReactNode;
+    description?: ReactNode;
+    submitLabel?: string | undefined;
+    skipLabel?: string | undefined;
+    messages?: Partial<HumanInputFormMessages> | undefined;
+    autoFocus?: boolean | undefined;
+    className?: string | undefined;
+};
+/**
+ * Styled but host-neutral renderer for one structured request. Hosts can use
+ * the headless `useHumanInputRequests` hook instead, or replace the title and
+ * description while retaining accessible field semantics and validation.
+ */
+declare function HumanInputForm({ request, onSubmit, submitting, error, title, description, submitLabel, skipLabel, messages: messageOverrides, autoFocus, className, }: HumanInputFormProps): react_jsx_runtime.JSX.Element;
+declare function answersFromDrafts(questions: HumanInputQuestion[], drafts: Record<string, HumanInputAnswerDraft>, messageOverrides?: Partial<HumanInputFormMessages>): {
+    answers: HumanInputAnswer[];
+    errors: Record<string, string>;
+};
+
+type ToolRendererProps = {
+    item: ToolCallItem;
+};
+type ToolRenderer = ComponentType<ToolRendererProps>;
+/** A registry entry: which key it matches and the component that renders it. */
+type ToolRegistryEntry = {
+    match: "rawType";
+    type: string;
+    render: ToolRenderer;
+} | {
+    match: "name";
+    name: string;
+    render: ToolRenderer;
+};
+type ToolRegistry = {
+    /** Resolve the renderer for a call (never null — falls back to generic). */
+    resolve: (item: ToolCallItem) => ToolRenderer;
+    /** The generic fallback renderer. */
+    fallback: ToolRenderer;
+};
+type CreateToolRegistryOptions = {
+    /**
+     * Entries that take precedence over the built-ins. Earlier entries win, so a
+     * consumer can shadow a default renderer for the same key.
+     */
+    entries?: ToolRegistryEntry[] | undefined;
+    /** Replace the generic fallback used for unmatched tools. */
+    fallback?: ToolRenderer | undefined;
+};
+/** The `raw.type` of a projected tool call, when the provider item carries one. */
+declare function rawTypeOf(item: ToolCallItem): string | null;
+/**
+ * Build a tool registry from a set of entries and a fallback. The returned
+ * registry resolves in priority order: `raw.type` entries first, then `name`
+ * entries, then the fallback. Consumer `entries` are consulted before the
+ * built-in `baseEntries`, so they shadow defaults cleanly.
+ */
+declare function createToolRegistry(baseEntries: ToolRegistryEntry[], baseFallback: ToolRenderer, options?: CreateToolRegistryOptions): ToolRegistry;
+
+/** The built-in tool renderer registry: every first-party tool plus a fallback. */
+declare const defaultToolRegistry: ToolRegistry;
+/** Build a registry that extends the built-ins with consumer entries/fallback. */
+declare function createDefaultToolRegistry(options?: Parameters<typeof createToolRegistry>[2]): ToolRegistry;
+
+type ActivityRailProps = {
+    items: ActivityItem[];
+    /** Renderer registry for tool calls. Defaults to {@link defaultToolRegistry}. */
+    toolRegistry?: ToolRegistry | undefined;
+    /** Drill into a spawned worker session. */
+    onOpenSession?: ((sessionId: string) => void) | undefined;
+    /**
+     * Deep-link a memory row to its record in the host's memory pane. Opt-in: the
+     * library draws no "View in memory" affordance without a handler (the memory
+     * row is then non-interactive rich content). See {@link MessageTimelineProps}.
+     */
+    onMemoryClick?: ((memoryId: string) => void) | undefined;
+    /** Drop the left rule + indent (used inside a folded turn summary). */
+    bare?: boolean | undefined;
+    className?: string | undefined;
+};
+declare function ActivityRail({ items, toolRegistry, onOpenSession, onMemoryClick, bare, className, }: ActivityRailProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * A subtle settle signal — see the CHIP DOCTRINE above. The closed tone set.
+ * `"interrupted"` is a calm neutral tone for cancelled items — no dot, same
+ * quiet weight as `"muted"`, but semantically distinct from metadata.
+ */
+type DisclosureChip = {
+    tone: "ok" | "bad" | "muted" | "interrupted";
+    text: string;
+};
+type ActivityDisclosureProps = {
+    icon: ReactNode;
+    /** Icon tint. Defaults to the muted foreground; renderers pass accent/failed. */
+    iconTone?: "accent" | "failed" | "running" | "muted" | undefined;
+    title: ReactNode;
+    /** Render the title in the mono face (commands, paths). */
+    titleMono?: boolean | undefined;
+    /** Shimmer the title while the tool is in-flight. */
+    running?: boolean | undefined;
+    /**
+     * Quiet single-line secondary text (truncated). It is detail-on-demand: hidden
+     * when a media preview is set, AND hidden once the row is expanded (the body
+     * then owns the detail), so a stat/path never appears twice at once.
+     */
+    preview?: ReactNode | undefined;
+    /** A small inline media preview (a screenshot thumbnail) shown in place of `preview`. */
+    media?: ReactNode | undefined;
+    /** At most one quiet settle chip, right-aligned to the gutter. */
+    chip?: DisclosureChip | undefined;
+    /**
+     * When true the row carries the standard failure affordance: the icon is tinted
+     * red and a "failed" bad-chip appears in the right gutter (unless an explicit
+     * `chip` is already supplied — the caller's chip wins). Output is still visible
+     * on expand; this is a quiet status signal, not a blocking banner.
+     *
+     * Renderers should pass `failed={item.status === "failed"}` on their settled
+     * (non-running) paths so any tool with a failed status shows a consistent
+     * affordance without each renderer having to duplicate the logic.
+     */
+    failed?: boolean | undefined;
+    /**
+     * When true the row carries a calm "interrupted" affordance: the icon stays
+     * muted (no red) and a quiet "interrupted" chip appears in the right gutter
+     * (unless an explicit `chip` is already supplied — the caller's chip wins).
+     * This is the cancelled-status analogue of `failed`, but deliberately calm
+     * and neutral — it is NOT an error; the user chose to stop.
+     *
+     * Renderers should pass `cancelled={item.status === "cancelled"}` so any
+     * in-flight item that was interrupted on turn.cancelled reads consistently.
+     * `cancelled` is ignored when `failed` is also true (failure takes precedence).
+     */
+    cancelled?: boolean | undefined;
+    /** When false the row is a static line (no expand affordance). */
+    expandable?: boolean | undefined;
+    children?: ReactNode | undefined;
+};
+/**
+ * The one disclosure row shape every activity row reuses (tool calls, reasoning,
+ * sandbox ops): a chevron, a tinted icon, a title, an optional muted preview or
+ * inline media, and at most one right-gutter settle chip. Compact by default;
+ * the body mounts only when expanded.
+ */
+declare function ActivityDisclosure({ icon, iconTone: iconToneProp, title, titleMono, running, preview, media, chip: chipProp, failed, cancelled, expandable, children, }: ActivityDisclosureProps): react_jsx_runtime.JSX.Element;
+declare function TermBlock({ command, workdir, output, live, tailLines, failed, }: {
+    /**
+     * The command shown in the prompt header. Pass `null` when the row title
+     * already carries it (e.g. an exec row titled `$ cmd`): the header then drops
+     * the command — and the whole prompt line if there is no workdir either — so
+     * the command never reads twice, stacked, above the output.
+     */
+    command: string | null;
+    workdir?: string | null | undefined;
+    /** The FULL output. TermBlock owns the tail/full slicing internally. */
+    output: string;
+    live?: boolean | undefined;
+    /** A non-zero exit / failed call — tints the left accent red (the one hue). */
+    failed?: boolean | undefined;
+    /**
+     * When the output exceeds the tail window, only the last `tailLines` are shown
+     * with a "show full output" toggle. The component holds the full text, so the
+     * toggle reveals the rest (never a dead affordance). Defaults to 12.
+     */
+    tailLines?: number | undefined;
+}): react_jsx_runtime.JSX.Element;
+declare function PayloadBlock({ label, value, failed, }: {
+    label: string;
+    value: unknown;
+    failed?: boolean | undefined;
+}): react_jsx_runtime.JSX.Element | null;
+/** A quiet inline note inside an expanded body (lost output, empty frame, …). */
+declare function BodyNote({ children, tone, }: {
+    children: ReactNode;
+    tone?: "error" | "muted" | undefined;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * A loading screenshot placeholder. A faint camera glyph over a shimmering box,
+ * so a still frame of the running state reads unambiguously as "capturing" — not
+ * a broken thumbnail.
+ */
+declare function MediaSkeleton(): react_jsx_runtime.JSX.Element;
+/** A standardized "tool ran, produced no image" placeholder in the media slot. */
+declare function MediaEmpty(): react_jsx_runtime.JSX.Element;
+/**
+ * A small inline screenshot thumbnail that opens the app lightbox on click.
  *
- * The base guard compares the live content at flush time against `baseContent`
- * (the exact bytes the editor loaded). This is equivalent to the sha256 compare
- * the dossier describes — M1 leaves `baseHash` null, so the loaded content IS the
- * authoritative base — and avoids async Web Crypto in the render path.
+ * Requires a `LightboxProvider` ancestor for the click-to-expand affordance.
+ * Outside one it degrades to a plain, non-interactive image — never a dead
+ * "Expand" button that announces an action it cannot perform.
  */
-declare function useWorkspaceEdit(sessionId: string | null | undefined, options?: UseWorkspaceEditOptions): UseWorkspaceEditResult;
+declare function Thumbnail({ src, caption, alt, }: {
+    src: string;
+    caption?: string | undefined;
+    alt?: string;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * The expanded screenshot inside a tool body: a contained, clickable preview
+ * (opens the lightbox) with a quiet caption. Constrained height + object-contain
+ * so it never breaks the row layout. Like {@link Thumbnail}, it degrades to a
+ * plain image outside a `LightboxProvider`.
+ */
+declare function ScreenshotFigure({ src, caption, alt, }: {
+    src: string;
+    caption?: string | undefined;
+    alt?: string;
+}): react_jsx_runtime.JSX.Element;
 
-/** The one truthful machine indicator (dossier §3 #10). Honest staleness beats
- *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
-type MachineChipState = "live" | "waking" | "offline";
-type MachineChip = {
-    state: MachineChipState;
-    /** A ready-to-render label ("Live" / "Waking…" / "Offline — as of 3m ago"). */
-    label: string;
-    /** The capture time backing an offline/stale label (ISO), or null. M4 may
-     *  reformat this; `label` already embeds a relative form. */
-    asOf: string | null;
-};
-type DeriveMachineChipInput = {
-    /** `capabilities.liveness` — "warm" | "draining" | "cold" (or null pre-negotiation). */
-    liveness?: string | null | undefined;
-    /** `useSessionCapabilities().state` — drives the "waking" (negotiating) read. */
-    capabilitiesState?: SessionCapabilitiesState | null | undefined;
-    /** The ACTIVE machine's connection state (from `useMachines`), when known. A
-     *  self-hosted machine that is `offline` cannot be remotely woken. */
-    activeMachineState?: MachineState | null | undefined;
-    /** Whether the active sandbox is a user-owned self-hosted machine (no remote wake). */
-    activeIsSelfhosted?: boolean | undefined;
-    /** An interaction (wake-on-edit, terminal focus) is actively warming the box. */
-    wantsWarm?: boolean | undefined;
-    /** The latest capture's `capturedAt` (ISO) — the "as of <time>" backing. */
-    capturedAt?: string | null | undefined;
-    /** Injectable clock for deterministic relative labels (defaults to Date.now). */
-    now?: number | undefined;
+type LightboxController = {
+    open: (src: string, caption?: string) => void;
 };
-/** Compact relative-time for the "as of" label. Pure, no Intl dependency. */
-declare function formatAsOf(capturedAt: string, now: number): string;
+/** Open the app-level screenshot lightbox. No-op outside a `LightboxProvider`. */
+declare function useLightbox(): LightboxController;
 /**
- * Derive the machine-state chip from the live capability/liveness surface, the
- * active machine's connection state, and the latest capture time. PURE (M4 renders
- * it; the whole point is a deterministic, testable projection).
- *
- * Precedence:
- *   1. warm/draining lease → **live** (a warm box always wins).
- *   2. actively warming (negotiating, wake-on-edit, or a reconnecting/enrolling
- *      machine) → **waking**.
- *   3. everything else (a cold/asleep box, a self-hosted machine that's offline,
- *      an error) → **offline**, labelled "as of <capture time>".
+ * The lightbox controller when one is mounted, or `null` outside a
+ * `LightboxProvider`. Lets a media primitive degrade to a non-interactive image
+ * (rather than a dead "Expand" button that announces an action it cannot do).
  */
-declare function deriveMachineChip(input: DeriveMachineChipInput): MachineChip;
-type UseMachineChipOptions = DeriveMachineChipInput;
+declare function useLightboxOptional(): LightboxController | null;
 /**
- * Thin memoized wrapper over `deriveMachineChip` for the dock header (M4). The
- * dock already runs `useSessionCapabilities` + `useMachines` + `useWorkspace
- * capture`; it feeds their `liveness` / `state` / active-machine state /
- * `capturedAt` here. Pass a periodically-updated `now` if you want the relative
- * "as of" label to tick.
+ * The app-level screenshot lightbox. Render once near the timeline; renderers
+ * call `useLightbox().open(src)`.
+ *
+ * Idempotent by design: when an ancestor `LightboxProvider` already exists (e.g.
+ * a `MessageTimeline` mounted inside an app that already wraps its shell), this
+ * one becomes a pass-through and does NOT mount a second focus-trapping Dialog.
+ * That keeps `MessageTimeline` self-sufficient (it owns its own provider) while
+ * composing cleanly when nested.
  */
-declare function useMachineChip(input: UseMachineChipOptions): MachineChip;
-
-type PendingApproval = {
-    /** The id to send back via `user.approvalDecision` (`approvalId`). */
-    id: string;
-    /** Tool/function name awaiting the decision. */
-    name: string;
-    arguments?: unknown;
-    /** The raw approval entry from the `session.requiresAction` payload. */
-    raw?: unknown;
-};
-/** The approvals carried by one `session.requiresAction` payload. */
-declare function approvalsFromRequiresAction(payload: unknown): PendingApproval[];
-/** The approvals still awaiting a decision after replaying `events` in order. */
-declare function projectPendingApprovals(events: SessionEvent[]): PendingApproval[];
+declare function LightboxProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
 
 /**
- * The slash-command registry. A command is a SESSION / OPERATOR control — an
- * action on the session or the UI (clear, compact, pause the goal, show help) —
- * NOT a structured way to talk to the agent. The human↔agent channel stays
- * plain chat; the palette only recognizes a leading "/" and never sends a
- * command to the model.
- *
- * Two kinds, modeled by where the handler does its work:
- *  - CLIENT commands touch only the local UI (e.g. /help, /clear-view).
- *  - SERVER commands call the API through the SDK (e.g. /clear, /compact,
- *    /goal).
- * Both are just `run(args, ctx)`; `ctx` exposes the client for server commands
- * and the UI affordances (notice, openHelp, clearView, confirm) for both.
- */
-/** A positional argument a command accepts after its name. */
-type SlashArg = {
-    name: string;
-    /** Enter runs only once every required arg is present; otherwise autocompletes. */
-    required?: boolean;
-    /** Closed value set (rendered as a hint; validated by the command itself). */
-    oneOf?: readonly string[];
-    description?: string;
-};
-/** Transient feedback surfaced in the composer (generalized error line). */
-type Notice = {
-    tone: "ok" | "error";
-    message: string;
-};
-/** Everything a command handler can reach. Assembled by the composer. */
-type CommandContext = {
-    /** SDK-shaped client for server commands. */
-    client: SessionClientLike;
-    workspaceId: string;
-    /** Null before a session exists (server commands should guard on this). */
-    sessionId: string | null;
-    status: SessionStatus$1 | null;
-    /** The operator's permissions on this workspace (gates command visibility). */
-    permissions: Permission[];
-    /** Surface a transient ok/error notice in the composer. */
-    notice: (notice: Notice) => void;
-    /** Open the in-composer /help panel (rendered from the registry). */
-    openHelp: () => void;
+ * Seed the initial open state of every timeline collapsible below this node.
+ * Intended for screenshot/test instrumentation only; absent by default.
+ */
+declare function DisclosureDefaultsProvider({ defaultOpen, children, }: {
+    defaultOpen: boolean;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+type TurnSummaryProps = {
+    /** The activity items in the turn (used only to compute the facet counts). */
+    items: ActivityItem[];
     /**
-     * Reset only the LOCAL timeline view — no server call. Returns whether a
-     * view-reset affordance was actually wired (and thus had an effect): the host
-     * surface supplies one via the composer's `onClearView` prop, and consoles
-     * that don't (no resettable local timeline) get `false`. The /clear-view
-     * command uses this to avoid reporting a false "cleared" success on a no-op.
+     * The settled verdict — or absent for a completed CLUSTER of a still-running
+     * turn, which folds neutrally: no verdict glyph (the turn has none yet), a
+     * quiet pulse dot in its place so alignment and the running feel both hold.
      */
-    clearView: () => boolean;
-    /** Show the danger confirm bar; resolves true once the operator confirms. */
-    confirm: () => Promise<boolean>;
-};
-type CommandResult = {
-    status: "ok" | "error";
-    message?: string;
+    outcome?: TurnOutcome | undefined;
+    /** A short failure reason shown inline on a failed chip (never hidden). */
+    failureText?: string | undefined;
+    /** Elapsed turn duration; shown as a trailing facet when at least 1s. */
+    durationMs?: number | undefined;
+    /** Start expanded. */
+    defaultOpen?: boolean | undefined;
     /**
-     * Keep the composer draft instead of clearing it on an ok result. Used when a
-     * command resolves to a no-op the operator may want to retry — e.g. canceling
-     * the /clear confirm bar returns ok (no error) but must NOT wipe the typed
-     * "/clear" draft. Default false: a successful command clears the draft.
+     * A nested fold — a cluster or sub-turn INSIDE an already-expanded turn. It
+     * drops the bordered/filled chip and renders as a plain disclosure node on the
+     * parent's rail (chevron + glyph + facets), so expanding a turn reveals a thread
+     * of nodes, never a stack of boxes-in-boxes. The top-level fold stays a chip.
      */
-    keepDraft?: boolean;
+    bare?: boolean | undefined;
+    /** The rendered activity rail revealed on expand. */
+    children: React.ReactNode;
 };
-type SlashCommand = {
-    /** Primary token after the slash (no leading "/"). */
-    name: string;
-    /** Alternate tokens that resolve to this command. */
-    aliases?: readonly string[];
-    description: string;
-    args?: readonly SlashArg[];
-    /** Required permission; the command is hidden from the palette without it. */
-    permission?: Permission;
-    /** Destructive — the palette shows a confirm bar before running. */
-    danger?: boolean;
+declare function TurnSummary({ items, outcome, failureText, durationMs, defaultOpen, bare, children, }: TurnSummaryProps): react_jsx_runtime.JSX.Element;
+
+/** Recover the exit code from a sandbox exec banner (`Process exited with code N`). */
+declare function sandboxCommandExitCode(out: unknown): number | null;
+/**
+ * Recover the numeric exec-session id the sandbox embeds for a STILL-RUNNING
+ * (backgrounded) process (`Process running with session ID N`). A finished
+ * command emits `Process exited with code N` instead, which yields `null`.
+ */
+declare function parseExecBannerSessionId(out: unknown): number | null;
+/** Strip the exec banner (`Chunk ID ...\n...\nOutput:\n`) down to the command's stdout. */
+declare function stripExecBanner(out: unknown): string;
+/** The sandbox clamped the output (token/line truncation markers in the banner). */
+declare function execTruncated(out: unknown): boolean;
+/** A `write_stdin` whose target PTY vanished (`write_stdin failed: session not found: N`). */
+declare function isExecSessionLostBanner(out: unknown): boolean;
+/** True when the exec stdout looks binary/garbled (a NUL byte or ELF magic). */
+declare function looksBinary(text: string): boolean;
+/**
+ * Render unprintable control characters as caret notation (0x03 -> `^C`) so a
+ * `write_stdin` keystroke payload reads cleanly in the row title.
+ */
+declare function controlCaret(printable: string): string;
+/** One operation inside an `apply_patch_call` (a V4A file edit). */
+type ApplyPatchOperation = {
     /**
-     * Dynamic availability beyond the permission gate (e.g. hide a server command
-     * until a session exists). Returning false hides the command.
+     * The V4A op kind. The three canonical values are `create_file`,
+     * `update_file`, and `delete_file`; the open `string` tail tolerates a
+     * forward-compatible/unknown op kind from the provider without a type error
+     * (it falls through to the "Edited" treatment).
      */
-    available?: (ctx: Pick<CommandContext, "sessionId" | "status" | "permissions">) => boolean;
-    /** Execute the command. Throwing is caught and surfaced as an error notice. */
-    run: (args: string[], ctx: CommandContext) => Promise<CommandResult> | CommandResult;
+    type: "create_file" | "update_file" | "delete_file" | (string & {});
+    path: string;
+    /** Rename target -- when present the op is a move/rename. */
+    moveTo?: string | null | undefined;
+    /** The V4A hunk string (`@@ ...` lines with `+`/`-`/context prefixes). */
+    diff?: string | undefined;
+};
+/**
+ * Parse a single V4A `apply_patch` operation into the SDK's `GitFileDiff` shape
+ * so it can flow into the SAME `DiffView` / `PierreDiff` the Files tab uses.
+ * Throws on a hunk string it cannot structure (no `@@` anchor on an update); the
+ * renderer catches and falls back to a raw-patch view.
+ */
+declare function v4aToGitFileDiff(op: ApplyPatchOperation): GitFileDiff;
+/**
+ * Extract the `apply_patch` operations from a provider-native tool item's `raw`
+ * payload, normalizing the two wire shapes (`raw.operations[]` for a multi-file
+ * patch, `raw.operation` for a single op). The single owner of this shape so the
+ * renderer and the turn-summary facet counter never drift.
+ */
+declare function applyPatchOps(raw: unknown): ApplyPatchOperation[];
+/**
+ * True when a tool item is an `apply_patch_call` — by its provider-native
+ * `raw.type` (the live-wire source of truth) or by tool `name` (first-party
+ * replays that omit `raw`). Centralizes the rawType-or-name check.
+ */
+declare function isApplyPatch(item: {
+    name: string;
+    raw: unknown;
+}): boolean;
+/** Deep-redact secret-looking values so arguments never leak a key into the UI. */
+declare function redactSecrets(value: unknown): unknown;
+/** Parse tool arguments that may arrive as a JSON string or an object. */
+declare function parseToolArgs(args: unknown): Record<string, unknown>;
+/** The last non-empty line of a string -- the compact "what happened" peek. */
+declare function tailPeek(text: string): string;
+/**
+ * Unwrap an MCP tool result (`{ content: [{ type: "text", text }], isError? }`)
+ * into a flat `{ text, isError }`. Non-MCP outputs pass through as their string
+ * form.
+ */
+declare function unwrapMcpOutput(output: unknown): {
+    text: string;
+    isError: boolean;
 };
 
 /**
@@ -1833,71 +1471,6 @@ declare function firstMissingRequiredArg(command: SlashCommand, args: string[]):
  */
 declare const defaultCommands: readonly SlashCommand[];
 
-/**
- * Context the composer supplies for command execution and visibility. The
- * composer owns the UI affordances (notice/openHelp/clearView/confirm), so they
- * are NOT part of this slice — the hook closes over them via `handlers`.
- */
-type SlashCommandContext = Pick<CommandContext, "client" | "workspaceId" | "sessionId" | "status" | "permissions">;
-/**
- * UI affordances the composer supplies. `confirm` differs from the registry-
- * facing {@link CommandContext.confirm} (which takes no args): the composer's
- * confirm receives the command being run so the confirm bar renders from that
- * exact command's identity. The hook bridges the two in {@link buildContext}.
- */
-type SlashCommandHandlers = Pick<CommandContext, "notice" | "openHelp" | "clearView"> & {
-    confirm: (command: SlashCommand) => Promise<boolean>;
-};
-type ConfirmState = {
-    command: SlashCommand;
-    /** Resolve the pending confirm() promise. */
-    resolve: (confirmed: boolean) => void;
-} | null;
-type UseSlashCommandsOptions = {
-    commands: readonly SlashCommand[];
-    context: SlashCommandContext | undefined;
-    handlers: SlashCommandHandlers;
-    /** The current composer draft. */
-    value: string;
-    /** Replace the composer draft (autocomplete writes through this). */
-    setValue: (value: string) => void;
-};
-type UseSlashCommandsResult = {
-    /** Whether the palette is open (a command token is being typed). */
-    open: boolean;
-    /**
-     * Whether the draft is a slash-command attempt (matches a registered command)
-     * — true even after Escape dismisses the popover. The composer blocks its send
-     * path while this holds so a command can't be delivered to the agent as chat.
-     */
-    isCommandDraft: boolean;
-    /** Commands shown for the current token + context, in display order. */
-    items: SlashCommand[];
-    /** Index into `items` of the highlighted row. */
-    highlight: number;
-    setHighlight: (index: number) => void;
-    /** The matched command once the name is closed by a space (arg-hint mode). */
-    activeCommand: SlashCommand | null;
-    /** The arg hint string for the active command (footer), or "". */
-    activeArgHint: string;
-    /**
-     * Key handler for the textarea. Returns true when it consumed the event
-     * (the composer must then NOT run its send path). Only consumes while open.
-     */
-    onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => boolean;
-    /** Run the highlighted command (or the active command in arg-hint mode). */
-    runHighlighted: () => Promise<void>;
-    /**
-     * Run the command at an explicitly chosen index (a pointer click on a row).
-     * Bypasses the exact-match token heuristic that runHighlighted uses for
-     * keyboard Enter, so an explicit click always runs the clicked command.
-     */
-    runAt: (index: number) => Promise<void>;
-    /** Autocomplete the highlighted command name + a trailing space. */
-    autocompleteHighlighted: () => void;
-};
-declare function useSlashCommands(options: UseSlashCommandsOptions): UseSlashCommandsResult;
-
 type CommandPaletteProps = {
     open: boolean;
     items: SlashCommand[];
@@ -1910,6 +1483,10 @@ type CommandPaletteProps = {
     argHintText: string;
     /** id used for aria-activedescendant wiring from the textarea. */
     listboxId: string;
+    /** Accessible list label. Defaults to "Slash commands". */
+    label?: string | undefined;
+    /** Badge shown for destructive commands. Defaults to "danger". */
+    dangerLabel?: string | undefined;
 };
 /**
  * The slash-command palette: a popover anchored above the textarea, rendered
@@ -1917,73 +1494,7 @@ type CommandPaletteProps = {
  * the opengeni#46 design tokens. Full keyboard nav lives in useSlashCommands;
  * this component is presentational + aria.
  */
-declare function CommandPalette({ open, items, highlight, onHighlight, onRun, argHintText, listboxId, }: CommandPaletteProps): react_jsx_runtime.JSX.Element;
-
-type ChatComposerProps = {
-    composer: ComposerState;
-    /** Current session status; shows the stop control while a turn runs. */
-    status?: SessionStatus$1 | null | undefined;
-    placeholder?: string | undefined;
-    disabled?: boolean | undefined;
-    autoFocus?: boolean | undefined;
-    /** Replaces the default keyboard hint under the field. */
-    hint?: string | undefined;
-    /** App controls (model picker, attach button, ...) in the footer row, replacing the hint. */
-    controlsStart?: ReactNode | undefined;
-    /** Content rendered above the textarea, inside the field chrome (e.g. attachment chips). */
-    header?: ReactNode | undefined;
-    /** Paste hook on the textarea (e.g. paste-image-to-attach). */
-    onPaste?: ((event: ClipboardEvent<HTMLTextAreaElement>) => void) | undefined;
-    /**
-     * Opt-in file attachments. When supplied (e.g. from {@link useFileAttachments}),
-     * the composer renders a built-in attach button (prepended to `controlsStart`),
-     * an attachment-chips strip (above the textarea, before any host `header`),
-     * routes paste through `addFromPaste` (image/* filter lives in the hook), and
-     * gates send while `uploading` so a message never departs without its files.
-     * Absent → no attachment UI renders and the composer behaves exactly as before.
-     */
-    attachments?: UseFileAttachmentsResult | undefined;
-    /**
-     * Opt-in model picker. When supplied (e.g. from {@link useAvailableModels}),
-     * the composer renders a {@link ModelPicker} at the start of `controlsStart`
-     * so the operator can choose which host-exposed model serves the next message.
-     * The host owns the selection (`selectedModel`/`onSelectModel`) and is
-     * responsible for threading it into the composer's `sendExtras` (typically
-     * `useComposer({ sendExtras: () => ({ model }) })`) so `composeSendInput`
-     * carries it. Absent → no picker renders and the composer behaves as before.
-     */
-    models?: ClientModel[] | undefined;
-    /** The currently selected model id (the picker's controlled value). */
-    selectedModel?: string | undefined;
-    /** Called with the chosen model id when the operator picks one. */
-    onSelectModel?: ((modelId: string) => void) | undefined;
-    className?: string | undefined;
-    /**
-     * Slash-command palette. Defaults to the built-in {@link defaultCommands};
-     * apps concat their own. Backward-compatible: when `commandContext` is absent
-     * the palette is inert and behavior is identical to before.
-     */
-    commands?: readonly SlashCommand[] | undefined;
-    /**
-     * Wiring the palette needs to run server commands and gate visibility. The
-     * composer supplies notice/openHelp/clearView/confirm internally.
-     */
-    commandContext?: SlashCommandContext | undefined;
-    /** Reset the local timeline view (the /clear-view command target). */
-    onClearView?: (() => void) | undefined;
-};
-/**
- * The chat composer — the only human-to-agent input surface. Plain chat in,
- * everything else is the agent's job. Enter sends, Shift+Enter breaks the
- * line, and the stop control appears while a turn is running (sending while
- * running is legitimate steering, so send stays available too).
- *
- * Typing a leading "/" opens the slash-command palette — SESSION/OPERATOR
- * controls (clear, compact, pause goal, help), never a structured channel to
- * the agent. The palette is purely additive: with no `commandContext` it is
- * inert and the composer behaves exactly as before.
- */
-declare function ChatComposer({ composer, status, placeholder, disabled, autoFocus, hint, controlsStart, header, onPaste, attachments, models, selectedModel, onSelectModel, className, commands, commandContext, onClearView, }: ChatComposerProps): react_jsx_runtime.JSX.Element;
+declare function CommandPalette({ open, items, highlight, onHighlight, onRun, argHintText, listboxId, label, dangerLabel, }: CommandPaletteProps): react_jsx_runtime.JSX.Element;
 
 type ModelPickerProps = {
     /** The host-exposed models to choose from (typically {@link useAvailableModels}). */
@@ -1994,6 +1505,8 @@ type ModelPickerProps = {
     onChange: (modelId: string) => void;
     disabled?: boolean | undefined;
     className?: string | undefined;
+    /** Visible-to-assistive-technology label. Defaults to "Model". */
+    label?: string | undefined;
 };
 /**
  * The model picker — a compact dropdown for the composer footer, grouping the
@@ -2006,7 +1519,7 @@ type ModelPickerProps = {
  * the send path. Renders nothing when no models are exposed, so a single-model
  * deployment shows no chrome.
  */
-declare function ModelPicker({ models, value, onChange, disabled, className }: ModelPickerProps): react_jsx_runtime.JSX.Element | null;
+declare function ModelPicker({ models, value, onChange, disabled, className, label, }: ModelPickerProps): react_jsx_runtime.JSX.Element | null;
 
 type MessageTimelineProps = {
     /** Raw session events (projected internally) … */
@@ -2290,7 +1803,8 @@ type FileBrowserProps = {
     editable?: boolean | undefined;
     /**
      * Confirm a (recursive) delete before it runs. Return `false` to cancel.
-     * Defaults to `window.confirm`. Pass a no-op returning `true` to skip.
+     * The default is an accessible, non-blocking confirmation dialog. Supply this
+     * callback to delegate confirmation to a host-owned dialog.
      */
     confirmDelete?: ((node: FileTreeNode) => boolean | Promise<boolean>) | undefined;
     className?: string | undefined;
@@ -2420,6 +1934,10 @@ type CodeEditorProps = {
     initialContents: string;
     /** Persist the current buffer. Resolves when the write lands; rejects to surface an error. */
     onSave: (contents: string) => Promise<unknown>;
+    /** Explicitly overwrite after a visible expected-content conflict. */
+    onOverwrite?: ((contents: string) => Promise<unknown>) | undefined;
+    /** Re-read the selected file after a visible save conflict. */
+    onReload?: (() => void) | undefined;
     /** Fired once when the buffer FIRST diverges from its baseline (the first real
      *  keystroke) — the wake-on-edit intent. The host warms the box on this so the
      *  eventual save lands fast; merely opening the file for reading never fires it. */
@@ -2445,7 +1963,7 @@ type CodeEditorProps = {
  * `readOnly` suppresses every mutation path so a truncated/binary file can never
  * be saved back (which would corrupt it by writing the truncated prefix).
  */
-declare function CodeEditor({ path, initialContents, onSave, onEditIntent, readOnly, themeType, loading, fallback, className, }: CodeEditorProps): react_jsx_runtime.JSX.Element;
+declare function CodeEditor({ path, initialContents, onSave, onOverwrite, onReload, onEditIntent, readOnly, themeType, loading, fallback, className, }: CodeEditorProps): react_jsx_runtime.JSX.Element;
 
 type SandboxFilesProps = {
     /** From `useSandboxFiles(...)`. */
@@ -2466,6 +1984,23 @@ type SandboxFilesProps = {
      *  dock warms the box on this so the save lands fast; opening/reading never fires
      *  it. Browsing the tree/diff must not warm a box. */
     onEditIntent?: (() => void) | undefined;
+    /** A guarded diff path routed here by the parent workspace. */
+    requestedPath?: string | undefined;
+    /** Identity for one guarded-file request. Increment this when the same path is
+     *  deliberately requested again; it also lets a pending request be consumed
+     *  without overriding later manual tree navigation. Defaults to the path. */
+    requestedPathRequestId?: string | number | undefined;
+    /** False while the parent is waking a cold sandbox for `requestedPath`. */
+    requestedPathReady?: boolean | undefined;
+    /** The machine is cold and no durable capture exists yet. Render an explicit
+     *  wake gate instead of an empty-tree lie or an implicit Channel-A read. */
+    workspaceResting?: boolean | undefined;
+    /** A deliberate wake has started but the live file surface is not ready yet. */
+    workspaceWaking?: boolean | undefined;
+    /** Whether live reads are currently authoritative. */
+    liveWorkspaceReady?: boolean | undefined;
+    /** Deliberately wake the machine to read content absent from the capture. */
+    onWakeWorkspace?: (() => void) | undefined;
     themeType?: "dark" | "light" | undefined;
     className?: string | undefined;
 };
@@ -2476,7 +2011,7 @@ type SandboxFilesProps = {
  * surface deliberately does NOT replicate the changed-files list, and does not
  * diff here — one job per tab). The agent commits; the human reviews.
  */
-declare function SandboxFiles({ files, git, fileSystemAvailable, usePierre, editable, onEditIntent, themeType, className, }: SandboxFilesProps): react_jsx_runtime.JSX.Element;
+declare function SandboxFiles({ files, git, fileSystemAvailable, usePierre, editable, onEditIntent, requestedPath, requestedPathRequestId, requestedPathReady, workspaceResting, workspaceWaking, liveWorkspaceReady, onWakeWorkspace, themeType, className, }: SandboxFilesProps): react_jsx_runtime.JSX.Element;
 
 type DesktopViewerProps = {
     /** The desktop cell of the negotiated capabilities (`capabilities.DesktopStream`). */
@@ -2604,21 +2139,30 @@ type WorkspaceNotification = {
 /** The workbench's canonical tab ids (a host injects extras around these). */
 declare const WORKBENCH_TAB_CHANGES = "changes";
 declare const WORKBENCH_TAB_FILES = "files";
+declare const WORKBENCH_TAB_TERMINAL = "terminal";
+declare const WORKBENCH_TAB_DESKTOP = "desktop";
+/**
+ * The built-in workbench surfaces in their canonical display order. Hosts can
+ * pass a subset through `surfaces`; omission preserves the complete standalone
+ * workbench.
+ */
+declare const WORKBENCH_SURFACES: readonly ["changes", "files", "terminal", "desktop"];
+type SandboxWorkspaceSurface = (typeof WORKBENCH_SURFACES)[number];
 /**
  * Decide a workspace tab from an already-local event log: the newest
  * `workspace.revision.captured` announce carries the change surface stats, so
  * "changes exist → Changes, else Files" needs zero machine round-trips. A host
  * `override` (e.g. a landing "run" tab) wins when supplied.
  *
- * NOTE: the dock no longer uses this for its default tab — `<SandboxWorkspace>`
- * now derives the default from its OWN capture fetch (`useWorkspaceCapture`'s
- * `fileCount`), so a pure embedder needs no events-at-mount contract (Refinement
- * 2). This remains exported as a standalone helper for hosts that already hold
- * the event log and want the same decision without the capture fetch.
+ * `<SandboxWorkspace>` uses this only as an optional early hint after its own
+ * capture GET reports no durable capture. A pure embedder needs no events-at-mount
+ * contract: it falls through to authoritative live Git instead.
  */
 declare function initialWorkspaceTab(events: SessionEvent[] | undefined, override?: string | null): string;
 type WorkspaceMachine = {
-    /** The derived live/waking/offline chip model (dossier §3 #10). */
+    /** Whether at least one built-in workbench surface is enabled. */
+    enabled: boolean;
+    /** The derived live/waking/offline chip model. */
     chip: MachineChip;
     /** The machine these surfaces are bound to (the Modal group box or a
      *  self-hosted machine), or null while the fleet is still resolving. */
@@ -2631,21 +2175,34 @@ type UseSandboxWorkspaceTabsOptions = ClientOverride & {
     sessionId: string;
     /** Live event log (usually `useSessionEvents().events`). */
     events: SessionEvent[];
-    /** Override the capture-driven default tab (e.g. a host landing tab id). When
-     *  omitted the workbench picks Changes-vs-Files from its own capture fetch. */
+    /**
+     * Built-in surfaces this host wants to expose. Omit for all four. A disabled
+     * surface is behaviorally dormant: its data hooks, warm intents, stream
+     * attachment, and navigation callbacks are not activated.
+     */
+    surfaces?: readonly SandboxWorkspaceSurface[] | undefined;
+    /** Override the source-driven default tab (e.g. a host landing tab id). When
+     *  omitted the workbench picks Changes-vs-Files from capture or live Git. */
     initialTab?: string | null | undefined;
     /** Host-routed notifications (mutation errors, desktop-consent failures). The
      *  package never imports a toast library — the host decides how to surface. */
     onNotify?: ((notification: WorkspaceNotification) => void) | undefined;
+    /** File requested by a Changes guard. The Files surface defers the read until
+     *  the sandbox is live, then reveals this path. */
+    requestedFilePath?: string | null | undefined;
+    /** Unique identity for `requestedFilePath`, including repeated requests for the
+     *  same path. */
+    requestedFileRequestId?: string | number | null | undefined;
+    /** Route a guarded diff into the host's Files tab. */
+    onOpenFile?: ((path: string) => void) | undefined;
 };
 type UseSandboxWorkspaceTabsResult = {
     /** Changes | Files | Terminal | Desktop (capability-gated where noted). */
     tabs: WorkspaceTab[];
-    /** The capture-driven default tab: Changes when the session has changes, else
-     *  Files (a host `initialTab` overrides). null during the brief window before the
-     *  capture GET first resolves (and no host override was given) — consumers render
-     *  their dock's own first-tab fallback until it latches, which it does ONCE, so it
-     *  never causes a post-render switch. */
+    /** The source-driven default tab: Changes when the first authoritative capture
+     *  or live Git result has changes, else Files (a host `initialTab` overrides).
+     *  null while that source resolves, or permanently when neither Changes nor
+     *  Files is enabled; the choice latches once. */
     defaultTab: string | null;
     /** The machine-state model for the dock-header chip. */
     machine: WorkspaceMachine;
@@ -2662,12 +2219,17 @@ type SandboxWorkspaceProps = ClientOverride & {
     events: SessionEvent[];
     /** The chat / primary pane shown beside the dock. */
     primary: ReactNode;
+    /**
+     * Built-in surfaces this host wants to expose. Omit for Changes, Files,
+     * Terminal, and Desktop. Disabled surfaces remain behaviorally dormant.
+     */
+    surfaces?: readonly SandboxWorkspaceSurface[] | undefined;
     /** Host tabs injected BEFORE the workbench tabs (e.g. a "Run" landing tab). */
     leadingTabs?: WorkspaceTab[] | undefined;
     /** Host tabs injected AFTER the workbench tabs (e.g. a "Debug" tab). */
     trailingTabs?: WorkspaceTab[] | undefined;
     /** Override the pre-paint default tab (e.g. a host landing tab id). When
-     *  omitted the workbench decides Changes-vs-Files from local capture stats. */
+     *  omitted the workbench decides from capture, then live Git when no capture exists. */
     initialTab?: string | undefined;
     /** Host-routed notifications (no toast dependency in the package). */
     onNotify?: ((notification: WorkspaceNotification) => void) | undefined;
@@ -2823,4 +2385,4 @@ declare function isCreditExhaustion(input: {
  */
 declare function humanizeFailureReason(reason: string | null): string | null;
 
-export { ActivityDisclosure, type ActivityDisclosureProps, type ActivityItem, ActivityRail, type ActivityRailProps, type AgentMessageItem, type ApplyPatchOperation, type AuthNeededItem, BodyNote, CREDIT_EXHAUSTION_MESSAGE, ChatComposer, type ChatComposerProps, ClientOverride, CodeEditor, type CodeEditorProps, type CodexAccountsClientLike, type CommandContext, CommandPalette, type CommandPaletteProps, type CommandResult, type ComposerMode, type ComposerSendExtras, type ComposerState, type ConfirmState, type CreateToolRegistryOptions, type DeriveMachineChipInput, DesktopViewer, type DesktopViewerProps, type DesktopWebSocketFactory, type DesktopWebSocketLike, type DiffTheme, DiffView, type DiffViewProps, type DisclosureChip, DisclosureDefaultsProvider, FILE_ONLY_MESSAGE_TEXT, type FileAttachment, FileBrowser, type FileBrowserProps, type FileTreeNode, type FileTreeStatus, FleetTile, type FleetTileProps, type GoalItem, LightboxProvider, type MachineChip, type MachineChipState, Markdown, type MarkdownProps, MediaEmpty, MediaSkeleton, MessageTimeline, type MessageTimelineProps, ModelPicker, type ModelPickerProps, type Notice, type NoticeItem, type ParsedCommandLine, PayloadBlock, type PendingApproval, PierreDiff, type PierreDiffProps, PierreFile, type PierreFileProps, type ReasoningItem, SESSION_STATUS_META, SandboxFiles, type SandboxFilesProps, type SandboxItem, SandboxTerminal, type SandboxTerminalProps, SandboxWorkspace, type SandboxWorkspaceProps, ScreenshotFigure, type SessionCapabilitiesState, SessionClientLike, type SessionEventsConnectionState, SessionStatus, type SessionStatusItem, type SessionStatusMeta, type SessionStatusProps, type SlashArg, type SlashCommand, type SlashCommandContext, type SlashCommandHandlers, StatusDot, type StatusDotProps, TermBlock, type TerminalChunk, type TerminalStreamStatus, Thumbnail, type TimelineGroup, type TimelineItem, TimelineRow, type ToolCallItem, type ToolRegistry, type ToolRegistryEntry, type ToolRenderer, type ToolRendererProps, type TurnEndItem, type TurnOutcome, TurnSummary, type TurnSummaryProps, type UseAvailableModelsOptions, type UseAvailableModelsResult, type UseBillingUsageOptions, type UseBillingUsageResult, type UseCodexAccountsOptions, type UseCodexAccountsResult, type UseComposerOptions, type UseDesktopStreamOptions, type UseDesktopStreamResult, type UseEnvironmentsOptions, type UseEnvironmentsResult, type UseFileAttachmentsOptions, type UseFileAttachmentsResult, type UseGoalOptions, type UseGoalResult, type UseMachineChipOptions, type UsePacksOptions, type UsePacksResult, type UseRelayFrameStreamOptions, type UseRelayFrameStreamResult, type UseRigChangesOptions, type UseRigChangesResult, type UseRigOptions, type UseRigResult, type UseRigVersionsOptions, type UseRigVersionsResult, type UseRigsOptions, type UseRigsResult, type UseSandboxFilesOptions, type UseSandboxFilesResult, type UseSandboxGitOptions, type UseSandboxGitResult, type UseSandboxTerminalOptions, type UseSandboxTerminalResult, type UseSandboxWorkspaceTabsOptions, type UseSandboxWorkspaceTabsResult, type UseScheduledTasksOptions, type UseScheduledTasksResult, type UseSessionCapabilitiesOptions, type UseSessionCapabilitiesResult, type UseSessionControlOptions, type UseSessionControlResult, type UseSessionEventsOptions, type UseSessionEventsResult, type UseSessionLineageOptions, type UseSessionLineageResult, type UseSessionOptions, type UseSessionResult, type UseSlashCommandsOptions, type UseSlashCommandsResult, type UseTerminalStreamOptions, type UseTerminalStreamResult, type UseTurnQueueOptions, type UseTurnQueueResult, type UseVariableSetsOptions, type UseVariableSetsResult, type UseWorkspaceCaptureOptions, type UseWorkspaceCaptureResult, type UseWorkspaceEditOptions, type UseWorkspaceEditResult, type UseWorkspaceSessionsOptions, type UseWorkspaceSessionsResult, type UseWorkspacesOptions, type UseWorkspacesResult, type UserMessageItem, WORKBENCH_TAB_CHANGES, WORKBENCH_TAB_FILES, type WorkerItem, WorkspaceDock, type WorkspaceDockProps, type WorkspaceEditConflict, type WorkspaceEditState, type WorkspaceMachine, type WorkspaceNotification, type WorkspaceTab, type XtermTheme, applyPatchOps, approvalsFromRequiresAction, argHint, buildTimeline, cn, composeSendInput, controlCaret, createDefaultToolRegistry, createToolRegistry, creditExhaustedFromEvents, defaultCommands, defaultToolRegistry, deriveMachineChip, execTruncated, extractSessionRef, filterCommands, firstMissingRequiredArg, formatAsOf, formatBytes, formatRelativeTime, gitFileDiffToPatch, groupTimeline, hasPermission, humanizeFailureReason, initialWorkspaceTab, isApplyPatch, isCodexAccountEvent, isCreditExhaustion, isExecSessionLostBanner, isGoalEvent, isLineageRefreshEvent, isTitleEvent, isTurnQueueEvent, languageForPath, looksBinary, matchCommand, parseCommandLine, parseExecBannerSessionId, parseToolArgs, projectPendingApprovals, rawTypeOf, redactSecrets, sandboxCommandExitCode, sessionDisplayTitle, sessionStatusFromEvents, shouldSubmitOnKey, stringifyPayload, stripExecBanner, tailPeek, toolDisplayName, truncate, tryParseJson, unwrapMcpOutput, useAvailableModels, useBillingUsage, useCodexAccounts, useComposer, useDesktopStream, useEnvironments, useFileAttachments, useGoal, useLightbox, useLightboxOptional, useMachineChip, usePacks, useRelayFrameStream, useRig, useRigChanges, useRigVersions, useRigs, useSandboxFiles, useSandboxGit, useSandboxTerminal, useSandboxWorkspaceTabs, useScheduledTasks, useSession, useSessionCapabilities, useSessionControl, useSessionEvents, useSessionLineage, useSlashCommands, useTerminalStream, useTurnQueue, useVariableSets, useWorkspaceCapture, useWorkspaceEdit, useWorkspaceSessions, useWorkspaces, v4aToGitFileDiff, xtermThemeFromTokens };
+export { ActivityDisclosure, type ActivityDisclosureProps, ActivityItem, ActivityRail, type ActivityRailProps, AgentMessageItem, type ApplyPatchOperation, ApprovalSurface, type ApprovalSurfaceMessages, type ApprovalSurfaceProps, AuthNeededItem, BodyNote, CREDIT_EXHAUSTION_MESSAGE, CapturedFileUnavailableError, type CapturedFileUnavailableReason, ChatComposer, ChatComposerMessages, type ChatComposerProps, ClientOverride, CodeEditor, type CodeEditorProps, type CodexAccountsClientLike, CommandContext, CommandPalette, type CommandPaletteProps, ComposerState, ComposerTranscriptionControlProps, type CreateToolRegistryOptions, type DeriveMachineChipInput, DesktopViewer, type DesktopViewerProps, type DesktopWebSocketFactory, type DesktopWebSocketLike, type DiffTheme, DiffView, type DiffViewProps, type DisclosureChip, DisclosureDefaultsProvider, FileBrowser, type FileBrowserProps, type FileTreeNode, type FileTreeStatus, FileWriteConflictError, FleetTile, type FleetTileProps, type HumanInputAnswerDraft, HumanInputForm, type HumanInputFormMessages, type HumanInputFormProps, LightboxProvider, type MachineChip, type MachineChipState, Markdown, type MarkdownProps, MediaEmpty, MediaSkeleton, MessageTimeline, type MessageTimelineProps, ModelPicker, type ModelPickerProps, OpenGeniProvider, type OpenGeniProviderProps, type ParsedCommandLine, PayloadBlock, PendingApproval, PierreDiff, type PierreDiffProps, PierreFile, type PierreFileProps, QueueSurface, type QueueSurfaceProps, SESSION_STATUS_META, SandboxFiles, type SandboxFilesProps, type SandboxGitFileDiff, SandboxTerminal, type SandboxTerminalProps, SandboxWorkspace, type SandboxWorkspaceProps, type SandboxWorkspaceSurface, type SandboxWriteFileOptions, ScreenshotFigure, type SessionCapabilitiesState, SessionClientLike, SessionStatus, type SessionStatusMeta, type SessionStatusProps, SlashArg, SlashCommand, SlashCommandContext, StatusDot, type StatusDotProps, TermBlock, type TerminalChunk, type TerminalStreamStatus, Thumbnail, TimelineItem, TimelineRow, ToolCallItem, type ToolRegistry, type ToolRegistryEntry, type ToolRenderer, type ToolRendererProps, TurnOutcome, TurnSummary, type TurnSummaryProps, type UseAvailableModelsOptions, type UseAvailableModelsResult, type UseBillingUsageOptions, type UseBillingUsageResult, type UseCodexAccountsOptions, type UseCodexAccountsResult, type UseDesktopStreamOptions, type UseDesktopStreamResult, type UseEnvironmentsOptions, type UseEnvironmentsResult, UseFileAttachmentsResult, type UseGoalOptions, type UseGoalResult, type UseMachineChipOptions, type UsePacksOptions, type UsePacksResult, type UseRelayFrameStreamOptions, type UseRelayFrameStreamResult, type UseRigChangesOptions, type UseRigChangesResult, type UseRigOptions, type UseRigResult, type UseRigVersionsOptions, type UseRigVersionsResult, type UseRigsOptions, type UseRigsResult, type UseSandboxFilesOptions, type UseSandboxFilesResult, type UseSandboxGitOptions, type UseSandboxGitResult, type UseSandboxTerminalOptions, type UseSandboxTerminalResult, type UseSandboxWorkspaceTabsOptions, type UseSandboxWorkspaceTabsResult, type UseScheduledTasksOptions, type UseScheduledTasksResult, type UseSessionCapabilitiesOptions, type UseSessionCapabilitiesResult, type UseSessionLineageOptions, type UseSessionLineageResult, type UseSessionOptions, type UseSessionResult, type UseTerminalStreamOptions, type UseTerminalStreamResult, UseTurnQueueResult, type UseVariableSetsOptions, type UseVariableSetsResult, type UseWorkspaceCaptureOptions, type UseWorkspaceCaptureResult, type UseWorkspaceEditOptions, type UseWorkspaceEditResult, type UseWorkspaceSessionsOptions, type UseWorkspaceSessionsResult, type UseWorkspacesOptions, type UseWorkspacesResult, UserMessageItem, WORKBENCH_SURFACES, WORKBENCH_TAB_CHANGES, WORKBENCH_TAB_DESKTOP, WORKBENCH_TAB_FILES, WORKBENCH_TAB_TERMINAL, WorkspaceDock, type WorkspaceDockProps, type WorkspaceEditConflict, type WorkspaceEditState, type WorkspaceMachine, type WorkspaceNotification, type WorkspaceTab, type XtermTheme, answersFromDrafts, applyPatchOps, argHint, cn, controlCaret, createDefaultToolRegistry, createToolRegistry, defaultApprovalSurfaceMessages, defaultCommands, defaultHumanInputFormMessages, defaultToolRegistry, deriveMachineChip, execTruncated, filterCommands, firstMissingRequiredArg, formatAsOf, formatBytes, formatRelativeTime, gitFileDiffToPatch, hasPermission, humanizeFailureReason, initialWorkspaceTab, isApplyPatch, isCodexAccountEvent, isCreditExhaustion, isExecSessionLostBanner, isGoalEvent, isLineageRefreshEvent, isTitleEvent, languageForPath, looksBinary, matchCommand, parseCommandLine, parseExecBannerSessionId, parseToolArgs, rawTypeOf, redactSecrets, sandboxCommandExitCode, sessionDisplayTitle, stringifyPayload, stripExecBanner, tailPeek, truncate, tryParseJson, unwrapMcpOutput, useAvailableModels, useBillingUsage, useCodexAccounts, useDesktopStream, useEnvironments, useGoal, useLightbox, useLightboxOptional, useMachineChip, usePacks, useRelayFrameStream, useRig, useRigChanges, useRigVersions, useRigs, useSandboxFiles, useSandboxGit, useSandboxTerminal, useSandboxWorkspaceTabs, useScheduledTasks, useSession, useSessionCapabilities, useSessionLineage, useTerminalStream, useVariableSets, useWorkspaceCapture, useWorkspaceEdit, useWorkspaceSessions, useWorkspaces, v4aToGitFileDiff, xtermThemeFromTokens };