agentilda 1.0.3 → 2.0.0

data/lib/agentilda/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "dry/cli/autocomplete/command"
+require "tty-screen"
 
 # One file per command, `subcommands/` under the prefixed ones. Base carries
 # the shared flags and plumbing, so it loads first; the rest only meet each
@@ -21,6 +22,10 @@ require_relative "cli/version/version"
 require_relative "cli/states/states"
 require_relative "cli/agents/subcommands/list"
 require_relative "cli/agents/subcommands/describe"
+require_relative "cli/worktree/worktree"
+require_relative "cli/mail/mail"
+require_relative "cli/mail/subcommands/send"
+require_relative "cli/mail/subcommands/read"
 
 module Agentilda
   # The command line. Every command is a thin shell over one library class:
@@ -37,6 +42,37 @@ module Agentilda
   module CLI
     extend Dry::CLI::Registry
 
+    # What `agentilda -h` prints above and below the command list. Rendering,
+    # wrapping and colour belong to dry-cli-help; only the words live here.
+    # dry-cli-help 0.2 configures once per process, not per registry, which
+    # suits a gem with exactly one registry.
+    Dry::CLI::Help.configure do
+      title "agentilda — Agentic Specification-Driven Development v#{Agentilda::VERSION}"
+
+      description <<~TEXT
+        Drives the agentic flow: spec → plan → build → review → tune/fix → approve.
+
+        Keeps the .plans folders in step with GitHub pull requests and Linear issues.
+        The final merge and deploy stay manual.
+      TEXT
+
+      epilogue <<~TEXT.chomp
+        Global flags: -C, --no-color disables colour in every command.
+
+        Documentation: https://github.com/kigster/agentilda
+      TEXT
+
+      # The bare program prints this screen, and asking for help is not a failure.
+      exit_code_without_arguments 0
+
+      # Wrap at column 90, or two short of the terminal when it is narrower.
+      width [90, TTY::Screen.width - 2].min
+
+      group "Plans", "create", "list-plans", "index", "resync", "unblock", "worktree"
+      group "Agents", "run", "agents", "describe", "mail"
+      group "Reference", "docs", "states", "linear", "completion", "version"
+    end
+
     register "create", Create, aliases: %w[new c]
     # Renamed from `status`, which read as "is the tool OK?" rather than "what
     # plans are there?". The old spellings stay registered: other repos, agent
@@ -44,6 +80,7 @@ module Agentilda
     register "list-plans", ListPlans, aliases: %w[status st]
     register "run", Run
     register "unblock", Unblock
+    register "worktree", Worktree
     register "docs", Docs
     register "states", States, aliases: %w[diagram]
     register "index", Index, aliases: %w[idx]
@@ -69,6 +106,12 @@ module Agentilda
       prefix.register "projects", Linear::Projects
     end
 
+    # What a paired agent shells out to between steps. See {Agentilda::Mailbox}.
+    register "mail" do |prefix|
+      prefix.register "send", Mail::Send
+      prefix.register "read", Mail::Read
+    end
+
     register "completion", ::Dry::CLI::Autocomplete::Command[::Agentilda::CLI]
   end
 end

