@trillboards/edge-sdk 0.2.19 → 0.2.20

package/deploy/windows/README.md

@@ -93,3 +93,44 @@ stable download URL never changes while field tests remain artifact-verifiable.
 - The legacy `install-service.ps1` (local-inference: requires system Node + npm
   install + ONNX models + a hand-edited deviceToken) is a different, older path.
   This local-first installer supersedes it for BYO-CCTV onboarding.
+
+## Auto-update (since 0.2.20)
+
+An installed connector keeps itself current. It is the only consumer of
+`trillboards-connector-windows.version.json`, which until now was published,
+correct, and read by nothing.
+
+- **Check** — `src/connectorUpdate.ts` reads the manifest every 6 h (first check
+  60 s after start, so a PC that reboots nightly still reports) and posts the
+  running version plus the advertised one to
+  `POST /v2/earner/cameras/connector-status`. A MISSING manifest answers
+  `HTTP 200 text/html` on this CDN, so the client validates every field rather
+  than the status code, and an unreadable manifest reports UNKNOWN — never
+  "up to date".
+- **Payload** — a code-only `bin\` + `lib\` zip, a small fraction of the 2.6 GB
+  customer installer, because the ~2.4 GB Gemma weights already have their own
+  hourly SHA-256-verified OTA channel. The release step prints the measured size;
+  the macOS equivalent measured 207 MB of a 2.27 GB pkg. Published under a
+  content-addressed prefix so a cached payload can never disagree with its
+  catalog.
+- **Verify** — `apply-update.ps1 -Stage` checks the Authenticode signature AND
+  the signer CN of a signed catalog, binds it to the manifest's version, then
+  checks the payload's size and SHA-256 against it, then that every executable
+  in the expanded tree is signed. The signed `.ps1` catalog exists because a
+  `.zip` and a `.json` cannot carry Authenticode, and a hash arriving over the
+  channel it protects is a corruption check, not an authenticity check.
+- **Apply** — `apply-update.ps1 -Commit` hands the swap to `install-update.ps1`
+  unchanged. The connector picks the moment: it waits until it holds no
+  in-flight analysis and no flagged frames, because `stop()` discards held
+  candidates. After 2 h without a quiet moment it applies anyway and records
+  which branch it took.
+- **Task shape** — re-registration produces the best shape the CALLER can make,
+  and a headless S4U/boot shape needs an elevated caller. The applier probes
+  first and REFUSES the update rather than silently returning a headless machine
+  to logon-only; it also re-classifies and restores after the swap.
+
+Outcomes land in `<install>\.auto-update\outcome.json` and are reported on the
+next start, so a refused update is visible instead of a machine that quietly
+stopped receiving fixes. Proved on `windows-latest` by
+`ci/verify-update-applier.ps1`, where every negative arm carries a control that
+must fire. Full detail: `docs/runbooks/cctv-connector-windows-gtm-readiness.md` §5.

package/deploy/windows/apply-update.ps1

@@ -0,0 +1,530 @@
+<#
+.SYNOPSIS
+  apply-update.ps1 - download, VERIFY, and apply a connector update in the field.
+
+.DESCRIPTION
+  The half the product was missing. Every release publishes a signed installer
+  and a version manifest to the CDN, and nothing read either: a field fix
+  reached a customer only when that customer re-downloaded 2.6 GB and re-ran the
+  installer by hand. The connector now reads the manifest (see
+  src/connectorUpdate.ts) and drives THIS script when it finds itself behind.
+
+  Two phases, because a store's uplink is slow and sensing must not stop while
+  bytes are moving:
+
+    -Stage    download + verify + extract, with the connector still running and
+              still sensing. Touches nothing in the live install. Ends by
+              writing staged.json, which is the connector's signal that a
+              verified tree is on disk and waiting.
+    -Commit   swap it in. Called only after the connector has decided it is at a
+              safe point, and only ever by a connector that is about to exit.
+
+  ==========================================================================
+  WHAT IS VERIFIED BEFORE ANY BYTE IS APPLIED, AND WHY IN THIS ORDER
+  ==========================================================================
+  An updater that installs an unverified payload is a remote-code-execution
+  channel into every customer's store. So the payload is not trusted because it
+  came from our CDN - it is trusted because Microsoft's root CA says we signed
+  it.
+
+  1. AUTHENTICODE on the catalog. `Get-AuthenticodeSignature` must return
+     Valid AND the signer subject must be the expected publisher. Status alone
+     is not enough: a certificate minted by anyone and installed in the
+     machine's trusted roots also returns Valid, so the SUBJECT is what pins
+     this to us. Both halves have a control in CI that must fail.
+  2. VERSION BINDING. The catalog names the version it describes and it must
+     equal the version the manifest advertised. Without this, a catalog+payload
+     pair from an older release could be replayed against a newer manifest.
+  3. SIZE, then SHA-256, of the payload archive against the catalog. The catalog
+     is signed and the archive is not, so this is the step that extends
+     Authenticode's guarantee over every byte of the payload - including
+     lib\edge-sdk\dist\cli.js, which is the code that matters most and which
+     cannot carry a signature of its own.
+
+  Why a signed CATALOG rather than the manifest's own sha256: the manifest is
+  plain JSON on the same channel as the payload, so an attacker who can serve
+  one can serve the other. A hash that arrives over the channel it is meant to
+  protect is a CORRUPTION check, not an authenticity check. A .ps1 can carry
+  Authenticode; a .json and a .zip cannot.
+
+  4. INNER SIGNATURES. Every .ps1/.vbs and ffmpeg.exe in the extracted tree, and
+     node.exe's vendor signature, must be Valid. The hash above already proves
+     the archive is the one we built, so this cannot catch an attacker - it
+     catches US, if a build ever regresses and ships an unsigned script that
+     would then fail to run on a customer under GPO AllSigned.
+
+  ==========================================================================
+  WHAT IS DELIBERATELY NOT REINVENTED
+  ==========================================================================
+  The swap itself is install-update.ps1, unchanged. It already solves the hard
+  parts, all of them incident-derived: stop-existing.ps1 DISABLES the task
+  before stopping it (a task registered -RestartCount 99 otherwise relaunches
+  node.exe straight into the middle of the swap), Assert-BinariesUnlocked proves
+  node.exe and ffmpeg.exe are WRITABLE rather than merely process-free (an AV
+  scanner holding a handle is caught before the installer commits), the task is
+  re-enabled on EVERY exit path, and bin/lib roll back from .previous on
+  failure. This script calls it and adds nothing to it.
+
+  ==========================================================================
+  THE ONE THING THIS SCRIPT ADDS TO THE SWAP: A TASK-SHAPE GUARD
+  ==========================================================================
+  install-update.ps1 re-registers the scheduled task by running the NEW payload's
+  register-task.ps1 - which is correct, because the new version's registration
+  logic is the one that should win. But register-task.ps1 registers the best
+  shape THE CALLER CAN CREATE, and a headless (S4U / boot-triggered) shape can
+  only be created by a caller that is BOTH elevated AND the account itself.
+  This script runs from the connector's own task, which is RunLevel Limited. So
+  a machine whose owner accepted one UAC prompt to become headless would be
+  silently re-registered logon-only by an unattended update - and the loss would
+  not be visible until the next unattended reboot, days later, with the machine
+  up and no error anywhere.
+
+  So, before the swap: if the CURRENT task is headless, register a throwaway
+  probe task carrying the same principal (and boot trigger, when present). If
+  the probe is refused, re-registration would downgrade this machine, and the
+  update is REJECTED rather than applied. Nothing is touched; the connector
+  stays on the older version and the server is told exactly why. After the swap
+  the shape is re-classified anyway and restored from the captured definition if
+  it moved - belt as well as braces, because the probe predicts and the
+  re-classification measures.
+
+  The probe task is registered DISABLED-by-construction (no trigger it can fire
+  during the probe, an inert action) and removed in a finally.
+
+.OUTPUTS
+  Exit 0 on success. Non-zero on any failure. Every terminal state also writes
+  <InstallDir>\.auto-update\outcome.json, which the connector reads on its next
+  start and reports to the server - so a failed update is visible in the fleet
+  view rather than being a machine that quietly stopped receiving fixes.
+#>
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true)][string]$InstallDir,
+  [switch]$Stage,
+  [switch]$Commit,
+  # Stage-phase inputs, all read from the published manifest by the connector.
+  [string]$UpdateUrl,
+  [string]$CatalogUrl,
+  [string]$ExpectedVersion,
+  [string]$CurrentVersion,
+  # The publisher every shipped Trillboards artifact carries. Overridable ONLY so
+  # CI can prove the check with a throwaway certificate; a static test asserts
+  # this default, so a CI harness can never prove the wrong publisher.
+  [string]$ExpectedSigner = 'Aethercorp Inc',
+  # Escape hatch for the CI control that must FAIL: with this set, a degraded
+  # task shape is measured and reported but not repaired. Never set in the field.
+  [switch]$SkipTaskShapeRestore
+)
+
+$ErrorActionPreference = 'Stop'
+# Invoke-WebRequest renders a progress bar per chunk in Windows PowerShell 5.1,
+# which dominates the wall time of a 200 MB download on a slow uplink.
+$ProgressPreference = 'SilentlyContinue'
+
+$TaskName = 'TrillboardsEdge'
+$ProbeTaskName = 'TrillboardsEdgeUpdateProbe'
+$UpdateDir = Join-Path $InstallDir '.auto-update'
+$PayloadDir = Join-Path $UpdateDir 'payload'
+$ArchivePath = Join-Path $UpdateDir 'payload.zip'
+$CatalogPath = Join-Path $UpdateDir 'catalog.ps1'
+$StagedMarker = Join-Path $UpdateDir 'staged.json'
+$OutcomePath = Join-Path $UpdateDir 'outcome.json'
+$AttemptedAt = (Get-Date).ToUniversalTime().ToString('o')
+
+function Log([string]$Message) { Write-Host "[apply-update] $Message" }
+
+<#
+  Write the terminal state, atomically, then leave. The connector reads this on
+  its next start; a torn file would be read as a malformed outcome and dropped,
+  so tmp+rename rather than a direct write.
+
+  Vocabulary, and it is load-bearing because the server persists it:
+    rejected - we refused. NOTHING was changed. Hash, signature, disk, or a
+               swap that would have downgraded the task shape.
+    failed   - we tried and the transaction did not complete. install-update.ps1
+               rolled back, or the shape moved and could not be restored.
+    success  - the new version is live and the task shape is intact.
+#>
+function Write-Outcome([string]$Result, [string]$Detail) {
+  try {
+    if (-not (Test-Path -LiteralPath $UpdateDir)) {
+      New-Item -ItemType Directory -Force -Path $UpdateDir | Out-Null
+    }
+    $outcome = [ordered]@{
+      attemptedAt = $AttemptedAt
+      fromVersion = $CurrentVersion
+      toVersion   = $ExpectedVersion
+      result      = $Result
+      detail      = $Detail
+    }
+    $json = $outcome | ConvertTo-Json -Compress
+    $tmp = "$OutcomePath.tmp"
+    [System.IO.File]::WriteAllText($tmp, $json, (New-Object System.Text.UTF8Encoding($false)))
+    Move-Item -LiteralPath $tmp -Destination $OutcomePath -Force
+  } catch {
+    Log "could not record the outcome: $($_.Exception.Message)"
+  }
+}
+
+function Fail([string]$Result, [string]$Detail) {
+  Log "$Result - $Detail"
+  Write-Outcome $Result $Detail
+  exit 1
+}
+
+<#
+  Free space on the volume the install lives on.
+
+  Get-PSDrive rather than wmic: `wmic` is REMOVED on recent Windows 11, and the
+  connector's own diagnose path already had to grow a Get-PSDrive fallback for
+  exactly that. Returns $null when it cannot be measured, and the caller treats
+  "cannot measure" as "do not proceed" - a preflight that passes because it
+  could not look is the disk check that reported `pass` on a full disk.
+#>
+function Get-FreeBytes([string]$Path) {
+  try {
+    $qualifier = Split-Path -Qualifier ([System.IO.Path]::GetFullPath($Path))
+    $drive = Get-PSDrive -Name $qualifier.TrimEnd(':') -ErrorAction Stop
+    if ($null -eq $drive.Free) { return $null }
+    return [int64]$drive.Free
+  } catch {
+    return $null
+  }
+}
+
+function Assert-SignedBy([string]$Path, [string]$Subject, [string]$What) {
+  $sig = Get-AuthenticodeSignature -LiteralPath $Path
+  if ($sig.Status -ne 'Valid') {
+    Fail 'rejected' "$What signature is not Valid (status $($sig.Status)): $($sig.StatusMessage)"
+  }
+  $signer = ''
+  if ($sig.SignerCertificate) { $signer = [string]$sig.SignerCertificate.Subject }
+  # Match the CN specifically. A substring match anywhere in the subject would
+  # accept a certificate that merely mentions the name in its O or OU.
+  if ($signer -notmatch ("(^|,)\s*CN=" + [regex]::Escape($Subject) + "\s*(,|$)")) {
+    Fail 'rejected' "$What is signed by an unexpected publisher: '$signer'"
+  }
+  Log "$What signature OK (Valid, CN=$Subject)"
+}
+
+# ---------------------------------------------------------------------------
+# STAGE
+# ---------------------------------------------------------------------------
+function Invoke-Stage {
+  if ([string]::IsNullOrWhiteSpace($UpdateUrl)) { Fail 'rejected' '-UpdateUrl is required to stage' }
+  if ([string]::IsNullOrWhiteSpace($CatalogUrl)) { Fail 'rejected' '-CatalogUrl is required to stage' }
+  if ([string]::IsNullOrWhiteSpace($ExpectedVersion)) { Fail 'rejected' '-ExpectedVersion is required to stage' }
+
+  # Clear the previous attempt's working files but KEEP outcome.json. The
+  # connector reports that record on its next start, and a report can fail
+  # (offline, rotated token); wiping it here would erase the only evidence that
+  # an update was ever refused on this machine.
+  New-Item -ItemType Directory -Force -Path $UpdateDir | Out-Null
+  foreach ($stale in @($PayloadDir, $ArchivePath, $CatalogPath, $StagedMarker)) {
+    if (Test-Path -LiteralPath $stale) { Remove-Item -LiteralPath $stale -Recurse -Force }
+  }
+
+  Log "fetching the update catalog: $CatalogUrl"
+  try {
+    Invoke-WebRequest -Uri $CatalogUrl -OutFile $CatalogPath -UseBasicParsing -TimeoutSec 60
+  } catch {
+    Fail 'rejected' "could not fetch the update catalog: $($_.Exception.Message)"
+  }
+
+  Assert-SignedBy $CatalogPath $ExpectedSigner 'update catalog'
+
+  # PARSED, never executed. The signature covers these bytes, so reading them is
+  # safe - but running a downloaded script to learn a hash would give the
+  # catalog far more authority than it needs, and there is nothing in it that
+  # requires an interpreter.
+  $catalogText = [System.IO.File]::ReadAllText($CatalogPath)
+  $mVersion = [regex]::Match($catalogText, "(?m)^\s*\`$TrillboardsUpdateVersion\s*=\s*'([^']+)'")
+  $mSha = [regex]::Match($catalogText, "(?m)^\s*\`$TrillboardsUpdateSha256\s*=\s*'([0-9a-f]{64})'")
+  $mSize = [regex]::Match($catalogText, "(?m)^\s*\`$TrillboardsUpdateSizeBytes\s*=\s*(\d+)")
+  if (-not ($mVersion.Success -and $mSha.Success -and $mSize.Success)) {
+    Fail 'rejected' 'the update catalog is signed but does not declare version, sha256 and sizeBytes'
+  }
+  $catalogVersion = $mVersion.Groups[1].Value
+  $catalogSha = $mSha.Groups[1].Value
+  $catalogSize = [int64]$mSize.Groups[1].Value
+
+  if ($catalogVersion -ne $ExpectedVersion) {
+    Fail 'rejected' "catalog describes $catalogVersion but the manifest advertised $ExpectedVersion"
+  }
+  if ($catalogSize -le 0) { Fail 'rejected' 'the catalog declares a non-positive payload size' }
+
+  # Preflight against REAL free space, before a single payload byte is written.
+  # x3: the archive, its expansion, and headroom for the .previous copy the swap
+  # keeps for rollback. Refusing here leaves a machine that is merely stale;
+  # discovering it mid-download leaves a machine that is stale AND full.
+  $required = $catalogSize * 3
+  $free = Get-FreeBytes $InstallDir
+  if ($null -eq $free) { Fail 'rejected' 'could not measure free disk space' }
+  if ($free -lt $required) {
+    Fail 'rejected' ("not enough free disk space: need {0} MB, have {1} MB" -f [math]::Round($required / 1MB), [math]::Round($free / 1MB))
+  }
+  Log ("disk preflight OK: need {0} MB, have {1} MB" -f [math]::Round($required / 1MB), [math]::Round($free / 1MB))
+
+  Log "downloading the update payload: $UpdateUrl"
+  try {
+    Invoke-WebRequest -Uri $UpdateUrl -OutFile $ArchivePath -UseBasicParsing -TimeoutSec 3600
+  } catch {
+    # A disk that fills DURING the download lands here, and the partial file
+    # must not survive: a resumed or retried run would otherwise hash a
+    # truncated archive against a full-length expectation forever.
+    Remove-Item -LiteralPath $ArchivePath -Force -ErrorAction SilentlyContinue
+    Fail 'rejected' "could not download the update payload: $($_.Exception.Message)"
+  }
+
+  $actualSize = (Get-Item -LiteralPath $ArchivePath).Length
+  if ($actualSize -ne $catalogSize) {
+    Remove-Item -LiteralPath $ArchivePath -Force -ErrorAction SilentlyContinue
+    Fail 'rejected' "payload size mismatch: expected $catalogSize bytes, got $actualSize"
+  }
+  $actualSha = (Get-FileHash -LiteralPath $ArchivePath -Algorithm SHA256).Hash.ToLowerInvariant()
+  if ($actualSha -ne $catalogSha) {
+    Remove-Item -LiteralPath $ArchivePath -Force -ErrorAction SilentlyContinue
+    Fail 'rejected' "payload SHA-256 mismatch: expected $catalogSha, got $actualSha"
+  }
+  Log "payload verified: $actualSize bytes, sha256 $actualSha"
+
+  Add-Type -AssemblyName System.IO.Compression.FileSystem
+  try {
+    [System.IO.Compression.ZipFile]::ExtractToDirectory($ArchivePath, $PayloadDir)
+  } catch {
+    Fail 'rejected' "could not expand the update payload: $($_.Exception.Message)"
+  }
+  Remove-Item -LiteralPath $ArchivePath -Force -ErrorAction SilentlyContinue
+
+  foreach ($rel in @('bin\node.exe', 'bin\install-update.ps1', 'bin\stop-existing.ps1', 'bin\register-task.ps1', 'lib\edge-sdk\dist\cli.js')) {
+    if (-not (Test-Path -LiteralPath (Join-Path $PayloadDir $rel))) {
+      Fail 'rejected' "the expanded payload is missing $rel"
+    }
+  }
+
+  Assert-PayloadSignatures $PayloadDir
+
+  # LAST, and atomically. staged.json is the connector's only signal that a
+  # verified tree is waiting, so it must be impossible for a half-staged tree to
+  # look ready.
+  $staged = [ordered]@{
+    version  = $ExpectedVersion
+    sha256   = $catalogSha
+    stagedAt = (Get-Date).ToUniversalTime().ToString('o')
+  } | ConvertTo-Json -Compress
+  $tmp = "$StagedMarker.tmp"
+  [System.IO.File]::WriteAllText($tmp, $staged, (New-Object System.Text.UTF8Encoding($false)))
+  Move-Item -LiteralPath $tmp -Destination $StagedMarker -Force
+  Log "staged $ExpectedVersion - waiting for the connector to reach a safe point"
+}
+
+<#
+  Every executable in the staged tree carries a Valid signature.
+
+  This cannot stop an attacker - the archive hash already did that - and it is
+  not here for one. It stops US shipping a tree that a customer under GPO
+  AllSigned could not run: an unsigned .ps1 in the payload would install fine
+  and then fail at every logon, silently, on exactly the managed estates the
+  signing work was done for.
+
+  node.exe is checked but NOT expected to carry our publisher: it keeps the
+  OpenJS Foundation's signature on purpose, because re-signing it would replace
+  the vendor's provenance with ours.
+#>
+function Assert-PayloadSignatures([string]$Root) {
+  $bad = 0
+  $checked = 0
+  $files = Get-ChildItem -LiteralPath (Join-Path $Root 'bin') -File -ErrorAction SilentlyContinue |
+    Where-Object { $_.Extension -in @('.ps1', '.vbs', '.exe') }
+  foreach ($f in $files) {
+    $checked++
+    $sig = Get-AuthenticodeSignature -LiteralPath $f.FullName
+    if ($sig.Status -ne 'Valid') {
+      $bad++
+      Log "  UNSIGNED OR INVALID: $($f.Name) ($($sig.Status))"
+    }
+  }
+  # A derivation that found nothing must fail rather than pass silently - the
+  # shipped bin\ carries at least the eight .ps1, three .vbs and two .exe the
+  # release signs, so a count this low means the tree is not what we think.
+  if ($checked -lt 10) {
+    Fail 'rejected' "only $checked executable artifact(s) found in the staged bin\ - the payload is not the shipped shape"
+  }
+  if ($bad -gt 0) {
+    Fail 'rejected' "$bad of $checked executable artifact(s) in the staged payload are unsigned or invalid"
+  }
+  Log "all $checked executable artifacts in the staged payload are signed"
+}
+
+# ---------------------------------------------------------------------------
+# TASK SHAPE
+# ---------------------------------------------------------------------------
+<#
+  Classify the registered task the way the product cares about it.
+
+  "Headless" is TWO independent properties and it needs both: a trigger that
+  fires with nobody logged on (a boot trigger or a repetition), AND a principal
+  that does not need an interactive session. Either one alone still waits for a
+  human to sign in.
+#>
+function Get-TaskShape([string]$Name) {
+  $task = Get-ScheduledTask -TaskName $Name -ErrorAction SilentlyContinue
+  if (-not $task) { return $null }
+  $xml = Export-ScheduledTask -TaskName $Name
+  $logonType = 'unknown'
+  $m = [regex]::Match($xml, '<LogonType>([^<]+)</LogonType>')
+  if ($m.Success) { $logonType = $m.Groups[1].Value }
+  $userId = ''
+  $mu = [regex]::Match($xml, '<Principal[^>]*>\s*<UserId>([^<]+)</UserId>')
+  if (-not $mu.Success) { $mu = [regex]::Match($xml, '<UserId>([^<]+)</UserId>') }
+  if ($mu.Success) { $userId = $mu.Groups[1].Value }
+  $hasBoot = $xml -match '<BootTrigger>'
+  $hasRepetition = $xml -match '<Repetition>'
+  return [pscustomobject]@{
+    Xml            = $xml
+    LogonType      = $logonType
+    UserId         = $userId
+    HasBootTrigger = [bool]$hasBoot
+    LogonFree      = [bool]($hasBoot -or $hasRepetition)
+    NonInteractive = ($logonType -ne 'InteractiveToken')
+    Headless       = ([bool]($hasBoot -or $hasRepetition)) -and ($logonType -ne 'InteractiveToken')
+  }
+}
+
+function Format-TaskShape($Shape) {
+  if ($null -eq $Shape) { return 'absent' }
+  return ("logonType=$($Shape.LogonType) logonFreeTrigger=$($Shape.LogonFree) headless=$($Shape.Headless)")
+}
+
+<#
+  Can THIS caller still create the shape this machine already has?
+
+  Registers a throwaway task with the same principal, and the boot trigger when
+  the current shape has one, then deletes it. It cannot fire while it exists: a
+  boot trigger needs a boot, and when the current shape has none the probe is
+  registered with NO trigger at all. The action is inert regardless.
+
+  Returns $true when the probe landed, $false when Windows refused it.
+#>
+function Test-CanRegisterShape($Shape) {
+  if ($null -eq $Shape) { return $true }
+  $triggers = @()
+  if ($Shape.HasBootTrigger) { $triggers = @(New-ScheduledTaskTrigger -AtStartup) }
+  $userId = $Shape.UserId
+  if ([string]::IsNullOrWhiteSpace($userId)) {
+    $userId = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
+  }
+  # InteractiveToken is what Export writes; the cmdlet spells it 'Interactive'.
+  $logonType = $Shape.LogonType
+  if ($logonType -eq 'InteractiveToken') { $logonType = 'Interactive' }
+  try {
+    Unregister-ScheduledTask -TaskName $ProbeTaskName -Confirm:$false -ErrorAction SilentlyContinue
+    $action = New-ScheduledTaskAction -Execute (Join-Path $env:WINDIR 'System32\cmd.exe') -Argument '/c exit'
+    $principal = New-ScheduledTaskPrincipal -UserId $userId -LogonType $logonType -RunLevel Limited
+    if ($triggers.Count -gt 0) {
+      Register-ScheduledTask -TaskName $ProbeTaskName -Action $action -Trigger $triggers `
+        -Principal $principal -Description 'Trillboards update pre-flight probe' -ErrorAction Stop | Out-Null
+    } else {
+      Register-ScheduledTask -TaskName $ProbeTaskName -Action $action `
+        -Principal $principal -Description 'Trillboards update pre-flight probe' -ErrorAction Stop | Out-Null
+    }
+    return $true
+  } catch {
+    Log "task-shape probe refused: $($_.Exception.Message)"
+    return $false
+  } finally {
+    Unregister-ScheduledTask -TaskName $ProbeTaskName -Confirm:$false -ErrorAction SilentlyContinue
+  }
+}
+
+# ---------------------------------------------------------------------------
+# COMMIT
+# ---------------------------------------------------------------------------
+function Invoke-Commit {
+  if (-not (Test-Path -LiteralPath $StagedMarker)) {
+    Fail 'rejected' 'no staged update is present'
+  }
+  $staged = $null
+  try {
+    $staged = Get-Content -LiteralPath $StagedMarker -Raw | ConvertFrom-Json
+  } catch {
+    Fail 'rejected' 'the staged marker is unreadable'
+  }
+  if (-not $staged.version) { Fail 'rejected' 'the staged marker names no version' }
+  if ($ExpectedVersion -and $staged.version -ne $ExpectedVersion) {
+    Fail 'rejected' "staged $($staged.version) but was asked to commit $ExpectedVersion"
+  }
+  if (-not $ExpectedVersion) { $script:ExpectedVersion = $staged.version }
+  if (-not (Test-Path -LiteralPath (Join-Path $PayloadDir 'bin\install-update.ps1'))) {
+    Fail 'rejected' 'the staged payload is gone'
+  }
+
+  $before = Get-TaskShape $TaskName
+  Log "task shape before: $(Format-TaskShape $before)"
+
+  # The predictive half. Only a machine that HAS a headless shape has one to
+  # lose, so a logon-only install skips the probe entirely and updates freely.
+  if ($null -ne $before -and $before.Headless) {
+    if (-not (Test-CanRegisterShape $before)) {
+      Fail 'rejected' 'applying this update would re-register the scheduled task logon-only, and this machine is currently headless'
+    }
+    Log 'task-shape probe OK - the headless shape can be re-created by this caller'
+  }
+
+  # Close the relaunch race before it can happen. The connector exits 0 to hand
+  # us the machine, and a task carrying a repetition trigger can start a fresh
+  # one in the seconds it takes install-update.ps1 to validate the staged tree -
+  # which then holds bin\node.exe open and turns a healthy update into a
+  # rollback. stop-existing.ps1 disables the task too, but only AFTER that
+  # validation, so the window exists. Nothing between here and the call can
+  # fail without install-update.ps1 having run, and that script re-enables the
+  # task on every one of its exit paths.
+  Disable-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue | Out-Null
+
+  $installUpdate = Join-Path $PayloadDir 'bin\install-update.ps1'
+  try {
+    # install-update.ps1 owns the whole swap transaction, including disabling the
+    # task before stopping it, proving the binaries are writable, the .previous
+    # rollback, and re-enabling the task on every exit path. It throws on
+    # failure and $ErrorActionPreference = 'Stop' turns that into ours.
+    & $installUpdate -InstallDir $InstallDir -StagingDir $PayloadDir
+  } catch {
+    Fail 'failed' "the swap failed and the previous version was restored: $($_.Exception.Message)"
+  }
+
+  # The measured half. The probe predicts; this observes.
+  $after = Get-TaskShape $TaskName
+  Log "task shape after: $(Format-TaskShape $after)"
+  $degraded = ($null -ne $before -and $before.Headless -and (($null -eq $after) -or (-not $after.Headless)))
+  if ($degraded -and -not $SkipTaskShapeRestore) {
+    Log 'the swap left a NON-headless task - restoring the captured definition'
+    try {
+      Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
+      Register-ScheduledTask -TaskName $TaskName -Xml $before.Xml -ErrorAction Stop | Out-Null
+    } catch {
+      Log "restore failed: $($_.Exception.Message)"
+    }
+    $after = Get-TaskShape $TaskName
+    Log "task shape after restore: $(Format-TaskShape $after)"
+    $degraded = ($null -eq $after) -or (-not $after.Headless)
+  }
+
+  Remove-Item -LiteralPath $StagedMarker -Force -ErrorAction SilentlyContinue
+  Remove-Item -LiteralPath $PayloadDir -Recurse -Force -ErrorAction SilentlyContinue
+
+  if ($degraded) {
+    # The code IS updated, so this is not a rollback case - but the machine is
+    # now worse in a way that only shows up at the next unattended reboot, which
+    # is precisely the class of failure that must never be silent.
+    Fail 'failed' 'the update applied but the scheduled task is no longer headless'
+  }
+
+  Write-Outcome 'success' $null
+  Log "updated to $ExpectedVersion"
+}
+
+# ---------------------------------------------------------------------------
+if ($Stage -and $Commit) { Fail 'rejected' 'pass exactly one of -Stage or -Commit' }
+if ($Stage) { Invoke-Stage; exit 0 }
+if ($Commit) { Invoke-Commit; exit 0 }
+Fail 'rejected' 'pass -Stage or -Commit'

package/deploy/windows/build-windows.ps1

@@ -204,6 +204,10 @@ Copy-Item -Force "$Here\run-connector.ps1"      "$Payload\bin\run-connector.ps1"
 Copy-Item -Force "$Here\register-task.ps1"    "$Payload\bin\register-task.ps1"
 Copy-Item -Force "$Here\stop-existing.ps1"    "$Payload\bin\stop-existing.ps1"
 Copy-Item -Force "$Here\install-update.ps1"    "$Payload\bin\install-update.ps1"
+# The in-field updater. Ships in bin\ so an INSTALLED connector can drive its own
+# replacement; being here is also what puts it in the Authenticode signing set,
+# which list-shipped-scripts.ps1 derives from these Copy-Item calls.
+Copy-Item -Force "$Here\apply-update.ps1"      "$Payload\bin\apply-update.ps1"
 
 # Construct the real customer window with Windows PowerShell before packaging.
 # -SmokeTest creates and validates every control but never displays the form or
@@ -249,4 +253,12 @@ Log "Built: $out ($sizeMb MB)"
 # failed downstream on `Test-Path $null` with a misleading error. GITHUB_OUTPUT
 # is unambiguous and survives stream pollution.
 if ($env:GITHUB_OUTPUT) { "exe=$out" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append }
+# The staged tree is ALSO the auto-update payload: bin\ + lib\ is exactly the
+# shape install-update.ps1 takes as its -StagingDir, and it carries no Gemma
+# weights - those have their own hourly, SHA-256-verified OTA channel. The
+# release job zips this and publishes it beside the manifest so a field fix does
+# not cost every store 2.6 GB. The exact ratio is MEASURED and printed by the
+# release step rather than asserted here; the macOS equivalent measured 207 MB
+# of a 2.27 GB pkg (9.1%), which is the order to expect, not a Windows number.
+if ($env:GITHUB_OUTPUT) { "payload=$Payload" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append }
 Write-Output $out