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

package/src/__tests__/wire-tui-client-commands.test.ts

@@ -0,0 +1,243 @@
+/**
+ * #3189 — the commands a terminal attached to a workspace daemon runs in its own process.
+ *
+ * The attached terminal gives them its own handoff and working directory, applies the appearance
+ * patch `/theme` asks for itself, and refuses any other host action by name instead of dropping it.
+ */
+import { createTerminalClientCommands } from '@robota-sdk/agent-command';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  createTuiClientCommandHost,
+  findTuiClientCommand,
+  runTuiClientCommand,
+} from '../wire-tui-client-commands.js';
+
+import type {
+  ITuiClientCommand,
+  ITuiClientCommands,
+  TTuiClientCommandHost,
+} from '../wire-tui-client-commands.js';
+import type {
+  ICommandResult,
+  IThemeCatalogueEntry,
+  IThemeCataloguePort,
+  TAppearanceSettingsPatch,
+  TCommandHostAction,
+} from '@robota-sdk/agent-interface-command';
+import type { ITerminalHandoff } from '@robota-sdk/agent-interface-session';
+
+/** Stands in for `/shell`: hands the terminal to a "child" that runs in the host's directory. */
+const shellLike: ITuiClientCommand = {
+  name: 'shell',
+  async execute(host, args) {
+    if (!host.canHandoffTerminal()) {
+      return { success: false, message: 'An interactive shell is unavailable here.' };
+    }
+    const cwd = host.getCwd();
+    const ran = await host.runWithTerminal(async () => `${args} in ${cwd}`);
+    return { success: true, message: ran };
+  },
+};
+
+function commandReturning(name: string, result: ICommandResult): ITuiClientCommand {
+  return { name, execute: () => result };
+}
+
+function hostFor(terminalHandoff?: ITerminalHandoff): TTuiClientCommandHost {
+  return createTuiClientCommandHost({ terminalHandoff, cwd: '/work/project' });
+}
+
+function writerSpy() {
+  return {
+    writeAppearanceSettings: vi.fn(async (_patch: TAppearanceSettingsPatch) => undefined),
+  };
+}
+
+const THEMES: IThemeCatalogueEntry[] = [
+  { id: 'dark', name: 'Dark', appearance: 'dark', source: 'built-in' },
+  { id: 'light', name: 'Light', appearance: 'light', source: 'built-in' },
+];
+const themeCatalogue: IThemeCataloguePort = {
+  listThemes: () => THEMES,
+  getTheme: (id) => THEMES.find((theme) => theme.id === id),
+  getAppearance: () => ({
+    settings: { theme: 'dark', syntaxHighlighting: true, reducedMotion: false },
+  }),
+};
+
+describe('createTuiClientCommandHost (#3189)', () => {
+  it('hands this terminal to the command and runs it in this terminal’s directory', async () => {
+    const handedOff = vi.fn();
+    const handoff: ITerminalHandoff = {
+      canHandoffTerminal: true,
+      runWithTerminal: <T>(fn: () => Promise<T>): Promise<T> => {
+        handedOff();
+        return fn();
+      },
+    };
+    const host = hostFor(handoff);
+
+    const outcome = await runTuiClientCommand(shellLike, 'ls', host, writerSpy());
+
+    expect(handedOff).toHaveBeenCalledTimes(1);
+    expect(outcome.result).toEqual({ success: true, message: 'ls in /work/project' });
+    expect(host.getCommandInvocationSource()).toBe('user');
+  });
+
+  it('without a handoff it cannot take the terminal, so the command takes its refusal path', async () => {
+    const host = hostFor(undefined);
+
+    expect(host.canHandoffTerminal()).toBe(false);
+    const outcome = await runTuiClientCommand(shellLike, 'ls', host, writerSpy());
+
+    expect(outcome.result).toEqual({
+      success: false,
+      message: 'An interactive shell is unavailable here.',
+    });
+    await expect(host.runWithTerminal(async () => 'never')).rejects.toThrow(/unavailable/u);
+  });
+});
+
+describe('runTuiClientCommand (#3189)', () => {
+  it('/theme with no arguments opens this terminal’s theme picker and writes nothing', async () => {
+    const theme = commandReturning('theme', {
+      success: true,
+      message: 'Opening the theme picker...',
+      uiIntents: [{ type: 'show-theme-picker' }],
+    });
+    const writers = writerSpy();
+
+    const outcome = await runTuiClientCommand(theme, '', hostFor(), writers);
+
+    expect(outcome.uiIntents).toEqual([{ type: 'show-theme-picker' }]);
+    expect(outcome.result).toEqual({ success: true, message: 'Opening the theme picker...' });
+    expect(writers.writeAppearanceSettings).not.toHaveBeenCalled();
+  });
+
+  it('/theme light, from the real client command set, is written before the command settles', async () => {
+    let finishWrite: () => void = () => undefined;
+    const written: TAppearanceSettingsPatch[] = [];
+    const commands: ITuiClientCommands = {
+      commands: createTerminalClientCommands({ themeCatalogue }),
+      writeAppearanceSettings: (patch) => {
+        written.push(patch);
+        return new Promise<void>((resolve) => {
+          finishWrite = resolve;
+        });
+      },
+    };
+    const theme = findTuiClientCommand(commands, 'theme');
+    if (!theme) throw new Error('the client command set has no /theme');
+
+    let settled = false;
+    const running = runTuiClientCommand(theme, 'light', hostFor(), commands).then((outcome) => {
+      settled = true;
+      return outcome;
+    });
+    await vi.waitFor(() => expect(written).toEqual([{ theme: 'light' }]));
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(settled).toBe(false);
+
+    finishWrite();
+    const outcome = await running;
+
+    expect(outcome.result.success).toBe(true);
+    expect(outcome.result.hostActions).toBeUndefined();
+    expect(outcome.result.data).toEqual({ appearance: { theme: 'light' } });
+    expect(outcome.uiIntents).toEqual([]);
+  });
+
+  it('an invalid appearance patch writes nothing and fails', async () => {
+    const command = commandReturning('theme', {
+      success: true,
+      message: 'Applied.',
+      hostActions: [
+        {
+          type: 'appearance-settings-patch',
+          patch: { reducedMotion: 'yes' } as unknown as TAppearanceSettingsPatch,
+        },
+      ],
+    });
+    const writers = writerSpy();
+
+    const outcome = await runTuiClientCommand(command, 'x', hostFor(), writers);
+
+    expect(outcome.result.success).toBe(false);
+    expect(outcome.result.message).toContain('invalid appearance settings patch');
+    expect(outcome.uiIntents).toEqual([]);
+    expect(writers.writeAppearanceSettings).not.toHaveBeenCalled();
+  });
+
+  it('a host action this terminal cannot perform is refused by name, and nothing beside it is written', async () => {
+    const hostActions: TCommandHostAction[] = [
+      { type: 'appearance-settings-patch', patch: { theme: 'light' } },
+      { type: 'session-exit' },
+    ];
+    const command = commandReturning('theme', {
+      success: true,
+      message: 'Applied.',
+      hostActions,
+      uiIntents: [{ type: 'show-theme-picker' }],
+    });
+    const writers = writerSpy();
+
+    const outcome = await runTuiClientCommand(command, '', hostFor(), writers);
+
+    expect(outcome).toEqual({
+      result: { success: false, message: "Cannot apply 'session-exit' on this terminal." },
+      uiIntents: [],
+    });
+    expect(writers.writeAppearanceSettings).not.toHaveBeenCalled();
+  });
+
+  it('a write that fails turns the result into that failure', async () => {
+    const command = commandReturning('theme', {
+      success: true,
+      message: 'Applied.',
+      hostActions: [{ type: 'appearance-settings-patch', patch: { theme: 'light' } }],
+    });
+
+    const outcome = await runTuiClientCommand(command, 'light', hostFor(), {
+      writeAppearanceSettings: () => Promise.reject(new Error('disk full')),
+    });
+
+    expect(outcome.result).toEqual({
+      success: false,
+      message: "Failed to apply 'appearance-settings-patch': disk full",
+    });
+  });
+
+  it('a failed result passes through unchanged and applies nothing', async () => {
+    const failed: ICommandResult = {
+      success: false,
+      message: 'Unknown theme "nope".',
+      hostActions: [{ type: 'appearance-settings-patch', patch: { theme: 'nope' } }],
+    };
+    const writers = writerSpy();
+
+    const outcome = await runTuiClientCommand(
+      commandReturning('theme', failed),
+      'nope',
+      hostFor(),
+      writers,
+    );
+
+    expect(outcome.result).toBe(failed);
+    expect(outcome.uiIntents).toEqual([]);
+    expect(writers.writeAppearanceSettings).not.toHaveBeenCalled();
+  });
+});
+
+describe('findTuiClientCommand (#3189)', () => {
+  it('finds a client command by name, and nothing without a set', () => {
+    const commands: ITuiClientCommands = {
+      commands: [shellLike],
+      writeAppearanceSettings: () => undefined,
+    };
+
+    expect(findTuiClientCommand(commands, 'shell')).toBe(shellLike);
+    expect(findTuiClientCommand(commands, 'model')).toBeUndefined();
+    expect(findTuiClientCommand(undefined, 'shell')).toBeUndefined();
+  });
+});