data/lib/agentilda/clock.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # The advisory clock one invocation runs against.
+  #
+  # It never terminates the agent on its own. It writes into the control file
+  # the agent polls: a warning ten and five minutes out, a wrap-up request at
+  # one, STOP at zero. Only a process still alive {GRACE} seconds after STOP
+  # is killed, and that is the executor's act on this clock's say-so, so the
+  # agent has every chance to write its ledger line first.
+  #
+  # `now` is injectable so the moments can be tested without sleeping.
+  class Clock
+    # Seconds before the deadline, and what the control file says then.
+    # A moment already in the past when the clock starts is skipped: a five
+    # minute agent told "10 minutes left" at t=0 has been lied to.
+    WARNINGS = [
+      [600, "WARN: 10 minutes left"],
+      [300, "WARN: 5 minutes left"],
+      [60, "WRAP_UP: 1 minute left, write to disk now"]
+    ].freeze
+
+    # Seconds after STOP before {#on_expire} fires.
+    GRACE = 60
+
+    # @param seconds [Integer] the budget
+    # @param control [String] the invocation's control file
+    # @param on_expire [Proc] called once, GRACE seconds after STOP
+    # @param now [Proc] a monotonic clock reading
+    def initialize(seconds:, control:, on_expire:, now: -> { UI.monotonic })
+      @control = control
+      @on_expire = on_expire
+      @now = now
+      @mutex = Mutex.new
+      arm(seconds)
+    end
+
+    # @return [Integer] whole seconds left, floored at zero
+    def remaining = [@deadline - @now.call, 0].max.round
+
+    # @return [Symbol] :calm, :warned, :wrap_up, :stopped or :expired
+    attr_reader :phase
+
+    # Evaluate every moment once. Idempotent within a phase.
+    #
+    # @return [void]
+    def tick
+      @mutex.synchronize do
+        left = @deadline - @now.call
+        WARNINGS.each do |before, text|
+          next if @fired.include?(before) || left > before
+
+          @fired << before
+          Control.write(@control, text)
+          @phase = before == 60 ? :wrap_up : :warned
+        end
+        if left <= 0 && !@fired.include?(:stop)
+          @fired << :stop
+          Control.write(@control, Control::STOP)
+          @phase = :stopped
+        end
+        if @fired.include?(:stop) && !@fired.include?(:expired) && left <= -GRACE
+          @fired << :expired
+          @phase = :expired
+          @on_expire.call
+        end
+      end
+    end
+
+    # @return [self]
+    def start
+      @thread ||= Thread.new do
+        Thread.current.report_on_exception = false
+        loop do
+          tick
+          break if phase == :expired
+
+          sleep(1)
+        end
+      end
+      self
+    end
+
+    # @return [void]
+    def stop
+      @thread&.kill
+      @thread = nil
+    end
+
+    # Ten more minutes, or however many. The file is emptied so the next poll
+    # reads a reprieve, and every moment is re-armed against the new deadline.
+    #
+    # @param seconds [Integer]
+    # @return [void]
+    def extend!(seconds)
+      @mutex.synchronize do
+        @deadline += seconds
+        @fired = []
+        @phase = :calm
+        Control.write(@control, "")
+      end
+    end
+
+    private
+
+    # @param seconds [Integer]
+    # @return [void]
+    def arm(seconds)
+      @deadline = @now.call + seconds
+      @fired = WARNINGS.map(&:first).select { |before| before >= seconds }
+      @phase = :calm
+    end
+  end
+end

