openlanes 3.0.1 → 3.1.0

data/lib/openlanes/cli/create/create.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "fileutils"
-
 module OpenLanes
   module CLI
     # `openlanes create <words…>` — backs /spec-create.
@@ -57,12 +55,12 @@ module OpenLanes
 
       # noinspection RubyMismatchedArgumentType
       example [
-        "tax rule dsl                        # 003.00-⚪️ → tax-rule-dsl, spec.md scaffolded and drafted",
+        "tax rule dsl                        # 003.00━━⚪━━❯tax-rule-dsl, spec.md scaffolded and drafted",
         "tax rule dsl --no-draft --no-open   # scaffold only, nothing shelled out, nothing opened",
-        "--after 002 schedule k1             # 002.01-🕰️-schedule-k1 (documented after the fact)",
+        "--after 002 schedule k1             # 002.01━━⏪━━❯schedule-k1 (documented after the fact)",
         "--after 018 --prs 12,15 verify      # …and write spec.md from what those PRs did",
         "--after 018 --pr https://…/pull/12 verify # verify the pull request by number or URL",
-        "--status ready billing sync         # opens at ⭐️ instead of ⚪️",
+        "--status ready billing sync         # opens at ⭐ instead of ⚪",
         "--from notes/tax-dsl.md             # title and opening prose from the file's frontmatter and body",
         "--lane quick split big migration    # r2d2-mechanic does it and opens the PR; no research, spec or plan"
       ]
@@ -71,222 +69,18 @@ module OpenLanes
       # @param options [Hash]
       # @return [void]
       def call(words:, **options)
-        dir = options.fetch(:dir, OpenLanes::PLANS_DIR)
-        FileUtils.mkdir_p(dir)
-
-        words, seed = resolve_seed(words, options)
-        prs = fetch_prs(options)
-        result =
-          Lifecycle.create(dir:,
-            words:,
-            after:  options[:after],
-            status: options[:status],
-            prs:)
-
-        result.either(
-          ->(path) { created(path, prs, options, seed:) },
-          ->(message) { refuse("Could not create the plan:\n#{message}", 65) }
-        )
+        workflow = Lifecycle.create_plan(dir: options.fetch(:dir, OpenLanes::PLANS_DIR),
+          **options.slice(:root, :after, :status, :prs, :spec, :draft, :lane, :depth),
+          from: typed_path(options[:from]))
+        created = unwrap(workflow.call(words))
+
+        open_spec(created.spec) if created.spec && options.fetch(:open, true)
+        puts created.path
+        success(created.message) unless quiet?(options)
       end
 
       private
 
