agentilda 2.0.3 → 2.0.4

data/lib/agentilda/engine/progress_log.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Engine
+    # 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 = Plans::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
+end

data/lib/agentilda/engine/runner.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Engine
+    # Drives specialist agents over a `.plans` tree until nothing is left to
+    # dispatch.
+    #
+    # The loop itself is {Dispatcher}. This holds what the loop needs about
+    # the run: the tree and its scope, the roster, the executor, how many run
+    # at once, where each plan is checked out, and how a finished plan is
+    # published. Blocked plans (⭕️ 🅱️) are stepped around, never assigned.
+    class Runner
+      # What one agent did to one plan.
+      Attempt = Data.define(:ordinal,
+        :agent,
+        :from,
+        :to,
+        :ok,
+        :note,
+        :up,
+        :down,
+        :subagents,
+        :delegated,
+        :seconds,
+        :round,
+        :file,
+        :model,
+        :status) do
+        def initialize(round: 1, file: "", model: nil, status: nil, **rest) = super
+
+        # @return [Boolean] whether the plan actually moved
+        def advanced? = ok && from != to
+      end
+
+      # One unit of work: an agent, a plan, and the checkout it happens in.
+      Task = Data.define(:agent, :subject, :root, :checkout, :round) do
+        # @return [Hash] columns for the log
+        def log_fields
+          { plan: subject.feature.ordinal.to_s, status: subject.status.to_s,
+           agent: agent.name, round: format("%02d", round) }
+        end
+      end
+
+      # @param rounds [Integer, nil] `--rounds`, capping each agent's own
+      # @param state [Agentilda::Engine::StateFile, nil]
+      # @param sleeper [Proc]
+      # @param on_board [Proc, nil]
+      def initialize(tree:, executor:, agents: Agents::Registry.new, isolation: :shared, jobs: 1, worktree: nil,
+        plans: nil, publisher: nil, dry_run: false, rounds: nil, state: nil,
+        sleeper: ->(seconds) { sleep(seconds) }, on_board: nil)
+        @tree = tree
+        @executor = executor
+        @agents = agents
+        @isolation = isolation
+        @worktree = worktree
+        @plans = plans
+        @publisher = publisher
+        @dry_run = dry_run
+        @rounds = rounds
+        @state = dry_run ? nil : state
+        @sleeper = sleeper
+        @on_board = on_board
+        @attempts = []
+        @jobs = isolated? ? jobs : 1
+      end
+
+      attr_reader :jobs, :worktree, :tree, :attempts, :executor, :agents
+
+      # @return [Boolean]
+      def isolated? = @isolation == :worktree
+
+      # @return [Boolean]
+      def dry_run? = @dry_run
+
+      # @return [String] the repository root
+      def root = isolated? ? worktree.root : shared_root
+
+      # @param subject [Agentilda::Plans::Subject]
+      # @return [Boolean]
+      def in_scope?(subject) = @plans.nil? || @plans.include?(subject.feature.ordinal)
+
+      # @return [Array<Agentilda::Plans::Subject>]
+      def in_scope = tree.subjects.select { |s| in_scope?(s) }
+
+      # Run until nothing is dispatchable.
+      #
+      # @yieldparam dispatcher [Agentilda::Engine::Dispatcher] before it runs, so a
+      #   console can attach itself and reach the running jobs
+      # @return [Array<Agentilda::Engine::Runner::Attempt>]
+      def call
+        dispatcher = Dispatcher.new(runner: self, state: @state, rounds: @rounds, sleeper: @sleeper, on_board: @on_board)
+        yield dispatcher if block_given?
+        @attempts = dispatcher.run
+      end
+
+      # @return [Array<Agentilda::Plans::Subject>]
+      def blocked = in_scope.select { |s| %i[blocked product_blocked].include?(s.status.key) }
+
+      # @return [Boolean]
+      def settled? = in_scope.all? { |s| Plans::StateMachine::SETTLED.include?(s.status.key) }
+
+      # A dry run gets the shared root whatever the isolation says: nothing
+      # runs in the checkout, and `git worktree add` is a side effect a
+      # preview must not have. It also fails outright when the plan's branch
+      # is the one checked out where the run was typed, which is where a dry
+      # run of that plan is typed.
+      #
+      # @return [Agentilda::Engine::Runner::Task]
+      def prepare(agent, subject, round)
+        return Task.new(agent:, subject:, root: shared_root, checkout: nil, round:) if !isolated? || dry_run?
+
+        checkout = worktree.checkout_for(subject.feature)
+        Task.new(agent:, subject:, root: checkout.path, checkout:, round:)
+      end
+
+      # @return [Agentilda::Vcs::Publisher::Publication, nil]
+      def publish(task, subject)
+        return nil unless @publisher && task.checkout&.dirty?
+
+        publication = @publisher.publish(checkout: task.checkout, subject:)
+        record_pull_request(subject.feature.path, publication) if publication.published?
+        publication
+      end
+
+      private
+
+      # @return [String]
+      def shared_root = File.dirname(tree.dir)
+
+      # @return [void]
+      def record_pull_request(path, publication)
+        number = publication.url.to_s[%r{/pull/(\d+)}, 1]
+        rows = Plans::PullRequests.new(dir: path).all.map { |pr|
+          { number: pr.number, title: pr.title, url: pr.url, state: pr.state, body: "" }
+        }
+        rows << { number:, title: publication.title, url: publication.url, state: "Open 🟡", body: "" }
+        Plans::PullRequests.upsert(File.join(path, Plans::PullRequests::FILENAME), rows)
+      end
+    end
+  end
+end

