openlanes 3.0.0 → 3.0.1

data/lib/openlanes/live/copilot.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module OpenLanes
+  module Live
+    # The conversation with the run's copilot, c3po-operator (W17): one Redis
+    # stream per node ({Keys#copilot}) holding every turn, the person's and
+    # the copilot's, in the order they were said. The page reads it once with
+    # {#history} and then follows it on the event stream it already has
+    # (`event: copilot`), so the copilot needs no transport of its own.
+    #
+    # Who answers is the responder's business, not this class's: the API
+    # server hands it {Operator}, which runs c3po-operator, and `--demo` a
+    # canned line. Whatever answers writes {Turn}s, and {Turn.check} refuses
+    # a card that lacks what the page needs to draw it, whoever wrote it.
+    class Copilot
+      # A message the person may not send as written.
+      class Invalid < Error; end
+
+      # A message nobody is there to answer.
+      class Unanswered < Error; end
+
+      # Who spoke a turn.
+      SPEAKERS = %w[you copilot].freeze
+
+      # What a turn is: words, a red card asking to confirm a command that
+      # cannot be undone, or a quiet card holding a drafted answer.
+      KINDS = %w[text confirm draft].freeze
+
+      # The fields each card cannot be drawn without.
+      FIELDS = {
+        "text"    => [],
+        "confirm" => %w[command confirm done],
+        "draft"   => %w[question draft]
+      }.freeze
+
+      # Characters one message may carry. A longer one is a paste gone
+      # wrong, and the agent would pay for every token of it.
+      LIMIT = 4000
+
+      # Tokens and model before the copilot has said anything that counts them.
+      NO_USAGE = { model: nil, up: 0, down: 0 }.freeze
+
+      # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+      # @param keys [OpenLanes::Live::Keys]
+      # @param responder [#call, nil] the person's {Turn} in, the copilot's
+      #   {Turn}s out; nil for a reader, which {#say} refuses to write through
+      def initialize(store:, keys:, responder: nil)
+        @store = store
+        @keys = keys
+        @responder = responder
+      end
+
+      # Record the person's message, and nothing more. Answering is
+      # {#answer}'s, run apart from the request that brought the message: a
+      # real responder is a `claude -p` call, and a POST held open for the
+      # whole of it would keep the page from showing the message, or that
+      # the copilot is reading, until the answer was already written.
+      #
+      # @param input [String, Hash] `CopilotMessage`: `{id, text}`
+      # @return [OpenLanes::Live::Copilot::Turn] the person's turn
+      # @raise [OpenLanes::Live::Copilot::Invalid] for the API server's 422
+      # @raise [OpenLanes::Live::Copilot::Unanswered] when nobody would answer
+      def say(input)
+        turn = message(input)
+        # Refused before it is stored: a message kept where nothing will ever
+        # answer it reads, on the page, as a copilot that is merely slow.
+        raise Unanswered, "the copilot is not running in this server" unless @responder
+
+        turn.tap { append(it) }
+      end
+
+      # Store whatever the responder answers to +turn+. A responder that
+      # fails is answered for, under the reply id the page waits for, so the
+      # failure shows in the conversation rather than as a page reading
+      # forever.
+      #
+      # @param turn [OpenLanes::Live::Copilot::Turn] the person's, from {#say}
+      # @return [Array<OpenLanes::Live::Copilot::Turn>] what was stored
+      def answer(turn)
+        replies = begin
+          @responder.call(turn)
+        rescue StandardError => e
+          [Turn.new(id: "#{turn.id}.1", from: "copilot", kind: "text", text: "c3po-operator could not answer: #{e.message}")]
+        end
+        replies.each { append(it) }
+      end
+
+      # The conversation as the page draws it on load: the newest turns,
+      # oldest first, and the copilot's latest model and tokens. The usage is
+      # looked for in the whole retained stream when the newest turns carry
+      # none, so a run of unmetered turns does not reset the header to zero.
+      #
+      # @param count [Integer]
+      # @return [Hash] `CopilotLog`: `{turns:, usage:}`
+      def history(count: 100)
+        turns = newest_turns(count)
+        usage = latest_usage(turns)
+        usage ||= latest_usage(newest_turns(Keys::COPILOT_LENGTH)) if turns.size == count
+        { turns:, usage: usage || NO_USAGE }
+      end
+
+      # Turns written after +after+, oldest first, with their stream ids.
+      #
+      # @param after [String] a stream id
+      # @return [Array<Array(String, Hash)>]
+      def since(after)
+        @store.xread(@keys.copilot, id: after).map { |entry| [entry.id, JSON.parse(entry.fields["json"])] }
+      end
+
+      # @return [String] the newest turn's stream id, `0-0` when there is none
+      def newest = @store.xrevrange(@keys.copilot, count: 1).first&.id || "0-0"
+
+      private
+
+      # @return [OpenLanes::Live::Copilot::Turn]
+      def message(input)
+        data = input.is_a?(String) ? JSON.parse(input) : input
+        raise Invalid, "a message is a JSON object" unless data.is_a?(Hash)
+
+        id = data["id"].to_s
+        text = data["text"].to_s.strip
+        raise Invalid, "id must be 1 to 64 letters, digits, - or _" unless id.match?(Command::ID)
+        raise Invalid, "a message needs text" if text.empty?
+        raise Invalid, "a message is at most #{LIMIT} characters" if text.length > LIMIT
+
+        Turn.new(id:, from: "you", kind: "text", text:)
+      rescue JSON::ParserError => e
+        raise Invalid, "not a message: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # @return [Array<Hash>] up to +count+ turns, oldest first
+      def newest_turns(count)
+        @store.xrevrange(@keys.copilot, count:).reverse.map { JSON.parse(it.fields["json"]) }
+      end
+
+      # @return [Hash, nil]
+      def latest_usage(turns) = turns.reverse_each.map { it["usage"] }.find(&:itself)
+
+      # @return [void]
+      def append(turn)
+        @store.xadd(@keys.copilot, { json: turn.to_json }, maxlen: Keys::COPILOT_LENGTH)
+      end
+    end
+
+    class Copilot
+      # One thing said in the conversation: `CopilotTurn` in `types.ts`.
+      #
+      # @!attribute [r] id
+      #   @return [String] the person's message id; a reply's is that id, a
+      #     dot and its place among the replies, so a reply names what it answers
+      # @!attribute [r] from
+      #   @return [String] one of {SPEAKERS}
+      # @!attribute [r] kind
+      #   @return [String] one of {KINDS}
+      # @!attribute [r] text
+      #   @return [String]
+      # @!attribute [r] at
+      #   @return [Time]
+      # @!attribute [r] usage
+      #   @return [Hash, nil] `{model, up, down}`, the copilot's running total
+      #     after this turn; nil on the person's turns and on answers no model
+      #     wrote
+      # @!attribute [r] fields
+      #   @return [Hash{String => Object}] what a card needs, per {FIELDS}
+      Turn = Data.define(:id, :from, :kind, :text, :at, :usage, :fields) do
+        def initialize(at: Time.now, usage: nil, fields: {}, **rest)
+          super
+          Turn.check(self)
+        end
+
+        # @return [Hash] as the wire carries it
+        def wire = { id:, from:, kind:, text:, at: at.utc.iso8601, usage: }.merge(fields.transform_keys(&:to_sym))
+
+        # @return [String]
+        def to_json(*) = JSON.generate(wire)
+      end
+
+      class Turn
+        # The keys every turn has; anything else belongs to {FIELDS}.
+        BASE = %w[id from kind text at usage].freeze
+
+        # @param data [Hash] a turn as the wire carries it
+        # @return [OpenLanes::Live::Copilot::Turn]
+        # @raise [OpenLanes::Live::Copilot::Invalid]
+        def self.parse(data)
+          data = data.transform_keys(&:to_s)
+          new(id: data["id"].to_s,
+            from: data["from"].to_s,
+            kind: data["kind"].to_s,
+            text: data["text"].to_s,
+            at: data["at"] ? Time.iso8601(data["at"]) : Time.now,
+            usage: data["usage"],
+            fields: data.except(*BASE))
+        rescue ArgumentError => e
+          raise Invalid, "not a turn: #{e.message}"
+        end
+
+        # @param turn [OpenLanes::Live::Copilot::Turn]
+        # @return [void]
+        # @raise [OpenLanes::Live::Copilot::Invalid] naming what is wrong
+        def self.check(turn)
+          raise Invalid, "unknown speaker #{turn.from.inspect}" unless SPEAKERS.include?(turn.from)
+          raise Invalid, "unknown kind #{turn.kind.inspect}; known: #{KINDS.join(", ")}" unless KINDS.include?(turn.kind)
+          raise Invalid, "only the copilot draws cards" if turn.from == "you" && turn.kind != "text"
+
+          fields = turn.fields.transform_keys(&:to_s)
+          check_names(turn.kind, fields.keys)
+          check_text(turn.kind, fields)
+          check_command(fields["command"]) if turn.kind == "confirm"
+        end
+
+        # A card holds exactly its own fields: a missing one cannot be drawn,
+        # and an extra one could shadow a base key such as `id` on the wire.
+        #
+        # @return [void]
+        def self.check_names(kind, names)
+          wanted = FIELDS.fetch(kind)
+          missing = wanted - names
+          raise Invalid, "a #{kind} card needs #{missing.join(" and ")}" unless missing.empty?
+
+          extra = names - wanted
+          raise Invalid, "a #{kind} card has no #{extra.join(" or ")}" unless extra.empty?
+        end
+
+        # Every field but a command is drawn as text, so it has to be some:
+        # a blank one would draw an unnamed button or an empty draft.
+        #
+        # @return [void]
+        def self.check_text(kind, fields)
+          wrong = (FIELDS.fetch(kind) - %w[command]).reject { fields[it].is_a?(String) && !fields[it].strip.empty? }
+          raise Invalid, "a #{kind} card's #{wrong.join(" and ")} must be text" unless wrong.empty?
+        end
+
+        # A confirm card is sent through the same gate as the page's own
+        # buttons (W13), so it has to be a command that gate would take. It
+        # carries no id: the page mints one when the person presses, and an id
+        # supplied here would replace it and could repeat one already done.
+        #
+        # @return [void]
+        def self.check_command(command)
+          raise Invalid, "a confirm card's command is a JSON object" unless command.is_a?(Hash)
+
+          command = command.transform_keys(&:to_s)
+          raise Invalid, "a confirm card's command carries no id; the page mints one" if command.key?("id")
+
+          Command.parse(command.merge("id" => "card"))
+        rescue Command::Invalid => e
+          raise Invalid, "a confirm card's command is not one: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/live/keys.rb

