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.

Document app-v2 goals and save portable continuation drafts

dee744c1feeefc2
diff --git a/desktop/tool/native_benchmark/NativeBenchmark.swift b/desktop/tool/native_benchmark/NativeBenchmark.swift
new file mode 100644
index 000000000..563b7fdd3
--- /dev/null
+++ b/desktop/tool/native_benchmark/NativeBenchmark.swift
@@ -0,0 +1,108 @@
+// AppKit input driver compiled ONLY into the isolated benchmark copy.
+// prepare.py appends this to that copy's MainFlutterWindow.swift; production
+// Runner sources and the user's V2 bundle never contain this channel.
+private enum NativeBenchmark {
+ private static var channel: FlutterMethodChannel?
+
+ static func install(window: NSWindow, messenger: FlutterBinaryMessenger) {
+ guard Bundle.main.bundleIdentifier == "ai.autonomous.harness.benchmark",
+ ProcessInfo.processInfo.environment["HARNESS_NATIVE_BENCHMARK"] == "1",
+ ProcessInfo.processInfo.environment["FLUTTER_TEST"] == "1" else {
+ return
+ }
+ let bridge = FlutterMethodChannel(name: "harness/isolated_benchmark", binaryMessenger: messenger)
+ channel = bridge
+ bridge.setMethodCallHandler { call, result in
+ switch call.method {
+ case "ready":
+ window.setContentSize(NSSize(width: 1280, height: 800))
+ window.center()
+ window.makeKeyAndOrderFront(nil)
+ NSApp.activate(ignoringOtherApps: true)
+ result([
+ "bundle": Bundle.main.bundleIdentifier!,
+ "width": window.contentView?.bounds.width ?? 0,
+ "height": window.contentView?.bounds.height ?? 0,
+ "scale": window.backingScaleFactor,
+ "maximumFramesPerSecond": window.screen?.maximumFramesPerSecond ?? 0,
+ "os": ProcessInfo.processInfo.operatingSystemVersionString,
+ ])
+ case "begin":
+ guard window.isKeyWindow, NSApp.isActive,
+ let view = window.contentViewController?.view,
+ window.makeFirstResponder(view) else {
+ result(FlutterError(code: "inactive", message: "Benchmark content must own initial focus", details: nil))
+ return
+ }
+ // Once, after the synthetic UI is mounted. Never reset native or Dart
+ // focus between observations: navigation must perform its own handoff.
+ result(String(describing: type(of: window.firstResponder!)))
+ case "key":
+ guard window.isKeyWindow, NSApp.isActive,
+ let args = call.arguments as? [String: Any],
+ let operation = args["operation"] as? String else {
+ result(FlutterError(code: "inactive", message: "Benchmark window must own focus", details: nil))
+ return
+ }
+ let code: UInt16
+ let characters: String
+ let unmodified: String
+ let flags: NSEvent.ModifierFlags
+ switch operation {
+ case "typing":
+ code = 7; characters = "x"; unmodified = "x"; flags = []
+ case "focus":
+ guard let index = args["index"] as? Int, (1...4).contains(index) else {
+ result(FlutterError(code: "invalid", message: "Invalid pane index", details: nil))
+ return
+ }
+ code = [18, 19, 20, 21][index - 1]
+ characters = String(index); unmodified = characters
+ // AppKit carries both aggregate and device-side modifier bits.
+ // NX_DEVICELCMDKEYMASK = 0x8; Flutter tracks the device-side bits.
+ flags = [.command, NSEvent.ModifierFlags(rawValue: 0x8)]
+ case "tab":
+ code = 30; characters = "}"; unmodified = "]"
+ // NX_DEVICELSHIFTKEYMASK = 0x2.
+ flags = [.command, .shift, NSEvent.ModifierFlags(rawValue: 0xa)]
+ default:
+ result(FlutterError(code: "invalid", message: "Unknown benchmark operation", details: nil))
+ return
+ }
+ let started = Int64(Date().timeIntervalSince1970 * 1_000_000)
+ let timestamp = ProcessInfo.processInfo.systemUptime
+ var events: [(NSEvent.EventType, UInt16, NSEvent.ModifierFlags, String, String)] = []
+ let commandFlags: NSEvent.ModifierFlags = [.command, NSEvent.ModifierFlags(rawValue: 0x8)]
+ if flags.contains(.command) { events.append((.flagsChanged, 55, commandFlags, "", "")) }
+ if flags.contains(.shift) { events.append((.flagsChanged, 56, flags, "", "")) }
+ events.append((.keyDown, code, flags, characters, unmodified))
+ events.append((.keyUp, code, flags, characters, unmodified))
+ if flags.contains(.shift) { events.append((.flagsChanged, 56, commandFlags, "", "")) }
+ if flags.contains(.command) { events.append((.flagsChanged, 55, [], "", "")) }
+ for (type, keyCode, modifiers, text, plainText) in events {
+ guard let event = NSEvent.keyEvent(
+ with: type, location: .zero, modifierFlags: modifiers,
+ timestamp: timestamp, windowNumber: window.windowNumber,
+ context: nil, characters: text,
+ charactersIgnoringModifiers: plainText, isARepeat: false,
+ keyCode: keyCode
+ ) else {
+ result(FlutterError(code: "event", message: "Could not construct native event", details: nil))
+ return
+ }
+ // Only this fixture's application queue/window receives these events.
+ NSApp.postEvent(event, atStart: false)
+ }
+ result([
+ "queuedWallMicros": started,
+ "responder": window.firstResponder.map { String(describing: type(of: $0)) } ?? "none",
+ ])
+ case "finish":
+ result(nil)
+ DispatchQueue.main.async { NSApp.terminate(nil) }
+ default:
+ result(FlutterMethodNotImplemented)
+ }
+ }
+ }
+}
diff --git a/desktop/tool/native_benchmark/README.md b/desktop/tool/native_benchmark/README.md
new file mode 100644
index 000000000..475a45ba0
--- /dev/null
+++ b/desktop/tool/native_benchmark/README.md
@@ -0,0 +1,71 @@
+# Native Release interaction benchmark
+
+**Handoff status, September 13, 2026:** this previously untracked fixture is saved
+for continuation, not a validated measurement result. Before building/running,
+update the old `Harness V2` product-name replacement in `prepare.py`, the process
+name check in `run.py`, and the initial native responder selection. See the
+[handoff](../../../docs/harness-v2-handoff.md) and
+[failed calibration notes](../../../docs/harness-v2-performance.md#native-calibration-remains-unmeasured-2026-09-13).
+Keep isolation and foreground/key-window guards intact; no p50/p95/p99 result
+has been accepted.
+
+This macOS fixture measures AppKit-queued input through the production Swarm
+screen, terminal session parser and Flutter renderer. It runs as **Harness
+Benchmark**, in an isolated copy with its own bundle ID, synthetic transports,
+blocked HTTP and temporary state. It never reads the user's saved Swarms or sends
+input to an agent. The benchmark bridge is appended only to the copied native
+host; it is absent from the production Runner and V2 bundle.
+
+From `desktop/`, build with a compatible Flutter SDK and Xcode:
+
+```sh
+python3 tool/native_benchmark/prepare.py --flutter /path/to/flutter
+```
+
+Use the `BENCHMARK_APP` path printed by the build. Normally close V2 and finish
+other builds/tests first. Keep this fixture in the foreground during a run; it
+exits on focus loss instead of reclaiming focus between observations. The runner
+refuses to start alongside another V2 or benchmark process and never quits them.
+
+```sh
+python3 tool/native_benchmark/run.py \
+ --app '/private/tmp/harness-native-benchmark-EXAMPLE/desktop/build/macos/Build/Products/Release/Harness Benchmark.app' \
+ --terminals 16 --samples 120 \
+ --output /private/tmp/harness-native-16.json
+```
+
+Repeat with `--terminals 48` and a fresh output path. Use `--samples 3` only for
+calibration, not percentile claims. The fixture closes itself normally when it
+finishes; reopen V2 afterward. Launch through `run.py`, which uses Launch Services
+and supplies the required environment. Opening the fixture without that
+environment fails immediately.
+
+## Workload and timing boundary
+
+- A 1280 × 800 content area, four visible terminals, 16 or 48 retained sessions,
+ and 1,000 initial scrollback rows each. Every Swarm is visited before warming.
+- Typing posts `x` through AppKit and echoes it through the production binary
+ output handler with zero simulated network RTT. The exact destination session
+ and input count are checked. Focus uses Cmd+1…4; tabs use Cmd+Shift+].
+- One cold interaction per operation, then 20 warmups and the requested measured
+ observations for each operation, both idle and with output to every terminal
+ at 20 Hz. Each burst repaints eight rows with ANSI cursor save/restore. Reported
+ byte counts, phase duration and skipped bursts expose the achieved output load.
+- Input is posted only to this fixture's own `NSApplication` queue and window.
+ Both aggregate and device-side modifier flags, with press/release events, match
+ AppKit's keyboard representation. Initial content focus is established once;
+ subsequent navigation must perform its own focus handoff.
+- The first post-frame callback after the expected state/output change captures
+ the engine's frame number. It joins that exact ID to `FrameTiming`, including
+ its wall-clock raster-finish timestamp. Results retain every sample, including
+ warmup and cold observations, and summarize p50/p95/p99/max in milliseconds.
+- The fixture uses the real layout file store in a fresh temporary directory.
+ Normal discovery, networking, telemetry and background services are disabled.
+
+**These are native event-queue-to-Flutter-raster timings**, not physical
+keyboard-to-photon measurements. They exclude device scanning, real transport
+and agent response time, GPU/display presentation, and the completion of separate
+AppKit titlebar drawing. The configured display maximum is recorded; it does not
+establish a fixed refresh rate. This does not measure app startup, IME, paste,
+scrolling, reconnect, or every output pattern. Preserve slower runs and report
+the machine, build revision, host load and sampling limits with results.
diff --git a/desktop/tool/native_benchmark/main.dart b/desktop/tool/native_benchmark/main.dart
new file mode 100644
index 000000000..b5526f38f
--- /dev/null
+++ b/desktop/tool/native_benchmark/main.dart
@@ -0,0 +1,470 @@
+// Native Release benchmark. Run only through the isolated copy from prepare.py.
+// The fixture uses the production Swarm screen, sessions, parser and renderer;
+// all machines, transports, terminal output and storage are disposable.
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+import 'dart:math';
+import 'dart:ui' as ui;
+
+import 'package:flutter/material.dart';
+import 'package:flutter/scheduler.dart';
+import 'package:flutter/services.dart';
+import 'package:harness/auth/auth_session.dart';
+import 'package:harness/core/config.dart';
+import 'package:harness/core/harness_file_store.dart';
+import 'package:harness/core/models.dart';
+import 'package:harness/screens/swarm_screen.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/state/app_state.dart';
+import 'package:harness/state/pane_layout_store.dart';
+import 'package:harness/state/swarm_catalog.dart';
+import 'package:harness/terminal/terminal_binary.dart';
+import 'package:harness/terminal/terminal_session.dart';
+
+const _host = MethodChannel('harness/isolated_benchmark');
+final _timings = <int, ui.FrameTiming>{};
+final _samples = <_Sample>[];
+final _sequences = <String, int>{};
+_Sample? _pending;
+Timer? _outputTimer;
+bool _burstPending = false;
+int _outputBytes = 0;
+int _skippedBursts = 0;
+int _inputBytes = 0;
+
+class _Sample {
+ _Sample(
+ this.operation,
+ this.phase,
+ this.load,
+ this.expectedSwarm,
+ this.expectedPane,
+ );
+ final String operation, phase, load, expectedSwarm;
+ final int expectedPane;
+ final done = Completer<void>();
+ int? queued, observed, postFrame, frame;
+ String? nativeResponder;
+
+ void observe() {
+ if (observed != null) return;
+ observed = DateTime.now().microsecondsSinceEpoch;
+ SchedulerBinding.instance.addPostFrameCallback((_) {
+ frame = ui.PlatformDispatcher.instance.frameData.frameNumber;
+ postFrame = DateTime.now().microsecondsSinceEpoch;
+ done.complete();
+ });
+ SchedulerBinding.instance.ensureVisualUpdate();
+ }
+
+ Map<String, Object?> toJson() {
+ final timing = _timings[frame];
+ return {
+ 'operation': operation,
+ 'phase': phase,
+ 'load': load,
+ 'frame': frame,
+ 'nativeResponder': nativeResponder,
+ 'queuedWallMicros': queued,
+ 'observedWallMicros': observed,
+ 'postFrameWallMicros': postFrame,
+ if (timing != null) ...{
+ 'rasterFinishWallMicros': timing.timestampInMicroseconds(
+ ui.FramePhase.rasterFinishWallTime,
+ ),
+ 'buildMicros': timing.buildDuration.inMicroseconds,
+ 'rasterMicros': timing.rasterDuration.inMicroseconds,
+ 'eventToObservedMicros': observed! - queued!,
+ 'eventToRasterMicros':
+ timing.timestampInMicroseconds(ui.FramePhase.rasterFinishWallTime) -
+ queued!,
+ },
+ };
+ }
+}
+
+Future<void> _output(TerminalSession session, List<int> bytes) =>
+ session.handleBinary(
+ TerminalBinaryFrame(
+ kind: TerminalBinaryKind.output,
+ streamId: session.streamId!,
+ seq: _sequences.update(session.agentId, (value) => value + 1) - 1,
+ bytes: bytes is Uint8List ? bytes : Uint8List.fromList(bytes),
+ compressed: false,
+ ),
+ );
+
+Future<AppNotifier> _fixture(int count, Directory stateDirectory) async {
+ final app = AppNotifier(
+ config: const AppConfig(
+ apiBaseUrl: 'http://127.0.0.1:1',
+ localCliBaseUrl: 'http://127.0.0.1:1',
+ ),
+ authSession: AuthSession(),
+ paneLayoutStore: PaneLayoutStore(
+ storage: HarnessFileStore(directory: stateDirectory),
+ ),
+ connectionForTest: (_) =>
+ throw StateError('The benchmark cannot attach a transport'),
+ )..hasNavigationRail = false;
+ const machine = Machine(
+ machineId: 'fixture',
+ name: 'Isolated fixture',
+ authMode: MachineAuthMode.remote,
+ );
+ app.machines = [machine];
+ app.machineStates[machine.machineId] = MachineState(machine)
+ ..nodeOnline = true
+ ..agentLoadStatus = AgentLoadStatus.loaded
+ ..agents = [
+ for (var i = 0; i < count; i++)
+ Agent(
+ id: 'fixture-$i',
+ name: 'Fixture agent $i',
+ engine: 'codex',
+ terminalAvailable: true,
+ ),
+ ];
+ final first = app.activeSwarmId;
+ for (var i = 0; i < count; i++) {
+ if (i % 4 == 0) {
+ if (i != 0) app.newSwarm();
+ app.renameSwarm(app.activeSwarmId, 'Fixture ${i ~/ 4 + 1}');
+ }
+ late TerminalSession session;
+ session = TerminalSession(
+ machineId: machine.machineId,
+ agentId: 'fixture-$i',
+ agentName: 'Fixture agent $i',
+ engineId: 'codex',
+ send: (_, _) async => true,
+ sendBinary: (packet) async {
+ if (packet.kind != TerminalBinaryKind.input) return true;
+ final sample = _pending;
+ if (sample == null ||
+ sample.operation != 'typing' ||
+ packet.bytes.length != 1 ||
+ packet.bytes.any((byte) => byte != 120) ||
+ app.activeSwarmId != sample.expectedSwarm ||
+ app.focusedPaneId != sample.expectedPane ||
+ !identical(app.focusedPane?.session, session)) {
+ final error = StateError(
+ 'Unexpected input: session ${session.agentId}, '
+ 'focused ${app.focusedPane?.session?.agentId}, '
+ 'bytes ${packet.bytes}, pending ${sample?.operation}',
+ );
+ stderr.writeln(error);
+ throw error;
+ }
+ _inputBytes += packet.bytes.length;
+ // Zero-RTT echo through the actual output decoder/parser, not a widget label.
+ await _output(session, packet.bytes);
+ sample.observe();
+ return true;
+ },
+ )..streamId = 'fixture-stream-$i';
+ _sequences[session.agentId] = 1;
+ await session.handleBinary(
+ TerminalBinaryFrame(
+ kind: TerminalBinaryKind.keyframe,
+ streamId: session.streamId!,
+ seq: 0,
+ bytes: utf8.encode(
+ List.generate(
+ 1000,
+ (row) =>
+ '\x1b[32m$row\x1b[0m retained terminal output with project context\r\n',
+ ).join(),
+ ),
+ compressed: false,
+ cols: 160,
+ rows: 40,
+ ),
+ );
+ // This executable is an isolated native test fixture.
+ // ignore: invalid_use_of_visible_for_testing_member
+ app.adoptSessionForTest(session);
+ }
+ app.selectSwarm(first, attachPending: false);
+ app.addListener(() {
+ final sample = _pending;
+ if (sample != null &&
+ sample.operation != 'typing' &&
+ app.activeSwarmId == sample.expectedSwarm &&
+ app.focusedPaneId == sample.expectedPane) {
+ sample.observe();
+ }
+ });
+ return app;
+}
+
+Future<void> _frame() async {
+ SchedulerBinding.instance.scheduleFrame();
+ await SchedulerBinding.instance.endOfFrame;
+}
+
+Future<void> _sample(
+ AppNotifier app,
+ String operation,
+ String phase,
+ String load,
+) async {
+ var expectedSwarm = app.activeSwarm;
+ var expectedPane = app.focusedPaneId!;
+ var index = 0;
+ if (operation == 'focus') {
+ index = (app.panes.indexWhere((p) => p.id == expectedPane) + 1) % 4;
+ expectedPane = app.panes[index].id;
+ } else if (operation == 'tab') {
+ expectedSwarm = app
+ .swarms[(app.swarms.indexOf(app.activeSwarm) + 1) % app.swarms.length];
+ expectedPane = expectedSwarm.focusedPaneId!;
+ }
+ final sample = _Sample(
+ operation,
+ phase,
+ load,
+ expectedSwarm.id,
+ expectedPane,
+ );
+ _samples.add(sample);
+ _pending = sample;
+ final reply = await _host.invokeMapMethod<String, Object?>('key', {
+ 'operation': operation,
+ 'index': index + 1,
+ });
+ sample.queued = reply!['queuedWallMicros'] as int;
+ sample.nativeResponder = reply['responder'] as String?;
+ await sample.done.future.timeout(
+ const Duration(seconds: 3),
+ onTimeout: () => throw StateError(
+ '$operation did not reach its expected pane/frame: '
+ 'expected ${sample.expectedSwarm}/${sample.expectedPane}, '
+ 'actual ${app.activeSwarmId}/${app.focusedPaneId}, '
+ 'Dart focus ${FocusManager.instance.primaryFocus?.debugLabel}, '
+ 'native responder ${sample.nativeResponder}',
+ ),
+ );
+ _pending = null;
+}
+
+Map<String, num> _distribution(Iterable<int> values) {
+ final sorted = values.toList()..sort();
+ num percentile(double p) =>
+ sorted[(sorted.length * p).ceil().clamp(1, sorted.length) - 1] / 1000;
+ return {
+ 'samples': sorted.length,
+ 'p50Ms': percentile(.50),
+ 'p95Ms': percentile(.95),
+ 'p99Ms': percentile(.99),
+ 'maxMs': sorted.last / 1000,
+ };
+}
+
+Future<void> _run() async {
+ final env = Platform.environment;
+ if (env['HARNESS_NATIVE_BENCHMARK'] != '1' ||
+ !env.containsKey('FLUTTER_TEST')) {
+ throw StateError('Use the isolated native benchmark runner');
+ }
+ final output = env['HARNESS_BENCH_OUTPUT'];
+ if (output == null || !output.startsWith('/private/tmp/')) {
+ throw StateError('A private temporary output path is required');
+ }
+ final count = int.parse(env['HARNESS_BENCH_TERMINALS'] ?? '16');
+ final observations = int.parse(env['HARNESS_BENCH_SAMPLES'] ?? '120');
+ if (![16, 48].contains(count) || observations < 1 || observations > 500) {
+ throw StateError('Invalid fixture size');
+ }
+ final binding = WidgetsFlutterBinding.ensureInitialized();
+ binding.addTimingsCallback((values) {
+ for (final value in values) {
+ _timings[value.frameNumber] = value;
+ }
+ });
+ await const MethodChannel('harness/swarm_tabs')
+ .invokeMethod<void>('configure');
+ final metadata = await _host.invokeMapMethod<String, Object?>('ready');
+ if (metadata?['bundle'] != 'ai.autonomous.harness.benchmark') {
+ throw StateError('Wrong native host');
+ }
+ final app = await _fixture(
+ count,
+ Directory(
+ '${File(output).parent.path}/state-$count-${DateTime.now().microsecondsSinceEpoch}',
+ ),
+ );
+ final projects = SwarmProjectStore();
+ runApp(
+ grid.BrightnessScope(
+ child: MaterialApp(
+ debugShowCheckedModeBanner: false,
+ theme: grid.buildAppTheme(brightness: Brightness.dark),
+ home: SwarmScreen(
+ notifier: app,
+ nativeTabs: true,
+ projectStore: projects,
+ ),
+ ),
+ ),
+ );
+ await _frame();
+ await Future<void>.delayed(const Duration(seconds: 1));
+ final random = Random(77);
+ final phases = <Map<String, Object?>>[];
+ try {
+ metadata!['initialResponder'] = await _host.invokeMethod<String>('begin');
+ for (final op in ['typing', 'focus', 'tab']) {
+ await _sample(app, op, 'cold_interaction', 'idle');
+ }
+ // Visit all tabs so the warm workload includes every retained renderer.
+ for (var i = 0; i < app.swarms.length * 2; i++) {
+ app.stepSwarm(1);
+ await _frame();
+ }
+ final packet = utf8.encode(
+ '\x1b7\x1b[1;1H${List.filled(8, '${List.filled(110, 'output ').join().substring(0, 110)}\x1b[K\r\n').join()}\x1b8',
+ );
+ for (final load in ['idle', 'all_terminals_20hz']) {
+ final began = DateTime.now().microsecondsSinceEpoch;
+ final bytesBefore = _outputBytes;
+ if (load != 'idle') {
+ _outputTimer = Timer.periodic(const Duration(milliseconds: 50), (
+ _,
+ ) async {
+ if (_burstPending) {
+ _skippedBursts++;
+ return;
+ }
+ _burstPending = true;
+ try {
+ await Future.wait([
+ for (final pane in app.allPanes) _output(pane.session!, packet),
+ ]);
+ _outputBytes += packet.length * count;
+ } finally {
+ _burstPending = false;
+ }
+ });
+ }
+ for (final op in ['typing', 'focus', 'tab']) {
+ for (var i = 0; i < 20 + observations; i++) {
+ await Future<void>.delayed(
+ Duration(milliseconds: 20 + random.nextInt(40)),
+ );
+ await _sample(app, op, i < 20 ? 'warmup' : 'measured', load);
+ }
+ }
+ _outputTimer?.cancel();
+ _outputTimer = null;
+ phases.add({
+ 'load': load,
+ 'durationMicros': DateTime.now().microsecondsSinceEpoch - began,
+ 'outputBytes': _outputBytes - bytesBefore,
+ 'skippedBursts': _skippedBursts,
+ 'packetBytesPerTerminal': packet.length,
+ });
+ }
+ // Release engines batch timing delivery; retain exact frame IDs before joining.
+ for (
+ var i = 0;
+ i < 25 && _samples.any((s) => !_timings.containsKey(s.frame));
+ i++
+ ) {
+ await _frame();
+ await Future<void>.delayed(const Duration(milliseconds: 100));
+ }
+ final rows = _samples.map((sample) => sample.toJson()).toList();
+ if (rows.any(
+ (row) =>
+ row['eventToRasterMicros'] is! int ||
+ (row['eventToRasterMicros'] as int) < 0,
+ )) {
+ throw StateError('Missing or invalid exact-frame timing');
+ }
+ if (_inputBytes !=
+ _samples.where((sample) => sample.operation == 'typing').length) {
+ throw StateError('Native typing produced duplicate or missing input');
+ }
+ final summaries = <Map<String, Object?>>[];
+ for (final load in ['idle', 'all_terminals_20hz']) {
+ for (final op in ['typing', 'focus', 'tab']) {
+ final group = rows
+ .where(
+ (row) =>
+ row['load'] == load &&
+ row['operation'] == op &&
+ row['phase'] == 'measured',
+ )
+ .toList();
+ summaries.add({
+ 'operation': op,
+ 'load': load,
+ 'eventToRaster': _distribution(
+ group.map((row) => row['eventToRasterMicros'] as int),
+ ),
+ 'eventToObserved': _distribution(
+ group.map((row) => row['eventToObservedMicros'] as int),
+ ),
+ 'build': _distribution(group.map((row) => row['buildMicros'] as int)),
+ 'raster': _distribution(
+ group.map((row) => row['rasterMicros'] as int),
+ ),
+ });
+ }
+ }
+ await File(output).writeAsString(
+ const JsonEncoder.withIndent(' ').convert({
+ 'success': true,
+ 'kind': 'native_release_event_to_raster',
+ 'terminals': count,
+ 'visible': 4,
+ 'initialScrollbackRows': 1000,
+ 'metadata': metadata,
+ 'inputBytes': _inputBytes,
+ 'phases': phases,
+ 'summaries': summaries,
+ 'samples': rows,
+ }),
+ );
+ stdout.writeln(
+ 'NATIVE_BENCH ${jsonEncode({'terminals': count, 'summaries': summaries})}',
+ );
+ } catch (error, stack) {
+ await File(output).writeAsString(
+ jsonEncode({
+ 'success': false,
+ 'error': '$error',
+ 'stack': '$stack',
+ 'samples': _samples.map((s) => s.toJson()).toList(),
+ }),
+ );
+ stderr.writeln('Native benchmark failed: $error');
+ } finally {
+ _outputTimer?.cancel();
+ runApp(const SizedBox());
+ await _frame();
+ await app.flushPaneLayout();
+ app.dispose();
+ projects.dispose();
+ await _host.invokeMethod<void>('finish');
+ }
+}
+
+void main() {
+ runZonedGuarded(
+ () => HttpOverrides.runZoned(
+ () => unawaited(_run()),
+ createHttpClient: (_) =>
+ throw StateError('Network is disabled in the native fixture'),
+ ),
+ (error, stack) {
+ // A missing runner environment or setup error must not leave a blank app.
+ stderr.writeln(
+ 'Native benchmark setup/asynchronous failure: $error\n$stack',
+ );
+ exit(1);
+ },
+ );
+}
diff --git a/desktop/tool/native_benchmark/prepare.py b/desktop/tool/native_benchmark/prepare.py
new file mode 100644
index 000000000..804f1f6cc
--- /dev/null
+++ b/desktop/tool/native_benchmark/prepare.py
@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Build an isolated Release benchmark; never rewrite the user's V2 bundle."""
+import argparse
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument('--flutter', required=True, type=Path)
+args = parser.parse_args()
+source = Path(__file__).resolve().parents[2]
+root = Path(tempfile.mkdtemp(prefix='harness-native-benchmark-', dir='/private/tmp'))
+desktop = root / 'desktop'
+shutil.copytree(source, desktop, ignore=shutil.ignore_patterns('build', '.dart_tool', 'ephemeral', '.DS_Store'))
+window = desktop / 'macos/Runner/MainFlutterWindow.swift'
+code = window.read_text()
+marker = ' super.awakeFromNib()'
+if code.count(marker) != 1:
+ raise RuntimeError('Native benchmark insertion point changed')
+code = code.replace(marker, ' NativeBenchmark.install(window: self, messenger: flutterViewController.engine.binaryMessenger)\n' + marker)
+code += '\n' + (source / 'tool/native_benchmark/NativeBenchmark.swift').read_text()
+window.write_text(code)
+info = desktop / 'macos/Runner/Configs/AppInfo.xcconfig'
+info.write_text(info.read_text().replace('PRODUCT_NAME = Harness V2', 'PRODUCT_NAME = Harness Benchmark').replace('ai.autonomous.harness.v2', 'ai.autonomous.harness.benchmark'))
+env = dict(os.environ, XDG_CONFIG_HOME=str(root / 'tool-config'))
+flutter = str(args.flutter / 'bin/flutter')
+log = root / 'build.log'
+print(f'BENCHMARK_ROOT={root}', flush=True)
+with log.open('w') as output:
+ def run(command):
+ subprocess.run(command, cwd=desktop, env=env, stdout=output, stderr=subprocess.STDOUT, check=True)
+ run([flutter, '--suppress-analytics', 'config', '--enable-swift-package-manager'])
+ run([flutter, '--suppress-analytics', 'pub', 'get', '--offline'])
+ run([flutter, '--suppress-analytics', 'build', 'macos', '--release', '--config-only', '--no-pub', '--target', 'tool/native_benchmark/main.dart'])
+ run(['xcodebuild', '-workspace', 'macos/Runner.xcworkspace', '-scheme', 'Runner', '-configuration', 'Release', '-derivedDataPath', 'build/macos', '-destination', 'platform=macOS,arch=arm64', 'CODE_SIGN_IDENTITY=-', 'CODE_SIGN_STYLE=Manual', 'DEVELOPMENT_TEAM=', 'OTHER_CODE_SIGN_FLAGS=', 'ENABLE_HARDENED_RUNTIME=NO', 'build'])
+app = desktop / 'build/macos/Build/Products/Release/Harness Benchmark.app'
+if not app.exists():
+ raise RuntimeError('Expected isolated bundle was not built')
+print(f'BENCHMARK_APP={app}', flush=True)
diff --git a/desktop/tool/native_benchmark/run.py b/desktop/tool/native_benchmark/run.py
new file mode 100644
index 000000000..7f86c74a1
--- /dev/null
+++ b/desktop/tool/native_benchmark/run.py
@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Run the disposable native fixture and require complete, successful results."""
+import argparse
+import json
+from pathlib import Path
+import plistlib
+import subprocess
+import sys
+
+
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument('--app', required=True, type=Path)
+parser.add_argument('--output', required=True, type=Path)
+parser.add_argument('--terminals', type=int, choices=(16, 48), default=16)
+parser.add_argument('--samples', type=int, default=120)
+args = parser.parse_args()
+app = args.app.resolve()
+output = args.output.resolve()
+temporary = Path('/private/tmp').resolve()
+if not app.is_relative_to(temporary) or not output.is_relative_to(temporary):
+ parser.error('The benchmark app and output must be under /private/tmp')
+if not 1 <= args.samples <= 500:
+ parser.error('Use between 1 and 500 samples per operation/load')
+with (app / 'Contents/Info.plist').open('rb') as source:
+ info = plistlib.load(source)
+if info.get('CFBundleIdentifier') != 'ai.autonomous.harness.benchmark':
+ parser.error('Refusing to launch a bundle other than the isolated fixture')
+log = output.with_suffix('.log')
+if output.exists() or log.exists():
+ parser.error('Choose fresh result and log paths')
+processes = subprocess.check_output(['ps', '-axo', 'command='], text=True)
+for name in ('Harness Benchmark', 'Harness V2'):
+ if f'/{name}.app/Contents/MacOS/{name}' in processes:
+ parser.error(f'Normally close {name} before measuring; this runner never quits other apps')
+output.parent.mkdir(parents=True, exist_ok=True)
+command = [
+ 'open', '-n', '-W', '-o', str(log), '--stderr', str(log),
+ '--env', 'FLUTTER_TEST=1',
+ '--env', 'HARNESS_NATIVE_BENCHMARK=1',
+ '--env', f'HARNESS_BENCH_TERMINALS={args.terminals}',
+ '--env', f'HARNESS_BENCH_SAMPLES={args.samples}',
+ '--env', f'HARNESS_BENCH_OUTPUT={output}',
+ str(app),
+]
+print(f'Native benchmark: {args.terminals} terminals, {args.samples} samples per group', flush=True)
+print('Keep the benchmark foreground. It stops if another app takes focus.', flush=True)
+try:
+ # Launch Services gives the fixture normal app activation. Executing the
+ # bundle binary directly does not reliably activate a native macOS window.
+ subprocess.run(command, check=True, timeout=300)
+except (subprocess.SubprocessError, OSError) as error:
+ sys.exit(f'Benchmark launch/wait failed: {error}. Inspect {log}; close any remaining fixture normally.')
+if not output.exists():
+ sys.exit(f'No result file was written; inspect {log}')
+data = json.loads(output.read_text())
+if data.get('success') is not True:
+ sys.exit(f'Benchmark failed: {data.get("error")}; details in {output}')
+if data.get('terminals') != args.terminals or len(data.get('summaries', [])) != 6:
+ sys.exit(f'Incomplete workload in {output}')
+for group in data['summaries']:
+ timing = group['eventToRaster']
+ if timing['samples'] != args.samples:
+ sys.exit(f'Incomplete sample count in {output}')
+ print(f'{group["load"]:22} {group["operation"]:7} '
+ f'p50 {timing["p50Ms"]:7.3f} ms p95 {timing["p95Ms"]:7.3f} ms '
+ f'p99 {timing["p99Ms"]:7.3f} ms max {timing["maxMs"]:7.3f} ms')
+print(f'Raw samples: {output}')
diff --git a/docs/handoff/app-v2-2026-09-13/README.md b/docs/handoff/app-v2-2026-09-13/README.md
new file mode 100644
index 000000000..eeed736cc
--- /dev/null
+++ b/docs/handoff/app-v2-2026-09-13/README.md
@@ -0,0 +1,55 @@
+# Saved app-v2 drafts
+
+These files preserve work paused during the user's design discussion. They are
+**not active application source**. Read [the current handoff](../../harness-v2-handoff.md)
+before reusing them: the final decision requires distinct Navigate and Add UIs.
+
+The drafts were saved from a worktree based on `ac443eb`. Both patches separately
+pass `git apply --check` at the `26a372e` code checkpoint. They overlap in
+`desktop/lib/screens/swarm_screen.dart`; this is not a verified combined patch.
+The `.dart.txt` suffix keeps archived source out of compilation and test discovery.
+
+## Picker draft
+
+- `picker-wip.patch`: tracked source/test changes, with affected paths listed in
+ `picker-files.txt`.
+- `swarm_add_agent_test.dart.txt`: additional test source, intended for
+ `desktop/test/swarm_add_agent_test.dart` when the relevant implementation is ready.
+
+Contains bottom-right Add FAB and removal of top-right New agent; existing/new
+agent routing for FAB and splits; inline Add semantics; preserved target/split
+context; duplicate/group membership handling; always-on preview and eye-toggle
+removal; a bounded output excerpt; darker shared modal veil; menu order changes;
+native keyboard and widget regressions. It formerly kept global Navigate and
+local Add in the same picker component, which the latest user instruction
+explicitly supersedes. Its preview cleanup and footer/layout still need visual
+refinement, and custom configs containing `picker.preview` need a deliberate
+compatibility decision when removing that action.
+
+Earlier validation before parking: 57 focused Flutter tests; 51 decoder and
+343 AppKit checks. This is evidence for that draft only, not a completed visual
+review or acceptance of the current two-UI design.
+
+## Onboarding draft
+
+- `onboarding-wip.patch`: changes to SwarmScreen and SwarmWelcome.
+- `first_workspace_welcome.dart.txt`: proposed new widget, intended for
+ `desktop/lib/widgets/first_workspace_welcome.dart`.
+
+Contains a first-use welcome with ready agents, folder-first creation, separate
+GitHub cloning, and progressively revealed machine/project browsing. It broadens
+first-use detection beyond a single empty-machine case. It was saved before
+validation and must be adapted to the approved shared Add interface. Do not
+describe it as shipped or proven to improve onboarding.
+
+Inspect/reuse selected changes rather than automatically applying both files:
+
+```sh
+# From repository root; checks only, without modifying source.
+git apply --check docs/handoff/app-v2-2026-09-13/picker-wip.patch
+git apply --check docs/handoff/app-v2-2026-09-13/onboarding-wip.patch
+```
+
+The original `/private/tmp/harness-*-wip*` copies are no longer required to
+continue on another computer. Logs and screenshots mentioned in historical
+progress notes remain local evidence, not portable build dependencies.
diff --git a/docs/handoff/app-v2-2026-09-13/first_workspace_welcome.dart.txt b/docs/handoff/app-v2-2026-09-13/first_workspace_welcome.dart.txt
new file mode 100644
index 000000000..c254e3d50
--- /dev/null
+++ b/docs/handoff/app-v2-2026-09-13/first_workspace_welcome.dart.txt
@@ -0,0 +1,390 @@
+import 'package:flutter/material.dart';
+
+import '../shared/theme/app_theme.dart' as grid;
+import '../state/app_state.dart';
+import '../state/swarm_catalog.dart';
+import 'engine_identity.dart';
+import 'swarm_icon.dart';
+import 'welcome_workspace_preview.dart';
+
+/// Start with the work already available. Machine and project management is
+/// available on demand, without making it a prerequisite for the first agent.
+class FirstWorkspaceWelcome extends StatefulWidget {
+ const FirstWorkspaceWelcome({
+ super.key,
+ required this.notifier,
+ required this.groups,
+ required this.searchField,
+ required this.onNewAgent,
+ required this.onLinkMachine,
+ required this.onProject,
+ required this.catalogBuilder,
+ this.onChooseFolder,
+ this.onCloneRepository,
+ this.onAgent,
+ });
+
+ final AppNotifier notifier;
+ final List<SwarmProjectGroup> groups;
+ final Widget searchField;
+ final VoidCallback onNewAgent, onLinkMachine;
+ final VoidCallback? onChooseFolder, onCloneRepository;
+ final ValueChanged<SwarmAgentRef>? onAgent;
+ final ValueChanged<SwarmProjectGroup> onProject;
+ final WidgetBuilder catalogBuilder;
+
+ @override
+ State<FirstWorkspaceWelcome> createState() => _FirstWorkspaceWelcomeState();
+}
+
+class _FirstWorkspaceWelcomeState extends State<FirstWorkspaceWelcome> {
+ bool _catalogOpen = false;
+
+ @override
+ Widget build(BuildContext context) {
+ grid.AppTheme.watch(context);
+ final app = widget.notifier;
+ final ready =
+ swarmAgents(app)
+ .where(
+ (entry) =>
+ !entry.machine.needsLink &&
+ entry.machine.nodeOnline != false &&
+ entry.agent.terminalAvailable,
+ )
+ .toList()
+ ..sort((a, b) {
+ if (a.machine.isLocalMachine != b.machine.isLocalMachine) {
+ return a.machine.isLocalMachine ? -1 : 1;
+ }
+ return a.agent.name.toLowerCase().compareTo(
+ b.agent.name.toLowerCase(),
+ );
+ });
+ final local = app.machineStates.values
+ .where(
+ (machine) =>
+ machine.isLocalMachine &&
+ !machine.needsLink &&
+ machine.nodeOnline != false,
+ )
+ .firstOrNull;
+ final canCreate = app.machineStates.values.any(
+ (machine) => !machine.needsLink && machine.nodeOnline != false,
+ );
+ final finding =
+ app.machinesLoading ||
+ app.machineStates.values.any(
+ (machine) =>
+ !machine.needsLink &&
+ machine.nodeOnline != false &&
+ (machine.agentLoadStatus == AgentLoadStatus.idle ||
+ machine.agentLoadStatus == AgentLoadStatus.loading),
+ );
+ final chooseFolder = local != null && widget.onChooseFolder != null;
+ final existing = ready.isNotEmpty && widget.onAgent != null;
+ final saved = widget.groups.where((group) => group.saved != null).toList();
+
+ Widget primary() => FilledButton.icon(
+ key: const ValueKey('first-workspace-start'),
+ autofocus: !existing,
+ onPressed: chooseFolder
+ ? widget.onChooseFolder
+ : canCreate
+ ? widget.onNewAgent
+ : finding
+ ? null
+ : widget.onLinkMachine,
+ icon: Icon(
+ chooseFolder
+ ? Icons.folder_open_outlined
+ : canCreate
+ ? Icons.add
+ : Icons.computer_outlined,
+ size: 18,
+ ),
+ label: Text(
+ chooseFolder
+ ? 'Choose folder…'
+ : canCreate
+ ? 'New agent'
+ : finding
+ ? 'Finding your computers…'
+ : 'Link a machine',
+ ),
+ style: FilledButton.styleFrom(
+ minimumSize: const Size(168, 44),
+ backgroundColor: grid.AppPalette.swarmAccent,
+ foregroundColor: grid.AppPalette.swarmTabBar,
+ ),
+ );
+
+ Widget intro() => Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(
+ existing ? 'Your agents, ready to go' : 'Your agents, together',
+ style: const TextStyle(
+ fontSize: 32,
+ height: 1.15,
+ fontWeight: FontWeight.w600,
+ letterSpacing: -0.7,
+ color: Colors.white,
+ ),
+ ),
+ const SizedBox(height: 12),
+ Text(
+ existing
+ ? 'Bring your existing work into Harness. Choose an agent to continue.'
+ : 'Work with Claude Code, Codex, and other agents side by side. Start with one in a folder you already use.',
+ style: const TextStyle(
+ fontSize: 14,
+ height: 1.55,
+ color: Colors.white70,
+ ),
+ ),
+ if (!existing) ...[
+ const SizedBox(height: 24),
+ Wrap(
+ spacing: 12,
+ runSpacing: 8,
+ crossAxisAlignment: WrapCrossAlignment.center,
+ children: [
+ primary(),
+ if (local != null && widget.onCloneRepository != null)
+ TextButton(
+ key: const ValueKey('first-workspace-clone'),
+ onPressed: widget.onCloneRepository,
+ style: TextButton.styleFrom(foregroundColor: Colors.white70),
+ child: const Text('Clone repository…'),
+ ),
+ ],
+ ),
+ const SizedBox(height: 12),
+ const Text(
+ 'Choose a folder → Pick an agent → Give it a task',
+ style: TextStyle(fontSize: 12, height: 1.5, color: Colors.white60),
+ ),
+ ],
+ ],
+ );
+
+ const example = Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Row(
+ children: [
+ Text(
+ 'Work side by side',
+ style: TextStyle(
+ fontSize: 12,
+ fontWeight: FontWeight.w600,
+ color: Colors.white70,
+ ),
+ ),
+ Spacer(),
+ Text(
+ 'Example',
+ style: TextStyle(fontSize: 11, color: Colors.white54),
+ ),
+ ],
+ ),
+ SizedBox(height: 10),
+ WelcomeWorkspacePreview(),
+ SizedBox(height: 10),
+ Text(
+ 'A swarm is a tab of agents. Add another with + when you’re ready.',
+ style: TextStyle(fontSize: 12, height: 1.5, color: Colors.white60),
+ ),
+ ],
+ );
+
+ return LayoutBuilder(
+ builder: (context, constraints) => SingleChildScrollView(
+ child: ConstrainedBox(
+ constraints: BoxConstraints(minHeight: constraints.maxHeight),
+ child: Center(
+ child: Container(
+ constraints: const BoxConstraints(maxWidth: 1040),
+ padding: EdgeInsets.symmetric(
+ horizontal: constraints.maxWidth < 700 ? 24 : 48,
+ vertical: 40,
+ ),
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ if (existing) ...[
+ intro(),
+ const SizedBox(height: 24),
+ widget.searchField,
+ const SizedBox(height: 16),
+ _Surface(
+ child: Column(
+ children: [
+ for (final entry in ready.take(3))
+ ListTile(
+ key: ValueKey(
+ 'welcome-agent:${entry.machineId}:${entry.agent.id}',
+ ),
+ leading: EngineMark(
+ engine: entry.agent.engine,
+ size: 22,
+ ),
+ title: Text(
+ entry.agent.name,
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: const TextStyle(
+ fontSize: 14,
+ color: Colors.white,
+ ),
+ ),
+ subtitle: Text(
+ [
+ entry.machine.machine.displayName,
+ entry.project?.name,
+ ].whereType<String>().join(' · '),
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: const TextStyle(
+ fontSize: 12,
+ color: Colors.white60,
+ ),
+ ),
+ trailing: const Icon(
+ Icons.arrow_forward,
+ size: 16,
+ color: Colors.white54,
+ ),
+ onTap: () => widget.onAgent!(entry),
+ ),
+ ],
+ ),
+ ),
+ const SizedBox(height: 12),
+ TextButton.icon(
+ onPressed: widget.onNewAgent,
+ icon: const Icon(Icons.add, size: 17),
+ style: TextButton.styleFrom(
+ foregroundColor: Colors.white70,
+ ),
+ label: const Text('New agent'),
+ ),
+ ] else ...[
+ LayoutBuilder(
+ builder: (context, size) => size.maxWidth >= 720
+ ? Row(
+ crossAxisAlignment: CrossAxisAlignment.center,
+ children: [
+ Expanded(flex: 6, child: intro()),
+ const SizedBox(width: 40),
+ const Expanded(flex: 5, child: example),
+ ],
+ )
+ : Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ intro(),
+ const SizedBox(height: 28),
+ example,
+ ],
+ ),
+ ),
+ if (finding) ...[
+ const SizedBox(height: 24),
+ const Semantics(
+ liveRegion: true,
+ child: Text(
+ 'Looking for existing agents…',
+ style: TextStyle(fontSize: 12, color: Colors.white60),
+ ),
+ ),
+ ],
+ ],
+ if (saved.isNotEmpty && !_catalogOpen) ...[
+ const SizedBox(height: 28),
+ const Text(
+ 'Your folders',
+ style: TextStyle(
+ fontSize: 13,
+ fontWeight: FontWeight.w600,
+ color: Colors.white70,
+ ),
+ ),
+ const SizedBox(height: 10),
+ _Surface(
+ child: Column(
+ children: [
+ for (final group in saved.take(3))
+ ListTile(
+ key: ValueKey(
+ 'first-workspace-project:${group.id}',
+ ),
+ leading: const SwarmIcon(color: Colors.white60),
+ title: Text(
+ group.name,
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: const TextStyle(
+ fontSize: 13,
+ color: Colors.white,
+ ),
+ ),
+ subtitle: Text(
+ group.saved!.path,
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: const TextStyle(
+ fontSize: 12,
+ color: Colors.white60,
+ ),
+ ),
+ onTap: () => widget.onProject(group),
+ ),
+ ],
+ ),
+ ),
+ ],
+ const SizedBox(height: 24),
+ TextButton.icon(
+ key: const ValueKey('first-workspace-catalog'),
+ onPressed: () =>
+ setState(() => _catalogOpen = !_catalogOpen),
+ icon: Icon(
+ _catalogOpen ? Icons.expand_less : Icons.expand_more,
+ size: 18,
+ ),
+ label: const Text('Browse machines and projects'),
+ style: TextButton.styleFrom(
+ foregroundColor: Colors.white60,
+ ),
+ ),
+ if (_catalogOpen) ...[
+ const SizedBox(height: 12),
+ widget.catalogBuilder(context),
+ ],
+ ],
+ ),
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+}
+
+class _Surface extends StatelessWidget {
+ const _Surface({required this.child});
+ final Widget child;
+ @override
+ Widget build(BuildContext context) => Container(
+ padding: const EdgeInsets.all(6),
+ decoration: BoxDecoration(
+ color: grid.AppPalette.swarmSearchSurface,
+ borderRadius: BorderRadius.circular(12),
+ border: Border.all(color: Colors.white12),
+ ),
+ child: child,
+ );
+}
diff --git a/docs/handoff/app-v2-2026-09-13/onboarding-wip.patch b/docs/handoff/app-v2-2026-09-13/onboarding-wip.patch
new file mode 100644
index 000000000..867b0299f
--- /dev/null
+++ b/docs/handoff/app-v2-2026-09-13/onboarding-wip.patch
@@ -0,0 +1,493 @@
+diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
+index 4aefbf5..309d8ee 100644
+--- a/desktop/lib/screens/swarm_screen.dart
++++ b/desktop/lib/screens/swarm_screen.dart
+@@ -34,6 +34,7 @@ import '../widgets/new_agent_dialog.dart';
+ import '../widgets/pane_grid.dart';
+ import '../widgets/shortcuts_sheet.dart';
+ import '../widgets/swarm_dialogs.dart';
++import '../widgets/clone_repository_dialog.dart';
+ import '../widgets/swarm_inline_search.dart';
+ import '../widgets/swarm_search_input.dart';
+ import '../widgets/swarm_project_agents.dart';
+@@ -500,10 +501,14 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ String? swarmId,
+ PaneSplitRequest? split,
+ bool chooseFolderFirst = false,
++ bool cloneRepositoryFirst = false,
+ }) => _dialog(() async {
+ final focused = app.focusedPane;
+ final inherit =
+- machineId == null && !chooseFolderFirst && focused?.agentId != null;
++ machineId == null &&
++ !chooseFolderFirst &&
++ !cloneRepositoryFirst &&
++ focused?.agentId != null;
+ final focusedMachine = inherit
+ ? app.machineStates[focused!.machineId]
+ : null;
+@@ -530,14 +535,16 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ ? null
+ : focusedMachine?.projectOf(focusedAgent)?.cwd);
+ Future<void>? initialEngineProbe;
+- if (chooseFolderFirst && machine != null && machine.isLocalMachine) {
++ if ((chooseFolderFirst || cloneRepositoryFirst) &&
++ machine != null &&
++ machine.isLocalMachine) {
+ // Read availability while the user chooses a folder, so the form can
+ // prefer an installed agent without adding a second probe or wait.
+ initialEngineProbe = app.probeEngines(id, force: true);
+ try {
+- selectedFolder = await getDirectoryPath(
+- confirmButtonText: 'Use folder',
+- );
++ selectedFolder = cloneRepositoryFirst
++ ? await showCloneRepositoryDialog(context)
++ : await getDirectoryPath(confirmButtonText: 'Use folder');
+ } catch (error) {
+ if (mounted) {
+ ScaffoldMessenger.of(context).showSnackBar(
+@@ -560,7 +567,11 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ context,
+ app,
+ id,
+- source: chooseFolderFirst ? 'first_folder' : 'swarm',
++ source: cloneRepositoryFirst
++ ? 'first_clone'
++ : chooseFolderFirst
++ ? 'first_folder'
++ : 'swarm',
+ initialFolder: selectedFolder,
+ initialEngineProbe: initialEngineProbe,
+ swarmId: targetId,
+@@ -1169,6 +1180,8 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ onNewAgent: _newAgent,
+ onChooseFirstFolder: () =>
+ _newAgent(chooseFolderFirst: true),
++ onCloneRepository: () =>
++ _newAgent(cloneRepositoryFirst: true),
+ onAgent: (entry) => _activateSearch(
+ SwarmSearchSelection(
+ SwarmDestination(
+diff --git a/desktop/lib/widgets/swarm_welcome.dart b/desktop/lib/widgets/swarm_welcome.dart
+index 587add8..09abada 100644
+--- a/desktop/lib/widgets/swarm_welcome.dart
++++ b/desktop/lib/widgets/swarm_welcome.dart
+@@ -7,7 +7,7 @@ import '../shared/theme/app_theme.dart' as grid;
+ import '../shared/widgets/skeleton.dart';
+ import '../state/app_state.dart';
+ import '../state/swarm_catalog.dart';
+-import 'engine_identity.dart';
++import 'first_workspace_welcome.dart';
+ import 'swarm_icon.dart';
+
+ class SwarmWelcome extends StatelessWidget {
+@@ -22,6 +22,7 @@ class SwarmWelcome extends StatelessWidget {
+ required this.onMachine,
+ required this.onProject,
+ this.onChooseFirstFolder,
++ this.onCloneRepository,
+ this.onAgent,
+ this.onProjectAgents,
+ });
+@@ -29,6 +30,7 @@ class SwarmWelcome extends StatelessWidget {
+ final List<SavedSwarmProject> projects;
+ final VoidCallback onNewAgent;
+ final VoidCallback? onChooseFirstFolder;
++ final VoidCallback? onCloneRepository;
+ final Widget searchField;
+ final VoidCallback onAddProject;
+ final VoidCallback onLinkMachine;
+@@ -44,36 +46,20 @@ class SwarmWelcome extends StatelessWidget {
+ final firstWorkspace =
+ app.swarms.every((swarm) => swarm.panes.isEmpty) &&
+ app.closedHistory.isEmpty;
+- final agents = firstWorkspace ? swarmAgents(app) : const <SwarmAgentRef>[];
+- final noAgents =
+- firstWorkspace &&
+- !app.machinesLoading &&
+- agents.isEmpty &&
+- groups.isEmpty &&
+- app.machineStates.length == 1 &&
+- app.machineStates.values.first.isLocalMachine &&
+- app.machineStates.values.first.agentLoadStatus ==
+- AgentLoadStatus.loaded &&
+- app.machineStates.values.first.nodeOnline != false &&
+- !app.machineStates.values.first.needsLink;
+- final chooseFirstFolder = noAgents && onChooseFirstFolder != null;
+- final readyAgents =
+- agents
+- .where(
+- (entry) =>
+- !entry.machine.needsLink &&
+- entry.machine.nodeOnline != false &&
+- entry.agent.terminalAvailable,
+- )
+- .toList()
+- ..sort((a, b) {
+- if (a.machine.isLocalMachine != b.machine.isLocalMachine) {
+- return a.machine.isLocalMachine ? -1 : 1;
+- }
+- return a.agent.name.toLowerCase().compareTo(
+- b.agent.name.toLowerCase(),
+- );
+- });
++ if (firstWorkspace) {
++ return FirstWorkspaceWelcome(
++ notifier: app,
++ groups: groups,
++ searchField: searchField,
++ onNewAgent: onNewAgent,
++ onChooseFolder: onChooseFirstFolder,
++ onCloneRepository: onCloneRepository,
++ onLinkMachine: onLinkMachine,
++ onAgent: onAgent,
++ onProject: onProject,
++ catalogBuilder: (_) => _catalog(app, groups),
++ );
++ }
+ return Stack(
+ fit: StackFit.expand,
+ children: [
+@@ -90,7 +76,7 @@ class SwarmWelcome extends StatelessWidget {
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(
+- noAgents ? 'Start with one agent' : 'Start a swarm',
++ 'Start a swarm',
+ style: const TextStyle(
+ fontSize: 32,
+ fontWeight: FontWeight.w500,
+@@ -103,9 +89,7 @@ class SwarmWelcome extends StatelessWidget {
+ ),
+ const SizedBox(height: 10),
+ Text(
+- noAgents
+- ? 'Choose a project folder and an agent. Add more whenever you want to work side by side.'
+- : 'A swarm keeps related agents together. Open a machine or project to bring its agents into this tab.',
++ 'Keep related agents together in this tab. Choose existing work or start a new agent.',
+ style: const TextStyle(
+ fontSize: 13,
+ color: Color(0xffe0dce3),
+@@ -117,20 +101,9 @@ class SwarmWelcome extends StatelessWidget {
+ Expanded(child: searchField),
+ const SizedBox(width: 12),
+ FilledButton.icon(
+- onPressed: chooseFirstFolder
+- ? onChooseFirstFolder
+- : onNewAgent,
+- icon: Icon(
+- chooseFirstFolder
+- ? Icons.folder_open_outlined
+- : Icons.add,
+- size: 17,
+- ),
+- label: Text(
+- chooseFirstFolder
+- ? 'Choose folder…'
+- : 'New agent',
+- ),
++ onPressed: onNewAgent,
++ icon: const Icon(Icons.add, size: 17),
++ label: const Text('New agent'),
+ style: FilledButton.styleFrom(
+ minimumSize: const Size(126, 44),
+ backgroundColor: grid.AppPalette.swarmAccent,
+@@ -140,148 +113,7 @@ class SwarmWelcome extends StatelessWidget {
+ ],
+ ),
+ const SizedBox(height: 34),
+- if (noAgents)
+- _Glass(
+- child: _FirstAgentGuide(onLinkMachine: onLinkMachine),
+- )
+- else ...[
+- if (onAgent != null && readyAgents.isNotEmpty) ...[
+- _Glass(
+- child: Column(
+- crossAxisAlignment: CrossAxisAlignment.start,
+- children: [
+- const Text(
+- 'Go to an agent',
+- style: TextStyle(
+- fontSize: 13,
+- fontWeight: FontWeight.w600,
+- ),
+- ),
+- const SizedBox(height: 8),
+- for (final entry in readyAgents.take(3))
+- ListTile(
+- key: ValueKey(
+- 'welcome-agent:${entry.machineId}:${entry.agent.id}',
+- ),
+- contentPadding: const EdgeInsets.symmetric(
+- horizontal: 4,
+- ),
+- leading: EngineMark(
+- engine: entry.agent.engine,
+- size: 22,
+- ),
+- title: Text(
+- entry.agent.name,
+- maxLines: 1,
+- overflow: TextOverflow.ellipsis,
+- style: const TextStyle(fontSize: 13),
+- ),
+- subtitle: Text(
+- [
+- entry.machine.machine.displayName,
+- entry.project?.name,
+- ].whereType<String>().join(' · '),
+- maxLines: 1,
+- overflow: TextOverflow.ellipsis,
+- style: const TextStyle(
+- fontSize: 12,
+- color: Colors.white70,
+- ),
+- ),
+- onTap: () => onAgent!(entry),
+- ),
+- ],
+- ),
+- ),
+- const SizedBox(height: 18),
+- ],
+- _Glass(
+- child: LayoutBuilder(
+- builder: (context, size) {
+- final machines = _section(
+- 'Machines',
+- 'Link machine',
+- onLinkMachine,
+- [
+- if (app.machinesLoading &&
+- app.machineStates.isEmpty)
+- const SkeletonList(rows: 3),
+- for (final machine
+- in app.machineStates.values)
+- _StarterRow(
+- name: machine.machine.displayName,
+- note: machine.needsLink
+- ? 'Link required'
+- : machine.nodeOnline == false
+- ? 'Offline'
+- : machine.isLocalMachine
+- ? 'Local'
+- : null,
+- count: machine.agents.length,
+- onTap: () => onMachine(machine),
+- ),
+- if (!app.machinesLoading &&
+- app.machineStates.isEmpty)
+- const Padding(
+- padding: EdgeInsets.symmetric(
+- vertical: 18,
+- ),
+- child: Text(
+- 'Link a machine to find its agents.',
+- ),
+- ),
+- ],
+- );
+- final projects = _section(
+- 'Projects',
+- 'Add project',
+- onAddProject,
+- [
+- for (final group in groups)
+- _StarterRow(
+- name: group.name,
+- count: group.agents.length,
+- onTap: () => onProject(group),
+- onManage: onProjectAgents == null
+- ? null
+- : () => onProjectAgents!(group),
+- ),
+- if (groups.isEmpty)
+- const Padding(
+- padding: EdgeInsets.symmetric(
+- vertical: 18,
+- ),
+- child: Text(
+- 'Add a working folder to start a project.',
+- style: TextStyle(
+- color: Color(0xffc5bece),
+- fontSize: 12,
+- ),
+- ),
+- ),
+- ],
+- );
+- return size.maxWidth < 570
+- ? Column(
+- children: [
+- machines,
+- const SizedBox(height: 24),
+- projects,
+- ],
+- )
+- : Row(
+- crossAxisAlignment:
+- CrossAxisAlignment.start,
+- children: [
+- Expanded(child: machines),
+- const SizedBox(width: 36),
+- Expanded(child: projects),
+- ],
+- );
+- },
+- ),
+- ),
+- ],
++ _catalog(app, groups),
+ ],
+ ),
+ ),
+@@ -293,6 +125,64 @@ class SwarmWelcome extends StatelessWidget {
+ );
+ }
+
++ Widget _catalog(AppNotifier app, List<SwarmProjectGroup> groups) => _Glass(
++ child: LayoutBuilder(
++ builder: (context, size) {
++ final machines = _section('Machines', 'Link machine', onLinkMachine, [
++ if (app.machinesLoading && app.machineStates.isEmpty)
++ const SkeletonList(rows: 3),
++ for (final machine in app.machineStates.values)
++ _StarterRow(
++ name: machine.machine.displayName,
++ note: machine.needsLink
++ ? 'Link required'
++ : machine.nodeOnline == false
++ ? 'Offline'
++ : machine.isLocalMachine
++ ? 'Local'
++ : null,
++ count: machine.agents.length,
++ onTap: () => onMachine(machine),
++ ),
++ if (!app.machinesLoading && app.machineStates.isEmpty)
++ const Padding(
++ padding: EdgeInsets.symmetric(vertical: 18),
++ child: Text('Link a machine to find its agents.'),
++ ),
++ ]);
++ final projects = _section('Projects', 'Add project', onAddProject, [
++ for (final group in groups)
++ _StarterRow(
++ name: group.name,
++ count: group.agents.length,
++ onTap: () => onProject(group),
++ onManage: onProjectAgents == null
++ ? null
++ : () => onProjectAgents!(group),
++ ),
++ if (groups.isEmpty)
++ const Padding(
++ padding: EdgeInsets.symmetric(vertical: 18),
++ child: Text(
++ 'Add a working folder to start a project.',
++ style: TextStyle(color: Color(0xffc5bece), fontSize: 12),
++ ),
++ ),
++ ]);
++ return size.maxWidth < 570
++ ? Column(children: [machines, const SizedBox(height: 24), projects])
++ : Row(
++ crossAxisAlignment: CrossAxisAlignment.start,
++ children: [
++ Expanded(child: machines),
++ const SizedBox(width: 36),
++ Expanded(child: projects),
++ ],
++ );
++ },
++ ),
++ );
++
+ Widget _section(
+ String title,
+ String action,
+@@ -321,82 +211,6 @@ class SwarmWelcome extends StatelessWidget {
+ );
+ }
+
+-class _FirstAgentGuide extends StatelessWidget {
+- const _FirstAgentGuide({required this.onLinkMachine});
+- final VoidCallback onLinkMachine;
+-
+- @override
+- Widget build(BuildContext context) => Column(
+- crossAxisAlignment: CrossAxisAlignment.start,
+- children: [
+- const Text(
+- 'Your first workspace',
+- style: TextStyle(fontSize: 14, fontWeight: FontWeight.w500),
+- ),
+- const SizedBox(height: 16),
+- for (final (number, title, detail) in const [
+- ('1', 'Choose a folder', 'Use a project you already work on.'),
+- ('2', 'Pick your agent', 'Claude Code, Codex, or another agent.'),
+- (
+- '3',
+- 'Start working',
+- 'Your agent opens here. Sign in if needed, then give it a task.',
+- ),
+- ])
+- Padding(
+- padding: const EdgeInsets.only(bottom: 14),
+- child: Row(
+- children: [
+- Container(
+- width: 28,
+- height: 28,
+- alignment: Alignment.center,
+- decoration: const BoxDecoration(
+- color: Colors.white10,
+- shape: BoxShape.circle,
+- ),
+- child: Text(
+- number,
+- style: const TextStyle(fontSize: 12, color: Colors.white70),
+- ),
+- ),
+- const SizedBox(width: 12),
+- Expanded(
+- child: Column(
+- crossAxisAlignment: CrossAxisAlignment.start,
+- children: [
+- Text(
+- title,
+- style: const TextStyle(
+- fontSize: 13,
+- fontWeight: FontWeight.w500,
+- ),
+- ),
+- const SizedBox(height: 2),
+- Text(
+- detail,
+- style: const TextStyle(
+- fontSize: 12,
+- color: Colors.white70,
+- ),
+- ),
+- ],
+- ),
+- ),
+- ],
+- ),
+- ),
+- TextButton(
+- onPressed: onLinkMachine,
+- child: const Text(
+- 'Link another machine',
+- style: TextStyle(color: Colors.white70),
+- ),
+- ),
+- ],
+- );
+-}
+-
+ class SwarmSearchField extends StatefulWidget {
+ const SwarmSearchField({
+ super.key,
diff --git a/docs/handoff/app-v2-2026-09-13/picker-files.txt b/docs/handoff/app-v2-2026-09-13/picker-files.txt
new file mode 100644
index 000000000..f4c659d2d
--- /dev/null
+++ b/docs/handoff/app-v2-2026-09-13/picker-files.txt
@@ -0,0 +1,21 @@
+desktop/lib/screens/swarm_screen.dart
+desktop/lib/shared/widgets/app_dialog.dart
+desktop/lib/shortcuts/keymap_commands.dart
+desktop/lib/state/swarm_navigation.dart
+desktop/lib/state/swarm_search.dart
+desktop/lib/terminal/search_output_preview.dart
+desktop/lib/widgets/agent_switcher.dart
+desktop/lib/widgets/device_row.dart
+desktop/lib/widgets/swarm_attention.dart
+desktop/lib/widgets/swarm_inline_search.dart
+desktop/lib/widgets/swarm_search_input.dart
+desktop/lib/widgets/swarm_switcher.dart
+desktop/lib/widgets/task_palette.dart
+desktop/macos/Runner/SwarmTitlebar.swift
+desktop/test/first_workspace_test.dart
+desktop/test/keymap_runtime_test.dart
+desktop/test/swarm_inline_search_test.dart
+desktop/test/swarm_search_preview_test.dart
+desktop/test/swarm_split_test.dart
+desktop/tool/keymap_native_checks.swift
+desktop/tool/swarm_titlebar_checks.swift
diff --git a/docs/handoff/app-v2-2026-09-13/picker-wip.patch b/docs/handoff/app-v2-2026-09-13/picker-wip.patch
new file mode 100644
index 000000000..6737ec6fe
--- /dev/null
+++ b/docs/handoff/app-v2-2026-09-13/picker-wip.patch
@@ -0,0 +1,1716 @@
+diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
+index 4aefbf5..872e137 100644
+--- a/desktop/lib/screens/swarm_screen.dart
++++ b/desktop/lib/screens/swarm_screen.dart
+@@ -12,6 +12,7 @@ import '../core/test_run.dart';
+ import '../settings/settings_screen.dart';
+ import '../settings/settings_section.dart';
+ import '../shared/theme/app_theme.dart' as grid;
++import '../shared/widgets/app_dialog.dart';
+ import '../shortcuts/app_shortcuts.dart';
+ import '../shortcuts/app_keymap.dart';
+ import '../shortcuts/keymap.dart';
+@@ -202,6 +203,10 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ mounted && _routeIsCurrent && !_dialogOpen && !_spokenPaletteOpen;
+
+ void _runShortcut(String id) {
++ if (id == 'agent.new' && _search != null) {
++ unawaited(_newAgentFromSearch());
++ return;
++ }
+ if (!_canExecuteCommand(id)) return;
+ if (id != 'navigation.quick_open' && id != 'navigation.commands') {
+ _closeSearch();
+@@ -347,7 +352,6 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ const {
+ 'picker.next': 'next',
+ 'picker.previous': 'previous',
+- 'picker.preview': 'preview',
+ 'picker.accept': 'submit',
+ 'picker.add_here': 'add',
+ 'picker.cancel': 'close',
+@@ -358,8 +362,6 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ search.move(1);
+ case 'previous':
+ search.move(-1);
+- case 'preview':
+- search.togglePreview();
+ case 'submit':
+ final choice = search.submit();
+ if (choice != null) await _chooseSearch(choice);
+@@ -371,6 +373,11 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ }
+ return;
+ }
++ if (call.method == 'newAgent' && _search != null) {
++ unawaited(_newAgentFromSearch());
++ await WidgetsBinding.instance.endOfFrame;
++ return;
++ }
+ if (call.method != 'jump') _closeSearch(restoreFocus: false);
+ switch (call.method) {
+ case 'new':
+@@ -570,22 +577,13 @@ class _SwarmScreenState extends State<SwarmScreen> {
+
+ Future<void> _splitAgent(PaneResizeAxis axis) async {
+ final split = app.preparePaneSplit(axis);
+- final pane = app.focusedPane;
+- if (split == null || pane == null) return;
+- final machine = app.machineStates[pane.machineId];
+- final agent = machine?.agents
+- .where((a) => a.id == pane.agentId)
+- .firstOrNull;
+- await _newAgent(
+- machineId: pane.machineId,
+- folder: agent == null ? null : machine?.projectOf(agent)?.cwd,
+- swarmId: split.swarmId,
+- split: split,
+- );
++ if (split == null) return;
++ _openSearch(adding: true, split: split);
+ }
+
+ Future<void> _jump({bool historyOnly = false}) async {
+ if (!historyOnly) {
++ if (_search?.adding == true) _closeSearch(restoreFocus: false);
+ _openSearch();
+ _focusSearch(selectAll: true);
+ return;
+@@ -601,8 +599,9 @@ class _SwarmScreenState extends State<SwarmScreen> {
+
+ Future<void> _activateSearch(
+ SwarmSearchSelection selected,
+- String target,
+- ) async {
++ String target, {
++ PaneSplitRequest? split,
++ }) async {
+ final command = selected.destination.commandId;
+ if (command != null) {
+ // The result list is gone before a dialog or focus-changing command runs.
+@@ -617,6 +616,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ selected,
+ destinationSwarmId: target,
+ projects: _projects.projects,
++ split: split,
+ );
+ if (!opened && mounted) {
+ ScaffoldMessenger.of(context).showSnackBar(
+@@ -627,7 +627,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ }
+ }
+
+- void _openSearch() {
++ void _openSearch({bool adding = false, PaneSplitRequest? split}) {
+ if (_search != null ||
+ !mounted ||
+ _dialogOpen ||
+@@ -644,7 +644,8 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ _navigation.recent,
+ projects: _projects,
+ commands: _searchCommands,
+- previewInitiallyEnabled: true,
++ adding: adding,
++ split: split,
+ );
+ _search!.addListener(_syncSearch);
+ _searchOverlay = OverlayEntry(builder: _buildSearchOverlay);
+@@ -666,6 +667,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ }
+
+ void _showSearchCommands() {
++ if (_search?.adding == true) _closeSearch(restoreFocus: false);
+ _openSearch();
+ _search?.setQuery('> ');
+ _focusSearch();
+@@ -707,9 +709,19 @@ class _SwarmScreenState extends State<SwarmScreen> {
+
+ Future<void> _chooseSearch(SwarmSearchSelection choice) async {
+ final target = _search?.targetId;
++ final split = _search?.split;
+ if (target == null) return;
+ _closeSearch(restoreFocus: choice.destination.isCommand);
+- await _activateSearch(choice, target);
++ await _activateSearch(choice, target, split: split);
++ }
++
++ Future<void> _newAgentFromSearch() async {
++ final search = _search;
++ if (search == null || !search.canCreate) return;
++ final target = search.targetId;
++ final split = search.split;
++ _closeSearch(restoreFocus: false);
++ await _newAgent(swarmId: target, split: split);
+ }
+
+ Widget _buildSearchOverlay(BuildContext context) {
+@@ -723,7 +735,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ child: GestureDetector(
+ behavior: HitTestBehavior.opaque,
+ onTap: _closeSearch,
+- child: const ColoredBox(color: Color(0x66000000)),
++ child: const ColoredBox(color: kDialogVeilTint),
+ ),
+ ),
+ Align(
+@@ -752,6 +764,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ onClose: _closeSearch,
+ onChanged: search.setQuery,
+ showClose: true,
++ onNewAgent: _newAgentFromSearch,
+ ),
+ const Divider(height: 1, color: Colors.white12),
+ Expanded(
+@@ -759,7 +772,10 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ search: search,
+ onChoose: _chooseSearch,
+ onRefocus: _focusSearch,
+- onCommands: _showSearchCommands,
++ onCommands: search.allowsCommands
++ ? _showSearchCommands
++ : null,
++ onNewAgent: _newAgentFromSearch,
+ ),
+ ),
+ ],
+@@ -1062,6 +1078,17 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ autofocus: app.panes.isNotEmpty,
+ child: Scaffold(
+ backgroundColor: grid.AppPalette.swarmField,
++ floatingActionButtonLocation:
++ FloatingActionButtonLocation.endFloat,
++ floatingActionButton: FloatingActionButton.small(
++ key: const ValueKey('swarm-add-agent-button'),
++ tooltip: 'Add agent',
++ onPressed: () => _openSearch(adding: true),
++ backgroundColor: grid.AppPalette.swarmAccent,
++ foregroundColor: grid.AppPalette.swarmField,
++ shape: const CircleBorder(),
++ child: const Icon(Icons.add, size: 24),
++ ),
+ body: Column(
+ children: [
+ if (!_native) _tabStrip(),
+@@ -1151,7 +1178,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ Padding(
+ padding: app.panes.isEmpty
+ ? EdgeInsets.zero
+- : const EdgeInsets.all(10),
++ : const EdgeInsets.fromLTRB(10, 10, 10, 68),
+ child: Stack(
+ children: [
+ Positioned.fill(
+@@ -1185,6 +1212,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ agentId: entry.agent.id,
+ engine: entry.agent.engine,
+ ),
++ SwarmSearchAction.addHere,
+ ),
+ app.activeSwarmId,
+ ),
+@@ -1197,6 +1225,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ recent: _navigation.recent,
+ commands: _searchCommands,
+ onChoose: _activateSearch,
++ onNewAgent: _newAgent,
+ ),
+ onAddProject: _addProject,
+ onLinkMachine: () => _dialog(
+@@ -1313,16 +1342,6 @@ class _SwarmScreenState extends State<SwarmScreen> {
+ onPressed: _jump,
+ icon: const Icon(Icons.search, size: 20),
+ ),
+- IconButton(
+- key: const ValueKey('swarm-new-agent-button'),
+- tooltip: withEffectiveShortcutHint(
+- context,
+- 'New agent',
+- ShortcutAction.newAgent,
+- ),
+- onPressed: _newAgent,
+- icon: const Icon(Icons.add, size: 20),
+- ),
+ IconButton(
+ key: const ValueKey('swarm-notifications-button'),
+ tooltip: withEffectiveShortcutHint(
+diff --git a/desktop/lib/shared/widgets/app_dialog.dart b/desktop/lib/shared/widgets/app_dialog.dart
+index e9faf0c..d43fdf6 100644
+--- a/desktop/lib/shared/widgets/app_dialog.dart
++++ b/desktop/lib/shared/widgets/app_dialog.dart
+@@ -27,14 +27,9 @@ import 'package:flutter/services.dart';
+ /// still reads as the window.
+ const double kDialogVeilBlur = 7;
+
+-/// The tint over that blur.
+-///
+-/// `rgba(0,0,0,.64)` — deeper than Material's own 54% black barrier looks over
+-/// a light page, because this one is laid over a dark one, where the same alpha
+-/// barely registers. Read against the panel's own fill rather than picked off a
+-/// scale: the dialog has to sit clearly in front of the veil, and the veil
+-/// clearly in front of the window.
+-const Color kDialogVeilTint = Color(0xA3000000);
++/// Shared dark backdrop for dialogs and centered pickers. Terminal output
++/// stays in the background while the active surface has the user's attention.
++const Color kDialogVeilTint = Color(0xC7000000);
+
+ /// The app's dialog barrier: a blur, then a tint, then whatever opened.
+ ///
+diff --git a/desktop/lib/shortcuts/keymap_commands.dart b/desktop/lib/shortcuts/keymap_commands.dart
+index 1c18302..e3d1b11 100644
+--- a/desktop/lib/shortcuts/keymap_commands.dart
++++ b/desktop/lib/shortcuts/keymap_commands.dart
+@@ -368,13 +368,6 @@ final harnessCommands = <HarnessCommand>[
+ extraKeys: ['cmd+enter'],
+ context: KeymapContext.picker,
+ ),
+- const HarnessCommand(
+- 'picker.preview',
+- 'Toggle agent output preview',
+- ShortcutGroup.navigate,
+- extraKeys: ['cmd+i'],
+- context: KeymapContext.picker,
+- ),
+ const HarnessCommand(
+ 'picker.cancel',
+ 'Close search',
+diff --git a/desktop/lib/state/swarm_navigation.dart b/desktop/lib/state/swarm_navigation.dart
+index 5808bb3..ad9e04f 100644
+--- a/desktop/lib/state/swarm_navigation.dart
++++ b/desktop/lib/state/swarm_navigation.dart
+@@ -1,8 +1,9 @@
+-import 'package:flutter/foundation.dart' show listEquals;
++import 'package:flutter/foundation.dart' show listEquals, setEquals;
+
+ import '../core/fuzzy_match.dart';
+ import '../core/models.dart';
+ import 'app_state.dart';
++import 'pane_arrangement.dart';
+ import 'swarm.dart';
+ import 'swarm_catalog.dart';
+
+@@ -284,6 +285,7 @@ Future<bool> activateSwarmSearchSelection(
+ SwarmSearchSelection selection, {
+ required String destinationSwarmId,
+ List<SavedSwarmProject> projects = const [],
++ PaneSplitRequest? split,
+ }) async {
+ final destination = selection.destination;
+ if (selection.action == SwarmSearchAction.open && !destination.isGroup) {
+@@ -294,7 +296,36 @@ Future<bool> activateSwarmSearchSelection(
+ );
+ }
+ if (selection.action == SwarmSearchAction.addHere) {
++ if (destination.agentId == null) {
++ if (split != null || destination.isCommand) return false;
++ final target = app.swarms.where((swarm) => swarm.id == destinationSwarmId).firstOrNull;
++ final catalog = SwarmSearchCatalog().read(app, projects);
++ final live = catalog.where((row) => row.id == destination.id).firstOrNull;
++ if (target == null || live == null ||
++ !setEquals(destination.members, live.members)) return false;
++ final members = catalog.where((row) => destination.members.contains(row.id) &&
++ !target.panes.any((pane) => pane.machineId == row.machineId &&
++ pane.agentId == row.agentId)).toList();
++ if (members.isEmpty || target.panes.length + members.length > AppNotifier.maxPanes ||
++ members.any((row) => !(app.machineStates[row.machineId]?.agents.any((agent) => agent.id == row.agentId) ?? false))) {
++ return false;
++ }
++ if (target.panes.isEmpty && target.name == 'New swarm') {
++ app.renameSwarm(target.id, destination.title);
++ }
++ // Every membership is recorded before awaiting any attachment. A slow
++ // machine cannot retarget the add or hold up the other agents.
++ await Future.wait([
++ for (final row in members)
++ app.addAgentToSwarm(row.machineId!, row.agentId!, swarmId: target.id),
++ ]);
++ return members.every((row) => target.panes.any((pane) =>
++ pane.machineId == row.machineId && pane.agentId == row.agentId));
++ }
+ if (destination.agentId == null ||
++ (split != null &&
++ (split.swarmId != destinationSwarmId ||
++ !app.isPaneSplitCurrent(split))) ||
+ !app.swarms.any((s) => s.id == destinationSwarmId)) {
+ return false;
+ }
+@@ -302,10 +333,12 @@ Future<bool> activateSwarmSearchSelection(
+ .where((e) => e.id == destination.id)
+ .firstOrNull;
+ if (live == null) return false;
+- await app.addAgentToSwarm(
++ await app.assignAgentToPane(
++ null,
+ destination.machineId!,
+ destination.agentId!,
+ swarmId: destinationSwarmId,
++ split: split,
+ );
+ if (app.activeSwarmId == destinationSwarmId) {
+ app.revealAgentView(
+@@ -485,6 +518,10 @@ List<SwarmDestination> swarmDestinations(
+ if (pane.agentId != null) pane.machineId,
+ ]),
+ detail: _agentCountLabel(swarm.panes.map((pane) => pane.agentId)),
++ members: {
++ for (final pane in swarm.panes)
++ if (pane.agentId != null) agentDestinationId(pane.machineId, pane.agentId!),
++ },
+ swarmId: swarm.id,
+ current: swarm.id == app.activeSwarmId,
+ searchFields: context.toSet(),
+diff --git a/desktop/lib/state/swarm_search.dart b/desktop/lib/state/swarm_search.dart
+index a3ddf3b..2d055bc 100644
+--- a/desktop/lib/state/swarm_search.dart
++++ b/desktop/lib/state/swarm_search.dart
+@@ -4,6 +4,7 @@ import 'package:xterm/xterm.dart';
+ import '../terminal/search_output_preview.dart';
+
+ import 'app_state.dart';
++import 'pane_arrangement.dart';
+ import 'swarm_catalog.dart';
+ import 'swarm_navigation.dart';
+
+@@ -16,9 +17,9 @@ class SwarmSearchController extends ChangeNotifier {
+ this.projects,
+ this.history,
+ this.commands,
+- bool previewInitiallyEnabled = false,
+- }) : previewEnabled = previewInitiallyEnabled,
+- targetId = app.activeSwarmId,
++ this.adding = false,
++ this.split,
++ }) : targetId = app.activeSwarmId,
+ targetName = app.activeSwarm.name {
+ _refresh();
+ app.addListener(_refresh);
+@@ -33,7 +34,10 @@ class SwarmSearchController extends ChangeNotifier {
+ /// Availability is read from workspace state and rechecked at activation.
+ /// Commands never enter the ordinary agent/swarm catalog or History.
+ final List<SwarmDestination> Function()? commands;
+- bool get isCommandMode => history == null && query.trimLeft().startsWith('>');
++ final bool adding;
++ final PaneSplitRequest? split;
++ bool get allowsCommands => split == null && history == null;
++ bool get isCommandMode => allowsCommands && query.trimLeft().startsWith('>');
+ final String targetId, targetName;
+ final _cache = SwarmSearchCatalog();
+ List<SwarmDestination> _catalog = const [];
+@@ -42,7 +46,6 @@ class SwarmSearchController extends ChangeNotifier {
+ String query = '';
+ String? _selectedId;
+ int cursor = 0;
+- bool previewEnabled;
+ SearchOutputPreview? preview;
+ String? _previewId;
+
+@@ -51,13 +54,22 @@ class SwarmSearchController extends ChangeNotifier {
+ history == null &&
+ selected != null &&
+ selected?.closedId == null;
+- bool get previewVisible => previewEnabled && canPreview;
++ bool get previewVisible => canPreview;
+
+- void togglePreview() {
+- if (!previewEnabled && !canPreview) return;
+- previewEnabled = !previewEnabled;
+- _updatePreview();
+- notifyListeners();
++ List<SwarmDestination> get previewMembers {
++ final row = selected;
++ if (row == null || row.agentId != null) return const [];
++ final memberIds = row.isGroup
++ ? row.members
++ : {
++ for (final swarm in app.swarms.where(
++ (swarm) => swarm.id == row.swarmId,
++ ))
++ for (final pane in swarm.panes)
++ if (pane.agentId != null)
++ agentDestinationId(pane.machineId, pane.agentId!),
++ };
++ return _catalog.where((entry) => memberIds.contains(entry.id)).toList();
+ }
+
+ void _updatePreview() {
+@@ -68,8 +80,8 @@ class SwarmSearchController extends ChangeNotifier {
+ }
+ final row = selected!;
+ // Keep a snapshot while this selection stays put. Query edits and output
+- // traffic do not read the buffers again. A new selection or re-enabling
+- // preview captures fresh context, including any replacement session.
++ // traffic do not read the buffers again. Choosing another result
++ // captures fresh context, including any replacement session.
+ if (_previewId == row.id) return;
+ final terminal = app.allPanes
+ .where(
+@@ -88,13 +100,41 @@ class SwarmSearchController extends ChangeNotifier {
+ ? 'Search commands…'
+ : history != null
+ ? 'Search history…'
++ : adding
++ ? 'Search agents to add…'
+ : 'Search agents, swarms, machines, projects…';
+
++ bool get canCreate =>
++ history == null &&
++ app.swarms.any(
++ (swarm) =>
++ swarm.id == targetId && swarm.panes.length < AppNotifier.maxPanes,
++ ) &&
++ (split == null || app.isPaneSplitCurrent(split!));
++
++ String get primaryAction => switch (split?.axis) {
++ PaneResizeAxis.x => 'Split right',
++ PaneResizeAxis.y => 'Split down',
++ null => 'Add to this swarm',
++ };
++
++ String actionLabel(SwarmDestination? row) => row?.isCommand == true ? action(row!) : adding
++ ? row != null && row.agentId == null && split == null && _missingIds(row).length > 1
++ ? 'Add ${_missingIds(row).length} agents' : primaryAction
++ : row == null
++ ? 'Go to'
++ : action(row);
++
++ String get unavailableMessage =>
++ split != null && !app.isPaneSplitCurrent(split!)
++ ? 'The layout changed. Split the agent again.'
++ : 'This swarm has no room for another agent.';
++
+ void _refresh() {
+ final next = history == null
+ ? _cache.read(app, projects?.projects ?? const [], recent: recent)
+ : [...history!.menuDestinations(app), ...closedWorkDestinations(app)];
+- if (identical(next, _catalog) && !isCommandMode) return;
++ if (identical(next, _catalog) && !isCommandMode && !adding) return;
+ _catalog = next;
+ _filter();
+ notifyListeners();
+@@ -116,7 +156,14 @@ class SwarmSearchController extends ChangeNotifier {
+ availableCommands,
+ query.trimLeft().substring(1).trimLeft(),
+ )
+- : rankSwarmDestinations(_catalog, query, recent: recent);
++ : rankSwarmDestinations(
++ adding
++ ? _catalog.where((row) => (split == null || row.agentId != null) &&
++ _missingIds(row).isNotEmpty).toList()
++ : _catalog,
++ query,
++ recent: recent,
++ );
+ final index = rows.indexWhere((row) => row.id == _selectedId);
+ cursor = rows.isEmpty
+ ? 0
+@@ -152,29 +199,40 @@ class SwarmSearchController extends ChangeNotifier {
+ false)) {
+ return null;
+ }
+- return SwarmSearchSelection(destination);
++ return SwarmSearchSelection(
++ destination,
++ adding ? SwarmSearchAction.addHere : SwarmSearchAction.open,
++ );
+ }
+
+ bool canSubmit(SwarmDestination? row) =>
+ row != null &&
++ (!adding || row.isCommand || canAdd(row)) &&
+ (!row.isCommand || (isCommandMode && _commandIds.contains(row.id))) &&
+- (!row.isGroup ||
++ (adding || !row.isGroup ||
+ canOpenSwarmGroup(app, row, destinationSwarmId: targetId)) &&
+ (row.closedId == null || app.canReopenClosed(row.closedId!));
+
++ Set<String> _missingIds(SwarmDestination row) {
++ final members = row.agentId == null ? row.members : {row.id};
++ final present = {
++ for (final swarm in app.swarms.where((swarm) => swarm.id == targetId))
++ for (final pane in swarm.panes)
++ if (pane.agentId != null) agentDestinationId(pane.machineId, pane.agentId!),
++ };
++ return members.difference(present);
++ }
++
+ bool canAdd(SwarmDestination? row) =>
+ history == null &&
+- row?.agentId != null &&
+- row!.hasView &&
++ row != null && !row.isCommand && row.closedId == null &&
++ _missingIds(row).isNotEmpty &&
++ (split == null || row.agentId != null) &&
++ (split == null || app.isPaneSplitCurrent(split!)) &&
+ app.swarms.any(
+ (swarm) =>
+ swarm.id == targetId &&
+- swarm.panes.length < AppNotifier.maxPanes &&
+- !swarm.panes.any(
+- (pane) =>
+- pane.machineId == row.machineId &&
+- pane.agentId == row.agentId,
+- ),
++ swarm.panes.length + _missingIds(row).length <= AppNotifier.maxPanes,
+ );
+
+ SwarmSearchSelection? addHere() => canAdd(selected)
+diff --git a/desktop/lib/terminal/search_output_preview.dart b/desktop/lib/terminal/search_output_preview.dart
+index 772ae03..f320c53 100644
+--- a/desktop/lib/terminal/search_output_preview.dart
++++ b/desktop/lib/terminal/search_output_preview.dart
+@@ -10,27 +10,67 @@ class SearchOutputPreview {
+ // Covers the maximum 120-row viewport plus a small amount of scrollback,
+ // including a short prompt near the top of an otherwise empty tall pane.
+ static const scannedLines = 160;
+- static const shownLines = 12;
+ static const shownColumns = 192;
++ static const shownCharacters = 720;
+ final String text;
+ static final _controls = RegExp(r'[\x00-\x1f\x7f-\x9f]');
++ static final _rules = RegExp(r'[-─━═_╌┄─]{4,}');
++ static final _frame = RegExp(r'^[│┃┆╎┊┇]+\s*');
++ static final _prompt = RegExp(r'^[>›❯_$▌█\s]+$');
++ static final _blockStart = RegExp(r'^(?:[>›❯•●◦]|[-*]\s|\d+\.\s)');
+
+ static SearchOutputPreview capture(Terminal? terminal) {
+ if (terminal == null) return const SearchOutputPreview('');
+ final lines = terminal.buffer.lines;
+- final excerpt = <String>[];
++ final logical = <String>[];
+ final start = math.max(0, lines.length - scannedLines);
+- for (var row = lines.length - 1; row >= start; row--) {
++ for (var row = start; row < lines.length; row++) {
+ // getText works in terminal cells, so a wide Unicode character is not
+ // split as it could be by slicing an arbitrary UTF-16 string.
+ final text = lines[row]
+ .getText(0, shownColumns)
+ .replaceAll(_controls, '')
+ .trimRight();
+- if (text.trim().isEmpty) continue;
+- excerpt.add(text);
+- if (excerpt.length == shownLines) break;
++ if (lines[row].isWrapped && logical.isNotEmpty) {
++ logical[logical.length - 1] += text;
++ } else {
++ logical.add(text);
++ }
+ }
+- return SearchOutputPreview(excerpt.reversed.join('\n'));
++ final blocks = <String>[];
++ var paragraph = '';
++ void finish() {
++ if (paragraph.isNotEmpty) blocks.add(paragraph);
++ paragraph = '';
++ }
++
++ for (final line in logical) {
++ final text = line.replaceAll(_rules, '').trim().replaceFirst(_frame, '');
++ if (text.isEmpty ||
++ _prompt.hasMatch(text) ||
++ text == 'Conversation recap' ||
++ RegExp(r'^Ask (Codex|Claude) to ').hasMatch(text)) {
++ finish();
++ continue;
++ }
++ if (_blockStart.hasMatch(text) || !line.startsWith(RegExp(r'\s')))
++ finish();
++ paragraph = paragraph.isEmpty ? text : '$paragraph $text';
++ }
++ finish();
++ // Show complete recent paragraphs, not the bottom of a wrapped terminal
++ // viewport. This is a reading excerpt, never a second terminal renderer.
++ final recentBlocks = blocks.skip(math.max(0, blocks.length - 3)).toList();
++ while (recentBlocks.length > 1 &&
++ recentBlocks.join('\n\n').runes.length > shownCharacters) {
++ recentBlocks.removeAt(0);
++ }
++ final recent = recentBlocks.join('\n\n');
++ final characters = recent.runes.toList();
++ return SearchOutputPreview(
++ characters.length <= shownCharacters
++ ? recent
++ : '${String.fromCharCodes(characters.take(shownCharacters)).trimRight()}…',
++ );
+ }
+ }
+diff --git a/desktop/lib/widgets/agent_switcher.dart b/desktop/lib/widgets/agent_switcher.dart
+index 60bc977..8bd1c36 100644
+--- a/desktop/lib/widgets/agent_switcher.dart
++++ b/desktop/lib/widgets/agent_switcher.dart
+@@ -6,6 +6,7 @@ import 'package:flutter/services.dart';
+ import '../core/models.dart';
+ import '../core/fuzzy_match.dart';
+ import '../shared/theme/app_theme.dart' as grid;
++import '../shared/widgets/app_dialog.dart';
+ import '../state/app_state.dart';
+ import 'engine_identity.dart';
+
+@@ -42,7 +43,7 @@ Future<void> showAgentSwitcher(BuildContext context, AppNotifier notifier) {
+ _switcherOpen = true;
+ return showDialog<void>(
+ context: context,
+- barrierColor: Colors.black.withValues(alpha: 0.3),
++ barrierColor: kDialogVeilTint,
+ builder: (context) => _AgentSwitcher(notifier: notifier),
+ ).whenComplete(() => _switcherOpen = false);
+ }
+diff --git a/desktop/lib/widgets/device_row.dart b/desktop/lib/widgets/device_row.dart
+index 4e440d6..4a277fd 100644
+--- a/desktop/lib/widgets/device_row.dart
++++ b/desktop/lib/widgets/device_row.dart
+@@ -4,6 +4,7 @@ import 'package:flutter/material.dart';
+ import 'package:url_launcher/url_launcher.dart';
+
+ import '../shared/theme/app_theme.dart' as grid;
++import '../shared/widgets/app_dialog.dart';
+ import '../state/app_state.dart';
+ import '../state/dial_status.dart';
+
+@@ -166,7 +167,7 @@ class _DeviceRowState extends State<DeviceRow> {
+ Future<void> _showStatus(BuildContext context) {
+ return showDialog<void>(
+ context: context,
+- barrierColor: Colors.black.withValues(alpha: 0.42),
++ barrierColor: kDialogVeilTint,
+ builder: (context) => _DeviceStatusCard(notifier: widget.notifier),
+ );
+ }
+diff --git a/desktop/lib/widgets/swarm_attention.dart b/desktop/lib/widgets/swarm_attention.dart
+index 8a01862..729c7aa 100644
+--- a/desktop/lib/widgets/swarm_attention.dart
++++ b/desktop/lib/widgets/swarm_attention.dart
+@@ -15,7 +15,6 @@ Future<SwarmAttentionEntry?> showSwarmAttention(
+ context: context,
+ transitionDuration: Duration.zero,
+ veilBlur: 0,
+- veilTint: const Color(0x66000000),
+ builder: (_) => _SwarmAttention(app: app, recent: history.recent),
+ );
+
+diff --git a/desktop/lib/widgets/swarm_inline_search.dart b/desktop/lib/widgets/swarm_inline_search.dart
+index 4c342ae..be0cab0 100644
+--- a/desktop/lib/widgets/swarm_inline_search.dart
++++ b/desktop/lib/widgets/swarm_inline_search.dart
+@@ -22,12 +22,14 @@ class SwarmInlineSearch extends StatefulWidget {
+ required this.recent,
+ required this.onChoose,
+ this.commands,
++ this.onNewAgent,
+ });
+
+ final AppNotifier app;
+ final SwarmProjectStore projects;
+ final List<String> recent;
+ final List<SwarmDestination> Function()? commands;
++ final VoidCallback? onNewAgent;
+ final void Function(SwarmSearchSelection choice, String target) onChoose;
+
+ @override
+@@ -73,7 +75,7 @@ class _SwarmInlineSearchState extends State<SwarmInlineSearch> {
+ widget.recent,
+ projects: widget.projects,
+ commands: widget.commands,
+- previewInitiallyEnabled: true,
++ adding: true,
+ )..setQuery(_text.text);
+ _search!.addListener(_changed);
+ _overlay.show();
+@@ -108,6 +110,12 @@ class _SwarmInlineSearchState extends State<SwarmInlineSearch> {
+ widget.onChoose(choice, target);
+ }
+
++ void _newAgent() {
++ if (_search?.canCreate == false) return;
++ _close();
++ widget.onNewAgent?.call();
++ }
++
+ @override
+ void dispose() {
+ _keymap?.removeListener(_keymapChanged);
+@@ -162,6 +170,7 @@ class _SwarmInlineSearchState extends State<SwarmInlineSearch> {
+ onChoose: _choose,
+ onRefocus: _focus.requestFocus,
+ onCommands: _showCommands,
++ onNewAgent: widget.onNewAgent == null ? null : _newAgent,
+ ),
+ ),
+ ),
+@@ -178,6 +187,7 @@ class _SwarmInlineSearchState extends State<SwarmInlineSearch> {
+ onChoose: _choose,
+ onClose: _close,
+ onOpen: _begin,
++ onNewAgent: widget.onNewAgent == null ? null : _newAgent,
+ onTapOutside: _close,
+ onChanged: (value) {
+ _begin();
+diff --git a/desktop/lib/widgets/swarm_search_input.dart b/desktop/lib/widgets/swarm_search_input.dart
+index 6c642a8..aa53b87 100644
+--- a/desktop/lib/widgets/swarm_search_input.dart
++++ b/desktop/lib/widgets/swarm_search_input.dart
+@@ -18,6 +18,7 @@ class SwarmSearchInput extends StatelessWidget {
+ required this.onClose,
+ required this.onChanged,
+ this.onOpen,
++ this.onNewAgent,
+ this.groupId,
+ this.onTapOutside,
+ this.showClose = false,
+@@ -32,6 +33,7 @@ class SwarmSearchInput extends StatelessWidget {
+ final VoidCallback onClose;
+ final ValueChanged<String> onChanged;
+ final VoidCallback? onOpen;
++ final VoidCallback? onNewAgent;
+ final Object? groupId;
+ final VoidCallback? onTapOutside;
+ final bool showClose, autofocus;
+@@ -52,6 +54,7 @@ class SwarmSearchInput extends StatelessWidget {
+ onChoose: onChoose,
+ onClose: onClose,
+ onOpen: onOpen,
++ onNewAgent: onNewAgent,
+ child: TextField(
+ key: inputKey,
+ groupId: groupId ?? EditableText,
+diff --git a/desktop/lib/widgets/swarm_switcher.dart b/desktop/lib/widgets/swarm_switcher.dart
+index 5389b34..d3219ec 100644
+--- a/desktop/lib/widgets/swarm_switcher.dart
++++ b/desktop/lib/widgets/swarm_switcher.dart
+@@ -25,7 +25,6 @@ Future<SwarmSearchSelection?> showSwarmHistory(
+ context: context,
+ transitionDuration: Duration.zero,
+ veilBlur: 0,
+- veilTint: const Color(0x66000000),
+ builder: (_) => _SwarmHistory(search: search),
+ );
+ } finally {
+@@ -113,6 +112,7 @@ class SwarmSearchKeys extends StatelessWidget {
+ required this.onChoose,
+ required this.onClose,
+ this.onOpen,
++ this.onNewAgent,
+ required this.child,
+ });
+ final SwarmSearchController? search;
+@@ -123,6 +123,7 @@ class SwarmSearchKeys extends StatelessWidget {
+ /// A focused field may be ready for typing while its suggestions are closed.
+ /// The first navigation/accept key reveals them without choosing unseen work.
+ final VoidCallback? onOpen;
++ final VoidCallback? onNewAgent;
+ final Widget child;
+
+ @override
+@@ -154,14 +155,14 @@ class SwarmSearchKeys extends StatelessWidget {
+ contextKind: KeymapContext.picker,
+ composing: composing,
+ actions: {
++ if (onNewAgent != null) 'agent.new': () => run(onNewAgent!),
+ if (search != null || onOpen != null) ...{
+ 'picker.accept': () => choose(false),
+ 'picker.add_here': () => choose(true),
+ 'picker.next': () => move(1),
+ 'picker.previous': () => move(-1),
+- if (search != null) 'picker.preview': search.togglePreview,
+ 'picker.cancel': onClose,
+- if (search?.history == null)
++ if (search == null || search.allowsCommands)
+ 'navigation.commands': () {
+ editing.value = const TextEditingValue(
+ text: '> ',
+@@ -182,6 +183,13 @@ class SwarmSearchKeys extends StatelessWidget {
+ bindings: search == null && onOpen == null
+ ? {}
+ : {
++ if (onNewAgent != null)
++ const SingleActivator(
++ LogicalKeyboardKey.keyN,
++ meta: true,
++ includeRepeats: false,
++ ): () =>
++ run(onNewAgent!),
+ const SingleActivator(
+ LogicalKeyboardKey.enter,
+ includeRepeats: false,
+@@ -207,13 +215,6 @@ class SwarmSearchKeys extends StatelessWidget {
+ const SingleActivator(LogicalKeyboardKey.arrowDown): () =>
+ move(1),
+ const SingleActivator(LogicalKeyboardKey.arrowUp): () => move(-1),
+- if (search != null)
+- const SingleActivator(
+- LogicalKeyboardKey.keyI,
+- meta: true,
+- includeRepeats: false,
+- ): () =>
+- run(search.togglePreview),
+ const SingleActivator(
+ LogicalKeyboardKey.keyN,
+ control: true,
+@@ -268,11 +269,13 @@ class SwarmSearchResults extends StatefulWidget {
+ required this.onChoose,
+ required this.onRefocus,
+ this.onCommands,
++ this.onNewAgent,
+ });
+ final SwarmSearchController search;
+ final ValueChanged<SwarmSearchSelection> onChoose;
+ final VoidCallback onRefocus;
+ final VoidCallback? onCommands;
++ final VoidCallback? onNewAgent;
+ @override
+ State<SwarmSearchResults> createState() => _SwarmSearchResultsState();
+ }
+@@ -341,15 +344,17 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
+ );
+ return LayoutBuilder(
+ builder: (context, constraints) {
+- final showPreview =
+- search.previewVisible && constraints.maxWidth >= 600;
++ final showPreview = search.previewVisible;
+ return Semantics(
+ container: true,
+ label: 'Search results',
+ child: Column(
+ children: [
+ Expanded(
+- child: Row(
++ child: Flex(
++ direction: constraints.maxWidth >= 600
++ ? Axis.horizontal
++ : Axis.vertical,
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ Expanded(
+@@ -359,6 +364,10 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
+ child: Text(
+ search.isCommandMode
+ ? 'No matching commands'
++ : search.adding && search.query.isEmpty
++ ? 'Choose New agent to start fresh.'
++ : search.adding
++ ? 'No matching agents'
+ : 'No matching results',
+ style: const TextStyle(
+ fontSize: 14,
+@@ -381,6 +390,7 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
+ enabled: search.canSubmit(row),
+ selected: index == search.cursor,
+ selectedColor: Colors.white,
++ hoverColor: Colors.transparent,
+ selectedTileColor: Colors.white.withValues(
+ alpha: .075,
+ ),
+@@ -442,12 +452,16 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
+ ),
+ ),
+ if (showPreview) ...[
+- const VerticalDivider(width: 1, color: Colors.white12),
++ if (constraints.maxWidth >= 600)
++ const VerticalDivider(width: 1, color: Colors.white12)
++ else
++ const Divider(height: 1, color: Colors.white12),
+ Expanded(
+ flex: 4,
+ child: _OutputPreview(
+ row: selected!,
+ text: search.preview?.text ?? '',
++ members: search.previewMembers,
+ ),
+ ),
+ ],
+@@ -461,7 +475,24 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
+ padding: const EdgeInsets.symmetric(horizontal: 12),
+ child: Row(
+ children: [
+- if (widget.onCommands != null)
++ if (widget.onNewAgent != null)
++ TextButton.icon(
++ key: const ValueKey('swarm-search-new-agent'),
++ onPressed: search.canCreate
++ ? widget.onNewAgent
++ : null,
++ style: TextButton.styleFrom(
++ foregroundColor: Colors.white,
++ ),
++ icon: const Icon(Icons.add, size: 16),
++ label: const Text(
++ 'New agent',
++ style: TextStyle(fontSize: 12),
++ ),
++ ),
++ if (widget.onCommands != null &&
++ (widget.onNewAgent == null ||
++ constraints.maxWidth >= 900))
+ TextButton(
+ key: const ValueKey('swarm-search-commands'),
+ onPressed: widget.onCommands,
+@@ -473,12 +504,15 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
+ style: TextStyle(fontSize: 12),
+ ),
+ ),
+- if (selected != null && !search.canSubmit(selected))
++ if ((selected != null && !search.canSubmit(selected)) ||
++ search.adding && !search.canCreate)
+ Expanded(
+ child: Text(
+- selected.isGroup &&
+- selected.members.length >
+- AppNotifier.maxPanes
++ search.adding
++ ? search.unavailableMessage
++ : selected!.isGroup &&
++ selected.members.length >
++ AppNotifier.maxPanes
+ ? 'A swarm supports up to ${AppNotifier.maxPanes} agents'
+ : 'No room to open this ${selected.isSwarm || selected.isGroup ? 'swarm' : 'agent'}',
+ maxLines: 1,
+@@ -491,37 +525,9 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
+ )
+ else
+ const Spacer(),
+- if (constraints.maxWidth >= 600 &&
+- (search.canPreview ||
+- search.previewEnabled && !search.isCommandMode))
+- IconButton(
+- key: const ValueKey('swarm-search-preview-toggle'),
+- tooltip: [
+- search.previewEnabled
+- ? 'Hide preview'
+- : 'Show preview',
+- if (effectiveCommandHint(
+- context,
+- 'picker.preview',
+- contextKind: KeymapContext.picker,
+- )
+- case final hint?)
+- '($hint)',
+- ].join(' '),
+- onPressed: () {
+- search.togglePreview();
+- widget.onRefocus();
+- },
+- icon: Icon(
+- search.previewEnabled
+- ? Icons.visibility_outlined
+- : Icons.visibility_off_outlined,
+- size: 18,
+- color: Colors.white60,
+- ),
+- visualDensity: VisualDensity.compact,
+- ),
+- if (search.canAdd(selected))
++ if (!search.adding &&
++ search.canAdd(selected) &&
++ constraints.maxWidth >= 900)
+ TextButton(
+ onPressed: () => widget.onChoose(search.addHere()!),
+ style: TextButton.styleFrom(
+@@ -537,11 +543,7 @@ class _SwarmSearchResultsState extends State<SwarmSearchResults> {
+ style: TextButton.styleFrom(
+ foregroundColor: Colors.white,
+ ),
+- child: _SearchActionLabel(
+- selected == null
+- ? 'Go to'
+- : SwarmSearchController.action(selected),
+- ),
++ child: _SearchActionLabel(search.actionLabel(selected)),
+ ),
+ ],
+ ),
+@@ -600,86 +602,128 @@ class _SearchActionLabel extends StatelessWidget {
+ }
+
+ class _OutputPreview extends StatelessWidget {
+- const _OutputPreview({required this.row, required this.text});
++ const _OutputPreview({
++ required this.row,
++ required this.text,
++ required this.members,
++ });
+ final SwarmDestination row;
+ final String text;
++ final List<SwarmDestination> members;
+
+ @override
+ Widget build(BuildContext context) => Container(
+ key: const ValueKey('swarm-search-preview'),
+- color: Colors.black.withValues(alpha: 0.10),
+- padding: const EdgeInsets.all(20),
+- child: Column(
+- crossAxisAlignment: CrossAxisAlignment.start,
+- children: [
+- Text(
+- row.agentId == null ? 'SWARM PREVIEW' : 'AGENT PREVIEW',
+- style: const TextStyle(
+- fontSize: 10,
+- letterSpacing: 1.3,
+- color: Colors.white54,
+- ),
+- ),
+- const SizedBox(height: 18),
+- Row(
+- children: [
+- if (row.agentId == null)
+- const SwarmIcon(size: 20, color: Colors.white70)
+- else
+- EngineMark(engine: row.engine, size: 20),
+- const SizedBox(width: 10),
+- Expanded(
+- child: Text(
+- row.title,
+- maxLines: 2,
+- overflow: TextOverflow.ellipsis,
+- style: const TextStyle(
+- fontSize: 15,
+- fontWeight: FontWeight.w500,
+- color: Colors.white,
++ color: Colors.black.withValues(alpha: .10),
++ child: SingleChildScrollView(
++ primary: false,
++ padding: const EdgeInsets.all(24),
++ child: Column(
++ crossAxisAlignment: CrossAxisAlignment.start,
++ children: [
++ Row(
++ crossAxisAlignment: CrossAxisAlignment.start,
++ children: [
++ if (row.agentId == null)
++ const SwarmIcon(size: 24, color: Colors.white70)
++ else
++ EngineMark(engine: row.engine, size: 24),
++ const SizedBox(width: 12),
++ Expanded(
++ child: Text(
++ row.title,
++ maxLines: 2,
++ overflow: TextOverflow.ellipsis,
++ style: const TextStyle(
++ fontSize: 16,
++ height: 1.35,
++ fontWeight: FontWeight.w600,
++ color: Colors.white,
++ ),
+ ),
+ ),
++ ],
++ ),
++ const SizedBox(height: 12),
++ Text(
++ row.detail,
++ maxLines: 2,
++ overflow: TextOverflow.ellipsis,
++ style: const TextStyle(
++ fontSize: 12,
++ height: 1.5,
++ color: Colors.white54,
+ ),
+- ],
+- ),
+- const SizedBox(height: 8),
+- Text(
+- row.detail,
+- maxLines: 3,
+- overflow: TextOverflow.ellipsis,
+- style: const TextStyle(
+- fontSize: 12,
+- height: 1.5,
+- color: Colors.white60,
+ ),
+- ),
+- const SizedBox(height: 24),
+- Expanded(
+- child: SingleChildScrollView(
+- primary: false,
+- child: Text(
+- row.agentId == null
+- ? 'Work with the agents in this swarm side by side.'
+- : text.isEmpty
+- ? 'No recent output available.'
+- : text,
+- style: TextStyle(
+- fontFamily: text.isEmpty
+- ? grid.AppFont.sans
+- : grid.AppFont.mono,
+- fontFamilyFallback: text.isEmpty
+- ? grid.AppFont.sansFallback
+- : grid.AppFont.monoFallback,
+- fontSize: 12,
+- height: 1.65,
+- color: text.isEmpty
+- ? Colors.white60
+- : Colors.white.withValues(alpha: .85),
+- ),
++ const SizedBox(height: 24),
++ Text(
++ row.agentId == null ? 'Agents in this swarm' : 'Recent output',
++ style: const TextStyle(
++ fontSize: 11,
++ fontWeight: FontWeight.w500,
++ color: Colors.white54,
+ ),
+ ),
+- ),
+- ],
++ const SizedBox(height: 10),
++ if (row.agentId != null)
++ Container(
++ width: double.infinity,
++ padding: const EdgeInsets.all(16),
++ decoration: BoxDecoration(
++ color: Colors.white.withValues(alpha: .035),
++ borderRadius: BorderRadius.circular(8),
++ border: Border.all(color: Colors.white.withValues(alpha: .06)),
++ ),
++ child: Text(
++ text.isEmpty ? 'No recent output yet.' : text,
++ maxLines: 12,
++ overflow: TextOverflow.ellipsis,
++ style: TextStyle(
++ fontFamily: grid.AppFont.sans,
++ fontFamilyFallback: grid.AppFont.sansFallback,
++ fontSize: 13,
++ height: 1.6,
++ color: text.isEmpty
++ ? Colors.white54
++ : Colors.white.withValues(alpha: .82),
++ ),
++ ),
++ )
++ else if (members.isEmpty)
++ const Text(
++ 'No agents yet.',
++ style: TextStyle(fontSize: 13, color: Colors.white54),
++ )
++ else ...[
++ for (final member in members.take(5))
++ Padding(
++ padding: const EdgeInsets.symmetric(vertical: 8),
++ child: Row(
++ children: [
++ EngineMark(engine: member.engine, size: 18),
++ const SizedBox(width: 10),
++ Expanded(
++ child: Text(
++ member.title,
++ maxLines: 1,
++ overflow: TextOverflow.ellipsis,
++ style: const TextStyle(
++ fontSize: 13,
++ color: Colors.white70,
++ ),
++ ),
++ ),
++ ],
++ ),
++ ),
++ if (members.length > 5)
++ Text(
++ '+ ${members.length - 5} more',
++ style: const TextStyle(fontSize: 12, color: Colors.white54),
++ ),
++ ],
++ ],
++ ),
+ ),
+ );
+ }
+diff --git a/desktop/lib/widgets/task_palette.dart b/desktop/lib/widgets/task_palette.dart
+index be20151..0a8c59f 100644
+--- a/desktop/lib/widgets/task_palette.dart
++++ b/desktop/lib/widgets/task_palette.dart
+@@ -6,6 +6,7 @@ import 'package:flutter/services.dart';
+
+ import '../core/models.dart';
+ import '../shared/theme/app_theme.dart' as grid;
++import '../shared/widgets/app_dialog.dart';
+ import '../state/app_state.dart';
+ import 'engine_identity.dart';
+
+@@ -113,7 +114,7 @@ abstract final class _D {
+ static const innerLight = Color(0x0FFFFFFF);
+
+ /// The veil.
+- static const veil = Color(0xBD000000); // rgba(0,0,0,.74)
++ static const veil = kDialogVeilTint;
+ static const veilBlur = 3.0;
+
+ /// ABOVE the middle, deliberately: the list grows downwards, and a box pinned to the centre would
+diff --git a/desktop/macos/Runner/SwarmTitlebar.swift b/desktop/macos/Runner/SwarmTitlebar.swift
+index 927c4e4..7932bbd 100644
+--- a/desktop/macos/Runner/SwarmTitlebar.swift
++++ b/desktop/macos/Runner/SwarmTitlebar.swift
+@@ -112,8 +112,6 @@ final class SwarmTitlebar: NSObject, NSMenuItemValidation, NSMenuDelegate {
+ keymap = map
+ let hint = map.hint(for: "navigation.quick_open", context: "workspace")
+ strip.searchButton.toolTip = hint.map { "Search (\($0))" } ?? "Search"
+- let newHint = map.hint(for: "agent.new", context: "workspace")
+- strip.newAgentButton.toolTip = newHint.map { "New agent (\($0))" } ?? "New agent"
+ if let main = NSApp.mainMenu, let window {
+ let menu = main as? HarnessKeymapMenu ?? HarnessKeymapMenu.replacing(main)
+ if NSApp.mainMenu !== menu { NSApp.mainMenu = menu }
+@@ -219,8 +217,7 @@ final class SwarmTitlebar: NSObject, NSMenuItemValidation, NSMenuDelegate {
+ install(agent, at: 2)
+
+ rebuildHistoryMenu()
+- let windowIndex = main.items.firstIndex(where: { $0.title == "Window" }) ?? main.numberOfItems
+- install(historyMenu, at: windowIndex)
++ install(historyMenu, at: 3)
+
+ // Native menu hints mirror Flutter; the shared picker owns all editing.
+ if let edit = main.item(withTitle: "Edit")?.submenu {
+@@ -235,7 +232,7 @@ final class SwarmTitlebar: NSObject, NSMenuItemValidation, NSMenuDelegate {
+ modelsMenu.autoenablesItems = false
+ modelsMenu.delegate = self
+ rebuildModelsMenu()
+- install(modelsMenu, at: windowIndex + 1)
++ install(modelsMenu, at: 3)
+ installTerminalFindMenu(main)
+ }
+
+@@ -662,7 +659,6 @@ private final class SwarmTabStrip: NSView {
+ private let document = NSView()
+ private let newButton = NSButton()
+ fileprivate let searchButton = NSButton()
+- fileprivate let newAgentButton = NSButton()
+ fileprivate let notificationButton = SwarmNotificationButton()
+ private var tabs: [SwarmTabButton] = []
+ private var activeId = ""
+@@ -695,10 +691,6 @@ private final class SwarmTabStrip: NSView {
+ button(newButton, "plus", "New swarm (⌘T)", #selector(newSwarm))
+ newButton.isEnabled = false
+ button(searchButton, "magnifyingglass", "Search (⌘P)", #selector(openSearch))
+- button(newAgentButton, "plus", "New agent (⌘N)", #selector(newAgent))
+- newAgentButton.imagePosition = .imageOnly
+- newAgentButton.setAccessibilityLabel("New agent")
+- newAgentButton.isEnabled = false
+ button(notificationButton, "bell", "Notifications", #selector(openNotifications))
+ searchButton.isEnabled = false
+ notificationButton.isEnabled = false
+@@ -711,7 +703,6 @@ private final class SwarmTabStrip: NSView {
+ guard nextPalette != palette else { return }
+ palette = nextPalette
+ searchButton.contentTintColor = palette.accent
+- newAgentButton.contentTintColor = palette.accent
+ notificationButton.contentTintColor = palette.accent
+ newButton.contentTintColor = palette.accent
+ for tab in tabs { tab.palette = palette }
+@@ -754,7 +745,6 @@ private final class SwarmTabStrip: NSView {
+ document.setAccessibilityChildren(tabs)
+ newButton.isEnabled = actionsEnabled && tabs.count < 24
+ searchButton.isEnabled = actionsEnabled
+- newAgentButton.isEnabled = actionsEnabled
+ notificationButton.isEnabled = actionsEnabled
+ let attention = state["attention"] as? Int ?? 0
+ notificationButton.hasAttention = attention > 0
+@@ -781,7 +771,7 @@ private final class SwarmTabStrip: NSView {
+ let activeWasVisible = active.map { scroll.documentVisibleRect.intersects($0.frame) } ?? false
+ let previousScrollSize = scroll.frame.size
+ let previousDocumentSize = document.frame.size
+- let available = max(132, bounds.width - 164)
++ let available = max(132, bounds.width - 124)
+ let width = min(220, max(132, available / CGFloat(max(1, tabs.count))))
+ let occupied = min(available, CGFloat(tabs.count) * width)
+ scroll.frame = NSRect(x: 0, y: 0, width: occupied, height: bounds.height)
+@@ -792,8 +782,7 @@ private final class SwarmTabStrip: NSView {
+ }
+ let buttonY = (bounds.height - 28) / 2
+ newButton.frame = NSRect(x: occupied + 4, y: buttonY, width: 28, height: 28)
+- searchButton.frame = NSRect(x: bounds.width - 120, y: buttonY, width: 28, height: 28)
+- newAgentButton.frame = NSRect(x: bounds.width - 80, y: buttonY, width: 28, height: 28)
++ searchButton.frame = NSRect(x: bounds.width - 80, y: buttonY, width: 28, height: 28)
+ notificationButton.frame = NSRect(x: bounds.width - 40, y: buttonY, width: 28, height: 28)
+ let geometryChanged = scroll.frame.size != previousScrollSize || document.frame.size != previousDocumentSize
+ if let active, revealActiveAfterLayout || (activeWasVisible && (geometryChanged || tabOrderChanged)) {
+@@ -823,11 +812,6 @@ private final class SwarmTabStrip: NSView {
+ if actionsEnabled { emit?("notifications", nil) }
+ }
+
+- @objc private func newAgent() {
+- guard actionsEnabled else { return }
+- emit?("newAgent", nil)
+- }
+-
+ private func draggedTab(_ sender: NSDraggingInfo) -> SwarmTabButton? {
+ guard actionsEnabled, sender.draggingSourceOperationMask.contains(.move),
+ let source = sender.draggingSource as? SwarmTabButton,
+diff --git a/desktop/test/first_workspace_test.dart b/desktop/test/first_workspace_test.dart
+index c1413ea..c2d3c16 100644
+--- a/desktop/test/first_workspace_test.dart
++++ b/desktop/test/first_workspace_test.dart
+@@ -159,7 +159,7 @@ void main() {
+
+ for (final native in [false, true]) {
+ testWidgets(
+- 'new agent toolbar ${native ? 'native' : 'Flutter'} action inherits the focused working folder',
++ 'new agent ${native ? 'native menu' : 'floating picker'} action inherits the focused working folder',
+ (tester) async {
+ tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(
+ const MethodChannel('harness/swarm_tabs'),
+@@ -193,18 +193,24 @@ void main() {
+ await opening;
+ } else {
+ final search = find.byKey(const ValueKey('swarm-search-button'));
+- final add = find.byKey(const ValueKey('swarm-new-agent-button'));
++ final add = find.byKey(const ValueKey('swarm-add-agent-button'));
+ final bell = find.byKey(const ValueKey('swarm-notifications-button'));
+ expect(
+ tester.getRect(search).right,
+- lessThanOrEqualTo(tester.getRect(add).left),
++ lessThanOrEqualTo(tester.getRect(bell).left),
+ );
++ expect(tester.getRect(add).left, greaterThan(1000));
+ expect(
+- tester.getRect(add).right,
+- lessThanOrEqualTo(tester.getRect(bell).left),
++ tester.getRect(add).top,
++ greaterThan(tester.getRect(find.byKey(pane.cellKey)).bottom),
+ );
+ await tester.tap(add);
+ await tester.pump();
++ expect(find.byType(AlertDialog), findsNothing);
++ await tester.tap(
++ find.byKey(const ValueKey('swarm-search-new-agent')),
++ );
++ await tester.pump();
+ }
+ expect(find.byType(AlertDialog), findsOneWidget);
+ expect(find.text('/work/existing'), findsOneWidget);
+diff --git a/desktop/test/keymap_runtime_test.dart b/desktop/test/keymap_runtime_test.dart
+index 655e3ab..9773a52 100644
+--- a/desktop/test/keymap_runtime_test.dart
++++ b/desktop/test/keymap_runtime_test.dart
+@@ -125,9 +125,7 @@ void main() {
+ {"keys":"down","command":null,"when":"picker"},
+ {"keys":"ctrl+j","command":"picker.previous","when":"picker"},
+ {"keys":"enter","command":null,"when":"picker"},
+- {"keys":"alt+enter","command":"picker.accept","when":"picker"},
+- {"keys":"cmd+i","command":null,"when":"picker"},
+- {"keys":"ctrl+i","command":"picker.preview","when":"picker"}
++ {"keys":"alt+enter","command":"picker.accept","when":"picker"}
+ ]}''');
+ final app = createApp();
+ app.machineStates['m']!.nodeOnline = true;
+@@ -135,6 +133,7 @@ void main() {
+ final pane = app.adoptSessionForTest(terminal('a0', frames));
+ final original = app.activeSwarmId;
+ app.newSwarm();
++ final addingTo = app.activeSwarmId;
+ await mount(tester, app, map);
+ final input = find.byKey(
+ ValueKey(
+@@ -158,16 +157,16 @@ void main() {
+ expect(search.cursor, (initial - 1) % search.rows.length);
+ await tester.enterText(input, 'Agent 0');
+ await tester.pump();
+- expect(find.byTooltip('Hide preview (⌃I)'), findsOneWidget);
+- await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+- expect(search.previewEnabled, isTrue);
+- await key(tester, LogicalKeyboardKey.keyI, ctrl: true);
+- expect(search.previewEnabled, isFalse);
++ expect(search.previewVisible, isTrue);
++ expect(
++ find.byKey(const ValueKey('swarm-search-preview-toggle')),
++ findsNothing,
++ );
+ await key(tester, LogicalKeyboardKey.enter);
+ expect(find.byType(SwarmSearchResults), findsOneWidget);
+ expect(frames, isEmpty);
+ await key(tester, LogicalKeyboardKey.enter, alt: true);
+- expect(app.activeSwarmId, original);
++ expect(app.activeSwarmId, inline ? addingTo : original);
+ expect(app.focusedPane, same(pane));
+ expect(find.byType(SwarmSearchResults), findsNothing);
+ await key(tester, LogicalKeyboardKey.arrowLeft);
+@@ -402,11 +401,6 @@ void main() {
+ 'Agent 0',
+ );
+ await tester.pump();
+- await native(tester, 'keymapCommand', {'command': 'picker.preview'});
+- await tester.pump();
+- expect(find.byKey(const ValueKey('swarm-search-preview')), findsNothing);
+- await native(tester, 'keymapCommand', {'command': 'picker.preview'});
+- await tester.pump();
+ expect(
+ find.byKey(const ValueKey('swarm-search-preview')),
+ findsOneWidget,
+diff --git a/desktop/test/swarm_inline_search_test.dart b/desktop/test/swarm_inline_search_test.dart
+index bef56a0..45d87a3 100644
+--- a/desktop/test/swarm_inline_search_test.dart
++++ b/desktop/test/swarm_inline_search_test.dart
+@@ -183,14 +183,15 @@ void main() {
+ );
+
+ testWidgets(
+- 'inline selection opens the existing agent and hands it the next key',
++ 'inline selection adds the existing agent here and hands it the next key',
+ (tester) async {
+ final app = createApp();
+ app.machineStates['m']!.nodeOnline = true;
+ final frames = <TerminalBinaryFrame>[];
+ final pane = app.adoptSessionForTest(terminal('a0', frames));
+- final original = app.activeSwarmId;
++ final original = app.activeSwarm;
+ app.newSwarm();
++ final destination = app.activeSwarmId;
+ await mount(tester, app);
+ await tester.tap(_input);
+ await tester.enterText(_input, 'Agent 0');
+@@ -198,7 +199,8 @@ void main() {
+ expect(frames, isEmpty);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+- expect(app.activeSwarmId, original);
++ expect(app.activeSwarmId, destination);
++ expect(original.panes.single, same(pane));
+ expect(app.panes.single, same(pane));
+ expect(_results, findsNothing);
+ expect(
+diff --git a/desktop/test/swarm_search_preview_test.dart b/desktop/test/swarm_search_preview_test.dart
+index 213fb64..8d2de27 100644
+--- a/desktop/test/swarm_search_preview_test.dart
++++ b/desktop/test/swarm_search_preview_test.dart
+@@ -28,7 +28,11 @@ void main() {
+ final before = terminal.buffer.getText();
+ final position = (terminal.buffer.cursorX, terminal.buffer.cursorY);
+ final snapshot = SearchOutputPreview.capture(terminal).text;
+- expect(snapshot.split('\n').length, SearchOutputPreview.shownLines);
++ expect(snapshot.split('\n\n').length, lessThanOrEqualTo(3));
++ expect(
++ snapshot.runes.length,
++ lessThanOrEqualTo(SearchOutputPreview.shownCharacters + 1),
++ );
+ expect(snapshot, contains('木' * 96));
+ expect(snapshot, isNot(contains('木' * 97)));
+ expect(snapshot, contains('Recent result 😀'));
+@@ -42,43 +46,38 @@ void main() {
+ },
+ );
+
+- test(
+- 'preview is lazy and cached for the selection, with explicit refresh',
+- () {
+- final app = createApp();
+- addTearDown(app.dispose);
+- final output = terminal('a0', []);
+- output.terminal.write('Original context');
+- final pane = app.adoptSessionForTest(output);
+- final search = SwarmSearchController(app, []);
+- addTearDown(search.dispose);
+- search.setQuery('Agent 0');
+- expect(search.preview, isNull);
+- search.togglePreview();
+- final first = search.preview;
+- expect(first!.text, contains('Original context'));
+- output.terminal.write('\r\nNew output');
+- for (final query in ['Agent', 'Agent 0', 'Test host Agent 0']) {
+- search.setQuery(query);
+- expect(search.preview, same(first));
+- }
+- search.togglePreview();
+- expect(search.preview, isNull);
+- search.togglePreview();
+- expect(search.preview!.text, contains('New output'));
+- expect(pane.session, same(output));
+- search.setQuery('Agent 1');
+- expect(search.preview!.text, isEmpty);
+- expect(app.allPanes, [pane]);
+- search.setQuery('>');
+- expect(search.previewVisible, isFalse);
+- expect(search.preview, isNull);
+- },
+- );
++ test('preview is always on and cached until selection changes', () {
++ final app = createApp();
++ addTearDown(app.dispose);
++ final output = terminal('a0', []);
++ output.terminal.write('Original context');
++ final pane = app.adoptSessionForTest(output);
++ final search = SwarmSearchController(app, []);
++ addTearDown(search.dispose);
++ search.setQuery('Agent 0');
++ expect(search.previewVisible, isTrue);
++ final first = search.preview;
++ expect(first!.text, contains('Original context'));
++ output.terminal.write('\r\nNew output');
++ for (final query in ['Agent', 'Agent 0', 'Test host Agent 0']) {
++ search.setQuery(query);
++ expect(search.preview, same(first));
++ }
++ search.setQuery('Agent 1');
++ search.setQuery('Agent 0');
++ expect(search.preview!.text, contains('New output'));
++ expect(pane.session, same(output));
++ search.setQuery('Agent 1');
++ expect(search.preview!.text, isEmpty);
++ expect(app.allPanes, [pane]);
++ search.setQuery('>');
++ expect(search.previewVisible, isFalse);
++ expect(search.preview, isNull);
++ });
+
+ for (final inline in [false, true]) {
+ testWidgets(
+- 'optional preview keeps ${inline ? 'New swarm' : 'titlebar'} input and go-to action',
++ 'always-on preview keeps ${inline ? 'New swarm' : 'titlebar'} input and go-to action',
+ (tester) async {
+ final app = createApp();
+ app.machineStates['m']!.nodeOnline = true;
+@@ -105,15 +104,11 @@ void main() {
+ find.byKey(const ValueKey('swarm-search-preview')),
+ findsOneWidget,
+ );
+- await chord(tester, LogicalKeyboardKey.keyI);
+- await tester.pump();
+ expect(
+- find.byKey(const ValueKey('swarm-search-preview')),
++ find.byKey(const ValueKey('swarm-search-preview-toggle')),
+ findsNothing,
+ );
+ final field = tester.widget<TextField>(input);
+- final controller = field.controller!;
+- final focus = field.focusNode!;
+ await chord(tester, LogicalKeyboardKey.keyI);
+ await tester.pump();
+ expect(
+@@ -121,41 +116,10 @@ void main() {
+ findsOneWidget,
+ );
+ expect(find.textContaining('One useful clue'), findsOneWidget);
+- expect(controller.text, 'Agent 0');
+- expect(focus.hasFocus, isTrue);
++ expect(field.controller!.text, 'Agent 0');
++ expect(field.focusNode!.hasFocus, isTrue);
+ expect(app.activeSwarm, same(target));
+ expect(frames, isEmpty);
+-
+- // Mouse toggling also keeps editing in the field that opened search.
+- await tester.tap(
+- find.byKey(const ValueKey('swarm-search-preview-toggle')),
+- );
+- await tester.pump();
+- expect(
+- find.byKey(const ValueKey('swarm-search-preview')),
+- findsNothing,
+- );
+- expect(focus.hasFocus, isTrue);
+- controller.value = const TextEditingValue(
+- text: 'Agent 0',
+- composing: TextRange(start: 0, end: 7),
+- );
+- await chord(tester, LogicalKeyboardKey.keyI);
+- await tester.pump();
+- expect(
+- find.byKey(const ValueKey('swarm-search-preview')),
+- findsNothing,
+- );
+- controller.value = const TextEditingValue(
+- text: 'Agent 0',
+- selection: TextSelection.collapsed(offset: 7),
+- );
+- await chord(tester, LogicalKeyboardKey.keyI);
+- await tester.pump();
+- expect(
+- find.byKey(const ValueKey('swarm-search-preview')),
+- findsOneWidget,
+- );
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(app.focusedPaneId, original.id);
+diff --git a/desktop/test/swarm_split_test.dart b/desktop/test/swarm_split_test.dart
+index 78bc232..681c43a 100644
+--- a/desktop/test/swarm_split_test.dart
++++ b/desktop/test/swarm_split_test.dart
+@@ -225,6 +225,10 @@ void main() {
+ await tester.pump();
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
++ expect(find.text('Split right'), findsOneWidget);
++ expect(find.byType(AlertDialog), findsNothing);
++ await tester.tap(find.byKey(const ValueKey('swarm-search-new-agent')));
++ await tester.pump();
+ expect(find.text('New agent to the right'), findsOneWidget);
+ expect(find.text('/work/checkout'), findsOneWidget);
+ expect(app.panes, [pane]);
+diff --git a/desktop/tool/keymap_native_checks.swift b/desktop/tool/keymap_native_checks.swift
+index befbcc2..d00434e 100644
+--- a/desktop/tool/keymap_native_checks.swift
++++ b/desktop/tool/keymap_native_checks.swift
+@@ -37,8 +37,8 @@ try checkKeymap(changed.match([stroke("down")], context: "picker").binding == ni
+ "Picker unbinding removes the original arrow action")
+ try checkKeymap(changed.match([stroke("ctrl+j")], context: "picker").binding?.command == "picker.previous",
+ "Picker remapping wins")
+-try checkKeymap(defaults.match([stroke("cmd+i")], context: "picker").binding?.command == "picker.preview",
+- "The shipped optional-preview shortcut joins the catalog")
++try checkKeymap(defaults.match([stroke("cmd+i")], context: "picker").binding == nil,
++ "Always-on preview does not consume a hide-preview shortcut")
+
+ let dispatcher = HarnessNativeKeyDispatch(changed)
+ let field = NSObject(), otherField = NSObject()
+diff --git a/desktop/tool/swarm_titlebar_checks.swift b/desktop/tool/swarm_titlebar_checks.swift
+index 73a5336..c820a8b 100644
+--- a/desktop/tool/swarm_titlebar_checks.swift
++++ b/desktop/tool/swarm_titlebar_checks.swift
+@@ -40,7 +40,7 @@ private extension SwarmTabStrip {
+ try checkTitlebar(palette == expected && searchButton.contentTintColor == expected.accent && notificationButton.contentTintColor == expected.accent &&
+ newButton.contentTintColor == expected.accent,
+ "Initial search and new-swarm colors use the saved palette")
+- try checkTitlebar(tabs.isEmpty && !actionsEnabled && !newButton.isEnabled && !newAgentButton.isEnabled && !searchButton.isEnabled && !notificationButton.isEnabled,
++ try checkTitlebar(tabs.isEmpty && !actionsEnabled && !newButton.isEnabled && !searchButton.isEnabled && !notificationButton.isEnabled,
+ "Initial palette setup does not create or enable workspace controls")
+ }
+
+@@ -125,14 +125,12 @@ private extension SwarmTabStrip {
+ try checkTitlebar(newButton.isEnabled, "New tab returns below capacity")
+ try checkTitlebar(searchButton.toolTip?.contains("⌘P") == true, "Search advertises its keyboard shortcut")
+ try checkTitlebar(newButton.frame.maxX + 12 <= searchButton.frame.minX, "New swarm leaves space before the search icon")
+- try checkTitlebar(searchButton.frame.maxX < newAgentButton.frame.minX && newAgentButton.frame.maxX < notificationButton.frame.minX, "Search, new agent and bell have separate targets in order")
+- try checkTitlebar(newAgentButton.title.isEmpty && newAgentButton.accessibilityLabel() == "New agent", "New agent uses an icon with an accessible label")
++ try checkTitlebar(searchButton.frame.maxX < notificationButton.frame.minX, "Search and bell have separate targets in order")
+ try checkTitlebar(!subviews.contains(where: { $0 is NSTextField }), "The titlebar has no competing text editor")
+ events.removeAll()
+ searchButton.performClick(nil)
+- newAgentButton.performClick(nil)
+ notificationButton.performClick(nil)
+- try checkTitlebar(events == ["jump", "newAgent", "notifications"], "Each toolbar icon opens its shared Flutter surface once")
++ try checkTitlebar(events == ["jump", "notifications"], "Each toolbar icon opens its shared Flutter surface once")
+ try checkTitlebar(notificationButton.hasAttention, "The bell represents pending agent attention")
+ let oldButton = searchButton
+ var themedState = state([["id": "swarm-0", "name": "Renamed tab"]], active: "swarm-0")
+@@ -150,10 +148,9 @@ private extension SwarmTabStrip {
+ events.removeAll()
+ update(state([["id": "swarm-0", "name": "Renamed tab"]], active: "swarm-0", enabled: false))
+ try original.checkEnabled(false)
+- try checkTitlebar(!newButton.isEnabled && !newAgentButton.isEnabled && !searchButton.isEnabled && !notificationButton.isEnabled, "Titlebar actions disable with a modal")
++ try checkTitlebar(!newButton.isEnabled && !searchButton.isEnabled && !notificationButton.isEnabled, "Titlebar actions disable with a modal")
+ original.clickBothActions()
+ newButton.performClick(nil)
+- newAgentButton.performClick(nil)
+ searchButton.performClick(nil)
+ notificationButton.performClick(nil)
+ try checkTitlebar(events.isEmpty, "Disabled controls emit no actions")
+@@ -222,7 +219,7 @@ private extension SwarmTabStrip {
+ messenger.finishNextReply()
+ try checkTitlebar(window.firstResponder === window.contentViewController,
+ "The latest acknowledged tab action restores content focus")
+- for (button, method) in [(newAgentButton, "newAgent"), (notificationButton, "notifications")] {
++ for (button, method) in [(notificationButton, "notifications")] {
+ window.makeFirstResponder(button)
+ let before = messenger.calls.count
+ button.performClick(nil)
+@@ -232,7 +229,7 @@ private extension SwarmTabStrip {
+ "The toolbar waits for Flutter's destination focus tree")
+ messenger.finishNextReply()
+ try checkTitlebar(window.firstResponder === window.contentViewController,
+- "New-agent and notification controls return keyboard ownership to Flutter")
++ "Notification control returns keyboard ownership to Flutter")
+ }
+ messenger.holdReplies = false
+ }
+@@ -445,7 +442,7 @@ private extension SwarmTitlebar {
+ try strip.checkStartupPalette(startupPalette)
+ try checkTitlebar(window.firstResponder === window.contentViewController,
+ "Adding toolbar buttons does not take initial keyboard focus from the workspace")
+- try checkTitlebar(main.items.map(\.title) == ["Harness", "Swarm", "Agent", "Edit", "View", "History", "Models", "Window", "Help"], "Swarm and Agent replace File without duplicate menus")
++ try checkTitlebar(main.items.map(\.title) == ["Harness", "Swarm", "Agent", "Models", "History", "Edit", "View", "Window", "Help"], "Swarm and Agent replace File without duplicate menus")
+ let settings = appItem.submenu!.items[0]
+ try checkTitlebar(settings.title == "Settings…" && settings.representedObject as? String == "settings", "Settings stays in the application menu")
+ let swarm = main.item(withTitle: "Swarm")!.submenu!
diff --git a/docs/handoff/app-v2-2026-09-13/swarm_add_agent_test.dart.txt b/docs/handoff/app-v2-2026-09-13/swarm_add_agent_test.dart.txt
new file mode 100644
index 000000000..ea885d4a7
--- /dev/null
+++ b/docs/handoff/app-v2-2026-09-13/swarm_add_agent_test.dart.txt
@@ -0,0 +1,108 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/state/pane_arrangement.dart';
+import 'package:harness/state/swarm_navigation.dart';
+import 'package:harness/state/swarm_search.dart';
+import 'package:harness/terminal/terminal_binary.dart';
+import 'package:xterm/xterm.dart';
+
+import 'swarm_interactions_test.dart' show chord;
+import 'swarm_screen_test.dart' show mount, terminal;
+import 'swarm_state_test.dart' show createApp;
+
+void main() {
+ testWidgets('floating Add agent keeps the destination and reuses the chosen session', (tester) async {
+ final app = createApp();
+ final input = <TerminalBinaryFrame>[];
+ final shared = app.adoptSessionForTest(terminal('a0', input));
+ final source = app.activeSwarm;
+ app.newSwarm(name: 'Review');
+ final existing = app.adoptSessionForTest(terminal('a1', input));
+ final target = app.activeSwarm;
+ await mount(tester, app);
+ tester.view.physicalSize = const Size(880, 560);
+ await tester.pump();
+ final add = find.byKey(const ValueKey('swarm-add-agent-button'));
+ expect(tester.getRect(add).left, greaterThan(780));
+ expect(tester.getRect(add).top, greaterThan(tester.getRect(find.byKey(existing.cellKey)).bottom));
+ await tester.tap(add);
+ await tester.pump();
+ await tester.enterText(find.byKey(const ValueKey('swarm-search-input')), 'Agent 0');
+ await tester.pump();
+ expect(find.text('Add to this swarm'), findsOneWidget);
+ expect(find.text('Go to agent'), findsNothing);
+ expect(find.byType(AlertDialog), findsNothing);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(app.activeSwarm, same(target));
+ expect(target.panes, [existing, shared]);
+ expect(source.panes, [shared]);
+ expect(input, isEmpty);
+ expect(tester.takeException(), isNull);
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ });
+
+ for (final axis in PaneResizeAxis.values) {
+ testWidgets('split ${axis.name} chooses an existing agent and preserves its neighbors', (tester) async {
+ final app = createApp();
+ final input = <TerminalBinaryFrame>[];
+ final first = app.adoptSessionForTest(terminal('a0', input));
+ final neighbor = app.adoptSessionForTest(terminal('a1', input));
+ final target = app.activeSwarm;
+ app.newSwarm(name: 'Elsewhere');
+ final shared = app.adoptSessionForTest(terminal('a2', input));
+ final source = app.activeSwarm;
+ app.selectSwarm(target.id);
+ app.focusPane(first.id);
+ await mount(tester, app);
+ tester.view.physicalSize = const Size(3000, 1800);
+ await tester.pump();
+ final neighborRect = tester.getRect(find.byKey(neighbor.cellKey));
+ final expected = app.preparePaneSplit(axis)!;
+ await chord(tester, LogicalKeyboardKey.keyP);
+ final inputField = find.byKey(const ValueKey('swarm-search-input'));
+ await tester.enterText(inputField, axis == PaneResizeAxis.x ? '> split right' : '> split down');
+ await tester.pump();
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(find.byType(AlertDialog), findsNothing);
+ expect(app.panes, [first, neighbor]);
+ await tester.enterText(inputField, 'Agent 2');
+ await tester.pump();
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(app.panes, [first, shared, neighbor]);
+ expect(source.panes, [shared]);
+ expect(app.activeSwarm.manualLayout!.tiles, expected.after.tiles);
+ expect(tester.getRect(find.byKey(neighbor.cellKey)), neighborRect);
+ expect(input, isEmpty);
+ expect(find.byType(TerminalView), findsNWidgets(3));
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ });
+ }
+
+ test('adding a group uses this swarm, skips duplicates and keeps the source', () async {
+ final app = createApp();
+ addTearDown(app.dispose);
+ app.adoptSessionForTest(terminal('a0', []));
+ app.adoptSessionForTest(terminal('a1', []));
+ final source = app.activeSwarm;
+ app.renameSwarm(source.id, 'Release');
+ app.newSwarm(name: 'Review');
+ final target = app.activeSwarm;
+ await app.addAgentToSwarm('m', 'a0');
+ final search = SwarmSearchController(app, [], adding: true);
+ addTearDown(search.dispose);
+ final row = search.rows.singleWhere((row) => row.id == swarmDestinationId(source.id));
+ final choice = search.submit(row)!;
+ expect(choice.action, SwarmSearchAction.addHere);
+ expect(await activateSwarmSearchSelection(app, choice, destinationSwarmId: target.id), isTrue);
+ expect(app.activeSwarm, same(target));
+ expect(target.panes, source.panes);
+ expect(target.name, 'Review');
+ expect(search.canAdd(row), isFalse);
+ });
+}
diff --git a/docs/harness-collaboration-design.md b/docs/harness-collaboration-design.md
new file mode 100644
index 000000000..5e7844bfd
--- /dev/null
+++ b/docs/harness-collaboration-design.md
@@ -0,0 +1,254 @@
+# Shared swarms in Harness
+
+Harness should make a swarm a shared place to work with a small group of persistent agents. A teammate opens a link, understands the work, and contributes. **One shared swarm has one shared state:** everyone sees the same agent panes, arrangement, content, and changes.
+
+The proposed product contract has five rules:
+
+1. **Share a swarm.** One invitation gives someone access to the work gathered there.
+2. **Watch or work.** Reviewers can read and comment. Collaborators can operate and contribute agents.
+3. **Work in parallel.** Several people can operate different agents. Each agent has one person controlling input at a time.
+4. **Edit the same swarm.** Adding, closing, moving, resizing, renaming, or maximizing a pane changes the shared arrangement for everyone.
+5. **Leave useful context.** Shared notes, comments, and results remain available when teammates return.
+
+This is a design for trusted engineering teams, informed by the repository and official documentation reviewed on September 13, 2026. The shared arrangement is the chosen direction. Multi-user swarms, browser invitations, and durable shared discussion still require implementation; they are not claims about the current app. Product documentation establishes the comparison platforms' behavior; the remaining recommendations should be validated with developers.
+
+## Lessons from the five collaboration models
+
+| Platform | Observed model | Recommendation for Harness |
+| --- | --- | --- |
+| **Figma** | A link opens a shared file. File permissions distinguish viewing, which includes commenting and following, from editing. Access permissions and product seats are separate. [Figma sharing](https://help.figma.com/hc/en-us/articles/1500007609322-Guide-to-sharing-and-permissions) | Make the swarm the object someone shares. Synchronize edits to its contents and arrangement, show who is present, and make the invitation's capabilities and cost understandable together. |
+| **Google Docs** | Viewer, Commenter, and Editor are distinct roles. Suggestions allow a contribution to be considered before changing the document; version history identifies changes and supports restoration. [Sharing](https://support.google.com/drive/answer/2494822?hl=en), [suggestions](https://support.google.com/docs/answer/6033474?hl=en-8), [history](https://support.google.com/docs/answer/190843?hl=en) | Let someone contribute feedback without operating an agent. Attribute human actions. Preserve the distinction between a suggestion, an instruction, and an executed action. |
+| **GitHub** | Pull requests gather discussion, commits, checks, and diffs around a proposed change. Repository roles distinguish contributing from administering access. [Pull requests](https://docs.github.com/en/pull-requests/reference/pull-requests), [repository roles](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) | Give teammates evidence they can inspect independently. Keep routine contribution easy and membership administration explicit. Link to the team's existing code review process. |
+| **Notion** | Guests can be invited to a specific page. Editing can be granted without permission to reshare it. Comments attach to a page or particular content and can be resolved and reopened. [Sharing](https://www.notion.com/help/sharing-and-permissions), [comments](https://www.notion.com/help/comments-mentions-and-reminders) | Make a swarm understandable to someone arriving later. Keep its purpose and discussion with the work. Inviting someone to one swarm should not require adding them to an entire company workspace. |
+| **Slack** | Channels organize conversation by purpose. Public channels are discoverable within a workspace; private channels require membership. Threads contain focused discussion, with notifications normally following participation or mentions. [Channels](https://slack.com/help/articles/360017938993-What-is-a-channel), [threads](https://slack.com/help/articles/115000769927-Use-threads-to-organize-discussions) | Give a swarm a clear purpose and durable discussion. Direct attention to a relevant question or reply. Begin with explicit invitations; broader team discovery can follow later. |
+
+The common pattern is a stable place, an understandable audience, a useful way to contribute, and enough retained context to return. Presence makes live work easier. The shared object and its history make collaboration useful when nobody else is there. That synthesis is a design judgment, not a claim that these features alone caused the platforms' commercial success.
+
+Their complexity also offers lessons. Figma separates seats from permissions; Notion supports inherited permissions and respects the broadest applicable grant; GitHub has five standard repository roles. Those mechanisms serve large organizations, but Harness's initial invitation does not need to expose a comparable hierarchy. Start with one swarm audience and two contribution levels.
+
+There is direct competitive overlap to acknowledge. Slack now documents **Slack Code**, which is rolling out gradually: temporary code channels let teammates prompt supported agents, pause a response, and discuss generated artifacts. Multiplayer agent work already extends beyond conventional chat. Harness's proposed differentiation is direct access to persistent sessions across real environments, with several engines and a clear human handoff. Whether teams value that enough to adopt another product needs testing. [Slack Code](https://slack.com/help/articles/54310833022355-Build-with-AI-as-a-team-using-Slack-Code)
+
+## The unit of sharing
+
+A swarm contains its name, an optional short purpose, agent panes in a shared arrangement, and discussion. A link opens that swarm in its current state. It does not require a new project, a task board, a lead agent, or an organization setup flow.
+
+An agent remains a real session with its original machine, environment, and model account. Adding it to a swarm does not copy its process, migrate its files, merge its context with other agents, or make the agents coordinate automatically. This extends the existing product thesis and the current separation between a swarm arrangement and a running session. [R1](../../harness-new-ui/research/harness-browser-thesis.md), [R2](../desktop/lib/state/swarm.dart)
+
+| Shared state | What everyone sees |
+| --- | --- |
+| Swarm name and purpose | The same title and description |
+| Agent panes | The same agents in the swarm; additions and removals update everyone's swarm |
+| Pane arrangement | The same order, sizes, positions, and maximized pane |
+| Agent content | The same submitted instructions and available output |
+| Comments, saved excerpts, and links | The same discussion, results, and resolved state |
+| Membership and control | The same participants, roles, and current controller for each agent |
+
+When Alice sends a prompt to Agent A, everyone in the swarm sees that submitted prompt and the same live execution in Agent A's pane. For example, Alice submits “Fix the login bug and run the tests”; Sam sees her instruction, the agent's reported work as it happens, and its results. Structured prompts identify Alice as the sender. The original host executes the accepted instruction once and distributes that session's output and activity to all participants. Joining or receiving those updates must never start another execution.
+
+Adding an agent adds its pane to everyone's swarm immediately. Moving or resizing it updates everyone's arrangement. Closing it removes it from everyone's swarm, with Undo, while its underlying process continues. A new participant and a returning participant both receive the current shared state. There is no separate per-person pane list or hidden roster to manage.
+
+Keyboard focus, text selection, scrolling, and unsent composer drafts remain local interaction state, as in a collaborative editor. Once input is sent to the session, its resulting terminal echo and activity are shared. Closing an application window or leaving the swarm also remains a local action. These do not create a separate copy of the swarm's content or arrangement.
+
+After an agent is shared, interactions with that same session remain visible to its authorized observers wherever its contributor operates it, including from a private swarm.
+
+For the first multiplayer release, give each live agent **one shared swarm**. It may still appear in several personal swarms as it does today. This deliberate initial limit keeps the controlling audience understandable and avoids one room's discussion silently affecting another room's live agent. An attempted second share should offer to open the existing shared swarm or create a separate agent. Broader sharing can be reconsidered when there is demonstrated demand and an understandable account of overlapping access.
+
+## The invitation and Alice's first minute
+
+The Share dialog asks for a person and one role:
+
+| Role in Share | Short explanation |
+| --- | --- |
+| **Can work** | Use agents, edit the shared swarm, and comment. |
+| **Can review** | Watch shared agents and comment. |
+
+Default to **Can work** for a named teammate invitation in this trusted-team product. Keep the explanation visible before the owner sends it. The swarm creator is its owner and manages people, roles, ownership transfer, and archival; Owner is not another everyday invitation choice.
+
+Start with **Only invited people**. Copying a normal swarm link does not grant access. An invited person can accept; another person can request access. Acceptance establishes a named identity, without a requirement to create a team, enter payment details, configure a model provider, or connect a computer.
+
+The intended join experience works in a browser. Alice can inspect output, comment, and operate an already shared agent there. Opening in the native app is optional. Connecting her own computer is needed only when she wants to contribute an agent from it. This browser experience requires development beyond the current desktop onboarding and must be included in the estimate, rather than promised as an existing path.
+
+A concrete first visit:
+
+1. The owner shares **Release** with Alice as **Can work**.
+2. Alice opens the invitation and signs in. She lands in Release, with its purpose, shared agents, and the latest shared note available. The note might say: “Retry fix is ready; please check the regression,” with a pull request link.
+3. Alice inspects the test agent's pane in the same arrangement Sam sees. A small label says **Sam is controlling** if Sam is operating it. Watching sends no agent input.
+4. She comments on the relevant test excerpt, takes control of an available agent, or requests Sam's control. Sam can continue on another agent while Alice works.
+5. If she wants a separate implementation approach, she adds an agent from her own connected environment. Its pane appears in everyone's swarm without a new invitation. If she moves or resizes it, everyone sees that change.
+6. Before leaving, she posts the result or next question in a comment. The next visitor can find that context alongside the agent and its output.
+
+The swarm owner should not need to be present for an already invited teammate to join. Live interaction still requires the agent's host to be available. Shared notes and saved excerpts should remain readable independently of that host.
+
+## What Alice can do
+
+| Action | Can review | Can work |
+| --- | --- | --- |
+| Watch available output and read shared context | Yes | Yes |
+| Comment, mention a teammate, and reply | Yes | Yes |
+| Scroll, select text, or leave the swarm | Yes | Yes |
+| Move, resize, or maximize a pane in the shared layout | No | Yes; the change applies to everyone |
+| Send instructions, answer an agent's question, or use its terminal | No | Yes, while controlling that agent |
+| Interrupt or end the running agent | No | Yes, while controlling it; ending a session is explicit |
+| Add an existing agent she is entitled to share | No | Yes |
+| Create an agent on her own connected machine | No | Yes |
+| Close an agent pane | No | Yes; removed for everyone, and the process continues |
+| Change the swarm name, purpose, or shared links | No | Yes |
+| Invite or remove people, change roles, transfer ownership, archive the swarm | No | Owner only |
+
+This intentionally removes per-person, per-agent role settings from the everyday experience. A contributor shares an agent with the swarm's audience: reviewers can observe it and collaborators can operate it. The contributor authorizes that scope when sharing the agent, including future members admitted by the swarm owner. A contributor can withdraw their own agent at any time.
+
+Starting a fresh agent through Harness on somebody else's computer is outside the initial invitation. A contributor starts it there and shares it, or Alice uses her own connected machine. A future team runtime could make creation a team capability with an explicit payer, but it should not create another permissions panel in the first release.
+
+**Operating an agent is a real delegation of its capabilities.** A collaborator who can use its shell or tools may read files, spend model credits, alter code, or end processes using that environment's existing privileges. Hiding a launch, delete, or billing button does not establish isolation from commands executed inside the session. Microsoft documents the same fundamental issue for Live Share's writable terminals, although its terminals allow simultaneous writers. Harness's single-controller rule is a coordination choice, not a security sandbox. [Live Share security](https://learn.microsoft.com/en-us/visualstudio/liveshare/reference/security)
+
+The contributor retains authority over the host and can stop sharing or stop the runtime. The swarm owner controls membership. Those responsibilities should appear where they matter, such as the Share dialog and agent details, without requiring people to configure a second role system.
+
+## Input and handoffs
+
+Most parallel work should happen on different agents. When people work with the same agent, use a visible, exclusive right to send input. The agent can continue running between human interactions.
+
+| Agent input state | What Alice sees | What an action does |
+| --- | --- | --- |
+| Nobody is controlling | **Take control** | Acquires control if it is still available; then enables input. |
+| Sam is controlling | **Sam is controlling · Request control** | Sends Sam a handoff request; Alice remains able to watch and comment. |
+| Alice is controlling | **You're controlling · Release** | Lets Alice type, paste, answer, or interrupt. Release ends her input control. |
+| Connection is lost | **Disconnected** with retained output | Disables input. Drafts remain personal until a fresh connection and deliberate send. |
+
+Opening, focusing, joining, following, or reconnecting must never displace another controller. Requests do not forcibly seize control. A controller can hand over or release; the host owner has an explicit recovery action. If a controller disappears, its host-enforced lease expires, after which another authorized collaborator can claim control. A timeout is never permission to replay queued instructions.
+
+Control is attached to the actual agent runtime across every swarm and client. A role downgrade or revocation invalidates that person's input authority. Every agent-execution route must obey the same rule, including terminal input, uploads, question responses, interrupts, and runtime actions. Shared layout edits require the swarm's edit permission; they do not require taking over an agent's input. Permission checks only in the visible terminal widget would be insufficient.
+
+Store one canonical terminal size per shared pane. Resizing that pane is a shared layout edit, and the host applies its resulting terminal dimensions once. An accepted shared resize affects the person currently typing as well as observers. Merely joining from a smaller display or resizing an application window must not produce competing terminal resize requests. Each client renders the same logical layout within its available display; scrolling retained output and selecting text remain local.
+
+Record who held control and who performed explicit Harness actions. For structured prompts, record the sender with the submitted instruction. For raw terminal input, the reliable evidence is the authenticated controller and accepted input sequence; do not invent semantic task authorship or change Git commit identity behind the developer's back.
+
+Figma's engineering account describes conflict resolution and multiplayer undo over document state. That is useful background for shared swarm state, but arbitrary agent instructions can cause external effects that cannot be merged or undone as document edits. Harness should serialize control of those effects and use ordinary versioned updates for the shared arrangement. It does not need collaborative character editing of prompt drafts to validate this product. [Figma multiplayer engineering](https://www.figma.com/blog/how-figmas-multiplayer-technology-works/)
+
+Apply layout changes to stable pane identities. Concurrent changes to different panes should both survive; conflicting changes to the same property follow the authoritative accepted order. A stale move or resize cannot recreate a closed pane. Undo reverses an attributable arrangement edit without rewinding everyone else's work. Reconnection loads the latest shared state instead of restoring an old per-person layout over it.
+
+## Closing, removing, and stopping
+
+These actions need distinct names and behavior:
+
+| Action | Effect |
+| --- | --- |
+| **Close pane** — the pane's × action | Removes the pane and its agent from the shared swarm for everyone. Its process remains on the host. |
+| **Close swarm tab** | Leaves the swarm in this person's app. Membership and the shared arrangement remain. |
+| **Stop sharing** — available to the agent contributor | Withdraws that agent's grant to the swarm. Other members cannot undo the contributor's decision. |
+| **End session** — explicit runtime action | Ends the agent process; requires control and confirmation. Saved discussion remains. |
+
+A normal pane close should offer Undo while the original contributor's grant remains valid. Confirm a close that would displace another active controller, and name that person. Undo cannot restore withdrawn access, revive a terminated process, or reverse commands already run. The pane close control should say **Remove from swarm for everyone** in its accessible label or tooltip; reviewers cannot invoke it. There is no separate **Hide for me** action.
+
+Removing an agent or stopping its live sharing leaves comments and excerpts already posted to the swarm in its shared record. Make that distinction visible in the action's explanation.
+
+Removing a person revokes their swarm access, including open streams and future encrypted content. Their previously shared comments remain attributed. Agents they personally contributed should be withdrawn as part of removal, leaving the original processes intact; the membership dialog must show that consequence. Team-owned runtimes can provide continuity beyond any one person's membership in a later phase.
+
+Archiving a swarm preserves its discussion and saved excerpts for authorized members, and ends its live agent grants. It does not terminate agents. Reopening an archive does not silently restore withdrawn grants; contributors must share those agents again. Ownership transfer changes swarm administration, not the ownership of contributed computers or model accounts. The owner must transfer or archive before leaving.
+
+## Context that survives the meeting
+
+Begin with an optional one-sentence purpose and a small comments surface available on demand. A comment can refer to the swarm, a specific agent, a selected output excerpt, or a link such as a pull request. Mentions and replies make it useful both during a session and the next morning.
+
+An output comment must retain an immutable excerpt with its agent identity and time. A terminal screen coordinate is an unreliable anchor because the screen is overwritten and rewrapped. If more source history remains available, the comment can also lead back to it. Clearly label a saved excerpt versus live output.
+
+On return, offer the latest shared note, unread mentions and replies, and unresolved discussion. Agent states should report verified facts such as a pending question or unavailable host. An agent saying it finished does not establish that its change passed review. Automatic summaries and a comprehensive replay of all activity can wait until the basic context is useful and dependable.
+
+Keep human discussion separate from agent input. A comment is not automatically sent to an agent. A collaborator who wants to use a comment as an instruction explicitly sends it while controlling that agent. Resolving a thread marks the discussion resolved; it neither approves a tool action nor merges code.
+
+Use GitHub links for detailed review, checks, and merge decisions. Harness membership does not itself issue repository permissions. An operated agent still acts using its environment's credentials, which may be more powerful than Alice's personal GitHub account; the UI must not suggest otherwise. The team's repository rules and credential setup remain relevant.
+
+Notifications should begin with mentions, replies to participated threads, and direct handoff requests. Other agent activity stays available in the swarm and existing attention/search surfaces. Do not add a second company chat, a mandatory activity dashboard, or notifications for every generated line.
+
+## Sharing an existing private agent
+
+Sharing a live agent is different from sharing a screenshot of it. Before the contributor publishes it, show the destination swarm, its current audience, the agent's host, and what output will become available. Explain that collaborators can use the agent's existing capabilities and model account.
+
+Do not offer a misleading guarantee that sharing “from now on” hides earlier context. The current terminal screen, retained output, model conversation, files, and future agent responses can expose earlier work. For a clean collaboration boundary, offer **Start a new shared agent** with deliberately selected context. A saved excerpt is the smaller option when only feedback is needed.
+
+The runtime's original account continues to fund model usage. If the payer cannot be verified, say so rather than guessing. Granting a collaborator access does not copy model API keys into their app or create an independent model subscription, but commands executed in the shared environment still have that environment's privileges.
+
+## What the current repository supports
+
+The current `Swarm` model already separates membership from process ownership and reuses a session across views. Its serialized state includes membership, focus, zoom, and layout. Multiplayer should synchronize agent membership and the durable arrangement, including pane order, dimensions, and maximized state, as one authoritative swarm document. Keep only transient interaction state such as keyboard focus and scrolling local. Do not introduce separate participant layouts or hidden pane memberships. [R2](../desktop/lib/state/swarm.dart)
+
+The terminal stream manager currently closes an incumbent stream when a later client opens the same terminal, then assigns the controller. This supports the current single-user arrangement but is not a many-observer collaboration protocol. The desktop terminal state also assumes a controlling connection. The next foundation is independent read subscriptions plus explicit, host-enforced input control. [R3](../cli/src/lib/terminalStreamManager.ts#L276), [R4](../desktop/lib/terminal/terminal_session.dart)
+
+Machine listing is currently scoped to a user, and fetching a machine's owner data is restricted to its owner or an administrator. A swarm invitation must introduce a scoped collaborator path; it must not return the machine owner's API key or reuse an unrestricted machine link. Harness's listing and metadata APIs should expose only the agents and details granted to that collaborator. This API boundary does not restrict what a writable session can discover through its own tools. [R5](../backend/src/services/MachineService.ts#L490)
+
+The desktop uses the local CLI for normal authentication and machine transport. Relayed terminal control is pairwise end-to-end encrypted. Browser participation and encrypted shared history require a deliberate identity and key-distribution design, including invitation acceptance while the owner is absent, host enforcement, and revocation. Do not weaken the existing relay confidentiality to implement comments or summaries. [R6](../desktop/CLAUDE.md#L88), [R7](../cli/src/lib/e2ee/core.ts#L379)
+
+The app's current browsing history is bounded, session-local navigation history; it does not establish a durable team record. Shared metadata, comments, and selected excerpts need their own persistence and retention contract. While a host is offline, the browser should show saved shared context and clearly stale output, rather than imply that an agent is live or has migrated elsewhere. [R8](harness-v2-progress.md)
+
+The implementation can remain conceptually small: one shared swarm document, memberships, scoped agent grants, persistent comments/excerpts, and transient control leases. Authorization and encryption still need careful implementation. Revocation governs future access; it cannot remove information a former participant has already received or copied. Changing read keys alone also cannot enforce a reviewer's lack of write permission: the host must verify the authenticated sender and current grant on every action.
+
+## A complete first pilot
+
+Build one end-to-end journey: an invited Alice can join in a browser, see the same swarm as Sam, understand a shared agent, leave a useful comment, edit the arrangement, operate an agent through an explicit handoff, and return later to the current shared work. The native app preserves its fast navigation while adopting the shared arrangement for shared swarms.
+
+The pilot needs invitation and revocation, the two roles, quiet presence, observer streams, input handoff, contribution of an agent from an already connected host, synchronized pane edits with Undo, and durable comments with selected excerpts. Implement the stream and authorization foundation first, then exercise the full journey. A desktop-only internal experiment can validate control sooner, but it does not validate the intended low-friction browser invitation.
+
+Leave shared cloud compute, creation on other people's hosts, cross-swarm live sharing, public discovery, co-editing drafts, automatic agent coordination, audio/video, and custom permission roles for later. Those are independent product bets and are unnecessary to learn whether developers want to work this way.
+
+Try the complete experience with a few real engineering pairs on real tasks. The central product test is whether Alice can make a useful contribution without the owner explaining the interface or reconstructing the context in Slack. Observe her understanding of where commands execute, who pays, what closing does, and whether a comment will reach an agent. These are proposed tests, not measured outcomes.
+
+Before expanding the pilot, verify the cases where apparently simple collaboration can fail:
+
+| Scenario | Required behavior |
+| --- | --- |
+| Alice joins while Sam types | Sam's control and terminal geometry remain unchanged. |
+| Alice submits a prompt to Agent A | Everyone sees her submitted prompt and the same agent output and reported actions; the host accepts a single execution. |
+| Another participant joins while Agent A is working | They observe the existing execution; joining never resubmits its prompt. |
+| Two people claim control together | Only one receives a valid input lease. |
+| Two participants operate different agents | Their input remains independent; shared arrangement edits still synchronize. |
+| Alice adds, moves, resizes, renames, or maximizes a pane | Everyone receives the same change and resulting layout. |
+| Two people edit different panes at once | Both accepted changes survive. |
+| A stale layout update arrives after a pane was closed | The pane stays removed; only a valid explicit Undo or add can restore it. |
+| An old connection reconnects after handoff | It resumes observing; stale input cannot reach the runtime. |
+| A reviewer attempts input, upload, or a shared layout edit directly | The authoritative handler rejects it, regardless of what the UI displays. |
+| A controlling person's role is downgraded or revoked | Future input is rejected across all routes and clients. |
+| The same agent is open in multiple personal swarms | All views agree on the real controller. |
+| Alice closes an agent pane | It disappears from everyone's swarm; the agent process continues. |
+| Alice undoes a valid pane close | The pane returns to the shared arrangement for everyone. |
+| Alice closes her swarm tab or application window | The shared arrangement, membership, and agent execution continue. |
+| Alice returns after others changed the swarm | She receives the current shared arrangement, including additions and removals. |
+| A contributor withdraws an agent | Its live grant ends; ordinary Undo cannot restore it. |
+| The owner is absent or an agent host is offline | Invitations and saved context behave as promised; live availability is honest. |
+| A comment's source terminal has scrolled away | Its saved excerpt and attribution remain understandable. |
+| An input acknowledgement is lost | No blind retry or duplicate execution; show uncertainty when delivery cannot be established. |
+
+A successful pilot should demonstrate independent contribution, understandable permissions, dependable handoffs, and useful return visits. Shared presence alone would not validate the product.
+
+## Commercial implication
+
+Keep review and invitation acceptance free of a payment step. Charge the sponsoring team for people who regularly work in shared swarms, with one seat covering that team's swarms. Show the owner any seat cost before activating a paid collaborator; do not silently convert a guest or viewer into a billable seat. Treat any introductory free collaboration allowance and the exact price as experiments. Model usage remains a separate, clearly identified expense until Harness actually supplies the compute.
+
+The recurring value to test is that teammates can understand, contribute to, and resume agent work with less coordination overhead. That is a stronger basis for a team subscription than charging for each invitation or each agent visible on screen.
+
+## Sources
+
+Official help pages are living documents, accessed September 13, 2026; publication dates are not asserted where the publisher does not provide one. The 2019 Figma engineering article is used for its documented design reasoning, not as a claim about its entire current implementation. The comparison is a product-design study, not an exhaustive enterprise permissions or pricing audit.
+
+1. Figma. [Guide to sharing and permissions](https://help.figma.com/hc/en-us/articles/1500007609322-Guide-to-sharing-and-permissions). Sharing scope, viewing/editing, permission inheritance, and seats.
+2. Google. [Share files from Google Drive](https://support.google.com/drive/answer/2494822?hl=en). Roles and restricted/link access.
+3. Google. [Suggest edits in Google Docs](https://support.google.com/docs/answer/6033474?hl=en-8). Suggestions and review before applying changes.
+4. Google. [Find what's changed in a file](https://support.google.com/docs/answer/190843?hl=en). Attribution and version history.
+5. GitHub. [Pull requests](https://docs.github.com/en/pull-requests/reference/pull-requests). Review context and independent development models.
+6. GitHub. [Repository roles for an organization](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). Contribution and administration privileges.
+7. Notion. [Sharing & permissions](https://www.notion.com/help/sharing-and-permissions). Page guests, resharing, inheritance, and overlapping grants.
+8. Notion. [Comments, mentions & reactions](https://www.notion.com/help/comments-mentions-and-reminders). Durable discussion anchored to content.
+9. Slack. [What is a channel?](https://slack.com/help/articles/360017938993-What-is-a-channel). Purpose, discovery, membership, and discussion.
+10. Slack. [Use threads to organize discussions](https://slack.com/help/articles/115000769927-Use-threads-to-organize-discussions). Thread participation and notification behavior.
+11. Slack. [Build with AI as a team using Slack Code](https://slack.com/help/articles/54310833022355-Build-with-AI-as-a-team-using-Slack-Code). Gradual rollout of team agent channels and artifact collaboration.
+12. Microsoft. [Security — Live Share](https://learn.microsoft.com/en-us/visualstudio/liveshare/reference/security), section “Sharing a terminal.” Writable terminal capabilities and host responsibility.
+13. Evan Wallace, Figma. [How Figma's multiplayer technology works](https://www.figma.com/blog/how-figmas-multiplayer-technology-works/), October 16, 2019. Document synchronization and undo.
+
+Repository evidence reflects the working files inspected on September 13, 2026:
+
+- **R1:** Companion checkout, [Harness browser thesis](../../harness-new-ui/research/harness-browser-thesis.md). Persistent agents, arbitrary personal swarms, real environments, and explicit coordination. The relative link assumes the companion checkout is a sibling of this repository.
+- **R2:** [Swarm state](../desktop/lib/state/swarm.dart). Membership, view state, and session reuse.
+- **R3:** [Terminal stream manager](../cli/src/lib/terminalStreamManager.ts#L276). Open-time takeover and control ownership.
+- **R4:** [Desktop terminal session](../desktop/lib/terminal/terminal_session.dart). Terminal connection and input state.
+- **R5:** [Machine service](../backend/src/services/MachineService.ts#L490). Owner-scoped machine access.
+- **R6:** [Desktop architecture](../desktop/CLAUDE.md#L88). CLI-owned authentication and transport.
+- **R7:** [E2EE core](../cli/src/lib/e2ee/core.ts#L379). Encrypted terminal control routes.
+- **R8:** [V2 development handoff](harness-v2-progress.md). Current navigation, session-local history, and verification limits.
diff --git a/docs/harness-v2-appearance-onboarding.md b/docs/harness-v2-appearance-onboarding.md
index e3be68c5d..e04b13a9e 100644
--- a/docs/harness-v2-appearance-onboarding.md
+++ b/docs/harness-v2-appearance-onboarding.md
@@ -1,5 +1,7 @@
# Appearance and first use
+For the current goal, approved Navigate/Add separation, first-use plan, and acceptance criteria, start with [the continuation handoff](harness-v2-handoff.md). The earlier onboarding implementation below did not resolve the user's first-impression concerns. A further welcome draft is preserved in the handoff archive but remains unverified and unapplied.
+
Research and implementation notes, 2026-09-13. The product decisions below are Harness adaptations, not claims that the referenced tools endorse them.
## Palette selection
diff --git a/docs/harness-v2-handoff.md b/docs/harness-v2-handoff.md
new file mode 100644
index 000000000..44516c1c7
--- /dev/null
+++ b/docs/harness-v2-handoff.md
@@ -0,0 +1,363 @@
+# Harness v2: goal, plan, and continuation handoff
+
+Updated September 13, 2026. **Read this first when resuming on another computer.**
+This is the current product contract and next-work order. It supersedes conflicting
+historical checkpoints in [the progress log](harness-v2-progress.md). The user
+requested this checkpoint so another agent/session can take over; the overall
+goal is still active and unfinished.
+
+## Goal
+
+Build the best everyday workspace for people directing persistent AI agents:
+a fast, polished, keyboard-first **agentic browser**, with each tab representing
+a swarm. The user describes it as a “super terminal” for the intelligence age.
+Developers should feel the speed, predictability, and familiar habits of a great
+terminal/editor while working with several agents across real machines and
+projects. They should keep their place and know exactly which agent receives
+their next instruction.
+
+The product is called **Harness**. “V2” is the internal UI/UX project name.
+This is a working desktop preview, not a completed release. Improving first use,
+navigation, input correctness, and latency matters more than adding many surfaces.
+The user wants autonomous progress, frequent commits/pushes, and decisions made
+in users' interests. Continue research into strong developer tools after the
+concrete issues are handled, adapting their useful habits to directing agents.
+Research must lead to justified improvements, not feature accumulation.
+
+## Repository and checkpoint
+
+- Repository: <https://github.com/autonomous-ai/autonomous-harness>.
+- Continue on **`app-v2`**, tracking `origin/app-v2`.
+- Draft [PR #31 — Harness: swarm workspaces for AI agents](https://github.com/autonomous-ai/autonomous-harness/pull/31)
+ is open from `app-v2` to `main`; verified at this handoff. Keep it draft while
+ qualification remains incomplete.
+- Previous UI checkpoint: `ac443eb`, following `2e8d69d` (search/menu controls),
+ `4154cf6` (Harness branding/account labels), and `06ba77c` (agent creation).
+- New code checkpoint: **`26a372e`**, terminal viewport preservation and naming
+ an empty default swarm after its first agent.
+- The following handoff commit saves this document, pending UI drafts, native
+ benchmark tooling, and the existing collaboration design notes.
+- The user explicitly authorized pushing everything to this public repository
+ on `app-v2`; do not ask again for routine checkpoint pushes there.
+- After the PR is merged, delete its branch, update `main`, and create a fresh
+ branch for the next change. Do not delete `app-v2` while its draft PR is active.
+
+Start with a clean checkout of the remote branch and inspect its latest commit.
+On an existing checkout, preserve local work before updating; use a fast-forward
+pull, not a reset. The prior computer's `/private/tmp` files, installed apps,
+saved account state, and localhost prototype server will not transfer with Git.
+All essential pending source drafts are now in [the handoff archive](handoff/app-v2-2026-09-13/README.md).
+
+## Core product rules
+
+- A **swarm** is a named collection of agent views. Its membership is deliberate;
+ opening a machine/project can seed it once, but later discovery must not
+ silently add or remove members.
+- An **agent** is a persistent runtime, not necessarily a coding agent. Codex,
+ Claude Code, Cursor, Hermes, OpenClaw, and others must fit the terminology.
+ Use the label **Agent**, not “Coding agent.”
+- One agent can appear in multiple personal swarms. Reuse its session, terminal
+ buffer, and retained renderer. Preserve each swarm's arrangement and focus.
+- Closing an agent view or swarm tab removes views; it must not stop or delete
+ the underlying agent. Focus/navigation must not send terminal input or seize
+ control of a runtime controlled elsewhere.
+- Keep native macOS tabs and traffic lights, compact pane headers, and a quiet
+ canvas. Wallpaper belongs on the empty New swarm page. Existing palettes
+ coordinate native chrome, Flutter UI, and terminal colors.
+- Preserve text drafts, selection, deliberate scroll position, clipboard/IME
+ behavior, and the destination of the first keystroke after every transition.
+- Notifications reflect real pending questions. No sample statuses or mock
+ agents in the normal application.
+- Ordinary shells, a full IDE, permanent management sidebars, and unrelated
+ dashboards are outside the current desktop task. Models/account usage remains
+ part of the native menu; older notes saying “No Models” are obsolete.
+
+## Latest approved design: two different experiences
+
+This is the next implementation priority. The user explicitly rejected using
+one global picker with only different labels/icons for navigation versus adding.
+Share data/search utilities where useful, but build **distinct UI and interaction
+flows** for these two jobs.
+
+| Entry point | Job | Required behavior |
+| --- | --- | --- |
+| Top-right navigation icon, replacing Search; Cmd-P | Navigate globally | Find agents/swarms and choose an exact existing destination. |
+| New swarm page | Add to this swarm | Find an existing agent or create a new one in this tab. |
+| Bottom-right floating + inside the swarm | Add to this swarm | The same Add agent experience as New swarm. |
+| Pane menu: Split right / Split down | Add at this position | The same Add agent experience, preserving the selected neighbor and direction. |
+| New agent action, including Cmd-N | Create | Always create a fresh runtime in the intended swarm/position. |
+| Tab-strip + | New swarm | Create a new swarm tab. |
+
+### Navigate
+
+- Put a navigation icon at the top right, alongside the notification bell.
+ Remove the separate top-right New agent +. A compass is a reasonable visual
+ candidate, but the exact glyph has not yet been implemented or reviewed.
+- Make the surface visibly about **places to go**, distinct from Add agent's
+ existing-agent search and creation surface. A swarm-oriented hierarchy/list
+ is an implementation candidate, not a separately approved mockup.
+- **If one matching agent appears in three swarms, show all three swarm
+ destinations and let the user choose.** Do not silently choose its latest
+ swarm or hide the alternatives by deduplicating only on agent identity.
+- Selecting an agent location focuses that exact agent in the chosen swarm;
+ selecting a swarm goes to that swarm. Navigation does not mutate membership.
+- Cmd-P remains the navigation shortcut. Cmd-Shift-P remains command mode.
+ Native menu, tooltip, help, custom bindings, and actual dispatch must agree.
+- The presentation for agents with no open swarm, closed swarm destinations,
+ and no matching agent still needs design. Resolve it deliberately: a clear
+ transition to Add/Create is possible, but do not turn a navigation result
+ into an unexpected membership change or silently create a duplicate runtime.
+
+### Add agent
+
+- Build one shared Add interface for **New swarm, the floating +, and both
+ split directions**. It must support existing agents and a clearly visible
+ **New agent** action. A split must not immediately force the creation form.
+- Existing-agent results on the left, attractive always-on preview on the
+ right, inspired by fzf and the user's Swarms v4 prototype. New swarm may embed
+ the component; + and Split can present it centrally as a modal.
+- Remove the eye/preview toggle. Show a bounded, readable excerpt with agent
+ identity and useful context; avoid raw terminal dumps, long separator rules,
+ clipped ANSI/TUI debris, and competing selected/hovered rows. Preview must
+ follow the actual keyboard/mouse selection and show an honest empty state.
+- Use one unambiguous primary action: add here, or add at the requested split.
+ “Go to agent” is wrong on the New swarm page. Keep the user in that tab.
+- Adding an existing agent reuses it and leaves its source swarms intact.
+ Avoid duplicate memberships. Decide a clear already-here/capacity state;
+ never pretend an unavailable action succeeded.
+- New agent from this surface preserves the original swarm/split destination,
+ even if the active tab changes while a dialog or request is pending.
+ Canceling preserves arrangement, zoom, focus, and the user's input.
+- Darken the modal backdrop so the active dialog has clear visual focus.
+ Apply the shared treatment consistently to app popups.
+
+### Other agreed visual and interaction decisions
+
+- Use one four-pane **SwarmIcon** everywhere a swarm is represented: search,
+ History, native menus, and starters that open swarms. A real folder/project
+ chooser can still use a folder symbol; keep the represented entity clear.
+- Swarm location metadata: show the machine name for one machine, or
+ **N machines** for multiple distinct machines.
+- Models/account rows consistently use short account IDs without the literal
+ word “Account”; do not mix email and ID presentation.
+- Native menu order requested: **Harness · Swarm · Agent · Models · History ·
+ Edit · View · Window · Help**. Keep standard supporting menus for native
+ editing/window/help behavior. The reorder is only in the saved picker draft.
+- New agent has one-click Codex / Claude Code / Cursor choices plus More for
+ the full list, remembered choice, neat Advanced options, and a separate
+ GitHub clone flow alongside choosing a local working folder.
+- Keep existing effective shortcuts. In particular preserve Cmd-H/J/K/L and
+ Cmd-arrows for focus, Cmd-S for layout, Cmd-R for refresh, and Cmd-B for Boss
+ mode. Do not revive the previously rejected default-remapping proposal.
+- Resizing uses restrained centered grips. Pane headers expose zoom and a
+ menu with split right/down. Verify their actual geometry and discoverability,
+ not just that callbacks exist.
+
+## Current implementation versus saved drafts
+
+**Implemented on the branch:** swarm/session retention, native tabs, layouts,
+closed-work History, palettes, editable centered search and command mode,
+keyboard customization, pane split/zoom controls, the simplified New agent
+dialog, Harness branding, consistent short account labels, saved project-name
+precedence, and independent machine loading while account metadata loads.
+See [the progress log](harness-v2-progress.md) for individual checkpoints and
+[the developer-tool audit](harness-v2-developer-tools-research.md) for research.
+
+**Important discrepancies still in the running/source UI:** the last built
+toolbar has Search + New agent + Notifications; global and inline pickers
+still share the old navigation behavior; previews remain optional/raw; Split
+opens creation directly. Do not describe the new two-experience design as shipped.
+
+**Saved, not applied to production source:** [picker and onboarding drafts](handoff/app-v2-2026-09-13/README.md).
+They contain reusable work for the floating +, add/split routing, preview cleanup,
+darker veils, menu order, keyboard routing, and first-use welcome. The picker draft
+predates the user's final requirement for completely different Navigate/Add UIs;
+adapt selected parts rather than blindly applying and shipping it. Both patches
+touch SwarmScreen and must be reconciled. The onboarding draft is unverified.
+
+**Also saved:** [native benchmark tooling](../desktop/tool/native_benchmark/README.md)
+and [shared-swarm collaboration research](harness-collaboration-design.md), which
+were existing uncommitted work. Collaboration is a separate proposal/prototype,
+not implemented multiplayer or a prerequisite for finishing this desktop pass.
+The benchmark still needs compatibility fixes before another run: its prepare
+script assumes the old `Harness V2` product name, its process check uses that
+name, and its native initial-responder logic is the older version. Preserve its
+isolation/focus guards. The performance notes explain the failed calibration.
+
+## Latest terminal fix and verification
+
+The user reported opening a project swarm with five terminals showing older
+content instead of the latest output. Ordinary fresh/delayed five-pane fixtures
+already reached the bottom. A targeted regression reproduced a separate concrete
+cause: shrinking a captured 100-row TUI while its hidden cursor is parked near
+the top deletes the newest rows from the local emulator.
+
+`26a372e` adds `TerminalView.resizeBuffer` (default true); Harness sets it false.
+The renderer reports the desired viewport without destructively resizing captured
+remote cells. The daemon's resized keyframe replaces the grid. Repeated output
+does not repeat the same resize request. New views show the latest output, while
+returning to a deliberately scrolled view preserves the reading position.
+The exact five-pane real-session screenshot still needs a direct recheck; do not
+claim this reproducer proves every cause of that symptom.
+
+The same checkpoint saves the existing first-agent naming change: an empty
+default “New swarm” adopts its first agent's name; custom names and other tabs
+are preserved. Tests cover subsequent additions and close/reopen behavior.
+
+Final checks on the committed code:
+
+- **1,244 desktop tests passed, one existing skip**, including the new four-case
+ terminal regression file and the two swarm naming tests.
+- Analyzer: **zero errors/warnings**, 12 existing vendored xterm informational
+ diagnostics, using `--no-fatal-infos`.
+- Native benchmark Python files pass syntax parsing; no new native benchmark
+ run or accepted timing result is claimed.
+- Both archived patches individually pass `git apply --check` against this
+ source checkpoint. That does not validate applying them together or their
+ compatibility with the new product decision.
+- The archived picker previously passed 57 focused Flutter tests and
+ 51 keymap decoder + 343 AppKit checks before it was parked. Those results
+ apply to the old draft only. Its final visual treatment still needs review.
+
+The workspace Release preview predates `26a372e`. It was last built through the
+search/toolbar checkpoint. **This handoff does not rebuild or restart the user's
+apps.** Tests are not proof of native visual/input latency. Prior native
+computer-use inspection failed at pipe startup; calibration failed with an
+inactive/non-key benchmark window. Continue on the new computer when that
+capability is actually available, not by looping the same failed attempt.
+
+## Plan for the next session
+
+1. **Read this document and inspect the current source.** Confirm branch/PR state,
+ toolchain, and local app identity. Inspect archived drafts before editing.
+2. **Implement the two approved experiences.** First define an exact navigation
+ destination `(swarm, agent/pane)` and location results for multi-swarm agents.
+ Build the distinct Navigate surface and shared Add interface. Reuse selected
+ draft pieces for FAB/split wiring, always-on preview, and backdrop treatment.
+ Complete native and Flutter entry points together so no route retains the
+ old confusing behavior. Keep command mode and customized keys working.
+3. **Validate the full interaction matrix below**, capture actual/synthetic
+ visuals with real fonts, and clearly label which was verified. Commit/push
+ the coherent result and update this handoff/progress record.
+4. **Improve genuine first use.** Start with no account/runtime/agents/projects
+ knowledge. Make “choose a working folder → choose an agent → start” clear;
+ use this computer by default, reveal machine/link/project concepts when
+ needed, and offer existing work prominently when discovered. Adapt the saved
+ onboarding draft to the new Add experience. Preserve choices on failure.
+5. **Recheck fresh terminal positioning and real workflows** on disposable
+ local/remote agents: startup, delayed snapshots, resizing, returning to a
+ scrolled view, reconnect, paste, selection, and IME.
+6. **Measure native responsiveness** under representative retained/output load,
+ then close remaining visual/platform/release qualification gaps. Maintain
+ the draft PR and keep its description honest about what's still unverified.
+
+## Acceptance criteria
+
+### Navigation and adding
+
+- One agent in three swarms yields three explicit usable destinations. Enter
+ focuses the chosen pane in the chosen swarm without altering membership.
+- The first character typed after navigation reaches only the selected agent.
+ Hidden/offscreen/zoomed destinations are revealed while retained sessions and
+ reading positions survive switching away and back.
+- All three Add entry points can add an existing agent and create a new agent.
+ Both split directions preserve their exact original placement. Source swarms
+ remain intact, and existing-agent addition starts no duplicate runtime.
+- Already-present, offline, removed, changed-membership, full-capacity, canceled,
+ and failed asynchronous actions produce a clear result without modifying the
+ wrong swarm or losing a draft. Late completion revalidates its destination.
+- Arrow keys, Enter, Escape, Cmd-A/Delete, paste, and IME work in each input.
+ One selected result drives the preview; repeated output cannot steal focus.
+- The toolbar has Navigate and Notifications; only the tab-strip + creates a
+ swarm. The floating Add + is bottom right and does not cover the terminal prompt.
+- The Add preview is always present when meaningful, readable at small/large
+ window sizes, bounded, and useful for choosing an agent. No eye toggle, raw
+ overflow, or ambiguous “Go to agent” action in the local Add workflow.
+
+### First impression and visual quality
+
+- A first-time developer can identify the primary next step without first
+ learning machines, projects, swarms, and agent-account configuration.
+- The happy path reaches a real usable agent with the fewest meaningful choices;
+ joining existing work and starting fresh are both discoverable. Missing tools,
+ authentication, connectivity, and failed creation give an actionable next step.
+- Observe first-use completion and confusion directly. “Hook everyone instantly”
+ is the user's aspiration, not a measured 100% conversion claim. Record actual
+ steps/time/errors before making onboarding performance claims.
+- One icon per concept and consistent labels/contrast across native and Flutter
+ controls. Six coordinated palettes remain legible; system text scaling,
+ keyboard focus indicators, accessibility labels, and narrow windows work.
+- Modals clearly separate foreground from background. Grips, splits, zoom,
+ menus, and account rows look intentional with real fonts and content.
+
+### Correctness and performance
+
+- Fresh views land at the latest output, including tall/delayed snapshots and
+ five-agent project swarms. Revisited scrolled-up views retain their position.
+- Shared agents retain one session/buffer/controller; hidden output does not
+ repeatedly lay out/paint hidden terminals or reconstruct unchanged catalogs.
+- Report cold/warm p50/p95/p99 for native event-to-raster typing/focus/tab changes
+ with 16 and 48 retained terminals, idle and under output load, when valid
+ foreground measurement is available. Report machine/build/load and raw sample
+ limits. Synthetic search CPU, Flutter raster, network RTT, and physical
+ key-to-display latency are different measurements and must stay distinct.
+- Reconnect preserves readable output/drafts and does not blindly replay input
+ or take over another controller. Real remote reconnect still needs evidence.
+- Run meaningful affected tests, analyzer, native decoder/titlebar checks for
+ native changes, and a Release build before claiming a new preview is loaded.
+ Full desktop regressions must pass before promoting the PR from draft.
+- Verify macOS native behavior directly and qualify Linux on a Linux host.
+ Windows support is unexercised; do not claim it from macOS test success.
+
+## Implementation and verification map
+
+| Area | Start here |
+| --- | --- |
+| Workspace orchestration, picker routes, split/new-agent context | `desktop/lib/screens/swarm_screen.dart` |
+| Search data, actions, destinations | `desktop/lib/state/swarm_search.dart`, `swarm_navigation.dart`, `swarm_catalog.dart` |
+| Existing picker and welcome UI | `desktop/lib/widgets/swarm_switcher.dart`, `swarm_inline_search.dart`, `swarm_search_input.dart`, `swarm_welcome.dart` |
+| Preview extraction | `desktop/lib/terminal/search_output_preview.dart` |
+| Native tabs, toolbar, menus | `desktop/macos/Runner/SwarmTitlebar.swift` |
+| Key ownership and customization | `desktop/lib/shortcuts/`, `desktop/tool/check_keymap_native.sh` |
+| Membership, retained panes and runtime | `desktop/lib/state/app_state.dart`, `swarm.dart`, `terminal_pane.dart` |
+| Terminal viewport fix | `desktop/lib/widgets/terminal_panel.dart`, `desktop/third_party/xterm/lib/src/ui/render.dart`, `desktop/test/terminal_initial_output_test.dart` |
+| Remote resized snapshot | `cli/src/lib/terminalStreamManager.ts`, `desktop/lib/terminal/terminal_session.dart` |
+| Design/research history | `docs/harness-v2-{progress,keyboard-system,appearance-onboarding,developer-tools-research,prototype-review,performance}.md` |
+
+## Toolchain and operating boundaries
+
+Read `desktop/CLAUDE.md`, but treat its old integration-test/sidebar/architecture
+descriptions as historical where current source differs. No applicable AGENTS.md
+was found in this checkout or its ancestors during the work.
+
+This checkpoint used **Flutter 3.47.2 / Dart 3.13.2**, Swift Package Manager,
+and Xcode on Apple Silicon. On the other computer install/select that compatible
+SDK; the old `/private/tmp/harness-v2-flutter` path is not a portable dependency.
+From `desktop/`:
+
+```sh
+flutter config --enable-swift-package-manager
+flutter pub get
+flutter analyze --no-pub --no-fatal-infos
+flutter test --no-pub
+bash tool/check_keymap_native.sh /absolute/path/to/flutter-sdk
+```
+
+Enable SPM before pub get. Do not commit a CocoaPods fallback rewrite, generated
+build files, caches, credentials, or real account/terminal state. The vendored
+xterm contains required patches; do not replace it with the pub.dev package.
+Build instructions and prior measurements are in the progress/performance notes.
+
+The normal entry point is `desktop/lib/main.dart`. The public app/binary name
+is **Harness**; the development bundle ID remains `ai.autonomous.harness.v2` to
+preserve its separate state. Workspace Release path on the old computer was
+`desktop/build/macos/Build/Products/Release/Harness.app`; the installed Harness
+was a separate process. Recheck exact bundle paths/PIDs before normally quitting
+or relaunching a preview. Do not launch a competing duplicate or use a real
+agent's prompt as a test input.
+
+Keep tests/benchmarks isolated with temporary stores and synthetic/disposable
+transports. Do not upgrade or restart the user's production CLI/daemon for
+qualification. Follow the requested `app-v2` checkpoint workflow; publishing a
+release, merging the draft, and production end-to-end operations are separate
+tasks. Keep handoff notes current as work progresses.
diff --git a/docs/harness-v2-keyboard-system.md b/docs/harness-v2-keyboard-system.md
index 2c9f68aec..6ebd6c1ff 100644
--- a/docs/harness-v2-keyboard-system.md
+++ b/docs/harness-v2-keyboard-system.md
@@ -1,5 +1,7 @@
# A coherent keyboard system for Harness
+Current continuation: [goal, plan, and acceptance criteria](harness-v2-handoff.md). The latest user decision separates global Navigate (Cmd-P) from local Add agent; earlier descriptions of identical direct-open behavior in both search fields are superseded. Cmd-Shift-P remains command mode. The new separation is approved but not yet implemented at this handoff.
+
Updated 2026-09-13 after the user's review. **The earlier proposed modifier-heavy defaults are withdrawn.** The user explicitly chose to retain Cmd-H/J/K/L and Cmd-arrows for pane movement, Cmd-S for layout, Cmd-R for refresh, and Cmd-B for Boss mode. Cmd-L stays move right. File remapping is available; menus and help reflect the effective bindings.
## Product contract
@@ -18,8 +20,9 @@ Keep ordinary typing and editing predictable inside the actual agent CLI, search
| Layout | Keep Cmd-S. The user explicitly resolved the Cmd-L conflict in favor of the complete H/J/K/L family. |
| Refresh machines/agents | Keep Cmd-R. The user considered using it for relayout and chose to preserve refresh. |
| Boss mode / task routing | Keep Cmd-B. |
-| Search and open agents/swarms | Keep Cmd-P and the same direct-open behavior in both search fields. |
-| Machine/project search result | Open its swarm directly; no intermediate Browse agents step. |
+| Navigate agents/swarms | Keep Cmd-P. Show every swarm destination for agents with multiple memberships; choosing one focuses that exact view. New design pending implementation. |
+| Local Add agent | New swarm, floating +, and Split share existing-agent search and New agent creation. Keep the target swarm/position; this is a separate UI from Navigate. |
+| Machine/project results | Their effect depends on the entry point; never silently navigate away from a local Add flow. Bulk addition seeds membership once. Final presentation belongs to the new Navigate/Add implementation. |
| Other existing shortcuts | Preserve until a concrete problem justifies a reviewed change. Do not silently switch Cmd-number navigation, zoom, tab traversal, or closing to the earlier proposed alternatives. |
| File customization | One commented config file with reload; menus, help and dispatch must agree. |
| Commands in search | Approved: Cmd-Shift-P opens `>` command mode, following the later user decision. Pin remains available in the Agent menu, pane menu, commands and custom bindings. |
diff --git a/docs/harness-v2-progress.md b/docs/harness-v2-progress.md
index 296554d0f..38a87c584 100644
--- a/docs/harness-v2-progress.md
+++ b/docs/harness-v2-progress.md
@@ -1,6 +1,18 @@
# Harness App V2 — development handoff
-Updated 2026-09-13 with coordinated palettes, Models, combined closed-work History and faster unified search. This is a working preview, not a release.
+Updated 2026-09-13 for transfer to another computer/session. This is a working preview, not a release.
+
+**Resume with [Harness v2: goal, plan, and continuation handoff](harness-v2-handoff.md).** It records the latest approved design, acceptance criteria, next-work order, and portable drafts. The checkpoints below are historical; the current handoff supersedes their conflicting toolbar, picker, preview, menu, and onboarding directions.
+
+## Cross-computer checkpoint
+
+- Saved `26a372e`: preserve captured terminal rows until the remote resized keyframe, avoiding deletion of the latest output when a tall TUI enters a smaller pane. Fresh five-pane and delayed-snapshot regressions reach the bottom; revisited scrolled views retain their place. The user's exact live screenshot still needs rechecking.
+- Also committed the existing first-agent naming work: default empty New swarms adopt the first agent's name, preserving custom names and close/reopen behavior.
+- Full desktop suite: **1,244 passed, one existing skip**. Analyzer: zero errors/warnings, 12 existing vendored infos. Logs on the original computer: `/private/tmp/harness-handoff-full-tests.log` and `/private/tmp/harness-handoff-analyze.log`.
+- Latest approved UX is **two distinct experiences**: top-right global Navigate/Cmd-P with an explicit choice of every swarm containing a matching agent; bottom-right floating +, New swarm, and Split right/down share one local Add interface for existing or new agents. This is the next implementation step, not shipped UI.
+- Saved earlier picker/onboarding work under [docs/handoff/app-v2-2026-09-13](handoff/app-v2-2026-09-13/README.md), including new Dart files. Do not blindly reapply the older combined picker; reconcile it with the two-UI decision. Both patches check individually; their combined application and onboarding behavior remain unverified.
+- The handoff also saves the previously untracked native benchmark and collaboration design. Benchmark calibration is still unmeasured and its old product-name/focus assumptions need updating; collaboration is a proposal, not implemented multiplayer.
+- Draft [PR #31](https://github.com/autonomous-ai/autonomous-harness/pull/31) is still open, `app-v2` to `main`. The user requested committing/pushing all work and transferring ownership. No new app rebuild/restart is part of this checkpoint.
## Search, creation and workspace controls checkpoint
@@ -245,6 +257,8 @@ Updated 2026-09-13 with coordinated palettes, Models, combined closed-work Histo
## Resume here
+Historical environment snapshot below. Start with [the current cross-computer handoff](harness-v2-handoff.md); local paths/PIDs and older design decisions here may be stale.
+
- Repository: https://github.com/autonomous-ai/autonomous-harness
- Branch: `app-v2`, tracking `origin/app-v2` in that repository.
- Resume folder: `/Users/ab/code/autonomous-harness`.
@@ -281,6 +295,8 @@ The former preview folder `/Users/ab/code/harness-app-v2` is retained as a backu
## Product contract and design reference
+This section preserves the earlier contract. Current Navigate/Add, Models, palettes, and onboarding decisions are in [the handoff](harness-v2-handoff.md).
+
Harness is one place to work with all your agents. Swarms are named, chosen collections of agent terminal views across machines and projects, shown as real native window tabs on macOS.
- No Models, Grid, permanent workspace sidebar, persistent workspace toolbar, or pane footer.
@@ -496,6 +512,8 @@ Earlier logs contain superseded failures. Temporary logs and toolchains are loca
## Remaining work
+The immediate priority is the approved distinct Navigate surface and shared local Add interface, followed by first-use clarity. Use [the current plan and acceptance criteria](harness-v2-handoff.md#plan-for-the-next-session) before this older qualification backlog.
+
1. Measure native terminal input and tab-switch responsiveness under output load, including p50/p95/p99 and cold/warm paths. Calibration is paused until there is new evidence that the isolated window can become active/key; do not bypass its focus guard. Earlier live Cmd+P destination focus/quick return, branch headers, project associations, New swarm cleanup and native History were verified. Keep typing/transport measurements in disposable fixtures; the user's real agent terminals are not test inputs.
2. Native overflow, drop ownership/bounds, close-last-tab, rename and keyboard/accessibility control focus are now covered by isolated AppKit/Flutter regressions. Live pointer dragging and VoiceOver still need a foreground-capable disposable window. Keep any integration runner separate and out of the foreground review app; preserve saved agent memberships.
3. Verify real remote reconnect, agent input, paste, selection and IME against disposable local/remote processes. The AppNotifier/keyframe and stale completion regressions now pass; they do not prove every network or native editing condition. Preserve immediate first-input flush and shared retained renderers.
@@ -532,7 +550,7 @@ XDG_CONFIG_HOME=/private/tmp/harness-v2-tool-config xcodebuild \
-derivedDataPath build/macos -destination 'platform=macOS,arch=arm64' \
CODE_SIGN_IDENTITY=- CODE_SIGN_STYLE=Manual DEVELOPMENT_TEAM= \
OTHER_CODE_SIGN_FLAGS= ENABLE_HARDENED_RUNTIME=NO build
-open -n 'build/macos/Build/Products/Release/Harness V2.app'
+open -n 'build/macos/Build/Products/Release/Harness.app'
```
Quit an existing V2 preview normally before rebuilding its bundle. Flutter's asynchronous termination may make AppleScript report `User canceled (-128)` even though the process exits; verify the process state before interpreting that as a refused quit. The final optimized preview was launched and its process verified running. Do not launch a second V2 instance while one remains active.
@@ -556,10 +574,10 @@ npx vitest run src/lib/agentFrame.spec.ts src/lib/agentProject.spec.ts
Some tests require permission to bind disposable loopback sockets. Inject memory/temp stores, skip real credential/usage pollers using `kUnderTest`, and never treat a real Harness home as a fixture. Keep patched `desktop/third_party/xterm`, not pub.dev xterm.
-The real review app uses `/Users/ab/code/autonomous-harness/desktop/build/macos/Build/Products/Release/Harness V2.app`, with the separate V2 bundle identity and saved V2 state. Its optimized local build has been launched and verified running. The earlier debug build remains in the sibling `Debug/` directory. Production Harness remains separate. Never automatically take over its terminals or use a real Harness home as a test fixture.
+The real review app uses `/Users/ab/code/autonomous-harness/desktop/build/macos/Build/Products/Release/Harness.app`, with the separate V2 bundle identity and saved V2 state. Its previous optimized local build was launched and verified running; the handoff's latest terminal change has not been rebuilt into that preview. Production Harness remains separate. Never automatically take over its terminals or use a real Harness home as a test fixture.
## Publishing boundaries
-The user authorized publishing branch `app-v2` in `autonomous-ai/autonomous-harness` for later merging. This is not authorization to merge, release/tag, publish binaries, run production E2E, update/restart the production CLI, or delete the old fork. No PR is needed yet.
+The user explicitly authorized frequent pushes to branch `app-v2` in public `autonomous-ai/autonomous-harness`, including all workspace work for this handoff. Draft PR #31 is open for later merging; keep it draft while qualification is incomplete. Release/tag publishing, production E2E and production CLI changes are separate tasks. After the PR merges, delete `app-v2`, update `main`, and create a fresh branch for the next change.
Workflow triggers were checked: CI runs for PRs/manual calls; internal desktop builds for `internal/**`; release/deployment for suffixed tags. A plain `app-v2` push does not trigger those release workflows. Keep future work/pushes on `app-v2` unless the user changes that instruction.