@trillboards/edge-sdk 0.2.104 → 0.2.106

package/deploy/detector/README.md

@@ -133,6 +133,39 @@ states the box is in. The service does not exit when nothing was injected: all
 three supervisors restart on a non-zero exit, and this file's own rule for a
 required input that has not arrived is *start, and report the reason*.
 
+#### Who actually supplies it — added 2026-08-26, because until then NOBODY did
+
+This section described a parameter that existed on both spellings and was passed
+on neither. `TRILLBOARDS_DETECTOR_RAM_BUDGET_MB` appeared in this file, in
+`cli.py`, in `modelpath.py` and in the tests, and in **zero** of the six
+supervisor definitions — so on every fielded box the "not injected" row of the
+table above was not one of two states, it was the only one, and every delivered
+specialist was permanently `idle`.
+
+`ram-budget.js`, in this directory, is the supplier. It is run by the three
+installers, not by this service — the ceiling must stay something this process is
+TOLD — and it derives the number from the box rather than picking one, because
+`docs/runbooks/sensing-model-library.md` §2 is arithmetic about a SET on a
+specific machine and the two measured field boxes are 9.8 GB and 31.4 GB. It
+subtracts the on-device VLM's measured working set, the connector process and the
+capture lane from physical memory, floors the result at the pinned model's own
+footprint (below that `ModelRegistry.__init__` raises and the supervisor
+crash-loops, which is strictly worse than being constrained), and prints the whole
+subtraction with `--explain` so an installer log says why.
+
+Three transports, one number, because the three supervisors differ in what they
+can carry:
+
+| platform | how | why not the other one |
+| --- | --- | --- |
+| Linux | `TRILLBOARDS_DETECTOR_RAM_BUDGET_MB` in `/etc/trillboards/env` | the unit is a static file `install.sh` copies verbatim; there is nothing to template, and both units already declare `EnvironmentFile=-` |
+| macOS | `--ram-budget-mb` in the plist's `ProgramArguments` | the plist IS generated by `setup-detector.sh`, from a template |
+| Windows | `--ram-budget-mb` in the Scheduled Task's argument string | a Scheduled Task action has no environment block, and a User-scope variable would be global machine state |
+
+On every platform, **failing to derive injects nothing** rather than a fallback —
+the "not injected" row stays reachable, and it is the honest thing to report about
+a box we could not measure.
+
 **Eviction is a last-resort safety valve, not the allocator.** It logs a WARNING
 naming the box as oversubscribed against what it was allocated, and `/health`
 carries a top-level `evictions` count — because a service quietly thrashing

