@inkandswitch/patchwork-bootloader 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @inkandswitch/patchwork-bootloader
 
+## 0.4.3
+
+### Patch Changes
+
+- bd9cd3d: Reliability and boot-speed fixes:
+
+  - The service worker no longer blocks responses on cache writes (they move to
+    `waitUntil`), page caching writes its three entries in parallel, non-GET
+    requests bypass the worker entirely, cache-write failures (e.g. quota) are
+    always logged, the cache is capped at 2000 entries with oldest-first
+    trimming, and boot requests persistent storage so cache growth can't trip
+    origin-wide eviction of user data.
+  - `automerge.wasm` is fetched under one URL from both the tab and the
+    automerge worker (the `?main`/`?worker` tracing query strings defeated the
+    HTTP cache, the SW cache, and the sites' preload — the ~3MB body downloaded
+    twice).
+  - Tabs now recover when the automerge SharedWorker dies or its connection is
+    stranded. Previously death was only logged and tabs silently stopped syncing
+    until reload. Silence alone never tears anything down (a slow-booting or
+    busy worker delivers everything queued once it catches up): a silent port
+    first starts a non-destructive probe — a second connection to the same
+    instance — and only when the probe gets a `hello` while the original port
+    stays silent (proving a live instance with a stranded port) is the worker
+    handle recreated, with sync-state subscriptions replayed and every
+    subscriber's repo re-wired onto a fresh port. This rescues boots whose
+    initial SharedWorker port comes up deaf (~6s), including in hidden
+    background tabs; a port `close` event still recovers immediately.
+  - The worker no longer rescans every doc handle on every
+    `subduction-remote-heads` event (quadratic during sync bursts); it tracks
+    just the reported doc.
+  - `ModuleWatcher` announces are generation-tracked, so a stale retry of an
+    older module version can no longer land after a newer version and roll the
+    registry back.
+  - `resolveAccountHandle` never overwrites a valid stored account pointer when
+    `repo.find` fails: it retries briefly and then throws, instead of silently
+    creating a fresh account and orphaning the user's workspace.
+  - `OverlayRepo` no longer memoizes rejected resolutions: a `find` that failed
+    because the doc (or its keyhive access) hadn't synced yet used to pin every
+    later `find` of that url to the same cached rejection, so the views' "retry
+    once access syncs" recovery could never reach the base repo. Rejections now
+    evict and the next `find` re-resolves. `findWithProgress().subscribe` also
+    no longer leaks its inner subscription (or fires the callback) when
+    unsubscribed before the resolution settles.
+
+- Updated dependencies [bd9cd3d]
+  - @inkandswitch/patchwork-filesystem@0.2.1
+  - @inkandswitch/patchwork-plugins@1.0.1
+  - @inkandswitch/patchwork-providers@0.4.1
+
 ## 0.4.2
 
 ### Patch Changes

package/dist/automerge-worker.js

@@ -172,11 +172,9 @@ setInterval(() => {
     const gap = now - watchdogLast;
     watchdogLast = now;
     if (gap > WATCHDOG_TICK_MS * WATCHDOG_GAP_FACTOR) {
-        console.warn(`[lifecycle] worker resumed after ~${Math.round(gap / 1000)}s gap ` +
-            `(timer expected every ${WATCHDOG_TICK_MS / 1000}s) — likely ` +
-            `suspended/frozen/throttled; WebSocket keepalive pongs were not sent ` +
-            `during this window, so the sync server may have reaped us. at ` +
-            `${new Date(now).toISOString()}`);
+        console.warn(`[lifecycle] ${new Date(now).toISOString()} watchdog timer gap ` +
+            `~${Math.round(gap / 1000)}s (expected every ` +
+            `${WATCHDOG_TICK_MS / 1000}s)`);
     }
 }, WATCHDOG_TICK_MS);
 // Sync server selection. Sub is the default. Build with KEYHIVE_SYNC_SERVER=true
@@ -225,9 +223,7 @@ function getSubductionEndpoints() {
                 : [
                     new WorkerWebSocketEndpoint(SUBDUCTION_SYNC_URL, {
                         worker: subductionPortProvider.source,
-                        ...(WS_WINDOW_FRAMES
-                            ? { windowFrames: WS_WINDOW_FRAMES }
-                            : {}),
+                        ...(WS_WINDOW_FRAMES ? { windowFrames: WS_WINDOW_FRAMES } : {}),
                     }),
                 ];
     }
