lazycodex-ai 5.0.0-beta.7 → 5.0.0-beta.71

package/packages/omo-codex/plugin/skills/debugging/references/scripts/fixture-adapter.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Deterministic DAP fixture used by dap.test.ts.
+import { stdin, stdout, argv } from "node:process";
+
+let seq = 1;
+let buffer = Buffer.alloc(0);
+const noAnswer = argv.includes("--no-answer") || process.env.DAP_FIXTURE_NO_ANSWER === "1";
+
+function send(message) {
+  const body = Buffer.from(JSON.stringify(message));
+  stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+  stdout.write(body);
+}
+function response(request, body = {}, success = true, message) {
+  send({ type: "response", seq: seq++, request_seq: request.seq, success, command: request.command, body, ...(message ? { message } : {}) });
+}
+function event(event, body = {}) { send({ type: "event", seq: seq++, event, body }); }
+function handle(request) {
+  if (noAnswer && request.command === "initialize") return;
+  switch (request.command) {
+    case "initialize":
+      response(request, { supportsConfigurationDoneRequest: true, supportsEvaluateForHovers: true });
+      event("initialized");
+      break;
+    case "setBreakpoints": {
+      const bps = request.arguments?.breakpoints ?? [];
+      response(request, { breakpoints: bps.map((bp, i) => ({ id: i + 1, verified: !request.arguments?.source?.path?.includes("unverified"), line: bp.line, column: bp.column ?? 1, message: "fixture" })) });
+      break;
+    }
+    case "configurationDone": response(request); break;
+    case "launch": response(request); break;
+    case "continue": response(request, { allThreadsContinued: true }); event("stopped", { reason: "breakpoint", threadId: 1, allThreadsStopped: true }); break;
+    case "next": case "stepIn": case "stepOut": response(request); event("stopped", { reason: "step", threadId: 1 }); break;
+    case "pause": response(request); event("stopped", { reason: "pause", threadId: 1 }); break;
+    case "threads": response(request, { threads: [{ id: 1, name: "main" }] }); break;
+    case "stackTrace": response(request, { stackFrames: [{ id: 42, name: "main", source: { path: "/tmp/program.py" }, line: 12, column: 3 }] }); break;
+    case "scopes": response(request, { scopes: [{ name: "Locals", variablesReference: 7, expensive: false }] }); break;
+    case "variables": response(request, { variables: Array.from({ length: 250 }, (_, i) => ({ name: `v${i + 1}`, value: request.arguments?.variablesReference === 8 ? `${String(i + 1)} ${"x".repeat(500)}` : String(i + 1), variablesReference: 0 })) }); break;
+    case "evaluate": response(request, { result: "42", type: "int", variablesReference: 0 }); break;
+    case "terminate": response(request); event("terminated", {}); break;
+    default: response(request, {}, false, `unsupported ${request.command}`);
+  }
+}
+stdin.on("data", chunk => {
+  buffer = Buffer.concat([buffer, chunk]);
+  while (true) {
+    const marker = buffer.indexOf(Buffer.from("\r\n\r\n"));
+    if (marker < 0) return;
+    const header = buffer.subarray(0, marker).toString();
+    const match = header.match(/Content-Length:\s*(\d+)/i);
+    if (!match) { buffer = buffer.subarray(marker + 4); continue; }
+    const length = Number(match[1]);
+    const start = marker + 4;
+    if (buffer.length < start + length) return;
+    const body = buffer.subarray(start, start + length);
+    buffer = buffer.subarray(start + length);
+    try { handle(JSON.parse(body.toString("utf8"))); } catch { /* fixture input is controlled */ }
+  }
+});

package/packages/omo-codex/plugin/skills/debugging/references/tools/dap.md

