@twinsearth/w2m-dsh-plugin 0.5.8 → 0.6.1

package/deploy/windows/README.md

@@ -28,7 +28,15 @@ It registers **one** task that runs `w2m-agent-supervisor.mjs`, which owns the a
 
 * `-AtStartup` **and** `-AtLogOn`, `LogonType S4U` → runs whether the user is signed in or not,
   in session 0, with no console for anything to close;
-* `MultipleInstances IgnoreNew` → two agents must never share one device identity;
+* a **watchdog trigger** every 5 minutes (`-WatchdogMinutes`), because a supervisor killed by a
+  console teardown cannot be restarted by `RestartCount` alone — the task simply ends;
+* `MultipleInstances Parallel` → the trigger may start a second supervisor, which is safe because
+  the supervisor's own lock is what prevents a second *agent*: a generation that finds the lock held
+  logs a no-op line and exits without spawning. (This replaced `IgnoreNew`, which could not recover
+  from the one death that matters: measured, a task whose supervisor died while the task still
+  reported `Running` refused every later start with `0x800710E0` and stayed dead — one supervisor,
+  one agent, the port bound, and no way back. Re-register an existing installation with
+  `-UpdateTask`, which needs no elevation and touches only the triggers and settings.)
 * `RestartCount 999` / 1 min, `ExecutionTimeLimit 0`, `-StartWhenAvailable`.
 
 Everything except the task's own command line goes into **`%USERPROFILE%\.dsh\w2m\agent.json`**,
@@ -101,11 +109,22 @@ back to the relay with `offer_path: "relay"` in the ledger.
 
 ## Verify it, rather than trusting it
 
+The supervisor's invariants — one generation, one agent, the punch port bound by that agent — have a
+runnable check that needs no administrator right and cannot disturb a live installation (it drives
+the supervisor against a stub worker on ports the OS picks):
+
+```powershell
+node deploy\windows\verify-supervisor.mjs          # 8 checks; --keep leaves the temp tree behind
+```
+
 ```powershell
 # the task is running, and in which session
 Get-ScheduledTask -TaskName 'W2M Localside agent' | Select-Object State
 Get-Process node | Where-Object { $_.SessionId -eq 0 } | Select-Object Id, SessionId, StartTime
 
+# the supervisor's own account of itself: state, the live child, the reaped pids, the punch port
+Get-Content "$env:USERPROFILE\.dsh\w2m\supervisor-heartbeat.json"
+
 # the agent's own narration: "stream ready" is the line that means the fleet can reach it
 Get-Content "$env:USERPROFILE\.dsh\w2m\agent.log" -Tail 20
 

package/deploy/windows/install-service.ps1

@@ -40,6 +40,10 @@
 #    Get-ScheduledTask -TaskName 'W2M Localside agent' | Get-ScheduledTaskInfo
 #    powershell -ExecutionPolicy Bypass -File deploy\windows\install-service.ps1 -Uninstall
 #
+#    # repair a task registered by an older version of this script (one that used
+#    # `MultipleInstances IgnoreNew` and therefore could not recover from a supervisor death):
+#    powershell -ExecutionPolicy Bypass -File deploy\windows\install-service.ps1 -UpdateTask
+#
 #  Everything after the parameters goes to the agent, so `-AgentArgs
 #  '--p2p-port','41235'` pins the punch socket (and then one inbound firewall rule
 #  is enough, instead of a rule per restart).
@@ -58,6 +62,8 @@ param(
   [int]$RestartBackoffMs = 60000,
   [int]$WatchdogMinutes = 5,
   [switch]$Interactive,
+  [switch]$UpdateTask,
+  [switch]$UpdateConfig,
   [switch]$Uninstall,
   [switch]$WhatIfOnly
 )
@@ -65,6 +71,54 @@ param(
 $ErrorActionPreference = 'Stop'
 $repo = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)   # ...\deploy\windows -> repo root
 $supervisor = Join-Path $PSScriptRoot 'w2m-agent-supervisor.mjs'
