oh-my-opencode 5.0.0-beta.62 → 5.0.0-beta.63

package/packages/omo-codex/plugin/skills/ulw-research/SKILL.md

@@ -177,7 +177,7 @@ Scaling floor — more angles always justify more workers:
 | Multi-faceted | 4 | 6 | 2 | 2 | 14 |
 | Full due diligence | 4 | 6 | 3 | 2 | 15 |
 
-The browsing column is BINDING, not advisory: when the brief says `Browsing: yes`, the roster names a browsing-worker angle before the first wave launches, and that worker is spawned in the same turn as the rest of the wave. A run that reaches wave 2 with zero browsing workers on a `Browsing: yes` brief has silently downgraded every source to what plain fetch happened to return.
+The browsing column is BINDING, not advisory: when the brief says `Browsing: yes`, the roster names a browsing-worker angle, armed with the `ultimate-browsing` skill, before the first wave launches, and that worker is spawned in the same turn as the rest of the wave. A run that reaches wave 2 with zero browsing workers on a `Browsing: yes` brief has silently downgraded every source to what plain fetch happened to return.
 
 **Disambiguate before you expand.** When the topic names something that could resolve several ways — a product, a person, a codename, a version — the first wave settles WHICH entity before any worker researches its history, benchmarks, or controversies: canonical name, first-party URL or account, whether it exists in the claimed category, and a confidence line. An unresolved entity never becomes a premise in a later wave's spawn message; that is exactly how a run starts inventing facts about something that does not exist.
 
@@ -185,7 +185,7 @@ Role protocols — embed the relevant one in each spawn message; every worker ge
 
 - **Codebase (explore), 2-4 workers.** Grep with 3+ keyword variations; structural/AST search; LSP definitions and references; file-name globs; `git log --all -S '<keyword>'` and `--grep` for history including deleted code. Cross-validate hits across tools. Report absolute file paths, patterns with `file:line`, and how findings connect.
 - **Web (librarian), 3-6 workers.** At least 10 distinct websearch queries per worker, each with a different operator or angle (see Search craft); fetch the full page for every result that matters — snippets lie. Context7 with 3+ queries per known library. grep.app and `gh search code|repos|issues` for real-world usage. Official docs via sitemap discovery (`<base>/sitemap.xml`), then targeted pages.
-- **Browsing, 1-3 workers on a `Browsing: yes` brief (0 otherwise).** This worker RENDERS pages, it does not re-fetch them: it drives a real browser through whatever the harness provides — the Browser plugin, an agent-browser or playwright skill, or a code-cell browser — and loads the `ultimate-browsing` skill to escalate through its tiers (insane-search engine with its Phase-2.5 archive surrogates, platform-native readers, then Chrome stealth) only when that browser is blocked. Its standing deliverable is a full-page screenshot of every top source plus the rendered text plain fetch could not reach; a worker that returns only fetched text has not done its job. JS-rendered, login-gated, WAF-blocked, and screenshot-bearing sources all belong here rather than in the web lane. **Provenance is part of the claim**: when a source came back with `provenance` of `snapshot` (an archive copy), cite it with its `snapshot_timestamp` and never state it as the current live page; content from a `proxy` route is `untrusted` and needs a second independent route before any claim rests on it. When one blocked territory hides many leads, fan out more browsing subagents in parallel for breadth instead of serializing one worker through them.
+- **Browsing, 1-3 workers on a `Browsing: yes` brief (0 otherwise), every one loaded with the `ultimate-browsing` skill.** The skill owns the routing — the harness's own browser first, then its extraction engine with archive surrogates, platform-native readers, and Chrome stealth as each source demands; the worker owns the deliverable. This worker RENDERS pages, it does not re-fetch them: its standing deliverable is a full-page screenshot of every top source plus the rendered text plain fetch could not reach; a worker that returns only fetched text has not done its job. JS-rendered, login-gated, WAF-blocked, and screenshot-bearing sources all belong here rather than in the web lane. **Provenance is part of the claim**: when a source came back with `provenance` of `snapshot` (an archive copy), cite it with its `snapshot_timestamp` and never state it as the current live page; content from a `proxy` route is `untrusted` and needs a second independent route before any claim rests on it. When one blocked territory hides many leads, fan out more browsing subagents in parallel for breadth instead of serializing one worker through them.
 - **Repo deep-dive (librarian), 0-2 workers.** Shallow-clone the most relevant repos to `${TMPDIR:-/tmp}`, pin the HEAD SHA, read core modules, follow call chains, return SHA-pinned permalinks.
 
 Example spawn (codebase axis; librarian, browsing, and repo-dive follow the same contract with their own protocol):
