openlanes 3.0.0 → 3.1.0

data/lib/openlanes/web/app.rb

@@ -4,6 +4,8 @@ require "ipaddr"
 require "json"
 require "rack/utils"
 require "sinatra/base"
+require "newrelic_rpm"
+require 'newrelic/infinite_tracing'
 
 module OpenLanes
   module Web
@@ -11,13 +13,9 @@ module OpenLanes
     # {.serving}, carries that server's {Context} as a setting, so two apps in
     # one process (the suite) never share a token or a store.
     class App < Sinatra::Base
-      # The plan files the drawer and the preview may read. A name is looked
-      # up in this list and never joined onto a path as typed, which is what
-      # makes `../` meaningless here rather than merely refused.
-      PLAN_FILES = %w[spec.md plan.md blocked.md research.md design.md].freeze
-
-      # Host headers the server answers. Loopback only, so a page on another
-      # site cannot reach it through DNS rebinding.
+      # Host headers the server always answers: loopback, so a page on another
+      # site cannot reach it through DNS rebinding. A server listening beyond
+      # this machine adds its own addresses and name ({Listen#permitted_hosts}).
       LOCAL_HOSTS = ["localhost", IPAddr.new("127.0.0.0/8"), IPAddr.new("::1")].freeze
 
       # What `/` says when the page was never built.
@@ -50,7 +48,9 @@ module OpenLanes
         # @return [Class] a subclass serving that context
         def serving(context)
           Class.new(self) do
+            use AdminAuth, credentials: context.credentials if context.credentials
             set :context, context
+            set :host_authorization, { permitted_hosts: LOCAL_HOSTS + context.listen.permitted_hosts }
             set :public_folder, context.dist
           end
         end
@@ -63,6 +63,58 @@ module OpenLanes
         # @return [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
         def store = context.store
 
+        # @return [OpenLanes::Live::Copilot]
+        def copilot = Live.copilot(store:, keys: context.keys, responder: context.copilot)
+
+        # Answer +turn+ apart from this request, on a store of its own,
+        # since a Redis connection is never shared between threads.
+        #
+        # @param turn [OpenLanes::Live::Copilot::Turn]
+        # @return [void]
+        def answer_later(turn)
+          context.background.call do
+            Live.copilot(store: context.stores.current, keys: context.keys, responder: context.copilot).answer(turn)
+          ensure
+            context.stores.release
+          end
+        end
+
+        # @return [OpenLanes::Web::PlanFiles]
+        def plan_files = PlanFiles.new(plans_dir: context.plans_dir)
+
+        # The rule the page draws cars by: this machine's board lists the
+        # plan with at least one car. No snapshot means no engine, so no car.
+        #
+        # @param ordinal [String] e.g. "017.00"
+        # @return [Boolean]
+        def live_car?(ordinal)
+          plans = Live.board(store:, keys: context.keys).dig(:me, "plans") || []
+          plans.any? { it["ordinal"].to_s == ordinal && Array(it["cars"]).any? }
+        end
+
+        # @return [OpenLanes::Live::Chat]
+        def chat = context.chat || halt(404, json(error: "this server has no chat"))
+
+        # The request's JSON object, or a 422.
+        #
+        # @return [Hash]
+        def body_json
+          data = JSON.parse(request.body.read)
+          data.is_a?(Hash) ? data : halt(422, json(error: "the body is a JSON object"))
+        rescue JSON::ParserError => e
+          halt 422, json(error: "not JSON: #{e.message.lines.first.to_s.strip}")
+        end
+
+        # Another machine on the board, as `user@host`, so an invite names
+        # who it went to and is only sent to a machine that is there.
+        #
+        # @param id [String] a node id
+        # @return [String]
+        def machine_label(id)
+          node = Live.board(store:, keys: context.keys)[:others].map { it["node"] }.find { it["id"] == id }
+          node ? "#{node["user"]}@#{node["host"]}" : halt(422, json(error: "no machine #{id} is on this Redis now"))
+        end
+
         # @param data [Object]
         # @return [String]
         def json(data)