package/deploy/detector/ram-budget.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * The detector's RAM ceiling, DERIVED FROM THIS BOX — run by the installer, for
+ * the supervisor to write down.
+ *
+ * ── Why this file exists ────────────────────────────────────────────────────
+ *
+ * `registry.py::_admit` refuses to make any non-pinned model resident unless a
+ * ceiling was injected, and says so out loud:
+ *
+ *     cannot admit ['gh_forklift_combine'] — no RAM ceiling was injected, so this
+ *     service has no basis for a portfolio decision and will not invent one.
+ *
+ * That refusal is correct. What was missing is the other half of it:
+ * `TRILLBOARDS_DETECTOR_RAM_BUDGET_MB` appeared in the detector's source, its
+ * README, its tests and its CHANGELOG, and in ZERO of the six supervisor
+ * definitions — three plists, three units, three Windows scripts. So on every
+ * fielded box the ceiling was absent, and every delivered specialist stayed
+ * permanently `idle` while `/detect` answered 503. Measured on a live GCE
+ * connector on 2026-08-26.
+ *
+ * ── Why the number is derived and not a constant ────────────────────────────
+ *
+ * `docs/runbooks/sensing-model-library.md` §2 is the arithmetic: the binding
+ * field box is a Ryzen 5 7640HS with a measured 9.8 GB carrying 6 of the 9
+ * spec-reporting screens, and Gemma's working set alone is 3.31 GB. **The SUM
+ * has to fit, not each member** — a selector that approves each model
+ * independently approves a set that OOM-kills the box, and the failure then
+ * looks like a camera problem. A hardcoded 4096 is wrong on that box and wrong
+ * again on the 31.4 GB Core Ultra 9 285H beside it in the same table.
+ *
+ * ── Why HERE and not in the service ─────────────────────────────────────────
+ *
+ * `registry.py`'s header settles it: a ceiling chosen by the detector would be a
+ * SECOND allocation authority that cannot see the first. So the service still
+ * has no default and still refuses; this runs at INSTALL time, in the
+ * installer, and the supervisor records the answer in its own definition where
+ * an operator can read it and override it.
+ *
+ * It also could not honestly live in the Python package: every quantity it
+ * subtracts is a CONNECTOR cost — Gemma's working set, the connector process,
+ * one ffmpeg per feed — and the detector knows none of them. It sits in
+ * `deploy/detector/` because that is the one directory all three installers
+ * already resolve a path to (`find_detector_source` / `Resolve-DetectorSource`),
+ * so no packaging step had to change on any platform. It is NOT part of the
+ * Python distribution: `pyproject.toml` declares
+ * `packages = ["trillboards_detector"]`, so the wheel never sees this file.
+ *
+ * ── Node, and only Node built-ins ───────────────────────────────────────────
+ *
+ * ONE implementation for three supervisors. A bash twin and a PowerShell twin
+ * would be two more places for the arithmetic to drift, and `os.totalmem()` is
+ * the same probe on all three. Node is present wherever this runs: `install.sh`
+ * requires >= 18 before anything else, the macOS pkg bundles `$ROOT/bin/node`
+ * and the Windows payload bundles `bin\node.exe`.
+ *
+ * ── Contract ────────────────────────────────────────────────────────────────
+ *
+ *   stdout   the ceiling, as a bare integer number of MiB. Nothing else, so a
+ *            caller can `$(node ram-budget.js)` it.
+ *   stderr   with --explain, the whole subtraction, so an operator reading a
+ *            setup log can see WHY the number is what it is.
+ *   exit 0   derived. exit 1: could not read this box's memory — the caller
+ *            then injects NOTHING, which leaves the service in its existing,
+ *            honest refusing state rather than acting on a guess.
+ *
+ * `--assume-total-mb` / `--assume-platform` exist for the fixture matrix in
+ * `src/__tests__/detectorRamBudget.test.ts` and for reproducing a field box's
+ * number on a laptop. An INSTALLER must never pass them: a number an installer
+ * supplied is not a number derived from the box.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CONTRACT_PATH = path.join(__dirname, 'ram-budget.json');
+const BYTES_PER_MIB = 1024 * 1024;
+
+/** Read the committed inputs. Keys prefixed `_` are prose and are ignored. */
+function loadContract(contractPath) {
+  const raw = fs.readFileSync(contractPath || CONTRACT_PATH, 'utf8');
+  const parsed = JSON.parse(raw);
+  for (const key of ['pinnedModelMb', 'localVlmWorkingSetMb', 'connectorProcessMb', 'captureMb']) {
+    if (!Number.isFinite(parsed[key]) || parsed[key] <= 0) {
+      throw new Error(`ram-budget.json: ${key} must be a positive number, got ${parsed[key]}`);
+    }
+  }
+  if (!parsed.operatingSystemMb || !Number.isFinite(parsed.operatingSystemMb.default)) {
+    throw new Error('ram-budget.json: operatingSystemMb.default must be a positive number');
+  }
+  return parsed;
+}
+
+/**
+ * The ceiling, in MiB, and the subtraction that produced it.
+ *
+ * FLOORED AT THE PINNED MODEL, never below. `ModelRegistry.__init__` RAISES on a
+ * budget it cannot hold the pinned model in — "the service would be permanently
+ * unavailable rather than merely constrained" — and every supervisor restarts a
+ * non-zero exit, so a ceiling of 200 MiB on a tiny box would be a crash-loop
+ * rather than a constraint. At the floor the service still starts, still holds
+ * the model it was told to hold, and refuses each specialist with a CAPACITY
+ * reason naming what did not fit, which is the truthful thing to say about a box
+ * that has no room.
+ */
+function deriveRamBudgetMb(opts) {
+  const contract = opts.contract;
+  const totalMb = opts.totalMb;
+  const platform = opts.platform;
+
+  const osMb = Number.isFinite(contract.operatingSystemMb[platform])
+    ? contract.operatingSystemMb[platform]
+    : contract.operatingSystemMb.default;
+
+  const reserved = osMb
+    + contract.connectorProcessMb
+    + contract.localVlmWorkingSetMb
+    + contract.captureMb;
+
+  const available = totalMb - reserved;
+  const floored = available < contract.pinnedModelMb;
+  const budgetMb = floored ? contract.pinnedModelMb : Math.floor(available);
+
+  return {
+    budgetMb,
+    totalMb,
+    platform,
+    osMb,
+    osKeyed: Number.isFinite(contract.operatingSystemMb[platform]),
+    connectorProcessMb: contract.connectorProcessMb,
+    localVlmWorkingSetMb: contract.localVlmWorkingSetMb,
+    captureMb: contract.captureMb,
+    pinnedModelMb: contract.pinnedModelMb,
+    reserved,
+    available,
+    floored,
+  };
+}
+
+/** `os.totalmem()` in whole MiB, or null when it reported nothing usable. */
+function readTotalMemoryMb(totalmem) {
+  let bytes;
+  try {
+    bytes = (totalmem || os.totalmem)();
+  } catch {
+    return null;
+  }
+  if (!Number.isFinite(bytes) || bytes <= 0) return null;
+  return Math.floor(bytes / BYTES_PER_MIB);
+}
+
+function explain(d) {
+  const floorNote = d.floored
+    ? `\n  FLOORED at the pinned model (${d.pinnedModelMb} MiB): this box has `
+      + `${d.available} MiB left after the reservations, which cannot hold a second model. `
+      + 'The detector still starts and still holds its pinned model; every specialist is '
+      + 'refused with a capacity reason.'
+    : '';
+  const osNote = d.osKeyed ? d.platform : `${d.platform} -> default (unrecognised platform)`;
+  return `detector RAM ceiling ${d.budgetMb} MiB`
+    + `\n  ${d.totalMb} MiB total on this box`
+    + `\n  - ${d.osMb} MiB operating system (${osNote})`
+    + `\n  - ${d.connectorProcessMb} MiB connector process`
+    + `\n  - ${d.localVlmWorkingSetMb} MiB on-device VLM working set`
+    + `\n  - ${d.captureMb} MiB capture (one persistent ffmpeg per feed, at the 16-session ceiling)`
+    + `\n  = ${d.available} MiB for every resident detector session TOGETHER`
+    + floorNote;
+}
+
+function parseArgs(argv) {
+  const opts = { explain: false, totalMb: null, platform: null };
+  for (const arg of argv) {
+    if (arg === '--explain') opts.explain = true;
+    else if (arg.startsWith('--assume-total-mb=')) opts.totalMb = Number(arg.split('=')[1]);
+    else if (arg.startsWith('--assume-platform=')) opts.platform = arg.split('=')[1];
+    else throw new Error(`unknown argument ${arg}`);
+  }
+  return opts;
+}
+
+function main(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    return 1;
+  }
+
+  const totalMb = opts.totalMb !== null ? Math.floor(opts.totalMb) : readTotalMemoryMb();
+  if (!Number.isFinite(totalMb) || totalMb <= 0) {
+    // NOTHING IS INJECTED, and that is the designed outcome rather than a
+    // fallback. An absent ceiling is a STATE the service already handles
+    // correctly and loudly; a made-up one is a portfolio decision nobody made.
+    process.stderr.write(
+      'could not read this box\'s total memory, so no RAM ceiling is derived. '
+      + 'The detector will start, hold its pinned model, and refuse to make a second '
+      + 'model resident — naming why.\n',
+    );
+    return 1;
+  }
+
+  let derived;
+  try {
+    derived = deriveRamBudgetMb({
+      contract: loadContract(),
+      totalMb,
+      platform: opts.platform || process.platform,
+    });
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    return 1;
+  }
+
+  if (opts.explain) process.stderr.write(`${explain(derived)}\n`);
+  process.stdout.write(`${derived.budgetMb}\n`);
+  return 0;
+}
+
+module.exports = { loadContract, deriveRamBudgetMb, readTotalMemoryMb, explain, main, CONTRACT_PATH };
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));

