@mulmoclaude/core 1.8.0 → 1.10.0

package/dist/remote-host/health.d.ts

@@ -0,0 +1,13 @@
+export declare const RUNNER_HEALTH_STATES: readonly ["online", "reconnecting", "offline"];
+export type RunnerHealthState = (typeof RUNNER_HEALTH_STATES)[number];
+export interface RunnerHealth {
+    state: RunnerHealthState;
+    /** Last channel error seen, for the popover and the log. Null before the first one. */
+    lastError: string | null;
+    /** ms epoch of the last state change, so the UI can say how long it has been down. */
+    changedAt: number;
+}
+export declare const isRunnerHealthState: (value: unknown) => value is RunnerHealthState;
+/** Narrows a parsed HTTP payload. The client renders whatever this accepts, so a
+ *  half-shaped health has to read as "no health reported" rather than as a state. */
+export declare const isRunnerHealth: (value: unknown) => value is RunnerHealth;

package/dist/remote-host/index.cjs

@@ -1,31 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let firebase_firestore = require("firebase/firestore");
-//#region src/remote-host/index.ts
-/** Widen a JSON-shaped handler payload to the channel's `JsonObject`.
-*
-*  Exists so the `Jsonify` reasoning above lives in ONE place. Before this,
-*  eight remote-host handlers each carried their own `as unknown as JsonObject`
-*  with the justification re-argued in eight slightly different comments —
-*  which is how a rule stops being reviewable. */
-var toJsonObject = (payload) => payload;
-var isExpired = (command, now) => typeof command.expiresAt === "number" && now >= command.expiresAt;
-var byCreatedAt = (left, right) => (left.createdAt ?? 0) - (right.createdAt ?? 0);
-var REMOTE_HOST_PROTOCOL_VERSION = 2;
-var buildHostPresence = (channel, handlers, online) => ({
-	online,
-	hostId: channel.hostId,
-	protocolVersion: 2,
-	capabilities: Object.keys(handlers)
-});
-var commandsCollection = (firestore, channel) => (0, firebase_firestore.collection)(firestore, "users", channel.uid, "hosts", channel.hostId, "commands");
-var hostDoc = (firestore, channel) => (0, firebase_firestore.doc)(firestore, "users", channel.uid, "hosts", channel.hostId);
-//#endregion
-exports.REMOTE_HOST_PROTOCOL_VERSION = REMOTE_HOST_PROTOCOL_VERSION;
-exports.buildHostPresence = buildHostPresence;
-exports.byCreatedAt = byCreatedAt;
-exports.commandsCollection = commandsCollection;
-exports.hostDoc = hostDoc;
-exports.isExpired = isExpired;
-exports.toJsonObject = toJsonObject;
-
-//# sourceMappingURL=index.cjs.map
+const require_remote_host = require("../remote-host-DkDVxNim.cjs");
+exports.REMOTE_HOST_PROTOCOL_VERSION = require_remote_host.REMOTE_HOST_PROTOCOL_VERSION;
+exports.RUNNER_HEALTH_STATES = require_remote_host.RUNNER_HEALTH_STATES;
+exports.buildHostPresence = require_remote_host.buildHostPresence;
+exports.byCreatedAt = require_remote_host.byCreatedAt;
+exports.commandsCollection = require_remote_host.commandsCollection;
+exports.hostDoc = require_remote_host.hostDoc;
+exports.isExpired = require_remote_host.isExpired;
+exports.isRunnerHealth = require_remote_host.isRunnerHealth;
+exports.isRunnerHealthState = require_remote_host.isRunnerHealthState;
+exports.toJsonObject = require_remote_host.toJsonObject;

package/dist/remote-host/index.d.ts

