openlanes 3.0.0 → 3.0.1

data/lib/openlanes/vcs/publisher.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "tempfile"
 require "tty/command"
 
@@ -93,6 +94,7 @@ module OpenLanes
         mismatch = open && head_mismatch(open, checkout)
         return refuse(subject, checkout, title, mismatch) if mismatch
 
+        carry_plan(checkout, subject)
         commit(checkout, title)
         push(checkout)
         url = open ? open.url : create_pull_request(checkout, subject, title)
@@ -132,8 +134,68 @@ module OpenLanes
       # @return [String]
       def auto_letter(subject) = LETTERS.fetch(subject.pull_requests.size, LETTERS.last)
 
+      # Left out of the copy: the half-written temporaries an atomic write
+      # renames into place (`state.json.<pid>.<thread>.tmp`).
+      CARRY_EXCLUDED = ["*.tmp"].freeze
+
+      # Copy the plan's folder from the main checkout into the worktree, so
+      # the pull request carries its spec, plan and state next to the code.
+      #
+      # The main checkout stays the only writer. The engine reads, signs and
+      # renames the plan there and nowhere else; the worktree gets a snapshot,
+      # refreshed on every publish. Every copy of the same plan number is
+      # removed first, so a folder renamed since the last publish (⭐️ to 🟢,
+      # say) does not leave its old name behind in the branch, and a file
+      # deleted in the main checkout is deleted in the branch too.
+      #
+      # Nothing is copied when the worktree is the main checkout itself, which
+      # would delete the source, or when the plans live outside the
+      # repository, where the branch has no place for them.
+      #
+      # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
+      # @param subject [OpenLanes::Plans::Subject] the plan in the main checkout
+      # @return [String, nil] the copy's path, nil when nothing was copied
+      def carry_plan(checkout, subject)
+        root = real(@root)
+        source = real(subject.feature.path)
+        return nil if real(checkout.path) == root || !source.start_with?("#{root}/")
+
+        parent = File.join(checkout.path, File.dirname(source.delete_prefix("#{root}/")))
+        FileUtils.mkdir_p(parent)
+        Dir.children(parent).each do |name|
+          next unless Plans::Ordinal.from_dirname(name) == subject.feature.ordinal
+
+          FileUtils.rm_rf(File.join(parent, name))
+        end
+        copy_tree(source, File.join(parent, File.basename(source)))
+      end
+
       private
 
+      # @param path [String]
+      # @return [String] symlinks resolved, so /var and /private/var compare equal
+      def real(path)
+        File.realpath(path)
+      rescue Errno::ENOENT
+        File.expand_path(path)
+      end
+
+      # @param source [String]
+      # @param target [String]
+      # @return [String] target
+      def copy_tree(source, target)
+        Dir.glob("**/*", File::FNM_DOTMATCH, base: source).each do |relative|
+          next if relative == "." || CARRY_EXCLUDED.any? { File.fnmatch?(it, File.basename(relative)) }
+
+          from = File.join(source, relative)
+          to = File.join(target, relative)
+          FileUtils.mkdir_p(File.directory?(from) ? to : File.dirname(to))
+          FileUtils.cp(from, to) if File.file?(from)
+        end
+        FileUtils.mkdir_p(target)
+        target
+      end
+
       # Why the open pull request cannot receive this checkout's push, if it
       # cannot.
       #

data/lib/openlanes/vcs/worktree.rb

@@ -20,11 +20,43 @@ module OpenLanes
     # carries itself from worktree creation through to a merged pull request with
     # nobody having to remember it.
     class Worktree
-      # `bin/setup-worktree`, which copies in the ignored-but-required files a new
-      # checkout does not get. Shelling out rather than reimplementing the rules
-      # here keeps one answer to "what does a worktree need", and keeps that answer
-      # usable from a shell on a machine that has never run `bundle install`.
-      SEEDER = File.expand_path("../../../bin/setup-worktree", __dir__)
+      # `setup-worktree`, which copies in the ignored-but-required files a new
+      # checkout does not get. It is the user's own script, not this gem's:
+      # shelling out rather than reimplementing the rules here keeps one answer
+      # to "what does a worktree need", usable from a shell on a machine that
+      # has never run `bundle install`.
+      SEEDER_NAME = "setup-worktree"
+
+      # Names the seeder outright, ahead of every place {.seeder} searches.
+      SEEDER_ENV = "OPENLANES_SETUP_WORKTREE"
+
+      # Searched after `PATH`, where the user's own tooling keeps it.
+      SEEDER_HOMES = %w[~/.claude/bin ~/.agents/bin].freeze
+
+      class << self
+        # The seeder to run, or nil when none is installed.
+        #
+        # It used to be `bin/setup-worktree` beside this file, which the gem
+        # never shipped, so every installed run seeded nothing and said so
+        # once per agent.
+        #
+        # @param env [Hash] the environment, for `PATH` and {SEEDER_ENV}
+        # @return [String, nil] an executable path
+        def seeder(env = ENV) = seeder_candidates(env).find { File.file?(it) && File.executable?(it) }
+
+        # Every place {.seeder} looks, in order.
+        #
+        # @param env [Hash]
+        # @return [Array<String>]
+        def seeder_candidates(env = ENV)
+          on_path = env.fetch("PATH", "").split(File::PATH_SEPARATOR).reject(&:empty?).map { File.join(it, SEEDER_NAME) }
+          homes = SEEDER_HOMES.map { File.join(File.expand_path(it), SEEDER_NAME) }
+          [env[SEEDER_ENV].to_s, *on_path, *homes].reject(&:empty?).uniq
+        end
+
+        # @return [String] where {.seeder} looks, for a person
+        def seeder_search = "$#{SEEDER_ENV}, #{SEEDER_NAME} on PATH, #{SEEDER_HOMES.join(", ")}"
+      end
 
       # One plan's isolated checkout.
       #
