openlanes 3.0.1 → 3.1.0

data/lib/openlanes/live/snapshot.rb

@@ -13,17 +13,6 @@ module OpenLanes
     # to the page's fixture, level by level, so a field renamed on one side
     # fails the other's suite.
     class Snapshot
-      # How an agent marks a question as answerable with Yes or No (W30), on
-      # its own line under the question's heading. The agents' prompt shows
-      # it, and {#questions} looks for it; neither spells it twice.
-      YES_NO_MARK = "answers: yes, no"
-
-      # {YES_NO_MARK}, read forgivingly: brackets, case and spacing vary.
-      YES_NO = /answers:\s*\[?\s*yes\s*,\s*no\s*\]?/i
-
-      # Any Markdown heading, which ends the body of the question above it.
-      HEADING = /^[ \t]{0,3}\#{1,6}[ \t]/
-
       # Plan states finished with, kept off "Choose an existing plan".
       FINISHED = %i[approved deployed discarded].freeze
 
@@ -42,9 +31,16 @@ module OpenLanes
       # @param meter [OpenLanes::Live::Meter]
       # @param log [Array<Hash>] `LogLine`s, newest last
       # @param adapter [OpenLanes::Adapters::Base] whose models the page offers
+      # @param judge [#call, nil] a second opinion on whether a question asks
+      #   to choose ({ChoiceJudge}); nil leaves the parser's verdict alone
+      # @param redis_url [String, nil] the store the engine itself is using,
+      #   unredacted: the snapshot redacts it ({Live.redact})
+      # @param outage [Hash, nil] {OutageReport#to_h} of the outage this run
+      #   last recovered from; nil when there was none
       def initialize(board:, tree:, agents:, node:, repo:, project:, seq:, description: nil, at: Time.now,
         started_at: nil, claims: nil, run_state: RunState.new, meter: Meter.new, log: [],
-        adapter: Adapters.for(Adapters::DEFAULT))
+        adapter: Adapters.for(Adapters::DEFAULT), judge: Live.choice_judge, redis_url: nil,
+        outage: nil)
         @board = board
         @tree = tree
         @agents = agents
@@ -60,6 +56,9 @@ module OpenLanes
         @meter = meter
         @log = log
         @adapter = adapter
+        @judge = judge
+        @redis_url = redis_url
+        @outage = outage
       end
 
       # @return [Hash]
@@ -76,8 +75,10 @@ module OpenLanes
           stations:    Stations.all(@agents).map(&:wire),
           plans:       mine,
           backlog:     backlog(subjects, mine.map { it[:ordinal] }),
+          bombs:       bombs(subjects),
           models:      @adapter.models.map(&:wire),
           autocompact: Adapters::AUTOCOMPACT / 100.0,
+          redis_url:   @redis_url && Live.redact(@redis_url),
           log:         @log }
       end
 
@@ -93,7 +94,9 @@ module OpenLanes
           up:             @board.up.to_i,
           down:           @board.down.to_i,
           cost:           plans.sum { it[:cost] }.round(4),
-          agents_working: @board.running.to_i }
+          agents_working: @board.running.to_i,
+          jobs:           @board.jobs.to_i,
+          outage:         @outage }
       end
 
       # @return [String]
@@ -121,12 +124,15 @@ module OpenLanes
         ordinal = subject.feature.ordinal.to_s
         state = Plans::PlanState.for(subject.feature.path)
         stages = state.stages
+        finished = state.finished
         rows = @board.rows.select { it.ordinal == ordinal }
         spent = @meter.for(ordinal, method(:price))
         started = @meter.started_at(ordinal)
