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

package/src/__tests__/tui-app-channel-port.test.ts

@@ -0,0 +1,31 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import type {
+  ITuiAppChannelPort,
+  ITuiCommandQueryPort,
+  ITuiSessionUiEventPort,
+} from '../tui-app-channel-port.js';
+
+describe('TUI React capability boundary', () => {
+  it('excludes concrete channel and state-manager escape hatches', () => {
+    expectTypeOf<ITuiAppChannelPort>().not.toHaveProperty('getSession');
+    expectTypeOf<ITuiAppChannelPort>().not.toHaveProperty('getRegistry');
+    expectTypeOf<ITuiAppChannelPort>().not.toHaveProperty('stateManager');
+  });
+
+  it('limits autocomplete to command queries', () => {
+    expectTypeOf<ITuiCommandQueryPort>().toHaveProperty('getCommands');
+    expectTypeOf<ITuiCommandQueryPort>().toHaveProperty('getSubcommands');
+    expectTypeOf<ITuiCommandQueryPort>().not.toHaveProperty('addModule');
+    expectTypeOf<ITuiCommandQueryPort>().not.toHaveProperty('execute');
+  });
+
+  it('limits React event effects to the two UI event names', () => {
+    expectTypeOf<Parameters<ITuiSessionUiEventPort['on']>[0]>().toEqualTypeOf<
+      'ui_intent' | 'session_renamed'
+    >();
+    expectTypeOf<Parameters<ITuiSessionUiEventPort['off']>[0]>().toEqualTypeOf<
+      'ui_intent' | 'session_renamed'
+    >();
+  });
+});

package/src/__tests__/tui-channel-init-failure.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { IAIProvider } from '@robota-sdk/agent-core';
+
+vi.mock('@robota-sdk/agent-framework', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('@robota-sdk/agent-framework')>();
+
+  class FakeInteractiveSession {
+    on(): void {}
+    off(): void {}
+    getFullHistory(): unknown[] {
+      return [];
+    }
+    getContextState(): never {
+      throw new Error('ENOENT: session store unreadable');
+    }
+    getName(): string | undefined {
+      return undefined;
+    }
+    getSession(): { getSessionId: () => string } {
+      return { getSessionId: () => 'test-session' };
+    }
+    async shutdown(): Promise<void> {}
+  }
+
+  // RUNTIME-001: construction flows through buildRuntimeSession (wraps InteractiveSession in agent-framework).
+  return {
+    ...mod,
+    InteractiveSession: FakeInteractiveSession,
+    buildRuntimeSession: () => new FakeInteractiveSession(),
+  };
+});
+
+import { TuiInteractionChannel } from '../TuiInteractionChannel.js';
+
+describe('TuiInteractionChannel init failure surfacing', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('TC-05: a real init error records a session-init-error entry and sets error state', async () => {
+    const channel = new TuiInteractionChannel({
+      cwd: '/tmp/project',
+      provider: {} as IAIProvider,
+    });
+    await channel.start();
+
+    vi.advanceTimersByTime(400);
+
+    const entries = channel.stateManager.history;
+    const initError = entries.find((e) => e.type === 'session-init-error');
+    expect(initError).toBeDefined();
+    const message = (initError?.data as { message?: string } | undefined)?.message ?? '';
+    expect(message).toContain('Session initialization failed');
+    expect(message).toContain('ENOENT');
+
+    await channel.stop();
+  });
+});

package/src/__tests__/tui-channel-lifecycle-coordinator.test.ts

