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(mobile): resync a terminal stream that goes quiet

tonya0a4c7fb37d0
diff --git a/mobile/lib/terminal/terminal_session.dart b/mobile/lib/terminal/terminal_session.dart
index 381d62c20..a88685ac6 100644
--- a/mobile/lib/terminal/terminal_session.dart
+++ b/mobile/lib/terminal/terminal_session.dart
@@ -132,7 +132,7 @@ class _ActiveUpload {
/// One controller stream for one remote Harness agent.
///
/// Sequence corruption is recovered with bounded resync retries and one clean
-/// reopen. Transport loss still freezes input until the user opens a session.
+/// reopen, and so is a stream that goes quiet without a word ([_sendHeartbeat]).
class TerminalSession extends ChangeNotifier {
static const protocolVersion = 3;
static const minCols = 40;
@@ -383,6 +383,14 @@ class TerminalSession extends ChangeNotifier {
int _autoReopenAttempts = 0;
bool _openStallRecovered = false;
+ /// Heartbeats in a row that heard nothing on this stream — see [_sendHeartbeat].
+ int _quietBeats = 0;
+
+ /// The heartbeats a live stream cannot go without a frame: at least 15s of silence, the
+ /// desktop's limit. Four, not three, because the count is of beats that heard nothing, and the
+ /// last frame may have landed just before the first of them.
+ static const _quietBeatsBeforeResync = 4;
+
/// When the open now in flight first left — kept through its resends, so its patience
/// ([_openPatience]) counts from the first ask rather than starting over at each one.
DateTime? _openSentAt;
@@ -816,6 +824,7 @@ class TerminalSession extends ChangeNotifier {
// for the life of the process, beating twice as often and still
// beating after [dispose].
_heartbeat?.cancel();
+ _quietBeats = 0;
_heartbeat = Timer.periodic(
const Duration(seconds: 5),
(_) => unawaited(_sendHeartbeat()),
@@ -835,6 +844,16 @@ class TerminalSession extends ChangeNotifier {
if (_activeUpload?.beginAccepted.isCompleted == false) {
_activeUpload!.beginAccepted.complete(accepted);
}
+ // A stream the daemon no longer has takes no input and no upload, and nothing else says
+ // so: the picture fails, and the terminal sat on as if live. Its screen is kept and it is
+ // opened once more — the desktop's recovery — without sending the picture again. Older
+ // daemons give only the reason's words.
+ if (!accepted &&
+ (payload['code'] == 'TERMINAL_STREAM_NOT_FOUND' ||
+ payload['reason'] ==
+ 'no live terminal stream for this pane (reopen it and try again)')) {
+ await _recoverByReopen(reason: 'TERMINAL_STREAM_NOT_FOUND');
+ }
return true;
case 'terminal_chunked_upload_progress':
if (!_matchesStream(payload)) return true;
@@ -991,6 +1010,8 @@ class TerminalSession extends ChangeNotifier {
Future<void> handleBinary(TerminalBinaryFrame frame) async {
if (_disposed || frame.streamId != streamId) return;
+ // Heard from: whatever the frame turns out to be, the stream is alive — see [_sendHeartbeat].
+ _quietBeats = 0;
final generation = _generation;
_renderTail = _renderTail
.then((_) async {
@@ -1996,13 +2017,31 @@ class TerminalSession extends ChangeNotifier {
}
}
+ /// Keeps the lease, and notices a stream that went quiet without a word.
+ ///
+ /// ⚠️ **A send that succeeds proves only that the socket takes bytes, not that THIS stream is
+ /// still there.** The daemon sends a sync frame every five seconds even while the terminal is idle
+ /// (`SYNC_INTERVAL_MS`, `cli/src/lib/terminalStreamManager.ts`), so a stream that hears nothing for
+ /// [_quietBeatsBeforeResync] beats is gone: a socket left half-open by Wi-Fi giving way to 4G
+ /// while the app was away, a stale relay session, a stream the daemon dropped and never said.
+ /// Until this, such a terminal looked live and took no input until the account's two-minute agent
+ /// poll gave up on the machine — about four minutes. It resyncs, then reopens, as the desktop does
+ /// (#432).
+ ///
+ /// Counted in beats, not by the clock, on purpose: an app the OS suspended runs no timers, so
+ /// the gap it was away is no beat at all, and coming back is not taken for a silence.
Future<void> _sendHeartbeat() async {
if (!acceptsInput) return;
final generation = _generation;
final sent = await send('terminal_alive', {'streamId': streamId});
if (!sent && _isCurrent(generation)) {
transportLost('Terminal heartbeat was not sent');
+ return;
}
+ if (!_isCurrent(generation) || !acceptsInput) return;
+ if (++_quietBeats < _quietBeatsBeforeResync) return;
+ _quietBeats = 0;
+ await _requestResync('TERMINAL_STREAM_TIMEOUT');
}
Future<void> _requestResync(String reason) async {
diff --git a/mobile/test/terminal_session_protocol_test.dart b/mobile/test/terminal_session_protocol_test.dart
index c0d0169ba..1b7059cfa 100644
--- a/mobile/test/terminal_session_protocol_test.dart
+++ b/mobile/test/terminal_session_protocol_test.dart
@@ -399,6 +399,91 @@ void main() {
});
},
);
+
+ /// An open answered, its first screen drawn, on [async]'s clock — a stream the session holds.
+ String liveOn(
+ FakeAsync async,
+ TerminalSession s, {
+ bool readOnly = false,
+ }) {
+ s.open();
+ async.flushMicrotasks();
+ final streamId = _streamId();
+ s.handleFrame('terminal_ready', {
+ 'requestId': wire.last('terminal_open')['requestId'],
+ 'agentId': 'a',
+ 'protocolVersion': TerminalSession.protocolVersion,
+ 'streamId': streamId,
+ if (readOnly) 'readOnly': true,
+ });
+ s.handleBinary(_keyframe(streamId));
+ async.flushMicrotasks();
+ return streamId;
+ }
+
+ // A socket left half-open (Wi-Fi giving way to 4G while the app was away) takes every send and
+ // brings nothing back: the heartbeat goes out, and the terminal looked live while taking no
+ // input for minutes. The daemon sends a sync frame every five seconds, so silence is the sign.
+ test(
+ 'a stream quiet for 15s is resynced, and reopened once the resync '
+ 'gets no answer',
+ () {
+ fakeAsync((async) {
+ final s = session(disposeAtEnd: false);
+ final streamId = liveOn(async, s);
+
+ // Three beats that heard nothing: the last frame may have landed just before the first.
+ async.elapse(const Duration(seconds: 15));
+ expect(wire.of('terminal_resync'), isEmpty);
+ expect(s.acceptsInput, isTrue);
+
+ // The fourth: at least fifteen seconds without the sync the daemon sends every five.
+ async.elapse(const Duration(seconds: 5));
+ expect(s.status, TerminalSessionStatus.resyncing);
+ expect(s.errorCode, 'TERMINAL_STREAM_TIMEOUT');
+ expect(wire.of('terminal_resync'), hasLength(1));
+
+ // Unanswered: two more tries, then the stream is opened again and the old one closed.
+ final opens = wire.of('terminal_open').length;
+ async.elapse(const Duration(milliseconds: 200));
+ expect(wire.of('terminal_resync'), hasLength(3));
+ expect(wire.of('terminal_open'), hasLength(opens + 1));
+ expect(wire.last('terminal_close')['streamId'], streamId);
+ s.dispose();
+ });
+ },
+ );
+
+ test('the sync frames an idle stream sends keep it from a resync', () {
+ fakeAsync((async) {
+ final s = session(disposeAtEnd: false);
+ final streamId = liveOn(async, s);
+
+ for (var seq = 1; seq <= 12; seq++) {
+ async.elapse(const Duration(seconds: 5));
+ s.handleBinary(_sync(streamId, seq));
+ async.flushMicrotasks();
+ }
+
+ expect(wire.of('terminal_alive'), hasLength(12));
+ expect(wire.of('terminal_resync'), isEmpty);
+ expect(s.acceptsInput, isTrue);
+ s.dispose();
+ });
+ });
+
+ test('a terminal only watched is not resynced for being quiet', () {
+ fakeAsync((async) {
+ final s = session(disposeAtEnd: false);
+ liveOn(async, s, readOnly: true);
+
+ async.elapse(const Duration(seconds: 60));
+
+ expect(s.watching, isTrue);
+ expect(wire.of('terminal_resync'), isEmpty);
+ s.dispose();
+ });
+ });
});
group('the screen and the output after it', () {
@@ -1223,6 +1308,67 @@ void main() {
expect(s.uploadProgress, isNull);
});
+ /// The rows the terminal shows, as text.
+ String screenOf(TerminalSession s) => [
+ for (var i = 0; i < s.terminal.buffer.lines.length; i++)
+ s.terminal.buffer.lines[i].getText(),
+ ].join('\n');
+
+ // The daemon no longer has the stream: it takes no input and no upload, and only this answer
+ // says so. Left alone, the picture failed and the terminal sat on as if live.
+ for (final (name, refusal) in [
+ (
+ 'refused because the stream is gone',
+ {
+ 'code': 'TERMINAL_STREAM_NOT_FOUND',
+ 'reason':
+ 'no live terminal stream for this pane (reopen it and try again)',
+ },
+ ),
+ (
+ 'refused in an older daemon\'s words only',
+ {
+ 'reason':
+ 'no live terminal stream for this pane (reopen it and try again)',
+ },
+ ),
+ ]) {
+ test('$name: the terminal is opened again, its screen kept and the '
+ 'picture not sent twice', () async {
+ final (s, streamId) = await live(screen: 'kept screen');
+ final opens = wire.of('terminal_open').length;
+
+ final pasting = s.pasteImage(Uint8List(3));
+ await Future<void>.delayed(Duration.zero);
+ await answer(s, 'terminal_chunked_upload_begin_result', {
+ 'accepted': false,
+ ...refusal,
+ });
+
+ expect(await pasting, isFalse);
+ expect(wire.of('terminal_open'), hasLength(opens + 1));
+ expect(wire.last('terminal_close')['streamId'], streamId);
+ expect(screenOf(s), contains('kept screen'));
+ expect(wire.of('terminal_chunked_upload_begin'), hasLength(1));
+ });
+ }
+
+ test('refused for another reason: the stream stays as it is', () async {
+ final (s, streamId) = await live();
+ final opens = wire.of('terminal_open').length;
+
+ final pasting = s.pasteImage(Uint8List(3));
+ await Future<void>.delayed(Duration.zero);
+ await answer(s, 'terminal_chunked_upload_begin_result', {
+ 'accepted': false,
+ 'code': 'TERMINAL_UPLOAD_TOO_LARGE',
+ });
+
+ expect(await pasting, isFalse);
+ expect(wire.of('terminal_open'), hasLength(opens));
+ expect(s.streamId, streamId);
+ });
+
test('one at a time, and cancelling says so', () async {
final (s, streamId) = await live();