@@ -98,6 +150,26 @@ module OpenLanes
         cache_control :no_store
       end
 
+      error PlanFiles::NotFound do
+        status 404
+        json(error: env["sinatra.error"].message)
+      end
+
+      error PlanFiles::ReadOnly do
+        status 403
+        json(error: env["sinatra.error"].message)
+      end
+
+      error PlanFiles::Stale do
+        status 412
+        json(error: env["sinatra.error"].message)
+      end
+
+      error PlanFiles::FrontmatterChanged do
+        status 422
+        json(error: env["sinatra.error"].message)
+      end
+
       error Live::Unavailable do
         status 503
         json(error: env["sinatra.error"].message)
@@ -120,7 +192,7 @@ module OpenLanes
       get "/api/events" do
         content_type "text/event-stream"
         headers "Cache-Control" => "no-cache, no-transform", "X-Accel-Buffering" => "no"
-        events = Events.new(context:, store:, last_id: request.env["HTTP_LAST_EVENT_ID"])
+        events = Events.new(context:, store:, last_id: request.env["HTTP_LAST_EVENT_ID"], page: params[:page])
         stream { |out| events.run(out) }
       end
 
@@ -136,6 +208,108 @@ module OpenLanes
         json(Live::Reply.new(id: id_in(body), status: "refused", reason: e.message).wire)
       end
 
+      # The Preview tab's toolbar (plan 012): Restart backend, a named
+      # restart, or Stop, for the `openlanes app start` running that plan's
+      # app. Queued on the app runner's stream, not the engine's: the engine
+      # never runs an app, so it would never read them.
+      post "/api/apps/commands" do
+        halt 403, json(error: "X-CSRF-Token does not match; fetch /api/session again") unless csrf?
+
+        data = body_json
+        plan = Plans::Ordinal.parse(data["plan"].to_s)&.to_s or halt 422, json(error: "plan must be a plan number like 012.00")
+        action = data["action"].to_s
+        halt 422, json(error: "action must be one of #{Apps::Runner::ACTIONS.join(", ")}") unless Apps::Runner::ACTIONS.include?(action)
+        target = data["target"]
+        unless target.nil? || target.to_s.match?(Apps::Definition::NAME)
+          halt 422, json(error: "target must be backend or a process name")
+        end
+
+        command = { plan:, action:, target: }
+        Live::EventBus.for(store).append(context.keys.app_commands, { json: JSON.generate(command) }, maxlen: Apps::Runner::COMMANDS_LENGTH)
+        status 202
+        json(command)
+      end
+
+      # The interview a new idea gets before its spec is written (M6). No
+      # interviewer, or one that failed, is not an error: the page gets no
+      # questions and a reason, and creates the plan as it always has.
+      post "/api/interview" do
+        halt 403, json(error: "X-CSRF-Token does not match; fetch /api/session again") unless csrf?
+
+        idea = body_json["idea"].to_s.strip
+        halt 422, json(error: "interview needs an idea") if idea.empty?
+
+        interviewer = Live.interviewer
+        next json(questions: [], reason: "no interviewer: OPENROUTER_API_KEY is not set") unless interviewer
+
+        begin
+          json(questions: interviewer.call(idea:).map(&:wire))
+        rescue StandardError => e
+          json(questions: [], reason: "the interviewer failed: #{e.message.lines.first.to_s.strip}")
+        end
+      end
+
+      get "/api/copilot" do
+        json(copilot.history)
+      end
+
+      # The person's message to the copilot (W17). It is stored and accepted
+      # at once; the answer is written afterwards, apart from this request,
+      # and comes on the event stream as `event: copilot`, like a command's
+      # replies do. The answer is c3po-operator's ({Context#copilot}), except
+      # for a slash command (plan 020.00), which the engine answers.
+      post "/api/copilot" do
+        halt 403, json(error: "X-CSRF-Token does not match; fetch /api/session again") unless csrf?
+
+        turn = copilot.say(request.body.read)
+        answer_later(turn) unless turn.slash?
+        status 202
+        json(turn.wire)
+      rescue Live::Copilot::Invalid => e
+        status 422
+        json(error: e.message)
+      rescue Live::Copilot::Unanswered => e
+        status 503
+        json(error: e.message)
+      end
+
+      # The chat between machines (plan 006): this page's chat, the invites
+      # open to this machine, and the ones this page waits on.
+      get "/api/chat" do
+        json(chat.state(page: params[:page]))
+      rescue Live::Chat::Invalid => e
+        status 422
+        json(error: e.message)
+      end
+
+      # What a page does in a chat. Everyone hears of it as `event: chat`
+      # on their own stream, this page included.
+      post "/api/chat/:action" do
+        halt 403, json(error: "X-CSRF-Token does not match; fetch /api/session again") unless csrf?
+
+        data = body_json
+        page = data["page"]
+        machine = data["machine"].to_s
+        answer = case params[:action]
+                 when "start" then chat.start_chat(page:, name: data["name"], machine:, label: machine_label(machine))
+                 when "invite" then chat.invite(page:, machine:, label: machine_label(machine))
+                 when "accept" then chat.accept(page:, invite: data["invite"].to_s, name: data["name"])
+                 when "decline" then chat.decline(page:, invite: data["invite"].to_s).then { {} }
+                 when "leave" then chat.leave(page:).then { {} }
+                 when "say" then chat.say(page:, id: data["id"], text: data["text"])
+                 when "presence" then chat.presence(page:, idle: data["idle"]).then { {} }
+                 else halt 404, json(error: "no such chat action: #{params[:action]}")
+                 end
+        status 202
+        json(answer)
+      rescue Live::Chat::Invalid => e
+        status 422
+        json(error: e.message)
+      rescue Live::Chat::Settled => e
+        status 409
+        json(error: e.message)
+      end
+
       # Demo only: the board back to the fixture, for a test that wants a
       # known start. A real engine's run has no such thing.
       post "/api/demo/reset" do
