openlanes 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7658c5f19c6cee3a0fdbf6b199439cbd0bf94a5c4c62380909ee389d3ed3592
-  data.tar.gz: 0c58d76a809b55ec3cbf6be45083bde5971d2fa76f0b3cc891a8f60467a8808a
+  metadata.gz: b480713b45345b2c7477e65702505d70f4da9cbcfe1a099f8125d9333d827ee8
+  data.tar.gz: 49c1328895393365f5b4a197e9c0ea7819e79a68757769aa3ce8660851ef78bc
 SHA512:
-  metadata.gz: ad1b3ea0ab150357c0b20e8e19db6c5a930d65d7405854dea60e4b59272c224bacab5ea238be2efe09cd19ddf4ff0b52619e15daa5387bf87876bb77f2ada76f
-  data.tar.gz: f733b50907984ac3fa0228e8815cd8cf04d610625451dbf6022ca26c1eff3cfc6ceb6dc659aca181b2af2a7d7b2552a3b0fd8ffd919134681654a8c505af1c64
+  metadata.gz: aba10c8c3eb5a3c955014e9b2a262204f9917d3c9eace688a69ef8c10be11a68546866cbb3ba0b2c4f49ff88f682728bafb771bd72db5730b372f02b1eb617d8
+  data.tar.gz: 94cdc0e5cae5136c799cbd41f473cd268f0de018057d8f49e681ef334893c91941d3ad9aa7c948e51e43ebc4784b7e060089ce099c9d448e004cd94dcc317293

data/agents/c3po-operator.md

