@trillboards/edge-sdk 0.2.16 → 0.2.18

package/deploy/windows/ensure-sensing.ps1

@@ -40,7 +40,97 @@ if (-not $task) {
   }
 }
 
-if ($task.State -eq 'Disabled') {
+# MIGRATION. Installs made before the headless fix carry a logon-only task, so
+# they still go dark after an unattended reboot even though the shipped scripts
+# on disk are now correct. There is no auto-updater, so the installer is not the
+# only path that has to repair this. Re-register when -- and only when -- the
+# registered task has NO logon-free start path: after one repair this is a
+# no-op, so it cannot churn a healthy install or interrupt sensing on every
+# wizard close.
+#
+# Both shapes count as repaired. register-task.ps1 registers a boot trigger only
+# when it can (Microsoft allows those to Administrators only) and otherwise
+# lands on a repeating trigger, which is the shape a normal no-admin install
+# gets. Keying this check on <BootTrigger> alone would re-register that install
+# on EVERY wizard close.
+$needsHeadlessRepair = $false
+try {
+  $definition = Export-ScheduledTask -TaskName $TaskName
+  $needsHeadlessRepair = ($definition -notmatch "<BootTrigger>") -and ($definition -notmatch "<Repetition>")
+} catch {
+  Write-Host "Could not read the current task definition: $($_.Exception.Message)"
+}
+if ($needsHeadlessRepair) {
+  $register = Join-Path $InstallDir "bin\register-task.ps1"
+  if (Test-Path $register) {
+    Write-Host "Upgrading '$TaskName' from a logon-only registration to a startup one."
+    # Non-fatal: the final runnable check below is the loud signal. A failed
+    # repair must not be what stops a customer closing the setup window.
+    try { & $register -InstallDir $InstallDir | Out-Null }
+    catch { Write-Host "Headless re-registration failed: $($_.Exception.Message)" }
+    $task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+  }
+}
+
+# THE ONE UAC PROMPT. Everything above works unelevated, but the PRINCIPAL does
+# not: measured on windows-latest (run 31836760844), a standard user registering
+# for ITSELF is refused S4U with "Access is denied", because S4U performs a batch
+# logon and Task Scheduler only grants SeBatchLogonRight when the CALLER is an
+# administrator. An unelevated install therefore lands on 'Interactive + repeat',
+# which still needs somebody logged on -- i.e. the reboot defect is NOT fixed.
+# One elevation is the entire difference, so ask for it HERE: this runs at setup
+# -wizard close, with the customer present, and register-task.ps1 repairs the
+# model-server task in the same elevated pass so this is the only prompt.
+#
+# Every guard below exists to make sure we never prompt when it cannot help:
+#   - already headless          -> nothing to gain
+#   - not UserInteractive       -> no desktop to show a dialog on; -Verb RunAs
+#                                  would throw or hang an unattended install
+#   - not admin-capable         -> UAC would show an over-the-shoulder CREDENTIAL
+#                                  prompt to a standard user who cannot satisfy it
+#   - already elevated          -> register-task.ps1 above already used it
+# A declined or failed prompt is NOT an error: the unelevated registration from
+# the ladder is still in place and still better than what shipped before.
+function Test-IsElevated {
+  $identity = [System.Security.Principal.WindowsIdentity]::GetCurrent()
+  (New-Object System.Security.Principal.WindowsPrincipal($identity)).IsInRole(
+    [System.Security.Principal.WindowsBuiltInRole]::Administrator)
+}
+function Test-AdminCapable {
+  # On a filtered admin token the Administrators SID is still present (deny-only),
+  # which is exactly the population for whom one UAC click changes the outcome.
+  foreach ($group in [System.Security.Principal.WindowsIdentity]::GetCurrent().Groups) {
+    if ($group.Value -eq 'S-1-5-32-544') { return $true }
+  }
+  return $false
+}
+
+$isHeadless = $false
+try {
+  $current = Export-ScheduledTask -TaskName $TaskName
+  $isHeadless = (($current -match "<BootTrigger>") -or ($current -match "<Repetition>")) -and
+    ($current -notmatch "<LogonType>InteractiveToken</LogonType>")
+} catch {}
+
+if ((-not $isHeadless) -and [Environment]::UserInteractive -and (Test-AdminCapable) -and -not (Test-IsElevated)) {
+  $register = Join-Path $InstallDir "bin\register-task.ps1"
+  if (Test-Path $register) {
+    Write-Host "Asking for one elevation so sensing can resume after an unattended restart."
+    try {
+      $psExe = Join-Path $env:WINDIR "System32\WindowsPowerShell\v1.0\powershell.exe"
+      $psArgs = @(
+        '-NoProfile', '-ExecutionPolicy', 'Bypass', '-WindowStyle', 'Hidden',
+        '-File', ('"' + $register + '"'), '-InstallDir', ('"' + $InstallDir + '"')
+      )
+      Start-Process -FilePath $psExe -ArgumentList $psArgs -Verb RunAs -WindowStyle Hidden -Wait -ErrorAction Stop
+      $task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+    } catch {
+      Write-Host "Elevated re-registration was not completed ($($_.Exception.Message)). Keeping the unelevated registration."
+    }
+  }
+}
+
+if ($task -and $task.State -eq 'Disabled') {
   Enable-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue | Out-Null
   $task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
 }

package/deploy/windows/register-litertlm-task.ps1

@@ -1,10 +1,20 @@
 <#
-  register-litertlm-task.ps1 — register the per-user Scheduled Task that runs the
-  LiteRT-LM on-device VLM server (Gemma 4 E2B) at logon, with crash-restart.
-  Per-user + Interactive logon type → NO admin/UAC (mirrors the macOS
-  com.trillboards.litertlm LaunchAgent: KeepAlive=true + ThrottleInterval=30).
-  The connector's LiteRtVlmProvider talks to the OpenAI-compatible endpoint on
-  127.0.0.1:<Port>. Invoked by setup-litertlm.ps1.
+  register-litertlm-task.ps1 -- register the Scheduled Task that runs the
+  LiteRT-LM on-device VLM server (Gemma 4 E2B) with crash-restart. It runs the
+  SAME degradation ladder as register-task.ps1 and must land on the same rung --
+  this task is not optional furniture, because the connector's default
+  auto-sense mode WAITS on the OpenAI-compatible endpoint at 127.0.0.1:<Port>,
+  so a connector that comes back headless while this one still waits for a logon
+  is a connector that runs and senses nothing.
+
+  This script never prompts. Headless costs one elevation on Windows (S4U needs
+  the account to hold SeBatchLogonRight, which Task Scheduler grants only to an
+  administrator caller), and a second UAC dialog in one install is not
+  acceptable -- so ensure-sensing.ps1 owns the single prompt and register-task.ps1
+  repairs THIS task inside that same elevated pass. Unelevated, both land on
+  'Interactive + repeat' together, which is consistent rather than headless.
+  Mirrors the macOS com.trillboards.litertlm LaunchAgent (KeepAlive=true +
+  ThrottleInterval=30). Invoked by setup-litertlm.ps1.
 #>
 param(
   [Parameter(Mandatory = $true)][string]$LitertLmPath,
@@ -14,29 +24,118 @@ $ErrorActionPreference = "Stop"
 
 $TaskName = "TrillboardsLiteRtLm"
 $UserId = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
-# litert-lm serve --host 127.0.0.1 --port <port>  (loopback only — the connector
+# litert-lm serve --host 127.0.0.1 --port <port>  (loopback only -- the connector
 # is local; never expose the model server off-box).
 $argument = 'serve --host 127.0.0.1 --port ' + $Port
 $Action  = New-ScheduledTaskAction  -Execute $LitertLmPath -Argument $argument
-$Trigger = New-ScheduledTaskTrigger -AtLogOn -User $UserId
+
+# NOT AT LOGON -- see register-task.ps1 for the full rationale, including why
+# the REPEATING trigger (not the boot trigger) is the load-bearing one: only an
+# Administrators-group member can create a task with a boot trigger, and this
+# runs from a no-admin installer.
+$RepeatTrigger = New-ScheduledTaskTrigger -Once -At ((Get-Date).AddMinutes(1)) `
+  -RepetitionInterval (New-TimeSpan -Minutes 5) -RepetitionDuration (New-TimeSpan -Days 3650)
+# The boot delay is longer here than the connector's 30s because this process
+# memory-maps a ~2.4 GB model off a disk that is still busy with the rest of boot.
+$BootTrigger = New-ScheduledTaskTrigger -AtStartup
+# Best-effort, exactly as in register-task.ps1: never fail registration over it.
+try { $BootTrigger.Delay = "PT1M" } catch { Write-Warning "Could not set the boot-trigger delay: $($_.Exception.Message)" }
+# Fastest re-arm when someone does log on.
+$LogonTrigger = New-ScheduledTaskTrigger -AtLogOn -User $UserId
+
 # RestartCount/Interval == the plist's ThrottleInterval crash-loop guard (e.g.
 # while the ~2.4 GB model is still importing on first run); Zero time limit ==
-# the always-on KeepAlive serve endpoint.
+# the always-on KeepAlive serve endpoint. MultipleInstances IgnoreNew matters
+# now that several triggers exist: a second `serve` would fail to bind $Port anyway.
 $Settings = New-ScheduledTaskSettingsSet -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1) `
   -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable `
+  -MultipleInstances IgnoreNew `
   -ExecutionTimeLimit ([TimeSpan]::Zero)
-$Principal = New-ScheduledTaskPrincipal -UserId $UserId -LogonType Interactive -RunLevel Limited
 
-Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
-Register-ScheduledTask -TaskName $TaskName -Action $Action -Trigger $Trigger -Settings $Settings `
-  -Principal $Principal -Description "Trillboards LiteRT-LM - on-device Gemma VLM server (:$Port)" | Out-Null
+# S4U, NOT SystemAccount: litert-lm.exe itself lives under the user profile
+# ($env:USERPROFILE\.local\bin, setup-litertlm.ps1:23) and loads the model from
+# $env:USERPROFILE\.litert-lm (:25). SYSTEM would resolve both to
+# C:\Windows\system32\config\systemprofile and the server would not start at all.
+function New-LitertPrincipal([string]$LogonType) {
+  New-ScheduledTaskPrincipal -UserId $UserId -LogonType $LogonType -RunLevel Limited
+}
+
+$Description = "Trillboards LiteRT-LM - on-device Gemma VLM server (:$Port)"
+
+# Same degradation ladder as register-task.ps1, for the same reasons.
+$Attempts = @(
+  @{ Label = "S4U + boot + repeat";      LogonType = "S4U";         Triggers = @($BootTrigger, $RepeatTrigger, $LogonTrigger) },
+  @{ Label = "S4U + repeat";             LogonType = "S4U";         Triggers = @($RepeatTrigger, $LogonTrigger) },
+  @{ Label = "Interactive + repeat";     LogonType = "Interactive"; Triggers = @($RepeatTrigger, $LogonTrigger) },
+  @{ Label = "Interactive + logon only"; LogonType = "Interactive"; Triggers = @($LogonTrigger) }
+)
+
+# STOP THE RUNNING SERVE BEFORE RE-REGISTERING, and wait for it to actually go.
+#
+# Unregistering a task is not documented to terminate a running instance, and
+# `litert-lm serve` is a long-lived process holding :$Port. Left alive it keeps
+# ANSWERING - so a version upgrade would install the new CLI, re-register the
+# task, fail to bind the port, and leave the OLD binary serving while every
+# health probe passed. That is precisely how a host could sit on a litert-lm
+# that rejects the `,gpu` model id after we thought we had repaired it.
+#
+# Done ONCE, before the degradation ladder below: the ladder may unregister and
+# re-register several times, and killing the serve on each attempt would only
+# lengthen the window with no model server.
+Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+
+# Belt and braces: kill any litert-lm process still listening on the port. Scoped
+# to THIS user's processes whose command line carries our port, so a developer's
+# unrelated python is never touched.
+try {
+  Get-CimInstance Win32_Process -Filter "Name = 'python.exe' OR Name = 'litert-lm.exe' OR Name = 'pythonw.exe'" -ErrorAction SilentlyContinue |
+    Where-Object { $_.CommandLine -and $_.CommandLine -match 'litert-lm' -and $_.CommandLine -match ('--port\s+' + [regex]::Escape($Port)) } |
+    ForEach-Object {
+      Write-Host "stopping previous litert-lm serve (pid $($_.ProcessId)) before re-registering"
+      Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue
+    }
+} catch { }
+
+# Wait for the port to free, so the Start-ScheduledTask below does not race a
+# dying serve.
+for ($i = 0; $i -lt 15; $i++) {
+  $inUse = $null
+  try { $inUse = Get-NetTCPConnection -LocalPort ([int]$Port) -State Listen -ErrorAction SilentlyContinue } catch { }
+  if (-not $inUse) { break }
+  Start-Sleep -Seconds 1
+}
+
+$Landed = $null
+foreach ($attempt in $Attempts) {
+  Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
+  try {
+    Register-ScheduledTask -TaskName $TaskName -Action $Action -Trigger $attempt.Triggers -Settings $Settings `
+      -Principal (New-LitertPrincipal $attempt.LogonType) -Description $Description -ErrorAction Stop | Out-Null
+    $Landed = $attempt
+    break
+  } catch {
+    Write-Host "Registration attempt '$($attempt.Label)' was refused: $($_.Exception.Message)"
+  }
+}
+if (-not $Landed) {
+  Write-Error "Scheduled task '$TaskName' could not be registered in ANY supported shape."
+  exit 1
+}
 
 $registered = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
 if (-not $registered) {
   Write-Error "Scheduled task '$TaskName' did NOT register (Get-ScheduledTask found nothing)."
   exit 1
 }