@@ -146,15 +320,39 @@ module OpenLanes
         status 204
       end
 
-      get "/api/plans/:ordinal/files/:name" do
-        name = PLAN_FILES.find { it == params[:name] } or halt 404, json(error: "not a plan file: #{params[:name]}")
-        ordinal = Plans::Ordinal.parse(params[:ordinal]) or halt 404, json(error: "not a plan number")
-        subject = Plans.tree(context.plans_dir).find(ordinal) or halt 404, json(error: "there is no plan #{ordinal}")
-        path = File.join(subject.feature.path, name)
-        halt 404, json(error: "#{ordinal} has no #{name}") unless File.file?(path)
+      # The plan files (plan 017). The page may read six names and write
+      # two; {PlanFiles} holds both lists and every guard but the car, so a
+      # name is never joined onto a path as typed.
+      get "/api/plans/:ordinal/files" do
+        json(files: plan_files.list(params[:ordinal]))
+      end
 
+      get "/api/plans/:ordinal/files/:name" do
+        file = plan_files.read(params[:ordinal], params[:name])
+        headers "ETag" => file.etag
         content_type "text/markdown", charset: "utf-8"
-        File.read(path)
+        file.body
+      end
+
+      # A whole file, saved from the popup. The car is checked here rather
+      # than in {PlanFiles}, since the board is this server's to read: an
+      # agent working the plan would overwrite the save, or be overwritten.
+      put "/api/plans/:ordinal/files/:name" do
+        halt 403, json(error: "X-CSRF-Token does not match; fetch /api/session again") unless csrf?
+
+        ordinal, name = params.values_at(:ordinal, :name)
+        plan_files.read(ordinal, name)
+        halt 403, json(error: "#{name} is read only") unless PlanFiles::EDITABLE.include?(name)
+
+        if_match = request.env["HTTP_IF_MATCH"].to_s.strip
+        halt 428, json(error: "If-Match is required; send the ETag from GET") if if_match.empty?
+
+        number = Plans::Ordinal.parse(ordinal).to_s
+        halt 409, json(error: "#{number} has an agent working on it; wait until it stops") if live_car?(number)
+
+        tag = plan_files.write(ordinal, name, body: request.body.read, if_match:)
+        headers "ETag" => tag
+        json(etag: tag)
       end
 
       get "/api/*" do

