@openclaw/facetime 0.0.0 → 2026.9.6

package/src/runtime-call-events.ts

@@ -0,0 +1,407 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import type { RuntimeLogger } from "openclaw/plugin-sdk/plugin-runtime";
+import {
+  isActiveCall,
+  isEndedCall,
+  isIncomingRingingCall,
+  isOutgoingRingingCall,
+  isUnknownCallStatus,
+  isVerifiedFaceTimeTransport,
+  normalizeFaceTimeHandle,
+  resolveAuthorizedFaceTimeOwner,
+  type AuthenticatedFaceTimeOwner,
+  type FaceTimeCallStatusEvent,
+} from "./call-events.js";
+import type { FaceTimeCallRegistry } from "./call-lifecycle.js";
+import type { FaceTimeConfig } from "./config.js";
+import {
+  projectFaceTimeNativeAction,
+  type FaceTimeHelperPeer,
+  type FaceTimeHelperSocketServer,
+} from "./helper-rpc.js";
+import {
+  doesFaceTimeCallMatchPendingDial,
+  retainFaceTimeDialCallUUID,
+  type PendingFaceTimeDial,
+} from "./outbound-call.js";
+import { retainHelperResultPeers } from "./runtime-helper-results.js";
+import {
+  createManagedCall,
+  readCallUUID,
+  updateCallStatus,
+  type ActiveFaceTimeCall,
+} from "./runtime-state.js";
+
+type CallControl = {
+  activateCallTalk(call: ActiveFaceTimeCall, options: { unmute: boolean }): Promise<void>;
+  attemptCarrierHangup(call: ActiveFaceTimeCall, reason: string): Promise<boolean>;
+  closeCall(call: ActiveFaceTimeCall, reason: string): Promise<void>;
+  startCallTalk(call: ActiveFaceTimeCall): Promise<void>;
+};
+
+export function createFaceTimeCallEventHandler(params: {
+  calls: FaceTimeCallRegistry<ActiveFaceTimeCall>;
+  helper: FaceTimeHelperSocketServer;
+  config: FaceTimeConfig;
+  logger: RuntimeLogger;
+  callControl: CallControl;
+  isStopping: () => boolean;
+  isDriverInstallPending: () => boolean;
+  getPendingDial: () => PendingFaceTimeDial | undefined;
+  clearPendingDial: () => Promise<void>;
+  persistPendingDial: () => Promise<void>;
+  outboundCarrierPeers: ReadonlyMap<number, FaceTimeHelperPeer>;
+  cancelPendingDial: (pending: PendingFaceTimeDial) => Promise<void>;
+}) {
+  const eventIdentities = (event: FaceTimeCallStatusEvent): string[] =>
+    [
+      event.data.call_uuid,
+      event.data.dial_id,
+      event.data.proxy_identifier,
+      event.data.conversation_uuid,
+    ].filter(
+      (identity): identity is string => typeof identity === "string" && identity.trim() !== "",
+    );
+  const resolveEventCall = (event: FaceTimeCallStatusEvent) => {
+    for (const identity of eventIdentities(event)) {
+      const call = params.calls.get(identity);
+      if (call) {
+        return call;
+      }
+    }
+    return undefined;
+  };
+  const canPromotePendingDial = (pending: PendingFaceTimeDial) =>
+    !params.isStopping() &&
+    params.getPendingDial() === pending &&
+    pending.delivery !== "cancelling";
+  const authorizePendingDial = async (
+    event: FaceTimeCallStatusEvent,
+    pending: PendingFaceTimeDial,
+  ): Promise<AuthenticatedFaceTimeOwner | undefined> => {
+    retainFaceTimeDialCallUUID(pending, readCallUUID(event));
+    await params.persistPendingDial();
+    if (params.isStopping() || params.getPendingDial() !== pending) {
+      return undefined;
+    }
+    const owner =
+      pending.delivery === "cancelling"
+        ? undefined
+        : resolveAuthorizedFaceTimeOwner({
+            event,
+            ownerHandles: params.config.ownerHandles,
+          });
+    if (owner) {
+      return owner;
+    }
+    if (pending.delivery !== "cancelling") {
+      params.logger.warn(
+        "[facetime] cancelling correlated outbound call because its handle is no longer authorized; add it to ownerHandles before dialing again",
+      );
+    }
+    try {
+      await params.cancelPendingDial(pending);
+    } catch (error) {
+      params.logger.warn(
+        `[facetime] outbound authorization cancellation remains pending: ${formatErrorMessage(error)}`,
+      );
+    }
+    return undefined;
+  };
+  const retainAliases = (call: ActiveFaceTimeCall, event: FaceTimeCallStatusEvent) => {
+    for (const alias of [
+      event.data.call_uuid,
+      event.data.dial_id,
+      event.data.proxy_identifier,
+      event.data.conversation_uuid,
+      event.data.conversation_group_uuid,
+    ]) {
+      if (typeof alias === "string" && alias.trim()) {
+        params.calls.retainAlias(call, alias);
+      }
+    }
+    call.carrierCallUUIDs.add(String(event.data.call_uuid));
+  };
+  const retainPendingDial = (call: ActiveFaceTimeCall, pending: PendingFaceTimeDial) => {
+    params.calls.retainAlias(call, pending.dialID);
+    if (pending.proxyIdentifier) {
+      params.calls.retainAlias(call, pending.proxyIdentifier);
+    }
+    for (const alias of pending.callUUIDAliases ?? []) {
+      params.calls.retainAlias(call, alias);
+      call.carrierCallUUIDs.add(alias);
+    }
+    for (const carrierPeer of params.outboundCarrierPeers.values()) {
+      call.carrierPeers.set(carrierPeer.processId, carrierPeer);
+    }
+  };
+  const answerIncoming = async (
+    event: FaceTimeCallStatusEvent,
+    owner: AuthenticatedFaceTimeOwner,
+    peer?: FaceTimeHelperPeer,
+  ) => {
+    const callUUID = readCallUUID(event);
+    if (params.isDriverInstallPending()) {
+      params.logger.warn("[facetime] ignored incoming call; audio driver installation is pending");
+      return;
+    }
+    if (resolveEventCall(event)) {
+      return;
+    }
+    if (params.calls.size > 0) {
+      params.logger.warn("[facetime] ignored incoming call; another FaceTime bridge is active");
+      return;
+    }
+    const call = createManagedCall({
+      callUUID,
+      phase: "ringing",
+      owner,
+      handle: normalizeFaceTimeHandle(event.data.handle),
+      peer,
+    });
+    updateCallStatus(call, event);
+    params.calls.create(call);
+    retainAliases(call, event);
+    let answerAttempted = false;
+    try {
+      await params.callControl.startCallTalk(call);
+      if (
+        call.lifecycleAbort.signal.aborted ||
+        params.calls.active !== call ||
+        call.carrierHangupPending
+      ) {
+        throw new Error("FaceTime call closed before answer");
+      }
+      const generation = call.beginAnswering();
+      answerAttempted = true;
+      const answerResult = await call.runCarrierCommand({
+        generation,
+        action: async () => await params.helper.answerCall(callUUID),
+      });
+      projectFaceTimeNativeAction("answer", answerResult);
+      retainHelperResultPeers(call, answerResult);
+      await params.callControl.activateCallTalk(call, { unmute: true });
+      params.logger.info("[facetime] answered authorized FaceTime call");
+    } catch (error) {
+      params.logger.warn(`[facetime] failed to answer FaceTime call: ${formatErrorMessage(error)}`);
+      if (answerAttempted) {
+        await params.callControl.attemptCarrierHangup(call, "answer-failed");
+        return;
+      }
+      await params.callControl.closeCall(call, "answer-failed").catch((closeError: unknown) => {
+        params.logger.warn(
+          `[facetime] answer failure cleanup failed: ${formatErrorMessage(closeError)}`,
+        );
+      });
+    }
+  };
+  const activate = async (
+    event: FaceTimeCallStatusEvent,
+    owner?: AuthenticatedFaceTimeOwner,
+    peer?: FaceTimeHelperPeer,
+    pending?: PendingFaceTimeDial,
+  ) => {
+    const callUUID = readCallUUID(event);
+    if (params.isDriverInstallPending()) {
+      params.logger.warn("[facetime] ignored active call; audio driver installation is pending");
+      return;
+    }
+    let call = resolveEventCall(event);
+    if (!call) {
+      if (!owner) {
+        params.logger.warn("[facetime] refused active call without authenticated owner");
+        return;
+      }
+      if (params.calls.size > 0) {
+        params.logger.warn("[facetime] ignored active call; another FaceTime bridge is active");
+        return;
+      }
+      call = createManagedCall({
+        callUUID,
+        phase: "active",
+        owner,
+        handle: normalizeFaceTimeHandle(event.data.handle),
+        peer,
+      });
+      params.calls.create(call);
+      retainAliases(call, event);
+    }
+    if (pending) {
+      retainPendingDial(call, pending);
+    }
+    if (peer) {
+      call.carrierPeers.set(peer.processId, peer);
+    }
+    // Apple can replace the ringing call object when it becomes active. Keep
+    // lifecycle identity stable, but direct subsequent commands to this owner event's UUID.
+    call.promoteCarrierCallUUID(callUUID);
+    updateCallStatus(call, event);
+    try {
+      await params.callControl.startCallTalk(call);
+      await params.callControl.activateCallTalk(call, { unmute: true });
+      params.logger.info("[facetime] realtime talk session active");
+    } catch (error) {
+      if (call.lifecycleAbort.signal.aborted || params.calls.active !== call) {
+        return;
+      }
+      params.logger.warn(`[facetime] failed to start realtime talk: ${formatErrorMessage(error)}`);
+      await params.callControl.attemptCarrierHangup(call, "talk-start-failed");
+    }
+  };
+  const handleCallEvent = async (event: FaceTimeCallStatusEvent, peer?: FaceTimeHelperPeer) => {
+    if (params.isStopping()) {
+      return;
+    }
+    const callUUID = readCallUUID(event);
+    const existingCall = resolveEventCall(event);
+    const pending = params.getPendingDial();
+    if (existingCall) {
+      if (peer) {
+        existingCall.carrierPeers.set(peer.processId, peer);
+      }
+      updateCallStatus(existingCall, event);
+      retainAliases(existingCall, event);
+    }
+    const verifiedTransport = isVerifiedFaceTimeTransport(event);
+    if (existingCall && !verifiedTransport && !isEndedCall(event)) {
+      params.logger.warn(
+        "[facetime] managed call transport lost FaceTime verification; closing fail-closed",
+      );
+      await params.callControl.attemptCarrierHangup(existingCall, "transport-verification-lost");
+      return;
+    }
+    if (
+      pending &&
+      !existingCall &&
+      event.data.is_outgoing !== true &&
+      (isIncomingRingingCall(event) || isActiveCall(event))
+    ) {
+      params.logger.info("[facetime] ignored incoming call; an outbound FaceTime call is pending");
+      return;
+    }
+    if (isIncomingRingingCall(event)) {
+      const owner = resolveAuthorizedFaceTimeOwner({
+        event,
+        ownerHandles: params.config.ownerHandles,
+      });
+      if (owner) {
+        await answerIncoming(event, owner, peer);
+      } else {
+        params.logger.info("[facetime] ignored unauthorized incoming FaceTime call");
+      }
+      return;
+    }
+    if (isOutgoingRingingCall(event)) {
+      if (verifiedTransport && pending && doesFaceTimeCallMatchPendingDial({ event, pending })) {
+        const owner = await authorizePendingDial(event, pending);
+        if (!owner || !canPromotePendingDial(pending)) {
+          return;
+        }
+        let ringingCall = resolveEventCall(event);
+        if (!ringingCall && params.calls.size === 0) {
+          ringingCall = createManagedCall({
+            callUUID,
+            phase: "ringing",
+            owner,
+            handle: normalizeFaceTimeHandle(event.data.handle),
+            peer,
+          });
+          updateCallStatus(ringingCall, event);
+          params.calls.create(ringingCall);
+          retainAliases(ringingCall, event);
+          retainPendingDial(ringingCall, pending);
+        }
+        if (ringingCall) {
+          try {
+            const generation = ringingCall.captureGeneration();
+            const muteResult = await ringingCall.runCarrierCommand({
+              generation,
+              action: async () => await params.helper.safetyMute(ringingCall.carrierCallUUID),
+            });
+            ringingCall.lastHelperAction = muteResult;
+            retainHelperResultPeers(ringingCall, muteResult);
+            projectFaceTimeNativeAction("safe-mute", muteResult);
+          } catch (error) {
+            params.logger.warn(
+              `[facetime] outbound ringing safety mute failed: ${formatErrorMessage(error)}`,
+            );
+            await params.callControl.attemptCarrierHangup(
+              ringingCall,
+              "outbound-ringing-safety-mute-failed",
+            );
+          }
+        }
+      }
+      return;
+    }
+    if (isActiveCall(event)) {
+      const authorizedPending =
+        event.data.is_outgoing === true &&
+        verifiedTransport &&
+        pending &&
+        doesFaceTimeCallMatchPendingDial({ event, pending })
+          ? pending
+          : undefined;
+      const owner = authorizedPending
+        ? await authorizePendingDial(event, authorizedPending)
+        : event.data.is_outgoing === true
+          ? undefined
+          : resolveAuthorizedFaceTimeOwner({
+              event,
+              ownerHandles: params.config.ownerHandles,
+            });
+      if (authorizedPending && (!owner || !canPromotePendingDial(authorizedPending))) {
+        return;
+      }
+      const pendingCall = authorizedPending && params.calls.get(authorizedPending.dialID);
+      if (pendingCall) {
+        params.calls.retainAlias(pendingCall, callUUID);
+      }
+      if (!resolveEventCall(event) && !owner) {
+        params.logger.info("[facetime] ignored unauthorized active FaceTime call");
+        return;
+      }
+      await activate(event, owner, peer, authorizedPending);
+      if (
+        authorizedPending &&
+        canPromotePendingDial(authorizedPending) &&
+        params.calls.has(callUUID)
+      ) {
+        await params.clearPendingDial();
+      }
+      return;
+    }
+    if (isEndedCall(event)) {
+      const clearing =
+        event.data.is_outgoing === true &&
+        pending &&
+        doesFaceTimeCallMatchPendingDial({ event, pending })
+          ? params.clearPendingDial()
+          : undefined;
+      const endedCall = resolveEventCall(event);
+      if (endedCall) {
+        if (endedCall.retiredCarrierCallUUIDs.has(callUUID)) {
+          params.logger.debug?.(
+            "[facetime] ignored ended event for a stale carrier alias while another carrier is current",
+          );
+          await clearing;
+          return;
+        }
+        // Native terminal evidence revokes media immediately, even while SQLite settles.
+        endedCall.markCarrierClosed();
+        await Promise.all([clearing, params.callControl.closeCall(endedCall, "native-ended")]);
+      } else {
+        await clearing;
+      }
+      return;
+    }
+    if (isUnknownCallStatus(event)) {
+      const unknownCall = params.calls.get(callUUID);
+      if (unknownCall) {
+        params.logger.warn("[facetime] unknown native call status; closing carrier fail-closed");
+        await params.callControl.attemptCarrierHangup(unknownCall, "unknown-native-status");
+      }
+    }
+  };
+  return { handleCallEvent };
+}

