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): keep the terminal on screen while it reconnects

tonyb3d7563226e3
diff --git a/mobile/lib/phone/terminal_page.dart b/mobile/lib/phone/terminal_page.dart
index 0a0c16c62..b6f497988 100644
--- a/mobile/lib/phone/terminal_page.dart
+++ b/mobile/lib/phone/terminal_page.dart
@@ -1962,6 +1962,30 @@ class _TerminalPageState extends State<TerminalPage>
final placeholder = machineAway
? _MachineAway(name: machine.machine.displayName)
: _Attaching(key: _skeletonKey);
+ // A screen this terminal already drew, being brought back: its stream reopening, or its socket
+ // dialling again after the stream was lost with it. Kept up under [_Reconnecting] rather than
+ // covered by the skeleton, which is for a terminal with nothing on it yet. Not while the machine
+ // is away — nothing is on its way then, and [_MachineAway] says why.
+ //
+ // ⚠️ **Lost with its socket, it counts from the drop to the reopen, with no gap between.** The
+ // socket comes back (`connected`) before the terminal is reopened: the one on screen waits as
+ // the machine's `pendingOfflineAgentId` while the app re-reads the machine's list, a round
+ // trip, and only then reopens it (`AppNotifier._recoverPendingAgent`). Read off the socket
+ // alone, the spinner went in that round trip and came back a beat later, a flicker. Waiting as
+ // the pending agent keeps it up; a session lost and NOT waiting — nothing is going to reopen
+ // it — shows its screen plainly, as it did, for a tap to reopen.
+ final waitingToReopen =
+ session != null &&
+ (machine?.connectionStatus != ConnectionStatus.connected ||
+ machine?.pendingOfflineAgentId == widget.agentId);
+ final reconnecting =
+ session != null &&
+ !agentGone &&
+ !machineAway &&
+ (session.showsEarlierScreen ||
+ (session.lostWithTransport &&
+ session.hasScreen &&
+ waitingToReopen));
// Read-only either way — the terminal was never this pane's (a watcher) or was taken from it.
// `_AgentGone` owns the page when the agent itself is missing, so this stays out of its way.
final blocked =
@@ -2312,7 +2336,13 @@ class _TerminalPageState extends State<TerminalPage>
// computer just restarted left the phone on it for close
// to 90 seconds, read as a launch that hung. [_MachineAway]
// covers the panel the same way and says why.
- if (session != null && !session.hasScreen)
+ //
+ // ⚠️ **Unless the panel already shows a screen this
+ // terminal drew** — see `reconnecting` above. Then the
+ // screen stays and only [_Reconnecting] lies over it.
+ if (reconnecting)
+ const Positioned.fill(child: _Reconnecting())
+ else if (session != null && !session.hasScreen)
Positioned.fill(child: placeholder),
// The mic and Search, floating in the
// terminal's bottom-right corner — see
@@ -3063,6 +3093,102 @@ class _MachineAway extends StatelessWidget {
}
}
+/// Laid over a screen this terminal already drew while it is brought back — its stream reopened,
+/// or its socket dialled again — a light blur and a spinner, with the screen still under them.
+///
+/// ⚠️ **Over the old screen, not in its place (owner, 2026-10-15).** The skeleton ([_Attaching])
+/// stands for a terminal with nothing on it yet. Laid over one the reader was just reading — back
+/// from a network switch, a redial — it made their terminal vanish into a skeleton and come back a
+/// moment later, which read as lost work. The screen stays; this only says it is being refreshed,
+/// and goes the moment the new stream's keyframe replaces it.
+///
+/// ⚠️ **After a beat ([showAfter]).** A reopen on a good line is answered in a few hundred
+/// milliseconds; a spinner and a blur flashed over a terminal for that long read as a glitch. Only
+/// a wait that lasts gets them, faded in.
+///
+/// ⚠️ **The blur is light and short-lived, and the spinner is on its own layer.** A `BackdropFilter`
+/// re-blurs what is under it whenever the frame is drawn again, which is why the floating buttons
+/// lost theirs (`FloatingGlass`, `floating_glass.dart`): they sit over a streaming terminal all
+/// the time. This is up only for the seconds a terminal is being brought back, over a screen that
+/// is not streaming, at a small sigma; the spinner's own [RepaintBoundary] keeps its animation out
+/// of the blurred layer. With animations off it stands still, so nothing redraws at all.
+///
+/// Taps go through to the terminal, as the skeleton's do: a swipe to Find or another agent, or a tap
+/// to raise the keyboard, should not wait for the reconnect.
+class _Reconnecting extends StatefulWidget {
+ const _Reconnecting();
+
+ /// How long a reconnect may take before it is shown at all.
+ static const showAfter = Duration(milliseconds: 300);
+
+ @override
+ State<_Reconnecting> createState() => _ReconnectingState();
+}
+
+class _ReconnectingState extends State<_Reconnecting> {
+ Timer? _wait;
+ bool _shown = false;
+
+ @override
+ void initState() {
+ super.initState();
+ _wait = Timer(_Reconnecting.showAfter, () {
+ if (mounted) setState(() => _shown = true);
+ });
+ }
+
+ @override
+ void dispose() {
+ _wait?.cancel();
+ super.dispose();
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ // Not even the blur before the beat: a quick reopen should leave the screen exactly as it was.
+ if (!_shown) return const SizedBox.shrink();
+ final tty = Tty.of(context);
+ final still = MediaQuery.disableAnimationsOf(context);
+ return IgnorePointer(
+ child: Semantics(
+ key: const ValueKey('terminal-reconnecting'),
+ label: 'Reconnecting to the harness',
+ liveRegion: true,
+ child: TweenAnimationBuilder<double>(
+ tween: Tween(begin: 0, end: 1),
+ duration: still ? Duration.zero : const Duration(milliseconds: 180),
+ builder: (context, fade, child) => Opacity(opacity: fade, child: child),
+ child: Stack(
+ fit: StackFit.expand,
+ children: [
+ ClipRect(
+ child: BackdropFilter(
+ filter: ui.ImageFilter.blur(sigmaX: 2.5, sigmaY: 2.5),
+ child: ColoredBox(color: tty.ground.withValues(alpha: 0.3)),
+ ),
+ ),
+ Center(
+ child: RepaintBoundary(
+ child: SizedBox.square(
+ dimension: 22,
+ // The app's one spinner, as Settings ▸ Sign out and the home screen draw it.
+ // Still with animations off: three quarters of a ring, so it reads as waiting.
+ child: CircularProgressIndicator(
+ strokeWidth: 2,
+ color: AppPalette.accent,
+ value: still ? 0.75 : null,
+ ),
+ ),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+ }
+}
+
/// The terminal's body while its first keyframe is still crossing the network.
///
/// ⚠️ **A skeleton here, not a spinner, because the shape IS known** — that is
diff --git a/mobile/lib/terminal/terminal_session.dart b/mobile/lib/terminal/terminal_session.dart
index b9ed2388e..52b2204b9 100644
--- a/mobile/lib/terminal/terminal_session.dart
+++ b/mobile/lib/terminal/terminal_session.dart
@@ -333,6 +333,34 @@ class TerminalSession extends ChangeNotifier {
/// Something to show: this attach's first frame, or a kept screen standing in for it.
bool get hasScreen => hasRenderedFrame || _showingKeptScreen;
+ /// Whether a new stream of this session is on its way over a screen this session itself drew —
+ /// a reopen once its socket was dialled again, a recovery — rather than an empty terminal
+ /// waiting for its first keyframe.
+ ///
+ /// ⚠️ **Why the page needs to know.** An open forgets the stream's sequence ([hasRenderedFrame]
+ /// goes false) but keeps the terminal and what is on it (`preserveTerminal`, which every reopen
+ /// asks for). Read as "no screen", the page laid its attaching skeleton over that screen: back
+ /// from a network switch, the reader saw their terminal vanish into a skeleton and come back a
+ /// moment later. The page keeps it up under a spinner instead ([TerminalPage]).
+ ///
+ /// Only a screen of this session's own streams. A kept screen seeded from another session (the
+ /// pager's, see [seedScreen]) is [hasScreen] already, and needs no word while it attaches.
+ bool get showsEarlierScreen => !hasScreen && _drewScreen;
+
+ /// Set when a keyframe of this session's lands, and cleared only when an open puts a blank
+ /// terminal in its place — see [showsEarlierScreen].
+ bool _drewScreen = false;
+
+ /// The stream was lost with its socket ([transportLost]) and waits for the socket to come back
+ /// — the one `error` the app repairs by itself, by reopening once the machine's socket is up.
+ /// Other errors stay until somebody acts on them.
+ bool get lostWithTransport =>
+ status == TerminalSessionStatus.error &&
+ errorCode == transportLostCode;
+
+ /// The [errorCode] [transportLost] leaves.
+ static const transportLostCode = 'TERMINAL_DISCONNECTED';
+
/// Shows [kept] — the screen this agent had when the phone last left it — until the live stream's
/// first keyframe lands and replaces it.
///
@@ -594,7 +622,11 @@ class TerminalSession extends ChangeNotifier {
// blank terminal where the reader's last screen should have been, with
// [hasScreen] telling it not to show the skeleton either.
final keep = preserveTerminal || _showingKeptScreen;
- if (!keep) terminal = _newTerminal()..resize(cols, rows);
+ if (!keep) {
+ terminal = _newTerminal()..resize(cols, rows);
+ // A blank terminal: whatever this session drew before is gone with the old one.
+ _drewScreen = false;
+ }
status = TerminalSessionStatus.opening;
_openRequestId =
'term_${DateTime.now().microsecondsSinceEpoch}_${Random.secure().nextInt(1 << 31)}';
@@ -1347,6 +1379,7 @@ class TerminalSession extends ChangeNotifier {
_bindTerminal(replacement);
terminal = replacement;
_showingKeptScreen = false;
+ _drewScreen = true;
cols = _clampCols(nextCols);
rows = _clampRows(nextRows);
_utf8Tail = decoded.tail;
@@ -2227,7 +2260,7 @@ class TerminalSession extends ChangeNotifier {
streamId = null;
linkMode = null;
status = TerminalSessionStatus.error;
- errorCode = 'TERMINAL_DISCONNECTED';
+ errorCode = transportLostCode;
errorMessage = message;
_abortActiveUpload();
notifyListeners();
diff --git a/mobile/test/phone_edge/focus_behavior_test.dart b/mobile/test/phone_edge/focus_behavior_test.dart
index 24be2417c..9fa6c3877 100644
--- a/mobile/test/phone_edge/focus_behavior_test.dart
+++ b/mobile/test/phone_edge/focus_behavior_test.dart
@@ -1053,6 +1053,205 @@ void main() {
});
});
+ // Back from a network switch or a redial, the terminal being read stays on screen under a light
+ // blur and a spinner — never the attaching skeleton, which made it vanish and come back. The
+ // skeleton is for a terminal with nothing on it yet (owner, 2026-10-15).
+ group('brought back', () {
+ Finder reconnecting() =>
+ find.bySemanticsLabel('Reconnecting to the harness');
+ Finder attaching() => find.bySemanticsLabel('Attaching to the harness');
+
+ /// The terminal's socket dropping as the app sees it go: the machine dialling again, and the
+ /// terminal on screen marked lost and waiting to be reopened.
+ void socketDropped(_Focus focus) {
+ final machine = focus.app.stateOf('m')!;
+ machine.connectionStatus = ConnectionStatus.reconnecting;
+ machine.pendingOfflineAgentId = 'a';
+ focus.session.transportLost('Connection lost. Reconnecting…');
+ }
+
+ testWidgets('lost with its socket: the screen stays under a blur and a '
+ 'spinner until the new screen lands', (tester) async {
+ final focus = await _Focus.open(tester);
+ socketDropped(focus);
+ await tester.pump();
+ // A beat first: a quick return leaves the screen exactly as it was.
+ expect(reconnecting(), findsNothing);
+
+ await tester.pump(const Duration(milliseconds: 350));
+ expect(reconnecting(), findsOneWidget);
+ expect(attaching(), findsNothing);
+ final overlay = find.byKey(const ValueKey('terminal-reconnecting'));
+ expect(
+ find.descendant(of: overlay, matching: find.byType(BackdropFilter)),
+ findsOneWidget,
+ );
+ expect(
+ find.descendant(
+ of: overlay,
+ matching: find.byType(CircularProgressIndicator),
+ ),
+ findsOneWidget,
+ );
+ // The screen is still the one that was read.
+ expect(focus.session.hasScreen, isTrue);
+
+ // Socket back, terminal reopened, the new screen lands: the spinner goes.
+ focus.app.stateOf('m')!
+ ..connectionStatus = ConnectionStatus.connected
+ ..pendingOfflineAgentId = null;
+ await focus.session.reopen();
+ await focus.answerOpen(screen: 'what is now');
+ await frames(tester);
+ expect(reconnecting(), findsNothing);
+ expect(attaching(), findsNothing);
+ await focus.close();
+ });
+
+ testWidgets('no gap between the socket coming back and the reopen: the '
+ 'spinner stays, and does not start its beat over', (tester) async {
+ final focus = await _Focus.open(tester);
+ socketDropped(focus);
+ // One frame to put the overlay up, then its beat.
+ await tester.pump();
+ await tester.pump(const Duration(milliseconds: 350));
+ expect(reconnecting(), findsOneWidget);
+
+ // The socket is back while the terminal waits its turn (the app re-reads the list first).
+ focus.app.stateOf('m')!.connectionStatus = ConnectionStatus.connected;
+ focus.app.notifyListeners();
+ await tester.pump();
+ expect(reconnecting(), findsOneWidget);
+
+ // Its turn: reopened, the old screen still on show under the same spinner.
+ focus.app.stateOf('m')!.pendingOfflineAgentId = null;
+ await focus.session.reopen();
+ await tester.pump();
+ expect(reconnecting(), findsOneWidget);
+ expect(attaching(), findsNothing);
+
+ await focus.answerOpen(screen: 'what is now');
+ await frames(tester);
+ expect(reconnecting(), findsNothing);
+ await focus.close();
+ });
+
+ testWidgets('a quick reopen leaves the screen as it was: no spinner, no '
+ 'skeleton', (tester) async {
+ final focus = await _Focus.open(tester);
+
+ await focus.session.reopen(force: true);
+ await tester.pump(const Duration(milliseconds: 100));
+ expect(focus.session.showsEarlierScreen, isTrue);
+ expect(reconnecting(), findsNothing);
+ expect(attaching(), findsNothing);
+
+ await focus.answerOpen(screen: 'what is now');
+ await tester.pump(const Duration(milliseconds: 400));
+ expect(reconnecting(), findsNothing);
+ expect(attaching(), findsNothing);
+ await focus.close();
+ });
+
+ testWidgets('lost and not waiting to be reopened: the screen, plainly, for '
+ 'a tap to reopen', (tester) async {
+ final focus = await _Focus.open(tester);
+ // The socket is up and nothing is queued to reopen this terminal.
+ focus.session.transportLost('Connection lost. Reconnecting…');
+ await frames(tester);
+
+ expect(reconnecting(), findsNothing);
+ expect(attaching(), findsNothing);
+ await focus.close();
+ });
+
+ testWidgets('a terminal with nothing on it yet still waits behind the '
+ 'skeleton', (tester) async {
+ setPhone(tester, largePhone);
+ final app = edgeApp();
+ await tester.pumpWidget(
+ phoneApp(
+ TerminalPage(
+ notifier: app,
+ machineId: 'm',
+ agentId: 'a',
+ voice: edgeVoice().voice,
+ ),
+ ),
+ );
+ await tester.pump(const Duration(milliseconds: 400));
+
+ expect(attaching(), findsOneWidget);
+ expect(reconnecting(), findsNothing);
+ await tester.pumpWidget(const SizedBox());
+ await tester.pump(const Duration(seconds: 3));
+ app.dispose();
+ await tester.pump(const Duration(seconds: 30));
+ });
+
+ testWidgets('its machine away: says why, and no spinner promises anything', (
+ tester,
+ ) async {
+ setPhone(tester, largePhone);
+ final app = edgeApp(online: false);
+ final session = await liveTerminal(app, 'a');
+ await tester.pumpWidget(
+ phoneApp(
+ TerminalPage(
+ notifier: app,
+ machineId: 'm',
+ agentId: 'a',
+ voice: edgeVoice().voice,
+ ),
+ ),
+ );
+ await session.reopen(force: true);
+ // One frame to rebuild on the reopen, then longer than the spinner's beat.
+ await tester.pump();
+ await tester.pump(const Duration(milliseconds: 400));
+
+ expect(reconnecting(), findsNothing);
+ expect(find.textContaining('is offline'), findsOneWidget);
+ await tester.pumpWidget(const SizedBox());
+ await tester.pump(const Duration(seconds: 3));
+ app.dispose();
+ await tester.pump(const Duration(seconds: 30));
+ });
+
+ testWidgets('with animations off, the spinner stands still', (tester) async {
+ setPhone(tester, largePhone);
+ final app = edgeApp();
+ final session = await liveTerminal(app, 'a');
+ await tester.pumpWidget(
+ phoneApp(
+ MediaQuery(
+ data: const MediaQueryData(disableAnimations: true),
+ child: TerminalPage(
+ notifier: app,
+ machineId: 'm',
+ agentId: 'a',
+ voice: edgeVoice().voice,
+ ),
+ ),
+ ),
+ );
+ await session.reopen(force: true);
+ // One frame to rebuild on the reopen, then longer than the spinner's beat.
+ await tester.pump();
+ await tester.pump(const Duration(milliseconds: 400));
+
+ expect(reconnecting(), findsOneWidget);
+ final spinner = tester.widget<CircularProgressIndicator>(
+ find.byType(CircularProgressIndicator),
+ );
+ expect(spinner.value, isNotNull, reason: 'a still ring, not a spinning one');
+ await tester.pumpWidget(const SizedBox());
+ await tester.pump(const Duration(seconds: 3));
+ app.dispose();
+ await tester.pump(const Duration(seconds: 30));
+ });
+ });
+
group('more of what a thumb does', () {
testWidgets('a restart the machine refuses says why', (tester) async {
final focus = await _Focus.open(
diff --git a/mobile/test/terminal_session_protocol_test.dart b/mobile/test/terminal_session_protocol_test.dart
index 63af47f6f..66d052f66 100644
--- a/mobile/test/terminal_session_protocol_test.dart
+++ b/mobile/test/terminal_session_protocol_test.dart
@@ -7,6 +7,7 @@ import 'package:flutter_test/flutter_test.dart';
import 'package:harness_mobile/terminal/terminal_binary.dart';
import 'package:harness_mobile/terminal/terminal_session.dart';
import 'package:harness_mobile/terminal/terminal_viewport.dart';
+import 'package:xterm/xterm.dart' show Terminal;
/// The terminal stream protocol a phone speaks with a machine's daemon, frame
/// by frame: an open and its answer, a screen and the output after it, gaps
@@ -1205,6 +1206,82 @@ void main() {
expect(s.agentName, 'api');
expect(told, 1);
});
+
+ // What the page reads to keep a screen up under a spinner while it is brought back, rather
+ // than covering it with the attaching skeleton — which made a terminal vanish into a skeleton
+ // and come back, every time the phone returned from a network switch.
+ group('a screen kept through a reopen', () {
+ test('a first open has no earlier screen to keep', () async {
+ final s = session();
+ await s.open();
+
+ expect(s.hasScreen, isFalse);
+ expect(s.showsEarlierScreen, isFalse);
+ });
+
+ test('lost with its socket, the screen stays and the stream says why', () async {
+ final (s, _) = await live(screen: 'what was read');
+
+ s.transportLost('Connection lost. Reconnecting…');
+
+ expect(s.lostWithTransport, isTrue);
+ expect(s.hasScreen, isTrue);
+ expect(_screen(s), contains('what was read'));
+ });
+
+ test('reopened, it is an earlier screen until the new one lands', () async {
+ final (s, _) = await live(screen: 'what was read');
+ s.transportLost('Connection lost. Reconnecting…');
+
+ await s.reopen();
+
+ expect(s.hasScreen, isFalse, reason: 'the new stream has no frame yet');
+ expect(s.showsEarlierScreen, isTrue);
+ expect(s.lostWithTransport, isFalse);
+ expect(_screen(s), contains('what was read'));
+
+ final next = await ready(s);
+ await s.handleBinary(_keyframe(next, text: 'what is now'));
+
+ expect(s.showsEarlierScreen, isFalse);
+ expect(s.hasScreen, isTrue);
+ expect(_screen(s), contains('what is now'));
+ });
+
+ test('an open that starts on a blank terminal forgets the earlier '
+ 'screen', () async {
+ final (s, _) = await live(screen: 'what was read');
+
+ await s.open();
+
+ expect(s.showsEarlierScreen, isFalse);
+ expect(_screen(s), isNot(contains('what was read')));
+ });
+
+ test('a kept screen seeded from elsewhere is a screen already, and no '
+ 'earlier one', () async {
+ final s = session();
+ s.seedScreen(Terminal()..write('kept from the pager'));
+
+ await s.open();
+
+ expect(s.hasScreen, isTrue);
+ expect(s.showsEarlierScreen, isFalse);
+ });
+
+ test('an error of another kind is not a loss with the socket', () async {
+ final s = session();
+ await s.open();
+ await s.handleFrame('terminal_ready', {
+ 'requestId': wire.last('terminal_open')['requestId'],
+ 'agentId': 'a',
+ 'protocolVersion': TerminalSession.protocolVersion,
+ });
+
+ expect(s.status, TerminalSessionStatus.error);
+ expect(s.lostWithTransport, isFalse);
+ });
+ });
});
group('what is typed', () {