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.

71.8 KB
Raw Blame
import 'dart:convert';
import 'dart:io' show ZLibEncoder;
import 'dart:typed_data';

import 'package:fake_async/fake_async.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness_mobile/terminal/terminal_binary.dart';
import 'package:harness_mobile/terminal/terminal_session.dart';
import 'package:harness_mobile/terminal/terminal_viewport.dart';
import 'package:xterm/xterm.dart' show Terminal;

/// The terminal stream protocol a phone speaks with a machine's daemon, frame
/// by frame: an open and its answer, a screen and the output after it, gaps
/// and the resync that repairs them, a stream closed or taken, and everything
/// typed, pasted and uploaded back.
void main() {
  late _Wire wire;

  setUp(() => wire = _Wire());

  /// [disposeAtEnd] false for a test that disposes the session itself.
  TerminalSession session({
    String engine = 'claude',
    bool takeover = true,
    Future<bool> Function()? onOpenStalled,
    DateTime? Function()? lastHeardFromMachine,
    bool Function()? onTransportSilent,
    Duration resync = const Duration(milliseconds: 40),
    Duration uploadStall = const Duration(seconds: 30),
    bool disposeAtEnd = true,
  }) {
    final built = TerminalSession(
      machineId: 'm',
      agentId: 'a',
      agentName: 'a',
      engineId: engine,
      send: wire.send,
      sendBinary: wire.sendBinary,
      client: const TerminalClientDescriptor(kind: 'phone', name: 'Pat'),
      onOpenStalled: onOpenStalled,
      lastHeardFromMachine: lastHeardFromMachine,
      onTransportSilent: onTransportSilent,
      resyncTimeout: resync,
      uploadStallTimeout: uploadStall,
      takeover: takeover,
    );
    if (disposeAtEnd) addTearDown(built.dispose);
    return built;
  }

  /// Real time passing until [done], in small steps — for a ladder of timers
  /// whose exact rungs a test wants to stop between.
  Future<void> until(bool Function() done) async {
    for (var i = 0; i < 200 && !done(); i++) {
      await Future<void>.delayed(const Duration(milliseconds: 2));
    }
    expect(done(), isTrue, reason: 'never got there');
  }

  /// The daemon answering the last open: a stream id.
  Future<String> ready(
    TerminalSession s, {
    bool readOnly = false,
    Map<String, dynamic>? heldBy,
  }) async {
    final streamId = _streamId();
    await s.handleFrame('terminal_ready', {
      'requestId': wire.last('terminal_open')['requestId'],
      'agentId': 'a',
      'protocolVersion': TerminalSession.protocolVersion,
      'streamId': streamId,
      if (readOnly) 'readOnly': true,
      'heldBy': ?heldBy,
    });
    return streamId;
  }

  /// A session with a stream and its first screen.
  Future<(TerminalSession, String)> live({
    String engine = 'claude',
    String screen = 'prompt> ',
    Duration resync = const Duration(milliseconds: 40),
    Duration uploadStall = const Duration(seconds: 30),
  }) async {
    final s = session(engine: engine, resync: resync, uploadStall: uploadStall);
    await s.open();
    final streamId = await ready(s);
    await s.handleBinary(_keyframe(streamId, text: screen));
    return (s, streamId);
  }

  group('the open', () {
    test(
      'asks for the agent at a size the daemon will accept, and says who asks',
      () async {
        final s = session();

        await s.open(initialCols: 10, initialRows: 500);

        final open = wire.last('terminal_open');
        expect(open['protocolVersion'], TerminalSession.protocolVersion);
        expect(open['agentId'], 'a');
        expect(open['cols'], TerminalSession.minCols);
        expect(open['rows'], TerminalSession.maxRows);
        expect(open['compression'], ['zlib', 'none']);
        expect(open['client'], {'kind': 'phone', 'name': 'Pat'});
        expect(open.containsKey('takeover'), isFalse);
        expect(s.status, TerminalSessionStatus.opening);
        expect(s.holdsTerminal, isTrue);
        expect(s.hasRenderedFrame, isFalse);
      },
    );

    test('a polite open says so', () async {
      final s = session(takeover: false);

      await s.open();

      expect(wire.last('terminal_open')['takeover'], isFalse);
    });

    test('waits for the panel\'s own measurement', () async {
      final s = session();

      final opening = s.open(waitForViewportSize: true);
      await Future<void>.delayed(Duration.zero);
      expect(wire.of('terminal_open'), isEmpty);
      s.reportViewport(120, 40);
      s.reportViewport(10, 10);
      await opening;

      expect(wire.last('terminal_open')['cols'], 120);
      expect(wire.last('terminal_open')['rows'], 40);
    });

    test('opens at the fallback size when the panel never measures', () {
      fakeAsync((async) {
        final s = session(disposeAtEnd: false);
        s.open(waitForViewportSize: true);
        async.elapse(const Duration(seconds: 3));

        expect(wire.last('terminal_open')['cols'], 80);
        expect(wire.last('terminal_open')['rows'], 24);
        s.dispose();
      });
    });

    test(
      'an open that cannot be sent, with nothing to recover it, fails',
      () async {
        wire.sends = false;
        final s = session();

        await s.open();

        expect(s.status, TerminalSessionStatus.error);
        expect(s.errorMessage, 'Could not send terminal_open');
      },
    );

    test(
      'an open that cannot be sent redials once and sends it again',
      () async {
        var redials = 0;
        final s = session(
          onOpenStalled: () async {
            redials++;
            wire.sends = true;
            return true;
          },
        );
        wire.sends = false;

        await s.open();

        expect(redials, 1);
        expect(s.status, TerminalSessionStatus.opening);
        expect(wire.of('terminal_open'), hasLength(2));
        expect(
          wire.of('terminal_open').last['requestId'],
          wire.of('terminal_open').first['requestId'],
        );
      },
    );

    test('a redial that throws still started one, and is polled', () async {
      final s = session(
        onOpenStalled: () async {
          wire.sends = true;
          throw StateError('socket closed mid-redial');
        },
      );
      wire.sends = false;

      await s.open();

      expect(s.status, TerminalSessionStatus.opening);
    });

    test(
      'a transport that declines the redial keeps its one recovery',
      () async {
        var asked = 0;
        final s = session(
          onOpenStalled: () async {
            asked++;
            return false;
          },
        );
        wire.sends = false;

        await s.open();
        expect(s.status, TerminalSessionStatus.error);

        // Declined, so not spent: the next open that stalls may still redial.
        await s.reopen();
        expect(asked, 2);
      },
    );

    // On the fake clock, like the test below: on the real one a 20ms resync and a 120ms wait
    // raced a loaded machine, and the resend landed after the check in one full run of several.
    test('silence after the open redials, resends, then gives up', () {
      fakeAsync((async) {
        var redials = 0;
        final s = session(
          disposeAtEnd: false,
          onOpenStalled: () async {
            redials++;
            return true;
          },
          resync: const Duration(milliseconds: 20),
        );

        s.open();
        async.flushMicrotasks();
        async.elapse(const Duration(milliseconds: 120));

        expect(redials, 1, reason: 'one forced redial per open');
        expect(wire.of('terminal_open').length, greaterThanOrEqualTo(2));
        expect(s.status, TerminalSessionStatus.error);
        expect(s.errorCode, 'TERMINAL_RESYNC_TIMEOUT');
        expect(s.errorMessage, contains('did not respond'));
        s.dispose();
      });
    });

    test('a resend that cannot be sent either gives up at once', () {
      fakeAsync((async) {
        final s = session(
          disposeAtEnd: false,
          onOpenStalled: () async {
            wire.sends = false;
            return true;
          },
        );
        s.open();
        async.flushMicrotasks();
        async.elapse(const Duration(seconds: 5));

        expect(s.status, TerminalSessionStatus.error);
        expect(s.errorCode, 'TERMINAL_RESYNC_TIMEOUT');
        s.dispose();
      });
    });
  });

  group('terminal_ready', () {
    test(
      'an answer to another open, agent or protocol is not this one\'s',
      () async {
        final s = session();
        await s.open();
        final requestId = wire.last('terminal_open')['requestId'];

        for (final payload in [
          {'requestId': 'other', 'agentId': 'a', 'protocolVersion': 3},
          {'requestId': requestId, 'agentId': 'b', 'protocolVersion': 3},
          {'requestId': requestId, 'agentId': 'a', 'protocolVersion': 2},
        ]) {
          expect(
            await s.handleFrame('terminal_ready', {
              ...payload,
              'streamId': _streamId(),
            }),
            isTrue,
          );
        }

        expect(s.streamId, isNull);
        expect(s.status, TerminalSessionStatus.opening);
      },
    );

    test('a ready with no stream is a failure', () async {
      final s = session();
      await s.open();

      await s.handleFrame('terminal_ready', {
        'requestId': wire.last('terminal_open')['requestId'],
        'agentId': 'a',
        'protocolVersion': TerminalSession.protocolVersion,
      });

      expect(s.status, TerminalSessionStatus.error);
      expect(s.errorCode, 'TERMINAL_READY_INVALID');
    });

    test('an answered takeover is spent', () async {
      final s = session();
      await s.open();
      expect(s.takeover, isTrue);

      await ready(s);

      expect(s.takeover, isFalse);
    });

    test(
      'a read-only answer watches, names the holder and types nothing',
      () async {
        final s = session();
        await s.open();

        final streamId = await ready(
          s,
          readOnly: true,
          heldBy: {'kind': 'desktop', 'name': 'Studio'},
        );
        await s.handleBinary(_keyframe(streamId));
        s.terminal.textInput('x');
        await Future<void>.delayed(Duration.zero);

        expect(s.watching, isTrue);
        expect(s.heldBy?.name, 'Studio');
        expect(
          s.takeover,
          isTrue,
          reason: 'nothing was won, so nothing is spent',
        );
        expect(s.acceptsInput, isFalse);
        expect(wire.binaries, isEmpty);
      },
    );

    test(
      'a second answer to the same open leaves one heartbeat, and none after',
      () {
        fakeAsync((async) {
          final s = session(disposeAtEnd: false);
          s.open();
          async.flushMicrotasks();
          final requestId = wire.last('terminal_open')['requestId'];
          Map<String, dynamic> answer(String streamId) => {
            'requestId': requestId,
            'agentId': 'a',
            'protocolVersion': TerminalSession.protocolVersion,
            'streamId': streamId,
          };
          // The original reply, late, and the reply to the SAME open resent
          // after the watchdog gave up on it — both match, and both land before
          // the first screen.
          s.handleFrame('terminal_ready', answer(_streamId()));
          final second = _streamId();
          s.handleFrame('terminal_ready', answer(second));
          s.handleBinary(_keyframe(second));
          async.flushMicrotasks();

          async.elapse(const Duration(seconds: 5));
          expect(wire.of('terminal_alive'), hasLength(1));

          s.dispose();
          async.elapse(const Duration(seconds: 20));
          expect(
            wire.of('terminal_alive'),
            hasLength(1),
            reason: 'a disposed session sends nothing',
          );
        });
      },
    );

    test(
      'heartbeats and resyncs ask the daemon to report a stream it no longer has',
      () {
        fakeAsync((async) {
          final s = session(
            disposeAtEnd: false,
            resync: const Duration(seconds: 30),
          );
          s.open();
          async.flushMicrotasks();
          final streamId = _streamId();
          s.handleFrame('terminal_ready', {
            'requestId': wire.last('terminal_open')['requestId'],
            'agentId': 'a',
            'protocolVersion': TerminalSession.protocolVersion,
            'streamId': streamId,
          });
          s.handleBinary(_keyframe(streamId));
          async.flushMicrotasks();

          async.elapse(const Duration(seconds: 5));
          expect(wire.last('terminal_alive'), {
            'streamId': streamId,
            'reportMissing': true,
          });

          s.handleBinary(_output(streamId, 2, 'gap'));
          async.flushMicrotasks();
          expect(wire.last('terminal_resync')['reportMissing'], isTrue);
          s.dispose();
        });
      },
    );

    test('a stream the daemon no longer has is reopened in place at once', () async {
      final s = session();
      final opening = s.open();
      final streamId = await ready(s);
      await opening;
      await s.handleBinary(_keyframe(streamId));

      await s.handleFrame('terminal_error', {
        'streamId': streamId,
        'code': 'TERMINAL_STREAM_NOT_FOUND',
      });
      await until(() => wire.of('terminal_open').length == 2);

      expect(s.status, TerminalSessionStatus.opening);
    });

    test('a missing-stream report about another stream is ignored', () async {
      final s = session();
      final opening = s.open();
      await ready(s);
      await opening;

      await s.handleFrame('terminal_error', {
        'streamId': _streamId(),
        'code': 'TERMINAL_STREAM_NOT_FOUND',
      });

      expect(wire.of('terminal_open'), hasLength(1));
      expect(s.status, isNot(TerminalSessionStatus.error));
    });

    test(
      'heartbeats keep a live stream alive, and a failed one is a lost stream',
      () {
        fakeAsync((async) {
          final s = session(disposeAtEnd: false);
          s.open();
          async.flushMicrotasks();
          s.handleFrame('terminal_ready', {
            'requestId': wire.last('terminal_open')['requestId'],
            'agentId': 'a',
            'protocolVersion': TerminalSession.protocolVersion,
            'streamId': _streamId(),
          });
          s.handleBinary(_keyframe(s.streamId!));
          async.flushMicrotasks();

          async.elapse(const Duration(seconds: 10));
          expect(wire.of('terminal_alive'), hasLength(2));

          wire.sends = false;
          async.elapse(const Duration(seconds: 5));
          expect(s.status, TerminalSessionStatus.error);
          expect(s.errorMessage, 'Terminal heartbeat was not sent');
          s.dispose();
        });
      },
    );

    /// An open answered, its first screen drawn, on [async]'s clock — a stream the session holds.
    String liveOn(
      FakeAsync async,
      TerminalSession s, {
      bool readOnly = false,
    }) {
      s.open();
      async.flushMicrotasks();
      final streamId = _streamId();
      s.handleFrame('terminal_ready', {
        'requestId': wire.last('terminal_open')['requestId'],
        'agentId': 'a',
        'protocolVersion': TerminalSession.protocolVersion,
        'streamId': streamId,
        if (readOnly) 'readOnly': true,
      });
      s.handleBinary(_keyframe(streamId));
      async.flushMicrotasks();
      return streamId;
    }

    // A socket left half-open (Wi-Fi giving way to 4G while the app was away) takes every send and
    // brings nothing back: the heartbeat goes out, and the terminal looked live while taking no
    // input for minutes. The daemon sends a sync frame every five seconds, so silence is the sign.
    test(
      'a stream quiet for 15s is resynced, and reopened once the resync '
      'gets no answer',
      () {
        fakeAsync((async) {
          final s = session(disposeAtEnd: false);
          final streamId = liveOn(async, s);

          // Three beats that heard nothing: the last frame may have landed just before the first.
          async.elapse(const Duration(seconds: 15));
          expect(wire.of('terminal_resync'), isEmpty);
          expect(s.acceptsInput, isTrue);

          // The fourth: at least fifteen seconds without the sync the daemon sends every five.
          async.elapse(const Duration(seconds: 5));
          expect(s.status, TerminalSessionStatus.resyncing);
          expect(s.errorCode, 'TERMINAL_STREAM_TIMEOUT');
          expect(wire.of('terminal_resync'), hasLength(1));

          // Unanswered: two more tries, then the stream is opened again and the old one closed.
          final opens = wire.of('terminal_open').length;
          async.elapse(const Duration(milliseconds: 200));
          expect(wire.of('terminal_resync'), hasLength(3));
          expect(wire.of('terminal_open'), hasLength(opens + 1));
          expect(wire.last('terminal_close')['streamId'], streamId);
          s.dispose();
        });
      },
    );

    test('the sync frames an idle stream sends keep it from a resync', () {
      fakeAsync((async) {
        final s = session(disposeAtEnd: false);
        final streamId = liveOn(async, s);

        for (var seq = 1; seq <= 12; seq++) {
          async.elapse(const Duration(seconds: 5));
          s.handleBinary(_sync(streamId, seq));
          async.flushMicrotasks();
        }

        expect(wire.of('terminal_alive'), hasLength(12));
        expect(wire.of('terminal_resync'), isEmpty);
        expect(s.acceptsInput, isTrue);
        s.dispose();
      });
    });

    test('a terminal only watched is not resynced for being quiet', () {
      fakeAsync((async) {
        final s = session(disposeAtEnd: false);
        liveOn(async, s, readOnly: true);

        async.elapse(const Duration(seconds: 60));

        expect(s.watching, isTrue);
        expect(wire.of('terminal_resync'), isEmpty);
        s.dispose();
      });
    });

    // The socket heard nothing from the machine for as long as the stream was quiet: the socket is
    // what died (a half-open line after a network switch), and a resync over it would only wait
    // out three unanswered tries and an open's patience before anything redialled.
    group('quiet on a socket that is quiet too', () {
      /// The socket's last word from the machine, [heard], as the hook reports it; and every call
      /// of the redial hook, answered [redials].
      ({TerminalSession s, List<void> asked}) quietOn(
        FakeAsync async, {
        required DateTime? heard,
        bool redials = true,
        bool hook = true,
      }) {
        final asked = <void>[];
        final s = session(
          disposeAtEnd: false,
          lastHeardFromMachine: () => heard,
          onTransportSilent: hook
              ? () {
                  asked.add(null);
                  return redials;
                }
              : null,
        );
        liveOn(async, s);
        return (s: s, asked: asked);
      }

      test('the socket is dialled again at once, the stream not resynced', () {
        fakeAsync((async) {
          final (:s, :asked) = quietOn(async, heard: DateTime(2000));

          async.elapse(const Duration(seconds: 15));
          expect(asked, isEmpty, reason: 'three beats are not yet a silence');

          async.elapse(const Duration(seconds: 5));
          expect(asked, hasLength(1));
          expect(wire.of('terminal_resync'), isEmpty);
          s.dispose();
        });
      });

      test('a socket that still hears the machine leaves the repair to the '
          'stream: resynced, nothing redialled', () {
        fakeAsync((async) {
          // Heard after this stream's last frame: another agent's output, a reply.
          final (:s, :asked) = quietOn(
            async,
            heard: DateTime.now().add(const Duration(hours: 1)),
          );

          async.elapse(const Duration(seconds: 20));

          expect(asked, isEmpty);
          expect(s.errorCode, 'TERMINAL_STREAM_TIMEOUT');
          expect(wire.of('terminal_resync'), hasLength(1));
          s.dispose();
        });
      });

      test('a redial the app declines leaves the stream to its resync', () {
        fakeAsync((async) {
          final (:s, :asked) = quietOn(
            async,
            heard: DateTime(2000),
            redials: false,
          );

          async.elapse(const Duration(seconds: 20));

          expect(asked, hasLength(1));
          expect(wire.of('terminal_resync'), hasLength(1));
          s.dispose();
        });
      });

      test('a socket that never heard the machine is no proof: resynced', () {
        fakeAsync((async) {
          final (:s, :asked) = quietOn(async, heard: null);

          async.elapse(const Duration(seconds: 20));

          expect(asked, isEmpty);
          expect(wire.of('terminal_resync'), hasLength(1));
          s.dispose();
        });
      });

      test('with no redial hook, the stream is resynced as before', () {
        fakeAsync((async) {
          final (:s, asked: _) = quietOn(
            async,
            heard: DateTime(2000),
            hook: false,
          );

          async.elapse(const Duration(seconds: 20));

          expect(wire.of('terminal_resync'), hasLength(1));
          s.dispose();
        });
      });

      test('a redial that took the session down meanwhile is not followed by '
          'a resync over its "Connection lost"', () {
        fakeAsync((async) {
          late TerminalSession s;
          s = session(
            disposeAtEnd: false,
            lastHeardFromMachine: () => DateTime(2000),
            // Declined for this stream, but another stream of the machine got there first and
            // the app took every session of it down.
            onTransportSilent: () {
              s.transportLost('Connection lost. Reconnecting…');
              return false;
            },
          );
          liveOn(async, s);

          async.elapse(const Duration(seconds: 20));

          expect(wire.of('terminal_resync'), isEmpty);
          expect(s.errorMessage, 'Connection lost. Reconnecting…');
          s.dispose();
        });
      });

      test('the stream heard from again resets it: no redial for a quiet '
          'that ended', () {
        fakeAsync((async) {
          final (:s, :asked) = quietOn(async, heard: DateTime(2000));
          final streamId = s.streamId!;

          async.elapse(const Duration(seconds: 15));
          s.handleBinary(_sync(streamId, 1));
          async.flushMicrotasks();
          async.elapse(const Duration(seconds: 15));

          expect(asked, isEmpty);
          expect(wire.of('terminal_resync'), isEmpty);
          s.dispose();
        });
      });
    });
  });

  group('the screen and the output after it', () {
    test('a keyframe before its stream is ready is dropped, and the watchdog asks again', () async {
      final s = session();
      await s.open();
      final streamId = _streamId();

      // The screen overtakes its own ready.
      await s.handleBinary(_keyframe(streamId));
      expect(s.hasRenderedFrame, isFalse);

      await s.handleFrame('terminal_ready', {
        'requestId': wire.last('terminal_open')['requestId'],
        'agentId': 'a',
        'protocolVersion': TerminalSession.protocolVersion,
        'streamId': streamId,
      });
      await Future<void>.delayed(const Duration(milliseconds: 60));

      expect(s.status, TerminalSessionStatus.resyncing);
      expect(wire.last('terminal_resync'), {
        'streamId': streamId,
        'attempt': 1,
        'reason': 'TERMINAL_KEYFRAME_TIMEOUT',
        'reportMissing': true,
      });

      await s.handleBinary(_keyframe(streamId, seq: 5));
      expect(s.status, TerminalSessionStatus.controlling);
      expect(s.hasRenderedFrame, isTrue);
    });

    test('a frame for another stream is not drawn', () async {
      final (s, _) = await live();
      final ticks = s.outputTicks.value;

      await s.handleBinary(_output(_streamId(), 1, 'stray'));

      expect(s.outputTicks.value, ticks);
      expect(s.status, TerminalSessionStatus.controlling);
    });

    test('output in order is drawn and acknowledged', () async {
      final (s, streamId) = await live();

      await s.handleBinary(_output(streamId, 1, 'hello '));
      await s.handleBinary(_output(streamId, 2, 'world'));
      await Future<void>.delayed(const Duration(milliseconds: 40));

      expect(_screen(s), contains('hello world'));
      expect(wire.last('terminal_ack'), {'streamId': streamId, 'lastSeq': 2});
    });

    test('a scalar split across two frames is drawn whole', () async {
      final (s, streamId) = await live(screen: '');
      final bytes = utf8.encode('é');

      await s.handleBinary(
        _output(streamId, 1, null, bytes: bytes.sublist(0, 1)),
      );
      await s.handleBinary(_output(streamId, 2, null, bytes: bytes.sublist(1)));

      expect(_screen(s), contains('é'));
    });

    test(
      'a gap is repaired by a resync, and output meanwhile is dropped',
      () async {
        final (s, streamId) = await live(resync: const Duration(seconds: 5));

        await s.handleBinary(_output(streamId, 3, 'skipped ahead'));
        expect(s.status, TerminalSessionStatus.resyncing);
        expect(s.errorCode, 'TERMINAL_SEQUENCE_GAP');
        expect(wire.last('terminal_resync')['attempt'], 1);
        expect(s.acceptsInput, isFalse);

        await s.handleBinary(_output(streamId, 4, 'more'));
        await s.handleBinary(_sync(streamId, 5));
        expect(_screen(s), isNot(contains('more')));

        await s.handleBinary(_keyframe(streamId, seq: 9, text: 'repaired'));
        expect(s.status, TerminalSessionStatus.controlling);
        expect(s.errorCode, isNull);
        expect(_screen(s), contains('repaired'));

        await s.handleBinary(_output(streamId, 10, ' next'));
        expect(_screen(s), contains('repaired next'));
      },
    );

    test(
      'a sync frame moves the sequence on; one out of order is a gap',
      () async {
        final (s, streamId) = await live(resync: const Duration(seconds: 5));

        await s.handleBinary(_sync(streamId, 1));
        await s.handleBinary(_output(streamId, 2, 'after sync'));
        expect(_screen(s), contains('after sync'));

        await s.handleBinary(_sync(streamId, 9));
        expect(s.status, TerminalSessionStatus.resyncing);
      },
    );

    test('a sync or output before any screen asks for one', () async {
      for (final frame in [
        _sync,
        (String id, int seq) => _output(id, seq, 'x'),
      ]) {
        final s = session(resync: const Duration(seconds: 5));
        await s.open();
        final streamId = await ready(s);

        await s.handleBinary(frame(streamId, 0));

        expect(s.status, TerminalSessionStatus.resyncing);
      }
    });

    test(
      'three unanswered resyncs, then one reopen, then it says so',
      () async {
        final (s, streamId) = await live(
          resync: const Duration(milliseconds: 20),
        );

        await s.handleBinary(_output(streamId, 7, 'gap'));
        await until(() => wire.of('terminal_open').length == 2);

        expect(
          [for (final r in wire.of('terminal_resync')) r['attempt']],
          [1, 2, 3],
        );
        expect(wire.last('terminal_close'), {'streamId': streamId});
        expect(s.status, TerminalSessionStatus.opening);
        expect(
          _screen(s),
          contains('prompt>'),
          reason: 'kept through the reopen',
        );

        // The reopened stream answers, and never draws.
        await ready(s);
        await until(() => s.status == TerminalSessionStatus.error);

        expect(
          s.errorMessage,
          'Terminal did not recover after resync and reopen.',
        );
      },
    );

    test('a reopen nobody answers says the reopen failed', () async {
      final (s, streamId) = await live(
        resync: const Duration(milliseconds: 20),
      );

      await s.handleBinary(_output(streamId, 7, 'gap'));
      await until(() => wire.of('terminal_open').length == 2);
      await until(() => s.status == TerminalSessionStatus.error);

      expect(s.errorCode, 'TERMINAL_RESYNC_TIMEOUT');
      expect(s.errorMessage, 'Terminal did not reopen after resync failed.');
    });

    test('a screen after the reopen resets the ladder', () async {
      final (s, streamId) = await live(
        resync: const Duration(milliseconds: 20),
      );
      await s.handleBinary(_output(streamId, 7, 'gap'));
      await until(() => wire.of('terminal_open').length == 2);

      final second = await ready(s);
      await s.handleBinary(_keyframe(second));
      await s.handleBinary(_output(second, 1, 'fine'));
      expect(s.status, TerminalSessionStatus.controlling);
      expect(_screen(s), contains('fine'));

      // A second gap climbs the whole ladder again, reopen included.
      await s.handleBinary(_output(second, 9, 'gap'));
      await until(() => wire.of('terminal_open').length == 3);
      expect(s.status, TerminalSessionStatus.opening);
    });

    test('a resync that cannot be sent is a lost stream', () async {
      final (s, streamId) = await live();
      wire.sends = false;

      await s.handleBinary(_output(streamId, 5, 'gap'));

      expect(s.status, TerminalSessionStatus.error);
      expect(s.errorMessage, 'Could not request terminal resync');
    });

    test(
      'a compressed screen is inflated; a corrupt one is asked for again',
      () async {
        final s = session(resync: const Duration(seconds: 5));
        await s.open();
        final streamId = await ready(s);

        await s.handleBinary(
          _keyframe(
            streamId,
            bytes: ZLibEncoder().convert(utf8.encode('zipped')),
            compressed: true,
          ),
        );
        expect(_screen(s), contains('zipped'));

        await s.handleBinary(
          _output(streamId, 1, null, bytes: [1, 2, 3], compressed: true),
        );
        expect(s.status, TerminalSessionStatus.resyncing);
        expect(s.errorCode, 'TERMINAL_BINARY_DECODE_FAILED');
      },
    );

    test('a screen with no size is asked for again', () async {
      final s = session(resync: const Duration(seconds: 5));
      await s.open();
      final streamId = await ready(s);

      await s.handleBinary(
        TerminalBinaryFrame(
          kind: TerminalBinaryKind.keyframe,
          streamId: streamId,
          seq: 0,
          bytes: Uint8List(0),
          compressed: false,
        ),
      );

      expect(s.errorCode, 'TERMINAL_KEYFRAME_INVALID');
    });

    test(
      'a renderer that throws is repaired by a resync, not a dead tile',
      () async {
        final (s, _) = await live(resync: const Duration(seconds: 5));

        await s.onRendererFailure();

        expect(s.status, TerminalSessionStatus.resyncing);
        expect(s.errorCode, 'TERMINAL_RENDERER_FAILED');
      },
    );

    test('a resync with no stream to ask on is a failure', () async {
      final s = session();

      await s.onRendererFailure();

      expect(s.status, TerminalSessionStatus.error);
    });

    test('Grok is drawn in the alternate buffer, reset or not', () async {
      for (final screen in ['\x1bcgrok', 'grok']) {
        final (s, _) = await live(engine: 'grok', screen: screen);

        expect(s.terminal.isUsingAltBuffer, isTrue);
        expect(s.scrollViaTmuxCopyMode, isTrue);
      }
    });

    test('bulk data sent as JSON is refused', () async {
      final (s, _) = await live();

      expect(await s.handleFrame('terminal_output', {}), isTrue);

      expect(s.status, TerminalSessionStatus.error);
      expect(s.errorCode, 'TERMINAL_BINARY_REQUIRED');
    });

    test('a kept screen stands in until the first real one', () async {
      final (first, _) = await live(screen: 'last time');
      final s = session();

      s.seedScreen(first.terminal);
      expect(s.showingKeptScreen, isTrue);
      expect(s.hasScreen, isTrue);
      final opening = s.open(waitForViewportSize: true);
      expect(_screen(s), contains('last time'), reason: 'through the open');
      s.reportViewport(100, 30);
      await opening;
      expect(_screen(s), contains('last time'));
      final streamId = await ready(s);
      expect(_screen(s), contains('last time'), reason: 'until a screen lands');
      await s.handleBinary(_keyframe(streamId, text: 'now'));

      expect(s.showingKeptScreen, isFalse);
      expect(_screen(s), contains('now'));
      s.seedScreen(first.terminal);
      expect(s.showingKeptScreen, isFalse, reason: 'too late to stand in');
    });
  });

  group('a stream closed, taken or refused', () {
    test('closed for another stream is not this one\'s', () async {
      final (s, _) = await live();

      await s.handleFrame('terminal_closed', {'streamId': _streamId()});

      expect(s.status, TerminalSessionStatus.controlling);
    });

    test('closed by the machine, with its reason', () async {
      final (s, streamId) = await live();

      await s.handleFrame('terminal_closed', {
        'streamId': streamId,
        'reason': 'pane exited',
      });

      expect(s.status, TerminalSessionStatus.closed);
      expect(s.errorMessage, 'pane exited');
      expect(s.errorCode, isNull);
      expect(s.streamId, isNull);
    });

    test('taken, by someone named or not', () async {
      final (s, streamId) = await live();

      await s.handleFrame('terminal_closed', {
        'streamId': streamId,
        'code': 'TERMINAL_TAKEN_OVER',
      });

      expect(s.status, TerminalSessionStatus.takenOver);
      expect(s.errorMessage, 'Another client connected to this terminal.');
      expect(s.takenOverBy, isNull);
    });

    test('a lost socket does not overwrite a stream someone took', () async {
      final (s, streamId) = await live();
      await s.handleFrame('terminal_closed', {
        'streamId': streamId,
        'code': 'TERMINAL_TAKEN_OVER',
      });

      s.transportLost('gone');
      await s.handleFrame('terminal_transport_error', {'code': 'X'});

      expect(s.status, TerminalSessionStatus.takenOver);
    });

    test('an error about another stream or open is not this one\'s', () async {
      final (s, _) = await live();

      await s.handleFrame('terminal_error', {
        'streamId': _streamId(),
        'code': 'BOOM',
      });
      await s.handleFrame('terminal_error', {
        'requestId': 'other',
        'code': 'BOOM',
      });

      expect(s.status, TerminalSessionStatus.controlling);
    });

    test(
      'an error for this stream fails it with the daemon\'s words',
      () async {
        final (s, streamId) = await live();

        await s.handleFrame('terminal_error', {
          'streamId': streamId,
          'code': 'TERMINAL_PASTE_FAILED',
          'message': 'pty write failed',
        });

        expect(s.status, TerminalSessionStatus.error);
        expect(s.errorCode, 'TERMINAL_PASTE_FAILED');
        expect(s.errorMessage, 'pty write failed');
      },
    );

    test('an error with no code is still an error', () async {
      final (s, _) = await live();

      await s.handleFrame('terminal_error', {});

      expect(s.errorCode, 'TERMINAL_ERROR');
    });

    test('a refused paste leaves the stream alone', () async {
      final (s, streamId) = await live();

      await s.handleFrame('terminal_error', {
        'streamId': streamId,
        'code': 'TERMINAL_PASTE_INVALID',
      });

      expect(s.status, TerminalSessionStatus.controlling);
    });

    test(
      'a refused keystroke realigns the count once, not per refusal',
      () async {
        final (s, streamId) = await live();
        for (final key in ['a', 'b', 'c']) {
          s.terminal.textInput(key);
          await Future<void>.delayed(const Duration(milliseconds: 10));
        }
        expect(_inputSeqs(wire), [0, 1, 2]);

        for (var i = 0; i < 2; i++) {
          await s.handleFrame('terminal_error', {
            'streamId': streamId,
            'code': 'TERMINAL_INPUT_INVALID',
            'expectedSeq': 1,
          });
        }
        s.terminal.textInput('d');
        await Future<void>.delayed(const Duration(milliseconds: 10));

        expect(_inputSeqs(wire).last, 1);
        expect(s.status, TerminalSessionStatus.controlling);
      },
    );

    test(
      'a refused keystroke from a daemon that does not say reopens',
      () async {
        final (s, streamId) = await live();

        await s.handleFrame('terminal_error', {
          'streamId': streamId,
          'code': 'TERMINAL_INPUT_INVALID',
        });
        await Future<void>.delayed(Duration.zero);

        expect(wire.last('terminal_close'), {'streamId': streamId});
        expect(wire.of('terminal_open'), hasLength(2));
      },
    );

    test('a polite open refused waits for a person', () async {
      final s = session(takeover: false);
      await s.open();

      await s.handleFrame('terminal_error', {
        'requestId': wire.last('terminal_open')['requestId'],
        'code': 'CONTROL_LEASE_HELD',
      });

      expect(s.status, TerminalSessionStatus.takenOver);
      expect(s.errorMessage, 'Another client controls this terminal.');
      expect(wire.of('terminal_open'), hasLength(1));
    });

    test(
      'a polite open refused after a person arrived asks again, properly',
      () async {
        final s = session(takeover: false);
        await s.open();
        s.takeover = true;

        await s.handleFrame('terminal_error', {
          'requestId': wire.last('terminal_open')['requestId'],
          'code': 'CONTROL_LEASE_HELD',
        });
        await Future<void>.delayed(Duration.zero);

        expect(wire.of('terminal_open'), hasLength(2));
        expect(wire.last('terminal_open').containsKey('takeover'), isFalse);
      },
    );

    test('an ordinary open that lost the race keeps its retry', () async {
      final s = session();
      await s.open();

      await s.handleFrame('terminal_error', {
        'requestId': wire.last('terminal_open')['requestId'],
        'code': 'CONTROL_LEASE_HELD',
      });

      expect(s.status, TerminalSessionStatus.error);
    });

    test(
      'the link\'s mode is shown only when it is one the header can draw',
      () async {
        final (s, streamId) = await live();

        await s.handleFrame('terminal_link_mode', {
          'streamId': streamId,
          'mode': 'p2p',
        });
        expect(s.linkMode, 'p2p');
        await s.handleFrame('terminal_link_mode', {
          'streamId': streamId,
          'mode': 'carrier-pigeon',
        });
        expect(s.linkMode, 'p2p');
        await s.handleFrame('terminal_link_mode', {
          'streamId': _streamId(),
          'mode': 'relay',
        });
        expect(s.linkMode, 'p2p');
      },
    );

    test(
      'an unknown frame is not the session\'s; a disposed one hears nothing',
      () async {
        final s = session(disposeAtEnd: false);

        expect(await s.handleFrame('terminal_whatever', {}), isFalse);
        s.dispose();
        expect(await s.handleFrame('terminal_ready', {}), isFalse);
        await s.open();
        await s.reopen();
        expect(wire.of('terminal_open'), isEmpty);
      },
    );
  });

  group('reopening and closing', () {
    test(
      'a stream on its way or alive is not reopened, unless forced',
      () async {
        final (s, _) = await live();

        await s.reopen();
        expect(wire.of('terminal_open'), hasLength(1));

        await s.reopen(force: true);
        expect(wire.of('terminal_open'), hasLength(2));
        expect(s.status, TerminalSessionStatus.opening);
        expect(_screen(s), contains('prompt>'), reason: 'the screen is kept');
      },
    );

    test('a dead stream reopens at the measured size', () async {
      final (s, _) = await live();
      s.reportViewport(100, 30);
      s.transportLost('gone');

      await s.reopen();

      expect(wire.last('terminal_open')['cols'], 100);
      expect(wire.last('terminal_open')['rows'], 30);
    });

    test('closing says so to the daemon, once there is a stream', () async {
      final (s, streamId) = await live();

      await s.close();
      await s.close();

      expect(wire.of('terminal_close'), [
        {'streamId': streamId},
      ]);
      expect(s.status, TerminalSessionStatus.closed);
      s.transportLost('late');
      expect(s.status, TerminalSessionStatus.closed);
    });

    test('a rename is trimmed, and said only when it changes', () async {
      final s = session();
      var told = 0;
      s.addListener(() => told++);

      s.renameAgent('  api ');
      s.renameAgent('api');
      s.renameAgent('   ');

      expect(s.agentName, 'api');
      expect(told, 1);
    });

    // What the page reads to keep a screen up under a spinner while it is brought back, rather
    // than covering it with the attaching skeleton — which made a terminal vanish into a skeleton
    // and come back, every time the phone returned from a network switch.
    group('a screen kept through a reopen', () {
      test('a first open has no earlier screen to keep', () async {
        final s = session();
        await s.open();

        expect(s.hasScreen, isFalse);
        expect(s.showsEarlierScreen, isFalse);
      });

      test('lost with its socket, the screen stays and the stream says why', () async {
        final (s, _) = await live(screen: 'what was read');

        s.transportLost('Connection lost. Reconnecting…');

        expect(s.lostWithTransport, isTrue);
        expect(s.hasScreen, isTrue);
        expect(_screen(s), contains('what was read'));
      });

      test('reopened, it is an earlier screen until the new one lands', () async {
        final (s, _) = await live(screen: 'what was read');
        s.transportLost('Connection lost. Reconnecting…');

        await s.reopen();

        expect(s.hasScreen, isFalse, reason: 'the new stream has no frame yet');
        expect(s.showsEarlierScreen, isTrue);
        expect(s.lostWithTransport, isFalse);
        expect(_screen(s), contains('what was read'));

        final next = await ready(s);
        await s.handleBinary(_keyframe(next, text: 'what is now'));

        expect(s.showsEarlierScreen, isFalse);
        expect(s.hasScreen, isTrue);
        expect(_screen(s), contains('what is now'));
      });

      test('an open that starts on a blank terminal forgets the earlier '
          'screen', () async {
        final (s, _) = await live(screen: 'what was read');

        await s.open();

        expect(s.showsEarlierScreen, isFalse);
        expect(_screen(s), isNot(contains('what was read')));
      });

      test('a kept screen seeded from elsewhere is a screen already, and no '
          'earlier one', () async {
        final s = session();
        s.seedScreen(Terminal()..write('kept from the pager'));

        await s.open();

        expect(s.hasScreen, isTrue);
        expect(s.showsEarlierScreen, isFalse);
      });

      test('an error of another kind is not a loss with the socket', () async {
        final s = session();
        await s.open();
        await s.handleFrame('terminal_ready', {
          'requestId': wire.last('terminal_open')['requestId'],
          'agentId': 'a',
          'protocolVersion': TerminalSession.protocolVersion,
        });

        expect(s.status, TerminalSessionStatus.error);
        expect(s.lostWithTransport, isFalse);
      });
    });
  });

  group('what is typed', () {
    test('goes out numbered, and nothing before the stream is live', () async {
      final s = session();
      await s.open();
      s.terminal.textInput('early');
      await Future<void>.delayed(const Duration(milliseconds: 10));
      expect(wire.binaries, isEmpty);

      final streamId = await ready(s);
      await s.handleBinary(_keyframe(streamId));
      s.terminal.textInput('l');
      await Future<void>.delayed(const Duration(milliseconds: 10));
      s.terminal.textInput('s\r');
      await Future<void>.delayed(const Duration(milliseconds: 10));

      expect(_typed(wire), 'ls\r');
      expect(_inputSeqs(wire), [0, 1]);
    });

    test('an armed ctrl turns the next key into its chord, once', () async {
      final (s, _) = await live();

      s.armControl(true);
      expect(s.controlArmed, isTrue);
      s.terminal.textInput('c');
      await Future<void>.delayed(const Duration(milliseconds: 10));
      s.terminal.textInput('c');
      await Future<void>.delayed(const Duration(milliseconds: 10));

      expect(_typed(wire), '\x03c');
      expect(s.controlArmed, isFalse);
    });

    test(
      'clearing the prompt is ctrl-K then ctrl-U, and the keyboard\'s buffer',
      () async {
        // A prompt two rows from the foot of the screen, its footer under it
        // and the cursor back in it, as Claude Code draws one.
        final (s, _) = await live(
          screen: '${'\r\n' * 22}❯ fix it\r\n  ? for shortcuts\x1b[23;9H',
        );
        final viewport = _Viewport();
        s.attachViewport(viewport);

        s.clearPrompt();
        await until(() => _typed(wire).length == 8);

        // One kill is one row as wrapped, and a kill past the prompt's ends
        // does nothing — so two each way for each of its two rows.
        expect(_typed(wire), '${'\x0b' * 4}${'\x15' * 4}');
        expect(viewport.cleared, 1);
        s.detachViewport(_Viewport());
        s.resetInputBuffer();
        expect(
          viewport.cleared,
          2,
          reason: 'another view detaching changes nothing',
        );
        s.detachViewport(viewport);
        s.resetInputBuffer();
        expect(viewport.cleared, 2);
      },
    );

    test('a key that cannot be sent is a lost stream', () async {
      final (s, _) = await live();
      wire.binarySends = false;

      s.terminal.textInput('x');
      await Future<void>.delayed(const Duration(milliseconds: 10));

      expect(s.status, TerminalSessionStatus.error);
      expect(s.errorMessage, 'Terminal input was not sent');
    });

    test('a paste too big for one frame is split, still in order', () async {
      final (s, _) = await live();
      final big = 'x' * (TerminalSession.kInputFrameMaxBytes + 10);

      s.terminal.textInput('$big\r');
      await Future<void>.delayed(const Duration(milliseconds: 20));

      final frames = wire.binaries
          .where((f) => f.kind == TerminalBinaryKind.input)
          .toList();
      expect(frames.length, greaterThan(1));
      expect(
        frames.every(
          (f) => f.bytes.length <= TerminalSession.kInputFrameMaxBytes,
        ),
        isTrue,
      );
      expect(_typed(wire), '$big\r');
    });

    test('a composed message is one turn, not keystrokes', () async {
      final (s, _) = await live();

      expect(await s.sendComposerText('  '), isFalse);
      expect(await s.sendComposerText('fix it  \n'), isTrue);

      expect(wire.last('message'), {
        'content': 'fix it',
        'agentId': 'a',
        'mode': 'auto',
      });
      expect(wire.binaries, isEmpty);
    });

    test('a watcher sends no message', () async {
      final s = session();
      await s.open();
      await ready(s, readOnly: true);

      expect(await s.sendComposerText('hi'), isFalse);
      expect(await s.pasteText('hi'), isFalse);
    });

    test('a line sent — a Return, or a message that went — is said, once each', () async {
      final (s, _) = await live();
      var sent = 0;
      s.onLineSent = () => sent++;

      s.terminal.textInput('l');
      s.terminal.textInput('s');
      await Future<void>.delayed(const Duration(milliseconds: 10));
      expect(sent, 0, reason: 'keys typed are not a line sent');
      s.terminal.textInput('\r');
      await Future<void>.delayed(const Duration(milliseconds: 10));
      expect(sent, 1);

      expect(await s.sendComposerText('  '), isFalse);
      expect(sent, 1, reason: 'nothing went');
      expect(await s.sendComposerText('fix it'), isTrue);
      expect(sent, 2);
    });

    test('a line that cannot go is not said', () async {
      final s = session();
      await s.open();
      await ready(s, readOnly: true);
      var sent = 0;
      s.onLineSent = () => sent++;

      s.terminal.textInput('ls\r');
      await Future<void>.delayed(const Duration(milliseconds: 10));
      expect(await s.sendComposerText('hi'), isFalse);
      expect(sent, 0);
    });

    test(
      'a paste is one frame; one that cannot be sent is a lost stream',
      () async {
        final (s, streamId) = await live();

        expect(await s.pasteText(''), isFalse);
        expect(await s.pasteText('line one\nline two'), isTrue);
        final paste = wire.binaries.single;
        expect(paste.kind, TerminalBinaryKind.paste);
        expect(paste.streamId, streamId);
        expect(utf8.decode(paste.bytes), 'line one\nline two');

        wire.binarySends = false;
        expect(await s.pasteText('again'), isFalse);
        expect(s.errorMessage, 'Terminal paste was not sent');
      },
    );
  });

  group('images and files', () {
    Future<void> answer(
      TerminalSession s,
      String type, [
      Map<String, dynamic> extra = const {},
    ]) => s.handleFrame(type, {'streamId': s.streamId, ...extra});

    test(
      'an image is announced, sent in chunks, and done when the daemon says',
      () async {
        final (s, streamId) = await live();
        final image = Uint8List(terminalUploadChunkBytes + 5);

        final pasting = s.pasteImage(image);
        await Future<void>.delayed(Duration.zero);
        expect(wire.last('terminal_chunked_upload_begin'), {
          'streamId': streamId,
          'uploadKind': 'image',
          'totalBytes': image.length,
        });
        expect(s.uploadProgress?.label, 'image');

        await answer(s, 'terminal_chunked_upload_begin_result', {
          'accepted': true,
        });
        await Future<void>.delayed(Duration.zero);
        final chunks = wire.binaries
            .where((f) => f.kind == TerminalBinaryKind.imagePaste)
            .toList();
        expect([for (final c in chunks) c.seq], [0, 1]);
        expect(chunks.first.bytes.length, terminalUploadChunkBytes);

        await answer(s, 'terminal_chunked_upload_progress', {
          'bytesWritten': 100,
          'totalBytes': image.length,
        });
        expect(s.uploadProgress!.bytesWritten, 100);
        expect(s.uploadProgress!.percent, closeTo(100 / image.length, 1e-9));

        await answer(s, 'terminal_paste_image_result');
        expect(await pasting, isTrue);
        expect(s.uploadProgress, isNull);
      },
    );

    test('a file carries its name', () async {
      final (s, _) = await live();

      final pasting = s.pasteFile('notes.md', Uint8List.fromList([1, 2]));
      await Future<void>.delayed(Duration.zero);
      expect(
        wire.last('terminal_chunked_upload_begin')['filename'],
        'notes.md',
      );
      expect(s.uploadProgress?.label, 'notes.md');
      await answer(s, 'terminal_chunked_upload_begin_result', {
        'accepted': true,
      });
      await Future<void>.delayed(Duration.zero);
      await answer(s, 'terminal_paste_file_result');

      expect(await pasting, isTrue);
      expect(await s.pasteFile('', Uint8List(1)), isFalse);
      expect(await s.pasteFile('x', Uint8List(0)), isFalse);
      expect(await s.pasteImage(Uint8List(0)), isFalse);
    });

    test('a refused announcement ends it', () async {
      final (s, _) = await live();

      final pasting = s.pasteImage(Uint8List(3));
      await Future<void>.delayed(Duration.zero);
      await answer(s, 'terminal_chunked_upload_begin_result', {
        'accepted': false,
      });

      expect(await pasting, isFalse);
      expect(s.uploadProgress, isNull);
    });

    /// The rows the terminal shows, as text.
    String screenOf(TerminalSession s) => [
      for (var i = 0; i < s.terminal.buffer.lines.length; i++)
        s.terminal.buffer.lines[i].getText(),
    ].join('\n');

    // The daemon no longer has the stream: it takes no input and no upload, and only this answer
    // says so. Left alone, the picture failed and the terminal sat on as if live.
    for (final (name, refusal) in [
      (
        'refused because the stream is gone',
        {
          'code': 'TERMINAL_STREAM_NOT_FOUND',
          'reason':
              'no live terminal stream for this pane (reopen it and try again)',
        },
      ),
      (
        'refused in an older daemon\'s words only',
        {
          'reason':
              'no live terminal stream for this pane (reopen it and try again)',
        },
      ),
    ]) {
      test('$name: the terminal is opened again, its screen kept and the '
          'picture not sent twice', () async {
        final (s, streamId) = await live(screen: 'kept screen');
        final opens = wire.of('terminal_open').length;

        final pasting = s.pasteImage(Uint8List(3));
        await Future<void>.delayed(Duration.zero);
        await answer(s, 'terminal_chunked_upload_begin_result', {
          'accepted': false,
          ...refusal,
        });

        expect(await pasting, isFalse);
        expect(wire.of('terminal_open'), hasLength(opens + 1));
        expect(wire.last('terminal_close')['streamId'], streamId);
        expect(screenOf(s), contains('kept screen'));
        expect(wire.of('terminal_chunked_upload_begin'), hasLength(1));
      });
    }

    test('refused for another reason: the stream stays as it is', () async {
      final (s, streamId) = await live();
      final opens = wire.of('terminal_open').length;

      final pasting = s.pasteImage(Uint8List(3));
      await Future<void>.delayed(Duration.zero);
      await answer(s, 'terminal_chunked_upload_begin_result', {
        'accepted': false,
        'code': 'TERMINAL_UPLOAD_TOO_LARGE',
      });

      expect(await pasting, isFalse);
      expect(wire.of('terminal_open'), hasLength(opens));
      expect(s.streamId, streamId);
    });

    test('one at a time, and cancelling says so', () async {
      final (s, streamId) = await live();

      final first = s.pasteImage(Uint8List(3));
      await Future<void>.delayed(Duration.zero);
      expect(await s.pasteImage(Uint8List(3)), isFalse);

      await s.cancelUpload();

      expect(await first, isFalse);
      expect(wire.last('terminal_chunked_upload_cancel'), {
        'streamId': streamId,
      });
      await s.cancelUpload();
      expect(wire.of('terminal_chunked_upload_cancel'), hasLength(1));
    });

    test('cancelling before the daemon answers the announcement settles it at '
        'once', () {
      fakeAsync((async) {
        final s = session(disposeAtEnd: false);
        s.open();
        async.flushMicrotasks();
        s.handleFrame('terminal_ready', {
          'requestId': wire.last('terminal_open')['requestId'],
          'agentId': 'a',
          'protocolVersion': TerminalSession.protocolVersion,
          'streamId': _streamId(),
        });
        s.handleBinary(_keyframe(s.streamId!));
        async.flushMicrotasks();
        bool? result;
        s.pasteImage(Uint8List(3)).then((value) => result = value);
        async.flushMicrotasks();

        s.cancelUpload();
        async.flushMicrotasks();

        expect(result, isFalse);
        expect(wire.of('terminal_chunked_upload_cancel'), hasLength(1));
        s.dispose();
      });
    });

    test('a stream lost mid-upload settles it at once', () async {
      final (s, _) = await live();

      final pasting = s.pasteImage(Uint8List(3));
      await Future<void>.delayed(Duration.zero);
      s.transportLost('gone');

      expect(await pasting, isFalse);
    });

    test(
      'a chunk the daemon calls malformed ends it and keeps the stream',
      () async {
        final (s, streamId) = await live();

        final pasting = s.pasteImage(Uint8List(3));
        await Future<void>.delayed(Duration.zero);
        await s.handleFrame('terminal_error', {
          'streamId': streamId,
          'code': 'TERMINAL_CHUNKED_UPLOAD_INVALID',
        });

        expect(await pasting, isFalse);
        expect(s.status, TerminalSessionStatus.controlling);
      },
    );

    test(
      'an announcement or chunk that cannot be sent is a lost stream',
      () async {
        final (s, _) = await live();
        wire.sends = false;
        expect(await s.pasteImage(Uint8List(3)), isFalse);
        expect(s.errorMessage, 'Terminal upload request was not sent');

        wire.sends = true;
        final (t, _) = await live();
        wire.binarySends = false;
        final pasting = t.pasteImage(Uint8List(3));
        await Future<void>.delayed(Duration.zero);
        await t.handleFrame('terminal_chunked_upload_begin_result', {
          'streamId': t.streamId,
          'accepted': true,
        });
        expect(await pasting, isFalse);
        expect(t.errorMessage, 'Terminal upload chunk was not sent');
      },
    );

    test('a daemon that never answers the announcement times it out', () {
      fakeAsync((async) {
        final s = session(disposeAtEnd: false);
        s.open();
        async.flushMicrotasks();
        s.handleFrame('terminal_ready', {
          'requestId': wire.last('terminal_open')['requestId'],
          'agentId': 'a',
          'protocolVersion': TerminalSession.protocolVersion,
          'streamId': _streamId(),
        });
        s.handleBinary(_keyframe(s.streamId!));
        async.flushMicrotasks();
        bool? result;
        s.pasteImage(Uint8List(3)).then((value) => result = value);

        async.elapse(const Duration(seconds: 11));

        expect(result, isFalse);
        // It may have been accepted all the same: the daemon is told to drop it.
        expect(wire.last('terminal_chunked_upload_cancel'), {
          'streamId': s.streamId,
        });
        s.dispose();
      });
    });

    test(
      'chunks wait for the daemon to confirm: at most the window is on the way',
      () async {
        final (s, _) = await live();
        final window = terminalUploadWindowBytes ~/ terminalUploadChunkBytes;
        final image = Uint8List(terminalUploadChunkBytes * (window + 2) + 7);
        List<int> sent() => [
          for (final f in wire.binaries)
            if (f.kind == TerminalBinaryKind.imagePaste) f.seq,
        ];
        Future<void> confirm(int bytes) async {
          await answer(s, 'terminal_chunked_upload_progress', {
            'bytesWritten': bytes,
            'totalBytes': image.length,
          });
          await Future<void>.delayed(Duration.zero);
        }

        final pasting = s.pasteImage(image);
        await Future<void>.delayed(Duration.zero);
        await answer(s, 'terminal_chunked_upload_begin_result', {
          'accepted': true,
        });
        await Future<void>.delayed(Duration.zero);
        expect(sent(), hasLength(window));

        await confirm(terminalUploadChunkBytes);
        expect(sent(), hasLength(window + 1));
        await confirm(terminalUploadChunkBytes);
        expect(sent(), hasLength(window + 1));
        await confirm(terminalUploadChunkBytes * 3);
        expect(sent(), [for (var seq = 0; seq < window + 3; seq++) seq]);

        await confirm(image.length);
        await answer(s, 'terminal_paste_image_result');
        expect(await pasting, isTrue);
        expect(wire.of('terminal_chunked_upload_cancel'), isEmpty);
      },
    );

    for (final waitingForRoom in [true, false]) {
      test('an upload the daemon stops confirming is given up, here and on the '
          'daemon (waiting for room: $waitingForRoom)', () async {
        final (s, streamId) = await live(
          uploadStall: const Duration(milliseconds: 50),
        );
        final window = terminalUploadWindowBytes ~/ terminalUploadChunkBytes;
        final chunks = waitingForRoom ? window + 3 : 3;
        final image = Uint8List(terminalUploadChunkBytes * chunks);

        final pasting = s.pasteImage(image);
        await Future<void>.delayed(Duration.zero);
        await answer(s, 'terminal_chunked_upload_begin_result', {
          'accepted': true,
        });
        await Future<void>.delayed(Duration.zero);
        // Part of the picture arrives; the rest was lost on the way.
        await answer(s, 'terminal_chunked_upload_progress', {
          'bytesWritten': terminalUploadChunkBytes,
          'totalBytes': image.length,
        });

        expect(await pasting, isFalse);
        expect(
          wire.binaries.where((f) => f.kind == TerminalBinaryKind.imagePaste),
          hasLength(waitingForRoom ? window + 1 : 3),
        );
        expect(s.uploadProgress, isNull);
        expect(s.lastStalledUpload!.bytesWritten, terminalUploadChunkBytes);
        expect(wire.last('terminal_chunked_upload_cancel'), {
          'streamId': streamId,
        });
        expect(s.status, TerminalSessionStatus.controlling);

        final next = s.pasteImage(Uint8List(3));
        await Future<void>.delayed(Duration.zero);
        expect(wire.of('terminal_chunked_upload_begin'), hasLength(2));
        expect(s.lastStalledUpload, isNull);
        await s.cancelUpload();
        expect(await next, isFalse);
      });
    }

    test('an upload the daemon still holds for this pane is cancelled, and the '
        'announcement made once more', () async {
      final (s, streamId) = await live();
      const stale = {
        'accepted': false,
        'reason': 'an upload is already in progress on this pane',
      };

      final pasting = s.pasteImage(Uint8List(3));
      await Future<void>.delayed(Duration.zero);
      await answer(s, 'terminal_chunked_upload_begin_result', stale);
      await Future<void>.delayed(Duration.zero);
      expect(wire.of('terminal_chunked_upload_cancel'), [
        {'streamId': streamId},
      ]);
      expect(wire.of('terminal_chunked_upload_begin'), hasLength(2));
      await answer(s, 'terminal_chunked_upload_begin_result', {
        'accepted': true,
      });
      await Future<void>.delayed(Duration.zero);
      await answer(s, 'terminal_paste_image_result');
      expect(await pasting, isTrue);

      // Only once: a daemon that refuses again ends it.
      final again = s.pasteImage(Uint8List(3));
      for (var i = 0; i < 2; i++) {
        await Future<void>.delayed(Duration.zero);
        await answer(s, 'terminal_chunked_upload_begin_result', stale);
      }
      expect(await again, isFalse);
      expect(wire.of('terminal_chunked_upload_begin'), hasLength(4));
    });

    test('frames about an upload on another stream are ignored', () async {
      final (s, _) = await live();
      final other = _streamId();

      for (final type in [
        'terminal_chunked_upload_begin_result',
        'terminal_chunked_upload_progress',
        'terminal_paste_image_result',
      ]) {
        expect(await s.handleFrame(type, {'streamId': other}), isTrue);
      }
      expect(s.uploadProgress, isNull);
    });
  });

  group('size and scrolling', () {
    test('the first resize goes at once; a drag is asked for once, where it settles', () async {
      final (s, streamId) = await live();

      s.resize(100, 30);
      await Future<void>.delayed(Duration.zero);
      s.resize(110, 31);
      s.resize(120, 32);
      await Future<void>.delayed(const Duration(milliseconds: 80));

      final sizes = [
        for (final r in wire.of('terminal_resize')) (r['cols'], r['rows']),
      ];
      expect(sizes, [(100, 30), (120, 32)]);
      expect(wire.last('terminal_resize')['streamId'], streamId);
      expect(wire.last('terminal_resize')['resizeSeq'], 1);
    });

    test('a resize to the size it already is sends nothing', () async {
      final (s, _) = await live();

      s.resize(80, 24);
      await Future<void>.delayed(Duration.zero);

      expect(wire.of('terminal_resize'), isEmpty);
    });

    test('a resize that cannot be sent is a lost stream', () async {
      final (s, _) = await live();
      wire.sends = false;

      s.resize(100, 30);
      await Future<void>.delayed(Duration.zero);

      expect(s.errorMessage, 'Terminal resize was not sent');
    });

    test(
      'the measured size is asked for as soon as the screen lands',
      () async {
        final s = session();
        await s.open();
        s.reportViewport(90, 30);
        final streamId = await ready(s);

        await s.handleBinary(_keyframe(streamId));
        await Future<void>.delayed(Duration.zero);

        expect(wire.last('terminal_resize')['cols'], 90);
      },
    );

    test('Grok\'s scroll goes to tmux, coalesced, flushed on a turn', () async {
      final (s, streamId) = await live(engine: 'grok');

      s.sendScrollCommand(true, 2);
      s.sendScrollCommand(true, 3);
      s.sendScrollCommand(false, 1);
      await Future<void>.delayed(const Duration(milliseconds: 40));
      s.sendScrollCommand(true, 0);

      expect(wire.of('terminal_scroll'), [
        {'streamId': streamId, 'direction': 'up', 'lines': 5},
        {'streamId': streamId, 'direction': 'down', 'lines': 1},
      ]);
    });

    test('any other engine scrolls its own copy', () async {
      final (s, _) = await live();
      final viewport = _Viewport();
      s.attachViewport(viewport);

      s.sendScrollCommand(true, 3);
      s.scroll(1, 10, 0);
      expect(s.focusInput(), isTrue);
      await Future<void>.delayed(const Duration(milliseconds: 40));

      expect(wire.of('terminal_scroll'), isEmpty);
      expect(viewport.scrolls, [(1, 10, 0)]);
    });

    group('a shrink that cuts rows under the cursor', () {
      // Claude Code's screen at 80×24: its prompt between two rules, two status lines under it, and
      // the cursor at the end of what is typed.
      final claudeScreen =
          '\x1b[?25h${'\r\n' * 18}${'─' * 79}\r\n❯ hello world\r\n${'─' * 79}'
          '\r\n  ? for shortcuts\r\n  auto mode on\x1b[20;14H';

      TerminalBinaryFrame answer(String streamId, String text) =>
          TerminalBinaryFrame(
            kind: TerminalBinaryKind.keyframe,
            streamId: streamId,
            seq: 1,
            bytes: Uint8List.fromList(utf8.encode(text)),
            compressed: false,
            cols: 80,
            rows: 18,
          );

      Future<(TerminalSession, String)> shrunk() async {
        final (s, streamId) = await live(screen: claudeScreen);
        expect(s.terminal.cursorVisibleMode, isTrue);
        // The keyboard comes up: tmux drops the rows under the prompt.
        s.resize(80, 18);
        await Future<void>.delayed(const Duration(milliseconds: 60));
        expect(wire.of('terminal_resize'), isNotEmpty);
        return (s, streamId);
      }

      test('keeps the cursor shown when the answer has it in the prompt', () async {
        final (s, streamId) = await shrunk();

        await s.handleBinary(
          answer(
            streamId,
            '\x1b[?25h${'\r\n' * 12}${'─' * 79}\r\n❯ hello world\r\n${'─' * 79}'
            '\r\n  ? for shortcuts\r\n  auto mode on\x1b[14;14H',
          ),
        );

        expect(s.terminal.cursorVisibleMode, isTrue);
      });

      test('hides a cursor left under the status lines until the program '
          'draws again', () async {
        final (s, streamId) = await shrunk();

        await s.handleBinary(
          answer(
            streamId,
            '\x1b[?25h${'\r\n' * 12}${'─' * 79}\r\n❯ hello world\r\n${'─' * 79}'
            '\r\n  ? for shortcuts\r\n  auto mode on\x1b[18;1H',
          ),
        );
        expect(s.terminal.cursorVisibleMode, isFalse);

        await s.handleBinary(_output(streamId, 2, '\x1b[14;14H'));
        expect(s.terminal.cursorVisibleMode, isTrue);
      });
    });

    test('the cursor blinks locally, never into the stream', () async {
      final (s, _) = await live();

      s.setCursorBlinkPhase(false);
      expect(s.terminal.cursorVisibleMode, isFalse);
      s.setCursorBlinkPhase(false);
      s.setCursorBlinkPhase(true);
      expect(s.terminal.cursorVisibleMode, isTrue);
      expect(wire.binaries, isEmpty);
    });

    test('an acknowledgement that cannot be sent is a lost stream', () async {
      final (s, streamId) = await live();
      wire.sends = false;

      await s.handleBinary(_output(streamId, 1, 'x'));
      await Future<void>.delayed(const Duration(milliseconds: 40));

      expect(s.errorMessage, 'Terminal ACK was not sent');
    });

    test('a large burst is acknowledged at once, not on the timer', () async {
      final (s, streamId) = await live();
      final before = wire.of('terminal_ack').length;

      await s.handleBinary(_output(streamId, 1, 'y' * (64 * 1024)));

      expect(wire.of('terminal_ack').length, before + 1);
    });
  });

  group('who a client is', () {
    test('only a well-formed introduction is believed', () {
      expect(TerminalClientDescriptor.fromJson(null), isNull);
      expect(
        TerminalClientDescriptor.fromJson({'kind': 'Desk top', 'name': 'x'}),
        isNull,
      );
      expect(
        TerminalClientDescriptor.fromJson({'kind': 'desktop', 'name': 3}),
        isNull,
      );
      expect(
        TerminalClientDescriptor.fromJson({'kind': 'desktop', 'name': '  '}),
        isNull,
      );
      expect(
        TerminalClientDescriptor.fromJson({
          'kind': 'desktop',
          'name': 'x' * (TerminalClientDescriptor.nameMax + 1),
        }),
        isNull,
      );
      expect(
        TerminalClientDescriptor.fromJson({
          'kind': 'desktop',
          'name': 'Mac',
          'machineId': 'not-hex',
        }),
        isNull,
      );

      final mac = TerminalClientDescriptor.fromJson({
        'kind': 'desktop',
        'name': 'Mac\u0007 mini',
        'machineId': 'a' * 16,
      })!;
      expect(mac.name, 'Mac  mini');
      expect(mac.toJson()['machineId'], 'a' * 16);
    });

    test('a desktop is named as the fleet names its machine now', () {
      final mac = TerminalClientDescriptor(
        kind: 'desktop',
        name: 'old name',
        machineId: 'a' * 16,
      );

      expect(mac.label((_) => ' Studio '), 'Studio');
      expect(mac.label((_) => null), 'old name');
      expect(mac.label((_) => '  '), 'old name');
      expect(
        const TerminalClientDescriptor(
          kind: 'phone',
          name: 'Pat',
        ).label((_) => 'never asked'),
        'Pat',
      );
    });

    test('an upload\'s progress never reads past the ends', () {
      const empty = UploadProgress(label: 'x', bytesWritten: 5, totalBytes: 0);
      expect(empty.percent, 0);
      final over = empty.copyWith(totalBytes: 2);
      expect(over.percent, 1);
      expect(over.copyWith().bytesWritten, 5);
    });
  });
}