data/lib/openlanes/web/context.rb

@@ -5,8 +5,8 @@ require "concurrent/atomic/atomic_boolean"
 module OpenLanes
   module Web
     # Everything one API server knows, fixed when it starts: where Redis is,
-    # whose keys it reads, the token every write must carry, and how often
-    # the event stream looks for news.
+    # whose keys it reads, the token every write must carry, and how long
+    # an event stream sleeps when nobody nudges it.
     #
     # @!attribute [r] stores
     #   @return [OpenLanes::Web::Stores] a store per request thread
@@ -23,19 +23,34 @@ module OpenLanes
     # @!attribute [r] node
     #   @return [OpenLanes::Live::Node, nil] this machine, for `/api/session`
     #     while no engine has published a snapshot
-    # @!attribute [r] tick
-    #   @return [Float] seconds between the event stream's looks (contract: 250 ms)
     # @!attribute [r] ping_every
-    #   @return [Float] seconds between `: ping` comments
+    #   @return [Float] seconds between `: ping` comments, and the longest an
+    #     event stream waits for a nudge before it looks anyway
     # @!attribute [r] lifetime
     #   @return [Float, nil] seconds an event stream lives; nil for as long as
     #     the browser holds it. The suite sets one so a stream ends.
     # @!attribute [r] demo
     #   @return [OpenLanes::Web::Demo, nil] the demo engine, under `--demo`,
     #     which `POST /api/demo/reset` puts back to the start
+    # @!attribute [r] copilot
+    #   @return [#call, nil] who answers the copilot's messages (W17):
+    #     {Live::Copilot::Operator} beside a real run, {Demo::COPILOT} under
+    #     `--demo`, nil where nothing does, and `POST /api/copilot` says so
+    # @!attribute [r] background
+    #   @return [#call] runs the block it is given apart from the request, a
+    #     thread by default; the suite passes one that runs it when told
+    # @!attribute [r] chat
+    #   @return [OpenLanes::Live::Chat, nil] the chat between machines (plan 006),
+    #     relayed to this server's pages; nil where nothing serves it
+    # @!attribute [r] listen
+    #   @return [OpenLanes::Web::Listen] the addresses served, which decide
+    #     the Host headers answered
+    # @!attribute [r] credentials
+    #   @return [OpenLanes::Web::AdminAuth::Credentials, nil] the login asked
+    #     of every request from off this machine; nil asks for none
     # @!attribute [r] stopping
     #   @return [Concurrent::AtomicBoolean] set when the server shuts down, so
-    #     open streams end within a tick
+    #     open streams end on the `stop` nudge that follows
     Context = Data.define(:stores,
       :keys,
       :plans_dir,
@@ -43,13 +58,17 @@ module OpenLanes
       :csrf,
       :dist,
       :node,
-      :tick,
       :ping_every,
       :lifetime,
       :demo,
+      :copilot,
+      :background,
+      :chat,
+      :listen,
+      :credentials,
       :stopping) do
-      def initialize(dist: DIST, node: nil, tick: 0.25, ping_every: 15.0, lifetime: nil, demo: nil,
-        stopping: Concurrent::AtomicBoolean.new, **rest)
+      def initialize(dist: DIST, node: nil, ping_every: 15.0, lifetime: nil, demo: nil, copilot: nil, chat: nil,
+        background: Context::THREAD, listen: Listen.parse(nil), credentials: nil, stopping: Concurrent::AtomicBoolean.new, **rest)
         super
       end
 
