relay-companion 0.1.69 → 0.1.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.69",
+  "version": "0.1.70",
   "description": "Relay companion for ordinary messages, with dormant coordination features available only by explicit opt-in.",
   "type": "module",
   "bin": {

package/src/auto-update.js

@@ -1,16 +1,27 @@
 // Companion self-update.
 //
-// The companion ships as an npm package (`relay-companion`) run by two launchd
-// agents (work.relay.companion = daemon, work.relay.companion.pill = overlay),
-// both pointing at ABSOLUTE paths inside the global install. Publishing a new
-// version to npm is the production deploy — but nothing pulled it onto users'
-// machines, so a click-routing fix (or any fix) only reached people who manually
-// re-ran `npm i -g relay-companion@latest`.
+// The companion ships as an npm package (`relay-companion`) run by two always-on
+// services — on macOS two launchd agents (work.relay.companion = daemon,
+// work.relay.companion.pill = overlay), on Windows two Scheduled Tasks ("Relay
+// Companion Daemon" / "Relay Companion Pill") — all pointing at ABSOLUTE paths
+// inside the npm-managed install. Publishing a new version to npm is the
+// production deploy — but nothing pulled it onto users' machines, so a
+// click-routing fix (or any fix) only reached people who manually re-ran
+// `npm i -g relay-companion@latest`.
 //
 // This closes that loop: the daemon (the single always-on owner, kept alive by
-// launchd KeepAlive) checks npm's latest dist-tag, installs that exact version into
-// the prefix which owns the running package, verifies/repairs the desktop surfaces,
-// and reloads both launchd services from their refreshed plists.
+// launchd KeepAlive / Task Scheduler) checks npm's latest dist-tag, installs that
+// exact version into the prefix which owns the running package, verifies the
+// freshly written tree, and restarts both services (pill first, daemon last).
+//
+// macOS restart hand-off: the detached updater shell DESCENDS from the daemon's
+// launchd job. Booting out an ancestor job orphans the shell's Mach bootstrap
+// session, after which every `launchctl bootstrap` fails with EIO ("Bootstrap
+// failed: 5: Input/output error"), stranding BOTH services unloaded (observed in
+// the field on 0.1.68). The restart phase is therefore submitted to launchd as an
+// independent one-shot job (`launchctl submit`) that does not descend from the
+// daemon, verifies both services are listed afterwards, retries once, and rolls
+// back to the backed-up tree when verification fails.
 
 import os from "node:os";
 import path from "node:path";
@@ -26,6 +37,9 @@ import {
 export const PACKAGE_NAME = "relay-companion";
 const DAEMON_LABEL = "work.relay.companion";
 const PILL_LABEL = "work.relay.companion.pill";
+// Must match the Scheduled Task names registered by src/install.js.
+const WINDOWS_DAEMON_TASK_NAME = "Relay Companion Daemon";
+const WINDOWS_PILL_TASK_NAME = "Relay Companion Pill";
 const DEFAULT_REGISTRY = "https://registry.npmjs.org";
 // A production publish should reach an idle machine promptly. The registry request is
 // a tiny dist-tags document and the daemon is the only checker, so one minute gives us
@@ -75,10 +89,41 @@ export function isManagedInstall(packageRoot) {
 }
 
 // Resolve the npm prefix which OWNS this exact package tree. Global npm installs live
-// at <prefix>/lib/node_modules; Relay's no-sudo fallback lives at
-// <prefix>/node_modules. Passing the explicit prefix to npm prevents an nvm/fnm/volta
-// daemon from accidentally updating Homebrew's copy (or the reverse).
-export function managedInstallInfo(packageRoot, { home = os.homedir() } = {}) {
+// at <prefix>/lib/node_modules (macOS/Linux) or <prefix>\node_modules (Windows);
+// Relay's no-sudo fallback lives at <home>/.relay/lib/node_modules. Passing the
+// explicit prefix to npm prevents an nvm/fnm/volta daemon from accidentally updating
+// Homebrew's copy (or the reverse).
+export function managedInstallInfo(
+  packageRoot,
+  { home = os.homedir(), platform = process.platform, exists = fs.existsSync } = {},
+) {
+  if (platform === "win32") {
+    // Decide with path.win32 so the same logic is exact both on a real Windows
+    // daemon and when unit tests exercise it from POSIX. Windows paths are
+    // case-insensitive; compare accordingly.
+    const win = path.win32;
+    const root = win.resolve(String(packageRoot || ""));
+    const nmSuffix = win.sep + win.join("node_modules", PACKAGE_NAME);
+    if (!root.toLowerCase().endsWith(nmSuffix.toLowerCase())) return null;
+    const prefix = root.slice(0, root.length - nmSuffix.length) || win.parse(root).root;
+    const relayLocalSuffix = win.sep + win.join(".relay", "lib");
+    if (prefix.toLowerCase().endsWith(relayLocalSuffix.toLowerCase())) {
+      return { packageRoot: root, prefix, global: false };
+    }
+    // A Windows global prefix has the same <dir>\node_modules\<pkg> shape as an
+    // arbitrary project checkout, which is NOT a safe rollback unit (the project
+    // hoists Relay's dependencies beside it). Only adopt a prefix that carries
+    // npm's global bin shims: `npm i -g relay-companion` always writes
+    // <prefix>\relay.cmd, and custom prefixes that own npm itself carry npm.cmd /
+    // node_modules\npm. The darwin branch refuses arbitrary node_modules for the
+    // same reason.
+    for (const marker of ["relay.cmd", "npm.cmd", win.join("node_modules", "npm")]) {
+      try {
+        if (exists(win.join(prefix, marker))) return { packageRoot: root, prefix, global: true };
+      } catch {}
+    }
+    return null;
+  }
   const root = path.resolve(String(packageRoot || ""));
   const globalSuffix = path.join("lib", "node_modules", PACKAGE_NAME);
   const localSuffix = path.join("node_modules", PACKAGE_NAME);
@@ -191,6 +236,207 @@ export function runtimeNpmDir(execPath = process.execPath) {
   return null;
 }
 
+// Build the Windows (win32) update script: a single PowerShell program with the same
+// guarantees as the darwin shell script — single-writer pid-aware lock, local backup
+// of the running tree, exact-version install + verification BEFORE any restart,
+// Scheduled Task restart (pill first, daemon last), and restore-on-any-failure.
+// It is spawned detached via `powershell.exe -EncodedCommand` (base64 UTF-16LE),
+// which sidesteps every powershell/cmd quoting layer for the multi-line script.
+export function buildWindowsUpdateScript({
+  home = os.homedir(),
+  currentVersion = null,
+  targetVersion = null,
+  packageRoot = companionPackageRoot(),
+  execPath = process.execPath,
+  logPath = path.win32.join(home, ".relay", "update.log"),
+  lockPath = path.win32.join(home, ".relay", "update.lock"),
+  exists = fs.existsSync,
+} = {}) {
+  const install = managedInstallInfo(packageRoot, { home, platform: "win32", exists });
+  if (!install) throw new Error(`cannot update unmanaged package root: ${packageRoot}`);
+  // Safe single-quote for PowerShell literals: inside '...' the only escape is ''.
+  const pq = (s) => `'${String(s).replaceAll("'", "''")}'`;
+  // Restore target if the new install is broken: reinstall the version we're running
+  // now so the on-disk tree stays loadable for the next Scheduled Task launch.
+  const restore = parseVersion(currentVersion) ? currentVersion : "latest";
+  const target = parseVersion(targetVersion) ? String(targetVersion) : null;
+  const installTarget = target || "latest";
+  const installFlags = install.global ? "-g " : "";
+  const win = path.win32;
+  // Prefer the npm.cmd that sits beside the runtime node.exe which owns the running
+  // install (nvm-windows/volta), mirroring darwin's runtime-PATH prepend. The install
+  // command separately pins the owning prefix, so an unusual npm config still cannot
+  // redirect the update to another copy.
+  const execDir = execPath ? win.dirname(String(execPath)) : "";
+  const execBase = execPath ? win.basename(String(execPath)).toLowerCase() : "";
+  let runtimeDir = null;
+  if (execDir && execDir !== "." && !execBase.includes("electron")) {
+    try {
+      if (exists(win.join(execDir, "npm.cmd")) || exists(win.join(execDir, "npm"))) runtimeDir = execDir;
+    } catch {}
+  }
+  const npmInstallLine =
+    `npm install ${installFlags}--prefix "${install.prefix}" "${PACKAGE_NAME}@${installTarget}"` +
+    " --prefer-online --no-audit --no-fund --no-save --package-lock=false" +
+    " --fetch-retries=3 --fetch-retry-mintimeout=1000 --fetch-retry-maxtimeout=10000";
+  const lines = [
+    `$ErrorActionPreference = 'Continue'`,
+    `$Log = ${pq(logPath)}`,
+    `$Lock = ${pq(lockPath)}`,
+    `$Prefix = ${pq(install.prefix)}`,
+    `$Pkg = ${pq(install.packageRoot)}`,
+    `$PkgParent = Split-Path -Parent $Pkg`,
+    // Global npm on Windows nests Relay's dependencies inside the package directory,
+    // making it a complete rollback unit. The no-sudo fallback hoists dependencies
+    // into the Relay-owned node_modules, so that whole directory is the unit there.
+    install.global ? `$LiveTree = $Pkg` : `$LiveTree = Join-Path $Prefix 'node_modules'`,
+    install.global
+      ? `$Backup = Join-Path $PkgParent '.relay-companion-update-backup'`
+      : `$Backup = Join-Path $Prefix '.relay-companion-node_modules-update-backup'`,
+    `$Node = ${pq(execPath || "node.exe")}`,
+    `$ComSpec = if ($env:ComSpec) { $env:ComSpec } else { Join-Path $env:SystemRoot 'System32\\cmd.exe' }`,
+    `$NodeCmd = if (Test-Path -LiteralPath $Node) { '"' + $Node + '"' } else { 'node' }`,
+    // Relay's own postinstall would repair/restart surfaces mid-update; this script
+    // owns the verify + restart sequencing itself (matches the darwin script).
+    `$env:RELAY_SKIP_DESKTOP_POSTINSTALL = '1'`,
+    ...(runtimeDir ? [`$env:Path = ${pq(`${runtimeDir};`)} + $env:Path`] : []),
+    `function Write-UpdateLog([string]$Message) {`,
+    `  try { Add-Content -LiteralPath $Log -Value ('[relay-update] ' + (Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' ' + $Message) } catch {}`,
+    `}`,
+    // cmd /d /s /c resolves npm.cmd/schtasks through PATH exactly like a console
+    // would, and appends all native output to the update log, mirroring the darwin
+    // script's ">> LOG 2>&1" on every native step. Windows PowerShell 5.1 passes the
+    // argument with inner quotes verbatim, which is precisely the /s /c contract.
+    `function Invoke-Native([string]$CommandLine) {`,
+    `  & $ComSpec /d /s /c ($CommandLine + ' >> "' + $Log + '" 2>&1')`,
+    `  return $LASTEXITCODE`,
+    `}`,
+    `function Restore-Tree {`,
+    `  if (Test-Path -LiteralPath $Backup) {`,
+    `    Remove-Item -LiteralPath $LiveTree -Recurse -Force -ErrorAction SilentlyContinue`,
+    `    Move-Item -LiteralPath $Backup -Destination $LiveTree -Force -ErrorAction SilentlyContinue`,
+    `    Write-UpdateLog 'restored previous package tree'`,
+    `  }`,
+    `}`,
+    `$null = New-Item -ItemType Directory -Force -Path (Split-Path -Parent $Lock) -ErrorAction SilentlyContinue`,
+    // Never steal from a live slow install. A recorded dead owner is recoverable
+    // immediately; an ownerless lock is stolen only when truly stale (>20 minutes).
+    `if (Test-Path -LiteralPath $Lock) {`,
+    `  $LockPidRaw = $null`,
+    `  try { $LockPidRaw = Get-Content -LiteralPath (Join-Path $Lock 'pid') -TotalCount 1 -ErrorAction Stop } catch {}`,
+    `  if ($null -ne $LockPidRaw -and ('' + $LockPidRaw).Trim() -ne '') {`,
+    `    $OwnerAlive = $false`,
+    `    try { $OwnerAlive = [bool](Get-Process -Id ([int](('' + $LockPidRaw).Trim())) -ErrorAction Stop) } catch { $OwnerAlive = $false }`,
+    `    if (-not $OwnerAlive) { Remove-Item -LiteralPath $Lock -Recurse -Force -ErrorAction SilentlyContinue }`,
+    `  } else {`,
+    `    $LockItem = $null`,
+    `    try { $LockItem = Get-Item -LiteralPath $Lock -ErrorAction Stop } catch {}`,
+    `    if ($LockItem -and ((Get-Date) - $LockItem.LastWriteTime).TotalMinutes -gt 20) { Remove-Item -LiteralPath $Lock -Recurse -Force -ErrorAction SilentlyContinue }`,
+    `  }`,
+    `}`,
+    // Single-writer: New-Item -ItemType Directory WITHOUT -Force is CreateDirectory —
+    // atomic, and fails when the directory already exists (= mkdir lock semantics).
+    `try { $null = New-Item -ItemType Directory -Path $Lock -ErrorAction Stop } catch { Write-UpdateLog 'another update in progress; skipping'; exit 0 }`,
+    `$KeepNew = $false`,
+    // PowerShell runs `finally` on normal completion, thrown errors, and `exit`,
+    // covering the same paths as the darwin EXIT/INT/TERM trap.
+    `try {`,
+    `  try { Set-Content -LiteralPath (Join-Path $Lock 'pid') -Value ([string]$PID) -ErrorAction Stop } catch {}`,
+    // Sweep trash a previous commit could not delete (a locked file keeps a renamed
+    // backup dir alive; see the commit step below).
+    `  try { Get-ChildItem -LiteralPath (Split-Path -Parent $Backup) -Force -Filter ((Split-Path -Leaf $Backup) + '.trash-*') -ErrorAction Stop | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue } catch {}`,
+    // A hard kill bypasses `finally` and can leave both the known-good backup and a
+    // partially written live tree. The backup always wins.
+    `  if (Test-Path -LiteralPath $Backup) {`,
+    `    Write-UpdateLog 'recovering interrupted prior update'`,
+    `    Remove-Item -LiteralPath $LiveTree -Recurse -Force -ErrorAction SilentlyContinue`,
+    `    Move-Item -LiteralPath $Backup -Destination $LiveTree -Force -ErrorAction SilentlyContinue`,
+    `    if (Test-Path -LiteralPath $Backup) { Write-UpdateLog 'could not restore interrupted backup; aborting safely'; exit 1 }`,
+    `  }`,
+    // Same-volume directory rename: atomic, and legal on Windows even while files
+    // inside are open/executing (delete is what NTFS blocks, not rename).
+    `  Move-Item -LiteralPath $LiveTree -Destination $Backup -Force -ErrorAction SilentlyContinue`,
+    `  if ((Test-Path -LiteralPath $LiveTree) -or -not (Test-Path -LiteralPath $Backup)) { Write-UpdateLog ('could not back up ' + $LiveTree + '; aborting safely'); exit 1 }`,
+    `  Write-UpdateLog ('installing ${PACKAGE_NAME}@${installTarget} into ' + $Pkg + ' (current ${restore})')`,
+    `  $InstallExit = Invoke-Native ${pq(npmInstallLine)}`,
+    `  if ($InstallExit -ne 0) { Write-UpdateLog 'install FAILED; restoring ${restore} from local backup'; exit 1 }`,
+    // Electron lives nested under the package (global layout) or hoisted beside it
+    // (Relay's local-prefix layout). Repair a skipped binary download before verify.
+    `  $ElectronDir = $null`,
+    `  foreach ($Candidate in @((Join-Path $Pkg 'node_modules\\electron'), (Join-Path $PkgParent 'electron'))) {`,
+    `    if (Test-Path -LiteralPath (Join-Path $Candidate 'package.json')) { $ElectronDir = $Candidate; break }`,
+    `  }`,
+    `  $Electron = $null`,
+    `  if ($ElectronDir) { $Electron = Join-Path $ElectronDir 'dist\\electron.exe' }`,
+    `  if ($ElectronDir -and -not (Test-Path -LiteralPath $Electron) -and (Test-Path -LiteralPath (Join-Path $ElectronDir 'install.js'))) {`,
+    `    Write-UpdateLog 'electron runtime missing; running electron install.js'`,
+    `    $null = Invoke-Native ($NodeCmd + ' "' + (Join-Path $ElectronDir 'install.js') + '"')`,
+    `  }`,
+    // Verify the package at the exact Task-Scheduler-owned root reached the exact
+    // discovered version. A mismatched prefix or stale npm response must never
+    // trigger a restart.
+    `  $InstalledVersion = $null`,
+    `  try { $InstalledVersion = (Get-Content -LiteralPath (Join-Path $Pkg 'package.json') -Raw -ErrorAction Stop | ConvertFrom-Json).version } catch {}`,
+    `  Write-UpdateLog ('installed version=' + $InstalledVersion + ' at ' + $Pkg)`,
+    target
+      ? `  $VersionOk = $false; if ($InstalledVersion -ceq '${target}') { $VersionOk = $true } else { Write-UpdateLog ('verify FAILED: installed ' + $InstalledVersion + ' != exact target ${target}') }`
+      : `  $VersionOk = $true`,
+    `  $VerifyOk = $false`,
+    `  if ($VersionOk -and $Electron -and (Test-Path -LiteralPath $Electron) -and (Test-Path -LiteralPath (Join-Path $Pkg 'bin\\relay.js'))) { $VerifyOk = $true }`,
+    `  if (-not $VerifyOk) { Write-UpdateLog 'post-install verify FAILED; restoring ${restore} from local backup'; exit 1 }`,
+    // Unlike macOS there is no repair-desktop step: the Scheduled Task actions embed
+    // only update-stable absolute paths (node.exe, bin\relay.js, electron.exe live at
+    // the same locations inside the refreshed tree), so re-registration is unneeded —
+    // and would /End + /Run tasks outside this script's careful sequencing.
+    `  Write-UpdateLog 'install verified; restarting services (pill first, daemon last)'`,
+    `  $null = Invoke-Native 'schtasks /End /TN "${WINDOWS_PILL_TASK_NAME}"'`,
+    `  $PillRun = Invoke-Native 'schtasks /Run /TN "${WINDOWS_PILL_TASK_NAME}"'`,
+    `  if ($PillRun -ne 0) {`,
+    `    Write-UpdateLog 'pill restart FAILED; restoring previous tree'`,
+    // End the (possibly half-started) new pill BEFORE restoring: Windows cannot
+    // delete a tree whose executables are running.
+    `    $null = Invoke-Native 'schtasks /End /TN "${WINDOWS_PILL_TASK_NAME}"'`,
+    `    Restore-Tree`,
+    `    $null = Invoke-Native 'schtasks /Run /TN "${WINDOWS_PILL_TASK_NAME}"'`,
+    `    exit 1`,
+    `  }`,
+    // /End on the daemon task may terminate THIS script too (Task Scheduler ends the
+    // action's process tree; node's detached spawn does not breakaway from it). The
+    // watcher below is created via CIM, so it is parented to the WMI provider — OUT of
+    // that tree — and re-runs the daemon task even if this script dies between the
+    // /End and the /Run. When this script survives, the extra /Run is a harmless
+    // "already running" no-op appended to the log.
+    `  try {`,
+    `    $WatchCmd = 'ping -n 16 127.0.0.1 >nul & schtasks /Run /TN "${WINDOWS_DAEMON_TASK_NAME}" >> "' + $Log + '" 2>&1'`,
+    `    $Startup = New-CimInstance -ClassName Win32_ProcessStartup -ClientOnly -Property @{ ShowWindow = [uint16]0 } -ErrorAction Stop`,
+    `    $null = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = ('"' + $ComSpec + '" /d /s /c "' + $WatchCmd + '"'); ProcessStartupInformation = $Startup } -ErrorAction Stop`,
+    `  } catch { Write-UpdateLog 'daemon revival watcher unavailable; relying on direct schtasks restart' }`,
+    `  $null = Invoke-Native 'schtasks /End /TN "${WINDOWS_DAEMON_TASK_NAME}"'`,
+    `  $DaemonRun = Invoke-Native 'schtasks /Run /TN "${WINDOWS_DAEMON_TASK_NAME}"'`,
+    `  if ($DaemonRun -ne 0) {`,
+    `    Write-UpdateLog 'daemon restart FAILED; restoring previous tree'`,
+    `    $null = Invoke-Native 'schtasks /End /TN "${WINDOWS_PILL_TASK_NAME}"'`,
+    `    Restore-Tree`,
+    `    $null = Invoke-Native 'schtasks /Run /TN "${WINDOWS_PILL_TASK_NAME}"'`,
+    `    $null = Invoke-Native 'schtasks /Run /TN "${WINDOWS_DAEMON_TASK_NAME}"'`,
+    `    exit 1`,
+    `  }`,
+    `  $KeepNew = $true`,
+    // Rename-then-delete: if a leftover locked file blocks deletion, the rename has
+    // already moved the dir OUT of the backup name, so a later "recovering
+    // interrupted prior update" can never restore a stale tree over a good one.
+    `  $BackupTrash = $Backup + '.trash-' + $PID`,
+    `  try { Move-Item -LiteralPath $Backup -Destination $BackupTrash -Force -ErrorAction Stop } catch { $BackupTrash = $Backup }`,
+    `  Remove-Item -LiteralPath $BackupTrash -Recurse -Force -ErrorAction SilentlyContinue`,
+    `  Write-UpdateLog 'update committed; pill and daemon restarted from the new tree'`,
+    `} finally {`,
+    `  if (-not $KeepNew) { Restore-Tree }`,
+    `  Remove-Item -LiteralPath $Lock -Recurse -Force -ErrorAction SilentlyContinue`,
+    `}`,
+  ];
+  return lines.join("\n");
+}
+
 export function spawnDetachedUpdate({
   home = os.homedir(),
   uid = typeof process.getuid === "function" ? process.getuid() : 0,
@@ -199,18 +445,52 @@ export function spawnDetachedUpdate({
   packageRoot = companionPackageRoot(),
   execPath = process.execPath,
   launchctlPath = "/bin/launchctl",
+  platform = process.platform,
   logPath = path.join(home, ".relay", "update.log"),
   lockPath = path.join(home, ".relay", "update.lock"),
   spawnImpl = spawn,
   log = () => {},
   ensureDir = true,
   mode = DEFAULT_COMPANION_MODE,
+  exists = fs.existsSync,
 } = {}) {
   if (ensureDir) {
     try {
       fs.mkdirSync(path.dirname(logPath), { recursive: true });
     } catch {}
   }
+  // A detached child with NO 'error' listener turns an async spawn failure (EMFILE,
+  // EAGAIN, ENOENT on the shell binary) into an unhandled 'error' that would crash
+  // this always-on daemon. Attach the listener BEFORE unref, then release the child
+  // so it survives this process being killed by the restart it performs.
+  const attachAndRelease = (child) => {
+    if (child && typeof child.on === "function") {
+      child.on("error", (err) => log(`auto-update spawn error: ${err && err.message ? err.message : String(err)}`));
+    }
+    if (child && typeof child.unref === "function") child.unref();
+    return child;
+  };
+  if (platform === "win32") {
+    const script = buildWindowsUpdateScript({
+      home,
+      currentVersion,
+      targetVersion,
+      packageRoot,
+      execPath,
+      logPath,
+      lockPath,
+      exists,
+    });
+    const encoded = Buffer.from(script, "utf16le").toString("base64");
+    const systemRoot = process.env.SystemRoot || process.env.windir || "C:\\Windows";
+    const powershellPath = path.win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    const child = spawnImpl(
+      powershellPath,
+      ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encoded],
+      { detached: true, stdio: "ignore", windowsHide: true },
+    );
+    return attachAndRelease(child);
+  }
   const q = (s) => `'${String(s).replaceAll("'", "'\\''")}'`; // safe single-quote for the shell
   const LOG = q(logPath);
   const LOCK = q(lockPath);
@@ -230,8 +510,66 @@ export function spawnDetachedUpdate({
   const installTarget = target || "latest";
   const installFlags = install.global ? "-g " : "";
   const launchAgentsDir = path.join(home, "Library", "LaunchAgents");
+  const pillPlistPath = path.join(launchAgentsDir, `${PILL_LABEL}.plist`);
+  const daemonPlistPath = path.join(launchAgentsDir, `${DAEMON_LABEL}.plist`);
+  const liveTreePath = install.global ? install.packageRoot : path.join(install.prefix, "node_modules");
+  const backupPath = install.global
+    ? path.join(path.dirname(install.packageRoot), ".relay-companion-update-backup")
+    : path.join(install.prefix, ".relay-companion-node_modules-update-backup");
   const npmInstall = (version) =>
     `RELAY_SKIP_DESKTOP_POSTINSTALL=1 npm install ${installFlags}--prefix "$PREFIX" ${q(`${PACKAGE_NAME}@${version}`)} --prefer-online --no-audit --no-fund --no-save --package-lock=false --fetch-retries=3 --fetch-retry-mintimeout=1000 --fetch-retry-maxtimeout=10000`;
+  // The restart phase, written to $LOCK/restart.sh and SUBMITTED to launchd as an
+  // independent one-shot job. It must not run from this detached shell: the shell
+  // descends from the daemon's launchd job, and booting out an ancestor job orphans
+  // the shell's Mach bootstrap session — every subsequent `launchctl bootstrap`
+  // (and `load`) then fails with EIO, leaving BOTH services unloaded until a human
+  // intervenes (observed in the field on the 0.1.68 rollout). A submitted job is
+  // parented to the gui domain itself, so it can bootout/bootstrap anything.
+  // After a successful submit the main script sets HANDOFF=1: lock, backup, and
+  // commit/rollback responsibility all transfer to this job.
+  const restartScript = [
+    `# Relay update restart phase — runs as its own launchd job (see updater log).`,
+    `RESTART_LABEL="$1"`,
+    `LOCK=${LOCK}`,
+    `printf '%s\n' "$$" > "$LOCK/pid" 2>/dev/null || true`,
+    `LIVE_TREE=${q(liveTreePath)}`,
+    `BACKUP=${q(backupPath)}`,
+    `LAUNCHCTL=${q(launchctlPath)}`,
+    `PILL_PLIST=${q(pillPlistPath)}`,
+    `DAEMON_PLIST=${q(daemonPlistPath)}`,
+    `log_line() { echo "[relay-update] $(date) $1" >> ${LOG} 2>&1; }`,
+    `restore_tree() { if [ -d "$BACKUP" ]; then rm -rf "$LIVE_TREE"; mv "$BACKUP" "$LIVE_TREE"; log_line "restored previous package tree"; fi; }`,
+    `start_job() { "$LAUNCHCTL" bootstrap gui/${uid} "$1" >> ${LOG} 2>&1 || "$LAUNCHCTL" load "$1" >> ${LOG} 2>&1 || "$LAUNCHCTL" kickstart -k "gui/${uid}/$2" >> ${LOG} 2>&1; }`,
+    // Verification with one retry: a service missing from launchd after the restart
+    // is bootstrapped again, loudly. Only a job listed by `launchctl print` counts.
+    `ensure_job() { if "$LAUNCHCTL" print "gui/${uid}/$2" >/dev/null 2>&1; then return 0; fi; log_line "$2 missing after restart; bootstrapping again"; start_job "$1" "$2"; "$LAUNCHCTL" print "gui/${uid}/$2" >/dev/null 2>&1; }`,
+    `RESTART_FAILED=0`,
+    // Pill first, daemon last (unchanged ordering contract).
+    `"$LAUNCHCTL" bootout gui/${uid}/${PILL_LABEL} >> ${LOG} 2>&1 || true`,
+    `start_job "$PILL_PLIST" ${PILL_LABEL} || true`,
+    `"$LAUNCHCTL" bootout gui/${uid}/${DAEMON_LABEL} >> ${LOG} 2>&1 || true`,
+    `start_job "$DAEMON_PLIST" ${DAEMON_LABEL} || true`,
+    `ensure_job "$PILL_PLIST" ${PILL_LABEL} || { log_line "pill restart verification FAILED"; RESTART_FAILED=1; }`,
+    `ensure_job "$DAEMON_PLIST" ${DAEMON_LABEL} || { log_line "daemon restart verification FAILED"; RESTART_FAILED=1; }`,
+    `if [ "$RESTART_FAILED" = 1 ]; then`,
+    `  log_line "restart verification FAILED; restoring previous tree"`,
+    `  restore_tree`,
+    `  "$LAUNCHCTL" bootout gui/${uid}/${PILL_LABEL} >> ${LOG} 2>&1 || true`,
+    `  "$LAUNCHCTL" bootout gui/${uid}/${DAEMON_LABEL} >> ${LOG} 2>&1 || true`,
+    `  start_job "$PILL_PLIST" ${PILL_LABEL} || true`,
+    `  start_job "$DAEMON_PLIST" ${DAEMON_LABEL} || true`,
+    `  ensure_job "$PILL_PLIST" ${PILL_LABEL} || log_line "pill STILL missing after rollback; run 'relay setup' to repair"`,
+    `  ensure_job "$DAEMON_PLIST" ${DAEMON_LABEL} || log_line "daemon STILL missing after rollback; run 'relay setup' to repair"`,
+    `else`,
+    `  rm -rf "$BACKUP" 2>/dev/null`,
+    `  log_line "update committed; pill and daemon restarted from the new tree"`,
+    `fi`,
+    `rm -rf "$LOCK" 2>/dev/null`,
+    // One-shot label cleanup: the submitted job removes itself from launchd. This is
+    // deliberately the last line — remove may terminate the job's own process.
+    `"$LAUNCHCTL" remove "$RESTART_LABEL" >/dev/null 2>&1 || true`,
+    `exit 0`,
+  ].join("\n");
   const script = [
     `export PATH=${pathPrefix}"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:$PATH"`,
     `PREFIX=${q(install.prefix)}`,
@@ -245,8 +583,8 @@ export function spawnDetachedUpdate({
       : `LIVE_TREE="$PREFIX/node_modules"; BACKUP="$PREFIX/.relay-companion-node_modules-update-backup"`,
     `NODE=${q(execPath)}`,
     `LAUNCHCTL=${q(launchctlPath)}`,
-    `PILL_PLIST=${q(path.join(launchAgentsDir, `${PILL_LABEL}.plist`))}`,
-    `DAEMON_PLIST=${q(path.join(launchAgentsDir, `${DAEMON_LABEL}.plist`))}`,
+    `PILL_PLIST=${q(pillPlistPath)}`,
+    `DAEMON_PLIST=${q(daemonPlistPath)}`,
     `if [ ! -x "$NODE" ]; then NODE="$(command -v node 2>/dev/null)"; fi`,
     // Hold the lock path in a shell var and reference "$LOCK" everywhere so every use
     // (including the single-quoted trap action) stays correct even if the home path
@@ -264,8 +602,11 @@ export function spawnDetachedUpdate({
     // restore the known-running tree without relying on npm or the network. The EXIT
     // trap also covers shell termination between moving the old tree and verification.
     `KEEP_NEW=0`,
+    // After a successful hand-off to the independent restart job, the lock (and the
+    // restart.sh inside it) belong to THAT job — the exit trap must not remove them.
+    `HANDOFF=0`,
     `restore_tree() { if [ -d "$BACKUP" ]; then rm -rf "$LIVE_TREE"; mv "$BACKUP" "$LIVE_TREE"; echo "[relay-update] $(date) restored previous package tree" >> ${LOG} 2>&1; fi; KEEP_NEW=1; }`,
-    `cleanup_update() { CODE=$?; trap - EXIT INT TERM; if [ "$KEEP_NEW" != 1 ]; then restore_tree; fi; rm -rf "$LOCK" 2>/dev/null; exit "$CODE"; }`,
+    `cleanup_update() { CODE=$?; trap - EXIT INT TERM; if [ "$KEEP_NEW" != 1 ]; then restore_tree; fi; if [ "$HANDOFF" != 1 ]; then rm -rf "$LOCK" 2>/dev/null; fi; exit "$CODE"; }`,
     `trap cleanup_update EXIT INT TERM`,
     // A SIGKILL bypasses EXIT cleanup and can leave both the known-good backup and a
     // partially written live tree. The backup always wins; never delete our only
@@ -296,16 +637,31 @@ export function spawnDetachedUpdate({
     `    if "$NODE" "$PKG/bin/relay.js" repair-desktop --no-restart${repairModeArgs ? ` ${repairModeArgs}` : ""} >> ${LOG} 2>&1; then DESKTOP_OK=1; else echo "[relay-update] $(date) desktop repair FAILED" >> ${LOG} 2>&1; fi`,
     `  fi`,
     `  if [ "$DESKTOP_OK" = 1 ]; then`,
-    `    echo "[relay-update] $(date) install and desktop repair verified; restarting services" >> ${LOG} 2>&1`,
-    // A kickstart does NOT reload changed ProgramArguments from disk. Bootout +
-    // bootstrap makes version-manager/prefix repairs take effect and also revives a
-    // job a user/agent previously unloaded. The detached shell survives booting out
-    // its daemon parent. Pill first; daemon last.
+    `    echo "[relay-update] $(date) install and desktop repair verified; handing restart to an independent launchd job" >> ${LOG} 2>&1`,
+    // A kickstart does NOT reload changed ProgramArguments from disk, so the restart
+    // must bootout + bootstrap. But this shell DESCENDS from the daemon's launchd
+    // job: booting out that ancestor orphans this shell's Mach bootstrap session,
+    // after which bootstrap/load fail with EIO and both services are stranded
+    // unloaded (field-observed on 0.1.68). Hand the whole restart phase to a
+    // launchd-submitted one-shot job instead; start_job stays defined here only for
+    // the degraded inline fallback when submit itself is unavailable.
     `    start_job() { "$LAUNCHCTL" bootstrap gui/${uid} "$1" >> ${LOG} 2>&1 || "$LAUNCHCTL" load "$1" >> ${LOG} 2>&1 || "$LAUNCHCTL" kickstart -k "gui/${uid}/$2" >> ${LOG} 2>&1; }`,
-    `    "$LAUNCHCTL" bootout gui/${uid}/${PILL_LABEL} >> ${LOG} 2>&1 || true`,
-    `    if ! start_job "$PILL_PLIST" ${PILL_LABEL}; then echo "[relay-update] $(date) pill restart FAILED; restoring previous tree" >> ${LOG} 2>&1; restore_tree; start_job "$PILL_PLIST" ${PILL_LABEL} || true; exit 1; fi`,
-    `    "$LAUNCHCTL" bootout gui/${uid}/${DAEMON_LABEL} >> ${LOG} 2>&1 || true`,
-    `    if start_job "$DAEMON_PLIST" ${DAEMON_LABEL}; then KEEP_NEW=1; rm -rf "$BACKUP" 2>/dev/null; else echo "[relay-update] $(date) daemon restart FAILED; restoring previous tree" >> ${LOG} 2>&1; restore_tree; "$LAUNCHCTL" bootout gui/${uid}/${PILL_LABEL} >> ${LOG} 2>&1 || true; start_job "$PILL_PLIST" ${PILL_LABEL} || true; start_job "$DAEMON_PLIST" ${DAEMON_LABEL} || true; exit 1; fi`,
+    `    cat > "$LOCK/restart.sh" <<'RELAY_RESTART_EOF'`,
+    restartScript,
+    `RELAY_RESTART_EOF`,
+    `    RESTART_LABEL="work.relay.update.restart.$(date +%s).$$"`,
+    `    if "$LAUNCHCTL" submit -l "$RESTART_LABEL" -- /bin/sh "$LOCK/restart.sh" "$RESTART_LABEL" >> ${LOG} 2>&1; then`,
+    `      KEEP_NEW=1; HANDOFF=1`,
+    `      echo "[relay-update] $(date) restart phase submitted as $RESTART_LABEL (lock, backup, and rollback now owned by that job)" >> ${LOG} 2>&1`,
+    `    else`,
+    `      echo "[relay-update] $(date) launchctl submit FAILED; degraded inline restart (pill reload; daemon kickstart without plist reload)" >> ${LOG} 2>&1`,
+    `      "$LAUNCHCTL" bootout gui/${uid}/${PILL_LABEL} >> ${LOG} 2>&1 || true`,
+    `      if ! start_job "$PILL_PLIST" ${PILL_LABEL}; then echo "[relay-update] $(date) pill restart FAILED; restoring previous tree" >> ${LOG} 2>&1; restore_tree; start_job "$PILL_PLIST" ${PILL_LABEL} || true; exit 1; fi`,
+    // Never bootout our own ancestor inline (the EIO trap above). kickstart -k
+    // restarts the daemon without removing its job; stale ProgramArguments, if any,
+    // are corrected by the next successful submit-based update.
+    `      if "$LAUNCHCTL" kickstart -k "gui/${uid}/${DAEMON_LABEL}" >> ${LOG} 2>&1; then KEEP_NEW=1; rm -rf "$BACKUP" 2>/dev/null; else echo "[relay-update] $(date) daemon kickstart FAILED; restoring previous tree" >> ${LOG} 2>&1; restore_tree; "$LAUNCHCTL" bootout gui/${uid}/${PILL_LABEL} >> ${LOG} 2>&1 || true; start_job "$PILL_PLIST" ${PILL_LABEL} || true; "$LAUNCHCTL" kickstart -k "gui/${uid}/${DAEMON_LABEL}" >> ${LOG} 2>&1 || true; exit 1; fi`,
+    `    fi`,
     `  else`,
     `    echo "[relay-update] $(date) post-install verify FAILED; restoring ${restore} from local backup" >> ${LOG} 2>&1`,
     `    exit 1`,
@@ -316,14 +672,7 @@ export function spawnDetachedUpdate({
     `fi`,
   ].join("\n");
   const child = spawnImpl("/bin/sh", ["-c", script], { detached: true, stdio: "ignore" });
-  // A detached child with NO 'error' listener turns an async spawn failure (EMFILE,
-  // EAGAIN, ENOENT on /bin/sh) into an unhandled 'error' that would crash this
-  // always-on daemon. Swallow it — the update simply doesn't happen this cycle.
-  if (child && typeof child.on === "function") {
-    child.on("error", (err) => log(`auto-update spawn error: ${err && err.message ? err.message : String(err)}`));
-  }
-  if (child && typeof child.unref === "function") child.unref();
-  return child;
+  return attachAndRelease(child);
 }
 
 // ---- orchestrator -------------------------------------------------------
@@ -390,7 +739,7 @@ export function createAutoUpdater({
     state.updating = true;
     state.updateStartedAt = t;
     try {
-      spawnUpdate({ log, currentVersion: runningVersion, targetVersion: latest, packageRoot, mode: normalizedMode });
+      spawnUpdate({ log, currentVersion: runningVersion, targetVersion: latest, packageRoot, mode: normalizedMode, platform });
     } catch (err) {
       state.updating = false;
       log(`auto-update launch failed: ${err && err.message ? err.message : String(err)}`);
@@ -401,15 +750,16 @@ export function createAutoUpdater({
 
   async function tick() {
     if (!autoUpdateEnabled(env)) return { status: "disabled" };
-    // Only darwin has the launchctl restart path today. On win32/linux the detached
-    // /bin/sh + launchctl script is a no-op that would falsely report "updating" and
-    // then never restart — so the daemon would run stale code forever while thinking
-    // it self-updates. Gate explicitly until a real per-platform path exists.
-    if (platform !== "darwin") return { status: "unsupported-platform" };
+    // Only platforms with a real restart path may update: darwin (launchd bootout +
+    // bootstrap, handed to an independent submitted job) and win32 (Scheduled Tasks
+    // via schtasks /End + /Run, pill first, daemon last). Elsewhere a detached
+    // script would falsely report "updating" and never restart — the daemon would
+    // run stale code forever while thinking it self-updates. Gate explicitly.
+    if (platform !== "darwin" && platform !== "win32") return { status: "unsupported-platform" };
     // The broad layout check is useful for diagnostics, but only update trees we can
     // safely roll back as one unit: a true global install or Relay's dedicated local
     // fallback prefix. Never adopt an arbitrary project's hoisted node_modules.
-    if (!managedInstallInfo(packageRoot)) return { status: "unmanaged" };
+    if (!managedInstallInfo(packageRoot, { platform })) return { status: "unmanaged" };
     const t = now();
     // An update was launched but we're still alive (install failed, or restart is
     // pending) — hold off briefly, then retry the exact pending version. A successful
@@ -489,7 +839,7 @@ export async function runUpdateOnce({
       log("could not reach the npm registry to check for updates.");
       break;
     case "unsupported-platform":
-      log("self-update is only supported on macOS right now — update with `npm i -g relay-companion@latest`.");
+      log("self-update is only supported on macOS and Windows right now — update with `npm i -g relay-companion@latest`.");
       break;
     case "deferred-busy":
       log(`an update to ${result.latest} is ready but deferred while an agent turn is active; it will install once idle.`);