browser-automation-skill 0.71.0

package/scripts/browser-replay.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+# scripts/browser-replay.sh — re-execute a prior capture's steps + diff against
+# original. Phase 9 part 1-iv.
+#
+# Usage:
+#   bash scripts/browser-replay.sh <capture-id> [--strict] [--session NAME] [--dry-run]
+#
+# Loads ${CAPTURES_DIR}/<capture-id>/meta.json + steps.jsonl. Re-dispatches
+# each step via flow_dispatch (composes 9-1-i + 9-1-ii). Writes a NEW capture
+# with `replay_of: <capture-id>` + `replay_match: bool`. Emits per-step
+# replay_diff event lines + one replay_diff_summary on stdout.
+#
+# Status mapping (per design doc §3 F5 + plan locked decision D3):
+#   All steps match → status:ok   replay_match:true   exit 0
+#   Mixed match/diverge → status:partial replay_match:false exit 0
+#   All steps diverged OR aborted → status:error exit non-zero
+#
+# --strict flag: ANY divergence → exit 13 (EXIT_ASSERTION_FAILED), matching
+# the assert verb's exit code. Composes with CI scripts that grep for 13.
+
+set -euo pipefail
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPTS_DIR="${SCRIPT_DIR}"
+export SCRIPTS_DIR
+
+# 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/capture.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/capture.sh"
+# shellcheck source=lib/flow.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/flow.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+capture_id="${1:-}"
+[ -n "${capture_id}" ] || die "${EXIT_USAGE_ERROR}" "browser-replay: missing <capture-id>"
+shift
+
+strict=0
+dry_run=0
+session_override=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --strict)  strict=1; shift ;;
+    --dry-run) dry_run=1; shift ;;
+    --session) session_override="$2"; shift 2 ;;
+    *)         die "${EXIT_USAGE_ERROR}" "browser-replay: unknown flag '$1'" ;;
+  esac
+done
+
+old_dir="${CAPTURES_DIR}/${capture_id}"
+old_meta="${old_dir}/meta.json"
+old_steps="${old_dir}/steps.jsonl"
+
+[ -d "${old_dir}" ] || die "${EXIT_USAGE_ERROR}" "browser-replay: no such capture '${capture_id}' at ${old_dir}"
+[ -f "${old_meta}" ] || die "${EXIT_USAGE_ERROR}" "browser-replay: no meta.json at ${old_meta}"
+
+# Reject non-flow captures — only `verb: flow` (or `verb: replay`) captures
+# carry steps.jsonl. Per plan sub-scope: replay only consumes flow captures.
+old_verb="$(jq -r '.verb' "${old_meta}")"
+case "${old_verb}" in
+  flow|replay) ;;
+  *) die "${EXIT_USAGE_ERROR}" "browser-replay: capture ${capture_id} is not a flow capture (verb=${old_verb})" ;;
+esac
+
+[ -f "${old_steps}" ] || die "${EXIT_USAGE_ERROR}" "browser-replay: no steps.jsonl at ${old_steps}"
+
+# Dry-run pre-pass: print planned steps; no execution.
+if [ "${dry_run}" = "1" ]; then
+  ok "dry-run: would replay ${capture_id} (verb=${old_verb})"
+  printf '%s\n' "$(cat "${old_steps}")"
+  emit_summary verb=replay tool=none why=dry-run status=ok \
+    replay_of="${capture_id}" dry_run=true
+  exit 0
+fi
+
+# Real run: capture pipeline + per-step re-dispatch + per-step diff.
+capture_start "replay"
+new_meta="${CAPTURE_DIR}/meta.json"
+tmp="${new_meta}.tmp.$$"
+jq --arg ro "${capture_id}" '.replay_of = $ro' "${new_meta}" > "${tmp}"
+chmod 600 "${tmp}"
+mv "${tmp}" "${new_meta}"
+
+new_steps="${CAPTURE_DIR}/steps.jsonl"
+: > "${new_steps}"
+chmod 600 "${new_steps}"
+
+# Reset flow state in this shell (replay starts fresh; no inherited refs).
+declare -gA FLOW_VARS=()
+declare -gA FLOW_REFS=()
+
+total_steps=0
+matched_steps=0
+diverged_steps=0
+last_exit=0
+
+# Iterate the OLD steps in order; re-dispatch each; emit diff event.
+while IFS= read -r old_step; do
+  [ -z "${old_step}" ] && continue
+  total_steps=$((total_steps + 1))
+
+  # Re-build the step input for flow_dispatch from the OLD step's verb + args.
+  # (We don't carry over the OLD status / summary — we want the FRESH outcome.)
+  step_input="$(printf '%s' "${old_step}" | jq -c '{step_index, verb, args}')"
+  new_step_event="$(flow_dispatch "${step_input}")"
+  printf '%s\n' "${new_step_event}" >> "${new_steps}"
+
+  # Diff old vs new.
+  set +e
+  diff_event="$(flow_diff_steps "${old_step}" "${new_step_event}")"
+  diff_rc=$?
+  set -e
+  printf '%s\n' "${diff_event}"
+
+  if [ "${diff_rc}" = "0" ]; then
+    matched_steps=$((matched_steps + 1))
+  else
+    diverged_steps=$((diverged_steps + 1))
+  fi
+
+  # Track step-level errors for status mapping.
+  step_status="$(printf '%s' "${new_step_event}" | jq -r '.status')"
+  if [ "${step_status}" != "ok" ]; then
+    last_exit="$(printf '%s' "${new_step_event}" | jq -r '.exit_code')"
+  fi
+
+  # Phase 9-1-ii ref-harvest semantics also apply during replay.
+  refs_for_step="$(printf '%s' "${new_step_event}" | jq -c '.refs // null')"
+  if [ "${refs_for_step}" != "null" ]; then
+    FLOW_REFS=()
+    while IFS=$'\t' read -r ref_text ref_id; do
+      [ -z "${ref_text}" ] && continue
+      FLOW_REFS["${ref_text}"]="${ref_id}"
+    done <<< "$(printf '%s' "${refs_for_step}" | jq -r '.[] | "\(.text)\t\(.ref)"')"
+  fi
+done < "${old_steps}"
+
+# Determine replay_match + status.
+if [ "${diverged_steps}" = "0" ] && [ "${total_steps}" -gt "0" ]; then
+  replay_match=true
+  flow_status="ok"
+elif [ "${matched_steps}" = "0" ] && [ "${diverged_steps}" -gt "0" ]; then
+  replay_match=false
+  flow_status="error"
+else
+  replay_match=false
+  flow_status="partial"
+fi
+
+# Append replay-specific fields to meta.json.
+tmp="${new_meta}.tmp.$$"
+jq \
+  --arg     ro    "${capture_id}" \
+  --argjson rm    "${replay_match}" \
+  --argjson tot   "${total_steps}" \
+  --argjson mat   "${matched_steps}" \
+  --argjson div   "${diverged_steps}" \
+  '. + {replay_of: $ro, replay_match: $rm, total_steps: $tot, matched_steps: $mat, diverged_steps: $div}' \
+  "${new_meta}" > "${tmp}"
+chmod 600 "${tmp}"
+mv "${tmp}" "${new_meta}"
+
+capture_finish "${flow_status}" true
+
+# Emit replay_diff_summary line.
+jq -nc \
+  --arg     event         "replay_diff_summary" \
+  --arg     old_capture_id "${capture_id}" \
+  --arg     new_capture_id "${CAPTURE_ID}" \
+  --argjson total_steps   "${total_steps}" \
+  --argjson matched_steps "${matched_steps}" \
+  --argjson diverged_steps "${diverged_steps}" \
+  --argjson replay_match  "${replay_match}" \
+  '{event: $event, old_capture_id: $old_capture_id, new_capture_id: $new_capture_id,
+    total_steps: $total_steps, matched_steps: $matched_steps, diverged_steps: $diverged_steps,
+    replay_match: $replay_match}'
+
+# --strict: any divergence → exit 13 (EXIT_ASSERTION_FAILED).
+if [ "${strict}" = "1" ] && [ "${diverged_steps}" -gt "0" ]; then
+  emit_summary verb=replay tool=none why=run status=error \
+    replay_of="${capture_id}" capture_id="${CAPTURE_ID}" \
+    replay_match="${replay_match}" \
+    total_steps="${total_steps}" matched_steps="${matched_steps}" diverged_steps="${diverged_steps}"
+  exit "${EXIT_ASSERTION_FAILED}"
+fi
+
+emit_summary verb=replay tool=none why=run status="${flow_status}" \
+  replay_of="${capture_id}" capture_id="${CAPTURE_ID}" \
+  replay_match="${replay_match}" \
+  total_steps="${total_steps}" matched_steps="${matched_steps}" diverged_steps="${diverged_steps}"
+
+if [ "${flow_status}" = "ok" ] || [ "${flow_status}" = "partial" ]; then
+  exit 0
+fi
+exit "${last_exit}"