/// The session's two send channels, recorded.
class _Wire {
  final frames = <(String, Map<String, dynamic>)>[];
  final binaries = <TerminalBinaryFrame>[];
  bool sends = true;
  bool binarySends = true;

  Future<bool> send(String type, Map<String, dynamic> payload) async {
    frames.add((type, payload));
    return sends;
  }

  Future<bool> sendBinary(TerminalBinaryFrame frame) async {
    binaries.add(frame);
    return binarySends;
  }

  List<Map<String, dynamic>> of(String type) => [
    for (final (sent, payload) in frames)
      if (sent == type) payload,
  ];

  Map<String, dynamic> last(String type) => of(type).last;
}

class _Viewport implements TerminalViewport {
  final scrolls = <(int, int, int)>[];
  var cleared = 0;

  @override
  void scroll(int phase, int dy, int velocity) =>
      scrolls.add((phase, dy, velocity));

  @override
  bool focusInput() => true;

  @override
  void clearInputBuffer() => cleared++;
}

var _streams = 0;

String _streamId() =>
    '00000000-0000-4000-8000-${(++_streams).toString().padLeft(12, '0')}';

TerminalBinaryFrame _keyframe(
  String streamId, {
  int seq = 0,
  String text = 'prompt> ',
  List<int>? bytes,
  bool compressed = false,
}) => TerminalBinaryFrame(
  kind: TerminalBinaryKind.keyframe,
  streamId: streamId,
  seq: seq,
  bytes: Uint8List.fromList(bytes ?? utf8.encode(text)),
  compressed: compressed,
  cols: 80,
  rows: 24,
);

TerminalBinaryFrame _output(
  String streamId,
  int seq,
  String? text, {
  List<int>? bytes,
  bool compressed = false,
}) => TerminalBinaryFrame(
  kind: TerminalBinaryKind.output,
  streamId: streamId,
  seq: seq,
  bytes: Uint8List.fromList(bytes ?? utf8.encode(text!)),
  compressed: compressed,
);

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

/// Everything on the session's screen, as text.
String _screen(TerminalSession s) {
  final buffer = s.terminal.buffer;
  return [
    for (var i = 0; i < buffer.lines.length; i++)
      buffer.lines[i].toString().trimRight(),
  ].join('\n');
}

String _typed(_Wire wire) => utf8.decode([
  for (final frame in wire.binaries)
    if (frame.kind == TerminalBinaryKind.input) ...frame.bytes,
]);

List<int> _inputSeqs(_Wire wire) => [
  for (final frame in wire.binaries)
    if (frame.kind == TerminalBinaryKind.input) frame.seq,
];