browserctl 0.11.0 → 0.12.0

data/lib/browserctl/logger.rb

@@ -2,6 +2,8 @@
 
 require "logger"
 require "fileutils"
+require "json"
+require "time"
 
 module Browserctl
   LEVEL_MAP = {
@@ -11,6 +13,16 @@ module Browserctl
     "error" => ::Logger::ERROR
   }.freeze
 
+  # JSONL rotation policy. Stdlib `Logger` rotates by size when given an
+  # integer `shift_age` and `shift_size`.
+  LOG_SHIFT_AGE  = 10                # keep last 10 rotated files
+  LOG_SHIFT_SIZE = 10 * 1024 * 1024  # rotate at 10MB
+
+  # Resolved at call time so tests can override BROWSERCTL_DIR via stub_const.
+  def self.log_dir
+    File.join(BROWSERCTL_DIR, "logs")
+  end
+
   class MultiLogger
     def initialize(*loggers)
       @loggers = loggers
@@ -30,6 +42,37 @@ module Browserctl
     end
   end
 
+  # Formats every log line as a single JSON object: {ts, level, component, msg, ...}.
+  # If the message is a Hash, its keys are merged so callers can attach
+  # structured context, e.g. `logger.info(event: "x", session: id)`.
+  class JsonlFormatter
+    def initialize(component:)
+      @component = component
+    end
+
+    def call(severity, time, _progname, msg)
+      record = {
+        ts: time.utc.iso8601(3),
+        level: severity,
+        component: @component
+      }
+
+      case msg
+      when Hash
+        explicit = msg[:msg] || msg["msg"]
+        record[:msg] = explicit if explicit
+        record.merge!(msg.reject { |k, _| k.to_s == "msg" })
+      when Exception
+        record[:msg] = "#{msg.class}: #{msg.message}"
+        record[:backtrace] = Array(msg.backtrace).first(10)
+      else
+        record[:msg] = msg.to_s
+      end
+
+      "#{JSON.generate(record)}\n"
+    end
+  end
+
   def self.logger
     @logger ||= build_logger("info")
   end
@@ -38,19 +81,69 @@ module Browserctl
     @logger = instance
   end
 
-  def self.build_logger(level_name, log_path: nil)
+  # Build a logger that writes:
+  #   - human-readable lines to stderr (unchanged behaviour)
+  #   - human-readable lines to log_path: when given (the daemon tail file)
+  #   - structured JSONL lines to ~/.browserctl/logs/<component>.log (rotating
+  #     10 files x 10MB) when jsonl: is true
+  #
+  # JSONL output is purely additive — existing stderr/stdout behaviour is
+  # preserved so scripted callers see no change.
+  def self.build_logger(level_name, log_path: nil, component: "daemon", jsonl: true)
     level = LEVEL_MAP.fetch(level_name.to_s.downcase, ::Logger::INFO)
-    formatter = proc { |sev, t, prog, msg| "#{t.strftime('%Y-%m-%dT%H:%M:%S')} #{sev[0]} [#{prog}] #{msg}\n" }
+    text_formatter = proc do |sev, t, prog, msg|
+      "#{t.strftime('%Y-%m-%dT%H:%M:%S')} #{sev[0]} [#{prog}] #{format_text_msg(msg)}\n"
+    end
+
+    loggers = [make_logger($stderr, level, text_formatter)]
 
-    stderr_log = make_logger($stderr, level, formatter)
-    return stderr_log unless log_path
+    if log_path
+      FileUtils.mkdir_p(File.dirname(log_path), mode: 0o700)
+      FileUtils.touch(log_path)
+      File.chmod(0o600, log_path)
+      loggers << make_logger(log_path, level, text_formatter)
+    end
 