data/lib/agentilda/engine/state_file.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Agentilda
+  module Engine
+    # 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::Plans::Tree]
+      # @return [String]
+      def self.for(tree) = File.join(tree.dir, FILENAME)
+
+      # @param tree [Agentilda::Plans::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
+end

data/lib/agentilda/engine/tally.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Engine
+    # What a `run` cost, once it is over.
+    #
+    # The loop reports movement — which plan went from ⭐️ to 🟡, which agent
+    # failed and why — and says nothing about the bill. A round of five agents
+    # against a large repository spends several million tokens and the better
+    # part of an hour, and until this existed the only record of that was a
+    # directory of trace files nobody reads.
+    #
+    # {#render} returns a string and prints nothing, so the caller decides where
+    # it goes, the same way {Reporter} works.
+    class Tally
+      # One agent's share of the run, added up across every round it ran in.
+      #
+      # @!attribute [r] name
+      #   @return [String]
+      # @!attribute [r] invocations
+      #   @return [Integer] times this agent was started
+      # @!attribute [r] subagents
+      #   @return [Integer] sub-agents it spawned, across all of them
+      # @!attribute [r] up
+      #   @return [Integer] tokens sent, sub-agent spend included
+      # @!attribute [r] down
+      #   @return [Integer] tokens generated
+      # @!attribute [r] seconds
+      #   @return [Float] how long it was running, added up
+      Row = Data.define(:name, :invocations, :subagents, :up, :down, :seconds)
+
+      # Cells per column, so the header, the rows and the rule cannot drift.
+      WIDTHS = { name: 22, invocations: 6, subagents: 11, up: 9, down: 9, seconds: 8 }.freeze
+
+      # @param attempts [Array<Agentilda::Engine::Runner::Attempt>]
+      # @param seconds [Float] wall clock for the whole loop, which is not the
+      #   sum of the agents' own times: several of them run at once
+      # @param rounds [Integer, nil] accepted so an older caller still works, and
+      #   otherwise unused: the loop has no rounds of its own any more, each
+      #   agent counts its own per plan, so the summary counts invocations
+      def initialize(attempts:, seconds:, rounds: nil)
+        @attempts = attempts.reject { |a| a.ordinal == "?" }
+        @seconds = seconds
+        @rounds = rounds
+      end
+
+      # @return [Array<Agentilda::Engine::Runner::Attempt>]
+      attr_reader :attempts
+
+      # @return [Float] wall clock
+      attr_reader :seconds
+
+      # @return [Integer, nil]
+      attr_reader :rounds
+
+      # Plans an agent was actually started against, counted once each however
+      # many rounds they took.
+      #
+      # @return [Integer]
+      def plans = attempts.map(&:ordinal).uniq.size
+
+      # @return [Integer] tokens sent, everything included
+      def up = attempts.sum(&:up)
+
+      # @return [Integer] tokens generated
+      def down = attempts.sum(&:down)
+
+      # @return [Integer] sub-agents spawned by every agent in the run
+      def subagents = attempts.sum(&:subagents)
+
+      # Sub-agent spend that arrived as one number. `claude` reports what a
+      # sub-agent cost without splitting it between the two directions, so this
+      # much of {#up} is really up and down together.
+      #
+      # @return [Integer]
+      def delegated = attempts.sum(&:delegated)
+
+      # @return [Float] seconds of agent time, added up across all of them
+      def busy = attempts.sum(&:seconds)
+
+      # How many agents were running at any given moment, averaged over the
+      # run: agent-seconds divided by wall-clock seconds. Below the `-j` ceiling
+      # by however much the round spent waiting for its slowest member.
+      #
+      # @return [Float]
+      def concurrency = seconds.positive? ? busy / seconds : 0.0
+
+      # @return [Array<Agentilda::Engine::Tally::Row>] one per agent, dearest first
+      def by_agent
+        attempts.group_by(&:agent).map { |name, list|
+          Row.new(name:,
+            invocations: list.size,
+            subagents: list.sum(&:subagents),
+            up: list.sum(&:up),
+            down: list.sum(&:down),
+            seconds: list.sum(&:seconds))
+        }.sort_by { |row| -row.up }
+      end
+
+      # @return [String] the table and the summary line under it
+      def render
+        return summary if attempts.empty?
+
+        ([header, rule] + by_agent.map { |row| line(row) } + [rule, totals, "", summary]).join("\n")
+      end
+
+      # @return [String] the one-line version, for a box
+      def summary
+        [
+          "#{plans} plan#{"s" unless plans == 1} addressed",
+          "#{attempts.size} invocation#{"s" unless attempts.size == 1}",
+          duration(seconds),
+          "#{format("%.1f", concurrency)} agents at a time",
+          "↑ #{UI.abbreviate(up)} ↓ #{UI.abbreviate(down)}"
+        ].join(" · ") + delegation
+      end
+
+      private
+
+      # @return [String] the caveat, where there is one to make
+      def delegation
+        return "" if delegated.zero?
+
+        "\n#{subagents} sub-agent#{"s" unless subagents == 1} reported #{UI.abbreviate(delegated)} " \
+          "tokens without splitting them, counted above as ↑."
+      end
+
+      # @return [String]
+      def header
+        cell("Agent", :name) + %i[invocations subagents up down seconds]
+                               .zip(["runs", "sub-agents", "↑", "↓", "time"])
+                               .map { |key, text| right(text, key) }.join
+      end
+
+      # @return [String]
+      def rule = WIDTHS.values.map { |width| ("─" * (width - 1)) + " " }.join
+
+      # @param row [Agentilda::Engine::Tally::Row]
+      # @return [String]
+      def line(row)
+        cell(row.name, :name) + right(row.invocations.to_s, :invocations) +
+          right(row.subagents.to_s, :subagents) + right(UI.abbreviate(row.up), :up) +
+          right(UI.abbreviate(row.down), :down) + right(duration(row.seconds), :seconds)
+      end
+
+      # @return [String]
+      def totals
+        cell("", :name) + right(attempts.size.to_s, :invocations) + right(subagents.to_s, :subagents) +
+          right(UI.abbreviate(up), :up) + right(UI.abbreviate(down), :down) + right(duration(busy), :seconds)
+      end
+
+      # @param text [String]
+      # @param key [Symbol]
+      # @return [String] padded to its column, left-justified
+      def cell(text, key) = UI.fit(text, WIDTHS.fetch(key))
+
+      # @param text [String]
+      # @param key [Symbol]
+      # @return [String] padded to its column, right-justified
+      def right(text, key)
+        width = WIDTHS.fetch(key) - 1
+        text = UI.fit(text, width).rstrip
+        UI.fit("", width - UI.display_width(text)) + text + " "
+      end
+
+      # @param seconds [Numeric]
+      # @return [String] e.g. "42s", "12m40s", "1h04m"
+      def duration(seconds)
+        total = seconds.to_i
+        return "#{total}s" if total < 60
+        return "#{total / 60}m#{format("%02ds", total % 60)}" if total < 3600
+
+        "#{total / 3600}h#{format("%02dm", (total % 3600) / 60)}"
+      end
+    end
+  end
+end

data/lib/agentilda/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # The run loop: which agent works which plan, in what order, until a round
+  # changes nothing. It decides; {Execution} carries the decision out.
+  module Engine
+    module_function
+
+    # @return [Agentilda::Engine::Runner]
+    def runner(**) = Runner.new(**)
+
+    # @param tree [Agentilda::Plans::Tree]
+    # @return [Agentilda::Engine::StateFile]
+    def state_file(tree) = StateFile.new(path: StateFile.for(tree))
+
+    # @return [Agentilda::Engine::Tally]
+    def tally(**) = Tally.new(**)
+  end
+end