@robota-sdk/agent-ui-terminal 3.0.0-beta.100

package/src/hooks/useAppThemeState.ts

@@ -0,0 +1,157 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import { createThemeRegistry, formatUnknownThemeNotice } from '../theme/theme-registry.js';
+
+import type { ITuiTheme } from '../theme/theme-contracts.js';
+import type { IThemeRegistry, IThemeSkip } from '../theme/theme-registry.js';
+import type {
+  IAppearanceSettings,
+  IThemeAppearanceState,
+  TReducedMotionOverride,
+} from '@robota-sdk/agent-interface-command';
+
+/** The tier that pinned motion for this run and what it pinned — the contract's own pair. */
+type IReducedMotionPin = NonNullable<IThemeAppearanceState['reducedMotionPin']>;
+
+export interface IThemeToggles {
+  readonly syntaxHighlighting: boolean;
+  readonly reducedMotion: boolean;
+}
+
+export interface IAppThemePickerViewModel {
+  readonly visible: boolean;
+  readonly themes: readonly ITuiTheme[];
+  /** Theme files that were found and refused — shown as rows that cannot be chosen. */
+  readonly skipped: readonly IThemeSkip[];
+  /** The id that is PERSISTED — the row the picker returns to when it is cancelled. */
+  readonly activeThemeId: string;
+  /** The PERSISTED toggles the picker seeds itself from and submits alongside the theme. */
+  readonly syntaxHighlighting: boolean;
+  readonly reducedMotion: boolean;
+  /**
+   * Set when a tier above the settings pinned motion for this run — the tier AND what it pinned,
+   * as one value, for the reason `IThemeAppearanceState` states: the tier alone cannot say which
+   * way a run went.
+   */
+  readonly reducedMotionPin?: IReducedMotionPin | undefined;
+  /** Move the highlight: the live region re-renders in that theme, nothing is written. */
+  readonly preview: (id: string) => void;
+  /**
+   * Commit: submits `/theme <id> syntax <on|off> motion <on|off>` — ONE patch through the command
+   * path, because the HOST owns writing the settings document. Three separate submissions would be
+   * three chances to half-apply what the user saw as one decision.
+   */
+  readonly select: (id: string, toggles: IThemeToggles) => void;
+  /** Leave: the preview is dropped and the persisted theme is what remains. */
+  readonly cancel: () => void;
+}
+
+export interface IAppThemeViewModel {
+  /** The theme every component renders with right now — the preview when one is open. */
+  readonly resolved: ITuiTheme;
+  /** Whether motion is suppressed for this run, after the flag/env/settings chain. */
+  readonly reducedMotion: boolean;
+  /** Whether fenced code blocks are highlighted. Every markdown render site reads this. */
+  readonly syntaxHighlighting: boolean;
+  /** Present once, when the persisted id names a theme this build does not have. */
+  readonly unknownThemeNotice?: string;
+  readonly picker: IAppThemePickerViewModel;
+}
+
+interface IOptions {
+  readonly appearance: IAppearanceSettings;
+  readonly registry?: IThemeRegistry | undefined;
+  readonly reducedMotion?: boolean | undefined;
+  /** Which tier decided it, when that was not the settings. */
+  readonly reducedMotionOverride?: TReducedMotionOverride | undefined;
+  readonly visible: boolean;
+  readonly setVisible: (visible: boolean) => void;
+  readonly submit: (input: string) => void;
+}
+
+/**
+ * SCREEN-2002 — which theme the live region renders with, and the picker over it.
+ *
+ * Two inputs, one answer. The PERSISTED appearance is the baseline; a preview is a local overlay
+ * that exists only while the picker is open. Selecting does not write — it submits `/theme <id>`,
+ * so the host applies the patch and the refresh-on-result path re-reads it. That keeps ONE writer
+ * for the settings document and means the picker cannot persist something `/theme` would refuse.
+ *
+ * `reducedMotion` arrives already resolved from the CLI (settings ← env ← flag). It is not
+ * recomputed here, because a second place deciding the same question is how the two start
+ * disagreeing — and it is still not the final say: `useMotion()` gates on the colour gate and
+ * screen-reader mode above it.
+ */
+export function useAppThemeState(options: IOptions): IAppThemeViewModel {
+  const registry = useMemo(() => options.registry ?? createThemeRegistry(), [options.registry]);
+  const [previewId, setPreviewId] = useState<string | undefined>(undefined);
+  const resolution = useMemo(
+    () => registry.resolve(previewId ?? options.appearance.theme),
+    [registry, previewId, options.appearance.theme],
+  );
+
+  const { setVisible, submit } = options;
+  const cancel = useCallback((): void => {
+    setPreviewId(undefined);
+    setVisible(false);
+  }, [setVisible]);
+  const { syntaxHighlighting, reducedMotion } = options.appearance;
+  const select = useCallback(
+    (id: string, toggles: IThemeToggles): void => {
+      setPreviewId(undefined);
+      setVisible(false);
+      const parts = [`/theme ${id}`];
+      // Only what the user actually CHANGED. Sending all three would make choosing a theme report
+      // "syntax highlighting on, motion on" as applied to someone who touched neither — and on a
+      // run with a reduced-motion flag it would also drag out the pinned-for-this-run notice for a
+      // setting they never asked about.
+      if (toggles.syntaxHighlighting !== syntaxHighlighting) {
+        parts.push(`syntax ${toggles.syntaxHighlighting ? 'on' : 'off'}`);
+      }
+      if (toggles.reducedMotion !== reducedMotion) {
+        // `motion on` means ANIMATE, which is `reducedMotion: false` — the inversion lives in the
+        // command's parser, and this is the one place that has to speak its vocabulary.
+        parts.push(`motion ${toggles.reducedMotion ? 'off' : 'on'}`);
+      }
+      submit(parts.join(' '));
+    },
+    [reducedMotion, setVisible, submit, syntaxHighlighting],
+  );
+
+  // A preview of an unknown id is impossible (the rows come from the registry), so the notice can
+  // only be about what is PERSISTED — and it is suppressed while previewing so it does not read as
+  // a complaint about the row the user is looking at.
+  const unknownId = previewId === undefined ? resolution.unknownId : undefined;
+  // One expression for "what motion IS for this run", read by both the view model and the picker:
+  // two copies of the same `??` chain are two things to keep in step.
+  const reducedMotionForRun = options.reducedMotion ?? options.appearance.reducedMotion;
+  return {
+    resolved: resolution.theme,
+    reducedMotion: reducedMotionForRun,
+    syntaxHighlighting: options.appearance.syntaxHighlighting,
+    ...(unknownId === undefined ? {} : { unknownThemeNotice: formatUnknownThemeNotice(unknownId) }),
+    picker: {
+      visible: options.visible,
+      themes: registry.list(),
+      skipped: registry.skipped(),
+      activeThemeId: options.appearance.theme,
+      syntaxHighlighting: options.appearance.syntaxHighlighting,
+      reducedMotion: options.appearance.reducedMotion,
+      // Both halves or neither. A tier with no resolved value would have to be paired with the
+      // PERSISTED one, which is the contradiction this pair exists to stop — so a caller that
+      // supplies only the tier gets no pin rather than a wrong one, and the row simply says
+      // nothing about a pin instead of naming the wrong direction.
+      ...(options.reducedMotionOverride === undefined || options.reducedMotion === undefined
+        ? {}
+        : {
+            reducedMotionPin: {
+              tier: options.reducedMotionOverride,
+              reducedMotion: options.reducedMotion,
+            },
+          }),
+      preview: setPreviewId,
+      select,
+      cancel,
+    },
+  };
+}

