@mochi.js/core 0.2.2 → 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
@@ -266,42 +412,111 @@ export class Session {
     // (only Runtime.enable is forbidden). We enable here so subsequent
     // addScriptToEvaluateOnNewDocument is honoured by the page domain.
     await this.router.send("Page.enable", undefined, { sessionId: attached.sessionId });
+    // Task 0262: timezone spoof via CDP `Emulation.setTimezoneOverride`.
+    //
+    // Drives BOTH `Intl.DateTimeFormat().resolvedOptions().timeZone` AND
+    // `Date.getTimezoneOffset()` because Chromium's V8 reads from the same
+    // internal timezone source. We do NOT manually rewrite
+    // `Date.prototype.getTimezoneOffset` in inject — that's detectable via
+    // prototype-shape checks. The CDP override is the canonical
+    // mechanism.
+    //
+    // Per the CDP docs (`tot/Emulation/#method-setTimezoneOverride`),
+    // this method does NOT require `Emulation.enable` (it stores override
+    // state directly on the target's `EmulationAgent`). §8.2's bans are
+    // unaffected. Sent per-target before any navigation so the very first
+    // document JS already sees the spoofed zone.
+    //
+    // The empty-string sentinel in the protocol means "clear override";
+    // we never send empty here because that would defeat the purpose.
+    //
+    // Skipped under `bypassInject:true` (PLAN.md §12.1) — capture flows
+    // record the bare browser timezone.
+    if (!this.bypassInject) {
+      await this.router.send(
+        "Emulation.setTimezoneOverride",
+        { timezoneId: this.profile.timezone },
+        { sessionId: attached.sessionId },
+      );
+    }
     // Task 0255: defensive UA override at the network layer.
     //
     // The inject payload (Page.addScriptToEvaluateOnNewDocument) spoofs
-    // `navigator.userAgent` in the JS surface, but `Network.requestWillBeSent`
-    // events (and the request line itself) carry the BARE browser UA — which
-    // under `--headless=new` still contains the substring "HeadlessChrome".
-    // The inject can never reach those bytes because they're emitted before
-    // any document script runs.
+    // `navigator.userAgent` and `navigator.userAgentData` in the JS
+    // surface, but `Network.requestWillBeSent` events (and the request
+    // line itself) carry the BARE browser UA — which under `--headless=new`
+    // still contains the substring "HeadlessChrome" — AND the bare
+    // `Sec-CH-UA*` request-header set. The inject can never reach those
+    // bytes because they're emitted before any document script runs.
+    //
+    // 0255 plumbed `userAgent`. 0261 closes the cross-layer leak that left
+    // open: without `userAgentMetadata`, the request `Sec-CH-UA*` headers
+    // carry CfT defaults instead of the matrix, so a fingerprinter doing
+    // `getHighEntropyValues()` and comparing against the request headers
+    // sees a mismatch (direct PLAN.md I-5 violation). The metadata struct
+    // is the CDP-canonical UA-CH descriptor; Chromium derives every
+    // `Sec-CH-UA*` header from it. Both surfaces (this network call and
+    // the inject's `client-hints.ts` getHighEntropyValues) read the SAME
+    // matrix fields, so they cannot drift.
     //
     // `Network.setUserAgentOverride` is a per-target setter that does NOT
     // require `Network.enable` (it only stores override state); §8.2's ban
-    // on `Network.enable` is therefore unaffected. Sent immediately after
-    // attach and before any navigation so the very first request the page
-    // issues already carries the matrix UA.
+    // on `Network.enable` is therefore unaffected, with or without the
+    // metadata payload. Sent immediately after attach and before any
+    // navigation so the very first request the page issues already carries
+    // the matrix UA + UA-CH headers.
     //
     // Skipped under `bypassInject:true` (PLAN.md §12.1) — capture flows must
-    // record the bare browser fingerprint, including its raw UA.
+    // record the bare browser fingerprint, including its raw UA AND raw
+    // `Sec-CH-UA*` headers.
     if (!this.bypassInject) {
       await this.router.send(
         "Network.setUserAgentOverride",
-        { userAgent: this.profile.userAgent },
+        {
+          userAgent: this.profile.userAgent,
+          userAgentMetadata: buildUserAgentMetadata(this.profile),
+        },
         { 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 },
       );
@@ -351,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}.
    *
-   * Uses `Storage.getCookies` on the *root* browser target (the only domain
-   * that exposes a global cookie reader without a per-page Network domain).
+   * 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.
+   *
+   * 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: {} };
   }
 