data/lib/agentilda/console.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # What the keys do to the screen, and to the running agents.
+  #
+  # Selection and the dialog live here, never on the screen: the screen
+  # draws whatever board it is handed, and this decides what the board
+  # says. Pending changes are visible only in the dialog and take effect
+  # only on ENTER, so a stray `k` kills nobody.
+  class Console
+    # Seconds each `x` adds.
+    EXTENSION = 600
+
+    # @param screen [Agentilda::Screen::Ratatui]
+    def initialize(screen:)
+      @screen = screen
+      @dispatcher = nil
+      @board = nil
+      @selected = nil
+      @dialog = false
+      @help = false
+      @about = false
+      @pending = { kill: false, extend: 0 }
+      @mutex = Mutex.new
+    end
+
+    # @return [String, nil] the selected row's key
+    attr_reader :selected
+
+    # @return [Hash] `{kill: Boolean, extend: Integer}`
+    attr_reader :pending
+
+    # @return [Agentilda::Screen::Ratatui]
+    attr_reader :screen
+
+    # @return [Boolean]
+    def dialog? = @dialog
+
+    # @return [Boolean]
+    def help? = @help
+
+    # @return [Boolean]
+    def about? = @about
+
+    # The dispatcher exists only once the run starts, after the keyboard is
+    # already listening, so it arrives late.
+    #
+    # @param dispatcher [Agentilda::Dispatcher]
+    # @return [void]
+    def attach(dispatcher) = @dispatcher = dispatcher
+
+    # Called by the dispatcher each tick.
+    #
+    # @param board [Agentilda::Board]
+    # @return [void]
+    def paint(board)
+      @mutex.synchronize do
+        @board = board
+        @selected = nil if @selected && board.rows.none? { |r| r.key == @selected && r.running? }
+        @screen.draw(board.with(selected: @selected,
+          dialog: (dialog_text if @dialog),
+          help: (help_text if @help),
+          about: (about_text if @about)))
+      end
+    end
+
+    # @return [void]
+    def select_next = move(1)
+
+    # @return [void]
+    def select_prev = move(-1)
+
+    # @return [void]
+    def toggle_kill
+      select_next unless @selected
+      return unless @selected
+
+      @pending[:kill] = !@pending[:kill]
+      @dialog = true
+    end
+
+    # @return [void]
+    def extend
+      select_next unless @selected
+      return unless @selected
+
+      @pending[:extend] += EXTENSION
+      @dialog = true
+    end
+
+    # ENTER.
+    #
+    # @return [void]
+    def apply
+      return unless @dialog && @selected && @dispatcher
+
+      @dispatcher.kill(@selected) if @pending[:kill]
+      @dispatcher.extend(@selected, @pending[:extend]) if @pending[:extend].positive?
+      UI.log("applied to #{@selected}: #{dialog_text.tr("\n", ", ")}")
+      close_dialog
+    end
+
+    # ESC: the dialog first, then the help, then the about screen, then the
+    # selection.
+    #
+    # @return [void]
+    def escape
+      if @dialog
+        close_dialog
+      elsif @help
+        @help = false
+      elsif @about
+        @about = false
+      else
+        @selected = nil
+      end
+    end
+
+    # @return [void]
+    def toggle_help = @help = !@help
+
+    # @return [void]
+    def toggle_about = @about = !@about
+
+    private
+
+    # @return [void]
+    def close_dialog
+      @dialog = false
+      @pending = { kill: false, extend: 0 }
+    end
+
+    # @param step [Integer]
+    # @return [void]
+    def move(step)
+      keys = (@board&.rows || []).select(&:running?).map(&:key)
+      return @selected = nil if keys.empty?
+
+      index = keys.index(@selected)
+      @selected = index.nil? ? keys.first : keys[(index + step) % keys.size]
+    end
+
+    # @return [String]
+    def dialog_text
+      row = @board&.rows&.find { |r| r.key == @selected }
+      who = row ? "#{row.ordinal} #{row.agent}" : @selected.to_s
+      extension = @pending[:extend].positive? ? "+#{@pending[:extend] / 60}m" : "none"
+      "#{who}\n\nkill: #{@pending[:kill] ? "yes" : "no"}\nextend: #{extension}"
+    end
+
+    # @return [String]
+    def help_text = Keyboard.new(input: $stdin).help
+
+    # @return [String]
+    def about_text = Keyboard.new(input: $stdin).about
+  end
+end

data/lib/agentilda/control.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 module Agentilda
   # The side channel between a keypress and a running agent.
   #
@@ -16,6 +18,13 @@ module Agentilda
     WRAP_UP = "WRAP_UP"
     STOP = "STOP"
 
+    # Ctrl-C: STOP, and the run will be started again, so the agent leaves
+    # a resume note before it goes. The prompt says what that note is.
+    INTERRUPT = "INTERRUPT"
+
+    # The clock's warnings start with this; the agent's prompt explains them.
+    WARN = "WARN"
+
     # Seconds between {#quit!} and the harness terminating whatever is still
     # running. Long enough to write files and a handoff note; short enough
     # that q means quit rather than "quit eventually".
@@ -24,6 +33,7 @@ module Agentilda
     @mutex = Mutex.new
     @files = []
     @quit = false
+    @interrupted = false
     @deadline = nil
 
     class << self
@@ -52,6 +62,18 @@ module Agentilda
         FileUtils.rm_f(path)
       end
 
+      # One line into one file, from the clock. Not a broadcast: a warning is
+      # about one agent's own deadline.
+      #
+      # @param path [String]
+      # @param text [String]
+      # @return [void]
+      def write(path, text)
+        File.write(path, text.empty? ? "" : "#{text}\n")
+      rescue SystemCallError
+        # The invocation finished and released its file; nothing to warn.
+      end
+
       # `w`: every running agent is asked to finish the essential remainder
       # as fast as it can. The loop itself keeps going.
       #
@@ -78,9 +100,49 @@ module Agentilda
         }
       end
 
+      # Ctrl-C, the first time: {#quit!}, except that every running agent is
+      # told the run is being interrupted rather than stopped, so it writes
+      # down where it got to. A restart then reads that note instead of
+      # redoing, or half-redoing, the work.
+      #
+      # @return [void]
+      def interrupt!
+        broadcast(INTERRUPT)
+        @mutex.synchronize {
+          @quit = true
+          @interrupted = true
+          @deadline ||= UI.monotonic + GRACE
+        }
+      end
+
       # @return [Boolean] whether `q` has been pressed
       def quit? = @mutex.synchronize { @quit }
 
