@twinsearth/w2m-dsh-plugin 0.0.0-stage → 0.4.6

package/deploy/systemd/w2m-rabbit.service

@@ -0,0 +1,150 @@
+# ============================================================================
+#  w2m-rabbit.service  --  systemd unit for the W2M relay
+# ============================================================================
+#
+#  This file is a TEMPLATE. Replace the @PLACEHOLDERS@ before installing.
+#
+#  Install (Linux server, systemd):
+#      sudo useradd --system --home /var/lib/w2m --shell /usr/sbin/nologin w2m
+#      sudo install -d -o w2m -g w2m -m 0750 /var/lib/w2m
+#      sudo install -d -o w2m -g w2m -m 0750 /etc/w2m
+#      sudo install -m 0644 deploy/systemd/w2m-rabbit.service \
+#           /etc/systemd/system/w2m-rabbit.service
+#      sudo systemctl daemon-reload
+#      sudo systemctl enable --now w2m-rabbit
+#      journalctl -u w2m-rabbit -f          # watch the pairing code / operator token
+#
+#  Validated how: systemd is not available on the authoring machine, so this
+#  file was NOT checked with `systemd-analyze verify`. It follows the unit
+#  directives' documented semantics; docs/DEPLOY.md names the exact command to
+#  run before trusting it.
+#
+#  ---------------------------------------------------------------------------
+#  WHAT THIS UNIT DELIBERATELY DOES
+#  ---------------------------------------------------------------------------
+#  * Binds 127.0.0.1, never 0.0.0.0. In every supported shape something else
+#    terminates TLS (nginx/Caddy/tunnel) or the network is already encrypted
+#    (Tailscale/WireGuard), so the relay must not be reachable directly.
+#  * Keeps state in /var/lib/w2m via StateDirectory=, so devices and the task
+#    ledger survive restarts. Without this, every restart forces every machine
+#    to pair again -- see docs/TROUBLESHOOTING.md, "everything needs re-pairing".
+#  * Writes nothing to the user's home and needs no writable directory except
+#    its state dir and /run for the pairing-code file.
+#  * Restarts on failure but not in a tight loop (RestartSec + StartLimit*).
+# ============================================================================
+
+[Unit]
+Description=W2M relay (Rabbit) - task relay for cross-machine execution
+Documentation=https://github.com/TwinsEarth/dsh-windows2macos/blob/main/docs/DEPLOY.md
+# Start after the network is up; the relay itself does not need DNS, but
+# ordering here keeps journal timestamps meaningful on a cold boot.
+After=network-online.target
+Wants=network-online.target
+# If the relay sits behind a reverse proxy on the same host, uncomment so the
+# proxy outlives a relay restart without logging connection errors:
+# After=nginx.service
+
+[Service]
+Type=simple
+User=w2m
+Group=w2m
+
+# --- state -----------------------------------------------------------------
+# systemd creates /var/lib/w2m owned by User/Group.
+# `%S` is the *state root* (/var/lib), so `--state %S/w2m` is /var/lib/w2m --
+# the same directory StateDirectory= names. Using the full `%S/w2m` path rather
+# than $STATE_DIRECTORY keeps the flag self-explanatory in `ps` output.
+StateDirectory=w2m
+StateDirectoryMode=0750
+Environment=DSH_HOME=/var/lib/w2m
+# Files created by the relay (operator-token.txt is written 0600, devices.json
+# and ledger.jsonl hold device tokens) must not be world-readable.
+UMask=0077
+
+# --- relay flags -----------------------------------------------------------
+# Keep the relay on loopback and let the proxy/tunnel terminate TLS.
+#
+# Shape A (Tailscale): change the bind address to the tailnet address and read
+#   the "Shape A" section of docs/DEPLOY.md instead; the relay must be
+#   reachable from the tailnet, and 127.0.0.1 is not.
+#
+# Shape B (VPS + TLS): the relay stays here on loopback; nginx/Caddy owns 443.
+#   If you prefer the relay to terminate TLS itself, replace the two flags
+#   below with --tls-cert / --tls-key and give it a --port clients can reach,
+#   then delete the reverse proxy. Pick one, never both.
+#
+# Shape C (tunnel): the tunnel client runs as its own unit (see docs) and
+#   dials 127.0.0.1:8787, so this line does not change. If the tunnel publishes
+#   the relay under a prefix, add --base-path here AND keep the two in sync.
+ExecStart=@RELAY_BIN@ --host 127.0.0.1 --port 8787 --state %S/w2m
+# Extra flags (uncomment what the deployment shape needs):
+#   --base-path /w2m            # only when the tunnel/proxy forwards the prefix
+#   --trust-proxy               # only behind a proxy you control
+#   --pair-rate-limit 5         # default; raise only on a trusted network
+#   --operator-token-file %S/w2m/operator-token.txt   # if the CLI supports it
+#
+# Multi-line form when the flag list grows (systemd joins lines ending in \)：
+# ExecStart=@RELAY_BIN@ \
+#     --host 127.0.0.1 \
+#     --port 8787 \
+#     --state %S/w2m \
+#     --base-path /w2m \
+#     --trust-proxy
+
+# --- secrets ---------------------------------------------------------------
+# Do NOT put the operator token in this file: the unit is world-readable and
+# the token authorises SENDING work to every paired machine.
+# Preferred: let the relay generate one and read /var/lib/w2m/operator-token.txt.
+# If you must inject your own, keep it in an EnvironmentFile with mode 0600
+# owned by root, and let systemd read it:
+# EnvironmentFile=-/etc/w2m/relay.env      # W2M_OPERATOR_TOKEN=...
+# (the leading '-' means "start anyway if the file is missing")
+#
+# NOTE: the relay prints the operator token and the pairing code to stdout, so
+# they end up in the journal. For a public deployment, restrict journal access
+# (sudo usermod -aG systemd-journal <user>) or send them elsewhere.
+
+# --- restart policy --------------------------------------------------------
+Restart=on-failure
+RestartSec=3
+# Give up only after repeated fast failures rather than flapping forever.
+StartLimitIntervalSec=60
+StartLimitBurst=5
+# The relay handles SIGTERM by closing the server and exiting 0; give it time
+# to let clients see a clean disconnect.
+TimeoutStopSec=15
+KillSignal=SIGTERM
+
+# --- hardening -------------------------------------------------------------
+# The relay needs only: loopback sockets, its state dir, and enough of the
+# filesystem to load its own JS. Everything else is denied.
+NoNewPrivileges=yes
+PrivateTmp=yes
+ProtectSystem=strict
+ProtectHome=yes
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectControlGroups=yes
+RestrictSUIDSGID=yes
+RestrictNamespaces=yes
+LockPersonality=yes
+MemoryDenyWriteExecute=no
+# Loopback + (for shape A) the tailnet interface. AF_UNIX is needed by the
+# Node runtime for internal sockets on some builds; AF_INET/AF_INET6 carry the
+# relay itself.
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+SystemCallFilter=@system-service
+SystemCallErrorNumber=EPERM
+# ProtectSystem=strict makes everything read-only except paths named here.
+ReadWritePaths=/var/lib/w2m
+
+# --- logs ------------------------------------------------------------------
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=w2m-rabbit
+# Uncomment to make the startup banner (pairing code, operator token) land in a
+# file an operator can read without journal access. Keep that file 0600.
+# StandardOutput=append:/var/lib/w2m/relay.log
+
+[Install]
+WantedBy=multi-user.target

