agentilda 1.0.3 → 2.0.1

data/lib/agentilda/screen/ratatui.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+require "ratatui_ruby"
+
+module Agentilda
+  module Screen
+    # A ratatui_ruby-backed alternative to {Screen}, selected with `--tui
+    # ratatui`. Unlike {Screen}, whose #draw renders synchronously from the
+    # dispatcher's own tick, ratatui_ruby owns a blocking render+input loop
+    # of its own — see the lifecycle methods added in the next task. This
+    # class carries the parts of that loop with no terminal dependency: the
+    # widget tree built from a {Board}.
+    class Ratatui
+      # Cells each column takes. The last one is stretched to the edge by
+      # ratatui's legacy flex. The elapsed/time-left columns (indices 8 and 9) are 17,
+      # not 13: {Bar.cell} emits a 10-cell bar plus a clock suffix up to 7
+      # characters wide (e.g. " 12:41"), and a narrower column clips the
+      # clock digits once ratatui actually lays the table out (see
+      # spec/agentilda/screen/ratatui_spec.rb's real-terminal regression
+      # test, which is the only one of this file's specs that can see
+      # that — the rest inspect the pre-layout `Text::Line` object).
+      COLUMNS = [9, 7, 16, 18, 8, 8, 5, 13, 17, 17].freeze
+
+      HEADER = %w[time plan feature agent round model subs tokens elapsed left].freeze
+
+      # Blank lines between two agents.
+      ROW_GAP = 1
+
+      # The highlight symbol's column. Reserved even with nothing selected,
+      # so the activity line's x never shifts when a selection appears.
+      HIGHLIGHT_SYMBOL = "> "
+
+      # The activity line starts under the feature column: past the
+      # highlight symbol, time and plan, each column plus its 1-cell gap.
+      ACTIVITY_INDENT = HIGHLIGHT_SYMBOL.length + COLUMNS[0] + 1 + COLUMNS[1] + 1
+
+      # Cells a status line stops short of the terminal's right edge.
+      ACTIVITY_MARGIN = 5
+
+      # Status lines drawn under an agent's row when nobody says otherwise.
+      SCROLL_HEIGHT = 3
+
+      # Seconds between samples for the running-agent-count sparkline.
+      SAMPLE_INTERVAL = 10
+
+      # Points the sparkline keeps before the oldest scrolls off the left.
+      HISTORY = 60
+
+      # @return [Array<Integer>] running-agent-count samples, oldest first
+      attr_reader :history
+
+      # @return [Integer] status lines drawn under each agent's row
+      attr_reader :scroll_height
+
+      # @param runner [#call] `RatatuiRuby.method(:run)` by default; a fake
+      #   in tests, so this class never needs a real terminal to exercise
+      #   its own orchestration
+      # @param scroll_height [Integer] how many of an agent's latest statuses
+      #   show under its row, newest at the top
+      def initialize(runner: RatatuiRuby.method(:run), scroll_height: SCROLL_HEIGHT)
+        @runner = runner
+        @scroll_height = Integer(scroll_height).clamp(1, Board::Row::HISTORY)
+        @board = nil
+        @keyboard = nil
+        @history = []
+        @last_sample = nil
+        # Read from the dispatcher's thread in #tick's `until @closing` via
+        # #run_loop, written from the caller's thread in #close. Safe only
+        # under MRI/CRuby's GVL, which serializes the read and the write;
+        # a GVL-free Ruby would need a real memory barrier here.
+        @closing = false
+        @error = nil
+        @mutex = Mutex.new
+      end
+
+      # @param keyboard [Agentilda::Keyboard] built with `.new`, never
+      #   `.start`'d — this is what feeds it keys, from the thread
+      #   ratatui_ruby's own loop runs on.
+      # @return [void]
+      def attach_keyboard(keyboard) = @keyboard = keyboard
+
+      # @return [void]
+      def open
+        @closing = false
+        @error = nil
+        @thread = Thread.new do
+          Thread.current.report_on_exception = false
+          begin
+            @runner.call { |tui| run_loop(tui) }
+          rescue StandardError => e
+            # A background render thread's job is never to crash the run:
+            # #close's `@thread&.join` would otherwise re-raise this inside
+            # `run.rb`'s `ensure`, after every agent has already run,
+            # discarding the whole run report. Stash it; #close surfaces it
+            # with a one-line warning instead.
+            @error = e
+          end
+        end
+      end
+
+      # Called by {Console#paint} from the dispatcher's own thread, exactly
+      # as {Screen#draw} is. Stores the board; the ratatui thread picks it
+      # up on its own next tick, a fraction of a frame later.
+      #
+      # @param board [Agentilda::Board]
+      # @return [void]
+      def draw(board) = @mutex.synchronize { @board = board }
+
+      # @return [void]
+      def close
+        @closing = true
+        @thread&.join
+        @thread = nil
+        UI.line("ratatui backend failed: #{@error.message} (the run itself continued; nothing was drawn)") if @error
+      end
+
+      # @param tui [RatatuiRuby::TUI]
+      # @return [void]
+      def run_loop(tui)
+        # `TableState.new`'s documented `selected = nil` default isn't
+        # honored by the native binding — it raises ArgumentError given
+        # zero arguments (see spec/agentilda/screen/ratatui_spec.rb's own
+        # `table_state` let) — so the nil has to be explicit.
+        table_state = tui.table_state(nil)
+        tick(tui, table_state) until @closing
+      end
+
+      # One frame: draw the latest board, sample the sparkline, forward the
+      # next key. Public so the lifecycle spec can drive it without needing
+      # to manage the `until @closing` loop.
+      #
+      # @param tui [RatatuiRuby::TUI]
+      # @param table_state [RatatuiRuby::TableState]
+      # @return [void]
+      def tick(tui, table_state)
+        board = @mutex.synchronize { @board }
+        unless board
+          # `tui.poll_event` below is what paces this loop (ratatui's
+          # default poll timeout is ~16ms); returning ahead of it, as here,
+          # would otherwise spin a CPU core flat out until the dispatcher's
+          # first paint.
+          sleep(0.05)
+          return
+        end
+
+        sample(board)
+        tui.draw { |frame| render(tui, frame, frame.area, board, table_state) }
+        forward(tui.poll_event)
+      end
+
+      # @param tui [RatatuiRuby::TUI]
+      # @param frame [RatatuiRuby::Frame]
+      # @param area [RatatuiRuby::Layout::Rect]
+      # @param board [Agentilda::Board]
+      # @param table_state [RatatuiRuby::TableState]
+      # @return [void]
+      def render(tui, frame, area, board, table_state)
+        sync_selection(board, table_state)
+        _, top, _, table_area, bottom = tui.layout_split(area,
+          direction:   :vertical,
+          constraints: [tui.constraint_length(1), tui.constraint_length(1), tui.constraint_length(1),
+                        tui.constraint_fill(1), tui.constraint_length(1)])
+        _bottom_text, bottom_spark = tui.layout_split(bottom,
+          direction:   :horizontal,
+          constraints: [tui.constraint_fill(3), tui.constraint_fill(1)])
+
+        frame.render_widget(top_bar(tui, board), top)
+        frame.render_stateful_widget(table(tui, board), table_area, table_state)
+        render_activities(tui, frame, table_area, board, table_state)
+        # The bar is painted across the whole strip first, sparkline area
+        # included, so the cyan reaches both edges; the sparkline is then
+        # drawn over its right-hand share of it, in the same colors.
+        frame.render_widget(bottom_bar(tui, board), bottom)
+        frame.render_widget(tui.sparkline(data: @history, style: tui.style(fg: :black, bg: :cyan)), bottom_spark)
+        render_overlay(tui, frame, area, board)
+      end
+
+      # @param board [Agentilda::Board]
+      # @return [void]
+      def sample(board)
+        now = UI.monotonic
+        return if @last_sample && now - @last_sample < SAMPLE_INTERVAL
+
+        @last_sample = now
+        @history << board.running
+        @history.shift while @history.size > HISTORY
+      end
+
+      # @param event [RatatuiRuby::Event]
+      # @return [void]
+      def forward(event)
+        key = KeyTranslator.call(event) or return
+        @keyboard&.handle(key)
+      end
+
+      private
+
+      # @param board [Agentilda::Board]
+      # @param table_state [RatatuiRuby::TableState]
+      # @return [void]
+      def sync_selection(board, table_state)
+        index = board.selected && board.rows.index { |r| r.key == board.selected }
+        table_state.select(index)
+      end
+
+      # @return [RatatuiRuby::Widgets::Paragraph]
+      def top_bar(tui, board)
+        tui.paragraph(
+          text:  "#{board.status} · plans: #{board.plans.join(", ")} " \
+                 "· tokens ↑#{UI.abbreviate(board.up)} ↓#{UI.abbreviate(board.down)}",
+          style: tui.style(fg: :black, bg: :cyan)
+        )
+      end
+
+      # @return [RatatuiRuby::Widgets::Paragraph]
+      def bottom_bar(tui, board)
+        tui.paragraph(
+          text:  "working in #{board.root} · agents running: #{board.running} " \
+                 "· live ↑#{UI.abbreviate(board.live_up)} ↓#{UI.abbreviate(board.live_down)}",
+          style: tui.style(fg: :black, bg: :cyan)
+        )
+      end
+
+      # @return [RatatuiRuby::Widgets::Table]
+      def table(tui, board)
+        tui.table(header: HEADER,
+          rows: board.rows.map { |row| table_row(tui, row) },
+          widths: COLUMNS.map { |w| tui.constraint_length(w) },
+          highlight_symbol: HIGHLIGHT_SYMBOL,
+          highlight_spacing: :always,
+          row_highlight_style: tui.style(modifiers: [:reversed]))
+      end
+
+      # Lines one agent takes: its table row, then its statuses.
+      #
+      # @return [Integer]
+      def row_height = 1 + scroll_height
+
+      # Paints each visible agent's latest statuses over the empty lines
+      # under its table row, newest first: the newest bold, the rest plain,
+      # all yellow. A table cell cannot span columns, so a status would
+      # otherwise be clipped to one column's width; drawn on top, it gets
+      # everything from the feature column to {ACTIVITY_MARGIN} cells before
+      # the right edge, and a longer status ends in an ellipsis.
+      #
+      # @return [void]
+      def render_activities(tui, frame, table_area, board, table_state)
+        width = table_area.width - ACTIVITY_INDENT - ACTIVITY_MARGIN
+        return if width <= 0
+
+        bottom = table_area.y + table_area.height
+        board.rows.drop(table_state.offset.to_i).each_with_index do |row, index|
+          # +1 for the header line, +1 more to land under the row's own line.
+          top = table_area.y + 1 + (index * (row_height + ROW_GAP)) + 1
+          break if top >= bottom
+
+          statuses(row).each_with_index do |text, line|
+            y = top + line
+            break if y >= bottom
+
+            modifiers = line.zero? ? [:bold] : []
+            frame.render_widget(
+              tui.paragraph(text: ellipsize(text, width), style: tui.style(fg: :yellow, modifiers:)),
+              tui.rect(x: table_area.x + ACTIVITY_INDENT, y:, width:, height: 1)
+            )
+          end
+        end
+      end
+
+      # @param text [String]
+      # @param width [Integer] cells available
+      # @return [String] the text, or its head and an ellipsis within +width+
+      def ellipsize(text, width) = text.length > width ? "#{text[0, width - 1]}…" : text
+
+      # @param row [Agentilda::Board::Row]
+      # @return [Array<String>] newest first, at most {#scroll_height}
+      def statuses(row)
+        lines = row.history.empty? ? [row.message.to_s] : row.history
+        lines.first(scroll_height)
+      end
+
+      # @return [RatatuiRuby::Widgets::Row]
+      def table_row(tui, row)
+        tui.row(height: row_height,
+          bottom_margin: ROW_GAP,
+          cells: [
+            row.at.strftime("%H:%M:%S"),
+            row.ordinal,
+            row.file,
+            tui.text_span(content: row.agent, style: tui.style(fg: :yellow, modifiers: [:bold])),
+            "R:#{row.round}/#{row.rounds}",
+            row.model.to_s,
+            row.subagents.to_s,
+            "↑#{UI.abbreviate(row.up)} ↓#{UI.abbreviate(row.down)}",
+            Bar.cell(tui, row.elapsed, Bar.elapsed_color(row.elapsed)),
+            Bar.cell(tui, row.remaining, Bar.remaining_color(row.remaining))
+          ])
+      end
+
+      # @return [void]
+      def render_overlay(tui, frame, area, board)
+        text = board.dialog || board.help || board.about or return
+        title = if board.dialog
+                  "Agent"
+                else
+                  (board.help ? "Keys" : "About")
+                end
+        lines = text.lines.size + 4
+        width = [text.lines.map { |l| l.chomp.length }.max.to_i + 6, area.width].min
+        overlay_area = tui.rect(x: [(area.width - width) / 2, 0].max,
+          y: [(area.height - lines) / 2, 0].max,
+          width:,
+          height: lines)
+        frame.render_widget(tui.paragraph(text:, block: tui.block(title:, borders: [:all])), overlay_area)
+      end
+    end
+  end
+end

