Detached update hand-off on every OS: quit → hermes update → reopen, with one dumb shim window

[OutThisLife]

Updating a desktop app should be: quit, run hermes update in the background, reopen. This PR makes that literally the architecture — on every OS.

The design

Three parts, strictly separated by what they're allowed to know:

1. The orchestrator owns the truth — scripts/desktop-update/windows.ps1 (existing, evolved) and scripts/desktop-update/posix.sh (new). The Desktop spawns it detached and quits; the script waits the app out, runs plain hermes update (retry-once across the update boundary, truthful desktop-rebuild completion), swaps/relaunches the app, writes .hermes-update-result.json, and cleans up the marker. Both scripts live in the repo checkout, so every update refreshes the code that drives the next update. Nothing orchestration-shaped is frozen anywhere anymore.

2. The shim owns nothing — scripts/desktop-update/ui.html, one page for both OSes, rendered in a chromeless browser app window (Edge on Windows, any chromium-family browser on mac/linux; loopback-only server because file:// pages can't receive events from a detached process). It polls /progress for exactly two events — done, error — and reacts: checkmark + "Opening Hermes…", or "Failed to update / Run hermes debug share". It streams nothing, decides nothing, and closes/relaunches nothing. If no renderer exists, no UI is shown and the update is identical — the ladder degrades Edge → WinForms card → log-only on Windows, browser → log-only on posix.

3. The Desktop only leaves — applyUpdates spawns the orchestrator and quits. The relaunched Desktop reads the result file on boot and surfaces failures (existing handoff-result.ts contract, unchanged).

The UI is #75895's hand-off screen ported verbatim (Fourier Flow loader, one title, one line, OS light/dark with the settled charcoal dark seeds) with #83634's terse failure state.

Why this is different from the current architecture

Today there are three updater codepaths, one per situation, each with its own bug tail:

	Today	This PR
Windows	ps1 hand-off (window = 720×420 WinForms dashboard w/ streaming log)	same hand-off, shim window
macOS	in-app: applyUpdatesPosixInApp in main.ts drives update+rebuild while the app runs, then swaps its own bundle and re-execs	quit → posix.sh → relaunch
Linux	in-app + a 3-outcome relaunch matrix (relaunch / guiSkew / manual-sandbox)	quit → posix.sh (same outcomes, decided post-update by the script)

Killing the in-app path deletes its structural hazards, not just its lines:

• The bug: desktop auto-update kills its own backend via _kill_stale_dashboard_processes #37532 reaper-exclusion dance is gone. hermes update reaps stale backends; the in-app path had to thread HERMES_DESKTOP_CHILD_PID (every desktop-managed backend PID) into the update env so the reap would spare the app's own live backends. With the app dead before the update starts, there is nothing to spare. That whole class — boot→kill→crash loops when the exclusion list was wrong — can't exist.
• No app swaps its own bundle while running. The swap runs after the process exits, from outside it.
• main.ts sheds ~500 lines of updater machinery (runStreamedUpdate, rebuild retry, the relaunch-outcome matrix + update-relaunch.ts/update-rebuild.ts and their tests, shellQuote, resolveHermesCliBinary) from a 12.7k-line file the root AGENTS.md already flags for extraction.
• One shape everywhere. A Windows update bug and a mac update bug are now the same investigation: read the same hand-off log, same result file, same marker protocol. The only OS-specific part left is the one that's genuinely OS-specific (the Windows venv-lock gauntlet; posix has no locks and its orchestrator is ~200 lines because of it).

Ordering note: the failure card and result file point at hermes debug share, which uploads the full hand-off log — so the window never needs to show error detail, which is what lets it stay this small.

Why this is different from the web-shell spike

The spike (rich web progress UI) and this PR share plumbing — its TcpListener loopback server, the msedge --app spawn with a throwaway profile, the degradation ladder, and -SelfTestUi are salvaged here directly (co-authored on the shim commit). The difference is the philosophy of the window:

• The spike's page is a dashboard: phase checklist with checkmarks, animated progress sweep, live log tail. Those are the three elements Updater UX: quiet minimal update surfaces + permanent dry-run simulation #75895 removed from the other update surfaces, argued and settled: the percents were hardcoded milestones (lies), the log pane duplicated the status line, and updating is a wait, not a dashboard. This PR's page is the settled shape.
• The spike feeds the UI from inside the orchestration (phase transitions pushed at each gate, Write-HandoffLog streaming into the page). That couples the window to the update's internals — every new stage is a UI change. Here the contract is two terminal events; the orchestrator can be rewritten freely and the shim never changes. A shim with a two-event contract is done — freezing it anywhere (old checkouts, cached copies) is harmless, which is the property that killed the last updater architecture.
• The spike is Windows-only polish on one rung. This PR is the same window on every OS, plus the mac/linux architecture inversion.

Compatibility

• No signed-binary dependency. Everything ships through the repo via hermes update — no installer rebuild, no re-signing, no user re-downloads. The staged Tauri binary remains exactly what it is today: last-resort fallback for checkouts predating the scripts.
• Skew both directions: old asar + new checkout → compat forwarder at the legacy scripts/desktop-update.ps1 path; new asar + old checkout → resolver falls back to the flat path (tested).
• Checkouts predating posix.sh get the manual hermes update card once; their next update pulls the script.
• Marker protocol, fail-closed gates, result-file contract: byte-identical semantics to main.

Repro / QA

Sandboxed repro paths (disposable HERMES_HOME under /tmp, real code paths — the literal install.sh, the real orchestrator):

npm run update:shim          # shim dry run → done state
npm run update:shim:fail     # shim dry run → error state
npm run update:repro:fresh   # fresh install via scripts/install.sh
npm run update:repro:behind  # install rewound N commits (default 25), orchestrator drives it forward
npm run update:repro:error   # broken venv → abort + result file + error card

Validated here (mac): shim renders live in Chrome app-mode and settles both states; server E2E (routes, event flip, 404, teardown); orchestrator error path writes the result file, exit 3, cleans its marker; updater-process suite 14/14 including both skew directions; full desktop electron suite 970 passed / 2 skipped; both ps1 files parse clean (pwsh AST). Windows leg needs a box for visual QA: powershell -File scripts\desktop-update\windows.ps1 -SelfTestUi.

Supersedes the web-shell spike's window (plumbing salvaged, credited); built on #83634.

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 4280413 — fix(update): exempt manual results from the hand-off freshne}