@@ -0,0 +1,258 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { TuiChannelLifecycleCoordinator } from '../tui-channel-lifecycle-coordinator.js';
+
+function operations() {
+  return {
+    start: vi.fn(async () => {}),
+    stop: vi.fn(async () => {}),
+    beginShutdown: vi.fn(),
+    shutdownSession: vi.fn(async () => {}),
+  };
+}
+
+describe('TuiChannelLifecycleCoordinator', () => {
+  it('starts and stops idempotently, including one discard shutdown', async () => {
+    const ops = operations();
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+    await lifecycle.start();
+    expect(lifecycle.isActiveForPeerStatus).toBe(true);
+    await lifecycle.start();
+    await lifecycle.stop();
+    expect(lifecycle.isActiveForPeerStatus).toBe(false);
+    await lifecycle.stop();
+
+    expect(ops.start).toHaveBeenCalledTimes(1);
+    expect(ops.stop).toHaveBeenCalledTimes(1);
+    expect(ops.shutdownSession).toHaveBeenCalledTimes(1);
+    expect(ops.shutdownSession).toHaveBeenCalledWith({
+      reason: 'other',
+      message: 'channel stopped',
+    });
+  });
+
+  it('does not repeat a graceful shutdown when stop follows it', async () => {
+    const ops = operations();
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+    await lifecycle.shutdown({ reason: 'prompt_input_exit' });
+    await lifecycle.shutdown({ reason: 'other' });
+    await lifecycle.stop();
+
+    expect(lifecycle.isShuttingDown).toBe(true);
+    expect(ops.beginShutdown).toHaveBeenCalledTimes(1);
+    expect(ops.shutdownSession).toHaveBeenCalledTimes(1);
+  });
+
+  it('allows a failed start to be retried', async () => {
+    const ops = operations();
+    ops.start.mockRejectedValueOnce(new Error('transport start failed'));
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+
+    await expect(lifecycle.start()).rejects.toThrow('transport start failed');
+    expect(lifecycle.isActiveForPeerStatus).toBe(false);
+    await lifecycle.start();
+    await lifecycle.start();
+
+    expect(ops.start).toHaveBeenCalledTimes(2);
+  });
+
+  it('invalidates peer activity before a failing stop settles', async () => {
+    const ops = operations();
+    ops.stop.mockRejectedValueOnce(new Error('teardown failed'));
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+    await lifecycle.start();
+    expect(lifecycle.isActiveForPeerStatus).toBe(true);
+    const stopping = lifecycle.stop();
+    expect(lifecycle.isActiveForPeerStatus).toBe(false);
+    await expect(stopping).rejects.toThrow('teardown failed');
+    expect(lifecycle.isActiveForPeerStatus).toBe(false);
+  });
+
+  it('shares one in-flight start across concurrent callers', async () => {
+    const ops = operations();
+    let release: (() => void) | undefined;
+    ops.start.mockImplementationOnce(() => new Promise<void>((resolve) => (release = resolve)));
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+
+    const first = lifecycle.start();
+    const second = lifecycle.start();
+    expect(ops.start).toHaveBeenCalledTimes(1);
+    release?.();
+    await Promise.all([first, second]);
+  });
+
+  it('waits for an in-flight start before tearing the channel down', async () => {
+    const ops = operations();
+    let release: (() => void) | undefined;
+    ops.start.mockImplementationOnce(() => new Promise<void>((resolve) => (release = resolve)));
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+
+    const start = lifecycle.start();
+    const stop = lifecycle.stop();
+    await Promise.resolve();
+    expect(ops.stop).not.toHaveBeenCalled();
+
+    release?.();
+    await Promise.all([start, stop]);
+    expect(ops.start.mock.invocationCallOrder[0]).toBeLessThan(
+      ops.stop.mock.invocationCallOrder[0]!,
+    );
+  });
+
+  it('surfaces an in-flight start failure after teardown completes', async () => {
+    const ops = operations();
+    let rejectStart: ((error: Error) => void) | undefined;
+    ops.start.mockImplementationOnce(
+      () => new Promise<void>((_resolve, reject) => (rejectStart = reject)),
+    );
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+
+    const start = lifecycle.start();
+    const stop = lifecycle.stop();
+    rejectStart?.(new Error('transport start failed'));
+
+    await expect(start).rejects.toThrow('transport start failed');
+    await expect(stop).rejects.toThrow('transport start failed');
+    expect(ops.stop).toHaveBeenCalledTimes(1);
+    await lifecycle.stop();
+    expect(ops.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it('preserves concurrent start and teardown errors and keeps teardown retryable', async () => {
+    const ops = operations();
+    let rejectStart: ((error: Error) => void) | undefined;
+    ops.start.mockImplementationOnce(
+      () => new Promise<void>((_resolve, reject) => (rejectStart = reject)),
+    );
+    ops.stop.mockRejectedValueOnce(new Error('transport stop failed'));
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+
+    const start = lifecycle.start();
+    const stop = lifecycle.stop();
+    rejectStart?.(new Error('transport start failed'));
+    await expect(start).rejects.toThrow('transport start failed');
+    const failure = await stop.catch((error: Error) => error);
+
+    expect(failure).toBeInstanceOf(AggregateError);
+    expect((failure as AggregateError).errors).toEqual([
+      expect.objectContaining({ message: 'transport start failed' }),
+      expect.objectContaining({ message: 'transport stop failed' }),
+    ]);
+
+    await lifecycle.stop();
+    expect(ops.stop).toHaveBeenCalledTimes(2);
+  });
+
+  it('shares session shutdown while failed transport cleanup remains retryable', async () => {
+    const ops = operations();
+    ops.stop.mockRejectedValueOnce(new Error('transport stop failed'));
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+
+    await expect(lifecycle.stop()).rejects.toThrow('transport stop failed');
+    expect(ops.shutdownSession).toHaveBeenCalledTimes(1);
+
+    await lifecycle.stop();
+    expect(ops.stop).toHaveBeenCalledTimes(2);
+    expect(ops.shutdownSession).toHaveBeenCalledTimes(1);
+  });
+
+  it('refuses to restart after a failed teardown', async () => {
+    const ops = operations();
+    ops.stop.mockRejectedValueOnce(new Error('transport stop failed'));
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+
+    await lifecycle.start();
+    await expect(lifecycle.stop()).rejects.toThrow('transport stop failed');
+    await expect(lifecycle.start()).rejects.toThrow(
+      'Cannot start a channel after teardown has begun.',
+    );
+
+    expect(ops.start).toHaveBeenCalledTimes(1);
+  });
+
+  it('refuses to start after graceful shutdown has begun', async () => {
+    const ops = operations();
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+
+    await lifecycle.shutdown();
+    await expect(lifecycle.start()).rejects.toThrow(
+      'Cannot start a channel after teardown has begun.',
+    );
+
+    expect(ops.start).not.toHaveBeenCalled();
+  });
+
+  it('serializes graceful shutdown after start and shares its completion', async () => {
+    const ops = operations();
+    let releaseStart: (() => void) | undefined;
+    let releaseShutdown: (() => void) | undefined;
+    ops.start.mockImplementationOnce(
+      () => new Promise<void>((resolve) => (releaseStart = resolve)),
+    );
+    ops.shutdownSession.mockImplementationOnce(
+      () => new Promise<void>((resolve) => (releaseShutdown = resolve)),
+    );
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+
+    const start = lifecycle.start();
+    const firstShutdown = lifecycle.shutdown();
+    const secondShutdown = lifecycle.shutdown();
+    await Promise.resolve();
+    expect(ops.shutdownSession).not.toHaveBeenCalled();
+
+    releaseStart?.();
+    await start;
+    await Promise.resolve();
+    expect(ops.shutdownSession).toHaveBeenCalledTimes(1);
+
+    let secondSettled = false;
+    void secondShutdown.then(() => (secondSettled = true));
+    await Promise.resolve();
+    expect(secondSettled).toBe(false);
+
+    releaseShutdown?.();
+    await Promise.all([firstShutdown, secondShutdown]);
+  });
+
+  it('does not finish stop before an in-flight graceful shutdown', async () => {
+    const ops = operations();
+    let releaseShutdown: (() => void) | undefined;
+    ops.shutdownSession.mockImplementationOnce(
+      () => new Promise<void>((resolve) => (releaseShutdown = resolve)),
+    );
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+    await lifecycle.start();
+
+    const shutdown = lifecycle.shutdown();
+    let stopSettled = false;
+    const stop = lifecycle.stop().then(() => (stopSettled = true));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(stopSettled).toBe(false);
+
+    releaseShutdown?.();
+    await Promise.all([shutdown, stop]);
+  });
+
+  it('does not finish graceful shutdown before an in-flight stop', async () => {
+    const ops = operations();
+    let releaseStop: (() => void) | undefined;
+    ops.stop.mockImplementationOnce(() => new Promise<void>((resolve) => (releaseStop = resolve)));
+    const lifecycle = new TuiChannelLifecycleCoordinator(ops, 100);
+    await lifecycle.start();
+
+    const stop = lifecycle.stop();
+    await Promise.resolve();
+    const shutdown = lifecycle.shutdown();
+    let shutdownSettled = false;
+    void shutdown.then(() => (shutdownSettled = true));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(shutdownSettled).toBe(false);
+    expect(ops.shutdownSession).not.toHaveBeenCalled();
+
+    releaseStop?.();
+    await Promise.all([stop, shutdown]);
+    expect(ops.shutdownSession).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/tui-interaction-queues.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { TuiPermissionQueue, TuiUserActionQueue } from '../tui-interaction-queues.js';
+
+import type { IActionRequest } from '@robota-sdk/agent-core';
+
+const FIRST: IActionRequest = {
+  id: 'first',
+  title: 'First?',
+  options: [{ value: 'yes', label: 'Yes' }],
+  maxSelect: 1,
+};
+const SECOND: IActionRequest = {
+  id: 'second',
+  title: 'Second?',
+  options: [{ value: 'no', label: 'No' }],
+  maxSelect: 1,
+};
+
+afterEach(() => vi.useRealTimers());
+
+describe('TuiUserActionQueue', () => {
+  it('resolves FIFO and promotes the next action', async () => {
+    const queue = new TuiUserActionQueue(vi.fn());
+    const first = queue.enqueue(FIRST, 'prompt-1');
+    const second = queue.enqueue(SECOND, 'prompt-2');
+
+    const firstPrompt = queue.current;
+    expect(firstPrompt).toEqual(FIRST);
+    queue.resolveCurrent(firstPrompt!, { type: 'answer', values: ['yes'] });
+    expect(await first).toEqual({ type: 'answer', values: ['yes'] });
+    const secondPrompt = queue.current;
+    expect(secondPrompt).toEqual(SECOND);
+    queue.resolveCurrent(secondPrompt!, { type: 'cancelled' });
+    expect(await second).toEqual({ type: 'cancelled' });
+    expect(queue.current).toBeNull();
+  });
+
+  it('cancels every active and queued action during a drain', async () => {
+    const queue = new TuiUserActionQueue(vi.fn());
+    const first = queue.enqueue(FIRST);
+    const second = queue.enqueue(SECOND);
+    queue.cancelAll();
+    await expect(first).resolves.toEqual({ type: 'cancelled' });
+    await expect(second).resolves.toEqual({ type: 'cancelled' });
+    expect(queue.current).toBeNull();
+  });
+
+  it('ignores a stale answer after remote dismissal promotes the next action', async () => {
+    const queue = new TuiUserActionQueue(vi.fn());
+    const first = queue.enqueue(FIRST, 'prompt-1');
+    const second = queue.enqueue(SECOND, 'prompt-2');
+    const stalePrompt = queue.current;
+
+    expect(queue.dismissById('prompt-1')).toBe(true);
+    await expect(first).resolves.toEqual({ type: 'cancelled' });
+    const activePrompt = queue.current;
+    expect(activePrompt).toEqual(SECOND);
+
+    queue.resolveCurrent(stalePrompt!, { type: 'answer', values: ['yes'] });
+    expect(queue.current).toBe(activePrompt);
+    queue.resolveCurrent(activePrompt!, { type: 'answer', values: ['no'] });
+    await expect(second).resolves.toEqual({ type: 'answer', values: ['no'] });
+  });
+
+  it('binds stale-answer protection to an entry when the request object is reused', async () => {
+    const queue = new TuiUserActionQueue(vi.fn());
+    const first = queue.enqueue(FIRST, 'prompt-1');
+    const second = queue.enqueue(FIRST, 'prompt-2');
+    const stalePrompt = queue.current;
+
+    expect(queue.dismissById('prompt-1')).toBe(true);
+    await expect(first).resolves.toEqual({ type: 'cancelled' });
+    const activePrompt = queue.current;
+    expect(activePrompt).not.toBeNull();
+
+    queue.resolveCurrent(stalePrompt!, { type: 'answer', values: ['stale'] });
+    expect(queue.current).toBe(activePrompt);
+    queue.resolveCurrent(activePrompt!, { type: 'answer', values: ['current'] });
+    await expect(second).resolves.toEqual({ type: 'answer', values: ['current'] });
+  });
+});
+
+describe('TuiPermissionQueue', () => {
+  it('resolves FIFO and promotes the next permission on the scheduled turn', async () => {
+    vi.useFakeTimers();
+    const queue = new TuiPermissionQueue(vi.fn());
+    const first = queue.enqueue('Read', { path: 'a' }, 'permission-1');
+    const second = queue.enqueue('Write', { path: 'b' }, 'permission-2');
+
+    expect(queue.current?.toolName).toBe('Read');
+    queue.current?.resolve(true);
+    await expect(first).resolves.toBe(true);
+    await vi.runAllTimersAsync();
+    expect(queue.current?.toolName).toBe('Write');
+    queue.current?.resolve('allow-session');
+    await expect(second).resolves.toBe('allow-session');
+  });
+
+  it('denies every active and queued permission during a drain', async () => {
+    const queue = new TuiPermissionQueue(vi.fn());
+    const first = queue.enqueue('Read', { path: 'a' });
+    const second = queue.enqueue('Write', { path: 'b' });
+    queue.cancelAll();
+    await expect(first).resolves.toBe(false);
+    await expect(second).resolves.toBe(false);
+    expect(queue.current).toBeNull();
+  });
+
+  it('preserves the active permission when a queued request is dismissed', async () => {
+    const queue = new TuiPermissionQueue(vi.fn());
+    const first = queue.enqueue('Read', { path: 'a' }, 'permission-1');
+    const second = queue.enqueue('Write', { path: 'b' }, 'permission-2');
+    const active = queue.current;
+
+    expect(queue.dismissById('permission-2')).toBe(true);
+    expect(queue.current).toBe(active);
+    await expect(second).resolves.toBe(false);
+
+    active?.resolve(true);
+    await expect(first).resolves.toBe(true);
+  });
+
+  it('ignores a stale permission callback after remote dismissal promotes the next request', async () => {
+    const queue = new TuiPermissionQueue(vi.fn());
+    const first = queue.enqueue('Read', { path: 'a' }, 'permission-1');
+    const second = queue.enqueue('Write', { path: 'b' }, 'permission-2');
+    const stale = queue.current;
+
+    expect(queue.dismissById('permission-1')).toBe(true);
+    await expect(first).resolves.toBe(false);
+    expect(queue.current?.toolName).toBe('Write');
+
+    stale?.resolve(true);
+    expect(queue.current?.toolName).toBe('Write');
+    queue.current?.resolve(true);
+    await expect(second).resolves.toBe(true);
+  });
+});

package/src/__tests__/tui-preset-capabilities.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+
+import { toChannelOptions } from '../render.js';
+import { buildTuiSessionOptions } from '../tui-session-options.js';
+
+import type { IRenderOptions } from '../render.js';
+
+function renderOptions(extra: Partial<IRenderOptions> = {}): IRenderOptions {
+  return { cwd: '/work', provider: {} as never, ...extra } as IRenderOptions;
+}
+
+describe('TUI preset capabilities reach the session', () => {
+  it('preserves generation, prompt-seed, and response-format fields', () => {
+    const responseFormat = { type: 'json_object' as const };
+    const render = renderOptions({
+      temperature: 0.37,
+      maxOutputTokens: 481,
+      presetSystemPrompt: 'Preset seed',
+      appendSystemPrompt: 'CLI addition',
+      responseFormat,
+    });
+
+    const session = buildTuiSessionOptions(toChannelOptions(render));
+
+    expect(session).toMatchObject({
+      temperature: 0.37,
+      maxOutputTokens: 481,
+      presetSystemPrompt: 'Preset seed',
+      appendSystemPrompt: 'CLI addition',
+      responseFormat,
+    });
+  });
+});

package/src/__tests__/tui-state-manager.error-stall.test.ts

@@ -0,0 +1,169 @@
+/**
+ * ERR-001 G2/G3 — TUI error-state reducer: last-error message lifecycle and the
+ * dead-air stall hint timer.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { TuiStateManager } from '../tui-state-manager';
+
+describe('TuiStateManager — error state (ERR-001 G2)', () => {
+  it('records the error message on onError and clears it when the next turn starts', () => {
+    const manager = new TuiStateManager();
+
+    manager.onError(new Error('connection reset'));
+    expect(manager.lastErrorMessage).toBe('connection reset');
+    expect(manager.isThinking).toBe(false);
+
+    manager.onThinking(true);
+    expect(manager.lastErrorMessage).toBeNull();
+  });
+
+  it('falls back to a generic message when no Error object arrives', () => {
+    const manager = new TuiStateManager();
+    manager.onError();
+    expect(manager.lastErrorMessage).toBe('Unknown error');
+  });
+});
+
+describe('TuiStateManager — dead-air stall hint (ERR-001 G3)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('flags isStalled after 15s of thinking with no provider activity', () => {
+    const manager = new TuiStateManager();
+    manager.onThinking(true);
+    expect(manager.isStalled).toBe(false);
+
+    vi.advanceTimersByTime(15_000);
+    expect(manager.isStalled).toBe(true);
+  });
+
+  it('provider activity (text delta) resets the timer — no stall flag', () => {
+    const manager = new TuiStateManager();
+    manager.onThinking(true);
+
+    vi.advanceTimersByTime(10_000);
+    manager.onTextDelta('still alive');
+    vi.advanceTimersByTime(10_000);
+    expect(manager.isStalled).toBe(false);
+
+    vi.advanceTimersByTime(5_000);
+    expect(manager.isStalled).toBe(true);
+  });
+
+  it('clears the stall flag and timer when the turn ends (thinking false / error)', () => {
+    const manager = new TuiStateManager();
+    manager.onThinking(true);
+    vi.advanceTimersByTime(15_000);
+    expect(manager.isStalled).toBe(true);
+
+    manager.onThinking(false);
+    expect(manager.isStalled).toBe(false);
+
+    manager.onThinking(true);
+    manager.onError(new Error('boom'));
+    vi.advanceTimersByTime(20_000);
+    expect(manager.isStalled).toBe(false);
+  });
+});
+
+describe('TuiStateManager — stall hint suppressed during tool execution (RUNTIME-39)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  const runningTool = { toolName: 'bash', firstArg: 'sleep 60', isRunning: true };
+  const endedTool = {
+    toolName: 'bash',
+    firstArg: 'sleep 60',
+    isRunning: false,
+    result: 'success' as const,
+  };
+
+  it('a running tool suppresses the dead-air hint — no stall while a tool executes', () => {
+    const manager = new TuiStateManager();
+    manager.onThinking(true); // arms the stall timer
+    vi.advanceTimersByTime(10_000);
+    manager.onToolStart(runningTool); // a tool is now legitimately busy → suppress
+    vi.advanceTimersByTime(60_000); // long tool, no provider deltas
+    expect(manager.isStalled).toBe(false);
+  });
+
+  it('re-arms the hint when the last running tool ends and the turn is still thinking', () => {
+    const manager = new TuiStateManager();
+    manager.onThinking(true);
+    manager.onToolStart(runningTool);
+    vi.advanceTimersByTime(60_000);
+    expect(manager.isStalled).toBe(false);
+
+    manager.onToolEnd(endedTool); // no more running tools → re-arm dead-air watch
+    vi.advanceTimersByTime(15_000);
+    expect(manager.isStalled).toBe(true);
+  });
+
+  it('does not re-arm after tool end once the turn is no longer thinking', () => {
+    const manager = new TuiStateManager();
+    manager.onThinking(true);
+    manager.onToolStart(runningTool);
+    manager.onThinking(false); // turn ended
+    manager.onToolEnd(endedTool);
+    vi.advanceTimersByTime(20_000);
+    expect(manager.isStalled).toBe(false);
+  });
+
+  it('keeps the hint suppressed while ANY tool is still running (concurrent tools)', () => {
+    const manager = new TuiStateManager();
+    manager.onThinking(true);
+    manager.onToolStart({ toolName: 'bash', firstArg: 'a', isRunning: true });
+    manager.onToolStart({ toolName: 'bash', firstArg: 'b', isRunning: true });
+    // End one of the two — one tool is still running, so the hint stays suppressed.
+    manager.onToolEnd({ toolName: 'bash', firstArg: 'b', isRunning: false, result: 'success' });
+    vi.advanceTimersByTime(60_000);
+    expect(manager.isStalled).toBe(false);
+  });
+});
+
+describe('TuiStateManager — dispose (RUNTIME-52)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('clears the stall timer and nulls onChange so nothing fires after dispose', () => {
+    const manager = new TuiStateManager();
+    const onChange = vi.fn();
+    manager.onChange = onChange;
+    manager.onThinking(true); // arms the stall timer
+    onChange.mockClear();
+
+    manager.dispose();
+    vi.advanceTimersByTime(30_000);
+
+    expect(manager.isStalled).toBe(false);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('flushes the pending streaming-debounce timer on dispose', () => {
+    const manager = new TuiStateManager();
+    const onChange = vi.fn();
+    manager.onChange = onChange;
+    manager.isThinking = true;
+    manager.onTextDelta('partial'); // schedules the debounced notify
+    onChange.mockClear();
+
+    manager.dispose();
+    vi.advanceTimersByTime(1_000);
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});