@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/agent-browser/SKILL.md

@@ -0,0 +1,698 @@
+---
+name: agent-browser
+description: "This skill should be used when automating browser interactions via Vercel's agent-browser CLI. It handles web page navigation, form filling, screenshots, and data scraping using ref-based element selection."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# agent-browser: CLI Browser Automation
+
+Vercel's headless browser automation CLI designed for AI agents. Uses ref-based selection (@e1, @e2) from accessibility snapshots.
+
+## Setup Check
+
+```bash
+# Check installation
+command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED - run: npm install --prefix ~/.local -g agent-browser@0.22.3 && agent-browser install"
+```
+
+### Install if needed
+
+```bash
+npm install --prefix ~/.local -g agent-browser@0.22.3
+agent-browser install  # Downloads Chrome for Testing (~300MB)
+# On Linux if system deps missing:
+# agent-browser install --with-deps
+```
+
+### Required launch flag on Linux: `--no-sandbox`
+
+On Ubuntu 23.10+, containers, and VMs, the host's AppArmor policy restricts
+unprivileged user namespaces, so Chrome for Testing cannot initialize its zygote
+sandbox and the browser fails to launch. Export the no-sandbox flag once per
+session **before the first `agent-browser` command** — the daemon reads it at
+launch and every later command in the session inherits it:
+
+```bash
+export AGENT_BROWSER_ARGS="--no-sandbox"
+```
+
+Inline alternative (first `open` only): `agent-browser open <url> --args "--no-sandbox"`.
+This confines `--no-sandbox` to agent-browser's own ephemeral automation Chrome —
+the same posture Playwright already runs here; it does not touch your real browser.
+
+### Troubleshooting: Chrome fails to launch / `open` hangs (no usable sandbox)
+
+Symptom on pinned 0.22.3: `agent-browser open <url>` **hangs indefinitely** with
+zero stdout/stderr (even `--debug` prints nothing). On newer versions it fails
+fast with `No usable sandbox! ... unprivileged user namespaces ... AppArmor` and a
+`--args "--no-sandbox"` hint. Both are the same cause.
+
+1. Set the launch flag: `export AGENT_BROWSER_ARGS="--no-sandbox"` (see above).
+2. If it still fails, a stale/wedged daemon may be holding the socket. Clear it:
+   `pkill -f agent-browser-linux-x64; rm -rf /tmp/agent-browser/* "/run/user/$(id -u)/agent-browser/"*`
+   then retry. (Never kill `playwright-mcp` processes — those are a separate stack.)
+   The commonest cause is a daemon whose worktree was REAPED: resolve each match's
+   `/proc/<pid>/cwd` and expect one ending `(deleted)`, often weeks old and inherited
+   by every later session on the machine. Such a daemon does not answer and **survives
+   SIGTERM** — it needs `kill -9`. Nothing in the CLI's error names any of this; the
+   only symptom is `Resource temporarily unavailable (os error 11)` (#7947).
+3. Verify: `AGENT_BROWSER_ARGS="--no-sandbox" timeout 45 agent-browser open https://example.com --headless` → exit 0 + a `✓` line.
+
+### Troubleshooting: Playwright MCP backend closed between calls
+
+This is the **other** browser-automation symptom #6605 reported (the "MCP tools
+de-register" half) — distinct from the agent-browser CLI hang above, and covering the
+Playwright **MCP** stack. If a `mcp__plugin_soleur_playwright__browser_*` call
+(or the same call on a host's own `mcp__playwright__*` registration) returns
+`browserBackend.callTool: Target page, context or browser has been closed`, the browser
+backend dropped while the MCP server itself stayed registered (a lifecycle event, not a
+dead tool).
+
+Two known causes, check in this order. **(1) A hook killing the browser at the end of
+a turn.** Older plugin versions registered `browser-cleanup-hook.sh` on `Stop`, which
+fires every turn and SIGTERMed every Playwright Chrome of the user (ADR-271; method in
+`knowledge-base/project/learnings/bug-fixes/2026-10-04-stop-hook-killed-live-playwright-chrome-heartbeat-theory-refuted.md`).
+Tell-tale: the next call after a turn boundary fails, and the session transcript
+(`~/.claude/projects/<slug>/<session>.jsonl`) carries a `hook_success` attachment whose
+`hookEvent` is `Stop` and whose `command` matches `browser-cleanup`; the kill text
+`Browser cleanup: killed N orphaned Playwright Chrome process(es)` is in
+`attachment.stderr`, not `stdout`. The hook is removed from the repository, but a
+session may run the installed plugin copy, which keeps it until the plugin is updated:
+
+1. Check (read-only): take `installPath` for `soleur@soleur` from
+   `~/.claude/plugins/installed_plugins.json`, then run
+   `jq -c '.hooks.Stop[].hooks[].command' <installPath>/hooks/hooks.json`. A line naming
+   `browser-cleanup-hook.sh` means the installed copy still kills the browser.
+2. Update: `claude plugin update soleur@soleur` (or the id `claude plugin list` prints).
+   The installed version is a git sha, so the update carries the fix only once the release
+   that removes the hook has been published; before that it changes nothing.
+3. Restart: the USER restarts Claude Code (an agent cannot restart its own host). A `/mcp`
+   reconnect reuses the cached `.mcp.json` command and does not reload hooks.
+4. Until then, complete a whole browser flow inside ONE turn. Interim and untested: the
+   user can `chmod -x` the installed copy's `hooks/browser-cleanup-hook.sh`, which should
+   make that hook fail without blocking until the next update overwrites it.
+
+**A second killer survives the update: a session in ANOTHER checkout still on the old
+`.mcp.json` launch string.** That string contains `pkill -9 -f` and, on every start or
+`/mcp` reconnect of that session, kills the proxy, server and Chrome of EVERY slot of
+a session on the new string. Read-only check: `for w in $(git worktree list --porcelain |
+sed -n 's/^worktree //p'); do grep -aq pkill "$w/.mcp.json" && echo "$w"; done` prints each
+checkout still carrying it. Bring those checkouts to this `.mcp.json` and restart their
+sessions (the string a running session loaded cannot be changed from here).
+
+**A login that should persist is missing in the repo registration:** that session was
+given a numbered slot or a `-p<pid>` directory. Run `grep -a 'was skipped:' "$(ls -t
+~/.cache/claude-cli-nodejs/"$(pwd | sed 's/[^A-Za-z0-9]/-/g')"/mcp-logs-playwright/*.jsonl |
+head -1)"` from the project directory: the repo registration logs under `mcp-logs-playwright`
+in the directory named after the working directory with every character that is not a
+letter or digit replaced by a dash (`/.worktrees/` becomes `--worktrees-`). The plugin
+registration's `mcp-logs-plugin-soleur-playwright` never runs the slot script and never
+prints that line. The line names why slot 0 (the persistent profile) was not used, and the
+remedy depends on the reason:
+
+- "its lock is held by another live launch": the lease is held by the other session's
+  proxy process, and `browser_close` does not release it (it closes Chrome, not the
+  proxy). End that session, or disconnect its Playwright MCP server, then reconnect.
+- "its SingletonLock names a live Chrome": that Chrome must exit, for example
+  `browser_close` in the session that owns it, then reconnect.
+- A reason naming another HOST (a renamed host or a copied home directory) is
+  cleared by hand: after confirming no Chrome of yours uses that profile, `rm
+  <slot-0 dir>/Singleton*`, which removes only the stale lock files and no login.
+
+A search for another killer must cover every enabled plugin's `hooks.json` (the installed
+copy too), not only `settings.json`. The server's ping heartbeat is not a cause on stdio
+(ADR-271). **(2) A Wayland/Vulkan GPU crash** — already diagnosed and
+remediated in `.claude/playwright-mcp.config.json` (forces the X11/XWayland backend
+and disables the GPU); see `knowledge-base/project/learnings/workflow-patterns/2026-06-17-playwright-mcp-wayland-vulkan-launch-crash.md`.
+
+**Whatever the cause**, recycle the context and re-navigate (the pattern in
+`plugins/soleur/skills/qa/SKILL.md`: `browser_close` — safe even if already closed —
+then `browser_navigate`); the backend restarts. Note that snapshot `ref=` handles do
+**not** survive the restart; target elements by name/selector
+(`button:has-text("Save")`, `input[aria-label="..."]`) across it. A separate
+`"these deferred tools are no longer available"` notice means the MCP server
+disconnected (reload via `ToolSearch`) — a different failure from the backend-close.
+
+### Troubleshooting: version mismatch
+
+If you see "Version mismatch between agent-browser (expects 1200) and installed Playwright (1208)":
+
+1. Check which binary is running: `which agent-browser && agent-browser --version`
+2. If it resolves to `/usr/bin/agent-browser` (version 0.5.0), a stale system install is shadowing the correct version
+3. Fix: `sudo npm uninstall -g agent-browser` to remove the system binary
+4. Verify: `which agent-browser` should now resolve to `~/.local/bin/agent-browser` (0.22.3)
+
+## Core Workflow
+
+**The snapshot + ref pattern is optimal for LLMs:**
+
+1. **Navigate** to URL
+2. **Snapshot** to get interactive elements with refs
+3. **Interact** using refs (@e1, @e2, etc.)
+4. **Re-snapshot** after navigation or DOM changes
+
+**Playwright MCP flow: when the flow is finished, call `browser_close`.** Nothing reaps the
+browser at turn end (ADR-271): it lives as long as the session that launched it, and a
+logged-in window left open after a credential hand-off stays logged in. For the
+`agent-browser` CLI the same duty is `agent-browser close`.
+
+### Preflight: verify the plugin install before any snapshot
+
+The redactor is reached through `${CLAUDE_PLUGIN_ROOT}`. An ambient value pointing at a
+directory that is not a Soleur install would resolve to a path that does not exist — or, worse,
+to one an attacker chose. Verify plugin IDENTITY and halt if it does not hold (ADR-179 decision 2);
+a `test -f` on the script alone is a shape check and was measured bypassable.
+
+```bash
+[ -f "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" ] \
+  && grep -q '"name"[[:space:]]*:[[:space:]]*"soleur"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" \
+  || { echo "SOLEUR_SNAPSHOT_HALT reason=plugin-root-unverified root=[${CLAUDE_PLUGIN_ROOT}]" >&2
+       echo "  Cannot locate the snapshot redactor, so no accessibility snapshot may be taken here." >&2
+       echo "  Root EMPTY: no Soleur plugin is loaded in this session. Install it and start a NEW session." >&2
+       echo "  Root set but wrong: a repo checkout is not an install. Run 'claude plugin update soleur@soleur-marketplace' (or the id 'claude plugin list' prints, if you added the repository directly), then RESTART Claude Code." >&2
+       echo "  Nothing has been captured yet, so nothing has leaked." >&2
+       exit 2; }
+```
+
+```bash
+# Step 1: Open URL
+agent-browser open https://example.com
+
+# Step 2: Get interactive elements with refs
+agent-browser snapshot -i --json 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+
+# Step 3: Interact using refs
+agent-browser click @e1
+agent-browser fill @e2 "search query"
+
+# Step 4: Re-snapshot after changes
+agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+```
+
+## Key Commands
+
+### Navigation
+
+```bash
+agent-browser open <url>       # Navigate to URL
+agent-browser back             # Go back
+agent-browser forward          # Go forward
+agent-browser reload           # Reload page
+agent-browser close            # Close browser
+```
+
+### Snapshots (Essential for AI)
+
+```bash
+agent-browser snapshot 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"  # Full accessibility tree
+agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"  # Interactive elements only (recommended)
+agent-browser snapshot -i --json 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"  # JSON output for parsing
+agent-browser snapshot -c 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"  # Compact (remove empty elements)
+agent-browser snapshot -d 3 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"  # Limit depth
+```
+
+### Interactions
+
+```bash
+agent-browser click @e1                    # Click element
+agent-browser dblclick @e1                 # Double-click
+agent-browser fill @e1 "text"              # Clear and fill input
+agent-browser type @e1 "text"              # Type without clearing
+agent-browser press Enter                  # Press key
+agent-browser hover @e1                    # Hover element
+agent-browser check @e1                    # Check checkbox
+agent-browser uncheck @e1                  # Uncheck checkbox
+agent-browser select @e1 "option"          # Select dropdown option
+agent-browser scroll down 500              # Scroll (up/down/left/right)
+agent-browser scrollintoview @e1           # Scroll element into view
+```
+
+### Get Information
+
+```bash
+agent-browser get text @e1          # Get element text
+agent-browser get html @e1          # Get element HTML
+agent-browser get value @e1         # Get input value
+agent-browser get attr href @e1     # Get attribute
+agent-browser get title             # Get page title
+agent-browser get url               # Get current URL
+agent-browser get count "button"    # Count matching elements
+```
+
+### Screenshots & PDFs
+
+```bash
+agent-browser screenshot                      # Viewport screenshot
+agent-browser screenshot --full               # Full page
+agent-browser screenshot output.png           # Save to file
+agent-browser screenshot --full output.png    # Full page to file
+agent-browser pdf output.pdf                  # Save as PDF
+```
+
+### Wait
+
+```bash
+agent-browser wait @e1              # Wait for element
+agent-browser wait 2000             # Wait milliseconds
+agent-browser wait "text"           # Wait for text to appear
+```
+
+## Semantic Locators (Alternative to Refs)
+
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign up" click
+agent-browser find label "Email" fill "user@example.com"
+agent-browser find placeholder "Search..." fill "query"
+```
+
+## Sessions (Parallel Browsers)
+
+```bash
+# Run multiple independent browser sessions
+agent-browser --session-name browser1 open https://site1.com
+agent-browser --session-name browser2 open https://site2.com
+
+# List saved states
+agent-browser state list
+```
+
+## Examples
+
+### Credential safety on a login or credential page
+
+An accessibility snapshot serializes the **value** of input fields. A value the
+agent never typed — a password manager's autofill, a static `value=`, a JS
+assignment, or a freshly-minted credential shown in a panel — is rendered into
+the transcript and into any snapshot file written to disk. Nothing about the
+call looks credential-adjacent, which is why this is a gate and not advice: the
+PreToolUse hook `browser-snapshot-credential-guard.sh` denies an unrouted
+snapshot before it runs (#7947).
+
+**Route every snapshot on a credential-bearing page through the redactor**,
+[redact-a11y-snapshot.py](./scripts/redact-a11y-snapshot.py):
+
+```bash
+agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+```
+
+Stating the ceiling first, because the rule is otherwise read as "piping makes a
+snapshot safe": the redactor is **defense-in-depth on one sink**, not a control
+that makes snapshotting a credential page safe. It keys on the node's accessible
+name, because neither surface serializes the input's `type` — measured, see the
+[Phase 0.1 record](../../../../knowledge-base/project/specs/feat-one-shot-7946-7947-sentry-org-token-and-snapshot-redaction/phase-0-measurement.md).
+It therefore cannot see a localised field name, a credential outside a
+text-input role, or a value split across segmented inputs.
+
+**A screenshot is safe for a `type=password` field** — the browser renders it as
+dots — **and is NOT safe for a generated-credential panel.** Measured: a readonly
+`type=text` box named "Token" renders its value in clear in the screenshot
+exactly as it does in the snapshot. On a page displaying a credential, capture
+neither: read the value with `agent-browser get value <sel>` into a file, use it,
+and shred the file.
+
+**When the credential is TEXT, not an input, `get value` finds nothing — use
+`eval`, and never let its output reach the transcript.** Measured on the Anthropic
+Console key panel (#8505): the fresh key is leaf text, zero `<input>` holds it.
+Redirect `eval`'s stdout straight into a file created mode 0600, then print only
+its length and prefix. Run both lines in ONE Bash call — `umask` does not carry
+across calls — and note the file holds a JSON *string* (quoted); unwrap it with
+`json.load`, never by printing it:
+
+```bash
+umask 077
+agent-browser eval "(()=>{const m=document.body.innerText.match(/sk-ant-[A-Za-z0-9_-]{20,}/);return m?m[0]:''})()" > "${SCRATCH:?}/key.json"
+python3 -c 'import json,sys; v=json.load(open(sys.argv[1])); print(len(v), v.startswith("sk-ant-"))' "${SCRATCH:?}/key.json"
+```
+
+Neither redactor is a backstop here: `redact-a11y-snapshot.py` and the MCP proxy
+key on an accessibility node's NAME, so a raw key string returned by `eval` or by
+the MCP's `browser_run_code_unsafe` passes both unredacted. Return a length or a
+fixed code from any in-page script, never the value, and catch every error inside
+the script so a thrown message cannot carry the value out either.
+
+### Login Flow
+
+`fill @e2` needs a ref, and a ref comes from a snapshot — so the login step
+snapshots **through the redactor** rather than not at all.
+
+```bash
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+# Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Sign in" [ref=e3]
+agent-browser fill @e1 "user@example.com"
+# Pass the secret by env indirection -- never a literal, which lands in the
+# transcript as the tool-call argument before any snapshot happens.
+agent-browser fill @e2 "$APP_PASSWORD"
+agent-browser click @e3
+agent-browser wait 2000
+# Verify logged in -- still through the redactor: the password manager may have
+# refilled the field on the post-login page.
+agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+```
+
+### Search and Extract
+
+```bash
+agent-browser open https://news.ycombinator.com
+agent-browser snapshot -i --json 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+# Parse JSON to find story links
+agent-browser get text @e12  # Get headline text
+agent-browser click @e12     # Click to open story
+```
+
+### Form Filling
+
+```bash
+agent-browser open https://forms.example.com
+agent-browser snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+agent-browser fill @e1 "John Doe"
+agent-browser fill @e2 "john@example.com"
+agent-browser select @e3 "United States"
+agent-browser check @e4  # Agree to terms
+agent-browser click @e5  # Submit button
+agent-browser screenshot confirmation.png
+```
+
+### Debug Mode
+
+```bash
+# Run with visible browser window
+agent-browser --headed open https://example.com
+agent-browser --headed snapshot -i 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+agent-browser --headed click @e1
+```
+
+## JSON Output
+
+Add `--json` for structured output:
+
+```bash
+agent-browser snapshot -i --json 2>&1 | python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"
+```
+
+Returns:
+
+```json
+{
+  "success": true,
+  "data": {
+    "refs": {
+      "e1": {"name": "Submit", "role": "button"},
+      "e2": {"name": "Email", "role": "textbox"}
+    },
+    "snapshot": "- button \"Submit\" [ref=e1]\n- textbox \"Email\" [ref=e2]"
+  }
+}
+```
+
+## vs Playwright MCP
+
+| Feature | agent-browser (CLI) | Playwright MCP |
+|---------|---------------------|----------------|
+| Interface | Bash commands | MCP tools |
+| Selection | Refs (@e1) | Refs (e1) |
+| Output | Text/JSON | Tool responses |
+| Parallel | Session names | Tabs |
+| Browser | Chrome for Testing | Chromium |
+| Runtime | Rust native | Node.js |
+| Best for | Quick automation | Tool integration |
+
+Use agent-browser when:
+
+- You prefer Bash-based workflows
+- You want simpler CLI commands
+- You need quick one-off automation
+
+Use Playwright MCP when:
+
+- You need deep MCP tool integration
+- You want tool-based responses
+- You're building complex automation
+
+### Wrapping the server
+
+**The plugin registers the wrapped server.** `plugins/soleur/.mcp.json`
+registers `playwright` with `python3` running
+`"${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/playwright-mcp-redact-proxy.py"`
+in front of `npx @playwright/mcp@0.0.78`, so on Claude Code its tools arrive as
+`mcp__plugin_soleur_playwright__*` — already wrapped, no customer
+configuration. The registration passes
+`--user-data-dir-name soleur-playwright-mcp-profile` and `--chromium-fallback`, so the wrapped browser
+runs on its own profile under `$XDG_CACHE_HOME` (default `~/.cache`), separate
+from any `playwright` registration the customer configured themselves. On a
+registration routed through the proxy, every `tools/call` result is rewritten
+through `redact-a11y-snapshot.py` at the stdio boundary — between the server's
+stdout and the client's stdin, before the model reads it — which is what
+"redacted in flight" means: a content rewrite, not encryption and not
+transport security. A registration not routed through it is not covered by
+anything at runtime (#7980). **The registration ships no config; its `env` block carries only
+`PLAYWRIGHT_MCP_PING_TIMEOUT_MS=0`, an inert guard on stdio that is not a fix for
+anything (ADR-271). The server runs upstream defaults: headed — a visible Chrome
+window opens when a tool drives the browser — on channel `chrome` (real Google
+Chrome), except that when no Google Chrome executable exists at
+`/opt/google/chrome/chrome` (Linux) or `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` (macOS)
+and the launch names no browser, `--chromium-fallback` makes the proxy append
+`--browser chromium --sandbox`, which Playwright maps to its bundled Chromium with the
+Chromium sandbox kept on, like real Chrome. If that sandbox cannot start on the host (no
+unprivileged user namespaces, an Ubuntu AppArmor restriction, running as root, a
+default-seccomp container), the first browser call fails with a sandbox error and no
+browser opens; the supported remedy is to install Google Chrome, never to disable the
+sandbox, which the proxy refuses in every spelling.** Headed is deliberate: the
+credential-handoff flows need an operator-visible window. On a display-less host
+the server still connects but browser tools fail to launch — see the playbook at
+the end of this section.
+
+**Preconditions.** The plugin server exists only where all of these hold: the
+session is Claude Code ≥2.1.139 with the soleur plugin installed; `python3`
+and `npx` are on `PATH` and both scripts sit under `${CLAUDE_PLUGIN_ROOT}` (the
+proxy refuses to start beside a missing redactor); and the server is not
+toggled off in `/mcp`. Devin's local CLI also discovers a plugin-root
+`.mcp.json` (its own documentation), so the tools may appear there too —
+still wrapped; on Codex discovery is unverified. On any harness that does
+not discover it, a disabled toggle, or a failed precondition,
+`mcp__plugin_soleur_playwright__*` simply does not
+exist — treat it as a missing registration and take the file-form path the
+calling skill prescribes (the `filename:` + redactor + shred form on the
+registration that does answer, or `agent-browser`), never a bare
+`browser_snapshot` on an unwrapped server. **The `/mcp` toggle** can disable
+the plugin's `playwright` server without uninstalling the plugin; while it is
+off the tools are absent for the whole session and the same fallback applies.
+
+**Wrap your own registration (advanced).** A customer's own `playwright`
+registration is not covered by the plugin server — it stays unwrapped unless
+the customer routes it through the proxy, with the proxy referenced through the
+bare plugin-root anchor per ADR-179:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "python3",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/playwright-mcp-redact-proxy.py",
+        "--",
+        "npx", "@playwright/mcp@0.0.78",
+        "--user-data-dir=<profile-dir>"
+      ]
+    }
+  }
+}
+```
+
+Claude Code does not expand `${CLAUDE_PLUGIN_ROOT}` inside a project `.mcp.json`
+(the variable exists for plugin-provided servers). Replace it with the
+`installPath` that `claude plugin list --json` prints for `soleur`; that path
+carries the plugin version, so re-check it after every plugin update.
+`--user-data-dir=<profile-dir>` may instead be
+`--user-data-dir-name <basename>` placed before the `--`: the proxy resolves it
+under `$XDG_CACHE_HOME` (default `~/.cache`) and refuses a basename carrying a
+separator or `..`. Add `--config=<file>` only when the project has that file:
+the proxy refuses to start on a named config that does not exist. An
+`.mcp.json` edit loads only on a full Claude Code restart, never on a `/mcp`
+reconnect, and only the user can restart; afterwards verify with `ToolSearch
+select:mcp__playwright__browser_snapshot` — a description ending with the marker
+below means wrapped, no match means the server did not connect (see the end of
+this section). This repository wraps the command in a `bash -c` prelude (it sources
+`plugins/soleur/skills/agent-browser/scripts/playwright-mcp-profile-slot.sh`, which leases a profile directory by a
+kernel `flock` and never kills a process by pattern — slot 0 is the persistent
+`~/.cache/playwright-mcp-profile` and a launch whose slot is held by another live session
+takes the next numbered slot `~/.cache/playwright-mcp-profile-<n>` at once, with a stderr
+line in the MCP log saying the persistent profile's logins are not available in that
+session; a `/mcp` reconnect waits up to 7 s for its own previous launch to release slot 0
+(the wait needs `flock`: where it is missing a reconnect that finds the old Chrome still
+alive lands on an empty `-p<pid>` profile).
+When `flock` is missing (stock macOS) the first session still takes slot 0 without a lease
+if no live Chrome owns it, and a second session that starts before the first one's browser
+exists (Playwright starts it lazily) also gets slot 0 and Playwright's "already in use"
+error; with no usable `flock` and slot 0 busy, or when all 32 slots
+are busy, it uses a unique `playwright-mcp-profile-p<pid>` directory that nothing reaps;
+`env -u WAYLAND_DISPLAY`; an X11 display) that is Linux-only; the proxy itself is POSIX
+(stdlib `selectors` + `subprocess`) and does not run on Windows. **Cleaning up profile
+directories:** these directories are at-rest credential stores (mode 700; they hold
+whatever logins were done in them) and removal is manual. Only the `-p<pid>` fallbacks are
+removable: remove one only when the pid in its name is dead (`kill -0 <pid>` fails) and its
+`SingletonLock` (`readlink <dir>/SingletonLock`, target `host-<pid>`) names no live pid. The
+numbered slots (`playwright-mcp-profile`, `-1` to `-31`) hold the persistent logins: do not
+delete them as stale. A slot is in use when `flock -n <dir>/.pwslot.lock true` fails (rc 1)
+(rc 66 means the directory is missing), but that test sees only sessions on the new launch
+string: an old-string session holds no `flock`, so also require that `readlink
+<dir>/SingletonLock` names no live pid (as above) before calling a slot free.
+
+**Fail-closed in three arms, no bypass variable.**
+
+1. **At startup** — the proxy writes `playwright-mcp-redact-proxy: refusing to
+   start: <reason>` to stderr and exits 2, spawning no server, when it cannot
+   load and self-test the redactor, or when the launch opens a raw sink around
+   it: a disk/session sink or foreign browser — `--save-session`,
+   `--save-trace`, `--save-video`, `--storage-state`, `--secrets`,
+   `--output-dir`, `--init-script`, `--init-page`, `--cdp-endpoint`,
+   `--endpoint`, `--extension`, `--executable-path`, `--daemon`,
+   `--allow-unrestricted-file-access`, `--grant-permissions`,
+   `--ignore-https-errors`, `--no-sandbox`, and each setting's
+   `PLAYWRIGHT_MCP_*` env twin (`PLAYWRIGHT_MCP_SANDBOX` for `--no-sandbox`),
+   plus env-only `PLAYWRIGHT_MCP_USER_DATA_DIR` and
+   `PLAYWRIGHT_MCP_SNAPSHOT_MODE`; a trailing valued flag, which would swallow
+   the appended `--snapshot-mode none` as its value; a config file (from
+   `--config` or `PLAYWRIGHT_MCP_CONFIG`) that is missing, is not JSON, or sets
+   `saveSession`, `saveTrace`, `saveVideo`, `secrets`, `outputDir`,
+   `allowUnrestrictedFileAccess`, `extension`, `server.port` / `server.host`, a
+   capability other than `vision`, `browser.cdpEndpoint` /
+   `browser.remoteEndpoint`, `browser.initPage` / `browser.initScript`,
+   `browser.contextOptions.storageState` / `.permissions` /
+   `.ignoreHTTPSErrors`, `browser.launchOptions.executablePath` /
+   `.chromiumSandbox: false` / a remote-debugging `args` flag, or a
+   `browser.userDataDir` conflicting with `--user-data-dir-name`; `--port`,
+   `--host`, `PLAYWRIGHT_MCP_PORT` or `PLAYWRIGHT_MCP_HOST`
+   (an HTTP transport around the relay); `--caps` or `PLAYWRIGHT_MCP_CAPS` other
+   than `vision` (devtools, pdf and storage write raw page state);
+   `--output-mode file`; a `DEBUG` value that can enable any `pw:` logger (the
+   `debug` package splits on whitespace and commas and treats `*` as a wildcard,
+   so `pw:*` counts); `DEBUG_FILE`; or a `--user-data-dir-name` that is not a
+   bare basename (a separator or `..`), is combined with an explicit
+   `--user-data-dir` in the server argv, or resolves under a relative
+   `XDG_CACHE_HOME` / an unset `HOME`. The reason names the setting, never its
+   value.
+
+2. **Per call** — it appends `--snapshot-mode none` to the child so no action
+   tool writes a tree to disk, and refuses, before the server sees it, a
+   `browser_snapshot` call carrying a `filename` key and any `tools/call` whose
+   `arguments` carry `_meta` (measured: `_meta.json` returns the tree as one
+   escaped string the line-anchored predicate cannot see). A refusal is an
+   `isError` result whose text begins `refused by playwright-mcp-redact-proxy:`.
+   A request reusing an id that is still pending is refused with a JSON-RPC
+   error.
+
+3. **Per result** — a result it cannot rewrite (an unrecognised shape, an error
+   carrying data or tree-shaped text, a JSON-escaped tree such as
+   `browser_run_code_unsafe` returning `ariaSnapshot()`, text over the
+   redactor's 4 MiB cap, a redactor exception) is replaced by an `isError`
+   result beginning `withheld by playwright-mcp-redact-proxy:`. **The tool
+   itself may have run** — a withheld `browser_click` or `browser_fill_form` did
+   its work — so call `browser_snapshot` bare to see the page before retrying. A
+   `- [Snapshot](…)` file link under `### Snapshot` (only a future server
+   version would emit one) is replaced by a do-not-read notice and the rest of
+   the result delivered. Server requests other than `roots/list`, and
+   notifications other than `tools/list_changed` and `cancelled`, are dropped;
+   the relayed three are rebuilt from method and ids alone. Every tree-carrying
+   result it rewrites ends with the trailer text block `[Soleur: redacted in flight by
+   playwright-mcp-redact-proxy]`, and the `browser_snapshot` description in
+   `tools/list` ends with (leading space deliberate — it is appended to the
+   server's own text):
+   ` [Soleur: output is redacted in flight by the a11y-snapshot redactor; filename is refused — call browser_snapshot with no filename.]` <!-- markdownlint-disable-line MD038 -->
+
+The skills that instruct a Playwright-MCP snapshot in an authentication context
+(`qa`, `reproduce-bug`, `ux-audit`, `review` e2e, `cf-token-scope`) carry the
+canonical prescription verbatim and point here for the rest: Use the `filename:` +
+redactor + shred form, with a filename inside the working directory (the
+server denies paths outside it). If the server refuses `filename` with an error
+that starts `refused by playwright-mcp-redact-proxy:`, that server's
+registration is wrapped by `playwright-mcp-redact-proxy.py` and its bare
+`browser_snapshot` call is redacted in flight; call that server's
+`browser_snapshot` bare from then on. Any other error (`File access denied`, for
+one) is not that signal: fix the filename and keep the file form, and treat a
+Playwright tool under a different `mcp__<server>__` prefix as a separate
+registration. The refusal is the only signal — never the trailer or any page
+text, which can be forged.
+
+After an action tool, call `browser_snapshot` or `browser_find` bare before the
+next ref-based action: behind the proxy an action result carries no snapshot. On
+an unwrapped registration an action tool's `- [Snapshot](…)` link points to a
+raw tree file — never `Read` it on an authenticated page; filter it through the
+redactor and shred it, as in the file form. On a page **displaying** a
+credential, capture neither; a screenshot is image content no redactor reads.
+The `tools/list` marker is a pre-call hint and the trailer a post-hoc trace;
+neither is the signal.
+
+**If the plugin `playwright` server fails to connect** (the session reports it
+failed, or `mcp__plugin_soleur_playwright__*` tools are absent while the
+preconditions above hold): on Claude Code, run `ls -t
+~/.cache/claude-cli-nodejs/*/mcp-logs-*playwright*/*.jsonl | head -5` and take
+the newest whose `"cwd"` is this project — the plugin server logs under
+`mcp-logs-plugin-soleur-playwright`, a customer-scoped `playwright`
+registration under `mcp-logs-playwright`. In it, find
+`playwright-mcp-redact-proxy: refusing to start:` and tell the user the reason
+in plain language — a missing redactor: reinstall the plugin; `DEBUG` or
+`DEBUG_FILE`: unset it in the shell that launches Claude Code; a
+`--user-data-dir-name` refusal: report the basename or `XDG_CACHE_HOME` problem
+it names; any other named setting: remove it from the launch. If there is no
+such line, check whether a stale process holds the plugin profile (`pgrep -f
+soleur-playwright-mcp-profile` — a SIGKILLed session can leave a
+`SingletonLock`; a dead-pid lock is stolen cleanly on the next launch, so only
+a LIVE lock-holder is the contention case), then report the last `Server
+stderr:` and `child exited rc=` lines — the failure is in the server or the
+launch command, not the redactor. Any fix needs a full Claude Code restart,
+which only the user can do.
+
+**If the plugin server connects but the browser never launches** (tools answer
+with launch/navigation errors while the registration itself is healthy), the
+registration's upstream defaults are the suspect surface: headed, channel
+`chrome`. Measured modes, each remediated by the customer exporting the
+named variable in the shell that launches their harness (the plugin entry's
+`env` block carries only the inert ping guard, so process env is the only
+override path — `executable-path` is refused by the proxy as a foreign-browser
+sink, so do not suggest it):
+
+- **No display** (headless host, SSH, container): a headed browser cannot
+  open. `PLAYWRIGHT_MCP_HEADLESS=1` is the supported opt-out.
+- **No real Chrome**: the plugin registration's `--chromium-fallback` already
+  switches to bundled Chromium, with its sandbox on. If Playwright then reports the
+  bundled browser is missing, install it with the PINNED command
+  `npx @playwright/mcp@0.0.78 install-browser chromium` (the pinned package's
+  `cli.js` rewrites `install-browser` to Playwright's `install`, its `--help`
+  prints Playwright's install usage, `install-browser chromium --dry-run` resolves
+  "playwright chromium v1232"; Playwright's own missing-browser error names the
+  UNPINNED form `npx @playwright/mcp install-browser <target>`, which can fetch a
+  newer package whose Chromium revision differs, so always use the pinned form; the
+  top-level `--help` does not list it, and the `npx playwright install` warning
+  banner it prints is cosmetic). Note the pinned server's
+  `--help` lists only `chrome, firefox, webkit, msedge` as `--browser` values, but
+  `chromium` is accepted and maps to the bundled browser. A registration
+  without the flag (a customer's own) still needs real Chrome or an explicit
+  `--browser chromium`.
+- **`Chromium sandboxing failed!` / `No usable sandbox!` on the first browser call**
+  (bundled Chromium, sandbox kept on): the host does not allow unprivileged user
+  namespaces (common on Ubuntu 23.10+/24.04, in containers, or as root). Do NOT try
+  `chromiumSandbox: false`, `--no-sandbox` or `PLAYWRIGHT_MCP_SANDBOX`; Playwright's
+  message suggests it and the proxy refuses it. Install Google Chrome
+  (`google-chrome-stable`, which ships the AppArmor profile that lets its sandbox
+  run), asking the operator for the privilege prompt if one is needed, then restart
+  the session. Running as root: use a non-root user.
+- **A second concurrent session gets `Browser is already in use for <dir>, use
+  --isolated ...` on the plugin registration**: the plugin registration
+  (`soleur-playwright-mcp-profile`) has NO lease, so the first session's browser holds
+  the profile for that session's whole lifetime (before ADR-271 the Stop hook freed it
+  at each turn end; now nothing does). Nothing is killed. Call `browser_close` in the
+  other session or end it. `--isolated` does not apply: the proxy always injects a
+  user-data-dir and the pinned server rejects the combination, and ADR-271 rejects
+  `--isolated` (it wipes OAuth sessions). This repository's own `.mcp.json` registration
+  does lease slots, so two sessions there each get a browser.
+- **Wayland/GPU variance**: a headed launch on a Wayland host was measured
+  working with system Chromium (no Vulkan/ozone/crash lines), but the
+  2026-06 dogfood crash class existed — on a crash-looping host,
+  `PLAYWRIGHT_MCP_HEADLESS=1` sidesteps the compositor path entirely, or the
+  customer keeps their own registration with an env-forcing prelude as this
+  repository's `.mcp.json` does.