hecks 5.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/desktop_alert/alert.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class DesktopAlert
+      # One alert, and the program that shows it on this machine: `terminal-notifier` where it is
+      # installed, since clicking its alert opens the link; else `osascript` on macOS, whose alert
+      # opens Script Editor when clicked; else `notify-send`.
+      #
+      # @!attribute [r] title
+      #   @return [String] the alert's first line
+      # @!attribute [r] subtitle
+      #   @return [String] the line beneath it
+      # @!attribute [r] body
+      #   @return [String] the rest
+      # @!attribute [r] link
+      #   @return [String, nil] what clicking the alert opens
+      Alert = Struct.new(:title, :subtitle, :body, :link, keyword_init: true) do
+        # Shows the alert with the first program this machine has.
+        #
+        # @param shell [Shell] the adapter the program runs through
+        # @return [Shell::Result] how the last program tried ended; 127 when none is installed
+        def show(shell)
+          shown = shell.capture(*notifier)
+          status = shown.status
+          return shown unless status.exitstatus == 127
+
+          shell.capture(*fallback)
+        end
+
+        private
+
+        def notifier
+          ["terminal-notifier", "-title", title, "-subtitle", subtitle, "-message", body.empty? ? subtitle : body,
+           "-group", title, "-sound", "Glass", *(["-open", link] if link)]
+        end
+
+        def fallback
+          return ["notify-send", title, "#{subtitle}\n#{body}"] unless RUBY_PLATFORM.include?("darwin")
+
+          ["osascript", "-e", "display notification #{quoted(body)} with title #{quoted(title)} " \
+                              "subtitle #{quoted(subtitle)} sound name \"Glass\""]
+        end
+
+        # An AppleScript string literal.
+        def quoted(text) = "\"#{text.gsub(/[\\"]/) { |char| "\\#{char}" }}\""
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/desktop_alert.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/desktop_alert"
+
+Hecks.adapter "DesktopAlert" do
+  port "Alerts"
+end

