feat(desktop): add fresh setup checks and terminal handoff

apps/desktop/DESIGN.md

@@ -162,25 +162,26 @@ snapshot, only counts and nothing else.
 
 ## 2. First-run onboarding
 
-Shown on first launch and from the Doctor row ("Run setup again"). One card per
+Shown when fresh launch checks find unresolved setup, and from the Doctor row
+("Run setup again"). No persisted first-run flag. One card per
 check, in order. Every check is read-only; every card offers **Check again**.
 
 ![Onboarding](diagrams/onboarding.svg) ([source](diagrams/onboarding.mmd))
 
 | Step | Read-only check | Fix | Admin | Skipped / unknown shows |
 |---|---|---|---|---|
-| CLI | `hack --version` (text; R1 for JSON) | `brew install hack-dance/tap/hack` (copy) | no | Cannot skip |
+| CLI | `hack --version` (text; R1 for JSON) | v5 install documentation; select the supported executable for the app | no | Cannot skip |
 | Docker (Compose projects) | `runtime_ok` from `/v1/projects` or `hack projects --json` (Docker only) | open Docker Desktop / Docker docs | no | "Docker not reachable" on Compose projects only |
 | Native runtime (native projects) | native `ps` `data.status` per native project (`runtime_not_running` etc.) | native setup doc (HACK-2193) | no | that native project shows Unknown; Compose projects unaffected |
 | hackd | `hack daemon status --json` | `hack daemon start` | no | Status bar "hackd off"; slower refresh |
 | Routing and DNS (Compose) | macOS: doctor `resolver:<tld>`, `dnsmasq.conf:<tld>`, `dnsmasq:53` and `coredns forwarding` (all must pass). Linux: doctor `linux dns route`. Never `hack global status` (can start Docker) | `hack global install` | **yes** | URLs greyed "DNS not set up"; "unknown" when a check is missing |
 | Routing and DNS (native) | `hack doctor --browser-url <project URL>` → `native host dns` (absent without `--browser-url`) | none from the app: `hack global install` refuses native; link to the native setup doc (HACK-2193) | — | "unknown" |
-| Certificate trust (Compose) | **Unknown** today: doctor `caddy local ca` checks the exported CA, not system or browser trust (R16) | `hack global trust` | **yes** | Lock icon on URLs: "browser may warn" |
+| Certificate trust (Compose) | doctor `local ca trust` when available (system and Linux NSS); **Unknown** on older CLIs. `caddy local ca` checks only the exported CA, never trust (R16) | `hack global trust` | **yes** | Lock icon on URLs: "browser may warn" |
 | Certificate trust (native) | doctor `native root trust` | none from the app: `hack global trust` refuses native; doc link | — | "unknown" |
-| Login service | `daemon status` `service.installed` | `hack daemon install` | no | Always-on switch disabled |
+| Login service | `daemon status` `service.installed` | `hack daemon install` only with explicit manager availability, ordinary home and guards permitting it; otherwise docs | no | Always-on switch disabled |
 
-Skips are not stored: the next check finds the step still open and Doctor lists
-it. Non-admin **Run** executes the command and shows its output, then re-checks.
+Skips are memory-only for the app session and survive checks. The next launch
+finds the step still open and Doctor lists it. Non-admin **Run** executes the command and shows its output, then re-checks.
 Admin steps offer **Copy command** and **Open Terminal**; neither is assumed to
 have succeeded until **Check again** (also run when the window regains focus).
 

apps/desktop/README.md

@@ -215,10 +215,177 @@ observations, not locks against concurrent same-user changes.
 
 ## What v0 does not do yet
 