+      # @return [Boolean] whether Ctrl-C has been pressed
+      def interrupted? = @mutex.synchronize { @interrupted }
+
+      # Ctrl-C where no keyboard reads it: a run with no terminal to put in
+      # raw mode still gets the graceful first press and the hard second.
+      #
+      # A trap handler may not take a mutex, so the first press hands
+      # {#interrupt!} to a thread; the second raises, as Ctrl-C always has.
+      #
+      # @yieldreturn [Object]
+      # @return [Object] the block's value
+      def on_interrupt
+        previous = Signal.trap("INT") do
+          # A plain read, not {#interrupted?}: a trap handler may not lock.
+          raise Interrupt if @interrupted || @pending_interrupt
+
+          @pending_interrupt = true
+          Thread.new { interrupt! }
+        end
+        yield
+      ensure
+        @pending_interrupt = false
+        Signal.trap("INT", previous || "DEFAULT")
+      end
+
       # @return [Boolean] whether the grace period after `q` has run out
       def overdue?
         @mutex.synchronize { !@deadline.nil? && UI.monotonic > @deadline }
@@ -95,6 +157,7 @@ module Agentilda
           @files.each { |f| FileUtils.rm_f(f) }
           @files.clear
           @quit = false
+          @interrupted = false
           @deadline = nil
         }
       end

data/lib/agentilda/creator.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+require "dry/monads"
+require "fileutils"
+
+require "agentilda/status"
+
 module Agentilda
   # Mints new plan folders. Backs `/spec-create`.
   #
@@ -52,8 +57,8 @@ module Agentilda
         return [] unless File.directory?(dir)
 
         Dir.children(dir)
-          .select { |c| File.directory?(File.join(dir, c)) }
-          .filter_map { |c| Ordinal.from_dirname(c) }
+           .select { |c| File.directory?(File.join(dir, c)) }
+           .filter_map { |c| Ordinal.from_dirname(c) }
       end
     end
 