package/src/hooks/useAppWorkspaceState.ts

@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import {
+  countActiveBackgroundWorkspaceEntries,
+  getDefaultBackgroundWorkspaceEntries,
+} from '../execution-workspace-view-model.js';
+import { useBackgroundPanel } from './useBackgroundPanel.js';
+import { resolveBackgroundFocusKey } from '../flows/background-focus-flow.js';
+import { useKeybindingActions } from '../keybindings/keybindings-context.js';
+
+import type { IAppBackgroundViewModel } from '../app-view-model.js';
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+
+export interface IAppWorkspaceState {
+  readonly background: IAppBackgroundViewModel;
+  readonly activeBackgroundTaskCount: number;
+  readonly activeAgentLabel: string | undefined;
+  readonly mainThreadEntryId: string | undefined;
+  readonly isSelectedEntryInteractive: boolean;
+  readonly isBackgroundListFocused: boolean;
+  readonly openSwitcher: () => void;
+  readonly toggleSwitcher: () => void;
+  readonly focusBackgroundList: () => void;
+}
+
+interface IOptions {
+  readonly snapshot: IExecutionWorkspaceSnapshot | null;
+  readonly selectedEntryId: string | undefined;
+  readonly select: (entryId: string) => void;
+  readonly read: (entryId: string) => Promise<IExecutionDetailPage>;
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  readonly onSessionSwitch: (sessionId: string) => Promise<void>;
+  readonly addEntry: (entry: IHistoryEntry) => void;
+  readonly navigationEnabled: boolean;
+  readonly switcherVisible: boolean;
+  readonly setSwitcherVisible: (visible: boolean | ((current: boolean) => boolean)) => void;
+}
+
+interface ISwitcherActions {
+  readonly open: () => void;
+  readonly toggle: () => void;
+  readonly close: () => void;
+}
+
+function useBackgroundListKeys(
+  focusedIndex: number | null,
+  entryIds: readonly string[],
+  setFocusedIndex: (index: number | null) => void,
+  select: (entryId: string) => void,
+  enabled: boolean,
+): void {
+  useKeybindingActions(
+    'background-list',
+    (actions) => {
+      if (focusedIndex === null) return;
+      const action = resolveBackgroundFocusKey(focusedIndex, entryIds.length, {
+        upArrow: actions.includes('previous'),
+        downArrow: actions.includes('next'),
+        return: actions.includes('open'),
+        escape: actions.includes('close'),
+      });
+      if (action.type === 'move') setFocusedIndex(action.index);
+      if (action.type === 'open') {
+        const entryId = entryIds[action.index];
+        if (entryId) select(entryId);
+        setFocusedIndex(null);
+      }
+      if (action.type === 'exit') setFocusedIndex(null);
+    },
+    { isActive: focusedIndex !== null && enabled },
+  );
+}
+
+function useBackgroundFocus(
+  entryIds: readonly string[],
+  select: (entryId: string) => void,
+  enabled: boolean,
+): { focusedIndex: number | null; focusList: () => void } {
+  const [focusedIndex, setFocusedIndex] = useState<number | null>(null);
+  useEffect(() => {
+    setFocusedIndex((index) => {
+      if (index === null || entryIds.length === 0) return null;
+      return Math.min(index, entryIds.length - 1);
+    });
+  }, [entryIds.length]);
+  useBackgroundListKeys(focusedIndex, entryIds, setFocusedIndex, select, enabled);
+  const focusList = useCallback(() => {
+    if (entryIds.length > 0) setFocusedIndex(0);
+  }, [entryIds.length]);
+  return { focusedIndex, focusList };
+}
+
+function useSwitcherActions(setVisible: IOptions['setSwitcherVisible']): ISwitcherActions {
+  const open = useCallback(() => setVisible(true), [setVisible]);
+  const toggle = useCallback(() => setVisible((visible) => !visible), [setVisible]);
+  const close = useCallback(() => setVisible(false), [setVisible]);
+  return { open, toggle, close };
+}
+
+export function useAppWorkspaceState(options: IOptions): IAppWorkspaceState {
+  const entries = useMemo(
+    () => getDefaultBackgroundWorkspaceEntries(options.snapshot),
+    [options.snapshot],
+  );
+  const { focusedIndex, focusList } = useBackgroundFocus(
+    entries.map((entry) => entry.id),
+    options.select,
+    options.navigationEnabled,
+  );
+
+  const panel = useBackgroundPanel({
+    selectedEntryId: options.selectedEntryId,
+    snapshot: options.snapshot,
+    read: options.read,
+    sessionStore: options.sessionStore,
+    onSessionSwitch: options.onSessionSwitch,
+    addEntry: options.addEntry,
+  });
+  const switcher = useSwitcherActions(options.setSwitcherVisible);
+  const selected = panel.entry;
+  return {
+    background: {
+      entries,
+      focusedIndex,
+      selectedEntry: selected,
+      detail: panel.detail,
+      switcherVisible: options.switcherVisible,
+      snapshot: options.snapshot,
+      selectedEntryId: options.selectedEntryId,
+      select: options.select,
+      closeSwitcher: switcher.close,
+      attachToFork: panel.attachToFork,
+    },
+    activeBackgroundTaskCount: countActiveBackgroundWorkspaceEntries(options.snapshot),
+    activeAgentLabel: selected?.kind === 'main_thread' ? undefined : selected?.title,
+    mainThreadEntryId: options.snapshot?.entries.find((entry) => entry.kind === 'main_thread')?.id,
+    isSelectedEntryInteractive:
+      !selected || selected.kind === 'main_thread' || selected.controls.includes('send'),
+    isBackgroundListFocused: focusedIndex !== null,
+    openSwitcher: switcher.open,
+    toggleSwitcher: switcher.toggle,
+    focusBackgroundList: focusList,
+  };
+}

