openlanes 3.0.1 → 3.1.0

data/lib/openlanes/plans/plan_state.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "fileutils"
 require "json"
+require "securerandom"
 require "socket"
 require "time"
 require "tmpdir"
@@ -22,6 +23,8 @@ module OpenLanes
     #   messages    the agents, through `openlanes mail send`: what a pair
     #               says to each other, and the RESUME notes an interrupted
     #               agent leaves for its successor
+    #   memory      the harness again: each agent's journal (M2), the lines
+    #               it printed as it worked, with the answers to its questions
     #
     # A stage still Started whose harness process is gone is a crash, which is
     # how a restarted run finds what it has to resume.
@@ -104,38 +107,216 @@ module OpenLanes
       # @return [String, nil]
       def state = read["state"]
 
+      # Until when a 💣 on this plan does not halt the run: "Resume anyway
+      # for 24 h" from the control room. Kept here, not in `.openlanes.yml`,
+      # so it lapses on its own and nobody has to remember to take it out.
+      #
+      # @return [Time, nil]
+      def resume_until
+        text = read["resume_until"] or return nil
+        parse_time(text)
+      end
+
+      # @param now [Time]
+      # @return [Boolean] whether a halt on this plan is lifted right now
+      def resumed?(now: Time.now) = (resume_until || now) > now
+
+      # @param till [Time] when the halt comes back
+      # @return [Time] as written
+      def resume_anyway!(till:)
+        update { |data| data["resume_until"] = till.iso8601 }
+        till
+      end
+
+      # ---- finished ---------------------------------------------------------
+
+      # How a plan finished: hansolo approved it, or its pull request merged.
+      FINISH_KINDS = %w[approved merged].freeze
+
+      # When and how a plan finished, which the control room keeps on the
+      # board for the rest of the run (and a restarted engine carries the
+      # latest one over). Kept here because nothing else records the moment:
+      # the folder name says ✅ but not since when, and `pull-requests.md`
+      # has no times at all.
+      #
+      # @!attribute [r] kind
+      #   @return [String] one of {FINISH_KINDS}
+      # @!attribute [r] at
+      #   @return [Time]
+      Finished = Data.define(:kind, :at) do
+        # @return [Boolean]
+        def merged? = kind == "merged"
+
+        # @return [Hash] as `state.json` and the snapshot carry it
+        def to_json_h = { "kind" => kind, "at" => at.utc.iso8601 }
+      end
+
+      # @return [OpenLanes::Plans::PlanState::Finished, nil]
+      def finished
+        record = read["finished"] or return nil
+        Finished.new(kind: record["kind"], at: parse_time(record["at"]))
+      end
+
+      # Record that the plan finished. A merge replaces an approval; nothing
+      # replaces a merge, so the watch, which reports the same merged pull
+      # request on every poll, keeps the time of the first report and writes
+      # nothing after it. A second approval, after a rejection and a rebuild,
+      # is a new approval and takes its own time.
+      #
+      # @param kind [String] one of {FINISH_KINDS}
+      # @param at [Time]
+      # @return [OpenLanes::Plans::PlanState::Finished] the record kept
+      # @raise [OpenLanes::Error] for a kind outside {FINISH_KINDS}
+      def finish!(kind, at: Time.now)
+        kind = kind.to_s
+        raise Error, "a plan finishes #{FINISH_KINDS.join(" or ")}, not #{kind.inspect}" unless FINISH_KINDS.include?(kind)
+
+        current = finished
+        return current if current&.merged?
+
+        kept = Finished.new(kind:, at:)
+        update do |data|
+          existing = data["finished"]
+          if existing && existing["kind"] == "merged"
+            kept = Finished.new(kind: "merged", at: parse_time(existing["at"]))
+          else
+            data["finished"] = kept.to_json_h
+          end
+        end
+        kept
+      end
+
+      # Forget that the plan finished: an agent is working on it again, or a
+      # person rejected what was approved. Writes nothing when there was
+      # nothing to forget.
+      #
+      # @return [void]
+      def unfinish!
+        return unless read.key?("finished")
+
+        update { |data| data.delete("finished") }
+      end
+
       # ---- the harness --------------------------------------------------------
 
