From b15a516c9907f9d2f80f73f593974522e0a79664 Mon Sep 17 00:00:00 2001 From: Diego Marinho <4332052+dmoliveira@users.noreply.github.com> Date: Tue, 3 Nov 2026 21:37:43 +1100 Subject: [PATCH 1/2] docs: warn about ast-grep recovery and indirect installs --- README.md | 5 +++-- docs/command-handbook.md | 31 +++++++++++++++++++++++------ docs/quickstart.md | 16 ++++++++++----- docs/readme-deep-notes.md | 29 +++++++++++++++++---------- instructions/auto_slash_detector.md | 11 ++++++++-- 5 files changed, 66 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 062a2a66..856ccd2d 100644 --- a/README.md +++ b/README.md @@ -63,8 +63,9 @@ 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 +reads, and ast-grep installation, retries, recovery, or version probes. Preserve +existing ast-grep stage and journal files. Some diagnostics also access the +background store or managed ast-grep state. See `docs/command-handbook.md` for affected commands and remaining risks. - 🧠 Built-in `/mcp` command for `status`, `help`, `doctor`, `profile`, `enable`, and `disable`. diff --git a/docs/command-handbook.md b/docs/command-handbook.md index c52158a7..2407787f 100644 --- a/docs/command-handbook.md +++ b/docs/command-handbook.md @@ -50,12 +50,31 @@ npx --yes @playwright/cli@0.1.17 -s= open 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. +**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 state; avoid +them on live state that must be preserved or remain unaccessed. They may still +recommend running the installer: disregard that recommendation while this hold +applies. +`/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 diff --git a/docs/quickstart.md b/docs/quickstart.md index 5fd412c8..208c32d3 100644 --- a/docs/quickstart.md +++ b/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] @@ -41,10 +40,17 @@ For browser UX work, use the verified CLI path first: - Use `/browser ensure --json` plus `/mcp profile playwright` when integrated MCP network, storage, assertion, or vision tools are the better fit. - 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. +**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`. Playwright CLI remains a separate +explicit install. Exploratory examples after startup is healthy: [h:9e27aaf8] [h:e0a80255] diff --git a/docs/readme-deep-notes.md b/docs/readme-deep-notes.md index c78b1372..acd1c750 100644 --- a/docs/readme-deep-notes.md +++ b/docs/readme-deep-notes.md @@ -5,7 +5,8 @@ This document contains detailed historical implementation notes moved out of the Note: this archive includes historical implementation notes and may mention legacy or compatibility command forms alongside canonical ones. Use `docs/quickstart.md` and `docs/command-handbook.md` for the current operator-facing command surface. **Safety hold:** Background mutations, untrusted background-record reads, and -live ast-grep installation or version probes are not safe to run as examples. +live ast-grep installation, retries, recovery, or version probes are not safe +to run as examples. Preserve ast-grep journals and staged files. `/doctor`, `/doctor status`, and `/doctor run` also access the background store and its lock; avoid them on live state that must be preserved. Some health and swarm operations read background records. See `docs/command-handbook.md`. @@ -608,14 +609,14 @@ Optional/manual add-ons: - `browser-use` when you need a higher-level browser agent beyond the built-in Playwright-first path; install it manually and keep `BROWSER_USE_API_KEY` scoped to workflows that actually need it. - Context7 only when you have a local CLI workflow you trust; keep the remote MCP path disabled by default when token cost matters. -Use these directly in OpenCode: +`/devtools status` and `/devtools doctor` inspect managed ast-grep state and may +still recommend installation. Avoid them on live state that must be preserved or +remain unaccessed, and disregard that recommendation while the safety hold applies. +Other commands: ```text -/devtools status /devtools help /devtools install playwright-cli -/devtools doctor -/devtools doctor --json /devtools hooks-install /tmux status --json /tmux doctor --json @@ -637,7 +638,7 @@ direnv allow ``` Notes: -- 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. The installer targets pinned Darwin arm64 `ast-grep 0.45.0`; see `docs/command-handbook.md` for the 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 journals and staged files. The installer targets pinned Darwin arm64 `ast-grep 0.45.0`; see `docs/command-handbook.md` for the safety hold. - `/devtools` observes all other host-managed tools and gives manual guidance without invoking a host package manager. - `playwright-cli` remains an exact explicit install and is never included in `install all`. - `.pre-commit-config.yaml` is the canonical local hook configuration; `/devtools hooks-install` invokes the resolved local `pre-commit` executable with a finite deadline. @@ -987,12 +988,18 @@ Epic 10 introduces an intent-mapping detector for common command families: - command wrapper: `scripts/auto_slash_command.py` - contract guide: `instructions/auto_slash_detector.md` +**Safety hold:** `/auto-slash execute` can dispatch `/doctor` or a devtools +install request. The former accesses the background store; an install intent +without a recognized devtools target can resolve to `install all`, which includes +ast-grep. Do not execute prompts that route to held commands. Preview-first can be +disabled, so execution without `--force` is not always a preview. +`/auto-slash doctor --json` may suggest executing `/doctor`; disregard that +suggestion when background state must be preserved. + Use: ```text /auto-slash status --json /auto-slash preview --prompt "run doctor diagnostics" --json -/auto-slash execute --prompt "run doctor diagnostics" --json -/auto-slash execute --prompt "run doctor diagnostics" --force --json /auto-slash disable-command devtools /auto-slash audit --limit 10 --json /auto-slash doctor --json @@ -1001,14 +1008,14 @@ Use: Detector behavior: - maps natural-language prompts to `/doctor`, `/stack`, `/nvim`, or `/devtools` - enforces confidence + ambiguity thresholds before selecting a command -- defaults to preview-first execution (`execute` requires `--force`) +- defaults to preview-first execution; `--force` is required only when that setting is enabled - keeps per-command enable/disable controls in layered config -- appends forced execution events to runtime audit log for traceability +- appends execution events to the runtime audit log Examples: - basic: `/auto-slash preview --prompt "please run doctor diagnostics" --json` - intermediate: `/auto-slash preview --prompt "switch to focus mode" --json` -- safety path: `/auto-slash execute --prompt "run doctor diagnostics" --json` then rerun with `--force` +- do not execute a preview that routes to a command under a safety hold Limitations: - intentionally limited command set to reduce misfire risk diff --git a/instructions/auto_slash_detector.md b/instructions/auto_slash_detector.md index cab6663b..b7962581 100644 --- a/instructions/auto_slash_detector.md +++ b/instructions/auto_slash_detector.md @@ -29,10 +29,17 @@ If any gate fails, detector returns `NOOP` with explicit reason (`low_confidence ## Execution model - preview-first by default (`preview_first=true`) -- `/auto-slash execute` without `--force` returns `PREVIEW_ONLY` -- forced execution dispatches backend command and records an audit event +- for a match, `preview_first=true` makes `/auto-slash execute` without `--force` return `PREVIEW_ONLY`; when it is false, execution can proceed without `--force` +- a matched execution dispatches the backend and records an audit event if preview is bypassed or disabled - audit entries are appended to `~/.config/opencode/my_opencode/runtime/auto_slash_audit.jsonl` +**Safety hold:** Do not execute prompts that route to held background diagnostics +or ast-grep installation. A devtools install intent without a recognized target +can resolve to `install all`, which includes ast-grep. `/doctor` accesses the +background store. `/auto-slash doctor --json` may suggest executing `/doctor`; +disregard that suggestion when background state must be preserved. See +`docs/command-handbook.md` for current restrictions. + ## Config shape (`auto_slash_detector`) ```json From 84144776a8fbc6c70a457ca05c52620ec021d5cd Mon Sep 17 00:00:00 2001 From: Diego Marinho <4332052+dmoliveira@users.noreply.github.com> Date: Tue, 3 Nov 2026 21:46:47 +1100 Subject: [PATCH 2/2] docs: hold unsafe Playwright CLI cache writes --- .opencode/skills/playwright-web-ux/SKILL.md | 29 ++++++++++-------- README.md | 8 ++--- docs/command-handbook.md | 34 ++++++++++----------- docs/ox-command-pack.md | 16 ++++------ docs/playwright-ux-scenarios.md | 18 +++++++---- docs/quickstart.md | 14 ++++++--- docs/readme-deep-notes.md | 11 ++++--- 7 files changed, 71 insertions(+), 59 deletions(-) diff --git a/.opencode/skills/playwright-web-ux/SKILL.md b/.opencode/skills/playwright-web-ux/SKILL.md index b81aeb03..78249ae9 100644 --- a/.opencode/skills/playwright-web-ux/SKILL.md +++ b/.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 ` or use `--target` and `--scope` for a narrower audit. -- Start a unique session with `npx --yes @playwright/cli@0.1.17 -s= open `. -- 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=` 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= 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. diff --git a/README.md b/README.md index 856ccd2d..47271272 100644 --- a/README.md +++ b/README.md @@ -63,10 +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, retries, recovery, or version probes. Preserve -existing ast-grep stage and journal files. Some diagnostics also access the -background store or managed ast-grep state. 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. diff --git a/docs/command-handbook.md b/docs/command-handbook.md index 2407787f..39fe7d0c 100644 --- a/docs/command-handbook.md +++ b/docs/command-handbook.md @@ -41,14 +41,18 @@ 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= open -``` - -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. +**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 @@ -66,10 +70,9 @@ 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 state; avoid -them on live state that must be preserved or remain unaccessed. They may still -recommend running the installer: disregard that recommendation while this hold -applies. +`/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. @@ -80,11 +83,8 @@ 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= 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. diff --git a/docs/ox-command-pack.md b/docs/ox-command-pack.md index b04e8671..391bd65a 100644 --- a/docs/ox-command-pack.md +++ b/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= open -``` - -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= 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. diff --git a/docs/playwright-ux-scenarios.md b/docs/playwright-ux-scenarios.md index b757f7d8..af57e882 100644 --- a/docs/playwright-ux-scenarios.md +++ b/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=` 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. diff --git a/docs/quickstart.md b/docs/quickstart.md index 208c32d3..bb2ac9cc 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -34,12 +34,17 @@ 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=` 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. +**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 @@ -49,8 +54,7 @@ journals and staged files. 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`. Playwright CLI remains a separate -explicit install. +the hold applies. See `docs/command-handbook.md`. Exploratory examples after startup is healthy: [h:9e27aaf8] [h:e0a80255] diff --git a/docs/readme-deep-notes.md b/docs/readme-deep-notes.md index acd1c750..59523ebc 100644 --- a/docs/readme-deep-notes.md +++ b/docs/readme-deep-notes.md @@ -6,7 +6,8 @@ Note: this archive includes historical implementation notes and may mention lega **Safety hold:** Background mutations, untrusted background-record reads, and live ast-grep installation, retries, recovery, or version probes are not safe -to run as examples. Preserve ast-grep journals and staged files. +to run as examples. Live Playwright CLI installation and retries are also on +hold. Preserve ast-grep journals and stages and the Playwright CLI cache. `/doctor`, `/doctor status`, and `/doctor run` also access the background store and its lock; avoid them on live state that must be preserved. Some health and swarm operations read background records. See `docs/command-handbook.md`. @@ -610,13 +611,13 @@ Optional/manual add-ons: - Context7 only when you have a local CLI workflow you trust; keep the remote MCP path disabled by default when token cost matters. `/devtools status` and `/devtools doctor` inspect managed ast-grep state and may -still recommend installation. Avoid them on live state that must be preserved or -remain unaccessed, and disregard that recommendation while the safety hold applies. +also inspect Playwright CLI state. They may still recommend the held installers. +Avoid them on live state that must be preserved or remain unaccessed, and +disregard those recommendations while the safety holds apply. Other commands: ```text /devtools help -/devtools install playwright-cli /devtools hooks-install /tmux status --json /tmux doctor --json @@ -640,7 +641,7 @@ direnv allow Notes: - 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 journals and staged files. The installer targets pinned Darwin arm64 `ast-grep 0.45.0`; see `docs/command-handbook.md` for the safety hold. - `/devtools` observes all other host-managed tools and gives manual guidance without invoking a host package manager. -- `playwright-cli` remains an exact explicit install and is never included in `install all`. +- Do not run live Playwright CLI installation or retries. Preserve its existing cache, npm config, and attestation files; see `docs/command-handbook.md`. - `.pre-commit-config.yaml` is the canonical local hook configuration; `/devtools hooks-install` invokes the resolved local `pre-commit` executable with a finite deadline. - Browser-use and Context7 remain manual/opt-in because they need SDK/API-key or CLI-specific setup outside the default host-tool path. - Prefer tmux session names with an AI/OpenCode prefix such as `ai-oc-` so cleanup and resume targeting stay obvious.