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.

Desktop Machines screen follows the design standard (#3370)

harness-for-autonomous[bot]cdf47784cdae
diff --git a/desktop/lib/super_tabs/machines.dart b/desktop/lib/super_tabs/machines.dart
index 0e0c85cd7..c790f0be1 100644
--- a/desktop/lib/super_tabs/machines.dart
+++ b/desktop/lib/super_tabs/machines.dart
@@ -23,6 +23,7 @@ import '../terminal/terminal_theme_store.dart';
import '../usage/models_menu_controller.dart';
import '../widgets/browser_menu_guard.dart';
import '../widgets/finger_target.dart';
+import '../shared/widgets/skeleton.dart';
import '../widgets/desktop_chrome.dart';
import '../widgets/engine_identity.dart';
import '../widgets/harness_activity_mark.dart';
@@ -854,6 +855,10 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
/// redraws only a row whose words moved, and the list only when rows move.
final _rowsDrawn = <String, Object>{};
List<String> _orderDrawn = const [];
+
+ /// Each row's group as drawn: a machine can change group with the order of rows unchanged (Online to Offline),
+ /// and its headings' counts must follow it (review of #3370).
+ List<String> _groupsDrawn = const [];
final _rowBeats = <String, ValueNotifier<int>>{};
final _tips = <String, GlobalKey<TooltipState>>{};
@@ -986,8 +991,11 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
void _redrawMoved() {
if (!mounted || c.snapshot == null || c.accessRevoked) return;
final views = _sortedViews();
- if (c.backendUnreachable ||
- !listEquals(_orderDrawn, [for (final v in views) v.id])) {
+ final groups = [
+ for (final (key, _, group) in _groups())
+ for (final v in group) '$key/${v.id}',
+ ];
+ if (c.backendUnreachable || !listEquals(_groupsDrawn, groups)) {
_changed();
return;
}
@@ -2676,26 +2684,125 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
return views;
}
- /// One row each, redrawn on its own ([_redrawMoved]).
- List<Widget> _machines() {
+ /// Status first (Scholes, task #3801): the reader's own machines pinned in Yours, then Online, Status unknown and
+ /// Offline, each under a heading with its count. A group with no machine has no heading.
+ List<(String, String, List<_MachineView>)> _groups() {
final views = _sortedViews();
- _orderDrawn = [for (final v in views) v.id];
+ final yours = <_MachineView>[];
+ final online = <_MachineView>[];
+ final unknown = <_MachineView>[];
+ final offline = <_MachineView>[];
+ for (final view in views) {
+ if (view.owner?.id != null && view.owner?.id == c.accountId) {
+ yours.add(view);
+ } else {
+ (switch (view.status) {
+ SuperTabMachineStatus.unknown => unknown,
+ SuperTabMachineStatus.offline => offline,
+ _ => online,
+ }).add(view);
+ }
+ }
+ return [
+ ('yours', 'Yours', yours),
+ ('online', 'Online', online),
+ ('unknown', 'Status unknown', unknown),
+ ('offline', 'Offline', offline),
+ ].where((g) => g.$3.isNotEmpty).toList();
+ }
+
+ /// A group's heading, announced as one.
+ Widget _groupHeading(String key, String label, int count) => Semantics(
+ key: ValueKey('super-machines-group-$key'),
+ header: true,
+ container: true,
+ child: Padding(
+ padding: const EdgeInsets.fromLTRB(
+ grid.AppDesktop.controlGap,
+ grid.AppDesktop.controlGap,
+ grid.AppDesktop.controlGap,
+ grid.AppDesktop.listRowGap,
+ ),
+ child: Text(
+ '$label · $count',
+ style: DesktopChrome.metadata().copyWith(
+ fontWeight: grid.AppFont.semibold,
+ ),
+ ),
+ ),
+ );
+
+ /// Before the Swarm is read, a loading list; a Swarm that cannot be read and holds no machine says so with Retry,
+ /// even when an earlier read found none; a read Swarm with none, the empty note (task #3801). Null when there are
+ /// machines to list.
+ Widget? _stateNote(EdgeInsets emptyPadding) {
+ if (_ids.isNotEmpty) return null;
+ if (c.backendUnreachable) {
+ return Padding(
+ key: const ValueKey('super-machines-error'),
+ padding: emptyPadding,
+ // Wraps: in a narrow sidebar with large text, Retry goes under the sentence rather than squeezing it.
+ child: Wrap(
+ crossAxisAlignment: WrapCrossAlignment.center,
+ children: [
+ Text(
+ "Couldn't read this Swarm's machines.",
+ style: DesktopChrome.metadata(),
+ ),
+ TextButton(
+ key: const ValueKey('super-machines-retry'),
+ onPressed: () => unawaited(c.refresh()),
+ child: const Text('Retry'),
+ ),
+ ],
+ ),
+ );
+ }
+ if (c.snapshot == null) {
+ return const SkeletonList(
+ key: ValueKey('super-machines-loading'),
+ rows: 3,
+ );
+ }
+ return Padding(
+ padding: emptyPadding,
+ child: Text(
+ "Add a machine for this Swarm's agents to use.",
+ style: DesktopChrome.metadata(),
+ ),
+ );
+ }
+
+ /// One row each, redrawn on its own ([_redrawMoved]), under its group's heading.
+ List<Widget> _machines() {
+ final groups = _groups();
+ _orderDrawn = [
+ for (final (_, _, views) in groups)
+ for (final v in views) v.id,
+ ];
+ _groupsDrawn = [
+ for (final (key, _, views) in groups)
+ for (final v in views) '$key/${v.id}',
+ ];
_rowBeats.removeWhere((id, beat) {
if (_orderDrawn.contains(id)) return false;
beat.dispose();
return true;
});
return [
- for (final id in _orderDrawn)
- ValueListenableBuilder<int>(
- key: ValueKey('super-machine-row-$id'),
- valueListenable: _rowBeats.putIfAbsent(id, () => ValueNotifier(0)),
- builder: (context, _, _) {
- final view = _view(id);
- _rowsDrawn[id] = _rowWords(view);
- return _machine(view);
- },
- ),
+ for (final (key, label, views) in groups) ...[
+ _groupHeading(key, label, views.length),
+ for (final id in [for (final v in views) v.id])
+ ValueListenableBuilder<int>(
+ key: ValueKey('super-machine-row-$id'),
+ valueListenable: _rowBeats.putIfAbsent(id, () => ValueNotifier(0)),
+ builder: (context, _, _) {
+ final view = _view(id);
+ _rowsDrawn[id] = _rowWords(view);
+ return _machine(view);
+ },
+ ),
+ ],
];
}
@@ -2734,16 +2841,8 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
: widget.now().difference(failingSince),
),
),
- if (_ids.isEmpty)
- Padding(
- padding: const EdgeInsets.all(grid.AppDesktop.controlGap),
- child: Text(
- "Add a machine for this Swarm's agents to use.",
- style: DesktopChrome.metadata(),
- ),
- )
- else
- ..._machines(),
+ ?_stateNote(const EdgeInsets.all(grid.AppDesktop.controlGap)),
+ if (_ids.isNotEmpty) ..._machines(),
const SizedBox(height: 8),
Align(
alignment: Alignment.centerRight,
@@ -2779,13 +2878,7 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {
),
if (!widget.collapsed) ...[
if (_ids.isEmpty)
- Padding(
- padding: const EdgeInsets.fromLTRB(36, 8, 16, 16),
- child: Text(
- "Add a machine for this Swarm's agents to use.",
- style: DesktopChrome.metadata(),
- ),
- )
+ _stateNote(const EdgeInsets.fromLTRB(36, 8, 16, 16))!
else
Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
diff --git a/desktop/test/super_tab_machines_standard_shots_test.dart b/desktop/test/super_tab_machines_standard_shots_test.dart
new file mode 100644
index 000000000..2d0118c12
--- /dev/null
+++ b/desktop/test/super_tab_machines_standard_shots_test.dart
@@ -0,0 +1,78 @@
+// Task #3801 (Scholes, 11-06): the Machines screen grouped by status, your own pinned, light and dark, for the PR's
+// pictures. Writes nothing unless HARNESS_SUPER_TAB_CAPTURE names a folder.
+import 'dart:io';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/super_tabs/machines.dart';
+
+import 'support/capture.dart';
+import 'support/super_tab_fixture.dart';
+
+final shots = Platform.environment['HARNESS_SUPER_TAB_CAPTURE'];
+
+Map<String, dynamic> _machine(
+ String id,
+ String name,
+ String owner,
+ Duration seen,
+) => {
+ 'machineId': id,
+ 'name': name,
+ 'contributorId': owner,
+ 'observation': {
+ 'receivedAt': DateTime.now().millisecondsSinceEpoch - seen.inMilliseconds,
+ 'resources': {
+ 'cpuPercent': 18,
+ 'memoryTotalBytes': 32000000000,
+ 'memoryUsedBytes': 12000000000,
+ 'diskTotalBytes': 1000000000000,
+ 'diskFreeBytes': 420000000000,
+ },
+ },
+};
+
+void main() {
+ setUpAll(() => loadCaptureFonts(shots));
+
+ for (final brightness in Brightness.values) {
+ testWidgets('Machines grouped in ${brightness.name}', (tester) async {
+ if (shots == null) return;
+ final previous = grid.AppTheme.brightness.value;
+ grid.AppTheme.brightness.value = brightness;
+ addTearDown(() => grid.AppTheme.brightness.value = previous);
+ tester.view.devicePixelRatio = 2;
+ tester.view.physicalSize = const Size(840, 1000);
+ addTearDown(tester.view.reset);
+ final server = ConversationServer();
+ (server.state['people'] as List).add({
+ 'id': 'peer',
+ 'email': '[email protected]',
+ 'role': 'collaborator',
+ });
+ server.state['machines'] = [
+ _machine('mine', 'My MacBook Pro', 'owner', Duration.zero),
+ _machine('build', 'Build Box', 'peer', Duration.zero),
+ _machine('studio', 'Studio Mac', 'peer', const Duration(seconds: 5)),
+ _machine('old', 'Old Linux', 'peer', const Duration(hours: 3)),
+ ];
+ final c = server.controller();
+ await tester.runAsync(c.refresh);
+ addTearDown(() async {
+ await tester.pumpWidget(const SizedBox());
+ c.dispose();
+ });
+ await tester.pumpWidget(
+ MaterialApp(
+ theme: grid.buildAppTheme(brightness: brightness),
+ home: Scaffold(
+ body: SuperTabMachines(controller: c, onAddAgent: (_) {}),
+ ),
+ ),
+ );
+ await tester.pump(const Duration(milliseconds: 100));
+ await captureWindow(tester, shots, 'machines-grouped-${brightness.name}');
+ });
+ }
+}
diff --git a/desktop/test/super_tab_machines_standard_test.dart b/desktop/test/super_tab_machines_standard_test.dart
new file mode 100644
index 000000000..9b38fda2a
--- /dev/null
+++ b/desktop/test/super_tab_machines_standard_test.dart
@@ -0,0 +1,254 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/super_tabs/controller.dart';
+import 'package:harness/super_tabs/machines.dart';
+
+import 'support/super_tab_fixture.dart';
+
+/// Task #3801 (Scholes, 11-06): the Machines screen groups its rows by status, with the reader's own machines pinned
+/// first, and has real loading, empty and error states.
+
+Finder _key(String k) => find.byKey(ValueKey(k));
+
+Map<String, dynamic> _machine(
+ String id,
+ String name,
+ String owner, {
+ Duration? seen,
+}) => {
+ 'machineId': id,
+ 'name': name,
+ 'contributorId': owner,
+ if (seen != null)
+ 'observation': {
+ 'receivedAt': DateTime.now().millisecondsSinceEpoch - seen.inMilliseconds,
+ 'resources': {'cpuPercent': 5},
+ },
+};
+
+Future<void> _mount(WidgetTester tester, SuperTabController c) async {
+ await tester.binding.setSurfaceSize(const Size(420, 900));
+ addTearDown(() => tester.binding.setSurfaceSize(null));
+ await tester.pumpWidget(
+ MaterialApp(
+ // As the Swarm view does: it rebuilds on the controller's changes.
+ home: Scaffold(
+ body: ListenableBuilder(
+ listenable: c,
+ builder: (context, _) =>
+ SuperTabMachines(controller: c, onAddAgent: (_) {}),
+ ),
+ ),
+ ),
+ );
+ await tester.pump();
+}
+
+Future<void> _end(WidgetTester tester, SuperTabController c) async {
+ await tester.pumpWidget(const SizedBox());
+ await c.flush();
+ c.dispose();
+}
+
+double _top(WidgetTester tester, String key) => tester.getTopLeft(_key(key)).dy;
+
+void main() {
+ // Status unknown is the Swarm's own state (it cannot be read), not a machine's: its group shows only then.
+ testWidgets('rows sit under Yours, Online and Offline, in that order, each '
+ 'heading with its count', (tester) async {
+ final server = ConversationServer();
+ (server.state['people'] as List).add({
+ 'id': 'peer',
+ 'email': '[email protected]',
+ 'role': 'collaborator',
+ });
+ server.state['machines'] = [
+ _machine('theirs-off', 'Old Box', 'peer', seen: const Duration(hours: 2)),
+ _machine('theirs-silent', 'Quiet Box', 'peer'),
+ _machine('theirs-live', 'Build Box', 'peer', seen: Duration.zero),
+ _machine('mine', 'My Mac', 'owner', seen: const Duration(hours: 2)),
+ ];
+ final c = server.controller();
+ await c.refresh();
+ await _mount(tester, c);
+
+ final order = [
+ 'super-machines-group-yours',
+ 'super-machine-row-mine',
+ 'super-machines-group-online',
+ 'super-machine-row-theirs-live',
+ 'super-machines-group-offline',
+ 'super-machine-row-theirs-off',
+ 'super-machine-row-theirs-silent',
+ ];
+ for (final key in order) {
+ expect(_key(key), findsOneWidget, reason: key);
+ }
+ for (var i = 1; i < order.length; i++) {
+ expect(
+ _top(tester, order[i - 1]),
+ lessThan(_top(tester, order[i])),
+ reason: '${order[i - 1]} above ${order[i]}',
+ );
+ }
+ // Yours holds the reader's machine whatever its status (offline here).
+ expect(
+ find.descendant(
+ of: _key('super-machines-group-yours'),
+ matching: find.text('Yours · 1'),
+ ),
+ findsOneWidget,
+ );
+ expect(
+ find.descendant(
+ of: _key('super-machines-group-online'),
+ matching: find.text('Online · 1'),
+ ),
+ findsOneWidget,
+ );
+ expect(
+ find.descendant(
+ of: _key('super-machines-group-offline'),
+ matching: find.text('Offline · 2'),
+ ),
+ findsOneWidget,
+ );
+ expect(_key('super-machines-group-unknown'), findsNothing);
+ final heading = tester.getSemantics(_key('super-machines-group-online'));
+ expect(heading.flagsCollection.isHeader, isTrue);
+ await _end(tester, c);
+ });
+
+ testWidgets('a group with no machine shows no heading', (tester) async {
+ final server = ConversationServer();
+ server.state['machines'] = [
+ _machine('theirs-live', 'Build Box', 'peer', seen: Duration.zero),
+ ];
+ final c = server.controller();
+ await c.refresh();
+ await _mount(tester, c);
+ expect(_key('super-machines-group-online'), findsOneWidget);
+ expect(_key('super-machines-group-yours'), findsNothing);
+ expect(_key('super-machines-group-offline'), findsNothing);
+ expect(_key('super-machines-group-unknown'), findsNothing);
+ await _end(tester, c);
+ });
+
+ testWidgets('before the Swarm is read the screen is loading, not empty', (
+ tester,
+ ) async {
+ final server = ConversationServer();
+ server.state['machines'] = [
+ _machine('theirs-live', 'Build Box', 'peer', seen: Duration.zero),
+ ];
+ final c = server.controller();
+ await _mount(tester, c);
+ expect(_key('super-machines-loading'), findsOneWidget);
+ expect(find.textContaining('Add a machine'), findsNothing);
+ await _end(tester, c);
+ });
+
+ testWidgets('a Swarm that cannot be read says so with Retry, and Retry reads '
+ 'it again', (tester) async {
+ final server = ConversationServer()..failReads = true;
+ server.state['machines'] = [
+ _machine('theirs-live', 'Build Box', 'peer', seen: Duration.zero),
+ ];
+ final c = server.controller();
+ await tester.runAsync(() async {
+ try {
+ await c.refresh();
+ } catch (_) {}
+ });
+ await _mount(tester, c);
+ expect(_key('super-machines-error'), findsOneWidget);
+ expect(find.textContaining('Add a machine'), findsNothing);
+
+ server.failReads = false;
+ await tester.tap(_key('super-machines-retry'));
+ for (var i = 0; i < 10; i++) {
+ await tester.pump(const Duration(milliseconds: 50));
+ }
+
+ expect(_key('super-machines-error'), findsNothing);
+ expect(_key('super-machine-row-theirs-live'), findsOneWidget);
+ await _end(tester, c);
+ });
+
+ // Review of #3370: a machine that leaves Online for Offline keeps the same order of rows, and its group's heading
+ // and count must follow it all the same. Mounted with no host rebuilding it: only the machines' own news redraws.
+ testWidgets('a machine going offline moves its group heading and counts, '
+ 'even when the order of rows stays the same', (tester) async {
+ final server = ConversationServer();
+ server.state['machines'] = [
+ _machine('a', 'Alpha', 'peer', seen: Duration.zero),
+ _machine('b', 'Bravo', 'peer', seen: Duration.zero),
+ _machine('c', 'Charlie', 'peer', seen: const Duration(hours: 2)),
+ ];
+ final c = server.controller();
+ await c.refresh();
+ await tester.binding.setSurfaceSize(const Size(420, 900));
+ addTearDown(() => tester.binding.setSurfaceSize(null));
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: SuperTabMachines(controller: c, onAddAgent: (_) {}),
+ ),
+ ),
+ );
+ await tester.pump();
+ expect(find.text('Online · 2'), findsOneWidget);
+ expect(find.text('Offline · 1'), findsOneWidget);
+
+ // Bravo goes quiet: the rows still read Alpha, Bravo, Charlie.
+ final machines = (server.state['machines'] as List)
+ .cast<Map<String, dynamic>>();
+ machines[1] = _machine(
+ 'b',
+ 'Bravo',
+ 'peer',
+ seen: const Duration(hours: 2),
+ );
+ server.revision++;
+ await tester.runAsync(c.refresh);
+ for (var i = 0; i < 4; i++) {
+ await tester.pump(const Duration(milliseconds: 50));
+ }
+ expect(find.text('Online · 1'), findsOneWidget);
+ expect(find.text('Offline · 2'), findsOneWidget);
+ await _end(tester, c);
+ });
+
+ testWidgets('a Swarm read empty, then unreachable, says so with Retry, not '
+ 'Add a machine', (tester) async {
+ final server = ConversationServer();
+ server.state['machines'] = <dynamic>[];
+ final c = server.controller();
+ await c.refresh();
+ server.failReads = true;
+ await tester.runAsync(() async {
+ try {
+ await c.refresh();
+ } catch (_) {}
+ });
+ expect(c.backendUnreachable, isTrue);
+ await _mount(tester, c);
+ expect(_key('super-machines-error'), findsOneWidget);
+ expect(find.textContaining('Add a machine'), findsNothing);
+ await _end(tester, c);
+ });
+
+ testWidgets('a read Swarm with no machine shows the empty note', (
+ tester,
+ ) async {
+ final server = ConversationServer();
+ server.state['machines'] = <dynamic>[];
+ final c = server.controller();
+ await c.refresh();
+ await _mount(tester, c);
+ expect(find.textContaining('Add a machine'), findsOneWidget);
+ expect(_key('super-machines-loading'), findsNothing);
+ expect(_key('super-machines-error'), findsNothing);
+ await _end(tester, c);
+ });
+}
diff --git a/docs/plans/2026-11-06-machines-standard-plan.md b/docs/plans/2026-11-06-machines-standard-plan.md
new file mode 100644
index 000000000..dd0af2c75
--- /dev/null
+++ b/docs/plans/2026-11-06-machines-standard-plan.md
@@ -0,0 +1,52 @@
+# Desktop Machines screen follows the design standard — plan (task #3801)
+
+**Goal:** The Desktop Machines screen (Swarm sidebar and Manage ▸ Machines) meets the Machines design standard Scholes
+asked for: status-first grouping with the reader's own machines pinned; collapsed crew counts; one fixed row anatomy;
+four type sizes; token-only colour, light and dark; real loading, empty and error states; keyboard and VoiceOver.
+No reference doc is coming (Scholes, 11-06): the brief is the spec.
+
+**Architecture:** `SuperTabMachines` (`desktop/lib/super_tabs/machines.dart`) already draws one row per machine with a
+fixed anatomy (`_MachineLine`), a spoken label per row, the context menu on the keyboard (Menu, Shift+F10), the crew
+collapsed to one count line (`superTabMachineCrewLine`, "3 crew · 1 asleep"), the four `DesktopChrome` text roles and
+`grid` colour tokens. What it lacks: the rows are one list sorted by status, not grouped; nothing is pinned; while the
+Swarm is first read the screen says "Add a machine…" as if it had none; and a Swarm that can't be read shows the same
+empty note under its pill. This change groups the sorted rows under headings (Yours, Online, Status unknown, Offline,
+each with its count; Yours first and only when the reader owns a machine there), and gives the screen a loading state
+(skeleton rows) and an error state (what failed, with Retry). Data, filters, row actions and menus are unchanged.
+
+**Tech Stack:** Flutter 3.47 (Desktop), `flutter_test` with `ConversationServer` (memory store, fake sign-in).
+
+**Spec:** River's brief on task #3801 (Scholes, 11-06), and River's note that no reference doc is coming.
+
+This plan is written and carried out by its Engineer, test first; there is no execution handoff.
+
+## Design
+
+N/A beyond the screen: no stored data, no server read or command, no migration. The groups come from the statuses and
+owners the screen already reads.
+
+## Global Constraints
+
+- Same rows, actions, menus and filters; only their grouping and the screen's states change.
+- Harness design language (`scripts/check-ui-style.py`), light and dark; the four `DesktopChrome` text roles only.
+- Desktop tests use a memory store and a fake sign-in. No process starts (Windows: no window flash).
+
+## Review Focus
+
+- Every machine is in exactly one group; the reader's own are in Yours whatever their status.
+- Loading is never shown as empty, and an unreadable Swarm is never shown as having no machines.
+- Headings are announced as headings; each row keeps its spoken label and keyboard menu.
+
+## Tasks
+
+### 1. Status groups, the reader's machines pinned (`machines.dart`)
+
+- [x] Failing test: machines of the reader and of others, live, unknown and offline, sit under Yours, Online, Status
+ unknown and Offline in that order, each heading with its count and announced as a heading; no empty group shows.
+- [x] Code.
+
+### 2. Loading and error states (`machines.dart`)
+
+- [x] Failing test: before the Swarm is read the screen shows its loading rows, not "Add a machine"; a Swarm that can't
+ be read and holds no machine says so with Retry, which reads it again; a read Swarm with none shows the empty note.
+- [x] Code. Light and dark screenshots of the grouped list.