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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(windows): refuse updates while persistent sessions are running
enes129b3bb3bf84
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 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.tsxdiff --git a/CLAUDE.md b/CLAUDE.mdindex 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 versionallowed 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 adowngrade in trust), and the fork's PE-identity polish (electron-builder leaves `OriginalFilename`diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 surfacesA feature is not done until you have decided how it behaves on each — even if the decision is "notdiff --git a/build/installer.nsh b/build/installer.nshnew file mode 100644index 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+!macroenddiff --git a/build/windows-update-preflight.ps1 b/build/windows-update-preflight.ps1new file mode 100644index 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.mdindex 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 remainpropagated. That propagation is what lets the periodic snapshot keep its dirty bit for a retry andwhat 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).+## LifetimeMirrors tmux's server lifetime rule as closely as a different OS allows:diff --git a/package.json b/package.jsonindex 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.tsnew file mode 100644index 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.tsindex 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,