@trillboards/edge-sdk 0.2.74 → 0.2.78

package/deploy/detector/trillboards_detector/session.py

@@ -0,0 +1,354 @@
+"""The ONNX session, and the pre/post-processing that must match the reference.
+
+WHY THE PROCESSING IS TRANSCRIBED RATHER THAN IMPORTED
+-----------------------------------------------------
+The score in `docs/runbooks/cctv-detector-tier.md` (98.8/98.8 pooled, 2.1% of
+events lost to buy 84.7% of VLM calls) was produced by the `rfdetr` package's
+own `predict()`. That package pulls torch + torchvision + transformers — about
+3 GB — which is not going on a shop PC to run a 128 MiB graph. So the four steps
+that decide whether the shipped service reproduces the measured number are
+transcribed here from the exact call sites, each named in the function that
+implements it:
+
+  resize    `rfdetr/detr.py`  F.resize(t, [576, 576], antialias=False)
+  normalize `rfdetr/detr.py`  F.normalize(t, [0.485,0.456,0.406], [0.229,0.224,0.225])
+  select    `rfdetr/models/postprocess.py::PostProcess._select_topk`
+  boxes     `rfdetr/models/postprocess.py::PostProcess._gather_and_scale_boxes`
+
+`antialias=False` is not a detail to tidy up: the upstream comment says it
+matches the antialias-free bilinear resize Albumentations uses in training, and
+changing it changes the pixels the model was scored on. Likewise the resize is a
+STRETCH to a square, not a letterbox — aspect ratio is not preserved, and
+"fixing" that silently re-scores every box.
+
+A transcription can drift from its source. `bench/verify_against_reference.py`
+is the control: it runs this pipeline and the `rfdetr` package on the same image
+and fails on any disagreement.
+"""
+
+from __future__ import annotations
+
+import io
+import math
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+import onnxruntime as ort
+from PIL import Image
+
+from .labels import COCO91_CLASS_NAMES, EXPECTED_LOGIT_SLOTS
+
+#: `rfdetr/detr.py` — ImageNet statistics, applied AFTER scaling to [0,1].
+IMAGENET_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32).reshape(3, 1, 1)
+IMAGENET_STD = np.array([0.229, 0.224, 0.225], dtype=np.float32).reshape(3, 1, 1)
+
+#: `PostProcess.__init__(num_select=300)`. The graph emits 300 queries x 91
+#: classes = 27,300 (query, class) pairs and the reference keeps the best 300 of
+#: them BEFORE thresholding. Reproduced exactly: thresholding first would return
+#: rows the measured arm never saw on a busy frame.
+NUM_SELECT = 300
+
+
+@dataclass(frozen=True)
+class Detection:
+    """One wire-shaped detection. Pixel box, canonical label, [0,1] confidence."""
+
+    label: str
+    confidence: float
+    x: float
+    y: float
+    width: float
+    height: float
+
+
+@dataclass
+class DetectionBatch:
+    detections: list[Detection]
+    #: The ORT forward pass alone, in ms — directly comparable to the ~63 ms in
+    #: `docs/runbooks/cctv-detector-tier.md`. Decode and post-processing are
+    #: reported separately (`total_ms`) so a slow JPEG decode cannot hide inside
+    #: a number the runbook will later be checked against.
+    inference_ms: float = 0.0
+    total_ms: float = 0.0
+    #: Boxes that survived the threshold but cover no pixels after clamping to
+    #: the frame. Counted, never silently swallowed — see `_to_wire`.
+    degenerate_dropped: int = 0
+    #: Detections whose argmax landed on one of the eleven COCO id gaps.
+    unnamed_class_dropped: int = 0
+
+
+@dataclass
+class GraphSpec:
+    """What the loaded artifact actually is, read off the graph, never assumed."""
+
+    input_name: str
+    box_output: str
+    logit_output: str
+    height: int
+    width: int
+    num_queries: int
+    num_classes: int
+    providers: list[str] = field(default_factory=list)
+
+
+class ModelContractError(RuntimeError):
+    """The artifact loaded, but it is not the graph this service can label."""
+
+
+def preprocess(jpeg: bytes, width: int, height: int) -> tuple[np.ndarray, int, int]:
+    """JPEG bytes -> NCHW float32, plus the SUBMITTED frame's pixel size.
+
+    The submitted size is what boxes are scaled back to, so it is returned here
+    rather than re-read later: the frame is decoded exactly once.
+    """
+    with Image.open(io.BytesIO(jpeg)) as im:
+        rgb = im.convert("RGB")
+        src_w, src_h = rgb.size
+        # BILINEAR without a prefilter == torchvision's antialias=False path.
+        # `Image.BILINEAR` in Pillow does not low-pass on downscale, which is
+        # the behaviour being matched. Do not "improve" this to LANCZOS.
+        resized = rgb.resize((width, height), resample=Image.BILINEAR)
+        arr = np.asarray(resized, dtype=np.float32)
+
+    chw = arr.transpose(2, 0, 1) / np.float32(255.0)
+    chw -= IMAGENET_MEAN
+    chw /= IMAGENET_STD
+    return chw[None, ...], src_w, src_h
+
+
+def postprocess(
+    boxes_cxcywh: np.ndarray,
+    logits: np.ndarray,
+    frame_w: int,
+    frame_h: int,
+    min_confidence: float,
+    wanted: "set[str] | None" = None,
+) -> DetectionBatch:
+    """Raw graph outputs -> wire detections, in the submitted frame's pixels.
+
+    Mirrors `PostProcess._select_topk` and `_gather_and_scale_boxes`.
+
+    `wanted` filters HERE, at the service, because the alternative is shipping
+    every box across loopback to throw most away — `LocalDetectorClient`'s own
+    reasoning, and the reason `classes` rides the wire at all.
+    """
+    # (1, Q, C) -> (Q, C); the graph is batch-1 by construction.
+    prob = _sigmoid(logits[0])
+    flat = prob.reshape(-1)
+    n_classes = prob.shape[1]
+
+    num_to_select = min(NUM_SELECT, flat.size)
+    # torch's `argsort(descending=True, stable=True)`: descending score, ties
+    # broken by ascending flattened index. Negating and sorting ascending-stable
+    # is the same order; `np.argsort(...)[::-1]` is NOT (it reverses ties too).
+    order = np.argsort(-flat, kind="stable")[:num_to_select]
+    scores = flat[order]
+    query_idx = order // n_classes
+    class_idx = order % n_classes
+
+    keep = scores > min_confidence
+    scores = scores[keep]
+    query_idx = query_idx[keep]
+    class_idx = class_idx[keep]
+
+    sel = boxes_cxcywh[0][query_idx]
+    cx, cy, w, h = sel[:, 0], sel[:, 1], sel[:, 2], sel[:, 3]
+    x0 = np.clip((cx - 0.5 * w) * frame_w, 0.0, frame_w)
+    y0 = np.clip((cy - 0.5 * h) * frame_h, 0.0, frame_h)
+    x1 = np.clip((cx + 0.5 * w) * frame_w, 0.0, frame_w)
+    y1 = np.clip((cy + 0.5 * h) * frame_h, 0.0, frame_h)
+
+    return _to_wire(scores, class_idx, x0, y0, x1, y1, wanted)
+
+
+def _to_wire(
+    scores: np.ndarray,
+    class_idx: np.ndarray,
+    x0: np.ndarray,
+    y0: np.ndarray,
+    x1: np.ndarray,
+    y1: np.ndarray,
+    wanted: "set[str] | None",
+) -> DetectionBatch:
+    """Assemble detections, dropping only what CANNOT be put on the wire.
+
+    Two drops, and each is counted rather than swallowed:
+
+    * an UNNAMED CLASS SLOT. Eleven of the ninety-one slots are COCO id gaps
+      with no name. `docs/runbooks/cctv-detector-tier.md` §5 rule 2 forbids
+      guessing; a detection with no nameable class is dropped.
+    * a ZERO-EXTENT BOX. A box clamped flush against a frame edge can have zero
+      width or height, and `LocalDetectorClient` REJECTS THE ENTIRE PAYLOAD on
+      one — correctly, since it cannot tell a schema-drifted service from a
+      quiet venue. Emitting one would turn a numerical edge into the total loss
+      of a frame's result, so it is dropped here instead.
+
+    Neither is the "skip a malformed entry" defect the client warns about. That
+    is about a SERVICE that has stopped speaking the contract, where an
+    undercount is indistinguishable from an emptier frame. These two are the
+    producer declining to emit a box that describes no pixels and a class that
+    has no name — and both increment a counter `/health` publishes, so the
+    failure can report itself.
+    """
+    out: list[Detection] = []
+    degenerate = 0
+    unnamed = 0
+
+    for i in range(scores.shape[0]):
+        name = COCO91_CLASS_NAMES.get(int(class_idx[i]))
+        if name is None:
+            unnamed += 1
+            continue
+        if wanted is not None and name not in wanted:
+            continue
+
+        left, top = float(x0[i]), float(y0[i])
+        width, height = float(x1[i]) - left, float(y1[i]) - top
+        if not (width > 0.0 and height > 0.0):
+            degenerate += 1
+            continue
+
+        conf = float(scores[i])
+        if not math.isfinite(conf):
+            # A non-finite confidence is unrepresentable on the wire and the
+            # client refuses the whole payload on one. sigmoid cannot produce
+            # it, so reaching here means the graph did — which is a load-bearing
+            # surprise, not a row to drop quietly.
+            raise ModelContractError(f"model produced a non-finite confidence at index {i}")
+        # sigmoid is (0,1); clamp only guards float64 round-trip at the edges.
+        out.append(Detection(name, min(1.0, max(0.0, conf)), left, top, width, height))
+
+    return DetectionBatch(out, degenerate_dropped=degenerate, unnamed_class_dropped=unnamed)
+
+
+def _sigmoid(x: np.ndarray) -> np.ndarray:
+    # Branch on sign so neither exp() overflows; np.exp(710) is inf.
+    pos = x >= 0
+    out = np.empty_like(x, dtype=np.float64)
+    out[pos] = 1.0 / (1.0 + np.exp(-x[pos].astype(np.float64)))
+    e = np.exp(x[~pos].astype(np.float64))
+    out[~pos] = e / (1.0 + e)
+    return out
+
+
+class OnnxDetector:
+    """One ORT session, one inference at a time.
+
+    SERIALISED ON PURPOSE. `docs/runbooks/cctv-detector-tier.md` §2 measures
+    threads as NON-MONOTONIC — 16 threads (99.9 ms) is slower than 6 (78-83) and
+    slower than ORT's own auto heuristic (63.9) — so "use all cores" is wrong,
+    and so is letting N concurrent HTTP requests each start an intra-op thread
+    pool's worth of work on the same box. The detector gates the ANALYZE
+    cadence, where §2 measured that nothing binds (hundreds of cameras clear at
+    every thread count, holding under 5x pessimisation), so a queue costs
+    nothing that was ever measured to matter.
+
+    Thread counts are therefore LEFT AT ORT'S DEFAULT unless an operator
+    overrides them. Pinning them is the mistake the same section names.
+    """
+
+    def __init__(self, model_path: Path, model_name: str, intra_op_threads: "int | None" = None):
+        self.model_path = model_path
+        self.model_name = model_name
+        self._lock = threading.Lock()
+
+        opts = ort.SessionOptions()
+        if intra_op_threads is not None:
+            opts.intra_op_num_threads = intra_op_threads
+        # Loopback service, one process, one model: log only what a fault needs.
+        opts.log_severity_level = 3
+
+        self._session = ort.InferenceSession(
+            str(model_path), sess_options=opts, providers=["CPUExecutionProvider"]
+        )
+        self.spec = _read_graph_spec(self._session)
+
+    def detect(
+        self,
+        jpeg: bytes,
+        min_confidence: float,
+        wanted: "set[str] | None" = None,
+    ) -> DetectionBatch:
+        started = time.perf_counter()
+        blob, frame_w, frame_h = preprocess(jpeg, self.spec.width, self.spec.height)
+
+        with self._lock:
+            infer_started = time.perf_counter()
+            outputs = self._session.run(
+                [self.spec.box_output, self.spec.logit_output], {self.spec.input_name: blob}
+            )
+            infer_ms = (time.perf_counter() - infer_started) * 1000.0
+
+        batch = postprocess(outputs[0], outputs[1], frame_w, frame_h, min_confidence, wanted)
+        batch.inference_ms = infer_ms
+        batch.total_ms = (time.perf_counter() - started) * 1000.0
+        return batch
+
+
+def _read_graph_spec(session: "ort.InferenceSession") -> GraphSpec:
+    """Read the contract off the loaded graph, and REFUSE a graph we cannot label.
+
+    The exported artifact carries no class metadata, so the label map in
+    `labels.py` is the only thing naming its 91 slots. If the graph's class axis
+    is not 91 wide, that map does not describe it — and applying it anyway
+    renames every object in the venue while every number stays plausible. That
+    is the `yolov8_nano` failure with the sign flipped: instead of a model
+    offered and never loadable, a model loaded and never right.
+
+    So a mismatch raises, the service goes UNHEALTHY with the reason, and
+    nothing is emitted. The 2.1%-of-events figure the placement decision rests
+    on is a claim about ONE artifact; a different one has no score at all.
+    """
+    inputs = session.get_inputs()
+    if len(inputs) != 1:
+        raise ModelContractError(
+            f"expected exactly one graph input, found {[i.name for i in inputs]}"
+        )
+    shape = inputs[0].shape
+    if len(shape) != 4:
+        raise ModelContractError(f"expected an NCHW input, found shape {shape}")
+    _, channels, height, width = shape
+    if channels != 3:
+        raise ModelContractError(f"expected a 3-channel input, found {channels}")
+    if not isinstance(height, int) or not isinstance(width, int):
+        raise ModelContractError(
+            f"expected a fixed input resolution, found {height}x{width}; a dynamic "
+            "axis means the resolution this model was scored at is not recoverable "
+            "from the artifact, and imgsz is one of the two numbers a detector "
+            "arm is meaningless without"
+        )
+
+    outputs = session.get_outputs()
+    by_name = {o.name: o for o in outputs}
+    if "dets" not in by_name or "labels" not in by_name:
+        raise ModelContractError(
+            f"expected `dets` and `labels` outputs, found {sorted(by_name)}"
+        )
+    box_shape = by_name["dets"].shape
+    logit_shape = by_name["labels"].shape
+    if len(box_shape) != 3 or box_shape[2] != 4:
+        raise ModelContractError(f"`dets` is not (N, Q, 4): {box_shape}")
+    if len(logit_shape) != 3:
+        raise ModelContractError(f"`labels` is not (N, Q, C): {logit_shape}")
+
+    num_classes = logit_shape[2]
+    if num_classes != EXPECTED_LOGIT_SLOTS:
+        raise ModelContractError(
+            f"model has {num_classes} class slots; the committed label map describes "
+            f"{EXPECTED_LOGIT_SLOTS}. Refusing rather than labelling boxes by an "
+            "index this map does not name — see labels.py."
+        )
+
+    return GraphSpec(
+        input_name=inputs[0].name,
+        box_output="dets",
+        logit_output="labels",
+        height=int(height),
+        width=int(width),
+        num_queries=int(logit_shape[1]) if isinstance(logit_shape[1], int) else -1,
+        num_classes=int(num_classes),
+        providers=list(session.get_providers()),
+    )

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

