openlanes 3.0.1 → 3.1.0

data/lib/openlanes/vcs/publisher.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "open3"
 require "tempfile"
 require "tty/command"
 
@@ -35,13 +36,23 @@ module OpenLanes
       # @!attribute [r] updated
       #   @return [Boolean] whether the push went to a pull request the plan
       #     already had open, rather than opening a new one
-      Publication = Data.define(:ordinal, :branch, :title, :url, :refusal, :updated) do
-        def initialize(updated: false, **rest) = super
+      # @!attribute [r] label_error
+      #   @return [String, nil] why `ready-for-review` could not be applied; the
+      #     pull request stays open regardless (open question 4)
+      Publication = Data.define(:ordinal, :branch, :title, :url, :refusal, :updated, :label_error) do
+        def initialize(updated: false, label_error: nil, **rest) = super
 
         # @return [Boolean]
         def published? = !url.nil?
+
+        # @return [Boolean] whether it was refused for want of `## How to test`,
+        #   which an agent can write, unlike a rejected push
+        def untestable? = refusal == UNTESTABLE
       end
 
+      # Why a pull request nobody could test is not opened.
+      UNTESTABLE = "publish refused — plan.md has no `#{Lifecycle::Completion::HOW_TO_TEST}` section".freeze
+
       # A..Z, which is more parts than any feature should be split into.
       LETTERS = ("A".."Z").to_a.freeze
 
@@ -89,6 +100,9 @@ module OpenLanes
           return refuse(subject, checkout, title, "nothing to publish — the worktree is unchanged")
         end
 
+        untestable = open.nil? && missing_how_to_test(subject)
+        return refuse(subject, checkout, title, untestable) if untestable
+
         return Publication.new(**base_fields(subject, checkout, title), url: nil, refusal: nil) if @dry_run
 
         mismatch = open && head_mismatch(open, checkout)
@@ -98,12 +112,82 @@ module OpenLanes
         commit(checkout, title)
         push(checkout)
         url = open ? open.url : create_pull_request(checkout, subject, title)
+        label_error = url.nil? ? nil : label_for_review(url, resubmitted: !open.nil?)
 
-        Publication.new(**base_fields(subject, checkout, title), url:, refusal: nil, updated: !open.nil?)
+        Publication.new(**base_fields(subject, checkout, title), url:, refusal: nil, updated: !open.nil?, label_error:)
       rescue TTY::Command::ExitError => e
         refuse(subject, checkout, title, git_complaint(e))
       end
 