data/lib/agentilda/state_file.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Agentilda
+  # Where a run stands, written every second, so a harness that dies leaves
+  # the next one something to restart from.
+  #
+  # 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.
+  class StateFile
+    FILENAME = "agentilda-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.
+    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 = ["#{Agentilda::PLANS_DIR}/#{FILENAME}", "#{Agentilda::PLANS_DIR}/#{FILENAME}.*.tmp"].freeze
+
+    # @param tree [Agentilda::Tree]
+    # @return [String]
+    def self.for(tree) = File.join(tree.dir, FILENAME)
+
+    # @param tree [Agentilda::Tree]
+    # @return [String] where {LEGACY_DIRNAME} put it
+    def self.legacy_for(tree) = 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.
+    #
+    # @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)
+
+      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")
+      true
+    end
+
+    # @param path [String]
+    # @param pid [Integer] this run's process id
+    def initialize(path:, pid: Process.pid)
+      @path = path
+      @pid = pid
+      @data = { "run" => {}, "plans" => {} }
+      @mutex = Mutex.new
+    end
+
+    # @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.
+    #
+    # @return [String]
+    def legacy_path = 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
+    # to the run that picks it up, and {#stranded} would report no stranded
+    # stages for a harness that died with several.
+    #
+    # @return [self]
+    def load
+      @mutex.synchronize do
+        source = [path, legacy_path].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
+      self
+    rescue JSON::ParserError
+      self
+    end
+
+    # Written whole to a sibling and renamed over, so a reader never sees
+    # half a file.
+    #
+    # @return [void]
+    def save
+      @mutex.synchronize do
+        FileUtils.mkdir_p(File.dirname(path))
+        temp = "#{path}.#{@pid}.tmp"
+        File.write(temp, JSON.pretty_generate(@data))
+        File.rename(temp, path)
+      end
+    end
+
+    # @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 }
+      end
+    end
+
+    # @return [void]
+    def heartbeat!
+      @mutex.synchronize { @data["run"]["heartbeat_at"] = Time.now.iso8601 }
+    end
+
+    # @param ordinal [String]
+    # @param agent [String]
+    # @param round [Integer]
+    # @param fields [Hash] anything else worth keeping: status, model, file,
+    #   pid, up, down, state, next, exit
+    # @return [void]
+    def record(ordinal, agent:, round:, **fields)
+      @mutex.synchronize do
+        plan = (@data["plans"][ordinal.to_s] ||= { "stages" => [] })
+        stage = plan["stages"].find { |s| s["agent"] == agent && s["round"] == round }
+        unless stage
+          stage = { "agent" => agent, "round" => round, "run_pid" => @pid }
+          plan["stages"] << stage
+        end
+        fields.each { |key, value| stage[key.to_s] = value }
+      end
+    end
+
+    # @param ordinal [String]
+    # @return [Array<Hash>]
+    def stages(ordinal) = @mutex.synchronize { (@data.dig("plans", ordinal.to_s, "stages") || []).map(&:dup) }
+
+    # @return [Array<String>] every ordinal with a stage recorded
+    def plans = @mutex.synchronize { @data["plans"].keys }
+
+    # @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
+
+      Process.kill(0, previous)
+      false
+    rescue Errno::ESRCH, Errno::EPERM
+      true
+    end
+
+    # Stages a dead run left `Started`. Each is an agent that was cut off
+    # mid-flight and has to be re-run, with the harness's own Interrupted
+    # line written so the document agrees with this file.
+    #
+    # @return [Array<Array(String, Hash)>] ordinal and stage
+    def stranded
+      return [] unless previous_run_dead?
+
+      @mutex.synchronize do
+        @data["plans"].flat_map { |ordinal, plan|
+          plan["stages"].select { |s| s["status"] == "Started" && s["run_pid"] != @pid }
+                        .map { |s| [ordinal, s.dup] }
+        }
+      end
+    end
+  end
+end

