@camstack/server 1.1.61 → 1.1.63

package/dist/api/trpc/trpc.router.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enrichInputWithUserAgent = enrichInputWithUserAgent;
+exports.enrichInputWithRelayClass = enrichInputWithRelayClass;
 exports.wrapWebrtcSessionProviderWithRelay = wrapWebrtcSessionProviderWithRelay;
 exports.buildAppRouter = buildAppRouter;
 const addon_settings_router_js_1 = require("../core/addon-settings.router.js");
@@ -39,30 +40,93 @@ function enrichInputWithUserAgent(input, userAgent) {
     };
 }
 /**
- * Relay-only forcing for remote viewers is DISABLED (2026-05-26).
+ * Operator gate for FORCING TURN-relay-only ICE on genuinely-remote viewers.
+ * DEFAULT OFF.
  *
- * It was meant to give CGNAT/4G viewers a clean relay↔relay path, but werift's
- * TURN media-forward is unreliable between two real TURN servers (relay↔relay
- * connects yet media never arrives → connected-but-black), and forcing relay
- * ALSO kills the direct LAN/Tailscale host pair — which carries full native
- * quality with no relay. We now offer ALL candidates (host incl. the hub's
- * advertised Tailscale address, srflx, relay) and let ICE nominate the best
- * reachable pair: direct when possible, relay only as a fallback. The
- * `relayOnly` cap field + broker support remain for when relay media-forward
- * is fixed.
+ * The forced relay↔relay path is disabled by default because it was NEVER
+ * validated to deliver media. It was originally disabled on 2026-05-26 after a
+ * connected relay session produced a black picture — ICE/DTLS completed but no
+ * decodable media was forwarded over the relay (a MEDIA-FORWARD reliability
+ * bug, not a signalling one). The later werift+0.22.9 patch
+ * (`patches/werift+0.22.9.patch`) fixed a DIFFERENT bug — a host/srflx
+ * candidate LEAK in the forced-relay SDP — and does nothing for relay
+ * media-forward, so the connected-but-black regression remains unproven-fixed.
  *
- * The wrapper additionally enriches the `createSession` / `handleOffer`
- * subscriber attribution with the originating client's User-Agent, read
- * from the tRPC request context (browser sessions). All OTHER methods
- * delegate straight through — auth, the remote-proxy factory and every
- * signaling behaviour are untouched.
+ * Until an operator confirms that ONE real remote relay session (4G /
+ * Cloudflare-tunnel) actually delivers media, remote viewers stay on the same
+ * `relayOnly:false` path as everyone else. Set `CAMSTACK_FORCE_RELAY_REMOTE=1`
+ * (or `true`) to re-enable remote→relay once validated; the broker's pairClass
+ * logging is the instrument for that validation.
+ */
+const FORCE_RELAY_REMOTE = process.env.CAMSTACK_FORCE_RELAY_REMOTE === '1' ||
+    process.env.CAMSTACK_FORCE_RELAY_REMOTE === 'true';
+/**
+ * Inject the SERVER-computed `relayOnly` ICE override.
+ *
+ * The client's three-way classification (`lan | vpn | remote`, see
+ * `client-ip.ts`) is ALWAYS computed by the caller and passed here so the
+ * broker's pairClass logging can observe the viewer class for every session.
+ * Whether that class actually forces a relay is gated by
+ * `FORCE_RELAY_REMOTE` (default OFF — see above):
+ *   - gate OFF → `relayOnly: false` for ALL classes (today's effective,
+ *     validated behaviour: nobody is forced onto the unproven relay path).
+ *   - gate ON  → `deriveRelayOnly(clientClass)` — only genuinely-remote
+ *     viewers (public / CGNAT-4G / Cloudflare-tunnel) get `relayOnly: true`;
+ *     `lan` and `vpn` (Tailscale) keep the low-latency direct host/srflx path.
+ *
+ * When the class is `null` (mesh-originated call — no request context) the
+ * input passes through UNCHANGED so a trusted addon-set `relayOnly` (e.g.
+ * Alexa) is never clobbered. Any client-supplied `relayOnly` on a
+ * request-bound call IS overwritten — the hub trusts only the request context.
+ *
+ * Immutable — builds a NEW input object, never mutates the caller's.
+ */
+function enrichInputWithRelayClass(input, clientClass) {
+    if (clientClass === null)
+        return input;
+    const relayOnly = FORCE_RELAY_REMOTE ? (0, client_ip_js_1.deriveRelayOnly)(clientClass) : false;
+    return { ...input, relayOnly };
+}
+/**
+ * Per-request wrapper around the resolved `webrtc-session` broker singleton.
+ *
+ * Two SERVER-side enrichments, both read from the tRPC request context (the
+ * broker is a forked addon that cannot see the HTTP request):
+ *  1. `relayOnly` — the ICE policy. The client is classified three ways
+ *     (`lan | vpn | remote`, 2026-07-15): Tailscale (`vpn`) is distinguished
+ *     from genuine internet (`remote`) and Cloudflare Tunnel's
+ *     `CF-Connecting-IP` on the loopback connector path is honoured, closing
+ *     the two blind spots the boolean classifier had (a tailnet client on the
+ *     hub's own 100.64/10 address is `vpn`; a Cloudflare-tunneled viewer with
+ *     a loopback socket peer is `remote`, not misread as LAN). The class is
+ *     ALWAYS computed and threaded so the broker's pairClass logging can
+ *     observe it — but FORCING remote viewers onto a relay↔relay path is
+ *     GATED OFF by default (`CAMSTACK_FORCE_RELAY_REMOTE`, see
+ *     `enrichInputWithRelayClass`).
+ *
+ *     Why gated: the forced-relay MEDIA-FORWARD path was disabled on
+ *     2026-05-26 because a connected relay session delivered NO decodable
+ *     media (ICE/DTLS up, picture black). The werift+0.22.9 patch
+ *     (`patches/werift+0.22.9.patch`) fixed a DIFFERENT bug — the forced-relay
+ *     SDP host/srflx candidate LEAK — and does NOT address relay
+ *     media-forward, so the connected-but-black regression is still unproven-
+ *     fixed. The flag lets the operator re-enable remote→relay only after
+ *     validating that ONE real 4G / Cloudflare-tunnel relay session actually
+ *     delivers media (the broker pairClass logging is the instrument). Until
+ *     then every class gets `relayOnly:false`.
+ *  2. `consumerAttribution.userAgent` — the browser UA for the broker's
+ *     client list.
+ *
+ * All OTHER methods delegate straight through — auth, the remote-proxy
+ * factory and every signaling behaviour are untouched.
  */
 function wrapWebrtcSessionProviderWithRelay(provider, ctx) {
     const userAgent = (0, client_ip_js_1.extractUserAgent)(ctx.req);
+    const clientClass = (0, client_ip_js_1.classifyClientRequest)(ctx.req);
     return {
         ...provider,
-        createSession: (input) => provider.createSession(enrichInputWithUserAgent(input, userAgent)),
-        handleOffer: (input) => provider.handleOffer(enrichInputWithUserAgent(input, userAgent)),
+        createSession: (input) => provider.createSession(enrichInputWithRelayClass(enrichInputWithUserAgent(input, userAgent), clientClass)),
+        handleOffer: (input) => provider.handleOffer(enrichInputWithRelayClass(enrichInputWithUserAgent(input, userAgent), clientClass)),
     };
 }
 /**

package/dist/core/addon/addon-registry.service.js

@@ -38,6 +38,7 @@ exports.shouldEmitProviderRegisteredReady = shouldEmitProviderRegisteredReady;
 /* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access -- pre-existing lint debt across this 2200-line orchestration class. The flagged sites (StorageService.setLocationManager / setSettingsBackend, LoggingService.addDestination, RouteRegistry, etc.) are typed as `unknown` by their owning services to break circular construction-order dependencies; runtime contracts are validated structurally. Tracked separately; do not amend in unrelated edits. */
 const os = __importStar(require("node:os"));
 const addon_row_manifest_1 = require("./addon-row-manifest");