+      # Why a push from this checkout would not reach the pull request, as
+      # {#publish} asks before pushing. `pull-requests.md` does not record a
+      # head branch, and an adopted or hand-opened pull request can come from
+      # any branch, while the checkout's branch is derived from the plan.
+      # Verification asks it too, before chewie runs and before its commit:
+      # otherwise it verifies one branch's code, pushes screenshots to it,
+      # and labels a pull request built from another.
+      #
+      # @param pull [OpenLanes::Plans::PullRequest] an open pull request
+      # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
+      # @param refused [String] how the sentence starts
+      # @return [String, nil] nil when the pull request is built from the checkout's branch
+      def branch_mismatch(pull, checkout, refused: "refused") = head_mismatch(pull, checkout, refused:)
+
+      # Paths named in a {#commit_plan} refusal before the rest are counted.
+      STRAY_SHOWN = 10
+
+      # Commit the plan's folder, and nothing else, to the checkout's branch and
+      # push it. Verification uses it to land chewie's screenshots on the pull
+      # request before the engine links them by SHA.
+      #
+      # It refuses a checkout with changes outside the plan folder: chewie
+      # writes `verification/**` and nothing more, so a stray code edit is
+      # something it should not have made, and committing it here would slip
+      # unreviewed code into a pull request that already passed review. Nor is
+      # it a resubmit, so the review labels are left exactly as they are.
+      #
+      # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
+      # @param plan [OpenLanes::Plans::Subject] the plan in the main checkout
+      # @param message [String] the commit subject
+      # @return [String, nil] the new commit's SHA, nil on a dry run
+      # @raise [OpenLanes::Error] on a stray change, a pull request built from
+      #   another branch, or nothing to commit
+      def commit_plan(checkout:, plan:, message:)
+        folder = plan_parent(plan)
+        raise Error, "the plans live outside the repository, so the branch has no place for them" if folder.nil?
+
+        stray = changed_paths(checkout).reject { |path, _| inside_plan?(path, folder, plan) }
+        raise Error, stray_complaint(plan, stray) if stray.any?
+        return nil if @dry_run
+
+        open = plan.pull_requests.select(&:open?).last
+        mismatch = open && branch_mismatch(open, checkout, refused: "refused to commit #{plan.feature.ordinal}")
+        raise Error, mismatch if mismatch
+
+        carry_plan(checkout, plan)
+        run(checkout, "git", "add", "-A", "--", folder)
+        raise Error, "nothing to commit for #{plan.feature.ordinal}" if run!(checkout, "git", "diff", "--cached", "--quiet").success?
+
+        run(checkout, "git", "commit", "-m", message)
+        sha = run(checkout, "git", "rev-parse", "HEAD").out.strip
+        pushed!(checkout, sha)
+        sha
+      rescue TTY::Command::ExitError => e
+        raise Error, git_complaint(e)
+      end
+
+      # A commit that stayed on this machine is said as one: "not committed"
+      # would send someone looking for a change that is right there in the
+      # checkout, waiting for the next push to carry it.
+      #
+      # @return [void]
+      # @raise [OpenLanes::Error] when the push fails
+      def pushed!(checkout, sha)
+        push(checkout)
+      rescue TTY::Command::ExitError => e
+        raise Error, "committed #{sha[0, 7]} locally, but the push failed: #{git_complaint(e)}"
+      end
+
       # git and gh put the useful sentence in stderr, several lines below the
       # command they echo. Reporting only the first line reports "it failed".
       #
@@ -144,7 +228,7 @@ module OpenLanes
       # The main checkout stays the only writer. The engine reads, signs and
       # renames the plan there and nowhere else; the worktree gets a snapshot,
       # refreshed on every publish. Every copy of the same plan number is
-      # removed first, so a folder renamed since the last publish (⭐️ to 🟢,
+      # removed first, so a folder renamed since the last publish (⭐ to 🟢,
       # say) does not leave its old name behind in the branch, and a file
       # deleted in the main checkout is deleted in the branch too.
       #
@@ -172,6 +256,64 @@ module OpenLanes
 
       private
 
+      # @param plan [OpenLanes::Plans::Subject]
+      # @return [String, nil] the plans directory relative to the repository,
+      #   nil when the plans live outside it
+      def plan_parent(plan)
+        root = real(@root)
+        source = real(plan.feature.path)
+        source.start_with?("#{root}/") ? File.dirname(source.delete_prefix("#{root}/")) : nil
+      end
+
+      # Every path git sees changed, untracked files included. `-z` keeps an
+      # emoji folder name unquoted; a rename's second entry is its old path.
+      #
+      # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
+      # @return [Hash{String => Boolean}] each path, and whether git does not
+      #   track it
+      def changed_paths(checkout)
+        entries = run(checkout, "git", "status", "--porcelain", "-z", "--untracked-files=all").out.split("\0")
+        paths = {}
+        until entries.empty?
+          entry = entries.shift
+          paths[entry[3..]] = entry.start_with?("??")
+          paths[entries.shift] = false if entry.start_with?("R", "C")
+        end
+        paths.reject { |path, _| path.nil? }
+      end
+
+      # Running the app in the checkout leaves files behind that a project
+      # may never have ignored (logs, `tmp/`, a SQLite file, `coverage/`),
+      # and each one refuses every verification commit until it is. So the
+      # refusal names them, apart from edits to tracked files, and says what
+      # to do about them; "changes outside its plan folder" alone reads as a
+      # stray code edit and sends someone looking for one.
+      #
+      # @param plan [OpenLanes::Plans::Subject]
+      # @param stray [Hash{String => Boolean}] see {#changed_paths}
+      # @return [String]
+      def stray_complaint(plan, stray)
+        untracked, edited = stray.partition { |_, new| new }.map { |pairs| pairs.map(&:first) }
+        parts = []
+        parts << "edited #{shown(edited)}" if edited.any?
+        parts << "untracked #{shown(untracked)} (left by the app or its tests? add them to .gitignore)" if untracked.any?
+        "refused to commit #{plan.feature.ordinal}: changes outside its plan folder: #{parts.join("; ")}"
+      end
+
+      # @param paths [Array<String>]
+      # @return [String]
+      def shown(paths)
+        more = paths.size - STRAY_SHOWN
+        "#{paths.first(STRAY_SHOWN).join(", ")}#{" and #{more} more" if more.positive?}"
+      end
+
+      # @return [Boolean] whether `path` lies in any copy of this plan's folder
+      def inside_plan?(path, folder, plan)
+        return false unless path.start_with?("#{folder}/")
+
+        Plans::Ordinal.from_dirname(path.delete_prefix("#{folder}/").split("/").first) == plan.feature.ordinal
+      end
+
       # @param path [String]
       # @return [String] symlinks resolved, so /var and /private/var compare equal
       def real(path)