@@ -62,6 +62,60 @@ module OpenLanes
       # @return [String]
       def run(of = node) = "#{base}:#{of}:run"
 
+      # Stream: `{json}`, one `CopilotTurn`: the conversation with this
+      # node's copilot (W17), the person's messages and its answers in the
+      # order they were said. {Copilot} writes and reads it.
+      #
+      # @param of [String]
+      # @return [String]
+      def copilot(of = node) = "#{base}:#{of}:copilot"
+
+      # Hash: `session`, `model`, `up` and `down`, the copilot's `claude`
+      # session id and what it has spent in it. Kept beside {#copilot} so a
+      # reloaded page or a restarted server carries on the same conversation
+      # (W17: one session, resumed on each message).
+      #
+      # @param of [String]
+      # @return [String]
+      def copilot_session(of = node) = "#{base}:#{of}:copilot-session"
+
+      # Pub/sub channel: one chat's messages, joins, leaves and idle notices
+      # (plan 006). Redis delivers a `PUBLISH` to every database's
+      # subscribers, so the database is part of every chat channel's name: a
+      # chat between nodes on database 13 never reaches a page on database 0.
+      #
+      # @param id [String] the chat's UUID
+      # @param db [Integer] the Redis database the nodes share
+      # @return [String]
+      def chat_room(id, db:) = "#{chat_base(db)}:room:#{id}"
+
+      # Pub/sub pattern matching every {#chat_room} on +db+, which each API
+      # server subscribes to once, so joining a chat needs no new subscription.
+      #
+      # @param db [Integer]
+      # @return [String]
+      def chat_rooms(db:) = "#{chat_base(db).gsub(/[*?\[\]\\]/) { "\\#{it}" }}:room:*"
+
+      # Pub/sub channel: one machine's chat inbox, where invites to it and
+      # their answers arrive. Every API server for that machine listens, so
+      # an invite reaches every page open there (D9).
+      #
+      # @param machine [String] a node id, 24 hex digits of `user@host`
+      # @param db [Integer]
+      # @return [String]
+      def chat_inbox(machine, db:) = "#{chat_base(db)}:machine:#{machine}"
+
+      # String: how an invite was settled (`accepted`, `declined`, `expired`),
+      # `SET NX EX`, so the first answer from any page wins (D9).
+      #
+      # @param invite [String] the invite's UUID
+      # @return [String]
+      def chat_answer(invite) = "#{base}:chat:invite:#{invite}"
+
+      # @param db [Integer]
+      # @return [String]
+      def chat_base(db) = "#{base}:chat:#{db}"
+
       # String: the node name holding a plan, `SET NX EX`.
       #
       # @param ordinal [#to_s] e.g. "004.00"
