@opengeni/react 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { C as ClientOverride, S as SessionClientLike } from './machines-BeZ3bD3t.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-BeZ3bD3t.js';
-import { SessionEvent, Session, ResourceRef, ToolRef, SessionStatus as SessionStatus$1, GitFileDiff, StreamConnectionState, SendMessageInput, FileAsset, FileResourceRef, SessionTurn, UpdateSessionTurnRequest, SessionGoal, ScheduledTask, WorkspaceEnvironment, CreateWorkspaceEnvironmentRequest, UpdateWorkspaceEnvironmentRequest, WorkspaceEnvironmentVariableMetadata, CapabilityPack, PackInstallation, RegisterCapabilityPackRequest, WorkspaceRegisteredPack, EnablePackRequest, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, BillingBalance, UsageEvent, ClientModel, SessionCapabilities, DesktopStreamCapability, DesktopConnectionState, DesktopRfbFactory, TerminalCapability, FsReadResponse, FsWriteResponse, Permission, CapabilityUnavailableReason, CodexAccountsResponse, CodexAccount, CodexRotationSettings } from '@opengeni/sdk';
+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';
 export { MachineKind, MachineMetricsSeriesResponse, MachineState, MachineView, MachinesResponse, MetricSample } from '@opengeni/sdk';
 import * as react from 'react';
 import { ComponentType, ReactNode, RefObject, KeyboardEvent, ClipboardEvent } from 'react';