data/lib/agentilda/state_machine.rb

@@ -2,6 +2,8 @@
 
 require "aasm"
 
+require "agentilda/status"
+
 module Agentilda
   # The state machine for one plan folder.
   #
@@ -34,18 +36,19 @@ module Agentilda
     # work back through both halves of building, it does not skip the reviewer
     # and it does not assume the half nobody complained about still holds.
     SPINE = {
-      retroactive: :planned,
-      new: :researched,
-      researched: :planned,
-      planned: :building,
-      building: :building_ui,
-      building_ui: :ready_for_review,
-      ready_for_review: :in_review,
-      in_review: :approved,
-      approved: :deployed,
-      rejected: :building_ui,
-      rolled_back: :ready_for_review,
-      shit: :planned
+      retroactive:        :planned,
+      new:                :researched,
+      researched:         :ready_for_planning,
+      ready_for_planning: :planned,
+      planned:            :building,
+      building:           :building_ui,
+      building_ui:        :ready_for_review,
+      ready_for_review:   :in_review,
+      in_review:          :approved,
+      approved:           :deployed,
+      rejected:           :building_ui,
+      rolled_back:        :ready_for_review,
+      shit:               :planned
     }.freeze
 
     # Preference order when several states fit a folder's contents at once.
@@ -54,7 +57,7 @@ module Agentilda
     # absence of documents rather than the presence of any.
     PREFERENCE = %i[
       discarded rolled_back shit deferred blocked product_blocked
-      deployed approved rejected in_review ready_for_review building planned
+      deployed approved rejected in_review ready_for_review building_ui building planned ready_for_planning
       researched new
       retroactive
     ].freeze