-      # `--from FILE` trades the words argument for a markdown file: the
-      # frontmatter's `title:` names the folder, and the body travels on to
-      # {Brief} as the author's own opening statement. Words and a file are
-      # two answers to one question — the folder's name — so holding both is
-      # refused rather than silently ranked.
-      #
-      # @param words [Array<String>]
-      # @param options [Hash]
-      # @return [Array(Array<String>, String, nil)] the slug words, and the
-      #   seed body when a file supplied them
-      def resolve_seed(words, options)
-        file = typed_path(options[:from])
-        return words, nil unless file
-
-        unless words.empty?
-          refuse(
-            "--from names the topic by its frontmatter title;\n" \
-            "drop the words, or drop --from",
-            64
-          )
-        end
-        if options[:prs]
-          refuse(
-            "--prs reconstructs spec.md from the pull requests, so a seed file\n" \
-            "would be ignored; use one or the other",
-            64
-          )
-        end
-        unless File.file?(file)
-          refuse("Could not read the seed file:\n#{file} does not exist", 66)
-        end
-
-        title, body = parse_seed(File.read(file, encoding: "UTF-8"))
-        if title.to_s.strip.empty?
-          refuse(
-            "The seed file needs a frontmatter title, e.g.\n" \
-            "---\ntitle: Tax Rule DSL\n---",
-            65
-          )
-        end
-
-        [title.split, body]
-      end
-
-      # Frontmatter that will not parse used to be reported as a missing
-      # title, which sends the author looking for a `title:` line that is
-      # sitting right there. Say which of the two actually went wrong.
-      #
-      # @param content [String]
-      # @return [Array(String, String)] title and body
-      def parse_seed(content)
-        meta, body = Frontmatter.split(content)
-        [meta["title"].to_s, body.strip]
-      rescue Psych::Exception => e
-        refuse(
-          "The seed file's frontmatter is not valid YAML:\n#{e.message}",
-          65
-        )
-      end
-
-      # A retroactive plan documents work that landed *somewhere* in the
-      # sequence, and only its author knows where. Guessing would put the
-      # number — the one thing that never changes — in the wrong place.
-      #
-      # @param options [Hash]
-      # @return [Array<Hash>, nil]
-      def fetch_prs(options)
-        return nil unless options[:prs]
-
-        unless options[:after]
-          refuse(
-            "--prs documents work that already shipped;\n" \
-            "name the plan it landed after with --after, e.g. --after 018",
-            64
-          )
-        end
-
-        Vcs.github.pull_requests(Vcs::GitHub.parse_refs(options[:prs]))
-      rescue OpenLanes::Error => e
-        refuse("Could not read the pull requests:\n#{e.message}", 65)
-      end
-
-      # A plan with recorded pull requests already has its facts — hand it to
-      # the writer that reconstructs a specification from a diff. One without
-      # them does not exist yet, and reconstructing is not the job; {#brief} is.
-      #
-      # @param path [String]
-      # @param prs [Array<Hash>, nil]
-      # @param options [Hash]
-      # @return [void]
-      def created(path, prs, options, seed: nil)
-        from_prs = prs && !prs.empty?
-        path =
-          if from_prs
-            synthesize(path, options) if options.fetch(:spec, true)
-          else
-            brief(path, options, seed:)
-          end || path
-        puts path
-        return if quiet?(options)
-
-        feature = Plans::Feature.parse(path)
-        success(
-          "Created #{File.basename(path)}\n\n" \
-          "#{feature.status.emoji} #{feature.status.label} — #{feature.status.note}\n" \
-          "#{next_step(path, feature, from_prs:)}"
-        )
-      end
-
-      # Hand the folder to the writer that already knows how to write a
-      # retroactive specification, then let `resync dirs` decide what the
-      # folder has become — 🕰️ is only true while there is no `spec.md`.
-      #
-      # @param path [String]
-      # @param options [Hash]
-      # @return [String] the folder's path, which the resync may have renamed
-      def synthesize(path, options)
-        agent = OpenLanes::Agents.registry.find(OpenLanes::RETROACTIVE_WRITER) or
-          return path
-        root = options[:root] || File.dirname(path, 2)
-
-        feature = Plans::Feature.parse(path)
-        ok, note = on_agent_row("Writing spec.md from #{UI.paint(File.basename(path).to_s, :yellow)}",
-          agent: agent.name,
-          plan:  feature.ordinal.to_s) do |line|
-          Execution.executor(root:).call(agent, Plans.subject(feature), &line)
-        end
-        warn_about(note) unless ok
-
-        settle(path)
-      end
-
-      # A folder with no pull requests to reconstruct from is a feature that
-      # does not exist yet. {Brief} writes the four headings a human still has
-      # to answer, makes a best-effort pass at them from what the project
-      # already has on disk, and — unless told not to — opens the result for
-      # a human to finish. The folder's state never moves: ⚪️ New only ever
-      # claimed that a specification exists, not that it is complete.
-      #
-      # @param path [String] the path to the folder
-      # @param seed [String, nil] the seed body from the `--from` file
-      # @param options [Hash] the options hash
-      # @return [String] +path+, unchanged
-      def brief(path, options, seed: nil)
-        feature = Plans::Feature.parse(path)
-        return path if feature.status.key == :retroactive
-
-        root = options[:root] || File.dirname(path, 2)
-        brief = Lifecycle.brief(path:, title: feature.title, root:, seed:)
-        brief.write_scaffold!
-
-        if options.fetch(:draft, true)
-          # Painted the way Runner::Task#label paints a roster agent, so the
-          # half-agent reads as one of them on the terminal.
-          label =
-            "#{UI.paint(Lifecycle::Brief::AGENT_NAME, :yellow, :bold)} drafting spec.md from #{seed}"
-          ok, note = on_agent_row(label, agent: Lifecycle::Brief::AGENT_NAME, plan: feature.ordinal.to_s) { brief.attempt! }
-          warn_about_draft(note) unless ok
-        end
-
-        stamp(brief.spec_path, options)
-        open_spec(brief.spec_path) if options.fetch(:open, true)
-        path
-      end
-
-      # One agent writing spec.md, drawn as a spinner line.
-      #
-      # @param label [String] the spinner line's text
-      # @param agent [String]
-      # @param plan [String]
-      # @yieldparam line [OpenLanes::UI::Line]
-      # @return [Object] the block's value
-      def on_agent_row(label, agent:, plan:, &block)
-        Execution.on_interrupt do
-          UI.concurrently([plan],
-            label,
-            jobs:   1,
-            label:  ->(_) { label },
-            fields: ->(_) { { plan:, agent: } }) { |_, line| block.call(line) }.first
-        end
-      end
-
-      # Writes `--lane` and `--depth` into spec.md's frontmatter, after the
-      # draft, so a drafting agent that rewrites the file cannot drop them.
-      #
-      # @param spec_path [String]
-      # @param options [Hash]
-      # @return [void]
-      def stamp(spec_path, options)
-        settings = { "lane" => options[:lane], "depth" => options[:depth] }.compact
-        return if settings.empty? || !File.file?(spec_path)
-
-        meta, body = Frontmatter.split(File.read(spec_path, encoding: "UTF-8"))
-        File.write(spec_path, "#{YAML.dump(meta.merge(settings))}---\n#{body}")
-      end
-
       # @param spec_path [String]
       # @return [void]
       def open_spec(spec_path)