@@ -42,8 +42,6 @@ type UserMessageItem = {
     kind: "user-message";
     id: string;
     text: string;
-    /** Queued for a future turn whose start has not appeared in the event log. */
-    pending?: boolean;
     /** Resources attached to this message (file uploads, repositories). */
     resources: ResourceRef[];
     /** Tools requested for the turn this message starts. */
@@ -96,19 +94,27 @@ type WorkerItem = {
     id: string;
     turnId: string | null;
     callId: string | null;
-    action: "spawn" | "message" | "interrupt";
+    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;
-    /**
-     * For an `interrupt` action, whether it stops the target (default) or steers
-     * it (cancel the current turn, keep the goal). Absent on spawn/message.
-     */
-    mode?: "stop" | "steer";
     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;
@@ -116,9 +122,45 @@ type SandboxItem = {
     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;
@@ -128,7 +170,7 @@ type SessionStatusItem = {
 type GoalItem = {
     kind: "goal";
     id: string;
-    action: "set" | "updated" | "completed" | "paused" | "resumed" | "continuation";
+    action: "set" | "updated" | "completed" | "paused" | "resumed" | "cleared" | "continuation";
     text: string | null;
     occurredAt: string;
 };
@@ -137,12 +179,45 @@ type NoticeItem = {
     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";
@@ -152,9 +227,9 @@ type TurnEndItem = {
     failureText: string | null;
     occurredAt: string;
 };
-type TimelineItem = UserMessageItem | AgentMessageItem | ReasoningItem | ToolCallItem | WorkerItem | SandboxItem | SessionStatusItem | GoalItem | NoticeItem | TurnEndItem;
-/** Activity items cluster between chat messages (reasoning, tools, workers, sandbox). */
-type ActivityItem = ReasoningItem | ToolCallItem | WorkerItem | SandboxItem;
+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;
@@ -175,6 +250,13 @@ type TimelineGroup = {
 };
 
 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[];
@@ -184,7 +266,16 @@ declare function groupTimeline(items: TimelineItem[]): TimelineGroup[];
  * text: "{...}" }], structuredContent? }`).
  */
 declare function extractSessionRef(value: unknown, depth?: number): string | null;
-/** Readable label for a tool call ("session_create" -> "session create"). */
+/**
+ * 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 = {
@@ -237,11 +328,17 @@ type ActivityRailProps = {
     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, bare, className }: ActivityRailProps): react_jsx_runtime.JSX.Element;
+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.
@@ -305,7 +402,7 @@ type ActivityDisclosureProps = {
  * 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, }: {
+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
@@ -317,6 +414,8 @@ declare function TermBlock({ command, workdir, output, live, tailLines, }: {
     /** 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
@@ -324,13 +423,13 @@ declare function TermBlock({ command, workdir, output, live, tailLines, }: {
      */
     tailLines?: number | undefined;
 }): react_jsx_runtime.JSX.Element;
-declare function PayloadBlock({ label, value, failed }: {
+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 }: {
+declare function BodyNote({ children, tone, }: {
     children: ReactNode;
     tone?: "error" | "muted" | undefined;
 }): react_jsx_runtime.JSX.Element;
@@ -349,7 +448,7 @@ declare function MediaEmpty(): react_jsx_runtime.JSX.Element;
  * 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 }: {
+declare function Thumbnail({ src, caption, alt, }: {
     src: string;
     caption?: string | undefined;
     alt?: string;
@@ -360,7 +459,7 @@ declare function Thumbnail({ src, caption, alt }: {
  * 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 }: {
+declare function ScreenshotFigure({ src, caption, alt, }: {
     src: string;
     caption?: string | undefined;
     alt?: string;
@@ -395,7 +494,7 @@ declare function LightboxProvider({ children }: {
  * 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 }: {
+declare function DisclosureDefaultsProvider({ defaultOpen, children, }: {
     defaultOpen: boolean;
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
@@ -415,10 +514,17 @@ type TurnSummaryProps = {
     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, children }: TurnSummaryProps): react_jsx_runtime.JSX.Element;
+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;
@@ -533,9 +639,8 @@ declare function useSessionEvents(sessionId: string | null | undefined, options?
 
 type ComposerSendExtras = Omit<SendMessageInput, "text" | "clientEventId">;
 /**
- * Compose-time delivery choice. `queue` (the default) stacks the message
- * behind the running turn — visible, editable, reorderable until claimed.
- * `steer` interrupts the running turn and injects the message now.
+ * Enter appends a prompt; Cmd/Ctrl+Enter steers it to the head and supersedes
+ * the current inference.
  */
 type ComposerMode = "queue" | "steer";
 type UseComposerOptions = ClientOverride & {
@@ -547,27 +652,24 @@ type UseComposerOptions = ClientOverride & {
      * surrounding UI state (attachment pickers, model selectors, ...).
      */
     sendExtras?: ComposerSendExtras | (() => ComposerSendExtras) | undefined;
-    /** Initial delivery mode. Defaults to `"queue"`. */
-    defaultMode?: ComposerMode | undefined;
 };
 type ComposerState = {
     value: string;
     setValue: (value: string) => void;
-    /** Send the draft (or an explicit text) using the current mode. */
-    send: (text?: string) => Promise<boolean>;
+    /** Send the draft (or explicit text). Queue is the default; steer is explicit. */
+    send: (text?: string, mode?: ComposerMode) => Promise<boolean>;
     sending: boolean;
     canSend: boolean;
-    /** Queue (default) vs steer — the compose-time delivery choice. */
-    mode: ComposerMode;
-    setMode: (mode: ComposerMode) => void;
-    /** Ask the agent to stop the current turn. */
-    interrupt: (reason?: string) => Promise<void>;
-    interrupting: 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 + interrupt state for the chat composer — the only
+ * 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.
@@ -589,6 +691,8 @@ declare function composeSendInput(text: string, clientEventId: string, extras: C
 declare function shouldSubmitOnKey(event: {
     key: string;
     shiftKey: boolean;
+    metaKey?: boolean;
+    ctrlKey?: boolean;
     nativeEvent?: {
         isComposing?: boolean;
     };
@@ -652,55 +756,32 @@ type UseFileAttachmentsResult = {
  */
 declare function useFileAttachments(options?: UseFileAttachmentsOptions): UseFileAttachmentsResult;
 
-/** Event types that change the turn queue (queue/edit/reorder/claim/finish). */
+/** Events that can change the authoritative prompt queue or its pause gates. */
 declare function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean;
-/** Queued turns in execution order (position, then creation time). */
-declare function queueFromTurns(turns: SessionTurn[]): SessionTurn[];
-/** The turn currently holding the session (running or awaiting approval). */
-declare function activeTurnFromTurns(turns: SessionTurn[]): SessionTurn | null;
-/** Optimistic projection of a queued-turn edit. */
-declare function applyTurnEdit(turns: SessionTurn[], turnId: string, update: UpdateSessionTurnRequest): SessionTurn[];
-/**
- * Optimistic projection of a reorder, mirroring the server: the listed
- * queued turns get positions 1..n in the given order; everything else keeps
- * its position.
- */
-declare function applyTurnReorder(turns: SessionTurn[], turnIds: string[]): SessionTurn[];
-/** Optimistic projection of a queued-turn delete (server marks it cancelled). */
-declare function applyTurnRemoval(turns: SessionTurn[], turnId: string): SessionTurn[];
 type UseTurnQueueOptions = ClientOverride & SessionEventFeedOptions & {
-    /** Optional safety-net polling (ms). Off by default — turn.* events drive updates. */
     pollIntervalMs?: number | undefined;
 };
 type UseTurnQueueResult = {
-    /** All turns the API returned (history + queue), newest server view. */
-    turns: SessionTurn[];
-    /** Queued turns in execution order — render this as the editable queue. */
+    snapshot: SessionQueueSnapshot | null;
+    /** Human/API prompts exactly in server execution order. Never client-sorted. */
     queue: SessionTurn[];
-    /** The running / requires_action turn, if any. */
-    activeTurn: SessionTurn | null;
+    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>;
-    /** Edit a queued turn (optimistic; rolls back via refetch on failure). */
-    editTurn: (turnId: string, update: UpdateSessionTurnRequest) => Promise<SessionTurn | null>;
-    /** Reorder the queue to the given queued-turn id order (optimistic). */
-    reorderTurns: (turnIds: string[]) => Promise<SessionTurn[] | null>;
-    /** Delete (cancel) a queued turn before it is claimed (optimistic). */
-    removeTurn: (turnId: string) => Promise<SessionTurn | null>;
-    /** True while an edit/reorder/remove is in flight. */
+    /** Delete a waiting prompt before the worker claims it. */
+    removeTurn: (turnId: string) => Promise<boolean>;
     mutating: boolean;
-    /** Last failed mutation, until the next mutation or clear. */
     mutationError: Error | null;
     clearMutationError: () => void;
 };
 /**
- * The live turn queue — the heart of the queue-by-default interaction model.
- * Messages sent mid-turn stack up here, visible and editable/reorderable/
- * deletable until the worker claims them. Updates arrive over the session
- * event stream (`turn.*`), either shared via `options.events` (pass the log
- * from `useSessionEvents` to reuse its connection) or a dedicated tail
- * stream. All mutations apply optimistically and reconcile with the server.
+ * The single authoritative waiting-prompt queue. The server owns ordering; the
+ * client renders the returned array verbatim and supports deletion only.
  */
 declare function useTurnQueue(sessionId: string | null | undefined, options?: UseTurnQueueOptions): UseTurnQueueResult;
 
@@ -724,7 +805,11 @@ type UseGoalResult = {
     pause: (rationale?: string) => Promise<SessionGoal | null>;
     /** Resume a paused goal: resets counters and re-arms continuations. */
     resume: () => Promise<SessionGoal | null>;
-    /** True while a pause/resume is in flight. */
+    /** Clear the session goal; goal-less sessions remain a successful no-op. */
+    clearGoal: () => Promise<void>;
+    /** Alias for `clearGoal`. */
+    deleteGoal: () => Promise<void>;
+    /** True while a pause/resume/clear is in flight. */
     updating: boolean;
     mutationError: Error | null;
     clearMutationError: () => void;
@@ -739,9 +824,9 @@ declare function useGoal(sessionId: string | null | undefined, options?: UseGoal
 
 type UseSessionControlOptions = ClientOverride;
 type UseSessionControlResult = {
-    /** Interrupt the running turn (the explicit alternative to queueing). */
-    interrupt: (reason?: string) => Promise<SessionEvent | null>;
-    interrupting: boolean;
+    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. */
@@ -752,7 +837,7 @@ type UseSessionControlResult = {
     clearError: () => void;
 };
 /**
- * Session control events: interrupt and approval decisions. Pair with
+ * Session pause/resume and approval decisions. Pair with
  * `useSessionEvents` (for `session.requiresAction` payloads carrying the
  * `approvalId`) to render an approval bar.
  */
@@ -774,12 +859,22 @@ declare function useScheduledTasks(options?: UseScheduledTasksOptions): UseSched
 
 type UseWorkspaceSessionsOptions = ClientOverride & {
     limit?: number | undefined;
+    parentSessionId?: string | null | undefined;
+    cursor?: string | undefined;
+    search?: string | undefined;
     /** Refresh interval (ms) for fleet/manager views. Off by default. */
     pollIntervalMs?: number | undefined;
     enabled?: boolean | undefined;
 };
 type UseWorkspaceSessionsResult = {
+    /**
+     * All visible rows, with pins first. This preserves the pre-pinning hook
+     * contract for consumers that only read `sessions`.
+     */
     sessions: Session[];
+    /** The complete personal pinned section, also present in `sessions`. */
+    pinned: Session[];
+    nextCursor: string | null;
     loading: boolean;
     error: Error | null;
     refresh: () => Promise<void>;
@@ -787,32 +882,142 @@ type UseWorkspaceSessionsResult = {
 /** List the workspace's sessions — the data behind fleet and manager views. */
 declare function useWorkspaceSessions(options?: UseWorkspaceSessionsOptions): UseWorkspaceSessionsResult;
 
-type UseEnvironmentsOptions = ClientOverride & {
+type UseSessionLineageOptions = ClientOverride & {
+    events?: SessionEvent[] | undefined;
+    /** Refresh interval (ms). Off by default. */
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseSessionLineageResult = {
+    lineage: SessionLineageResponse | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+declare function isLineageRefreshEvent(event: SessionEvent): boolean;
+/** Read the ancestors + descendant tree for one session. Data-only; no UI state. */
+declare function useSessionLineage(sessionId: string | null | undefined, options?: UseSessionLineageOptions): UseSessionLineageResult;
+
+type UseVariableSetsOptions = ClientOverride & {
     pollIntervalMs?: number | undefined;
     enabled?: boolean | undefined;
 };
-type UseEnvironmentsResult = {
-    environments: WorkspaceEnvironment[];
+type UseVariableSetsResult = {
+    variableSets: VariableSet[];
     loading: boolean;
     error: Error | null;
     refresh: () => Promise<void>;
-    create: (request: CreateWorkspaceEnvironmentRequest) => Promise<WorkspaceEnvironment | null>;
-    update: (environmentId: string, request: UpdateWorkspaceEnvironmentRequest) => Promise<WorkspaceEnvironment | null>;
-    remove: (environmentId: string) => Promise<boolean>;
+    create: (request: CreateVariableSetRequest) => Promise<VariableSet | null>;
+    update: (variableSetId: string, request: UpdateVariableSetRequest) => Promise<VariableSet | null>;
+    remove: (variableSetId: string) => Promise<boolean>;
     /** Set/rotate a variable. Values are write-only — reads expose metadata only. */
-    setVariable: (environmentId: string, name: string, value: string) => Promise<WorkspaceEnvironmentVariableMetadata | null>;
-    deleteVariable: (environmentId: string, name: string) => Promise<boolean>;
+    setVariable: (variableSetId: string, name: string, value: string) => Promise<VariableSetVariableMetadata | null>;
+    deleteVariable: (variableSetId: string, name: string) => Promise<boolean>;
     mutating: boolean;
     mutationError: Error | null;
     clearMutationError: () => void;
 };
 /**
- * Workspace environments (named, encrypted variable sets attached to sessions
+ * Variable sets (named, encrypted variable sets attached to sessions
  * and scheduled tasks). Variable values are write-only end to end: this hook
  * never sees a value after it is sent.
  */
+declare function useVariableSets(options?: UseVariableSetsOptions): UseVariableSetsResult;
+/** @deprecated use UseVariableSetsOptions */
+type UseEnvironmentsOptions = UseVariableSetsOptions;
+/** @deprecated use UseVariableSetsResult */
+type UseEnvironmentsResult = UseVariableSetsResult & {
+    environments: VariableSet[];
+};
+/** @deprecated use useVariableSets */
 declare function useEnvironments(options?: UseEnvironmentsOptions): UseEnvironmentsResult;
 
+type UseRigsOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseRigsResult = {
+    rigs: Rig[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: CreateRigRequest) => Promise<Rig | null>;
+    update: (rigId: string, request: UpdateRigRequest) => Promise<Rig | null>;
+    remove: (rigId: string) => Promise<boolean>;
+    listVersions: (rigId: string) => Promise<RigVersion[] | null>;
+    activateVersion: (rigId: string, versionId: string) => Promise<RigVersion | null>;
+    listChanges: (rigId: string) => Promise<RigChange[] | null>;
+    proposeChange: (rigId: string, request: ProposeRigChangeRequest) => Promise<RigChange | null>;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * Rigs (workspace-scoped, versioned sandbox machine definitions). The list
+ * polls; version/change reads are on-demand (they are per-rig detail, not part
+ * of the list surface).
+ */
+declare function useRigs(options?: UseRigsOptions): UseRigsResult;
+type UseRigOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseRigResult = {
+    rig: Rig | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    update: (request: UpdateRigRequest) => Promise<Rig | null>;
+    remove: () => Promise<boolean>;
+    activateVersion: (versionId: string) => Promise<RigVersion | null>;
+    proposeChange: (request: ProposeRigChangeRequest) => Promise<RigChange | null>;
+    /** Re-run verification for a change (asynchronous — poll for the outcome). */
+    verifyChange: (changeId: string) => Promise<RigChange | null>;
+    /** Promote a verified definition_edit into a new active version (rigs:manage). */
+    promoteChange: (changeId: string) => Promise<RigVersion | null>;
+    /** Re-verify the active version's checks in a clean throwaway sandbox. */
+    verify: () => Promise<{
+        ok: boolean;
+        versionId: string;
+    } | null>;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * A single rig (its active version + counts), polled so verification and
+ * promotion state stay live. Owns the rig's write actions; the versions and
+ * changes lists are separate polled reads (`useRigVersions`/`useRigChanges`).
+ */
+declare function useRig(rigId: string, options?: UseRigOptions): UseRigResult;
+type UseRigVersionsOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseRigVersionsResult = {
+    versions: RigVersion[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/** A rig's append-only version history, newest-first (polled). */
+declare function useRigVersions(rigId: string, options?: UseRigVersionsOptions): UseRigVersionsResult;
+type UseRigChangesOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseRigChangesResult = {
+    changes: RigChange[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/**
+ * A rig's change queue (polled). The default poll cadence lets a change move
+ * through verifying → merged/rejected without a manual refresh.
+ */
+declare function useRigChanges(rigId: string, options?: UseRigChangesOptions): UseRigChangesResult;
+
 type UsePacksOptions = ClientOverride & {
     pollIntervalMs?: number | undefined;
     enabled?: boolean | undefined;
@@ -907,7 +1112,7 @@ type UseAvailableModelsResult = {
  */
 declare function useAvailableModels(options?: UseAvailableModelsOptions): UseAvailableModelsResult;
 
-type SessionCapabilitiesState = "idle" | "negotiating" | "ready" | "cold" | "error";
+type SessionCapabilitiesState = "idle" | "negotiating" | "ready" | "cold" | "on-demand" | "error";
 type UseSessionCapabilitiesOptions = ClientOverride & {
     /**
      * Live event log to fold `stream.url.rotated` from (usually
@@ -933,15 +1138,18 @@ type UseSessionCapabilitiesOptions = ClientOverride & {
      */
     attachTerminal?: boolean | undefined;
     /**
-     * Whether to acquire a viewer holder purely to KEEP THE BOX WARM while the
-     * structured Files surface is open. Shares the SAME viewer attach as the
-     * desktop/terminal (one warm box, one holder) and — like the terminal — needs
-     * NO un-redacted acknowledgment: listing/reading/writing files is the ordinary
-     * Channel-A control plane, not the pixel plane. Default false: the Files tab
-     * negotiates read-only and each op pays the cold-box resume (~5s). When true,
-     * the holder warms the box once and heartbeats it, so subsequent fs ops are
-     * ~100ms instead of re-resuming the box on every list/write. It folds NO live
-     * URL (files ride the stateless HTTP plane) — it only refcounts liveness.
+     * Whether to acquire a viewer holder to warm the box for a FILE WRITE — the
+     * wake-on-edit INTENT (a first keystroke in the editor), NOT passive browsing.
+     * Shares the SAME viewer attach as the desktop/terminal (one warm box, one
+     * holder) and — like the terminal — needs NO un-redacted acknowledgment:
+     * reading/writing files is the ordinary Channel-A control plane, not the pixel
+     * plane. It folds NO live URL (files ride the stateless HTTP plane) — it only
+     * refcounts liveness. Unlike desktop/terminal it warms even a COLD box: an edit
+     * legitimately cold-creates (that IS the wake), so the write lands ~100ms warm
+     * instead of paying the ~5s cold resume. Default false. IMPORTANT: merely
+     * opening/reading the Files tab must NOT set this — browsing capture-served
+     * trees/diffs needs no box, and warming one on a cold glance burns box-hours to
+     * serve reads the capture already answers for free.
      */
     attachFiles?: boolean | undefined;
     /** Hold off negotiating (e.g. the workbench panel is collapsed). Default true. */
@@ -1197,6 +1405,10 @@ type FileTreeNode = {
     children?: FileTreeNode[] | undefined;
     size?: number | null | undefined;
     status?: FileTreeStatus | undefined;
+    /** A residue dir the capture COLLAPSED (node_modules, .git, dist, …): its
+     *  contents were never indexed. Cold, expanding it can't list children — the
+     *  UI shows an inline "contents on machine" row until the box is warm. */
+    truncated?: boolean | undefined;
 };
 type UseSandboxFilesOptions = ClientOverride & {
     /** Live event log (usually `useSessionEvents().events`) — drives auto-refresh
@@ -1212,6 +1424,12 @@ 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). */
+    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
      *  toast — the tree silently rolls the node back, the user sees why. */
@@ -1243,6 +1461,11 @@ type UseSandboxFilesResult = {
     }) => Promise<void>;
     /** Re-list the whole tree from the root. */
     refresh: () => Promise<void>;
+    /** Which source the tree is currently served from: the live box, the turn-end
+     *  capture (cold/offline), or neither yet. M5's source badge reads this. */
+    source: "live" | "capture" | null;
+    /** When the served capture was taken (ISO), when `source === "capture"`. */
+    capturedAt: string | null;
     loading: boolean;
     error: Error | null;
 };
@@ -1265,6 +1488,12 @@ type UseSandboxGitOptions = ClientOverride & {
     staged?: boolean | undefined;
     /** Hold off the initial fetch. Default true. */
     enabled?: boolean | undefined;
+    /** 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). */
+    capture?: WorkspaceCaptureManifest | null | undefined;
 };
 type UseSandboxGitResult = {
     /** Working-tree (or staged) diff vs HEAD — the structured hunks the Pierre
@@ -1276,18 +1505,197 @@ type UseSandboxGitResult = {
     ahead: number;
     behind: number;
     refresh: () => Promise<void>;
+    /** Which source the diff is served from: the live box or the turn-end capture. */
+    source: "live" | "capture" | null;
+    /** When the served capture was taken (ISO), when `source === "capture"`. */
+    capturedAt: string | null;
     loading: boolean;
     error: Error | null;
 };
 /**
  * Project the Git service into the Pierre diff data contract: structured
  * `GitFileDiff[]` (per-file hunks with per-line old/new numbers, rename
- * detection, binary flag, add/del counts) plus branch + ahead/behind. The
- * `git diff` runs in-box (API-direct) and the hunks come back inline. Refreshes
- * on `git.changed`.
+ * 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
+ * `git.changed`; reconciles live in place on the cold→warm transition.
  */
 declare function useSandboxGit(sessionId: string | null | undefined, options?: UseSandboxGitOptions): UseSandboxGitResult;
 
+type UseWorkspaceCaptureOptions = ClientOverride & {
+    /** Live event log (usually `useSessionEvents().events`) — a
+     *  `workspace.revision.captured` for a NEWER revision refreshes the manifest. */
+    events?: SessionEvent[] | undefined;
+    /** Hold off the mount fetch (e.g. the workbench panel is collapsed). Default true. */
+    enabled?: boolean | undefined;
+};
+type UseWorkspaceCaptureResult = {
+    /** The resolved manifest (tree index + per-repo diffs + file refs), or null when
+     *  no capture exists (falls back to the live/wake path — status quo). */
+    capture: WorkspaceCaptureManifest | null;
+    /** The loaded capture's monotonic revision, or null when unavailable. */
+    revision: number | null;
+    /** When the loaded capture was taken (ISO), for the "as of <time>" source badge. */
+    capturedAt: string | null;
+    /** Whether a capture is available at all (the `{available:false}` discriminator). */
+    available: boolean;
+    /** Why the newest durable revision is unavailable. null means no capture has
+     *  been attempted yet; a value means capture explicitly failed closed and
+     *  consumers must use the live box rather than trust an incomplete snapshot. */
+    degradedReason: WorkspaceCaptureDegradedReason | null;
+    /** The changed-file count from the capture's stats, resolved on the FIRST GET
+     *  (from the response's top-level `stats`, before any manifest-URL hop). null
+     *  until that first resolve; 0 when no capture exists. This is the pre-paint
+     *  "changes exist?" signal the dock uses to pick its default tab with no
+     *  embedder events-at-mount contract. */
+    fileCount: number | null;
+    /** A newer revision has been ANNOUNCED than the one currently loaded (a refresh
+     *  is in flight or pending). M5's source badge can show a subtle "updating…". */
+    isStale: boolean;
+    loading: boolean;
+    error: Error | null;
+    /** Force a re-fetch of the latest capture. */
+    refresh: () => Promise<void>;
+};
+/**
+ * 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
+ * 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
+ * newer than the one loaded triggers a background refresh (stale-while-revalidate).
+ * `{available:false}` is a value, never a crash — consumers fall back to the
+ * live/wake path exactly as before the capture feature existed.
+ */
+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:
+ *
+ *   viewing-cold      — cold snapshot open, no local edits (editable, cloud).
+ *   buffering         — local edits buffered; the box is not warm and no warm is
+ *                       yet in flight (the host has not attached).
+ *   warming           — edits buffered; the box is actively coming up (the host
+ *                       attached a viewer in response to `wantsWarm`).
+ *   flushing          — the box is warm; the guarded write is in flight.
+ *   flushed           — the buffer was written to the live box.
+ *   conflict          — the live file diverged from the captured base between
+ *                       capture and flush; NO write was issued (C2).
+ *   readonly-offline  — a self-hosted machine that is offline; read-only, no wake.
+ */
+type WorkspaceEditState = "viewing-cold" | "buffering" | "warming" | "flushing" | "flushed" | "conflict" | "readonly-offline";
+type WorkspaceEditConflict = {
+    path: string;
+    /** The capture-served content the edit was based on. */
+    base: string;
+    /** The live content found on the box at flush time (what would be overwritten). */
+    live: string;
+};
+type UseWorkspaceEditOptions = ClientOverride & {
+    /** The file being edited (workspace-relative). null disables the machine. */
+    path?: string | null | undefined;
+    /** The capture-served content loaded into the editor — the flush base (C2). */
+    baseContent?: string | null | undefined;
+    /** `capabilities.liveness` — "warm" | "draining" | "cold". Drives the flush. */
+    liveness?: string | undefined;
+    /** True while the host is actively warming the box (attach in flight, not warm
+     *  yet) — lifts `buffering` → `warming`. The host sets this after acting on
+     *  `wantsWarm` (e.g. flipping `attachFiles` on `useSessionCapabilities`). */
+    warming?: boolean | undefined;
+    /** A self-hosted machine that is OFFLINE: read-only, no remote wake possible. */
+    offline?: boolean | undefined;
+    /** Called once when the first cold edit needs the box warmed — the host wires
+     *  this to its liveness primitive (flip `attachFiles`/`attachViewer`). */
+    onWarmRequested?: (() => void) | undefined;
+};
+type UseWorkspaceEditResult = {
+    state: WorkspaceEditState;
+    /** The editor should be read-only (self-hosted offline). */
+    readOnly: boolean;
+    /** The current buffered content (null = no local edit yet). */
+    buffer: string | null;
+    /** The host should warm the box (flip its attach primitive). Latches true from
+     *  the first cold edit until the buffer flushes or is discarded. */
+    wantsWarm: boolean;
+    /** Record an edit from the editor (idempotent per identical content). */
+    edit: (content: string) => void;
+    /** The conflict detail when `state === "conflict"`. */
+    conflict: WorkspaceEditConflict | null;
+    /** Flush the buffer regardless of the base guard (the user chose "overwrite"
+     *  from the conflict bar). Writes last-writer-wins. */
+    overwrite: () => Promise<void>;
+    /** Drop the local buffer and return to viewing the snapshot. */
+    discard: () => void;
+    error: Error | null;
+};
+/**
+ * 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).
+ *
+ * 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.
+ */
+declare function useWorkspaceEdit(sessionId: string | null | undefined, options?: UseWorkspaceEditOptions): UseWorkspaceEditResult;
+
+/** 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;
+};
+/** 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 PendingApproval = {
     /** The id to send back via `user.approvalDecision` (`approvalId`). */
     id: string;
@@ -1509,7 +1917,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;
+declare function CommandPalette({ open, items, highlight, onHighlight, onRun, argHintText, listboxId, }: CommandPaletteProps): react_jsx_runtime.JSX.Element;
 
 type ChatComposerProps = {
     composer: ComposerState;
@@ -1611,6 +2019,31 @@ type MessageTimelineProps = {
     renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
     /** Drill into a spawned worker session. */
     onOpenSession?: ((sessionId: string) => void) | undefined;
+    /**
+     * Deep-link a memory row (a `memory.saved` / `memory.corrected` step) to its
+     * record in the host's memory pane. Opt-in, exactly like `onReconnect`: the
+     * library draws no "View in memory" affordance without a handler — the memory
+     * row is then non-interactive rich content. This is the switch that makes the
+     * deep-link a first-party OpenGeni capability without other SDK consumers
+     * opting into it. The app supplies it (it owns routing to the memory pane).
+     */
+    onMemoryClick?: ((memoryId: string) => void) | undefined;
+    /**
+     * Start the reconnect flow when a tool needs its connection reauthorized. The
+     * app supplies this (it owns the SDK client + workspace): it typically kicks
+     * off `startConnectionOAuth` and redirects, or routes to credential entry.
+     * Rejecting surfaces a calm inline error on the card; the library never draws
+     * a Reconnect button without a handler to run it.
+     */
+    onReconnect?: ((item: AuthNeededItem) => void | Promise<void>) | undefined;
+    /**
+     * Resolve a provider domain (from a reconnect card) to a logo URL the host
+     * serves itself — the app maps it through its catalog + `catalogAssetUrl`.
+     * Return null/undefined to fall back to a calm monogram. The library never
+     * fetches an off-origin favicon (CSP + privacy); an unresolved logo is a
+     * monogram, not an external image.
+     */
+    resolveProviderLogo?: ((providerDomain: string) => string | null | undefined) | undefined;
     /**
      * The tool-renderer registry that resolves how each tool call is drawn.
      * Defaults to {@link defaultToolRegistry}; pass a registry from
@@ -1634,15 +2067,18 @@ type MessageTimelineProps = {
  * cards, goal markers, and status transitions. Owns stick-to-bottom scrolling
  * with a "jump to latest" affordance when the reader scrolls back.
  */
-declare function MessageTimeline({ events, items, status, renderMessageText, onOpenSession, toolRegistry, autoFollow, hasOlder, loadingOlder, onLoadOlder, emptyState, className, }: MessageTimelineProps): react_jsx_runtime.JSX.Element;
+declare function MessageTimeline({ events, items, status, renderMessageText, onOpenSession, onMemoryClick, onReconnect, resolveProviderLogo, toolRegistry, autoFollow, hasOlder, loadingOlder, onLoadOlder, emptyState, className, }: MessageTimelineProps): react_jsx_runtime.JSX.Element;
 /**
  * Render one non-activity timeline item (chat message, status divider, goal
  * landmark, notice). Exported so the component demo draws the EXACT same rows as
  * the live app — no forked bubble/goal markup.
  */
-declare function TimelineRow({ item, renderMessageText, }: {
+declare function TimelineRow({ item, renderMessageText, onReconnect, resolveProviderLogo, onOpenSession, }: {
     item: TimelineItem;
     renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
+    onReconnect?: ((item: AuthNeededItem) => void | Promise<void>) | undefined;
+    resolveProviderLogo?: ((providerDomain: string) => string | null | undefined) | undefined;
+    onOpenSession?: ((sessionId: string) => void) | undefined;
 }): react_jsx_runtime.JSX.Element | null;
 
 /**
@@ -1710,13 +2146,37 @@ declare function sessionDisplayTitle(session: Session): string;
  */
 declare function FleetTile({ session, title, subtitle, onOpen, className }: FleetTileProps): react_jsx_runtime.JSX.Element;
 
-/** A subset of xterm.js's ITheme — the tokens worth themeing from a host app. */
+type RendererTier = "webgl" | "canvas" | "dom";
+
+/**
+ * A COMPLETE xterm `ITheme` (subset by intent, but every field xterm colors a
+ * cell with is present so it never falls back to its stock VGA palette). Built
+ * from the og tokens via `xtermThemeFromTokens`.
+ */
 type XtermTheme = {
     background?: string;
     foreground?: string;
     cursor?: string;
     cursorAccent?: string;
     selectionBackground?: string;
+    selectionForeground?: string;
+    selectionInactiveBackground?: string;
+    black?: string;
+    red?: string;
+    green?: string;
+    yellow?: string;
+    blue?: string;
+    magenta?: string;
+    cyan?: string;
+    white?: string;
+    brightBlack?: string;
+    brightRed?: string;
+    brightGreen?: string;
+    brightYellow?: string;
+    brightBlue?: string;
+    brightMagenta?: string;
+    brightCyan?: string;
+    brightWhite?: string;
 };
 type SandboxTerminalProps = {
     /** From `useSandboxTerminal(...)`. */
@@ -1731,9 +2191,21 @@ type SandboxTerminalProps = {
      * (`result.chunks`). Omit to force the legacy firehose-only behavior.
      */
     terminalCapability?: TerminalCapability | null | undefined;
+    /**
+     * Full xterm theme. When omitted the terminal self-derives it from the `--og-*`
+     * tokens of its own container (correct even inside a nested `data-og-theme`
+     * subtree). Passing it lets the host drive re-theme on a theme flip.
+     */
     theme?: XtermTheme | undefined;
     fontFamily?: string | undefined;
     fontSize?: number | undefined;
+    /**
+     * Lease liveness (`cold` | `warming` | `warm` | `draining`). Drives the
+     * boot-in-terminal status lines: once the user has focused the terminal and
+     * the box is not yet warm, a styled "● waking machine — Ns…" line is rendered
+     * INSIDE xterm (no overlay/spinner) until the live PTY connects.
+     */
+    liveness?: string | undefined;
     /**
      * Force read-only even when the PTY accepts stdin. Default: interactive
      * whenever a live pty-ws stream is connected OR `result.write !== null` (the box
@@ -1756,19 +2228,44 @@ type SandboxTerminalProps = {
     onActivate?: (() => void) | undefined;
     className?: string | undefined;
 };
+/** Debug seam (dev/evidence only, never a typed public API): a global hook the
+ *  screenshot harness reads to probe the settled renderer tier + resolved font
+ *  without mounting a real WebGL context in unit tests. */
+type TerminalDebugInfo = {
+    renderer: RendererTier | null;
+    fontFamily: string | undefined;
+    fontSize: number | undefined;
+    hasVarInFont: boolean;
+    theme: XtermTheme | undefined;
+    /** The live xterm instance (opaque) — the evidence harness reads its buffer to
+     *  prove screen preservation (E5) and drive the burst-responsiveness probe. */
+    term: unknown;
+};
+declare global {
+    var __OG_TERMINAL_DEBUG__: ((info: TerminalDebugInfo) => void) | undefined;
+    var __OG_FORCE_RENDERER_FAIL__: string | undefined;
+}
 /**
  * An xterm.js terminal fed by the Channel-A event projection
- * (`useSandboxTerminal`). xterm + the fit + web-links addons are lazy-imported
+ * (`useSandboxTerminal`) or a live ttyd PTY. xterm + its addons are lazy-imported
  * inside an effect, so SSR renders the placeholder and the terminal mounts on
- * hydration. Output chunks are written incrementally (tracking a written-cursor
- * by chunk id so a re-render never re-writes). When `result.write` is non-null
- * and not forced read-only, keystrokes pipe back through the PTY.
+ * hydration.
+ *
+ * Renderer: WebGL (GPU-composited cells) with a canvas → DOM fallback ladder
+ * (`attachRenderer`), so bursty output stays smooth but a lost/blocklisted
+ * context degrades gracefully. Font + theme are resolved to CONCRETE values
+ * from the og tokens BEFORE construction (xterm measures glyphs in a canvas
+ * where `var()` never resolves, and colors every cell from a full ANSI palette).
+ *
+ * The terminal is mounted ONCE and its data source is swapped in place: the
+ * read-only firehose (`result.chunks`) → the live PTY. Stdin is toggled via
+ * `term.options.disableStdin` at runtime (not a remount), so scrollback and the
+ * visible screen survive the projection→PTY handoff.
  *
  * Resizes are tracked with a `ResizeObserver` on the container (not just
- * `window.resize`) so dragging the dock handle refits the grid instead of
- * leaving the terminal mis-sized.
+ * `window.resize`) so dragging the dock handle refits the grid.
  */
-declare function SandboxTerminal({ result, terminalCapability, theme, fontFamily, fontSize, readOnly, placeholder, showHeader, shell, onActivate, className, }: SandboxTerminalProps): react_jsx_runtime.JSX.Element;
+declare function SandboxTerminal({ result, terminalCapability, theme, fontFamily, fontSize, liveness, readOnly, placeholder, showHeader, shell, onActivate, className, }: SandboxTerminalProps): react_jsx_runtime.JSX.Element;
 
 type FileBrowserProps = {
     /** From `useSandboxFiles(...)`. */
@@ -1815,35 +2312,42 @@ type FileBrowserProps = {
  */
 declare function FileBrowser({ result, fallback, onSelectFile, selectedPath, renderNode, emptyState, editable, confirmDelete, className, }: FileBrowserProps): react_jsx_runtime.JSX.Element;
 
-/** Theme tokens for the diff line backgrounds. */
+/**
+ * @deprecated Use {@link PierreDiff} directly. Retained only as a thin,
+ * back-compat alias that renders the Pierre (Shiki) renderer with a plain-text
+ * degrade. The old hand-rolled hunk renderer was removed in Workbench v2 — the
+ * workbench keeps exactly ONE diff renderer. This alias is removed next major.
+ */
 type DiffTheme = {
     addBackground?: string;
     delBackground?: string;
     contextBackground?: string;
     metaForeground?: string;
 };
+/**
+ * @deprecated Use {@link PierreDiff}. `theme`/`onSelectFile`/`emptyState` from the
+ * removed hand-rolled renderer are accepted for source compatibility and ignored;
+ * `fallback` still overrides the plain-text degrade.
+ */
 type DiffViewProps = {
-    /** From `useSandboxGit().diff` — the structured per-file hunks. */
     diff: GitFileDiff[];
-    /** Rendered instead of the built-in diff (the Pierre-swap escape hatch). */
     fallback?: ReactNode | undefined;
-    /** unified | split. Default "unified". */
     layout?: "unified" | "split" | undefined;
+    themeType?: "dark" | "light" | undefined;
+    /** @deprecated line-background theming was part of the removed renderer. */
     theme?: DiffTheme | undefined;
+    /** @deprecated the alias no longer renders a clickable file header. */
     onSelectFile?: ((path: string) => void) | undefined;
-    /** Distinguishes "no changes" from "no repository mounted". */
     isRepo?: boolean | undefined;
     emptyState?: ReactNode | undefined;
     className?: string | undefined;
 };
 /**
- * The diff view, fed by the Git service via `useSandboxGit().diff`. This is our
- * `PierreDiff` boundary: the built-in renderer delivers the same UX (per-file
- * hunks, unified or side-by-side, old/new line numbers, add/del counts), and a
- * consumer with Pierre's `@pierre/diffs` installed can swap it via `fallback`
- * while keeping the same `GitFileDiff[]` data contract from the hook.
+ * @deprecated Use {@link PierreDiff} directly. Thin alias: renders `PierreDiff`
+ * (Shiki-highlighted, unified/split) with a plain-text fallback for a host
+ * without `@pierre/diffs`. Removed next major.
  */
-declare function DiffView({ diff, fallback, layout, theme, onSelectFile, isRepo, emptyState, className, }: DiffViewProps): react_jsx_runtime.JSX.Element;
+declare function DiffView({ diff, fallback, layout, themeType, isRepo, emptyState, className, }: DiffViewProps): react_jsx_runtime.JSX.Element;
 
 type PierreDiffProps = {
     diff: GitFileDiff[];
@@ -1860,15 +2364,23 @@ type PierreDiffProps = {
     loading?: ReactNode | undefined;
     /** Rendered if `@pierre/diffs/react` is not installed / fails to import. */
     fallback?: ReactNode | undefined;
+    /** Skip the Shiki renderer entirely and show the plain-text degrade (the old
+     *  `usePierre={false}` path — one renderer, opted out of highlighting). */
+    plain?: boolean | undefined;
+    /** Long-line handling: `"wrap"` soft-wraps (the default — a diff in a narrow
+     *  dock pane should be readable without a horizontal-scroll tax), `"scroll"`
+     *  keeps lines on one row behind a horizontal scrollbar (better for a wide
+     *  viewport or pathological minified lines). */
+    overflow?: "wrap" | "scroll" | undefined;
     className?: string | undefined;
 };
 /**
  * The Pierre-backed diff: Shiki-highlighted, virtualized, unified/split. Renders
  * one `PatchDiff` per changed file (a reconstructed unified patch from the
- * `GitFileDiff` hunks). This sits behind `DiffView`'s `fallback` seam so a host
- * that lacks `@pierre/diffs` keeps the hand-rolled renderer.
+ * `GitFileDiff` hunks). The ONE workbench diff renderer; a host without
+ * `@pierre/diffs` gets the built-in plain-text degrade (`PlainPatch`).
  */
-declare function PierreDiff({ diff, layout, themeType, theme, disableWorkerPool, loading, fallback, className, }: PierreDiffProps): react_jsx_runtime.JSX.Element;
+declare function PierreDiff({ diff, layout, themeType, theme, disableWorkerPool, loading, fallback, plain, overflow, className, }: PierreDiffProps): react_jsx_runtime.JSX.Element;
 
 type PierreFileProps = {
     /** Workspace-relative path (used for the header + language inference). */
@@ -1908,6 +2420,10 @@ type CodeEditorProps = {
     initialContents: string;
     /** Persist the current buffer. Resolves when the write lands; rejects to surface an error. */
     onSave: (contents: string) => Promise<unknown>;
+    /** 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. */
+    onEditIntent?: (() => void) | undefined;
     /** Read-only mode (e.g. a truncated/too-large file shown for reference only). */
     readOnly?: boolean | undefined;
     themeType?: "dark" | "light" | undefined;
@@ -1929,33 +2445,38 @@ 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, readOnly, themeType, loading, fallback, className, }: CodeEditorProps): react_jsx_runtime.JSX.Element;
+declare function CodeEditor({ path, initialContents, onSave, onEditIntent, readOnly, themeType, loading, fallback, className, }: CodeEditorProps): react_jsx_runtime.JSX.Element;
 
 type SandboxFilesProps = {
     /** From `useSandboxFiles(...)`. */
     files: UseSandboxFilesResult;
-    /** From `useSandboxGit(...)` — the working-tree diff. */
+    /** From `useSandboxGit(...)` — drives the branch/dirty header only. */
     git: UseSandboxGitResult;
-    /** From a second `useSandboxGit(..., { staged: true })` — the staged diff. */
+    /** @deprecated Diffs live in the dedicated Changes tab now; accepted for
+     *  source-compat but unused (the Files surface is a browser + viewer). */
     stagedGit?: UseSandboxGitResult | undefined;
     /** Whether a FileSystem surface is advertised (drives the unavailable notice). */
     fileSystemAvailable?: boolean | undefined;
-    /** Use Pierre's Shiki-highlighted diff (default true; falls back to built-in). */
+    /** Use Pierre's Shiki highlighter for the viewer (default true; plain fallback). */
     usePierre?: boolean | undefined;
     /** Allow in-place editing of tree files (CodeMirror). Default true. When false
      *  the surface is review-only: every text file opens in the read-only viewer. */
     editable?: boolean | undefined;
+    /** Fired once when the user first edits an open file (wake-on-edit intent). The
+     *  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;
     themeType?: "dark" | "light" | undefined;
     className?: string | undefined;
 };
 /**
- * The review-first Files surface: a sticky branch/dirty header, a "Changes"
- * group (changed files vs HEAD, badged), the full lazy file tree for context,
- * and an inline diff pane below for the selected changed file. The agent
- * commits; the human reviews — there is no stage/commit/push UI here (power-git
- * lives in the terminal).
+ * The Files surface: a branch/dirty header, the full lazy file tree, and a
+ * viewer/editor pane for the selected file. This is the workspace BROWSER — pick
+ * a file to read or edit it. Diff review lives in the dedicated Changes tab (this
+ * 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, stagedGit, fileSystemAvailable, usePierre, editable, themeType, className, }: SandboxFilesProps): react_jsx_runtime.JSX.Element;
+declare function SandboxFiles({ files, git, fileSystemAvailable, usePierre, editable, onEditIntent, themeType, className, }: SandboxFilesProps): react_jsx_runtime.JSX.Element;
 
 type DesktopViewerProps = {
     /** The desktop cell of the negotiated capabilities (`capabilities.DesktopStream`). */
@@ -2058,6 +2579,13 @@ type WorkspaceDockProps = {
     /** Controlled collapsed state for hosts that expose their own dock toggle. */
     collapsed?: boolean | undefined;
     onCollapsedChange?: ((collapsed: boolean) => void) | undefined;
+    /** A status accessory pinned to the right of the tab strip, left of the
+     *  maximize/collapse controls (e.g. the machine-state chip). Renders in both
+     *  the docked header and the full-screen overlay header. */
+    headerAccessory?: ReactNode | undefined;
+    /** Optional host navigation shown at the start of the phone overlay header.
+     *  It is intentionally absent from desktop dock chrome. */
+    mobileLeadingControl?: ReactNode | undefined;
     /** Persisted layout id (localStorage key) for react-resizable-panels. */
     autoSaveId?: string | undefined;
     /** Default dock width as a percent of the session area. */
@@ -2066,7 +2594,102 @@ type WorkspaceDockProps = {
     maxSize?: number | undefined;
     className?: string | undefined;
 };
-declare function WorkspaceDock({ primary, tabs, activeTab, onActiveTabChange, collapsed: collapsedProp, onCollapsedChange, autoSaveId, defaultSize, minSize, maxSize, className, }: WorkspaceDockProps): react_jsx_runtime.JSX.Element;
+declare function WorkspaceDock({ primary, tabs, activeTab, onActiveTabChange, collapsed: collapsedProp, onCollapsedChange, headerAccessory, mobileLeadingControl, autoSaveId, defaultSize, minSize, maxSize, className, }: WorkspaceDockProps): react_jsx_runtime.JSX.Element;
+
+/** A host-routed notification (replaces the app-only `sonner` toast coupling). */
+type WorkspaceNotification = {
+    kind: "error" | "info";
+    message: string;
+};
+/** The workbench's canonical tab ids (a host injects extras around these). */
+declare const WORKBENCH_TAB_CHANGES = "changes";
+declare const WORKBENCH_TAB_FILES = "files";
+/**
+ * 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.
+ */
+declare function initialWorkspaceTab(events: SessionEvent[] | undefined, override?: string | null): string;
+type WorkspaceMachine = {
+    /** The derived live/waking/offline chip model (dossier §3 #10). */
+    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. */
+    activeMachine: MachineView | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+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. */
+    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;
+};
+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. */
+    defaultTab: string | null;
+    /** The machine-state model for the dock-header chip. */
+    machine: WorkspaceMachine;
+};
+/**
+ * Build the workbench tabs + the machine-chip model for one session. This is the
+ * dock "brain": capability negotiation, capture-backed cold reads, prewarm
+ * flags, desktop consent, and the xterm theme observer — all package-local.
+ */
+declare function useSandboxWorkspaceTabs(options: UseSandboxWorkspaceTabsOptions): UseSandboxWorkspaceTabsResult;
+type SandboxWorkspaceProps = ClientOverride & {
+    sessionId: string;
+    /** Live event log (usually `useSessionEvents().events`). */
+    events: SessionEvent[];
+    /** The chat / primary pane shown beside the dock. */
+    primary: ReactNode;
+    /** 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. */
+    initialTab?: string | undefined;
+    /** Host-routed notifications (no toast dependency in the package). */
+    onNotify?: ((notification: WorkspaceNotification) => void) | undefined;
+    /** Controlled collapsed state for hosts with their own dock toggle. */
+    collapsed?: boolean | undefined;
+    onCollapsedChange?: ((collapsed: boolean) => void) | undefined;
+    /** Host navigation shown only in the phone workspace overlay header. */
+    mobileLeadingControl?: ReactNode | undefined;
+    autoSaveId?: string | undefined;
+    defaultSize?: number | undefined;
+    minSize?: number | undefined;
+    maxSize?: number | undefined;
+    className?: string | undefined;
+};
+/**
+ * The whole session workspace, ready to mount: `<SandboxWorkspace>` assembles the
+ * capability-gated tabs, pins the machine-state chip in the dock header, and
+ * renders the resizable `<WorkspaceDock>`. Wrap the tree in `<OpenGeniProvider>`
+ * (client + workspaceId) and import `@opengeni/react/styles.css`; that is the
+ * entire integration (see `docs/embedding-workbench.md`).
+ */
+declare function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode;
 
 /** Events that change which Codex account a session runs on (or just ran). */
 declare function isCodexAccountEvent(event: Pick<SessionEvent, "type">): boolean;
@@ -2144,12 +2767,14 @@ declare function useCodexAccounts(options?: UseCodexAccountsOptions): UseCodexAc
 declare function gitFileDiffToPatch(file: GitFileDiff): string;
 
 /**
- * Derive an xterm `ITheme` subset from the live OKLCH `--og-*` token system.
- * Reads the COMPUTED values so xterm — which
- * paints into a canvas and can't consume CSS vars — gets concrete colors. Call
- * on mount and re-derive on a `data-og-theme` flip.
+ * Derive a COMPLETE xterm `ITheme` from the live `--og-*` token system on the
+ * DOM. Reads the COMPUTED values so xterm gets concrete colors, detects the
+ * active theme mode, and fills every ANSI slot. Call on mount + re-derive on a
+ * `data-og-theme` flip. SSR-safe: returns undefined off the DOM.
  *
- * SSR-safe: returns undefined off the DOM (the caller keeps xterm's defaults).
+ * `root` should be an element INSIDE the themed subtree (e.g. the terminal
+ * container) so nested `[data-og-theme]` themes resolve correctly; when omitted
+ * it falls back to the nearest `[data-og-theme]` element, then documentElement.
  */
 declare function xtermThemeFromTokens(root?: HTMLElement | null): XtermTheme | undefined;
 
@@ -2166,15 +2791,36 @@ declare function truncate(text: string, maxLength: number): string;
 declare function stringifyPayload(value: unknown): string;
 /** JSON.parse that returns `undefined` instead of throwing. */
 declare function tryParseJson(text: string): unknown;
+/**
+ * The canonical credit-death sentence. Credit exhaustion is the one failure a
+ * user can fix themselves — the copy must say what happened (empty balance),
+ * what to do (add credits), and what is safe (nothing was lost). Crucially it
+ * must NOT say "send a message to revive": a revive turn burns credits the
+ * workspace no longer has.
+ */
+declare const CREDIT_EXHAUSTION_MESSAGE = "Out of OpenGeni credits \u2014 this workspace's balance is empty. Add credits to continue; the conversation is preserved.";
+/**
+ * Does this failure/completion payload (or raw error string) mean the
+ * workspace ran out of OpenGeni credits? Matches the engine's
+ * "insufficient OpenGeni credits" text (case-insensitive, substring — it
+ * arrives both bare and wrapped in "Activity task failed: …") and the
+ * budget-exhausted segment limit the engine stamps on a turn it ended early.
+ */
+declare function isCreditExhaustion(input: {
+    error?: string | null;
+    detail?: string | null;
+    segmentLimit?: string | null;
+} | string): boolean;
 /**
  * Humanize engine/provider failure text before it reaches the timeline or a
  * failure banner. Raw provider errors leak the wrong audience's instructions —
  * "Incorrect API key … find your API key at platform.openai.com" tells a
  * managed-deployment USER to fix credentials only an OPERATOR controls (and is
- * flatly wrong for Azure or subscription-backed engines). Auth and quota
- * failures collapse to one neutral, honest sentence; every other reason passes
- * through untouched. Raw payloads stay available in the debug surfaces.
+ * flatly wrong for Azure or subscription-backed engines). Auth, quota, and
+ * credit-exhaustion failures collapse to one neutral, honest sentence; every
+ * other reason passes through untouched. Raw payloads stay available in the
+ * debug surfaces.
  */
 declare function humanizeFailureReason(reason: string | null): string | null;
 
-export { ActivityDisclosure, type ActivityDisclosureProps, type ActivityItem, ActivityRail, type ActivityRailProps, type AgentMessageItem, type ApplyPatchOperation, BodyNote, 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, 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, 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, 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 UsePacksOptions, type UsePacksResult, type UseRelayFrameStreamOptions, type UseRelayFrameStreamResult, type UseSandboxFilesOptions, type UseSandboxFilesResult, type UseSandboxGitOptions, type UseSandboxGitResult, type UseSandboxTerminalOptions, type UseSandboxTerminalResult, type UseScheduledTasksOptions, type UseScheduledTasksResult, type UseSessionCapabilitiesOptions, type UseSessionCapabilitiesResult, type UseSessionControlOptions, type UseSessionControlResult, type UseSessionEventsOptions, type UseSessionEventsResult, type UseSessionOptions, type UseSessionResult, type UseSlashCommandsOptions, type UseSlashCommandsResult, type UseTerminalStreamOptions, type UseTerminalStreamResult, type UseTurnQueueOptions, type UseTurnQueueResult, type UseWorkspaceSessionsOptions, type UseWorkspaceSessionsResult, type UseWorkspacesOptions, type UseWorkspacesResult, type UserMessageItem, type WorkerItem, WorkspaceDock, type WorkspaceDockProps, type WorkspaceTab, type XtermTheme, activeTurnFromTurns, applyPatchOps, applyTurnEdit, applyTurnRemoval, applyTurnReorder, approvalsFromRequiresAction, argHint, buildTimeline, cn, composeSendInput, controlCaret, createDefaultToolRegistry, createToolRegistry, defaultCommands, defaultToolRegistry, execTruncated, extractSessionRef, filterCommands, firstMissingRequiredArg, formatBytes, formatRelativeTime, gitFileDiffToPatch, groupTimeline, hasPermission, humanizeFailureReason, isApplyPatch, isCodexAccountEvent, isExecSessionLostBanner, isGoalEvent, isTitleEvent, isTurnQueueEvent, languageForPath, looksBinary, matchCommand, parseCommandLine, parseExecBannerSessionId, parseToolArgs, projectPendingApprovals, queueFromTurns, rawTypeOf, redactSecrets, sandboxCommandExitCode, sessionDisplayTitle, sessionStatusFromEvents, shouldSubmitOnKey, stringifyPayload, stripExecBanner, tailPeek, toolDisplayName, truncate, tryParseJson, unwrapMcpOutput, useAvailableModels, useBillingUsage, useCodexAccounts, useComposer, useDesktopStream, useEnvironments, useFileAttachments, useGoal, useLightbox, useLightboxOptional, usePacks, useRelayFrameStream, useSandboxFiles, useSandboxGit, useSandboxTerminal, useScheduledTasks, useSession, useSessionCapabilities, useSessionControl, useSessionEvents, useSlashCommands, useTerminalStream, useTurnQueue, useWorkspaceSessions, useWorkspaces, v4aToGitFileDiff, xtermThemeFromTokens };
+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 };