deployangel 0.1.13 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d88c16de71d5010f445a966a6eea5701d96cc84aa3017df5fc362152331dd4e
-  data.tar.gz: a6df4ed365874fefe0708bf3cc5e482074b7f1f148f5bfe0aa25a7de2f44ed58
+  metadata.gz: fae02d0fd8337fc6eb82ef0492d1bab86d03071dd9c9774dc332e95a6f52ffc9
+  data.tar.gz: 733fce2015cfa6e8fd6f5c618005cdda6c5aabf6aae8d7be128a156c46be65a6
 SHA512:
-  metadata.gz: 2486f4bf45d20d65bc01bd3f89881e5def3ea9cbef692c4a87e0af631bccbb7ece176ad30c41040c8b57ac46b8635d8cc8d8625ac92eb503e0531086f4caefee
-  data.tar.gz: 19a7a768889a541fc9f7688e3999947440ade5f747cfe6d8726211eb9536f9700369855896e31d8d0fe4091c35ee2559381d9329f78dd303be21e1a87964ddba
+  metadata.gz: db2bd88f8bb149df827631c8a44453c8a328c790b6174a370d39469c1e025055bfb5923c70f52984b8a1a6f2e702e79a17c600f176375dc053f31c390f7ebae8
+  data.tar.gz: 2e33938b4d09aa6bd342300e2097ad7a10fe8a3a722296acd5e06a6e5fc9f39a9c6f16364907abb159dcfe02c95f659e0df5096e3c51f9334240b1cce50f0faa

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.15 (2026-10-06)
+
+- Checkpoints report whether they were recorded in an HTTP request or a job
+  (`http` and `job` counts on each checkpoint), so DeployAngel compares a
+  checkpoint recorded in jobs against job traffic rather than requests. A job
+  performed inline during a request counts as a job. Needs a DeployAngel
+  server that reads the new fields; older servers ignore them.
+
+## 0.1.14 (2026-10-06)
+
+- `deployangel plan` separates what clearance waits on ("Needed to clear")
+  from changed and rarely used paths that are only worth running, and
+  `deployangel verify` and the GitHub Actions job summary list only what's
+  needed. The MCP tool `get_exercise_plan` describes the server's new
+  `needed` flag on each item.
+
 ## 0.1.13 (2026-10-06)
 
 - The MCP tools `list_deployments` and `list_late_regressions` return their

data/README.md