@@ -58,3 +58,5 @@ export interface HostPresence {
 export declare const buildHostPresence: (channel: Channel, handlers: CommandHandlers, online: boolean) => HostPresence;
 export declare const commandsCollection: (firestore: Firestore, channel: Channel) => CollectionReference<DocumentData>;
 export declare const hostDoc: (firestore: Firestore, channel: Channel) => DocumentReference<DocumentData>;
+export { RUNNER_HEALTH_STATES, isRunnerHealth, isRunnerHealthState } from './health.js';
+export type { RunnerHealth, RunnerHealthState } from './health.js';

package/dist/remote-host/index.js

@@ -1,24 +1,2 @@
-import { collection, doc } from "firebase/firestore";
-//#region src/remote-host/index.ts
-/** Widen a JSON-shaped handler payload to the channel's `JsonObject`.
-*
-*  Exists so the `Jsonify` reasoning above lives in ONE place. Before this,
-*  eight remote-host handlers each carried their own `as unknown as JsonObject`
-*  with the justification re-argued in eight slightly different comments —
-*  which is how a rule stops being reviewable. */
-var toJsonObject = (payload) => payload;
-var isExpired = (command, now) => typeof command.expiresAt === "number" && now >= command.expiresAt;
-var byCreatedAt = (left, right) => (left.createdAt ?? 0) - (right.createdAt ?? 0);
-var REMOTE_HOST_PROTOCOL_VERSION = 2;
-var buildHostPresence = (channel, handlers, online) => ({
-	online,
-	hostId: channel.hostId,
-	protocolVersion: 2,
-	capabilities: Object.keys(handlers)
-});
-var commandsCollection = (firestore, channel) => collection(firestore, "users", channel.uid, "hosts", channel.hostId, "commands");
-var hostDoc = (firestore, channel) => doc(firestore, "users", channel.uid, "hosts", channel.hostId);
-//#endregion
-export { REMOTE_HOST_PROTOCOL_VERSION, buildHostPresence, byCreatedAt, commandsCollection, hostDoc, isExpired, toJsonObject };
-
-//# sourceMappingURL=index.js.map
+import { a as hostDoc, c as RUNNER_HEALTH_STATES, i as commandsCollection, l as isRunnerHealth, n as buildHostPresence, o as isExpired, r as byCreatedAt, s as toJsonObject, t as REMOTE_HOST_PROTOCOL_VERSION, u as isRunnerHealthState } from "../remote-host-D_BRFHcI.js";
+export { REMOTE_HOST_PROTOCOL_VERSION, RUNNER_HEALTH_STATES, buildHostPresence, byCreatedAt, commandsCollection, hostDoc, isExpired, isRunnerHealth, isRunnerHealthState, toJsonObject };

package/dist/remote-host/server/firestoreSafeResult.d.ts

@@ -1,11 +1,13 @@
 /** Path reported for a reply that is itself `undefined` — it has no field name. */
 export declare const ROOT_PATH = "(root)";
-/** Every path holding `undefined`, in `a.b.0.c` form. Empty when the value is safe to write. */
+/** Every path holding `undefined`, in `a.b.0.c` form. Empty when the value is safe to write.
+ *  Throws on a circular reply, naming the path it closed the loop at. */
 export declare const undefinedPaths: (value: unknown, prefix?: string) => string[];
 /**
  * The same value with every `undefined` removed — object keys dropped, array holes
  * turned into `null` so the surrounding indexes still line up with what the sender
  * meant. Returns `unknown` because a stripped object is no longer the input type.
+ * Throws on a circular reply, same as `undefinedPaths`.
  */
 export declare const stripUndefined: (value: unknown) => unknown;
 /** Does `path` match `pattern`, where `*` stands for exactly one segment?

package/dist/remote-host/server/hostRunner.d.ts

@@ -1,7 +1,9 @@
 import { Firestore } from 'firebase/firestore';
 import { Channel, Command, CommandHandler, CommandHandlers } from '../index.js';
+export declare const DEFAULT_HEARTBEAT_MS = 60000;
 export declare const classifyListenerError: (error: unknown) => "transient" | "fatal";
-export declare const MAX_LISTEN_RETRIES = 5;
+export declare const LISTEN_RETRY_WINDOW_MS: number;
+export declare const shouldGiveUpListening: (downSinceMs: number, now: number, windowMs?: number) => boolean;
 export declare const backoffDelayMs: (attempt: number) => number;
 export interface HostEvent {
     phase: "received" | "done" | "error";
@@ -16,4 +18,5 @@ export interface HostRunnerOptions {
     expectedUndefined?: Record<string, readonly string[]>;
 }
 export declare const resolveCommandHandler: (handlers: CommandHandlers, method: string) => CommandHandler | undefined;
+export declare const presenceStaleAfterMs: (options?: HostRunnerOptions) => number;
 export declare const startHostRunner: (firestore: Firestore, channel: Channel, handlers: CommandHandlers, options?: HostRunnerOptions) => (() => void);

package/dist/remote-host/server/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_dist = require("../../dist-pWpC-b04.cjs");
-const require_remote_host_index = require("../index.cjs");
+const require_remote_host = require("../../remote-host-DkDVxNim.cjs");
 let firebase_firestore = require("firebase/firestore");
 let firebase_auth = require("firebase/auth");
 let firebase_app = require("firebase/app");
@@ -10,25 +10,36 @@ var isPlainObject = (value) => {
 	return proto === Object.prototype || proto === null;
 };
 var isWalkable = (value) => typeof value === "object" && value !== null && (Array.isArray(value) || isPlainObject(value));
-/** Every path holding `undefined`, in `a.b.0.c` form. Empty when the value is safe to write. */
-var undefinedPaths = (value, prefix = "") => {
+var childPath = (prefix, key) => prefix ? `${prefix}.${key}` : String(key);
+var withCycleGuard = (value, ancestors, path, walk) => {
+	if (ancestors.has(value)) throw new Error(`circular reference at ${path || "(root)"} — Firestore cannot serialise it`);
+	ancestors.add(value);
+	try {
+		return walk();
+	} finally {
+		ancestors.delete(value);
+	}
+};
+var pathsIn = (value, prefix, ancestors) => {
 	if (value === void 0) return [prefix || "(root)"];
 	if (!isWalkable(value)) return [];
-	const child = (key) => prefix ? `${prefix}.${key}` : String(key);
-	if (Array.isArray(value)) return Array.from(value).flatMap((item, index) => undefinedPaths(item, child(index)));
-	return Object.entries(value).flatMap(([key, item]) => undefinedPaths(item, child(key)));
+	return withCycleGuard(value, ancestors, prefix, () => Array.isArray(value) ? Array.from(value).flatMap((item, index) => pathsIn(item, childPath(prefix, index), ancestors)) : Object.entries(value).flatMap(([key, item]) => pathsIn(item, childPath(prefix, key), ancestors)));
+};
+/** Every path holding `undefined`, in `a.b.0.c` form. Empty when the value is safe to write.
+*  Throws on a circular reply, naming the path it closed the loop at. */
+var undefinedPaths = (value, prefix = "") => pathsIn(value, prefix, /* @__PURE__ */ new WeakSet());
+var strippedIn = (value, prefix, ancestors) => {
+	if (value === void 0) return null;
+	if (!isWalkable(value)) return value;
+	return withCycleGuard(value, ancestors, prefix, () => Array.isArray(value) ? Array.from(value, (item, index) => strippedIn(item, childPath(prefix, index), ancestors)) : Object.fromEntries(Object.entries(value).flatMap(([key, item]) => item === void 0 ? [] : [[key, strippedIn(item, childPath(prefix, key), ancestors)]])));
 };
 /**
 * The same value with every `undefined` removed — object keys dropped, array holes
 * turned into `null` so the surrounding indexes still line up with what the sender
 * meant. Returns `unknown` because a stripped object is no longer the input type.
+* Throws on a circular reply, same as `undefinedPaths`.
 */
-var stripUndefined = (value) => {
-	if (value === void 0) return null;
-	if (!isWalkable(value)) return value;
-	if (Array.isArray(value)) return Array.from(value, (item) => stripUndefined(item));
-	return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => item === void 0 ? [] : [[key, stripUndefined(item)]]));
-};
+var stripUndefined = (value) => strippedIn(value, "", /* @__PURE__ */ new WeakSet());
 /** Does `path` match `pattern`, where `*` stands for exactly one segment?
 *  Segment-wise rather than by regex: no escaping of user-supplied dots, and no
 *  pattern can turn into a catastrophic backtrack. */