package/deploy/detector/ram-budget.json

@@ -0,0 +1,76 @@
+{
+  "_comment": [
+    "Inputs to the detector's RAM ceiling. ONE file, read by the one derivation",
+    "(ram-budget.js) that all three installers run, so a number can never mean two",
+    "things on two platforms.",
+    "",
+    "Every entry carries its own basis, and the basis says whether it is a",
+    "MEASUREMENT or a POLICY. That distinction is the whole point of writing them",
+    "down separately: a measurement is re-derived when the thing is re-measured, a",
+    "policy is argued about. Collapsing them into one 'reserve' number is how a",
+    "guess acquires the authority of a measurement."
+  ],
+
+  "pinnedModelMb": 632,
+  "_pinnedModelMb": [
+    "MEASURED. RF-DETR Medium's peak RSS — docs/runbooks/cctv-detector-tier.md §6,",
+    "and the same figure `labels.py` commits as RFDETR_MEDIUM.approx_ram_bytes.",
+    "It is the FLOOR of the derived ceiling, not a reservation: ModelRegistry",
+    "REFUSES to construct with a budget below the pinned model's footprint",
+    "(`the service would be permanently unavailable rather than merely",
+    "constrained`), so a ceiling under this would crash-loop the service on a",
+    "small box instead of merely denying it specialists. tests/test_ram_budget.py",
+    "pins this to labels.py so the two cannot drift."
+  ],
+
+  "localVlmWorkingSetMb": 3390,
+  "_localVlmWorkingSetMb": [
+    "MEASURED. Gemma's working set on the SHIPPED GPU-vision path —",
+    "docs/runbooks/cctv-local-inference-hardware-floor.md §3, re-measured",
+    "2026-08-19 at 3.31 GB (2.7 GB on the retired stock config; the GPU vision",
+    "encoder costs ~0.6 GB). The 4.3 GB .litertlm bundle is memory-MAPPED and is",
+    "deliberately not reserved here — what binds is the working set.",
+    "3.31 read as GiB, which is the larger of the two readings of that unit and",
+    "therefore the safe one: over-reserving costs a specialist slot, under-",
+    "reserving OOM-kills a box and looks like a camera fault."
+  ],
+
+  "connectorProcessMb": 2048,
+  "_connectorProcessMb": [
+    "DECLARED, not measured — and it is our own declaration, which is why it is",
+    "usable: trillboards-edge.service sets MemoryMax=2G, so on Linux this is not",
+    "an estimate of the connector, it is the cgroup ceiling the kernel enforces on",
+    "it. macOS and Windows run the same program with no such cap, so the same",
+    "number carries as the best statement we have about it."
+  ],
+
+  "captureMb": 384,
+  "_captureMb": [
+    "MEASURED. RTSPStreamCameraProvider holds one long-lived ffmpeg per feed into",
+    "a bounded ring; docs/runbooks/sensing-catch-rate.md §2b measured that at",
+    "+366 MB RSS at 16 feeds. 16 is the learned per-recorder session ceiling, so",
+    "this reserves the whole capture lane at its widest rather than per feed —",
+    "the feed count is not known at install time, and a per-feed reservation",
+    "would have to be revised every time an operator adds a camera."
+  ],
+
+  "operatingSystemMb": {
+    "linux": 1024,
+    "darwin": 3072,
+    "win32": 2048,
+    "default": 3072
+  },
+  "_operatingSystemMb": [
+    "POLICY, NOT MEASUREMENT, and it must not be read as one. There is no fleet",
+    "measurement of idle OS footprint anywhere in this tree; these are floors",
+    "chosen to be comfortably above what each platform idles at, because the",
+    "consequence of under-reserving here is the OOM killer choosing which of our",
+    "processes dies. `default` takes the largest value, so an unrecognised",
+    "platform fails conservative rather than optimistic.",
+    "linux 1024: the connector's Linux SKU is a headless mini-PC; a Debian/Ubuntu",
+    "  server idles well under 512 MB, and this is roughly twice that.",
+    "win32 2048: Windows 11 idles at roughly 2-3 GB of working set.",
+    "darwin 3072: macOS holds a large (compressed) working set even idle; on the",
+    "  16 GB Mac mini M4 that is the recommended SKU this is ~19% of the box."
+  ]
+}