+        mailbox = Plans.mailbox(subject.feature.path)
         { ordinal:,
           title:       subject.feature.title,
           slug:        subject.feature.slug,
+          summary:     Plans::Spec.summary(subject.read(Plans::Spec::FILENAME).to_s),
           status:      status(subject.status),
           lane:        Plans::Spec.for(subject).lane.to_s,
           station:     Stations.key_for(subject.status.key, before: stages.last&.fetch("from", nil)&.to_sym).to_s,
@@ -136,15 +142,20 @@ module OpenLanes
           started_at:  started && iso(started),
           elapsed:     started ? (@at - started).round : 0,
           cars:        rows.map { car(it, subject, stages) },
-          pr:          pull_request(subject),
+          pr:          pull_request(subject, finished),
           questions:   questions(subject, state),
           interrupted: interrupted(stages, rows),
-          claimed_by:  claimed_by(ordinal) }
+          claimed_by:  claimed_by(ordinal),
+          unacked:     mailbox.unacked,
+          mail:        mailbox.unacked_pairs,
+          last_known:  last_known(state),
+          locked:      Plans::Lock.read(subject.feature.path)&.to_json_hash,
+          finished:    finished && { kind: finished.kind, at: iso(finished.at) } }
       end
 
       # @param status [OpenLanes::Plans::Status]
       # @return [Hash] `Status`
-      def status(status) = { key: status.key.to_s, emoji: status.emoji, label: status.label }
+      def status(status) = { key: status.key.to_s, emoji: status.emoji, label: status.label, note: status.note.to_s.delete("`") }
 
       # @param subjects [Array<OpenLanes::Plans::Subject>]
       # @param taken [Array<String>] ordinals already on the board
@@ -158,6 +169,24 @@ module OpenLanes
         end
       end
 
+      # Every 💣 in the tree that is not another machine's, on the board or
+      # not: a bomb halts the whole run, so the page shows it whatever this
+      # node is working on (plan 009).
+      #
+      # @param subjects [Array<OpenLanes::Plans::Subject>]
+      # @return [Array<Hash>] `Bomb`
+      def bombs(subjects)
+        aging = Lifecycle::Aging.new(tree: @tree, now: @at)
+        subjects.select { it.status.key == :bomb && !foreign?(it.feature.ordinal.to_s) }.map do |s|
+          resume = Plans::PlanState.for(s.feature.path).resume_until
+          { plan:          s.feature.ordinal.to_s,
+            slug:          s.feature.slug,
+            blocked_md:    s.read("blocked.md").to_s,
+            blocked_since: iso(aging.started_at(s)),
+            resume_until:  resume && iso(resume) }
+        end
+      end
+
       # ---- cars -------------------------------------------------------------
 
       # @param row [OpenLanes::Engine::Board::Row]
@@ -183,6 +212,7 @@ module OpenLanes
           elapsed:       row.elapsed.to_i,
           remaining:     row.remaining,
           held:          @run_state.car_held?(row.key),
+          subagents:     Array(row.running),
           next_model:    next_model(row) }
       end
 
@@ -229,16 +259,24 @@ module OpenLanes
       # ---- pull request, interruption, claim --------------------------------
 
       # @param subject [OpenLanes::Plans::Subject]
+      # @param finished [OpenLanes::Plans::PlanState::Finished, nil]
       # @return [Hash, nil] `PullRequest`
-      def pull_request(subject)
+      def pull_request(subject, finished)
         pr = subject.pull_requests.find(&:open?) || subject.pull_requests.last or return nil
-        { number: pr.number.to_s[/\d+/].to_i, url: pr.url, state: pr_state(pr, subject), ci: nil, merged_at: nil }
+        merged_at = finished.at if pr.merged? && finished&.merged?
+        { number: pr.number.to_s[/\d+/].to_i, url: pr.url, state: pr_state(pr, subject, finished), ci: nil,
+          merged_at: merged_at && iso(merged_at) }
       end
 
+      # hansolo's approval leaves the plan at 👀 with its pull request open,
+      # which the status key alone reads as "open": `finished` is what says
+      # it was approved, so the page's pill turns green.
+      #
       # @return [String]
-      def pr_state(pr, subject)
+      def pr_state(pr, subject, finished)
         return "merged" if pr.merged?
         return "closed" unless pr.open?
