machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/relay-diagnostics.mjs

@@ -0,0 +1,91 @@
+export const APPLICATION_PROXY_ROUTE_SCOPE = "application-proxy-selection-only";
+
+export function preferredRelayCloseCategory(current, next) {
+  const existing = String(current || "");
+  const candidate = String(next || "relay_transport_error");
+  return !existing || existing === "relay_transport_error" ? candidate : existing;
+}
+
+export function relayStatusSnapshot(state, now = Date.now()) {
+  const current = Number(now) || 0;
+  const liveness = state.liveness?.snapshot(current) || null;
+  return {
+    authenticated: state.authenticated === true,
+    ready: state.ready === true,
+    readiness_probe_delivered: state.readinessProbeDelivered === true,
+    closed: state.closed === true,
+    network_route: state.networkRoute,
+    network_route_scope: state.networkRouteScope,
+    transport: "websocket",
+    last_connect_stage: state.lastConnectStage || "idle",
+    last_connect_duration_ms: Math.max(0, Math.round(Number(state.lastConnectDurationMs) || 0)),
+    last_connect_http_status: Number.isInteger(state.lastConnectHttpStatus) ? state.lastConnectHttpStatus : null,
+    reconnect_attempt: state.reconnectAttempt,
+    outage_active: state.outageStartedAt > 0,
+    outage_count: state.outageCount,
+    outage_attempts: state.outageAttempts,
+    outage_started_at: isoTimestamp(state.outageStartedWallAt),
+    outage_duration_ms: state.outageStartedAt > 0 ? Math.max(0, current - state.outageStartedAt) : 0,
+    last_close_category: state.outageCount > 0 ? state.lastCloseCategory : null,
+    last_close_code: state.outageCount > 0 ? state.lastCloseCode : null,
+    last_transport_error_class: state.outageCount > 0 ? (state.lastTransportErrorClass || null) : null,
+    last_disconnected_at: isoTimestamp(state.lastDisconnectedAt),
+    last_ready_at: isoTimestamp(state.lastReadyWallAt),
+    last_ready_duration_ms: state.lastReadyDurationMs,
+    last_ready_inbound_silence_ms: state.lastReadyInboundSilenceMs,
+    application_heartbeat_interval_ms: liveness?.application_heartbeat_interval_ms || 0,
+    application_heartbeat_timeout_ms: liveness?.application_heartbeat_timeout_ms || 0,
+    last_reconnect_delay_ms: state.lastReconnectDelayMs,
+    next_reconnect_at: isoTimestamp(state.nextReconnectWallAt),
+    next_reconnect_in_ms: state.nextReconnectAt > 0 ? Math.max(0, state.nextReconnectAt - current) : 0,
+    session_generation: state.sessionGeneration,
+    heartbeat: liveness,
+  };
+}
+
+export function relayOutageFields(state, now, cause) {
+  const current = Number(now) || 0;
+  return {
+    event: "relay.outage.active",
+    outage_seconds: roundSeconds(Math.max(0, current - state.outageStartedAt)),
+    attempts: state.outageAttempts,
+    cause,
+    close_category: state.lastCloseCategory,
+    close_code: state.lastCloseCode,
+    previous_ready_inbound_silence_ms: state.lastReadyInboundSilenceMs,
+    network_route: state.networkRoute,
+    network_route_scope: state.networkRouteScope,
+    transport: "websocket",
+    last_connect_stage: state.lastConnectStage || "idle",
+    last_connect_duration_ms: Math.max(0, Math.round(Number(state.lastConnectDurationMs) || 0)),
+    last_connect_http_status: Number.isInteger(state.lastConnectHttpStatus) ? state.lastConnectHttpStatus : null,
+    next_reconnect_in_ms: state.nextReconnectAt > 0 ? Math.max(0, state.nextReconnectAt - current) : 0,
+    ...(state.lastTransportErrorClass ? { error_class: state.lastTransportErrorClass } : {}),
+  };
+}
+
+export function relayRecoveryFields(state, outageMs) {
+  return {
+    event: "relay.outage.recovered",
+    outage_seconds: roundSeconds(outageMs),
+    attempts: state.outageAttempts,
+    close_category: state.lastCloseCategory,
+    close_code: state.lastCloseCode,
+    previous_ready_inbound_silence_ms: state.lastReadyInboundSilenceMs,
+    network_route: state.networkRoute,
+    network_route_scope: state.networkRouteScope,
+    transport: "websocket",
+    last_connect_stage: state.lastConnectStage || "idle",
+    last_connect_duration_ms: Math.max(0, Math.round(Number(state.lastConnectDurationMs) || 0)),
+    last_connect_http_status: Number.isInteger(state.lastConnectHttpStatus) ? state.lastConnectHttpStatus : null,
+    ...(state.lastTransportErrorClass ? { error_class: state.lastTransportErrorClass } : {}),
+  };
+}
+
+function isoTimestamp(value) {
+  return Number(value) > 0 ? new Date(Number(value)).toISOString() : null;
+}
+
+function roundSeconds(milliseconds) {
+  return Math.max(1, Math.round(Number(milliseconds || 0) / 1000));
+}

