@alfe.ai/gateway 0.0.1

package/dist/health.js

@@ -0,0 +1,1846 @@
+import { createRequire } from "node:module";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import pino from "pino";
+import { chmodSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { getEndpointFromToken, readConfig } from "@alfe.ai/config";
+import { parse } from "smol-toml";
+import WebSocket from "ws";
+import { createConnection, createServer } from "node:net";
+import { execSync } from "node:child_process";
+import { IntegrationManager, IntegrationManagerAdapter, OpenClawApplier } from "@alfe.ai/integrations";
+import { randomUUID } from "node:crypto";
+//#region \0rolldown/runtime.js
+var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+//#endregion
+//#region src/logger.ts
+/**
+* Daemon logger — pino with rolling file output.
+*
+* Writes to ~/.alfe/logs/gateway.log with 10MB rotation, keep 5 files.
+* Also outputs to stdout in development mode.
+*/
+const LOG_DIR = join(homedir(), ".alfe", "logs");
+const LOG_FILE = join(LOG_DIR, "gateway.log");
+try {
+	mkdirSync(LOG_DIR, { recursive: true });
+} catch {}
+const isDev = process.env.NODE_ENV !== "production";
+/**
+* Create the daemon logger.
+* In development: pretty-prints to stdout.
+* In production: JSON to rolling file.
+*/
+function createLogger() {
+	if (isDev) return pino({
+		level: process.env.LOG_LEVEL ?? "debug",
+		transport: {
+			target: "pino/file",
+			options: { destination: 1 }
+		}
+	});
+	const transport = pino.transport({
+		target: "pino-roll",
+		options: {
+			file: LOG_FILE,
+			size: "10m",
+			limit: { count: 5 }
+		}
+	});
+	return pino({ level: process.env.LOG_LEVEL ?? "info" }, transport);
+}
+const logger = createLogger();
+//#endregion
+//#region src/config.ts
+/**
+* Daemon configuration — reads ~/.alfe/config.toml and resolves agent identity.
+*
+* Bootstrap flow:
+*   1. Read api_key from ~/.alfe/config.toml (via @alfe.ai/config)
+*   2. Derive API endpoint from token prefix
+*   3. Call /auth/validate to get tenantId (orgId)
+*   4. Use tokenId as agent identity for cloud registration
+*/
+const ALFE_DIR = join(homedir(), ".alfe");
+const SOCKET_PATH = join(ALFE_DIR, "gateway.sock");
+const PID_PATH = join(ALFE_DIR, "gateway.pid");
+/**
+* Resolve agent identity by validating the api_key with the auth service.
+* Returns agentId (derived from tokenId) and orgId (tenantId).
+*/
+async function resolveAgentIdentity(apiKey, apiEndpoint) {
+	const validateUrl = `${apiEndpoint}/auth/validate`;
+	const response = await fetch(validateUrl, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ token: apiKey })
+	});
+	if (!response.ok) throw new Error(`Token validation failed (HTTP ${String(response.status)}). Is your API key valid? Run \`alfe login\` to reconfigure.`);
+	const result = await response.json();
+	if (!result.success || !result.data?.valid) throw new Error(`API key invalid: ${result.data?.error ?? "validation failed"}. Run \`alfe login\` to reconfigure.`);
+	const orgId = result.data.tenantId;
+	if (!orgId) throw new Error("Token validation returned no tenantId — cannot determine org.");
+	return {
+		agentId: result.data.tokenId ?? deriveAgentId(apiKey),
+		orgId,
+		runtime: result.data.runtime ?? "openclaw"
+	};
+}
+/**
+* Derive a stable agent ID from an API key (fallback when tokenId not available).
+*/
+function deriveAgentId(apiKey) {
+	let hash = 0;
+	for (let i = 0; i < apiKey.length; i++) {
+		const chr = apiKey.charCodeAt(i);
+		hash = (hash << 5) - hash + chr | 0;
+	}
+	return `agent-${Math.abs(hash).toString(36)}`;
+}
+/**
+* Derive the cloud gateway WebSocket URL from the API endpoint.
+* The cloud gateway runs on Fly.io — its URL follows a convention.
+*/
+function deriveGatewayWsUrl(apiEndpoint) {
+	if (apiEndpoint.includes("dev.alfe.ai")) return process.env.ALFE_GATEWAY_WS_URL ?? "wss://gateway.dev.alfe.ai/ws";
+	if (apiEndpoint.includes("test.alfe.ai")) return process.env.ALFE_GATEWAY_WS_URL ?? "wss://gateway.test.alfe.ai/ws";
+	return process.env.ALFE_GATEWAY_WS_URL ?? "wss://gateway.alfe.ai/ws";
+}
+/**
+* Parse [runtimes.*] sections from config.toml.
+* Returns a map of runtime name → RuntimeConfig.
+*
+* Example config.toml:
+*   [runtimes.openclaw]
+*   workspace = "~/.openclaw"
+*/
+async function loadRuntimeConfigs() {
+	const configPath = join(ALFE_DIR, "config.toml");
+	if (!existsSync(configPath)) return {};
+	try {
+		const runtimes = parse(await readFile(configPath, "utf-8")).runtimes;
+		if (!runtimes) return {};
+		const result = {};
+		for (const [name, cfg] of Object.entries(runtimes)) if (typeof cfg.workspace === "string") result[name] = { workspace: cfg.workspace.startsWith("~/") ? join(homedir(), cfg.workspace.slice(2)) : cfg.workspace };
+		return result;
+	} catch {
+		return {};
+	}
+}
+/**
+* Whether the daemon is running in managed mode (ECS Fargate container).
+* In managed mode, configuration comes from environment variables instead
+* of ~/.alfe/config.toml, and IPC/PID features are disabled.
+*/
+function isManagedMode() {
+	return process.env.ALFE_MANAGED === "true";
+}
+/**
+* Load configuration for managed mode (ECS Fargate).
+* All config comes from environment variables — no local files needed.
+*/
+async function loadManagedConfig() {
+	const apiKey = process.env.ALFE_API_KEY;
+	const apiEndpoint = process.env.ALFE_API_ENDPOINT;
+	if (!apiKey || !apiEndpoint) throw new Error("ALFE_API_KEY and ALFE_API_ENDPOINT required in managed mode");
+	const identity = await resolveAgentIdentity(apiKey, apiEndpoint);
+	return {
+		apiKey,
+		apiEndpoint,
+		gatewayWsUrl: process.env.ALFE_GATEWAY_WS_URL ?? deriveGatewayWsUrl(apiEndpoint),
+		socketPath: "",
+		pidPath: "",
+		agentId: identity.agentId,
+		orgId: identity.orgId,
+		runtime: identity.runtime,
+		runtimes: identity.runtime === "openclaw" ? { openclaw: { workspace: join(homedir(), ".openclaw") } } : {}
+	};
+}
+/**
+* Load full daemon configuration.
+* Reads config.toml, validates the API key, resolves agent identity,
+* and parses runtime configurations.
+*
+* In managed mode, loads from environment variables instead.
+*/
+async function loadDaemonConfig() {
+	if (isManagedMode()) return loadManagedConfig();
+	let alfeConfig;
+	try {
+		alfeConfig = await readConfig();
+	} catch {
+		throw new Error("Alfe not configured. Run `alfe login` first.");
+	}
+	const apiEndpoint = alfeConfig.gateway ?? getEndpointFromToken(alfeConfig.api_key);
+	const identity = await resolveAgentIdentity(alfeConfig.api_key, apiEndpoint);
+	const gatewayWsUrl = alfeConfig.gateway_url ?? deriveGatewayWsUrl(apiEndpoint);
+	const runtimes = await loadRuntimeConfigs();
+	return {
+		apiKey: alfeConfig.api_key,
+		apiEndpoint,
+		gatewayWsUrl,
+		socketPath: process.env.ALFE_GATEWAY_SOCKET ?? SOCKET_PATH,
+		pidPath: PID_PATH,
+		agentId: identity.agentId,
+		orgId: identity.orgId,
+		runtime: identity.runtime,
+		runtimes
+	};
+}
+/**
+* Fetch agent workspace config from the API.
+*
+* 1. GET /agents/me/workspace → { personalityKey }
+* 2. If personalityKey set, GET /personalities/:key/files → persona file contents
+*
+* Returns null if the agent has no personality assigned or the fetch fails.
+*/
+async function fetchAgentConfig(apiKey, apiEndpoint) {
+	try {
+		const wsResponse = await fetch(`${apiEndpoint}/agents/me/workspace`, {
+			method: "GET",
+			headers: { "Authorization": `Bearer ${apiKey}` }
+		});
+		if (!wsResponse.ok) return null;
+		const personalityKey = (await wsResponse.json()).data?.personalityKey;
+		if (!personalityKey) return null;
+		const filesResponse = await fetch(`${apiEndpoint}/personalities/${encodeURIComponent(personalityKey)}/files`, {
+			method: "GET",
+			headers: { "Authorization": `Bearer ${apiKey}` }
+		});
+		if (!filesResponse.ok) return {
+			personalityKey,
+			files: {}
+		};
+		return {
+			personalityKey,
+			files: (await filesResponse.json()).data?.files ?? {}
+		};
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region ../../packages-internal/ids/dist/prefixes.js
+const ID_PREFIXES = {
+	agent: "agt",
+	organization: "org",
+	person: "per",
+	auditEvent: "evt",
+	token: "tok",
+	transaction: "txn",
+	subscription: "sub",
+	request: "req",
+	connection: "conn",
+	correlation: "cor",
+	command: "cmd",
+	message: "msg",
+	ipcRequest: "ipc",
+	pluginConnection: "plg"
+};
+//#endregion
+//#region ../../packages-internal/ids/dist/create.js
+var import_index_umd = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
+	(function(global, factory) {
+		typeof exports === "object" && typeof module !== "undefined" ? factory(exports) : typeof define === "function" && define.amd ? define(["exports"], factory) : (global = typeof globalThis !== "undefined" ? globalThis : global || self, factory(global.ULID = {}));
+	})(exports, (function(exports$1) {
+		"use strict";
+		function createError(message) {
+			const err = new Error(message);
+			err.source = "ulid";
+			return err;
+		}
+		const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+		const ENCODING_LEN = 32;
+		const TIME_MAX = Math.pow(2, 48) - 1;
+		const TIME_LEN = 10;
+		const RANDOM_LEN = 16;
+		function replaceCharAt(str, index, char) {
+			if (index > str.length - 1) return str;
+			return str.substr(0, index) + char + str.substr(index + 1);
+		}
+		function incrementBase32(str) {
+			let done = void 0;
+			let index = str.length;
+			let char;
+			let charIndex;
+			const maxCharIndex = ENCODING_LEN - 1;
+			while (!done && index-- >= 0) {
+				char = str[index];
+				charIndex = ENCODING.indexOf(char);
+				if (charIndex === -1) throw createError("incorrectly encoded string");
+				if (charIndex === maxCharIndex) {
+					str = replaceCharAt(str, index, ENCODING[0]);
+					continue;
+				}
+				done = replaceCharAt(str, index, ENCODING[charIndex + 1]);
+			}
+			if (typeof done === "string") return done;
+			throw createError("cannot increment this string");
+		}
+		function randomChar(prng) {
+			let rand = Math.floor(prng() * ENCODING_LEN);
+			if (rand === ENCODING_LEN) rand = ENCODING_LEN - 1;
+			return ENCODING.charAt(rand);
+		}
+		function encodeTime(now, len) {
+			if (isNaN(now)) throw new Error(now + " must be a number");
+			if (now > TIME_MAX) throw createError("cannot encode time greater than " + TIME_MAX);
+			if (now < 0) throw createError("time must be positive");
+			if (Number.isInteger(Number(now)) === false) throw createError("time must be an integer");
+			let mod;
+			let str = "";
+			for (; len > 0; len--) {
+				mod = now % ENCODING_LEN;
+				str = ENCODING.charAt(mod) + str;
+				now = (now - mod) / ENCODING_LEN;
+			}
+			return str;
+		}
+		function encodeRandom(len, prng) {
+			let str = "";
+			for (; len > 0; len--) str = randomChar(prng) + str;
+			return str;
+		}
+		function decodeTime(id) {
+			if (id.length !== TIME_LEN + RANDOM_LEN) throw createError("malformed ulid");
+			var time = id.substr(0, TIME_LEN).split("").reverse().reduce((carry, char, index) => {
+				const encodingIndex = ENCODING.indexOf(char);
+				if (encodingIndex === -1) throw createError("invalid character found: " + char);
+				return carry += encodingIndex * Math.pow(ENCODING_LEN, index);
+			}, 0);
+			if (time > TIME_MAX) throw createError("malformed ulid, timestamp too large");
+			return time;
+		}
+		function detectPrng(allowInsecure = false, root) {
+			if (!root) root = typeof window !== "undefined" ? window : null;
+			const browserCrypto = root && (root.crypto || root.msCrypto);
+			if (browserCrypto) return () => {
+				const buffer = new Uint8Array(1);
+				browserCrypto.getRandomValues(buffer);
+				return buffer[0] / 255;
+			};
+			else try {
+				const nodeCrypto = __require("crypto");
+				return () => nodeCrypto.randomBytes(1).readUInt8() / 255;
+			} catch (e) {}
+			if (allowInsecure) {
+				try {
+					console.error("secure crypto unusable, falling back to insecure Math.random()!");
+				} catch (e) {}
+				return () => Math.random();
+			}
+			throw createError("secure crypto unusable, insecure Math.random not allowed");
+		}
+		function factory(currPrng) {
+			if (!currPrng) currPrng = detectPrng();
+			return function ulid(seedTime) {
+				if (isNaN(seedTime)) seedTime = Date.now();
+				return encodeTime(seedTime, TIME_LEN) + encodeRandom(RANDOM_LEN, currPrng);
+			};
+		}
+		function monotonicFactory(currPrng) {
+			if (!currPrng) currPrng = detectPrng();
+			let lastTime = 0;
+			let lastRandom;
+			return function ulid(seedTime) {
+				if (isNaN(seedTime)) seedTime = Date.now();
+				if (seedTime <= lastTime) {
+					const incrementedRandom = lastRandom = incrementBase32(lastRandom);
+					return encodeTime(lastTime, TIME_LEN) + incrementedRandom;
+				}
+				lastTime = seedTime;
+				const newRandom = lastRandom = encodeRandom(RANDOM_LEN, currPrng);
+				return encodeTime(seedTime, TIME_LEN) + newRandom;
+			};
+		}
+		const ulid = factory();
+		exports$1.decodeTime = decodeTime;
+		exports$1.detectPrng = detectPrng;
+		exports$1.encodeRandom = encodeRandom;
+		exports$1.encodeTime = encodeTime;
+		exports$1.factory = factory;
+		exports$1.incrementBase32 = incrementBase32;
+		exports$1.monotonicFactory = monotonicFactory;
+		exports$1.randomChar = randomChar;
+		exports$1.replaceCharAt = replaceCharAt;
+		exports$1.ulid = ulid;
+	}));
+})))();
+function createId(prefix) {
+	return `${prefix}_${(0, import_index_umd.ulid)()}`;
+}
+function pluginConnectionId() {
+	return createId(ID_PREFIXES.pluginConnection);
+}
+//#endregion
+//#region src/protocol.ts
+/**
+* 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.
+*/
+const CLOUD_COMMAND_TO_IPC = {};
+/**
+* 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];
+	if (!method) return null;
+	return {
+		type: "req",
+		id: command.commandId,
+		method,
+		params: {
+			...typeof command.payload === "object" && command.payload !== null ? command.payload : {},
+			_agentId: command.agentId,
+			_commandId: command.commandId
+		}
+	};
+}
+/**
+* Translate a local IPC response back into a cloud COMMAND_ACK.
+*/
+function ipcResponseToCloudAck(commandId, response) {
+	return {
+		type: "COMMAND_ACK",
+		commandId,
+		status: response.ok ? "ok" : "error",
+		result: response.ok ? response.payload : response.error
+	};
+}
+/**
+* Create a SERVICE_REGISTER message for cloud registration.
+*/
+function createServiceRegister(agentId, capabilities = [
+	"integrations",
+	"lifecycle",
+	"health"
+]) {
+	return {
+		type: "SERVICE_REGISTER",
+		serviceId: `gateway-daemon-${agentId}`,
+		agentIds: [agentId],
+		capabilities
+	};
+}
+/**
+* Create an IPC success response.
+*/
+function createIPCResponse(id, payload) {
+	return {
+		id,
+		ok: true,
+		payload
+	};
+}
+/**
+* Create an IPC error response.
+*/
+function createIPCError(id, code, message) {
+	return {
+		id,
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	};
+}
+/**
+* Create an IPC event message.
+*/
+function createIPCEvent(event, payload) {
+	return {
+		type: "event",
+		event,
+		payload
+	};
+}
+/**
+* Parse a raw JSON string into a typed message, or null on failure.
+*/
+function parseMessage(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+/**
+* Type guard: is this a cloud COMMAND message?
+*/
+function isCloudCommand(msg) {
+	return typeof msg === "object" && msg !== null && msg.type === "COMMAND" && typeof msg.commandId === "string";
+}
+/**
+* Type guard: is this a cloud SERVICE_ACK message?
+*/
+function isCloudServiceAck(msg) {
+	return typeof msg === "object" && msg !== null && msg.type === "SERVICE_ACK";
+}
+/**
+* Type guard: is this a cloud DESIRED_STATE message?
+*/
+function isCloudDesiredState(msg) {
+	return typeof msg === "object" && msg !== null && msg.type === "DESIRED_STATE" && Array.isArray(msg.integrations);
+}
+/**
+* Create a RECONCILIATION_REPORT message.
+*/
+function createReconciliationReport(results) {
+	return {
+		type: "RECONCILIATION_REPORT",
+		results
+	};
+}
+/**
+* Type guard: is this a cloud PING message?
+*/
+function isCloudPing(msg) {
+	return typeof msg === "object" && msg !== null && msg.type === "PING";
+}
+/**
+* Type guard: is this an IPC request?
+*/
+function isIPCRequest(msg) {
+	return typeof msg === "object" && msg !== null && msg.type === "req" && typeof msg.id === "string" && typeof msg.method === "string";
+}
+/**
+* Type guard: is this an IPC response?
+*/
+function isIPCResponse(msg) {
+	return typeof msg === "object" && msg !== null && typeof msg.id === "string" && typeof msg.ok === "boolean" && !("type" in msg);
+}
+/** Current IPC protocol version */
+const PROTOCOL_VERSION = 1;
+//#endregion
+//#region src/reconciliation.ts
+const log = logger.child({ component: "Reconciliation" });
+var ReconciliationEngine = class {
+	constructor(manager) {
+		this.manager = manager;
+	}
+	/**
+	* Reconcile local state against desired state from cloud.
+	*/
+	async reconcile(desiredIntegrations) {
+		const report = {
+			results: [],
+			installed: [],
+			activated: [],
+			deactivated: [],
+			uninstalled: [],
+			errors: []
+		};
+		let localIntegrations;
+		try {
+			localIntegrations = await this.manager.getInstalledIntegrations();
+		} catch (err) {
+			log.error({ err }, "Failed to get local integrations");
+			localIntegrations = [];
+		}
+		const localMap = new Map(localIntegrations.map((i) => [i.id, i]));
+		const desiredMap = new Map(desiredIntegrations.map((d) => [d.integrationId, d]));
+		for (const desired of desiredIntegrations) if (desired.desiredStatus === "active") await this.reconcileActive(desired, localMap.get(desired.integrationId), report);
+		else await this.reconcileRemoved(desired.integrationId, localMap.get(desired.integrationId), report);
+		for (const local of localIntegrations) if (!desiredMap.has(local.id)) await this.reconcileRemoved(local.id, local, report);
+		return report;
+	}
+	async reconcileActive(desired, local, report) {
+		const id = desired.integrationId;
+		try {
+			if (!local) {
+				log.info(`Installing ${id}@${desired.version}`);
+				await this.manager.install(id, desired.version, desired.config);
+				report.installed.push(id);
+				report.results.push({
+					integrationId: id,
+					action: "installed",
+					actualStatus: "active"
+				});
+				return;
+			}
+			if (local.version !== desired.version) {
+				log.info(`Upgrading ${id}: ${local.version} → ${desired.version}`);
+				try {
+					await this.manager.deactivate(id);
+					await this.manager.uninstall(id);
+				} catch {}
+				await this.manager.install(id, desired.version, desired.config);
+				report.installed.push(id);
+				report.results.push({
+					integrationId: id,
+					action: "installed",
+					actualStatus: "active"
+				});
+				return;
+			}
+			if (local.status !== "active") {
+				log.info(`Activating ${id}`);
+				await this.manager.activate(id);
+				report.activated.push(id);
+				report.results.push({
+					integrationId: id,
+					action: "activated",
+					actualStatus: "active"
+				});
+				return;
+			}
+			report.results.push({
+				integrationId: id,
+				action: "up_to_date",
+				actualStatus: "active"
+			});
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			log.error({ err }, `Error reconciling ${id}`);
+			report.errors.push({
+				integrationId: id,
+				error: message
+			});
+			report.results.push({
+				integrationId: id,
+				action: "error",
+				actualStatus: "error",
+				errorMessage: message
+			});
+		}
+	}
+	async reconcileRemoved(id, local, report) {
+		if (!local) {
+			report.results.push({
+				integrationId: id,
+				action: "up_to_date",
+				actualStatus: "inactive"
+			});
+			return;
+		}
+		try {
+			log.info(`Removing ${id}`);
+			if (local.status === "active") {
+				await this.manager.deactivate(id);
+				report.deactivated.push(id);
+			}
+			await this.manager.uninstall(id);
+			report.uninstalled.push(id);
+			report.results.push({
+				integrationId: id,
+				action: "uninstalled",
+				actualStatus: "inactive"
+			});
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			log.error({ err }, `Error removing ${id}`);
+			report.errors.push({
+				integrationId: id,
+				error: message
+			});
+			report.results.push({
+				integrationId: id,
+				action: "error",
+				actualStatus: "error",
+				errorMessage: message
+			});
+		}
+	}
+};
+//#endregion
+//#region src/cloud-client.ts
+/**
+* Cloud WebSocket client — connects to Alfe cloud gateway (Fly.io).
+*
+* Adapted from gateway-relay-plugin.ts CloudRelay class.
+* Uses the cloud protocol: SERVICE_REGISTER / COMMAND / COMMAND_ACK / PING / PONG.
+*
+* Auth: user's api_key as Bearer token in WS upgrade header.
+*/
+var CloudClient = class {
+	ws = null;
+	backoffMs = 1e3;
+	closed = false;
+	registered = false;
+	pingTimer = null;
+	lastPong = 0;
+	config;
+	onCommand = null;
+	onConnectionChange = null;
+	reconciliationEngine = null;
+	constructor(config) {
+		this.config = config;
+	}
+	get isConnected() {
+		return this.registered && this.ws?.readyState === WebSocket.OPEN;
+	}
+	/**
+	* Set the handler for incoming COMMAND messages from cloud.
+	*/
+	setCommandHandler(handler) {
+		this.onCommand = handler;
+	}
+	/**
+	* Set a callback for connection state changes.
+	*/
+	setConnectionChangeHandler(handler) {
+		this.onConnectionChange = handler;
+	}
+	/**
+	* Set the integration manager for reconciliation.
+	* When set, the cloud client will handle DESIRED_STATE messages automatically.
+	*/
+	setIntegrationManager(manager) {
+		this.reconciliationEngine = new ReconciliationEngine(manager);
+	}
+	/**
+	* Start the cloud connection with auto-reconnect.
+	*/
+	start() {
+		this.closed = false;
+		this.doConnect();
+	}
+	/**
+	* Stop the cloud connection and all timers.
+	*/
+	stop() {
+		this.closed = true;
+		this.stopPingTimer();
+		if (this.ws) {
+			try {
+				this.ws.close(1e3, "Daemon shutting down");
+			} catch {}
+			this.ws = null;
+		}
+		this.registered = false;
+	}
+	/**
+	* Get connection latency (time since last pong).
+	* Returns -1 if no pong received yet.
+	*/
+	getLatencyMs() {
+		if (this.lastPong === 0) return -1;
+		return Date.now() - this.lastPong;
+	}
+	doConnect() {
+		if (this.closed) return;
+		logger.info({ url: this.config.wsUrl }, "Connecting to cloud gateway...");
+		this.ws = new WebSocket(this.config.wsUrl, {
+			headers: { authorization: `Bearer ${this.config.apiKey}` },
+			maxPayload: 10 * 1024 * 1024
+		});
+		this.ws.on("open", () => {
+			logger.info("Cloud WebSocket connected");
+			this.backoffMs = 1e3;
+			this.sendRegister();
+		});
+		this.ws.on("message", (data) => {
+			const text = Buffer.isBuffer(data) ? data.toString("utf-8") : Buffer.from(data).toString("utf-8");
+			this.handleMessage(text);
+		});
+		this.ws.on("ping", () => {
+			this.ws?.pong();
+		});
+		this.ws.on("close", (code, reason) => {
+			logger.warn({
+				code,
+				reason: reason.toString()
+			}, "Cloud WebSocket disconnected");
+			this.registered = false;
+			this.stopPingTimer();
+			this.onConnectionChange?.(false);
+			this.scheduleReconnect();
+		});
+		this.ws.on("error", (err) => {
+			logger.error({ err: err.message }, "Cloud WebSocket error");
+		});
+	}
+	sendRegister() {
+		const msg = createServiceRegister(this.config.agentId);
+		this.send(msg);
+		logger.info({ serviceId: msg.serviceId }, "Sent SERVICE_REGISTER");
+	}
+	async handleMessage(raw) {
+		const msg = parseMessage(raw);
+		if (!msg) {
+			logger.warn("Cloud: received invalid JSON");
+			return;
+		}
+		if (isCloudServiceAck(msg)) {
+			this.handleServiceAck(msg);
+			return;
+		}
+		if (isCloudPing(msg)) {
+			this.send({ type: "PONG" });
+			this.lastPong = Date.now();
+			return;
+		}
+		if (isCloudDesiredState(msg)) {
+			await this.handleDesiredState(msg);
+			return;
+		}
+		if (isCloudCommand(msg)) {
+			await this.handleCommand(msg);
+			return;
+		}
+		logger.debug({ msg }, "Cloud: unhandled message");
+	}
+	handleServiceAck(ack) {
+		if (ack.status === "ok") {
+			logger.info("Cloud: registered successfully ✅");
+			this.registered = true;
+			this.startPingTimer();
+			this.onConnectionChange?.(true);
+		} else {
+			logger.error({ message: ack.message }, "Cloud: registration failed");
+			this.ws?.close(1008, "Registration rejected");
+		}
+	}
+	async handleCommand(command) {
+		logger.info({
+			commandId: command.commandId,
+			command: command.command,
+			agentId: command.agentId
+		}, "Cloud: received COMMAND");
+		if (!this.onCommand) {
+			const ack = {
+				type: "COMMAND_ACK",
+				commandId: command.commandId,
+				status: "error",
+				result: {
+					code: "NO_HANDLER",
+					message: "No command handler registered"
+				}
+			};
+			this.send(ack);
+			return;
+		}
+		try {
+			const ack = await this.onCommand(command);
+			this.send(ack);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			logger.error({
+				err: message,
+				commandId: command.commandId
+			}, "Cloud: command handler failed");
+			const ack = {
+				type: "COMMAND_ACK",
+				commandId: command.commandId,
+				status: "error",
+				result: {
+					code: "HANDLER_ERROR",
+					message
+				}
+			};
+			this.send(ack);
+		}
+	}
+	async handleDesiredState(msg) {
+		logger.info({ count: msg.integrations.length }, "Cloud: received DESIRED_STATE");
+		if (!this.reconciliationEngine) {
+			logger.warn("Cloud: DESIRED_STATE received but no integration manager set — skipping reconciliation");
+			return;
+		}
+		try {
+			const report = await this.reconciliationEngine.reconcile(msg.integrations);
+			logger.info({
+				installed: report.installed.length,
+				activated: report.activated.length,
+				deactivated: report.deactivated.length,
+				uninstalled: report.uninstalled.length,
+				errors: report.errors.length
+			}, "Cloud: reconciliation complete");
+			const reportMsg = createReconciliationReport(report.results);
+			this.send(reportMsg);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			logger.error({ err: message }, "Cloud: reconciliation failed");
+		}
+	}
+	send(msg) {
+		if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify(msg));
+	}
+	startPingTimer() {
+		this.stopPingTimer();
+		this.pingTimer = setInterval(() => {
+			if (this.ws?.readyState === WebSocket.OPEN) {
+				if (this.lastPong > 0 && Date.now() - this.lastPong > 9e4) {
+					logger.warn("Cloud: no ping received in 90s — reconnecting");
+					this.ws.close(4e3, "Ping timeout");
+					return;
+				}
+			}
+		}, 3e4);
+	}
+	stopPingTimer() {
+		if (this.pingTimer) {
+			clearInterval(this.pingTimer);
+			this.pingTimer = null;
+		}
+	}
+	scheduleReconnect() {
+		if (this.closed) return;
+		const delay = this.backoffMs;
+		this.backoffMs = Math.min(this.backoffMs * 2, 3e4);
+		logger.info({ delayMs: delay }, "Cloud: reconnecting...");
+		setTimeout(() => {
+			this.doConnect();
+		}, delay);
+	}
+};
+//#endregion
+//#region src/ipc-server.ts
+/**
+* IPC Server — Unix socket server for local plugin connections.
+*
+* Plugins connect to ~/.alfe/gateway.sock and speak the IPC protocol:
+*   Request:  { type: 'req', id, method, params }
+*   Response: { id, ok, payload?, error? }
+*   Event:    { type: 'event', event, payload }
+*
+* Each connected plugin registers with its name/version and receives
+* commands from the daemon (forwarded from cloud).
+*/
+var IPCServer = class {
+	server = null;
+	connections = /* @__PURE__ */ new Map();
+	socketPath;
+	requestHandler = null;
+	constructor(socketPath) {
+		this.socketPath = socketPath;
+	}
+	/**
+	* Set the handler for incoming IPC requests from plugins.
+	*/
+	setRequestHandler(handler) {
+		this.requestHandler = handler;
+	}
+	/**
+	* Start listening on the Unix socket.
+	*/
+	async start() {
+		try {
+			unlinkSync(this.socketPath);
+		} catch {}
+		return new Promise((resolve, reject) => {
+			this.server = createServer((socket) => {
+				this.handleConnection(socket);
+			});
+			this.server.on("error", (err) => {
+				logger.error({ err: err.message }, "IPC server error");
+				reject(err);
+			});
+			this.server.listen(this.socketPath, () => {
+				try {
+					chmodSync(this.socketPath, 384);
+				} catch (err) {
+					logger.warn({ err }, "Failed to chmod socket");
+				}
+				logger.info({ path: this.socketPath }, "IPC server listening");
+				resolve();
+			});
+		});
+	}
+	/**
+	* Stop the IPC server and disconnect all plugins.
+	*/
+	async stop() {
+		for (const conn of this.connections.values()) try {
+			this.sendEvent(conn, "daemon.shutdown", { reason: "daemon stopping" });
+			conn.socket.end();
+		} catch {}
+		return new Promise((resolve) => {
+			if (!this.server) {
+				resolve();
+				return;
+			}
+			this.server.close(() => {
+				try {
+					unlinkSync(this.socketPath);
+				} catch {}
+				logger.info("IPC server stopped");
+				resolve();
+			});
+			for (const conn of this.connections.values()) conn.socket.destroy();
+			this.connections.clear();
+		});
+	}
+	/**
+	* Send an IPC request to a specific plugin and wait for response.
+	*/
+	async sendRequest(pluginId, method, params, timeoutMs = 3e4) {
+		const conn = this.connections.get(pluginId);
+		if (!conn?.info) return {
+			id: "",
+			ok: false,
+			error: {
+				code: "PLUGIN_NOT_CONNECTED",
+				message: `Plugin ${pluginId} not connected`
+			}
+		};
+		const id = pluginConnectionId();
+		const request = {
+			type: "req",
+			id,
+			method,
+			params
+		};
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				conn.pending.delete(id);
+				resolve({
+					id,
+					ok: false,
+					error: {
+						code: "TIMEOUT",
+						message: `Request ${method} timed out after ${String(timeoutMs)}ms`
+					}
+				});
+			}, timeoutMs);
+			conn.pending.set(id, {
+				resolve,
+				reject,
+				timer
+			});
+			try {
+				conn.socket.write(JSON.stringify(request) + "\n");
+			} catch (err) {
+				clearTimeout(timer);
+				conn.pending.delete(id);
+				resolve({
+					id,
+					ok: false,
+					error: {
+						code: "SEND_FAILED",
+						message: `Failed to send to plugin: ${err instanceof Error ? err.message : String(err)}`
+					}
+				});
+			}
+		});
+	}
+	/**
+	* Send an IPC request to ALL registered plugins.
+	* Returns responses keyed by plugin ID.
+	*/
+	async broadcastRequest(method, params, timeoutMs = 3e4) {
+		const results = /* @__PURE__ */ new Map();
+		const registered = this.getRegisteredPlugins();
+		await Promise.all(registered.map(async ([pluginId]) => {
+			const response = await this.sendRequest(pluginId, method, params, timeoutMs);
+			results.set(pluginId, response);
+		}));
+		return results;
+	}
+	/**
+	* Send an event to a specific plugin (fire-and-forget).
+	*/
+	sendEventToPlugin(pluginId, event, payload) {
+		const conn = this.connections.get(pluginId);
+		if (!conn) return false;
+		return this.sendEvent(conn, event, payload);
+	}
+	/**
+	* Broadcast an event to all connected plugins.
+	*/
+	broadcastEvent(event, payload) {
+		for (const conn of this.connections.values()) if (conn.info) this.sendEvent(conn, event, payload);
+	}
+	/**
+	* Get all registered plugins and their info.
+	*/
+	getRegisteredPlugins() {
+		const plugins = [];
+		for (const [id, conn] of this.connections) if (conn.info) plugins.push([id, conn.info]);
+		return plugins;
+	}
+	/**
+	* Get number of connected plugins (including unregistered).
+	*/
+	get connectionCount() {
+		return this.connections.size;
+	}
+	/**
+	* Get number of registered plugins.
+	*/
+	get registeredCount() {
+		let count = 0;
+		for (const conn of this.connections.values()) if (conn.info) count++;
+		return count;
+	}
+	handleConnection(socket) {
+		const connId = pluginConnectionId();
+		const conn = {
+			id: connId,
+			socket,
+			info: null,
+			buffer: "",
+			pending: /* @__PURE__ */ new Map()
+		};
+		this.connections.set(connId, conn);
+		logger.info({ connId }, "IPC: new connection");
+		socket.on("data", (data) => {
+			conn.buffer += data.toString();
+			this.processBuffer(conn);
+		});
+		socket.on("close", () => {
+			logger.info({
+				connId,
+				plugin: conn.info?.name
+			}, "IPC: connection closed");
+			for (const [, pending] of conn.pending) {
+				clearTimeout(pending.timer);
+				pending.resolve({
+					id: "",
+					ok: false,
+					error: {
+						code: "DISCONNECTED",
+						message: "Plugin disconnected"
+					}
+				});
+			}
+			this.connections.delete(connId);
+		});
+		socket.on("error", (err) => {
+			logger.error({
+				connId,
+				err: err.message
+			}, "IPC: socket error");
+		});
+	}
+	processBuffer(conn) {
+		let newlineIdx;
+		while ((newlineIdx = conn.buffer.indexOf("\n")) !== -1) {
+			const line = conn.buffer.slice(0, newlineIdx).trim();
+			conn.buffer = conn.buffer.slice(newlineIdx + 1);
+			if (!line) continue;
+			let parsed;
+			try {
+				parsed = JSON.parse(line);
+			} catch {
+				logger.warn({ connId: conn.id }, "IPC: invalid JSON from plugin");
+				continue;
+			}
+			if (isIPCResponse(parsed)) {
+				this.handlePluginResponse(conn, parsed);
+				continue;
+			}
+			if (isIPCRequest(parsed)) {
+				this.handlePluginRequest(conn, parsed);
+				continue;
+			}
+			logger.debug({
+				connId: conn.id,
+				msg: parsed
+			}, "IPC: unhandled message");
+		}
+	}
+	handlePluginResponse(conn, response) {
+		const pending = conn.pending.get(response.id);
+		if (!pending) return;
+		clearTimeout(pending.timer);
+		conn.pending.delete(response.id);
+		pending.resolve(response);
+	}
+	async handlePluginRequest(conn, request) {
+		if (conn.info) conn.info.lastSeen = Date.now();
+		if (request.method === "register") {
+			this.handleRegister(conn, request);
+			return;
+		}
+		if (this.requestHandler) try {
+			const result = await this.requestHandler(request.method, request.params, conn.id);
+			const response = result.ok ? createIPCResponse(request.id, result.payload) : createIPCError(request.id, result.error?.code ?? "UNKNOWN", result.error?.message ?? "Unknown error");
+			this.sendResponse(conn, response);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			this.sendResponse(conn, createIPCError(request.id, "INTERNAL", message));
+		}
+		else this.sendResponse(conn, createIPCError(request.id, "NO_HANDLER", `No handler for method: ${request.method}`));
+	}
+	handleRegister(conn, request) {
+		const { name, version, protocolVersion, capabilities } = request.params;
+		if (!name || !version) {
+			this.sendResponse(conn, createIPCError(request.id, "INVALID_REGISTER", "name and version are required"));
+			return;
+		}
+		if (protocolVersion !== void 0 && protocolVersion !== 1) {
+			this.sendResponse(conn, createIPCError(request.id, "PROTOCOL_MISMATCH", `Unsupported protocol version ${String(protocolVersion)}. Server supports v${String(1)}.`));
+			return;
+		}
+		conn.info = {
+			name,
+			version,
+			protocolVersion: protocolVersion ?? 1,
+			capabilities: capabilities ?? [],
+			connectedAt: Date.now(),
+			lastSeen: Date.now()
+		};
+		logger.info({
+			connId: conn.id,
+			plugin: name,
+			version,
+			capabilities
+		}, "IPC: plugin registered");
+		this.sendResponse(conn, createIPCResponse(request.id, {
+			status: "registered",
+			daemonVersion: "0.1.0",
+			protocolVersion: 1
+		}));
+	}
+	sendResponse(conn, response) {
+		try {
+			conn.socket.write(JSON.stringify(response) + "\n");
+		} catch (err) {
+			logger.error({
+				connId: conn.id,
+				err
+			}, "IPC: failed to send response");
+		}
+	}
+	sendEvent(conn, event, payload) {
+		try {
+			const msg = createIPCEvent(event, payload);
+			conn.socket.write(JSON.stringify(msg) + "\n");
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+//#region src/command-queue.ts
+const DEFAULT_TTL_MS = 300 * 1e3;
+var CommandQueue = class {
+	queues = /* @__PURE__ */ new Map();
+	ttlMs;
+	gcTimer = null;
+	constructor(ttlMs = DEFAULT_TTL_MS) {
+		this.ttlMs = ttlMs;
+	}
+	/**
+	* Start periodic garbage collection of expired commands.
+	*/
+	startGC(intervalMs = 3e4) {
+		this.stopGC();
+		this.gcTimer = setInterval(() => this.purgeExpired(), intervalMs);
+	}
+	/**
+	* Stop periodic garbage collection.
+	*/
+	stopGC() {
+		if (this.gcTimer) {
+			clearInterval(this.gcTimer);
+			this.gcTimer = null;
+		}
+	}
+	/**
+	* Enqueue a command for a specific service.
+	*/
+	enqueue(serviceId, request, commandId) {
+		let queue = this.queues.get(serviceId);
+		if (!queue) {
+			queue = [];
+			this.queues.set(serviceId, queue);
+		}
+		queue.push({
+			request,
+			queuedAt: Date.now(),
+			commandId
+		});
+	}
+	/**
+	* Drain all pending (non-expired) commands for a service.
+	* Returns them in order and removes them from the queue.
+	*/
+	drain(serviceId) {
+		const queue = this.queues.get(serviceId);
+		if (!queue || queue.length === 0) return [];
+		const now = Date.now();
+		const valid = queue.filter((cmd) => now - cmd.queuedAt < this.ttlMs);
+		this.queues.delete(serviceId);
+		return valid;
+	}
+	/**
+	* Get the number of pending commands for a service.
+	*/
+	pendingCount(serviceId) {
+		const queue = this.queues.get(serviceId);
+		if (!queue) return 0;
+		const now = Date.now();
+		return queue.filter((cmd) => now - cmd.queuedAt < this.ttlMs).length;
+	}
+	/**
+	* Get total pending commands across all services.
+	*/
+	totalPending() {
+		let total = 0;
+		for (const [serviceId] of this.queues) total += this.pendingCount(serviceId);
+		return total;
+	}
+	/**
+	* Remove expired commands from all queues.
+	*/
+	purgeExpired() {
+		const now = Date.now();
+		let purged = 0;
+		for (const [serviceId, queue] of this.queues) {
+			const before = queue.length;
+			const remaining = queue.filter((cmd) => now - cmd.queuedAt < this.ttlMs);
+			if (remaining.length === 0) this.queues.delete(serviceId);
+			else this.queues.set(serviceId, remaining);
+			purged += before - remaining.length;
+		}
+		return purged;
+	}
+	/**
+	* Clear all queues.
+	*/
+	clear() {
+		this.queues.clear();
+	}
+	/**
+	* Get all service IDs that have pending commands.
+	*/
+	serviceIds() {
+		return Array.from(this.queues.keys());
+	}
+};
+//#endregion
+//#region src/process-manager.ts
+/**
+* Process management — launchd/systemd service installation.
+*
+* Generates and installs user-space service units for auto-start on boot.
+* No root required — uses user agents (Mac) or user units (Linux).
+*/
+const LAUNCHD_LABEL = "ai.alfe.gateway";
+const SYSTEMD_SERVICE = "alfe-gateway";
+function getLaunchdPlistPath() {
+	return join(homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+}
+function getSystemdServicePath() {
+	return join(homedir(), ".config", "systemd", "user", `${SYSTEMD_SERVICE}.service`);
+}
+/**
+* Resolve the path to the gateway binary.
+*/
+function getGatewayBinPath() {
+	const globalBin = process.env.ALFE_GATEWAY_BIN;
+	if (globalBin) return globalBin;
+	const builtBin = join(import.meta.dirname, "..", "bin", "gateway.js");
+	if (existsSync(builtBin)) return builtBin;
+	return "alfe-gateway";
+}
+function getNodePath() {
+	try {
+		return execSync("which node", { encoding: "utf-8" }).trim();
+	} catch {
+		return "/usr/local/bin/node";
+	}
+}
+/**
+* Generate a launchd plist for macOS.
+*/
+function generateLaunchdPlist() {
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${getNodePath()}</string>
+    <string>${getGatewayBinPath()}</string>
+    <string>daemon</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>${join(homedir(), ".alfe", "logs", "gateway.log")}</string>
+  <key>StandardErrorPath</key>
+  <string>${join(homedir(), ".alfe", "logs", "gateway.err.log")}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>NODE_ENV</key>
+    <string>production</string>
+    <key>PATH</key>
+    <string>/usr/local/bin:/usr/bin:/bin:${join(homedir(), ".local", "bin")}</string>
+  </dict>
+</dict>
+</plist>`;
+}
+/**
+* Generate a systemd user unit for Linux.
+*/
+function generateSystemdUnit() {
+	return `[Unit]
+Description=Alfe Gateway Daemon
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${getNodePath()} ${getGatewayBinPath()} daemon
+Restart=always
+RestartSec=10
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=default.target`;
+}
+/**
+* Install the service unit for the current platform.
+*/
+async function installService() {
+	const platform = process.platform;
+	if (platform === "darwin") return installLaunchd();
+	if (platform === "linux") return installSystemd();
+	throw new Error(`Unsupported platform: ${platform}. Only macOS and Linux are supported.`);
+}
+/**
+* Uninstall the service unit for the current platform.
+*/
+async function uninstallService() {
+	const platform = process.platform;
+	if (platform === "darwin") return uninstallLaunchd();
+	if (platform === "linux") return uninstallSystemd();
+	throw new Error(`Unsupported platform: ${platform}`);
+}
+async function installLaunchd() {
+	const plistPath = getLaunchdPlistPath();
+	await mkdir(join(homedir(), "Library", "LaunchAgents"), { recursive: true });
+	await writeFile(plistPath, generateLaunchdPlist(), "utf-8");
+	logger.info({ path: plistPath }, "Wrote launchd plist");
+	try {
+		execSync(`launchctl load ${plistPath}`, { stdio: "pipe" });
+	} catch {}
+	return `Installed: ${plistPath}\nService will start on boot and restart on crash.`;
+}
+async function uninstallLaunchd() {
+	const plistPath = getLaunchdPlistPath();
+	try {
+		execSync(`launchctl unload ${plistPath}`, { stdio: "pipe" });
+	} catch {}
+	try {
+		await unlink(plistPath);
+	} catch {}
+	return `Uninstalled: ${plistPath}`;
+}
+async function installSystemd() {
+	const unitPath = getSystemdServicePath();
+	await mkdir(join(homedir(), ".config", "systemd", "user"), { recursive: true });
+	await writeFile(unitPath, generateSystemdUnit(), "utf-8");
+	logger.info({ path: unitPath }, "Wrote systemd unit");
+	try {
+		execSync("systemctl --user daemon-reload", { stdio: "pipe" });
+		execSync(`systemctl --user enable ${SYSTEMD_SERVICE}`, { stdio: "pipe" });
+	} catch {}
+	return `Installed: ${unitPath}\nService enabled for user session.`;
+}
+async function uninstallSystemd() {
+	const unitPath = getSystemdServicePath();
+	try {
+		execSync(`systemctl --user disable ${SYSTEMD_SERVICE}`, { stdio: "pipe" });
+		execSync(`systemctl --user stop ${SYSTEMD_SERVICE}`, { stdio: "pipe" });
+	} catch {}
+	try {
+		await unlink(unitPath);
+	} catch {}
+	try {
+		execSync("systemctl --user daemon-reload", { stdio: "pipe" });
+	} catch {}
+	return `Uninstalled: ${unitPath}`;
+}
+/**
+* Write the current process PID to the PID file.
+*/
+async function writePidFile() {
+	await writeFile(PID_PATH, String(process.pid), "utf-8");
+}
+/**
+* Remove the PID file.
+*/
+async function removePidFile() {
+	try {
+		await unlink(PID_PATH);
+	} catch {}
+}
+/**
+* Check if a daemon is already running.
+* Returns the PID if alive, null if not running.
+*/
+async function checkExistingDaemon() {
+	if (!existsSync(PID_PATH)) return null;
+	try {
+		const pidStr = await readFile(PID_PATH, "utf-8");
+		const pid = parseInt(pidStr.trim(), 10);
+		if (isNaN(pid)) {
+			await removePidFile();
+			return null;
+		}
+		try {
+			process.kill(pid, 0);
+			return pid;
+		} catch {
+			await removePidFile();
+			return null;
+		}
+	} catch {
+		return null;
+	}
+}
+/**
+* Send SIGTERM to an existing daemon process.
+*/
+async function stopExistingDaemon() {
+	const pid = await checkExistingDaemon();
+	if (!pid) return false;
+	try {
+		process.kill(pid, "SIGTERM");
+		for (let i = 0; i < 50; i++) {
+			await new Promise((r) => setTimeout(r, 100));
+			try {
+				process.kill(pid, 0);
+			} catch {
+				await removePidFile();
+				return true;
+			}
+		}
+		process.kill(pid, "SIGKILL");
+		await removePidFile();
+		return true;
+	} catch {
+		await removePidFile();
+		return false;
+	}
+}
+//#endregion
+//#region src/daemon.ts
+/**
+* Alfe Gateway Daemon — main entry point.
+*
+* Starts all subsystems:
+*   1. Load config + resolve agent identity
+*   2. Check for existing daemon (PID file)
+*   3. Start IPC server (Unix socket)
+*   4. Start cloud client (WebSocket to Fly.io)
+*   5. Wire up protocol translation (cloud COMMAND → IPC request)
+*   6. Start command queue GC
+*   7. Write PID file
+*   8. Handle graceful shutdown
+*/
+let config;
+let cloudClient;
+let ipcServer = null;
+let commandQueue;
+let startedAt;
+let integrationManager;
+let cloudConnected = false;
+let shuttingDown = false;
+async function startDaemon() {
+	startedAt = Date.now();
+	const managed = isManagedMode();
+	logger.info({ managed }, "Starting Alfe Gateway Daemon...");
+	if (!managed) {
+		await mkdir(join(homedir(), ".alfe"), { recursive: true });
+		const existingPid = await checkExistingDaemon();
+		if (existingPid) {
+			logger.error({ pid: existingPid }, "Daemon already running. Use `alfe gateway stop` first.");
+			process.exit(1);
+		}
+	}
+	try {
+		config = await loadDaemonConfig();
+		logger.info({
+			agentId: config.agentId,
+			orgId: config.orgId,
+			wsUrl: config.gatewayWsUrl
+		}, "Config loaded, identity resolved");
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		logger.error({ err: message }, "Failed to load config");
+		process.exit(1);
+	}
+	commandQueue = new CommandQueue();
+	commandQueue.startGC();
+	if (!managed) {
+		ipcServer = new IPCServer(config.socketPath);
+		ipcServer.setRequestHandler(handlePluginRequest);
+		try {
+			await ipcServer.start();
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			logger.error({ err: message }, "Failed to start IPC server");
+			process.exit(1);
+		}
+	}
+	cloudClient = new CloudClient({
+		wsUrl: config.gatewayWsUrl,
+		apiKey: config.apiKey,
+		agentId: config.agentId
+	});
+	cloudClient.setCommandHandler(handleCloudCommand);
+	cloudClient.setConnectionChangeHandler((connected) => {
+		cloudConnected = connected;
+		logger.info({ connected }, "Cloud connection state changed");
+		if (ipcServer) ipcServer.broadcastEvent("cloud.status", { connected });
+	});
+	const runtimeAppliers = /* @__PURE__ */ new Map();
+	for (const [name, runtimeCfg] of Object.entries(config.runtimes)) if (name === "openclaw") {
+		runtimeAppliers.set(name, new OpenClawApplier({ workspace: runtimeCfg.workspace }));
+		logger.info({
+			runtime: name,
+			workspace: runtimeCfg.workspace
+		}, "Registered OpenClaw runtime applier");
+	} else logger.warn({ runtime: name }, "Unknown runtime type — skipping");
+	integrationManager = new IntegrationManager({
+		logger,
+		runtimeAppliers
+	});
+	const integrationAdapter = new IntegrationManagerAdapter(integrationManager);
+	cloudClient.setIntegrationManager(integrationAdapter);
+	cloudClient.start();
+	if (!managed) await writePidFile();
+	const shutdown = async (signal) => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		logger.info({ signal }, "Shutting down...");
+		if (ipcServer) await ipcServer.stop();
+		cloudClient.stop();
+		commandQueue.stopGC();
+		if (!managed) await removePidFile();
+		logger.info("Daemon stopped");
+		process.exit(0);
+	};
+	process.on("SIGTERM", () => {
+		shutdown("SIGTERM");
+	});
+	process.on("SIGINT", () => {
+		shutdown("SIGINT");
+	});
+	logger.info({
+		pid: process.pid,
+		socket: config.socketPath || "(managed)",
+		cloud: config.gatewayWsUrl,
+		agentId: config.agentId
+	}, "Alfe Gateway Daemon started ✅");
+}
+async function handleCloudCommand(command) {
+	const ipcRequest = cloudCommandToIPCRequest(command);
+	if (!ipcRequest) {
+		logger.warn({ command: command.command }, "Unrecognized cloud command");
+		return {
+			type: "COMMAND_ACK",
+			commandId: command.commandId,
+			status: "error",
+			result: {
+				code: "UNKNOWN_COMMAND",
+				message: `Unrecognized command: ${command.command}`
+			}
+		};
+	}
+	const plugins = ipcServer?.getRegisteredPlugins() ?? [];
+	if (plugins.length === 0) {
+		logger.info({
+			commandId: command.commandId,
+			command: command.command
+		}, "No plugins connected — queuing command");
+		commandQueue.enqueue("_default", ipcRequest, command.commandId);
+		return {
+			type: "COMMAND_ACK",
+			commandId: command.commandId,
+			status: "ok",
+			result: {
+				queued: true,
+				message: "Command queued — no plugins connected"
+			}
+		};
+	}
+	const [pluginId] = plugins[0];
+	if (!ipcServer) return {
+		type: "COMMAND_ACK",
+		commandId: command.commandId,
+		status: "error",
+		result: {
+			code: "NO_IPC",
+			message: "IPC server not available"
+		}
+	};
+	try {
+		const response = await ipcServer.sendRequest(pluginId, ipcRequest.method, ipcRequest.params, 3e4);
+		return ipcResponseToCloudAck(command.commandId, response);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return {
+			type: "COMMAND_ACK",
+			commandId: command.commandId,
+			status: "error",
+			result: {
+				code: "PLUGIN_ERROR",
+				message
+			}
+		};
+	}
+}
+function handlePluginRequest(method, params, pluginId) {
+	switch (method) {
+		case "status": return Promise.resolve(handleStatus());
+		case "integration.list": return Promise.resolve(handleIntegrationList());
+		case "integration.report": return Promise.resolve(handleIntegrationReport(params, pluginId));
+		default: return Promise.resolve({
+			ok: false,
+			error: {
+				code: "UNKNOWN_METHOD",
+				message: `Unknown method: ${method}`
+			}
+		});
+	}
+}
+function handleStatus() {
+	return {
+		ok: true,
+		payload: {
+			daemon: {
+				status: "running",
+				pid: process.pid,
+				uptime: (Date.now() - startedAt) / 1e3,
+				version: "0.1.0"
+			},
+			cloud: {
+				status: cloudConnected ? "connected" : "disconnected",
+				latencyMs: cloudClient.getLatencyMs()
+			},
+			plugins: (ipcServer?.getRegisteredPlugins() ?? []).map(([, info]) => ({
+				name: info.name,
+				version: info.version,
+				capabilities: info.capabilities,
+				connectedAt: info.connectedAt,
+				lastSeen: info.lastSeen
+			})),
+			commandQueue: { totalPending: commandQueue.totalPending() }
+		}
+	};
+}
+function handleIntegrationList() {
+	return {
+		ok: true,
+		payload: { integrations: integrationManager.list() }
+	};
+}
+function handleIntegrationReport(params, pluginId) {
+	const { name, status, detail } = params;
+	if (!name || !status) return {
+		ok: false,
+		error: {
+			code: "INVALID_PARAMS",
+			message: "name and status are required"
+		}
+	};
+	logger.info({
+		pluginId,
+		integration: name,
+		status,
+		detail
+	}, "Integration status report");
+	return {
+		ok: true,
+		payload: { acknowledged: true }
+	};
+}
+//#endregion
+//#region src/health.ts
+/**
+* Health reporting — used by `alfe doctor` and `alfe gateway status`.
+*
+* Connects to the daemon's IPC socket and queries health information.
+* Works even when the daemon is the only thing running (OpenClaw can be down).
+*/
+/**
+* Query daemon health via IPC socket.
+* Used by `alfe doctor` and `alfe gateway status`.
+*/
+async function queryDaemonHealth(socketPath, timeoutMs = 5e3) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			socket.destroy();
+			reject(/* @__PURE__ */ new Error("Health check timed out"));
+		}, timeoutMs);
+		let buffer = "";
+		const requestId = randomUUID();
+		const socket = createConnection(socketPath, () => {
+			const request = JSON.stringify({
+				type: "req",
+				id: requestId,
+				method: "status",
+				params: {}
+			}) + "\n";
+			socket.write(request);
+		});
+		socket.on("data", (data) => {
+			buffer += data.toString();
+			const newlineIdx = buffer.indexOf("\n");
+			if (newlineIdx === -1) return;
+			const line = buffer.slice(0, newlineIdx).trim();
+			buffer = buffer.slice(newlineIdx + 1);
+			clearTimeout(timer);
+			socket.end();
+			try {
+				const response = JSON.parse(line);
+				if (response.ok && response.payload) resolve(response.payload);
+				else reject(new Error(response.error?.message ?? "Health check failed"));
+			} catch {
+				reject(/* @__PURE__ */ new Error("Invalid health response"));
+			}
+		});
+		socket.on("error", (err) => {
+			clearTimeout(timer);
+			if (err.code === "ECONNREFUSED" || err.code === "ENOENT") resolve({
+				daemon: { status: "stopped" },
+				cloud: { status: "unknown" },
+				plugins: [],
+				commandQueue: { totalPending: 0 }
+			});
+			else reject(err);
+		});
+	});
+}
+/**
+* Format health info for terminal display.
+*/
+function formatHealthReport(health) {
+	const lines = [];
+	const daemonIcon = health.daemon.status === "running" ? "✓" : "✗";
+	lines.push(`  Gateway daemon      ${daemonIcon}  ${health.daemon.status}` + (health.daemon.uptime ? ` (uptime: ${formatUptime(health.daemon.uptime)})` : "") + (health.daemon.version ? ` v${health.daemon.version}` : ""));
+	const cloudIcon = health.cloud.status === "connected" ? "✓" : "✗";
+	lines.push(`  Cloud connection    ${cloudIcon}  ${health.cloud.status}` + (health.cloud.latencyMs !== void 0 ? ` (latency: ${String(health.cloud.latencyMs)}ms)` : ""));
+	if (health.plugins.length === 0) lines.push("  Plugins             –  none connected");
+	else for (const plugin of health.plugins) {
+		const lastSeenAgo = Date.now() - plugin.lastSeen;
+		lines.push(`  Plugin: ${plugin.name}  ✓  v${plugin.version} (last seen ${formatDuration(lastSeenAgo)} ago)`);
+	}
+	if (health.commandQueue.totalPending > 0) lines.push(`  Queued commands     ⚠  ${String(health.commandQueue.totalPending)} pending`);
+	return lines.join("\n");
+}
+function formatUptime(seconds) {
+	if (seconds < 60) return `${String(Math.round(seconds))}s`;
+	if (seconds < 3600) return `${String(Math.round(seconds / 60))}m`;
+	if (seconds < 86400) return `${String(Math.round(seconds / 3600))}h`;
+	return `${String(Math.round(seconds / 86400))}d`;
+}
+function formatDuration(ms) {
+	const seconds = ms / 1e3;
+	if (seconds < 60) return `${String(Math.round(seconds))}s`;
+	if (seconds < 3600) return `${String(Math.round(seconds / 60))}m`;
+	return `${String(Math.round(seconds / 3600))}h`;
+}
+//#endregion
+export { installService as a, PROTOCOL_VERSION as c, SOCKET_PATH as d, fetchAgentConfig as f, LOG_FILE as h, checkExistingDaemon as i, ALFE_DIR as l, resolveAgentIdentity as m, queryDaemonHealth as n, stopExistingDaemon as o, loadDaemonConfig as p, startDaemon as r, uninstallService as s, formatHealthReport as t, PID_PATH as u };