feat(01-11): wave-2 — Puppeteer harness scaffolding + A0 GREEN, popup-bridge architecture

Task 3 of Plan 01-11 (Puppeteer UAT harness).

Harness file tree (tests/uat/):
- harness.test.ts: tsx-runnable top-to-bottom harness entry point.
  Runs A0 inline (filesystem grep gate, abort-on-fail T-1-11-01),
  then launches Chrome + opens popup bridge + queries manifest, then
  iterates A1-A13 stubs. Each stub throws "NOT YET IMPLEMENTED —
  Plan 01-11 Task N wires this assertion". Exit code = 0 on full
  pass, 1 otherwise. Final line: "UAT harness: N/14 assertions passed".
- lib/launch.ts: launchHarnessBrowser() — wraps puppeteer.launch with
  enableExtensions:[dist-test/], headless default (HEADLESS=0
  override), --no-sandbox + --auto-select-desktop-capture-source flags.
  Polls browser.extensions() until the extension registers (empirically
  ~100ms but the first call right after launch returns Map(0)).
  Opens both a blank page (for triggerExtensionAction) AND the popup
  page (the bridge surface). Returns { browser, extension, extensionId,
  sw, downloadsDir, page, popup }.
- lib/extension.ts: waitForOffscreenTarget + attachToOffscreen +
  countOffscreenTargets. Offscreen attach uses target.type() ===
  'background_page' + .asPage() (NOT .page() — RESEARCH §4 Pitfall 1).
- lib/sw.ts: chrome.* state queries via the POPUP page handle (NOT
  the WebWorker handle — see architecture note below). getBadgeText,
  getPopup, getManifest, getIconSize, getIsRecording (side-channeled
  through badge text), fireOnStartup (via __mokoshTestQuery bridge),
  sendSyntheticRecordingError, getNotificationSnapshot (via bridge),
  keepalivePing (no-op message to wake SW for ~30s).
- lib/offscreen.ts: getDisplaySurface, simulateUserStop (the
  dispatchEvent('ended') path per RESEARCH §7 BLOCKER — DO NOT REFACTOR
  to track.stop()), getSegmentCount.
- lib/assertions.ts: runAssertion(idx, name, buffers, fn) wrapper —
  records pass/fail/duration; on failure dumps last 30 lines of SW
  + offscreen console buffers to stderr before rethrowing. assertEqual
  / assertMatch / assertTrue / assertGte / waitFor polling helper.
- lib/zip.ts: jszip-based assertArchiveShape + extractEntryToFile for
  assertions 12 + 13.
- README.md: runtime + local-debug + CI semantics + locale gotcha
  + dev-dep size note + assertion catalog table.
- tsconfig.json: per-tree type-check config (mirrors root tsconfig.json
  compiler options but includes the harness tree explicitly).

Architecture refinement (DEVIATION from RESEARCH §1 — Rule 1+3 inline fix):
- RESEARCH §1 sketched `sw.evaluate(() => chrome.action.getBadgeText({}))`
  as the chrome.* query path. Empirical probes during Task 3 execution
  against Puppeteer 25.0.2 + Chrome 148 + --headless=true revealed two
  blockers:
    1. Puppeteer's WebWorker.evaluate runs in an ISOLATED WORLD that
       carries SW globals (clients, registration, ...) but NOT the
       extension's full chrome.* API surface. Object.keys(chrome) inside
       sw.evaluate returns ["loadTimes","csi"] — the public webpage
       chrome, not the extension chrome.
    2. Chrome 148's headless mode aggressively suspends MV3 service
       workers; subsequent swTarget.worker() calls return
       "Protocol error: No target with given id found".
- WORKAROUND: open the popup page (chrome-extension://<id>/src/popup/
  index.html) as a separate Puppeteer Page. The popup has full
  chrome.* access (it's an extension context with same privileges as
  the SW) AND stable Puppeteer lifetime. For SW-globalThis state
  (__mokoshTest in the SW isolate, NOT in the popup), bridge via
  chrome.runtime.sendMessage. The popup sends
  { type: '__mokoshTestQuery', op: 'snapshot' | 'fire-on-startup' |
  'handler-types' }; the SW hook's onMessage handler responds.
- Bridge implementation added to src/test-hooks/sw-hooks.ts — registers
  AFTER the production listeners so it never intercepts production
  messages (__mokoshTest* type is unambiguously test-only). Tier-1
  grep gate (no-test-hooks-in-prod-bundle.test.ts) continues to enforce
  ZERO __mokoshTest occurrences in dist/ — the bridge handler is
  tree-shaken alongside the rest of the hook module via the
  __MOKOSH_UAT__ gate.