-      # Record or update one agent's round. A second call for the same agent
-      # and round updates the first, so a round is one record from dispatch
-      # to settlement.
+      # Record or update one agent's round. A later call for the same agent
+      # and round updates the latest record of it, so a round is one record
+      # from dispatch to settlement.
+      #
+      # A new dispatch passes +reset+, which appends a record rather than
+      # finding one: rounds are numbered per state and per run, so round 1 of
+      # a later run shares its number with round 1 of an earlier one. Merging
+      # into the earlier record would carry its session, checkout and outcome
+      # into a round that has none of them yet, and replacing it would lose
+      # that round from `openlanes state show`. Appending keeps both, in
+      # dispatch order, which {#resumption} relies on when two rounds started
+      # in the same second.
       #
       # @param agent [String]
       # @param round [Integer]
+      # @param reset [Boolean] start a new record rather than update one
       # @param fields [Hash] status, started_at, finished_at, adapter, model,
-      #   effort, up, down, seconds, note, to, run
+      #   effort, up, down, seconds, note, to, session, cwd; `run` only in files older releases wrote
       # @return [Hash] the stage as written
-      def stage!(agent:, round:, **fields)
+      def stage!(agent:, round:, reset: false, **fields)
         stage = nil
         update do |data|
-          stage = data["stages"].find { |s| s["agent"] == agent && s["round"] == round }
+          stage = data["stages"].rfind { |s| s["agent"] == agent && s["round"] == round } unless reset
           unless stage
             stage = { "agent" => agent, "round" => round }
             data["stages"] << stage
           end
           stage.merge!(fields.transform_keys(&:to_s).compact)
+          # A settling round notes how often the plan had moved by then, in
+          # the same write, so {#resumption} sees a move no stage recorded.
+          stage["moves"] = data["moves"].to_i if fields.key?(:to)
         end
         stage
       end
 
+      # Whether one agent's next round may carry on the session its last one
+      # ran in (M1), and if not, why not. Asked before the new round's own
+      # stage is written, so the answer is about the rounds before it.
+      #
+      # The latest stage of +agent+ that names a session is the candidate. It
+      # is resumable only when it settled leaving the plan in +state+, no
+      # stage started after it moved the plan anywhere else, and it ran in
+      # +root+: `claude` keeps its sessions per working directory, so an id
+      # recorded in a worktree is not found from the main checkout. The
+      # candidate's own `from` is not compared, because an agent that
+      # `starts_as` renames the folder on dispatch: its first round leaves
+      # from Planned and works in Building, and its second leaves from
+      # Building.
+      #
+      # A move no agent made, such as `resync dirs` or a person through
+      # the CLI, records no stage, so {#state!} counts every move in `moves`
+      # and a settling stage notes the count it saw: a count that has grown
+      # since means the plan went away and came back. A folder renamed by
+      # hand, outside openlanes, is not counted.
+      #
+      # A round that ends Blocked starts the next one fresh, after the
+      # person answers: the plan went to Blocked and back. That is the case
+      # where the earlier context would help most, and it is deliberately
+      # conservative for now; the answer reaches the agent through
+      # blocked.md either way.
+      #
+      # @param agent [String]
+      # @param state [#to_s] the state key the plan is in now
+      # @param root [String] the checkout the new round will run in
+      # @return [OpenLanes::Plans::PlanState::Resumption]
+      def resumption(agent:, state:, root:)
+        data = read
+        all = data["stages"]
+        # `started_at` has second precision, so two rounds can tie on it; the
+        # one dispatched later sits later in the array.
+        last, = all.each_with_index
+                   .select { |s, _| s["agent"] == agent && !s["session"].to_s.empty? }
+                   .max_by { |s, i| [started(s), i] }
+        return Resumption.new(session: nil, reason: "no session recorded for #{agent}") unless last
+
+        session = last["session"]
+        state = state.to_s
+        reason = if last["to"].to_s.empty?
+                   "round #{last["round"]} (#{session}) never settled"
+                 elsif last["to"] != state
+                   "the plan moved to #{last["to"]} after round #{last["round"]} (#{session})"
+                 elsif (moved = moved_since(all, last, state))
+                   "the plan moved to #{moved} since round #{last["round"]} (#{session})"
+                 elsif last.key?("moves") && data["moves"].to_i != last["moves"]
+                   "the plan moved away and back since round #{last["round"]} (#{session})"
+                 elsif File.expand_path(last["cwd"].to_s) != File.expand_path(root) || last["cwd"].to_s.empty?
+                   "session #{session} ran in #{last["cwd"] || "an unrecorded checkout"}, not #{root}"
+                 end
+        Resumption.new(session: reason ? nil : session, reason: reason || "round #{last["round"]} left it in #{state}")
+      end
+
+      # What {#resumption} decided.
+      #
+      # @!attribute [r] session
+      #   @return [String, nil] the id to resume, nil to start fresh
+      # @!attribute [r] reason
+      #   @return [String] why, for the log
+      Resumption = Data.define(:session, :reason) do
+        # @return [Boolean]
+        def resume? = !session.nil?
+      end
+
       # @param key [Symbol, String] the state the folder was just moved to
       # @return [void]
       def state!(key)
