openlanes 3.0.1 → 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
@@ -79,6 +79,19 @@ module OpenLanes
           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"))
 
@@ -137,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)
@@ -175,6 +208,47 @@ 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
@@ -182,12 +256,13 @@ module OpenLanes
       # 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}).
+      # 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)
+        answer_later(turn) unless turn.slash?
         status 202
         json(turn.wire)
       rescue Live::Copilot::Invalid => e
@@ -245,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,10 +23,9 @@ 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.
@@ -43,9 +42,15 @@ module OpenLanes
     # @!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,
@@ -53,16 +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, copilot: nil, chat: nil,
-        background: Context::THREAD, 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
 

data/lib/openlanes/web/demo.rb

@@ -31,13 +31,16 @@ module OpenLanes
 
       # @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 = {}
@@ -53,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.
       #
@@ -75,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
@@ -91,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
@@ -100,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
@@ -141,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
@@ -162,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]

data/lib/openlanes/web/events.rb

@@ -10,9 +10,15 @@ module OpenLanes
     # conversation with the copilot (W17), and a `: ping` comment so proxies and the
     # browser keep the connection open.
     #
-    # Polled rather than blocked on: a blocking read would hold the thread's
-    # connection for the length of the wait, and the board has to be looked
-    # at every tick anyway.
+    # Pushed rather than polled: the stream holds a subscription of its own
+    # to {Live::Keys#news} and sleeps on it until a writer nudges ({Live::News}),
+    # then reads Redis exactly as it did when it looked every quarter second.
+    # The nudge carries no data, so the cursors below are untouched by it.
+    # It subscribes before its first read, so a write that lands between
+    # the two is read twice rather than missed. With no nudge it still looks
+    # once per ping, which is how it notices what nobody announces: a node
+    # whose snapshot expired, an app whose runner was killed. One
+    # subscription per stream, closed when the stream ends.
     #
     # A reply carries its stream id as the event's `id:`, so a browser that
     # reconnects sends `Last-Event-ID` and gets what it missed. The stream
@@ -37,15 +43,31 @@ module OpenLanes
     # the boundary and the stream everything after. A turn written between a
     # read the page started on its own and the stream opening fell in the
     # gap between the two and was never shown.
+    #
+    # The apps running on this machine (plan 012) open the stream as one
+    # `apps` event, sent only when there is one, so a project with no app
+    # gets the stream it always had; the page starts each stream with no
+    # apps. After that each process whose status changed comes as an `app`
+    # event. A process whose plan's entry vanished (its runner
+    # stopped or died) is sent once more as `stopped`, so the page never
+    # keeps a tab for an app that is gone.
     class Events
+      # How often a stream without a subscription looks again: the polling
+      # interval every stream used before nudges.
+      POLL = 0.25
+
+      # Block on the subscription for the next nudge, or, with none, poll.
+      WAIT = ->(news, seconds) { news ? news.next_message(seconds) : sleep([seconds, POLL].min) }
+
       # @param context [OpenLanes::Web::Context]
       # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
       # @param last_id [String, nil] the `Last-Event-ID` the browser sent
       # @param page [String, nil] the page's own id, `?page=` on the stream, for its chat
       # @param clock [Proc] seconds, monotonic
-      # @param sleeper [Proc] waits the given seconds between ticks
+      # @param waiter [Proc] given the subscription and at most how many
+      #   seconds to wait, returns once a nudge arrives or the time is up
       def initialize(context:, store:, last_id: nil, page: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
-        sleeper: ->(seconds) { sleep seconds })
+        waiter: WAIT)
         @context = context
         @store = store
         @keys = context.keys
@@ -54,7 +76,7 @@ module OpenLanes
         @chat = context.chat
         @page = page.to_s.match?(Live::Chat::PAGE) ? page : nil
         @clock = clock
-        @sleeper = sleeper
+        @waiter = waiter
       end
 
       # Write events to +out+ until the browser leaves, the server stops, or
@@ -64,6 +86,7 @@ module OpenLanes
       # @return [void]
       def run(out)
         @chat&.attach(@page) if @page
+        news = subscribe
         started = @clock.call
         pinged = started
         cursor = @last_id || newest_reply