⚠️ Warnings

OSV vulnerability scan · View job

2 known vulnerabilities found in pinned dependencies.

• CVE-2026-70608 in package-lock.json
• CVE-2026-70606 in package-lock.json

How to fix:

Review the findings in the Security tab. Update the affected dependencies if a patched version is available.

---

debug info

CI timings

CI timings · View report · View job

Wall time 7m6s vs 6m32s (+8.7%). 16 job(s) slower, 18 faster, 2 unchanged.

• JS & TS checks / apps/desktop / check:test:ui: +38.0s
• Python tests / Run tests slice 6/12: +28.0s
• Python tests / Run tests slice 2/12: -25.0s
• JS & TS checks / apps/desktop / check:test:desktop:all: +18.0s
• Python tests / Run tests slice 8/12: +16.0s

[helix4u]

I like the core direction here. Moving update orchestration into repo-owned scripts solves the frozen-updater problem, and the separation between the orchestrator, the two-event UI shim, and the Desktop process is clean. The Windows forwarder, fail-closed exit/venv gates, marker ownership, and asynchronous stdout/stderr draining also look like solid improvements.

I do not think the new POSIX handoff is ready to merge yet, though. I found several blocking lifecycle issues:

1. Linux can close Hermes, report success, and never reopen it.

applyUpdatesPosixHandoff() quits before the script determines whether the running Linux application can actually be replaced or relaunched. In scripts/desktop-update/posix.sh, finish() writes the result and publishes done before calling relaunch().

For AppImage/deb/rpm installs, the later relaunch() branch only changes FINAL_MSG and starts nothing. The durable result has already been written as ok: true with Update complete., and readAndConsumeHandoffResult() only logs successful result messages rather than displaying them. The shim therefore says Opening Hermes..., closes, and leaves the user with no application and no visible explanation.

The sandbox-blocked Linux branch has the same problem. The old in-app implementation made the relaunch / guiSkew / manual decision while the working window was still alive. That safety property needs to be preserved, or the handoff protocol needs a surfaced warning/manual terminal state that is decided before done is published.

2. The Linux relaunch gate no longer preserves the old safety contract.

