@inkandswitch/patchwork-bootloader 0.4.2 → 0.4.4

package/src/setup.ts

@@ -17,270 +17,363 @@ import {
 const serviceWorkerDebugging = debug.enabled("patchwork:serviceworker");
 const workerDebugging = debug.enabled("patchwork:automergeworker");
 
-// Diagnostic [lifecycle] logging, on by default. Disable via
-// localStorage["patchwork:lifecycle-logs"] = "off". Read live at log time.
-const LIFECYCLE_LOG_KEY = "patchwork:lifecycle-logs";
-export function lifecycleLoggingEnabled(): boolean {
-  try {
-    const v = globalThis.localStorage?.getItem(LIFECYCLE_LOG_KEY);
-    return v !== "off" && v !== "false" && v !== "0" && v !== "no";
-  } catch {
-    return true;
-  }
-}
-
-// The SW can't read localStorage, so it always emits [lifecycle] markers and
-// forwards them as `sw-lifecycle`; gate rendering here on the live toggle.
-let swLifecycleListenerInstalled = false;
-function installServiceWorkerLogForwarding(): void {
-  if (swLifecycleListenerInstalled) return;
-  if (typeof navigator === "undefined" || !navigator.serviceWorker) return;
-  swLifecycleListenerInstalled = true;
-  navigator.serviceWorker.addEventListener("message", (event: MessageEvent) => {
-    const data = event.data;
-    if (data?.type !== "sw-lifecycle") return;
-    if (!lifecycleLoggingEnabled()) return;
-    const fn = (console as any)[data.level] ?? console.log;
-    fn(`[service-worker] ${data.msg}`);
-  });
+export const lifecycleLog = debug("patchwork:lifecycle");
+
+function describeErrorEvent(event: Event): string {
+  const error = event as ErrorEvent;
+  const where = error.filename
+    ? ` (${error.filename}:${error.lineno}:${error.colno})`
+    : "";
+  return `${error.message || String(event)}${where}`;
 }
 
-const key = "patchworkServiceWorkerCacheVersion";
-const defaultServiceWorkerCacheName = "patchwork";
-let nextRepoChannelId = 0;
-
-function bumpServiceWorkerCacheVersion() {
-  const version = new Date().valueOf().toString(36);
-  localStorage.setItem(key, version);
-  return getServiceWorkerCacheVersion();
-}
+// The version is cleared on every boot, so the steady state is
+// DEFAULT_CACHE_NAME. bumpServiceWorkerCache is a dev escape hatch: it moves
+// the worker to a throwaway cache now, and the next boot both reverts the name
+// and (via the worker's activate handler) deletes the throwaway.
+const CACHE_VERSION_KEY = "patchworkServiceWorkerCacheVersion";
+const DEFAULT_CACHE_NAME = "patchwork";
 
-function getServiceWorkerCacheVersion() {
-  return localStorage.getItem(key);
+function currentCacheName(): string {
+  return localStorage.getItem(CACHE_VERSION_KEY) ?? DEFAULT_CACHE_NAME;
 }
 
-function setServiceWorkerCacheName(sw: ServiceWorker | null) {
-  if (!sw) {
-    throw new Error("no service worker!");
-  }
-  sw.postMessage({
-    type: "cachename",
-    cachename: getServiceWorkerCacheVersion() ?? defaultServiceWorkerCacheName,
-  });
+function configureServiceWorker(sw: ServiceWorker | null) {
+  if (!sw) return;
+  sw.postMessage({ type: "debug", debug: serviceWorkerDebugging });
+  sw.postMessage({ type: "cachename", cachename: currentCacheName() });
 }
 
 export function bumpServiceWorkerCache(
-  sw = navigator.serviceWorker.controller
+  sw: ServiceWorker | null = navigator.serviceWorker.controller
 ) {
-  bumpServiceWorkerCacheVersion();
-  setServiceWorkerCacheName(sw);
+  if (!sw) throw new Error("no service worker!");
+  localStorage.setItem(CACHE_VERSION_KEY, Date.now().toString(36));
+  sw.postMessage({ type: "cachename", cachename: currentCacheName() });
 }
 
-(window as any).bumpServiceWorkerCache = bumpServiceWorkerCache;
-
-function configureServiceWorker(sw: ServiceWorker | null) {
-  if (!sw) return;
-  sw.postMessage({ type: "debug", debug: serviceWorkerDebugging });
-  sw.postMessage({
-    type: "cachename",
-    cachename: getServiceWorkerCacheVersion() ?? defaultServiceWorkerCacheName,
+// The service worker has no localStorage, so it can't read the debug config —
+// it always emits lifecycle markers and forwards them here to be filtered.
+let logForwardingInstalled = false;
+function installServiceWorkerLogForwarding(): void {
+  if (logForwardingInstalled) return;
+  if (typeof navigator === "undefined" || !navigator.serviceWorker) return;
+  logForwardingInstalled = true;
+  navigator.serviceWorker.addEventListener("message", (event: MessageEvent) => {
+    if (event.data?.type !== "sw-lifecycle") return;
+    lifecycleLog("[service-worker] %s", event.data.msg);
   });
 }
 
-// ── The automerge worker ───────────────────────────────────────────────
-// The automerge repo lives in a SharedWorker (not the service worker). One
-// instance is shared by every tab and lives exactly as long as any tab
-// does, so there's no keepalive ping and no restart detection: if we're
-// alive, it's alive. Repo sync ports are passed to it over its connect
-// port; it talks to the service worker over a BroadcastChannel.
+// The automerge repo lives in a SharedWorker. one instance serves every
+// tab. Browsers might kill a SharedWorker under memory pressure, so we
+// heartbeat it and rebuild everything if it dies.
 
 let automergeWorkerPath = "/automerge-worker.js";
 let automergeWorker: SharedWorker | undefined;
+// A repo port opened against instance N is stale once instance N+1 exists — its
+// channel ends in a dead worker — so deliveries are guarded on generation.
+let workerGeneration = 0;
+let disposeWorkerDeathDetection: (() => void) | undefined;
+const repoChannelListeners = new Set<ServiceWorkerRepoChannelListener>();
+let recoveringWorker = false;
+let lastWorkerRecoveryAt = 0;
+// Below this spacing, skip: if the fresh worker is dead too, its own heartbeat
+// re-triggers recovery later rather than spinning in a tight loop.
+const RECOVERY_MIN_INTERVAL_MS = 15_000;
+let nextRepoChannelId = 0;
 
-// SharedWorker proxy entry that owns the subduction WebSocket. Chrome can't
-// spawn workers from inside a SharedWorker, so each tab offers this proxy's
-// port to the automerge worker (which requests one via its port provider).
-// Being a SharedWorker itself, the proxy — and the donated worker↔worker
-// port — outlives the donor tab. Emitted at /packages/... via externals.ts.
+// Chrome can't spawn workers inside a SharedWorker, so each tab offers this
+// proxy's port to the automerge worker, which requests one via its port
+// provider. Being a SharedWorker itself, the proxy — and the donated
+// worker↔worker port — outlives the donor tab.
 const SUBDUCTION_IO_WORKER_URL =
   "/packages/@automerge/automerge-repo/subduction-websocket-worker-shared.js";
 
-// Bench toggles for the subduction socket (see getSubductionEndpoints in
-// automerge-worker.ts), passed as query params because SharedWorker scope
-// has no localStorage — which also gives each configuration its own worker
-// instance, so bench arms can't share state.
-//   localStorage["patchwork:ws-mode"] = "inline"  → socket on worker thread
-//   localStorage["patchwork:ws-window"] = "16"    → WorkerWebSocketEndpoint
-//                                                    windowFrames override
-function workerBenchParams(): string {
-  const params = new URLSearchParams();
-  try {
-    for (const [key, param] of [
-      ["patchwork:ws-mode", "ws-mode"],
-      ["patchwork:ws-window", "ws-window"],
-    ] as const) {
-      const value = globalThis.localStorage?.getItem(key);
-      if (value) params.set(param, value);
-    }
-  } catch {
-    // No localStorage (shouldn't happen in a tab) — use defaults.
-  }
-  const qs = params.toString();
-  return qs ? `?${qs}` : "";
+export function getAutomergeWorker(): SharedWorker {
+  if (automergeWorker) return automergeWorker;
+
+  workerGeneration++;
+  const worker = new SharedWorker(automergeWorkerPath, {
+    name: "patchwork-automerge",
+    type: "module",
+  });
+  automergeWorker = worker;
+
+  // Fires when a message can't be structured-deserialized. Silent otherwise:
+  // the message is dropped, which looks identical to a worker that never
+  // replied.
+  worker.port.addEventListener("messageerror", (event) => {
+    console.error(
+      "[automerge-worker] undeserializable message from worker:",
+      event
+    );
+  });
+  // Control replies come back on this port, and we listen with
+  // addEventListener rather than onmessage, so it needs start().
+  worker.port.start();
+  worker.port.addEventListener("message", handleWorkerMessage);
+  worker.port.postMessage({ type: "debug", debug: workerDebugging });
+
+  donatePort(worker.port, createSubductionIoPort);
+  disposeWorkerDeathDetection = installWorkerDeathDetection(worker);
+  return worker;
 }
 
-export function getAutomergeWorker(): SharedWorker {
-  if (!automergeWorker) {
-    const workerUrl = `${automergeWorkerPath}${workerBenchParams()}`;
-    automergeWorker = new SharedWorker(workerUrl, {
-      name: "patchwork-automerge",
-      type: "module",
-    });
-    // Control replies (port-ready &c) come back on this port, so it needs
-    // start() — we listen with addEventListener, not onmessage.
-    automergeWorker.port.start();
-    // Surface the SharedWorker's console output and uncaught errors in this
-    // tab's console (it has its own console that's awkward to find otherwise).
-    automergeWorker.port.addEventListener("message", (event: MessageEvent) => {
-      if (event.data?.type === "sync-state") {
-        dispatchSyncState(event.data as SyncStateDocMessage);
-        return;
-      }
-      if (isWorkerErrorMessage(event.data)) {
-        // Crash/skew reports relayed from the subduction io proxy (e.g.
-        // protocol-mismatch from a stale SW-cached worker chunk). Surface
-        // loudly — these otherwise only exist in chrome://inspect.
-        console.error("[subduction-io]", event.data);
-        return;
-      }
-      if (event.data?.type === "drift-samples") {
-        // Keepalive-drift samples from the worker's bench probe. Kept on a
-        // bounded window global for the Playwright bench to harvest.
-        const sink = ((window as any).__driftSamples ??= []) as number[];
-        sink.push(...event.data.samples);
-        if (sink.length > 10_000) sink.splice(0, sink.length - 10_000);
-        return;
-      }
-      if (event.data?.type !== "console") return;
-      const { level, args } = event.data;
-      // Gate forwarded [lifecycle] logs on the toggle too.
-      if (
-        !lifecycleLoggingEnabled() &&
-        typeof args?.[0] === "string" &&
-        args[0].includes("[lifecycle]")
-      ) {
-        return;
-      }
-      const fn = (console as any)[level] ?? console.log;
-      // The worker's logs (debug library, the worker's own log()) carry %c
-      // format directives in args[0] with CSS in the following args. Prefix
-      // the tag into the format string rather than as a separate positional,
-      // or the %c would no longer be in arg 0 and the CSS would print raw.
-      if (typeof args[0] === "string") {
-        fn(`[automerge-worker] ${args[0]}`, ...args.slice(1));
-      } else {
-        fn("[automerge-worker]", ...args);
-      }
-    });
-    automergeWorker.port.postMessage({ type: "debug", debug: workerDebugging });
-
-    // Offer the subduction io proxy's port; the worker's port provider pulls
-    // it when (re)constructing its WorkerWebSocketEndpoint.
-    donatePort(automergeWorker.port, () => {
-      const io = new SharedWorker(SUBDUCTION_IO_WORKER_URL, {
-        type: "module",
-        name: "subduction-websocket",
-      });
-      return io.port;
-    });
+function handleWorkerMessage(event: MessageEvent): void {
+  const data = event.data;
 
-    installWorkerDeathDetection(automergeWorker);
+  if (data?.type === "sync-state") {
+    dispatchSyncState(data as SyncStateDocMessage);
+    return;
+  }
+
+  // Crash/skew reports relayed from the subduction io proxy (e.g. a protocol
+  // mismatch from a stale SW-cached worker chunk). These otherwise only exist
+  // in chrome://inspect.
+  if (isWorkerErrorMessage(data)) {
+    console.error("[subduction-io]", data);
+    return;
+  }
+
+  if (data?.type !== "console") return;
+  const { level, args } = data;
+  if (
+    !lifecycleLog.enabled &&
+    typeof args?.[0] === "string" &&
+    args[0].includes("[lifecycle]")
+  ) {
+    return;
+  }
+  const write = (console as any)[level] ?? console.log;
+  // The worker's logs carry %c directives in args[0] with CSS in the following
+  // args, so the tag has to go inside the format string or the CSS prints raw.
+  if (typeof args[0] === "string") {
+    write(`[automerge-worker] ${args[0]}`, ...args.slice(1));
+  } else {
+    write("[automerge-worker]", ...args);
   }
-  return automergeWorker;
+}
+
+function createSubductionIoPort(): MessagePort {
+  const io = new SharedWorker(SUBDUCTION_IO_WORKER_URL, {
+    type: "module",
+    name: "subduction-websocket",
+  });
+  // This worker carries the websocket to the sync server, so a load failure
+  // stops sync with no other symptom.
+  io.addEventListener("error", (event) => {
+    console.error(
+      `[subduction-io] failed to load/run ${SUBDUCTION_IO_WORKER_URL}:`,
+      describeErrorEvent(event)
+    );
+  });
+  io.port.addEventListener("messageerror", (event) => {
+    console.error("[subduction-io] undeserializable message:", event);
+  });
+  return io.port;
 }
 
 /**
- * Detect when the automerge SharedWorker dies or restarts: control-port close,
- * worker error, changed instance id, or an unanswered heartbeat while the tab
- * is visible (a miss while hidden is more likely suspension). [lifecycle]-tagged.
+ * Build a replacement worker and re-wire everything a live tab holds against
+ * it: console forwarding and port donation (both re-done by
+ * getAutomergeWorker), the per-doc sync-state subscriptions, and every
+ * subscriber's repo port. The new instance boots with cold state.
  */
-function installWorkerDeathDetection(worker: SharedWorker): void {
-  const stamp = () => new Date().toISOString();
-  const warn = (msg: string) => {
-    if (lifecycleLoggingEnabled()) console.warn(`[lifecycle] ${stamp()} ${msg}`);
-  };
-  const info = (msg: string) => {
-    if (lifecycleLoggingEnabled()) console.info(`[lifecycle] ${stamp()} ${msg}`);
-  };
+async function recoverAutomergeWorker(
+  reason: string,
+  deadWorker: SharedWorker
+): Promise<void> {
+  if (deadWorker !== automergeWorker) return;
+  if (recoveringWorker) return;
+  const now = Date.now();
+  if (now - lastWorkerRecoveryAt < RECOVERY_MIN_INTERVAL_MS) return;
+  recoveringWorker = true;
+  lastWorkerRecoveryAt = now;
+  lifecycleLog("recreating the automerge SharedWorker (%s)", reason);
 
+  try {
+    disposeWorkerDeathDetection?.();
+    disposeWorkerDeathDetection = undefined;
+    automergeWorker = undefined;
+    try {
+      deadWorker.port.close();
+    } catch {}
+
+    const fresh = getAutomergeWorker();
+    for (const documentId of syncStateListeners.keys()) {
+      fresh.port.postMessage({ type: "sync-sub", documentId });
+    }
+    for (const listener of repoChannelListeners) {
+      try {
+        const generation = workerGeneration;
+        const port = await openRepoChannel();
+        // Replaced again while we waited — the newer recovery re-delivers.
+        if (generation !== workerGeneration) break;
+        await listener(port);
+      } catch (err) {
+        console.error(
+          "failed to re-wire a repo channel after worker recovery",
+          err
+        );
+      }
+    }
+  } finally {
+    recoveringWorker = false;
+  }
+}
+
+// A silent port is not proof of death: the worker may still be evaluating its
+// module graph, or be busy with wasm/sync work. In both cases every queued
+// message — including the repo ports the network adapters ride on — is
+// delivered once it catches up, and tearing the port down would lose them. So
+// silence only starts a non-destructive probe: a second connection to the same
+// instance. Only if the probe gets a `hello` while this port stays silent do we
+// know the instance is alive but our port is stranded, and recover.
+const HEARTBEAT_MS = 5_000;
+const HEARTBEAT_TIMEOUT_MS = 25_000;
+// An idle worker hellos within milliseconds of connecting, so before first
+// contact the budget is tighter — probing early rescues stranded boots fast.
+const FIRST_CONTACT_TIMEOUT_MS = 4_000;
+// After a slow boot both connections hello at roughly the same moment and
+// cross-port delivery order isn't guaranteed, so give the suspect this long to
+// also speak before concluding it's stranded.
+const PROBE_GRACE_MS = 500;
+
+function installWorkerDeathDetection(worker: SharedWorker): () => void {
   let instanceId: string | undefined;
-  let lastPongAt = Date.now();
+  let lastHeardAt = Date.now();
   let warnedUnresponsive = false;
+  let warnedSendFailed = false;
+  let disposed = false;
+  let probe: SharedWorker | undefined;
+  let seq = 0;
+
+  const closeProbe = () => {
+    if (!probe) return;
+    try {
+      probe.port.close();
+    } catch {}
+    probe = undefined;
+  };
 
   worker.port.addEventListener("message", (event: MessageEvent) => {
     const data = event.data;
     if (data?.type !== "hello" && data?.type !== "pong") return;
-    if (data.type === "pong") {
-      lastPongAt = Date.now();
-      warnedUnresponsive = false;
-    }
+    lastHeardAt = Date.now();
+    warnedUnresponsive = false;
+    closeProbe();
     if (instanceId === undefined) {
       instanceId = data.instanceId;
-      info(`automerge SharedWorker instance ${data.instanceId} (via ${data.type})`);
+      lifecycleLog(
+        "automerge SharedWorker instance %s (via %s)",
+        data.instanceId,
+        data.type
+      );
     } else if (data.instanceId && data.instanceId !== instanceId) {
-      warn(
-        `automerge SharedWorker RESTARTED (instance ${data.instanceId}, ` +
-          `was ${instanceId}) — fresh peerId + cold state; docs need re-subscribe`
+      lifecycleLog(
+        "automerge SharedWorker instance changed (instance %s, was %s)",
+        data.instanceId,
+        instanceId
       );
       instanceId = data.instanceId;
     }
   });
 
-  // Fires when the SharedWorker is destroyed (where supported).
   worker.port.addEventListener("close", () => {
-    warn("automerge SharedWorker control port CLOSED — worker terminated");
+    if (disposed) return;
+    lifecycleLog("automerge SharedWorker control port closed");
+    void recoverAutomergeWorker("control port closed", worker);
   });
 
-  worker.addEventListener("error", event => {
-    warn(`automerge SharedWorker error: ${(event as ErrorEvent).message || event}`);
+  // Not gated on the debug namespace: a worker that fails to load never replies
+  // to anything, and this is the only signal that says so.
+  worker.addEventListener("error", (event) => {
+    console.error("automerge SharedWorker error:", describeErrorEvent(event));
   });
 
-  // A missed pong while the tab is visible means the worker likely died (an
-  // active tab keeps it alive); a miss while hidden is more likely suspension.
-  const HEARTBEAT_MS = 10_000;
-  const HEARTBEAT_TIMEOUT_MS = 25_000;
-  let seq = 0;
-  setInterval(() => {
+  const startProbe = (reason: string) => {
+    if (probe || disposed) return;
+    lifecycleLog(
+      "automerge SharedWorker %s; probing with a second connection",
+      reason
+    );
+    const startedAt = Date.now();
+    const p = new SharedWorker(automergeWorkerPath, {
+      name: "patchwork-automerge",
+      type: "module",
+    });
+    probe = p;
+    p.port.start();
+    p.port.addEventListener("message", (event: MessageEvent) => {
+      if (event.data?.type !== "hello") return;
+      setTimeout(() => {
+        if (disposed || probe !== p) return;
+        closeProbe();
+        // The suspect spoke while the probe ran: it was merely busy, and
+        // everything queued on it has been delivered.
+        if (lastHeardAt >= startedAt) return;
+        void recoverAutomergeWorker(
+          `port unresponsive on a live worker (${reason}; probe confirmed)`,
+          worker
+        );
+      }, PROBE_GRACE_MS);
+    });
+    // No hello on the probe means the instance is loading or busy. The probe
+    // waits indefinitely rather than tearing anything down on a timer.
+  };
+
+  const heartbeat = setInterval(() => {
     try {
       worker.port.postMessage({ type: "ping", id: ++seq });
-    } catch {
-      // Port already torn down — the "close" handler covers that case.
+    } catch (error) {
+      // Without this a failed send is indistinguishable from a dead worker.
+      if (!warnedSendFailed) {
+        warnedSendFailed = true;
+        console.error("automerge SharedWorker ping send threw", error);
+      }
     }
-    const silentMs = Date.now() - lastPongAt;
+
+    const neverHeard = instanceId === undefined;
+    const silentMs = Date.now() - lastHeardAt;
+    const timeoutMs = neverHeard
+      ? FIRST_CONTACT_TIMEOUT_MS
+      : HEARTBEAT_TIMEOUT_MS;
+    if (silentMs <= timeoutMs) return;
+
+    // First contact probes regardless of visibility: SharedWorkers don't
+    // suspend with the tab, and the probe destroys nothing. Post-contact
+    // silence defers to visibility, since a hidden page's throttling can fake
+    // it.
     const visible =
       typeof document === "undefined" || document.visibilityState === "visible";
-    if (silentMs > HEARTBEAT_TIMEOUT_MS && visible && !warnedUnresponsive) {
+    if (!neverHeard && !visible) return;
+
+    const seconds = Math.round(silentMs / 1000);
+    const reason = neverHeard
+      ? `no hello ~${seconds}s after connecting`
+      : `no pong for ~${seconds}s`;
+    if (!warnedUnresponsive) {
       warnedUnresponsive = true;
-      warn(
-        `automerge SharedWorker UNRESPONSIVE ~${Math.round(silentMs / 1000)}s ` +
-          `while tab visible — likely died/crashed`
-      );
+      lifecycleLog("automerge SharedWorker %s (tab visible)", reason);
     }
+    startProbe(reason);
   }, HEARTBEAT_MS);
+
+  return () => {
+    disposed = true;
+    clearInterval(heartbeat);
+    closeProbe();
+  };
 }
 
-// ── Sync-state subscriptions ────────────────────────────────────────────
-// The automerge worker pushes per-document heads only to the tabs that ask for
-// them (see SyncStateDocMessage). We ref-count locally so several callers in
-// this tab can watch the same doc with a single worker subscription, and tear
-// the worker subscription down when the last local watcher drops.
+// Ref-counted locally so several callers in this tab can watch the same doc
+// with a single worker subscription.
 type SyncStateListener = (update: SyncStateDocMessage) => void;
 const syncStateListeners = new Map<string, Set<SyncStateListener>>();
 
 function dispatchSyncState(update: SyncStateDocMessage): void {
-  const listeners = syncStateListeners.get(update.documentId);
-  if (!listeners) return;
-  for (const listener of listeners) {
+  for (const listener of syncStateListeners.get(update.documentId) ?? []) {
     try {
       listener(update);
     } catch (err) {
@@ -297,22 +390,22 @@ export function subscribeSyncState(
   let listeners = syncStateListeners.get(documentId);
   if (!listeners) {
     syncStateListeners.set(documentId, (listeners = new Set()));
-    // First local watcher for this doc — ask the worker to start pushing it.
     worker.port.postMessage({ type: "sync-sub", documentId });
   }
   listeners.add(listener);
 
   let active = true;
   return () => {
-    if (!active) return; // idempotent
+    if (!active) return;
     active = false;
     const set = syncStateListeners.get(documentId);
     if (!set) return;
     set.delete(listener);
-    if (set.size === 0) {
-      syncStateListeners.delete(documentId);
-      worker.port.postMessage({ type: "sync-unsub", documentId });
-    }
+    if (set.size > 0) return;
+    syncStateListeners.delete(documentId);
+    // Unsubscribe from whichever instance is current: recovery replays
+    // subscriptions onto a new worker, so it may not be the one captured above.
+    automergeWorker?.port.postMessage({ type: "sync-unsub", documentId });
   };
 }
 
@@ -336,11 +429,9 @@ export function connectClassicSync(
     port1.onmessage = (event) => {
       clearTimeout(timeout);
       port1.close();
-      if (event.data?.type === "connect-classic-sync-ready") {
-        resolve();
-      } else {
+      if (event.data?.type === "connect-classic-sync-ready") resolve();
+      else
         reject(new Error(event.data?.error ?? "connect-classic-sync failed"));
-      }
     };
     worker.port.postMessage({ type: "connect-classic-sync", server: url }, [
       port2,
@@ -348,104 +439,113 @@ export function connectClassicSync(
   });
 }
 
-/** Wait for a registration to have an active worker */
-function waitForActive(reg: ServiceWorkerRegistration): Promise<ServiceWorker> {
-  if (reg.active) return Promise.resolve(reg.active);
-  const worker = reg.installing || reg.waiting;
-  if (!worker)
-    return Promise.reject(new Error("no service worker in registration"));
-  return new Promise((resolve) => {
-    worker.addEventListener("statechange", () => {
-      if (worker.state === "activated") resolve(worker);
-    });
-  });
+function sendRepoPort(id: number): MessagePort {
+  const { port1, port2 } = new MessageChannel();
+  getAutomergeWorker().port.postMessage({ type: "port", id }, [port2]);
+  return port1;
 }
 
-async function openRepoChannel(): Promise<MessagePort> {
-  const worker = getAutomergeWorker();
-
-  // Send a MessagePort so the worker's repo can sync with this tab, and wait
-  // for the worker to confirm its repo is constructed before returning. The
-  // MessageChannel adapter's whenReady() force-resolves after 100ms regardless
-  // of the other end's state, so it can't be used as a real readiness signal
-  // on first boot (when the worker still has to fetch wasm and build its repo).
-  const id = ++nextRepoChannelId;
-  const { port1, port2 } = new MessageChannel();
-  const workerReady = new Promise<void>((resolve, reject) => {
-    let timeout: ReturnType<typeof setTimeout>;
+/**
+ * Wait for the worker to confirm its repo is constructed. The MessageChannel
+ * adapter's whenReady() force-resolves after 100ms regardless of the other
+ * end's state, so it can't serve as a readiness signal on first boot, when the
+ * worker still has to fetch wasm and build its repo.
+ */
+function awaitPortReady(control: MessagePort, id: number): Promise<void> {
+  return new Promise((resolve, reject) => {
     const cleanup = () => {
       clearTimeout(timeout);
-      worker.port.removeEventListener("message", listener);
+      control.removeEventListener("message", listener);
     };
     const listener = (event: MessageEvent) => {
       if (event.data?.id !== id) return;
-      if (event.data?.type === "port-ready") {
+      if (event.data.type === "port-ready") {
         cleanup();
         resolve();
-      } else if (event.data?.type === "port-failed") {
+      } else if (event.data.type === "port-failed") {
         cleanup();
         reject(new Error(`automerge worker init failed: ${event.data.error}`));
       }
     };
-    worker.port.addEventListener("message", listener);
-    // Failsafe: don't block boot forever if the worker never replies. Surface
-    // the issue and let the rest of the site come up rather than hanging on a
-    // blank page.
-    timeout = setTimeout(() => {
+    control.addEventListener("message", listener);
+    const timeout = setTimeout(() => {
       cleanup();
       reject(new Error("automerge worker port-ready timeout"));
     }, 30_000);
   });
-  worker.port.postMessage({ type: "port", id }, [port2]);
+}
+
+async function openRepoChannel(): Promise<MessagePort> {
+  const id = ++nextRepoChannelId;
+  const ready = awaitPortReady(getAutomergeWorker().port, id);
+  const port = sendRepoPort(id);
   try {
-    await workerReady;
+    await ready;
   } catch (err) {
+    // Surface the problem and let the rest of the site come up rather than
+    // hanging on a blank page.
     console.warn(
       "proceeding without worker ready ack:",
       err instanceof Error ? err.message : err
     );
   }
-  return port1;
+  return port;
 }
 
 /** Open a fresh repo sync port to the automerge worker (dev console). */
 function getRepoChannel(): MessagePort {
-  const worker = getAutomergeWorker();
-  const { port1, port2 } = new MessageChannel();
-  worker.port.postMessage({ type: "port", id: ++nextRepoChannelId }, [port2]);
-  return port1;
+  return sendRepoPort(++nextRepoChannelId);
+}
+
+function waitForActive(reg: ServiceWorkerRegistration): Promise<ServiceWorker> {
+  if (reg.active) return Promise.resolve(reg.active);
+  const worker = reg.installing || reg.waiting;
+  if (!worker) {
+    return Promise.reject(new Error("no service worker in registration"));
+  }
+  return new Promise((resolve, reject) => {
+    worker.addEventListener("statechange", () => {
+      if (worker.state === "activated") resolve(worker);
+      // Without this the promise never settles when an install fails.
+      else if (worker.state === "redundant") {
+        reject(new Error("service worker became redundant before activating"));
+      }
+    });
+  });
 }
 
 export default async function setupServiceWorker(
   options?: SetupServiceWorkerOptions
 ): Promise<SetupServiceWorkerResult> {
-  // Attach the SW→tab [lifecycle] log bridge as early as possible so boot /
-  // install / activate markers from the controlling worker are rendered here.
+  // Attach the log bridge first so the controlling worker's boot/install/
+  // activate markers are rendered here.
   installServiceWorkerLogForwarding();
-  localStorage.removeItem(key);
+  localStorage.removeItem(CACHE_VERSION_KEY);
+
+  // Cache growth can otherwise trip origin-wide eviction, which would take the
+  // Automerge IndexedDB — the user's documents — with it. Chrome/Safari decide
+  // silently from site engagement; Firefox may prompt. Denial just means
+  // default eviction.
+  void navigator.storage?.persist?.().catch(() => {});
 
   if (options?.workerPath) automergeWorkerPath = options.workerPath;
 
-  // Start the automerge worker right away so it boots (wasm, repo) while the
+  // Start the automerge worker now so it boots wasm and its repo while the
   // service worker installs.
   const shared = getAutomergeWorker();
-  // todo delete
-
-  const path = options?.path ?? "/service-worker.js";
-  // No controller at this point means the page loaded without a service
-  // worker — i.e. this is a first-time install (or a hard reload). Wait for
-  // activation so the app boots with the SW in control of generated fetches.
-  const reg = await navigator.serviceWorker.register(path, { type: "module" });
-
-  // If there's an update waiting or installing, wait for it to activate
-  let active = reg.active;
-  if (reg.installing || reg.waiting) {
-    active = await waitForActive(reg);
-  }
 
+  const reg = await navigator.serviceWorker.register(
+    options?.path ?? "/service-worker.js",
+    { type: "module" }
+  );
+
+  const active =
+    reg.installing || reg.waiting ? await waitForActive(reg) : reg.active;
   configureServiceWorker(active);
 
-  // Wait for the controller to be available
+  // No controller means the page loaded without a service worker — a first-time
+  // install or a hard reload. Wait for it so the app boots with the worker in
+  // control of generated fetches.
   if (!navigator.serviceWorker.controller) {
     await new Promise<void>((resolve) => {
       navigator.serviceWorker.addEventListener(
@@ -456,8 +556,8 @@ export default async function setupServiceWorker(
     });
   }
 
-  // A replacement service worker boots with the default cache name — re-send
-  // its configuration whenever a new one takes control.
+  // A replacement worker boots with the default cache name, so reconfigure
+  // whenever a new one takes control.
   navigator.serviceWorker.addEventListener("controllerchange", () => {
     configureServiceWorker(navigator.serviceWorker.controller);
   });
@@ -467,24 +567,27 @@ export default async function setupServiceWorker(
     "background: #fcf2f0; color: #333; border: 2px solid; border-radius: 4px"
   );
 
-  // todon't
-  (window as any).killsw = () => {
-    if (automergeWorker) {
-      automergeWorker.port.close();
-      automergeWorker = undefined;
-    }
-  };
-
   return {
     shared,
     connectClassicSync,
     getRepoChannel,
     subscribeSyncState,
+    // Called once with the boot port. If the automerge worker later dies and is
+    // recreated, the listener is called again with a fresh port — treat every
+    // call as "(re)wire your repo's sync onto this port".
     async subscribeToRepoChannel(listener: ServiceWorkerRepoChannelListener) {
-      // The automerge worker outlives the page, so unlike the old in-service-
-      // worker repo there's nothing to reconnect: one port, handed over once.
-      await listener(await openRepoChannel());
-      return () => {};
+      repoChannelListeners.add(listener);
+      const generation = workerGeneration;
+      const port = await openRepoChannel();
+      // If the worker was replaced while this channel was opening, recovery has
+      // already delivered a good port to this listener — drop the stale one
+      // rather than wiring the repo to a dead channel.
+      if (generation === workerGeneration) await listener(port);
+      return () => {
+        repoChannelListeners.delete(listener);
+      };
     },
   };
 }
+
+(window as any).bumpServiceWorkerCache = bumpServiceWorkerCache;