hecks 7.0.0 → 7.1.0

data/lib/hecks/hecks/adapters/git_leftovers.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "git_landing"
+require_relative "landed_branches"
+
+module Hecks
+  module Adapters
+    # The `Leftovers` port's adapter: after a push, lists the worktrees of branches that landed and
+    # are still there, each with what a retirement would do. It removes nothing, so a session still
+    # working in one is never moved; a person or agent retires what the list says is safe.
+    #
+    # A branch counts only if `Landing` recorded it as landed, so a worktree that was merely opened
+    # is never named. What a retirement would do is `GitLanding::Tidy`'s own verdict, so the list
+    # and `Landing.retire!` cannot disagree.
+    class GitLeftovers
+      include GitWorktrees
+
+      # Accepts the arguments every driven adapter is built with; only the registry is kept.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      # @param registry [Runtime::Registry, nil] where the landed `Landing` rows are read
+      def initialize(aggregate: nil, settings: {}, root: nil, registry: nil)
+        @git = Git.new
+        @registry = registry
+      end
+
+      # @param held [Hash] the `SendTrain` record: `checkout` (any directory in the repository)
+      # @return [Hash{Symbol => Hash}] `report:` one line per such worktree, or that none is left
+      # @raise [ConsoleCapture::Failure] when the checkout is not a repository
+      def leftovers(**held)
+        settle(held)
+        lines = LandedBranches.of(@registry).filter_map { |branch| line(branch) }
+        { report: { value: lines.empty? ? "no landed worktree is left" : lines.join("\n") } }
+      end
+
+      private
+
+      def line(branch)
+        return unless worktree_on(branch)
+
+        "#{branch}: #{GitLanding::Tidy.new(@git, @checkout, branch: branch, onto: "main").verdict}"
+      rescue ConsoleCapture::Failure => e
+        "#{branch}: could not be checked (#{e.message})"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_main_pull.rb

@@ -91,8 +91,8 @@ module Hecks
         lacking = count("#{branch_tip(branch)}..#{REMOTE_MAIN}")
         return if lacking.zero? || ancestor?(branch_tip(branch), branch_tip("main"))
 
-        raise ConsoleCapture::Failure, "main is behind origin/main by #{lacking} commit#{"s" unless lacking == 1}: " \
-                                       "pull main first (LinkedTree.pull_main!) and rebase the branch"
+        raise ConsoleCapture::Failure, "#{branch} lacks #{lacking} commit#{"s" unless lacking == 1} that origin/main has: " \
+                                       "pull main first (LinkedTree.pull_main!) and rebase the branch onto it"
       end
     end
   end

data/lib/hecks/hecks/adapters/git_train.rb

@@ -3,6 +3,7 @@
 require_relative "git"
 require_relative "console_capture"
 require_relative "push_size"
+require_relative "red_flag_guard"
 require_relative "git_train/reading"
 require_relative "git_train/bench"
 require_relative "git_train/local_branch"
@@ -88,7 +89,9 @@ module Hecks
 
       # The commit the branch names as the boarding begins, read once the line is held.
       def boarded_commit(held)
-        Carriage.new(@git, @checkout, branch: branch_of(held), remote: remote_of(held)).local_head
+        head = Carriage.new(@git, @checkout, branch: branch_of(held), remote: remote_of(held)).local_head
+        RedFlagGuard.new(read("rev-parse", "--path-format=absolute", "--git-common-dir")).boarding!(head)
+        head
       end
 
       # Brings the branch up to its remote and settles the shape ledger, then carries the settled
@@ -106,7 +109,7 @@ module Hecks
       def push_size(held)
         ahead = read("rev-list", "--count", "#{remote_of(held)}/#{branch_of(held)}..#{branch_of(held)}").to_i
         sentence = PushSize.sentence(ahead, PushSize.thresholds(@registry))
-        sentence.empty? ? "pushing #{ahead} commits" : "pushing #{ahead} commits; #{sentence}"
+        [ahead, sentence.empty? ? "pushing #{ahead} commits" : "pushing #{ahead} commits; #{sentence}"]
       end
 
       def branch_of(held) = plain(held[:branch]) || "main"
@@ -115,11 +118,12 @@ module Hecks
 
       # The carriage's answer, its report opened with what the mint did and naming the boarded
       # commit (and the settled one when settlement moved the branch).
-      def after_mint(minted, boarded, carried, size = nil)
+      def after_mint(minted, boarded, carried, size)
         answer, settled = carried