@@ -301,54 +95,6 @@ module OpenLanes
       #
       # @return [Boolean]
       def macos? = RbConfig::CONFIG["host_os"].to_s.match?(/darwin/)
-
-      # @param path [String]
-      # @return [String] where the folder ended up
-      def settle(path)
-        tree = Plans.tree(File.dirname(path))
-        change =
-          OpenLanes::Lifecycle::Resync::Dirs
-          .new(tree:)
-          .call(commit: true)
-          .find { |c| c.source == path }
-        change ? change.target : path
-      end
-
-      # @param note [String]
-      # @return [void]
-      def warn_about(note)
-        error(
-          "The folder was created, but spec.md was not written:\n#{note}\n\n" \
-          "The pull requests are recorded. Run `openlanes run` to retry."
-        )
-      end
-
-      # @param note [String]
-      # @return [void]
-      def warn_about_draft(note)
-        error(
-          "spec.md was scaffolded, but the drafting attempt did not finish:\n#{note}\n\n" \
-          "The four headings are there, empty. Fill them in by hand, or hand off to leah-researcher."
-        )
-      end
-
-      # @param path [String]
-      # @param feature [OpenLanes::Plans::Feature]
-      # @return [String]
-      def next_step(path, feature, from_prs:)
-        spec = File.join(File.basename(path), "spec.md")
-        unless feature.status.key == :new &&
-               File.file?(File.join(path, "spec.md"))
-          return "Next: write #{spec}"
-        end
-        if from_prs
-          return (
-            "Next: read #{spec} — it was written from the pull requests, so check it against what actually shipped"
-          )
-        end
-
-        "Next: fill in the four headings in #{spec}, then hand off to leah-researcher"
-      end
     end
   end
 end

data/lib/openlanes/cli/eval/eval.rb

@@ -11,6 +11,7 @@ module OpenLanes
       standalone!
       desc "Score agents against evals/cases: recorded folders by default, real runs with --live"
 
+      argument :name, required: false, desc: "Only this agent's cases, as `--agent` says it"
       option :agent, aliases: ["-a"], desc: "Only this agent's cases"
       option :case, aliases: ["-c"], desc: "Only the case with this id"
       option :depth,
@@ -36,9 +37,11 @@ module OpenLanes
         "--live -c research-fast --max-tokens 100000"
       ]
 
+      # @param name [String, nil] the positional spelling of `--agent`
       # @param options [Hash]
       # @return [void]
-      def call(**options)
+      def call(name: nil, **options)
+        options = options.merge(agent: name) if name && options[:agent].nil?
         quiet?(options)
         refuse("--max-tokens only applies to --live runs.", 64) if options[:max_tokens] && !options[:live]
         cases = selected(options)

data/lib/openlanes/cli/init/init.rb

@@ -21,6 +21,9 @@ module OpenLanes
         type: :boolean,
         desc: "Whether plans have a front end; leave it out to let each plan decide"
       option :jobs, aliases: ["-j"], desc: "How many plans `openlanes run` works on at once (default: cores - 2)"
