hecks 7.0.0 → 7.1.0

data/lib/hecks/hecks/adapters/claude_agents.rb

@@ -5,16 +5,18 @@ require_relative "shell"
 require "time"
 require_relative "console_capture"
 require_relative "claude_transcript"
+require_relative "claude_jobs"
+require_relative "claude_agent_list"
 require_relative "dispatching/settings"
 
 module Hecks
   module Adapters
-    # The `Agents` port's adapter for `AgentRun`: finds the directory a session will work in, starts
-    # a background Claude session there with the `claude` command, and reports the state a started
-    # session says it is in.
+    # The `Agents` port's adapter for `AgentRun`: finds the directory a session will work in and the
+    # agents `claude` lists there, starts a background Claude session with the `claude` command,
+    # and reads the state its job is in.
     #
-    # It decides nothing. Whether a brief is enough, whether an agent name is acceptable and which
-    # states mean a session has ended are the bluebook's; this only looks, starts and reads. The
+    # It decides nothing. Whether a brief is enough, whether an agent is listed and which states
+    # are new or mean a session has ended are the bluebook's; this only looks, starts and reads. The
     # command is an argument list, never a string for a shell, and a `--` keeps a brief from being
     # taken for a flag.
     class ClaudeAgents
@@ -24,10 +26,14 @@ module Hecks
       # A background start prints `backgrounded · <id>` first, then how to attach to the session.
       SESSION_ID = /\Abackgrounded\W+([0-9A-Za-z][0-9A-Za-z_-]{5,})/
 
+      # How long a just-started session is given to fail before its job is read, in seconds.
+      SETTLE_SECONDS = 3
+
       # Keeps the command to run, so a spec can point it at a stand-in.
       #
       # @param aggregate [Object, nil] unused
-      # @param settings [Hash] `command:` the program that starts sessions (default `claude`)
+      # @param settings [Hash] `command:` the program that starts sessions (default `claude`),
+      #   `jobs:` the jobs directory, `settle:` the seconds a new session is given to fail
       # @param root [String, nil] unused
       # @param registry [Runtime::Registry, nil] whose Tickets world names the session environment
       def initialize(aggregate: nil, settings: {}, root: nil, registry: nil)
@@ -35,18 +41,24 @@ module Hecks
         @session = Dispatching::Settings.new(registry)
         @shell = Shell.new
         @transcript = ClaudeTranscript.new(**settings.slice(:projects))
+        @jobs = ClaudeJobs.new(directory: settings[:jobs])
+        @agents = ClaudeAgentList.new(@command, shell: @shell)
+        @settle = settings.fetch(:settle, SETTLE_SECONDS)
       end
 
-      # Says the directory a session would work in is there.
+      # Says the directory a session would work in is there, and whether the `claude` there lists
+      # the named agent. With no agent named the session runs `claude`'s default, so nothing is
+      # asked.
       #
-      # @param held [Hash] the `AgentRun` record: `repo`
-      # @return [Hash{Symbol => Hash}] `report:` that the directory is there
-      # @raise [ConsoleCapture::Failure] when it is not a directory
+      # @param held [Hash] the `AgentRun` record: `repo`, and `agent` when one is named
+      # @return [Hash{Symbol => Object}] `report:` that the directory is there, `listed:` whether
+      #   the agent is listed, and `note:` that in words, naming the agents that are
+      # @raise [ConsoleCapture::Failure] when it is not a directory, or `claude` names no agents
       def locate(**held)
         repo = plain(held[:repo])
         raise ConsoleCapture::Failure, "#{repo} is not a directory" unless File.directory?(repo.to_s)
 
-        { report: { value: "#{repo} is a directory" } }
+        { report: { value: "#{repo} is a directory" }, **agent_listing(repo, plain(held[:agent])) }
       end
 
       # Starts a background session in the directory, with the brief as its first prompt.
@@ -64,15 +76,27 @@ module Hecks
         { session: { value: id } }
       end
 
-      # Reads the state a started session reports.
+      # Reads the state a started session's job is in, beside the state the run last recorded.
       #
