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.

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

import 'package:fake_async/fake_async.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/core/config.dart';
import 'package:harness/core/harness_cli_runner.dart';
import 'package:harness/ws/local_cli_discovery.dart';

void main() {
  HttpServer? server;
  late Directory scratch;

  setUp(() async {
    scratch = await Directory.systemTemp.createTemp('local-cli-discovery-');
  });

  tearDown(() async {
    await server?.close(force: true);
    server = null;
    if (await scratch.exists()) await scratch.delete(recursive: true);
  });

  test('uses the stable Harness computer id path', () {
    final path = LocalMachineIdentity.defaultComputerIdPath(
      environment: {'HOME': '/Users/tester'},
    );
    expect(path, '/Users/tester/.harness/computer-id');
  }, skip: Platform.isWindows);

  test('discovers only an exact-computer loopback endpoint', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    final identityFile = File('${scratch.path}/computer-id')
      ..writeAsStringSync('$computerId\n');
    server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
    server!.listen((request) async {
      request.response.headers.contentType = ContentType.json;
      request.response.write(
        jsonEncode({
          'computerId': computerId,
          'localWs': {
            'path': '/api/local-ws',
            'protocolVersion': 1,
            'terminalProtocolVersion': 3,
            'e2ee': false,
          },
        }),
      );
      await request.response.close();
    });
    final endpoint = await LocalCliDiscovery(
      config: AppConfig(
        apiBaseUrl: 'https://harness-api.autonomous.ai',
        localCliBaseUrl: 'http://127.0.0.1:${server!.port}',
      ),
      identity: LocalMachineIdentity(computerIdFile: identityFile),
    ).discover();
    expect(endpoint?.computerId, computerId);
    expect(
      endpoint?.wsUri.toString(),
      'ws://127.0.0.1:${server!.port}/api/local-ws',
    );
  });

  test('a CLI still on its initial terminal discovery is usable, and says it is scanning', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    final identityFile = File('${scratch.path}/computer-id')
      ..writeAsStringSync(computerId);
    server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
    server!.listen((request) async {
      request.response.headers.contentType = ContentType.json;
      request.response.write(
        jsonEncode({
          'computerId': computerId,
          'discoveryReady': false,
          'localWs': {
            'path': '/api/local-ws',
            'protocolVersion': 1,
            'terminalProtocolVersion': 3,
            'e2ee': false,
          },
        }),
      );
      await request.response.close();
    });

    final endpoint = await LocalCliDiscovery(
      config: AppConfig(
        apiBaseUrl: 'https://harness-api.autonomous.ai',
        localCliBaseUrl: 'http://127.0.0.1:${server!.port}',
      ),
      identity: LocalMachineIdentity(computerIdFile: identityFile),
    ).discover();

    // Not a reason to hold the window: tiles wait as intent and attach as agents arrive.
    expect(endpoint, isNotNull);
    expect(endpoint!.scanning, isTrue);
  });

  test('rejects non-loopback and mismatched status endpoints', () async {
    const computerId = 'abcdef0123456789abcdef0123456789';
    final identityFile = File('${scratch.path}/computer-id')
      ..writeAsStringSync(computerId);
    final nonLoopback = await LocalCliDiscovery(
      config: const AppConfig(
        apiBaseUrl: 'https://harness-api.autonomous.ai',
        localCliBaseUrl: 'http://example.com:18473',
      ),
      identity: LocalMachineIdentity(computerIdFile: identityFile),
    ).discover();
    expect(nonLoopback, isNull);

    server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
    server!.listen((request) async {
      request.response.headers.contentType = ContentType.json;
      request.response.write(
        jsonEncode({
          'computerId': 'fedcba9876543210fedcba9876543210',
          'localWs': {
            'path': '/api/local-ws',
            'protocolVersion': 1,
            'terminalProtocolVersion': 3,
            'e2ee': false,
          },
        }),
      );
      await request.response.close();
    });
    final mismatch = await LocalCliDiscovery(
      config: AppConfig(
        apiBaseUrl: 'https://harness-api.autonomous.ai',
        localCliBaseUrl: 'http://127.0.0.1:${server!.port}',
      ),
      identity: LocalMachineIdentity(computerIdFile: identityFile),
    ).discover();
    expect(mismatch, isNull);
  });

  test('does not accept missing or malformed computer id files', () async {
    final missing = await LocalMachineIdentity(
      computerIdFile: File('${scratch.path}/missing'),
    ).computerId();
    final malformedFile = File('${scratch.path}/malformed')
      ..writeAsStringSync('not-a-computer-id');
    final malformed = await LocalMachineIdentity(computerIdFile: malformedFile)
        .computerId();
    expect(missing, isNull);
    expect(malformed, isNull);
  });

  test('honors a pinned CLI computer id before the local file', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    final identity = LocalMachineIdentity(
      computerIdFile: File('${scratch.path}/missing'),
      environment: {'ADAPTER_COMPUTER_ID': computerId},
    );
    expect(await identity.computerId(), computerId);
  });

  Map<String, dynamic> readyStatus(
    String computerId, {
    Map<String, dynamic> extra = const {},
  }) => {
    'computerId': computerId,
    'pid': 4242,
    'version': '9.9.9',
    'localWs': {
      'path': '/api/local-ws',
      'protocolVersion': 1,
      'terminalProtocolVersion': 3,
      'e2ee': false,
    },
    ...extra,
  };

  Future<HttpServer> serveStatus(
    int port,
    Map<String, dynamic> Function() body,
  ) async {
    final s = await HttpServer.bind(InternetAddress.loopbackIPv4, port);
    s.listen((request) async {
      request.response.headers.contentType = ContentType.json;
      request.response.write(jsonEncode(body()));
      await request.response.close();
    });
    return s;
  }

  /// A loopback port nothing listens on right now — but that a test can bind later.
  Future<int> freePort() async {
    final probe = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
    final port = probe.port;
    await probe.close(force: true);
    return port;
  }

  LocalCliDiscovery discoveryFor(
    int port,
    File identityFile, {
    Future<void> Function()? spawnCommand,
    Future<void> Function()? stopCommand,
  }) => LocalCliDiscovery(
    config: AppConfig(
      apiBaseUrl: 'https://harness-api.autonomous.ai',
      localCliBaseUrl: 'http://127.0.0.1:$port',
    ),
    identity: LocalMachineIdentity(computerIdFile: identityFile),
    spawnCommand: spawnCommand,
    stopCommand: stopCommand,
  );

  test('supervision asks checkOwner once per daemon pid, and never for one that is not ready', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    final identityFile = File('${scratch.path}/computer-id')
      ..writeAsStringSync(computerId);
    // Not ready: a daemon answering for another computer.
    var status = readyStatus('fedcba9876543210fedcba9876543210');
    server = await serveStatus(await freePort(), () => status);
    final checked = <int>[];
    final discovery = discoveryFor(
      server!.port,
      identityFile,
      spawnCommand: () async =>
          fail('A running daemon must not be spawned over'),
    );
    final timer = discovery.startSupervising(
      checkInterval: const Duration(milliseconds: 20),
      checkOwner: (pid) async => checked.add(pid),
    );
    addTearDown(timer.cancel);
    await Future.delayed(const Duration(milliseconds: 150));
    expect(checked, isEmpty, reason: 'not ready: no owner check');
    status = readyStatus(computerId);
    await Future.delayed(const Duration(milliseconds: 200));
    status = readyStatus(computerId, extra: {'pid': 5353});
    await Future.delayed(const Duration(milliseconds: 200));
    expect(checked, [4242, 5353]);
  });

  test('restart stops the daemon, waits for its port to go quiet, and spawns a new one', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    final identityFile = File('${scratch.path}/computer-id')
      ..writeAsStringSync(computerId);
    final port = await freePort();
    server = await serveStatus(port, () => readyStatus(computerId));
    final calls = <String>[];
    final discovery = discoveryFor(
      port,
      identityFile,
      stopCommand: () async {
        calls.add('stop');
        await server!.close(force: true);
      },
      spawnCommand: () async {
        calls.add('start');
        server = await serveStatus(
          port,
          () => readyStatus(computerId, extra: {'pid': 7777}),
        );
      },
    );
    final probe = await discovery.restart();
    expect(calls, ['stop', 'start']);
    expect(probe.ready, isTrue);
    expect(probe.pid, 7777);
  });

  test(
    'reads real working folders from older local status snapshots',
    () async {
      const computerId = '0123456789abcdef0123456789abcdef';
      final identityFile = File('${scratch.path}/computer-id')
        ..writeAsStringSync(computerId);
      server = await serveStatus(
        await freePort(),
        () => {
          ...readyStatus(computerId),
          'sessions': [
            {'id': 'first', 'cwd': '~/work/project/'},
            {'id': 'same', 'cwd': '${scratch.path}/work/project'},
            {'id': 'missing'},
            {'id': 'relative', 'cwd': 'work/project'},
            {'id': 'other-user', 'cwd': '~other/work'},
            {'id': 'control', 'cwd': '/work/\u0000bad'},
            {'id': '', 'cwd': '/work/ignored'},
          ],
        },
      );
      final endpoint = await LocalCliDiscovery(
        config: AppConfig(
          apiBaseUrl: 'https://fixture.invalid',
          localCliBaseUrl: 'http://127.0.0.1:${server!.port}',
        ),
        identity: LocalMachineIdentity(
          computerIdFile: identityFile,
          environment: {'HOME': scratch.path},
        ),
      ).discover();
      final projects = endpoint!.agentProjects;
      expect(projects.keys, ['first', 'same']);
      expect(projects['first']!.cwd, '${scratch.path}/work/project');
      expect(projects['first']!.name, 'project');
      expect(projects['first'], projects['same']);
      expect(projects['first']!.remote, isNull);
      expect(projects['first']!.branch, isNull);
    },
    skip: Platform.isWindows,
  );

  test(
    'supervision publishes changing folders without reconnecting or spawning',
    () async {
      const computerId = '0123456789abcdef0123456789abcdef';
      final identityFile = File('${scratch.path}/computer-id')
        ..writeAsStringSync(computerId);
      var cwd = '${scratch.path}/before';
      server = await serveStatus(
        await freePort(),
        () => {
          ...readyStatus(computerId),
          'sessions': [
            {'id': 'agent', 'cwd': cwd},
          ],
        },
      );
      var readyCount = 0;
      final before = Completer<void>();
      final after = Completer<void>();
      final discovery = discoveryFor(
        server!.port,
        identityFile,
        spawnCommand: () async => fail('A ready daemon must not be restarted'),
      );
      final timer = discovery.startSupervising(
        checkInterval: const Duration(milliseconds: 20),
        onReady: (_) => readyCount++,
        onSnapshot: (endpoint) {
          final name = endpoint.agentProjects['agent']?.name;
          if (name == 'before' && !before.isCompleted) before.complete();
          if (name == 'after' && !after.isCompleted) after.complete();
        },
      );
      addTearDown(timer.cancel);
      await before.future.timeout(const Duration(seconds: 3));
      cwd = '${scratch.path}/after';
      await after.future.timeout(const Duration(seconds: 3));
      expect(readyCount, 1);
    },
  );

  group('probe', () {
    const computerId = '0123456789abcdef0123456789abcdef';
    late File identityFile;
    setUp(() {
      identityFile = File('${scratch.path}/computer-id')
        ..writeAsStringSync(computerId);
    });

    test(
      'a refused port is DOWN — the one state where spawning helps',
      () async {
        final probe = await discoveryFor(
          await freePort(),
          identityFile,
        ).probe();
        expect(probe.state, LocalCliProbeState.down);
        expect(probe.alive, isFalse);
        expect(probe.endpoint, isNull);
      },
    );

    test('an error status is NOT READY — something owns the port', () async {
      server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
      server!.listen((request) async {
        request.response.statusCode = HttpStatus.serviceUnavailable;
        await request.response.close();
      });
      final probe = await discoveryFor(server!.port, identityFile).probe();
      expect(probe.state, LocalCliProbeState.notReady);
      expect(probe.alive, isTrue);
      expect(probe.reason, contains('503'));
    });

    test(
      'a daemon with no backend link is READY, and says the backend is offline',
      () async {
        // Readiness is the loopback's: a daemon that cannot reach the backend still serves every
        // agent on this computer. `connected:false` used to hold the app on "Starting local
        // service…" for 45s and then an error strip, with tmux and the agents right there.
        server = await serveStatus(
          0,
          () => readyStatus(
            computerId,
            extra: {'connected': false, 'machineId': 'm' * 32},
          ),
        );
        final probe = await discoveryFor(server!.port, identityFile).probe();
        expect(probe.state, LocalCliProbeState.ready);
        expect(probe.endpoint!.backendOnline, isFalse);
        expect(probe.endpoint!.machineId, 'm' * 32);
        expect(probe.pid, 4242);
        expect(probe.version, '9.9.9');
      },
    );

    test(
      'discover() still hands back the endpoint while the backend is down',
      () async {
        // `discover()` is what the machine refresh applies to this computer's row. When it returned
        // null on `connected:false`, `_applyLocalTransport` read that as "the CLI is offline" and put
        // the LOCAL terminal into localOffline — a daemon that lost its cloud link took the terminal
        // on the same desk down with it.
        server = await serveStatus(
          0,
          () => readyStatus(computerId, extra: {'connected': false}),
        );
        final endpoint = await discoveryFor(
          server!.port,
          identityFile,
        ).discover(expectedComputerId: computerId);
        expect(endpoint, isNotNull);
        expect(endpoint!.backendOnline, isFalse);
      },
    );

    test(
      'a daemon that reports no `connected` (older CLI) counts as online',
      () async {
        server = await serveStatus(0, () => readyStatus(computerId));
        final probe = await discoveryFor(server!.port, identityFile).probe();
        expect(probe.state, LocalCliProbeState.ready);
        expect(probe.endpoint!.backendOnline, isTrue);
        expect(probe.endpoint!.machineId, isNull);
      },
    );

    test(
      'a daemon still scanning for agents is READY, marked scanning',
      () async {
        server = await serveStatus(
          0,
          () => readyStatus(computerId, extra: {'discoveryReady': false}),
        );
        final probe = await discoveryFor(server!.port, identityFile).probe();
        expect(probe.state, LocalCliProbeState.ready);
        expect(probe.endpoint!.scanning, isTrue);
        expect(probe.pid, 4242);
        expect(probe.version, '9.9.9');
      },
    );

    test(
      'a daemon that has finished scanning is not marked scanning',
      () async {
        server = await serveStatus(
          0,
          () => readyStatus(computerId, extra: {'discoveryReady': true}),
        );
        final probe = await discoveryFor(server!.port, identityFile).probe();
        expect(probe.state, LocalCliProbeState.ready);
        expect(probe.endpoint!.scanning, isFalse);
      },
    );

    test('a daemon for another computer is NOT READY, not down', () async {
      server = await serveStatus(
        0,
        () => readyStatus('fedcba9876543210fedcba9876543210'),
      );
      final probe = await discoveryFor(server!.port, identityFile).probe();
      expect(probe.state, LocalCliProbeState.notReady);
      expect(probe.reason, 'a daemon for a different computer');
    });

    test('a full status is READY with the endpoint', () async {
      server = await serveStatus(0, () => readyStatus(computerId));
      final probe = await discoveryFor(server!.port, identityFile).probe();
      expect(probe.state, LocalCliProbeState.ready);
      expect(probe.endpoint?.computerId, computerId);
      expect(
        probe.endpoint?.wsUri.toString(),
        'ws://127.0.0.1:${server!.port}/api/local-ws',
      );
      expect(probe.pid, 4242);
    });
  });

  test('ensureRunning returns the endpoint immediately when the daemon is already up, '
      'never needing to spawn `harness start`', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    final identityFile = File('${scratch.path}/computer-id')
      ..writeAsStringSync(computerId);
    server = await serveStatus(0, () => readyStatus(computerId));
    var spawned = false;
    final probe = await discoveryFor(
      server!.port,
      identityFile,
      spawnCommand: () async {
        spawned = true;
      },
    ).ensureRunning();
    expect(probe.state, LocalCliProbeState.ready);
    expect(probe.endpoint?.computerId, computerId);
    expect(spawned, isFalse);
  });

  test('ensureRunning does not wait for a daemon that is still scanning for agents', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    final identityFile = File('${scratch.path}/computer-id')
      ..writeAsStringSync(computerId);
    server = await serveStatus(
      0,
      () => readyStatus(computerId, extra: {'discoveryReady': false}),
    );
    final watch = Stopwatch()..start();
    final probe = await discoveryFor(
      server!.port,
      identityFile,
    ).ensureRunning(readyTimeout: const Duration(seconds: 5));
    expect(probe.state, LocalCliProbeState.ready);
    expect(probe.endpoint!.scanning, isTrue);
    expect(watch.elapsedMilliseconds, lessThan(1000));
  });

  test('ensureRunning waits for a daemon that answers but is not ready, without spawning', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    final identityFile = File('${scratch.path}/computer-id')
      ..writeAsStringSync(computerId);
    var scanned = false;
    // Answers, but not ready yet: for another computer until it flips.
    server = await serveStatus(
      0,
      () => readyStatus(
        scanned ? computerId : 'fedcba9876543210fedcba9876543210',
      ),
    );
    var spawned = false;
    final discovery = discoveryFor(
      server!.port,
      identityFile,
      spawnCommand: () async {
        spawned = true;
      },
    );
    Future.delayed(const Duration(milliseconds: 700), () => scanned = true);
    final probe = await discovery.ensureRunning(
      readyTimeout: const Duration(seconds: 5),
    );
    expect(probe.state, LocalCliProbeState.ready);
    expect(spawned, isFalse, reason: 'a running daemon is never spawned over');
  });

  test('ensureRunning gives up on a daemon that never becomes ready and says which state it is in', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    final identityFile = File('${scratch.path}/computer-id')
      ..writeAsStringSync(computerId);
    server = await serveStatus(
      0,
      () => readyStatus('fedcba9876543210fedcba9876543210'),
    );
    var spawned = false;
    final probe = await discoveryFor(
      server!.port,
      identityFile,
      spawnCommand: () async {
        spawned = true;
      },
    ).ensureRunning(readyTimeout: const Duration(milliseconds: 600));
    expect(probe.state, LocalCliProbeState.notReady);
    expect(probe.reason, 'a daemon for a different computer');
    expect(spawned, isFalse);
  });

  test('ensureRunning spawns once when the port is quiet and returns ready once the daemon binds', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    final identityFile = File('${scratch.path}/computer-id')
      ..writeAsStringSync(computerId);
    final port = await freePort();
    var spawnCount = 0;
    final discovery = discoveryFor(
      port,
      identityFile,
      spawnCommand: () async {
        spawnCount++;
        server = await serveStatus(
          port,
          () => readyStatus(computerId),
        ); // "harness start" binds the port
      },
    );
    final probe = await discovery.ensureRunning(
      timeout: const Duration(seconds: 3),
    );
    expect(probe.state, LocalCliProbeState.ready);
    expect(spawnCount, 1);
  });

  test('runHarnessStart treats a non-zero exit as a failed spawn', () async {
    final failing = HarnessCliRunner(
      runProcess: (exe, args, {environment}) async =>
          ProcessResult(1, 1, '', 'daemon spawn lock is held'),
    );
    await expectLater(
      runHarnessStart(failing),
      throwsA(isA<ProcessException>()),
    );
    final fine = HarnessCliRunner(
      runProcess: (exe, args, {environment}) async =>
          ProcessResult(1, 0, 'already running', ''),
    );
    await runHarnessStart(fine);
  });

  test('inSpawnSlot is :10–:20 of every minute, clear of the CLI update slot at :45', () {
    DateTime at(int second) => DateTime(2026, 9, 15, 10, 0, second);
    expect(inSpawnSlot(at(9)), isFalse);
    expect(inSpawnSlot(at(10)), isTrue);
    expect(inSpawnSlot(at(15)), isTrue);
    expect(inSpawnSlot(at(19)), isTrue);
    expect(inSpawnSlot(at(20)), isFalse);
    expect(inSpawnSlot(at(45)), isFalse);
    expect(inSpawnSlot(at(0), second: 5, window: 10), isTrue);
  });

  test('startSupervising holds a spawn outside the slot and takes it on the first tick inside', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    var running = false;
    var spawnCount = 0;
    var slotOpen = false;
    final discovery = _SupervisionProbe(
      readProbe: () async => running
          ? LocalCliProbe.ready(LocalCliEndpoint(
              computerId: computerId,
              wsUri: Uri.parse('ws://127.0.0.1/api/local-ws'),
              protocolVersion: localWsProtocolVersion,
              terminalProtocolVersion: localTerminalProtocolVersion,
            ))
          : const LocalCliProbe.down('fixture daemon is down'),
      spawnCommand: () async {
        spawnCount++;
        running = true;
      },
    );

    final timer = discovery.startSupervising(
      checkInterval: const Duration(milliseconds: 20),
      graceStep: const Duration(milliseconds: 10),
      graceWindow: const Duration(milliseconds: 100),
      initialBackoff: const Duration(milliseconds: 200),
      maxBackoff: const Duration(milliseconds: 200),
      spawnAllowedAt: (_) => slotOpen,
    );
    addTearDown(timer.cancel);

    // Down for many ticks, but the slot is shut: nothing is spawned, and nothing is backed off
    // either — the moment the slot opens the spawn is immediate.
    await Future.delayed(const Duration(milliseconds: 200));
    expect(spawnCount, 0);
    slotOpen = true;
    await Future.delayed(const Duration(milliseconds: 60));
    expect(spawnCount, 1);
    expect(running, isTrue);
  });

  // `harness uninstall` stops the daemon, then removes its files (on Windows after it has exited): a daemon
  // started in between holds them and undoes the uninstall.
  test(
    'startSupervising starts no daemon while harness uninstall is at work',
    () async {
      var uninstalling = true;
      var spawnCount = 0;
      final discovery = _SupervisionProbe(
        readProbe: () async =>
            const LocalCliProbe.down('fixture daemon is down'),
        spawnCommand: () async => spawnCount++,
      );
      final timer = discovery.startSupervising(
        checkInterval: const Duration(milliseconds: 20),
        graceStep: const Duration(milliseconds: 10),
        graceWindow: const Duration(milliseconds: 20),
        uninstalling: () => uninstalling,
      );
      addTearDown(timer.cancel);

      await Future.delayed(const Duration(milliseconds: 150));
      expect(spawnCount, 0);

      uninstalling = false;
      await Future.delayed(const Duration(milliseconds: 150));
      expect(spawnCount, greaterThan(0));
    },
  );

  test('startSupervising spawns harness start while down, and stops once discovery succeeds', () async {
    const computerId = '0123456789abcdef0123456789abcdef';
    var running = false;
    var spawnCount = 0;
    final readies = <LocalCliEndpoint>[];
    final discovery = _SupervisionProbe(
      readProbe: () async => running
          ? LocalCliProbe.ready(LocalCliEndpoint(
              computerId: computerId,
              wsUri: Uri.parse('ws://127.0.0.1/api/local-ws'),
              protocolVersion: localWsProtocolVersion,
              terminalProtocolVersion: localTerminalProtocolVersion,
            ))
          : const LocalCliProbe.down('fixture daemon is down'),
      spawnCommand: () async {
        spawnCount++;
        running = true; // simulate `harness start` succeeding
      },
    );

    final timer = discovery.startSupervising(
      checkInterval: const Duration(milliseconds: 20),
      graceStep: const Duration(milliseconds: 10),
      graceWindow: const Duration(milliseconds: 100),
      initialBackoff: const Duration(milliseconds: 200),
      maxBackoff: const Duration(milliseconds: 200),
      onReady: readies.add,
    );
    addTearDown(timer.cancel);

    await Future.delayed(const Duration(milliseconds: 120));
    expect(spawnCount, 1);
    expect(running, isTrue);

    // Discovery now succeeds on every tick — no further spawn should ever happen, and the
    // transition into ready was reported exactly once.
    await Future.delayed(const Duration(milliseconds: 200));
    expect(spawnCount, 1);
    expect(readies, hasLength(1));
    expect(readies.single.computerId, computerId);
  });

  test(
    'startSupervising reports the backend link on every change, not every tick',
    () {
      fakeAsync((clock) {
        var connected = false;
        final discovery = _SupervisionProbe(
          readProbe: () async => LocalCliProbe.ready(
            LocalCliEndpoint(
              computerId: '0123456789abcdef0123456789abcdef',
              wsUri: Uri.parse('ws://127.0.0.1/api/local-ws'),
              protocolVersion: localWsProtocolVersion,
              terminalProtocolVersion: localTerminalProtocolVersion,
              backendOnline: connected,
            ),
          ),
          spawnCommand: () async {},
        );
        final seen = <bool>[];
        const interval = Duration(milliseconds: 20);
        final timer = discovery.startSupervising(
          checkInterval: interval,
          onBackendOnline: seen.add,
        );
        void ticks() {
          for (var i = 0; i < 6; i++) {
            clock.elapse(interval);
            clock.flushMicrotasks();
          }
        }

        try {
          ticks();
          expect(seen, [false], reason: 'offline at first sight, said once');
          connected = true;
          ticks();
          expect(seen, [false, true], reason: 'the reconnect, said once');
        } finally {
          timer.cancel();
          clock.flushMicrotasks();
        }
      });
    },
  );

  test(
    'startSupervising never spawns over a daemon that answers but is not ready',
    () async {
      var spawnCount = 0;
      final discovery = _SupervisionProbe(
        readProbe: () async => const LocalCliProbe.notReady('startup scan'),
        spawnCommand: () async {
          spawnCount++;
        },
      );

      final timer = discovery.startSupervising(
        checkInterval: const Duration(milliseconds: 20),
        graceStep: const Duration(milliseconds: 10),
        graceWindow: const Duration(milliseconds: 50),
        initialBackoff: const Duration(milliseconds: 20),
        maxBackoff: const Duration(milliseconds: 20),
        stillSignedIn: () async => true,
      );
      addTearDown(timer.cancel);

      await Future.delayed(const Duration(milliseconds: 400));
      expect(
        spawnCount,
        0,
        reason: 'it is running; a second one can only fail on the port',
      );
    },
  );

  test('startSupervising waits for more than one quiet tick before spawning into an update gap', () {
    fakeAsync((clock) {
      final ready = LocalCliProbe.ready(
        LocalCliEndpoint(
          computerId: '0123456789abcdef0123456789abcdef',
          wsUri: Uri.parse('ws://127.0.0.1/api/local-ws'),
          protocolVersion: localWsProtocolVersion,
          terminalProtocolVersion: localTerminalProtocolVersion,
        ),
      );
      const down = LocalCliProbe.down('handoff gap');
      var seen = ready;
      var spawnCount = 0;
      final discovery = _SupervisionProbe(
        readProbe: () async => seen,
        spawnCommand: () async {
          spawnCount++;
        },
      );
      const interval = Duration(milliseconds: 20);
      final timer = discovery.startSupervising(
        checkInterval: interval,
        // This fixture tests consecutive probes, not grace/backoff durations.
        graceWindow: Duration.zero,
        initialBackoff: Duration.zero,
        maxBackoff: Duration.zero,
        spawnAfter: 3,
        stillSignedIn: () async => true,
      );
      void tick() {
        clock.elapse(interval);
        clock.flushMicrotasks();
      }

      try {
        tick();
        // Real socket/timer delays can stretch a nominal 30 ms gap on busy
        // runners. Specify the observations: two quiet ticks, then recovery.
        seen = down;
        tick();
        tick();
        expect(spawnCount, 0, reason: 'a short gap is a handoff, not a crash');
        seen = ready;
        tick();
        expect(spawnCount, 0);

        // Recovery must reset the count. Only three NEW consecutive quiet
        // probes may start a replacement daemon.
        seen = down;
        tick();
        tick();
        expect(
          spawnCount,
          0,
          reason: 'quiet ticks before recovery do not accumulate',
        );
        tick();
        expect(
          spawnCount,
          1,
          reason: 'confirmed failure starts one replacement',
        );
      } finally {
        timer.cancel();
      }
    });
  });

  test('startSupervising backs off between failed spawn attempts instead of spawning every tick', () async {
    var spawnCount = 0;
    final discovery = _SupervisionProbe(
      readProbe: () async => const LocalCliProbe.down('fixture daemon is down'),
      spawnCommand: () async {
        spawnCount++;
      },
    );

    final timer = discovery.startSupervising(
      checkInterval: const Duration(milliseconds: 20),
      graceStep: const Duration(milliseconds: 10),
      graceWindow: const Duration(milliseconds: 50),
      initialBackoff: const Duration(milliseconds: 150),
      maxBackoff: const Duration(milliseconds: 150),
    );
    addTearDown(timer.cancel);

    await Future.delayed(const Duration(milliseconds: 500));
    // Without backoff, ~500ms / 20ms checkInterval would spawn on nearly every tick (~25 times).
    // With backoff (each failed attempt costs ~50ms grace window + a 150ms floor before the next),
    // attempts are bounded to roughly 500 / 200 ≈ 2-3.
    expect(spawnCount, greaterThan(0));
    expect(spawnCount, lessThan(6));
  });

  // Signed-out daemons now serve local agents in guest mode, so supervision must continue.
  test(
    'startSupervising keeps the guest daemon alive after sign-out',
    () async {
      var spawnCount = 0;
      var signedOutCalls = 0;
      final discovery = _SupervisionProbe(
        readProbe: () async => const LocalCliProbe.down('fixture daemon is down'),
        spawnCommand: () async {
          spawnCount++;
        },
      );

      final timer = discovery.startSupervising(
        checkInterval: const Duration(milliseconds: 20),
        graceStep: const Duration(milliseconds: 10),
        graceWindow: const Duration(milliseconds: 50),
        initialBackoff: const Duration(milliseconds: 20),
        maxBackoff: const Duration(milliseconds: 20),
        stillSignedIn: () async => false,
        onSignedOut: () => signedOutCalls++,
      );
      addTearDown(timer.cancel);

      await Future.delayed(const Duration(milliseconds: 300));

      expect(spawnCount, greaterThan(0));
      expect(
        spawnCount,
        lessThan(6),
        reason: 'guest restarts retain the backoff',
      );
      expect(
        signedOutCalls,
        spawnCount,
        reason: 'auth is checked once per spawn attempt',
      );
      expect(timer.isActive, isTrue);
    },
  );

  test(
    'startSupervising keeps respawning while the CLI is still signed in',
    () async {
      var spawnCount = 0;
      var signedOutCalls = 0;
      final discovery = _SupervisionProbe(
        readProbe: () async => const LocalCliProbe.down('fixture daemon is down'),
        spawnCommand: () async {
          spawnCount++;
        },
      );

      final timer = discovery.startSupervising(
        checkInterval: const Duration(milliseconds: 20),
        graceStep: const Duration(milliseconds: 10),
        graceWindow: const Duration(milliseconds: 50),
        initialBackoff: const Duration(milliseconds: 20),
        maxBackoff: const Duration(milliseconds: 20),
        stillSignedIn: () async => true,
        onSignedOut: () => signedOutCalls++,
      );
      addTearDown(timer.cancel);

      await Future.delayed(const Duration(milliseconds: 300));

      // A daemon that merely crashed, or was stopped by hand, must still be brought back.
      expect(spawnCount, greaterThan(0));
      expect(signedOutCalls, 0);
      expect(timer.isActive, isTrue);
    },
  );

  // `harness auth status` sat out a refresh lock a dying daemon had left (30s) and threw on the app's
  // own timeout; the throw skipped the spawn and the local terminals stayed dark (2026-09-28 18:47).
  for (final (name, check) in <(String, Future<bool> Function())>[
    (
      'fails',
      () async => throw ProcessException(
        'harness',
        const [],
        'did not finish within 30s',
      ),
    ),
    ('never answers', () => Completer<bool>().future),
  ]) {
    test('startSupervising still respawns when the auth check $name', () async {
      var spawnCount = 0;
      var signedOutCalls = 0;
      final discovery = _SupervisionProbe(
        readProbe: () async => const LocalCliProbe.down('fixture daemon is down'),
        spawnCommand: () async {
          spawnCount++;
        },
      );

      final timer = discovery.startSupervising(
        checkInterval: const Duration(milliseconds: 20),
        graceStep: const Duration(milliseconds: 10),
        graceWindow: const Duration(milliseconds: 50),
        initialBackoff: const Duration(milliseconds: 20),
        maxBackoff: const Duration(milliseconds: 20),
        stillSignedIn: check,
        onSignedOut: () => signedOutCalls++,
      );
      addTearDown(timer.cancel);

      await Future.delayed(const Duration(milliseconds: 300));

      expect(spawnCount, greaterThan(0));
      expect(
        signedOutCalls,
        0,
        reason: 'an auth check with no answer is not a sign-out',
      );
    });
  }

  test('startSupervising spawns without waiting for a slow auth check, and still reports its sign-out', () async {
    var spawnCount = 0;
    var signedOutCalls = 0;
    final answer = Completer<bool>();
    final discovery = _SupervisionProbe(
      readProbe: () async => const LocalCliProbe.down('fixture daemon is down'),
      spawnCommand: () async {
        spawnCount++;
      },
    );

    final timer = discovery.startSupervising(
      checkInterval: const Duration(milliseconds: 20),
      graceStep: const Duration(milliseconds: 10),
      graceWindow: const Duration(milliseconds: 50),
      initialBackoff: const Duration(seconds: 10),
      maxBackoff: const Duration(seconds: 10),
      stillSignedIn: () => answer.future,
      onSignedOut: () => signedOutCalls++,
    );
    addTearDown(timer.cancel);

    await Future.delayed(const Duration(milliseconds: 150));
    expect(spawnCount, 1, reason: 'the spawn does not wait on the auth check');
    expect(signedOutCalls, 0);

    answer.complete(false);
    await Future.delayed(Duration.zero);
    expect(signedOutCalls, 1, reason: 'a late answer is still told');
  });
}

/// Control probe results while exercising the real supervisor and its timers.
class _SupervisionProbe extends LocalCliDiscovery {
  _SupervisionProbe({
    required this.readProbe,
    required Future<void> Function() spawnCommand,
  }) : super(config: AppConfig.dev, spawnCommand: spawnCommand);

  final Future<LocalCliProbe> Function() readProbe;

  @override
  Future<LocalCliProbe> probe({String? expectedComputerId}) => readProbe();
}