package/deploy/systemd/w2m-stun.service

@@ -0,0 +1,69 @@
+# ============================================================================
+#  w2m-stun.service  --  systemd unit for the W2M STUN responder
+# ============================================================================
+#
+#  This file is a TEMPLATE. Replace the @PLACEHOLDERS@ before installing.
+#
+#  Install (Linux server, systemd):
+#      sudo install -m 0644 deploy/systemd/w2m-stun.service \
+#           /etc/systemd/system/w2m-stun.service
+#      sudo systemctl daemon-reload
+#      sudo systemctl enable --now w2m-stun
+#      journalctl -u w2m-stun -f
+#
+#  Anything that has to reach it needs UDP :3478 open -- `ufw allow 3478/udp`.
+#  There is nothing to open for TCP: STUN is UDP only in this implementation.
+#
+#  ---------------------------------------------------------------------------
+#  WHAT THIS UNIT DELIBERATELY DOES
+#  ---------------------------------------------------------------------------
+#  * Binds 0.0.0.0. A STUN server that only listened on loopback would discover
+#    nothing: the whole answer it gives is "the address and port the NAT gave
+#    you", which is only meaningful when the query arrives from outside.
+#  * Holds no state and writes nothing. It is the one W2M service that can be
+#    restarted at any time without a single client noticing anything except a
+#    lost query, so it gets no StateDirectory and no writable path at all.
+#  * Runs as the same unprivileged `w2m` user as the relay, because 3478 is
+#    above 1024 and no capability is needed.
+#  * Restarts on failure but not in a tight loop (RestartSec + StartLimit*).
+#
+#  NOT verified: `systemd-analyze verify` was not run (systemd is unavailable on
+#  the authoring machine). The unit that shipped is the one in this repository's
+#  own deployment script, and docs/DEPLOY.md names the command to check it.
+# ============================================================================
+
+[Unit]
+Description=W2M STUN responder - reflexive address discovery for P2P hole punching
+Documentation=https://github.com/TwinsEarth/dsh-windows2macos/blob/main/docs/DEPLOY.md
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=w2m
+Group=w2m
+
+# --- the listener ----------------------------------------------------------
+# 3478 is the IANA-registered STUN port. Machines are pointed at it by
+# `stunServers`, whose default already lists the shared server first.
+ExecStart=/usr/local/bin/node /opt/w2m/app/bin/w2m-stun.mjs --host 0.0.0.0 --port 3478 --log-level info
+
+Restart=always
+RestartSec=2
+StartLimitIntervalSec=60
+StartLimitBurst=5
+
+# --- hardening -------------------------------------------------------------
+# No filesystem access is needed at all: no state, no log file (journal only).
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=
+ProtectKernelTunables=true
+ProtectControlGroups=true
+RestrictAddressFamilies=AF_INET AF_INET6
+RestrictNamespaces=true
+
+[Install]
+WantedBy=multi-user.target

