browser-automation-skill 0.71.0

package/scripts/browser-hover.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# scripts/browser-hover.sh — pointer hover an element by --ref eN or --selector CSS.
+# Usage: bash scripts/browser-hover.sh [--site NAME] [--tool NAME] [--dry-run]
+#                                       [--raw] (--ref eN | --selector CSS)
+#
+# Routes to chrome-devtools-mcp by default (Phase 6 part 3). Stateful —
+# requires running daemon (refMap precondition; mirrors click/select).
+# --selector path enables Phase 11 cache dispatch (cache stores selectors,
+# not snapshot-relative refs). Mirrors browser-click.sh + browser-fill.sh
+# 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=""
+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))
+      ;;
+    *)
+      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}" "hover requires --ref eN or --selector CSS"
+fi
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  ok "dry-run: would hover ${ref:-${selector}}"
+  emit_summary verb=hover tool=none why=dry-run status=ok ref="${ref}" selector="${selector}" dry_run=true
+  exit 0
+fi
+
+picked="$(pick_tool hover "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+set +e
+adapter_out="$(invoke_with_retry hover "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  emit_summary verb=hover tool="${tool_name}" why="${why}" status=ok ref="${ref}" selector="${selector}"
+  exit 0
+fi
+emit_summary verb=hover tool="${tool_name}" why="${why}" status=error ref="${ref}" selector="${selector}"
+exit "${adapter_rc}"

package/scripts/browser-inspect.sh

