@trillboards/edge-sdk 0.2.52 → 0.2.54

package/deploy/macos/README.md

@@ -19,6 +19,7 @@ What lands on disk (home-domain, **no sudo / no admin password**):
                            edge-sdk), WITHOUT the heavy local-inference stack
   share/com.trillboards.edge.plist   LaunchAgent template
   share/ensure-litertlm.sh           background local-AI retry supervisor
+  share/apply-update.sh              signed-pkg updater with rollback
   share/models/gemma-4-E2B-it.litertlm   required customer local VLM (removed after import)
 ~/Applications/Trillboards CCTV Setup.app native customer setup window (opened automatically)
 ~/Library/Application Support/Trillboards/trillboards.config.json   (after pair, 0600)
@@ -31,14 +32,15 @@ bootstrapped automatically on first successful pair. The device token is
 delivered **only by pairing** — it is never baked into the `.pkg`.
 
 > The customer build includes Gemma and completes its local health check before
-> pairing. Cloud inference requires explicit configuration. `--skip-model` is
-> available only for engineering checks and must not be published.
+> pairing. Cloud inference requires explicit configuration. The release lane
+> also builds a signed, notarized `--skip-model` package for automatic upgrades;
+> it is accepted only on an already-provisioned machine whose model is healthy.
 
 ---
 
 ## Install (operator)
 
-1. Download `TrillboardsEdge-<version>-arm64.pkg`.
+1. Download `SenseAnythingConnector.pkg`.
 2. Double-click it. The installer offers **Install for me only** (home-domain) —
    no admin password. (Equivalent CLI: `installer -pkg <pkg> -target
    CurrentUserHomeDirectory`.)
@@ -73,7 +75,7 @@ launchctl kickstart -k "gui/$(id -u)/com.trillboards.edge"
 cd trillboards-edge-sdk
 npm install                       # ensures ffmpeg-static is fetched
 cd packages/edge-sdk/deploy/macos
-./build-macos-pkg.sh              # → dist-installer/TrillboardsEdge-<ver>-arm64.pkg
+./build-macos-pkg.sh              # → dist-installer/SenseAnythingConnector.pkg
 ```
 
 Options:
@@ -83,13 +85,26 @@ Options:
 | `--arch arm64\|x64` | host arch | target architecture |
 | `--node-version vX.Y.Z` | `v22.22.0` | pinned Node runtime to bundle |
 | `--bundle-model` | on | include the pinned ~2.4 GB Gemma model required by customer setup |
-| `--skip-model` | off | build a slim engineering artifact that must not be published to customers |
+| `--skip-model` | off | build the slim code-only upgrade package; it is not a valid first installer |
 | `--offline` | off | skip the official Node download; copy the host `node` |
 | `--sign-installer "Developer ID Installer: …"` | unset | `productsign` the pkg |
 
 The build is idempotent (it wipes its staging tree each run) and **smoke-tests
 the staged bundle** (`trillboards-edge version`) before packaging.
 
+### Automatic updates
+
+Every paired connector checks the macOS version manifest at launch and every
+six hours. Once a release has baked for six hours, the connector downloads the
+content-addressed code-only package while sensing remains online. Before it can
+be staged, macOS must validate the exact Aethercorp Developer ID Installer
+identity, the notarization staple, Gatekeeper acceptance, size, and SHA-256.
+The connector waits for a safe sensing point, exits cleanly, installs the
+package, smoke-tests the new version, and relaunches the LaunchAgent. The old
+tree remains as `~/Library/Trillboards/edge.previous` and is restored
+automatically if installation, smoke testing, or relaunch fails. Existing
+pairing and the local model are preserved; the setup window does not reopen.
+
 ### Local end-to-end test
 
 ```bash
@@ -121,9 +136,9 @@ To ship a Gatekeeper-clean installer, on a machine that has the
 #   (or: export MAC_INSTALLER_IDENTITY="Developer ID Installer: …" && ./build-macos-pkg.sh)
 
 # 2. Notarize + staple
-xcrun notarytool submit dist-installer/TrillboardsEdge-<ver>-arm64.pkg \
+xcrun notarytool submit dist-installer/SenseAnythingConnector.pkg \
   --keychain-profile <notary-profile> --wait