The new */release/*-unpacked/* match is not anchored to $INSTALL_ROOT/apps/desktop/release/linux-unpacked, so it does not prove that this update rebuilt the selected executable.

The sandbox check also differs materially from the deleted sandboxPreflight() logic:

• it checks the setuid bit but not root ownership;
• it rejects a missing chrome-sandbox, although the previous code allowed builds using the namespace sandbox;
• it checks HERMES_DESKTOP_NO_SANDBOX, which does not appear to be an established launch setting;
• it no longer recognizes the supported ELECTRON_DISABLE_SANDBOX=1 or --no-sandbox cases.

Finally, setsid "$RELAUNCH_TARGET" drops the original launch arguments and working directory. The deleted implementation deliberately preserved filtered launch args, the relevant environment, and process.cwd(). A valid --no-sandbox launch, deep link, or project-scoped launch can therefore fail or return in a different context after updating.

Please retain or port the exact path resolution, sandbox preflight, argument filtering, environment preservation, and cwd restoration as tested pure logic rather than replacing them with the shell wildcard and -u check.

3. macOS reports success before proving that the bundle swap and relaunch worked.

finish() writes ok: true, removes the update marker, and publishes done before relaunch() runs ditto, the bundle moves, and /usr/bin/open.

The swap sequence also does not check the second move:

mv "$RELAUNCH_TARGET" "$RELAUNCH_TARGET.old" || rm -rf "$RELAUNCH_TARGET"
mv "$RELAUNCH_TARGET.new" "$RELAUNCH_TARGET"

If that second move fails, the installed app can be missing while the result still says the update completed. An open failure is likewise only logged.

The swap should be transactional with a checked rollback, and swap/relaunch outcome must be reflected in the durable result before the marker is removed and done is published.

4. POSIX status and result JSON are not escaped.

Both publish() and finish() interpolate strings directly into JSON. A quote or newline in a message or branch name produces malformed JSON. Git permits a branch name containing ", so this can happen through a valid branch. Please use a real JSON serializer and keep the write atomic.

The current test evidence does not cover these paths. This PR deletes the focused update-relaunch and update-rebuild tests, resolvePosixScriptHandoff() is not covered by updater-process.test.ts, and the repro script never passes --relaunch-target, so it does not exercise Linux relaunch/gui-skew/sandbox behavior or the macOS swap. Desktop E2E was also skipped, and the PR notes that Windows visual QA is still pending.

My recommendation would be to split the Windows shim/PowerShell refinements from the POSIX architecture change so the sound Windows work can proceed independently. If this stays as one PR, I would hold it until the Linux terminal-state and relaunch contracts, macOS transactional swap, JSON serialization, and focused regression coverage are addressed.

[teknium1]

Reviewed in depth — the architecture here is right, and it's the logical conclusion of the same argument that produced desktop-update.ps1 in the first place: nothing orchestration-shaped should be frozen anywhere. Taking the posix side out of main.ts and into a repo-owned script kills real hazard classes (the #37532 reaper-exclusion dance, the app swapping its own bundle while running), not just lines. The compat forwarder with both skew directions tested is exactly the right touch, and the two-event shim contract is a genuinely durable design: a frozen shim is harmless, which is the property the last updater architecture died for lacking.

Credit where due: the loopback-server/Edge-app plumbing salvage from #83637 is cleanly done and the co-author attribution is appreciated.

Three things before this can land:

1. The window design isn't settled yet. The PR body cites Updater UX: quiet minimal update surfaces + permanent dry-run simulation #75895 for "argued and settled: no phases, no log pane" — but Updater UX: quiet minimal update surfaces + permanent dry-run simulation #75895 is still open. Whether the update window is the quiet minimal shim or a richer progress surface (feat(desktop): rich web progress UI for the Windows update hand-off #83637, also green) is a product call that belongs to @teknium1, and both PRs are now in front of him. Neither should merge until he picks; they rewrite the same surface.

2. Blast radius on the posix inversion. Deleting the battle-tested in-app mac/linux updater in the same PR that introduces its replacement is a lot at once. The mac validation (970 electron tests, shim E2E, repro scripts) is solid groundwork — but the mac bundle-swap block (ditto → mv/rm -rf on the running .app) and the Linux chrome-sandbox gating are the parts I'd want exercised via npm run update:repro:behind on a real mac (and ideally one Linux box) with logs attached before the old path is deleted rather than deprecated. If splitting is on the table: Windows orchestrator + window now, posix inversion as its own PR after that QA, would land the low-risk half immediately.

3. Windows visual QA gap is shared. Neither this PR's windows.ps1 -SelfTestUi nor feat(desktop): rich web progress UI for the Windows update hand-off #83637's has been run on a real Windows box yet. Whichever window wins needs that one run before it rides a production update.

Substantively: posix.sh reads correct on review — fail-closed desktop-exit gate preserved, marker claim/adopt/cleanup-if-owned semantics byte-compatible, #37541 sandbox honesty on the Linux relaunch, result-file contract intact. Nice work.

[OutThisLife]

@helix4u — all four were correct, thank you for the depth. Fixed in 324f7cb:

• Ordering: finish() now delivers the outcome before publishing it — mac swap and the linux relaunch gate run first, then the result file, marker removal, and the shim event, with the app launch itself last so it can't race the result write. A gated linux install (AppImage/deb/rpm, broken sandbox helper) surfaces its message in the result file AND holds the shim window open with it instead of closing on a false "Opening Hermes…".
• Gate: now an exact port of the deleted update-relaunch.ts decision — anchored path-segment match on <root>/apps/desktop/release/linux-unpacked, chrome-sandbox absent = namespace build = fine, present = root-owned + setuid required, with the real opt-outs (ELECTRON_DISABLE_SANDBOX, --no-sandbox among the replayed launch args, or the Desktop vouching via --sandbox-fallback). HERMES_DESKTOP_NO_SANDBOX is gone. collectRelaunchArgs/sandboxFallbackFromEnv live in updater-process.ts again, and the Desktop passes the filtered launch args (after --) plus --relaunch-cwd, so a deep-link or --no-sandbox launch survives the update.
• mac swap: transactional with a checked rollback — a failed install restores the previous bundle and the result says so; even a failed rollback has an honest terminal state (exit 7, pointing at the rebuilt bundle). A failed open rewrites the result truthfully.
• JSON: escaped + atomic (tmp + rename), regression-tested with a hostile branch name.

Coverage: resolvePosixScriptHandoff + the ported helpers in updater-process.test.ts (19 pass), and npm run update:repro:gate asserts the whole gate matrix plus the hostile-branch JSON round-trip. Full desktop suite 4701 passed / 2 skipped.

[OutThisLife]

@teknium1 — thanks. On 2, I'd push back on the split: the risky part of this PR isn't the posix deletion, it's the window of time where two updater architectures coexist. The in-app path isn't so much battle-tested as battle-scarred — it's the code that produced #37532, #37541, and #45205, and its hazards are structural (live backends during the update, an app swapping its own bundle, the reaper exclusion list). Landing the Windows half alone means the next posix incident gets debugged against code already deleted on a branch somewhere, and the compat matrix (old asar × new checkout × 3 OSes × 2 architectures) doubles for a release cycle.

The residual risk the split was hedging is what helix4u's review flagged, and that's now closed (see above): the relaunch gate is a byte-faithful port of the deleted update-relaunch.ts decision with its own asserted matrix (npm run update:repro:gate), the mac swap is transactional with checked rollback, and outcome-before-publication ordering is enforced in one place.

On 3: windows.ps1 -SelfTestUi has now run on a real Windows 11 box through real Edge — both terminal states render correctly (loader + "Updating Hermes" → checkmark, and the ✕ / "Failed to update" / hermes debug share card, light theme).

[OutThisLife]

Test methodology + confidence

Full evidence trail for what was actually exercised, on what, and what remains open.

What was run, where

1. Windows 11, real hardware (WSL2 host, PowerShell 5.1, real Edge)

• Shim visual QA (windows.ps1 -SelfTestUi): both terminal states rendered through a real chromeless Edge app window — loader + "Updating Hermes" → checkmark, and ✕ / "Failed to update" / hermes debug share. Light theme verified against the OS. This closes the "no Windows box has run it" gap for this PR's window.
• Sandboxed skew E2E — the actual "old GUI, N commits behind" path: disposable HERMES_HOME under C:\Users\Public, real install.ps1 install, checkout rewound 100 commits (predating this PR's layout: flat=True nested=False), then the old flat scripts\desktop-update.ps1 — the exact file an old asar resolves and spawns — drove hermes update forward onto this branch. Result: {"ok":true,"exit_code":0,"message":"Update complete."}, checkout landed on the PR head, scripts/desktop-update/windows.ps1 materialized, the flat path became the 11-line forwarder, and no marker was left behind. That is the one-time migration every existing Windows user rides when this merges, executed end-to-end on real Windows against the real venv-lock machinery.

2. Linux (this branch)

• npm run update:repro:gate — full relaunch-gate decision matrix asserted: AppImage/not-under-unpacked → skew; sibling-prefix dir (linux-unpacked-evil) not fooled; missing chrome-sandbox = namespace build → relaunch; present-but-not-root/setuid → manual; each opt-out (--sandbox-fallback, --no-sandbox replayed arg, ELECTRON_DISABLE_SANDBOX=1) → relaunch. Plus a hostile-branch (evil"branch\n$(x)) round-trip through the result JSON, parsed back with a real JSON parser.
• Shim server E2E: /progress serving the done-with-message state, HTML fallback line, 404 route.
• updater-process.test.ts: 19/19 — including resolvePosixScriptHandoff (present / predates-script / Windows-null), both Windows resolver skew directions, and the ported collectRelaunchArgs / sandboxFallbackFromEnv.
• Full desktop electron suite: 4701 passed / 2 skipped, typecheck clean.

3. macOS — covered by the PR-body validation (shim live in Chrome app-mode both states, server E2E, orchestrator error path, 970-test suite) plus review-driven hardening now unit- and matrix-tested. The transactional swap's failure legs (ditto failure → keep old; mv-in failure → rollback; rollback failure → exit 7 honest terminal state) are code-path-reviewed and shell-syntax-verified but not fault-injected on real hardware.

Confidence, stated plainly

Population	Path	Confidence
Existing Windows users (incl. months-stale frozen hermes-setup.exe)	old flat ps1 → update → forwarder handoff	High — the literal migration ran E2E on real Windows, plus both resolver skew directions unit-tested
New users (install after merge)	nested orchestrator from day one	High — same code the E2E ran post-migration; no legacy state to collide with
mac/linux users, happy path	quit → posix.sh → update → swap/relaunch	High — repro scripts + suite + the ordering fix means the result file can no longer lie
linux edge population (AppImage/deb/rpm, broken sandbox helper, --no-sandbox launches)	gate → skew/manual terminal states	High on the decision (matrix-asserted), medium on real-desktop ergonomics — the honest message now reaches the window and result file, but no real AppImage box has run it
mac swap failure legs	rollback chain	Medium — reviewed + syntax-checked, not fault-injected on hardware
Future users	repo-owned scripts refresh with every update	Structural — this is the point of the architecture: there is no longer any frozen orchestration to age; a bug shipped here is fixable by the very next hermes update

No claim of certainty beyond that. The two medium cells are exactly where a real mac + one AppImage box before (or immediately after) merge would convert review confidence into executed confidence — happy to run those if someone lends the hardware, and npm run update:repro:behind / update:repro:gate make each run a one-liner.

[helix4u]

Thanks, I re-reviewed 324f7cb and the added test-methodology notes. The fixes are substantive:

• The Linux relaunch gate now preserves the old safety contract: anchored unpacked path, root/setuid sandbox validation, missing-helper behavior, established sandbox opt-outs, filtered launch args, and cwd restoration.
• The macOS bundle replacement is now transactional, with checked rollback and an honest hard-failure state if rollback also fails.
• The practical JSON corruption case is fixed with escaping plus atomic replacement.
• The gate matrix, hostile-branch round-trip, real Windows shim QA, and old-flat-script to nested-orchestrator migration E2E close most of the original coverage gaps.

I do not think the terminal lifecycle is fully closed yet, though.

1. posix.sh::finish() still writes the result, removes the marker, publishes done, and closes the success shim before calling launch_app(). On macOS, an open failure only rewrites the result after the visible success state has disappeared. On Linux, setsid ... & reports that the background shell started, not that the target executable successfully launched, so an immediate exec failure can retain the success result. Please make launch acceptance part of the terminal outcome before publishing done; if launch is rejected, rewrite the result and retain a visible manual/error state before cleaning up the marker.

2. Linux skew and manual outcomes still rely on the optional Chromium-family shim for their only visible instruction. On an AppImage/deb/rpm or sandbox-blocked install without Chrome/Chromium/Edge/Brave, Hermes quits, the gate deliberately does not relaunch it, no shim appears, and successful result messages are only logged on the next manual boot. A failed update from a packaged launch has the same problem because the skew gate prevents the Desktop from reopening to surface the failure dialog. This path needs a recovery surface that does not depend on a separately installed browser, or the decision needs to happen before the working Desktop exits.

3. The Windows orchestrator has the same sibling truth gap: its finally block writes the result, removes the marker, and closes the progress UI before Start-DesktopRelaunch(). WMI and fallback launch failures are only logged, leaving the result as ok: true. Since this PR defines one cross-platform handoff contract, the Windows launcher should also return an outcome and preserve a visible/manual state if both launch mechanisms fail.

The current tests validate the gate decisions and normal Windows migration well, but they do not exercise launch failure, Linux skew/manual without a renderer, or the final terminal-event ordering. Focused regressions for those paths would close the remaining review concerns.

[OutThisLife]

@helix4u — round 2 addressed in db835fd (plus daf83a4, a bug the mac E2E caught in the meantime — see the confidence comment below).

1. Launch acceptance is now part of the terminal outcome, ordered before the event. finish() runs: deliver outcome → durable result + marker → launch with acceptance → terminal event. macOS acceptance is open's exit code (launchd fails loudly on a broken bundle); Linux verifies the setsid child is still alive 1.5s after spawn, so an instant exec failure (ENOENT/ELF/sandbox death) downgrades to a held manual state with a rewritten result instead of a vanished "done". The shim gains manual as a third terminal state — title "Update complete", message says what to do, window stays up. Still zero logic in the page.

2. Renderer-free recovery surface. When a manual/error outcome fires with no shim (no chromium-family browser), the posix orchestrator now raises notify-send → zenity → kdialog, best-effort, Linux-only (mac's open reopens the app even on the error path, and the browser list there is effectively always satisfiable). A gated skew/manual on a browserless AppImage box is no longer a silent disappearance — it's a desktop notification plus the truthful result on next boot. On "decide before the Desktop exits" as the alternative: the skew/manual decision inputs (is the rebuilt binary the running one, is the fresh chrome-sandbox launchable) only exist after the rebuild, so the decision can't move pre-quit without deciding on stale artifacts; the notification path covers the gap without giving the window authority back.

3. Windows sibling contract closed. Start-DesktopRelaunch now returns verified acceptance — WMI pid must still be alive (dying before its window appears counts as failure, not "nothing to focus"), and the Start-Process fallback checks the process is alive after 1.5s. On a failed launch the finally block rewrites the result and holds Show-ManualFinale (shim manual event, or the WinForms card with the same copy). The error path still relaunches after showing itself, same as before.

Regressions: npm run update:repro:launch drives the real orchestrator against stub installs: instant-exit relaunch → manual downgrade in the result JSON; gated skew → skew message in the result (never a bare "Update complete."). Gate matrix unchanged and still green; updater-process suite 19/19.

[OutThisLife]

macOS E2E + confidence

Ran the posix leg end-to-end on this mac (arm64, Sequoia) against sandboxed installs — disposable HERMES_HOME under /tmp, real install.sh, real orchestrator, real hermes update.

What the E2E caught (and why it existed)

The sandboxed behind-repro caught the worst bug this PR could have shipped: posix.sh inherited the Desktop's cwd, and parts of the update pipeline resolve the tree they mutate from the working directory — the run updated my development checkout (the cwd at spawn time) while reporting success against the sandbox. Result file said ok:true, sandbox SHA never moved, and an unrelated repo got fast-forwarded. Fixed in daf83a4 (cd "$INSTALL_ROOT" before the update — the exact cwd: updateRoot contract the deleted in-app path had); rerun confirmed the outside checkout stays untouched (reflog clean before/after).

That this fell out of npm run update:repro:behind on the first real run is the argument for keeping these repro paths in the tree.

Runs

Leg	Result
update:shim / update:shim:fail (Chrome app-mode, live window)	✅ loader → ✓/✕, error window held, server torn down cleanly
shim server E2E (routes, event flip, 404, teardown, hostile-JSON status)	✅
update:repro:error (broken venv)	✅ abort exit 3, truthful result file, marker cleaned (owned-only)
update:repro:behind (rewound sandbox, full orchestrator: marker → hermes update → result → relaunch decision)	✅ flow; ⚠️ see caveat
update:repro:gate (linux gate matrix, 8 cases)	✅ 8/8
update:repro:launch (launch-acceptance matrix)	✅
updater-process.test.ts (both skew directions, ported helpers)	✅ 19/19
full desktop electron suite	✅ 970 passed / 2 skipped
both ps1 files, pwsh AST parse	✅

Confidence, per path

• mac shim + event channel: high. Watched live repeatedly, both terminal states, teardown clean.
• mac orchestrator flow (marker → update → result → relaunch decision): high for the flow itself — every leg exercised for real, including the abort and downgrade paths.
• mac bundle swap + relaunch acceptance: medium. The transactional swap and open acceptance are exercised only through the launch matrix's negative case here; the positive swap needs a packaged .app run (the sandbox install doesn't build the desktop bundle). This is the leg I'd watch on the first dogfood update.
• behind-repro caveat: the sandbox's git tree doesn't advance — its origin is a local clone, so hermes update's pull path self-limits (reports up-to-date against a non-official remote). The orchestrator legs all run for real; the git-pull leg is effectively a no-op in the sandbox. Pointing the sandbox at the official remote would close this, at the cost of the repro testing origin/main instead of your branch. Open to either.
• linux gate/launch/notify paths: medium-high — gate and launch matrices are real-orchestrator runs, but on darwin the linux-only branches (setsid acceptance, notify-send ladder) execute only in the matrix's simulated shapes. Needs one run on a real linux box.
• Windows: not tested here — Brooklyn's PC has that leg; windows.ps1 -SelfTestUi + the migration E2E cover it.

[helix4u]

@OutThisLife
Thanks, this round substantively closes the earlier Windows and POSIX findings. The Windows relaunch acceptance/manual finale now matches the intended contract, the Linux gate preserves the old safety behavior, the macOS replacement is transactional, and the additional launch/result regressions are useful.

I still see four correctness issues before approval:

1. A missing macOS relaunch target is treated as accepted.

   In posix.sh::launch_app(), [ -d "$RELAUNCH_TARGET" ] || return 0 treats a nonempty but nonexistent relaunch target as success.

   Once a relaunch target has been supplied, its disappearance is a rejected launch, not "no launch due." The Darwin launch repro currently codifies this false-success behavior by expecting ok:true for a missing bundle. This should return nonzero and assert the manual downgrade/result instead.

2. Renderer-free recovery is still not guaranteed.

   On macOS, find_browser() only recognizes Chrome, Edge, Chromium, and Brave. A Safari-only machine has no shim. Recoverable swap failures set DONE_NOTE, and that branch publishes manual without calling launch_app(), so Hermes can remain closed with no visible instruction. A native macOS fallback such as osascript, or another guaranteed recovery surface, is still needed.

   On Linux, notify-send, zenity, and kdialog are all optional. The current elif chain also selects notify-send based on its existence, then suppresses execution failure with || true. If it exists but cannot reach D-Bus or the desktop session, the code never tries zenity or kdialog. The ladder should fall through when a candidate fails, and the no-browser/no-notifier outcome still needs an explicit recovery contract.

3. The install-root correction must fail closed.

   posix.sh uses set -u, not set -e, so cd "$INSTALL_ROOT" can fail and then continue running hermes update from the previous directory. That recreates the wrong-tree mutation class the change is intended to eliminate.

   Please check the cd, write an honest terminal result, and exit before invoking Hermes if the install root cannot be entered.

4. update:repro:fresh is not reliably noninteractive.

   install.sh supports --non-interactive. Redirecting stdin from /dev/null is not equivalent because prompt_yes_no() falls back to /dev/tty when one is available. The repro can therefore prompt or hang when optional system dependencies are missing. Please pass --non-interactive explicitly.

The macOS testing meaningfully raises confidence in the orchestrator, marker, result, shim, and abort paths. Its stated boundaries remain important:

• The sandbox origin made the behind-update pull effectively a no-op.
• The positive packaged .app replacement and relaunch path was not exercised.
• The Linux setsid and notification paths were simulated on Darwin rather than run on Linux.
• The cwd repro proved that the script was dangerously caller-cwd-sensitive, but the production Electron spawn uses cwd: HERMES_HOME; the development-checkout mutation was observed through the repro caller, not reproduced from the exact production Desktop spawn.

I would still want one packaged macOS dogfood update and one real Linux run before deleting the old POSIX updater path in the same merge.

[OutThisLife]

@helix4u — all four fixed in fa03494.

1. Missing mac target = rejected launch. launch_app() returns nonzero for a supplied-but-missing target; the launch matrix now asserts the manual downgrade ('Reopen Hermes' in message) instead of codifying the false success. Related: a mac swap-failure DONE_NOTE now still relaunches the kept/rolled-back bundle before publishing manual — the user gets their old app back and the instruction to re-run.

2. Recovery surface guaranteed. The ladder now falls through on execution failure, not just absence — a notify-send that can't reach D-Bus no longer eats the message; zenity/kdialog get their turn. macOS gets osascript display notification (present on every macOS, covers the Safari-only machine). The end of the ladder is an explicit contract, not silence: the no-surface case logs that the result file is the delivery channel, and the relaunched/next-boot Desktop surfaces it — which is the same contract the old in-app path ended at when its window was gone.

3. cd fails closed. Checked; on failure: honest result (exit 3, "Nothing was changed"), no hermes update. You're right that set -u alone made the correction itself a member of the wrong-tree class it was killing.

4. --non-interactive passed explicitly — I'd grepped the flag list too narrowly and missed the /dev/tty fallback in prompt_yes_no(). </dev/null dropped.

On the CI red: slice 5's test_multiplex_busy_input_mode failure was the stale merge-ref (branch base predated a31be48's gateway busy-mode fixes; the test passes on merged main locally). Merged main into the branch — the rerun should be green.

Agreed on the merge gate: one packaged mac dogfood update + one real linux run before this merges. The positive .app swap leg is queued as exactly that dogfood run.

[OutThisLife]

CI note: the red on slice 5 (test_multiplex_busy_input_mode) is #83743 — main has been red since c8f235a106 (bisect evidence on the issue). Not introduced by this branch; every other check is green.

[helix4u]

@OutThisLife
Thanks, I re-reviewed fa03494f7e. Three of the four findings are now closed correctly:

• A supplied-but-missing macOS relaunch target is rejected, and the repro now asserts the manual downgrade.
• Failure to enter INSTALL_ROOT aborts before hermes update.
• The fresh-install repro now passes --non-interactive explicitly.

The renderer-free recovery finding is still only partially closed.

On Linux, the final no-surface outcome is still a log line. For a gated skew or manual result, Hermes deliberately does not relaunch, so a machine with no shim browser and no working notifier can still close with no visible instruction.

The notifier ladder also does not fully verify execution. notify-send now falls through when it fails, which is good, but zenity and kdialog are backgrounded. Their shell command reports successful submission immediately, even if the process then exits because no display or desktop session is available.

More importantly, the claimed next-boot delivery channel does not currently surface manual-success messages. main.ts displays a dialog only when result.ok is false. An ok:true result with a skew, sandbox, or reopen instruction is only logged and then consumed. The comment that the relaunched or next-boot Desktop surfaces that message therefore does not match the current consumer.

I think the result protocol needs to distinguish ordinary success from manual action required, and the Desktop must visibly surface the latter when it consumes the result. That would at least make the durable fallback real. If immediate browserless Linux disappearance is accepted as an unavoidable limitation, the code and PR should describe it as best-effort recovery rather than guaranteed recovery. Otherwise, it still needs a recovery surface that does not depend on optional desktop utilities.

One smaller macOS edge remains in the same area: the DONE_NOTE branch calls launch_app || true, so failure to reopen the kept or rolled-back bundle is ignored and not reflected in the durable message.

The packaged macOS update and real Linux run are also still outstanding. I would wait to approve this until the packaged macOS and real Linux runs are complete and the manual-result delivery issue is fixed.

[OutThisLife]

@helix4u — round 4 in 015f595.

The durable channel is now real, and it's the contract. You were right that "next boot surfaces it" didn't match the consumer — main.ts only dialogged ok:false. The result protocol now carries manual: an ok result the user still must act on. Both orchestrators set it on every DONE_NOTE/downgrade path (skew, sandbox-manual, rejected launch), and the Desktop surfaces manual results in a real dialog when it consumes them. So the browserless-Linux gated case now ends at a visible dialog, worst case one boot later — not a log line. Older result files without the field parse as manual:false (covered in handoff-result.test.ts).

Notifier ladder verifies execution. zenity/kdialog must survive their first second — an instant death (no display/session) falls through instead of reporting submission. The end of the ladder is now explicitly documented as best-effort immediate delivery whose guaranteed channel is the result dialog above; the code and comments no longer claim more than that. On the residual case you named — no browser, no working notifier, gated skew, user watching the machine right now — immediate visibility is accepted as best-effort; the guarantee is durable-and-visible, one boot deferred. That's now what the code says it is.

mac DONE_NOTE + failed reopen: || true dropped — the durable message now carries both facts ("update ok, previous version kept, and Hermes could not reopen itself").

Matrices assert manual in the result JSON; updater-process + handoff-result suites 25/25, typecheck clean, gate/launch matrices green, ps1 AST clean.

On the merge gate: agreed and unchanged — packaged mac dogfood + one real Linux run before this merges. Those two runs are queued; this PR shouldn't land on green CI alone.

[helix4u]

The manual-result protocol now matches the intended contract. One retention edge remains: readAndConsumeHandoffResult() still applies the 30-minute freshness limit to manual:true results.

If browserless Linux has no working notifier and the user reopens Hermes more than 30 minutes later, Desktop deletes the manual result as stale and never shows the action-required dialog.

Please preserve manual:true results until they are consumed, or give them a separate retention policy. A regression should verify that an old ordinary result is discarded while an old manual result is still returned once.

[OutThisLife]

@helix4u — fixed in 4280413. manual:true results are now exempt from the freshness window: they're the durable action-required channel, and the browserless-Linux boot dialog is the first and only place the message ever surfaces, so a >30-min reopen must not drop it. readAndConsumeHandoffResult() now parses before the age check and only applies maxAgeMs to non-manual results. The unconditional unlinkSync still runs before any age check, so a manual result is surfaced at most once — no resurfacing on a later boot. Ordinary results still expire as before.

Regression added (handoff-result.test.ts): a stale ordinary result is discarded (and consumed), while a stale manual result is still returned once and null on the second read.

[helix4u]

@OutThisLife
Thanks, I re-reviewed 4280413db against current main. The stale-manual-result fix is correct: ordinary results still expire, while manual:true results survive until they are consumed once. The previous correctness findings are addressed.

I found one remaining integration issue in the durable-result path.

readAndConsumeHandoffResult() is only called inside waitForUpdateToFinish(), which is passed to runPrimaryBackendStartup() as waitForLocalStart. An already-saved remote connection returns before that callback runs. The existing startup test explicitly asserts that waitForLocalStart is never called for a saved remote.

As a result, a Desktop boot using a saved remote backend never consumes or displays a local handoff failure or manual:true result. The manual result no longer expires, which prevents permanent loss, but it can remain hidden indefinitely. This is narrower than the normal remote update flow, since that flow targets the remote backend, but it still breaks the stated contract that the next Desktop boot surfaces the durable result.

Please separate result consumption and surfacing from the local update-marker wait, then run the result consumer unconditionally during Desktop startup. The marker wait can remain local-only. A regression should cover an already-saved remote connection with a pending manual or failed handoff result.

Non-blocking: the PR body should be refreshed before merge. It still describes a two-event shim and unchanged result contract, says POSIX falls back to log-only, and says Windows visual QA is pending. Those statements no longer match the current implementation or later test evidence.