@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+# scripts/browser-inspect.sh — inspect a page (console, network, screenshot,
+# or selector text). Usage:
+#   bash scripts/browser-inspect.sh [--site NAME] [--tool NAME] [--dry-run]
+#                                   [--raw]
+#                                   (--capture-console | --capture-network
+#                                    | --screenshot | --selector CSS)
+#                                   [--capture]
+#
+# Routes to chrome-devtools-mcp by default (post-1d router promotion — only
+# adapter with dedicated console + network MCP tools per parent spec
+# Appendix B). At least one of --capture-* / --screenshot / --selector is
+# required so the adapter has something to do.
+#
+# Phase 7 part 1-iii: --capture writes adapter output to ${CAPTURES_DIR}/NNN/
+# as console.json + network.har, sanitized via lib/sanitize.sh. Stdout output
+# is ALSO sanitized (defense in depth) — single transformation, both sinks.
+
+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/capture.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/capture.sh"
+# shellcheck source=lib/sanitize.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/sanitize.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+parse_verb_globals "$@"
+
+resolve_session_storage_state
+
+selector="" capture_console=0 capture_network=0 screenshot=0 do_capture=0 unsanitized=0
+verb_argv=()
+i=0
+while [ "${i}" -lt "${#REMAINING_ARGV[@]}" ]; do
+  case "${REMAINING_ARGV[i]}" in
+    --selector)
+      selector="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${selector}" ] || die "${EXIT_USAGE_ERROR}" "--selector requires a value"
+      verb_argv+=(--selector "${selector}")
+      i=$((i + 2))
+      ;;
+    --capture-console)
+      capture_console=1
+      verb_argv+=(--capture-console)
+      i=$((i + 1))
+      ;;
+    --capture-network)
+      capture_network=1
+      verb_argv+=(--capture-network)
+      i=$((i + 1))
+      ;;
+    --screenshot)
+      screenshot=1
+      verb_argv+=(--screenshot)
+      i=$((i + 1))
+      ;;
+    --capture)
+      do_capture=1
+      i=$((i + 1))
+      ;;
+    --unsanitized)
+      unsanitized=1
+      i=$((i + 1))
+      ;;
+    *)
+      verb_argv+=("${REMAINING_ARGV[i]}")
+      i=$((i + 1))
+      ;;
+  esac
+done
+
+# Phase 7 part 1-iv: --unsanitized requires typed-phrase confirmation.
+# Strict equality (no whitespace strip) — friction-by-design. Mirrors
+# scripts/browser-creds-show.sh::--reveal precedent. Phrase verbatim per
+# parent spec §8.3. Scripted use: pipe phrase via stdin.
+if [ "${unsanitized}" = "1" ]; then
+  printf 'Type the unsanitized confirmation phrase to confirm: ' >&2
+  IFS= read -r unsanitized_answer || true
+  if [ "${unsanitized_answer}" != "I want raw network/console data including auth tokens" ]; then
+    die "${EXIT_USAGE_ERROR}" "unsanitized aborted (confirmation mismatch)"
+  fi
+fi
+
+if [ -z "${selector}" ] && [ "${capture_console}" = 0 ] \
+   && [ "${capture_network}" = 0 ] && [ "${screenshot}" = 0 ]; then
+  die "${EXIT_USAGE_ERROR}" \
+      "inspect requires one of --capture-console / --capture-network / --screenshot / --selector CSS"
+fi
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  ok "dry-run: would inspect (${selector:-<no-selector>})"
+  if [ "${do_capture}" = "1" ]; then
+    emit_summary verb=inspect tool=none why=dry-run status=ok selector="${selector}" dry_run=true capture=true
+  else
+    emit_summary verb=inspect tool=none why=dry-run status=ok selector="${selector}" dry_run=true
+  fi
+  exit 0
+fi
+
+picked="$(pick_tool inspect "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+if [ "${do_capture}" = "1" ]; then
+  capture_start inspect
+fi
+
+set +e
+adapter_out="$(invoke_with_retry inspect "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+if [ "${do_capture}" = "1" ] && [ -n "${adapter_out}" ]; then
+  # Single (maybe-)sanitize, both sinks: stdout + per-aspect files. Either
+  # path produces the same emit-twice contract; only the transformation
+  # differs. --unsanitized skips sanitize_inspect_reply.
+  if [ "${unsanitized}" = "1" ]; then
+    out_for_emit="${adapter_out}"
+    sanitized_flag=false
+  else
+    out_for_emit="$(printf '%s' "${adapter_out}" | sanitize_inspect_reply)"
+    sanitized_flag=true
+  fi
+
+  # console.json — extract .console_messages array.
+  if [ "${capture_console}" = "1" ]; then
+    if printf '%s' "${out_for_emit}" | jq -e 'has("console_messages")' >/dev/null 2>&1; then
+      printf '%s' "${out_for_emit}" | jq '.console_messages // []' > "${CAPTURE_DIR}/console.json"
+      chmod 600 "${CAPTURE_DIR}/console.json"
+    fi
+  fi
+
+  # network.har — wrap .network_requests in HAR envelope and persist.
+  if [ "${capture_network}" = "1" ]; then
+    if printf '%s' "${out_for_emit}" | jq -e 'has("network_requests")' >/dev/null 2>&1; then
+      printf '%s' "${out_for_emit}" \
+        | jq '{log: {version: "1.2", entries: (.network_requests // [])}}' \
+        > "${CAPTURE_DIR}/network.har"
+      chmod 600 "${CAPTURE_DIR}/network.har"
+    fi
+  fi
+
+  printf '%s\n' "${out_for_emit}"
+
+  if [ "${adapter_rc}" -eq 0 ]; then
+    capture_finish ok "${sanitized_flag}"
+  else
+    capture_finish error "${sanitized_flag}"
+  fi
+else
+  [ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+fi
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  if [ "${do_capture}" = "1" ]; then
+    emit_summary verb=inspect tool="${tool_name}" why="${why}" status=ok selector="${selector}" capture_id="${CAPTURE_ID}"
+  else
+    emit_summary verb=inspect tool="${tool_name}" why="${why}" status=ok selector="${selector}"
+  fi
+  exit 0
+fi
+if [ "${do_capture}" = "1" ]; then
+  emit_summary verb=inspect tool="${tool_name}" why="${why}" status=error selector="${selector}" capture_id="${CAPTURE_ID}"
+else
+  emit_summary verb=inspect tool="${tool_name}" why="${why}" status=error selector="${selector}"
+fi
+exit "${adapter_rc}"

package/scripts/browser-list-sessions.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# list-sessions — list captured Playwright sessions (storageState files).
+#
+# Sessions are tied to sites via meta.site; pass --site NAME to filter.
+# A site may have many sessions — this verb is the discoverability surface
+# for the 1-many credential model (e.g. prod--admin, prod--readonly, prod--ci).
+#
+# Storage state itself is sensitive and stays at mode 0600 — this verb only
+# emits metadata (origin, captured_at, expires_in_hours), never cookie/token
+# values.
+
+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
+
+site_filter=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --site) site_filter="$2"; shift 2 ;;
+    -h|--help)
+      cat <<'USAGE'
+Usage: list-sessions [--site NAME]
+
+  --site NAME    show only sessions bound to this site
+USAGE
+      exit 0
+      ;;
+    *) die "${EXIT_USAGE_ERROR}" "unknown flag: $1" ;;
+  esac
+done
+
+started_at_ms="$(now_ms)"
+
+rows='[]'
+count=0
+if [ -d "${SESSIONS_DIR}" ]; then
+  shopt -s nullglob
+  for f in "${SESSIONS_DIR}"/*.json; do
+    base="$(basename "${f}" .json)"
+    case "${base}" in
+      *.meta) continue ;;
+      *interactive-tmp*) continue ;;
+    esac
+    [ -f "${SESSIONS_DIR}/${base}.meta.json" ] || continue
+    meta="$(session_meta_load "${base}" 2>/dev/null)" || continue
+    sess_site="$(printf '%s' "${meta}" | jq -r '.site // ""')"
+    if [ -n "${site_filter}" ] && [ "${sess_site}" != "${site_filter}" ]; then
+      continue
+    fi
+    rows="$(jq --arg n "${base}" --argjson m "${meta}" '
+      . + [{
+        session:          $n,
+        site:             ($m.site // null),
+        origin:           ($m.origin // null),
+        captured_at:      ($m.captured_at // null),
+        expires_in_hours: ($m.expires_in_hours // null)
+      }]' <<< "${rows}")"
+    count=$((count + 1))
+  done
+  shopt -u nullglob
+fi
+
+duration_ms=$(( $(now_ms) - started_at_ms ))
+jq -cn --argjson r "${rows}" --argjson c "${count}" --argjson d "${duration_ms}" \
+  --arg sf "${site_filter}" \
+  '{verb: "list-sessions", tool: "none", why: (if $sf == "" then "list-all" else "list-by-site" end),
+    status: (if $c == 0 then "empty" else "ok" end),
+    site_filter: ($sf | if . == "" then null else . end),
+    count: $c, sessions: $r, duration_ms: $d}'

package/scripts/browser-list-sites.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# list-sites — list registered site profiles (no creds; sites are non-secret).
+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
+
+started_at_ms="$(now_ms)"
+
+names="$(site_list_names)"
+rows='[]'
+count=0
+if [ -n "${names}" ]; then
+  while IFS= read -r n; do
+    [ -z "${n}" ] && continue
+    profile="$(site_load "${n}")"
+    meta="$(site_meta_load "${n}")"
+    rows="$(jq --argjson p "${profile}" --argjson m "${meta}" '
+      . + [{
+        name:           $p.name,
+        url:            $p.url,
+        label:          ($p.label // ""),
+        default_session:$p.default_session,
+        default_tool:   $p.default_tool,
+        last_used_at:   ($m.last_used_at // null)
+      }]' <<< "${rows}")"
+    count=$((count + 1))
+  done <<< "${names}"
+fi
+
+duration_ms=$(( $(now_ms) - started_at_ms ))
+jq -cn --argjson r "${rows}" --argjson c "${count}" --argjson d "${duration_ms}" \
+  '{verb: "list-sites", tool: "none", why: "list", status: "ok",
+    count: $c, sites: $r, duration_ms: $d}'

package/scripts/browser-login.sh

@@ -0,0 +1,279 @@
+#!/usr/bin/env bash
+# login — capture a Playwright storageState into sessions/<name>.json.
+#
+# Three modes:
+#   --interactive          headed Chromium; user logs in, presses Enter
+#   --storage-state-file   import a hand-edited storageState file
+#   --auto                 phase-5 part 3 — programmatic headless login
+#                          using the stored credential (creds-add). Reads
+#                          username + password (NUL-separated) from
+#                          credential, sends to driver via stdin per AP-7.
+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"
+# shellcheck source=lib/session.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/session.sh"
+# shellcheck source=lib/credential.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/credential.sh"
+init_paths
+
+site=""; as=""; ss_file=""; dry_run=0; auto=0; headed=1; interactive=0
+
+usage() {
+  cat <<'USAGE'
+Usage: login --site NAME --as SESSION (--storage-state-file PATH | --interactive) [--dry-run]
+
+Capture a Playwright storageState into sessions/<SESSION>.json. Two modes:
+
+  --interactive               Launch a headed Chromium via the playwright-lib
+                              driver. User logs in interactively; press Enter
+                              in this terminal to capture and save the session.
+  --storage-state-file PATH   Skip the browser launch; consume an already-
+                              captured storageState file (legacy hand-edit
+                              path, useful for CI / non-interactive imports).
+  --auto                      Programmatic headless login using the stored
+                              credential (set via creds-add). Requires
+                              --site + --as; the credential's auto_relogin
+                              flag must be true. Username + password reach
+                              the driver via stdin only (AP-7).
+
+  --site NAME                 site profile to bind the session to (required)
+  --as SESSION                session name (required; falls back to site.default_session)
+  --dry-run                   validate inputs; write nothing
+  --headed                    accepted (interactive mode is always headed)
+  -h, --help
+
+A site may have many sessions: pass different --as names to capture per-role
+or per-account credentials (e.g. prod--admin, prod--readonly, prod--ci).
+USAGE
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --site)                 site="$2"; shift 2 ;;
+    --as)                   as="$2"; shift 2 ;;
+    --storage-state-file)   ss_file="$2"; shift 2 ;;
+    --interactive)          interactive=1; shift ;;
+    --dry-run)              dry_run=1; shift ;;
+    --headed)               headed=1; shift ;;
+    --auto)                 auto=1; shift ;;
+    -h|--help)              usage; exit 0 ;;
+    *)                      die "${EXIT_USAGE_ERROR}" "unknown flag: $1" ;;
+  esac
+done
+
+if [ "${auto}" -eq 1 ] && [ "${interactive}" -eq 1 ]; then
+  die "${EXIT_USAGE_ERROR}" "--auto and --interactive are mutually exclusive"
+fi
+if [ "${auto}" -eq 1 ] && [ -n "${ss_file}" ]; then
+  die "${EXIT_USAGE_ERROR}" "--auto and --storage-state-file are mutually exclusive"
+fi
+if [ "${interactive}" -eq 1 ] && [ -n "${ss_file}" ]; then
+  die "${EXIT_USAGE_ERROR}" "--interactive and --storage-state-file are mutually exclusive"
+fi
+[ -n "${site}" ]    || { usage; die "${EXIT_USAGE_ERROR}" "--site is required"; }
+# --as defaults to site.default_session if the site sets one.
+if [ -z "${as}" ]; then
+  default_session_from_site="$(site_load "${site}" | jq -r '.default_session // ""')"
+  if [ -n "${default_session_from_site}" ]; then
+    as="${default_session_from_site}"
+  else
+    die "${EXIT_USAGE_ERROR}" "--as is required (site ${site} has no default_session set)"
+  fi
+fi
+assert_safe_name "${as}" "session-name"
+if [ "${interactive}" -eq 0 ] && [ "${auto}" -eq 0 ] && [ -z "${ss_file}" ]; then
+  usage
+  die "${EXIT_USAGE_ERROR}" "--interactive, --auto, or --storage-state-file is required"
+fi
+if [ "${interactive}" -eq 0 ] && [ "${auto}" -eq 0 ]; then
+  [ -f "${ss_file}" ] || die "${EXIT_USAGE_ERROR}" "storage-state-file not found: ${ss_file}"
+fi
+
+started_at_ms="$(now_ms)"
+
+# Site must exist; load its URL → derive origin for binding.
+profile_json="$(site_load "${site}")"   # exits 23 if missing
+site_url="$(printf '%s' "${profile_json}" | jq -r .url)"
+site_origin="$(url_origin "${site_url}")"
+
+# --auto: programmatic headless login using stored credential. Validates the
+# credential exists + is bound to this site + has auto_relogin=true. Loads
+# the secret via credential_get_secret (dispatches to whichever backend the
+# cred uses — plaintext / keychain / libsecret). Sends username\0password
+# to the driver via stdin (AP-7 — secret never on argv).
+if [ "${auto}" -eq 1 ]; then
+  if ! credential_exists "${as}"; then
+    die "${EXIT_SITE_NOT_FOUND}" "credential not found: ${as} (run: creds-add --site ${site} --as ${as} --password-stdin)"
+  fi
+
+  cred_meta="$(credential_load "${as}")"
+  cred_site="$(printf '%s' "${cred_meta}" | jq -r .site)"
+  cred_account="$(printf '%s' "${cred_meta}" | jq -r .account)"
+  cred_auto="$(printf '%s' "${cred_meta}" | jq -r .auto_relogin)"
+  cred_auth_flow="$(printf '%s' "${cred_meta}" | jq -r '.auth_flow // "single-step-username-password"')"
+  cred_totp_enabled="$(printf '%s' "${cred_meta}" | jq -r '.totp_enabled // false')"
+
+  if [ "${cred_site}" != "${site}" ]; then
+    die "${EXIT_USAGE_ERROR}" "credential ${as} is bound to site '${cred_site}', not '${site}'"
+  fi
+  if [ "${cred_auto}" != "true" ]; then
+    die "${EXIT_USAGE_ERROR}" "credential ${as} has auto_relogin=false; cannot --auto (re-add the credential or use --interactive)"
+  fi
+  if [ -z "${cred_account}" ] || [ "${cred_account}" = "null" ]; then
+    die "${EXIT_USAGE_ERROR}" "credential ${as} has empty account; cannot --auto"
+  fi
+  # Phase-5 part 3-iii: only single-step-username-password is supported by
+  # the playwright-driver auto-relogin path. Other auth_flow values were
+  # persisted at creds-add time for documentation; relogin requires user
+  # interaction.
+  if [ "${cred_auth_flow}" != "single-step-username-password" ]; then
+    die "${EXIT_USAGE_ERROR}" "credential ${as} has auth_flow=${cred_auth_flow}; --auto only supports single-step-username-password (use --interactive)"
+  fi
+
+  if [ "${dry_run}" -eq 1 ]; then
+    ok "dry-run: would auto-relogin ${as} (site=${site}, account=${cred_account})"
+    duration_ms=$(( $(now_ms) - started_at_ms ))
+    summary_json verb=login tool=playwright-lib why=auto-relogin-dry-run status=ok would_run=true \
+                 site="${site}" session="${as}" account="${cred_account}" \
+                 duration_ms="${duration_ms}"
+    exit "${EXIT_OK}"
+  fi
+
+  mkdir -p "${SESSIONS_DIR}"
+  chmod 700 "${SESSIONS_DIR}"
+  ss_file="${SESSIONS_DIR}/${as}.auto-tmp.$$"
+  ok "auto-relogin: launching headless Chromium at ${site_url} as ${cred_account}"
+
+  # Pipe `account\0password` to driver stdin. AP-7: secret never on argv.
+  # Phase-5 part 4-iii: when cred is totp_enabled, append `\0totp_secret` so
+  # the driver can replay TOTP automatically after detect2FA fires.
+  set +e
+  if [ "${cred_totp_enabled}" = "true" ]; then
+    {
+      printf '%s\0' "${cred_account}"
+      credential_get_secret "${as}"
+      printf '\0'
+      credential_get_totp_secret "${as}"
+    } | node "${SCRIPT_DIR}/lib/node/playwright-driver.mjs" auto-relogin \
+          --url "${site_url}" --output-path "${ss_file}"
+  else
+    { printf '%s\0' "${cred_account}"; credential_get_secret "${as}"; } | \
+      node "${SCRIPT_DIR}/lib/node/playwright-driver.mjs" auto-relogin \
+        --url "${site_url}" --output-path "${ss_file}"
+  fi
+  driver_rc=${PIPESTATUS[1]}
+  set -e
+  if [ "${driver_rc}" = "${EXIT_AUTH_INTERACTIVE_REQUIRED}" ]; then
+    # Phase-5 part 3-iv: driver detected a 2FA challenge that it couldn't
+    # auto-replay (no totp_enabled cred OR replay failed). Tell the user to
+    # either store a TOTP secret (creds-add --enable-totp) or fall back to
+    # --interactive.
+    rm -f "${ss_file}"
+    die "${EXIT_AUTH_INTERACTIVE_REQUIRED}" \
+        "site requires 2FA / interactive challenge — re-run with --interactive (or store a TOTP secret with creds-add --enable-totp --totp-secret-stdin)"
+  fi
+  if [ "${driver_rc}" -ne 0 ]; then
+    rm -f "${ss_file}"
+    die "${EXIT_TOOL_CRASHED}" "auto-relogin failed (driver returned ${driver_rc})"
+  fi
+fi
+
+# Interactive mode: launch the driver, which opens a headed browser, waits
+# for the user to press Enter, and writes the captured storageState to a
+# temp file. Then we validate + save through the same pipeline as the
+# storage-state-file path.
+if [ "${interactive}" -eq 1 ]; then
+  if [ "${dry_run}" -eq 1 ]; then
+    ok "dry-run: would launch headed browser to ${site_url}, capture session ${as}"
+    duration_ms=$(( $(now_ms) - started_at_ms ))
+    summary_json verb=login tool=playwright-lib why=interactive-dry-run status=ok would_run=true \
+                 site="${site}" session="${as}" duration_ms="${duration_ms}"
+    exit "${EXIT_OK}"
+  fi
+  # Tempfile under SESSIONS_DIR (mode 0600 inherited from 0700 dir + driver chmod).
+  mkdir -p "${SESSIONS_DIR}"
+  chmod 700 "${SESSIONS_DIR}"
+  ss_file="${SESSIONS_DIR}/${as}.interactive-tmp.$$"
+  ok "launching headed Chromium at ${site_url}; press Enter when done logging in"
+  if ! node "${SCRIPT_DIR}/lib/node/playwright-driver.mjs" login \
+        --url "${site_url}" --output-path "${ss_file}"; then
+    rm -f "${ss_file}"
+    die "${EXIT_TOOL_CRASHED}" "interactive login failed (driver returned non-zero)"
+  fi
+fi
+
+# Read & validate the storageState file.
+if ! ss_json="$(jq -c . "${ss_file}" 2>/dev/null)"; then
+  if [ "${interactive}" -eq 1 ] || [ "${auto}" -eq 1 ]; then
+    rm -f "${ss_file}"
+  fi
+  die "${EXIT_USAGE_ERROR}" "storage-state-file is not valid JSON: ${ss_file}"
+fi
+
+# Origin-binding (spec §5.5): every storageState.origins[] must match site_origin.
+# Empty origins[] is allowed (storageState may carry only cookies).
+mismatched="$(printf '%s' "${ss_json}" | jq -r --arg target "${site_origin}" '
+  [.origins[]? | select(.origin != $target) | .origin] | join(",")')"
+if [ -n "${mismatched}" ]; then
+  die "${EXIT_SESSION_EXPIRED}" \
+    "origin mismatch: storage-state-file origins=[${mismatched}], site origin=${site_origin}"
+fi
+
+ok "site=${site} session=${as} origin=${site_origin}"
+
+if [ "${dry_run}" -eq 1 ]; then
+  ok "dry-run: would write ${SESSIONS_DIR}/${as}.json"
+  duration_ms=$(( $(now_ms) - started_at_ms ))
+  summary_json verb=login tool=playwright-lib why=dry-run status=ok would_run=true \
+               site="${site}" session="${as}" duration_ms="${duration_ms}"
+  exit "${EXIT_OK}"
+fi
+
+# Build meta sidecar.
+captured_at="$(now_iso)"
+if [ "${auto}" -eq 1 ]; then
+  ua_tag='browser-skill playwright-lib auto-relogin'
+elif [ "${interactive}" -eq 1 ]; then
+  ua_tag='browser-skill playwright-lib interactive capture'
+else
+  ua_tag='browser-skill storageState-file import'
+fi
+meta_json="$(jq -nc \
+  --arg n "${as}" \
+  --arg s "${site}" \
+  --arg o "${site_origin}" \
+  --arg c "${captured_at}" \
+  --arg ua "${ua_tag}" \
+  '{
+    name: $n, site: $s, origin: $o, captured_at: $c,
+    source_user_agent: $ua, expires_in_hours: 168, schema_version: 1
+  }')"
+
+session_save "${as}" "${ss_json}" "${meta_json}"
+if [ "${interactive}" -eq 1 ] || [ "${auto}" -eq 1 ]; then
+  rm -f "${ss_file}"
+fi
+ok "session captured: ${as}"
+
+duration_ms=$(( $(now_ms) - started_at_ms ))
+if [ "${auto}" -eq 1 ]; then
+  why_tag="auto-relogin"
+elif [ "${interactive}" -eq 1 ]; then
+  why_tag="interactive-headed-capture"
+else
+  why_tag="storageState-file-import"
+fi
+summary_json verb=login tool=playwright-lib why="${why_tag}" status=ok \
+             site="${site}" session="${as}" origin="${site_origin}" \
+             expires_in_hours=168 duration_ms="${duration_ms}"