@@ -384,7 +384,7 @@ High-yield combinations: official docs (`site:<docs domain>`), GitHub implementa
 | Obeying a surrounding "stop exploring" rule mid-research | Authority section — those rules do not bind this mode |
 | Asking a worker to write journal or session files | Workers are read-only; you journal every return |
 | Two workers given the same angle | One unique angle per worker, always |
-| A `Browsing: yes` run whose roster carries no browsing worker | The browsing column is binding — name the angle in the brief and spawn it with the first wave, before any lead is chased |
+| A `Browsing: yes` run whose roster carries no browsing worker, or a browsing worker spawned without `ultimate-browsing` | The browsing column is binding — name the angle in the brief and spawn it, armed with the skill, in the first wave before any lead is chased |
 | Contested claim settled by judgment | Phase 3 — run code, capture output, verdict |
 | Deliverable claims without citations | Every claim cites a source or a verification artifact |
 | Guessing the deliverable format instead of asking | The format gate is unconditional: propose PDF+DOCX plus the domain-fitting alternatives and the template, then wait before wave 1 |

package/packages/omo-codex/plugin/skills/visual-qa/AGENTS.md

@@ -11,7 +11,7 @@ The visual-QA skill's executable core: a zero-dependency Node CLI that produces
 ```
 visual-qa/
 ├── SKILL.md                      # reviewer workflow (dual oracle, evidence gates) — the prose contract
-├── references/agent-browser-setup.md
+├── references/browser-setup.md
 └── scripts/
     ├── visual-qa.mjs             # SHIPPED RUNTIME: bun-build bundle of cli.ts (+ embedded modules)
     ├── cli.ts                    # development source; dispatches image-diff / tui-check

package/packages/omo-codex/plugin/skills/visual-qa/SKILL.md

@@ -73,7 +73,7 @@ Before any reviewer sees an image, verify each capture yourself: the file signat
 ### Web
 
 1. Capture a REFERENCE image: the user's mock/target, generated page snapshot, Figma export, source-site capture, or known-good baseline. Save as PNG. If the user provided overview text or annotations, save them next to the image and treat them as part of the reference packet.
-2. Capture the ACTUAL rendered screenshot at the same viewport size, driving the browser your harness actually has. Where a code cell can reach a browser (`new Bun.WebView()` on a Bun >= 1.4 kernel, otherwise `playwright-core` against the local Chrome), capture in-process: it needs no CLI and returns the PNG path directly. In Codex, `browser:control-in-app-browser` is that in-process surface — use it first unless the page needs an authenticated user browser session. Otherwise use the project's configured browser tooling (the playwright, agent-browser, or dev-browser skill). Save as PNG. If nothing is available, install [agent-browser](https://github.com/vercel-labs/agent-browser) (`bun add -g agent-browser && agent-browser install`) and capture with it — see `$SKILL_DIR/references/agent-browser-setup.md` for the full setup, including how to shoot a fixed-viewport screenshot.
+2. Capture the ACTUAL rendered screenshot at the reference viewport. Use two browser tiers from js eval: (1) `new Bun.WebView()` on Bun >= 1.4 (macOS default; Linux/Windows need installed Chrome/Chromium/Edge); (2) otherwise, or for Chrome semantics, stealth, trace, or authenticated profiles, WRITE a `playwright-core` script and run it from the kernel against local Chrome (`chromium.launch({ channel: "chrome" })` / `launchPersistentContext` on a CLONED profile, never the live one). In Codex, prefer `browser:control-in-app-browser` for ordinary captures. Save PNG and return its path; close the browser context. See `$SKILL_DIR/references/browser-setup.md` for fixed-viewport examples and prerequisites.
 3. Run the diff and keep the JSON:
 
 ```