package/src/hooks/useAppearanceSettings.ts

@@ -0,0 +1,30 @@
+import { readAppearanceSettings } from '@robota-sdk/agent-framework';
+import { useCallback, useState } from 'react';
+
+import { useTuiCliAdapter } from '../tui-cli-adapter-context.js';
+
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { IAppearanceSettings } from '@robota-sdk/agent-interface-command';
+
+function readFromAdapter(cliAdapter: ITuiCliAdapter): IAppearanceSettings {
+  return readAppearanceSettings(cliAdapter.readSettings(cliAdapter.getUserSettingsPath()));
+}
+
+/**
+ * SCREEN-2002 — the persisted appearance, plus a from-disk `refresh()`.
+ *
+ * Refresh-on-result, the shape `useStatusLineSettings` already uses: the HOST applies
+ * `appearance-settings-patch` through the settings adapter, so the renderer learns about a change by
+ * RE-READING the document when a command result arrives. The TUI never writes these keys itself,
+ * which is what keeps one writer for one file.
+ */
+export function useAppearanceSettings(): [IAppearanceSettings, () => void] {
+  const cliAdapter = useTuiCliAdapter();
+  const [appearance, setAppearance] = useState<IAppearanceSettings>(() =>
+    readFromAdapter(cliAdapter),
+  );
+  const refresh = useCallback((): void => {
+    setAppearance(readFromAdapter(cliAdapter));
+  }, [cliAdapter]);
+  return [appearance, refresh];
+}

