sunwood-ai-labs/browser-reuse-guard/skill

Browser Reuse Guard

Treat a new browser surface as an exception, not a starting point. Follow this workflow before every new tab, window, profile, CDP listener, or authorization URL.

1. Inspect before deciding

Select the browser surface already associated with the task. Inspect its existing candidate tabs and record only:

• URL origin and path; omit query and fragment values
• title
• visible rendered state

Never treat an uninspected tab as unsuitable. Do not inspect cookies, local storage, profile files, saved passwords, tokens, or auth files.

2. Reuse or prove the exception

• Reuse a tab when its visible state can serve the task.
• If no tab can serve it, record a specific reason: the target tab closed, the browser transport remained inaccessible after retry, the provider showed a terminal error, or an isolated test profile is explicitly required.
• A slow page, blank tab, provider/account picker, consent screen, ordinary Allow, or a reachable CDP port is not evidence for creating or switching a browser surface.
• For OAuth started by a CLI or app, inspect and reuse that process's browser/tab. Do not create another authorization URL or choose an in-app/dedicated browser to look for a more convenient session.

3. Validate a new-surface decision

Before a new-surface action, run the read-only checker with sanitized observations:

& "$env:USERPROFILE\.codex\skills\browser-reuse-guard\scripts\validate_browser_reuse_record.ps1" `
  -Decision new-tab `
  -ExistingTabsObserved 'https://accounts.example.com/oauth | Sign in | provider picker' `
  -FailureEvidence 'terminal provider error on the inspected OAuth tab'

Use -Decision reuse when retaining an existing tab. The checker rejects missing inspection, query-bearing URLs, sensitive storage/auth references, and new-surface decisions without objective evidence.

4. Act and verify

Open or switch only after the record passes. Reinspect the resulting visible tab state after navigation. For OAuth, browser appearance never proves completion; use the workflow's fresh CLI authentication check.