-        update { |data| data["state"] = key.to_s }
+        update do |data|
+          data["moves"] = data["moves"].to_i + 1 unless data["state"] == key.to_s
+          data["state"] = key.to_s
+        end
       end
 
+      # @return [Integer] how many times {#state!} has moved the plan
+      def moves = read["moves"].to_i
+
       # Stages a dead harness left Started. Nobody is working them, and nobody
-      # will finish them unless a run picks them up.
+      # will finish them unless a run picks them up. Only a stage an older
+      # release wrote carries `run`; newer ones leave it to the run's
+      # {Engine::StateFile}, so they are never reported here.
       #
       # @param alive [Proc] pid → Boolean
       # @param pid [Integer] this run, which is never its own crash
@@ -192,13 +373,385 @@ module OpenLanes
           next if message
 
           number = [data["messages"].map { |m| m["number"] }.max.to_i, after].max + 1
-          message = { "number" => number, "at" => at.iso8601, "from" => from, "to" => to, "body" => body }
+          # The id, not the number, is what a drain dedupes on: a worktree's
+          # copy of this file numbers its messages independently of the main
+          # checkout's, so two different messages can both be #4.
+          message = { "id" => SecureRandom.uuid, "number" => number, "at" => at.iso8601, "from" => from, "to" => to,
+                      "body" => body, "read" => "no" }
           message["command"] = command if command
           data["messages"] << message
         end
         message
       end
 