@@ -73,20 +96,23 @@ module OpenLanes
         # The page is attached, so every chat event from here on is queued for
         # it: a `GET /api/chat` the page starts on this misses nothing.
         out << self.class.frame("chat_cursor", {}) if @chat && @page && !out.closed?
+        apps = open_apps(out)
         seqs = nil
         until over?(out, started)
           seqs = board(out, seqs)
+          apps = app_news(out, apps)
           cursor = replies(out, cursor)
           said = copilot(out, said)
           chat(out)
           pinged = ping(out) if @clock.call - pinged >= @context.ping_every
-          @sleeper.call(@context.tick)
+          wait(news, started, pinged)
         end
       rescue Live::Unavailable => e
         # Ending the stream is the right answer: the page reconnects with
         # backoff and shows itself as reconnecting meanwhile.
         out << ": #{e.message.tr("\n", " ")}\n\n"
       ensure
+        news&.close
         @chat&.detach(@page) if @page
       end
 
@@ -98,11 +124,45 @@ module OpenLanes
 
       private
 
+      # The stream's subscription to nudges, or nil to poll. A Redis user
+      # whose ACL withholds SUBSCRIBE got a working polled board before
+      # nudges existed, and ending the stream instead would leave its page
+      # reconnecting forever. A Redis that is gone fails the first read
+      # just after, and ends the stream there.
+      #
+      # @return [OpenLanes::Live::Subscriber, OpenLanes::Live::MemorySubscriber, nil]
+      def subscribe
+        Live::News.subscribe(store: @store, keys: @keys)
+      rescue Live::Unavailable => e
+        UI.log("events: no nudges, polling every #{POLL}s: #{e.message}", level: :warn)
+        nil
+      end
+
       # @return [Boolean]
       def over?(out, started)
         out.closed? || @context.stopping.true? || (@context.lifetime && @clock.call - started >= @context.lifetime)
       end
 
+      # Sleep until a nudge, the next ping, or the end of the stream's
+      # lifetime, whichever comes first. One nudge, one look: a nudge that
+      # arrives while the stream is reading stays queued and wakes the next
+      # wait at once, so nothing written during a look is missed. Queued
+      # nudges are not drained first because the drain costs more than it
+      # saves: redis-client cannot poll without waiting, so emptying the
+      # queue costs {Live::Subscriber::SHORTEST} on every wake, ten times
+      # what an extra look costs, and a tick nudges once or twice at most.
+      #
+      # @param news [OpenLanes::Live::Subscriber, OpenLanes::Live::MemorySubscriber]
+      # @param started [Float]
+      # @param pinged [Float]
+      # @return [void]
+      def wait(news, started, pinged)
+        now = @clock.call
+        limits = [@context.ping_every - (now - pinged)]
+        limits << (@context.lifetime - (now - started)) if @context.lifetime
+        @waiter.call(news, [limits.min, 0].max)
+      end
+
       # @return [Array] the seqs now, after sending the board if they changed
       def board(out, seqs)
         board = Live.board(store: @store, keys: @keys)
@@ -111,6 +171,25 @@ module OpenLanes
         now
       end
 
+      # @return [Hash{Array(String, String) => Hash}] what was sent, by plan and process
+      def open_apps(out)
+        now = live_apps
+        out << self.class.frame("apps", { apps: now.values }) unless now.empty? || out.closed?
+        now
+      end
+
+      # @param sent [Hash{Array(String, String) => Hash}]
+      # @return [Hash{Array(String, String) => Hash}]
+      def app_news(out, sent)
+        now = live_apps
+        now.each { |key, app| out << self.class.frame("app", app) unless sent[key] == app }
+        sent.except(*now.keys).each_value { out << self.class.frame("app", it.merge("state" => "stopped")) }
+        now
+      end
+
+      # @return [Hash{Array(String, String) => Hash}]
+      def live_apps = Apps::Listing.read(store: @store, keys: @keys).to_h { [[it["plan"], it["process"]], it] }
+
       # @return [String] the last reply id sent
       def replies(out, cursor)
         Live.replies(store: @store, keys: @keys, after: cursor).each do |id, reply|