deployangel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b1740b8bdbebb7cf89db6fe0a93eb1e09f3452492c88ee0d13bac1d6060e6778
+  data.tar.gz: 95bf36dc26fdf153a4783172dd3296a92e004f0109068ade65716d46ffa18590
+SHA512:
+  metadata.gz: fc6ba275f576aa06da811002891c7d158008fc729462c3c6cec9a30792a62f891469cffb41e8a9538cf863611d348d94c451d6735c41a9b9a0c63fb2fee692ac
+  data.tar.gz: 6a85b7eef1c4989d5dcab0790d226e21a9acaee7a5c40592d11c1608eb5f5bef06452dcd01ae41e988d91ce9a6d6a475c0d32bc74051ecf23a18d4346ea002ec

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.1.0 (2026-10-01)
+
+- Release identity on Kamal (`KAMAL_VERSION`), Render (`RENDER_GIT_COMMIT`),
+  Fly.io (the deploy's image tag), Railway (`RAILWAY_GIT_COMMIT_SHA`, or the
+  deployment ID), Coolify (`SOURCE_COMMIT`), and Dokku (`GIT_REV`), with no
+  configuration. Kamal versions with
+  uncommitted changes report the version and the commit it starts with.
+- `deployangel release` registers Kamal's release inside a Kamal hook, and
+  `deployangel install kamal` adds a `post-deploy` hook that does it.
+
+- HTTP request telemetry for Rails: request counts, 4xx/5xx status counts,
+  unhandled exceptions, and mergeable latency histograms, per route.
+- Release identity from configuration, Heroku dyno metadata, or a REVISION file.
+- One payload per process per minute (heartbeats included), sent from a
+  background thread; fails open, bounded buffering, fork-safe.
+- Background jobs: attempts, failures, discards, duration, and queue latency
+  per job class, for every ActiveJob adapter (Solid Queue, Sidekiq, GoodJob,
+  ...) and for native Sidekiq jobs. Failures handled by `retry_on` and
+  `discard_on` are counted exactly once.
+- Exceptions: stable fingerprints (algorithm v1: class plus top application
+  frame, with no line numbers, messages, or gem versions), sanitized messages,
+  and application-only representative backtraces, tagged with the route or
+  job class they came from. Handled `Rails.error` reports are included for
+  context.
+- Application metadata, once per process: route table, job classes, Solid
+  Queue recurring schedules, critical flows, and file digests (paths and
+  short hashes only; uploaded only when the cloud has not seen the manifest).
+- Defaults to `https://api.deployangel.com`.
+- `deployangel` CLI (`verify`, `status`, `release`, `check`, `exception`) with
+  stable exit codes for coding agents and CI, and `deployangel mcp`, a stdio
+  MCP server.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jordan Owens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,293 @@
+# DeployAngel for Rails
+
+The DeployAngel agent. It watches what your Rails app does in production and
+reports one small aggregated payload per process per minute. DeployAngel uses
+that to verify every deployment, and to tell you (or your coding agent) when a
+release is **cleared** and you can stop watching it.
+
+## Install
+
+Requires Ruby 3.1 or later and Rails 7.1 or later.
+
+```ruby
+# Gemfile
+gem "deployangel"
+```
+
+Set these in production:
+
+```bash
+DEPLOYANGEL_TOKEN=da_live_...           # an ingestion token with the telemetry scope
+```
+
+The agent must know which release it is running. It finds it in this order:
+
+1. `DEPLOYANGEL_REVISION` (the commit SHA) and `DEPLOYANGEL_RELEASE_VERSION`, if you set them
+2. Heroku dyno metadata. Enable it with `heroku labs:enable runtime-dyno-metadata`
+3. Kamal: `KAMAL_VERSION`, which Kamal sets in every container
+4. Render: `RENDER_GIT_COMMIT`
+5. Fly.io: the deploy's image tag, from `FLY_IMAGE_REF`. Fly.io sets no commit, so
+   pass one in for commit-level change tracking:
+   `fly deploy --build-arg GIT_SHA=$(git rev-parse HEAD)`, with `ARG GIT_SHA` and
+   `ENV DEPLOYANGEL_REVISION=$GIT_SHA` in the Dockerfile
+6. Railway: `RAILWAY_GIT_COMMIT_SHA`, or `RAILWAY_DEPLOYMENT_ID` for deploys that
+   didn't come from GitHub
+7. Coolify: `SOURCE_COMMIT`. Dokku: `GIT_REV`
+8. a `REVISION` file in the app root, which Capistrano writes and any build step can
+
+For other Docker deploys (compose, Swarm, ECS, Kubernetes), bake the commit into
+the image, since `.dockerignore` usually leaves `.git` out:
+
+```dockerfile
+ARG GIT_SHA
+ENV DEPLOYANGEL_REVISION=$GIT_SHA
+```
+
+and build with `docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .`. On
+DigitalOcean App Platform, set `DEPLOYANGEL_REVISION: ${_self.COMMIT_HASH}` in
+the app spec. If the agent finds none of these, its telemetry can't be tied to a
+deploy, and the dashboard says so.
+
+## What it sends
+
+- HTTP request counts, 4xx/5xx counts by status code, unhandled exceptions,
+  and a latency histogram, both per app and per route.
+- Routes are recorded as the matched pattern (`GET /users/:id`), never the raw
+  path. At most 100 routes are sent per payload; the rest are folded into
+  `__other__`.
+- Background jobs: attempts, failed attempts, discarded jobs, duration, and
+  queue latency, per job class. Works with every ActiveJob adapter (Solid
+  Queue, Sidekiq, GoodJob, ...) and with native Sidekiq jobs through a server
+  middleware. Failures that `retry_on` or `discard_on` handle still count.
+- Release identity, runtime versions, and a per-process instance ID.
+
+- Exceptions: a stable fingerprint, the exception class, a sanitized message
+  (numbers, IDs, emails, and quoted values removed), and application frames
+  only.
+- Once per process: the route table, job classes, Solid Queue recurring
+  schedules, critical flows, and file digests (relative paths and hashes, never
+  file contents) so DeployAngel can tell which routes changed in a release.
+  Disable digests with `DEPLOYANGEL_FILE_DIGESTS=false`.
+
+It does not send request bodies, parameters, headers, cookies, SQL, logs, or
+user data.
+
+## Safety
+
+- Nothing runs on the network during a request. Requests only update
+  in-memory counters.
+- Payloads are sent from a background thread, once a minute, with short
+  timeouts.
+- When DeployAngel is unreachable, the buffer is bounded (10 payloads) and the
+  oldest are dropped. Your app is never blocked or failed.
+- Safe across forks (Puma cluster mode and similar), and the minute in progress
+  is flushed at shutdown.
+
+## Configuration
+
+Environment variables are enough for most apps. To override in code:
+
+```ruby
+# config/initializers/deployangel.rb
+DeployAngel.configure do |config|
+  config.environments = %w[production staging] # default: production only
+end
+```
+
+Critical flows (for example sign-up or password reset) are always listed in
+clearance reports:
+
+```ruby
+DeployAngel.configure do |config|
+  config.critical_flows = { "password_reset" => [ "POST /password_resets", "job:PasswordsMailer" ] }
+end
+```
+
+`DEPLOYANGEL_ENABLED=true|false` forces reporting on or off in any environment.
+`DEPLOYANGEL_URL` overrides the API endpoint (default `https://api.deployangel.com`).
+
+## Checkpoints
+
+Errors and latency don't catch work that silently stops happening. Count the
+business events that matter with one line:
+
+```ruby
+DeployAngel.checkpoint("order.created")
+DeployAngel.checkpoint("receipt.sent")
+DeployAngel.checkpoint("webhook.stripe.processed", count: events.size)
+```
+
+DeployAngel learns each checkpoint's normal rate relative to your traffic and
+fails a release after which it drops sharply or stops, even when every request
+and job still succeeds. Only drops are flagged, and a checkpoint without enough
+traffic never blocks a release from being cleared. Checkpoints can also be part
+of a critical flow (`checkpoint:order.created`).
+
+It's safe to call anywhere: it never raises, never touches the network, and is
+ignored outside reporting environments. Names use letters, numbers, and
+`. _ : -` (up to 100 characters); keep them to a fixed set rather than
+including IDs, since only 100 distinct names are counted per minute.
+
+## Registering deploys
+
+On Heroku, the add-on registers every release for you. Anywhere else,
+DeployAngel notices a new release when the agent first reports it, and verifies
+it from there. The releases running when you install the agent are the baseline.
+
+Registering deploys yourself adds a link to the CI run and a label of your
+choice, and starts verification as soon as the deploy finishes. Use an API
+token created for **CI deploys** in the dashboard (`DEPLOYANGEL_API_TOKEN`):
+
+```bash
+bundle exec deployangel release --commit=$GIT_SHA [--version=LABEL]
+```
+
+`--version` is an optional label for the dashboard (a tag, build number, or
+date). Without it, releases are labelled by their short commit.
+
+In GitHub Actions, GitLab CI, CircleCI, and Buildkite, `deployangel release`
+needs no arguments: it uses the CI's commit, labels the release with the build
+number (`run-123`, `pipeline-45`, `build-67`), and links the release page back
+to the run. Explicit options still win.
+
+```yaml
+# .github/workflows/deploy.yml, after the deploy step
+- run: bundle exec deployangel release
+  env:
+    DEPLOYANGEL_API_TOKEN: ${{ secrets.DEPLOYANGEL_API_TOKEN }}
+- run: bundle exec deployangel verify --wait --until=initial   # optional: fail the job on a bad release
+  env:
+    DEPLOYANGEL_API_TOKEN: ${{ secrets.DEPLOYANGEL_API_TOKEN }}
+```
+
+### Deploying with Kamal
+
+The agent reads `KAMAL_VERSION`, so it knows its release with no setup. Pass
+the agent's token to the app through Kamal's secrets:
+
+```yaml
+# config/deploy.yml
+env:
+  secret:
+    - DEPLOYANGEL_TOKEN
+```
+
+with `DEPLOYANGEL_TOKEN=$DEPLOYANGEL_TOKEN` in `.kamal/secrets`. To register each
+deploy, add a post-deploy hook:
+
+```bash
+bundle exec deployangel install kamal
+```
+
+It writes `.kamal/hooks/post-deploy`, which runs `deployangel release` after each
+`kamal deploy` (or adds nothing if you already have a hook, and prints the line
+to add). Set `DEPLOYANGEL_API_TOKEN` (a CI deploys token) wherever you run
+`kamal deploy`. The hook never fails a deploy.
+
+### Deploying with Capistrano
+
+Capistrano writes a `REVISION` file into each release, so the agent already
+knows which commit it's running. Add one line to the `Capfile` to register
+each deploy:
+
+```ruby
+# Capfile
+require "deployangel/capistrano"
+```
+
+and set `DEPLOYANGEL_API_TOKEN` (a CI deploys token) wherever you run
+`cap production deploy`. After each deploy is published, the release is
+registered with its commit, labelled with Capistrano's release timestamp.
+If DeployAngel can't be reached, the deploy continues with a warning.
+
+Optional settings in `config/deploy.rb`:
+
+```ruby
+set :deployangel_wait, "initial"      # wait for the initial check after deploying
+set :deployangel_wait_timeout, "15m"
+set :deployangel_version, nil         # label releases by commit instead of timestamp
+set :deployangel_register, false      # turn it off, e.g. for a stage without DeployAngel
+```
+
+With `:deployangel_wait`, `cap` exits with an error if the release fails
+verification, which CI can act on. It never rolls anything back.
+
+## CLI and coding agents
+
+The gem ships a `deployangel` command. It doesn't boot Rails. Give it a token
+with the `verifications:read` scope (plus `deployments` to register deploys or
+report checks). Never use the production telemetry token on a developer
+machine.
+
+```bash
+export DEPLOYANGEL_API_TOKEN=da_live_...
+
+bundle exec deployangel verify --wait                  # current git HEAD, until a verdict
+bundle exec deployangel verify --wait --until=initial  # return at the 15-minute initial check
+bundle exec deployangel status                         # latest deployment
+bundle exec deployangel release --commit=$SHA          # register a deploy (manual or CI)
+bundle exec deployangel check --name="smoke: signup" --status=pass --covers=registration
+bundle exec deployangel exception <fingerprint>
+```
+
+Output is text on a terminal and JSON (the verdict document) when piped, or
+choose with `--format=text|json`. Exit codes:
+
+| Code | Meaning |
+|---|---|
+| 0 | verified (cleared) |
+| 1 | failed |
+| 2 | inconclusive (not verified) |
+| 3 | still in progress, or timed out |
+| 4 | deployment not found |
+| 5 | usage, authentication, or network error |
+| 6 | initial check: no problems so far, **not cleared** |
+| 7 | initial check: warnings, **not cleared** |
+
+### MCP server
+
+```bash
+claude mcp add deployangel -- bundle exec deployangel mcp
+```
+
+Tools: `get_verification`, `wait_for_verification` (up to 5 minutes per call),
+`list_deployments`, `get_exception`, `list_late_regressions`, and
+`register_deployment` when the token allows it. The tools are read-only with
+respect to production.
+
+### Suggested instructions for your coding agent
+
+Add this to your `CLAUDE.md` or `AGENTS.md`:
+
+```markdown
+## Production verification
+
+After deploying, run `bundle exec deployangel verify --wait --until initial`
+(or call the `wait_for_verification` MCP tool with `until: "initial"`).
+
+- Exit 0 / verified: the release is cleared. Report the clearance line and
+  anything DeployAngel is still watching, then move on.
+- Exit 6: no problems so far, but NOT cleared. Report "no problems so far, not
+  yet cleared" and the expected clearance time. DeployAngel keeps verifying and
+  alerts on failure.
+- Exit 7: warnings at the initial check. Report them and review the findings.
+  The release is NOT cleared.
+- Exit 2 / inconclusive: the release is NOT verified. Do not claim success.
+- Exit 1 / failed: read the findings and exceptions, investigate the likely
+  cause, and propose a fix. Do not roll back or change production without
+  explicit approval.
+- Exit 3: still verifying; run the command again.
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+The agent speaks DeployAngel Agent Protocol v1: one gzipped JSON payload per
+process per minute to `POST /api/v1/telemetry`, and the application's metadata
+once per process to `POST /api/v1/application_metadata`.
+`lib/deployangel/core/protocol.rb` and `lib/deployangel/rails/metadata.rb`
+build them.

data/exe/deployangel

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/deployangel/cli"
+
+exit DeployAngel::CLI.new(ARGV).run

data/lib/deployangel/agent.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  # The per-process runtime: records requests into the aggregator and sends
+  # completed minutes from a background thread. Every public method fails
+  # open; nothing here may raise into, or block, the customer's app.
+  class Agent
+    TELEMETRY_PATH = "/api/v1/telemetry"
+    METADATA_PATH = "/api/v1/application_metadata"
+    SHUTDOWN_TIMEOUT = 2
+    DEFAULT_PAUSE = 60
+
+    attr_reader :config, :release, :instance
+    attr_writer :metadata
+
+    def initialize(config:, environment:, root: nil, framework: nil, framework_version: nil,
+                   env: ENV, transport: nil, clock: -> { Time.now.utc }, eager: false)
+      @config = config
+      @active = config.active?(environment)
+      @release = Release.resolve(config: config, env: env, root: root)
+      @runtime = Protocol.runtime(framework: framework, framework_version: framework_version)
+      @transport = transport || Transport.new(config)
+      @env = env
+      @root = root
+      @clock = clock
+      @eager = eager
+      @thread_mutex = Mutex.new
+      @warned = {}
+      reset_process_state
+      warn_once(:unknown_release, "DeployAngel could not determine the release; set DEPLOYANGEL_REVISION " \
+        "or enable Heroku dyno metadata. Telemetry will not be attributed to deployments.") if @active && @release.unknown?
+      start_reporter if @active && eager
+    end
+
+    def active?
+      @active
+    end
+
+    def record_request(route_key:, status:, duration_ms:, unhandled: false)
+      return unless @active
+
+      after_fork! if Process.pid != @pid
+      start_reporter
+      @aggregator.record(route_key: route_key, status: status, duration_ms: duration_ms, unhandled: unhandled)
+    rescue StandardError => e
+      warn_once(:record, "DeployAngel failed to record a request: #{e.class}: #{e.message}")
+    end
+
+    def record_job(job_class:, duration_ms:, failed: false, discarded: false, queue_latency_ms: nil)
+      return unless @active
+
+      after_fork! if Process.pid != @pid
+      start_reporter
+      @aggregator.record_job(job_class: job_class, duration_ms: duration_ms, failed: failed,
+        discarded: discarded, queue_latency_ms: queue_latency_ms)
+    rescue StandardError => e
+      warn_once(:record_job, "DeployAngel failed to record a job: #{e.class}: #{e.message}")
+    end
+
+    def record_discard(job_class:)
+      return unless @active
+
+      @aggregator.record_discard(job_class: job_class)
+    rescue StandardError => e
+      warn_once(:record_discard, "DeployAngel failed to record a discarded job: #{e.class}: #{e.message}")
+    end
+
+    def record_checkpoint(name, count: 1)
+      return unless @active
+
+      after_fork! if Process.pid != @pid
+      start_reporter
+      @aggregator.record_checkpoint(name: name, count: count)
+    rescue StandardError => e
+      warn_once(:record_checkpoint, "DeployAngel failed to record a checkpoint: #{e.class}: #{e.message}")
+    end
+
+    SEEN = :@__deployangel_recorded
+
+    # Records each exception object once, whichever instrumentation sees it
+    # first (middleware, job events, or Rails.error).
+    def record_exception(exception, source: nil, handled: false)
+      return unless @active && exception.is_a?(Exception)
+      return if exception.instance_variable_defined?(SEEN)
+
+      exception.instance_variable_set(SEEN, true) unless exception.frozen?
+      start_reporter
+      @aggregator.record_exception(Fingerprint.for(exception, root: @root), source: source, handled: handled,
+        backtrace: Fingerprint.backtrace(exception, root: @root))
+    rescue StandardError => e
+      warn_once(:record_exception, "DeployAngel failed to record an exception: #{e.class}: #{e.message}")
+    end
+
+    # Signals this process can observe, announced in every payload so the
+    # cloud never claims to verify what the agent cannot see.
+    def capabilities
+      DeployAngel.capabilities
+    end
+
+    # Drains completed minutes into the buffer and sends what it can.
+    def flush(include_current: false)
+      return 0 unless @active
+
+      @aggregator.drain(include_current: include_current, max_periods: config.max_queued_payloads).each do |period|
+        @buffer.push(Protocol.telemetry(period, instance: @instance, release: @release, runtime: @runtime,
+          capabilities: capabilities))
+      end
+      send_buffered
+    rescue StandardError => e
+      warn_once(:flush, "DeployAngel failed to flush telemetry: #{e.class}: #{e.message}")
+      0
+    end
+
+    def start_reporter
+      return unless @active
+      return if @thread&.alive?
+
+      @thread_mutex.synchronize do
+        return if @thread&.alive?
+
+        @stopping = false
+        @thread = Thread.new { run_reporter }
+        @thread.name = "deployangel-reporter"
+        @thread.report_on_exception = false
+      end
+    end
+
+    # Sends the in-progress minute too, bounded by a short timeout, because
+    # deployments restart processes.
+    def shutdown(timeout: SHUTDOWN_TIMEOUT)
+      return unless @active
+
+      @stopping = true
+      @thread&.wakeup if @thread&.alive?
+      finisher = Thread.new { flush(include_current: true) }
+      finisher.join(timeout)
+    rescue StandardError
+      nil
+    end
+
+    # Threads do not survive fork, and the parent's identity and counts must
+    # not be reused by the child.
+    def after_fork!
+      reset_process_state
+      start_reporter if @active && @eager
+    end
+
+    # Sent once per process; retried on the next minute if it fails. File
+    # digests are only uploaded when the cloud has not seen the manifest.
+    def send_metadata
+      return if @metadata_sent || @metadata.nil? || paused?
+
+      base = { "protocol_version" => Protocol::VERSION, "instance" => @instance.to_protocol,
+               "release" => @release.to_protocol, "runtime" => @runtime }.merge(@metadata.to_protocol)
+      result = @transport.post(METADATA_PATH, base)
+      return unless result.ok?
+
+      if result.body.is_a?(Hash) && result.body["manifest_needed"]
+        return unless @transport.post(METADATA_PATH, base.merge("files" => @metadata.files)).ok?
+      end
+      @metadata_sent = true
+    rescue StandardError => e
+      warn_once(:metadata, "DeployAngel failed to send application metadata: #{e.class}: #{e.message}")
+    end
+
+    private
+      def reset_process_state
+        @pid = Process.pid
+        @instance = Instance.new(env: @env, now: @clock.call)
+        @aggregator = Aggregator.new(max_routes: config.max_routes, clock: @clock)
+        @buffer = Buffer.new(config.max_queued_payloads)
+        @paused_until = nil
+        @metadata_sent = false
+        @thread = nil
+        # Spread processes across the first seconds of each minute.
+        @jitter = rand(1.0..10.0)
+      end
+
+      def run_reporter
+        until @stopping
+          sleep(seconds_until_next_flush)
+          break if @stopping
+
+          send_metadata
+          flush
+        end
+      rescue StandardError => e
+        warn_once(:reporter, "DeployAngel reporter stopped: #{e.class}: #{e.message}")
+      end
+
+      def seconds_until_next_flush
+        now = @clock.call.to_f
+        interval = config.flush_interval
+        (interval - (now % interval)) + @jitter
+      end
+
+      def send_buffered
+        sent = 0
+        while (payload = @buffer.shift)
+          if paused?
+            @buffer.unshift(payload)
+            break
+          end
+
+          result = @transport.post(TELEMETRY_PATH, payload)
+          case result.outcome
+          when :ok
+            sent += 1
+          when :retry
+            @buffer.unshift(payload)
+            break
+          else
+            handle_rejection(result)
+          end
+        end
+        sent
+      end
+
+      def handle_rejection(result)
+        case result.status
+        when 429
+          @paused_until = @clock.call + (result.retry_after.to_i.positive? ? result.retry_after : DEFAULT_PAUSE)
+        when 401, 403
+          warn_once(:auth, "DeployAngel rejected the token (HTTP #{result.status}); check DEPLOYANGEL_TOKEN " \
+            "and that it has the telemetry scope.")
+        else
+          warn_once(:"rejected_#{result.status}", "DeployAngel rejected a telemetry payload (HTTP #{result.status}).")
+        end
+      end
+
+      def paused?
+        @paused_until && @clock.call < @paused_until
+      end
+
+      def warn_once(key, message)
+        return if @warned[key]
+
+        @warned[key] = true
+        config.logger&.warn(message)
+      end
+  end
+end

data/lib/deployangel/capistrano/steps.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../cli"
+
+module DeployAngel
+  module Capistrano
+    # What the Capistrano tasks do, kept free of Capistrano so it can be
+    # tested on its own. Each step runs the CLI in-process and returns
+    # [outcome, message], where outcome is :ok, :warn, or :fail.
+    module Steps
+      # Exit codes that let a deploy continue for each --until mode.
+      PASSING = { "initial" => [ 0, 6 ], "verdict" => [ 0 ], "closed" => [ 0 ] }.freeze
+      # Not a pass, but not a reason to fail the deploy either: warnings at
+      # the initial check, not cleared, or still in progress.
+      WARNING = [ 2, 3, 7 ].freeze
+
+      module_function
+
+      # Registration never fails a deploy: DeployAngel being unreachable or
+      # misconfigured shouldn't stop a release from shipping.
+      def register(token:, commit:, version: nil, endpoint: nil, output: StringIO.new, **cli)
+        return [ :warn, "DeployAngel: DEPLOYANGEL_API_TOKEN is not set; release not registered" ] if blank?(token)
+        return [ :warn, "DeployAngel: no commit for this release; not registered" ] if blank?(commit)
+
+        argv = [ "release", "--commit=#{commit}", "--provider=capistrano" ]
+        argv << "--version=#{version}" unless blank?(version)
+        code = run(argv, token: token, endpoint: endpoint, output: output, **cli)
+        code.zero? ? [ :ok, output.string.strip ] : [ :warn, "DeployAngel: could not register the release (exit #{code}): #{output.string.strip}" ]
+      end
+
+      # Waits for the release's verification. Fails the deploy only when
+      # DeployAngel found a problem (exit 1).
+      def verify(token:, commit:, until_mode:, timeout:, endpoint: nil, output: StringIO.new, **cli)
+        return [ :warn, "DeployAngel: DEPLOYANGEL_API_TOKEN is not set; not waiting for a verdict" ] if blank?(token)
+
+        argv = [ "verify", "--commit=#{commit}", "--wait", "--until=#{until_mode}", "--timeout=#{timeout}", "--format=text" ]
+        code = run(argv, token: token, endpoint: endpoint, output: output, **cli)
+        summary = output.string.strip
+        if PASSING.fetch(until_mode, [ 0 ]).include?(code)
+          [ :ok, summary ]
+        elsif WARNING.include?(code) || code != 1
+          [ :warn, "DeployAngel: #{summary}" ]
+        else
+          [ :fail, "DeployAngel: release failed verification\n#{summary}" ]
+        end
+      end
+
+      # cli: options passed through to DeployAngel::CLI (tests inject a client).
+      def run(argv, token:, endpoint:, output:, **cli)
+        env = { "DEPLOYANGEL_API_TOKEN" => token }
+        env["DEPLOYANGEL_URL"] = endpoint unless blank?(endpoint)
+        DeployAngel::CLI.new(argv, env: env, stdout: output, stderr: output, **cli).run
+      end
+
+      def blank?(value)
+        value.to_s.strip.empty?
+      end
+    end
+  end
+end