package/src/local/relay-heartbeat.mjs

@@ -0,0 +1,119 @@
+export class RelayHeartbeatMonitor {
+  constructor(options = {}) {
+    this.intervalMs = positiveInteger(options.intervalMs, 25_000);
+    this.timeoutMs = positiveInteger(options.timeoutMs, 75_000);
+    this.stallThresholdMs = positiveInteger(options.stallThresholdMs, Math.max(1000, Math.floor(this.intervalMs / 2)));
+    this.recoveryGraceMs = positiveInteger(options.recoveryGraceMs, Math.max(this.intervalMs, Math.min(this.timeoutMs, 30_000)));
+    this.scheduler = options.scheduler;
+    this.now = options.now;
+    this.logger = options.logger || console;
+    this.isActive = options.isActive;
+    this.lastInboundAt = options.lastInboundAt;
+    this.sendHeartbeat = options.sendHeartbeat;
+    this.onTimeout = options.onTimeout;
+    this.timer = null;
+    this.expectedAt = 0;
+    this.recoveryUntil = 0;
+    this.lastEventLoopLagMs = 0;
+    this.maxEventLoopLagMs = 0;
+    this.eventLoopStallCount = 0;
+    this.lastEventLoopStallAt = 0;
+    this.lastEventLoopStallWarnAt = 0;
+  }
+
+  start() {
+    this.stop();
+    this.expectedAt = this.now() + this.intervalMs;
+    this.recoveryUntil = 0;
+    this.timer = this.scheduler.setInterval(() => this.tick(), this.intervalMs);
+    this.timer?.unref?.();
+  }
+
+  stop() {
+    if (this.timer) this.scheduler.clearInterval(this.timer);
+    this.timer = null;
+    this.expectedAt = 0;
+    this.recoveryUntil = 0;
+  }
+
+  observeInbound() {
+    this.recoveryUntil = 0;
+  }
+
+  snapshot(now = this.now()) {
+    const current = Number(now) || 0;
+    return {
+      interval_ms: this.intervalMs,
+      timeout_ms: this.timeoutMs,
+      recovery_grace_ms: this.recoveryGraceMs,
+      recovery_active: this.recoveryUntil > current,
+      recovery_remaining_ms: this.recoveryUntil > current ? this.recoveryUntil - current : 0,
+      last_event_loop_lag_ms: this.lastEventLoopLagMs,
+      max_event_loop_lag_ms: this.maxEventLoopLagMs,
+      event_loop_stall_count: this.eventLoopStallCount,
+      last_event_loop_stall_at: isoTimestamp(this.lastEventLoopStallAt),
+    };
+  }
+
+  tick() {
+    if (!this.isActive()) return;
+    const now = this.now();
+    const expectedAt = this.expectedAt || now;
+    const eventLoopLagMs = Math.max(0, now - expectedAt);
+    this.expectedAt = now + this.intervalMs;
+    this.lastEventLoopLagMs = eventLoopLagMs;
+    this.maxEventLoopLagMs = Math.max(this.maxEventLoopLagMs, eventLoopLagMs);
+
+    if (eventLoopLagMs >= this.stallThresholdMs) {
+      const silentForMs = Math.max(0, now - this.lastInboundAt());
+      const staleAfterLongPause = eventLoopLagMs > this.timeoutMs + this.recoveryGraceMs
+        && silentForMs > this.timeoutMs;
+      this.observeEventLoopStall(now, eventLoopLagMs, !staleAfterLongPause);
+      if (staleAfterLongPause) {
+        this.recoveryUntil = 0;
+        this.onTimeout({ silentForMs, eventLoopLagMs });
+        return;
+      }
+      this.recoveryUntil = Math.max(this.recoveryUntil, now + this.recoveryGraceMs);
+      this.sendHeartbeat(now);
+      return;
+    }
+    if (now < this.recoveryUntil) {
+      this.sendHeartbeat(now);
+      return;
+    }
+
+    const silentForMs = Math.max(0, now - this.lastInboundAt());
+    if (silentForMs >= this.timeoutMs) {
+      this.onTimeout({ silentForMs, eventLoopLagMs });
+      return;
+    }
+    this.sendHeartbeat(now);
+  }
+
+  observeEventLoopStall(now, lagMs, relayDisconnectDeferred = true) {
+    this.eventLoopStallCount += 1;
+    this.lastEventLoopStallAt = now;
+    if (this.lastEventLoopStallWarnAt && now - this.lastEventLoopStallWarnAt < this.timeoutMs) return;
+    this.lastEventLoopStallWarnAt = now;
+    this.logger.warn?.(
+      relayDisconnectDeferred
+        ? "local event loop stalled; relay liveness decision deferred"
+        : "local event loop resumed after a long pause; reconnecting stale relay transport",
+      {
+        event: "runtime.event_loop.stall",
+        lag_ms: lagMs,
+        recovery_grace_ms: this.recoveryGraceMs,
+        relay_disconnect_deferred: relayDisconnectDeferred,
+      },
+    );
+  }
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}
+function isoTimestamp(value) {
+  return Number(value) > 0 ? new Date(Number(value)).toISOString() : null;
+}