@@ -379,6 +379,28 @@ if [ "${1:-}" = "auto-sense" ]; then
   if { [ ! -f "$MODEL_MARKER" ] || [ ! -f "$SERVE_PLIST" ] || [ "$LOCAL_AI_HEALTHY" -ne 1 ]; } && [ -f "$SETUP" ]; then
     nohup /bin/bash "$SETUP" >/dev/null 2>&1 &
   fi
+
+  # The detector cascade, repaired on the same trigger. TWO signals, and the
+  # health one asks only whether the service ANSWERS: its model is OTA'd, so a
+  # correctly-installed detector reports 503 until the artifact lands, and
+  # treating that as broken would reinstall a working tool on every launch.
+  DETECTOR_PLIST="$HOME/Library/LaunchAgents/com.trillboards.detector.plist"
+  DETECTOR_SETUP="$ROOT/share/ensure-detector.sh"
+  # NO `|| echo 000` HERE. curl writes `000` through -w AND exits nonzero when
+  # it cannot connect, so a fallback appends a SECOND value and the variable
+  # becomes `000\n000` -- which equals neither `000` nor any HTTP code, so the
+  # equality test below silently stops firing and the repair path is dead on
+  # exactly the machines that need it. Measured 2026-08-24 against a closed
+  # port: `[000000]`. Caught by codex on this PR.
+  #
+  # Anything that is not a real HTTP status means "not answering": empty (curl
+  # missing entirely) and `000` (could not connect) both trigger the repair.
+  DETECTOR_CODE="$(/usr/bin/curl -s -o /dev/null -w '%{http_code}' --max-time 2 \
+      http://127.0.0.1:9380/health 2>/dev/null)"
+  if { [ ! -f "$DETECTOR_PLIST" ] || [ -z "$DETECTOR_CODE" ] || [ "$DETECTOR_CODE" = "000" ]; } \
+     && [ -f "$DETECTOR_SETUP" ]; then
+    nohup /bin/bash "$DETECTOR_SETUP" >/dev/null 2>&1 &
+  fi
 fi
 
 exec "$HERE/node" "$ROOT/lib/edge-sdk/dist/cli.js" "$@"
