docs: warn about unsafe devtools installer paths

.opencode/skills/playwright-web-ux/SKILL.md

@@ -7,10 +7,16 @@ description: Use when browser-first validation, Playwright CLI or MCP, implement
 Validate the real implemented web experience in-browser and produce concrete UX findings with evidence.
 
 ## Default Operating Mode
-- Use the verified, exact `playwright-cli` package first for standard coding-agent browser flows and longer exploratory sessions.
-- Use Playwright MCP when the task specifically benefits from its integrated network, storage, assertion, vision, or protocol tool surface.
+- Choose a browser backend only after independently checking its effects on state that must be preserved.
+- Consider Playwright MCP when its integrated network, storage, assertion, vision, or protocol tools are useful and its state effects are acceptable.
 - Keep the same quality bar in both paths: deterministic state setup, user-visible assertions, and evidence-backed findings.
 
+**Safety hold:** Do not run live `/devtools install playwright-cli` or retry it.
+Preserve the existing Playwright CLI cache, npm config, and attestation files
+until cache-write authority and no-clobber publication are qualified. See
+`docs/command-handbook.md`. This hold does not qualify MCP or `npx` as safe
+alternatives.
+
 ## Use When
 - the user asks for Playwright or browser testing
 - the task is an implemented web flow review
@@ -23,21 +29,20 @@ Validate the real implemented web experience in-browser and produce concrete UX
 - static code review is sufficient
 
 ## First Steps
-- `/devtools install playwright-cli`
+- Check the safety hold and preserve existing state.
 - `/ox-ux --repo <repo>` or use `--target` and `--scope` for a narrower audit.
-- Start a unique session with `npx --yes @playwright/cli@0.1.17 -s=<unique-session> open <url>`.
-- If MCP is the better fit, run `/browser ensure --json` and `/mcp profile playwright` instead.
+- Start a unique session only with a backend independently confirmed safe for the task.
 
 ## Tool Selection Rules
 - Quick gate:
-  - Use `playwright-cli` for standard implemented website and app audits, repeated coding-agent interactions, and token-efficient persistent sessions.
-  - Use Playwright MCP when integrated network mocking, storage control, assertions, vision, or host-managed browser tools are the deciding requirement.
-  - If semantics are weak, use CLI screenshots or coordinates, or switch to MCP vision when its integrated tool path is more useful.
+  - Use `playwright-cli` for standard implemented website and app audits only when it is independently available and safe for the task.
+  - Consider Playwright MCP when integrated network mocking, storage control, assertions, vision, or host-managed browser tools are needed and its state effects are acceptable.
+  - If semantics are weak, consider screenshots, coordinates, or MCP vision only with an independently safe backend.
 - Prefer accessibility snapshots and refs first.
 - Use Playwright MCP assertions when you need deterministic visible-state checks.
 - Use network and storage controls when auth, retries, offline mode, or error states must be reproduced reliably.
 - Use vision mode only when the accessibility tree is insufficient, such as canvas, WebGL, maps, charts, or custom widgets without meaningful ARIA.
-- Use `playwright-cli` first when the task needs longer exploratory loops, multiple sessions, browser-game traversal, or token-efficient repeated commands.
+- Consider `playwright-cli` for longer exploratory loops or browser-game traversal only when it is independently available and safe.
 - Reuse one unique `-s=<session>` value and end it with the scoped `close` command.
 - Use `close-all` or `kill-all` only inside a fully owned isolated `HOME` and cache. Never use them against the host session inventory.
 - Do not install external CLI skill bundles; keep this audited skill and the pinned package invocation as the command contract.
@@ -47,7 +52,7 @@ Validate the real implemented web experience in-browser and produce concrete UX
 ## Scenario Playbooks
 
 ### Standard website or app audit
-- Run `/devtools install playwright-cli`, then use a unique CLI session for the journey.
+- Use a unique session with an independently safe backend for the journey.
 - Exercise the main journey first.
 - Then cover loading, empty, error, success, and mobile states.
 - Verify visible copy, hierarchy, responsiveness, and trust cues.