-      # @param held [Hash] the `AgentRun` record: `session`
-      # @return [Hash{Symbol => String}] `condition:` the state the session reports, as a bare
-      #   string
-      # @raise [ConsoleCapture::Failure] when the sessions cannot be listed or this one is not among
-      #   them
-      def examine(**held)
-        { condition: listed(plain(held[:session]))["state"].to_s }
+      # @param held [Hash] the `AgentRun` record: `session`, `repo`, and the `condition` it holds
+      # @return [Hash{Symbol => String}] `state:` and `detail:` from the job, `previous:` the held
+      #   condition (empty when none), and `checkout:` the run's directory with its trailing slash
+      # @raise [ConsoleCapture::Failure] when the job's state cannot be read
+      def read_job(**held)
+        job = @jobs.state(plain(held[:session]))
+        { state: job["state"].to_s, detail: job["detail"].to_s, previous: plain(held[:condition]).to_s,
+          checkout: File.join(plain(held[:repo]).to_s, "") }
+      end
+
+      # Waits the settling time, then reads the job as {#read_job} does: a session that dies at
+      # once has reported it by then.
+      #
+      # @param held [Hash] the `AgentRun` record, as for {#read_job}
+      # @return [Hash{Symbol => String}] what {#read_job} answers
+      # @raise [ConsoleCapture::Failure] when the job's state cannot be read
+      def await_job(**held)
+        sleep(@settle) if @settle.positive?
+        read_job(**held)
       end
 
       # Says whether a person replied in a session after its brief.
@@ -103,6 +127,13 @@ module Hecks
 
       private
 
+      def agent_listing(repo, agent)
+        return { listed: true, note: "no agent named: the session runs the default agent" } unless agent
+
+        names = @agents.names(repo)
+        { listed: names.include?(agent), note: "agent #{agent} is not available in #{repo}; available: #{names.join(", ")}" }
+      end
+
       def listed(id)
         listing = @shell.capture(@command, "agents", "--json", "--all")
         raise ConsoleCapture::Failure, "#{@command} could not list sessions: #{listing.err.strip}" unless listing.ok?

data/lib/hecks/hecks/adapters/claude_jobs.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The state a background session's job keeps in `~/.claude/jobs/<session>/state.json`: the
+    # `state` it is in (working, blocked, done, failed, stopped) and the `detail` it gave, such as
+    # the question a blocked session waits on or why a failed one stopped.
+    #
+    # It reads and judges nothing: which states are new, and which mean a session ended, are the
+    # bluebook's.
+    class ClaudeJobs
+      # Where the jobs are kept unless a setting names another directory.
+      DIRECTORY = "~/.claude/jobs"
+
+      # @param directory [String, nil] the jobs directory (default `~/.claude/jobs`)
+      def initialize(directory: nil)
+        @directory = File.expand_path(directory || DIRECTORY)
+      end
+
+      # @param session [String] the session's id, which names its job's directory
+      # @return [Hash{String => Object}] the job's state file, parsed
+      # @raise [ConsoleCapture::Failure] when the session names no job, or its state cannot be read
+      def state(session)
+        path = File.join(@directory, session.to_s, "state.json")
+        raise ConsoleCapture::Failure, "no job state at #{path}" if session.to_s.empty? || !File.file?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        raise ConsoleCapture::Failure, "the job state at #{path} cannot be read: #{e.message}"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/corpus_queries.rb

@@ -3,7 +3,8 @@
 module Hecks
   module Adapters
     class SourceTree
-      # The `SourceTree` queries that read the corpus of domains: which have Rust, the order regeneration
+      # The `SourceTree` queries that read the corpus of domains: which have Rust, the order
+      # regeneration
       # walks them in, and what the IR and its propagation touchpoints say. Each is answered through
       # `corpus`, which the includer provides.
       module CorpusQueries

data/lib/hecks/hecks/adapters/codebase/minitest_runs.rb

@@ -5,7 +5,8 @@ require "open3"
 module Hecks
   module Adapters
     module Codebase
-      # The minitest files of a spec directory. RSpec does not run them, so each one runs in its own Ruby
+      # The minitest files of a spec directory. RSpec does not run them, so each one runs in its own
+      # Ruby
       # process, and its run summary is reported beside the RSpec output.
       module MinitestRuns
         # The summary line minitest prints, such as "3 runs, 5 assertions".
@@ -19,7 +20,8 @@ module Hecks
           Dir.glob("#{TestSuite::SPEC_DIRECTORY}/**/*_test.rb", base: tree.root).sort
         end
 
