browser-automation-skill 0.71.0

package/references/recipes/fingerprint-rescue.md

@@ -0,0 +1,154 @@
+# Recipe — Phase 13 fingerprint rescue
+
+**Use when**: a cached selector goes stale (class rename, id rename, minor DOM
+reshuffle). The Phase-11 memory cache used to require 4 consecutive failures
++ an LLM re-resolve to recover. Phase 13 adds a *pre-LLM* rescue tier that
+tries to find an equivalent element via weak-fingerprint similarity. If it
+succeeds, the cache silently heals (selector overwritten, fail_count reset,
+`self_heal_history[]` appended with `event:"rescued"`). If it fails, the
+existing fail_count path runs unchanged.
+
+**Inspired by**: Scrapling's adaptive selectors. *Not* a Scrapling adapter —
+the algorithm is ported as ~150 LOC of Node-side scoring + bash glue. No
+Python dependency added.
+
+## When the rescue runs
+
+Only on `browser-do --intent` cache-hit-then-fail with exit code
+`EXIT_EMPTY_RESULT` (11) or `EXIT_ASSERTION_FAILED` (13). Environmental
+failures (network 30, tool crash 42, timeout 43) skip the rescue — those
+would poison the cache if counted.
+
+```
+cache hit → dispatch verb → adapter resolves 0 elements (rc=11)
+                              │
+                              ▼
+                  memory_fingerprint_rescue
+                              │
+              ┌───────────────┴───────────────┐
+              ▼                               ▼
+   returns rescued_selector            returns "" (no match ≥ threshold)
+              │                               │
+              ▼                               ▼
+       retry verb with rescued     memory_record_failure (existing path)
+              │                       fail_count++ → after 4 → disabled
+       retry succeeds?
+              │
+        ┌─────┴─────┐
+        ▼           ▼
+       yes          no
+        │           │
+   memory_record_heal:      memory_record_failure (existing path)
+   - overwrite selector
+   - reset fail_count
+   - bump success_count
+   - append self_heal_history
+   - emit stats event {rescued:true}
+```
+
+## Algorithm
+
+1. **Parse cached selector → weak fingerprint** (bash + jq):
+
+   ```
+   "button.delete"            → { tag: "BUTTON", classes: ["delete"], attrs: {} }
+   "#submit"                  → { tag: "*",      classes: [],         attrs: {id: "submit"} }
+   "form > input.email"       → { tag: "FORM",   classes: ["email"],  attrs: {} }  (combinator stripped — weak)
+   ```
+
+   Combinators (`>`, `+`, `~`), pseudo-classes (`:hover`), attribute operators
+   (`^=`, `*=`) are not parsed. The fingerprint will simply be weaker and the
+   JS scorer will probably miss — caller falls through to LLM re-resolve.
+
+2. **Inject scorer into the page** via `browser-extract --eval` (Phase 13 JS
+   file: `scripts/lib/fingerprint-rescue.js`). Constants `__FP` (the
+   fingerprint) and `__TH` (threshold) are prepended bash-side.
+
+3. **Score each DOM element**:
+
+   ```
+   score = 0.4 × tag_match
+         + 0.4 × jaccard(target.classes, candidate.classList)
+         + 0.2 × jaccard(target.attrs,   candidate.attributes)
+   ```
+
+4. **Synthesise selector for the best-scoring candidate** above threshold:
+
+   ```
+   1. #id                    (when id is /^[A-Za-z][\w-]*$/ AND uniquely resolving)
+   2. [data-testid="…"]      (preferred test-automation hook)
+   3. tag.class[.class…]     (uniquely resolving)
+   4. nth-child path         (absolute last-resort)
+   ```
+
+## Threshold
+
+Default `0.70`. Override per-session:
+
+```bash
+BROWSER_DO_RESCUE_THRESHOLD=0.85 bash scripts/browser-do.sh --site myapp --verb click --intent "delete row" --pattern '/devices/:id'
+```
+
+- `0.70` (default) — Scrapling-like balance. Accepts moderate drift (class
+  rename) but rejects very-different candidates.
+- `0.85` — conservative. Fewer false positives, more LLM round-trips on
+  borderline drift.
+- `0.50` — permissive. More heals, but watch the `failure_mode=
+  wrong_element_acted` count in `browser-stats report` for false-positive
+  drift.
+
+## Audit visibility
+
+Each successful rescue emits a dedicated stats event:
+
+```json
+{
+  "schema_version": 1,
+  "ts": "2026-05-18T01:02:03.456Z",
+  "gen_ai_tool_name": "browser-do.fingerprint_rescue",
+  "verb": "do",
+  "adapter_route": "browser-do",
+  "outcome": "success",
+  "rescued": true,
+  "fingerprint_from_selector": "button.delete",
+  "fingerprint_to_selector": "button[data-testid=delete-btn]"
+}
+```
+
+Query the heal-rate:
+
+```bash
+bash scripts/browser-stats.sh report --verb do
+# → look for "browser-do.fingerprint_rescue" rows + outcome=success share
+```
+
+## When NOT to use
+
+- **Cross-page rescue.** The rescue only runs against the *currently-loaded*
+  DOM. If the verb already redirected and the cached selector is for the
+  prior page, rescue won't find it. (`navigation_mismatch` failure mode
+  instead.)
+- **Identifier-free designs.** If the target element has no id, no
+  data-testid, no stable classes, and no unique nth-child position, the
+  synthesised selector will be brittle. Better to invest in a stable
+  test-automation hook than depend on rescue.
+- **Heavy DOMs.** The scorer walks `document.querySelectorAll('*')` — O(n).
+  For pages with 10k+ DOM nodes the scoring will take >500ms. Consider
+  scoping with `document.querySelectorAll(target.tag.toLowerCase())` if you
+  hit this in practice (future v2 — the current implementation prioritises
+  recall over speed).
+
+## Failure modes mapped (vs the Phase-12 stats audit)
+
+| Outcome | failure_mode | rescued | Interpretation |
+|---|---|---|---|
+| Cache hit, adapter ok | null | null | Steady-state. No rescue ran. |
+| Cache hit, adapter fail, rescue ok | null | true | Silent heal. Audit row: `gen_ai_tool_name=browser-do.fingerprint_rescue`. |
+| Cache hit, adapter fail, rescue no-match | stale_ref (on the verb event) | null | Original fail_count++. Eventual LLM re-resolve. |
+| Cache hit, adapter fail, rescue match-but-retry-fail | stale_ref (on the verb event) | false (future — currently null) | Algorithm picked wrong candidate. Track this metric to tune threshold. |
+| Cache hit, adapter wrong-click | wrong_element_acted | true (false positive!) | Rescue scored a wrong element ≥ threshold. **Tune threshold up** if this rises. |
+
+## Related
+
+- Phase 11 `self_heal_history[]` lifecycle is preserved — see `scripts/lib/memory.sh::memory_record` (enabled→disabled) + `memory_record_failure` (disabled→enabled). Phase 13 adds the third event type: `event:"rescued"`.
+- Phase 12 audit surface: `references/browser-stats-cheatsheet.md`.