package/scripts/browser-route.sh

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# scripts/browser-route.sh — register a network-route rule on the daemon.
+# Usage: bash scripts/browser-route.sh [--site NAME] [--tool NAME]
+#                                       [--dry-run] [--raw]
+#                                       --pattern URL_PATTERN
+#                                       --action allow|block|fulfill
+#                                       [--status N]                    (fulfill)
+#                                       [--body STR | --body-stdin]     (fulfill)
+#
+# Routes to chrome-devtools-mcp by default. Daemon-state-mutating: registers
+# the rule in the daemon's routeRules array. Daemon-required.
+#
+# Phase 6 part 7-i: action ∈ {allow, block}.
+# Phase 6 part 7-ii: action fulfill adds synthetic responses (--status / --body
+# or --body-stdin). Body via stdin uses the same passthrough pattern as
+# fill --secret-stdin (browser-fill.sh:87): the bash script forwards the
+# --body-stdin flag and stdin inherits naturally to the bridge subprocess.
+#
+# Body binary-safety: any non-NUL byte sequence rides through. NUL itself
+# can't ride bash variables or JSON strings — multipart bodies legitimately
+# containing NUL would need a different transport (out of scope for 7-ii).
+
+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
+
+pattern="" action="" status_code="" body_inline="" use_body_stdin=0
+have_body_inline=0
+verb_argv=()
+i=0
+while [ "${i}" -lt "${#REMAINING_ARGV[@]}" ]; do
+  case "${REMAINING_ARGV[i]}" in
+    --pattern)
+      pattern="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${pattern}" ] || die "${EXIT_USAGE_ERROR}" "--pattern requires a value"
+      verb_argv+=(--pattern "${pattern}")
+      i=$((i + 2))
+      ;;
+    --action)
+      action="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${action}" ] || die "${EXIT_USAGE_ERROR}" "--action requires a value"
+      case "${action}" in
+        allow|block|fulfill) ;;
+        *) die "${EXIT_USAGE_ERROR}" "--action must be one of {allow, block, fulfill} (got: ${action})" ;;
+      esac
+      verb_argv+=(--action "${action}")
+      i=$((i + 2))
+      ;;
+    --status)
+      status_code="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${status_code}" ] || die "${EXIT_USAGE_ERROR}" "--status requires a value"
+      verb_argv+=(--status "${status_code}")
+      i=$((i + 2))
+      ;;
+    --body)
+      body_inline="${REMAINING_ARGV[i+1]:-}"
+      have_body_inline=1
+      verb_argv+=(--body "${body_inline}")
+      i=$((i + 2))
+      ;;
+    --body-stdin)
+      use_body_stdin=1
+      verb_argv+=(--body-stdin)
+      i=$((i + 1))
+      ;;
+    *)
+      verb_argv+=("${REMAINING_ARGV[i]}")
+      i=$((i + 1))
+      ;;
+  esac
+done
+
+[ -n "${pattern}" ] || die "${EXIT_USAGE_ERROR}" "route requires --pattern URL_PATTERN"
+[ -n "${action}" ]  || die "${EXIT_USAGE_ERROR}" "route requires --action (allow|block|fulfill)"
+
+# 7-ii validation: fulfill-only flags are rejected when paired with block/allow.
+if [ "${action}" != "fulfill" ]; then
+  [ -z "${status_code}" ] || die "${EXIT_USAGE_ERROR}" "--status is only valid with --action fulfill"
+  [ "${have_body_inline}" = "0" ] || die "${EXIT_USAGE_ERROR}" "--body is only valid with --action fulfill"
+  [ "${use_body_stdin}" = "0" ]   || die "${EXIT_USAGE_ERROR}" "--body-stdin is only valid with --action fulfill"
+fi
+
+# 7-ii: fulfill requires status + (body | body-stdin); body / body-stdin mutex.
+body_bytes=0
+if [ "${action}" = "fulfill" ]; then
+  [ -n "${status_code}" ] || die "${EXIT_USAGE_ERROR}" "fulfill requires --status N (HTTP code in 100-599)"
+  case "${status_code}" in
+    ''|*[!0-9]*) die "${EXIT_USAGE_ERROR}" "--status must be an integer (got: ${status_code})" ;;
+  esac
+  if [ "${status_code}" -lt 100 ] || [ "${status_code}" -gt 599 ]; then
+    die "${EXIT_USAGE_ERROR}" "--status must be in 100-599 (got: ${status_code})"
+  fi
+  if [ "${have_body_inline}" = "1" ] && [ "${use_body_stdin}" = "1" ]; then
+    die "${EXIT_USAGE_ERROR}" "--body and --body-stdin are mutually exclusive"
+  fi
+  if [ "${have_body_inline}" = "0" ] && [ "${use_body_stdin}" = "0" ]; then
+    die "${EXIT_USAGE_ERROR}" "fulfill requires --body STR or --body-stdin"
+  fi
+  if [ "${have_body_inline}" = "1" ]; then
+    body_bytes="${#body_inline}"
+  fi
+  # body_bytes for --body-stdin is a daemon-side concern; bash doesn't peek at
+  # stdin (would consume it before the bridge subprocess can read).
+fi
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  if [ "${action}" = "fulfill" ]; then
+    ok "dry-run: would register fulfill rule pattern=${pattern} status=${status_code}"
+    if [ "${use_body_stdin}" = "1" ]; then
+      # Don't consume stdin in dry-run — body_bytes unknown until daemon reads it.
+      emit_summary verb=route tool=none why=dry-run status=ok \
+                   pattern="${pattern}" action="${action}" \
+                   fulfill_status="${status_code}" body_source=stdin dry_run=true
+    else
+      emit_summary verb=route tool=none why=dry-run status=ok \
+                   pattern="${pattern}" action="${action}" \
+                   fulfill_status="${status_code}" body_bytes="${body_bytes}" dry_run=true
+    fi
+  else
+    ok "dry-run: would register route rule pattern=${pattern} action=${action}"
+    emit_summary verb=route tool=none why=dry-run status=ok \
+                 pattern="${pattern}" action="${action}" dry_run=true
+  fi
+  exit 0
+fi
+
+picked="$(pick_tool route "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+set +e
+adapter_out="$(invoke_with_retry route "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  if [ "${action}" = "fulfill" ]; then
+    emit_summary verb=route tool="${tool_name}" why="${why}" status=ok \
+                 pattern="${pattern}" action="${action}" \
+                 fulfill_status="${status_code}"
+  else
+    emit_summary verb=route tool="${tool_name}" why="${why}" status=ok \
+                 pattern="${pattern}" action="${action}"
+  fi
+  exit 0
+fi
+emit_summary verb=route tool="${tool_name}" why="${why}" status=error \
+             pattern="${pattern}" action="${action}"
+exit "${adapter_rc}"