-        # Runs each file in its own Ruby process, from the folder, outside this process's bundle so the
+        # Runs each file in its own Ruby process, from the folder, outside this process's bundle so
+        # the
         # folder's own gems are the ones it loads.
         #
         # @param tree [Tree] the folder the files run in

data/lib/hecks/hecks/adapters/codebase/run_options.rb

@@ -3,7 +3,8 @@
 module Hecks
   module Adapters
     module Codebase
-      # What a spec run's arguments become: the variables the specs read, and the flags a stress run takes.
+      # What a spec run's arguments become: the variables the specs read, and the flags a stress run
+      # takes.
       # A person names them in a request, so they never set them in a shell.
       module RunOptions
         module_function

data/lib/hecks/hecks/adapters/codebase/test_suite.rb

@@ -20,11 +20,11 @@ module Hecks
       # The tooling owns its options, so each ask runs one of the `Hecks::Tools` commands in this
       # process from the checkout's root, except a single example (the `TestRunner` adapter runs it)
       # and the persistence fixtures (the `SqliteFixture` adapter). A listing is a pure read.
-      # Refreshing the committed timings, regenerating the fixtures and writing the committed spec
-      # list change tracked files, so unconfirmed they report what they would do and write nothing.
+      # Regenerating the fixtures and writing the committed spec list change tracked files, so
+      # unconfirmed they report what they would do and write nothing.
       module TestSuite
         # Every operation this family carries out.
