@trillboards/edge-sdk 0.2.4 → 0.2.6

package/deploy/macos/com.trillboards.litertlm.plist

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  Per-user LaunchAgent for the LiteRT-LM on-device VLM server (Gemma 4 E2B).
+
+  This is a TEMPLATE: setup-litertlm.sh substitutes __LITERTLM__ (absolute path
+  to the uv-installed `litert-lm` binary) / __PORT__ / __LOG_DIR__ and writes the
+  result to ~/Library/LaunchAgents/com.trillboards.litertlm.plist, then loads it
+  via `launchctl bootstrap gui/$UID`.
+
+  Runs the OpenAI-compatible server the connector's LiteRtVlmProvider talks to.
+  KeepAlive=true (always-on local inference endpoint); ThrottleInterval guards a
+  hot crash-loop if the installed runtime becomes temporarily unavailable.
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.trillboards.litertlm</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>__LITERTLM__</string>
+    <string>serve</string>
+    <string>--host</string>
+    <string>127.0.0.1</string>
+    <string>--port</string>
+    <string>__PORT__</string>
+  </array>
+
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+
+  <key>ProcessType</key>
+  <string>Background</string>
+
+  <key>StandardOutPath</key>
+  <string>__LOG_DIR__/litertlm.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>__LOG_DIR__/litertlm.err.log</string>
+</dict>
+</plist>

package/deploy/macos/pair.command