package/src/app-banner.tsx

@@ -0,0 +1,42 @@
+/**
+ * The startup banner, committed once to the terminal scrollback.
+ *
+ * Extracted from `App.tsx` under CLI-2004: the art is ASCII, not box-drawing, so a
+ * no-box-drawing sweep passes over it unchanged — it needs its own suppression AND its own
+ * assertion, and neither is reviewable while the glyphs live inline in a 600-line component.
+ * `BANNER_GLYPHS` is the set a test asserts is absent in screen-reader mode.
+ */
+
+import { Box } from 'ink';
+import React from 'react';
+
+import { Text } from './SafeText.js';
+import { usePalette } from './theme/index.js';
+
+/** The ASCII art itself. */
+export const BANNER_ART = `
+  ____   ___  ____   ___ _____  _
+ |  _ \\ / _ \\| __ ) / _ \\_   _|/ \\
+ | |_) | | | |  _ \\| | | || | / _ \\
+ |  _ <| |_| | |_) | |_| || |/ ___ \\
+ |_| \\_\\\\___/|____/ \\___/ |_/_/   \\_\\
+`;
+
+/**
+ * The characters the art is drawn from. None is a box-drawing character, which is exactly why the
+ * banner needs a suppression test of its own.
+ */
+export const BANNER_GLYPHS: readonly string[] = ['_', '|', '\\', '/', '<'];
+
+/** The banner as it is committed to scrollback: the art plus the version line. */
+export function AppBanner({ version }: { version: string }): React.ReactElement {
+  const palette = usePalette();
+  return (
+    <Box flexDirection="column" paddingX={1} marginBottom={1}>
+      <Text color={palette.text.accent} bold>
+        {BANNER_ART}
+      </Text>
+      <Text dimColor> v{version}</Text>
+    </Box>
+  );
+}