-        OPERATIONS = %w[refresh_runtime_baseline run_spec_example run_spec_files run_impacted_specs run_suite run_changed
+        OPERATIONS = %w[run_spec_example run_spec_files run_impacted_specs run_suite run_changed
                         stress_concurrency run_cargo_tests clear_caches regenerate_legacy_fixtures seed_semantics_corpus
                         write_io_parallel_spec_list].freeze
 
@@ -38,9 +38,6 @@ module Hecks
         # The tag filter the postgres job lists its specs by when none is named.
         DEFAULT_TAGS = "--tag io --tag ~fuzzing"
 
-        # The committed files a baseline refresh writes.
-        BASELINES = %w[.github/rspec_runtime_baseline.log .github/postgres_io_runtime_baseline.log].freeze
-
         module_function
 
         # Loads the command a `Hecks::Tools` file defines, the first time an ask needs it: several
@@ -79,7 +76,6 @@ module Hecks
         # @return [String] what the tool printed
         def tooling(operation, args, tree, shell)
           case operation
-          when "refresh_runtime_baseline" then refresh(args, tree)
           when "stress_concurrency" then stress(args, tree)
           when "regenerate_legacy_fixtures" then regenerate_fixtures(args, tree, shell)
           when "seed_semantics_corpus" then seed(args, tree)
@@ -204,18 +200,6 @@ module Hecks
         # @return [Array<String>] the tag filter, one word each
         def tag_words(args) = (args[:tags] || DEFAULT_TAGS).split
 
-        # @param args [Hash] `workers` and `from_run`
-        # @param tree [Tree] the checkout whose baselines are rewritten
-        # @return [String] what was written, or (unconfirmed) what would be
-        # @raise [ConsoleCapture::Failure] when the refresh ends badly
-        def refresh(args, tree)
-          source = args[:from_run] ? ["--from-run", args[:from_run]] : [*args[:workers]&.to_s]
-          return answer { command("refresh_rspec_runtime_baseline").call(source, root: tree.root) } if args[:confirm] == true
-
-          "dry run, would #{args[:from_run] ? "read CI run #{args[:from_run]}'s timings" : "time a local run"} " \
-            "and rewrite #{BASELINES.join(", ")} (add --confirm)"
-        end
-
         # @param args [Hash] `exclude`, `tags`, `write` and `confirm`
         # @param tree [Tree] the checkout whose spec list is written
         # @return [String] what was written, or (unconfirmed) how many files would be

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

@@ -3,12 +3,14 @@
 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
+      # 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
+        SECTIONS = %w[rules review verification workflow landing restraints report].freeze
 
         # @param brief [Hash] the composed brief: its attribute values by name
         def initialize(brief)

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

@@ -20,7 +20,8 @@ module Hecks
         # 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 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

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

@@ -5,11 +5,14 @@ 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
+      # 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,
+      # 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.
@@ -38,7 +41,8 @@ module Hecks
           planned.each { |row| consider(row) }
         end
 
-        # @return [Array<Row>] the started rows and the chosen ones: whose areas are not to be edited
+        # @return [Array<Row>] the started rows and the chosen ones: whose areas are not to be
+        #   edited
         def holders = @started + @chosen
 
         private

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

@@ -53,7 +53,8 @@ module Hecks
         # @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
+        # @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

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

@@ -3,8 +3,10 @@
 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,
+      # 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

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

@@ -9,7 +9,8 @@ require_relative "dispatching/settler"
 
 module Hecks
   module Adapters
-    # The `Dispatching` port's adapter for `Dispatch`: reads the Work queue and the machine, says which
+    # 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
@@ -18,7 +19,8 @@ module Hecks
     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 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
@@ -28,7 +30,8 @@ module Hecks
       # 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
+      # @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

data/lib/hecks/hecks/adapters/doctor_reading.rb

@@ -50,7 +50,8 @@ module Hecks
         [directory, Dir.pwd].uniq.flat_map { |where| Dir[File.join(where, "*.local.{world,hecksagon}")] }.uniq
       end
 
-      # The first line of a compile error, or nil when the file is valid Ruby. Compiling never runs it.
+      # The first line of a compile error, or nil when the file is valid Ruby. Compiling never runs
+      # it.
       def syntax_error(path)
         RubyVM::InstructionSequence.compile(File.read(path), path)
         nil
@@ -124,7 +125,8 @@ module Hecks
         row("store", :fail, "#{adapter} directory #{dir} is missing", "mkdir -p #{dir}")
       end
 
-      # Postgres reachable, and the role the URL names exists; a read of the catalog, nothing written.
+      # Postgres reachable, and the role the URL names exists; a read of the catalog, nothing
+      # written.
       def reach(url)
         require "pg"
         PG.connect(url, connect_timeout: 3) { |conn| role_row(conn, URI.parse(url).user) }

data/lib/hecks/hecks/adapters/git_landing/carried.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # How a branch stands against the branch it was cut for: whether `onto` carries its commits,
+      # by
+      # id or by patch, and what a discard says it dropped.
+      #
+      # Mixed into `Tidy`, which supplies `@onto`, `@discarding`, `@checkout`, `count`, `ancestor?`
+      # and
+      # `read`.
+      module Carried
+        private
+
+        def unmerged(tip)
+          return "it has no commit to verify" unless tip
+          return if @discarding
+
+          local = "refs/heads/#{@onto}"
+          return unless count("#{local}..#{tip}").positive? || !ancestor?(tip, local)
+
+          lacking = unmatched(local, tip)
+          "it has #{lacking} commit(s) not on #{@onto}" if lacking.positive?
+        end
+
+        # How many commits the branch adds that `onto` carries under no id and no patch: `git cherry`
+        # marks one `onto` has a patch-equivalent of with `-`, and one it lacks with `+`.
+        def unmatched(local, tip)
+          read("cherry", local, tip, dir: @checkout).lines.count { |line| line.start_with?("+") }
+        end
+
+        # What a discard says it dropped, so the commits can be found again by their tip.
+        def discarded_note(tip)
+          return unless @discarding
+
+          "it was at #{tip} with #{unmatched("refs/heads/#{@onto}", tip)} commit(s) not on #{@onto}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_landing/finisher.rb

@@ -7,7 +7,8 @@ require_relative "../shell"
 module Hecks
   module Adapters
     class GitLanding
-      # The steps before a landing that an agent used to run by hand: refuse unsaved work, rebase the
+      # The steps before a landing that an agent used to run by hand: refuse unsaved work, rebase
+      # the
       # branch onto local `main`, and run the quick gate in the branch's worktree.
       #
       # Each step refuses by name at the first failure, with the reason, and leaves the branch as it

data/lib/hecks/hecks/adapters/git_landing/flagged.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../red_flag_guard"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # What landing on main asks beyond any other landing: a base that is not behind origin, and
+      # no standing red flag unless the branch is a red row's fix. A fix that lands records its tip
+      # on the flag so the push train may board it. The including class answers `common_git_dir`,
+      # `@git` and `refuse_stale_base`.
+      module Flagged
+        private
+
+        # @return [Object] what the block answers, run only after main's checks pass
+        def on_main(branch, onto)
+          return yield unless onto == "main"
+
+          refuse_stale_base(branch)
+          git_dir = common_git_dir
+          guard = RedFlagGuard.new(git_dir)
+          guard.landing!(branch)
+          yield.tap { guard.landed(branch, tip(git_dir)) }
+        end
+
+        # Main's commit, read against the git directory: the worktree a finish lands from is gone
+        # by now.
+        def tip(git_dir) = @git.capture("--git-dir=#{git_dir}", "rev-parse", "main").out.strip
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_landing/tidy.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../git_worktrees"
+require_relative "carried"
 
 module Hecks
   module Adapters
@@ -10,11 +11,14 @@ module Hecks
       # When in doubt it keeps both. It removes them only when the worktree is a linked one that
       # nobody stands in, holds no file that is not tracked and clean (ignored files and build
       # output count, so a local `.env` is never lost), and its branch tip, verified once, is
-      # contained in local `onto`. The worktree goes without `--force`, and the branch goes only
-      # while it still names the verified tip, so a commit made in between is never dropped.
+      # contained in local `onto` or every commit it adds has a patch-equivalent there (a rebase or
+      # a cherry-pick carries a commit under another id). The worktree goes without `--force`, and
+      # the branch goes only while it still names the verified tip, so a commit made in between is
+      # never dropped.
       # `main`, `stable`, `edge`, the target and a branch another worktree holds are never deleted.
       class Tidy
         include GitWorktrees
+        include Carried
 
         # Branches no tidy deletes, whatever they contain.
         PROTECTED = %w[main stable edge].freeze
@@ -26,14 +30,17 @@ module Hecks
         # @param checkout [String] the repository's top level
         # @param branch [String] the landed branch
         # @param onto [String] the branch it was landed on
-        # @param retiring [Boolean] whether `checkout` is the very worktree to retire
-        def initialize(git, checkout, branch:, onto:, retiring: false)
+        # @param mode [Symbol] `:land` tidies after a landing, `:retire` removes the worktree named
+        #   by `checkout`, `:discard` does that although `onto` lacks the branch's commits; every
+        #   other guard holds, and the sentence names the tip it was at
+        def initialize(git, checkout, branch:, onto:, mode: :land)
           @git = git
           @checkout = checkout
           @from = checkout
           @branch = ref(branch)
           @onto = ref(onto)
-          @retiring = retiring
+          @retiring = mode != :land
+          @discarding = mode == :discard
         end
 
         # @return [String] a sentence saying what was removed, or why nothing was
@@ -49,7 +56,21 @@ module Hecks
           tree = worktree_on(@branch)
           tip = tree && branch_tip(@branch)
           why = reason_to_keep(tree, tip)
-          why ? [true, why] : drop(tree.path, tip)
+          return [true, why] if why
+
+          note = discarded_note(tip)
+          kept, said = drop(tree.path, tip)
+          [kept, kept || !@discarding ? said : "#{said}; #{note}"]
+        end
+
+        # What `retire` would do, said and not done: it removes nothing and takes no lock.
+        #
+        # @return [String] "would retire it", or "would keep it: " and why
+        def verdict
+          @checkout = primary.path
+          tree = worktree_on(@branch)
+          why = reason_to_keep(tree, tree && branch_tip(@branch))
+          why ? "would keep it: #{why}" : "would retire it"
         end
 
         private
@@ -89,14 +110,6 @@ module Hecks
           lines.size > NAMED ? "#{shown} and #{lines.size - NAMED} more" : shown
         end
 
-        def unmerged(tip)
-          return "it has no commit to verify" unless tip
-
-          local = "refs/heads/#{@onto}"
-          behind = count("#{local}..#{tip}")
-          "it has #{behind} commit(s) not on #{@onto}" if behind.positive? || !ancestor?(tip, local)
-        end
-
         def drop(path, tip)
           return [true, "#{@branch} moved after it was checked"] unless branch_tip(@branch) == tip
 

data/lib/hecks/hecks/adapters/git_landing.rb

@@ -7,6 +7,7 @@ require_relative "git_landing/tidy"
 require_relative "git_landing/rivals"
 require_relative "git_landing/finisher"
 require_relative "git_landing/lineup"
+require_relative "git_landing/flagged"
 require_relative "../../indifferent_key"
 
 module Hecks
@@ -19,6 +20,7 @@ module Hecks
     class GitLanding
       include GitWorktrees
       include GitMainPull
+      include Flagged
 
       # Accepts the arguments every driven adapter is built with; only the registry and the
       # overrides are kept.
@@ -96,16 +98,20 @@ module Hecks
       # @raise [ConsoleCapture::Failure] when anything makes keeping it the safe answer: the primary
       #   worktree, one the process stands in, any file not tracked and clean (ignored included), a
       #   branch with commits `onto` lacks or a protected branch, or git refusing the removal
-      def remove(**held)
-        settle(held)
-        branch = plain(held[:branch]) || current_branch
-        onto = plain(held[:onto]) || "main"
-        gone = @checkout
-        kept, said = Tidy.new(@git, @checkout, branch: branch, onto: onto, retiring: true).retire
-        raise ConsoleCapture::Failure, "#{gone} is kept: #{said}" if kept
+      def remove(**held) = take_down(held, :retire, "retired")
 
-        { outcome: { value: "retired" }, checkout: { value: gone }, branch: { value: branch },
-          report: { value: said } }
+      # Removes a linked worktree and deletes its branch although `onto` lacks the branch's commits.
+      #
+      # Every other guard of `remove` holds: the primary worktree, one the process stands in, any
+      # file not tracked and clean, a protected branch and a branch that moved are all refused. The
+      # answer names the tip the branch was at and how many commits `onto` lacked, so they can be
+      # found again, and the reason the caller gave.
+      #
+      # @param held [Hash] the `Landing` record: `checkout`, `branch`, `onto` and `reason`
+      # @return [Hash{Symbol => Hash}] `outcome:` (`discarded`), `checkout:`, `branch:`, `report:`
+      # @raise [ConsoleCapture::Failure] when anything makes keeping it the safe answer
+      def drop_branch(**held)
+        take_down(held, :discard, "discarded") { |said| "#{said}; reason: #{plain(held[:reason])}" }
       end
 
       # The branches whose commits are not on a branch, or that hold uncommitted work.
@@ -124,6 +130,17 @@ module Hecks
 
       private
 
+      def take_down(held, mode, outcome)
+        settle(held)
+        branch = plain(held[:branch]) || current_branch
+        gone = @checkout
+        kept, said = Tidy.new(@git, @checkout, branch: branch, onto: plain(held[:onto]) || "main", mode: mode).retire
+        raise ConsoleCapture::Failure, "#{gone} is kept: #{said}" if kept
+
+        { outcome: { value: outcome }, checkout: { value: gone }, branch: { value: branch },
+          report: { value: block_given? ? yield(said) : said } }
+      end
+
       # One landing from another worktree, as the train makes it for a waiting branch.
       def land_for(checkout, branch, onto)
         mine = @checkout
@@ -135,9 +152,8 @@ module Hecks
 
       def land_alone(branch, onto, note)
         refuse_unsaved(branch)
-        refuse_stale_base(branch) if onto == "main"
         refuse_rival(branch, onto)
-        said = tidy(Merger.new(@git, @checkout, branch: branch, onto: onto).land, branch, onto)
+        said = on_main(branch, onto) { tidy(Merger.new(@git, @checkout, branch: branch, onto: onto).land, branch, onto) }
         note ? said.merge(report: { value: "#{said[:report][:value]}; #{note}" }) : said
       end
 
@@ -159,11 +175,12 @@ module Hecks
         landed.merge(report: { value: "#{landed[:report][:value]}; #{said}" })
       end
 
-      # A finish runs inside the worktree it retires, so the process leaves it first; a worktree that
+      # A finish runs inside the worktree it retires, so the process leaves it first; a worktree
+      # that
       # holds ignored files is kept and said so.
       def retire_from_primary(branch, onto)
         Dir.chdir(primary.path) do
-          kept, said = Tidy.new(@git, @checkout, branch: branch, onto: onto, retiring: true).retire
+          kept, said = Tidy.new(@git, @checkout, branch: branch, onto: onto, mode: :retire).retire
           kept ? "kept #{branch}: #{said}" : said
         end
       end

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