@robota-sdk/agent-ui-terminal 3.0.0-beta.82 → 3.0.0-beta.83

package/src/__tests__/TuiInteractionChannel.display-contract.test.ts

@@ -13,7 +13,11 @@
  *   - every history assertion checks entry.type (= role) explicitly
  *   - timing: user message visible BEFORE complete fires
  */
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 vi.mock('@robota-sdk/agent-framework', async () => {
   const actual = await vi.importActual<typeof import('@robota-sdk/agent-framework')>(
@@ -42,8 +46,7 @@ vi.mock('@robota-sdk/agent-framework', async () => {
         getPendingPrompt: vi.fn().mockReturnValue(null),
         abort: vi.fn(),
         cancelQueue: vi.fn(),
-        listSelfPacedLoops: vi.fn().mockReturnValue([]),
-        stopSelfPacedLoop: vi.fn().mockResolvedValue(undefined),
+        stopWaitingSelfPacedLoop: vi.fn().mockResolvedValue({ kind: 'none' }),
         getContextState: vi.fn().mockReturnValue({
           usedPercentage: 0,
           usedTokens: 0,
@@ -77,12 +80,15 @@ import { TuiInteractionChannel } from '../TuiInteractionChannel.js';
 import type { IAIProvider, IHistoryEntry } from '@robota-sdk/agent-core';
 import type { IExecutionResult } from '@robota-sdk/agent-interface-session';
 
+/** The session's working directory: private to this run, never a fixed name under /tmp. */
+const SESSION_CWD = mkdtempSync(join(tmpdir(), 'robota-tui-display-'));
+afterAll(() => rmSync(SESSION_CWD, { recursive: true, force: true }));
+
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 type MockSession = {
   getFullHistory: ReturnType<typeof vi.fn>;
-  listSelfPacedLoops: ReturnType<typeof vi.fn>;
-  stopSelfPacedLoop: ReturnType<typeof vi.fn>;
+  stopWaitingSelfPacedLoop: ReturnType<typeof vi.fn>;
   on: ReturnType<typeof vi.fn>;
   emit: (event: string, ...args: unknown[]) => void;
 };
@@ -97,7 +103,7 @@ function emitSessionEvent(channel: TuiInteractionChannel, event: string, ...args
 
 function makeChannel(provider: IAIProvider = {} as IAIProvider): TuiInteractionChannel {
   return new TuiInteractionChannel({
-    cwd: '/tmp/test',
+    cwd: SESSION_CWD,
     provider,
   });
 }
@@ -139,40 +145,44 @@ afterEach(() => {
 // ── Group D: display contract (what the user sees) ────────────────────────────
 
 describe('Group D — display contract: history entries and active tools', () => {
-  it('keeps automatic naming text-only when an external event starts the session', async () => {
+  it('leaves naming to the session: a first prompt asks the provider for no name', async () => {
     const chat = vi.fn().mockResolvedValue({ role: 'assistant', content: 'Event summary' });
     const channel = makeChannel({ chat } as unknown as IAIProvider);
     await channel.start();
 
     emitSessionEvent(channel, 'turn_source', 'external');
     emitSessionEvent(channel, 'user_message', 'external event');
+    await vi.runOnlyPendingTimersAsync();
 
-    expect(chat).toHaveBeenCalledTimes(1);
-    expect(chat.mock.calls[0]?.[1]?.toolChoice).toBe('none');
+    expect(chat).not.toHaveBeenCalled();
+    expect(channel.sessionName).toBeUndefined();
     await channel.stop();
   });
 
-  it('Esc stops the only waiting self-paced loop without aborting the session', async () => {
+  it('Esc asks the session to stop its waiting loop and shows what it did', async () => {
     const channel = makeChannel();
     const session = getMockSession(channel);
-    session.listSelfPacedLoops.mockReturnValue([{ loopId: 'loop_one', phase: 'waiting' }]);
+    session.stopWaitingSelfPacedLoop.mockResolvedValue({ kind: 'stopped', loopId: 'loop_one' });
     await channel.stopWaitingSelfPacedLoop();
-    expect(session.stopSelfPacedLoop).toHaveBeenCalledWith('loop_one', 'Loop stopped by Esc');
-    expect(channel.stateManager.history.some((entry) =>
-      JSON.stringify(entry).includes('loop_one'))).toBe(true);
+    expect(session.stopWaitingSelfPacedLoop).toHaveBeenCalledWith('Loop stopped by Esc');
+    expect(channel.stateManager.history.at(-1)?.data).toMatchObject({
+      content: 'Loop loop_one stopped by Esc.',
+    });
   });
 
-  it('Esc does not guess which loop to stop when several are waiting', async () => {
+  it('Esc shows the session\'s word when several loops wait, and nothing when none does', async () => {
     const channel = makeChannel();
     const session = getMockSession(channel);
-    session.listSelfPacedLoops.mockReturnValue([
-      { loopId: 'loop_one', phase: 'waiting' },
-      { loopId: 'loop_two', phase: 'waiting' },
-    ]);
     await channel.stopWaitingSelfPacedLoop();
-    expect(session.stopSelfPacedLoop).not.toHaveBeenCalled();
-    expect(channel.stateManager.history.some((entry) =>
-      JSON.stringify(entry).includes('/loop stop'))).toBe(true);
+    expect(channel.stateManager.history).toHaveLength(0);
+    session.stopWaitingSelfPacedLoop.mockResolvedValue({
+      kind: 'several',
+      message: 'Several self-paced loops are waiting. Use /loop list and /loop stop <id> to choose one.',
+    });
+    await channel.stopWaitingSelfPacedLoop();
+    expect(channel.stateManager.history.at(-1)?.data).toMatchObject({
+      content: expect.stringContaining('/loop stop'),
+    });
   });
 
   it('D1 (CLI-B05): user_message event immediately adds role=user entry before complete', async () => {

package/src/__tests__/TuiInteractionChannel.lifecycle.test.ts

@@ -4,7 +4,11 @@
  *
  * No Ink rendering, no PTY — pure TypeScript.
  */
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 vi.mock('@robota-sdk/agent-framework', async () => {
   const actual = await vi.importActual<typeof import('@robota-sdk/agent-framework')>(
@@ -126,13 +130,17 @@ function makeMockTransportRegistry(): {
   };
 }
 
+/** The session's working directory: private to this run, never a fixed name under /tmp. */
+const SESSION_CWD = mkdtempSync(join(tmpdir(), 'robota-tui-lifecycle-'));
+afterAll(() => rmSync(SESSION_CWD, { recursive: true, force: true }));
+
 function makeChannel(opts?: {
   transportRegistry?: ITransportRegistryView;
   bindTransports?: (session: IInteractiveSession) => void | Promise<void>;
   onSessionEventDeliveryError?: (error: Error, event: TInteractiveEventName) => void;
 }): TuiInteractionChannel {
   return new TuiInteractionChannel({
-    cwd: '/tmp/test',
+    cwd: SESSION_CWD,
     provider: {} as IAIProvider,
     ...opts,
   });

package/src/__tests__/attached-app-session-switch.test.tsx

@@ -0,0 +1,317 @@
+/**
+ * #3189: the full App on a wire channel. The session picker lists the host's sessions, and choosing
+ * one asks the host to switch instead of building a new channel.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import App from '../App.js';
+import { WireTuiChannel } from '../wire-tui-channel.js';
+
+import type { IAttachedSessionConnection } from '../attached-session-connection.js';
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { TClientMessage, TServerMessage } from '@robota-sdk/agent-transport/client';
+
+const TICK_MS = 30;
+const FRAME_DEADLINE_MS = 3000;
+
+function tick(ms = TICK_MS): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitFor(predicate: () => boolean, describeFailure: () => string): Promise<void> {
+  const deadline = Date.now() + FRAME_DEADLINE_MS;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await tick(10);
+  }
+  throw new Error(`waitFor timeout\n${describeFailure()}`);
+}
+
+function scriptedConnection(): IAttachedSessionConnection & {
+  sent: TClientMessage[];
+  push: (message: TServerMessage) => void;
+} {
+  const listeners = new Set<(message: TServerMessage) => void>();
+  const sent: TClientMessage[] = [];
+  return {
+    sent,
+    send: (message) => {
+      sent.push(message);
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    onClose: () => () => undefined,
+    push: (message) => {
+      for (const listener of [...listeners]) listener(message);
+    },
+  };
+}
+
+function cliAdapter(settingsPath: string): ITuiCliAdapter {
+  return {
+    getUserSettingsPath: () => settingsPath,
+    readSettings: () => ({}),
+    reloadPluginCommandSource: vi.fn(),
+    applyActiveModelChange: vi.fn().mockReturnValue({ applied: true }),
+    getGitBranch: vi.fn().mockReturnValue(undefined),
+    getProviderDisplayName: vi.fn((type: string) => type),
+  };
+}
+
+function lastListRequestId(sent: readonly TClientMessage[]): string {
+  const requests = sent.filter(
+    (message): message is Extract<TClientMessage, { type: 'list-sessions' }> =>
+      message.type === 'list-sessions',
+  );
+  return requests.at(-1)?.requestId ?? '';
+}
+
+describe('the full App attached to a host over the wire', () => {
+  let cwd: string;
+
+  beforeEach(() => {
+    cwd = mkdtempSync(join(tmpdir(), 'robota-attached-app-'));
+  });
+
+  afterEach(() => {
+    rmSync(cwd, { recursive: true, force: true });
+  });
+
+  it("lists the host's sessions in the picker and asks the host to switch", async () => {
+    const link = scriptedConnection();
+    const channel = new WireTuiChannel({ connection: link, driverId: 'attach:1' });
+    const createChannel = vi.fn(() => channel);
+    const view = render(
+      <App
+        cwd={cwd}
+        createChannel={createChannel}
+        requestSessionSwitch={(sessionId) => channel.requestSessionSwitch(sessionId)}
+        cliAdapter={cliAdapter(join(cwd, 'settings.json'))}
+      />,
+    );
+    try {
+      await waitFor(
+        () => link.sent.some((message) => message.type === 'list-sessions'),
+        () => JSON.stringify(link.sent),
+      );
+      // `/resume` ran on the host, which routes the picker back to this terminal only.
+      link.push({
+        type: 'ui_intent',
+        event: { intent: { type: 'show-session-picker' }, requesterDriverId: 'attach:1' },
+      });
+      link.push({
+        type: 'sessions',
+        requestId: lastListRequestId(link.sent),
+        listing: {
+          currentSessionId: 'host-current',
+          sessions: [
+            {
+              id: 'host-other-session',
+              name: 'Host session',
+              cwd,
+              updatedAt: '2026-09-26T10:00:00.000Z',
+              messageCount: 4,
+              preview: 'kept by the daemon',
+            },
+          ],
+          unreadableSessionIds: [],
+        },
+      });
+      await waitFor(
+        () => (view.lastFrame() ?? '').includes('Host session'),
+        () => view.lastFrame() ?? '<none>',
+      );
+      expect(view.lastFrame()).toContain('Select a session to resume');
+      await tick();
+
+      link.sent.length = 0;
+      view.stdin.write('\r');
+      await waitFor(
+        () => link.sent.some((message) => message.type === 'switch-session'),
+        () => JSON.stringify(link.sent),
+      );
+      expect(link.sent).toContainEqual({
+        type: 'switch-session',
+        sessionId: 'host-other-session',
+        requestId: expect.any(String),
+      });
+      // The App keeps its channel; the host's `session_switched` is what moves it.
+      expect(createChannel).toHaveBeenCalledTimes(1);
+      // A refusal is shown where the terminal shows what happened, and the switch is over.
+      const request = link.sent.find((message) => message.type === 'switch-session');
+      link.push({
+        type: 'session_change_failed',
+        code: 'limit',
+        message: 'Four sessions are live; none can be closed.',
+        ...(request?.type === 'switch-session' && request.requestId !== undefined
+          ? { requestId: request.requestId }
+          : {}),
+      });
+      await waitFor(
+        () => (view.lastFrame() ?? '').includes('Four sessions are live; none can be closed.'),
+        () => view.lastFrame() ?? '<none>',
+      );
+    } finally {
+      view.unmount();
+      await channel.stop();
+    }
+  });
+
+  async function resumeAgainst(
+    answer: (requestId: string) => TServerMessage,
+    notice: string,
+  ): Promise<string> {
+    const link = scriptedConnection();
+    const channel = new WireTuiChannel({ connection: link, driverId: 'attach:1' });
+    const view = render(
+      <App
+        cwd={cwd}
+        createChannel={() => channel}
+        requestSessionSwitch={(sessionId) => channel.requestSessionSwitch(sessionId)}
+        cliAdapter={cliAdapter(join(cwd, 'settings.json'))}
+      />,
+    );
+    try {
+      await waitFor(
+        () => (view.lastFrame() ?? '').includes('Type a message'),
+        () => view.lastFrame() ?? '<none>',
+      );
+      link.sent.length = 0;
+      link.push({
+        type: 'ui_intent',
+        event: { intent: { type: 'show-session-picker' }, requesterDriverId: 'attach:1' },
+      });
+      link.push(answer(lastListRequestId(link.sent)));
+      await waitFor(
+        () => (view.lastFrame() ?? '').includes(notice),
+        () => view.lastFrame() ?? '<none>',
+      );
+      await tick();
+      return view.lastFrame() ?? '';
+    } finally {
+      view.unmount();
+      await channel.stop();
+    }
+  }
+
+  it('gives the prompt back with the reason when the host cannot list its sessions', async () => {
+    const frame = await resumeAgainst(
+      (requestId) => ({
+        type: 'sessions_error',
+        requestId,
+        code: 'not_available',
+        message: 'Session listing is not available on this host.',
+      }),
+      'Session listing is not available on this host.',
+    );
+    expect(frame).not.toContain('Select a session to resume');
+    expect(frame).not.toContain('Waiting for response');
+    expect(frame).toContain('Type a message');
+  });
+
+  it("prints the new session's transcript when the switch and its history arrive together", async () => {
+    const link = scriptedConnection();
+    const channel = new WireTuiChannel({ connection: link, driverId: 'attach:1' });
+    const view = render(
+      <App
+        cwd={cwd}
+        createChannel={() => channel}
+        requestSessionSwitch={(sessionId) => channel.requestSessionSwitch(sessionId)}
+        cliAdapter={cliAdapter(join(cwd, 'settings.json'))}
+      />,
+    );
+    const entry = (id: string, content: string) => ({
+      id,
+      timestamp: '2026-09-26T10:00:00.000Z',
+      category: 'chat',
+      type: 'user',
+      data: { id: `m-${id}`, role: 'user', content, state: 'complete' },
+    });
+    try {
+      await waitFor(
+        () => link.sent.some((message) => message.type === 'get-history'),
+        () => JSON.stringify(link.sent),
+      );
+      link.push({
+        type: 'history',
+        startIndex: 0,
+        total: 3,
+        entries: [entry('o1', 'old one'), entry('o2', 'old two'), entry('o3', 'old three')],
+      });
+      await waitFor(
+        () => (view.lastFrame() ?? '').includes('old three'),
+        () => view.lastFrame() ?? '<none>',
+      );
+      // One chunk from the host: the switch and the new session's history, handled in one pass.
+      link.push({ type: 'session_switched', event: { sessionId: 'session-2' } });
+      link.push({
+        type: 'history',
+        startIndex: 0,
+        total: 1,
+        entries: [entry('n1', 'new session prompt')],
+      });
+      await waitFor(
+        () => (view.lastFrame() ?? '').includes('new session prompt'),
+        () => view.lastFrame() ?? '<none>',
+      );
+      expect(view.lastFrame()).toContain('Switched to session session-2.');
+    } finally {
+      view.unmount();
+      await channel.stop();
+    }
+  });
+
+  it('detaches on Ctrl-] the way it does on Ctrl-C and /exit', async () => {
+    const link = scriptedConnection();
+    const channel = new WireTuiChannel({ connection: link, driverId: 'attach:1' });
+    const view = render(
+      <App
+        cwd={cwd}
+        createChannel={() => channel}
+        requestSessionSwitch={(sessionId) => channel.requestSessionSwitch(sessionId)}
+        cliAdapter={cliAdapter(join(cwd, 'settings.json'))}
+      />,
+    );
+    try {
+      await waitFor(
+        () => (view.lastFrame() ?? '').includes('Type a message'),
+        () => view.lastFrame() ?? '<none>',
+      );
+      view.stdin.write('\x1d');
+      await waitFor(
+        () => channel.getSnapshot().isShuttingDown,
+        () => view.lastFrame() ?? '<none>',
+      );
+      expect(JSON.stringify(channel.getSnapshot().history)).toContain(
+        'Detached. The session keeps running.',
+      );
+      expect(link.sent.some((message) => message.type === 'submit')).toBe(false);
+    } finally {
+      view.unmount();
+      await channel.stop();
+    }
+  });
+
+  it('opens no empty picker when the host has no sessions to resume', async () => {
+    const frame = await resumeAgainst(
+      (requestId) => ({
+        type: 'sessions',
+        requestId,
+        listing: { currentSessionId: 'host-current', sessions: [], unreadableSessionIds: [] },
+      }),
+      'No saved sessions to resume',
+    );
+    expect(frame).not.toContain('Select a session to resume');
+    expect(frame).not.toContain('Waiting for response');
+    expect(frame).toContain('Type a message');
+  });
+});

package/src/__tests__/checkpoint-store-per-channel.test.ts

@@ -0,0 +1,81 @@
+/**
+ * #3231: the TUI builds a new channel on every session switch, and it may do so before the old
+ * session's turn has ended. A checkpoint store holds one turn in progress, so a store shared across
+ * channels would let the old turn close the new session's turn. Each channel gets its own.
+ */
+
+import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createScriptedProvider } from '@robota-sdk/agent-core/testing';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createInProcessChannelFactory } from '../render.js';
+import { TerminalHandoffController } from '../terminal-handoff-controller.js';
+
+import type { IChannelServices, IRenderOptions } from '../render.js';
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { ITuiAppChannelPort } from '../tui-app-channel-port.js';
+import type { EditCheckpointStore } from '@robota-sdk/agent-framework';
+
+const sessionStores = vi.hoisted(() => [] as unknown[]);
+
+vi.mock('../tui-session-options.js', async (importOriginal) => {
+  const original = await importOriginal<typeof import('../tui-session-options.js')>();
+  return {
+    buildTuiSessionOptions: (
+      ...args: Parameters<typeof original.buildTuiSessionOptions>
+    ): ReturnType<typeof original.buildTuiSessionOptions> => {
+      const built = original.buildTuiSessionOptions(...args);
+      sessionStores.push(built.editCheckpointStore);
+      return built;
+    },
+  };
+});
+
+function fakeCliAdapter(settingsPath: string): ITuiCliAdapter {
+  return {
+    getUserSettingsPath: () => settingsPath,
+    readSettings: () => ({}),
+    reloadPluginCommandSource: vi.fn(),
+    applyActiveModelChange: vi.fn().mockReturnValue({ applied: true }),
+    getGitBranch: vi.fn().mockReturnValue(undefined),
+    getProviderDisplayName: vi.fn((type: string) => type),
+  };
+}
+
+describe('#3231: the in-process channel factory', () => {
+  const channels: ITuiAppChannelPort[] = [];
+  let cwd: string | undefined;
+
+  afterEach(async () => {
+    for (const channel of channels.splice(0)) await channel.stop();
+    sessionStores.splice(0);
+    if (cwd !== undefined) rmSync(cwd, { recursive: true, force: true });
+    cwd = undefined;
+  });
+
+  it('gives each channel, including a switched-to one, its own checkpoint store', () => {
+    cwd = realpathSync(mkdtempSync(join(tmpdir(), 'robota-store-per-channel-')));
+    const createEditCheckpointStore = vi.fn(() => ({}) as EditCheckpointStore);
+    const options: IRenderOptions = {
+      cwd,
+      provider: createScriptedProvider([{ text: 'unused' }]).provider,
+      cliAdapter: fakeCliAdapter(join(cwd, 'settings.json')),
+      createEditCheckpointStore,
+    };
+    const services = {
+      terminalHandoff: new TerminalHandoffController(),
+    } as unknown as IChannelServices;
+    const createChannel = createInProcessChannelFactory(options, services);
+
+    channels.push(createChannel(), createChannel('switched-to-session'));
+
+    expect(createEditCheckpointStore).toHaveBeenCalledTimes(2);
+    expect(sessionStores).toHaveLength(2);
+    expect(sessionStores[0]).toBeDefined();
+    expect(sessionStores[1]).toBeDefined();
+    expect(sessionStores[0]).not.toBe(sessionStores[1]);
+  });
+});

package/src/__tests__/command-handoff-pty-e2e.test.ts

@@ -49,7 +49,7 @@ describe('command handoff PTY E2E', () => {
       tempDirs.push(dir);
       const outputPath = join(dir, 'result.json');
       const session = spawnPtyFixture(FIXTURE, {
-        argv: ['shell', outputPath, 'IFS= read -r line; printf "SHELL_GOT:[%s]\\n" "$line"'],
+        argv: ['shell', outputPath],
         cwd: PACKAGE_DIR,
         // HARNESS-025: isolated HOME — the subshell must not read the developer's `~` (a real
         // shell rc there would otherwise change what the handoff child does).
@@ -81,7 +81,7 @@ describe('command handoff PTY E2E', () => {
       tempDirs.push(dir);
       const outputPath = join(dir, 'result.json');
       const session = spawnPtyFixture(FIXTURE, {
-        argv: ['editor', outputPath, ''],
+        argv: ['editor', outputPath],
         cwd: PACKAGE_DIR,
         // HARNESS-025: isolated HOME — only the EDITOR override comes from the test, so a real
         // `~/.selected_editor` (or similar) on the host cannot influence the assertion.

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

@@ -34,10 +34,12 @@ it('updates the host-selected settings file when changing the active 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: '/tmp/product-settings.json',
+    userSettingsPath: join(root, 'product-settings.json'),
     settingsSources: [],
     formatResumeCommand: (sessionId) => `product --resume ${sessionId}`,
   });

package/src/__tests__/fixtures/command-handoff-driver.tsx

@@ -9,8 +9,10 @@
  * terminal can: the controller releasing raw mode so the child (subshell / `$EDITOR`) owns the TTY,
  * and `runWithTerminal` returning so the TUI resumes.
  *
- * argv: [mode ('shell'|'editor'), outputPath, commandArg?]. Markers: `@@READY canHandoff=…@@`,
- * `@@CMD_DONE@@`, `@@INPUT_AFTER_HANDOFF …@@`. A JSON result
+ * argv: [mode ('shell'|'editor'), outputPath]. The `/shell` command text is fixed here rather than
+ * taken from argv: argv only selects the mode, so no process input becomes shell text.
+ *
+ * Markers: `@@READY canHandoff=…@@`, `@@CMD_DONE@@`, `@@INPUT_AFTER_HANDOFF …@@`. A JSON result
  * `{ success, exitCode?, message }` is written to outputPath.
  */
 import { writeFileSync } from 'node:fs';
@@ -30,7 +32,8 @@ import type {
 
 const MODE = process.argv[2];
 const OUTPUT_PATH = process.argv[3];
-const COMMAND_ARG = process.argv[4] ?? '';
+/** Reads one line from the handed-off terminal and echoes it back, proving the child owned the TTY. */
+const SHELL_COMMAND = 'IFS= read -r line; printf "SHELL_GOT:[%s]\\n" "$line"';
 
 const controller = new TerminalHandoffController();
 let resolveInputAfterHandoff: ((input: string) => void) | undefined;
@@ -78,8 +81,8 @@ async function main(): Promise<void> {
   const ctx = createTestCommandHost({ overrides: context });
   const result =
     MODE === 'editor'
-      ? await executeEditorCommand(ctx, COMMAND_ARG)
-      : await executeShellCommand(ctx, COMMAND_ARG);
+      ? await executeEditorCommand(ctx, '')
+      : await executeShellCommand(ctx, SHELL_COMMAND);
 
   marker('CMD_DONE');
   const inputAfterHandoff = await new Promise<string>((resolve) => {

package/src/__tests__/grant-history-reaches-the-session.test.ts

@@ -0,0 +1,31 @@
+/**
+ * #3189 — the run's external-event grant history reaches every session the TUI builds. It is created
+ * once per run so a session switch replays no spent token and resets no rate; dropped on the way
+ * (the render projection copies field by field, and a spread skips the excess-property check), each
+ * session would open its grants with an empty history.
+ */
+
+import { createExternalEventGrantHistory } from '@robota-sdk/agent-framework';
+import { describe, expect, it } from 'vitest';
+
+import { toChannelOptions } from '../render.js';
+import { buildTuiSessionOptions } from '../tui-session-options.js';
+
+import type { IRenderOptions } from '../render.js';
+
+describe('#3189: the grant history survives the TUI projection', () => {
+  it('carries the same history instance into every session it builds', () => {
+    const history = createExternalEventGrantHistory();
+    const options = {
+      cwd: '/work',
+      provider: {} as never,
+      externalEventGrantHistory: history,
+    } as unknown as IRenderOptions;
+
+    const first = buildTuiSessionOptions(toChannelOptions(options, undefined));
+    const switchedTo = buildTuiSessionOptions(toChannelOptions(options, 'session-b'));
+
+    expect(first.externalEventGrantHistory).toBe(history);
+    expect(switchedTo.externalEventGrantHistory).toBe(history);
+  });
+});