@@ -50,9 +82,11 @@ module OpenLanes
       # @param root [String] the main repository
       # @param dir [String, nil] where worktrees go; defaults to a sibling
       # @param user [String] branch namespace
-      def initialize(root:, dir: nil, user: ENV["USER"] || "agent")
+      # @param seeder [String, nil] the seeder to run; nil runs none
+      def initialize(root:, dir: nil, user: ENV["USER"] || "agent", seeder: self.class.seeder)
         @root = File.expand_path(root)
         @user = user
+        @seeder = seeder
         @dir = File.expand_path(dir || default_dir)
       end
 
@@ -118,12 +152,13 @@ module OpenLanes
       # @param path [String] the worktree to seed
       # @return [Boolean] whether the seeder ran and succeeded
       def seed(path)
-        unless File.executable?(SEEDER)
-          UI.log("worktree: #{SEEDER} is missing, so #{path} has no .env or credential keys")
+        unless @seeder && File.executable?(@seeder)
+          UI.log("worktree: no #{SEEDER_NAME} found (searched #{self.class.seeder_search}), " \
+                 "so #{path} has no .env or credential keys")
           return false
         end
 
-        return true if system(SEEDER, "--quiet", path, out: File::NULL, err: File::NULL)
+        return true if system(@seeder, "--quiet", path, out: File::NULL, err: File::NULL)
 
         UI.log("worktree: could not seed #{path}; its suite may fail on a missing key")
         false

data/lib/openlanes/version.rb

@@ -6,5 +6,5 @@
 #
 # © 2026 Konstantin Gredeskoul
 module OpenLanes
-  VERSION = "3.0.0"
+  VERSION = "3.0.1"
 end

data/lib/openlanes/web/app.rb

@@ -63,6 +63,45 @@ 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::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)
@@ -120,7 +159,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 +175,66 @@ module OpenLanes
         json(Live::Reply.new(id: id_in(body), status: "refused", reason: e.message).wire)
       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}).
+      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)
+        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

data/lib/openlanes/web/context.rb

@@ -33,6 +33,16 @@ module OpenLanes
     # @!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] stopping
     #   @return [Concurrent::AtomicBoolean] set when the server shuts down, so
     #     open streams end within a tick
@@ -47,9 +57,12 @@ module OpenLanes
       :ping_every,
       :lifetime,
       :demo,
+      :copilot,
+      :background,
+      :chat,
       :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, tick: 0.25, ping_every: 15.0, lifetime: nil, demo: nil, copilot: nil, chat: nil,
+        background: Context::THREAD, stopping: Concurrent::AtomicBoolean.new, **rest)
         super
       end
 
@@ -62,5 +75,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,6 +19,16 @@ 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]

data/lib/openlanes/web/events.rb

@@ -6,7 +6,8 @@ module OpenLanes
   module Web
     # One page's event stream (contract.md, `GET /api/events`): a `board`
     # event whenever any node's snapshot `seq` changes, a `reply` event for
-    # each reply the engine writes, and a `: ping` comment so proxies and the
+    # each reply the engine writes, a `copilot` event for each turn of the
+    # 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
@@ -18,18 +19,40 @@ module OpenLanes
     # opens with a `cursor` event carrying the id it starts from, so a
     # browser that drops before the first reply still has one to send;
     # without it, replies written during that gap were skipped.
+    #
+    # A `chat` event (plan 006) carries no `id:` either, and like the
+    # copilot's the stream opens with a `chat_cursor` when it carries a
+    # page's chat, so the page reads `GET /api/chat` only once relaying has
+    # begun. Nor is there a cursor id to carry: the chat between
+    # machines keeps no history (D2), so there is nothing to catch up on.
+    # The stream is how {Live::Chat} knows the page is still open; when it
+    # closes, the page has {Live::Chat::GRACE} to reconnect before it counts
+    # as having left (D6).
+    #
+    # A copilot turn carries no `id:`, so it never moves that cursor. The
+    # conversation has a boundary of its own instead: the stream samples the
+    # newest turn, says so in a `copilot_cursor` event, and from then on
+    # sends every turn after it. The page reads `GET /api/copilot` when that
+    # event arrives, never before it, so the read covers everything up to
+    # 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.
     class Events
       # @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