-xcrun stapler staple dist-installer/TrillboardsEdge-<ver>-arm64.pkg
+xcrun stapler staple dist-installer/SenseAnythingConnector.pkg
 ```
 
 The bundled `bin/node` and `bin/ffmpeg` are third-party Mach-O binaries; for full

package/deploy/macos/apply-update.sh

@@ -0,0 +1,225 @@
+#!/bin/bash
+#
+# Stage and apply the signed, notarized macOS connector update package.
+# The running connector chooses the safe point; this detached helper owns the
+# download, macOS trust checks, LaunchAgent handoff, swap, smoke test, and
+# `.previous` rollback.
+
+set -u
+
+LABEL='com.trillboards.edge'
+EXPECTED_SIGNER='Developer ID Installer: Aethercorp Inc (78JQ7882U9)'
+MODE=''
+INSTALL_DIR=''
+UPDATE_URL=''
+EXPECTED_VERSION=''
+CURRENT_VERSION=''
+EXPECTED_SHA256=''
+EXPECTED_SIZE=''
+WAIT_PID=''
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --stage|--commit) MODE="$1"; shift ;;
+    --install-dir) INSTALL_DIR="${2:-}"; shift 2 ;;
+    --update-url) UPDATE_URL="${2:-}"; shift 2 ;;
+    --expected-version) EXPECTED_VERSION="${2:-}"; shift 2 ;;
+    --current-version) CURRENT_VERSION="${2:-}"; shift 2 ;;
+    --expected-sha256) EXPECTED_SHA256="${2:-}"; shift 2 ;;
+    --expected-size) EXPECTED_SIZE="${2:-}"; shift 2 ;;
+    --wait-pid) WAIT_PID="${2:-}"; shift 2 ;;
+    *) printf '[apply-update] unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+log() {
+  /usr/bin/logger -t com.trillboards.edge "apply-update: $*" 2>/dev/null || true
+  printf '[apply-update] %s\n' "$*"
+}
+
+case "$EXPECTED_VERSION" in
+  [0-9]*.[0-9]*.[0-9]*) ;;
+  *) log 'invalid expected version'; exit 2 ;;
+esac
+
+# The updater is intentionally scoped to the one home-domain path the package
+# installs. This makes every later rm/mv target resolved and bounded.
+EXPECTED_INSTALL_DIR="${HOME}/Library/Trillboards/edge"
+if [ "$INSTALL_DIR" != "$EXPECTED_INSTALL_DIR" ]; then
+  log "refusing unexpected install root: $INSTALL_DIR"
+  exit 2
+fi
+
+PARENT_DIR="$(dirname "$INSTALL_DIR")"
+UPDATE_DIR="$PARENT_DIR/.edge-auto-update"
+ARCHIVE="$UPDATE_DIR/connector-update.pkg"
+MARKER="$UPDATE_DIR/staged.json"
+OUTCOME="$UPDATE_DIR/outcome.json"
+LOCK_DIR="$UPDATE_DIR/lock"
+PREVIOUS="$PARENT_DIR/edge.previous"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+
+mkdir -p "$UPDATE_DIR" || exit 1
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  log 'another update transaction is already running'
+  exit 0
+fi
+trap 'rmdir "$LOCK_DIR" 2>/dev/null || true' EXIT
+
+json_escape() {
+  printf '%s' "$1" | /usr/bin/sed 's/\\/\\\\/g; s/"/\\"/g'
+}
+
+write_outcome() {
+  local result="$1" detail="$2" tmp="$OUTCOME.tmp.$$"
+  printf '{"attemptedAt":"%s","result":"%s","detail":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$result" "$(json_escape "$detail")" > "$tmp" \
+    && mv -f "$tmp" "$OUTCOME"
+}
+
+fail_stage() {
+  log "$1"
+  rm -f "$ARCHIVE.download" "$MARKER.tmp.$$"
+  exit 1
+}
+
+configure_proxy() {
+  if [ -n "${HTTPS_PROXY:-}" ] || [ -n "${https_proxy:-}" ] || [ -n "${ALL_PROXY:-}" ]; then
+    return
+  fi
+  local proxy_conf enabled host port
+  proxy_conf="$(/usr/sbin/scutil --proxy 2>/dev/null || true)"
+  enabled="$(printf '%s\n' "$proxy_conf" | /usr/bin/awk '/HTTPSEnable/ {print $3}')"
+  [ "$enabled" = '1' ] || return
+  host="$(printf '%s\n' "$proxy_conf" | /usr/bin/awk '/HTTPSProxy/ {print $3}')"
+  port="$(printf '%s\n' "$proxy_conf" | /usr/bin/awk '/HTTPSPort/ {print $3}')"
+  [ -n "$host" ] || return
+  HTTPS_PROXY="http://$host${port:+:$port}"
+  export HTTPS_PROXY HTTP_PROXY="$HTTPS_PROXY"
+}
+
+verify_pkg() {
+  local pkg="$1" sha="$2" size="$3" actual_size actual_sha sig_out
+  [ -f "$pkg" ] || return 1
+  case "$size" in *[!0-9]*|'') return 1 ;; esac
+  printf '%s' "$sha" | /usr/bin/grep -Eq '^[0-9a-f]{64}$' || return 1
+
+  actual_size="$(/usr/bin/wc -c < "$pkg" | tr -d ' ')"
+  [ "$actual_size" = "$size" ] || { log "payload size mismatch: expected $size, got $actual_size"; return 1; }
+  actual_sha="$(/usr/bin/shasum -a 256 "$pkg" | /usr/bin/awk '{print $1}')"
+  [ "$actual_sha" = "$sha" ] || { log 'payload SHA-256 mismatch'; return 1; }
+
+  sig_out="$UPDATE_DIR/signature.txt"
+  /usr/sbin/pkgutil --check-signature "$pkg" > "$sig_out" 2>&1 || { log 'package signature is invalid'; return 1; }
+  /usr/bin/grep -Fq "$EXPECTED_SIGNER" "$sig_out" || { log 'package signer is not Aethercorp'; return 1; }
+  /usr/bin/xcrun stapler validate "$pkg" >/dev/null 2>&1 || { log 'package has no valid notarization staple'; return 1; }
+  /usr/sbin/spctl -a -vv --type install "$pkg" >/dev/null 2>&1 || { log 'Gatekeeper rejected the update package'; return 1; }
+  return 0
+}
+
+if [ "$MODE" = '--stage' ]; then
+  case "$UPDATE_URL" in https://*) ;; *) fail_stage 'update URL must use HTTPS' ;; esac
+  configure_proxy
+  log "downloading connector $EXPECTED_VERSION while sensing stays online"
+  /usr/bin/curl --fail --location --silent --show-error --proto '=https' --tlsv1.2 \
+    --connect-timeout 30 --max-time 3600 --output "$ARCHIVE.download" "$UPDATE_URL" \
+    || fail_stage 'update download failed'
+  verify_pkg "$ARCHIVE.download" "$EXPECTED_SHA256" "$EXPECTED_SIZE" \
+    || fail_stage 'update package verification failed'
+  mv -f "$ARCHIVE.download" "$ARCHIVE" || fail_stage 'could not retain verified package'
+  marker_tmp="$MARKER.tmp.$$"
+  printf '{"version":"%s","currentVersion":"%s","sha256":"%s","sizeBytes":%s}\n' \
+    "$EXPECTED_VERSION" "$CURRENT_VERSION" "$EXPECTED_SHA256" "$EXPECTED_SIZE" > "$marker_tmp" \
+    || fail_stage 'could not write staged marker'
+  mv -f "$marker_tmp" "$MARKER" || fail_stage 'could not publish staged marker'
+  log "connector $EXPECTED_VERSION is staged, signed, notarized, and verified"
+  exit 0
+fi
+
+if [ "$MODE" != '--commit' ]; then
+  log 'exactly one of --stage or --commit is required'
+  exit 2
+fi
+
+marker_version="$(/usr/bin/plutil -extract version raw "$MARKER" 2>/dev/null || true)"
+marker_sha="$(/usr/bin/plutil -extract sha256 raw "$MARKER" 2>/dev/null || true)"
+marker_size="$(/usr/bin/plutil -extract sizeBytes raw "$MARKER" 2>/dev/null || true)"
+if [ "$marker_version" != "$EXPECTED_VERSION" ]; then
+  write_outcome 'rejected' 'staged version did not match the requested version'
+  log 'staged version mismatch; refusing update'
+  exit 1
+fi
+verify_pkg "$ARCHIVE" "$marker_sha" "$marker_size" || {
+  write_outcome 'rejected' 'staged package failed commit-time verification'
+  rm -f "$MARKER" "$ARCHIVE"
+  exit 1
+}
+
+# The connector launches us and then exits cleanly. Do not touch its mapped
+# binaries until that PID is gone; a timeout leaves the current install intact.
+if [ -n "$WAIT_PID" ]; then
+  waited=0
+  while kill -0 "$WAIT_PID" 2>/dev/null && [ "$waited" -lt 120 ]; do
+    sleep 1
+    waited=$((waited + 1))
+  done
+  if kill -0 "$WAIT_PID" 2>/dev/null; then
+    write_outcome 'failed' 'connector did not exit before the update deadline'
+    log 'connector did not exit; leaving current install untouched'
+    exit 1
+  fi
+fi
+
+restart_agent() {
+  [ -f "$PLIST" ] || return 1
+  /bin/launchctl bootout "gui/$(id -u)/$LABEL" >/dev/null 2>&1 || true
+  local attempt=1
+  while [ "$attempt" -le 10 ]; do
+    /bin/launchctl bootstrap "gui/$(id -u)" "$PLIST" >/dev/null 2>&1 || true
+    if /bin/launchctl print "gui/$(id -u)/$LABEL" >/dev/null 2>&1; then
+      /bin/launchctl kickstart -k "gui/$(id -u)/$LABEL" >/dev/null 2>&1 || true
+      return 0
+    fi
+    sleep 1
+    attempt=$((attempt + 1))
+  done
+  return 1
+}
+
+rollback() {
+  local detail="$1"
+  /bin/launchctl bootout "gui/$(id -u)/$LABEL" >/dev/null 2>&1 || true
+  rm -rf "$INSTALL_DIR"
+  if [ -d "$PREVIOUS" ]; then
+    mv "$PREVIOUS" "$INSTALL_DIR" || true
+  fi
+  if restart_agent; then
+    write_outcome 'failed' "$detail; previous version restored"
+  else
+    write_outcome 'failed' "$detail; previous files restored but the agent did not restart"
+  fi
+  rm -f "$MARKER" "$ARCHIVE"
+  log "$detail; rolled back"
+  exit 1
+}
+
+log "applying connector $EXPECTED_VERSION"
+/bin/launchctl bootout "gui/$(id -u)/$LABEL" >/dev/null 2>&1 || true
+rm -rf "$PREVIOUS"
+mv "$INSTALL_DIR" "$PREVIOUS" || {
+  write_outcome 'failed' 'could not preserve the current install for rollback'
+  exit 1
+}
+
+/usr/sbin/installer -pkg "$ARCHIVE" -target CurrentUserHomeDirectory >/dev/null 2>&1 \
+  || rollback 'macOS Installer rejected the update'
+
+installed_version="$($INSTALL_DIR/bin/trillboards-edge version 2>/dev/null || true)"
+printf '%s' "$installed_version" | /usr/bin/grep -Fq "edge-sdk v$EXPECTED_VERSION" \
+  || rollback 'updated connector failed its version smoke test'
+
+restart_agent || rollback 'updated connector installed but its LaunchAgent did not restart'
+write_outcome 'success' "updated from $CURRENT_VERSION to $EXPECTED_VERSION"
+rm -f "$MARKER" "$ARCHIVE" "$UPDATE_DIR/signature.txt"
+log "connector $EXPECTED_VERSION installed and relaunched"
+exit 0

package/deploy/macos/bench-local-vlm.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+#
+# bench-local-vlm.sh — macOS twin of `deploy/windows/e2e/test-local-sense.ps1
+# -Mode bench`: provision the PINNED litert-lm + Gemma 4 E2B, start a real
+# serve, and MEASURE this machine's per-frame cost.
+#
+# WHY IT EXISTS. Local-only inference makes the box spec the product spec, and
+# every latency number in the capacity plan came off one Apple M4 Max
+# workstation — including the 7.30 s/frame in connectorCadence.ts that sizes the
+# whole 493-analyses/hour budget. A 3-core / 7 GB Apple silicon runner is the
+# closest CI has to the Mac mini we would actually recommend, and it is the only
+# cheap way to test the "16 GB+ RAM" minimum the activation runbook publishes.
+#
+# It does NOT use setup-litertlm.sh's LaunchAgent path: that bootstraps a
+# per-login agent, and a CI runner's session is not the session a customer logs
+# into. The runtime, the pin and the model are identical; only the supervisor
+# differs, and the supervisor is not what is being measured.
+#
+# NOTE ON BASH 3.2. macOS still ships bash 3.2 as /bin/bash and that is what a
+# GitHub macOS runner executes. Its identifier scan is NOT UTF-8 aware, so an
+# expansion written `$VAR…` swallows the ellipsis bytes into the variable NAME
+# and `set -u` then reports an unbound variable whose name is the real one with
+# mojibake stapled to it — which reads as "the variable is unset" when it is set.
+# Every expansion here is braced and every log line is ASCII for that reason.
+#
+# Usage:
+#   deploy/macos/bench-local-vlm.sh [--port 9379] [--arms a,b] [--frames f]
+#                                   [--rounds 1] [--budget-min 40]
+#                                   [--frame-timeout-min 20] [--out FILE]
+#                                   [--model <non-default>.litertlm]
+#
+# Exit 0 = a matrix was written (even a partial one — a slow box is a RESULT).
+# Exit 1 = nothing was measured at all.
+set -uo pipefail
+
+PORT=9379
+ARMS='cpu-sop,cpu-dooh-sop,gpu-sop'
+FRAMES='kitchen-5-people'
+ROUNDS=1
+BUDGET_MIN=40
+FRAME_TIMEOUT_MIN=20
+OUT="${TMPDIR:-/tmp}/bench-local-vlm.json"
+NOTE=''
+# A NON-default .litertlm id, for the per-silicon A/B. Empty = the generic file
+# both provisioners import everywhere.
+MODEL=''
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --port) PORT="$2"; shift 2 ;;
+    --arms) ARMS="$2"; shift 2 ;;
+    --frames) FRAMES="$2"; shift 2 ;;
+    --rounds) ROUNDS="$2"; shift 2 ;;
+    --budget-min) BUDGET_MIN="$2"; shift 2 ;;
+    --frame-timeout-min) FRAME_TIMEOUT_MIN="$2"; shift 2 ;;
+    --out) OUT="$2"; shift 2 ;;
+    --note) NOTE="$2"; shift 2 ;;
+    --model) MODEL="$2"; shift 2 ;;
+    *) echo "unknown flag: $1" >&2; exit 2 ;;
+  esac
+done
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"   # <edge-sdk>/deploy/macos
+PKG_ROOT="$(cd "$HERE/../.." && pwd)"                  # <edge-sdk>
+WORKSPACE_ROOT="$(cd "$PKG_ROOT/../.." && pwd)"        # <repo>/trillboards-edge-sdk
+[ -f "$PKG_ROOT/scripts/bench-local-vlm.mjs" ] || { echo "FAIL - PKG_ROOT wrong: $PKG_ROOT" >&2; exit 1; }
+[ -f "$WORKSPACE_ROOT/package.json" ] || { echo "FAIL - WORKSPACE_ROOT wrong: $WORKSPACE_ROOT" >&2; exit 1; }
+log() { echo "[macos-bench] $*"; }
+die() { echo "FAIL - $*" >&2; exit 1; }
+
+# The PINNED version, read from the provisioner rather than restated here — the
+# litert-lm-version-pin guard already keeps that one declaration honest, and a
+# second copy would be a second thing to forget.
+LITERT_LM_VERSION="$(sed -n 's/^LITERT_LM_VERSION="\${LITERT_LM_VERSION:-\([^}]*\)}"/\1/p' "$HERE/scripts/setup-litertlm.sh" | head -1)"
+[ -n "$LITERT_LM_VERSION" ] || die "could not read the pinned litert-lm version from setup-litertlm.sh"
+log "pinned litert-lm: $LITERT_LM_VERSION"
+
+log "building the connector (tsc, all workspaces in dependency order) ..."
+( cd "$WORKSPACE_ROOT" && npm run build ) || die "npm run build failed"
+
+if ! command -v uv >/dev/null 2>&1; then
+  log "installing uv (home-domain, no sudo) ..."
+  curl -LsSf https://astral.sh/uv/install.sh | sh || die "uv install failed"
+fi
+export PATH="$HOME/.local/bin:$PATH"
+
+log "installing litert-lm==${LITERT_LM_VERSION} ..."
+uv tool install --python 3.12 --managed-python --force "litert-lm==$LITERT_LM_VERSION" \
+  || die "litert-lm install failed"
+LITERTLM="$HOME/.local/bin/litert-lm"
+[ -x "$LITERTLM" ] || die "litert-lm not installed at $LITERTLM"
+
+MODEL_ID='gemma-4-E2B-it.litertlm'
+HF_REPO='litert-community/gemma-4-E2B-it-litert-lm'
+if ! "$LITERTLM" list 2>/dev/null | grep -q "$MODEL_ID"; then
+  # EXACT form setup-litertlm.sh uses. The positional argument is the FILE inside
+  # the repo, not the repo: passing the repo id alone gets
+  # "Source file not found: <repo>", because the bare form imports a LOCAL path.
+  log "importing ${MODEL_ID} from ${HF_REPO} (~2.4 GB) ..."
+  "$LITERTLM" import --from-huggingface-repo "$HF_REPO" "$MODEL_ID" || die "model import failed"
+fi
+
+SERVE_LOG="${TMPDIR:-/tmp}/litertlm-serve-bench.log"
+if curl -fsS --max-time 3 "http://127.0.0.1:$PORT/v1/models" >/dev/null 2>&1; then
+  log "a serve is already healthy on :$PORT"
+  SERVE_PID=''
+else
+  log "starting litert-lm serve on 127.0.0.1:$PORT (log: $SERVE_LOG)"
+  "$LITERTLM" serve --host 127.0.0.1 --port "$PORT" --verbose > "$SERVE_LOG" 2>&1 &
+  SERVE_PID=$!
+fi
+cleanup() { [ -n "${SERVE_PID:-}" ] && kill "$SERVE_PID" 2>/dev/null; }
+trap cleanup EXIT
+
+HEALTHY=0
+for _ in $(seq 1 120); do
+  if curl -fsS --max-time 3 "http://127.0.0.1:$PORT/v1/models" >/dev/null 2>&1; then HEALTHY=1; break; fi
+  [ -n "${SERVE_PID:-}" ] && ! kill -0 "$SERVE_PID" 2>/dev/null && break
+  sleep 5
+done
+[ "$HEALTHY" = "1" ] || { tail -40 "$SERVE_LOG" 2>/dev/null; die "litert-lm serve never became healthy on :$PORT"; }
+log "litert-lm serve healthy on :$PORT"
+
+log "running the hardware matrix — arms=$ARMS frames=$FRAMES rounds=$ROUNDS budget=${BUDGET_MIN}m"
+node "$PKG_ROOT/scripts/bench-local-vlm.mjs" \
+  --litert "http://127.0.0.1:$PORT" \
+  --arms "$ARMS" --frames "$FRAMES" --rounds "$ROUNDS" \
+  --budget-ms "$((BUDGET_MIN * 60000))" \
+  --timeout-ms "$((FRAME_TIMEOUT_MIN * 60000))" \
+  --machine-note "$NOTE" \
+  ${MODEL:+--model "$MODEL"} \
+  --out "$OUT"
+BENCH_EXIT=$?
+
+# A bench REPORTS; it does not gate. Exiting non-zero because a machine is slow
+# would turn "this box is too slow" into "the lane is broken" — the confusion
+# that left windows-latest unmeasured for two months. Only producing NOTHING fails.
+[ -f "$OUT" ] || die "bench produced no matrix at all (node exit $BENCH_EXIT)"
+log "matrix written: $OUT"
+exit 0

