lazycodex-ai 5.0.0-beta.82 → 5.0.0-beta.84

package/packages/omo-codex/plugin/hooks/session-start-checking-bootstrap-provisioning.json

@@ -8,7 +8,7 @@
 						"command": "node \"${PLUGIN_ROOT}/components/bootstrap/dist/cli.js\" hook session-start",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\bootstrap.ps1\"",
 						"timeout": 30,
-						"statusMessage": "(OmO 5.0.0-beta.82) Checking Bootstrap Provisioning"
+						"statusMessage": "(OmO 5.0.0-beta.84) Checking Bootstrap Provisioning"
 					}
 				]
 			}

package/packages/omo-codex/plugin/hooks/session-start-loading-project-rules.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/rules/dist/cli.js\" hook session-start",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.82) Loading Project Rules",
+						"statusMessage": "(OmO 5.0.0-beta.84) Loading Project Rules",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\rules\\dist\\cli.js\" hook session-start"
 					}
 				]

package/packages/omo-codex/plugin/hooks/session-start-recording-session-telemetry.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/telemetry/dist/cli.js\" hook session-start",
 						"timeout": 15,
-						"statusMessage": "(OmO 5.0.0-beta.82) Recording Session Telemetry",
+						"statusMessage": "(OmO 5.0.0-beta.84) Recording Session Telemetry",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\telemetry\\dist\\cli.js\" hook session-start"
 					}
 				]

package/packages/omo-codex/plugin/hooks/stop-checking-ulw-execute-continuation.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/ulw-execute-continuation/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.82) Checking Ulw-Execute Continuation",
+						"statusMessage": "(OmO 5.0.0-beta.84) Checking Ulw-Execute Continuation",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\ulw-execute-continuation\\dist\\cli.js\" hook stop"
 					}
 				]

package/packages/omo-codex/plugin/hooks/stop-checking-ulw-loop-resume.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/ulw-loop/dist/cli.js\" hook stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.82) Checking Ulw-Loop Resume",
+						"statusMessage": "(OmO 5.0.0-beta.84) Checking Ulw-Loop Resume",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\ulw-loop\\dist\\cli.js\" hook stop"
 					}
 				]

package/packages/omo-codex/plugin/hooks/subagent-stop-verifying-lazycodex-executor-evidence.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/lazycodex-executor-verify/dist/cli.js\" hook subagent-stop",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.82) Verifying LazyCodex Executor Evidence",
+						"statusMessage": "(OmO 5.0.0-beta.84) Verifying LazyCodex Executor Evidence",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\lazycodex-executor-verify\\dist\\cli.js\" hook subagent-stop"
 					}
 				],

package/packages/omo-codex/plugin/hooks/user-prompt-submit-checking-ultrawork-trigger.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/ultrawork/dist/cli.js\" hook user-prompt-submit",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.82) Checking Ultrawork Trigger",
+						"statusMessage": "(OmO 5.0.0-beta.84) Checking Ultrawork Trigger",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\ultrawork\\dist\\cli.js\" hook user-prompt-submit"
 					}
 				]

package/packages/omo-codex/plugin/hooks/user-prompt-submit-checking-ulw-loop-steering.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/ulw-loop/dist/cli.js\" hook user-prompt-submit",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.82) Checking Ulw-Loop Steering",
+						"statusMessage": "(OmO 5.0.0-beta.84) Checking Ulw-Loop Steering",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\ulw-loop\\dist\\cli.js\" hook user-prompt-submit"
 					}
 				]

package/packages/omo-codex/plugin/hooks/user-prompt-submit-loading-project-rules.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/rules/dist/cli.js\" hook user-prompt-submit",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.0.0-beta.82) Loading Project Rules",
+						"statusMessage": "(OmO 5.0.0-beta.84) Loading Project Rules",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\rules\\dist\\cli.js\" hook user-prompt-submit"
 					}
 				]

package/packages/omo-codex/plugin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "@sisyphuslabs/omo-codex-plugin",
-	"version": "5.0.0-beta.82",
+	"version": "5.0.0-beta.84",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@sisyphuslabs/omo-codex-plugin",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"workspaces": [
 				"components/comment-checker",
 				"components/git-bash",
