BramVR · BramVR · Aug 19, 2026 · Aug 19, 2026
@@ -20,7 +20,7 @@ Codex CLI output: avoid Markdown tables by default; they render poorly there. Us
 - Skill descriptions: short generic trigger phrase, not summary; no personal names, long paths, or workflow narration unless needed for routing.
 - Skill frontmatter: quote `description`; after SKILL.md edits, YAML-parse frontmatter before commit.
 - After adding/removing/renaming a skill: run `scripts/sync-skills` (mirrors into `~/.claude/skills` + `~/.codex/skills`, prunes dead links). `--dry-run` to preview.
-- Upstream sync: treat `steipete/agent-scripts` as a source to mine, not a branch to merge. Preserve Bram-local skills/helpers (`hermes-win`, `hermes-dashboard`, `autoreview`, `bram-maintainer-loop-v2`, `tdd`, `to-prd`, `to-issues`, `grill-with-docs`). Scrub or skip non-Bram personal/product assumptions; do not adopt broken symlinks unless Bram explicitly configures that repo. Mining marker + flow: `docs/upstream-mined.md`.
+- Upstream sync: treat `steipete/agent-scripts` as a source to mine, not a branch to merge. Preserve Bram-local skills/helpers (`hermes-win`, `hermes-dashboard`, `autoreview`, `bram-maintainer-loop-v2`, `tdd`, `to-prd`, `to-tickets`, `grill-with-docs`). Scrub or skip non-Bram personal/product assumptions; do not adopt broken symlinks unless Bram explicitly configures that repo. Mining marker + flow: `docs/upstream-mined.md`.
 - Read `~/Projects/agent-scripts/tools.md` when the tool catalog matters.
 
 ## Routing

@@ -4,6 +4,9 @@ summary: Timeline of guardrail helper changes mirrored from Sweetistics and rela
 
 # Changelog
 
+## 2026-08-19 — Recent Skill Refresh
+- Replaced the retired `to-issues` route with `to-tickets`, refreshed the Matt Pocock TDD/setup/ticket bundle from current upstream, upgraded Peekaboo CLI and guidance to v4, and updated browser automation for cmux-first routing plus fail-closed Chrome extension relay use.
+
 ## 2026-08-19 — Diagnosis, Design, and Writing Skills
 - Added Matt Pocock's `diagnosing-bugs` workflow plus minimally adapted Codex-native copies of PStack's `architect` and `blast-radius`, and an unchanged PStack `unslop` workflow, with upstream attribution, MIT notices, UI metadata, validation, and local skill-mirror discovery.
 

@@ -117,7 +117,7 @@ Treat this repo as Bram's canonical shared agent setup and portable helper mirro
 
 Upstream intake from `steipete/agent-scripts`:
 - Mine selectively; do not merge wholesale.
-- Preserve Bram-local skills/helpers: `hermes-win`, `hermes-dashboard`, `autoreview`, `bram-maintainer-loop-v2`, `tdd`, `to-prd`, `to-issues`, `grill-with-docs`.
+- Preserve Bram-local skills/helpers: `hermes-win`, `hermes-dashboard`, `autoreview`, `bram-maintainer-loop-v2`, `tdd`, `to-prd`, `to-tickets`, `grill-with-docs`.
 - Skip or scrub non-Bram personal/product defaults before adopting docs or skills.
 - Do not adopt symlinks to missing repos unless Bram explicitly configures them.
 - Prefer generic helper/script fixes, CI smoke checks, and non-personal skill improvements.

@@ -3,6 +3,7 @@
 - Reviewed `upstream/main` through: `6878dd818b34659a925ec45fb7225a81b6a5c69a` (2026-07-22, reviewed 2026-07-23)
 - Full classification report of the 232-commit pass (through `0798fed`): 19 groups already present, 12 skip (Peter-personal), 19 port candidates, 2 preserved-skill conflict families (autoreview, maintainer-loop). Port candidates pending Bram triage.
 - 2026-07-23 pass (`0798fed..6878dd8`, 1 commit): ported codex-first git-mechanics mandate, guarded CI waits, fresh work-order sessions, AGENTS.md-only rule; scrubbed openclaw watcher example + CLAUDE.md-symlink claim; kept Bram divergences (no fast_mode, loopback-only gate, short description, `$bram-maintainer-loop-v2` pointer).