+        commits, said = size
         named = settled == boarded ? "boarded #{boarded[0, 9]}" : "boarded #{boarded[0, 9]}, settled to #{settled[0, 9]}"
-        report = "#{"#{size}\n" if size}#{minted}, then #{named}: #{answer.dig(:report, :value)}"
-        answer.merge(boarded: { value: boarded }, report: { value: report })
+        report = "#{said}\n#{minted}, then #{named}: #{answer.dig(:report, :value)}"
+        answer.merge(boarded: { value: boarded }, commits: { value: commits }, report: { value: report })
       end
 
       # A git hook takes no arguments, so the argument reaches the pre-push hook as git

data/lib/hecks/hecks/adapters/git_worktree_add.rb

@@ -5,11 +5,13 @@ require_relative "git_main_pull"
 
 module Hecks
   module Adapters
-    # The `WorktreeAdding` port's adapter for `Worktree`: opens a linked worktree on a new branch cut from
+    # The `WorktreeAdding` port's adapter for `Worktree`: opens a linked worktree on a new branch
+    # cut from
     # `main` (pulled first, see {GitMainPull}), at the path named or under the checkout's
     # `.claude/worktrees`.
     #
-    # It never checks out `main` in a worktree, never pushes, and never forces. A branch that already exists
+    # It never checks out `main` in a worktree, never pushes, and never forces. A branch that
+    # already exists
     # is declined by git, and the reason travels back on the record.
     class GitWorktreeAdd
       include GitWorktrees
@@ -26,10 +28,12 @@ module Hecks
 
       # Opens the worktree, then reads the sha it stands on.
       #
-      # @param held [Hash] the `Worktree` record: `checkout` (a directory inside the repository; the current
+      # @param held [Hash] the `Worktree` record: `checkout` (a directory inside the repository; the
+      #   current
       #   directory when absent), `branch` (a new branch name), and `path` (optional)
       # @return [Hash{Symbol => Hash}] `sha:` the commit it stands on, `report:` where it is
-      # @raise [ConsoleCapture::Failure] on a missing branch, a branch named main, or a directory outside a repository
+      # @raise [ConsoleCapture::Failure] on a missing branch, a branch named main, or a directory
+      #   outside a repository
       def create(**held)
         repo = settle(held)
         branch = branch_named(held)

data/lib/hecks/hecks/adapters/github_pull_requests.rb

@@ -27,7 +27,8 @@ module Hecks
 
       # Opens a pull request from a branch onto a base, its title and body taken from the commits.
       #
-      # @param held [Hash] the `PullRequest` record: `branch` (required), `base` (`main` when absent)
+      # @param held [Hash] the `PullRequest` record: `branch` (required), `base` (`main` when
+      #   absent)
       # @return [Hash{Symbol => Hash}] `outcome:` (`opened`), `number:`, `url:` and `report:`
       # @raise [ConsoleCapture::Failure] when no branch is named, or GitHub refuses
       def create(**held)

data/lib/hecks/hecks/adapters/in_process_operations.rb

@@ -16,7 +16,8 @@ module Hecks
     # the asks of `ModelCheckRun` and `Operation`, plus the `Follow` query.
     #
     # An ask is handed the whole record it was made on (its `held_state`), so each method reads the
-    # record's fields, runs the existing `Hecks::Tools::*` entry point captured, and answers the text
+    # record's fields, runs the existing `Hecks::Tools::*` entry point captured, and answers the
+    # text
     # it printed. An answer records a success; a raise records a refusal, so a check that finds
     # something, or a run that fails, is refused with the report as its reason.
     module InProcessOperations

data/lib/hecks/hecks/adapters/journal_store/edge_audit.rb

@@ -86,7 +86,7 @@ module Hecks
           return verdict.edge if verdict.verdict == "would_mint"
 
           raise Runtime::NotFound, "no translation edge leads #{latest[:label]} to #{label} " \
-                                   "(the decision is #{verdict.verdict}) — run `hecks query era.scaffold_translation` first"
+                                   "(the decision is #{verdict.verdict}) — run `hecks era.scaffold_translation` first"
         end
 
         # The registered translations that leave the latest era.

data/lib/hecks/hecks/adapters/journal_store/readings/composition.rb

@@ -11,7 +11,8 @@ module Hecks
           # it would remove.
           #
           # @param domain [Hash, String] the domain directory
