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.

fix(windows): refuse updates while persistent sessions are running

enes129b3bb3bf84
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8bb7a4597..9c6e55c30 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -71,4 +71,4 @@ jobs:
run: npm run host:build
- name: Windows-relevant tests
- run: npx vitest run src/core/fs-atomic.test.ts src/core/fs-atomic.guard.test.ts src/core/exec-path.test.ts src/core/claude-cli.test.ts src/core/codex-identity-caps.test.ts src/core/codex-cli.test.ts src/core/grok-cli.test.ts src/core/commit-message.test.ts src/core/context-link.windows.test.ts src/core/git-service.windows.test.ts src/core/usage/codex-usage.windows.test.ts src/session-host/ src/core/session-host-client.test.ts src/core/session-host-launch-ledger.test.ts src/core/session-host-client-startup-wait.test.ts src/core/agent-launch.test.ts src/core/pty-session-host.test.ts src/main/bootstrap-windows.test.ts src/main/media-protocol.test.ts src/main/remote-atomic-write.test.ts src/main/ssh-fs.test.ts src/main/remote-ssh/ssh-project.test.ts src/renderer/terminal/file-links.test.ts src/renderer/terminal/file-links.windows.test.ts src/renderer/terminal/file-link-dialect.test.ts src/renderer/terminal/host-platform.test.ts src/main/pairing-service.windows.test.ts src/main/windows-ssh-keys.test.ts src/shared/pairing-gate.test.ts src/renderer/components/settings/sections/PhoneSection.windows.test.tsx
+ run: npx vitest run scripts/windows-update-preflight.test.ts src/core/fs-atomic.test.ts src/core/fs-atomic.guard.test.ts src/core/exec-path.test.ts src/core/claude-cli.test.ts src/core/codex-identity-caps.test.ts src/core/codex-cli.test.ts src/core/grok-cli.test.ts src/core/commit-message.test.ts src/core/context-link.windows.test.ts src/core/git-service.windows.test.ts src/core/usage/codex-usage.windows.test.ts src/session-host/ src/core/session-host-client.test.ts src/core/session-host-launch-ledger.test.ts src/core/session-host-client-startup-wait.test.ts src/core/agent-launch.test.ts src/core/pty-session-host.test.ts src/main/bootstrap-windows.test.ts src/main/media-protocol.test.ts src/main/remote-atomic-write.test.ts src/main/ssh-fs.test.ts src/main/remote-ssh/ssh-project.test.ts src/renderer/terminal/file-links.test.ts src/renderer/terminal/file-links.windows.test.ts src/renderer/terminal/file-link-dialect.test.ts src/renderer/terminal/host-platform.test.ts src/main/pairing-service.windows.test.ts src/main/windows-ssh-keys.test.ts src/shared/pairing-gate.test.ts src/renderer/components/settings/sections/PhoneSection.windows.test.tsx
diff --git a/CLAUDE.md b/CLAUDE.md
index f108819c7..acad57c00 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4491,6 +4491,11 @@ component is absent, which otherwise fails only after the full install with `MSB
`/opt:lldltojobs` with `LNK1117`. These are gyp overrides, not a reason to reject a Node version
allowed by `package.json`. `.github/workflows/win-package-smoke.yml` is a
**workflow_dispatch-only** packaging smoke on windows-latest — build only, never publishes.
+Windows installer safety (#829): `build/installer.nsh` overrides NSIS's process-killing check.
+A running app or session host blocks install/uninstall, and a failed process query blocks too.
+Never restore automatic host termination: quitting the app preserves those live sessions.
+See `docs/windows-session-host.md` for the user-controlled preparation/recovery steps and limits.
+
**Follow-ups, in order:** code signing, then Windows auto-update wiring (electron-updater NSIS leg
+ `latest.yml` on the nodeterm.dev feed — blocked on signing: an unsigned auto-update is a
downgrade in trust), and the fork's PE-identity polish (electron-builder leaves `OriginalFilename`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0223794bd..b3ae6031f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -56,6 +56,11 @@ handler needs something only Electron has (an SSH ControlMaster, a native dialog
**injected dep** whose absence is a documented degrade — see `registerTranscriptIpc` /
`registerContextEnsureIpc` — rather than a reason to keep the whole handler in `src/main`.
+Windows installer safety (#829): `build/installer.nsh` overrides NSIS's process-killing check.
+A running app or session host blocks install/uninstall, and a failed process query blocks too.
+Never restore automatic host termination: quitting the app preserves those live sessions.
+See `docs/windows-session-host.md` for the user-controlled preparation/recovery steps and limits.
+
## Three surfaces
A feature is not done until you have decided how it behaves on each — even if the decision is "not
diff --git a/build/installer.nsh b/build/installer.nsh
new file mode 100644
index 000000000..185cabda7
--- /dev/null
+++ b/build/installer.nsh
@@ -0,0 +1,24 @@
+# Override BOTH install and uninstall checks. The stock check can kill processes under INSTDIR,
+# including the detached session host. A renamed hard link still holds the installed image open.
+!macro customCheckAppRunning
+ InitPluginsDir
+ File /oname=$PLUGINSDIR\nodeterm-update-preflight.ps1 "${BUILD_RESOURCES_DIR}/windows-update-preflight.ps1"
+ nodeterm_preflight_retry:
+ nsExec::Exec /TIMEOUT=15000 '"$SYSDIR\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$PLUGINSDIR\nodeterm-update-preflight.ps1" -InstallDirectory "$INSTDIR"'
+ Pop $R0
+ ${If} $R0 == 0
+ Goto nodeterm_preflight_clear
+ ${EndIf}
+ # Silent installs must fail closed too, with a nonzero result and no default consent.
+ SetErrorLevel 2
+ IfSilent nodeterm_preflight_cancel
+ ${If} $R0 == 10
+ MessageBox MB_RETRYCANCEL|MB_ICONEXCLAMATION "nodeterm or its background session host is still running.$\r$\n$\r$\nClosing the app keeps terminal and agent sessions alive. Updating requires those sessions to end.$\r$\n$\r$\nCancel to keep working. When ready, save your work, reopen nodeterm, and end local sessions in every project (Sessions sidebar: End session). Quit nodeterm, wait at least 30 seconds for the host to exit, then retry.$\r$\n$\r$\nThis installer will not stop your sessions for you." /SD IDCANCEL IDRETRY nodeterm_preflight_retry
+ ${Else}
+ MessageBox MB_RETRYCANCEL|MB_ICONEXCLAMATION "nodeterm could not verify whether the app or its background session host is running. No sessions have been stopped.$\r$\n$\r$\nCancel and check that Windows PowerShell and process queries are available. If another Windows user is running nodeterm, ask them to save and end their sessions before retrying." /SD IDCANCEL IDRETRY nodeterm_preflight_retry
+ ${EndIf}
+ nodeterm_preflight_cancel:
+ Quit
+ nodeterm_preflight_clear:
+ SetErrorLevel 0
+!macroend
diff --git a/build/windows-update-preflight.ps1 b/build/windows-update-preflight.ps1
new file mode 100644
index 000000000..3e3b74a26
--- /dev/null
+++ b/build/windows-update-preflight.ps1
@@ -0,0 +1,19 @@
+# Read-only installer gate. No process is terminated, including on query failure.
+# Exit 0 = clear, 10 = app/host running, 20 = could not prove it is safe to proceed.
+param([Parameter(Mandatory = $true)][string]$InstallDirectory)
+$ErrorActionPreference = 'Stop'
+try {
+ if ($InstallDirectory -notmatch '^(?:[A-Za-z]:\\|\\\\)') { exit 20 }
+ $directory = $InstallDirectory.TrimEnd('\') + '\'
+ $processes = @(Get-CimInstance -ClassName Win32_Process -ErrorAction Stop)
+ foreach ($process in $processes) {
+ if ($process.Name -ine 'nodeterm.exe' -and $process.Name -ine 'nodeterm-session-host.exe') { continue }
+ # An inaccessible process might be another user's host in an all-users installation.
+ # Absence of a path is not proof that it belongs to a different installation.
+ if ([string]::IsNullOrWhiteSpace($process.ExecutablePath)) { exit 20 }
+ if ($process.ExecutablePath.StartsWith($directory, [StringComparison]::OrdinalIgnoreCase)) { exit 10 }
+ }
+ exit 0
+} catch {
+ exit 20
+}
diff --git a/docs/windows-session-host.md b/docs/windows-session-host.md
index 3ebb82400..1d68b5453 100644
--- a/docs/windows-session-host.md
+++ b/docs/windows-session-host.md
@@ -346,6 +346,45 @@ confirmed `{ok:true}` host responses, while a transport/request rejection remain
propagated. That propagation is what lets the periodic snapshot keep its dirty bit for a retry and
what prevents a delete from claiming a persistent process is gone when the host never confirmed it.
+## Windows updates and uninstalls
+
+A running host maps the installed Electron executable and its DLLs. Its separate hard-link name
+makes it identifiable; it does **not** make the install directory safe to replace. Closing the app
+alone deliberately leaves the host and its sessions running (#829).
+
+The NSIS install/uninstall preflight now refuses to proceed while the app or host is running from
+the target installation. It replaces electron-builder's automatic process termination, including
+its silent/`--updated` path. Cancel leaves sessions alone. Retry performs a fresh, read-only process
+query. A failed query (including an inaccessible nodeterm process with no executable path) blocks
+instead of guessing. Silent installation returns a nonzero exit code, without a dialog or kill.
+The query uses Windows PowerShell with a child-process-only execution policy; no persistent policy
+or trust setting is changed. Group Policy restrictions still cause a safe refusal.
+
+To update when you are ready to end sessions:
+
+1. Cancel the installer and reopen nodeterm if you already quit it. Save work in local terminals
+ and agents, including those in closed/other projects and sessions accessed from a phone.
+2. Use **End session** in the Sessions sidebar for each local session. This ends its process and
+ removes its node; do not mistake closing a project or quitting the app for ending a session.
+ Shells may also be exited normally once their work is saved.
+3. Quit nodeterm, wait at least 30 seconds after the last session ends, and run the installer again.
+ Do not reopen the app or start sessions while installation is in progress.
+4. If the host remains, keep the installer cancelled and inspect Windows Task Manager's Details
+ view. Verify the executable path belongs to this installation. Ending that exact host manually
+ is a last resort **only if you accept losing every terminal/agent process it owns**; never use
+ a machine-wide name-based kill. A host shared by another Windows user requires their decision.
+
+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.
+
+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.
+Real Windows per-user/all-users upgrades, old uninstallers, PowerShell policy variations, and
+phone reconnection still require device verification (fixtures do not prove file-lock behavior).
+
## Lifetime
Mirrors tmux's server lifetime rule as closely as a different OS allows:
diff --git a/package.json b/package.json
index 67e1266e3..e7bd51a83 100644
--- a/package.json
+++ b/package.json
@@ -142,7 +142,8 @@
"nsis": {
"artifactName": "${productName}-Setup-${version}.${ext}",
"oneClick": true,
- "perMachine": false
+ "perMachine": false,
+ "include": "build/installer.nsh"
},
"publish": {
"provider": "generic",
diff --git a/scripts/windows-update-preflight.test.ts b/scripts/windows-update-preflight.test.ts
new file mode 100644
index 000000000..215f7d8f2
--- /dev/null
+++ b/scripts/windows-update-preflight.test.ts
@@ -0,0 +1,87 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+
+const root = path.resolve(__dirname, '..')
+const script = path.join(root, 'build/windows-update-preflight.ps1')
+const include = fs.readFileSync(path.join(root, 'build/installer.nsh'), 'utf8')
+const powershell = process.platform === 'win32' ? 'powershell.exe' : 'pwsh'
+const available = spawnSync(powershell, ['-NoProfile', '-Command', 'exit 0']).status === 0
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'nodeterm-update-fixture-'))
+afterAll(() => fs.rmSync(temp, { recursive: true, force: true }))
+
+type Process = { Name: string; ExecutablePath: string | null }
+const app: Process = { Name: 'nodeterm.exe', ExecutablePath: 'C:\\Apps\\nodeterm\\nodeterm.exe' }
+const host: Process = {
+ Name: 'nodeterm-session-host.exe',
+ ExecutablePath: 'C:\\Apps\\nodeterm\\nodeterm-session-host.exe'
+}
+function probe(processes: Process[], fail = false, directory = 'C:\\Apps\\nodeterm'): number | null {
+ // Override only the query, in a fresh PowerShell process. Never enumerate or stop real sessions.
+ const fixture = path.join(temp, 'processes.json')
+ fs.writeFileSync(fixture, JSON.stringify(processes))
+ const quote = (s: string): string => "'" + s.replace(/'/g, "''") + "'"
+ const command = `function Get-CimInstance { param($ClassName, $ErrorAction)
+ ${fail ? "throw 'fixture query denied'" : `Get-Content -Raw ${quote(fixture)} | ConvertFrom-Json`}
+ }; & ${quote(script)} -InstallDirectory ${quote(directory)}; exit $LASTEXITCODE`
+ return spawnSync(powershell, ['-NoProfile', '-NonInteractive', '-Command', command], {
+ timeout: 15000
+ }).status
+}
+
+describe.skipIf(!available)('installer preflight with disposable process-query fixtures', { timeout: 30000 }, () => {
+ it.each([
+ ['app closed / host live', [host], 10],
+ ['app live / host live', [app, host], 10],
+ ['app live / no host', [app], 10],
+ ['app closed / host exited', [], 0],
+ ['host fallback to original executable', [app], 10],
+ ['host in another installation', [{ ...host, ExecutablePath: 'C:\\Apps\\nodeterm-other\\nodeterm-session-host.exe' }], 0],
+ ['case-insensitive Windows path', [{ ...host, ExecutablePath: host.ExecutablePath!.toUpperCase() }], 10],
+ ['unknown host owner/path', [{ ...host, ExecutablePath: null }], 20],
+ ['unknown app owner/path', [{ ...app, ExecutablePath: '' }], 20],
+ ['uninstaller is not the app', [{ Name: 'Uninstall nodeterm.exe', ExecutablePath: 'C:\\Apps\\nodeterm\\Uninstall nodeterm.exe' }], 0]
+ ] as const)('%s', (_name, processes, result) => {
+ expect(probe([...processes])).toBe(result)
+ })
+ it('refuses failed queries and invalid installation paths', () => {
+ expect(probe([], true)).toBe(20)
+ expect(probe([], false, 'relative')).toBe(20)
+ })
+ it('supports spaces, apostrophes, trailing separators and UNC installations', () => {
+ for (const directory of ["C:\\User's Apps\\nodeterm", '\\\\server\\share\\nodeterm', 'C:\\Apps\\nodeterm\\']) {
+ expect(probe([{ ...host, ExecutablePath: directory.replace(/\\$/, '') + '\\nodeterm-session-host.exe' }], false, directory)).toBe(10)
+ }
+ })
+})
+
+describe('NSIS safety wiring', () => {
+ it.skipIf(process.platform !== 'win32')('requires PowerShell fixtures on Windows CI', () => {
+ expect(available).toBe(true)
+ })
+ it('replaces the stock destructive check in both installer and uninstaller', () => {
+ const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
+ expect(pkg.build.nsis.include).toBe('build/installer.nsh')
+ expect(include).toContain('!macro customCheckAppRunning')
+ const templates = path.dirname(require.resolve('app-builder-lib/package.json')) + '/templates/nsis/'
+ const running = fs.readFileSync(templates + 'include/allowOnlyOneInstallerInstance.nsh', 'utf8')
+ expect(running).toMatch(/!ifmacrodef customCheckAppRunning\s+!insertmacro customCheckAppRunning\s+!else/)
+ const install = fs.readFileSync(templates + 'installSection.nsh', 'utf8')
+ const check = install.indexOf('!insertmacro CHECK_APP_RUNNING')
+ expect(check).toBeGreaterThanOrEqual(0)
+ expect(check).toBeLessThan(install.indexOf('!insertmacro uninstallOldVersion SHELL_CONTEXT'))
+ expect(fs.readFileSync(templates + 'uninstaller.nsh', 'utf8')).toContain('!insertmacro CHECK_APP_RUNNING')
+ })
+ it('only proceeds on proven clear; silent, error and cancellation paths quit nonzero', () => {
+ expect(include).toMatch(/\$R0 == 0\s+Goto nodeterm_preflight_clear/)
+ expect(include).toMatch(/SetErrorLevel 2\s+IfSilent nodeterm_preflight_cancel/)
+ expect(include).toMatch(/nodeterm_preflight_cancel:\s+Quit/)
+ expect(include.match(/\/SD IDCANCEL/g)).toHaveLength(2)
+ expect(include).toContain('wait at least 30 seconds')
+ expect(include).toContain('This installer will not stop your sessions')
+ const production = include + fs.readFileSync(script, 'utf8')
+ expect(production).not.toMatch(/\b(?:Stop-Process|taskkill|KILL_PROCESS|_CHECK_APP_RUNNING|Set-ExecutionPolicy)\b/i)
+ })
+})
diff --git a/src/core/session-host-launcher.ts b/src/core/session-host-launcher.ts
index 995cbc023..0358d4096 100644
--- a/src/core/session-host-launcher.ts
+++ b/src/core/session-host-launcher.ts
@@ -83,16 +83,11 @@ export interface HostLinkFs {
* The binary to spawn the host with — `execPath` everywhere, except on Windows, where it is a hard
* link beside it named `nodeterm-session-host.exe`.
*
- * The host is deliberately detached and outlives the app, and it is the Electron binary, so it runs
- * as `nodeterm.exe`. The one-click NSIS installer identifies the running app by image name plus
- * install directory and waits on it — so a host left running after a quit IS the app as far as the
- * installer can tell, and the install stalls until that process is killed by hand. Reported the
- * first time anyone installed a build carrying this feature.
- *
- * A hard link takes the host out of that match structurally rather than by exception: same file, no
- * second copy of a 224 MB binary, no admin, and Windows reports the process under the LINK's name
- * (measured). It must sit in the install directory — Electron needs its sibling DLLs, `locales/`
- * and `resources/`, and a link elsewhere exits immediately (0x80000003, measured).
+ * The separate image name makes the background host identifiable, but does NOT isolate it from
+ * updates: it still maps the installed Electron image and DLLs. NSIS can find processes by path
+ * as well as name. The installer preflight must refuse while this host (or the app) is running;
+ * it must never kill the host implicitly, because doing so ends every preserved session (#829).
+ * The link must sit beside Electron's sibling DLLs, locales/ and resources/ to run.
*
* Identity is compared with BIGINT stats. An NTFS file id is 64-bit and routinely exceeds
* `Number.MAX_SAFE_INTEGER`, so the default numeric `ino` can report two different files as the
@@ -101,7 +96,7 @@ export interface HostLinkFs {
*
* Every failure — a read-only install dir, a filesystem without hard links, a directory squatting
* the name, a link that cannot be removed — returns `execPath`, which is exactly today's behaviour.
- * The worst case is the installer annoyance this fixes, never a host that cannot start.
+ * The installer preflight checks both names, including this fallback.
*/
export function hostLauncherPath(
execPath: string,