package/deploy/detector/tests/test_ram_budget.py

@@ -0,0 +1,124 @@
+"""The supervisor's ceiling and this service's floor are ONE number.
+
+`ram-budget.json` is read by the installer, not by this package — the ceiling is
+INJECTED and this service owns no RAM policy (`registry.py`'s header). But the
+supervisor's derivation floors its answer at the pinned model's footprint, and
+that floor is only correct if it is EXACTLY the boundary `ModelRegistry` refuses
+below. One MiB either way and the two artifacts disagree in one of two ways:
+
+  * floor too LOW  -> `ModelRegistry.__init__` raises on a small box, the process
+    exits non-zero, and all three supervisors restart it. A crash-loop instead of
+    a constraint, on exactly the boxes least able to report it.
+  * floor too HIGH -> the derivation quietly hands small boxes more than they
+    have, which is the OOM this whole portfolio design exists to prevent.
+
+So the JSON is pinned to `labels.py` here, in the package that owns the number,
+rather than restated in the JS that reads it.
+
+Stdlib only, like every other suite in this directory.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from trillboards_detector.labels import RFDETR_MEDIUM, ModelVocabulary
+from trillboards_detector.registry import ModelEntry, ModelRegistry
+
+MB = 1024 * 1024
+CONTRACT_PATH = Path(__file__).resolve().parent.parent / "ram-budget.json"
+
+
+def _contract() -> dict:
+    return json.loads(CONTRACT_PATH.read_text())
+
+
+class TestTheFloorIsThePinnedModel(unittest.TestCase):
+    def test_the_contract_ships_next_to_the_package(self):
+        # All three installers resolve the detector SOURCE directory and read the
+        # derivation out of it, so the file has to be here and not somewhere a
+        # packaging step would have to be taught about.
+        self.assertTrue(CONTRACT_PATH.is_file(), f"{CONTRACT_PATH} is missing")
+
+    def test_pinned_model_mb_is_exactly_the_pinned_vocabulary_footprint(self):
+        self.assertEqual(
+            _contract()["pinnedModelMb"] * MB,
+            RFDETR_MEDIUM.approx_ram_bytes,
+            "ram-budget.json's floor and RFDETR_MEDIUM.approx_ram_bytes are the same "
+            "quantity; a supervisor flooring below it crash-loops this service",
+        )
+
+    def test_every_reservation_is_a_positive_number_of_mib(self):
+        contract = _contract()
+        for key in (
+            "pinnedModelMb",
+            "localVlmWorkingSetMb",
+            "connectorProcessMb",
+            "captureMb",
+        ):
+            self.assertIsInstance(contract[key], int, key)
+            self.assertGreater(contract[key], 0, key)
+        os_mb = contract["operatingSystemMb"]
+        self.assertIn("default", os_mb)
+        for platform, value in os_mb.items():
+            self.assertIsInstance(value, int, platform)
+            self.assertGreater(value, 0, platform)
+        # An unrecognised platform must be treated at least as expensively as
+        # every recognised one — failing conservative is the only safe direction
+        # when the consequence is the OOM killer picking a victim.
+        self.assertEqual(
+            os_mb["default"],
+            max(v for k, v in os_mb.items() if k != "default"),
+        )
+
+
+class TestTheFloorIsCONSTRUCTIBLE(unittest.TestCase):
+    """The boundary, exercised against the real registry rather than asserted.
+
+    `ModelRegistry.__init__` refuses a ceiling below the pinned model's footprint
+    — "the service would be permanently unavailable rather than merely
+    constrained". These two cases are the MiB either side of the floor the
+    supervisor derives.
+    """
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self._tmp.name)
+        self.addCleanup(self._tmp.cleanup)
+        self.pinned = ModelVocabulary(
+            model_name=RFDETR_MEDIUM.model_name,
+            slot_names=dict(RFDETR_MEDIUM.slot_names),
+            logit_slots=RFDETR_MEDIUM.logit_slots,
+            approx_ram_bytes=RFDETR_MEDIUM.approx_ram_bytes,
+            onnx_variant=RFDETR_MEDIUM.onnx_variant,
+        )
+
+    def _registry(self, budget_bytes: int) -> ModelRegistry:
+        entry = ModelEntry(
+            self.pinned,
+            self.root / "models" / self.pinned.model_name / "model.onnx",
+            pinned=True,
+        )
+        return ModelRegistry(
+            entries=[entry],
+            session_factory=lambda _e: object(),
+            probe=lambda _s: None,
+            ram_budget_bytes=budget_bytes,
+            log=lambda _m: None,
+        )
+
+    def test_the_derived_floor_constructs(self):
+        floor_mb = _contract()["pinnedModelMb"]
+        self.assertIsNotNone(self._registry(floor_mb * MB))
+
+    def test_one_mib_below_the_floor_refuses(self):
+        floor_mb = _contract()["pinnedModelMb"]
+        with self.assertRaises(ValueError):
+            self._registry((floor_mb - 1) * MB)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -12,9 +12,19 @@
   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`.
+  to the uv-installed `trillboards-detector` binary) / __PORT__ / __LOG_DIR__ /
+  __RAM_BUDGET_ARGS__ and writes the result to
+  ~/Library/LaunchAgents/com.trillboards.detector.plist, then loads it via
+  `launchctl bootstrap gui/$UID`.
+
+  __RAM_BUDGET_ARGS__ becomes either the two <string> elements of
+  `--ram-budget-mb <N>` or NOTHING AT ALL, and the emptiness is meaningful: the
+  detector distinguishes "the supervisor told me a ceiling" from "nobody has
+  told me one", and refuses to invent one in the second state
+  (`registry.py::_admit`). A placeholder value here would be this file quietly
+  becoming a second allocation authority. The number is derived from THIS
+  machine by deploy/detector/ram-budget.js — see its header for why a constant
+  is wrong on both of the two field boxes we have measured.
 
   KeepAlive=true + ThrottleInterval=30 exactly as com.trillboards.litertlm.plist.
   ThrottleInterval is load-bearing here for a specific reason: the model is OTA'd,
@@ -35,6 +45,7 @@
     <string>127.0.0.1</string>
     <string>--port</string>
     <string>__PORT__</string>
+    __RAM_BUDGET_ARGS__
   </array>
 
   <key>RunAtLoad</key>

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

@@ -135,6 +135,39 @@ if [ ! -x "$DETECTOR" ]; then
 fi
 log "trillboards-detector installed at $DETECTOR"
 
+# 2b. THE RAM CEILING, derived from THIS Mac.
+#
+# Without it the service holds its pinned model and refuses to make any second
+# model resident — `registry.py::_admit` says so in the 503 — so every delivered
+# specialist stays permanently `idle`. The refusal is correct; the injection was
+# missing from all six supervisor definitions until 2026-08-26.
+#
+# A COMMAND-LINE ARGUMENT here, not an environment variable, because this
+# supervisor definition is GENERATED by this script — same for the Windows
+# Scheduled Task. Only Linux, whose unit is a static file, uses the env var.
+# One derivation (deploy/detector/ram-budget.js), 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, and a number
+# invented here would be a second allocation authority.
+RAM_BUDGET_ARGS=""
+NODE_BIN="$SCRIPT_DIR/../bin/node"
+[ -x "$NODE_BIN" ] || NODE_BIN="$(command -v node || true)"
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  log "WARN: no node runtime found, so no RAM ceiling is derived; the detector will refuse a second resident model"
+elif [ ! -f "$SOURCE/ram-budget.js" ]; then
+  log "WARN: $SOURCE/ram-budget.js is missing, so no RAM ceiling is derived"
+else
+  _budget="$("$NODE_BIN" "$SOURCE/ram-budget.js" --explain 2>>"$LOG")" || _budget=""
+  case "$_budget" in
+    ''|*[!0-9]*) log "WARN: could not derive a RAM ceiling for this Mac (see $LOG); the detector will refuse a second resident model" ;;
+    *)
+      RAM_BUDGET_ARGS="<string>--ram-budget-mb</string><string>$_budget</string>"
+      log "RAM ceiling $_budget MiB (derived from this Mac; see the log above for the subtraction)"
+      ;;
+  esac
+fi
+
 # 3. Render + bootstrap the LaunchAgent.
 TEMPLATE="$SHARE_DIR/$SERVE_LABEL.plist"
 TARGET="$LA_DIR/$SERVE_LABEL.plist"
@@ -146,6 +179,7 @@ fi
 sed -e "s#__DETECTOR__#$DETECTOR#g" \
     -e "s#__PORT__#$SERVE_PORT#g" \
     -e "s#__LOG_DIR__#$LOG_DIR#g" \
+    -e "s#__RAM_BUDGET_ARGS__#$RAM_BUDGET_ARGS#g" \
     "$TEMPLATE" > "$TARGET" 2>/dev/null || { log "WARN: could not render the detector plist"; exit 0; }
 
 SERVICE_DOMAIN="gui/$(id -u)"

package/deploy/systemd/install.sh

@@ -157,7 +157,20 @@ sudo -u trillboards HOME=/opt/trillboards bash \
 # starting left a fresh Linux box with no detector until its next reboot, with
 # the installer reporting success. `--now` starts it here, where we have root,
 # and after the provisioner so the binary the unit points at already exists.
-sudo systemctl enable --now trillboards-detector \
+#
+# `enable` THEN `restart`, NOT `enable --now`, AND THE DIFFERENCE ONLY SHOWS ON AN
+# UPGRADE. `--now` starts a unit that is INACTIVE and does nothing at all to one
+# that is already running — so on a box where the detector is already up, the
+# provisioner above would write a new `TRILLBOARDS_DETECTOR_RAM_BUDGET_MB` into
+# /etc/trillboards/env and the running process would keep the environment it was
+# exec'd with, until the next reboot. A ceiling the service never re-read is a
+# decision nobody acted on: exactly what the litert-lm block above this one
+# records about `write_litertlm_config` without a restart.
+#
+# `restart` is correct in BOTH states — it starts an inactive unit and replaces a
+# running one — so the fresh-install behaviour `--now` was added for is kept.
+sudo systemctl enable trillboards-detector 2>/dev/null || true
+sudo systemctl restart trillboards-detector \
   || echo "  *** The detector unit did not start. Sensing is unaffected. Check:
   *** sudo systemctl status trillboards-detector"
 

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.106';
 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.106";
 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.106';
 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.106",
   "description": "Composable cross-platform Edge AI SDK for audience sensing on DOOH/CTV devices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",