@@ -0,0 +1,58 @@
+---
+name: c3po-operator
+description: The control room's copilot. Talks to the person about the run, drafts answers to blocked agents, and proposes stops for the person to confirm; edits nothing and works no plan.
+handles: []
+model: haiku
+effort: low
+timeout: 180
+allowed_tools:
+  - Read
+  - Grep
+  - Glob
+  - "Bash(openlanes list-plans:*)"
+  - "Bash(openlanes status:*)"
+  - "Bash(openlanes state show:*)"
+  - "Bash(openlanes mail read:*)"
+  - "Bash(openlanes agents list:*)"
+  - "Bash(openlanes agents describe:*)"
+  - "Bash(openlanes describe:*)"
+  - "Bash(openlanes states:*)"
+---
+
+You are c3po-operator, the copilot in the openlanes control room. A person watching a run asks you about it, and you answer in a small chat panel. You work no plan: `openlanes run` never hands you one.
+
+## What you know
+
+Every message arrives with the board as it stands: each plan on this machine, its state, the agents working it (cars), what they spent, the questions waiting on a person, and the recent log. Trust it over anything you remember from earlier in the conversation, because the run moves between two messages.
+
+Read further when the board does not answer the question:
+
+- the plan folders it names: `spec.md`, `plan.md`, `blocked.md`, and `state.json` with the signatures and the mailbox;
+- the agents' transcripts in the trace directory it names, one NDJSON file per invocation, named by time, plan and agent. They are large: `Grep` them for what you need rather than reading them whole;
+- the read-only `openlanes` commands: `list-plans`, `state show --plan NNN`, `mail read --plan NNN --for <agent>`, `agents list`, `describe <agent>`, `states`.
+
+You have nothing else. You cannot edit a file, run any other command, or reach the network, and you never try to: changing code and plan documents is the other agents' job.
+
+## How you answer
+
+Short, plain and specific. The panel is narrow; three short paragraphs is a long answer. Name plans by number and agents by name. Say what the evidence is ("luke-backend's last tool call was 14 minutes ago, an `rspec` run"). When you do not know, say so and say what would tell you.
+
+## Cards
+
+You never act. When the person should act, you write a card, and the page draws a button the person presses or does not. A card is a fenced block whose info string is exactly `c3po`, holding one JSON object, and nothing else:
+
+```c3po
+{"card": "confirm", "text": "luke-backend has made no progress in 20 minutes.", "command": {"kind": "stop", "plan": "002", "agent": "luke-backend"}, "confirm": "Stop luke-backend", "done": "luke-backend was asked to stop."}
+```
+
+```c3po
+{"card": "draft", "question": "002/B1", "text": "A draft from what spec.md already says:", "draft": "Ninety days from the cart's last change."}
+```
+
+- `confirm` proposes a command that cannot be undone. `command.kind` is one of `stop` (one agent: needs `plan` and `agent`), `discard` (a whole plan's work in progress: needs `plan`) or `stop_all` (the whole run). `confirm` is the button's label, at most 60 characters; `done` is what the card says once the engine has accepted it.
+- `draft` drafts an answer to a question waiting on the board. `question` is its id exactly as the board writes it (`002/B1`). The page puts the draft in the answer box; the person edits and sends it.
+- `text` is the line above the card. Prose outside the cards is shown as it is.
+
+A drafted answer to a waiting question is always a `draft` card, never prose: the card is what puts it in the answer box. A proposal to stop or discard is always a `confirm` card. Offer a card only for a plan, agent or question that is on the board now, at most three in one answer, and only when the person asked for it or it plainly helps. A card the control room cannot take is shown to the person as plain text, and nothing is sent.
+
+Nothing else is a card. To message an agent, hold it, extend its time, answer a question or change its model, tell the person where to do it on the page (the car's drawer, the question's answer box) and draft the words if that helps.

data/lib/openlanes/adapters/base.rb

@@ -58,6 +58,13 @@ module OpenLanes
       #   carried on in the same session
       def compacts? = !compact_prompt.nil?
 
+      # Whether {#argv} honours {Invocation#resume}. The copilot (W17) keeps
+      # one conversation across messages only on a CLI that says yes; on any
+      # other each message starts afresh, and says so.
+      #
+      # @return [Boolean]
+      def resumes? = false
+
       # Whether the CLI itself refuses the denied tools, rather than only being
       # asked not to use them. The prompt says which, because telling an agent
       # a guard exists when it does not is how it stops being careful.

data/lib/openlanes/adapters/claude.rb

@@ -64,10 +64,14 @@ module OpenLanes
         # it the stream reports a settled input count and a placeholder output
         # count — 2 for a four-thousand-token answer — and a spinner counting
         # what came back would read zero all run.
-        argv = ["claude", "-p", invocation.prompt, "--add-dir", invocation.root,
-                "--output-format", "stream-json", "--verbose", "--include-partial-messages", "--brief"]
+        argv = ["claude", "-p", invocation.prompt, "--add-dir", invocation.root]
+        invocation.dirs.each { argv += ["--add-dir", it] }
+        argv += ["--output-format", "stream-json", "--verbose", "--include-partial-messages"]
+        argv << "--brief" if invocation.brief
         argv += ["--resume", invocation.resume] if invocation.resume
         argv += LEAN.reject { invocation.slash_commands && it == SLASH_COMMANDS_OFF } if invocation.lean
+        argv += restricted(invocation.tools) if invocation.tools
+        argv += ["--append-system-prompt", invocation.system] if invocation.system
         argv += ["--disallowedTools", invocation.denied_tools.join(",")] unless invocation.denied_tools.empty?
         argv += ["--allowedTools", invocation.allowed_tools.join(",")] unless invocation.allowed_tools.empty?
         model = model(invocation.model)
@@ -79,6 +83,18 @@ module OpenLanes
       # @return [OpenLanes::Execution::Transcript]
       def transcript(trace: nil, &) = Execution::Transcript.new(trace:, &)
 
+      # A fixed tool set. `--tools` takes every other built-in tool away, and
+      # `--restricted` stops the project's and the operator's settings files
+      # from granting more: an allow rule in `.claude/settings.json` would
+      # otherwise widen what `--allowedTools` permits, and `--disallowedTools`
+      # only removes what somebody thought to name. `dontAsk` refuses whatever
+      # the allow list does not cover, rather than waiting on a prompt that
+      # nobody under `-p` can answer.
+      #
+      # @param tools [Array<String>]
+      # @return [Array<String>]
+      def restricted(tools) = ["--restricted", "--tools", tools.join(","), "--permission-mode", "dontAsk"]
+
       # @param model [String, nil] an alias (`sonnet`) or a full id
       #   (`claude-fable-5-1`)
       # @return [String, nil]
@@ -92,6 +108,9 @@ module OpenLanes
       # @return [Boolean]
       def enforces_tool_denial? = true
 
+      # @return [Boolean] `--resume <session id>` carries a conversation on
+      def resumes? = true
+
       # `claude -p --resume <id> "/compact"` compacts the session and prints a
       # `compact_boundary` event; the agent cannot run it on itself, because
       # `/compact` is the caller's command, not a tool.

data/lib/openlanes/adapters.rb

@@ -44,6 +44,18 @@ module OpenLanes
     # @!attribute [r] slash_commands
     #   @return [Boolean] keep the CLI's slash commands even when lean, which
     #     only the `/compact` sent into a resumed session needs
+    # @!attribute [r] dirs
+    #   @return [Array<String>] directories beyond {#root} the agent may read,
+    #     such as the trace directory the copilot reads transcripts from
+    # @!attribute [r] brief
+    #   @return [Boolean] whether the agent reports through the CLI's
+    #     one-line status tool, which only a car on the board has a use for
+    # @!attribute [r] tools
+    #   @return [Array<String>, nil] the only built-in tools the agent has, with
+    #     no settings file able to add one; nil leaves the CLI's own set
+    # @!attribute [r] system
+    #   @return [String, nil] standing instructions, sent as system prompt on
+    #     every invocation so a compacted conversation does not lose them
     Invocation = Data.define(:prompt,
       :root,
       :model,
@@ -54,9 +66,14 @@ module OpenLanes
       :network,
       :lean,
       :resume,
-      :slash_commands) do
+      :slash_commands,
+      :dirs,
+      :brief,
+      :tools,
+      :system) do
       def initialize(allowed_tools: [], denied_tools: [], denied_commands: [], network: false, lean: true,
-        model: nil, effort: nil, resume: nil, slash_commands: false, **rest)
+        model: nil, effort: nil, resume: nil, slash_commands: false, dirs: [], brief: true, tools: nil, system: nil,
+        **rest)
         super
       end
     end

