@mochi.js/core 0.3.0 → 0.6.0

package/src/session.ts

@@ -25,11 +25,15 @@ import {
   type NetCtx,
   type NetFetchInit,
 } from "@mochi.js/net";
+import {
+  type InitInjectorHandle,
+  installInitInjector,
+  wrapSelfRemovingPayload,
+} from "./cdp/init-injector";
 import { MessageRouter } from "./cdp/router";
 import type { AttachedToTargetEvent } from "./cdp/types";
 import { Page } from "./page";
 import type { ChromiumProcess } from "./proc";
-import { installProxyAuth, type ProxyAuthHandle } from "./proxy-auth";
 import { VERSION } from "./version";
 
 /**
@@ -49,6 +53,40 @@ const defaultNetAdapter: NetAdapter = {
   requestOnCtx: defaultRequestOnCtx,
 };
 
+/**
+ * Per-call timeout for the worker idOnly inject roundtrip. 5s, not the
+ * router's 30s default — workers spawned by sites like sannysoft,
+ * bot.incolumitas, fingerprintjs probes routinely die between
+ * `Target.attachedToTarget` and our reply. Without a tight cap, every
+ * orphan worker stalls the route loop for the full 30s. Real workers
+ * resolve in single-digit ms; 5s is generous.
+ *
+ * If you ever see a legitimate worker fail at 5s, raise this — but the
+ * symptom would be a missing inject on a long-running worker, which is
+ * separate from the orphan-worker race we're sizing for.
+ */
+const WORKER_INJECT_TIMEOUT_MS = 5_000;
+
+/**
+ * Predicate: is this an "expected" failure from the worker idOnly inject
+ * race (worker died between attach and our roundtrip)? Recognized:
+ *   - `CdpTimeoutError` — router gave up after WORKER_INJECT_TIMEOUT_MS
+ *     because the target stopped responding. Most common path.
+ *   - CDP `Session with given id not found` — target detached mid-call.
+ *   - CDP `Target closed` — same race, different message variant.
+ *
+ * All three are routine and silent. A genuine bug (bad contextId,
+ * wrong serialization, schema drift) surfaces as anything else and
+ * still warns through the console.
+ */
+function isTransientWorkerError(err: unknown): boolean {
+  if (err === null || typeof err !== "object") return false;
+  const name = (err as { name?: string }).name;
+  if (name === "CdpTimeoutError") return true;
+  const msg = (err as { message?: string }).message ?? "";
+  return msg.includes("Session with given id not found") || msg.includes("Target closed");
+}
+
 export interface SessionInit {
   proc: ChromiumProcess;
   matrix: MatrixV1;
@@ -56,10 +94,10 @@ export interface SessionInit {
   /** Optional overrides for the underlying message-router timeout. */
   defaultTimeoutMs?: number;
   /**
-   * When true, skip {@link buildPayload} AND skip
-   * `Page.addScriptToEvaluateOnNewDocument` on every new page; worker
-   * targets receive no inject either. Intended for `mochi capture` and
-   * similar baseline-collection flows. PLAN.md §12.1, task 0040.
+   * When true, skip {@link buildPayload} AND skip the init-injector install
+   * (no `Fetch.fulfillRequest` body splice on documents); worker targets
+   * receive no inject either. Intended for `mochi capture` and similar
+   * baseline-collection flows. PLAN.md §12.1, task 0040.
    */
   bypassInject?: boolean;
   /**
@@ -118,6 +156,86 @@ export interface StorageSnapshot {
   sessionStorage: Record<string, Record<string, string>>;
 }
 
+// ---- cookie-jar persistence (task 0257) -------------------------------------
+
+/**
+ * Current on-disk cookie-file format version. Bumped on incompatible header
+ * changes. The reader refuses unknown majors with a precise diagnostic so a
+ * stale jar doesn't silently load with the wrong shape.
+ */
+export const COOKIE_JAR_FORMAT_VERSION = 1 as const;
+
+/**
+ * On-disk shape for {@link Session.cookies.save}. The `cookies` array is the
+ * verbatim `Storage.getCookies` payload — every shipped Chromium revision
+ * agrees on this shape, so loading on a newer Chromium round-trips losslessly.
+ *
+ * @see tasks/0257-dx-cluster-cookies-storage-permissions.md (success criteria)
+ * @see https://chromedevtools.github.io/devtools-protocol/tot/Storage/#method-getCookies
+ */
+export interface CookieJarFile {
+  /** Format version (currently `1`). */
+  version: typeof COOKIE_JAR_FORMAT_VERSION;
+  /** ISO-8601 UTC timestamp of `save()` (ends in `Z`). */
+  savedAt: string;
+  /** Mochi core version that produced the file. */
+  mochiVersion: string;
+  /** The regex source that filtered the saved set (default `".*"`). */
+  pattern: string;
+  /** Number of cookies in the `cookies` array — redundant with `cookies.length`, kept for trace logs. */
+  count: number;
+  /** Raw `Storage.getCookies` cookies, optionally filtered by `pattern`. */
+  cookies: import("./page").Cookie[];
+}
+
+/** Options shared by `cookies.save` / `cookies.load`. */
+export interface CookieJarOptions {
+  /**
+   * Optional regex matched against each cookie's `domain`. Default `.*`
+   * (everything). Cookies failing the match are skipped on save AND on load
+   * (so a saved-with-everything jar can be partially restored).
+   */
+  pattern?: RegExp;
+}
+
+/**
+ * `Session.cookies` namespace — exposes the read/write/persist surface for the
+ * session's cookie jar. The legacy `Session.cookies(filter)` and
+ * `Session.setCookies(...)` shapes are gone; callers go through this object.
+ *
+ * The whole namespace is bound to a Session instance via the `Session.cookies`
+ * getter — every method routes through `Storage.getCookies` /
+ * `Storage.setCookies` on the root browser target (the only domain that
+ * exposes a global cookie reader without a per-page Network domain).
+ */
+export interface CookieJar {
+  /**
+   * All cookies the browser is aware of, optionally filtered by url. The url
+   * filter is a coarse hostname match (no path / secure / sameSite handling) —
+   * sufficient for "scope down to a session" use cases.
+   */
+  get(filter?: { url?: string }): Promise<import("./page").Cookie[]>;
+  /** Set cookies via the root-target Storage domain. */
+  set(cookies: import("./page").Cookie[]): Promise<void>;
+  /**
+   * Persist cookies to a JSON file at `path`. Cookies whose `domain` does NOT
+   * match `opts.pattern` (default: every domain) are skipped. The file format
+   * is {@link CookieJarFile}.
+   */
+  save(path: string, opts?: CookieJarOptions): Promise<void>;
+  /**
+   * Read a JSON file written by {@link save} and replay every cookie back into
+   * the browser via `Storage.setCookies`. Cookies whose `domain` does NOT
+   * match `opts.pattern` (default: everything) are skipped — useful when one
+   * jar holds multi-domain state but only a slice should be re-installed for
+   * the current run.
+   *
+   * Throws on missing/corrupt files or version mismatch with a diagnostic that
+   * pins the exact failure point.
+   */
+  load(path: string, opts?: CookieJarOptions): Promise<void>;
+}
+
 export class Session {
   /**
    * The resolved Matrix for this session — a relationally-locked snapshot
@@ -163,18 +281,22 @@ export class Session {
   private readonly _payload: PayloadResult | null;
   /**
    * Whether this session bypasses the inject pipeline (no `buildPayload`,
-   * no `Page.addScriptToEvaluateOnNewDocument`, no worker injection).
-   * Set from {@link SessionInit.bypassInject}. PLAN.md §12.1, task 0040.
+   * no body splice via `Fetch.fulfillRequest`, no worker injection). Set
+   * from {@link SessionInit.bypassInject}. PLAN.md §12.1, task 0040.
    *
    * @internal
    */
   private readonly bypassInject: boolean;
   /**
-   * Live handle for the CDP `Fetch.authRequired` subscription. Created
-   * lazily on construction when `init.proxyAuth` is set; disposed on
-   * `Session.close`. Undefined when the session has no proxy auth.
+   * Live handle for the unified `Fetch` domain owner — installs once on
+   * construction and tears down on `Session.close`. Owns BOTH the
+   * Document-body splice (init-script delivery, task 0266) AND the
+   * `Fetch.authRequired` listener for proxy creds. Undefined when neither
+   * inject nor proxy auth is in play (capture-with-no-proxy short-circuit).
+   *
+   * @see PLAN.md §8.4, tasks/0266-fetch-fulfill-init-script.md
    */
-  private proxyAuthHandle: ProxyAuthHandle | undefined;
+  private initInjectorHandle: InitInjectorHandle | undefined;
   /**
    * Snapshot of the `challenges` launch option, retained so
    * {@link newPage} can install the per-page auto-click handler. Undefined
@@ -196,6 +318,13 @@ export class Session {
    * @internal
    */
   private readonly workerExecutionContextIds = new Map<string, number>();
+  /**
+   * The `CookieJar` instance returned by the {@link cookies} getter. Created
+   * once at construction and bound to this Session — every call routes
+   * through `Storage.getCookies` / `Storage.setCookies` on the root browser
+   * target. See {@link CookieJar} for the surface contract.
+   */
+  private readonly cookieJar: CookieJar;
 
   constructor(init: SessionInit) {
     this.proc = init.proc;
@@ -212,26 +341,40 @@ export class Session {
       defaultTimeoutMs: init.defaultTimeoutMs,
     });
     this.router.start();
+    this.cookieJar = createCookieJar(this);
     this.installAutoAttach();
     this.installCrashGuard();
-    // Wire CDP-driven proxy auth only when credentials were supplied. The
-    // no-auth path skips Fetch.enable entirely so we don't pay the
-    // protocol-attach cost or surface any extra CDP traffic.
-    if (init.proxyAuth !== undefined) {
+    // Task 0266: unified Fetch.enable owner — handles both Document-body
+    // splice (init-script delivery via Fetch.fulfillRequest, replacing
+    // Page.addScriptToEvaluateOnNewDocument) AND the proxy-auth handler
+    // when credentials are supplied. Single Fetch.enable per session.
+    //
+    // The injector skips Fetch.enable entirely when both are inactive
+    // (capture flow with no proxy) so we keep the §8.2-clean
+    // "no extra protocol surface" property of the v0.1 baseline for that
+    // narrow case.
+    const payloadCode = this._payload?.code ?? null;
+    const auth = init.proxyAuth;
+    if (payloadCode !== null || auth !== undefined) {
       // Fire-and-forget: surface failures via console.warn but don't reject
-      // the constructor — pages still launch and unauthenticated traffic
-      // will simply 407, giving callers a recoverable signal.
-      void installProxyAuth(this.router, init.proxyAuth)
+      // the constructor. The init-script path means a failure to install
+      // breaks inject delivery (the page still loads with the bare
+      // browser fingerprint), so we log loudly to keep the failure
+      // visible.
+      void installInitInjector(this.router, {
+        payloadCode,
+        ...(auth !== undefined ? { auth } : {}),
+      })
         .then((handle) => {
           if (this.closed) {
             void handle.dispose();
             return;
           }
-          this.proxyAuthHandle = handle;
+          this.initInjectorHandle = handle;
         })
         .catch((err: unknown) => {
           if (!this.closed) {
-            console.warn("[mochi] proxy-auth installation failed:", err);
+            console.warn("[mochi] init-injector installation failed:", err);
           }
         });
     }
@@ -242,12 +385,15 @@ export class Session {
    *   1. `Target.createTarget` opens a new browser tab.
    *   2. `Target.attachToTarget({ flatten: true })` returns a flat-mode session
    *      id we'll use to address page-level CDP methods.
-   *   3. `Page.addScriptToEvaluateOnNewDocument({ source, runImmediately: true,
-   *      worldName: "" })` installs the inject payload to run main-world,
-   *      before any page script, on every navigation. The returned identifier
-   *      is tracked on the {@link Page} so it can be removed on close.
-   *      Critical: `worldName: ""` — any non-empty string creates an isolated
-   *      world (PLAN.md §8.4) which is detectable.
+   *   3. The inject payload is delivered NOT via
+   *      `Page.addScriptToEvaluateOnNewDocument` but via the always-on
+   *      `Fetch` domain handler installed once at session-construction time
+   *      (`installInitInjector`). When this page navigates, the document
+   *      response is intercepted, its CSP rewritten, and the payload
+   *      spliced as an inline `<script>` at end-of-`<head>` before the
+   *      first non-comment `<script>`. See PLAN.md §8.4 / task 0266 for
+   *      the rationale (closes the source-attribution leak that
+   *      `addScriptToEvaluateOnNewDocument` otherwise carries).
    *
    * `flatten: true` is critical — without it, page CDP messages would need to
    * be wrapped in `Target.sendMessageToTarget` envelopes. Flat mode lets us
@@ -333,18 +479,44 @@ export class Session {
         { sessionId: attached.sessionId },
       );
     }
-    // PLAN.md §12.1 / task 0040 — capture flow short-circuits inject so the
-    // browser reports its bare fingerprint. Otherwise install the payload
-    // main-world via §8.4. worldName MUST be the empty string.
+    // Task 0266: the inject payload is delivered via a TWO-MECHANISM strategy:
+    //
+    //   1. Session-level `installInitInjector` (constructor) — listens on
+    //      `Fetch.requestPaused`, splices the wrapped payload into every
+    //      HTTP/HTTPS Document response. This is the load-bearing path for
+    //      real navigations: closes the `addScriptToEvaluateOnNewDocument`
+    //      source-attribution leak.
+    //
+    //   2. Per-page `Page.addScriptToEvaluateOnNewDocument` (this block) —
+    //      registers the SAME wrapped payload as a fallback for URL schemes
+    //      that the Fetch domain does NOT intercept: `about:blank`,
+    //      `data:`, `blob:`. Without this, an `await page.goto("about:blank")`
+    //      followed by an inject-dependent assertion (e.g. `navigator.
+    //      webdriver` patched via R-022) would fail because the inject
+    //      never fired.
+    //
+    // The wrapper sets `__mochi_inject_marker = true` on globalThis and
+    // checks for it at entry, so when both paths fire on the same realm
+    // (a normal HTTP nav has Fetch splice + new-document fire), the second
+    // invocation early-returns before any side effect. PLAN.md §8.4
+    // documents this dual-mechanism design and the trade-off it accepts:
+    // the source-attribution leak is closed for every URL scheme that
+    // matters (HTTP/HTTPS — i.e. every fingerprinter-relevant page) but
+    // remains for transitional URLs (about:blank/data:/blob:) where no
+    // fingerprinter typically reads.
     let injectScriptIdentifier: string | undefined;
     if (!this.bypassInject && this._payload !== null) {
+      const wrapped = wrapSelfRemovingPayload(this._payload.code);
       const installed = await this.router.send<{ identifier: string }>(
         "Page.addScriptToEvaluateOnNewDocument",
         {
-          source: this._payload.code,
+          source: wrapped,
+          // Run before the first script in the document — same timing the
+          // Fetch.fulfillRequest splice achieves on HTTP nav.
           runImmediately: true,
+          // Empty `worldName` MUST be the literal empty string — naming any
+          // world creates a fingerprintable isolated world (PLAN.md §8.4).
           worldName: "",
-          // includeCommandLineAPI defaults to false; we don't set it.
         },
         { sessionId: attached.sessionId },
       );
@@ -394,38 +566,26 @@ export class Session {
   }
 
   /**
-   * All cookies the browser is aware of, optionally filtered by url.
+   * Cookie-jar surface: `get`, `set`, `save`, `load`. See {@link CookieJar}.
+   *
+   * All four methods route through `Storage.getCookies` /
+   * `Storage.setCookies` on the *root* browser target — the only domain that
+   * exposes a global cookie reader/writer without a per-page Network domain.
    *
-   * Uses `Storage.getCookies` on the *root* browser target (the only domain
-   * that exposes a global cookie reader without a per-page Network domain).
+   * The persistence layer (`save`/`load`) is JSON, NOT pickle (per audit:
+   * `docs/audits/nodriver.md` LOW finding 2 — Bun-native code uses JSON).
+   * Format pinned by {@link CookieJarFile}; a small header (`version`,
+   * `savedAt`, `mochiVersion`, `pattern`, `count`) lets a future incompatible
+   * change be detected before any cookie touches the browser.
    */
-  async cookies(filter: { url?: string } = {}): Promise<import("./page").Cookie[]> {
-    this.assertOpen();
-    const result = await this.router.send<{ cookies: import("./page").Cookie[] }>(
-      "Storage.getCookies",
-    );
-    if (filter.url === undefined) return result.cookies;
-    // v0.1 only supports a coarse host-string filter — full URL matching with
-    // path, secure, etc. is out of scope per the brief.
-    let host: string;
-    try {
-      host = new URL(filter.url).hostname;
-    } catch {
-      return [];
-    }
-    return result.cookies.filter((c) => c.domain.endsWith(host) || host.endsWith(c.domain));
-  }
-
-  /** Set cookies via the root-target Storage domain. */
-  async setCookies(cookies: import("./page").Cookie[]): Promise<void> {
-    this.assertOpen();
-    await this.router.send("Storage.setCookies", { cookies });
+  get cookies(): CookieJar {
+    return this.cookieJar;
   }
 
   /** Storage snapshot. v0.1: cookies only. localStorage/sessionStorage are empty placeholders pending phase 0.7. */
   async storage(): Promise<StorageSnapshot> {
     this.assertOpen();
-    const c = await this.cookies();
+    const c = await this.cookieJar.get();
     return { cookies: c, localStorage: {}, sessionStorage: {} };
   }
 
@@ -544,15 +704,16 @@ export class Session {
       }
       this.netCtx = undefined;
     }
-    // Drop the proxy-auth subscription + Fetch.disable BEFORE we tear down
-    // the router so the disable round-trip can still complete.
-    if (this.proxyAuthHandle !== undefined) {
+    // Drop the unified init-injector subscription (and its `Fetch.disable`)
+    // BEFORE we tear down the router so the disable round-trip can still
+    // complete on the live transport.
+    if (this.initInjectorHandle !== undefined) {
       try {
-        await this.proxyAuthHandle.dispose();
+        await this.initInjectorHandle.dispose();
       } catch (err) {
-        console.warn("[mochi] proxy-auth dispose failed:", err);
+        console.warn("[mochi] init-injector dispose failed:", err);
       }
-      this.proxyAuthHandle = undefined;
+      this.initInjectorHandle = undefined;
     }
     await this.router.close();
     await this.proc.close();
@@ -610,6 +771,25 @@ export class Session {
    */
   static readonly VERSION = VERSION;
 
+  /**
+   * Module-private accessor used by {@link createCookieJar}. The cookie-jar
+   * factory lives in module scope (so callers can subclass via the public
+   * {@link CookieJar} interface without touching the Session internals); this
+   * accessor lets the factory reach the router + the open-state guard while
+   * keeping both genuinely private to user code.
+   *
+   * @internal
+   */
+  _internalCookieJarPlumbing(): {
+    router: MessageRouter;
+    assertOpen: () => void;
+  } {
+    return {
+      router: this.router,
+      assertOpen: () => this.assertOpen(),
+    };
+  }
+
   // ---- internals --------------------------------------------------------------
 
   private installAutoAttach(): void {
@@ -687,6 +867,14 @@ export class Session {
         // so the call binds to the worker's own context, not whatever
         // `Runtime.evaluate` happens to resolve. The payload IIFE is wrapped
         // as a function declaration so `callFunctionOn` accepts it.
+        //
+        // Timeout: 5s, not the 30s default. Transient workers (sannysoft,
+        // bot.incolumitas, etc. spawn brief workers that die between attach
+        // and inject) WILL silently disappear; without a per-call cap the
+        // route loop blocks for 30s waiting on a reply that's never coming,
+        // adding 30s × N orphan workers per test run. 5s is plenty for a
+        // real worker (callFunctionOn against a live context returns in
+        // single-digit ms); anything past that, the target is dead.
         await this.router.send(
           "Runtime.callFunctionOn",
           {
@@ -696,11 +884,26 @@ export class Session {
             awaitPromise: false,
             // includeCommandLineAPI must remain false (§8.2).
           },
-          { sessionId: childSessionId },
+          { sessionId: childSessionId, timeoutMs: WORKER_INJECT_TIMEOUT_MS },
         );
       } catch (err: unknown) {
         if (!this.closed) {
-          console.warn(`[mochi] payload inject into worker ${ev.targetInfo.targetId} failed:`, err);
+          // Downgrade to debug for the expected race (worker died before
+          // inject completed). The two error fingerprints are: our own
+          // CdpTimeoutError (router gave up), or CDP's own "Session with
+          // given id not found" / "Target closed" (target detached
+          // mid-roundtrip). Both are routine on real-world pages with
+          // short-lived workers; warning on every one is just noise. A
+          // genuine bug (e.g. the idOnly extraction returning a bad
+          // contextId) is anything else and still warns.
+          if (isTransientWorkerError(err)) {
+            // best-effort: silent. The worker is gone; nothing to do.
+          } else {
+            console.warn(
+              `[mochi] payload inject into worker ${ev.targetInfo.targetId} failed:`,
+              err,
+            );
+          }
         }
       }
     }
@@ -709,13 +912,18 @@ export class Session {
       try {
         await this.router.send("Runtime.runIfWaitingForDebugger", undefined, {
           sessionId: childSessionId,
+          timeoutMs: WORKER_INJECT_TIMEOUT_MS,
         });
       } catch (err: unknown) {
         if (!this.closed) {
-          console.warn(
-            `[mochi] Runtime.runIfWaitingForDebugger on target ${ev.targetInfo.targetId} failed:`,
-            err,
-          );
+          if (isTransientWorkerError(err)) {
+            // best-effort: silent. Same race as the inject path above.
+          } else {
+            console.warn(
+              `[mochi] Runtime.runIfWaitingForDebugger on target ${ev.targetInfo.targetId} failed:`,
+              err,
+            );
+          }
         }
       }
     }
@@ -982,3 +1190,94 @@ export function buildUserAgentMetadata(matrix: MatrixV1): {
     wow64: false,
   };
 }
+
+// ---- cookie-jar factory (task 0257) -----------------------------------------
+
+/**
+ * Build the {@link CookieJar} returned by `Session.cookies`. Bound to one
+ * Session instance via {@link Session._internalCookieJarPlumbing}. Module-
+ * private; the public surface is the interface — instances are only created
+ * by the Session constructor.
+ *
+ * `save`/`load` use Bun's filesystem APIs (`Bun.file`, `Bun.write`) — Bun is
+ * the only supported runtime per PLAN.md I-3 so there's no Node fallback.
+ *
+ * @internal
+ */
+function createCookieJar(session: Session): CookieJar {
+  const { router, assertOpen } = session._internalCookieJarPlumbing();
+  return {
+    async get(filter: { url?: string } = {}) {
+      assertOpen();
+      const result = await router.send<{ cookies: import("./page").Cookie[] }>(
+        "Storage.getCookies",
+      );
+      if (filter.url === undefined) return result.cookies;
+      // Coarse host-string filter — full URL matching with path / secure /
+      // sameSite is out of scope per the brief. Mirrors the pre-0257
+      // behaviour of the legacy `Session.cookies(filter)` method.
+      let host: string;
+      try {
+        host = new URL(filter.url).hostname;
+      } catch {
+        return [];
+      }
+      return result.cookies.filter((c) => c.domain.endsWith(host) || host.endsWith(c.domain));
+    },
+    async set(cookies: import("./page").Cookie[]) {
+      assertOpen();
+      await router.send("Storage.setCookies", { cookies });
+    },
+    async save(path: string, opts: CookieJarOptions = {}) {
+      assertOpen();
+      const pattern = opts.pattern ?? /.*/;
+      const all = await router.send<{ cookies: import("./page").Cookie[] }>("Storage.getCookies");
+      const filtered = all.cookies.filter((c) => pattern.test(c.domain));
+      const file: CookieJarFile = {
+        version: COOKIE_JAR_FORMAT_VERSION,
+        savedAt: new Date().toISOString(),
+        mochiVersion: VERSION,
+        pattern: pattern.source,
+        count: filtered.length,
+        cookies: filtered,
+      };
+      // Pretty-print with 2-space indent: jars are committed by some users
+      // alongside fixtures (per nodriver's `pickle` use case); pretty JSON
+      // diffs cleanly. Negligible size impact for a few-kB cookie set.
+      await Bun.write(path, `${JSON.stringify(file, null, 2)}\n`);
+    },
+    async load(path: string, opts: CookieJarOptions = {}) {
+      assertOpen();
+      const pattern = opts.pattern ?? /.*/;
+      const file = Bun.file(path);
+      const exists = await file.exists();
+      if (!exists) {
+        throw new Error(`[mochi] cookies.load: file not found at ${path}`);
+      }
+      let parsed: unknown;
+      try {
+        const text = await file.text();
+        parsed = JSON.parse(text);
+      } catch (err) {
+        throw new Error(`[mochi] cookies.load: ${path} is not valid JSON: ${String(err)}`);
+      }
+      const jar = parsed as Partial<CookieJarFile>;
+      if (typeof jar !== "object" || jar === null) {
+        throw new Error(`[mochi] cookies.load: ${path} is not a JSON object`);
+      }
+      if (jar.version !== COOKIE_JAR_FORMAT_VERSION) {
+        throw new Error(
+          `[mochi] cookies.load: ${path} version ${String(jar.version)} is not supported (expected ${COOKIE_JAR_FORMAT_VERSION})`,
+        );
+      }
+      if (!Array.isArray(jar.cookies)) {
+        throw new Error(`[mochi] cookies.load: ${path} has no \`cookies\` array`);
+      }
+      // Filter on load too: a single saved-with-everything jar can be sliced
+      // domain-wise without re-saving.
+      const toLoad = jar.cookies.filter((c) => pattern.test(c.domain));
+      if (toLoad.length === 0) return;
+      await router.send("Storage.setCookies", { cookies: toLoad });
+    },
+  };
+}