-    FileUtils.mkdir_p(File.dirname(log_path), mode: 0o700)
-    FileUtils.touch(log_path)
-    File.chmod(0o600, log_path)
-    file_log = make_logger(log_path, level, formatter)
-    MultiLogger.new(stderr_log, file_log)
+    if jsonl
+      jsonl_logger = build_jsonl_logger(level, component)
+      loggers << jsonl_logger if jsonl_logger
+    end
+
+    loggers.length == 1 ? loggers.first : MultiLogger.new(*loggers)
+  end
+
+  # Returns a stdlib Logger writing JSON-Lines records to
+  # ~/.browserctl/logs/<component>.log with size-based rotation. Returns nil
+  # (and stays silent) if the directory cannot be created so logging never
+  # crashes the daemon.
+  # LogDevice that suppresses stdlib's "# Logfile created on ..." header so
+  # the resulting file is pure JSON Lines.
+  class HeaderlessLogDevice < ::Logger::LogDevice
+    def add_log_header(_file); end
+  end
+
+  def self.build_jsonl_logger(level, component)
+    dir = log_dir
+    FileUtils.mkdir_p(dir, mode: 0o700)
+    path = File.join(dir, "#{component}.log")
+    device = HeaderlessLogDevice.new(path, shift_age: LOG_SHIFT_AGE, shift_size: LOG_SHIFT_SIZE)
+    log = ::Logger.new(device)
+    log.level     = level
+    log.progname  = component
+    log.formatter = JsonlFormatter.new(component: component)
+    log
+  rescue StandardError
+    nil
+  end
+
+  def self.format_text_msg(msg)
+    case msg
+    when Hash      then (msg[:msg] || msg["msg"] || msg.inspect).to_s
+    when Exception then "#{msg.class}: #{msg.message}"
+    else                msg.to_s
+    end
   end
+  private_class_method :format_text_msg
 
   def self.make_logger(device, level, formatter)
     log = ::Logger.new(device)