package/packages/omo-codex/plugin/skills/visual-qa/references/browser-setup.md

@@ -0,0 +1,75 @@
+# Browser setup (Web capture)
+
+Use the js-eval kernel for both tiers. In Codex, prefer
+`browser:control-in-app-browser` for ordinary captures.
+
+## Tier 1: Bun.WebView
+
+On a Bun >= 1.4 kernel, `new Bun.WebView()` is the macOS default (system
+WebKit, no browser download). Linux/Windows require `backend: "chrome"`
+and installed Chrome/Chromium/Edge. WebView is headless; WebKit has no CDP,
+and `type()` emits no keyboard events. Use tier 2 when these differences matter.
+
+```js
+// js-eval cell; url and pngPath belong to this QA run.
+const view = new Bun.WebView({ width: 1280, height: 720 })
+try {
+  await view.navigate(url)
+  await Bun.write(pngPath, await view.screenshot())
+  console.log(pngPath)
+} finally {
+  view[Symbol.dispose]()
+}
+```
+
+## Tier 2: playwright-core with local Chrome
+
+For other kernels, real-Chrome semantics, stealth, traces, or authenticated
+profiles, WRITE a script beside the project's installed `playwright-core`
+dependency and execute it from js eval. The user installs `playwright-core`
+once with `bun add playwright-core` if needed; Chrome must already exist.
+No managed browser download is needed.
+
+```js
+// capture.mjs
+import { chromium } from "playwright-core"
+const [url, pngPath] = process.argv.slice(2)
+const browser = await chromium.launch({ channel: "chrome", headless: true })
+try {
+  const page = await browser.newPage({ viewport: { width: 1280, height: 720 }, deviceScaleFactor: 1 })
+  await page.goto(url, { waitUntil: "load", timeout: 30000 })
+  await page.screenshot({ path: pngPath })
+  console.log(pngPath)
+} finally {
+  await browser.close()
+}
+```
+
+Run from the js-eval kernel (also works on a Node kernel):
+
+```js
+const { promisify } = await import("node:util")
+const { execFile } = await import("node:child_process")
+const result = await promisify(execFile)("node", [scriptPath, url, pngPath], { timeout: 45000 })
+console.log(result.stdout)
+```
+
+For auth, CLONE the user-data directory to a private task-owned directory
+and use `chromium.launchPersistentContext(clonePath, { channel: "chrome" })`.
+NEVER launch against or clear cookies/cache/site data from the live profile.
+Close the context and remove only the clone after QA. For script-based stealth,
+read the ultimate-browsing skill's `references/chrome-stealth.md`.
+
+## Capture a screenshot at a fixed viewport
+
+Match CSS viewport AND PNG dimensions: WebKit follows native display scale
+(a 1280x720 viewport can yield 2560x1440 pixels). Use matching reference
+captures or Chrome's `deviceScaleFactor`, not resizing to force a pass.
+Wait for the specific page state, not a sleep, then compare:
+
+```sh
+node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff reference.png actual.png
+```
+
+Inspect `dimensionsMatch` and `diffRatio`, then inspect the image. Close every
+WebView/browser context and the fixture server, even on a failed capture.