+$definition = Export-ScheduledTask -TaskName $TaskName
+$logonType = if ($definition -match "<LogonType>([^<]+)</LogonType>") { $Matches[1] } else { "unknown" }
+if (($definition -notmatch "<BootTrigger>") -and ($definition -notmatch "<Repetition>")) {
+  Write-Warning "Scheduled task '$TaskName' registered with a LOGON-ONLY trigger - the connector would come back after a reboot with no model server."
+}
+if ($logonType -eq "InteractiveToken") {
+  Write-Warning "Scheduled task '$TaskName' registered with an INTERACTIVE principal - the model server will only run while $UserId is logged on."
+}
 
-# Start it now (don't wait for the next logon) so first-run sensing has a server.
+# Start it now (don't wait for the next boot) so first-run sensing has a server.
 Start-ScheduledTask -TaskName $TaskName
-Write-Host "Registered scheduled task '$TaskName' (litert-lm serve on :$Port, restarts on failure)."
+Write-Host "Registered scheduled task '$TaskName' (litert-lm serve on :$Port, shape '$($Landed.Label)', logon type $logonType, restarts on failure)."

package/deploy/windows/register-task.ps1

@@ -1,8 +1,9 @@
 <#
-  register-task.ps1 — register the per-user Scheduled Task that runs the
-  Trillboards local-first connector at logon (with crash-restart). Per-user +
-  Interactive logon type so NO admin/UAC is required (mirrors the home-domain,
-  no-sudo macOS LaunchAgent). Invoked by the NSIS installer post-copy.
+  register-task.ps1 -- register the Scheduled Task that runs the Trillboards
+  local-first connector HEADLESS: an AtStartup trigger plus an S4U principal, so
+  sensing is back within a minute of an unattended Windows Update reboot with
+  NOBODY logged on. Still no admin/UAC -- S4U registers for the CURRENT user and
+  stores no password. Invoked by the NSIS installer post-copy.
 #>
 param(
   [Parameter(Mandatory = $true)][string]$InstallDir,
@@ -22,18 +23,108 @@ $wscript = Join-Path $env:WINDIR "System32\wscript.exe"
 # crashes without exposing cmd.exe or PowerShell to the customer.
 $argument = '"' + $taskHost + '" "' + $Mode + '"'
 $Action = New-ScheduledTaskAction -Execute $wscript -Argument $argument -WorkingDirectory $InstallDir
-$Trigger = New-ScheduledTaskTrigger -AtLogOn -User $UserId
+
+# NOT AT LOGON. A store back-office PC reboots itself for Windows Update and
+# nobody signs in for days. With the old -AtLogOn trigger sensing simply stopped
+# until someone logged in, and nothing reported it: the machine is up, the
+# customer sees no error, and we have no coverage.
+#
+# The REPEATING trigger is the load-bearing one, not the boot trigger.
+# Microsoft documents that only a member of the Administrators group can create
+# a task with a boot trigger, and installer.nsi:33 is RequestExecutionLevel
+# user -- so on the supported no-admin path -AtStartup can be refused outright.
+# A -Once trigger with a repetition needs no admin, and under the S4U principal
+# it starts the connector with NOBODY logged on within one interval of a
+# reboot. MultipleInstances IgnoreNew (below) makes every repeat a no-op while
+# the connector is already running, so this costs nothing at steady state.
+$RepeatTrigger = New-ScheduledTaskTrigger -Once -At ((Get-Date).AddMinutes(1)) `
+  -RepetitionInterval (New-TimeSpan -Minutes 5) -RepetitionDuration (New-TimeSpan -Days 3650)
+# The boot trigger is a LATENCY optimisation on top: ~30s after boot instead of
+# up to 5 minutes, for installs that do happen to run elevated. The ladder below
+# DROPS it rather than failing when it is refused.
+$BootTrigger = New-ScheduledTaskTrigger -AtStartup
+# Best-effort: the delay is a nicety, StartWhenAvailable + RestartCount are what
+# actually cover a slow boot. Never let it be the thing that fails registration.
+try { $BootTrigger.Delay = "PT30S" } catch { Write-Warning "Could not set the boot-trigger delay: $($_.Exception.Message)" }
+# Kept as a trigger, not a replacement. It is the fastest re-arm when someone
+# does log on, which is the one thing the old logon-only registration was good at.
+$LogonTrigger = New-ScheduledTaskTrigger -AtLogOn -User $UserId
+
+# MultipleInstances IgnoreNew is load-bearing now that two triggers exist:
+# logging on while the boot instance is running must NOT start a second
+# connector against the same cameras, config and log file.
 $Settings = New-ScheduledTaskSettingsSet -RestartCount 99 -RestartInterval (New-TimeSpan -Minutes 1) `
   -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable `
-  -ExecutionTimeLimit ([TimeSpan]::Zero)   # no time limit — sensing runs continuously
-$Principal = New-ScheduledTaskPrincipal -UserId $UserId -LogonType Interactive -RunLevel Limited
+  -MultipleInstances IgnoreNew `
+  -ExecutionTimeLimit ([TimeSpan]::Zero)   # no time limit -- sensing runs continuously
+
+# WHY S4U AND NOT SYSTEM. S4U ("run whether the user is logged on or not", no
+# stored password) is the only logon type that runs with no interactive session
+# AND keeps the connector inside the SAME user profile. That second half is not
+# a nicety: the device identity, the paired data dir and the ~2.4 GB Gemma model
+# all resolve through os.homedir()/$env:USERPROFILE --
+#   edge-core/src/DeviceIdentity.ts:17   os.homedir()/.trillboards
+#   edge-sdk/src/config.ts:502           dataDir = USERPROFILE/.trillboards
+#   setup-litertlm.ps1:23,25             USERPROFILE/.local/bin, USERPROFILE/.litert-lm
+# Under SYSTEM or NETWORK SERVICE that root becomes
+# C:\Windows\system32\config\systemprofile, so the connector would start at boot,
+# find no device token and no model, and fail while looking alive -- strictly
+# worse than the outage it replaces. SYSTEM also needs admin to register, which
+# would put UAC in front of a deliberately no-admin installer.
+# Password logon is rejected outright: it needs the customer's password at
+# install time and leaves a reusable credential in the task store.
+# S4U's documented limitation is that the token carries no NETWORK credentials.
+# That costs us nothing: the connector only makes unauthenticated-at-the-Windows
+# -layer connections -- outbound TLS to api.trillboards.com, RTSP/ONVIF to LAN
+# cameras (camera creds live in trillboards.config.json, not in the Windows
+# token), a spawned ffmpeg, and loopback to litert-lm on 127.0.0.1.
+function New-ConnectorPrincipal([string]$LogonType) {
+  New-ScheduledTaskPrincipal -UserId $UserId -LogonType $LogonType -RunLevel Limited
+}
 
-Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
-Register-ScheduledTask -TaskName $TaskName -Action $Action -Trigger $Trigger -Settings $Settings `
-  -Principal $Principal -Description "Trillboards Edge - CCTV $Mode connector" | Out-Null
+$Description = "Trillboards Edge - CCTV $Mode connector"
+
+# DEGRADATION LADDER. Each rung drops exactly one capability that a locked-down
+# or non-elevated machine can refuse, in order of how much it costs us. The
+# first rung that registers wins.
+#
+# Measured on windows-latest (run 31836760844), NOT assumed:
+#   elevated   -> rung 1. Both capabilities available.
+#   unelevated -> rung 3. BOTH S4U rungs are refused with "Access is denied",
+#                 because S4U performs a batch logon and Task Scheduler grants
+#                 SeBatchLogonRight only to an administrator CALLER (boot
+#                 triggers are Administrators-only for the same reason).
+# So rung 3 is what a plain no-admin install gets, and it is NOT headless: it
+# still needs somebody logged on. It is nonetheless better than the pre-fix
+# shape, because the repetition revives a connector that died while a user was
+# logged on. ensure-sensing.ps1 asks for the one elevation that lifts a machine
+# from rung 3 to rung 1. Rung 4 exists only so a machine can never be left with
+# NO task at all -- a total sensing outage rather than a degraded one.
+$Attempts = @(
+  @{ Label = "S4U + boot + repeat";      LogonType = "S4U";         Triggers = @($BootTrigger, $RepeatTrigger, $LogonTrigger) },
+  @{ Label = "S4U + repeat";             LogonType = "S4U";         Triggers = @($RepeatTrigger, $LogonTrigger) },
+  @{ Label = "Interactive + repeat";     LogonType = "Interactive"; Triggers = @($RepeatTrigger, $LogonTrigger) },
+  @{ Label = "Interactive + logon only"; LogonType = "Interactive"; Triggers = @($LogonTrigger) }
+)
+
+$Landed = $null
+foreach ($attempt in $Attempts) {
+  Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
+  try {
+    Register-ScheduledTask -TaskName $TaskName -Action $Action -Trigger $attempt.Triggers -Settings $Settings `
+      -Principal (New-ConnectorPrincipal $attempt.LogonType) -Description $Description -ErrorAction Stop | Out-Null
+    $Landed = $attempt
+    break
+  } catch {
+    Write-Host "Registration attempt '$($attempt.Label)' was refused: $($_.Exception.Message)"
+  }
+}
+if (-not $Landed) {
+  throw "Scheduled task '$TaskName' could not be registered in ANY supported shape."
+}
 
 # VERIFY the registration landed instead of trusting Register-ScheduledTask's