package/src/local/relay-liveness.mjs

@@ -0,0 +1,109 @@
+import relayContract from "../shared/relay-contract.json" with { type: "json" };
+import { RelayHeartbeatMonitor } from "./relay-heartbeat.mjs";
+
+const SILENT_STALL_LOGGER = Object.freeze({ warn() {} });
+
+export class RelayLiveness {
+  constructor(options = {}) {
+    this.now = options.now;
+    this.currentSocket = options.currentSocket;
+    this.sendApplicationHeartbeat = options.sendApplicationHeartbeat;
+    this.lastInboundAt = 0;
+    this.lastApplicationInboundAt = 0;
+    const active = options.isActive;
+    const scheduler = options.scheduler;
+    const transportIntervalMs = positiveInteger(options.transportPingIntervalMs ?? options.heartbeatIntervalMs,
+      relayContract.transportPingIntervalMs);
+    this.transport = new RelayHeartbeatMonitor({
+      intervalMs: transportIntervalMs,
+      timeoutMs: positiveInteger(options.transportPongTimeoutMs ?? options.heartbeatTimeoutMs,
+        relayContract.transportPongTimeoutMs),
+      stallThresholdMs: options.heartbeatStallThresholdMs,
+      recoveryGraceMs: options.heartbeatRecoveryGraceMs ?? transportIntervalMs,
+      scheduler,
+      now: this.now,
+      logger: options.logger,
+      isActive: active,
+      lastInboundAt: () => this.lastInboundAt,
+      sendHeartbeat: () => this.probeTransport(options.onTransportError),
+      onTimeout: (details) => options.onTransportTimeout?.(details, this.currentSocket?.()),
+    });
+    this.application = new RelayHeartbeatMonitor({
+      intervalMs: positiveInteger(options.applicationHeartbeatIntervalMs,
+        relayContract.daemonApplicationHeartbeatIntervalMs),
+      timeoutMs: positiveInteger(options.applicationHeartbeatTimeoutMs,
+        relayContract.daemonApplicationHeartbeatTimeoutMs),
+      stallThresholdMs: options.heartbeatStallThresholdMs,
+      recoveryGraceMs: options.heartbeatRecoveryGraceMs,
+      scheduler,
+      now: this.now,
+      logger: SILENT_STALL_LOGGER,
+      isActive: active,
+      lastInboundAt: () => this.lastApplicationInboundAt,
+      sendHeartbeat: (now) => this.sendApplicationProbe(now),
+      onTimeout: (details) => options.onApplicationTimeout?.(details, this.currentSocket?.()),
+    });
+  }
+
+  start() {
+    const now = this.now();
+    this.lastInboundAt = now;
+    this.lastApplicationInboundAt = now;
+    this.transport.start();
+    this.application.start();
+  }
+
+  stop() {
+    this.transport.stop();
+    this.application.stop();
+  }
+
+  observeInbound() {
+    this.lastInboundAt = this.now();
+    this.transport.observeInbound();
+  }
+
+  observeApplicationInbound() {
+    const now = this.now();
+    this.lastInboundAt = now;
+    this.lastApplicationInboundAt = now;
+    this.transport.observeInbound();
+    this.application.observeInbound();
+  }
+
+  silenceMs(now = this.now()) {
+    return this.lastInboundAt > 0 ? Math.max(0, Number(now) - this.lastInboundAt) : 0;
+  }
+
+  snapshot(now = this.now()) {
+    const application = this.application.snapshot(now);
+    return {
+      ...this.transport.snapshot(now),
+      application_heartbeat_interval_ms: application.interval_ms,
+      application_heartbeat_timeout_ms: application.timeout_ms,
+      application_inbound_silence_ms: Math.max(0, Number(now) - this.lastApplicationInboundAt),
+    };
+  }
+
+  probeTransport(onTransportError) {
+    const socket = this.currentSocket?.();
+    if (!socket) return false;
+    if (typeof socket.ping !== "function") return this.sendApplicationProbe(this.now());
+    try {
+      socket.ping();
+      return true;
+    } catch (error) {
+      onTransportError?.(error, socket);
+      return false;
+    }
+  }
+
+  sendApplicationProbe(now) {
+    const socket = this.currentSocket?.();
+    return socket ? this.sendApplicationHeartbeat?.(now, socket) !== false : false;
+  }
+}
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}

