@alfe.ai/gateway 0.7.4 → 0.8.1

package/dist/sentry.js

@@ -0,0 +1,386 @@
+import { readConfig, resolveConfig } from "@alfe.ai/config";
+//#region src/sentry.ts
+/**
+* Agent-side error reporting (Sentry) for the Alfe CLI + gateway daemon.
+*
+* This module is the single Sentry bootstrap shared by both published
+* agent-side packages — `@alfe.ai/gateway` (the daemon) and `@alfe.ai/cli`
+* (which re-imports these helpers from `@alfe.ai/gateway`). It exists so
+* integration-installation failures on customer/managed VMs surface centrally
+* instead of silently rotting until someone SSHes into the box.
+*
+* Design constraints (see packages/gateway/DEVELOPING.md → "Error reporting"):
+*   - Errors only. No tracing/profiling (`tracesSampleRate: 0`, `sampleRate: 1`).
+*   - `@sentry/node` is lazy-imported so `alfe --version` doesn't pay for it.
+*   - Sentry can NEVER break the CLI/daemon — every entry point is try/catch'd.
+*   - The DSNs are baked as constants: published tarballs run on agent VMs and
+*     cannot read the repo's `config/config.ts`. That file's `SENTRY_DSNS`
+*     registry (keys `agentDaemon` + `cli`) mirrors them as the human reference.
+*   - Secrets are scrubbed in `beforeSend`; request/env payloads are dropped.
+*   - Opt-out via `ALFE_ERROR_REPORTING=0|false` or `errorReporting = false`
+*     in `~/.alfe/config.toml`. Default ON.
+*/
+/**
+* Baked per-surface Sentry DSNs (org `alfe-ai`). DSNs are public by design
+* (they only permit event ingestion). Mirrors of `config/config.ts` →
+* `SENTRY_DSNS.agentDaemon` / `SENTRY_DSNS.cli`. If you rotate a DSN, update
+* both places.
+*/
+const AGENT_DAEMON_SENTRY_DSN = "https://a47f010d8d39fb4350f913492189f283@o4511008239452160.ingest.us.sentry.io/4511679448547328";
+const CLI_SENTRY_DSN = "https://82dde4631336561f2fcc89d7531623de@o4511008239452160.ingest.us.sentry.io/4511679411191808";
+/**
+* Dedicated project for errors emitted BY the agent runtime child process
+* (OpenClaw/Hermes) — crashes, spawn failures, and error-looking output. Kept
+* separate from `agent-daemon` so runtime noise never drowns daemon issues.
+* Mirrors `SENTRY_DSNS.agentRuntime` in `config/config.ts`.
+*/
+const AGENT_RUNTIME_SENTRY_DSN = "https://feb7fb2e3b8e723aec518e74715bfa6d@o4511008239452160.ingest.us.sentry.io/4511683667558400";
+/**
+* MCP tool/server failures on agent VMs — reported by the daemon-hosted MCP
+* bundler (tool errors, child crashes, stderr output). Dedicated `local-mcp`
+* project for the locally-installed MCP surface: the cloud MCP Fly service
+* keeps the `mcp` project (`SENTRY_DSNS.mcp`), so planned daemon restarts
+* tearing down MCP children never pollute the remote service's signal.
+* The `source: agent-daemon` + `agentId` tags are kept for continuity.
+*/
+const AGENT_MCP_SENTRY_DSN = "https://b4c4b4e19135692206bacabcd12a7fd3@o4511008239452160.ingest.us.sentry.io/4511697094377472";
+/** Surface → Sentry project: `cli` and `agent-daemon` respectively. */
+const SURFACE_DSNS = {
+	cli: CLI_SENTRY_DSN,
+	daemon: AGENT_DAEMON_SENTRY_DSN
+};
+/** Held after a successful init so the capture helpers can run synchronously. */
+let sentry = null;
+/**
+* Additional bound clients (daemon surface only). The default client keeps the
+* daemon's own DSN; runtime child-process events and MCP failures are routed
+* to their own projects via explicitly-bound Scopes — the documented
+* multi-client pattern. `null` until `initAgentSentry({ surface: "daemon" })`
+* succeeds.
+*/
+let runtimeClient = null;
+let runtimeScope = null;
+let mcpClient = null;
+let mcpScope = null;
+/**
+* Map the configured API URL to a coarse environment tag. Best-effort — returns
+* `"unknown"` when no config is present yet (e.g. `alfe login` pre-setup).
+*/
+function deriveEnvironment() {
+	try {
+		const { apiUrl } = resolveConfig();
+		if (apiUrl.includes("api.dev.alfe.ai") || apiUrl.includes("dev.alfe.ai")) return "dev";
+		if (apiUrl.includes("api.test.alfe.ai")) return "test";
+		if (apiUrl.includes("api.demo.alfe.ai")) return "demo";
+		if (apiUrl.includes("api.alfe.ai")) return "prod";
+	} catch {}
+	return "unknown";
+}
+/** Active runtime (`openclaw`/`hermes`) from config, or undefined if unknown. */
+function deriveRuntime() {
+	try {
+		return resolveConfig().runtime;
+	} catch {
+		return;
+	}
+}
+/** True when the operator has opted out of error reporting. */
+function errorReportingDisabled() {
+	const env = process.env.ALFE_ERROR_REPORTING?.trim().toLowerCase();
+	if (env === "0" || env === "false") return true;
+	try {
+		if (readConfig().errorReporting === false) return true;
+	} catch {}
+	return false;
+}
+const KV_SECRET_RE = /(?<![A-Za-z0-9])([A-Za-z0-9_-]*(?:authorization|api[_-]?key|apikey|token|secret|password|passwd|bearer|credential)s?)(\s*[:=]\s*|\s+)("?)([^\s"']+)\3/gi;
+const URL_QUERY_SECRET_RE = /([?&](?:[A-Za-z0-9_-]*(?:token|secret|key|signature|credential|password)|sig|code|x-amz-[a-z-]+)=)[^&\s"']+/gi;
+const MIN_BARE_SECRET_LEN = 16;
+const ALFE_TOKEN_RE = /alfe_(?:dev|test|demo|live)_[A-Za-z0-9._-]+/g;
+const BEARER_RE = /\bbearer\s+[A-Za-z0-9._\-+/=]+/gi;
+function scrubString(value) {
+	return value.replace(BEARER_RE, "Bearer [REDACTED]").replace(URL_QUERY_SECRET_RE, "$1[REDACTED]").replace(KV_SECRET_RE, (match, label, sep, _q, secret) => {
+		if (!/[:=]/.test(sep) && secret.length < MIN_BARE_SECRET_LEN) return match;
+		return `${label}${sep}[REDACTED]`;
+	}).replace(ALFE_TOKEN_RE, "alfe_[REDACTED]");
+}
+/** Scrub secrets from a breadcrumb's message + string data values in place. */
+function scrubBreadcrumb(b) {
+	if (typeof b.message === "string") b.message = scrubString(b.message);
+	const data = b.data;
+	if (data) for (const k of Object.keys(data)) {
+		const dv = data[k];
+		if (typeof dv === "string") data[k] = scrubString(dv);
+	}
+	return b;
+}
+/**
+* Scrub secrets and drop request/env payloads before an event is sent.
+* Generic so it preserves the caller's exact event subtype (`beforeSend`
+* receives — and must return — an `ErrorEvent`, not a widened `Event`).
+*/
+function scrubEvent(event) {
+	delete event.request;
+	if (event.contexts) delete event.contexts.runtime;
+	delete event.extra;
+	delete event.server_name;
+	if (typeof event.message === "string") event.message = scrubString(event.message);
+	const values = event.exception?.values;
+	if (values) {
+		for (const v of values) if (typeof v.value === "string") v.value = scrubString(v.value);
+	}
+	if (event.breadcrumbs) for (const b of event.breadcrumbs) scrubBreadcrumb(b);
+	return event;
+}
+/**
+* Initialise Sentry for the agent-side CLI/daemon. Idempotent, best-effort, and
+* a no-op when opted out or when the baked DSN is empty. Never throws.
+*/
+async function initAgentSentry(options) {
+	try {
+		if (sentry) return;
+		if (errorReportingDisabled()) return;
+		const dsn = SURFACE_DSNS[options.surface].trim();
+		if (!dsn) return;
+		const mod = await import("@sentry/node");
+		if (options.surface === "daemon") {
+			const buildBoundScope = (dsn, extraTags) => {
+				try {
+					if (!dsn.trim()) return null;
+					const client = new mod.NodeClient({
+						dsn: dsn.trim(),
+						environment: deriveEnvironment(),
+						...options.release ? { release: options.release } : {},
+						sampleRate: 1,
+						tracesSampleRate: 0,
+						sendDefaultPii: false,
+						transport: mod.makeNodeTransport,
+						stackParser: mod.defaultStackParser,
+						integrations: [],
+						beforeSend: (event) => scrubEvent(event)
+					});
+					client.init();
+					const scope = new mod.Scope();
+					scope.setClient(client);
+					const runtime = deriveRuntime();
+					if (runtime) scope.setTag("runtime", runtime);
+					for (const [k, v] of Object.entries(extraTags)) scope.setTag(k, v);
+					return {
+						client,
+						scope
+					};
+				} catch {
+					return null;
+				}
+			};
+			if (!runtimeScope) {
+				const bound = buildBoundScope(AGENT_RUNTIME_SENTRY_DSN, {});
+				runtimeClient = bound?.client ?? null;
+				runtimeScope = bound?.scope ?? null;
+			}
+			if (!mcpScope) {
+				const bound = buildBoundScope(AGENT_MCP_SENTRY_DSN, { source: "agent-daemon" });
+				mcpClient = bound?.client ?? null;
+				mcpScope = bound?.scope ?? null;
+			}
+		}
+		if (mod.getClient()) {
+			sentry = mod;
+			return;
+		}
+		mod.init({
+			dsn,
+			environment: deriveEnvironment(),
+			...options.release ? { release: options.release } : {},
+			sampleRate: 1,
+			tracesSampleRate: 0,
+			sendDefaultPii: false,
+			...options.surface === "daemon" ? { integrations: (defaults) => defaults.filter((i) => i.name !== "OnUncaughtException" && i.name !== "OnUnhandledRejection") } : {},
+			beforeSend: (event) => scrubEvent(event),
+			beforeBreadcrumb: (breadcrumb) => scrubBreadcrumb(breadcrumb)
+		});
+		sentry = mod;
+		mod.setTag("surface", options.surface);
+		const runtime = deriveRuntime();
+		if (runtime) mod.setTag("runtime", runtime);
+	} catch {
+		sentry = null;
+	}
+}
+/**
+* Attach the resolved agent identity to all subsequent events. Called by the
+* daemon once `loadDaemonConfig()` has resolved `agentId`/`runtime`.
+*/
+function setAgentContext(context) {
+	if (!sentry) return;
+	try {
+		for (const scope of [
+			sentry,
+			runtimeScope,
+			mcpScope
+		]) {
+			if (!scope) continue;
+			if (context.agentId) scope.setTag("agentId", context.agentId);
+			if (context.runtime) scope.setTag("runtime", context.runtime);
+		}
+	} catch {}
+}
+/**
+* Capture an integration lifecycle failure (install/activate/reinstall/remove)
+* with `{ integration, phase }` tags. Accepts an `Error` (captured with stack)
+* or a plain message string (captured as an error-level message). No-op when
+* Sentry is not initialised.
+*/
+function captureIntegrationFailure(integration, phase, cause) {
+	if (!sentry) return;
+	try {
+		if (cause instanceof Error) sentry.captureException(cause, { tags: {
+			integration,
+			phase
+		} });
+		else sentry.captureMessage(String(cause), {
+			level: "error",
+			tags: {
+				integration,
+				phase
+			}
+		});
+	} catch {}
+}
+/**
+* Capture a generic CLI failure with a `{ context }` tag. The CLI counterpart
+* to `captureIntegrationFailure` — used by `exitWithError` at the handled-error
+* `process.exit()` sites in `@alfe.ai/cli`'s commands, which otherwise report
+* nothing (the error was caught, never thrown). Accepts an `Error` (captured
+* with stack), a defined non-Error value (captured as an error-level message),
+* or nothing (the `context` string itself becomes the message). No-op when
+* Sentry is not initialised. Never throws.
+*/
+function captureCliFailure(context, cause) {
+	if (!sentry) return;
+	try {
+		if (cause instanceof Error) sentry.captureException(cause, { tags: { context } });
+		else if (cause === void 0) sentry.captureMessage(context, { level: "error" });
+		else sentry.captureMessage(String(cause), {
+			level: "error",
+			tags: { context }
+		});
+	} 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
+* `beforeSend`) deletes. Throttling is the caller's job (`CaptureThrottle` in
+* `runtime-output-monitor.ts`). No-op when the runtime client is not
+* initialised. Never throws.
+*/
+function captureRuntimeCrash(opts) {
+	if (!runtimeScope) return;
+	try {
+		const scope = runtimeScope.clone();
+		for (const { stream, line } of opts.recentOutput) scope.addBreadcrumb({
+			category: `runtime.${stream}`,
+			level: stream === "stderr" ? "warning" : "info",
+			message: line
+		});
+		const crashKey = opts.spawnError ? `spawn:${opts.spawnError.code ?? "error"}` : String(opts.code ?? opts.signal ?? "unknown");
+		scope.setFingerprint([
+			"runtime-crash",
+			opts.runtime,
+			crashKey
+		]);
+		scope.setTags({
+			runtime: opts.runtime,
+			exitCode: String(opts.code),
+			signal: String(opts.signal),
+			crashesSuppressed: String(opts.crashesSuppressed ?? 0)
+		});
+		if (opts.spawnError) scope.captureException(opts.spawnError);
+		else scope.captureMessage(`Runtime ${opts.runtime} crashed (code=${String(opts.code)}, signal=${String(opts.signal)})`, "error");
+	} catch {}
+}
+/**
+* Capture an error-looking block of runtime output (stack trace, Python
+* traceback, or ERROR-level log line) detected while the child is running.
+* The block lines travel as breadcrumbs; the head line is the message.
+* Throttling/dedupe is the caller's job. No-op when Sentry is not initialised.
+* Never throws.
+*/
+function captureRuntimeErrorOutput(opts) {
+	if (!runtimeScope) return;
+	try {
+		const scope = runtimeScope.clone();
+		for (const line of opts.lines) scope.addBreadcrumb({
+			category: `runtime.${opts.stream}`,
+			level: "error",
+			message: line
+		});
+		scope.setFingerprint([
+			"runtime-output",
+			opts.runtime,
+			opts.kind,
+			opts.fingerprintKey
+		]);
+		scope.setTags({
+			runtime: opts.runtime,
+			stream: opts.stream,
+			kind: opts.kind,
+			suppressedCount: String(opts.suppressedCount ?? 0)
+		});
+		scope.captureMessage(opts.lines[0].slice(0, 300), "error");
+	} catch {}
+}
+/**
+* Capture an MCP failure (tool error, server crash, or error-looking stderr
+* output) into the `mcp` project via the daemon's bound MCP client. Throttling
+* is the caller's job (`mcp-error-capture.ts`). No-op when the MCP client is
+* not initialised. Never throws.
+*/
+function captureMcpFailure(opts) {
+	if (!mcpScope) return;
+	try {
+		const scope = mcpScope.clone();
+		for (const line of opts.lines ?? []) scope.addBreadcrumb({
+			category: `mcp.${opts.server}`,
+			level: "error",
+			message: line
+		});
+		scope.setFingerprint([
+			"agent-mcp",
+			opts.server,
+			opts.kind,
+			...opts.tool ? [opts.tool] : []
+		]);
+		scope.setTags({
+			server: opts.server,
+			kind: opts.kind,
+			...opts.tool ? { tool: opts.tool } : {},
+			suppressedCount: String(opts.suppressedCount ?? 0)
+		});
+		scope.captureMessage(`MCP ${opts.server}${opts.tool ? `.${opts.tool}` : ""} ${opts.kind}: ${opts.message.slice(0, 300)}`, "error");
+	} catch {}
+}
+/** Flush queued events (small timeout) so short-lived commands deliver them. */
+async function flushSentry(timeoutMs = 2e3) {
+	for (const client of [runtimeClient, mcpClient]) try {
+		if (client) await client.flush(timeoutMs);
+	} catch {}
+	if (!sentry) return;
+	try {
+		await sentry.flush(timeoutMs);
+	} catch {}
+}
+/**
+* Capture a fatal error — for the CLI's top-level catch. Does NOT flush: the
+* caller's `finally { await flushSentry() }` delivers it (flushing here too
+* doubled the worst-case exit delay on a failing command).
+*/
+function captureFatal(cause) {
+	if (!sentry) return;
+	try {
+		sentry.captureException(cause);
+	} catch {}
+}
+//#endregion
+export { captureFatal as a, captureRuntimeCrash as c, initAgentSentry as d, setAgentContext as f, captureCliFailure as i, captureRuntimeErrorOutput as l, AGENT_MCP_SENTRY_DSN as n, captureIntegrationFailure as o, AGENT_RUNTIME_SENTRY_DSN as r, captureMcpFailure as s, AGENT_DAEMON_SENTRY_DSN as t, flushSentry as u };

package/dist/src/index.d.ts

@@ -339,12 +339,6 @@ declare function formatHealthReport(health: DaemonHealth): string;
 declare const logger: pino.Logger<never, boolean>;
 //#endregion
 //#region src/process-manager.d.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).
- */
 /**
  * Install the service unit for the current platform.
  */

package/dist/src/index.js

@@ -1,3 +1,4 @@
-import { C as PID_PATH, D as resolveAgentIdentity, E as loadDaemonConfig, O as PINNED_OPENCLAW_VERSION, S as ALFE_DIR, T as fetchAgentConfig, _ as captureRuntimeErrorOutput, a as installService, b as setAgentContext, c as uninstallService, d as AGENT_RUNTIME_SENTRY_DSN, f as captureCliFailure, g as captureRuntimeCrash, h as captureMcpFailure, i as checkExistingDaemon, l as AGENT_DAEMON_SENTRY_DSN, m as captureIntegrationFailure, n as queryDaemonHealth, o as startService, p as captureFatal, r as startDaemon, s as stopExistingDaemon, t as formatHealthReport, u as AGENT_MCP_SENTRY_DSN, v as flushSentry, w as SOCKET_PATH, x as PROTOCOL_VERSION, y as initAgentSentry } from "../health.js";
+import { a as installService, c as uninstallService, d as PID_PATH, f as SOCKET_PATH, g as PINNED_OPENCLAW_VERSION, h as resolveAgentIdentity, i as checkExistingDaemon, l as PROTOCOL_VERSION, m as loadDaemonConfig, n as queryDaemonHealth, o as startService, p as fetchAgentConfig, r as startDaemon, s as stopExistingDaemon, t as formatHealthReport, u as ALFE_DIR } from "../health.js";
 import { n as logger } from "../logger.js";
+import { a as captureFatal, c as captureRuntimeCrash, d as initAgentSentry, f as setAgentContext, i as captureCliFailure, l as captureRuntimeErrorOutput, 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, PID_PATH, PINNED_OPENCLAW_VERSION, PROTOCOL_VERSION, SOCKET_PATH, captureCliFailure, captureFatal, captureIntegrationFailure, captureMcpFailure, captureRuntimeCrash, captureRuntimeErrorOutput, checkExistingDaemon, fetchAgentConfig, flushSentry, formatHealthReport, initAgentSentry, installService, loadDaemonConfig, logger, queryDaemonHealth, resolveAgentIdentity, setAgentContext, startDaemon, startService, stopExistingDaemon, uninstallService };

package/dist/upgrade.js

@@ -1,6 +1,132 @@
 import { n as logger } from "./logger.js";
+import { i as captureCliFailure } from "./sentry.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { existsSync } from "node:fs";
+//#region src/verify-cli-install.ts
+/**
+* Verify a global `@alfe.ai/cli` install is intact.
+*
+* Used by two crash-safety defenses (see `packages/cli/DEVELOPING.md` →
+* "Crash-safe CLI self-update"):
+*
+*   1. Verify-before-exit in the daemon self-update path (`upgrade.ts`): after
+*      `npm install -g @alfe.ai/cli@<v>` returns, confirm the tree is intact
+*      BEFORE `process.exit(0)`. A bad tree (npm returned but produced no
+*      `dist/`, empty `package.json`) must NOT trigger the exit — the old,
+*      still-working daemon stays up instead of exiting into a 203/EXEC brick.
+*
+*   2. The boot-time self-heal guard (`alfe-cli-guard.sh`, installed by the CLI
+*      setup flow as an `ExecStartPre=` on the systemd unit) reimplements the
+*      SAME two checks in POSIX sh, because it must run OUTSIDE the (possibly
+*      broken) `alfe` binary. Keep the two in lockstep.
+*
+* The two checks:
+*   - the resolved CLI entry (`.../dist/index.js`, the symlink target of the
+*     `alfe` bin) exists on disk; and
+*   - running it (`node <entry> --version`, or `alfe --version`) exits 0 and
+*     prints the expected version.
+*
+* This module holds only pure decision logic + a thin exec wrapper so the
+* decision can be unit-tested without a real install on disk.
+*/
+const execFileAsync$1 = promisify(execFile);
+/**
+* Pure verification decision. Given a probe of the install on disk, decide
+* whether it is intact. When `expectedVersion` is provided, the reported
+* version must match exactly; otherwise any exit-0 version string passes.
+*
+* Kept side-effect-free so the healthy/broken decision is unit-testable.
+*/
+function decideCliInstallOk(probe, expectedVersion) {
+	if (probe.entryPath !== void 0 && !probe.entryExists) return {
+		ok: false,
+		reason: `CLI entry missing at ${probe.entryPath}`,
+		probe
+	};
+	if (probe.reportedVersion === null) return {
+		ok: false,
+		reason: "CLI --version did not run cleanly",
+		probe
+	};
+	if (expectedVersion && probe.reportedVersion !== expectedVersion) return {
+		ok: false,
+		reason: `CLI reports ${probe.reportedVersion}, expected ${expectedVersion}`,
+		probe
+	};
+	return {
+		ok: true,
+		probe
+	};
+}
+/**
+* Resolve the CLI entry file this daemon is running from. When the gateway is
+* loaded as a dependency of the globally-installed CLI the layout is
+* `.../@alfe.ai/cli/dist/index.js` with `.../@alfe.ai/gateway/dist/...`
+* alongside — walk up to the sibling `@alfe.ai/cli/package.json` and derive its
+* `bin.alfe` / main entry. Returns undefined when it can't be resolved (e.g.
+* `alfe gateway daemon` run from a dev checkout); the caller then skips the
+* file-exists check and relies on `alfe --version` alone.
+*/
+async function resolveCliEntryPath(fromUrl) {
+	try {
+		const { fileURLToPath } = await import("node:url");
+		const { dirname, join } = await import("node:path");
+		const { readFile } = await import("node:fs/promises");
+		let dir = dirname(fileURLToPath(fromUrl));
+		for (let i = 0; i < 10; i++) {
+			const pkgPath = join(dir, "package.json");
+			try {
+				const raw = await readFile(pkgPath, "utf-8");
+				const pkg = JSON.parse(raw);
+				if (pkg.name === "@alfe.ai/cli") {
+					const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.alfe ?? pkg.main ?? "dist/index.js";
+					return join(dir, binRel);
+				}
+			} catch {}
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	} catch {}
+}
+/**
+* Run `<cmd>` and return the trimmed stdout on exit 0, or null on any failure
+* (non-zero exit, ENOENT, timeout). Never throws.
+*/
+async function tryVersion(cmd, args) {
+	try {
+		const { stdout } = await execFileAsync$1(cmd, args, { timeout: 15e3 });
+		const out = stdout.trim();
+		return out.length > 0 ? out : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Probe + decide whether the on-disk global CLI install is intact.
+*
+* @param expectedVersion  when set, the reported version must match exactly.
+* @param entryPath        the resolved `.../dist/index.js` (from
+*                         `resolveCliEntryPath`). When provided and missing,
+*                         the check fails fast. Also used to run the CLI
+*                         directly via `node <entry> --version`, which is more
+*                         reliable than a PATH lookup of `alfe`.
+*/
+async function verifyCliInstall(expectedVersion, entryPath) {
+	const entryExists = entryPath !== void 0 ? existsSync(entryPath) : true;
+	if (entryPath !== void 0 && !entryExists) return decideCliInstallOk({
+		entryPath,
+		entryExists,
+		reportedVersion: null
+	});
+	return decideCliInstallOk({
+		entryPath,
+		entryExists,
+		reportedVersion: entryPath ? await tryVersion(process.execPath, [entryPath, "--version"]) : await tryVersion("alfe", ["--version"])
+	}, expectedVersion);
+}
+//#endregion
 //#region src/upgrade.ts
 /**
 * CLI upgrade — runs npm install inline then exits.
@@ -12,13 +138,25 @@ import { promisify } from "node:util";
 * Flow:
 *   1. Daemon ACKs the COMMAND (caller handles this before calling upgrade)
 *   2. npm install -g @alfe.ai/cli@{version} runs as a child process
-*   3. Daemon exits with code 0
-*   4. Systemd restarts the service → new version boots
+*   3. VERIFY the new install is intact (dist/index.js present + `--version`
+*      reports the target). Only then exit — an interrupted/aborted npm
+*      install that returned a broken tree must NOT trigger the exit, or
+*      systemd relaunches a dangling binary and crash-loops with 203/EXEC.
+*   4. Daemon exits with code 0
+*   5. Systemd restarts the service → new version boots
+*
+* See `packages/cli/DEVELOPING.md` → "Crash-safe CLI self-update". This is
+* defense #1 (verify-before-exit); the boot-time self-heal guard (defense #2,
+* an `ExecStartPre=` on the systemd unit) covers the case where the process is
+* KILLED mid-install (reboot) and this function never gets to run.
 */
 const execFileAsync = promisify(execFile);
 /**
-* Upgrade the CLI to a target version and exit.
-* Systemd will restart the daemon with the new version.
+* Upgrade the CLI to a target version and exit — UNLESS the resulting install
+* is broken, in which case we stay up on the current version.
+*
+* Returns `Promise<never>` on the success path (it exits). On a verification
+* failure it returns normally so the caller (and the daemon) keep running.
 */
 async function upgradeAndExit(version) {
 	logger.info({ version }, "Upgrading CLI...");
@@ -30,14 +168,25 @@ async function upgradeAndExit(version) {
 		], { timeout: 12e4 });
 		if (stdout) logger.debug({ stdout: stdout.trim() }, "npm install stdout");
 		if (stderr) logger.debug({ stderr: stderr.trim() }, "npm install stderr");
-		logger.info({ version }, "CLI upgraded — exiting for systemd restart");
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		logger.error({
 			err: message,
 			version
 		}, "CLI upgrade failed");
+		process.exit(0);
+	}
+	const result = await verifyCliInstall(void 0, await resolveCliEntryPath(import.meta.url));
+	if (!result.ok) {
+		logger.error({
+			version,
+			reason: result.reason,
+			probe: result.probe
+		}, "CLI upgrade verification FAILED — staying on current version instead of exiting into a broken binary");
+		captureCliFailure("upgrade.verify_failed", /* @__PURE__ */ new Error(`CLI upgrade to ${version} produced a broken install: ${result.reason ?? "unknown"}`));
+		return;
 	}
+	logger.info({ version }, "CLI upgrade verified — exiting for systemd restart");
 	process.exit(0);
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/gateway",
-  "version": "0.7.4",
+  "version": "0.8.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.10.0",
+    "@alfe.ai/agent-api-client": "^0.11.0",
     "@alfe.ai/ai-proxy-local": "^0.0.13",
     "@alfe.ai/config": "^0.3.0",
-    "@alfe.ai/integration-manifest": "^0.3.1",
-    "@alfe.ai/integrations": "^0.4.2",
+    "@alfe.ai/integration-manifest": "^0.3.2",
+    "@alfe.ai/integrations": "^0.5.1",
     "@alfe.ai/mcp-bundler": "^0.3.1"
   },
   "license": "UNLICENSED",