+        return "approved" if finished&.kind == "approved"
 
         { rejected: "rejected", approved: "approved" }.fetch(subject.status.key, "open")
       end
@@ -255,6 +293,18 @@ module OpenLanes
         { agent: last["agent"], at: last["finished_at"] || last["started_at"], note: last["note"].to_s }
       end
 
+      # Where each interrupted agent stood, as the next round will read it.
+      # Read-only: an unacked count or a resume record never changes a round.
+      #
+      # @param state [OpenLanes::Plans::PlanState]
+      # @return [Array<Hash>] `LastKnown`, one per agent
+      def last_known(state)
+        state.last_known_states.map do |agent, entry|
+          { agent:, source: entry.source, at: entry.at, round: entry.round, status: entry.status,
+            next_step: entry.next_step, note: entry.note }
+        end
+      end
+
       # @param ordinal [String]
       # @return [String, nil] the node id, without its checkout
       def claimed_by(ordinal) = @claims&.held_by(ordinal)&.then { it.split(":").first }
@@ -265,17 +315,25 @@ module OpenLanes
 
       # ---- questions --------------------------------------------------------
 
-      # The questions `blocked.md` still asks, each with its body, whether it
-      # is a yes/no question, and who asked.
+      # The questions `blocked.md` still asks, each with its context, the
+      # options it offers (D3), and who asked; then the harness's own
+      # requests for more time or rounds (E1), and R4's quality question on
+      # the plan that asked it.
       #
       # @param subject [OpenLanes::Plans::Subject]
       # @param state [OpenLanes::Plans::PlanState]
       # @return [Array<Hash>] `Question`
       def questions(subject, state)
+        blocked(subject, state) + Engine::Extensions.questions(subject, state) +
+          Engine::QualityQuestion.questions(subject, state)
+      end
+
+      # @return [Array<Hash>] `Question`, from `blocked.md`
+      def blocked(subject, state)
         open = Lifecycle::Unblocker.questions(subject).reject(&:answered)
         return [] if open.empty?
 
-        bodies = bodies(subject.read("blocked.md").to_s)
+        bodies = Plans::BlockedFile.bodies(subject.read("blocked.md").to_s)
         asker = state.signatures.rfind { it["status"] == "Blocked" }
         asked_at = asker&.fetch("at", nil) || iso(File.mtime(File.join(subject.feature.path, "blocked.md")))
         open.map { |q| question(subject, q, bodies.fetch(q.number, ""), asker, asked_at) }
@@ -284,34 +342,37 @@ module OpenLanes
       # @return [Hash]
       def question(subject, open, body, asker, asked_at)
         id = "#{subject.feature.ordinal}/B#{open.number}"