data/lib/agentilda/dashboard.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # The ratatui dashboard for agent work that is not a `run`: `unblock`
+  # handing plans to lando-broker, `create` drafting a spec.md. `run` has a
+  # {Dispatcher} to build its {Board}; this builds one from the items
+  # {UI.concurrently} hands it, so every agent a person waits on is drawn
+  # the same way, with the same keys.
+  #
+  # It stands in for the dispatcher behind {Console}, which is why it
+  # answers {#kill} and {#extend}: a row whose work passed its
+  # {Tracker#handle} on to {Executor#call} can be killed or given more time.
+  class Dashboard
+    # Seconds between frames handed to the screen.
+    REFRESH = 0.25
+
+    # Seconds a finished row stays on screen, so a fast agent is still seen.
+    LINGER = 3
+
+    # One item's row, and the {UI::Line} its work streams progress through.
+    # Nothing is drawn by the line itself; the dashboard reads it each frame.
+    class Tracker < UI::Line
+      # @return [String]
+      attr_reader :key
+
+      # @return [Agentilda::Executor::Handle] handed to {Executor#call} by a
+      #   caller that wants the kill and extend keys to reach its agent.
+      #   Not `@handle`: {UI::Line} keeps its dry-cli-ui line under that name.
+      def handle = @executor_handle
+
+      # @return [Symbol] :running, :done or :failed
+      attr_reader :state
+
+      # @return [Float, nil] monotonic reading of when it stopped running
+      attr_reader :finished_at
+
+      # @param key [String]
+      # @param fields [Hash] plan, status, agent and round, for the log and the row
+      # @param file [String] what the row's feature column says
+      # @param message [String] shown until the agent says something
+      # @param timeout [Integer, nil]
+      def initialize(key:, fields:, file:, message:, timeout: nil)
+        super(fields:, timeout:)
+        @key = key
+        @file = file
+        @message = message
+        @executor_handle = Executor::Handle.new
+        @state = :running
+        @update = nil
+        @history = []
+        @finished_at = nil
+      end
+
+      # @param update [Agentilda::Transcript::Progress]
+      # @return [void]
+      def call(update)
+        super
+        @update = update
+        return unless update.activity
+
+        @message = update.activity
+        @history = Board::Row.remember(@history, @message)
+      end
+
+      # @return [void]
+      def done
+        super
+        finish(:done)
+      end
+
+      # @param reason [String]
+      # @return [void]
+      def failed(reason)
+        super
+        @message = reason
+        @history = Board::Row.remember(@history, reason)
+        finish(:failed)
+      end
+
+      # @return [Agentilda::Board::Row]
+      def row
+        Board::Row.new(key:,
+          at: Time.now,
+          ordinal: @fields[:plan].to_s,
+          file: @file,
+          agent: @fields[:agent].to_s,
+          role: @fields[:agent].to_s,
+          round: @fields[:round] || 1,
+          rounds: @fields[:round] || 1,
+          model: "default",
+          remaining: handle.remaining || remaining,
+          phase: handle.phase,
+          up: @update&.up.to_i,
+          down: @update&.down.to_i,
+          message: @message,
+          state:,
+          elapsed: seconds.round,
+          subagents: @update&.subagents.to_i,
+          history: @history)
+      end
+
+      private
+
+      # @param state [Symbol]
+      # @return [void]
+      def finish(state)
+        @state = state
+        @finished_at = UI.monotonic
+      end
+    end
+
+    # Opens the screen, runs the block, and always closes it again.
+    #
+    # @param root [String] shown in the bottom bar
+    # @param screen [Agentilda::Screen::Ratatui]
+    # @yieldparam dashboard [Agentilda::Dashboard]
+    # @return [Object] the block's value
+    def self.open(root: Dir.pwd, screen: Screen::Ratatui.new)
+      dashboard = new(root:, screen:)
+      dashboard.start
+      begin
+        yield dashboard
+      ensure
+        dashboard.stop
+      end
+    end
+
+    # @param root [String]
+    # @param screen [Agentilda::Screen::Ratatui]
+    def initialize(root:, screen:)
+      @root = root
+      @screen = screen
+      @console = Console.new(screen:)
+      @console.attach(self)
+      @trackers = []
+      @lock = Mutex.new
+      @started_at = UI.monotonic
+      @closing = false
+    end
+
+    # @return [void]
+    def start
+      # ratatui owns the terminal's input, so the keyboard is fed from its
+      # loop rather than reading STDIN on a thread of its own.
+      @keyboard = Keyboard.new(sink: @console)
+      @screen.attach_keyboard(@keyboard)
+      @screen.open
+      @painter = Thread.new do
+        Thread.current.report_on_exception = false
+        until @closing
+          paint
+          sleep(REFRESH)
+        end
+      end
+    end
+
+    # @return [void]
+    def stop
+      @closing = true
+      @painter&.join
+      paint
+      @screen.close
+    end
+
+    # @param key [String]
+    # @param fields [Hash]
+    # @param file [String]
+    # @param message [String]
+    # @param timeout [Integer, nil]
+    # @return [Tracker]
+    def track(key:, fields: {}, file: "", message: "starting", timeout: nil)
+      Tracker.new(key:, fields:, file:, message:, timeout:).tap do |tracker|
+        @lock.synchronize { @trackers << tracker }
+      end
+    end
+
+    # @return [void]
+    def paint = @console.paint(board)
+
+    # @return [Agentilda::Board]
+    def board
+      rows = visible.map(&:row)
+      running = rows.select(&:running?)
+      Board.new(started_at: @started_at,
+        status: Control.quit? ? :quitting : :running,
+        plans: rows.map(&:ordinal).reject(&:empty?).uniq,
+        up: rows.sum(&:up),
+        down: rows.sum(&:down),
+        rows:,
+        root: @root,
+        running: running.size,
+        live_up: running.sum(&:up),
+        live_down: running.sum(&:down))
+    end
+
+    # @param key [String]
+    # @return [void]
+    def kill(key) = find(key)&.handle&.kill!
+
+    # @param key [String]
+    # @param seconds [Integer]
+    # @return [void]
+    def extend(key, seconds) = find(key)&.handle&.extend!(seconds)
+
+    private
+
+    # @return [Array<Tracker>] running, plus whatever finished a moment ago
+    def visible
+      now = UI.monotonic
+      @lock.synchronize do
+        @trackers.reject { |t| t.finished_at && now - t.finished_at > LINGER }
+      end
+    end
+
+    # @param key [String]
+    # @return [Tracker, nil]
+    def find(key) = @lock.synchronize { @trackers.find { |t| t.key == key } }
+  end
+end

data/lib/agentilda/dev_work.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "agentilda/status"
+
 module Agentilda
   # Telling "this belongs to no specification" apart from "nobody could tell".
   #