+- 2026-08-19 targeted refresh: mined `skills/browser-use` through `2e320ff086cfc82d01037edab0683857d48c1698`; combined current relay hardening with Bram's cmux-first route. Global marker unchanged because this was not a full upstream classification pass.
 
 ## Flow (repeat per pass)
 

@@ -1,24 +1,33 @@
 ---
 name: browser-use
-description: "Browser automation in cmux or Chrome DevTools; no AppleScript."
+description: "Browser automation in cmux or signed-in Chrome; fail-closed relay fallback."
 ---
 
 # Browser Use
 
-Use this for browser tasks in cmux or against an existing Chrome session.
+_Source: [steipete/agent-scripts](https://github.com/steipete/agent-scripts), browser-use through `2e320ff0`; combined with Bram's cmux-first routing._
 
-Hard rule: use `cmux browser` in cmux; otherwise use `mcporter` `chrome-devtools`. Do not fall back to AppleScript, `osascript`, GUI scripting, or macOS `open` for browser control.
+Control a browser without AppleScript or generic GUI scripting. Preserve the user's signed-in state when the task depends on cookies, SSO, device trust, or extensions.
 
-## cmux Browser
+## Route
 
-Prefer this path when `cmux browser status` prints `enabled`.
+1. Use `cmux browser` when `cmux browser status` reports `enabled`.
+2. Otherwise use the callable Codex `Chrome` or `Chrome [Internal]` plugin when available in the active session. Installed on disk is not enough.
+3. Otherwise use the OpenClaw extension-backed Chrome DevTools MCP route through mcporter.
+4. Use full-profile direct DevTools attachment only as an explicit last fallback.
+
+Never substitute an isolated browser, Playwright, Puppeteer, AppleScript, `osascript`, generic GUI scripting, or macOS `open` unless the user explicitly asked for a new or isolated browser. Peekaboo is allowed only for Chrome or extension setup, native browser chrome, and visible prompts.
+
+For a rendered-browser bug, prove behavior in the selected real browser. Treat `curl`, source inspection, API checks, and isolated tests as supporting evidence, not live UI proof.
+
+## cmux browser
 
 ```bash
 cmux browser status
 cmux --json browser open https://example.com --focus false
 ```
 
-Use the returned `surface_ref` for the task:
+Use the returned `surface_ref`:
 
 ```bash
 cmux browser surface:25 get url
@@ -32,63 +41,115 @@ cmux browser surface:25 eval 'document.title'
 cmux browser surface:25 screenshot --out /tmp/cmux-browser.png
 ```
 
-Use explicit `--text` / `--value` when a mutating command also has flags; otherwise trailing flags can be parsed as input text. Run actions sequentially and re-snapshot after DOM changes; refs from older snapshots can go stale.
+Use explicit `--text` and `--value` when a mutating command also has flags. Otherwise trailing flags can be parsed as input text. Run actions sequentially and re-snapshot after DOM changes because older refs can go stale.
 
-Use `cmux identify --json` when you need caller workspace/window/surface context. If a snapshot or eval returns `js_error`, fall back to:
+Use `cmux identify --json` when caller workspace, window, or surface context matters. If snapshot or evaluation returns `js_error`, fall back to:
 
 ```bash
 cmux browser surface:25 get text body
 cmux browser surface:25 get html body
 ```
 
-cmux uses WKWebView. Known gaps: viewport emulation, offline emulation, tracing/screencast, network interception, and low-level raw input.
+cmux uses WKWebView. Known gaps include viewport and offline emulation, tracing, screencast, network interception, and low-level raw input.
 
-## Check MCP
+## OpenClaw extension relay
 
-Use this path when cmux browser is unavailable and Chrome DevTools MCP is the target.
+The Chrome DevTools MCP call is the agent-facing interface. The OpenClaw extension is its authenticated transport. Require relay-only routing so a missing relay cannot silently become direct DevTools attachment:
 
 ```bash
-npx -y mcporter list chrome-devtools --schema
-npx -y mcporter call chrome-devtools.list_pages --args '{}' --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.<tool>
 ```
 
-If `list_pages` fails with `DevToolsActivePort`, restart the mcporter daemon and retry:
+A Chrome "Allow remote debugging?" prompt or relay-policy error means the extension transport was not used.
+
+OpenClaw creates a random per-host relay key. The extension and same-host clients use nonce-bound mutual HMAC proofs. The reusable key must not enter URLs, child process arguments, configuration, command output, chat, logs, or screenshots.
+
+New pairings default to all eligible ordinary tabs except tabs paused in the popup. Existing pairings keep their stored mode. In selected-tabs mode, membership in the Chrome tab group named `OpenClaw` is the sharing boundary. Restricted pages, incognito tabs, other profiles, and ineligible URLs stay excluded.
+
+Direct remote Gateway pairing does not create a local relay for local mcporter. Do not copy remote secrets or create ad-hoc SSH tunnels around that boundary.
+
+### Setup and repair
+
+- Run `openclaw browser extension install` before loading the unpacked extension. It installs a stable copy and registers its deterministic Chrome ID.
+- Use `openclaw browser extension status --json`. Require no reported issues and `manualSetupRequired: false`.
+- Confirm Settings reports automatic setup ready and the popup reports connected.
+- If the extension attempted native messaging before installation, restart Chrome once. Chrome caches the miss for the process lifetime.
+- After pairing or route changes, run `npx -y mcporter daemon stop`. A restart can reuse a child with a dead upstream socket; a stop forces a clean child on the next call.
+- MCPorter discovers the relay through `openclaw browser extension cdp --json`. A source-checkout launcher may need `MCPORTER_CHROME_DEVTOOLS_RELAY_TIMEOUT_MS=15000` for its freshness build.
+
+Do not run the CDP discovery command or inspect process arguments as routine diagnostics because either can expose relay credentials.
+
+### Fail-closed readiness proof
+
+Require every condition:
+
+1. Extension status reports the stable copy and exact native registrations with no issues.
+2. The popup reports connected and the target tab is eligible and not paused.
+3. The mcporter daemon was stopped after pairing or route changes.
+4. A call with `MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require` succeeds.
+5. Selection and evaluation both succeed in a known disposable tab.
 
 ```bash
-npx -y mcporter daemon restart
-npx -y mcporter call chrome-devtools.list_pages --args '{}' --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.list_pages --args '{}' --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.select_page --args '{"pageId":9}' --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.evaluate_script --args '{"function":"() => ({title: document.title, href: location.href})"}' --output json
 ```
 
-If it still fails, stop and say Chrome DevTools MCP is unavailable. Do not use AppleScript.
+A relay-policy error means the extension route is unavailable. Report or repair it instead of retrying without `require`.
 
-Avoid noisy recovery loops. Repeated MCP/browser restarts can trigger
-reconnect/login prompts and alerts. Try once, then pause and choose a quieter
-path.
+## Chrome DevTools flow
 
-## Typical Flow
+Use current snapshot UIDs. Prefer DOM snapshots over screenshots unless layout matters.
 
 ```bash
-# pick the page id from list_pages
-npx -y mcporter call chrome-devtools.select_page pageId=9 --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.list_pages --args '{}' --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.select_page --args '{"pageId":9}' --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.take_snapshot --args '{}' --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.click --args '{"uid":"1_38","includeSnapshot":true}' --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.fill --args '{"uid":"1_13","value":"text","includeSnapshot":true}' --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.evaluate_script --args '{"function":"() => document.title"}' --output json
+```
 
-# inspect page
-npx -y mcporter call chrome-devtools.take_snapshot --args '{}' --output text
+Capture state before the action, perform the requested interaction, then snapshot or evaluate the rendered result. Keep secrets out of DOM, input, network, console, and screenshot output. Return only safe shapes for credential checks, such as present or absent, length, status code, or account name.
 
-# navigate selected page
-npx -y mcporter call chrome-devtools.navigate_page url=https://example.com --output text
+If automation is unavailable, report the verification gap instead of switching to prohibited or isolated tooling.
 
-# click an element uid from the latest snapshot
-npx -y mcporter call chrome-devtools.click uid=1_38 includeSnapshot=true --output text
+## Argument and output mechanics
 
-# type/fill
-npx -y mcporter call chrome-devtools.fill uid=1_13 value='text' includeSnapshot=true --output text
+`--args` accepts inline JSON only. It does not read `@file`. Flag-style named arguments do:
 
-# run JS, keep secrets out of output
-npx -y mcporter call chrome-devtools.evaluate_script --args '{"function":"() => document.title"}' --output json
+```bash
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.navigate_page url=@/tmp/target-url.txt --output text
+MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require npx -y mcporter call chrome-devtools.evaluate_script function=@/tmp/probe.js --output json
 ```
 
-Use `take_snapshot` before actions and use current `uid` values only. Avoid `take_screenshot` unless visual layout matters.
+Use a mode-0600 file for sign-in URLs, magic links, callbacks, and multiline scripts so their values do not enter shell history, process arguments, or captured output.
+
+Other mechanics:
+
+- Interactive navigation, snapshots, and consent pages can exceed the short default timeout. Use `--timeout 30000`.
+- `take_screenshot` paths are confined to configured workspace roots. When necessary, omit `filePath`, read base64 JSON output, and decode it locally.
+- `new_page` can fail for an unavailable or unshared target. Prefer navigating an eligible shared tab.
+- Run `npx -y mcporter list chrome-devtools --schema` instead of guessing parameter names.
+
+## Clicks that do not click
+
+A UID click can report success while a page ignores the synthetic event. Verify state after every activation.
+
+When click no-ops, use `press_key` with `Tab`, `Shift+Tab`, or `Enter`, and confirm focus with a screenshot first. Never send blind Enter on a consent screen.
+
+Navigation and re-rendering invalidate UIDs. Re-run `take_snapshot` after each state change.
+
+## Empty relay mid-task
+
+An empty page list usually means there are no eligible tabs, the tab was paused, selected-tabs mode lost its group members, or the extension disconnected. Confirm Chrome is running, check the popup connection and pause state, then check the access mode.
+
+Restarting mcporter cannot repair extension disconnection, tab eligibility, or access policy. Do not switch to full-profile attachment or an isolated browser to hide the gap.
+
+## Legacy full-profile fallback
+
+Use direct attachment only after the callable plugin and authenticated local extension relay are unavailable. It exposes the full real-profile tab set and can show Chrome's blocking remote-debugging prompt.
 
-## Secret Handling
+Approve one visible, unambiguous prompt, then retry `list_pages` once. If the prompt is absent, ambiguous, or the retry fails, stop. Never loop approvals, repeatedly restart Chrome or mcporter, or kill browser processes.
 
-Never print tokens/passwords from page DOM, network logs, or inputs. For token checks, return shape only: present/absent, length, status code, account/org name.
+Verify the intended real-profile tabs before acting and label this route as full-profile direct attachment, never extension relay success.
@@ -120,7 +120,7 @@ Never work multiple tickets at once in one worker. For each item:
    - Go: performance improvements unless complexity rises too much; bugfixes with repro/root cause and verification path; small UI/UX tweaks; docs fixes; narrow test/internal fixes; low-risk dependency/CI cleanup with green proof.
    - Ask first: new features, product/vision choices, broad behavior changes, risky dependencies, security-sensitive changes without strong proof, live-provider work without usable credentials, anything that cannot be end-to-end tested.
    - Refactor preference: choose a clean bounded refactor when it is the better fix for an autonomous item; do not use "small patch" as the default if it leaves worse design.
-3. Implement or fix the PR in the best maintainable way. Use `tdd` for behavior changes unless trivial/docs-only: start with a failing regression or characterization test when feasible, make it pass, then refactor within scope. Use `to-prd` or `to-issues` when the item is too vague or too large.
+3. Implement or fix the PR in the best maintainable way. Use `tdd` for behavior changes unless trivial/docs-only: start with a failing regression or characterization test when feasible, make it pass, then refactor within scope. Use `to-prd` or `to-tickets` when the item is too vague or too large.
 4. Verify locally and live end-to-end when possible. For UI behavior, use the repo's expected live UI proof path. For API/provider behavior, use a real usable key/account through the expected secret workflow when available. If access is missing, stop before pretending the item is done and ask Bram for the exact access or waiver.
 5. Run `autoreview` before commit/land unless trivial/docs-only or explicitly skipped; address accepted/actionable findings.
 6. Ensure CI is green when CI work is authorized. Do not push, merge, close, rerun, or mutate public state without matching permission.