package/deploy/macos/build-macos-pkg.sh

@@ -31,7 +31,7 @@
 #                      [--sign-app "Developer ID Application: …"]
 #                      [--sign-installer "Developer ID Installer: …"]
 #                      [--bundle-model] (default; include the pinned ~2.4 GB VLM)
-#                      [--skip-model] (engineering-only slim build)
+#                      [--skip-model] (code-only upgrade; not a first installer)
 #                      [--offline]   (skip the official Node + ffmpeg downloads,
 #                                     copy the host `node`/`ffmpeg` instead — for
 #                                     air-gapped CI)
@@ -104,6 +104,7 @@ WORKSPACE_ROOT="$(cd "$PKG_ROOT/../.." && pwd)"  # …/trillboards-edge-sdk
 
 BUNDLE_ID="com.trillboards.edge"
 APP_NAME="TrillboardsEdge"
+INSTALLER_NAME="SenseAnythingConnector"
 INSTALL_SUBDIR="Library/Trillboards/edge"        # relative to the user home
 
 # ─── Args ────────────────────────────────────────────────────────────────────
@@ -150,8 +151,8 @@ while [ $# -gt 0 ]; do
   esac
 done
 
-# Offline customer builds must provide the model cache explicitly. Slim builds
-# remain available only for focused engineering checks.
+# Offline first-install builds must provide the model cache explicitly. Slim
+# builds are the release lane's code-only upgrade artifact.
 if [ "$OFFLINE" -eq 1 ] && [ "$BUNDLE_MODEL" -eq 1 ] && [ -z "$GEMMA_MODEL_FILE" ]; then
   echo "--offline with the customer model bundle requires GEMMA_MODEL_FILE" >&2
   exit 2
@@ -176,7 +177,7 @@ DIST_DIR="$PKG_ROOT/deploy/macos/dist-installer"
 STAGE="$DIST_DIR/stage-$ARCH_LABEL"    # the payload root (== the user home view)
 PAYLOAD="$STAGE/$INSTALL_SUBDIR"       # …/Library/Trillboards/edge
 SCRATCH="$DIST_DIR/scratch-$ARCH_LABEL"
-PKG_OUT="$DIST_DIR/${APP_NAME}-${VERSION}-${ARCH_LABEL}.pkg"
+PKG_OUT="$DIST_DIR/${INSTALLER_NAME}.pkg"
 COMPONENT_PKG="$SCRATCH/${APP_NAME}-component.pkg"
 SETUP_APP="$STAGE/Applications/Trillboards CCTV Setup.app"
 
@@ -398,7 +399,9 @@ cp "$PKG_ROOT/deploy/macos/com.trillboards.edge.plist" "$PAYLOAD/share/com.trill
 cp "$PKG_ROOT/deploy/macos/com.trillboards.litertlm.plist" "$PAYLOAD/share/com.trillboards.litertlm.plist"
 cp "$PKG_ROOT/deploy/macos/scripts/setup-litertlm.sh" "$PAYLOAD/share/setup-litertlm.sh"
 cp "$PKG_ROOT/deploy/macos/scripts/ensure-litertlm.sh" "$PAYLOAD/share/ensure-litertlm.sh"
-chmod +x "$PAYLOAD/share/setup-litertlm.sh" "$PAYLOAD/share/ensure-litertlm.sh"
+cp "$PKG_ROOT/deploy/macos/apply-update.sh" "$PAYLOAD/share/apply-update.sh"
+chmod +x "$PAYLOAD/share/setup-litertlm.sh" "$PAYLOAD/share/ensure-litertlm.sh" \
+  "$PAYLOAD/share/apply-update.sh"
 
 # ─── 7b. Stage the pre-bundled Gemma model (.litertlm) into the payload ───────
 # Stage the redistributable (Apache-2.0) Gemma 4 E2B LiteRT-LM model and verify
@@ -423,7 +426,7 @@ if [ "$BUNDLE_MODEL" -eq 1 ]; then
   printf '%s  %s\n' "$GEMMA_MODEL_SHA256" "$GEMMA_MODEL_ID" > "$PAYLOAD/share/models/$GEMMA_MODEL_ID.sha256"
   log "Staged + SHA-verified bundled Gemma model ($(du -h "$GEMMA_OUT" | cut -f1))"
 else
-  warn "Building an engineering-only slim package without local AI. Do not publish this artifact to customers."
+  warn "Building the code-only upgrade package without bundled local AI; it requires an already-provisioned Mac."
 fi
 
 # ─── 7c. Build the native customer setup application ─────────────────────────
@@ -588,7 +591,7 @@ productbuild \
 # ─── 10. Optional sign ───────────────────────────────────────────────────────
 if [ -n "$SIGN_IDENTITY" ]; then
   log "productsign with '$SIGN_IDENTITY'…"
-  SIGNED="$DIST_DIR/${APP_NAME}-${VERSION}-${ARCH}-signed.pkg"
+  SIGNED="$DIST_DIR/${INSTALLER_NAME}-signed.pkg"
   productsign --sign "$SIGN_IDENTITY" "$PKG_OUT" "$SIGNED"
   mv "$SIGNED" "$PKG_OUT"
   log "Signed: $PKG_OUT"
@@ -603,12 +606,12 @@ else
   warn "cert (pass --sign-installer) then notarize (see deploy/macos/README.md)."
 fi
 
-# Keep deliberately slim engineering builds bounded so an unrelated payload
-# regression cannot masquerade as the bundled customer package.
+# Keep code-only upgrade builds bounded so an unrelated payload regression
+# cannot turn an automatic update into another multi-gigabyte first install.
 PKG_BYTES="$(stat -f%z "$PKG_OUT")"
 MAX_SLIM_PKG_BYTES="${MAX_SLIM_PKG_BYTES:-262144000}"
 if [ "$BUNDLE_MODEL" -eq 0 ] && [ "$PKG_BYTES" -gt "$MAX_SLIM_PKG_BYTES" ]; then
-  die "slim engineering installer is $PKG_BYTES bytes; maximum is $MAX_SLIM_PKG_BYTES bytes"
+  die "code-only update package is $PKG_BYTES bytes; maximum is $MAX_SLIM_PKG_BYTES bytes"
 fi
 
 # ─── Done ────────────────────────────────────────────────────────────────────

package/deploy/macos/scripts/postinstall

@@ -8,7 +8,8 @@
 #   - ensure the runtime dirs exist (Application Support config dir + Logs dir)
 #   - make the bundled binaries executable (pkg payloads can lose +x)
 #   - install and health-check the bundled local AI model
-#   - open camera pairing only after local AI is ready
+#   - open camera pairing only after local AI is ready on a first install
+#   - keep an already-paired update headless
 #   - DO NOT start the LaunchAgent: there is no paired config yet, and a
 #     config-less cloud-sense crash-loops. The agent is bootstrapped only after
 #     a successful setup (the installed pairing engine does that).
@@ -42,6 +43,9 @@ fi
 EDGE_ROOT="$USER_HOME/Library/Trillboards/edge"
 APP_SUPPORT="$USER_HOME/Library/Application Support/Trillboards"
 LOG_DIR="$USER_HOME/Library/Logs/Trillboards"
+PAIRED_CONFIG="$APP_SUPPORT/trillboards.config.json"
+IS_UPGRADE=0
+[ -s "$PAIRED_CONFIG" ] && IS_UPGRADE=1
 
 log() { /usr/bin/logger -t com.trillboards.edge "postinstall: $*" 2>/dev/null || true; printf '[trillboards postinstall] %s\n' "$*"; }
 
@@ -118,7 +122,9 @@ APPS_DIR="$USER_HOME/Applications"
 SETUP_APP="$APPS_DIR/Trillboards CCTV Setup.app"
 LEGACY_PAIR_LAUNCHER="$APPS_DIR/Trillboards Pair.command"
 rm -f "$LEGACY_PAIR_LAUNCHER" 2>/dev/null || true
-if [ -d "$SETUP_APP" ] && [ -x "$EDGE_ROOT/bin/trillboards-pair" ]; then
+if [ "$IS_UPGRADE" -eq 1 ]; then
+  log "paired connector upgrade detected; setup remains closed"
+elif [ -d "$SETUP_APP" ] && [ -x "$EDGE_ROOT/bin/trillboards-pair" ]; then
   log "native setup app ready: \"$SETUP_APP\" (opening it)"
   if [ "$(id -u)" = "0" ] && [ -n "$OWNER" ] && [ "$OWNER" != "root" ]; then
     LAUNCH_UID="$(id -u "$OWNER" 2>/dev/null || echo '')"
@@ -149,5 +155,9 @@ else
   log "WARNING: launcher not executable at $EDGE_ROOT/bin/trillboards-edge"
 fi
 
-log "done. Connector and local AI installed; Trillboards CCTV Setup opened automatically."
+if [ "$IS_UPGRADE" -eq 1 ]; then
+  log "done. Connector update installed; existing pairing preserved."
+else
+  log "done. Connector and local AI installed; Trillboards CCTV Setup opened automatically."
+fi
 exit 0

package/deploy/windows/README.md

@@ -70,15 +70,17 @@ serves every Windows 10/11 — no per-arch builds.
 ./build-windows.ps1 -Offline        # copy host node/ffmpeg (air-gapped)
 
 # after the inner installer is signed, create the one-file customer artifact
-./bundle-windows-installer.ps1 -InnerInstaller <signed-inner.exe>
+./bundle-windows-installer.ps1 -InnerInstaller <signed-inner.exe> # -> dist-installer\customer\SenseAnythingConnector.exe
 ```
 
 Requires NSIS and 7-Zip on PATH (`choco install nsis 7zip -y`). The release workflow publishes
-the `.exe` to `s3://trillboards-screen-static/connector/trillboards-connector-windows.exe`
+the `.exe` to `s3://trillboards-screen-static/connector/SenseAnythingConnector.exe`
 plus `trillboards-connector-windows.version.json`, containing the exact connector
-version, production commit, SHA-256, file size, and publication time. It then
-invalidates the `screen.trillboards.com` CloudFront distribution, so the portal's
-stable download URL never changes while field tests remain artifact-verifiable.
+version, production commit, SHA-256, file size, and publication time. The old
+`trillboards-connector-windows.exe` object remains a compatibility alias, with a
+content-disposition header that still downloads as `SenseAnythingConnector.exe`.
+It then invalidates the `screen.trillboards.com` CloudFront distribution, so the
+portal's stable download URL never changes while field tests remain artifact-verifiable.
 
 ## Notes
 

package/deploy/windows/bundle-windows-installer.ps1

@@ -37,9 +37,7 @@ if (-not (Test-Path -LiteralPath $InnerInstaller -PathType Leaf)) {
 }
 
 if ([string]::IsNullOrWhiteSpace($OutputPath)) {
-  $version = [System.Diagnostics.FileVersionInfo]::GetVersionInfo($InnerInstaller).ProductVersion
-  if ([string]::IsNullOrWhiteSpace($version)) { $version = "unknown" }
-  $OutputPath = Join-Path (Join-Path $DistDir "customer") "TrillboardsEdgeSetup-$version-x64.exe"
+  $OutputPath = Join-Path (Join-Path $DistDir "customer") "SenseAnythingConnector.exe"
 }
 $OutputPath = [System.IO.Path]::GetFullPath($OutputPath)