package/scripts/browser-select.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# scripts/browser-select.sh — pick an option from a <select> element by ref or selector.
+# Usage: bash scripts/browser-select.sh [--site NAME] [--tool NAME]
+#                                        [--dry-run] [--raw]
+#                                        (--ref eN | --selector CSS)
+#                                        (--value V | --label L | --index N)
+#
+# Routes to chrome-devtools-mcp by default (Phase 6 part 2). Stateful —
+# requires a running daemon (refMap precondition; same shape as click/fill).
+# --selector path enables Phase 11 cache dispatch (cache stores selectors,
+# not snapshot-relative refs). Mirrors browser-click/fill/hover precedent.
+
+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
+
+ref="" selector="" value="" label="" index=""
+mode_count=0
+verb_argv=()
+i=0
+while [ "${i}" -lt "${#REMAINING_ARGV[@]}" ]; do
+  case "${REMAINING_ARGV[i]}" in
+    --ref)
+      ref="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${ref}" ] || die "${EXIT_USAGE_ERROR}" "--ref requires a value"
+      verb_argv+=(--ref "${ref}")
+      i=$((i + 2))
+      ;;
+    --selector)
+      selector="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${selector}" ] || die "${EXIT_USAGE_ERROR}" "--selector requires a value"
+      verb_argv+=(--selector "${selector}")
+      i=$((i + 2))
+      ;;
+    --value)
+      value="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${value}" ] || die "${EXIT_USAGE_ERROR}" "--value requires a value"
+      verb_argv+=(--value "${value}")
+      mode_count=$((mode_count + 1))
+      i=$((i + 2))
+      ;;
+    --label)
+      label="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${label}" ] || die "${EXIT_USAGE_ERROR}" "--label requires a value"
+      verb_argv+=(--label "${label}")
+      mode_count=$((mode_count + 1))
+      i=$((i + 2))
+      ;;
+    --index)
+      index="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${index}" ] || die "${EXIT_USAGE_ERROR}" "--index requires a value"
+      verb_argv+=(--index "${index}")
+      mode_count=$((mode_count + 1))
+      i=$((i + 2))
+      ;;
+    *)
+      verb_argv+=("${REMAINING_ARGV[i]}")
+      i=$((i + 1))
+      ;;
+  esac
+done
+
+if [ -n "${ref}" ] && [ -n "${selector}" ]; then
+  die "${EXIT_USAGE_ERROR}" "--ref and --selector are mutually exclusive"
+fi
+if [ -z "${ref}" ] && [ -z "${selector}" ]; then
+  die "${EXIT_USAGE_ERROR}" "select requires --ref eN or --selector CSS"
+fi
+if [ "${mode_count}" -eq 0 ]; then
+  die "${EXIT_USAGE_ERROR}" "select requires one of --value, --label, or --index"
+fi
+if [ "${mode_count}" -gt 1 ]; then
+  die "${EXIT_USAGE_ERROR}" "select: --value / --label / --index are mutually exclusive"
+fi
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  ok "dry-run: would select ${ref:-${selector}} (value=${value}, label=${label}, index=${index})"
+  emit_summary verb=select tool=none why=dry-run status=ok ref="${ref}" selector="${selector}" \
+               value="${value}" label="${label}" index="${index}" dry_run=true
+  exit 0
+fi
+
+picked="$(pick_tool select "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+set +e
+adapter_out="$(invoke_with_retry select "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  emit_summary verb=select tool="${tool_name}" why="${why}" status=ok ref="${ref}" selector="${selector}"
+  exit 0
+fi
+emit_summary verb=select tool="${tool_name}" why="${why}" status=error ref="${ref}" selector="${selector}"
+exit "${adapter_rc}"

