@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/client/hooks/chat/timeline/timeline-rail.test.ts

@@ -0,0 +1,259 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The timeline's two scroll/index behaviours, both of which are about a WINDOW
+ * of a long session rather than about the messages on screen:
+ *
+ * - The jump rail lists the FULL session's user turns (`/api/chat/:id/turns`),
+ *   because the mounted window holds only the newest slice. Live rows the
+ *   committed index does not carry yet (an optimistic send) are appended with
+ *   `index: -1` — dropping them would make the rail lag one turn behind the
+ *   composer, and asking the pager to reach them would page history for a row
+ *   that is already on screen. Until the index lands the mounted rows ARE the
+ *   rail, so a chat that already shows turns never renders an empty one.
+ * - Opening a session jumps to its tail exactly ONCE, on the commit where that
+ *   session's messages appear — not on the commit where the id flips, where the
+ *   DOM still holds the previous session's rows — and the jump is the
+ *   unconditional `jumpToBottom('instant')` rather than the follow-gated one,
+ *   because follow mode belongs to this mounted view, not to the session.
+ */
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { useUserTurns, type UserTurnsState } from '@/client/hooks/chat/timeline/user-turns';
+import { useTimelineAutoScroll } from '@/client/hooks/chat/timeline/auto-scroll';
+import { TURN_PREVIEW_CHARS } from '@/shared/lib/chat/timeline/turns';
+import type { ChatMessageData } from '@/shared/types';
+
+const DOM_GLOBALS = ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event', 'CustomEvent'] as const;
+/** The runner's own globals, restored on teardown so later files still have them. */
+const native: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+
+/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
+const originalFetch = Bun.fetch;
+let container: HTMLElement | undefined;
+
+beforeAll(() => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in native)) native[key] = target[key];
+    target[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+});
+
+afterAll(() => {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (native[key] === undefined) delete target[key];
+    else target[key] = native[key];
+  }
+  globalThis.fetch = originalFetch;
+});
+
+afterEach(() => {
+  if (container) render(null, container);
+  container?.remove();
+  globalThis.fetch = originalFetch;
+  delete (document as unknown as Record<string, unknown>).getElementById;
+});
+
+async function drain(): Promise<void> {
+  for (let i = 0; i < 8; i += 1) await act(async () => {});
+}
+
+/** Timeline rows in this file are only ever user prompts; the builder exists so
+ *  every case states which turn it is about, not how a row is shaped. */
+function userMessage(id: string, content: string): ChatMessageData {
+  return { id, role: 'user', content };
+}
+
+describe('useUserTurns', () => {
+  let rail: UserTurnsState | undefined;
+  const turnsRequests: string[] = [];
+  const scrolled: string[] = [];
+  let committed: { turns?: unknown } | null = { turns: [] };
+
+  function RailProbe({ sessionId, messages, jumpToTurn }: {
+    sessionId: string | null;
+    messages: ChatMessageData[];
+    jumpToTurn: (id: string, index: number) => Promise<boolean>;
+  }) {
+    rail = useUserTurns({ sessionId, messages, jumpToTurn });
+    return null;
+  }
+
+  beforeEach(() => {
+    rail = undefined;
+    turnsRequests.length = 0;
+    scrolled.length = 0;
+    committed = { turns: [] };
+    globalThis.fetch = (async (input: unknown) => {
+      turnsRequests.push(String(input));
+      if (committed === null) return new Response('no', { status: 500 });
+      return new Response(JSON.stringify(committed), { status: 200, headers: { 'content-type': 'application/json' } });
+    }) as typeof fetch;
+    (document as unknown as Record<string, unknown>).getElementById = () => ({
+      scrollIntoView: (opts: unknown) => { scrolled.push(JSON.stringify(opts)); },
+    });
+  });
+
+  async function open(sessionId: string | null, messages: ChatMessageData[], jumpToTurn = async () => true): Promise<void> {
+    container ??= document.body.appendChild(document.createElement('div'));
+    await act(async () => { render(h(RailProbe, { sessionId, messages, jumpToTurn }), container as HTMLElement); });
+    await drain();
+  }
+
+  test('the mounted rows are the rail until the committed index lands', async () => {
+    const long = 'x'.repeat(TURN_PREVIEW_CHARS + 50);
+    committed = { turns: [] };
+    await open('s1', [userMessage('u1', long), { id: 'a1', role: 'ai', content: 'hi' }]);
+    expect(turnsRequests).toEqual(['/api/chat/s1/turns']);
+    expect(rail?.turns).toEqual([
+      { id: 'u1', index: -1, preview: long.slice(0, TURN_PREVIEW_CHARS), date: undefined, timestamp: undefined },
+    ]);
+  });
+
+  test('the committed index is used and a live row it does not carry is appended', async () => {
+    committed = { turns: [{ id: 'u1', index: 0, preview: 'old' }] };
+    await open('s1', [userMessage('u1', 'old'), userMessage('u2', 'live')]);
+    expect(rail?.turns.map((turn) => turn.id)).toEqual(['u1', 'u2']);
+    expect(rail?.turns[1].index).toBe(-1);
+  });
+
+  test('a row the index already carries is not duplicated', async () => {
+    committed = { turns: [{ id: 'u1', index: 4, preview: 'old' }] };
+    await open('s1', [userMessage('u1', 'old')]);
+    expect(rail?.turns).toHaveLength(1);
+    expect(rail?.turns[0].index).toBe(4);
+  });
+
+  /**
+   * A sent turn lives under TWO ids for a moment: the optimistic bubble the
+   * composer mounted (`msg-…-user`) and the id omp echoed for the same request.
+   * The `/turns` index reports the echoed id as soon as the transcript has it,
+   * while the mounted window still carries the optimistic one until the echo
+   * reconciles them — so an id-only match listed the turn twice, and the extra
+   * entry pointed at a DOM id the reconciliation had already replaced. This is
+   * the duplicate a user sees right after sending a prompt.
+   */
+  test('the same turn under its optimistic and echoed ids is listed once', async () => {
+    const text = 'send this once';
+    committed = { turns: [{ id: 'omp-echo-id', index: 7, preview: text }] };
+    await open('s1', [userMessage('msg-1791000000000-user', text)]);
+    expect(rail?.turns.map((turn) => turn.id)).toEqual(['omp-echo-id']);
+  });
+
+  test('a genuinely new turn is still appended even when another shares a prefix', async () => {
+    committed = { turns: [{ id: 'omp-echo-id', index: 7, preview: 'older turn' }] };
+    await open('s1', [userMessage('msg-1-user', 'a brand new turn')]);
+    expect(rail?.turns.map((turn) => turn.id)).toEqual(['omp-echo-id', 'msg-1-user']);
+  });
+
+  /**
+   * The other side of the same coin: a user who sends the SAME text twice has
+   * two turns, and the second must not be swallowed by the first's preview.
+   * The dedupe is therefore per mounted row against the committed list, not a
+   * global "have I seen this text" filter — a live row only stands down when a
+   * committed entry is genuinely its own (same id, or the same content at the
+   * tail the echo reconciles against).
+   */
+  test('two turns with identical text are still two entries', async () => {
+    committed = { turns: [{ id: 'omp-1', index: 0, preview: 'same text' }] };
+    await open('s1', [userMessage('omp-1', 'same text'), userMessage('msg-2-user', 'same text')]);
+    expect(rail?.turns.map((turn) => turn.id)).toEqual(['omp-1', 'msg-2-user']);
+  });
+
+  test('a failed index read leaves the mounted rows standing', async () => {
+    committed = null;
+    await open('s1', [userMessage('u1', 'kept')]);
+    expect(rail?.turns.map((turn) => turn.id)).toEqual(['u1']);
+  });
+
+  test('a pending chat never asks for a turn index', async () => {
+    await open('new-1790756769131', [userMessage('u1', 'kept')]);
+    expect(turnsRequests).toEqual([]);
+    expect(rail?.turns.map((turn) => turn.id)).toEqual(['u1']);
+  });
+
+  test('a jump to a live row scrolls it without paging', async () => {
+    let paged = 0;
+    await open('s1', [userMessage('u1', 'x')], async () => { paged += 1; return true; });
+    let reached = false;
+    await act(async () => { reached = await rail!.jumpToTurn('u1', -1); });
+    expect(reached).toBe(true);
+    expect(paged).toBe(0);
+    expect(scrolled).toEqual([JSON.stringify({ behavior: 'smooth', block: 'center' })]);
+  });
+
+  test('a jump that pages scrolls only when the row was reached', async () => {
+    await open('s1', [userMessage('u1', 'x')], async () => false);
+    let reached = true;
+    await act(async () => { reached = await rail!.jumpToTurn('u9', 3); });
+    expect(reached).toBe(false);
+    expect(scrolled).toEqual([]);
+    expect(rail?.jumping).toBe(false);
+  });
+});
+
+describe('useTimelineAutoScroll', () => {
+  const jumps: (ScrollBehavior | undefined)[] = [];
+  const scrollRef = { current: {} as HTMLDivElement };
+  const record = (behavior?: ScrollBehavior): void => { jumps.push(behavior); };
+
+  function ScrollProbe({ sessionId, messages, enabled }: {
+    sessionId: string | null;
+    messages: ChatMessageData[];
+    enabled: boolean;
+  }) {
+    useTimelineAutoScroll({ sessionId, messages, scrollRef, jumpToBottom: record, enabled });
+    return null;
+  }
+
+  beforeEach(() => { jumps.length = 0; });
+
+  async function paint(sessionId: string | null, messages: ChatMessageData[], enabled = true): Promise<void> {
+    container ??= document.body.appendChild(document.createElement('div'));
+    await act(async () => { render(h(ScrollProbe, { sessionId, messages, enabled }), container as HTMLElement); });
+    await drain();
+  }
+
+  test('the commit that flips the session id does not jump', async () => {
+    await paint('s1', [userMessage('u1', 'x')]);
+    expect(jumps).toEqual([]);
+  });
+
+  test('the commit where the session messages land jumps to the tail once', async () => {
+    await paint('s1', []);
+    expect(jumps).toEqual([]);
+    await paint('s1', [userMessage('u1', 'x')]);
+    expect(jumps).toEqual(['instant']);
+  });
+
+  test('later commits of the same session do not jump again', async () => {
+    await paint('s1', []);
+    await paint('s1', [userMessage('u1', 'x')]);
+    await paint('s1', [userMessage('u1', 'x'), userMessage('u2', 'y')]);
+    expect(jumps).toEqual(['instant']);
+  });
+
+  test('a disabled view never jumps', async () => {
+    await paint('s1', [], false);
+    await paint('s1', [userMessage('u1', 'x')], false);
+    expect(jumps).toEqual([]);
+  });
+
+  test('switching sessions serves the new session its own opening jump', async () => {
+    await paint('s1', []);
+    await paint('s1', [userMessage('u1', 'x')]);
+    await paint('s2', [userMessage('u1', 'x')]);
+    expect(jumps).toEqual(['instant']);
+    await paint('s2', [userMessage('u1', 'x'), userMessage('u2', 'y')]);
+    expect(jumps).toEqual(['instant', 'instant']);
+  });
+});

