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.

perf(desktop): skip unrelated terminal queues during frame dispatch

dee9976d06f0e36
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 2ee4b6800..af01ccf7d 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -2379,11 +2379,10 @@ class AppNotifier extends ChangeNotifier {
/// Bulk terminal data for a machine, which may now be feeding several tiles.
///
- /// Offered to EVERY tile on that machine rather than routed by this side:
- /// each session already drops a frame whose `streamId` is not its own, and
- /// that check is the authority on which stream a frame belongs to. Choosing
- /// here instead would mean keeping a second copy of that mapping in sync with
- /// the first, and the copy that drifts is the one nobody is looking at.
+ /// Read the live session identity instead of maintaining a second registry.
+ /// Skip unrelated sessions before awaiting: every ignored async call adds a
+ /// scheduling turn to the socket's incoming queue. Matching frames enter the
+ /// session's ordered renderer queue synchronously, regardless of tab order.
Future<void> _handleTerminalBinary(String machineId, Uint8List raw) async {
final targets = panesFor(machineId)
.map((pane) => pane.session)
@@ -2400,7 +2399,9 @@ class AppNotifier extends ChangeNotifier {
return;
}
for (final terminal in targets) {
- await terminal.handleBinary(clear);
+ if (terminal.streamId == clear.streamId) {
+ await terminal.handleBinary(clear);
+ }
}
}
@@ -4451,6 +4452,10 @@ class AppNotifier extends ChangeNotifier {
Map<String, dynamic> event,
) => _handleEvent(machineId, event);
+ @visibleForTesting
+ Future<void> handleTerminalBinaryForTest(String machineId, Uint8List frame) =>
+ _handleTerminalBinary(machineId, frame);
+
/// Put an already-built session on the grid.
///
/// The seam tests used to get from assigning `activeTerminal` directly, which
diff --git a/desktop/test/swarm_terminal_routing_test.dart b/desktop/test/swarm_terminal_routing_test.dart
new file mode 100644
index 000000000..23c4c336a
--- /dev/null
+++ b/desktop/test/swarm_terminal_routing_test.dart
@@ -0,0 +1,133 @@
+import 'dart:convert';
+import 'dart:typed_data';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/terminal/terminal_binary.dart';
+import 'package:harness/terminal/terminal_session.dart';
+
+import 'swarm_state_test.dart' show createApp;
+
+const _streamA = '00000000-0000-0000-0000-000000000001';
+const _streamB = '00000000-0000-0000-0000-000000000002';
+
+TerminalSession _session(
+ String agentId,
+ String streamId, {
+ String machineId = 'm',
+}) =>
+ TerminalSession(
+ machineId: machineId,
+ agentId: agentId,
+ agentName: agentId,
+ engineId: 'codex',
+ send: (_, _) async => true,
+ sendBinary: (_) async => true,
+ )
+ ..streamId = streamId
+ ..status = TerminalSessionStatus.controlling;
+
+TerminalBinaryFrame _frame(
+ String stream,
+ int sequence,
+ String text, {
+ bool keyframe = false,
+}) => TerminalBinaryFrame(
+ kind: keyframe ? TerminalBinaryKind.keyframe : TerminalBinaryKind.output,
+ streamId: stream,
+ seq: sequence,
+ bytes: Uint8List.fromList(utf8.encode(text)),
+ compressed: false,
+ cols: keyframe ? 80 : null,
+ rows: keyframe ? 24 : null,
+);
+
+void main() {
+ test(
+ 'reordering swarms between incoming frames preserves stream order',
+ () async {
+ final app = createApp();
+ addTearDown(app.dispose);
+ app.adoptSessionForTest(_session('a0', _streamA));
+ app.newSwarm();
+ final destination = app.activeSwarmId;
+ final terminal = _session('a1', _streamB);
+ app.adoptSessionForTest(terminal);
+ await terminal.handleBinary(_frame(_streamB, 0, '', keyframe: true));
+
+ // WsConn serializes socket delivery. Deliberately overlap this lower
+ // dispatcher too: unrelated sessions must not delay reaching the
+ // matching stream's own FIFO queue when the view order changes.
+ final first = app.handleTerminalBinaryForTest(
+ 'm',
+ encodeTerminalLocal(_frame(_streamB, 1, 'first '))!,
+ );
+ app.reorderSwarm(destination, 0);
+ final second = app.handleTerminalBinaryForTest(
+ 'm',
+ encodeTerminalLocal(_frame(_streamB, 2, 'second'))!,
+ );
+ await Future.wait([first, second]);
+ expect(terminal.terminal.buffer.getText(), contains('first second'));
+ expect(terminal.status, TerminalSessionStatus.controlling);
+ },
+ );
+
+ test(
+ 'a hidden shared view receives a frame once, scoped to its machine',
+ () async {
+ final app = createApp();
+ addTearDown(app.dispose);
+ final first = app.activeSwarmId;
+ final terminal = _session('a0', _streamA);
+ final pane = app.adoptSessionForTest(terminal);
+ app.newSwarm();
+ await app.addAgentToSwarm('m', 'a0');
+ expect(app.panes.single, same(pane));
+ app.newSwarm();
+ final peer = _session('a0', _streamA, machineId: 'peer');
+ app.adoptSessionForTest(peer);
+ await peer.handleBinary(_frame(_streamA, 0, 'peer data', keyframe: true));
+ await app.handleTerminalBinaryForTest(
+ 'm',
+ encodeTerminalLocal(_frame(_streamA, 0, 'hidden ', keyframe: true))!,
+ );
+ await app.handleTerminalBinaryForTest(
+ 'm',
+ encodeTerminalLocal(_frame(_streamA, 1, 'output'))!,
+ );
+ expect(terminal.terminal.buffer.getText(), contains('hidden output'));
+ expect(terminal.status, TerminalSessionStatus.controlling);
+ expect(peer.terminal.buffer.getText(), contains('peer data'));
+ expect(peer.terminal.buffer.getText(), isNot(contains('hidden')));
+ app.selectSwarm(first);
+ expect(app.panes.single.session, same(terminal));
+ await app.handleTerminalBinaryForTest(
+ 'm',
+ encodeTerminalLocal(_frame(_streamB, 50, 'unknown stream'))!,
+ );
+ expect(
+ terminal.terminal.buffer.getText(),
+ isNot(contains('unknown stream')),
+ );
+ expect(terminal.status, TerminalSessionStatus.controlling);
+ },
+ );
+
+ test('a corrupt frame marks all views on its machine unreachable, including hidden views', () async {
+ final app = createApp();
+ addTearDown(app.dispose);
+ final first = _session('a0', _streamA);
+ app.adoptSessionForTest(first);
+ app.newSwarm();
+ final second = _session('a1', _streamB);
+ app.adoptSessionForTest(second);
+ app.newSwarm();
+ final peer = _session('a0', _streamA, machineId: 'peer');
+ app.adoptSessionForTest(peer);
+ await app.handleTerminalBinaryForTest('m', Uint8List.fromList([0, 1, 2]));
+ expect(first.status, TerminalSessionStatus.error);
+ expect(second.status, TerminalSessionStatus.error);
+ expect(peer.status, TerminalSessionStatus.controlling);
+ expect(first.errorMessage, contains('could not be decoded'));
+ });
+}
diff --git a/docs/harness-v2-performance.md b/docs/harness-v2-performance.md
index f4bcd2ab6..54a7acad0 100644
--- a/docs/harness-v2-performance.md
+++ b/docs/harness-v2-performance.md
@@ -31,6 +31,8 @@ With 16 retained terminals, one switch went from **2,480 to 1,491 widget rebuild
Rapid navigation also coalesces pending arrangement writes. While the first write is in flight, only the latest subsequent snapshot is retained. Tests with 100 rapid tab changes verify that the first and final snapshots are written, including recovery after the first write fails. Normal quit waits for the final snapshot with a one-second bound for stalled storage.
+Incoming binary data now skips unrelated sessions before awaiting the matching renderer queue. This removes one async scheduling turn per unrelated view from each frame's dispatch, while retaining socket FIFO, current stream identity and machine isolation. This change is verified by routing tests; the CPU table above does not measure network delivery.
+
## Native follow-up
The optimized real-data app builds and runs locally. A separate windowless AppKit check covers tab overflow geometry, resizing, accessibility order and disabled actions (`bash tool/check_swarm_titlebar.sh`, with an optional Flutter SDK path). Measure release input-to-display and tab-switch latency in the unlocked native window before making latency claims. The screen was locked during this pass, so native end-to-end drag and visual inspection remain in the development handoff.
diff --git a/docs/harness-v2-progress.md b/docs/harness-v2-progress.md
index 420ccd3de..3afa13f8c 100644
--- a/docs/harness-v2-progress.md
+++ b/docs/harness-v2-progress.md
@@ -66,6 +66,7 @@ Approved reference: `/Users/ab/code/harness-new-ui`, React prototype commit `f83
- `TerminalPane.lastViewSize` retains geometry. Hidden `TerminalPanel` views stop auto-resizing/reporting viewport and release input focus.
- Compact headers remove routine transport/status/pin clutter, retaining exceptional states and offline/unavailable placeholders.
- Existing terminal sessions/transports/renderer and patched `third_party/xterm` are retained. One regression verifies renderer identity, hidden geometry during window resize, and input going only to the active view.
+- Binary dispatch reads current session stream IDs and skips unrelated sessions before awaiting them, avoiding a scheduling turn per unrelated view. No duplicate stream registry is maintained. Socket FIFO remains in `WsConn`; regressions additionally exercise direct concurrent dispatch during tab reorder, hidden shared views, machine isolation, unknown streams and corrupt-frame recovery.
- Compact remote panes expose a Show/Hide message composer button in their header. Closing the final visible pane restores keyboard focus even when its shared terminal remains parked in another Swarm.
### Shell and dialogs
@@ -138,7 +139,7 @@ Swarm shortcuts, help, and tooltips now read the same catalog in `shortcuts/app_
| --- | --- |
| macOS debug build | Passed and launched from the monorepo with real saved Swarms and terminals. |
| macOS optimized local build | Passed and running with the real entry point and saved V2 state. Local ad hoc signing requires the command-line `ENABLE_HARDENED_RUNTIME=NO` override for Flutter's framework; distribution signing settings remain unchanged. The distribution Developer ID certificate is unavailable; nothing was uploaded. Normal asynchronous quit and relaunch were verified. The screen remains locked, so final native visual review is pending. |
-| Full Flutter suite | **977 passed, 1 skipped** after persistence, modal menus and retained-terminal performance changes. |
+| Full Flutter suite | **980 passed, 1 skipped** after persistence, modal menus, retained-terminal performance and stream-dispatch changes. |
| Focused interaction checks | 8 passed: picker navigation/scroll/refresh, welcome keys, shared-view close, composer, native modal guard, profile and folder races. |
| Local CLI discovery | 25 passed, including older-daemon folder parsing and continuous snapshots without spawning/reconnecting. |
| CLI typecheck | `npm run typecheck` passed. |
@@ -154,7 +155,7 @@ Tests now exercise the actual V2 welcome/settings/linking flow. Usage pricing ag
Evidence on this Mac under `/private/tmp`:
-- `harness-v2-final-tests.log`: full 977-test pass.
+- `harness-v2-final-tests.log`: full 980-test pass.
- `harness-v2-final-analyze.log`: latest diagnostics.
- `harness-v2-final-build.log`: real-entry debug build.
- `harness-v2-release-build.log`: optimized local build.
@@ -165,6 +166,7 @@ Evidence on this Mac under `/private/tmp`:
- `harness-v2-persistence-tests.log`: 21 state/async checks including rapid writes and bounded quit.
- `harness-v2-benchmark-final.log`: latest catalog and retained-terminal CPU measurements.
- `harness-v2-native-titlebar-tests.log`: windowless checks against the actual AppKit tab source.
+- `harness-v2-routing-tests.log`: 68 stream-routing, binary protocol and terminal session checks.
Earlier logs contain superseded failures. Temporary logs and toolchains are local conveniences, not committed artifacts.