-          # @return [Hash] `text:` the edge file's text, or the sentence that says nothing is to be written
+          # @return [Hash] `text:` the edge file's text, or the sentence that says nothing is to be
+          #   written
           # @raise [Runtime::NotFound] if the domain holds no eras, cannot be loaded, or its chain
           #   cannot be composed
           def compose_translation(domain:)

data/lib/hecks/hecks/adapters/journal_store/translation_write/shape_edge.rb

@@ -4,7 +4,8 @@ module Hecks
   module Adapters
     class JournalStore
       module TranslationWrite
-        # The edge for a shape that changed under an unchanged label: the scaffold's diff, written from
+        # The edge for a shape that changed under an unchanged label: the scaffold's diff, written
+        # from
         # the label to itself. Only `TranslationWrite` includes it.
         module ShapeEdge
           # A line of an edge file that still marks a field as undecided.
@@ -13,7 +14,8 @@ module Hecks
           private
 
           # A held label that equals the current one with a different projection: the edge is the
-          # scaffold's diff, from the label to itself. A field the diff cannot decide refuses the write.
+          # scaffold's diff, from the label to itself. A field the diff cannot decide refuses the
+          # write.
           #
           # @raise [Runtime::WiringError] when the diff leaves a field or an aggregate to decide
           def shape_edge_plan(domain, latest, current)

data/lib/hecks/hecks/adapters/journal_store/translation_write.rb

@@ -16,7 +16,8 @@ module Hecks
       # `translations/` directory.
       module TranslationWrite
         # What a write would do: the file it writes and its text, the stale files it deletes, and
-        # the shape labels the chain passes through. `message` alone answers when nothing is to be done.
+        # the shape labels the chain passes through. `message` alone answers when nothing is to be
+        # done.
         Plan = Struct.new(:message, :path, :text, :removals, :labels, keyword_init: true)
 
         include ShapeEdge
@@ -83,7 +84,8 @@ module Hecks
 
         # Writes the composed edge and deletes the stale ones; returns what each file held before.
         #
-        # @return [Hash{String => String, nil}] each touched path with its earlier text, nil if absent
+        # @return [Hash{String => String, nil}] each touched path with its earlier text, nil if
+        #   absent
         def write_translation!(plan)
           originals = [plan.path, *plan.removals].to_h { |path| [path, read_if_present(path)] }
           File.write(plan.path, plan.text)

data/lib/hecks/hecks/adapters/landed_branches.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "started_work"
+
+module Hecks
+  module Adapters
+    # The branches a booted registry holds a landed `Landing` row for. The `Leftovers` port reads
+    # them to know which worktrees came from a landing, so a branch that was only opened is never
+    # listed. It writes nothing.
+    module LandedBranches
+      module_function
+
+      # @param registry [Runtime::Registry, nil] the booted registry; nil reads no rows
+      # @return [Array<String>] each landed branch once, in the order its rows come
+      def of(registry)
+        aggregate = landing_aggregate(registry)
+        return [] unless aggregate
+
+        rows = registry.repository("Hecks", aggregate).all
+        rows.filter_map { |record| branch(record) }.uniq
+      end
+
+      # @return [Object, nil] the Landing aggregate, nil when no Hecks bluebook is booted
+      def landing_aggregate(registry)
+        bluebook = registry&.bluebook("Hecks")
+        bluebook&.aggregates&.find { |candidate| candidate.hecks_name == "Landing" }
+      end
+
+      # @return [String, nil] the row's branch, nil unless the row landed and names one
+      def branch(record)
+        return unless StartedWork.value(record, :status) == "landed"
+
+        name = StartedWork.value(record, :branch).to_s
+        name unless name.empty?
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/main_boarding.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/main_boarding"
+
+Hecks.adapter "MainBoarding" do
+  port "MainBoarding"
+end