package/src/runtime-carrier-process.ts

@@ -0,0 +1,79 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk/plugin-runtime";
+import type { FaceTimeHelperPeer } from "./helper-rpc.js";
+
+export async function terminateExactCarrierProcesses(params: {
+  runtime: { system: Pick<PluginRuntime["system"], "runCommandWithTimeout"> };
+  peers: ReadonlyMap<number, FaceTimeHelperPeer>;
+  assertCurrent: () => void;
+}): Promise<void> {
+  params.assertCurrent();
+  if (params.peers.size === 0) {
+    throw new Error(
+      "no authenticated carrier process identity is available for fail-closed shutdown",
+    );
+  }
+  for (const peer of params.peers.values()) {
+    const expected =
+      peer.bundleIdentifier === "com.apple.FaceTime"
+        ? "FaceTime"
+        : peer.bundleIdentifier === "com.apple.FaceTime.FTConversationService"
+          ? "FTConversationService"
+          : peer.bundleIdentifier === "com.apple.mobilephone"
+            ? "Phone"
+            : peer.bundleIdentifier === "com.apple.TelephonyUtilities"
+              ? "TelephonyUtilities"
+              : "";
+    const inspectExactProcess = async (): Promise<boolean> => {
+      const inspected = await params.runtime.system.runCommandWithTimeout(
+        ["/bin/ps", "-p", String(peer.processId), "-o", "comm="],
+        { timeoutMs: 500 },
+      );
+      params.assertCurrent();
+      if (inspected.code === 1 && !inspected.stdout.trim() && !inspected.stderr.trim()) {
+        return false;
+      }
+      const executable = inspected.stdout.trim();
+      if (
+        inspected.code !== 0 ||
+        !expected ||
+        (executable !== expected && !executable.endsWith(`/${expected}`))
+      ) {
+        throw new Error("authenticated carrier process identity no longer matches its executable");
+      }
+      const started = await params.runtime.system.runCommandWithTimeout(
+        ["/bin/ps", "-p", String(peer.processId), "-o", "lstart="],
+        { timeoutMs: 500 },
+      );
+      params.assertCurrent();
+      if (started.code === 1 && !started.stdout.trim() && !started.stderr.trim()) {
+        return false;
+      }
+      const observedStartedAt = Date.parse(started.stdout.trim());
+      if (
+        started.code !== 0 ||
+        !Number.isFinite(observedStartedAt) ||
+        observedStartedAt !== Math.floor(peer.processStartedAtMs / 1_000) * 1_000
+      ) {
+        throw new Error("authenticated carrier process identity no longer matches its executable");
+      }
+      return true;
+    };
+    let alive = await inspectExactProcess();
+    params.assertCurrent();
+    for (const signal of ["-TERM", "-KILL"]) {
+      if (!alive) {
+        break;
+      }
+      await params.runtime.system.runCommandWithTimeout(
+        ["/bin/kill", signal, String(peer.processId)],
+        { timeoutMs: 500 },
+      );
+      params.assertCurrent();
+      alive = await inspectExactProcess();
+      params.assertCurrent();
+    }
+    if (alive) {
+      throw new Error("authenticated carrier process remains alive after force termination");
+    }
+  }
+}

