browser-automation-skill 0.71.0

package/scripts/browser-fill.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# scripts/browser-fill.sh — fill an input by --ref eN or --selector CSS with --text or --secret-stdin.
+# Usage: bash scripts/browser-fill.sh [--site NAME] [--tool NAME] [--dry-run]
+#                                     [--raw] (--ref eN | --selector CSS)
+#                                     (--text VALUE | --secret-stdin)
+#
+# CRITICAL: --secret-stdin reads the secret from this script's stdin and pipes
+# it to the adapter; the secret never appears on argv (anti-pattern AP-7).
+# Test: tests/browser-fill.bats::secret-not-in-argv.
+#
+# --selector path enables Phase 11 cache dispatch (cache stores selectors,
+# not snapshot-relative refs). Mirrors browser-click.sh's --ref/--selector
+# 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"
+# shellcheck source=lib/stats.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/stats.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+parse_verb_globals "$@"
+
+# Resolve site/session → BROWSER_SKILL_STORAGE_STATE (no-op if neither set).
+# Router's rule_session_required reads the env var to prefer playwright-lib
+# (which natively supports --secret-stdin via stdin-pipe to driver).
+resolve_session_storage_state
+
+ref="" selector="" text="" use_stdin=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))
+      ;;
+    --text)
+      text="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${text}" ] || die "${EXIT_USAGE_ERROR}" "--text requires a value"
+      verb_argv+=(--text "${text}")
+      i=$((i + 2))
+      ;;
+    --secret-stdin)
+      use_stdin=1
+      verb_argv+=(--secret-stdin)
+      i=$((i + 1))
+      ;;
+    *)
+      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}" "fill requires --ref eN or --selector CSS"
+fi
+if [ -n "${text}" ] && [ "${use_stdin}" = "1" ]; then
+  die "${EXIT_USAGE_ERROR}" "--text and --secret-stdin are mutually exclusive"
+fi
+if [ -z "${text}" ] && [ "${use_stdin}" = "0" ]; then
+  die "${EXIT_USAGE_ERROR}" "fill requires --text VALUE or --secret-stdin"
+fi
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  ok "dry-run: would fill ${ref:-${selector}}"
+  emit_summary verb=fill tool=none why=dry-run status=ok ref="${ref}" selector="${selector}" dry_run=true
+  exit 0
+fi
+
+picked="$(pick_tool fill "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+# stdin (if --secret-stdin) flows through to tool_fill -> adapter binary.
+# Capture stdout in subshell; stdin inherits naturally.
+stats_t0="$(now_ms)"
+set +e
+adapter_out="$(invoke_with_retry fill "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+# Phase 12 part 1 + Phase 14 (Bundle #2): per-action telemetry. CRITICAL — when
+# --secret-stdin was used, NEVER auto-derive EXPECT_VALUE from the secret
+# (would leak the secret into stats.jsonl per AP-7). Auto-derive only fires when
+# (a) --text was used (no secrets) AND (b) BROWSER_SKILL_STRICT_POSTCOND=1
+# opts in. Opt-in default: many fill adapters don't echo the typed value back,
+# so a blanket auto-check would generate false oblivious_success events.
+# Future: compose with a follow-up snapshot to read the actual element value.
+if [ "${BROWSER_SKILL_STRICT_POSTCOND:-0}" = "1" ] \
+   && [ "${use_stdin}" = "0" ] && [ -n "${text}" ] \
+   && [ "${adapter_rc}" -eq 0 ]; then
+  : "${BROWSER_STATS_EXPECT_TYPE:=element_value}"
+  : "${BROWSER_STATS_EXPECT_MATCH:=include}"
+  : "${BROWSER_STATS_EXPECT_VALUE:=${text}}"
+fi
+: "${BROWSER_STATS_OBSERVED:=${adapter_out}}"
+export BROWSER_STATS_EXPECT_TYPE BROWSER_STATS_EXPECT_MATCH BROWSER_STATS_EXPECT_VALUE BROWSER_STATS_OBSERVED
+
+stats_run_adapter_emit \
+  "fill" "${tool_name}" "${stats_t0}" "${adapter_rc}" "${adapter_out}" "" \
+  -- "${verb_argv[@]}" || true
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  emit_summary verb=fill tool="${tool_name}" why="${why}" status=ok ref="${ref}" selector="${selector}"
+  exit 0
+fi
+emit_summary verb=fill tool="${tool_name}" why="${why}" status=error ref="${ref}" selector="${selector}"
+exit "${adapter_rc}"

