browser-automation-skill 0.71.0

package/scripts/browser-stats.sh

@@ -0,0 +1,522 @@
+#!/usr/bin/env bash
+# scripts/browser-stats.sh — Phase 12 part 1: telemetry surface verb.
+# Usage:
+#   browser-stats event ...              # internal — emit one event from CLI
+#   browser-stats rebuild                # rebuild SQLite mirror from JSONL
+#   browser-stats report [--days N] [--route ROUTE] [--verb VERB] [--pareto]
+#   browser-stats mark <span_id> <verdict>[:<reason>]
+#   browser-stats tune [--days N] [--route ROUTE]
+#
+# Verdict ∈ {success, fail}. Reason optional ("fail:popup_intercept" etc).
+#
+# All subcommands respect $BROWSER_SKILL_HOME. Writes are mode 0600 in the
+# memory/ dir (mode 0700). No network. SQLite is built lazily on `rebuild`;
+# JSONL is the source of truth.
+
+set -Eeuo pipefail
+# Inherit errexit into command substitutions (bash 4.4+). Without this,
+# `local x=$(jq ...)` silently swallows jq's non-zero exit (shellcheck SC2311
+# trap). With it, the script aborts as expected.
+shopt -s inherit_errexit
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/output.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/output.sh"
+# shellcheck source=lib/stats.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/stats.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+STATS_JSONL="${BROWSER_SKILL_HOME}/memory/stats.jsonl"
+STATS_DB="${BROWSER_SKILL_HOME}/memory/stats.db"
+PRICES_FILE="${BROWSER_STATS_PRICES_FILE:-${SCRIPT_DIR}/../references/stats-prices.json}"
+
+subcmd="${1:-}"
+[ -n "${subcmd}" ] || die "${EXIT_USAGE_ERROR}" "browser-stats: subcommand required (event|rebuild|report|mark|tune)"
+shift
+
+# --- helpers ----------------------------------------------------------------
+
+require_sqlite3() {
+  command -v sqlite3 >/dev/null 2>&1 \
+    || die "${EXIT_PREFLIGHT_FAILED}" "browser-stats: sqlite3 not installed"
+}
+
+# stats_db_init — create schema if absent (idempotent).
+stats_db_init() {
+  require_sqlite3
+  stats_init_dir
+  sqlite3 "${STATS_DB}" <<'SQL'
+CREATE TABLE IF NOT EXISTS stats_events (
+  id                          INTEGER PRIMARY KEY AUTOINCREMENT,
+  schema_version              INTEGER NOT NULL,
+  ts                          TEXT    NOT NULL,
+  trace_id                    TEXT    NOT NULL,
+  span_id                     TEXT    NOT NULL UNIQUE,
+  parent_span_id              TEXT,
+  session_id                  TEXT,
+  gen_ai_tool_name            TEXT,
+  verb                        TEXT    NOT NULL,
+  adapter_route               TEXT    NOT NULL,
+  site                        TEXT,
+  selector_kind               TEXT,
+  selector_value              TEXT,
+  duration_ms                 INTEGER,
+  argv_bytes                  INTEGER DEFAULT 0,
+  stdout_bytes                INTEGER DEFAULT 0,
+  stderr_bytes                INTEGER DEFAULT 0,
+  rc                          INTEGER,
+  outcome                     TEXT    NOT NULL,
+  failure_mode                TEXT,
+  model                       TEXT,
+  service_tier                TEXT,
+  input_tokens                INTEGER,
+  output_tokens               INTEGER,
+  cache_read_tokens           INTEGER,
+  cache_create_tokens         INTEGER,
+  post_condition_target_type  TEXT,
+  post_condition_matcher      TEXT,
+  post_condition_hit          INTEGER,
+  post_condition_expected     TEXT,
+  post_condition_observed     TEXT,
+  raw_json                    TEXT    NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ix_stats_ts            ON stats_events(ts DESC);
+CREATE INDEX IF NOT EXISTS ix_stats_verb_route    ON stats_events(verb, adapter_route);
+CREATE INDEX IF NOT EXISTS ix_stats_outcome       ON stats_events(outcome);
+CREATE INDEX IF NOT EXISTS ix_stats_site          ON stats_events(site);
+CREATE INDEX IF NOT EXISTS ix_stats_failure_mode  ON stats_events(failure_mode);
+
+CREATE TABLE IF NOT EXISTS stats_cursor (
+  source     TEXT PRIMARY KEY,
+  last_line  INTEGER NOT NULL DEFAULT 0,
+  last_ts    TEXT
+);
+CREATE TABLE IF NOT EXISTS stats_overrides (
+  span_id     TEXT PRIMARY KEY,
+  verdict     TEXT NOT NULL,
+  reason      TEXT,
+  marked_at   TEXT NOT NULL
+);
+PRAGMA user_version = 1;
+SQL
+  chmod 600 "${STATS_DB}" 2>/dev/null || true
+}
+
+# stats_rebuild — tail JSONL from last cursor, upsert into SQLite.
+stats_rebuild() {
+  stats_db_init
+  [ -f "${STATS_JSONL}" ] || { ok "stats: no JSONL yet — nothing to rebuild"; return 0; }
+
+  local last_line cur new_lines processed=0
+  last_line=$(sqlite3 "${STATS_DB}" \
+    "SELECT COALESCE(last_line, 0) FROM stats_cursor WHERE source='stats.jsonl';" 2>/dev/null \
+    || printf '0')
+  last_line="${last_line:-0}"
+  cur=$(wc -l < "${STATS_JSONL}" | tr -d ' ')
+
+  if [ "${cur}" -le "${last_line}" ]; then
+    ok "stats: SQLite up to date (${cur} lines indexed)"
+    return 0
+  fi
+
+  # Stream new lines into SQL inserts via jq → sqlite3 stdin (single transaction).
+  new_lines=$(( cur - last_line ))
+  {
+    printf 'BEGIN;\n'
+    tail -n "${new_lines}" "${STATS_JSONL}" | jq -r '
+      def q: tostring | gsub("'"'"'"; "'"'"''"'"'");
+      [
+        (.schema_version // 1 | tostring),
+        ("'"'"'" + (.ts // "" | q) + "'"'"'"),
+        ("'"'"'" + (.trace_id // "" | q) + "'"'"'"),
+        ("'"'"'" + (.span_id // "" | q) + "'"'"'"),
+        (if .parent_span_id then ("'"'"'" + (.parent_span_id | q) + "'"'"'") else "NULL" end),
+        (if .session_id then ("'"'"'" + (.session_id | q) + "'"'"'") else "NULL" end),
+        (if .gen_ai_tool_name then ("'"'"'" + (.gen_ai_tool_name | q) + "'"'"'") else "NULL" end),
+        ("'"'"'" + (.verb // "" | q) + "'"'"'"),
+        ("'"'"'" + (.adapter_route // "" | q) + "'"'"'"),
+        (if .site then ("'"'"'" + (.site | q) + "'"'"'") else "NULL" end),
+        (if .selector_kind then ("'"'"'" + (.selector_kind | q) + "'"'"'") else "NULL" end),
+        (if .selector_value then ("'"'"'" + (.selector_value | q) + "'"'"'") else "NULL" end),
+        (.duration_ms // 0 | tostring),
+        (.argv_bytes // 0 | tostring),
+        (.stdout_bytes // 0 | tostring),
+        (.stderr_bytes // 0 | tostring),
+        (.rc // 0 | tostring),
+        ("'"'"'" + (.outcome // "" | q) + "'"'"'"),
+        (if .failure_mode then ("'"'"'" + (.failure_mode | q) + "'"'"'") else "NULL" end),
+        (if .model then ("'"'"'" + (.model | q) + "'"'"'") else "NULL" end),
+        (if .service_tier then ("'"'"'" + (.service_tier | q) + "'"'"'") else "NULL" end),
+        (if .gen_ai_usage_input_tokens  then (.gen_ai_usage_input_tokens | tostring) else "NULL" end),
+        (if .gen_ai_usage_output_tokens then (.gen_ai_usage_output_tokens | tostring) else "NULL" end),
+        (if .gen_ai_usage_cache_read_input_tokens     then (.gen_ai_usage_cache_read_input_tokens | tostring) else "NULL" end),
+        (if .gen_ai_usage_cache_creation_input_tokens then (.gen_ai_usage_cache_creation_input_tokens | tostring) else "NULL" end),
+        (if .post_condition_target_type then ("'"'"'" + (.post_condition_target_type | q) + "'"'"'") else "NULL" end),
+        (if .post_condition_matcher     then ("'"'"'" + (.post_condition_matcher | q) + "'"'"'") else "NULL" end),
+        (if .post_condition_hit == true then "1" elif .post_condition_hit == false then "0" else "NULL" end),
+        (if .post_condition_expected then ("'"'"'" + (.post_condition_expected | q) + "'"'"'") else "NULL" end),
+        (if .post_condition_observed then ("'"'"'" + (.post_condition_observed | q) + "'"'"'") else "NULL" end),
+        ("'"'"'" + (. | tostring | q) + "'"'"'")
+      ] | "INSERT OR IGNORE INTO stats_events VALUES (NULL," + join(",") + ");"
+    '
+    printf "INSERT INTO stats_cursor(source,last_line,last_ts) VALUES('stats.jsonl',%d,datetime('now')) ON CONFLICT(source) DO UPDATE SET last_line=excluded.last_line,last_ts=excluded.last_ts;\n" "${cur}"
+    printf 'COMMIT;\n'
+  } | sqlite3 "${STATS_DB}"
+  processed="${new_lines}"
+  ok "stats: rebuilt — indexed ${processed} new event(s) (total lines: ${cur})"
+}
+
+# stats_load_prices — sources the JSON price table; sets globals PRICE_<MODEL>_<KIND>.
+# Falls back silently if file missing — cost columns become null in report.
+stats_load_prices() {
+  PRICES_AVAILABLE=0
+  [ -f "${PRICES_FILE}" ] || return 0
+  PRICES_AVAILABLE=1
+}
+
+# stats_report — print summary tables.
+stats_report() {
+  require_sqlite3
+  stats_rebuild >/dev/null 2>&1 || true
+  [ -f "${STATS_DB}" ] || { ok "stats: no events yet"; emit_summary verb=stats tool=none why=report status=empty events=0; return 0; }
+
+  local days=7 route_filter="" verb_filter="" pareto=0
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --days)   days="$2"; shift 2 ;;
+      --route)  route_filter="$2"; shift 2 ;;
+      --verb)   verb_filter="$2"; shift 2 ;;
+      --pareto) pareto=1; shift ;;
+      *) die "${EXIT_USAGE_ERROR}" "report: unknown flag '$1'" ;;
+    esac
+  done
+
+  local where="WHERE ts >= datetime('now', '-${days} days')"
+  [ -n "${route_filter}" ] && where="${where} AND adapter_route='${route_filter}'"
+  [ -n "${verb_filter}" ]  && where="${where} AND verb='${verb_filter}'"
+
+  stats_load_prices
+
+  printf '\n=== browser-stats report (last %s day(s)) ===\n\n' "${days}" >&2
+
+  # Headline: events / outcomes.
+  local total
+  total=$(sqlite3 "${STATS_DB}" "SELECT COUNT(*) FROM stats_events ${where};")
+  [ "${total}" = "0" ] && { ok "stats: no events in window"; emit_summary verb=stats tool=none why=report status=empty events=0; return 0; }
+
+  printf 'Events: %s\n' "${total}" >&2
+  sqlite3 -separator $'\t' "${STATS_DB}" "
+    SELECT outcome, COUNT(*) AS n,
+           ROUND(100.0*COUNT(*)/${total}, 1) AS pct
+    FROM stats_events ${where}
+    GROUP BY outcome ORDER BY n DESC;" \
+    | awk -F'\t' 'BEGIN{printf "\n  %-10s %8s %8s\n", "outcome","count","pct"}
+                  {printf "  %-10s %8s %7s%%\n",$1,$2,$3}' >&2
+
+  # Route × verb table.
+  printf '\nRoute × verb:\n' >&2
+  sqlite3 -separator $'\t' "${STATS_DB}" "
+    SELECT adapter_route, verb, COUNT(*) AS n,
+           SUM(CASE WHEN outcome='success' THEN 1 ELSE 0 END) AS ok,
+           CAST(AVG(duration_ms) AS INTEGER) AS avg_ms,
+           CAST(AVG(stdout_bytes) AS INTEGER) AS avg_out
+    FROM stats_events ${where}
+    GROUP BY adapter_route, verb
+    ORDER BY n DESC LIMIT 20;" \
+    | awk -F'\t' 'BEGIN{printf "  %-22s %-12s %6s %6s %8s %10s\n","route","verb","n","ok","avg_ms","avg_out_b"}
+                  {printf "  %-22s %-12s %6s %6s %8s %10s\n",$1,$2,$3,$4,$5,$6}' >&2
+
+  # Failure modes.
+  printf '\nFailure modes:\n' >&2
+  sqlite3 -separator $'\t' "${STATS_DB}" "
+    SELECT COALESCE(failure_mode,'(unclassified)') AS fm, COUNT(*) AS n
+    FROM stats_events ${where} AND outcome != 'success'
+    GROUP BY failure_mode ORDER BY n DESC LIMIT 15;" 2>/dev/null \
+    | awk -F'\t' '{printf "  %-24s %6s\n",$1,$2}' >&2
+
+  # Post-condition assertion rate.
+  printf '\nPost-condition assertions:\n' >&2
+  sqlite3 -separator $'\t' "${STATS_DB}" "
+    SELECT
+      SUM(CASE WHEN post_condition_hit=1 THEN 1 ELSE 0 END) AS hit,
+      SUM(CASE WHEN post_condition_hit=0 THEN 1 ELSE 0 END) AS miss,
+      SUM(CASE WHEN post_condition_hit IS NULL THEN 1 ELSE 0 END) AS none
+    FROM stats_events ${where};" \
+    | awk -F'\t' '{printf "  hit:%s  miss:%s  not-asserted:%s\n",$1,$2,$3}' >&2
+
+  # Oblivious-success — the killer signal.
+  local obliv
+  obliv=$(sqlite3 "${STATS_DB}" "
+    SELECT COUNT(*) FROM stats_events ${where}
+    AND failure_mode='oblivious_success';")
+  printf '\n  ⚠ oblivious_success: %s (adapter said ok but post-condition failed)\n' "${obliv}" >&2
+
+  # Token + cost rollup if prices available.
+  if [ "${PRICES_AVAILABLE}" = "1" ]; then
+    printf '\nToken / cost (when injected via CLAUDE_USAGE_* env):\n' >&2
+    sqlite3 -separator $'\t' "${STATS_DB}" "
+      SELECT
+        COALESCE(model,'(no model)') AS m,
+        COUNT(*) AS n,
+        COALESCE(SUM(input_tokens),0) AS in_tok,
+        COALESCE(SUM(output_tokens),0) AS out_tok,
+        COALESCE(SUM(cache_read_tokens),0) AS cr,
+        COALESCE(SUM(cache_create_tokens),0) AS cc
+      FROM stats_events ${where}
+      GROUP BY model ORDER BY n DESC;" \
+      | awk -F'\t' 'BEGIN{printf "  %-22s %6s %10s %10s %10s %10s\n","model","n","input","output","cache_r","cache_w"}
+                    {printf "  %-22s %6s %10s %10s %10s %10s\n",$1,$2,$3,$4,$5,$6}' >&2
+
+    # Read prices, compute $ per model. Per-model row produced by SQLite;
+    # jq does the dollar math (centi-USD rounded to keep the report readable).
+    local rows_json
+    rows_json="$(sqlite3 "${STATS_DB}" -json "
+      SELECT
+        COALESCE(model,'(none)') AS model,
+        COALESCE(SUM(input_tokens),0)        AS i,
+        COALESCE(SUM(output_tokens),0)       AS o,
+        COALESCE(SUM(cache_read_tokens),0)   AS cr,
+        COALESCE(SUM(cache_create_tokens),0) AS cc
+      FROM stats_events ${where}
+      GROUP BY model;")"
+    [ -z "${rows_json}" ] && rows_json='[]'
+    local cost_json
+    cost_json=$(
+      jq -nc \
+        --slurpfile prices "${PRICES_FILE}" \
+        --argjson rows "${rows_json}" '
+        ($prices[0].models // {}) as $p
+        | [ $rows[]
+            | . as $r
+            | ($p[$r.model]) as $price
+            | if ($price == null) then
+                {model: $r.model, cost_usd: null}
+              else
+                ( ($r.i  * ($price.input        // 0)) +
+                  ($r.o  * ($price.output       // 0)) +
+                  ($r.cr * ($price.cache_read   // 0)) +
+                  ($r.cc * ($price.cache_create // 0))
+                ) as $raw
+                | (($raw * 100 | round) / 100) as $cents
+                | {model: $r.model, cost_usd: $cents}
+              end
+          ]'
+    )
+    printf '\n  cost (USD, computed from references/stats-prices.json):\n' >&2
+    printf '%s\n' "${cost_json}" | jq -r '.[] | "    \(.model): $\(.cost_usd // "n/a")"' >&2
+  fi
+
+  # Pareto frontier — composite efficiency score.
+  if [ "${pareto}" = "1" ]; then
+    printf '\nRoute Pareto (success_rate × 1/(1+log10(1+avg_kb))):\n' >&2
+    sqlite3 -separator $'\t' "${STATS_DB}" "
+      SELECT adapter_route,
+             ROUND(1.0*SUM(CASE WHEN outcome='success' THEN 1 ELSE 0 END)/COUNT(*),3) AS sr,
+             CAST(AVG(stdout_bytes)/1024.0 AS REAL) AS kb,
+             ROUND(
+               (1.0*SUM(CASE WHEN outcome='success' THEN 1 ELSE 0 END)/COUNT(*))
+               / (1.0 + 0.4343*LN(1.0 + AVG(stdout_bytes)/1024.0))
+             ,3) AS efficiency
+      FROM stats_events ${where}
+      GROUP BY adapter_route ORDER BY efficiency DESC;" \
+      | awk -F'\t' 'BEGIN{printf "  %-22s %8s %10s %12s\n","route","sr","avg_kb","efficiency"}
+                    {printf "  %-22s %8s %10.2f %12s\n",$1,$2,$3,$4}' >&2
+  fi
+
+  emit_summary verb=stats tool=none why=report status=ok events="${total}" days="${days}"
+}
+
+# stats_mark — record a user override for one span_id.
+stats_mark() {
+  stats_db_init
+  local span="${1:-}"; local verdict_full="${2:-}"
+  [ -n "${span}" ] && [ -n "${verdict_full}" ] \
+    || die "${EXIT_USAGE_ERROR}" "mark: usage: browser-stats mark <span_id> <success|fail[:reason]>"
+  local verdict reason
+  verdict="${verdict_full%%:*}"
+  reason="${verdict_full#*:}"
+  [ "${reason}" = "${verdict}" ] && reason=""
+  case "${verdict}" in
+    success|fail) ;;
+    *) die "${EXIT_USAGE_ERROR}" "mark: verdict must be 'success' or 'fail' (got '${verdict}')" ;;
+  esac
+  # Confirm span exists.
+  local found
+  found=$(sqlite3 "${STATS_DB}" "SELECT COUNT(*) FROM stats_events WHERE span_id='${span//\'/\'\'}';")
+  if [ "${found}" = "0" ]; then
+    warn "mark: span_id '${span}' not found in stats_events (override recorded anyway; will apply on rebuild)"
+  fi
+  sqlite3 "${STATS_DB}" "
+    INSERT INTO stats_overrides(span_id, verdict, reason, marked_at)
+    VALUES('${span//\'/\'\'}', '${verdict}', '${reason//\'/\'\'}', datetime('now'))
+    ON CONFLICT(span_id) DO UPDATE SET verdict=excluded.verdict, reason=excluded.reason, marked_at=excluded.marked_at;"
+  ok "stats: override recorded — span=${span} verdict=${verdict} reason=${reason:-(none)}"
+  emit_summary verb=stats tool=none why=mark status=ok span_id="${span}" verdict="${verdict}"
+}
+
+# stats_tune — surface a candidate verb for /autoresearch handoff.
+stats_tune() {
+  require_sqlite3
+  stats_rebuild >/dev/null 2>&1 || true
+  local days=30 route_filter=""
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --days)  days="$2"; shift 2 ;;
+      --route) route_filter="$2"; shift 2 ;;
+      *) die "${EXIT_USAGE_ERROR}" "tune: unknown flag '$1'" ;;
+    esac
+  done
+  local where="WHERE ts >= datetime('now', '-${days} days')"
+  [ -n "${route_filter}" ] && where="${where} AND adapter_route='${route_filter}'"
+
+  printf '\n=== browser-stats tune (last %s day(s)) ===\n\n' "${days}" >&2
+  printf 'Worst-performing (verb,route) by success rate (min 10 events):\n' >&2
+  sqlite3 -separator $'\t' "${STATS_DB}" "
+    SELECT verb, adapter_route,
+           COUNT(*) AS n,
+           ROUND(1.0*SUM(CASE WHEN outcome='success' THEN 1 ELSE 0 END)/COUNT(*),3) AS sr,
+           CAST(AVG(duration_ms) AS INTEGER) AS avg_ms
+    FROM stats_events ${where}
+    GROUP BY verb, adapter_route
+    HAVING n >= 10
+    ORDER BY sr ASC, avg_ms DESC LIMIT 5;" \
+    | awk -F'\t' 'BEGIN{printf "  %-12s %-22s %6s %8s %10s\n","verb","route","n","sr","avg_ms"}
+                  {printf "  %-12s %-22s %6s %8s %10s\n",$1,$2,$3,$4,$5}' >&2
+
+  printf '\nHand-off recipe (human-in-loop):\n' >&2
+  printf '  1. Pick a (verb,route) row above with low success rate.\n' >&2
+  printf '  2. Invoke /autoresearch with that verb as the optimization target.\n' >&2
+  printf '  3. autoresearch reads stats_events to derive eval cases automatically.\n' >&2
+  printf '  4. Review proposed mutation; apply by hand. No auto-merge.\n' >&2
+
+  emit_summary verb=stats tool=none why=tune status=ok days="${days}"
+}
+
+# stats_prune — close the telemetry feedback loop (Phase 14+).
+#
+# Find (site, selector) tuples with ≥THRESHOLD oblivious_success events in
+# the last --days days. Each such tuple = "cache lied" repeatedly: adapter
+# said ok but post-condition failed. The interaction's cached selector is
+# semantically broken (pointing at the wrong element, or page redesigned in
+# a way Phase-13 + Path 3 can't rescue).
+#
+# Modes:
+#   default (advisory): list candidates as NDJSON _kind:prune_candidate
+#                       lines; summary reports count. No mutation.
+#   --apply           : mark each candidate interaction .disabled=true in
+#                       its archetype JSON; emits _kind:prune_applied. The
+#                       disabled marker is the same one Phase 11 self-heal
+#                       sets after 4 plain failures; cache lookups skip
+#                       disabled interactions, so the cloud-LLM path takes
+#                       over on the next call.
+#
+# Why pruning matters: without this, cache pollution accumulates silently
+# over time. Phase 12 telemetry (oblivious_success) was the read side;
+# this is the write side that closes the loop.
+stats_prune() {
+  require_sqlite3
+  stats_rebuild >/dev/null 2>&1 || true
+  local days=7 threshold=3 apply=0 site_filter=""
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --days)      days="$2"; shift 2 ;;
+      --threshold) threshold="$2"; shift 2 ;;
+      --apply)     apply=1; shift ;;
+      --site)      site_filter="$2"; shift 2 ;;
+      -h|--help)
+        cat <<'PRUNEUSAGE' >&2
+browser-stats prune [--days N] [--threshold N] [--apply] [--site NAME]
+
+Find cache archetype interactions where the cached selector has caused
+≥THRESHOLD oblivious_success events in the last --days days (default
+--days 7, --threshold 3). Adapter said ok but post-condition failed
+— a strong "cache is wrong" signal that Phase-13 + Path 3 couldn't
+heal. Dry-run by default: emits _kind:prune_candidate lines. With
+--apply, marks each matching interaction .disabled=true in its
+archetype JSON (lookups skip disabled → cloud-LLM path runs instead).
+PRUNEUSAGE
+        return 0
+        ;;
+      *) die "${EXIT_USAGE_ERROR}" "prune: unknown flag '$1'" ;;
+    esac
+  done
+  local where="WHERE failure_mode='oblivious_success' AND ts >= datetime('now', '-${days} days') AND site IS NOT NULL AND selector_value IS NOT NULL"
+  [ -n "${site_filter}" ] && where="${where} AND site='${site_filter}'"
+
+  local candidates
+  candidates="$(sqlite3 -separator $'\t' "${STATS_DB}" "
+    SELECT site, selector_value, COUNT(*) AS n
+    FROM stats_events ${where}
+    GROUP BY site, selector_value
+    HAVING n >= ${threshold}
+    ORDER BY n DESC;" 2>/dev/null)"
+
+  local candidate_count=0 applied_count=0
+  while IFS=$'\t' read -r site sel n; do
+    [ -z "${site}" ] && continue
+    [ -z "${sel}" ] && continue
+    local arch_dir="${BROWSER_SKILL_HOME}/memory/${site}/archetypes"
+    [ -d "${arch_dir}" ] || continue
+    local arch_file
+    for arch_file in "${arch_dir}"/*.json; do
+      [ -f "${arch_file}" ] || continue
+      local arch_id intent
+      arch_id="$(basename "${arch_file}" .json)"
+      intent="$(jq -r --arg sel "${sel}" \
+        '.interactions[]? | select(.selector == $sel) | .intent' \
+        "${arch_file}" 2>/dev/null | head -1)"
+      if [ -n "${intent}" ]; then
+        candidate_count=$((candidate_count + 1))
+        jq -nc \
+          --arg site "${site}" --arg sel "${sel}" \
+          --arg arch_id "${arch_id}" --arg intent "${intent}" \
+          --argjson n "${n}" \
+          '{_kind:"prune_candidate", site:$site, selector:$sel,
+            oblivious_success_count:$n, archetype_id:$arch_id, intent:$intent}'
+        if [ "${apply}" = "1" ]; then
+          local tmp
+          tmp="$(mktemp)"
+          jq --arg sel "${sel}" \
+            '(.interactions[] | select(.selector == $sel)).disabled = true' \
+            "${arch_file}" > "${tmp}" \
+            && mv "${tmp}" "${arch_file}" \
+            && chmod 600 "${arch_file}" \
+            && applied_count=$((applied_count + 1))
+          jq -nc \
+            --arg site "${site}" --arg sel "${sel}" \
+            --arg arch_id "${arch_id}" --arg intent "${intent}" \
+            '{_kind:"prune_applied", site:$site, selector:$sel,
+              archetype_id:$arch_id, intent:$intent}'
+        fi
+        break
+      fi
+    done
+  done <<< "${candidates}"
+
+  emit_summary verb=stats tool=none why=prune status=ok \
+    days="${days}" threshold="${threshold}" \
+    candidates="${candidate_count}" applied="${applied_count}"
+}
+
+case "${subcmd}" in
+  rebuild) stats_rebuild "$@" ;;
+  report)  stats_report  "$@" ;;
+  mark)    stats_mark    "$@" ;;
+  tune)    stats_tune    "$@" ;;
+  prune)   stats_prune   "$@" ;;
+  event)
+    # Internal use — adapters normally call lib/stats.sh helpers directly.
+    # Exposed via CLI for debugging and for tests.
+    die "${EXIT_USAGE_ERROR}" "browser-stats event: reserved for in-process callers (use lib/stats.sh::stats_run_adapter_emit)"
+    ;;
+  *) die "${EXIT_USAGE_ERROR}" "browser-stats: unknown subcommand '${subcmd}' (expected: rebuild|report|mark|tune|prune)" ;;
+esac

package/scripts/browser-tab-close.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# scripts/browser-tab-close.sh — close a tab in the daemon-held browser.
+# Usage: bash scripts/browser-tab-close.sh [--site NAME] [--tool NAME]
+#                                           [--dry-run] [--raw]
+#                                           (--tab-id N | --by-url-pattern STR)
+#
+# Routes to chrome-devtools-mcp by default (Phase 6 part 8-iii). Daemon-required.
+# Splices the matching entry from the daemon's tabs[] cache + asks upstream MCP
+# to close the page. If the closed tab matches `currentTab`, the pointer is
+# nulled (`current_tab_id: null` in subsequent tab-list output).
+#
+# Mutex: exactly one of --tab-id (canonical 1-based id from tab-list output) or
+# --by-url-pattern (substring-contains, first-match-wins, mirrors tab-switch).
+#
+# Why --tab-id instead of --by-index: by the time agents reach tab-close, they
+# already hold a tab_id from tab-list. Positional indexing would drift across
+# successive closes; canonical id is unambiguous.
+
+set -euo pipefail
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/output.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/output.sh"
+# shellcheck source=lib/router.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/router.sh"
+# shellcheck source=lib/verb_helpers.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/verb_helpers.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+parse_verb_globals "$@"
+
+resolve_session_storage_state
+
+tab_id="" by_url_pattern=""
+verb_argv=()
+i=0
+while [ "${i}" -lt "${#REMAINING_ARGV[@]}" ]; do
+  case "${REMAINING_ARGV[i]}" in
+    --tab-id)
+      tab_id="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${tab_id}" ] || die "${EXIT_USAGE_ERROR}" "--tab-id requires a value"
+      verb_argv+=(--tab-id "${tab_id}")
+      i=$((i + 2))
+      ;;
+    --by-url-pattern)
+      by_url_pattern="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${by_url_pattern}" ] || die "${EXIT_USAGE_ERROR}" "--by-url-pattern requires a value"
+      verb_argv+=(--by-url-pattern "${by_url_pattern}")
+      i=$((i + 2))
+      ;;
+    *)
+      verb_argv+=("${REMAINING_ARGV[i]}")
+      i=$((i + 1))
+      ;;
+  esac
+done
+
+# Mutex + presence: exactly one selector required.
+if [ -n "${tab_id}" ] && [ -n "${by_url_pattern}" ]; then
+  die "${EXIT_USAGE_ERROR}" "--tab-id and --by-url-pattern are mutually exclusive"
+fi
+if [ -z "${tab_id}" ] && [ -z "${by_url_pattern}" ]; then
+  die "${EXIT_USAGE_ERROR}" "tab-close requires exactly one of --tab-id N or --by-url-pattern STR"
+fi
+
+# Validate tab_id is a positive integer (1-based).
+if [ -n "${tab_id}" ]; then
+  if ! printf '%s' "${tab_id}" | grep -Eq '^[1-9][0-9]*$'; then
+    die "${EXIT_USAGE_ERROR}" "--tab-id must be a positive integer (1-based); got: ${tab_id}"
+  fi
+fi
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  if [ -n "${tab_id}" ]; then
+    ok "dry-run: would close tab #${tab_id}"
+    emit_summary verb=tab-close tool=none why=dry-run status=ok tab_id="${tab_id}" dry_run=true
+  else
+    ok "dry-run: would close first tab matching ${by_url_pattern}"
+    emit_summary verb=tab-close tool=none why=dry-run status=ok by_url_pattern="${by_url_pattern}" dry_run=true
+  fi
+  exit 0
+fi
+
+picked="$(pick_tool tab-close "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+set +e
+adapter_out="$(invoke_with_retry tab-close "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  emit_summary verb=tab-close tool="${tool_name}" why="${why}" status=ok
+  exit 0
+fi
+emit_summary verb=tab-close tool="${tool_name}" why="${why}" status=error
+exit "${adapter_rc}"