openlanes 3.0.0

data/lib/openlanes/execution/child.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Execution
+    # One `claude` process the harness started and therefore owns.
+    #
+    # `TTY::Command` never exposes the pid it spawned, so the executor used to
+    # find its child by scraping `ps` for a fresh `claude` under this process
+    # and could never safely signal it. Kill (`k`) and the sixty-second
+    # backstop after STOP both need a pid that is certainly ours, so the
+    # process is spawned here and the pid kept.
+    #
+    # stderr is folded into the same pipe as stdout: `claude` prints the cause
+    # of a failure there, and the transcript keeps non-JSON lines for exactly
+    # that reason.
+    #
+    # The process leads a process group of its own, and every stop is sent to
+    # the whole group. A SIGKILL aimed at `claude` alone once left the shell
+    # its Bash tool had started (and the `eza` an `ls` alias ran in it)
+    # holding the write end of this pipe: the reader never saw end of file,
+    # and `--timeout 600` ended nothing. The group is also why a terminal's
+    # Ctrl-C no longer reaches an agent directly; the harness forwards its
+    # own stop instead, and {.terminate_all} catches a harness that exits
+    # before its agents have.
+    class Child
+      # Seconds between TERM and KILL in {#terminate}: long enough for a
+      # process to flush and exit, short enough that a stop is a stop.
+      TERM_GRACE = 5
+
+      # Seconds {#terminate} waits, after KILL, for the reader to reach end of
+      # file on its own before closing the pipe under it. Only a process that
+      # left the group, by `setsid` or a daemonising double fork, can still be
+      # holding the pipe by then.
+      DRAIN_GRACE = 1
+
+      # How often {#terminate} looks again while it waits.
+      POLL = 0.05
+
+      @live = []
+      @mutex = Mutex.new
+
+      class << self
+        # @param argv [Array<String>]
+        # @param chdir [String, nil]
+        # @param env [Hash{String => String}] what the adapter adds on top of
+        #   {.environment}, e.g. claude's autocompact threshold
+        # @return [OpenLanes::Execution::Child]
+        def spawn(argv, chdir: nil, env: {})
+          reader, writer = IO.pipe
+          options = { out: writer, err: writer, in: File::NULL, unsetenv_others: true, pgroup: true }
+          options[:chdir] = chdir if chdir
+          pid = Process.spawn(environment.merge(env), *argv, **options)
+          writer.close
+          track(new(pid:, reader:))
+        end
+
+        # The environment the child starts in: the one Bundler was loaded under,
+        # less what Bundler itself put there. `exe/openlanes` pins `BUNDLE_GEMFILE`
+        # to its own Gemfile and `bundler/setup` adds `-rbundler/setup` to
+        # `RUBYOPT`; a child that inherited them would run every `bundle exec`,
+        # `standardrb` and `alock` against the harness's checkout instead of the
+        # worktree it was handed, and be told the gems that worktree's Gemfile adds
+        # are "not currently included in the bundle". Bundler knows exactly what it
+        # changed, so it is asked; without Bundler there is nothing to strip.
+        #
+        # @return [Hash{String => String}]
+        def environment
+          defined?(::Bundler) ? ::Bundler.unbundled_env : ENV.to_h
+        end
+
+        # @return [Array<OpenLanes::Execution::Child>] spawned and not yet reaped
+        def live = @mutex.synchronize { @live.dup }
+
+        # KILL every group still running. Registered with `at_exit`, so a
+        # second Ctrl-C, which raises in the harness and ends it at once, takes
+        # its agents down with it now that the terminal's own SIGINT no
+        # longer reaches them.
+        #
+        # A child stays here after its leader is reaped for as long as its
+        # group has members: a grandchild that ignores TERM and let go of the
+        # pipe outlives the leader, and this is what still reaches it.
+        #
+        # @return [void]
+        def terminate_all = live.each { it.kill("KILL") }
+
+        # @param child [OpenLanes::Execution::Child]
+        # @return [void]
+        def forget(child) = @mutex.synchronize { @live.delete(child) }
+
+        private
+
+        # @param child [OpenLanes::Execution::Child]
+        # @return [OpenLanes::Execution::Child]
+        def track(child)
+          @mutex.synchronize do
+            @at_exit ||= at_exit { terminate_all }
+            @live.reject!(&:finished?)
+            @live << child
+          end
+          child
+        end
+      end
+
+      # @param pid [Integer]
+      # @param reader [IO]
+      def initialize(pid:, reader:)
+        @pid = pid
+        @reader = reader
+        @status = nil
+        @terminating = false
+        @emptied = false
+        @guard = Mutex.new
+      end
+
+      # @return [Integer]
+      attr_reader :pid
+
+      # Read until the process closes its end. Runs on the caller's thread;
+      # the executor reads on the same thread it always did.
+      #
+      # @yieldparam text [String] whatever arrived, possibly a partial line
+      # @return [void]
+      def each_chunk
+        loop { yield @reader.readpartial(65_536) }
+      rescue IOError
+        # End of file, or {#terminate} closed the pipe under a reader that
+        # would otherwise have waited on it forever.
+        @reader.close unless @reader.closed?
+      end
+
+      # @return [Process::Status]
+      def wait
+        @status ||= begin
+          _, status = Process.wait2(pid)
+          status
+        end
+      rescue Errno::ECHILD
+        @status
+      ensure
+        self.class.forget(self) if finished?
+      end
+
+      # @return [Boolean] reaped, and nothing left in its group
+      def finished? = !@status.nil? && !group?
+
+      # Signal the whole group: the agent and everything it started.
+      #
+      # The group is signalled even after its leader has been reaped. A member
+      # that ignored TERM and let go of the pipe outlives the leader, and POSIX
+      # does not hand a group's id out as a pid while the group has members,
+      # so `-pid` still means this group. Once it answers ESRCH the group is
+      # empty, the id is free, and it is never signalled again.
+      #
+      # @param signal [String]
+      # @return [void]
+      def kill(signal = "KILL")
+        return if @emptied
+
+        Process.kill(signal, -pid)
+      rescue Errno::ESRCH
+        @emptied = true
+      rescue Errno::EPERM
+        # Not ours to signal, so not ours to end.
+      end
+
+      # The guarantee behind every stop: TERM to the group, KILL to whatever
+      # is left after +grace+, and the pipe closed if something outside the
+      # group still holds it, so the reader always finishes.
+      #
+      # Once only: the dispatcher asks again on every tick past a quit's
+      # deadline, and a second caller has nothing to add to the first.
+      #
+      # The leader being reaped mid-grace does not cut it short: the reader
+      # sees end of file as soon as the leader dies, and a member that
+      # ignored TERM is still there to KILL. The caller's thread must be left
+      # to finish; {Clock#stop} waits for an expiry under way for that reason.
+      #
+      # @param grace [Numeric] seconds between TERM and KILL
+      # @param drain [Numeric] seconds after KILL before the pipe is closed
+      # @return [void]
+      def terminate(grace: TERM_GRACE, drain: DRAIN_GRACE)
+        return if @guard.synchronize { @terminating.tap { @terminating = true } }
+
+        kill("TERM")
+        await(grace) { !group? }
+        kill("KILL")
+        await(drain) { @reader.closed? }
+        @reader.close unless @reader.closed?
+      rescue IOError
+        # The reader closed it first.
+      end
+
+      # @return [Boolean]
+      def alive?
+        return false if @status
+
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      end
+
+      private
+
+      # @return [Boolean] whether anything in the group, a zombie leader
+      #   included, is still there
+      def group?
+        return false if @emptied
+
+        Process.kill(0, -pid)
+        true
+      rescue Errno::ESRCH
+        @emptied = true
+        false
+      rescue Errno::EPERM
+        false
+      end
+
+      # @param seconds [Numeric]
+      # @yieldreturn [Boolean] done waiting
+      # @return [void]
+      def await(seconds)
+        deadline = UI.monotonic + seconds
+        sleep(POLL) until yield || UI.monotonic >= deadline
+      end
+    end
+  end
+end