@@ -50,6 +61,42 @@ var matchesPathPattern = (path, pattern) => {
 */
 var unexpectedPaths = (paths, expected = []) => paths.filter((path) => !expected.some((pattern) => matchesPathPattern(path, pattern)));
 //#endregion
+//#region src/remote-host/server/presenceBeat.ts
+var PRESENCE_STALE_BEATS = 3;
+var errorText$1 = (error) => error instanceof Error ? error.message : String(error);
+var notify = (report, onThrow) => {
+	try {
+		report();
+	} catch (error) {
+		onThrow?.(error);
+	}
+};
+var createPresenceBeat = (deps) => {
+	const now = deps.now ?? Date.now;
+	const state = { lastAckMs: now() };
+	const announce = (online) => {
+		const fail = (error) => notify(() => deps.onError(errorText$1(error)));
+		const ack = () => notify(() => {
+			state.lastAckMs = now();
+		});
+		notify(() => {
+			deps.write(online).then(ack, fail);
+		}, fail);
+	};
+	const beat = () => {
+		const silentMs = now() - state.lastAckMs;
+		if (silentMs >= deps.staleAfterMs) {
+			notify(() => deps.onStale(silentMs));
+			return;
+		}
+		announce(true);
+	};
+	return {
+		announce,
+		beat
+	};
+};
+//#endregion
 //#region src/remote-host/server/hostRunner.ts
 var DEFAULT_HEARTBEAT_MS = 6e4;
 var TRANSIENT_LISTEN_ERROR_CODES = /* @__PURE__ */ new Set([
@@ -58,6 +105,7 @@ var TRANSIENT_LISTEN_ERROR_CODES = /* @__PURE__ */ new Set([
 	"deadline-exceeded",
 	"internal",
 	"resource-exhausted",
+	"unauthenticated",
 	"unavailable"
 ]);
 var isRecord$1 = (value) => typeof value === "object" && value !== null;
@@ -65,6 +113,8 @@ var listenErrorCode = (error) => isRecord$1(error) && typeof error.code === "str
 var classifyListenerError = (error) => TRANSIENT_LISTEN_ERROR_CODES.has(listenErrorCode(error)) ? "transient" : "fatal";
 var BASE_LISTEN_RETRY_MS = 1e3;
 var MAX_LISTEN_RETRY_MS = 3e4;
+var LISTEN_RETRY_WINDOW_MS = 5 * 6e4;
+var shouldGiveUpListening = (downSinceMs, now, windowMs = LISTEN_RETRY_WINDOW_MS) => now - downSinceMs >= windowMs;
 var backoffDelayMs = (attempt) => Math.min(MAX_LISTEN_RETRY_MS, BASE_LISTEN_RETRY_MS * 2 ** attempt);
 var noop$2 = () => void 0;
 var writeError = (ref, code, message) => (0, firebase_firestore.updateDoc)(ref, {
@@ -146,7 +196,7 @@ var expireCommand = async (ref, command, options, uid) => {
 };
 var processCommand = async (ctx, ref, command, now) => {
 	const { handlers, options } = ctx;
-	if (require_remote_host_index.isExpired(command, now)) {
+	if (require_remote_host.isExpired(command, now)) {
 		await expireCommand(ref, command, options, ctx.uid);
 		return;
 	}
@@ -173,7 +223,7 @@ var dispatchAddedCommands = (ctx, snapshot) => {
 	snapshot.docChanges().filter((change) => change.type === "added").map((change) => ({
 		ref: change.doc.ref,
 		command: change.doc.data()
-	})).sort((left, right) => require_remote_host_index.byCreatedAt(left.command, right.command)).forEach(({ ref, command }) => {
+	})).sort((left, right) => require_remote_host.byCreatedAt(left.command, right.command)).forEach(({ ref, command }) => {
 		processCommand(ctx, ref, command, now).catch(noop$2);
 	});
 };
@@ -188,7 +238,9 @@ function handleListenError(run, error) {
 		message: error.message
 	});
 	if (run.stopped) return;
-	if (classifyListenerError(error) === "fatal" || run.attempt >= 5) {
+	const now = Date.now();
+	run.downSinceMs ??= now;
+	if (classifyListenerError(error) === "fatal" || shouldGiveUpListening(run.downSinceMs, now)) {
 		run.goOffline();
 		return;
 	}
@@ -199,6 +251,7 @@ function subscribeCommands(run) {
 	if (run.stopped) return;
 	run.unsubscribe = (0, firebase_firestore.onSnapshot)(run.queuedCommands, (snapshot) => {
 		run.attempt = 0;
+		run.downSinceMs = null;
 		dispatchAddedCommands(run.ctx, snapshot);
 	}, (error) => handleListenError(run, error));
 }
@@ -210,7 +263,8 @@ var listenForCommands = (queuedCommands, ctx, goOffline) => {
 		stopped: false,
 		unsubscribe: noop$2,
 		retryTimer: null,
-		attempt: 0
+		attempt: 0,
+		downSinceMs: null
 	};
 	subscribeCommands(run);
 	return () => {
@@ -219,36 +273,265 @@ var listenForCommands = (queuedCommands, ctx, goOffline) => {
 		run.unsubscribe();
 	};
 };
-var startHostRunner = (firestore, channel, handlers, options = {}) => {
-	const presence = require_remote_host_index.hostDoc(firestore, channel);
-	const writePresence = (online) => {
-		(0, firebase_firestore.setDoc)(presence, {
-			...require_remote_host_index.buildHostPresence(channel, handlers, online),
+var heartbeatMs = (options) => options.heartbeatMs ?? 6e4;
+var presenceStaleAfterMs = (options = {}) => heartbeatMs(options) * 3;
+var buildPresenceBeat = (firestore, channel, handlers, options, onStale) => {
+	const presence = require_remote_host.hostDoc(firestore, channel);
+	const report = (message) => options.onEvent?.({
+		phase: "error",
+		method: "presence",
+		message
+	});
+	return createPresenceBeat({
+		write: (online) => (0, firebase_firestore.setDoc)(presence, {
+			...require_remote_host.buildHostPresence(channel, handlers, online),
 			updatedAt: (0, firebase_firestore.serverTimestamp)()
-		}).catch(noop$2);
-	};
-	const announce = () => {
-		writePresence(true);
+		}),
+		onError: (message) => report(`presence write failed: ${message}`),
+		onStale: (silentMs) => {
+			report(`no presence write acknowledged for ${Math.round(silentMs / 1e3)}s — the remote cannot see this host`);
+			onStale();
+		},
+		staleAfterMs: presenceStaleAfterMs(options)
+	});
+};
+var shutDown = (run, presence) => {
+	if (run.closed) return;
+	run.closed = true;
+	if (run.beat) clearInterval(run.beat);
+	run.beat = null;
+	presence.announce(false);
+	run.stopListening();
+};
+var startHostRunner = (firestore, channel, handlers, options = {}) => {
+	const run = {
+		beat: null,
+		stopListening: noop$2,
+		closed: false
 	};
-	announce();
-	const beat = setInterval(announce, options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
-	const queuedCommands = (0, firebase_firestore.query)(require_remote_host_index.commandsCollection(firestore, channel), (0, firebase_firestore.where)("status", "==", "queued"));
-	const ctx = {
+	const presence = buildPresenceBeat(firestore, channel, handlers, options, goOffline);
+	function goOffline() {
+		if (run.closed) return;
+		shutDown(run, presence);
+		options.onClosed?.();
+	}
+	presence.announce(true);
+	run.beat = setInterval(presence.beat, heartbeatMs(options));
+	run.stopListening = listenForCommands((0, firebase_firestore.query)(require_remote_host.commandsCollection(firestore, channel), (0, firebase_firestore.where)("status", "==", "queued")), {
 		firestore,
 		handlers,
 		options,
 		uid: channel.uid
+	}, goOffline);
+	return () => shutDown(run, presence);
+};
+//#endregion
+//#region src/remote-host/server/resilientRunner.ts
+var ONE_SECOND_MS$1 = 1e3;
+var ONE_MINUTE_MS = 60 * ONE_SECOND_MS$1;
+var RECONNECT_BASE_MS = ONE_SECOND_MS$1;
+var RECONNECT_MAX_MS = ONE_MINUTE_MS;
+var SETTLE_MS = ONE_MINUTE_MS;
+var GIVE_UP_MS = 5 * ONE_MINUTE_MS;
+var PROBE_INTERVAL_MS = 90 * ONE_SECOND_MS$1;
+var reconnectDelayMs = (attempt) => Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** attempt);
+var errorText = (error) => error instanceof Error ? error.message : String(error);
+var scheduleWithTimeout = (task, delayMs) => {
+	const timer = setTimeout(task, delayMs);
+	return () => clearTimeout(timer);
+};
+var setState = (ctx, next) => {
+	ctx.state = next;
+	try {
+		ctx.deps.onHealth?.({
+			state: next,
+			lastError: ctx.lastError,
+			changedAt: ctx.now()
+		});
+	} catch (error) {
+		ctx.deps.log.warn(`host runner health observer threw: ${errorText(error)}`);
+	}
+};
+var clearTimer = (ctx) => {
+	ctx.cancelTimer?.();
+	ctx.cancelTimer = null;
+};
+var clearProbe = (ctx) => {
+	ctx.cancelProbe?.();
+	ctx.cancelProbe = null;
+};
+function scheduleProbe(ctx) {
+	if (ctx.stopped || !ctx.deps.checkAlive) return;
+	clearProbe(ctx);
+	ctx.cancelProbe = ctx.schedule(() => void runProbe(ctx), PROBE_INTERVAL_MS);
+}
+var STALE_REASON = "presence went stale — the phone can no longer see this host";
+async function askAlive(ctx) {
+	try {
+		return {
+			alive: await ctx.deps.checkAlive?.() ?? null,
+			reason: STALE_REASON
+		};
+	} catch (error) {
+		return {
+			alive: false,
+			reason: `presence probe failed: ${errorText(error)}`
+		};
+	}
+}
+async function runProbe(ctx) {
+	ctx.cancelProbe = null;
+	if (ctx.stopped || ctx.state !== "online") return;
+	const answer = await askAlive(ctx);
+	if (ctx.stopped || ctx.state !== "online") return;
+	if (answer.alive === false) {
+		ctx.lastError = answer.reason;
+		ctx.deps.log.warn(`host runner ${answer.reason}`);
+		onUnderlyingClosed(ctx);
+		return;
+	}
+	scheduleProbe(ctx);
+}
+var releaseUnderlying = (ctx) => {
+	const stop = ctx.stopUnderlying;
+	ctx.stopUnderlying = null;
+	try {
+		stop?.();
+	} catch (error) {
+		ctx.deps.log.warn(`host runner teardown failed: ${errorText(error)}`);
+	}
+};
+var markRecovered = (ctx) => {
+	ctx.downSinceMs = null;
+	ctx.attempt = 0;
+	ctx.lastError = null;
+	if (ctx.state === "online") return;
+	ctx.deps.log.info("host runner re-subscribed");
+	setState(ctx, "online");
+	scheduleProbe(ctx);
+};
+async function settle(ctx) {
+	ctx.cancelTimer = null;
+	if (ctx.stopped) return;
+	const answer = await askAlive(ctx);
+	if (ctx.stopped) return;
+	if (answer.alive === false) {
+		ctx.lastError = answer.reason;
+		ctx.deps.log.warn(`host runner is up but still unreachable — ${answer.reason}`);
+		onUnderlyingClosed(ctx);
+		return;
+	}
+	markRecovered(ctx);
+}
+var giveUp = (ctx) => {
+	ctx.stopped = true;
+	clearProbe(ctx);
+	ctx.deps.log.warn(`host runner stayed down for ${Math.round(GIVE_UP_MS / ONE_SECOND_MS$1)}s, giving up (${ctx.lastError ?? "no error reported"})`);
+	setState(ctx, "offline");
+	ctx.deps.options.onClosed?.();
+};
+function scheduleRelaunch(ctx) {
+	const delayMs = reconnectDelayMs(ctx.attempt);
+	ctx.attempt += 1;
+	ctx.deps.log.warn(`host runner closed (${ctx.lastError ?? "no error reported"}); re-subscribing in ${Math.round(delayMs / ONE_SECOND_MS$1)}s`);
+	if (ctx.state !== "reconnecting") setState(ctx, "reconnecting");
+	ctx.cancelTimer = ctx.schedule(() => launch(ctx), delayMs);
+}
+function onUnderlyingClosed(ctx) {
+	if (ctx.stopped) return;
+	releaseUnderlying(ctx);
+	clearTimer(ctx);
+	clearProbe(ctx);
+	ctx.downSinceMs ??= ctx.now();
+	if (ctx.now() - ctx.downSinceMs >= GIVE_UP_MS) giveUp(ctx);
+	else scheduleRelaunch(ctx);
+}
+var CHANNEL_METHODS = /* @__PURE__ */ new Set(["listen", "presence"]);
+var runnerOptions = (ctx) => ({
+	...ctx.deps.options,
+	onEvent: (event) => {
+		if (event.phase === "error") {
+			const text = `${event.method}: ${event.message ?? "no detail"}`;
+			if (CHANNEL_METHODS.has(event.method)) ctx.lastError = text;
+			ctx.deps.log.warn(`host runner event error — ${text}`);
+		}
+		ctx.deps.options.onEvent?.(event);
+	},
+	onClosed: () => onUnderlyingClosed(ctx)
+});
+function launch(ctx) {
+	ctx.cancelTimer = null;
+	if (ctx.stopped) return;
+	try {
+		ctx.stopUnderlying = ctx.deps.start(runnerOptions(ctx));
+	} catch (error) {
+		ctx.lastError = errorText(error);
+		onUnderlyingClosed(ctx);
+		return;
+	}
+	ctx.cancelTimer = ctx.schedule(() => void settle(ctx), SETTLE_MS);
+}
+function startResilientHostRunner(deps) {
+	const ctx = {
+		deps,
+		schedule: deps.schedule ?? scheduleWithTimeout,
+		now: deps.now ?? Date.now,
+		stopUnderlying: null,
+		cancelTimer: null,
+		attempt: 0,
+		downSinceMs: null,
+		lastError: null,
+		state: "online",
+		stopped: false,
+		cancelProbe: null
 	};
-	const goOffline = () => {
-		clearInterval(beat);
-		writePresence(false);
-		options.onClosed?.();
-	};
-	const stopListening = listenForCommands(queuedCommands, ctx, goOffline);
+	setState(ctx, "online");
+	launch(ctx);
+	scheduleProbe(ctx);
 	return () => {
-		clearInterval(beat);
-		writePresence(false);
-		stopListening();
+		ctx.stopped = true;
+		clearTimer(ctx);
+		clearProbe(ctx);
+		releaseUnderlying(ctx);
+	};
+}
+//#endregion
+//#region src/remote-host/server/presenceProbe.ts
+var ONE_SECOND_MS = 1e3;
+var PRESENCE_STALE_MS = presenceStaleAfterMs();
+var PROBE_TIMEOUT_MS = 30 * ONE_SECOND_MS;
+var hasToMillis = (value) => "toMillis" in value && typeof Reflect.get(value, "toMillis") === "function";
+var asMillis = (value) => {
+	if (typeof value === "number") return value;
+	if (typeof value === "object" && value !== null && hasToMillis(value)) return value.toMillis();
+	return null;
+};
+/** Judge a presence document that was read successfully. Exported for its own test:
+*  the freshness rule is the part worth pinning, and it needs no Firestore. */
+var presenceIsFresh = (data, now, staleAfterMs = PRESENCE_STALE_MS) => {
+	if (!data) return null;
+	const updatedAt = asMillis(data.updatedAt);
+	if (updatedAt === null) return null;
+	if (data.online === false) return null;
+	return now - updatedAt < staleAfterMs;
+};
+/** Reject once `timeoutMs` has passed, so a stalled read answers instead of hanging. */
+var withTimeout = async (work, timeoutMs) => {
+	const timer = { handle: null };
+	const deadline = new Promise((_, reject) => {
+		timer.handle = setTimeout(() => reject(/* @__PURE__ */ new Error(`presence read did not answer within ${Math.round(timeoutMs / ONE_SECOND_MS)}s`)), timeoutMs);
+	});
+	try {
+		return await Promise.race([work, deadline]);
+	} finally {
+		if (timer.handle) clearTimeout(timer.handle);
+	}
+};
+/** Reads the host's own presence document from the server and reports whether it is fresh. */
+var createPresenceProbe = (deps) => {
+	const now = deps.now ?? Date.now;
+	return async () => {
+		return presenceIsFresh((await withTimeout((0, firebase_firestore.getDocFromServer)(require_remote_host.hostDoc(deps.firestore(), deps.channel)), deps.timeoutMs ?? PROBE_TIMEOUT_MS)).data(), now(), deps.staleAfterMs ?? PRESENCE_STALE_MS);
 	};
 };
 //#endregion
@@ -259,6 +542,7 @@ var silentLogger = {
 	warn: noop$1,
 	debug: noop$1
 };
+var eventText = (event) => event.message ? `${event.phase} ${event.method} — ${event.message}` : `${event.phase} ${event.method}`;
 var createRemoteHost = (deps) => {
 	const log = deps.log ?? silentLogger;
 	let stopRunner = null;
@@ -284,7 +568,7 @@ var createRemoteHost = (deps) => {
 			uid,
 			hostId: deps.hostId
 		}, deps.handlers, {
-			onEvent: (event) => log.debug(`host event: ${event.phase} ${event.method}`),
+			onEvent: (event) => log.debug(`host event: ${eventText(event)}`),
 			onExpire: deps.onExpire,
 			onClosed: () => {
 				if (stopRunner === runner) {
@@ -481,15 +765,25 @@ var createRemoteHostSession = (config) => {
 	};
 };
 //#endregion
+exports.DEFAULT_HEARTBEAT_MS = DEFAULT_HEARTBEAT_MS;
+exports.LISTEN_RETRY_WINDOW_MS = LISTEN_RETRY_WINDOW_MS;
+exports.PRESENCE_STALE_BEATS = PRESENCE_STALE_BEATS;
+exports.PRESENCE_STALE_MS = PRESENCE_STALE_MS;
 exports.createHostSessionPersistence = createHostSessionPersistence;
+exports.createPresenceProbe = createPresenceProbe;
 exports.createRemoteHost = createRemoteHost;
 exports.createRemoteHostAuth = createRemoteHostAuth;
 exports.createRemoteHostFirebase = createRemoteHostFirebase;
 exports.createRemoteHostSession = createRemoteHostSession;
 exports.isSeedableBlob = isSeedableBlob;
+exports.presenceIsFresh = presenceIsFresh;
+exports.presenceStaleAfterMs = presenceStaleAfterMs;
+exports.reconnectDelayMs = reconnectDelayMs;
 exports.startHostRunner = startHostRunner;
+exports.startResilientHostRunner = startResilientHostRunner;
 exports.stripUndefined = stripUndefined;
 exports.undefinedPaths = undefinedPaths;
 exports.unexpectedPaths = unexpectedPaths;
+exports.withTimeout = withTimeout;
 
 //# sourceMappingURL=index.cjs.map