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.

Keep first-launch installation actions visible and fix retry

dee3ab66ca1ee40
diff --git a/desktop/lib/widgets/environment_setup_screen.dart b/desktop/lib/widgets/environment_setup_screen.dart
index 5dad543f6..d71244a98 100644
--- a/desktop/lib/widgets/environment_setup_screen.dart
+++ b/desktop/lib/widgets/environment_setup_screen.dart
@@ -4,6 +4,7 @@ import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import '../bootstrap/environment_provisioner.dart';
+import '../shared/theme/app_theme.dart' as grid;
import '../shared/widgets/command_row.dart';
import '../state/app_state.dart';
import '../theme/app_theme.dart';
@@ -21,6 +22,25 @@ class EnvironmentSetupScreen extends StatefulWidget {
class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
String? _copied;
+ final _scroll = ScrollController();
+ final _primaryFocus = FocusNode(debugLabel: 'Setup action');
+ final _bodyFocus = FocusNode(
+ debugLabel: 'Setup details',
+ skipTraversal: true,
+ );
+ final _manualFocus = FocusNode(debugLabel: 'Switch setup method');
+ EnvironmentSetupPhase? _lastPhase;
+ bool _actionWasAvailable = false;
+ bool _detailsOpen = false;
+
+ @override
+ void dispose() {
+ _scroll.dispose();
+ _primaryFocus.dispose();
+ _bodyFocus.dispose();
+ _manualFocus.dispose();
+ super.dispose();
+ }
Future<void> _copy(String value) async {
await Clipboard.setData(ClipboardData(text: value));
@@ -33,23 +53,68 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
@override
Widget build(BuildContext context) {
+ grid.AppTheme.watch(context);
final state = widget.notifier.environmentReadiness;
+ final phaseChanged = _lastPhase != state.phase;
+ final actionAvailable =
+ !widget.notifier.environmentSetupInFlight &&
+ const {
+ EnvironmentSetupPhase.review,
+ EnvironmentSetupPhase.chooseMethod,
+ EnvironmentSetupPhase.failed,
+ EnvironmentSetupPhase.waitingForTerminal,
+ EnvironmentSetupPhase.ready,
+ }.contains(state.phase);
+ if (phaseChanged || (actionAvailable && !_actionWasAvailable)) {
+ WidgetsBinding.instance.addPostFrameCallback((_) {
+ if (!mounted || ModalRoute.of(context)?.isCurrent == false) return;
+ if (widget.notifier.environmentReadiness.phase != state.phase) return;
+ if (phaseChanged && _scroll.hasClients) _scroll.jumpTo(0);
+ // A new next step should be usable with Enter. Keep an explicit choice
+ // to read/copy details or change methods when asynchronous updates land.
+ if (actionAvailable &&
+ !widget.notifier.environmentSetupInFlight &&
+ !_bodyFocus.hasFocus &&
+ !_manualFocus.hasFocus) {
+ _primaryFocus.requestFocus();
+ }
+ });
+ }
+ _lastPhase = state.phase;
+ _actionWasAvailable = actionAvailable;
+ final compact = MediaQuery.sizeOf(context).height < 640;
return Scaffold(
backgroundColor: AppColors.background,
- body: Center(
- child: SingleChildScrollView(
- padding: const EdgeInsets.all(24),
- child: ConstrainedBox(
- constraints: const BoxConstraints(maxWidth: 760),
- child: Column(
- mainAxisSize: MainAxisSize.min,
- children: [
- Padding(
- padding: const EdgeInsets.fromLTRB(32, 28, 32, 24),
- child: _body(state),
+ body: SafeArea(
+ child: Padding(
+ padding: EdgeInsets.all(compact ? 16 : 24),
+ child: Center(
+ child: ConstrainedBox(
+ constraints: const BoxConstraints(maxWidth: 760),
+ child: Material(
+ color: AppColors.sidebar,
+ clipBehavior: Clip.antiAlias,
+ shape: RoundedRectangleBorder(
+ borderRadius: BorderRadius.circular(14),
+ side: BorderSide(color: AppColors.border),
),
- _footer(state),
- ],
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Flexible(
+ child: SingleChildScrollView(
+ controller: _scroll,
+ padding: EdgeInsets.all(compact ? 20 : 28),
+ child: Focus(
+ focusNode: _bodyFocus,
+ child: _body(state),
+ ),
+ ),
+ ),
+ _footer(state),
+ ],
+ ),
+ ),
),
),
),
@@ -80,14 +145,14 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
letterSpacing: 1.4,
),
),
- const SizedBox(height: 10),
+ const SizedBox(height: 6),
Text(
title,
style: const TextStyle(fontSize: 28, fontWeight: FontWeight.w600),
),
- const SizedBox(height: 12),
+ const SizedBox(height: 8),
Text(lead, style: TextStyle(color: AppColors.textSoft, height: 1.55)),
- const SizedBox(height: 26),
+ const SizedBox(height: 16),
],
);
@@ -97,14 +162,8 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
_heading(
'Getting started',
'Checking this computer',
- 'This check is read-only. Harness verifies every tool it needs before proposing any changes.',
- ),
- _notice(
- Icons.lock_outline,
- 'Nothing is being installed',
- 'No files, packages or system settings change during this check.',
+ 'Checking the tools Harness needs to run your agents.',
),
- const SizedBox(height: 18),
_checkList(state, checking: true),
],
);
@@ -113,8 +172,7 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
final mode = state.mode ?? EnvironmentSetupMode.automatic;
final items = _installItems(state);
final count = items.length;
- final countLabel =
- '$count missing ${count == 1 ? 'dependency' : 'dependencies'}';
+ final countLabel = '$count ${count == 1 ? 'tool' : 'tools'}';
final needsTerminal = items.any((item) => item.requiresTerminal);
return Column(
crossAxisAlignment: CrossAxisAlignment.start,
@@ -123,9 +181,10 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
'Getting started',
'Get this computer ready',
count == 0
- ? 'Nothing is left to install. Harness will run one final verification.'
- : 'Harness brings your agents together in one workspace. '
- 'Set up the $countLabel below, then sign in to get started.',
+ ? 'Your tools are ready. Verify them to continue.'
+ : count == 1
+ ? 'Install this tool, then sign in to start your first agent.'
+ : 'Install these $countLabel, then sign in to start your first agent.',
),
Row(
children: [
@@ -156,16 +215,13 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
_notice(
Icons.terminal,
'Admin prompts stay in Terminal',
- 'Harness opens one operating system Terminal for the missing host dependencies. Your password is entered there and is never read or stored by this app.',
- warning: true,
+ 'Complete any installation prompts there, then return to Harness.',
),
const SizedBox(height: 16),
],
_planList(items),
] else
_manualList(items),
- const SizedBox(height: 14),
- _verificationHint(),
],
);
}
@@ -186,8 +242,7 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
_notice(
Icons.lock_outline,
'Harness cannot see your password',
- 'Complete the visible prompts in Terminal. This screen checks again automatically every 5 seconds.',
- warning: true,
+ 'Finish the prompts in Terminal, then return here. Harness checks progress automatically.',
),
const SizedBox(height: 18),
_checkList(state, checking: true),
@@ -205,13 +260,6 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
failure?.title ?? 'Environment setup failed',
failure?.detail ?? state.message ?? 'Review the full error below.',
),
- _notice(
- Icons.error_outline,
- 'The app stopped safely',
- 'Nothing after the failed required step was started. Retry or switch to Manual.',
- error: true,
- ),
- const SizedBox(height: 16),
_checkList(state),
if (failure?.command != null) ...[
const SizedBox(height: 16),
@@ -235,12 +283,6 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
'Every required command passed. Continue to Harness sign-in.',
),
_checkList(state),
- const SizedBox(height: 18),
- _notice(
- Icons.check_circle_outline,
- 'Verified, not assumed',
- 'Harness repeats this quick read-only check whenever the desktop app starts.',
- ),
],
);
@@ -402,11 +444,13 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
'Every dependency is ready. Continue to final verification.',
);
}
+ final stacked = MediaQuery.textScalerOf(context).scale(1) > 1.25;
return _Panel(
child: Column(
children: [
for (var index = 0; index < items.length; index++)
ListTile(
+ dense: true,
leading: CircleAvatar(
radius: 14,
backgroundColor: AppColors.hover,
@@ -419,16 +463,24 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
items[index].title,
style: const TextStyle(fontSize: 13),
),
- trailing: ConstrainedBox(
- constraints: const BoxConstraints(maxWidth: 280),
- child: Text(
- items[index].detail,
- maxLines: 2,
- overflow: TextOverflow.ellipsis,
- textAlign: TextAlign.end,
- style: TextStyle(color: AppColors.muted, fontSize: 11),
- ),
- ),
+ subtitle: stacked
+ ? Text(
+ items[index].detail,
+ style: TextStyle(color: AppColors.textSoft, fontSize: 11),
+ )
+ : null,
+ trailing: stacked
+ ? null
+ : ConstrainedBox(
+ constraints: const BoxConstraints(maxWidth: 280),
+ child: Text(
+ items[index].detail,
+ maxLines: 2,
+ overflow: TextOverflow.ellipsis,
+ textAlign: TextAlign.end,
+ style: TextStyle(color: AppColors.muted, fontSize: 11),
+ ),
+ ),
),
],
),
@@ -471,19 +523,6 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
],
);
- Widget _verificationHint() => Row(
- children: [
- Icon(Icons.verified_outlined, size: 16, color: AppColors.success),
- const SizedBox(width: 8),
- Expanded(
- child: Text(
- 'After installation, Harness verifies every required command.',
- style: TextStyle(color: AppColors.textSoft, fontSize: 11),
- ),
- ),
- ],
- );
-
Widget _logs(EnvironmentReadiness state) {
if (state.output.isEmpty) return const SizedBox.shrink();
final diagnostics = state.output.join('\n');
@@ -495,28 +534,30 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
border: Border.all(color: AppColors.border),
borderRadius: BorderRadius.circular(10),
),
- child: Column(
- crossAxisAlignment: CrossAxisAlignment.start,
- children: [
- Padding(
- padding: const EdgeInsets.symmetric(horizontal: 14, vertical: 10),
- child: Row(
- children: [
- const Text(
- 'Live logs',
- style: TextStyle(fontSize: 12, fontWeight: FontWeight.w600),
- ),
- const Spacer(),
- TextButton.icon(
- onPressed: () => _copy(diagnostics),
- icon: const Icon(Icons.copy, size: 14),
- label: Text(
- _copied == diagnostics ? 'Copied' : 'Copy diagnostics',
- ),
- ),
- ],
+ child: ExpansionTile(
+ initiallyExpanded: _detailsOpen,
+ maintainState: true,
+ expandedCrossAxisAlignment: CrossAxisAlignment.stretch,
+ expansionAnimationStyle: AnimationStyle.noAnimation,
+ onExpansionChanged: (open) => setState(() => _detailsOpen = open),
+ title: Row(
+ children: [
+ const Expanded(
+ child: Text(
+ 'Setup details',
+ style: TextStyle(fontSize: 12, fontWeight: FontWeight.w600),
+ ),
),
- ),
+ TextButton.icon(
+ onPressed: () => _copy(diagnostics),
+ icon: const Icon(Icons.copy, size: 14),
+ label: Text(
+ _copied == diagnostics ? 'Copied' : 'Copy diagnostics',
+ ),
+ ),
+ ],
+ ),
+ children: [
Divider(height: 1, color: AppColors.border),
ConstrainedBox(
constraints: const BoxConstraints(maxHeight: 210),
@@ -539,18 +580,8 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
);
}
- Widget _notice(
- IconData icon,
- String title,
- String detail, {
- bool warning = false,
- bool error = false,
- }) {
- final tone = error
- ? AppColors.danger
- : warning
- ? AppColors.warning
- : AppColors.accent;
+ Widget _notice(IconData icon, String title, String detail) {
+ final tone = AppColors.accent;
return Container(
padding: const EdgeInsets.all(14),
decoration: BoxDecoration(
@@ -595,85 +626,104 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {
final busy = widget.notifier.environmentSetupInFlight;
final mode = state.mode ?? EnvironmentSetupMode.automatic;
final missingCount = _installItems(state).length;
+ final manual = mode == EnvironmentSetupMode.manual;
+ String? label;
+ VoidCallback? action;
+ IconData? icon;
+ switch (state.phase) {
+ case EnvironmentSetupPhase.review || EnvironmentSetupPhase.chooseMethod:
+ label = manual
+ ? 'Check again'
+ : missingCount == 0
+ ? 'Verify and continue'
+ : 'Install $missingCount ${missingCount == 1 ? 'tool' : 'tools'}';
+ icon = manual ? Icons.refresh : Icons.download_outlined;
+ action = manual
+ ? widget.notifier.retryEnvironmentSetup
+ : widget.notifier.startEnvironmentSetup;
+ case EnvironmentSetupPhase.failed:
+ label = 'Retry';
+ action = manual
+ ? widget.notifier.retryEnvironmentSetup
+ : widget.notifier.startEnvironmentSetup;
+ case EnvironmentSetupPhase.ready:
+ label = 'Continue to sign in';
+ action = widget.notifier.continueAfterEnvironmentSetup;
+ case EnvironmentSetupPhase.waitingForTerminal:
+ label = 'Recheck now';
+ icon = Icons.refresh;
+ action = () => widget.notifier.recheckEnvironmentStep(
+ state.steps[EnvironmentStep.clipboard] ==
+ EnvironmentStepStatus.needsTerminal
+ ? EnvironmentStep.clipboard
+ : EnvironmentStep.tmux,
+ );
+ default:
+ break;
+ }
+ final actions = Wrap(
+ alignment: WrapAlignment.end,
+ crossAxisAlignment: WrapCrossAlignment.center,
+ spacing: 8,
+ runSpacing: 8,
+ children: [
+ if (state.phase == EnvironmentSetupPhase.failed && !manual)
+ TextButton(
+ focusNode: _manualFocus,
+ onPressed: busy
+ ? null
+ : () {
+ widget.notifier.selectEnvironmentSetupMode(
+ EnvironmentSetupMode.manual,
+ );
+ widget.notifier.showEnvironmentMethodChoice();
+ },
+ child: const Text('Switch to Manual'),
+ ),
+ if (label != null)
+ FilledButton.icon(
+ focusNode: _primaryFocus,
+ autofocus: true,
+ onPressed: busy ? null : action,
+ icon: icon == null ? null : Icon(icon, size: 16),
+ label: Text(label),
+ )
+ else if (busy)
+ const SizedBox(
+ width: 18,
+ height: 18,
+ child: CircularProgressIndicator(strokeWidth: 2),
+ ),
+ ],
+ );
+ final next = Text(
+ 'Next: sign in and start an agent.',
+ style: TextStyle(color: AppColors.textSoft, fontSize: 11),
+ );
return Container(
- padding: const EdgeInsets.symmetric(horizontal: 36, vertical: 16),
+ padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 16),
decoration: BoxDecoration(
color: AppColors.sidebar,
border: Border(top: BorderSide(color: AppColors.border)),
),
- child: Row(
- children: [
- Expanded(
- child: Text(
- 'Next: sign in and start an agent.',
- maxLines: 1,
- overflow: TextOverflow.ellipsis,
- style: TextStyle(color: AppColors.muted, fontSize: 11),
- ),
- ),
- const SizedBox(width: 12),
- if (state.phase == EnvironmentSetupPhase.review ||
- state.phase == EnvironmentSetupPhase.chooseMethod) ...[
- FilledButton.icon(
- onPressed: busy
- ? null
- : mode == EnvironmentSetupMode.automatic
- ? widget.notifier.startEnvironmentSetup
- : widget.notifier.retryEnvironmentSetup,
- icon: Icon(
- mode == EnvironmentSetupMode.automatic
- ? Icons.play_arrow
- : Icons.refresh,
- size: 16,
- ),
- label: Text(
- mode == EnvironmentSetupMode.automatic
- ? missingCount == 0
- ? 'Verify and continue'
- : 'Install $missingCount ${missingCount == 1 ? 'tool' : 'tools'}'
- : 'I ran these · Recheck',
- ),
- ),
- ] else if (state.phase == EnvironmentSetupPhase.ready)
- FilledButton(
- onPressed: widget.notifier.continueAfterEnvironmentSetup,
- child: const Text('Continue to sign in'),
- )
- else if (state.phase == EnvironmentSetupPhase.failed) ...[
- TextButton(
- onPressed: () {
- widget.notifier.selectEnvironmentSetupMode(
- EnvironmentSetupMode.manual,
- );
- widget.notifier.showEnvironmentMethodChoice();
- },
- child: const Text('Switch to Manual'),
- ),
- const SizedBox(width: 8),
- FilledButton(
- onPressed: busy ? null : widget.notifier.startEnvironmentSetup,
- child: const Text('Retry'),
- ),
- ] else if (state.phase == EnvironmentSetupPhase.waitingForTerminal)
- OutlinedButton.icon(
- onPressed: busy
- ? null
- : () => widget.notifier.recheckEnvironmentStep(
- state.steps[EnvironmentStep.clipboard] ==
- EnvironmentStepStatus.needsTerminal
- ? EnvironmentStep.clipboard
- : EnvironmentStep.tmux,
- ),
- icon: const Icon(Icons.refresh, size: 16),
- label: const Text('Recheck now'),
- )
- else if (busy)
- const SizedBox(
- width: 18,
- height: 18,
- child: CircularProgressIndicator(strokeWidth: 2),
- ),
- ],
+ child: LayoutBuilder(
+ builder: (context, constraints) {
+ if (constraints.maxWidth < 600 ||
+ MediaQuery.textScalerOf(context).scale(1) > 1.25) {
+ return Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [next, const SizedBox(height: 12), actions],
+ );
+ }
+ return Row(
+ children: [
+ Expanded(child: next),
+ const SizedBox(width: 12),
+ actions,
+ ],
+ );
+ },
),
);
}
diff --git a/desktop/test/boot_flow_widget_test.dart b/desktop/test/boot_flow_widget_test.dart
index 367a2b6c9..9655825fc 100644
--- a/desktop/test/boot_flow_widget_test.dart
+++ b/desktop/test/boot_flow_widget_test.dart
@@ -642,7 +642,7 @@ void main() {
await tester.pump();
expect(find.textContaining('/bin/sh -s -- --desktop'), findsOneWidget);
- expect(find.text('I ran these · Recheck'), findsOneWidget);
+ expect(find.text('Check again'), findsOneWidget);
});
testWidgets(
diff --git a/desktop/test/environment_setup_screen_test.dart b/desktop/test/environment_setup_screen_test.dart
new file mode 100644
index 000000000..53bfb1b6c
--- /dev/null
+++ b/desktop/test/environment_setup_screen_test.dart
@@ -0,0 +1,278 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/auth/auth_session.dart';
+import 'package:harness/auth/cli_login.dart';
+import 'package:harness/bootstrap/environment_provisioner.dart';
+import 'package:harness/core/config.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/state/app_state.dart';
+import 'package:harness/widgets/environment_setup_screen.dart';
+
+const _review = EnvironmentReadiness(
+ steps: {
+ EnvironmentStep.clipboard: EnvironmentStepStatus.notApplicable,
+ EnvironmentStep.tmux: EnvironmentStepStatus.failed,
+ EnvironmentStep.harness: EnvironmentStepStatus.failed,
+ },
+ phase: EnvironmentSetupPhase.review,
+ homebrewReady: false,
+ tmuxBinaryReady: false,
+);
+
+class _Login extends CliLogin {
+ @override
+ Future<CliAuthStatus> checkStatus() async =>
+ const CliAuthStatus(loggedIn: false);
+}
+
+class _Attempt {
+ _Attempt(this.install, this.progress);
+ final bool install;
+ final void Function(EnvironmentReadiness) progress;
+ final result = Completer<EnvironmentReadiness>();
+ void finish(EnvironmentReadiness state) {
+ progress(state);
+ result.complete(state);
+ }
+}
+
+class _Provisioner extends EnvironmentProvisioner {
+ _Provisioner() : super(isMacOS: true);
+ final attempts = <_Attempt>[];
+ @override
+ Future<EnvironmentReadiness> ensureReady({
+ required void Function(EnvironmentReadiness) onProgress,
+ EnvironmentReadiness? resumeFrom,
+ bool install = true,
+ EnvironmentSetupMode? mode,
+ }) {
+ final attempt = _Attempt(install, onProgress);
+ attempts.add(attempt);
+ onProgress(
+ (resumeFrom ?? _review).copyWith(
+ phase: install
+ ? EnvironmentSetupPhase.installing
+ : EnvironmentSetupPhase.preflight,
+ ),
+ );
+ return attempt.result.future;
+ }
+}
+
+Future<void> _mount(
+ WidgetTester tester,
+ AppNotifier app, {
+ double textScale = 1,
+}) async {
+ tester.view.devicePixelRatio = 1;
+ tester.view.physicalSize = const Size(880, 560);
+ addTearDown(tester.view.reset);
+ await tester.pumpWidget(
+ MaterialApp(
+ theme: grid
+ .buildAppTheme(brightness: Brightness.dark)
+ .copyWith(platform: TargetPlatform.macOS),
+ builder: (context, child) => MediaQuery(
+ data: MediaQuery.of(context).copyWith(
+ disableAnimations: true,
+ textScaler: TextScaler.linear(textScale),
+ ),
+ child: child!,
+ ),
+ home: ListenableBuilder(
+ listenable: app,
+ builder: (_, _) => app.status == AppStatus.unauthenticated
+ ? const Scaffold(body: Text('Sign-in reached'))
+ : EnvironmentSetupScreen(notifier: app),
+ ),
+ ),
+ );
+ await tester.pump();
+}
+
+AppNotifier _app(_Provisioner provisioner) =>
+ AppNotifier(
+ config: AppConfig.dev,
+ authSession: AuthSession(),
+ configStore: null,
+ cliLogin: _Login(),
+ environmentProvisioner: provisioner,
+ )
+ ..status = AppStatus.preparingEnvironment
+ ..environmentReadiness = _review;
+
+void main() {
+ testWidgets('manual setup keeps keyboard focus and never starts an install', (
+ tester,
+ ) async {
+ final provisioner = _Provisioner();
+ final app = _app(provisioner);
+ await _mount(tester, app);
+ await tester.sendKeyDownEvent(LogicalKeyboardKey.shiftLeft);
+ await tester.sendKeyEvent(LogicalKeyboardKey.tab);
+ await tester.sendKeyUpEvent(LogicalKeyboardKey.shiftLeft);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(app.environmentReadiness.mode, EnvironmentSetupMode.manual);
+ expect(find.text('Check again').hitTestable(), findsOneWidget);
+ // The method button retains focus when its label changes. Enter again
+ // switches back instead of accidentally running the newly enabled action.
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(app.environmentReadiness.mode, EnvironmentSetupMode.automatic);
+ expect(provisioner.attempts, isEmpty);
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ });
+
+ testWidgets('Retry after manual setup failure remains a read-only check', (
+ tester,
+ ) async {
+ final provisioner = _Provisioner();
+ final app = _app(provisioner)
+ ..environmentReadiness = _review.copyWith(
+ phase: EnvironmentSetupPhase.failed,
+ mode: EnvironmentSetupMode.manual,
+ );
+ await _mount(tester, app);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(provisioner.attempts, hasLength(1));
+ expect(provisioner.attempts.single.install, isFalse);
+ provisioner.attempts.single.finish(
+ _review.copyWith(mode: EnvironmentSetupMode.manual),
+ );
+ await tester.pump();
+ await tester.pump();
+ expect(find.text('Check again').hitTestable(), findsOneWidget);
+ expect(app.environmentReadiness.mode, EnvironmentSetupMode.manual);
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ });
+
+ testWidgets('setup details can expand and copy without hiding Retry', (
+ tester,
+ ) async {
+ final provisioner = _Provisioner();
+ final diagnostics = List.generate(40, (i) => 'Installer output line $i');
+ final app = _app(provisioner)
+ ..environmentReadiness = _review.copyWith(
+ phase: EnvironmentSetupPhase.failed,
+ failure: const EnvironmentFailure(
+ title: 'Could not install Harness',
+ detail: 'Check your connection, then retry setup.',
+ ),
+ output: diagnostics,
+ );
+ String? clipboard;
+ tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(
+ SystemChannels.platform,
+ (call) async {
+ if (call.method == 'Clipboard.setData') {
+ clipboard = (call.arguments as Map)['text'] as String;
+ }
+ return null;
+ },
+ );
+ addTearDown(
+ () => tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(
+ SystemChannels.platform,
+ null,
+ ),
+ );
+ await _mount(tester, app);
+ expect(find.byType(SelectableText), findsNothing);
+ await tester.ensureVisible(find.text('Setup details'));
+ await tester.tap(find.text('Setup details'));
+ await tester.pump();
+ expect(find.byType(SelectableText), findsOneWidget);
+ expect(find.text('Retry').hitTestable(), findsOneWidget);
+ await tester.tap(find.text('Copy diagnostics'));
+ await tester.pump();
+ expect(clipboard, diagnostics.join('\n'));
+ expect(find.text('Copied'), findsOneWidget);
+ expect(provisioner.attempts, isEmpty);
+ await tester.pump(const Duration(milliseconds: 1500));
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ });
+
+ for (final scale in [1.0, 2.0]) {
+ testWidgets('setup actions stay visible at minimum size with $scale text', (
+ tester,
+ ) async {
+ final provisioner = _Provisioner();
+ final app = _app(provisioner);
+ addTearDown(app.dispose);
+ await _mount(tester, app, textScale: scale);
+ expect(find.text('Install 4 tools').hitTestable(), findsOneWidget);
+ expect(provisioner.attempts, isEmpty);
+ app.environmentReadiness = _review.copyWith(
+ phase: EnvironmentSetupPhase.failed,
+ failure: const EnvironmentFailure(
+ title: 'Could not install Harness',
+ detail: 'Check your connection, then retry setup.',
+ ),
+ output: List.generate(40, (i) => 'Installer output line $i'),
+ );
+ app.notifyListeners();
+ await tester.pump();
+ expect(find.text('Retry').hitTestable(), findsOneWidget);
+ expect(find.text('Switch to Manual').hitTestable(), findsOneWidget);
+ expect(tester.takeException(), isNull);
+ });
+ }
+
+ testWidgets('Enter installs and retries once before reaching sign-in', (
+ tester,
+ ) async {
+ final provisioner = _Provisioner();
+ final app = _app(provisioner);
+ await _mount(tester, app);
+ expect(provisioner.attempts, isEmpty);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(provisioner.attempts, hasLength(1));
+ expect(provisioner.attempts.single.install, isTrue);
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(provisioner.attempts, hasLength(1));
+ provisioner.attempts.single.finish(
+ _review.copyWith(
+ phase: EnvironmentSetupPhase.failed,
+ failure: const EnvironmentFailure(
+ title: 'Could not install Harness',
+ detail: 'Check your connection, then retry setup.',
+ ),
+ ),
+ );
+ await tester.pump();
+ await tester.pump();
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(provisioner.attempts, hasLength(2));
+ provisioner.attempts.last.finish(
+ const EnvironmentReadiness(
+ steps: {
+ EnvironmentStep.clipboard: EnvironmentStepStatus.notApplicable,
+ EnvironmentStep.tmux: EnvironmentStepStatus.ready,
+ EnvironmentStep.harness: EnvironmentStepStatus.ready,
+ },
+ phase: EnvironmentSetupPhase.ready,
+ systemReady: true,
+ ),
+ );
+ await tester.pump();
+ await tester.pump();
+ expect(find.text('Sign-in reached'), findsOneWidget);
+ expect(provisioner.attempts.map((attempt) => attempt.install), [
+ true,
+ true,
+ ]);
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ });
+}
diff --git a/docs/harness-v2-appearance-onboarding.md b/docs/harness-v2-appearance-onboarding.md
index 4b7978577..48bc34b80 100644
--- a/docs/harness-v2-appearance-onboarding.md
+++ b/docs/harness-v2-appearance-onboarding.md
@@ -95,6 +95,32 @@ were inspected at 1280×800 and at 880×560 with 2× text. These are synthetic U
checks; first-install/provider-sign-in observation and measured time to a useful
real agent remain release qualification work.
+## First-launch installation
+
+The tools screen before sign-in keeps its primary action outside the scrollable
+body. **Install N tools**, **Retry**, **Check again** and **Continue to sign in**
+stay visible at the minimum 880×560 window size and with 2× text. The required
+tool list is denser, larger text stacks its details, and the footer states what
+comes next. Verbose output starts collapsed under **Setup details**; Copy
+diagnostics remains available, and expanded output stays selectable.
+
+Enter activates the current step and can retry after a failed installation.
+Repeated Enter while work is pending does not start a duplicate attempt. Users
+who explicitly focus manual controls or details retain that focus through
+asynchronous updates. Manual Retry now checks installed tools without installing
+anything; the previous callback entered the automatic path, which returned
+without doing anything in manual mode. Manual review uses **Check again**.
+
+The 59 affected workflow checks and one real-font render check pass. Six new
+regressions cover visibility, keyboard recovery, manual-mode focus and retry,
+and diagnostics copying. Review, CLI-only, manual, failed, Terminal handoff and
+expanded-details screens were rendered at minimum size, including 2× review
+and failure states. Analysis has no errors/warnings and 14 existing infos; the
+normal arm64 Release build succeeds. Provisioning and authentication use fakes
+in these checks. Actual dependency installation, administrator prompts and
+provider sign-in still need first-use observation. Native benchmarking remains
+deferred at the user's request.
+
## Browser sign-in recovery
Sign-in keeps its workspace example and action in the same card through CLI
diff --git a/docs/harness-v2-handoff.md b/docs/harness-v2-handoff.md
index eab92aec9..9cd80e384 100644
--- a/docs/harness-v2-handoff.md
+++ b/docs/harness-v2-handoff.md
@@ -55,6 +55,14 @@ and return keyboard focus to the retry action. The public GitHub clone service
was also exercised directly in a disposable folder; private access and the
native chooser still need first-use observation.
+First-launch installation now keeps **Install**, **Retry** and **Check again**
+visible while the tool list and diagnostics scroll. Enter activates the current
+step, including recovery after failure; explicit manual/detail focus is retained.
+Manual Retry performs a read-only check instead of silently doing nothing.
+Verbose output is optional under **Setup details**, with Copy diagnostics still
+available. This changes the first-launch tools screen before sign-in; it does not
+add another step to New agent or the common empty-swarm page.
+
## Goal
Build the best everyday workspace for people directing persistent AI agents:
@@ -79,7 +87,20 @@ Research must lead to justified improvements, not feature accumulation.
- Continue on **`main`**, tracking `origin/main`. The user's latest instruction
is to work, commit, and push directly on main from now on. This supersedes
the earlier preference for creating a fresh feature branch after each merge.
-- Clone recovery passes 49 affected workflow checks and one real-font render
+- First-launch installation passes 59 affected workflow checks and one real-font
+ render check (60 total). Six new regressions cover minimum-size/2× text action
+ visibility, Enter/retry, manual-mode focus and read-only retry, and diagnostics.
+ The original action-visibility and Enter regressions failed before the fix.
+ Analysis has zero errors/warnings and 14 existing infos. The normal arm64
+ Release build succeeds at
+ `/private/tmp/harness-setup-release/Build/Products/Release/Harness.app`.
+ Logs: `/private/tmp/harness-setup-final-{tests,analyze}.log` and
+ `/private/tmp/harness-setup-release.log`. The app was not launched. These are
+ fake-provisioner and rendered-screen checks, not a real fresh install or
+ provider sign-in. Main was fast-forwarded through the team's `e14d0fb`;
+ incoming release-script and dial-firmware changes leave the tested desktop
+ application sources unchanged. Benchmarking remains deferred.
+- **`cb92d2a`** adds clone recovery, passing 49 affected workflow checks and one real-font render
check at 880×560 with normal/2× text. The original cancellation and keyboard
retry regressions failed before the fix; visual review then exposed the hidden
large-text error. Analysis has zero errors/warnings and 14 existing infos.
diff --git a/docs/harness-v2-progress.md b/docs/harness-v2-progress.md
index e48c94701..6538c6518 100644
--- a/docs/harness-v2-progress.md
+++ b/docs/harness-v2-progress.md
@@ -6,6 +6,22 @@ Updated 2026-09-14 after integrating the continuation into main. This is a worki
## Continue directly on main
+- Fixed first-launch installation at minimum window size: Install/Retry/Check
+ again stay visible outside the scrollable tool list, and Enter can start or
+ retry the current step. Manual Retry now performs a read-only check instead of
+ calling the automatic path that returned without doing anything. Explicit
+ method/detail focus stays put. Shorter copy, denser required-tool rows and
+ optional **Setup details** keep the next action clear; expanded diagnostics
+ remain selectable and copyable. The affected suite passes 59 workflow checks
+ plus one real-font render check at 880×560 with normal/2× text. Analysis has
+ zero errors/warnings and 14 existing infos. The normal arm64 Release build
+ succeeds at `/private/tmp/harness-setup-release/Build/Products/Release/Harness.app`.
+ Logs: `/private/tmp/harness-setup-final-{tests,analyze}.log` and
+ `/private/tmp/harness-setup-release.log`. Verification uses fake provisioning;
+ no tools were installed and no real sign-in ran. First-install observation
+ remains open, and benchmarking stays deferred. Main preserves the team's
+ changes through `e14d0fb`; incoming release-script/dial work does not alter the
+ tested desktop application sources.
- Fixed Clone repository cancellation and keyboard recovery. Escape now uses
Cancel and waits for cleanup; a late successful clone cannot advance a
cancelled flow. Outside clicks leave an active clone running. Failed clones