Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

80.7 KB
Raw Blame
import 'dart:async';
import 'dart:convert';
import 'dart:io';

import 'package:fake_async/fake_async.dart';
import 'package:harness/logging/app_log.dart';
import 'package:harness/terminal/terminal_session.dart';
import 'package:harness/terminal/terminal_binary.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter/foundation.dart';
import 'package:xterm/xterm.dart' show Terminal, TerminalTargetPlatform;

void main() {
  const streamId = '00112233-4455-6677-8899-aabbccddeeff';
  late List<({String type, Map<String, dynamic> payload})> sent;
  late List<TerminalBinaryFrame> binarySent;
  late TerminalSession session;
  DateTime? controlledNow;

  setUp(() {
    controlledNow = null;
    sent = [];
    binarySent = [];
    session = TerminalSession(
      machineId: 'machine-1',
      agentId: 'agent-1',
      agentName: 'backend-api',
      engineId: 'codex',
      now: () => controlledNow ?? DateTime.now(),
      send: (type, payload) async {
        sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
        return true;
      },
      sendBinary: (frame) async {
        binarySent.add(frame);
        return true;
      },
    );
  });

  tearDown(() => session.dispose());

  Future<void> ready() async {
    await session.open(initialCols: 100, initialRows: 30);
    final requestId = sent.single.payload['requestId'];
    await session.handleFrame('terminal_ready', {
      'requestId': requestId,
      'protocolVersion': 3,
      'streamId': streamId,
      'agentId': 'agent-1',
    });
  }

  TerminalBinaryFrame output(
    int seq,
    List<int> bytes, {
    bool compress = false,
    bool keyframe = false,
    int? cols,
    int? rows,
  }) {
    final body = compress ? ZLibEncoder(level: 1).convert(bytes) : bytes;
    return TerminalBinaryFrame(
      kind: keyframe ? TerminalBinaryKind.keyframe : TerminalBinaryKind.output,
      streamId: streamId,
      seq: seq,
      bytes: Uint8List.fromList(body),
      compressed: compress,
      cols: cols,
      rows: rows,
    );
  }

  test('a renderer fault resyncs instead of freezing the pane', () async {
    await ready();
    await session.handleBinary(
      output(0, 'hello'.codeUnits, keyframe: true, cols: 100, rows: 30),
    );
    expect(session.status, TerminalSessionStatus.controlling);
    final before = session.terminal;

    // The exception itself comes from deep inside the emulator on some specific
    // content — what matters here is that the ANSWER to one is recovery, not a
    // frozen tile demanding a manual reattach.
    await session.onRendererFailure();

    expect(session.status, TerminalSessionStatus.resyncing);
    expect(sent.any((frame) => frame.type == 'terminal_resync'), isTrue);
    expect(session.errorCode, 'TERMINAL_RENDERER_FAILED');
    // The damaged emulator is not written to again: the keyframe that answers
    // the resync builds a fresh one, and output frames are dropped until then.
    await session.handleBinary(output(1, 'more'.codeUnits));
    expect(identical(session.terminal, before), isTrue);
  });

  test('changing input context withholds typing until the new stream is ready and preserves its terminal', () async {
    await ready();
    await session.handleBinary(
      output(
        0,
        'retained screen'.codeUnits,
        keyframe: true,
        cols: 100,
        rows: 30,
      ),
    );
    final terminal = session.terminal;
    expect(session.acceptsInput, isTrue);
    session.stageInputContext('context_alpha_123456');
    expect(session.acceptsInput, isFalse);
    await session.setInputContext('context_alpha_123456');
    final opening = sent
        .lastWhere((frame) => frame.type == 'terminal_open')
        .payload;
    expect(opening['inputContext'], 'context_alpha_123456');
    expect(identical(session.terminal, terminal), isTrue);
    await session.handleFrame('terminal_ready', {
      'requestId': opening['requestId'],
      'protocolVersion': 3,
      'streamId': streamId,
      'agentId': 'agent-1',
    });
    await session.handleBinary(
      output(
        0,
        'retained screen'.codeUnits,
        keyframe: true,
        cols: 100,
        rows: 30,
      ),
    );
    expect(session.acceptsInput, isTrue);
    final latestTerminal = session.terminal;
    expect(await session.sendComposerText('Scoped composed input'), isTrue);
    expect(
      sent
          .lastWhere((frame) => frame.type == 'message')
          .payload['inputContext'],
      'context_alpha_123456',
    );
    session.stageInputContext(null);
    expect(session.acceptsInput, isFalse);
    await session.setInputContext(null);
    expect(
      sent
          .lastWhere((frame) => frame.type == 'terminal_open')
          .payload
          .containsKey('inputContext'),
      isFalse,
    );
    expect(identical(session.terminal, latestTerminal), isTrue);
  });

  test(
    'a renderer that keeps failing still gives up rather than looping',
    () async {
      await ready();
      await session.handleBinary(
        output(0, 'hello'.codeUnits, keyframe: true, cols: 100, rows: 30),
      );

      for (var attempt = 0; attempt < 8; attempt++) {
        await session.onRendererFailure();
      }

      // Bounded by the existing ladder: three resyncs, then a reopen.
      final resyncs = sent.where((f) => f.type == 'terminal_resync').length;
      expect(resyncs, lessThanOrEqualTo(3));
    },
  );

  test('a watch-only scope cannot take control or submit text', () async {
    await ready();
    await session.handleBinary(
      output(0, 'screen'.codeUnits, keyframe: true, cols: 100, rows: 30),
    );
    session.stageInputContext(null, watchOnly: true);
    expect(session.readOnly, isTrue);
    expect(session.acceptsInput, isFalse);
    expect(await session.sendComposerText('Do not send'), isFalse);
    await session.setInputContext(null, watchOnly: true);
    expect(
      sent
          .lastWhere((frame) => frame.type == 'terminal_open')
          .payload['watchOnly'],
      isTrue,
    );
    expect(sent.where((frame) => frame.type == 'message'), isEmpty);
  });

  test('a tmux passthrough sequence is swallowed, not painted', () async {
    await ready();

    // Verbatim shape of what Claude Code emits inside tmux to ask the OUTER
    // terminal for its background colour: OSC 11 wrapped in tmux's DCS
    // passthrough, which doubles every ESC in the body.
    //
    //   ESC P tmux; ESC ESC ] 11 ; ? BEL ESC \
    //
    // Untreated it reached the screen as `tmux;]11;?` in the middle of Claude's
    // theme picker, because ESC P was an unknown escape and the body then fell
    // through to the text path one fragment at a time.
    await session.handleBinary(
      output(
        0,
        utf8.encode('1. \x1bPtmux;\x1b\x1b]11;?\x07\x1b\\(match terminal)'),
        keyframe: true,
        cols: 80,
        rows: 24,
      ),
    );

    final text = session.terminal.buffer.getText();
    expect(text, startsWith('1. (match terminal)'));
    expect(text, isNot(contains('tmux;')));
    expect(text, isNot(contains(']11;?')));
  });

  test('an unterminated string sequence never leaks its body', () async {
    await ready();

    // Split across two writes with no ST in sight: the parser must hold the body
    // back rather than print what it has, the same contract OSC keeps.
    await session.handleBinary(
      output(
        0,
        utf8.encode('A\x1bPtmux;partial'),
        keyframe: true,
        cols: 80,
        rows: 24,
      ),
    );
    expect(session.terminal.buffer.getText(), isNot(contains('partial')));

    await session.handleBinary(output(1, utf8.encode('\x1b\\B')));
    final text = session.terminal.buffer.getText();
    expect(text, startsWith('AB'));
    expect(text, isNot(contains('tmux;')));
  });

  test('CSI erase-left at column zero renders without a resync', () async {
    await ready();

    await session.handleBinary(
      output(
        0,
        utf8.encode('abc\x1b[1G\x1b[1K'),
        keyframe: true,
        cols: 80,
        rows: 24,
      ),
    );

    expect(session.status, TerminalSessionStatus.controlling);
    // Cell 0 is now blank (erased), not gone — it copies as a literal leading space, the same as
    // any other blank cell with real content after it. See the getText() whitespace test below.
    expect(session.terminal.buffer.getText(), startsWith(' bc'));
    expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
  });

  test('copied text keeps cursor-positioned gaps as spaces instead of gluing words together', () async {
    await ready();

    // TUI-style output (Claude Code, Codex, …) lays out text with cursor-forward moves (CSI C)
    // rather than printing literal space bytes — those cells are never written to, so their
    // stored codePoint is 0, the same value an erased cell has. Line 1: 3-column indent before
    // "indented". Line 2: a 5-column gap between two words.
    await session.handleBinary(
      output(
        0,
        utf8.encode('\x1b[3Cindented\r\nfirst\x1b[5Csecond'),
        keyframe: true,
        cols: 80,
        rows: 24,
      ),
    );

    final lines = session.terminal.buffer.getText().split('\n');
    expect(lines[0], '   indented');
    expect(lines[1], 'first     second');
    // A line with no real content anywhere must still copy as empty, not as columns of padding —
    // only the gap BEFORE real content becomes spaces, not blank cells with nothing after them.
    expect(lines[2], isEmpty);
  });

  test(
    'uses measured viewport geometry for the initial terminal_open',
    () async {
      final opening = session.open(
        initialCols: 80,
        initialRows: 24,
        waitForViewportSize: true,
      );
      await Future<void>.delayed(Duration.zero);
      expect(sent, isEmpty);

      session.reportViewport(168, 54);
      await opening;

      expect(sent.single.type, 'terminal_open');
      expect(sent.single.payload['cols'], 168);
      expect(sent.single.payload['rows'], 54);
      expect(session.cols, 168);
      expect(session.rows, 54);
    },
  );

  test('opens immediately at fallback size and flushes measured resize after first keyframe', () async {
    await session.open();
    expect(sent.single.type, 'terminal_open');
    expect(sent.single.payload, containsPair('cols', 80));
    final requestId = sent.single.payload['requestId'];

    session.reportViewport(120, 40);
    expect(sent.where((frame) => frame.type == 'terminal_resize'), isEmpty);
    await session.handleFrame('terminal_ready', {
      'requestId': requestId,
      'protocolVersion': 3,
      'streamId': streamId,
      'agentId': 'agent-1',
    });
    await session.handleBinary(
      output(0, const [], keyframe: true, cols: 80, rows: 24),
    );
    await Future<void>.delayed(Duration.zero);

    expect(
      sent.where((frame) => frame.type == 'terminal_resize').single.payload,
      containsPair('cols', 120),
    );
  });

  test(
    'keyframe + split UTF-8 output render in FIFO order and ACK quickly',
    () async {
      await ready();
      final before = session.terminal;
      await session.handleBinary(
        output(
          0,
          utf8.encode('hello '),
          compress: true,
          keyframe: true,
          cols: 100,
          rows: 30,
        ),
      );
      expect(session.status, TerminalSessionStatus.controlling);
      expect(identical(before, session.terminal), isFalse);

      final emoji = utf8.encode('😀');
      await session.handleBinary(output(1, emoji.sublist(0, 2)));
      await session.handleBinary(
        output(2, [...emoji.sublist(2), ...utf8.encode(' world')]),
      );
      expect(session.terminal.buffer.getText(), startsWith('hello 😀 world'));

      await Future<void>.delayed(const Duration(milliseconds: 70));
      final ack = sent.lastWhere((frame) => frame.type == 'terminal_ack');
      expect(ack.payload['lastSeq'], 2);
    },
  );

  test('standalone terminal keeps query replies on its output callback', () {
    final emitted = <String>[];
    final terminal = Terminal(onOutput: emitted.add)..resize(80, 24);
    terminal.write('\x1b[6n\x1b[5n\x1b[c\x1b[>c\x1b[=c\x1b[18t');
    expect(emitted, hasLength(6));
    expect(emitted.first, '\x1b[0;0R');
  });

  test(
    'remote cursor queries do not inject replies before the first key',
    () async {
      await ready();
      await session.handleBinary(
        output(0, utf8.encode('PS> '), keyframe: true, cols: 80, rows: 24),
      );
      // The host emulator has already answered these. A second cursor reply
      // makes Windows PowerShell/PSReadLine swallow the first printable key.
      await session.handleBinary(output(1, utf8.encode('\x1b[6n')));
      await Future<void>.delayed(const Duration(milliseconds: 12));
      expect(binarySent, isEmpty);

      session.terminal.textInput('a');
      await Future<void>.delayed(const Duration(milliseconds: 12));
      expect(binarySent, hasLength(1));
      expect(utf8.decode(binarySent.single.bytes), 'a');
      expect(binarySent.single.seq, 0);
    },
  );

  test('remote terminals preserve other query responses', () async {
    await ready();
    await session.handleBinary(
      output(0, utf8.encode('PS> '), keyframe: true, cols: 80, rows: 24),
    );
    // DA3 is not answered by every host emulator; keep its existing behavior.
    await session.handleBinary(output(1, utf8.encode('\x1b[=c')));
    await Future<void>.delayed(const Duration(milliseconds: 12));
    expect(binarySent, hasLength(1));
    expect(utf8.decode(binarySent.single.bytes), '\x1bP!|00000000\x1b\\');
  });

  test(
    'terminal input batches, preserves Enter boundary and is never retried',
    () async {
      // Keep all typed characters inside the 4 ms logical batching window,
      // even when a loaded CI host takes longer to schedule the test itself.
      controlledNow = DateTime(2026, 9, 18);
      await ready();
      await session.handleBinary(
        output(0, utf8.encode(r'prompt> '), keyframe: true, cols: 80, rows: 24),
      );

      // Leading edge: the first keystroke after a pause is not held for the batching window.
      session.terminal.onOutput?.call('abc');
      await Future<void>.delayed(const Duration(milliseconds: 1));
      expect(binarySent, hasLength(1));
      expect(utf8.decode(binarySent.single.bytes), 'abc');

      // Anything arriving inside the window is batched behind the trailing timer instead.
      session.terminal.onOutput?.call('d');
      session.terminal.onOutput?.call('ef');
      expect(binarySent, hasLength(1));
      await Future<void>.delayed(const Duration(milliseconds: 12));
      session.terminal.onOutput?.call('\r');
      await Future<void>.delayed(const Duration(milliseconds: 12));

      final inputs = binarySent;
      expect(inputs, hasLength(3));
      expect(utf8.decode(inputs[0].bytes), 'abc');
      expect(utf8.decode(inputs[1].bytes), 'def');
      expect(utf8.decode(inputs[2].bytes), '\r');
      expect(inputs.map((frame) => frame.seq), [0, 1, 2]);
      expect(
        inputs.every((frame) => frame.kind == TerminalBinaryKind.input),
        isTrue,
      );

      final paste = '\x1b[200~${'x' * 20000}\x1b[201~';
      session.terminal.onOutput?.call(paste);
      await Future<void>.delayed(const Duration(milliseconds: 12));
      final pasteFrames = binarySent.skip(3).toList();
      expect(pasteFrames, hasLength(3));
      final pasteBytes = <int>[for (final frame in pasteFrames) ...frame.bytes];
      expect(
        pasteFrames.every((frame) => frame.bytes.length <= 8 * 1024),
        isTrue,
      );
      expect(utf8.decode(pasteBytes), paste);

      session.transportLost();
      session.terminal.onOutput?.call('must-not-send');
      await Future<void>.delayed(const Duration(milliseconds: 8));
      expect(binarySent, hasLength(6));
      expect(session.status, TerminalSessionStatus.error);
    },
  );

  test(
    'terminal input preserves committed IME Unicode as UTF-8 bytes',
    () async {
      await ready();
      await session.handleBinary(
        output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
      );
      const committed = 'Tiếng Việt 日本語 中文';

      session.terminal.onOutput?.call(committed);
      await Future<void>.delayed(const Duration(milliseconds: 12));

      expect(binarySent, hasLength(1));
      expect(binarySent.single.bytes, orderedEquals(utf8.encode(committed)));
      expect(utf8.decode(binarySent.single.bytes), committed);
    },
  );

  test('malformed PTY UTF-8 renders replacement text without resync', () async {
    await ready();
    await session.handleBinary(
      output(0, utf8.encode('screen '), keyframe: true, cols: 80, rows: 24),
    );

    await session.handleBinary(output(1, [0x80, ...utf8.encode('tail')]));

    expect(session.status, TerminalSessionStatus.controlling);
    expect(session.terminal.buffer.getText(), contains('\uFFFDtail'));
    expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
  });

  test(
    'local cursor blink preserves the remote cursor visibility state',
    () async {
      await ready();
      await session.handleBinary(
        output(
          0,
          utf8.encode('prompt\x1b[?25h'),
          keyframe: true,
          cols: 80,
          rows: 24,
        ),
      );

      session.setCursorBlinkPhase(false);
      expect(session.terminal.cursorVisibleMode, isFalse);

      // Ordinary output while the paint phase is dark must not become a remote
      // cursor-hide command. The next bright phase restores the cursor.
      await session.handleBinary(output(1, utf8.encode('x')));
      expect(session.terminal.cursorVisibleMode, isFalse);
      session.setCursorBlinkPhase(true);
      expect(session.terminal.cursorVisibleMode, isTrue);

      // An explicit remote hide stays hidden through later blink phases.
      await session.handleBinary(output(2, utf8.encode('\x1b[?25l')));
      session.setCursorBlinkPhase(false);
      session.setCursorBlinkPhase(true);
      expect(session.terminal.cursorVisibleMode, isFalse);
    },
  );

  test(
    'cursor visibility notifications ignore local blinks and ordinary output',
    () async {
      await ready();
      await session.handleBinary(
        output(
          0,
          utf8.encode('prompt\x1b[?25h'),
          keyframe: true,
          cols: 100,
          rows: 30,
        ),
      );
      final visibility = <bool>[];
      var sessionChanges = 0;
      session.remoteCursorVisibility.addListener(() {
        visibility.add(session.remoteCursorVisibility.value);
      });
      session.addListener(() => sessionChanges++);

      expect(session.setCursorBlinkPhase(false), isTrue);
      expect(session.setCursorBlinkPhase(false), isFalse);
      expect(session.remoteCursorVisibility.value, isTrue);
      await session.handleBinary(output(1, utf8.encode('output')));
      expect(session.terminal.cursorVisibleMode, isFalse);
      expect(visibility, isEmpty);
      expect(session.setCursorBlinkPhase(true), isTrue);

      await session.handleBinary(output(2, utf8.encode('\x1b[?25l')));
      expect(visibility, [false]);
      expect(session.setCursorBlinkPhase(false), isFalse);
      expect(session.setCursorBlinkPhase(true), isFalse);
      // Transient hide/show within one packet does not change the final state.
      await session.handleBinary(output(3, utf8.encode('\x1b[?25h\x1b[?25l')));
      expect(visibility, [false]);
      await session.handleBinary(output(4, utf8.encode('\x1b[?25h')));
      expect(visibility, [false, true]);
      expect(
        sessionChanges,
        0,
        reason: 'cursor changes must not rebuild the workspace',
      );
    },
  );

  test('remote history keyframe survives viewport resize without circular-buffer reflow', () async {
    await ready();
    final oldStyleHistory = List.generate(
      1000,
      (index) => '\x1b[3${index % 8}mremote-history-$index\x1b[0m\r\n',
    ).join();
    final keyframe = utf8.encode(
      '\x1bc\x1b[?25l\x1b[?7l\x1b[H\x1b[2J\x1b[3J'
      '$oldStyleHistory\x1b[1;1Hremote-current-screen\x1b[0m'
      '\x1b[20;7H\x1b[?7h\x1b[?25h',
    );

    await session.handleBinary(
      output(0, keyframe, keyframe: true, cols: 154, rows: 48),
    );

    expect(session.terminal.reflowEnabled, isFalse);
    expect(
      session.terminal.buffer.getText(),
      contains('remote-current-screen'),
    );
    expect(() => session.terminal.resize(235, 52), returnsNormally);
    expect(() => session.terminal.resize(154, 48), returnsNormally);
    expect(session.status, TerminalSessionStatus.controlling);
  });

  test(
    'scroll-region output keeps buffer lines attached across frames',
    () async {
      await ready();
      await session.handleBinary(
        output(
          0,
          utf8.encode(
            'one\r\ntwo\r\nthree\r\nfour\r\nfive'
            '\x1b[2;5r\x1b[5;1H\n',
          ),
          keyframe: true,
          cols: 80,
          rows: 24,
        ),
      );

      // The first partial-region scroll used to leave duplicated, detached
      // BufferLine objects. A later top-anchored scroll then crashed inside
      // IndexAwareCircularBuffer.insert, matching the Grok live failure.
      await session.handleBinary(
        output(1, utf8.encode('\x1b[1;5r\x1b[5;1H\nnext')),
      );

      expect(session.status, TerminalSessionStatus.controlling);
      expect(session.terminal.buffer.getText(), contains('next'));
      expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
    },
  );

  test(
    'reverse-index scroll keeps buffer lines attached across frames',
    () async {
      await ready();
      await session.handleBinary(
        output(
          0,
          utf8.encode(
            'one\r\ntwo\r\nthree\r\nfour\r\nfive'
            '\x1b[2;5r\x1b[2;1H\x1bM',
          ),
          keyframe: true,
          cols: 80,
          rows: 24,
        ),
      );

      await session.handleBinary(
        output(1, utf8.encode('\x1b[1;5r\x1b[5;1H\nnext')),
      );

      expect(session.status, TerminalSessionStatus.controlling);
      expect(session.terminal.buffer.getText(), contains('next'));
      expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
    },
  );

  test('Grok keyframes use remote-owned alternate-buffer scrolling', () async {
    session.dispose();
    session = TerminalSession(
      machineId: 'machine-1',
      agentId: 'agent-1',
      agentName: 'grok-agent',
      engineId: 'grok',
      send: (type, payload) async {
        sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
        return true;
      },
      sendBinary: (frame) async {
        binarySent.add(frame);
        return true;
      },
    );
    await ready();

    final staleRepaints = List.generate(
      80,
      (index) => '\x1b[31mstale-grok-frame-$index\x1b[0m\r\n',
    ).join();
    await session.handleBinary(
      output(
        0,
        utf8.encode(
          '\x1bc\x1b[?25l\x1b[?7l\x1b[H\x1b[2J'
          '$staleRepaints'
          '\x1b[H\x1b[2J\x1b[?1003h\x1b[?1006h'
          '\x1b[1;1Hcurrent-grok-screen\x1b[0m'
          '\x1b[5;7H\x1b[?7h\x1b[?25h',
        ),
        keyframe: true,
        cols: 80,
        rows: 24,
      ),
    );

    expect(session.terminal.isUsingAltBuffer, isTrue);
    expect(session.terminal.buffer.getText(), contains('current-grok-screen'));
    expect(
      session.terminal.buffer.getText(),
      isNot(contains('stale-grok-frame')),
    );
  });

  test('scrollViaTmuxCopyMode is true only for grok, mirroring _prepareKeyframeBytes', () {
    expect(
      session.scrollViaTmuxCopyMode,
      isFalse,
    ); // engineId: 'codex' from setUp
  });

  group('sendScrollCommand (grok only)', () {
    Future<void> readyGrokSession() async {
      session.dispose();
      session = TerminalSession(
        machineId: 'machine-1',
        agentId: 'agent-1',
        agentName: 'grok-agent',
        engineId: 'grok',
        send: (type, payload) async {
          sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
          return true;
        },
        sendBinary: (frame) async {
          binarySent.add(frame);
          return true;
        },
      );
      await ready();
      // acceptsInput (which _flushScrollCommand requires) only becomes true once a keyframe has
      // been applied — terminal_ready alone leaves status at `opening`.
      await session.handleBinary(
        output(0, utf8.encode('grok'), keyframe: true, cols: 100, rows: 30),
      );
    }

    test(
      'is a no-op for a non-grok session — codex still uses raw mouseInput',
      () async {
        await ready();
        session.sendScrollCommand(true, 5);
        await Future<void>.delayed(const Duration(milliseconds: 30));
        expect(sent.where((f) => f.type == 'terminal_scroll'), isEmpty);
      },
    );

    test('coalesces a burst of same-direction deltas into one frame', () async {
      await readyGrokSession();
      sent.clear();

      for (var i = 0; i < 5; i++) {
        session.sendScrollCommand(true, 1);
      }
      expect(
        sent.where((f) => f.type == 'terminal_scroll'),
        isEmpty,
      ); // still coalescing

      await Future<void>.delayed(const Duration(milliseconds: 30));
      final scrolls = sent.where((f) => f.type == 'terminal_scroll').toList();
      expect(scrolls, hasLength(1));
      expect(scrolls.single.payload['direction'], 'up');
      expect(scrolls.single.payload['lines'], 5);
      expect(scrolls.single.payload['streamId'], streamId);
    });

    test(
      'a direction reversal mid-burst flushes the first batch separately',
      () async {
        await readyGrokSession();
        sent.clear();

        session.sendScrollCommand(true, 3);
        session.sendScrollCommand(true, 2);
        session.sendScrollCommand(
          false,
          1,
        ); // reverses direction — flushes the 5 "up" first
        await Future<void>.delayed(const Duration(milliseconds: 30));

        final scrolls = sent
            .where((f) => f.type == 'terminal_scroll')
            .map((f) => f.payload)
            .toList();
        expect(scrolls, hasLength(2));
        expect(scrolls[0]['direction'], 'up');
        expect(scrolls[0]['lines'], 5);
        expect(scrolls[1]['direction'], 'down');
        expect(scrolls[1]['lines'], 1);
      },
    );
  });

  test('Ctrl+C (0x03) is forwarded like any other keystroke', () async {
    await ready();
    await session.handleBinary(
      output(0, utf8.encode(r'prompt> '), keyframe: true, cols: 80, rows: 24),
    );

    session.terminal.onOutput?.call('\x03');
    await Future<void>.delayed(const Duration(milliseconds: 12));
    expect(binarySent, hasLength(1));
    expect(utf8.decode(binarySent.single.bytes), '\x03');

    session.terminal.onOutput?.call('a\x03b');
    await Future<void>.delayed(const Duration(milliseconds: 12));
    expect(binarySent, hasLength(2));
    expect(utf8.decode(binarySent[1].bytes), 'a\x03b');
  });

  test(
    'sequence gap emits one resync and next keyframe replaces state',
    () async {
      await ready();
      await session.handleBinary(
        output(
          0,
          utf8.encode('old screen'),
          keyframe: true,
          cols: 80,
          rows: 24,
        ),
      );
      final oldTerminal = session.terminal;

      await session.handleBinary(output(2, utf8.encode('gap')));
      await session.handleBinary(output(3, utf8.encode('ignored')));
      expect(session.status, TerminalSessionStatus.resyncing);
      expect(
        sent.where((frame) => frame.type == 'terminal_resync'),
        hasLength(1),
      );

      await session.handleBinary(
        output(
          9,
          utf8.encode('new screen'),
          keyframe: true,
          cols: 90,
          rows: 28,
        ),
      );
      expect(session.status, TerminalSessionStatus.controlling);
      expect(session.errorCode, isNull);
      expect(identical(oldTerminal, session.terminal), isFalse);
      expect(session.terminal.buffer.getText(), startsWith('new screen'));
      expect(session.cols, 90);
      expect(session.rows, 28);
    },
  );

  test('a keystroke dropped while resyncing does not leave a hole in the input seq', () async {
    // The daemon counts input frames and never re-syncs that counter. A frame this side drops
    // — the session went `resyncing` while an earlier send was still in flight — used to take
    // its number with it, so the first keystroke after recovery arrived one ahead and was
    // refused: TERMINAL_INPUT_INVALID, and a frozen pane over a perfectly good tmux.
    final gate = Completer<void>();
    final frames = <TerminalBinaryFrame>[];
    final blocking = TerminalSession(
      machineId: 'machine-1',
      agentId: 'agent-1',
      agentName: 'backend-api',
      engineId: 'codex',
      send: (type, payload) async {
        sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
        return true;
      },
      sendBinary: (frame) async {
        frames.add(frame);
        if (frames.length == 1) await gate.future; // the first send stalls
        return true;
      },
    );
    addTearDown(blocking.dispose);
    await blocking.open(initialCols: 100, initialRows: 30);
    await blocking.handleFrame('terminal_ready', {
      'requestId': sent.single.payload['requestId'],
      'protocolVersion': 3,
      'streamId': streamId,
      'agentId': 'agent-1',
    });
    await blocking.handleBinary(
      output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
    );

    blocking.terminal.onOutput?.call('a'); // seq 0, send stalls on the gate
    await Future<void>.delayed(const Duration(milliseconds: 1));
    blocking.terminal.onOutput?.call('b'); // queued behind it
    await Future<void>.delayed(const Duration(milliseconds: 12));
    expect(frames, hasLength(1));

    // The output stream skips a number: resync, same stream.
    await blocking.handleBinary(output(5, utf8.encode('gap')));
    expect(blocking.status, TerminalSessionStatus.resyncing);
    gate.complete(); // 'a' goes out; 'b' reaches the tail while resyncing and is dropped
    await Future<void>.delayed(const Duration(milliseconds: 1));

    await blocking.handleBinary(
      output(9, utf8.encode('fresh'), keyframe: true, cols: 80, rows: 24),
    );
    expect(blocking.status, TerminalSessionStatus.controlling);
    blocking.terminal.onOutput?.call('c');
    await Future<void>.delayed(const Duration(milliseconds: 12));

    final inputs = frames.where((f) => f.kind == TerminalBinaryKind.input);
    expect(inputs.map((f) => utf8.decode(f.bytes)), ['a', 'c']);
    // Contiguous: the dropped 'b' did not spend a number.
    expect(inputs.map((f) => f.seq), [0, 1]);
  });

  test(
    'TERMINAL_INPUT_INVALID with expectedSeq realigns in place, nothing frozen',
    () async {
      await ready();
      await session.handleBinary(
        output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
      );
      session.terminal.onOutput?.call('a');
      await Future<void>.delayed(const Duration(milliseconds: 12));
      session.terminal.onOutput?.call('b');
      await Future<void>.delayed(const Duration(milliseconds: 12));
      expect(binarySent.map((f) => f.seq), [0, 1]);

      // The daemon only ever saw seq 0 — say it is still waiting for 1.
      await session.handleFrame('terminal_error', {
        'streamId': streamId,
        'code': 'TERMINAL_INPUT_INVALID',
        'reason': 'seq',
        'expectedSeq': 1,
      });
      expect(session.status, TerminalSessionStatus.controlling);
      expect(session.errorCode, isNull);
      expect(sent.where((f) => f.type == 'terminal_close'), isEmpty);
      expect(sent.where((f) => f.type == 'terminal_open'), hasLength(1));

      session.terminal.onOutput?.call('c');
      await Future<void>.delayed(const Duration(milliseconds: 12));
      expect(binarySent.last.seq, 1);
      expect(utf8.decode(binarySent.last.bytes), 'c');
    },
  );

  test('a stale duplicate TERMINAL_INPUT_INVALID does not rewind a counter that moved on', () async {
    // The daemon refuses every in-flight frame it cannot take, each naming
    // the same expected seq. By the time the second refusal lands, the
    // first has already realigned us and frames under the new numbers have
    // been accepted — rewinding again would reuse them.
    await ready();
    await session.handleBinary(
      output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
    );
    session.terminal.onOutput?.call('a');
    await Future<void>.delayed(const Duration(milliseconds: 12));
    session.terminal.onOutput?.call('b');
    await Future<void>.delayed(const Duration(milliseconds: 12));
    session.terminal.onOutput?.call('c');
    await Future<void>.delayed(const Duration(milliseconds: 12));
    expect(binarySent.map((f) => f.seq), [0, 1, 2]);

    // Both 'b' (1) and 'c' (2) were refused: the daemon still wants 1.
    final refusal = {
      'streamId': streamId,
      'code': 'TERMINAL_INPUT_INVALID',
      'reason': 'seq',
      'expectedSeq': 1,
    };
    await session.handleFrame('terminal_error', refusal);
    session.terminal.onOutput?.call('d'); // goes out as 1, accepted
    await Future<void>.delayed(const Duration(milliseconds: 12));
    await session.handleFrame('terminal_error', refusal); // the stale one
    session.terminal.onOutput?.call('e');
    await Future<void>.delayed(const Duration(milliseconds: 12));

    final after = binarySent.skip(3).toList();
    expect(after.map((f) => utf8.decode(f.bytes)), ['d', 'e']);
    expect(after.map((f) => f.seq), [1, 2]);
    expect(session.status, TerminalSessionStatus.controlling);

    // A genuinely new gap names a larger seq and is honoured.
    await session.handleFrame('terminal_error', {...refusal, 'expectedSeq': 2});
    session.terminal.onOutput?.call('f');
    await Future<void>.delayed(const Duration(milliseconds: 12));
    expect(binarySent.last.seq, 2);
  });

  test(
    'TERMINAL_INPUT_INVALID from an older daemon reopens instead of freezing',
    () async {
      await ready();
      await session.handleBinary(
        output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
      );
      session.terminal.onOutput?.call('a');
      await Future<void>.delayed(const Duration(milliseconds: 12));

      // No expectedSeq: a daemon from before it said. The only way back in step is a new stream.
      await session.handleFrame('terminal_error', {
        'streamId': streamId,
        'code': 'TERMINAL_INPUT_INVALID',
      });
      expect(session.status, isNot(TerminalSessionStatus.error));
      expect(sent.where((f) => f.type == 'terminal_close'), hasLength(1));
      final opens = sent.where((f) => f.type == 'terminal_open').toList();
      expect(opens, hasLength(2));

      const newStream = 'ffeeddcc-bbaa-9988-7766-554433221100';
      await session.handleFrame('terminal_ready', {
        'requestId': opens.last.payload['requestId'],
        'protocolVersion': 3,
        'streamId': newStream,
        'agentId': 'agent-1',
      });
      await session.handleBinary(
        TerminalBinaryFrame(
          kind: TerminalBinaryKind.keyframe,
          streamId: newStream,
          seq: 0,
          bytes: Uint8List.fromList(utf8.encode('prompt> ')),
          compressed: false,
          cols: 80,
          rows: 24,
        ),
      );
      expect(session.status, TerminalSessionStatus.controlling);
      session.terminal.onOutput?.call('b');
      await Future<void>.delayed(const Duration(milliseconds: 12));
      expect(binarySent.last.streamId, newStream);
      expect(binarySent.last.seq, 0);
    },
  );

  test(
    'input larger than the daemon accepts is split, never refused',
    () async {
      await ready();
      await session.handleBinary(
        output(0, utf8.encode('prompt> '), keyframe: true, cols: 80, rows: 24),
      );
      // Bypass the 8 KiB chunker's boundaries: one contiguous burst of 70,000 bytes.
      session.terminal.onOutput?.call('x' * 70000);
      await Future<void>.delayed(const Duration(milliseconds: 12));
      final inputs = binarySent
          .where((f) => f.kind == TerminalBinaryKind.input)
          .toList();
      expect(
        inputs.every(
          (f) => f.bytes.length <= TerminalSession.kInputFrameMaxBytes,
        ),
        isTrue,
      );
      expect(inputs.map((f) => f.seq), List.generate(inputs.length, (i) => i));
      expect(inputs.fold<int>(0, (n, f) => n + f.bytes.length), 70000);
    },
  );

  test(
    'idle sync advances sequence and is acknowledged after render',
    () async {
      await ready();
      await session.handleBinary(
        output(0, utf8.encode('screen'), keyframe: true, cols: 80, rows: 24),
      );
      await session.handleBinary(
        TerminalBinaryFrame(
          kind: TerminalBinaryKind.sync,
          streamId: streamId,
          seq: 1,
          bytes: Uint8List(0),
          compressed: false,
        ),
      );
      await Future<void>.delayed(const Duration(milliseconds: 30));
      expect(session.status, TerminalSessionStatus.controlling);
      expect(
        sent
            .lastWhere((frame) => frame.type == 'terminal_ack')
            .payload['lastSeq'],
        1,
      );
    },
  );

  test(
    'takeover freezes the rendered terminal until the user reconnects',
    () async {
      await ready();
      await session.handleBinary(
        output(
          0,
          utf8.encode('last screen'),
          keyframe: true,
          cols: 80,
          rows: 24,
        ),
      );

      await session.handleFrame('terminal_closed', {
        'streamId': streamId,
        'code': 'TERMINAL_TAKEN_OVER',
        'reason': 'another client connected',
      });

      expect(session.status, TerminalSessionStatus.takenOver);
      expect(session.acceptsInput, isFalse);
      expect(session.errorCode, 'TERMINAL_TAKEN_OVER');
      expect(session.errorMessage, contains('Another client'));
      expect(session.terminal.buffer.getText(), contains('last screen'));

      // A WS hiccup on this machine (node offline/online) must not turn a takeover into a plain
      // `error`, which auto-reattach would then silently reopen — re-stealing the terminal back
      // from whoever took it over.
      session.transportLost('Harness reconnected; restoring terminal…');
      expect(session.status, TerminalSessionStatus.takenOver);
    },
  );

  // Who took the terminal rides on the close (`takenBy`), so the banner can
  // name them; the name goes away with the next open, so a retaken pane never
  // shows a stale one.
  test('a takeover names its taker when the daemon says who', () async {
    await ready();
    await session.handleFrame('terminal_closed', {
      'streamId': streamId,
      'code': 'TERMINAL_TAKEN_OVER',
      'reason': 'another client connected',
      'takenBy': {
        'kind': 'desktop',
        'name': 'Mac mini',
        'machineId': 'ab12ab12ab12ab12',
      },
    });
    expect(session.status, TerminalSessionStatus.takenOver);
    expect(session.takenOverBy?.name, 'Mac mini');
    expect(session.takenOverBy?.kind, 'desktop');
    expect(session.takenOverBy?.machineId, 'ab12ab12ab12ab12');
    expect(session.errorMessage, contains('Mac mini'));
    // The fleet's current name for that machine wins over the declared one.
    expect(
      session.takenOverBy!.label(
        (id) => id == 'ab12ab12ab12ab12' ? 'Studio' : null,
      ),
      'Studio',
    );
    expect(session.takenOverBy!.label((_) => null), 'Mac mini');

    await session.reopen();
    expect(session.takenOverBy, isNull);
  });

  test(
    'a takeover with no or a malformed taker reads as another app',
    () async {
      await ready();
      await session.handleFrame('terminal_closed', {
        'streamId': streamId,
        'code': 'TERMINAL_TAKEN_OVER',
        'takenBy': {'kind': 'not a kind', 'name': 'x'},
      });
      expect(session.status, TerminalSessionStatus.takenOver);
      expect(session.takenOverBy, isNull);
      expect(session.errorMessage, contains('Another client'));
      expect(
        TerminalClientDescriptor.fromJson({'kind': 'phone', 'name': ' iPhone '})
            ?.name,
        'iPhone',
      );
      expect(
        TerminalClientDescriptor.fromJson({
          'kind': 'desktop',
          'name': 'a',
          'machineId': '../x',
        }),
        isNull,
      );
      expect(TerminalClientDescriptor.fromJson('Mac'), isNull);
    },
  );

  test(
    'terminal_open carries this client\'s introduction when it has one',
    () async {
      final introduced = TerminalSession(
        machineId: 'machine-1',
        agentId: 'agent-1',
        agentName: 'backend-api',
        engineId: 'codex',
        client: const TerminalClientDescriptor(
          kind: 'desktop',
          name: 'This Mac',
          machineId: 'ab12ab12ab12ab12',
        ),
        send: (type, payload) async {
          sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
          return true;
        },
        sendBinary: (_) async => true,
      );
      addTearDown(introduced.dispose);
      await introduced.open(initialCols: 100, initialRows: 30);
      expect(sent.single.payload['client'], {
        'kind': 'desktop',
        'name': 'This Mac',
        'machineId': 'ab12ab12ab12ab12',
      });
      sent.clear();
      await session.open(initialCols: 100, initialRows: 30);
      expect(sent.single.payload.containsKey('client'), isFalse);
    },
  );

  test(
    'terminal_link_mode updates linkMode, ignoring a stale stream id',
    () async {
      await ready();
      expect(session.linkMode, isNull);

      await session.handleFrame('terminal_link_mode', {
        'streamId': streamId,
        'mode': 'p2p',
      });
      expect(session.linkMode, 'p2p');

      await session.handleFrame('terminal_link_mode', {
        'streamId': streamId,
        'mode': 'relay',
      });
      expect(session.linkMode, 'relay');

      // A frame for a DIFFERENT (stale) stream id must not touch this session's state.
      await session.handleFrame('terminal_link_mode', {
        'streamId': 'some-other-stream',
        'mode': 'p2p',
      });
      expect(session.linkMode, 'relay');
    },
  );

  test('terminal_link_mode accepts turn, the third transport, alongside the other two', () async {
    await ready();

    // 'turn' is additive: 'relay' keeps meaning the backend WebSocket, so a build that predates TURN
    // can never read a Cloudflare-relayed session as a WS-relayed one.
    for (final mode in ['p2p', 'turn', 'relay']) {
      await session.handleFrame('terminal_link_mode', {
        'streamId': streamId,
        'mode': mode,
      });
      expect(session.linkMode, mode);
    }
  });

  test(
    'a mode this build cannot draw leaves the last known one alone',
    () async {
      await ready();
      await session.handleFrame('terminal_link_mode', {
        'streamId': streamId,
        'mode': 'turn',
      });
      expect(session.linkMode, 'turn');

      // A newer CLI inventing a fourth value must not blank the badge or set a value the header has no
      // icon for — the allow-list is what keeps linkMode drawable.
      await session.handleFrame('terminal_link_mode', {
        'streamId': streamId,
        'mode': 'quic',
      });
      expect(session.linkMode, 'turn');
    },
  );

  test(
    'linkMode resets whenever streamId resets (reopen/close/error)',
    () async {
      await ready();
      await session.handleFrame('terminal_link_mode', {
        'streamId': streamId,
        'mode': 'p2p',
      });
      expect(session.linkMode, 'p2p');

      await session.handleFrame('terminal_closed', {
        'streamId': streamId,
        'reason': 'closed by peer',
      });
      expect(session.streamId, isNull);
      expect(session.linkMode, isNull);
    },
  );

  group('stream liveness', () {
    setUp(() => controlledNow = DateTime.utc(2026));

    Future<void> tick(WidgetTester tester, Duration elapsed) async {
      controlledNow = controlledNow!.add(elapsed);
      await tester.pump(elapsed);
    }

    Future<void> live() async {
      await ready();
      await session.handleBinary(
        output(
          0,
          utf8.encode('retained screen'),
          keyframe: true,
          cols: 100,
          rows: 30,
        ),
      );
    }

    TerminalBinaryFrame sync(int seq, {String id = streamId}) =>
        TerminalBinaryFrame(
          kind: TerminalBinaryKind.sync,
          streamId: id,
          seq: seq,
          bytes: Uint8List(0),
          compressed: false,
        );

    for (final watching in [false, true]) {
      testWidgets(
        'a silently replaced stream recovers without replaying input (watching=$watching)',
        (tester) async {
          await live();
          final retained = session.terminal;
          session.terminal.textInput('sent before disconnect');
          await tester.pump(const Duration(milliseconds: 5));
          binarySent.clear();

          for (var i = 0; i < 3; i++) {
            await tick(tester, const Duration(seconds: 5));
          }
          expect(session.status, TerminalSessionStatus.resyncing);
          expect(session.errorCode, 'TERMINAL_STREAM_TIMEOUT');
          expect(session.acceptsInput, isFalse);
          expect(session.terminal, same(retained));
          // Nothing answers for the vanished stream. Use the existing bounded ladder.
          for (var i = 0; i < 3; i++) {
            await tick(tester, const Duration(seconds: 4));
          }
          final opens = sent
              .where((frame) => frame.type == 'terminal_open')
              .toList();
          expect(opens, hasLength(2));
          expect(opens.last.payload['takeover'], isFalse);
          expect(session.status, TerminalSessionStatus.opening);
          expect(session.terminal, same(retained));

          // The daemon now reports replacement explicitly. A late close for the old
          // stream must not kill the reopen this view already asked for.
          await session.handleFrame('terminal_closed', {
            'streamId': streamId,
            'code': 'TERMINAL_TAKEN_OVER',
            'reason': 'terminal reopened in another view',
          });
          expect(session.status, TerminalSessionStatus.opening);
          const replacementId = '11112233-4455-6677-8899-aabbccddeeff';
          await session.handleFrame('terminal_ready', {
            'requestId': opens.last.payload['requestId'],
            'protocolVersion': 3,
            'streamId': replacementId,
            'agentId': 'agent-1',
            'readOnly': watching,
          });
          expect(session.acceptsInput, isFalse);
          await session.handleBinary(
            TerminalBinaryFrame(
              kind: TerminalBinaryKind.keyframe,
              streamId: replacementId,
              seq: 0,
              bytes: Uint8List.fromList(utf8.encode('reconnected screen')),
              compressed: false,
              cols: 100,
              rows: 30,
            ),
          );
          expect(session.acceptsInput, !watching);
          expect(
            binarySent,
            isEmpty,
            reason: 'Input on the retired stream is never replayed',
          );
          session.terminal.textInput('new input');
          await tester.pump(const Duration(milliseconds: 5));
          if (watching) {
            expect(binarySent, isEmpty);
          } else {
            expect(binarySent.single.streamId, replacementId);
            expect(utf8.decode(binarySent.single.bytes), 'new input');
          }
          await session.close();
        },
      );
    }

    testWidgets('a live stream that answers resync keeps its lease', (
      tester,
    ) async {
      await live();
      await tick(tester, const Duration(seconds: 15));
      expect(session.status, TerminalSessionStatus.resyncing);
      await session.handleBinary(
        output(
          5,
          utf8.encode('fresh snapshot'),
          keyframe: true,
          cols: 100,
          rows: 30,
        ),
      );
      expect(session.acceptsInput, isTrue);
      expect(session.errorCode, isNull);
      await tick(tester, const Duration(seconds: 5));
      await session.handleBinary(sync(6));
      expect(session.acceptsInput, isTrue);
      expect(
        sent.where((frame) => frame.type == 'terminal_open'),
        hasLength(1),
      );
      await session.close();
    });

    for (final kind in ['sync', 'output']) {
      testWidgets('$kind frames keep a live terminal healthy', (tester) async {
        await live();
        for (var seq = 1; seq <= 8; seq++) {
          await tick(tester, const Duration(seconds: 5));
          await session.handleBinary(
            kind == 'sync' ? sync(seq) : output(seq, utf8.encode('text')),
          );
        }
        expect(session.acceptsInput, isTrue);
        expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
        expect(
          sent.where((frame) => frame.type == 'terminal_open'),
          hasLength(1),
        );
        await session.close();
      });
    }

    testWidgets('traffic for other panes cannot hide a stale terminal', (
      tester,
    ) async {
      await live();
      for (var seq = 1; seq <= 3; seq++) {
        await session.handleBinary(sync(seq, id: 'another-pane'));
        await session.handleFrame('terminal_link_mode', {
          'streamId': streamId,
          'mode': 'turn',
        });
        await tick(tester, const Duration(seconds: 5));
      }
      expect(session.status, TerminalSessionStatus.resyncing);
      expect(session.errorCode, 'TERMINAL_STREAM_TIMEOUT');
      await session.close();
    });

    testWidgets(
      'a reported takeover waits for the user instead of reconnecting',
      (tester) async {
        await live();
        await session.handleFrame('terminal_closed', {
          'streamId': streamId,
          'code': 'TERMINAL_TAKEN_OVER',
          'reason': 'terminal reopened in another view',
        });
        await tick(tester, const Duration(seconds: 60));
        expect(session.status, TerminalSessionStatus.takenOver);
        expect(session.acceptsInput, isFalse);
        expect(
          sent.where((frame) => frame.type == 'terminal_open'),
          hasLength(1),
        );
        expect(sent.where((frame) => frame.type == 'terminal_resync'), isEmpty);
        await session.close();
      },
    );
  });

  testWidgets('resync retries three times, reopens once, then fails closed', (
    tester,
  ) async {
    session.dispose();
    session = TerminalSession(
      machineId: 'machine-1',
      agentId: 'agent-1',
      agentName: 'backend-api',
      engineId: 'codex',
      resyncTimeout: const Duration(milliseconds: 5),
      send: (type, payload) async {
        sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
        return true;
      },
      sendBinary: (frame) async {
        binarySent.add(frame);
        return true;
      },
    );
    await ready();
    await session.handleBinary(
      output(0, utf8.encode('screen'), keyframe: true, cols: 80, rows: 24),
    );
    await session.handleBinary(output(2, utf8.encode('gap')));

    // Advance the retry clock deterministically; an overloaded test runner
    // can wake a 45 ms wall-clock wait before the last 5 ms retry is armed.
    await tester.pump(const Duration(milliseconds: 45));

    expect(
      sent.where((frame) => frame.type == 'terminal_resync'),
      hasLength(3),
    );
    expect(sent.where((frame) => frame.type == 'terminal_open'), hasLength(2));
    expect(sent.where((frame) => frame.type == 'terminal_close'), hasLength(1));
    expect(session.status, TerminalSessionStatus.error);
    expect(session.errorCode, 'TERMINAL_RESYNC_TIMEOUT');
  });

  testWidgets(
    'heartbeats and resyncs ask the daemon to report a stream it no longer has',
    (tester) async {
      session.dispose();
      session = TerminalSession(
        machineId: 'machine-1',
        agentId: 'agent-1',
        agentName: 'backend-api',
        engineId: 'codex',
        resyncTimeout: const Duration(seconds: 30),
        send: (type, payload) async {
          sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
          return true;
        },
        sendBinary: (frame) async => true,
      );
      await ready();
      await session.handleBinary(
        output(0, utf8.encode('screen'), keyframe: true, cols: 80, rows: 24),
      );
      await tester.pump(const Duration(seconds: 5));
      expect(
        sent.lastWhere((frame) => frame.type == 'terminal_alive').payload,
        {'streamId': streamId, 'reportMissing': true},
      );

      await session.handleBinary(output(2, utf8.encode('gap')));
      await tester.pump();
      expect(
        sent
            .firstWhere((frame) => frame.type == 'terminal_resync')
            .payload['reportMissing'],
        isTrue,
      );
      await session.close();
    },
  );

  test('a reopen that may not redial leaves the machine link alone', () async {
    var redials = 0;
    TerminalSession stalled() => TerminalSession(
      machineId: 'machine-1',
      agentId: 'agent-1',
      agentName: 'backend-api',
      engineId: 'codex',
      send: (type, payload) async => type != 'terminal_open',
      sendBinary: (frame) async => true,
      onOpenStalled: () async => redials++,
    );
    final quiet = stalled();
    addTearDown(quiet.dispose);
    await quiet.reopen(redial: false);
    expect(redials, 0);
    expect(quiet.status, TerminalSessionStatus.error);

    final loud = stalled();
    final reopening = loud.reopen();
    await pumpEventQueue();
    expect(redials, 1);
    loud.dispose();
    await reopening;
  });

  test(
    'a stream the daemon no longer has is reopened in place at once',
    () async {
      await ready();
      await session.handleBinary(
        output(0, utf8.encode('screen'), keyframe: true, cols: 100, rows: 30),
      );
      await session.handleFrame('terminal_error', {
        'streamId': streamId,
        'code': 'TERMINAL_STREAM_NOT_FOUND',
        'message': 'no live terminal stream',
      });
      await pumpEventQueue();

      expect(
        sent.where((frame) => frame.type == 'terminal_open'),
        hasLength(2),
      );
      expect(session.status, TerminalSessionStatus.opening);
      expect(session.errorCode, isNot('TERMINAL_STREAM_NOT_FOUND'));
    },
  );

  test('a missing-stream report about another stream is ignored', () async {
    await ready();
    await session.handleFrame('terminal_error', {
      'streamId': 'ffffffff-ffff-ffff-ffff-ffffffffffff',
      'code': 'TERMINAL_STREAM_NOT_FOUND',
    });
    await pumpEventQueue();

    expect(sent.where((frame) => frame.type == 'terminal_open'), hasLength(1));
    expect(session.status, isNot(TerminalSessionStatus.error));
  });

  test('a failure is written to the file log with its code', () async {
    final log = _RecordingLog();
    final previous = appLog;
    appLog = log;
    addTearDown(() => appLog = previous);
    await ready();

    await session.handleFrame('terminal_error', {
      'streamId': streamId,
      'code': 'TERMINAL_SNAPSHOT_FAILED',
      'message': 'tmux snapshot failed',
    });

    expect(
      log.lines,
      contains(
        'terminal failed machine=machine-1 agent=agent-1 stream=$streamId '
        'code=TERMINAL_SNAPSHOT_FAILED message=tmux snapshot failed',
      ),
    );
  });

  group('slow input log', () {
    late _RecordingLog log;

    Future<void> typing() async {
      log = _RecordingLog();
      final previous = appLog;
      appLog = log;
      addTearDown(() => appLog = previous);
      controlledNow = DateTime(2026, 10, 19, 10);
      await ready();
      await session.handleBinary(
        output(0, utf8.encode(r'$ '), keyframe: true, cols: 100, rows: 30),
      );
      session.terminal.onOutput?.call('a');
      await pumpEventQueue();
      expect(binarySent, hasLength(1));
    }

    List<String> slow() =>
        log.lines.where((line) => line.contains('input ')).toList();

    test('an echo that comes back late is logged with the wait', () async {
      await typing();
      controlledNow = controlledNow!.add(const Duration(seconds: 9));
      await session.handleBinary(output(1, utf8.encode('a')));
      await pumpEventQueue();

      expect(slow(), [
        'terminal input answered late machine=machine-1 agent=agent-1 stream=$streamId '
            'link=null waitedMs=9000 by=output',
      ]);
    });

    test('a prompt echo is not logged', () async {
      await typing();
      controlledNow = controlledNow!.add(const Duration(milliseconds: 300));
      await session.handleBinary(output(1, utf8.encode('a')));
      await pumpEventQueue();

      expect(slow(), isEmpty);
    });

    test(
      'an idle sync after unechoed input is not logged inside its cadence',
      () async {
        await typing();
        controlledNow = controlledNow!.add(const Duration(seconds: 8));
        await session.handleBinary(
          TerminalBinaryFrame(
            kind: TerminalBinaryKind.sync,
            streamId: streamId,
            seq: 1,
            bytes: Uint8List(0),
            compressed: false,
          ),
        );
        await pumpEventQueue();

        expect(slow(), isEmpty);
      },
    );

    test('a stream timeout with typing still waiting is logged', () async {
      await typing();
      controlledNow = controlledNow!.add(const Duration(seconds: 16));
      session.transportLost();

      expect(slow(), [
        'terminal input unanswered machine=machine-1 agent=agent-1 stream=$streamId '
            'link=null waitedMs=16000 until=transport_lost',
      ]);
    });
  });

  group('composer', () {
    /// The `message` frames this session put on the wire.
    List<Map<String, dynamic>> messages() => [
      for (final frame in sent)
        if (frame.type == 'message') frame.payload,
    ];

    Future<void> live() async {
      await ready();
      await session.handleBinary(
        output(0, utf8.encode(r'$ '), keyframe: true, cols: 100, rows: 30),
      );
      sent.clear();
    }

    test('drives a turn with the same frame the web client uses', () async {
      await live();

      expect(await session.sendComposerText('run the tests'), isTrue);

      expect(messages(), hasLength(1));
      expect(messages().single['content'], 'run the tests');
      expect(messages().single['agentId'], 'agent-1');
      expect(messages().single['mode'], 'auto');
      // Nothing is typed into the pane: injection is the machine's job, and doing it here is what
      // left a composed line sitting unsent in Codex.
      expect(binarySent, isEmpty);
    });

    test('carries a multi-line body through verbatim', () async {
      await live();

      expect(await session.sendComposerText('first line\nsecond line'), isTrue);

      // No bracketed-paste wrapping of our own — the machine decides how to inject it.
      expect(messages().single['content'], 'first line\nsecond line');
      expect(messages().single['content'], isNot(contains('\x1b[200~')));
    });

    test('drops a trailing newline so it cannot double the submit', () async {
      await live();

      expect(await session.sendComposerText('ship it\n'), isTrue);

      expect(messages().single['content'], 'ship it');
    });

    test('forwards Ctrl+C in composed text rather than stripping it', () async {
      await live();

      expect(await session.sendComposerText('a\x03b'), isTrue);

      expect(messages().single['content'], 'a\x03b');
    });

    test('sends nothing while the stream is not accepting input', () async {
      expect(session.acceptsInput, isFalse);
      expect(await session.sendComposerText('should not go'), isFalse);
      expect(messages(), isEmpty);
    });

    test('sends nothing for a body that is only whitespace', () async {
      await live();

      expect(await session.sendComposerText(''), isFalse);
      expect(await session.sendComposerText('   \n  '), isFalse);
      expect(messages(), isEmpty);
    });
  });

  group('pasteText', () {
    /// The `TerminalBinaryKind.paste` frames this session put on the wire.
    List<TerminalBinaryFrame> pastes() => [
      for (final frame in binarySent)
        if (frame.kind == TerminalBinaryKind.paste) frame,
    ];

    Future<void> live() async {
      await ready();
      await session.handleBinary(
        output(0, utf8.encode(r'$ '), keyframe: true, cols: 100, rows: 30),
      );
      sent.clear();
      binarySent.clear();
    }

    test(
      'sends the whole clipboard as one binary frame, not chunked',
      () async {
        await live();
        final big = List.generate(200, (i) => 'line $i').join('\n');

        expect(await session.pasteText(big), isTrue);

        expect(pastes(), hasLength(1));
        expect(utf8.decode(pastes().single.bytes), big);
        expect(pastes().single.streamId, streamId);
        expect(pastes().single.compressed, isFalse);
        // Never through the ordinary keystroke pipeline this feature exists to avoid, and never as JSON.
        expect(
          binarySent.where((f) => f.kind == TerminalBinaryKind.input),
          isEmpty,
        );
        expect(sent, isEmpty);
      },
    );

    test('forwards Ctrl+C in a paste rather than stripping it', () async {
      await live();

      expect(await session.pasteText('a\x03b'), isTrue);

      expect(utf8.decode(pastes().single.bytes), 'a\x03b');
    });

    test('sends nothing while the stream is not accepting input', () async {
      expect(session.acceptsInput, isFalse);
      expect(await session.pasteText('should not go'), isFalse);
      expect(pastes(), isEmpty);
    });

    test('sends nothing for an empty paste', () async {
      await live();

      expect(await session.pasteText(''), isFalse);
      expect(pastes(), isEmpty);
    });

    test('a rejected paste (too large/empty) leaves the stream alive, unlike every other terminal_error', () async {
      await live();

      final handled = await session.handleFrame('terminal_error', {
        'streamId': streamId,
        'code': 'TERMINAL_PASTE_INVALID',
        'message': 'paste too large',
      });

      expect(handled, isTrue);
      expect(session.status, TerminalSessionStatus.controlling);
      expect(session.streamId, streamId);
      expect(session.errorCode, isNull);
    });

    test('a real paste delivery failure still freezes the stream, like resize/input failures do', () async {
      await live();

      await session.handleFrame('terminal_error', {
        'streamId': streamId,
        'code': 'TERMINAL_PASTE_FAILED',
        'message': 'tmux paste-buffer could not be sent',
      });

      expect(session.status, TerminalSessionStatus.error);
      expect(session.errorCode, 'TERMINAL_PASTE_FAILED');
    });
  });

  group('pasteImage / pasteFile — chunked upload', () {
    List<TerminalBinaryFrame> imagePastes() => [
      for (final frame in binarySent)
        if (frame.kind == TerminalBinaryKind.imagePaste) frame,
    ];
    List<TerminalBinaryFrame> filePastes() => [
      for (final frame in binarySent)
        if (frame.kind == TerminalBinaryKind.pasteFile) frame,
    ];

    Future<void> live() async {
      await ready();
      await session.handleBinary(
        output(0, utf8.encode(r'$ '), keyframe: true, cols: 100, rows: 30),
      );
      sent.clear();
      binarySent.clear();
    }

    /// Lets the microtasks/event-loop turns between `session.pasteImage`/`pasteFile`'s internal
    /// awaits (send → await begin_result → send chunks → await the result frame) actually run,
    /// so the test can inject the simulated server replies in between.
    Future<void> pump() => Future<void>.delayed(Duration.zero);

    Future<void> acceptBegin() async {
      await pump();
      expect(
        sent
            .where((frame) => frame.type == 'terminal_chunked_upload_begin')
            .single
            .type,
        'terminal_chunked_upload_begin',
      );
      await session.handleFrame('terminal_chunked_upload_begin_result', {
        'streamId': streamId,
        'accepted': true,
      });
    }

    test(
      'image: begin → one chunk → result, and reports live progress',
      () async {
        await live();
        final png = Uint8List.fromList(const [
          0x89,
          0x50,
          0x4e,
          0x47,
          0x0d,
          0x0a,
          0x1a,
          0x0a,
          0xff,
        ]);

        final future = session.pasteImage(png);
        await acceptBegin();
        expect(
          sent
              .where((frame) => frame.type == 'terminal_chunked_upload_begin')
              .single
              .payload,
          containsPair('uploadKind', 'image'),
        );
        expect(
          sent
              .where((frame) => frame.type == 'terminal_chunked_upload_begin')
              .single
              .payload,
          containsPair('totalBytes', png.length),
        );
        expect(
          sent
              .where((frame) => frame.type == 'terminal_chunked_upload_begin')
              .single
              .payload,
          isNot(contains('filename')),
        );

        await pump();
        expect(imagePastes(), hasLength(1));
        expect(imagePastes().single.bytes, png);
        expect(imagePastes().single.seq, 0);
        expect(imagePastes().single.compressed, isFalse);
        // Never through the ordinary keystroke pipeline or the text-paste kind.
        expect(
          binarySent.where((f) => f.kind == TerminalBinaryKind.input),
          isEmpty,
        );
        expect(
          binarySent.where((f) => f.kind == TerminalBinaryKind.paste),
          isEmpty,
        );

        expect(session.uploadProgress, isNotNull);
        await session.handleFrame('terminal_chunked_upload_progress', {
          'streamId': streamId,
          'bytesWritten': png.length,
          'totalBytes': png.length,
        });
        expect(session.uploadProgress!.percent, 1.0);

        await session.handleFrame('terminal_paste_image_result', {
          'streamId': streamId,
          'outcome': 'clipboard',
        });
        expect(await future, isTrue);
        expect(session.uploadProgress, isNull); // cleared once finished
      },
    );

    test(
      'file: begin carries the filename, and the result frame finishes it',
      () async {
        await live();
        final content = Uint8List.fromList(const [0x25, 0x50, 0x44, 0x46]);

        final future = session.pasteFile('report.pdf', content);
        await acceptBegin();
        expect(
          sent
              .where((frame) => frame.type == 'terminal_chunked_upload_begin')
              .single
              .payload,
          containsPair('uploadKind', 'file'),
        );
        expect(
          sent
              .where((frame) => frame.type == 'terminal_chunked_upload_begin')
              .single
              .payload,
          containsPair('filename', 'report.pdf'),
        );

        await pump();
        expect(filePastes(), hasLength(1));
        expect(filePastes().single.bytes, content);

        await session.handleFrame('terminal_paste_file_result', {
          'streamId': streamId,
          'path': '/remote/path/report.pdf',
        });
        expect(await future, isTrue);
      },
    );

    test(
      'splits a large image across several chunks, indexed by seq',
      () async {
        await live();
        final big = Uint8List(terminalUploadChunkBytes * 2 + 100)
          ..fillRange(0, terminalUploadChunkBytes * 2 + 100, 0xab);

        final future = session.pasteImage(big);
        await acceptBegin();
        await pump();

        expect(imagePastes(), hasLength(3));
        expect(imagePastes().map((f) => f.seq), [0, 1, 2]);
        expect(imagePastes()[0].bytes, hasLength(terminalUploadChunkBytes));
        expect(imagePastes()[1].bytes, hasLength(terminalUploadChunkBytes));
        expect(imagePastes()[2].bytes, hasLength(100));

        await session.handleFrame('terminal_paste_image_result', {
          'streamId': streamId,
          'outcome': 'clipboard',
        });
        expect(await future, isTrue);
      },
    );

    test(
      'resolves false, with no chunks sent, when begin is not accepted',
      () async {
        await live();
        final png = Uint8List.fromList(const [1, 2, 3]);

        final future = session.pasteImage(png);
        await pump();
        await session.handleFrame('terminal_chunked_upload_begin_result', {
          'streamId': streamId,
          'accepted': false,
          'reason': 'exceeds the 8 MB limit',
        });

        expect(await future, isFalse);
        expect(imagePastes(), isEmpty);
        expect(session.uploadProgress, isNull);
        expect(session.acceptsInput, isTrue);
        expect(sent.where((frame) => frame.type == 'terminal_open'), isEmpty);
        expect(
          sent.where((frame) => frame.type == 'terminal_chunked_upload_cancel'),
          isEmpty,
        );
      },
    );

    test('cancels an upload the daemon still holds for this pane, then begins again', () async {
      await live();
      final png = Uint8List.fromList(const [1, 2, 3]);

      final future = session.pasteImage(png);
      await pump();
      await session.handleFrame('terminal_chunked_upload_begin_result', {
        'streamId': streamId,
        'accepted': false,
        'reason': 'an upload is already in progress on this pane',
      });
      await pump();
      expect(sent.map((frame) => frame.type), [
        'terminal_chunked_upload_begin',
        'terminal_chunked_upload_cancel',
        'terminal_chunked_upload_begin',
      ]);
      expect(imagePastes(), isEmpty);

      await session.handleFrame('terminal_chunked_upload_begin_result', {
        'streamId': streamId,
        'accepted': true,
      });
      await pump();
      expect(imagePastes().single.bytes, png);
      await session.handleFrame('terminal_paste_image_result', {
        'streamId': streamId,
        'outcome': 'clipboard',
      });
      expect(await future, isTrue);
    });

    test(
      'asks only once more when the daemon still says an upload is in progress',
      () async {
        await live();
        final future = session.pasteImage(Uint8List.fromList(const [1]));
        for (var answer = 0; answer < 2; answer++) {
          await pump();
          await session.handleFrame('terminal_chunked_upload_begin_result', {
            'streamId': streamId,
            'accepted': false,
            'reason': 'an upload is already in progress on this pane',
          });
        }
        expect(await future, isFalse);
        expect(
          sent.where((frame) => frame.type == 'terminal_chunked_upload_begin'),
          hasLength(2),
        );
        expect(imagePastes(), isEmpty);
        expect(session.uploadProgress, isNull);
      },
    );

    test('cancels on the daemon a begin it never answered', () {
      fakeAsync((async) {
        live();
        async.flushMicrotasks();
        bool? result;
        session
            .pasteImage(Uint8List.fromList(const [1, 2, 3]))
            .then((value) => result = value);
        async.flushMicrotasks();
        expect(
          sent.where((frame) => frame.type == 'terminal_chunked_upload_begin'),
          hasLength(1),
        );

        async.elapse(const Duration(seconds: 9));
        expect(result, isNull);
        async.elapse(const Duration(seconds: 2));
        expect(result, isFalse);
        expect(
          sent
              .where((frame) => frame.type == 'terminal_chunked_upload_cancel')
              .single
              .payload['streamId'],
          streamId,
        );
        expect(session.uploadProgress, isNull);
        expect(imagePastes(), isEmpty);
      });
    });

    test('keeps at most the window of unconfirmed bytes on the way', () async {
      await live();
      final chunks = terminalUploadWindowBytes ~/ terminalUploadChunkBytes;
      final big = Uint8List(terminalUploadChunkBytes * (chunks + 2) + 10);

      final future = session.pasteImage(big);
      await acceptBegin();
      await pump();
      expect(imagePastes(), hasLength(chunks));

      Future<void> confirm(int bytes) async {
        await session.handleFrame('terminal_chunked_upload_progress', {
          'streamId': streamId,
          'bytesWritten': bytes,
          'totalBytes': big.length,
        });
        await pump();
      }

      await confirm(terminalUploadChunkBytes);
      expect(imagePastes(), hasLength(chunks + 1));
      // A repeated or older figure makes no room.
      await confirm(terminalUploadChunkBytes);
      expect(imagePastes(), hasLength(chunks + 1));
      await confirm(terminalUploadChunkBytes * 3);
      expect(imagePastes().map((frame) => frame.seq), [
        for (var seq = 0; seq < chunks + 3; seq++) seq,
      ]);
      expect(imagePastes().last.bytes, hasLength(10));

      await confirm(big.length);
      await session.handleFrame('terminal_paste_image_result', {
        'streamId': streamId,
        'outcome': 'clipboard',
      });
      expect(await future, isTrue);
      expect(
        sent.where((frame) => frame.type == 'terminal_chunked_upload_cancel'),
        isEmpty,
      );
    });

    for (final waitingForRoom in [true, false]) {
      test('gives up an upload the daemon stops confirming, here and on the daemon '
          '(waiting for room in the window: $waitingForRoom)', () async {
        session.dispose();
        session = TerminalSession(
          machineId: 'machine-1',
          agentId: 'agent-1',
          agentName: 'backend-api',
          engineId: 'codex',
          uploadStallTimeout: const Duration(milliseconds: 50),
          send: (type, payload) async {
            sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
            return true;
          },
          sendBinary: (frame) async {
            binarySent.add(frame);
            return true;
          },
        );
        await live();
        final chunks = waitingForRoom
            ? terminalUploadWindowBytes ~/ terminalUploadChunkBytes + 3
            : 3;
        final image = Uint8List(terminalUploadChunkBytes * chunks);

        final future = session.pasteImage(image);
        await acceptBegin();
        await pump();
        // Part of the image arrives; the rest was lost on the way.
        await session.handleFrame('terminal_chunked_upload_progress', {
          'streamId': streamId,
          'bytesWritten': terminalUploadChunkBytes,
          'totalBytes': image.length,
        });

        expect(await future, isFalse);
        expect(imagePastes(), hasLength(waitingForRoom ? 5 : 3));
        expect(session.uploadProgress, isNull);
        expect(
          session.lastStalledUpload!.bytesWritten,
          terminalUploadChunkBytes,
        );
        expect(sent.last.type, 'terminal_chunked_upload_cancel');
        expect(sent.last.payload['streamId'], streamId);
        // The stream itself is fine: nothing reopens, and the next upload starts at once.
        expect(session.status, TerminalSessionStatus.controlling);
        expect(sent.where((frame) => frame.type == 'terminal_open'), isEmpty);
        unawaited(session.pasteImage(Uint8List.fromList(const [1])));
        await pump();
        expect(sent.last.type, 'terminal_chunked_upload_begin');
        expect(session.lastStalledUpload, isNull);
        await session.cancelUpload();
      });
    }

    for (final coded in [true, false]) {
      test(
        'a missing-stream upload rejection reopens once without replay (coded=$coded)',
        () async {
          await live();
          final retained = session.terminal;
          final uploading = session.pasteImage(Uint8List.fromList([1, 2, 3]));
          await pump();
          final rejection = <String, dynamic>{
            'streamId': streamId,
            'accepted': false,
            if (coded) 'code': 'TERMINAL_STREAM_NOT_FOUND',
            'reason': coded ? 'stream unavailable' : 'no live terminal stream for this pane (reopen it and try again)',
          };
          await session.handleFrame(
            'terminal_chunked_upload_begin_result',
            rejection,
          );
          expect(await uploading, isFalse);
          expect(session.status, TerminalSessionStatus.opening);
          expect(session.terminal, same(retained));
          expect(session.uploadProgress, isNull);
          expect(imagePastes(), isEmpty);
          final opens = sent.where((frame) => frame.type == 'terminal_open');
          expect(opens, hasLength(1));
          expect(opens.single.payload['takeover'], isFalse);
          await session.handleFrame(
            'terminal_chunked_upload_begin_result',
            rejection,
          );
          expect(
            sent.where((frame) => frame.type == 'terminal_open'),
            hasLength(1),
          );
        },
      );
    }

    test(
      'a malformed-chunk error clears the upload without freezing the session',
      () async {
        await live();
        final png = Uint8List.fromList(const [1, 2, 3]);

        final future = session.pasteImage(png);
        await acceptBegin();
        await pump();

        await session.handleFrame('terminal_error', {
          'streamId': streamId,
          'code': 'TERMINAL_CHUNKED_UPLOAD_INVALID',
          'message': 'malformed upload chunk',
        });

        expect(await future, isFalse);
        expect(session.status, TerminalSessionStatus.controlling);
        expect(session.uploadProgress, isNull);
      },
    );

    test('a genuine mid-transfer failure freezes the session, like TERMINAL_PASTE_FAILED does', () async {
      await live();
      final png = Uint8List.fromList(const [1, 2, 3]);

      final future = session.pasteImage(png);
      await acceptBegin();
      await pump();

      await session.handleFrame('terminal_error', {
        'streamId': streamId,
        'code': 'TERMINAL_PASTE_IMAGE_FAILED',
        'message': 'xclip exited with code 1',
      });

      expect(await future, isFalse);
      expect(session.status, TerminalSessionStatus.error);
      expect(session.errorCode, 'TERMINAL_PASTE_IMAGE_FAILED');
      expect(session.uploadProgress, isNull);
    });

    test(
      'cancelUpload before the daemon answers the begin settles it at once',
      () {
        fakeAsync((async) {
          live();
          async.flushMicrotasks();
          bool? result;
          session
              .pasteImage(Uint8List.fromList(const [1, 2, 3]))
              .then((value) => result = value);
          async.flushMicrotasks();

          session.cancelUpload();
          async.flushMicrotasks();

          expect(result, isFalse);
          expect(
            sent.where(
              (frame) => frame.type == 'terminal_chunked_upload_cancel',
            ),
            hasLength(1),
          );
        });
      },
    );

    test('cancelUpload stops the transfer and tells the daemon', () async {
      await live();
      final png = Uint8List.fromList(const [1, 2, 3]);

      final future = session.pasteImage(png);
      await acceptBegin();
      await pump();
      expect(session.uploadProgress, isNotNull);

      await session.cancelUpload();
      expect(await future, isFalse);
      expect(session.uploadProgress, isNull);
      expect(sent.last, isA<Object>());
      expect(sent.last.type, 'terminal_chunked_upload_cancel');
      expect(sent.last.payload['streamId'], streamId);
    });

    test(
      'rejects a second upload while one is already in flight on this session',
      () async {
        await live();
        final png = Uint8List.fromList(const [1, 2, 3]);

        final first = session.pasteImage(png);
        await acceptBegin();
        await pump();

        expect(
          await session.pasteFile('a.txt', Uint8List.fromList(const [1])),
          isFalse,
        );

        await session.handleFrame('terminal_paste_image_result', {
          'streamId': streamId,
          'outcome': 'clipboard',
        });
        expect(await first, isTrue);
      },
    );

    test('sends nothing while the stream is not accepting input', () async {
      expect(session.acceptsInput, isFalse);
      expect(
        await session.pasteImage(Uint8List.fromList(const [1, 2, 3])),
        isFalse,
      );
      expect(
        await session.pasteFile('a.txt', Uint8List.fromList(const [1])),
        isFalse,
      );
      expect(imagePastes(), isEmpty);
      expect(filePastes(), isEmpty);
    });

    test(
      'sends nothing for an empty image or an empty filename/content',
      () async {
        await live();

        expect(await session.pasteImage(Uint8List(0)), isFalse);
        expect(
          await session.pasteFile('', Uint8List.fromList(const [1])),
          isFalse,
        );
        expect(await session.pasteFile('a.txt', Uint8List(0)), isFalse);
        expect(imagePastes(), isEmpty);
        expect(filePastes(), isEmpty);
        expect(sent, isEmpty);
      },
    );
  });
  test('xterm learns the desktop it runs on', () {
    addTearDown(() => debugDefaultTargetPlatformOverride = null);
    for (final (platform, expected) in [
      (TargetPlatform.macOS, TerminalTargetPlatform.macos),
      (TargetPlatform.linux, TerminalTargetPlatform.linux),
      (TargetPlatform.windows, TerminalTargetPlatform.windows),
    ]) {
      debugDefaultTargetPlatformOverride = platform;
      final local = TerminalSession(
        machineId: 'm',
        agentId: 'a',
        agentName: 'a',
        engineId: 'codex',
        send: (type, payload) async => true,
        sendBinary: (frame) async => true,
      );
      expect(local.terminal.platform, expected, reason: '$platform');
      local.dispose();
    }
  });
}

class _RecordingLog implements AppLog {
  final lines = <String>[];
  @override
  void record(
    AppLogLevel level,
    String category,
    String message, {
    Object? error,
    StackTrace? stackTrace,
  }) => lines.add('$category $message');
}