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

package/src/__tests__/real-cursor-positioning.test.tsx

@@ -0,0 +1,264 @@
+/**
+ * CLI-062 — real-terminal-cursor positioning through ink's actual interactive render path.
+ *
+ * Renders CjkTextInput inside a TransportTUI-shaped harness against a fake TTY stdout
+ * (`interactive: true`), then interprets the raw ANSI stream with the same VT logic a terminal
+ * emulator (and the OS IME) applies. This is the component-level half of the CLI-062 contract
+ * (.design/investigations/2026-07-25-cli-062-ime-cursor-design.md): the hardware cursor must be
+ * shown ON the input row at the composition column, track CJK width growth, disappear when the
+ * input is unfocused (I4), propagate `undefined` on unmount (I4), and the production code must
+ * write NOTHING to the real process streams (the PoC row-accounting lesson, I3).
+ *
+ * The host override opts the capability gate in explicitly — the vitest process has no TTY,
+ * so the default gate would (correctly) refuse.
+ */
+
+import { EventEmitter } from 'node:events';
+
+import chalk from 'chalk';
+import { Box, Text, render } from 'ink';
+import React, { useState } from 'react';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { interpretVtStream } from './helpers/vt-cursor-interpreter.js';
+import CjkTextInput from '../CjkTextInput.js';
+import { TerminalCapabilitiesProvider } from '../terminal-capabilities-context.js';
+import korean from './__fixtures__/korean-text.json';
+
+const COLS = 60;
+const ROWS = 24;
+const PROMPT = '> ';
+
+class FakeTtyStdout extends EventEmitter {
+  readonly isTTY = true;
+  readonly columns = COLS;
+  readonly rows = ROWS;
+  private chunks: string[] = [];
+  write = (chunk: string, callback?: () => void): boolean => {
+    this.chunks.push(String(chunk));
+    callback?.();
+    return true;
+  };
+  stream(): string {
+    return this.chunks.join('');
+  }
+}
+
+class FakeStdin extends EventEmitter {
+  readonly isTTY = true;
+  private pending: string | null = null;
+  setEncoding(): void {}
+  setRawMode(): void {}
+  resume(): void {}
+  pause(): void {}
+  ref(): void {}
+  unref(): void {}
+  read(): string | null {
+    const data = this.pending;
+    this.pending = null;
+    return data;
+  }
+  send(data: string): void {
+    this.pending = data;
+    this.emit('readable');
+    this.emit('data', data);
+  }
+}
+
+function Harness({
+  focus = true,
+  bannerLines = 1,
+}: {
+  focus?: boolean;
+  /** Rows rendered above the input — the layout the measured y must follow. */
+  bannerLines?: number;
+}): React.ReactElement {
+  const [value, setValue] = useState('');
+  return (
+    <Box flexDirection="column">
+      {Array.from({ length: bannerLines }, (_, index) => (
+        <Text key={index}>banner line {index}</Text>
+      ))}
+      <Box>
+        <Text>{PROMPT}</Text>
+        <CjkTextInput value={value} onChange={setValue} availableWidth={COLS - 2} focus={focus} />
+      </Box>
+      <Text>status line</Text>
+    </Box>
+  );
+}
+
+interface IScenario {
+  stdout: FakeTtyStdout;
+  stdin: FakeStdin;
+  unmount: () => void;
+}
+
+function renderScenario(focus?: boolean, bannerLines?: number): IScenario {
+  const stdout = new FakeTtyStdout();
+  const stdin = new FakeStdin();
+  const instance = render(
+    <TerminalCapabilitiesProvider overrides={{ imeCursorPositioning: true }}>
+      <Harness
+        {...(focus === undefined ? {} : { focus })}
+        {...(bannerLines === undefined ? {} : { bannerLines })}
+      />
+    </TerminalCapabilitiesProvider>,
+    {
+      // Cast: ink wants real process streams; the fakes implement the parts its render loop uses.
+      stdout: stdout as unknown as NodeJS.WriteStream,
+      stdin: stdin as unknown as NodeJS.ReadStream,
+      interactive: true,
+      exitOnCtrlC: false,
+      patchConsole: false,
+    },
+  );
+  return { stdout, stdin, unmount: instance.unmount };
+}
+
+/** Ink throttles frames (≤30fps) and React effects settle asynchronously — allow both to flush. */
+const settle = (): Promise<void> => new Promise((r) => setTimeout(r, 120));
+
+const INPUT_ROW = 1; // banner is row 0, input row is row 1 in the harness frame
+
+describe('CLI-062 — real cursor positioning (interactive ink render)', () => {
+  const ORIGINAL_CHALK_LEVEL = chalk.level;
+
+  beforeAll(() => {
+    chalk.level = 3; // make the drawn inverse cursor observable in bytes, so suppression is provable
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+    chalk.level = ORIGINAL_CHALK_LEVEL;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('shows the hardware cursor on the input row at the composition column and tracks CJK growth', async () => {
+    const stdoutSpy = vi.spyOn(process.stdout, 'write');
+    const stderrSpy = vi.spyOn(process.stderr, 'write');
+
+    const { stdout, stdin, unmount } = renderScenario();
+    await settle();
+
+    stdin.send(korean.greetingFirstTwoSyllables);
+    await settle();
+
+    const afterTwo = interpretVtStream(stdout.stream(), ROWS, COLS);
+    const showsAfterTwo = afterTwo.showEvents;
+    expect(showsAfterTwo.length).toBeGreaterThan(0);
+    // Every show lands on the input row (never the banner/top region — the crash geometry).
+    for (const event of showsAfterTwo) {
+      expect(event.row).toBe(INPUT_ROW);
+    }
+    // Composition column: '> ' (2 cols) + two syllables (2 wide chars = 4 cols).
+    expect(showsAfterTwo.at(-1)).toMatchObject({ row: INPUT_ROW, col: 6 });
+
+    stdin.send(korean.greetingThirdSyllable); // one more wide char → +2 columns
+    await settle();
+
+    const afterThree = interpretVtStream(stdout.stream(), ROWS, COLS);
+    expect(afterThree.showEvents.at(-1)).toMatchObject({ row: INPUT_ROW, col: 8 });
+
+    // Drawn-cursor suppression: before the first measurement the fallback legitimately draws the
+    // inverse block (I1: no guessed rows), but from the first positioned show onward the hardware
+    // cursor and the inverse block must never coexist.
+    const firstShowOffset = afterThree.showEvents[0]!.offset;
+    expect(stdout.stream().slice(firstShowOffset)).not.toContain('\u001b[7m');
+
+    // I3/PoC lesson: the production path writes NOTHING to the real process streams.
+    expect(stdoutSpy).not.toHaveBeenCalled();
+    expect(stderrSpy).not.toHaveBeenCalled();
+
+    unmount();
+  });
+
+  /**
+   * SIGSEGV regression guard, as a test rather than an argument.
+   *
+   * The Terminal.app Korean-IME crash was root-caused to `setCursorPosition({x, y: 0})` — a
+   * CONSTANT row that pointed the hardware cursor at the logo area. The mechanical statement that
+   * the bug class is gone is not "the literal is absent from the source" but "the emitted row is a
+   * function of the layout": move the input box down and the positioned row must move with it. A
+   * hardcoded `y: 0` — or any other constant — cannot satisfy both halves of this test.
+   */
+  it('SIGSEGV guard: the positioned row FOLLOWS the layout, so a constant y (the y:0 bug) is unrepresentable', async () => {
+    const rowsSeen: number[] = [];
+    for (const bannerLines of [1, 4]) {
+      const { stdout, stdin, unmount } = renderScenario(true, bannerLines);
+      await settle();
+      stdin.send(korean.greetingFirstTwoSyllables);
+      await settle();
+
+      const vt = interpretVtStream(stdout.stream(), ROWS, COLS);
+      expect(vt.showEvents.length, `banner=${bannerLines}`).toBeGreaterThan(0);
+      const row = vt.showEvents.at(-1)!.row;
+      // The input box starts immediately below the banner, so its measured row IS bannerLines.
+      expect(row, `banner=${bannerLines}`).toBe(bannerLines);
+      // ...and never the top of the frame while any banner occupies it (the crash geometry).
+      expect(row, `banner=${bannerLines}`).toBeGreaterThan(0);
+      rowsSeen.push(row);
+      unmount();
+      await settle();
+    }
+    // Two different layouts must yield two different rows — a constant cannot pass both.
+    expect(new Set(rowsSeen).size).toBe(2);
+  });
+
+  it('I4: unfocused input never positions the cursor (and keeps the fallback drawn-cursor path off)', async () => {
+    const { stdout, stdin, unmount } = renderScenario(false);
+    await settle();
+    stdin.send('x'); // ignored — not focused
+    await settle();
+
+    const vt = interpretVtStream(stdout.stream(), ROWS, COLS);
+    expect(vt.showEvents).toEqual([]);
+    unmount();
+  });
+
+  it('I4: blur withdraws the position (no shows after focus loss) and unmount leaves the cursor visible', async () => {
+    const stdout = new FakeTtyStdout();
+    const stdin = new FakeStdin();
+    const instance = render(
+      <TerminalCapabilitiesProvider overrides={{ imeCursorPositioning: true }}>
+        <Harness />
+      </TerminalCapabilitiesProvider>,
+      {
+        stdout: stdout as unknown as NodeJS.WriteStream,
+        stdin: stdin as unknown as NodeJS.ReadStream,
+        interactive: true,
+        exitOnCtrlC: false,
+        patchConsole: false,
+      },
+    );
+    await settle();
+    stdin.send(korean.greetingFirstSyllable);
+    await settle();
+    expect(interpretVtStream(stdout.stream(), ROWS, COLS).showEvents.length).toBeGreaterThan(0);
+
+    // Blur: the guard fails → setCursorPosition(undefined) → ink hides the hardware cursor and
+    // emits NO further positioned shows (the I4 fallback path).
+    instance.rerender(
+      <TerminalCapabilitiesProvider overrides={{ imeCursorPositioning: true }}>
+        <Harness focus={false} />
+      </TerminalCapabilitiesProvider>,
+    );
+    await settle();
+    const afterBlurMark = stdout.stream().length;
+    stdin.send('x'); // ignored — not focused; also must not resurrect the cursor
+    await settle();
+    const blurShows = interpretVtStream(stdout.stream(), ROWS, COLS).showEvents.filter(
+      (event) => event.offset >= afterBlurMark,
+    );
+    expect(blurShows).toEqual([]);
+
+    // Unmount: useCursor's cleanup propagates `undefined`; ink's teardown restores a bare,
+    // visible cursor (never a freshly positioned one).
+    instance.unmount();
+    await settle();
+    expect(interpretVtStream(stdout.stream(), ROWS, COLS).visible).toBe(true);
+  });
+});

package/src/__tests__/rename-broadcast-persistence.test.tsx

@@ -0,0 +1,140 @@
+/**
+ * CMD-004 Phase 2 Stage C — TC-10 (/rename persistence proof, TUI half).
+ *
+ * The spec gates deleting the TUI `renameSession` mutation on a red-first proof that `/rename`
+ * (1) persists HOST-side — the session executes the rename, no TUI handler involved — and
+ * (2) updates the TUI title via the broadcast `session_renamed` event.
+ *
+ * Runs the REAL TuiInteractionChannel over a real InteractiveSession (scripted provider) with a
+ * command module mirroring the real `/rename` contract (returns the `session-rename` host action
+ * on the split contract — Stage E deleted the legacy effect union).
+ *
+ * Red-first evidence: against pre-Stage-C code the broadcast half FAILED (the TUI only reacted to
+ * the legacy effect, which Stage B strips after host execution — so the title never updated).
+ */
+
+import { Text } from 'ink';
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createScriptedProvider } from '@robota-sdk/agent-core/testing';
+import { useSideEffects } from '../hooks/useSideEffects.js';
+import { TuiCliAdapterProvider } from '../tui-cli-adapter-context.js';
+import { TuiInteractionChannel } from '../TuiInteractionChannel.js';
+
+import type { IUseSideEffectsOptions } from '../hooks/side-effects-types.js';
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { ICommandModule } from '@robota-sdk/agent-framework';
+
+const READY_DEADLINE_MS = 10_000;
+const POLL_MS = 25;
+
+async function waitUntil(predicate: () => boolean, deadlineMs = READY_DEADLINE_MS): Promise<void> {
+  const deadline = Date.now() + deadlineMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+  }
+  expect(predicate()).toBe(true);
+}
+
+/** Mirrors the real session-command `/rename` contract: NO mutation in the command, host action only. */
+const renameModule: ICommandModule = {
+  name: 'stage-c-rename-proof',
+  systemCommands: [
+    {
+      name: 'rename',
+      description: 'Rename the session (test mirror of the real /rename contract)',
+      requiresPermission: false,
+      execute: (_context, args) => ({
+        success: true,
+        message: `Session renamed to "${args}".`,
+        hostActions: [{ type: 'session-rename', name: args }],
+      }),
+    },
+  ],
+};
+
+function fakeCliAdapter(): ITuiCliAdapter {
+  return {
+    getUserSettingsPath: () => '/tmp/fake-settings.json',
+    readSettings: () => ({}),
+    reloadPluginCommandSource: vi.fn(),
+    applyActiveModelChange: vi.fn().mockReturnValue({ applied: true }),
+    getGitBranch: vi.fn().mockReturnValue(undefined),
+    getProviderDisplayName: vi.fn((type: string) => type),
+  } as unknown as ITuiCliAdapter;
+}
+
+describe('TC-10 — /rename persists host-side and the TUI title follows the broadcast', () => {
+  let channel: TuiInteractionChannel | undefined;
+
+  afterEach(async () => {
+    await channel?.stop();
+    channel = undefined;
+  });
+
+  it('host executes the rename; the TUI updates its title from session_renamed only', async () => {
+    const scripted = createScriptedProvider([{ text: 'unused in this test' }]);
+    channel = new TuiInteractionChannel({
+      cwd: process.cwd(),
+      provider: scripted.provider,
+      sessionName: 'Before Rename',
+      commandModules: [renameModule],
+    });
+    await channel.start();
+    const session = channel.getSession();
+    await waitUntil(() => {
+      try {
+        session.getContextState();
+        return true;
+      } catch {
+        return false; // allow-fallback: session init is asynchronous; poll until it is ready
+      }
+    });
+
+    const setSessionName = vi.fn();
+    const options = {
+      cwd: process.cwd(),
+      uiEventPort: session,
+      commandEffectQueue: {
+        enqueueEffects: () => undefined,
+        drain: () => undefined,
+        clear: () => undefined,
+      },
+      addEntry: vi.fn(),
+      baseHandleSubmit: (input: string) => channel!.handleInput(input),
+      setSessionName,
+      setStatusLineSettings: vi.fn(),
+      refreshStatusLineSettings: vi.fn(),
+      refreshAppearanceSettings: vi.fn(),
+      showSessionPickerOnStart: false,
+    } as unknown as IUseSideEffectsOptions;
+
+    const submitRef: { current: ((input: string) => Promise<void>) | null } = { current: null };
+    function Probe(): React.ReactElement {
+      const state = useSideEffects(options);
+      submitRef.current = state.handleSubmit;
+      return <Text>probe</Text>;
+    }
+    const instance = render(
+      <TuiCliAdapterProvider value={fakeCliAdapter()}>
+        <Probe />
+      </TuiCliAdapterProvider>,
+    );
+    await waitUntil(() => submitRef.current !== null);
+
+    await submitRef.current!('/rename Stage C Proof');
+
+    // (1) HOST persistence: the session itself performed the rename — no TUI mutation handler.
+    expect(session.getName()).toBe('Stage C Proof');
+
+    // (2) Title update via the broadcast `session_renamed` (the dual-carry legacy effect is
+    // stripped by the host applier, so this is the ONLY path that can update the title).
+    await waitUntil(() => setSessionName.mock.calls.length > 0, 3000);
+    expect(setSessionName).toHaveBeenCalledWith('Stage C Proof');
+
+    instance.unmount();
+  });
+});