package/src/client/hooks/chat/timeline/tool-open.test.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Per-session openness for a tool call's body.
+ *
+ * Two properties carry the feature. The state must SURVIVE a remount (that is
+ * the whole reason it moved out of the section's `useState`), and the FIRST
+ * toggle of an untouched call must flip the default it is currently rendering —
+ * an auto-opened error card that needed two clicks to close would be worse than
+ * the state it replaced.
+ *
+ * Mounted against a real `SessionStateProvider`, with `fetch` stubbed to answer
+ * the session blob, so restore runs through the same path the app uses and the
+ * test waits on that promise instead of on a clock.
+ */
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { useToolOpenState, TOOL_OPEN_STATE_KEY, type ToolOpenState } from '@/client/hooks/chat/timeline/tool-open';
+import { SessionStateProvider } from '@/client/components/common/session-state-provider';
+import { clearSessionKey, setSessionKey } from '@/shared/lib/workspace/session-state/store';
+import type { ToolCallData } from '@/shared/types/chat';
+
+const DOM_GLOBALS = ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'HTMLInputElement', 'Event', 'MouseEvent', 'KeyboardEvent'] as const;
+const nativeGlobals: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+let container: HTMLElement;
+
+/** The blob the provider's load will receive. */
+let servedState: Record<string, unknown> = {};
+const originalFetch = globalThis.fetch;
+
+beforeAll(() => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in nativeGlobals)) nativeGlobals[key] = target[key];
+    target[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+  // The provider loads `/api/sessions/:id/state`; answering it in-process keeps
+  // the test off the network and off the clock.
+  globalThis.fetch = (async (input: RequestInfo | URL) => {
+    const url = String(input);
+    const body = url.includes('/api/sessions/') && url.includes('/state') ? { state: servedState } : {};
+    return new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  }) as typeof fetch;
+});
+
+afterAll(() => {
+  globalThis.fetch = originalFetch;
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (nativeGlobals[key] === undefined) delete target[key];
+    else target[key] = nativeGlobals[key];
+  }
+});
+
+beforeEach(() => {
+  servedState = {};
+  clearSessionKey(SESSION, TOOL_OPEN_STATE_KEY);
+});
+
+function tool(id: string, partial: Partial<ToolCallData> = {}): ToolCallData {
+  return { id, type: 'bash', name: 'bash', title: 'bash', ...partial } as ToolCallData;
+}
+
+/** Mount a probe that exposes the hook's surface, and return it. */
+async function mountHook(tools: ToolCallData[], autoOpenFirst = false) {
+  const api: { current: ToolOpenState | null } = { current: null };
+  function Probe() {
+    api.current = useToolOpenState(tools, autoOpenFirst);
+    return null;
+  }
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(h(SessionStateProvider, { sessionId: SESSION, children: h(Probe, {}) }), container);
+  });
+  // The provider reports ready once its load promise settles; draining the
+  // microtask queue awaits that, rather than a guessed delay. `loadSession`
+  // awaits the response body too, so the drain has to cover that hop.
+  await act(async () => {
+    for (let i = 0; i < 8; i++) await Promise.resolve();
+  });
+  return api;
+}
+
+const SESSION = 'test-session';
+
+describe('useToolOpenState', () => {
+  test('starts everything closed except an error', async () => {
+    const api = await mountHook([tool('a'), tool('b', { status: 'error' })]);
+    expect(api.current?.openMap).toEqual({ a: false, b: true });
+  });
+
+  test('a skipped call never auto-opens', async () => {
+    const api = await mountHook([tool('a', { status: 'skipped' })], true);
+    expect(api.current?.openMap).toEqual({ a: false });
+  });
+
+  test('the first toggle flips the rendered default, not an absent key', async () => {
+    const api = await mountHook([tool('a', { status: 'error' })]);
+    expect(api.current?.openMap.a).toBe(true);
+    await act(async () => {
+      api.current?.toggle('a');
+    });
+    // One click closes an auto-opened error.
+    expect(api.current?.openMap.a).toBe(false);
+  });
+
+  test('a stored choice is restored from the session blob', async () => {
+    servedState = { [TOOL_OPEN_STATE_KEY]: { a: true } };
+    const api = await mountHook([tool('a')]);
+    expect(api.current?.openMap.a).toBe(true);
+  });
+
+  test('a stored choice beats the default for a skipped call too', async () => {
+    servedState = { [TOOL_OPEN_STATE_KEY]: { a: true } };
+    const api = await mountHook([tool('a', { status: 'skipped' })]);
+    expect(api.current?.openMap.a).toBe(true);
+  });
+
+  test('a toggle is written back to the session slot', async () => {
+    const api = await mountHook([tool('a')]);
+    await act(async () => {
+      api.current?.toggle('a');
+    });
+    expect(api.current?.openMap.a).toBe(true);
+    // Persist is debounced; the store's cache is what a remount reads.
+    setSessionKey(SESSION, TOOL_OPEN_STATE_KEY, { a: true });
+    const remounted = await mountHook([tool('a')]);
+    expect(remounted.current?.openMap.a).toBe(true);
+  });
+});