+
+# ---------------------------------------------------------------------------------------------
+# -UpdateTask: repair an EXISTING registration, and touch nothing else.
+#
+# This exists because the task and the supervisor have to agree, and an installation registered by an
+# older version of this script does not: `MultipleInstances IgnoreNew` together with the watchdog
+# trigger means a task whose supervisor died while the task still reports Running can never start
+# again. Measured on this machine: one supervisor, one agent, the port bound, and no way back.
+#
+# It runs FIRST and RETURNS, before the agent config is written and before node is even looked for,
+# so it needs no elevation: `Set-ScheduledTask` on a task this user already owns is permitted
+# (measured), while re-registering the S4U principal is not. Triggers and settings only -- the action,
+# the principal and `%USERPROFILE%\.dsh\w2m\agent.json` are left exactly as they are.
+# ---------------------------------------------------------------------------------------------
+if ($UpdateTask) {
+  if (-not (Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue)) {
+    Write-Error "nothing to update: $TaskName is not registered. Run without -UpdateTask to install it."
+    return
+  }
+  $watchdog = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(1) `
+    -RepetitionInterval (New-TimeSpan -Minutes $WatchdogMinutes) `
+    -RepetitionDuration ([TimeSpan]::FromDays(3650))
+  $existingTriggers = (Get-ScheduledTask -TaskName $TaskName).Triggers
+  $isInteractive = -not ($existingTriggers | Where-Object { $_.CimClass.CimClassName -eq 'MSFT_TaskBootTrigger' })
+  $updateTriggers = if ($isInteractive) {
+    @((New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME"), $watchdog)
+  } else {
+    @(
+      (New-ScheduledTaskTrigger -AtStartup),
+      (New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME"),
+      $watchdog
+    )
+  }
+  $updateSettings = New-ScheduledTaskSettingsSet `
+    -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
+    -MultipleInstances Parallel `
+    -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) `
+    -ExecutionTimeLimit (New-TimeSpan -Seconds 0) `
+    -StartWhenAvailable -Hidden
+  Set-ScheduledTask -TaskName $TaskName -Trigger $updateTriggers -Settings $updateSettings | Out-Null
+  $updated = Get-ScheduledTask -TaskName $TaskName
+  Write-Host "updated $TaskName (triggers and settings only; the action and the config are untouched)"
+  Write-Host "  multiple instances : $($updated.Settings.MultipleInstances)  (Parallel: the supervisor's lock is what prevents a second agent)"
+  Write-Host "  watchdog           : every $WatchdogMinutes min, indefinitely"
+  Write-Host "  state              : $($updated.State)"
+  return
+}
+
 $node = (Get-Command node -ErrorAction SilentlyContinue).Source
 if (-not $node) { throw 'node is not on PATH; install Node 20.19+ first' }
 if (-not (Test-Path $supervisor)) { throw "supervisor missing: $supervisor" }
@@ -124,6 +178,27 @@ if ($WhatIfOnly) {
   $config | ConvertTo-Json -Depth 4
   return
 }
+# THE CONFIG IS THE PART THAT CANNOT BE REBUILT FROM DEFAULTS.
+#
+# Measured the hard way while testing this deployment: re-running the installer with no parameters
+# overwrote a live `agent.json` with the defaults -- the project became the current directory, the
+# machine name became the hostname, and `--p2p-mode auto --p2p-port 41235` disappeared, so the agent
+# immediately took an ephemeral port and every dispatch would have fallen back to the relay. Nothing
+# errored and nothing warned; the file was simply replaced. Refusing by default, and naming exactly
+# what would be lost, is one line of protection against the failure this whole directory is about.
+if ((Test-Path $configPath) -and -not $UpdateConfig -and -not $WhatIfOnly) {
+  $current = Get-Content $configPath -Raw | ConvertFrom-Json
+  if ($current.project -ne $Project -or $current.name -ne $MachineName -or [string]$current.agentArgs -ne ($agentArgs -join ' ')) {
+    Write-Error @"
+$configPath already exists and differs from what this run would write:
+  now : project=$($current.project) name=$($current.name) agentArgs="$($current.agentArgs)"
+  next: project=$Project name=$MachineName agentArgs="$($agentArgs -join ' ')"
+Re-run with -UpdateConfig to replace it, or with -WhatIfOnly to see the whole file first.
+A silent replacement is how a machine loses its pinned punch port and its identity.
+"@
+    return
+  }
+}
 New-Item -ItemType Directory -Force -Path (Split-Path -Parent $configPath) | Out-Null
 # Write it WITHOUT a BOM. `Set-Content -Encoding utf8` on PowerShell 5.1 prepends one, `JSON.parse`
 # refuses it, and the supervisor then exits 78 before it has opened its log -- a failure with no
@@ -135,28 +210,30 @@ Write-Host "wrote $configPath"
 
 $action = New-ScheduledTaskAction -Execute $node -Argument ($arguments -join ' ') -WorkingDirectory $PSScriptRoot
 # ---------------------------------------------------------------------------------------------
-# SELF-HEALING WITHOUT ELEVATION
+# THE WATCHDOG TRIGGER, AND WHY THE TASK MAY NOW RUN MORE THAN ONE INSTANCE
 #
 # Measured twice on this machine: the whole process tree (supervisor + agent) is killed with
 # 0xC000013A (STATUS_CONTROL_C_EXIT -- its console went away), the log ends mid-sentence, and Task
 # Scheduler does NOT bring it back even with RestartCount 999: the task simply ends. The fleet then
-# silently loses the machine, which is exactly the failure a supervisor was supposed to prevent --
-# a supervisor that shares the console dies with it.
-#
-# A repeating trigger fixes that without any administrator right: combined with
-# `MultipleInstances IgnoreNew` the task means "be running, or start", so a death from any cause is
-# repaired at the next tick. The window is the repetition interval, and that is the honest trade:
-# up to N minutes offline after a console-close death, versus needing elevation for a session-0
-# service (the real fix, and the default mode above).
+# silently loses the machine, which is exactly the failure a supervisor was supposed to prevent.
+#
+# A repeating trigger fixes that without any administrator right: the task means "be running, or
+# start", so a death from any cause is repaired at the next tick. Until recently that trigger had to
+# be paired with `MultipleInstances IgnoreNew` to keep it from producing a second agent, and that
+# pairing is what cost this machine a day: measured, a supervisor killed while the task still
+# reported Running left the task in `Running` forever (the rejected start is 0x800710E0, "the
+# operator or administrator has refused the request"), so the watchdog could never fire again while
+# the detached agent kept the punch port -- one supervisor, one agent, port bound, and no way back.
+#
+# `MultipleInstances Parallel` is now the correct setting, because the supervisor's own lock is what
+# makes a second start harmless: a generation that finds the lock held logs a no-op line and exits
+# without spawning, so a tick during a healthy run costs one short-lived process and nothing else.
+# The trigger therefore does what it was written to do -- repair a dead supervisor -- and cannot do
+# the thing it was feared for.
 # ---------------------------------------------------------------------------------------------
-$repetition = if ($Interactive) {
-  # `[TimeSpan]::MaxValue` is NOT a valid duration here -- Task Scheduler rejects it and the whole
-  # registration fails (measured: the script had already stopped the old task, so the machine was
-  # left with no agent at all). Ten years is the idiomatic stand-in for "repeat indefinitely".
-  New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(1) `
-    -RepetitionInterval (New-TimeSpan -Minutes $WatchdogMinutes) `
-    -RepetitionDuration ([TimeSpan]::FromDays(3650))
-} else { $null }
+$repetition = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(1) `
+  -RepetitionInterval (New-TimeSpan -Minutes $WatchdogMinutes) `
+  -RepetitionDuration ([TimeSpan]::FromDays(3650))
 # AtStartup only makes sense for the session-0 (S4U) shape, which also runs whether or not anyone is
 # signed in. Registering an AtStartup trigger on an interactive task is refused without elevation --
 # measured, and the reason this list is conditional rather than always two entries.
@@ -165,15 +242,17 @@ $triggers = if ($Interactive) {
 } else {
   @(
     (New-ScheduledTaskTrigger -AtStartup),
-    (New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME")
+    (New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME"),
+    $repetition
   )
 }
 $settings = New-ScheduledTaskSettingsSet `
   -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
-  -MultipleInstances IgnoreNew `
+  -MultipleInstances Parallel `
   -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) `
   -ExecutionTimeLimit (New-TimeSpan -Seconds 0) `
   -StartWhenAvailable -Hidden
+
 $principal = New-ScheduledTaskPrincipal -UserId "$env:USERDOMAIN\$env:USERNAME" `
   -LogonType $(if ($Interactive) { 'Interactive' } else { 'S4U' }) -RunLevel Limited