package/src/app-static-items.ts

@@ -0,0 +1,35 @@
+/**
+ * SCREEN-010 / CLI-2004 — what gets committed to the terminal's native scrollback.
+ *
+ * The App renders exactly this list inside a single Ink `<Static>`, so each item is written once and
+ * never repainted. Building the list is a pure function so the ONE decision that varies — whether
+ * the startup banner is committed at all — is assertable without mounting the App.
+ */
+
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+
+/** A committed item: the startup banner, or one conversation entry. */
+export type TStaticItem =
+  | { readonly kind: 'banner'; readonly version: string }
+  | { readonly kind: 'entry'; readonly entry: IHistoryEntry };
+
+export interface IBuildStaticItemsInputs {
+  history: readonly IHistoryEntry[];
+  version: string | undefined;
+  /**
+   * Screen-reader mode. The banner is ASCII art with no spoken meaning — a reader announces it
+   * character by character before the session has said anything — so the mode omits the item
+   * entirely rather than styling it differently.
+   */
+  screenReader: boolean;
+}
+
+const FALLBACK_VERSION = '0.0.0';
+
+/** Build the `<Static>` item list. */
+export function buildStaticItems(inputs: IBuildStaticItemsInputs): TStaticItem[] {
+  const banner: TStaticItem[] = inputs.screenReader
+    ? []
+    : [{ kind: 'banner', version: inputs.version ?? FALLBACK_VERSION }];
+  return [...banner, ...inputs.history.map((entry): TStaticItem => ({ kind: 'entry', entry }))];
+}

package/src/app-view-model.ts

