pi-ui-extend 0.1.68 → 0.1.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extend",
-  "version": "0.1.68",
+  "version": "0.1.69",
   "description": "Pix: a workspace-first terminal UI for Pi with tabs, readable tool activity, voice input, and bundled agent tools.",
   "private": false,
   "repository": {

package/skills/playwright-cli/SKILL.md

@@ -6,31 +6,49 @@ allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)
 
 # Browser Automation with playwright-cli
 
+## Required session lifecycle
+
+Browser sessions are daemon-backed and can outlive both a command and its task. Treat each session as an owned resource:
+
+1. Before the first session-scoped command, choose a unique, task-scoped name (semantic prefix plus timestamp/PID or random suffix), confirm it is not already in `playwright-cli list`, and record the exact name in task state as owned by this task. Do not create automation in the shared `default` session.
+2. Pass that exact name with `-s=<name>` to **every** command. In examples, `$SESSION` is shorthand for the recorded literal; do not assume shell variables persist between tool calls.
+3. As soon as the session is created, plan cleanup for success, failure, cancellation, and timeout. In a shell script, install an `EXIT INT TERM` trap immediately after registering the name.
+4. Before the final response—and on every error path—run `playwright-cli -s=<owned-name> close`. Then run `playwright-cli list` and verify that the exact owned name is absent. If it remains, retry the session-specific close and investigate before finishing.
+
+Only close sessions registered as owned by the current task. `close-all` and `kill-all` can disrupt other agents or users and are not routine cleanup. Use `kill-all` only as an emergency fallback when session-specific cleanup cannot remove a confirmed stale daemon, after checking `list` and either confirming every listed session is yours or obtaining user approval.
+
+For sessions attached to an external browser, use a unique name but `detach` instead of `close`; do not close the external browser. Only attach to a user's regular Chrome/Edge when explicitly requested. For `--debug=cli` sessions, also stop the background test process that owns the browser and verify its generated session is gone.
+
 ## Quick start
 
 ```bash
+# Pick once and record as owned; use this exact value for the whole task.
+SESSION="docs-check-$(date +%s)-$$"
 # open new browser
-playwright-cli open
+playwright-cli -s="$SESSION" open
 # navigate to a page
-playwright-cli goto https://playwright.dev
+playwright-cli -s="$SESSION" goto https://playwright.dev
 # interact with the page using refs from the snapshot
-playwright-cli click e15
-playwright-cli type "page.click"
-playwright-cli press Enter
+playwright-cli -s="$SESSION" click e15
+playwright-cli -s="$SESSION" type "page.click"
+playwright-cli -s="$SESSION" press Enter
 # take a screenshot (rarely used, as snapshot is more common)
-playwright-cli screenshot
-# close the browser
-playwright-cli close
+playwright-cli -s="$SESSION" screenshot
+# mandatory task cleanup, including error paths
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify the exact value of $SESSION is absent
 ```
 
 ## Commands
 
