feat(desktop): add evidence-gated upgrade review flow

apps/desktop/README.md

@@ -215,9 +215,9 @@ observations, not locks against concurrent same-user changes.
 
 ## What v0 does not do yet
 
-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).
+The Activity tab, CPU and memory, always-on and broader daemon controls come in
+later units. The design and the CLI/daemon requests they need are in `DESIGN.md`
+(PR #800).
 
 ## Setup
 
@@ -386,6 +386,104 @@ 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.
 
+## Upgrade review (preview)
+
+![Upgrade evidence flow](diagrams/upgrade.svg) ([source](diagrams/upgrade.mmd))
+
+**Upgrade Hack** opens without probing for updates. **Review readiness** runs the
+selected CLI's read-only `upgrade check --json` on a background worker, keeping
+valid reports from exit 1. Only `report_version` 2 is read: every plan step must
+carry its `count` and `targets`, and a step covers the machine (no targets), one
+checkout (its name) or several (`projects`). A target must name a live checkout,
+by name and root, with exactly one finding for that step; any other report stays
+Unknown. Grouped cards list each checkout with its own instruction and, when it
+has one, its own quoted command. The hackd version comes from the socket named in the
+CLI's own read-only `daemon status --json` answer.
+
+Every upgrade read and write (readiness, CLI version, daemon status, snapshot and
+rollback) runs the CLI by its checked absolute path with the same non-secret
+execution context as Setup (home, `HACK_HOME`, backend, service guards, the CLI's
+`HACK_HOST_PROBES_DISABLE=1` hard deny when it is set, and Docker selectors;
+nothing else from the app's environment) and Doctor's private tool
+PATH: per-operation wrappers only for tools no other user can change, with
+interpreter startup variables such as `BASH_ENV` removed. Like Doctor, every run
+disables repository `core.fsmonitor` and hooks through command-line Git config,
+because `upgrade check` reads Git in registered checkouts, and pins the native
+runtime Doctor checked. Copied commands keep the host-probe hard deny too. They
+run later, without the private wrapper PATH, so their PATH keeps only directories
+no other user can change (owner- or root-owned, not group- or other-writable, with
+the same ancestry and ACL rule as Doctor); with none left, it is `/usr/bin:/bin`. If that PATH cannot be
+built, or a tool such as `docker` or `git` on PATH is in a location other users can
+change, or PATH is too long to check fully, the operation is refused before the CLI
+runs and the message names the tools. No `update --check` probe or daily check runs. The
+CLI now has a read-only update check (R14), but this desktop adapter does not
+consume it yet, so availability stays Unknown for every live install kind, including candidates and
+Homebrew. Readiness is separate from update availability. Actual Upgrade stays
+disabled until verified target and installation evidence exists; the current
+live adapter never supplies that evidence. Doctor's
+helper and Docker preflight also runs first, so a remote Docker endpoint (for
+example `DOCKER_HOST=ssh://...`) refuses the operation as well.
+
+**Save file snapshot** is an explicit CLI write, available after a complete ready
+review. The app accepts a recovery point only for `status: created`, `complete:
+true`, an empty `gaps` list and an absolute `manifest.json` path under the returned
+snapshot id. Refused, malformed and incomplete receipts enable neither Upgrade
+nor rollback. For a refused receipt the pane shows the CLI's own reason (control
+characters removed, at most 600 characters) so the user knows what to fix
+before retrying. The app never opens the saved files or reads file values or keys.
+The CLI remains responsible for private-manifest validation and file ownership.
+
+With proposed R14 evidence, the fixture flow offers **Upgrade in Terminal** only
+after a complete snapshot. The authored sequence is `brew upgrade hack` followed
+by `brew upgrade --cask hack-desktop`, stopping on failure. The shared terminal
+adapter quotes each argument, displays the sequence and waits for Enter. It never
+runs finding `command` text. Plan argv may be displayed/copied only after quoting,
+bound like Setup's commands to the reviewed CLI and context (`/usr/bin/env -i
+HOME=… HACK_HOME=… <cli> …`), so a terminal run addresses the reviewed home,
+backend and guards, plus `HACK_MCP_COMMAND` naming the reviewed CLI so a copied
+daemon command restarts that CLI. A review without a checked context offers no copy;
+R17 safe metadata and an authored allowlist are required before any plan fix can
+be run in the app. Today those cards offer Copy and documentation only. No admin
+action, password prompt, self update or relaunch happens in the app.
+
+Terminal launch and window focus never confirm success. **Check again** requires
+fresh CLI and Homebrew-installed app versions at the exact target, hackd matching
+the CLI, and a live, fully readable ready report with no remaining plan. Every
+previous step needs the same scope, checkout root and explicit `ok` finding;
+a grouped step needs that for every checkout it covered, under the id of the
+finding that put the checkout in the step (an `apply_fix` group may differ).
+A disappeared step, missing scope, unreadable checkout or unchecked registry
+entry stays Unknown. The snapshot plan entry is proven by its separate complete
+receipt. A read adapter for `brew info --json=v2 --cask hack-desktop` uses the
+installed version, never the catalog version; it stays unwired until the desktop adopts
+R14's installation-ownership evidence. **Restart hackd** is explicit, shares the machine-action
+gate with setup/recovery, and re-reads versions after the command. No poll starts
+or restarts a service. Upgrade reads run only on demand, including while hidden;
+there is no eager or background daily upgrade check.
+
+**Restore files from snapshot** calls only `upgrade rollback --rollback-manifest
+<exact snapshot path> --json`, without overwrite. Results list each path, status,
+kept-as path and reason. Incomplete restores stay failed. A complete result says
+**Files restored. Versions, containers and services were not changed.** Fresh
+readiness is required again. All state and receipts stay in memory for this app
+session. The desktop has no signing/cask distribution or production updater in
+this unit (DESIGN sections 4 and 8).
+
+Offline proposed-capability examples (no CLI, Homebrew or terminal effects):
+
+```sh
+cargo run -p hack-desktop -- --upgrade-fixture ready --theme dark
+cargo run -p hack-desktop -- --upgrade-fixture availability-unknown
+```
+
+Fixture names: `availability-unknown`, `available`, `checking`, `blocked`, `ready`,
+`snapshotting`, `incomplete`, `applying`, `unknown`, `restarting`, `done`, `failed`,
+`rolling-back`, `restored`. `--screenshots` renders all fourteen in both themes
+without a window. Evidence: [light](screenshots/upgrade-light.png),
+[dark](screenshots/upgrade-dark.png). Core tests use only fake executables, isolated homes, disabled
+autostart, injected launchers and pure evidence inputs. They do not qualify live
+Homebrew, terminal, platform focus, a published app or a real upgrade.
+
 ## Logs tab
 
 `hack logs --json` for the selected project, following by default:

apps/desktop/app/src/doctor_view.rs

@@ -28,6 +28,7 @@ pub enum Pane {
     Project,
     Doctor,
     Setup,
+    Upgrade,
 }
 
 pub fn render(pane: &DoctorPane, cx: &mut Context<HackApp>) -> AnyElement {

apps/desktop/app/src/main.rs

@@ -14,6 +14,7 @@ mod logs_view;
 #[cfg(feature = "screenshots")]
 mod screenshots;
 mod setup_view;
+mod upgrade_view;
 mod view;
 
 use std::sync::Arc;
@@ -26,14 +27,15 @@ use hack_desktop_core::source::{FixtureSource, LiveSource, Source};
 pub(crate) struct Args {
     pub fixture: Option<Fixture>,
     pub setup_fixture: Option<String>,
+    pub upgrade_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 [--setup-fixture missing-cli|partial|ready|native-unknown|service-unavailable] [--fixtures <state> | --logs-fixture <state>] [--theme light|dark] [--list-fixtures] [--screenshots <dir>]"
+        "usage: hack-desktop [--upgrade-fixture <state>] [--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)
 }
@@ -42,13 +44,21 @@ fn parse_args() -> Args {
     let mut a = Args {
         fixture: None,
         setup_fixture: None,
+        upgrade_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() {
+            "--upgrade-fixture" => {
+                let name = it.next().unwrap_or_else(|| usage());
+                if hack_desktop_core::upgrade_fixtures::load(&name).is_none() {
+                    usage();
+                }
+                a.upgrade_fixture = Some(name);
+            }
             "--setup-fixture" => {
                 let name = it.next().unwrap_or_else(|| usage());
                 if hack_desktop_core::setup_fixtures::load(&name).is_none() {
@@ -131,6 +141,7 @@ fn main() {
     gpui_kit::application().run(move |cx| {
         gpui_kit::init(cx);
         let setup_fixture = args.setup_fixture;
+        let upgrade_fixture = args.upgrade_fixture;
         let fixture = args
             .fixture
             .or(args.logs_fixture.map(|l| {
@@ -140,7 +151,8 @@ fn main() {
                     Fixture::Running
                 }
             }))
-            .or(setup_fixture.as_ref().map(|_| Fixture::Running));
+            .or(setup_fixture.as_ref().map(|_| Fixture::Running))
+            .or(upgrade_fixture.as_ref().map(|_| Fixture::Running));
         let logs_fixture = args.logs_fixture;
         let theme = args.theme;
         let source = source_for(fixture);
@@ -173,6 +185,12 @@ fn main() {
                 {
                     app.show_setup_now(report);
                 }
+                if let Some(flow) = upgrade_fixture
+                    .as_deref()
+                    .and_then(hack_desktop_core::upgrade_fixtures::load)
+                {
+                    app.show_upgrade_now(flow);
+                }
                 if let Some(a) = fixture.and_then(|f| fixtures::local(f).in_flight) {
                     app.simulate_in_flight(a);
                 }

apps/desktop/app/src/screenshots.rs

@@ -35,6 +35,45 @@ pub fn run(dir: &Path, fixture: Option<Fixture>) {
         shots.push((l.name(), base, Some(l)));
     }
     for mode in [ThemeMode::Light, ThemeMode::Dark] {
+        for name in hack_desktop_core::upgrade_fixtures::NAMES {
+            cx.update(|cx| Theme::change(mode, None, cx));
+            let opts = WindowOptions {
+                focus: false,
+                show: false,
+                ..crate::window_options()
+            };
+            let (handle, _) = cx
+                .update(|cx| {
+                    gpui_kit::open_window(opts, cx, |window, cx| {
+                        cx.new(|cx| {
+                            let mut app = HackApp::new(
+                                crate::source_for(Some(Fixture::Running)),
+                                false,
+                                window,
+                                cx,
+                            );
+                            app.show_upgrade_now(
+                                hack_desktop_core::upgrade_fixtures::load(name)
+                                    .expect("known upgrade fixture"),
+                            );
+                            app
+                        })
+                    })
+                })
+                .expect("offscreen upgrade window");
+            cx.update_window(handle, |_, w, cx| w.render_frame(cx))
+                .expect("render upgrade");
+            let image = cx.capture_screenshot(handle).expect("upgrade renderer");
+            let suffix = if mode == ThemeMode::Dark {
+                "dark"
+            } else {
+                "light"
+            };
+            image
+                .save(dir.join(format!("upgrade-{name}-{suffix}.png")))
+                .expect("save upgrade");
+            cx.update_window(handle, |_, w, _| w.remove_window()).ok();
+        }
         for name in hack_desktop_core::setup_fixtures::NAMES {
             cx.update(|cx| Theme::change(mode, None, cx));
             let mut opts = crate::window_options();

apps/desktop/app/src/setup_controller.rs

@@ -16,7 +16,7 @@ impl HackApp {
             self.setup.refresh_again = true;
             return;
         }
-        if self.setup.action_busy || self.recovery_busy {
+        if self.setup.action_busy || self.recovery_busy || self.upgrade.busy {
             return;
         }
         let generation = self.setup.begin();
@@ -65,6 +65,7 @@ impl HackApp {
             && !self.setup.loading
             && !self.setup.action_busy
             && !self.recovery_busy
+            && !self.upgrade.busy
         {
             self.pane = Pane::Project;
             cx.notify();