openlanes 3.0.0 → 3.1.0

data/lib/openlanes/engine/merging.rb

@@ -0,0 +1,459 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Engine
+    # What the engine does with a 🏁 Completed plan once palpatine has ruled
+    # (decisions P1 to P5).
+    #
+    # palpatine only writes `plan.md` and signs. Everything that leaves the
+    # machine happens here: labelling each `ready-to-merge` pull request
+    # `auto-merged` or `merge-manually`, merging the `auto` ones one at a
+    # time under `merge.by: auto`, and rebasing the siblings left open onto
+    # `main` after each merge. A rebase that raises leaves that sibling for a
+    # person, and every other open sibling is still rebased or left in the
+    # same pass, rather than retrying the merge on old green CI. A branch
+    # GitHub still reports as `BEHIND` is never merged. Every step is asked of
+    # GitHub as it stands, so {#advance} may be called on every poll and does
+    # nothing twice. That is also how a sibling waits for CI on its rebased
+    # head, and how a person's merge of a `merge-manually` pull request is
+    # noticed in either mode.
+    #
+    # The plan reaches ✅ through {PrOutcomes}, once nothing is left open,
+    # exactly as when a person merges the last pull request by hand.
+    class Merging
+      # The phase an agent definition declares to be the risk assessor. Its
+      # Completed note carries the verdicts.
+      PHASE = "completion"
+
+      # The two verdicts palpatine may give.
+      VERDICTS = %w[auto manual].freeze
+
+      # One verdict, with or without the pull request it is for.
+      VERDICT = /(auto|manual)(?:\s+#?(\d+))?/i
+
+      # The only notes read at all: `auto`, `manual #13`, `auto #12, manual #13`,
+      # with at most one bare verdict, first. Matched against the whole note,
+      # because a scan found the `auto` in "do not auto-merge" and would have
+      # merged the plan.
+      NOTE = /\A\s*#{VERDICT}(?:\s*,\s*(?:auto|manual)\s+#?\d+)*\s*\z/i
+
+      # How long a rebased sibling's zero checks still mean "CI has not
+      # registered on the new head yet", as {Verification::Outcome::NO_CHECKS_GRACE}
+      # does for the verification commit.
+      NO_CHECKS_GRACE = Verification::Outcome::NO_CHECKS_GRACE
+
+      # Who signs the comment carrying a rebase conflict.
+      SENDER = "openlanes"
+
+      # What one call did, for the log.
+      #
+      # @!attribute [r] note
+      #   @return [String]
+      # @!attribute [r] to
+      #   @return [Symbol, nil] the state the folder moved to, nil when it stayed
+      # @!attribute [r] merged
+      #   @return [Boolean] whether the engine merged a pull request in this pass
+      Result = Data.define(:note, :to, :merged) do
+        def initialize(to: nil, merged: false, **rest) = super
+      end
+
+      class << self
+        # The verdict for each pull request, read off palpatine's note. A
+        # bare verdict covers every pull request it does not name; a pull
+        # request the note says nothing about, or a note that is missing or
+        # not in the {NOTE} shape, is `manual` (P4): a wrong `manual` costs a
+        # person ten minutes, a wrong `auto` can ship an outage.
+        #
+        # @param note [String, nil]
+        # @param numbers [Array<Integer>] the `ready-to-merge` pull requests
+        # @return [Hash{Integer => String}]
+        def verdicts(note, numbers)
+          return numbers.to_h { [it, "manual"] } unless readable?(note)
+
+          found = note.to_s.scan(VERDICT).map { |word, number| [word.downcase, number&.to_i] }
+          named = found.select(&:last).to_h { |word, number| [number, word] }
+          bare = found.find { |_, number| number.nil? }&.first || "manual"
+          numbers.to_h { |n| [n, named.fetch(n, bare)] }
+        end
+
+        # @param note [String, nil]
+        # @return [Boolean] whether the note is in the {NOTE} shape
+        def readable?(note) = note.to_s.match?(NOTE)
+      end
+
+      # @param github [Vcs::GitHub]
+      # @param outcomes [PrOutcomes] records merges and rejections, and moves the folder
+      # @param merge_by [#call, Symbol] {Config#merger}, read live
+      # @param worktree [Vcs::Worktree, nil] where a plan's own branch is checked out
+      # @param publisher [Vcs::Publisher, nil] pushes a rebased branch, with the lease
+      # @param clock [#call]
+      # @param held [#call, nil] path -> who holds an alock lock in it, or nil;
+      #   a merged plan's checkout somebody holds is not retired
+      def initialize(github:, outcomes:, merge_by:, worktree: nil, publisher: nil, clock: -> { Clock::System.now }, held: nil)
+        @github = github
+        @outcomes = outcomes
+        @merge_by = merge_by
+        @worktree = worktree
+        @publisher = publisher
+        @clock = clock
+        @held = held
+      end
+
+      # palpatine signed, or its run ended without a signature: keep the
+      # verdicts for this visit to 🏁, then act on them.
+      #
+      # @param subject [Plans::Subject] at 🏁
+      # @param note [String, nil] palpatine's Completed note; nil reads as `manual` throughout
+      # @return [Result]
+      def assess(subject, note)
+        numbers = subject.pull_requests.select(&:open?).map { number_of(it) }
+        unless note.nil? || self.class.readable?(note)
+          UI.log("palpatine's note is not a verdict list, so every pull request is manual: #{note.inspect}",
+            level: :warn,
+            plan:  subject.feature.ordinal.to_s)
+        end
+        Plans::PlanState.for(subject.feature.path).assess!(self.class.verdicts(note, numbers), at: @clock.call)
+        advance(subject)
+      end
+
+      # @param subject [Plans::Subject]
+      # @return [Boolean] whether palpatine has ruled on this visit to 🏁, so
+      #   nobody is to start it again
+      def assessed?(subject) = subject.status.key == :completed && !record(subject).nil?
+
+      # One pass over a 🏁 plan's pull requests. At most one merge per pass:
+      # the siblings are rebased after it, and each must show green CI on
+      # its new head before it merges in turn.
+      #
+      # @param subject [Plans::Subject] at 🏁, assessed
+      # @return [Result]
+      def advance(subject)
+        record = record(subject) or return Result.new(note: "palpatine has not ruled yet")
+
+        notes = []
+        subject.pull_requests.select(&:open?).each do |pull|
+          step = step(subject, pull, record)
+          next unless step
+
+          notes << step.note
+          return Result.new(note: notes.join("; "), to: step.to, merged: step.merged) if step.to || step.merged
+        end
+        Result.new(note: notes.empty? ? "waiting on every pull request" : notes.join("; "))
+      end
+
+      # The plans whose checkouts wait on a rebase after a merge.
+      #
+      # @return [Array<String>] ordinals
+      def pending_rebases = queued.keys
+
+      # Rebase every queued checkout no agent is running in onto `main`, and
+      # push the ones that moved. A busy checkout stays queued, so its
+      # `HEAD` moves only between runs, before its next boundary snapshot.
+      # A conflict is aborted and left for that plan's next round, whose own
+      # pre-run rebase hands it to bb8; uncommitted work is refused by
+      # {Vcs::Refresh} and never touched.
+      #
+      # @param busy [Array<String>] ordinals with an agent running
+      # @return [Array<String>] one line per checkout handled, for the log
+      def rebase_queued(busy:)
+        (queued.keys - busy).map do |ordinal|
+          other = queued.delete(ordinal)
+          rebase_checkout(other)
+        rescue OpenLanes::Error => e
+          "#{ordinal} not rebased onto main: #{e.message.lines.first.to_s.strip}"
+        end
+      end
+
+      private
+
+      # @param other [Plans::Subject]
+      # @return [String]
+      def rebase_checkout(other)
+        feature = other.feature
+        checkout = @worktree.checkout_for(feature)
+        refresh = Vcs::Refresh.new(path: checkout.path)
+        outcome = refresh.call
+        ordinal = feature.ordinal.to_s
+        if outcome.conflicted?
+          refresh.abort!("conflicts after a merge to main")
+          return "#{ordinal} conflicts with main in #{outcome.files.join(", ")}; its next round resolves it"
+        end
+        return "#{ordinal} not rebased: #{outcome.reason}" unless outcome.done?
+        return "#{ordinal} already on main" if outcome.kind == :current
+        # A branch with no pull request was never published, and a rebase
+        # is no reason to publish it.
+        return "#{ordinal} rebased onto main" unless other.pull_requests.any?(&:open?)
+
+        @publisher.pushed!(checkout, "HEAD")
+        "#{ordinal} rebased onto main"
+      end
+
+      # One pull request, one step along its machine.
+      #
+      # @return [Result, nil] nil when there is nothing to do for it now
+      def step(subject, pull, record)
+        number = number_of(pull)
+        repo = Vcs::GitHub.repo_of(pull.url)
+        live = @github.pull_request(pull.url || number.to_s)
+        return settled_by_someone(subject, number, live[:state], live:) unless live[:open]
+
+        machine = Plans::PullRequestMachine.new(pull, live[:labels])
+        return nil unless machine.key == :ready_to_merge
+
+        verdict = record.dig("verdicts", number.to_s) || "manual"
+        return leave(machine, number, repo, "palpatine said manual") if verdict == "manual"
+        return leave(machine, number, repo, "merge.by is #{merge_by}") unless merge_by == :auto
+
+        merge(subject, machine, number, repo, record, live[:head], merge_state: live[:merge_state])
+      end
+
+      # Merged or closed on GitHub, by the engine a moment ago or by a person
+      # at any time, in either mode.
+      #
+      # @param state [String] as {Vcs::GitHub.state_label} words it
+      # @param live [Hash, nil] the pull request as {Vcs::GitHub#pull_request} read it
+      # @param ref [String, nil] how to read it when +live+ is nil
+      # @return [Result]
+      def settled_by_someone(subject, number, state, live: nil, ref: nil)
+        kind = state.to_s.match?(/merged/i) ? :merged : :closed
+        applied = @outcomes.apply(PrWatch::Outcome.new(plan: subject.feature.ordinal.to_s, pr: number, kind:))
+        retire(subject, number, live || ref) if kind == :merged
+        Result.new(note: "PR ##{number} #{kind}", to: applied&.to)
+      end
+
+      # A merged pull request ends its plan's worktree, once it is the
+      # plan's last open one: a sibling still open is rebased in that
+      # checkout after this merge. {Vcs::Worktree#retire} decides whether
+      # each checkout's work really landed; this only says when to ask.
+      # Never fatal: a checkout left behind costs disk, and a merge that
+      # failed over one would cost the plan.
+      #
+      # @param pull [Hash, String, nil] the merged pull request as read, or a ref to read it by
+      # @return [void]
+      def retire(subject, number, pull)
+        return if @worktree.nil? || pull.nil?
+        return if fresh(subject).pull_requests.any? { it.open? && number_of(it) != number }
+
+        ordinal = subject.feature.ordinal.to_s
+        live = pull.is_a?(Hash) ? pull : @github.pull_request(pull)
+        return if live[:merge_commit].to_s.empty?
+
+        @worktree.checkouts_of(subject.feature).each do |path|
+          UI.log(@worktree.retire(path, merge_commit: live[:merge_commit], base: live[:base], held: @held).to_s, plan: ordinal)
+        end
+      rescue OpenLanes::Error => e
+        UI.log("worktree not retired: #{e.message.lines.first.to_s.strip}", level: :warn, plan: ordinal)
+      end
+
+      # @param comment [Boolean] post +why+ on the pull request, so a person
+      #   looking at it sees why the engine stepped away
+      # @return [Result]
+      def leave(machine, number, repo, why, comment: false)
+        machine.fire!(:leave_for_a_person)
+        @github.swap_label(number:,
+          repo:,
+          add: Plans::ReviewLabel::MERGE_MANUALLY,
+          remove: Plans::ReviewLabel.displaced_by(Plans::ReviewLabel::MERGE_MANUALLY))
+        @github.comment(number:, repo:, body: why) if comment
+        Result.new(note: "PR ##{number} #{Plans::ReviewLabel::MERGE_MANUALLY}: #{why}")
+      end
+
+      # Merge once CI is green on the head as it stands, then rebase the
+      # siblings. A merge GitHub refuses, a conflict among the reasons, is
+      # left for a person rather than retried every poll. So is one with no
+      # CI at all: nobody watches this merge, and no checks is no evidence.
+      # The merge names the head read before the checks, so a push in
+      # between makes GitHub refuse it rather than merge a head CI never saw.
+      # A branch still behind `main` is the same: CI on that head never saw
+      # the commit just merged, so a person rebases it.
+      #
+      # @param head [String, nil] the head commit, as read before the checks
+      # @param merge_state [String, nil] GitHub's `mergeStateStatus`
+      # @return [Result, nil]
+      def merge(subject, machine, number, repo, record, head, merge_state: nil)
+        ci = Vcs::CiGate.verdict(@github.checks(number:, repo:))
+        ci = :registering if ci == :none && registering?(record, number)
+        return Result.new(note: "PR ##{number} waits on CI before it merges") if %i[pending registering].include?(ci)
+        return reject(subject, number, repo, "CI is red on PR ##{number} after its rebase onto main.") if ci == :red
+        return leave(machine, number, repo, "no CI checks ran") if ci == :none
+        return leave(machine, number, repo, "its head commit could not be read") if head.to_s.empty?
+        return leave(machine, number, repo, "its branch is behind main", comment: true) if behind?(merge_state)
+        return leave(machine, number, repo, "it does not merge clean onto main", comment: true) if dirty?(merge_state)
+        return Result.new(note: "PR ##{number} waits on GitHub to work out whether it merges clean") if unknown?(merge_state)
+
+        main = main_ci(repo)
+        return Result.new(note: "PR ##{number} waits on CI on main, which is #{main}") unless main == :green
+
+        begin
+          @github.merge(number:, repo:, head:)
+        rescue OpenLanes::Error => e
+          return leave(machine, number, repo, e.message)
+        end
+        queue_other_plans(subject)
+        machine.fire!(:merge_automatically)
+        @github.swap_label(number:,
+          repo:,
+          add: Plans::ReviewLabel::AUTO_MERGED,
+          remove: Plans::ReviewLabel.displaced_by(Plans::ReviewLabel::AUTO_MERGED))
+        merged = settled_by_someone(subject, number, "Merged", ref: repo ? "https://github.com/#{repo}/pull/#{number}" : number.to_s)
+        done = Result.new(note: "PR ##{number} #{Plans::ReviewLabel::AUTO_MERGED}", to: merged.to, merged: true)
+        return done if merged.to
+
+        rebased = rebase_siblings(fresh(subject), number)
+        rebased ? rebased.with(note: "#{done.note}; #{rebased.note}", merged: true) : done
+      end
+
+      # Every pull request of the plan still open, onto `main` (P5). The
+      # plan's own branch is rebased in its worktree and pushed with the
+      # lease; a sibling from any other branch is rebased on GitHub's side.
+      # A conflict still sends the plan to 🔴. Anything else that raises
+      # (a refused push, a GitHub update that did not finish) leaves that
+      # sibling for a person, and the walk continues: returning from the
+      # first raise used to skip later siblings, which kept `ready-to-merge`
+      # and the old green CI. GitHub's `BEHIND` is silent unless the base
+      # requires branches to be up to date, so each sibling must be rebased
+      # or left in this pass.
+      #
+      # @return [Result, nil] the rejection a conflict caused, or the leaves a
+      #   rebase that raised caused; nil when every sibling rebased
+      def rebase_siblings(subject, merged)
+        notes = []
+        subject.pull_requests.select(&:open?).each do |pull|
+          number = number_of(pull)
+          repo = Vcs::GitHub.repo_of(pull.url)
+          why = rebase(subject, pull, number, repo)
+          return reject(subject, number, repo, why) if why
+
+          Plans::PlanState.for(subject.feature.path).rebased!(number, at: @clock.call)
+        rescue OpenLanes::Error => e
+          UI.log("rebase after merging ##{merged} not finished: #{e.message}",
+            level: :warn,
+            plan:  subject.feature.ordinal.to_s)
+          notes << leave_unrebased(pull, number, repo, e.message).note
+        end
+        notes.empty? ? nil : Result.new(note: notes.join("; "))
+      end
+
+      # @return [Result]
+      def leave_unrebased(pull, number, repo, error)
+        live = @github.pull_request(pull.url || number.to_s)
+        machine = Plans::PullRequestMachine.new(pull, live[:labels])
+        leave(machine, number, repo, "rebase onto main failed: #{error}", comment: true)
+      end
+
+      # @param status [String, nil] GitHub's `mergeStateStatus`
+      # @return [Boolean]
+      def behind?(status) = status.to_s.upcase == "BEHIND"
+
+      # @param status [String, nil] GitHub's `mergeStateStatus`
+      # @return [Boolean] whether the merge would conflict
+      def dirty?(status) = status.to_s.upcase == "DIRTY"
+
+      # @param status [String, nil] GitHub's `mergeStateStatus`
+      # @return [Boolean] whether GitHub is still computing it
+      def unknown?(status) = status.to_s.upcase == "UNKNOWN"
+
+      # CI on `main` (R5). No checks at all reads as `:none`, which holds
+      # the merge like red does: nobody watches it, and no checks is no
+      # evidence `main` builds.
+      #
+      # @return [Symbol] as {Vcs::CiGate.verdict}
+      def main_ci(repo) = Vcs::CiGate.verdict(@github.branch_checks(branch: "main", repo:))
+
+      # Every other plan whose checkout exists, to be rebased onto `main`
+      # once no agent is running in it (R5). Never done here: a rebase moves
+      # `HEAD`, and an agent's after-check would blame the agent for it.
+      #
+      # @return [void]
+      def queue_other_plans(subject)
+        return if @worktree.nil? || @publisher.nil?
+
+        Plans::Tree.new(dir: File.dirname(subject.feature.path)).subjects.each do |other|
+          next if other.feature.ordinal == subject.feature.ordinal || other.status.terminal?
+          next unless File.directory?(@worktree.path_for(other.feature))
+
+          queued[other.feature.ordinal.to_s] = other
+        end
+      end
+
+      # @return [Hash{String => Plans::Subject}] checkouts waiting on a rebase, by plan
+      def queued = @queued ||= {}
+
+      # @return [String, nil] why the rebase failed, nil when it went through
+      def rebase(subject, pull, number, repo)
+        checkout = own_checkout(subject, pull) or return github_rebase(number, repo)
+
+        refresh = Vcs::Refresh.new(path: checkout.path)
+        outcome = refresh.call
+        if outcome.conflicted?
+          refresh.abort!("conflicts after a sibling merged")
+          return "PR ##{number} no longer rebases onto #{outcome.base}: conflicts in #{outcome.files.join(", ")}."
+        end
+        # Skipped or refused locally (a dirty tree, no remote): GitHub can
+        # still rebase the branch it holds, and says so if it conflicts.
+        return github_rebase(number, repo) unless outcome.done?
+
+        @publisher.pushed!(checkout, "HEAD") unless outcome.kind == :current
+        nil
+      end
+
+      # The plan's own checkout, when it already exists and builds this
+      # pull request. Never made here: a poll that minted a worktree per
+      # 🏁 plan would leave one behind for every plan a person merges.
+      #
+      # @return [Vcs::Worktree::Checkout, nil]
+      def own_checkout(subject, pull)
+        return nil if @worktree.nil? || @publisher.nil? || !File.directory?(@worktree.path_for(subject.feature))
+
+        checkout = @worktree.checkout_for(subject.feature)
+        @publisher.branch_mismatch(pull, checkout) ? nil : checkout
+      end
+
+      # @return [String, nil]
+      def github_rebase(number, repo)
+        @github.update_branch(number:, repo:)
+        nil
+      rescue OpenLanes::Error => e
+        "PR ##{number} no longer rebases onto main: #{e.message}"
+      end
+
+      # A conflict or red CI after a rebase: `review-rejected` on the pull
+      # request, and the plan to 🔴 with the reason mailed to luke and rey,
+      # through {PrOutcomes} exactly as a person's rejection is.
+      #
+      # @return [Result]
+      def reject(subject, number, repo, why)
+        @github.swap_label(number:,
+          repo:,
+          add: Plans::ReviewLabel::REJECTED,
+          remove: Plans::ReviewLabel.displaced_by(Plans::ReviewLabel::REJECTED))
+        @github.comment(number:, repo:, body: why)
+        comments = [{ author: SENDER, url: "", body: why }]
+        applied = @outcomes.apply(PrWatch::Outcome.new(plan: subject.feature.ordinal.to_s, pr: number, kind: :rejected, comments:))
+        Result.new(note: "PR ##{number} back to the builders: #{why}", to: applied&.to)
+      end
+
+      # Whether a rebased sibling's push is recent enough that CI may not
+      # have registered on its new head yet.
+      #
+      # @return [Boolean]
+      def registering?(record, number)
+        at = record.dig("rebased", number.to_s) or return false
+
+        @clock.call - Time.iso8601(at) < NO_CHECKS_GRACE
+      end
+
+      # @return [Hash, nil]
+      def record(subject) = Plans::PlanState.for(subject.feature.path).merge_risk
+
+      # @return [Symbol]
+      def merge_by = @merge_by.respond_to?(:call) ? @merge_by.call : @merge_by
+
+      # @return [Integer]
+      def number_of(pull) = Vcs::GitHub.number_of(pull.url || pull.number.to_s)
+
+      # @return [Plans::Subject]
+      def fresh(subject) = Plans::Tree.new(dir: File.dirname(subject.feature.path)).find(subject.feature.ordinal.to_s) || subject
+    end
+  end
+end

data/lib/openlanes/engine/narrator.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Engine
+    # What a run says on the terminal while it works: one plain line per
+    # event, appended, never redrawn.
+    #
+    # It is a {UI.tap_log} tap, so it hears exactly what the progress log
+    # file hears (an agent started or finished, a plan changed state, a
+    # command came from the page, the reason the engine idles) and nothing
+    # else. The file keeps its fixed columns for `awk`; the terminal gets
+    # only the fields a line actually has. Echoing the file's format there
+    # is what drew an idle line as a row of empty columns,
+    # `[13:39:10 |        |  …  |   83054 |       ] idle: …`.
+    #
+    # Nothing here moves the cursor or colours anything. A line is written
+    # whole, under a lock, with any carriage return or escape sequence in any
+    # field (an agent's note is free text, a page command's plan is unchecked)
+    # taken out first, so two threads logging at once
+    # cannot splice their lines, and no message can rewrite the one above.
+    # The same lines serve a terminal, a pipe and a CI log alike.
+    #
+    # @example
+    #   narrator = Narrator.new
+    #   UI.tap_log(narrator)
+    #   UI.log("started", plan: "003.00", status: "⭐ Planned", agent: "yoda-writer", round: "01")
+    #   # 13:39:10  003.00 ⭐  Planned  yoda-writer r01  started
+    class Narrator
+      # Between the parts of a line. Two spaces read as columns without
+      # holding open the ones a line does not have.
+      GAP = "  "
+
+      # A carriage return, an escape sequence, or any other control
+      # character but a tab: what would let one message overwrite another.
+      CONTROL = %r{\e\[[0-9;?]*[ -/]*[@-~]|[\x00-\x08\x0a-\x1f\x7f]}
+
+      # @param stream [#puts, nil] where the lines go; nil means whatever
+      #   `$stderr` is when a line is written, so a spec swapping it is heard
+      # @param clock [Proc] wall time, injectable for a fixed timestamp
+      def initialize(stream: nil, clock: -> { Clock::System.now })
+        @stream = stream
+        @clock = clock
+        @lock = Mutex.new
+        @last = nil
+      end
+
+      # The tap itself. A line identical to the previous one is dropped, so
+      # whatever repeats itself tick after tick (an idle reason, a store
+      # that keeps refusing) is said once per change rather than once a
+      # second.
+      #
+      # @param message [String]
+      # @param fields [Hash] the log line's fields: plan, status, agent, round,
+      #   and `to:` when the event moved the plan
+      # @return [void]
+      def call(message, fields = {})
+        text = render(message, **fields)
+        @lock.synchronize do
+          next if text == @last
+
+          @last = text
+          # Unpainted, so a terminal gets the same bytes as a pipe or a CI log.
+          (@stream || $stderr).puts("#{@clock.call.strftime(ProgressLog::TIME_FORMAT)}#{GAP}#{text}")
+        end
+      rescue StandardError
+        # A tap runs on the logging thread and must never take it down;
+        # a terminal that went away is no reason to stop the agents.
+        nil
+      end
+
+      # @return [Proc] for {UI.tap_log}
+      def to_proc = method(:call).to_proc
+
+      # One event, without its timestamp.
+      #
+      # @param message [String]
+      # @param plan [String, nil]
+      # @param status [String, nil] emoji and label
+      # @param agent [String, nil]
+      # @param round [String, nil] e.g. "01"
+      # @param to [String, nil] the state the plan moved to, emoji and label
+      # @return [String] e.g. `003.00 ⭐  Planned  yoda-writer r01  finished → 🟡  Building`
+      def render(message, plan: nil, status: nil, agent: nil, round: nil, to: nil, **)
+        # Every field, not just the message: a page command's plan and agent
+        # are logged before anything checks that they name real ones.
+        plan, status, agent, round = [plan, status, agent, round].map { clean(it) if it }
+        said = clean(message)
+        said = "#{said} → #{self.class.status_cell(clean(to))}" if to
+        [[plan, (self.class.status_cell(status) if status)].compact.join(" "), [agent, ("r#{round}" if round)].compact.join(" "), said]
+          .reject(&:empty?).join(GAP)
+      end
+
+      # The emoji fitted to two cells and followed by two spaces, then the
+      # label, exactly as the progress log draws it.
+      #
+      # @param status [String] emoji and label, e.g. "⭐ Planned"
+      # @return [String] e.g. "⭐  Planned"
+      def self.status_cell(status) = ProgressLog.status_cell(status).to_s
+
+      private
+
+      # @param text [Object]
+      # @return [String] on one line, with nothing that moves the cursor
+      def clean(text) = text.to_s.gsub(CONTROL, " ").squeeze(" ").strip
+    end
+  end
+end

data/lib/openlanes/engine/plan_locks.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Engine
+    # The dispatcher's `locked-by.pid` files, counted per plan. Both halves of
+    # a pair work in one folder and so share one lock file; removing it when
+    # the first of them finished left the partner running in an unlocked
+    # folder, which a separate `resync dirs` was then free to rename. The
+    # file goes when the last job holding the plan does.
+    #
+    # The plan's alock (W31) follows the same count. It is taken first, by
+    # {#reserve}, on the folder as it is named before the job starts: the
+    # start may rename the folder, and a refusal found after the rename would
+    # leave a folder renamed under somebody else's work. {#hold} moves it to
+    # the new name.
+    class PlanLocks
+      # Raised when an agent outside openlanes holds the plan.
+      class Refused < Error; end
+
+      # @param agent_locks [AgentLocks, nil] nil leaves alock out
+      def initialize(agent_locks: nil)
+        @agent_locks = agent_locks
+        @mutex = Mutex.new
+        @held = {}
+        @reserved = {}
+      end
+
+      # Take the plan's alock before its first job starts. A partner joining
+      # a running plan already has it.
+      #
+      # @param ordinal [String]
+      # @param dir [String] the plan folder, before any rename
+      # @param intent [String] said to whoever reads the lock
+      # @return [void]
+      # @raise [Refused] when somebody else holds the folder
+      def reserve(ordinal, dir, intent)
+        @mutex.synchronize do
+          next if @held.key?(ordinal) || @reserved.key?(ordinal) || @agent_locks.nil?
+          raise Refused, "#{File.basename(dir)} is held in alock" unless @agent_locks.acquire(dir, intent)
+
+          @reserved[ordinal] = dir
+        end
+      end
+
+      # @param ordinal [String]
+      # @param dir [String] the plan folder, as the job about to start sees it
+      # @return [void]
+      def hold(ordinal, dir)
+        @mutex.synchronize do
+          path, count = @held.fetch(ordinal) { [@reserved.fetch(ordinal, dir), 0] }
+          # A folder renamed since the first hold carried its lock along;
+          # writing at the new path again costs nothing and is never wrong.
+          begin
+            Plans::Lock.write(dir) if count.zero? || path != dir
+          rescue Plans::Lock::Held
+            drop_reservation(ordinal) if count.zero?
+            raise
+          end
+          move_alock(path, dir) if path != dir
+          @reserved.delete(ordinal)
+          @held[ordinal] = [dir, count + 1]
+        end
+      end
+
+      # Give back a reservation whose job never started.
+      #
+      # @param ordinal [String]
+      # @return [void]
+      def unreserve(ordinal) = @mutex.synchronize { drop_reservation(ordinal) }
+
+      # @param ordinal [String]
+      # @return [void]
+      def release(ordinal)
+        @mutex.synchronize do
+          path, count = @held[ordinal]
+          next unless path
+
+          if count > 1
+            @held[ordinal] = [path, count - 1]
+          else
+            @held.delete(ordinal)
+            Plans::Lock.remove(path)
+            @agent_locks&.release(path)
+          end
+        end
+      end
+
+      # @param ordinal [String]
+      # @return [Integer] how many running jobs hold it
+      def count(ordinal) = @mutex.synchronize { @held.fetch(ordinal, [nil, 0]).last }
+
+      private
+
+      # @return [void]
+      def drop_reservation(ordinal)
+        dir = @reserved.delete(ordinal) or return
+        @agent_locks&.release(dir)
+      end
+
+      # The folder was renamed under its lock. The new name is taken before
+      # the old is given back, so the plan is never left unheld; a refusal
+      # here means somebody claimed a name they could only have guessed, and
+      # is said rather than stopping a job that already started.
+      #
+      # @return [void]
+      def move_alock(from, to)
+        return unless @agent_locks
+
+        UI.log("alock not moved to #{File.basename(to)}: refused", level: :warn) unless @agent_locks.acquire(to, "openlanes")
+        @agent_locks.release(from)
+      end
+    end
+  end
+end