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

package/src/__tests__/confirm-permission-flow.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest';
+import {
+  applyConfirmPromptInput,
+  getConfirmPromptInputAction,
+} from '../flows/confirm-prompt-flow.js';
+import {
+  applyPermissionPromptInput,
+  getPermissionPromptInputAction,
+  PERMISSION_PROMPT_OPTIONS,
+  permissionPromptOptionsFor,
+} from '../flows/permission-prompt-flow.js';
+import { createSelectionFlowState } from '../flows/selection-flow.js';
+
+describe('confirm prompt flow', () => {
+  it('Given two options When y shortcut is mapped and applied Then first option is selected', () => {
+    const action = getConfirmPromptInputAction('y', {}, 2);
+    expect(action).toEqual({ type: 'shortcut', index: 0 });
+
+    const result = applyConfirmPromptInput(createSelectionFlowState(), action!, 2);
+
+    expect(result.effect).toEqual({ type: 'select', index: 0 });
+  });
+
+  it('Given more than two options When y or n is typed Then shortcuts are ignored', () => {
+    expect(getConfirmPromptInputAction('y', {}, 3)).toBeUndefined();
+    expect(getConfirmPromptInputAction('n', {}, 3)).toBeUndefined();
+  });
+
+  it('Given selection moved right When enter is applied Then current option is selected', () => {
+    const moved = applyConfirmPromptInput(createSelectionFlowState(), 'next', 2).state;
+
+    const result = applyConfirmPromptInput(moved, 'select', 2);
+
+    expect(result.effect).toEqual({ type: 'select', index: 1 });
+  });
+
+  it('Given prompt is resolved When shortcut is applied Then no second selection is emitted', () => {
+    const selected = applyConfirmPromptInput(createSelectionFlowState(), 'select', 2).state;
+
+    const result = applyConfirmPromptInput(selected, { type: 'shortcut', index: 1 }, 2);
+
+    expect(result.effect).toEqual({ type: 'none' });
+  });
+});
+
+describe('permission prompt flow', () => {
+  it('Given y shortcut When applied Then allow decision is emitted', () => {
+    const action = getPermissionPromptInputAction('y', {});
+
+    const result = applyPermissionPromptInput(createSelectionFlowState(), action!);
+
+    expect(result.effect).toEqual({ type: 'resolve', decision: true });
+  });
+
+  it('Given a shortcut When applied Then allow-session decision is emitted', () => {
+    const action = getPermissionPromptInputAction('a', {});
+
+    const result = applyPermissionPromptInput(createSelectionFlowState(), action!);
+
+    expect(result.effect).toEqual({ type: 'resolve', decision: 'allow-session' });
+  });
+
+  it('Given p or 3 shortcut When applied Then allow-project decision is emitted', () => {
+    expect(
+      applyPermissionPromptInput(
+        createSelectionFlowState(),
+        getPermissionPromptInputAction('p', {})!,
+      ).effect,
+    ).toEqual({ type: 'resolve', decision: 'allow-project' });
+    expect(
+      applyPermissionPromptInput(
+        createSelectionFlowState(),
+        getPermissionPromptInputAction('3', {})!,
+      ).effect,
+    ).toEqual({ type: 'resolve', decision: 'allow-project' });
+  });
+
+  it('labels unavailable project approval and ignores its shortcut or selection', () => {
+    expect(permissionPromptOptionsFor('Bash(git *)', false)[2]).toBe(
+      'Project-wide approval unavailable',
+    );
+    const state = createSelectionFlowState();
+    expect(
+      applyPermissionPromptInput(state, getPermissionPromptInputAction('p', {})!, false),
+    ).toEqual({ state, effect: { type: 'none' } });
+    const selectedProject = applyPermissionPromptInput(
+      applyPermissionPromptInput(state, 'next', false).state,
+      'next',
+      false,
+    ).state;
+    expect(applyPermissionPromptInput(selectedProject, 'select', false).effect).toEqual({
+      type: 'none',
+    });
+  });
+
+  it('Given deny shortcuts When applied Then false decision is emitted', () => {
+    expect(
+      applyPermissionPromptInput(
+        createSelectionFlowState(),
+        getPermissionPromptInputAction('n', {})!,
+      ).effect,
+    ).toEqual({ type: 'resolve', decision: false });
+    expect(
+      applyPermissionPromptInput(
+        createSelectionFlowState(),
+        getPermissionPromptInputAction('4', {})!,
+      ).effect,
+    ).toEqual({ type: 'resolve', decision: false });
+  });
+
+  it('Given arrow navigation When enter is applied Then selected permission is resolved', () => {
+    const moved = applyPermissionPromptInput(createSelectionFlowState(), 'next').state;
+
+    const result = applyPermissionPromptInput(moved, 'select');
+
+    expect(result.effect).toEqual({ type: 'resolve', decision: 'allow-session' });
+  });
+
+  it('Given permission is resolved When shortcut is applied Then no second decision is emitted', () => {
+    const resolved = applyPermissionPromptInput(createSelectionFlowState(), 'select').state;
+
+    const result = applyPermissionPromptInput(resolved, { type: 'shortcut', index: 2 });
+
+    expect(result.effect).toEqual({ type: 'none' });
+  });
+
+  // CLI-030 TC-03: [s] option is shown
+  it('Given PERMISSION_PROMPT_OPTIONS When inspected Then session option contains [s] hint', () => {
+    expect(PERMISSION_PROMPT_OPTIONS[1]).toContain('[s]');
+  });
+
+  // CLI-030 TC-03: s key maps to allow-session
+  it('Given s shortcut When applied Then allow-session decision is emitted', () => {
+    const action = getPermissionPromptInputAction('s', {});
+
+    const result = applyPermissionPromptInput(createSelectionFlowState(), action!);
+
+    expect(result.effect).toEqual({ type: 'resolve', decision: 'allow-session' });
+  });
+
+  // CLI-030 TC-04: allow-once (y) does not add to session list
+  it('Given y (allow-once) shortcut When applied Then true decision is emitted (not allow-session)', () => {
+    const action = getPermissionPromptInputAction('y', {});
+
+    const result = applyPermissionPromptInput(createSelectionFlowState(), action!);
+
+    expect(result.effect).toEqual({ type: 'resolve', decision: true });
+  });
+});

