@camstack/server 1.2.689 → 1.2.691

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.691] - 2026-10-29
+
+### Changed
+
+- An unpaired agent now shows its real memory on its own page instead of unknown.
+
+## [1.2.690] - 2026-10-29
+
+### Changed
+
+- The agent reports its memory, reclaims stranded pages and gets a heap ceiling sized to the host; a node's launch parameters (heap ceiling, allocator) come from the server and can be overridden per node from the hub
+
 ## [1.2.689] - 2026-10-29
 
 ### Added
@@ -17,6 +29,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Generated routers for the pet-fountain capability
 - Agents report their own process memory in the topology (the core process showed 0), and an unreadable memory shows as unknown
 
+### Changed
+
+- The agent now reports its own [mem] agent-main heartbeat and reclaims stranded memory, as the hub does
+- The hub tells its addon runners which telemetry categories anyone consumes, so unused ones stop crossing the process boundary
+- Node launch parameters (heap ceiling, allocator env) are decided by a closure module, with a per-node override and a source line in the boot log
+- A node's heap-ceiling override can be read and set through server-management (applies at the next restart)
+
 ## [1.2.688] - 2026-10-29
 
 ### Changed

package/dist/agent/agent-heap-watch.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startAgentHeapWatch = startAgentHeapWatch;
+/**
+ * The agent root's own memory, on the record and returned to the OS.
+ *
+ * hub-main has had the `[mem]` heartbeat and the stranded-page reclaimer since
+ * 2026-08; the agent root process (container AND desktop — both reach
+ * `startAgent` through the same launcher) had neither, so a measured 0.8–1.4 GB
+ * agent root emitted no line at all and never gave a page back. This is the same
+ * mechanism, not a second one: `startHeapWatch` with the V8 reclaimer, labelled
+ * `agent-main`.
+ */
+const system_1 = require("@camstack/system");
+const DEFAULT_DEPS = {
+    start: system_1.startHeapWatch,
+    createReclaimer: system_1.createV8Reclaimer,
+};
+/**
+ * Start the heartbeat + reclaim for the agent root. Returns the stop function.
+ * `createV8Reclaimer()` returns undefined when V8 declines; the heartbeat then
+ * runs report-only, exactly as hub-main does.
+ */
+function startAgentHeapWatch(logger, deps = DEFAULT_DEPS) {
+    const reclaimer = deps.createReclaimer();
+    const sink = {
+        info: (line) => {
+            logger.info(line);
+        },
+        warn: (line) => {
+            logger.warn(line);
+        },
+    };
+    return deps.start(system_1.AGENT_MAIN_HEAP_WATCH_LABEL, sink, undefined, reclaimer === undefined ? undefined : { reclaim: reclaimer }, undefined, undefined, 
+    // Say who chose the ceiling: the default ceiling below is applied by the
+    // launcher's argv, and an absent flag means the image/desktop predates it.
+    true);
+}

package/dist/agent/agent-status-metrics.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStatusMetrics = resolveStatusMetrics;
+/**
+ * The metrics source `$agent.status` reads (and so the agent's own local page).
+ *
+ * A PAIRED agent boots the `metrics-provider` addon, so the registry answers. An
+ * UNPAIRED agent boots no addon at all (agent-boot-mode.ts), the registry has no
+ * provider, and the page read memory as unknown although the host reader works. The
+ * fallback is the SAME native reader the addon registers - never a second formula -
+ * and it is asked only when the registry has nothing.
+ */
+function resolveStatusMetrics(fromRegistry, fallback) {
+    return () => fromRegistry() ?? fallback();
+}

package/dist/agent/main.js

@@ -59,6 +59,7 @@ const agent_node_certificates_js_1 = require("./agent-node-certificates.js");
 const agent_reconnect_js_1 = require("./agent-reconnect.js");
 const serial_queue_js_1 = require("./serial-queue.js");
 const agent_boot_mode_js_1 = require("./agent-boot-mode.js");
+const agent_status_metrics_js_1 = require("./agent-status-metrics.js");
 const agent_self_update_js_1 = require("./agent-self-update.js");
 const update_check_scheduler_js_1 = require("../core/updates/update-check-scheduler.js");
 const agent_infra_capabilities_js_1 = require("./agent-infra-capabilities.js");