@@ -0,0 +1,519 @@
+#!/bin/bash
+#
+# pair.command — first-run pairing helper for the Trillboards local-first CCTV
+# connector. Installed as ~/Library/Trillboards/edge/bin/trillboards-pair.
+#
+# Three modes:
+#   Native app (`--setup --status-file <path>`):
+#       runs validate-first setup without Terminal or AppleScript dialogs and
+#       reports credential-free progress to Trillboards CCTV Setup.app.
+#   Legacy GUI (no arguments):
+#       osascript prompts for the pairing code, runs the bundled
+#       `trillboards-edge pair`, bootstraps the per-user LaunchAgent, and shows
+#       a success/failure dialog. Kept for compatibility with older launchers.
+#   Headless (CI / scripted):
+#       trillboards-pair <CODE> [--api-base URL]
+#       Pairs, bootstraps the agent, prints status, exits 0/1. Drives the same
+#       code path as the GUI without any dialog (so the local test can use it).
+#
+# The device token is delivered ONLY by pairing — it is never baked into the
+# pkg. The paired config is written to
+# ~/Library/Application Support/Trillboards/trillboards.config.json (mode 0600).
+
+set -euo pipefail
+
+# ─── Resolve paths ───────────────────────────────────────────────────────────
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"   # …/edge/bin
+ROOT="$(cd "$HERE/.." && pwd)"                          # …/edge
+USER_HOME="${HOME:-$(eval echo "~$(id -un)")}"
+
+LAUNCHER="$HERE/trillboards-edge"
+NODE_BIN="$HERE/node"                                   # bundled node runtime
+APP_SUPPORT="$USER_HOME/Library/Application Support/Trillboards"
+CONFIG="$APP_SUPPORT/trillboards.config.json"
+LOG_DIR="$USER_HOME/Library/Logs/Trillboards"
+LA_DIR="$USER_HOME/Library/LaunchAgents"
+PLIST="$LA_DIR/com.trillboards.edge.plist"
+PLIST_TEMPLATE="$ROOT/share/com.trillboards.edge.plist"
+LOCAL_AI_SETUP="$ROOT/share/setup-litertlm.sh"
+LABEL="com.trillboards.edge"
+
+API_BASE="${TRILLBOARDS_API_BASE:-}"
+HEADLESS_CODE=""
+UI_STATUS_FILE=""
+
+# Parse args. First non-flag positional == the code (headless mode).
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --api-base) API_BASE="$2"; shift 2;;
+    --setup) SETUP_MODE=1; shift;;
+    --status-file) UI_STATUS_FILE="$2"; shift 2;;
+    -h|--help) sed -n '2,20p' "${BASH_SOURCE[0]}"; exit 0;;
+    *) if [ -z "$HEADLESS_CODE" ]; then HEADLESS_CODE="$1"; fi; shift;;
+  esac
+done
+
+mkdir -p "$APP_SUPPORT" "$LOG_DIR" "$LA_DIR"
+chmod 700 "$APP_SUPPORT" 2>/dev/null || true
+
+# ─── Helpers ─────────────────────────────────────────────────────────────────
+is_headless() { [ -n "$HEADLESS_CODE" ]; }
+is_ui() { [ -n "$UI_STATUS_FILE" ]; }
+
+# Milestone log (rolling transcript for "send diagnostics" — never codes/tokens).
+plog() { printf '[%s] %s\n' "$(date '+%Y-%m-%dT%H:%M:%S')" "$*" >> "$LOG_DIR/pairing.log" 2>/dev/null || true; }
+
+# Advance the credential-free state consumed by the native setup app. The CLI
+# writer merges prior metrics (for example cameraCount) and writes atomically.
+write_ui_status() { # stage title message
+  is_ui || return 0
+  "$LAUNCHER" setup-status \
+    --status-file "$UI_STATUS_FILE" \
+    --stage "$1" \
+    --title "$2" \
+    --message "$3" >/dev/null 2>&1 || true
+}
+
+# Confirm the installer-owned local AI service is still healthy before starting
+# the camera connector. Required-bundle mode can repair the runtime or restart
+# the service, but it can never download a missing model from the network.
+verify_local_ai_setup() {
+  if [ ! -f "$LOCAL_AI_SETUP" ]; then
+    plog "local-ai: setup script missing at $LOCAL_AI_SETUP"
+    return 1
+  fi
+  chmod +x "$LOCAL_AI_SETUP" 2>/dev/null || true
+  if TRILLBOARDS_REQUIRE_BUNDLED_MODEL=1 /bin/bash "$LOCAL_AI_SETUP" >> "$LOG_DIR/litertlm-setup.log" 2>&1; then
+    plog "local-ai: bundled model and service verified"
+    return 0
+  fi
+  plog "local-ai: verification failed"
+  return 1
+}
+
+# The LaunchAgent must actually RUN, not just load — "bootstrapped" alone is the
+# same false success the Windows helper shipped (task registered ≠ task running).
+agent_running() {
+  launchctl print "gui/$(id -u)/$LABEL" 2>/dev/null | grep -q 'state = running'
+}
+wait_agent_running() { # up to ~12s
+  local i
+  for i in $(seq 1 12); do
+    agent_running && return 0
+    sleep 1
+  done
+  return 1
+}
+
+run_with_timeout() {
+  local seconds="$1"; shift
+  "$@" &
+  local pid=$!
+  local elapsed=0
+  while kill -0 "$pid" 2>/dev/null; do
+    if [ "$elapsed" -ge "$seconds" ]; then
+      kill "$pid" 2>/dev/null || true
+      sleep 1
+      kill -9 "$pid" 2>/dev/null || true
+      wait "$pid" 2>/dev/null || true
+      return 124
+    fi
+    sleep 1
+    elapsed=$((elapsed + 1))
+  done
+  wait "$pid"
+  local rc=$?
+  return "$rc"
+}
+
+# Verify the SAVED pairing works from this machine (network + token). Exit codes
+# from `trillboards-edge verify-connection`: 0 ok / 2 network / 3 auth /
+# 4 no-config / 5 server — resume logic branches on these.
+verify_saved_pairing() {
+  "$LAUNCHER" verify-connection --config "$CONFIG" >/dev/null 2>&1
+}
+
+dialog_get_code() {
+  # Returns the entered code on stdout, or exits 2 if cancelled.
+  osascript <<'OSA' 2>/dev/null
+try
+  set theResult to display dialog "Paste your Trillboards pairing code" & return & "(Get one from the Trillboards portal → Add a camera → Install.)" default answer "" with title "Trillboards Edge — Pair this Mac" buttons {"Cancel", "Pair"} default button "Pair" with icon note
+  set theCode to text returned of theResult
+  return theCode
+on error
+  error "cancelled" number 2
+end try
+OSA
+}
+
+# Dual-mode chooser. DEFAULT = the validate-first SETUP flow (this Mac shows a
+# short code; the portal proves every camera stream BEFORE anything is
+# created). "Classic code…" keeps the legacy portal-minted claim-code flow
+# working (old wizard versions, scripted installs). Echoes "setup"|"classic",
+# exits 2 on cancel.
+dialog_choose_mode() {
+  osascript <<'OSA' 2>/dev/null
+try
+  set theResult to display dialog "Connect this Mac's cameras to Trillboards." & return & return & "Start setup: this window shows a code, you type it in the portal, and the portal checks every camera BEFORE anything is created." with title "Trillboards Edge — Camera setup" buttons {"Cancel", "Classic code…", "Start setup"} default button "Start setup" with icon note
+  if button returned of theResult is "Start setup" then
+    return "setup"
+  else
+    return "classic"
+  end if
+on error
+  error "cancelled" number 2
+end try
+OSA
+}
+
+dialog_info() {  # $1 = message
+  osascript -e "display dialog \"$1\" with title \"Trillboards Edge\" buttons {\"OK\"} default button \"OK\" with icon note" >/dev/null 2>&1 || true
+}
+dialog_error() { # $1 = message
+  osascript -e "display dialog \"$1\" with title \"Trillboards Edge — Pairing failed\" buttons {\"OK\"} default button \"OK\" with icon stop" >/dev/null 2>&1 || true
+}
+
+# The ONE true remediation for "config dir/file owned by another account" — the
+# signature of a .pkg installed with admin rights (its postinstall ran as root
+# and left ~/Library/Application Support/Trillboards ROOT-OWNED). Names the REAL
+# cause + the exact one-line fix; deliberately NEVER "check the code". Kept in
+# one place so the pre-write guard AND the post-pair failure branch say the same
+# thing (and match cli.ts configWritePermissionMessage). Real newlines mirror the
+# working multi-line dialog below; single-quotes make the command copy-pasteable
+# and are safe to interpolate into osascript's double-quoted string (no " / \).
+# $1 = "fresh" when this fires AFTER the connector already spent the one-time
+# claim code (post-pair net), so the operator must get a NEW code — not reuse the
+# consumed one. The pre-write guards fire BEFORE the code is spent → default.
+perm_remediation_msg() {
+  cat <<MSG
+Trillboards can't save its settings because
+  $APP_SUPPORT
+(or the config file inside it) is owned by another account — the installer ran
+with admin rights. This is NOT a code problem.
+
+Fix ownership once by pasting this in Terminal:
+
+  sudo chown -R $(whoami) '$APP_SUPPORT'
+MSG
+  if [ "${1:-}" = "fresh" ]; then
+    printf '\n%s\n' "Then generate a NEW pairing code in the portal (the last one was already used) and run pairing again."
+  else
+    printf '\n%s\n' "Then run pairing again."
+  fi
+}
+
+# Substitute the plist template tokens with this machine's real paths and load
+# the per-user LaunchAgent (bootstrap on modern macOS, load as fallback).
+bootstrap_agent() {
+  /usr/bin/sed \
+    -e "s|__LAUNCHER__|$LAUNCHER|g" \
+    -e "s|__CONFIG__|$CONFIG|g" \
+    -e "s|__LOG_DIR__|$LOG_DIR|g" \
+    "$PLIST_TEMPLATE" > "$PLIST"
+
+  local uid; uid="$(id -u)"
+  # Reload cleanly: tear down any prior instance first (ignore errors).
+  launchctl bootout "gui/$uid/$LABEL" >/dev/null 2>&1 || true
+  launchctl unload "$PLIST" >/dev/null 2>&1 || true
+
+  if launchctl bootstrap "gui/$uid" "$PLIST" >/dev/null 2>&1; then
+    run_with_timeout 10 launchctl kickstart -k "gui/$uid/$LABEL" >/dev/null 2>&1 \
+      || plog "agent: launchctl kickstart did not finish cleanly (continuing to running check)"
+    return 0
+  fi
+  # Fallback for older macOS.
+  if launchctl load -w "$PLIST" >/dev/null 2>&1; then
+    return 0
+  fi
+  return 1
+}
+
+# Count paired feeds that still need an rtspUrl (creds-stay-on-prem mode: the
+# server delivers the screen + token, the operator pastes the camera URL into
+# this machine's config). Echoes the count (0 = all feeds ready). Mirrors the
+# `needRtsp` guard in cli.ts runPair so the GUI helper never bootstraps a
+# LaunchAgent that would crash-loop on a config whose feeds have no URL.
+count_feeds_missing_rtsp() {
+  [ -f "$CONFIG" ] || { echo 0; return; }
+  [ -x "$NODE_BIN" ] || { echo 0; return; }   # can't parse → don't block
+  "$NODE_BIN" -e '
+    try {
+      const cfg = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+      const feeds = Array.isArray(cfg.cameras)
+        ? cfg.cameras
+        : (cfg.camera && (cfg.camera.rtspUrl || cfg.deviceToken) ? [cfg.camera] : []);
+      const missing = feeds.filter((f) => !f || !f.rtspUrl).length;
+      process.stdout.write(String(missing));
+    } catch (e) { process.stdout.write("0"); }
+  ' "$CONFIG" 2>/dev/null || echo 0
+}
+
+# ─── Guard: the config dir must be WRITABLE by us ────────────────────────────
+# If the .pkg was installed with admin rights (system domain), its postinstall
+# ran as root and may have left $APP_SUPPORT ROOT-OWNED. We run as the normal
+# user, so writing the paired config there dies with EACCES — which historically
+# surfaced as the misleading "Double-check the code (codes expire)". Detect it up
+# front (before we even ask for a code), self-heal the common empty-dir case,
+# else FAIL LOUDLY with the real cause + the one-line fix.
+if [ -e "$APP_SUPPORT" ] && [ ! -w "$APP_SUPPORT" ]; then
+  # Best-effort self-heal. We run as the user, so we can't chown a root-owned
+  # dir — but we CAN (a) fix perms on a dir we already own, or (b) replace an
+  # EMPTY dir, since its parent (~/Library/Application Support) is ours. rmdir
+  # only succeeds when the dir is empty, so this can NEVER destroy a real config.
+  chmod u+rwx "$APP_SUPPORT" 2>/dev/null || true
+  if [ ! -w "$APP_SUPPORT" ]; then
+    { rmdir "$APP_SUPPORT" 2>/dev/null && mkdir -p "$APP_SUPPORT" 2>/dev/null; } || true
+    chmod 700 "$APP_SUPPORT" 2>/dev/null || true
+  fi
+fi
+if [ -e "$APP_SUPPORT" ] && [ ! -w "$APP_SUPPORT" ]; then
+  if is_ui; then
+    write_ui_status error "Camera settings need permission" "Reinstall Trillboards for this account. If the problem continues, contact Trillboards support."
+  elif is_headless; then
+    printf '[trillboards-pair] ERROR: %s\n' "$(perm_remediation_msg)" >&2
+  else
+    dialog_error "$(perm_remediation_msg)"
+  fi
+  exit 1
+fi
+
+# The config FILE itself may be root-owned inside an otherwise-writable dir (a
+# prior admin run wrote it as root). The paired-config write would then EACCES
+# AFTER the connector already CONSUMED the one-time claim code — so heal it HERE,
+# before we spend the code. We own the parent dir, so we can just remove the
+# stale file (pairing rewrites it); only if that's somehow impossible do we stop
+# — and because this is still before the launcher, the code is unspent, so the
+# default "run pairing again" is correct.
+if [ -e "$CONFIG" ] && [ ! -w "$CONFIG" ]; then
+  rm -f "$CONFIG" 2>/dev/null || true
+fi
+if [ -e "$CONFIG" ] && [ ! -w "$CONFIG" ]; then
+  if is_ui; then
+    write_ui_status error "Camera settings need permission" "Reinstall Trillboards for this account. If the problem continues, contact Trillboards support."
+  elif is_headless; then
+    printf '[trillboards-pair] ERROR: %s\n' "$(perm_remediation_msg)" >&2
+  else
+    dialog_error "$(perm_remediation_msg)"
+  fi
+  exit 1
+fi
+
+# ─── Battery caution (non-blocking) ──────────────────────────────────────────
+# Sensing dies silently if this Mac sleeps or shuts down. The connector holds a
+# caffeinate keep-awake while running, but a closed lid still stops it.
+if pmset -g batt 2>/dev/null | grep -q "Battery Power"; then
+  BATT_NOTE="Note: this Mac is on battery. Keep it plugged in and awake — your cameras stop reporting if it sleeps or shuts down."
+  if is_ui; then plog "power: running on battery"; elif is_headless; then echo "[trillboards-pair] $BATT_NOTE"; else dialog_info "$BATT_NOTE"; fi
+fi
+
+# ─── Resume path: a saved, complete pairing skips the code prompt ─────────────
+# Branch on WHY verification failed: only an auth rejection (3) or a token-less
+# config (4) needs a new code — a network/server failure (2/5) means the saved
+# pairing is fine and the operator just fixes connectivity (NO new code).
+if [ -f "$CONFIG" ] && [ "$(count_feeds_missing_rtsp)" = "0" ]; then
+  set +e
+  verify_saved_pairing
+  VERIFY_RC=$?
+  set -e
+  case "$VERIFY_RC" in
+    0)
+      plog "resume: existing config verified — skipping code prompt"
+      if is_headless; then
+        echo "[trillboards-pair] already paired (connection verified) — ensuring the background agent runs"
+      fi
+      CODE=""   # sentinel: skip the pair exchange below
+      ;;
+    2|5)
+      plog "resume: saved config, connection check failed (rc=$VERIFY_RC)"
+      MSG="This Mac already has a saved Trillboards pairing, but it can't reach Trillboards right now. Check the internet connection, then run this helper again — you will NOT need a new code."
+      if is_ui; then write_ui_status error "This computer is offline" "Check the internet connection, then try again. Your saved pairing is still secure."; elif is_headless; then echo "[trillboards-pair] $MSG" >&2; else dialog_error "$MSG"; fi
+      exit 1
+      ;;
+    *) : ;;   # 3/4 → genuinely re-pair below
+  esac
+fi
+
+# ─── Choose mode / get the code ──────────────────────────────────────────────
+if [ "${CODE+set}" = "set" ] && [ -z "$CODE" ]; then
+  : # resume path — already paired + verified, jump straight to the agent stage
+elif [ "${SETUP_MODE:-0}" = "1" ]; then
+  : # --setup flag (headless/scripted) — handled below
+elif is_headless; then
+  CODE="$HEADLESS_CODE"
+else
+  MODE="$(dialog_choose_mode)" || exit 0   # cancelled — nothing to do
+  if [ "$MODE" = "setup" ]; then
+    SETUP_MODE=1
+  else
+    if ! CODE="$(dialog_get_code)"; then
+      exit 0   # user cancelled — nothing to do
+    fi
+    if [ -z "$CODE" ]; then
+      dialog_error "No code entered. Re-run the pairing helper and paste the code from the portal."
+      exit 1
+    fi
+  fi
+fi
+
+# ─── Validate-first setup mode ────────────────────────────────────────────────
+# The CLI displays progress in legacy/headless mode or writes structured status
+# for the native app. It exits 0 once the portal finalizes cameras, then the same
+# LaunchAgent stages at the bottom of this script run. rc=2 = expired/timeout.
+if [ "${SETUP_MODE:-0}" = "1" ]; then
+  plog "setup: starting validate-first setup mode"
+  set +e
+  if is_ui; then
+    "$LAUNCHER" setup --config "$CONFIG" --status-file "$UI_STATUS_FILE"
+  else
+    "$LAUNCHER" setup --config "$CONFIG"
+  fi
+  SETUP_RC=$?
+  set -e
+  if [ "$SETUP_RC" -eq 0 ]; then
+    plog "setup: config received"
+    CODE=""   # fall through to the agent stage exactly like the resume path
+  elif [ "$SETUP_RC" -eq 3 ]; then
+    plog "setup: server 404 (rc=3) — classic fallback"
+    if is_ui; then
+      write_ui_status error "Setup is temporarily unavailable" "Try again shortly or contact Trillboards support."
+      exit 1
+    fi
+    if ! CODE="$(dialog_get_code)"; then exit 0; fi
+    if [ -z "$CODE" ]; then
+      dialog_error "No code entered. Re-run the pairing helper and paste the code from the portal."
+      exit 1
+    fi
+    SETUP_MODE=0
+  elif [ "$SETUP_RC" -eq 2 ]; then
+    plog "setup: expired/timeout (rc=2)"
+    if is_ui; then write_ui_status error "Setup ended before finishing" "Try again when you are ready. No cameras were created."; else dialog_info "Setup ended without finishing (expired or timed out). Open this helper again to start over — nothing was created, nothing is lost."; fi
+    exit 1
+  else
+    plog "setup: failed (rc=$SETUP_RC)"
+    if is_ui; then write_ui_status error "Setup needs attention" "Try again. If the problem continues, contact Trillboards support."; else dialog_error "Setup hit an error. Details were saved to: $LOG_DIR/pairing.log — send that file to Trillboards support if it keeps happening."; fi
+    exit 1
+  fi
+fi
+
+# ─── Pair (skipped on the verified-resume path) ──────────────────────────────
+# `pair` exit codes: 0 = paired + connection VERIFIED; 6 = paired + config saved
+# but the connection check failed (code is SPENT — re-running needs NO new code);
+# anything else = pairing failed with a classified, owner-grade reason already
+# printed by the CLI (bad/expired code vs network vs rate-limit vs server).
+if [ -n "${CODE:-}" ]; then
+  PAIR_ARGS=(pair --code "$CODE" --config "$CONFIG")
+  [ -n "$API_BASE" ] && PAIR_ARGS+=(--api-base "$API_BASE")
+
+  SAVED_UNVERIFIED_MSG="Paired and saved, but this Mac can't reach Trillboards right now. Fix the internet connection, then run this helper again — it resumes automatically and you will NOT need a new code."
+  # rc=7: the API REJECTED the fresh pairing (auth) — unlike rc=6 the saved
+  # config is unusable and the owner genuinely needs a new code.
+  AUTH_REJECTED_MSG="Trillboards rejected this new pairing. Generate a FRESH code in the portal and run this helper again."
+
+  if is_headless; then
+    echo "[trillboards-pair] pairing (headless)…"
+    set +e
+    "$LAUNCHER" "${PAIR_ARGS[@]}"
+    PAIR_RC=$?
+    set -e
+    if [ "$PAIR_RC" -eq 0 ]; then
+      echo "[trillboards-pair] paired + connection verified → $CONFIG"
+      plog "pair: ok (verified)"
+    elif [ "$PAIR_RC" -eq 6 ]; then
+      echo "[trillboards-pair] $SAVED_UNVERIFIED_MSG" >&2
+      plog "pair: saved but unverified (rc=6)"
+      exit 1
+    elif [ "$PAIR_RC" -eq 7 ]; then
+      echo "[trillboards-pair] $AUTH_REJECTED_MSG" >&2
+      plog "pair: saved but auth-rejected (rc=7)"
+      exit 1
+    else
+      echo "[trillboards-pair] PAIRING FAILED" >&2
+      plog "pair: failed (rc=$PAIR_RC)"
+      exit 1
+    fi
+  else
+    set +e
+    PAIR_OUT="$("$LAUNCHER" "${PAIR_ARGS[@]}" 2>&1)"
+    PAIR_RC=$?
+    set -e
+    if [ "$PAIR_RC" -eq 6 ]; then
+      plog "pair: saved but unverified (rc=6)"
+      dialog_info "$SAVED_UNVERIFIED_MSG"
+      exit 1
+    elif [ "$PAIR_RC" -eq 7 ]; then
+      plog "pair: saved but auth-rejected (rc=7)"
+      dialog_error "$AUTH_REJECTED_MSG"
+      exit 1
+    elif [ "$PAIR_RC" -ne 0 ]; then
+      plog "pair: failed (rc=$PAIR_RC)"
+      # If the connector failed for a PERMISSION reason (config dir/file owned by
+      # another account — an admin install left it root-owned), say THAT + the
+      # one-line fix; do NOT tell the operator to re-check a code that is fine. The
+      # writability pre-check above catches the common root-owned-DIR case first;
+      # this net covers a root-owned config FILE inside an otherwise-writable dir.
+      # Matches a raw EACCES AND cli.ts's clean message ("owned by another
+      # account" / "sudo chown").
+      if printf '%s' "$PAIR_OUT" | grep -qiE 'permission denied|EACCES|EPERM|owned by another account|sudo chown'; then
+        # Reached only if a permission failure slipped past the pre-write guards
+        # above — by now the connector has already spent the one-time code, so tell
+        # the operator to fix ownership AND get a fresh code.
+        dialog_error "$(perm_remediation_msg fresh)"
+      else
+        # The CLI's last lines carry the classified reason — show them verbatim
+        # instead of the historical blanket "Double-check the code" (a lie for
+        # network/server failures; only the CLI knows which it was).
+        dialog_error "Pairing did not complete.\n\n$(printf '%s' "$PAIR_OUT" | tail -6)"
+      fi
+      exit 1
+    fi
+    plog "pair: ok (verified)"
+  fi
+fi
+
+# ─── Gate on RTSP URLs, then bootstrap the LaunchAgent ───────────────────────
+# In creds-stay-on-prem mode the server returns cameras WITHOUT an rtspUrl, and
+# the connector writes those as empty placeholders. Starting the LaunchAgent now
+# would crash-loop (`cloud-sense` skips URL-less feeds and exits with nothing to
+# run) while the dialog claims "Paired and running" — so if ANY feed still needs
+# a URL, skip the bootstrap and tell the operator to add the URL(s) first, then
+# start. Mirrors the `needRtsp` guard in cli.ts runPair.
+MISSING_RTSP="$(count_feeds_missing_rtsp)"
+if [ "${MISSING_RTSP:-0}" -gt 0 ] 2>/dev/null; then
+  MSG="Paired ($MISSING_RTSP camera feed(s) still need an RTSP URL). Camera credentials stay on this Mac — add the rtsp:// URL(s) to:
+$CONFIG
+then run 'trillboards-edge auto-sense' (or re-run this pairing helper) to start. The background agent was NOT started yet so it won't crash-loop on an incomplete config."
+  if is_ui; then
+    write_ui_status error "Camera links are incomplete" "One or more cameras still need a stream link. Contact Trillboards support."
+  elif is_headless; then
+    echo "[trillboards-pair] $MISSING_RTSP feed(s) missing rtspUrl — NOT bootstrapping LaunchAgent. Add URL(s) to $CONFIG then run auto-sense." >&2
+  else
+    dialog_info "$MSG"
+  fi
+  exit 0
+fi
+
+# The config is complete and verified. Local AI was installed before this wizard
+# opened; confirm it is still healthy before starting the camera service.
+write_ui_status local_ai "Checking local AI" "The cameras are ready. Verifying the private AI service installed with Trillboards."
+if ! verify_local_ai_setup; then
+  write_ui_status local_ai_error "Local AI needs attention" "The included local AI could not be started. Reinstall Trillboards CCTV Setup; your camera pairing is saved."
+  exit 1
+fi
+
+write_ui_status starting_service "Starting Trillboards" "Installing and verifying the background camera service."
+
+# "Bootstrapped" alone is not success — verify the agent PROCESS is actually
+# running before telling the owner anything is running (the Windows twin of this
+# lie left a 16-camera install "paired" with a never-registered task).
+if bootstrap_agent && wait_agent_running; then
+  plog "agent: bootstrapped + running"
+  MSG="Paired and running. Local AI is installed and healthy. Trillboards starts automatically at login."
+  write_ui_status ready "Camera setup is complete" "Trillboards and private local AI are running in the background."
+  if is_ui; then :; elif is_headless; then echo "[trillboards-pair] LaunchAgent running ($LABEL)"; else dialog_info "$MSG"; fi
+  exit 0
+fi
+
+plog "agent: bootstrap or start FAILED (not running after wait)"
+MSG="Paired successfully, but the background agent did not start. Your pairing IS saved — nothing is lost. Try restarting this Mac (the agent starts at login). If it still fails, send this file to Trillboards support: $LOG_DIR/pairing.log (plus edge.err.log in the same folder)."
+if is_ui; then write_ui_status error "Cameras paired, service not running" "Restart this Mac, then open Trillboards CCTV Setup again. Your pairing is saved."; elif is_headless; then echo "[trillboards-pair] ERROR: $MSG" >&2; else dialog_error "$MSG"; fi
+exit 1