package/src/__tests__/render-channel-options.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect } from 'vitest';
+import type { IAIProvider } from '@robota-sdk/agent-core';
+import { createNodeHostSettingsSource } from '@robota-sdk/agent-framework';
+import { createNodeHostContributionSource } from '@robota-sdk/agent-framework';
+import type { IPromptHistoryOptions } from '@robota-sdk/agent-framework';
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import { toChannelOptions } from '../render.js';
+import { buildTuiSessionOptions } from '../tui-session-options.js';
+import type { IRenderOptions } from '../render.js';
+
+describe('toChannelOptions', () => {
+  it('keeps host model identifiers through render, channel, and session', () => {
+    const channel = toChannelOptions({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      promptFileReferenceTag: 'acme_files',
+      modelCommandToolPrefix: 'acme_command_',
+      observerFailureWarningCode: 'ACME_BACKGROUND_OBSERVER_FAILURE',
+      subagentHookEnvironmentNames: { agentId: 'ACME_AGENT_ID', agentType: 'ACME_AGENT_TYPE' },
+      commandHookShell: '/bin/bash',
+    });
+    const session = buildTuiSessionOptions(channel);
+    expect(session.promptFileReferenceTag).toBe('acme_files');
+    expect(session.modelCommandToolPrefix).toBe('acme_command_');
+    expect(session.observerFailureWarningCode).toBe('ACME_BACKGROUND_OBSERVER_FAILURE');
+    expect(session.subagentHookEnvironmentNames).toEqual({
+      agentId: 'ACME_AGENT_ID',
+      agentType: 'ACME_AGENT_TYPE',
+    });
+    expect('commandHookShell' in session && session.commandHookShell).toBe('/bin/bash');
+  });
+
+  it('keeps safe mode (no instructions, plugins or settings hooks) through render, channel, and session', () => {
+    const channel = toChannelOptions({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      bare: true,
+      skipConfiguredHooks: true,
+    });
+    const session = buildTuiSessionOptions(channel);
+    expect('bare' in session && session.bare).toBe(true);
+    expect('skipConfiguredHooks' in session && session.skipConfiguredHooks).toBe(true);
+  });
+
+  it('preserves host permission baselines through render, channel, and session', () => {
+    const baselinePermissionAllow = ['Read(custom/**)'];
+    const channel = toChannelOptions({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      baselinePermissionAllow,
+    });
+    const session = buildTuiSessionOptions(channel);
+    if (!('baselinePermissionAllow' in session)) {
+      throw new Error('TUI standard session options must preserve the host permission baseline.');
+    }
+    expect(session.baselinePermissionAllow).toBe(baselinePermissionAllow);
+  });
+  it('keeps the host task-context selection through render, channel, and session', () => {
+    const taskContext = { enabled: true, dir: 'custom/tasks' };
+    const channel = toChannelOptions({
+      cwd: '/test-project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      taskContext,
+    });
+    expect(channel.taskContext).toBe(taskContext);
+    const session = buildTuiSessionOptions(channel);
+    if (!('taskContext' in session)) {
+      throw new Error(
+        'TUI standard session options must preserve the host task-context selection.',
+      );
+    }
+    expect(session.taskContext).toBe(taskContext);
+  });
+
+  it('keeps the host contribution sources and skill roots through render, channel, and session', () => {
+    const sources = [createNodeHostContributionSource('/test-project')];
+    const skillRoots = [{ root: 'custom/skills', kind: 'skills' as const }];
+    const channel = toChannelOptions({
+      cwd: '/test-project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      contributionSources: sources,
+      skillRoots,
+    });
+    const session = buildTuiSessionOptions(channel);
+    if (!('contributionSources' in session) || !('skillRoots' in session)) {
+      throw new Error('TUI standard session options must preserve host skill discovery settings.');
+    }
+    expect(session.contributionSources).toBe(sources);
+    expect(session.skillRoots).toBe(skillRoots);
+  });
+
+  it('keeps the host user settings sources through render, channel, and session', () => {
+    const sources = [createNodeHostSettingsSource('user', '/test-home/settings.json')];
+    const channel = toChannelOptions({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      userSettingsSources: sources,
+    });
+    expect(buildTuiSessionOptions(channel).userSettingsSources).toBe(sources);
+  });
+
+  it('forwards the loop kill switch through the channel to the session', () => {
+    const options = toChannelOptions({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      disableSessionLoops: true,
+    });
+    expect(options.disableSessionLoops).toBe(true);
+    expect(buildTuiSessionOptions(options).disableSessionLoops).toBe(true);
+  });
+
+  it('TC-02: threads allowedTools and deniedTools into the channel options', () => {
+    const renderOptions: IRenderOptions = {
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      allowedTools: ['Read'],
+      deniedTools: ['Bash'],
+    };
+    const channelOptions = toChannelOptions(renderOptions, 'session-1');
+    expect(channelOptions.allowedTools).toEqual(['Read']);
+    expect(channelOptions.deniedTools).toEqual(['Bash']);
+    expect(channelOptions.resumeSessionId).toBe('session-1');
+    expect(channelOptions.cwd).toBe('/tmp/project');
+  });
+
+  it('leaves tool filters undefined when not provided', () => {
+    const channelOptions = toChannelOptions({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+    });
+    expect(channelOptions.allowedTools).toBeUndefined();
+    expect(channelOptions.deniedTools).toBeUndefined();
+  });
+
+  it('CLI-076: threads the display modelId into the channel model override', () => {
+    const channelOptions = toChannelOptions({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      modelId: 'claude-haiku-4-5-20251001',
+    });
+    // The status-line model id IS the session's model override (header == the model actually called).
+    expect(channelOptions.model).toBe('claude-haiku-4-5-20251001');
+  });
+
+  it('CLI-076: leaves model undefined when no modelId is resolved', () => {
+    const channelOptions = toChannelOptions({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+    });
+    expect(channelOptions.model).toBeUndefined();
+  });
+
+  it('carries the host external-event verifier factory to the session options', () => {
+    const factory = () => ({ verify: async () => ({ admitted: true as const }) });
+    const channelOptions = toChannelOptions({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      externalEventVerifierFactory: factory,
+    });
+    expect(channelOptions.externalEventVerifierFactory).toBe(factory);
+    expect(buildTuiSessionOptions(channelOptions).externalEventVerifierFactory).toBe(factory);
+  });
+
+  it('SCREEN-1993: projects the prompt-history writer to the channel and on to the session options', () => {
+    const promptHistory = { writer: { append: () => undefined }, project: '/p' };
+    const channelOptions = toChannelOptions({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+      cliAdapter: {} as ITuiCliAdapter,
+      promptHistory,
+    });
+    expect(channelOptions.promptHistory).toBe(promptHistory);
+    // The session-options union hides standard-only fields; read the projected field by name.
+    const session = (
+      options: ReturnType<typeof toChannelOptions>,
+    ): { promptHistory?: IPromptHistoryOptions } =>
+      buildTuiSessionOptions(options) as { promptHistory?: IPromptHistoryOptions };
+    expect(session(channelOptions).promptHistory).toBe(promptHistory);
+    expect(
+      session(
+        toChannelOptions({
+          cwd: '/tmp/project',
+          provider: {} as IAIProvider,
+          cliAdapter: {} as ITuiCliAdapter,
+        }),
+      ).promptHistory,
+    ).toBeUndefined();
+  });
+});

package/src/__tests__/render-lifecycle.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { waitForRenderAndStop } from '../render.js';
+
+describe('renderApp lifecycle ownership', () => {
+  it('awaits active channel teardown after Ink exits', async () => {
+    let release: (() => void) | undefined;
+    const stop = vi.fn(() => new Promise<void>((resolve) => (release = resolve)));
+    let settled = false;
+
+    const outcome = waitForRenderAndStop(
+      async () => {},
+      () => ({ stop }),
+    ).then(() => {
+      settled = true;
+    });
+    await Promise.resolve();
+
+    expect(stop).toHaveBeenCalledTimes(1);
+    expect(settled).toBe(false);
+    release?.();
+    await outcome;
+    expect(settled).toBe(true);
+  });
+
+  it('propagates channel teardown failure to the renderApp caller', async () => {
+    const stopError = new Error('transport stop failed');
+
+    await expect(
+      waitForRenderAndStop(
+        async () => {},
+        () => ({ stop: vi.fn().mockRejectedValue(stopError) }),
+      ),
+    ).rejects.toBe(stopError);
+  });
+});