data/lib/openlanes/cli/run/run.rb

@@ -120,9 +120,8 @@ module OpenLanes
         # whether a round prints anything at all) is read the whole time the
         # loop runs, not just when `report` prints its closing summary.
         quiet?(options)
-        UI.log_path = options[:log] ||
-                      File.join(Dir.tmpdir, "openlanes-#{File.basename(root)}.log")
-        info("Progress: #{UI.log_path}") unless quiet?(options)
+        UI.log_path = options[:log] || Engine::ProgressLog.default_path(root)
+        startup("Progress", UI.log_path)
         credentials_warning if !dry_run?(options) && !quiet?(options)
         spec_warning(tree, plans) unless quiet?(options)
 
@@ -165,11 +164,18 @@ module OpenLanes
           claims:    live&.claims,
           **staying(options, web)
         )
+        startup_box(options)
 
+        # The terminal hears the run as it happens, one appended line per
+        # event, whether or not a control room is up: the page is the board,
+        # and the terminal is its log. Nothing here redraws, so nothing can
+        # draw over a box or over another line.
+        narrator = UI.tap_log(Engine::Narrator.new) unless quiet?(options)
         started  = UI.monotonic
         attempts = begin
           Execution.on_interrupt(signals:) { runner.call { |dispatcher| live&.attach(dispatcher) } }
         ensure
+          UI.untap_log(narrator) if narrator
           live&.close
           web&.stop
         end
@@ -190,7 +196,7 @@ module OpenLanes
       def staying(options, web)
         return {} if web.nil? || options[:until_settled]
 
-        info("The engine stays up with its control room: Stop All Local or Ctrl-C ends it.") unless quiet?(options)
+        @stays = "The engine stays up with its control room: Stop All Local or Ctrl-C ends it."
         { stay: true, rescan: Engine::Dispatcher::RESCAN }
       end
 