@@ -404,7 +426,33 @@ cp "$PKG_ROOT/deploy/macos/scripts/setup-litertlm.sh" "$PAYLOAD/share/setup-lite
 cp "$PKG_ROOT/deploy/litertlm/trillboards_litertlm_shim.py" "$PAYLOAD/share/trillboards_litertlm_shim.py"
 cp "$PKG_ROOT/deploy/macos/scripts/ensure-litertlm.sh" "$PAYLOAD/share/ensure-litertlm.sh"
 cp "$PKG_ROOT/deploy/macos/apply-update.sh" "$PAYLOAD/share/apply-update.sh"
+
+# On-device OBJECT DETECTOR stack: the LaunchAgent template, the provisioner,
+# the retry wrapper, and the Python package SOURCE that `uv tool install` builds
+# into its own venv.
+#
+# THE SOURCE, NOT THE MODEL. The package is a few tens of KB; the 124 MB fp32
+# ONNX it runs is OTA'd by edge-core's ModelManager, because the code-only build
+# is capped at MAX_SLIM_PKG_BYTES = 250 MiB below and the code slice is already
+# ~207 MB — staging the artifact here would `die` on every slim build. It is
+# staged NEXT TO setup-detector.sh because that is where find_detector_source
+# looks first, the same convention trillboards_litertlm_shim.py follows.
+cp "$PKG_ROOT/deploy/macos/com.trillboards.detector.plist" "$PAYLOAD/share/com.trillboards.detector.plist"
+cp "$PKG_ROOT/deploy/macos/scripts/setup-detector.sh" "$PAYLOAD/share/setup-detector.sh"
+cp "$PKG_ROOT/deploy/macos/scripts/ensure-detector.sh" "$PAYLOAD/share/ensure-detector.sh"
+mkdir -p "$PAYLOAD/share/detector"
+# `build/`, `dist/` and `*.egg-info` are excluded for a REASON, not for tidiness:
+# setuptools copies from `build/lib/` on a later build, so a stale one staged
+# into the payload would install the PREVIOUS revision of the service while the
+# installer reported success. The package uses hatchling precisely so it never
+# creates one, and this exclude covers a leftover from an older backend or a
+# hand-run build on a developer's tree.
+rsync -a --exclude '__pycache__' --exclude '*.pyc' --exclude 'bench' \
+  --exclude 'build' --exclude 'dist' --exclude '*.egg-info' \
+  "$PKG_ROOT/deploy/detector/" "$PAYLOAD/share/detector/"
+
 chmod +x "$PAYLOAD/share/setup-litertlm.sh" "$PAYLOAD/share/ensure-litertlm.sh" \