-      def initialize(context:, store:, last_id: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
+      def initialize(context:, store:, last_id: nil, page: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
         sleeper: ->(seconds) { sleep seconds })
         @context = context
         @store = store
         @keys = context.keys
+        @copilot = Live.copilot(store:, keys: @keys)
         @last_id = last_id.to_s.match?(/\A\d+-\d+\z/) ? last_id : nil
+        @chat = context.chat
+        @page = page.to_s.match?(Live::Chat::PAGE) ? page : nil
         @clock = clock
         @sleeper = sleeper
       end
@@ -40,14 +63,22 @@ module OpenLanes
       # @param out [#<<, #closed?]
       # @return [void]
       def run(out)
+        @chat&.attach(@page) if @page
         started = @clock.call
         pinged = started
         cursor = @last_id || newest_reply
         out << self.class.frame("cursor", { id: cursor }, id: cursor)
+        said = @copilot.newest
+        out << self.class.frame("copilot_cursor", { id: said }) unless out.closed?
+        # 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?
         seqs = nil
         until over?(out, started)
           seqs = board(out, seqs)
           cursor = replies(out, cursor)
+          said = copilot(out, said)
+          chat(out)
           pinged = ping(out) if @clock.call - pinged >= @context.ping_every
           @sleeper.call(@context.tick)
         end
@@ -55,6 +86,8 @@ module OpenLanes
         # 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
+        @chat&.detach(@page) if @page
       end
 
       # @param event [String]
@@ -87,6 +120,22 @@ module OpenLanes
         cursor
       end
 
+      # @return [String] the last copilot turn's stream id sent
+      def copilot(out, said)
+        @copilot.since(said).each do |id, turn|
+          out << self.class.frame("copilot", turn)
+          said = id
+        end
+        said
+      end
+
+      # @return [void]
+      def chat(out)
+        return unless @chat && @page
+
+        @chat.drain(@page).each { out << self.class.frame("chat", it) }
+      end
+
       # @return [Float] when it pinged
       def ping(out)
         out << ": ping\n\n"

data/lib/openlanes/web/launcher.rb

@@ -137,7 +137,7 @@ module OpenLanes
       def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
       # @return [String]
-      def default_log(root) = File.join(Dir.tmpdir, "openlanes-web-#{File.basename(root)}.log")
+      def default_log(root) = Engine::ProgressLog.default_path(root, kind: "web")
     end
   end
 end

data/lib/openlanes/web/server.rb

@@ -50,6 +50,7 @@ module OpenLanes
           log_writer:           Puma::LogWriter.new(File.open(File::NULL, "w"), @log))
         @puma.add_tcp_listener(@host, @port)
         @thread = @puma.run
+        @context.chat&.start
         self
       end
 
@@ -69,6 +70,7 @@ module OpenLanes
       # @return [void]
       def stop
         @context.stopping.make_true
+        @context.chat&.stop
         @puma&.stop(true)
         @context.stores.close
       end

data/lib/openlanes/web/stores.rb

@@ -26,6 +26,17 @@ module OpenLanes
       # @return [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
       def current = @mutex.synchronize { @by_thread[Thread.current] ||= @factory.call }
 
+      # Drop and close this thread's store. A thread that is not one of
+      # Puma's pooled ones calls it when done, or the map would keep a
+      # connection for every such thread that ever ran. A shared store is
+      # dropped but not closed: the others still hold it.
+      #
+      # @return [void]
+      def release
+        store = @mutex.synchronize { @by_thread.delete(Thread.current) }
+        store&.close unless @mutex.synchronize { @by_thread.value?(store) }
+      end
+
       # @return [void]
       def close
         stores = @mutex.synchronize { @by_thread.values.uniq.tap { @by_thread.clear } }

data/lib/openlanes/web.rb

@@ -38,9 +38,22 @@ module OpenLanes
     # @param rest [Hash] {Context}'s other fields
     # @return [OpenLanes::Web::Context]
     def context(stores:, keys:, plans_dir:, url:, **rest)
+      rest[:chat] ||= chat(stores:, keys:, node: rest[:node])
       Context.new(stores:, keys:, plans_dir:, url:, csrf: SecureRandom.hex(32), **rest)
     end
 
+    # The chat between machines for one server (plan 006). Its machine is
+    # the node id in +keys+, so it answers for the same machine the board does.
+    #
+    # @param stores [OpenLanes::Web::Stores]
+    # @param keys [OpenLanes::Live::Keys]
+    # @param node [OpenLanes::Live::Node, nil]
+    # @return [OpenLanes::Live::Chat]
+    def chat(stores:, keys:, node: nil, **)
+      machine = keys.node.split(":").first
+      Live::Chat.new(stores:, keys:, machine:, label: node&.label || machine, **)
+    end
+
     # @param context [OpenLanes::Web::Context]
     # @return [Class] a Rack application
     def app(context) = App.serving(context)