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.

fix(desktop): local terminals no longer stick on "Offline" after a sleep/wake

0xken15a2ae2ca04d0e
diff --git a/desktop/lib/core/sleep_aware.dart b/desktop/lib/core/sleep_aware.dart
new file mode 100644
index 000000000..8bfd9eb58
--- /dev/null
+++ b/desktop/lib/core/sleep_aware.dart
@@ -0,0 +1,91 @@
+import 'dart:async';
+import 'dart:math';
+
+/// Deadlines that a closed lid does not spend.
+///
+/// Dart's timers do not stop while a Mac sleeps: a `Timer(10s)` armed before the lid closed fires on
+/// the first event-loop turn after it opens, however long the machine was asleep. Measured
+/// 2026-09-29: an `agents_list` asked of this computer's own daemon "timed out" at 19:06:11, the
+/// instant the machine woke, and its answer arrived at 19:06:12 — and that false timeout marked the
+/// local machine offline over a socket that had never dropped. `cli/src/lib/sleepAware.ts` is the
+/// same idea on the daemon's side.
+///
+/// No clock is read. A periodic timer that comes due late runs its callback ONCE and skips the
+/// periods it missed (the VM advances `Timer.tick` instead of replaying them), so counting only the
+/// callbacks that arrived on time counts time the process was actually running. Under `fakeAsync`
+/// every period runs on time, which is why tests that pump through a timeout still see it fire.
+class SleepAwareTimer implements Timer {
+ /// Runs [callback] once [duration] of AWAKE time has passed. Counted in at most one-second steps, so
+ /// a long deadline is kept to the second and a short one exactly.
+ SleepAwareTimer(Duration duration, void Function() callback) {
+ if (duration <= Duration.zero) {
+ _timer = Timer(Duration.zero, callback);
+ return;
+ }
+ final steps = max(
+ 1,
+ (duration.inMicroseconds / _maxStep.inMicroseconds).ceil(),
+ );
+ final step = Duration(microseconds: duration.inMicroseconds ~/ steps);
+ var lastTick = 0;
+ _timer = Timer.periodic(step, (timer) {
+ // A step the process slept through (or sat blocked through) is not counted — not even the
+ // last one, which is what would otherwise make a short deadline fire straight after a wake.
+ final onTime = !sleptSinceTick(timer, lastTick);
+ lastTick = timer.tick;
+ if (!onTime) return;
+ _counted++;
+ if (_counted < steps) return;
+ timer.cancel();
+ callback();
+ });
+ }
+
+ static const _maxStep = Duration(seconds: 1);
+
+ late final Timer _timer;
+ int _counted = 0;
+
+ @override
+ void cancel() => _timer.cancel();
+
+ @override
+ bool get isActive => _timer.isActive;
+
+ /// Steps counted so far — awake steps, unlike the underlying timer's `tick`.
+ @override
+ int get tick => _counted;
+}
+
+/// Whether a periodic timer's callback arrived after the process slept through at least one of its
+/// periods: the VM skipped them, so [tick] moved by more than one since [previousTick].
+bool sleptSinceTick(Timer timer, int previousTick) =>
+ timer.tick - previousTick > 1;
+
+/// [Future.timeout], but counting only awake time (see [SleepAwareTimer]).
+Future<T> awakeTimeout<T>(
+ Future<T> future,
+ Duration timeout, {
+ required T Function() onTimeout,
+}) {
+ final result = Completer<T>();
+ final timer = SleepAwareTimer(timeout, () {
+ if (result.isCompleted) return;
+ try {
+ result.complete(onTimeout());
+ } catch (error, stack) {
+ result.completeError(error, stack);
+ }
+ });
+ future.then(
+ (value) {
+ timer.cancel();
+ if (!result.isCompleted) result.complete(value);
+ },
+ onError: (Object error, StackTrace stack) {
+ timer.cancel();
+ if (!result.isCompleted) result.completeError(error, stack);
+ },
+ );
+ return result.future;
+}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index d5d1f81ef..13d407dfe 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -29,6 +29,7 @@ import '../auth/cli_login.dart';
import '../bootstrap/environment_provisioner.dart';
import '../core/viewer_mode.dart';
import '../core/config.dart';
+import '../core/sleep_aware.dart';
import '../core/agent_git_context.dart';
import '../core/agent_names.dart';
import '../core/agent_preference.dart';
@@ -728,6 +729,10 @@ class AppNotifier extends ChangeNotifier {
);
final Map<String, Timer> _offlineRetryTimers = {};
+
+ /// One reload per machine, owed after this computer's daemon was too slow to answer its list while
+ /// still on the socket — the error strip says "retrying", and this is the retry.
+ final Map<String, Timer> _slowReloadTimers = {};
// Periodic retry for a machine the relay reported NO_PEER_LINK for — a `harness link connect` run
// in a terminal (or another app instance) has no way to notify this one, so this is what makes the
// app pick up a fresh link within a few seconds instead of only on the next manual click/restart.
@@ -2554,7 +2559,7 @@ class AppNotifier extends ChangeNotifier {
// not only the local one — a successful select IS the machine being reachable again, and
// this is what lets a pending agent (captured below on disconnect) reattach automatically
// instead of leaving the user stuck on the empty "select a machine" placeholder.
- unawaited(_applyNodeStatus(machine, true));
+ unawaited(_applyNodeStatus(machine, true, why: 'socket connected'));
unawaited(_loadMachineData(machine, force: true));
// An install this socket was carrying when it dropped went on without it
// (the daemon never heard the socket go); its outcome is in the list, so
@@ -3901,6 +3906,16 @@ class AppNotifier extends ChangeNotifier {
void _updateLocalProjectSnapshot(LocalCliEndpoint endpoint) {
if (_disposed) return;
+ // Every five seconds the daemon answers ready: the one steady witness that this computer's
+ // machine is up, whatever a timeout or a missed probe said. It used to skip a row whose endpoint
+ // had been cleared — the very row that needed it.
+ for (final machine in machineStates.values) {
+ if (machine.localOnly &&
+ _normalizeComputerId(machine.machine.computerId) ==
+ endpoint.computerId) {
+ _healLocalMachine(machine, 'daemon ready', endpoint: endpoint);
+ }
+ }
var changed = false;
for (final machine in machineStates.values) {
final previous = machine.localEndpoint;
@@ -4640,7 +4655,13 @@ class AppNotifier extends ChangeNotifier {
// purpose: the retry loop's own close() lands as a plain `disconnected` too. needsLink is
// set by onLocalFailure, which runs before this branch for 4404 (see WsConn._onDone).
if (!machine.needsLink) {
- unawaited(_applyNodeStatus(machine, false));
+ unawaited(
+ _applyNodeStatus(
+ machine,
+ false,
+ why: 'socket ${nextStatus.name}',
+ ),
+ );
}
}
notifyListeners();
@@ -4879,16 +4900,24 @@ class AppNotifier extends ChangeNotifier {
: MachineTransportMode.localOffline;
} else if (state.localOnly &&
localEndpoint == null &&
- state.localEndpoint != null &&
- state.connectionStatus == ConnectionStatus.connected) {
+ (_localLinkLive(state) ||
+ (state.localEndpoint != null &&
+ state.connectionStatus == ConnectionStatus.connected))) {
// The probe found nothing this time (the daemon mid-restart, or mid-scan) but the socket to
// it is open and answering right now — the socket is the better witness. Keep the endpoint
// it was dialed through; demoting a live connection to "offline" on a missed probe is what
- // took a working terminal's tiles dark.
+ // took a working terminal's tiles dark. The probe that missed may even have been taken
+ // before the socket answered and applied after (a refresh holds it across its fetch), so the
+ // live socket is checked itself rather than the stored status, and a cleared endpoint comes
+ // back from the one the app dialed.
+ state.localEndpoint ??= _cliEndpoint;
state.transportMode = MachineTransportMode.localPlaintext;
} else if (state.localOnly) {
// The token still identifies this as local, but the CLI is offline or
// failed its identity/capability check. Never fall back to cloud E2EE.
+ if (state.localEndpoint != null || state.nodeOnline != false) {
+ _logLocalMachine(state, 'offline (daemon probe found nothing)');
+ }
state.localEndpoint = null;
state.transportMode = MachineTransportMode.localOffline;
state.nodeOnline = false;
@@ -5207,6 +5236,10 @@ class AppNotifier extends ChangeNotifier {
timer.cancel();
}
_offlineRetryTimers.clear();
+ for (final timer in _slowReloadTimers.values) {
+ timer.cancel();
+ }
+ _slowReloadTimers.clear();
_offlinePollsInFlight.clear();
_offlineRecoveryInFlight.clear();
}
@@ -5637,6 +5670,16 @@ class AppNotifier extends ChangeNotifier {
}
}
+ /// Why the last offline poll of this computer's machine came back empty — logged once per change,
+ /// not every five seconds, so a poll that keeps missing leaves one line saying why.
+ String? _localPollMiss;
+
+ void _noteLocalPollMiss(MachineState machine, String why) {
+ if (_localPollMiss == why) return;
+ _localPollMiss = why;
+ _logLocalMachine(machine, 'still offline: $why');
+ }
+
Future<void> _pollOfflineMachine(String machineId) async {
final machine = machineStates[machineId];
if (machine == null ||
@@ -5648,17 +5691,28 @@ class AppNotifier extends ChangeNotifier {
_offlinePollsInFlight.add(machineId);
try {
if (machine.isLocalMachine) {
+ // The socket first: a daemon answering on it needs no probe to prove it is there.
+ if (_healLocalMachine(machine, 'offline poll, socket live')) {
+ _localPollMiss = null;
+ return;
+ }
final discovery = _discovery;
final localComputerId = await discovery.computerId();
if (localComputerId == null ||
_normalizeComputerId(machine.machine.computerId) !=
localComputerId) {
+ _noteLocalPollMiss(machine, 'computer id does not match');
return;
}
final endpoint = await discovery.discover(
expectedComputerId: localComputerId,
);
- if (endpoint == null || endpoint.computerId != localComputerId) return;
+ if (endpoint == null || endpoint.computerId != localComputerId) {
+ _noteLocalPollMiss(machine, 'daemon probe found nothing');
+ return;
+ }
+ _localPollMiss = null;
+ _logLocalMachine(machine, 'online (offline poll found the daemon)');
machine.localEndpoint = endpoint;
// The gate never got here (the daemon was down at boot): this is the endpoint it would have
// recorded, and every later dial reads it.
@@ -6357,9 +6411,24 @@ class AppNotifier extends ChangeNotifier {
if (machine.machine.isShared) return;
if (!_machineWorkCurrent(machine, _authRevision)) return;
if (machine.agentLoadStatus == AgentLoadStatus.loaded && !force) return;
+ if (machine.isLocalMachine &&
+ !machine.usesLocalTransport &&
+ _localLinkLive(machine) &&
+ _cliEndpoint != null) {
+ // The endpoint was cleared by a probe that missed, but the socket to the daemon is answering:
+ // the socket is the better witness. Restore what it was dialed through and load.
+ machine.localEndpoint ??= _cliEndpoint;
+ _logLocalMachine(machine, 'endpoint restored for a load (socket live)');
+ }
if (machine.isLocalMachine && !machine.usesLocalTransport) {
machine.transportMode = MachineTransportMode.localOffline;
+ if (machine.nodeOnline != false) {
+ _logLocalMachine(machine, 'offline (no local endpoint)');
+ }
machine.nodeOnline = false;
+ // Offline with nothing to bring it back used to be possible from here: the poll that
+ // re-probes the daemon is what ends this state.
+ _startOfflineRetry(machine);
machine.agentsRefreshing = false;
machine.agentsLoadError = 'Harness is offline — run harness login';
machine.agentLoadStatus = machine.agents.isEmpty
@@ -6400,10 +6469,11 @@ class AppNotifier extends ChangeNotifier {
}
// Keep the inventory's existing total budget, including connection time.
// Capabilities get their own budget only once the handshake is complete.
- final remaining = inventoryTimeout - deadline.elapsed;
- if (remaining <= Duration.zero) {
- throw const WsRequestTimeout('agents_list');
- }
+ // Never less than a few seconds for the list itself: `deadline` is wall time, and a wait that
+ // spanned a sleep (the wait itself counts awake time) would otherwise leave the list none.
+ final left = inventoryTimeout - deadline.elapsed;
+ const floor = Duration(seconds: 3);
+ final remaining = left < floor ? floor : left;
final capabilities = _loadTerminalCapabilities(
machine,
connection,
@@ -6452,12 +6522,34 @@ class AppNotifier extends ChangeNotifier {
// the remote node itself has stopped answering — exactly what a REST-status flip to offline
// means elsewhere, so route it through _applyNodeStatus (not just `nodeOnline = false`) so the
// pending agent gets captured for auto-reattach, same as any other offline detection path.
- if (error is WsRequestTimeout) {
+ if (error is WsRequestTimeout && _localLinkLive(machine)) {
+ // This computer's daemon is still on the socket: it is slow, not gone (just after a wake
+ // it can take seconds to answer). Calling it offline here is what left local tiles dark
+ // over a live socket until the app was restarted (2026-09-29). The minute's agent sync
+ // asks again; a daemon that really died closes the socket, and that path marks it.
+ machine.agentsLoadError = 'Harness is not responding — retrying';
+ _logLocalMachine(machine, 'slow to answer ${error.type}; kept online');
+ final machineId = machine.machine.machineId;
+ _slowReloadTimers[machineId] ??= SleepAwareTimer(
+ const Duration(seconds: 5),
+ () {
+ _slowReloadTimers.remove(machineId);
+ if (_disposed ||
+ !identical(machineStates[machineId], machine) ||
+ !_localLinkLive(machine)) {
+ return;
+ }
+ unawaited(_loadMachineData(machine, force: true));
+ },
+ );
+ } else if (error is WsRequestTimeout) {
machine.agentsLoadError = machine.isLocalMachine
? 'Harness is offline — run harness login'
: 'Harness is offline — run harness start on that machine';
if (machine.nodeOnline != false) {
- unawaited(_applyNodeStatus(machine, false));
+ unawaited(
+ _applyNodeStatus(machine, false, why: '${error.type} timed out'),
+ );
}
if (!machine.isLocalMachine) {
// The relay's cached upstream session can go stale at the E2EE-session layer without the
@@ -6993,7 +7085,11 @@ class AppNotifier extends ChangeNotifier {
final pending = machine.pendingOfflineAgentId;
if (pending != null && !nextIds.contains(pending)) {
machine.pendingOfflineAgentId = null;
- _stopOfflineRetry(machine.machine.machineId);
+ // A local machine is polled back from offline with or without a pending agent; stopping the
+ // poll here left it offline with nothing to end that.
+ if (!machine.isLocalMachine || machine.nodeOnline != false) {
+ _stopOfflineRetry(machine.machine.machineId);
+ }
}
if (machine.activeAgentId != null &&
!nextIds.contains(machine.activeAgentId) &&
@@ -7131,7 +7227,9 @@ class AppNotifier extends ChangeNotifier {
if (machine.activeAgentId == agentId) machine.activeAgentId = null;
if (machine.pendingOfflineAgentId == agentId) {
machine.pendingOfflineAgentId = null;
- _stopOfflineRetry(machine.machine.machineId);
+ if (!machine.isLocalMachine || machine.nodeOnline != false) {
+ _stopOfflineRetry(machine.machine.machineId);
+ }
}
// Every tile showing it, not just the focused one — and without
// `terminal_close`, which would be addressed to an agent the machine has
@@ -9905,11 +10003,94 @@ class AppNotifier extends ChangeNotifier {
}
}
- Future<void> _applyNodeStatus(MachineState machine, bool online) async {
+ /// One line per change in this computer's own machine state, with why — the trail that was
+ /// missing when a local tile sat on "Offline" over a live socket until the app was restarted
+ /// (2026-09-29 19:13): nothing then said which of four writers had put it there.
+ void _logLocalMachine(MachineState machine, String event) {
+ final id = machine.machine.machineId;
+ appLog.info(
+ 'machine',
+ 'local ${id.length > 8 ? id.substring(0, 8) : id}: $event',
+ );
+ }
+
+ /// This computer's own daemon is answering on its socket right now.
+ ///
+ /// For the local machine that socket IS the machine: the daemon it reaches is the Harness running
+ /// here, and it only selects once the daemon has taken the machine. So nothing weaker — an RPC that
+ /// timed out, a status probe that missed its 400ms, a refresh applying a probe taken before the
+ /// daemon was answering — may call it offline while this holds. A socket that really dies closes,
+ /// and `reconnecting` takes the machine offline the ordinary way.
+ bool _localLinkLive(MachineState machine) {
+ if (!machine.localOnly || machine.machine.isShared) return false;
+ final machineId = machine.machine.machineId;
+ final testConnection = connectionForTest;
+ final connection = testConnection != null
+ ? testConnection(machineId)
+ : _pool?[machineId];
+ return connection != null && connection.isReady;
+ }
+
+ /// Bring this computer's machine back from "offline" when its socket says otherwise.
+ ///
+ /// Only one path restored it before, and that path runs when the socket RECONNECTS — which, once a
+ /// wake stopped dropping the loopback socket, is exactly what no longer happens. A false timeout
+ /// could then mark it offline for good over a socket that never dropped. Called from the three
+ /// places that see the daemon answering: the supervisor's five-second snapshot, any frame arriving
+ /// from it, and the offline poll.
+ ///
+ /// Deliberately NOT `_applyNodeStatus(true)`: that re-marks every pane's session unreachable, and
+ /// the streams here may already be live again. Only tiles whose stream is actually dead reattach.
+ /// Returns whether anything was restored.
+ bool _healLocalMachine(
+ MachineState machine,
+ String why, {
+ LocalCliEndpoint? endpoint,
+ }) {
+ if (_disposed || !_localLinkLive(machine)) return false;
+ final restoredEndpoint = machine.localEndpoint == null
+ ? (endpoint ?? _cliEndpoint)
+ : null;
+ final wasOffline = machine.nodeOnline == false;
+ final staleStatus = machine.connectionStatus != ConnectionStatus.connected;
+ if (!wasOffline && restoredEndpoint == null && !staleStatus) return false;
+ if (machine.localEndpoint == null && restoredEndpoint == null) return false;
+ machine.localEndpoint ??= restoredEndpoint;
+ machine.connectionStatus = ConnectionStatus.connected;
+ machine.transportMode = MachineTransportMode.localPlaintext;
+ machine.nodeOnline = true;
+ _stopOfflineRetry(machine.machine.machineId);
+ // A `reconnecting` status that was never followed by `connected` stopped the minute's agent
+ // sync; the socket being live again is the connect it was waiting for.
+ _startAgentSyncTimer(machine.machine.machineId);
+ _logLocalMachine(
+ machine,
+ 'restored ($why${restoredEndpoint != null ? ', endpoint' : ''})',
+ );
+ final pending = machine.pendingOfflineAgentId;
+ if (pending != null) {
+ unawaited(_recoverPendingAgent(machine, pending));
+ } else if (wasOffline ||
+ restoredEndpoint != null ||
+ panesFor(machine.machine.machineId).any(_paneNeedsAttach)) {
+ unawaited(_loadMachineData(machine, force: true));
+ }
+ notifyListeners();
+ return true;
+ }
+
+ Future<void> _applyNodeStatus(
+ MachineState machine,
+ bool online, {
+ String why = 'unspecified',
+ }) async {
if (_disposed) return;
final machineId = machine.machine.machineId;
final wasOnline = machine.nodeOnline;
machine.nodeOnline = online;
+ if (machine.localOnly && wasOnline != online) {
+ _logLocalMachine(machine, online ? 'online ($why)' : 'offline ($why)');
+ }
if (!online) {
if (wasOnline != false) _resetMachineDiscovery(machine);
@@ -12534,6 +12715,12 @@ class AppNotifier extends ChangeNotifier {
) async {
final machine = machineStates[machineId];
if (machine == null) return;
+ // A frame from this computer's daemon is the daemon answering. Cheap: the flags are checked
+ // first, and only a machine currently marked down goes on to look at the socket.
+ if (machine.localOnly &&
+ (machine.nodeOnline == false || machine.localEndpoint == null)) {
+ _healLocalMachine(machine, 'frame from the daemon');
+ }
final type = event['type'] as String? ?? '';
final payload = (event['payload'] as Map<String, dynamic>?) ?? {};
if (type == 'orchestrator_changed') {
@@ -12836,7 +13023,7 @@ class AppNotifier extends ChangeNotifier {
break;
case 'node_status':
final online = payload['online'] == true;
- await _applyNodeStatus(machine, online);
+ await _applyNodeStatus(machine, online, why: 'node_status');
break;
case 'machine_select_error':
_lastError =
@@ -13139,6 +13326,11 @@ class AppNotifier extends ChangeNotifier {
Map<String, dynamic> event,
) => _handleEvent(machineId, event);
+ /// The supervisor's five-second "daemon ready" snapshot, without a supervisor.
+ @visibleForTesting
+ void daemonSnapshotForTest(LocalCliEndpoint endpoint) =>
+ _updateLocalProjectSnapshot(endpoint);
+
/// What the local CLI closing this machine's socket with [code] does to the
/// model — the `WsPool.onLocalFailure` path, without a socket.
@visibleForTesting
diff --git a/desktop/lib/terminal/terminal_session.dart b/desktop/lib/terminal/terminal_session.dart
index 3f9362edf..f0f5da67a 100644
--- a/desktop/lib/terminal/terminal_session.dart
+++ b/desktop/lib/terminal/terminal_session.dart
@@ -7,6 +7,7 @@ import 'package:archive/archive.dart' show ZLibDecoder;
import 'package:xterm/xterm.dart';
import '../core/crash_log.dart';
+import '../core/sleep_aware.dart';
import 'terminal_binary.dart';
import 'terminal_input.dart';
import 'terminal_viewport.dart';
@@ -275,6 +276,7 @@ class TerminalSession extends ChangeNotifier {
List<int> _utf8Tail = const [];
final List<int> _inputBytes = [];
Timer? _heartbeat;
+ int _heartbeatTick = 0;
DateTime? _lastStreamActivityAt;
Timer? _ackTimer;
Timer? _inputTimer;
@@ -469,7 +471,7 @@ class TerminalSession extends ChangeNotifier {
// Armed unconditionally (not just on reopen attempts): a `terminal_open` sent through a silently
// stale relay session never gets ANY reply — nothing else would ever notice or recover from that.
_resyncTimer?.cancel();
- _resyncTimer = Timer(
+ _resyncTimer = SleepAwareTimer(
resyncTimeout,
() => unawaited(_handleOpenTimeout(openPayload, generation)),
);
@@ -496,7 +498,7 @@ class TerminalSession extends ChangeNotifier {
}
if (sent) {
_resyncTimer?.cancel();
- _resyncTimer = Timer(
+ _resyncTimer = SleepAwareTimer(
resyncTimeout,
() => unawaited(_handleOpenTimeout(openPayload, generation)),
);
@@ -566,10 +568,12 @@ class TerminalSession extends ChangeNotifier {
if (!watching) takeover = false;
_resyncTimer?.cancel();
_resyncTimer = null;
- _heartbeat = Timer.periodic(
- const Duration(seconds: 5),
- (_) => unawaited(_sendHeartbeat()),
- );
+ _heartbeatTick = 0;
+ _heartbeat = Timer.periodic(const Duration(seconds: 5), (timer) {
+ final slept = sleptSinceTick(timer, _heartbeatTick);
+ _heartbeatTick = timer.tick;
+ unawaited(_sendHeartbeat(afterSleep: slept));
+ });
_armInitialKeyframeWatchdog();
return true;
case 'terminal_keyframe':
@@ -1480,8 +1484,12 @@ class TerminalSession extends ChangeNotifier {
}
}
- Future<void> _sendHeartbeat() async {
+ Future<void> _sendHeartbeat({bool afterSleep = false}) async {
if (status != TerminalSessionStatus.controlling || streamId == null) return;
+ // The first beat after the computer slept: the stream was quiet because nobody here was running,
+ // not because it died. Its silence is measured afresh from now — the daemon carries the lease over
+ // the same gap — instead of declaring TERMINAL_STREAM_TIMEOUT and throwing away typed input.
+ if (afterSleep) _lastStreamActivityAt = _now();
final generation = _generation;
final sent = await send('terminal_alive', {'streamId': streamId});
if (!sent && _isCurrent(generation)) {
@@ -1518,7 +1526,7 @@ class TerminalSession extends ChangeNotifier {
void _armInitialKeyframeWatchdog() {
_resyncTimer?.cancel();
- _resyncTimer = Timer(resyncTimeout, () {
+ _resyncTimer = SleepAwareTimer(resyncTimeout, () {
if (streamId != null && _expectedSeq == null) {
unawaited(_requestResync('TERMINAL_KEYFRAME_TIMEOUT'));
}
@@ -1553,7 +1561,7 @@ class TerminalSession extends ChangeNotifier {
return;
}
_resyncTimer?.cancel();
- _resyncTimer = Timer(resyncTimeout, () {
+ _resyncTimer = SleepAwareTimer(resyncTimeout, () {
if (_resyncRequested && streamId == currentStream) {
unawaited(_sendResyncAttempt());
}
diff --git a/desktop/lib/ws/ws_conn.dart b/desktop/lib/ws/ws_conn.dart
index 06dee2ccc..e3c31153d 100644
--- a/desktop/lib/ws/ws_conn.dart
+++ b/desktop/lib/ws/ws_conn.dart
@@ -7,6 +7,7 @@ import 'package:flutter/foundation.dart';
import 'package:web_socket_channel/io.dart';
import 'package:web_socket_channel/web_socket_channel.dart';
+import '../core/sleep_aware.dart';
import '../logging/app_log.dart';
import '../logging/redact.dart';
import '../core/models.dart';
@@ -149,12 +150,12 @@ class WsConn {
if (_closing) return Future<void>.error(StateError('WS closed'));
final ready = Completer<void>();
_readinessWaiters.add(ready);
- return ready.future
- .timeout(
- timeout,
- onTimeout: () => throw const WsRequestTimeout('machine_select'),
- )
- .whenComplete(() => _readinessWaiters.remove(ready));
+ // Awake time: a wait begun before the lid closed must not expire on the wake (see sleep_aware).
+ return awakeTimeout<void>(
+ ready.future,
+ timeout,
+ onTimeout: () => throw const WsRequestTimeout('machine_select'),
+ ).whenComplete(() => _readinessWaiters.remove(ready));
}
void _settleReadiness([String? failure]) {
@@ -614,7 +615,10 @@ class WsConn {
}) {
final requestId = _newRequestId();
final completer = Completer<Map<String, dynamic>>();
- final timer = Timer(timeout, () {
+ // Awake time, not wall time: a request asked just before the lid closed used to "time out" on the
+ // first turn after it opened, its answer a second behind — and a timed-out inventory is what
+ // marks a machine offline (measured 2026-09-29 19:06:11).
+ final timer = SleepAwareTimer(timeout, () {
_pending.remove(requestId);
_queue.removeWhere(
(f) =>
diff --git a/desktop/test/machine_list_outage_test.dart b/desktop/test/machine_list_outage_test.dart
index 90f27e88f..a9178ee5b 100644
--- a/desktop/test/machine_list_outage_test.dart
+++ b/desktop/test/machine_list_outage_test.dart
@@ -89,6 +89,16 @@ class _Connection extends WsConn {
onEvent: (_) {},
onStatus: (_) {},
);
+
+ /// The socket to the daemon is open and selected (`WsConn.isReady`).
+ bool ready = false;
+
+ /// The next `agents_list` goes unanswered in time — what a timer armed before a sleep did on the
+ /// wake, or a daemon slow to answer just after it.
+ bool timeOutNextList = false;
+
+ @override
+ bool get isReady => ready;
@override
Future<void> waitUntilReady({required Duration timeout}) async {}
@override
@@ -96,9 +106,23 @@ class _Connection extends WsConn {
String type, {
Map<String, dynamic> payload = const {},
Duration timeout = const Duration(seconds: 20),
- }) async => const {'agents': []};
+ }) async {
+ if (type == 'agents_list' && timeOutNextList) {
+ timeOutNextList = false;
+ throw const WsRequestTimeout('agents_list');
+ }
+ return const {'agents': []};
+ }
}
+LocalCliEndpoint _endpoint() => LocalCliEndpoint(
+ computerId: _computerId,
+ wsUri: Uri.parse('ws://127.0.0.1:18473/ws'),
+ protocolVersion: localWsProtocolVersion,
+ terminalProtocolVersion: 1,
+ machineId: 'local-machine',
+);
+
class _App extends AppNotifier {
_App(_Api api, _Connection connection, this.discovery)
: super(
@@ -128,6 +152,7 @@ Future<void> _tick() => Future.delayed(Duration.zero);
void main() {
late _Api api;
late _App app;
+ late _Connection connection;
// Some tests deliberately end with the recovery timer armed; the binding checks for pending timers
// when the BODY ends, so those dispose themselves and tell tearDown not to do it twice.
var disposedEarly = false;
@@ -135,7 +160,8 @@ void main() {
setUp(() {
disposedEarly = false;
api = _Api();
- app = _App(api, _Connection(), _Discovery());
+ connection = _Connection();
+ app = _App(api, connection, _Discovery());
app.status = AppStatus.authenticated;
// The state a running session is in: this computer's machine, already known to be local.
app.machines = [_localMachine];
@@ -370,4 +396,91 @@ void main() {
expect(app.machinesAreStale, isFalse);
expect(app.machineRecoveryPending, isFalse);
});
+
+ // 2026-09-29: after a lid was opened, an agents_list "timed out" (its timer had run on through the
+ // sleep) and marked this computer offline. The socket to the daemon never dropped, so the one
+ // path that brought the machine back — a reconnect — never ran, and the tiles sat on "Offline"
+ // over live terminals until the app was restarted.
+ group('this computer, while its daemon is on the socket', () {
+ setUp(() {
+ connection.ready = true;
+ app.machineStates['local-machine']!
+ ..localEndpoint = _endpoint()
+ ..connectionStatus = ConnectionStatus.connected
+ ..nodeOnline = true;
+ });
+
+ test('is not called offline by a request that timed out', () async {
+ final local = app.machineStates['local-machine']!;
+ connection.timeOutNextList = true;
+ app.onMachineConnectedForTest('local-machine');
+ await _tick();
+ await _tick();
+
+ expect(local.nodeOnline, isTrue, reason: 'the socket is the witness');
+ expect(local.usesLocalTransport, isTrue);
+ expect(local.agentsLoadError, 'Harness is not responding — retrying');
+
+ // "retrying" is a promise: the list is asked again, and the answer clears the strip.
+ await Future<void>.delayed(const Duration(seconds: 6));
+ await _tick();
+ expect(local.agentsLoadError, isNull);
+ });
+
+ test(
+ 'comes back on the daemon’s next ready snapshot, endpoint and all',
+ () async {
+ // However it got here — a probe that missed, a status left stale — this is the stuck state.
+ final local = app.machineStates['local-machine']!
+ ..nodeOnline = false
+ ..localEndpoint = null
+ ..connectionStatus = ConnectionStatus.disconnected;
+
+ app.daemonSnapshotForTest(_endpoint());
+ await _tick();
+
+ expect(local.nodeOnline, isTrue);
+ expect(local.usesLocalTransport, isTrue);
+ expect(local.connectionStatus, ConnectionStatus.connected);
+ expect(local.transportMode, MachineTransportMode.localPlaintext);
+ },
+ );
+
+ test('comes back on any frame the daemon sends', () async {
+ final local = app.machineStates['local-machine']!..nodeOnline = false;
+ await app.handleEventForTest('local-machine', {
+ 'type': 'turn_heartbeat',
+ 'payload': <String, dynamic>{},
+ });
+ expect(local.nodeOnline, isTrue);
+ });
+
+ test('keeps its endpoint when a refresh applies a missed probe over a stale status', () async {
+ final local = app.machineStates['local-machine']!
+ ..connectionStatus = ConnectionStatus.disconnected;
+ app.discovery.probeMisses = true;
+ final refresh = app.refreshMachines();
+ await _tick();
+ api.lists.single.complete([_localMachine]);
+ await refresh;
+ await _tick();
+
+ expect(local.usesLocalTransport, isTrue);
+ expect(local.nodeOnline, isTrue);
+ });
+ });
+
+ test('a request that times out over a dead socket still takes this computer offline', () async {
+ final local = app.machineStates['local-machine']!
+ ..localEndpoint = _endpoint()
+ ..connectionStatus = ConnectionStatus.connected
+ ..nodeOnline = true;
+ connection.ready = false;
+ connection.timeOutNextList = true;
+ app.onMachineConnectedForTest('local-machine');
+ await _tick();
+ await _tick();
+
+ expect(local.nodeOnline, isFalse);
+ });
}
diff --git a/desktop/test/sleep_aware_test.dart b/desktop/test/sleep_aware_test.dart
new file mode 100644
index 000000000..dc011a0e1
--- /dev/null
+++ b/desktop/test/sleep_aware_test.dart
@@ -0,0 +1,87 @@
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/sleep_aware.dart';
+
+/// What a closed lid looks like to the event loop: nothing runs, then every overdue timer is due at
+/// once. Blocking the isolate reproduces exactly that — the VM skips the periods it missed.
+void _sleepFor(Duration duration) {
+ final until = DateTime.now().add(duration);
+ while (DateTime.now().isBefore(until)) {}
+}
+
+void main() {
+ test('fires after its duration of awake time, like any timer', () async {
+ var fired = 0;
+ SleepAwareTimer(const Duration(milliseconds: 150), () => fired++);
+ await Future<void>.delayed(const Duration(milliseconds: 60));
+ expect(fired, 0);
+ await Future<void>.delayed(const Duration(milliseconds: 200));
+ expect(fired, 1);
+ });
+
+ // 2026-09-29 19:06:11: a request timed out the instant the machine woke, its answer one second
+ // behind. A plain timer spends the sleep; this one does not.
+ test(
+ 'does not spend a sleep on its deadline, where a plain timer does',
+ () async {
+ var plain = 0;
+ var aware = 0;
+ Timer(const Duration(milliseconds: 200), () => plain++);
+ SleepAwareTimer(const Duration(milliseconds: 200), () => aware++);
+ _sleepFor(const Duration(milliseconds: 900));
+ await Future<void>.delayed(const Duration(milliseconds: 20));
+ expect(
+ plain,
+ 1,
+ reason: 'the plain timer fires on the first turn after the wake',
+ );
+ expect(aware, 0, reason: 'the time asleep was nobody’s silence');
+ await Future<void>.delayed(const Duration(milliseconds: 300));
+ expect(aware, 1, reason: 'awake again for the whole deadline, it fires');
+ },
+ );
+
+ test('can be cancelled', () async {
+ var fired = 0;
+ final timer = SleepAwareTimer(
+ const Duration(milliseconds: 50),
+ () => fired++,
+ );
+ expect(timer.isActive, isTrue);
+ timer.cancel();
+ expect(timer.isActive, isFalse);
+ await Future<void>.delayed(const Duration(milliseconds: 150));
+ expect(fired, 0);
+ });
+
+ test(
+ 'awakeTimeout answers with the future, or with onTimeout after awake time',
+ () async {
+ expect(
+ await awakeTimeout(
+ Future.value(7),
+ const Duration(seconds: 1),
+ onTimeout: () => 0,
+ ),
+ 7,
+ );
+ expect(
+ await awakeTimeout(
+ Completer<int>().future,
+ const Duration(milliseconds: 50),
+ onTimeout: () => -1,
+ ),
+ -1,
+ );
+ await expectLater(
+ awakeTimeout<int>(
+ Completer<int>().future,
+ const Duration(milliseconds: 50),
+ onTimeout: () => throw TimeoutException('late'),
+ ),
+ throwsA(isA<TimeoutException>()),
+ );
+ },
+ );
+}