package/src/local/relay-peer-diagnostics.mjs

@@ -0,0 +1,29 @@
+// @ts-check
+
+import { clampInteger } from "./numbers.mjs";
+import { isPlainRecord } from "./records.mjs";
+
+export function relayHandshakeDiagnostics(value = {}) {
+  const status = isPlainRecord(value) ? value : {};
+  return {
+    schema_version: 1,
+    transport: ["websocket", "https"].includes(status.transport) ? status.transport : "unknown",
+    network_route: typeof status.network_route === "string" ? status.network_route : "unresolved",
+    last_connect_stage: typeof status.last_connect_stage === "string" ? status.last_connect_stage : "idle",
+    last_connect_duration_ms: clampInteger(status.last_connect_duration_ms, 0, 0, 10 * 60_000),
+    last_connect_http_status: Number.isSafeInteger(status.last_connect_http_status) ? status.last_connect_http_status : null,
+    outage_count: clampInteger(status.outage_count, 0, 0, 1_000_000_000),
+    outage_active: status.outage_active === true,
+    outage_started_at: typeof status.outage_started_at === "string" ? status.outage_started_at : null,
+    outage_duration_ms: clampInteger(status.outage_duration_ms, 0, 0, 31 * 24 * 60 * 60_000),
+    outage_attempts: clampInteger(status.outage_attempts, 0, 0, 1_000_000),
+    last_close_category: typeof status.last_close_category === "string" ? status.last_close_category : null,
+    last_close_code: Number.isSafeInteger(status.last_close_code) ? status.last_close_code : null,
+    last_transport_error_class: typeof status.last_transport_error_class === "string"
+      ? status.last_transport_error_class
+      : null,
+    last_disconnected_at: typeof status.last_disconnected_at === "string" ? status.last_disconnected_at : null,
+    previous_ready_duration_ms: clampInteger(status.last_ready_duration_ms, 0, 0, 365 * 24 * 60 * 60_000),
+    previous_ready_inbound_silence_ms: clampInteger(status.last_ready_inbound_silence_ms, 0, 0, 31 * 24 * 60 * 60_000),
+  };
+}

package/src/local/release-runtime-lock.mjs

