deployangel 0.1.0

data/lib/deployangel/mcp.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DeployAngel
+  module MCP
+    # A Model Context Protocol server over stdio (JSON-RPC 2.0, one message
+    # per line) so coding agents can ask whether their release passed
+    # production. stdout carries only protocol messages.
+    #
+    # The tools are read-only with respect to production: nothing here rolls
+    # back, restarts, or changes customer infrastructure.
+    class Server
+      PROTOCOL_VERSIONS = %w[2025-06-18 2025-03-26 2024-11-05].freeze
+      MAX_WAIT_SECONDS = 300
+
+      INSTRUCTIONS = <<~TEXT.freeze
+        DeployAngel verifies deployments in production. After deploying, call wait_for_verification
+        with until "initial" (about 15 minutes) or "verdict". Verdicts: verified means cleared, so you may
+        report the release as successful. inconclusive means NOT verified: never report it as success.
+        failed means production regressed: read the findings and exceptions and investigate.
+        Findings are deterministic evidence; any "investigation" field is AI inference. These tools cannot
+        change production. Do not roll back or change production without explicit approval.
+      TEXT
+
+      TARGET_PROPERTIES = {
+        "commit" => { "type" => "string", "description" => "Commit SHA (prefix of 7+ characters is fine)." },
+        "version" => { "type" => "string", "description" => "Release version, e.g. v184." },
+        "deployment_id" => { "type" => "string", "description" => "DeployAngel deployment ID." },
+        "latest" => { "type" => "boolean", "description" => "Use the most recent deployment." }
+      }.freeze
+
+      ERROR_CODES = { parse: -32_700, invalid: -32_600, method: -32_601, params: -32_602, internal: -32_603 }.freeze
+
+      def initialize(client:, input: $stdin, output: $stdout, error_output: $stderr,
+                     sleeper: ->(seconds) { sleep(seconds) }, clock: -> { Time.now }, git_head: -> {})
+        @client = client
+        @input = input
+        @output = output
+        @error_output = error_output
+        @sleeper = sleeper
+        @clock = clock
+        @git_head = git_head
+      end
+
+      def run
+        @input.each_line do |line|
+          next if line.strip.empty?
+
+          response = handle_line(line)
+          next unless response
+
+          @output.puts(JSON.generate(response))
+          @output.flush
+        end
+      end
+
+      def handle_line(line)
+        message = JSON.parse(line)
+        return error_response(nil, :invalid, "expected a JSON object") unless message.is_a?(Hash)
+
+        handle(message)
+      rescue JSON::ParserError
+        error_response(nil, :parse, "invalid JSON")
+      end
+
+      def handle(message)
+        id = message["id"]
+        method = message["method"]
+        return nil if id.nil? # notifications, including notifications/initialized
+
+        case method
+        when "initialize" then result(id, initialize_result(message.dig("params", "protocolVersion")))
+        when "ping" then result(id, {})
+        when "tools/list" then result(id, { "tools" => tools })
+        when "tools/call" then result(id, call_tool(message.dig("params", "name"), message.dig("params", "arguments") || {}))
+        else error_response(id, :method, "method not found: #{method}")
+        end
+      rescue ArgumentError => e
+        error_response(id, :params, e.message)
+      rescue StandardError => e
+        @error_output.puts("deployangel mcp: #{e.class}: #{e.message}")
+        error_response(id, :internal, "internal error")
+      end
+
+      def tools
+        list = [
+          tool("get_verification", "Current verdict document for a deployment: state, verdict, confidence, coverage, " \
+            "findings, new exceptions, clearance report, and what is still watched. Defaults to the current git HEAD.",
+            TARGET_PROPERTIES),
+          tool("wait_for_verification", "Wait for a deployment's verification. until=initial returns at the 15-minute " \
+            "initial check (\"no problems so far\" is NOT clearance); until=verdict waits for verified, failed, or " \
+            "inconclusive. Returns the in-progress document if timeout_seconds (max 300) is reached; call again " \
+            "while it is still in progress. Inconclusive means not verified.",
+            TARGET_PROPERTIES.merge(
+              "until" => { "type" => "string", "enum" => %w[initial verdict], "default" => "initial" },
+              "timeout_seconds" => { "type" => "integer", "minimum" => 1, "maximum" => MAX_WAIT_SECONDS, "default" => MAX_WAIT_SECONDS }
+            )),
+          tool("list_deployments", "Recent deployments with their verification state and verdict.",
+            { "limit" => { "type" => "integer", "minimum" => 1, "maximum" => 50, "default" => 10 } }),
+          tool("get_exception", "Sanitized details and the application stack trace for an exception fingerprint.",
+            { "fingerprint" => { "type" => "string" } }, required: %w[fingerprint]),
+          tool("list_late_regressions", "Failures found after a release was cleared, on paths the clearance did not cover.",
+            { "since" => { "type" => "string", "description" => "ISO 8601 time" },
+              "limit" => { "type" => "integer", "minimum" => 1, "maximum" => 50, "default" => 10 } })
+        ]
+        if scopes.include?("deployments")
+          list << tool("register_deployment", "Register a deployment so it is verified (manual and CI deploys).",
+            { "commit" => { "type" => "string" }, "version" => { "type" => "string" },
+              "kind" => { "type" => "string", "enum" => %w[code config rollback promotion] } })
+        end
+        list
+      end
+
+      private
+        def initialize_result(requested)
+          {
+            "protocolVersion" => PROTOCOL_VERSIONS.include?(requested) ? requested : PROTOCOL_VERSIONS.first,
+            "capabilities" => { "tools" => { "listChanged" => false } },
+            "serverInfo" => { "name" => "deployangel", "version" => DeployAngel::VERSION },
+            "instructions" => INSTRUCTIONS
+          }
+        end
+
+        def call_tool(name, arguments)
+          content =
+            case name
+            when "get_verification" then waiter.wait(target(arguments), wait: false).then { |o| verification_content(o) }
+            when "wait_for_verification" then wait_content(arguments)
+            when "list_deployments" then @client.deployments(limit: arguments.fetch("limit", 10))
+            when "get_exception" then @client.exception(arguments.fetch("fingerprint") { raise ArgumentError, "fingerprint is required" })
+            when "list_late_regressions" then @client.late_regressions(since: arguments["since"], limit: arguments.fetch("limit", 10))
+            when "register_deployment"
+              raise ArgumentError, "register_deployment is not available for this token" unless scopes.include?("deployments")
+
+              @client.register_deployment(commit: arguments["commit"], version: arguments["version"], kind: arguments["kind"])
+            else raise ArgumentError, "unknown tool: #{name}"
+            end
+          { "content" => [ { "type" => "text", "text" => JSON.pretty_generate(content) } ],
+            "structuredContent" => content, "isError" => false }
+        rescue Client::Error => e
+          { "content" => [ { "type" => "text", "text" => "DeployAngel API error: #{e.message}" } ], "isError" => true }
+        end
+
+        def wait_content(arguments)
+          until_mode = arguments.fetch("until", "initial")
+          raise ArgumentError, "until must be initial or verdict" unless %w[initial verdict].include?(until_mode)
+
+          timeout = arguments.fetch("timeout_seconds", MAX_WAIT_SECONDS).to_i.clamp(1, MAX_WAIT_SECONDS)
+          verification_content(waiter.wait(target(arguments), until_mode: until_mode, timeout: timeout))
+        end
+
+        def verification_content(outcome)
+          return { "found" => false, "note" => "No matching deployment is registered yet." } if outcome.not_found
+
+          { "exit_code" => outcome.exit_code, "meaning" => meaning(outcome.exit_code),
+            "in_progress" => outcome.exit_code == VerificationWaiter::TIMED_OUT, "verification" => outcome.document }
+        end
+
+        def meaning(code)
+          {
+            0 => "verified: the release is cleared",
+            1 => "failed: production regressed",
+            2 => "inconclusive: NOT verified; do not report success",
+            3 => "still in progress; call wait_for_verification again",
+            6 => "initial check: no problems so far, NOT cleared yet",
+            7 => "initial check: warnings present, NOT cleared"
+          }.fetch(code, "unknown")
+        end
+
+        def target(arguments)
+          return { deployment_id: arguments["deployment_id"].to_s } if arguments["deployment_id"]
+          return { version: arguments["version"].to_s } if arguments["version"]
+          return { commit: arguments["commit"].to_s.downcase } if arguments["commit"]
+          return { latest: true } if arguments["latest"]
+
+          head = @git_head.call
+          head ? { commit: head.downcase } : { latest: true }
+        end
+
+        def waiter
+          VerificationWaiter.new(client: @client, sleeper: @sleeper, clock: @clock)
+        end
+
+        def scopes
+          @scopes ||= Array(@client.token_info["scopes"])
+        rescue Client::Error
+          []
+        end
+
+        def tool(name, description, properties, required: [])
+          { "name" => name, "description" => description,
+            "inputSchema" => { "type" => "object", "properties" => properties, "required" => required } }
+        end
+
+        def result(id, payload)
+          { "jsonrpc" => "2.0", "id" => id, "result" => payload }
+        end
+
+        def error_response(id, kind, message)
+          { "jsonrpc" => "2.0", "id" => id, "error" => { "code" => ERROR_CODES.fetch(kind), "message" => message } }
+        end
+    end
+  end
+end