+      # Keep a message that arrived with its number already given, as one
+      # drained from Redis does (B4).
+      #
+      # A message is the same message when its id matches, or, when either
+      # side was written before ids existed, when sender, recipient, time and
+      # body all match. Never by number alone: `mail send` in a worktree
+      # numbers against the worktree's `state.json`, the main checkout
+      # numbers against its own, and both can hand out #4. Deduping on the
+      # number dropped the second #4 as a "duplicate" without a word.
+      #
+      # So the usual case, `mail send` having already written here before it
+      # published, writes nothing at all and the file's mtime stays; and a
+      # different message whose number is taken is kept under the next free
+      # one.
+      #
+      # @param message [Hash] as {#message!} writes it, string keys
+      # @param reserved [Array<Integer>] numbers taken outside this file,
+      #   i.e. by mailbox.md
+      # @return [Hash, nil] the message as written, nil when it was here
+      def deliver!(message, reserved: [])
+        return nil if messages.any? { |m| same_message?(m, message) }
+
+        delivered = nil
+        update do |data|
+          next if data["messages"].any? { |m| same_message?(m, message) }
+
+          taken = data["messages"].map { |m| m["number"].to_i } + reserved
+          number = taken.include?(message["number"]) ? taken.max + 1 : message["number"]
+          # Unread whatever it arrived saying: only `mail ack` in this file
+          # says its reader read it.
+          delivered = message.slice("id", "number", "at", "from", "to", "body", "command")
+                             .merge("number" => number, "read" => "no")
+          data["messages"] << delivered
+          data["messages"].sort_by! { |m| m["number"].to_i }
+        end
+        delivered
+      end
+
+      # Mark one message read, under the lock, so an ack and a send in the
+      # same second cannot lose each other. Only its recipient may ack it:
+      # `read` says the reader read it, not that somebody did.
+      #
+      # @param number [Integer]
+      # @param by [String] the agent acking, who must be the recipient
+      # @return [Hash, nil] the message as written, nil when there is no
+      #   such number
+      # @raise [OpenLanes::Error] when +by+ is not the recipient
+      def ack!(number, by:)
+        message = nil
+        update do |data|
+          message = data["messages"].find { |m| m["number"] == number }
+          next unless message
+          raise Error, "message ##{number} is for #{message["to"]}, not #{by}" unless message["to"] == by
+
+          message["read"] = "yes"
+        end
+        message
+      end
+
+      # ---- conversions ------------------------------------------------------
+
+      # Questions the engine rewrote into lettered choices (D9), and the ones
+      # it tried and could not. `blocked.md` keeps only the rewrite, so the
+      # words the agent wrote live here, beside the digest that keeps a
+      # restarted run from asking the model about the same text again.
+      #
+      # @return [Array<Hash>] oldest first; empty for a plan never converted
+      def conversions = read["conversions"] || []
+
+      # @param digest [String] SHA256 of the question's body as the agent wrote it
+      # @return [Boolean] whether that text was converted, or failed to be
+      def converted?(digest) = conversions.any? { it["digest"] == digest }
+
+      # @param question [Integer] the `n` of `## Bn`
+      # @param digest [String] SHA256 of +original+
+      # @param original [String] the body before the rewrite
+      # @param model [String] the model asked
+      # @param outcome [String] "converted" or "rejected"
+      # @param note [String, nil] why it was rejected
+      # @param at [Time]
+      # @return [Hash] the record as written
+      def conversion!(question:, digest:, original:, model:, outcome:, note: nil, at: Time.now)
+        record = { "question" => Integer(question), "digest" => digest, "original" => original, "at" => at.iso8601,
+                   "model" => model, "outcome" => outcome, "note" => note }.compact
+        update { |data| (data["conversions"] ||= []) << record }
+        record
+      end
+
+      # ---- extensions -------------------------------------------------------
+
+      # The harness asking a person for more time or another round for one
+      # agent (E1), and how each request was answered. Kept here rather than
+      # in the run's memory, so a grant survives a restart and an answer can
+      # come from any control room, after the run that asked is gone.
+      #
+      # @return [Array<Hash>] oldest first; empty for a plan that never asked
+      def extensions = read["extensions"] || []
+
+      # @param agent [String]
+      # @param state [String] the plan state the agent was working, a {Status} key
+      # @param round [Integer]
+      # @param limit [String] "time" or "rounds", whichever ran out
+      # @param at [Time]
+      # @return [Hash] the request as written, with its `number`
+      def ask_extension!(agent:, state:, round:, limit:, at: Time.now)
+        record = nil
+        update do |data|
+          all = (data["extensions"] ||= [])
+          record = { "number" => (all.map { it["number"] }.max || 0) + 1, "agent" => agent, "state" => state.to_s,
+                     "round" => Integer(round), "limit" => limit, "asked_at" => at.iso8601 }
+          all << record
+        end
+        record
+      end
+
+      # Answer a request, or close it unanswered. Once settled it stays
+      # settled: a second answer, from another page or a replayed command,
+      # changes nothing.
+      #
+      # @param number [Integer]
+      # @param fields [Hash{String => Object}] `answer`, `by`, `grant`, `seconds`, `closed`
+      # @param at [Time]
+      # @return [Hash, nil] the request as settled; nil when there is no such
+      #   request, or when it was settled already
+      def settle_extension!(number, at: Time.now, **fields)
+        settled = nil
+        update do |data|
+          found = (data["extensions"] || []).find { it["number"] == Integer(number) } or next
+          next if found.key?("settled_at")
+
+          settled = found.merge!(fields.transform_keys(&:to_s).compact, "settled_at" => at.iso8601)
+        end
+        settled
+      end
+
+      # Correct how a settled request was granted, when the grant could not
+      # be given as settled: time for a clock that had already stopped.
+      #
+      # @param number [Integer]
+      # @param fields [Hash{String => Object}]
+      # @return [Hash, nil] the request as it now stands
+      def amend_extension!(number, **fields)
+        amended = nil
+        update do |data|
+          amended = (data["extensions"] || []).find { it["number"] == Integer(number) }&.merge!(fields.transform_keys(&:to_s))
+        end
+        amended
+      end
+
+      # R4's question, when this plan is the one that asked it.
+      #
+      # @return [Hash, nil] `asked_at`, and once answered `answer`, `by`, `settled_at`
+      def quality_ask = read["quality_ask"]
+
+      # Record that this plan asked R4's question. Asking twice changes
+      # nothing, so a hand-off repeated every tick keeps its first moment.
+      #
+      # @param at [Time]
+      # @return [Hash] the ask as it stands
+      def ask_quality!(at: Time.now)
+        update { |data| data["quality_ask"] ||= { "asked_at" => at.iso8601 } }
+        quality_ask
+      end
+
+      # @param answer [String] "high" or "mvp"
+      # @param by [String]
+      # @param at [Time]
+      # @return [Hash, nil] the ask as settled; nil when none is open
+      def settle_quality_ask!(answer:, by:, at: Time.now)
+        settled = nil
+        update do |data|
+          ask = data["quality_ask"]
+          next if ask.nil? || ask.key?("settled_at")
+
+          settled = ask.merge!("answer" => answer.to_s, "by" => by, "settled_at" => at.iso8601)
+        end
+        settled
+      end
+
+      # Mark a granted round's extra seconds as given to the round that ran on them.
+      #
+      # @param number [Integer]
+      # @return [void]
+      def spend_extension!(number)
+        update { |data| (data["extensions"] || []).find { it["number"] == Integer(number) }&.store("spent", true) }
+      end
+
+      # ---- merge risk ---------------------------------------------------------
+
+      # palpatine's verdicts for this visit to 🏁 (P1, P4), keyed by pull
+      # request number, plus the moments the engine rebased a sibling (P5).
+      # A visit is told apart by {#moves}: a plan sent back to 🔴 and
+      # brought to 🏁 again has moved since, so its old verdicts no longer
+      # stand and palpatine weighs the new code.
+      #
+      # @return [Hash, nil] `moves`, `at`, `verdicts` and `rebased`, nil when
+      #   palpatine has not ruled on this visit
+      def merge_risk
+        record = read["merge_risk"] or return nil
+        record["moves"] == moves ? record : nil
+      end
+
+      # @param verdicts [Hash{Integer, String => String}] number => `auto` or `manual`
+      # @param at [Time]
+      # @return [Hash] the record kept
+      def assess!(verdicts, at: Time.now)
+        update do |data|
+          data["merge_risk"] = { "moves" => data["moves"].to_i, "at" => at.iso8601,
+                                 "verdicts" => verdicts.to_h { |n, v| [n.to_s, v.to_s] }, "rebased" => {} }
+        end
+        merge_risk
+      end
+
+      # @param number [Integer] the sibling pull request the engine rebased
+      # @param at [Time]
+      # @return [void]
+      def rebased!(number, at: Time.now)
+        update { |data| data["merge_risk"]&.fetch("rebased")&.store(number.to_s, at.iso8601) }
+      end
+
+      # ---- memory -----------------------------------------------------------
+
+      # Where the journals live in the document (M2).
+      MEMORY = "memory"
+
+      # One agent's journal on this plan, oldest round first, each entry
+      # numbered as the agent refers to it: 1 up, across every round.
+      #
+      # @param agent [String]
+      # @return [Array<OpenLanes::Plans::Journal::Round>] empty for an agent
+      #   that never printed an entry here
+      def journal(agent)
+        rounds = read.dig(MEMORY, agent, "rounds") || {}
+        first = 1
+        rounds.sort_by { |key, _| key.to_i }.map do |key, value|
+          entries = Array(value["entries"]).map { Journal::Entry.from_h(it) }
+          round = Journal::Round.new(number: key.to_i, round: value["round"], state: value["state"], entries:, first:)
+          first += entries.size
+          round
+        end
+      end
+
+      # Append entries to one of the agent's journal rounds, as they arrive.
+      #
+      # The first call of a dispatch passes no +number+ and is given the next
+      # one, under the same lock as the write, so two runs on one plan cannot
+      # both take round 3. Later calls of the same dispatch pass it back.
+      #
+      # An `override` must name an entry before its own: one pointing at
+      # itself or ahead can only be a miscount, and the prompt would draw it
+      # as overturning something it never saw.
+      #
+      # @param agent [String]
+      # @param entries [Array<OpenLanes::Plans::Journal::Entry>]
+      # @param number [Integer, nil] the journal round, nil to start one
+      # @param round [Integer, nil] the dispatcher's round, kept beside it
+      # @param state [#to_s, nil] the state the round started in
+      # @return [Array(Integer, Array<OpenLanes::Plans::Journal::Rejection>)]
+      #   the journal round written to, and what was refused
+      # @raise [OpenLanes::Error] on an agent name that is not one token
+      def journal!(agent:, entries:, number: nil, round: nil, state: nil)
+        raise Error, "a journal needs an agent name" unless agent.to_s.match?(/\A[\w-]+\z/)
+
+        rejected = []
+        update do |data|
+          rounds = ((data[MEMORY] ||= {})[agent] ||= {})["rounds"] ||= {}
+          number ||= rounds.keys.map(&:to_i).max.to_i + 1
+          target = (rounds[number.to_s] ||= { "round" => round, "state" => state&.to_s }.compact.merge("entries" => []))
+          count = rounds.sum { |_, value| Array(value["entries"]).size }
+          entries.each do |entry|
+            if entry.overrides && entry.overrides > count
+              rejected << Journal::Rejection.new(line: Journal.line(entry.kind, entry.text, overrides: entry.overrides),
+                reason: "entry #{count + 1} overrides #{entry.overrides}, which is not before it")
+              next
+            end
+            target["entries"] << entry.to_json_h
+            count += 1
+          end
+        end
+        [number, rejected]
+      end
+
+      # A person's answer to one of the agent's `blocked.md` questions, kept
+      # in the agent's journal with the question (M3): B1 with A1. Appended to
+      # the agent's latest round, which is the one that asked. Written once:
+      # a drain that is run again finds the same ref and answer already there.
+      # The check is made under the lock the write takes, so two drains at
+      # once (two control rooms, or a hand run beside the broker) cannot both
+      # find it missing and both write it.
+      #
+      # @param agent [String]
+      # @param ref [String] `B<n>`
+      # @param question [String]
+      # @param answer [String]
+      # @return [OpenLanes::Plans::Journal::Entry, nil] nil when it was there
+      # @raise [OpenLanes::Error] on an agent name that is not one token
+      def answer!(agent:, ref:, question:, answer:)
+        raise Error, "a journal needs an agent name" unless agent.to_s.match?(/\A[\w-]+\z/)
+
+        entry = Journal::Entry.new(kind: "question", text: question, ref:, answer:)
+        written = nil
+        update do |data|
+          rounds = ((data[MEMORY] ||= {})[agent] ||= {})["rounds"] ||= {}
+          next if rounds.each_value.any? { Array(it["entries"]).include?(entry.to_json_h) }
+
+          latest = rounds.keys.map(&:to_i).max || 1
+          (rounds[latest.to_s] ||= { "entries" => [] })["entries"] << entry.to_json_h
+          written = entry
+        end
+        written
+      end
+
+      # The agent whose questions `blocked.md` holds: whoever blocked last,
+      # a round that settled Blocked or a Blocked signature, since a plan
+      # blocked by hand-run agents has signatures and no stages. Neither
+      # kind outranks the other: a hand-run agent that blocks after a
+      # harness round did is the one that asked.
+      #
+      # @return [String, nil] nil when nothing on record ever blocked
+      def blocked_by
+        data = read
+        blocks = data["stages"].select { it["status"] == "Blocked" }
+                               .map { [parse_time(it["finished_at"] || it["started_at"]), it["agent"]] }
+        blocks += data["signatures"].select { it["status"] == "Blocked" }.map { [parse_time(it["at"]), it["agent"]] }
+        blocks.each_with_index.max_by { |(at, _), i| [at, i] }&.first&.last
+      end
+
+      # ---- last-known-state -------------------------------------------------
+
+      # Where the resume records live in the document.
+      LAST_KNOWN = "last-known-state"
+
+      # Keep one agent's resume record, keyed by agent, so an agent
+      # interrupted in rounds 1 and 3 leaves one entry, not two nobody prunes.
+      # A harness entry does not replace the agent's own of the same round or
+      # later: see {LastKnownState#supersedes?}.
+      #
+      # @param agent [String]
+      # @param entry [OpenLanes::Plans::LastKnownState]
+      # @return [OpenLanes::Plans::LastKnownState] the entry kept, which is
+      #   the existing one when the new one may not replace it
+      # @raise [OpenLanes::Error] on an agent name that is not one token
+      def record_last_known(agent, entry)
+        raise Error, "a resume record needs an agent name" unless agent.to_s.match?(/\A[\w-]+\z/)
+
+        kept = entry
+        update do |data|
+          section = (data[LAST_KNOWN] ||= {})
+          existing = section[agent] && LastKnownState.from_h(section[agent])
+          if entry.supersedes?(existing)
+            section[agent] = entry.to_json_h
+          else
+            kept = existing
+          end
+        end
+        kept
+      end
+
+      # @param agent [String]
+      # @return [OpenLanes::Plans::LastKnownState, nil]
+      def last_known(agent) = last_known_states[agent]
+
+      # @return [Hash{String => OpenLanes::Plans::LastKnownState}] empty when
+      #   no agent was ever interrupted
+      def last_known_states
+        (read[LAST_KNOWN] || {}).transform_values { |h| LastKnownState.from_h(h) }
+      end
+
       # The signatures as ledger entries, so the dispatcher reads them exactly
       # as it reads a line in plan.md. Each signature takes two line numbers,
       # the entry and its handoff, so {Ledger.handoff_after} pairs them.