@@ -0,0 +1,18 @@
+import { withOwnerStateLock } from "./owner-state-lock.mjs";
+import { assertStateMaintenanceAvailable, machineServiceControlRoot } from "./state.mjs";
+
+const LOCK_FILE = "release-runtime.lock";
+const LOCK_PURPOSE = "release-runtime";
+
+export function withReleaseRuntimeLock(stateRoot, callback, options = {}) {
+  if (typeof callback !== "function") throw new TypeError("release-runtime lock requires a callback");
+  return withOwnerStateLock(machineServiceControlRoot(options), async () => {
+    if (stateRoot) assertStateMaintenanceAvailable(stateRoot);
+    return callback();
+  }, {
+    purpose: LOCK_PURPOSE,
+    fileName: LOCK_FILE,
+    label: "release runtime",
+    timeoutMs: options.timeoutMs ?? 30_000,
+  });
+}

package/src/local/remote-activity-idle-sleep-guard.mjs

@@ -0,0 +1,77 @@
+import { MacosIdleSleepAssertion } from "./macos-idle-sleep-assertion.mjs";
+
+export const DEFAULT_REMOTE_ACTIVITY_IDLE_SLEEP_GRACE_MS = 5 * 60_000;
+
+export class RemoteActivityIdleSleepGuard {
+  constructor({ platform = process.platform, daemonPid = process.pid, graceMs = DEFAULT_REMOTE_ACTIVITY_IDLE_SLEEP_GRACE_MS,
+    spawnProcess, setTimer = setTimeout, clearTimer = clearTimeout, logger = console } = {}) {
+    this.assertion = new MacosIdleSleepAssertion({ platform, processId: daemonPid, spawnProcess, logger });
+    this.enabled = this.assertion.supported && Number.isSafeInteger(graceMs) && graceMs > 0;
+    this.graceMs = this.enabled ? graceMs : 0;
+    this.setTimer = setTimer;
+    this.clearTimer = clearTimer;
+    this.releaseTimer = null;
+    this.activeActivities = 0;
+  }
+
+  beginActivity() {
+    if (!this.enabled) return false;
+    this.activeActivities += 1;
+    this.cancelReleaseTimer();
+    return this.assertion.acquire();
+  }
+
+  endActivity() {
+    if (!this.enabled) return false;
+    if (this.activeActivities <= 0) return this.assertion.snapshot().active;
+    this.activeActivities -= 1;
+    if (this.activeActivities > 0 || !this.assertion.snapshot().active) return this.assertion.snapshot().active;
+    try {
+      this.armReleaseTimer();
+      return true;
+    } catch (error) {
+      this.release();
+      this.assertion.reportUnavailable(error);
+      return false;
+    }
+  }
+
+  cancelReleaseTimer() {
+    const timer = this.releaseTimer;
+    this.releaseTimer = null;
+    if (!timer) return;
+    try { this.clearTimer(timer); } catch { /* Stale timer callbacks also check identity before release. */ }
+  }
+
+  armReleaseTimer() {
+    this.cancelReleaseTimer();
+    const timer = this.setTimer(() => {
+      if (this.releaseTimer !== timer || this.activeActivities > 0) return;
+      this.releaseTimer = null;
+      this.assertion.release();
+    }, this.graceMs);
+    timer?.unref?.();
+    this.releaseTimer = timer;
+  }
+
+  release() {
+    this.cancelReleaseTimer();
+    this.assertion.release();
+  }
+
+  stop() {
+    this.activeActivities = 0;
+    this.release();
+  }
+
+  snapshot() {
+    const assertion = this.assertion.snapshot();
+    return {
+      supported: assertion.supported,
+      enabled: this.enabled,
+      active: assertion.active,
+      grace_ms: this.graceMs,
+      last_error_class: assertion.last_error_class,
+    };
+  }
+}

package/src/local/remote-configuration.mjs