+Most of the command catalog omits `-s="$SESSION"` for readability. When executing it, always target the unique session registered under [Required session lifecycle](#required-session-lifecycle); session creation and cleanup show the option explicitly.
+
 ### Core
 
 ```bash
-playwright-cli open
+playwright-cli -s="$SESSION" open
 # open and navigate right away
-playwright-cli open https://example.com/
+playwright-cli -s="$SESSION" open https://example.com/
 playwright-cli goto https://playwright.dev
 playwright-cli type "search query"
 playwright-cli click e3
@@ -56,7 +74,7 @@ playwright-cli dialog-accept
 playwright-cli dialog-accept "confirmation text"
 playwright-cli dialog-dismiss
 playwright-cli resize 1920 1080
-playwright-cli close
+playwright-cli -s="$SESSION" close
 ```
 
 ### Navigation
@@ -200,33 +218,34 @@ playwright-cli list --json
 ## Open parameters
 ```bash
 # Use specific browser when creating session
-playwright-cli open --browser=chrome
-playwright-cli open --browser=firefox
-playwright-cli open --browser=webkit
-playwright-cli open --browser=msedge
+playwright-cli -s="$SESSION" open --browser=chrome
+playwright-cli -s="$SESSION" open --browser=firefox
+playwright-cli -s="$SESSION" open --browser=webkit
+playwright-cli -s="$SESSION" open --browser=msedge
 
 # Use persistent profile (by default profile is in-memory)
-playwright-cli open --persistent
+playwright-cli -s="$SESSION" open --persistent
 # Use persistent profile with custom directory
-playwright-cli open --profile=/path/to/profile
+playwright-cli -s="$SESSION" open --profile=/path/to/profile
 
 # Connect to browser via Playwright Extension
-playwright-cli attach --extension=chrome
+playwright-cli -s="$SESSION" attach --extension=chrome
 
 # Connect to a running Chrome or Edge by channel name
-playwright-cli attach --cdp=chrome
-playwright-cli attach --cdp=msedge
+playwright-cli -s="$SESSION" attach --cdp=chrome
+playwright-cli -s="$SESSION" attach --cdp=msedge
 
 # Connect to a running browser via CDP endpoint
-playwright-cli attach --cdp=http://localhost:9222
+playwright-cli -s="$SESSION" attach --cdp=http://localhost:9222
 
 # Start with config file
-playwright-cli open --config=my-config.json
+playwright-cli -s="$SESSION" open --config=my-config.json
 
-# Close the browser
-playwright-cli close
+# Close and verify an owned browser
+playwright-cli -s="$SESSION" close
+playwright-cli list
 # Detach from an attached browser (leaves the external browser running)
-playwright-cli -s=msedge detach
+playwright-cli -s="$SESSION" detach
 # Delete user data for the default session
 playwright-cli delete-data
 ```
@@ -292,21 +311,23 @@ playwright-cli click "getByTestId('submit-button')"
 ## Browser Sessions
 
 ```bash
-# create new browser session named "mysession" with persistent profile
-playwright-cli -s=mysession open example.com --persistent
-# same with manually specified profile directory (use when requested explicitly)
-playwright-cli -s=mysession open example.com --profile=/path/to/profile
-playwright-cli -s=mysession click e6
-playwright-cli -s=mysession close  # stop a named browser
-playwright-cli -s=mysession delete-data  # delete user data for persistent session
+# Choose a unique name once and register it as owned by this task.
+SESSION="profile-check-$(date +%s)-$$"
+# Choose either persistent option, not both.
+# Auto-generated profile location:
+playwright-cli -s="$SESSION" open example.com --persistent
+# Or a manually specified profile directory (only when requested explicitly):
+playwright-cli -s="$SESSION" open example.com --profile=/path/to/profile
+playwright-cli -s="$SESSION" click e6
+playwright-cli -s="$SESSION" delete-data  # delete user data if requested
+playwright-cli -s="$SESSION" close        # mandatory on success and errors
+playwright-cli list                        # verify $SESSION is absent
 
 playwright-cli list
-# Close all browsers
-playwright-cli close-all
-# Forcefully kill all browser processes
-playwright-cli kill-all
 ```
 
+The global commands `playwright-cli close-all` and `playwright-cli kill-all` may affect sessions owned by others. Do not use them for this workflow; follow the emergency-only policy above.
+
 ## Installation
 
 If global `playwright-cli` command is not available, try a local version via `npx playwright-cli`:
@@ -324,45 +345,53 @@ npm install -g @playwright/cli@latest
 ## Example: Form submission
 
 ```bash
-playwright-cli open https://example.com/form
-playwright-cli snapshot
-
-playwright-cli fill e1 "user@example.com"
-playwright-cli fill e2 "password123"
-playwright-cli click e3
-playwright-cli snapshot
-playwright-cli close
+SESSION="form-check-$(date +%s)-$$"
+playwright-cli -s="$SESSION" open https://example.com/form
+playwright-cli -s="$SESSION" snapshot
+
+playwright-cli -s="$SESSION" fill e1 "user@example.com"
+playwright-cli -s="$SESSION" fill e2 "password123"
+playwright-cli -s="$SESSION" click e3
+playwright-cli -s="$SESSION" snapshot
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ## Example: Multi-tab workflow
 
 ```bash
-playwright-cli open https://example.com
-playwright-cli tab-new https://example.com/other
-playwright-cli tab-list
-playwright-cli tab-select 0
-playwright-cli snapshot
-playwright-cli close
+SESSION="tabs-check-$(date +%s)-$$"
+playwright-cli -s="$SESSION" open https://example.com
+playwright-cli -s="$SESSION" tab-new https://example.com/other
+playwright-cli -s="$SESSION" tab-list
+playwright-cli -s="$SESSION" tab-select 0
+playwright-cli -s="$SESSION" snapshot
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ## Example: Debugging with DevTools
 
 ```bash
-playwright-cli open https://example.com
-playwright-cli click e4
-playwright-cli fill e7 "test"
-playwright-cli console
-playwright-cli requests
-playwright-cli close
+SESSION="devtools-check-$(date +%s)-$$"
+playwright-cli -s="$SESSION" open https://example.com
+playwright-cli -s="$SESSION" click e4
+playwright-cli -s="$SESSION" fill e7 "test"
+playwright-cli -s="$SESSION" console
+playwright-cli -s="$SESSION" requests
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ```bash
-playwright-cli open https://example.com
-playwright-cli tracing-start
-playwright-cli click e4
-playwright-cli fill e7 "test"
-playwright-cli tracing-stop
-playwright-cli close
+SESSION="trace-check-$(date +%s)-$$"
+playwright-cli -s="$SESSION" open https://example.com
+playwright-cli -s="$SESSION" tracing-start
+playwright-cli -s="$SESSION" click e4
+playwright-cli -s="$SESSION" fill e7 "test"
+playwright-cli -s="$SESSION" tracing-stop
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ## Example: Interactive session
@@ -370,8 +399,11 @@ playwright-cli close
 Ask the user for UI review or design feedback. The user draws boxes on the live page and types comments; you receive the annotated screenshot, the snapshot of the marked region, and the user's notes. Use this whenever the user asks for "UI review", "design feedback", or to "ask the user what they think / want / mean":
 
 ```bash
-playwright-cli open https://example.com
-playwright-cli show --annotate
+SESSION="ui-review-$(date +%s)-$$"
+playwright-cli -s="$SESSION" open https://example.com
+playwright-cli -s="$SESSION" show --annotate
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ## Specific tasks

package/skills/playwright-cli/references/playwright-tests.md

@@ -14,13 +14,14 @@ PLAYWRIGHT_HTML_OPEN=never npm run special-test-command
 
 To debug a failing Playwright test, run it with `--debug=cli` option. This command will pause the test at the start and print the debugging instructions.
 
-**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed. Make sure to stop the command after you have finished.
+**IMPORTANT**: run the command in the background, record its PID as owned by the task, and check the output until "Debugging Instructions" is printed. As soon as the generated `tw-...` name appears, register that exact session as owned by this debug run. Plan cleanup immediately: on success, failure, interruption, or timeout, detach the CLI session, stop and reap the background test PID, then check `playwright-cli list` and verify the generated name is absent.
 
 Once instructions containing a session name are printed, use `playwright-cli` to attach the session and explore the page.
 
 ```bash
-# Run the test
-PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
+# Run the test in the background and retain ownership of its PID.
+PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli > playwright-debug.log 2>&1 &
+TEST_PID=$!
 # ...
 # ... debugging instructions for "tw-abcdef" session ...
 # ...
@@ -36,4 +37,14 @@ where the problem is most likely to be.
 Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
 This code appears in the output and can be copied directly into the test. Most of the time, a specific locator or an expectation should be updated, but it could also be a bug in the app. Use your judgement.
 
-After fixing the test, stop the background test run. Rerun to check that test passes.
+After fixing the test, clean up before rerunning or responding:
+
+```bash
+# Detach does not close an external browser. Ignore "not attached" if the test already exited.
+playwright-cli -s=tw-abcdef detach || true
+kill "$TEST_PID" 2>/dev/null || true
+wait "$TEST_PID" 2>/dev/null || true
+playwright-cli list  # verify tw-abcdef is absent
+```
+
+Do not use `close-all` or `kill-all`: other debug or automation sessions may belong to another task. Rerun normally to check that the test passes.

package/skills/playwright-cli/references/session-management.md

@@ -2,20 +2,38 @@
 
 Run multiple isolated browser sessions concurrently with state persistence.
 
+## Ownership and cleanup contract
+
+Browser sessions are backed by daemons and can survive the task that created them. Before the first session-scoped command:
+
+1. Generate a unique task-scoped name (semantic purpose plus timestamp/PID or random suffix).
+2. Confirm the candidate is absent from `playwright-cli list`, then record the exact name in the task's owned-session list. Do not use `default` for agent automation.
+3. Use that exact name on every command. `$SESSION` below is shorthand for the recorded literal, not a shell variable that can be assumed to persist between tool calls.
+4. On success, error, cancellation, or timeout, close each session owned by the task individually, then run `playwright-cli list` and verify every owned name is absent. Retry a session-specific close if needed.
+
+Never close a session merely because it looks stale: it may belong to another agent or user. Do not use `close-all` or `kill-all` as normal cleanup.
+
 ## Named Browser Sessions
 
 Use `-s` flag to isolate browser contexts:
 
 ```bash
+AUTH_SESSION="auth-check-$(date +%s)-$$"
+PUBLIC_SESSION="public-check-$(date +%s)-$$"
 # Browser 1: Authentication flow
-playwright-cli -s=auth open https://app.example.com/login
+playwright-cli -s="$AUTH_SESSION" open https://app.example.com/login
 
 # Browser 2: Public browsing (separate cookies, storage)
-playwright-cli -s=public open https://example.com
+playwright-cli -s="$PUBLIC_SESSION" open https://example.com
 
 # Commands are isolated by browser session
-playwright-cli -s=auth fill e1 "user@example.com"
-playwright-cli -s=public snapshot
+playwright-cli -s="$AUTH_SESSION" fill e1 "user@example.com"
+playwright-cli -s="$PUBLIC_SESSION" snapshot
+
+# Mandatory cleanup, including error paths
+playwright-cli -s="$AUTH_SESSION" close
+playwright-cli -s="$PUBLIC_SESSION" close
+playwright-cli list  # verify both exact names are absent
 ```
 
 ## Browser Session Isolation Properties
@@ -34,19 +52,11 @@ Each browser session has independent:
 # List all browser sessions
 playwright-cli list
 
-# Stop a browser session (close the browser)
-playwright-cli close                # stop the default browser
-playwright-cli -s=mysession close   # stop a named browser
-
-# Stop all browser sessions
-playwright-cli close-all
+# Stop a browser session owned by this task
+playwright-cli -s="$OWNED_SESSION" close
 
-# Forcefully kill all daemon processes (for stale/zombie processes)
-playwright-cli kill-all
-
-# Delete browser session user data (profile directory)
-playwright-cli delete-data                # delete default browser data
-playwright-cli -s=mysession delete-data   # delete named browser data
+# Delete user data for a persistent session owned by this task
+playwright-cli -s="$OWNED_SESSION" delete-data
 ```
 
 ## Environment Variable
@@ -54,43 +64,70 @@ playwright-cli -s=mysession delete-data   # delete named browser data
 Set a default browser session name via environment variable:
 
 ```bash
-export PLAYWRIGHT_CLI_SESSION="mysession"
-playwright-cli open example.com  # Uses "mysession" automatically
+export PLAYWRIGHT_CLI_SESSION="env-check-$(date +%s)-$$"
+playwright-cli list  # first confirm $PLAYWRIGHT_CLI_SESSION is absent
+playwright-cli -s="$PLAYWRIGHT_CLI_SESSION" open example.com
+playwright-cli -s="$PLAYWRIGHT_CLI_SESSION" close
+playwright-cli list  # verify $PLAYWRIGHT_CLI_SESSION is absent
+unset PLAYWRIGHT_CLI_SESSION
 ```
 
+For agent tasks, prefer an explicit unique `-s=<owned-name>` on every command. Environment variables may not persist across tool calls, and a fixed value such as `mysession` can collide with another task.
+
 ## Common Patterns
 
 ### Concurrent Scraping
 
 ```bash
 #!/bin/bash
+set -u
 # Scrape multiple sites concurrently
 
+sessions=(
+  "site1-$(date +%s)-$$-1"
+  "site2-$(date +%s)-$$-2"
+  "site3-$(date +%s)-$$-3"
+)
+
+cleanup() {
+  for session in "${sessions[@]}"; do
+    playwright-cli -s="$session" close || true
+  done
+  # Inspect this output and verify every name above is absent.
+  playwright-cli list
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
 # Start all browsers
-playwright-cli -s=site1 open https://site1.com &
-playwright-cli -s=site2 open https://site2.com &
-playwright-cli -s=site3 open https://site3.com &
+playwright-cli -s="${sessions[0]}" open https://site1.com &
+playwright-cli -s="${sessions[1]}" open https://site2.com &
+playwright-cli -s="${sessions[2]}" open https://site3.com &
 wait
 
 # Take snapshots from each
-playwright-cli -s=site1 snapshot
-playwright-cli -s=site2 snapshot
-playwright-cli -s=site3 snapshot
-
-# Cleanup
-playwright-cli close-all
+playwright-cli -s="${sessions[0]}" snapshot
+playwright-cli -s="${sessions[1]}" snapshot
+playwright-cli -s="${sessions[2]}" snapshot
 ```
 
 ### A/B Testing Sessions
 
 ```bash
+VARIANT_A="variant-a-$(date +%s)-$$"
+VARIANT_B="variant-b-$(date +%s)-$$"
 # Test different user experiences
-playwright-cli -s=variant-a open "https://app.com?variant=a"
-playwright-cli -s=variant-b open "https://app.com?variant=b"
+playwright-cli -s="$VARIANT_A" open "https://app.com?variant=a"
+playwright-cli -s="$VARIANT_B" open "https://app.com?variant=b"
 
 # Compare
-playwright-cli -s=variant-a screenshot
-playwright-cli -s=variant-b screenshot
+playwright-cli -s="$VARIANT_A" screenshot
+playwright-cli -s="$VARIANT_B" screenshot
+
+playwright-cli -s="$VARIANT_A" close
+playwright-cli -s="$VARIANT_B" close
+playwright-cli list  # verify both exact names are absent
 ```
 
 ### Persistent Profile
@@ -98,11 +135,15 @@ playwright-cli -s=variant-b screenshot
 By default, browser profile is kept in memory only. Use `--persistent` flag on `open` to persist the browser profile to disk:
 
 ```bash
-# Use persistent profile (auto-generated location)
-playwright-cli open https://example.com --persistent
+SESSION="persistent-check-$(date +%s)-$$"
+# Choose one persistent-profile option. Auto-generated location:
+playwright-cli -s="$SESSION" open https://example.com --persistent
 
-# Use persistent profile with custom directory
-playwright-cli open https://example.com --profile=/path/to/profile
+# Or a custom directory:
+playwright-cli -s="$SESSION" open https://example.com --profile=/path/to/profile
+
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ## Attaching to a Running Browser
@@ -111,32 +152,40 @@ Use `attach` to connect to a browser that is already running, instead of launchi
 
 ### Attach by channel name
 
-Connect to a running Chrome or Edge instance by its channel name. The browser must have remote debugging enabled — navigate to `chrome://inspect/#remote-debugging` in the target browser and check "Allow remote debugging for this browser instance".
+Connect to a running Chrome or Edge instance by its channel name only when the user explicitly requests interaction with that external browser. The browser must have remote debugging enabled — navigate to `chrome://inspect/#remote-debugging` in the target browser and check "Allow remote debugging for this browser instance".
 
 ```bash
+SESSION="external-debug-$(date +%s)-$$"
 # Attach to Chrome
-playwright-cli attach --cdp=chrome
+playwright-cli -s="$SESSION" attach --cdp=chrome
 
 # Attach to Chrome Canary
-playwright-cli attach --cdp=chrome-canary
+playwright-cli -s="$SESSION" attach --cdp=chrome-canary
 
 # Attach to Microsoft Edge
-playwright-cli attach --cdp=msedge
+playwright-cli -s="$SESSION" attach --cdp=msedge
 
 # Attach to Edge Dev
-playwright-cli attach --cdp=msedge-dev
+playwright-cli -s="$SESSION" attach --cdp=msedge-dev
+
+# End the CLI attachment without closing the external browser
+playwright-cli -s="$SESSION" detach
+playwright-cli list  # verify $SESSION is absent
 ```
 
 Supported channels: `chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`, `msedge-beta`, `msedge-dev`, `msedge-canary`.
 
-When `--session` is not provided, the session is named after the channel (e.g. `--cdp=msedge` creates a session called `msedge`), so parallel attaches to Chrome and Edge don't collide on `default`. Pass `--session=<name>` to override.
+When `--session` is not provided, the session is named after the channel (for example, `msedge`). Agent tasks must override this with their unique owned name so they do not collide with another task.
 
 ### Attach via CDP endpoint
 
 Connect to a browser that exposes a Chrome DevTools Protocol endpoint:
 
 ```bash
-playwright-cli attach --cdp=http://localhost:9222
+SESSION="cdp-debug-$(date +%s)-$$"
+playwright-cli -s="$SESSION" attach --cdp=http://localhost:9222
+playwright-cli -s="$SESSION" detach
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ### Attach via browser extension
@@ -144,7 +193,10 @@ playwright-cli attach --cdp=http://localhost:9222
 Connect to a browser with the Playwright extension installed:
 
 ```bash
-playwright-cli attach --extension
+SESSION="extension-debug-$(date +%s)-$$"
+playwright-cli -s="$SESSION" attach --extension
+playwright-cli -s="$SESSION" detach
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ### Detach
@@ -152,74 +204,70 @@ playwright-cli attach --extension
 Tear down an attached session without affecting the external browser:
 
 ```bash
-# Detach the default attached session
-playwright-cli detach
-
 # Detach a specific attached session
-playwright-cli -s=msedge detach
+playwright-cli -s="$SESSION" detach
+playwright-cli list  # verify the exact owned name is absent
 ```
 
 `detach` only works on sessions created via `attach`. For sessions created via `open`, use `close`.
 
-## Default Browser Session
+## Default Browser Session (avoid for agent-created browsers)
 
-When `-s` is omitted, commands use the default browser session:
-
-```bash
-# These use the same default browser session
-playwright-cli open https://example.com
-playwright-cli snapshot
-playwright-cli close  # Stops default browser
-```
+When `-s` is omitted, commands use a shared session named `default`. Do not use this legacy behavior for agent-created browsers: ownership is ambiguous and concurrent tasks can collide.
 
 ## Browser Session Configuration
 
 Configure a browser session with specific settings when opening:
 
 ```bash
-# Open with config file
-playwright-cli open https://example.com --config=.playwright/my-cli.json
+SESSION="configured-check-$(date +%s)-$$"
+# Choose one of these open configurations.
+# Config file:
+playwright-cli -s="$SESSION" open https://example.com --config=.playwright/my-cli.json
 
 # Open with specific browser
-playwright-cli open https://example.com --browser=firefox
+playwright-cli -s="$SESSION" open https://example.com --browser=firefox
 
 # Open in headed mode
-playwright-cli open https://example.com --headed
+playwright-cli -s="$SESSION" open https://example.com --headed
 
 # Open with persistent profile
-playwright-cli open https://example.com --persistent
+playwright-cli -s="$SESSION" open https://example.com --persistent
+
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ## Best Practices
 
-### 1. Name Browser Sessions Semantically
+### 1. Name Browser Sessions Uniquely and Semantically
 
 ```bash
-# GOOD: Clear purpose
-playwright-cli -s=github-auth open https://github.com
-playwright-cli -s=docs-scrape open https://docs.example.com
-
-# AVOID: Generic names
-playwright-cli -s=s1 open https://github.com
+# GOOD: Clear purpose plus a per-task uniqueness suffix.
+SESSION="github-auth-$(date +%s)-$$"
+playwright-cli -s="$SESSION" open https://github.com
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
+Avoid shared, generic, or reusable names such as `s1` or `github-auth`, and never omit `-s` for a session the task creates.
+
 ### 2. Always Clean Up
 
 ```bash
-# Stop browsers when done
-playwright-cli -s=auth close
-playwright-cli -s=scrape close
+# Stop only browsers registered as owned by this task, including on errors.
+playwright-cli -s="$AUTH_SESSION" close
+playwright-cli -s="$SCRAPE_SESSION" close
+playwright-cli list  # verify both exact names are absent
+```
 
-# Or stop all at once
-playwright-cli close-all
+### 3. Reserve Global Cleanup for Emergencies
 
-# If browsers become unresponsive or zombie processes remain
-playwright-cli kill-all
-```
+If session-specific `close` repeatedly fails and a daemon is confirmed stale, inspect `playwright-cli list`. Use `kill-all` only if every listed session belongs to the current task or the user approves disrupting foreign sessions. `close-all` has the same ownership risk and is not a shortcut for tracked cleanup. Never use either command to manage the user's ordinary Chrome/Edge processes.
 
-### 3. Delete Stale Browser Data
+### 4. Delete Stale Browser Data
 
 ```bash
 # Remove old browser data to free disk space
-playwright-cli -s=oldsession delete-data
+playwright-cli -s="$OWNED_SESSION" delete-data
 ```

package/skills/playwright-cli/references/spec-driven-testing.md

@@ -8,6 +8,8 @@ End-to-end workflow for authoring and maintaining Playwright tests using `playwr
 
 All three lean on the same mechanic: run `npx playwright test --debug=cli` in the background, then `playwright-cli attach tw-XXXX` to drive the paused page interactively. See [playwright-tests.md](playwright-tests.md) for the debug/attach mechanics and [test-generation.md](test-generation.md) for how every `playwright-cli` action emits Playwright TypeScript.
 
+Each debug run owns two resources: the background test PID and the unique generated `tw-XXXX` session. Record both as soon as they exist. On success, failure, interruption, or timeout, detach that exact CLI session, stop and reap that exact PID, and verify the session name is absent from `playwright-cli list` before starting another run or responding. Never substitute `close-all` or `kill-all`, because other sessions may have different owners.
+
 ---
 
 ## 1. Planning
@@ -76,7 +78,8 @@ If no seed exists, create one that at least navigates to the app.
 Launch the app via the seed in the background and attach:
 
 ```bash
-PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/seed.spec.ts --debug=cli
+PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/seed.spec.ts --debug=cli > playwright-debug.log 2>&1 &
+TEST_PID=$!
 # wait for "Debugging Instructions" and the session name tw-XXXX
 playwright-cli attach tw-XXXX
 ```
@@ -100,7 +103,7 @@ Map out:
 - Navigation: which controls change the URL, back/forward behaviour.
 
 **Important**: Do not just open the app url with playwright-cli, always go through the test to capture any custom setup done there.
-**Important**: Stop the background test when done exploring.
+**Important**: When done exploring, run `playwright-cli -s=tw-XXXX detach`, stop and `wait` for `$TEST_PID`, then run `playwright-cli list` and verify `tw-XXXX` is absent.
 
 ### 1.4 Write the spec file
 
@@ -164,7 +167,9 @@ Goal: take a spec file and produce Playwright test files. Optionally update the
 For each target scenario, in sequence (never in parallel — scenarios share the seed session):
 
 ```bash
-PLAYWRIGHT_HTML_OPEN=never npx playwright test <seed-file> --debug=cli   # background
+PLAYWRIGHT_HTML_OPEN=never npx playwright test <seed-file> --debug=cli > playwright-debug.log 2>&1 &
+TEST_PID=$!
+# Read the log, register the generated session name, then attach.
 playwright-cli attach tw-XXXX
 # resume
 ```
@@ -216,11 +221,11 @@ Rules:
 - Prefix each numbered step with a `// N. <step text>` comment before its actions.
 - Use the describe group name verbatim from the spec (no `1.` ordinal).
 - Import from `./fixtures` if the project has one; otherwise `@playwright/test`.
-- **Important**: close the CLI session and stop the background test before moving to the next scenario.
+- **Important**: detach the exact `tw-XXXX` CLI session, stop and reap `$TEST_PID`, and verify the session is absent from `playwright-cli list` before moving to the next scenario.
 
 ### 2.3 Generate multiple scenarios
 
-Loop 2.2 over the targeted scenarios one at a time, restarting the seed between each so every test starts from a clean page. This is safe to parallelise due to unique generated session names - just make sure each test run is stopped.
+Loop 2.2 over the targeted scenarios one at a time, restarting the seed between each so every test starts from a clean page. Keep this sequential as required above; unique generated names prevent collisions but do not replace per-run ownership and verified cleanup.
 
 ### 2.4 Run generated tests
 
@@ -251,7 +256,8 @@ Record the list of failing `<file>:<line>` entries and process them one at a tim
 Run the single failing test in debug mode in the background, then attach:
 
 ```bash
-PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts:<line> --debug=cli
+PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts:<line> --debug=cli > playwright-debug.log 2>&1 &
+TEST_PID=$!
 # wait for "Debugging Instructions" and the tw-XXXX session name
 playwright-cli attach tw-XXXX
 ```
@@ -271,7 +277,7 @@ Rehearse the corrected interaction with `playwright-cli` — the generated code
 
 ### 3.3 Apply the fix
 
-Edit the test file: update the locator, assertion, step order, or inputs to match the corrected behaviour. Stop the background debug run. Rerun the single test to confirm green.
+Edit the test file: update the locator, assertion, step order, or inputs to match the corrected behaviour. Detach the exact generated CLI session, stop and reap the background debug PID, and verify the session name is absent from `playwright-cli list`. Then rerun the single test to confirm green.
 
 Never skip hooks or add sleeps as a fix. Never use `networkidle`.
 

package/skills/playwright-cli/references/storage-state.md

@@ -19,11 +19,14 @@ playwright-cli state-save my-auth-state.json
 ### Restore Storage State
 
 ```bash
+SESSION="state-restore-$(date +%s)-$$"  # record as owned before first command
 # Load storage state from file
-playwright-cli state-load my-auth-state.json
+playwright-cli -s="$SESSION" state-load my-auth-state.json
 
 # Reload page to apply cookies
-playwright-cli open https://example.com
+playwright-cli -s="$SESSION" open https://example.com
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ### Storage State File Format
@@ -233,37 +236,49 @@ playwright-cli run-code "async page => {
 
 ```bash
 # Step 1: Login and save state
-playwright-cli open https://app.example.com/login
-playwright-cli snapshot
-playwright-cli fill e1 "user@example.com"
-playwright-cli fill e2 "password123"
-playwright-cli click e3
+LOGIN_SESSION="auth-save-$(date +%s)-$$"
+playwright-cli -s="$LOGIN_SESSION" open https://app.example.com/login
+playwright-cli -s="$LOGIN_SESSION" snapshot
+playwright-cli -s="$LOGIN_SESSION" fill e1 "user@example.com"
+playwright-cli -s="$LOGIN_SESSION" fill e2 "password123"
+playwright-cli -s="$LOGIN_SESSION" click e3
 
 # Save the authenticated state
-playwright-cli state-save auth.json
+playwright-cli -s="$LOGIN_SESSION" state-save auth.json
+playwright-cli -s="$LOGIN_SESSION" close
+playwright-cli list  # verify $LOGIN_SESSION is absent
 
 # Step 2: Later, restore state and skip login
-playwright-cli state-load auth.json
-playwright-cli open https://app.example.com/dashboard
+RESTORE_SESSION="auth-restore-$(date +%s)-$$"
+playwright-cli -s="$RESTORE_SESSION" state-load auth.json
+playwright-cli -s="$RESTORE_SESSION" open https://app.example.com/dashboard
 # Already logged in!
+playwright-cli -s="$RESTORE_SESSION" close
+playwright-cli list  # verify $RESTORE_SESSION is absent
 ```
 
 ### Save and Restore Roundtrip
 
 ```bash
 # Set up authentication state
-playwright-cli open https://example.com
-playwright-cli eval "() => { document.cookie = 'session=abc123'; localStorage.setItem('user', 'john'); }"
+SAVE_SESSION="state-save-$(date +%s)-$$"
+playwright-cli -s="$SAVE_SESSION" open https://example.com
+playwright-cli -s="$SAVE_SESSION" eval "() => { document.cookie = 'session=abc123'; localStorage.setItem('user', 'john'); }"
 
 # Save state to file
-playwright-cli state-save my-session.json
+playwright-cli -s="$SAVE_SESSION" state-save my-session.json
+playwright-cli -s="$SAVE_SESSION" close
+playwright-cli list  # verify $SAVE_SESSION is absent
 
 # ... later, in a new session ...
 
 # Restore state
-playwright-cli state-load my-session.json
-playwright-cli open https://example.com
+LOAD_SESSION="state-load-$(date +%s)-$$"
+playwright-cli -s="$LOAD_SESSION" state-load my-session.json
+playwright-cli -s="$LOAD_SESSION" open https://example.com
 # Cookies and localStorage are restored!
+playwright-cli -s="$LOAD_SESSION" close
+playwright-cli list  # verify $LOAD_SESSION is absent
 ```
 
 ## Security Notes

package/skills/playwright-cli/references/test-generation.md

@@ -10,25 +10,30 @@ This code appears in the output and can be copied directly into your test files.
 ## Example Workflow
 
 ```bash
-# Start a session
-playwright-cli open https://example.com/login
+# Choose a unique name, record it as owned by this task, and start the session.
+SESSION="testgen-login-$(date +%s)-$$"
+playwright-cli -s="$SESSION" open https://example.com/login
 
 # Take a snapshot to see elements
-playwright-cli snapshot
+playwright-cli -s="$SESSION" snapshot
 # Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
 
 # Fill form fields - generates code automatically
-playwright-cli fill e1 "user@example.com"
+playwright-cli -s="$SESSION" fill e1 "user@example.com"
 # Ran Playwright code:
 # await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
 
-playwright-cli fill e2 "password123"
+playwright-cli -s="$SESSION" fill e2 "password123"
 # Ran Playwright code:
 # await page.getByRole('textbox', { name: 'Password' }).fill('password123');
 
-playwright-cli click e3
+playwright-cli -s="$SESSION" click e3
 # Ran Playwright code:
 # await page.getByRole('button', { name: 'Sign In' }).click();
+
+# Mandatory on success and errors.
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ## Building a Test File
@@ -69,10 +74,13 @@ await page.locator('#submit-btn').click();
 Take snapshots to understand the page structure before recording actions:
 
 ```bash
-playwright-cli open https://example.com
-playwright-cli snapshot
+SESSION="testgen-explore-$(date +%s)-$$"
+playwright-cli -s="$SESSION" open https://example.com
+playwright-cli -s="$SESSION" snapshot
 # Review the element structure
-playwright-cli click e5
+playwright-cli -s="$SESSION" click e5
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ### 3. Add Assertions Manually

package/skills/playwright-cli/references/tracing.md

@@ -5,16 +5,19 @@ Capture detailed execution traces for debugging and analysis. Traces include DOM
 ## Basic Usage
 
 ```bash
+SESSION="trace-basic-$(date +%s)-$$"  # record as owned before first command
 # Start trace recording
-playwright-cli tracing-start
+playwright-cli -s="$SESSION" tracing-start
 
 # Perform actions
-playwright-cli open https://example.com
-playwright-cli click e1
-playwright-cli fill e2 "test"
+playwright-cli -s="$SESSION" open https://example.com
+playwright-cli -s="$SESSION" click e1
+playwright-cli -s="$SESSION" fill e2 "test"
 
 # Stop trace recording
-playwright-cli tracing-stop
+playwright-cli -s="$SESSION" tracing-stop
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ## Trace Output Files
@@ -64,22 +67,28 @@ When you start tracing, Playwright creates a `traces/` directory with several fi
 ### Debugging Failed Actions
 
 ```bash
-playwright-cli tracing-start
-playwright-cli open https://app.example.com
+SESSION="trace-failure-$(date +%s)-$$"
+playwright-cli -s="$SESSION" tracing-start
+playwright-cli -s="$SESSION" open https://app.example.com
 
 # This click fails - why?
-playwright-cli click e5
+playwright-cli -s="$SESSION" click e5
 
-playwright-cli tracing-stop
+playwright-cli -s="$SESSION" tracing-stop
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 # Open trace to see DOM state when click was attempted
 ```
 
 ### Analyzing Performance
 
 ```bash
-playwright-cli tracing-start
-playwright-cli open https://slow-site.com
-playwright-cli tracing-stop
+SESSION="trace-performance-$(date +%s)-$$"
+playwright-cli -s="$SESSION" tracing-start
+playwright-cli -s="$SESSION" open https://slow-site.com
+playwright-cli -s="$SESSION" tracing-stop
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 
 # View network waterfall to identify slow resources
 ```
@@ -88,15 +97,18 @@ playwright-cli tracing-stop
 
 ```bash
 # Record a complete user flow for documentation
-playwright-cli tracing-start
-
-playwright-cli open https://app.example.com/checkout
-playwright-cli fill e1 "4111111111111111"
-playwright-cli fill e2 "12/25"
-playwright-cli fill e3 "123"
-playwright-cli click e4
-
-playwright-cli tracing-stop
+SESSION="trace-evidence-$(date +%s)-$$"
+playwright-cli -s="$SESSION" tracing-start
+
+playwright-cli -s="$SESSION" open https://app.example.com/checkout
+playwright-cli -s="$SESSION" fill e1 "4111111111111111"
+playwright-cli -s="$SESSION" fill e2 "12/25"
+playwright-cli -s="$SESSION" fill e3 "123"
+playwright-cli -s="$SESSION" click e4
+
+playwright-cli -s="$SESSION" tracing-stop
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 # Trace shows exact sequence of events
 ```
 
@@ -117,10 +129,13 @@ playwright-cli tracing-stop
 
 ```bash
 # Trace the entire flow, not just the failing step
-playwright-cli tracing-start
-playwright-cli open https://example.com
+SESSION="trace-flow-$(date +%s)-$$"
+playwright-cli -s="$SESSION" tracing-start
+playwright-cli -s="$SESSION" open https://example.com
 # ... all steps leading to the issue ...
-playwright-cli tracing-stop
+playwright-cli -s="$SESSION" tracing-stop
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ### 2. Clean Up Old Traces

package/skills/playwright-cli/references/video-recording.md

@@ -5,26 +5,30 @@ Capture browser automation sessions as video for debugging, documentation, or ve
 ## Basic Recording
 
 ```bash
+# Choose a unique name and record it as owned before opening.
+SESSION="video-demo-$(date +%s)-$$"
 # Open browser first
-playwright-cli open
+playwright-cli -s="$SESSION" open
 
 # Start recording
-playwright-cli video-start demo.webm
+playwright-cli -s="$SESSION" video-start demo.webm
 
 # Add a chapter marker for section transitions
-playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
+playwright-cli -s="$SESSION" video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
 
 # Navigate and perform actions
-playwright-cli goto https://example.com
-playwright-cli snapshot
-playwright-cli click e1
+playwright-cli -s="$SESSION" goto https://example.com
+playwright-cli -s="$SESSION" snapshot
+playwright-cli -s="$SESSION" click e1
 
 # Add another chapter
-playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
-playwright-cli fill e2 "test input"
+playwright-cli -s="$SESSION" video-chapter "Filling Form" --description="Entering test data" --duration=2000
+playwright-cli -s="$SESSION" fill e2 "test input"
 
 # Stop and save
-playwright-cli video-stop
+playwright-cli -s="$SESSION" video-stop
+playwright-cli -s="$SESSION" close
+playwright-cli list  # verify $SESSION is absent
 ```
 
 ## Best Practices
@@ -44,7 +48,7 @@ It allows pulling appropriate pauses between the actions and annotating the vide
 
 1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
 2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
-3) Use playwright-cli run-code --filename your-script.js
+3) In the task-owned unique session, use `playwright-cli -s="$SESSION" run-code --filename your-script.js`, then close that exact session and verify it is absent from `playwright-cli list`, including on errors.
 
 **Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.