package/src/hooks/useAutocomplete.ts

@@ -0,0 +1,101 @@
+/**
+ * Slash command autocomplete hook.
+ * Extracted from InputArea.tsx for single-responsibility.
+ */
+
+import React, { useState, useMemo, useEffect } from 'react';
+
+import type { ITuiCommandQueryPort } from '../tui-app-channel-port.js';
+import type { ICommand } from '@robota-sdk/agent-interface-command';
+
+/** Parse input to determine autocomplete state */
+function parseSlashInput(value: string): {
+  isSlash: boolean;
+  parentCommand: string;
+  filter: string;
+} {
+  if (!value.startsWith('/')) return { isSlash: false, parentCommand: '', filter: '' };
+  const afterSlash = value.slice(1);
+  const spaceIndex = afterSlash.indexOf(' ');
+  if (spaceIndex === -1) return { isSlash: true, parentCommand: '', filter: afterSlash };
+  const parent = afterSlash.slice(0, spaceIndex);
+  const rest = afterSlash.slice(spaceIndex + 1);
+  return { isSlash: true, parentCommand: parent, filter: rest };
+}
+
+/** Hook: manage autocomplete state */
+export function useAutocomplete(
+  value: string,
+  commandQueryPort: ITuiCommandQueryPort | undefined,
+): {
+  showPopup: boolean;
+  filteredCommands: ICommand[];
+  selectedIndex: number;
+  setSelectedIndex: React.Dispatch<React.SetStateAction<number>>;
+  isSubcommandMode: boolean;
+  setShowPopup: React.Dispatch<React.SetStateAction<boolean>>;
+} {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [dismissed, setDismissed] = useState(false);
+
+  // Reset dismissed when input changes
+  const prevValueRef = React.useRef(value);
+  if (prevValueRef.current !== value) {
+    prevValueRef.current = value;
+    if (dismissed) setDismissed(false);
+  }
+
+  const parsed = parseSlashInput(value);
+  const isSubcommandMode = parsed.isSlash && parsed.parentCommand.length > 0;
+
+  const previousParentCommandRef = React.useRef(parsed.parentCommand);
+  useEffect(() => {
+    if (previousParentCommandRef.current === parsed.parentCommand) return;
+    previousParentCommandRef.current = parsed.parentCommand;
+    setSelectedIndex(0);
+  }, [parsed.parentCommand]);
+
+  const filteredCommands = useMemo(() => {
+    if (!commandQueryPort || !parsed.isSlash || dismissed) return [];
+    if (isSubcommandMode) {
+      const subs = commandQueryPort.getSubcommands(parsed.parentCommand);
+      if (subs.length === 0) return [];
+      if (!parsed.filter) return subs;
+      const lower = parsed.filter.toLowerCase();
+      return subs.filter((c) => c.name.toLowerCase().startsWith(lower));
+    }
+    return commandQueryPort.getCommands(parsed.filter);
+  }, [
+    commandQueryPort,
+    parsed.isSlash,
+    parsed.parentCommand,
+    parsed.filter,
+    dismissed,
+    isSubcommandMode,
+  ]);
+
+  const showPopup = parsed.isSlash && filteredCommands.length > 0 && !dismissed;
+
+  // Clamp selectedIndex
+  if (selectedIndex >= filteredCommands.length && filteredCommands.length > 0) {
+    setSelectedIndex(filteredCommands.length - 1);
+  }
+
+  return {
+    showPopup,
+    filteredCommands,
+    selectedIndex,
+    setSelectedIndex,
+    isSubcommandMode,
+    setShowPopup: (val) => {
+      if (typeof val === 'function') {
+        setDismissed((prev) => {
+          const nextVal = (val as (prev: boolean) => boolean)(!prev);
+          return !nextVal;
+        });
+      } else {
+        setDismissed(!val);
+      }
+    },
+  };
+}

