openlanes 3.0.1 → 3.1.0

data/lib/openlanes/cli/start/start.rb

@@ -20,10 +20,10 @@ module OpenLanes
 
       # Inherited from `run`, and meaningless here: a dry run publishes no
       # board, and a run without its page cannot be answered.
-      @options = options.reject { %i[dry_run web until_settled].include?(it.name) }
+      @options = options.reject { %i[dry_run web stay until_settled].include?(it.name) }
 
       option :rescan,
-        default: Engine::Dispatcher::RESCAN.to_s,
+        default: Engine::Dispatcher::RESCAN_SECONDS.to_s,
         desc:    "Seconds between rescans of .plans while idle; a command from the page rescans at once"
 
       example [
@@ -33,13 +33,10 @@ module OpenLanes
         "--plan 005             # only plan 005, until stopped"
       ]
 
-      # Exit status when Redis or the control room is not there to serve.
-      UNAVAILABLE = 69
-
       # @param options [Hash]
       # @return [void]
       def call(**options)
-        @rescan = Integer(options.fetch(:rescan, Engine::Dispatcher::RESCAN), exception: false)
+        @rescan = Integer(options.fetch(:rescan, Engine::Dispatcher::RESCAN_SECONDS), exception: false)
         refuse("--rescan takes a whole number of seconds, at least 1.", 64) unless @rescan&.positive?
 
         super
@@ -47,51 +44,10 @@ module OpenLanes
 
       private
 
-      # @param _options [Hash]
-      # @param _web [OpenLanes::Web::Launcher]
-      # @return [Hash]
-      def staying(_options, _web) = { stay: true, rescan: @rescan }
-
-      # @return [void]
-      def without_live(message, _options)
-        refuse("#{message}\n\nopenlanes start needs Redis: its control room is the only way to answer the " \
-               "agents' questions. Start redis-server, or pass --redis-url. " \
-               "`openlanes run` goes on without it, headless.",
-          UNAVAILABLE)
-      end
-
-      # @return [void]
-      def without_web(web, live, _options)
-        live.close
-        refuse("The control room did not answer on #{web.url}, and openlanes start is no use without it. " \
-               "Its log: #{web.log}",
-          UNAVAILABLE)
-      end
-
-      # A project with nothing left to do opens on the idea dialog (W19).
-      #
-      # @return [String]
-      def browser_url(web, tree)
-        open = tree.subjects.reject { Engine::Dispatcher::FINISHED.include?(it.status.key) }
-        open.empty? ? "#{web.url}#start" : web.url
-      end
-
-      # What the service did, and exit 0: stopping it on purpose is not a
-      # failure, and the failed attempts it lived through are listed above
-      # the box.
-      #
-      # @return [void]
-      def finish(runner, attempts, options, seconds:)
-        puts_report(attempts, Engine.tally(attempts:, seconds:).render)
-        unless quiet?(options)
-          blocked = runner.blocked.map { it.feature.ordinal }
-          lines = ["Stopped. Unfinished plans keep their state; openlanes start picks them up again."]
-          lines << "Still waiting for answers: #{blocked.join(", ")}" unless blocked.empty?
-          success("#{attempts.size} invocation#{"s" unless attempts.size == 1}, " \
-                  "#{attempts.count(&:advanced?)} advanced\n\n#{lines.join("\n")}")
-        end
-        exit(0)
-      end
+      # @param tree [OpenLanes::Plans::Tree]
+      # @param options [Hash]
+      # @return [OpenLanes::Engine::StartWorkflow]
+      def workflow(tree, options) = Engine.start(tree:, origin:, **options.except(:rescan), rescan: @rescan)
     end
   end
 end

data/lib/openlanes/cli/state/state.rb

@@ -13,7 +13,7 @@ module OpenLanes
         # @param options [Hash]
         # @return [OpenLanes::Plans::PlanState]
         def plan_state_for(options)
-          tree = tree_for(options)
+          tree = tree_for(options).everything
           ordinal = Plans::Ordinal.parse(options[:plan].to_s)
           subject = ordinal && tree.find(ordinal)
           refuse("No plan #{options[:plan]} in #{tree.dir}.\n\nKnown: #{tree.ordinals.join(", ")}", 66) unless subject

