@mochi.js/core 0.6.0 → 0.8.1

package/src/launch.ts

@@ -11,6 +11,7 @@
  */
 
 import { deriveMatrix, type ProfileV1 } from "@mochi.js/consistency";
+import { getProfile, ProfileBaselineMissingError, UnknownProfileIdError } from "@mochi.js/profiles";
 import { resolveBinary } from "./binary";
 import { defaultProfileForHost, unsupportedHostMessage } from "./default-profile";
 import { type GeoConsistencyMode, reconcileGeoConsistency } from "./geo-consistency";
@@ -92,7 +93,7 @@ export interface LaunchOptions {
    * string (looked up against `KNOWN_PROFILE_IDS`) or an inline `ProfileV1`
    * object.
    *
-   * **Optional since task 0272** — when omitted, mochi auto-picks the
+   * **Optional** — when omitted, mochi auto-picks the
    * profile whose declared OS matches the host's `process.platform` /
    * `process.arch` pair via {@link defaultProfileForHost}:
    *
@@ -120,7 +121,7 @@ export interface LaunchOptions {
    * `false` (default in v0.1) runs headful. New code should prefer
    * {@link headlessMode}, which is more expressive AND env-aware.
    *
-   * Resolution priority (task 0258):
+   * Resolution priority:
    *
    *   1. `headlessMode` if set.
    *   2. Else `headless: true → "new"`, `headless: false → "off"`.
@@ -130,7 +131,7 @@ export interface LaunchOptions {
    */
   headless?: boolean;
   /**
-   * Headless dispatch mode (task 0258). One of:
+   * Headless dispatch mode. One of:
    *
    *   - `"new"`    — modern Chromium headless (`--headless=new`). Full
    *                  rendering, near-byte-identical to headful for
@@ -178,7 +179,7 @@ export interface LaunchOptions {
    * trivially fingerprinted as Chromium-for-Testing.
    *
    * Defaults to `false`. PLAN.md §12.1 (capture must run against bare
-   * Chromium); task 0040.
+   * Chromium);
    */
   bypassInject?: boolean;
   /**
@@ -199,7 +200,7 @@ export interface LaunchOptions {
    *
    * Pairs with — but is independent of — {@link bypassInject}. Capture
    * flows set both `true`; harness conformance runs set `hermetic: true`
-   * with full inject pipeline active. PLAN.md §8.6 + task 0256.
+   * with full inject pipeline active. PLAN.md §8.6 +
    */
   hermetic?: boolean;
   /**
@@ -235,13 +236,13 @@ export interface LaunchOptions {
    * - `"off"` — skip the probe entirely. Use in offline tests / when
    *   the probe service is rate-limited.
    *
-   * The probe is a single GET through wreq (using the matrix's
-   * `wreqPreset`, so the geo service sees the same JA4/headers as user
-   * traffic). 4-attempt cap, 2s per endpoint. Probe results are NOT
-   * cached across sessions — proxy IPs rotate.
+   * The probe is a single GET through Chromium itself (Session.fetch via
+   * CDP `Network.loadNetworkResource`), so the geo service sees the same
+   * JA4 / headers as user traffic by definition. 4-attempt cap, 2s per
+   * endpoint. Probe results are NOT cached across sessions — proxy IPs
+   * rotate.
    *
    * @see PLAN.md §9 (relational consistency, IP/TZ/Locale axis)
-   * @see tasks/0262-ip-tz-locale-exit-consistency.md
    */
   geoConsistency?: GeoConsistencyMode;
 }
@@ -255,27 +256,29 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
   const normalized = normalizeProxy(opts.proxy);
 
   // Resolve the `MatrixV1` BEFORE spawning so matrix-derived values flow
-  // into both the `--lang` flag (task 0251) and `--window-size` flag
-  // (task 0252). The matrix is otherwise read post-spawn for inject;
+  // into both the `--lang` flag and `--window-size` flag
+  //. The matrix is otherwise read post-spawn for inject;
   // deriving early is cheap (~µs, pure function) and lets us close the
   // I-5 leaks between Chromium's native network/OS-window state and the
   // JS-layer spoof.
   //
   // Inline `ProfileV1` objects flow straight through; string profile ids
-  // are resolved against a placeholder profile until `@mochi.js/profiles`
-  // ships its first capture (phase 0.4). The matrix is bit-stable per
-  // `(profile, seed)` excluding the `derivedAt` timestamp.
+  // resolve to the captured `data/<id>/profile.json` baseline shipped by
+  // `@mochi.js/profiles`. When the catalog declares an id but no captured
+  // baseline ships yet (e.g. `mac-m2-chrome-stable`), we fall back to a
+  // synthesized placeholder so the launch still succeeds. The matrix is
+  // bit-stable per `(profile, seed)` excluding the `derivedAt` timestamp.
   //
   // Task 0272 — when `profile` is omitted, auto-pick the host-OS-matching
   // profile id. Throws with a precise diagnostic if the host is one of the
   // unsupported ones (FreeBSD, Linux arm64 today, Windows arm64, Alpine
   // musl). Explicit `profile:` always wins; the auto-pick never overrides.
-  const profileSource = resolveProfileSource(opts.profile);
+  const profileSource = await resolveProfileSource(opts.profile);
   const matrix = deriveMatrix(profileSource.profile, opts.seed);
   if (profileSource.autoPicked) {
     // One info-level log line so users can see what mochi inferred without
     // calling `defaultProfileForHost()` themselves. Wording is pinned by
-    // task 0272 — keep stable so docs + LLM-context blocks stay correct.
+    // — keep stable so docs + LLM-context blocks stay correct.
     // (Routed through `console.warn` to match the existing diagnostic
     // channel for `geoConsistency` / Linux-server inference; `console.info`
     // is gated by the workspace lint config — `noConsole` only allows
@@ -289,9 +292,10 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
 
   // Task 0262 — exit-IP / TZ / locale reconciliation.
   //
-  // Probe the apparent exit IP through the configured proxy (using wreq
-  // with the matrix's `wreqPreset` so the geo service sees the same JA4
-  // / headers as user traffic). Then cross-reference against
+  // Probe the apparent exit IP through the configured proxy. Post-0.7
+  // the probe runs through Chromium itself (Session.fetch via CDP
+  // `Network.loadNetworkResource`), so the geo service sees the same
+  // JA4 / headers as user traffic by definition. Cross-reference against
   // `(matrix.timezone, matrix.locale)` and apply `geoConsistency`. The
   // adjusted matrix flows into BOTH `spawnChromium` (so `--lang` reflects
   // any override) AND `Session` (so inject + the CDP `Emulation.set
@@ -303,7 +307,7 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
   let adjustedMatrix = matrix;
   if (geoMode !== "off") {
     const geo = await probeExitGeo({
-      ...(normalized?.netProxy !== undefined ? { proxy: normalized.netProxy } : {}),
+      ...(normalized?.proxy !== undefined ? { proxy: normalized.proxy } : {}),
       matrix,
     });
     // Strict mode throws GeoMismatchError on real mismatch; let it
@@ -359,13 +363,13 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
     // multi-locale list still flows through `matrix.languages` to the
     // inject layer's `navigator.languages` spoof; Chromium derives the
     // q-weighted `Accept-Language` value from the single `--lang` primary
-    // automatically. Task 0251.
+    // automatically.
     locale: adjustedMatrix.locale,
     // Pin OS-level outer window from the matrix's display geometry so
     // `window.outerWidth/outerHeight` (which reads from the OS window,
     // NOT the JS-spoofed `screen.*`) matches the spoof. Closes the
     // `fingerprint-scan.com` 800×600 leak under `--headless=new`.
-    // UDC fixes the same issue at `__init__.py:410-411`. Task 0252.
+    // UDC fixes the same issue at `__init__.py:410-411`.
     //
     // (`adjustedMatrix.display` === `matrix.display` since geo reconcile
     // only touches timezone/locale/languages — but we use the adjusted
@@ -395,10 +399,11 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
     seed: opts.seed,
     ...(opts.timeout !== undefined ? { defaultTimeoutMs: opts.timeout } : {}),
     ...(opts.bypassInject === true ? { bypassInject: true } : {}),
-    // Forward the same proxy (with auth, if any) to the net FFI so
-    // out-of-band Session.fetch traffic shares the apparent egress.
-    // `@mochi.js/net` (wreq) accepts the full `user:pass@host` URL form.
-    ...(normalized !== undefined ? { netProxy: normalized.netProxy } : {}),
+    // Proxy auth is the only piece that needs explicit Session-side
+    // wiring (the `--proxy-server` flag is already on Chromium's command
+    // line above). Out-of-band `Session.fetch` traffic rides Chromium's
+    // network stack post-0.7, so it inherits the `--proxy-server` egress
+    // automatically — no per-call proxy URL needed.
     ...(normalized?.auth !== undefined ? { proxyAuth: normalized.auth } : {}),
     ...(opts.challenges !== undefined ? { challenges: opts.challenges } : {}),
   });
@@ -417,16 +422,15 @@ export const mochi = {
    * Inspect what mochi would infer about the current process environment for
    * Linux-server detection (drives `headlessMode` defaulting). Pure read of
    * `process.platform`, `process.env.DISPLAY`, `process.env.WAYLAND_DISPLAY`,
-   * `process.getuid?.()`, and the container probe paths. Task 0258.
+   * `process.getuid?.()`, and the container probe paths.
    */
   detectLinuxServerEnv: probeLinuxServerEnv,
   /**
    * Inspect which profile id `mochi.launch` would auto-pick on the current
    * host when `profile` is omitted. Pure read of `process.platform` /
    * `process.arch`. Returns `null` on unsupported hosts — the launcher
-   * throws on that path with a list of explicit profile IDs. Task 0272.
+   * throws on that path with a list of explicit profile IDs.
    *
-   * @see tasks/0271-the-linux-os-thesis.md — the strategic thesis
    * @see https://mochijs.com/docs/concepts/stealth-philosophy
    */
   defaultProfileForHost,
@@ -463,9 +467,10 @@ export function resolveHeadlessMode(
  * Reconcile the two `LaunchOptions.proxy` shapes (URL string and
  * `ProxyConfig` record) into a single normalized record carrying:
  *   - `server`: auth-stripped URL safe to feed `--proxy-server=`.
- *   - `netProxy`: the URL handed to the network FFI. Preserves credentials
- *     (wreq accepts `user:pass@host` inline) so out-of-band fetches
- *     authenticate against the same proxy.
+ *   - `proxy`: the auth-stripped URL forwarded to the geo-probe so it
+ *     can record the egress on diagnostics. (Kept for API parity even
+ *     though the probe now rides Session.fetch + Chromium's network
+ *     stack — i.e. picks up `--proxy-server` automatically.)
  *   - `auth`: parsed credentials for the CDP auth handler. Undefined when
  *     no creds were supplied.
  *
@@ -474,7 +479,7 @@ export function resolveHeadlessMode(
 function normalizeProxy(p: LaunchOptions["proxy"]):
   | {
       server: string;
-      netProxy: string;
+      proxy: string;
       auth?: { username: string; password: string };
     }
   | undefined {
@@ -484,7 +489,7 @@ function normalizeProxy(p: LaunchOptions["proxy"]):
     const parsed = parseProxyUrl(p);
     return {
       server: parsed.server,
-      netProxy: p,
+      proxy: parsed.server,
       ...(parsed.auth !== undefined ? { auth: parsed.auth } : {}),
     };
   }
@@ -493,31 +498,13 @@ function normalizeProxy(p: LaunchOptions["proxy"]):
   const parsed = parseProxyUrl(p.server);
   const auth =
     p.username !== undefined ? { username: p.username, password: p.password ?? "" } : parsed.auth;
-  // Reconstruct the netProxy URL preserving any explicit auth (wreq path).
-  const netProxy = auth !== undefined ? injectAuth(parsed.server, auth) : parsed.server;
   return {
     server: parsed.server,
-    netProxy,
+    proxy: parsed.server,
     ...(auth !== undefined ? { auth } : {}),
   };
 }
 
-/**
- * Inject `username:password@` into a server URL, percent-encoding both
- * components so reserved characters round-trip cleanly through wreq's URL
- * parser.
- */
-function injectAuth(server: string, auth: { username: string; password: string }): string {
-  const u = encodeURIComponent(auth.username);
-  const p = encodeURIComponent(auth.password);
-  // server is `<protocol>://<host>:<port>` (per parseProxyUrl).
-  const idx = server.indexOf("://");
-  if (idx < 0) return server;
-  const head = server.slice(0, idx + 3);
-  const tail = server.slice(idx + 3);
-  return `${head}${u}:${p}@${tail}`;
-}
-
 /**
  * Resolve `LaunchOptions.profile` into a concrete `ProfileV1` plus the
  * meta-flag the launcher needs to decide whether to log the auto-pick
@@ -525,55 +512,112 @@ function injectAuth(server: string, auth: { username: string; password: string }
  *
  *   1. Explicit `ProfileV1` object — flows through unchanged. `autoPicked`
  *      false; `id` taken from the inline object.
- *   2. Explicit `ProfileId` string — same placeholder synthesis as before.
- *      `autoPicked` false.
+ *   2. Explicit `ProfileId` string — load the captured baseline from
+ *      `@mochi.js/profiles`. If the id is known to the catalog but no
+ *      captured baseline ships, fall back to a placeholder synthesis so
+ *      the launch still succeeds (and the consistency engine still locks
+ *      a relationally-consistent Matrix from the skeleton). Unknown ids
+ *      propagate as a hard error. `autoPicked` false.
  *   3. `undefined` — task 0272: call `defaultProfileForHost()`. Throw with
  *      the unsupported-host diagnostic when the resolver returns `null`.
- *      `autoPicked` true.
+ *      `autoPicked` true; same captured-vs-placeholder fallback as branch
+ *      2.
  *
- * Pure function — does not log. The launcher emits the INFO line itself
- * after observing `autoPicked === true` so test fixtures can assert the
- * resolution without intercepting `console`.
+ * Async because `getProfile` reads `data/<id>/profile.json` from disk via
+ * `Bun.file().json()`. The launcher does not log here — the INFO line for
+ * `autoPicked === true` is emitted at the call-site so test fixtures can
+ * assert the resolution without intercepting `console`.
  */
-function resolveProfileSource(profile: ProfileId | ProfileV1 | undefined): {
+async function resolveProfileSource(profile: ProfileId | ProfileV1 | undefined): Promise<{
   profile: ProfileV1;
   id: ProfileId;
   autoPicked: boolean;
-} {
+}> {
   if (typeof profile === "object") {
     return { profile, id: profile.id, autoPicked: false };
   }
   if (typeof profile === "string") {
     return {
-      profile: synthesizePlaceholderProfile(profile),
+      profile: await loadProfileWithFallback(profile),
       id: profile,
       autoPicked: false,
     };
   }
-  // Auto-pick branch — task 0272.
+  // Auto-pick branch —
   const picked = defaultProfileForHost();
   if (picked === null) {
     throw new Error(unsupportedHostMessage(process.platform, process.arch));
   }
   return {
-    profile: synthesizePlaceholderProfile(picked),
+    profile: await loadProfileWithFallback(picked),
     id: picked,
     autoPicked: true,
   };
 }
 
 /**
- * Synthesize a generic placeholder `ProfileV1` from a profile id. Until
- * `@mochi.js/profiles.getProfile` lands (phase 0.4), the consistency engine
- * still produces a real, relationally-locked Matrix from this skeleton —
- * the id is what flows into `sha256(profile.id + seed)`.
+ * Load a `ProfileV1` for `id` from `@mochi.js/profiles` if a captured
+ * baseline ships, otherwise synthesize a placeholder. Unknown ids also fall
+ * back to the placeholder (with a console.warn) — preserving the
+ * pre-getProfile() contract that any string id produces a working session.
+ * E2E test fixtures rely on synthetic ids like "test-humanize".
+ *
+ * Critical correctness path: the captured baselines pin tip-of-stable Chrome
+ * majors (147+ as of 2026-05). The pre-fix code path called
+ * `synthesizePlaceholderProfile` for every string id, which hardcoded
+ * Chrome 131 and produced a UA mismatch with the actual Chromium-for-Testing
+ * binary.
+ */
+async function loadProfileWithFallback(id: ProfileId): Promise<ProfileV1> {
+  try {
+    // `ProfileId` here is the loose `string` alias the launcher accepts
+    // (see comment near the type definition). `getProfile` narrows it
+    // back to the catalog union at runtime and throws
+    // `UnknownProfileIdError` for ids outside the catalog.
+    return await getProfile(id as Parameters<typeof getProfile>[0]);
+  } catch (err) {
+    if (err instanceof ProfileBaselineMissingError) {
+      // Known catalog entry, no baseline shipped yet — fall back to the
+      // synthesized placeholder so the launch still succeeds.
+      return synthesizePlaceholderProfile(id);
+    }
+    if (err instanceof UnknownProfileIdError) {
+      // Caller passed an id that isn't in `KNOWN_PROFILE_IDS`. Surface a
+      // warning so typos are visible, but fall back to the placeholder so
+      // synthetic test-fixture ids (e.g. "test-humanize") keep working.
+      // biome-ignore lint/suspicious/noConsole: dev-facing diagnostic
+      console.warn(
+        `[mochi] profile id "${id}" is not in @mochi.js/profiles.KNOWN_PROFILE_IDS; ` +
+          "falling back to a synthesized placeholder. Pass a ProfileV1 object directly " +
+          "or use one of the catalog ids to silence this warning.",
+      );
+      return synthesizePlaceholderProfile(id);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Synthesize a generic placeholder `ProfileV1` from a profile id, used as
+ * a fallback when the catalog declares an id but no captured baseline
+ * ships in `@mochi.js/profiles` yet. The consistency engine still produces
+ * a real, relationally-locked Matrix from this skeleton — the id is what
+ * flows into `sha256(profile.id + seed)`.
+ *
+ * The major version pinned here MUST track the live Chromium-for-Testing
+ * pin (`packages/cli/src/browsers/manifest.ts:PINNED_FALLBACK_VERSION`)
+ * and the tip entry in
+ * `packages/consistency/src/rules/lookups/browser.ts:BROWSER_TIP_FULL_VERSION`.
+ * A drift between these surfaces ships a UA whose major doesn't match the
+ * installed binary — the canonical fingerprint-mismatch bug R-004 was
+ * meant to prevent. Bump all three together.
  */
 function synthesizePlaceholderProfile(profile: ProfileId): ProfileV1 {
   return {
     id: profile,
     version: "0.0.0-placeholder",
     engine: "chromium",
-    browser: { name: "chrome", channel: "stable", minVersion: "131", maxVersion: "133" },
+    browser: { name: "chrome", channel: "stable", minVersion: "148", maxVersion: "148" },
     os: { name: "linux", version: "22", arch: "x64" },
     device: {
       vendor: "generic",
@@ -598,9 +642,13 @@ function synthesizePlaceholderProfile(profile: ProfileId): ProfileV1 {
     locale: "en-US",
     languages: ["en-US", "en"],
     behavior: { hand: "right", tremor: 0.18, wpm: 60, scrollStyle: "smooth" },
-    wreqPreset: "chrome_131_linux",
+    // `wreqPreset` is required by the ProfileV1 schema for one release of
+    // back-compat (see `schemas/profile.schema.json`). The runtime no
+    // longer reads it — `Session.fetch` rides Chromium's network stack via
+    // CDP, so JA4 is real Chrome by definition. Drops in 0.8.
+    wreqPreset: "chrome_148_linux",
     userAgent:
-      "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+      "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36",
     uaCh: {},
     entropyBudget: { fixed: [], perSeed: [] },
   };

package/src/page/element-handle.ts

@@ -17,7 +17,6 @@
  * which is fine for a v0.2 surface.
  *
  * @see PLAN.md §8.2 / §8.3
- * @see tasks/0253-closed-shadow-piercing-locator.md
  */
 
 import type { MessageRouter } from "../cdp/router";

package/src/page/piercing.ts

@@ -33,7 +33,6 @@
  * brief — a per-page cache layer is a v0.3+ concern).
  *
  * @see PLAN.md §8.2 — `DOM.getDocument` / `DOM.resolveNode` are not forbidden
- * @see tasks/0253-closed-shadow-piercing-locator.md
  */
 
 import type { PierceDomNode } from "../cdp/types";

package/src/page/selector.ts

@@ -31,7 +31,6 @@
  * Throws `SelectorParseError` on syntactically invalid input. The matcher
  * itself never throws — unsupported nodes just don't match.
  *
- * @see tasks/0253-closed-shadow-piercing-locator.md
  * @see PLAN.md §8.2 (forbidden CDP — neither `DOM.getDocument` nor
  *   `DOM.resolveNode` is forbidden; both fine).
  */

package/src/page.ts

@@ -202,7 +202,7 @@ export interface ScreenshotOptions {
   encoding?: "binary" | "base64";
 }
 
-// ---- DX cluster: DOM storage + permissions (task 0257) ---------------------
+// ---- DX cluster: DOM storage + permissions ---------------------
 
 /**
  * Options for {@link Page.localStorage} / {@link Page.sessionStorage}
@@ -252,43 +252,61 @@ export interface DomStorage {
 /**
  * Every browser-level permission descriptor `Browser.grantPermissions` accepts.
  *
- * Pinned to the CDP `Browser.PermissionType` enum on Chromium ≥ 131 (the
- * mochi profile floor — same baseline the worker idOnly bootstrap relies on).
- * The list is verbose-on-purpose: we want a contract test to catch the day
- * Chromium adds a new permission so we can decide whether to forward it.
+ * Pinned to the CDP `Browser.PermissionType` enum on Chromium 148 (the
+ * post-0.7 profile floor — verified `2026-05-09` against the live CDP
+ * reference). The list is verbose-on-purpose: we want a contract test
+ * to catch the day Chromium adds a new permission so we can decide
+ * whether to forward it.
+ *
+ * Drift history:
+ *   - 0.7: removed `accessibilityEvents`, `captureHandle`, `flash`,
+ *     `videoCapturePanTiltZoom` (gone or renamed in 148). Added the XR
+ *     cluster (`ar`, `vr`, `handTracking`), `automaticFullscreen`,
+ *     `cameraPanTiltZoom`, `capturedSurfaceControl`, `keyboardLock`,
+ *     `pointerLock`, `localNetwork`, `localNetworkAccess`,
+ *     `loopbackNetwork`, `smartCard`, `webPrinting`.
  *
  * @see https://chromedevtools.github.io/devtools-protocol/tot/Browser/#type-PermissionType
  */
 export const ALL_BROWSER_PERMISSIONS = [
-  "accessibilityEvents",
+  "ar",
   "audioCapture",
-  "backgroundSync",
+  "automaticFullscreen",
   "backgroundFetch",
-  "captureHandle",
+  "backgroundSync",
+  "cameraPanTiltZoom",
+  "capturedSurfaceControl",
   "clipboardReadWrite",
   "clipboardSanitizedWrite",
   "displayCapture",
   "durableStorage",
-  "flash",
   "geolocation",
+  "handTracking",
   "idleDetection",
+  "keyboardLock",
   "localFonts",
+  "localNetwork",
+  "localNetworkAccess",
+  "loopbackNetwork",
   "midi",
   "midiSysex",
   "nfc",
   "notifications",
   "paymentHandler",
   "periodicBackgroundSync",
+  "pointerLock",
   "protectedMediaIdentifier",
   "sensors",
-  "storageAccess",
+  "smartCard",
   "speakerSelection",
+  "storageAccess",
   "topLevelStorageAccess",
   "videoCapture",
-  "videoCapturePanTiltZoom",
+  "vr",
   "wakeLockScreen",
   "wakeLockSystem",
   "webAppInstallation",
+  "webPrinting",
   "windowManagement",
 ] as const;
 
@@ -1030,13 +1048,12 @@ export class Page {
    * Supported selectors (see `selector.ts`): tag / id / class / attribute /
    * descendant combinator / comma-separated lists. **Not** supported:
    * `>`/`+`/`~` combinators, `:pseudo-classes`, `::pseudo-elements`, XPath.
-   * XPath is a stretch goal per task 0253 brief — TODO if a future surface
+   * XPath is a stretch goal — TODO if a future surface
    * needs it (Turnstile detection only needs CSS).
    *
    * Performance: O(N) in DOM size per call. Acceptable for v0.2; a per-page
    * cache layer is a v0.3+ concern (also called out in 0253).
    *
-   * @see tasks/0253-closed-shadow-piercing-locator.md
    * @see PLAN.md §8.2 (`DOM.getDocument` and `DOM.resolveNode` are not on the
    *   forbidden list — both fine to use here).
    */
@@ -1480,7 +1497,7 @@ function hash01(s: string): number {
   return (h >>> 0) / 0x1_0000_0000;
 }
 
-// ---- DOM storage factory (task 0257) ----------------------------------------
+// ---- DOM storage factory ----------------------------------------
 
 /**
  * Build the {@link DomStorage} returned by `Page.localStorage` /

package/src/proc.ts

@@ -15,7 +15,7 @@ import type { PipeReader, PipeWriter } from "./cdp/transport";
 /**
  * The chromium flags PLAN.md §8.6 mandates we always pass in PRODUCTION
  * (non-hermetic) mode. Trimmed against patchright's
- * `chromiumSwitchesPatch.ts:20-34` removal list (task 0256): every flag
+ * `chromiumSwitchesPatch.ts:20-34` removal list: every flag
  * here passes two tests — (a) it isn't a passive command-line bot-tell that
  * patchright explicitly drops, AND (b) we have a concrete production reason
  * to keep it (CDP transport, UI suppression that matters in headed mode,
@@ -181,7 +181,7 @@ export interface SpawnConfig {
    * integers; otherwise the flag is omitted. Sourced from
    * `matrix.display.{width,height}` by `launch.ts` — the matrix is canonical.
    *
-   * @see UDC `__init__.py:410-411`, UDC issue #2242, task 0252.
+   * @see UDC `__init__.py:410-411`, UDC issue #2242,
    */
   windowSize?: { width: number; height: number };
   /**
@@ -418,7 +418,7 @@ export function buildChromiumArgs(
   }
   // Headless dispatch.
   //
-  // `headlessMode` (task 0258) supersedes the legacy `headless: boolean` knob
+  // `headlessMode` supersedes the legacy `headless: boolean` knob
   // when both are set. When `headlessMode` is unset, fall back to the v0.1
   // mapping (`headless: true → "new"`, `false → "off"`). The launcher in
   // `launch.ts` is responsible for the env-aware default ("new" on Linux
@@ -445,7 +445,7 @@ export function buildChromiumArgs(
   // header so the network surface matches the JS-layer `navigator.language`
   // spoof (PLAN.md I-5). Pushed BEFORE `extraArgs` so a user-supplied
   // override in `args` can win on the command line if absolutely needed —
-  // Chromium honors the last-occurrence on the line for `--lang`. Task 0251.
+  // Chromium honors the last-occurrence on the line for `--lang`.
   if (cfg.locale !== undefined && cfg.locale.length > 0) {
     args.push(`--lang=${cfg.locale}`);
   }
@@ -454,7 +454,7 @@ export function buildChromiumArgs(
   // Chromium's headless 800×600 default. The matrix is canonical: when
   // `display.{width,height}` is missing or non-finite we omit the flag
   // rather than fall back to a hardcoded value (a hardcoded value would
-  // mismatch a profile that legitimately uses different dimensions). Task 0252.
+  // mismatch a profile that legitimately uses different dimensions).
   if (cfg.windowSize !== undefined) {
     const { width, height } = cfg.windowSize;
     if (
@@ -501,7 +501,6 @@ export function buildChromiumArgs(
  * surfaces only the raw stderr tail. Exported for unit tests so we can lock
  * the regexes against regressions without spawning Chromium.
  *
- * @see tasks/0259-linux-first-run-experience.md
  */
 export function diagnoseEarlyExitTail(tail: string): string {
   if (/running.*root.*without.*--no-sandbox|--no-sandbox.*required/i.test(tail)) {

package/src/proxy-auth.ts

@@ -39,8 +39,6 @@
  * handler covers both.
  *
  * @see PLAN.md §8.2 / §10
- * @see tasks/0160-proxy-auth-and-ci-fix.md
- * @see tasks/0266-fetch-fulfill-init-script.md
  */
 
 import { installInitInjector } from "./cdp/init-injector";
@@ -148,7 +146,7 @@ export interface ProxyAuthHandle {
  * shim — delegates to {@link installInitInjector} with `payloadCode: null`
  * so the proxy-auth-only call path still works for any out-of-tree caller.
  *
- * The Session no longer uses this directly (task 0266); proxy auth and
+ * The Session no longer uses this directly; proxy auth and
  * init-script delivery share a single `Fetch.enable` owner.
  *
  * Behavior (unchanged contract):