@@ -0,0 +1,48 @@
+import { effectiveLogFormat, effectiveLogLevel } from "./cli-options.mjs";
+import { resolvePolicy } from "./cli-policy.mjs";
+import { ensurePreferredDeviceRoot } from "./device-root-provider.mjs";
+import { createLogger } from "./log.mjs";
+import {
+  ensureWorkerSecrets,
+  promotePendingDeviceIdentity,
+  saveState,
+} from "./state.mjs";
+import { ensureWorkerDeployment } from "./worker-deployment.mjs";
+
+export async function convergeRemoteConfiguration({ args, state }) {
+  const workerName = validateWorkerName(args.workerName);
+  ensureWorkerSecrets(state, {
+    rotateSecrets: Boolean(args.rotateSecrets),
+    deferDeviceRotation: true,
+    workerName,
+    allowWorkerRename: Boolean(args.forceWorker),
+  });
+  if (!state.worker.pendingDeviceIdentity) {
+    const candidate = await ensurePreferredDeviceRoot({
+      profileDir: state.paths.profileDir,
+      workspaceHash: state.workspace.hash,
+      existing: args.rotateSecrets ? null : state.worker.deviceIdentity,
+      rotate: Boolean(args.rotateSecrets),
+    });
+    if (candidate.keyId !== state.worker.deviceIdentity.keyId) state.worker.pendingDeviceIdentity = candidate;
+  }
+  state.policy = resolvePolicy(args, state.policy);
+  state.policy.updatedAt = new Date().toISOString();
+  saveState(state);
+  const logger = createLogger({
+    level: args.json ? "error" : effectiveLogLevel(args),
+    format: effectiveLogFormat(args),
+    component: "worker",
+  });
+  await ensureWorkerDeployment(state, args, { logger });
+  if (promotePendingDeviceIdentity(state)) saveState(state);
+}
+
+export function validateWorkerName(value) {
+  if (value === undefined || value === null || value === false) return undefined;
+  const name = String(value).trim();
+  if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(name)) {
+    throw new Error("--worker-name must be 1-63 lowercase letters, digits, or hyphens, and cannot start or end with a hyphen");
+  }
+  return name;
+}

package/src/local/resilient-relay-connection.mjs