@@ -268,7 +274,7 @@ module OpenLanes
         config = Config.current
         store = Live.connect(Live.redis_url(option: options[:redis_url], config:))
         Live.session(store:, root:, tree:, agents:, project: config.project).tap do |session|
-          info("Live board: #{session.describe}") unless quiet?(options)
+          startup("Live board", session.described)
         end
       rescue Live::Unavailable => e
         without_live(e.message, options)
@@ -297,11 +303,31 @@ module OpenLanes
           return without_web(web, live, options)
         end
 
-        info("Control room: #{web.url}") unless quiet?(options)
+        startup("Control room", web.url)
         OpenLanes::Web.open(browser_url(web, tree)) unless options[:open] == false
         web
       end
 
+      # One line of the startup box, kept until {#startup_box} draws it.
+      #
+      # @param label [String]
+      # @param value [String, Array<String>] parts a narrow box may break between
+      # @return [void]
+      def startup(label, value) = (@startup ||= []) << [label, value]
+
+      # Where the run writes, what it publishes to, and where its page is:
+      # one Info box, drawn once all three are known. Each used to be a box
+      # of its own, three frames for three lines. A line that does not apply
+      # (no Redis, no control room) is left out, not drawn empty.
+      #
+      # @param options [Hash]
+      # @return [void]
+      def startup_box(options)
+        return if quiet?(options) || @startup.to_a.empty?
+
+        info([UI.labelled(@startup), @stays].compact.join("\n\n"))
+      end
+
       # The attempts list, padded into columns.
       #
       # Tabs used to separate these, which put every column on the next
@@ -461,6 +487,20 @@ module OpenLanes
       # @return [Array<OpenLanes::Engine::Runner::Attempt>]
       def failures(attempts) = attempts.reject(&:ok)
 
+      # The attempts and the bill, one blank line before each part that has
+      # anything in it. `puts []` prints an empty line, so a run with no
+      # attempts used to open its report with two blank lines and a third
+      # before the tally.
+      #
+      # @param attempts [Array<OpenLanes::Engine::Runner::Attempt>]
+      # @param tally [String, nil] nil prints none
+      # @return [void]
+      def puts_report(attempts, tally)
+        lines = attempt_lines(attempts)
+        puts("", *lines) unless lines.empty?
+        puts("", tally) if tally
+      end
+
       # The one thing this harness does that leaves the machine — pushing a
       # branch and opening its pull request — so it takes one more thing to
       # turn on than everything else here: not being a dry run is not enough,
@@ -497,18 +537,10 @@ module OpenLanes
       # @param seconds [Float] wall clock for the whole loop
       # @return [void]
       def report(runner, attempts, options, seconds: 0.0)
-        # A leading blank line, because the spinners this replaces write to
-        # STDERR and the last of them may have left the cursor mid-line:
-        # without it the first attempt starts wherever that line stopped,
-        # indented by however much it had drawn.
-        puts ""
-        puts attempt_lines(attempts)
-
         # What the run cost, on STDOUT with the attempts it belongs to, so a run
         # redirected to a file keeps its bill. A dry run spent nothing and gets
         # none of this.
-        tally = Engine.tally(attempts:, seconds:)
-        puts("", tally.render) unless dry_run?(options)
+        puts_report(attempts, (Engine.tally(attempts:, seconds:).render unless dry_run?(options)))
 
         return if quiet?(options)
 

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

@@ -36,24 +36,13 @@ module OpenLanes
       # Exit status when Redis or the control room is not there to serve.
       UNAVAILABLE = 69
 
-      # The progress log, echoed to the terminal: the terminal is where a
-      # person watches `start` from when the page is closed, and it takes
-      # no input.
-      #
       # @param options [Hash]
       # @return [void]
       def call(**options)
         @rescan = Integer(options.fetch(:rescan, Engine::Dispatcher::RESCAN), exception: false)
         refuse("--rescan takes a whole number of seconds, at least 1.", 64) unless @rescan&.positive?
 