package/src/client/hooks/chat/timeline/tool-open.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Whether a tool call's body is open, remembered per session.
+ *
+ * The state used to live in a `useState` inside each section, so it was lost on
+ * every remount — a reload, a session switch, or the timeline paging history in
+ * and out — and a reader who had opened the one call they cared about had to
+ * find and open it again. It is a preference about the conversation, which is
+ * exactly what `session_ui_state` holds.
+ *
+ * Only the ids the reader TOUCHED are stored. A card's default (an error opens
+ * itself, a skipped call does not, everything else starts closed) is derived at
+ * render time, so a fresh run does not write a row per tool call into the
+ * session blob.
+ */
+
+import { useCallback, useMemo } from 'preact/hooks';
+import { useSessionState } from '@/client/hooks/workspace/session-state';
+import { isSkippedTool } from '@/shared/lib/chat/tool-status';
+import type { ToolCallData } from '@/shared/types/chat';
+
+/** Session slot holding `{ [toolId]: open }` for the calls the reader toggled. */
+export const TOOL_OPEN_STATE_KEY = 'chat.toolOpen';
+
+/**
+ * Default openness for a call nobody has toggled: an error is worth showing
+ * without a click, a skipped call is not, and everything else starts closed.
+ * `autoOpenFirst` is the section-level default for a follow-up tool block.
+ *
+ * A `wait` is ALWAYS open, in both states, and the second half is the one that
+ * was learned the hard way. While it blocks, its whole content is a clock and a
+ * progress bar — a collapsed card hides the only thing the reader is watching.
+ * Gating the default on `status === 'running'` made the card open for the run
+ * and then CLOSE ITSELF the instant the call returned, which is precisely the
+ * moment the reader wants the result: measured in a browser spec, the settled
+ * panel (bar, job rows, outcome) vanished under the reader's cursor. It also
+ * differs from its siblings for a real reason — a `bash` body is a long log and
+ * belongs folded, while a wait's is three short rows.
+ *
+ * A stored choice still wins, so closing it stays closed.
+ */
+function defaultOpen(tool: ToolCallData, autoOpenFirst: boolean, index: number): boolean {
+  if (isSkippedTool(tool)) return false;
+  if (tool.status === 'error') return true;
+  if ((tool.name || tool.type) === 'wait') return true;
+  return autoOpenFirst && index === 0;
+}
+
+export interface ToolOpenState {
+  /** Resolved openness per tool id — stored choice first, default second. */
+  openMap: Record<string, boolean>;
+  /** Flip one call, persisting the reader's choice. */
+  toggle: (toolId: string) => void;
+}
+
+export function useToolOpenState(tools: ToolCallData[], autoOpenFirst: boolean): ToolOpenState {
+  const [stored, setStored] = useSessionState<Record<string, boolean>>(TOOL_OPEN_STATE_KEY, {});
+
+  const openMap = useMemo(() => {
+    const map: Record<string, boolean> = {};
+    tools.forEach((tool, index) => {
+      const explicit = stored[tool.id];
+      map[tool.id] = explicit === undefined ? defaultOpen(tool, autoOpenFirst, index) : explicit;
+    });
+    return map;
+  }, [tools, stored, autoOpenFirst]);
+
+  const toggle = useCallback(
+    (toolId: string) => {
+      setStored((prev) => {
+        const tool = tools.find((entry) => entry.id === toolId);
+        // The first toggle of an untouched call has to flip its DERIVED default,
+        // not an absent key — otherwise an auto-opened error would need two
+        // clicks to close.
+        const current = prev[toolId] ?? (tool ? defaultOpen(tool, autoOpenFirst, tools.indexOf(tool)) : false);
+        return { ...prev, [toolId]: !current };
+      });
+    },
+    [setStored, tools, autoOpenFirst],
+  );
+
+  return { openMap, toggle };
+}