@@ -80,6 +134,10 @@ module OpenLanes
       BOARD_LENGTH = 100
       REPLIES_LENGTH = 1000
 
+      # Length of {#copilot}, kept approximately: a conversation the page
+      # can scroll back through, not an archive.
+      COPILOT_LENGTH = 500
+
       # Seconds a snapshot outlives its last refresh.
       SNAPSHOT_TTL = 30
 

data/lib/openlanes/live/memory_store.rb

@@ -22,6 +22,7 @@ module OpenLanes
         @groups = Hash.new { |h, k| h[k] = {} }
         @last_ms = 0
         @last_seq = 0
+        @subscribers = []
       end
 
       # @return [String] what {Live.mask} shows for it
@@ -193,6 +194,29 @@ module OpenLanes
       # @return [Array<String>]
       def scan(prefix) = locked { @data.keys.select { |k| k.start_with?(prefix) && !live(k).nil? }.sort }
 
+      # ---- pub/sub ----------------------------------------------------------
+
+      # @return [Integer] how many subscriptions received it
+      def publish(channel, message)
+        receivers = locked { @subscribers.dup }
+        receivers.sum do |subscriber|
+          subscriber.deliver(channel, message.to_s)
+          subscriber.matches(channel)
+        end
+      end
+
+      # @return [OpenLanes::Live::MemorySubscriber]
+      def subscriber(channels: [], patterns: [])
+        MemorySubscriber.new(store: self, channels:, patterns:).tap { |s| locked { @subscribers << s } }
+      end
+
+      # @param subscriber [OpenLanes::Live::MemorySubscriber]
+      # @return [void]
+      def unsubscribe(subscriber) = locked { @subscribers.delete(subscriber) }
+
+      # @return [Integer] always 0: one process, one keyspace
+      def db = 0
+
       # ---- transactions -----------------------------------------------------
 
       # @yieldparam tx [Store::Transaction]

