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
refactor: replace local install logic with unified environment provisioner plan
0xken1505a5117ca77e
diff --git a/cli/scripts/install.sh b/cli/scripts/install.shindex 712b4e0e3..f9c1294db 100755--- a/cli/scripts/install.sh+++ b/cli/scripts/install.sh@@ -8,7 +8,8 @@# install.sh, but only as a redirect to the CDN one (its next.config.js) — kept for anyone with the old# link already saved.# curl -fsSL https://cdn.autonomous.ai/harness/cli/install.sh | bash-# curl -fsSL https://cdn.autonomous.ai/harness/cli/install.sh | sh -s -- --desktop # Desktop only+# curl -fsSL https://cdn.autonomous.ai/harness/cli/install.sh | sh -s -- --desktop # Desktop: runtime + CLI only+# curl -fsSL https://cdn.autonomous.ai/harness/cli/install.sh | sh -s -- --host # Desktop: host requirements only# harness login# harness start#@@ -18,19 +19,24 @@# There is no system Node prerequisite. The CLI is plain JS (no native binary, no code-signing) and it runs on a# checksum-verified Node this installer puts in ~/.harness/runtime — the same runtime Desktop Harness# manages, shared on purpose so one cli.js is never run by two different Nodes. Your own Node and nvm-# are neither required nor touched. In standalone mode, tmux is the only supported terminal backend,-# so it is prepared and verified before any Harness runtime or CLI files are installed. On macOS the-# supported tmux path is Homebrew; on Ubuntu it is apt. A Linux GUI also requires the clipboard-# helper for its active display protocol. Desktop mode trusts the app's earlier host pre-flight and-# skips that package work. The runtime's absolute path is baked into the launcher,-# so a Finder launch — where PATH is launchd's bare /usr/bin:/bin:/usr/sbin:/sbin — resolves the CLI-# exactly like a terminal does.+# are neither required nor touched.+#+# What the CLI RUNS is a short list — tmux (its only terminal backend), `ps`, and on a Linux desktop+# the clipboard helper for the active display — and step 1 checks exactly that list. Everything else+# here (Homebrew, the Apple developer tools, apt, curl/tar/sed/awk/sha256sum) is only a way of+# obtaining one of those or of downloading the runtime, and is looked at only when the thing it+# obtains is missing: a Mac with tmux never hears about Homebrew, a Mac with Homebrew never hears+# about Xcode, and the download tools are checked only when a runtime is actually downloaded.+# Desktop mode (`--desktop`) trusts the app's own host pre-flight and skips step 1; host mode+# (`--host`) is the app handing step 1 to a real terminal for its password prompts and stops after it.+# The runtime's absolute path is baked into the launcher, so a Finder launch — where PATH is+# launchd's bare /usr/bin:/bin:/usr/sbin:/sbin — resolves the CLI exactly like a terminal does.# POSIX sh (so `| sh` and `| bash` both work).set -eu# No argument is the complete standalone/server installer. Desktop owns host pre-flight and passes# --desktop so this script installs only the managed runtime and CLI instead of asking twice for the-# same package-manager/admin work.+# same package-manager/admin work — or --host for the opposite half.INSTALL_MODE=standalonecase "${1:-}" in"") ;;@@ -38,6 +44,10 @@ case "${1:-}" inINSTALL_MODE=desktopshift;;+ --host)+ INSTALL_MODE=host+ shift+ ;;*)echo "✗ Unsupported installer argument: $1" >&2echo " This installer no longer accepts a machine token." >&2@@ -46,7 +56,7 @@ case "${1:-}" in;;esacif [ "$#" -gt 0 ]; then- echo "✗ Desktop mode accepts no additional arguments." >&2+ echo "✗ $INSTALL_MODE mode accepts no additional arguments." >&2echo "✗ This installer no longer accepts a machine token." >&2exit 2fi@@ -62,9 +72,9 @@ CURRENT_NODE_FILE="$RUNTIME_DIR/current-node"BIN_DIR="$HOME/.local/bin"LAUNCHER="$BIN_DIR/harness"-# 1. Standalone host setup. tmux is the CLI's only supported terminal backend, so prepare it before-# writing Node or Harness files and fail clearly if it cannot be verified. This installer already-# runs in a terminal, so package-manager password prompts stay with the OS — never Harness.+# 1. Host requirements (standalone and --host). The CLI runs tmux, `ps`, and on a Linux desktop the+# clipboard helper — those are checked, and only what is missing is obtained. This installer+# already runs in a terminal, so package-manager password prompts stay with the OS — never Harness.require_command() {command -v "$1" >/dev/null 2>&1 || {echo "✗ Required system tool is missing: $1" >&2@@ -92,43 +102,60 @@ install_with_apt() {apt_as_root install -y "$@"}-if [ "$INSTALL_MODE" = "standalone" ]; then+tmux_runs() {+ command -v tmux >/dev/null 2>&1 && tmux -V >/dev/null 2>&1+}++if [ "$INSTALL_MODE" != "desktop" ]; thencase "$(uname -s)" inDarwin)- require_command curl- require_command tar- require_command sed- require_command awk- command -v shasum >/dev/null 2>&1 || { echo "✗ Required system tool is missing: shasum" >&2; exit 11; }- if ! /usr/bin/xcrun --find clang >/dev/null 2>&1; then- echo "▸ Apple developer tools are required by Homebrew (Xcode or Command Line Tools)."- if [ -x /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild ]; then- echo " Xcode is installed but is not the active developer directory."- echo " macOS may ask for your password to select it."- sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer- else- echo " macOS will open its installer now. Finish it, then run this Harness installer again."- xcode-select --install >/dev/null 2>&1 || true- exit 20+ if tmux_runs; then+ : # tmux runs. Homebrew and the Apple developer tools are how it would have been installed;+ # with it here they are nobody's business, and neither is looked at.+ else+ # A Homebrew installed for a different shell is still installed.+ if ! command -v brew >/dev/null 2>&1; then+ eval "$(/opt/homebrew/bin/brew shellenv 2>/dev/null || /usr/local/bin/brew shellenv 2>/dev/null || true)"+ fi+ if ! command -v brew >/dev/null 2>&1; then+ # Homebrew's own installer needs the Apple developer tools; this is the only place they matter.+ if ! /usr/bin/xcrun --find clang >/dev/null 2>&1; then+ echo "▸ Apple developer tools are required by Homebrew (Xcode or Command Line Tools)."+ if [ -x /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild ]; then+ # xcrun answers "not ready" for two different reasons, and only one of them is the+ # developer directory. An unaccepted Xcode licence exits 69 and no amount of+ # xcode-select fixes it.+ if ! /usr/bin/xcodebuild -license check >/dev/null 2>&1; then+ echo " Xcode is installed but its licence has not been accepted."+ echo " macOS may ask for your password to accept it."+ sudo /usr/bin/xcodebuild -license accept+ fi+ if ! /usr/bin/xcrun --find clang >/dev/null 2>&1; then+ echo " Xcode is installed but is not the active developer directory."+ echo " macOS may ask for your password to select it."+ sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer+ fi+ else+ echo " macOS will open its installer now. Finish it, then run this Harness installer again."+ xcode-select --install >/dev/null 2>&1 || true+ exit 20+ fi+ /usr/bin/xcrun --find clang >/dev/null 2>&1 || {+ echo "✗ Apple developer tools are selected but are not usable." >&2+ exit 20+ }+ fi+ echo "▸ Installing Homebrew (macOS may ask for your password)"+ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" || {+ echo "✗ Homebrew installation failed. Review the output above, then retry." >&2+ exit 21+ }+ eval "$(/opt/homebrew/bin/brew shellenv 2>/dev/null || /usr/local/bin/brew shellenv 2>/dev/null)"+ command -v brew >/dev/null 2>&1 || {+ echo "✗ Homebrew was installed but is not available to this shell." >&2+ exit 21+ }fi- /usr/bin/xcrun --find clang >/dev/null 2>&1 || {- echo "✗ Apple developer tools are selected but are not usable." >&2- exit 20- }- fi- if ! command -v brew >/dev/null 2>&1; then- echo "▸ Installing Homebrew (macOS may ask for your password)"- /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" || {- echo "✗ Homebrew installation failed. Review the output above, then retry." >&2- exit 21- }- fi- eval "$(/opt/homebrew/bin/brew shellenv 2>/dev/null || /usr/local/bin/brew shellenv 2>/dev/null)"- command -v brew >/dev/null 2>&1 || {- echo "✗ Homebrew was installed but is not available to this shell." >&2- exit 21- }- if ! command -v tmux >/dev/null 2>&1; thenecho "▸ Installing tmux via Homebrew"brew install tmux || {echo "✗ Could not install tmux via Homebrew. Retry with: brew install tmux" >&2@@ -137,45 +164,9 @@ case "$(uname -s)" infi;;Linux)- missing_system_packages=""- command -v bash >/dev/null 2>&1 || missing_system_packages="$missing_system_packages bash"- command -v curl >/dev/null 2>&1 || missing_system_packages="$missing_system_packages curl"- command -v tar >/dev/null 2>&1 || missing_system_packages="$missing_system_packages tar"- command -v sed >/dev/null 2>&1 || missing_system_packages="$missing_system_packages sed"- command -v awk >/dev/null 2>&1 || missing_system_packages="$missing_system_packages gawk"- command -v sha256sum >/dev/null 2>&1 || missing_system_packages="$missing_system_packages coreutils"- if [ -n "$missing_system_packages" ]; then- command -v apt-get >/dev/null 2>&1 || {- echo "✗ Required Linux system tools are missing. Automatic install supports apt-based Linux only." >&2- echo " Install these packages with this distribution's package manager:$missing_system_packages" >&2- exit 11- }- echo "▸ Installing required Linux system tools (you may be asked for your password)"- # Intentional word splitting: this list contains only package names selected above.- # shellcheck disable=SC2086- install_with_apt $missing_system_packages || {- echo "✗ Could not install required Linux system tools via apt-get." >&2- exit 11- }- fi- require_command bash- require_command curl- require_command tar- require_command sed- require_command awk- require_command sha256sum- if ! command -v tmux >/dev/null 2>&1; then- command -v apt-get >/dev/null 2>&1 || {- echo "✗ tmux is required. Automatic install supports apt-based Linux only." >&2- echo " Install tmux with this distribution's package manager, then retry." >&2- exit 22- }- echo "▸ Installing tmux (you may be asked for your password)"- install_with_apt tmux || {- echo "✗ Could not install tmux via apt-get. Retry with: sudo apt-get install -y tmux" >&2- exit 22- }- fi+ missing_host_packages=""+ tmux_runs || missing_host_packages="$missing_host_packages tmux"+ command -v ps >/dev/null 2>&1 || missing_host_packages="$missing_host_packages procps"# Native image paste needs the helper for the display protocol this process will use. A# genuinely headless server has no OS clipboard, so installing either package there would add a# sudo prompt without adding a capability; the CLI deliberately uses its file-path fallback.@@ -191,18 +182,29 @@ case "$(uname -s)" inecho "▸ No X11 or Wayland display detected; native image clipboard is not applicable."fiif [ -n "$clipboard_command" ] && ! command -v "$clipboard_command" >/dev/null 2>&1; then+ missing_host_packages="$missing_host_packages $clipboard_package"+ fi+ if [ -n "$missing_host_packages" ]; thencommand -v apt-get >/dev/null 2>&1 || {- echo "✗ $clipboard_command is required for native image paste on this Linux desktop." >&2- echo " Install $clipboard_package with this distribution's package manager, then retry." >&2- exit 23+ echo "✗ Required Linux packages are missing:$missing_host_packages" >&2+ echo " Automatic install supports apt-based Linux only; install them with this distribution's package manager, then retry." >&2+ exit 22}- echo "▸ Installing $clipboard_package for native image paste (you may be asked for your password)"- install_with_apt "$clipboard_package" || {- echo "✗ Could not install $clipboard_package via apt-get." >&2- echo " Retry with: sudo apt-get install -y $clipboard_package" >&2- exit 23+ echo "▸ Installing required Linux packages (you may be asked for your password):$missing_host_packages"+ # Intentional word splitting: this list contains only package names selected above.+ # shellcheck disable=SC2086+ install_with_apt $missing_host_packages || {+ echo "✗ Could not install${missing_host_packages} via apt-get." >&2+ echo " Retry with: sudo apt-get install -y$missing_host_packages" >&2+ # 23 is the clipboard helper's own code, kept for a transaction that was only that.+ if [ "$missing_host_packages" = " $clipboard_package" ]; then exit 23; fi+ exit 22}fi+ command -v ps >/dev/null 2>&1 || {+ echo "✗ ps is required but did not pass verification." >&2+ exit 22+ }if [ -n "$clipboard_command" ]; thencommand -v "$clipboard_command" >/dev/null 2>&1 || {echo "✗ $clipboard_command is required but did not pass verification." >&2@@ -217,11 +219,15 @@ case "$(uname -s)" in;;esac-command -v tmux >/dev/null 2>&1 && tmux -V >/dev/null 2>&1 || {+tmux_runs || {echo "✗ tmux is required but did not pass verification." >&2exit 22}echo "✓ tmux ready ($(tmux -V))"+if [ "$INSTALL_MODE" = "host" ]; then+ echo "✓ Host requirements ready."+ exit 0+fielseecho "▸ Desktop mode: trusting the app's host pre-flight; skipping system packages and tmux setup."fi@@ -315,6 +321,36 @@ fiif [ -z "$NODE_BIN" ]; then+ # Fetching, unpacking and verifying the runtime is the only work in this file that needs these+ # host tools (step 3 is Node, and Node needs none of them) — so they are asked for here, once the+ # download is known to be happening, and nowhere earlier. macOS ships them all; a minimal Linux+ # can lack curl, and that is what apt is for.+ if [ "$(uname -s)" = "Linux" ]; then+ missing_download_tools=""+ command -v curl >/dev/null 2>&1 || missing_download_tools="$missing_download_tools curl"+ command -v tar >/dev/null 2>&1 || missing_download_tools="$missing_download_tools tar"+ command -v sed >/dev/null 2>&1 || missing_download_tools="$missing_download_tools sed"+ command -v awk >/dev/null 2>&1 || missing_download_tools="$missing_download_tools gawk"+ command -v sha256sum >/dev/null 2>&1 || missing_download_tools="$missing_download_tools coreutils"+ if [ -n "$missing_download_tools" ]; then+ command -v apt-get >/dev/null 2>&1 || {+ echo "✗ Downloading the Node runtime needs tools this computer lacks:$missing_download_tools" >&2+ echo " Automatic install supports apt-based Linux only; install them with this distribution's package manager, then retry." >&2+ exit 11+ }+ echo "▸ Installing the tools needed to download the runtime (you may be asked for your password):$missing_download_tools"+ # shellcheck disable=SC2086+ install_with_apt $missing_download_tools || {+ echo "✗ Could not install the download tools via apt-get." >&2+ exit 11+ }+ fi+ fi+ require_command curl+ require_command tar+ require_command sed+ require_command awk+# sha256 is the one tool that genuinely differs between the two platforms, and it is needed# BEFORE Node exists to smooth it over — hence this pair rather than step 2's single JS path.if command -v shasum >/dev/null 2>&1; then@@ -323,7 +359,7 @@ if [ -z "$NODE_BIN" ]; thensha256_of() { sha256sum "$1" | awk '{print $1}'; }elseecho "✗ Need shasum or sha256sum to verify the Node download, and found neither." >&2- exit 1+ exit 11fiecho "▸ Installing the Harness Node runtime into $RUNTIME_DIR"diff --git a/cli/src/scripts/install.spec.ts b/cli/src/scripts/install.spec.tsindex 1b690793c..6eee9579c 100644--- a/cli/src/scripts/install.spec.ts+++ b/cli/src/scripts/install.spec.ts@@ -13,12 +13,23 @@ const writeCommand = (directory: string, name: string, lines: string[]) => {chmodSync(path, 0o700);};-const writeLinuxBaseCommands = (directory: string) => {- for (const command of ["bash", "curl", "tar", "sed", "awk", "sha256sum"]) {- writeCommand(directory, command, ["exit 0"]);- }+// What the CLI runs on Linux besides tmux — the only other command step 1 asks about.+const writeLinuxHostCommands = (directory: string) => {+ writeCommand(directory, "ps", ["exit 0"]);};+// Step 1 of the script — the host-requirements ladder — as one runnable unit.+const hostSetupOf = (source: string) =>+ source.slice(source.indexOf("require_command()"), source.indexOf("# 2. Resolve the Node"));++// The download-tools check that guards the Node download, with the helpers it calls.+const downloadToolsOf = (source: string) =>+ source.slice(source.indexOf("require_command()"), source.indexOf("tmux_runs()")) ++ source.slice(+ source.indexOf(" # Fetching, unpacking and verifying the runtime"),+ source.indexOf(" # sha256 is the one tool"),+ );+describe("scripts/install.sh command contract", () => {it("rejects a legacy machine-token argument before installing", () => {const result = spawnSync("sh", [installer, "legacy-token"], { encoding: "utf8" });@@ -28,7 +39,7 @@ describe("scripts/install.sh command contract", () => {expect(result.stderr).toContain("harness login && harness start");});- it("accepts only standalone default or explicit desktop mode", () => {+ it("accepts only standalone default, explicit desktop mode or host mode", () => {const source = readFileSync(installer, "utf8");const parser = source.slice(0, source.indexOf('METADATA_URL='));@@ -40,6 +51,10 @@ describe("scripts/install.sh command contract", () => {encoding: "utf8",input: parser,});+ const host = spawnSync("/bin/sh", ["-s", "--", "--host"], {+ encoding: "utf8",+ input: parser,+ });const extra = spawnSync("/bin/sh",["-s", "--", "--desktop", "legacy-token"],@@ -48,6 +63,7 @@ describe("scripts/install.sh command contract", () => {expect(standalone.status).toBe(0);expect(desktop.status).toBe(0);+ expect(host.status).toBe(0);expect(extra.status).toBe(2);expect(extra.stderr).toContain("accepts no additional arguments");});@@ -87,7 +103,7 @@ describe("scripts/install.sh command contract", () => {it("prepares and verifies required tmux before installing Node or Harness", () => {const source = readFileSync(installer, "utf8");- const tmuxStep = source.indexOf("# 1. Standalone host setup");+ const tmuxStep = source.indexOf("# 1. Host requirements");const nodeStep = source.indexOf("# 2. Resolve the Node");const cliStep = source.indexOf("# 3. Fetch manifest");@@ -99,40 +115,133 @@ describe("scripts/install.sh command contract", () => {"sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer",);expect(source).toContain("xcode-select --install");+ // An unaccepted Xcode licence makes xcrun fail exactly like an unselected directory; only+ // one of them is fixed by xcode-select, so the licence is checked and accepted first.+ expect(source).toContain("/usr/bin/xcodebuild -license check");+ expect(source).toContain("sudo /usr/bin/xcodebuild -license accept");+ expect(source.indexOf("-license accept")).toBeLessThan(+ source.indexOf("sudo xcode-select --switch"),+ );expect(source).toContain("Homebrew installation failed");expect(source).toContain("brew install tmux");- expect(source).toContain("install_with_apt tmux");+ expect(source).toContain("install_with_apt $missing_host_packages");expect(source).toContain('if [ "$(id -u)" -eq 0 ]; then');expect(source).toContain('sudo apt-get "$@"');expect(source).not.toContain("sudo apt-get update &&");expect(source).toContain("Could not install tmux via Homebrew");- expect(source).toContain("Could not install tmux via apt-get");expect(source).toContain("tmux is required but did not pass verification");expect(source).toContain("exit 22");});- it("installs missing Linux base tools before tmux", () => {+ // The ladder, in source order: tmux is asked about first, Homebrew only when tmux is missing, the+ // Apple developer tools only when Homebrew is missing too.+ it("asks about Homebrew only without tmux, and about Xcode only without Homebrew", () => {const source = readFileSync(installer, "utf8");- const hostSetup = source.slice(- source.indexOf("apt_as_root()"),- source.indexOf("# 2. Resolve the Node"),- );- const scratch = mkdtempSync(join(tmpdir(), "harness-linux-tools-"));- const invocations = join(scratch, "apt-invocations");- const fakeCurl = join(scratch, "curl");+ const darwin = source.slice(source.indexOf(" Darwin)"), source.indexOf(" Linux)"));++ const tmuxCheck = darwin.indexOf("if tmux_runs; then");+ const brewCheck = darwin.indexOf('if ! command -v brew >/dev/null 2>&1; then');+ const xcrunCheck = darwin.indexOf("/usr/bin/xcrun --find clang");+ expect(tmuxCheck).toBeGreaterThan(-1);+ expect(brewCheck).toBeGreaterThan(tmuxCheck);+ expect(xcrunCheck).toBeGreaterThan(brewCheck);+ });++ it("does nothing on a Mac that already runs tmux", () => {+ const source = readFileSync(installer, "utf8");+ const hostSetup = hostSetupOf(source);+ const scratch = mkdtempSync(join(tmpdir(), "harness-mac-tmux-"));+ const invoked = join(scratch, "brew-invoked");try {- for (const command of ["bash", "tar", "sed", "awk", "sha256sum"]) {- writeCommand(scratch, command, ["exit 0"]);- }- writeCommand(scratch, "id", ["printf '0\\n'"]);- writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);+ writeCommand(scratch, "uname", ["printf 'Darwin\\n'"]);writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);- writeCommand(scratch, "apt-get", [+ writeCommand(scratch, "brew", [`: > '${invoked}'`, "exit 99"]);+ writeCommand(scratch, "sudo", [`: > '${invoked}'`, "exit 99"]);+ writeCommand(scratch, "xcode-select", [`: > '${invoked}'`, "exit 99"]);++ const result = spawnSync("/bin/sh", ["-c", hostSetup], {+ encoding: "utf8",+ env: { ...process.env, INSTALL_MODE: "standalone", PATH: scratch },+ });++ expect(result.status).toBe(0);+ expect(result.stdout).toContain("tmux ready");+ expect(result.stdout).not.toContain("Homebrew");+ expect(() => readFileSync(invoked, "utf8")).toThrow();+ } finally {+ rmSync(scratch, { recursive: true, force: true });+ }+ });++ it("installs tmux with an existing Homebrew and never looks for Xcode", () => {+ const source = readFileSync(installer, "utf8");+ const hostSetup = hostSetupOf(source);+ const scratch = mkdtempSync(join(tmpdir(), "harness-mac-brew-"));+ const invocations = join(scratch, "brew-invocations");+ const developerTools = join(scratch, "developer-tools-touched");+ const fakeTmux = join(scratch, "tmux");++ try {+ writeCommand(scratch, "uname", ["printf 'Darwin\\n'"]);+ writeCommand(scratch, "brew", [`printf '%s\\n' "$*" >> '${invocations}'`,- `printf '%s\\n' '#!/bin/sh' 'exit 0' > '${fakeCurl}'`,- `/bin/chmod 700 '${fakeCurl}'`,+ `if [ "$1" = "shellenv" ]; then exit 0; fi`,+ `printf '%s\\n' '#!/bin/sh' 'printf "tmux 3.6\\\\n"' > '${fakeTmux}'`,+ `/bin/chmod 700 '${fakeTmux}'`,]);+ writeCommand(scratch, "sudo", [`: > '${developerTools}'`, "exit 99"]);+ writeCommand(scratch, "xcode-select", [`: > '${developerTools}'`, "exit 99"]);++ const result = spawnSync("/bin/sh", ["-c", hostSetup], {+ encoding: "utf8",+ env: { ...process.env, INSTALL_MODE: "standalone", PATH: scratch },+ });++ expect(result.status).toBe(0);+ expect(readFileSync(invocations, "utf8")).toContain("install tmux\n");+ expect(result.stdout).not.toContain("Apple developer tools");+ expect(() => readFileSync(developerTools, "utf8")).toThrow();+ } finally {+ rmSync(scratch, { recursive: true, force: true });+ }+ });++ it("host mode stops after the host requirements", () => {+ const source = readFileSync(installer, "utf8");+ const hostSetup = hostSetupOf(source);+ const scratch = mkdtempSync(join(tmpdir(), "harness-host-mode-"));++ try {+ writeCommand(scratch, "uname", ["printf 'Darwin\\n'"]);+ writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);++ const result = spawnSync("/bin/sh", ["-c", `${hostSetup}\necho REACHED-NODE-STEP`], {+ encoding: "utf8",+ env: { ...process.env, INSTALL_MODE: "host", PATH: scratch },+ });++ expect(result.status).toBe(0);+ expect(result.stdout).toContain("Host requirements ready");+ expect(result.stdout).not.toContain("REACHED-NODE-STEP");+ } finally {+ rmSync(scratch, { recursive: true, force: true });+ }+ });++ it("installs nothing on a Linux host that already runs tmux and ps", () => {+ const source = readFileSync(installer, "utf8");+ const hostSetup = hostSetupOf(source);+ const scratch = mkdtempSync(join(tmpdir(), "harness-linux-ready-"));+ const invoked = join(scratch, "apt-invoked");++ try {+ writeLinuxHostCommands(scratch);+ writeCommand(scratch, "id", ["printf '0\\n'"]);+ writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);+ writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);+ // curl is a download tool, not a host requirement: its absence is no business of step 1.+ writeCommand(scratch, "apt-get", [`: > '${invoked}'`, "exit 99"]);const result = spawnSync("/bin/sh", ["-c", hostSetup], {encoding: "utf8",@@ -145,12 +254,48 @@ describe("scripts/install.sh command contract", () => {},});+ expect(result.status).toBe(0);+ expect(result.stdout).toContain("tmux ready");+ expect(() => readFileSync(invoked, "utf8")).toThrow();+ } finally {+ rmSync(scratch, { recursive: true, force: true });+ }+ });++ it("installs the download tools only when the runtime is downloaded", () => {+ const source = readFileSync(installer, "utf8");+ // The check lives inside the download branch, after managed-runtime reuse is ruled out.+ const download = source.indexOf('if [ -z "$NODE_BIN" ]; then\n\n # Fetching');+ const reuse = source.indexOf('if [ -z "$NODE_BIN" ] && [ -r "$CURRENT_NODE_FILE" ]');+ expect(reuse).toBeGreaterThan(-1);+ expect(download).toBeGreaterThan(reuse);+ expect(source.slice(0, download)).not.toContain("require_command curl");++ const downloadTools = downloadToolsOf(source);+ const scratch = mkdtempSync(join(tmpdir(), "harness-download-tools-"));+ const invocations = join(scratch, "apt-invocations");+ const fakeCurl = join(scratch, "curl");++ try {+ for (const command of ["tar", "sed", "awk", "sha256sum"]) {+ writeCommand(scratch, command, ["exit 0"]);+ }+ writeCommand(scratch, "id", ["printf '0\\n'"]);+ writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);+ writeCommand(scratch, "apt-get", [+ `printf '%s\\n' "$*" >> '${invocations}'`,+ `printf '%s\\n' '#!/bin/sh' 'exit 0' > '${fakeCurl}'`,+ `/bin/chmod 700 '${fakeCurl}'`,+ ]);++ const result = spawnSync("/bin/sh", ["-c", downloadTools], {+ encoding: "utf8",+ env: { ...process.env, PATH: scratch },+ });+expect(result.status).toBe(0);expect(readFileSync(invocations, "utf8")).toBe("install -y curl\n");- expect(result.stdout).toContain("Installing required Linux system tools");- expect(result.stdout.indexOf("system tools")).toBeLessThan(- result.stdout.indexOf("tmux ready"),- );+ expect(result.stdout).toContain("tools needed to download the runtime");} finally {rmSync(scratch, { recursive: true, force: true });}@@ -158,16 +303,13 @@ describe("scripts/install.sh command contract", () => {it("installs tmux through sudo without refreshing usable package indexes", () => {const source = readFileSync(installer, "utf8");- const tmuxStep = source.slice(- source.indexOf("apt_as_root()"),- source.indexOf("# 2. Resolve the Node"),- );+ const tmuxStep = hostSetupOf(source);const scratch = mkdtempSync(join(tmpdir(), "harness-tmux-user-"));const invocation = join(scratch, "sudo-invocation");const fakeTmux = join(scratch, "tmux");try {- writeLinuxBaseCommands(scratch);+ writeLinuxHostCommands(scratch);writeCommand(scratch, "id", ["printf '1000\\n'"]);writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);writeCommand(scratch, "apt-get", ["exit 99"]);@@ -179,7 +321,13 @@ describe("scripts/install.sh command contract", () => {const result = spawnSync("/bin/sh", ["-c", tmuxStep], {encoding: "utf8",- env: { ...process.env, INSTALL_MODE: "standalone", PATH: scratch },+ env: {+ ...process.env,+ INSTALL_MODE: "standalone",+ DISPLAY: "",+ WAYLAND_DISPLAY: "",+ PATH: scratch,+ },});expect(result.status).toBe(0);@@ -192,17 +340,14 @@ describe("scripts/install.sh command contract", () => {it("installs as root without sudo and retries after a failed index refresh", () => {const source = readFileSync(installer, "utf8");- const tmuxStep = source.slice(- source.indexOf("apt_as_root()"),- source.indexOf("# 2. Resolve the Node"),- );+ const tmuxStep = hostSetupOf(source);const scratch = mkdtempSync(join(tmpdir(), "harness-tmux-root-"));const invocations = join(scratch, "apt-invocations");const firstAttempt = join(scratch, "first-attempt");const fakeTmux = join(scratch, "tmux");try {- writeLinuxBaseCommands(scratch);+ writeLinuxHostCommands(scratch);writeCommand(scratch, "id", ["printf '0\\n'"]);writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);writeCommand(scratch, "apt-get", [@@ -215,7 +360,13 @@ describe("scripts/install.sh command contract", () => {const result = spawnSync("/bin/sh", ["-c", tmuxStep], {encoding: "utf8",- env: { ...process.env, INSTALL_MODE: "standalone", PATH: scratch },+ env: {+ ...process.env,+ INSTALL_MODE: "standalone",+ DISPLAY: "",+ WAYLAND_DISPLAY: "",+ PATH: scratch,+ },});expect(result.status).toBe(0);@@ -245,16 +396,13 @@ describe("scripts/install.sh command contract", () => {it("installs xclip for X11 and verifies it", () => {const source = readFileSync(installer, "utf8");- const hostSetup = source.slice(- source.indexOf("apt_as_root()"),- source.indexOf("# 2. Resolve the Node"),- );+ const hostSetup = hostSetupOf(source);const scratch = mkdtempSync(join(tmpdir(), "harness-xclip-root-"));const invocations = join(scratch, "apt-invocations");const fakeXclip = join(scratch, "xclip");try {- writeLinuxBaseCommands(scratch);+ writeLinuxHostCommands(scratch);writeCommand(scratch, "id", ["printf '0\\n'"]);writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);@@ -285,15 +433,12 @@ describe("scripts/install.sh command contract", () => {it("does not install clipboard packages on a headless Linux host", () => {const source = readFileSync(installer, "utf8");- const hostSetup = source.slice(- source.indexOf("apt_as_root()"),- source.indexOf("# 2. Resolve the Node"),- );+ const hostSetup = hostSetupOf(source);const scratch = mkdtempSync(join(tmpdir(), "harness-headless-root-"));const invoked = join(scratch, "apt-invoked");try {- writeLinuxBaseCommands(scratch);+ writeLinuxHostCommands(scratch);writeCommand(scratch, "id", ["printf '0\\n'"]);writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);@@ -320,14 +465,11 @@ describe("scripts/install.sh command contract", () => {it("fails before Node when the active Wayland helper cannot be installed", () => {const source = readFileSync(installer, "utf8");- const hostSetup = source.slice(- source.indexOf("apt_as_root()"),- source.indexOf("# 2. Resolve the Node"),- );+ const hostSetup = hostSetupOf(source);const scratch = mkdtempSync(join(tmpdir(), "harness-wayland-fail-"));try {- writeLinuxBaseCommands(scratch);+ writeLinuxHostCommands(scratch);writeCommand(scratch, "id", ["printf '0\\n'"]);writeCommand(scratch, "uname", ["printf 'Linux\\n'"]);writeCommand(scratch, "tmux", ["printf 'tmux 3.6\\n'"]);@@ -354,10 +496,7 @@ describe("scripts/install.sh command contract", () => {it("desktop mode skips all host package and tmux work", () => {const source = readFileSync(installer, "utf8");- const hostSetup = source.slice(- source.indexOf("apt_as_root()"),- source.indexOf("# 2. Resolve the Node"),- );+ const hostSetup = hostSetupOf(source);const scratch = mkdtempSync(join(tmpdir(), "harness-desktop-mode-"));const invoked = join(scratch, "host-command-invoked");diff --git a/desktop/CLAUDE.md b/desktop/CLAUDE.mdindex e36334364..ab2f28a7e 100644--- a/desktop/CLAUDE.md+++ b/desktop/CLAUDE.md@@ -119,6 +119,18 @@ a terminal, instead of a second copy here that had to keep its own pinned checksscreen ever opens a terminal: a fresh Homebrew or any `apt-get install` needs a password prompt on areal tty.+**Readiness is the list of commands the app runs, nothing more** (`EnvironmentStep`: tmux — plus `ps`+on Linux — the Harness CLI, and on a Linux desktop the clipboard helper). Homebrew, the Apple developer+tools, apt and the curl/tar/sed/awk/sha256sum the CLI installer downloads Node with are *recipes* for a+missing command, kept in `EnvironmentReadiness.plan` and probed top-down only while the command is+missing: a Mac with tmux is never asked about Homebrew, a Mac with Homebrew never about `xcrun`, and a+Linux box with a managed runtime never about curl. The ladder itself is implemented once, in+`cli/scripts/install.sh` (`--host` runs just that half); the macOS Terminal window the app opens is a+log/exit-code frame around it, while the Linux one keeps the app's own apt transaction so its+clock-skew repair stays. Gating readiness on the recipes was what sent a computer whose tmux ran fine+into Terminal to reinstall developer tools after a macOS upgrade — the screen renders `plan`, it does+not infer one.+### Boot and state`lib/main.dart`: `CrashLog.install()` → `loadPersistedSettings()` (theme mode + terminal font, awaiteddiff --git a/desktop/RELEASE.md b/desktop/RELEASE.mdindex 02e3bd2e7..61cee8a93 100644--- a/desktop/RELEASE.md+++ b/desktop/RELEASE.md@@ -58,7 +58,7 @@ Until that managed manifest covers a platform, the desktop build falls back to iofficial Node 22 archive for it. The fallback keeps first-run setup functional but is intentionallynot a replacement for publishing the managed runtime channel before release.-Homebrew and `apt` are still used for **tmux**, which is a separate step and unrelated to Node.+Homebrew and `apt` are still used for **tmux**, which is a separate step and unrelated to Node — and only when tmux is missing; a computer that already runs it is never asked about either.## Two macOS builds — Intel on Skia, Apple Silicon on Impellerdiff --git a/desktop/lib/bootstrap/environment_provisioner.dart b/desktop/lib/bootstrap/environment_provisioner.dartindex 769257b8c..a27c98928 100644--- a/desktop/lib/bootstrap/environment_provisioner.dart+++ b/desktop/lib/bootstrap/environment_provisioner.dart@@ -5,13 +5,20 @@ import 'dart:io';import '../core/harness_cli_runner.dart';/// The CLI-only installer contract for callers that already own host setup.-/// Desktop verifies system tools, the active Linux clipboard helper and tmux-/// before reaching this command, then performs its own complete verification-/// again after Harness lands.+/// 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 —+/// for the Terminal window the app opens when obtaining them needs a+/// 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;const int _linuxAptInstallFailureExitCode = 33;@@ -20,9 +27,20 @@ const String _linuxClockRepairCommand ='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.tmux;/// Harness Desktop is only ready when every command in this list works.@@ -43,7 +61,7 @@ enum EnvironmentSetupPhase {enum EnvironmentSetupMode { automatic, manual }/// Identifies which host setup owns a visible Terminal handoff. Linux can wait-/// on base/clipboard packages even when tmux itself is already ready, so a+/// 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, tmux }@@ -79,6 +97,66 @@ enum EnvironmentStepStatus {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 macOS ladder for tmux, one rung each, and the CLI installer — the+ /// items a plan is assembled from, written down once.+ static const appleDeveloperTools = EnvironmentPlanItem(+ step: EnvironmentStep.tmux,+ title: 'Apple developer tools',+ detail: 'Xcode or Command Line Tools · needed by the Homebrew installer',+ command: '/usr/bin/xcrun --find clang || { if [ -x /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild ]; then sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer; else xcode-select --install; fi; }',+ requiresTerminal: true,+ );++ static const homebrew = EnvironmentPlanItem(+ step: EnvironmentStep.tmux,+ title: 'Homebrew',+ detail: 'Package manager that installs tmux',+ command: '/bin/bash -c "\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',+ requiresTerminal: true,+ );++ static const tmuxViaHomebrew = EnvironmentPlanItem(+ step: EnvironmentStep.tmux,+ title: 'tmux',+ detail: 'Required for every terminal session',+ command: 'eval "\$(/opt/homebrew/bin/brew shellenv 2>/dev/null || /usr/local/bin/brew shellenv)" && brew install tmux',+ );++ static const harnessCli = EnvironmentPlanItem(+ step: EnvironmentStep.harness,+ title: 'Managed Node 20+ & Harness CLI',+ detail: '~/.harness only',+ command: kHarnessDesktopInstallCommand,+ );+}+class EnvironmentReadiness {final Map<EnvironmentStep, EnvironmentStepStatus> steps;final String? message;@@ -89,10 +167,9 @@ class EnvironmentReadiness {final String? terminalLogPath;final String? terminalResultPath;final EnvironmentTerminalSetup? terminalSetup;- final bool systemReady;- final bool? homebrewReady;- final bool? tmuxBinaryReady;- final List<String> missingLinuxPackages;++ /// What setup will install, in order — empty when everything runs.+ final List<EnvironmentPlanItem> plan;const EnvironmentReadiness({required this.steps,@@ -104,10 +181,7 @@ class EnvironmentReadiness {this.terminalLogPath,this.terminalResultPath,this.terminalSetup,- this.systemReady = false,- this.homebrewReady,- this.tmuxBinaryReady,- this.missingLinuxPackages = const [],+ this.plan = const [],});factory EnvironmentReadiness.initial() => EnvironmentReadiness(@@ -117,13 +191,20 @@ class EnvironmentReadiness {},);- bool get isReady =>- systemReady &&- steps.values.every(- (status) =>- status == EnvironmentStepStatus.ready ||- status == EnvironmentStepStatus.notApplicable,- );+ bool get isReady => steps.values.every(+ (status) =>+ status == EnvironmentStepStatus.ready ||+ status == 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 ||@@ -131,6 +212,14 @@ class EnvironmentReadiness {(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,@@ -141,10 +230,7 @@ class EnvironmentReadiness {String? terminalLogPath,String? terminalResultPath,EnvironmentTerminalSetup? terminalSetup,- bool? systemReady,- bool? homebrewReady,- bool? tmuxBinaryReady,- List<String>? missingLinuxPackages,+ List<EnvironmentPlanItem>? plan,bool clearFailure = false,bool clearTerminalHandoff = false,}) => EnvironmentReadiness(@@ -163,10 +249,7 @@ class EnvironmentReadiness {terminalSetup: clearTerminalHandoff? null: terminalSetup ?? this.terminalSetup,- systemReady: systemReady ?? this.systemReady,- homebrewReady: homebrewReady ?? this.homebrewReady,- tmuxBinaryReady: tmuxBinaryReady ?? this.tmuxBinaryReady,- missingLinuxPackages: missingLinuxPackages ?? this.missingLinuxPackages,+ plan: plan ?? this.plan,);}@@ -318,10 +401,7 @@ class EnvironmentProvisioner {String? terminalLogPath,String? terminalResultPath,EnvironmentTerminalSetup? terminalSetup,- bool? systemReady,- bool? homebrewReady,- bool? tmuxBinaryReady,- List<String>? missingLinuxPackages,+ List<EnvironmentPlanItem>? plan,}) {final next = Map<EnvironmentStep, EnvironmentStepStatus>.from(state.steps,@@ -345,15 +425,62 @@ class EnvironmentProvisioner {terminalLogPath: terminalLogPath ?? state.terminalLogPath,terminalResultPath: terminalResultPath ?? state.terminalResultPath,terminalSetup: terminalSetup ?? state.terminalSetup,- systemReady: systemReady ?? state.systemReady,- homebrewReady: homebrewReady ?? state.homebrewReady,- tmuxBinaryReady: tmuxBinaryReady ?? state.tmuxBinaryReady,- missingLinuxPackages:- missingLinuxPackages ?? state.missingLinuxPackages,+ 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.'+ : 'Harness CLI or its managed Node runtime is missing.',+ output: probe.harnessRuns+ ? '✓ managed Node >= 20 · harness version'+ : '✗ managed Node >= 20 · harness version',+ plan: probe.plan,+ );+ return probe;+ }+final previousTerminalLog = state.terminalLogPath;var previousTerminalLogText = '';EnvironmentTerminalSetup? completedTerminalSetup;@@ -426,8 +553,6 @@ class EnvironmentProvisioner {failure: EnvironmentFailure(step: !linuxHost? EnvironmentStep.tmux- : !state.systemReady- ? null: clipboardFailed? EnvironmentStep.clipboard: tmuxFailed@@ -442,7 +567,9 @@ class EnvironmentProvisioner {command:classifiedFailure?.command ??(linuxHost- ? await _linuxHostManualCommand()+ ? await _linuxHostManualCommand(+ _aptPackagesOf(state.plan),+ ): _manualCommandFor(EnvironmentStep.tmux)),exitCode: exitCode,),@@ -472,126 +599,21 @@ class EnvironmentProvisioner {}try {- var linuxMissingBasePackages = <String>[];- String? linuxMissingClipboardPackage;- EnvironmentFailure? systemFailure;- if (_isMacOS) {- systemFailure = await _systemPreflightFailure();- } else {- if (!await _hasWritableHome()) {- systemFailure = const EnvironmentFailure(- title: 'Home directory is not writable',- detail: 'Harness needs to write ~/.harness and ~/.local/bin.',- );- } else {- linuxMissingBasePackages = await _missingLinuxBasePackages();- linuxMissingClipboardPackage = await _missingLinuxClipboardPackage();- }- }- if (systemFailure != null) {+ // The one thing every step needs and no plan can install.+ if (!await _hasWritableHome()) {+ const failure = EnvironmentFailure(+ title: 'Home directory is not writable',+ detail: 'Harness needs to write ~/.harness and ~/.local/bin.',+ );emit(- message: systemFailure.detail,+ message: failure.detail,phase: EnvironmentSetupPhase.failed,- failure: systemFailure,+ failure: failure,);return state;}- // On macOS the developer tools exist for ONE reason here: Homebrew needs- // them to build tmux. A machine that already has a working tmux has- // nothing to build, and must not be sent to a Terminal to fix a- // toolchain it will never use — that is how a desk with tmux 3.6 sat on- // "Xcode is installed but is not the active developer directory" while- // the app waited (2026-09-15: the real cause was an unaccepted Xcode- // licence, which xcrun reports as "not ready" too).- final tmuxAlready = _isMacOS && await _hasTmux();- var systemReady = _isMacOS- ? (tmuxAlready || await _hasAppleDeveloperTools())- : linuxMissingBasePackages.isEmpty;- emit(- systemReady: systemReady,- missingLinuxPackages: _isLinux- ? <String>[- ...linuxMissingBasePackages,- ?linuxMissingClipboardPackage,- ]- : const [],- output: systemReady- ? (tmuxAlready && !await _hasAppleDeveloperTools()- ? '✓ tmux already installed · Apple developer tools not needed'- : '✓ required system tools · writable home')- : _isMacOS- ? '✗ Apple developer tools · xcrun --find clang'- : '✗ missing Linux base packages · ${linuxMissingBasePackages.join(', ')}',- );-- final clipboardApplicable = _isLinux && _linuxClipboardCommand() != null;- var clipboardReady =- !clipboardApplicable || linuxMissingClipboardPackage == null;- emit(- step: EnvironmentStep.clipboard,- status: clipboardApplicable- ? clipboardReady- ? EnvironmentStepStatus.ready- : EnvironmentStepStatus.failed- : EnvironmentStepStatus.notApplicable,- message: clipboardApplicable- ? clipboardReady- ? 'Native image clipboard is ready.'- : '$linuxMissingClipboardPackage is required for native image paste.'- : _isLinux- ? 'Native image clipboard is not applicable on a headless Linux host.'- : null,- output: clipboardApplicable- ? clipboardReady- ? '✓ native image clipboard · ${_linuxClipboardCommand()}'- : '✗ native image clipboard · $linuxMissingClipboardPackage'- : _isLinux- ? '– native image clipboard N/A (headless)'- : null,- );-- final homebrewReady = !_isMacOS || await _hasHomebrew();- var tmuxBinaryReady = await _hasTmux();- // A tmux that runs is a tmux that is ready. Homebrew and the developer- // tools are what INSTALL it; they gate nothing once it is there.- var tmuxReady = tmuxBinaryReady;- emit(- step: EnvironmentStep.tmux,- status: tmuxReady- ? EnvironmentStepStatus.ready- : EnvironmentStepStatus.failed,- message: tmuxReady- ? (_isMacOS ? 'Homebrew and tmux are ready.' : 'tmux is ready.')- : _isMacOS && !systemReady- ? 'Apple developer tools are required.'- : _isMacOS && !homebrewReady- ? 'Homebrew is required.'- : 'tmux is required.',- output: tmuxReady- ? (_isMacOS ? '✓ Homebrew · tmux --version' : '✓ tmux --version')- : _isMacOS && !systemReady- ? '✗ Apple developer tools · xcrun --find clang'- : _isMacOS && !homebrewReady- ? '✗ Homebrew · brew --version'- : '✗ tmux --version',- homebrewReady: _isMacOS ? homebrewReady : null,- tmuxBinaryReady: tmuxBinaryReady,- );-- final harnessReady = await _hasHarness();- emit(- step: EnvironmentStep.harness,- status: harnessReady- ? EnvironmentStepStatus.ready- : EnvironmentStepStatus.failed,- message: harnessReady- ? 'Harness CLI and managed Node are ready.'- : 'Harness CLI or its managed Node runtime is missing.',- output: harnessReady- ? '✓ managed Node >= 20 · harness version'- : '✗ managed Node >= 20 · harness version',- );+ var probe = await probeAndReport();if (state.isReady) {emit(message: 'All required tools passed verification.',@@ -601,12 +623,7 @@ class EnvironmentProvisioner {}if (!install) {- final linuxMissingPackages = <String>[- ...linuxMissingBasePackages,- ?linuxMissingClipboardPackage,- ];- if (terminalResultPending &&- (!systemReady || !clipboardReady || !tmuxReady)) {+ if (terminalResultPending && !state.hostReady) {emit(message:state.message ?? 'Complete the visible prompts in Terminal.',@@ -614,44 +631,46 @@ class EnvironmentProvisioner {);return state;}- if (completedTerminalSetup == EnvironmentTerminalSetup.linuxHost &&- (linuxMissingPackages.isNotEmpty || !tmuxBinaryReady)) {+ if (completedTerminalSetup != null && !state.hostReady) {+ final linuxHost =+ completedTerminalSetup == EnvironmentTerminalSetup.linuxHost;emit(- message: 'The Linux host dependency install finished, but verification still found missing packages.',+ message: linuxHost+ ? 'The Linux host dependency install finished, but verification still found missing packages.'+ : 'The Terminal setup finished, but tmux still did not pass verification.',phase: EnvironmentSetupPhase.failed,failure: EnvironmentFailure(- step: !systemReady- ? null- : linuxMissingClipboardPackage != null+ step: !probe.terminalReady+ ? EnvironmentStep.tmux+ : !probe.clipboardRuns? EnvironmentStep.clipboard- : EnvironmentStep.tmux,+ : null,title: 'Host dependency verification failed',detail:- 'Still missing: ${[...linuxMissingPackages, if (!tmuxBinaryReady) 'tmux'].join(', ')}. Review the Terminal log, then retry when ready.',- command: await _linuxHostManualCommand(),+ 'Still missing: ${probe.missingHostNames.join(', ')}. Review the Terminal log, then retry when ready.',+ command: linuxHost+ ? await _linuxHostManualCommand(probe.aptPackages)+ : _manualCommandFor(EnvironmentStep.tmux),),);return state;}emit(- message: _isLinux && linuxMissingPackages.isNotEmpty- ? 'Linux host packages required: ${linuxMissingPackages.join(', ')}.'+ 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 (base tools,- // tmux and the active clipboard helper) -> managed Node/Harness.- if (_isLinux && (!systemReady || !clipboardReady || !tmuxBinaryReady)) {- var packages = <String>{- ...linuxMissingBasePackages,- ?linuxMissingClipboardPackage,- if (!tmuxBinaryReady) 'tmux',- }.toList();+ // 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();+ final command = await _linuxHostManualCommand(packages);emit(message: 'Automatic Linux package installation supports apt-based distributions only.',phase: EnvironmentSetupPhase.failed,@@ -667,17 +686,10 @@ class EnvironmentProvisioner {ProcessResult? backgroundInstall;if (await _canInstallAptUnattended()) {- if (linuxMissingClipboardPackage != null) {- emit(- step: EnvironmentStep.clipboard,- status: EnvironmentStepStatus.running,- );+ for (final step in probe.missingHostSteps) {+ emit(step: step, status: EnvironmentStepStatus.running);}- emit(- step: tmuxBinaryReady ? null : EnvironmentStep.tmux,- status: tmuxBinaryReady ? null : EnvironmentStepStatus.running,- message: 'Installing Linux system packages…',- );+ emit(message: 'Installing Linux system packages…');try {backgroundInstall = await _shellStreaming(_linuxAptInstallCommand(packages, nonInteractiveSudo: true),@@ -693,26 +705,7 @@ class EnvironmentProvisioner {emit(output: 'Background Linux package install failed: $error');}- linuxMissingBasePackages = await _missingLinuxBasePackages();- linuxMissingClipboardPackage = await _missingLinuxClipboardPackage();- systemReady = linuxMissingBasePackages.isEmpty;- clipboardReady =- !clipboardApplicable || linuxMissingClipboardPackage == null;- tmuxBinaryReady = await _hasTmux();- tmuxReady = tmuxBinaryReady;- emit(- step: EnvironmentStep.clipboard,- status: clipboardApplicable- ? clipboardReady- ? EnvironmentStepStatus.ready- : EnvironmentStepStatus.failed- : EnvironmentStepStatus.notApplicable,- missingLinuxPackages: <String>[- ...linuxMissingBasePackages,- ?linuxMissingClipboardPackage,- ],- tmuxBinaryReady: tmuxBinaryReady,- );+ probe = await probeAndReport();final classifiedBackgroundFailure = backgroundInstall == null? null: _classifiedLinuxPackageFailure(@@ -720,24 +713,11 @@ class EnvironmentProvisioner {_resultText(backgroundInstall),);if (classifiedBackgroundFailure != null) {- if (!tmuxReady) {- emit(- step: EnvironmentStep.tmux,- status: EnvironmentStepStatus.failed,- );- }emit(message: classifiedBackgroundFailure.detail,phase: EnvironmentSetupPhase.failed,- systemReady: systemReady,failure: EnvironmentFailure(- step: !systemReady- ? null- : !clipboardReady- ? EnvironmentStep.clipboard- : !tmuxReady- ? EnvironmentStep.tmux- : null,+ step: probe.missingHostSteps.firstOrNull,title: classifiedBackgroundFailure.title,detail: classifiedBackgroundFailure.detail,command: classifiedBackgroundFailure.command,@@ -746,15 +726,10 @@ class EnvironmentProvisioner {);return state;}- if (systemReady && clipboardReady && tmuxReady) {+ if (probe.aptPackages.isEmpty) {emit(- step: EnvironmentStep.tmux,- status: EnvironmentStepStatus.ready,- message: 'Linux system packages and tmux are ready.',+ message: 'Linux system packages are ready.',output: '✓ Linux host dependencies installed and verified',- systemReady: true,- tmuxBinaryReady: true,- missingLinuxPackages: const [],);} else {if (backgroundInstall != null) {@@ -765,27 +740,14 @@ class EnvironmentProvisioner {'${_resultText(backgroundInstall)}',);}- packages = <String>{- ...linuxMissingBasePackages,- ?linuxMissingClipboardPackage,- if (!tmuxBinaryReady) 'tmux',- }.toList();+ packages = probe.aptPackages;}}- if (!systemReady || !clipboardReady || !tmuxReady) {+ if (probe.aptPackages.isNotEmpty) {final terminal = await _launchLinuxHostSetup(packages);- if (linuxMissingClipboardPackage != null) {- emit(- step: EnvironmentStep.clipboard,- status: EnvironmentStepStatus.needsTerminal,- );- }- if (!tmuxReady) {- emit(- step: EnvironmentStep.tmux,- status: EnvironmentStepStatus.needsTerminal,- );+ 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.',@@ -796,87 +758,65 @@ class EnvironmentProvisioner {terminalLogPath: terminal.log.path,terminalResultPath: terminal.result.path,terminalSetup: EnvironmentTerminalSetup.linuxHost,- systemReady: systemReady,);return state;}}- if (_isMacOS && systemReady && homebrewReady && !tmuxBinaryReady) {- emit(- step: EnvironmentStep.tmux,- status: EnvironmentStepStatus.running,- message: 'Installing tmux via Homebrew…',- );- ProcessResult? installResult;- try {- installResult = await _shellStreaming(- 'brew install tmux',- onOutput: (line) => emit(output: line),- );- } catch (error) {- emit(output: 'Background tmux install failed: $error');- }- tmuxReady = installResult?.exitCode == 0 && await _hasTmux();- if (tmuxReady) {+ if (_isMacOS && !probe.tmuxRuns) {+ if (probe.homebrewInstallsTmux) {+ // Homebrew is here, so tmux is one bottle away and needs no password.emit(step: EnvironmentStep.tmux,- status: EnvironmentStepStatus.ready,- message: 'Homebrew and tmux are ready.',- output: '✓ tmux installed via Homebrew',- homebrewReady: true,- tmuxBinaryReady: true,+ status: EnvironmentStepStatus.running,+ message: 'Installing tmux via Homebrew…',);- } else {- if (installResult != null) {+ ProcessResult? installResult;+ try {+ installResult = await _shellStreaming(+ 'brew install tmux',+ onOutput: (line) => emit(output: line),+ );+ } catch (error) {+ emit(output: 'Background tmux install failed: $error');+ }+ if (installResult?.exitCode == 0 && await _hasTmux()) {emit(- output: installResult.exitCode == 0- ? 'Homebrew finished, but tmux did not pass verification.'- : 'Background tmux install exited ${installResult.exitCode}: '- '${_resultText(installResult)}',+ step: EnvironmentStep.tmux,+ status: EnvironmentStepStatus.ready,+ message: 'tmux is ready.',+ output: '✓ tmux installed via Homebrew',+ plan: state.planWithout(EnvironmentStep.tmux),+ );+ } else {+ if (installResult != null) {+ emit(+ output: installResult.exitCode == 0+ ? 'Homebrew finished, but tmux did not pass verification.'+ : 'Background tmux install exited ${installResult.exitCode}: '+ '${_resultText(installResult)}',+ );+ }+ await _handTmuxToTerminal(+ emit,+ 'Complete the visible Homebrew prompts in Terminal. Harness never sees your password.',+ 'Background install failed; Terminal opened to retry tmux.',);+ return state;}- emit(- step: EnvironmentStep.tmux,- status: EnvironmentStepStatus.running,- message: 'tmux needs attention in Terminal…',- );- final terminal = await _launchTmuxSetup();- emit(- step: EnvironmentStep.tmux,- status: EnvironmentStepStatus.needsTerminal,- message: 'Complete the visible Homebrew prompts in Terminal. Harness never sees your password.',- output: 'Background install failed; Terminal opened to retry tmux.',- phase: EnvironmentSetupPhase.waitingForTerminal,- terminalLogPath: terminal.log.path,- terminalResultPath: terminal.result.path,- terminalSetup: EnvironmentTerminalSetup.tmux,+ } else {+ // Homebrew (and maybe the developer tools) must be installed first,+ // and both ask for a password — a real terminal's job.+ await _handTmuxToTerminal(+ emit,+ 'Complete any password or macOS prompts in Terminal. Harness never sees your password.',+ 'Terminal opened to install ${probe.planFor(EnvironmentStep.tmux).map((item) => item.title).join(', ')}.',);return state;}- } else if (!tmuxReady) {- emit(- step: EnvironmentStep.tmux,- status: EnvironmentStepStatus.running,- message: 'Preparing tmux in a secure terminal…',- );- final terminal = await _launchTmuxSetup();- emit(- step: EnvironmentStep.tmux,- status: EnvironmentStepStatus.needsTerminal,- message: 'Complete any password or macOS prompts in Terminal. Harness never sees your password.',- output: _isMacOS- ? 'Terminal opened to install Homebrew and tmux.'- : 'Terminal opened to install tmux.',- phase: EnvironmentSetupPhase.waitingForTerminal,- terminalLogPath: terminal.log.path,- terminalResultPath: terminal.result.path,- terminalSetup: EnvironmentTerminalSetup.tmux,- );- return state;}- if (!harnessReady) {+ if (!probe.harnessRuns) {emit(step: EnvironmentStep.harness,status: EnvironmentStepStatus.running,@@ -894,46 +834,15 @@ class EnvironmentProvisioner {message: 'Verifying every required command…',phase: EnvironmentSetupPhase.verifying,);- if (_isLinux) {- final missingBase = await _missingLinuxBasePackages();- final missingClipboard = await _missingLinuxClipboardPackage();- final writableHome = await _hasWritableHome();- if (missingBase.isNotEmpty ||- missingClipboard != null ||- !writableHome) {- if (missingClipboard != null) {- emit(- step: EnvironmentStep.clipboard,- status: EnvironmentStepStatus.failed,- );- }- emit(- message:- 'Linux system dependencies did not pass final verification.',- phase: EnvironmentSetupPhase.failed,- systemReady: writableHome && missingBase.isEmpty,- failure: EnvironmentFailure(- title: 'Linux system verification failed',- detail: !writableHome- ? 'The home directory is not writable.'- : 'Still missing packages: ${[...missingBase, ?missingClipboard].join(', ')}',- command: await _linuxHostManualCommand(),- ),- );- return state;- }- }- final finalChecks = <EnvironmentStep, Future<bool> Function()>{- EnvironmentStep.tmux: _isTmuxEnvironmentReady,- EnvironmentStep.harness: _hasHarness,- };- for (final entry in finalChecks.entries) {- if (!await entry.value()) {- emit(step: entry.key, status: EnvironmentStepStatus.failed);- throw StateError(- '${entry.key.name} did not pass final version verification.',- );- }+ await probeAndReport();+ if (!state.isReady) {+ 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;@@ -963,6 +872,126 @@ class EnvironmentProvisioner {}}+ /// Opens the Terminal window that installs tmux (and whatever obtaining it+ /// takes) and leaves the tmux row waiting on it.+ Future<void> _handTmuxToTerminal(+ void Function({+ EnvironmentStep? step,+ EnvironmentStepStatus? status,+ String? message,+ String? output,+ EnvironmentSetupPhase? phase,+ EnvironmentFailure? failure,+ String? terminalLogPath,+ String? terminalResultPath,+ EnvironmentTerminalSetup? terminalSetup,+ List<EnvironmentPlanItem>? plan,+ })+ emit,+ String message,+ String output,+ ) async {+ emit(+ step: EnvironmentStep.tmux,+ status: EnvironmentStepStatus.running,+ message: 'Preparing tmux in a secure terminal…',+ );+ final terminal = await _launchTmuxSetup();+ emit(+ step: EnvironmentStep.tmux,+ status: EnvironmentStepStatus.needsTerminal,+ message: message,+ output: output,+ phase: EnvironmentSetupPhase.waitingForTerminal,+ terminalLogPath: terminal.log.path,+ terminalResultPath: terminal.result.path,+ terminalSetup: EnvironmentTerminalSetup.tmux,+ );+ }++ /// 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 (_isMacOS) {+ final tmuxRuns = await _hasTmux();+ var homebrewInstallsTmux = false;+ if (!tmuxRuns) {+ if (await _hasHomebrew()) {+ homebrewInstallsTmux = true;+ } else {+ // Homebrew's installer is what needs the developer tools — not+ // tmux, and not this app — so they are asked about only here.+ if (!await _hasAppleDeveloperTools()) {+ plan.add(EnvironmentPlanItem.appleDeveloperTools);+ }+ plan.add(EnvironmentPlanItem.homebrew);+ }+ plan.add(EnvironmentPlanItem.tmuxViaHomebrew);+ }+ 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,+ );+ }+/// Windows gets a VERIFY pass rather than the install pass above.////// Every installer this class drives is a POSIX shell script — `install.sh` piped into `/bin/sh`,@@ -1020,81 +1049,38 @@ class EnvironmentProvisioner {);}- Future<EnvironmentFailure?> _systemPreflightFailure() async {- final tools = _isMacOS- ? 'command -v sh zsh bash curl tar sed awk shasum >/dev/null'- : 'command -v sh bash curl tar sed awk sha256sum >/dev/null';- final base = await _shell(tools);- if (base.exitCode != 0) {- return EnvironmentFailure(- title: 'Required system tools are missing',- detail: _resultText(base).isEmpty- ? 'Harness needs curl, tar, sed, awk, checksum tools and a POSIX shell.'- : _resultText(base),- command: _isMacOS- ? 'xcode-select --install'- : 'sudo apt-get install -y bash curl tar sed gawk coreutils',- );- }- if (!await _hasWritableHome()) {- return const EnvironmentFailure(- title: 'Home directory is not writable',- detail: 'Harness needs to write ~/.harness and ~/.local/bin.',- );- }- return null;- }-Future<bool> _hasWritableHome() async {final writable = await _shell('test -w "\$HOME"');return writable.exitCode == 0;}- /// Base packages the desktop needs before it can hand host setup to the- /// CLI-only installer. Native clipboard support is reported separately so- /// the UI can explain it without creating a second install transaction.- Future<List<String>> _missingLinuxBasePackages() async {- if (!_isLinux) return const [];- const commandPackages = <String, String>{- 'sh': 'dash',- 'bash': 'bash',- 'curl': 'curl',- 'tar': 'tar',- 'sed': 'sed',- 'awk': 'gawk',- 'sha256sum': 'coreutils',- };- final missing = <String>[];- for (final entry in commandPackages.entries) {- final probe = await _shell('command -v ${entry.key} >/dev/null 2>&1');- if (probe.exitCode != 0) missing.add(entry.value);- }- return missing.toSet().toList();+ Future<bool> _hasCommand(String command) async {+ final probe = await _shell('command -v $command >/dev/null 2>&1');+ return probe.exitCode == 0;}- /// 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.- Future<String?> _missingLinuxClipboardPackage() async {- if (!_isLinux) return null;- final clipboardCommand = _linuxClipboardCommand();- final clipboardPackage = _linuxClipboardPackage();- if (clipboardCommand != null && clipboardPackage != null) {- final probe = await _shell(- 'command -v $clipboardCommand >/dev/null 2>&1',- );- if (probe.exitCode != 0) return clipboardPackage;- }- return null;+ /// 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 _shell(+ 'for c in ${commands.join(' ')}; do command -v "\$c" >/dev/null 2>&1 || exit 1; done',+ );+ return probe.exitCode == 0;}- Future<List<String>> _missingLinuxHostPackages() async {- final packages = <String>{...await _missingLinuxBasePackages()};- final clipboard = await _missingLinuxClipboardPackage();- if (clipboard != null) packages.add(clipboard);- return packages.toList();- }+ /// 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) {@@ -1110,6 +1096,10 @@ class EnvironmentProvisioner {_ => 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 _shell('command -v apt-get >/dev/null 2>&1');return result.exitCode == 0;@@ -1258,16 +1248,13 @@ elsefi''';}- Future<String> _linuxHostManualCommand() async {- final packages = <String>{- ...await _missingLinuxHostPackages(),- if (!await _hasTmux()) 'tmux',- }.join(' ');- if (packages.isEmpty) return 'Recheck Linux system dependencies.';+ 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: $packages';+ return 'Install with your distribution package manager: $names';}- return 'sudo apt-get install -y $packages';+ return 'sudo apt-get install -y $names';}Future<bool> _hasHarness() async {@@ -1360,13 +1347,6 @@ fi''';return result.exitCode == 0;}- Future<bool> _isTmuxEnvironmentReady() async {- if (await _hasTmux()) return true; // installed is ready, whatever built it- if (_isMacOS && !await _hasAppleDeveloperTools()) return false;- if (_isMacOS && !await _hasHomebrew()) return false;- return false;- }-/// `xcode-select -p` only proves that a path was selected. It also succeeds/// for an incomplete or moved Command Line Tools directory. Resolve a tool/// through xcrun so pre-flight reflects whether Homebrew can actually use@@ -1389,6 +1369,9 @@ fi''';await directory.create(recursive: true);await _run('/bin/chmod', ['700', directory.path]);if (_isMacOS) {+ // The ladder itself — tmux, else Homebrew, else the developer tools+ // first — lives in the CLI installer's `--host` mode, so this window+ // only adds what the app needs from it: a log and an exit code.final script = File('${directory.path}/install-tmux.command');await script.writeAsString('''#!/bin/zshset -e@@ -1407,51 +1390,8 @@ finish() {return "\$status"}trap finish EXIT-apple_developer_tools_ready() {- /usr/bin/xcrun --find clang >/dev/null 2>&1-}-if command -v tmux >/dev/null 2>&1; then- echo 'tmux is already installed. Return to Harness.'- exit 0-fi-if ! apple_developer_tools_ready; then- if [ -x /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild ]; then- # xcrun answers "not ready" for two different reasons, and only one of them is the developer- # directory. An unaccepted Xcode licence exits 69 and no amount of xcode-select fixes it.- if ! /usr/bin/xcodebuild -license check >/dev/null 2>&1; then- echo 'Xcode is installed but its licence has not been accepted.'- echo 'macOS may ask for your password to accept it.'- sudo /usr/bin/xcodebuild -license accept- fi- if ! apple_developer_tools_ready; then- echo 'Xcode is installed but is not the active developer directory.'- echo 'macOS may ask for your password to select it.'- sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer- fi- else- echo 'Apple developer tools are missing. Installing Command Line Tools; finish the macOS dialog to continue.'- xcode-select --install || true- fi- attempts=0- until apple_developer_tools_ready; do- attempts=\$((attempts + 1))- if [ "\$attempts" -ge 200 ]; then- echo 'Apple developer tools did not become ready within 10 minutes.' >&2- echo 'Finish the macOS installer, then retry setup.' >&2- exit 12- fi- sleep 3- done-fi-if ! command -v brew >/dev/null 2>&1; then- echo 'Installing Homebrew (macOS may ask for your password)…'- /bin/bash -c "\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"-fi-eval "\$(/opt/homebrew/bin/brew shellenv 2>/dev/null || /usr/local/bin/brew shellenv)"-if ! command -v tmux >/dev/null 2>&1; then- brew install tmux-fi-echo 'tmux is ready. Return to Harness.'+$kHarnessHostSetupCommand+echo 'Return to Harness.'''', flush: true);await _run('/bin/chmod', ['700', script.path]);return script;@@ -1461,14 +1401,13 @@ echo 'tmux is ready. Return to Harness.': linuxPackages.toSet().toList();final packages = packageList.join(' ');const packageCommands = <String, String>{- 'dash': 'sh',- 'bash': 'bash','curl': 'curl','tar': 'tar','sed': 'sed','gawk': 'awk','coreutils': 'sha256sum','tmux': 'tmux',+ 'procps': 'ps','xclip': 'xclip','wl-clipboard': 'wl-copy',};@@ -1634,3 +1573,81 @@ fiextension 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;++ /// 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.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 (terminalReady) return 'tmux is ready.';+ final titles = planFor(EnvironmentStep.tmux).map((item) => item.title);+ if (homebrewInstallsTmux) return 'tmux will be installed with Homebrew.';+ if (titles.length > 1) {+ return '${titles.join(', then ')} will be installed in Terminal.';+ }+ return '${psRuns ? 'tmux' : 'tmux and ps'} will be installed with apt.';+ }++ String get tmuxOutput {+ if (terminalReady) return '✓ tmux --version';+ final lines = <String>[tmuxRuns ? '✓ tmux --version' : '✗ tmux --version'];+ if (!psRuns) lines.add('✗ ps');+ if (homebrewInstallsTmux) lines.add('✓ brew --version');+ for (final item in planFor(EnvironmentStep.tmux)) {+ if (identical(item, EnvironmentPlanItem.homebrew)) {+ lines.add('✗ brew --version');+ }+ if (identical(item, EnvironmentPlanItem.appleDeveloperTools)) {+ lines.add('✗ xcrun --find clang');+ }+ }+ return lines.join(' · ');+ }+}diff --git a/desktop/lib/bootstrap/environment_step_guidance.dart b/desktop/lib/bootstrap/environment_step_guidance.dartdeleted file mode 100644index 78a3254ce..000000000--- a/desktop/lib/bootstrap/environment_step_guidance.dart+++ /dev/null@@ -1,65 +0,0 @@-import 'environment_provisioner.dart';--/// The exact command to hand the user for a step stuck in [EnvironmentStepStatus.failed] or-/// [EnvironmentStepStatus.needsTerminal], so they can run it themselves instead of only seeing a-/// generic "Retry" with no idea what actually needs to happen. Returns null for any step/status-/// combination that isn't a stuck, self-servable state.-String? environmentStepGuidanceCommand(- EnvironmentStep step,- EnvironmentStepStatus status, {- required bool isMacOS,-}) {- switch (step) {- case EnvironmentStep.clipboard:- if (status != EnvironmentStepStatus.failed &&- status != EnvironmentStepStatus.needsTerminal) {- return null;- }- return 'if [ -n "\${WAYLAND_DISPLAY:-}" ]; then sudo apt-get install -y wl-clipboard; else sudo apt-get install -y xclip; fi';- case EnvironmentStep.harness:- if (status != EnvironmentStepStatus.failed) return null;- // Same URL _ensureHarness() itself curls — see environment_provisioner.dart.- return kHarnessDesktopInstallCommand;- case EnvironmentStep.tmux:- if (status == EnvironmentStepStatus.needsTerminal) {- return isMacOS- ? '/bin/bash -c "\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" && brew install tmux'- : 'sudo apt-get install -y tmux';- }- if (status == EnvironmentStepStatus.failed) {- // The only way tmux itself reaches `failed` rather than `needsTerminal` is a Homebrew- // install that ran and errored (see _ensureTmux) — Homebrew is already present.- return 'brew install tmux';- }- return null;- }-}--/// A short explanation to sit above the command — kept separate from the command itself so the-/// command block stays copy-paste clean.-String environmentStepGuidanceText(- EnvironmentStep step,- EnvironmentStepStatus status, {- required bool isMacOS,-}) {- switch (step) {- case EnvironmentStep.clipboard:- return status == EnvironmentStepStatus.needsTerminal- ? 'The clipboard package is part of the single Host dependencies install. Finish the existing Terminal prompt; do not start a second installer.'- : 'Install the clipboard helper for the active Linux display, then click Recheck.';- case EnvironmentStep.harness:- return 'Run this in a terminal, then click Recheck.';- case EnvironmentStep.tmux:- if (status == EnvironmentStepStatus.needsTerminal) {- final opened = isMacOS- ? 'A Terminal window was opened to install Homebrew and tmux — finish any prompts there.'- : 'A terminal window was opened to install tmux — finish any prompts there.';- final manual = isMacOS- ? "If it didn't open, or you'd rather run it yourself:"- : "If it didn't open, or you'd rather run it yourself (on a non-apt "- "distribution, use your own package manager instead):";- return '$opened $manual';- }- return 'Homebrew is installed but the tmux install itself failed. Run it again yourself:';- }-}diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dartindex b9d9fba29..98df3660a 100644--- a/desktop/lib/state/app_state.dart+++ b/desktop/lib/state/app_state.dart@@ -1707,7 +1707,7 @@ class AppNotifier extends ChangeNotifier {terminalLogPath: value.terminalLogPath,terminalResultPath: value.terminalResultPath,terminalSetup: value.terminalSetup,- systemReady: value.systemReady,+ plan: value.plan,);} else {environmentReadiness = value;@@ -1836,7 +1836,7 @@ class AppNotifier extends ChangeNotifier {}/// Rechecks a single stuck step (`failed`/`needsTerminal`) without re-running steps already- /// `ready` — the user fixed it by hand (see `environment_step_guidance.dart`'s command) and this+ /// `ready` — the user fixed it by hand (with the command the review lists) and this/// confirms it, then falls through to whatever step comes next, exactly like a fresh `bootstrap()`/// would have. [step] identifies which row's Recheck button was pressed; the provisioner itself/// decides what to (re-)attempt from the current [environmentReadiness], so an already-resolved@@ -1858,15 +1858,12 @@ class AppNotifier extends ChangeNotifier {environmentReadiness.phase ==EnvironmentSetupPhase.waitingForTerminal,);+ // Every host step done means only the Harness CLI is left, and that+ // installs in-app without another prompt — so carry on into it.if (!result.isReady &&mode == EnvironmentSetupMode.automatic &&result.phase != EnvironmentSetupPhase.waitingForTerminal &&- result.systemReady &&- result.steps[EnvironmentStep.tmux] == EnvironmentStepStatus.ready &&- (result.steps[EnvironmentStep.clipboard] ==- EnvironmentStepStatus.ready ||- result.steps[EnvironmentStep.clipboard] ==- EnvironmentStepStatus.notApplicable)) {+ result.hostReady) {result = await _runProvisioner(resumeFrom: result,install: true,@@ -1882,7 +1879,7 @@ class AppNotifier extends ChangeNotifier {terminalLogPath: result.terminalLogPath,terminalResultPath: result.terminalResultPath,terminalSetup: result.terminalSetup,- systemReady: result.systemReady,+ plan: result.plan,);}_scheduleEnvironmentRecheck();diff --git a/desktop/lib/widgets/environment_setup_screen.dart b/desktop/lib/widgets/environment_setup_screen.dartindex d374f4fa5..852c7a89d 100644--- a/desktop/lib/widgets/environment_setup_screen.dart+++ b/desktop/lib/widgets/environment_setup_screen.dart@@ -170,7 +170,7 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {Widget _choose(EnvironmentReadiness state) {final mode = state.mode ?? EnvironmentSetupMode.automatic;- final items = _installItems(state);+ final items = state.plan;final count = items.length;final countLabel = '$count ${count == 1 ? 'tool' : 'tools'}';final needsTerminal = items.any((item) => item.requiresTerminal);@@ -286,54 +286,51 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {],);- Widget _checkList(EnvironmentReadiness state, {bool checking = false}) =>- _Panel(- child: Column(- children: [- const _CheckSectionLabel('Host dependencies'),- _CheckRow(- label: 'System tools & writable home',- detail: Platform.isMacOS- ? 'Shell, curl, tar, sed, awk, shasum · Xcode or Command Line Tools'- : 'Shell, curl, tar, sed, awk, sha256sum · writable home',- status: _systemStatus(state),- checking:- checking && state.phase == EnvironmentSetupPhase.preflight,- ),- _CheckRow(- label: Platform.isMacOS- ? 'Homebrew & tmux terminal backend'- : 'tmux terminal backend',- detail: 'Required for every terminal session',- status: state.steps[EnvironmentStep.tmux],- ),- if (Platform.isLinux)- _CheckRow(- label: 'Native image clipboard',- detail: _linuxClipboardDetail,- status: state.steps[EnvironmentStep.clipboard],- ),- const _CheckSectionLabel('Harness components'),- _CheckRow(- label: 'Managed Node 20+ & Harness CLI',- detail: '~/.harness/runtime · harness version',- status: state.steps[EnvironmentStep.harness],- ),- ],+ /// One row per command Harness runs — never one per way of obtaining it.+ /// What obtaining a missing one takes is the row's detail, read off the+ /// plan the provisioner computed.+ Widget _checkList(+ EnvironmentReadiness state, {+ bool checking = false,+ }) => _Panel(+ child: Column(+ children: [+ const _CheckSectionLabel('Host dependencies'),+ _CheckRow(+ label: 'tmux terminal backend',+ detail: _tmuxDetail(state),+ status: state.steps[EnvironmentStep.tmux],+ checking: checking && state.phase == EnvironmentSetupPhase.preflight,),- );+ if (Platform.isLinux)+ _CheckRow(+ label: 'Native image clipboard',+ detail: _linuxClipboardDetail,+ status: state.steps[EnvironmentStep.clipboard],+ checking:+ checking && state.phase == EnvironmentSetupPhase.preflight,+ ),+ const _CheckSectionLabel('Harness components'),+ _CheckRow(+ label: 'Managed Node 20+ & Harness CLI',+ detail: '~/.harness/runtime · harness version',+ status: state.steps[EnvironmentStep.harness],+ checking: checking && state.phase == EnvironmentSetupPhase.preflight,+ ),+ ],+ ),+ );- EnvironmentStepStatus? _systemStatus(EnvironmentReadiness state) {- if (state.systemReady) return EnvironmentStepStatus.ready;- if (state.phase == EnvironmentSetupPhase.preflight) return null;- if (state.phase == EnvironmentSetupPhase.waitingForTerminal &&- state.terminalSetup == EnvironmentTerminalSetup.linuxHost) {- return EnvironmentStepStatus.needsTerminal;+ String _tmuxDetail(EnvironmentReadiness state) {+ const base = 'Required for every terminal session';+ final steps = state.planFor(EnvironmentStep.tmux);+ if (steps.isEmpty) {+ return Platform.isLinux ? '$base · tmux, ps' : base;}- if (state.phase == EnvironmentSetupPhase.installing) {- return EnvironmentStepStatus.running;- }- return EnvironmentStepStatus.failed;+ if (Platform.isLinux) return '$base · installs with apt';+ final titles = steps.map((item) => item.title).toList();+ if (titles.length == 1) return '$base · installs with Homebrew';+ return '$base · installs ${titles.join(', then ')}';}String? get _linuxClipboardPackage {@@ -350,93 +347,7 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {_ => 'Not applicable · image paste uses file-path fallback',};- bool _needsInstall(EnvironmentStepStatus? status) =>- status != EnvironmentStepStatus.ready &&- status != EnvironmentStepStatus.notApplicable;-- List<_InstallItem> _installItems(EnvironmentReadiness state) {- final items = <_InstallItem>[];- final tmuxStatusMissing = _needsInstall(state.steps[EnvironmentStep.tmux]);- final tmuxMissing =- state.tmuxBinaryReady == false ||- (state.tmuxBinaryReady == null && tmuxStatusMissing);-- if (Platform.isMacOS) {- if (!state.systemReady) {- items.add(- const _InstallItem(- title: 'Apple developer tools',- detail: 'Xcode or Command Line Tools',- command: '/usr/bin/xcrun --find clang || { if [ -x /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild ]; then sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer; else xcode-select --install; fi; }',- requiresTerminal: true,- ),- );- }- final homebrewMissing =- state.homebrewReady == false ||- (state.homebrewReady == null && tmuxStatusMissing);- if (homebrewMissing) {- items.add(- const _InstallItem(- title: 'Homebrew',- detail: 'Required package manager for tmux',- command: '/bin/bash -c "\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',- requiresTerminal: true,- ),- );- }- if (tmuxMissing) {- items.add(- const _InstallItem(- title: 'tmux',- detail: 'Required for every terminal session',- command: 'eval "\$(/opt/homebrew/bin/brew shellenv 2>/dev/null || /usr/local/bin/brew shellenv)" && brew install tmux',- ),- );- }- } else if (Platform.isLinux) {- final packages = <String>{...state.missingLinuxPackages};- if (!state.systemReady && packages.isEmpty) {- packages.addAll(const [- 'bash',- 'curl',- 'tar',- 'sed',- 'gawk',- 'coreutils',- ]);- }- if (_needsInstall(state.steps[EnvironmentStep.clipboard]) &&- _linuxClipboardPackage != null) {- packages.add(_linuxClipboardPackage!);- }- if (tmuxMissing) packages.add('tmux');- if (packages.isNotEmpty) {- final names = packages.join(', ');- items.add(- _InstallItem(- title: 'Linux host dependencies',- detail: '$names · one apt transaction',- command: 'sudo apt-get install -y ${packages.join(' ')}',- requiresTerminal: true,- ),- );- }- }-- if (_needsInstall(state.steps[EnvironmentStep.harness])) {- items.add(- const _InstallItem(- title: 'Managed Node 20+ & Harness CLI',- detail: '~/.harness only',- command: kHarnessDesktopInstallCommand,- ),- );- }- return items;- }-- Widget _planList(List<_InstallItem> items) {+ Widget _planList(List<EnvironmentPlanItem> items) {if (items.isEmpty) {return _notice(Icons.check_circle_outline,@@ -487,7 +398,7 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {);}- Widget _manualList(List<_InstallItem> items) => Column(+ Widget _manualList(List<EnvironmentPlanItem> items) => Column(children: [if (items.isEmpty)_notice(@@ -625,7 +536,7 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {Widget _footer(EnvironmentReadiness state) {final busy = widget.notifier.environmentSetupInFlight;final mode = state.mode ?? EnvironmentSetupMode.automatic;- final missingCount = _installItems(state).length;+ final missingCount = state.plan.length;final manual = mode == EnvironmentSetupMode.manual;String? label;VoidCallback? action;@@ -729,20 +640,6 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {}}-class _InstallItem {- final String title;- final String detail;- final String command;- final bool requiresTerminal;-- const _InstallItem({- required this.title,- required this.detail,- required this.command,- this.requiresTerminal = false,- });-}-class _Panel extends StatelessWidget {final Widget child;final EdgeInsetsGeometry padding;diff --git a/desktop/test/boot_flow_widget_test.dart b/desktop/test/boot_flow_widget_test.dartindex 06f1ecbb0..89de7e2d1 100644--- a/desktop/test/boot_flow_widget_test.dart+++ b/desktop/test/boot_flow_widget_test.dart@@ -93,7 +93,6 @@ class _ReadyEnvironmentProvisioner extends EnvironmentProvisioner {for (final step in EnvironmentStep.values)step: EnvironmentStepStatus.ready,},- systemReady: true,);onProgress(ready);return ready;@@ -267,7 +266,6 @@ void main() {},phase: EnvironmentSetupPhase.ready,mode: EnvironmentSetupMode.automatic,- systemReady: true,);final provisioner = _ScriptedEnvironmentProvisioner([missing, ready]);final app = AppNotifier(@@ -320,7 +318,6 @@ void main() {for (final step in EnvironmentStep.values)step: EnvironmentStepStatus.ready,},- systemReady: true,);final storage = _FakeKeyValueStore();final provisioner = _ScriptedEnvironmentProvisioner([stuck, ready]);@@ -398,7 +395,6 @@ void main() {},phase: EnvironmentSetupPhase.waitingForTerminal,mode: EnvironmentSetupMode.automatic,- systemReady: true,);final probing = waiting.copyWith(phase: EnvironmentSetupPhase.preflight);final reviewed = waiting.copyWith(@@ -453,7 +449,17 @@ void main() {phase: EnvironmentSetupPhase.waitingForTerminal,mode: EnvironmentSetupMode.automatic,terminalSetup: EnvironmentTerminalSetup.linuxHost,- systemReady: false,+ plan: [+ EnvironmentPlanItem(+ step: EnvironmentStep.harness,+ title: 'Linux host dependencies',+ detail: 'curl · one apt transaction',+ command: 'sudo apt-get install -y curl',+ requiresTerminal: true,+ packages: ['curl'],+ ),+ EnvironmentPlanItem.harnessCli,+ ],);final provisioner = _ScriptedEnvironmentProvisioner([waiting, waiting]);final app = AppNotifier(@@ -617,9 +623,7 @@ void main() {EnvironmentStep.tmux: EnvironmentStepStatus.ready,},phase: EnvironmentSetupPhase.review,- systemReady: true,- homebrewReady: true,- tmuxBinaryReady: true,+ plan: [EnvironmentPlanItem.harnessCli],);await tester.pumpWidget(ProviderScope(@@ -655,7 +659,6 @@ void main() {step: EnvironmentStepStatus.ready,},phase: EnvironmentSetupPhase.ready,- systemReady: true,),]);final app = AppNotifier(@@ -672,9 +675,7 @@ void main() {EnvironmentStep.tmux: EnvironmentStepStatus.ready,},phase: EnvironmentSetupPhase.review,- systemReady: true,- homebrewReady: true,- tmuxBinaryReady: true,+ plan: [EnvironmentPlanItem.harnessCli],);await tester.pumpWidget(ProviderScope(@@ -706,9 +707,7 @@ void main() {},phase: EnvironmentSetupPhase.chooseMethod,mode: EnvironmentSetupMode.automatic,- systemReady: true,- homebrewReady: false,- tmuxBinaryReady: false,+ plan: [EnvironmentPlanItem.homebrew, EnvironmentPlanItem.tmuxViaHomebrew],);await tester.pumpWidget(ProviderScope(@@ -749,9 +748,7 @@ void main() {},phase: EnvironmentSetupPhase.chooseMethod,mode: EnvironmentSetupMode.automatic,- systemReady: true,- homebrewReady: true,- tmuxBinaryReady: true,+ plan: [EnvironmentPlanItem.harnessCli],);await tester.pumpWidget(ProviderScope(@@ -768,30 +765,49 @@ void main() {expect(find.text('Admin prompts stay in Terminal'), findsNothing);});- testWidgets('review marks unusable Apple developer tools as missing', (- tester,- ) async {- final app = makeNotifier(AppStatus.preparingEnvironment);- app.environmentReadiness = const EnvironmentReadiness(- steps: {- EnvironmentStep.harness: EnvironmentStepStatus.ready,- EnvironmentStep.tmux: EnvironmentStepStatus.ready,- },- phase: EnvironmentSetupPhase.review,- systemReady: false,- );- await tester.pumpWidget(- ProviderScope(- overrides: [appStateProvider.overrideWithValue(app)],- child: const DesktopApp(),- ),- );- await tester.pump();+ testWidgets(+ 'review lists the whole ladder when neither tmux nor Homebrew nor Xcode is there',+ (tester) async {+ // The plan is the provisioner's, in ladder order: the developer tools+ // appear only because Homebrew was found missing, Homebrew only because+ // tmux was.+ final app = makeNotifier(AppStatus.preparingEnvironment);+ app.environmentReadiness = const EnvironmentReadiness(+ steps: {+ EnvironmentStep.clipboard: EnvironmentStepStatus.notApplicable,+ EnvironmentStep.harness: EnvironmentStepStatus.ready,+ EnvironmentStep.tmux: EnvironmentStepStatus.failed,+ },+ phase: EnvironmentSetupPhase.review,+ plan: [+ EnvironmentPlanItem.appleDeveloperTools,+ EnvironmentPlanItem.homebrew,+ EnvironmentPlanItem.tmuxViaHomebrew,+ ],+ );+ await tester.pumpWidget(+ ProviderScope(+ overrides: [appStateProvider.overrideWithValue(app)],+ child: const DesktopApp(),+ ),+ );+ await tester.pump();- expect(find.text('Apple developer tools'), findsOneWidget);- expect(find.text('Install 1 tool'), findsOneWidget);- expect(find.text('tmux'), findsNothing);- });+ expect(find.text('Apple developer tools'), findsOneWidget);+ expect(find.text('Homebrew'), findsOneWidget);+ expect(find.text('tmux'), findsOneWidget);+ expect(find.text('Install 3 tools'), findsOneWidget);+ expect(+ tester.getTopLeft(find.text('Apple developer tools')).dy,+ lessThan(tester.getTopLeft(find.text('Homebrew')).dy),+ );+ expect(+ tester.getTopLeft(find.text('Homebrew')).dy,+ lessThan(tester.getTopLeft(find.text('tmux')).dy),+ );+ expect(find.text('Apple developer tools'), findsOneWidget);+ },+ );testWidgets('RootShell rebuilds to LoginScreen when status flips after boot', (tester,diff --git a/desktop/test/environment_provisioner_test.dart b/desktop/test/environment_provisioner_test.dartindex 3839f19d7..a6b0ee32c 100644--- a/desktop/test/environment_provisioner_test.dart+++ b/desktop/test/environment_provisioner_test.dart@@ -54,6 +54,12 @@ void main() {for (final missing in missingCommands) {if (shell.contains('command -v $missing ')) return result(1);}+ // `for c in a b c; do command -v "$c" …` — the all-of-these probe.+ final loop = RegExp(r'for c in ([^;]+); do command -v').firstMatch(shell);+ if (loop != null) {+ final names = loop.group(1)!.trim().split(' ');+ return names.any(missingCommands.contains) ? result(1) : result(0);+ }if (shell.contains('apt_as_root install -y')) {final packages = <String>[for (final package in [@@ -65,6 +71,7 @@ void main() {'gawk','coreutils','tmux',+ 'procps','xclip','wl-clipboard',])@@ -161,11 +168,13 @@ void main() {},);- test('an installed tmux is ready whatever the developer tools say', () async {- // The developer tools exist to BUILD tmux. With tmux already there, an- // unusable toolchain — an unselected directory, an unaccepted licence —- // must not stand between the person and the app; it did, for a whole- // morning, on a desk with tmux 3.6 and an Xcode licence never clicked.+ // The macOS ladder, one rung at a time. Each rung is probed only when the+ // one above it is missing: tmux, else Homebrew, else the developer tools.+ test('a computer with tmux is ready without Apple developer tools or Homebrew', () async {+ // The tools are how tmux gets INSTALLED, not how it runs. A `brew install`+ // from last year keeps working after a macOS upgrade invalidated the+ // Command Line Tools or an Xcode update left its licence unaccepted —+ // and this used to send that computer into Terminal to reinstall them.var terminalLaunches = 0;final calls = <String>[];final provisioner = EnvironmentProvisioner(@@ -175,33 +184,39 @@ void main() {openTerminal: (_) async => terminalLaunches++,run: runner(developerToolsPresent: false,+ homebrewPresent: () => false,tmuxPresent: () => true,+ installHarness: createManagedHarness,calls: calls,),);final readiness = await provisioner.ensureReady(onProgress: (_) {},- install: false,+ install: true,+ mode: EnvironmentSetupMode.automatic,);- expect(readiness.systemReady, isTrue);- expect(readiness.tmuxBinaryReady, isTrue);+ expect(readiness.isReady, isTrue, reason: readiness.output.join('\n'));expect(readiness.steps[EnvironmentStep.tmux], EnvironmentStepStatus.ready);- expect(readiness.output.join('\n'), contains('tmux already installed'));+ expect(readiness.plan, isEmpty);+ expect(+ calls.any((line) => line.contains('/usr/bin/xcrun --find clang')),+ isFalse,+ );+ expect(calls.any((line) => line.contains('brew --version')), isFalse);expect(terminalLaunches, 0);});- test('an unusable selected developer directory is shown as missing when tmux is absent', () async {- var terminalLaunches = 0;+ test('with Homebrew present the plan is tmux alone and Xcode is never asked about', () async {final calls = <String>[];final provisioner = EnvironmentProvisioner(harnessHome: scratch,isMacOS: true,isLinux: false,- openTerminal: (_) async => terminalLaunches++,run: runner(developerToolsPresent: false,+ homebrewPresent: () => true,tmuxPresent: () => false,calls: calls,),@@ -213,16 +228,64 @@ void main() {);expect(readiness.phase, EnvironmentSetupPhase.review);- expect(readiness.systemReady, isFalse);- expect(readiness.output.join('\n'), contains('xcrun --find clang'));+ expect(readiness.plan.map((item) => item.title), [+ 'tmux',+ 'Managed Node 20+ & Harness CLI',+ ]);+ expect(readiness.plan.first.requiresTerminal, isFalse);expect(calls.any((line) => line.contains('/usr/bin/xcrun --find clang')),- isTrue,+ isFalse,);- expect(terminalLaunches, 0);+ expect(readiness.output.join('\n'), contains('✓ brew --version'));+ });++ test('without Homebrew the developer tools are probed, and listed only when missing', () async {+ for (final developerTools in [true, false]) {+ final calls = <String>[];+ final provisioner = EnvironmentProvisioner(+ harnessHome: scratch,+ isMacOS: true,+ isLinux: false,+ run: runner(+ developerToolsPresent: developerTools,+ homebrewPresent: () => false,+ tmuxPresent: () => false,+ calls: calls,+ ),+ );++ final readiness = await provisioner.ensureReady(+ onProgress: (_) {},+ install: false,+ );++ expect(readiness.phase, EnvironmentSetupPhase.review);+ expect(+ calls.where((line) => line.contains('/usr/bin/xcrun --find clang')),+ hasLength(1),+ reason: 'developerTools=$developerTools',+ );+ expect(readiness.plan.map((item) => item.title), [+ if (!developerTools) 'Apple developer tools',+ 'Homebrew',+ 'tmux',+ 'Managed Node 20+ & Harness CLI',+ ]);+ expect(+ readiness.plan.where((item) => item.requiresTerminal).length,+ developerTools ? 1 : 2,+ );+ expect(+ readiness.output.join('\n'),+ developerTools+ ? isNot(contains('xcrun --find clang'))+ : contains('✗ xcrun --find clang'),+ );+ }});- test('automatic setup repairs or installs Apple developer tools in Terminal', () async {+ test('automatic setup hands the Homebrew rungs to Terminal, through the installer', () async {String? terminalScript;final calls = <String>[];final provisioner = EnvironmentProvisioner(@@ -232,6 +295,7 @@ void main() {openTerminal: (path) async => terminalScript = path,run: runner(developerToolsPresent: false,+ homebrewPresent: () => false,tmuxPresent: () => false,calls: calls,),@@ -244,24 +308,22 @@ void main() {);expect(readiness.phase, EnvironmentSetupPhase.waitingForTerminal);- expect(readiness.systemReady, isFalse);- expect(readiness.homebrewReady, isTrue);- expect(readiness.tmuxBinaryReady, isFalse);+ expect(+ readiness.steps[EnvironmentStep.tmux],+ EnvironmentStepStatus.needsTerminal,+ );+ expect(readiness.terminalSetup, EnvironmentTerminalSetup.tmux);expect(terminalScript, isNotNull);+ expect(calls.where((line) => line.contains('brew install tmux')), isEmpty);expect(calls.where((line) => line.contains('install.sh')), isEmpty);+ // The ladder lives in the CLI installer's host mode; the window only adds+ // the log and exit code the app polls.final script = await File(terminalScript!).readAsString();- expect(script, contains('/usr/bin/xcrun --find clang'));- expect(- script,- contains(- 'sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer',- ),- );- expect(script, contains('xcode-select --install'));- expect(script, contains('xcodebuild -license accept'));- expect(script, contains("tmux is already installed"));- expect(script, contains('did not become ready within 10 minutes'));- expect(script, contains('if ! command -v tmux'));+ expect(script, contains(kHarnessHostSetupCommand));+ expect(script, contains('terminal.log'));+ expect(script, contains('terminal.exit'));+ expect(script, isNot(contains('xcode-select')));+ expect(script, isNot(contains('brew install')));if (File('/bin/zsh').existsSync()) {expect((await Process.run('/bin/zsh', ['-n', terminalScript!])).exitCode,@@ -296,8 +358,7 @@ void main() {);expect(readiness.isReady, isTrue);- expect(readiness.homebrewReady, isTrue);- expect(readiness.tmuxBinaryReady, isTrue);+ expect(readiness.plan, isEmpty);expect(terminalLaunches, 0);expect(calls.where((line) => line.contains('brew install tmux')),@@ -339,41 +400,6 @@ void main() {expect(readiness.output.join('\n'), contains('Terminal opened to retry'));});- test(- 'missing Homebrew still opens Terminal before installing tmux',- () async {- String? terminalScript;- final calls = <String>[];- final provisioner = EnvironmentProvisioner(- harnessHome: scratch,- isMacOS: true,- isLinux: false,- openTerminal: (path) async => terminalScript = path,- run: runner(- homebrewPresent: () => false,- tmuxPresent: () => false,- calls: calls,- ),- );-- final readiness = await provisioner.ensureReady(- onProgress: (_) {},- install: true,- mode: EnvironmentSetupMode.automatic,- );-- expect(readiness.phase, EnvironmentSetupPhase.waitingForTerminal);- expect(readiness.homebrewReady, isFalse);- expect(readiness.tmuxBinaryReady, isFalse);- expect(terminalScript, isNotNull);- expect(- calls.where((line) => line.contains('brew install tmux')),- isEmpty,- );- expect(readiness.output.join('\n'), contains('brew --version'));- },- );-test('automatic setup installs Harness, then verifies', () async {final calls = <String>[];final provisioner = EnvironmentProvisioner(@@ -458,7 +484,6 @@ void main() {);expect(readiness.phase, EnvironmentSetupPhase.waitingForTerminal);- expect(readiness.systemReady, isTrue);expect(readiness.steps[EnvironmentStep.tmux],EnvironmentStepStatus.ready,@@ -853,7 +878,7 @@ void main() {EnvironmentStepStatus.needsTerminal,);final script = await File(terminalScript!).readAsString();- expect(script, contains('apt_as_root install -y xclip tmux'));+ expect(script, contains('apt_as_root install -y tmux xclip'));expect(script,contains('This window will close automatically in 5 seconds.'),@@ -866,6 +891,97 @@ void main() {},);+ test('a Linux computer that runs tmux, ps and Harness is ready whatever else it lacks', () async {+ // curl, tar and the rest download the runtime; with the runtime here they+ // are not asked about, and neither is apt.+ await createManagedHarness();+ final calls = <String>[];+ final provisioner = EnvironmentProvisioner(+ harnessHome: scratch,+ isMacOS: false,+ isLinux: true,+ platformEnvironment: const {},+ run: runner(+ tmuxPresent: () => true,+ aptPresent: false,+ missingCommands: const {'curl', 'tar', 'sed', 'awk', 'sha256sum'},+ calls: calls,+ ),+ );++ final readiness = await provisioner.ensureReady(+ onProgress: (_) {},+ install: false,+ );++ expect(readiness.isReady, isTrue, reason: readiness.output.join('\n'));+ expect(readiness.plan, isEmpty);+ expect(calls.any((line) => line.contains('command -v curl ')), isFalse);+ expect(calls.any((line) => line.contains('for c in tar')), isFalse);+ expect(calls.any((line) => line.contains('command -v apt-get')), isFalse);+ });++ test('a missing ps joins tmux in the one apt transaction', () async {+ await createManagedHarness();+ final provisioner = EnvironmentProvisioner(+ harnessHome: scratch,+ isMacOS: false,+ isLinux: true,+ platformEnvironment: const {},+ run: runner(tmuxPresent: () => false, missingCommands: const {'ps'}),+ );++ final readiness = await provisioner.ensureReady(+ onProgress: (_) {},+ install: false,+ );++ expect(readiness.steps[EnvironmentStep.tmux], EnvironmentStepStatus.failed);+ expect(readiness.plan.single.packages, ['tmux', 'procps']);+ expect(readiness.plan.single.requiresTerminal, isTrue);+ expect(readiness.output.join('\n'), contains('✗ ps'));+ });++ test(+ 'curl is added to the transaction only because Harness must be downloaded',+ () async {+ final calls = <String>[];+ final provisioner = EnvironmentProvisioner(+ harnessHome: scratch,+ isMacOS: false,+ isLinux: true,+ platformEnvironment: const {},+ run: runner(+ tmuxPresent: () => true,+ missingCommands: const {'curl'},+ calls: calls,+ ),+ );++ final readiness = await provisioner.ensureReady(+ onProgress: (_) {},+ install: false,+ );++ expect(+ readiness.steps[EnvironmentStep.tmux],+ EnvironmentStepStatus.ready,+ );+ expect(readiness.plan.map((item) => item.title), [+ 'Linux host dependencies',+ 'Managed Node 20+ & Harness CLI',+ ]);+ expect(readiness.plan.first.packages, ['curl']);+ expect(readiness.plan.first.step, EnvironmentStep.harness);+ // One probe for the lot; the per-tool probes run only when it fails.+ expect(+ calls.where((line) => line.contains('for c in tar')),+ hasLength(1),+ );+ expect(calls.any((line) => line.contains('command -v tar ')), isFalse);+ },+ );+test('missing Linux base tools are installed before Harness', () async {var tmuxPresent = true;var curlPresent = false;diff --git a/desktop/test/environment_recheck_timer_test.dart b/desktop/test/environment_recheck_timer_test.dartindex e88ee4587..64b634a1e 100644--- a/desktop/test/environment_recheck_timer_test.dart+++ b/desktop/test/environment_recheck_timer_test.dart@@ -77,7 +77,6 @@ void main() {},phase: EnvironmentSetupPhase.ready,mode: EnvironmentSetupMode.automatic,- systemReady: true,);final provisioner = _ScriptedProvisioner([review, waiting, ready]);final app = AppNotifier(diff --git a/desktop/test/environment_setup_screen_test.dart b/desktop/test/environment_setup_screen_test.dartindex 53bfb1b6c..f2b9ae081 100644--- a/desktop/test/environment_setup_screen_test.dart+++ b/desktop/test/environment_setup_screen_test.dart@@ -18,8 +18,14 @@ const _review = EnvironmentReadiness(EnvironmentStep.harness: EnvironmentStepStatus.failed,},phase: EnvironmentSetupPhase.review,- homebrewReady: false,- tmuxBinaryReady: false,+ // The full ladder — nothing on this computer — so the layout tests see the+ // longest plan the screen can render.+ plan: [+ EnvironmentPlanItem.appleDeveloperTools,+ EnvironmentPlanItem.homebrew,+ EnvironmentPlanItem.tmuxViaHomebrew,+ EnvironmentPlanItem.harnessCli,+ ],);class _Login extends CliLogin {@@ -262,7 +268,6 @@ void main() {EnvironmentStep.harness: EnvironmentStepStatus.ready,},phase: EnvironmentSetupPhase.ready,- systemReady: true,),);await tester.pump();diff --git a/desktop/test/profile_startup_test.dart b/desktop/test/profile_startup_test.dartindex b8d12e343..ee069c713 100644--- a/desktop/test/profile_startup_test.dart+++ b/desktop/test/profile_startup_test.dart@@ -58,7 +58,6 @@ class _Environment extends EnvironmentProvisioner {for (final step in EnvironmentStep.values)step: EnvironmentStepStatus.ready,},- systemReady: true,phase: EnvironmentSetupPhase.ready,);onProgress(ready);