fix(win): graceful shutdown, one startup-mode control, and a stray-\r bug

Windows-only changes, all found by actually running the previous session's
work rather than by review alone:

- CTRL_CLOSE_EVENT/LOGOFF/SHUTDOWN handler (platform.py, ctypes
  SetConsoleCtrlHandler) so closing a console window, signing off, or a
  system shutdown runs the daemon's real _shutdown() instead of Windows
  just ending the process — closing WebRTC sessions and any in-flight
  ffmpeg transcode instead of orphaning it. `taskkill /F` itself stays
  uncatchable (like SIGKILL), so autostart_run() now spawns with
  CREATE_NEW_PROCESS_GROUP instead of DETACHED_PROCESS and autostart_end()
  tries CTRL_BREAK_EVENT against the recorded pid first, falling back to
  the hard kill only if that doesn't stop it in time.

- Replaced the Node page's two independent autostart/service-mode toggles
  with one "start automatically" select (off / at sign-in / as a
  background service). The old pair let both be active at once — starting
  the daemon twice, at boot and at sign-in — and their layout broke
  wrapping inside .node-service's flex row. The new control always removes
  whichever mechanism is active before installing the target; platform.py's
  service_install() does the same on the CLI side. The "background
  service" option disables itself (with a hint pointing at the CLI) when
  running unpackaged, since service-mode.ps1/service.ps1/firewall.ps1 all
  assume an installed build's layout — verified live rather than assumed
  by actually running those scripts unelevated.

- findNodeBinary() no longer bakes a stray \r into resolved paths. Found by
  rebooting after enabling per-user autostart: where.exe listed two
  matches, and stdout.trim().split('\n')[0] only strips the whole string's
  ends, leaving line one's own trailing \r attached — which landed inside
  the Startup .vbs's quoted path and broke it with "Unterminated string
  constant" at boot. Fixed by splitting on \r?\n and trimming every line.

- Dependency audit for the Windows installer (docs/WINDOWS-PORT.md): no
  VC++ Redistributable needed, confirmed by inspecting the built
  node-runtime's actual import table rather than assuming. New
  docs/windows-build.md: a concise clone-to-installer build guide.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

4 files changed, 385 insertions, 13 deletions

diff --git a/packages/meshbay-node/src/meshbay_node/daemon.py b/packages/meshbay-node/src/meshbay_node/daemon.py
index b932c16..ea13680 100644
--- a/packages/meshbay-node/src/meshbay_node/daemon.py
+++ b/packages/meshbay-node/src/meshbay_node/daemon.py
@@ -678,9 +678,18 @@ class NodeDaemon:
             # 12. Wait for shutdown
             stop_event = asyncio.Event()
             loop = asyncio.get_event_loop()
+            console_shutdown_done = None
             if sys.platform == "win32":
-                for sig in (signal.SIGINT, signal.SIGTERM):
+                # SIGBREAK: CTRL_BREAK_EVENT, how platform.autostart_end() asks
+                # a per-user-mode daemon to stop gracefully instead of only
+                # ever taskkill /F.
+                for sig in (signal.SIGINT, signal.SIGTERM, signal.SIGBREAK):
                     signal.signal(sig, lambda *_: stop_event.set())
+                # CTRL_CLOSE/LOGOFF/SHUTDOWN reach no Python signal at all --
+                # see platform.install_console_close_handler for why this is
+                # a separate mechanism rather than another signal.signal() line.
+                from meshbay_node.platform import install_console_close_handler
+                console_shutdown_done = install_console_close_handler(loop, stop_event)
             else:
                 for sig in (signal.SIGINT, signal.SIGTERM):
                     loop.add_signal_handler(sig, stop_event.set)
@@ -694,6 +703,13 @@ class NodeDaemon:
             await stop_event.wait()
 
         await self._shutdown()