-        yes_no = open.heading.match?(YES_NO) || body.match?(YES_NO)
+        choices = choices(open.heading, body)
         { id:,
           number:   open.number,
-          heading:  open.heading.sub(YES_NO, "").strip,
-          body:     body.lines.grep_v(/\A\s*#{YES_NO.source}\s*\z/i).join.strip,
+          kind:     "block",
+          heading:  open.heading.sub(Plans::Choices::YES_NO, "").strip,
+          body:     choices ? choices.context : body.strip,
           agent:    asker&.fetch("agent", nil),
           owner:    subject.status.key == :product_blocked ? "product" : "technical",
-          answers:  yes_no ? %w[yes no] : nil,
+          options:  choices&.to_a,
           held:     @run_state.question_held?(id),
           asked_at: }
       end
 
-      # @param text [String] the whole of blocked.md
-      # @return [Hash{Integer => String}] each open question's number to the
-      #   lines under its heading, up to the next heading
-      def bodies(text)
-        found = {}
-        current = nil
-        text.each_line do |line|
-          if (number = line[Plans::OPEN_BLOCK, 1])
-            current = found[number.to_i] = +""
-          elsif line.match?(HEADING) || line.match?(Plans::ANSWER_BLOCK)
-            current = nil
-          elsif current
-            current << line
-          end
-        end
-        found
+      # The options a question offers, or nil for one that wants words.
+      #
+      # A question its agent marked yes/no (W30) is taken at its word. Any
+      # other the parser found options in goes past the judge, which may say
+      # the list was not a choice after all; it is never asked about a
+      # question the parser found nothing in, since there would be no buttons
+      # to show.
+      #
+      # @param heading [String]
+      # @param body [String]
+      # @return [OpenLanes::Plans::Choices, nil]
+      def choices(heading, body)
+        return Plans::Choices.yes_no(body) if heading.match?(Plans::Choices::YES_NO)
+
+        found = Plans::Choices.parse(body) or return nil
+        return found if body.match?(Plans::Choices::YES_NO)
+
+        @judge&.call(body) == false ? nil : found
       end
 
       # @param time [Time]

data/lib/openlanes/live/stations.rb

@@ -25,7 +25,7 @@ module OpenLanes
         def wire = { key: key.to_s, label:, agents: }
       end
 
-      # Key, label and the states folded into it, in spine order. ⭐️ Planned
+      # Key, label and the states folded into it, in spine order. ⭐ Planned
       # sits with 🟡 Building and 🟢 Ready for Review with 👀 In Review,
       # because on the board each pair is one stop with the same agents.
       # 🔴 Rejected sits at Building too: luke and rey rework it there, and
@@ -37,8 +37,8 @@ module OpenLanes
         [:ready_for_planning, "Planning", %i[ready_for_planning]],
         [:building, "Building", %i[planned building rejected]],
         [:building_ui, "Building UI", %i[building_ui]],
-        [:in_review, "Review", %i[ready_for_review in_review]],
-        [:pr, "Pull request", %i[approved deployed]]
+        [:in_review, "Review", %i[ready_for_review in_review verifying]],
+        [:pr, "Pull request", %i[completed approved deployed]]
       ].freeze
 
       module_function
@@ -54,7 +54,7 @@ module OpenLanes
       # The stop a plan in +state+ is shown at. A state a {GROUPS} entry
       # names is shown at that stop, which is how 🔴 Rejected lands at
       # Building. Any other state off the spine (💩, 😱) is shown where the
-      # spine takes it next; one with no way forward (⭕️, 🅱️) where the
+      # spine takes it next; one with no way forward (⭕, 🛑) where the
       # plan was when it stopped, which only its history knows.
       #
       # @param state [Symbol]

data/lib/openlanes/live/store.rb

@@ -45,7 +45,7 @@ module OpenLanes
 
       # The writes {#multi} accepts. Reads inside a transaction answer
       # nothing until it commits, so none are offered.
-      WRITES = %i[set del expire hset hdel xadd xack].freeze
+      WRITES = %i[set del expire hset hdel xadd xack xtrim].freeze
 
       # Records the writes of one {#multi} block, to be applied together.
       class Transaction
@@ -144,6 +144,15 @@ module OpenLanes
       # @return [Integer] entries in the stream
       def xlen(key) = call("XLEN", key)
 
+      # Drops every entry older than +minid+, exactly rather than with `~`,
+      # so a message an hour old is gone when the hour is up, not when Redis
+      # next finds a whole node to free.
+      #
+      # @param key [String]
+      # @param minid [String] `<ms>-<seq>`, the oldest id kept
+      # @return [Integer] how many were removed
+      def xtrim(key, minid:) = call(*xtrim_command(key, minid:))
+
       # Creates the group, and the stream with it. Asking twice is not an
       # error: every engine start asks.
       #
@@ -169,6 +178,10 @@ module OpenLanes
       # @return [Array<Entry>]
       def xreadgroup(key, group, consumer, id: ">", count: 100)
         entries(call("XREADGROUP", "GROUP", group, consumer, "COUNT", count, "STREAMS", key, id)&.fetch(key, nil))