package/src/hooks/useBackgroundPanel.ts

@@ -0,0 +1,58 @@
+/**
+ * The background panel's two data concerns as one call: what the selected entry's detail page says,
+ * and what happens when the operator attaches to a forked one.
+ *
+ * Both belong to the same surface and both are read by the same component, so `App` asks for them
+ * once rather than wiring two hooks whose inputs it has to keep in step. Split out because CLI-2004
+ * had already brought `App.tsx` to its size budget by extracting the detail read, and CLI-1994 adds
+ * the attach handler beside it — growing the file was the alternative the size rule forbids.
+ */
+
+import { useMemo } from 'react';
+
+import { useExecutionDetailPage } from './useExecutionDetailPage.js';
+import { useForkAttach } from './useForkAttach.js';
+
+import type { IExecutionDetailState } from './useExecutionDetailPage.js';
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+
+export interface IUseBackgroundPanelOptions {
+  /** Which entry the switcher has selected; resolved against the snapshot below. */
+  readonly selectedEntryId: string | undefined;
+  /** The panel's data, and the re-read trigger — the detail follows a running task's output. */
+  readonly snapshot: IExecutionWorkspaceSnapshot | null;
+  readonly read: (entryId: string) => Promise<IExecutionDetailPage>;
+  /** Absent ⇒ this surface cannot open another session's record, and attach says so. */
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  readonly onSessionSwitch: (sessionId: string) => void;
+  readonly addEntry: (entry: IHistoryEntry) => void;
+}
+
+export interface IBackgroundPanel {
+  /** The selected entry itself, which the switcher and the detail view both render. */
+  readonly entry: IExecutionWorkspaceEntry | undefined;
+  readonly detail: IExecutionDetailState;
+  readonly attachToFork: (entry: IExecutionWorkspaceEntry) => void;
+}
+
+/** Wire the background panel's detail read and its attach handler together. */
+export function useBackgroundPanel(inputs: IUseBackgroundPanelOptions): IBackgroundPanel {
+  const { snapshot, selectedEntryId } = inputs;
+  const entry = useMemo(
+    () => snapshot?.entries.find((candidate) => candidate.id === selectedEntryId),
+    [snapshot, selectedEntryId],
+  );
+  const detail = useExecutionDetailPage({ entry, snapshot, read: inputs.read });
+  const attachToFork = useForkAttach({
+    sessionStore: inputs.sessionStore,
+    onSessionSwitch: inputs.onSessionSwitch,
+    addEntry: inputs.addEntry,
+  });
+  return { entry, detail, attachToFork };
+}