@@ -62,5 +81,10 @@ module OpenLanes
       # @return [Boolean]
       def dist? = File.file?(index)
     end
+
+    class Context
+      # Work started apart from a request, on a thread of its own.
+      THREAD = ->(&work) { Thread.new(&work) }
+    end
   end
 end

data/lib/openlanes/web/demo.rb

@@ -19,15 +19,28 @@ module OpenLanes
       # The other machine's checkout id, fixed so its keys are stable.
       OTHER_CHECKOUT = Live::Node.digest("openlanes-demo-other", Live::Node::CHECKOUT_LENGTH)
 
+      # What the copilot answers in the demo, where no agent runs and the
+      # board is made up: one plain line, so the panel can still be tried.
+      COPILOT_TEXT = "This is the demo run: c3po-operator does not run here, so nothing reads this or acts on it."
+
+      # The copilot's responder under `--demo` (W17), in place of
+      # {Live::Copilot::Operator}.
+      COPILOT = lambda do |turn|
+        [Live::Copilot::Turn.new(id: "#{turn.id}.1", from: "copilot", kind: "text", text: COPILOT_TEXT)]
+      end
+
       # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
       # @param keys [OpenLanes::Live::Keys] this node's
-      # @param board [OpenLanes::Web::DemoBoard]
+      # @param board [OpenLanes::Web::DemoBoard, nil] the fixture's, by default
+      # @param node [OpenLanes::Live::Node, nil] a declared identity
+      #   (`--identity`), which the board, and every reset of it, is published as
       # @param interval [Float]
       # @param clock [Proc] wall time
-      def initialize(store:, keys:, board: DemoBoard.new, interval: INTERVAL, clock: -> { Time.now })
+      def initialize(store:, keys:, board: nil, node: nil, interval: INTERVAL, clock: -> { Time.now })
         @store = store
         @keys = keys
-        @board = board
+        @node = node
+        @board = board || DemoBoard.new(node:)
         @interval = interval
         @clock = clock
         @seqs = {}
@@ -43,7 +56,7 @@ module OpenLanes
       # same board whatever the last one answered or stopped.
       #
       # @return [void]
-      def reset = @mutex.synchronize { @board = DemoBoard.new }
+      def reset = @mutex.synchronize { @board = DemoBoard.new(node: @node) }
 
       # Publish and answer every {INTERVAL}, on a thread of its own.
       #
@@ -65,8 +78,9 @@ module OpenLanes
       def stop
         @running = false
         @thread&.join(@interval * 2)
-        @store.del(@keys.snapshot, @keys.snapshot(other))
-        @store.hdel(@keys.nodes, @keys.node, other)
+        names = [@keys.node, other].compact
+        @store.del(*names.map { @keys.snapshot(it) })
+        @store.hdel(@keys.nodes, *names)
       rescue Live::Unavailable
         nil
       end
@@ -81,6 +95,9 @@ module OpenLanes
           @board.advance(@clock.call)
           publish(@keys.node, @board.me)
           @board.others.each { publish(other, it) }
+          # The demo's board moves on every tick, so every tick is news, and
+          # the one nudge covers this tick's replies as well.
+          Live::News.publish(store: @store, keys: @keys, kind: "board")
           replies
         end
       rescue Live::Unavailable => e
@@ -90,16 +107,19 @@ module OpenLanes
 
       private
 
-      # @return [String] the pretend other machine's node name
-      def other = "#{@board.others.first&.dig("node", "id")}:#{OTHER_CHECKOUT}"
+      # @return [String, nil] the pretend other machine's node name, when this demo has one
+      def other = @board.others.first&.dig("node", "id")&.then { "#{it}:#{OTHER_CHECKOUT}" }
 
       # @return [void]
       def publish(name, snapshot)
         snapshot["seq"] = next_seq(name)