data/lib/deployangel/rails/active_job.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  module Rails
+    # Instruments every ActiveJob adapter (Solid Queue, Sidekiq, GoodJob,
+    # ...) through ActiveSupport::Notifications.
+    #
+    # Failures handled by retry_on or discard_on never surface on the
+    # perform event, so enqueue_retry, discard, and retry_stopped mark the
+    # job while it performs. Everything is then counted exactly once when
+    # perform finishes.
+    module ActiveJob
+      STATE = :@__deployangel_job_state
+
+      module_function
+
+      def install
+        return if @installed || !defined?(::ActiveSupport::Notifications)
+
+        @installed = true
+        DeployAngel.add_capability("jobs")
+        subscribe("perform_start.active_job") { |payload| state(payload)[:queue_latency_ms] = queue_latency_ms(payload[:job]) }
+        subscribe("enqueue_retry.active_job") { |payload| state(payload).merge!(failed: true, error: payload[:error]) }
+        subscribe("discard.active_job") { |payload| state(payload).merge!(failed: true, discarded: true, error: payload[:error]) }
+        subscribe("retry_stopped.active_job") { |payload| state(payload).merge!(failed: true, discarded: true, error: payload[:error]) }
+        ::ActiveSupport::Notifications.subscribe("perform.active_job") { |event| record(event) }
+      end
+
+      def record(event)
+        return unless DeployAngel.recording?
+
+        job = event.payload[:job]
+        state = job&.instance_variable_get(STATE) || {}
+        error = event.payload[:exception_object] || state[:error]
+        DeployAngel.record_exception(error, source: "job_class:#{job.class.name}") if error
+        DeployAngel.record_job(
+          job_class: job.class.name,
+          duration_ms: event.duration,
+          failed: state[:failed] || !event.payload[:exception_object].nil?,
+          discarded: state[:discarded] || false,
+          queue_latency_ms: state[:queue_latency_ms]
+        )
+      rescue StandardError
+        nil
+      end
+
+      def subscribe(name)
+        ::ActiveSupport::Notifications.subscribe(name) do |*, payload|
+          yield payload if DeployAngel.recording? && payload[:job]
+        rescue StandardError
+          nil
+        end
+      end
+
+      def state(payload)
+        job = payload[:job]
+        job.instance_variable_get(STATE) || job.instance_variable_set(STATE, {})
+      end
+
+      # From when the job became runnable: its scheduled time, else when it
+      # was enqueued.
+      def queue_latency_ms(job)
+        runnable_at = job.scheduled_at || job.enqueued_at
+        return unless runnable_at
+
+        [ (Time.now - runnable_at) * 1000.0, 0 ].max
+      end
+    end
+  end
+end

