openlanes 3.0.1 → 3.1.0

data/lib/openlanes/engine/runner.rb

@@ -8,7 +8,8 @@ module OpenLanes
     # The loop itself is {Dispatcher}. This holds what the loop needs about
     # the run: the tree and its scope, the roster, the executor, how many run
     # at once, where each plan is checked out, and how a finished plan is
-    # published. Blocked plans (⭕️ 🅱️) are stepped around, never assigned.
+    # published. Blocked plans (⭕ 🛑 💣) are stepped around, never assigned,
+    # and while a 💣 stands nothing new is assigned at all (plan 009).
     class Runner
       # What one agent did to one plan.
       Attempt = Data.define(:ordinal,
@@ -33,7 +34,11 @@ module OpenLanes
       end
 
       # One unit of work: an agent, a plan, and the checkout it happens in.
-      Task = Data.define(:agent, :subject, :root, :checkout, :round) do
+      # `refresh` is what bringing the checkout up to date did, nil when
+      # nothing was tried (shared isolation, a dry run, a partner already in it).
+      Task = Data.define(:agent, :subject, :root, :checkout, :round, :refresh) do
+        def initialize(refresh: nil, **rest) = super
+
         # @return [Hash] columns for the log
         def log_fields
           { plan: subject.feature.ordinal.to_s, status: subject.status.to_s,
@@ -49,10 +54,24 @@ module OpenLanes
       #   other machines; nil when the run is not live, and every plan is ours
       # @param stay [Boolean] idle past fixed points until a person stops
       #   the run; see {Dispatcher#done?}
-      # @param rescan [Integer] seconds between rescans while idle
+      # @param rescan [Integer] ticks between rescans while idle
+      # @param watch [OpenLanes::Engine::PrWatch, nil] see {Dispatcher#initialize}
+      # @param ignore_bombs [Boolean] `--ignore-bombs`: a 💣 halts nothing
+      # @param aging_since [Date, nil] `plans.aging_since`, the floor of every
+      #   blocked plan's clock
+      # @param verification [OpenLanes::Engine::Verification::Driver, nil]
+      #   what a 🧪 plan is run through (plan 014); nil when the run publishes
+      #   nothing, and an approved plan then finishes at 👀
+      # @param journal [OpenLanes::Engine::EventJournal, nil] the progress
+      #   journal each engine event is appended to; nil keeps none
+      # @param merging [OpenLanes::Engine::Merging, nil] what a 🏁 plan's
+      #   pull requests go through once palpatine has ruled; nil when the
+      #   run publishes nothing
       def initialize(tree:, executor:, agents: Agents::Registry.new, isolation: :shared, jobs: 1, worktree: nil,
         plans: nil, publisher: nil, dry_run: false, rounds: nil, state: nil,
-        sleeper: ->(seconds) { sleep(seconds) }, on_board: nil, claims: nil, stay: false, rescan: Dispatcher::RESCAN)
+        sleeper: ->(seconds) { sleep(seconds) }, on_board: nil, claims: nil, stay: false, rescan: Dispatcher::RESCAN,
+        watch: nil, ignore_bombs: false, aging_since: nil, extensions: nil, verification: nil, journal: nil,
+        merging: nil)
         @tree = tree
         @executor = executor
         @agents = agents
@@ -68,6 +87,14 @@ module OpenLanes
         @claims = claims
         @stay = stay
         @rescan = rescan
+        @watch = watch
+        @ignore_bombs = ignore_bombs
+        @aging_since = aging_since
+        @extensions = extensions
+        @verification = verification
+        @journal = dry_run ? nil : journal
+        @merging = merging
+        @would_bomb = []
         @attempts = []
         @dropped = []
         @jobs = isolated? ? jobs : 1
@@ -75,6 +102,29 @@ module OpenLanes
 
       attr_reader :jobs, :worktree, :tree, :attempts, :executor, :agents
 
+      # @return [OpenLanes::Engine::Verification::Driver, nil]
+      attr_reader :verification
+
+      # @return [OpenLanes::Engine::Merging, nil]
+      attr_reader :merging
+
+      # A new concurrency limit, from the copilot's `/concurrency N`. Nothing
+      # running is stopped: the dispatcher fills only while fewer agents run
+      # than the limit, so a lower one takes effect as agents finish.
+      #
+      # @param count [Integer] at least 1
+      # @return [void]
+      # @raise [OpenLanes::Error] under `--isolation shared`, where every agent
+      #   works in one checkout and a second would write over the first
+      def jobs=(count)
+        raise OpenLanes::Error, "concurrency must be a whole number of at least 1, not #{count.inspect}" unless count.is_a?(Integer) && count >= 1
+        if !isolated? && count != 1
+          raise OpenLanes::Error, "this run is --isolation shared: one checkout, one agent at a time, so concurrency stays 1"
+        end
+
+        @jobs = count
+      end
+
       # @return [Boolean]
       def isolated? = @isolation == :worktree
 
@@ -104,6 +154,16 @@ module OpenLanes
       # @return [void]
       def drop_plan(ordinal) = @dropped |= [ordinal.to_s]
 
+      # @param ordinal [#to_s]
+      # @return [Boolean] whether {#drop_plan} took it out of this run
+      def dropped?(ordinal) = @dropped.include?(ordinal.to_s)
+
+      # Let another machine take the plan: a person stopped it here.
+      #
+      # @param ordinal [#to_s]
+      # @return [void]
+      def release(ordinal) = @claims&.release(ordinal)
+
       # @return [Array<OpenLanes::Plans::Subject>]
       def in_scope = tree.subjects.select { |s| in_scope?(s) }
 
@@ -132,20 +192,30 @@ module OpenLanes
         false
       end
 
-      # Take the plan before an agent starts on it. With Redis gone the run
-      # carries on unclaimed rather than stalling: the claim is an agreement
-      # between machines, and a machine that cannot reach the others is
-      # working alone.
+      # Take the plan before an agent starts on it. With Redis gone nothing
+      # new starts (W31): this machine cannot tell whether another one sharing
+      # the Redis already took the plan, and two machines building one spec is
+      # the collision the claim exists to prevent. Agents already running keep
+      # going. A run with no Redis at all has no claims and works alone.
       #
       # @param subject [OpenLanes::Plans::Subject]
       # @return [Boolean] whether this machine may work it
       def claim(subject)
-        @claims.nil? || @claims.claim(subject.feature.ordinal)
+        claimed = @claims.nil? || @claims.claim(subject.feature.ordinal)
+        @claims_down = nil
+        claimed
       rescue Live::Unavailable => e
         claims_unavailable(e)
-        true
+        false
       end
 
+      # Where the plan's checkout lives when the run isolates, whether or not
+      # it has been made.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [String, nil]
+      def checkout_path(subject) = isolated? ? worktree.path_for(subject.feature) : nil
+
       # Run until nothing is dispatchable, or, staying, until a person stops
       # it.
       #
@@ -159,13 +229,99 @@ module OpenLanes
           sleeper:  @sleeper,
           on_board: @on_board,
           stay:     @stay,
-          rescan:   @rescan)
+          rescan:   @rescan,
+          watch:      @watch,
+          extensions: @extensions,
+          journal:    @journal)
         yield dispatcher if block_given?
         @attempts = dispatcher.run
       end
 
       # @return [Array<OpenLanes::Plans::Subject>]