data/lib/openlanes/live/memory_subscriber.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    # {Subscriber}'s methods over {MemoryStore#publish}: a queue in this
+    # process, matched by exact channel or by Redis-style glob.
+    class MemorySubscriber
+      # @param store [OpenLanes::Live::MemoryStore]
+      # @param channels [Array<String>]
+      # @param patterns [Array<String>]
+      def initialize(store:, channels: [], patterns: [])
+        @store = store
+        @channels = channels
+        @patterns = patterns
+        @queue = Thread::Queue.new
+      end
+
+      # @param channel [String]
+      # @return [Integer] how many of its subscriptions match, as Redis counts receivers
+      def matches(channel)
+        @channels.count(channel) + @patterns.count { File.fnmatch?(it, channel) }
+      end
+
+      # @param channel [String]
+      # @param message [String]
+      # @return [void]
+      def deliver(channel, message) = matches(channel).times { @queue << [channel, message] }
+
+      # @param timeout [Float]
+      # @return [Array(String, String), nil]
+      def next_message(timeout) = @queue.pop(timeout: [timeout, 0].max)
+
+      # @return [void]
+      def close
+        @store.unsubscribe(self)
+        @queue.close
+      end
+    end
+  end
+end

data/lib/openlanes/live/session.rb

@@ -101,7 +101,13 @@ module OpenLanes
       end
 
       # @return [String] where, with the password masked, and as whom
