skydive-cli 0.5.0-beta.9 → 0.5.0

package/dist/js/chunk-BbwQpWto.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+//#endregion
+export { __require as n, __toESM as r, __commonJSMin as t };

package/dist/js/{client-DabRpc_T.mjs → client--k9cjfkX.mjs}

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
-import { a as mintPortalDeviceToken, c as unifyLegacyCliGrants, i as grantPortalAccess, n as fetchPortalDevices, r as findThisDevice } from "./api-DG5W6iwx.mjs";
+import { a as mintPortalDeviceToken, c as unifyLegacyCliGrants, i as grantPortalAccess, l as startTlsForward, n as fetchPortalDevices, r as findThisDevice } from "./api-BFQ4PQDA.mjs";
 import os from "node:os";
 import { z } from "zod";
-import { execFile, spawn } from "node:child_process";
+import * as childProcess from "node:child_process";
+import { spawn } from "node:child_process";
 import net from "node:net";
 import { WebSocket, createWebSocketStream } from "ws";
 
 //#region ../portal-daemon/src/machine.ts
+const SCUTIL_TIMEOUT_MS = 2e3;
+const SCUTIL_ATTEMPTS = 3;
 /**
 * Identity this machine registers under on the portal.
 *
@@ -15,38 +18,74 @@ import { WebSocket, createWebSocketStream } from "ws";
 * row, so a grant applies to the machine no matter which surface the user
 * shared from. The name must therefore match what the desktop app registers —
 * on macOS that is `scutil --get LocalHostName` (the Rust client's own
-* derivation, stabler than the network-assigned hostname), with the plain
-* hostname as the fallback for other platforms or a failed read.
+* derivation, stabler than the network-assigned hostname).
+*
+* The machine name is a durable IDENTITY, not a fresh network reading: every
+* grant hangs off the device row keyed by this name, so if it changes the
+* device flips to a brand-new row with ZERO grants and every agent re-prompts
+* across every open CLI. `os.hostname()` is NOT durable — macOS rewrites it
+* from DHCP/DNS per network — so it must never be allowed to silently replace
+* a name we already registered under. Resolution order:
+*
+*   1. `scutil --get LocalHostName` (retried) — the stable, correct source.
+*   2. `previous` — the name we last successfully registered under, persisted
+*      by the daemon. Preferred over the volatile hostname so a transient
+*      `scutil` failure keeps our existing identity (and grants) intact.
+*   3. `os.hostname()` — last resort for a machine that has NEVER resolved a
+*      name (first run, non-macOS, scutil permanently unavailable).
 *
 * Historically the CLI suffixed `-cli` to keep a device distinct from the
 * desktop's; `unifyLegacyCliGrants` migrates grants off those rows.
 */