@@ -0,0 +1,140 @@
+import type { TStaticItem } from './app-static-items.js';
+import type { IAppThemeViewModel } from './hooks/useAppThemeState.js';
+import type { IInputAreaHistorySearch } from './hooks/useInputAreaHistorySearch.js';
+import type { ITuiCommandQueryPort } from './tui-app-channel-port.js';
+import type { ITuiSessionEventNotice } from './tui-session-events.js';
+import type { IPendingPermissionRequest } from './types.js';
+import type {
+  IActionRequest,
+  IHistoryEntry,
+  TActionResponse,
+  TModelEffortSelection,
+  TPermissionMode,
+} from '@robota-sdk/agent-core';
+import type {
+  ICommandPluginAdapter,
+  IStatusLineCommandSettings,
+} from '@robota-sdk/agent-interface-command';
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import type {
+  ISessionListingEntry,
+  IToolState,
+} from '@robota-sdk/agent-interface-session';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+export interface IAppViewModel {
+  readonly staticItems: TStaticItem[];
+  /** Printing starts over from the first item when this changes (see `transcriptGeneration`). */
+  readonly transcriptKey: number;
+  readonly handoffSuspended: boolean;
+  readonly updateNotice: string | undefined;
+  readonly coordinationError: string | undefined;
+  readonly coordinationPending: boolean;
+  readonly sessionEventNotices: readonly ITuiSessionEventNotice[];
+  readonly isShuttingDown: boolean;
+  readonly stream: {
+    readonly text: string;
+    readonly activeTools: readonly IToolState[];
+    readonly isThinking: boolean;
+    readonly isStalled: boolean;
+    readonly lastErrorMessage: string | null;
+  };
+  readonly background: IAppBackgroundViewModel;
+  readonly permissionRequest: IPendingPermissionRequest | null;
+  readonly pendingUserAction: IActionRequest | null;
+  readonly resolveUserAction: (request: IActionRequest, response: TActionResponse) => void;
+  readonly plugin: IAppPluginViewModel;
+  readonly transport: IAppTransportViewModel;
+  readonly sessionPicker: IAppSessionPickerViewModel;
+  /** SCREEN-2002: the live theme, the resolved motion setting, and the picker over them. */
+  readonly theme: IAppThemeViewModel;
+  readonly contextPercentage: number;
+  readonly input: IAppInputViewModel;
+  readonly status: IAppStatusViewModel;
+}
+
+export type { IAppThemePickerViewModel, IAppThemeViewModel } from './hooks/useAppThemeState.js';
+
+export interface IAppBackgroundViewModel {
+  readonly entries: IExecutionWorkspaceEntry[];
+  readonly focusedIndex: number | null;
+  readonly selectedEntry: IExecutionWorkspaceEntry | undefined;
+  readonly detail: {
+    readonly page: IExecutionDetailPage | null;
+    readonly loading: boolean;
+    readonly error: string | undefined;
+  };
+  readonly switcherVisible: boolean;
+  readonly snapshot: IExecutionWorkspaceSnapshot | null;
+  readonly selectedEntryId: string | undefined;
+  readonly select: (entryId: string) => void;
+  readonly closeSwitcher: () => void;
+  readonly attachToFork: (entry: IExecutionWorkspaceEntry) => void;
+}
+
+export interface IAppPluginViewModel {
+  readonly visible: boolean;
+  readonly callbacks: ICommandPluginAdapter;
+  readonly close: () => void;
+  readonly addMessage: (content: string) => void;
+}
+
+export interface IAppTransportViewModel {
+  readonly visible: boolean;
+  readonly registry: ITransportRegistryView | undefined;
+  readonly close: () => void;
+}
+
+export interface IAppSessionPickerViewModel {
+  readonly visible: boolean;
+  readonly sessions: readonly ISessionListingEntry[];
+  readonly select: (sessionId: string) => void;
+  readonly cancel: () => void;
+}
+
+export interface IAppInputViewModel {
+  /** FLOW-2006: the deep link's prefill, present only until the composer takes it. */
+  readonly initialValue?: string | undefined;
+  /** Called by the composer the first time it seeds itself, so a remount does not re-seed. */
+  readonly consumeInitialValue?: (() => void) | undefined;
+  /** True while the composer's text is the one a deep link supplied. */
+  readonly externalPromptOrigin?: boolean | undefined;
+  readonly submit: (input: string) => Promise<void>;
+  readonly cancelQueue: () => void;
+  readonly disabled: boolean;
+  readonly queueCancellationDisabled: boolean;
+  readonly isAborting: boolean;
+  readonly pendingPrompt: string | null;
+  readonly pendingCount: number;
+  readonly commandQueryPort: ITuiCommandQueryPort;
+  readonly sessionName: string | undefined;
+  readonly history: readonly IHistoryEntry[];
+  readonly focusBackgroundList: () => void;
+  /** SCREEN-1993: the stored-prompt search surface; absent ⇒ the feature is off. */
+  readonly historySearch: IInputAreaHistorySearch | undefined;
+}
+
+export interface IAppStatusViewModel {
+  readonly cwd: string;
+  readonly permissionMode: TPermissionMode;
+  readonly modelId: string | undefined;
+  readonly providerType: string | undefined;
+  readonly sessionId: string;
+  readonly isThinking: boolean;
+  readonly activeToolCount: number;
+  readonly activeBackgroundTaskCount: number;
+  readonly hasPendingPrompt: boolean;
+  readonly contextState: { percentage: number; usedTokens: number; maxTokens: number };
+  readonly sessionName: string | undefined;
+  readonly settings: IStatusLineCommandSettings;
+  readonly activeAgentLabel: string | undefined;
+  readonly activePresetId: string | undefined;
+  readonly effort: TModelEffortSelection | undefined;
+  readonly gitRefreshToken: number;
+  /** This terminal only observes the session; the status bar says so. */
+  readonly readOnly: boolean;
+}