data/lib/deployangel/rails/error_subscriber.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  module Rails
+    # Receives Rails.error reports, for handled errors only (Rails.error.handle
+    # and Rails.error.report(handled: true)), shown for context.
+    #
+    # Rails also reports unhandled request and job exceptions here, before the
+    # middleware and job instrumentation see them. Those paths record them
+    # with their route or job class, so unhandled reports are skipped here.
+    class ErrorSubscriber
+      def report(error, handled:, **)
+        DeployAngel.record_exception(error, handled: true) if handled
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/deployangel/rails/http.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  module Rails
+    # Rack middleware at the top of the stack, so it sees the final status
+    # after Rails renders exceptions. Records the matched route pattern,
+    # never the raw path, which keeps IDs out of route keys.
+    class Http
+      FORMAT_SUFFIX = "(.:format)"
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless DeployAngel.recording?
+
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          status, headers, body = @app.call(env)
+        rescue Exception => e # rubocop:disable Lint/RescueException -- recorded, then re-raised untouched
+          record(env, 500, started, unhandled: true, exception: e)
+          raise
+        end
+        # Rails renders some exceptions as 4xx (routing errors, RecordNotFound,
+        # ParameterMissing); only those that end in a 5xx count as unhandled.
+        exception = env["action_dispatch.exception"] if status.to_i >= 500
+        record(env, status, started, unhandled: !exception.nil?, exception: exception)
+        [ status, headers, body ]
+      end
+
+      private
+        def record(env, status, started, unhandled:, exception: nil)
+          route = route_key(env)
+          # Unrouted successes are static files and similar; unrouted
+          # errors (such as routing 404s) still count.
+          return if route.nil? && status.to_i < 400
+
+          key = route || "#{env["REQUEST_METHOD"]} unmatched"
+          DeployAngel.record_exception(exception, source: "route:#{key}") if exception
+          DeployAngel.record_request(
+            route_key: key,
+            status: status.to_i,
+            duration_ms: (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0,
+            unhandled: unhandled
+          )
+        rescue StandardError
+          nil
+        end
+
+        def route_key(env)
+          method = env["REQUEST_METHOD"]
+          if (pattern = route_pattern(env))
+            "#{method} #{pattern.delete_suffix(FORMAT_SUFFIX)}"
+          elsif (params = env["action_dispatch.request.path_parameters"]) && params[:controller]
+            "#{method} #{params[:controller]}##{params[:action]}"
+          end
+        end
+
+        def route_pattern(env)
+          env["action_dispatch.route_uri_pattern"] || env["action_dispatch.route"]&.path&.spec&.to_s
+        end
+    end
+  end
+end

data/lib/deployangel/rails/metadata.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "digest"
+require "erb"
+require "yaml"
+
+module DeployAngel
+  module Rails
+    # What the application contains, sent once per process: the route table,
+    # job classes, declared recurring schedules, critical flows, and file
+    # digests. Paths and hashes only; source code never leaves the
+    # application.
+    class Metadata
+      DIGEST_GLOBS = %w[app/**/* config/**/* lib/**/* db/migrate/**/* Gemfile.lock].freeze
+      MAX_FILES = 20_000
+      DIGEST_LENGTH = 16
+      FORMAT_SUFFIX = "(.:format)"
+
+      def initialize(app:, config:, root:)
+        @app = app
+        @config = config
+        @root = root
+      end
+
+      def to_protocol
+        {
+          "routes" => routes,
+          "job_classes" => job_classes,
+          "schedules" => schedules,
+          "critical_flows" => @config.critical_flows.transform_keys(&:to_s).transform_values { |items| Array(items).map(&:to_s) },
+          "file_manifest" => file_manifest.slice("hash", "count", "truncated")
+        }
+      end
+
+      def files
+        file_manifest["files"]
+      end
+
+      def routes
+        @app.routes.routes.flat_map do |route|
+          controller = route.defaults[:controller]
+          next [] if controller.nil? || controller.start_with?("rails/", "active_storage/", "action_mailbox/")
+
+          path = route.path.spec.to_s.delete_suffix(FORMAT_SUFFIX)
+          route.verb.to_s.split("|").reject(&:empty?).map do |verb|
+            { "key" => "#{verb} #{path}", "controller" => controller, "action" => route.defaults[:action].to_s }
+          end
+        end.uniq { |route| route["key"] }
+      rescue StandardError
+        []
+      end
+
+      def job_classes
+        return [] unless defined?(::ActiveJob::Base)
+
+        ::ActiveJob::Base.descendants.filter_map(&:name).reject { |name| name == "ApplicationJob" }.sort
+      rescue StandardError
+        []
+      end
+
+      # Solid Queue recurring tasks for the current environment.
+      def schedules
+        path = File.join(@root, "config", "recurring.yml")
+        return [] unless File.file?(path)
+
+        config = YAML.safe_load(ERB.new(File.read(path)).result, aliases: true) || {}
+        tasks = config.key?(::Rails.env) ? config[::Rails.env] : config
+        Array(tasks).filter_map do |key, task|
+          next unless task.is_a?(Hash) && task["schedule"]
+
+          { "key" => key.to_s, "class" => task["class"]&.to_s, "schedule" => task["schedule"].to_s, "source" => "solid_queue" }
+        end
+      rescue StandardError
+        []
+      end
+
+      def file_manifest
+        @file_manifest ||= begin
+          if @config.file_digests
+            paths = DIGEST_GLOBS.flat_map { |glob| Dir.glob(File.join(@root, glob)) }.select { |path| File.file?(path) }.sort
+            truncated = paths.size > MAX_FILES
+            files = paths.first(MAX_FILES).to_h do |path|
+              [ path.delete_prefix(@root).delete_prefix("/"), Digest::SHA256.file(path).hexdigest[0, DIGEST_LENGTH] ]
+            end
+            hash = Digest::SHA256.hexdigest(files.map { |path, digest| "#{path}:#{digest}" }.join("\n"))
+            { "hash" => hash, "count" => files.size, "truncated" => truncated, "files" => files }
+          else
+            { "hash" => nil, "count" => 0, "truncated" => false, "files" => {} }
+          end
+        end
+      rescue StandardError
+        { "hash" => nil, "count" => 0, "truncated" => false, "files" => {} }
+      end
+    end
+  end
+end

data/lib/deployangel/rails/railtie.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module DeployAngel
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "deployangel.middleware" do |app|
+        app.config.middleware.insert(0, DeployAngel::Rails::Http)
+      end
+
+      initializer "deployangel.jobs" do
+        ActiveSupport.on_load(:active_job) { DeployAngel::Rails::ActiveJob.install }
+        DeployAngel::Sidekiq.install
+      end
+
+      # Handled reports (Rails.error.handle / Rails.error.report) are shown for
+      # context; only unhandled exceptions count toward verdicts.
+      initializer "deployangel.error_reporter" do |app|
+        app.executor.error_reporter&.subscribe(DeployAngel::Rails::ErrorSubscriber.new) if app.executor.respond_to?(:error_reporter)
+      end
+
+      config.after_initialize do |app|
+        agent = DeployAngel.start(
+          environment: ::Rails.env,
+          root: ::Rails.root.to_s,
+          framework: "rails",
+          framework_version: ::Rails.version,
+          logger: ::Rails.logger
+        )
+        agent&.metadata = DeployAngel::Rails::Metadata.new(app: app, config: DeployAngel.configuration, root: ::Rails.root.to_s)
+      end
+    end
+  end
+end

data/lib/deployangel/sidekiq.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  # Server middleware for native Sidekiq jobs (Sidekiq::Job without
+  # ActiveJob). ActiveJob jobs on Sidekiq are recorded by the ActiveJob
+  # instrumentation instead, so they are skipped here to avoid double counts.
+  module Sidekiq
+    ACTIVE_JOB_WRAPPERS = %w[
+      Sidekiq::ActiveJob::Wrapper
+      ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper
+    ].freeze
+
+    class ServerMiddleware
+      def call(_job_instance, job, _queue)
+        return yield if ACTIVE_JOB_WRAPPERS.include?(job["class"]) || !DeployAngel.recording?
+
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        latency = DeployAngel::Sidekiq.queue_latency_ms(job)
+        begin
+          yield
+        rescue Exception => e # rubocop:disable Lint/RescueException -- recorded, then re-raised untouched
+          DeployAngel.record_exception(e, source: "job_class:#{job["class"]}")
+          record(job, started, latency, failed: true)
+          raise
+        end
+        record(job, started, latency, failed: false)
+      end
+
+      private
+        def record(job, started, latency, failed:)
+          DeployAngel.record_job(job_class: job["class"], failed: failed, queue_latency_ms: latency,
+            duration_ms: (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0)
+        rescue StandardError
+          nil
+        end
+    end
+
+    module_function
+
+    def install
+      return if @installed || !defined?(::Sidekiq) || !::Sidekiq.respond_to?(:configure_server)
+
+      @installed = true
+      DeployAngel.add_capability("jobs")
+      ::Sidekiq.configure_server do |config|
+        config.server_middleware { |chain| chain.add(ServerMiddleware) }
+        # Jobs that exhausted their retries are discarded.
+        config.death_handlers << ->(job, _error) { record_death(job) } if config.respond_to?(:death_handlers)
+      end
+    end
+
+    # A dead job was already counted as a failed attempt by the middleware;
+    # this only records that it will not run again.
+    def record_death(job)
+      return if ACTIVE_JOB_WRAPPERS.include?(job["class"]) || !DeployAngel.agent
+
+      DeployAngel.agent.record_discard(job_class: job["class"])
+    rescue StandardError
+      nil
+    end
+
+    # Sidekiq 8 stores epoch milliseconds; earlier versions store seconds.
+    def queue_latency_ms(job)
+      enqueued = job["enqueued_at"]
+      return unless enqueued.is_a?(Numeric)
+
+      enqueued_ms = enqueued > 100_000_000_000 ? enqueued : enqueued * 1000.0
+      [ (Time.now.to_f * 1000.0) - enqueued_ms, 0 ].max
+    end
+  end
+end

data/lib/deployangel/verification_waiter.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  # Finds a deployment and polls its verdict document until the requested
+  # point: the 15-minute initial check, a verdict, or the end of watching.
+  # Shared by the CLI and the MCP server.
+  class VerificationWaiter
+    Outcome = Struct.new(:document, :exit_code, :timed_out, :not_found, keyword_init: true)
+
+    # Exit codes are the primary signal for agents and CI.
+    EXIT_CODES = { "verified" => 0, "failed" => 1, "inconclusive" => 2 }.freeze
+    TIMED_OUT = 3
+    NOT_FOUND = 4
+    INITIAL_OK = 6
+    INITIAL_WARNINGS = 7
+    UNTIL_MODES = %w[initial verdict closed].freeze
+    PENDING_POLL = 15
+
+    def initialize(client:, sleeper: ->(seconds) { sleep(seconds) }, clock: -> { Time.now }, on_progress: nil)
+      @client = client
+      @sleeper = sleeper
+      @clock = clock
+      @on_progress = on_progress
+    end
+
+    # target: { deployment_id: } | { version: } | { commit: } | { latest: true }
+    def wait(target, until_mode: "verdict", timeout: 1800, wait: true)
+      deadline = @clock.call + timeout
+      last_state = nil
+      loop do
+        deployment = find(target)
+        if deployment.nil?
+          return Outcome.new(not_found: true, exit_code: NOT_FOUND) if !wait || @clock.call >= deadline
+
+          progress("Waiting for deployment #{describe(target)} to be registered…") unless last_state == :pending_registration
+          last_state = :pending_registration
+          @sleeper.call([ PENDING_POLL, deadline - @clock.call ].min.clamp(1, PENDING_POLL))
+          next
+        end
+
+        document = @client.verification(deployment["id"])
+        state = document.dig("verification", "state")
+        progress("#{document.dig("deployment", "version") || document.dig("deployment", "commit")}: #{state}") if state != last_state
+        last_state = state
+
+        code = self.class.exit_code(document, until_mode)
+        return Outcome.new(document: document, exit_code: code) if code
+        return Outcome.new(document: document, exit_code: TIMED_OUT) unless wait
+        return Outcome.new(document: document, exit_code: TIMED_OUT, timed_out: true) if @clock.call >= deadline
+
+        poll = (document["poll_after_seconds"] || 30).to_i.clamp(5, 60)
+        @sleeper.call([ poll, deadline - @clock.call ].min.clamp(1, 60))
+      end
+    end
+
+    # nil means "keep waiting". Failed always returns immediately.
+    def self.exit_code(document, until_mode)
+      verification = document["verification"] || {}
+      verdict = verification["verdict"]
+      return EXIT_CODES["failed"] if verdict == "failed"
+
+      case until_mode
+      when "closed"
+        EXIT_CODES[verdict] if verdict && verification["state"] == "closed"
+      when "initial"
+        if verdict
+          EXIT_CODES[verdict]
+        elsif (check = verification["initial_check"])
+          check["result"] == "warnings" ? INITIAL_WARNINGS : INITIAL_OK
+        end
+      else
+        EXIT_CODES[verdict] if verdict
+      end
+    end
+
+    private
+      def find(target)
+        if target[:deployment_id]
+          { "id" => target[:deployment_id] }
+        elsif target[:latest]
+          @client.latest_deployment
+        else
+          @client.deployments(commit: target[:commit], version: target[:version], limit: 1).first
+        end
+      rescue Client::NotFound
+        nil
+      end
+
+      def describe(target)
+        target[:version] || target[:commit]&.slice(0, 12) || target[:deployment_id] || "latest"
+      end
+
+      def progress(message)
+        @on_progress&.call(message)
+      end
+  end
+end

data/lib/deployangel/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  VERSION = "0.1.0"
+end