openlanes 3.0.1 → 3.1.0

data/lib/openlanes/engine/verification/round.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OpenLanes
+  module Engine
+    module Verification
+      # One verification of one plan: `<plan folder>/verification/<number>/`
+      # (M14), where chewie leaves its screenshots and `report.md`.
+      #
+      # The number is read from disk, never kept anywhere else: a round is
+      # finished once its `report.md` exists, so the next run of chewie gets
+      # the next number, while a run that died before reporting hands its
+      # folder to the one that follows it rather than leaving a gap.
+      #
+      # @!attribute [r] plan_dir
+      #   @return [String] the plan folder, in the main checkout
+      # @!attribute [r] number
+      #   @return [Integer] from 1
+      Round = Data.define(:plan_dir, :number) do
+        # @return [String] the round's own folder
+        def dir = File.join(plan_dir, Round::FOLDER, number.to_s)
+
+        # @return [String] what chewie writes when it is done
+        def report_path = File.join(dir, Round::REPORT)
+
+        # @return [Boolean] whether chewie, or the engine for it, reported
+        def reported? = File.file?(report_path)
+
+        # @return [Report, nil]
+        def report = reported? ? Report.read(report_path) : nil
+
+        # @return [String] the folder, relative to the plan folder
+        def relative = File.join(Round::FOLDER, number.to_s)
+
+        # @return [String] where the engine records the verification commit
+        def published_path = File.join(dir, Round::PUBLISHED)
+
+        # Whether the engine pushed this round's evidence. chewie's
+        # `Verdict: verified` is only chewie's word: a run that died after
+        # writing it, before its signature or the push, would otherwise be
+        # taken for a round waiting on CI, and the old head labelled ready.
+        #
+        # @return [Boolean]
+        def published? = File.file?(published_path)
+
+        # @param sha [String, nil] the commit that carried the round
+        # @return [void]
+        def publish!(sha) = File.write(published_path, "#{sha}\n")
+
+        # @return [self] with its folder made
+        def make!
+          FileUtils.mkdir_p(dir)
+          self
+        end
+      end
+
+      class Round
+        # Under the plan folder.
+        FOLDER = "verification"
+
+        # chewie's own account of the round.
+        REPORT = "report.md"
+
+        # The engine's note to chewie about the app it started.
+        APP_NOTE = "app.md"
+
+        # The engine's record that the round's evidence was pushed: the SHA.
+        PUBLISHED = "published.txt"
+
+        class << self
+          # @param plan_dir [String]
+          # @return [Array<Round>] every round on disk, oldest first
+          def all(plan_dir)
+            base = File.join(plan_dir, FOLDER)
+            return [] unless File.directory?(base)
+
+            Dir.children(base).grep(/\A[1-9]\d*\z/).map(&:to_i).sort.map { new(plan_dir:, number: it) }
+          end
+
+          # @param plan_dir [String]
+          # @return [Round, nil] the newest round, reported or not
+          def latest(plan_dir) = all(plan_dir).last
+
+          # The round a new run of chewie works in: the newest one when it
+          # has no report yet, otherwise the one after it.
+          #
+          # @param plan_dir [String]
+          # @return [Round]
+          def next(plan_dir)
+            last = latest(plan_dir)
+            return last if last && !last.reported?
+
+            new(plan_dir:, number: (last&.number || 0) + 1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/engine/verification/screenshots.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+
+module OpenLanes
+  module Engine
+    module Verification
+      # The images one round leaves, made ready to commit (M14): PNG only,
+      # only the failing step and the final state, each optimised.
+      #
+      # PNG because GitHub renders neither AVIF nor WebP inline in a pull
+      # request comment, and a screenshot nobody sees proves nothing. Two
+      # images because every one lands in the branch, then on `main`, for
+      # good: a plan rejected three times already adds six.
+      class Screenshots
+        # Anything an image could be. Only `.png` survives {#prepare}.
+        IMAGE = /\.(?:png|jpe?g|gif|webp|avif|heic|heif|bmp|tiff?)\z/i
+
+        # The last screenshot of every round, pass or fail.
+        FINAL = "final.png"
+
+        # Optimisers, in the order tried (M14 names both). Each writes a
+        # recompressed copy; the smallest file, the original included, is
+        # the one kept, so an optimiser that grows an already tight PNG (vips
+        # does, on small flat images) costs nothing.
+        TOOLS = {
+          "vips"   => ->(from, to) { ["vips", "pngsave", from, to, "--compression", "9", "--keep", "none"] },
+          "magick" => ->(from, to) { ["magick", from, "-strip", "-define", "png:compression-level=9", to] }
+        }.freeze
+
+        # A round holding an image other than PNG.
+        class Refused < Error; end
+
+        # @param dir [String] the round's folder
+        # @param tools [Hash{String => Proc}] name to argv builder, see {TOOLS}
+        # @param which [#call] a tool name to whether it is on `PATH`
+        # @param runner [#call] argv to whether it succeeded
+        def initialize(dir:, tools: TOOLS, which: method(:on_path?), runner: method(:run))
+          @dir = dir
+          @tools = tools
+          @which = which
+          @runner = runner
+        end
+
+        # Refuse what is not PNG, drop every image but the failing step's and
+        # {FINAL}, and optimise those.
+        #
+        # @param failing_step [Integer, nil] the step whose screenshot to keep
+        # @return [Array<String>] the kept paths, failing step first
+        # @raise [Refused] naming every image that is not PNG; nothing is deleted then
+        def prepare(failing_step: nil)
+          images = Dir.children(@dir).select { it.match?(IMAGE) && File.file?(File.join(@dir, it)) }.sort
+          foreign = images.grep_v(/\.png\z/i)
+          raise Refused, "#{@dir}: not PNG, which GitHub does not show inline: #{foreign.join(", ")}" unless foreign.empty?
+
+          keep = [(format(Report::STEP_PNG, failing_step) if failing_step), FINAL].compact
+          (images - keep).each { FileUtils.rm_f(File.join(@dir, it)) }
+          kept = keep.map { File.join(@dir, it) }.select { File.file?(it) }
+          optimise(kept)
+          kept
+        end
+
+        # Delete every image that is not PNG. {#prepare} deletes nothing when
+        # it refuses, so that a person reading the round can see what was
+        # there; but the round's folder is committed whole, so whatever is
+        # left in it is published. A caller about to commit calls this
+        # first, then {#prepare} again.
+        #
+        # @return [Array<String>] the names removed
+        def discard_foreign!
+          foreign = Dir.children(@dir).select { it.match?(IMAGE) && !it.match?(/\.png\z/i) && File.file?(File.join(@dir, it)) }.sort
+          foreign.each { FileUtils.rm_f(File.join(@dir, it)) }
+          foreign
+        end
+
+        private
+
+        # @param paths [Array<String>]
+        # @return [void]
+        def optimise(paths)
+          return if paths.empty?
+
+          available = @tools.select { |name, _| @which.call(name) }
+          if available.empty?
+            UI.log("screenshots not optimised: neither #{@tools.keys.join(" nor ")} is installed", level: :warn)
+            return
+          end
+
+          paths.each { |path| shrink(path, available.values) }
+        end
+
+        # @return [void]
+        def shrink(path, builders)
+          candidates = builders.each_with_index.filter_map do |build, i|
+            out = "#{path}.#{i}.tmp.png"
+            @runner.call(build.call(path, out)) && File.file?(out) ? out : nil
+          end
+          best = candidates.min_by { File.size(it) }
+          FileUtils.mv(best, path) if best && File.size(best) < File.size(path)
+        ensure
+          candidates&.each { FileUtils.rm_f(it) }
+        end
+
+        # @param name [String]
+        # @return [Boolean]
+        def on_path?(name) = ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? { File.executable?(File.join(it, name)) }
+
+        # @param argv [Array<String>]
+        # @return [Boolean]
+        def run(argv)
+          _, status = Open3.capture2e(*argv)
+          status.success?
+        rescue SystemCallError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/engine/verification.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Engine
+    # Running a reviewed pull request before it may merge (plan 014, M1).
+    #
+    # hansolo's approval moves the plan to 🧪 Verifying. The engine starts the
+    # plan's app ({AppSession}), `chewie-verifier` follows the pull request's
+    # `## How to test` against it and leaves screenshots and a report in a
+    # {Round}'s folder, and the engine acts on the verdict ({Outcome}):
+    # commit, comment, label, and the plan to 🔴, or green CI, the coverage
+    # gate and `ready-to-merge`.
+    module Verification
+      # The phase an agent definition declares to be the verifier. Its
+      # Completed notes are verdicts, as the review phase's are.
+      PHASE = "verification"
+
+      # The verdicts that go on to verification at every quality.
+      FROM_REVIEW = [Plans::ReviewLabel::APPROVED].freeze
+
+      # The verdict whose fate `desired_codebase_quality` decides (R4): on
+      # to verification under `mvp`, back to luke and rey under `high`.
+      ON_QUALITY = Plans::ReviewLabel::OK_NOT_PERFECT
+
+      module_function
+
+      # @param plan_dir [String]
+      # @return [Round] the round a new run of chewie works in
+      def round_for(plan_dir) = Round.next(plan_dir)
+
+      # @param plan_dir [String]
+      # @return [Round, nil] the newest round
+      def latest(plan_dir) = Round.latest(plan_dir)
+
+      # @return [AppSession]
+      def session(**) = AppSession.new(**)
+
+      # @return [Outcome]
+      def outcome(**) = Outcome.new(**)
+
+      # @param labels [Array<String>] a pull request's labels
+      # @param quality [Symbol, nil] {Config#desired_codebase_quality}; nil
+      #   while the project is still to be asked, which lets nothing but
+      #   {FROM_REVIEW} through
+      # @return [Boolean] whether its review verdict goes on to verification
+      def from_review?(labels, quality: nil)
+        return true if FROM_REVIEW.any? { labels.include?(it.name) }
+
+        quality == :mvp && labels.include?(ON_QUALITY.name)
+      end
+
+      # @param labels [Array<String>] a pull request's labels
+      # @return [Boolean] whether the verdict is the one the quality decides
+      def ok_not_perfect?(labels) = labels.include?(ON_QUALITY.name) && FROM_REVIEW.none? { labels.include?(it.name) }
+    end
+  end
+end

data/lib/openlanes/engine.rb

@@ -6,14 +6,43 @@ module OpenLanes
   module Engine
     module_function
 
+    # @param options [Hash] passed to {RunWorkflow#initialize}
+    # @return [OpenLanes::Engine::RunWorkflow] `openlanes run`, without the command
+    def run(**) = RunWorkflow.new(**)
+
+    # @param options [Hash] passed to {StartWorkflow#initialize}
+    # @return [OpenLanes::Engine::StartWorkflow] `openlanes start`, without the command
+    def start(**) = StartWorkflow.new(**)
+
     # @return [OpenLanes::Engine::Runner]
     def runner(**) = Runner.new(**)
 
     # @param tree [OpenLanes::Plans::Tree]
     # @return [OpenLanes::Engine::StateFile]
-    def state_file(tree) = StateFile.new(path: StateFile.for(tree))
+    def state_file(tree) = StateFile.new(path: StateFile.for(tree), legacy: StateFile.legacy_for(tree))
 
     # @return [OpenLanes::Engine::Tally]
     def tally(**) = Tally.new(**)
+
+    # The coverage check `ready-to-merge` waits on (M15).
+    #
+    # @return [OpenLanes::Engine::CoverageGate]
+    def coverage_gate(**) = CoverageGate.new(**)
+
+    @agent_locks = ->(dir, own: []) { AgentLocks.new(root: dir, own:) }
+
+    # The plans' alock register (W31), for the repository holding +dir+; nil
+    # when the factory is, which is how the suite keeps `alock` unrun.
+    #
+    # @param dir [String] any directory in the repository, the plans' one
+    # @param own [Array<String>] the engine's agents, whose locks are not outside ones
+    # @return [OpenLanes::Engine::AgentLocks, nil]
+    def agent_locks(dir, own: []) = @agent_locks&.call(dir, own:)
+
+    # @param factory [#call, nil] answers `call(dir, own:)` with an {AgentLocks}
+    # @return [void]
+    def agent_locks=(factory)
+      @agent_locks = factory
+    end
   end
 end

data/lib/openlanes/execution/boundary.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module OpenLanes
+  module Execution
+    # The AFTER half of the autonomy boundary: what the checkout looked like
+    # before an agent ran, and what crossing the line looks like afterwards.
+    #
+    # Two things are checked. HEAD must not move, because the boundary is docs
+    # plus code and no commits. And no remote-tracking ref may have been moved
+    # by a push, because a push is the one thing that leaves the machine.
+    #
+    # The push check reads only local state: `git push` updates the
+    # remote-tracking ref of every branch it pushes (`refs/remotes/origin/x`)
+    # and logs that update as "update by push". `git ls-remote` would also see
+    # pushes made some other way (a URL instead of a remote name, the GitHub
+    # API), but it costs a network round trip on every invocation, and it
+    # cannot tell an agent's push from a teammate's, from CI, or from this
+    # harness publishing another plan a second earlier, so it would fail
+    # honest runs for other people's work. A check that cries wolf gets
+    # turned off.
+    #
+    # Comparing tracking refs alone is not enough either: an agent that runs
+    # `git fetch` moves them to whatever the remote already holds, and nothing
+    # left the machine. So a ref that moved counts only when its reflog says a
+    # push moved it during the run. A ref that moved with no reflog entry at all
+    # (reflogs switched off) cannot be told apart from a push, and is reported.
+    #
+    # Worktrees share `refs/remotes`, so a push from any other checkout of
+    # the repository (a person, another session, a sibling agent's harness)
+    # moves the same refs during this run. A pushed commit reachable from
+    # another worktree's HEAD, and not from this one's, was pushed from there
+    # and is not this agent's. The main checkout counts as another worktree,
+    # so a push of whatever its HEAD names is exempt too; that is accepted,
+    # because it is a push from that checkout, not from this agent. A sibling
+    # that sits on this checkout's own commit is not told apart from it, so a
+    # push of that shared commit is still reported.
+    #
+    # Blind spots, by construction: a push to a bare URL updates no tracking
+    # ref, and a deleted remote branch takes its tracking ref and that ref's
+    # reflog with it, which locally looks the same as `git fetch --prune`.
+    module Boundary
+      # How `git push` signs the tracking refs it updates.
+      PUSHED = "update by push"
+
+      # What one checkout looked like before an agent ran in it.
+      #
+      # @!attribute [r] head
+      #   @return [String, nil] nil outside a repository, which turns the check off
+      # @!attribute [r] remotes
+      #   @return [Hash{String => String}] remote-tracking ref to the commit it named
+      # @!attribute [r] reflogs
+      #   @return [Hash{String => Integer}] remote-tracking ref to how many
+      #     reflog entries it had, so the entries the run added can be told
+      #     from the ones before it. Counting, rather than comparing reflog
+      #     timestamps, because those have one-second resolution and a
+      #     publish in the same second as the snapshot would read as new.
+      Snapshot = Data.define(:head, :remotes, :reflogs) do
+        # @param root [String] the checkout the agent worked in
+        # @return [String, nil] what boundary was crossed, or nil
+        def violation(root)
+          return nil if head.nil?
+
+          after = Boundary.head(root)
+          return "agent committed (HEAD moved #{head[0, 7]} → #{after.to_s[0, 7]}) — the boundary is docs plus code, no commits" if after != head
+
+          pushed = Boundary.pushed(self, root)
+          return nil if pushed.empty?
+
+          "agent pushed (#{pushed.map { |ref| ref.delete_prefix("refs/remotes/") }.join(", ")}) — the boundary is docs plus code, nothing leaves the machine"
+        end
+      end
+
+      @sanctioned = Hash.new { |hash, ref| hash[ref] = [] }
+      @lock = Mutex.new
+
+      class << self
+        # @param root [String]
+        # @return [OpenLanes::Execution::Boundary::Snapshot]
+        def snapshot(root)
+          Snapshot.new(head: head(root), remotes: remotes(root), reflogs: reflogs(root).transform_values(&:size))
+        end
+
+        # Records a push the harness itself is about to make, so an agent
+        # running in another worktree of the same repository is not blamed
+        # for it. Worktrees share `refs/remotes`, and the publisher pushes one
+        # plan's branch while other agents are still working theirs.
+        #
+        # @param path [String] the checkout being pushed
+        # @param remote [String]
+        # @param branch [String]
+        # @return [void]
+        def sanction(path, remote, branch)
+          sha = rev_parse(path, "refs/heads/#{branch}")
+          return if sha.nil?
+
+          @lock.synchronize { @sanctioned["refs/remotes/#{remote}/#{branch}"] << sha }
+        end
+
+        # @param ref [String]
+        # @param sha [String]
+        # @return [Boolean]
+        def sanctioned?(ref, sha) = @lock.synchronize { @sanctioned.fetch(ref, []).include?(sha) }
+
+        # For specs: forget every sanctioned push.
+        #
+        # @return [void]
+        def reset! = @lock.synchronize { @sanctioned.clear }
+
+        # @param root [String]
+        # @return [String, nil] current commit, or nil outside a repository
+        def head(root) = rev_parse(root, "HEAD")
+
+        # The symbolic `refs/remotes/<remote>/HEAD` is left out: it moves with
+        # `git remote set-head`, which pushes nothing.
+        #
+        # @param root [String]
+        # @return [Hash{String => String}]
+        def remotes(root)
+          out = `git -C #{root.shellescape} for-each-ref --format='%(refname) %(objectname)' refs/remotes 2>/dev/null`
+          out.lines.map(&:split).select { |pair| pair.size == 2 }.reject { |ref, _| ref.end_with?("/HEAD") }.to_h
+        end
+
+        # @param before [OpenLanes::Execution::Boundary::Snapshot]
+        # @param root [String]
+        # @return [Array<String>] tracking refs a push moved since the snapshot
+        def pushed(before, root)
+          logs = elsewhere = nil
+          remotes(root).filter_map do |ref, sha|
+            next if before.remotes[ref] == sha || sanctioned?(ref, sha)
+            next if pushed_elsewhere?(root, sha, elsewhere ||= other_heads(root))
+
+            logs ||= reflogs(root)
+            entries = logs.fetch(ref, [])
+            added = entries.first([entries.size - before.reflogs.fetch(ref, 0), 0].max)
+            ref if added.empty? || added.any? { |reason| reason.start_with?(PUSHED) }
+          end
+        end
+
+        # Whether a pushed commit came from another worktree: it is reachable
+        # from that worktree's HEAD (not merely equal to it, so a sibling that
+        # pushed and then committed again before this check is still
+        # recognised) and not reachable from this checkout's own HEAD. The
+        # second half matters because an agent's HEAD is unmoved, so
+        # everything it could push is an ancestor of it; without the
+        # exclusion a sibling branched from the same commit would exempt the
+        # agent's own base commit.
+        #
+        # @param root [String]
+        # @param sha [String]
+        # @param heads [Set<String>] from {#other_heads}
+        # @return [Boolean]
+        def pushed_elsewhere?(root, sha, heads)
+          return false if ancestor?(root, sha, "HEAD")
+
+          heads.any? { |head| ancestor?(root, sha, head) }
+        end
+
+        # The commit checked out in every worktree of the repository but
+        # +root+'s own: what a push from one of them would carry.
+        #
+        # @param root [String]
+        # @return [Set<String>]
+        def other_heads(root)
+          own = real(rev_parse_path(root))
+          out = `git -C #{root.shellescape} worktree list --porcelain 2>/dev/null`
+          out.split("\n\n").each_with_object(Set.new) do |block, heads|
+            fields = block.lines.to_h { |line| line.chomp.split(" ", 2) }
+            heads << fields["HEAD"] if fields["HEAD"] && real(fields["worktree"]) != own
+          end
+        end
+
+        private
+
+        # @return [Boolean] whether +sha+ is reachable from +rev+ (or is it)
+        def ancestor?(root, sha, rev) = system("git", "-C", root, "merge-base", "--is-ancestor", sha, rev, err: File::NULL)
+
+        # @return [String, nil] the checkout's top level
+        def rev_parse_path(root)
+          out = `git -C #{root.shellescape} rev-parse --show-toplevel 2>/dev/null`.strip
+          out.empty? ? root : out
+        end
+
+        # @return [String, nil] the path with symlinks resolved, as git prints it
+        def real(path)
+          File.realpath(path.to_s)
+        rescue SystemCallError
+          path
+        end
+
+        # @return [String, nil]
+        def rev_parse(root, rev)
+          out = `git -C #{root.shellescape} rev-parse --verify --quiet #{rev.shellescape} 2>/dev/null`.strip
+          out.empty? ? nil : out
+        end
+
+        # Every remote-tracking ref's reflog, in one call.
+        #
+        # @return [Hash{String => Array<String>}] ref to why it moved, newest first
+        def reflogs(root)
+          out = `git -C #{root.shellescape} log --walk-reflogs --glob=refs/remotes --format=%gD%x09%gs 2>/dev/null`
+          out.lines.each_with_object(Hash.new { |hash, ref| hash[ref] = [] }) do |line, logs|
+            selector, reason = line.chomp.split("\t", 2)
+            ref, index = selector.to_s.match(/\A(.+)@\{(\d+)\}\z/)&.captures
+            logs[ref][index.to_i] = reason.to_s if ref
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/execution/child.rb

@@ -44,12 +44,14 @@ module OpenLanes
         # @param chdir [String, nil]
         # @param env [Hash{String => String}] what the adapter adds on top of
         #   {.environment}, e.g. claude's autocompact threshold
+        # @param spawner [#spawn] {OpenLanes::Spawner::System} unless a spec
+        #   starts nothing
         # @return [OpenLanes::Execution::Child]
-        def spawn(argv, chdir: nil, env: {})
+        def spawn(argv, chdir: nil, env: {}, spawner: Spawner::System)
           reader, writer = IO.pipe
           options = { out: writer, err: writer, in: File::NULL, unsetenv_others: true, pgroup: true }
           options[:chdir] = chdir if chdir
-          pid = Process.spawn(environment.merge(env), *argv, **options)
+          pid = spawner.spawn(environment.merge(env), *argv, **options)
           writer.close
           track(new(pid:, reader:))
         end

data/lib/openlanes/execution/clock.rb

@@ -47,6 +47,8 @@ module OpenLanes
       # @return [void]
       def tick
         @mutex.synchronize do
+          next if paused
+
           left = @deadline - @now.call
           WARNINGS.each do |before, text|
             next if @fired.include?(before) || left > before
@@ -89,26 +91,54 @@ module OpenLanes
       #
       # @return [void]
       def stop
-        thread = @mutex.synchronize { @thread.tap { @thread = nil } }
+        thread = @mutex.synchronize do
+          @closed = true
+          @thread.tap { @thread = nil }
+        end
         thread&.kill
       end
 
-      # Ten more minutes, or however many. The file is emptied so the next poll
-      # reads a reprieve, and every moment is re-armed against the new deadline.
+      # Ten more minutes, or however many. The file tells the agent how long
+      # it now has, so one told "5 minutes left" does not wrap up on the old
+      # deadline, and every moment is re-armed against the new one.
+      #
+      # Refused once STOP is out or the clock is stopped: that agent is
+      # exiting, and time given to it would reach nobody.
       #
       # @param seconds [Integer]
-      # @return [void]
+      # @return [Boolean] whether the time reached a clock still running
       def extend!(seconds)
         @mutex.synchronize do
+          next false if @closed || %i[stopped expired].include?(@phase)
+
           @deadline += seconds
-          @fired = []
+          @fired = WARNINGS.map(&:first).select { |before| before >= @deadline - @now.call }
           @phase = :calm
-          Control.write(@control, "")
+          Control.write(@control, "#{Control::WARN}: #{((@deadline - @now.call) / 60.0).round} minutes left, time was extended")
+          true
         end
       end
 
       private
 
+      # While agents are paused (W32) the clock stands still: no warning
+      # overwrites the PAUSE in the agent's file, and on resume the deadline
+      # moves on by as long as the pause lasted, so a paused agent is never
+      # stopped for time it spent waiting.
+      #
+      # @return [Boolean] whether this tick is skipped
+      def paused
+        if Control.paused?
+          @paused_at ||= @now.call
+          return true
+        end
+        if @paused_at
+          @deadline += @now.call - @paused_at
+          @paused_at = nil
+        end
+        false
+      end
+
       # @param seconds [Integer]
       # @return [void]
       def arm(seconds)