data/lib/openlanes/cli/state/subcommands/resume.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    module State
+      # `openlanes state resume` — what an interrupted agent leaves for
+      # whoever runs next, most likely itself.
+      #
+      # It used to be a `RESUME: ...` mail, which the next round had to read
+      # and believe. This is a record with fixed fields, kept in `state.json`
+      # under `last-known-state`, one per agent.
+      class Resume < Base
+        include Locating
+
+        desc "Record where an interrupted agent stood, for the next round to resume from"
+
+        option :plan, required: true, desc: "Which plan: NNN or NNN.MM"
+        option :agent, required: true, desc: "The agent recording"
+        option :round, required: true, desc: "Which round this is, as the prompt states it"
+        option :status, default: "Interrupted", values: Plans::Ledger::STATUSES, desc: "Where the agent stands"
+        option :done, desc: "What is finished, comma-separated"
+        option :remaining, desc: "What is not, comma-separated"
+        option :next_step, desc: "The exact first thing to do on resuming"
+        option :files, desc: "Files touched, comma-separated"
+
+        example [
+          %(--plan 003 --agent luke-backend --round 1 --done "B1,B2" --remaining "B3" --next-step "run rspec spec/openlanes/live" --files lib/openlanes/live/mail.rb)
+        ]
+
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          state = plan_state_for(options)
+          entry = begin
+            state.record_last_known(options[:agent],
+              Plans::LastKnownState.new(source: "agent",
+                round:         Integer(options[:round].to_s, exception: false) || refuse("--round must be a number", 64),
+                status:        options[:status],
+                done:          list(options[:done]),
+                remaining:     list(options[:remaining]),
+                next_step:     options[:next_step],
+                files_touched: list(options[:files])))
+          rescue OpenLanes::Error => e
+            refuse(e.message, 64)
+          end
+
+          return if quiet?(options)
+
+          UI.line("#{options[:agent]}: #{entry.status}, round #{entry.round}, resume record " \
+                  "in #{File.basename(state.dir)}/#{Plans::PlanState::FILENAME}")
+        end
+
+        private
+
+        # @param text [String, nil]
+        # @return [Array<String>]
+        def list(text) = text.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+    end
+  end
+end

data/lib/openlanes/cli/state/subcommands/sign.rb

@@ -20,7 +20,7 @@ module OpenLanes
         example [
           "--plan 003 --agent luke-backend --round 1 --status Started",
           "--plan 003 --agent hansolo-reviewer --round 1 --status Completed --note approved",
-          "--plan 003 --agent yoda-writer --round 1 --status Completed --next palpatine-planner"
+          "--plan 003 --agent yoda-writer --round 1 --status Completed --next luthen-rael-planner"
         ]
 
         # @param options [Hash]

data/lib/openlanes/cli/unblock/unblock.rb

@@ -3,24 +3,9 @@
 module OpenLanes
   module CLI
     # `openlanes unblock NNN…` — hand a stopped plan to the agent that
-    # drains its `blocked.md`.
-    #
-    # Deliberately not part of `run`. ⭕️ and 🅱️ are {StateMachine::SETTLED}, so
-    # the loop never offers a blocked plan to anybody, and that is the property
-    # that makes the state mean anything: the plan waits for a human, and no
-    # agent quietly decides otherwise. Answers arriving is not a fact the tool
-    # can observe, so a human typing this command *is* the signal, and there is
-    # nothing else that could produce it.
+    # drains its `blocked.md`. Why this is a command of its own rather than
+    # part of `run` is told in {Lifecycle::UnblockWorkflow}.
     class Unblock < Base
-      # The agent that knows the shape of `blocked.md`.
-      DEFAULT_AGENT = "lando-broker"
-
-      # What each token turned out to be, for whoever has to fix it.
-      PROBLEMS = {
-        missing:     "no plan of that number",
-        not_blocked: "no blocked.md, so there is nothing to drain"
-      }.freeze
-
       desc "Fold answered blocks into a plan's documents and retire blocked.md"
 
       argument :plans,