@@ -0,0 +1,178 @@
+import relayContract from "../shared/relay-contract.json" with { type: "json" };
+import { RelayConnection } from "./relay-connection.mjs";
+import { DaemonHttpRelayConnection } from "./daemon-http-relay-connection.mjs";
+
+export class ResilientRelayConnection {
+  constructor(options = {}) {
+    this.logger = options.logger || {};
+    this.onReady = typeof options.onReady === "function" ? options.onReady : () => {};
+    this.onDisconnect = typeof options.onDisconnect === "function" ? options.onDisconnect : () => {};
+    this.scheduler = options.scheduler || { setTimeout, clearTimeout };
+    this.fallbackDelayMs = positiveInteger(options.fallbackDelayMs, relayContract.httpFallbackActivationDelayMs);
+    this.activeTransport = "";
+    this.closed = true;
+    this.startResolve = null;
+    this.startPromise = null;
+    this.fallbackTimer = null;
+    this.fallbackRecoveredOutageMs = 0;
+    const WebSocketRelayClass = options.WebSocketRelayClass || RelayConnection;
+    const HttpRelayClass = options.HttpRelayClass || DaemonHttpRelayConnection;
+    this.websocket = new WebSocketRelayClass({
+      ...options.websocket,
+      onReady: (event) => this.handleReady("websocket", event),
+      onDisconnect: () => this.handleDisconnect("websocket"),
+    });
+    this.http = new HttpRelayClass({
+      ...options.http,
+      onReady: (event) => this.handleReady("https", event),
+      onDisconnect: () => this.handleDisconnect("https"),
+    });
+  }
+
+  start() {
+    if (!this.closed && this.startPromise) return this.startPromise;
+    this.closed = false;
+    this.startPromise = new Promise((resolve) => { this.startResolve = resolve; });
+    void this.websocket.start().catch(() => {
+      /* RelayConnection owns reconnect/backoff and reports readiness through callbacks; startup rejection is not terminal here. */
+    });
+    this.armFallback(this.fallbackDelayMs);
+    return this.startPromise;
+  }
+
+  stop() {
+    if (this.closed) return;
+    this.closed = true;
+    this.clearFallbackTimer();
+    this.websocket.stop();
+    this.http.stop();
+    this.activeTransport = "";
+    this.fallbackRecoveredOutageMs = 0;
+    this.startResolve?.(false);
+    this.startResolve = null;
+    this.startPromise = null;
+  }
+
+  status() {
+    const websocket = this.websocket.status();
+    const http = this.http.status();
+    if (this.activeTransport === "https" && http.ready) {
+      return {
+        ...websocket,
+        authenticated: true,
+        ready: true,
+        closed: this.closed,
+        transport: "https",
+        network_route: http.network_route,
+        last_transport_error_class: http.last_transport_error_class,
+        outage_active: false,
+        outage_duration_ms: this.fallbackRecoveredOutageMs,
+        https_fallback_active: true,
+        https_fallback: http,
+        websocket_ready: websocket.ready === true,
+        websocket_outage_active: websocket.outage_active === true,
+        websocket_outage_duration_ms: Number(websocket.outage_duration_ms) || 0,
+        websocket_reconnect_attempt: Number(websocket.reconnect_attempt) || 0,
+      };
+    }
+    return {
+      ...websocket,
+      transport: "websocket",
+      https_fallback_active: false,
+      https_fallback: http,
+    };
+  }
+
+  currentSessionId() {
+    return this.activeTransport === "https" ? this.http.currentSessionId() : this.websocket.currentSessionId();
+  }
+
+  send(value) {
+    if (this.activeTransport === "websocket") return this.websocket.send(value);
+    if (this.activeTransport === "https") return this.http.send(value);
+    return false;
+  }
+
+  sendForSession(value, expectedSessionId) {
+    const sessionId = Number(expectedSessionId) || 0;
+    if (sessionId && sessionId === this.http.currentSessionId()) return this.http.sendForSession(value, sessionId);
+    return this.websocket.sendForSession(value, sessionId);
+  }
+
+  interrupt(category) {
+    if (this.activeTransport === "https") return this.http.interrupt(category);
+    return this.websocket.interrupt(category);
+  }
+
+  observeWelcome(message, relayContext = {}) {
+    if (relayContext?.transport === "https") return false;
+    return this.websocket.observeWelcome(message);
+  }
+  acknowledge(message, relayContext = {}) {
+    if (relayContext?.transport === "https") return false;
+    return this.websocket.acknowledge(message);
+  }
+  confirmReady(message, relayContext = {}) {
+    return relayContext?.transport === "https" ? this.http.confirmReady(message) : this.websocket.confirmReady(message);
+  }
+  handleServerError(message, relayContext = {}) {
+    if (relayContext?.transport === "https") return this.http.interrupt(message?.error);
+    return this.websocket.handleServerError(message);
+  }
+
+  handleReady(transport, event) {
+    if (this.closed) return;
+    if (transport === "websocket") {
+      this.activeTransport = "websocket";
+      this.fallbackRecoveredOutageMs = 0;
+      this.http.stop();
+      this.clearFallbackTimer();
+    } else {
+      if (this.websocket.status().ready === true) { this.http.stop(); return; }
+      this.fallbackRecoveredOutageMs = Math.max(0, Number(this.websocket.status().outage_duration_ms) || 0);
+      this.activeTransport = "https";
+    }
+    this.startResolve?.(true);
+    this.startResolve = null;
+    try { this.onReady({ ...event, transport }); }
+    catch { /* Transport readiness is already committed; observer failure must not tear down the usable channel. */ }
+  }
+
+  handleDisconnect(transport) {
+    if (this.closed) return;
+    if (transport === "websocket") {
+      const wasPrimary = this.activeTransport === "websocket";
+      this.armFallback(0, wasPrimary);
+      if (!wasPrimary) return;
+    } else if (this.activeTransport !== "https") return;
+    this.activeTransport = "";
+    try { this.onDisconnect({ transport }); }
+    catch { /* The transport is already unavailable; observer failure must not block failover/reconnect. */ }
+  }
+
+  armFallback(delay, takeoverWebSocket = false) {
+    if (this.closed) return;
+    if (this.http.status().closed === false) {
+      if (takeoverWebSocket) this.http.start({ takeoverWebSocket: true });
+      return;
+    }
+    if (this.fallbackTimer) return;
+    this.fallbackTimer = this.scheduler.setTimeout(() => {
+      this.fallbackTimer = null;
+      if (this.closed || this.websocket.status().ready === true) return;
+      this.http.start({ takeoverWebSocket });
+    }, Math.max(0, Number(delay) || 0));
+    this.fallbackTimer?.unref?.();
+  }
+
+  clearFallbackTimer() {
+    if (!this.fallbackTimer) return;
+    this.scheduler.clearTimeout(this.fallbackTimer);
+    this.fallbackTimer = null;
+  }
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}