-      def describe = "#{Live.mask(@store.url)} as #{@node.label} (#{@node.name})"
+      def describe = described.join(" ")
+
+      # The same, in the two parts a narrow box may break it between: the
+      # node id is long, and wraps mid-word when left to the box.
+      #
+      # @return [Array(String, String)] `"redis://… as kig@host"` and `"(<node id>)"`
+      def described = ["#{Live.mask(@store.url)} as #{@node.label}", "(#{@node.name})"]
     end
   end
 end

data/lib/openlanes/live/stations.rb

@@ -28,11 +28,14 @@ module OpenLanes
       # Key, label and the states folded into it, in spine order. ⭐️ Planned
       # sits with 🟡 Building and 🟢 Ready for Review with 👀 In Review,
       # because on the board each pair is one stop with the same agents.
+      # 🔴 Rejected sits at Building too: luke and rey rework it there, and
+      # placed by the spine alone it showed them at Building UI, a stop whose
+      # agent list leaves luke out.
       GROUPS = [
         [:new, "New", %i[new]],
         [:researched, "Researched", %i[researched retroactive]],
         [:ready_for_planning, "Planning", %i[ready_for_planning]],
-        [:building, "Building", %i[planned building]],
+        [:building, "Building", %i[planned building rejected]],
         [:building_ui, "Building UI", %i[building_ui]],
         [:in_review, "Review", %i[ready_for_review in_review]],
         [:pr, "Pull request", %i[approved deployed]]
@@ -48,10 +51,11 @@ module OpenLanes
         end
       end
 
-      # The stop a plan in +state+ is shown at. A state off the spine (🔴,
-      # 💩, 😱) is shown where the spine takes it next; one with no way
-      # forward (⭕️, 🅱️) where the plan was when it stopped, which only
-      # its history knows.
+      # The stop a plan in +state+ is shown at. A state a {GROUPS} entry
+      # names is shown at that stop, which is how 🔴 Rejected lands at
+      # Building. Any other state off the spine (💩, 😱) is shown where the
+      # spine takes it next; one with no way forward (⭕️, 🅱️) where the
+      # plan was when it stopped, which only its history knows.
       #
       # @param state [Symbol]
       # @param before [Symbol, nil] the state the plan was worked in last

data/lib/openlanes/live/store.rb

@@ -215,6 +215,24 @@ module OpenLanes
         found.uniq.sort
       end
 
+      # ---- pub/sub ----------------------------------------------------------
+
+      # @param channel [String]
+      # @param message [String]
+      # @return [Integer] how many subscriptions received it
+      def publish(channel, message) = call("PUBLISH", channel, message)
+
+      # A connection of its own, subscribed to +channels+ and +patterns+.
+      #
+      # @return [OpenLanes::Live::Subscriber]
+      def subscriber(channels: [], patterns: []) = Subscriber.new(url:, channels:, patterns:)
+
+      # The database in the URL. Pub/sub ignores databases, so whoever names
+      # a channel puts this in it (see {Keys#chat_room}).
+      #
+      # @return [Integer]
+      def db = @client.config.db.to_i
+
       # ---- transactions -----------------------------------------------------
 
       # The writes the block makes, applied atomically.

data/lib/openlanes/live/subscriber.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "redis-client"
+
+module OpenLanes
+  module Live
+    # One Redis pub/sub connection, subscribed once to the channels and
+    # patterns it was made with (plan 006's chat). A subscribed connection
+    # can do nothing else, so it is its own connection, never the {Store}'s.
+    #
+    # Made by {Store#subscriber}; {MemorySubscriber} is the suite's.
+    class Subscriber
+      # Seconds the shortest wait lasts. redis-client reads a timeout of 0 as
+      # "wait for ever", which is the one thing a polling loop must not do.
+      SHORTEST = 0.01
+
+      # @param url [String]
+      # @param channels [Array<String>]
+      # @param patterns [Array<String>]
+      # @param timeout [Float] seconds to connect and to wait for each confirmation
+      # @raise [OpenLanes::Live::Unavailable]
+      def initialize(url:, channels: [], patterns: [], timeout: Store::TIMEOUT)
+        @url = url
+        guarded do
+          @pubsub = RedisClient.config(url:, timeout:).new_client.pubsub
+          @pubsub.call("SUBSCRIBE", *channels) unless channels.empty?
+          @pubsub.call("PSUBSCRIBE", *patterns) unless patterns.empty?
+          confirm(channels.size + patterns.size, timeout)
+        end
+      end
+
+      # The next message, waiting up to +timeout+ seconds for one.
+      #
+      # @param timeout [Float]
+      # @return [Array(String, String), nil] its channel and its payload
+      # @raise [OpenLanes::Live::Unavailable]
+      def next_message(timeout)
+        loop do
+          event = guarded { @pubsub.next_event([timeout, SHORTEST].max) } or return nil
+          case event.first
+          when "message" then return [event[1], event[2]]
+          when "pmessage" then return [event[2], event[3]]
+          end
+        end
+      end
+
+      # @return [void]
+      def close = @pubsub&.close
+
+      private
+
+      # Waits until Redis has confirmed every subscription, so a message
+      # published the moment this returns is one this connection receives.
+      #
+      # @return [void]
+      def confirm(expected, timeout)
+        confirmed = 0
+        while confirmed < expected
+          event = @pubsub.next_event(timeout) or raise Unavailable, "Redis at #{Live.mask(@url)} did not confirm a subscription"
+          confirmed += 1 if %w[subscribe psubscribe].include?(event.first)
+        end
+      end
+
+      # @return [Object] the block's value
+      # @raise [OpenLanes::Live::Unavailable]
+      def guarded
+        yield
+      rescue RedisClient::Error => e
+        raise Unavailable, "Redis at #{Live.mask(@url)} is unavailable: #{e.message.sub(/\s*\(redis:.*\)\z/, "")}"
+      end
+    end
+  end
+end

data/lib/openlanes/live.rb

@@ -57,6 +57,11 @@ module OpenLanes
     # @return [OpenLanes::Live::Session]
     def session(**) = Session.new(**)
 
+    # The conversation with the run's copilot (W17), on +store+ under +keys+.
+    #
+    # @return [OpenLanes::Live::Copilot]
+    def copilot(**) = Copilot.new(**)
+
     # This checkout's keys, for the API server beside its engine.
     #
     # @param root [String]

data/lib/openlanes/presentation/reporter.rb

@@ -67,7 +67,7 @@ module OpenLanes
       #
       # @return [String]
       def row(flag, ordinal, emoji, label, title, tail)
-        format("%s %s  %s %s  %s %s", flag, ordinal, emoji, label, title, tail)
+        format("%s %s  %s  %s  %s %s", flag, ordinal, emoji, label, title, tail)
       end
 
       # Cell at which the pull requests start, so a plan's second and third pull
@@ -162,7 +162,7 @@ module OpenLanes
 
       # @return [String]
       def footer
-        counts = totals.map { |key, n| "#{Plans::STATUS_BY_KEY.fetch(key).emoji} #{n}" }.join("   ")
+        counts = totals.map { |key, n| "#{Plans::STATUS_BY_KEY.fetch(key).emoji}  #{n}" }.join("   ")
         lines = ["  #{tree.subjects.size} #{tree.subjects.size == 1 ? "plan" : "plans"}   #{counts}"]
 
         unless inconsistent.empty?

data/lib/openlanes/support/ui.rb

@@ -280,7 +280,10 @@ module OpenLanes
         log_taps.each { |tap| tap.call(message, fields) }
         path = log_path or return
 
-        line = Engine::ProgressLog.render(message, **fields)
+        # Taps hear every field; the file takes only its own columns, so a
+        # field meant for the terminal (the state a plan moved to) adds
+        # nothing to the file's format.
+        line = Engine::ProgressLog.render(message, **fields.slice(*Engine::ProgressLog::FIELDS))
         (@log_mutex ||= Mutex.new).synchronize do
           FileUtils.mkdir_p(File.dirname(path))
           File.open(path, "a") { |f| f.puts(line) }
@@ -612,6 +615,77 @@ module OpenLanes
       # @return [void]
       def box(kind, message) = console.public_send(kind, message.to_s)
 
+      # Labelled lines for a box, the labels padded to one width:
+      #
+      #   Progress:     /var/folders/…/openlanes-minesweeper.log
+      #   Live board:   redis://host:6379 as kig@host
+      #                 (c016…:734c…)
+      #
+      # A value given as several parts is joined with spaces while it fits
+      # the box, and each part that does not starts a continuation line
+      # under the values, so a long id breaks where it was meant to rather
+      # than wherever the box's own wrap runs out of room.
+      #
+      # @param rows [Array<Array(String, String | Array<String>)>] label and value
+      # @param room [Integer] text columns inside the box
+      # @return [String]
+      def labelled(rows, room: box_room)
+        pad = rows.map { |label, _| display_width("#{label}:") }.max.to_i + 1
+        free = [room - pad, 1].max
+        rows.flat_map { |label, parts|
+          lines = Array(parts).map(&:to_s).each_with_object([]) do |part, acc|
+            if acc.any? && display_width("#{acc.last} #{part}") <= free
+              acc[-1] = "#{acc.last} #{part}"
+            else
+              acc.concat(broken(part, free))
+            end
+          end
+          lines.each_with_index.map { |text, i| (i.zero? ? fit("#{label}:", pad) : " " * pad) + text }
+        }.join("\n")
+      end
+
+      # A value wider than its column, cut into pieces that fit: after a
+      # `/` where it can be, so a path breaks between directories, and
+      # anywhere when one name is wider than the column on its own. Left
+      # to the box, a path wider than the room after its label wrapped
+      # onto the next line whole, under the label rather than beside it,
+      # and was then cut mid-name with no indent.
+      #
+      # @param text [String]
+      # @param free [Integer] columns
+      # @return [Array<String>] the pieces, each at most +free+ wide
+      def broken(text, free)
+        return [text] if display_width(text) <= free
+
+        text.split(%r{(?<=/)}).flat_map { cells(it, free) }.each_with_object([+""]) do |piece, acc|
+          acc.last.empty? || display_width(acc.last + piece) <= free ? acc.last << piece : acc << piece.dup
+        end
+      end
+
+      # A piece cut by terminal cells rather than characters, one grapheme
+      # cluster at a time, so a wide name such as `界界界` is never cut into
+      # a chunk wider than +free+ (nor a combining mark off its letter).
+      #
+      # @param text [String]
+      # @param free [Integer] columns
+      # @return [Array<String>]
+      def cells(text, free)
+        text.each_grapheme_cluster.with_object([+""]) do |grapheme, acc|
+          acc << +"" unless acc.last.empty? || display_width(acc.last + grapheme) <= free
+          acc.last << grapheme
+        end
+      end
+
+      # Text columns inside a box, as dry-cli-ui works them out: the box is
+      # {.width} or the terminal less two, whichever is narrower, and a
+      # border and two columns of padding go on either side.
+      #
+      # @return [Integer]
+      def box_room
+        terminal = tty? ? TTY::Screen.width : Dry::CLI::UI::Terminal::DEFAULT_WIDTH
+        [width, terminal - 2].min - 6
+      end
+
       # A framed panel centered on the screen, for the keyboard help. Unlike
       # {.box} it positions itself absolutely, so it overlays whatever the
       # spinners are drawing rather than scrolling in below them — the next