browser-control

name	browser-control
description	Control real websites and authenticated browser sessions, inspect pages, complete approved UI flows, or troubleshoot browser automation. Use for general browser work, site settings, OAuth consent, existing tabs, and Slack app configuration. Uses Aside first and routes deterministic app testing to playwright-ui-testing.

Browser control

Route the task

1. Live websites, authenticated sessions, account settings, OAuth, or existing tabs: use aside-browser-default first. Inspect the active runtime's available browser tools before hard-coding a tool name.
2. Deterministic local-app testing, CI, isolated profiles, traces, video, or multi-browser coverage: load playwright-ui-testing.
3. Authorized API discovery only: use browserclaw. Do not use it for Slack app settings, OAuth flows, or any capture likely to retain credentials, cookies, authorization headers, or tokens.

Live-browser workflow

1. Check for usable existing tabs before opening a new one.
2. Read the page with an accessibility snapshot before acting. Use current refs, not guessed selectors or coordinates.
3. Treat login, consent, chooser, and MFA screens as recoverable states. Never bypass them, extract secrets, or copy cookies between browser profiles.
4. Confirm any side effect from the resulting page state. Before sending, submitting, deleting, installing, authorizing, or publishing, verify the target and requested scope.
5. Close tabs opened solely for the task when they are no longer useful.

Slack app and credential work

• Configure or rotate Slack credentials through the normal Slack UI. Load hermes-slack-rotation for manifest scopes, OAuth and Socket Mode token rotation, protected shell-file updates, and validation.
• Do not put tokens in prompts, screenshots, HAR files, shell output, artifacts, or source control.
• Do not infer a post's identity. Verify it with auth.test or the platform's confirmed result before claiming user versus bot behavior.

Failure classification

Report the precise layer that failed: browser transport, current tab/profile access, page authentication or consent, website UI, or action permission. A CLI failure does not prove an existing browser tab or another browser tool is unavailable.

Environment gotchas

• Aside CLI in a sandboxed Bash tool call fails closed, not soft. aside account list / aside repl / aside "<prompt>" return fetch failed immediately — before the Aside daemon writes any log line — when the Bash tool's default sandbox blocks the CLI's local IPC to the already-running Aside.app (a real launchd-managed process; verify with ps -p <pid> or launchctl list | grep -i aside, not ps aux | grep aside, since sandboxed ps aux may not enumerate it even though the process is alive). This is NOT an Aside outage. Fix: pass dangerouslyDisableSandbox: true on every Bash call that invokes aside. Confirmed 2026-07-16: identical command failed sandboxed, succeeded immediately unsandboxed against the same running daemon.
• Aside additionally requires a real, rendered display — not just an unsandboxed process. On a headless host (ioreg -c IODisplayConnect | grep -c IODisplayConnect returns 0), the Aside daemon answers metadata-only calls (account list) fine but any call needing a browser window/tab (openTab, navigation, an agent aside "<prompt>" task) fails with This task is not bound to a browser profile. Open it in Aside browser and try again. — confirmed 2026-07-16 on a headless Mac runner even after disabling the sandbox and confirming the daemon PID alive. This is a hardware/session limitation, not fixable by CLI flags, retries, or open -a Aside. On a headless host, do not attempt Aside for any interactive navigation — go straight to the browserclaw headless fallback below. Aside remains correct on a host with a real attached display (physical or a virtual/loopback one).
• Aside has no headless mode (aside --help lists no such flag) — it drives a real, visible browser via an extension bridge tied to the active macOS GUI session. It is not a background/CI-safe tool by design.
• browserclaw as a headless-chrome fallback: browserclaw capture --headless --url <url> [--goal "<task>" --provider <p> --model <m>] is genuinely headless (Playwright-backed, no display or GUI session required) and works from a sandboxed Bash call without special flags — confirmed working on the same headless host where Aside failed. Use browserclaw cookies decrypt / cookies inject to carry over an authenticated session from the real Chrome/Brave/Edge profile. — those commands persist full HTTP request/response traffic to a file on disk, which will contain the new secret in plaintext (the exact leak class this skill's credential rule already bans). For those flows, use (navigation only, no HAR) or a bare Playwright script, read the result from the DOM/page text, and do not persist the page's raw network traffic.

Completion

Report browser mode, the confirmed result, and any blocker. For browser-dependent actions, attach a focused screenshot when it is safe and useful.