data/lib/hecks/hecks/adapters/main_boarding.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+require_relative "main_integration"
+require_relative "main_integration/repository"
+require_relative "main_integration/range_guard"
+require_relative "main_integration/train"
+require_relative "main_integration/command_runner"
+
+module Hecks
+  module Adapters
+    # The `MainBoarding` port's adapter for `Integration.Board`: pushes a verified commit of main
+    # by boarding the push train in the train's own copy, and answers the commit the remote holds.
+    #
+    # It refuses, naming why, a run that was not verified, a boarding while another run is being
+    # pushed or watched, and a range carrying an agent's attribution trailer, a release approval or
+    # a version change. A commit other than the head of local main is answered `superseded`: the
+    # run for the head pushes it. It never runs a plain push, a force, a skipped hook or the
+    # owner's override: the train's command line is fixed and the override is not handed on.
+    class MainBoarding
+      class << self
+        # @return [#call, nil] takes `(argv, chdir:)` and answers `[ok, output]`; the command
+        #   runner when nil. A spec replaces it so nothing is pushed.
+        attr_accessor :runner
+
+        # @return [String, nil] the train's copy; `Train::ROOT` when nil
+        attr_accessor :train_root
+      end
+
+      # @param registry [Runtime::Registry, nil] the booted registry whose runs are read
+      # @param aggregate [Object, nil] unused
+      def initialize(registry: nil, aggregate: nil)
+        @registry = registry
+      end
+
+      # @param held [Hash] the `Integration` record: `landed` and `checkout`
+      # @return [Hash{Symbol => Hash}] `outcome:` (`pushed` or `superseded`), `pushed:`, `report:`
+      # @raise [ConsoleCapture::Failure] on any refusal named above, or when the train did not push
+      def embark(**held)
+        landed = plain(held[:landed]).to_s
+        refuse_unboardable!(landed)
+        repository = MainIntegration::Repository.new(checkout_of(held))
+        head = repository.main
+        return superseded(landed, head) unless head == landed
+
+        MainIntegration::RangeGuard.new(repository).check!(repository.remote_main, landed)
+        push(landed, checkout_of(held))
+      end
+
+      private
+
+      def checkout_of(held) = plain(held[:checkout]) || Dir.pwd
+
+      def push(landed, checkout)
+        train = MainIntegration::Train.new(runner, root: self.class.train_root || MainIntegration::Train::ROOT)
+        note = train.refresh
+        record = train.board(checkout)
+        pushed = [record["pushed"], record["boarded"], landed].compact.first
+        { outcome: { value: "pushed" }, pushed: { value: pushed.to_s },
+          report: { value: "#{landed[0, 10]} #{record["status"]} as #{pushed.to_s[0, 10]}; #{note}" } }
+      end
+
+      # The run must have come to boarding from verified (the saga moved it as the boarding
+      # began), and no other run may be being pushed or watched.
+      def refuse_unboardable!(landed)
+        runs = MainIntegration::Runs.new(@registry)
+        run = runs.find(landed) or refuse!("no integration run is keyed by #{landed[0, 10]}")
+        refuse!("#{run.short} is #{run.state}, not verified") unless run.state == "boarding"
+        other = runs.in_flight(except: landed).first
+        refuse!("#{other.short} is #{other.state}; one run boards at a time") if other
+      end
+
+      def refuse!(why) = raise(ConsoleCapture::Failure, "boarding refused: #{why}")
+
+      def superseded(landed, head)
+        report = "#{landed[0, 10]} is not the head of main (#{head[0, 10]}); the run for the head pushes it"
+        { outcome: { value: "superseded" }, report: { value: report } }
+      end
+
+      def runner = self.class.runner || MainIntegration::CommandRunner.new
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/main_integration/checks.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../git_rehearsal/spec_map"
+
+module Hecks
+  module Adapters
+    class MainIntegration
+      # The checks a verification runs in a clean copy of a landed commit, each a launcher command
+      # run there: the quick gate, the specs the changes touch (the changed spec files and the
+      # specs `SpecMap` names for the other changes, in batches of at most `BATCH`), the command
+      # names, the CI pipeline and the generated corpus, the last two only compared. Nothing here
+      # runs the full spec suite.
+      class Checks
+        # The most spec files one launcher call runs, the local cap of the `test_scope` setting.
+        BATCH = 25
+
+        # The most spec files one verification runs; the rest run in CI.
+        LIMIT = 100
+
+        # The launcher, as the copy holds it.
+        LAUNCHER = "exe/hecks"
+
+        # The checks that do not depend on what changed, by name.
+        FIXED = {
+          "quick gate"    => %w[gate_run.gate! stage=quick --wait],
+          "command names" => %w[conformance_run.check_command_names! --wait],
+          "ci pipeline"   => %w[regeneration_run.project_ci_pipeline! check.value=true --wait],
+          "corpus"        => %w[regeneration_run.regenerate_corpus! check.value=true --wait]
+        }.freeze
+
+        # @param directory [String] the clean copy the checks run in
+        # @param changed [Array<String>] the paths the landed range changed, relative to the copy
+        def initialize(directory, changed)
+          @directory = directory
+          @changed = changed
+        end
+
+        # @return [Array<Array(String, Array<String>)>] each check's name and its command line
+        def all
+          named = FIXED.map { |name, args| [name, [LAUNCHER, *args]] }
+          named.first(1) + spec_batches + named.drop(1)
+        end
+
+        # @return [Array<String>] the spec files the checks run, at most `LIMIT`
+        def specs
+          own = @changed.select { |path| path.end_with?("_spec.rb") && File.file?(File.join(@directory, path)) }
+          mapped = GitRehearsal::SpecMap.new(@directory).map(@changed, limit: LIMIT).specs
+          (own | mapped).first(LIMIT)
+        end
+
+        private
+
+        def spec_batches
+          batches = specs.each_slice(BATCH).to_a
+          batches.each_with_index.map do |batch, index|
+            ["specs #{index + 1}/#{batches.size}",
+             [LAUNCHER, "test_suite_run.run_spec_files!", "files.value=#{batch.join(" ")}", "--wait"]]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/main_integration/command_runner.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "hecks/vendoring/git_environment"
+require_relative "../shell"
+
+module Hecks
+  module Adapters
+    class MainIntegration
+      # Runs one command in a directory for an integration step, with the variables that would
+      # point it at another checkout, or let it push as the owner, left out. It answers whether
+      # the command ended well and what it printed.
+      class CommandRunner
+        # The variables of the calling process that are never handed on: Bundler's, which would
+        # run the command against the calling checkout, and the owner's push override.
+        DROPPED = %w[BUNDLE_GEMFILE BUNDLE_BIN_PATH RUBYOPT RUBYLIB HECKS_OWNER_PUSH].freeze
+
+        # @param argv [Array<String>] the command and its arguments
+        # @param chdir [String] the directory it runs in
+        # @return [Array(Boolean, String)] whether it ended with status zero, and what it printed:
+        #   its standard output when it ended well, both streams when it did not
+        def call(argv, chdir:)
+          result = Shell.new.capture(*argv, env: environment, chdir: chdir)
+          [result.ok?, result.ok? ? result.out : "#{result.out}#{result.err}"]
+        end
+
+        private
+
+        def environment = Vendoring::GitEnvironment.clean.merge(DROPPED.to_h { |name| [name, nil] })
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/main_integration/range_guard.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    class MainIntegration
+      # What a boarding refuses to push, read from the range origin/main does not hold: a commit
+      # message with an agent's attribution trailer or a release approval, and a change to the
+      # version file, which is the owner's release decision. Each refusal names what it found.
+      class RangeGuard
+        # The message lines that stop a boarding, each with the name its refusal gives it.
+        FORBIDDEN_LINES = {
+          "a Co-Authored-By: Claude trailer" => /^Co-Authored-By:.*Claude/i,
+          "a Claude-Session trailer"         => /^Claude-Session:/i,
+          "a Release-Approved-By line"       => /^Release-Approved-By:/i
+        }.freeze
+
+        # The file whose change is a release, never boarded by an integration.
+        VERSION_FILE = "lib/hecks/version.rb"
+
+        # @param repository [Repository] the checkout the range is read in
+        def initialize(repository)
+          @repository = repository
+        end
+
+        # @param base [String] the commit the remote holds
+        # @param tip [String] the commit a boarding would push
+        # @return [void]
+        # @raise [ConsoleCapture::Failure] naming the first forbidden line or the version change
+        def check!(base, tip)
+          found = forbidden_line(@repository.messages(base, tip))
+          refuse!(tip, "carries #{found}") if found
+          refuse!(tip, "changes #{VERSION_FILE}, a release") if @repository.changed(base, tip).include?(VERSION_FILE)
+        end
+
+        private
+
+        def forbidden_line(messages)
+          FORBIDDEN_LINES.find { |_name, pattern| messages.any? { |message| message.match?(pattern) } }&.first
+        end
+
+        def refuse!(tip, why)
+          raise ConsoleCapture::Failure, "boarding refused: the range up to #{tip[0, 10]} #{why}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/main_integration/repository.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "../git"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    class MainIntegration
+      # The checkout a run landed in, as an integration step reads it: where local main and
+      # origin/main stand, what a range changed and says, and a clean detached copy of a commit.
+      class Repository
+        # The prefix of the scratch directory a clean copy is made in.
+        COPY_PREFIX = "hecks-main-integration"
+
+        # The files a development checkout keeps for itself and a clean copy must not hold.
+        LOCAL_FILES = "lib/**/*.local.{hecksagon,world}"
+
+        # @param checkout [String] a directory inside the repository
+        def initialize(checkout)
+          @checkout = checkout
+          @git = Git.new
+        end
+
+        # @param ref [String] a branch or commit
+        # @return [String, nil] the full commit it names, nil when it names none
+        def commit(ref)
+          done = @git.capture("rev-parse", "--verify", "--quiet", "#{ref}^{commit}", chdir: @checkout)
+          done.ok? ? done.out.strip : nil
+        end
+
+        # @return [String] the commit local main is at
+        # @raise [ConsoleCapture::Failure] when the checkout has no main
+        def main = commit("main") || raise(ConsoleCapture::Failure, "#{@checkout} has no main branch")
+
+        # @return [String] the commit origin/main is at, as last fetched; main's when none is
+        def remote_main = commit("origin/main") || main
+
+        # @param base [String] the commit the range starts after
+        # @param tip [String] the commit it ends at
+        # @return [Array<String>] the paths the range changed
+        def changed(base, tip) = read("diff", "--name-only", base, tip).split("\n").reject(&:empty?)
+
+        # @return [Array<String>] the message of every commit in the range
+        def messages(base, tip) = read("log", "--format=%B%x1e", "#{base}..#{tip}").split("\x1e").map(&:strip)
+
+        # Yields a clean detached copy of a commit, holding only what the commit tracks, and
+        # removes it once the block ends.
+        #
+        # @param tip [String] the commit to copy
+        # @yieldparam directory [String] the copy
+        # @return [Object] what the block answered
+        def clean_copy(tip)
+          Dir.mktmpdir(COPY_PREFIX) do |scratch|
+            directory = File.join(scratch, "main")
+            read("worktree", "add", "--quiet", "--detach", directory, tip)
+            begin
+              yield refuse_local_files!(directory)
+            ensure
+              @git.capture("worktree", "remove", "--force", directory, chdir: @checkout)
+            end
+          end
+        end
+
+        private
+
+        def refuse_local_files!(directory)
+          found = Dir.glob(LOCAL_FILES, base: directory)
+          raise ConsoleCapture::Failure, "the clean copy holds local files: #{found.join(", ")}" unless found.empty?
+
+          directory
+        end
+
+        def read(*args)
+          done = @git.capture(*args, chdir: @checkout)
+          raise ConsoleCapture::Failure, "git #{args.first} in #{@checkout}: #{done.err.strip}" unless done.ok?
+
+          done.out
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/main_integration/runs.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class MainIntegration
+      # The open and finished runs of the MainIntegration saga, read from the booted registry:
+      # each landed commit, the stage its run is in and the checkout it landed in. Writes nothing.
+      class Runs
+        # The saga whose instances are read.
+        SAGA = "MainIntegration"
+
+        # The stages in which a run is being pushed or watched; only one run may be in them.
+        IN_FLIGHT = %w[boarding pushed ci_running].freeze
+
+        # One run: the landed commit it is keyed by, its stage, and the checkout it landed in.
+        Run = Struct.new(:landed, :state, :checkout) do
+          # @return [String] the commit's first ten characters, for a report
+          def short = landed[0, 10]
+        end
+
+        # @param registry [Runtime::Registry] the booted registry whose saga instances are read
+        def initialize(registry)
+          @registry = registry
+        end
+
+        # @return [Array<Run>] every run the saga remembers, in the order they started
+        def all
+          instances.map { |landed, instance| Run.new(landed.to_s, instance[:state].to_s, checkout_of(instance)) }
+        end
+
+        # @param landed [String] the landed commit
+        # @return [Run, nil] the run keyed by it
+        def find(landed) = all.find { |run| run.landed == landed.to_s }
+
+        # @param landed [String] the run to leave out
+        # @return [Array<Run>] the other runs that are being pushed or watched
+        def in_flight(except: nil) = all.select { |run| run.landed != except.to_s && IN_FLIGHT.include?(run.state) }
+
+        private
+
+        def instances = @registry.saga_instances[SAGA] || {}
+
+        def checkout_of(instance)
+          held = (instance[:memory] || {})[:checkout]
+          held = held[:value] if held.is_a?(Hash)
+          held.respond_to?(:value) ? held.value.to_s : held.to_s
+        end
+      end
+    end
+  end
+end