data/lib/hecks/hecks/adapters/desktop_alert.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "shell"
+require_relative "console_capture"
+require_relative "git"
+require_relative "desktop_alert/alert"
+
+module Hecks
+  module Adapters
+    # The `Alerts` port's adapter: says on the operator's desktop that a pushed branch is ready to
+    # deploy. A machine with neither a notifier nor `osascript` refuses, and the push it announces
+    # stands.
+    #
+    # The alert reads at a glance: the repository and "ready to deploy" as its title, the branch,
+    # commit and how many commits went out beneath it, and the newest commits' subjects as its body.
+    # Clicking it opens the branch's runs on GitHub when the remote is a GitHub repository.
+    class DesktopAlert
+      # How many commit subjects the body lists.
+      SUBJECTS = 3
+
+      # A GitHub remote's owner and repository, over HTTPS or SSH.
+      GITHUB = %r{github\.com[:/]([^/]+)/(.+?)(?:\.git)?/?\z}
+
+      # How many commits a push report says went out, captured.
+      COMMIT_COUNT = /(\d+) commit/
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @shell = Shell.new
+        @git = Git.new
+      end
+
+      # Shows that a branch was pushed and a deploy is ready.
+      #
+      # @param held [Hash] the `PushTrain` record: `checkout`, `branch`, `remote`, `pushed` and
+      #   `report`
+      # @return [Hash{Symbol => Hash}] `report:` the alert's title and subtitle
+      # @raise [ConsoleCapture::Failure] when no desktop alert could be shown
+      def announce(**held)
+        alert = Alert.new(title: title(held), subtitle: subtitle(held), body: body(held), link: runs(held))
+        shown = alert.show(@shell)
+        raise ConsoleCapture::Failure, "no desktop alert was shown: #{shown.err.strip}" unless shown.ok?
+
+        { report: { value: "#{alert.title}: #{alert.subtitle}" } }
+      end
+
+      private
+
+      # Named by its GitHub repository, else by the main checkout's directory: a boarding is often
+      # made from a worktree, whose directory says nothing about the repository.
+      def title(held)
+        owner_and_name = github(held)
+        "#{owner_and_name ? owner_and_name.last : main_checkout(held)} is ready to deploy"
+      end
+
+      def main_checkout(held)
+        common = git(held, "rev-parse", "--path-format=absolute", "--git-common-dir")
+        File.basename(common.ok? ? File.dirname(common.out.strip) : plain(held[:checkout]))
+      end
+
+      def subtitle(held)
+        went_out = plain(held[:report]).to_s[COMMIT_COUNT, 1]
+        "#{plain(held[:remote])}/#{plain(held[:branch])} at #{plain(held[:pushed])[0, 7]}" \
+          "#{" · #{went_out} new" if went_out}"
+      end
+
+      def body(held)
+        listed = git(held, "log", "-#{SUBJECTS}", "--format=%s", plain(held[:pushed]))
+        listed.ok? ? bullets(listed.out) : ""
+      end
+
+      # Each line of `text` as a bullet.
+      def bullets(text) = text.lines.map { |line| "• #{line.strip}" }.join("\n")
+
+      # The branch's runs on GitHub, newest first, or nil for a remote that is not on GitHub.
+      def runs(held)
+        owner, name = github(held)
+        "https://github.com/#{owner}/#{name}/actions?query=branch%3A#{plain(held[:branch])}" if owner
+      end
+
+      # The remote's GitHub owner and repository, or nil.
+      def github(held)
+        url = git(held, "remote", "get-url", plain(held[:remote]))
+        return unless url.ok?
+
+        remote = url.out.strip
+        remote.match(GITHUB)&.captures
+      end
+
+      def git(held, *) = @git.capture(*, chdir: plain(held[:checkout]))
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching/brief_text.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # The words a session is started with, laid out from a composed brief. Every sentence in it is the
+      # Coder bluebook's; this only orders the sections, fills in the row's key and lists the areas the
+      # caller knows.
+      class BriefText
+        # The sections of a brief after the outcome, in the order they are read.
+        SECTIONS = %w[rules verification workflow landing restraints report].freeze
+
+        # @param brief [Hash] the composed brief: its attribute values by name
+        def initialize(brief)
+          @brief = brief
+        end
+
+        # @return [String] the first line of the text: the outcome
+        def first_line = "Outcome: #{plain("outcome")}"
+
+        # @param key [String] the Work row's key, which names the worktree and branch
+        # @param area [Array<String>] the areas the session may edit
+        # @param held [Array<String>] a line for each area another started row holds
+        # @param frozen [Array<String>] the areas and aggregates whose shape may not move
+        # @param limit [Integer, nil] the most spec files a session runs per call, from the world's
+        #   `test_scope` setting; fills `{limit}`
+        # @return [String] the whole text
+        def render(key, area: [], held: [], frozen: [], limit: nil)
+          parts = [first_line, labelled("Detail", plain("detail")), labelled("Area", area.join(", "))]
+          parts += SECTIONS.map { |name| plain(name) }
+          parts += [listed("coordination", held), listed("freeze", frozen)]
+          joined(parts).gsub("{work}", key).gsub("{limit}", limit&.to_s || "the world's spec_files_limit")
+        end
+
+        private
+
+        def labelled(label, text) = text.empty? ? nil : "#{label}: #{text}"
+
+        def listed(name, lines) = lines.empty? ? nil : ([plain(name)] + lines.map { |line| "- #{line}" }).join("\n")
+
+        def joined(parts) = parts.compact.reject(&:empty?).join("\n\n")
+
+        # A value is a bare string or a one-field hash, and a name is a string or a symbol.
+        def plain(name)
+          found = @brief.transform_keys(&:to_s)[name]
+          (found.is_a?(Hash) ? found.transform_keys(&:to_s)["value"] : found).to_s
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching/launcher.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "../shell"
+require_relative "../console_capture"
+require_relative "brief_text"
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # Starts one chosen row's session by running the launcher's own commands, so each step is the
+      # bluebook's command and nothing is written but through one: start the Work row, compose its
+      # brief, hand the brief to `AgentRun`. Before any of them, pull main (`LinkedTree.PullMain`),
+      # so a session never starts from a stale base. A step that fails yields the row to the plan.
+      class Launcher
+        # The claimant every dispatched row names.
+        CLAIMANT = "dispatch"
+
+        # The JSON object a command prints after any log lines.
+        JSON_OBJECT = /\{.*\}/m
+
+        # @param repo [String] the checkout whose `exe/hecks` runs the commands and where sessions work
+        # @param runner [#call, nil] runs an argument list in `repo` and answers a {Shell::Result}
+        def initialize(repo, runner: nil)
+          @repo = repo
+          @runner = runner || ->(argv) { Shell.new.capture("exe/hecks", *argv, chdir: repo) }
+        end
+
+        # @param row [Plan::Row] the row to start
+        # @param held [Array<String>] a line for each area another started row holds
+        # @param frozen [Array<String>] the frozen areas and aggregates
+        # @param minutes [Integer] the time budget of the row
+        # @param limit [Integer, nil] the most spec files a session runs per call, from the world
+        # @return [String] one line: the session started, or why the row went back to the plan
+        def launch(row, held:, frozen:, minutes:, limit: nil)
+          step(row, "pull main", pull_argv)
+          step(row, "start", start_argv(row, minutes))
+          text = BriefText.new(composed(row)).render(row.key, area: row.area, held: held, frozen: frozen, limit: limit)
+          step(row, "dispatch", dispatch_argv(row, text))
+          "started #{row.key}"
+        rescue ConsoleCapture::Failure => e
+          yield_back(row, e.message)
+        end
+
+        # @param key [String] the run, which is also the Work row's key
+        # @return [void]
+        def check(key) = @runner.call(["AgentRun.check!", "to=#{key}", "--wait"])
+
+        # @param key [String] the Work row to record as done
+        # @return [String] the line that says so
+        def finish(key)
+          @runner.call(["tickets", "Work.finish!", "to=#{key}", "--wait"])
+          "finished #{key}"
+        end
+
+        # @param key [String] the Work row to send back to the plan
+        # @param reason [String] why
+        # @return [String] the line that says so
+        def yield_back(key, reason)
+          key = key.key if key.respond_to?(:key)
+          @runner.call(["tickets", "Work.yield!", "to=#{key}", "reason.value=#{reason}", "--wait"])
+          "yielded #{key}: #{reason}"
+        end
+
+        private
+
+        def step(row, name, argv)
+          result = @runner.call(argv)
+          return result if result.ok? && !result.out.include?('"refusal": "')
+
+          raise ConsoleCapture::Failure, "#{name} of #{row.key} failed: #{said(result)}"
+        end
+
+        def said(result) = (result.err.empty? ? result.out : result.err).strip[0, 300]
+
+        # Local `main` current before the session starts, so no worktree is cut from a stale base.
+        def pull_argv = ["LinkedTree.pull_main!", "checkout.value=#{@repo}", "--wait"]
+
+        def dispatch_argv(row, text)
+          ["AgentRun.dispatch!", "run.value=#{row.key}", "repo.value=#{@repo}", "brief.value=#{text}", "--wait"]
+        end
+
+        def start_argv(row, minutes)
+          ["tickets", "Work.start!", "to=#{row.key}", "claimed_by.value=#{CLAIMANT}", "claimed_at.value=#{Time.now.utc.iso8601}",
+           *row.area.map { |word| "area.value=#{word}" }, "budget_minutes.value=#{minutes}", "--wait"]
+        end
+
+        def composed(row)
+          result = step(row, "compose", ["coder", "Brief.compose!", "work.value=#{row.key}", "outcome.value=#{row.title}",
+                                         "detail.value=#{row.detail}", *row.area.map { |word| "area.value=#{word}" }, "--wait"])
+          JSON.parse(result.out[JSON_OBJECT])["state"]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching/plan.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../area_overlap"
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # Which planned rows start a session now, and why each of the others waits. It decides from the
+      # rows it is given and starts nothing.
+      #
+      # A planned row waits when it sits in a frozen area, when its area overlaps a started row's or an
+      # earlier chosen row's (by {AreaOverlap}), or when the machine is loaded or the cap is reached,
+      # which also hold back every row after it.
+      class Plan
+        # A row, as {Rows} reads it.
+        Row = Struct.new(:key, :title, :detail, :area, keyword_init: true)
+
+        # What a name is compared without, so `quality_control` and `QualityControl` meet.
+        NOT_ALNUM = /[^a-z0-9]/
+
+        # A row left waiting, and the reason.
+        Skip = Struct.new(:key, :reason)
+
+        # @return [Array<Row>] the rows to start, in plan order
+        attr_reader :chosen
+
+        # @return [Array<Skip>] the rows left waiting, in plan order
+        attr_reader :skipped
+
+        # @param planned [Array<Row>] the planned rows, in plan order
+        # @param started [Array<Row>] the started rows
+        # @param limits [Hash] `cap:` (Integer), `load:` and `max_load:` (Float), `frozen:` (Array)
+        def initialize(planned, started, **limits)
+          @started = started
+          @limits = limits
+          @chosen = []
+          @skipped = []
+          planned.each { |row| consider(row) }
+        end
+
+        # @return [Array<Row>] the started rows and the chosen ones: whose areas are not to be edited
+        def holders = @started + @chosen
+
+        private
+
+        def consider(row)
+          reason = stop_reason || frozen_reason(row) || overlap_reason(row)
+          reason ? @skipped << Skip.new(row.key, reason) : @chosen << row
+        end
+
+        def stop_reason = overloaded || capped
+
+        def overloaded
+          return unless @limits[:load] > @limits[:max_load]
+
+          "skipped: load #{@limits[:load].round(1)} > #{@limits[:max_load].round(1)}"
+        end
+
+        def capped
+          return unless holders.size >= @limits[:cap]
+
+          "skipped: cap #{@limits[:cap]} reached (#{holders.size} started or chosen)"
+        end
+
+        def frozen_reason(row)
+          hit = @limits[:frozen].find { |name| row.area.any? { |word| squash(word).include?(squash(name)) } }
+          "skipped: frozen (#{hit})" if hit
+        end
+
+        def overlap_reason(row)
+          holders.each do |other|
+            pair = AreaOverlap.first_overlap(row.area, other.area)
+            return "skipped: #{pair[0]} overlaps #{other.key} at #{pair[1]}" if pair
+          end
+          nil
+        end
+
+        def squash(text) = text.to_s.downcase.gsub(NOT_ALNUM, "")
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching/rows.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../started_work"
+require_relative "plan"
+require_relative "../push_size"
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # The Work rows and agent runs of a booted registry, read and never written.
+      class Rows
+        # @param registry [Runtime::Registry, nil]
+        def initialize(registry)
+          @registry = registry
+        end
+
+        # The key prefix of a row that says main is red; such a row is planned first, and so is the
+        # `push-due` row once its title says the push is urgent.
+        RED = "red-"
+
+        # @return [Array<Plan::Row>] the planned rows, red ones first, then in plan order (a row
+        #   with no step last)
+        def planned = rows("planned").sort_by.with_index { |row, index| [red?(row[1]) ? 0 : 1, row[0], index] }.map(&:last)
+
+        # @return [Array<Plan::Row>] the started rows
+        def started = rows("started").map(&:last)
+
+        # @return [Hash{String => Hash}] each agent run's key with its `status:` and `condition:`
+        def runs
+          aggregate = find("Hecks", "AgentRun")
+          return {} unless aggregate
+
+          @registry.repository("Hecks", aggregate).all.to_h { |run| [field(run, :run).to_s, state(run)] }
+        end
+
+        private
+
+        def red?(row) = row.key.start_with?(RED) || (row.key == "push-due" && row.title.start_with?(PushSize::URGENT))
+
+        def rows(status)
+          work = find("Tickets", "Work")
+          return [] unless work
+
+          records = @registry.repository("Tickets", work).all
+          records.select { |record| field(record, :status) == status }.map { |record| [step(record), row(record)] }
+        end
+
+        def row(record)
+          Plan::Row.new(key: field(record, :work).to_s, title: field(record, :title).to_s,
+                        detail: field(record, :detail).to_s, area: StartedWork.words(field(record, :area)))
+        end
+
+        def state(run) = { status: field(run, :status).to_s, condition: field(run, :condition).to_s }
+
+        def step(record) = field(record, :step) || Float::INFINITY
+
+        def find(domain, name)
+          bluebook = @registry&.bluebook(domain)
+          bluebook&.aggregates&.find { |candidate| candidate.hecks_name == name }
+        end
+
+        def field(record, name) = StartedWork.value(record, name)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching/settings.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "etc"
+require_relative "../work_limits"
+require_relative "../shell"
+require_relative "../codebase/test_scope"
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # What the Tickets world says about filling the queue, and what the machine says about its
+      # load. The bluebook never reads the OS, so the load and the CPU count come through here.
+      class Settings
+        # The world verb naming the areas and aggregates whose persisted shape may not move.
+        FREEZE = "frozen_shapes"
+
+        # The world verb that carries the highest 1-minute load a session may be started under.
+        MAX_LOAD = "dispatch_max_load"
+
+        # The world verb that carries what every session starts with.
+        SESSION = "session_environment"
+
+        # Minutes a started row may run when the caller names no budget.
+        BUDGET_MINUTES = 90
+
+        # What `uptime` prints before the 1-minute load, on macOS and Linux.
+        UPTIME_LOAD = /load averages?:\s*([0-9]+[.,][0-9]+)/
+
+        # @param registry [Runtime::Registry, nil] the booted registry whose Tickets world is read
+        # @param load [#call, nil] answers the 1-minute load average; the machine's when nil
+        # @param cpus [Integer, nil] the CPU count; the machine's when nil
+        def initialize(registry, load: nil, cpus: nil)
+          @registry = registry
+          @load = load || -> { self.class.uptime_load }
+          @cpus = cpus || Etc.nprocessors
+        end
+
+        # Ruby's `Etc` has no load average, so the 1-minute figure is read from `uptime`.
+        #
+        # @param text [String, nil] what `uptime` printed; the machine's when nil
+        # @return [Float] the 1-minute load, 0.0 when `uptime` says none
+        def self.uptime_load(text = nil)
+          text ||= Shell.new.capture("uptime").out
+          text[UPTIME_LOAD, 1].to_s.tr(",", ".").to_f
+        end
+
+        # @return [Array<String>] the frozen areas and aggregates, empty when none is declared
+        def frozen = Array(declared(FREEZE)[:areas]).map(&:to_s)
+
+        # @return [Float] the 1-minute load average now
+        def load = @load.call.to_f
+
+        # @return [Integer] the CPU count
+        attr_reader :cpus
+
+        # @return [Float] the load above which no session is started: the world's, else the CPU count
+        def max_load = (declared(MAX_LOAD)[:limit] || @cpus).to_f
+
+        # @return [Integer] the cap on started rows
+        def cap = WorkLimits.cap(@registry)
+
+        # @return [Integer, nil] the most spec files a session may run per call, from the Hecks
+        #   world's `test_scope` setting; nil when none is declared
+        def spec_files_limit = Codebase::TestScope.limit(@registry)
+
+        # @return [Hash{String => String}] the environment every dispatched session starts with
+        def session_environment
+          dir = declared(SESSION)[:cargo_target_dir]
+          dir ? { "CARGO_TARGET_DIR" => File.expand_path(dir.to_s) } : {}
+        end
+
+        # @return [Integer, nil] the `nice` increment for a session's processes, nil for none
+        def nice = declared(SESSION)[:nice]
+
+        private
+
+        def declared(verb) = @registry&.world("Tickets")&.for_verb(verb) || {}
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching/settler.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # Settles the started rows whose sessions have ended: asks each running session how it is, then
+      # finishes the row of one that ended `done` and yields the row of one that ended any other way,
+      # with the condition as the reason. A session still working is left alone.
+      class Settler
+        # @param rows [Rows] where the started rows and the runs are read
+        # @param launcher [Launcher] runs the commands that check, finish and yield
+        def initialize(rows, launcher)
+          @rows = rows
+          @launcher = launcher
+        end
+
+        # @return [Array<String>] one line for each row settled, empty when none was
+        def call
+          checkable.each_key { |key| @launcher.check(key) }
+          ended.map { |key, run| settle(key, run[:condition]) }
+        end
+
+        private
+
+        def settle(key, condition)
+          condition == "done" ? @launcher.finish(key) : @launcher.yield_back(key, "its session ended #{condition}")
+        end
+
+        def checkable = mine.select { |_key, run| run[:status] == "started" }
+
+        def ended = mine.select { |_key, run| run[:status] == "finished" }
+
+        def mine
+          started = @rows.started.map(&:key)
+          @rows.runs.slice(*started)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/dispatching"
+
+Hecks.adapter "Dispatching" do
+  port "Dispatching"
+end