+      option :quality,
+        values: Config::QUALITIES.map(&:to_s),
+        desc:   "desired_codebase_quality: high or mvp (R4); leave it out to be asked on the first ok-not-perfect review"
       option :yes,
         type:    :boolean,
         default: false,
@@ -43,6 +46,7 @@ module OpenLanes
       # @return [void]
       def call(**options)
         quiet?(options)
+        prepare(options)
         root = Project.init_root
         path = File.join(root, Config::FILE)
         plans = File.expand_path(options.fetch(:dir, OpenLanes::PLANS_DIR), root)
@@ -62,7 +66,28 @@ module OpenLanes
 
       private
 
-      # The four values, each from its flag, else asked on a terminal, else
+      # `openlanes setup`, but only when the machine is not ready, so a new
+      # project goes setup, init, start in one go and a ready machine is
+      # not made to wait on brew. A check that still fails is reported and
+      # init carries on: the file it writes needs none of them.
+      #
+      # @param options [Hash]
+      # @return [void]
+      def prepare(options)
+        return if machine.ready?
+
+        UI.line("This machine is missing something openlanes needs; running openlanes setup first.")
+        outcome = machine.call(dry_run: dry_run?(options))
+        $stderr.write(OpenLanes::Setup.render(outcome.checks))
+        warn("Still not ready: run each fix above, then openlanes setup.") unless outcome.ok?
+      end
+
+      # A named seam, so a spec can stand in for brew, gh and Redis.
+      #
+      # @return [OpenLanes::Setup::Machine]
+      def machine = @machine ||= OpenLanes::Setup.machine
+
+      # The five values, each from its flag, else asked on a terminal, else
       # its default. The result is parsed back as the file would be, so
       # `init` cannot write a file every other command then refuses.
       #
@@ -75,8 +100,9 @@ module OpenLanes
         lane = options[:lane] || (ask ? prompt.select("Default lane for new plans:", Plans::Spec::LANES.map(&:to_s)) : "full")
         frontend = options.key?(:frontend) ? options[:frontend] : (ask_frontend if ask)
         jobs = options[:jobs] || (prompt.ask("Plans to run at once (blank: cores - 2):") if ask)
+        quality = options[:quality] || (ask_quality if ask)
 
-        draft = Config.new(project:, lane: lane.to_sym, frontend:, jobs: count(jobs))
+        draft = Config.new(project:, lane: lane.to_sym, frontend:, jobs: count(jobs), desired_codebase_quality: quality&.to_sym)
         Config.parse(draft.to_yaml, path: File.join(root, Config::FILE))
       end
 
@@ -86,6 +112,17 @@ module OpenLanes
         { "YES" => true, "NO" => false }[choice]
       end
 
+      # R4's question. Left unanswered under -y, so the first
+      # `review-ok-not-perfect` pull request asks it instead.
+      #
+      # @return [String]
+      def ask_quality
+        prompt.select("Please indicate the desired quality of the codebase (this affects the severity of items " \
+                      "found during review that will require rework):",
+          { "High quality, but slower and more expensive: a review-ok-not-perfect PR returns to developers" => "high",
+            "Good enough, but faster and cheaper, think MVP: review-ok-not-perfect is accepted"             => "mvp" })
+      end
+
       # @param value [String, Integer, nil]
       # @return [Integer, nil]
       def count(value)

data/lib/openlanes/cli/linear/subcommands/import.rb

@@ -39,7 +39,7 @@ module OpenLanes
         # @param options [Hash]
         # @return [void]
         def call(team:, **options)
-          tree = tree_for(options)
+          tree = tree_for(options).everything
           require_project!(options)
           import = build(tree, team, resolve_project(team, tree, options), options)
 

data/lib/openlanes/cli/linear/subcommands/projects.rb

@@ -16,7 +16,7 @@ module OpenLanes
         # @param options [Hash]
         # @return [void]
         def call(team:, **options)
-          tree = tree_for(options)
+          tree = tree_for(options).everything
           _api, survey = survey_for(team, tree)
 
           survey.projects.each { |project| puts row(project) }

data/lib/openlanes/cli/list_plans/list_plans.rb

@@ -6,12 +6,18 @@ module OpenLanes
     class ListPlans < Base
       desc "Print every plan, its state, and its pull requests"
 
