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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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();
}