@@ -58,7 +63,7 @@ Validate the real implemented web experience in-browser and produce concrete UX
 - Assert the post-login state explicitly.
 
 ### Canvas, WebGL, or browser-game flow
-- Start with `playwright-cli` when the UI is mostly non-semantic or coordinate-driven.
+- Consider `playwright-cli` for non-semantic or coordinate-driven UI only when it is independently available and safe.
 - High-value starter moves:
   - use `open --persistent` or `attach --cdp=chrome` for longer sessions
   - use `state-save` / `state-load` for auth-heavy flows
@@ -69,7 +74,7 @@ Validate the real implemented web experience in-browser and produce concrete UX
 - Be explicit when a game scenario is observational UX validation rather than deterministic state proof.
 
 ### Session cleanup
-- Close only the session you opened: `npx --yes @playwright/cli@0.1.17 -s=<session> close`.
+- Close only the session you opened; do not use a close command that implicitly installs a package.
 - Confirm the owned session and browser processes exited before reporting completion.
 - Reserve `close-all` and `kill-all` for disposable sandboxes whose `HOME`, cache, and process groups are fully owned by the current gate.
 

README.md

@@ -63,9 +63,10 @@ New OpenCode sessions now load `~/.config/opencode/my_opencode/AGENTS.md` as a g
 ## Features and benefits 🌟
 
 **Safety hold:** Avoid live background job mutations, untrusted background job
-reads, and ast-grep installation or version probes. Some diagnostics can also
-access or initialize the background store. See `docs/command-handbook.md` for
-affected commands and remaining risks.
+reads; ast-grep installation, retries, recovery, or version probes; and
+Playwright CLI installation or retries. Preserve existing ast-grep stages and
+journals and the Playwright CLI cache. Some diagnostics also access preserved
+state. See `docs/command-handbook.md` for affected commands and remaining risks.
 
 - 🧠 Built-in `/mcp` command for `status`, `help`, `doctor`, `profile`, `enable`, and `disable`.
 - 🎛️ Built-in `/plugin` command to enable or disable plugins without editing JSON.

docs/command-handbook.md

@@ -41,31 +41,50 @@ Use these directly in OpenCode:
 /mcp disable all
 ```
 
-For browser-first coding-agent work, start with:
-
-```text
-/devtools install playwright-cli
-npx --yes @playwright/cli@0.1.17 -s=<unique-session> open <url>
-```
-
-The devtools command verifies the exact package version, license, integrity, Node requirement, and lifecycle-script posture before it executes package code. It uses an isolated npm config and owner-only cache; `install all` never includes this optional target.
-
-**Safety hold:** Do not run live ast-grep installation or version probes,
-including `/devtools install ast-grep` and `/devtools install all`, until
-process-group teardown is made safe. A version process whose leader has exited
-can leave a group that the current teardown cannot authenticate; permission
-errors are also not handled reliably. A mock-only test demonstrated the signal
-path, not that an unrelated process was actually signalled.
+**Playwright CLI safety hold:** Do not run live
+`/devtools install playwright-cli` or retry it until cache-write authority and
+no-clobber publication are qualified. Preserve the existing Playwright CLI cache, npm
+config files, and attestation files; do not clean or repair them as a shortcut.
+Synthetic tests showed that an attestation-stage symlink or a hardlinked npm
+config can overwrite and change permissions on a file outside the cache. No
+live file or package was involved. Package provenance checks do not establish
+filesystem write authority.
+
+For browser-first work, use a backend only after independently confirming it is
+safe for the state that must be preserved. The optional Playwright CLI target is
+not part of `install all`; that does not qualify it for live installation.
+
+**Safety hold:** Do not run live ast-grep installation, retries, recovery, or
+version probes, including `/devtools install ast-grep` and
+`/devtools install all`, until process containment, bounded draining, and
+recovery ownership and cleanup are qualified.
+Preserve existing ast-grep journals, staged files, and managed artifacts; do not
+manually remove them as a recovery shortcut.
+
+A version process whose leader has exited can leave a group that the current
+teardown cannot authenticate, and permission errors are not handled reliably.
+Downloader cleanup can also wait without a deadline after a timeout.
+A mock-only test demonstrated the signal path, not that an unrelated process
+was actually signalled. Separately, a synthetic same-UID test with a valid
+journal showed that recovery can unlink a file moved from outside the cache
+under an expected stage name. No live file was involved. A journal, pathname,
+or metadata check does not prove stage ownership or make a later unlink atomic.
+
+`/devtools status` and `/devtools doctor` inspect managed ast-grep and Playwright
+CLI state; avoid them on live state that must be preserved or remain unaccessed.
+They may still recommend the held installers: disregard those recommendations.
+`/auto-slash execute` can route a devtools install request with no target to
+`install all`. Do not execute such requests while the hold applies; preview-first
+can be disabled, so execution without `--force` is not always a preview.
+`/auto-slash doctor --json` may also suggest executing `/doctor`; disregard that
+suggestion when the background state must be preserved.
 
 The managed installer targets only pinned Darwin arm64 `ast-grep 0.45.0`;
 other host tools remain observation/manual-only. Git hooks use the resolved
 local `pre-commit` executable only.
 
-Reuse the same session for each command, then close only that session:
-
-```text
-npx --yes @playwright/cli@0.1.17 -s=<unique-session> close
-```
+Reuse a session only when its backend is independently safe, and close only the
+session you opened. Do not use a close command that implicitly installs a package.
 
 Use `close-all` or `kill-all` only in a disposable sandbox with a fully owned `HOME`, cache, and process group. Do not install external CLI skill bundles.
 

docs/ox-command-pack.md

@@ -76,18 +76,14 @@ Examples:
 /ox-ux --target https://dmoliveira.github.io/top-uni/ --focus hierarchy,copy,states --goal "polish the browsing flow"
 ```
 