-      example ["", "-D .plans", "| less -R"]
+      option :all,
+        type:    :boolean,
+        default: false,
+        desc:    "Also list the plans in archive/, deferred/ and abandoned/"
+
+      example ["", "--all", "-D .plans", "| less -R"]
 
       # @param options [Hash]
       # @return [void]
       def call(**options)
-        reporter = Presentation.reporter(tree: tree_for(options))
+        tree = tree_for(options)
+        reporter = Presentation.reporter(tree: options[:all] ? tree.everything : tree)
         $stdout.write(reporter.render)
 
         exit 1 unless reporter.inconsistent.empty?

data/lib/openlanes/cli/mail/subcommands/ack.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    module Mail
+      # `openlanes mail ack` — say a message was read.
+      #
+      # Delivery cannot say it: a message that reached `state.json` may sit
+      # there for a whole round while its reader never polls. Only the reader
+      # knows, so only the reader writes `read: "yes"`.
+      class Ack < Base
+        include Locating
+
+        desc "Mark a message in a plan's mailbox as read"
+
+        argument :number, type: :string, required: true, desc: "The message's number, as `mail read` prints it"
+
+        option :plan, required: true, desc: "Which plan: NNN or NNN.MM"
+        option :for, required: true, desc: "The agent that read it, who must be its recipient"
+
+        example [
+          "--plan 003 --for rey-frontend 4   # rey read #4"
+        ]
+
+        # @param number [String]
+        # @param options [Hash]
+        # @return [void]
+        def call(number:, **options)
+          quiet?(options)
+          mailbox = mailbox_for(options)
+          message = begin
+            mailbox.ack(number, by: options[:for])
+          rescue OpenLanes::Error => e
+            refuse(e.message, 65)
+          end
+
+          return if quiet?(options)
+
+          # A mailbox.md message is history and already counts as read, so
+          # nothing was written; saying "read by" would claim a record that
+          # does not exist.
+          if mailbox.legacy?(message.number)
+            return UI.line("##{message.number} is a legacy message in #{File.basename(mailbox.dir)}/#{Plans::Mailbox::FILENAME}, " \
+                           "already counted as read; nothing was written")
+          end
+
+          UI.line("##{message.number} read by #{message.to}, in #{File.basename(mailbox.dir)}/#{Plans::PlanState::FILENAME}")
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/mail/subcommands/render.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    module Mail
+      # `openlanes mail render` — the whole exchange, as Markdown, on STDOUT.
+      #
+      # The JSON is the record. This prints a view of it and writes no file,
+      # so there is never a second copy in the plan folder to disagree with
+      # the first.
+      class Render < Base
+        include Locating
+
+        desc "Print a plan's whole mailbox as Markdown"
+
+        option :plan, required: true, desc: "Which plan: NNN or NNN.MM"
+
+        example [
+          "--plan 003            # every message, with read or unread",
+          "--plan 003 > mail.md  # keep a copy wherever you like"
+        ]
+
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          puts mailbox_for(options).render
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/mail/subcommands/send.rb

@@ -30,6 +30,7 @@ module OpenLanes
           rescue OpenLanes::Error => e
             refuse(e.message, 64)
           end
+          publish(mailbox, message)
 
           return if quiet?(options)
 
@@ -37,6 +38,31 @@ module OpenLanes
           # four-line frame around "#7 → rey-frontend" is noise it reads.
           UI.line("##{message.number} → #{message.to}, in #{File.basename(mailbox.dir)}/#{Plans::PlanState::FILENAME}")
         end
+
+        private
+
+        # Hand the message to the harness over Redis, when there is one.
+        # `state.json` already has it, so no Redis is not a failure and says
+        # nothing: an agent that sees a warning on every send learns to
+        # ignore warnings. The keys are the plans directory's checkout, not
+        # this process's, because an agent in a worktree sends to the run in
+        # the main checkout.
+        #
+        # @param mailbox [OpenLanes::Plans::Mailbox]
+        # @param message [OpenLanes::Plans::Mailbox::Message]
+        # @return [void]
+        def publish(mailbox, message)
+          feature = Plans::Feature.parse(mailbox.dir) or return
+          root = File.dirname(mailbox.dir, 2)
+          store = Live.connect(Live.redis_url(config: Config.current))
+          begin
+            Live::Mail.new(store:, keys: Live.keys(root:)).publish(plan: feature.ordinal, message:)
+          ensure
+            store.close
+          end
+        rescue Live::Unavailable
+          nil
+        end
       end
     end
   end