@@ -29,7 +14,9 @@ module OpenLanes
         desc:     "Which plans to drain: NNN or NNN.MM, e.g. 003 005.01"
 
       dry_run_option "Invoke no agent; print the questions still open"
-      option :agent, default: DEFAULT_AGENT, desc: "Hand the folder to a different agent"
+      option :agent,
+        default: OpenLanes::Lifecycle::UnblockWorkflow::DEFAULT_AGENT,
+        desc:    "Hand the folder to a different agent"
       option :root, desc: "Repository root the agent works in (default: the .plans parent)"
 
       example [
@@ -42,193 +29,12 @@ module OpenLanes
       # @param options [Hash]
       # @return [void]
       def call(plans:, **options)
-        tree = tree_for(options)
-        quiet?(options)
-        unblocker = Lifecycle.unblocker(tree:,
-          agent: agent_for(options),
-          root: options[:root],
-          commit: !dry_run?(options),
-          executor: Execution.executor(root: options[:root] || File.dirname(tree.dir),
-            dry_run: dry_run?(options)))
-
-        targets = unblocker.resolve(plans)
-        refused(targets, tree, options)
-        subjects = targets.select(&:drainable?).map(&:subject)
-        exit(worst(targets, [])) if subjects.empty?
-
-        credentials_warning if !dry_run?(options) && !quiet?(options)
-        preflight(subjects, unblocker, options)
-
-        outcomes = Execution.on_interrupt { unblocker.call(subjects) }
-        outcomes.each { |outcome| report(outcome, options) }
-        footer(outcomes, options) unless quiet?(options)
-        exit(worst(targets, outcomes))
-      end
-
-      private
-
-      # @param options [Hash]
-      # @return [OpenLanes::Agents::Agent]
-      def agent_for(options)
-        name = options.fetch(:agent, DEFAULT_AGENT)
-        agents = OpenLanes::Agents.registry
-        agents.find(name) or
-          refuse("No agent called #{name}.\n\nKnown: #{agents.all.map(&:name).join(", ")}", 65)
-      end
-
-      # A number that names no folder, or a folder that was never stopped, is
-      # refused rather than skipped. Whoever typed this believes an answer has
-      # arrived; running against a folder nobody blocked and saying nothing is
-      # how you come back later to a plan nobody touched and no record of why.
-      #
-      # Every bad token is reported, not just the first, because stopping at
-      # the first one hides the rest of the answer.
-      #
-      # @param targets [Array<OpenLanes::Lifecycle::Unblocker::Target>]
-      # @param tree [OpenLanes::Plans::Tree]
-      # @param options [Hash]
-      # @return [void]
-      def refused(targets, tree, options)
-        problems = targets.reject(&:drainable?)
-        return if problems.empty?
-
-        problems.each do |target|
-          state = target.subject ? target.subject.status.key : "unknown"
-          puts "#{target.token}\t#{state}\t0 open\t#{PROBLEMS.fetch(target.problem)}"
-        end
-        return if quiet?(options)
-
-        error("#{problems.size} of the plans named cannot be drained:\n\n" +
-              problems.map { |t| "  #{t.token} — #{PROBLEMS.fetch(t.problem)}" }.join("\n") +
-              "\n\nThe tree holds: #{tree.ordinals.join(", ")}")
-      end
-
-      # What each folder is waiting on, said BEFORE the agent is invoked.
-      #
-      # This is the half that was missing. A real run hands the folder to an
-      # agent that can take a quarter of an hour, and until it came back the
-      # terminal showed nothing at all — a run that had found nothing to do and
-      # a run still working looked exactly alike.
-      #
-      # @param subjects [Array<OpenLanes::Plans::Subject>]
-      # @param unblocker [OpenLanes::Lifecycle::Unblocker]
-      # @param options [Hash]
-      # @return [void]
-      def preflight(subjects, _unblocker, options)
-        return if quiet?(options)
-
-        subjects.each do |subject|
-          questions = Lifecycle::Unblocker.questions(subject)
-          answered = questions.count(&:answered)
-          say("#{paint(subject.feature.ordinal.to_s, :bright_black)} #{subject.status.emoji} " \
-              "#{subject.feature.title} — #{summary(questions.size, answered)}")
-          detail(subject, questions)
-        end
-      end
-
-      # @param open [Integer]
-      # @param answered [Integer]
-      # @return [String]
-      def summary(open, answered)
-        return "nothing open" if open.zero?
-
-        "#{open} open, #{answered.zero? ? "none answered yet" : "#{answered} with an answer waiting"}"
-      end
-
-      # @param subject [OpenLanes::Plans::Subject]
-      # @param questions [Array<OpenLanes::Lifecycle::Unblocker::Question>]
-      # @return [void]
-      def detail(subject, questions)
-        if subject.unreadable_block?
-          say("  #{paint("blocked.md names no `## B<n>` question, so nothing here can be drained", :red)}",
-            bullet: " ")
-          say("  #{paint("Number each open question `## B1`, `## B2`, and each answer `## A1`, `## A2`.", :yellow)}",
-            bullet: " ")
-        elsif questions.empty?
-          say("  #{paint("nothing left open", :green)}", bullet: " ")
-        else
-          questions.each { |question| say("  #{paint(question.to_s, :yellow)}", bullet: " ") }
-        end
-      end
-
-      # One plan, after the fact: the deliverable line on STDOUT, and what
-      # changed on STDERR.
-      #
-      # @param outcome [OpenLanes::Lifecycle::Unblocker::Outcome]
-      # @param options [Hash]
-      # @return [void]
-      def report(outcome, options)
-        moved = movement(outcome, !dry_run?(options))
-        puts "#{outcome.ordinal}\t#{outcome.ok ? outcome.subject.status.key : "failed"}\t" \
-             "#{outcome.after.size} open\t#{moved}\t#{outcome.note}"
-        # A dry run changed nothing, so the preflight above it is still the
-        # whole truth. Printing the same three lines again reads as a second
-        # pass that found the same thing, which is not what happened.
-        return if quiet?(options) || dry_run?(options)
-
-        say("#{paint(outcome.ordinal.to_s, :bright_black)} #{outcome.subject.status.emoji} " \
-            "#{outcome.subject.feature.title} — #{paint(moved, outcome.ok ? :green : :red)}")
-        detail(outcome.subject, outcome.after)
-      end
-
-      # What the file says happened, rather than what the agent claims. The
-      # questions are counted off disk on both sides of the run.
-      #
-      # @param outcome [OpenLanes::Lifecycle::Unblocker::Outcome]
-      # @param commit [Boolean]
-      # @return [String]
-      def movement(outcome, commit)
-        return "failed" unless outcome.ok
-        return "not attempted" unless commit
-        return "blocked.md retired" if outcome.cleared?
-        return "nothing folded" if outcome.folded.empty?
-
-        "folded #{outcome.folded.map { |n| "B#{n}" }.join(", ")}"
-      end
-
-      # @param outcomes [Array<OpenLanes::Lifecycle::Unblocker::Outcome>]
-      # @param options [Hash]
-      # @return [void]
-      def footer(outcomes, options)
-        failed = outcomes.reject(&:ok)
-
-        if dry_run?(options)
-          warn("Dry run: no agent was invoked, and #{outcomes.size} " \
-               "plan#{"s" unless outcomes.size == 1} #{outcomes.size == 1 ? "is" : "are"} unchanged.\n" \
-               "Re-run without --dry-run to fold in whatever has been answered.")
-          return
-        end
-
-        return error(failed.map { |o| "#{o.ordinal}: #{o.note}" }.join("\n")) unless failed.empty?
-
-        cleared = outcomes.count(&:cleared?)
-        folded = outcomes.sum { |o| o.folded.size }
-        waiting = outcomes.sum { |o| o.after.size }
-        success("#{folded} question#{"s" unless folded == 1} folded in · " \
-                "#{cleared} plan#{"s" unless cleared == 1} out of the block · " \
-                "#{waiting} still waiting on a human." +
-                (if folded.zero?
-                   "\n\nNothing moved. An answer has to be written into blocked.md as its own " \
-                     "`## A<n>` section, answering the `## B<n>` of the same number, before " \
-                     "there is anything to fold."
-                 else
-                   ""
-                 end))
-      end
-
-      # The most serious thing that happened, as an exit status. A tree that
-      # was partly drained still exits non-zero when part of it could not be.
-      #
-      # @param targets [Array<OpenLanes::Lifecycle::Unblocker::Target>]
-      # @param outcomes [Array<OpenLanes::Lifecycle::Unblocker::Outcome>]
-      # @return [Integer]
-      def worst(targets, outcomes)
-        problems = targets.map(&:problem)
-        return 66 if problems.include?(:missing)
-        return 65 if problems.include?(:not_blocked)
-        return 1 unless outcomes.all?(&:ok)
-
-        0
+        workflow = OpenLanes::Lifecycle.unblock(tree: tree_for(options),
+          agent:   options.fetch(:agent, OpenLanes::Lifecycle::UnblockWorkflow::DEFAULT_AGENT),
+          root:    options[:root],
+          dry_run: dry_run?(options),
+          quiet:   quiet?(options))
+        exit(unwrap(workflow.call(plans)))
       end
     end
   end

data/lib/openlanes/cli/web/web.rb

@@ -6,11 +6,13 @@ module OpenLanes
     # starts one beside the engine; this is that server, and with `--demo`
     # the same server over a pretend engine, for Cypress and front-end work.
     class Web < Base
-      desc "Serve the control room page and its API on 127.0.0.1"
+      desc "Serve the control room page and its API, on 127.0.0.1 unless told otherwise"
 
       option :port,
+        aliases: ["-p"],
         default: OpenLanes::Web::DEFAULT_PORT.to_s,
         desc:    "Port to listen on"
+      listen_options
       option :redis_url,
         desc: "Redis the engine publishes to (default: $OPENLANES_REDIS_URL, else .openlanes.yml redis_url, else $REDIS_URL, " \
               "else #{Live::DEFAULT_URL})"
@@ -23,11 +25,19 @@ module OpenLanes
         default: false,
         desc:    "Serve a sample run that moves and answers commands, with no agents. " \
                  "Uses Redis when it answers, an in-memory store when it does not"
+      option :identity,
+        desc: "With --demo: register as USER@HOST instead of this login and host, so a second demo on " \
+              "another port is another machine on the same Redis"
+      log_options
 
       example [
         "                 # serve the live run of this checkout",
         "--demo --no-open # the sample run, for Cypress and npm run dev",
-        "--port 4848      # somewhere other than 11000"
+        "--port 4848      # somewhere other than 11000",
+        "-I --admin-credentials admin:s3cret # reachable from other machines, behind a login",
+        "-i 127.0.0.1,192.168.1.20 -p 4848 # loopback and one LAN address",
+        "--bind 0.0.0.0 --admin-credentials admin:s3cret # every interface, behind a login",
+        "--demo --port 11101 --identity demo@second-machine # a second machine for the chat"
       ]
 
       # @param options [Hash]
@@ -35,16 +45,27 @@ module OpenLanes
       def call(**options)
         tree = tree_for(options)
         root = File.dirname(tree.dir)
+        logging(options, root:)
+        listen = listen_for(options)
+        credentials = credentials_for(options, listen)
         url = Live.redis_url(option: redis_url_option(options), config: Config.current)
+        node = node_for(root, options)
         stores = stores_for(url, options)
-        node = Live::Node.current(root:)
         keys = Live.keys(root:, node:)
         keys = keys.with(repo: "demo/#{keys.repo}") if options[:demo]
-        demo = OpenLanes::Web.demo(store: stores.current, keys:).start if options[:demo]
+        demo = OpenLanes::Web.demo(store: stores.current, keys:, node: declared(node, options)).start if options[:demo]
         copilot = demo ? OpenLanes::Web::Demo::COPILOT : copilot_for(root:, tree:, stores:, keys:)
-        context = OpenLanes::Web.context(stores:, keys:, plans_dir: tree.dir, url: stores.current.url, node:, demo:, copilot:)
-        server = OpenLanes::Web.server(app: OpenLanes::Web.app(context), context:, port: options[:port])
-        serve(server, options, keys:, node:, url: stores.current.url)
+        context = OpenLanes::Web.context(stores:,
+          keys:,
+          plans_dir: tree.dir,
+          url: stores.current.url,
+          node:,
+          demo:,
+          copilot:,
+          listen:,
+          credentials:)
+        server = OpenLanes::Web.server(app: OpenLanes::Web.app(context), context:, port: options[:port], listen:)
+        serve(server, options, keys:, node:, url: stores.current.url, credentials:)
       ensure
         demo&.stop
         copilot.stop if copilot.respond_to?(:stop)
@@ -52,6 +73,19 @@ module OpenLanes
 
       private
 
+      # Logs as `web`, to the file the engine named in this process's
+      # environment when the engine spawned it, else to the same default the
+      # engine would pick, so a server started by hand still joins the run's log.
+      #
+      # @param options [Hash]
+      # @param root [String]
+      # @return [OpenLanes::Log::Settings]
+      def logging(options, root:)
+        Log.setup(Log::Settings.from(options, root:), name: "web")
+      rescue Log::Invalid => e
+        refuse(e.message, 64)
+      end
+
       # `--redis-url`, else the URL `openlanes run` hands its server through the
       # environment, so a password never shows in `ps`. Both are passed to
       # {Live.redis_url} as the option, which keeps the rest of its order.
@@ -63,6 +97,27 @@ module OpenLanes
         [options[:redis_url], env[OpenLanes::Web::Launcher::REDIS_URL_ENV]].find { !it.to_s.strip.empty? }
       end
 
+      # This machine, or under `--demo` the one `--identity` declares. A live
+      # server is refused one: its node id is what claims and commands are
+      # keyed by, and a run under a borrowed name would answer for a machine
+      # it is not.
+      #
+      # @param root [String]
+      # @param options [Hash]
+      # @return [OpenLanes::Live::Node]
+      def node_for(root, options)
+        identity = options[:identity].to_s.strip
+        return Live::Node.current(root:) if identity.empty?
+
+        refuse("--identity is for the demo only; pass --demo with it.", 64) unless options[:demo]
+        Live::Node.declared(identity, root:)
+      rescue Live::Node::Invalid => e
+        refuse("--identity: #{e.message}", 64)
+      end
+
+      # @return [OpenLanes::Live::Node, nil] the node the demo publishes as, when declared
+      def declared(node, options) = options[:identity].to_s.strip.empty? ? nil : node
+
       # @return [OpenLanes::Web::Stores]
       def stores_for(url, options)
         store = Live.connect(url)
@@ -89,22 +144,43 @@ module OpenLanes
       # Listen until INT or TERM.
       #
       # @return [void]
-      def serve(server, options, keys:, node:, url:)
+      def serve(server, options, keys:, node:, url:, credentials:)
         begin
           server.start
         rescue Errno::EADDRINUSE
           refuse("Port #{options[:port]} is taken: another `openlanes web` may already be serving. " \
                  "Pass --port to use another.",
             69)
+        rescue Errno::EADDRNOTAVAIL
+          refuse("--ips #{server.listen.ips.join(",")}: an address is not one of this machine's.", 69)
         end
         %w[INT TERM].each { |name| Signal.trap(name) { Thread.new { server.stop } } }
         unless quiet?(options)
           info("Control room: #{server.url}#{" (demo)" if options[:demo]}\n" \
+               "#{"Also on: #{(server.urls - [server.url]).join(", ")}\n" if server.listen.public?}" \
                "Redis: #{Live.mask(url)} as #{node.label} (#{keys.node}), repository #{keys.repo}")
         end
+        exposed(server, credentials)
+        Log.logger.info("listening", url: server.url, urls: server.urls, demo: options[:demo], repo: keys.repo)
         OpenLanes::Web.open(server.url) if options[:open]
         server.wait
       end
+
+      # Said even under --quiet, and logged: listening beyond this machine
+      # hands anyone with the login the controls, and that is never silent.
+      # {#credentials_for} has already refused a public server without one.
+      #
+      # @param server [OpenLanes::Web::Server]
+      # @param credentials [OpenLanes::Web::AdminAuth::Credentials]
+      # @return [void]
+      def exposed(server, credentials)
+        return unless server.listen.public?
+
+        ips = server.listen.public_ips.join(", ")
+        warn("Listening on #{ips}, behind a login as #{credentials.user}: anyone with it who can reach this " \
+             "machine on port #{server.port} can stop agents, answer their questions and message them.")
+        Log.logger.warn("listening beyond loopback", ips: server.listen.public_ips, port: server.port, user: credentials.user)
+      end
     end
   end
 end

data/lib/openlanes/cli/worktree/worktree.rb

@@ -18,7 +18,7 @@ module OpenLanes
       example [
         "002                         # create/seed the worktree for plan 002.00",
         "002.01                      # create/seed the worktree for plan 002.01",
-        "002.00-⚪️ → update-dsl      # find the plan by its folder name",
+        "002.00━━⚪━━❯update-dsl      # find the plan by its folder name",
         "--skip-seed 003             # create the worktree but don't seed it"
       ]
 

data/lib/openlanes/cli/worktree/worktree_prune.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes worktree prune` — remove the plan worktrees whose pull
+    # request merged into the default branch and whose work landed with it.
+    #
+    # The engine retires a plan's checkout as it sees the merge (see
+    # {Engine::Merging}). This is for the ones it never saw: a run that
+    # crashed, a merge made while no engine was up, checkouts from before
+    # retirement existed. The rules are {Vcs::Worktree#retire}'s, so a
+    # checkout with uncommitted work, unmerged commits or somebody's lock
+    # in it stays, and the table says why.
+    class WorktreePrune < Base
+      desc "Remove plan worktrees whose pull request merged and whose work is on main"
+
+      dry_run_option "Remove nothing; print what would be removed and why the rest stay"
+
+      example [
+        "                            # remove every worktree whose work landed",
+        "-n                          # show what would be removed, and why the rest stay"
+      ]
+
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        worktree = OpenLanes::Vcs.worktree(root: OpenLanes::Vcs::Worktree.main_root(File.dirname(tree_for(options).dir)))
+        refuse("#{worktree.root} is not a git repository", 66) unless worktree.repository?
+
+        github = OpenLanes::Vcs.github
+        locks = OpenLanes::Engine.agent_locks(worktree.root)
+        held = ->(path) { locks&.held_in(path)&.to_s }
+        rows = worktree.list.map { row(worktree, github, it, held, dry_run?(options)) }
+        return UI.line("No plan worktrees under #{worktree.dir}.") if rows.empty? && !quiet?(options)
+
+        puts table([%w[WORKTREE BRANCH PR RESULT], *rows]) unless quiet?(options)
+        return unless dry_run?(options)
+
+        count = rows.count { it.last.start_with?("would be removed") }
+        dry_run_footer(count, "removal#{"s" unless count == 1}")
+      end
+
+      private
+
+      # @return [Array<String>] one table row
+      def row(worktree, github, path, held, dry_run)
+        name = File.basename(path)
+        branch = worktree.branch_of(path)
+        return [name, "(detached)", "", "kept: detached HEAD, no branch to match a pull request"] if branch.empty?
+
+        pull = github.merged_pull_for(branch)
+        return [name, branch, "", "kept: no merged pull request"] unless pull
+
+        retired = worktree.retire(path, merge_commit: pull[:merge_commit], base: pull[:base], held:, dry_run:)
+        [name, branch, "##{pull[:number]}", result(retired)]
+      rescue OpenLanes::Error => e
+        [name, branch.to_s, "", "kept: #{e.message.lines.first.to_s.strip}"]
+      end
+
+      # @param retired [OpenLanes::Vcs::Worktree::Retirement]
+      # @return [String]
+      def result(retired)
+        return "removed (#{retired.sha[0, 8]}): #{retired.reason}" if retired.removed?
+        return retired.reason if retired.reason.start_with?("would be removed")
+
+        "kept: #{retired.reason}"
+      end
+
+      # @param rows [Array<Array<String>>]
+      # @return [String]
+      def table(rows)
+        widths = rows.transpose.map { |column| column.map { it.to_s.length }.max }
+        rows.map { |row| row.each_with_index.map { |cell, i| cell.to_s.ljust(widths[i]) }.join("  ").rstrip }.join("\n")
+      end
+    end
+  end
+end