data/lib/browserctl/migrations.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "errors"
+require_relative "error/codes"
+
+module Browserctl
+  # Migration registry for browserctl persisted formats. Operators run
+  # `browserctl migrate <path>` to upgrade an artifact written by an older
+  # browserctl to the current build's format version.
+  #
+  # Distinct from `verify_format_version!` (in bundle/recording/workflow):
+  # those gates stay strict — a reader that encounters an unknown version
+  # raises {Browserctl::ProtocolMismatch}. This module is the only blessed
+  # path to mutate an old artifact in place.
+  #
+  # The registry ships **empty** in v0.12. The first real migration arrives
+  # only when a format actually changes post-1.0. See
+  # `docs/reference/format-versions.md` ("Migration registry").
+  module Migrations
+    # Single registered upgrader. `upgrade` is a Proc invoked with the
+    # absolute path of the file being migrated; it is responsible for
+    # rewriting that file in place, advancing it from `from_version` to
+    # `to_version`.
+    Migration = Struct.new(:format, :from_version, :to_version, :upgrade, keyword_init: true)
+
+    # Result of {.run}. `applied` is the ordered list of {Migration} steps
+    # that ran. When the artifact was already at target, `applied` is empty.
+    Result = Struct.new(:format, :from, :to, :applied, keyword_init: true)
+
+    FORMAT_EXTENSIONS = {
+      ".bctl" => :bundle,
+      ".jsonl" => :recording,
+      ".rb" => :workflow
+    }.freeze
+
+    @registry = []
+    @mutex = Mutex.new
+
+    class << self
+      # Registers an upgrader for one hop in `format`'s version chain. The
+      # block receives the file path as a keyword argument and must rewrite
+      # the file in place to the new version.
+      def register(format:, from_version:, to_version:, &upgrade)
+        raise ArgumentError, "upgrade block required" unless upgrade
+
+        @mutex.synchronize do
+          @registry << Migration.new(format: format, from_version: from_version,
+                                     to_version: to_version, upgrade: upgrade)
+        end
+      end
+
+      # All registered migrations, in registration order.
+      def all
+        @mutex.synchronize { @registry.dup }
+      end
+
+      # Test-only hook — clears the registry. Not part of the public API.
+      def reset!
+        @mutex.synchronize { @registry.clear }
+      end
+
+      # Breadth-first search through registered migrations to chain a path
+      # for `format` from `from` to `to`. Returns the ordered list of
+      # {Migration} hops, or `nil` if no path is reachable. When `from == to`
+      # returns an empty array (already at target — no work to do).
+      def find_path(format:, from:, to:)
+        return [] if from == to
+
+        all_for_format = all.select { |m| m.format == format }
+        queue = [[from, []]]
+        seen  = { from => true }
+
+        until queue.empty?
+          current, path = queue.shift
+          all_for_format.each do |m|
+            next unless m.from_version == current
+            next if seen[m.to_version]
+
+            new_path = path + [m]
+            return new_path if m.to_version == to
+
+            seen[m.to_version] = true
+            queue << [m.to_version, new_path]
+          end
+        end
+        nil
+      end
+
+      # Inspects an artifact path and returns a format symbol — `:bundle`,
+      # `:recording`, or `:workflow` — or `nil` when the format cannot be
+      # identified. Detection is extension-driven: keep new formats listed
+      # in {FORMAT_EXTENSIONS} so this stays a one-line lookup.
+      def detect_format(path)
+        FORMAT_EXTENSIONS[File.extname(path.to_s).downcase]
+      end
+
+      # Reads `path` and returns the integer format_version it declares, or
+      # `nil` when no version header is present. Format-specific because
+      # each format stores the header differently — the bundle in its
+      # binary manifest, the recording in a `_meta` JSONL line, the
+      # workflow in a Ruby comment.
+      def detect_version(path, format)
+        case format
+        when :bundle    then peek_bundle_version(path)
+        when :recording then peek_recording_version(path)
+        when :workflow  then peek_workflow_version(path)
+        end
+      end
+
+      # End-to-end migration. Detects format and current version, finds a
+      # chain of registered upgraders to `target_version` (or the latest
+      # `to_version` seen for this format if `target_version` is nil), and
+      # invokes each in order. Each upgrader rewrites the file in place.
+      #
+      # Returns a {Result}. When no migrations are needed (or the registry
+      # has no entries for this format), `applied` is empty.
+      #
+      # Raises {Browserctl::ProtocolMismatch} when format detection fails,
+      # the version cannot be read, or no chain reaches the target.
+      def run(path, target_version: nil)
+        format  = detect_format(path) or raise_protocol("could not detect format for #{path}")
+        current = detect_version(path, format) or raise_protocol("could not read format_version from #{path}")
+        target  = target_version || latest_known_target(format, current)
+
+        if current == target
+          # If we'd be a no-op but the artifact's declared version is one this
+          # build's reader does not support, surface that as PROTOCOL_MISMATCH —
+          # there is no migration registered to bring it into range.
+          unless format_version_supported?(format, current)
+            raise_protocol("#{format} at #{path} declares unsupported format_version=#{current}; " \
+                           "no migration registered")
+          end
+          return Result.new(format: format, from: current, to: current, applied: [])
+        end
+
+        chain = find_path(format: format, from: current, to: target)
+        raise_protocol("no migration path from #{format} v#{current} to v#{target}") if chain.nil?
+
+        chain.each { |m| m.upgrade.call(path: path, from_version: m.from_version, to_version: m.to_version) }
+        Result.new(format: format, from: current, to: target, applied: chain)
+      end
+
+      private
+
+      # Reflects whether each format's reader currently accepts a given
+      # version. Mirrors the SUPPORTED_FORMAT_VERSIONS constant on the
+      # corresponding class — kept here so adding a new format is one
+      # branch, not a new public API.
+      def format_version_supported?(format, version)
+        case format
+        when :bundle
+          require_relative "state/bundle"
+          Browserctl::State::Bundle::SUPPORTED_FORMAT_VERSIONS.include?(version)
+        when :recording
+          require_relative "recording"
+          Browserctl::Recording::SUPPORTED_FORMAT_VERSIONS.include?(version)
+        when :workflow
+          require_relative "workflow"
+          Browserctl::SUPPORTED_WORKFLOW_FORMAT_VERSIONS.include?(version)
+        else
+          false
+        end
+      end
+
+      def latest_known_target(format, current)
+        targets = all.select { |m| m.format == format }.map(&:to_version)
+        targets.empty? ? current : targets.max
+      end
+
+      def peek_bundle_version(path)
+        require_relative "state/bundle"
+        manifest = Browserctl::State::Bundle.peek_manifest(File.binread(path))
+        manifest[:format_version] || manifest["format_version"]
+      rescue Browserctl::ProtocolMismatch
+        # `peek_manifest` raises on unknown versions, but we want to *return*
+        # the version so a migration can target it. Re-parse the manifest
+        # bytes directly when the strict gate refuses.
+        peek_bundle_version_loosely(path)
+      end
+
+      def peek_bundle_version_loosely(path)
+        blob = File.binread(path)
+        # Manifest length is at byte offset 8 (5 magic + 3 header). Parse
+        # the JSON without invoking Bundle's strict version check.
+        manifest_len = blob.byteslice(8, 4).unpack1("N")
+        manifest_bytes = blob.byteslice(12, manifest_len)
+        manifest = JSON.parse(manifest_bytes)
+        manifest["format_version"]
+      rescue StandardError
+        nil
+      end
+
+      def peek_recording_version(path)
+        first_line = File.foreach(path).first
+        return nil unless first_line
+
+        meta = JSON.parse(first_line, symbolize_names: true)
+        return nil unless meta[:cmd] == "_meta"
+
+        meta[:format_version]
+      rescue JSON::ParserError
+        nil
+      end
+
+      def peek_workflow_version(path)
+        require_relative "workflow"
+        Browserctl.parse_workflow_format_version(File.read(path))
+      end
+
+      def raise_protocol(msg)
+        raise Browserctl::ProtocolMismatch.new(msg, code: Browserctl::Error::Codes::PROTOCOL_MISMATCH)
+      end
+    end
+  end
+end