@@ -66,18 +69,19 @@ module Agentilda
     # ⭕️ and 🅱️ both mean "a human must decide before this moves"; *which*
     # human is recorded nowhere but the emoji.
     #
-    # 🟡 🟢 👀 🔴 all look identical on disk — a `plan.md` and some open pull
-    # requests. Whether someone is still building, CI is green and a reviewer
-    # is wanted, a reviewer is reading it, or a reviewer asked for changes is
-    # not written down anywhere a program could read. So `resync` never moves
-    # between them; they advance by events alone.
+    # ⭐️ 🟡 🎨 look identical on disk: a `spec.md` and a `plan.md` with work
+    # units in it. Whether nobody has started, the back end is under way, or
+    # the interface is, is recorded only by the agent that renamed the folder
+    # when it started. 🟢 👀 🔴 add an open pull request and are just as
+    # mute about whether a reviewer has seen it. So `resync` never moves
+    # between any of them; they advance by events alone.
     #
-    # Order matters: the first member is the *weakest claim* in the family, and
-    # it is where a folder arriving from outside lands. Contents that fit the
-    # family justify only its floor, never its ceiling.
+    # Order matters: the members run weakest claim first, and a folder
+    # arriving from outside lands on the weakest member its contents fit.
+    # Contents that fit the family justify only its floor, never its ceiling.
     FAMILIES = [
       %i[blocked product_blocked],
-      %i[building ready_for_review in_review rejected]
+      %i[planned building building_ui ready_for_review in_review rejected]
     ].freeze
 
     # States the agent loop leaves alone: work that is finished (✅ 😎), work