+        # The fixture names a Redis for the page to show; the demo says the
+        # one it is really publishing through, as the engine does.
+        snapshot["redis_url"] = Live.redact(@store.url)
         json = JSON.generate(snapshot)
-        @store.multi do |tx|
+        Live::EventBus.for(@store).transaction do |tx|
           tx.set(@keys.snapshot(name), json, ex: Live::Keys::SNAPSHOT_TTL)
-          tx.xadd(@keys.board(name), { seq: snapshot["seq"], json: }, maxlen: Live::Keys::BOARD_LENGTH)
+          tx.append(@keys.board(name), { seq: snapshot["seq"], json: }, maxlen: Live::Keys::BOARD_LENGTH)
           tx.hset(@keys.nodes, name, JSON.generate(snapshot["node"]))
         end
       end
@@ -131,9 +151,14 @@ module OpenLanes
         command = Live::Command.parse(entry.fields["json"].to_s)
         first = @store.hget(@keys.done, command.id)
         reply = first ? parse(first) : outcome(command)
-        @store.multi do |tx|
+        # A slash command is answered in the conversation too, or the page's
+        # copilot waits for an engine reply that never comes. Once only: a
+        # redelivery has its turn already.
+        turn = Live::Commands.echo_turn(reply) if !first && command.payload["source"] == "copilot"
+        Live::EventBus.for(@store).transaction do |tx|
           tx.hset(@keys.done, reply.id, reply.to_json) unless first
-          tx.xadd(@keys.replies, { json: reply.to_json }, maxlen: Live::Keys::REPLIES_LENGTH)
+          tx.append(@keys.replies, { json: reply.to_json }, maxlen: Live::Keys::REPLIES_LENGTH)
+          tx.append(@keys.copilot, { json: turn.to_json }, maxlen: Live::Keys::COPILOT_LENGTH) if turn
           tx.xack(@keys.commands, Live::Keys::GROUP, entry.id)
         end
         reply
@@ -152,8 +177,8 @@ module OpenLanes
       # @return [OpenLanes::Live::Reply]
       def refuse(entry, reason)
         reply = Live::Reply.new(id: entry.id, status: "refused", reason:, at: @clock.call)
-        @store.multi do |tx|
-          tx.xadd(@keys.replies, { json: reply.to_json }, maxlen: Live::Keys::REPLIES_LENGTH)
+        Live::EventBus.for(@store).transaction do |tx|
+          tx.append(@keys.replies, { json: reply.to_json }, maxlen: Live::Keys::REPLIES_LENGTH)
           tx.xack(@keys.commands, Live::Keys::GROUP, entry.id)
         end
         reply

data/lib/openlanes/web/demo_board.rb

@@ -10,6 +10,10 @@ module OpenLanes
     #
     # Each command kind is one method, named as {Live::Commands} names its
     # handlers, raising {Refusal} with the reason the engine would give.
+    #
+    # The fixture carries one plan hansolo approved and one whose pull
+    # request merged, each with `finished` set and no cars, so the demo
+    # shows the half-height rows a real run keeps until it restarts.
     class DemoBoard
       # A command the demo will not apply.
       class Refusal < StandardError; end
@@ -35,12 +39,20 @@ module OpenLanes
         "stop"    => { "phase" => "stopped", "state" => "done" }
       }.freeze
 
+      # The fields of a snapshot's `node` a declared identity replaces.
+      IDENTITY = %w[id user host ip checkout].freeze
+
       # @param fixture [String] path to a `Board` JSON
       # @param random [Random]
-      def initialize(fixture: FIXTURE, random: Random.new(4747))
+      # @param node [OpenLanes::Live::Node, nil] a declared identity
+      #   (`--identity`): this board is then that machine's, and the pretend
+      #   other machine is left to the demo that has none, so two demos on
+      #   one Redis never publish the same node twice
+      def initialize(fixture: FIXTURE, random: Random.new(4747), node: nil)
         board = JSON.parse(File.read(fixture))
         @me = board.fetch("me")
