@alfe.ai/gateway 0.9.19 → 0.10.1

package/dist/bin/gateway.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { a as installService, d as uninstallService, h as SOCKET_PATH, i as checkExistingDaemon, l as stopExistingDaemon, n as queryDaemonHealth, r as startDaemon, t as formatHealthReport } from "../health.js";
-import { p as LOG_FILE } from "../sentry.js";
+import { m as LOG_FILE } from "../sentry.js";
 import { spawn } from "node:child_process";
 //#region bin/gateway.ts
 /**

package/dist/health.js

@@ -1,5 +1,5 @@
-import { a as ErrorLineDetector, c as createLogger, f as __commonJSMin, i as CaptureThrottle, o as STRICT_ERROR_CAPTURE_PROFILE, p as __require, r as RuntimeProcess, s as toFingerprintKey, t as DRAIN_GRACE_MS } from "./runtime-process.js";
-import { a as captureFatal, d as initAgentSentry, f as setAgentContext, m as logger, o as captureIntegrationFailure, s as captureMcpFailure, u as flushSentry } from "./sentry.js";
+import { a as ErrorLineDetector, c as createLogger, i as CaptureThrottle, m as __require, o as STRICT_ERROR_CAPTURE_PROFILE, p as __commonJSMin, r as RuntimeProcess, s as toFingerprintKey, t as DRAIN_GRACE_MS } from "./runtime-process.js";
+import { a as captureFatal, d as flushSentry, f as initAgentSentry, h as logger, o as captureIntegrationFailure, p as setAgentContext, s as captureMcpFailure } from "./sentry.js";
 import { chmod, mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
@@ -5662,16 +5662,20 @@ const MAX_IPC_MESSAGE_BYTES = 1024 * 1024;
 * Map a cloud command name to an IPC method name.
 * Cloud commands use dot-notation matching IPC methods.
 *
-* Currently empty — Phase 1 has no daemon-to-plugin commands.
-* Commands will be added here as the protocol evolves.
+* Work reads are dispatched by executeWorkCommand so they select a capable
+* OpenClaw plugin and fail immediately instead of joining an offline queue.
 */
-const CLOUD_COMMAND_TO_IPC = {};
+const CLOUD_COMMAND_TO_IPC = {
+	"work.snapshot": "work.snapshot",
+	"work.job_runs": "work.job_runs",
+	"work.actions": "work.actions"
+};
 /**
 * Translate a cloud COMMAND into a local IPC request.
 * Returns null if the command isn't recognized.
 */
 function cloudCommandToIPCRequest(command) {
-	const method = CLOUD_COMMAND_TO_IPC[command.command];
+	const method = Object.hasOwn(CLOUD_COMMAND_TO_IPC, command.command) ? CLOUD_COMMAND_TO_IPC[command.command] : void 0;
 	if (!method) return null;
 	return {
 		type: "req",
@@ -6997,6 +7001,42 @@ var CommandQueue = class {
 	}
 };
 //#endregion
+//#region src/work-commands.ts
+const WORK_COMMANDS = [
+	"work.snapshot",
+	"work.job_runs",
+	"work.actions"
+];
+function isWorkCommand(command) {
+	return WORK_COMMANDS.includes(command);
+}
+const MAX_WORK_RESPONSE_BYTES = 768 * 1024;
+/** Read requests never enter an offline queue or choose an arbitrary connected plugin. */
+async function executeWorkCommand(command, agentId, runtime, ipc) {
+	const error = (code, message) => ({
+		type: "COMMAND_ACK",
+		commandId: command.commandId,
+		status: "error",
+		result: {
+			code,
+			message
+		}
+	});
+	if (!isWorkCommand(command.command)) return error("UNKNOWN_COMMAND", "Unsupported work command");
+	if (command.agentId !== agentId) return error("AGENT_MISMATCH", "Work request targets a different agent");
+	if (runtime !== "openclaw") return error("UNSUPPORTED_RUNTIME", "Work visibility is available for OpenClaw agents");
+	if (!command.payload || typeof command.payload !== "object" || Array.isArray(command.payload)) return error("INVALID_PARAMS", "Work parameters must be an object");
+	const plugin = ipc?.getRegisteredPlugins().find(([, info]) => info.name === "@alfe.ai/openclaw" && info.capabilities.includes("work.read"));
+	if (!ipc || !plugin) return error("WORK_UNAVAILABLE", "The runtime work bridge is unavailable; update the agent if needed");
+	try {
+		const response = await ipc.sendRequest(plugin[0], command.command, command.payload, 6e3);
+		if (Buffer.byteLength(JSON.stringify(response), "utf8") > MAX_WORK_RESPONSE_BYTES) return error("RESPONSE_TOO_LARGE", "Runtime work data exceeds the response limit");
+		return ipcResponseToCloudAck(command.commandId, response);
+	} catch {
+		return error("WORK_UNAVAILABLE", "The runtime work bridge did not respond");
+	}
+}
+//#endregion
 //#region src/process-manager.ts
 /**
 * Process management — launchd/systemd service installation.
@@ -7649,9 +7689,7 @@ var IPCServer = class {
 				reject,
 				timer
 			});
-			try {
-				conn.socket.write(JSON.stringify(request) + "\n");
-			} catch (err) {
+			if (!this.writeFrame(conn, request, "request")) {
 				clearTimeout(timer);
 				conn.pending.delete(id);
 				resolve({
@@ -7659,7 +7697,7 @@ var IPCServer = class {
 					ok: false,
 					error: {
 						code: "SEND_FAILED",
-						message: `Failed to send to plugin: ${err instanceof Error ? err.message : String(err)}`
+						message: "Failed to send to plugin (write failed or frame over the transport limit)"
 					}
 				});
 			}
@@ -7879,21 +7917,57 @@ var IPCServer = class {
 		}));
 	}
 	sendResponse(conn, response) {
+		if (!this.writeFrame(conn, response, "response")) logger.error({
+			connId: conn.id,
+			requestId: response.id
+		}, "IPC: failed to send response");
+	}
+	sendEvent(conn, event, payload) {
+		return this.writeFrame(conn, createIPCEvent(event, payload), "event");
+	}
+	/**
+	* Every outbound frame goes through here. The plugin destroys its socket on
+	* a frame over MAX_IPC_MESSAGE_BYTES (the mirror of our inbound cap), so a
+	* frame we know it will reject must never be written: responses degrade to a
+	* typed per-request error the plugin surfaces to the model, while requests
+	* and events are logged and dropped (a dropped request times out at the
+	* peer instead of killing the connection). MCP tool results are additionally
+	* bounded semantically in mcp-handlers.ts so this is the backstop, not the
+	* normal path.
+	*/
+	writeFrame(conn, message, kind) {
+		let frame;
 		try {
-			conn.socket.write(JSON.stringify(response) + "\n");
+			frame = JSON.stringify(message) + "\n";
 		} catch (err) {
 			logger.error({
 				connId: conn.id,
+				kind,
 				err
-			}, "IPC: failed to send response");
+			}, "IPC: failed to serialize outbound frame");
+			if (kind !== "response") return false;
+			frame = JSON.stringify(createIPCError(message.id, "INTERNAL", "Response could not be serialized")) + "\n";
+		}
+		const bytes = Buffer.byteLength(frame, "utf8");
+		if (bytes > 1048576) {
+			logger.warn({
+				connId: conn.id,
+				kind,
+				bytes,
+				maxBytes: MAX_IPC_MESSAGE_BYTES
+			}, "IPC: outbound frame exceeded size limit");
+			if (kind !== "response") return false;
+			frame = JSON.stringify(createIPCError(message.id, "RESPONSE_TOO_LARGE", `Response exceeded the ${String(MAX_IPC_MESSAGE_BYTES)} byte transport limit and was dropped. Narrow the request (filters, smaller page size) and retry.`)) + "\n";
 		}