-        tap = UI.tap_log(lambda { |message, fields|
-          next if UI.quiet
-
-          Kernel.warn(Engine::ProgressLog.render(message, **fields.slice(:plan, :status, :agent, :seconds, :round)))
-        })
         super
-      ensure
-        UI.untap_log(tap) if tap
       end
 
       private
@@ -93,9 +82,7 @@ module OpenLanes
       #
       # @return [void]
       def finish(runner, attempts, options, seconds:)
-        puts ""
-        puts attempt_lines(attempts)
-        puts("", Engine.tally(attempts:, seconds:).render)
+        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."]

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

@@ -41,11 +41,13 @@ module OpenLanes
         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]
-        context = OpenLanes::Web.context(stores:, keys:, plans_dir: tree.dir, url: stores.current.url, node:, 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)
       ensure
         demo&.stop
+        copilot.stop if copilot.respond_to?(:stop)
       end
 
       private
@@ -76,6 +78,14 @@ module OpenLanes
         OpenLanes::Web::Stores.shared(Live.memory_store)
       end
 
+      # c3po-operator, answering in this server (W17). It runs beside the
+      # page rather than in the engine so it answers with no run going too.
+      #
+      # @return [OpenLanes::Live::Copilot::Operator]
+      def copilot_for(root:, tree:, stores:, keys:)
+        Live::Copilot::Operator.new(root:, plans_dir: tree.dir, stores:, keys:)
+      end
+
       # Listen until INT or TERM.
       #
       # @return [void]

data/lib/openlanes/engine/dispatcher.rb

@@ -703,14 +703,21 @@ module OpenLanes
       def next_dispatchable
         reconcile
         @runner.in_scope.each do |subject|
+          working = @running.select { plan_of(it) == subject.feature.ordinal.to_s }.map { it.task.agent }
           # After {#reconcile} this is the folder's name. On a dry run, which
-          # renames nothing, it is what the name would have become.
-          state = Lifecycle::Lanes.target(subject) || Lifecycle::Resync::Dirs.target(subject)
+          # renames nothing, it is what the name would have become. A plan an
+          # agent is in right now is never reconciled, so its contents are
+          # not asked: see {#partners_only}.
+          state = if working.empty?
+                    Lifecycle::Lanes.target(subject) || Lifecycle::Resync::Dirs.target(subject)
+                  else
+                    subject.status
+                  end
           next if Plans::StateMachine::SETTLED.include?(state.key)
           next if @finished_plans.include?(subject.feature.ordinal.to_s)
           next if @runner.foreign?(subject) || @discarding.key?(subject.feature.ordinal.to_s)
 
-          candidates = Agents::Routing.filter(@runner.agents.for_status(state), subject)
+          candidates = partners_only(Agents::Routing.filter(@runner.agents.for_status(state), subject), working, state)
           preferred = @preferred[subject.feature.ordinal.to_s]
           candidates = candidates.sort_by { |a| a.name == preferred ? 0 : 1 } if preferred
           agent = candidates.find { |a| eligible?(a, subject) }
@@ -719,6 +726,30 @@ module OpenLanes
         nil
       end
 
+      # One agent at a time on a plan, except a pair working the same state.
+      #
+      # A plan with an agent in it is judged by its folder's name, never by
+      # what its contents would justify. Asking the contents is how the
+      # minesweeper trial ran its whole chain inside ⚪️ New: leah wrote her
+      # `## Research` chapter, the next tick saw a Researched plan and started
+      # yoda beside her, and leah's own Completed then found a partner running
+      # and held the folder where it was. Every later agent repeated it, so
+      # the folder never moved and luke and rey were building on a plan whose
+      # name still said nobody had researched it.
+      #
+      # @param candidates [Array<OpenLanes::Agents::Agent>]
+      # @param working [Array<OpenLanes::Agents::Agent>] already on the plan
+      # @param state [OpenLanes::Plans::Status] the folder's state
+      # @return [Array<OpenLanes::Agents::Agent>]
+      def partners_only(candidates, working, state)
+        return candidates if working.empty?
+
+        team = @runner.agents.team_for(state).map(&:name)
+        return [] unless working.all? { team.include?(it.name) }
+
+        candidates.select { team.include?(it.name) }
+      end
+
       # A folder's name can lag its contents: a run killed before its rename,
       # a plan.md written by hand, a resync nobody ran. So the names are
       # reconciled before every dispatch, the way `resync dirs` would, and a