@@ -501,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();
@@ -567,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 {
@@ -644,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",
           {
@@ -653,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,
+            );
+          }
         }
       }
     }
@@ -666,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,
+            );
+          }
         }
       }
     }
@@ -764,3 +1015,269 @@ export class Session {
     }
   }
 }
+
+// ---- UA-CH metadata helpers (task 0261) -------------------------------------
+
+/**
+ * Single brand entry as accepted by `Network.setUserAgentOverride`'s
+ * `userAgentMetadata.brands` / `fullVersionList`.
+ *
+ * @internal
+ */
+interface UaMetadataBrand {
+  brand: string;
+  version: string;
+}
+
+/**
+ * Strip surrounding ASCII double-quotes (the on-the-wire form for several
+ * `Sec-CH-UA*` headers — `'"macOS"'`, `'"14.0.0"'`, `'"arm"'`, `'"64"'`).
+ * The CDP `userAgentMetadata` enums consume the unquoted form.
+ */
+function unquoteUaCh(s: string): string {
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+/**
+ * Parse a Sec-CH-UA-style header value
+ * (`'"Brand A";v="123", "Not.A/Brand";v="8", "Brand B";v="456"'`) into the
+ * `[{brand, version}, ...]` shape `userAgentMetadata.brands` expects.
+ *
+ * Hand-written state machine — Sec-CH-UA is RFC 8941 Structured Headers
+ * with quoted strings, so a regex split on `,` would break on
+ * `"Brand,with,commas"`. Mirrors `parseSecChUa` in
+ * `@mochi.js/inject/src/modules/client-hints.ts` byte-for-byte: same
+ * source field (`matrix.uaCh["sec-ch-ua"]`), same output shape, so the
+ * network surface and the JS surface cannot drift.
+ *
+ * @internal
+ */
+function parseSecChUaBrandList(s: string): UaMetadataBrand[] {
+  const out: UaMetadataBrand[] = [];
+  // Split on `,` outside quoted segments. `depth` toggles inside `"…"`.
+  const parts: string[] = [];
+  let depth = 0;
+  let cur = "";
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i] as string;
+    if (c === '"') {
+      depth = depth === 0 ? 1 : 0;
+      cur += c;
+    } else if (c === "," && depth === 0) {
+      parts.push(cur);
+      cur = "";
+    } else {
+      cur += c;
+    }
+  }
+  if (cur.length > 0) parts.push(cur);
+  for (const raw of parts) {
+    const piece = raw.trim();
+    if (piece.length === 0) continue;
+    const semi = piece.indexOf(";");
+    if (semi === -1) {
+      out.push({ brand: unquoteUaCh(piece), version: "" });
+      continue;
+    }
+    const brandPart = piece.slice(0, semi).trim();
+    const rest = piece.slice(semi + 1).trim();
+    let version = "";
+    if (rest.startsWith("v=")) {
+      version = unquoteUaCh(rest.slice(2).trim());
+    }
+    out.push({ brand: unquoteUaCh(brandPart), version });
+  }
+  return out;
+}
+
+/**
+ * Parse the JSON-encoded `uaCh.ua-full-version-list` (R-031) into the
+ * `[{brand, version}]` shape. Falls through to the brand-list parser if
+ * the matrix doesn't carry the field — every shipped profile does, so
+ * the fallback is purely defensive.
+ *
+ * @internal
+ */
+function parseFullVersionList(matrix: MatrixV1): UaMetadataBrand[] {
+  const raw = matrix.uaCh["ua-full-version-list"];
+  if (typeof raw === "string" && raw.length > 0) {
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (Array.isArray(parsed)) {
+        return parsed
+          .filter(
+            (e): e is UaMetadataBrand =>
+              typeof e === "object" &&
+              e !== null &&
+              typeof (e as { brand?: unknown }).brand === "string" &&
+              typeof (e as { version?: unknown }).version === "string",
+          )
+          .map((e) => ({ brand: e.brand, version: e.version }));
+      }
+    } catch {
+      // Fall through.
+    }
+  }
+  // Fallback: reuse the brand-list majors. Matches the inject side's same
+  // fallback in client-hints.ts.
+  const secChUa = matrix.uaCh["sec-ch-ua"] ?? "";
+  return parseSecChUaBrandList(secChUa);
+}
+
+/**
+ * Build the `userAgentMetadata` parameter for `Network.setUserAgentOverride`
+ * from a derived MatrixV1. Single source of truth = the matrix; the inject
+ * `client-hints.ts` module reads the same fields, so the JS-API surface
+ * (`navigator.userAgentData.getHighEntropyValues`) and the request-header
+ * surface (`Sec-CH-UA*`) cannot drift.
+ *
+ * Field shape per CDP spec:
+ *   - `brands`             — `[{brand, version}]`, brand-list majors.
+ *   - `fullVersionList`    — `[{brand, version}]`, tip-locked full versions.
+ *   - `fullVersion`        — string, branded entry's version (R-046).
+ *   - `platform`           — unquoted Sec-CH-UA-Platform value.
+ *   - `platformVersion`    — unquoted Sec-CH-UA-Platform-Version.
+ *   - `architecture`       — `"arm" | "x86" | ""` (R-042 unquoted).
+ *   - `model`              — free-form string, empty for desktop (R-045).
+ *   - `mobile`             — boolean (R-044 → `?1` mapped to true).
+ *   - `bitness`            — STRING `"64" | "32" | ""` (R-043 unquoted),
+ *                            never numeric.
+ *   - `wow64`              — boolean; matrix doesn't model nested-WOW64,
+ *                            we always emit false (task 0261 out-of-scope).
+ *
+ * @internal
+ */
+export function buildUserAgentMetadata(matrix: MatrixV1): {
+  brands: UaMetadataBrand[];
+  fullVersionList: UaMetadataBrand[];
+  fullVersion: string;
+  platform: string;
+  platformVersion: string;
+  architecture: string;
+  model: string;
+  mobile: boolean;
+  bitness: string;
+  wow64: boolean;
+} {
+  const ua = matrix.uaCh;
+  const brandsRaw = ua["sec-ch-ua"] ?? "";
+  const brands = parseSecChUaBrandList(brandsRaw);
+  const fullVersionList = parseFullVersionList(matrix);
+  const fullVersion =
+    typeof ua["ua-full-version"] === "string" && ua["ua-full-version"].length > 0
+      ? ua["ua-full-version"]
+      : (fullVersionList[0]?.version ?? "");
+  const platform = unquoteUaCh(ua["sec-ch-ua-platform"] ?? "");
+  const platformVersion = unquoteUaCh(ua["sec-ch-ua-platform-version"] ?? "");
+  const architecture = unquoteUaCh(ua["sec-ch-ua-arch"] ?? "");
+  const bitness = unquoteUaCh(ua["sec-ch-ua-bitness"] ?? "");
+  const model = unquoteUaCh(ua["sec-ch-ua-model"] ?? "");
+  // Sec-CH-UA-Mobile wire form is "?0" / "?1" (Structured-Headers boolean).
+  const mobile = ua["sec-ch-ua-mobile"] === "?1";
+  return {
+    brands,
+    fullVersionList,
+    fullVersion,
+    platform,
+    platformVersion,
+    architecture,
+    model,
+    mobile,
+    bitness,
+    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 });
+    },
+  };
+}