-      def blocked = in_scope.select { |s| %i[blocked product_blocked].include?(s.status.key) }
+      def blocked = in_scope.select { |s| Dispatcher::BLOCKED.include?(s.status.key) }
+
+      # Age the blocked plans in scope (plan 009): bomb the ones others wait
+      # on, defer the ones nobody does. A dry run fires nothing, and
+      # remembers what it would have bombed so it halts as a real run would.
+      #
+      # @param except [Array<String>] ordinals an agent or a drain is in
+      # @param now [Time]
+      # @return [OpenLanes::Lifecycle::Aging::Result]
+      def age!(except: [], now: Clock::System.now)
+        subjects = in_scope.reject { except.include?(it.feature.ordinal.to_s) || foreign?(it) }
+        result = Lifecycle.age(tree:, subjects:, since: @aging_since, now:, commit: !dry_run?)
+        @would_bomb = result.bombed if dry_run?
+        result
+      end
+
+      # Plans in scope that are 💣, or on a dry run would have become one.
+      #
+      # @return [Array<OpenLanes::Plans::Subject>]
+      def bombs
+        in_scope.select { it.status.key == :bomb || @would_bomb.include?(it.feature.ordinal.to_s) }
+      end
+
+      # The bombs that stop new work right now: none under `--ignore-bombs`,
+      # and none whose halt a person lifted from the page until it lapses.
+      #
+      # @param now [Time]
+      # @return [Array<OpenLanes::Plans::Subject>]
+      def halted_by(now: Clock::System.now)
+        return [] if @ignore_bombs
+
+        bombs.reject { Plans::PlanState.for(it.feature.path).resumed?(now:) }
+      end
+
+      # @return [Boolean] whether a 💣 keeps every new agent from starting
+      def halted? = !halted_by.empty?
+
+      # Plans in scope the dependency gate holds back, with the reason: a
+      # dependency that is not done yet, or a cycle that no order can break.
+      # A plan with no `depends_on:` key is never held, nor is one already
+      # parked, whose own state says more than its dependencies do.
+      #
+      # @param deps [OpenLanes::Plans::Dependencies] the graph to ask; the
+      #   dispatcher passes the one it gated with, so both say the same thing
+      # @return [Hash{String => String}] ordinal => "waiting on 034.00" or "cycle: ..."
+      def held(deps = dependencies)
+        in_scope.each_with_object({}) do |subject, out|
+          next if Plans::StateMachine::SETTLED.include?(subject.status.key)
+
+          ordinal = subject.feature.ordinal.to_s
+          reason = deps.reason(ordinal) and out[ordinal] = reason
+        end
+      end
+
+      # The dependency graph judged by the states this run acts on. A real run
+      # has reconciled every folder name before it asks, so the names are the
+      # states. A dry run renames nothing, so it judges each plan by the state
+      # reconciliation would give it, as {Dispatcher} does when it picks an
+      # agent; otherwise an In Review prerequisite whose pull requests have
+      # all merged would read as done to one and open to the other.
+      #
+      # @param except [Array<String>] ordinals reconciliation leaves alone
+      #   (an agent is in them), judged by their folder's name; plans another
+      #   machine holds are always left alone
+      # @return [OpenLanes::Plans::Dependencies]
+      def dependencies(except: [])
+        return tree.dependencies unless dry_run?
+
+        leave = except.map(&:to_s)
+        # Every plan, archived ones included, as {Plans::Tree#dependencies}
+        # does: a shipped prerequisite sits in `archive/`.
+        Plans::Dependencies.new(tree.everything,
+          status_of: lambda { |subject|
+            untouched = leave.include?(subject.feature.ordinal.to_s) || foreign?(subject)
+            untouched ? subject.status : effective_status(subject)
+          })
+      end
+
+      # The state a plan's contents justify, which reconciliation would rename
+      # its folder to: its lane's skip first, then what `resync dirs` reads.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [OpenLanes::Plans::Status]
+      def effective_status(subject) = Lifecycle::Lanes.target(subject) || Lifecycle::Resync::Dirs.target(subject)
 
       # @return [Boolean]
       def settled? = in_scope.all? { |s| Plans::StateMachine::SETTLED.include?(s.status.key) }
