Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

docs(windows): staged host survives updates; unattended preflight wait; feed check

review68dbcdd95923
diff --git a/CLAUDE.md b/CLAUDE.md
index c06ca6534..697c6d3f7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9312,13 +9312,16 @@ beside the installer + zip. The app checks the feed and shows the same "vX is av
Download" card a Linux .deb gets; it never downloads, never installs on quit, and main refuses
`appRestartToUpdate` for any build that is not `self-install`/`dev` (`mayQuitAndInstall`), so
`quitAndInstall` cannot run on the unsigned beta whatever the renderer sends. A failed
-AUTOMATIC check on that marker build is logged, not carded (offline, or a mirror that does not
-serve `latest.yml` yet, must not raise an error card on every launch); a user-initiated check
-still reports its failure. Local `dist:win`
+AUTOMATIC check on that marker build is not carded (offline, or a mirror that does not
+serve `latest.yml` yet, must not raise an error card on every launch) but is recorded
+(`lastUpdateCheck`) and logged as one warning that names a 404 on `latest*.yml` as the mirror
+missing the file (`describeCheckFailure`); a user-initiated check still reports its failure. Local `dist:win`
keeps `disabled` (never polls). Do not add `*.blockmap` (or a broad `*.yml`) to that job's
upload globs — differential downloads are the self-install leg, and it waits on signing; guarded
by `src/main/release-win-workflow.test.ts`. The nodeterm.dev/updates mirror serving `latest.yml`
-lives outside this repo. `bootstrap-windows.bat` (repo root) takes a fresh Windows
+lives outside this repo; `release.yml`'s `verify-feed` job (after the promote, never a gate) curls
+each `latest*.yml` there and compares `version:` to the tag — mac/linux are errors, `latest.yml` a
+warning until the mirror is confirmed to serve it. `bootstrap-windows.bat` (repo root) takes a fresh Windows
machine to a built checkout: it verifies Node ≥ 20 / VS Build Tools C++ / Python 3 with exact
winget hints (it never installs machine-wide tools itself, and the full bootstrap refuses to run
elevated) and runs `npm ci`. Its `--check-vs-build-tools` mode is the narrow exception used by
@@ -9340,6 +9343,12 @@ Update preparation must keep saved canvas nodes: exit programs normally, quit, t
verify and stop any remaining host. Never recommend **End session** (it deletes nodes). Cold agent
resume depends on supported, saved conversation history; it does not preserve running tasks.
See `docs/windows-session-host.md` for the user-controlled preparation/recovery steps and limits.
+**Unattended runs wait** (silent or `--updated`, the app's own handoff, which starts while
+nodeterm.exe is still exiting): on preflight exit 10 they poll up to ~30 s; exit 20 stays fatal at
+once, nothing is ever killed, and the machine-wide name match stays (old uninstallers kill by
+name). A timed-out `--updated` install writes `%LOCALAPPDATA%\nodeterm\update-failed.json` and
+relaunches the installed build before quitting; the updater reads + deletes that note on start
+(`main/update-install-marker.ts`). This is the prerequisite for any future Windows self-install.
**Prepare for update (#829 step 2).** The in-app answer to the refusal above, Windows only.
Rules a refactor must not undo:
@@ -9366,6 +9375,12 @@ Rules a refactor must not undo:
- The confirm is a danger `ConfirmDialog` with `enterConfirms={false}` (Cancel focused) and says
plainly that shells and their unsaved work stop and that nodes are kept. Never route anything
through End session / node deletion.
+- **A staged host only needs a quit** (U3): the host publishes `exe` (its `process.execPath`) in
+ its state file (optional, additive); `classifyHostImage` / `resolveHostStaging`
+ (`core/session-host-runtime.ts`) answer `staged | install | unknown`, falling back to a process
+ query by pid for 0.4.1–0.4.3 hosts. Only `staged` sets `UpdatePrepInspection.staged`, and only
+ then does the dialog lead with "Quit nodeterm (sessions keep running)" (`prepareEntry`), with
+ stopping sessions as the secondary path. `unknown` is never staged — fail closed to the stop flow.
- IPC (`app:update-prep-*`) is raw `ipcMain`, main-window senders only, and in
`HOST_ONLY_CHANNELS`. Server Edition: the bridge stub answers `unsupported` (Linux tmux, no
installer; a browser must never end every session on the server). Mobile: N/A — a phone cannot
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4794b1458..395df0f5a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -111,6 +111,9 @@ confirms what still stops (Cancel focused), then sends the host's `shutdown` com
once the host process is confirmed gone. `shutdown` is a negotiated hello feature: never send it to
a host that did not advertise it, and never add a taskkill/name-kill fallback — an older host gets
the manual steps. The flow never deletes a node. Server Edition: degraded stub (`unsupported`).
+A host classified `staged` (runs from its `%LOCALAPPDATA%` copy) only needs a quit, so the dialog
+leads with "Quit nodeterm (sessions keep running)"; `unknown` must never be treated as staged.
+The NSIS preflight waits (bounded, exit 10 only) in silent/`--updated` runs and never kills.
Staged host runtime (#829 step 3): a packaged Windows build launches the host from a private
copy, `%LOCALAPPDATA%\nodeterm\session-host\<version>-<fingerprint>\nodeterm-sessionhost-v2.exe`
diff --git a/docs/windows-session-host.md b/docs/windows-session-host.md
index 9d48f81a7..4bcb7a0d9 100644
--- a/docs/windows-session-host.md
+++ b/docs/windows-session-host.md
@@ -538,7 +538,10 @@ name begins with this installation's name) can therefore block an update. The ne
cover those legacy targets before invoking the old executable; it never stops them on your behalf.
**The in-app way (nodeterm with the `shutdown` host feature):** open the command palette
-(Ctrl+K) → **Prepare for update…**, or the button on the update card. It:
+(Ctrl+K) → **Prepare for update…**, or the button on the update card. When the running host is the
+staged copy, the dialog leads with **Quit nodeterm (sessions keep running)** — quit, including from
+the system tray, then run the installer; **Stop all sessions instead…** is the secondary path. A
+host whose location cannot be determined is treated as blocking. Otherwise it:
1. lists every session the host holds — every project, closed ones too — and waits while any agent
is working or waiting for your answer (each listed with a **Go** button; **Check again** when
@@ -589,9 +592,18 @@ alone does not guarantee resume, restore an in-flight task, or recover unsaved w
New installers run this check before invoking the previous version's uninstaller. Already shipped
installers/uninstallers cannot be patched retroactively; use the same preparation steps for them.
-This is a safe refusal and manual recovery path, not live host migration: sessions cannot yet
-survive replacing the binaries they have mapped. A process could still start after the preflight;
-it is not an installation-wide launch lock.
+This is a safe refusal and manual recovery path, not live host migration. A **staged** host
+(0.4.1 and later, running from `%LOCALAPPDATA%\nodeterm\session-host`) maps none of the installed
+files, so it does not block the installer and its sessions survive the update — quitting nodeterm
+(from the tray too) is enough; device-verified across 0.4.1 → 0.4.2 → 0.4.3 in #829, all sessions
+reattached warm. Only a legacy hard-link host inside the installation must be stopped first. A
+process could still start after the preflight; it is not an installation-wide launch lock.
+
+Unattended runs (silent, or the app's own `--updated` handoff) wait up to about 30 seconds for
+nodeterm to finish exiting before refusing; "could not verify" (exit 20) still refuses at once. If
+an `--updated` install still finds nodeterm running, it writes
+`%LOCALAPPDATA%\nodeterm\update-failed.json`, restarts the installed version, and quits; the app
+logs the failure on its next start.
Server Edition has no NSIS updater and is unchanged. Mobile/relay clients must expect a disconnect
when the user deliberately ends desktop sessions; they cannot authorize an update shutdown.