+      rescue RedisClient::CommandError => e
+        raise unless e.message.start_with?("NOGROUP")
+
+        raise GroupMissing, e.message.lines.first.to_s.strip
       end
 
       # @return [Integer] how many were acknowledged
@@ -268,10 +281,14 @@ module OpenLanes
         case name
         when :set then set_command(*args, **kwargs)
         when :xadd then xadd_command(*args, **kwargs)
+        when :xtrim then xtrim_command(*args, **kwargs)
         else [name.to_s.upcase, *args]
         end
       end
 
+      # @return [Array]
+      def xtrim_command(key, minid:) = ["XTRIM", key, "MINID", minid]
+
       # @return [Array]
       def set_command(key, value, ex: nil, nx: false)
         ["SET", key, value, *("NX" if nx), *(["EX", ex] if ex)]

data/lib/openlanes/live/subscriber.rb

@@ -27,6 +27,12 @@ module OpenLanes
           @pubsub.call("PSUBSCRIBE", *patterns) unless patterns.empty?
           confirm(channels.size + patterns.size, timeout)
         end
+      rescue Unavailable
+        # The caller never gets this object, so nobody else can close the
+        # connection, and a chat retrying a NOPERM every step would pile up
+        # one open socket per try until the GC got round to them.
+        close
+        raise
       end
 
       # The next message, waiting up to +timeout+ seconds for one.
@@ -36,7 +42,7 @@ module OpenLanes
       # @raise [OpenLanes::Live::Unavailable]
       def next_message(timeout)
         loop do
-          event = guarded { @pubsub.next_event([timeout, SHORTEST].max) } or return nil
+          event = read([timeout, SHORTEST].max) or return nil
           case event.first
           when "message" then return [event[1], event[2]]
           when "pmessage" then return [event[2], event[3]]
@@ -56,11 +62,25 @@ module OpenLanes
       def confirm(expected, timeout)
         confirmed = 0
         while confirmed < expected
-          event = @pubsub.next_event(timeout) or raise Unavailable, "Redis at #{Live.mask(@url)} did not confirm a subscription"
+          event = read(timeout) or raise Unavailable, "Redis at #{Live.mask(@url)} did not confirm a subscription"
           confirmed += 1 if %w[subscribe psubscribe].include?(event.first)
         end
       end
 
+      # The next event on the connection. redis-client hands a refusal back
+      # as an error object rather than raising it, so a `NOPERM` from an ACL
+      # that withholds `PSUBSCRIBE` would otherwise reach `event.first` as a
+      # NoMethodError and kill the hub's thread without a word.
+      #
+      # @param timeout [Float]
+      # @return [Array, nil]
+      # @raise [OpenLanes::Live::Unavailable]
+      def read(timeout)
+        event = guarded { @pubsub.next_event(timeout) }
+        guarded { raise event } if event.is_a?(RedisClient::Error)
+        event
+      end
+
       # @return [Object] the block's value
       # @raise [OpenLanes::Live::Unavailable]
       def guarded

data/lib/openlanes/live.rb

@@ -17,6 +17,11 @@ module OpenLanes
     # Redis could not be reached, or stopped answering.
     class Unavailable < Error; end
 
+    # A stream's consumer group is not there: a Redis that restarted empty
+    # (W32) took it with everything else. Whoever reads the group creates it
+    # again; nothing is wrong with the connection.
+    class GroupMissing < Error; end
+
     module_function
 
     # W16's order: `--redis-url`, then `.openlanes.yml`'s `redis_url:`, then
