browserctl 0.10.0 → 0.12.0

data/lib/browserctl/commands/workflow.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "json"
 require_relative "cli_output"
+require_relative "../recording"
+require_relative "../workflow/promoter"
 
 module Browserctl
   module Commands
     module Workflow
       extend CliOutput
 
-      USAGE = "Usage: browserctl workflow <run|list|describe> [args]"
+      USAGE = "Usage: browserctl workflow <run|list|describe|generate|promote> [args]"
 
       def self.run(runner, args)
         sub = args.shift or abort USAGE
@@ -16,18 +19,73 @@ module Browserctl
         when "run"      then run_workflow(runner, args)
         when "list"     then run_list(runner)
         when "describe" then run_describe(runner, args)
+        when "generate" then run_generate(args)
+        when "promote"  then run_promote(args)
         else abort "unknown workflow subcommand '#{sub}'\n#{USAGE}"
         end
       end
 
+      def self.run_promote(args)
+        name = args.shift or abort \
+          "usage: browserctl workflow promote <name> [--force] [--threshold N] [--as-flow]"
+
+        force   = !args.delete("--force").nil?
+        as_flow = !args.delete("--as-flow").nil?
+
+        threshold_idx = args.index("--threshold")
+        threshold = if threshold_idx
+                      val = args.delete_at(threshold_idx + 1)
+                      args.delete_at(threshold_idx)
+                      Integer(val)
+                    else
+                      Browserctl::Workflow::PromotionLedger::DEFAULT_THRESHOLD
+                    end
+
+        result = Browserctl::Workflow::Promoter.promote(
+          workflow: name, force: force, threshold: threshold, as_flow: as_flow
+        )
+        puts JSON.generate(ok: true, **result)
+      rescue Browserctl::Workflow::Promoter::IneligibleError => e
+        puts JSON.generate(
+          ok: false, error: "ineligible",
+          message: e.message, streak: e.streak, threshold: e.threshold
+        )
+        exit 1
+      rescue Browserctl::Workflow::Promoter::NotFoundError => e
+        abort "Error: #{e.message}"
+      rescue ArgumentError => e
+        abort "Error: invalid --threshold value: #{e.message}"
+      end
+
+      def self.run_generate(args)
+        name = args.shift or abort \
+          "usage: browserctl workflow generate <recording> [--out PATH]"
+        out_idx = args.index("--out")
+        out = if out_idx
+                args.delete_at(out_idx + 1).tap { args.delete_at(out_idx) }
+              else
+                File.join(".browserctl/workflows", "#{name}.rb")
+              end
+        FileUtils.mkdir_p(File.dirname(out))
+        Browserctl::Recording.generate_workflow(name, output_path: out, keep_log: true)
+        puts JSON.generate({ ok: true, name: name, path: out })
+      rescue StandardError => e
+        abort "Error generating workflow: #{e.message}"
+      end
+
+      EXIT_CODE = { clean: 0, drift: 2, fail: 1 }.freeze
+
       def self.run_workflow(runner, args)
-        name = args.shift or abort "usage: browserctl workflow run <name|file> [--params file] [--key value ...]"
+        name = args.shift or abort \
+          "usage: browserctl workflow run <name|file> [--check] [--params file] [--key value ...]"
         if File.exist?(name)
           before = Browserctl.registry_snapshot.keys
           load File.expand_path(name)
           name = (Browserctl.registry_snapshot.keys - before).first || File.basename(name, ".rb")
         end
 
+        check = !args.delete("--check").nil?
+
         params_file_idx = args.index("--params")
         file_params = {}
         if params_file_idx
@@ -47,8 +105,8 @@ module Browserctl
         end
 
         params = file_params.merge(cli_params)
-        success = runner.run_workflow(name, **params)
-        exit(success ? 0 : 1)
+        verdict = runner.run_workflow(name, check: check, **params)
+        exit(EXIT_CODE.fetch(verdict, 1))
       end
 
       def self.run_list(runner)

data/lib/browserctl/constants.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "errors"
+
 module Browserctl
   BROWSERCTL_DIR   = File.expand_path("~/.browserctl")
   IDLE_TTL         = 30 * 60
   # Increment when a breaking wire protocol change ships (new field names, removed commands, changed response shapes).
   # Clients read this from `ping` to verify compatibility before sending commands.