-Recommended first step for browser-first work:
-
-```text
-/devtools install playwright-cli
-npx --yes @playwright/cli@0.1.17 -s=<unique-session> open <url>
-```
-
-The install target verifies the exact package provenance in an isolated npm environment. Reuse the unique session for the audit and end it with `npx --yes @playwright/cli@0.1.17 -s=<unique-session> close`.
+**Safety hold:** Do not run live `/devtools install playwright-cli` or retry it.
+Preserve its existing cache, npm config, and attestation files until cache-write
+authority and no-clobber publication are qualified. Package provenance checks do
+not prove filesystem write safety. See `docs/command-handbook.md`.
 
 Execution split:
-- Use the verified `playwright-cli` path first for standard browser-first site/app audits and long persistent exploratory loops.
-- Use `/browser ensure --json` and `/mcp profile playwright` when integrated MCP network, storage, assertion, or vision tools are the better fit.
+- Choose a backend only after independently checking its effects on state that must be preserved; the hold does not qualify MCP or `npx` as safe alternatives.
+- Consider integrated MCP network, storage, assertion, or vision tools when their independently assessed state effects are acceptable.
 - Do not install external CLI skill bundles; use scoped `close`. Reserve `close-all` and `kill-all` for a fully owned disposable sandbox.
 - Keep `/ox-ux` as the routing contract either way so the agent still frames the work as a full UX audit instead of ad hoc browser poking.
 

docs/playwright-ux-scenarios.md

@@ -2,15 +2,21 @@
 
 Use this guide when the agent should turn a broad “test the UX” request into concrete browser scenarios.
 
+**Safety hold:** Do not run live `/devtools install playwright-cli` or retry it.
+Preserve its existing cache, npm config, and attestation files until cache-write
+authority and no-clobber publication are qualified. See `docs/command-handbook.md`.
+Check any alternative backend independently; this hold does not qualify MCP or
+an `npx` invocation as safe for state that must be preserved.
+
 ## Operating split
 
-- **Verified `playwright-cli` first** for normal websites, SPAs, dashboards, forms, responsive checks, and longer exploratory loops.
-- **Playwright MCP** when integrated network, storage, assertion, vision, or host-managed browser tools materially simplify the flow.
-- Run `/devtools install playwright-cli` before the CLI path, use a unique session, and close only that session.
+- Choose a browser backend only after confirming its state effects are safe for the task.
+- Playwright MCP may help when integrated network, storage, assertion, vision, or host-managed browser tools are needed; assess it independently.
+- Use a unique session and close only that session when doing so is safe.
 
 ## Scenario matrix
 
