agentilda 2.0.3 → 2.0.4

data/lib/agentilda/ledger.rb

@@ -1,233 +0,0 @@
-# frozen_string_literal: true
-
-require "time"
-
-module Agentilda
-  # The dated notes an agent leaves in the document it owns.
-  #
-  # This is the only place in the codebase that knows the syntax. The
-  # dispatcher reads it to learn whether an agent finished and who it named
-  # next; the state file records it; the screen paints it. An agent writes
-  # one entry when it starts and one when it stops, in a GitHub NOTE alert,
-  # one entry per line:
-  #
-  #   > [!NOTE]
-  #   >
-  #   > [2026-09-04 11:29:20 AM PDT] [ agent: leah-researcher   status: Started, round 1 ]
-  #   > [2026-09-04 11:44:03 AM PDT] [ agent: leah-researcher   status: Completed, round 1 ]
-  #   > [2026-09-04 11:44:04 AM PDT] [ next: yoda-writer ]
-  #
-  # The verbs are a closed set. A line that looks like an entry but does not
-  # parse is reported as a {Problem}, never dropped, because an agent that
-  # wrote "Done" has said nothing the harness can act on and silence would
-  # read as a stall.
-  module Ledger
-    # Everything an agent may claim. `Completed` is the only verb a `next:`
-    # line may follow.
-    STATUSES = ["Started", "Completed", "Almost completed", "Interrupted", "Blocked"].freeze
-
-    # Local time with the zone spelled out, so an entry written on one
-    # machine reads correctly on another.
-    TIME_FORMAT = "%Y-%m-%d %I:%M:%S %p %Z"
-
-    # An entry. `**` around the status is how the harness marks the one line
-    # it writes itself, the Interrupted that precedes a signature.
-    ENTRY = /\A>\s*\[(?<at>[^\]]+)\]\s*\[\s*agent:\s*(?<agent>[\w-]+)\s+status:\s*(?<bold>\*\*)?
-      (?<status>#{STATUSES.map { |s| Regexp.escape(s) }.join("|")}),\s*round\s*(?<round>\d+)
-      (?:\s*\((?<note>[^)]*)\))?\s*(?:\*\*)?\s*\]\s*\z/x
-
-    # The handoff line.
-    NEXT = /\A>\s*\[(?<at>[^\]]+)\]\s*\[\s*next:\s*(?<next>[\w-]+)\s*\]\s*\z/
-
-    # A line that is trying to be one of the two above. Anything matching
-    # this and neither of those is a {Problem}.
-    ATTEMPT = /\A>\s*\[[^\]]+\]\s*\[/
-
-    # The whole alert block, for {.stripped}.
-    BLOCK = /^[ \t]*>[ \t]*\[!NOTE\][ \t]*\n(?:[ \t]*>.*\n?)*/
-
-    # @!attribute [r] at
-    #   @return [Time]
-    # @!attribute [r] agent
-    #   @return [String] the definition's name, `leah-researcher`
-    # @!attribute [r] status
-    #   @return [String] one of {STATUSES}
-    # @!attribute [r] round
-    #   @return [Integer]
-    # @!attribute [r] note
-    #   @return [String, nil] the parenthesised tail, `rejected 1/2`
-    # @!attribute [r] file
-    #   @return [String] the document it was read from
-    # @!attribute [r] line
-    #   @return [Integer] 1-based
-    # @!attribute [r] bold
-    #   @return [Boolean] written `**bold**`, which only the harness does
-    Entry = Data.define(:at, :agent, :status, :round, :note, :file, :line, :bold) do
-      def initialize(note: nil, bold: false, **rest) = super
-
-      # @return [Boolean]
-      def completed? = status == "Completed"
-
-      # @return [Boolean] whether the agent gets another round
-      def retry? = ["Almost completed", "Interrupted"].include?(status)
-
-      # @return [Boolean]
-      def blocked? = status == "Blocked"
-    end
-
-    # @!attribute [r] next
-    #   @return [String] the agent named
-    Handoff = Data.define(:at, :next, :file, :line)
-
-    # @!attribute [r] text
-    #   @return [String] the line as written
-    Problem = Data.define(:file, :line, :text)
-
-    # What one read of a plan folder yielded.
-    Reading = Data.define(:entries, :handoffs, :problems) do
-      # @return [Agentilda::Ledger::Reading]
-      def self.empty = new(entries: [], handoffs: [], problems: [])
-
-      # @param other [Agentilda::Ledger::Reading]
-      # @return [Agentilda::Ledger::Reading]
-      def +(other)
-        self.class.new(entries: entries + other.entries,
-          handoffs: handoffs + other.handoffs,
-          problems: problems + other.problems)
-      end
-    end
-
-    class << self
-      # @param text [String] a whole document
-      # @param file [String] its name, carried on every entry
-      # @return [Agentilda::Ledger::Reading]
-      def parse(text, file:)
-        entries = []
-        handoffs = []
-        problems = []
-        text.to_s.each_line.with_index(1) do |raw, line|
-          stripped = raw.chomp
-          if (m = ENTRY.match(stripped))
-            entries << Entry.new(at: parse_time(m[:at]),
-              agent: m[:agent],
-              status: m[:status],
-              round: m[:round].to_i,
-              note: m[:note]&.strip,
-              file:,
-              line:,
-              bold: !m[:bold].nil?)
-          elsif (m = NEXT.match(stripped))
-            handoffs << Handoff.new(at: parse_time(m[:at]), next: m[:next], file:, line:)
-          elsif ATTEMPT.match?(stripped)
-            problems << Problem.new(file:, line:, text: stripped.strip)
-          end
-        end
-        Reading.new(entries:, handoffs:, problems:)
-      end
-
-      # Every document an agent may sign, in the order its definition lists
-      # them. A missing file is not a problem; an agent that has not reached
-      # `pull-requests.md` yet has not written it.
-      #
-      # @param dir [String] the plan folder
-      # @param files [Array<String>]
-      # @return [Agentilda::Ledger::Reading]
-      def read(dir, files)
-        files.each_with_index.reduce(Reading.empty) do |reading, (name, _index)|
-          path = File.join(dir, name)
-          next reading unless File.file?(path)
-
-          found = parse(File.read(path, encoding: "UTF-8"), file: name)
-          reading + Reading.new(entries: found.entries.map { |e| e.with(file: name) },
-            handoffs: found.handoffs,
-            problems: found.problems)
-        end
-      end
-
-      # @param time [Time]
-      # @return [String]
-      def timestamp(time = Time.now) = time.strftime(TIME_FORMAT)
-
-      # Agents write what `date` prints, and `Time.strptime` cannot read a
-      # zone abbreviation back into an offset. The abbreviation is dropped
-      # and the time read as local, which is right on the machine that wrote
-      # it and off by a zone anywhere else, which the tick tolerates: entries
-      # are compared with each other, never with the wall clock.
-      #
-      # @param text [String]
-      # @return [Time]
-      def parse_time(text)
-        Time.strptime(text.to_s.strip.sub(/\s+[A-Z]{2,5}\z/, ""), "%Y-%m-%d %I:%M:%S %p")
-      rescue ArgumentError
-        Time.at(0)
-      end
-
-      # @param entry [Agentilda::Ledger::Entry]
-      # @return [String] one quoted line, no newline
-      def render(entry)
-        tail = entry.note ? " (#{entry.note})" : ""
-        body = "#{entry.status}, round #{entry.round}#{tail}"
-        body = "**#{body}**" if entry.bold
-        "> [#{timestamp(entry.at)}] [ agent: #{entry.agent}   status: #{body} ]"
-      end
-
-      # @param handoff [Agentilda::Ledger::Handoff]
-      # @return [String]
-      def render_handoff(handoff) = "> [#{timestamp(handoff.at)}] [ next: #{handoff.next} ]"
-
-      # @param lines [Array<String>] already quoted
-      # @return [String] a NOTE alert, newline-terminated
-      def block(*lines) = (["> [!NOTE]", ">"] + lines.flatten).join("\n") + "\n"
-
-      # Append one block. Separated from what is there by a blank line so the
-      # alert renders as its own block rather than merging into a paragraph.
-      #
-      # @param path [String]
-      # @param lines [Array<String>]
-      # @return [void]
-      def append(path, *lines)
-        existing = File.file?(path) ? File.read(path, encoding: "UTF-8") : ""
-        glue = if existing.empty?
-                 ""
-               elsif existing.end_with?("\n\n")
-                 ""
-               elsif existing.end_with?("\n")
-                 "\n"
-               else
-                 "\n\n"
-               end
-        File.write(path, existing + glue + block(*lines))
-      end
-
-      # The entry that tells the harness where this agent stands: the latest
-      # by clock, then by the order its documents are listed, then by line.
-      #
-      # @param reading [Agentilda::Ledger::Reading]
-      # @param agent [String]
-      # @return [Agentilda::Ledger::Entry, nil]
-      def last_for(reading, agent)
-        files = reading.entries.map(&:file).uniq
-        reading.entries.select { |e| e.agent == agent }
-               .max_by { |e| [e.at, files.index(e.file), e.line] }
-      end
-
-      # The `next:` that belongs to an entry: same file, a later line, and no
-      # other entry between the two. A handoff written under somebody else's
-      # entry is not this agent's handoff.
-      #
-      # @param reading [Agentilda::Ledger::Reading]
-      # @param entry [Agentilda::Ledger::Entry]
-      # @return [Agentilda::Ledger::Handoff, nil]
-      def handoff_after(reading, entry)
-        candidates = reading.handoffs.select { |h| h.file == entry.file && h.line > entry.line }
-        handoff = candidates.min_by(&:line) or return nil
-        between = reading.entries.any? { |e| e.file == entry.file && e.line > entry.line && e.line < handoff.line }
-        between ? nil : handoff
-      end
-
-      # @param text [String]
-      # @return [String] the document without its ledger blocks
-      def stripped(text) = text.to_s.gsub(BLOCK, "")
-    end
-  end
-end

data/lib/agentilda/mailbox.rb

@@ -1,141 +0,0 @@
-# frozen_string_literal: true
-
-module Agentilda
-  # The one channel two agents on the same plan have to each other.
-  #
-  # `luke-backend` and `rey-frontend` build one plan in one worktree at the
-  # same time, but each is its own `claude -p` process. Claude Code can
-  # message between local sessions, and the prompts used to say so, but a
-  # session is named after its directory plus a random suffix, so a pair had
-  # to guess its partner from a list of every session on the machine by start
-  # time. It worked once, by luck. With ten plans running there would have
-  # been ten `agentilda-xx` entries and nothing to tell them apart.
-  #
-  # So the mailbox is a file in the plan folder, append-only, one numbered
-  # entry per message, readable by `agentilda mail read` during the round and
-  # by a person after it. The harness names the file and the partner in each
-  # agent's prompt, so nobody guesses.
-  class Mailbox
-    FILENAME = "mailbox.md"
-
-    # Between the fields of a heading. Neither a name nor a timestamp
-    # contains it, which is what makes the heading parseable.
-    SEPARATOR = " · "
-
-    # `## 3 · 2026-09-06 10:30:53 -0700 · rey-frontend → luke-backend`
-    HEADING = /\A\#\# (\d+) · (.+?) · (\S+) → (\S+)\s*\z/
-
-    TIME_FORMAT = "%Y-%m-%d %H:%M:%S %z"
-
-    # One entry.
-    #
-    # @!attribute [r] number
-    #   @return [Integer] 1-based, in order of writing
-    # @!attribute [r] at
-    #   @return [String] when, as {TIME_FORMAT} writes it
-    # @!attribute [r] from
-    #   @return [String] the agent that wrote it
-    # @!attribute [r] to
-    #   @return [String] the agent it is for
-    # @!attribute [r] body
-    #   @return [String]
-    Message = Data.define(:number, :at, :from, :to, :body) do
-      # @return [String] as it stands in the file
-      def to_s = "## #{number}#{SEPARATOR}#{at}#{SEPARATOR}#{from} → #{to}\n\n#{body.strip}\n"
-    end
-
-    # @param dir [String] the plan folder
-    def initialize(dir:)
-      @dir = dir
-    end
-
-    # @return [String] the plan folder
-    attr_reader :dir
-
-    # @return [String]
-    def path = File.join(dir, FILENAME)
-
-    # @return [Boolean]
-    def exist? = File.file?(path)
-
-    # Every message, in the order it was written.
-    #
-    # @return [Array<Agentilda::Mailbox::Message>]
-    def messages
-      return [] unless exist?
-
-      parse(File.read(path, encoding: "UTF-8"))
-    end
-
-    # What is waiting for one agent.
-    #
-    # @param name [String] the reader
-    # @param after [Integer] a number the reader has already seen; only
-    #   messages above it are returned
-    # @return [Array<Agentilda::Mailbox::Message>]
-    def for(name, after: 0)
-      messages.select { |m| m.to == name && m.number > after }
-    end
-
-    # Append one message and give it the next number.
-    #
-    # The append takes a lock on the file. Two agents finishing a unit in the
-    # same second would otherwise read the same last number and both write
-    # the one after it.
-    #
-    # @param from [String]
-    # @param to [String]
-    # @param body [String]
-    # @param at [Time]
-    # @return [Agentilda::Mailbox::Message] as written
-    # @raise [Agentilda::Error] on an empty body, which would be a heading
-    #   with nothing under it for the reader to act on, or on a sender or
-    #   recipient that is blank or holds whitespace: {HEADING} could not
-    #   parse such an entry back, so it would be written and never read
-    def append(from:, to:, body:, at: Time.now)
-      text = body.to_s.strip
-      raise Error, "a message needs a body" if text.empty?
-      raise Error, "a message needs --from and --to, each one agent name" unless name?(from) && name?(to)
-
-      File.open(path, File::RDWR | File::CREAT | File::APPEND, 0o644) do |f|
-        f.flock(File::LOCK_EX)
-        f.rewind
-        existing = f.read
-        number = (parse(existing).last&.number || 0) + 1
-        message = Message.new(number:, at: at.strftime(TIME_FORMAT), from:, to:, body: text)
-        f.write(existing.empty? ? "# Mailbox\n\n#{message}" : "\n#{message}")
-        message
-      end
-    end
-
-    private
-
-    # @param value [Object]
-    # @return [Boolean] one token, as {HEADING} expects a name to be
-    def name?(value) = value.to_s.match?(/\A\S+\z/)
-
-    # Only a line shaped exactly like {HEADING} starts a message, so a body
-    # may hold headings of its own, code, anything.
-    #
-    # @param text [String]
-    # @return [Array<Agentilda::Mailbox::Message>]
-    def parse(text)
-      messages = []
-      current = nil
-      body = []
-
-      text.to_s.each_line(chomp: true) do |line|
-        if (heading = HEADING.match(line))
-          messages << current.with(body: body.join("\n").strip) if current
-          current = Message.new(number: heading[1].to_i, at: heading[2], from: heading[3], to: heading[4], body: "")
-          body = []
-        elsif current
-          body << line
-        end
-      end
-
-      messages << current.with(body: body.join("\n").strip) if current
-      messages
-    end
-  end
-end

data/lib/agentilda/ordinal.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-module Agentilda
-  # A plan's number, and therefore its identity. Set once when the folder is
-  # created and never changed: branch names, pull request titles and every
-  # `pull-requests.md` join on it, and renumbering breaks all of them silently.
-  #
-  # Always rendered `NNN.MM`. `002.00` is an ordinary plan, specified before it
-  # was built. `002.01` is retroactive — work that shipped between 002 and 003
-  # and was documented afterwards. The decimal marks a **sibling**, not
-  # containment: 002.01 is not part of 002.
-  #
-  # `000` is where the sequence starts, so the first plan of a project is
-  # `000.00`. It also absorbs the older meaning — work that predates the plan
-  # discipline — since either way it sorts first, which is where it belongs.
-  #
-  # @!attribute [r] major
-  #   @return [Integer] 0..999
-  # @!attribute [r] minor
-  #   @return [Integer] 0..99; zero for an ordinary plan
-  class Ordinal < Data.define(:major, :minor)
-    include Comparable
-
-    # The canonical form, plus the bare `NNN` that trees written before this
-    # rule still use and must remain readable.
-    PATTERN = /\A(\d{1,3})(?:\.(\d{1,2}))?\z/
-
-    # The most retroactive slots a single gap can hold.
-    MAX_MINOR = 99
-
-    # @param text [String, nil] e.g. "3", "003", "003.00", "018.01"
-    # @return [Agentilda::Ordinal, nil] nil when it is not a plan number
-    def self.parse(text)
-      m = PATTERN.match(text.to_s.strip)
-      m && new(major: m[1].to_i, minor: m[2].to_i)
-    end
-
-    # Pull the number off the front of a folder name.
-    #
-    # @param dirname [String] e.g. "018.01-✅--verify-against-filed-returns"
-    # @return [Agentilda::Ordinal, nil]
-    def self.from_dirname(dirname) = parse(dirname.to_s[/\A[\d.]+/])
-
-    # The next ordinary plan after everything in +existing+.
-    #
-    # The first plan in an empty tree is `000.00`, not `001.00`: the sequence
-    # counts from zero so that the very first specification — usually the
-    # project's own — sorts above everything and needs no gap reserved for it.
-    #
-    # @param existing [Array<Agentilda::Ordinal>]
-    # @return [Agentilda::Ordinal]
-    def self.next_major(existing)
-      return new(major: 0, minor: 0) if existing.empty?
-
-      new(major: existing.map(&:major).max + 1, minor: 0)
-    end
-
-    # The next retroactive slot in the gap after +major+.
-    #
-    # @param existing [Array<Agentilda::Ordinal>]
-    # @param major [Integer] the plan the work landed after
-    # @return [Agentilda::Ordinal]
-    # @raise [Agentilda::Error] when the gap is full
-    def self.next_minor(existing, major:)
-      taken = existing.select { |o| o.major == major }.map(&:minor).max || 0
-      if taken >= MAX_MINOR
-        raise Error, "all #{MAX_MINOR} retroactive slots after #{format("%03d", major)} are taken"
-      end
-
-      new(major:, minor: taken + 1)
-    end
-
-    # @return [Boolean] whether this plan was documented after the fact
-    def retroactive? = minor.positive?
-
-    # @return [String] the canonical `NNN.MM`
-    def to_s = format("%03d.%02d", major, minor)
-
-    # @return [String] what a pull request title carries
-    def to_prefix = "[#{self}]"
-
-    # @param other [Object]
-    # @return [Integer, nil]
-    def <=>(other)
-      return nil unless other.is_a?(self.class)
-
-      [major, minor] <=> [other.major, other.minor]
-    end
-  end
-end

data/lib/agentilda/progress_log.rb

@@ -1,126 +0,0 @@
-# frozen_string_literal: true
-
-require "agentilda/status"
-require "agentilda/ui"
-
-module Agentilda
-  # One line of `run --log FILE`, laid out as fixed-width columns.
-  #
-  # The log file is the only record of a headless run, and it is shared: two
-  # `agentilda run` invocations pointed at the same `--log` both append to
-  # it, interleaved, and so does every round within one run. That is what the
-  # process id column is for. Without it a reader cannot tell one run's agents
-  # from another's, and "started 003.00" twice looks like a bug rather than two
-  # machines doing the same work.
-  #
-  # Fixed columns are what make the file readable by eye and by `awk` alike. A
-  # value wider than its column is cut rather than allowed to push the columns
-  # out, and a value that is missing still occupies its width, so a round header
-  # with no plan or agent of its own lines up with the lines underneath it.
-  #
-  # @example
-  #   ProgressLog.render("editing spec.md", plan: "003.00", status: "⭐️ Planned",
-  #     agent: "yoda-writer", seconds: 42, round: "01", pid: 91_234)
-
-  #   #=> "[16:22:14 | 003.00 | ⭐️ Planned            | yoda-writer          | 01 |   91234 |    42s] editing spec.md"
-  module ProgressLog
-    # Wall clock only. A log line answers "when", and the date is the file's.
-    TIME_FORMAT = "%H:%M:%S"
-
-    # Width of {TIME_FORMAT}'s output.
-    TIME_WIDTH = 8
-
-    # "003.00".
-    PLAN_WIDTH = 6
-
-    # Derived from the widest state as {Status#to_s} renders it, emoji
-    # included, so a state added to {STATUSES} with a longer label cannot
-    # silently knock the columns after it out of line — then trimmed by five
-    # cells: the emoji already names the state, so the longest labels can
-    # afford to lose their tails to keep the line short.
-    STATUS_WIDTH = STATUSES.map { |status| UI.display_width(status.to_s) }.max - 5
-
-    # The longest specialist name in `agents/` is `palpatine-planner` at 17,
-    # and the names are hyphenated words rather than a bounded vocabulary, so
-    # this leaves room for one more without a reflow.
-    AGENT_WIDTH = 20
-
-    # Enough for a 32-bit process id, right justified.
-    PID_WIDTH = 7
-
-    # "01". Rounds cap at two digits; a run that reaches a third has bigger
-    # problems than this column.
-    ROUND_WIDTH = 2
-
-    # "  907s". Anything longer than four digits of seconds is an agent nobody
-    # is still waiting on.
-    SECONDS_WIDTH = 6
-
-    # Between columns, inside the brackets.
-    SEPARATOR = " | "
-
-    # Cells from the opening bracket to the closing one, separators included.
-    # The message starts one space after this on every line, whatever fields
-    # that line happens to be missing, so a reader indenting a wrapped message
-    # has a number to indent by.
-    COLUMN_WIDTHS = [TIME_WIDTH, PLAN_WIDTH, STATUS_WIDTH, AGENT_WIDTH, ROUND_WIDTH, PID_WIDTH,
-                     SECONDS_WIDTH].freeze
-
-    # @see COLUMN_WIDTHS
-    LINE_WIDTH = COLUMN_WIDTHS.sum + (SEPARATOR.length * (COLUMN_WIDTHS.size - 1)) + 2
-
-    class << self
-      # Render one log line: bracketed fixed-width columns, then the message.
-      #
-      # No colour. The line goes to a file, where an escape sequence is neither
-      # readable nor the width it claims to be.
-      #
-      # @param message [String] the free-form tail, the only variable-width part
-      # @param plan [String, nil] the plan's ordinal, e.g. "003.00"
-      # @param status [String, nil] emoji and label, e.g. "⭐️ Planned"
-      # @param agent [String, nil] the specialist's name, e.g. "yoda-writer"
-      # @param seconds [Numeric, nil] how long this agent has been alive
-      # @param round [String, nil] which pass over the tree, e.g. "01"
-      # @param pid [Integer, nil] which run wrote the line
-      # @param at [Time] injectable, so a caller can render a fixed clock
-      # @return [String] one line, with no trailing newline
-      def render(message, plan: nil, status: nil, agent: nil, seconds: nil,
-        round: nil, pid: Process.pid, at: Time.now)
-        columns = [
-          left(at.strftime(TIME_FORMAT), TIME_WIDTH),
-          left(plan, PLAN_WIDTH),
-          left(status, STATUS_WIDTH),
-          left(agent, AGENT_WIDTH),
-          right(round, ROUND_WIDTH),
-          right(pid, PID_WIDTH),
-          right(duration(seconds), SECONDS_WIDTH)
-        ]
-
-        text = message.to_s
-        prefix = "[#{columns.join(SEPARATOR)}]"
-        text.empty? ? prefix : "#{prefix} #{text}"
-      end
-
-      # @param seconds [Numeric, nil]
-      # @return [String] whole seconds with a trailing "s", or blank for nil
-      def duration(seconds) = seconds.nil? ? "" : "#{seconds.round}s"
-
-      # @param value [Object, nil]
-      # @param width [Integer] terminal cells
-      # @return [String] padded on the right to exactly +width+ cells
-      def left(value, width) = UI.fit(value, width)
-
-      # {UI.fit} pads on the right, which is the wrong end for a number. Fit
-      # first so an over-long value is still truncated to the column, then move
-      # the padding to the front.
-      #
-      # @param value [Object, nil]
-      # @param width [Integer] terminal cells
-      # @return [String] padded on the left to exactly +width+ cells
-      def right(value, width)
-        text = UI.fit(value, width).rstrip
-        UI.fit("", width - UI.display_width(text)) + text
-      end
-    end
-  end
-end