+  "$PAYLOAD/share/setup-detector.sh" "$PAYLOAD/share/ensure-detector.sh" \
   "$PAYLOAD/share/apply-update.sh"
 
 # ─── 7b. Stage the pre-bundled Gemma model (.litertlm) into the payload ───────

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

@@ -0,0 +1,61 @@
+<?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 on-device OBJECT DETECTOR (RF-DETR Medium, fp32
+  ONNX) that gates the analyze cadence in front of the VLM.
+
+  A SECOND service, not a route on the first. `LocalDetectorClient.ts` records
+  the three reasons: `onnxruntime-node` is excluded by name from both installers,
+  `uv tool install` gives one isolated venv per tool name (and `--force` rebuilds
+  litert-lm's from scratch on any version drift, which would take a package added
+  into it with it), and a supervised loopback service is already a solved problem
+  here. Port 9380; litert-lm owns 9379 and is not touched.
+
+  This is a TEMPLATE: setup-detector.sh substitutes __DETECTOR__ (absolute path
+  to the uv-installed `trillboards-detector` binary) / __PORT__ / __LOG_DIR__ and
+  writes the result to ~/Library/LaunchAgents/com.trillboards.detector.plist,
+  then loads it via `launchctl bootstrap gui/$UID`.
+
+  KeepAlive=true + ThrottleInterval=30 exactly as com.trillboards.litertlm.plist.
+  ThrottleInterval is load-bearing here for a specific reason: the model is OTA'd,
+  so on a fresh install this service starts with NO artifact. It is designed to
+  stay up and answer /health with 503 rather than exit — but if it ever did exit
+  early, this is what keeps the failure to a slow retry instead of a hot loop.
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.trillboards.detector</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>__DETECTOR__</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>
+
+  <!--
+    Keep the service's own stdout. The Windows Scheduled Task cannot (a task has
+    no stdout), which is exactly why litert-lm's 2026-08-19 failure on
+    windows-latest is still undiagnosed — see the hardware-floor runbook. On
+    this platform there is no excuse for discarding it.
+  -->
+  <key>StandardOutPath</key>
+  <string>__LOG_DIR__/detector.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>__LOG_DIR__/detector.err.log</string>
+</dict>
+</plist>

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