-        @others = board.fetch("others")
+        @others = node ? [] : board.fetch("others")
+        @me["node"].merge!(node.wire(heartbeat_at: Time.now).transform_keys(&:to_s).slice(*IDENTITY)) if node
         @random = random
         @ticks = 0
       end
@@ -64,7 +76,12 @@ module OpenLanes
       # @return [String, nil] a reason to show beside "done"
       # @raise [Refusal]
       def apply(command)
-        send(Live::Commands::HANDLERS.fetch(command.kind), command)
+        handler = Live::Commands::HANDLERS.fetch(command.kind)
+        # A kind the engine gained and the demo did not would otherwise raise
+        # NoMethodError on the demo's thread, and the board would freeze.
+        raise Refusal, "the demo cannot #{command.kind}" unless respond_to?(handler, true)
+
+        send(handler, command)
       end
 
       private
@@ -227,6 +244,46 @@ module OpenLanes
         entry["id"]
       end
 
+      # ---- lanes (plan 020.00) ----------------------------------------------
+
+      # `/stop NNN`: every running agent on the plan stops. The plan stays on
+      # the board, stopped, so `/restart` has something to bring back.
+      #
+      # @return [String]
+      def stop_plan(command)
+        cars = plan!(command)["cars"].select { it["state"] == "running" }
+        cars.each { it.merge!(SIGNALS.fetch("stop"), "held" => false) }
+        "stopped #{cars.size} agent#{"s" unless cars.size == 1} on #{command.plan} and took it off the board"
+      end
+
+      # `/restart NNN`: the plan's stopped cars run again, unless one still does.
+      #
+      # @return [String]
+      def restart_plan(command)
+        plan = plan!(command)
+        working = plan["cars"].select { it["state"] == "running" }.map { it["agent"] }
+        raise Refusal, "#{command.plan} already has an agent: #{working.join(", ")}" unless working.empty?
+
+        # A stuck car waits on a question, and a restart answers none.
+        plan["cars"].select { it["state"] == "done" }.each { it.merge!("state" => "running", "phase" => "calm", "held" => false) }
+        "#{command.plan} restarts at the next tick"
+      end
+
+      # `/concurrency N`, worded as the engine words it. Lowering it stops
+      # nobody, as in the engine.
+      #
+      # @return [String]
+      def set_concurrency(command) # rubocop:disable Naming/AccessorMethodName -- the engine's handler name
+        limit = command.payload["limit"]
+        raise Refusal, "concurrency must be a whole number of at least 1, not #{limit.inspect}" unless limit.is_a?(Integer) && limit >= 1
+
+        before = @me["run"]["jobs"]
+        @me["run"]["jobs"] = limit
+        over = running(@me).size - limit
+        wait = over.positive? ? "; the run waits for #{over} agent#{"s" unless over == 1} to finish" : ""
+        "concurrency #{before} → #{limit}#{wait}"
+      end
+
       # ---- plans ------------------------------------------------------------
 
       # @return [nil]
@@ -245,7 +302,7 @@ module OpenLanes
         title = command["idea"].lines.first.to_s.strip.delete_prefix("#").strip
         @me["plans"] << plan_from({ "ordinal" => ordinal,
                                     "title" => title,
-                                    "status" => { "key" => "new", "emoji" => "⚪️", "label" => "New" },
+                                    "status" => { "key" => "new", "emoji" => "⚪", "label" => "New" },
                                     "lane" => "full" })
         "created #{ordinal} #{slug(title)}"
       end
@@ -264,7 +321,8 @@ module OpenLanes
           "pr" => nil,
           "questions" => [],
           "interrupted" => nil,
-          "claimed_by" => @me.dig("node", "id"))
+          "claimed_by" => @me.dig("node", "id"),
+          "finished" => nil)
       end
 
       # @return [String]