package/scripts/browser-show-session.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# show-session — emit session metadata only.
+#
+# CRITICAL SECURITY INVARIANT: this verb NEVER emits the storageState contents
+# (cookies, tokens, localStorage). Only the meta sidecar (origin, captured_at,
+# expires_in_hours, source_user_agent) is surfaced. The agent has no business
+# seeing raw session material; the adapter applies it via storageState file
+# path, never via JSON pass-through.
+
+set -euo pipefail
+IFS=$'\n\t'
+umask 077
+
+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/session.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/session.sh"
+init_paths
+
+name=""
+usage() { printf 'Usage: show-session --as NAME\n'; }
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --as) name="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "${EXIT_USAGE_ERROR}" "unknown flag: $1" ;;
+  esac
+done
+[ -n "${name}" ] || { usage; die "${EXIT_USAGE_ERROR}" "--as is required"; }
+assert_safe_name "${name}" "session-name"
+
+started_at_ms="$(now_ms)"
+
+if ! session_exists "${name}"; then
+  die "${EXIT_SESSION_EXPIRED}" "session not found: ${name}"
+fi
+
+meta="$(session_meta_load "${name}")"
+ss_path="${SESSIONS_DIR}/${name}.json"
+file_size="$(wc -c < "${ss_path}" 2>/dev/null | tr -d ' ' || printf '0')"
+duration_ms=$(( $(now_ms) - started_at_ms ))
+
+# Derive surface-level info from storageState WITHOUT echoing values: count
+# cookies + count distinct origins. Never reveal cookie names, values, or
+# domains beyond the count.
+counts="$(jq -c '{cookie_count: (.cookies // [] | length),
+                 origin_count: (.origins // [] | length)}' "${ss_path}" 2>/dev/null || printf '{}')"
+
+jq -cn --arg n "${name}" --argjson m "${meta}" --argjson c "${counts}" \
+       --argjson s "${file_size}" --argjson d "${duration_ms}" \
+  '{verb: "show-session", tool: "none", why: "show", status: "ok",
+    session: $n, meta: $m,
+    storage_state: ($c + {file_size_bytes: $s}),
+    duration_ms: $d}'

package/scripts/browser-show-site.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# show-site — emit one site's full profile JSON.
+# (Phase 5 will mask credential-shaped fields if any are added; today the
+#  profile contains nothing secret, so this verb has no --reveal flag.)
+set -euo pipefail
+IFS=$'\n\t'
+umask 077
+
+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/site.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/site.sh"
+init_paths
+
+name=""
+usage() { printf 'Usage: show-site --name NAME\n'; }
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --name) name="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "${EXIT_USAGE_ERROR}" "unknown flag: $1" ;;
+  esac
+done
+[ -n "${name}" ] || { usage; die "${EXIT_USAGE_ERROR}" "--name is required"; }
+
+started_at_ms="$(now_ms)"
+profile="$(site_load "${name}")"
+meta="$(site_meta_load "${name}")"
+duration_ms=$(( $(now_ms) - started_at_ms ))
+
+jq -cn --arg n "${name}" --argjson p "${profile}" --argjson m "${meta}" \
+       --argjson d "${duration_ms}" \
+  '{verb: "show-site", tool: "none", why: "show", status: "ok",
+    site: $n, profile: $p, meta: $m, duration_ms: $d}'