@inkandswitch/patchwork-bootloader 0.4.1 → 0.4.3

package/src/setup.ts

@@ -89,13 +89,85 @@ function configureServiceWorker(sw: ServiceWorker | null) {
 
 // ── 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: SharedWorker | undefined;
+// 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: (() => void) | undefined;
+// Every subscribeToRepoChannel listener, kept so a recovered worker can hand
+// each subscriber a fresh repo port.
+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;
+
+/**
+ * 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: string,
+  deadWorker: SharedWorker
+): Promise<void> {
+  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
@@ -129,13 +201,27 @@ function workerBenchParams(): string {
   return qs ? `?${qs}` : "";
 }
 
+function automergeWorkerUrl(): string {
+  return `${automergeWorkerPath}${workerBenchParams()}`;
+}
+
 export function getAutomergeWorker(): SharedWorker {
   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();
@@ -191,20 +277,45 @@ export function getAutomergeWorker(): SharedWorker {
         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 as ErrorEvent;
+        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: SharedWorker): void {
+function installWorkerDeathDetection(worker: SharedWorker): () => void {
   const stamp = () => new Date().toISOString();
   const warn = (msg: string) => {
     if (lifecycleLoggingEnabled()) console.warn(`[lifecycle] ${stamp()} ${msg}`);
@@ -214,23 +325,37 @@ function installWorkerDeathDetection(worker: SharedWorker): void {
   };
 
   let instanceId: string | undefined;
-  let lastPongAt = Date.now();
+  let lastHeardAt = Date.now();
   let warnedUnresponsive = false;
+  let disposed = false;
+  let probe: SharedWorker | undefined;
+
+  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: 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;
+    // 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`
+        `automerge SharedWorker instance changed (instance ${data.instanceId}, ` +
+          `was ${instanceId})`
       );
       instanceId = data.instanceId;
     }
@@ -238,35 +363,107 @@ function installWorkerDeathDetection(worker: SharedWorker): void {
 
   // 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 as ErrorEvent).message || event}`);
+    const error = event as ErrorEvent;
+    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: string) => {
+    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: MessageEvent) => {
+      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 });
-    } catch {
-      // Port already torn down — the "close" handler covers that case.
+      pingsSent++;
+    } 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();
+  };
 }
 
 // ── Sync-state subscriptions ────────────────────────────────────────────
@@ -311,7 +508,10 @@ export function subscribeSyncState(
     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 });
     }
   };
 }
@@ -424,6 +624,12 @@ export default async function setupServiceWorker(
   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
@@ -481,10 +687,21 @@ export default async function setupServiceWorker(
     getRepoChannel,
     subscribeSyncState,
     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 () => {};
+      // 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);
+      };
     },
   };
 }

package/src/site.ts

@@ -37,7 +37,7 @@ import { MemorySigner } from "@automerge/automerge-subduction/slim";
 
 declare const __SITE_NAME__: string;
 const siteName =
-  typeof __SITE_NAME__ !== "undefined" ? __SITE_NAME__ : "tiny-patchwork";
+  typeof __SITE_NAME__ !== "undefined" ? __SITE_NAME__ : "patchwork.inkandswitch.com";
 
 // Sync-server selection for keyhive. Defaults to "subduction". Build with
 // KEYHIVE_SYNC_SERVER=true to target keyhive.sync.automerge.org. This must match
@@ -48,7 +48,7 @@ const useKeyhiveSyncServer =
   typeof __KEYHIVE_SYNC_SERVER__ !== "undefined" && __KEYHIVE_SYNC_SERVER__;
 
 import { ModuleWatcher } from "@inkandswitch/patchwork-filesystem";
-import { importAutomergeModuleViaWorker } from "./module-loader.js";
+import { importAutomergePackageViaWorker } from "./module-loader.js";
 import {
   openDocument,
   registerPatchworkViewElement,
@@ -65,10 +65,7 @@ import {
 } from "@inkandswitch/patchwork-plugins";
 import * as plugins from "@inkandswitch/patchwork-plugins";
 
-import setupServiceWorker, {
-  getAutomergeWorker,
-  lifecycleLoggingEnabled,
-} from "./setup.js";
+import setupServiceWorker, { lifecycleLoggingEnabled } from "./setup.js";
 import type {
   ServiceWorkerRepoChannelListener,
   SyncStateDocMessage,
@@ -126,7 +123,7 @@ export interface SiteConfig {
    * folder docs or plain HTTP(S) bundles, so deployment targets can be freely
    * mixed.
    *
-   * Can be overridden at runtime by setting `localStorage.defaultToolsUrl` to
+   * Can be overridden at runtime by setting `localStorage.systemPackageListURL` to
    * another `automerge:` URL or manifest URL — useful for local development
    * against an unpublished tool set.
    */
@@ -179,7 +176,7 @@ const BIG_PATCHWORK_HASH_REGEX =
   /^(?<title>[^=&?/#]*)--(?<docId>[1-9A-HJ-NP-Za-km-z]+)/;
 
 const [automergeWasm, subductionWasm] = await Promise.all([
-  fetch("/automerge.wasm?main").then((r) => r.bytes()),
+  fetch("/automerge.wasm").then((r) => r.bytes()),
   fetch("/subduction.wasm").then((r) => r.bytes()),
 ]);
 
@@ -211,6 +208,10 @@ export async function bootPatchworkSite(
   let repo: Repo;
   let tabSignerIdentity: { peerId: string; verifyingKey: string } | undefined;
 
+  // Called with a fresh port when the automerge worker dies and is recreated
+  // (see recoverAutomergeWorker in setup.ts); assigned once the repo exists.
+  let onWorkerPortRenewed: ((port: MessagePort) => void) | undefined;
+
   // If a Repo is already on `window` — an embedding context provided one before
   // this entry ran — reuse it and its keyhive instead of standing up a fresh
   // realm-local Repo, so we share the same documents and sync/keyhive context.
@@ -222,14 +223,34 @@ export async function bootPatchworkSite(
   } else {
     // Get the initial automerge-worker port via subscribeToRepoChannel,
     // then pass it to keyhive init which wraps it in its own network adapter.
-    let resolvePort!: (port: MessagePort) => void;
-    const portPromise = new Promise<MessagePort>((r) => {
-      resolvePort = r;
+    // The listener is called again with a fresh port if the worker is ever
+    // recreated after dying.
+    let resolveFirstPort!: (port: MessagePort) => void;
+    const firstPortPromise = new Promise<MessagePort>((r) => {
+      resolveFirstPort = r;
     });
+    let seenFirstPort = false;
     log("subscribing to repo channel");
-    await sw.subscribeToRepoChannel(resolvePort);
+    // Deliberately not awaited: subscribeToRepoChannel resolves only after
+    // the boot channel's port-ready handshake, which can take its full 30s
+    // timeout against a stranded worker connection. Boot should block on the
+    // first *delivered* port instead — if the boot channel stalls, worker
+    // recovery hands the listener a good port long before that timeout.
+    void sw.subscribeToRepoChannel((port) => {
+      if (!seenFirstPort) {
+        seenFirstPort = true;
+        resolveFirstPort(port);
+      } else if (onWorkerPortRenewed) {
+        onWorkerPortRenewed(port);
+      } else {
+        console.warn(
+          "automerge worker port renewed before the repo existed; dropping it"
+        );
+      }
+    });
+    const workerPort = await firstPortPromise;
     log("repo channel subscribed");
-    const workerPort = await portPromise;
+    let workerAdapter = new MessageChannelNetworkAdapter(workerPort);
 
     if (config.keyhive) {
       log("setting up keyhive");
@@ -239,7 +260,7 @@ export async function bootPatchworkSite(
         createRepo: (config) => new Repo(config),
         storage: new IndexedDBWorkerStorageAdapter(`${siteName}-keyhive`),
         peerIdSuffix: siteName + Math.random().toString(36).slice(2),
-        networkAdapter: new MessageChannelNetworkAdapter(workerPort),
+        networkAdapter: workerAdapter,
         automaticArchiveIngestion: true,
         cachingMode: "periodic",
         onlyShareWithHardcodedServerPeerId: false,
@@ -260,7 +281,7 @@ export async function bootPatchworkSite(
       // id never goes on the wire.
       const tabSigner = new MemorySigner();
       repo = new Repo({
-        network: [new MessageChannelNetworkAdapter(workerPort)],
+        network: [workerAdapter],
         storage: new IndexedDBWorkerStorageAdapter(),
         signer: tabSigner,
         async sharePolicy(peerId) {
@@ -281,6 +302,37 @@ export async function bootPatchworkSite(
       console.log("[patchwork] tab subduction identity:", tabSignerIdentity);
       log("repo created");
     }
+
+    // The worker was recreated with cold state: wire the repo onto the fresh
+    // port and drop the adapter stranded on the dead one. `repo`/`hive` are
+    // settled by the time this can fire (recovery needs a missed heartbeat).
+    const bootHive = hive;
+    onWorkerPortRenewed = (port) => {
+      const fresh = new MessageChannelNetworkAdapter(port);
+      // Mirror the boot wiring: a keyhive repo talks to the worker through a
+      // keyhive adapter wrapped around the message channel (same parameters
+      // the worker uses for its side of the pair).
+      const registered = bootHive
+        ? bootHive.createKeyhiveNetworkAdapter(fresh, false, false, 2000)
+        : fresh;
+      repo.networkSubsystem.addNetworkAdapter(registered as any);
+      for (const adapter of [...repo.networkSubsystem.adapters]) {
+        if (adapter === (registered as any)) continue;
+        // The keyhive wrapper keeps the wrapped adapter on `.networkAdapter`.
+        const base = (adapter as any).networkAdapter ?? adapter;
+        if (base !== workerAdapter) continue;
+        try {
+          repo.networkSubsystem.removeNetworkAdapter(adapter as any);
+        } catch (err) {
+          console.error("failed to remove stale worker network adapter", err);
+        }
+      }
+      workerAdapter = fresh;
+      console.warn(
+        `[lifecycle] ${new Date().toISOString()} repo re-wired to the ` +
+          `recreated automerge worker`
+      );
+    };
   }
   log("popping repo on window");
   window.repo = repo;
@@ -322,7 +374,7 @@ export async function bootPatchworkSite(
     unregisterPlugins,
     // Discover an Automerge package's plugin descriptors off the main thread;
     // each plugin's load() re-imports the package (at heads) on this thread.
-    importAutomergeModuleViaWorker
+    importAutomergePackageViaWorker
   );
 
   const accountDocHandle = (await resolveAccountHandle(repo, {
@@ -381,7 +433,7 @@ function isValidModuleSource(source: string): boolean {
 
 /**
  * Resolve the site's default module-list sources, honouring the
- * `localStorage.defaultToolsUrl` dev override (which replaces the entire
+ * `localStorage.systemPackageListURL` dev override (which replaces the entire
  * built-in default bundle).
  */
 function resolveDefaultModules(config: SiteConfig): string[] {
@@ -390,18 +442,22 @@ function resolveDefaultModules(config: SiteConfig): string[] {
     Boolean
   );
 
-  const override = globalThis.localStorage?.getItem("defaultToolsUrl");
+  const storage = globalThis.localStorage;
+  // `defaultToolsUrl` is the pre-rename key, still honoured for existing browsers.
+  const override =
+    storage?.getItem("systemPackageListURL") ??
+    storage?.getItem("defaultToolsUrl");
   if (override) {
     if (isValidModuleSource(override)) {
       if (!builtinList.includes(override)) {
         console.info(
-          `using defaultToolsUrl override from localStorage: ${override}`
+          `using systemPackageListURL override from localStorage: ${override}`
         );
       }
       return [override];
     }
     console.warn(
-      `ignoring invalid defaultToolsUrl in localStorage: ${override}; using built-in default`
+      `ignoring invalid systemPackageListURL in localStorage: ${override}; using built-in default`
     );
   }
 
@@ -462,16 +518,26 @@ function installLifecycleLogging(): void {
     () => note(`visibilitychange → ${document.visibilityState}`),
     opts
   );
-  document.addEventListener("freeze", () => note("freeze (tab suspended)"), opts);
-  document.addEventListener("resume", () => note("resume (tab unsuspended)"), opts);
+  document.addEventListener(
+    "freeze",
+    () => note("freeze (tab suspended)"),
+    opts
+  );
+  document.addEventListener(
+    "resume",
+    () => note("resume (tab unsuspended)"),
+    opts
+  );
   window.addEventListener(
     "pageshow",
-    e => note("pageshow", { persisted: (e as PageTransitionEvent).persisted }),
+    (e) =>
+      note("pageshow", { persisted: (e as PageTransitionEvent).persisted }),
     opts
   );
   window.addEventListener(
     "pagehide",
-    e => note("pagehide", { persisted: (e as PageTransitionEvent).persisted }),
+    (e) =>
+      note("pagehide", { persisted: (e as PageTransitionEvent).persisted }),
     opts
   );
   window.addEventListener("online", () => note("online"), opts);

package/src/types.ts

@@ -161,7 +161,28 @@ export interface HandoffResponseMessage {
   response: HandoffResponse;
 }
 
-export type HandoffReplyMessage = HandoffCachedMessage | HandoffResponseMessage;
+/**
+ * Automerge worker → service worker: fail the request as a network error
+ * rather than serving any response at all.
+ *
+ * "Heads haven't arrived yet" is not a 404 — the document may well exist, so
+ * a status implying it doesn't is a lie any HTTP cache is entitled to store.
+ * A network error is the honest answer and isn't storable as a response.
+ *
+ * This does *not* help with `import()`: the ES module map memoizes failed
+ * fetches, network errors included, so a retry needs a distinct URL either
+ * way (see `importModule` in patchwork-filesystem).
+ */
+export interface HandoffAbortMessage {
+  id: string;
+  type: "abort";
+  reason: string;
+}
+
+export type HandoffReplyMessage =
+  | HandoffCachedMessage
+  | HandoffResponseMessage
+  | HandoffAbortMessage;
 
 /**
  * Automerge worker → world: broadcast once on startup so the service worker