data/lib/browserctl/recording.rb

@@ -6,12 +6,22 @@ require "time"
 require "fileutils"
 require "tmpdir"
 require "uri"
+require_relative "errors"
+require_relative "error/codes"
 
 module Browserctl
   class Recording # rubocop:disable Metrics/ClassLength
     RECORDINGS_DIR = File.join(Dir.tmpdir, "browserctl-recordings")
     STATE_FILE     = File.expand_path("~/.browserctl/active_recording")
 
+    # Recording-log format version, written into the `_meta` header and
+    # validated when generate_workflow loads a recording. Distinct from
+    # LOG_FORMAT below — that string ("v0.11") tracks the human-readable
+    # log shape; this integer is the machine-readable schema gate per the
+    # WS-1 format-version convention. See docs/reference/format-versions.md.
+    RECORDING_FORMAT_VERSION = 1
+    SUPPORTED_FORMAT_VERSIONS = [RECORDING_FORMAT_VERSION].freeze
+
     RECORDABLE = %w[page_open navigate fill click screenshot evaluate].freeze
 
     SENSITIVE_PARAM_PATTERN = /\A(token|key|secret|auth|code|access_token|api_key|client_secret|state)\z/ix
@@ -42,6 +52,7 @@ module Browserctl
       File.open(log_path(name), "a") do |f|
         f.puts JSON.generate(
           cmd: "_meta",
+          format_version: RECORDING_FORMAT_VERSION,
           log_format: LOG_FORMAT,
           recording: name,
           started_at: Time.now.utc.iso8601
@@ -52,7 +63,7 @@ module Browserctl
 
     def self.stop
       name = active
-      raise "no active recording — run: browserctl record start <name>" unless name
+      raise Browserctl::Error, "no active recording — run: browserctl record start <name>" unless name
 
       File.unlink(STATE_FILE)
       name
@@ -83,9 +94,10 @@ module Browserctl
 
     def self.generate_workflow(name, output_path: nil, keep_log: false)
       log = log_path(name)
-      raise "no recording found for '#{name}'" unless File.exist?(log)
+      raise Browserctl::Error, "no recording found for '#{name}'" unless File.exist?(log)
 
       raw   = File.readlines(log).map { |l| JSON.parse(l, symbolize_names: true) }
+      verify_format_version!(raw, path: log)
       lines = raw.reject { |l| l[:cmd] == "_meta" }
       ruby  = build_workflow_ruby(name, lines)
       File.write(output_path, ruby) if output_path
@@ -106,6 +118,25 @@ module Browserctl
     class << self
       private
 
+      # Raises Browserctl::ProtocolMismatch when the recording log's _meta
+      # header is missing or declares a format_version this build does not
+      # support. Mirrors Browserctl::State::Bundle.verify_format_version!.
+      def verify_format_version!(raw_lines, path: nil)
+        meta = raw_lines.first
+        version = meta && meta[:cmd] == "_meta" ? meta[:format_version] : nil
+        return if version && SUPPORTED_FORMAT_VERSIONS.include?(version)
+
+        where = path ? " at #{path}" : ""
+        msg = if version.nil?
+                "recording log#{where} is missing format_version " \
+                  "(supported: #{SUPPORTED_FORMAT_VERSIONS.inspect})"
+              else
+                "recording log#{where} declares format_version=#{version.inspect}, " \
+                  "this build supports #{SUPPORTED_FORMAT_VERSIONS.inspect}"
+              end
+        raise Browserctl::ProtocolMismatch.new(msg, code: Browserctl::Error::Codes::PROTOCOL_MISMATCH)
+      end
+
       def log_path(name)
         File.join(RECORDINGS_DIR, "#{name}.jsonl")
       end
@@ -141,6 +172,7 @@ module Browserctl
         header  = secret_header(secrets)
         <<~RUBY
           # frozen_string_literal: true
+          # format_version: #{Browserctl::WORKFLOW_FORMAT_VERSION}
           #{header}
           Browserctl.workflow #{name.inspect} do
             desc "Recorded on #{Date.today}"

data/lib/browserctl/redactor.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Browserctl
+  # Redacts known secret values from arbitrary strings.
+  #
+  # Used by `browserctl trace` to ensure traces are safe to attach to issues
+  # by default. Secret values are sourced from two places:
+  #   1. ENV variables whose names match well-known secret patterns
+  #      (`*_TOKEN`, `*_KEY`, `*_SECRET`, `*_PASSWORD`).
+  #   2. Values captured at runtime by `SecretResolverRegistry` (in-memory
+  #      only — never persisted).
+  #
+  # Replacement marker is the literal `[REDACTED]`. We considered including
+  # a sha256 prefix to distinguish values, but that doubles the surface area
+  # for accidental leakage (a determined attacker could brute-force short
+  # secrets from the prefix), and the timeline is more scannable with a
+  # uniform marker.
+  class Redactor
+    MARKER = "[REDACTED]"
+    MIN_LENGTH = 4
+    ENV_PATTERNS = [/_TOKEN\z/, /_KEY\z/, /_SECRET\z/, /_PASSWORD\z/].freeze
+
+    # @param secrets [Array<String>] secret values to redact.
+    def initialize(secrets: [])
+      # Filter empty / too-short values; longest-first to avoid partial
+      # overlaps (e.g. redacting "abcd" before "abcdef" would leave "ef").
+      @secrets = secrets
+                 .compact
+                 .map(&:to_s)
+                 .reject { |s| s.length < MIN_LENGTH }
+                 .uniq
+                 .sort_by { |s| -s.length }
+    end
+
+    # @param string [String, nil]
+    # @return [String, nil]
+    def redact(string)
+      return string if string.nil?
+
+      result = string.to_s
+      @secrets.each { |secret| result = result.gsub(secret, MARKER) }
+      result
+    end
+
+    def empty?
+      @secrets.empty?
+    end
+
+    # Build a Redactor from the current ENV using well-known patterns.
+    # Optionally merges in additional values (e.g. from runtime instrumentation).
+    def self.from_env(env: ENV, extra: [])
+      values = env.each_with_object([]) do |(name, value), acc|
+        acc << value if ENV_PATTERNS.any? { |re| name =~ re }
+      end
+      new(secrets: values + Array(extra))
+    end
+  end
+end

data/lib/browserctl/rubocop/cops/typed_error.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Cop
+    module Browserctl
+      # Enforces that any explicit `code:` keyword passed to a `raise` of a
+      # `Browserctl::*` error refers to a constant from
+      # `Browserctl::Error::Codes` rather than a free-form string literal.
+      #
+      # Subclasses with their own `default_code` are trusted (the cop does not
+      # try to statically resolve `default_code` across files); the contract
+      # is enforced by the unit test suite. This cop's job is to catch the
+      # specific failure mode of inlining a stale snake_case code at the
+      # raise site and bypassing the canonical enum.
+      #
+      # @example
+      #   # bad — string literal that isn't a Codes constant
+      #   raise Browserctl::Error, "state expired", code: "state_expired"
+      #
+      #   # good — Codes constant reference
+      #   raise Browserctl::Error, "state expired",
+      #         code: Browserctl::Error::Codes::STATE_EXPIRED
+      #
+      #   # good — typed subclass relies on its own default_code
+      #   raise Browserctl::SelectorNotFound, "no such selector"
+      #
+      # The pattern is intentionally narrow. The full default_code-vs-Codes
+      # reconciliation lives in `lib/browserctl/errors.rb` and is covered by
+      # `spec/unit/errors_spec.rb`.
+      class TypedError < RuboCop::Cop::Base
+        MSG = "Browserctl raise: `code:` must reference Browserctl::Error::Codes::* — " \
+              "got string literal %<value>p. See lib/browserctl/error/codes.rb."
+
+        VALID_CODES = %w[
+          AUTH_REQUIRED
+          SELECTOR_NOT_FOUND
+          STATE_EXPIRED
+          SECRET_RESOLUTION_FAILED
+          DAEMON_UNREACHABLE
+          PROTOCOL_MISMATCH
+        ].freeze
+
+        # Matches `raise Browserctl::Foo, ..., code: <value>` and yields the
+        # `code:` value node.
+        def_node_matcher :browserctl_raise_with_code, <<~PATTERN
+          (send nil? :raise
+            (const (const nil? :Browserctl) _)
+            ...
+            (hash <(pair (sym :code) $_) ...>))
+        PATTERN
+
+        def on_send(node)
+          return unless node.method?(:raise)
+
+          browserctl_raise_with_code(node) do |code_value|
+            next unless code_value.str_type?
+
+            value = code_value.value
+            next if VALID_CODES.include?(value)
+
+            add_offense(code_value, message: format(MSG, value: value))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/runner.rb

@@ -57,7 +57,7 @@ module Browserctl
     SAFE_WORKFLOW_NAME = /\A[a-zA-Z0-9_-]+\z/
 
     def self.load_params_file(path)
-      raise "params file not found: #{path}" unless File.exist?(path)
+      raise Browserctl::WorkflowError, "params file not found: #{path}" unless File.exist?(path)
 
       case File.extname(path).downcase
       when ".yml", ".yaml"
@@ -66,12 +66,12 @@ module Browserctl
       when ".json"
         JSON.parse(File.read(path), symbolize_names: true)
       else
-        raise "unsupported params file format: #{path} (use .yml, .yaml, or .json)"
+        raise Browserctl::WorkflowError, "unsupported params file format: #{path} (use .yml, .yaml, or .json)"
       end
     rescue Psych::SyntaxError => e
-      raise "invalid YAML in #{path}: #{e.message}"
+      raise Browserctl::WorkflowError, "invalid YAML in #{path}: #{e.message}"
     rescue JSON::ParserError => e
-      raise "invalid JSON in #{path}: #{e.message}"
+      raise Browserctl::WorkflowError, "invalid JSON in #{path}: #{e.message}"
     end
 
     private
@@ -95,7 +95,10 @@ module Browserctl
       return if Browserctl.lookup_workflow(name.to_s)
 
       path = workflow_path(name)
-      load path if path
+      return unless path
+
+      Browserctl.verify_workflow_format_version!(path)
+      load path
     end
 
     def workflow_path(name)
@@ -111,7 +114,10 @@ module Browserctl
 
     def load_from_dir(dir)
       Dir.glob("#{dir}/*.rb").each do |f|
-        load f unless $LOADED_FEATURES.include?(f)
+        next if $LOADED_FEATURES.include?(f)
+
+        Browserctl.verify_workflow_format_version!(f)
+        load f
       end
     end
 

data/lib/browserctl/secret_resolver_registry.rb

@@ -4,8 +4,9 @@ require_relative "errors"
 
 module Browserctl
   class SecretResolverRegistry
-    @mutex    = Mutex.new
-    @registry = {}
+    @mutex          = Mutex.new
+    @registry       = {}
+    @resolved_values = []
 
     def self.register(resolver_class)
       instance = resolver_class.new
@@ -25,7 +26,9 @@ module Browserctl
         raise SecretResolverError, msg
       end
 
-      resolver.resolve(reference)
+      value = resolver.resolve(reference)
+      record_resolved_value(value)
+      value
     rescue SecretResolverError
       raise
     rescue StandardError => e
@@ -36,8 +39,24 @@ module Browserctl
       @mutex.synchronize { @registry.key?(scheme) }
     end
 
+    # In-memory record of values resolved during this process. Used by the
+    # Redactor so trace output never leaks values that flowed through the
+    # registry. Never persisted.
+    def self.resolved_values
+      @mutex.synchronize { @resolved_values.dup }
+    end
+
+    def self.record_resolved_value(value)
+      return unless value.is_a?(String) && !value.empty?
+
+      @mutex.synchronize { @resolved_values << value unless @resolved_values.include?(value) }
+    end
+
     def self.reset!
-      @mutex.synchronize { @registry.clear }
+      @mutex.synchronize do
+        @registry.clear
+        @resolved_values.clear
+      end
     end
   end
 end

data/lib/browserctl/server/command_dispatcher.rb

@@ -2,6 +2,7 @@
 
 require_relative "snapshot_builder"
 require_relative "page_session"
+require_relative "handlers/error_payload"
 require_relative "handlers/page_lifecycle"
 require_relative "handlers/navigation"
 require_relative "handlers/observation"
@@ -15,10 +16,12 @@ require_relative "handlers/state"
 require_relative "handlers/interaction"
 require_relative "../detectors"
 require_relative "../policy"
+require_relative "../errors"
 require_relative "../replay/snapshot_diff"
 
 module Browserctl
   class CommandDispatcher
+    include Handlers::ErrorPayload
     include Handlers::PageLifecycle
     include Handlers::Navigation
     include Handlers::Observation