-async function resolveMachineIdentity() {
-	const fallback = fallbackHost();
-	if (process.platform !== "darwin") return {
-		machineName: fallback,
-		friendlyName: fallback
+async function resolveMachineIdentity(previous) {
+	const persisted = previous?.trim() || null;
+	if (process.platform !== "darwin") {
+		const machineName = persisted ?? fallbackHost();
+		return {
+			machineName,
+			friendlyName: machineName,
+			machineNameSource: persisted ? "persisted" : "hostname-fallback"
+		};
+	}
+	const local = await scutilRead("LocalHostName");
+	if (local) return {
+		machineName: local,
+		friendlyName: await scutilRead("ComputerName") ?? local,
+		machineNameSource: "scutil"
+	};
+	if (persisted) return {
+		machineName: persisted,
+		friendlyName: persisted,
+		machineNameSource: "persisted"
 	};
-	const local = await scutilRead("LocalHostName") ?? fallback;
+	const fallback = fallbackHost();
 	return {
-		machineName: local,
-		friendlyName: await scutilRead("ComputerName") ?? local
+		machineName: fallback,
+		friendlyName: fallback,
+		machineNameSource: "hostname-fallback"
 	};
 }
 function fallbackHost() {
 	return (os.hostname() || "machine").trim().replace(/\.local$/i, "") || "machine";
 }
 function scutilRead(key) {
-	return new Promise((resolve) => {
-		execFile("/usr/sbin/scutil", ["--get", key], { timeout: 2e3 }, (error, stdout) => {
-			if (error) {
-				resolve(null);
-				return;
-			}
-			const value = stdout.trim();
-			resolve(value.length > 0 ? value : null);
+	return attempt(0);
+	function attempt(n) {
+		return new Promise((resolve) => {
+			childProcess.execFile("/usr/sbin/scutil", ["--get", key], { timeout: SCUTIL_TIMEOUT_MS }, (error, stdout) => {
+				if (error) {
+					if (n + 1 < SCUTIL_ATTEMPTS) {
+						resolve(attempt(n + 1));
+						return;
+					}
+					resolve(null);
+					return;
+				}
+				const value = stdout.trim();
+				resolve(value.length > 0 ? value : null);
+			});
 		});
-	});
+	}
 }
 const INHERITED_ENV = [
 	"HOME",
@@ -77,9 +116,10 @@ function buildEnv(extra) {
 /**
 * Build the desktop-portal WebSocket URL from the chat origin. Mirrors the Rust
 * desktop client: http→ws, https→wss, scheme-less defaults to wss, and the
-* machine/label ride as query pairs (percent-encoded by URL).
+* machine/label (plus the dial diagnostics) ride as query pairs
+* (percent-encoded by URL).
 */
-function portalWsUrl(appUrl, machine, label) {
+function portalWsUrl(appUrl, machine, label, dial) {
 	const base = appUrl.replace(/\/+$/, "");
 	let wsBase;
 	if (base.startsWith("https://")) wsBase = `wss://${base.slice(8)}`;
@@ -88,6 +128,9 @@ function portalWsUrl(appUrl, machine, label) {
 	const url = new URL(`${wsBase}/api/v1/portal/desktop`);
 	url.searchParams.set("machine", machine);
 	url.searchParams.set("label", label);
+	if (dial.build) url.searchParams.set("build", dial.build);
+	if (dial.reason) url.searchParams.set("reason", dial.reason);
+	if (dial.downMs !== null) url.searchParams.set("down_ms", String(Math.max(0, Math.round(dial.downMs))));
 	return url.toString();
 }
 
@@ -104,6 +147,43 @@ function errorMessage(err) {
 	return err instanceof Error ? err.message : String(err);
 }
 
+//#endregion
+//#region ../portal-daemon/src/build-stamp.ts
+/**
+* This build's stamp: the unix commit time (seconds) of the source it was
+* compiled from. Empty string when unstamped (a dev source run without the
+* env override).
+*
+* Why a commit time and not a package version: the daemon ships inside two
+* independently-versioned installers (the skydive CLI and the desktop app),
+* so their semvers are not comparable — but both build from this repo, so
+* the commit time of the built tree is one monotonic clock they share.
+*/
+function portalDaemonBuild() {
+	return "1787785513";
+}
+/**
+* Whether a client carrying `mine` should replace a running daemon carrying
+* `theirs` (newest build wins):
+*
+*  - an unstamped client never takes over — it can't prove it's newer;
+*  - a stamped client replaces an unstamped daemon — every stamped build
+*    postdates stamping, so the unstamped daemon is older by construction;
+*  - otherwise strictly greater wins; equal keeps the incumbent, so two
+*    identical builds never bounce the daemon between them.
+*/
+function isNewerBuild(mine, theirs) {
+	const mineAt = parseStamp(mine);
+	if (mineAt === null) return false;
+	const theirsAt = parseStamp(theirs);
+	if (theirsAt === null) return true;
+	return mineAt > theirsAt;
+}
+function parseStamp(stamp) {
+	if (!/^[0-9]+$/.test(stamp)) return null;
+	return Number(stamp);
+}
+
 //#endregion
 //#region ../portal-protocol/src/index.ts
 const MAX_WS_FRAME_BYTES = 16 * 1024 * 1024;
@@ -198,10 +278,36 @@ function decodeFrame(frame) {
 */
 var ReverseListener = class {
 	server = null;
+	tls = null;
 	conns = /* @__PURE__ */ new Set();
 	constructor(opts) {
 		this.opts = opts;
 	}
+	/**
+	* One tunnel to the sandbox target — the same per-connection edge dial the
+	* plain accept path inlines, shaped for the TLS listener's acquireTunnel
+	* seam. Resolves once the upgrade completes, with the duplex PAUSED so no
+	* early bytes drop before adoption.
+	*/
+	dialTunnel() {
+		const { dialOrigin, targetPort, token } = this.opts.target();
+		const ws = new WebSocket(`${dialOrigin.replace(/^http/, "ws")}/portal/tcp?port=${targetPort}`, { headers: { authorization: `Bearer ${token}` } });
+		return new Promise((resolve, reject) => {
+			ws.once("error", reject);
+			ws.once("unexpected-response", (_req, res) => {
+				res.destroy();
+				reject(/* @__PURE__ */ new Error(`tunnel rejected (HTTP ${res.statusCode ?? "?"})`));
+			});
+			ws.once("open", () => {
+				const stream = createWebSocketStream(ws);
+				stream.pause();
+				resolve({
+					stream,
+					close: () => stream.destroy()
+				});
+			});
+		});
+	}
 	start() {
 		const server = net.createServer((sock) => {
 			this.conns.add(sock);
@@ -227,12 +333,52 @@ var ReverseListener = class {
 			});
 		});
 		server.once("error", (err) => this.opts.onListening(err));
-		server.listen(this.opts.listenPort, "127.0.0.1", () => this.opts.onListening(null));
+		server.listen(this.opts.listenPort, "127.0.0.1", () => {
+			this.opts.onListening(null);
+			this.startTls();
+		});
 		this.server = server;
 	}
+	/**
+	* The additive TLS+h2 twin (fire-and-forget from start): browsers negotiate
+	* h2 there, lifting the 6-connection cap that serializes module-heavy dev
+	* servers. Every failure logs once and leaves the plain listener — the
+	* product's default behavior — untouched. The ack (`reverse_listening`)
+	* deliberately stays keyed to the plain bind: TLS is an enhancement, never
+	* a condition of "the tunnel is up".
+	*/
+	startTls() {
+		const source = this.opts.tlsCertSource;
+		if (!source) return;
+		(async () => {
+			try {
+				const cert = await source();
+				if (!cert || this.server === null) return;
+				this.tls = await startTlsForward({
+					cert,
+					localPort: this.opts.listenPort,
+					targetPort: this.opts.target().targetPort,
+					acquireTunnel: () => this.dialTunnel(),
+					log: this.opts.log
+				});
+				if (this.server === null) {
+					const straggler = this.tls;
+					this.tls = null;
+					await straggler.close();
+					return;
+				}
+				this.opts.log(`expose: TLS origin up: https://${this.tls.hostname}:${this.tls.port} (HTTP/2)`);
+			} catch (error) {
+				this.opts.log(`expose: TLS origin unavailable (${error instanceof Error ? error.message : String(error)}); http listener unaffected`);
+			}
+		})();
+	}
 	stop() {
 		this.server?.close();
 		this.server = null;
+		const tls = this.tls;
+		this.tls = null;
+		if (tls) tls.close();
 		for (const sock of this.conns) sock.destroy();
 		this.conns.clear();
 	}
@@ -326,6 +472,7 @@ var JobManager = class {
 			listener: new ReverseListener({
 				listenPort,
 				target: () => rev.target,
+				tlsCertSource: this.opts.tlsCertSource,
 				log: (msg) => {
 					if (rev.settled) return;
 					this.opts.send(encodeData(id, STREAM.stderr, rev.seq, Buffer.from(msg)));
@@ -430,8 +577,71 @@ var JobManager = class {
 
 //#endregion
 //#region ../portal-daemon/src/client.ts
-const INITIAL_BACKOFF_MS = 500;
-const MAX_BACKOFF_MS = 1e4;
+const DEFAULT_HEARTBEAT = {
+	intervalMs: 15e3,
+	maxMissed: 2,
+	wakeTickMs: 2e3,
+	wakeGapThresholdMs: 1e4,
+	netWatchTickMs: 2e3,
+	initialBackoffMs: 500,
+	maxBackoffMs: 1e4
+};
+/**
+* A cheap fingerprint of the machine's network identity: every non-internal
+* interface name, its IPv4 addresses, and the /64 prefixes of its routable
+* IPv6 addresses. When it changes, the active network changed (interface
+* came/went, DHCP handed out a new address, VPN tunnel up/down, v6-only
+* network moved) and any live socket is riding a route that no longer exists.
+*
+* IPv6 is fingerprinted by PREFIX, not full address: macOS rotates temporary
+* IPv6 addresses on a schedule (RFC 8981), which would read as a "change"
+* every rotation and cause spurious reconnects — but every rotated address
+* stays inside the same delegated /64, so the prefix is rotation-immune while
+* still catching a v6-only network switch (a different network delegates a
+* different prefix). Link-local (fe80::/10) is skipped outright: it exists on
+* every interface regardless of which network is attached, so it carries no
+* network identity the interface NAME doesn't already.
+*/
+function networkFingerprint() {
+	const parts = [];
+	for (const [name, addrs] of Object.entries(os.networkInterfaces())) {
+		let external = false;
+		const v6Prefixes = /* @__PURE__ */ new Set();
+		for (const addr of addrs ?? []) {
+			if (addr.internal) continue;
+			external = true;
+			if (addr.family === "IPv4") parts.push(`${name}/${addr.address}`);
+			if (addr.family === "IPv6") {
+				const prefix = ipv6Prefix64(addr.address);
+				if (prefix) v6Prefixes.add(`${name}/${prefix}`);
+			}
+		}
+		for (const prefix of v6Prefixes) parts.push(prefix);
+		if (external) parts.push(name);
+	}
+	return parts.sort().join("|");
+}
+/**
+* The first 64 bits of an IPv6 address as a normalized `a:b:c:d` string, or
+* null for link-local / unparsable input. See networkFingerprint for why the
+* prefix (and not the full address) is the identity worth watching.
+*/
+function ipv6Prefix64(address) {
+	const [addr] = address.split("%");
+	if (!addr) return null;
+	if (/^fe[89ab]/i.test(addr)) return null;
+	const halves = addr.split("::");
+	if (halves.length > 2) return null;
+	const head = halves[0] ? halves[0].split(":") : [];
+	const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+	const missing = 8 - head.length - tail.length;
+	if (missing < 0 || halves.length === 1 && missing !== 0) return null;
+	return [
+		...head,
+		...Array(missing).fill("0"),
+		...tail
+	].slice(0, 4).map((group) => group.padStart(4, "0").toLowerCase()).join(":");
+}
 /**
 * Shares the local machine with agents over the portal: dials OUT to the api's
 * desktop-portal WebSocket (authenticating with a short-lived device token
@@ -454,8 +664,104 @@ var PortalClient = class {
 	machineName = "";
 	friendlyName = "";
 	legacyGrantsChecked = false;
+	wakeWatch = null;
+	lastTick = Date.now();
+	netWatch = null;
+	netFingerprint = networkFingerprint();
+	backoffKick = null;
+	dialReason = null;
+	disconnectedAt = null;
+	handingOff = false;
+	handoffResolve = null;
+	heartbeatConfig;
 	constructor(opts) {
 		this.opts = opts;
+		this.heartbeatConfig = {
+			...DEFAULT_HEARTBEAT,
+			...opts.heartbeat
+		};
+		this.startWakeWatch();
+		this.startNetWatch();
+	}
+	/**
+	* Detect wake-from-sleep without an Electron/`powerMonitor` dependency (the
+	* daemon also runs headless under the CLI). A repeating timer that should
+	* fire every WAKE_TICK_MS; when the actual gap since the last tick far
+	* exceeds that, the process was suspended (macOS sleep, laptop lid) and the
+	* current socket — if any — is a zombie against a server that has already
+	* reaped our presence. Terminate it now so `connectLoop` redials at once
+	* instead of waiting out the heartbeat deadline. Cheap: one no-op timer.
+	*/
+	startWakeWatch() {
+		this.lastTick = Date.now();
+		this.wakeWatch = setInterval(() => {
+			const now = Date.now();
+			const gap = now - this.lastTick;
+			this.lastTick = now;
+			if (gap > this.heartbeatConfig.wakeGapThresholdMs) this.forceReconnect("woke from sleep; reconnecting portal");
+		}, this.heartbeatConfig.wakeTickMs);
+		this.wakeWatch.unref?.();
+	}
+	/**
+	* Detect a network switch — the awake sibling of the wake detector. Changing
+	* Wi-Fi↔ethernet, switching SSID, or toggling a VPN kills the socket's route
+	* with no FIN/RST, so `ws` may never fire 'close' and the heartbeat's
+	* missed-pong deadline is the best case (~2 intervals), not a guarantee.
+	* Poll the network-identity fingerprint and, the moment it changes, terminate
+	* the socket so `connectLoop` redials over the new network immediately.
+	* Cheap: `os.networkInterfaces()` is one syscall-backed read per tick.
+	*/
+	startNetWatch() {
+		this.netWatch = setInterval(() => {
+			const fingerprint = networkFingerprint();
+			if (fingerprint === this.netFingerprint) return;
+			this.netFingerprint = fingerprint;
+			this.forceReconnect("network changed; reconnecting portal");
+		}, this.heartbeatConfig.netWatchTickMs);
+		this.netWatch.unref?.();
+	}
+	/**
+	* The one reaction every detector (wake, network change) converges on: make
+	* the connect loop re-evaluate NOW, whatever state it is in. With a live
+	* socket, terminate it — 'close' resolves `runConnection` and the loop
+	* redials. Between dials (backing off after a failure, e.g. while the
+	* network was down), cut the sleep short so the retry fires immediately — a
+	* dial that was pointless a moment ago is exactly right the moment the
+	* network comes back. These are per-machine local events, uncorrelated
+	* across the fleet, so the immediate retry can't herd; the backoff VALUE is
+	* untouched and still governs the next failure.
+	*/
+	forceReconnect(reason) {
+		this.dialReason = reason;
+		this.disconnectedAt ??= Date.now();
+		if (this.ws) {
+			this.error = reason;
+			this.ws.terminate();
+			return;
+		}
+		this.kickBackoff();
+	}
+	kickBackoff() {
+		const kick = this.backoffKick;
+		this.backoffKick = null;
+		kick?.();
+	}
+	/** The between-redials sleep, interruptible by a detector (forceReconnect). */
+	backoffSleep(ms) {
+		return new Promise((resolve) => {
+			let done = false;
+			const finish = () => {
+				if (done) return;
+				done = true;
+				this.backoffKick = null;
+				resolve();
+			};
+			const timer = setTimeout(finish, ms);
+			this.backoffKick = () => {
+				clearTimeout(timer);
+				finish();
+			};
+		});
 	}
 	isEnabled() {
 		return this.enabled;
@@ -481,6 +787,7 @@ var PortalClient = class {
 		this.ws = null;
 		this.deviceId = null;
 		this.granted = /* @__PURE__ */ new Set();
+		this.kickBackoff();
 		this.setStatus("off");
 	}
 	/**
@@ -491,10 +798,61 @@ var PortalClient = class {
 	dispose() {
 		this.disposed = true;
 		this.enabled = false;
+		if (this.wakeWatch) {
+			clearInterval(this.wakeWatch);
+			this.wakeWatch = null;
+		}
+		if (this.netWatch) {
+			clearInterval(this.netWatch);
+			this.netWatch = null;
+		}
 		this.jobs?.killAll();
 		this.jobs = null;
 		this.ws?.close();
 		this.ws = null;
+		this.kickBackoff();
+		this.finishHandoff();
+	}
+	/**
+	* Begin a make-before-break handoff to a successor daemon. Keep the current
+	* portal socket (and thus this machine's presence claim) alive so there is no
+	* `registered but not connected` gap, but stop redialing once it closes — the
+	* successor's `claim()` supersedes us and the server closes our socket, which
+	* is our cue to step down. Resolves when the socket has closed (clean
+	* handoff) OR after `timeoutMs` (the successor never came up, so we release
+	* the slot rather than hold it forever). Idempotent.
+	*/
+	beginHandoff(timeoutMs) {
+		if (this.disposed) return Promise.resolve();
+		if (this.handingOff) return new Promise((resolve) => {
+			const prev = this.handoffResolve;
+			this.handoffResolve = () => {
+				prev?.();
+				resolve();
+			};
+		});
+		this.handingOff = true;
+		if (!this.ws) return Promise.resolve();
+		return new Promise((resolve) => {
+			let done = false;
+			const finish = () => {
+				if (done) return;
+				done = true;
+				clearTimeout(timer);
+				resolve();
+			};
+			this.handoffResolve = finish;
+			const timer = setTimeout(() => {
+				this.disable();
+				this.finishHandoff();
+			}, timeoutMs);
+			if (typeof timer.unref === "function") timer.unref();
+		});
+	}
+	finishHandoff() {
+		const resolve = this.handoffResolve;
+		this.handoffResolve = null;
+		resolve?.();
 	}
 	/**
 	* Grant one agent access to this machine (default-deny; user-initiated).
@@ -550,55 +908,95 @@ var PortalClient = class {
 	}
 	async connectLoop() {
 		if (!this.machineName) {
-			const identity = await resolveMachineIdentity();
+			const identity = await resolveMachineIdentity(this.opts.persistedMachineName);
 			this.machineName = identity.machineName;
 			this.friendlyName = identity.friendlyName;
+			this.opts.onMachineName(identity.machineName, identity.machineNameSource);
 		}
-		let backoff = INITIAL_BACKOFF_MS;
-		while (this.enabled && !this.disposed) {
+		let backoff = this.heartbeatConfig.initialBackoffMs;
+		while (this.enabled && !this.disposed && !this.handingOff) {
 			this.setStatus("connecting");
 			try {
 				const token = await this.wsToken();
-				await this.runConnection(token);
-				backoff = INITIAL_BACKOFF_MS;
+				if (await this.runConnection(token)) backoff = this.heartbeatConfig.initialBackoffMs;
+				else backoff = Math.min(backoff * 2, this.heartbeatConfig.maxBackoffMs);
 			} catch (err) {
-				if (!this.enabled || this.disposed) break;
+				if (!this.enabled || this.disposed || this.handingOff) break;
 				this.setStatus("error", errorMessage(err));
+				backoff = Math.min(backoff * 2, this.heartbeatConfig.maxBackoffMs);
 			}
-			if (!this.enabled || this.disposed) break;
-			await sleep(backoff);
-			backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+			if (!this.enabled || this.disposed || this.handingOff) break;
+			await this.backoffSleep(Math.random() * backoff);
 		}
 	}
 	runConnection(token) {
 		return new Promise((resolve) => {
-			const ws = new WebSocket(portalWsUrl(this.opts.appUrl, this.machineName, this.friendlyName), {
+			let settled = false;
+			let healthy = false;
+			const settle = () => {
+				if (settled) return;
+				settled = true;
+				resolve(healthy);
+			};
+			const ws = new WebSocket(portalWsUrl(this.opts.appUrl, this.machineName, this.friendlyName, {
+				build: portalDaemonBuild(),
+				reason: this.dialReason ?? "initial",
+				downMs: this.disconnectedAt === null ? null : Date.now() - this.disconnectedAt
+			}), {
 				headers: { authorization: `Bearer ${token}` },
 				maxPayload: MAX_WS_FRAME_BYTES
 			});
 			this.ws = ws;
 			const jobs = new JobManager({
 				resolveCwd: this.opts.resolveCwd,
+				tlsCertSource: this.opts.tlsCertSource,
 				send: (frame) => {
 					if (ws.readyState === WebSocket.OPEN) ws.send(frame);
 				}
 			});
 			this.jobs = jobs;
+			let missed = 0;
+			const heartbeat = setInterval(() => {
+				if (ws.readyState !== WebSocket.OPEN && ws.readyState !== WebSocket.CONNECTING) return;
+				if (missed >= this.heartbeatConfig.maxMissed) {
+					this.error = ws.readyState === WebSocket.CONNECTING ? "portal handshake stalled; reconnecting" : "portal connection went silent (no pong); reconnecting";
+					this.dialReason = this.error;
+					this.disconnectedAt ??= Date.now();
+					ws.terminate();
+					return;
+				}
+				missed += 1;
+				if (ws.readyState === WebSocket.OPEN) ws.ping();
+			}, this.heartbeatConfig.intervalMs);
+			const markAlive = () => {
+				missed = 0;
+				healthy = true;
+			};
 			ws.on("open", () => {
+				missed = 0;
+				this.dialReason = null;
+				this.disconnectedAt = null;
 				this.setStatus("connected");
 				this.syncDeviceState();
 			});
+			ws.on("pong", markAlive);
+			ws.on("ping", markAlive);
 			ws.on("message", (data, isBinary) => {
+				markAlive();
 				if (isBinary) jobs.handleFrame(toBuffer(data));
 			});
 			ws.on("error", (err) => {
 				this.error = errorMessage(err);
 			});
-			ws.on("close", () => {
+			ws.on("close", (code) => {
+				this.dialReason ??= `connection closed (code ${code})`;
+				this.disconnectedAt ??= Date.now();
+				clearInterval(heartbeat);
 				jobs.killAll();
 				if (this.jobs === jobs) this.jobs = null;
 				if (this.ws === ws) this.ws = null;
-				resolve();
+				if (this.handingOff) this.finishHandoff();
+				settle();
 			});
 		});
 	}
@@ -650,4 +1048,4 @@ function sleep(ms) {
 }
 
 //#endregion
-export { isRecord as n, resolveMachineIdentity as r, PortalClient as t };
+export { resolveMachineIdentity as a, isRecord as i, isNewerBuild as n, portalDaemonBuild as r, PortalClient as t };