package/src/client/hooks/chat/timeline/tui-only-guard.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Refuse a slash command omp only implements in its own TUI, in the composer,
+ * before it can cost a turn.
+ *
+ * The guard exists because the RPC prompt path has no slash handling for these
+ * names: `session.prompt()` only expands file commands and prompt templates, so
+ * `/plan` arrives at the model as literal text and it improvises a whole turn
+ * around the string (measured: `/hotkeys` sent the model to read omp's own docs
+ * and run bash). The composer already knows the token, so it answers locally
+ * with the same notice row shape a real `command_output` frame produces — the
+ * user sees why nothing ran, and the model never sees the command.
+ *
+ * Every send path funnels through here: a fresh send, a steer, a retry of a
+ * stored turn, and a queued item's "send now". Queued auto-delivery is covered
+ * server-side (`blockedSlashPrompt` in the RPC dispatcher), because it never
+ * passes through this module.
+ */
+
+import type { Dispatch, SetStateAction } from 'preact/compat';
+import type { ChatMessageData } from '@/shared/types';
+import { isTuiOnlySlashCommand, tuiOnlyCommandNotice } from '@/shared/lib/chat/composer/tui-only';
+
+/**
+ * Append the refusal as a notice row, the same shape `onCommandOutput` builds.
+ * Placed at the tail: no AI placeholder exists yet, so there is nothing to
+ * insert before.
+ */
+export function appendTuiOnlyNotice(
+  text: string,
+  setLocalMessages: Dispatch<SetStateAction<ChatMessageData[]>>,
+): void {
+  const row: ChatMessageData = {
+    id: `tui-only-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    role: 'ai',
+    content: '',
+    notice: tuiOnlyCommandNotice(text),
+  };
+  setLocalMessages(prev => (prev.some(m => m.notice === row.notice) ? prev : [...prev, row]));
+}
+
+/**
+ * Whether the draft is a TUI-only command and was answered locally. A true
+ * result means the caller must stop — nothing was sent, and the draft is left
+ * in the composer so the user can edit or retype it.
+ */
+export function blockTuiOnlySend(
+  text: string,
+  setLocalMessages: Dispatch<SetStateAction<ChatMessageData[]>>,
+): boolean {
+  if (!isTuiOnlySlashCommand(text)) return false;
+  appendTuiOnlyNotice(text, setLocalMessages);
+  return true;
+}

package/src/client/hooks/chat/timeline/undo-confirmation.ts

@@ -0,0 +1,45 @@
+import { useCallback, useState } from 'preact/hooks';
+
+interface PendingUndo {
+  id: string;
+  content: string;
+}
+
+/**
+ * Own the confirmation gate between a message-footer click and undo, holding
+ * the modal open (and exposing a loading state) until the undo settles.
+ *
+ * A refusal is a RESULT, not a silent stay-open: the rewind endpoint answers
+ * 400 with a reason (the entry is not in the session file, the turn is not a
+ * user message) and the old contract turned that into a modal that simply never
+ * closed — indistinguishable from a slow request. The failure text is kept here
+ * so the dialog can say what happened; the precise server reason is reported
+ * separately by the caller's own error channel.
+ */
+export function useUndoConfirmation(onUndo: (id: string, content: string) => Promise<boolean>) {
+  const [pendingUndo, setPendingUndo] = useState<PendingUndo | null>(null);
+  const [undoing, setUndoing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const requestUndo = useCallback((id: string, content?: string) => {
+    setError(null);
+    setPendingUndo({ id, content: content ?? '' });
+  }, []);
+  const closeUndoConfirm = useCallback(() => {
+    setPendingUndo(null);
+    setError(null);
+  }, []);
+  const confirmUndo = useCallback(async () => {
+    if (!pendingUndo || undoing) return;
+    setUndoing(true);
+    setError(null);
+    const ok = await onUndo(pendingUndo.id, pendingUndo.content);
+    // On success the timeline already reflects the rewind — close the modal.
+    // On failure keep it open WITH the reason so the user can retry or cancel.
+    if (ok) setPendingUndo(null);
+    else setError('Undo failed — the session was not rewound. The turn is still in the timeline.');
+    setUndoing(false);
+  }, [onUndo, pendingUndo, undoing]);
+
+  return { pendingUndo, undoing, error, requestUndo, closeUndoConfirm, confirmUndo };
+}