-# silence — a silently-missing task is exactly how a real 16-camera install
+# silence -- a silently-missing task is exactly how a real 16-camera install
 # ended up paired with zero frames (the pairing helper then claimed success).
 # Callers (installer.nsi, trillboards-pair.cmd's self-repair) branch on our
 # exit code, so fail LOUDLY here.
@@ -41,4 +132,63 @@ $registered = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinu
 if (-not $registered) {
   throw "Scheduled task '$TaskName' did NOT register (Get-ScheduledTask found nothing)."
 }
-Write-Host "Registered scheduled task '$TaskName' (runs $Mode at logon, restarts on failure)."
+
+# And verify the HEADLESS SHAPE landed, not merely that a task exists. A start
+# path that did not persist is the original defect wearing a new name, and it
+# would be invisible until the next unattended reboot. "Headless" here means two
+# independent things, and BOTH are required: a trigger that fires without anyone
+# logging on (boot or repetition), AND a principal that does not need an
+# interactive session (anything but InteractiveToken).
+$definition = Export-ScheduledTask -TaskName $TaskName
+$logonType = if ($definition -match "<LogonType>([^<]+)</LogonType>") { $Matches[1] } else { "unknown" }
+$hasLogonFreeTrigger = ($definition -match "<BootTrigger>") -or ($definition -match "<Repetition>")
+if (-not $hasLogonFreeTrigger) {
+  # Only the last rung of the ladder can get here.
+  Write-Warning "Scheduled task '$TaskName' registered with a LOGON-ONLY trigger. Sensing will not resume after an unattended reboot until someone signs in."
+}
+if ($logonType -eq "InteractiveToken") {
+  Write-Warning "Scheduled task '$TaskName' registered with an INTERACTIVE principal. Sensing will only run while $UserId is logged on."
+}
+Write-Host "Registered scheduled task '$TaskName' (runs $Mode, shape '$($Landed.Label)', logon type $logonType, restarts on failure)."
+
+# HEADLESS COSTS ONE PRIVILEGE, and that is a Windows rule rather than a choice.
+# Measured on windows-latest (run 31836760844): a standard user registering for
+# ITSELF is refused S4U with "Access is denied". S4U performs a BATCH logon, and
+# Task Scheduler only grants the account SeBatchLogonRight when the CALLER is an
+# administrator; boot triggers are Administrators-only for the same reason. So an
+# unelevated install lands on 'Interactive + repeat' and is NOT headless.
+#
+# This script does NOT prompt for elevation -- it runs from install-update.ps1 and
+# from the connector's own repair path, where a UAC dialog would be wrong or
+# impossible. ensure-sensing.ps1 owns that prompt, at wizard close, once.
+# What we DO here is use elevation when we already have it: repair the model
+# server in the same elevated pass, so one prompt fixes both. The two must be
+# headless TOGETHER -- auto-sense waits on 127.0.0.1:9379, so a headless
+# connector paired with a logon-only model server is a connector that boots and
+# senses nothing.
+function Test-IsElevated {
+  $identity = [System.Security.Principal.WindowsIdentity]::GetCurrent()
+  (New-Object System.Security.Principal.WindowsPrincipal($identity)).IsInRole(
+    [System.Security.Principal.WindowsBuiltInRole]::Administrator)
+}
+
+if (Test-IsElevated) {
+  $litertTask = Get-ScheduledTask -TaskName "TrillboardsLiteRtLm" -ErrorAction SilentlyContinue
+  if ($litertTask) {
+    $litertXml = Export-ScheduledTask -TaskName "TrillboardsLiteRtLm"
+    $litertHeadless = (($litertXml -match "<BootTrigger>") -or ($litertXml -match "<Repetition>")) -and
+      ($litertXml -notmatch "<LogonType>InteractiveToken</LogonType>")
+    if (-not $litertHeadless) {
+      # Recover the interpreter path from the task we are replacing rather than
+      # re-deriving it: setup-litertlm.ps1 resolved it under the USER profile,
+      # and an elevated re-derivation could resolve somewhere else entirely.
+      $litertExe = ($litertTask.Actions | Select-Object -First 1).Execute
+      $litertRegister = Join-Path $InstallDir "bin\register-litertlm-task.ps1"
+      if ($litertExe -and (Test-Path $litertRegister)) {
+        Write-Host "Repairing 'TrillboardsLiteRtLm' in the same elevated pass."
+        try { & $litertRegister -LitertLmPath $litertExe | Out-Null }
+        catch { Write-Warning "Could not repair the model-server task: $($_.Exception.Message)" }
+      }
+    }
+  }
+}

