lazycodex-ai 5.0.0-beta.86 → 5.0.0-beta.87

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

@@ -1,12 +1,12 @@
 {
 	"name": "@sisyphuslabs/omo-codex-plugin",
-	"version": "5.0.0-beta.86",
+	"version": "5.0.0-beta.87",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@sisyphuslabs/omo-codex-plugin",
-			"version": "5.0.0-beta.86",
+			"version": "5.0.0-beta.87",
 			"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.86",
+			"version": "5.0.0-beta.87",
 			"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.86",
+			"version": "5.0.0-beta.87",
 			"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.86",
+			"version": "5.0.0-beta.87",
 			"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.86",
+			"version": "5.0.0-beta.87",
 			"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.86",
+			"version": "5.0.0-beta.87",
 			"license": "MIT",
 			"dependencies": {
 				"picomatch": "^4.0.7"
@@ -194,7 +194,7 @@
 		},
 		"components/teammode": {
 			"name": "@sisyphuslabs/codex-teammode",
-			"version": "5.0.0-beta.86",
+			"version": "5.0.0-beta.87",
 			"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.86",
+			"version": "5.0.0-beta.87",
 			"license": "MIT",
 			"bin": {
 				"omo-telemetry": "dist/cli.js"
@@ -227,7 +227,7 @@
 		},
 		"components/ultrawork": {
 			"name": "@code-yeongyu/codex-ultrawork",
-			"version": "5.0.0-beta.86",
+			"version": "5.0.0-beta.87",
 			"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.86",
+			"version": "5.0.0-beta.87",
 			"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.86",
+			"version": "5.0.0-beta.87",
 			"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.86",
+  "version": "5.0.0-beta.87",
   "description": "Aggregate Codex plugin root for OMO components.",
   "type": "module",
   "packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/scripts/materialize-shared-upstreams.mjs

@@ -6,8 +6,10 @@ import { isCliEntry } from "./entry-guard.mjs";
 
 const pluginScriptsDir = dirname(fileURLToPath(import.meta.url));
 const repoRoot = join(pluginScriptsDir, "..", "..", "..", "..");
-const sharedSkillsScripts = join(repoRoot, "packages", "shared-skills", "scripts");
+const sharedSkillsRoot = join(repoRoot, "packages", "shared-skills");
+const sharedSkillsScripts = join(sharedSkillsRoot, "scripts");
 const materializeScript = join(sharedSkillsScripts, "materialize-frontend-refs.mjs");
+const stageOmowrightScript = join(sharedSkillsRoot, "stage-omowright-runtime.mjs");
 
 const upstreamPaths = [
 	"packages/shared-skills/upstreams/open-design",
@@ -34,7 +36,11 @@ function initSubmodules({ strict }) {
 export async function materializeSharedUpstreams({ strict }) {
 	initSubmodules({ strict });
 	const { materializeFrontendRefs } = await import(pathToFileURL(materializeScript).href);
-	return materializeFrontendRefs({ strict });
+	const result = await materializeFrontendRefs({ strict });
+	const { stageOmowrightRuntime } = await import(pathToFileURL(stageOmowrightScript).href);
+	const omowright = await stageOmowrightRuntime();
+	process.stdout.write(`[materialize] staged omowright ${omowright.version} into the browser skill\n`);
+	return result;
 }
 
 if (isCliEntry(import.meta.url)) {

package/packages/omo-codex/plugin/scripts/sync-skills.mjs

@@ -183,7 +183,7 @@ export const ulwExecuteOriginalCompletion = [
 	"4. Print an `ORCHESTRATION COMPLETE` block with the plan path, verification commands, artifacts, and cleanup receipts.",
 ].join("\n");
 export const ulwExecuteOriginalHardRule = [
-	"- No production change before a failing-first proof exists (unit test at a seam, otherwise the failing Manual-QA scenario), and no change to existing behavior before a baseline characterization test pins the current behavior and passes on the unchanged code.",
+	"- No production change before the tests covering that behavior were read and a bug's reproduction captured; existing tests are green on the unchanged code first, and one that contradicts the intent is a FINDING, never edited green.",
 	"- No `--dry-run` as completion evidence.",
 	"- No tests-only completion claim. A Manual-QA artifact is required.",
 	"- **NO DIRECT IMPLEMENTATION BY THE ORCHESTRATOR.** Root NEVER edits product files, writes tests, or runs QA itself — a spawned worker does.",
@@ -203,7 +203,7 @@ const ulwExecuteCodexCompletion = [
 	"6. Print an `ORCHESTRATION COMPLETE` block with the plan path, verification commands, artifacts, and cleanup receipts.",
 ].join("\n");
 const ulwExecuteCodexHardRule = [
-	"- No production change before a failing-first proof exists (unit test at a seam, otherwise the failing Manual-QA scenario), and no change to existing behavior before a baseline characterization test pins the current behavior and passes on the unchanged code.",
+	"- No production change before the tests covering that behavior were read and a bug's reproduction captured; existing tests are green on the unchanged code first, and one that contradicts the intent is a FINDING, never edited green.",
 	"- No `--dry-run` as completion evidence.",
 	"- No tests-only completion claim. A Manual-QA artifact is required.",
 	"- **NO DIRECT IMPLEMENTATION BY THE ORCHESTRATOR.** Root NEVER edits product files, writes tests, or runs QA itself — a spawned worker does.",

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

@@ -1,25 +1,37 @@
 # 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.
+This skill (`browser`, part of `@oh-my-opencode/shared-skills`) is project-original documentation
+plus a staged copy of one library it drives.
+
+## omowright — bundled
+
+Both engines this skill documents are provided by **omowright**.
+
+- Upstream: the `omowright` repository on GitHub, pinned by commit in the root `package.json`
+  devDependency.
+- License: MIT
+- What ships here: `runtime/omowright/index.js` (the library bundled into one ESM file, including
+  its `ws` and `zod` dependencies) and `runtime/omowright/page-bundle.js` (the in-page snapshot
+  script it reads at import time), staged at build time by
+  `packages/shared-skills/stage-omowright-runtime.mjs` from the pinned root devDependency, with a
+  `manifest.json` recording the version and file digests. The repository holds no copy; the
+  staged files are gitignored and packed through the sibling `.npmignore`.
+- omowright's own license notice is preserved inside the bundled file.
 
 ## BrowserSkill — driven, not vendored
 
-The attached engine this skill documents is **BrowserSkill** by Tencent.
+The attached engine reaches the user's browser through **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.
+- What ships here: nothing of upstream's. omowright speaks the daemon's IPC protocol; the user
+  installs the `bsk` CLI from upstream's own installer (run by `scripts/browser-install.mjs`) and
+  the extension from the Chrome Web Store / Edge Add-ons listings (registered by the same script
+  through Chrome's external-extension mechanism). This package never bundles a browser binary or
+  an extension payload.
 
 ## 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.
+`references/owned-engine/` summarizes omowright's own skill and presets (escalation ladder,
+network-first reading, frames, dialogs, human handoff) as routing text; the library's repository
+is the authoritative treatment.

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

@@ -1,89 +1,102 @@
 ---
 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."
+description: "Drives a real browser through the omowright library from the js eval kernel: sites the user is already signed into, forms and clicks, JS-rendered pages, screenshots, web QA, extension popups, a human handoff for login, CAPTCHA or OTP, and a browser you own for scraping, bot-scored targets, network capture and QA traces. 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:
+One library, two engines. omowright ships inside this skill; choose the engine before you act:
 
-| You need | Engine | Where |
+| You need | Engine | Entry point |
 |---|---|---|
-| 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) |
+| A site the user is signed into, their open tabs, a form, a click-through, a screenshot, web QA, an extension popup | **attached** — the user's own browser through BrowserSkill | `connectBrowserSkill()` |
+| A throwaway profile, bot-scoring evasion, a CAPTCHA, network interception, a QA flight trace, coordinate control, headless runs | **owned** — a browser your code launches | `connectPipe()` / `connectCloakProfile()` — [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.
+one where a human is a single call away. Never substitute one engine for the other silently: if
+the attached engine is not set up, run the onboarding script and tell the user its one remaining
+step.
 
-## Step 0 — prove the stack before you drive it
+## Step 0 — load omowright and prove the stack
 
-```bash
-node "<skill-root>/scripts/browser-doctor.mjs"
+```js
+const { loadOmowright } = await import("<skill-root>/scripts/omowright.mjs")
+const { omowright } = await loadOmowright()          // { connectBrowserSkill, bskSnapshot, connectPipe, ... }
 ```
 
-It reports one of four states and what to do next:
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs" --json
+```
 
 | 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
+| `no-cli` / `no-daemon` / `no-extension` | something is missing | `node "<skill-root>/scripts/browser-install.mjs"` prepares everything it can, then prints the **single** step only the user can do (relaunch the browser and click **Enable**); relay it verbatim, wait, re-run the doctor |
+| `no-browser-support` | no Chromium-family profile on this machine | say so and stop |
+
+**Never launch a headless browser because the attached one is missing.** It has none of the
+user's sessions, so every login turns into a ladder you should not be climbing. Say which state
+you hit and ask.
+
+## The loop (attached)
+
+```js
+const session = await omowright.connectBrowserSkill({ name: "<task>", focused: false })
+try {
+  await session.navigate("https://example.com/", { waitUntil: "load" })
+  const { tree, refs, css } = await omowright.bskSnapshot(session, { interactive: true })  // OmOWright tree + refs, no trace in the page
+  await session.click({ selector: css.e3 })                                                 // css[ref] is null inside shadow roots:
+  const vom = await session.observe({ maxTokens: 4000 })                                    //   then read the daemon's own tree ...
+  await session.click("@e7")                                                                //   ... and click its @eN ref
+  await session.fill(css.e5, "hello")
+  await session.press("Enter")
+  await session.waitForNavigation({ waitUntil: "load" })
+  const shot = await session.screenshot()                                                   // { buffer, width, height, captureId }
+} finally {
+  await session.stop()                                                                      // success AND failure; returns borrowed tabs
+}
 ```
 
-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.
+1. **Read before every action.** `bskSnapshot` refs and `observe` `@eN` refs are reissued on each
+   call; use a ref in the same cycle you read it.
+2. **Navigation and large DOM changes stale every ref.** Read 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>`).
+4. **Borrow a user tab explicitly** (`tabList({ scope: "user" })`, `tabBorrow(id)`, `tabReturn(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.
+5. **Always `stop()` the session,** on success and on failure.
 
-Command semantics, the flags that behave differently than they read, and the failure table are in
-[references/commands.md](references/commands.md).
+Every method, its options, and the failure codes 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]
+```js
+const outcome = await session.requestHelp({ prompt: "<what you need done>", targets: ["@e4"], timeoutMs: 300_000 })
 ```
 
-Then observe again. Respect a `cancelled` or `timed_out` answer; do not work around it by changing
-the extension's automation settings.
+Then read the page again. Respect a `cancelled` or `timed_out` outcome; 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 read credentials through the page.** No `evaluate` that extracts a password, token,
+  cookie or recovery code. The value of the attached 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.
+- **`focused: false` 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
+- **Bot-scored or WAF targets go to the owned engine.** The attached engine's daemon enables console
+  capture on every tab it drives, which is a known automation signal; CloakBrowser through
+  `connectCloakProfile()` is the stealth path.
+
+## Where the rest lives
+
+| Topic | Read |
+|---|---|
+| Session methods, targets, options, error codes | [references/commands.md](references/commands.md) |
+| Installing: CLI, daemon, extension, the one human step, blocklisted extension | [references/install.md](references/install.md) |
+| Agent on one machine, browser on another | [references/remote.md](references/remote.md) |
+| Owned engine: launch, snapshot ladder, network, frames, human handoff | [references/owned-engine/README.md](references/owned-engine/README.md) |
+| Reading a 1Password vault the user has unlocked | [references/recipes/1password.md](references/recipes/1password.md) |

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

@@ -1,90 +1,105 @@
-# Command semantics
+# Session methods
 
-Everything here cost a failed attempt to learn. Read it before improvising.
+`connectBrowserSkill()` returns a `BskSession`. Every method is one call on the BrowserSkill
+daemon's tool surface; options are the daemon's parameter names in camelCase.
 
 ## 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
+```js
+const session = await omowright.connectBrowserSkill({ name: "<task>", focused: false, browser: "<instance id>", width: 1200, height: 800 })
+session.sessionId            // four letters, e.g. "ckhg"
+session.browserInstanceId    // which connected browser owns the Agent Window
+await session.stop()         // ALWAYS, on success and failure
 ```
 
-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.
+`browser` is needed only when more than one browser is connected (`bskDoctor()` lists them).
+`focused: false` keeps the Agent Window from stealing focus; drop it only when the user is watching
+on purpose. Throws `BskRpcError` `no_browser_connected` when no extension is attached — that is a
+stop, not a cue to launch something else.
 
-## Reading
+## Targets
 
-| Command | Returns |
+| Form | Meaning |
 |---|---|
-| `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 |
+| `"@e3"` / `"e3"` | a ref from the last `observe()` / `snapshot()` |
+| `"#login > button"` | a CSS selector, resolved live |
+| `{ captureId, x, y }` | a point in a screenshot, from `screenshot()` |
+| `css.e3` from `bskSnapshot` | the light-DOM CSS path of an OmOWright ref (`null` inside shadow roots — use the daemon ref instead) |
 
-**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.
+## Reading
 
-`observe --max-tokens <n>` bounds a large page. There is no default cap.
+| Call | Returns |
+|---|---|
+| `bskSnapshot(session, { interactive, maxDepth })` | `{ tree, refs, css }` — the OmOWright accessibility tree with refs, computed in the page **without** leaving a global or touching the DOM |
+| `session.observe({ maxTokens, cursor, probeHover })` | the daemon's semantic tree (`@vom`) with `@eN` refs, layers and hover probes — **the default read for shadow DOM and iframes** |
+| `session.snapshot({ maxDepth, maxTokens })` | the daemon's plain accessibility tree |
+| `session.getHtml({ ref, maxBytes })` | exact markup |
+| `session.screenshot({ ref })` / `screenshot({ fullPage: true })` | `{ buffer, width, height, captureId }`; full-page captures stream back in chunks |
+| `session.evaluate(expression, { awaitPromise, timeoutMs })` | `{ ok, value, error }` — **check `.ok`**; a resolved promise does not mean the script succeeded |
+| `session.console({ since })` / `session.network({ since })` | buffered console entries / request metadata (no bodies) |
+
+**Refs are reissued by every read.** 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.
 
 ## Acting
 
-| Need | Command |
+| Need | Call |
 |---|---|
-| 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>` |
+| Click | `session.click(target, { button, clickCount, modifiers })` |
+| Fill | `session.fill(target, value, { clearBefore })` |
+| Select | `session.select(target, ["<option value>"])` |
+| Key | `session.press("Enter", { target, modifiers, holdMs })` |
+| Hover | `session.hover(target, { settleMs })` |
+| Scroll into view | `session.scrollTo(target)` |
+| Wheel | `session.wheel({ deltaY: 600, target })` |
+| Focus / blur | `session.focus(target)` / `session.blur(target)` |
+| Navigate | `session.navigate(url, { waitUntil: "load" \| "domcontentloaded" \| "networkidle" \| "commit", timeoutMs })`, `back()`, `forward()`, `reload({ hard })`, `waitForNavigation()` |
+| Window | `session.resize(width, height)`, `session.emulate({ overrides: { width, mobile } })` |
 
 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>
+- `press` without `target` goes to the focused node; `press` with a CSS selector is fine, but a
+  daemon ref must come from the current read.
+- 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, read again, then act on the
+  revealed item's fresh ref. `observe({ probeHover: true })` finds one when no marker does, at the
+  cost of touching the live page.
+- The clipboard is unavailable in a window started `focused: false`, so read values out of the DOM.
+
+## Tabs
+
+```js
+const { tabs } = await session.tabList({ scope: "user" })   // "user" | "agent" | "all"
+await session.tabBorrow(tabId)                                // the user confirms in the browser (60 s)
+await session.tabReturn(tabId)                                // stop() returns anything still borrowed
+await session.tabCreate({ url }); await session.tabSelect(id); await session.tabClose(id)
+```
+
+Never invent tab ids and never repeat a denied borrow.
+
+## Humans
+
+```js
+const { outcome } = await session.requestHelp({ prompt, title, targets: ["@e4"], completionCriteria, timeoutMs })
+// outcome: "completed" | "continued" | "cancelled" | "timed_out" | "navigated" | "disabled"
 ```
 
-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).
+## Errors
 
-## Failures
+Every refusal is a `BskRpcError` with the daemon's own `code`:
 
-| Symptom | Meaning | Response |
+| `code` | Meaning | Do |
 |---|---|---|
-| `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.
+| `no_browser_connected` | no extension attached | run the onboarding script, relay the human step, wait |
+| `not_found` | stale ref or unknown session | read again; if the session is gone, start a new one |
+| `invalid_params` | wrong option shape | fix the call, do not retry as-is |
+| `permission_denied` | `evaluate` on a tab outside the Agent Window, or a denied borrow | stop; the user said no |
+| `timeout` | the tool did not finish in its budget | read the page state before retrying once |
+| `user_aborted` | the user pressed Stop in the browser | stop the task and report |
+| `cdp_failed` | the page cannot be attached (restricted URL, DevTools open) | say which page and why |
+
+Long calls can be cancelled: `const h = session.client.callWithHandle("tool.navigate", {...})`
+then `await session.client.cancel(h.rpcId)`.