-	}
-	sendEvent(conn, event, payload) {
 		try {
-			const msg = createIPCEvent(event, payload);
-			conn.socket.write(JSON.stringify(msg) + "\n");
+			conn.socket.write(frame);
 			return true;
-		} catch {
+		} catch (err) {
+			logger.error({
+				connId: conn.id,
+				kind,
+				err
+			}, "IPC: failed to write frame");
 			return false;
 		}
 	}
@@ -8122,6 +8196,250 @@ async function startIpcServer(socketPath, requestHandler, daemonVersion) {
 //#endregion
 //#region src/mcp-handlers.ts
 /**
+* Aggregate text budget for one MCP tool call. An order of magnitude under
+* MAX_IPC_MESSAGE_BYTES because JSON escaping inflates text: quotes and
+* newlines cost 2 bytes, control characters 6. The serialized fence below
+* makes the guarantee absolute; this is the budget the model sees.
+*/
+const MAX_MCP_RESULT_TEXT_BYTES = 256 * 1024;
+/**
+* Per-text-item cap. The consuming plugin (`@alfe.ai/openclaw-mcp-bundler`,
+* `plugin.ts` `MAX_JSON_STRING_LENGTH = 65_536`) rejects the WHOLE result as
+* "malformed" if any single string exceeds 65,536 UTF-16 code units, so a
+* kept item must never exceed that. UTF-8 bytes ≥ UTF-16 units, so capping
+* bytes at 64 KiB is safe for every already-deployed bundler.
+*/
+const MAX_MCP_RESULT_ITEM_TEXT_BYTES = 64 * 1024;
+/** Worst-case JSON wrapper per content item (`{"type":"text","text":""},`) for the fast-path estimate. */
+const ITEM_ENVELOPE_BYTES = 64;
+function isTextItem(item) {
+	return typeof item === "object" && item !== null && item.type === "text" && typeof item.text === "string";
+}
+function serializedBytes(value) {
+	return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+/**
+* Longest string value anywhere inside `value`, in UTF-8 bytes. The bundler
+* plugin's parser rejects the WHOLE result when any string at any depth is
+* over its cap (counted in UTF-16 units; UTF-8 bytes are never fewer), so
+* this is what a non-text item (image data, resource text) is measured by.
+*/
+/**
+* The bundler plugin's `sanitizeJsonRecord` limits, mirrored so the daemon
+* never hands it an item it will reject (which nulls the WHOLE result).
+* Keep in sync with `packages/openclaw-mcp-bundler/src/plugin.ts`.
+*/
+const PLUGIN_MAX_JSON_NODES = 1e4;
+const PLUGIN_MAX_JSON_DEPTH = 32;
+const PLUGIN_MAX_JSON_COLLECTION_ENTRIES = 2048;
+const PLUGIN_MAX_KEY_LENGTH = 512;
+/**
+* True when a content item stays inside the plugin parser's structural limits
+* (node budget per item, nesting depth, entries per collection, key length).
+* String length is bounded separately because `text` can be cut to fit; a
+* structural violation cannot, so the item is dropped.
+*/
+function withinPluginStructure(item) {
+	const budget = { nodes: 0 };
+	const walk = (value, depth) => {
+		budget.nodes += 1;
+		if (budget.nodes > PLUGIN_MAX_JSON_NODES || depth > PLUGIN_MAX_JSON_DEPTH) return false;
+		if (Array.isArray(value)) {
+			if (value.length > PLUGIN_MAX_JSON_COLLECTION_ENTRIES) return false;
+			for (const entry of value) if (!walk(entry, depth + 1)) return false;
+			return true;
+		}
+		if (typeof value === "object" && value !== null) {
+			const entries = Object.entries(value);
+			if (entries.length > PLUGIN_MAX_JSON_COLLECTION_ENTRIES) return false;
+			return entries.every(([key, entry]) => key.length <= PLUGIN_MAX_KEY_LENGTH && walk(entry, depth + 1));
+		}
+		return true;
+	};
+	return walk(item, 0);
+}
+function longestStringBytes(value) {
+	if (typeof value === "string") return Buffer.byteLength(value, "utf8");
+	if (Array.isArray(value)) {
+		let max = 0;
+		for (const entry of value) max = Math.max(max, longestStringBytes(entry));
+		return max;
+	}
+	if (typeof value === "object" && value !== null) {
+		let max = 0;
+		for (const entry of Object.values(value)) max = Math.max(max, longestStringBytes(entry));
+		return max;
+	}
+	return 0;
+}
+/** Cut at a UTF-8 boundary; drop a replacement char introduced by the cut. */
+function truncateUtf8(text, maxBytes) {
+	const buf = Buffer.from(text, "utf8");
+	if (buf.byteLength <= maxBytes) return text;
+	const out = buf.subarray(0, maxBytes).toString("utf8");
+	return out.endsWith("�") && !text.endsWith("�") ? out.slice(0, -1) : out;
+}
+/**
+* Model-visible notice. Deliberately names no bare tool: MCP hosts prefix tool
+* names, so a bare name is a dead end (packages/DEVELOPING.md, "Model-visible
+* errors carry the fix").
+*/
+function truncationNotice(args) {
+	const dropped = [];
+	if (args.droppedItems > 0) dropped.push(`${String(args.droppedItems)} further content item(s)`);
+	if (args.droppedStructured) dropped.push("the structured-content block");
+	return [
+		"[alfe] This tool result was truncated to fit the agent transport limit.",
+		`Source result was ${String(args.sourceBytes)} bytes; returned ${String(args.keptBytes)} bytes of text` + (args.truncatedItems > 0 ? ` (${String(args.truncatedItems)} item(s) cut short).` : ".") + (dropped.length > 0 ? ` Dropped ${dropped.join(" and ")}.` : ""),
+		"Do NOT retry this call unchanged; the same request will truncate again.",
+		"Narrow it instead: add a date range or status filter, lower the page size",
+		"(top / $top / limit), and page with skip / $skip. If this data source offers a",
+		"summary or report form of the same question, prefer that over listing raw records."
+	].join("\n");
+}
+/**
+* Bound a bundler tool result so the daemon never writes an IPC frame the
+* plugin will reject. In-budget results are returned by reference (no clone).
+* Over budget: items are kept front-to-back until the budget (text bytes plus
+* a per-item envelope allowance) is spent. Text items are cut at the per-item
+* cap on a UTF-8 boundary; a non-text item carrying any string over that cap
+* (image data, resource text) is dropped outright because the plugin would
+* reject the whole result on its account and it cannot be cut meaningfully.
+* `structuredContent` is dropped, `isError` is preserved verbatim, and a
+* model-visible notice is appended. If the serialized result is still over
+* the fence, only the notice is returned.
+*/
+function boundMcpToolResult(result) {
+	if (!Array.isArray(result.content)) throw new Error("MCP tool result content must be an array");
+	const content = result.content;
+	let textBytes = 0;
+	let maxItemBytes = 0;
+	let onlyBareText = true;
+	let structurallyValid = true;
+	for (const item of content) {
+		if (isTextItem(item)) {
+			textBytes += Buffer.byteLength(item.text, "utf8");
+			if (onlyBareText && Object.keys(item).some((key) => key !== "type" && key !== "text")) onlyBareText = false;
+		} else onlyBareText = false;
+		maxItemBytes = Math.max(maxItemBytes, longestStringBytes(item));
+		if (structurallyValid && !withinPluginStructure(item)) structurallyValid = false;
+	}
+	const structured = result.structuredContent;
+	const hasExtraKeys = Object.keys(result).some((key) => key !== "content" && key !== "isError" && key !== "structuredContent");
+	if (structurallyValid && textBytes <= 262144 && maxItemBytes <= 65536) {
+		const worstCase = textBytes * 6 + content.length * ITEM_ENVELOPE_BYTES + 256;
+		if (onlyBareText && structured === void 0 && !hasExtraKeys && worstCase <= 524288) return result;
+		if (serializedBytes(result) <= 524288) return result;
+	}
+	const sourceBytes = serializedBytes(result);
+	const { structuredContent: _dropped, ...withExtras } = result;
+	const rest = hasExtraKeys && serializedBytes(withExtras) - serializedBytes(content) > 524288 / 2 ? {
+		content,
+		...result.isError === void 0 ? {} : { isError: result.isError }
+	} : withExtras;
+	for (const textBudget of [
+		MAX_MCP_RESULT_TEXT_BYTES,
+		MAX_MCP_RESULT_TEXT_BYTES / 2,
+		MAX_MCP_RESULT_TEXT_BYTES / 4,
+		MAX_MCP_RESULT_TEXT_BYTES / 8
+	]) {
+		const candidate = boundWithBudget(content, rest, textBudget, sourceBytes, structured !== void 0);
+		if (serializedBytes(candidate) <= 524288) return candidate;
+	}
+	logger.warn({ sourceBytes }, "MCP tool result still over the serialized fence after text truncation; returning notice only");
+	const notice = truncationNotice({
+		sourceBytes,
+		keptBytes: 0,
+		truncatedItems: 0,
+		droppedItems: content.length,
+		droppedStructured: structured !== void 0
+	});
+	return {
+		...rest,
+		content: [{
+			type: "text",
+			text: notice
+		}]
+	};
+}
+function boundWithBudget(content, rest, textBudget, sourceBytes, droppedStructured) {
+	let remaining = textBudget;
+	let kept = 0;
+	let truncatedItems = 0;
+	let droppedItems = 0;
+	let exhausted = false;
+	const bounded = [];
+	for (const item of content) {
+		if (exhausted) {
+			droppedItems += 1;
+			continue;
+		}
+		if (!withinPluginStructure(item)) {
+			droppedItems += 1;
+			continue;
+		}
+		if (!isTextItem(item)) {
+			if (longestStringBytes(item) > 65536) {
+				droppedItems += 1;
+				continue;
+			}
+			const size = serializedBytes(item) + ITEM_ENVELOPE_BYTES;
+			if (size > remaining) {
+				droppedItems += 1;
+				exhausted = true;
+				continue;
+			}
+			remaining -= size;
+			bounded.push(item);
+			continue;
+		}
+		if (longestStringBytes({
+			...item,
+			text: ""
+		}) > 65536) {
+			droppedItems += 1;
+			continue;
+		}
+		const size = Buffer.byteLength(item.text, "utf8");
+		const allow = Math.min(remaining - ITEM_ENVELOPE_BYTES, MAX_MCP_RESULT_ITEM_TEXT_BYTES);
+		if (allow <= 0) {
+			droppedItems += 1;
+			exhausted = true;
+			continue;
+		}
+		if (size <= allow) {
+			remaining -= size + ITEM_ENVELOPE_BYTES;
+			kept += size;
+			bounded.push(item);
+			continue;
+		}
+		const cut = truncateUtf8(item.text, allow);
+		const cutBytes = Buffer.byteLength(cut, "utf8");
+		kept += cutBytes;
+		remaining -= cutBytes + ITEM_ENVELOPE_BYTES;
+		truncatedItems += 1;
+		bounded.push({
+			...item,
+			text: cut
+		});
+		if (remaining <= 0) exhausted = true;
+	}
+	const notice = {
+		type: "text",
+		text: truncationNotice({
+			sourceBytes,
+			keptBytes: kept,
+			truncatedItems,
+			droppedItems,
+			droppedStructured
+		})
+	};
+	return {
+		...rest,
+		content: [...bounded, notice]
+	};
+}
+/**
 * Return the daemon-hosted MCP bundler's current namespaced tool catalog.
 * Called by the openclaw-mcp-bundler plugin on every tool-factory invocation;
 * cheap (in-memory snapshot, no I/O).
@@ -8389,7 +8707,7 @@ async function handleMcpCallTool(bundler, params) {
 	try {
 		return {
 			ok: true,
-			payload: await bundler.callTool(name, args)
+			payload: boundMcpToolResult(await bundler.callTool(name, args))
 		};
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
@@ -9211,6 +9529,10 @@ let cloudConnected = false;
 * so a duplicate is ACKed with the prior result without re-executing.
 */
 const commandDedupe = new CommandDedupe();
+const workCommandDedupe = new CommandDedupe({
+	maxEntries: 4,
+	ttlMs: 5e3
+});
 let shuttingDown = false;
 let commandRegistry;
 let resolvedCliVersion;
@@ -9553,7 +9875,7 @@ async function startDaemon() {
 * bounce the box a second time.
 */
 async function handleCloudCommand(command) {
-	const { ack, duplicate } = await commandDedupe.run(command.commandId, () => executeCloudCommand(command));
+	const { ack, duplicate } = await (isWorkCommand(command.command) ? workCommandDedupe : commandDedupe).run(command.commandId, () => executeCloudCommand(command));
 	if (duplicate) {
 		logger.info({
 			commandId: command.commandId,
@@ -9606,6 +9928,7 @@ async function drainRuntimeBeforeExit(reason) {
 	}, "Runtime still mid-turn at drain grace deadline — proceeding with daemon exit");
 }
 async function executeCloudCommand(command) {
+	if (isWorkCommand(command.command)) return executeWorkCommand(command, config.agentId, config.runtime, ipcServer);
 	if (command.command === "daemon.update") {
 		const version = command.payload?.version ?? "latest";
 		setTimeout(() => {
@@ -9650,7 +9973,7 @@ async function executeCloudCommand(command) {
 		};
 		const payload = command.payload;
 		const runtime = config.runtime;
-		const version = payload?.version ?? (runtime === "openclaw" ? "2026.8.1" : runtime === "claude-code" ? "0.1.6" : void 0);
+		const version = payload?.version ?? (runtime === "openclaw" ? "2026.9.5" : runtime === "claude-code" ? "0.1.6" : void 0);
 		upgradingRuntime = true;
 		setTimeout(() => {
 			(async () => {
@@ -9658,6 +9981,7 @@ async function executeCloudCommand(command) {
 					const { upgradeRuntime } = await import("./runtime-upgrade.js");
 					const result = await upgradeRuntime(runtime, version, runtimeProcess, {
 						...runtime === "openclaw" && openclawCliLockRef ? { cliLock: openclawCliLockRef } : {},
+						...runtime === "openclaw" && isManagedMode() && process.env.ALFE_PRIVATE_DATA_PLANE !== "true" ? { nodeRemediation: {} } : {},
 						...runtime === "openclaw" && runtimeGateRef ? { gate: runtimeGateRef } : {}
 					});
 					if (result.success || result.runtimeChanged) {
@@ -9669,7 +9993,8 @@ async function executeCloudCommand(command) {
 						else {
 							logger.info({
 								runtime,
-								runtimeVersion: resolvedRuntimeVersion
+								runtimeVersion: resolvedRuntimeVersion,
+								nodeUpgraded: result.nodeUpgraded ?? false
 							}, "Runtime version updated after upgrade");
 							cloudClient.updateRuntimeVersionAndReRegister(resolvedRuntimeVersion);
 						}
@@ -9677,6 +10002,7 @@ async function executeCloudCommand(command) {
 					if (!result.success) logger.error({
 						runtime,
 						version,
+						nodeUpgraded: result.nodeUpgraded ?? false,
 						error: result.error
 					}, "Runtime upgrade did not complete cleanly");
 				} catch (err) {

package/dist/node-remediation.js

@@ -0,0 +1,163 @@
+import { f as supportsOpenClawNode, u as OPENCLAW_NODE_REQUIREMENT } from "./runtime-process.js";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+//#region src/node-remediation.ts
+/**
+* Managed-host Node.js remediation.
+*
+* OpenClaw 2026.9.x dropped Node 22 (and 25) from its engine range and its
+* preinstall refuses to install on them, while every managed Hetzner VM was
+* provisioned on Node 22. Rather than rebuild the fleet, the daemon's
+* `runtime.update` preflight and `alfe setup --managed` install the NodeSource
+* channel for `OPENCLAW_MANAGED_NODE_MAJOR` in place, re-verify, and continue.
+*
+* Self-hosted hosts never reach this module: the operator owns their Node and
+* gets the explicit engine error instead.
+*/
+/**
+* NodeSource setup + apt on a 2-vCPU box can take a few minutes, and
+* `unattended-upgrades` may hold the dpkg lock for a while first.
+*/
+const NODE_REMEDIATION_TIMEOUT_MS = 6e5;
+/**
+* After a failed attempt, refuse to re-run `curl | bash` + apt for this long.
+* `runtime.update` has no server-side dedupe or backoff (the dashboard and the
+* fleet bulk path can re-issue it immediately and indefinitely), so a host
+* whose remediation keeps failing must degrade to a cheap, loud no-op rather
+* than a NodeSource fetch storm.
+*/
+const NODE_REMEDIATION_FAILURE_COOLDOWN_MS = 30 * 6e4;
+const NODESOURCE_SETUP_URL = `https://deb.nodesource.com/setup_${String(24)}.x`;
+const FAILURE_MARKER_FILE = "node-remediation-failure.json";
+/**
+* Thrown when remediation fails. `nodeReplaced` is the load-bearing field: a
+* failure AFTER apt has swapped the host Node (verification or the installed
+* runtime's boot check failed) leaves the host on a new, unproven Node, which
+* is the state that needs an operator — very different from "never touched".
+*/
+var NodeRemediationError = class extends Error {
+	nodeReplaced;
+	resolvedNode;
+	cooldownActive;
+	constructor(message, details) {
+		super(message, details.cause === void 0 ? void 0 : { cause: details.cause });
+		this.name = "NodeRemediationError";
+		this.nodeReplaced = details.nodeReplaced;
+		this.resolvedNode = details.resolvedNode;
+		this.cooldownActive = details.cooldownActive ?? false;
+	}
+};
+async function readFailureMarker(path) {
+	try {
+		const parsed = JSON.parse(await readFile(path, "utf8"));
+		if (typeof parsed === "object" && parsed !== null && typeof parsed.failedAt === "number") return parsed;
+	} catch {}
+	return null;
+}
+async function writeFailureMarker(path, marker) {
+	try {
+		await mkdir(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(path, JSON.stringify(marker), { mode: 384 });
+	} catch {}
+}
+/**
+* Install the managed Node.js channel on a Debian/Ubuntu managed host and
+* return the resolved `node --version`.
+*
+* Runs BEFORE any runtime gate suspend or backup: the live OpenClaw child keeps
+* its already-open binary, and later `openclaw`/`npm` spawns resolve the new
+* binary through PATH. Fails closed (with `nodeReplaced` set accurately) if the
+* resulting Node still misses the range or if the currently installed OpenClaw
+* no longer boots under it — in that case the caller must not proceed to a
+* backup it could not produce.
+*/
+async function remediateManagedNode(runCommand, baseEnv, options = {}) {
+	const now = options.now ?? Date.now;
+	const stateDirectory = options.stateDirectory === void 0 ? join(homedir(), ".alfe") : options.stateDirectory;
+	const markerPath = stateDirectory ? join(stateDirectory, FAILURE_MARKER_FILE) : null;
+	if (markerPath) {
+		const marker = await readFailureMarker(markerPath);
+		if (marker && now() - marker.failedAt < 18e5) {
+			const remaining = Math.ceil((NODE_REMEDIATION_FAILURE_COOLDOWN_MS - (now() - marker.failedAt)) / 6e4);
+			throw new NodeRemediationError(`Node.js remediation failed ${String(Math.round((now() - marker.failedAt) / 6e4))} min ago (${marker.error}); not retrying for another ${String(remaining)} min. Fix the host (network egress to deb.nodesource.com, apt state) or remove ${markerPath} to retry now.`, {
+				nodeReplaced: false,
+				cooldownActive: true
+			});
+		}
+	}
+	const env = {
+		...baseEnv,
+		DEBIAN_FRONTEND: "noninteractive"
+	};
+	const longRunning = {
+		timeout: NODE_REMEDIATION_TIMEOUT_MS,
+		env
+	};
+	const quick = {
+		timeout: 1e4,
+		env
+	};
+	const { stdout: before } = await runCommand("node", ["--version"], quick).catch(() => ({ stdout: "" }));
+	const fromNode = before.trim();
+	const fail = async (message, details) => {
+		if (markerPath) await writeFailureMarker(markerPath, {
+			failedAt: now(),
+			fromNode,
+			error: message
+		});
+		throw new NodeRemediationError(message, details);
+	};
+	try {
+		await runCommand("bash", ["-c", `set -o pipefail; curl -fsSL --retry 3 --retry-connrefused --max-time 180 ${NODESOURCE_SETUP_URL} | bash -`], longRunning);
+		await runCommand("apt-get", [
+			"-o",
+			`DPkg::Lock::Timeout=${String(300)}`,
+			"install",
+			"-y",
+			"-qq",
+			"nodejs"
+		], longRunning);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		const observed = await runCommand("node", ["--version"], quick).then((r) => r.stdout.trim()).catch(() => void 0);
+		const nodeReplaced = observed !== void 0 && observed !== fromNode;
+		return fail(`Node.js channel install failed: ${message}`, {
+			nodeReplaced,
+			...nodeReplaced ? { resolvedNode: observed } : {},
+			cause: err
+		});
+	}
+	let nodeVersion;
+	try {
+		const { stdout } = await runCommand("node", ["--version"], quick);
+		nodeVersion = stdout.trim();
+	} catch (err) {
+		return fail(`Node.js was replaced but \`node --version\` failed afterwards: ${err instanceof Error ? err.message : String(err)}`, {
+			nodeReplaced: true,
+			cause: err
+		});
+	}
+	const nodeReplaced = nodeVersion !== fromNode;
+	if (!supportsOpenClawNode(nodeVersion)) return fail(`Node.js remediation resolved ${nodeVersion}, which does not satisfy ${OPENCLAW_NODE_REQUIREMENT}`, {
+		nodeReplaced,
+		resolvedNode: nodeVersion
+	});
+	if (options.verifyInstalledRuntime ?? true) try {
+		await runCommand("openclaw", ["--version"], quick);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return fail(`Host Node.js was replaced with ${nodeVersion} but the installed OpenClaw no longer boots under it: ${message}`, {
+			nodeReplaced,
+			resolvedNode: nodeVersion,
+			cause: err
+		});
+	}
+	if (markerPath) await unlink(markerPath).catch(() => void 0);
+	return nodeVersion;
+}
+//#endregion
+export { remediateManagedNode as n, NodeRemediationError as t };

package/dist/runtime-process.js

@@ -1,4 +1,4 @@
-import { c as captureRuntimeCrash, l as captureRuntimeErrorOutput } from "./sentry.js";
+import { l as captureRuntimeCrash, u as captureRuntimeErrorOutput } from "./sentry.js";
 import { createRequire } from "node:module";
 import pino from "pino";
 import crypto from "crypto";
@@ -50,32 +50,45 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 * truth for every install path:
 *   - `@alfe.ai/cli` `installRuntime` (fresh `alfe setup`)
 *   - the daemon `runtime.update` default (this package)
-*   - managed provisioning (`services/compute/src/lib/provisioner.ts` installs a
-*     compatible Node.js 22 before the CLI consumes this pin)
+*   - managed provisioning (`services/compute/src/lib/provisioner.ts` installs the
+*     Node.js 24 channel before the CLI consumes this pin)
 *
 * Pinning (rather than floating `npm install -g openclaw` → `latest`) is deliberate:
 * OpenClaw runs on every managed agent, so a `latest` that changes runtime semantics —
 * e.g. 2026.6.8 made a non-empty `plugins.allow` an exclusive allowlist — becomes a
 * silent fleet outage with no Alfe deploy. Bump deliberately after validating a new
 * OpenClaw, then cut a CLI release so the pin travels with the CLI version.
+*
+* Raising the engine range below obligates every consumer of it: the daemon upgrade
+* preflight (`runtime-upgrade.ts`), the CLI `installRuntime`, and the compute
+* cloud-init literals (tied to these constants by `provisioner.test.ts`).
+*/
+const PINNED_OPENCLAW_VERSION = "2026.9.5";
+/**
+* OpenClaw 2026.9.5's published Node.js engine floor. Node 22 and Node 25 are no
+* longer supported upstream (2026.9.x dropped both branches; the preinstall script
+* refuses to install on them).
 */
-const PINNED_OPENCLAW_VERSION = "2026.8.1";
-/** OpenClaw 2026.8.1's published Node.js engine floor. */
-const OPENCLAW_NODE_REQUIREMENT = ">=22.22.3 <23 || >=24.15.0 <25 || >=25.9.0";
+const OPENCLAW_NODE_REQUIREMENT = ">=24.16.0 <25 || >=26.1.0";
 /**
-* Whether a concrete Node.js version satisfies OpenClaw 2.x's engine range.
-* Accepts `process.versions.node` (`22.22.3`) or CLI output (`v22.22.3`).
+* The Node.js major the managed image installs (NodeSource `setup_24.x`) and that
+* `upgradeRuntime` remediates existing managed hosts onto. 24 is the current LTS
+* line; 26 is not LTS yet.
+*/
+const OPENCLAW_MANAGED_NODE_MAJOR = 24;
+/**
+* Whether a concrete Node.js version satisfies OpenClaw's engine range.
+* Accepts `process.versions.node` (`24.21.0`) or CLI output (`v24.21.0`).
+* Pre-release tags are rejected; build metadata (`+…`) is accepted.
 */
 function supportsOpenClawNode(nodeVersion) {
 	const match = /^v?(\d+)\.(\d+)\.(\d+)(?:\+[0-9A-Za-z.-]+)?$/u.exec(nodeVersion.trim());
 	if (!match) return false;
 	const major = Number(match[1]);
 	const minor = Number(match[2]);
-	const patch = Number(match[3]);
-	if (major === 22) return minor > 22 || minor === 22 && patch >= 3;
-	if (major === 24) return minor >= 15;
-	if (major === 25) return minor > 9 || minor === 9 && patch >= 0;
-	return major > 25;
+	if (major === 24) return minor >= 16;
+	if (major === 26) return minor >= 1;
+	return major > 26;
 }
 //#endregion
 //#region ../../node_modules/.pnpm/dotenv@17.2.2/node_modules/dotenv/package.json
@@ -15389,11 +15402,25 @@ const DETECTOR_FLUSH_DEBOUNCE_MS = 1500;
 const BACKOFF_INITIAL_MS = 1e3;
 const BACKOFF_MAX_MS = 3e4;
 const STABLE_UPTIME_MS = 6e4;
-/** Alfe owns supervision and version rollout; OpenClaw must not self-manage. */
+/**
+* Alfe owns supervision and version rollout; OpenClaw must not self-manage.
+*
+* `OPENCLAW_NODE_UPDATE_RESPAWNED=1` also disables 2026.9.x's node-runtime
+* recovery, which would otherwise re-exec the CLI under whatever other Node it
+* finds on PATH when the current one fails engine admission. Alfe chooses the
+* Node binary (managed remediation in `node-remediation.ts`); an admission
+* failure must surface as a clean exit the daemon can report, not a silent
+* respawn under an unmanaged interpreter.
+*
+* `OPENCLAW_CONFIG_READONLY` must never be set on the child or on upgrade
+* commands: since 2026.9.x it makes openclaw.json immutable and blocks setup,
+* doctor repairs and plugin installs.
+*/
 const OPENCLAW_EXTERNAL_SUPERVISOR_ENV = {
 	OPENCLAW_SUPERVISOR_MODE: "external",
 	OPENCLAW_SERVICE_REPAIR_POLICY: "external",
-	OPENCLAW_NO_AUTO_UPDATE: "1"
+	OPENCLAW_NO_AUTO_UPDATE: "1",
+	OPENCLAW_NODE_UPDATE_RESPAWNED: "1"
 };
 /**
 * Max time a NON-crash restart waits for an in-flight chat turn to finish
@@ -15739,4 +15766,4 @@ var RuntimeProcess = class {
 	}
 };
 //#endregion
-export { ErrorLineDetector as a, createLogger as c, supportsOpenClawNode as d, __commonJSMin as f, CaptureThrottle as i, OPENCLAW_NODE_REQUIREMENT as l, OPENCLAW_EXTERNAL_SUPERVISOR_ENV as n, STRICT_ERROR_CAPTURE_PROFILE as o, __require as p, RuntimeProcess as r, toFingerprintKey as s, DRAIN_GRACE_MS as t, PINNED_OPENCLAW_VERSION as u };
+export { ErrorLineDetector as a, createLogger as c, PINNED_OPENCLAW_VERSION as d, supportsOpenClawNode as f, CaptureThrottle as i, OPENCLAW_MANAGED_NODE_MAJOR as l, __require as m, OPENCLAW_EXTERNAL_SUPERVISOR_ENV as n, STRICT_ERROR_CAPTURE_PROFILE as o, __commonJSMin as p, RuntimeProcess as r, toFingerprintKey as s, DRAIN_GRACE_MS as t, OPENCLAW_NODE_REQUIREMENT as u };

package/dist/runtime-upgrade.js

@@ -1,5 +1,6 @@
-import { d as supportsOpenClawNode, l as OPENCLAW_NODE_REQUIREMENT, n as OPENCLAW_EXTERNAL_SUPERVISOR_ENV } from "./runtime-process.js";
-import { m as logger } from "./sentry.js";
+import { f as supportsOpenClawNode, n as OPENCLAW_EXTERNAL_SUPERVISOR_ENV, u as OPENCLAW_NODE_REQUIREMENT } from "./runtime-process.js";
+import { c as captureNodeRemediation, h as logger } from "./sentry.js";
+import { n as remediateManagedNode, t as NodeRemediationError } from "./node-remediation.js";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -25,7 +26,21 @@ import { promisify } from "node:util";
 */
 const execFileAsync = promisify(execFile);
 const OPENCLAW_UPGRADE_TIMEOUT_MS = 3e5;
-const OPENCLAW_DOCTOR_TIMEOUT_MS = 3e5;
+const OPENCLAW_DOCTOR_TIMEOUT_MS = 9e5;
+/**
+* A non-diagnostic probe run right after the new package lands. 2026.9.x
+* classifies `--version`/`--help` as diagnostic and lets them succeed even when
+* Node/SQLite runtime admission fails; `config` does not get that pass, so an
+* admission failure surfaces here — while `doctorStarted` is still false and
+* the pre-doctor package rollback is still safe. `config file` (prints the
+* resolved config path) is used rather than `config get <key>` because `get`
+* exits 1 for a valid-but-unset key, and not every agent has every key
+* authored (self-hosted agents set up by older CLIs, the ENOENT branch of
+* `initWorkspace`); a state-dependent probe would roll a good package back.
+* `config file` exists on 2026.8.1 and 2026.9.5 and exits 0 on an admitted
+* runtime regardless of config contents.
+*/
+const OPENCLAW_ADMISSION_PROBE_ARGS = ["config", "file"];
 function resolveUpgradeCommand(runtime, version) {
 	switch (runtime) {
 		case "openclaw":
@@ -67,12 +82,13 @@ async function upgradeRuntime(runtime, version, runtimeProcess, options = {}) {
 			stderr: result.stderr
 		};
 	});
+	const openclawEnv = {
+		...process.env,
+		...OPENCLAW_EXTERNAL_SUPERVISOR_ENV
+	};
 	const commandOptions = (timeout) => runtime === "openclaw" ? {
 		timeout,
-		env: {
-			...process.env,
-			...OPENCLAW_EXTERNAL_SUPERVISOR_ENV
-		}
+		env: openclawEnv
 	} : { timeout };
 	const cmd = resolveUpgradeCommand(runtime, version);
 	if (!cmd) {
@@ -89,24 +105,60 @@ async function upgradeRuntime(runtime, version, runtimeProcess, options = {}) {
 		};
 	}
 	let previousOpenClawVersion;
+	let nodeUpgraded = false;
 	if (runtime === "openclaw") try {
 		const [{ stdout: nodeOutput }, { stdout: openClawOutput }] = await Promise.all([runCommand("node", ["--version"], commandOptions(1e4)), runCommand("openclaw", ["--version"], commandOptions(1e4))]);
-		const nodeVersion = nodeOutput.trim();
+		previousOpenClawVersion = parseOpenClawVersion(openClawOutput);
+		let nodeVersion = nodeOutput.trim();
 		if (!supportsOpenClawNode(nodeVersion)) {
-			const message = `OpenClaw ${version ?? "2.x"} requires Node.js ${OPENCLAW_NODE_REQUIREMENT}; this host resolves ${nodeVersion}. Upgrade Node.js or rebuild the agent before retrying.`;
-			logger.error({
+			if (!options.nodeRemediation) {
+				const message = `OpenClaw ${version ?? "2.x"} requires Node.js ${OPENCLAW_NODE_REQUIREMENT}; this host resolves ${nodeVersion}. Upgrade Node.js or rebuild the agent before retrying.`;
+				logger.error({
+					runtime,
+					version,
+					nodeVersion
+				}, message);
+				return {
+					success: false,
+					runtime,
+					version,
+					error: message
+				};
+			}
+			const fromNode = nodeVersion;
+			logger.warn({
 				runtime,
 				version,
+				nodeVersion,
+				requirement: OPENCLAW_NODE_REQUIREMENT
+			}, "Host Node.js does not satisfy OpenClaw; installing the managed Node channel first");
+			try {
+				nodeVersion = await remediateManagedNode(runCommand, openclawEnv, options.nodeRemediation);
+			} catch (err) {
+				const replaced = err instanceof NodeRemediationError && err.nodeReplaced;
+				const resolvedNode = err instanceof NodeRemediationError ? err.resolvedNode : void 0;
+				nodeUpgraded = replaced;
+				if (!(err instanceof NodeRemediationError && err.cooldownActive)) captureNodeRemediation({
+					outcome: "failure",
+					fromNode,
+					...replaced && resolvedNode ? { toNode: resolvedNode } : {},
+					runtimeVersion: previousOpenClawVersion,
+					cause: err
+				});
+				throw err;
+			}
+			nodeUpgraded = true;
+			captureNodeRemediation({
+				outcome: "success",
+				fromNode,
+				toNode: nodeVersion,
+				runtimeVersion: previousOpenClawVersion
+			});
+			logger.info({
+				fromNode,
 				nodeVersion
-			}, message);
-			return {
-				success: false,
-				runtime,
-				version,
-				error: message
-			};
+			}, "Managed Node.js remediation complete");
 		}
-		previousOpenClawVersion = parseOpenClawVersion(openClawOutput);
 	} catch (err) {
 		const message = `OpenClaw upgrade preflight failed: ${err instanceof Error ? err.message : String(err)}`;
 		logger.error({
@@ -117,6 +169,7 @@ async function upgradeRuntime(runtime, version, runtimeProcess, options = {}) {
 			success: false,
 			runtime,
 			version,
+			nodeUpgraded,
 			error: message
 		};
 	}
@@ -155,6 +208,7 @@ async function upgradeRuntime(runtime, version, runtimeProcess, options = {}) {
 				const installedVersion = parseOpenClawVersion((await runCommand("openclaw", ["--version"], commandOptions(1e4))).stdout);
 				if (installedVersion !== version) throw new Error(`OpenClaw package verification failed: requested ${version}, resolved ${installedVersion ?? "unknown"}`);
 				runtimeChanged = installedVersion !== previousOpenClawVersion;
+				await runCommand("openclaw", [...OPENCLAW_ADMISSION_PROBE_ARGS], commandOptions(6e4));
 				doctorStarted = true;
 				await runCommand("openclaw", [
 					"doctor",
@@ -195,13 +249,15 @@ async function upgradeRuntime(runtime, version, runtimeProcess, options = {}) {
 		else await performUpgrade();
 		logger.info({
 			runtime,
-			version
+			version,
+			nodeUpgraded
 		}, "Runtime upgraded successfully");
 		return {
 			success: true,
 			runtime,
 			version,
-			runtimeChanged
+			runtimeChanged,
+			nodeUpgraded
 		};
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
@@ -215,6 +271,7 @@ async function upgradeRuntime(runtime, version, runtimeProcess, options = {}) {
 			runtime,
 			version,
 			runtimeChanged,
+			nodeUpgraded,
 			error: message
 		};
 	} finally {

package/dist/sentry.js

@@ -313,6 +313,34 @@ function captureCliFailure(context, cause) {
 	} catch {}
 }
 /**
+* Fleet-visible record of a managed Node.js remediation attempt (the in-place
+* Node 22 → 24 move `runtime-upgrade.ts` performs before installing an OpenClaw
+* that dropped Node 22). One event per host per attempt so the campaign can
+* count remediated vs failed agents; the daemon's local log alone cannot answer
+* that. No-op when Sentry is not initialised. Never throws.
+*/
+function captureNodeRemediation(opts) {
+	if (!sentry) return;
+	try {
+		const tags = {
+			context: "node-remediation",
+			outcome: opts.outcome,
+			fromNode: opts.fromNode,
+			...opts.toNode ? { toNode: opts.toNode } : {},
+			...opts.runtimeVersion ? { runtimeVersion: opts.runtimeVersion } : {}
+		};
+		if (opts.outcome === "failure" && opts.cause instanceof Error) {
+			sentry.captureException(opts.cause, { tags });
+			return;
+		}
+		const detail = opts.outcome === "failure" && opts.cause !== void 0 ? `: ${String(opts.cause)}` : "";
+		sentry.captureMessage(`node remediation ${opts.outcome}${detail}`, {
+			level: opts.outcome === "failure" ? "error" : "info",
+			tags
+		});
+	} catch {}
+}
+/**
 * Capture a runtime child-process crash (non-graceful exit) or spawn failure
 * into the dedicated `agent-runtime` project. Recent output travels as
 * breadcrumbs — NEVER `extra`, which `scrubEvent` (the runtime client's
@@ -428,4 +456,4 @@ function captureFatal(cause) {
 	} catch {}
 }
 //#endregion
-export { captureFatal as a, captureRuntimeCrash as c, initAgentSentry as d, setAgentContext as f, captureCliFailure as i, captureRuntimeErrorOutput as l, logger as m, AGENT_MCP_SENTRY_DSN as n, captureIntegrationFailure as o, LOG_FILE as p, AGENT_RUNTIME_SENTRY_DSN as r, captureMcpFailure as s, AGENT_DAEMON_SENTRY_DSN as t, flushSentry as u };
+export { captureFatal as a, captureNodeRemediation as c, flushSentry as d, initAgentSentry as f, logger as h, captureCliFailure as i, captureRuntimeCrash as l, LOG_FILE as m, AGENT_MCP_SENTRY_DSN as n, captureIntegrationFailure as o, setAgentContext as p, AGENT_RUNTIME_SENTRY_DSN as r, captureMcpFailure as s, AGENT_DAEMON_SENTRY_DSN as t, captureRuntimeErrorOutput as u };

package/dist/src/index.d.ts

@@ -44,24 +44,83 @@ declare function startDaemon(): Promise<void>;
  * truth for every install path:
  *   - `@alfe.ai/cli` `installRuntime` (fresh `alfe setup`)
  *   - the daemon `runtime.update` default (this package)
- *   - managed provisioning (`services/compute/src/lib/provisioner.ts` installs a
- *     compatible Node.js 22 before the CLI consumes this pin)
+ *   - managed provisioning (`services/compute/src/lib/provisioner.ts` installs the
+ *     Node.js 24 channel before the CLI consumes this pin)
  *
  * Pinning (rather than floating `npm install -g openclaw` → `latest`) is deliberate:
  * OpenClaw runs on every managed agent, so a `latest` that changes runtime semantics —
  * e.g. 2026.6.8 made a non-empty `plugins.allow` an exclusive allowlist — becomes a
  * silent fleet outage with no Alfe deploy. Bump deliberately after validating a new
  * OpenClaw, then cut a CLI release so the pin travels with the CLI version.
+ *
+ * Raising the engine range below obligates every consumer of it: the daemon upgrade
+ * preflight (`runtime-upgrade.ts`), the CLI `installRuntime`, and the compute
+ * cloud-init literals (tied to these constants by `provisioner.test.ts`).
+ */
+declare const PINNED_OPENCLAW_VERSION = "2026.9.5";
+/**
+ * OpenClaw 2026.9.5's published Node.js engine floor. Node 22 and Node 25 are no
+ * longer supported upstream (2026.9.x dropped both branches; the preinstall script
+ * refuses to install on them).
+ */
+declare const OPENCLAW_NODE_REQUIREMENT = ">=24.16.0 <25 || >=26.1.0";
+/**
+ * The Node.js major the managed image installs (NodeSource `setup_24.x`) and that
+ * `upgradeRuntime` remediates existing managed hosts onto. 24 is the current LTS
+ * line; 26 is not LTS yet.
  */
-declare const PINNED_OPENCLAW_VERSION = "2026.8.1";
-/** OpenClaw 2026.8.1's published Node.js engine floor. */
-declare const OPENCLAW_NODE_REQUIREMENT = ">=22.22.3 <23 || >=24.15.0 <25 || >=25.9.0";
+declare const OPENCLAW_MANAGED_NODE_MAJOR = 24;
 /**
- * Whether a concrete Node.js version satisfies OpenClaw 2.x's engine range.
- * Accepts `process.versions.node` (`22.22.3`) or CLI output (`v22.22.3`).
+ * Whether a concrete Node.js version satisfies OpenClaw's engine range.
+ * Accepts `process.versions.node` (`24.21.0`) or CLI output (`v24.21.0`).
+ * Pre-release tags are rejected; build metadata (`+…`) is accepted.
  */
 declare function supportsOpenClawNode(nodeVersion: string): boolean;
 //#endregion
+//#region src/node-remediation.d.ts
+
+type RemediationCommandRunner = (command: string, args: string[], options: {
+  timeout: number;
+  env?: NodeJS.ProcessEnv;
+}) => Promise<{
+  stdout: string;
+  stderr: string;
+}>;
+interface RemediateManagedNodeOptions {
+  /**
+   * Prove the currently installed `openclaw` still boots under the new Node
+   * (default true — the daemon needs the old runtime for the pre-upgrade
+   * backup). `alfe setup` on a fresh VM passes false: nothing is installed yet.
+   */
+  verifyInstalledRuntime?: boolean;
+  /**
+   * Where the failure cooldown marker lives (default `~/.alfe`). Test seam;
+   * `null` disables the marker entirely.
+   */
+  stateDirectory?: string | null;
+  /** Test seam for the cooldown clock. */
+  now?: () => number;
+}
+/**
+ * Thrown when remediation fails. `nodeReplaced` is the load-bearing field: a
+ * failure AFTER apt has swapped the host Node (verification or the installed
+ * runtime's boot check failed) leaves the host on a new, unproven Node, which
+ * is the state that needs an operator — very different from "never touched".
+ */
+
+/**
+ * Install the managed Node.js channel on a Debian/Ubuntu managed host and
+ * return the resolved `node --version`.
+ *
+ * Runs BEFORE any runtime gate suspend or backup: the live OpenClaw child keeps
+ * its already-open binary, and later `openclaw`/`npm` spawns resolve the new
+ * binary through PATH. Fails closed (with `nodeReplaced` set accurately) if the
+ * resulting Node still misses the range or if the currently installed OpenClaw
+ * no longer boots under it — in that case the caller must not proceed to a
+ * backup it could not produce.
+ */
+declare function remediateManagedNode(runCommand: RemediationCommandRunner, baseEnv: NodeJS.ProcessEnv, options?: RemediateManagedNodeOptions): Promise<string>;
+//#endregion
 //#region src/claude-code-host-version.d.ts
 /**
  * The `@alfe.ai/claude-code-host` version Alfe pins the claude-code runtime to —
@@ -164,6 +223,14 @@ declare function captureIntegrationFailure(integration: string, phase: string, c
  * Sentry is not initialised. Never throws.
  */
 declare function captureCliFailure(context: string, cause?: unknown): void;
+/**
+ * Fleet-visible record of a managed Node.js remediation attempt (the in-place
+ * Node 22 → 24 move `runtime-upgrade.ts` performs before installing an OpenClaw
+ * that dropped Node 22). One event per host per attempt so the campaign can
+ * count remediated vs failed agents; the daemon's local log alone cannot answer
+ * that. No-op when Sentry is not initialised. Never throws.
+ */
+
 /** A line of runtime child-process output attached to a crash event. */
 interface RuntimeOutputLine {
   stream: "stdout" | "stderr";
@@ -414,4 +481,4 @@ declare function checkExistingDaemon(): Promise<number | null>;
  */
 declare function stopExistingDaemon(): Promise<boolean>;
 //#endregion
-export { AGENT_DAEMON_SENTRY_DSN, AGENT_MCP_SENTRY_DSN, AGENT_RUNTIME_SENTRY_DSN, ALFE_DIR, type AgentIdentity, type AgentWorkspaceConfig, type DaemonConfig, type DaemonHealth, type IPCEvent, type IPCRequest, type IPCResponse, type InitAgentSentryOptions, OPENCLAW_NODE_REQUIREMENT, PID_PATH, PINNED_CLAUDE_CODE_HOST_VERSION, PINNED_OPENCLAW_VERSION, PROTOCOL_VERSION, type RuntimeOutputLine, SOCKET_PATH, type SentrySurface, captureCliFailure, captureFatal, captureIntegrationFailure, captureMcpFailure, captureRuntimeCrash, captureRuntimeErrorOutput, checkExistingDaemon, fetchAgentConfig, flushSentry, formatHealthReport, initAgentSentry, installService, isServiceInstalled, loadDaemonConfig, logger, queryDaemonHealth, resolveAgentIdentity, restartService, setAgentContext, startDaemon, startService, stopExistingDaemon, stopService, supportsOpenClawNode, uninstallService };
+export { AGENT_DAEMON_SENTRY_DSN, AGENT_MCP_SENTRY_DSN, AGENT_RUNTIME_SENTRY_DSN, ALFE_DIR, type AgentIdentity, type AgentWorkspaceConfig, type DaemonConfig, type DaemonHealth, type IPCEvent, type IPCRequest, type IPCResponse, type InitAgentSentryOptions, OPENCLAW_MANAGED_NODE_MAJOR, OPENCLAW_NODE_REQUIREMENT, PID_PATH, PINNED_CLAUDE_CODE_HOST_VERSION, PINNED_OPENCLAW_VERSION, PROTOCOL_VERSION, type RemediateManagedNodeOptions, type RemediationCommandRunner, type RuntimeOutputLine, SOCKET_PATH, type SentrySurface, captureCliFailure, captureFatal, captureIntegrationFailure, captureMcpFailure, captureRuntimeCrash, captureRuntimeErrorOutput, checkExistingDaemon, fetchAgentConfig, flushSentry, formatHealthReport, initAgentSentry, installService, isServiceInstalled, loadDaemonConfig, logger, queryDaemonHealth, remediateManagedNode, resolveAgentIdentity, restartService, setAgentContext, startDaemon, startService, stopExistingDaemon, stopService, supportsOpenClawNode, uninstallService };

package/dist/src/index.js

@@ -1,4 +1,5 @@
-import { d as supportsOpenClawNode, l as OPENCLAW_NODE_REQUIREMENT, u as PINNED_OPENCLAW_VERSION } from "../runtime-process.js";
+import { d as PINNED_OPENCLAW_VERSION, f as supportsOpenClawNode, l as OPENCLAW_MANAGED_NODE_MAJOR, u as OPENCLAW_NODE_REQUIREMENT } from "../runtime-process.js";
 import { _ as loadDaemonConfig, a as installService, c as startService, d as uninstallService, f as PROTOCOL_VERSION, g as fetchAgentConfig, h as SOCKET_PATH, i as checkExistingDaemon, l as stopExistingDaemon, m as PID_PATH, n as queryDaemonHealth, o as isServiceInstalled, p as ALFE_DIR, r as startDaemon, s as restartService, t as formatHealthReport, u as stopService, v as resolveAgentIdentity, y as PINNED_CLAUDE_CODE_HOST_VERSION } from "../health.js";
-import { a as captureFatal, c as captureRuntimeCrash, d as initAgentSentry, f as setAgentContext, i as captureCliFailure, l as captureRuntimeErrorOutput, m as logger, n as AGENT_MCP_SENTRY_DSN, o as captureIntegrationFailure, r as AGENT_RUNTIME_SENTRY_DSN, s as captureMcpFailure, t as AGENT_DAEMON_SENTRY_DSN, u as flushSentry } from "../sentry.js";
-export { AGENT_DAEMON_SENTRY_DSN, AGENT_MCP_SENTRY_DSN, AGENT_RUNTIME_SENTRY_DSN, ALFE_DIR, OPENCLAW_NODE_REQUIREMENT, PID_PATH, PINNED_CLAUDE_CODE_HOST_VERSION, PINNED_OPENCLAW_VERSION, PROTOCOL_VERSION, SOCKET_PATH, captureCliFailure, captureFatal, captureIntegrationFailure, captureMcpFailure, captureRuntimeCrash, captureRuntimeErrorOutput, checkExistingDaemon, fetchAgentConfig, flushSentry, formatHealthReport, initAgentSentry, installService, isServiceInstalled, loadDaemonConfig, logger, queryDaemonHealth, resolveAgentIdentity, restartService, setAgentContext, startDaemon, startService, stopExistingDaemon, stopService, supportsOpenClawNode, uninstallService };
+import { a as captureFatal, d as flushSentry, f as initAgentSentry, h as logger, i as captureCliFailure, l as captureRuntimeCrash, n as AGENT_MCP_SENTRY_DSN, o as captureIntegrationFailure, p as setAgentContext, r as AGENT_RUNTIME_SENTRY_DSN, s as captureMcpFailure, t as AGENT_DAEMON_SENTRY_DSN, u as captureRuntimeErrorOutput } from "../sentry.js";
+import { n as remediateManagedNode } from "../node-remediation.js";
+export { AGENT_DAEMON_SENTRY_DSN, AGENT_MCP_SENTRY_DSN, AGENT_RUNTIME_SENTRY_DSN, ALFE_DIR, OPENCLAW_MANAGED_NODE_MAJOR, OPENCLAW_NODE_REQUIREMENT, PID_PATH, PINNED_CLAUDE_CODE_HOST_VERSION, PINNED_OPENCLAW_VERSION, PROTOCOL_VERSION, SOCKET_PATH, captureCliFailure, captureFatal, captureIntegrationFailure, captureMcpFailure, captureRuntimeCrash, captureRuntimeErrorOutput, checkExistingDaemon, fetchAgentConfig, flushSentry, formatHealthReport, initAgentSentry, installService, isServiceInstalled, loadDaemonConfig, logger, queryDaemonHealth, remediateManagedNode, resolveAgentIdentity, restartService, setAgentContext, startDaemon, startService, stopExistingDaemon, stopService, supportsOpenClawNode, uninstallService };

package/dist/upgrade.js

@@ -1,4 +1,4 @@
-import { i as captureCliFailure, m as logger } from "./sentry.js";
+import { h as logger, i as captureCliFailure } from "./sentry.js";
 import { existsSync } from "node:fs";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/gateway",
-  "version": "0.9.19",
+  "version": "0.10.1",
   "description": "Alfe local gateway daemon — persistent control plane for agent integrations",
   "type": "module",
   "bin": {
@@ -23,11 +23,11 @@
     "pino-roll": "^1.2.0",
     "smol-toml": ">=1.6.1",
     "ws": "^8.18.0",
-    "@alfe.ai/agent-api-client": "^0.19.1",
+    "@alfe.ai/agent-api-client": "^0.19.2",
     "@alfe.ai/ai-proxy-local": "^0.0.17",
     "@alfe.ai/config": "^0.4.1",
     "@alfe.ai/integration-manifest": "^0.4.2",
-    "@alfe.ai/integrations": "^0.6.6",
+    "@alfe.ai/integrations": "^0.6.7",
     "@alfe.ai/mcp-bundler": "^0.4.2"
   },
   "license": "UNLICENSED",