package/src/runtime-helper-results.ts

@@ -0,0 +1,197 @@
+import {
+  readHelperResults,
+  type FaceTimeHelperPeer,
+  type FaceTimeHelperSocketServer,
+  type HelperActionResult,
+} from "./helper-rpc.js";
+import { retainFaceTimeDialCallUUID, type PendingFaceTimeDial } from "./outbound-call.js";
+import type { ActiveFaceTimeCall } from "./runtime-state.js";
+
+export const OUTBOUND_DIAL_HELPER_BUNDLES = new Set([
+  "com.apple.FaceTime",
+  "com.apple.FaceTime.FTConversationService",
+]);
+
+function readHelperPeers(result: HelperActionResult): FaceTimeHelperPeer[] {
+  const peers: FaceTimeHelperPeer[] = [];
+  for (const entry of readHelperResults(result)) {
+    const peer = entry.helperPeer;
+    if (
+      peer &&
+      typeof peer === "object" &&
+      "processId" in peer &&
+      "bundleIdentifier" in peer &&
+      "connectionGeneration" in peer &&
+      "processStartedAtMs" in peer &&
+      typeof peer.processId === "number" &&
+      typeof peer.bundleIdentifier === "string" &&
+      typeof peer.connectionGeneration === "number" &&
+      typeof peer.processStartedAtMs === "number"
+    ) {
+      peers.push({
+        bundleIdentifier: peer.bundleIdentifier,
+        processId: peer.processId,
+        processStartedAtMs: peer.processStartedAtMs,
+        connectionGeneration: peer.connectionGeneration,
+      });
+    }
+  }
+  return peers;
+}
+
+export function retainHelperResultPeers(
+  call: ActiveFaceTimeCall,
+  result: HelperActionResult,
+): void {
+  for (const peer of readHelperPeers(result)) {
+    call.carrierPeers.set(peer.processId, peer);
+  }
+}
+
+export function retainOutboundDialHelperPeers(
+  peers: Map<number, FaceTimeHelperPeer>,
+  result: HelperActionResult,
+): void {
+  for (const entry of readHelperResults(result)) {
+    // An absence-only observer never becomes an owner required for later closure.
+    if (
+      entry.found === false &&
+      entry.retained_outbound_dial !== true &&
+      entry.cancelled !== true
+    ) {
+      continue;
+    }
+    for (const peer of readHelperPeers(entry)) {
+      if (OUTBOUND_DIAL_HELPER_BUNDLES.has(peer.bundleIdentifier)) {
+        peers.set(peer.processId, peer);
+      }
+    }
+  }
+}
+
+export function readOutboundCallUUID(result: HelperActionResult): string | undefined {
+  return readHelperResults(result)
+    .map((entry) =>
+      typeof entry.call_uuid === "string" && entry.call_uuid.trim()
+        ? entry.call_uuid.trim()
+        : undefined,
+    )
+    .find((value) => Boolean(value));
+}
+
+export function readOutboundProxyIdentifier(result: HelperActionResult): string | undefined {
+  return readHelperResults(result)
+    .map((entry) =>
+      typeof entry.proxy_identifier === "string" && entry.proxy_identifier.trim()
+        ? entry.proxy_identifier.trim()
+        : undefined,
+    )
+    .find((value) => Boolean(value));
+}
+
+export function hasDialHelperConfirmation(results: HelperActionResult[]): boolean {
+  return results.some(
+    (entry) =>
+      typeof entry.helperBundleIdentifier === "string" &&
+      OUTBOUND_DIAL_HELPER_BUNDLES.has(entry.helperBundleIdentifier),
+  );
+}
+
+function hasDefinitiveDialHelperAbsence(
+  result: HelperActionResult,
+  requiredPeerProcessIds: Iterable<number>,
+): boolean {
+  const results = readHelperResults(result);
+  const observedProcessIds = new Set(readHelperPeers(result).map((peer) => peer.processId));
+  return (
+    result.topologyComplete === true &&
+    results.length === result.helpersContacted &&
+    hasDialHelperConfirmation(results) &&
+    results.every((entry) => entry.found === false && entry.retained_outbound_dial !== true) &&
+    [...requiredPeerProcessIds].every((processId) => observedProcessIds.has(processId))
+  );
+}
+
+export const OUTBOUND_RECONCILE_ATTEMPTS = 12;
+export const OUTBOUND_RECONCILE_INTERVAL_MS = 250;
+
+export async function reconcilePendingFaceTimeCarrier(params: {
+  helper: FaceTimeHelperSocketServer;
+  pending: PendingFaceTimeDial;
+  isCurrent: () => boolean;
+  peers: Map<number, FaceTimeHelperPeer>;
+  persist: () => Promise<void>;
+  clear: () => Promise<void>;
+}): Promise<void> {
+  const { pending } = params;
+  let previousAbsentTopology: number | undefined;
+  let previousAbsenceCurrent: (() => boolean) | undefined;
+  for (let attempt = 0; attempt < OUTBOUND_RECONCILE_ATTEMPTS; attempt += 1) {
+    if (!params.isCurrent()) {
+      return;
+    }
+    // Native events can enrich this same pending object while its query is in flight.
+    const { ownerEpoch, delivery, callUUID, proxyIdentifier } = pending;
+    const aliases = new Set(pending.callUUIDAliases);
+    const isSnapshotCurrent = () =>
+      params.isCurrent() &&
+      pending.ownerEpoch === ownerEpoch &&
+      pending.delivery === delivery &&
+      pending.callUUID === callUUID &&
+      pending.proxyIdentifier === proxyIdentifier &&
+      (pending.callUUIDAliases?.size ?? 0) === aliases.size &&
+      [...aliases].every((alias) => pending.callUUIDAliases?.has(alias) === true);
+    const result = await params.helper.findOutgoingCall(
+      pending.handle,
+      callUUID,
+      pending.dialID,
+      proxyIdentifier,
+      pending.requestedAt,
+      pending.mode,
+    );
+    if (!params.isCurrent()) {
+      return;
+    }
+    if (!isSnapshotCurrent()) {
+      previousAbsentTopology = undefined;
+      previousAbsenceCurrent = undefined;
+      continue;
+    }
+    retainOutboundDialHelperPeers(params.peers, result);
+    const reconciledCallUUID = readOutboundCallUUID(result);
+    const reconciledProxyIdentifier = readOutboundProxyIdentifier(result);
+    if (reconciledCallUUID || reconciledProxyIdentifier) {
+      retainFaceTimeDialCallUUID(pending, reconciledCallUUID);
+      if (reconciledProxyIdentifier) {
+        pending.proxyIdentifier = reconciledProxyIdentifier;
+      }
+      await params.persist();
+    }
+    if (
+      reconciledCallUUID ||
+      reconciledProxyIdentifier ||
+      readHelperResults(result).some((entry) => entry.found === true)
+    ) {
+      return;
+    }
+    const topologyGeneration =
+      typeof result.topologyGeneration === "number" ? result.topologyGeneration : undefined;
+    const completeAbsence = hasDefinitiveDialHelperAbsence(result, params.peers.keys());
+    if (
+      completeAbsence &&
+      topologyGeneration !== undefined &&
+      topologyGeneration === previousAbsentTopology &&
+      previousAbsenceCurrent?.()
+    ) {
+      await params.clear();
+      return;
+    }
+    previousAbsentTopology = completeAbsence ? topologyGeneration : undefined;
+    previousAbsenceCurrent = completeAbsence ? isSnapshotCurrent : undefined;
+    if (attempt + 1 < OUTBOUND_RECONCILE_ATTEMPTS) {
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, OUTBOUND_RECONCILE_INTERVAL_MS);
+      });
+    }
+  }
+}

package/src/runtime-lifecycle.ts

@@ -0,0 +1,17 @@
+export async function stopRetainedRuntime<T extends { stop(): Promise<void> }>(
+  current: Promise<T> | undefined,
+  clearIfCurrent: (stopped: Promise<T>) => void,
+): Promise<void> {
+  if (!current) {
+    return;
+  }
+  let runtime: T;
+  try {
+    runtime = await current;
+  } catch (error) {
+    clearIfCurrent(current);
+    throw error;
+  }
+  await runtime.stop();
+  clearIfCurrent(current);
+}