Other configuration changes:
- vitest.config.ts: exclude tests/uat/** from vitest discovery. The
  Puppeteer harness is invoked via `npm run test:uat` (not vitest);
  running it under vitest would try to launch real Chrome inside a
  vitest worker. The .test.ts suffix is retained for editor +
  naming-convention consistency with the rest of the tree.

Verification:
- npx tsc --noEmit (src/): exit 0
- npx tsc --noEmit -p tests/uat: exit 0
- npm run build: exit 0
- grep -rln '__mokoshTest|simulateUserStop|getSegmentCount|setCurrentStream|setSegmentCountGetter|__mokoshTestQuery|__mokoshKeepalive' dist/: ZERO matches
- npm run build:test: exit 0; dist-test/ populated with the new bridge code
- SKIP_BUILD=1 npx vitest run: 89/89 GREEN
- SKIP_PROD_REBUILD=1 npx tsx tests/uat/harness.test.ts:
  → A0 [PASS]: production bundle has no test-hook leaks (19ms)
  → Browser launches; popup opens; manifest read succeeds
  → A1-A13 [FAIL]: NOT YET IMPLEMENTED — Plan 01-11 Task N wires this
  → "UAT harness: 1/14 assertions passed, 13 failed (first failure: A1)"
  → Exit code: 1 (expected — 13 RED stubs intentional)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/test-hooks/sw-hooks.ts

@@ -227,4 +227,85 @@ globalThis.__mokoshTest = {
   },
 } as MokoshTestSurface;
 
+// ─── Harness message bridge ───────────────────────────────────────────
+// EMPIRICAL ARCHITECTURE NOTE: Puppeteer 25 + Chrome 148 + headless
+// cannot reliably evaluate against the SW directly. The harness
+// queries chrome.* state through the popup page (which has full
+// chrome.* API access) but cannot read the SW's globalThis.__mokoshTest
+// because the popup is a SEPARATE V8 isolate. So we bridge: the popup
+// sends chrome.runtime.sendMessage queries; this handler responds with
+// the queried state.
+//
+// Protocol — popup → SW message: { type: '__mokoshTestQuery', op: <string> }
+// Response shapes:
+//   op='snapshot' → { count, lastOptions, ids }
+//   op='fire-on-startup' → { ok: true } OR { ok: false, error: 'no-handler' }
+//   op='handler-types' → { onClicked, onStartup, notificationOnClicked }
+// Unknown ops respond { ok: false, error: 'unknown-op' }.
+//
+// Returning `true` from the onMessage handler tells Chrome the
+// response is async; we keep sendResponse as a closed-over callback.
+// The bridge handler is registered AFTER the production listeners so
+// the hook never accidentally intercepts a production message —
+// __mokoshTest* messages are unambiguously test-only.
+chrome.runtime.onMessage.addListener((rawMessage, _sender, sendResponse) => {
+  // Narrow the message — we accept ANY shape but only act on our type.
+  if (rawMessage === null || typeof rawMessage !== 'object') {
+    return false;
+  }
+  const message = rawMessage as { type?: unknown; op?: unknown };
+  if (message.type !== '__mokoshTestQuery') {
+    // Not our message — production handler will take it.
+    return false;
+  }
+  const op = String(message.op ?? '');
+  if (op === 'snapshot') {
+    sendResponse({
+      count: notificationCount,
+      lastOptions: lastNotificationOptions,
+      ids: notificationIds.slice(),
+    });
+    return false; // Sync response — return false per Chrome onMessage contract.
+  }
+  if (op === 'fire-on-startup') {
+    const h = handlers.onStartup;
+    if (h === null) {
+      sendResponse({ ok: false, error: 'no-handler' });
+      return false;
+    }
+    // Fire-and-respond. The handler may be async; we don't await it
+    // for the response, but if it throws synchronously the catch
+    // surfaces in the response.
+    try {
+      // Schedule on microtask so the response goes out first; the
+      // handler's side effects (notifications.create) happen right
+      // after, before the next harness assertion polls.
+      queueMicrotask(() => {
+        Promise.resolve(h()).catch((err) => {
+          // Swallow async errors — the assertion 8 check is on the
+          // notification side effect, not the handler's return value.
+          console.warn('[mokoshTest bridge] onStartup handler threw:', err);
+        });
+      });
+      sendResponse({ ok: true });
+    } catch (err) {
+      sendResponse({
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+    return false;
+  }
+  if (op === 'handler-types') {
+    sendResponse({
+      onClicked: typeof handlers.onClicked,
+      onStartup: typeof handlers.onStartup,
+      notificationOnClicked: typeof handlers.notificationOnClicked,
+    });
+    return false;
+  }
+  sendResponse({ ok: false, error: 'unknown-op' });
+  return false;
+});
+
 export {};