+const runner_convergence_1 = require("./runner-convergence");
 const types_1 = require("@camstack/types");
 const system_1 = require("@camstack/system");
 const system_2 = require("@camstack/system");
@@ -84,6 +85,15 @@ function isSettingsStore(backend) {
 function isAddonRoutesInvoker(provider) {
     return typeof Reflect.get(provider, 'invoke') === 'function';
 }
+/**
+ * Window within which a second `restart:true` respawn of the SAME group runner
+ * is coalesced to a no-op (a package reload loops `restartAddon` over every
+ * group member — see `recentGroupRespawns`). Chosen comfortably longer than a
+ * single group respawn (child fork + init) so all members of one reload pass
+ * fall inside it, and short enough that a genuinely independent later restart
+ * still respawns.
+ */
+const GROUP_RESPAWN_COALESCE_MS = 10_000;
 const ROUTE_METHODS = [
     'GET',
     'POST',
@@ -197,6 +207,17 @@ class AddonRegistryService {
      * `restartAddon` completes (success or failure) or by a 90s safety timer.
      */
     restartingAddons = new Map();
+    /**
+     * `runnerId → last-respawn epoch-ms`, used ONLY to coalesce redundant group
+     * respawns. A package reload loops `restartAddon` over EVERY addon in the
+     * package (`tryReloadPackage`); for a co-location group that maps N members
+     * onto ONE runner, the first member's restart already respawns the whole
+     * group (all members reboot from fresh on-disk code), so the 2nd..Nth
+     * restarts must NOT respawn again — that churns the runner N times and risks
+     * tripping the crash circuit-breaker. Consulted by `ensureForkedRunner`; only
+     * groups (roster > 1) are coalesced, so solo-addon restart stays byte-identical.
+     */
+    recentGroupRespawns = new Map();
     logger;
     addonLoader;
     healthMonitor;
@@ -1096,17 +1117,22 @@ class AddonRegistryService {
         // `@camstack/system` builtins reach the in-process path below) it
         // boots in-process on the hub.
         if (this.isForkedAddonEntry(entry)) {
-            // D5: one-addon-one-process. A forked addon ALWAYS boots in its
-            // own runner — there is NO in-process-on-the-hub fallback. If the
-            // runner spawn fails, the addon is `failed`, surfaced as
-            // `addon.error` + recorded on the health monitor; it does not
-            // silently run on the hub. (Task 7's circuit breaker governs the
-            // retry policy on top of this.)
+            // D5 + co-location: a forked addon ALWAYS boots in a runner — there is
+            // NO in-process-on-the-hub fallback. `ensureForkedRunner` resolves the
+            // addon's runner id (`resolveRunnerId`) and spawns/joins the FULL
+            // co-located roster: a groupless addon gets its own runner (one addon,
+            // one process — unchanged), while a `execution.group` member co-locates
+            // with its siblings so cross-addon cap calls resolve in-process (zero
+            // copy). Idempotent when a sibling already brought the group up. If the
+            // spawn fails, the addon is `failed`, surfaced as `addon.error` +
+            // recorded on the health monitor; it does not silently run on the hub.
+            // (Task 7's circuit breaker governs the retry policy on top of this.)
+            //
+            // Provider registration for forkable addons is delegated to the
+            // `CapabilityBridge` (see `MoleculerService.onProviderConnected`);
+            // custom actions are (re-)registered inside `ensureForkedRunner`.
             try {
-                await this.broker.call('$process.spawnRunner', {
-                    runnerId: id,
-                    addons: [{ addonId: id, addonDir: entry.addonDir }],
-                });
+                await this.ensureForkedRunner(id, { restart: false });
             }
             catch (err) {
                 const msg = (0, types_1.errMsg)(err);
@@ -1121,23 +1147,6 @@ class AddonRegistryService {
                 this.healthMonitor.recordFailure(entry.packageName, err, id);
                 throw new Error(`Failed to spawn runner for addon "${id}": ${msg}`, { cause: err });
             }
-            // Provider registration for forkable addons is delegated to the
-            // `CapabilityBridge` (see `MoleculerService.onProviderConnected`).
-            // When the spawned child announces its Moleculer service via
-            // NODE_INFO, the bridge builds a proxy from the capability
-            // definition (`{ id, nodeId, ...methods }`) and registers it.
-            //
-            // Custom actions: read the catalog fresh from the on-disk bundle
-            // and register it against the hub-side `CustomActionRegistry`.
-            // `registerForkedAddonCustomActions` re-`import()`s the entry
-            // (cache-busted), so it covers the hot-load path — where the addon
-            // was registered via `freshLoader` and `this.addonLoader`'s cached
-            // `module` namespace is stale or absent. Dispatch routes through
-            // `broker.call('<addonId>.custom.<action>')`, the only divergence
-            // vs in-process being the transport, exactly like cap methods.
-            await this.registerForkedAddonCustomActions(id, 
-            // `isForkedAddonEntry` narrowed `entry.declaration` to non-null.
-            (0, types_1.resolveRunnerId)(entry.declaration, id));
             entry.initialized = true;
             this.logger.info('Addon spawned as isolated process', { tags: { addonId: id } });
             this.emitAddonLifecycleEvent('addon.started', id);
@@ -1357,23 +1366,40 @@ class AddonRegistryService {
         // restarts. The Moleculer `$node.disconnected` handler skips entries
         // present in `restartingAddons`; a 90s safety timer clears the flag
         // even if the restart path throws before the finally block runs.
-        const existingTimer = this.restartingAddons.get(addonId);
-        if (existingTimer)
-            clearTimeout(existingTimer);
-        const safetyTimer = setTimeout(() => {
-            this.restartingAddons.delete(addonId);
-        }, 90_000);
-        this.restartingAddons.set(addonId, safetyTimer);
+        // Suppress the banner for the restarted addon AND — for a co-location
+        // group — every SIBLING sharing its runner. `ensureForkedRunner` respawns
+        // the WHOLE group process, so all members briefly `$node.disconnect`; without
+        // suppressing the siblings too, each would flash a spurious "Failed to load".
+        const suppressed = new Set([addonId]);
+        if (this.isForkedAddonEntry(entry)) {
+            const runnerId = (0, types_1.resolveRunnerId)(entry.declaration, addonId);
+            for (const { addonId: siblingId } of this.buildAddonGroupPlan([
+                ...this.addonEntries.keys(),
+            ]).get(runnerId) ?? []) {
+                suppressed.add(siblingId);
+            }
+        }
+        for (const id of suppressed) {
+            const prior = this.restartingAddons.get(id);
+            if (prior)
+                clearTimeout(prior);
+            const timer = setTimeout(() => {
+                this.restartingAddons.delete(id);
+            }, 90_000);
+            this.restartingAddons.set(id, timer);
+        }
         try {
-            // Group-runner-hosted addon — delegate to $process.restart for the group
+            // Group-runner-hosted addon — converge the runner topology onto the
+            // declared group, then respawn it. `ensureForkedRunner({ restart: true })`
+            // both (a) adopts a NEW roster if `execution.group` changed since the
+            // runner last spawned (stop stale solo runners → spawn the group; a plain
+            // `$process.restart` would respawn the OLD roster forever), and (b) on the
+            // common path respawns the group in place so the child reboots the WHOLE
+            // roster from the freshly-swapped on-disk bundle. Updating ONE member of a
+            // group therefore respawns the ENTIRE group — they share a process.
             if (this.isForkedAddonEntry(entry)) {
-                const result = (await this.broker.call('$process.restart', {
-                    name: addonId,
-                }));
-                if (!result.success) {
-                    throw new Error(`Process restart failed: ${result.reason ?? 'unknown'}`);
-                }
-                // $process.restart resolves as soon as the child is respawned, not when its
+                await this.ensureForkedRunner(addonId, { restart: true });
+                // The respawn resolves as soon as the child is up, not when its
                 // capabilities are re-registered. Callers (integrations.create, UI forms) may
                 // immediately try to route to the provider and hit a transient null. Block here
                 // until every declared capability is back on the registry so the restart is
@@ -1413,16 +1439,10 @@ class AddonRegistryService {
                             `(re-register asynchronously — e.g. device-scoped caps awaiting devices): ${missing.join(', ')}`, { tags: { addonId } });
                     }
                 }
-                // Re-register the addon's custom-action catalog. `$process.restart`
-                // respawns the group child and `CapabilityBridge` re-registers cap
-                // providers — but custom actions live in the hub-side
-                // `CustomActionRegistry`, which the restart path never touched.
-                // Without this, every hot-update of a group-hosted addon silently
-                // drops its custom actions (the catalog is only registered once,
-                // at boot, in `initializeAddonGroup`). Reads a fresh catalog from
-                // the just-updated on-disk bundle.
-                const runnerId = (0, types_1.resolveRunnerId)(entry.declaration, addonId);
-                await this.registerForkedAddonCustomActions(addonId, runnerId);
+                // Custom actions are re-registered inside `ensureForkedRunner` for
+                // every roster member (custom actions live in the hub-side
+                // `CustomActionRegistry`, which the process spawn never touches — a
+                // hot-update would otherwise silently drop them).
                 this.logAddonLifecycle('restarted', addonId, 'isolated');
                 this.emitAddonLifecycleEvent('addon.restarted', addonId);
                 return { success: true };
@@ -1483,13 +1503,16 @@ class AddonRegistryService {
             return { success: false, error: msg };
         }
         finally {
-            // Clear the suppression flag regardless of success/failure — if the
-            // restart failed, the operator will see the real error via the
-            // mutation result rather than a misleading transient health blip.
-            const timer = this.restartingAddons.get(addonId);
-            if (timer)
-                clearTimeout(timer);
-            this.restartingAddons.delete(addonId);
+            // Clear the suppression flags (restarted addon + any group siblings)
+            // regardless of success/failure — if the restart failed, the operator
+            // sees the real error via the mutation result rather than a misleading
+            // transient health blip.
+            for (const id of suppressed) {
+                const timer = this.restartingAddons.get(id);
+                if (timer)
+                    clearTimeout(timer);
+                this.restartingAddons.delete(id);
+            }
         }
     }
     getAddon(id) {
@@ -2705,6 +2728,107 @@ class AddonRegistryService {
             meta: { runnerId, addonCount: addons.length, addonIds: addons.map((a) => a.addonId) },
         });
     }
+    /**
+     * Snapshot of the live runner subprocesses (`$process.list`), reduced to the
+     * `{ runnerId, addonIds }` shape the convergence planner needs. Returns `[]`
+     * on any broker error so the caller degrades to a fresh spawn rather than
+     * throwing — a missing list can only mean "nothing is running".
+     */
+    async listRunnerProcesses() {
+        try {
+            // `$process.*` is an untyped Moleculer infra boundary (returns `unknown`);
+            // the process-service owns the `ProcessInfo` shape. Narrow to the two
+            // fields the planner reads.
+            const procs = (await this.broker.call('$process.list'));
+            return procs.map((p) => ({ name: p.name, addonIds: p.addonIds }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Group-aware, convergent forked-runner spawn — the SINGLE authority for
+     * bringing an addon's runner up OUTSIDE the boot plan (hot-install, retry,
+     * operator restart, deploy hot-reload). The boot plan
+     * (`buildAddonGroupPlan` → `initializeAddonGroup`) already groups; this makes
+     * every OTHER lifecycle path honour `execution.group` too, so co-location is
+     * not silently lost the moment an addon is (re)spawned post-boot.
+     *
+     * Resolves the runner id via `resolveRunnerId` and the FULL co-located roster
+     * via `buildAddonGroupPlan` (the same authority the boot plan uses), then
+     * converges the live process topology onto that roster (see
+     * `planRunnerConvergence`): stop stale/mismatched runners, then spawn or
+     * restart the group runner. Idempotent — safe to call once per roster member
+     * (the 2nd..Nth calls see the correct topology and no-op). A groupless addon
+     * keys to a size-1 roster whose runner id is its own id, so its behaviour is
+     * byte-identical to the pre-group solo path.
+     *
+     * `opts.restart` respawns the group in place even when the roster already
+     * matches — the deploy hot-reload path, so the child reboots the WHOLE roster
+     * from the freshly-swapped on-disk bundle. This is why updating ONE member of
+     * a group respawns the ENTIRE group (they share a process): the operator's
+     * "update one → respawn the whole group" invariant.
+     */
+    async ensureForkedRunner(addonId, opts) {
+        const entry = this.addonEntries.get(addonId);
+        if (!entry?.declaration || !entry.addonDir) {
+            throw new Error(`ensureForkedRunner("${addonId}") requires an on-disk forked addon`);
+        }
+        const runnerId = (0, types_1.resolveRunnerId)(entry.declaration, addonId);
+        const roster = this.buildAddonGroupPlan([...this.addonEntries.keys()]).get(runnerId) ?? [
+            { addonId, addonDir: entry.addonDir },
+        ];
+        // Coalesce redundant group respawns: a package reload loops `restartAddon`
+        // over every member of a co-location group, but the FIRST member's restart
+        // already respawned the whole runner (every member rebooted from fresh disk
+        // code). For a GROUP (roster > 1) whose runner was respawned inside the
+        // coalesce window, downgrade a restart request to a plain topology check so
+        // the 2nd..Nth members don't churn the runner. Solo addons (roster == 1) are
+        // never coalesced — their behaviour stays byte-identical.
+        const effectiveRestart = opts.restart &&
+            roster.length > 1 &&
+            Date.now() - (this.recentGroupRespawns.get(runnerId) ?? 0) < GROUP_RESPAWN_COALESCE_MS
+            ? false
+            : opts.restart;
+        const running = await this.listRunnerProcesses();
+        const plan = (0, runner_convergence_1.planRunnerConvergence)(runnerId, roster.map((r) => r.addonId), running, { restart: effectiveRestart });
+        // 1. Tear down every stale/mismatched runner that hosts a roster member.
+        for (const name of plan.stop) {
+            await this.broker.call('$process.stop', { name }).catch((err) => {
+                this.logger.warn('ensureForkedRunner: failed to stop stale runner (continuing)', {
+                    meta: { runnerId, stale: name, error: (0, types_1.errMsg)(err) },
+                });
+            });
+        }
+        // 2. Bring the target runner to the correct roster.
+        if (plan.action === 'spawn') {
+            await this.broker.call('$process.spawnRunner', { runnerId, addons: roster }).catch((err) => {
+                // A concurrent path may have won the spawn race — treat "already
+                // running" as success (idempotent), rethrow anything else.
+                if (!/already running/i.test((0, types_1.errMsg)(err)))
+                    throw err;
+            });
+            this.recentGroupRespawns.set(runnerId, Date.now());
+        }
+        else if (plan.action === 'restart') {
+            const res = (await this.broker.call('$process.restart', { name: runnerId }));
+            if (!res.success) {
+                throw new Error(`Process restart failed: ${res.reason ?? 'unknown'}`);
+            }
+            this.recentGroupRespawns.set(runnerId, Date.now());
+        }
+        // 3. Bookkeeping for EVERY roster member. Custom actions live in the
+        //    hub-side registry the process spawn never touches; a hot-update would
+        //    otherwise silently drop them (the boot plan is the only other place
+        //    they register). Mark each member initialized so the in-process
+        //    core-builtin boot passes skip them.
+        for (const { addonId: memberId } of roster) {
+            await this.registerForkedAddonCustomActions(memberId, runnerId);
+            const memberEntry = this.addonEntries.get(memberId);
+            if (memberEntry)
+                memberEntry.initialized = true;
+        }
+    }
     /**
      * (Re-)register the custom-action catalog for a forked / group-hosted
      * addon against the shared `CustomActionRegistry`.

package/dist/core/addon/runner-convergence.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Group-runner convergence planner (pure).
+ *
+ * Group membership is decided ONCE, at a runner's FIRST spawn — the `addons`
+ * array handed to `$process.spawnRunner`. Every later lifecycle op preserves
+ * it: `$process.restart` respawns a runner from its CAPTURED `runnerAddons`,
+ * never from a freshly-declared roster. That means the boot plan
+ * (`buildAddonGroupPlan` → `initializeAddonGroup`) is not the only place that
+ * has to be group-aware: any path that (re)spawns an addon's runner outside
+ * boot (hot-install, retry, operator restart, deploy hot-reload) must converge
+ * the LIVE process topology onto the addon's DECLARED runner id
+ * (`resolveRunnerId`) and its full co-located roster.
+ *
+ * This module holds the decision as a pure function so it is unit-testable
+ * without the heavyweight `AddonRegistryService`. The caller
+ * (`ensureForkedRunner`) executes the plan against `$process.*`.
+ *
+ * Why not just `$process.restart` the addon? Because restart respawns the
+ * runner's OLD roster. A runner named `detection` that was spawned solo (with
+ * only `pipeline-runner`, before the group manifest shipped) would be respawned
+ * solo forever. To adopt a NEW roster the stale runner(s) must be STOPPED and
+ * the group spawned fresh — the convergence this planner encodes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planRunnerConvergence = planRunnerConvergence;
+function sameRoster(addonIds, rosterSet) {
+    return addonIds.length === rosterSet.size && addonIds.every((a) => rosterSet.has(a));
+}
+/**
+ * Decide how to converge the live runner topology onto the declared group.
+ *
+ * @param runnerId       the addon's resolved runner id (`resolveRunnerId`).
+ * @param rosterAddonIds the FULL co-located roster (every eligible addon that
+ *                       resolves to `runnerId`). Always includes the addon
+ *                       itself; size-1 for a groupless addon.
+ * @param running        current runner subprocesses (`$process.list`).
+ * @param opts.restart   true when the caller wants an in-place respawn even if
+ *                       the roster already matches (deploy hot-reload path).
+ */
+function planRunnerConvergence(runnerId, rosterAddonIds, running, opts) {
+    const rosterSet = new Set(rosterAddonIds);
+    const target = running.find((p) => p.name === runnerId);
+    const targetIsCorrect = target !== undefined && sameRoster(target.addonIds, rosterSet);
+    if (targetIsCorrect) {
+        // The exact group runner is already up. Only stragglers to stop are OTHER
+        // runners that (wrongly) host a roster member.
+        const stop = running
+            .filter((p) => p.name !== runnerId && p.addonIds.some((a) => rosterSet.has(a)))
+            .map((p) => p.name);
+        return { stop, action: opts.restart ? 'restart' : 'none' };
+    }
+    // No correct runner: either nothing hosts the roster, or a same-id runner
+    // carries the WRONG roster, or roster members are scattered across stale
+    // solo runners. Stop every runner that hosts a roster member (INCLUDING a
+    // wrong-roster same-id runner — restart would just re-spawn its stale
+    // roster), then spawn the group fresh.
+    const stop = running
+        .filter((p) => p.name === runnerId || p.addonIds.some((a) => rosterSet.has(a)))
+        .map((p) => p.name);
+    return { stop, action: 'spawn' };
+}

package/dist/main.js

@@ -721,7 +721,14 @@ async function bootstrap() {
         // Addon HTTP API route catch-all: /addon/:addonId/*
         // Only handles non-GET or routes that actually exist in the addon route registry.
         // GET requests that don't match an addon route are SPA pages — handled by the /* fallback.
-        fastify.all('/addon/:addonId/*', async (request, reply) => {
+        //
+        // `compress: false`: the bridged reply body of a FORKED addon crosses the
+        // UDS route bridge as opaque bytes; piping those through the hub's global
+        // @fastify/compress emits an EMPTY brotli stream for any compressible body
+        // >1KiB (live-diagnosed 2026-07-16 — broke the notifier SVG icons; same
+        // class addon-upload.ts already dodges). Addons that care about coding own
+        // it end-to-end (see the notifier icon routes).
+        fastify.all('/addon/:addonId/*', { compress: false }, async (request, reply) => {
             const { addonId } = request.params;
             const subPath = request.params['*'] ?? '';
             const method = request.method;