package/src/__tests__/confirm-prompt.test.tsx

@@ -0,0 +1,103 @@
+import React from 'react';
+import { describe, it, expect, vi } from 'vitest';
+import { render } from 'ink-testing-library';
+import ConfirmPrompt from '../ConfirmPrompt.js';
+import { formatKeyHints } from '../key-hint-footer.js';
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe('ConfirmPrompt', () => {
+  it('renders message text', () => {
+    const { lastFrame } = render(<ConfirmPrompt message="Are you sure?" onSelect={() => {}} />);
+    expect(lastFrame()).toContain('Are you sure?');
+  });
+
+  it('renders default Yes/No options', () => {
+    const { lastFrame } = render(<ConfirmPrompt message="Confirm?" onSelect={() => {}} />);
+    const frame = lastFrame()!;
+    expect(frame).toContain('Yes');
+    expect(frame).toContain('No');
+  });
+
+  it('renders custom options', () => {
+    const { lastFrame } = render(
+      <ConfirmPrompt message="Pick" options={['A', 'B', 'C']} onSelect={() => {}} />,
+    );
+    const frame = lastFrame()!;
+    expect(frame).toContain('A');
+    expect(frame).toContain('B');
+    expect(frame).toContain('C');
+  });
+
+  it('first option is highlighted by default', () => {
+    const { lastFrame } = render(<ConfirmPrompt message="Confirm?" onSelect={() => {}} />);
+    const frame = lastFrame()!;
+    // The selected item has '> ' prefix
+    expect(frame).toContain('> Yes');
+  });
+
+  it('selects first option on Enter', () => {
+    const onSelect = vi.fn();
+    const { stdin } = render(<ConfirmPrompt message="Confirm?" onSelect={onSelect} />);
+    stdin.write('\r');
+    expect(onSelect).toHaveBeenCalledWith(0);
+  });
+
+  it('navigates to second option with arrow down and selects', async () => {
+    const onSelect = vi.fn();
+    const { stdin } = render(<ConfirmPrompt message="Confirm?" onSelect={onSelect} />);
+    // Arrow down (move to No)
+    stdin.write('\x1b[B');
+    await delay(50);
+    stdin.write('\r');
+    expect(onSelect).toHaveBeenCalledWith(1);
+  });
+
+  it('y shortcut selects first option (Yes)', () => {
+    const onSelect = vi.fn();
+    const { stdin } = render(<ConfirmPrompt message="Confirm?" onSelect={onSelect} />);
+    stdin.write('y');
+    expect(onSelect).toHaveBeenCalledWith(0);
+  });
+
+  it('n shortcut selects second option (No)', () => {
+    const onSelect = vi.fn();
+    const { stdin } = render(<ConfirmPrompt message="Confirm?" onSelect={onSelect} />);
+    stdin.write('n');
+    expect(onSelect).toHaveBeenCalledWith(1);
+  });
+
+  it('y/n shortcuts do not work with more than 2 options', () => {
+    const onSelect = vi.fn();
+    const { stdin } = render(
+      <ConfirmPrompt message="Pick" options={['A', 'B', 'C']} onSelect={onSelect} />,
+    );
+    stdin.write('y');
+    stdin.write('n');
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
+  it('ignores input after selection (no double-fire)', () => {
+    const onSelect = vi.fn();
+    const { stdin } = render(<ConfirmPrompt message="Confirm?" onSelect={onSelect} />);
+    stdin.write('\r');
+    stdin.write('\r');
+    stdin.write('y');
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+
+  // SCREEN-005: footer names the real keys (←→; the flow suppresses Esc, so the footer omits it —
+  // the footer lists exactly the keys that do something).
+  it('renders the footer in the shared key-hint grammar and omits Esc', () => {
+    const { lastFrame } = render(<ConfirmPrompt message="Confirm?" onSelect={() => {}} />);
+    const frame = lastFrame()!;
+    expect(frame).toContain(
+      formatKeyHints([
+        { keys: '←→', label: 'Navigate' },
+        { keys: 'Enter', label: 'Confirm' },
+      ]),
+    );
+    expect(frame).not.toContain('Esc');
+    expect(frame).not.toContain('arrow keys');
+  });
+});

package/src/__tests__/contextual-keybindings-input.test.tsx

@@ -0,0 +1,158 @@
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createLoopCommandEntry, createRemoteControlCommandEntry } from '@robota-sdk/agent-command';
+import InputArea from '../InputArea.js';
+import { KeybindingsProvider } from '../keybindings/keybindings-context.js';
+import { parseKeybindingsDocument } from '../keybindings/keybinding-registry.js';
+
+import type { IInputAreaHistorySearch } from '../hooks/useInputAreaHistorySearch.js';
+import type { IKeybindingsSource } from '../keybindings/node-keybindings-source.js';
+import type { ITuiCommandQueryPort } from '../tui-app-channel-port.js';
+
+async function tick(ms = 25): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function source(
+  bindings: Record<string, Record<string, string>> = {
+    'chat-input': { submit: 'ctrl+j' },
+    'autocomplete-menu': { accept: 'ctrl+j' },
+  },
+): IKeybindingsSource {
+  const parsed = parseKeybindingsDocument(
+    JSON.stringify({ version: 1, bindings }),
+    '/tmp/keybindings.json',
+  );
+  if (!parsed.ok) throw new Error(parsed.diagnostic.message);
+  return {
+    filePath: '/tmp/keybindings.json',
+    start: async () => undefined,
+    isStarted: () => true,
+    ensureFile: async () => '/tmp/keybindings.json',
+    getSnapshot: () => parsed.snapshot,
+    subscribe: () => () => undefined,
+    dispose: () => undefined,
+  };
+}
+
+describe('InputArea contextual keybindings', () => {
+  it('uses the same chord for autocomplete accept and then chat submit without double execution', async () => {
+    const onSubmit = vi.fn();
+    const commandQueryPort: ITuiCommandQueryPort = {
+      getCommands: () => [{ name: 'help', description: 'Show help', source: 'test' }],
+      getSubcommands: () => [],
+    };
+    const { stdin, lastFrame } = render(
+      <KeybindingsProvider source={source()}>
+        <InputArea onSubmit={onSubmit} isDisabled={false} commandQueryPort={commandQueryPort} />
+      </KeybindingsProvider>,
+    );
+    await tick();
+    stdin.write('/he');
+    await tick();
+    expect(lastFrame()).toContain('/help');
+    expect(lastFrame()).toContain('Ctrl+J Submit');
+
+    stdin.write('\r\n');
+    await tick();
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    stdin.write('\r\n');
+    await tick(50);
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith('/help');
+  });
+
+  it.each([
+    { name: 'remote-control', firstAction: 'status', entry: createRemoteControlCommandEntry() },
+    { name: 'loop', firstAction: 'list', entry: createLoopCommandEntry() },
+  ])(
+    'resets the selection when autocomplete changes from another parent to /$name',
+    async ({ name, firstAction, entry }) => {
+      const onSubmit = vi.fn();
+      const otherChildren = ['first', 'second', 'third'].map((child) => ({
+        name: child,
+        description: child,
+        source: 'test',
+        execute: async () => {},
+      }));
+      const commandQueryPort: ITuiCommandQueryPort = {
+        getCommands: () => [],
+        getSubcommands: (parent) =>
+          parent === 'other' ? otherChildren : parent === name ? (entry.subcommands ?? []) : [],
+      };
+      const { stdin, lastFrame } = render(
+        <KeybindingsProvider source={source()}>
+          <InputArea
+            initialValue="/other "
+            onSubmit={onSubmit}
+            isDisabled={false}
+            commandQueryPort={commandQueryPort}
+          />
+        </KeybindingsProvider>,
+      );
+      await tick();
+
+      stdin.write('\x1b[B\x1b[B'); // select index 2 under /other
+      await tick();
+      expect(lastFrame()).toContain('> third');
+      stdin.write('\x1b'); // dismiss so the text editor owns the next key
+      await tick();
+      stdin.write('\x15'); // Ctrl+U clears the current line
+      stdin.write(`/${name} `);
+      await tick();
+      expect(lastFrame()).toContain(`> ${firstAction}`);
+
+      stdin.write('\r\n');
+      await tick();
+      expect(onSubmit).not.toHaveBeenCalled();
+      stdin.write('\r\n');
+      await tick(50);
+      expect(onSubmit).toHaveBeenCalledWith(`/${name} ${firstAction}`);
+    },
+  );
+
+  // SCREEN-1993 TC-05: the open key and every overlay action are rebindable through the document,
+  // and the footer lists the live keys rather than the defaults.
+  it('rebinds the history-search open key and its actions through the document', async () => {
+    const onSubmit = vi.fn();
+    const historySearch: IInputAreaHistorySearch = {
+      source: {
+        async *read() {
+          yield {
+            entries: [
+              { at: '', sessionId: 'x', project: '/x', text: 'rotate the staging secrets' },
+            ],
+            skippedLines: 0,
+          };
+        },
+      },
+      sessionId: 's1',
+      project: '/p',
+    };
+    const { stdin, lastFrame } = render(
+      <KeybindingsProvider
+        source={source({
+          'chat-input': { 'history-search': 'ctrl+o' },
+          'history-search': { execute: 'ctrl+x', cancel: 'ctrl+g' },
+        })}
+      >
+        <InputArea onSubmit={onSubmit} isDisabled={false} historySearch={historySearch} />
+      </KeybindingsProvider>,
+    );
+    await tick();
+    stdin.write('\x12'); // the default ctrl+r no longer opens it
+    await tick();
+    expect(lastFrame()).not.toContain('(reverse-i-search)');
+    stdin.write('\x0f'); // ctrl+o
+    await tick();
+    expect(lastFrame()).toContain('(reverse-i-search)');
+    expect(lastFrame()).toContain('Ctrl+X Run');
+    expect(lastFrame()).toContain('Ctrl+G Close');
+    stdin.write('\x18'); // ctrl+x
+    await tick();
+    expect(onSubmit).toHaveBeenCalledWith('rotate the staging secrets');
+  });
+});

package/src/__tests__/default-tui-cli-adapter-host-settings.test.ts

@@ -0,0 +1,47 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createNodeHostSettingsSource } from '@robota-sdk/agent-framework';
+import { afterEach, expect, it } from 'vitest';
+
+import { createDefaultTuiCliAdapter } from '../create-default-tui-cli-adapter.js';
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+it('updates the host-selected settings file when changing the active model', () => {
+  const root = mkdtempSync(join(tmpdir(), 'tui-host-settings-'));
+  roots.push(root);
+  const settingsPath = join(root, 'product-settings.json');
+  writeFileSync(settingsPath, JSON.stringify({ currentProvider: 'custom', providers: { custom: {} } }));
+
+  const adapter = createDefaultTuiCliAdapter({
+    providerDefinitions: [],
+    reloadPluginCommandSource: () => undefined,
+    userSettingsPath: settingsPath,
+    settingsSources: [createNodeHostSettingsSource('user', settingsPath)],
+  });
+
+  adapter.applyActiveModelChange(root, 'custom-model', {});
+
+  expect(JSON.parse(readFileSync(settingsPath, 'utf8'))).toMatchObject({
+    providers: { custom: { model: 'custom-model' } },
+  });
+});
+
+it('keeps the host resume command formatter when one is supplied', () => {
+  const root = mkdtempSync(join(tmpdir(), 'tui-host-settings-'));
+  roots.push(root);
+  const adapter = createDefaultTuiCliAdapter({
+    providerDefinitions: [],
+    reloadPluginCommandSource: () => undefined,
+    userSettingsPath: join(root, 'product-settings.json'),
+    settingsSources: [],
+    formatResumeCommand: (sessionId) => `product --resume ${sessionId}`,
+  });
+  expect(adapter.formatResumeCommand?.('session_1')).toBe('product --resume session_1');
+});

package/src/__tests__/effort-reaches-the-session.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildTuiSessionOptions } from '../tui-session-options.js';
+
+import type { ITuiInteractionChannelOptions } from '../TuiInteractionChannel.js';
+
+/**
+ * ARCH-013 — a preset's `effort` is resolved at startup and then dropped.
+ *
+ * `TPresetEffort` is defined as `NonNullable<ICreateSessionOptions['effort']>` precisely so a preset
+ * can thread onto that seam, and three of the four built-in presets set it —
+ * `neutral-executor` asks for `'medium'`. At startup none of it arrives: no hop between the resolved
+ * preset and `createSession` carried the field, so the core applied its own `'high'` default.
+ *
+ * The same preset selected mid-session with `/preset` DOES apply it
+ * (`command-api/preset/preset-application.ts:91` → `applyModelOptions`), so one session could hold
+ * two different answers for the same preset depending on when it was chosen. That is the observable
+ * this pins, at the projection hop the TUI actually uses.
+ */
+function channelOptions(
+  overrides: Partial<ITuiInteractionChannelOptions> = {},
+): ITuiInteractionChannelOptions {
+  return { cwd: '/tmp', ...overrides } as ITuiInteractionChannelOptions;
+}
+
+describe('the TUI projection carries effort (ARCH-013)', () => {
+  it('forwards a resolved effort onto the session options', () => {
+    // Against the defect `effort` is not a key of the target type at all, so it is simply absent.
+    // Asserted over the entries rather than through a cast: the declared return type is the
+    // standard|injected union and only the standard arm can carry a construction-time option, but a
+    // double cast to reach the key would be the same "trust me" this whole item is about.
+    const built = buildTuiSessionOptions(channelOptions({ effort: 'medium' }));
+    expect(Object.entries(built)).toContainEqual(['effort', 'medium']);
+  });
+
+  it('omits the key entirely when no effort was resolved', () => {
+    // Not `undefined` — absent. The framework→provider seam owns the default, and a present-but-
+    // undefined key would claim a decision nobody made.
+    expect('effort' in buildTuiSessionOptions(channelOptions())).toBe(false);
+  });
+});

package/src/__tests__/execution-workspace-switcher.test.tsx

@@ -0,0 +1,147 @@
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { render } from 'ink-testing-library';
+import type {
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import ExecutionWorkspaceSwitcher from '../ExecutionWorkspaceSwitcher.js';
+import { formatKeyHints, SELECTION_INDICATOR } from '../key-hint-footer.js';
+import ExecutionWorkspaceDetailPane from '../ExecutionWorkspaceDetailPane.js';
+
+function makeEntry(overrides: Partial<IExecutionWorkspaceEntry>): IExecutionWorkspaceEntry {
+  return {
+    id: 'main:session_1',
+    sourceId: 'session_1',
+    kind: 'main_thread',
+    origin: { kind: 'user_prompt', sessionId: 'session_1' },
+    status: 'idle',
+    state: 'completed',
+    title: 'Main thread',
+    subtitle: '2 history entries',
+    unread: false,
+    attention: 'none',
+    visibility: 'default',
+    updatedAt: '2026-05-09T00:00:00.000Z',
+    controls: ['select'],
+    ...overrides,
+  };
+}
+
+function makeSnapshot(): IExecutionWorkspaceSnapshot {
+  return {
+    sessionId: 'session_1',
+    selectedEntryId: 'main:session_1',
+    updatedAt: '2026-05-09T00:00:00.000Z',
+    entries: [
+      makeEntry({ id: 'main:session_1', kind: 'main_thread', title: 'Main thread' }),
+      makeEntry({
+        id: 'task:agent_1',
+        sourceId: 'agent_1',
+        kind: 'background_task',
+        taskKind: 'agent',
+        status: 'running',
+        state: 'working',
+        title: 'Explore',
+        subtitle: 'general-purpose',
+        preview: 'Inspect task layer',
+        controls: ['select', 'cancel'],
+      }),
+    ],
+  };
+}
+
+describe('ExecutionWorkspaceSwitcher', () => {
+  it('renders main and background entries with selected radio markers', () => {
+    const { lastFrame } = render(
+      <ExecutionWorkspaceSwitcher
+        snapshot={makeSnapshot()}
+        selectedEntryId="task:agent_1"
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    );
+
+    const frame = lastFrame()!;
+    expect(frame).toContain('Execution workspace');
+    // SCREEN-1992: the state word sits beside the radio.
+    expect(frame).toContain('○ completed Main thread');
+    expect(frame).toContain('● working Explore agent');
+    expect(frame).toContain('Inspect task layer');
+  });
+
+  it('commits the highlighted entry on enter without invoking task controls', () => {
+    const onSelect = vi.fn();
+    const { stdin } = render(
+      <ExecutionWorkspaceSwitcher
+        snapshot={makeSnapshot()}
+        selectedEntryId="main:session_1"
+        onSelect={onSelect}
+        onClose={vi.fn()}
+      />,
+    );
+
+    stdin.write('\u001B[B');
+    stdin.write('\r');
+
+    expect(onSelect).toHaveBeenCalledWith('task:agent_1');
+  });
+
+  it('renders selected entry detail records from the SDK detail page', () => {
+    const entry = makeEntry({
+      id: 'task:agent_1',
+      sourceId: 'agent_1',
+      kind: 'background_task',
+      taskKind: 'agent',
+      status: 'completed',
+      title: 'Explore',
+      preview: 'Done',
+    });
+    const { lastFrame } = render(
+      <ExecutionWorkspaceDetailPane
+        entry={entry}
+        page={{
+          entryId: 'task:agent_1',
+          records: [{ id: 'r1', kind: 'result', text: 'Final background result' }],
+        }}
+      />,
+    );
+
+    const frame = lastFrame()!;
+    expect(frame).toContain('Viewing Explore agent');
+    expect(frame).toContain('Final background result');
+  });
+});
+
+// SCREEN-005: switcher footer + focused-row cursor go through the key-hint/indicator SSOT.
+describe('ExecutionWorkspaceSwitcher affordance (SCREEN-005)', () => {
+  it('renders the footer in the shared key-hint grammar (navigate → primary → dismiss)', () => {
+    const { lastFrame } = render(
+      <ExecutionWorkspaceSwitcher
+        snapshot={makeSnapshot()}
+        selectedEntryId="main:session_1"
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    );
+    expect(lastFrame()!).toContain(
+      formatKeyHints([
+        { keys: '↑↓', label: 'Navigate' },
+        { keys: 'Enter', label: 'Switch' },
+        { keys: 'Ctrl+B/Esc', label: 'Close' },
+      ]),
+    );
+  });
+
+  it('marks the focused row with the selection indicator', () => {
+    const { lastFrame } = render(
+      <ExecutionWorkspaceSwitcher
+        snapshot={makeSnapshot()}
+        selectedEntryId="main:session_1"
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    );
+    expect(lastFrame()!).toContain(`${SELECTION_INDICATOR}`);
+  });
+});