data/lib/hecks/hecks/adapters/dispatching.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+require_relative "dispatching/settings"
+require_relative "dispatching/rows"
+require_relative "dispatching/plan"
+require_relative "dispatching/launcher"
+require_relative "dispatching/settler"
+
+module Hecks
+  module Adapters
+    # The `Dispatching` port's adapter for `Dispatch`: reads the Work queue and the machine, says which
+    # planned rows would start a session and why each other waits, and with `confirm` starts them.
+    #
+    # It decides only what the Plan rules decide; whether a row may start is still the bluebook's
+    # (the `WorkAreas` and `WorkLimits` ports refuse a start that clashes or goes over the cap). The
+    # default is a dry run, which writes nothing.
+    class Dispatching
+      # @param registry [Runtime::Registry, nil] the booted registry whose rows are read
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `load:`, `cpus:` and `runner:` stand in for the machine and the launcher
+      # @param root [String, nil] unused
+      def initialize(registry: nil, aggregate: nil, settings: {}, root: nil)
+        @registry = registry
+        @standins = settings
+      end
+
+      # Says which planned rows start now, and starts them when confirmed.
+      #
+      # @param held [Hash] the `Dispatch` record: `repo`, `budget_minutes`, `confirm`
+      # @return [Hash{Symbol => Hash}] `report:` the load, the rows started or that would be, and the
+      #   rows left waiting with the reason
+      def choose(**held)
+        plan = plan_for
+        lines = [header(plan)] + plan.chosen.map { |row| chosen_line(row) } + plan.skipped.map { |skip| skipped_line(skip) }
+        lines += launch(plan, held) if plain(held[:confirm]) == true
+        { report: { value: lines.join("\n") } }
+      end
+
+      # Checks every started session and settles the row of each that ended: done finishes it.
+      #
+      # @param held [Hash] the `Dispatch` record: `repo`
+      # @return [Hash{Symbol => Hash}] `report:` one line per row settled
+      def conclude(**held)
+        lines = Settler.new(rows, launcher_for(held)).call
+        { report: { value: lines.empty? ? "nothing to settle" : lines.join("\n") } }
+      end
+
+      private
+
+      def rows = @standins[:rows] || Rows.new(@registry)
+
+      def machine = Settings.new(@registry, load: @standins[:load], cpus: @standins[:cpus])
+
+      def launcher_for(held) = Launcher.new(plain(held[:repo]), runner: @standins[:runner])
+
+      def plan_for
+        Plan.new(rows.planned, rows.started, cap: machine.cap, load: machine.load, max_load: machine.max_load,
+                                             frozen: machine.frozen)
+      end
+
+      def header(plan)
+        "#{load_line}; cap #{machine.cap}, #{rows.started.size} started; frozen: #{frozen_line}; #{plan.chosen.size} to start"
+      end
+
+      def load_line = "load #{machine.load.round(1)} (limit #{machine.max_load.round(1)}, #{machine.cpus} cpus)"
+
+      def frozen_line = machine.frozen.empty? ? "none" : machine.frozen.join(", ")
+
+      def chosen_line(row) = "would start #{row.key}: #{BriefText.new("outcome" => row.title).first_line}"
+
+      def skipped_line(skip) = "#{skip.key} #{skip.reason}"
+
+      def launch(plan, held)
+        launcher = launcher_for(held)
+        minutes = plain(held[:budget_minutes]) || Settings::BUDGET_MINUTES
+        plan.chosen.each_with_index.map do |row, index|
+          launcher.launch(row, held: holding(plan, index), frozen: machine.frozen, minutes: minutes,
+                          limit: machine.spec_files_limit)
+        end
+      end
+
+      # A line for each other row, started or chosen before this one, that holds an area.
+      def holding(plan, index)
+        (rows.started + plan.chosen.first(index)).reject { |other| other.area.empty? }.map { |other| held_line(other) }
+      end
+
+      def held_line(row) = "#{row.key}: #{row.title} (#{row.area.join(", ")})"
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end