@@ -266,6 +819,34 @@ module OpenLanes
         Digest::SHA256.hexdigest("#{plans}\0#{identity["ordinal"] || File.basename(dir)}")[0, 16]
       end
 
+      # @param stage [Hash]
+      # @return [Time]
+      def started(stage) = parse_time(stage["started_at"])
+
+      # @param all [Array<Hash>] every stage
+      # @param since [Hash] the stage to look after
+      # @param state [String]
+      # @return [String, nil] a state some later stage left the plan in, other
+      #   than +state+
+      def moved_since(all, since, state)
+        after = started(since)
+        at = all.index { it.equal?(since) }
+        all.each_with_index
+           .select { |s, i| i > at || started(s) > after }
+           .map { |s, _| s["to"].to_s }
+           .find { !it.empty? && it != state }
+      end
+
+      # @param one [Hash]
+      # @param other [Hash]
+      # @return [Boolean] whether the two are one message, by id when both
+      #   carry one, by what they say otherwise
+      def same_message?(one, other)
+        return one["id"] == other["id"] if one["id"] && other["id"]
+
+        %w[from to body].all? { one[it] == other[it] } && parse_time(one["at"]) == parse_time(other["at"])
+      end
+
       # @param text [String, nil]
       # @return [Time]
       def parse_time(text)