@@ -202,14 +344,14 @@ module OpenLanes
       # @param open [OpenLanes::Plans::PullRequest]
       # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
       # @return [String, nil] nil when the pull request is built from the checkout's branch
-      def head_mismatch(open, checkout)
+      def head_mismatch(open, checkout, refused: "publish refused")
         head = @github.pull_request(open.number || open.url).fetch(:branch)
         return if head == checkout.branch
 
-        "publish refused — ##{open.number} is built from #{head.empty? ? "an unknown branch" : head}, " \
+        "#{refused} — ##{open.number} is built from #{head.empty? ? "an unknown branch" : head}, " \
           "not #{checkout.branch}, so a push would not reach it"
       rescue Error => e
-        "publish refused — could not tell which branch ##{open.number} is built from: #{e.message}"
+        "#{refused} — could not tell which branch ##{open.number} is built from: #{e.message}"
       end
 
       # @return [Hash]
@@ -232,9 +374,42 @@ module OpenLanes
         run(checkout, "git", "commit", "-m", title.sub(/\A\[[^\]]+\](?:\([A-Z]\))?\s*/, ""))
       end
 
+      # The branch is the checkout's own, named by {Worktree#branch_for} and
+      # written only by this harness, so after the harness has rebased it
+      # (see {Refresh}) it may replace what `origin` holds. The lease alone
+      # is not enough: it trusts the tracking ref, and worktrees share
+      # `refs/remotes` with the main checkout, so a fetch there (an editor's
+      # auto-fetch, `gh pr checkout`) moves it onto somebody else's push and
+      # the lease would then let us overwrite it. `--force-if-includes` adds
+      # that the tracking ref's tip must be in this branch's own reflog,
+      # i.e. a commit the harness had here. It is a no-op beside an explicit
+      # `:<expect>`, so the lease names only the ref. A branch with no
+      # tracking ref yet gets a plain push, which can only fast-forward.
+      #
       # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
       # @return [void]
-      def push(checkout) = run(checkout, "git", "push", "-u", "origin", checkout.branch)
+      def push(checkout)
+        # Declared first, so an agent still running in another worktree is
+        # not blamed for the tracking ref this push moves under it.
+        Execution::Boundary.sanction(checkout.path, "origin", checkout.branch)
+        run(checkout, "git", "push", *lease(checkout), "-u", "origin", checkout.branch)
+      end
+
+      # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
+      # @return [Array<String>] the lease flags, or nothing
+      def lease(checkout)
+        # Read directly rather than through {#run}: it is a local lookup that
+        # changes nothing, and the command seam is for what leaves the machine.
+        seen, = Open3.capture2("git",
+          "-C",
+          checkout.path,
+          "rev-parse",
+          "--verify",
+          "--quiet",
+          "refs/remotes/origin/#{checkout.branch}",
+          err: File::NULL)
+        seen.strip.empty? ? [] : ["--force-with-lease=refs/heads/#{checkout.branch}", "--force-if-includes"]
+      end
 
       # @return [String, nil] the pull request URL
       def create_pull_request(checkout, subject, title)
@@ -263,9 +438,49 @@ module OpenLanes
 
           Implements `#{subject.feature.dirname}`. The specification and the plan
           for this work live in that folder.