@@ -176,12 +332,20 @@ module OpenLanes
       # is the one checked out where the run was typed, which is where a dry
       # run of that plan is typed.
       #
+      # A worktree is brought up to date with the default branch first (see
+      # {Vcs::Refresh}), here rather than on the agent's thread, so no partner
+      # can start in the same checkout while git is rewriting it.
+      #
+      # @param refresh [Boolean] false when another agent is already working
+      #   in the plan's checkout, which must not move under it
+      # @param hold [String, nil] see {Vcs::Refresh#call}
       # @return [OpenLanes::Engine::Runner::Task]
-      def prepare(agent, subject, round)
+      def prepare(agent, subject, round, refresh: true, hold: nil)
         return Task.new(agent:, subject:, root: shared_root, checkout: nil, round:) if !isolated? || dry_run?
 
         checkout = worktree.checkout_for(subject.feature)
-        Task.new(agent:, subject:, root: checkout.path, checkout:, round:)
+        outcome = worktree.refresh(checkout, hold:) if refresh
+        Task.new(agent:, subject:, root: checkout.path, checkout:, round:, refresh: outcome)
       end
 
       # Push a finished build and record the pull request it opened in the
@@ -208,7 +372,14 @@ module OpenLanes
 
       # @param error [OpenLanes::Live::Unavailable]
       # @return [void]