package/src/hooks/useCountdownTick.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from 'react';
+
+import { MS_PER_SECOND } from '../attention/time-units.js';
+
+/** SCREEN-1992: one second, the resolution a `in 59s` countdown is read at. */
+const COUNTDOWN_TICK_MS = MS_PER_SECOND;
+
+/**
+ * The clock a sleeping schedule's countdown is rendered against. Re-renders once a second only while
+ * `active` (an entry carries `nextFireAt`) and not in screen-reader mode — a reader would otherwise
+ * hear the row change every second. When not ticking the clock is still the CURRENT one on every
+ * render (never the mount-time seed): a reader gets a correct number, read once.
+ */
+export function useCountdownTick(active: boolean, screenReader: boolean): Date {
+  const ticking = active && !screenReader;
+  const [tickedAt, setTickedAt] = useState(() => new Date());
+  useEffect(() => {
+    if (!ticking) return undefined;
+    setTickedAt(new Date());
+    const timer = setInterval(() => setTickedAt(new Date()), COUNTDOWN_TICK_MS);
+    return () => clearInterval(timer);
+  }, [ticking]);
+  return ticking ? tickedAt : new Date();
+}

package/src/hooks/useExecutionDetailPage.ts

@@ -0,0 +1,69 @@
+/**
+ * Loads the inline detail page for the selected background-execution entry.
+ *
+ * Extracted from `App.tsx` (CLI-2004): three pieces of state and one async effect that exist only
+ * for the detail pane, sitting in the middle of the component's input handlers. One responsibility,
+ * one module — and the App keeps room for the concerns that actually belong to it.
+ */
+
+import { useEffect, useState } from 'react';
+
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+
+export interface IExecutionDetailState {
+  page: IExecutionDetailPage | null;
+  error: string | undefined;
+  loading: boolean;
+}
+
+export interface IUseExecutionDetailPageInputs {
+  /** The selected entry, or undefined / the main thread when no detail is shown. */
+  entry: IExecutionWorkspaceEntry | undefined;
+  /** Re-read trigger: the snapshot the entry came from. */
+  snapshot: IExecutionWorkspaceSnapshot | null;
+  read: (entryId: string) => Promise<IExecutionDetailPage>;
+}
+
+/** Load (and cancel-on-change) the detail page for the selected entry. */
+export function useExecutionDetailPage(
+  inputs: IUseExecutionDetailPageInputs,
+): IExecutionDetailState {
+  const [page, setPage] = useState<IExecutionDetailPage | null>(null);
+  const [error, setError] = useState<string | undefined>();
+  const [loading, setLoading] = useState(false);
+  const { entry, snapshot, read } = inputs;
+
+  useEffect(() => {
+    if (!entry || entry.kind === 'main_thread') {
+      setPage(null);
+      setError(undefined);
+      setLoading(false);
+      return;
+    }
+
+    let isCurrent = true;
+    setLoading(true);
+    setError(undefined);
+    read(entry.id)
+      .then((loaded) => {
+        if (!isCurrent) return;
+        setPage(loaded);
+        setLoading(false);
+      })
+      .catch((cause: Error) => {
+        if (!isCurrent) return;
+        setError(cause.message);
+        setLoading(false);
+      });
+
+    return () => {
+      isCurrent = false;
+    };
+  }, [snapshot, read, entry]);
+
+  return { page, error, loading };
+}