package/scripts/browser-flow.sh

@@ -0,0 +1,316 @@
+#!/usr/bin/env bash
+# scripts/browser-flow.sh — flow runner verb (Phase 9 part 1-i).
+#
+# Usage:
+#   bash scripts/browser-flow.sh run <flow-file> [--var key=val ...] [--dry-run]
+#
+# Sub-modes (current):
+#   run   — execute a .flow.yaml file end-to-end (this PR)
+# Sub-modes (planned):
+#   record — wrap `playwright codegen` (9-1-iii)
+#
+# Capture composition (per design doc 2026-05-10-phase-09-flow-runner-design §3 F4):
+#   one capture per flow run; per-step events streamed to ${CAPTURE_DIR}/steps.jsonl;
+#   meta.json carries verb=flow + flow_name + step_count + successful_steps +
+#   failed_steps + status (ok / partial / error).
+
+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
+
+sub_mode="${1:-}"
+[ -n "${sub_mode}" ] || die "${EXIT_USAGE_ERROR}" "browser-flow: missing sub-mode (use 'run')"
+shift
+
+case "${sub_mode}" in
+  run) ;;
+  record)
+    # Phase 9 part 1-iii: wraps `playwright codegen <url>`; transforms emitted
+    # JS → flow YAML; writes ${OUT} mode 0600. Privacy canary on recorder
+    # write side: passwords detected via /password/i name match, replaced
+    # with ${secrets.password} placeholder.
+    # shellcheck source=lib/flow_record.sh
+    # shellcheck disable=SC1091
+    source "${SCRIPT_DIR}/lib/flow_record.sh"
+
+    record_url=""
+    record_out=""
+    record_name=""
+    record_tool=""
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        --url)  record_url="$2"; shift 2 ;;
+        --out)  record_out="$2"; shift 2 ;;
+        --name) record_name="$2"; shift 2 ;;
+        --tool) record_tool="$2"; shift 2 ;;
+        --site) shift 2 ;;  # accepted; site resolution deferred
+        *)      die "${EXIT_USAGE_ERROR}" "browser-flow record: unknown flag '$1'" ;;
+      esac
+    done
+
+    # Per locked decision W1: codegen targets Playwright/Chrome; obscura's
+    # stateless one-shot model has no interactive recording surface.
+    if [ "${record_tool}" = "obscura" ]; then
+      die "${EXIT_USAGE_ERROR}" "browser-flow record: recorder does not support obscura (codegen targets Playwright; obscura is stateless one-shot — no interactive recording surface)"
+    fi
+
+    # Per locked decision O1: --out is REQUIRED.
+    [ -n "${record_out}" ] || die "${EXIT_USAGE_ERROR}" "browser-flow record: --out FILE is required"
+    [ -n "${record_url}" ] || die "${EXIT_USAGE_ERROR}" "browser-flow record: --url URL is required (or --site NAME — deferred to follow-up)"
+
+    # Path security: realpath canonicalize + sensitive-pattern reject. Mirror
+    # references/recipes/path-security.md.
+    record_out_dir="$(dirname "${record_out}")"
+    [ -d "${record_out_dir}" ] || mkdir -p "${record_out_dir}"
+    record_out_abs="$(cd "${record_out_dir}" && pwd)/$(basename "${record_out}")"
+    case "${record_out_abs}" in
+      */.ssh/*|*/.aws/*|*/.gnupg/*|*/.netrc*|*/private_key*|*/id_rsa*|*/id_ed25519*)
+        die "${EXIT_USAGE_ERROR}" "browser-flow record: --out path matches sensitive pattern (refusing): ${record_out_abs}"
+        ;;
+    esac
+
+    # Default flow name = basename of --out (sans .flow.yaml).
+    [ -z "${record_name}" ] && record_name="$(basename "${record_out}" .flow.yaml)"
+
+    # Spawn codegen (or mock via env-var override).
+    codegen_bin="${PLAYWRIGHT_CODEGEN_BIN:-}"
+    if [ -z "${codegen_bin}" ]; then
+      codegen_bin="$(command -v playwright || true)"
+      [ -z "${codegen_bin}" ] && die "${EXIT_PREFLIGHT_FAILED}" "playwright not found on PATH (set PLAYWRIGHT_CODEGEN_BIN to override)"
+      codegen_args=(codegen --target javascript "${record_url}")
+    else
+      codegen_args=()
+    fi
+
+    # Capture codegen stdout. Real codegen blocks until user closes the headed
+    # window; mock exits immediately.
+    set +e
+    codegen_js="$("${codegen_bin}" "${codegen_args[@]}" 2>/dev/null)"
+    codegen_rc=$?
+    set -e
+    if [ "${codegen_rc}" -ne 0 ]; then
+      die "${EXIT_TOOL_CRASHED}" "playwright codegen failed (rc=${codegen_rc})"
+    fi
+
+    # Transform JS → YAML. flow_record_transform sets globals
+    # FLOW_RECORD_PASSWORD_REDACTIONS + FLOW_RECORD_STEP_COUNT.
+    yaml_out="$(printf '%s' "${codegen_js}" | flow_record_transform "${record_name}" 2>/tmp/flow-record-stderr-$$.log)"
+    redaction_msgs="$(cat /tmp/flow-record-stderr-$$.log 2>/dev/null || true)"
+    rm -f /tmp/flow-record-stderr-$$.log
+    [ -n "${redaction_msgs}" ] && printf '%s\n' "${redaction_msgs}" >&2
+
+    # Write to --out, mode 0600.
+    tmp="${record_out_abs}.tmp.$$"
+    printf '%s' "${yaml_out}" > "${tmp}"
+    chmod 600 "${tmp}"
+    mv "${tmp}" "${record_out_abs}"
+
+    emit_summary verb=flow tool=playwright-cli why=record status=ok mode=record \
+      flow_name="${record_name}" out_file="${record_out_abs}" \
+      step_count="${FLOW_RECORD_STEP_COUNT}" \
+      password_redactions="${FLOW_RECORD_PASSWORD_REDACTIONS}"
+    exit 0
+    ;;
+  *)    die "${EXIT_USAGE_ERROR}" "browser-flow: unknown sub-mode '${sub_mode}'" ;;
+esac
+
+flow_file="${1:-}"
+[ -n "${flow_file}" ] || die "${EXIT_USAGE_ERROR}" "browser-flow run: missing <flow-file>"
+shift
+
+# Path security: realpath canonicalize. Reject sensitive patterns. Per recipe
+# references/recipes/path-security.md.
+if [ ! -f "${flow_file}" ]; then
+  alt="${BROWSER_SKILL_HOME}/flows/${flow_file}"
+  if [ -f "${alt}" ]; then
+    flow_file="${alt}"
+  else
+    die "${EXIT_USAGE_ERROR}" "flow file not found: ${flow_file}"
+  fi
+fi
+flow_file_abs="$(cd "$(dirname "${flow_file}")" && pwd)/$(basename "${flow_file}")"
+case "${flow_file_abs}" in
+  */.ssh/*|*/.aws/*|*/.gnupg/*|*/.netrc*|*/private_key*|*/id_rsa*|*/id_ed25519*)
+    die "${EXIT_USAGE_ERROR}" "flow file path matches sensitive pattern (refusing): ${flow_file_abs}"
+    ;;
+esac
+
+cli_var_overrides=()
+dry_run=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --var)
+      [ -n "${2:-}" ] || die "${EXIT_USAGE_ERROR}" "--var requires key=val"
+      cli_var_overrides+=("$2")
+      shift 2
+      ;;
+    --dry-run)
+      dry_run=1
+      shift
+      ;;
+    *)
+      die "${EXIT_USAGE_ERROR}" "browser-flow run: unknown flag '$1'"
+      ;;
+  esac
+done
+
+# Reset flow state in this shell.
+declare -gA FLOW_VARS=()
+declare -gA FLOW_REFS=()
+FLOW_NAME=""
+FLOW_SESSION=""
+
+# Parse the flow file → captures _meta line + per-step lines on stdout.
+parsed="$(flow_parse "${flow_file_abs}")"
+
+# Extract _meta line (first one with _kind=="meta").
+meta_line="$(printf '%s\n' "${parsed}" | jq -c -s 'map(select(._kind=="meta")) | .[0]' 2>/dev/null || printf 'null')"
+[ "${meta_line}" = "null" ] && die "${EXIT_GENERIC_ERROR}" "flow_parse: missing _meta line in output"
+FLOW_NAME="$(printf '%s' "${meta_line}" | jq -r '.name')"
+FLOW_SESSION="$(printf '%s' "${meta_line}" | jq -r '.session // ""')"
+
+# Hydrate FLOW_VARS from _meta.vars (file-defined defaults).
+while IFS=$'\t' read -r k v; do
+  [ -z "${k}" ] && continue
+  FLOW_VARS["${k}"]="${v}"
+done <<< "$(printf '%s' "${meta_line}" | jq -r '.vars | to_entries[]? | "\(.key)\t\(.value)"')"
+
+# Apply CLI --var overrides (after parse, so they win over file vars:).
+for ov in "${cli_var_overrides[@]}"; do
+  case "${ov}" in
+    *=*) FLOW_VARS["${ov%%=*}"]="${ov#*=}" ;;
+    *)   die "${EXIT_USAGE_ERROR}" "--var requires key=val (got: ${ov})" ;;
+  esac
+done
+
+# Extract step lines.
+steps_jsonl="$(printf '%s\n' "${parsed}" | jq -c 'select(._kind=="step")')"
+step_count=$(printf '%s\n' "${steps_jsonl}" | grep -c '^.' || printf '0')
+
+if [ "${dry_run}" = "1" ]; then
+  # Dry-run pre-pass: substitute vars (with refs-mode=skip since no snapshot
+  # has actually run); print the planned step list. Per Phase 9 part 1-ii:
+  # ${refs.NAME} stays literal in dry-run output (FLOW_REFS would be empty
+  # anyway).
+  while IFS= read -r step_line; do
+    [ -z "${step_line}" ] && continue
+    flow_apply_vars "${step_line}" skip
+  done <<< "${steps_jsonl}"
+  emit_summary verb=flow tool=none why=dry-run status=ok mode=run \
+    flow_name="${FLOW_NAME}" step_count="${step_count}" dry_run=true
+  exit 0
+fi
+
+# Real run: capture pipeline + per-step dispatch with mid-flow ref resolution.
+capture_start "flow"
+# Append flow_name into meta.json (additive; no schema bump per design F4).
+meta="${CAPTURE_DIR}/meta.json"
+tmp="${meta}.tmp.$$"
+jq --arg n "${FLOW_NAME}" '.flow_name = $n' "${meta}" > "${tmp}"
+chmod 600 "${tmp}"
+mv "${tmp}" "${meta}"
+
+steps_log="${CAPTURE_DIR}/steps.jsonl"
+: > "${steps_log}"
+chmod 600 "${steps_log}"
+
+successful_steps=0
+failed_steps=0
+last_exit=0
+while IFS= read -r step_line; do
+  [ -z "${step_line}" ] && continue
+  # Per-step substitution AT EXECUTION TIME — FLOW_REFS may have just been
+  # populated by the prior snapshot step. flow_apply_vars defaults to
+  # refs-mode=strict (fail loud on missing ref).
+  set +e
+  substituted_step="$(flow_apply_vars "${step_line}")"
+  apply_rc=$?
+  set -e
+  if [ "${apply_rc}" -ne 0 ]; then
+    # flow_apply_vars already emitted the error message via die. Surface
+    # the failure as a step-event + abort the flow.
+    evt="$(jq -nc \
+      --argjson step_index "$(printf '%s' "${step_line}" | jq '.step_index')" \
+      --arg     verb       "$(printf '%s' "${step_line}" | jq -r '.verb')" \
+      --argjson exit_code  "${apply_rc}" \
+      --arg     status     "error" \
+      --arg     error      "var/ref substitution failed" \
+      '{step_index: $step_index, verb: $verb, status: $status, exit_code: $exit_code, error: $error}')"
+    printf '%s\n' "${evt}" >> "${steps_log}"
+    failed_steps=$((failed_steps + 1))
+    last_exit="${apply_rc}"
+    break
+  fi
+
+  evt="$(flow_dispatch "${substituted_step}")"
+  printf '%s\n' "${evt}" >> "${steps_log}"
+  status="$(printf '%s' "${evt}" | jq -r '.status')"
+  if [ "${status}" = "ok" ]; then
+    successful_steps=$((successful_steps + 1))
+  else
+    failed_steps=$((failed_steps + 1))
+    last_exit="$(printf '%s' "${evt}" | jq -r '.exit_code')"
+  fi
+
+  # Phase 9 part 1-ii: harvest step.refs into FLOW_REFS (latest-wins).
+  refs_for_step="$(printf '%s' "${evt}" | jq -c '.refs // null')"
+  if [ "${refs_for_step}" != "null" ]; then
+    # Reset FLOW_REFS wholesale (latest-snapshot-wins).
+    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 <<< "${steps_jsonl}"
+
+# Determine overall flow status.
+if [ "${failed_steps}" = "0" ]; then
+  flow_status="ok"
+elif [ "${successful_steps}" = "0" ]; then
+  flow_status="error"
+else
+  flow_status="partial"
+fi
+
+# Append per-flow counts to meta.json.
+tmp="${meta}.tmp.$$"
+jq \
+  --argjson sc "${step_count}" \
+  --argjson ss "${successful_steps}" \
+  --argjson fs "${failed_steps}" \
+  '. + {step_count: $sc, successful_steps: $ss, failed_steps: $fs}' \
+  "${meta}" > "${tmp}"
+chmod 600 "${tmp}"
+mv "${tmp}" "${meta}"
+
+capture_finish "${flow_status}" true
+
+emit_summary verb=flow tool=none why=run status="${flow_status}" mode=run \
+  flow_name="${FLOW_NAME}" capture_id="${CAPTURE_ID}" \
+  step_count="${step_count}" successful_steps="${successful_steps}" failed_steps="${failed_steps}"
+
+if [ "${flow_status}" = "ok" ]; then
+  exit 0
+fi
+exit "${last_exit}"