-The Activity tab, CPU and memory, onboarding, always-on, daemon actions and
+The Activity tab, CPU and memory, always-on, broader daemon controls and
 upgrades come in later units. The design and the CLI/daemon requests they need
 are in `DESIGN.md` (PR #800).
 
+## Setup
+
+![Setup evidence flow](diagrams/setup-evidence.svg) ([source](diagrams/setup-evidence.mmd))
+
+On launch, fresh background checks determine whether setup is needed. The app
+supports Hack CLI 5.x; the CLI card cannot be skipped. Doctor offers **Run setup
+again**. Every card offers **Check again**. Skips last for this app session, survive rechecks,
+and never count as passed. Continue permits unresolved optional steps once the
+CLI is available; the next launch checks everything again. No first-run flag,
+setup results or command output are saved.
+
+Cards cover CLI, Compose Docker, each native runtime, hackd, routing, trust and
+the login service. Docker readiness comes from the machine Doctor run's `docker
+daemon` check, which uses the app's checked Docker selectors; a running hackd's
+own `runtime_ok` describes the engine in the daemon's environment and is not used. An empty registry checks Compose prerequisites. A native-only
+registry offers native documentation instead of global install/trust. Native DNS
+stays Unknown when doctor did not receive a browser URL. Compose macOS DNS needs
+all built-in resolver/dnsmasq pairs, any reported/custom host domain, port 53 and
+CoreDNS forwarding. Linux requires `linux dns route`. Missing checks stay Unknown.
+Only the explicit `local ca trust` check can prove Compose trust; `caddy local ca`
+only proves export. Older CLIs without R16 leave trust Unknown.
+
+Setup observes with a version-matched hackd snapshot, native `ps`, `daemon status
+--json`, socket status and bounded Doctor reads. Every automatic `daemon status`
+read (Setup, project polling, the install pre-check) runs with Doctor's private
+tool PATH, interpreter startup variables removed and no `docker` at all: the
+CLI's status command would otherwise run `docker info` and the service manager
+from the ordinary PATH, although the JSON answer uses neither Docker result. CLI project listing is refused
+until R18 because it writes the registry; unavailable project coverage stays Unknown. It never observes through
+`global status`. A setup refresh has a 120-second budget (plus the bounded socket
+read); individual commands and Doctor cleanup also have deadlines. Native checks
+not reached within the budget remain Unknown. `running` plus the socket version
+matching the CLI proves hackd; bare status exit zero does not. `service.installed`
+proves installation only; known disabled/drifted/failed service metadata stays
+Needs attention. Missing service-manager availability never permits Install.
+
+Start and Install, and the project pane's Start/Restart hackd recovery, pass the
+selected CLI as the CLI's self-invocation selector (`HACK_MCP_COMMAND`), so the daemon they start or install runs that CLI, not
+whatever `hack` is first on PATH. Only the fixed `daemon start` and supported `daemon install` actions offer **Run**, with
+bounded, memory-only output followed by fresh checks. Install requires explicit
+`service.available: true`, an ordinary home, and no launchd/systemd-disable guard;
+otherwise the card explains why and links to documentation. Availability is checked
+again immediately before install; an unavailable or unconfirmed manager is refused
+before an install command is submitted. Admin cards offer **Copy
+command** and **Open Terminal**. Both run later, outside the app, so the bound
+command's PATH keeps only directories no other user can change (owner- or
+root-owned, not group- or other-writable, with Doctor's ancestry and ACL rule;
+`/usr/bin:/bin` when none remain). The private one-use `.command` script quotes every
+argument, prints the command and waits for Enter. Afterward it shows the exit code
+and waits for Enter to close, preserving output and the command’s exit code. macOS requests a new window
+of the system Terminal through `open -g -a /System/Applications/Utilities/Terminal.app`
+(by path, not by application name; the bundle and every directory above it must be
+root-owned and not group- or other-writable, otherwise Copy only); Linux uses `xdg-terminal-exec` when available,
+otherwise Copy. The adapter must pass the same ownership, write and `#!` rules
+as the CLI before it runs. The script's temporary directory must not be changeable by
+another user (owned by this user, or by root and sticky like `/tmp`, with the
+same rule for every directory above it); otherwise the hand-off is refused. No existing pane is typed into and no password is requested by
+the app. The script removes itself and its private directory after use or
+cancellation; a terminal that never executes the script may leave that private
+temp directory behind. Launching a terminal never proves a fix succeeded.
+GPUI's window activation observer rechecks only when Setup is shown or an explicit
+fix is pending;
+visible setup also refreshes every ten minutes. Actual host focus and terminal
+behavior still need macOS/Linux live qualification; tests use injected launchers.
+
+Offline examples (no CLI, terminal or services):
+
+```sh
+cargo run -p hack-desktop -- --setup-fixture partial --theme dark
+cargo run -p hack-desktop-core --bin hack-desktop-state -- --setup-fixture native-unknown
+```
+
+Other setup fixtures: `missing-cli`, `ready`, `service-unavailable`. `--screenshots` renders all five
+in light and dark offscreen. Evidence: [light](screenshots/setup-light.png),
+[dark](screenshots/setup-dark.png).
+
+Reusable terminal API (`core::terminal`): `CommandSpec { program, args }` provides
+`display()` with shell quoting; `Script::create(temp_root, &spec)` owns the private
+script; `open(Platform, linux_adapter, &dyn Launcher)` transfers cleanup to the
+script after launch. `Launcher::launch(program, args)` is the injected boundary;
+`SystemLauncher` is used only on explicit live clicks. `linux_adapter()` discovers
+an absolute `xdg-terminal-exec`. Build upgrade commands from authored argv, never
+from arbitrary CLI finding text. `Report::command(args)` uses the checked absolute
+CLI and its captured context. It never rediscovers PATH at click time.
+
+The CLI setup card links to [v5 installation](../../docs/versions/v5/install.md),
+not the stable v4 Homebrew command. A terminal shell function does not change the
+app's executable. Select a prepared supported CLI explicitly when launching:
+
+```sh
+HACK_DESKTOP_CLI="$HOME/.hack-next/bin/hack-next" HACK_RUNTIME_BACKEND=compose hack-desktop
+```
+
+`HACK_DESKTOP_CLI` must be an absolute executable path. This selects the CLI for
+checks, safe actions and terminal hand-offs; it does not install anything or
+change PATH. Without it, the app finds `hack` on absolute PATH entries once and
+pins that executable for every later read and action; only setup checks
+(startup and **Check again**) search PATH again, so installing into an existing
+PATH directory recovers through **Check again** without restarting. A `hack`
+whose file or any directory above it is writable by group or others, or owned
+by another user, is refused before it runs. An explicit `HACK_DESKTOP_CLI` selection gets the same
+check before every use; a missing one is a missing CLI. A script CLI's `#!` interpreter must
+pass the same rule with no arguments (`#!/usr/bin/env` is refused here because
+the CLI uses the ordinary PATH). The app inherits PATH at launch; a changed PATH still needs a
+relaunch. Follow the installation page's platform limits and existing-v4 migration
+steps before using a candidate against a shared home.
+On Linux, this preview requires a separately prepared source-built 5.x CLI; the
+Apple Silicon prerelease download is not a Linux installer.
+
+Execution context (`core::execution::ExecutionContext`) reads only the allowlisted
+non-secret HOME, HACK_HOME, PATH, backend, launchd/systemd-disable guards,
+daemon-autostart guard, optional XDG_RUNTIME_DIR and an absolute XDG_CONFIG_HOME
+(which selects the systemd user unit; a relative one is ignored, as the CLI does). Docker
+selectors are kept when supported (`DOCKER_CONTEXT` as a plain name, an absolute
+`DOCKER_CONFIG`, and a `unix://` absolute, `tcp://` or `ssh://` `DOCKER_HOST`);
+any other value refuses the checked context rather than silently addressing a
+different Docker engine. Absolute `HACK_NATIVE_HOME`, `HACK_NATIVE_BINARY` and `HACK_GLOBAL_CONFIG_PATH` are kept
+the same way (relative values refuse), so native reads and actions address one
+runtime. An absent HACK_HOME stays
+absent so a candidate launcher can keep its own private-home default. Context is
+captured before version checking. `runner(checked_program)` pins that absolute
+executable, clears the child environment and applies the context for all reads
+and actions. `bind(&CommandSpec)` wraps authored argv in `/usr/bin/env -i` with
+individually quoted assignments, so a macOS Terminal login environment cannot
+select another home/backend or weaken a guard. Unknown keys, invalid paths,
+control characters and unsupported backends are refused. Wrapper-specific or
+credential environment is never forwarded; such integrations need an explicitly
+supported context or a manual documented workflow. `CommandSpec` and the
+single-command `Script::create` API remain compatible; a sequence consumer can
+bind each authored spec before composing it. The launcher also clears its inherited environment, carrying only fixed non-secret
+desktop routing metadata needed to open a terminal. Both the script and private directory
+are 0700 because the launch adapter executes the script.
+
+Machine effects share `HackApp::action_busy()` (including
+`AppModel::has_in_flight()` for every project); project effects check
+`machine_action_busy()`. New daemon/upgrade controls must extend that shared gate.
+Checks clear an older action receipt; the immediate post-action check retains its
+receipt once. A transient version timeout remains Unknown and does not force a
+project pane back into setup as though the CLI were missing.
+
+Remaining evidence limits: an installed unit without newer operational metadata
+proves installation, not enabled/healthy service operation. Native DNS remains
+Unknown without a checked browser URL. macOS custom/localhost suffixes without
+matching Doctor resolver evidence remain Unknown, even if OS routing works;
+setup does not infer trust or routing success from absence. These conservative
+limits do not justify offering an unsupported in-app fix. Live macOS Terminal,
+focus, trust and service effects still require host qualification.
+
+The offscreen generator writes every `setup-<fixture>-<theme>.png` and also writes
+`setup-light.png`/`setup-dark.png` aliases for the partial fixture used above.
+
+Unavailable login-manager fixture (no Run offered):
+[light](screenshots/setup-service-unavailable-light.png),
+[dark](screenshots/setup-service-unavailable-dark.png).
+
+Daemon socket discovery uses the selected CLI’s bounded, read-only bare
+`daemon status --json` response. Its absolute `socket_path` is authoritative,
+including candidate launchers with a private default home. Missing or invalid
+paths leave daemon evidence unavailable; the app never falls back to a guessed
+parent-home socket or a registry-writing project listing. Socket version and
+project reads still have to succeed before project state is accepted.
+Compose routing/trust observations and their fixed `global install`/`global trust`
+remedies explicitly select Compose while retaining the checked executable and
+home. Daemon remedies retain the original backend. Login-service installation
+alone does not pass when available evidence says inactive, unloaded, or failed
+launchd exit status; these states need attention even if hackd runs separately.
+
 ## Logs tab
 
 `hack logs --json` for the selected project, following by default:
@@ -294,7 +461,10 @@ On macOS, the CLI runner uses `posix_spawn` with `POSIX_SPAWN_CLOEXEC_DEFAULT`
 and explicit stdin/stdout/stderr actions. This prevents a CLI child from holding
 an unrelated descriptor during another thread's non-atomic close-on-exec setup.
 The process group, selected environment, cwd, timeout and retirement contracts
-are preserved. Linux retains the standard process implementation. This product
+are preserved. A clean-environment runner (setup's checked execution context)
+passes that mode to the boundary explicitly, so its child starts from an empty
+environment on macOS as on Linux. Linux retains the standard process
+implementation. This product
 boundary is needed independently of test isolation; a mutex around runner calls
 would not cover descriptors opened by other GUI/library threads.
 

apps/desktop/app/src/doctor_view.rs

@@ -27,6 +27,7 @@ pub enum Pane {
     #[default]
     Project,
     Doctor,
+    Setup,
 }
 
 pub fn render(pane: &DoctorPane, cx: &mut Context<HackApp>) -> AnyElement {
@@ -46,6 +47,13 @@ pub fn render(pane: &DoctorPane, cx: &mut Context<HackApp>) -> AnyElement {
                 .child("Doctor"),
         )
         .child(div().flex_1())
+        .child(
+            Button::new("run-setup-again")
+                .label("Run setup again")
+                .small()
+                .outline()
+                .on_click(cx.listener(|this, _, _, cx| this.open_setup(cx))),
+        )
         .children(
             pane.age_label(Instant::now())
                 .map(|a| div().text_sm().text_color(t.muted_foreground).child(a)),

apps/desktop/app/src/main.rs

@@ -13,6 +13,7 @@ mod doctor_view;
 mod logs_view;
 #[cfg(feature = "screenshots")]
 mod screenshots;
+mod setup_view;
 mod view;
 
 use std::sync::Arc;
@@ -24,28 +25,37 @@ use hack_desktop_core::source::{FixtureSource, LiveSource, Source};
 
 pub(crate) struct Args {
     pub fixture: Option<Fixture>,
+    pub setup_fixture: Option<String>,
     pub logs_fixture: Option<hack_desktop_core::logs::fixtures::LogsFixture>,
     pub theme: Option<ThemeMode>,
     pub screenshots: Option<std::path::PathBuf>,
 }
 
 fn usage() -> ! {
     eprintln!(
-        "usage: hack-desktop [--fixtures <state> | --logs-fixture <state>] [--theme light|dark] [--list-fixtures] [--screenshots <dir>]"
+        "usage: hack-desktop [--setup-fixture missing-cli|partial|ready|native-unknown|service-unavailable] [--fixtures <state> | --logs-fixture <state>] [--theme light|dark] [--list-fixtures] [--screenshots <dir>]"
     );
     std::process::exit(2)
 }
 
 fn parse_args() -> Args {
     let mut a = Args {
         fixture: None,
+        setup_fixture: None,
         logs_fixture: None,
         theme: None,
         screenshots: None,
     };
     let mut it = std::env::args().skip(1);
     while let Some(arg) = it.next() {
         match arg.as_str() {
+            "--setup-fixture" => {
+                let name = it.next().unwrap_or_else(|| usage());
+                if hack_desktop_core::setup_fixtures::load(&name).is_none() {
+                    usage();
+                }
+                a.setup_fixture = Some(name);
+            }
             "--fixtures" => {
                 let name = it.next().unwrap_or_else(|| usage());
                 a.fixture = Some(Fixture::parse(&name).unwrap_or_else(|| {
@@ -120,13 +130,17 @@ fn main() {
     }
     gpui_kit::application().run(move |cx| {
         gpui_kit::init(cx);
-        let fixture = args.fixture.or(args.logs_fixture.map(|l| {
-            if l == hack_desktop_core::logs::fixtures::LogsFixture::Stopped {
-                Fixture::Stopped
-            } else {
-                Fixture::Running
-            }
-        }));
+        let setup_fixture = args.setup_fixture;
+        let fixture = args
+            .fixture
+            .or(args.logs_fixture.map(|l| {
+                if l == hack_desktop_core::logs::fixtures::LogsFixture::Stopped {
+                    Fixture::Stopped
+                } else {
+                    Fixture::Running
+                }
+            }))
+            .or(setup_fixture.as_ref().map(|_| Fixture::Running));
         let logs_fixture = args.logs_fixture;
         let theme = args.theme;
         let source = source_for(fixture);
@@ -153,6 +167,12 @@ fn main() {
                         app.simulate_daemon_unavailable(f == Fixture::DaemonMismatch);
                     }
                 }
+                if let Some(report) = setup_fixture
+                    .as_deref()
+                    .and_then(hack_desktop_core::setup_fixtures::load)
+                {
+                    app.show_setup_now(report);
+                }
                 if let Some(a) = fixture.and_then(|f| fixtures::local(f).in_flight) {
                     app.simulate_in_flight(a);
                 }