@@ -0,0 +1,85 @@
+#!/bin/bash
+# Keep the installer-provisioned detector service alive across transient
+# failures. The inner setup script is idempotent and owns its own lock; this
+# wrapper owns a second one so pairing and auto-sense launches collapse into a
+# single retry loop. Mirrors ensure-litertlm.sh.
+#
+# THE HEALTH PREDICATE IS "IT ANSWERS", NOT "IT IS READY", AND THAT IS THE WHOLE
+# DIFFERENCE FROM ensure-litertlm.sh.
+#
+# The detector's model is OTA'd, so a correctly-installed service reports 503
+# for as long as the artifact has not landed — minutes on a fresh install,
+# indefinitely on a box that cannot reach the CDN. Retrying `uv tool install`
+# against that would be a permanent reinstall loop repairing something that is
+# not broken, on a box whose disk has no space preflight anywhere on the model
+# path. So: any HTTP answer means the service is up and this loop is done. The
+# 503-to-200 transition is the loader's job, and it does it without a restart.
+
+set -u
+USER_HOME="${HOME:-$(eval echo "~$(id -un)")}"
+ROOT="$USER_HOME/Library/Trillboards/edge"
+SETUP="$ROOT/share/setup-detector.sh"
+LOG_DIR="$USER_HOME/Library/Logs/Trillboards"
+LOCK_DIR="$LOG_DIR/detector-ensure.lock"
+HEALTH_URL="${TRILLBOARDS_DETECTOR_HEALTH_URL:-http://127.0.0.1:9380/health}"
+MAX_DELAY_SECONDS="${TRILLBOARDS_DETECTOR_RETRY_MAX_SECONDS:-300}"
+MAX_ATTEMPTS="${TRILLBOARDS_DETECTOR_MAX_ATTEMPTS:-5}"
+
+mkdir -p "$LOG_DIR" 2>/dev/null || true
+LOG="$LOG_DIR/detector-setup.log"
+log() { printf '[trillboards ensure-detector] %s %s\n' "$(date '+%H:%M:%S')" "$*" >>"$LOG" 2>&1; }
+
+# ANY status code is a live service. `curl --fail` would call the designed 503 a
+# failure, which is precisely the reinstall loop described above.
+detector_answers() {
+  _code="$(/usr/bin/curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$HEALTH_URL" 2>/dev/null)"
+  [ -n "$_code" ] && [ "$_code" != "000" ]
+}
+
+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 "detector 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
+trap 'rm -rf "$LOCK_DIR" 2>/dev/null || true' EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+if [ ! -f "$SETUP" ]; then
+  log "setup script is missing at $SETUP"
+  exit 1
+fi
+
+if detector_answers; then
+  log "detector service was already answering"
+  exit 0
+fi
+
+# BOUNDED, unlike ensure-litertlm.sh's unbounded loop. That one may retry
+# forever because without Gemma the connector cannot sense at all. This one
+# gates a cost optimisation: if it cannot be provisioned, every frame goes to
+# the VLM exactly as it does today, and an infinite background loop buys nothing
+# for a machine that will get another attempt at the next auto-sense anyway.
+delay=30
+attempt=0
+while [ "$attempt" -lt "$MAX_ATTEMPTS" ]; do
+  attempt=$((attempt + 1))
+  log "detector provisioning attempt $attempt of $MAX_ATTEMPTS"
+  /bin/bash "$SETUP" >>"$LOG" 2>&1 || true
+  if detector_answers; then
+    log "detector service is answering"
+    exit 0
+  fi
+  log "detector is not answering; retrying in ${delay}s"
+  sleep "$delay"
+  delay=$((delay * 2))
+  if [ "$delay" -gt "$MAX_DELAY_SECONDS" ]; then delay="$MAX_DELAY_SECONDS"; fi
+done
+
+log "detector did not come up after $MAX_ATTEMPTS attempts; the VLM keeps handling every frame"
+exit 0