@@ -0,0 +1,103 @@
+# DAP Client (`dap.mjs`) — Drive the Debugger's Protocol, Not Its Text
+
+**Design modeled on the `debug` tool of oh-my-pi (https://github.com/can1357/oh-my-pi, branch omp2).** Their harness proved the shape: one structured debug surface with bounded output, stop snapshots, and classified errors. This script brings the same discipline to any agent with a shell — no harness tool registration required.
+
+Debuggers already speak the Debug Adapter Protocol (DAP), a machine-readable JSON protocol. Driving DAP beats screen-scraping a PTY for the same reason an API beats OCR: structured stops, structured variables, structured errors. **If the debugger speaks DAP, use this script instead of parsing `gdb`/`pdb` output.**
+
+The script is at `references/scripts/dap.mjs` — zero dependencies, runs under Bun or Node.
+
+---
+
+## When to use which interface
+
+| Situation | Use |
+|---|---|
+| Source-level debugging of Python / Go / Node / native code, and you need breakpoints, stepping, variables | `dap.mjs` (this file) |
+| Browser-served JS, or anything already in Chrome | Scripted CDP — see `references/runtimes/node.md` |
+| Stripped binary, no source, no symbols | Ghidra (static) + Frida (live) — see `references/tools/` |
+| The debugger has no DAP mode (plain gdb on an exotic target) | pwndbg, with the output-budget rule from `references/methodology/00-setup.md` |
+
+---
+
+## How to drive it
+
+`dap.mjs` is a **REPL**, not a one-shot command: a debug session is long-lived, so the script runs as a persistent process reading one command per line on stdin and writing bounded text on stdout. Run it as a background shell session, send commands to its stdin, and subscribe to its output.
+
+```
+bun references/scripts/dap.mjs
+```
+
+Every execution-control answer prints a single snapshot line beginning with `STOP:` — subscribe your watcher to that exact prefix so a breakpoint hit wakes you instead of you polling.
+
+### Commands
+
+| Command | Effect |
+|---|---|
+| `launch <adapter> <program> [args...]` | Spawn a stdio adapter (path to executable or `.mjs` adapter) and launch the program under it |
+| `attach <host:port>` | Connect to a listening adapter over TCP and attach |
+| `break <file>:<line>` / `rmbreak <file>:<line>` | Set / remove a source breakpoint |
+| `continue` / `step` / `next` / `stepin` / `stepout` / `pause` | Execution control; each prints a `STOP:` snapshot when the debuggee next stops |
+| `stack [limit]` | TSV backtrace, bounded |
+| `scopes` | Scopes of the top frame with their variablesReferences |
+| `vars <ref>` | Variables under a variablesReference from `scopes` — refs are session-scoped; always chain `scopes` first |
+| `eval <expr>` | Evaluate in the top frame |
+| `threads` / `sessions` | Thread list / session state |
+| `terminate` / `quit` | End the debuggee / exit the REPL |
+
+### Output contract (what keeps your context alive)
+
+- Tabular results are TSV with a header row.
+- Hard caps: `MAX_ROWS = 100`, `MAX_OUTPUT_BYTES = 32 KB`. Overflow prints an explicit `TRUNCATED: rows dropped=N bytes dropped=M` line — never a silent cut.
+- After every continue/step: `STOP: stopped reason=<why> threadId=<id> <frame> at <file>:<line>:<col>`. On debuggee exit: `EXIT: terminated`.
+- Errors are one line, classified: `ERR: invalid-args | no-session | adapter-failed | unverified-breakpoint | timeout | terminated | adapter-error`. The token tells you the recovery — see the failure taxonomy in `references/methodology/02-investigate.md`.
+- Every request times out after 15 s (override with `DAP_TIMEOUT_MS`) and the session stays alive.
+- `DAP_DEBUG=1` logs raw protocol traffic to stderr for diagnosing a misbehaving adapter.
+
+### Adapter quirks this client already handles
+
+- **debugpy** requires `console: "internalConsole"` in the launch request, and withholds the `initialized` event for unrecognized `adapterID`s — the client sends both correctly. It also flushes `initialized` lazily, so the client launches first and awaits the event after.
+- **lldb-dap** reports the launch response's `success` unreliably (`false` even when the process started and stopped) and reports `threadId: 0` on the entry stop. The events are the real signal; the client tolerates the response flag.
+
+---
+
+## Adapter matrix
+
+Translated from oh-my-pi's `builtin_adapters()` (omp2 `crates/docserver/src/dap_adapter.rs`). Install the one matching your runtime; the client speaks to all of them the same way.
+
+| Runtime | Adapter | Install | Launch mode |
+|---|---|---|---|
+| Python | debugpy | `pip install debugpy` | `python -m debugpy.adapter` (stdio) |
+| Go | dlv | `go install github.com/go-delve/delve/cmd/dlv@latest` | `dlv dap` (stdio) |
+| C/C++/Swift/Rust/Zig | lldb-dap | ships with Xcode CLT / LLVM | `lldb-dap` (stdio) |
+| C/C++/Rust/Zig | codelldb | VS Code extension binary | stdio |
+| C/C++/Rust | gdb | `brew install gdb` / apt | via gdb's DAP mode where available |
+| JS/TS | js-debug | `npm i -g @vscode/js-debug` | stdio |
+| .NET | netcoredbg | GitHub releases | stdio |
+| Ruby | rdbg | `gem install debug` | stdio |
+| Kotlin | kotlin-debug-adapter | GitHub releases | stdio |
+| PHP | php-debug-adapter | composer | stdio |
+| Bash | bash-debug-adapter | GitHub releases | stdio |
+| Dart/Flutter | dart debug adapter | ships with Dart SDK | `dart` (stdio) |
+| Elixir | elixir-ls debugger | GitHub releases | stdio |
+
+If an adapter is missing, the install line is the fix — do not fall back to scraping a REPL.
+
+---
+
+## Worked example (Python)
+
+```
+launch /path/to/python -m debugpy.adapter myscript.py   # or a wrapper script path
+break myscript.py:12
+continue
+STOP: stopped reason=breakpoint threadId=1 compute at myscript.py:12:1
+stack
+scopes
+vars 6          # the variablesReference scopes just printed for Locals
+eval total
+continue
+terminate
+quit
+```
+
+Cleanup is part of the session: `terminate` the debuggee, `quit` the REPL, and journal any wrapper scripts you created per the skill's cleanup phase.

package/packages/omo-codex/plugin/skills/debugging/references/tools/frida.md

@@ -0,0 +1,193 @@
+# Frida — Hook a Live Process and See Real Values at Runtime
+
+**https://frida.re**
+
+Frida injects a JavaScript engine into a running process and lets you intercept function calls, read arguments, patch return values, and trace execution without touching the binary on disk. **When static analysis in Ghidra shows you *what* a function does, Frida shows you what it does *right now*, with real inputs.** The two compose naturally: use Ghidra to find the target function and its offset, then use Frida to hook it and watch live traffic.
+
+Choose Frida over Ghidra when you need runtime values (actual arguments, return codes, heap contents) or when the binary's control flow is too obfuscated for static analysis to resolve.
+
+---
+
+## Install
+
+```bash
+pip install frida-tools            # Python 3 required
+frida --version                    # verify
+```
+
+On macOS, attaching to another user's process needs root (`sudo frida ...`). SIP-protected system binaries (`/usr/bin/*`, `/usr/sbin/*`) are off-limits entirely. On Linux, you may need `ptrace` permissions: run as root or set `kernel.yama.ptrace_scope=0`.
+
+---
+
+## Target discovery with `frida-ps`
+
+```bash
+frida-ps                         # list local processes
+frida-ps -U                      # USB-connected device (iOS/Android)
+frida-ps | grep -i target        # find your target by name
+```
+
+---
+
+## `frida-trace` — zero-code entry point
+
+`frida-trace` auto-generates JavaScript handler stubs for every matched function. You don't write any code to start.
+
+```bash
+frida-trace -p <pid> -i "recv*"                               # trace exported functions by glob
+frida-trace -p <pid> -m "-[NSURLSession dataTaskWithRequest:*]"  # Objective-C method
+frida-trace -U -p <pid> -j "com.example.App!login*"             # Java method (Android)
+frida-trace -f ./target -i "open"                               # spawn + trace from start
+```
+
+Generated handler files land in `__handlers__/`. Each looks like:
+
+```js
+// __handlers__/libSystem.B.dylib/open.js
+{
+  onEnter(log, args, state) {
+    // args[0] is the first argument (a pointer)
+    log(`open("${args[0].readUtf8String()}")`);
+  },
+  onLeave(log, retval, state) {
+    log(`  => ${retval}`);
+  }
+}
+```
+
+Edit that file, save, and `frida-trace` hot-reloads it. This is the fastest path from "I wonder what this function receives" to a concrete answer.
+
+---
+
+## The JS agent API
+
+When `frida-trace` isn't enough, you write a JS agent and load it with `frida` or from a Python host script. These are the building blocks.
+
+### Find a function
+
+```js
+// By exported symbol name
+const openPtr = Module.getExportByName(null, "open");  // null = any module
+const sslWritePtr = Module.getExportByName("libssl.so", "SSL_write");
+
+// By offset in a stripped binary (get the offset from Ghidra)
+const base = Module.getBaseAddress("target");
+const funcPtr = base.add(0x1a3c);
+```
+
+### Intercept calls
+
+```js
+Interceptor.attach(openPtr, {
+  onEnter(args) {
+    // args[0], args[1], ... are NativePointer objects
+    const path = args[0].readUtf8String();
+    const flags = args[1].toInt32();
+    send({ event: "open", path: path, flags: flags });
+  },
+  onLeave(retval) {
+    // retval is the return value as a NativePointer
+    send({ event: "open_ret", fd: retval.toInt32() });
+  }
+});
+```
+
+### Read memory
+
+```js
+args[0].readUtf8String()          // read a UTF-8 C string from a pointer
+args[0].readCString()             // read a raw C string (stops at null)
+args[1].readByteArray(len)        // read len raw bytes (returns ArrayBuffer)
+```
+
+### Replace / stub a function
+
+```js
+// Force a function to always return 0 (e.g. bypass a license check)
+Interceptor.replace(checkLicensePtr, new NativeCallback(function () {
+  return 0;
+}, 'int', []));
+```
+
+Use `Interceptor.replace` sparingly. It changes program behavior, so always note in your journal that you patched something and why.
+
+---
+
+## Python host script
+
+A host script lets you load a JS agent, receive `send()` messages, and post-process results from the Python side.
+
+```python
+import frida, sys
+
+with open("agent.js") as f:
+    agent_source = f.read()
+
+def on_message(message, data):
+    if message["type"] == "send":
+        print(f"[*] {message['payload']}")
+    else:
+        print(f"[!] {message}")
+
+session = frida.attach(int(sys.argv[1]))
+script = session.create_script(agent_source)
+script.on("message", on_message)
+script.load()
+
+try:
+    sys.stdin.read()                 # block until Ctrl+C
+except KeyboardInterrupt:
+    session.detach()
+```
+
+The agent runs inside the target; the host script stays in your terminal and prints structured output.
+
+---
+
+## Output-budget discipline
+
+**Hooking a hot function (e.g. `malloc`, `read`) will flood your context with thousands of lines.** Don't print every call. Aggregate in the agent and report a summary.
+
+```js
+// Count calls, report every 1000
+let callCount = 0;
+Interceptor.attach(mallocPtr, {
+  onEnter(args) {
+    callCount++;
+    if (callCount % 1000 === 0) {
+      send({ event: "malloc_summary", total_calls: callCount });
+    }
+  }
+});
+```
+
+Alternatives: filter by argument value, only log calls from a specific caller module, or batch into an array and `send()` on a timer.
+
+---
+
+## ⚠️ Gotchas
+
+**Attach vs. spawn.** `frida -p <pid>` attaches to an already-running process. If you need to catch early initialization (constructors, `main` entry), spawn the process with `frida -f ./target`. Frida pauses it at startup. Resume with `%resume` in the REPL or by calling `device.resume(pid)` from Python.
+
+**Stripped binaries have no symbol names.** `Module.getExportByName` returns null for internal functions. You must find the function offset in Ghidra, then compute the address at runtime:
+
+```js
+const addr = Module.getBaseAddress("target").add(0x4a20);
+Interceptor.attach(addr, { /* ... */ });
+```
+
+**A crashing target kills your session.** If the target segfaults or aborts, Frida's agent dies with it. Script a respawn loop on the Python side if you expect crashes.
+
+**Thread safety.** `onEnter`/`onLeave` fire on multiple threads. Keep shared state to simple counters.
+
+---
+
+## Cleanup
+
+```bash
+kill <pid>                         # kill any process you spawned with -f
+rm -rf __handlers__/               # remove generated handler stubs
+rm -f agent.js host.py             # remove session-specific scripts
+```
+
+Always note in your journal which processes you attached to and whether you replaced any functions. A forgotten `Interceptor.replace` in a long-running target will cause confusing behavior later.

package/packages/omo-codex/plugin/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/omo-codex/plugin/skills/frontend/ATTRIBUTION.md

@@ -217,6 +217,16 @@ documentation text, or component implementations are vendored. beui.dev names re
 property of their owner, and the guide instructs reading component source for mechanism
 extraction only, not vendoring it into references or projects.
 
+`frontend/references/design/ambience-skill.md` is a project-original, curl-only operating
+guide for consulting the react-bits (reactbits.dev) animated-component registry during hero
+atmosphere, background, typographic-motion, and card-surface work, written from live endpoint
+verification; no react-bits source code, documentation text, or component implementations are
+vendored. react-bits is distributed under MIT plus the Commons Clause, which permits use inside
+applications but forbids redistributing or porting the components themselves; the guide
+therefore instructs reading component source for mechanism extraction only and never vendoring
+it into references, design documents, or this repository. React Bits names remain the property
+of their owner.
+
 `frontend/references/design/clone-from-url.md` is a project-original runtime-extraction
 workflow guide. Its browser + `getComputedStyle` clone approach follows the same
 MIT-licensed `JCodesMore/ai-website-cloner-template` clone-website workflow that `aside.md`