package/src/attached-session-connection.ts

@@ -0,0 +1,14 @@
+import type { TClientMessage, TServerMessage } from '@robota-sdk/agent-transport/client';
+
+/**
+ * A terminal's end of the session protocol to a session it is attached to. The terminal only sends
+ * and listens; closing the connection belongs to whoever opened it.
+ */
+export interface IAttachedSessionConnection {
+  send(message: TClientMessage): void;
+  subscribe(listener: (message: TServerMessage) => void): () => void;
+  onClose(listener: () => void): () => void;
+}
+
+/** Why an attached terminal stopped showing the session: the user left, or the connection closed. */
+export type TAttachedSessionEnd = 'user' | 'closed';

package/src/attention/__tests__/attention-coordinator.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest';
+
+import { AttentionCoordinator } from '../attention-coordinator.js';
+
+import type { IAttentionSource, TAttentionListener } from '../attention-tracker.js';
+import type { IExecutionWorkspaceSnapshot } from '@robota-sdk/agent-interface-execution';
+
+class FakeSource implements IAttentionSource {
+  attended = true;
+  readonly source = 'focus' as const;
+  private readonly listeners = new Set<TAttentionListener>();
+  subscribe(listener: TAttentionListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  lost(at: string): void {
+    this.attended = false;
+    for (const listener of this.listeners) listener({ kind: 'lost', at });
+  }
+  returned(at: string): void {
+    this.attended = true;
+    for (const listener of this.listeners) listener({ kind: 'returned', at });
+  }
+  get listenerCount(): number {
+    return this.listeners.size;
+  }
+}
+
+function snapshot(
+  entries: ReadonlyArray<{
+    id: string;
+    state: 'working' | 'completed' | 'failed';
+    kind?: 'main_thread' | 'background_task';
+  }>,
+) {
+  return {
+    sessionId: 's1',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    entries: entries.map((entry) => ({
+      id: entry.id,
+      sourceId: entry.id,
+      kind: entry.kind ?? ('background_task' as const),
+      origin: { kind: 'slash_command' as const, sessionId: 's1' },
+      status: 'running' as const,
+      state: entry.state,
+      title: entry.id,
+      unread: false,
+      attention: 'none' as const,
+      visibility: 'default' as const,
+      updatedAt: '2026-01-01T00:00:00.000Z',
+      controls: ['select' as const],
+    })),
+  } satisfies IExecutionWorkspaceSnapshot;
+}
+
+describe('AttentionCoordinator (SCREEN-1992 TC-02 wiring)', () => {
+  it('pushes one recap per unattended interval from the channel events it is fed', () => {
+    const source = new FakeSource();
+    const recaps: string[] = [];
+    const coordinator = new AttentionCoordinator({ source, onRecap: (line) => recaps.push(line) });
+    coordinator.wire();
+    coordinator.wire();
+    expect(source.listenerCount).toBe(1);
+
+    // Before the interval: an idle main thread and a task that already finished.
+    coordinator.onWorkspaceSnapshot(
+      snapshot([
+        { id: 'main:s1', state: 'completed', kind: 'main_thread' },
+        { id: 'task:done', state: 'completed' },
+        { id: 'task:a', state: 'working' },
+      ]),
+    );
+    source.lost('2026-01-01T00:00:00.000Z');
+    coordinator.onTurnSource('agent-wakeup');
+    coordinator.onWorkspaceSnapshot(
+      snapshot([
+        { id: 'main:s1', state: 'working', kind: 'main_thread' },
+        { id: 'task:done', state: 'completed' },
+        { id: 'task:a', state: 'working' },
+      ]),
+    );
+    coordinator.onComplete();
+    coordinator.onNeedsInput();
+    coordinator.onWorkspaceSnapshot(
+      snapshot([
+        { id: 'main:s1', state: 'completed', kind: 'main_thread' },
+        { id: 'task:done', state: 'completed' },
+        { id: 'task:a', state: 'failed' },
+      ]),
+    );
+    source.returned('2026-01-01T00:03:00.000Z');
+    expect(recaps).toEqual(['While away 3m: 1 turn finished (1 wake) · 1 needs input · 1 failed']);
+
+    // Attended activity is never recapped.
+    coordinator.onComplete();
+    source.lost('2026-01-01T00:10:00.000Z');
+    source.returned('2026-01-01T00:11:00.000Z');
+    expect(recaps).toHaveLength(1);
+
+    coordinator.unwire();
+    expect(source.listenerCount).toBe(0);
+  });
+
+  it('starts an interval immediately when wired while the user is already away', () => {
+    const source = new FakeSource();
+    source.attended = false;
+    const recaps: string[] = [];
+    const coordinator = new AttentionCoordinator({
+      source,
+      onRecap: (line) => recaps.push(line),
+      now: () => Date.parse('2026-01-01T00:00:00.000Z'),
+    });
+    coordinator.wire();
+    coordinator.onTurnSource('user');
+    coordinator.onComplete();
+    source.returned('2026-01-01T00:05:00.000Z');
+    expect(recaps).toEqual(['While away 5m: 1 turn finished']);
+  });
+
+  it('takes the first snapshot as the baseline when wired while already away', () => {
+    const source = new FakeSource();
+    source.attended = false;
+    const recaps: string[] = [];
+    const coordinator = new AttentionCoordinator({
+      source,
+      onRecap: (line) => recaps.push(line),
+      now: () => Date.parse('2026-01-01T00:00:00.000Z'),
+    });
+    coordinator.wire();
+    // A resumed session restores an already-finished task: not news.
+    coordinator.onWorkspaceSnapshot(
+      snapshot([
+        { id: 'task:restored', state: 'completed' },
+        { id: 'task:live', state: 'working' },
+      ]),
+    );
+    coordinator.onWorkspaceSnapshot(
+      snapshot([
+        { id: 'task:restored', state: 'completed' },
+        { id: 'task:live', state: 'failed' },
+      ]),
+    );
+    source.returned('2026-01-01T00:04:00.000Z');
+    expect(recaps).toEqual(['While away 4m: 1 failed']);
+  });
+
+  it('never reports the main thread finishing a turn as a completed entry', () => {
+    const source = new FakeSource();
+    const recaps: string[] = [];
+    const coordinator = new AttentionCoordinator({ source, onRecap: (line) => recaps.push(line) });
+    coordinator.wire();
+    // The user leaves mid-turn: the main thread is `working` when attention is lost …
+    coordinator.onWorkspaceSnapshot(
+      snapshot([{ id: 'main:s1', state: 'working', kind: 'main_thread' }]),
+    );
+    source.lost('2026-01-01T00:00:00.000Z');
+    coordinator.onTurnSource('user');
+    coordinator.onComplete();
+    // … and idle (`completed`) when they return. That is the turn, already counted, not an entry.
+    coordinator.onWorkspaceSnapshot(
+      snapshot([{ id: 'main:s1', state: 'completed', kind: 'main_thread' }]),
+    );
+    source.returned('2026-01-01T00:02:00.000Z');
+    expect(recaps).toEqual(['While away 2m: 1 turn finished']);
+  });
+});