@@ -207,6 +207,10 @@ 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`).
 
+The agent also records whether each checkpoint was counted during an HTTP
+request or a background job, so DeployAngel compares it against the right
+traffic: a checkpoint counted in jobs is judged against jobs, not requests.
+
 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
@@ -413,7 +417,8 @@ A quiet app can take hours to clear a release. `deployangel plan` (or the
 clearance, in the numbers of the rule it's judged by, and what to exercise
 against production so it clears sooner: normally active routes short of
 their runs, routes this release changed that haven't run, and critical
-flows. Requests to them count like any traffic. Routes that change data
+flows. It separates what clearance waits on from changed and rarely used
+paths that are only worth running. Requests to them count like any traffic. Routes that change data
 are marked; use a test account for them, or ask first. Report what you
 ran with the `deployangel check` command the plan gives you. A passing
 check labels what it covered; only the requests themselves count as

data/lib/deployangel/agent.rb

@@ -71,12 +71,14 @@ module DeployAngel
       warn_once(:record_discard, "DeployAngel failed to record a discarded job: #{e.class}: #{e.message}")
     end
 
-    def record_checkpoint(name, count: 1)
+    # context defaults to the unit of work this fiber is running: an HTTP
+    # request, a job, or neither.
+    def record_checkpoint(name, count: 1, context: ExecutionContext.current)
       return unless @active
 
       after_fork! if Process.pid != @pid
       start_reporter
-      @aggregator.record_checkpoint(name: name, count: count)
+      @aggregator.record_checkpoint(name: name, count: count, context: context)
     rescue StandardError => e
       warn_once(:record_checkpoint, "DeployAngel failed to record a checkpoint: #{e.class}: #{e.message}")
     end

data/lib/deployangel/cli/formatter.rb

@@ -122,18 +122,37 @@ module DeployAngel
           shortfall.each { |line| lines << "  #{line}" }
         end
         items = Array(plan["items"])
-        if items.any?
-          lines << (EXERCISABLE.include?(plan["status"]) ? "Exercise against production:" : "Optional:")
-          items.each { |item| lines << "  #{item_line(item)}" }
-          lines << "Use a test account, or ask first, for routes marked [changes data]." if items.any? { |item| item["mutating"] }
+        if EXERCISABLE.include?(plan["status"])
+          needed, extra = items.partition { |item| needed?(item) }
+          item_group(lines, "Needed to clear, exercise against production:", needed)
+          item_group(lines, "Also worth running, not needed to clear (changed or rarely used, watched on first use):", extra)
+        else
+          item_group(lines, "Optional:", items)
         end
+        lines << "Use a test account, or ask first, for routes marked [changes data]." if items.any? { |item| item["mutating"] }
         lines << "Then report it: #{plan["report_with"]}" if plan["report_with"]
         lines.join("\n")
       end
 
+      # Only what clearance waits on: the rest is in `deployangel plan`.
       def exercisable_items(document)
         plan = document["exercise_plan"] || {}
-        EXERCISABLE.include?(plan["status"]) ? Array(plan["items"]).map { |item| item_line(item) } : []
+        return [] unless EXERCISABLE.include?(plan["status"])
+
+        Array(plan["items"]).select { |item| needed?(item) }.map { |item| item_line(item) }
+      end
+
+      # Whether clearance waits on the item. Servers older than the needed
+      # flag listed normally active items first, so count those.
+      def needed?(item)
+        item.key?("needed") ? item["needed"] : item["reason"] == "normally_active"
+      end
+
+      def item_group(lines, heading, items)
+        return if items.empty?
+
+        lines << heading
+        items.each { |item| lines << "  #{item_line(item)}" }
       end
 
       def shortfall_lines(shortfall)

data/lib/deployangel/core/aggregator.rb

@@ -37,6 +37,20 @@ module DeployAngel
       end
     end
 
+    # count: every recording; http and job: those recorded while handling an
+    # HTTP request or running a job (see ExecutionContext). The rest were
+    # recorded outside either.
+    CheckpointStats = Struct.new(:count, :http, :job) do
+      def record(count, context)
+        self.count += count
+        if context == ExecutionContext::HTTP
+          self.http += count
+        elsif context == ExecutionContext::JOB
+          self.job += count
+        end
+      end
+    end
+
     class Period
       attr_reader :started_at, :requests, :status_counts, :unhandled_exceptions, :histogram, :routes,
         :jobs, :job_classes, :exceptions, :exceptions_truncated, :checkpoints
@@ -52,13 +66,13 @@ module DeployAngel
         @job_classes = {}
         @exceptions = {}
         @exceptions_truncated = 0
-        @checkpoints = Hash.new(0)
+        @checkpoints = {}
       end
 
       # Up to 100 names per period; the rest are counted together.
-      def record_checkpoint(name, count)
+      def record_checkpoint(name, count, context)
         key = @checkpoints.key?(name) || @checkpoints.size < MAX_CHECKPOINTS - 1 ? name : OTHER_ROUTE
-        @checkpoints[key] += count
+        (@checkpoints[key] ||= CheckpointStats.new(0, 0, 0)).record(count, context)
       end
 
       # Up to 20 fingerprints per period; the rest are only counted.
@@ -141,9 +155,11 @@ module DeployAngel
       @mutex.synchronize { (@periods[started_at] ||= Period.new(started_at)).record_discard(job_class.to_s, @max_routes) }
     end
 
-    def record_checkpoint(name:, count: 1)
+    # context: where it was recorded, ExecutionContext::HTTP, ExecutionContext::JOB,
+    # or nil for neither.
+    def record_checkpoint(name:, count: 1, context: nil)
       started_at = period_start(@clock.call)
-      @mutex.synchronize { (@periods[started_at] ||= Period.new(started_at)).record_checkpoint(name, count) }
+      @mutex.synchronize { (@periods[started_at] ||= Period.new(started_at)).record_checkpoint(name, count, context) }
     end
 
     # A representative backtrace is kept only the first time this process

data/lib/deployangel/core/execution_context.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  # The unit of work the current fiber is running: HTTP while the request
+  # middleware handles a request, JOB while job instrumentation runs a job,
+  # and nil otherwise (console, rake tasks, boot, a thread of the app's own).
+  # Checkpoints read it to say where they were recorded.
+  #
+  # Thread.current[] is fiber-local, like Rails' isolated execution state, so
+  # requests served concurrently in threads (Puma) or fibers (Falcon) each
+  # see their own. Every integration restores the previous value when its
+  # unit ends, even when it raises, so the innermost unit wins when they nest
+  # (a job performed inline during a request), and nothing leaks into the
+  # next request a reused thread serves.
+  module ExecutionContext
+    KEY = :__deployangel_execution_context
+    HTTP = :http
+    JOB = :job
+
+    module_function
+
+    def current
+      Thread.current[KEY]
+    end
+
+    # Returns the previous context, to hand back to restore.
+    def enter(kind)
+      previous = Thread.current[KEY]
+      Thread.current[KEY] = kind
+      previous
+    end
+
+    def restore(previous)
+      Thread.current[KEY] = previous
+    end
+  end
+end

data/lib/deployangel/core/protocol.rb

@@ -34,7 +34,11 @@ module DeployAngel
         "exceptions_truncated" => period.exceptions_truncated,
         "jobs" => job_stats(period.jobs),
         "job_classes" => period.job_classes.map { |key, stats| { "key" => key }.merge(job_stats(stats)) },
-        "checkpoints" => period.checkpoints.map { |key, count| { "key" => key, "count" => count } }
+        # http and job are always sent, 0 when none, so the cloud can tell
+        # this agent from one that doesn't say where checkpoints happened.
+        "checkpoints" => period.checkpoints.map do |key, stats|
+          { "key" => key, "count" => stats.count, "http" => stats.http, "job" => stats.job }
+        end
       }
     end
 

data/lib/deployangel/mcp.rb

@@ -22,7 +22,8 @@ module DeployAngel
         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.
         If a release isn't cleared yet, get_exercise_plan says what to exercise against production so it
-        clears sooner. Only act on status "exercisable" or "waiting_for_activity"; for "warm_up" or
+        clears sooner. Items with needed true are what clearance waits on; the rest are only worth running.
+        Only act on status "exercisable" or "waiting_for_activity"; for "warm_up" or
         "no_baseline" nothing you run can clear it. Exercise routes marked mutating only with a test account
         or after asking. Report what you ran with the plan's report_with command (deployangel check).
       TEXT
@@ -102,7 +103,8 @@ module DeployAngel
             )),
           tool("get_exercise_plan", "What stands between a release and clearance, and what to exercise against " \
             "production so it clears sooner: normally active routes short of their runs, routes this release changed " \
-            "that haven't run, and critical flows. Routes marked mutating change data: use a test account or ask first. " \
+            "that haven't run, and critical flows. needed marks what clearance waits on; the rest are only worth running. " \
+            "Routes marked mutating change data: use a test account or ask first. " \
             "Your requests count as ordinary traffic; report what you ran with report_with. Defaults to the current git HEAD.",
             TARGET_PROPERTIES),
           tool("list_deployments", "Recent deployments with their verification state and verdict.",

data/lib/deployangel/rack/http.rb

@@ -31,11 +31,16 @@ module DeployAngel
 
         started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         Redaction.request_host = env["HTTP_HOST"]
+        # Checkpoints recorded from here until the app returns count as
+        # recorded in a request.
+        previous_context = ExecutionContext.enter(ExecutionContext::HTTP)
         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
+        ensure
+          ExecutionContext.restore(previous_context)
         end
         # A framework that renders an exception itself swallows it before it
         # reaches this middleware, and renders some as 4xx; only those that

data/lib/deployangel/rails/active_job.rb

@@ -11,6 +11,34 @@ module DeployAngel
     # perform finishes.
     module ActiveJob
       STATE = :@__deployangel_job_state
+      PREVIOUS_CONTEXT = :@__deployangel_previous_context
+
+      # Marks the fiber as running a job for as long as perform.active_job
+      # lasts, so checkpoints recorded by the job say so. ActiveSupport calls
+      # finish from an ensure, so the previous context (an HTTP request, for
+      # a job performed inline) comes back even when the job raises. It is
+      # kept on the job, so only a perform that started here restores.
+      module ContextListener
+        module_function
+
+        def start(_name, _id, payload)
+          job = payload[:job]
+          return unless job && DeployAngel.recording?
+
+          job.instance_variable_set(PREVIOUS_CONTEXT, ExecutionContext.enter(ExecutionContext::JOB))
+        rescue StandardError
+          nil
+        end
+
+        def finish(_name, _id, payload)
+          job = payload[:job]
+          return unless job&.instance_variable_defined?(PREVIOUS_CONTEXT)
+
+          ExecutionContext.restore(job.remove_instance_variable(PREVIOUS_CONTEXT))
+        rescue StandardError
+          nil
+        end
+      end
 
       module_function
 
@@ -23,6 +51,7 @@ module DeployAngel
         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", ContextListener)
         ::ActiveSupport::Notifications.subscribe("perform.active_job") { |event| record(event) }
       end
 

data/lib/deployangel/sidekiq.rb

@@ -16,12 +16,15 @@ module DeployAngel
 
         started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         latency = DeployAngel::Sidekiq.queue_latency_ms(job)
+        previous_context = ExecutionContext.enter(ExecutionContext::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
+        ensure
+          ExecutionContext.restore(previous_context)
         end
         record(job, started, latency, failed: false)
       end

data/lib/deployangel/version.rb

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

data/lib/deployangel.rb

@@ -9,6 +9,7 @@ require_relative "deployangel/core/release"
 require_relative "deployangel/core/instance"
 require_relative "deployangel/core/aggregator"
 require_relative "deployangel/core/protocol"
+require_relative "deployangel/core/execution_context"
 require_relative "deployangel/core/buffer"
 require_relative "deployangel/core/transport"
 require_relative "deployangel/agent"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deployangel
 version: !ruby/object:Gem::Version
-  version: 0.1.13
+  version: 0.1.15
 platform: ruby
 authors:
 - Jordan Owens
@@ -38,6 +38,7 @@ files:
 - lib/deployangel/configuration.rb
 - lib/deployangel/core/aggregator.rb
 - lib/deployangel/core/buffer.rb
+- lib/deployangel/core/execution_context.rb
 - lib/deployangel/core/fingerprint.rb
 - lib/deployangel/core/histogram.rb
 - lib/deployangel/core/instance.rb