data/lib/openlanes/cli/resync/subcommands/dirs.rb

@@ -4,42 +4,83 @@ module OpenLanes
   module CLI
     # `openlanes resync …`
     module Resync
-      # `resync dirs` — reconcile folder names with folder contents.
+      # `resync dirs` — reconcile folder names and places with folder contents.
       class Dirs < Base
-        desc "Rename plan folders so the name matches the contents and the NNN.MM form"
+        desc "Rename and move plan folders so the name, the place and the contents agree"
 
-        dry_run_option "Rename nothing; print what would be renamed"
+        dry_run_option "Rename nothing; print what would be renamed or moved"
 
         example [
-          "-n              # show what would be renamed",
+          "-n              # show what would be renamed or moved",
           "                # do it"
         ]
 
         # @param options [Hash]
         # @return [void]
         def call(**options)
-          changes = OpenLanes::Lifecycle.resync_dirs(tree: tree_for(options))
-                                        .call(commit: !dry_run?(options))
+          resync = OpenLanes::Lifecycle.resync_dirs(tree: tree_for(options))
+          locks = resync.locks
+          rewrites = resync.rewrites
+          changes = resync.call(commit: !dry_run?(options))
 
-          if changes.empty?
-            success("Every folder is already named NNN.MM-<emoji> → <slug> and the emoji matches.") unless quiet?(options)
+          report_locks(locks, options)
+          report_rewrites(rewrites, options)
+
+          if changes.empty? && rewrites.empty?
+            unless quiet?(options)
+              success("Every folder is already named NNN.MM━━<emoji>━━❯<slug>, in its place, and the emoji matches.")
+            end
             return
           end
 
           changes.each do |change|
-            puts "#{change.dirname}\t#{File.basename(change.target)}\t#{change.reason}"
+            puts "#{change.dirname}\t#{change.target_name}\t#{change.reason}"
             next if quiet?(options)
 
-            say("#{paint(change.dirname, :bright_black)} → #{File.basename(change.target)}")
+            say("#{paint(change.dirname, :bright_black)} → #{change.target_name}")
             say("  #{paint(change.reason, :yellow)}", bullet: " ")
           end
 
           return if quiet?(options)
 
+          total = changes.size + rewrites.size
           if dry_run?(options)
-            dry_run_footer(changes.size, "rename#{"s" unless changes.size == 1}")
+            dry_run_footer(total, "change#{"s" unless total == 1}")
           else
-            success("Renamed #{changes.size} folder#{"s" unless changes.size == 1}.")
+            success("Renamed #{changes.size} folder#{"s" unless changes.size == 1}, " \
+                    "rewrote #{rewrites.size} spec#{"s" unless rewrites.size == 1}.")
+          end
+        end
+
+        private
+
+        # @param rewrites [Array<OpenLanes::Lifecycle::Resync::Dirs::Rewrite>]
+        # @param options [Hash]
+        # @return [void]
+        def report_rewrites(rewrites, options)
+          rewrites.each do |rewrite|
+            puts "#{rewrite.dirname}/spec.md\t#{rewrite.dirname}/spec.md\t#{rewrite.reason}"
+            say("#{rewrite.dirname}/spec.md: #{paint(rewrite.reason, :yellow)}") unless quiet?(options)
+          end
+        end
+
+        # A lock keeps its folder's name, so a folder that did not move needs
+        # a word about why. A dead local lock is cleared by a real run; one
+        # from another machine is only ever reported.
+        #
+        # @param locks [Array<OpenLanes::Lifecycle::Resync::Dirs::HeldLock>]
+        # @param options [Hash]
+        # @return [void]
+        def report_locks(locks, options)
+          return if quiet?(options)
+
+          locks.each do |held|
+            verdict = if held.foreign? then "another machine's lock; left alone"
+                      elsif held.stale? then dry_run?(options) ? "its process is gone; would clear it" : "its process is gone; cleared"
+                      else "an agent is working in it; not renamed"
+                      end
+            say("🔑 #{held}")
+            say("  #{paint(verdict, :yellow)}", bullet: " ")
           end
         end
       end