@@ -273,7 +269,7 @@ async function connectClassicSyncNetwork(server) {
         throw err;
     }
 }
-const siteName = typeof __SITE_NAME__ !== "undefined" ? __SITE_NAME__ : "tiny-patchwork";
+const siteName = typeof __SITE_NAME__ !== "undefined" ? __SITE_NAME__ : "patchwork.inkandswitch.com";
 const cacheableStatuses = [200, 203, 204];
 function log(...args) {
     if (!debugging)
@@ -288,7 +284,7 @@ function getRepoHive() {
             log("getRepo: starting");
             log("fetching wasm modules");
             const [amWasmBuf, sdnWasmBuf] = await Promise.all([
-                fetch("/automerge.wasm?worker").then((r) => r.arrayBuffer()),
+                fetch("/automerge.wasm").then((r) => r.arrayBuffer()),
                 fetch("/subduction.wasm").then((r) => r.arrayBuffer()),
             ]);
             initSubductionSync(new Uint8Array(sdnWasmBuf));
@@ -612,8 +608,13 @@ function setupSyncStateBroadcast(repo, identity) {
         byStorage.set(storageId, { heads: headsCopy, timestamp });
         postHeads(documentId, storageId, headsCopy, timestamp);
         // A doc the server reported is one we hold — make sure we're advertising
-        // our own heads for it too.
-        scanOwnHandles();
+        // our own heads for it too. Track just this doc: a full scanOwnHandles()
+        // per event is O(all handles) and goes quadratic during sync bursts,
+        // starving the thread that's doing the syncing. The 3s tick still covers
+        // general discovery.
+        const handle = repo.handles[documentId];
+        if (handle)
+            trackOwnHandle(handle);
         reviewResync(documentId);
     });
     repo.on("subduction-connection", ({ connected: isConnected }) => {
@@ -717,6 +718,16 @@ async function connectPort(port, connection) {
 }
 function handleControlMessage(event, controlPort, connection) {
     const data = event.data;
+    // Tally of control messages received, readable from the SharedWorker console
+    // as `self.patchworkControl`. Not using log(): that's gated on `debugging`,
+    // which is only enabled by a {type:"debug"} message arriving over this same
+    // channel.
+    const stats = (self.patchworkControl ??= {
+        connects: 0,
+        byType: {},
+    });
+    stats.byType[String(data?.type ?? "<untyped>")] =
+        (stats.byType[String(data?.type ?? "<untyped>")] ?? 0) + 1;
     if (data?.type === "port") {
         log("received repo channel");
         const [repoPort] = event.ports;
@@ -777,6 +788,7 @@ function handleControlMessage(event, controlPort, connection) {
 self.addEventListener("connect", (event) => {
     const controlPort = event.ports[0];
     const connection = { channels: new Set() };
+    (self.patchworkControl ??= { connects: 0, byType: {} }).connects++;
     controlPort.addEventListener("message", (messageEvent) => {
         handleControlMessage(messageEvent, controlPort, connection);
     });
@@ -848,6 +860,13 @@ function waitForHeads(handle, hexHeads, signal) {
         check();
     });
 }
+/**
+ * Thrown instead of returning a Response when the request should fail as a
+ * network error rather than resolve to something the caller can memoize.
+ * See {@link HandoffAbortMessage}.
+ */
+class AbortHandoff extends Error {
+}
 async function resolveAutomergeUrl(automergeURL) {
     const { repo } = await getRepoHive();
     const href = automergeURL.href;
@@ -878,7 +897,10 @@ async function resolveAutomergeUrl(automergeURL) {
     // The heads may not have synced to us yet — give them the rest of the
     // resolve window to arrive before giving up.
     if (!(await waitForHeads(baseHandle, hexHeads ?? [], signal))) {
-        return new Response("heads not found", { status: 404 });
+        // Not a 404: the heads may still be on their way, and this exact URL will
+        // be requested again once they land. Fail it as a network error so the
+        // caller doesn't memoize the miss.
+        throw new AbortHandoff(`heads not found for ${maybeAutomergeUrl} within ${RESOLVE_TIMEOUT_MS}ms`);
     }
     const rootHandle = baseHandle.view(heads);
     const resolved = await resolvePath(repo, rootHandle, path.map(decodeURIComponent));
@@ -949,6 +971,14 @@ async function handleHandoffRequest(message) {
         ]);
     }
     catch (error) {
+        if (error instanceof AbortHandoff) {
+            handoffChannel.postMessage({
+                id,
+                type: "abort",
+                reason: error.message,
+            });
+            return;
+        }
         const body = error instanceof Error
             ? `${error.message}\n\n${error.stack}`
             : String(error);

package/dist/service-worker.js

@@ -135,6 +135,9 @@ handoffChannel.addEventListener("message", (event) => {
         }
     }
 });
+/** Signals that respondWith should reject; see {@link HandoffAbortMessage}. */
+class HandoffAborted extends Error {
+}
 function handoff(request, handoffURL) {
     const id = crypto.randomUUID();
     const resolvers = Promise.withResolvers();
@@ -190,19 +193,34 @@ function rootRequestFor(request) {
 }
 async function cachePage(cache, request, response) {
     const indexRequest = indexRequestFor(request);
-    if (indexRequest)
-        await cache.put(indexRequest, response.clone());
     const rootRequest = rootRequestFor(request);
-    if (rootRequest)
-        await cache.put(rootRequest, response.clone());
-    await cache.put(request, response);
+    await Promise.all([
+        indexRequest && cache.put(indexRequest, response.clone()),
+        rootRequest && cache.put(rootRequest, response.clone()),
+        cache.put(request, response),
+    ]);
+}
+// Write to the cache without blocking the response: cache.put only resolves
+// once the whole body has been consumed and persisted, so awaiting it before
+// returning would turn time-to-first-byte into time-to-last-byte-plus-disk
+// for every proxied asset. waitUntil keeps the worker alive for the write.
+function cacheInBackground(fetchEvent, cache, request, response) {
+    fetchEvent.waitUntil((request.mode === "navigate" || request.destination === "document"
+        ? cachePage(cache, request, response)
+        : cache.put(request, response)).catch((error) => {
+        // Always loud (not gated on debugging): a QuotaExceededError here is
+        // the first sign the origin is under storage pressure.
+        console.warn(`error caching ${request.url} in ${cachename}`, error);
+    }));
 }
 // ── Fetch handler ──────────────────────────────────────────────────────
 self.addEventListener("fetch", (fetchEvent) => {
     log("fetch event", fetchEvent.request.url);
     const request = fetchEvent.request;
+    // Not calling respondWith at all lets the browser handle non-GETs natively
+    // instead of proxying their bodies through this worker.
     if (request.method !== "GET")
-        return fetchEvent.respondWith(fetch(request));
+        return;
     const url = new URL(fetchEvent.request.url);
     let handoffURL;
     if (url.hostname == self.location.hostname &&
@@ -227,6 +245,13 @@ self.addEventListener("fetch", (fetchEvent) => {
                 const replyPromise = handoff(request, handoffURL);
                 fetchEvent.waitUntil(replyPromise.catch(() => { }));
                 const reply = await replyPromise;
+                if (reply.type === "abort") {
+                    // Rejecting respondWith gives the caller a network error rather
+                    // than a response it can memoize. Rethrown past the catch below,
+                    // which would otherwise turn this into a 556.
+                    log(`aborting ${handoffURL}: ${reply.reason}`);
+                    throw new HandoffAborted(reply.reason);
+                }
                 if (reply.type === "response") {
                     // errors, redirects and other things that shouldn't be cached
                     log(`serving handed-off response for ${handoffURL}`, reply);
@@ -258,13 +283,7 @@ self.addEventListener("fetch", (fetchEvent) => {
                     if ((response.status === 0 ||
                         cacheableStatuses.includes(response.status)) &&
                         /^https?:/.test(request.url)) {
-                        const cachedResponse = response.clone();
-                        await (request.mode === "navigate" ||
-                            request.destination === "document"
-                            ? cachePage(cache, request, cachedResponse)
-                            : cache.put(request, cachedResponse)).catch((error) => {
-                            log(`error caching ${request.url} in ${cachename}`, error);
-                        });
+                        cacheInBackground(fetchEvent, cache, request, response.clone());
                     }
                     else {
                         log(`skipping uncacheable response code from cache: ${response.status} for ${request.url}`);
@@ -277,6 +296,9 @@ self.addEventListener("fetch", (fetchEvent) => {
             }
         }
         catch (error) {
+            // Deliberate: fail the request as a network error, no response.
+            if (error instanceof HandoffAborted)
+                throw error;
             const message = error instanceof Error
                 ? `${error.message}\n\n${error.stack}`
                 : String(error);

package/dist/setup.js

@@ -70,12 +70,82 @@ function configureServiceWorker(sw) {
 }
 // ── 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.
+// instance is shared by every tab and normally lives as long as any tab
+// does — but browsers do reap SharedWorkers under memory pressure, so we
+// heartbeat it and rebuild everything if it dies (see
+// recoverAutomergeWorker). Repo sync ports are passed to it over its
+// connect port; it talks to the service worker over a BroadcastChannel.
 let automergeWorkerPath = "/automerge-worker.js";
 let automergeWorker;
+// Bumped whenever a new SharedWorker is constructed. 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 the generation they started in.
+let workerGeneration = 0;
+// Tears down the current worker's heartbeat when it's replaced.
+let disposeWorkerDeathDetection;
+// Every subscribeToRepoChannel listener, kept so a recovered worker can hand
+// each subscriber a fresh repo port.
+const repoChannelListeners = new Set();
+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;
+/**
+ * The automerge SharedWorker died (browser reaped it, or it crashed): build a
+ * replacement and re-wire everything a live tab holds against it — console
+ * forwarding and the io-proxy port donation (both re-done by
+ * getAutomergeWorker), the per-doc sync-state subscriptions, and every
+ * subscriber's repo sync port. The new instance boots with cold state; its
+ * repo is reconstructed on the first port we send.
+ */
+async function recoverAutomergeWorker(reason, deadWorker) {
+    if (deadWorker !== automergeWorker)
+        return; // already replaced
+    if (recoveringWorker)
+        return;
+    const now = Date.now();
+    if (now - lastWorkerRecoveryAt < RECOVERY_MIN_INTERVAL_MS)
+        return;
+    recoveringWorker = true;
+    lastWorkerRecoveryAt = now;
+    console.warn(`[lifecycle] ${new Date().toISOString()} recreating the automerge ` +
+        `SharedWorker (${reason})`);
+    try {
+        disposeWorkerDeathDetection?.();
+        disposeWorkerDeathDetection = undefined;
+        automergeWorker = undefined;
+        try {
+            deadWorker.port.close();
+        }
+        catch {
+            // Port already dead.
+        }
+        const fresh = getAutomergeWorker();
+        // The fresh instance knows nothing — replay every doc subscription.
+        for (const documentId of syncStateListeners.keys()) {
+            fresh.port.postMessage({ type: "sync-sub", documentId });
+        }
+        // Hand every repo-channel subscriber a fresh port so their repos sync
+        // again (the old adapters sit on dead MessagePorts).
+        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;
+    }
+}
 // 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).
@@ -107,13 +177,23 @@ function workerBenchParams() {
     const qs = params.toString();
     return qs ? `?${qs}` : "";
 }
+function automergeWorkerUrl() {
+    return `${automergeWorkerPath}${workerBenchParams()}`;
+}
 export function getAutomergeWorker() {
     if (!automergeWorker) {
-        const workerUrl = `${automergeWorkerPath}${workerBenchParams()}`;
-        automergeWorker = new SharedWorker(workerUrl, {
+        workerGeneration++;
+        automergeWorker = new SharedWorker(automergeWorkerUrl(), {
             name: "patchwork-automerge",
             type: "module",
         });
+        // Fired when a message arrives that can't be structured-deserialized —
+        // e.g. a transfer list that named something unclonable. Silent otherwise:
+        // the message is simply dropped, which looks identical to a worker that
+        // never replied. Always loud, not gated on the lifecycle toggle.
+        automergeWorker.port.addEventListener("messageerror", (event) => {
+            console.error("[automerge-worker] undeserializable message from worker:", event);
+        });
         // Control replies (port-ready &c) come back on this port, so it needs
         // start() — we listen with addEventListener, not onmessage.
         automergeWorker.port.start();
@@ -169,16 +249,37 @@ export function getAutomergeWorker() {
                 type: "module",
                 name: "subduction-websocket",
             });
+            // This worker carries the websocket to the sync server, so if it fails
+            // to load, sync silently stops with no other symptom.
+            io.addEventListener("error", (event) => {
+                const error = event;
+                console.error(`[subduction-io] failed to load/run ${SUBDUCTION_IO_WORKER_URL}:`, error.message || event, error.filename ? `(${error.filename}:${error.lineno})` : "");
+            });
+            io.port.addEventListener("messageerror", (event) => {
+                console.error("[subduction-io] undeserializable message:", event);
+            });
             return io.port;
         });
-        installWorkerDeathDetection(automergeWorker);
+        disposeWorkerDeathDetection = installWorkerDeathDetection(automergeWorker);
     }
     return automergeWorker;
 }
 /**
- * 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.
+ * Detect when the automerge SharedWorker dies or its control port goes deaf.
+ *
+ * Silence alone is NOT proof of death: the worker may still be evaluating its
+ * (large) module graph on a cold boot, or its single thread may be busy with
+ * wasm/sync work — in both cases every queued message (including the repo
+ * ports the network adapters ride on) is delivered fine once it catches up,
+ * and tearing the port down would *lose* them. So silence only starts a
+ * non-destructive PROBE: a second SharedWorker connection to the same
+ * instance. Only when the probe gets a `hello` while this port stays silent do
+ * we know the instance is alive-and-responsive but our port is stranded (a
+ * failure mode observed in the wild) — or was replaced — and recovery is
+ * warranted. A `close` event (where supported) is a definitive death signal
+ * and recovers immediately. [lifecycle]-tagged. Returns a dispose that stops
+ * the heartbeat and any outstanding probe (called when this worker is
+ * replaced).
  */
 function installWorkerDeathDetection(worker) {
     const stamp = () => new Date().toISOString();
@@ -191,53 +292,135 @@ function installWorkerDeathDetection(worker) {
             console.info(`[lifecycle] ${stamp()} ${msg}`);
     };
     let instanceId;
-    let lastPongAt = Date.now();
+    let lastHeardAt = Date.now();
     let warnedUnresponsive = false;
+    let disposed = false;
+    let probe;
+    const closeProbe = () => {
+        if (!probe)
+            return;
+        try {
+            probe.port.close();
+        }
+        catch {
+            // Already closed.
+        }
+        probe = undefined;
+    };
+    let warnedSendFailed = false;
+    let pingsSent = 0;
     worker.port.addEventListener("message", (event) => {
         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;
+        // The port spoke — any outstanding probe is moot.
+        closeProbe();
         if (instanceId === undefined) {
             instanceId = data.instanceId;
             info(`automerge SharedWorker instance ${data.instanceId} (via ${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`);
+            warn(`automerge SharedWorker instance changed (instance ${data.instanceId}, ` +
+                `was ${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;
+        warn("automerge SharedWorker control port closed");
+        void recoverAutomergeWorker("control port closed", worker);
     });
+    // Not gated on the lifecycle toggle: a worker that fails to load never
+    // replies to anything, and this is the only signal that says so.
     worker.addEventListener("error", event => {
-        warn(`automerge SharedWorker error: ${event.message || event}`);
+        const error = event;
+        console.error(`[lifecycle] ${stamp()} automerge SharedWorker error:`, error.message || event, error.filename ? `(${error.filename}:${error.lineno})` : "");
     });
-    // 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;
+    // On probe hello, give the suspect port this long to also speak before
+    // concluding it's stranded: after a slow worker boot both connections hello
+    // at roughly the same moment and cross-port delivery order isn't guaranteed.
+    const PROBE_GRACE_MS = 500;
+    const startProbe = (reason) => {
+        if (probe || disposed)
+            return;
+        warn(`automerge SharedWorker ${reason}; probing with a second connection`);
+        const startedAt = Date.now();
+        const p = new SharedWorker(automergeWorkerUrl(), {
+            name: "patchwork-automerge",
+            type: "module",
+        });
+        probe = p;
+        p.port.start();
+        p.port.addEventListener("message", (event) => {
+            if (event.data?.type !== "hello")
+                return;
+            setTimeout(() => {
+                if (disposed || probe !== p)
+                    return; // superseded or torn down
+                closeProbe();
+                // The suspect spoke while (or just after) the probe ran: it was
+                // merely slow/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 — its hello triggers the check above whenever it
+        // lands) — never tear anything down on a timer.
+    };
+    // A silent-too-long port while the tab is visible starts a probe (a miss
+    // while hidden is more likely suspension). Before first contact the budget
+    // is tighter: an idle worker hellos within milliseconds of connecting, so
+    // probing early costs nothing and rescues genuinely stranded boots fast.
+    const HEARTBEAT_MS = 5_000;
     const HEARTBEAT_TIMEOUT_MS = 25_000;
+    const FIRST_CONTACT_TIMEOUT_MS = 4_000;
     let seq = 0;
-    setInterval(() => {
+    const heartbeat = setInterval(() => {
         try {
             worker.port.postMessage({ type: "ping", id: ++seq });
+            pingsSent++;
         }
-        catch {
-            // Port already torn down — the "close" handler covers that case.
+        catch (error) {
+            // Swallowing this makes a failed send indistinguishable from a dead
+            // worker in the "no pong" warning below. Once, not every heartbeat.
+            if (!warnedSendFailed) {
+                warnedSendFailed = true;
+                console.error(`[lifecycle] ${stamp()} automerge SharedWorker ping send threw ` +
+                    `after ${pingsSent} sent:`, 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;
         const visible = typeof document === "undefined" || document.visibilityState === "visible";
-        if (silentMs > HEARTBEAT_TIMEOUT_MS && visible && !warnedUnresponsive) {
-            warnedUnresponsive = true;
-            warn(`automerge SharedWorker UNRESPONSIVE ~${Math.round(silentMs / 1000)}s ` +
-                `while tab visible — likely died/crashed`);
+        // First contact probes regardless of visibility: SharedWorkers don't
+        // suspend with tab visibility, boots in background tabs must still get
+        // rescued, and the probe destroys nothing. Post-contact silence defers to
+        // visibility, since a hidden page's own throttling can fake it.
+        if (silentMs > timeoutMs && (neverHeard || visible)) {
+            const reason = neverHeard
+                ? `no hello ~${Math.round(silentMs / 1000)}s after connecting`
+                : `no pong for ~${Math.round(silentMs / 1000)}s`;
+            if (!warnedUnresponsive) {
+                warnedUnresponsive = true;
+                warn(`automerge SharedWorker ${reason} (tab visible)`);
+            }
+            startProbe(reason);
         }
     }, HEARTBEAT_MS);
+    return () => {
+        disposed = true;
+        clearInterval(heartbeat);
+        closeProbe();
+    };
 }
 const syncStateListeners = new Map();
 function dispatchSyncState(update) {
@@ -273,7 +456,10 @@ export function subscribeSyncState(documentId, listener) {
         set.delete(listener);
         if (set.size === 0) {
             syncStateListeners.delete(documentId);
-            worker.port.postMessage({ type: "sync-unsub", documentId });
+            // The worker may have been replaced since we subscribed (recovery
+            // replays subscriptions onto the new instance) — unsubscribe from
+            // whichever instance is current, not the one captured above.
+            automergeWorker?.port.postMessage({ type: "sync-unsub", documentId });
         }
     };
 }
@@ -375,6 +561,11 @@ export default async function setupServiceWorker(options) {
     // install / activate markers from the controlling worker are rendered here.
     installServiceWorkerLogForwarding();
     localStorage.removeItem(key);
+    // Ask for persistent storage so cache growth can't 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
+    // show a one-time prompt. Best-effort: 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
@@ -417,10 +608,22 @@ export default async function setupServiceWorker(options) {
         getRepoChannel,
         subscribeSyncState,
         async subscribeToRepoChannel(listener) {
-            // 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 () => { };
+            // Called once with the boot port. If the automerge worker later dies
+            // and is recreated (recoverAutomergeWorker), the listener is called
+            // again with a fresh port — treat every call as "(re)wire your repo's
+            // sync onto this port".
+            repoChannelListeners.add(listener);
+            const generation = workerGeneration;
+            const port = await openRepoChannel();
+            // If the worker was replaced while this channel was opening (e.g. the
+            // port-ready wait timed out against a stranded connection and recovery
+            // 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);
+            };
         },
     };
 }