camstack 1.2.36 → 1.2.37

package/dist/{chunk-V75HN7AE.js → chunk-OR2CMMOE.js}

@@ -27017,6 +27017,13 @@ var CameraStatusSchema = external_exports.object({
   /** Unix timestamp (ms) when this snapshot was composed server-side. */
   fetchedAt: external_exports.number()
 });
+var INFERENCE_DEVICE_EXCLUSION_REASONS = [
+  "disabled",
+  "unavailable",
+  "cannot-host-camera-root",
+  "accelerator-preferred"
+];
+var InferenceDeviceExclusionReasonSchema = external_exports.enum(INFERENCE_DEVICE_EXCLUSION_REASONS);
 var NodeInferenceDeviceSchema = external_exports.object({
   /** Stable per-node device key, e.g. `openvino:npu`, `edgetpu:usb`, `cpu`. */
   key: external_exports.string(),
@@ -27047,7 +27054,17 @@ var NodeInferenceDeviceSchema = external_exports.object({
   * available per format; this is the stored selection that becomes the
   * default for EVERY camera landing on this accelerator.
   */
-  steps: external_exports.record(external_exports.string(), DeviceStepConfigSchema).optional()
+  steps: external_exports.record(external_exports.string(), DeviceStepConfigSchema).optional(),
+  /**
+  * `null` when the device IS a camera-root candidate on this node; otherwise
+  * the reason the dispatcher drops it. Computed by the SAME
+  * `resolveInferenceDeviceEligibility` the dispatcher runs, so this view can
+  * never disagree with the election — deriving it in the UI from
+  * `enabled`/`available` would silently miss `cannot-host-camera-root` (needs
+  * the node's model catalog) and `accelerator-preferred` (needs the node-wide
+  * "an accelerator is serving" predicate).
+  */
+  exclusion: InferenceDeviceExclusionReasonSchema.nullable()
 });
 var NodeInferenceDevicesSchema = external_exports.object({
   nodeId: external_exports.string(),
@@ -32057,7 +32074,35 @@ var ConnectionEndpointSchema = external_exports.object({
   */
   priority: external_exports.number()
 });
-var GetConnectionEndpointsResultSchema = external_exports.object({ endpoints: external_exports.array(ConnectionEndpointSchema).readonly() });
+var LocalPortSourceEnum = external_exports.enum([
+  "server-config",
+  "server-env",
+  "caller-hint",
+  "default"
+]);
+var AdvertisedLocalPortSchema = external_exports.object({
+  port: external_exports.number().int().min(1).max(65535),
+  source: LocalPortSourceEnum
+});
+var GetConnectionEndpointsResultSchema = external_exports.object({
+  endpoints: external_exports.array(ConnectionEndpointSchema).readonly(),
+  /**
+  * The port the hub built the LAN/loopback URLs with, and where that number
+  * came from.
+  *
+  * Returned rather than merely applied, because "the URL is right" and "the
+  * client can KNOW the URL is right" are different properties. A client that
+  * only sees a corrected URL cannot distinguish a hub that fixed the port from
+  * a hub that echoed the port the client sent, so it cannot decide whether to
+  * race the candidate or discard it. With `source` it can: anything but
+  * `caller-hint` is the hub's own socket.
+  *
+  * Absent on hubs predating this field — a client that finds it missing is
+  * talking to an echoing hub and must degrade exactly as it does for
+  * `caller-hint`.
+  */
+  localPort: AdvertisedLocalPortSchema
+});
 var NotificationEndpointSchema = external_exports.object({
   /** The operator's explicit choice, or null for AUTO. */
   baseUrl: external_exports.string().nullable(),
@@ -32099,10 +32144,35 @@ var localNetworkCapability = {
     * Honours `getAllowedAddresses()` when set — addresses outside
     * the allowlist are dropped (the public tunnel + loopback are
     * always included as escape hatches).
+    *
+    * **The port is the hub's, not the caller's** (D62 — a function's fact
+    * belongs to whoever already owns it). This method used to take a `port`
+    * and echo it onto every LAN and loopback URL it advertised, which made
+    * every client a second authority on a socket only the hub binds. A viewer
+    * configured with a port-less public URL (`https://camstack.example.top`)
+    * infers 443 from the scheme, asks with 443, and was handed
+    * `https://192.168.1.9:443` for a hub listening on 4443. That candidate
+    * cannot ever answer, and losing its race reads in the log exactly like
+    * "the LAN was tried and it was slower" — so an operator sitting on his own
+    * WiFi stayed on the public tunnel for weeks, with the LAN candidate born
+    * dead on every single connect.
+    *
+    * The hub now resolves its own listen port and reports it as `localPort`,
+    * with the SOURCE of the number, so a client can tell a fact from an echo.
+    *
+    * Out of scope on purpose: a LAN URL that is not the hub's own socket (a
+    * reverse proxy in front of it on another port) is not this method's to
+    * invent either — pin it with `setNotificationEndpoint` / a configured
+    * origin, which is an operator statement rather than a guess.
     */
     getConnectionEndpoints: method(external_exports.object({
-      /** Local hub HTTP port to use in base URLs. */
-      port: external_exports.number().int().min(1).max(65535),
+      /**
+      * LEGACY HINT — do not send from new code. Kept optional so clients
+      * written against the echoing contract keep working; the hub uses it
+      * only when it cannot read its own port, and says so via
+      * `localPort.source === 'caller-hint'`.
+      */
+      port: external_exports.number().int().min(1).max(65535).optional(),
       /** Include `http(s)://127.0.0.1:<port>` as the lowest-priority
       *  candidate. Default `true`. */
       includeLoopback: external_exports.boolean().optional(),
@@ -36593,6 +36663,7 @@ var BATTERY_DEVICE_PROFILE = {
   settings: {}
 };
 var BATTERY_UNREACHABLE_AFTER_MS = 360 * 6e4;
+var OPERATOR_WRITTEN_STALE_MS = 10 * 6e4;
 var METHOD_ACCESS_MAP = Object.freeze({
   "accessories.setChildHidden": {
     capName: "accessories",

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runDiscover
-} from "./chunk-V75HN7AE.js";
+} from "./chunk-OR2CMMOE.js";
 import "./chunk-LMMQX4CK.js";
 
 // src/cli.ts
@@ -38,7 +38,7 @@ async function runServe(args) {
     ...typeof values.data === "string" ? { data: values.data } : {}
   };
   Object.assign(process.env, buildServeEnv(opts));
-  await import("./launcher-OXQ3W5WV.js");
+  await import("./launcher-6VDFMPM6.js");
 }
 
 // src/commands/agent.ts
@@ -83,7 +83,7 @@ async function runAgent(args) {
     ...typeof values.port === "string" ? { port: values.port } : {}
   };
   Object.assign(process.env, buildAgentEnv(opts));
-  await import("./launcher-OXQ3W5WV.js");
+  await import("./launcher-6VDFMPM6.js");
 }
 
 // src/commands/setup.ts
@@ -1130,7 +1130,7 @@ function isUnknown(_value) {
   return true;
 }
 async function resolveServerInteractive(presetNamespace) {
-  const { discoverNodes, resolveHubFromDiscovered, filterHubNodes, DEFAULT_HUB_HTTPS_PORT } = await import("./discover-FXX2XNDX.js");
+  const { discoverNodes, resolveHubFromDiscovered, filterHubNodes, DEFAULT_HUB_HTTPS_PORT } = await import("./discover-Y3C7HOBU.js");
   if (presetNamespace) {
     const spinner4 = clack.spinner();
     spinner4.start(`Discovering hub on LAN (namespace "${presetNamespace}")`);

package/dist/{discover-FXX2XNDX.js → discover-Y3C7HOBU.js}

@@ -5,7 +5,7 @@ import {
   filterHubNodes,
   resolveHubFromDiscovered,
   runDiscover
-} from "./chunk-V75HN7AE.js";
+} from "./chunk-OR2CMMOE.js";
 import "./chunk-LMMQX4CK.js";
 export {
   DEFAULT_HUB_HTTPS_PORT,

package/dist/{launcher-OXQ3W5WV.js → launcher-6VDFMPM6.js}

@@ -23631,9 +23631,9 @@ var require_zod = __commonJS({
   }
 });
 
-// ../system/dist/dist-B2CtwVW2.js
-var require_dist_B2CtwVW2 = __commonJS({
-  "../system/dist/dist-B2CtwVW2.js"(exports) {
+// ../system/dist/dist-C1Aea3c6.js
+var require_dist_C1Aea3c6 = __commonJS({
+  "../system/dist/dist-C1Aea3c6.js"(exports) {
     "use strict";
     var zod = require_zod();
     var EventCategory = /* @__PURE__ */ (function(EventCategory2) {
@@ -37300,6 +37300,12 @@ var require_dist_B2CtwVW2 = __commonJS({
       /** Unix timestamp (ms) when this snapshot was composed server-side. */
       fetchedAt: zod.z.number()
     });
+    var InferenceDeviceExclusionReasonSchema = zod.z.enum([
+      "disabled",
+      "unavailable",
+      "cannot-host-camera-root",
+      "accelerator-preferred"
+    ]);
     var NodeInferenceDeviceSchema = zod.z.object({
       /** Stable per-node device key, e.g. `openvino:npu`, `edgetpu:usb`, `cpu`. */
       key: zod.z.string(),
@@ -37330,7 +37336,17 @@ var require_dist_B2CtwVW2 = __commonJS({
       * available per format; this is the stored selection that becomes the
       * default for EVERY camera landing on this accelerator.
       */
-      steps: zod.z.record(zod.z.string(), DeviceStepConfigSchema).optional()
+      steps: zod.z.record(zod.z.string(), DeviceStepConfigSchema).optional(),
+      /**
+      * `null` when the device IS a camera-root candidate on this node; otherwise
+      * the reason the dispatcher drops it. Computed by the SAME
+      * `resolveInferenceDeviceEligibility` the dispatcher runs, so this view can
+      * never disagree with the election — deriving it in the UI from
+      * `enabled`/`available` would silently miss `cannot-host-camera-root` (needs
+      * the node's model catalog) and `accelerator-preferred` (needs the node-wide
+      * "an accelerator is serving" predicate).
+      */
+      exclusion: InferenceDeviceExclusionReasonSchema.nullable()
     });
     var NodeInferenceDevicesSchema = zod.z.object({
       nodeId: zod.z.string(),
@@ -42339,7 +42355,35 @@ var require_dist_B2CtwVW2 = __commonJS({
       */
       priority: zod.z.number()
     });
-    var GetConnectionEndpointsResultSchema = zod.z.object({ endpoints: zod.z.array(ConnectionEndpointSchema).readonly() });
+    var LocalPortSourceEnum = zod.z.enum([
+      "server-config",
+      "server-env",
+      "caller-hint",
+      "default"
+    ]);
+    var AdvertisedLocalPortSchema = zod.z.object({
+      port: zod.z.number().int().min(1).max(65535),
+      source: LocalPortSourceEnum
+    });
+    var GetConnectionEndpointsResultSchema = zod.z.object({
+      endpoints: zod.z.array(ConnectionEndpointSchema).readonly(),
+      /**
+      * The port the hub built the LAN/loopback URLs with, and where that number
+      * came from.
+      *
+      * Returned rather than merely applied, because "the URL is right" and "the
+      * client can KNOW the URL is right" are different properties. A client that
+      * only sees a corrected URL cannot distinguish a hub that fixed the port from
+      * a hub that echoed the port the client sent, so it cannot decide whether to
+      * race the candidate or discard it. With `source` it can: anything but
+      * `caller-hint` is the hub's own socket.
+      *
+      * Absent on hubs predating this field — a client that finds it missing is
+      * talking to an echoing hub and must degrade exactly as it does for
+      * `caller-hint`.
+      */
+      localPort: AdvertisedLocalPortSchema
+    });
     var NotificationEndpointSchema = zod.z.object({
       /** The operator's explicit choice, or null for AUTO. */
       baseUrl: zod.z.string().nullable(),
@@ -42381,10 +42425,35 @@ var require_dist_B2CtwVW2 = __commonJS({
         * Honours `getAllowedAddresses()` when set — addresses outside
         * the allowlist are dropped (the public tunnel + loopback are
         * always included as escape hatches).
+        *
+        * **The port is the hub's, not the caller's** (D62 — a function's fact
+        * belongs to whoever already owns it). This method used to take a `port`
+        * and echo it onto every LAN and loopback URL it advertised, which made
+        * every client a second authority on a socket only the hub binds. A viewer
+        * configured with a port-less public URL (`https://camstack.example.top`)
+        * infers 443 from the scheme, asks with 443, and was handed
+        * `https://192.168.1.9:443` for a hub listening on 4443. That candidate
+        * cannot ever answer, and losing its race reads in the log exactly like
+        * "the LAN was tried and it was slower" — so an operator sitting on his own
+        * WiFi stayed on the public tunnel for weeks, with the LAN candidate born
+        * dead on every single connect.
+        *
+        * The hub now resolves its own listen port and reports it as `localPort`,
+        * with the SOURCE of the number, so a client can tell a fact from an echo.
+        *
+        * Out of scope on purpose: a LAN URL that is not the hub's own socket (a
+        * reverse proxy in front of it on another port) is not this method's to
+        * invent either — pin it with `setNotificationEndpoint` / a configured
+        * origin, which is an operator statement rather than a guess.
         */
         getConnectionEndpoints: method(zod.z.object({
-          /** Local hub HTTP port to use in base URLs. */
-          port: zod.z.number().int().min(1).max(65535),
+          /**
+          * LEGACY HINT — do not send from new code. Kept optional so clients
+          * written against the echoing contract keep working; the hub uses it
+          * only when it cannot read its own port, and says so via
+          * `localPort.source === 'caller-hint'`.
+          */
+          port: zod.z.number().int().min(1).max(65535).optional(),
           /** Include `http(s)://127.0.0.1:<port>` as the lowest-priority
           *  candidate. Default `true`. */
           includeLoopback: zod.z.boolean().optional(),
@@ -56186,7 +56255,7 @@ var require_alerts_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     function selectExpired(alerts, cutoffMs) {
       return alerts.filter((a) => a.createdAt < cutoffMs).sort((a, b) => a.createdAt - b.createdAt).map((a) => a.id);
     }
@@ -56999,7 +57068,7 @@ var require_console_logging = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var require_formatter = require_formatter_DqAKDlvN();
     var LEVEL_RANK = {
       debug: 0,
@@ -57093,7 +57162,7 @@ var require_core_blocks_addon = __commonJS({
     "use strict";
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var node_crypto = __require("crypto");
     var node_fs_promises = __require("fs/promises");
     node_fs_promises = require_chunk.__toESM(node_fs_promises);
@@ -57990,11 +58059,11 @@ var require_core_blocks = __commonJS({
   }
 });
 
-// ../system/dist/retired-settings-keys-CYDGGkyM.js
-var require_retired_settings_keys_CYDGGkyM = __commonJS({
-  "../system/dist/retired-settings-keys-CYDGGkyM.js"(exports) {
+// ../system/dist/retired-settings-keys-B52KsNz8.js
+var require_retired_settings_keys_B52KsNz8 = __commonJS({
+  "../system/dist/retired-settings-keys-B52KsNz8.js"(exports) {
     "use strict";
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     function settingsStoreIsAuthoritativeHere(env) {
       const raw = (env["CAMSTACK_ROLE"] ?? "").trim().toLowerCase();
       return raw === "" || raw === "hub";
@@ -60037,8 +60106,8 @@ var require_device_manager_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
-    var require_retired_settings_keys = require_retired_settings_keys_CYDGGkyM();
+    var require_dist10 = require_dist_C1Aea3c6();
+    var require_retired_settings_keys = require_retired_settings_keys_B52KsNz8();
     var node_crypto = __require("crypto");
     var _camstack_types_node = require_node();
     var JOB_HISTORY = 20;
@@ -64365,7 +64434,7 @@ var require_hub_forwarder = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var require_formatter = require_formatter_DqAKDlvN();
     var DEFAULT_OUTBOUND_BUFFER_SIZE = 500;
     var HubForwarderDestination = class {
@@ -64502,7 +64571,7 @@ var require_liveness_monitor_addon = __commonJS({
     "use strict";
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var NO_DEVICES = "liveness:no-devices";
     var ALL_OFFLINE = "liveness:all-devices-offline";
     var NO_FOOTAGE_PREFIX = "liveness:no-footage:";
@@ -64692,7 +64761,7 @@ var require_local_auth_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var node_crypto = __require("crypto");
     node_crypto = require_chunk.__toESM(node_crypto);
     var crypto$1 = __require("crypto");
@@ -72376,7 +72445,7 @@ var require_loki_logging = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     function sanitizeLabelName(raw) {
       const replaced = raw.replaceAll(/[^a-zA-Z0-9_]/g, "_");
       return /^[a-zA-Z_]/.test(replaced) ? replaced : `_${replaced}`;
@@ -72941,7 +73010,7 @@ var require_native_metrics_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var node_child_process = __require("child_process");
     var node_util = __require("util");
     var node_os = __require("os");
@@ -73883,7 +73952,7 @@ var require_filesystem_storage_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var node_crypto = __require("crypto");
     var node_fs_promises = __require("fs/promises");
     var node_path = __require("path");
@@ -74999,8 +75068,8 @@ var require_sqlite_settings_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
-    var require_retired_settings_keys = require_retired_settings_keys_CYDGGkyM();
+    var require_dist10 = require_dist_C1Aea3c6();
+    var require_retired_settings_keys = require_retired_settings_keys_B52KsNz8();
     var node_crypto = __require("crypto");
     var node_fs = __require("fs");
     var node_module = __require("module");
@@ -76544,7 +76613,7 @@ var require_storage_orchestrator_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var node_crypto = __require("crypto");
     var node_fs_promises = __require("fs/promises");
     node_fs_promises = require_chunk.__toESM(node_fs_promises);
@@ -78423,7 +78492,7 @@ var require_system_config_addon = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var SECTION_TITLES = {
       server: "Server",
       auth: "Authentication"
@@ -96484,7 +96553,7 @@ var require_winston_logging = __commonJS({
       [Symbol.toStringTag]: { value: "Module" }
     });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var require_formatter = require_formatter_DqAKDlvN();
     var node_path = __require("path");
     node_path = require_chunk.__toESM(node_path);
@@ -118760,7 +118829,7 @@ var require_dist3 = __commonJS({
     "use strict";
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
     var require_chunk = require_chunk_Cek0wNdY();
-    var require_dist10 = require_dist_B2CtwVW2();
+    var require_dist10 = require_dist_C1Aea3c6();
     var require_builtins_alerts_alerts_addon = require_alerts_addon();
     require_alerts();
     var require_formatter = require_formatter_DqAKDlvN();
@@ -252258,6 +252327,13 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
       /** Unix timestamp (ms) when this snapshot was composed server-side. */
       fetchedAt: zod.z.number()
     });
+    var INFERENCE_DEVICE_EXCLUSION_REASONS = [
+      "disabled",
+      "unavailable",
+      "cannot-host-camera-root",
+      "accelerator-preferred"
+    ];
+    var InferenceDeviceExclusionReasonSchema = zod.z.enum(INFERENCE_DEVICE_EXCLUSION_REASONS);
     var NodeInferenceDeviceSchema = zod.z.object({
       /** Stable per-node device key, e.g. `openvino:npu`, `edgetpu:usb`, `cpu`. */
       key: zod.z.string(),
@@ -252288,7 +252364,17 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
       * available per format; this is the stored selection that becomes the
       * default for EVERY camera landing on this accelerator.
       */
-      steps: zod.z.record(zod.z.string(), DeviceStepConfigSchema).optional()
+      steps: zod.z.record(zod.z.string(), DeviceStepConfigSchema).optional(),
+      /**
+      * `null` when the device IS a camera-root candidate on this node; otherwise
+      * the reason the dispatcher drops it. Computed by the SAME
+      * `resolveInferenceDeviceEligibility` the dispatcher runs, so this view can
+      * never disagree with the election — deriving it in the UI from
+      * `enabled`/`available` would silently miss `cannot-host-camera-root` (needs
+      * the node's model catalog) and `accelerator-preferred` (needs the node-wide
+      * "an accelerator is serving" predicate).
+      */
+      exclusion: InferenceDeviceExclusionReasonSchema.nullable()
     });
     var NodeInferenceDevicesSchema = zod.z.object({
       nodeId: zod.z.string(),
@@ -257320,7 +257406,35 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
       */
       priority: zod.z.number()
     });
-    var GetConnectionEndpointsResultSchema = zod.z.object({ endpoints: zod.z.array(ConnectionEndpointSchema).readonly() });
+    var LocalPortSourceEnum = zod.z.enum([
+      "server-config",
+      "server-env",
+      "caller-hint",
+      "default"
+    ]);
+    var AdvertisedLocalPortSchema = zod.z.object({
+      port: zod.z.number().int().min(1).max(65535),
+      source: LocalPortSourceEnum
+    });
+    var GetConnectionEndpointsResultSchema = zod.z.object({
+      endpoints: zod.z.array(ConnectionEndpointSchema).readonly(),
+      /**
+      * The port the hub built the LAN/loopback URLs with, and where that number
+      * came from.
+      *
+      * Returned rather than merely applied, because "the URL is right" and "the
+      * client can KNOW the URL is right" are different properties. A client that
+      * only sees a corrected URL cannot distinguish a hub that fixed the port from
+      * a hub that echoed the port the client sent, so it cannot decide whether to
+      * race the candidate or discard it. With `source` it can: anything but
+      * `caller-hint` is the hub's own socket.
+      *
+      * Absent on hubs predating this field — a client that finds it missing is
+      * talking to an echoing hub and must degrade exactly as it does for
+      * `caller-hint`.
+      */
+      localPort: AdvertisedLocalPortSchema
+    });
     var NotificationEndpointSchema = zod.z.object({
       /** The operator's explicit choice, or null for AUTO. */
       baseUrl: zod.z.string().nullable(),
@@ -257362,10 +257476,35 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
         * Honours `getAllowedAddresses()` when set — addresses outside
         * the allowlist are dropped (the public tunnel + loopback are
         * always included as escape hatches).
+        *
+        * **The port is the hub's, not the caller's** (D62 — a function's fact
+        * belongs to whoever already owns it). This method used to take a `port`
+        * and echo it onto every LAN and loopback URL it advertised, which made
+        * every client a second authority on a socket only the hub binds. A viewer
+        * configured with a port-less public URL (`https://camstack.example.top`)
+        * infers 443 from the scheme, asks with 443, and was handed
+        * `https://192.168.1.9:443` for a hub listening on 4443. That candidate
+        * cannot ever answer, and losing its race reads in the log exactly like
+        * "the LAN was tried and it was slower" — so an operator sitting on his own
+        * WiFi stayed on the public tunnel for weeks, with the LAN candidate born
+        * dead on every single connect.
+        *
+        * The hub now resolves its own listen port and reports it as `localPort`,
+        * with the SOURCE of the number, so a client can tell a fact from an echo.
+        *
+        * Out of scope on purpose: a LAN URL that is not the hub's own socket (a
+        * reverse proxy in front of it on another port) is not this method's to
+        * invent either — pin it with `setNotificationEndpoint` / a configured
+        * origin, which is an operator statement rather than a guess.
         */
         getConnectionEndpoints: require_sleep.method(zod.z.object({
-          /** Local hub HTTP port to use in base URLs. */
-          port: zod.z.number().int().min(1).max(65535),
+          /**
+          * LEGACY HINT — do not send from new code. Kept optional so clients
+          * written against the echoing contract keep working; the hub uses it
+          * only when it cannot read its own port, and says so via
+          * `localPort.source === 'caller-hint'`.
+          */
+          port: zod.z.number().int().min(1).max(65535).optional(),
           /** Include `http(s)://127.0.0.1:<port>` as the lowest-priority
           *  candidate. Default `true`. */
           includeLoopback: zod.z.boolean().optional(),
@@ -263609,10 +263748,14 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
       } };
     }
     var LAST_FETCHED_FIELD = "lastFetchedAt";
+    var RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS = 6e4;
+    var OPERATOR_WRITTEN_STALE_MS = 10 * 6e4;
     function createRuntimeStateBridge(params) {
       const { runtimeState, cap, ownDeviceId, refresh, staleMs, empty, logger } = params;
       const missCooldownMs = params.refreshMissCooldownMs ?? 6e4;
+      const staleRead = params.staleRead ?? "await-refresh";
       let missCooldownUntil = 0;
+      let refreshInFlight = null;
       const readFetchedAt = () => {
         const value = runtimeState.getCapState(cap.name)?.[LAST_FETCHED_FIELD];
         return typeof value === "number" ? value : 0;
@@ -263627,14 +263770,7 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
           }
         });
       };
-      const ensureFresh = async () => {
-        const slice = runtimeState.getCapState(cap.name);
-        const fetchedAt = readFetchedAt();
-        if (slice && Date.now() - fetchedAt <= staleMs) {
-          missCooldownUntil = 0;
-          return;
-        }
-        if (Date.now() < missCooldownUntil) return;
+      const runRefresh = async (fetchedAt) => {
         try {
           await refresh();
         } catch (err) {
@@ -263650,6 +263786,34 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
         }
         openMissCooldown(void 0);
       };
+      const startRefresh = (fetchedAt) => {
+        const existing = refreshInFlight;
+        if (existing !== null) return existing;
+        const started = runRefresh(fetchedAt).catch(() => void 0).finally(() => {
+          refreshInFlight = null;
+        });
+        refreshInFlight = started;
+        return started;
+      };
+      const ensureFresh = async () => {
+        const slice = runtimeState.getCapState(cap.name);
+        const fetchedAt = readFetchedAt();
+        if (slice && Date.now() - fetchedAt <= staleMs) {
+          missCooldownUntil = 0;
+          return;
+        }
+        if (Date.now() < missCooldownUntil) return;
+        if (staleRead === "serve-and-revalidate") {
+          if (refreshInFlight !== null) return;
+          if (slice && fetchedAt > 0) {
+            startRefresh(fetchedAt);
+            return;
+          }
+          await startRefresh(fetchedAt);
+          return;
+        }
+        await runRefresh(fetchedAt);
+      };
       const projectStatus = () => {
         const slice = runtimeState.getCapState(cap.name);
         if (!slice) return empty();
@@ -277087,6 +277251,7 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
     exports.HumidifierStatusSchema = HumidifierStatusSchema;
     exports.HumiditySensorStatusSchema = HumiditySensorStatusSchema;
     exports.HvacModeSchema = HvacModeSchema;
+    exports.INFERENCE_DEVICE_EXCLUSION_REASONS = INFERENCE_DEVICE_EXCLUSION_REASONS;
     exports.ImageContractSchema = ImageContractSchema;
     exports.ImageContractStateSchema = ImageContractStateSchema;
     exports.ImageRotateSchema = ImageRotateSchema;
@@ -277094,6 +277259,7 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
     exports.ImageSettingsPatchSchema = ImageSettingsPatchSchema;
     exports.ImageSettingsStatusSchema = ImageSettingsStatusSchema;
     exports.ImageStatusSchema = ImageStatusSchema;
+    exports.InferenceDeviceExclusionReasonSchema = InferenceDeviceExclusionReasonSchema;
     exports.IngestOwnerSchema = IngestOwnerSchema;
     exports.InstalledPackageSchema = InstalledPackageSchema;
     exports.IntegrationLiteSchema = IntegrationLiteSchema;
@@ -277306,6 +277472,7 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
     exports.NotificationSchema = NotificationSchema;
     exports.NotifierStatusSchema = NotifierStatusSchema;
     exports.NumericSensorStatusSchema = NumericSensorStatusSchema;
+    exports.OPERATOR_WRITTEN_STALE_MS = OPERATOR_WRITTEN_STALE_MS;
     exports.OPS_LOG_DEFAULT_LIMIT = OPS_LOG_DEFAULT_LIMIT;
     exports.OPS_LOG_RING_DEFAULT_MAX = OPS_LOG_RING_DEFAULT_MAX;
     exports.OauthIntegrationDescriptorSchema = OauthIntegrationDescriptorSchema;
@@ -277388,6 +277555,7 @@ ${recipe.triggers.map((t, i) => emitTrigger(t, i)).join("\n\n")}
     exports.RESTORED_CAP_NAMES = RESTORED_CAP_NAMES;
     exports.RUNTIME_DEFAULTS = RUNTIME_DEFAULTS;
     exports.RUNTIME_STATE_POLICY = RUNTIME_STATE_POLICY;
+    exports.RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS = RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS;
     exports.RUNTIME_TO_FORMAT = RUNTIME_TO_FORMAT;
     exports.RawStateResultSchema = require_sleep.RawStateResultSchema;
     exports.ReadGopBytesResultSchema = ReadGopBytesResultSchema;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camstack",
-  "version": "1.2.36",
+  "version": "1.2.37",
   "description": "CLI tool for managing and running CamStack server",
   "keywords": [
     "camstack",