package/deploy/macos/scripts/postinstall

@@ -114,6 +114,34 @@ if [ "$AI_RC" -ne 0 ]; then
 fi
 log "bundled local AI is installed and healthy"
 
+# 3b. The on-device OBJECT DETECTOR service. BEST EFFORT, and deliberately not
+# fatal the way the block above is.
+#
+# Gemma is fatal because without it the connector cannot sense at all. The
+# detector is a CASCADE GATE in front of it: with the detector, ~84.7% of VLM
+# calls are removed for ~2.1% of events; without it every frame simply goes to
+# the VLM, which is what happens today. A cost optimisation must never be able
+# to stop a customer pairing a camera.
+#
+# It also cannot be verified here the way Gemma is: its 124 MB ONNX is OTA'd
+# (the code-only build is capped at 250 MiB and the code slice is already
+# ~207 MB), so at this moment the artifact is legitimately absent and the
+# service correctly reports itself unhealthy. setup-detector.sh checks that it
+# ANSWERS and logs which of the two states it is in.
+DETECTOR_SETUP="$EDGE_ROOT/share/setup-detector.sh"
+if [ -x "$DETECTOR_SETUP" ]; then
+  log "provisioning the on-device object detector (best effort)"
+  if [ "$(id -u)" = "0" ] && [ -n "$OWNER" ] && [ "$OWNER" != "root" ] && [ -n "${LAUNCH_UID:-}" ]; then
+    /bin/launchctl asuser "$LAUNCH_UID" /usr/bin/sudo -u "$OWNER" \
+      /usr/bin/env HOME="$USER_HOME" \
+      /bin/bash "$DETECTOR_SETUP" || log "WARN: detector provisioning did not finish; the VLM keeps handling every frame"
+  else
+    /bin/bash "$DETECTOR_SETUP" || log "WARN: detector provisioning did not finish; the VLM keeps handling every frame"
+  fi
+else
+  log "WARN: detector installer missing at $DETECTOR_SETUP; the VLM keeps handling every frame"
+fi
+
 # 4. Launch the real native setup application. It runs the canonical pairer as
 #    an invisible child process and renders its credential-free progress file,
 #    so customers never see Terminal or a command window. The app itself is