data/lib/openlanes/execution/clock.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Execution
+    # The advisory clock one invocation runs against.
+    #
+    # It never terminates the agent on its own. It writes into the control file
+    # the agent polls: a warning ten and five minutes out, a wrap-up request at
+    # one, STOP at zero. Only a process still alive {GRACE} seconds after STOP
+    # is killed, and that is the executor's act on this clock's say-so, so the
+    # agent has every chance to write its ledger line first.
+    #
+    # `now` is injectable so the moments can be tested without sleeping.
+    class Clock
+      # Seconds before the deadline, and what the control file says then.
+      # A moment already in the past when the clock starts is skipped: a five
+      # minute agent told "10 minutes left" at t=0 has been lied to.
+      WARNINGS = [
+        [600, "WARN: 10 minutes left"],
+        [300, "WARN: 5 minutes left"],
+        [60, "WRAP_UP: 1 minute left, write to disk now"]
+      ].freeze
+
+      # Seconds after STOP before {#on_expire} fires.
+      GRACE = 60
+
+      # @param seconds [Integer] the budget
+      # @param control [String] the invocation's control file
+      # @param on_expire [Proc] called once, GRACE seconds after STOP
+      # @param now [Proc] a monotonic clock reading
+      def initialize(seconds:, control:, on_expire:, now: -> { UI.monotonic })
+        @control = control
+        @on_expire = on_expire
+        @now = now
+        @mutex = Mutex.new
+        arm(seconds)
+      end
+
+      # @return [Integer] whole seconds left, floored at zero
+      def remaining = [@deadline - @now.call, 0].max.round
+
+      # @return [Symbol] :calm, :warned, :wrap_up, :stopped or :expired
+      attr_reader :phase
+
+      # Evaluate every moment once. Idempotent within a phase.
+      #
+      # @return [void]
+      def tick
+        @mutex.synchronize do
+          left = @deadline - @now.call
+          WARNINGS.each do |before, text|
+            next if @fired.include?(before) || left > before
+
+            @fired << before
+            Control.write(@control, text)
+            @phase = before == 60 ? :wrap_up : :warned
+          end
+          if left <= 0 && !@fired.include?(:stop)
+            @fired << :stop
+            Control.write(@control, Control::STOP)
+            @phase = :stopped
+          end
+          if @fired.include?(:stop) && !@fired.include?(:expired) && left <= -GRACE
+            @fired << :expired
+            @phase = :expired
+            @on_expire.call
+          end
+        end
+      end
+
+      # @return [self]
+      def start
+        @thread ||= Thread.new do
+          Thread.current.report_on_exception = false
+          loop do
+            tick
+            break if phase == :expired
+
+            sleep(1)
+          end
+        end
+        self
+      end
+
+      # Waits out an expiry under way before killing the thread. {#tick}
+      # holds the mutex while {#on_expire} runs, and that is the kill: a
+      # thread killed inside it, between TERM and KILL, once left a
+      # grandchild that ignored TERM running after the attempt had ended.
+      #
+      # @return [void]
+      def stop
+        thread = @mutex.synchronize { @thread.tap { @thread = nil } }
+        thread&.kill
+      end
+
+      # Ten more minutes, or however many. The file is emptied so the next poll
+      # reads a reprieve, and every moment is re-armed against the new deadline.
+      #
+      # @param seconds [Integer]
+      # @return [void]
+      def extend!(seconds)
+        @mutex.synchronize do
+          @deadline += seconds
+          @fired = []
+          @phase = :calm
+          Control.write(@control, "")
+        end
+      end
+
+      private
+
+      # @param seconds [Integer]
+      # @return [void]
+      def arm(seconds)
+        @deadline = @now.call + seconds
+        @fired = WARNINGS.map(&:first).select { |before| before >= seconds }
+        @phase = :calm
+      end
+    end
+  end
+end