@@ -36,6 +41,16 @@ module OpenLanes
     # @return [String]
     def mask(url) = url.to_s.sub(%r{\A([a-z][a-z0-9+.-]*://)([^:@/]*):[^@/]+@}i, '\1\2:***@')
 
+    # The address with all of its userinfo replaced, user name included, for
+    # a page anyone on the network can open. {.mask} keeps the user name
+    # because a log read by the person who ran the engine is better for it; a
+    # page shown on a shared screen is not.
+    #
+    # @param url [String]
+    # @return [String] `redis://:***@host:6379/0`, or the URL as it was when
+    #   it carries no userinfo
+    def redact(url) = url.to_s.sub(%r{\A([a-z][a-z0-9+.-]*://)[^@/]*@}i, '\1:***@')
+
     # @param url [String]
     # @return [OpenLanes::Live::Store]
     def store(url) = Store.new(url:)
@@ -54,6 +69,56 @@ module OpenLanes
       store
     end
 
+    # The process's {ChoiceJudge}: one, so its answers are shared by every
+    # snapshot built here; nil without TYPESAFE_API_KEY, and nil in the suite.
+    #
+    # @return [OpenLanes::Live::ChoiceJudge, nil]
+    def choice_judge
+      return @choice_judge if defined?(@choice_judge)
+
+      @choice_judge = ChoiceJudge.from_env
+    end
+
+    # @param judge [#call, nil] answers `call(text)` with true, false or nil
+    # @return [void]
+    def choice_judge=(judge)
+      @choice_judge = judge
+    end
+
+    # The process's {ChoiceConverter}: nil without OPENROUTER_API_KEY, and
+    # nil in the suite.
+    #
+    # @return [OpenLanes::Live::ChoiceConverter, nil]
+    def choice_converter
+      return @choice_converter if defined?(@choice_converter)
+
+      @choice_converter = ChoiceConverter.from_env
+    end
+
+    # @param converter [#call, nil] answers `call(heading:, body:)` with a
+    #   {ChoiceConverter::Result}
+    # @return [void]
+    def choice_converter=(converter)
+      @choice_converter = converter
+    end
+
+    # The process's {Interviewer} (M6): nil without OPENROUTER_API_KEY, and
+    # nil in the suite.
+    #
+    # @return [OpenLanes::Live::Interviewer, nil]
+    def interviewer
+      return @interviewer if defined?(@interviewer)
+
+      @interviewer = Interviewer.from_env
+    end
+
+    # @param interviewer [#call, nil] answers `call(idea:)` with
+    #   {Interviewer::Question}s
+    # @return [void]
+    def interviewer=(interviewer)
+      @interviewer = interviewer
+    end
+
     # @return [OpenLanes::Live::Session]
     def session(**) = Session.new(**)
 
@@ -95,7 +160,7 @@ module OpenLanes
     # @raise [OpenLanes::Live::Command::Invalid] for the API server's 422
     def enqueue(store:, keys:, input:)
       command = Command.parse(input)
-      store.xadd(keys.commands, { json: JSON.generate(command.wire) })
+      EventBus.for(store).append(keys.commands, { json: JSON.generate(command.wire) })
       Reply.new(id: command.id, status: "accepted")
     end
 

data/lib/openlanes/plans/blocked_file.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # The bodies of the questions in `blocked.md`: the lines under each
+    # `## Bn` heading, up to the next heading of any kind or the next `## An`;
+    # and the answers under `## An`, which run to the next `Bn` or `An`.
+    #
+    # The page reads a body to show it and the engine reads one to rewrite it
+    # into choices, so both find its edges here; two readers with two ideas
+    # of where a question ends would rewrite text the page never showed.
+    # Pure: text in, text out.
+    module BlockedFile
+      # Any Markdown heading, which ends the body of the question above it.
+      HEADING = /^[ \t]{0,3}\#{1,6}[ \t]/
+
+      # What sits between `A1` and the answer on its heading: a `.`, `:` or
+      # `)`, the close of a bold `**A1.**`, or a dash with a space after it.
+      # Only that, because the answer's own punctuation is part of it: `-1`
+      # and `--no-delete` are decisions, and `1` and `no-delete` the opposite.
+      SEPARATOR = /\A[ \t]*[.:)]?\**[ \t]*(?:[-–—][ \t]+)?/
+
+      # A question or an answer heading, either of which ends an answer.
+      BLOCK = Regexp.union(OPEN_BLOCK, ANSWER_BLOCK)
+
+      module_function
+
+      # @param text [String] the whole of blocked.md
+      # @return [Hash{Integer => String}] each question's number to the
+      #   lines under its heading; a number written twice keeps the last
+      def bodies(text)
+        lines = text.to_s.lines
+        spans(lines).transform_values { |(from, to)| lines[from...to].join }
+      end
+
+      # The answers waiting under `## An` headings, by number, which is how
+      # the harness copies each question and its answer into the asking
+      # agent's journal (M3) before the broker drains them.
+      #
+      # An answer is often its heading: `## A2. Retain, do not delete`, with
+      # only who decided under it. So the words after the number are part of
+      # it. And it is a person's text, which the page writes verbatim, so a
+      # heading inside it (`### Database`) is part of it too; only the next
+      # question or answer ends it.
+      #
+      # @param text [String] the whole of blocked.md
+      # @return [Hash{Integer => String}] each answer's number to its heading's
+      #   words, if any, and the lines under it
+      def answers(text)
+        lines = text.to_s.lines
+        spans(lines, ANSWER_BLOCK, ends: BLOCK).to_h do |number, (from, to)|
+          title = lines[from - 1].sub(ANSWER_BLOCK, "").sub(SEPARATOR, "").strip
+          [number, "#{"#{title}\n" unless title.empty?}#{lines[from...to].join}"]
+        end
+      end
+
+      # +text+ with question +number+'s body replaced by +body+, its heading
+      # and everything else as they were.
+      #
+      # @param text [String] the whole of blocked.md
+      # @param number [Integer]
+      # @param body [String]
+      # @return [String, nil] nil when the file has no such question
+      def replace(text, number, body)
+        lines = text.to_s.lines
+        from, to = spans(lines)[number]
+        return nil unless from
+
+        lines[from - 1] = "#{lines[from - 1].chomp}\n"
+        section = ["\n", "#{body.strip}\n"]
+        section << "\n" if to < lines.size
+        (lines[0...from] + section + lines[to..]).join
+      end
+
+      # +text+ with answer +number+ taken out and +note+ put at the top of its
+      # question's body, so the question is open again and says why.
+      #
+      # An answer the broker read and would not fold in otherwise sits under
+      # its question for good: the page counts the question answered and
+      # hides it, and the broker refuses it every time it is asked. Before
+      # the options, because the page reads a body's options off its end.
+      #
+      # @param text [String] the whole of blocked.md
+      # @param number [Integer]
+      # @param note [String]
+      # @return [String, nil] nil when the file has no such question or answer
+      def reject(text, number, note)
+        lines = text.to_s.lines
+        from, to = spans(lines, ANSWER_BLOCK, ends: BLOCK)[number]
+        return nil unless from && bodies(text).key?(number)
+
+        reopened = (lines[0...(from - 1)] + lines[to..]).join
+        replace(reopened, number, "#{note.strip}\n\n#{bodies(reopened)[number].strip}")
+      end
+
+      # @param lines [Array<String>]
+      # @param pattern [Regexp] {OPEN_BLOCK} for questions, {ANSWER_BLOCK}
+      #   for answers; either kind of heading ends the other's body
+      # @param ends [Regexp] what else ends a body: any heading, by default
+      # @return [Hash{Integer => Array(Integer, Integer)}] each block's
+      #   number to the first line under its heading and the line that ends it
+      def spans(lines, pattern = OPEN_BLOCK, ends: HEADING)
+        found = {}
+        open = nil
+        lines.each_with_index do |line, i|
+          number = line[pattern, 1]
+          if number || line.match?(ends) || line.match?(OPEN_BLOCK) || line.match?(ANSWER_BLOCK)
+            found[open.first] = [open.last, i] if open
+            open = number && [number.to_i, i + 1]
+          end
+        end
+        found[open.first] = [open.last, lines.size] if open
+        found
+      end
+    end
+  end
+end