@camstack/server 1.2.267 → 1.2.269

package/dist/api/trpc/ws-slow-consumer-guard.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WsSlowConsumerGuard = exports.WS_SLOW_CONSUMER_POLL_MS = exports.WS_SLOW_CONSUMER_GRACE_MS = exports.WS_SLOW_CONSUMER_MAX_BUFFERED_BYTES = void 0;
+exports.wsConnectionFacts = wsConnectionFacts;
+const client_ip_js_1 = require("./client-ip.js");
+/** Queued bytes above which a client is a slow consumer. */
+exports.WS_SLOW_CONSUMER_MAX_BUFFERED_BYTES = 16 * 1024 * 1024;
+/** How long the queue may stay above the bound before the socket is terminated. */
+exports.WS_SLOW_CONSUMER_GRACE_MS = 30_000;
+/** How often every connection's queue is read. A getter per socket; free. */
+exports.WS_SLOW_CONSUMER_POLL_MS = 5_000;
+/** WebSocket close code for a socket that was never closed cleanly. */
+const ABNORMAL_CLOSURE = 1006;
+const UNIDENTIFIED = '(unidentified)';
+class WsSlowConsumerGuard {
+    connections = new Set();
+    bySocket = new WeakMap();
+    logger;
+    maxBufferedBytes;
+    graceMs;
+    pollMs;
+    now;
+    timer = null;
+    constructor(options) {
+        this.logger = options.logger;
+        this.maxBufferedBytes = options.maxBufferedBytes ?? exports.WS_SLOW_CONSUMER_MAX_BUFFERED_BYTES;
+        this.graceMs = options.graceMs ?? exports.WS_SLOW_CONSUMER_GRACE_MS;
+        this.pollMs = options.pollMs ?? exports.WS_SLOW_CONSUMER_POLL_MS;
+        this.now = options.now ?? (() => Date.now());
+    }
+    /** Watch one connection until it closes. */
+    attach(socket, facts) {
+        const connection = {
+            socket,
+            facts,
+            openedAt: this.now(),
+            principal: UNIDENTIFIED,
+            overSince: null,
+            peakBufferedBytes: 0,
+            terminated: false,
+        };
+        this.connections.add(connection);
+        this.bySocket.set(socket, connection);
+        socket.once('close', (code, reason) => {
+            this.connections.delete(connection);
+            this.logger.info('tRPC WS connection closed', {
+                meta: {
+                    ...this.describe(connection),
+                    code,
+                    reason: reason.length > 0 ? reason.toString('utf8') : '',
+                    closedBy: connection.terminated
+                        ? 'slow-consumer-guard'
+                        : code === ABNORMAL_CLOSURE
+                            ? 'peer gone or keep-alive PING unanswered'
+                            : 'peer',
+                },
+            });
+        });
+    }
+    /** Name the connection's principal once the WS context resolved it. */
+    identify(socket, principal) {
+        const connection = this.bySocket.get(socket);
+        if (connection !== undefined)
+            connection.principal = principal;
+    }
+    /** Read every queue once. Exposed for the spec; production runs it on {@link start}. */
+    poll() {
+        const at = this.now();
+        for (const connection of this.connections) {
+            try {
+                this.judge(connection, at);
+            }
+            catch (err) {
+                // A diagnostic must never take down what it guards; say so instead.
+                this.logger.warn('tRPC WS slow-consumer guard could not read a socket', {
+                    meta: { ...this.describe(connection), error: errorMessage(err) },
+                });
+            }
+        }
+    }
+    start() {
+        if (this.timer !== null)
+            return;
+        this.timer = setInterval(() => this.poll(), this.pollMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer === null)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    judge(connection, at) {
+        if (connection.terminated)
+            return;
+        const buffered = connection.socket.bufferedAmount;
+        if (buffered > connection.peakBufferedBytes)
+            connection.peakBufferedBytes = buffered;
+        if (buffered <= this.maxBufferedBytes) {
+            if (connection.overSince !== null) {
+                // It came back: say so, so a merely slow client is visible and not confused
+                // with the ones that are terminated.
+                this.logger.info('tRPC WS client drained a backlog that had crossed the bound', {
+                    meta: {
+                        ...this.describe(connection),
+                        overForMs: at - connection.overSince,
+                        bufferedBytes: buffered,
+                    },
+                });
+                connection.overSince = null;
+                connection.peakBufferedBytes = buffered;
+            }
+            return;
+        }
+        connection.overSince ??= at;
+        const overForMs = at - connection.overSince;
+        if (overForMs < this.graceMs)
+            return;
+        connection.terminated = true;
+        this.logger.warn('tRPC WS client disconnected — slow consumer: it stopped reading and its send queue ' +
+            'stayed above the bound for the whole grace period (a backgrounded viewer keeps the ' +
+            'socket open with its JS suspended; the queue lived in hub-main old_space)', {
+            meta: {
+                ...this.describe(connection),
+                bufferedBytes: buffered,
+                overForMs,
+                boundBytes: this.maxBufferedBytes,
+                graceMs: this.graceMs,
+            },
+        });
+        connection.socket.terminate();
+    }
+    describe(connection) {
+        return {
+            ip: connection.facts.ip ?? UNIDENTIFIED,
+            userAgent: connection.facts.userAgent ?? UNIDENTIFIED,
+            principal: connection.principal,
+            bytesRead: safeCount(connection.facts.bytesRead),
+            bytesWritten: safeCount(connection.facts.bytesWritten),
+            peakBufferedBytes: connection.peakBufferedBytes,
+            connectionAgeMs: this.now() - connection.openedAt,
+        };
+    }
+}
+exports.WsSlowConsumerGuard = WsSlowConsumerGuard;
+function safeCount(read) {
+    try {
+        return read();
+    }
+    catch {
+        // A destroyed socket may have dropped its handle; null is "unknown", never 0.
+        return null;
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** The facts a real `ws` upgrade request provides. */
+function wsConnectionFacts(req) {
+    return {
+        ip: (0, client_ip_js_1.extractClientIp)(req),
+        userAgent: (0, client_ip_js_1.extractUserAgent)(req),
+        bytesRead: () => req.socket.bytesRead,
+        bytesWritten: () => req.socket.bytesWritten,
+    };
+}

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

@@ -43,7 +43,6 @@ const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
-const node_url_1 = require("node:url");
 const system_1 = require("@camstack/system");
 const types_1 = require("@camstack/types");
 const client_1 = require("@trpc/client");
@@ -53,8 +52,8 @@ const addon_settings_provider_js_1 = require("./addon-settings-provider.js");
 const device_meta_mirror_js_1 = require("./device-meta-mirror.js");
 const integration_visibility_js_1 = require("./integration-visibility.js");
 const package_dir_utils_1 = require("./package-dir-utils");
+const forked_custom_actions_js_1 = require("./forked-custom-actions.js");
 const prune_misplaced_addons_js_1 = require("./prune-misplaced-addons.js");
-const require_cache_js_1 = require("./require-cache.js");
 const runner_convergence_1 = require("./runner-convergence");
 const runner_spawn_fanout_js_1 = require("./runner-spawn-fanout.js");
 /**
@@ -269,10 +268,14 @@ class AddonRegistryService {
     // through this from the `api.addons.custom` tRPC procedure.
     customActionRegistry = new system_1.CustomActionRegistry();
     /**
-     * Keeps `purgeRequireCacheUnder` + `import()` atomic per addon directory now
-     * that the boot runner plan overlaps (D171). See `runner-spawn-fanout.ts`.
+     * Fingerprint of the custom-action catalogs each UDS child last DESCRIBED
+     * (keyed by child id), and the addon ids registered from that description.
+     * A re-register carrying the same catalogs is a no-op with no line; a child
+     * whose new description drops an addon has that addon's actions withdrawn.
+     * See {@link applyChildCustomActions}.
      */
-    moduleLoadSerializer = (0, runner_spawn_fanout_js_1.createKeyedSerializer)();
+    childCatalogFingerprints = new Map();
+    childCatalogAddons = new Map();
     /**
      * AddonIds whose group-runner disconnect is operator-initiated (update /
      * restart / uninstall). The Moleculer `$node.disconnected` handler skips
@@ -2375,6 +2378,11 @@ class AddonRegistryService {
     wireCapabilityConsumers() {
         if (!this.capabilityRegistry)
             return;
+        // A forked runner's custom-action catalogs arrive in its register frame,
+        // not as a capability event — a non-device runner's post-init register
+        // carries the same caps as its pre-init one, so no `provider-registered`
+        // event marks the moment the catalogs exist. See `applyChildCustomActions`.
+        this.moleculer.onChildCustomActions((child) => this.applyChildCustomActions(child));
         this.eventBusService.subscribe({ category: 'capability:provider-registered' }, (event) => {
             const rawCapability = event.data['capability'];
             const rawAddonId = event.data['addonId'];
@@ -3100,12 +3108,12 @@ class AddonRegistryService {
         catch (err) {
             throw new Error(`Failed to spawn runner "${runnerId}" (${addons.length} addons): ${(0, types_1.errMsg)(err)}`, { cause: err });
         }
-        // Register custom actions for each addon on the runner. Provider
-        // registration for cap methods is handled by
-        // `CapabilityBridge.onProviderConnected` once the runner's
-        // INFO heartbeat lands.
+        // Provider registration for cap methods is handled by
+        // `CapabilityBridge.onProviderConnected` once the runner's INFO heartbeat
+        // lands, and the custom-action catalogs arrive the same way — in the
+        // runner's post-init register frame, applied by `applyChildCustomActions`.
+        // Nothing about the runner is read from its bundle here (D444).
         for (const { addonId } of addons) {
-            await this.registerForkedAddonCustomActions(addonId, runnerId);
             // Mark the entry initialized so the in-process core-builtin boot
             // passes skip it (those passes only touch `@camstack/system`).
             const entry = this.addonEntries.get(addonId);
@@ -3207,146 +3215,78 @@ class AddonRegistryService {
             }
             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.
+        // 3. Bookkeeping for EVERY roster member. Mark each member initialized so
+        //    the in-process core-builtin boot passes skip them. The custom-action
+        //    catalogs are NOT touched here: the respawned runner describes them in
+        //    its post-init register frame and `applyChildCustomActions` replaces
+        //    whatever the previous incarnation registered (D444).
         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`.
+     * Apply the custom-action catalogs a UDS child DESCRIBED in its register
+     * frame (`RegisteredChild.customActions`, schemas stripped) to the hub-wide
+     * `CustomActionRegistry`, dispatching each action back to that child over
+     * the addon-call plane.
      *
-     * The catalog (zod `input`/`output` specs) is read STATICALLY from the
-     * addon module's `customActions` named export — the handler dispatches
-     * over UDS via `LocalChildRegistry.callAddonOnChild(addonId,
-     * {target:'custom', action, args})` (F3 — replaces the removed per-addon
-     * Moleculer `custom.<action>` action), so the only divergence vs an
-     * in-process addon is the transport, exactly like cap methods. The hub's
-     * `CustomActionRegistry` validates input/output around this dispatch.
+     * ## Why the child describes, and the hub never reads the bundle
      *
-     * Why a fresh import: `this.addonLoader`'s `module` namespace is
-     * captured once at boot. After a hot-update (`installFromTgz` →
-     * `restartAddon`) the on-disk bundle is newer than that cached module,
-     * so re-reading the boot-time `module` would register a STALE catalog
-     * (or none at all, if the addon was first installed after boot). We
-     * re-`import()` the entry with a cache-busting query so Node's ESM
-     * loader hands back the current bundle.
+     * Until D444 this was `registerForkedAddonCustomActions`: purge the require
+     * cache, re-import the addon's entry INSIDE hub-main, read its
+     * `customActions` export. Measured 2026-09-10 on the live hub: 9.3 MB of
+     * `addon-pipeline-orchestrator/dist/index.js` evaluated in hub-main by a
+     * sampling heap profile, ten deploys in the process's 23 h life, NONE of
+     * which exported a catalog — and the only line saying so was at `debug`,
+     * which the hub does not write. Every evaluation pins whatever module-scope
+     * state the evicted graph left behind, and the bundle-reload guard existed
+     * only to keep that re-execution survivable (D284). The runner is the
+     * process that owns the addon; it describes its catalog once its init loop
+     * has produced it, in the post-init register frame, and validates the
+     * action's input and output itself (`child-addon-call-dispatch.ts`).
      *
-     * Idempotent: drops any prior registration first. No-op (with a debug
-     * log) when the addon exports no `customActions` — most addons don't.
+     * ## What one description does
+     *
+     *  - identical to the child's last description → nothing, silently (a
+     *    native-cap change or reconnect re-sends the same frame);
+     *  - otherwise every addon in it is (re-)registered — an EMPTY catalog
+     *    withdraws that addon's actions — and an addon the previous description
+     *    named but this one does not is withdrawn too;
+     *  - and ONE `info` line per applied description names what it produced,
+     *    including "nothing": a load that produces nothing and says nothing is
+     *    the branch D391 forbids.
      */
-    async registerForkedAddonCustomActions(addonId, runnerId) {
-        // Always clear first so a restart that REMOVES custom actions (or an
-        // addon whose entry no longer exports them) doesn't leave stale
-        // entries resolvable.
-        this.customActionRegistry.unregisterAddon(addonId);
-        const entry = this.addonEntries.get(addonId);
-        const addonDir = entry?.addonDir;
-        const declarationEntry = entry?.declaration?.entry;
-        if (!addonDir || !declarationEntry)
-            return;
-        // Resolve the built entry the same way `AddonLoader.loadDeclaration`
-        // does: `./src/x.ts` → `dist/x.js`, with index.js fallbacks.
-        const entryFile = declarationEntry
-            .replace(/^\.\//, '')
-            .replace(/^src\//, 'dist/')
-            .replace(/\.ts$/, '.js');
-        let entryPath = path.resolve(addonDir, entryFile);
-        if (!fs.existsSync(entryPath)) {
-            const base = entryPath.replace(/\.(js|cjs|mjs)$/, '');
-            const alternatives = [
-                `${base}.cjs`,
-                `${base}.mjs`,
-                path.resolve(addonDir, 'dist', 'index.js'),
-                path.resolve(addonDir, 'dist', 'index.cjs'),
-                path.resolve(addonDir, 'dist', 'index.mjs'),
-                path.resolve(addonDir, declarationEntry),
-            ];
-            entryPath = alternatives.find((p) => fs.existsSync(p)) ?? entryPath;
-        }
-        if (!fs.existsSync(entryPath))
-            return;
-        let catalog;
-        try {
-            // ── The query string does NOT bust a CommonJS bundle ──────────────
-            //
-            // Every addon here builds to CJS, and Node's ESM loader serves a CJS
-            // module out of the REQUIRE cache, which is keyed by the resolved
-            // filename with the query stripped. So `?t=<now>` below busts nothing
-            // for them: this function re-registered the catalog captured at hub boot
-            // on every restart, forever.
-            //
-            // The consequence was invisible and total: an EXISTING action kept
-            // working, so nothing looked broken, while a NEWLY added one could never
-            // become reachable without restarting the whole hub process — which
-            // quietly falsifies the reason bridge actions exist ("no codegen, no
-            // republish, no train"). Found 2026-08-08, deploying `nc.injectTestEvent`:
-            // the deploy succeeded, the restart logged "custom actions registered",
-            // and the action 404'd.
-            //
-            // Dropping the addon's own modules from the require cache is what
-            // actually re-reads the bundle — see `require-cache.ts` for the scoping
-            // and the real-path match Node's cache keys demand.
-            //
-            // The purge mutates the PROCESS-GLOBAL require cache, so purge-then-import
-            // must stay atomic per BUNDLE now that the boot plan overlaps (D171):
-            // `@camstack/addon-remote-storage` ships four addon ids whose entries all
-            // resolve into one `dist/`, and a sibling's purge landing mid-import would
-            // evict a module graph while it is being evaluated. Different bundles
-            // still load concurrently.
-            //
-            // The scope is the BUNDLE (`<addonDir>/dist`), never `dirname(entryPath)`
-            // — see `bundleGraphRootFor`. The narrow scope evicted the entry chunk and
-            // kept the shared chunks, so the re-import re-ran the entry's module-scope
-            // declarations against singletons that had survived, and took the broker
-            // down on 2026-08-29 (D284). The serializer key MUST match the purge
-            // scope: two addon ids of one package now purge the same graph, so
-            // serializing them per entry-folder would let one evict the other's
-            // modules mid-evaluation — the exact race the key exists to prevent.
-            const graphRoot = (0, require_cache_js_1.bundleGraphRootFor)(addonDir, entryPath);
-            const modUnknown = await this.moduleLoadSerializer.run(graphRoot, async () => {
-                (0, require_cache_js_1.purgeRequireCacheUnder)(graphRoot);
-                // Kept for a genuinely ESM addon entry, where it IS the mechanism.
-                const cacheBustedUrl = `${(0, node_url_1.pathToFileURL)(entryPath).href}?t=${Date.now()}`;
-                // A plain `await import()` here is downleveled by tsc (the backend builds
-                // with `module: CommonJS`) into a `require()`-based shim. `require()` then
-                // treats the `?t=…` cache-bust query as part of the literal filename and
-                // throws MODULE_NOT_FOUND for EVERY forked addon — so no forked addon's
-                // custom-action catalog ever loaded. Use a native dynamic import the
-                // compiler won't rewrite, so Node's ESM loader handles the query string.
-                const nativeImport = new Function('specifier', 'return import(specifier)');
-                return nativeImport(cacheBustedUrl);
-            });
-            catalog =
-                modUnknown && typeof modUnknown === 'object'
-                    ? modUnknown['customActions']
-                    : undefined;
-        }
-        catch (err) {
-            this.logger.warn('Failed to load custom-action catalog for forked addon', {
-                tags: { addonId },
-                meta: { error: (0, types_1.errMsg)(err) },
-            });
+    applyChildCustomActions(child) {
+        const catalogs = child.customActions;
+        if (catalogs === undefined)
             return;
-        }
-        if (!catalog || typeof catalog !== 'object') {
-            this.logger.debug('Forked addon exports no custom actions', {
-                tags: { addonId },
-                meta: { runnerId },
-            });
+        const fingerprint = (0, forked_custom_actions_js_1.childCatalogsFingerprint)(catalogs);
+        if (this.childCatalogFingerprints.get(child.childId) === fingerprint)
             return;
+        this.childCatalogFingerprints.set(child.childId, fingerprint);
+        const described = new Set(Object.keys(catalogs));
+        for (const previous of this.childCatalogAddons.get(child.childId) ?? []) {
+            if (!described.has(previous))
+                this.customActionRegistry.unregisterAddon(previous);
+        }
+        this.childCatalogAddons.set(child.childId, described);
+        for (const [addonId, descriptor] of Object.entries(catalogs)) {
+            if (Object.keys(descriptor).length === 0) {
+                this.customActionRegistry.unregisterAddon(addonId);
+                continue;
+            }
+            this.customActionRegistry.registerAddon(addonId, (0, forked_custom_actions_js_1.toForkedCustomActionsSpec)(descriptor), (action, input, caller) => this.dispatchForkedCustomAction(addonId, action, input, caller));
         }
-        this.customActionRegistry.registerAddon(addonId, catalog, (action, input, caller) => this.dispatchForkedCustomAction(addonId, action, input, caller));
-        this.logger.info('Runner addon custom actions registered', {
-            tags: { addonId },
-            meta: { runnerId },
+        const summary = (0, forked_custom_actions_js_1.summarizeChildCatalogs)(catalogs);
+        this.logger.info('UDS child custom-action catalogs applied', {
+            meta: {
+                childId: child.childId,
+                incarnation: child.incarnation,
+                registered: summary.withActions.length > 0 ? summary.withActions.join(',') : '(none)',
+                withoutActions: summary.withoutActions.length > 0 ? summary.withoutActions.join(',') : '(none)',
+            },
         });
     }
     /**

package/dist/core/addon/forked-custom-actions.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toForkedCustomActionsSpec = toForkedCustomActionsSpec;
+exports.childCatalogsFingerprint = childCatalogsFingerprint;
+exports.summarizeChildCatalogs = summarizeChildCatalogs;
+const zod_1 = require("zod");
+/**
+ * Build the hub-side catalog for a forked addon.
+ *
+ * `input`/`output` are `z.unknown()` ON PURPOSE: the hub's
+ * `dispatchCustomAction` parses input and output around the dispatch, and for
+ * a forked addon both parses must be passthroughs — the runner owns the
+ * schemas and refuses what they refuse. `kind`, `auth`, `scope` and `caller`
+ * are the fields the hub actually gates on, and they arrive intact.
+ */
+function toForkedCustomActionsSpec(descriptor) {
+    const spec = {};
+    for (const [name, action] of Object.entries(descriptor)) {
+        spec[name] = {
+            input: zod_1.z.unknown(),
+            output: zod_1.z.unknown(),
+            kind: action.kind,
+            auth: action.auth,
+            scope: action.scope,
+            ...(action.caller === 'required' ? { caller: 'required' } : {}),
+        };
+    }
+    return spec;
+}
+/**
+ * A stable identity for a child's whole catalog set, so a re-register that
+ * carries the SAME catalogs (native-cap change, reconnect — 246 re-registers in
+ * 30 minutes with zero respawns, measured 2026-08-25) registers nothing and
+ * logs nothing. Key order is normalised at every level: two descriptions of
+ * one catalog must never fingerprint differently because a runner enumerated
+ * its map in another order.
+ */
+function childCatalogsFingerprint(catalogs) {
+    return JSON.stringify(sortKeysDeep(catalogs));
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        out[key] = sortKeysDeep(Reflect.get(value, key));
+    }
+    return out;
+}
+function summarizeChildCatalogs(catalogs) {
+    const withActions = [];
+    const withoutActions = [];
+    for (const addonId of Object.keys(catalogs).sort()) {
+        const count = Object.keys(catalogs[addonId] ?? {}).length;
+        if (count > 0)
+            withActions.push(`${addonId}:${count}`);
+        else
+            withoutActions.push(addonId);
+    }
+    return { withActions, withoutActions };
+}

package/dist/core/moleculer/moleculer.service.js

@@ -49,6 +49,15 @@ class MoleculerService {
      * See {@link ChildManifestGate}.
      */
     childManifestGate = new ChildManifestGate();
+    /**
+     * Receives every child register frame that DESCRIBES its custom-action
+     * catalogs (the post-init one and every re-register after it). Consulted
+     * BEFORE {@link ChildManifestGate}: the gate compares caps, and a post-init
+     * register of a non-device runner carries the same caps as its pre-init one
+     * — skipping it would lose the only frame that carries the catalogs (D444).
+     * The consumer (`AddonRegistryService`) dedupes by catalog fingerprint.
+     */
+    childCustomActionsHandler = null;
     /**
      * Fixed-period agent-readiness snapshot sweep (D8 reconcile) — repairs
      * agent-origin readiness deltas lost while the agent stayed connected.
@@ -126,6 +135,14 @@ class MoleculerService {
     get childRegistry() {
         return this.localChildRegistry;
     }
+    /**
+     * Register the (single) handler for a child's described custom-action
+     * catalogs. See {@link childCustomActionsHandler}. Called once by
+     * `AddonRegistryService` when it wires its consumers.
+     */
+    onChildCustomActions(handler) {
+        this.childCustomActionsHandler = handler;
+    }
     /** The CapRouteResolver once onModuleInit has completed; null before that. */
     get capRouteResolver() {
         return this.resolver;
@@ -437,6 +454,20 @@ class MoleculerService {
             registry.onChildRegistered((child) => {
                 const hubNodeId = this.brokerSafe.nodeID;
                 const childNodeId = `${hubNodeId}/${child.childId}`;
+                // The catalogs first, and unconditionally: the manifest gate below
+                // judges CAPS, and a frame whose caps are unchanged may still be the
+                // one frame that describes the catalogs. An absent field is a pre-init
+                // register and says nothing about actions — it is not forwarded.
+                if (child.customActions !== undefined) {
+                    try {
+                        this.childCustomActionsHandler?.(child);
+                    }
+                    catch (err) {
+                        logger.warn('UDS child custom-action catalogs could not be applied', {
+                            meta: { nodeId: childNodeId, incarnation: child.incarnation, error: (0, types_1.errMsg)(err) },
+                        });
+                    }
+                }
                 const params = buildChildUdsManifest(childNodeId, child.childId, child.caps);
                 // `updateCaps()` re-sends the whole register frame on the same socket,
                 // so this fires far more often than a runner starts: 246 rebuilds in 30

package/dist/core/update-availability-emitter.js

@@ -132,6 +132,11 @@ class UpdateAvailabilityEmitter {
             nodeId: scope,
         }));
         const head = list[0];
+        // `target: 'wrapper'` carries WHICH shell, and it has to survive the
+        // rebuild here or the notification loses the only thing that makes it
+        // actionable — a docker node would be told to press a button that cannot
+        // exist. Absent for every other target.
+        const wrapperKind = head.wrapperKind;
         this.eventBus.emit({
             id: `update.available:${target}:${scope}:${packages
                 .map((pkg) => `${pkg.packageName}@${pkg.latestVersion}`)
@@ -148,6 +153,7 @@ class UpdateAvailabilityEmitter {
                 packages,
                 nodeId: scope,
                 nodeIds: [scope],
+                ...(wrapperKind !== undefined ? { wrapperKind } : {}),
             },
         });
     }

package/dist/core/updates/update-check-scheduler.js

@@ -98,6 +98,9 @@ class UpdateCheckScheduler {
                     continue;
                 }
                 await this.attempt('node server package', node.id, () => this.targets.checkNodeServerUpdate(node.id, node.isHub));
+                // The shell, on EVERY node role — the hub is the one this failure was
+                // found on.
+                await this.attempt('node wrapper', node.id, () => this.targets.checkWrapperUpdate(node.id, node.isHub));
                 if (node.isHub)
                     continue;
                 await this.attempt('agent addon packages', node.id, () => this.targets.checkAgentAddons(node.id));

package/dist/core/updates/wrapper-update-checker.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WrapperUpdateChecker = exports.WRAPPER_PACKAGE_NAME = void 0;
+/**
+ * The availability row's package name. A shell is not an npm package, but the
+ * emitter keys dedup on `(target, node, packageName)` and a stable literal is
+ * what makes "one shell per node" the dedup slot. Never rendered: the
+ * notification body is chosen from the wrapper KIND.
+ */
+exports.WRAPPER_PACKAGE_NAME = 'camstack-wrapper';
+class WrapperUpdateChecker {
+    emitter;
+    logger;
+    readStatus;
+    constructor(options) {
+        this.emitter = options.emitter;
+        this.logger = options.logger;
+        this.readStatus = options.readStatus;
+    }
+    async check(nodeId, isHub) {
+        const status = await this.readStatus(nodeId, isHub);
+        const wrapper = status.wrapper;
+        const contract = status.imageContract;
+        if (wrapper === undefined || contract === undefined) {
+            // Version skew: this node's `@camstack/server` predates the wrapper
+            // field. Unanswerable, so it is an ERROR — reporting it as "no wrapper
+            // update" would be a claim nothing checked.
+            throw new Error(`node ${nodeId} reports no wrapper identity (server-management payload predates it)`);
+        }
+        if (contract.state === 'in-sync') {
+            // The one case where an empty snapshot is a fact rather than a guess.
+            this.emitter.publishSnapshot('wrapper', [], nodeId);
+            return;
+        }
+        const seedVersion = contract.seedVersion;
+        const contractVersion = contract.contractVersion;
+        const behind = contract.state === 'behind-patch' || contract.state === 'behind-series';
+        if (!behind || seedVersion === null || contractVersion === null) {
+            // `unknown` (no seed, or no registry answer yet) and `ahead` (a stale
+            // check) both mean "nothing was proved". Publishing an empty snapshot
+            // would clear a standing announcement on no evidence at all.
+            this.logger.warn('Wrapper check inconclusive — nothing published', {
+                tags: { nodeId },
+                meta: { state: contract.state, wrapperKind: wrapper.kind, seedVersion, contractVersion },
+            });
+            return;
+        }
+        const candidate = {
+            target: 'wrapper',
+            packageName: exports.WRAPPER_PACKAGE_NAME,
+            // The SHELL's versions, not the running code's. `wrapper.currentVersion`
+            // is what the shell says about ITSELF (an Electron app version), which
+            // is not on the same scale as a release; the seed is, and the seed is
+            // what `contractVersion` was compared against.
+            currentVersion: seedVersion,
+            latestVersion: contractVersion,
+            nodeId,
+            wrapperKind: wrapper.kind,
+        };
+        this.emitter.publishSnapshot('wrapper', [candidate], nodeId);
+    }
+}
+exports.WrapperUpdateChecker = WrapperUpdateChecker;

package/dist/main.js

@@ -79,6 +79,7 @@ const trpc_router_1 = require("./api/trpc/trpc.router");
 const trpc_error_principal_1 = require("./api/trpc/trpc-error-principal");
 const trpc_error_device_tags_1 = require("./api/trpc/trpc-error-device-tags");
 const ws_request_census_1 = require("./api/trpc/ws-request-census");
+const ws_slow_consumer_guard_js_1 = require("./api/trpc/ws-slow-consumer-guard.js");
 const addon_route_jwt_gate_js_1 = require("./auth/addon-route-jwt-gate.js");
 const addon_route_share_gate_js_1 = require("./auth/addon-route-share-gate.js");
 const session_cookie_js_1 = require("./auth/session-cookie.js");
@@ -302,6 +303,16 @@ async function bootstrap() {
         socketPlane: (0, system_1.createSocketPlaneReader)({
             registry: () => moleculerForEventPlane?.childRegistry ?? null,
         }),
+        // The ArrayBuffer census, armed by the probe itself. Twice on 2026-09-10
+        // this process's `arrayBuffers` climbed linearly for an hour (to 1.3 GB
+        // and to 5 GB, both LIVE across a forced compaction) and released in one
+        // instant, with no line at either boundary; the measurement that names
+        // the shape existed and was never run because it needed a human awake
+        // during the episode. Now the heartbeat takes it: one forced full GC —
+        // the pause a reclaim pass already costs — walked in memory, nothing
+        // written, on a threshold held for a minute, at most twice an hour.
+        // It is NOT a heap snapshot; see `array-buffer-census.ts`.
+        arrayBufferCensus: { census: (0, system_1.createInspectorArrayBufferCensus)() },
     });
     // Clean up orphaned processes from previous crashes before starting
     cleanupOrphanProcesses();
@@ -1223,18 +1234,39 @@ async function bootstrap() {
         // call. The frame is the only place an operation is observable from
         // outside the adapter — see `ws-request-census.ts`. Registered before
         // `applyWSSHandler` so no socket can be accepted without a session.
+        // A subscriber that stops READING is disconnected, not buffered until the
+        // hub dies. On 2026-09-10 the only WS client (the operator's phone, viewer
+        // in the background, JS suspended, TCP open) queued 88 MB of JSON strings
+        // in hub-main's old_space with no bound and no line. See
+        // `ws-slow-consumer-guard.ts` for the policy and the alternatives it beat.
+        const wsSlowConsumerGuard = new ws_slow_consumer_guard_js_1.WsSlowConsumerGuard({
+            logger: app.get(logging_service_1.LoggingService).createLogger('tRPC:ws'),
+        });
+        wsSlowConsumerGuard.start();
         wss.on('connection', (client, req) => {
             (0, ws_request_census_1.attachWsCensusSession)(httpRequestCensus, client, req, app.get(logging_service_1.LoggingService).createLogger('tRPC:ws'));
+            wsSlowConsumerGuard.attach(client, (0, ws_slow_consumer_guard_js_1.wsConnectionFacts)(req));
         });
         (0, ws_1.applyWSSHandler)({
             wss,
             router: appRouter,
+            // The complement of the bound above, for the SUSPENDED client: a PING is
+            // a text frame the client's JS must answer, and a backgrounded app's JS
+            // does not run — so the socket is terminated ~40 s into the background
+            // instead of accumulating for the night, and the app reconnects on
+            // return (every WS client of this hub is `@trpc/client` >= 11, which
+            // answers PING with PONG; the viewer pins ^11.16). The bound stays: it
+            // covers a client whose JS runs but whose link cannot drain the events.
+            // A termination here closes with 1006; the guard's close line names it.
+            keepAlive: { enabled: true, pingMs: 30_000, pongWaitMs: 10_000 },
             createContext: async (opts) => {
                 const wsCtx = await (0, trpc_context_1.createWsTrpcContext)(opts, authService, addonRegistry, shareTokenService, app.get(logging_service_1.LoggingService).createLogger('tRPC:ws'));
                 // The connection's identity, derived ONCE and reused for every
                 // operation on this socket. Frames that arrived while the bearer was
                 // still resolving are held by the session and released here.
-                (0, ws_request_census_1.identifyWsCensusSession)(opts.res, (0, trpc_error_principal_1.describeTrpcPrincipal)(wsCtx.user));
+                const principal = (0, trpc_error_principal_1.describeTrpcPrincipal)(wsCtx.user);
+                (0, ws_request_census_1.identifyWsCensusSession)(opts.res, principal);
+                wsSlowConsumerGuard.identify(opts.res, principal);
                 return wsCtx;
             },
             onError: ({ path: trpcPath, error, ctx, input, }) => {

package/dist/manual-boot.js

@@ -77,9 +77,11 @@ const server_update_service_1 = require("./core/server-update/server-update.serv
 const storage_service_1 = require("./core/storage/storage.service");
 const stream_probe_service_1 = require("./core/streaming/stream-probe.service");
 const topology_emitter_service_1 = require("./core/topology/topology-emitter.service");
+const update_availability_emitter_js_1 = require("./core/update-availability-emitter.js");
 const update_availability_store_js_1 = require("./core/update-availability-store.js");
 const agent_installed_packages_js_1 = require("./core/updates/agent-installed-packages.js");
 const update_check_scheduler_js_1 = require("./core/updates/update-check-scheduler.js");
+const wrapper_update_checker_js_1 = require("./core/updates/wrapper-update-checker.js");
 // ---------------------------------------------------------------------------
 // Service container — narrowing via `instanceof`, no casts.
 // ---------------------------------------------------------------------------
@@ -252,6 +254,25 @@ async function bootManual(opts) {
     // channel — that gate is why the only periodic publisher was dead on every
     // live hub (`{"channel":"off"}`). See UpdateCheckScheduler.
     const updateCheckLogger = loggingService.createLogger('UpdateCheck');
+    // The fifth target: the SHELL each node runs inside. Its own emitter scope,
+    // so a shell announcement and a code announcement never overwrite each
+    // other's dedup state — they are different facts about the same node (D437).
+    const wrapperUpdateChecker = new wrapper_update_checker_js_1.WrapperUpdateChecker({
+        logger: updateCheckLogger,
+        emitter: new update_availability_emitter_js_1.UpdateAvailabilityEmitter(eventBusService, { type: 'core', id: 'wrapper-update-check' }, new update_availability_store_js_1.FileUpdateAvailabilityStore(availabilityDataDir, 'wrapper-update', loggingService.createLogger('UpdateAvailability'))),
+        readStatus: async (nodeId, isHub) => {
+            if (isHub)
+                return serverUpdateService.getServerPackageStatus();
+            const proxy = moleculerService.createCapabilityProxy('server-management', nodeId);
+            if (proxy === null) {
+                // Unreachable is not "the image is fine". Reject so the scheduler
+                // records a failed check instead of a clean bill.
+                throw new Error(`server-management unreachable on ${nodeId}`);
+            }
+            const status = await proxy['getServerPackageStatus']?.({});
+            return types_1.ServerPackageStatusSchema.parse(status);
+        },
+    });
     const updateCheckScheduler = new update_check_scheduler_js_1.UpdateCheckScheduler({
         logger: updateCheckLogger,
         getIntervalSeconds: () => addonPackageService.getAutoUpdateSettings().updateCheckIntervalSeconds,
@@ -278,6 +299,7 @@ async function bootManual(opts) {
                 }
                 return proxy['checkServerUpdate']?.({});
             },
+            checkWrapperUpdate: (nodeId, isHub) => wrapperUpdateChecker.check(nodeId, isHub),
         },
     });
     addonPackageService.setUpdateCheckRescheduler(() => updateCheckScheduler.reschedule());

package/dist/server-root/index.js

@@ -77,6 +77,7 @@ var require_dist = __commonJS({
       DEV_UPLOADS_DIRNAME: /* @__PURE__ */ __name(() => DEV_UPLOADS_DIRNAME, "DEV_UPLOADS_DIRNAME"),
       DEV_UPLOADS_KEEP_COUNT: /* @__PURE__ */ __name(() => DEV_UPLOADS_KEEP_COUNT, "DEV_UPLOADS_KEEP_COUNT"),
       DEV_UPLOAD_MANIFEST_FILE: /* @__PURE__ */ __name(() => DEV_UPLOAD_MANIFEST_FILE, "DEV_UPLOAD_MANIFEST_FILE"),
+      ELECTRON_APP_VERSION_ENV: /* @__PURE__ */ __name(() => ELECTRON_APP_VERSION_ENV, "ELECTRON_APP_VERSION_ENV"),
       HOST_EXTERNAL_SPECIFIERS: /* @__PURE__ */ __name(() => HOST_EXTERNAL_SPECIFIERS, "HOST_EXTERNAL_SPECIFIERS"),
       HUB_ROOT_SPEC: /* @__PURE__ */ __name(() => HUB_ROOT_SPEC2, "HUB_ROOT_SPEC"),
       PENDING_ROOT_SWAP_FILE: /* @__PURE__ */ __name(() => PENDING_ROOT_SWAP_FILE, "PENDING_ROOT_SWAP_FILE"),
@@ -93,6 +94,7 @@ var require_dist = __commonJS({
       currentDir: /* @__PURE__ */ __name(() => currentDir, "currentDir"),
       currentEntryPath: /* @__PURE__ */ __name(() => currentEntryPath, "currentEntryPath"),
       detectWorkspaceRoot: /* @__PURE__ */ __name(() => detectWorkspaceRoot, "detectWorkspaceRoot"),
+      detectWrapperIdentity: /* @__PURE__ */ __name(() => detectWrapperIdentity, "detectWrapperIdentity"),
       devChannelEpoch: /* @__PURE__ */ __name(() => devChannelEpoch, "devChannelEpoch"),
       devUploadManifestPath: /* @__PURE__ */ __name(() => devUploadManifestPath, "devUploadManifestPath"),
       devUploadVersionDir: /* @__PURE__ */ __name(() => devUploadVersionDir, "devUploadVersionDir"),
@@ -110,6 +112,7 @@ var require_dist = __commonJS({
       readPendingRootSwap: /* @__PURE__ */ __name(() => readPendingRootSwap, "readPendingRootSwap"),
       readRestartIntentMarker: /* @__PURE__ */ __name(() => readRestartIntentMarker, "readRestartIntentMarker"),
       readServerRootState: /* @__PURE__ */ __name(() => readServerRootState, "readServerRootState"),
+      readWrapperProbes: /* @__PURE__ */ __name(() => readWrapperProbes, "readWrapperProbes"),
       registerActiveRootResolver: /* @__PURE__ */ __name(() => registerActiveRootResolver, "registerActiveRootResolver"),
       restartIntentMarkerPath: /* @__PURE__ */ __name(() => restartIntentMarkerPath, "restartIntentMarkerPath"),
       rootEntryPath: /* @__PURE__ */ __name(() => rootEntryPath2, "rootEntryPath"),
@@ -789,6 +792,93 @@ var require_dist = __commonJS({
       };
     }
     __name(assessImageContract, "assessImageContract");
+    var ELECTRON_APP_VERSION_ENV = "CAMSTACK_AGENT_APP_VERSION";
+    var CONTAINER_CGROUP_MARKERS = [
+      "docker",
+      "containerd",
+      "kubepods",
+      "podman"
+    ];
+    function cgroupNamesAContainer(contents) {
+      const lower = contents.toLowerCase();
+      return CONTAINER_CGROUP_MARKERS.some((marker) => lower.includes(marker));
+    }
+    __name(cgroupNamesAContainer, "cgroupNamesAContainer");
+    function cgroupDetail(contents) {
+      const lines = contents.split("\n").filter((line) => line.trim().length > 0);
+      const named = lines.find((line) => cgroupNamesAContainer(line));
+      return (named ?? lines[0] ?? "").trim().slice(0, 200);
+    }
+    __name(cgroupDetail, "cgroupDetail");
+    function detectWrapperIdentity(inputs) {
+      const { platform, dockerEnvFileExists, proc1Cgroup, electronAppVersion, seedVersion } = inputs;
+      const linux = platform === "linux";
+      const cgroupAnswered = proc1Cgroup !== null;
+      const cgroupSaysContainer = proc1Cgroup !== null && cgroupNamesAContainer(proc1Cgroup);
+      const containerObserved = dockerEnvFileExists || cgroupSaysContainer;
+      const electronDeclared = electronAppVersion !== void 0 && electronAppVersion.length > 0;
+      const containerRuledOut = !containerObserved && (cgroupAnswered || !linux);
+      const evidence = [
+        {
+          fact: "platform",
+          mode: "observed",
+          holds: linux,
+          detail: linux ? `process.platform=${platform} \u2014 a container is possible here` : `process.platform=${platform} \u2014 a linux container cannot run on this platform`
+        },
+        {
+          fact: "dockerenv-file",
+          mode: "observed",
+          holds: dockerEnvFileExists,
+          detail: dockerEnvFileExists ? "/.dockerenv exists" : "/.dockerenv not present"
+        },
+        {
+          fact: "proc-1-cgroup",
+          mode: "observed",
+          holds: cgroupSaysContainer,
+          detail: proc1Cgroup === null ? "/proc/1/cgroup unreadable \u2014 this probe did NOT answer" : cgroupDetail(proc1Cgroup)
+        },
+        {
+          fact: "electron-app-version-env",
+          mode: "declared",
+          holds: electronDeclared,
+          detail: electronDeclared ? `CAMSTACK_AGENT_APP_VERSION=${String(electronAppVersion)}` : "CAMSTACK_AGENT_APP_VERSION not set"
+        }
+      ];
+      if (containerObserved && electronDeclared) {
+        return {
+          kind: "contradictory",
+          evidence,
+          currentVersion: null
+        };
+      }
+      if (containerObserved) {
+        return {
+          kind: "docker",
+          evidence,
+          currentVersion: seedVersion
+        };
+      }
+      if (electronDeclared) {
+        return {
+          kind: "electron",
+          evidence,
+          currentVersion: electronAppVersion ?? null
+        };
+      }
+      if (containerRuledOut) {
+        return {
+          kind: "native",
+          evidence,
+          currentVersion: seedVersion
+        };
+      }
+      return {
+        kind: "unknown",
+        evidence,
+        currentVersion: null
+      };
+    }
+    __name(detectWrapperIdentity, "detectWrapperIdentity");
     var fs4 = __toESM2(require("fs"));
     var path4 = __toESM2(require("path"));
     function detectWorkspaceRoot(fromDir) {
@@ -930,6 +1020,26 @@ var require_dist = __commonJS({
     var NPM_INSTALL_TIMEOUT_MS = 15 * 6e4;
     var RESTART_REASON_PREFIX = "server-update";
     var STALE_TRANSIENT_MS = 24 * 60 * 60 * 1e3;
+    function readWrapperProbes() {
+      let proc1Cgroup = null;
+      try {
+        proc1Cgroup = fs6.readFileSync("/proc/1/cgroup", "utf-8");
+      } catch {
+        proc1Cgroup = null;
+      }
+      let dockerEnvFileExists = false;
+      try {
+        dockerEnvFileExists = fs6.existsSync("/.dockerenv");
+      } catch {
+        dockerEnvFileExists = false;
+      }
+      return {
+        platform: process.platform,
+        dockerEnvFileExists,
+        proc1Cgroup
+      };
+    }
+    __name(readWrapperProbes, "readWrapperProbes");
     function readPackageVersion(pkgJsonPath) {
       try {
         const raw = JSON.parse(fs6.readFileSync(pkgJsonPath, "utf-8"));
@@ -956,6 +1066,7 @@ var require_dist = __commonJS({
       execNpm;
       ensureNativePrebuildsFn;
       env;
+      readWrapperProbesFn;
       now;
       runningPackageJsonPath;
       workspaceProbeDir;
@@ -983,6 +1094,7 @@ var require_dist = __commonJS({
         });
         this.ensureNativePrebuildsFn = options.ensureNativePrebuilds ?? (async () => void 0);
         this.env = options.env ?? process.env;
+        this.readWrapperProbesFn = options.readWrapperProbes ?? readWrapperProbes;
         this.now = options.now ?? Date.now;
         this.runningPackageJsonPath = options.runningPackageJsonPath;
         this.workspaceProbeDir = options.workspaceProbeDir;
@@ -1008,6 +1120,20 @@ var require_dist = __commonJS({
         if (seedDir === void 0 || seedDir.length === 0) return null;
         return readPackageVersion(path6.join(seedDir, "package.json"));
       }
+      /**
+      * What this node runs INSIDE. Observed where it can be (the container
+      * probes), declared only where it cannot (the Electron app version, which a
+      * child process has no other way to learn). A contradiction between the two
+      * is reported as `contradictory`, never resolved — see `wrapper-identity.ts`
+      * and D437.
+      */
+      wrapperIdentity() {
+        return detectWrapperIdentity({
+          ...this.readWrapperProbesFn(),
+          electronAppVersion: this.env[ELECTRON_APP_VERSION_ENV],
+          seedVersion: this.seedVersion()
+        });
+      }
       rootDir() {
         return serverRootDir(this.dataDir);
       }
@@ -1046,7 +1172,11 @@ var require_dist = __commonJS({
             seedVersion: this.seedVersion(),
             latestVersion,
             runningVersion
-          })
+          }),
+          // The other half of the same question. `imageContract` says the shell is
+          // BEHIND; this says WHAT the shell is, which is the only thing that can
+          // turn that verdict into an instruction the operator can act on.
+          wrapper: this.wrapperIdentity()
         };
       }
       // ── Check ─────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.267",
+  "version": "1.2.269",
   "private": false,
   "files": [
     "dist",