package/deploy/windows/README.md

@@ -0,0 +1,115 @@
+# Windows: running the agent as a service
+
+The agent must run without a console, start with the machine, and survive sign-out.
+Three shapes do that on Windows, and they differ in one thing that matters: **whether
+something third-party ends up hosting the process.**
+
+| | Service-mode task (recommended) | Real SCM service (WinSW / NSSM) | Interactive task |
+|---|---|---|---|
+| Starts at boot | yes (S4U, session 0) | yes | no — at sign-in |
+| Survives sign-out | yes | yes | no |
+| Shows up in `services.msc`, `Restart-Service` | no (`Start-ScheduledTask`) | yes | no |
+| Third-party binary required | **no** | **yes** — the service host | no |
+| Needs elevation to install | yes (S4U ⇒ `SeBatchLogonRight`) | yes | **no** |
+| Console-close death (`0xC000013A`) | avoided (session 0 has no console) | avoided | **hit** — measured twice |
+
+## 1. Service-mode task — `install-service.ps1`
+
+```powershell
+# elevated PowerShell, from the repository root
+powershell -ExecutionPolicy Bypass -File deploy\windows\install-service.ps1 `
+  -Project 'E:\path\to\your\project' `
+  -MachineName win-desktop `
+  -AllowedCommands 'node --test, git status --porcelain' `
+  -AgentArgs '--p2p-mode auto --p2p-port 41235'
+```
+
+It registers **one** task that runs `w2m-agent-supervisor.mjs`, which owns the agent:
+
+* `-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;
+* `RestartCount 999` / 1 min, `ExecutionTimeLimit 0`, `-StartWhenAvailable`.
+
+Everything except the task's own command line goes into **`%USERPROFILE%\.dsh\w2m\agent.json`**,
+which the installer writes and the supervisor reads; edit that file to change the allow-list, the
+project, or the agent's flags, then `Restart-ScheduledTask`-equivalent
+(`Stop-ScheduledTask` + `Start-ScheduledTask`). `-AllowedCommands` is **comma-separated plain
+text** — not JSON, and not because JSON is wrong but because three separate layers eat its quotes
+(see below).
+
+Inspect and remove:
+
+```powershell
+Get-ScheduledTask -TaskName 'W2M Localside agent' | Get-ScheduledTaskInfo
+Get-Content "$env:USERPROFILE\.dsh\w2m\agent.json"
+powershell -ExecutionPolicy Bypass -File deploy\windows\install-service.ps1 -Uninstall
+```
+
+### The three things that were measured, not assumed
+
+1. **Without elevation, S4U registration is refused** with `Access is denied` (S4U needs
+   `SeBatchLogonRight`; an `-AtStartup` trigger needs elevation too). The script says so instead of
+   half-installing. Pass `-Interactive` for the no-elevation shape — it works, but the process lives
+   in the sign-in session, so signing out stops it.
+2. **A JSON argument does not survive the trip.** Registered through a task,
+   `--allowed-commands "[\"node --version\"]"` came back stored as `"[node --version]"`: the escapes
+   gone, the agent reading `[node`, exiting 2 with `ALLOWED_COMMANDS_INVALID`. This project has now
+   hit that in `cmd`, PowerShell 5.1 and Task Scheduler — hence the config file, and hence
+   `-AllowedCommands` taking plain text.
+3. **PowerShell 5.1 writes a UTF-8 BOM** with `Set-Content -Encoding utf8`, and `JSON.parse`
+   refuses it: the supervisor exits 78 *before it opens its log*, so the failure leaves no trace
+   anywhere. The installer writes without a BOM, and the supervisor strips one if it is there
+   (Notepad writes them too, and this file is meant to be hand-edited).
+
+## 2. Real SCM service — WinSW
+
+Only if you need the entry in `services.msc` (monitoring, `Restart-Service`, a
+configuration-management system that knows about services). This puts a third-party
+binary on the machine as the service host, which is a decision the project will not make
+for you:
+
+```powershell
+# 1. get the wrapper (verify the release hash yourself; this is the one third-party piece)
+#    https://github.com/winsw/winsw/releases
+# 2. put w2m-localside.exe and w2m-localside.xml (below) in C:\ProgramData\w2m\
+# 3. install it -- elevated
+C:\ProgramData\w2m\w2m-localside.exe install
+C:\ProgramData\w2m\w2m-localside.exe start
+```
+
+`deploy/windows/winsw/w2m-localside.xml` is the template; edit the two paths in it. The
+supervisor still wraps the agent, so a crash loop is visible in the log rather than
+turning into a service that flaps.
+
+## 3. The one thing that is not a deployment detail
+
+Whichever shape you pick, the machine must be **paired** and the punch port must match its
+firewall rule:
+
+```powershell
+# the identity this agent uses (create it by pairing once, with a code from the relay)
+Get-Content "$env:USERPROFILE\.dsh\xclient\device.json"
+# if you pinned --p2p-port, open exactly that port once -- elevated
+New-NetFirewallRule -DisplayName 'W2M punch (node UDP)' -Direction Inbound -Protocol UDP `
+  -Program 'C:\Program Files\nodejs\node.exe' -LocalPort 41235 -Action Allow
+```
+
+A pinned port is worth it for a service: an ephemeral one changes on every restart, and a
+stale rule looks exactly like "the punch just does not work" — every task quietly falls
+back to the relay with `offer_path: "relay"` in the ledger.
+
+## Verify it, rather than trusting it
+
+```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 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
+
+# and one real dispatch from any machine with the plugin installed
+#   w2m_devices  -> this machine must be listed as online
+#   w2m_run ["git","rev-parse","HEAD"]  -> w2m_wait must show transport: p2p (or relay, with a reason)
+```

package/deploy/windows/install-service.ps1

@@ -0,0 +1,195 @@
+# ============================================================================
+#  install-service.ps1 -- run the W2M Localside agent as a Windows service
+# ============================================================================
+#
+#  WHAT "SERVICE MODE" MEANS HERE, AND WHAT IT DOES NOT
+#
+#  A Node process cannot be an SCM service by itself: the Service Control Manager
+#  requires the process to answer StartServiceCtrlDispatcher, which needs native
+#  bindings this project does not have (and will not add -- zero runtime
+#  dependencies is a stated property, not an accident). So there are two honest
+#  shapes, and this script implements the first:
+#
+#    1. SERVICE-MODE TASK (this script) -- a scheduled task with LogonType S4U:
+#       starts at boot, runs in session 0 with no console, survives sign-out, and
+#       is managed with Start-ScheduledTask/Stop-ScheduledTask. No third-party
+#       binary. Requires **elevation** (S4U needs SeBatchLogonRight, and the
+#       registration is refused with "Access is denied" without it -- measured).
+#
+#    2. REAL SCM SERVICE via WinSW or NSSM -- a genuine entry in services.msc and
+#       for `Restart-Service`. It needs a third-party service host binary, which
+#       is a dependency decision rather than a deployment detail; see README.md
+#       in this directory for the template and the caveat.
+#
+#  WHY THE AGENT RUNS UNDER A SUPERVISOR
+#
+#  Measured twice: an agent started directly can be gone ~40 s later with
+#  0xC000013A (STATUS_CONTROL_C_EXIT -- its console went away) and no log line,
+#  because whatever was logging died with it. The task therefore runs
+#  w2m-agent-supervisor.mjs, which respawns the agent with a capped backoff and
+#  logs one line per run.
+#
+#  USAGE
+#
+#    # elevated PowerShell, from the repository root:
+#    powershell -ExecutionPolicy Bypass -File deploy\windows\install-service.ps1 `
+#      -Project 'E:\path\to\your\project' `
+#      -AllowedCommands '["node --test","git status --porcelain"]'
+#
+#    # inspect / remove
+#    Get-ScheduledTask -TaskName 'W2M Localside agent' | Get-ScheduledTaskInfo
+#    powershell -ExecutionPolicy Bypass -File deploy\windows\install-service.ps1 -Uninstall
+#
+#  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).
+# ============================================================================
+[CmdletBinding()]
+param(
+  [string]$TaskName = 'W2M Localside agent',
+  [string]$Rabbit = 'http://202.182.123.154:8787',
+  [string]$Project = (Get-Location).Path,
+  [string]$MachineName = $env:COMPUTERNAME,
+  [string]$AllowedCommands = 'node --version, node --test, git status --porcelain, git rev-parse',
+  [string]$StateDir = "$env:USERPROFILE\.dsh\w2m\localside",
+  [string]$LogPath = "$env:USERPROFILE\.dsh\w2m\agent.log",
+  [string]$Bin = '',
+  [string]$AgentArgs = '',
+  [int]$RestartBackoffMs = 60000,
+  [switch]$Interactive,
+  [switch]$Uninstall,
+  [switch]$WhatIfOnly
+)
+
+$ErrorActionPreference = 'Stop'
+$repo = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)   # ...\deploy\windows -> repo root
+$supervisor = Join-Path $PSScriptRoot 'w2m-agent-supervisor.mjs'
+$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" }
+
+if ($Uninstall) {
+  if (Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue) {
+    Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+    Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false
+    Write-Host "removed scheduled task: $TaskName"
+  } else {
+    Write-Host "nothing to remove: $TaskName does not exist"
+  }
+  return
+}
+
+if (-not $Bin) {
+  $Bin = Join-Path $env:USERPROFILE '.dsh\profiles\desktop\node_modules\@twinsearth\w2m-dsh-plugin\bin\w2m-localside.mjs'
+}
+
+# THE ALLOW-LIST GOES INTO A FILE, NOT ONTO A COMMAND LINE.
+#
+# Measured three times on this project: `cmd`, PowerShell 5.1 and finally Task Scheduler each
+# mangled a JSON argument. Registered through a task, `--allowed-commands "[\"node --version\"]"`
+# came back stored as `"[node --version]"` -- the escapes gone, the agent reading `[node` and
+# exiting 2 with ALLOWED_COMMANDS_INVALID. A config file has no quoting rules, and it is one more
+# thing this installer can write for whoever has to debug the service later.
+$configPath = Join-Path (Split-Path -Parent $StateDir) 'agent.json'
+$agentArgs = @($AgentArgs -split '[,\s]+' | Where-Object { $_ -ne '' })
+# Comma/semicolon/newline separated, NOT JSON. Measured: `powershell -File` strips the quotes out of
+# a JSON argument (`["node --version"]` arrives as `[node --version]`), which is one mangling more
+# than this installer needs to survive. Nothing in an allow-list entry contains a comma.
+$allowList = @($AllowedCommands -split '[,;\r\n]+' | ForEach-Object { $_.Trim() } | Where-Object { $_ -ne '' })
+if ($allowList.Count -eq 0) { throw '-AllowedCommands must name at least one command prefix' }
+$config = [ordered]@{
+  bin             = $Bin
+  rabbit          = $Rabbit
+  project         = $Project
+  name            = $MachineName
+  state           = $StateDir
+  log             = $LogPath
+  allowedCommands = $allowList
+  agentArgs       = $agentArgs
+  backoffMs       = $RestartBackoffMs
+}
+
+$arguments = @("`"$supervisor`"", '--config', "`"$configPath`"")
+
+Write-Host 'service-mode task plan'
+Write-Host "  task        : $TaskName"
+Write-Host "  runs as     : $env:USERDOMAIN\$env:USERNAME ($(if ($Interactive) { 'interactive: signed in only' } else { 'S4U: whether signed in or not, session 0' }))"
+Write-Host "  command     : `"$node`" $($arguments -join ' ')"
+Write-Host "  config      : $configPath"
+Write-Host "  allow-list  : $($config.allowedCommands -join ' | ')"
+Write-Host "  log         : $LogPath"
+if ($WhatIfOnly) {
+  Write-Host 'config that would be written:'
+  $config | ConvertTo-Json -Depth 4
+  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
+# trace anywhere. (The supervisor also strips a BOM now; both ends, because the file is meant to be
+# hand-editable and Notepad writes BOMs too.)
+$json = $config | ConvertTo-Json -Depth 4
+[System.IO.File]::WriteAllText($configPath, $json, (New-Object System.Text.UTF8Encoding($false)))
+Write-Host "wrote $configPath"
+
+$action = New-ScheduledTaskAction -Execute $node -Argument ($arguments -join ' ') -WorkingDirectory $PSScriptRoot
+# 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.
+$triggers = if ($Interactive) {
+  @(New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME")
+} else {
+  @(
+    (New-ScheduledTaskTrigger -AtStartup),
+    (New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME")
+  )
+}
+$settings = New-ScheduledTaskSettingsSet `
+  -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
+  -MultipleInstances IgnoreNew `
+  -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
+
+if ($Interactive) {
+  # The no-elevation shape. It works and it is what this project shipped first, but the process
+  # lives in the sign-in session: closing that session's console is what produced 0xC000013A, which
+  # is the death the supervisor now at least records.
+  Write-Warning 'Interactive mode: the agent runs only while this user is signed in, and a console close can kill it (the supervisor will restart it when the session returns).'
+}
+
+try {
+  Register-ScheduledTask -TaskName $TaskName -Action $action -Trigger $triggers -Settings $settings -Principal $principal -Force | Out-Null
+} catch {
+  Write-Error @"
+could not register the task: $($_.Exception.Message)
+
+For the default (session-0, S4U) shape that refusal is the expected one when this
+script is not elevated: S4U needs SeBatchLogonRight, and an AtStartup trigger needs
+elevation too -- the registration is denied with "Access is denied". Re-run the same
+command from an **elevated** PowerShell.
+
+If you cannot elevate, ask for the interactive shape instead (one trigger, AtLogOn):
+
+  powershell -ExecutionPolicy Bypass -File deploy\windows\install-service.ps1 -Interactive `
+    -Project '$Project' -AllowedCommands '$AllowedCommands'
+
+It works, and it is what this project shipped first -- but the process lives in the
+sign-in session, so signing out stops it and a console close can kill it.
+"@
+  return
+}
+
+Start-ScheduledTask -TaskName $TaskName
+Start-Sleep -Seconds 10
+$task = Get-ScheduledTask -TaskName $TaskName
+$info = $task | Get-ScheduledTaskInfo
+Write-Host "state=$($task.State) lastRun=$($info.LastRunTime) lastResult=$($info.LastTaskResult)"
+Write-Host "session of the agent process (0 = service session):"
+Get-Process node -ErrorAction SilentlyContinue |
+  Where-Object { $_.StartTime -gt (Get-Date).AddMinutes(-2) } |
+  Select-Object Id, SessionId, StartTime | Format-Table -AutoSize
+Write-Host "log tail:"
+Get-Content $LogPath -Tail 5 -ErrorAction SilentlyContinue