-  PROTOCOL_VERSION = "2"
+  PROTOCOL_VERSION = "3"
 
   def self.socket_path(name = nil)
     File.join(BROWSERCTL_DIR, name ? "#{name}.sock" : "browserd.sock")
@@ -26,7 +28,7 @@ module Browserctl
     1.upto(99) do |i|
       return "d#{i}" unless File.exist?(socket_path("d#{i}"))
     end
-    raise "too many running daemons (limit: 99)"
+    raise Browserctl::Error, "too many running daemons (limit: 99)"
   end
 
   def self.all_daemon_sockets

data/lib/browserctl/crash_report.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "fileutils"
+require "etc"
+
+require_relative "version"
+require_relative "logger"
+
+module Browserctl
+  # Writes a local crash report JSON file when the daemon panics. No telemetry,
+  # no upload — purely a local artifact users can attach to bug reports.
+  #
+  # The writer is intentionally defensive: it must never raise. If anything
+  # goes wrong while writing the file, it falls back to a single
+  # `[crash-report-failed]` line on stderr and returns nil.
+  module CrashReport
+    SCHEMA_VERSION = 1
+    LAST_EVENTS_LIMIT = 50
+
+    # @param error [Exception] the unhandled exception that took the daemon down
+    # @param log_path [String, nil] path to the daemon's JSONL log; the last
+    #   {LAST_EVENTS_LIMIT} valid records are tailed in
+    # @return [String, nil] the path of the written crash file, or nil on failure
+    def self.write(error:, log_path: nil)
+      ts = Time.now.utc
+      filename = "crash-#{ts.iso8601(3).gsub(':', '-')}.json"
+      dir = Browserctl.log_dir
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      path = File.join(dir, filename)
+
+      payload = {
+        schema_version: SCHEMA_VERSION,
+        ts: ts.iso8601(3),
+        daemon_version: Browserctl::VERSION,
+        ruby_version: RUBY_VERSION,
+        os: os_info,
+        error: error_info(error),
+        backtrace: Array(error.backtrace),
+        last_events: tail_events(log_path)
+      }
+
+      File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |f|
+        f.write(JSON.pretty_generate(payload))
+      end
+      path
+    rescue StandardError => e
+      warn "[crash-report-failed] #{e.class}: #{e.message}"
+      nil
+    end
+
+    def self.os_info
+      info = { platform: RUBY_PLATFORM }
+      uname = Etc.uname
+      info[:version] = uname[:version] if uname.is_a?(Hash) && uname[:version]
+      info[:sysname] = uname[:sysname] if uname.is_a?(Hash) && uname[:sysname]
+      info
+    rescue StandardError
+      { platform: RUBY_PLATFORM }
+    end
+    private_class_method :os_info
+
+    def self.error_info(error)
+      info = {
+        class: error.class.name,
+        message: error.message.to_s
+      }
+      info[:code] = error.code if error.respond_to?(:code) && error.code
+      info
+    end
+    private_class_method :error_info
+
+    def self.tail_events(log_path)
+      return [] unless log_path && File.exist?(log_path)
+
+      lines = File.readlines(log_path).last(LAST_EVENTS_LIMIT * 2)
+      events = []
+      lines.reverse_each do |line|
+        line = line.strip
+        next if line.empty?
+
+        begin
+          events.unshift(JSON.parse(line))
+        rescue JSON::ParserError
+          next
+        end
+        break if events.length >= LAST_EVENTS_LIMIT
+      end
+      events
+    rescue StandardError
+      []
+    end
+    private_class_method :tail_events
+  end
+end