@@ -76,6 +77,7 @@ const register_agent_cap_dispatch_js_1 = require("./register-agent-cap-dispatch.
 // entries flow through it (console output + hub forwarding).
 // ---------------------------------------------------------------------------
 const system_2 = require("@camstack/system");
+const agent_heap_watch_js_1 = require("./agent-heap-watch.js");
 /** A reconnect (stop + rebuild + start) that takes longer than this is abandoned. */
 const RECONNECT_DEADLINE_MS = 90_000;
 /** How often the agent re-evaluates whether to ask its hub "am I still a member?" (D857). */
@@ -97,6 +99,11 @@ const DATA_NODEID_CAPS = new Set(types_2.ALL_CAPABILITY_DEFINITIONS.filter((c) =
 // Main
 // ---------------------------------------------------------------------------
 async function startAgent(configPath) {
+    // The agent root's own memory: `[mem] agent-main` heartbeat + the stranded-page
+    // reclaim hub-main has had since 2026-08. Started first so a slow boot is on the
+    // record; lines reach the hub through the same LogManager the addons use.
+    const heapWatchLogger = agentLogManager.createLogger().withTags({ addonId: 'heap-watch' });
+    (0, agent_heap_watch_js_1.startAgentHeapWatch)(heapWatchLogger);
     const config = (0, agent_config_js_1.loadAgentConfig)(configPath);
     // Derive CAMSTACK_HUB_URL from the configured hub address so remote agents
     // no longer need a second, redundant env var set by hand (the cross-node
@@ -431,6 +438,7 @@ async function startAgent(configPath) {
         withTags: () => consoleLogger,
     };
     const capabilityRegistry = new system_1.CapabilityRegistry(consoleLogger);
+    let unpairedMetrics = null;
     // Declare all capabilities the agent uses — required before registerProvider()
     const agentCapabilities = [
         types_2.storageCapability,
@@ -480,7 +488,7 @@ async function startAgent(configPath) {
         dataDir: config.dataDir,
         runnerBootCheck: () => agentRunnerBootCheck?.current(),
     });
-    capabilityRegistry.registerProvider('server-management', agent_update_service_js_1.AGENT_RUNTIME_ADDON_ID, (0, server_management_provider_js_1.buildServerManagementProvider)(agentUpdateService));
+    capabilityRegistry.registerProvider('server-management', agent_update_service_js_1.AGENT_RUNTIME_ADDON_ID, (0, server_management_provider_js_1.buildServerManagementProvider)(agentUpdateService, config.dataDir));
     // The agent's certificates (D856): mesh leaf swap with automatic rollback, and the
     // hub-issued HTTPS leaf hot-swapped into the sniffing listener. The listener is
     // created later in boot, so it is read through a getter.
@@ -547,7 +555,17 @@ async function startAgent(configPath) {
         // Resolve the current metrics-provider cap lazily from the registry.
         // The cap is registered during bootCoreAddons but may not exist in test
         // scenarios — `null` is a documented fallback for both.
-        getMetricsProvider: () => capabilityRegistry.getSingleton('metrics-provider'),
+        // An UNPAIRED agent boots no addon, so the registry has no provider: its own page
+        // reads the same native reader the addon would register (see agent-status-metrics.ts).
+        getMetricsProvider: (0, agent_status_metrics_js_1.resolveStatusMetrics)(() => capabilityRegistry.getSingleton('metrics-provider'), () => {
+            if ((0, agent_boot_mode_js_1.decideAgentBootMode)({ paired: (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath) }) === 'full')
+                return null;
+            if (unpairedMetrics === null) {
+                unpairedMetrics = new system_1.NativeMetricsProvider();
+                unpairedMetrics.startSampling(5000);
+            }
+            return unpairedMetrics;
+        }),
         agentVersion: readAgentVersion(),
         // Drives `$agent.reload` — re-runs the same discovery pass the bootstrap
         // does at startup, picking up tarballs just landed via `$agent.deploy`.

package/dist/api/core/server-management.provider.js

@@ -1,7 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLaunchOverrideMethods = buildLaunchOverrideMethods;
 exports.buildServerManagementProvider = buildServerManagementProvider;
-function buildServerManagementProvider(service) {
+const launch_args_js_1 = require("../../launch-args.js");
+/** The per-node launch override methods (ADR 0970), backed by the node's data dir. */
+function buildLaunchOverrideMethods(dataDir) {
+    return {
+        getLaunchOverrides: () => Promise.resolve({ heapMb: (0, launch_args_js_1.readHeapOverrideMb)(dataDir) }),
+        setLaunchOverrides: (input) => {
+            (0, launch_args_js_1.writeHeapOverrideMb)(dataDir, input.heapMb);
+            return Promise.resolve({ heapMb: input.heapMb, restartRequired: true });
+        },
+    };
+}
+function buildServerManagementProvider(service, dataDir) {
     if (service === null)
         return null;
     return {
@@ -10,5 +22,6 @@ function buildServerManagementProvider(service) {
         applyServerUpdate: (input) => service.applyServerUpdate(input),
         rollbackServerUpdate: () => service.rollbackServerUpdate(),
         restartServer: () => Promise.resolve(service.restartNode()),
+        ...buildLaunchOverrideMethods(dataDir),
     };
 }

package/dist/api/trpc/generated-cap-routers.js

@@ -11047,6 +11047,22 @@ function createCapRouter_serverManagement(getProvider, createRemoteProxy) {
             const p = resolveProvider('server-management', input?.nodeId, () => getProvider(ctx), createRemoteProxy);
             return p.restartServer();
         }),
+        getLaunchOverrides: trpc_middleware_js_1.adminProcedure
+            .input(zod_1.z.object({ nodeId: zod_1.z.string().optional() }).optional())
+            .output(types_126.serverManagementCapability.methods.getLaunchOverrides.output)
+            .query(async ({ input, ctx }) => {
+            const p = resolveProvider('server-management', input?.nodeId, () => getProvider(ctx), createRemoteProxy);
+            return p.getLaunchOverrides();
+        }),
+        setLaunchOverrides: trpc_middleware_js_1.adminProcedure
+            .input(types_126.serverManagementCapability.methods.setLaunchOverrides.input.loose())
+            .output(types_126.serverManagementCapability.methods.setLaunchOverrides.output)
+            .mutation(async ({ input, ctx }) => {
+            const { nodeId, ...methodInput } = input;
+            const p = resolveProvider('server-management', nodeId, () => getProvider(ctx), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.setLaunchOverrides(methodInput);
+        }),
     });
 }
 function createCapRouter_settingsStore(getProvider, createRemoteProxy) {

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

@@ -254,7 +254,7 @@ function buildServerProviders(services) {
         integrations: wrap(() => (0, cap_providers_js_1.buildIntegrationsProvider)(services.addonRegistry, services.eventBus, services.loggingService, services.capabilityRegistry)),
         nodes: wrap(() => (0, cap_providers_js_1.buildNodesProvider)(services.agentRegistry, services.moleculer, services.addonRegistry, (0, cap_providers_js_1.createNodeRootPackageLookup)(services.moleculer, services.serverUpdateService), services.loggingService.createLogger('nodes'))),
         // server-management — runtime-updatable root package (phase 1: hub only).
-        'server-management': wrap(() => (0, server_management_provider_js_1.buildServerManagementProvider)(services.serverUpdateService)),
+        'server-management': wrap(() => (0, server_management_provider_js_1.buildServerManagementProvider)(services.serverUpdateService, path.resolve(process.env['CAMSTACK_DATA'] ?? 'camstack-data'))),
         addons: wrap((ctx) => (0, cap_providers_js_1.buildAddonsProvider)(services.addonRegistry, services.addonPackageService, services.loggingService, services.moleculer, services.configService, ctx, services.agentRegistry)),
         // webrtc-session — the resolved broker singleton, wrapped per request to
         // inject the server-read User-Agent into signaling attribution (the broker

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

@@ -759,6 +759,14 @@ class MoleculerService {
             // agents (non-retaining nodes).
             const hubChildRegistry = this.localChildRegistry;
             (0, system_1.setNodeEventInterest)(this.broker, () => hubChildRegistry.aggregateEventInterest());
+            // Producer-side suppression (D8): tell each forked child which categories
+            // someone else wants — siblings plus the hub's own in-process subscribers
+            // (the admin live stream is one) — so a high-frequency category nobody
+            // wants never leaves its process. Hub only: an agent cannot see the hub's
+            // subscribers, so its children keep sending everything. A remote node's
+            // interest in a ring-denied category is NOT visible here (ADR 0969).
+            hubChildRegistry.setEventInterestSource(() => (0, system_1.getLocalEventInterest)(this.broker));
+            (0, system_1.onLocalEventInterestChange)(this.broker, () => hubChildRegistry.refreshEventInterest());
         }
     }
     /**

package/dist/launch-args.js

@@ -0,0 +1,255 @@
+"use strict";
+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.ALLOCATOR_ENV_DEFAULTS = exports.OVERRIDE_MAX_MB = exports.OVERRIDE_MIN_MB = exports.AGENT_HEAP_CAP_MB = exports.AGENT_HEAP_FLOOR_MB = exports.HEAP_CEILING_SOURCE_ENV = exports.LAUNCH_OVERRIDES_FILE = void 0;
+exports.computedAgentHeapMb = computedAgentHeapMb;
+exports.planLaunch = planLaunch;
+exports.renderLaunchPlan = renderLaunchPlan;
+exports.overridesPath = overridesPath;
+exports.readHeapOverrideMb = readHeapOverrideMb;
+exports.writeHeapOverrideMb = writeHeapOverrideMb;
+exports.readCgroupLimitBytes = readCgroupLimitBytes;
+exports.runLaunchCli = runLaunchCli;
+/**
+ * NODE LAUNCH ARGUMENTS — decided by the server closure, executed by the image.
+ *
+ * `node <closure>/dist/launch-args.js --role hub|agent [--allocator-env]` prints
+ * what the launcher should add to the node's command line, so the Docker
+ * entrypoint, the Electron shell and the Windows service supervisor carry NO copy
+ * of the formula: changing it (or a node's override) needs a closure update and a
+ * restart, never a new image or app.
+ *
+ * Zero dependencies (node built-ins only): it runs BEFORE the closure's own
+ * `node_modules` resolution, from either the active closure or the baked seed.
+ *
+ * ## Output (stdout, one record per line, `\n` separated)
+ *
+ *     arg --max-old-space-size=2048      an extra node argv entry (flags only)
+ *     env NAME=value                     an environment variable to export
+ *     source override|legacy-env|computed|v8-default
+ *     warn <free text>                   something the launcher should log
+ *
+ * Nothing else is printed. A launcher treats any line it does not recognise as
+ * absent, and a non-zero exit, a timeout or empty output as "no extra args".
+ *
+ * ## The heap ceiling
+ *
+ *  - `override` — `<dataDir>/launch-overrides.json` `{ "heapMb": N }`, set from
+ *    the hub (`serverManagement.setLaunchOverrides`) and persisted on the node.
+ *  - `legacy-env` — `CAMSTACK_HUB_HEAP_MB` (hub) / `CAMSTACK_AGENT_HEAP_MB`
+ *    (agent), still honoured when no override is set.
+ *  - `computed` — AGENT only: clamp(min(RAM, cgroup limit) / 4, 1536, 4096) MB.
+ *    V8's own quarter-of-RAM rule with a floor above every measured agent RSS
+ *    (0.8-1.4 GB), so it bounds a runaway and never a healthy root.
+ *  - `v8-default` — HUB only, nothing set: no flag. A hardcoded 1536 killed the
+ *    hub four times in 15 h (see the history in the Dockerfile); V8's default
+ *    here was 4288 MB and is still bounded.
+ *
+ * Set on argv, never NODE_OPTIONS: forked addon runners are sized separately.
+ */
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+exports.LAUNCH_OVERRIDES_FILE = 'launch-overrides.json';
+/** Env var carrying {@link CeilingSource} to the node so its heartbeat can say who chose. */
+exports.HEAP_CEILING_SOURCE_ENV = 'CAMSTACK_HEAP_CEILING_SOURCE';
+exports.AGENT_HEAP_FLOOR_MB = 1536;
+exports.AGENT_HEAP_CAP_MB = 4096;
+/** An override outside this range is ignored with a warning, never applied. */
+exports.OVERRIDE_MIN_MB = 512;
+exports.OVERRIDE_MAX_MB = 65536;
+/**
+ * The native allocator pair, welded: glibc reads MALLOC_ARENA_MAX once at malloc
+ * init, so it must exist before `exec node`; sharp restores libvips concurrency
+ * from 1 to `availableParallelism()` the moment it appears, so the pair travels
+ * together or not at all. Defaults only: an operator value already in the
+ * environment wins (the launcher applies them with `: "${NAME:=value}"` semantics).
+ */
+exports.ALLOCATOR_ENV_DEFAULTS = {
+    MALLOC_ARENA_MAX: '2',
+    VIPS_CONCURRENCY: '1',
+};
+const BYTES_PER_MB = 1024 * 1024;
+/** cgroup v1 reports "unlimited" as a value near 2^63. */
+const CGROUP_UNLIMITED_BYTES = 2 ** 60;
+function validMb(value) {
+    return Number.isInteger(value) && value >= exports.OVERRIDE_MIN_MB && value <= exports.OVERRIDE_MAX_MB;
+}
+/** The agent's computed ceiling for `host`, in MB. */
+function computedAgentHeapMb(host) {
+    const limits = [host.totalMemBytes, host.cgroupLimitBytes ?? Number.POSITIVE_INFINITY].filter((n) => Number.isFinite(n) && n > 0);
+    if (limits.length === 0)
+        return exports.AGENT_HEAP_FLOOR_MB;
+    const quarterMb = Math.floor(Math.min(...limits) / BYTES_PER_MB / 4);
+    return Math.min(exports.AGENT_HEAP_CAP_MB, Math.max(exports.AGENT_HEAP_FLOOR_MB, quarterMb));
+}
+function planLaunch(input) {
+    const warnings = [];
+    let source = input.role === 'agent' ? 'computed' : 'v8-default';
+    let heapMb = input.role === 'agent' ? computedAgentHeapMb(input.host) : null;
+    const legacy = input.legacyEnv;
+    if (legacy !== undefined && legacy !== '') {
+        const mb = /^[1-9][0-9]*$/.test(legacy) ? Number(legacy) : Number.NaN;
+        if (validMb(mb)) {
+            source = 'legacy-env';
+            heapMb = mb;
+        }
+        else {
+            warnings.push(`ignoring the legacy heap env "${legacy}": not an integer in ${exports.OVERRIDE_MIN_MB}-${exports.OVERRIDE_MAX_MB} MB`);
+        }
+    }
+    if (input.overrideMb !== null) {
+        if (validMb(input.overrideMb)) {
+            source = 'override';
+            heapMb = input.overrideMb;
+        }
+        else {
+            warnings.push(`ignoring the heap override ${input.overrideMb}: not an integer in ${exports.OVERRIDE_MIN_MB}-${exports.OVERRIDE_MAX_MB} MB`);
+        }
+    }
+    return {
+        args: heapMb === null ? [] : [`--max-old-space-size=${heapMb}`],
+        env: {
+            [exports.HEAP_CEILING_SOURCE_ENV]: source,
+            ...(input.allocatorEnv ? exports.ALLOCATOR_ENV_DEFAULTS : {}),
+        },
+        source,
+        warnings,
+    };
+}
+function renderLaunchPlan(plan) {
+    const lines = [
+        ...plan.args.map((a) => `arg ${a}`),
+        ...Object.entries(plan.env).map(([k, v]) => `env ${k}=${v}`),
+        `source ${plan.source}`,
+        ...plan.warnings.map((w) => `warn ${w.replace(/[\r\n]+/g, ' ')}`),
+    ];
+    return `${lines.join('\n')}\n`;
+}
+const realFs = {
+    readFile(file) {
+        try {
+            return fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    },
+};
+function overridesPath(dataDir) {
+    return path.join(dataDir, exports.LAUNCH_OVERRIDES_FILE);
+}
+/** The persisted heap override in MB; `null` when absent, unreadable or not a number. */
+function readHeapOverrideMb(dataDir, io = realFs) {
+    const raw = io.readFile(overridesPath(dataDir));
+    if (raw === null)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || !('heapMb' in parsed))
+            return null;
+        const value = parsed.heapMb;
+        return typeof value === 'number' ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist (or, with `null`, clear) the heap override. Validated against the same
+ * range the launcher enforces, so a value the next launch would ignore is refused
+ * here instead of silently doing nothing. Written atomically (temp + rename).
+ */
+function writeHeapOverrideMb(dataDir, heapMb) {
+    const file = overridesPath(dataDir);
+    if (heapMb === null) {
+        fs.rmSync(file, { force: true });
+        return;
+    }
+    if (!validMb(heapMb)) {
+        throw new Error(`heap override must be an integer in ${exports.OVERRIDE_MIN_MB}-${exports.OVERRIDE_MAX_MB} MB, got ${heapMb}`);
+    }
+    fs.mkdirSync(dataDir, { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify({ heapMb })}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+function readCgroupLimitBytes(io = realFs, files) {
+    for (const file of files ?? [
+        '/sys/fs/cgroup/memory.max',
+        '/sys/fs/cgroup/memory/memory.limit_in_bytes',
+    ]) {
+        const raw = io.readFile(file)?.trim();
+        if (raw === undefined || !/^[0-9]+$/.test(raw))
+            continue;
+        const bytes = Number(raw);
+        if (bytes > 0 && bytes < CGROUP_UNLIMITED_BYTES)
+            return bytes;
+    }
+    return null;
+}
+function parseRole(argv) {
+    const i = argv.indexOf('--role');
+    const value = i >= 0 ? argv[i + 1] : undefined;
+    return value === 'hub' || value === 'agent' ? value : null;
+}
+/** Run the CLI; returns the stdout text and the exit code. Never throws. */
+function runLaunchCli(argv, deps) {
+    const role = parseRole(argv);
+    if (role === null)
+        return { stdout: '', code: 2 };
+    const dataDir = path.resolve(deps.env['CAMSTACK_DATA'] ?? 'camstack-data');
+    const legacyName = role === 'hub' ? 'CAMSTACK_HUB_HEAP_MB' : 'CAMSTACK_AGENT_HEAP_MB';
+    const plan = planLaunch({
+        role,
+        host: {
+            totalMemBytes: deps.totalMemBytes,
+            cgroupLimitBytes: readCgroupLimitBytes(deps.io, deps.cgroupFiles),
+        },
+        overrideMb: readHeapOverrideMb(dataDir, deps.io),
+        legacyEnv: deps.env[legacyName],
+        allocatorEnv: argv.includes('--allocator-env'),
+    });
+    return { stdout: renderLaunchPlan(plan), code: 0 };
+}
+if (require.main === module) {
+    const result = runLaunchCli(process.argv.slice(2), {
+        env: process.env,
+        io: realFs,
+        totalMemBytes: os.totalmem(),
+    });
+    process.stdout.write(result.stdout);
+    process.exitCode = result.code;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.689",
+  "version": "1.2.691",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,7 +24,8 @@
     "./package.json": "./package.json",
     "./main.js": "./dist/main.js",
     "./launcher.js": "./dist/launcher.js",
-    "./starter.js": "./dist/starter.js"
+    "./starter.js": "./dist/starter.js",
+    "./launch-args.js": "./dist/launch-args.js"
   },
   "scripts": {
     "build": "../../scripts/tsc7 -p tsconfig.build.json && tsup && node scripts/copy-closure-patches.mjs",
@@ -49,10 +50,10 @@
     ]
   },
   "dependencies": {
-    "@camstack/addon-admin-ui": "1.2.517",
-    "@camstack/addon-agent-ui": "1.2.292",
+    "@camstack/addon-admin-ui": "1.2.518",
+    "@camstack/addon-agent-ui": "1.2.293",
     "@camstack/addon-auth": "1.2.170",
-    "@camstack/addon-benchmark": "1.2.291",
+    "@camstack/addon-benchmark": "1.2.292",
     "@camstack/addon-decoder-nodeav": "1.2.144",
     "@camstack/addon-notifiers": "1.2.623",
     "@camstack/addon-pipeline": "1.2.634",
@@ -60,9 +61,9 @@
     "@camstack/addon-post-analysis": "1.2.651",
     "@camstack/develop": "0.1.39",
     "@camstack/sdk": "1.2.154",
-    "@camstack/system": "1.2.518",
-    "@camstack/types": "1.2.444",
-    "@camstack/ui-library": "1.2.350",
+    "@camstack/system": "1.2.519",
+    "@camstack/types": "1.2.445",
+    "@camstack/ui-library": "1.2.351",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.2.0",