-      def claims_unavailable(error) = UI.log("claims unchecked: #{error.message}")
+      # Said once per outage: every plan asks on every tick, and the same
+      # line a hundred times buries the moment Redis went away.
+      def claims_unavailable(error)
+        return if @claims_down == error.message
+
+        @claims_down = error.message
+        UI.log("claims unchecked, starting nothing new until Redis answers: #{error.message}", level: :warn)
+      end
 
       # @return [void]
       def record_pull_request(path, publication)

data/lib/openlanes/engine/start_workflow.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Engine
+    # `openlanes start` without the command: {RunWorkflow} as a long-lived
+    # service. It stays up past every fixed point, rescanning the tree, and
+    # treats a missing live board or control room as a refusal rather than a
+    # reason to go on headless, since the page is the only way in.
+    class StartWorkflow < RunWorkflow
+      # Exit status when Redis or the control room is not there to serve.
+      UNAVAILABLE = 69
+
+      # @param rescan [Integer] seconds between rescans of .plans while idle
+      # @param options [Hash] as for {RunWorkflow#initialize}
+      def initialize(rescan:, **)
+        super(**)
+        @rescan = rescan
+      end
+
+      private
+
+      # Always stays, at the rescan asked for, and watches the pull requests
+      # a person merges the way a staying `run` does. `--rescan` is seconds
+      # and the dispatcher counts ticks, so a 5 passed through unconverted
+      # would rescan every 2.5 s.
+      #
+      # @param _web [OpenLanes::Web::Launcher]
+      # @return [Hash]
+      def staying(_web, _live = nil) = { stay: true, rescan: Dispatcher.ticks(@rescan), watch: watch }
+
+      # @param message [String]
+      # @return [Dry::Monads::Result::Failure]
+      def without_live(message)
+        refusal("#{message}\n\nopenlanes start needs Redis: its control room is the only way to answer the " \
+                "agents' questions. Start redis-server, or pass --redis-url. " \
+                "`openlanes run` goes on without it, headless.",
+          UNAVAILABLE)
+      end
+
+      # @param web [OpenLanes::Web::Launcher]
+      # @param live [OpenLanes::Live::Session]
+      # @return [Dry::Monads::Result::Failure]
+      def without_web(web, live)
+        live.close
+        refusal("The control room did not answer on #{web.url}, and openlanes start is no use without it. " \
+                "Its log: #{web.log}",
+          UNAVAILABLE)
+      end
+
+      # A project with nothing left to do opens on the idea dialog (W19).
+      #
+      # @param web [OpenLanes::Web::Launcher]
+      # @return [String]
+      def browser_url(web)
+        open = @tree.subjects.reject { Dispatcher::FINISHED.include?(it.status.key) }
+        open.empty? ? "#{web.url}#start" : web.url
+      end
+
+      # What the service did, and exit 0: stopping it on purpose is not a
+      # failure, and the failed attempts it lived through are listed above
+      # the box.
+      #
+      # @return [Integer] 0
+      def finish(runner, attempts, seconds:)
+        puts_report(attempts, Engine.tally(attempts:, seconds:).render)
+        unless @quiet
+          blocked = runner.blocked.map { it.feature.ordinal }
+          lines = ["Stopped. Unfinished plans keep their state; openlanes start picks them up again."]
+          lines << "Still waiting for answers: #{blocked.join(", ")}" unless blocked.empty?
+          success("#{attempts.size} invocation#{"s" unless attempts.size == 1}, " \
+                  "#{attempts.count(&:advanced?)} advanced\n\n#{lines.join("\n")}")
+        end
+        0
+      end
+    end
+  end
+end

