@trillboards/edge-sdk 0.2.104 → 0.2.107

package/deploy/systemd/setup-detector.sh

@@ -23,6 +23,10 @@ LOCAL_BIN="$USER_HOME/.local/bin"
 SERVE_PORT="${TRILLBOARDS_DETECTOR_PORT:-9380}"
 SERVE_UNIT="trillboards-detector"
 DETECTOR_PYTHON="${TRILLBOARDS_DETECTOR_PYTHON:-3.12}"
+# The environment file BOTH units declare (`EnvironmentFile=-/etc/trillboards/env`).
+# Overridable like the four settings above it, and for the same reason those are:
+# so this script can be RUN in a test rather than only read by one.
+ENV_FILE="${TRILLBOARDS_ENV_FILE:-/etc/trillboards/env}"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd || echo .)"
 
 mkdir -p "$LOG_DIR" 2>/dev/null || LOG_DIR="$USER_HOME/.trillboards-logs"
@@ -75,6 +79,73 @@ DETECTOR="$LOCAL_BIN/trillboards-detector"
 [ -x "$DETECTOR" ] || { log "ERROR: trillboards-detector binary missing after install"; exit 0; }
 log "trillboards-detector installed at $DETECTOR"
 
+# ── THE RAM CEILING ─────────────────────────────────────────────────────────
+#
+# Without this the detector holds its pinned model and REFUSES to make any
+# second model resident — `registry.py::_admit`, "no RAM ceiling was injected,
+# so this service has no basis for a portfolio decision and will not invent
+# one". That refusal is correct and stays; what was missing is the injection.
+# Measured on a live GCE connector 2026-08-26: every delivered specialist sat
+# permanently `idle` and `POST /detect` answered 503 naming exactly this.
+#
+# THE ENVIRONMENT FILE, not the ExecStart line, because on this platform the
+# unit is a STATIC file `install.sh` copies verbatim — there is nothing to
+# template. Both units already declare `EnvironmentFile=-/etc/trillboards/env`
+# and nothing has ever written it. macOS and Windows take the same number as a
+# `--ram-budget-mb` argument instead, because their supervisor definitions ARE
+# generated by their setup scripts. One derivation, three transports.
+#
+# REWRITTEN ON EVERY RUN: the box's memory can change (a VM resize, a stick
+# added) and so can the committed reservations, so an upgrade must re-derive
+# rather than inherit. A run that CANNOT derive leaves an existing line alone —
+# it was derived from this same box — and injects nothing new, which leaves the
+# service in its existing honest refusal rather than acting on a guess.
+#
+# ONLY THE CEILING GOES IN THIS FILE. Assignments from `EnvironmentFile=`
+# OUTRANK a unit's own `Environment=` — measured on systemd 252 with the two
+# directives in both orders, the file wins either way — so anything written here
+# silently beats the units. That is harmless for a value the units do not set,
+# and it is a fresh outage for one they do: a `TRILLBOARDS_DATA_DIR` line here
+# would move the connector's state root out of `ReadWritePaths=`, which is a
+# literal and cannot follow a variable. Do not add one.
+inject_ram_ceiling() {
+  local budget_script env_file tmp_file budget
+  env_file="$ENV_FILE"
+  budget_script="$SOURCE/ram-budget.js"
+
+  command -v node >/dev/null 2>&1 || {
+    log "WARN: node not found, so no RAM ceiling is derived; the detector will hold its pinned model and refuse a second one"
+    return 0
+  }
+  [ -f "$budget_script" ] || {
+    log "WARN: $budget_script is missing, so no RAM ceiling is derived"
+    return 0
+  }
+
+  budget="$(node "$budget_script" --explain 2>>"$LOG")" || {
+    log "WARN: could not derive a RAM ceiling for this box (see $LOG); the detector will refuse a second resident model"
+    return 0
+  }
+  case "$budget" in
+    ''|*[!0-9]*) log "WARN: the RAM-ceiling derivation returned '$budget', which is not a number of MiB; injecting nothing"; return 0 ;;
+  esac
+
+  mkdir -p "$(dirname "$env_file")" 2>/dev/null || true
+  tmp_file="$env_file.tmp.$$"
+  # Rewrite through a temp file so a concurrent read never sees a half-file, and
+  # so the key is REPLACED rather than appended — systemd takes the last
+  # assignment, but a file that grows a line per install is its own bug.
+  { [ -f "$env_file" ] && grep -v '^TRILLBOARDS_DETECTOR_RAM_BUDGET_MB=' "$env_file"; true; } > "$tmp_file" 2>/dev/null || : > "$tmp_file"
+  printf 'TRILLBOARDS_DETECTOR_RAM_BUDGET_MB=%s\n' "$budget" >> "$tmp_file"
+  if mv "$tmp_file" "$env_file" 2>/dev/null; then
+    log "RAM ceiling $budget MiB written to $env_file (derived from this box; see the log above for the subtraction)"
+  else
+    rm -f "$tmp_file" 2>/dev/null || true
+    log "WARN: could not write $env_file (owned by another user?); the detector will refuse a second resident model"
+  fi
+}
+inject_ram_ceiling
+
 # The unit is installed AND STARTED by install.sh, which has root. This script
 # runs as the unprivileged `trillboards` service user (nologin, no sudoers
 # entry), so on a fresh install BOTH attempts below fail by design.