@@ -889,7 +920,11 @@ module OpenLanes
             remaining: nil,
             phase: nil,
             bold: !attempt.ok) }
-          UI.log(attempt.ok ? "finished: #{attempt.note}" : "failed: #{attempt.note}", **job.task.log_fields)
+          # `to:` is for the terminal's line; the log file keeps its columns.
+          moved = Plans::STATUS_BY_KEY[attempt.to]&.to_s if attempt.advanced?
+          UI.log(attempt.ok ? "finished: #{attempt.note}" : "failed: #{attempt.note}",
+            **job.task.log_fields,
+            **{ to: moved }.compact)
         end
       end
 
@@ -926,11 +961,15 @@ module OpenLanes
                   end
         attempt = attempt.with(note: "#{attempt.note}; #{problems.join(", ")}") unless problems.empty?
         attempt = attempt.with(to: fresh(task)&.status&.key || attempt.to)
+        # One outcome, written to both records. The engine's state file once
+        # defaulted a failed round to Completed while state.json said
+        # Interrupted, so the page and the plan disagreed about the same round.
+        outcome = attempt.status || (attempt.ok ? "Completed" : "Interrupted")
         if (settled = fresh(task))
           stage!(settled,
             agent,
             task.round,
-            status:      attempt.status || (attempt.ok ? "Completed" : "Interrupted"),
+            status:      outcome,
             to:          attempt.to.to_s,
             finished_at: Time.now.iso8601,
             up:          attempt.up.to_i,
@@ -941,7 +980,7 @@ module OpenLanes
         @state&.record(ordinal,
           agent:    agent.name,
           round:    task.round,
-          status:   attempt.status || "Completed",
+          status:   outcome,
           exit:     attempt.ok ? "ok" : attempt.note,
           ended_at: Time.now.iso8601,
           up:       attempt.up,
@@ -1063,7 +1102,7 @@ module OpenLanes
 
           attempt = published.attempt
           subject = published.subject
-          return attempt.with(ok: false, note: "ledger says Completed but #{Plans::STATUS_BY_KEY.fetch(target)} is not justified: #{Plans::STATUS_BY_KEY.fetch(target).violation(subject)}") unless subject.machine.may?(target)
+          return unjustified(job, attempt, subject, target) unless subject.machine.may?(target)
 
           subject.machine.promote!(target)
           attempt = attempt.with(to: target)
@@ -1074,6 +1113,22 @@ module OpenLanes
         attempt
       end
 
+      # The agent signed Completed, but what it left does not justify the
+      # state it advances to. The folder stays, its `next:` is not honoured,
+      # and the round is recorded as Interrupted, which is what the page
+      # lists under Needs you once the agent's rounds run out. Taking the
+      # signature at its word instead parked the plan: nobody else handles
+      # the state it is still in, and its own agent counted itself done.
+      #
+      # @return [OpenLanes::Engine::Runner::Attempt]
+      def unjustified(job, attempt, subject, target)
+        status = Plans::STATUS_BY_KEY.fetch(target)
+        remember(plan_of(job), job.task.agent.name, job.state, "Interrupted", job.task.round)
+        attempt.with(ok: false,
+          status: "Interrupted",
+          note: "ledger says Completed but #{status} is not justified: #{status.violation(subject)}")
+      end
+
       # A build finished in a run that opens no pull request: 🟢 needs one,
       # so the folder cannot move, and failing the attempt would only start
       # the builder again on work that is done. Only the missing pull request

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: -> { Time.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