package/references/recipes/model-routing.md

@@ -0,0 +1,143 @@
+# Recipe: Model routing — three-tier strategy
+
+When and how to route Claude model selection across the parent session, this skill, and (eventually) per-verb invocations. The default ships with `model: sonnet` + `effort: low` in `SKILL.md` frontmatter; this recipe explains why, when to override, and how to layer in `opusplan` / `/advisor` at the parent session level.
+
+## When to use this recipe
+
+Use this whenever:
+- A user reports the skill seems to "make wrong choices" on complex flows (multi-step logins, ambiguous snapshots) — they may need to escalate from default Sonnet.
+- Your session token bill on browser tasks is bigger than you'd like — verify the three-tier setup is in place.
+- You're integrating this skill into a different host CLI (Codex, Cursor, Gemini CLI) — the model-routing primitives may differ.
+
+Do NOT use this recipe for:
+- Picking which Anthropic SDK to install. Model routing is consumer-side; the SDK is producer-side.
+- Speed-of-response tuning. Use `effort:` (low/medium/high/xhigh/max), not `model:`, for that knob.
+
+## The three tiers
+
+| Tier | Where it lives | Default in this skill | What it controls |
+|---|---|---|---|
+| 1. Parent session | `/model` command, `~/.claude/settings.json::model`, env var `ANTHROPIC_MODEL` | (user's choice — recommended: `opusplan`) | The "thinking" model — used when Claude reasons about what verb to call, parses snapshots, plans next steps |
+| 2. Skill turn | `model:` field in `SKILL.md` frontmatter | `sonnet` + `effort: low` | The "acting" model — used during the single turn that invokes the skill. Per-turn override; resumes Tier 1 on next prompt |
+| 3. Per-verb (future) | (not yet supported) | n/a | Some verbs may need Opus reasoning (login flow auto-detect); most just shell out to bash |
+
+## Tier 1: Parent session
+
+### Recommended: `/model opusplan` (stable)
+
+```bash
+# In any Claude Code session:
+/model opusplan
+
+# Or persist as default in ~/.claude/settings.json:
+{ "model": "opusplan" }
+```
+
+`opusplan` is a Claude Code built-in alias: **Opus during plan mode, Sonnet during execution mode**. Plan mode is entered with `shift+tab` or `/plan`; exited with `shift+tab` again. Plan-mode reasoning is where the heavy thinking happens (designing flows, deciding how to debug a failure, brainstorming a feature plan). Execution mode is where Claude calls bash, edits files, runs verbs — Sonnet is enough.
+
+This is the **zero-risk** starting point. No beta header. No skill edits. Available everywhere Claude Code runs (Anthropic-direct, Bedrock, Vertex, Foundry — though `opus`/`sonnet` resolve to provider-pinned versions on third-party providers).
+
+### Advanced: `/advisor` (experimental as of v2.1.x)
+
+```bash
+/advisor    # toggle in current session
+```
+
+`/advisor` is the Claude Code surface for the [Advisor Tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool). The session model becomes the **executor** (Sonnet 4.6 by default; can pair Haiku 4.5 too); during generation the executor consults an **advisor** model (Opus 4.7) mid-stream when it hits decision points.
+
+Mechanism (per [Advisor Tool docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)):
+1. Executor decides to consult — emits `server_tool_use { name: "advisor", input: {} }`.
+2. Anthropic server runs Opus inference with the full transcript (no client orchestration).
+3. Advisor returns ~400-700 token plan (~1,400-1,800 with thinking).
+4. Executor continues, advice in context.
+
+Cost economics:
+- Executor (Sonnet) generates the bulk of output → billed at Sonnet rate ($3/$15 per 1M).
+- Advisor (Opus) generates only advice tokens, billed at Opus rate ($5/$25 per 1M).
+- Internal Anthropic benchmarks: "Sonnet executor at medium effort + Opus advisor → intelligence comparable to Sonnet at default effort, at lower cost."
+
+**Caveats:**
+- Beta status. May change. May hit rate limits on the advisor sub-inference (`too_many_requests` error code; executor continues without the advice).
+- Not yet on Bedrock/Vertex/Foundry — Anthropic-direct only.
+- Advisor sub-inference doesn't stream — expect a pause when consultation fires.
+- No built-in conv-level cap; if cost balloons, set `max_uses` per request or toggle `/advisor` off.
+
+**When to add `/advisor`**: after `opusplan` proves out the cost-saving direction. If browser-automation flows show ad-hoc reasoning bottlenecks (Sonnet picking wrong refs, missing the right verb sequence), `/advisor` lets Sonnet ask Opus for a plan without paying full Opus rate for the whole turn.
+
+## Tier 2: This skill's frontmatter
+
+```yaml
+---
+name: browser-automation-skill
+...
+model: sonnet
+effort: low
+---
+```
+
+Per [Claude Code skills docs](https://code.claude.com/docs/en/skills): "The override applies for the rest of the current turn and is not saved to settings; the session model resumes on your next prompt."
+
+So when a user (or Claude auto-loading) invokes the skill:
+- Skill turn = Sonnet + low effort
+- Next prompt = back to parent session model (Tier 1: opusplan or whatever the user set)
+
+**Why Sonnet, not Haiku.** Haiku 4.5 is ~3× cheaper than Sonnet 4.6 but has noticeably less robustness on multi-step verb chaining (snapshot → pick `eN` ref → fill → submit). Browser-automation flows have enough orchestration that Sonnet earns its 3× over Haiku. If a specific user's flows are simple (single-step extracts, dry-run-only), they can override per-skill via `~/.claude/settings.json::skillOverrides` (not currently a documented field for model — file an issue if you need this).
+
+**Why `effort: low`.** Effort is independent of model. Sonnet at `effort: low` saves tokens vs Sonnet at default effort, with minimal capability loss for pure verb-driving (no deep reasoning needed — Claude already planned in the parent turn). If a flow regresses, bump to `effort: medium`.
+
+**Override escape-hatch.** When a session demands Opus reasoning during the skill turn (debugging a complex login flow that Sonnet keeps mishandling), the user can:
+
+```bash
+# Override for the rest of the session — `inherit` keeps the parent model
+/model opus    # before invoking the skill
+```
+
+Or edit the skill's frontmatter to `model: inherit` permanently to disable the per-turn override (skill follows parent session model).
+
+## Tier 3: Per-verb (deferred)
+
+Not currently supported by Claude Code's frontmatter model. If different verbs in this skill needed different models (e.g. `login --interactive` wants Opus for form-shape detection; `snapshot` wants Haiku for pure screen-scrape), the workaround would be:
+
+- Split the skill into N skills, each with its own `SKILL.md` + `model:` field. Path: every verb script becomes a tiny standalone skill.
+- Or use `Agent` tool from inside the skill body to spawn a subagent with a different `model:` parameter.
+
+Not worth the structural complexity until multiple users report it. Track as open follow-up.
+
+## How to verify the routing is working
+
+```bash
+# In Claude Code:
+/status              # shows current session model
+/model               # opens picker — verify opusplan or your choice is selected
+```
+
+After invoking a skill verb (e.g. `/browser-automation-skill snapshot`), `/status` may show that the active model briefly flipped to Sonnet (depending on how Claude Code surfaces per-turn overrides). The `usage.iterations[]` array in the API response shows the breakdown if you're driving via SDK.
+
+For cost-per-session tracking, `/cost` (when available) summarizes token spend by model.
+
+## Common failure modes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Skill picks wrong `eN` ref repeatedly | Sonnet at `effort: low` undercutting on snapshot interpretation | Bump skill frontmatter to `effort: medium` or override session-side with `/model opus` |
+| `/advisor` toggle fails with "too_many_requests" | Advisor rate-limited on Opus | Toggle `/advisor` off; rely on opusplan only. Or wait + retry. |
+| `model: opusplan` in SKILL.md doesn't activate plan mode | opusplan is plan-mode-state-aware; skill turn doesn't enter plan mode by itself | Use `model: sonnet` (current default) — opusplan is a parent-session-level alias, not a skill-turn primitive |
+| Cost still high after opusplan + skill model:sonnet | Most tokens going to non-skill turns (parent reasoning, file reads) | Profile with `/cost`; if parent-side dominates, that's where to optimize next |
+
+## Recommended setup for new users
+
+```
+1. Run `claude update` to get v2.1.x (advisor support).
+2. Run `/model opusplan` once — persists across sessions.
+3. (Optional) Run `/advisor` to enable advisor consultation.
+4. Use this skill — frontmatter already routes the skill turn to Sonnet + low effort.
+5. Watch token usage via `/cost` over a few sessions; tune effort if needed.
+```
+
+## See also
+
+- [Claude Code Model configuration (`opusplan`)](https://code.claude.com/docs/en/model-config)
+- [Skills frontmatter reference (`model`/`effort`)](https://code.claude.com/docs/en/skills)
+- [Advisor Tool — Claude API Docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)
+- [Anthropic API pricing](https://platform.claude.com/docs/en/about-claude/pricing)
+- Sister recipes: [privacy-canary.md](privacy-canary.md), [path-security.md](path-security.md), [body-bytes-not-body.md](body-bytes-not-body.md)

package/references/recipes/path-security.md

@@ -0,0 +1,138 @@
+# Recipe: Path security
+
+For any verb that takes a `--path` argument and forwards bytes from disk to a downstream tool (browser, MCP server, network upstream). Establishes the three guarantees the verb owes its caller, all enforced bash-side BEFORE the adapter dispatches.
+
+## When to use this recipe
+
+Use this whenever a verb accepts a filesystem path and acts on its contents. Already shipped: `scripts/browser-upload.sh` (Phase 6 part 6).
+
+Phase 7 capture-pipeline work will reuse this for any verb that writes capture artifacts to a caller-specified location (`--out PATH`).
+
+Do NOT use this recipe for:
+- Paths the **framework owns** (e.g. `${BROWSER_SKILL_HOME}/sessions/<name>.json`). Trust boundary doesn't apply — those paths are constructed, not accepted.
+- Read-only metadata commands (`show-site --name X` — name isn't a path).
+
+## The three checks (in order)
+
+```bash
+# scripts/browser-<verb>.sh — paste-ready scaffold
+[ -n "${path}" ] || die "${EXIT_USAGE_ERROR}" "<verb> requires --path PATH"
+
+# 1. Existence + regular-file check.
+#    Rejects: missing files, directories, devices, FIFOs, sockets.
+if [ ! -e "${path}" ]; then
+  die "${EXIT_USAGE_ERROR}" "<verb>: path does not exist: ${path}"
+fi
+if [ ! -f "${path}" ]; then
+  die "${EXIT_USAGE_ERROR}" "<verb>: path is not a regular file: ${path}"
+fi
+
+# 2. Readability check (current user, current process).
+if [ ! -r "${path}" ]; then
+  die "${EXIT_USAGE_ERROR}" "<verb>: path is not readable by the current user: ${path}"
+fi
+
+# 3. Sensitive-pattern reject. Override with --allow-sensitive (typed ack).
+if [ "${allow_sensitive}" -ne 1 ]; then
+  case "${path}" in
+    *.ssh/*|*/.ssh/*|*.aws/credentials|*/.aws/credentials|*/.env|*.env|\
+    */credentials|*/credentials.json|*/secrets.json|*/private_key*|*/id_rsa*|\
+    */id_ed25519*|*/id_ecdsa*)
+      die "${EXIT_USAGE_ERROR}" "<verb>: path '${path}' matches a sensitive pattern; pass --allow-sensitive to override"
+      ;;
+  esac
+fi
+
+# 4. Realpath canonicalization (eliminates symlink games).
+canonical_path="$(realpath "${path}" 2>/dev/null \
+                  || readlink -f "${path}" 2>/dev/null \
+                  || printf '%s' "${path}")"
+
+# Forward the canonical path, not the user's input.
+verb_argv+=(--path "${canonical_path}")
+```
+
+Source of truth: `scripts/browser-upload.sh:74-103`.
+
+## Why each check exists
+
+### Check 1 — `[ -f "${path}" ]`
+
+```
+WRONG — only check existence
+[ -e "${path}" ] || die ...
+# Passes for /dev/zero, /tmp/some-fifo, /etc — agent uploads garbage.
+```
+
+`-f` rejects directories, character/block devices, FIFOs, and sockets. The downstream tool was promised "a file's bytes"; an attempt to read `/dev/zero` would either hang the agent or upload an arbitrary number of zero bytes.
+
+### Check 2 — `[ -r "${path}" ]`
+
+Failing this check returns a clear UX error from the verb script. Skipping it pushes the failure down to the adapter, where the error message is whatever cdt-mcp / playwright happens to emit (often opaque, often surfaces a permissions dump).
+
+### Check 3 — Sensitive-pattern reject
+
+```
+WRONG — trust the agent to know what they're doing
+verb_argv+=(--path "${path}")  # forward whatever the agent typed
+```
+
+The agent can be tricked. A user pastes `--path ~/.ssh/id_rsa` into a browser-automation prompt and the agent obediently uploads it. Sensitive-pattern reject is the **default-deny**; `--allow-sensitive` is the typed acknowledgment that the agent saw the pattern and is uploading intentionally (e.g. uploading a GPG key to a keyserver).
+
+The pattern list is intentionally short — it covers the **boring high-frequency** cases (SSH keys, AWS credentials, `.env` files). It is not a full DLP. Don't expand it to chase exotic filenames; that creates an arms race against tools-of-the-month.
+
+### Check 4 — Realpath canonicalization
+
+```
+WRONG — forward agent input verbatim
+verb_argv+=(--path "${path}")
+
+# Then a symlink game beats the sensitive-pattern reject:
+$ ln -s ~/.ssh/id_rsa /tmp/innocent.txt
+$ verb --path /tmp/innocent.txt   # passes step 3 (path doesn't match patterns)
+                                  # but actually uploads the SSH key
+```
+
+`realpath` resolves the symlink; the canonical path becomes `~/.ssh/id_rsa`, which the sensitive-pattern check would have caught — but that check already ran. Two correct orderings exist:
+
+- **Resolve THEN check** (safer; resolution can't be skipped). Order in the recipe is "check then resolve" because that's how `browser-upload.sh` shipped; both work, but resolve-first is what to write next time.
+- **Check then resolve, then re-check** (paranoid). Reasonable if you're worried about TOCTOU between the two operations.
+
+Cross-platform fallback: macOS pre-Xcode-11 lacks `readlink -f` and may lack `realpath`. The chain `realpath || readlink -f || printf '%s'` gracefully degrades to verbatim path on the rare platform that has neither — at the cost of skipping symlink resolution on that platform. CI exercises both GNU (Linux) and BSD (macOS) realpath paths.
+
+## What's NOT this recipe's job
+
+- **Encryption-at-rest of the file's contents.** That's a different layer (the user's filesystem, FileVault, LUKS, etc.).
+- **Anti-malware scanning.** Verb is a thin transport, not a security product.
+- **Quarantining files after upload.** Out of scope; the user owns the file.
+- **Sandboxing the downstream tool.** That's the adapter's concern — sensitive-pattern reject + realpath stops *accidental* exfil; defense against a hostile downstream tool is the wrong threat model for this layer.
+
+## Test surface (already shipped for upload, copy for new verbs)
+
+`tests/browser-upload.bats` cases worth porting:
+- Path doesn't exist → `EXIT_USAGE_ERROR`.
+- Path is a directory → `EXIT_USAGE_ERROR`.
+- Path matches `~/.ssh/id_rsa` pattern → `EXIT_USAGE_ERROR` mentioning sensitive.
+- Same path with `--allow-sensitive` → success (dry-run).
+- Symlink-to-sensitive resolved by realpath → still rejected.
+- Symlink-to-innocent resolved by realpath → success, canonical path forwarded.
+
+## Checklist for any new path-accepting verb
+
+```
+1. Verb takes --path PATH and (if writes) maybe --out PATH.
+2. Add --allow-sensitive flag (default 0; typed ack).
+3. Inline the four-step block from this recipe between argv parsing and
+   adapter dispatch. Replace `<verb>` with the verb name in error strings.
+4. Forward the CANONICAL path (post-realpath), not the user's input.
+5. Test cases: missing / dir / unreadable / sensitive-rejected /
+   sensitive-allowed / symlink-to-sensitive / symlink-to-innocent.
+6. CHANGELOG entry with [security] tag if this is a new attack surface.
+```
+
+## See also
+
+- `scripts/browser-upload.sh:74-103` — the source-of-truth implementation.
+- `tests/browser-upload.bats` — test cases to port.
+- [Privacy canary recipe](privacy-canary.md) — sister pattern for credential bytes.
+- [Body-bytes-not-body recipe](body-bytes-not-body.md) — sister pattern for content bodies.

package/references/recipes/privacy-canary.md

@@ -0,0 +1,96 @@
+# Recipe: Privacy canary
+
+A sentinel-byte regression test for any verb that ingests caller-supplied secrets (passwords, tokens, TOTP shared-secrets, session storage state). Detects the day a refactor accidentally re-emits the secret on stdout, in a log line, or inside a JSON reply.
+
+## When to use this recipe
+
+Use this **whenever you add a verb that reads a secret via stdin** (the AP-7 pattern — see `anti-patterns-tool-extension.md::AP-7`). Examples already shipped:
+
+- `tests/creds-show.bats::49` — `creds show` invariant.
+- `tests/creds-migrate.bats::124` — backend transfer mustn't echo.
+- `tests/creds-rotate-totp.bats::99` — TOTP shared-secret roundtrip.
+- `tests/chrome-devtools-mcp_daemon_e2e.bats::140` — `fill --secret-stdin` end-to-end.
+
+Do NOT use this recipe for:
+- Verbs that don't ingest secrets (the canary has nothing to detect).
+- Verbs whose only "secret" is something the agent typed and is happy to read back (e.g. `route fulfill --body` — see `body-bytes-not-body.md` instead; the body is content, not a credential).
+
+## The pattern
+
+```
+WRONG — assert "secret didn't appear in some specific field"
+@test "fill --secret-stdin: reply has no .text key" {
+  printf 'pw' | bash browser-fill.sh --ref e1 --secret-stdin
+  printf '%s' "$output" | jq -e '.text == null' >/dev/null
+}
+# Brittle: only catches a single regression mode (echoing in a known field).
+# A new code path that puts the secret into a NEW field passes this test.
+```
+
+```
+RIGHT — assert "this exact byte sequence does not appear ANYWHERE on stdout"
+@test "fill --secret-stdin: privacy canary" {
+  CANARY="sekret-do-not-leak-XYZ"
+  run bash -c "printf '%s' '${CANARY}' | bash '${SCRIPTS_DIR}/browser-fill.sh' --ref e1 --secret-stdin"
+  assert_status 0
+  printf '%s' "${output}" | grep -q "${CANARY}" \
+    && fail "skill stdout leaked the secret canary: ${CANARY}" || true
+  # Reply shape still correct (don't accept a "no output" pass).
+  printf '%s' "${output}" | jq -e '.verb == "fill" and .status == "ok"' >/dev/null
+}
+```
+
+The canary string MUST be:
+- **Unique** to this test (so a grep can't accidentally match a real reply field). Embed the verb name and the test number: `sekret-do-not-leak-CDT-1c-ii`, `canary-creds-show-49`.
+- **Long enough** that grep's failure mode is meaningful. ~10+ ASCII characters; shorter strings risk colliding with field names like `id` or `ok`.
+- **Distinct** from the bytes the test injects elsewhere (don't reuse the canary as a username).
+
+## Why a sentinel beats field-shape assertions
+
+Field-shape assertions catch the regression you predict; sentinels catch the regression you didn't predict. The sentinel test answers a different question:
+
+> "Does **any** code path between stdin-read and stdout-write echo this byte sequence?"
+
+That question is what the AP-7 invariant actually claims. Anchoring the test to a specific field reduces it to "does *this one path* echo," which is the strictly weaker claim.
+
+## Layered coverage: bash AND daemon
+
+Verbs that go through the bridge daemon need **two** canaries:
+
+```
+tests/<verb>.bats             # bash-side canary (verb script -> adapter)
+tests/<adapter>_daemon_e2e.bats # daemon-side canary (bridge -> daemon -> MCP)
+```
+
+Each layer can independently leak — bridge could echo on its way to the daemon, or the daemon could echo back through IPC. The bash-side canary doesn't catch a daemon-side leak and vice versa.
+
+Sample placement (already shipped): `fill --secret-stdin` has a canary in both `tests/browser-fill.bats` (bash) and `tests/chrome-devtools-mcp_daemon_e2e.bats:140` (daemon).
+
+## Don't grep the file system
+
+```
+WRONG — assert canary doesn't appear in any state-dir file
+grep -r "${CANARY}" "${BROWSER_SKILL_HOME}" && fail "leaked to disk"
+```
+
+Some verbs **legitimately persist the secret** (creds-add writes to keychain/file backend; that's the whole point). Disk persistence is governed by the credential-backend test, not by the privacy canary. The privacy canary is exclusively about **stdout** — what the agent / Claude transcript sees.
+
+## Checklist for any new secret-ingesting verb
+
+```
+1. Pick a unique canary string (`sekret-do-not-leak-<verb>-<n>`).
+2. Pipe the canary in via the verb's --secret-stdin / --*-stdin flag.
+3. Capture stdout with `run bash -c '...'` (let bats own the buffer).
+4. Negative assert: `printf '%s' "$output" | grep -q "${CANARY}" && fail`.
+5. Positive assert: jq the reply shape so a "no output" run doesn't false-pass.
+6. If the verb routes through a daemon/bridge, add a SECOND canary at the
+   daemon-e2e layer. Each layer's stdout is separately observable.
+7. NEVER grep ${BROWSER_SKILL_HOME} for the canary — disk persistence is
+   the credential backend's responsibility, not this test's invariant.
+```
+
+## See also
+
+- [Anti-patterns: tool extension `AP-7`](anti-patterns-tool-extension.md) — secrets-via-stdin invariant.
+- [Body-bytes-not-body recipe](body-bytes-not-body.md) — sister pattern for non-secret caller-supplied content.
+- `tests/argv_leak.bats` — the AP-7 enforcement test (catches secrets on argv).