data/lib/openlanes/engine/state_file.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "json"
+require "socket"
 
 module OpenLanes
   module Engine
@@ -11,58 +12,72 @@ module OpenLanes
     # The ledger inside each document is the record humans read and the
     # dispatcher acts on; this is the index of it, plus what the ledger cannot
     # hold: which run wrote what, process ids, tokens, and whether the run
-    # that wrote a `Started` is still alive. It sits in `.plans/` rather than
-    # the system temp dir because a reboot must not lose it, and it is
-    # gitignored because it is about one machine's run, not the plan.
+    # that wrote a `Started` is still alive. It sits in the runtime state
+    # directory ({OpenLanes::Runtime}) rather than the system temp dir because
+    # a reboot must not lose it, and outside `.plans/` because it is about one
+    # machine's run, not the plan: in `.plans/` every `git status` and every
+    # snapshot of the tree had to learn to ignore it.
     class StateFile
       FILENAME = "openlanes-state.json"
 
-      # Where it used to live, one directory down. Read by {#load} when the
-      # current path holds nothing, so a run started under the old layout is
-      # picked up rather than silently restarted from zero. Nothing writes
-      # here any more and nothing deletes it: the file left behind is the
-      # only record a half-finished run has.
+      # The oldest place it lived, under `.plans/tmp/`. Read by {#load} after
+      # `.plans/` itself, so a run started under either old layout is picked
+      # up rather than silently restarted from zero. Nothing writes to either
+      # any more and nothing deletes them: the file left behind is the only
+      # record a half-finished run has.
       LEGACY_DIRNAME = "tmp"
 
-      # The lines {.ensure_ignored!} adds. The second covers the sibling
-      # {#save} writes and renames over the first — brief, but `.plans/` is a
-      # directory whose other contents are committed, so a `git status` run
-      # during that instant must not offer it.
-      IGNORE = ["#{OpenLanes::PLANS_DIR}/#{FILENAME}", "#{OpenLanes::PLANS_DIR}/#{FILENAME}.*.tmp"].freeze
+      # The line {.ensure_ignored!} adds: the `<name>.<pid>.tmp` siblings
+      # `state.json` and `blocked.md` are written to and renamed over, inside
+      # plan folders whose other contents are committed. Brief, but a
+      # `git status` during that instant must not offer one.
+      IGNORE = ["#{OpenLanes::PLANS_DIR}/**/*.tmp"].freeze
+
+      # A literal path git can be asked about for the {IGNORE} line.
+      PROBE = "#{OpenLanes::PLANS_DIR}/000.00/state.json.1.2.tmp".freeze
 
       # @param tree [OpenLanes::Plans::Tree]
-      # @return [String]
-      def self.for(tree) = File.join(tree.dir, FILENAME)
+      # @return [String] in the runtime state directory, keyed by the tree's root
+      def self.for(tree) = Runtime.state_file(root: File.dirname(File.expand_path(tree.dir)))
 
       # @param tree [OpenLanes::Plans::Tree]