@@ -95,6 +99,14 @@ module Agentilda
     # `approved -> deployed`, and today nothing does.
     SETTLED = %i[approved deployed discarded blocked product_blocked deferred].freeze
 
+    # Every state an agent that may sign `Blocked` works in. A block the
+    # machine refuses is reported as a failed attempt and parks nothing, so a
+    # state missing here turns an honest "I need a decision" into a failure.
+    # The agents spec checks every prompt that describes blocking against it.
+    #
+    # Review is absent: a reviewer rules, it does not ask.
+    BLOCKABLE = %i[new researched retroactive ready_for_planning planned building building_ui rejected].freeze
+
     # Rerouting a transition below makes the hand-drawn
     # `docs/img/plan-spec-build.png` stale — `just docs` will show you, because
     # the mermaid source in the generated document is derived from this block.
@@ -111,13 +123,22 @@ module Agentilda
         transitions from: %i[new retroactive blocked product_blocked deferred], to: :researched
       end
 
+      # The specification is done and the planner has not started. Entered
+      # by the harness when `yoda-writer` completes; `resync` reaches it on
+      # a blank `plan.md`. Without it ⭐️ Planned required a file only the
+      # agent handling ⭐️ Planned writes, and nothing could enter it.
+      event :ready_to_plan, guard: :justified? do
+        transitions from: %i[researched new retroactive shit blocked product_blocked deferred],
+          to: :ready_for_planning
+      end
+
       # `new` stays in this list. The spine routes a plan through research, and
       # that is what the agent loop follows — but a specification somebody has
       # already researched by hand should not have to pretend otherwise to get
       # planned. What research buys is not enforced here; it is enforced by
       # `yoda-writer` handling `researched` and nothing else.
       event :plan, guard: :justified? do