data/lib/browserctl/detectors/auth_required.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Detectors
+    # Detects "you need to log in again" — the signal that flips a workflow's
+    # `load_state` into `state rotate` territory. Lives alongside the older
+    # `Detectors.cloudflare?` and follows the same `(page) -> Result` shape.
+    #
+    # Three independent checks, evaluated in order. The first to fire wins:
+    #
+    #   1. URL → login path. The page is currently sitting on /login,
+    #      /signin, /auth/login, or a similar canonical login route. This
+    #      catches redirect-based auth ("we noticed you're not logged in").
+    #   2. Recent HTTP 401 / 403. The most recent network response on this
+    #      page was an auth challenge from the backend.
+    #   3. Cookie ledger. A caller-supplied list of cookies contains entries
+    #      that have already expired. Useful when the daemon is preflighting
+    #      a bundle before navigating.
+    #
+    # Each check is pure — no daemon dependencies — so the same detector
+    # runs server-side (handlers/observation.rb) and client-side (workflow
+    # `load_state` hook).
+    module AuthRequired
+      Result = Struct.new(:triggered, :code, :reason, :suggested_flow, keyword_init: true) do
+        def to_h
+          { triggered: triggered, code: code, reason: reason, suggested_flow: suggested_flow }.compact
+        end
+      end
+
+      LOGIN_PATH_RE = %r{(?:^|/)(login|signin|sign[-_]in|auth/(?:login|signin)|account/login)(?:/|$|\?)}i
+
+      AUTH_HTTP_STATUSES = [401, 403].freeze
+
+      class << self
+        # Run every check; return the first triggered Result, or a non-
+        # triggered Result if all pass.
+        #
+        # @param page  [#current_url] anything quacking like a Page
+        # @param recent_responses [Array<Hash>] each `{ status:, url: }`; the
+        #   caller is responsible for collecting these (e.g. via Ferrum's
+        #   network.traffic). Empty by default so callers without traffic
+        #   instrumentation still get the URL/cookie checks.
+        # @param cookies [Array<Hash>, nil] each `{ name:, expires: }`;
+        #   `expires` is a unix timestamp. nil to skip the cookie check.
+        # @param suggested_flow [String, nil] flow name to surface when the
+        #   detector fires — populated by callers from the bundle manifest.
+        # @return [Result]
+        def detect(page, recent_responses: [], cookies: nil, suggested_flow: nil)
+          [
+            check_url(page, suggested_flow),
+            check_responses(recent_responses, suggested_flow),
+            check_cookies(cookies, suggested_flow)
+          ].find(&:triggered) || negative
+        end
+
+        # Convenience predicate matching the existing `Detectors.cloudflare?`
+        # style. Callers that just need a boolean can use this.
+        def triggered?(page, **)
+          detect(page, **).triggered
+        end
+
+        private
+
+        def check_url(page, suggested_flow)
+          url = safe_call(page, :current_url).to_s
+          match = LOGIN_PATH_RE.match(url)
+          return negative unless match
+
+          Result.new(triggered: true, code: "redirect_login",
+                     reason: "url '#{url}' matches login path", suggested_flow: suggested_flow)
+        end
+
+        def check_responses(recent_responses, suggested_flow)
+          response = Array(recent_responses).reverse_each.find do |r|
+            AUTH_HTTP_STATUSES.include?(r[:status] || r["status"])
+          end
+          return negative unless response
+
+          status = response[:status] || response["status"]
+          url    = response[:url] || response["url"]
+          Result.new(triggered: true, code: "http_#{status}",
+                     reason: "recent #{status} from #{url}", suggested_flow: suggested_flow)
+        end
+
+        def check_cookies(cookies, suggested_flow)
+          return negative if cookies.nil?
+
+          expired = expired_cookies(cookies)
+          return negative if expired.empty?
+
+          names = expired.map { |c| c[:name] || c["name"] }.compact.join(", ")
+          Result.new(triggered: true, code: "cookie_expired",
+                     reason: "expired cookies: #{names}", suggested_flow: suggested_flow)
+        end
+
+        def expired_cookies(cookies)
+          now = Time.now.to_f
+          Array(cookies).select { |c| cookie_expired?(c, now) }
+        end
+
+        def cookie_expired?(cookie, now)
+          exp = cookie[:expires] || cookie["expires"]
+          return false unless exp
+
+          float = exp.to_f
+          float.positive? && float < now
+        end
+
+        def negative
+          Result.new(triggered: false, code: nil, reason: nil, suggested_flow: nil)
+        end
+
+        def safe_call(obj, method)
+          obj.respond_to?(method) ? obj.public_send(method) : nil
+        end
+      end
+    end
+
+    # Module-level shorthand so callers match the existing `Detectors.cloudflare?` style.
+    def self.auth_required?(page, **)
+      AuthRequired.triggered?(page, **)
+    end
+
+    def self.auth_required(page, **)
+      AuthRequired.detect(page, **)
+    end
+  end
+end

