@trillboards/edge-sdk 0.2.19 → 0.2.20

package/dist/connectorUpdate.js

@@ -0,0 +1,701 @@
+"use strict";
+/**
+ * connectorUpdate — the CONSUMER the published version manifest never had.
+ *
+ * Every release publishes `trillboards-connector-<platform>.version.json` to the
+ * CDN with `connectorVersion`, `gitSha`, `sha256`, `sizeBytes` and `publishedAt`.
+ * Until this module existed, repo-wide the ONLY references to that object were
+ * the workflow that writes it, a test asserting the workflow writes it, and a
+ * README line. It was a producer with no consumer — the mirror image of the
+ * defect class in `docs/runbooks/telemetry-producer-substrate.md`, and just as
+ * invisible: the artifact that says "you are out of date" was published,
+ * correct, and read by nobody, so a field fix reached a customer only when that
+ * customer happened to re-download 2.6 GB and re-run the installer.
+ *
+ * THIS FILE ONLY CHECKS AND REPORTS. Applying an update is a separate,
+ * platform-specific transaction — see `deploy/windows/apply-update.ps1` and
+ * `connectorUpdateApply.ts`. The split is deliberate: "am I stale?" is a
+ * question every platform can answer over one 401-byte GET, while "swap the
+ * running binaries" is a Windows scheduled-task transaction with a rollback.
+ *
+ * ── WHY A 200 IS NOT AN ANSWER ──────────────────────────────────────────────
+ * The CDN in front of these objects serves the marketing SPA as its default
+ * behavior, so a MISSING manifest answers `HTTP 200 text/html`, not 404. Proved
+ * against production while writing this:
+ *
+ *   $ curl -o /dev/null -w '%{http_code} %{content_type}\n' \
+ *       .../connector/this-file-does-not-exist-control.json
+ *   200 text/html
+ *
+ * That is the exact shape of `.claude/lessons/2026-08-14-a-broken-probe-and-a-
+ * true-absence-are-the-same-bytes.md`. So the check is not "did the GET
+ * succeed"; it is "did the body parse as a manifest whose every required field
+ * is present and well-formed". A body that fails that test yields `null` —
+ * meaning UNKNOWN — and `null` is never rendered as "up to date". A staleness
+ * oracle that reports "current" when it cannot reach its own oracle is worse
+ * than no oracle at all.
+ *
+ * For the same reason `parseConnectorVersion` is STRICT rather than lenient.
+ * `edge-core`'s ModelManager parses versions with `.split('.').map(Number)` and
+ * `|| 0`, so a non-numeric version silently becomes `0.0.0` and every later
+ * comparison quietly answers "not newer" — forever, with no error anywhere. A
+ * version we cannot parse is a manifest we do not trust.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONNECTOR_UPDATE_SAFE_POINT_DEADLINE_MS = exports.CONNECTOR_UPDATE_STAGE_DEADLINE_MS = exports.CONNECTOR_UPDATE_POLL_INTERVAL_MS = exports.CONNECTOR_UPDATE_INITIAL_DELAY_MS = exports.ConnectorManifestClient = exports.defaultManifestFetcher = exports.CONNECTOR_UPDATE_MIN_RELEASE_AGE_MS = exports.CONNECTOR_UPDATE_CHECK_INTERVAL_MS = exports.CONNECTOR_UPDATE_BASE_URL = void 0;
+exports.parseConnectorVersion = parseConnectorVersion;
+exports.isNewerConnectorVersion = isNewerConnectorVersion;
+exports.manifestObjectForPlatform = manifestObjectForPlatform;
+exports.manifestUrlForPlatform = manifestUrlForPlatform;
+exports.parseVersionManifest = parseVersionManifest;
+exports.isSafeToApplyUpdate = isSafeToApplyUpdate;
+exports.busynessOf = busynessOf;
+exports.isReleaseBakedEnough = isReleaseBakedEnough;
+exports.checkForConnectorUpdate = checkForConnectorUpdate;
+exports.startConnectorUpdateService = startConnectorUpdateService;
+exports.connectorDeviceTokens = connectorDeviceTokens;
+exports.startConnectorUpdates = startConnectorUpdates;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const ConnectorStatusClient_1 = require("./ConnectorStatusClient");
+/** Where the release workflows publish every platform's manifest. */
+exports.CONNECTOR_UPDATE_BASE_URL = 'https://screen.trillboards.com/connector';
+/**
+ * How often an install asks whether it is stale.
+ *
+ * Six hours. The GET is ~401 bytes, so the poll itself costs nothing, and the
+ * release workflow fires on every `production` push touching the edge
+ * workspaces (measured: 15 releases on 2026-08-13, 13 on 08-12), so a shorter
+ * period would only discover the same churn sooner. The FIRST check is deferred
+ * one whole interval, matching `ModelManager.start()` — a connector in a crash
+ * loop must not turn into a CDN hammer, and a machine that just installed is by
+ * definition current.
+ */
+exports.CONNECTOR_UPDATE_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/**
+ * How old a release must be before an install will TAKE it.
+ *
+ * There is no canary ring in front of this. With ~13 releases a day reaching a
+ * fleet that auto-applies, a bad connector would be on every customer's PC
+ * within one check period, and the only recovery is another release. A bake
+ * window is the cheapest thing standing between "we merged a regression" and
+ * "every store stopped sensing", and it costs a fix at most one extra check.
+ *
+ * `publishedAt` comes from the manifest, i.e. from the same channel as the
+ * payload, so this is a release-hygiene control and NOT a security control. The
+ * security control is the Authenticode verification in the applier.
+ */
+exports.CONNECTOR_UPDATE_MIN_RELEASE_AGE_MS = 6 * 60 * 60 * 1000;
+/** Hard cap on the manifest body. It is ~401 bytes; anything near this is hostile. */
+const MANIFEST_MAX_BYTES = 64 * 1024;
+/** Manifest fetch timeout. */
+const MANIFEST_TIMEOUT_MS = 15000;
+/**
+ * Parse `MAJOR.MINOR.PATCH` (an optional leading `v`, an optional `-prerelease`
+ * or `+build` suffix that is IGNORED for ordering). Returns null — never a
+ * zeroed struct — for anything else.
+ */
+function parseConnectorVersion(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const m = /^v?(\d{1,9})\.(\d{1,9})\.(\d{1,9})(?:[-+][0-9A-Za-z.-]+)?$/.exec(raw.trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+/**
+ * Is `available` strictly newer than `installed`?
+ *
+ * FALSE whenever either side fails to parse. That direction is deliberate: an
+ * unparseable version must never authorise a swap of the running binaries. It
+ * also makes a DOWNGRADE impossible, which is the whole defence against a CDN
+ * that has been rolled back to an older (but still validly signed) payload.
+ */
+function isNewerConnectorVersion(available, installed) {
+    const a = parseConnectorVersion(available);
+    const i = parseConnectorVersion(installed);
+    if (!a || !i)
+        return false;
+    if (a.major !== i.major)
+        return a.major > i.major;
+    if (a.minor !== i.minor)
+        return a.minor > i.minor;
+    return a.patch > i.patch;
+}
+/**
+ * The manifest object name for a platform, or null where no manifest is
+ * published. Linux has no packaged connector release and therefore no manifest;
+ * returning null keeps a Linux install from polling a URL that would answer 200
+ * with the marketing SPA on every check, forever.
+ */
+function manifestObjectForPlatform(platform) {
+    if (platform === 'win32')
+        return 'trillboards-connector-windows.version.json';
+    if (platform === 'darwin')
+        return 'trillboards-connector-macos.version.json';
+    return null;
+}
+/** Full manifest URL for a platform, or null. */
+function manifestUrlForPlatform(platform, baseUrl = exports.CONNECTOR_UPDATE_BASE_URL) {
+    const object = manifestObjectForPlatform(platform);
+    if (!object)
+        return null;
+    return `${baseUrl.replace(/\/+$/, '')}/${object}`;
+}
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+/**
+ * Strictly validate a manifest body. Returns null when ANY required field is
+ * absent or malformed — including when the body is the CDN's HTML SPA fallback,
+ * which is what a deleted manifest looks like over the wire.
+ */
+function parseVersionManifest(body) {
+    let raw;
+    try {
+        raw = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const o = raw;
+    if (o.schemaVersion !== 1)
+        return null;
+    if (!isNonEmptyString(o.platform))
+        return null;
+    if (!parseConnectorVersion(o.connectorVersion))
+        return null;
+    if (!isNonEmptyString(o.gitSha))
+        return null;
+    // 64 lowercase hex. The applier compares against this byte for byte, so a
+    // shape it cannot use must not survive parsing.
+    if (typeof o.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(o.sha256))
+        return null;
+    if (typeof o.sizeBytes !== 'number' || !Number.isInteger(o.sizeBytes) || o.sizeBytes <= 0) {
+        return null;
+    }
+    if (!isNonEmptyString(o.publishedAt) || Number.isNaN(Date.parse(o.publishedAt)))
+        return null;
+    if (!isNonEmptyString(o.downloadUrl))
+        return null;
+    const manifest = {
+        schemaVersion: 1,
+        platform: o.platform,
+        connectorVersion: o.connectorVersion,
+        gitSha: o.gitSha,
+        sha256: o.sha256,
+        sizeBytes: o.sizeBytes,
+        publishedAt: o.publishedAt,
+        downloadUrl: o.downloadUrl,
+    };
+    if (isNonEmptyString(o.updateUrl))
+        manifest.updateUrl = o.updateUrl;
+    if (isNonEmptyString(o.updateCatalogUrl))
+        manifest.updateCatalogUrl = o.updateCatalogUrl;
+    return manifest;
+}
+/**
+ * GET a small public object with a HARD byte cap.
+ *
+ * Deliberately not `AudienceAnalyzeClient`'s `defaultHttpPoster`: that one is a
+ * POST-shaped transport that concatenates every chunk with no ceiling, which is
+ * fine for an API we authenticate to and wrong for an unauthenticated public
+ * object whose expected size is 401 bytes. A response that keeps coming is
+ * destroyed rather than buffered.
+ *
+ * `Cache-Control: no-cache` + `Pragma: no-cache` are belt-and-braces. The object
+ * is published `no-cache, no-store, must-revalidate` precisely because it is the
+ * staleness oracle, but an intercepting corporate proxy is not obliged to
+ * honour a response header, and a cached manifest reports the PREVIOUS release
+ * as current for the whole TTL.
+ */
+const defaultManifestFetcher = (url, timeoutMs) => new Promise((resolve, reject) => {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (err) {
+        reject(new Error(`Invalid connector manifest URL: ${err.message}`));
+        return;
+    }
+    const mod = parsed.protocol === 'https:' ? https : http;
+    const req = mod.request(url, {
+        method: 'GET',
+        headers: {
+            Accept: 'application/json',
+            'Cache-Control': 'no-cache',
+            Pragma: 'no-cache',
+        },
+        timeout: timeoutMs,
+    }, (res) => {
+        const chunks = [];
+        let total = 0;
+        res.on('data', (chunk) => {
+            total += chunk.length;
+            if (total > MANIFEST_MAX_BYTES) {
+                res.destroy();
+                reject(new Error('connector manifest exceeded the maximum size'));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        res.on('end', () => {
+            resolve({
+                statusCode: res.statusCode || 0,
+                body: Buffer.concat(chunks).toString('utf-8'),
+            });
+        });
+    });
+    req.on('error', (err) => reject(err));
+    req.on('timeout', () => req.destroy(new Error('connector manifest request timed out')));
+    req.end();
+});
+exports.defaultManifestFetcher = defaultManifestFetcher;
+/** Reads the published manifest for one platform. */
+class ConnectorManifestClient {
+    constructor(options, fetcher) {
+        this.url = manifestUrlForPlatform(options.platform, options.baseUrl);
+        this.timeoutMs = options.timeoutMs ?? MANIFEST_TIMEOUT_MS;
+        this.fetcher = fetcher ?? exports.defaultManifestFetcher;
+    }
+    /** The resolved URL, or null on a platform that publishes no manifest. */
+    getEndpoint() {
+        return this.url;
+    }
+    /**
+     * The published manifest, or null for UNKNOWN — no platform manifest, a
+     * transport failure, a non-2xx, or a body that is not a valid manifest (the
+     * SPA-fallback case). Never throws; the caller keeps sensing either way.
+     */
+    async fetchManifest() {
+        if (!this.url)
+            return null;
+        let result;
+        try {
+            result = await this.fetcher(this.url, this.timeoutMs);
+        }
+        catch {
+            return null;
+        }
+        if (result.statusCode < 200 || result.statusCode >= 300)
+            return null;
+        return parseVersionManifest(result.body);
+    }
+}
+exports.ConnectorManifestClient = ConnectorManifestClient;
+/**
+ * Is this a moment at which the connector may be stopped and replaced?
+ *
+ * The two quantities are the connector's IRRECOVERABLE work:
+ *
+ *  - `inFlight` — a frame the model is answering, or a POST in flight. There is
+ *    no store-and-forward on the Windows connector (`SignalBuffer` is
+ *    constructed only in `EdgeAgent`, which the Windows task never runs), so a
+ *    kill here loses that observation permanently.
+ *  - `buffered` — frames the motion cascade has ALREADY decided are
+ *    interesting: a person entering a restricted area, a spill, a fall. At a
+ *    30 s scan cadence the next look is a different event. `CloudSensingManager
+ *    .stop()` calls `candidates.reset()`, so these die on ANY stop, graceful or
+ *    not — stopping while the buffer is loaded is the dropped-alert failure, and
+ *    it is a product failure, not an implementation detail.
+ *
+ * NOT covered, and stated rather than hidden: a tick can be between
+ * `camera.getFrame()` and the admission gate — mid-decode, mid-motion-eval —
+ * with `inFlight === 0`, because on the cascade path the ticket is not taken
+ * until after the motion verdict. `LoopState.tickInFlight` is private and
+ * exposed nowhere. Losing that frame costs one SAMPLE that the cascade has not
+ * yet judged interesting, which is a different and much smaller loss than a
+ * flagged candidate, and the next tick captures a fresher frame. Widening the
+ * health struct to close it was judged not worth the blast radius.
+ */
+function isSafeToApplyUpdate(busyness) {
+    return busyness.inFlight === 0 && busyness.buffered === 0;
+}
+/**
+ * Map a `getSensingHealth()` reading onto the two numbers that matter. Tolerant
+ * of a partial shape so a test fake or a future manager cannot crash the
+ * watcher; an absent field reads as 0, i.e. "not holding anything", which is
+ * only ever reached by a manager that has no buffer to hold anything in.
+ */
+function busynessOf(health) {
+    return {
+        inFlight: Number.isFinite(health?.inFlight) ? health.inFlight : 0,
+        buffered: Number.isFinite(health?.candidateBuffer?.buffered)
+            ? health.candidateBuffer.buffered
+            : 0,
+    };
+}
+/** Has this release sat long enough to be taken? */
+function isReleaseBakedEnough(manifest, nowMs, minAgeMs = exports.CONNECTOR_UPDATE_MIN_RELEASE_AGE_MS) {
+    const published = Date.parse(manifest.publishedAt);
+    if (Number.isNaN(published))
+        return false;
+    // A publishedAt in the FUTURE (clock skew either side) is not evidence of
+    // age. Refusing is the safe direction: the next check is six hours away.
+    return nowMs - published >= minAgeMs;
+}
+/**
+ * One check: read the manifest, decide whether this install is behind.
+ *
+ * `availableVersion` is null both when the install is current AND when the
+ * manifest could not be read — but `publishedVersion` distinguishes them, so a
+ * caller that must not conflate "current" with "unknown" can.
+ */
+async function checkForConnectorUpdate(installedVersion, client) {
+    const manifest = await client.fetchManifest();
+    if (!manifest) {
+        return { installedVersion, publishedVersion: null, availableVersion: null, manifest: null };
+    }
+    const newer = isNewerConnectorVersion(manifest.connectorVersion, installedVersion);
+    return {
+        installedVersion,
+        publishedVersion: manifest.connectorVersion,
+        availableVersion: newer ? manifest.connectorVersion : null,
+        manifest,
+    };
+}
+/**
+ * Delay before the FIRST check.
+ *
+ * `ModelManager` defers its first check a whole hour, and that is right for a
+ * 2.4 GB model download. It is wrong here: this GET is 401 bytes, and deferring
+ * it six hours would mean a store PC that reboots nightly never reports its
+ * version at all — the fleet view would be blind to exactly the machines most
+ * likely to be stale. Sixty seconds is long enough for sensing to come up first
+ * and short enough that every start contributes a report.
+ *
+ * A fresh release still cannot be applied on that first check: the bake window
+ * is enforced separately, on `publishedAt`.
+ */
+exports.CONNECTOR_UPDATE_INITIAL_DELAY_MS = 60000;
+/** How often the apply state machine looks at the world while an update is in flight. */
+exports.CONNECTOR_UPDATE_POLL_INTERVAL_MS = 60000;
+/**
+ * How long to wait for staging to finish before giving up on this attempt.
+ *
+ * An hour. The payload is ~200 MB, and a store uplink is the slow case this
+ * number is for. Giving up is not a failure — the next check re-stages.
+ */
+exports.CONNECTOR_UPDATE_STAGE_DEADLINE_MS = 60 * 60 * 1000;
+/**
+ * How long to wait for a safe point before applying anyway.
+ *
+ * Two hours, and the branch matters. On a saturated multi-camera install the
+ * candidate buffer may never reach zero — measured on a 24 h 32-camera
+ * simulation, 89,056 of 92,160 candidates were EVICTED, i.e. the buffer is
+ * permanently full and those frames are already being dropped by the buffer's
+ * own fairness bound. Waiting forever for a quiet moment on such a machine
+ * would mean it never receives another fix, which is the strictly worse
+ * outcome. So: take the first genuinely quiet moment; failing that, accept the
+ * loss after two hours and record which branch was taken.
+ */
+exports.CONNECTOR_UPDATE_SAFE_POINT_DEADLINE_MS = 2 * 60 * 60 * 1000;
+/**
+ * The whole update loop: check the manifest, tell the server where this install
+ * stands, and — on Windows, with a verified payload and a quiet moment — apply.
+ *
+ * Every branch is best-effort. A failed check, a failed report, an applier that
+ * will not launch: each is one log line, and sensing continues. The one thing
+ * this must never do is stop the connector for any reason other than a
+ * deliberate, verified handoff.
+ */
+function startConnectorUpdateService(deps) {
+    const client = deps.client ?? new ConnectorManifestClient({ platform: deps.platform });
+    if (!client.getEndpoint())
+        return null;
+    const log = deps.log ?? (() => { });
+    const now = deps.now ?? (() => Date.now());
+    const reportStatus = deps.reportStatus ?? ConnectorStatusClient_1.reportConnectorStatus;
+    const setTimeoutFn = deps.setTimeoutFn ?? setTimeout;
+    const clearTimeoutFn = deps.clearTimeoutFn ?? clearTimeout;
+    const setIntervalFn = deps.setIntervalFn ?? setInterval;
+    const clearIntervalFn = deps.clearIntervalFn ?? clearInterval;
+    const applier = deps.applier ?? null;
+    const requestExit = deps.requestExit ?? (() => process.exit(0));
+    const pollIntervalMs = deps.pollIntervalMs ?? exports.CONNECTOR_UPDATE_POLL_INTERVAL_MS;
+    const stageDeadlineMs = deps.stageDeadlineMs ?? exports.CONNECTOR_UPDATE_STAGE_DEADLINE_MS;
+    const safePointDeadlineMs = deps.safePointDeadlineMs ?? exports.CONNECTOR_UPDATE_SAFE_POINT_DEADLINE_MS;
+    let stopped = false;
+    let phase = 'idle';
+    let target = null;
+    let phaseStartedMs = 0;
+    let pollTimer = null;
+    let checkTimer = null;
+    let initialTimer = null;
+    const unref = (t) => {
+        if (t && typeof t.unref === 'function') {
+            t.unref();
+        }
+    };
+    const endApply = () => {
+        phase = 'idle';
+        target = null;
+        if (pollTimer) {
+            clearIntervalFn(pollTimer);
+            pollTimer = null;
+        }
+    };
+    /**
+     * Report where this install stands, carrying any update outcome the applier
+     * left behind. The outcome is cleared only once the server has ACCEPTED it —
+     * a report that failed must be retried, not discarded, or a machine whose
+     * update was refused looks identical to one that never tried.
+     */
+    const report = async (check) => {
+        const outcome = applier?.readOutcome() ?? null;
+        const result = await reportStatus({
+            apiBaseUrl: deps.apiBaseUrl,
+            deviceTokens: deps.deviceTokens,
+            report: {
+                connectorVersion: deps.installedVersion,
+                // UNDEFINED when the manifest could not be read, so the server leaves
+                // its column alone. `check.availableVersion` is null both for "current"
+                // and for "unknown", and reporting the second as the first would let a
+                // transient CDN failure erase a real drift and re-stamp the row as
+                // freshly-current.
+                ...(check.manifest ? { availableVersion: check.availableVersion } : {}),
+                updateOutcome: outcome,
+            },
+            log,
+        });
+        // Cleared only when EVERY feed's report landed. The outcome file is
+        // machine-wide but the report is per feed, so clearing on the first success
+        // would lose the attempt for any feed that failed later in the loop — on a
+        // 16-camera install, fifteen rows recording a failed update and one that
+        // never will.
+        if (outcome && result.attempted > 0 && result.accepted === result.attempted) {
+            applier?.clearOutcome();
+        }
+    };
+    /** Advance the apply state machine. Called on a short timer while in flight. */
+    const pollApply = () => {
+        if (stopped || phase === 'idle' || !target || !applier)
+            return;
+        const elapsed = now() - phaseStartedMs;
+        if (phase === 'staging') {
+            if (applier.stagedVersion() === target.connectorVersion) {
+                log(`[update] ${target.connectorVersion} is staged and verified — waiting for a safe point`);
+                phase = 'awaiting-safe-point';
+                phaseStartedMs = now();
+                return;
+            }
+            if (elapsed >= stageDeadlineMs) {
+                log('[update] staging did not finish in time — will retry at the next check');
+                endApply();
+            }
+            return;
+        }
+        // awaiting-safe-point
+        const busyness = deps.busyness ? deps.busyness() : { inFlight: 0, buffered: 0 };
+        const safe = isSafeToApplyUpdate(busyness);
+        const overdue = elapsed >= safePointDeadlineMs;
+        if (!safe && !overdue)
+            return;
+        if (!safe) {
+            log(`[update] no safe point in ${Math.round(elapsed / 60000)} min — applying anyway ` +
+                `(inFlight=${busyness.inFlight}, held candidates=${busyness.buffered})`);
+        }
+        else {
+            log('[update] connector is idle — applying');
+        }
+        const version = target.connectorVersion;
+        endApply();
+        if (!applier.commit({ version, currentVersion: deps.installedVersion })) {
+            log('[update] could not launch the applier — staying on the current version');
+            return;
+        }
+        // The applier owns the machine now. Exiting frees bin\node.exe for the swap;
+        // it also means anything after this line does not run.
+        requestExit();
+    };
+    const beginApply = (manifest) => {
+        if (!applier)
+            return;
+        // A verified tree for THIS version may already be on disk: the connector
+        // restarted between staging and the safe point, or the safe point never
+        // arrived before the last check gave up. Re-downloading ~200 MB over a
+        // store's uplink to arrive at bytes we already hold — and already proved
+        // against a signed catalog — is pure waste, and on a connector that
+        // restarts often it is waste every six hours. `staged.json` is written last
+        // and atomically, so its presence means the whole verification ran.
+        const alreadyStaged = applier.stagedVersion() === manifest.connectorVersion;
+        if (!alreadyStaged && !applier.stage({ manifest, currentVersion: deps.installedVersion })) {
+            log('[update] could not launch the applier — staying on the current version');
+            return;
+        }
+        log(alreadyStaged
+            ? `[update] ${manifest.connectorVersion} is already staged — waiting for a safe point`
+            : `[update] staging ${manifest.connectorVersion}`);
+        phase = alreadyStaged ? 'awaiting-safe-point' : 'staging';
+        target = manifest;
+        phaseStartedMs = now();
+        if (!pollTimer) {
+            pollTimer = setIntervalFn(() => {
+                try {
+                    pollApply();
+                }
+                catch (err) {
+                    log(`[update] apply step failed (non-fatal): ${String(err)}`);
+                }
+            }, pollIntervalMs);
+            unref(pollTimer);
+        }
+    };
+    const runCheck = async () => {
+        if (stopped)
+            return;
+        const check = await checkForConnectorUpdate(deps.installedVersion, client);
+        if (!check.manifest) {
+            log('[update] could not read the published version manifest — staleness unknown');
+        }
+        else if (check.availableVersion) {
+            log(`[update] connector ${check.installedVersion} is behind published ${check.availableVersion}`);
+        }
+        await report(check);
+        if (!applier || !check.manifest || !check.availableVersion)
+            return;
+        if (phase !== 'idle')
+            return;
+        if (!check.manifest.updateUrl || !check.manifest.updateCatalogUrl) {
+            log('[update] the published manifest carries no update payload — reported only');
+            return;
+        }
+        if (!isReleaseBakedEnough(check.manifest, now(), deps.minReleaseAgeMs)) {
+            log(`[update] ${check.availableVersion} is too new to take yet — waiting out the bake window`);
+            return;
+        }
+        beginApply(check.manifest);
+    };
+    const safeRunCheck = () => {
+        runCheck().catch((err) => log(`[update] check failed (non-fatal): ${String(err)}`));
+    };
+    initialTimer = setTimeoutFn(safeRunCheck, deps.initialDelayMs ?? exports.CONNECTOR_UPDATE_INITIAL_DELAY_MS);
+    unref(initialTimer);
+    checkTimer = setIntervalFn(safeRunCheck, deps.intervalMs ?? exports.CONNECTOR_UPDATE_CHECK_INTERVAL_MS);
+    unref(checkTimer);
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            try {
+                if (initialTimer)
+                    clearTimeoutFn(initialTimer);
+                if (checkTimer)
+                    clearIntervalFn(checkTimer);
+                if (pollTimer)
+                    clearIntervalFn(pollTimer);
+            }
+            catch {
+                /* best-effort */
+            }
+            initialTimer = null;
+            checkTimer = null;
+            pollTimer = null;
+        },
+    };
+}
+/**
+ * Every device token this install holds, de-duplicated.
+ *
+ * One token per feed, because a token binds to exactly one screen — so a
+ * 16-camera store reports 16 times and every screen's row carries the version
+ * of the one connector serving it. Structurally typed rather than importing
+ * `EdgeAgentConfig` so this stays testable without a config file on disk.
+ */
+function connectorDeviceTokens(config) {
+    const tokens = [];
+    for (const camera of config.cameras ?? []) {
+        if (camera?.deviceToken)
+            tokens.push(camera.deviceToken);
+    }
+    if (config.deviceToken)
+        tokens.push(config.deviceToken);
+    return Array.from(new Set(tokens));
+}
+/**
+ * The one call every long-running sensing entrypoint makes.
+ *
+ * Deliberately NOT wired inside `buildCloudSensingManager`/
+ * `buildLocalSensingManager`: `auto-sense` builds BOTH managers and caches them,
+ * so a watcher created per manager would give that mode two update loops racing
+ * each other into the same swap. It belongs to the PROCESS, so it is started
+ * once per entrypoint.
+ *
+ * `combinedSense` (`sense`) is deliberately absent: the Windows task's
+ * `ValidateSet` admits only auto-sense/local-sense/cloud-sense, so that mode
+ * never runs on the platform this applies to.
+ */
+function startConnectorUpdates(opts) {
+    const platform = opts.platform ?? process.platform;
+    const apiBaseUrl = opts.config.apiBaseUrl;
+    const deviceTokens = connectorDeviceTokens(opts.config);
+    if (!apiBaseUrl || deviceTokens.length === 0)
+        return null;
+    let applier = null;
+    if (platform === 'win32') {
+        try {
+            // Lazy so the module graph stays acyclic and a non-Windows connector never
+            // loads the applier at all.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const mod = require('./connectorUpdateApply');
+            const candidate = new mod.WindowsConnectorUpdateApplier({ log: opts.log });
+            applier = candidate.installRoot() ? candidate : null;
+        }
+        catch {
+            applier = null;
+        }
+    }
+    try {
+        return startConnectorUpdateService({
+            installedVersion: opts.installedVersion,
+            platform,
+            apiBaseUrl,
+            deviceTokens,
+            busyness: opts.busyness,
+            requestExit: opts.requestExit,
+            applier,
+            log: opts.log,
+        });
+    }
+    catch {
+        // An update loop that cannot start must never stop a connector from sensing.
+        return null;
+    }
+}
+//# sourceMappingURL=connectorUpdate.js.map