package/scripts/browser-history.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+# scripts/browser-history.sh — read-side ops over the captures pipeline +
+# manual-trigger prune. Phase 9 part 1-v (CLOSES Phase 9).
+#
+# Sub-modes:
+#   list [--limit N]                   — enumerate captures (newest first)
+#   show <capture-id>                  — print meta.json + steps.jsonl
+#   diff <id1> <id2>                   — per-step replay_diff via flow_diff_steps
+#   clear [--keep N] [--days D]        — manual prune (composes Phase 7's
+#         [--not-baseline]               capture_prune; respects is_baseline
+#                                        skip-rule by default)
+
+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
+
+sub_mode="${1:-}"
+[ -n "${sub_mode}" ] || die "${EXIT_USAGE_ERROR}" "browser-history: missing sub-mode (list / show / diff / clear)"
+shift
+
+case "${sub_mode}" in
+  list)
+    limit=""
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        --limit) limit="$2"; shift 2 ;;
+        --since) shift 2 ;;  # accepted; deferred (out-of-scope filter)
+        *)       die "${EXIT_USAGE_ERROR}" "history list: unknown flag '$1'" ;;
+      esac
+    done
+    total=0
+    if [ -d "${CAPTURES_DIR}" ]; then
+      shopt -s nullglob
+      # Sort by capture_id (which is monotonic per Phase 7); newest first.
+      ids=()
+      for d in "${CAPTURES_DIR}"/[0-9]*/; do
+        ids+=("$(basename "${d}")")
+      done
+      shopt -u nullglob
+      # Reverse-sort to put newest first.
+      mapfile -t sorted < <(printf '%s\n' "${ids[@]}" | sort -r)
+      for id in "${sorted[@]}"; do
+        meta="${CAPTURES_DIR}/${id}/meta.json"
+        [ -f "${meta}" ] || continue
+        if [ -n "${limit}" ] && [ "${total}" -ge "${limit}" ]; then
+          break
+        fi
+        # Emit per-capture row event.
+        jq -c --arg event "history_row" \
+          '. + {event: $event}' "${meta}"
+        total=$((total + 1))
+      done
+    fi
+    emit_summary verb=history tool=none why=list status=ok mode=list total="${total}"
+    exit 0
+    ;;
+
+  show)
+    show_id="${1:-}"
+    [ -n "${show_id}" ] || die "${EXIT_USAGE_ERROR}" "history show: missing <capture-id>"
+    meta="${CAPTURES_DIR}/${show_id}/meta.json"
+    [ -f "${meta}" ] || die "${EXIT_USAGE_ERROR}" "history show: no such capture '${show_id}'"
+    # Compact meta.json onto a single line so callers can parse the first
+    # line as a complete JSON object (capture_start writes pretty-printed
+    # multi-line; jq -c re-flattens).
+    jq -c . "${meta}"
+    steps_log="${CAPTURES_DIR}/${show_id}/steps.jsonl"
+    [ -f "${steps_log}" ] && cat "${steps_log}"
+    emit_summary verb=history tool=none why=show status=ok mode=show capture_id="${show_id}"
+    exit 0
+    ;;
+
+  diff)
+    id1="${1:-}"
+    id2="${2:-}"
+    [ -n "${id1}" ] && [ -n "${id2}" ] || die "${EXIT_USAGE_ERROR}" "history diff: requires <id1> <id2>"
+    log1="${CAPTURES_DIR}/${id1}/steps.jsonl"
+    log2="${CAPTURES_DIR}/${id2}/steps.jsonl"
+    [ -f "${log1}" ] || die "${EXIT_USAGE_ERROR}" "history diff: no steps.jsonl at captures/${id1}/"
+    [ -f "${log2}" ] || die "${EXIT_USAGE_ERROR}" "history diff: no steps.jsonl at captures/${id2}/"
+    # Iterate paired step events; emit replay_diff per pair.
+    matched=0
+    diverged=0
+    paste -d $'\t' "${log1}" "${log2}" | while IFS=$'\t' read -r old new; do
+      [ -z "${old}" ] || [ -z "${new}" ] && continue
+      flow_diff_steps "${old}" "${new}" || true
+    done
+    # Aggregate counts via separate read pass.
+    total_steps="$(wc -l < "${log1}" | tr -d ' ')"
+    emit_summary verb=history tool=none why=diff status=ok mode=diff \
+      capture_id_old="${id1}" capture_id_new="${id2}" total_steps="${total_steps}"
+    exit 0
+    ;;
+
+  clear)
+    keep=""
+    days=""
+    not_baseline=0
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        --keep)         keep="$2"; shift 2 ;;
+        --days)         days="$2"; shift 2 ;;
+        --not-baseline) not_baseline=1; shift ;;
+        *)              die "${EXIT_USAGE_ERROR}" "history clear: unknown flag '$1'" ;;
+      esac
+    done
+
+    pruned=0
+    if [ -d "${CAPTURES_DIR}" ]; then
+      shopt -s nullglob
+      ids=()
+      for d in "${CAPTURES_DIR}"/[0-9]*/; do
+        ids+=("$(basename "${d}")")
+      done
+      shopt -u nullglob
+      # Newest-first sort; keep first N if --keep.
+      mapfile -t sorted < <(printf '%s\n' "${ids[@]}" | sort -r)
+      idx=0
+      now_epoch="$(date -u +%s)"
+      for id in "${sorted[@]}"; do
+        meta="${CAPTURES_DIR}/${id}/meta.json"
+        [ -f "${meta}" ] || continue
+        is_baseline="$(jq -r '.is_baseline // false' "${meta}" 2>/dev/null || printf 'false')"
+        # is_baseline:true is ALWAYS skipped (per Phase 7 prune contract +
+        # locked decision H3).
+        if [ "${is_baseline}" = "true" ]; then
+          idx=$((idx + 1))
+          continue
+        fi
+        # --keep N: keep the newest N (skip pruning the first N).
+        if [ -n "${keep}" ] && [ "${idx}" -lt "${keep}" ]; then
+          idx=$((idx + 1))
+          continue
+        fi
+        # --days D: keep captures younger than D days.
+        if [ -n "${days}" ]; then
+          finished_at="$(jq -r '.finished_at // .started_at // ""' "${meta}" 2>/dev/null || printf '')"
+          if [ -n "${finished_at}" ]; then
+            cap_epoch="$(date -d "${finished_at}" +%s 2>/dev/null || date -j -f '%Y-%m-%dT%H:%M:%SZ' "${finished_at}" +%s 2>/dev/null || printf '0')"
+            age_days=$(( (now_epoch - cap_epoch) / 86400 ))
+            if [ "${age_days}" -lt "${days}" ]; then
+              idx=$((idx + 1))
+              continue
+            fi
+          fi
+        fi
+        # If --not-baseline alone (no --keep / --days), prune everything
+        # non-baseline. If --not-baseline + --keep / --days, the above
+        # checks already excluded baselines + applied limits.
+        if [ -z "${keep}" ] && [ -z "${days}" ] && [ "${not_baseline}" = "0" ]; then
+          # No flags at all → no-op (use config defaults via auto-prune).
+          idx=$((idx + 1))
+          continue
+        fi
+        rm -rf "${CAPTURES_DIR}/${id}"
+        pruned=$((pruned + 1))
+        idx=$((idx + 1))
+      done
+    fi
+    emit_summary verb=history tool=none why=clear status=ok mode=clear pruned="${pruned}"
+    exit 0
+    ;;
+
+  *)
+    die "${EXIT_USAGE_ERROR}" "browser-history: unknown sub-mode '${sub_mode}' (use list / show / diff / clear)"
+    ;;
+esac