package/deploy/macos/scripts/ensure-litertlm.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# Keep installer-provisioned local AI healthy across transient service or
+# package-runtime failures. The inner setup script is idempotent and owns its
+# own lock; this wrapper owns a second lock so pairing and auto-sense launches
+# collapse into one retry loop.
+
+set -u
+USER_HOME="${HOME:-$(eval echo "~$(id -un)")}"
+ROOT="$USER_HOME/Library/Trillboards/edge"
+SETUP="$ROOT/share/setup-litertlm.sh"
+LOG_DIR="$USER_HOME/Library/Logs/Trillboards"
+LOCK_DIR="$LOG_DIR/litertlm-ensure.lock"
+HEALTH_URL="${LITERT_LM_HEALTH_URL:-http://127.0.0.1:9379/v1/models}"
+MODEL_ID="gemma-4-E2B-it.litertlm"
+MAX_DELAY_SECONDS="${LITERT_LM_RETRY_MAX_SECONDS:-300}"
+
+mkdir -p "$LOG_DIR" 2>/dev/null || true
+LOG="$LOG_DIR/litertlm-setup.log"
+log() { printf '[trillboards ensure-litertlm] %s %s\n' "$(date '+%H:%M:%S')" "$*" >>"$LOG" 2>&1; }
+local_ai_healthy() {
+  /usr/bin/curl --fail --silent --show-error --max-time 5 "$HEALTH_URL" 2>/dev/null |
+    /usr/bin/grep -Fq "$MODEL_ID"
+}
+
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  LOCK_PID="$(cat "$LOCK_DIR/pid" 2>/dev/null || echo '')"
+  if [ -n "$LOCK_PID" ] && kill -0 "$LOCK_PID" 2>/dev/null; then
+    log "provisioning retry loop is already running (pid $LOCK_PID)"
+    exit 0
+  fi
+  rm -rf "$LOCK_DIR" 2>/dev/null || true
+  mkdir "$LOCK_DIR" 2>/dev/null || exit 0
+fi
+printf '%s\n' "$$" >"$LOCK_DIR/pid" 2>/dev/null || true
+cleanup() { rm -rf "$LOCK_DIR" 2>/dev/null || true; }
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+if [ ! -f "$SETUP" ]; then
+  log "setup script is missing at $SETUP"
+  exit 1
+fi
+
+delay=30
+attempt=0
+while ! local_ai_healthy; do
+  attempt=$((attempt + 1))
+  log "provisioning attempt $attempt"
+  TRILLBOARDS_REQUIRE_BUNDLED_MODEL=1 /bin/bash "$SETUP" >>"$LOG" 2>&1 || true
+  if local_ai_healthy; then
+    log "local AI is healthy"
+    exit 0
+  fi
+  log "local AI is not ready; retrying in ${delay}s"
+  sleep "$delay"
+  delay=$((delay * 2))
+  if [ "$delay" -gt "$MAX_DELAY_SECONDS" ]; then delay="$MAX_DELAY_SECONDS"; fi
+done
+
+log "local AI was already healthy"
+exit 0