+
+          #{Lifecycle::Completion::HOW_TO_TEST}
+
+          #{how_to_test(subject)}
         MARKDOWN
       end
 
+      # A pull request a person cannot test is not ready for one to review.
+      #
+      # @return [String, nil] the refusal, or nil when plan.md has the section
+      def missing_how_to_test(subject)
+        UNTESTABLE if how_to_test(subject).empty?
+      end
+
+      # A plan.md written before the rename says `## How to verify`; the
+      # harness no longer appends a duplicate to it, so its steps are read
+      # here under either heading rather than refused.
+      #
+      # @return [String] the section's body, without its heading
+      def how_to_test(subject)
+        headings = [Lifecycle::Completion::HOW_TO_TEST, Lifecycle::Completion::FORMER_HOW_TO_TEST]
+        lines = subject.read("plan.md").to_s.lines
+        start = lines.index { |l| headings.any? { l.strip.casecmp?(it) } } or return ""
+        lines[(start + 1)..].take_while { |l| !l.start_with?("## ", "# ") }.join.strip
+      end
+
+      # Put `ready-for-review` on the pull request. A resubmission also takes
+      # off whatever verdict the last review left: a `review-rejected` still
+      # there after the fixes are pushed reads to the watch as a fresh
+      # rejection, and the 🟢 plan would be sent straight back to 🔴.
+      #
+      # @param url [String]
+      # @param resubmitted [Boolean] whether the pull request was already open
+      # @return [String, nil] the error, when labelling failed
+      def label_for_review(url, resubmitted: false)
+        number = GitHub.number_of(url)
+        remove = resubmitted ? Plans::ReviewLabel.known : []
+        @github.swap_label(number:, repo: GitHub.repo_of(url), add: Plans::ReviewLabel::INITIAL, remove:)
+        nil
+      rescue Error => e
+        e.message
+      end
+
       # The specification's own Goal section, verbatim. A pull request body that
       # paraphrases the spec is a second copy that drifts; quoting it is not.
       #
@@ -278,6 +493,9 @@ module OpenLanes
 
       # @return [TTY::Command::Result]
       def run(checkout, *argv) = @command.run(*argv, chdir: checkout.path)
+
+      # @return [TTY::Command::Result] whatever the exit status
+      def run!(checkout, *argv) = @command.run!(*argv, chdir: checkout.path)
     end
   end
 end