package/deploy/windows/install-update.ps1

@@ -43,6 +43,65 @@ function Register-Connector([string]$Root) {
   if ($LASTEXITCODE -ne 0) { throw "Scheduled-task registration failed." }
 }
 
+<#
+  Carry the detector's RAM ceiling onto an EXISTING install.
+
+  WHY THE UPDATE TRANSACTION HAS TO DO THIS. Nothing else on an upgraded box
+  will. This script only calls Register-Connector, and trillboards-edge.cmd
+  re-runs setup-detector.ps1 only when the task is MISSING or /health answers
+  000 - so a HEALTHY detector keeps the task action it was registered with. A
+  box that updates normally would therefore keep an action with no
+  `--ram-budget-mb` for ever, every delivered specialist would stay `idle`, and
+  the fix would reach NEW INSTALLS ONLY. That is the exact shape of the
+  2026-08-19 Windows BOM incident, and it is why this is here rather than left
+  to the repair path.
+
+  RE-REGISTER, NOT RE-PROVISION. `setup-detector.ps1` runs `uv tool install
+  --force`, which rebuilds a venv and needs the network; putting that inside an
+  update transaction would give the upgrade a new way to be slow and a new way
+  to fail. Re-registering the task is the whole of what has to change, and
+  register-detector-task.ps1 already stops the running service, replaces the
+  action and starts it again - so this both migrates and restarts it.
+
+  BEST EFFORT, ALWAYS. The detector is a cost optimisation: without it every
+  frame goes to the VLM exactly as it does today. It must never be able to fail
+  a customer's upgrade, so every path here returns quietly.
+#>
+function Update-DetectorTask([string]$Root) {
+  try {
+    $task = Get-ScheduledTask -TaskName "TrillboardsDetector" -ErrorAction SilentlyContinue
+    if (-not $task) { return }   # nothing registered yet; the cmd repair path owns that case
+    # The interpreter path comes off the task we are replacing rather than being
+    # re-derived - setup-detector.ps1 resolved it under the USER profile, and
+    # re-deriving here could resolve somewhere else entirely. Same rule
+    # register-task.ps1 states for its own repair.
+    $exe = ($task.Actions | Select-Object -First 1).Execute
+    if (-not $exe) { return }
+
+    $register = Join-Path $Root "bin\register-detector-task.ps1"
+    if (-not (Test-Path -LiteralPath $register)) { return }
+
+    # Re-DERIVED, not carried: the box may have gained memory since it was
+    # installed, and the reservations this is computed from are committed values
+    # that move with a release. If it cannot be derived we pass nothing, and
+    # register-detector-task.ps1 keeps whatever ceiling the old action carried.
+    $budget = ""
+    $budgetScript = Join-Path $Root "bin\detector\ram-budget.js"
+    $nodeExe = Join-Path $Root "bin\node.exe"
+    if ((Test-Path -LiteralPath $budgetScript) -and (Test-Path -LiteralPath $nodeExe)) {
+      $derived = ("" + (& $nodeExe $budgetScript)).Trim()
+      if ($LASTEXITCODE -eq 0 -and $derived -match '^\d+$') { $budget = $derived }
+    }
+
+    $registerArgs = @('-DetectorPath', $exe)
+    if ($budget) { $registerArgs += @('-RamBudgetMb', $budget) }
+    & $register @registerArgs | Out-Null
+    Write-Host "Detector task migrated$(if ($budget) { " (RAM ceiling $budget MiB)" })."
+  } catch {
+    Write-Warning "Could not migrate the detector task: $($_.Exception.Message). Sensing is unaffected; every frame keeps going to the VLM."
+  }
+}
+
 function Assert-ConnectorScheduled {
   # stop-existing.ps1 DISABLES the task so restart-on-failure cannot relaunch
   # node.exe mid-swap. A disabled task suppresses the AtLogOn trigger too, so
@@ -92,6 +151,7 @@ try {
   Assert-ConnectorVersion $InstallDir
   Register-Connector $InstallDir
   Assert-ConnectorScheduled
+  Update-DetectorTask $InstallDir
   if (Test-Path (Join-Path $InstallDir "trillboards.config.json")) {
     Start-ScheduledTask -TaskName "TrillboardsEdge" -ErrorAction Stop
   }

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

@@ -35,13 +35,48 @@
 param(
   [Parameter(Mandatory = $true)][string]$DetectorPath,
   [string]$Port = "9380",
-  [string]$LogFile = ""
+  [string]$LogFile = "",
+  # The portfolio RAM ceiling, in MiB, DERIVED FROM THIS MACHINE by
+  # deploy/detector/ram-budget.js and passed in by setup-detector.ps1.
+  #
+  # EMPTY IS A REAL VALUE AND MUST STAY REACHABLE. `registry.py::_admit` treats
+  # an absent ceiling as "nobody has told me one" and refuses to make a second
+  # model resident rather than inventing a number, which is the correct thing
+  # for this task to say when the box could not be measured. A default here
+  # would make this file a second allocation authority - and one that cannot see
+  # how much memory the machine has.
+  [string]$RamBudgetMb = ""
 )
 $ErrorActionPreference = "Stop"
 
 $TaskName = "TrillboardsDetector"
 $UserId = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
 
+# RECOVER THE CEILING FROM THE TASK WE ARE REPLACING, when the caller did not
+# supply one.
+#
+# register-task.ps1 repairs a non-headless TrillboardsDetector inside its own
+# elevated pass and calls us with ONLY -DetectorPath. Without this, the empty
+# default would win and the replacement action would silently lose
+# --ram-budget-mb -- turning a box that HAD a ceiling back into one that refuses
+# every specialist, on a path whose whole purpose is repair.
+#
+# It is the same idiom that caller already applies to the interpreter path:
+# "Recover ... from the task we are replacing rather than re-deriving it".
+# Re-deriving here would also be wrong for a subtler reason -- an elevated
+# repair pass may not see the same machine state the original derivation did,
+# and a repair must not quietly change a value nobody asked it to change.
+if ([string]::IsNullOrWhiteSpace($RamBudgetMb)) {
+  try {
+    $existingAction = (Get-ScheduledTask -TaskName $TaskName -ErrorAction Stop).Actions |
+      Select-Object -First 1
+    if ($existingAction -and $existingAction.Arguments -match '--ram-budget-mb\s+(\d+)') {
+      $RamBudgetMb = $Matches[1]
+      Write-Host "Carrying the existing RAM ceiling ($RamBudgetMb MiB) onto the replacement task."
+    }
+  } catch { }
+}
+
 if ([string]::IsNullOrWhiteSpace($LogFile)) {
   $LogFile = Join-Path (Join-Path $env:LOCALAPPDATA "Trillboards\logs") "detector.service.log"
 }
@@ -51,6 +86,15 @@ try { New-Item -ItemType Directory -Force -Path (Split-Path -Parent $LogFile) |
 # Loopback only -- LocalDetectorClient is local; nothing off-box has any
 # business reaching this.
 $argument = 'serve --host 127.0.0.1 --port ' + $Port + ' --log-file "' + $LogFile + '"'
+# Appended only when it was derived, and validated here rather than trusted:
+# this string becomes a command line, and a malformed one would either fail the
+# service's own argument parse on every restart or - worse - be silently
+# reinterpreted. Digits only.
+if ($RamBudgetMb -match '^\d+$') {
+  $argument += ' --ram-budget-mb ' + $RamBudgetMb
+} elseif (-not [string]::IsNullOrWhiteSpace($RamBudgetMb)) {
+  Write-Warning "Ignoring a RAM ceiling that is not a whole number of MiB: '$RamBudgetMb'. The detector will hold its pinned model and refuse to make a second one resident."
+}
 $Action  = New-ScheduledTaskAction -Execute $DetectorPath -Argument $argument
 
 # NOT AT LOGON ONLY -- see register-task.ps1 for the full rationale, including

package/deploy/windows/setup-detector.ps1

@@ -140,6 +140,48 @@ if (-not (Test-Path -LiteralPath $detectorPath)) {
 }
 Log "trillboards-detector installed at $detectorPath"
 
+# --- 2b. The RAM ceiling, derived from THIS machine --------------------------
+#
+# Without it the service holds its pinned model and refuses to make any second
+# model resident - `registry.py::_admit`, "no RAM ceiling was injected, so this
+# service has no basis for a portfolio decision and will not invent one". The
+# refusal is correct; the injection was missing from all six supervisor
+# definitions until 2026-08-26, so every delivered specialist stayed `idle`.
+#
+# A TASK ARGUMENT, not an environment variable. A Scheduled Task action has no
+# environment block of its own, and setting a User-scope variable would put a
+# per-machine tuning knob into global machine state where nothing associates it
+# with this service. macOS also takes an argument (its plist is generated too);
+# only Linux, whose unit is a static file with an EnvironmentFile already
+# declared, uses the variable. ONE derivation, three transports.
+#
+# EMPTY WHEN IT CANNOT BE DERIVED, never a placeholder: "nobody has told me a
+# ceiling" is a state the detector handles correctly and loudly.
+$ramBudgetMb = ""
+$budgetScript = Join-Path $source "ram-budget.js"
+$nodeExe = Join-Path $Here "node.exe"
+if (-not (Test-Path -LiteralPath $nodeExe)) {
+  $foundNode = Get-Command node -ErrorAction SilentlyContinue
+  if ($foundNode) { $nodeExe = $foundNode.Source } else { $nodeExe = $null }
+}
+if (-not $nodeExe) {
+  Log "WARN: no node runtime found, so no RAM ceiling is derived; the detector will refuse a second resident model"
+} elseif (-not (Test-Path -LiteralPath $budgetScript)) {
+  Log "WARN: $budgetScript is missing, so no RAM ceiling is derived"
+} else {
+  # `--explain` writes the subtraction to stderr and the bare integer to stdout,
+  # so the log carries WHY and the variable carries only the number. 2>&1 is
+  # deliberately NOT used: it would fold the explanation into the value.
+  $derived = & $nodeExe $budgetScript "--explain" 2>> $LogPath
+  $derived = ("$derived").Trim()
+  if ($LASTEXITCODE -eq 0 -and $derived -match '^\d+$') {
+    $ramBudgetMb = $derived
+    Log "RAM ceiling $ramBudgetMb MiB (derived from this machine; see the log above for the subtraction)"
+  } else {
+    Log "WARN: could not derive a RAM ceiling for this machine (see $LogPath); the detector will refuse a second resident model"
+  }
+}
+
 # --- 3. The Scheduled Task ---------------------------------------------------
 $registration = Join-Path $Here "register-detector-task.ps1"
 if (-not (Test-Path -LiteralPath $registration)) {
@@ -147,7 +189,17 @@ if (-not (Test-Path -LiteralPath $registration)) {
   exit 0
 }
 Log "registering the detector Scheduled Task on :$Port"
-& powershell.exe -NoProfile -ExecutionPolicy Bypass -File $registration -DetectorPath $detectorPath -Port $Port *>> $LogPath
+# OMITTED, not passed empty, when nothing was derived. Windows PowerShell drops
+# an empty-string argument to a native command, so `-RamBudgetMb ""` arrives as a
+# bare `-RamBudgetMb` with nothing after it and the whole registration dies with
+# "Missing an argument for parameter" - turning an undeterminable ceiling into an
+# unsupervised detector. The task script's own default covers the omission.
+$registrationArgs = @(
+  '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', $registration,
+  '-DetectorPath', $detectorPath, '-Port', $Port
+)
+if ($ramBudgetMb) { $registrationArgs += @('-RamBudgetMb', $ramBudgetMb) }
+& powershell.exe @registrationArgs *>> $LogPath
 if ($LASTEXITCODE -ne 0) {
   Log "ERROR: the detector Scheduled Task could not be registered; the cascade stays off"
   exit 0

package/dist/EdgeAgent.js

@@ -44,7 +44,7 @@ const edge_ads_1 = require("@trillboards/edge-ads");
 const CommandRouter_1 = require("./CommandRouter");
 const config_1 = require("./config");
 const dataDir_1 = require("./dataDir");
-const SDK_VERSION = '0.2.104';
+const SDK_VERSION = '0.2.107';
 class EdgeAgent extends events_1.EventEmitter {
     constructor(config, deps) {
         super();

package/dist/diagnose.d.ts

@@ -31,7 +31,7 @@ export interface DiagnosticReport {
         skipped: number;
     };
 }
-declare const SDK_VERSION = "0.2.104";
+declare const SDK_VERSION = "0.2.107";
 declare function checkNodeVersion(): CheckResult;
 declare function checkPlatform(): CheckResult;
 declare function checkMemory(): CheckResult;

package/dist/diagnose.js

@@ -63,7 +63,7 @@ const localNetworkAccess_1 = require("./localNetworkAccess");
 // ---------------------------------------------------------------------------
 // SDK version — mirrors package.json; kept in sync by CI
 // ---------------------------------------------------------------------------
-const SDK_VERSION = '0.2.104';
+const SDK_VERSION = '0.2.107';
 exports._SDK_VERSION = SDK_VERSION;
 // ---------------------------------------------------------------------------
 // ANSI helpers (no external deps)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trillboards/edge-sdk",
-  "version": "0.2.104",
+  "version": "0.2.107",
   "description": "Composable cross-platform Edge AI SDK for audience sensing on DOOH/CTV devices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",