-        transitions from: %i[researched new retroactive shit blocked product_blocked deferred],
+        transitions from: %i[ready_for_planning researched new retroactive shit blocked product_blocked deferred],
           to: :planned
       end
 
@@ -136,8 +157,10 @@ module Agentilda
         transitions from: %i[building rejected], to: :building_ui
       end
 
+      # The pair lands one pull request, and whichever half finishes last
+      # carries the plan to review from wherever the folder stands.
       event :submit, guard: :justified? do
-        transitions from: %i[building_ui rolled_back], to: :ready_for_review
+        transitions from: %i[building building_ui rejected rolled_back], to: :ready_for_review
       end
 
       event :review, guard: :justified? do
@@ -169,15 +192,15 @@ module Agentilda
       end
 
       event :block, guard: :justified? do
-        transitions from: %i[new planned building], to: :blocked
+        transitions from: BLOCKABLE, to: :blocked
       end
 
       event :block_on_product, guard: :justified? do
-        transitions from: %i[new planned building], to: :product_blocked
+        transitions from: BLOCKABLE, to: :product_blocked
       end
 
       event :defer, guard: :justified? do
-        transitions from: %i[new planned building blocked product_blocked], to: :deferred
+        transitions from: BLOCKABLE + %i[blocked product_blocked], to: :deferred
       end
 
       # Anything, from anywhere, may be dropped for good.
@@ -310,10 +333,12 @@ module Agentilda
     #
     # - **Already inside one** — the current name wins. Re-deriving it would be
     #   a guess dressed up as a correction, and every ⭕️ would become 🅱️.
-    # - **Arriving from outside** — the family's *first* member wins, not the
-    #   furthest. A ✅ folder found with an open pull request is demonstrably
-    #   back in the PR phase; nothing shows whether a reviewer has seen it, so
-    #   it lands on 🟡 rather than claiming 🔴.
+    # - **Arriving from outside** — the *weakest* member the contents fit
+    #   wins, not the furthest. A 📋 folder whose `plan.md` grew work units
+    #   lands on ⭐️, not 🟡, because nobody has started. A ✅ folder found
+    #   with an open pull request is demonstrably back in the PR phase, and
+    #   ⭐️ refuses an open pull request, so it lands on 🟡 rather than
+    #   claiming 🔴.
     #
     # @return [Agentilda::Status, nil] nil when nothing fits at all
     def best_fit
@@ -324,7 +349,10 @@ module Agentilda
       return status if self.class.family_of(key).include?(best.key)
 
       family = self.class.family_of(best.key)
-      family.empty? ? best : STATUS_BY_KEY.fetch(family.first)
+      return best if family.empty?
+
+      floor = family.find { |k| fitting.any? { |s| s.key == k } }
+      STATUS_BY_KEY.fetch(floor)
     end
 
     private