-      # @return [String] where {LEGACY_DIRNAME} put it
-      def self.legacy_for(tree) = File.join(tree.dir, LEGACY_DIRNAME, FILENAME)
+      # @return [Array<String>] where older releases wrote it, newest first
+      def self.legacy_for(tree) = [File.join(tree.dir, FILENAME), File.join(tree.dir, LEGACY_DIRNAME, FILENAME)]
 
-      # Add the ignore lines once. Editing somebody's `.gitignore` is a thing
-      # to announce, which is why this returns whether it did.
-      #
-      # Only the first line is asked about: git answers for a literal path,
-      # and the second is a glob no path equals. They are written together,
-      # so one being ignored means both are.
+      # Add the ignore line once. Editing somebody's `.gitignore` is a thing
+      # to announce, which is why this returns whether it did. Lines an older
+      # release wrote are left where they are: removing a line is editing
+      # something this method did not write.
       #
       # @param root [String] repository root
       # @return [Boolean] true when lines were added
       def self.ensure_ignored!(root)
         return false unless system("git", "-C", root, "rev-parse", "--git-dir", out: File::NULL, err: File::NULL)
-        return false if system("git", "-C", root, "check-ignore", "-q", IGNORE.first, out: File::NULL, err: File::NULL)
+
+        missing = ignored?(root, PROBE) ? [] : IGNORE
+        return false if missing.empty?
 
         path = File.join(root, ".gitignore")
         existing = File.file?(path) ? File.read(path) : ""
         glue = existing.empty? || existing.end_with?("\n") ? "" : "\n"
-        File.write(path, "#{existing}#{glue}#{IGNORE.join("\n")}\n")
+        File.write(path, "#{existing}#{glue}#{missing.join("\n")}\n")
         true
       end
 
+      # @param root [String]
+      # @param path [String] relative to +root+
+      # @return [Boolean]
+      def self.ignored?(root, path) = system("git", "-C", root, "check-ignore", "-q", path, out: File::NULL, err: File::NULL)
+      private_class_method :ignored?
+
       # @param path [String]
       # @param pid [Integer] this run's process id
-      def initialize(path:, pid: Process.pid)
+      # @param legacy [Array<String>, nil] older locations {#load} falls back
+      #   to; by default the two beside and under +path+'s directory
+      def initialize(path:, pid: Process.pid, legacy: nil)
         @path = path
         @pid = pid
+        @legacy = legacy
         @data = { "run" => {}, "plans" => {} }
         @mutex = Mutex.new
       end
@@ -70,11 +85,11 @@ module OpenLanes
       # @return [String]
       attr_reader :path
 
-      # Where a run started before the file moved up out of {LEGACY_DIRNAME}
-      # would have written. {#load} falls back to it; {#save} never uses it.
+      # Where a run started under an older layout would have written.
+      # {#load} falls back to them in order; {#save} never uses them.
       #
-      # @return [String]
-      def legacy_path = File.join(File.dirname(path), LEGACY_DIRNAME, File.basename(path))
+      # @return [Array<String>]
+      def legacy_paths = @legacy || [File.join(File.dirname(path), LEGACY_DIRNAME, File.basename(path))]
 
       # Reads the current path, or the legacy one when the current path holds
       # nothing. A run interrupted under the old layout is otherwise invisible
@@ -84,7 +99,7 @@ module OpenLanes
       # @return [self]
       def load
         @mutex.synchronize do
-          source = [path, legacy_path].find { |candidate| File.file?(candidate) }
+          source = [path, *legacy_paths].find { |candidate| File.file?(candidate) }
           @data = JSON.parse(File.read(source)) if source
           @data = { "run" => {}, "plans" => {} } unless @data.is_a?(Hash) && @data["plans"].is_a?(Hash)
         end
@@ -106,18 +121,24 @@ module OpenLanes
         end
       end
 
+      # Also forgets the previous run's `waiting_on`. A live pid only says some
+      # run is up, not that it watches: a plain `run`, or one with `merge.by:
+      # auto`, never writes the map, so the last watch's entries would read as
+      # current for as long as this run lasted.
+      #
       # @param root [String]
       # @return [void]
       def begin_run!(root:)
         @mutex.synchronize do