data/lib/openlanes/vcs/refresh.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module OpenLanes
+  module Vcs
+    # Brings one plan's worktree up to date with the default branch on
+    # `origin`, before an agent runs in it.
+    #
+    # A worktree reused round after round never moved: plan 008.01's branch
+    # had no commits of its own and sat 211 commits behind origin/main, so
+    # luke-backend went looking for code that had landed weeks earlier and
+    # could not find it. The agent could not catch up on its own either,
+    # because the boundary fails every run in which HEAD moved. So the
+    # harness moves HEAD, here, before {Execution::Boundary} takes its
+    # snapshot, and the agent's HEAD check still holds.
+    #
+    # Three cases, by what the branch carries:
+    #
+    # - nothing of its own: fast-forward. No agent is ever involved.
+    # - commits of its own, a clean tree: `git rebase`. A conflict leaves the
+    #   rebase stopped for an agent to resolve; the harness continues it.
+    # - uncommitted changes and commits of its own: left alone. Rebasing
+    #   needs a clean tree, and `--autostash` can strand an agent's
+    #   uncommitted work in the stash when it fails to re-apply, which is
+    #   exactly the silent loss worktrees exist to prevent.
+    #
+    # Nothing here commits anything of its own; `rebase --continue` replays
+    # commits that already exist, with the resolution an agent staged.
+    class Refresh
+      # The remote every plan branch is published to.
+      REMOTE = "origin"
+
+      # The default branch when `origin/HEAD` names none, as in a clone made
+      # with `git init` and `remote add` rather than `git clone`.
+      FALLBACK = "main"
+
+      # How git says a staged file still holds a conflict marker. `diff
+      # --check` also reports whitespace, which is no reason to stop a rebase.
+      MARKER = "leftover conflict marker"
+
+      # Seconds a fetch may take before it is abandoned. It runs on the
+      # dispatcher's tick thread, so a fetch stuck on a credential prompt or
+      # a stalled socket would stop every lane on the machine.
+      FETCH_TIMEOUT = 60
+
+      # git and ssh must fail rather than ask: nobody is there to answer.
+      # BatchMode is appended to the user's own ssh command, not put in its
+      # place, so a configured key or jump host still applies.
+      #
+      # @return [Hash{String => String}]
+      def self.fetch_env
+        { "GIT_TERMINAL_PROMPT" => "0", "GIT_SSH_COMMAND" => "#{ENV.fetch("GIT_SSH_COMMAND", "ssh")} -o BatchMode=yes" }
+      end
+
+      # What one refresh did.
+      #
+      # @!attribute [r] kind
+      #   @return [Symbol] :current, :fast_forwarded, :rebased, :conflicted,
+      #     :skipped, :pending or :aborted. Only :conflicted leaves a rebase
+      #     stopped; a :skipped from {#continue} still has one, for the
+      #     caller to abort
+      # @!attribute [r] base
+      #   @return [String, nil] e.g. "origin/main"
+      # @!attribute [r] target
+      #   @return [String, nil] the commit `base` named, so a retry can tell
+      #     whether the default branch has moved since
+      # @!attribute [r] commits
+      #   @return [Integer] how many commits the branch was behind
+      # @!attribute [r] files
+      #   @return [Array<String>] the conflicted paths, when it stopped
+      # @!attribute [r] reason
+      #   @return [String, nil] why nothing happened, for :skipped and :pending
+      Outcome = Data.define(:kind, :base, :target, :commits, :files, :reason) do
+        def initialize(base: nil, target: nil, commits: 0, files: [], reason: nil, **rest) = super
+
+        # @return [Boolean] the rebase is stopped, waiting on a resolution
+        def conflicted? = kind == :conflicted
+
+        # @return [Boolean] the branch now sits on the latest default branch
+        def done? = %i[current fast_forwarded rebased].include?(kind)
+
+        # One line for the progress log.
+        #
+        # @return [String]
+        def summary
+          case kind
+          when :current then "worktree: up to date with #{base}"
+          when :fast_forwarded then "worktree: fast-forwarded #{commits} commit#{"s" unless commits == 1} to #{base}"
+          when :rebased then "worktree: rebased onto #{base} (#{commits} new upstream commit#{"s" unless commits == 1})"
+          when :conflicted then "worktree: rebase onto #{base} stopped on conflicts in #{files.join(", ")}"
+          when :aborted then "worktree: rebase onto #{base} aborted, branch restored: #{reason}"
+          when :pending then "worktree: rebase onto #{base} pending: #{reason}"
+          else "worktree: not refreshed: #{reason}"
+          end
+        end
+      end
+
+      class << self
+        # The default branch, as `origin/HEAD` names it.
+        #
+        # @param path [String] any checkout of the repository
+        # @return [String] e.g. "main"
+        def default_branch(path)
+          out, status = Open3.capture2("git",
+            "-C",
+            path,
+            "symbolic-ref",
+            "--quiet",
+            "refs/remotes/#{REMOTE}/HEAD",
+            err: File::NULL)
+          name = out.strip.delete_prefix("refs/remotes/#{REMOTE}/")
+          status.success? && !name.empty? ? name : FALLBACK
+        end
+
+        # Fetch the default branch, and say where a new branch should start.
+        #
+        # A fetch only moves `refs/remotes`, logged as a fetch rather than a
+        # push, so {Execution::Boundary} does not blame an agent running in
+        # another worktree for it.
+        #
+        # @param path [String]
+        # @return [String, nil] "origin/<default>" once it exists, nil when
+        #   the repository has no such remote branch
+        def fetch(path)
+          return nil unless system("git", "-C", path, "remote", "get-url", REMOTE, out: File::NULL, err: File::NULL)
+
+          base = default_branch(path)
+          fetched = fetch_within("git", "-C", path, "fetch", "--quiet", REMOTE, base)
+          UI.log("worktree: could not fetch #{REMOTE} #{base}; working from the last fetch") unless fetched
+          ref = "#{REMOTE}/#{base}"
+          if system("git",
+            "-C",
+            path,
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            "refs/remotes/#{ref}",
+            out: File::NULL,
+            err: File::NULL)
+            ref
+          end
+        end
+
+        private
+
+        # Run a fetch, killing its whole process group (git, and the ssh or
+        # credential helper it started) once it has run past {FETCH_TIMEOUT}.
+        #
+        # @return [Boolean] whether it finished, and succeeded, in time
+        def fetch_within(*argv, timeout: FETCH_TIMEOUT, spawner: Spawner::System)
+          pid = spawner.spawn(fetch_env, *argv, pgroup: true, in: File::NULL, out: File::NULL, err: File::NULL)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          loop do
+            _, status = Process.wait2(pid, Process::WNOHANG)
+            return status.success? if status
+            break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+            sleep 0.05
+          end
+          UI.log("worktree: git fetch timed out after #{timeout}s")
+          begin
+            Process.kill("KILL", -pid)
+          rescue Errno::ESRCH, Errno::EPERM
+            # Already gone, or not ours to end.
+          end
+          Process.wait(pid)
+          false
+        end
+      end
+
+      # @param path [String] the plan's worktree
+      def initialize(path:) = @path = path
+
+      # @return [String]
+      attr_reader :path
+
+      # Fetch, then fast-forward or rebase onto the default branch.
+      #
+      # @param hold [String, nil] a default-branch commit the rebase has
+      #   already failed on as often as it may: while `origin/<default>` still
+      #   names it, a branch that would need a rebase is left where it is
+      # @return [OpenLanes::Vcs::Refresh::Outcome]
+      def call(hold: nil)
+        return resume if rebasing?
+
+        base = self.class.fetch(path) or return Outcome.new(kind: :skipped, reason: "no #{REMOTE} default branch")
+        target = rev(base)
+        behind = count("HEAD..#{base}")
+        return Outcome.new(kind: :current, base:, target:) if behind.zero?
+        return fast_forward(base, target, behind) if count("#{base}..HEAD").zero?
+
+        outcome = Outcome.new(kind: :skipped, base:, target:, commits: behind)
+        return outcome.with(reason: "uncommitted changes in the worktree") if dirty?
+        return outcome.with(kind: :pending, reason: "retries exhausted until #{base} moves") if hold == target
+
+        rebase(base, target, behind)
+      end
+
+      # Carry a stopped rebase on, once an agent has resolved and staged.
+      #
+      # Refused while any path is unmerged or a staged file still holds a
+      # marker: continuing then would commit the marker into the branch.
+      #
+      # @return [OpenLanes::Vcs::Refresh::Outcome] :rebased, or :conflicted
+      #   on the files that still need a resolution (the same commit's, or
+      #   the next one's)
+      def continue
+        base = onto
+        left = unresolved
+        return Outcome.new(kind: :conflicted, base:, target: rev(base), files: left) unless left.empty?
+
+        # A resolution identical to what is already on HEAD leaves the commit
+        # empty. Newer git drops it on continue, older git refuses and is
+        # skipped past. Either way it drops nothing the branch still needs
+        # (the index is HEAD), but the commit is gone, so it is named.
+        empty = git({}, "diff", "--cached", "--quiet")
+        stopped_at = capture("log", "-1", "--format=%h %s", "REBASE_HEAD") if empty
+        ok = git({ "GIT_EDITOR" => "true" }, "rebase", "--continue")
+        ok ||= empty && rebasing? && unmerged.empty? && git({}, "rebase", "--skip")
+        dropped(stopped_at, base)
+        stopped = rebasing? ? unmerged : []
+        return Outcome.new(kind: :conflicted, base:, target: rev(base), files: stopped) unless stopped.empty?
+        return Outcome.new(kind: :rebased, base:, target: rev(base)) if ok && !rebasing?
+
+        # Stopped with nothing to resolve (a hook refused, say): no agent can
+        # help, so the caller aborts.
+        Outcome.new(kind: :skipped, base:, reason: "git rebase --continue failed with nothing unmerged")
+      end
+
+      # Abandon a stopped rebase. git puts the branch back exactly where it
+      # was before the rebase began.
+      #
+      # @param why [String]
+      # @return [OpenLanes::Vcs::Refresh::Outcome]
+      def abort!(why)
+        base = onto
+        git({}, "rebase", "--abort") if rebasing?
+        Outcome.new(kind: :aborted, base:, target: rev(base), reason: why)
+      end
+
+      # @return [Boolean] whether a rebase is stopped in this worktree
+      def rebasing? = %w[rebase-merge rebase-apply].any? { File.directory?(git_path(it)) }
+
+      # @return [Array<String>] paths git still lists as unmerged
+      def unmerged = lines("diff", "--name-only", "--diff-filter=U")
+
+      # Unmerged paths, and staged files that still hold a conflict marker.
+      #
+      # @return [Array<String>]
+      def unresolved
+        marked = lines("diff", "--cached", "--check").filter_map { |line| line.split(":", 2).first if line.include?(MARKER) }
+        (unmerged + marked).uniq
+      end
+
+      private
+
+      # A rebase found stopped before anyone asked: a harness that died
+      # mid-resolution, or a round that ended before it continued. It is
+      # picked up where it stood rather than started again.
+      #
+      # @return [OpenLanes::Vcs::Refresh::Outcome]
+      def resume
+        left = unresolved
+        return Outcome.new(kind: :conflicted, base: onto, target: rev(onto), files: left) unless left.empty?
+
+        continue
+      end
+
+      # @return [OpenLanes::Vcs::Refresh::Outcome]
+      def fast_forward(base, target, behind)
+        # Safe with uncommitted changes: git refuses, touching nothing, when
+        # one of them is in a file the merge would change.
+        return Outcome.new(kind: :fast_forwarded, base:, target:, commits: behind) if git({}, "merge", "--ff-only", "--quiet", base)
+
+        Outcome.new(kind: :skipped,
+          base:,
+          target:,
+          commits: behind,
+          reason: "fast-forward refused; uncommitted changes touch files #{base} changed")
+      end
+
+      # @return [OpenLanes::Vcs::Refresh::Outcome]
+      def rebase(base, target, behind)
+        return Outcome.new(kind: :rebased, base:, target:, commits: behind) if git({ "GIT_EDITOR" => "true" }, "rebase", "--quiet", base)
+        return Outcome.new(kind: :conflicted, base:, target:, commits: behind, files: unresolved) if rebasing?
+
+        Outcome.new(kind: :skipped, base:, target:, commits: behind, reason: "git rebase refused to start")
+      end
+
+      # The branch the stopped rebase is replaying onto, as a name.
+      #
+      # @return [String]
+      def onto
+        sha = File.read(git_path("rebase-merge/onto")).strip if File.file?(git_path("rebase-merge/onto"))
+        base = "#{REMOTE}/#{self.class.default_branch(path)}"
+        sha.nil? || rev(base) == sha ? base : sha[0, 7]
+      end
+
+      # Log a commit the rebase replayed as empty, once it is past it.
+      #
+      # @param stopped_at [String, nil] "<sha> <subject>" of the commit
+      # @param base [String]
+      # @return [void]
+      def dropped(stopped_at, base)
+        return if stopped_at.nil?
+        return if rebasing? && capture("log", "-1", "--format=%h %s", "REBASE_HEAD") == stopped_at
+
+        UI.log("worktree: rebase dropped #{stopped_at}: its changes are already on #{base}")
+      end
+
+      # @return [Boolean]
+      def dirty? = !lines("status", "--porcelain").empty?
+
+      # @return [Integer]
+      def count(range) = capture("rev-list", "--count", range).to_i
+
+      # @return [String, nil]
+      def rev(ref) = capture("rev-parse", "--verify", "--quiet", ref).then { it.empty? ? nil : it }
+
+      # @return [String] a path inside this worktree's own git directory
+      def git_path(name) = File.expand_path(capture("rev-parse", "--git-path", name), path)
+
+      # @return [Array<String>]
+      def lines(*) = capture(*).lines(chomp: true).reject(&:empty?)
+
+      # @return [String]
+      def capture(*)
+        out, = Open3.capture2("git", "-C", path, *, err: File::NULL)
+        out.strip
+      end
+
+      # @return [Boolean]
+      def git(env, *) = system(env, "git", "-C", path, *, out: File::NULL, err: File::NULL)
+    end
+  end
+end