data/lib/openlanes/execution/control.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OpenLanes
+  module Execution
+    # The side channel between a keypress and a running agent.
+    #
+    # `claude -p` takes no input once it starts, so the only way to reach an
+    # agent mid-flight is a file it has been told to poll: each invocation gets
+    # a control file of its own, named in its prompt, and a keypress writes a
+    # word into every file currently registered. Like everything else about the
+    # prompt this is a request — an agent deep in a tool call reads the file at
+    # its next step, not instantly — which is why {#quit!} also arms a deadline
+    # the {Executor} checks, so "quit" is eventually a guarantee too.
+    module Control
+      # What a keypress writes into a control file. One word, one line, so an
+      # agent can act on `File.read(path).strip` and nothing subtler.
+      WRAP_UP = "WRAP_UP"
+      STOP = "STOP"
+
+      # Ctrl-C: STOP, and the run will be started again, so the agent leaves
+      # a resume note before it goes. The prompt says what that note is.
+      INTERRUPT = "INTERRUPT"
+
+      # The clock's warnings start with this; the agent's prompt explains them.
+      WARN = "WARN"
+
+      # From the page, to one agent: stop at the next safe point, read the
+      # plan's mailbox, and wait there for the next message before going on.
+      # A person holds an agent to say something to it.
+      HOLD = "HOLD"
+
+      # The words a person may send one agent from the page, by command kind.
+      # There is no word for compacting: `/compact` is the caller's command,
+      # not one an agent can run on itself, so the harness stops the agent and
+      # compacts its session from outside (see {Executor::Handle#compact!}).
+      WORDS = { "hold" => HOLD, "wrap_up" => WRAP_UP, "stop" => STOP }.freeze
+
+      # Seconds between {#quit!} and the harness terminating whatever is still
+      # running. Long enough to write files and a handoff note; short enough
+      # that q means quit rather than "quit eventually".
+      GRACE = 60
+
+      @mutex = Mutex.new
+      @files = []
+      @quit = false
+      @interrupted = false
+      @deadline = nil
+
+      class << self
+        # Register a fresh control file for one invocation and hand back its
+        # path, to be named in the agent's prompt.
+        #
+        # @param dir [String] where the file lives (the trace dir — outside the
+        #   repository for the same reason traces are)
+        # @param name [String] something findable: plan ordinal and agent name
+        # @return [String]
+        def register(dir, name)
+          FileUtils.mkdir_p(dir)
+          path = File.join(dir, "control-#{name}-#{Process.pid}-#{format("%04x", rand(0x10000))}")
+          File.write(path, "")
+          @mutex.synchronize { @files << path }
+          path
+        end
+
+        # Forget a finished invocation's file. The file itself is removed so a
+        # crashed run does not leave stale STOPs for the next one to find.
+        #
+        # @param path [String]
+        # @return [void]
+        def release(path)
+          @mutex.synchronize { @files.delete(path) }
+          FileUtils.rm_f(path)
+        end
+
+        # One line into one file, from the clock. Not a broadcast: a warning is
+        # about one agent's own deadline.
+        #
+        # @param path [String]
+        # @param text [String]
+        # @return [void]
+        def write(path, text)
+          File.write(path, text.empty? ? "" : "#{text}\n")
+        rescue SystemCallError
+          # The invocation finished and released its file; nothing to warn.
+        end
+
+        # `w`: every running agent is asked to finish the essential remainder
+        # as fast as it can. The loop itself keeps going.
+        #
+        # @return [void]
+        def wrap_up! = broadcast(WRAP_UP)
+
+        # `n`: every running agent is asked to write out what it has and end
+        # its turn. The loop keeps going — under chaining that is exactly what
+        # hands the plan to the next agent.
+        #
+        # @return [void]
+        def stop! = broadcast(STOP)
+
+        # `q`: {#stop!}, plus the loop ends after this round, plus a deadline —
+        # {GRACE} seconds from now — after which the {Executor} aborts whatever
+        # is still running rather than waiting on its goodwill.
+        #
+        # @return [void]
+        def quit!
+          stop!
+          @mutex.synchronize {
+            @quit = true
+            @deadline ||= UI.monotonic + GRACE
+          }
+        end
+
+        # Ctrl-C, the first time: {#quit!}, except that every running agent is
+        # told the run is being interrupted rather than stopped, so it writes
+        # down where it got to. A restart then reads that note instead of
+        # redoing, or half-redoing, the work.
+        #
+        # @return [void]
+        def interrupt!
+          broadcast(INTERRUPT)
+          @mutex.synchronize {
+            @quit = true
+            @interrupted = true
+            @deadline ||= UI.monotonic + GRACE
+          }
+        end
+
+        # @return [Boolean] whether `q` has been pressed
+        def quit? = @mutex.synchronize { @quit }
+
+        # @return [Boolean] whether Ctrl-C has been pressed
+        def interrupted? = @mutex.synchronize { @interrupted }
+
+        # Ctrl-C: the graceful first press and the hard second.
+        #
+        # A trap handler may not take a mutex, so the first press hands
+        # {#interrupt!} to a thread; the second raises, as Ctrl-C always has.
+        #
+        # @param signals [Array<String>] each handled as Ctrl-C is; `openlanes
+        #   start` adds TERM, so a service manager's stop is as graceful
+        # @yieldreturn [Object]
+        # @return [Object] the block's value
+        def on_interrupt(signals = %w[INT])
+          previous = signals.to_h do |signal|
+            [signal, Signal.trap(signal) do
+              # A plain read, not {#interrupted?}: a trap handler may not lock.
+              raise Interrupt if @interrupted || @pending_interrupt
+
+              @pending_interrupt = true
+              Thread.new { interrupt! }
+            end]
+          end
+          yield
+        ensure
+          @pending_interrupt = false
+          previous&.each { |signal, handler| Signal.trap(signal, handler || "DEFAULT") }
+        end
+
+        # @return [Boolean] whether the grace period after `q` has run out
+        def overdue?
+          @mutex.synchronize { !@deadline.nil? && UI.monotonic > @deadline }
+        end
+
+        # Back to rest, for the next `Runner#call` — and for the suite, where
+        # one example's q must not quit every example after it.
+        #
+        # @return [void]
+        def reset!
+          @mutex.synchronize {
+            @files.each { |f| FileUtils.rm_f(f) }
+            @files.clear
+            @quit = false
+            @interrupted = false
+            @deadline = nil
+          }
+        end
+
+        private
+
+        # @param word [String]
+        # @return [void]
+        def broadcast(word)
+          @mutex.synchronize { @files.dup }.each do |path|
+            File.write(path, "#{word}\n")
+          rescue SystemCallError
+            # A file whose invocation just finished is not an error to miss.
+          end
+        end
+      end
+    end
+  end
+end