-          @data["run"] = { "pid" => @pid, "root" => root, "started_at" => Time.now.iso8601,
-                          "heartbeat_at" => Time.now.iso8601 }
+          @data.delete("waiting_on")
+          @data["run"] = { "pid" => @pid, "host" => Socket.gethostname, "root" => root,
+                          "started_at" => Clock::System.now.iso8601, "heartbeat_at" => Clock::System.now.iso8601 }
         end
       end
 
       # @return [void]
       def heartbeat!
-        @mutex.synchronize { @data["run"]["heartbeat_at"] = Time.now.iso8601 }
+        @mutex.synchronize { @data["run"]["heartbeat_at"] = Clock::System.now.iso8601 }
       end
 
       # @param ordinal [String]
@@ -152,6 +173,42 @@ module OpenLanes
         @mutex.synchronize { @data["live"] = data }
       end
 
+      # The Redis outage under way (W32): when it began, when the agents were
+      # paused, how many times Redis was asked since. Nil when there is none.
+      #
+      # @return [Hash, nil]
+      def outage = @mutex.synchronize { @data["outage"]&.dup }
+
+      # @param record [Hash, nil] written by the next {#save}
+      # @return [void]
+      def outage=(record)
+        @mutex.synchronize { record ? @data["outage"] = record : @data.delete("outage") }
+      end
+
+      # Outages that ended, resumed or given up on, oldest first.
+      #
+      # @return [Array<Hash>]
+      def outages = @mutex.synchronize { (@data["outages"] || []).map(&:dup) }
+
+      # @param records [Array<Hash>]
+      # @return [void]
+      def outages=(records)
+        @mutex.synchronize { @data["outages"] = records }
+      end
+
+      # Pull requests open and waiting on a person, by plan, as the
+      # human-mode watch last saw them. Here so `openlanes list-plans`, a
+      # process of its own, can say who owes what while the engine runs.
+      #
+      # @return [Hash{String => Array<Integer>}]
+      def waiting_on = @mutex.synchronize { (@data["waiting_on"] || {}).transform_values(&:dup) }
+
+      # @param data [Hash{String => Array<Integer>}] written by the next {#save}
+      # @return [void]
+      def waiting_on=(data)
+        @mutex.synchronize { @data["waiting_on"] = data.transform_keys(&:to_s) }
+      end
+
       # @param ordinal [String]
       # @return [Array<Hash>]
       def stages(ordinal) = @mutex.synchronize { (@data.dig("plans", ordinal.to_s, "stages") || []).map(&:dup) }
@@ -159,11 +216,21 @@ module OpenLanes
       # @return [Array<String>] every ordinal with a stage recorded
       def plans = @mutex.synchronize { @data["plans"].keys }
 
+      # @return [Boolean] whether a run wrote this file and is still alive
+      def running? = !@data.dig("run", "pid").nil? && !previous_run_dead?
+
+      # A run recorded on another host is never provably dead: its pid names
+      # a process on a machine this one cannot see. A record with no `host`
+      # predates the field and keeps the local check.
+      #
       # @return [Boolean] whether the run that last wrote this file is gone
       def previous_run_dead?
         previous = @data.dig("run", "pid")
         return false if previous.nil? || previous == @pid
 
+        host = @data.dig("run", "host")
+        return false if host && host != Socket.gethostname
+
         Process.kill(0, previous)
         false
       rescue Errno::ESRCH, Errno::EPERM

data/lib/openlanes/engine/tally.rb

@@ -4,7 +4,7 @@ module OpenLanes
   module Engine
     # What a `run` cost, once it is over.
     #
-    # The loop reports movement — which plan went from ⭐️ to 🟡, which agent
+    # The loop reports movement — which plan went from ⭐ to 🟡, which agent
     # failed and why — and says nothing about the bill. A round of five agents
     # against a large repository spends several million tokens and the better
     # part of an hour, and until this existed the only record of that was a