data/lib/browserctl/detectors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "detectors/auth_required"
+
 module Browserctl
   module Detectors
     CLOUDFLARE_SIGNALS = [

data/lib/browserctl/error/codes.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class Error < StandardError
+    # Canonical enum of stable error code strings emitted on the wire and in
+    # CLI stderr payloads. Codes are SCREAMING_SNAKE_CASE and must remain
+    # stable across releases — agents branch on these deterministically.
+    #
+    # The full sweep that wires every raise site to one of these codes lands
+    # in PR #8 of the v0.12 "Solid" milestone. This module is the single
+    # source of truth those raises will reference.
+    module Codes
+      AUTH_REQUIRED            = "AUTH_REQUIRED"
+      SELECTOR_NOT_FOUND       = "SELECTOR_NOT_FOUND"
+      STATE_EXPIRED            = "STATE_EXPIRED"
+      SECRET_RESOLUTION_FAILED = "SECRET_RESOLUTION_FAILED"
+      DAEMON_UNREACHABLE       = "DAEMON_UNREACHABLE"
+      PROTOCOL_MISMATCH        = "PROTOCOL_MISMATCH"
+      DOMAIN_NOT_ALLOWED       = "DOMAIN_NOT_ALLOWED"
+      KEY_NOT_FOUND            = "KEY_NOT_FOUND"
+      GENERIC                  = "GENERIC"
+
+      ALL = [
+        AUTH_REQUIRED,
+        SELECTOR_NOT_FOUND,
+        STATE_EXPIRED,
+        SECRET_RESOLUTION_FAILED,
+        DAEMON_UNREACHABLE,
+        PROTOCOL_MISMATCH,
+        DOMAIN_NOT_ALLOWED,
+        KEY_NOT_FOUND,
+        GENERIC
+      ].freeze
+
+      def self.all
+        ALL
+      end
+
+      def self.valid?(code)
+        ALL.include?(code)
+      end
+    end
+  end
+end

data/lib/browserctl/error/exit_codes.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "codes"
+
+module Browserctl
+  class Error < StandardError
+    # Stable mapping from a canonical {Browserctl::Error::Codes} string to a
+    # process exit status. The CLI's top-level rescue uses this so AI agents
+    # and shell scripts can branch on `$?` deterministically without parsing
+    # stderr.
+    #
+    # Stability contract:
+    # - Exit code integers are part of the v0.12 stable surface and will not
+    #   be renumbered without a major version bump.
+    # - Unknown / unmapped codes intentionally fall through to {GENERIC} (1)
+    #   so an unfamiliar code never silently surfaces as a non-error (0).
+    #
+    # See docs/reference/exit-codes.md for the operator-facing table.
+    module ExitCodes
+      OK                 = 0
+      GENERIC            = 1
+      DRIFT              = 2
+      AUTH_REQUIRED      = 3
+      DAEMON_UNREACHABLE = 4
+      PROTOCOL_MISMATCH  = 5
+      SELECTOR_NOT_FOUND = 6
+      STATE_EXPIRED      = 7
+
+      # Canonical Codes string → exit status integer. Codes without an entry
+      # (e.g. DOMAIN_NOT_ALLOWED, KEY_NOT_FOUND, SECRET_RESOLUTION_FAILED,
+      # GENERIC) collapse to {GENERIC} for now; they may earn dedicated exit
+      # codes in a future milestone.
+      #
+      # DRIFT (2) is reserved for a future Codes::DRIFT and currently has no
+      # entry in this table — drift-related raises fall through to GENERIC
+      # until that code is introduced.
+      TABLE = {
+        Codes::AUTH_REQUIRED => AUTH_REQUIRED,
+        Codes::DAEMON_UNREACHABLE => DAEMON_UNREACHABLE,
+        Codes::PROTOCOL_MISMATCH => PROTOCOL_MISMATCH,
+        Codes::SELECTOR_NOT_FOUND => SELECTOR_NOT_FOUND,
+        Codes::STATE_EXPIRED => STATE_EXPIRED
+      }.freeze
+
+      # @param code [String, nil] a canonical code from {Browserctl::Error::Codes}
+      # @return [Integer] mapped exit status; {GENERIC} for nil or unknown codes
+      def self.for(code)
+        return GENERIC if code.nil?
+
+        TABLE.fetch(code, GENERIC)
+      end
+    end
+  end
+end

data/lib/browserctl/error/suggested_actions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "codes"
+
+module Browserctl
+  class Error < StandardError
+    # Maps a stable error code (see {Browserctl::Error::Codes}) to a short
+    # imperative sentence telling the operator (or AI agent) what to try
+    # next. Codes without an explicit entry fall back to a generic pointer
+    # to the error reference doc (added in PR #11 of v0.12).
+    module SuggestedActions
+      DEFAULT = "See docs/reference/errors.md for guidance."
+
+      TABLE = {
+        Codes::AUTH_REQUIRED =>
+          "Run the suggested flow to refresh credentials, then retry.",
+        Codes::SELECTOR_NOT_FOUND =>
+          "Re-run snapshot to get fresh refs, then retry with a stable ref or selector.",
+        Codes::STATE_EXPIRED =>
+          "Re-save the state bundle (state save) or rotate it (state rotate).",
+        Codes::SECRET_RESOLUTION_FAILED =>
+          "Verify the secret resolver config and that the underlying secret exists.",
+        Codes::DAEMON_UNREACHABLE =>
+          "Start the daemon with 'browserctl daemon start', then retry.",
+        Codes::PROTOCOL_MISMATCH =>
+          "Upgrade browserctl to a version that supports this artifact's format version.",
+        Codes::DOMAIN_NOT_ALLOWED =>
+          "Add the domain to your policy allowlist or use an allowed URL.",
+        Codes::KEY_NOT_FOUND =>
+          "Verify the key was stored in this daemon session before fetching.",
+        Codes::GENERIC => DEFAULT
+      }.freeze
+
+      # @param code [String, nil] a SCREAMING_SNAKE code from {Codes}
+      # @return [String] suggested action sentence; never nil
+      def self.for(code)
+        TABLE.fetch(code, DEFAULT)
+      end
+    end
+  end
+end

data/lib/browserctl/errors.rb

@@ -1,36 +1,96 @@
 # frozen_string_literal: true
 
+require_relative "error/codes"
+require_relative "error/exit_codes"
+require_relative "error/suggested_actions"
+
 module Browserctl
   # Base error class for all browserctl daemon errors.
   # Subclasses carry a machine-readable `code` that appears in wire responses.
+  # The canonical enum of stable codes lives in {Browserctl::Error::Codes};
+  # the sweep that retrofits every raise to use those codes lands in a later
+  # v0.12 PR.
   # @attr_reader code [String] machine-readable error code
+  # @attr_reader context [Hash] free-form structured fields (selector, path, ...)
   class Error < StandardError
     def self.default_code = "error"
 
-    attr_reader :code
+    attr_reader :code, :context
 
-    def initialize(msg = nil, code: self.class.default_code)
-      @code = code
+    def initialize(msg = nil, code: self.class.default_code, context: {})
+      @code    = code
+      @context = context || {}
       super(msg)
     end
+
+    # Returns the canonical structured payload emitted on the daemon wire and
+    # on CLI stderr. Shape is stable across releases — agents branch on `code`
+    # without parsing prose.
+    # @return [Hash{Symbol => Object}]
+    def to_payload
+      {
+        code: code,
+        message: message,
+        context: context,
+        suggested_action: SuggestedActions.for(code)
+      }
+    end
   end
 
-  class PageNotFound     < Error; def self.default_code = "page_not_found"     end
-  class SelectorNotFound < Error; def self.default_code = "selector_not_found" end
-  class RefNotFound      < Error; def self.default_code = "ref_not_found"      end
-  class PathNotAllowed   < Error; def self.default_code = "path_not_allowed"   end
-  class DomainNotAllowed < Error; def self.default_code = "domain_not_allowed" end
-  class TimeoutError     < Error; def self.default_code = "timeout"            end
-  class KeyNotFound < Error; def self.default_code = "key_not_found" end
-  class DaemonUnavailableError < Error; def self.default_code = "daemon_unavailable" end
+  class PageNotFound     < Error; def self.default_code = "page_not_found" end
+  class SelectorNotFound < Error; def self.default_code = Codes::SELECTOR_NOT_FOUND   end
+  class RefNotFound      < Error; def self.default_code = "ref_not_found"             end
+  class PathNotAllowed   < Error; def self.default_code = "path_not_allowed"          end
+  class DomainNotAllowed < Error; def self.default_code = "domain_not_allowed"        end
+  class TimeoutError     < Error; def self.default_code = "timeout"                   end
+  class KeyNotFound      < Error; def self.default_code = "key_not_found"             end
+  class DaemonUnavailableError < Error; def self.default_code = Codes::DAEMON_UNREACHABLE end
   class BrowserNotFound < Error; def self.default_code = "browser_not_found" end
 
+  # Raised when the daemon detects that the current page needs authentication —
+  # the canonical signal that a workflow's `load_state` should rotate the bound
+  # flow. Carries the bundle name (when a state load was in progress) and a
+  # suggested flow (from the bundle manifest) so callers can recover without
+  # additional lookups. The CLI maps this code to exit status 7.
+  class AuthRequiredError < Error
+    def self.default_code = Codes::AUTH_REQUIRED
+
+    AUTH_REQUIRED_EXIT_CODE = 7
+
+    attr_reader :state, :suggested_flow, :reason
+
+    def initialize(msg = "authentication required", state: nil, suggested_flow: nil, reason: nil)
+      super(msg)
+      @state          = state
+      @suggested_flow = suggested_flow
+      @reason         = reason
+    end
+
+    def to_response
+      {
+        error: message,
+        code: self.class.default_code,
+        state: state,
+        suggested_flow: suggested_flow,
+        reason: reason,
+        context: { state: state, suggested_flow: suggested_flow, reason: reason }.compact,
+        suggested_action: SuggestedActions.for(self.class.default_code)
+      }.compact
+    end
+  end
+
   class WorkflowError < Error; def self.default_code = "workflow_error" end
-  class SecretResolverError < WorkflowError; def self.default_code = "secret_resolver_error" end
+  class SecretResolverError < WorkflowError; def self.default_code = Codes::SECRET_RESOLUTION_FAILED end
 
   class FlowError < WorkflowError; def self.default_code = "flow_error" end
   class FlowParamError < FlowError; def self.default_code = "flow_param_error" end
   class FlowPreconditionError < FlowError; def self.default_code = "flow_precondition_failed" end
   class FlowStepError < FlowError; def self.default_code = "flow_step_failed" end
   class FlowPostconditionError < FlowError; def self.default_code = "flow_postcondition_failed" end
+
+  # Raised when a persisted artifact (bundle, recording, workflow, etc.) has a
+  # `version:` header that this build does not know how to read. The full error
+  # code taxonomy lands in WS-2 (PR #7); this class is a forward-reference stub
+  # so WS-1 PRs can already raise the canonical code.
+  class ProtocolMismatch < Error; def self.default_code = Codes::PROTOCOL_MISMATCH end
 end

data/lib/browserctl/flow.rb

@@ -186,9 +186,30 @@ module Browserctl
     end
   end
 
+  @flow_registry_mutex = Mutex.new
+  @flow_registry       = {}
+
   def self.flow(name, &block)
     raise ArgumentError, "Browserctl.flow requires a block" unless block
 
-    Flow.new(name).tap { |f| f.instance_exec(&block) }
+    flow = Flow.new(name).tap { |f| f.instance_exec(&block) }
+    register_flow(flow)
+    flow
+  end
+
+  def self.register_flow(flow)
+    @flow_registry_mutex.synchronize { @flow_registry[flow.name] = flow }
+  end
+
+  def self.lookup_flow(name)
+    @flow_registry_mutex.synchronize { @flow_registry[name.to_s] }
+  end
+
+  def self.flow_registry_snapshot
+    @flow_registry_mutex.synchronize { @flow_registry.dup }
+  end
+
+  def self.flow_registry_reset!
+    @flow_registry_mutex.synchronize { @flow_registry.clear }
   end
 end