@twinsearth/w2m-dsh-plugin 0.5.9 → 0.6.1

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