pi-browser-use 0.9.6 → 0.10.0

package/dist/setup-flow.d.ts

@@ -39,24 +39,30 @@ export declare function runBootstrap(options: {
     profileDir?: string;
     executablePath?: string;
     chromeArgs?: string[];
+    signal?: AbortSignal;
     launch?: (options: {
         userDataDir: string;
         profileDirectory?: string;
         executablePath?: string;
         chromeArgs?: string[];
+        signal?: AbortSignal;
     }) => Promise<number | null>;
 }, events?: SetupFlowEvents): Promise<number | null>;
 export interface ReauthOptions {
-    backend: PersistentBackend;
+    backend: Pick<PersistentBackend, 'profileDir' | 'restart'>;
     /** Page that needs auth (used for messaging + Variant B navigation hint). */
     url: string;
     variant?: ReauthVariant;
+    signal?: AbortSignal;
+    executablePath?: string;
+    chromeArgs?: string[];
     /** Plain-variant launcher (no CDP). Defaults to launchSetupBrowser. */
     launchPlain?: (options: {
         userDataDir: string;
         profileDirectory?: string;
         executablePath?: string;
         chromeArgs?: string[];
+        signal?: AbortSignal;
     }) => Promise<number | null>;
     /** Restart the backend headed/headless (Variant B + resume). */
     restartBackend?: (headed: boolean) => Promise<unknown>;

package/dist/setup-flow.js

@@ -44,6 +44,7 @@ export function reauthInstructions(url, variant) {
  * window exit code after marking the profile initialized.
  */
 export async function runBootstrap(options, events) {
+    options.signal?.throwIfAborted();
     const profileDir = options.profileDir ?? DEFAULT_PROFILE_DIR;
     events?.onSetupNeeded?.(SETUP_INSTRUCTIONS);
     // Same named identity automation uses: sign in here, automate there.
@@ -54,7 +55,11 @@ export async function runBootstrap(options, events) {
         profileDirectory: PI_PROFILE_NAME,
         executablePath: options.executablePath,
         chromeArgs: options.chromeArgs,
+        signal: options.signal,
     });
+    options.signal?.throwIfAborted();
+    if (code !== 0)
+        throw new Error(`Browser setup did not complete successfully (exit ${code}).`);
     markBootstrapped(profileDir);
     events?.onSetupComplete?.(profileDir);
     return code;
@@ -67,13 +72,23 @@ export async function runBootstrap(options, events) {
  * and waits for close. Returns the user-facing instruction to relay.
  */
 export async function runReauth(options) {
+    options.signal?.throwIfAborted();
     const variant = options.variant ?? 'instrumented';
     const profileDir = options.backend.profileDir?.() ?? DEFAULT_PROFILE_DIR;
     const message = reauthInstructions(options.url, variant);
     options.events?.onReauthNeeded?.(message);
     if (variant === 'plain') {
         const launch = options.launchPlain ?? launchSetupBrowser;
-        await launch({ userDataDir: profileDir, profileDirectory: PI_PROFILE_NAME });
+        const code = await launch({
+            userDataDir: profileDir,
+            profileDirectory: PI_PROFILE_NAME,
+            executablePath: options.executablePath,
+            chromeArgs: options.chromeArgs,
+            signal: options.signal,
+        });
+        options.signal?.throwIfAborted();
+        if (code !== 0)
+            throw new Error(`Browser verification did not complete successfully (exit ${code}).`);
     }
     else {
         if (options.restartBackend) {
@@ -83,6 +98,7 @@ export async function runReauth(options) {
             await options.backend.restart(true);
         }
     }
+    options.signal?.throwIfAborted();
     options.events?.onReauthComplete?.(profileDir);
     return message;
 }

package/dist/tab-bridge.js

@@ -110,8 +110,12 @@ export class TabBridge {
         const pollMs = options?.pollMs ?? 100;
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
-            if (options?.signal?.aborted)
+            if (options?.signal?.aborted) {
+                // Do not leave a cancelled request for the extension to consume; it
+                // would create an unmanaged tab after the caller has given up.
+                this.pending.delete(token);
                 throw new Error('Tab wait aborted.');
+            }
             const done = this.completed.get(token);
             if (done) {
                 this.completed.delete(token);

package/docs/agent-plugins.md

@@ -0,0 +1,131 @@
+# Agent Plugins 1.0
+
+One browser runtime, two host adapters: native Pi and a portable stdio MCP server.
+
+## Installation and distribution
+
+Native Pi remains unchanged: `pi install npm:pi-browser-use`. It loads `dist/index.js`,
+uses Pi's trusted settings, and retains `~/.pi/browser-profile` and `~/.pi/browser-artifacts`.
+Do not enable both adapters in the same Pi session; that would register duplicate tools.
+
+For a client supporting **Agent Plugins 1.0 and local stdio MCP**, install this npm
+package into a user-controlled directory, then use that client's local-plugin
+installation flow to select the **installed package root**, containing `plugin.json`,
+`mcp.json`, `skills/`, and `dist/`. Node and the package's production dependencies must
+be installed; a source-only Git clone is not a ready-to-run plugin.
+
+For example, from an empty directory:
+
+```sh
+npm install --omit=dev pi-browser-use
+# Select this directory in the client's local-plugin loader:
+# <absolute-install-directory>/node_modules/pi-browser-use
+```
+
+To test an unpublished branch, use `npm ci && npm run build` in the checkout and
+load that directory. The manifest starts `node ${PLUGIN_ROOT}/dist/mcp-server.js`;
+there is no install-time shell hook, network package download, or hidden Pi dependency
+in that command. Clients without local-plugin loading can register the same script
+as an ordinary stdio MCP server and load the bundled skills separately.
+
+Chrome/Chromium must be installed. Tool discovery and `browser_status` do not launch
+Chrome, open a login window, or require a signed-in profile. The first browser action
+starts the configured backend. A plugin-capable client that only supports remote MCP
+cannot run this local browser server.
+
+## Configuration and private state
+
+The manifest passes the client's `${PLUGIN_DATA}` as `PI_BROWSER_USE_DATA_DIR`.
+The server reads only `<data>/config.json` (a direct `BrowserUseConfig` object):
+
+```json
+{
+  "mode": "persistent",
+  "headed": false,
+  "tabBridgePort": 31973
+}
+```
+
+Missing configuration uses persistent headless defaults. Invalid JSON, unknown
+fields, and invalid field types fail closed. Pi user settings, project `.pi` files,
+and Pi model credentials are never read by the portable adapter. Environment
+interpolation is not performed inside this configuration file.
+
+The data layout is:
+
+```text
+PLUGIN_DATA/
+  config.json
+  browser-profile/           # named pi-browser-use identity, cookies and site sessions
+  browser-profile.*          # existing lock, metadata, preferences, ownership/advert files
+  artifacts/                # default screenshot and HTML destination
+```
+
+The plugin root can be read-only after dependencies and build output are installed.
+`browser_status` reports the actual profile and artifact paths; skills must use those
+paths rather than assume `~/.pi`. Each client's plugin data is separate by default:
+signing into one client does not authenticate another client's browser.
+
+For standalone MCP, set `PI_BROWSER_USE_DATA_DIR` explicitly. Without it the server
+uses `PLUGIN_DATA`, then `~/.local/share/pi-browser-use` (never Pi's data directory).
+`PI_BROWSER_USE_CONFIG` optionally selects a different **absolute** configuration
+file; an explicitly selected missing file is an error.
+
+The existing launch, category, URL restriction, network-redaction, and bridge options
+from `BrowserUseConfig` are supported. `userDataDir` and `executablePath` must be
+absolute paths (a leading `~/` is supported). An explicit `userDataDir` can share a
+**dedicated automation identity** across clients; coordinate profile ownership and
+never point it at the user's daily Chrome directory. The chosen identity is retained
+when switching through fresh or existing mode and back to persistent. `wsHeaders`
+belongs to a host-managed secret-bearing configuration file, not the plugin bundle.
+The core does not disable Chrome's sandbox.
+
+## Behavior and host-specific capabilities
+
+All curated upstream `browser_*` tools and the management tools (`save_artifact`,
+`doctor`, `switch_mode`, `setup`, `status`, `reauth`, `open_background_tab`) share the
+same runtime. The MCP adapter is not a raw chrome-devtools-mcp configuration: tool
+filtering, network-header redaction, overlay recovery, annotated artifacts, ownership
+checks, per-origin visibility preferences, and background-focus defaults remain in
+place. MCP inputs are validated against each advertised tool's JSON schema.
+
+Calls are serialized within a runtime so a mode switch cannot race an active page
+operation. Cancellation propagates to upstream MCP, startup and human setup; stdin
+EOF, MCP disconnect and SIGINT/SIGTERM close the session. Shutdown terminates only a
+browser owned by that runtime, never a borrowed peer/user browser. Abrupt SIGKILL
+still relies on the existing orphan-recovery mechanism. Profile locks cannot be
+reclaimed from a live owner merely because their timestamps are old.
+
+Existing mode remains explicit and human-authorized. Background grouped tabs require
+the bundled Chrome extension in `extension/`, just as in native Pi. The loopback tab
+bridge is not a hosted service. Multiple simultaneous Existing-mode runtimes need
+coordinated bridge ports/extension configuration; this migration does not implement
+a shared bridge broker.
+
+**Vision:** Native Pi retains optional `visionModel` / `browser_analyze_screenshot`
+through its own model registry. Portable hosts receive standard MCP image content
+from `browser_take_screenshot` and use their own vision capability; the portable
+adapter deliberately does not expose the Pi-registry analysis tool or make implicit
+model/sampling calls. `visionModel` is rejected in portable configuration.
+
+**Authentication:** `browser_setup` opens an ordinary headed window on the same
+managed profile, with no automation attached. A human completes login and closes it.
+Use `browser_reauth` for later verification, including `variant: plain` for a provider
+that rejects instrumented sign-in. Human setup can exceed a client's default tool
+request timeout; increase that timeout in the host before starting. Cancellation or
+a nonzero browser exit does not mark setup/verification successful. Never copy daily
+Chrome profiles, cookies, passwords or Pi credentials into a plugin installation.
+
+## Validation and release
+
+`npm test` exercises the shared runtime, native Pi adapter, MCP schema/routing/error
+boundary, cancellation and auth lifecycle. `npm run test:smoke` packs the npm artifact,
+installs its production dependency closure in a temporary directory **without Pi**,
+and exercises a real stdio process, all tool schemas, status, EOF and SIGTERM.
+`npm run test:browser` adds a real Chrome run against a loopback-only fixture, covering
+navigation, screenshots, artifacts, profile reuse and fresh-mode isolation.
+
+Release Please synchronizes `plugin.json.version` with the npm version. The package
+includes both manifests and all skills, while excluding source maps, tests and CI
+helpers. This is a packaging/API compatibility claim, not a claim that every named
+agent client or real-world authentication provider has been tested.

package/mcp.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "browser": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/dist/mcp-server.js"],
+      "cwd": "${PLUGIN_ROOT}",
+      "env": {
+        "PI_BROWSER_USE_DATA_DIR": "${PLUGIN_DATA}"
+      }
+    }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-browser-use",
-  "version": "0.9.6",
-  "description": "Opinionated browser-use for the Pi coding agent, powered by chrome-devtools-mcp (not Playwright). Fresh headless by default, authenticated persistent profile opt-in, CLI-first policy bundled.",
+  "version": "0.10.0",
+  "description": "Opinionated browser automation via chrome-devtools-mcp: native Pi extension and portable Agent Plugins 1.0 skills + MCP server.",
   "keywords": [
     "automation",
     "browser",
@@ -27,7 +27,10 @@
     "docs/performance.md",
     "extension",
     "skills",
-    "README.md"
+    "README.md",
+    "plugin.json",
+    "mcp.json",
+    "docs/agent-plugins.md"
   ],
   "type": "module",
   "sideEffects": false,
@@ -56,7 +59,9 @@
     "perf:audit": "node scripts/performance.mjs",
     "preperf:check": "npm run build",
     "perf:check": "node scripts/performance.mjs --check",
-    "pretest": "npm run build"
+    "pretest": "npm run build",
+    "test:smoke": "npm run build && node scripts/plugin-smoke.mjs",
+    "test:browser": "npm run build && node scripts/plugin-smoke.mjs --browser"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/plugin.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "pi-browser-use",
+  "version": "0.10.0",
+  "description": "Managed persistent, fresh, and existing Chrome sessions with focus-safe browser tools and CLI-first skills.",
+  "author": {
+    "name": "0xPlayerOne"
+  },
+  "repository": "https://github.com/0xPlayerOne/pi-browser-use",
+  "license": "MIT",
+  "keywords": ["browser", "chrome", "mcp", "agent-skills", "pi"]
+}

package/skills/auth-bootstrap/SKILL.md

@@ -1,58 +1,61 @@
 ---
 name: auth-bootstrap
-description: "Log the persistent browser profile in for the first time. Use when the persistent profile hits a login wall, after switching to a fresh machine, or when SSO, 2FA, or passkeys need a human."
+description: "Initialize or reauthenticate the managed persistent browser profile. Use on a new machine or plugin instance, at a login wall, or when SSO, 2FA, passkeys or provider verification require a human. Works with native Pi and portable MCP hosts."
 ---
 
 # Auth Bootstrap
 
-The persistent profile starts empty. Log in once per site; cookies persist across sessions after that. The agent must never see your passwords — you type, it waits.
+Each managed profile starts empty. Native Pi and portable clients have separate
+profiles by default. Call `browser_status` to identify this instance before doing
+anything: a signed-in daily Chrome or another agent client proves nothing about it.
+Never read, capture or paste passwords, one-time codes or session cookies into chat.
 
-## Recommended flow: headed once
+## First run: plain headed setup
 
-```text
-browser_switch_mode({ "mode": "persistent", "headed": true })
-```
-
-1. A visible Chrome window opens on the persistent profile.
-2. **You** navigate and log in normally — including SSO, 2FA, and passkeys.
-3. Tell the agent you're done. It verifies (account page loads logged-in) and you close the window or it switches back to fresh.
+Select persistent mode when needed, then call `browser_setup`. Explain **before**
+calling it that an ordinary headed window opens on the managed profile, the human
+signs into the needed sites, and they close that window when finished. No browser
+automation is attached to this setup window. Do not automate its credential fields.
 
-Headless cannot do this step: 2FA apps, security keys, and most SSO device checks need a human and often a visible window.
+Setup waits for the window to close. Use a host tool timeout sufficient for a human
+login; cancellation or browser failure is not success. Successful setup initializes
+the profile, but does not prove that every target site is authenticated.
 
-## Power option: clone your daily profile
+## Expired login or rejected instrumented sign-in
 
-Close **all** Chrome windows first (running Chrome locks the profile), then:
+In persistent mode, request the human handoff:
 
-```bash
-cp -R ~/Library/Application\ Support/Google/Chrome/Default ~/.pi/browser-profile
+```text
+browser_reauth({ "url": "https://example.com/" })
 ```
 
-Same macOS user, so Keychain-bound cookies and passwords decrypt fine. Prefer the headed-once flow unless you have dozens of logins — clones carry sync state, extensions, and version skew that cause strange breakage. Never copy while Chrome runs; you'll corrupt both ends.
-
-## Google SSO says "browser or app may not be secure"
+When the provider rejects an instrumented browser, use the plain variant on the
+**same managed identity**, not the user's daily profile:
 
-Expected: Google rejects sign-in from automation-driven Chrome
-(`--enable-automation`, debugging pipe, fresh profile with no history).
-Don't fight it — use one of these instead:
-
-1. **Email + password** on the login form (no Google involved).
-2. **Your daily browser**, which Google already trusts (real history, no
-   automation flags). Point the session at it temporarily with
-   `mode: existing` and drive the flow there, then switch back.
-3. Complete SSO there once; the persistent profile keeps the resulting
-   Cloudflare session cookies either way.
+```text
+browser_reauth({ "url": "https://example.com/", "variant": "plain" })
+```
 
-## What not to do
+Only the human completes SSO, 2FA, CAPTCHA, passkeys and device checks. Stop at the
+challenge; never loop attempts. A live peer-owned backend cannot be restarted or
+reauthenticated by this session: coordinate with its owner instead.
 
-- **Paste passwords or TOTP codes into chat.** The agent never needs them — type directly in the headed window.
-- **Export/import individual cookies** for HttpOnly session cookies. The tooling (keychain decryption, cookie-store surgery) is fragile; a two-minute headed login beats an hour of debugging.
-- **Reuse the persistent profile for hostile links.** Unknown URLs go through `fresh` — no credentials present, nothing to steal.
+## Resume and verify
 
-## Verify
+After human verification, return persistent automation to headless:
 
 ```text
-browser_navigate_page({ "pageId": <id>, "url": "https://github.com/settings/profile" })
-browser_take_snapshot({ "pageId": <id> })
+browser_switch_mode({ "mode": "persistent" })
+browser_list_pages({})
 ```
 
-Your username on the page means the profile is live. If a site challenges headless later (bot checks sometimes do), redo that site with `headed: true` — same profile, same cookies.
+Navigate an explicitly identified page to a benign, task-relevant account page and
+verify its authenticated DOM. For Gmail, load `gmail-auth`; generic Chrome sign-in
+is not proof of Gmail authentication. If only headless execution fails on this
+profile, use persistent headed-background with `rememberSite: true` for that origin,
+not a global downgrade.
+
+Never clone daily Chrome profiles, export/import cookies, or point `userDataDir` at
+the user's daily browser directory. Existing mode is a separate identity and requires
+the user's explicit choice. Its cookies do not migrate back to persistent mode.
+Use fresh mode only for anonymous checks and clean-room reproductions.

package/skills/browser-policy/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: browser-policy
-description: "Browser-use policy for Pi agents. Use before any browser_* tool call. Prefer CLIs and APIs over browser automation, default to fresh headless sessions, escalate to the authenticated profile only on login walls, and never steal user focus."
+description: "Browser-use policy for agents. Use before any browser_* tool call. Prefer CLIs and APIs over browser automation, default to a dedicated persistent headless profile, use fresh mode for anonymous checks, and never steal user focus."
 ---
 
 # Browser Policy
 
+These policies apply to native Pi and portable Agent Plugins/MCP hosts. Call
+`browser_status` for this instance's profile and artifact paths; never infer
+them from another client. Authentication does not transfer between profiles.
+
 `browser_*` tools (this `pi-browser-use` package, powered by `chrome-devtools-mcp` — not Playwright) drive a real Chrome. They are the tool of last resort, not the first.
 
 ## Decision order
@@ -15,14 +19,14 @@ description: "Browser-use policy for Pi agents. Use before any browser_* tool ca
 
 ## Session modes
 
-- **Default: persistent headless** (`mode: persistent`). Pi's own browser on its dedicated profile (`~/.pi/browser-profile`): self-launched Chrome, no window, never steals focus, no consent popups. Log in once via `browser_setup`; cookies persist. Use for everything unless there's a reason not to. Pass `headed: true` to watch, and warn the user before any headed launch.
+- **Default: persistent headless** (`mode: persistent`). The plugin's own browser on its dedicated profile (the profile reported by `browser_status`): self-launched Chrome, no window, never steals focus, no consent popups. Log in once via `browser_setup`; cookies persist. Use for everything unless there's a reason not to. Pass `headed: true` to watch, and warn the user before any headed launch.
 - **Clean room** (`mode: fresh`). Ephemeral profile, thrown away each session. Use for anonymous checks, hostile links, and "does it render logged-out?" verifications — never for anything needing identity.
-- **Existing Chrome** (`mode: existing`) attaches to the user's running Chrome — intrusive (drives the daily browser, sees all tabs). Avoid unless the user explicitly asks. First attach shows Chrome's "Allow remote debugging?" consent popup (once per session — click Allow). Pi tabs must be opened with `browser_open_background_tab` (extension-brokered into the collapsed `pi-browser-use` group), never raw `browser_new_page`. Closing the last Pi tab dissolves the group automatically; `browser_close_page` refuses tabs Pi didn't open unless `force: true` was explicitly requested.
+- **Existing Chrome** (`mode: existing`) attaches to the user's running Chrome — intrusive (drives the daily browser, sees all tabs). Avoid unless the user explicitly asks. First attach shows Chrome's "Allow remote debugging?" consent popup (once per session — click Allow). Agent tabs must be opened with `browser_open_background_tab` (extension-brokered into the collapsed `pi-browser-use` group), never raw `browser_new_page`. Closing the last agent tab dissolves the group automatically; `browser_close_page` refuses tabs this session didn't open unless `force: true` was explicitly requested.
 - **Switch, don't restart**: `browser_switch_mode` moves between persistent, fresh, and existing mid-session. Start persistent; drop to fresh for clean-room checks; touch existing only when the user explicitly asks.
 - **Hard blocks escalate themselves**: login walls in fresh sessions suggest the switch call; login walls and bot challenges in authenticated sessions rebuild headed and prompt the human. Once per call, never looping, never in attached sessions — and a headed popup from a block is the one case where stealing focus is the job, not a bug.
-- **Visual analysis** (`browser_analyze_screenshot`, only when `visionModel` is configured) is for canvas/WebGL scenes and coordinate clicks the tree cannot describe — not a substitute for reading the snapshot first.
+- **Visual analysis** (`browser_analyze_screenshot`, native Pi only when `visionModel` is configured; other hosts analyze the MCP image from `browser_take_screenshot`) is for canvas/WebGL scenes and coordinate clicks the tree cannot describe — not a substitute for reading the snapshot first.
 
-`--chrome-arg` flags only apply when `chrome-devtools-mcp` launches Chrome itself — never with `autoConnect`/`browserUrl`. On macOS `--start-minimized` is ignored; only `headless: true` truly hides the window.
+Chrome flags apply only to a managed launch (direct or upstream), never to an already-running browser attached with `autoConnect`/`browserUrl`. On macOS `--start-minimized` is ignored; only `headless: true` truly hides the window.
 
 ## Bot walls and logins
 
@@ -45,7 +49,7 @@ Turnstile, device checks, SSO/2FA cannot be automated away. On hitting one: stop
 
 ## Parallel agents (shared browser)
 
-Many agents share one Pi-owned Chrome. Separation is by tabs, not windows:
+Many agents share one plugin-owned Chrome. Separation is by tabs, not windows:
 
 - Always pass an explicit `pageId` (from your own `browser_list_pages`) to every page-scoped call. Never assume the selected page is yours.
 - Open your own tabs (`browser_new_page` background, or `browser_open_background_tab` in existing mode). They are claimed to your session automatically.
@@ -55,16 +59,16 @@ Many agents share one Pi-owned Chrome. Separation is by tabs, not windows:
 
 ## Browser mode rules
 
-1. Prefer Persistent (the default) for everything: Pi's browser, invisible, no popups.
+1. Prefer Persistent (the default) for everything: the plugin's browser, invisible, no popups.
 2. Use Fresh only for anonymous/stateless browsing: hostile links, logged-out checks, clean-room reproductions.
-3. Persistent uses Pi's dedicated browser profile — never the user's daily Chrome data.
-4. If Persistent has never been initialized, launch the Pi Browser setup flow (headed once, human signs in, close the window).
+3. Persistent uses the plugin's dedicated browser profile — never the user's daily Chrome data.
+4. If Persistent has never been initialized, launch the managed browser setup flow (headed once, human signs in, close the window).
 5. Never attempt to automate credentials, CAPTCHA, 2FA, passkeys, or security challenges that require the user.
 6. When authentication is required, request the headed authentication flow.
 7. After authentication, prefer restarting Persistent headless.
 8. If a site fails specifically because it is headless, retry using Persistent headed-background (per-origin; never downgrade every site).
-9. In headed-background mode, never request foreground focus unless the user explicitly asked to watch or Pi is handing over auth.
+9. In headed-background mode, never request foreground focus unless the user explicitly asked to watch or the agent is handing over auth.
 10. Use Existing only when the user explicitly chose it or Persistent cannot provide the required existing browser/session state.
-11. In Existing mode, all new Pi tabs must be created through the Pi extension and placed in the collapsed `pi-browser-use` group.
-12. Never activate Pi-created Existing-mode tabs by default.
-13. Never close or modify unrelated user tabs; on session end close only Pi-owned tabs.
+11. In Existing mode, all new agent tabs must be created through the bundled Chrome extension and placed in the collapsed `pi-browser-use` group.
+12. Never activate agent-created Existing-mode tabs by default.
+13. Never close or modify unrelated user tabs; close only this session's explicitly identified tabs; do not assume session shutdown closes tabs in a borrowed browser.

package/skills/gmail-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gmail-auth
-description: "Verify Gmail authentication in the persistent Pi browser profile. Use when a task needs the Gmail inbox, after browser_setup, or when Google shows a login or verification challenge."
+description: "Verify Gmail authentication in the persistent managed browser profile. Use when a task needs the Gmail inbox, after browser_setup, or when Google shows a login or verification challenge."
 ---
 
 # Gmail Auth
@@ -10,11 +10,14 @@ Authentication state lives in this skill, not in a generic browser heuristic: on
 ## Verify first
 
 ```text
-browser_open_background_tab({ "url": "https://mail.google.com/" })
+browser_new_page({ "url": "https://mail.google.com/", "background": true })
 browser_take_snapshot({ "pageId": <id> })
 ```
 
-Or in persistent mode, navigate directly — the persistent profile is Pi's browser, no tab group needed.
+Use the page ID returned by `browser_list_pages`. In explicitly selected Existing
+mode, use `browser_open_background_tab` instead so the bundled Chrome extension
+creates a grouped inactive tab. Check `browser_status` for the active profile; a
+login in another client or daily Chrome does not authenticate this instance.
 
 ## Authenticated