package/packages/omo-codex/scripts/install-dist/install-local.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// omo-codex-install:6df5dbbbb7ca9b9dce86fae98a525a9caa7de96caed85a4b77d4e8b4ab4d1501:205e3b91b12b465ff20c412c1ae0f8bf179eb3523234e475875924abeb015bd4
+// omo-codex-install:6df5dbbbb7ca9b9dce86fae98a525a9caa7de96caed85a4b77d4e8b4ab4d1501:9b64e23f577a752e30550d1f643f52fe0f27897bd70bc633db60eb57deab9827
 var __esm = (fn, res, err) => () => {
   if (fn)
     try {
@@ -7706,7 +7706,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@oh-my-opencode/omo-codex",
-    version: "5.0.0-beta.62",
+    version: "5.0.0-beta.63",
     type: "module",
     private: true,
     description: "Codex harness adapter for oh-my-openagent. Vendored Codex plugin namespace (omo) + TypeScript installer + telemetry.",
@@ -13271,6 +13271,7 @@ var OmoTaskSettingsSchema = object({
   model_concurrency: record(string2(), number2().int().nonnegative()).optional(),
   max_depth: number2().int().nonnegative().default(1),
   residency_max_children: ResidencyMaxChildrenInputSchema.default(8),
+  resident_idle_timeout_ms: number2().int().positive().max(Number.MAX_SAFE_INTEGER).default(900000),
   ttl_ms: number2().int().positive().default(86400000),
   state_dir: string2().optional(),
   reattach_on_reconcile: boolean2().optional(),
@@ -13315,6 +13316,7 @@ var OmoTaskSettingsLayerSchema = object({
   model_concurrency: record(string2(), number2().int().nonnegative()).optional(),
   max_depth: number2().int().nonnegative().optional(),
   residency_max_children: ResidencyMaxChildrenInputSchema.optional(),
+  resident_idle_timeout_ms: number2().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
   ttl_ms: number2().int().positive().optional(),
   state_dir: string2().optional(),
   reattach_on_reconcile: boolean2().optional(),

package/packages/prompts-core/prompts/ultrawork/codex.md

@@ -62,16 +62,17 @@ exercises the surface; capture the artifact.
      for color / layout / CJK evidence, which degrades truecolor.
   3. Browser use — in Codex, use `browser:control-in-app-browser`
      first when available and no authenticated/persistent user browser
-     profile is required. Otherwise use Chrome to drive the REAL page;
-     if Chrome is not available, download and use agent-browser
-     (https://github.com/vercel-labs/agent-browser). Capture action
+     profile is required. Otherwise, or for Chrome semantics, stealth,
+     or trace, WRITE a `playwright-core` script and run it from js eval
+     against local Chrome (`chromium.launch({ channel: "chrome" })` /
+     `launchPersistentContext` on a CLONED profile). Capture action
      log + screenshot path. Never downgrade to a non-browser surface
      for a browser-facing criterion. NEVER clear cookies, cache, or
      site data (`Network.clearBrowserCookies`, `Storage.clearCookies`,
      `chrome.browsingData.remove`, "clear browsing data") on the user's
      real/main browser profile — it wipes their logged-in state. If you
      need that profile's login state, clone it first (`rsync -a
-     <profile>/ <tmp-clone>/`) and launch Chrome / agent-browser against
+     <profile>/ <tmp-clone>/`) and launch Chrome against
      the clone as the user-data-dir; run any clearing there only.
   4. Computer use — when the surface is a desktop/GUI app rather than a
      page, drive it via OS-level automation (a computer-use agent,

package/packages/shared-skills/skills/ast-grep/SKILL.md

@@ -11,6 +11,18 @@ This skill ships a Python wrapper at `scripts/ast_grep_helper.py` and platform i
 
 ---
 
+## OmO native: the ast-grep MCP tools (fastest path, no CLI needed)
+
+OmO native also registers a bundled ast-grep MCP server. Its three tools are **deferred**: they are absent from the resident tool list and activate automatically the first time you call them by name — no `tool_search` round trip needed.
+
+- `mcp__ast_grep_search({ pattern, language, paths })` — AST-shape search, the MCP equivalent of `sg run -p`. Prefer this over shelling out to `sg` for one-off lookups: no install, no PATH issues.
+- `mcp__ast_grep_rewrite({ pattern, rewrite, language, paths, apply })` — preview matches (`apply: false`, the default) or apply the rewrite (`apply: true`). Same two-pass discipline as `sg run -r`: preview first, then apply.
+- `mcp__ast_grep_scan({ paths })` — run project YAML rules (`sgconfig.yml`, `rules/`), the MCP equivalent of `sg scan`.
+
+Same pattern language as the CLI: `$VAR` matches one AST node, `$$$VAR` matches zero or more, and the pattern is code, not regex. `paths` accepts a file or directory list; `language` is required for patterns that are ambiguous across languages.
+
+---
+
 ## When to use this skill
 
 Use it whenever the user's question is about **code structure**, not bytes:

package/packages/shared-skills/skills/debugging/references/tools/playwright-cli.md

@@ -1,194 +1,112 @@
-# Playwright CLI — Browser QA That Actually Drives a Browser
+# Browser QA — Scripts from js eval
 
-**https://playwright.dev/ · https://github.com/microsoft/playwright**
-
-For any browser-served web UI bug, this is the correct tool. Not curl. Not imagination. Not a headless HTTP library. A real browser with a real rendering engine, real JS execution, real cookies, real service workers, real viewport.
-
-**In Phase 8 Manual QA for browser products, using Playwright is not optional.** Curl cannot catch: CSS that breaks at specific viewport widths, hydration mismatches, client-side router bugs, cookie/session interactions, service-worker caching, JS-triggered navigations. All of those are common bug classes. Drive a browser.
-
-> Note: `microsoft/playwright-cli` is the legacy repo; the current tooling lives in `@playwright/test` (npm) and `playwright` (pip), which include the `playwright` CLI. Use those — the legacy `playwright-cli` package is deprecated.
-
----
+A browser UI bug needs a rendered browser, not curl. Use two tiers from the
+js-eval kernel: `new Bun.WebView()` on Bun >= 1.4 for ordinary captures (macOS
+uses WebKit; Linux/Windows need installed Chrome/Chromium/Edge), otherwise a
+written `playwright-core` script against local Chrome. Use the script tier for
+Chrome semantics, stealth, traces, keyboard events, or authenticated profiles.
+In Codex, prefer `browser:control-in-app-browser` for ordinary page control.
 
 ## When to reach for Playwright
 
-| Bug symptom | Use Playwright? |
-|---|---|
-| Form submit produces wrong result | ✅ — Playwright drives the form exactly as a user does |
-| Page blank in prod, fine locally | ✅ — hydration/env differences need a real browser |
-| CSS looks wrong at a specific width | ✅ — use `--viewport-size` |
-| Click doesn't fire / wrong handler | ✅ — Playwright fires real DOM events |
-| Flash of unstyled content / loading glitch | ✅ — use trace viewer to see frames |
-| API returns wrong data | ❌ — use curl, this isn't a browser bug |
-| Backend returns wrong status code | ❌ — use curl |
-| Client hits a URL that returns 500 | ✅ but also ❌ — Playwright shows the call + response + failure effect on UI |
-
----
+Use the script tier for forms, hydration, responsive CSS, cookie/session flows,
+service workers, or client-side navigation. For a backend-only status/body bug,
+use HTTP. WebView is headless, WebKit has no CDP, and `type()` emits no keyboard
+events; choose real Chrome when these distinctions affect the reproduction.
 
 ## Install (per-project)
 
-Playwright installs browser binaries separately from the npm package.
-
-```bash
-# In the project
-npm init playwright@latest             # interactive; picks TS/JS + browsers + config
-# Or if Playwright is already a dep:
-npx playwright install                 # downloads browsers
-npx playwright install chromium        # just chromium
-npx playwright install --with-deps     # also installs OS deps (Linux)
-```
-
-Python:
-```bash
-pip install playwright
-playwright install
-```
+Reuse installed `playwright-core`. If absent, the user can install the script
+dependency once with `bun add playwright-core`. Chrome must already be installed;
+report an absent executable rather than downloading a managed browser. Write the
+script beside the dependency so normal module resolution works.
 
----
+For stealth, use the ultimate-browsing reference `references/chrome-stealth.md`:
+its optional plugins are user-installed once in the engine directory and executed
+as a script, not injected into WebView.
 
 ## The four things you'll actually use
 
-### 1. `codegen` — record a session, generate the script
-
-The fastest way to create a repro. Opens a real browser; your clicks / typing become a Playwright script you can paste into a test.
-
-```bash
-npx playwright codegen https://your-app.local
-npx playwright codegen --viewport-size=375,667 https://your-app.local    # iPhone SE size
-npx playwright codegen --device="iPhone 14" https://your-app.local
-```
-
-Click / type / navigate in the browser; watch the script build in the side panel. Copy the generated script into your journal as the repro for Phase 8.
-
-### 2. A one-shot Playwright script — reproduce + capture
-
-Usually the Phase 8 QA artifact. Save to `/tmp/debug-repro.spec.ts` (journal it):
-
-```ts
-// /tmp/debug-repro.spec.ts
-import { test, expect } from '@playwright/test';
-
-test('refinement chat shows non-empty response when env var set', async ({ page }) => {
-  await page.goto('http://localhost:3000/chat');
-  await page.fill('textarea[name="message"]', 'Add a logging step');
-  await page.click('button[type=submit]');
-
-  // Wait for the response to appear (not just the spinner to disappear)
-  const response = page.locator('[data-testid="assistant-reply"]');
-  await expect(response).toBeVisible({ timeout: 30_000 });
-  await expect(response).not.toBeEmpty();
-
-  // Capture evidence
-  await page.screenshot({ path: '/tmp/debug-after-fix.png', fullPage: true });
-  console.log(await response.textContent());
-});
-```
-
-Run it with tracing enabled for rich post-mortem:
-
-```bash
-npx playwright test /tmp/debug-repro.spec.ts --trace on --headed
-```
-
-### 3. `PWDEBUG=1` — step through the script with Playwright Inspector
-
-```bash
-PWDEBUG=1 npx playwright test /tmp/debug-repro.spec.ts
+### 1. Write a reproduction script
+
+Record the exact URL, inputs, viewport, expected UI state, and output artifact.
+For auth, CLONE the user-data directory and use `launchPersistentContext` on the
+clone. NEVER launch against or clear data from the live profile.
+
+### 2. Reproduce + capture
+
+```js
+// debug-repro.mjs
+import { chromium } from 'playwright-core';
+const [url, pngPath, tracePath] = process.argv.slice(2);
+const browser = await chromium.launch({ channel: 'chrome', headless: true });
+try {
+  const context = await browser.newContext({ viewport: { width: 1280, height: 720 } });
+  await context.tracing.start({ screenshots: true, snapshots: true });
+  try {
+    const page = await context.newPage();
+    page.on('pageerror', error => console.error(error));
+    await page.goto(url, { waitUntil: 'load', timeout: 30000 });
+    // Add the scenario's actions and locator/state assertions here.
+    await page.screenshot({ path: pngPath });
+    console.log(pngPath);
+  } finally {
+    await context.tracing.stop({ path: tracePath });
+    await context.close();
+  }
+} finally {
+  await browser.close();
+}
 ```
 
-Opens the Playwright Inspector alongside the browser. You can step through Playwright actions, see the DOM state at each step, and edit selectors on the fly.
-
-Use this when the script doesn't reproduce cleanly and you need to watch it run.
+A screenshot alone is not a reproduction assertion. Use locators for the exact
+observable state; fail the script when that state is absent.
 
-### 4. `show-trace` — post-mortem on a failed run
+### 3. Run from the js-eval kernel
 
-```bash
-npx playwright show-trace trace.zip
-# or from the test-results dir:
-npx playwright show-trace test-results/<test-name>/trace.zip
+```js
+const { promisify } = await import('node:util')
+const { execFile } = await import('node:child_process')
+const result = await promisify(execFile)('node', [scriptPath, url, pngPath, tracePath], { timeout: 60000 })
+console.log(result.stdout)
 ```
 
-Scrubs through a recorded session: timeline, DOM snapshot at each action, network, console, source. When a test failed on CI but passed locally, this is the single best artifact.
+### 4. Inspect the trace
 
----
+Retain the trace ZIP for the project's existing trace viewer and inspect the PNG.
+Trace snapshots, network events, and screenshots identify where the UI diverged.
+Keep auth-bearing traces private; do not upload them to public viewers.
 
 ## Headless vs headed during debugging
 
-Always add `--headed` when debugging. Headless browsers sometimes behave subtly differently (font rendering, viewport, media permissions). For QA evidence, run headed and screenshot.
-
-```bash
-npx playwright test --headed
-npx playwright test --headed --project=chromium     # pin the browser
-```
-
----
+Use `headless: false` with an available display when reproducing headed-only
+behavior. State which mode produced the evidence; do not claim a headless capture
+proves desktop-browser permissions or window behavior.
 
 ## Catching the silent-failure patterns Playwright is good at
 
-```ts
-// Toast that flashes and disappears
-page.on('console', msg => console.log('[browser console]', msg.type(), msg.text()));
-
-// Unhandled page errors (uncaught exceptions in the page JS)
-page.on('pageerror', err => console.error('[page error]', err));
-
-// Network failures — e.g., backend returned 500 but UI shows nothing
-page.on('response', async resp => {
-  if (!resp.ok()) {
-    console.warn(`[network ${resp.status()}] ${resp.url()} — ${await resp.text()}`);
-  }
-});
-
-// Request that never came back
-page.on('requestfailed', req => {
-  console.error('[request failed]', req.url(), req.failure()?.errorText);
-});
-```
-
-Add these listeners to the top of the debug script. They surface a lot of the "UI showed nothing" class of bug.
-
----
+Subscribe before triggering the action: `page.on('pageerror', ...)`,
+`page.on('requestfailed', ...)`, or a bounded `page.waitForResponse(...)` promise.
+Await that specific response/state rather than sleeping or waiting for generic
+network idleness. Propagate failed assertions and process exit codes.
 
 ## Viewport and device emulation
 
-CSS bugs that only appear at specific sizes, or layout bugs on mobile:
-
-```ts
-// At test level
-test.use({ viewport: { width: 375, height: 667 } });
-
-// Per-page
-await page.setViewportSize({ width: 375, height: 667 });
-
-// Predefined devices
-import { devices } from '@playwright/test';
-test.use({ ...devices['iPhone 14'] });
-```
-
----
+Use `page.setViewportSize({ width: 375, height: 667 })` for a narrow capture.
+`devices` comes from `playwright-core`; apply the desired preset when creating
+a context. Match the reference's pixel scale as well as its viewport.
 
 ## Gotchas
 
-- **Wait for state, not for time.** `await page.waitForTimeout(2000)` is flaky. Use `await expect(locator).toBeVisible()` or `page.waitForResponse(urlPattern)`.
-- **Stale selectors re-resolve.** Playwright's locators re-find the element on each action, unlike Puppeteer's handles. Don't over-think it.
-- **Service workers persist across test runs in headed mode.** If you see cached behavior from a previous run, add `await context.clearCookies()` + clear storage before the test.
-- **Installing on CI requires `--with-deps`** on Linux images that lack the browser's shared-library deps.
-- **Parallel tests share a browser process by default**; if one test polls a debugger port, others may interfere. Use `workers: 1` for debugging.
-
----
+- Wait for state, not time: locator visibility or the exact response is the signal.
+- Locators re-resolve after UI changes; stale element handles do not.
+- Fresh task-owned contexts avoid cached state leaking between runs.
+- Auth belongs in a private clone, never the live browser profile.
+- Give every run its own output directory and bounded process lifetime.
 
 ## Phase 9 cleanup specifics
 
-```bash
-# Remove trace files from debug runs
-rm -rf playwright-report/ test-results/ trace.zip
-
-# Remove debug spec files from /tmp
-rm -f /tmp/debug-*.spec.ts
-
-# Remove screenshot captures
-rm -f /tmp/debug-*.png
-
-# If you installed browsers just for this session (rare):
-# Don't remove them — they're useful for future sessions. They live in ~/Library/Caches/ms-playwright (macOS) or ~/.cache/ms-playwright (Linux).
-```
+Close WebView/browser contexts even on failure, stop the fixture server, and remove
+only this run's temporary scripts and profile clone. Preserve requested PNG/trace
+artifacts, then record the cleanup receipt. Do not kill unrelated browsers or
+remove a user's installed Chrome.

package/packages/shared-skills/skills/frontend/SKILL.md

@@ -146,7 +146,7 @@ Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `
 | Situation | Load |
 |---|---|
 | Brand/style not among the 70 in `references/design/`, or the user says "Open Design" | `open-design` skill — the local nexu-io/open-design library (137+ design skills, 150+ design systems) |
-| Driving a browser for the Design QA phase | `agent-browser` skill |
+| Driving a browser for the Design QA phase | `visual-qa` skill: Bun.WebView / local-Chrome `playwright-core` scripts from js eval; Codex in-app browser |
 | Pure TypeScript/logic work with zero visual surface | `programming` skill alone — this skill adds nothing there |
 
 ## Activation

package/packages/shared-skills/skills/frontend/references/design/aside.md

@@ -1,7 +1,7 @@
 # Design System Inspired by Aside
 
 > Category: Developer Tools & IDEs
-> AI browser agent. Bright product-app marketing, custom display type, soft squircle controls, agent-browser product framing.
+> AI browser agent. Bright product-app marketing, custom display type, soft squircle controls, browser-product framing.
 
 ## Provenance
 

package/packages/shared-skills/skills/frontend/references/design/clone-from-url.md

@@ -8,7 +8,7 @@ A `DESIGN.md` whose every token, interaction state, and motion value was read fr
 
 ## Phase 1 — Extract the runtime truth (never guess a value)
 
-Drive a real browser: Codex `browser:control-in-app-browser` first, otherwise the project's `agent-browser` / playwright / dev-browser tooling. Do NOT parse CSS files — minification, CORS, CSS-in-JS, and Tailwind utilities make source unreliable. `getComputedStyle` returns what the browser ACTUALLY rendered, so it is the only source of truth.
+Drive a real browser from js eval: `new Bun.WebView()` on Bun >= 1.4 (macOS default; Linux/Windows need installed Chrome/Chromium/Edge), otherwise write and run a `playwright-core` script against local Chrome (`channel: "chrome"`). Use that script lane for Chrome semantics, stealth, trace, or auth, with persistent contexts on CLONED profiles only. Codex: `browser:control-in-app-browser`. Do NOT parse CSS files — minification, CORS, CSS-in-JS, and Tailwind utilities make source unreliable. `getComputedStyle` returns what the browser ACTUALLY rendered, so it is the only source of truth.
 
 Sweep the page and read, for every meaningful element and every repeated pattern:
 

package/packages/shared-skills/skills/frontend/scripts/perfection/lighthouse-audit.py

@@ -11,8 +11,8 @@
 # ─── How to run ───
 # 1. Install uv (if not installed):
 #      curl -LsSf https://astral.sh/uv/install.sh | sh
-# 2. Install Playwright browsers (one-time):
-#      uv run --with playwright python -m playwright install chromium
+# 2. Chrome must already be installed locally:
+#      The script uses channel="chrome"; it downloads no browser.
 # 3. Run:
 #      uv run lighthouse-audit.py https://example.com
 #      uv run lighthouse-audit.py https://example.com --desktop-only

package/packages/shared-skills/skills/review-work/SKILL.md

@@ -127,7 +127,7 @@ You are the QA lane. Do not delegate hands-on QA to a sub-agent: the orchestrato
 2. **Pick the channel that faithfully exercises the surface** and capture the artifact:
    - HTTP: `curl -i` (or an API request context) - status line, headers, body.
    - CLI / TUI: a real pty - drive the command and keep the transcript; for color or layout evidence render through a browser-based terminal, never a `tmux capture-pane` dump.
-   - Web: the real page in a real browser - the harness's in-process surface (a `Bun.WebView` / `playwright-core` code cell, or Codex's Browser plugin) or the agent-browser CLI - action log plus screenshot.
+   - Web: from js eval, use `new Bun.WebView()` on Bun >= 1.4 (macOS default; Linux/Windows need Chrome/Chromium/Edge). Otherwise, or for Chrome semantics, stealth, trace, or auth, write and run a `playwright-core` script against local Chrome (`channel: "chrome"`; persistent context on a CLONED profile). Codex: `browser:control-in-app-browser`. Capture action log plus screenshot.
    - Desktop / GUI: OS-level automation against the running app - action log plus screenshot.
    - Library / SDK: a script that imports and exercises the public API - transcript.
    - Data-shaped work (migrations, configs, generated files): the resulting artifact itself, diffed or dumped.