+        if console_shutdown_done is not None:
+            # Releases the console-control handler's blocking wait (see
+            # platform.install_console_close_handler) so it can return and
+            # let Windows actually end the process for CTRL_CLOSE/LOGOFF/
+            # SHUTDOWN, now that cleanup is genuinely done rather than just
+            # started.
+            console_shutdown_done.set()
 
     async def _reload_config(self) -> None:
         """
diff --git a/packages/meshbay-node/src/meshbay_node/platform.py b/packages/meshbay-node/src/meshbay_node/platform.py
index 9b18618..981d466 100644
--- a/packages/meshbay-node/src/meshbay_node/platform.py
+++ b/packages/meshbay-node/src/meshbay_node/platform.py
@@ -1,12 +1,18 @@
 """Platform-specific paths and tool resolution for meshbay-node."""
 
 import asyncio
+import logging
 import os
 import shutil
+import signal
 import subprocess
 import sys
+import threading
+import time
 from pathlib import Path
 
+log = logging.getLogger(__name__)
+
 # ── Console ──────────────────────────────────────────────────────────────────
 
 
@@ -213,6 +219,24 @@ def _startup_vbs() -> Path:
             / "Startup" / "MeshBay Node.vbs")
 
 
+def _pid_file() -> Path:
+    """Where autostart_run() records the pid it spawned, for autostart_end()
+    to signal later -- possibly from a different process (a new Electron
+    session, or a fresh CLI invocation), so this cannot be an in-memory
+    handle."""
+    return state_dir() / "node.pid"
+
+
+def _pid_is_meshbay_node(pid: int) -> bool:
+    """True if `pid` is currently running *and* is meshbay-node.exe. Guards
+    against a stale pidfile whose pid Windows has since handed to an
+    unrelated process -- autostart_end() would otherwise send CTRL_BREAK_EVENT
+    to whatever that is instead."""
+    r = subprocess.run(["tasklist", "/FI", f"PID eq {pid}", "/NH"],
+                       capture_output=True, text=True)
+    return "meshbay-node.exe" in r.stdout.lower()
+
+
 def _node_exe() -> str | None:
     """Best guess at the meshbay-node launcher: PATH first, then next to the
     interpreter (a venv's Scripts/ dir, or a bundled runtime), then argv[0]."""
@@ -260,22 +284,76 @@ def autostart_remove() -> None:
 
 
 def autostart_run() -> None:
-    """Start the daemon now, detached and windowless. Raises RuntimeError if
-    the launcher cannot be located."""
+    """Start the daemon now, windowless. Raises RuntimeError if the launcher
+    cannot be located."""
     if not autostart_supported():
         raise RuntimeError("autostart is Windows-only")
     exe = _node_exe()
     if not exe:
         raise RuntimeError("cannot locate the meshbay-node launcher")
-    subprocess.Popen([exe], creationflags=0x00000008 | 0x08000000,  # DETACHED | NO_WINDOW
-                     close_fds=True)
+    # CREATE_NEW_PROCESS_GROUP, not DETACHED_PROCESS: still no visible window
+    # (CREATE_NO_WINDOW), but the child keeps a console object of its own and
+    # becomes the root of its own process group -- what autostart_end() needs
+    # to target it with CTRL_BREAK_EVENT instead of only ever a hard taskkill.
+    # DETACHED_PROCESS has no console at all, so nothing could be signalled.
+    proc = subprocess.Popen([exe], creationflags=0x00000200 | 0x08000000,
+                            close_fds=True)
+    try:
+        pid_file = _pid_file()
+        pid_file.parent.mkdir(parents=True, exist_ok=True)
+        pid_file.write_text(str(proc.pid), encoding="utf-8")
+    except OSError:
+        pass  # best effort -- autostart_end() falls back to taskkill by image name
+
+
+# How long autostart_end() waits for a graceful CTRL_BREAK_EVENT stop before
+# giving up and force-killing. A chosen grace period, not an OS-enforced one
+# (unlike the ~5 s Windows itself allows a CTRL_CLOSE/LOGOFF/SHUTDOWN handler,
+# see install_console_close_handler below -- CTRL_BREAK carries no such ceiling).
+_GRACEFUL_STOP_TIMEOUT_SECS = 5.0
 
 
 def autostart_end() -> None:
-    """Stop any running daemon (hard: there is no CTRL_CLOSE handler yet)."""
-    if autostart_supported():
-        subprocess.run(["taskkill", "/IM", "meshbay-node.exe", "/F"],
-                       capture_output=True)
+    """
+    Stop the running daemon.
+
+    Tries a graceful stop first: CTRL_BREAK_EVENT to the pid autostart_run()
+    recorded. Because that process is the root of its own group
+    (CREATE_NEW_PROCESS_GROUP), daemon.py's own SIGBREAK handler turns this
+    into the same stop_event.set() SIGINT/SIGTERM already use, running the
+    real _shutdown() -- closes WebRTC sessions, kills any in-flight ffmpeg
+    transcode. Falls back to a hard `taskkill /F`, by image name, when there
+    is no pidfile, the recorded process is already gone, or it does not exit
+    within the grace period -- same as before this existed, just no longer
+    the only path. `taskkill /F` itself is TerminateProcess and cannot be made
+    graceful; nothing can catch it, on any OS.
+    """
+    if not autostart_supported():
+        return
+    pid_file = _pid_file()
+    try:
+        pid = int(pid_file.read_text(encoding="utf-8").strip())
+    except (OSError, ValueError):
+        pid = None
+    if pid is not None and not _pid_is_meshbay_node(pid):
+        pid = None  # stale pidfile -- Windows may have reused the pid since
+    if pid is not None:
+        try:
+            os.kill(pid, signal.CTRL_BREAK_EVENT)
+        except OSError:
+            pid = None  # already gone, or never existed
+        else:
+            deadline = time.monotonic() + _GRACEFUL_STOP_TIMEOUT_SECS
+            while time.monotonic() < deadline:
+                if not _pid_is_meshbay_node(pid):
+                    pid_file.unlink(missing_ok=True)
+                    return
+                time.sleep(0.2)
+            log.warning("pid %d did not exit within %.1fs of CTRL_BREAK_EVENT, "
+                        "falling back to taskkill /F", pid, _GRACEFUL_STOP_TIMEOUT_SECS)
+    pid_file.unlink(missing_ok=True)
+    subprocess.run(["taskkill", "/IM", "meshbay-node.exe", "/F"],
+                   capture_output=True)
 
 
 # ── Service mode (Windows, opt-in at install time) ───────────────────────────
@@ -340,9 +418,17 @@ def service_install(exe: str | None = None) -> None:
     Register the boot-time Scheduled Task. Needs admin — raises RuntimeError
     with schtasks' own message on failure, which is "Access is denied." when
     not elevated.
+
+    Removes the per-user Startup launcher first, if present: the two
+    mechanisms are mutually exclusive by design (both installed would start
+    the daemon twice, once at boot and again at sign-in), and this is a
+    separate front door from the Node page's own startup-mode selector (which
+    enforces the same thing on its side) -- the CLI (`meshbay-node service
+    install`) must not be able to leave that invariant broken.
     """
     if not service_supported():
         raise RuntimeError("service mode is Windows-only")
+    autostart_remove()
     exe = exe or _node_exe()
     if not exe:
         raise RuntimeError(
@@ -374,3 +460,70 @@ def service_end() -> None:
     """Stop the running instance, if any. No admin needed."""
     if service_supported():
         _schtasks("/end", "/tn", TASK_NAME)
+
+
+# ── Console close / logoff / shutdown handler (Windows) ──────────────────────
+#
+# CPython's own console handler claims CTRL_C_EVENT and CTRL_BREAK_EVENT --
+# delivered as SIGINT/SIGBREAK, handled in daemon.py's win32 signal block --
+# but returns "not handled" for CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT and
+# CTRL_SHUTDOWN_EVENT: there is no Python signal for any of the three. Without
+# a handler of our own, Windows just ends the process for these -- no
+# _shutdown(), no closed WebRTC sessions, no killed ffmpeg. Covers: closing
+# the console window of an interactively-run `meshbay-node run`, user logoff,
+# system shutdown. Does NOT cover `taskkill /F` -- TerminateProcess is
+# uncatchable on any OS, the same as SIGKILL; see autostart_end() for how the
+# Node page's Stop button avoids relying on it instead.
+
+_CONSOLE_HANDLER_REFS: list = []  # ctypes callbacks must be kept referenced or they may be freed
+
+CTRL_CLOSE_EVENT = 2
+CTRL_LOGOFF_EVENT = 5
+CTRL_SHUTDOWN_EVENT = 6
+
+
+def install_console_close_handler(
+    loop: asyncio.AbstractEventLoop, stop_event: asyncio.Event,
+) -> "threading.Event | None":
+    """
+    Register the handler. Returns a threading.Event the caller must set once
+    its own graceful shutdown has actually finished -- daemon.py does this
+    right after `await self._shutdown()` -- or None off-Windows, or if
+    registration itself failed (logged, not raised: losing this is a
+    regression, refusing to start the daemon over it would not be).
+
+    MSDN: for these three events the process is ended "after the process
+    returns from the handler function, or after 5 seconds, whichever occurs
+    first" -- so the handler, which Windows runs on a thread of its own and
+    never the main one, blocks here instead of returning immediately, and
+    nudges the asyncio loop the thread-safe way since it is not the loop's
+    own thread. The wait is capped just under that ceiling so the process
+    still exits by itself if cleanup runs long, rather than the OS treating an
+    unresponsive handler as a hang.
+    """
+    if sys.platform != "win32":
+        return None
+    import ctypes
+    from ctypes import wintypes
+
+    handled = {CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, CTRL_SHUTDOWN_EVENT}
+    shutdown_done = threading.Event()
+    handler_type = ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.DWORD)
+
+    def _handler(ctrl_type: int) -> bool:
+        if ctrl_type not in handled:
+            return False  # not ours -- let Python's own handler or the default action take it
+        log.info("Console control event %d (close/logoff/shutdown) -- shutting down", ctrl_type)
+        loop.call_soon_threadsafe(stop_event.set)
+        shutdown_done.wait(4.5)
+        return True
+
+    handler_ref = handler_type(_handler)
+    if not ctypes.windll.kernel32.SetConsoleCtrlHandler(handler_ref, True):
+        log.warning("SetConsoleCtrlHandler failed (%s) -- closing the console window, "
+                    "logging off or shutting down will not run a clean shutdown; "
+                    "SIGINT/SIGTERM/SIGBREAK are unaffected",
+                    ctypes.WinError())
+        return None
+    _CONSOLE_HANDLER_REFS.append(handler_ref)
+    return shutdown_done
diff --git a/packages/meshbay-node/tests/test_packaging_win.py b/packages/meshbay-node/tests/test_packaging_win.py
index 21aaf29..0cf6367 100644
--- a/packages/meshbay-node/tests/test_packaging_win.py
+++ b/packages/meshbay-node/tests/test_packaging_win.py
@@ -71,6 +71,25 @@ def test_the_node_runtime_is_carried_as_an_extraresource():
         "extraResources puts it")
 
 
+def test_find_node_binary_strips_stray_cr_from_multiline_where_output():
+    """
+    where.exe/which can list more than one match on PATH, and each line
+    keeps its own trailing \\r on Windows. `stdout.trim().split('\\n')[0]`
+    only strips the ends of the *whole* string, so with 2+ matches a stray
+    \\r stayed glued to the end of the first line -- which then landed
+    inside the quoted path written into the Startup .vbs and broke
+    VBScript's parser with "Unterminated string constant" the next time
+    Windows ran it at sign-in. Reproduced live 2026-09-05 (this user's own
+    machine has both a dev venv and an installed build on PATH) and fixed
+    by splitting on \\r?\\n and trimming each candidate line individually.
+    """
+    main_js = (CLIENT / "src" / "main.js").read_text(encoding="utf-8")
+    assert "stdout.split(/\\r?\\n/)" in main_js, (
+        "findNodeBinary must split where.exe/which output on \\r?\\n and "
+        "trim each line, not a single stdout.trim() over the whole blob")
+    assert "stdout.trim().split('\\n')[0]" not in main_js
+
+
 def test_firewall_helper_is_carried_as_an_extraresource():
     """packaging/win/firewall.ps1 must ride into resources/, at the fixed
     path installer.nsh invokes it from ($INSTDIR\\resources\\firewall.ps1)."""
diff --git a/packages/meshbay-node/tests/test_platform.py b/packages/meshbay-node/tests/test_platform.py
index 7042afb..91713be 100644
--- a/packages/meshbay-node/tests/test_platform.py
+++ b/packages/meshbay-node/tests/test_platform.py
@@ -164,14 +164,26 @@ def test_autostart_install_refuses_off_windows(monkeypatch):
         plat.autostart_install(exe="/usr/bin/meshbay-node")
 
 
-def test_autostart_run_launches_the_resolved_exe_detached(win_startup, monkeypatch):
+def test_autostart_run_launches_the_resolved_exe_windowless_and_records_its_pid(
+        win_startup, monkeypatch, tmp_path):
     monkeypatch.setattr(plat, "_node_exe", lambda: r"C:\x\meshbay-node.exe")
+    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))     # state_dir() -> pidfile location
     calls = {}
-    monkeypatch.setattr(plat.subprocess, "Popen",
-                        lambda argv, **kw: calls.update(argv=argv, kw=kw))
+
+    def fake_popen(argv, **kw):
+        calls.update(argv=argv, kw=kw)
+        return Mock(pid=4242)
+
+    monkeypatch.setattr(plat.subprocess, "Popen", fake_popen)
     plat.autostart_run()
     assert calls["argv"] == [r"C:\x\meshbay-node.exe"]
-    assert calls["kw"]["creationflags"] & 0x08000000      # CREATE_NO_WINDOW
+    flags = calls["kw"]["creationflags"]
+    assert flags & 0x08000000      # CREATE_NO_WINDOW
+    assert flags & 0x00000200      # CREATE_NEW_PROCESS_GROUP
+    assert not flags & 0x00000008  # not DETACHED_PROCESS -- that has no
+                                   # console at all, so CTRL_BREAK_EVENT
+                                   # would have nothing to signal
+    assert plat._pid_file().read_text(encoding="utf-8") == "4242"
 
 
 def test_autostart_run_refuses_off_windows(monkeypatch):
@@ -180,6 +192,178 @@ def test_autostart_run_refuses_off_windows(monkeypatch):
         plat.autostart_run()
 
 
+# ── Graceful stop (CTRL_BREAK_EVENT + taskkill fallback) ────────────────────
+#
+# autostart_end() references signal.CTRL_BREAK_EVENT, which genuinely does not
+# exist in the `signal` module off Windows -- monkeypatching sys.platform
+# cannot manufacture it, unlike the pure-Python behaviour tested above. Skip
+# rather than mock around it, matching test_configure_event_loop_selector_opt_in.
+
+@pytest.mark.skipif(sys.platform != "win32",
+                    reason="signal.CTRL_BREAK_EVENT exists only on win32")
+def test_autostart_end_stops_gracefully_when_ctrl_break_is_enough(monkeypatch, tmp_path):
+    monkeypatch.setattr(sys, "platform", "win32")
+    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+    plat._pid_file().parent.mkdir(parents=True, exist_ok=True)
+    plat._pid_file().write_text("4242", encoding="utf-8")
+
+    kill_calls = []
+    monkeypatch.setattr(plat.os, "kill", lambda pid, sig: kill_calls.append((pid, sig)))
+    # Alive (our exe) on the pre-signal check, gone by the first poll after --
+    # a plain constant can't tell those two calls apart.
+    seen = {"n": 0}
+
+    def fake_check(pid):
+        seen["n"] += 1
+        return seen["n"] == 1
+
+    monkeypatch.setattr(plat, "_pid_is_meshbay_node", fake_check)
+    run_calls = []
+    monkeypatch.setattr(plat.subprocess, "run",
+                        lambda argv, **kw: run_calls.append(argv))
+
+    plat.autostart_end()
+
+    assert kill_calls == [(4242, plat.signal.CTRL_BREAK_EVENT)]
+    assert run_calls == []                       # no taskkill needed
+    assert not plat._pid_file().exists()
+
+
+@pytest.mark.skipif(sys.platform != "win32",
+                    reason="signal.CTRL_BREAK_EVENT exists only on win32")
+def test_autostart_end_falls_back_to_taskkill_when_the_pid_never_exits(
+        monkeypatch, tmp_path):
+    monkeypatch.setattr(sys, "platform", "win32")
+    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+    plat._pid_file().parent.mkdir(parents=True, exist_ok=True)
+    plat._pid_file().write_text("4242", encoding="utf-8")
+
+    monkeypatch.setattr(plat.os, "kill", lambda pid, sig: None)
+    monkeypatch.setattr(plat, "_pid_is_meshbay_node", lambda pid: True)  # never exits
+    monkeypatch.setattr(plat.time, "sleep", lambda s: None)       # don't really wait
+    clock = iter([0.0, 1.0, 6.0])       # deadline = 0.0 + 5.0; third read is past it
+    monkeypatch.setattr(plat.time, "monotonic", lambda: next(clock))
+    run_calls = []
+    monkeypatch.setattr(plat.subprocess, "run",
+                        lambda argv, **kw: run_calls.append(argv))
+
+    plat.autostart_end()
+
+    assert run_calls == [["taskkill", "/IM", "meshbay-node.exe", "/F"]]
+    assert not plat._pid_file().exists()
+
+
+def test_autostart_end_falls_back_to_taskkill_without_a_pidfile(monkeypatch, tmp_path):
+    """No CTRL_BREAK_EVENT dependency here -- there is no pid to signal, so
+    this one runs everywhere, same as the pre-existing behaviour it replaces."""
+    monkeypatch.setattr(sys, "platform", "win32")
+    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+    run_calls = []
+    monkeypatch.setattr(plat.subprocess, "run",
+                        lambda argv, **kw: run_calls.append(argv))
+    plat.autostart_end()
+    assert run_calls == [["taskkill", "/IM", "meshbay-node.exe", "/F"]]
+
+
+def test_autostart_end_ignores_a_stale_pid_reused_by_another_process(monkeypatch, tmp_path):
+    """The recorded pid is alive but is not meshbay-node.exe -- Windows reused
+    it after the daemon exited. Must not send CTRL_BREAK_EVENT to whatever
+    that is; falls straight to taskkill (by image name, so harmless here)."""
+    monkeypatch.setattr(sys, "platform", "win32")
+    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+    plat._pid_file().parent.mkdir(parents=True, exist_ok=True)
+    plat._pid_file().write_text("4242", encoding="utf-8")
+
+    monkeypatch.setattr(plat, "_pid_is_meshbay_node", lambda pid: False)
+    kill_calls = []
+    monkeypatch.setattr(plat.os, "kill", lambda pid, sig: kill_calls.append((pid, sig)))
+    run_calls = []
+    monkeypatch.setattr(plat.subprocess, "run",
+                        lambda argv, **kw: run_calls.append(argv))
+
+    plat.autostart_end()
+
+    assert kill_calls == []                      # never signalled the reused pid
+    assert run_calls == [["taskkill", "/IM", "meshbay-node.exe", "/F"]]
+    assert not plat._pid_file().exists()
+
+
+def test_autostart_end_is_a_noop_off_windows(monkeypatch):
+    monkeypatch.setattr(sys, "platform", "linux")
+    run_calls = []
+    monkeypatch.setattr(plat.subprocess, "run",
+                        lambda argv, **kw: run_calls.append(argv))
+    plat.autostart_end()
+    assert run_calls == []
+
+
+# ── Console close / logoff / shutdown handler ───────────────────────────────
+
+def test_install_console_close_handler_is_a_noop_off_windows(monkeypatch):
+    monkeypatch.setattr(sys, "platform", "linux")
+    loop = Mock()
+    stop_event = Mock()
+    assert plat.install_console_close_handler(loop, stop_event) is None
+
+
+@pytest.mark.skipif(sys.platform != "win32",
+                    reason="ctypes.windll/wintypes exist only on win32")
+def test_install_console_close_handler_registers_and_the_callback_sets_stop_event():
+    import asyncio as _asyncio
+
+    loop = _asyncio.new_event_loop()
+    try:
+        stop_event = _asyncio.Event()
+        shutdown_done = plat.install_console_close_handler(loop, stop_event)
+        assert shutdown_done is not None
+        # Drive the registered handler directly rather than actually closing a
+        # console window -- exercises the same code path SetConsoleCtrlHandler
+        # would invoke, without needing a live console to close.
+        handler = plat._CONSOLE_HANDLER_REFS[-1]
+        shutdown_done.set()   # so the handler's bounded wait returns immediately
+        # ctypes marshals the WINFUNCTYPE's BOOL restype back as a plain int
+        # (1/0), not a Python bool, when called directly like this.
+        assert handler(plat.CTRL_CLOSE_EVENT)
+        loop.run_until_complete(_asyncio.sleep(0))   # let call_soon_threadsafe land
+        assert stop_event.is_set()
+        # An event this handler does not own (CTRL_C_EVENT) is left unhandled
+        # so Python's own console handler (or the default action) gets it.
+        assert not handler(0)
+    finally:
+        loop.close()
+
+
+# ── Service mode ─────────────────────────────────────────────────────────────
+
+def test_service_install_removes_the_startup_launcher_first(win_startup, monkeypatch):
+    """The two mechanisms are mutually exclusive by design -- both installed
+    would start the daemon twice, once at boot and again at sign-in. This is
+    the CLI's own front door to that invariant, separate from (but agreeing
+    with) the Node page's startup-mode selector."""
+    plat.autostart_install(exe=r"C:\x\meshbay-node.exe")
+    assert win_startup.exists()
+
+    monkeypatch.setattr(plat, "_current_user", lambda: "DOMAIN\\user")
+    calls = []
+    monkeypatch.setattr(
+        plat, "_schtasks",
+        lambda *args: calls.append(args) or Mock(returncode=0, stdout="", stderr=""))
+
+    plat.service_install(exe=r"C:\x\meshbay-node.exe")
+
+    assert not win_startup.exists()       # removed as part of service_install
+    assert calls and calls[0][0] == "/create"
+
+
+def test_service_install_tolerates_no_startup_launcher_present(win_startup, monkeypatch):
+    assert not win_startup.exists()
+    monkeypatch.setattr(plat, "_current_user", lambda: "DOMAIN\\user")
+    monkeypatch.setattr(plat, "_schtasks",
+                        lambda *args: Mock(returncode=0, stdout="", stderr=""))
+    plat.service_install(exe=r"C:\x\meshbay-node.exe")   # no error
+    assert not win_startup.exists()
+
+
 # ── Packaged defaults ────────────────────────────────────────────────────────
 
 def test_frozen_build_finds_default_env_beside_the_executable(monkeypatch, tmp_path):