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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import '../core/home_dir.dart';
import 'package:flutter/foundation.dart' show kDebugMode;
import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'dart:typed_data';
import 'package:path/path.dart' as p;
import '../core/harness_cli_runner.dart';
import '../core/hidden_process.dart';
import '../core/staging_build.dart';
import '../core/windows_layout.dart';
import '../update/desktop_updater.dart' show semverGt;
/// The CLI-only installer contract for callers that already own host setup.
/// Desktop verifies tmux, the active Linux clipboard helper and the rest of
/// what the CLI runs before reaching this command, then performs its own
/// complete verification again after Harness lands.
const String kHarnessDesktopInstallCommand =
'curl -fsSL https://cdn.autonomous.ai/harness/cli/install.sh | '
'/bin/sh -s -- --desktop';
/// The same installer's host half — tmux and what the CLI runs beside it.
/// On macOS this is how tmux is obtained, in-app: Homebrew's if Homebrew is
/// already there, else the managed build downloaded into `~/.harness/runtime`
/// (no compiler, no package manager, no password). One ladder, implemented
/// once, in the script.
const String kHarnessHostSetupCommand =
'curl -fsSL https://cdn.autonomous.ai/harness/cli/install.sh | '
'/bin/sh -s -- --host';
const int _linuxClockSyncFailureExitCode = 31;
const int _linuxAptUpdateFailureExitCode = 32;
/// The oldest Harness CLI this app runs against: 0.2.48 is the first that
/// starts its daemon for this computer without a sign-in, which the app's
/// first run relies on. Raise it when the app starts needing a newer daemon.
const kMinimumHarnessCliVersion = '0.2.48';
/// The oldest Harness CLI this app runs against on Windows: the first release
/// with Windows support (sub-project B). Every CLI `install.ps1` can lay down
/// is at least this, so on Windows the check only turns down a stale
/// development build. Raise it alongside [kMinimumHarnessCliVersion].
const kMinimumWindowsHarnessCliVersion = '0.4.20';
/// `--dart-define=HARNESS_INSTALL_PS1_URL=…` replaces the whole installer
/// address, for tests against a fake CDN.
const String _installScriptOverride = String.fromEnvironment(
'HARNESS_INSTALL_PS1_URL',
);
/// Where Windows setup downloads `install.ps1` from (spec §1.4).
String harnessInstallScriptUrl({
String override = _installScriptOverride,
bool staging = kHarnessStagingBuild,
}) {
if (override.isNotEmpty) return override;
return staging
? 'https://cdn.autonomous.ai/harness/staging/cli/install.ps1'
: 'https://cdn.autonomous.ai/harness/cli/install.ps1';
}
/// Whether [url] may go into the installer's PowerShell command: `https`, or
/// `http` to this computer (a test's fake CDN), with none of the characters
/// PowerShell would read as code inside the single quotes it is put in.
bool isTrustedInstallScriptUrl(String url) {
if (!RegExp(r"^[A-Za-z0-9._~:/?#\[\]@!&()*+,;=%-]+$").hasMatch(url)) {
return false;
}
final uri = Uri.tryParse(url);
if (uri == null || uri.host.isEmpty) return false;
return uri.scheme == 'https' ||
(uri.scheme == 'http' &&
(uri.host == '127.0.0.1' || uri.host == 'localhost'));
}
/// The `-Command` text: B's `install.ps1 -Desktop` line, plus what a hidden
/// run needs.
/// - PowerShell writes UTF-8, so a profile such as `C:\Users\Nguyễn Văn A'`
/// reaches the setup log intact (it would write the OEM code page).
/// - `-ErrorAction Stop` makes a failed download fail the command, where
/// `iex` of nothing would succeed.
/// - `exit $LASTEXITCODE`: under `iex` the script sets `$LASTEXITCODE` rather
/// than exiting, and `-Command` alone would exit 0 either way.
/// The address is in single quotes, and [isTrustedInstallScriptUrl] keeps
/// quotes out of it. No profile path is here: install.ps1 reads
/// `$env:USERPROFILE` itself.
String windowsInstallCommand(String url) =>
r'[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false); '
'iex "& { \$(irm \'$url\' -ErrorAction Stop) } -Desktop"; '
r'exit $LASTEXITCODE';
/// `powershell.exe`'s arguments for [windowsInstallCommand]. Dart quotes each
/// one for `CreateProcessW`; no shell re-parses them.
List<String> windowsInstallArguments(String url) => [
'-NoProfile',
'-NonInteractive',
'-ExecutionPolicy',
'Bypass',
'-Command',
windowsInstallCommand(url),
];
/// What a person pastes into PowerShell to install by hand. Quote the trusted
/// address as in [windowsInstallCommand], so URL punctuation stays literal.
String windowsManualInstallCommand(String url) =>
'iex "& { \$(irm \'$url\') } -Desktop"';
/// Windows PowerShell by its full path. A bare `powershell.exe` is looked for
/// in the working folder before System32.
String windowsPowerShellPath(Map<String, String> environment) {
var root = '';
for (final entry in environment.entries) {
if (entry.key.toUpperCase() == 'SYSTEMROOT') root = entry.value;
}
if (root.isEmpty) root = r'C:\Windows';
return '$root\\System32\\WindowsPowerShell\\v1.0\\powershell.exe';
}
const int _linuxAptInstallFailureExitCode = 33;
const String _linuxClockRepairCommand =
'if command -v chronyc >/dev/null 2>&1; then '
'sudo chronyc makestep; else sudo timedatectl set-ntp true && '
'sudo systemctl restart systemd-timesyncd; fi';
/// What Harness Desktop RUNS — the only things readiness is about. Everything
/// else the setup screen ever mentions (Homebrew, the Apple developer tools,
/// apt, curl) is a way of obtaining one of these, appears only in the plan
/// for a step that is missing, and is never probed while the step is ready.
enum EnvironmentStep {
/// The native image-paste helper of the active Linux display (`wl-copy` /
/// `xclip`). Not applicable on macOS or a headless Linux host.
clipboard,
/// The managed Node runtime and `cli.js` under `~/.harness`.
harness,
/// The terminal backend: `tmux`, and on Linux the `ps` the CLI's process
/// liveness and agent discovery run beside it. On Windows this step is B's
/// terminal host, harness-pty.exe, and there is no ps.
tmux;
/// Harness Desktop is only ready when every command in this list works.
bool get isRequired => true;
}
enum EnvironmentSetupPhase {
preflight,
review,
chooseMethod,
installing,
waitingForTerminal,
verifying,
ready,
failed,
}
enum EnvironmentSetupMode { automatic, manual }
/// Identifies which host setup owns a visible Terminal handoff. Only Linux has
/// one now — apt needs a password on a real tty; on macOS nothing does since
/// tmux comes from Homebrew-if-present or the managed download. Linux can wait
/// on the clipboard helper even when tmux itself is already ready, so a
/// resumed failure must not always be attributed to the tmux row.
enum EnvironmentTerminalSetup { linuxHost }
class EnvironmentFailure {
final EnvironmentStep? step;
final String title;
final String detail;
final String? command;
final int? exitCode;
const EnvironmentFailure({
this.step,
required this.title,
required this.detail,
this.command,
this.exitCode,
});
}
/// install.ps1's failure in its own words (B §1: "Errors are printed as a
/// sentence a first-time user understands, with the step that failed"):
/// `Harness could not be installed. The step that failed: <step>.`, with the
/// reason on the next line. Null when the installer succeeded.
EnvironmentFailure? windowsInstallFailure(
ProcessResult result, {
required String manualCommand,
}) {
final lines = const LineSplitter().convert(
'${result.stdout}\n${result.stderr}',
);
final sentence = RegExp(
r'^Harness could not be installed\. The step that failed: (.+)\.$',
);
for (var i = 0; i < lines.length; i++) {
final match = sentence.firstMatch(lines[i].trim());
if (match == null) continue;
final step = match.group(1)!;
final reason = lines
.skip(i + 1)
.map((line) => line.trim())
.firstWhere((line) => line.isNotEmpty, orElse: () => '');
return EnvironmentFailure(
step: step == 'Installing the terminal host'
? EnvironmentStep.tmux
: EnvironmentStep.harness,
title: 'Harness could not be installed',
detail: reason.isEmpty
? 'The step that failed: $step.'
: 'The step that failed: $step. $reason',
command: manualCommand,
exitCode: result.exitCode,
);
}
if (result.exitCode == 0) return null;
final output = '${result.stderr}\n${result.stdout}'.trim();
return EnvironmentFailure(
step: EnvironmentStep.harness,
title: 'Harness could not be installed',
detail:
'The installer exited ${result.exitCode}: '
'${output.length <= 700 ? output : output.substring(output.length - 700)}',
command: manualCommand,
exitCode: result.exitCode,
);
}
enum EnvironmentStepStatus {
pending,
running,
ready,
needsTerminal,
failed,
/// This host has no native clipboard to prepare (for example, headless
/// Linux). Unlike [unavailable], this is a satisfied, non-blocking state.
notApplicable,
/// The host does not support this dependency. All current steps are required,
/// so this status remains blocking.
unavailable,
}
/// One thing setup will do to obtain a missing [step], in the order it will
/// be done. Computed by the provisioner from what it actually probed, so the
/// screen renders it rather than inferring it — a plan that names Xcode is a
/// plan for a computer where Homebrew was found missing, never a guess.
class EnvironmentPlanItem {
final EnvironmentStep step;
final String title;
final String detail;
final String command;
/// Needs a real tty for a password or an OS dialog, so automatic setup
/// hands it to a visible Terminal window.
final bool requiresTerminal;
/// Linux: the apt packages this item installs, so a resumed Terminal
/// handoff can name what is still missing without re-probing.
final List<String> packages;
const EnvironmentPlanItem({
required this.step,
required this.title,
required this.detail,
required this.command,
this.requiresTerminal = false,
this.packages = const [],
});
/// The items a plan is assembled from, written down once. tmux on macOS
/// is a single in-app step whichever way it is obtained; the detail says
/// which, because that is the one thing the person reading the plan may
/// care about.
static const tmuxViaHomebrew = EnvironmentPlanItem(
step: EnvironmentStep.tmux,
title: 'tmux',
detail: 'Installs with the Homebrew already on this Mac',
command: kHarnessHostSetupCommand,
);
static const tmuxManaged = EnvironmentPlanItem(
step: EnvironmentStep.tmux,
title: 'tmux',
detail: 'Downloads a verified build into ~/.harness/runtime',
command: kHarnessHostSetupCommand,
);
static const harnessCli = EnvironmentPlanItem(
step: EnvironmentStep.harness,
title: 'Managed Node 20+ & Harness CLI',
detail: '~/.harness only',
command: kHarnessDesktopInstallCommand,
);
/// Windows: one `install.ps1 -Desktop` run lays down both the CLI and the
/// terminal host, so either item alone runs the same command.
static final windowsHarnessCli = EnvironmentPlanItem(
step: EnvironmentStep.harness,
title: 'Managed Node 20+ & Harness CLI',
detail: r'%USERPROFILE%\.harness only',
command: windowsManualInstallCommand(harnessInstallScriptUrl()),
);
/// The terminal step on Windows: B's terminal host, `harness-pty.exe`.
static final windowsTerminalHost = EnvironmentPlanItem(
step: EnvironmentStep.tmux,
title: 'Terminal host',
detail: r'harness-pty.exe, into %USERPROFILE%\.harness\runtime\pty',
command: windowsManualInstallCommand(harnessInstallScriptUrl()),
);
}
class EnvironmentReadiness {
final Map<EnvironmentStep, EnvironmentStepStatus> steps;
final String? message;
final List<String> output;
final EnvironmentSetupPhase phase;
final EnvironmentSetupMode? mode;
final EnvironmentFailure? failure;
final String? terminalLogPath;
final String? terminalResultPath;
final EnvironmentTerminalSetup? terminalSetup;
/// What setup will install, in order — empty when everything runs.
final List<EnvironmentPlanItem> plan;
const EnvironmentReadiness({
required this.steps,
this.message,
this.output = const [],
this.phase = EnvironmentSetupPhase.preflight,
this.mode,
this.failure,
this.terminalLogPath,
this.terminalResultPath,
this.terminalSetup,
this.plan = const [],
});
factory EnvironmentReadiness.initial() => EnvironmentReadiness(
steps: {
for (final step in EnvironmentStep.values)
step: EnvironmentStepStatus.pending,
},
);
bool get isReady =>
phase == EnvironmentSetupPhase.ready &&
failure == null &&
_requiredStepsReady;
bool get _requiredStepsReady => EnvironmentStep.values.every(
(step) =>
steps[step] == EnvironmentStepStatus.ready ||
steps[step] == EnvironmentStepStatus.notApplicable,
);
/// Every step but the Harness CLI itself is satisfied — the point at which
/// automatic setup can run the CLI installer without another host prompt.
bool get hostReady => steps.entries.every(
(entry) =>
entry.key == EnvironmentStep.harness ||
entry.value == EnvironmentStepStatus.ready ||
entry.value == EnvironmentStepStatus.notApplicable,
);
bool get needsTerminal =>
phase == EnvironmentSetupPhase.waitingForTerminal ||
steps.values.any(
(status) => status == EnvironmentStepStatus.needsTerminal,
);
/// The plan items serving one step, in order.
List<EnvironmentPlanItem> planFor(EnvironmentStep step) =>
plan.where((item) => item.step == step).toList();
/// The plan with one step's items done.
List<EnvironmentPlanItem> planWithout(EnvironmentStep step) =>
plan.where((item) => item.step != step).toList();
EnvironmentReadiness copyWith({
Map<EnvironmentStep, EnvironmentStepStatus>? steps,
String? message,
List<String>? output,
EnvironmentSetupPhase? phase,
EnvironmentSetupMode? mode,
EnvironmentFailure? failure,
String? terminalLogPath,
String? terminalResultPath,
EnvironmentTerminalSetup? terminalSetup,
List<EnvironmentPlanItem>? plan,
bool clearFailure = false,
bool clearTerminalHandoff = false,
}) => EnvironmentReadiness(
steps: steps ?? this.steps,
message: message ?? this.message,
output: output ?? this.output,
phase: phase ?? this.phase,
mode: mode ?? this.mode,
failure: clearFailure ? null : failure ?? this.failure,
terminalLogPath: clearTerminalHandoff
? null
: terminalLogPath ?? this.terminalLogPath,
terminalResultPath: clearTerminalHandoff
? null
: terminalResultPath ?? this.terminalResultPath,
terminalSetup: clearTerminalHandoff
? null
: terminalSetup ?? this.terminalSetup,
plan: plan ?? this.plan,
);
}
typedef ProcessRunner = Future<ProcessResult> Function(
String executable,
List<String> arguments, {
Map<String, String>? environment,
});
typedef TerminalLauncher = Future<void> Function(String scriptPath);
typedef ProcessStarter = Future<Process> Function(
String executable,
List<String> arguments, {
Map<String, String>? environment,
});
class _EnvironmentProbeTimeout implements Exception {
const _EnvironmentProbeTimeout(this.label, this.step);
final String label;
final EnvironmentStep? step;
@override
String toString() => 'The check for $label did not finish.';
}
Future<ProcessResult> _defaultRun(
String executable,
List<String> arguments, {
Map<String, String>? environment,
}) => runHidden(executable, arguments, environment: environment);
Future<Process> _defaultStart(
String executable,
List<String> arguments, {
Map<String, String>? environment,
}) => startHidden(executable, arguments, environment: environment);
/// macOS opens a real Terminal.app window. Linux has no single canonical
/// terminal, so this tries the Debian/Ubuntu `update-alternatives` target
/// first, then the two most common emulators, and gives up only if none of
/// them exist on the box.
Future<void> _defaultOpenTerminal(String scriptPath) async {
if (Platform.isMacOS) {
await Process.start('/usr/bin/open', ['-a', 'Terminal', scriptPath]);
return;
}
final candidates = <List<String>>[
['x-terminal-emulator', '-e', scriptPath],
['gnome-terminal', '--', scriptPath],
['xterm', '-e', scriptPath],
];
for (final candidate in candidates) {
try {
await Process.start(candidate.first, candidate.skip(1).toList());
return;
} on ProcessException {
continue;
}
}
throw StateError(
'Could not find a terminal emulator to launch (tried x-terminal-emulator, '
'gnome-terminal, xterm)',
);
}
/// Prepares the only system dependencies required by the desktop transport.
///
/// Node lives beneath [harnessHome] rather than in Homebrew/nvm/PATH. The
/// CLI launcher is written against that exact binary, so launching Harness
/// from Finder and from Terminal has identical runtime behavior.
class EnvironmentProvisioner {
final Directory harnessHome;
final ProcessRunner _run;
final ProcessStarter? _start;
final TerminalLauncher _openTerminal;
final bool _isMacOS;
final bool _isLinux;
final bool _isWindows;
final Map<String, String> _platformEnvironment;
final String _windowsInstallScriptUrl;
final Duration probeTimeout;
EnvironmentProvisioner({
Directory? harnessHome,
ProcessRunner? run,
ProcessStarter? start,
TerminalLauncher? openTerminal,
bool? isMacOS,
bool? isLinux,
bool? isWindows,
Map<String, String>? platformEnvironment,
String? windowsInstallScriptUrl,
this.probeTimeout = const Duration(seconds: 10),
}) : harnessHome = harnessHome ?? Directory(_defaultHarnessHome()),
_run = run ?? _defaultRun,
_start = start ?? (run == null ? _defaultStart : null),
_openTerminal = openTerminal ?? _defaultOpenTerminal,
_isMacOS = isMacOS ?? Platform.isMacOS,
_isLinux = isLinux ?? Platform.isLinux,
_isWindows = isWindows ?? Platform.isWindows,
_platformEnvironment = platformEnvironment ?? Platform.environment,
_windowsInstallScriptUrl =
windowsInstallScriptUrl ?? harnessInstallScriptUrl();
/// The current user's home: USERPROFILE on Windows, HOME elsewhere.
/// A launch from Explorer has no HOME at all.
static String? userHome() => maybeHomeDir();
static String _defaultHarnessHome() {
final home = userHome();
if (home == null) {
throw StateError('Could not resolve the current user home directory');
}
return '$home${Platform.pathSeparator}.harness';
}
/// Checks the complete environment, and mutates it only when [install] is explicitly true.
Future<EnvironmentReadiness> ensureReady({
required void Function(EnvironmentReadiness value) onProgress,
EnvironmentReadiness? resumeFrom,
bool install = true,
EnvironmentSetupMode? mode,
}) async {
final retryingFailedSetup =
install && resumeFrom?.phase == EnvironmentSetupPhase.failed;
var state = (resumeFrom ?? EnvironmentReadiness.initial()).copyWith(
phase: install
? EnvironmentSetupPhase.installing
: EnvironmentSetupPhase.preflight,
mode: mode,
clearFailure: true,
clearTerminalHandoff: retryingFailedSetup,
);
void emit({
EnvironmentStep? step,
EnvironmentStepStatus? status,
String? message,
String? output,
EnvironmentSetupPhase? phase,
EnvironmentFailure? failure,
String? terminalLogPath,
String? terminalResultPath,
EnvironmentTerminalSetup? terminalSetup,
List<EnvironmentPlanItem>? plan,
}) {
final next = Map<EnvironmentStep, EnvironmentStepStatus>.from(
state.steps,
);
if (step != null && status != null) next[step] = status;
final lines = [...state.output];
if (output != null && output.trim().isNotEmpty) {
if (output.startsWith('Terminal log:\n')) {
lines.removeWhere((line) => line.startsWith('Terminal log:\n'));
}
lines.add(output.trim());
if (lines.length > 200) lines.removeRange(0, lines.length - 200);
}
state = EnvironmentReadiness(
steps: next,
message: message ?? state.message,
output: lines,
phase: phase ?? state.phase,
mode: mode ?? state.mode,
failure: failure ?? state.failure,
terminalLogPath: terminalLogPath ?? state.terminalLogPath,
terminalResultPath: terminalResultPath ?? state.terminalResultPath,
terminalSetup: terminalSetup ?? state.terminalSetup,
plan: plan ?? state.plan,
);
onProgress(state);
}
// One read-only look at the computer, reported step by step, with the
// plan it implies. Called for the pre-flight and again for the final
// verification, so both answer the same question the same way.
Future<_HostProbe> probeAndReport() async {
final probe = await _probe();
emit(
step: EnvironmentStep.tmux,
status: probe.terminalReady
? EnvironmentStepStatus.ready
: EnvironmentStepStatus.failed,
message: probe.tmuxMessage,
output: probe.tmuxOutput,
);
emit(
step: EnvironmentStep.clipboard,
status: !probe.clipboardApplicable
? EnvironmentStepStatus.notApplicable
: probe.clipboardRuns
? EnvironmentStepStatus.ready
: EnvironmentStepStatus.failed,
message: probe.clipboardApplicable
? probe.clipboardRuns
? 'Native image clipboard is ready.'
: '${probe.clipboardPackage} is required for native image paste.'
: _isLinux
? 'Native image clipboard is not applicable on a headless Linux host.'
: null,
output: probe.clipboardApplicable
? probe.clipboardRuns
? '✓ native image clipboard · ${probe.clipboardCommand}'
: '✗ native image clipboard · ${probe.clipboardCommand}'
: _isLinux
? '– native image clipboard N/A (headless)'
: null,
);
emit(
step: EnvironmentStep.harness,
status: probe.harnessRuns
? EnvironmentStepStatus.ready
: EnvironmentStepStatus.failed,
message: probe.harnessRuns
? 'Harness CLI and managed Node are ready.'
: _harnessOutdated != null
? 'Harness CLI $_harnessOutdated is out of date; this app needs '
'$_minimumCliVersion or newer.'
: 'Harness CLI or its managed Node runtime is missing.',
output: probe.harnessRuns
? '✓ managed Node >= 20 · harness version'
: _harnessOutdated != null
? '✗ harness $_harnessOutdated < $_minimumCliVersion'
: '✗ managed Node >= 20 · harness version',
plan: probe.plan,
);
return probe;
}
try {
final previousTerminalLog = state.terminalLogPath;
var previousTerminalLogText = '';
EnvironmentTerminalSetup? completedTerminalSetup;
if (previousTerminalLog != null) {
try {
final recent = await _readTerminalLogTail(previousTerminalLog);
previousTerminalLogText = recent.text;
final snapshot =
'Terminal log:\n'
'${recent.truncated ? '[Earlier output omitted. Full log: $previousTerminalLog]\n' : ''}'
'${recent.text.trim()}';
if (recent.text.trim().isNotEmpty &&
!state.output.contains(snapshot)) {
emit(output: snapshot);
}
} on FileSystemException {
// The terminal may not have created its log yet.
}
}
final previousTerminalResult = state.terminalResultPath;
var terminalResultPending = false;
if (previousTerminalResult != null) {
// Missing, unreadable, or partially written results are still pending.
// Only a complete exit code can finish the handoff; live probes below
// can independently establish that the required tools are ready.
terminalResultPending = true;
if (!await File(previousTerminalResult).exists()) {
// `terminal.exit` is a handoff hint, not the source of truth. Some
// Linux terminal emulators keep the launched shell/window alive after
// apt has already finished, and an interrupted EXIT trap can omit the
// file entirely. Continue into the read-only command probes below so
// the 5-second poll (and the user's Recheck button) can observe that
// the host is actually ready instead of waiting forever for a file a
// cold app launch does not need either.
emit(
message:
state.message ?? 'Complete the visible prompts in Terminal.',
phase: EnvironmentSetupPhase.waitingForTerminal,
);
}
try {
final exitCode = int.tryParse(
(await File(previousTerminalResult).readAsString()).trim(),
);
if (exitCode != null) terminalResultPending = false;
if (exitCode != null && exitCode != 0) {
// The only Terminal handoff left is Linux's apt transaction.
final clipboardFailed =
state.steps[EnvironmentStep.clipboard] ==
EnvironmentStepStatus.needsTerminal;
final tmuxFailed =
state.steps[EnvironmentStep.tmux] ==
EnvironmentStepStatus.needsTerminal;
if (clipboardFailed) {
emit(
step: EnvironmentStep.clipboard,
status: EnvironmentStepStatus.failed,
);
}
if (tmuxFailed) {
emit(
step: EnvironmentStep.tmux,
status: EnvironmentStepStatus.failed,
);
}
final classifiedFailure = _classifiedLinuxPackageFailure(
exitCode,
previousTerminalLogText,
);
emit(
message: 'The Terminal setup exited with code $exitCode.',
phase: EnvironmentSetupPhase.failed,
failure: EnvironmentFailure(
step: clipboardFailed
? EnvironmentStep.clipboard
: tmuxFailed
? EnvironmentStep.tmux
: null,
title:
classifiedFailure?.title ??
'System package installation failed',
detail:
classifiedFailure?.detail ??
'Terminal exited with code $exitCode. Review the setup details below.',
command:
classifiedFailure?.command ??
await _linuxHostManualCommand(_aptPackagesOf(state.plan)),
exitCode: exitCode,
),
);
return state;
}
if (exitCode == 0) completedTerminalSetup = state.terminalSetup;
} on FileSystemException {
// The result can disappear between exists() and readAsString(). The
// live dependency probes below remain the authoritative fallback.
}
}
onProgress(state);
if (!_isMacOS && !_isLinux && !_isWindows) {
emit(
step: EnvironmentStep.harness,
status: EnvironmentStepStatus.failed,
message: 'Automatic environment setup is currently available on macOS and Linux only.',
phase: EnvironmentSetupPhase.failed,
);
return state;
}
// The one thing every step needs and no plan can install.
if (!await _hasWritableHome()) {
final failure = EnvironmentFailure(
title: 'Home directory is not writable',
detail: _isWindows
? r'Harness needs to write %USERPROFILE%\.harness.'
: 'Harness needs to write ~/.harness and ~/.local/bin.',
);
emit(
message: failure.detail,
phase: EnvironmentSetupPhase.failed,
failure: failure,
);
return state;
}
var probe = await probeAndReport();
if (state._requiredStepsReady) {
emit(
message: 'All required tools passed verification.',
phase: EnvironmentSetupPhase.ready,
);
return state;
}
if (!install) {
if (terminalResultPending && !state.hostReady) {
emit(
message:
state.message ?? 'Complete the visible prompts in Terminal.',
phase: EnvironmentSetupPhase.waitingForTerminal,
);
return state;
}
if (completedTerminalSetup != null && !state.hostReady) {
emit(
message: 'The Linux host dependency install finished, but verification still found missing packages.',
phase: EnvironmentSetupPhase.failed,
failure: EnvironmentFailure(
step: !probe.terminalReady
? EnvironmentStep.tmux
: !probe.clipboardRuns
? EnvironmentStep.clipboard
: null,
title: 'Host dependency verification failed',
detail:
'Still missing: ${probe.missingHostNames.join(', ')}. Review the Terminal log, then retry when ready.',
command: await _linuxHostManualCommand(probe.aptPackages),
),
);
return state;
}
emit(
message: _isLinux && probe.aptPackages.isNotEmpty
? 'Linux host packages required: ${probe.aptPackages.join(', ')}.'
: 'Review what Harness will install before continuing.',
phase: EnvironmentSetupPhase.review,
);
return state;
}
// Strict dependency order: one host-package transaction (tmux, ps, the
// active clipboard helper and, when the CLI must be downloaded, the
// tools that download it) -> managed Node/Harness.
if (_isLinux && probe.aptPackages.isNotEmpty) {
var packages = probe.aptPackages;
if (!await _hasAptGet()) {
final command = await _linuxHostManualCommand(packages);
emit(
message: 'Automatic Linux package installation supports apt-based distributions only.',
phase: EnvironmentSetupPhase.failed,
failure: EnvironmentFailure(
title: 'Unsupported Linux package manager',
detail:
'Install ${packages.join(', ')} with this distribution\'s package manager, then recheck.',
command: command,
),
);
return state;
}
ProcessResult? backgroundInstall;
if (await _canInstallAptUnattended()) {
for (final step in probe.missingHostSteps) {
emit(step: step, status: EnvironmentStepStatus.running);
}
emit(message: 'Installing Linux system packages…');
try {
backgroundInstall = await _shellStreaming(
_linuxAptInstallCommand(packages, nonInteractiveSudo: true),
onOutput: (line) => emit(
message:
line.contains('Enabling automatic time synchronization')
? 'Synchronizing the system clock before retrying Ubuntu packages…'
: null,
output: line,
),
);
} catch (error) {
emit(output: 'Background Linux package install failed: $error');
}
probe = await probeAndReport();
final classifiedBackgroundFailure = backgroundInstall == null
? null
: _classifiedLinuxPackageFailure(
backgroundInstall.exitCode,
_resultText(backgroundInstall),
);
if (classifiedBackgroundFailure != null) {
emit(
message: classifiedBackgroundFailure.detail,
phase: EnvironmentSetupPhase.failed,
failure: EnvironmentFailure(
step: probe.missingHostSteps.firstOrNull,
title: classifiedBackgroundFailure.title,
detail: classifiedBackgroundFailure.detail,
command: classifiedBackgroundFailure.command,
exitCode: classifiedBackgroundFailure.exitCode,
),
);
return state;
}
if (probe.aptPackages.isEmpty) {
emit(
message: 'Linux system packages are ready.',
output: '✓ Linux host dependencies installed and verified',
);
} else {
if (backgroundInstall != null) {
emit(
output: backgroundInstall.exitCode == 0
? 'apt finished, but Linux host dependencies did not pass verification.'
: 'Background apt install exited ${backgroundInstall.exitCode}: '
'${_resultText(backgroundInstall)}',
);
}
packages = probe.aptPackages;
}
}
if (probe.aptPackages.isNotEmpty) {
final terminal = await _launchLinuxHostSetup(packages);
for (final step in probe.missingHostSteps) {
emit(step: step, status: EnvironmentStepStatus.needsTerminal);
}
emit(
message: 'Complete the visible Linux package prompts in Terminal. Harness never sees your password.',
output: backgroundInstall == null
? 'Terminal opened to install Linux host dependencies.'
: 'Background install was incomplete; Terminal opened to finish Linux host dependencies.',
phase: EnvironmentSetupPhase.waitingForTerminal,
terminalLogPath: terminal.log.path,
terminalResultPath: terminal.result.path,
terminalSetup: EnvironmentTerminalSetup.linuxHost,
);
return state;
}
}
if (_isMacOS && !probe.tmuxRuns) {
// One in-app step whichever rung applies: the installer's host half
// uses the Homebrew already here or downloads the managed build.
// Neither needs a password, so no Terminal window and no waiting.
emit(
step: EnvironmentStep.tmux,
status: EnvironmentStepStatus.running,
message: probe.homebrewInstallsTmux
? 'Installing tmux via Homebrew…'
: 'Downloading the managed tmux…',
);
ProcessResult? installResult;
try {
installResult = await _shellStreaming(
'set -e; $kHarnessHostSetupCommand',
onOutput: (line) => emit(output: line),
);
} catch (error) {
emit(output: 'tmux install failed: $error');
}
if (installResult?.exitCode == 0 && await _hasTmux()) {
emit(
step: EnvironmentStep.tmux,
status: EnvironmentStepStatus.ready,
message: 'tmux is ready.',
output: '✓ tmux installed',
plan: state.planWithout(EnvironmentStep.tmux),
);
} else {
final detail = installResult == null
? 'The tmux installer could not be started.'
: installResult.exitCode == 0
? 'The installer finished, but tmux did not pass verification.'
: 'The tmux installer exited ${installResult.exitCode}: '
'${_resultText(installResult)}';
emit(
step: EnvironmentStep.tmux,
status: EnvironmentStepStatus.failed,
message: detail,
phase: EnvironmentSetupPhase.failed,
failure: EnvironmentFailure(
step: EnvironmentStep.tmux,
title: 'tmux could not be installed',
detail: detail,
command: _manualCommandFor(EnvironmentStep.tmux),
exitCode: installResult?.exitCode,
),
);
return state;
}
}
if (_isWindows) {
if (probe.plan.isNotEmpty) {
// One hidden install.ps1 -Desktop run lays down whatever the plan lists.
final planned = {for (final item in probe.plan) item.step};
for (final step in planned) {
emit(step: step, status: EnvironmentStepStatus.running);
}
emit(message: 'Installing the Harness CLI and terminal host…');
final failure = await _installWindows((line) => emit(output: line));
if (failure != null) {
final failedStep = failure.step ?? EnvironmentStep.harness;
for (final step in {...planned, failedStep}) {
emit(
step: step,
status: step == failedStep
? EnvironmentStepStatus.failed
: EnvironmentStepStatus.pending,
);
}
emit(
message: failure.detail,
phase: EnvironmentSetupPhase.failed,
failure: failure,
);
return state;
}
for (final step in planned) {
emit(step: step, status: EnvironmentStepStatus.ready);
}
emit(output: '✓ Harness CLI and terminal host installed');
}
} else if (!probe.harnessRuns) {
emit(
step: EnvironmentStep.harness,
status: EnvironmentStepStatus.running,
message: 'Installing managed Node and Harness CLI…',
);
await _ensureHarness((line) => emit(output: line));
emit(
step: EnvironmentStep.harness,
status: EnvironmentStepStatus.ready,
output: '✓ Harness CLI ready',
);
}
emit(
message: 'Verifying every required command…',
phase: EnvironmentSetupPhase.verifying,
);
await probeAndReport();
if (!state._requiredStepsReady) {
final failed = state.steps.entries
.where((entry) => entry.value == EnvironmentStepStatus.failed)
.map((entry) => entry.key)
.firstOrNull;
throw StateError(
'${failed?.name ?? 'environment'} did not pass final version verification.',
);
}
emit(message: 'Environment ready.', phase: EnvironmentSetupPhase.ready);
return state;
} catch (error) {
final probeTimeout = error is _EnvironmentProbeTimeout ? error : null;
final failed =
probeTimeout?.step ??
state.steps.entries
.where((entry) => entry.value == EnvironmentStepStatus.running)
.map((entry) => entry.key)
.firstOrNull ??
state.steps.entries
.where((entry) => entry.value == EnvironmentStepStatus.failed)
.map((entry) => entry.key)
.firstOrNull;
emit(
step: failed,
status: EnvironmentStepStatus.failed,
message: install
? 'Environment setup failed: $error'
: 'Computer check failed: $error',
phase: EnvironmentSetupPhase.failed,
failure: EnvironmentFailure(
step: failed,
title: probeTimeout != null
? 'Checking this computer took too long'
: install
? 'Setup could not finish'
: 'Could not check this computer',
detail: probeTimeout != null
? '$error Retry to check again.'
: '$error',
command: probeTimeout != null || !install || failed == null
? null
: _manualCommandFor(failed),
),
);
return state;
}
}
/// Polling a long-running installer must not reread and lay out its complete
/// log every five seconds. Preserve the original file for troubleshooting.
Future<({String text, bool truncated})> _readTerminalLogTail(
String path,
) async {
const maxBytes = 64 * 1024;
const maxLines = 200;
final file = await File(path).open();
try {
final length = await file.length();
final offset = length > maxBytes ? length - maxBytes : 0;
await file.setPosition(offset);
var text = utf8.decode(
await file.read(length - offset),
allowMalformed: true,
);
var truncated = offset > 0;
if (truncated) {
// The byte limit may cut a UTF-8 character or a line. Prefer complete
// lines, but keep the tail if the whole chunk is one long line.
final firstNewline = text.indexOf('\n');
if (firstNewline >= 0 &&
text.substring(firstNewline + 1).trim().isNotEmpty) {
text = text.substring(firstNewline + 1);
}
}
final lines = const LineSplitter().convert(text);
if (lines.length > maxLines) {
text = lines.skip(lines.length - maxLines).join('\n');
truncated = true;
}
return (text: text, truncated: truncated);
} finally {
await file.close();
}
}
/// One read-only look at what this computer runs, and the plan for what it
/// does not — each rung probed only when the one above it is missing.
Future<_HostProbe> _probe() async {
final plan = <EnvironmentPlanItem>[];
if (_isWindows) {
// What install.ps1 -Desktop lays down, and nothing else: there is no
// shell, tmux, ps or clipboard helper to ask about here.
final harnessRuns = await _hasHarness();
final host = await installedTerminalHost(harnessHome);
if (!harnessRuns) plan.add(EnvironmentPlanItem.windowsHarnessCli);
if (host == null) plan.add(EnvironmentPlanItem.windowsTerminalHost);
return _HostProbe(
tmuxRuns: host != null,
clipboardApplicable: false,
clipboardRuns: true,
harnessRuns: harnessRuns,
windows: true,
terminalHostVersion: host?.version,
plan: plan,
);
}
if (_isMacOS) {
final tmuxRuns = await _hasTmux();
var homebrewInstallsTmux = false;
if (!tmuxRuns) {
// Asked only to word the plan: the installer decides the same way.
homebrewInstallsTmux = await _hasHomebrew();
plan.add(
homebrewInstallsTmux
? EnvironmentPlanItem.tmuxViaHomebrew
: EnvironmentPlanItem.tmuxManaged,
);
}
final harnessRuns = await _hasHarness();
if (!harnessRuns) plan.add(EnvironmentPlanItem.harnessCli);
return _HostProbe(
tmuxRuns: tmuxRuns,
clipboardApplicable: false,
clipboardRuns: true,
harnessRuns: harnessRuns,
homebrewInstallsTmux: homebrewInstallsTmux,
plan: plan,
);
}
final tmuxRuns = await _hasTmux();
final psRuns = await _hasCommand('ps');
final clipboardCommand = _linuxClipboardCommand();
final clipboardRuns =
clipboardCommand == null || await _hasCommand(clipboardCommand);
final harnessRuns = await _hasHarness();
final apt = <String>[
if (!tmuxRuns) 'tmux',
if (!psRuns) 'procps',
if (!clipboardRuns) _linuxClipboardPackage()!,
];
if (!harnessRuns) {
// The installer downloads the runtime with these; a minimal Ubuntu can
// lack curl. Asked about only because there is a download coming.
if (!await _hasCommand('curl')) apt.add('curl');
if (!await _hasCommands(_linuxDownloadToolPackages.keys)) {
for (final entry in _linuxDownloadToolPackages.entries) {
if (!await _hasCommand(entry.key)) apt.add(entry.value);
}
}
}
if (apt.isNotEmpty) {
plan.add(
EnvironmentPlanItem(
step: !tmuxRuns || !psRuns
? EnvironmentStep.tmux
: !clipboardRuns
? EnvironmentStep.clipboard
: EnvironmentStep.harness,
title: 'Linux host dependencies',
detail: '${apt.join(', ')} · one apt transaction',
command: 'sudo apt-get install -y ${apt.join(' ')}',
requiresTerminal: true,
packages: apt,
),
);
}
if (!harnessRuns) plan.add(EnvironmentPlanItem.harnessCli);
return _HostProbe(
tmuxRuns: tmuxRuns,
psRuns: psRuns,
clipboardApplicable: clipboardCommand != null,
clipboardRuns: clipboardRuns,
clipboardCommand: clipboardCommand,
clipboardPackage: _linuxClipboardPackage(),
harnessRuns: harnessRuns,
aptPackages: apt,
plan: plan,
);
}
Future<bool> _hasWritableHome() async {
if (_isWindows) return _canCreateFileIn(harnessHome.parent);
final writable = await _probeShell(
'test -w "\$HOME"',
'your home directory',
);
return writable.exitCode == 0;
}
/// `test -w` for Windows, which has no shell to ask: create a file in
/// [folder], the profile, and delete it again.
static Future<bool> _canCreateFileIn(Directory folder) async {
final probe = File(p.join(folder.path, '.harness-write-check-$pid'));
try {
await probe.writeAsString('', flush: true);
await probe.delete();
return true;
} on FileSystemException {
return false;
}
}
Future<bool> _hasCommand(String command) async {
final probe = await _probeShell(
'command -v $command >/dev/null 2>&1',
command,
);
return probe.exitCode == 0;
}
/// All of [commands] resolve. One shell for the lot: `command -v a b`
/// answers "any" in bash, so it is a loop rather than a list.
Future<bool> _hasCommands(Iterable<String> commands) async {
final probe = await _probeShell(
'for c in ${commands.join(' ')}; do command -v "\$c" >/dev/null 2>&1 || exit 1; done',
commands.join(', '),
);
return probe.exitCode == 0;
}
/// What the CLI installer downloads and unpacks the runtime with, by the
/// apt package that provides it. `curl` is probed on its own first, since
/// it is the one a minimal Ubuntu actually lacks.
static const _linuxDownloadToolPackages = <String, String>{
'tar': 'tar',
'sed': 'sed',
'awk': 'gawk',
'sha256sum': 'coreutils',
};
/// Clipboard selection intentionally matches osClipboard.ts: Wayland wins
/// when both display variables exist, X11 is the fallback, and a headless
/// machine has no native clipboard requirement to satisfy.
String? _linuxClipboardCommand() {
if (!_isLinux) return null;
if ((_platformEnvironment['WAYLAND_DISPLAY'] ?? '').isNotEmpty) {
return 'wl-copy';
}
if ((_platformEnvironment['DISPLAY'] ?? '').isNotEmpty) return 'xclip';
return null;
}
String? _linuxClipboardPackage() => switch (_linuxClipboardCommand()) {
'wl-copy' => 'wl-clipboard',
'xclip' => 'xclip',
_ => null,
};
/// The apt packages a plan still owes, for a failure's manual command.
static List<String> _aptPackagesOf(List<EnvironmentPlanItem> plan) =>
plan.expand((item) => item.packages).toSet().toList();
Future<bool> _hasAptGet() async {
final result = await _probeShell(
'command -v apt-get >/dev/null 2>&1',
'apt-get',
);
return result.exitCode == 0;
}
Future<bool> _canInstallAptUnattended() async {
final user = await _probeShell('id -u', 'your user account');
if (user.exitCode == 0 && '${user.stdout}'.trim() == '0') return true;
final sudo = await _probeShell(
'command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1',
'sudo access',
);
return sudo.exitCode == 0;
}
bool _isLinuxClockSkewOutput(String output) {
final normalized = output.toLowerCase();
return normalized.contains('is not valid yet') ||
normalized.contains('certificate is not yet valid');
}
EnvironmentFailure? _classifiedLinuxPackageFailure(
int exitCode,
String output,
) {
if (exitCode == _linuxClockSyncFailureExitCode ||
_isLinuxClockSkewOutput(output)) {
return const EnvironmentFailure(
title: 'System clock could not be synchronized',
detail: 'Ubuntu reports that repository metadata is in the future relative to this computer. Enable automatic time synchronization, confirm the clock is correct, then retry.',
command: _linuxClockRepairCommand,
exitCode: _linuxClockSyncFailureExitCode,
);
}
if (exitCode == _linuxAptUpdateFailureExitCode) {
return const EnvironmentFailure(
title: 'Package repository refresh failed',
detail: 'Ubuntu could not refresh its package indexes, so Harness stopped instead of retrying with stale package data.',
command: 'sudo apt-get update',
exitCode: _linuxAptUpdateFailureExitCode,
);
}
return null;
}
String _linuxAptInstallCommand(
List<String> packages, {
required bool nonInteractiveSudo,
}) {
final names = packages.toSet().join(' ');
final sudoFlag = nonInteractiveSudo ? '-n ' : '';
return '''set -o pipefail
export LC_ALL=C
run_as_root() {
if [ "\$(id -u)" -eq 0 ]; then
"\$@"
elif command -v sudo >/dev/null 2>&1; then
sudo $sudoFlag"\$@"
else
echo 'Installing Linux system packages needs root access, but sudo is unavailable.' >&2
return 126
fi
}
apt_as_root() {
run_as_root env DEBIAN_FRONTEND=noninteractive apt-get "\$@"
}
repair_system_clock() {
if command -v chronyc >/dev/null 2>&1; then
echo 'Repository metadata is ahead of this computer. Enabling automatic time synchronization with chrony…'
run_as_root chronyc online >/dev/null 2>&1 || true
run_as_root chronyc burst 4/4 >/dev/null 2>&1 || true
clock_attempt=0
while :; do
chrony_tracking="\$(chronyc tracking 2>/dev/null || true)"
if printf '%s\n' "\$chrony_tracking" | grep -Eq 'Leap status[[:space:]]*:[[:space:]]*Normal'; then
if run_as_root chronyc makestep; then
echo 'System clock stepped with chrony.'
return 0
fi
echo 'chrony has a synchronized source but could not step the system clock.' >&2
break
fi
clock_attempt=\$((clock_attempt + 1))
if [ "\$clock_attempt" -ge 15 ]; then
echo 'chrony did not obtain a synchronized source within 30 seconds.' >&2
break
fi
sleep 2
done
fi
if ! command -v timedatectl >/dev/null 2>&1; then
echo 'System clock is behind repository metadata, but no usable time synchronization service was found.' >&2
return $_linuxClockSyncFailureExitCode
fi
echo 'Repository metadata is ahead of this computer. Enabling automatic time synchronization…'
run_as_root timedatectl set-ntp true || return $_linuxClockSyncFailureExitCode
if command -v systemctl >/dev/null 2>&1; then
run_as_root systemctl restart systemd-timesyncd >/dev/null 2>&1 || true
fi
clock_attempt=0
while [ "\$(timedatectl show -p NTPSynchronized --value 2>/dev/null || true)" != 'yes' ]; do
clock_attempt=\$((clock_attempt + 1))
if [ "\$clock_attempt" -ge 15 ]; then
echo 'Automatic time synchronization did not become ready within 30 seconds.' >&2
return $_linuxClockSyncFailureExitCode
fi
sleep 2
done
echo 'System clock synchronized.'
}
refresh_package_indexes() {
apt_update_log="\${TMPDIR:-/tmp}/harness-apt-update-\$\$.log"
if apt_as_root update 2>&1 | tee "\$apt_update_log"; then
rm -f "\$apt_update_log"
return 0
fi
if grep -Eiq 'is not valid yet|certificate is not yet valid' "\$apt_update_log"; then
rm -f "\$apt_update_log"
if ! repair_system_clock; then
echo 'System clock could not be synchronized automatically.' >&2
return $_linuxClockSyncFailureExitCode
fi
if ! apt_as_root update; then
echo 'Package repository refresh still failed after clock synchronization.' >&2
return $_linuxAptUpdateFailureExitCode
fi
return 0
fi
rm -f "\$apt_update_log"
echo 'Package repository refresh failed. Harness will not retry with stale package indexes.' >&2
return $_linuxAptUpdateFailureExitCode
}
install_linux_packages() {
apt_as_root install -y $names && return 0
echo 'Refreshing package indexes before retrying…'
refresh_package_indexes || return \$?
if ! apt_as_root install -y $names; then
echo 'Package installation still failed after a successful repository refresh.' >&2
return $_linuxAptInstallFailureExitCode
fi
}
if install_linux_packages; then
:
else
install_status=\$?
exit "\$install_status"
fi''';
}
Future<String> _linuxHostManualCommand(List<String> packages) async {
final names = packages.toSet().join(' ');
if (names.isEmpty) return 'Recheck Linux system dependencies.';
if (!await _hasAptGet()) {
return 'Install with your distribution package manager: $names';
}
return 'sudo apt-get install -y $names';
}
/// The installed CLI's version when [_hasHarness] turned it down as older
/// than [kMinimumHarnessCliVersion]; null otherwise.
String? _harnessOutdated;
/// [kMinimumHarnessCliVersion], or [kMinimumWindowsHarnessCliVersion] on Windows.
String get _minimumCliVersion =>
_isWindows ? kMinimumWindowsHarnessCliVersion : kMinimumHarnessCliVersion;
Future<bool> _hasHarness() async {
_harnessOutdated = null;
if (_isWindows) return _hasWindowsHarness();
final currentNode = File('${harnessHome.path}/runtime/current-node');
if (!await currentNode.exists()) return false;
final nodePath = (await currentNode.readAsString()).trim();
if (nodePath.isEmpty || !File(nodePath).existsSync()) return false;
final runtimeRoot = '${harnessHome.absolute.path}/runtime/';
if (!File(nodePath).absolute.path.startsWith(runtimeRoot)) return false;
final node = await _runProbe(
nodePath,
['--version'],
label: 'the managed Node runtime',
step: EnvironmentStep.harness,
);
if (!_nodeRuns(node)) return false;
try {
final cli = File('${harnessHome.path}/cli/cli.js');
if (!await cli.exists()) return false;
return _versionAccepted(
await _probeHarnessCommand(nodePath, [cli.path, 'version']),
);
} on ProcessException {
return false;
} on StateError {
return false;
}
}
/// [_hasHarness] on Windows: B's pointers ([managedWindowsCli]), the Node
/// they name, and the CLI's own version.
Future<bool> _hasWindowsHarness() async {
final cli = await managedWindowsCli(harnessHome);
if (cli == null) return false;
try {
final node = await _runProbe(
cli.node,
['--version'],
label: 'the managed Node runtime',
step: EnvironmentStep.harness,
);
if (!_nodeRuns(node)) return false;
return _versionAccepted(
await _probeHarnessCommand(cli.node, [cli.cliJs, 'version']),
);
} on ProcessException {
return false;
}
}
/// Node 20 or newer answered `--version`.
static bool _nodeRuns(ProcessResult node) {
if (node.exitCode != 0) return false;
final match = RegExp(r'^v?(\d+)').firstMatch('${node.stdout}'.trim());
return match != null && int.parse(match.group(1)!) >= 20;
}
/// `harness version` answered with a version this app runs against, and
/// [_harnessOutdated] says which when it did not.
bool _versionAccepted(ProcessResult version) {
if (version.exitCode != 0) return false;
// A CLI that runs is not enough: one from before the app's minimum
// refuses `harness start` without a sign-in, and it only self-updates
// from a running daemon — so it would never get past that on its own.
// Treated as missing, the installer lays the current one over it. An
// unparseable version (a local development build) is left alone.
final installed = '${version.stdout}'.trim().replaceFirst(RegExp('^v'), '');
// Local CLI builds intentionally use 0.0.1-dev.<revision>. A debug
// desktop must not mistake these for an obsolete release and offer to
// overwrite the developer's CLI. Release builds retain the minimum.
final localDevelopmentBuild =
kDebugMode && installed.startsWith('0.0.1-dev.');
_harnessOutdated =
!localDevelopmentBuild && semverGt(_minimumCliVersion, installed)
? installed
: null;
return _harnessOutdated == null;
}
/// `install.ps1 -Desktop` (spec §1.4): Windows PowerShell by its full path,
/// hidden, no shell, the output streamed into the setup log the screen
/// shows, and install.ps1's own sentence kept as the failure. Null when it
/// installed; the final probe then checks what it laid down.
Future<EnvironmentFailure?> _installWindows(
void Function(String line) onOutput,
) async {
final url = _windowsInstallScriptUrl;
final manual = windowsManualInstallCommand(url);
if (!isTrustedInstallScriptUrl(url)) {
return EnvironmentFailure(
step: EnvironmentStep.harness,
title: 'Harness could not be installed',
detail:
'This build names an installer address Harness does not trust: $url',
command: windowsManualInstallCommand(
harnessInstallScriptUrl(override: ''),
),
);
}
final executable = windowsPowerShellPath(_platformEnvironment);
final arguments = windowsInstallArguments(url);
try {
final start = _start;
final install = start == null
? await _replayed(
_run(executable, arguments, environment: _platformEnvironment),
onOutput,
)
: await _streamed(
start,
executable,
arguments,
environment: _platformEnvironment,
onOutput: onOutput,
);
return windowsInstallFailure(install, manualCommand: manual);
} on ProcessException catch (error) {
return EnvironmentFailure(
step: EnvironmentStep.harness,
title: 'Harness could not be installed',
detail: 'Windows PowerShell could not be started: ${error.message}',
command: manual,
);
}
}
Future<void> _ensureHarness(void Function(String line) onOutput) async {
final runner = HarnessCliRunner(
harnessHome: harnessHome,
runProcess: _probeHarnessCommand,
);
if (await _hasHarness()) return;
// No interpreter is named here. install.sh provisions the same
// checksum-verified Node under `~/.harness/runtime` when the computer has
// none, records it in `current-node`, and bakes its absolute path into the
// `~/.local/bin/harness` launcher — which is what makes a Finder launch,
// where PATH is launchd's bare `/usr/bin:/bin:/usr/sbin:/sbin`, still find
// a Node. Doing it there rather than here keeps ONE implementation of that,
// shared with everyone who installs the CLI from a terminal.
final install = await _shellStreaming(
// Served off the CDN-fronted public bucket (autonomous-code: apps/web/scripts/cli-install.sh,
// published with `make upload-cli-install-sh`), not by the web app. The old web-app URL,
// https://harness.autonomous.ai/cli/install.sh, still redirects here, but pointing at the CDN
// URL directly avoids that extra hop.
// A stale URL is worse here than anywhere else: a 404 piped into bash still exits 0 (measured),
// so the `install.exitCode != 0` check below would pass and the failure would only surface as
// the confusing "CLI did not start after installation" a few lines further down.
'set -e; $kHarnessDesktopInstallCommand',
onOutput: onOutput,
);
if (install.exitCode != 0) {
throw StateError(
'Harness installer exited ${install.exitCode}: ${_resultText(install)}',
);
}
final verified = await runner.run(['version']);
if (verified.exitCode != 0 || !await _hasHarness()) {
throw StateError(
'Harness CLI verification exited ${verified.exitCode}: ${_resultText(verified)}',
);
}
}
Future<({File log, File result})> _launchLinuxHostSetup(
List<String> packages,
) => _launchTerminalSetup(linuxPackages: packages);
Future<({File log, File result})> _launchTerminalSetup({
List<String> linuxPackages = const [],
}) async {
// Package-manager installs can ask for a password. Always hand them to a
// visible OS terminal instead of guessing whether this particular run will
// prompt in a headless Process.run child.
final script = await _writeTerminalBootstrapScript(
linuxPackages: linuxPackages,
);
await _openTerminal(script.path);
return (
log: File('${script.parent.path}/terminal.log'),
result: File('${script.parent.path}/terminal.exit'),
);
}
Future<bool> _hasTmux() async {
final result = await _probeShell(
'command -v tmux >/dev/null && tmux -V',
'tmux',
step: EnvironmentStep.tmux,
);
return result.exitCode == 0;
}
Future<bool> _hasHomebrew() async {
final result = await _probeShell(
'command -v brew >/dev/null && brew --version',
'Homebrew',
step: EnvironmentStep.tmux,
);
return result.exitCode == 0;
}
/// The Linux apt transaction as a script for a real terminal — the one
/// host step left that needs a password on a tty.
Future<File> _writeTerminalBootstrapScript({
List<String> linuxPackages = const [],
}) async {
final directory = Directory(
'${harnessHome.path}/desktop-app-v2/setup-runs/${DateTime.now().millisecondsSinceEpoch}',
);
await directory.create(recursive: true);
await _run('/bin/chmod', ['700', directory.path]);
final packageList = linuxPackages.isEmpty
? const ['tmux']
: linuxPackages.toSet().toList();
final packages = packageList.join(' ');
const packageCommands = <String, String>{
'curl': 'curl',
'tar': 'tar',
'sed': 'sed',
'gawk': 'awk',
'coreutils': 'sha256sum',
'tmux': 'tmux',
'procps': 'ps',
'xclip': 'xclip',
'wl-clipboard': 'wl-copy',
};
final verification = packageList
.map((package) => packageCommands[package])
.whereType<String>()
.map(
(command) => command == 'tmux'
? 'command -v tmux >/dev/null 2>&1 && tmux -V'
: 'command -v $command >/dev/null 2>&1',
)
.join('\n');
final aptInstallCommand = _linuxAptInstallCommand(
packageList,
nonInteractiveSudo: false,
);
final script = File('${directory.path}/install-linux-dependencies.sh');
await script.writeAsString('''#!/bin/bash
set -eu
umask 077
LOG_FILE="${directory.path}/terminal.log"
RESULT_FILE="${directory.path}/terminal.exit"
exec > >(tee -a "\$LOG_FILE") 2>&1
finish() {
status=\$?
printf '%s\\n' "\$status" > "\$RESULT_FILE"
if [ "\$status" -ne 0 ]; then
echo
echo 'Linux package installation failed. Review the error above, then try again.'
read -r -p 'Press Enter to close this window…' || true
fi
return "\$status"
}
trap finish EXIT
if command -v apt-get >/dev/null 2>&1; then
echo 'Installing Linux host dependencies (you may be asked for your password)…'
$aptInstallCommand
$verification
echo 'Installed packages: $packages'
echo 'Linux host dependencies are ready. This window will close automatically in 5 seconds.'
sleep 5
else
echo 'Automatic Linux package installation only supports apt-based distributions (Ubuntu/Debian).'
echo 'Install these packages with your distribution package manager: $packages'
exit 1
fi
''', flush: true);
await _run('/bin/chmod', ['700', script.path]);
return script;
}
List<String> _shellArguments(String command) => [
'-l',
'-c',
// The Homebrew prefixes are named rather than trusted to be on PATH:
// `-l` is a LOGIN shell but not an interactive one, so it reads
// `~/.zprofile` and never `~/.zshrc`
// — which is where `brew shellenv` sits on plenty of machines. A Finder
// launch then starts from launchd's bare `/usr/bin:/bin:/usr/sbin:/sbin`
// and this probe reports tmux missing on a computer that has it, then
// "installs" it through whichever `brew` it can see. Measured: an Apple
// Silicon Mac with both Homebrews picked up Intel `/usr/local/bin/brew`
// and built openssl@3 from source under Rosetta, holding the boot open
// on "Checking tmux…" for as long as that took. Apple Silicon first, so
// a machine with both never installs through the Intel one. The CLI
// closed the same gap in `lib/tmuxOnPath.ts`.
'export PATH="\$HOME/.local/bin${_isMacOS ? ':/opt/homebrew/bin:/usr/local/bin' : ''}:\$PATH"; $command',
];
Future<ProcessResult> _probeShell(
String command,
String label, {
EnvironmentStep? step,
}) => _runProbe(
_isMacOS ? '/bin/zsh' : '/bin/bash',
_shellArguments(command),
label: label,
step: step,
);
Future<ProcessResult> _probeHarnessCommand(
String executable,
List<String> arguments, {
Map<String, String>? environment,
}) => _runProbe(
executable,
arguments,
environment: environment,
label: 'the Harness CLI',
step: EnvironmentStep.harness,
);
/// A check owns its process and waits for at most one short deadline,
/// including process startup and output-pipe closure. Installers use the
/// separate streaming path: a slow version check must never look like a
/// missing tool or leave another check running every time Retry is pressed.
Future<ProcessResult> _runProbe(
String executable,
List<String> arguments, {
required String label,
EnvironmentStep? step,
Map<String, String>? environment,
}) async {
final timeout = _EnvironmentProbeTimeout(label, step);
final start = _start;
if (start == null) {
// Existing run-only test doubles do not own operating-system processes.
return _run(
executable,
arguments,
environment: environment,
).timeout(probeTimeout, onTimeout: () => throw timeout);
}
final result = Completer<ProcessResult>();
Process? process;
StreamSubscription<List<int>>? output;
StreamSubscription<List<int>>? errors;
final stdout = BytesBuilder();
final stderr = BytesBuilder();
int? exitCode;
var exited = false;
var outputClosed = false;
var errorsClosed = false;
void fail(Object error, StackTrace stack) {
if (!result.isCompleted) result.completeError(error, stack);
}
void collect(BytesBuilder buffer, List<int> bytes) {
const maxOutputBytes = 64 * 1024;
final available = maxOutputBytes - buffer.length;
if (available > 0) {
buffer.add(
bytes.length > available ? bytes.sublist(0, available) : bytes,
);
}
}
void finish() {
if (result.isCompleted || !exited || !outputClosed || !errorsClosed) {
return;
}
result.complete(
ProcessResult(
process!.pid,
exitCode!,
utf8.decode(stdout.takeBytes(), allowMalformed: true),
utf8.decode(stderr.takeBytes(), allowMalformed: true),
),
);
}
final timer = Timer(probeTimeout, () => fail(timeout, StackTrace.current));
unawaited(() async {
try {
final child = await start(
executable,
arguments,
environment: environment,
);
// A late launch must also be stopped; the timeout may have already
// returned control to the user and allowed a replacement check.
if (result.isCompleted) {
child.kill(ProcessSignal.sigkill);
await child.stdout.listen(null, onError: (Object _) {}).cancel();
await child.stderr.listen(null, onError: (Object _) {}).cancel();
await child.stdin.close();
return;
}
process = child;
// Probes never ask for input, including through shell startup files.
unawaited(
child.stdin.close().then<void>((_) {}, onError: (Object _) {}),
);
output = child.stdout.listen(
(bytes) => collect(stdout, bytes),
onError: fail,
onDone: () {
outputClosed = true;
finish();
},
);
errors = child.stderr.listen(
(bytes) => collect(stderr, bytes),
onError: fail,
onDone: () {
errorsClosed = true;
finish();
},
);
unawaited(
child.exitCode.then<void>((value) {
exited = true;
exitCode = value;
finish();
}, onError: fail),
);
} catch (error, stack) {
fail(error, stack);
}
}());
try {
return await result.future;
} finally {
timer.cancel();
if (!exited) process?.kill(ProcessSignal.sigkill);
await output?.cancel();
await errors?.cancel();
}
}
Future<ProcessResult> _shell(
String command, {
Map<String, String>? environment,
Duration? timeout,
}) {
final run = _run(
_isMacOS ? '/bin/zsh' : '/bin/bash',
_shellArguments(command),
environment: environment,
);
if (timeout == null) return run;
// The child keeps running — Process.run gives us no handle to kill. That is
// the intent: a slow install finishes in the background and the next launch
// finds it, while this one stops waiting.
return run.timeout(
timeout,
onTimeout: () => ProcessResult(0, 124, '', 'timed out after $timeout'),
);
}
Future<ProcessResult> _shellStreaming(
String command, {
required void Function(String line) onOutput,
Duration? timeout,
}) {
final start = _start;
if (start == null) {
return _replayed(_shell(command, timeout: timeout), onOutput);
}
return _streamed(
start,
_isMacOS ? '/bin/zsh' : '/bin/bash',
_shellArguments(command),
onOutput: onOutput,
timeout: timeout,
);
}
/// A finished run's output, handed to [onOutput] line by line, for the
/// run-only test doubles that own no process.
static Future<ProcessResult> _replayed(
Future<ProcessResult> run,
void Function(String line) onOutput,
) async {
final result = await run;
for (final line in '${result.stdout}\n${result.stderr}'.split('\n')) {
if (line.trim().isNotEmpty) onOutput(line);
}
return result;
}
/// Runs [executable] with its output handed to [onOutput] as each line
/// arrives.
Future<ProcessResult> _streamed(
ProcessStarter start,
String executable,
List<String> arguments, {
required void Function(String line) onOutput,
Map<String, String>? environment,
Duration? timeout,
}) async {
final process = await start(
executable,
arguments,
environment: environment,
);
// A Windows installer whose output encoding could not be set must not
// end the stream on its first OEM byte.
final Converter<List<int>, String> decoder = _isWindows
? const Utf8Decoder(allowMalformed: true)
: utf8.decoder;
final stdoutLines = <String>[];
final stderrLines = <String>[];
final stdoutSubscription = process.stdout
.transform(decoder)
.transform(const LineSplitter())
.listen((line) {
stdoutLines.add(line);
onOutput(line);
});
final stderrSubscription = process.stderr
.transform(decoder)
.transform(const LineSplitter())
.listen((line) {
stderrLines.add(line);
onOutput(line);
});
final stdoutDone = stdoutSubscription.asFuture<void>();
final stderrDone = stderrSubscription.asFuture<void>();
var timedOut = false;
final exit = timeout == null
? await process.exitCode
: await process.exitCode.timeout(
timeout,
onTimeout: () {
timedOut = true;
process.kill();
return 124;
},
);
if (timedOut) {
await stdoutSubscription.cancel();
await stderrSubscription.cancel();
} else {
await Future.wait([stdoutDone, stderrDone]);
}
return ProcessResult(
process.pid,
exit,
stdoutLines.join('\n'),
stderrLines.join('\n'),
);
}
String _manualCommandFor(EnvironmentStep step) => switch (step) {
_ when _isWindows => windowsManualInstallCommand(_windowsInstallScriptUrl),
EnvironmentStep.clipboard =>
'sudo apt-get install -y ${_linuxClipboardPackage() ?? 'xclip or wl-clipboard'}',
EnvironmentStep.tmux =>
_isMacOS
? '$kHarnessHostSetupCommand && tmux -V'
: 'sudo apt-get install -y tmux && tmux -V',
EnvironmentStep.harness =>
'$kHarnessDesktopInstallCommand && harness version',
};
String _resultText(ProcessResult result) {
final text = '${result.stderr}\n${result.stdout}'.trim();
return text.length <= 700 ? text : text.substring(text.length - 700);
}
}
extension on Iterable<EnvironmentStep> {
EnvironmentStep? get firstOrNull => isEmpty ? null : first;
}
/// The result of one read-only look at the computer: which required commands
/// run, and the plan for the ones that do not.
class _HostProbe {
final bool tmuxRuns;
final bool psRuns;
final bool clipboardApplicable;
final bool clipboardRuns;
final String? clipboardCommand;
final String? clipboardPackage;
final bool harnessRuns;
/// macOS: Homebrew is present, so tmux installs in-app without a password.
final bool homebrewInstallsTmux;
/// Windows: the terminal step is B's terminal host, and this is the version
/// `runtime\pty\current-pty` names (null when it is not installed).
final bool windows;
final String? terminalHostVersion;
/// Linux: the one apt transaction, in install order. Empty when nothing
/// needs apt.
final List<String> aptPackages;
final List<EnvironmentPlanItem> plan;
const _HostProbe({
required this.tmuxRuns,
this.psRuns = true,
required this.clipboardApplicable,
required this.clipboardRuns,
this.clipboardCommand,
this.clipboardPackage,
required this.harnessRuns,
this.homebrewInstallsTmux = false,
this.windows = false,
this.terminalHostVersion,
this.aptPackages = const [],
required this.plan,
});
List<EnvironmentPlanItem> planFor(EnvironmentStep step) =>
plan.where((item) => item.step == step).toList();
/// The terminal backend as a whole: tmux, and on Linux `ps` beside it.
bool get terminalReady => tmuxRuns && psRuns;
/// The host steps (everything but the Harness CLI) that are not ready.
List<EnvironmentStep> get missingHostSteps => [
if (!terminalReady) EnvironmentStep.tmux,
if (clipboardApplicable && !clipboardRuns) EnvironmentStep.clipboard,
];
/// What is still missing, by command name, for a failure detail.
List<String> get missingHostNames => [
if (!tmuxRuns) 'tmux',
if (!psRuns) 'ps',
if (clipboardApplicable && !clipboardRuns) ?clipboardCommand,
];
String get tmuxMessage {
if (windows) {
return terminalReady
? 'The terminal host is ready.'
: 'The terminal host installs with the Harness CLI.';
}
if (terminalReady) return 'tmux is ready.';
if (aptPackages.isNotEmpty) {
return '${psRuns ? 'tmux' : 'tmux and ps'} will be installed with apt.';
}
return homebrewInstallsTmux
? 'tmux will be installed with Homebrew.'
: 'tmux will be downloaded into ~/.harness/runtime.';
}
String get tmuxOutput {
if (windows) {
return terminalReady
? '✓ terminal host $terminalHostVersion'
: r'✗ terminal host · runtime\pty\current-pty';
}
if (terminalReady) return '✓ tmux --version';
final lines = <String>[tmuxRuns ? '✓ tmux --version' : '✗ tmux --version'];
if (!psRuns) lines.add('✗ ps');
if (aptPackages.isEmpty) {
lines.add(
homebrewInstallsTmux ? '✓ brew --version' : '– managed tmux download',
);
}
return lines.join(' · ');
}
}