@@ -95,7 +95,7 @@
 		},
 		"components/comment-checker": {
 			"name": "@code-yeongyu/codex-comment-checker",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"license": "MIT",
 			"bin": {
 				"omo-comment-checker": "dist/cli.js"
@@ -117,7 +117,7 @@
 		},
 		"components/git-bash": {
 			"name": "@sisyphuslabs/codex-git-bash-hook",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"bin": {
 				"omo-git-bash-hook": "dist/cli.js"
 			},
@@ -131,7 +131,7 @@
 		},
 		"components/lazycodex-executor-verify": {
 			"name": "@code-yeongyu/codex-lazycodex-executor-verify",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"license": "MIT",
 			"bin": {
 				"lazycodex-executor-verify": "dist/cli.js"
@@ -149,7 +149,7 @@
 		},
 		"components/lsp": {
 			"name": "@code-yeongyu/codex-lsp",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"license": "MIT",
 			"dependencies": {
 				"@code-yeongyu/lsp-daemon": "file:../../../../lsp-daemon",
@@ -171,7 +171,7 @@
 		},
 		"components/rules": {
 			"name": "@code-yeongyu/codex-rules",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"license": "MIT",
 			"dependencies": {
 				"picomatch": "^4.0.7"
@@ -194,7 +194,7 @@
 		},
 		"components/teammode": {
 			"name": "@sisyphuslabs/codex-teammode",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"devDependencies": {
 				"@types/node": "^26.6.2",
 				"@vitest/coverage-v8": "5.0.1",
@@ -208,7 +208,7 @@
 		},
 		"components/telemetry": {
 			"name": "@code-yeongyu/codex-telemetry",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"license": "MIT",
 			"bin": {
 				"omo-telemetry": "dist/cli.js"
@@ -227,7 +227,7 @@
 		},
 		"components/ultrawork": {
 			"name": "@code-yeongyu/codex-ultrawork",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"license": "MIT",
 			"bin": {
 				"omo-ultrawork": "dist/cli.js"
@@ -246,7 +246,7 @@
 		},
 		"components/ulw-execute-continuation": {
 			"name": "@code-yeongyu/codex-ulw-execute-continuation",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"license": "MIT",
 			"bin": {
 				"omo-ulw-execute-continuation": "dist/cli.js"
@@ -264,7 +264,7 @@
 		},
 		"components/ulw-loop": {
 			"name": "@code-yeongyu/codex-ulw-loop",
-			"version": "5.0.0-beta.82",
+			"version": "5.0.0-beta.84",
 			"license": "MIT",
 			"bin": {
 				"omo-ulw-loop": "dist/cli.js",

package/packages/omo-codex/plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sisyphuslabs/omo-codex-plugin",
-  "version": "5.0.0-beta.82",
+  "version": "5.0.0-beta.84",
   "description": "Aggregate Codex plugin root for OMO components.",
   "type": "module",
   "packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/skills/browser/ATTRIBUTION.md

@@ -0,0 +1,25 @@
+# ATTRIBUTION / NOTICE
+
+This skill (`browser`, part of `@oh-my-opencode/shared-skills`) is project-original documentation.
+It drives a third-party tool that it does **not** redistribute.
+
+## BrowserSkill — driven, not vendored
+
+The attached engine this skill documents is **BrowserSkill** by Tencent.
+
+- Upstream: https://github.com/Tencent/BrowserSkill
+- License: MIT
+- What ships here: documentation and two local helper scripts, authored by this project.
+- What does NOT ship here: the `bsk` CLI, the daemon, the browser extension, or any upstream
+  source. The user installs those from upstream's own installer and from the Chrome Web Store /
+  Edge Add-ons listings. This package never bundles a browser binary or an extension payload.
+
+MIT permits redistribution; we simply have no reason to, because upstream publishes signed
+per-platform releases and store builds that stay current on their own.
+
+## Owned-engine references
+
+`references/owned-engine/` documents a *contract* for a code-driven browser — the escalation
+ladder, viewport pinning, reading the network instead of the DOM, overlay and cross-origin
+handling — not any particular package. The techniques are generic CDP practice. No third-party
+source is reproduced.

package/packages/omo-codex/plugin/skills/browser/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: browser
+description: "Drives a real browser: sites the user is already signed into, forms and clicks, JS-rendered pages, screenshots, web QA, extension popups, and a human handoff for login, CAPTCHA or OTP. Works through the BrowserSkill extension and its bsk CLI, inside the user's own browser, in a separate Agent Window. Use for any interactive browser task; not for a plain search or an unblocked static fetch."
+---
+
+# Browser
+
+Two engines live behind this skill. Choose before you act:
+
+| You need | Engine | Where |
+|---|---|---|
+| A site the user is signed into, a form, a click-through, a screenshot, web QA, an extension popup | **attached** — the user's own browser | this file |
+| A throwaway profile, bot-scoring evasion, a CAPTCHA, network interception, a QA flight trace, coordinate control | **owned** — a browser your code launches | [references/owned-engine/README.md](references/owned-engine/README.md) |
+| Text out of a URL, a 403 bypass, a platform that blocks fetchers | neither | the `ultimate-browsing` skill |
+
+**Attached is the default,** because it is the only engine carrying the user's logins and the only
+one where a human is a single command away. The owned engine is an opt-in local install, not part
+of this package.
+
+## Step 0 — prove the stack before you drive it
+
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs"
+```
+
+It reports one of four states and what to do next:
+
+| State | Meaning | Next |
+|---|---|---|
+| `ready` | CLI, daemon and a connected browser | start a session |
+| `no-extension` | CLI works, no browser is connected | give the user the store link the doctor printed, wait, re-run |
+| `no-cli` | `bsk` is not installed | `node "<skill-root>/scripts/browser-install.mjs"`, then re-run |
+| `no-browser-support` | the platform has no supported browser | say so and stop |
+
+**Never substitute another browser for a missing one.** A headless browser you launch yourself has
+none of the user's sessions, so every login turns into a ladder you should not be climbing. If the
+attached engine is unavailable, say which state you hit and ask the user.
+
+## The loop
+
+```bash
+bsk session start --json --no-focus --name "<task>"     # keep session_id
+bsk navigate https://example.com --session <id> --json
+bsk observe --session <id>                              # @eN refs live here
+bsk click @e1 --session <id> --json
+bsk screenshot --session <id> --out ./shot.png --json
+bsk session stop <id> --json                            # success AND failure
+```
+
+1. **Observe before every action.** `observe` returns a semantic tree whose `@eN` refs are reissued
+   on each call. Read a ref and use it in the same cycle; a ref from two calls ago points somewhere
+   else now.
+2. **Navigation and large DOM changes stale every ref.** Observe again rather than reusing.
+3. **Two identical failures mean change approach, not retry.** A third identical attempt is a defect.
+4. **Borrow a user tab explicitly** (`tab list --scope user`, `tab borrow <id>`, `tab return <id>`).
+   Borrowing prompts the user; never invent tab ids and never repeat a denied borrow.
+5. **Always stop the session,** on success and on failure. Stopping also returns borrowed tabs.
+
+Command semantics, the flags that behave differently than they read, and the failure table are in
+[references/commands.md](references/commands.md).
+
+## When a human is the only way through
+
+Login, CAPTCHA, OTP, a payment confirmation, a consent dialog:
+
+```bash
+bsk request-help --session <id> --prompt "<what you need done>" [--target @eN]
+```
+
+Then observe again. Respect a `cancelled` or `timed_out` answer; do not work around it by changing
+the extension's automation settings.
+
+## Rules
+
+- **Never read credentials through the page.** No `evaluate` that extracts a password, token, cookie
+  or recovery code. The value of this engine is that the browser is already signed in.
+- **Never clear cookies, cache or site data.** It is the user's real profile; clearing it logs them
+  out everywhere. No flow here needs it.
+- **`--no-focus` by default.** The browser belongs to someone who is probably using it.
+- **One short, named session per task,** always stopped.
+- Do not toggle the extension's automation settings, and do not restart the browser to fix a state.
+
+## More
+
+- [references/install.md](references/install.md) — installing the CLI and the extension, per OS
+- [references/commands.md](references/commands.md) — command semantics, refs, failure table
+- [references/remote.md](references/remote.md) — agent on one machine, browser on another
+- [references/recipes/1password.md](references/recipes/1password.md) — reading a vault the user has unlocked
+- [references/owned-engine/README.md](references/owned-engine/README.md) — the code-driven engine

package/packages/omo-codex/plugin/skills/browser/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "(OmO) browser"

package/packages/omo-codex/plugin/skills/browser/references/commands.md

@@ -0,0 +1,90 @@
+# Command semantics
+
+Everything here cost a failed attempt to learn. Read it before improvising.
+
+## Sessions
+
+```bash
+bsk session start --json --no-focus --name "<task>"   # keep session_id
+bsk session list
+bsk session stop <id> --json                          # positional id, not --session
+```
+
+Every session-scoped command needs `--session <id>`. `--no-focus` keeps the Agent Window from
+stealing focus; drop it only when the user is watching on purpose.
+
+## Reading
+
+| Command | Returns |
+|---|---|
+| `observe --session <id>` | semantic tree with `@eN` refs and perception probes — **the default read** |
+| `snapshot --session <id>` | static accessibility tree |
+| `get-html --session <id>` | exact markup, hidden metadata |
+| `screenshot --session <id> --out <path>` | PNG; add `--full-page` for a long capture |
+| `evaluate "<js>" --session <id> --json` | `{ok, value}` — **check `.ok`; exit code 0 does not mean the script succeeded** |
+| `console` / `network` | buffered log lines and responses |
+
+**Refs are reissued by every `observe` and `snapshot`.** Read a ref and act on it in the same
+cycle. A ref captured two calls ago silently addresses a different element — this is how a click
+lands on the neighbouring row.
+
+`observe --max-tokens <n>` bounds a large page. There is no default cap.
+
+## Acting
+
+| Need | Command |
+|---|---|
+| Click | `click @e3 --session <id>` |
+| Fill | `fill @e3 --value "text" --session <id>` |
+| Select | `select @e3 --value "<option value>" --session <id>` |
+| Key | `press Enter --ref @e3 --session <id>` |
+| Hover | `hover @e3 --session <id>` |
+| Scroll into view | `scroll-to @e3 --session <id>` |
+| Wheel | `wheel --delta-y 600 --session <id>` |
+| Focus / blur | `focus @e3` / `blur @e3` |
+| Upload / download | `upload --file <path>` / `download --out <path>` |
+
+Traps:
+
+- `select` takes the option's **value attribute**, not its visible label.
+- `fill` and `click` accept a CSS selector; **`press --ref` does not** — it answers
+  `ref_not_found` for a selector. `press` without `--ref` goes to the focused node.
+- A menu that a `click` opens can be toggled shut by that same click. `focus` then
+  `press Enter` opens it reliably.
+- Hover-only controls report `element not visible`: hover the trigger, observe, then act on the
+  revealed item's fresh ref. Markers like `[has-submenu]` and `[expanded]` identify triggers;
+  `observe --probe-hover` finds one when no marker does, at the cost of touching the live page.
+- The clipboard is unavailable in a window started `--no-focus` (no document focus), so read
+  values out of the DOM instead.
+
+## Borrowing a user tab
+
+```bash
+bsk tab list --scope user
+bsk tab borrow <tab-id>
+bsk tab return <tab-id>
+```
+
+Borrowing asks the user to confirm. Never invent a tab id, never repeat a denied borrow, and
+always return what you borrowed (`session stop` also returns them).
+
+## Failures
+
+| Symptom | Meaning | Response |
+|---|---|---|
+| `browsers: []` | extension not connected | ask the user to open the browser / enable the extension |
+| daemon missing | idle exit or reboot | none; the next call restarts it |
+| `cdp_failed: Cannot access a chrome-extension:// URL of different extension` | another extension injected a frame, so the debugger cannot attach to that tab | transient and page-specific; collapse the work into one `evaluate` and retry, or navigate away and back |
+| `permission_denied: element not visible` | hover-gated or clipped control | drive its menu instead |
+| `ref_not_found` | stale ref, or a selector passed to `press` | observe again; use a real ref |
+| version skew warning | CLI and extension disagree | `bsk update` after finishing sessions; the extension updates through its store |
+
+**Two identical failures select a different approach. A third identical attempt is a defect.**
+
+## Sandboxed hosts
+
+If the host kills background children after each command, the daemon cannot survive between calls.
+Set `BSK_AUTO_START=0`, share one `BSK_HOME` across every call, and start
+`bsk daemon start --foreground` in the host's persistent background task. Check readiness with
+`bsk status --json` in a separate call before continuing. Do not loop on launches, delete runtime
+files, or restart a daemon another task is using.

package/packages/omo-codex/plugin/skills/browser/references/install.md

@@ -0,0 +1,71 @@
+# Installing the attached engine
+
+Three pieces. The agent can install exactly one of them.
+
+| Piece | Channel | Automatable |
+|---|---|---|
+| `bsk` CLI + daemon | upstream installer, GitHub Releases | **yes** |
+| Browser extension | Chrome Web Store / Edge Add-ons | **no — a human clicks Install** |
+| Daemon process | auto-starts on any `bsk` call | nothing to do |
+
+## Supported
+
+| | |
+|---|---|
+| Operating systems | macOS (Apple Silicon and Intel), Linux (x64, ARM64), Windows x64 |
+| Browsers | Chrome, Microsoft Edge. Other Chromium browsers work where they accept store builds. |
+
+## 1. The CLI
+
+```bash
+node "<skill-root>/scripts/browser-install.mjs"
+```
+
+That wraps upstream's official installer:
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
+export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
+```
+
+The Unix installer cannot change its parent shell's `PATH`. A shell opened before the install may
+still miss it, so either re-export in each call or use the absolute path (`$HOME/.local/bin/bsk`,
+`bsk.exe` on Windows). Verify with `bsk --version`.
+
+## 2. The extension
+
+Give the user the listing for their browser and wait:
+
+- Chrome: https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi
+- Edge: https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg
+
+Then confirm it landed:
+
+```bash
+bsk status --json     # a non-empty "browsers" array means connected
+```
+
+An empty `browsers` list is not a failure to work around. Either the browser is closed or the
+extension is not enabled; say which and ask.
+
+## 3. Do not install upstream's skill
+
+Upstream ships its own agent skill through `bsk install-skill`. **Do not run it here.** This
+package already provides the skill, and upstream's copy installs under a different name into the
+user skill directory, which takes precedence over a shipped skill — two descriptions of the same
+CLI, one of them shadowing the one that knows about this package's recipes and helper scripts.
+
+## Diagnosing
+
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs"          # this package's view
+bsk doctor                                              # upstream's own checks
+bsk logs                                                # daemon log
+```
+
+The daemon exits about ten minutes after the last browser disconnects and is not a system service,
+so a reboot also stops it. Both heal on the next `bsk` call — no repair needed.

package/packages/omo-codex/plugin/skills/browser/references/owned-engine/README.md

@@ -0,0 +1,42 @@
+# The owned engine
+
+A browser **your code launches and owns**, driven over CDP, with its own profile. The opposite of
+the attached engine: no user logins, full control.
+
+**This package ships no such engine.** These documents describe the contract and the technique, so
+that a locally installed CDP library — or a script you write against one — is driven correctly.
+If no owned engine is installed, say so and stay on the attached engine.
+
+## When it is the right engine
+
+| Reason | Why the attached engine cannot |
+|---|---|
+| A throwaway or pinned synthetic profile | the attached engine is the user's real profile |
+| Bot-scoring or fingerprint evasion | you do not get to configure the user's browser |
+| Solving a challenge widget programmatically | needs coordinate control and OCR |
+| Reading the network instead of the DOM | needs request interception on your own target |
+| A QA flight trace (steps, HAR, screenshots) | recording someone's real session is not acceptable |
+
+For anything that needs the user's login, the attached engine wins. For extracting text from a
+blocked URL, neither: use the `ultimate-browsing` skill.
+
+## What an owned engine must give you
+
+1. A transport that opens no listening port (launch over a pipe), or an explicit local CDP endpoint.
+2. An accessibility snapshot with stable in-page refs, and a **compact** form that drops the ref
+   map before the tree reaches a model — on a real page that map is roughly half the bytes and the
+   client never reads it.
+3. Locators that resolve those refs in-page, including refs inside cross-origin frames.
+4. Coordinate input, for what locators cannot address.
+5. A dialog policy, so `alert` / `confirm` / `beforeunload` can never block a run.
+
+## Reference
+
+- [ladder.md](ladder.md) — the escalation ladder, viewport pinning, coordinate control, challenge widgets
+- [network.md](network.md) — read the network instead of the DOM; traces and request interception
+- [frames-and-humans.md](frames-and-humans.md) — cross-origin frames, overlays, dialogs, human handoff
+
+## Cleanup is paired
+
+Close the browser and remove the profile directory in the same `finally`. A profile left behind is
+a logged-in browser nobody is watching.

package/packages/omo-codex/plugin/skills/browser/references/owned-engine/frames-and-humans.md

@@ -0,0 +1,39 @@
+# Frames, overlays, dialogs, and the human
+
+## Cross-origin frames and shadow DOM
+
+A cross-origin iframe is a separate target with its own snapshot. Reconcile the child trees into
+the parent so one tree describes the whole page, and address child elements through the page-level
+ref — never by fetching a frame handle first. Shadow roots are traversed by the snapshot engine;
+they are not a special case for you.
+
+## Overlays that swallow clicks
+
+Two identical misses on an element that is clearly visible usually means something invisible sits
+on top: a consent banner, a modal backdrop, a sticky header, a full-viewport tracking layer.
+Describe the layers at the click point before you retry. Either the overlay is named — dismiss it
+and continue — or nothing is reported, which means the miss has another cause and you climb the
+ladder instead.
+
+## Dialogs never block
+
+`alert`, `confirm`, `prompt`, and `beforeunload` must be answered by a policy set when the
+browser is created, not by a listener you hope registers in time. Default to accepting
+(`confirm` true, `prompt` empty). A run that hangs on an unhandled dialog looks exactly like a
+hang with no cause, which is the most expensive kind to diagnose.
+
+## Device emulation
+
+Emulating a device is viewport plus user agent plus touch, applied together. Changing only the
+viewport produces a desktop page at a phone size, which is not what you are testing. Re-read the
+viewport after emulating, and re-pin coordinates.
+
+## Handing the page to a human
+
+When every rung fails on a login, a one-time code, or a challenge you cannot clear, the human is
+the fallback, not the failure. Bring the tab to the front, state plainly what needs doing, and
+wait on a **condition** — the URL changed, the element appeared — with a bounded timeout, rather
+than on a fixed delay.
+
+Respect the answer. A cancelled or timed-out handoff is a stop, and the correct response is to
+report which rung failed with what evidence. Working around the user's refusal is never correct.

package/packages/omo-codex/plugin/skills/browser/references/owned-engine/ladder.md

@@ -0,0 +1,59 @@
+# The escalation ladder
+
+**Two identical failures on the same target mean climb, not retry. A third identical attempt is a
+defect.** The failure itself selects the next rung; never pause to ask which.
+
+| Rung | Use | Climb when |
+|---|---|---|
+| 1. snapshot + locator(ref) | anything with a usable ref | the ref is absent, stale, obscured, or the click lands on the wrong node twice |
+| 1b. layer description | a blocking overlay explains two identical misses | no overlay is reported, or it is gone and the click still misses |
+| 2. coordinates | canvas, extension popups, custom controls, drag surfaces | the click misses, or the screenshot and the coordinates disagree |
+| 3. pin the viewport, redo rung 2 | coordinate drift after a resize, a DPI change, or a foreign tab | coordinates land correctly but the widget still refuses input |
+| 4. the challenge widget | a challenge is the blocker | it clears and the flow still stalls |
+| 5. read the browser log | a browser-level failure | the log names a cause outside the page |
+
+**Rung 5 ends in a written diagnosis, never a speculative code change.** A missing entitlement, a
+dead extension service worker, an unavailable authenticator — none of those is fixed by editing
+automation code.
+
+## Pin the viewport before trusting any coordinate
+
+Coordinate input acts in viewport pixels. When the render surface and the coordinate space
+disagree, every coordinate is off by the same constant and retrying just repeats the miss. Set the
+device metrics explicitly (width, height, `deviceScaleFactor`, and a matching viewport), re-read
+the page's viewport size, then take a **fresh** screenshot. Coordinates read off an unpinned
+screenshot are stale. Pin every page you act on, including tabs you did not open.
+
+## Refs
+
+- Refs die on every new snapshot. Pass a ref straight from the latest snapshot; never reuse one
+  across snapshots and never put one in a CSS selector.
+- Refs stay page-level. A child-frame ref still resolves through the page, so you never fetch a
+  frame handle to click inside an iframe.
+- Always compact a snapshot before sending it to a model.
+
+## Challenge widgets
+
+A challenge is an obstacle on the path, not a stop sign: clear it, confirm it cleared, continue.
+Three shapes, three techniques:
+
+- **Checkbox** (the common embedded widgets): the control lives in a nested frame, so address it
+  by viewport coordinates.
+- **Slider / puzzle**: drag along a path with enough intermediate steps that the motion reads as
+  human. Raise the step count before you change the endpoints.
+- **Text or number**: OCR the region. On macOS the system vision framework is the cheapest
+  accurate option; elsewhere pass your own OCR function or a vision model.
+- **Image grid**: annotate a screenshot, then click per cell.
+
+**Bounds measured against an unpinned viewport are wrong by a constant offset.** If clicks have
+been landing wrong, drop to rung 3 first, then re-read the bounds.
+
+Verify with a fresh snapshot that the challenge is gone. Verification is part of the action, not a
+separate optimistic assumption.
+
+## Delegating the pixel loop
+
+Coordinate work and challenge solving are iterative: screenshot, reason, act, verify. When that
+loop would consume your own context, delegate the blocked page to a subagent armed with these
+references and have it return the post-solve state. Drive it yourself when the flow is short or
+the state is already in your hands.