-| Scenario | Default path | Why |
+| Scenario | Candidate path, subject to the hold | Why |
 | --- | --- | --- |
 | Marketing site / docs / landing page | `playwright-cli` | Compact snapshots and repeated interactions |
 | Product flow / dashboard / settings | `playwright-cli` | Persistent, token-efficient coding-agent flow |
@@ -47,7 +53,7 @@ Use this guide when the agent should turn a broad “test the UX” request into
 
 ### 4. Canvas, WebGL, or browser-gaming pass
 
-- start with `playwright-cli`
+- use `playwright-cli` only if it is independently available and safe for the task
 - capture a screenshot and identify the main interactive zones
 - test onboarding clarity, HUD readability, input discoverability, pause/settings, and failure/recovery loops
 - verify whether actions give immediate visible feedback
@@ -63,7 +69,7 @@ Use this guide when the agent should turn a broad “test the UX” request into
 
 ## Tool-selection rules
 
-- Verify the exact CLI package with `/devtools install playwright-cli` before use.
+- Do not bypass the Playwright CLI installation hold with another unqualified installer.
 - Use a unique `-s=<session>` value for each owned flow and finish with scoped `close`.
 - Do not install external CLI skill bundles. Use `close-all` or `kill-all` only in a fully owned disposable sandbox.
 - Prefer accessibility snapshots and refs first.

docs/quickstart.md

@@ -17,7 +17,6 @@ These commands affect the helper's legacy config only; they do not verify live s
 Required first-run checks: [h:bf437ec9]
  [h:92b53b41]
 ```text [h:be7b1450]
-/devtools status [h:edbb473e]
 /plugin status [h:014e2cdb]
 /mcp status [h:5435d065]
 /notify status [h:2890edfb]
@@ -35,16 +34,27 @@ Optional capability checks when you need them: [h:371d5a53]
 /tmux doctor --json [h:ae3cceae]
 ``` [h:0a584b58]
  [h:47685be0]
-For browser UX work, use the verified CLI path first:
-- `/devtools install playwright-cli` verifies `@playwright/cli@0.1.17` before exact on-demand execution.
+For browser UX work, choose a backend only after confirming it is safe for the state you must preserve:
 - Use a unique `-s=<session>` value and close only that session when the flow ends.
-- Use `/browser ensure --json` plus `/mcp profile playwright` when integrated MCP network, storage, assertion, or vision tools are the better fit.
+- Consider integrated MCP network, storage, assertion, or vision tools only after independently checking their state effects.
 - See `docs/playwright-ux-scenarios.md` for both paths. Do not install external CLI skill bundles.
 
-**Safety hold:** Do not run live ast-grep installation or version probes,
-including `/devtools install ast-grep` and `/devtools install all`, until
-process-group teardown is safe. See `docs/command-handbook.md`. Playwright CLI
-remains a separate explicit install.
+**Playwright CLI safety hold:** Do not run live `/devtools install playwright-cli`
+or retry it. Preserve the existing Playwright CLI cache, npm config files, and
+attestations until cache-write authority is qualified. Synthetic symlink and
+hardlink tests showed that installer writes can affect files outside the cache.
+See `docs/command-handbook.md`.
+
+**Safety hold:** Do not run live ast-grep installation, retries, recovery, or
+version probes, including `/devtools install ast-grep` and
+`/devtools install all`, until process containment, bounded draining, and
+recovery ownership and cleanup are qualified. Preserve existing ast-grep
+journals and staged files.
+`/devtools status` and `/devtools doctor` inspect managed state and may still
+recommend installation; avoid them on live state that must be preserved or
+remain unaccessed, and disregard that recommendation. Auto-slash can also route
+an unspecified devtools install request to `install all`; do not execute it while
+the hold applies. See `docs/command-handbook.md`.
 
 Exploratory examples after startup is healthy: [h:9e27aaf8]
  [h:e0a80255]