package/src/hooks/useForkAttach.ts

@@ -0,0 +1,60 @@
+/**
+ * CLI-1994: the App's `attach` handler, as a hook rather than another closure inside `App.tsx`.
+ *
+ * `App.tsx` is a file the size floor has already frozen as debt, where the rule is "split instead of
+ * extending" — so the handler lives beside the other App hooks. The decision itself is neither here
+ * nor there: `attachToForkedSession` asks the framework, which owns when `attach` is offered and
+ * when it is honoured.
+ */
+
+import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+import { useCallback } from 'react';
+
+import { attachToForkedSession } from '../flows/fork-attach-flow.js';
+import { useTuiCliAdapter } from '../tui-cli-adapter-context.js';
+
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+
+export interface IUseForkAttachOptions {
+  /** Absent when the surface persists nothing; attach then refuses, saying so. */
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  /** The surface's session-switch path — the same one the session picker takes. */
+  readonly onSessionSwitch: (sessionId: string) => void;
+  /** Where a refusal is written, so it reaches the operator instead of disappearing. */
+  readonly addEntry: (entry: IHistoryEntry) => void;
+}
+
+/**
+ * Attach to a forked conversation: point this terminal at the fork's own session record. A VIEW
+ * switch, never a merge — the parent's record is not read, written or joined either way.
+ */
+export function useForkAttach({
+  sessionStore,
+  onSessionSwitch,
+  addEntry,
+}: IUseForkAttachOptions): (entry: IExecutionWorkspaceEntry) => void {
+  const cliAdapter = useTuiCliAdapter();
+  return useCallback(
+    (entry: IExecutionWorkspaceEntry): void => {
+      const notify = (message: string): void =>
+        addEntry(messageToHistoryEntry(createSystemMessage(message)));
+      // A surface composed without a session store cannot open another session's record. Said
+      // plainly rather than reported as "the record is missing", which is a different fact.
+      if (sessionStore === undefined) {
+        notify('This surface has no session store, so it cannot attach to a forked session.');
+        return;
+      }
+      attachToForkedSession(entry, {
+        hasSessionRecord: (sessionId) => sessionStore.load(sessionId).status === 'valid',
+        switchSession: onSessionSwitch,
+        notify,
+        ...(cliAdapter.formatResumeCommand === undefined
+          ? {}
+          : { formatResumeCommand: cliAdapter.formatResumeCommand }),
+      });
+    },
+    [addEntry, cliAdapter, onSessionSwitch, sessionStore],
+  );
+}