docs: the Windows node's three modes and one lifecycle, and what it cost

- MESHBAY_DESIGN.md §11.2: the node runs only while the app is open, at
  sign-in, or as a boot-time service; starting and stopping have one
  implementation, the CLI's; a second instance refuses before it writes
  anything the running one depends on.
- packaging/win/README.md: the three modes, switching between them, upgrading
  a running node, where the log is, the service task's settings.
- docs/windows-build.md: the build's smoke start of the frozen daemon, the log
  location, and what an upgrade does to a running node.
- CLAUDE.md: four engineering lessons -- an upgrade that cannot stop the node
  installs around it; on Windows the CLI is the process it is stopping; a
  second instance must fail before it touches anything shared; a test that
  redirects HOME isolates nothing on Windows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 71 insertions, 12 deletions

diff --git a/packaging/win/README.md b/packaging/win/README.md
index 0598193..3c141d1 100644
--- a/packaging/win/README.md
+++ b/packaging/win/README.md
@@ -36,17 +36,47 @@ back out on uninstall. New shells only — a `WM_SETTINGCHANGE` broadcast nudges
 open ones. It uses stock `WordFunc.nsh` (the `EnVar` plugin is not in
 electron-builder's NSIS bundle).
 
-## Autostart: two modes, one choice at install time
+## When the node runs: three modes, chosen at install time
 
-**Per-user (default, no admin).** A `.vbs` in the Startup folder
-(`meshbay_node.platform._startup_vbs`), toggled from the Node page or
-`meshbay-node autostart install|remove`. Starts when *this user* signs in.
+Setup's radio page, and the Node page's *Start automatically* selector
+afterwards, offer the same three:
 
-**Service mode (one admin confirmation, at install time only).** A Scheduled
-Task, `meshbay_node.platform.service_install` / `packaging/win/service.ps1`,
-that starts **at boot, before anyone signs in**. A real Windows Service would
-run under LocalSystem/NetworkService — accounts with no normal user profile,
-so `%LOCALAPPDATA%\meshbay\` (config, keystore, data) would not exist for it.
+| Mode | What runs it | Stops when |
+|---|---|---|
+| **Only while MeshBay is open** | the desktop app, at launch (once the node has been set up) | the app quits — only a node the app started |
+| **At sign-in** (no admin) | a `.vbs` in the Startup folder (`meshbay_node.platform._startup_vbs`); `meshbay-node autostart install` / `remove` | sign-out (a hidden console of its own delivers CTRL_LOGOFF) |
+| **Background service** (one admin confirmation) | the boot-time Scheduled Task below | shutdown |
+
+The first mode used to do neither half: nothing started the node with the app
+(after a reboot a group stayed offline with MeshBay open) and nothing stopped it
+at quit. The two automatic ones are mutually exclusive — both would start the
+node twice — and `autostart install` refuses while the boot task exists.
+
+**Starting, stopping, restarting — one implementation.** The CLI's
+(`meshbay_node/cli/lifecycle.py`); the Node page, the tray, `node:start` and a
+terminal all go through it. A stop asks the node through its own control API
+first (`POST /api/shutdown`, loopback, per-run token): the only channel that
+reaches a node in any session with no elevation, and the one that runs its
+`_shutdown()` — WebRTC sessions closed, transcodes stopped. Then Task Scheduler,
+then `taskkill`. Before this, every stop of a Windows node was a
+TerminateProcess (nine in a row, not one shutdown logged), the CLI's own
+CTRL_BREAK reached every process on *its* console and killed itself, and the app
+reported a service node it could not reach as stopped. A start launches the node
+with nothing of the caller's inherited (a child of Electron held Electron's
+sockets after the app quit) and reports the version that answered.
+
+**Switching modes.** Leaving service mode stops the node first — deleting a
+task does not end its running instance, which ran on in session 0 with nothing
+able to stop it — removes the task, keeps the firewall rules (every mode needs
+them; removing them left a node that silently accepted no connections), and
+starts the node again in the new mode. Entering it stops the running node first,
+or the service's own finds the control API's port taken and quits.
+
+**Background service.** A Scheduled Task,
+`meshbay_node.platform.service_install` / `packaging/win/service.ps1`, that
+starts **at boot, before anyone signs in**. A real Windows Service would run
+under LocalSystem/NetworkService — accounts with no normal user profile, so
+`%LOCALAPPDATA%\meshbay\` (config, keystore, data) would not exist for it.
 Relocating storage to make that work is real surgery, deliberately not this.
 
 The alternative used instead: `schtasks /create ... /ru <user> /rp ""` with no
@@ -62,8 +92,37 @@ state — the same reason `/sc onlogon` needed it too, back when Task Scheduler
 was tried for the per-user mode and abandoned for exactly that reason).
 Querying, starting and stopping an *already-created* task does not — Task
 Scheduler grants the owning user that much itself, which is what lets the Node
-page's Start/Stop/Restart drive it with no further UAC prompts
-(`src/main.js`'s `winServiceTaskStatus/Run/End`, mirroring `service.ps1`).
+page's Start/Stop/Restart drive it with no further UAC prompts.
+
+**The task's settings.** Registered with no execution time limit, allowed to
+start and keep running on battery, `MultipleInstances IgnoreNew` and
+`StartWhenAvailable`. Task Scheduler's defaults end a task after 72 hours,
+never start it on battery and stop it when the cable comes out — each one a
+node that was simply down. `service.ps1 status` reports a task that still has
+those defaults, or that runs another executable than this install's, as stale
+(exit 2), and setup registers it again (its one elevation).
+
+**Upgrading a running node.** A service node lives in the task's S4U session,
+so an unelevated `taskkill` from setup gets "Access is denied" — and
+electron-builder's `customInstall` only runs after the files are copied anyway.
+Left running, a node keeps `meshbay-node.exe` locked, the copy fails, and
+electron-builder's last-resort extract ignores that. So `customCheckAppRunning`,
+which electron-builder runs before `uninstallOldVersion` and before extraction,
+runs `build/stop-node.ps1` (embedded in the installer — the installed copy of
+anything may be what is being replaced): the control API first, then
+`schtasks /end`, then `taskkill`, until no `meshbay-node.exe` is left; if one
+will not stop, setup says so and quits rather than half-upgrade.
+An upgrade keeps the mode it finds (`customInit` reads the task, then the
+launcher, then a previous install), restores the sign-in launcher — the previous
+version's uninstaller deletes it — and starts the node again the way that mode
+runs it. A silent upgrade of an "at sign-in" install used to come out with no
+autostart at all and its node stopped.
+
+**Logs.** A daemon started by the task or the Startup launcher has no console,
+so it also logs to `%LOCALAPPDATA%\meshbay\state\node.log` (rotated at 5 MB,
+three kept). That file is where to look when the app says the node did not
+start. `meshbay-node service start` waits for the daemon's control API and
+reports the version that answered, or points at this file.
 
 **One elevation, not two.** Choosing service mode needs admin for both the
 Scheduled Task *and* the firewall rules; `service-mode.ps1` runs both from a
@@ -90,7 +149,7 @@ That runs [`build-win.ps1`](build-win.ps1):
 | 2 | `npm ci` + download Electron's Chromium |
 | 3 | bump Electron to the latest release (Chromium CVE policy; `-NoElectronBump` to skip) |
 | 4 | `npm run sync-ui` — copy the interface from `meshbay-hub/.../static` |
-| 5 | [`build-node-runtime.ps1`](build-node-runtime.ps1) — PyInstaller freeze → `packages/meshbay-client/node-runtime/` |
+| 5 | [`build-node-runtime.ps1`](build-node-runtime.ps1) — PyInstaller freeze → `packages/meshbay-client/node-runtime/`, then [`smoke-node-runtime.ps1`](smoke-node-runtime.ps1) starts the frozen daemon in a throwaway profile and checks it answers with the right version and writes its log |
 | 6 | `electron-builder --win nsis` → `packages/meshbay-client/dist/MeshBay-Setup-<version>.exe` |
 
 ### Video (ffmpeg)