package/deploy/windows/setup-litertlm.ps1

@@ -9,6 +9,15 @@ param(
   [string]$ModelId = "gemma-4-E2B-it.litertlm",
   [string]$HfRepo = "litert-community/gemma-4-E2B-it-litert-lm",
   [string]$LitertPython = $(if ($env:LITERT_LM_PYTHON) { $env:LITERT_LM_PYTHON } else { "3.12" }),
+  # PINNED litert-lm - see deploy/macos/scripts/setup-litertlm.sh for why this is
+  # a correctness pin and not hygiene: the GPU delegate is selected by posting a
+  # "<model-id>,gpu" model id, upstream calls that syntax deprecated, and 0.14.0
+  # removed the parse outright. An unpinned --upgrade lets a customer's per-frame
+  # cost move 1.7-6.6x on a reinstall we did not ship. Kept in lockstep with the
+  # macOS script, LiteRtVlmProvider's LITERT_LM_PINNED_VERSION and
+  # .github/contracts/litert-lm-tested-versions.json by the litert-lm-version-pin
+  # guard.
+  [string]$LitertLmVersion = $(if ($env:LITERT_LM_VERSION) { $env:LITERT_LM_VERSION } else { "0.16.0" }),
   [string]$ModelVersion = $(if ($env:GEMMA_VLM_VERSION) { $env:GEMMA_VLM_VERSION } else { "1.0.0" }),
   [string]$BundledModelPath = "",
   [string]$BundledModelSha256 = "181938105e0eefd105961417e8da75903eacda102c4fce9ce90f50b97139a63c",
@@ -109,19 +118,19 @@ function Test-ServeHealthy {
 
 # WHICH DELEGATE WILL THIS HOST RUN?
 #
-# litert-lm chooses its accelerator by MODEL ID, not by a flag: `serve`
-# advertises its GPU delegate as a SEPARATE id carrying a ",gpu" suffix, and the
-# connector prefers that variant when it is present (LiteRtVlmProvider,
-# accelerator 'auto' - the default).
+# litert-lm chooses its accelerator by MODEL ID, not by a flag: the GPU delegate
+# is selected by posting the imported id with a ",gpu" suffix, and the connector
+# ATTEMPTS that id (LiteRtVlmProvider, accelerator 'auto' - the default).
 #
-# Test-ServeHealthy substring-matches the BARE id, so it passes identically
-# whether or not the GPU variant exists, and no Windows script has ever recorded
-# which ids this host actually advertises. That gap is why a 32-camera field
-# test on connector 0.2.13 could report a CPU-speed result (~2.4 analyses/min)
-# with no way to tell a CPU-only litert-lm build from a GPU-capable one that
-# failed at runtime. The Windows litert-lm runtime is the stock PyPI wheel
-# installed by `uv tool install` (unpinned), so its delegate list is not a fact
-# this repo controls - it has to be OBSERVED, per host.
+# THE MODEL LIST IS NOT THE ANSWER. Measured 2026-08-14 against real serves:
+# litert-lm 0.13.1 lists both ids; 0.14.0 lists one and rejects the ",gpu" POST
+# with 404; 0.16.0 lists one and SERVES the ",gpu" POST on the GPU. So a missing
+# entry means nothing about this host on its own, and the line below used to
+# state flatly that such a machine ran on CPU - which is how a 32-camera field
+# test on connector 0.2.13 reported a CPU-speed result (~2.4 analyses/min) and
+# read it as the product's speed. Log the list, name the version, and let the
+# connector's attempt settle the delegate. installerLocalAiFlow.test.ts asserts
+# that sentence stays gone rather than merely de-prioritised.
 #
 # Never throws: a diagnostic must not be able to fail an install.
 function Get-AdvertisedModelIds {
@@ -145,9 +154,13 @@ function Write-DelegateDiagnostic {
   Log ("delegate: /v1/models advertises " + $ids.Count + " id(s): " + ($ids -join ", "))
   $gpuId = "$ModelId,gpu"
   if ($ids -contains $gpuId) {
-    Log "delegate: GPU variant '$gpuId' IS advertised; the connector will run the GPU delegate"
+    Log "delegate: GPU variant '$gpuId' is listed; the connector attempts it on its first frame"
   } else {
-    Log "delegate: no ',gpu' variant advertised; this host runs the CPU delegate (measured 2.8-6.6x slower per frame)"
+    # NOT a statement about this host. litert-lm 0.15+ omits this entry while
+    # still serving the id (measured on 0.16.0), so the only thing that settles
+    # it is the connector's own attempt, reported on its [sensing] line.
+    Log ("delegate: '$gpuId' is not listed by litert-lm $LitertLmVersion, which does not mean it is unavailable - " +
+      "0.15+ omits the entry and still serves the id. The connector attempts it on its first frame and logs the outcome.")
   }
 }
 
@@ -232,11 +245,48 @@ if (-not [Environment]::Is64BitOperatingSystem) {
   exit 1
 }
 
-if (Test-ServeHealthy) {
+$litertlmCmd = Get-Command litert-lm -ErrorAction SilentlyContinue
+$litertlmPath = if ($litertlmCmd) { $litertlmCmd.Source } else { Join-Path $LocalBin "litert-lm.exe" }
+function Test-LitertLmCli {
+  if (-not (Test-Path -LiteralPath $litertlmPath)) { return $false }
+  try {
+    & $litertlmPath list *> $null
+    return ($LASTEXITCODE -eq 0)
+  } catch {
+    return $false
+  }
+}
+
+function Get-LitertLmVersion {
+  if (-not (Test-Path -LiteralPath $litertlmPath)) { return "" }
+  try {
+    $out = (& $litertlmPath --version 2>$null | Out-String).Trim()
+    if (-not $out) { return "" }
+    return ($out -split '\s+')[-1]
+  } catch {
+    return ""
+  }
+}
+
+# A HEALTHY SERVE IS NOT ENOUGH TO SKIP PROVISIONING.
+#
+# `Test-ServeHealthy` substring-matches the bare model id, and every litert-lm
+# version answers that identically - including the ones that reject the `,gpu`
+# model id the GPU delegate is selected with. So this fast path, which exists to
+# make a repeat run cheap, was also the path that let an already-installed
+# 0.14.0 declare itself ready forever: the hosts that most need the pinned
+# runtime are exactly the ones with a serve already answering. The version is
+# therefore part of the short-circuit condition, not a check further down that a
+# healthy serve never reaches.
+$installedLitertLmVersion = Get-LitertLmVersion
+if ((Test-ServeHealthy) -and ($installedLitertLmVersion -eq $LitertLmVersion)) {
   Complete-Setup
   Stop-SetupLock
   exit 0
 }
+if ((Test-ServeHealthy) -and ($installedLitertLmVersion -ne $LitertLmVersion)) {
+  Log "serve is healthy but litert-lm is $(if ($installedLitertLmVersion) { $installedLitertLmVersion } else { 'unknown' }) not pinned $LitertLmVersion; reinstalling and restarting the serve"
+}
 
 $env:Path = "$LocalBin;$env:Path"
 if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
@@ -253,24 +303,20 @@ if (-not $uvCmd) {
   exit 1
 }
 
-$litertlmCmd = Get-Command litert-lm -ErrorAction SilentlyContinue
-$litertlmPath = if ($litertlmCmd) { $litertlmCmd.Source } else { Join-Path $LocalBin "litert-lm.exe" }
-function Test-LitertLmCli {
-  if (-not (Test-Path -LiteralPath $litertlmPath)) { return $false }
-  try {
-    & $litertlmPath list *> $null
-    return ($LASTEXITCODE -eq 0)
-  } catch {
-    return $false
-  }
-}
-
-if (Test-LitertLmCli) {
-  Log "litert-lm CLI is healthy; keeping current install"
+# The version is part of "healthy". A list-only check kept each machine on
+# whatever it first installed, which is exactly how the accelerator behaviour
+# came to differ between our boxes and every host provisioned after 2026-07-08.
+# Re-read it: uv may have appeared on PATH since the first read above.
+$installedLitertLmVersion = Get-LitertLmVersion
+if ((Test-LitertLmCli) -and ($installedLitertLmVersion -eq $LitertLmVersion)) {
+  Log "litert-lm CLI is healthy at pinned $LitertLmVersion; keeping current install"
 } else {
-  Log "installing or repairing litert-lm with Python $LitertPython"
+  if ($installedLitertLmVersion -and ($installedLitertLmVersion -ne $LitertLmVersion)) {
+    Log "litert-lm $installedLitertLmVersion differs from pinned $LitertLmVersion; reinstalling"
+  }
+  Log "installing or repairing litert-lm==$LitertLmVersion with Python $LitertPython"
   Write-SetupProgress -Stage "local_ai" -Title "Installing local AI" -Message "Installing the local AI engine. Cloud inference remains off." -Phase "installing_runtime" -Percent 10
-  & $uvCmd.Source tool install --python $LitertPython --managed-python --upgrade --force litert-lm *>> $LogPath
+  & $uvCmd.Source tool install --python $LitertPython --managed-python --force "litert-lm==$LitertLmVersion" *>> $LogPath
   $litertlmCmd = Get-Command litert-lm -ErrorAction SilentlyContinue
   $litertlmPath = if ($litertlmCmd) { $litertlmCmd.Source } else { Join-Path $LocalBin "litert-lm.exe" }
   if (-not (Test-LitertLmCli)) {
@@ -279,7 +325,7 @@ if (Test-LitertLmCli) {
     Stop-SetupLock
     exit 1
   }
-  Log "litert-lm CLI repaired successfully"
+  Log "litert-lm CLI repaired successfully at $(Get-LitertLmVersion)"
 }
 
 $bundledModelVerified = $false

package/deploy/windows/stop-existing.ps1

@@ -15,7 +15,7 @@ $rootPrefix = $root + '\'
 # DISABLE BEFORE STOP. register-task.ps1 registers the task with
 # `-RestartCount 99 -RestartInterval 1 minute`, so Stop-ScheduledTask ends the
 # instance as a FAILURE and Task Scheduler relaunches node.exe about a minute
-# later — right inside the installer's bin\ + lib\ move. That is the "reinstall
+# later - right inside the installer's bin\ + lib\ move. That is the "reinstall
 # hit a locked node.exe" the field test saw. Disabling suppresses the restart
 # AND the AtLogOn trigger for the whole swap window; install-update.ps1 owns
 # re-enabling it on every exit path, and the uninstaller deletes the task.
@@ -25,7 +25,7 @@ Start-Sleep -Milliseconds 750
 
 function Get-TrillboardsEdgeProcesses {
   # The process that actually holds bin\node.exe open is node.exe itself, and
-  # its command line names NONE of these scripts — it names the cli.js entry.
+  # its command line names NONE of these scripts - it names the cli.js entry.
   # Win32_Process.ExecutablePath is empty across a 32/64-bit boundary, and then
   # the marker list is the only matcher left, so it has to cover the runtime.
   $markers = @(