agentilda 1.0.3 → 2.0.1

data/lib/agentilda/cli/run/run.rb

@@ -1,37 +1,60 @@
 # frozen_string_literal: true
 
+require "tmpdir"
+
 module Agentilda
   module CLI
     # `agentilda run` — drive the specialist agents until the tree settles.
     class Run < Base
       desc "Run specialist agents over the plans until nothing changes"
 
-      option :commit, type: :boolean, default: false,
-        desc: "Actually invoke the agents (default: dry run, prints the plan of work)"
-      option :rounds, desc: "Hard ceiling on loop iterations (default: 10)"
-      option :timeout, desc: "Seconds before one agent is abandoned (default: 900)"
-      option :chain, type: :boolean,
-        desc: "When an agent advances a plan, run the next agent in the same round " \
-              "(default: on; forced off by --agent)"
+      option :commit,
+        type:    :boolean,
+        default: false,
+        desc:    "Actually invoke the agents (default: dry run, prints the plan of work)"
+      option :rounds,
+        desc: "Cap on rounds per agent per plan; each agent declares its own, at most 5 " \
+              "(default: the agent's own)"
+      option :timeout,
+        desc: "Seconds before one agent is abandoned; only tightens an agent's own clock " \
+              "(default: the agent's own, else 900)"
       option :agent, desc: "Only run this one agent"
-      option :prompt, desc: "Extra instructions appended to the agent's prompt (only with --agent)"
-      option :skip, desc: "Never assign this agent; its plans wait, the rest of the pipeline runs. " \
-        "Comma separated for several"
-      option :model, desc: "Model for every agent this run, overriding each agent's own frontmatter " \
-        "(default: what the agent declares, else the claude CLI's default)"
-      option :max_tokens, desc: "Token budget per agent invocation, input plus output, sub-agents " \
-        "included. The agent is told the number so it can finish inside it; the meter aborts it past " \
-        "the number so the telling is true. (default: unmetered)"
-      option :plan, aliases: ["--plans"],
-        desc: "Only these plans, comma separated: NNN or NNN.MM, e.g. --plan 003,005.01. Default: the whole tree"
+      # `--prompt` shorter than this that names an existing file is read.
+      PROMPT_PATH_LIMIT = 80
+
+      option :prompt,
+        desc: "Extra instructions appended to the agent's prompt (only with --agent); " \
+              "a path to an existing text file under #{PROMPT_PATH_LIMIT} characters is read instead"
+      option :skip,
+        desc: "Never assign this agent; its plans wait, the rest of the pipeline runs. " \
+              "Comma separated for several"
+      option :model,
+        desc: "Model for every agent this run, overriding each agent's own frontmatter " \
+              "(default: what the agent declares, else the claude CLI's default)"
+      option :max_tokens,
+        desc: "Token budget per agent invocation, input plus output, sub-agents " \
+              "included. The agent is told the number so it can finish inside it; the meter aborts it past " \
+              "the number so the telling is true. (default: unmetered)"
+      option :plan,
+        aliases: ["--plans"],
+        desc:    "Only these plans, comma separated: NNN or NNN.MM, e.g. --plan 003,005.01. Default: the whole tree"
       option :root, desc: "Repository root the agents work in (default: the .plans parent)"
-      option :isolation, default: "worktree", values: %w[worktree shared],
-        desc: "worktree: a checkout and branch per plan, run in parallel. shared: one tree, serial"
-      option :jobs, aliases: ["-j"],
-        desc: "Agents to run at once (default: cores - 2, capped at 12)"
-      option :dont_push_anything, type: :boolean, default: false,
-        desc: "With --commit and --isolation worktree, a finished branch is pushed and its pull request " \
-              "opened as soon as it lands, titled [NNN.MM](X). Pass this to turn that off and leave it uncommitted."
+      option :isolation,
+        default: "worktree",
+        values:  %w[worktree shared],
+        desc:    "worktree: a checkout and branch per plan, run in parallel. shared: one tree, serial"
+      option :jobs,
+        aliases: ["-j"],
+        desc:    "Agents to run at once (default: cores - 2, capped at 12)"
+      option :git_push,
+        type:    :boolean,
+        default: true,
+        desc:    "With --commit and --isolation worktree, a finished branch is pushed and its pull request " \
+                 "opened as soon as it lands, titled [NNN.MM](X). --no-git-push turns that off and leaves it uncommitted."
+      option :scroll_height,
+        aliases: ["-s"],
+        desc:    "Lines of each agent's latest statuses shown under its row, newest first " \
+                 "(default: #{Screen::Ratatui::SCROLL_HEIGHT})"
       option :log, desc: "Append progress to this file (default: a per-project file under the system temp dir)"
 
       example [
@@ -39,8 +62,9 @@ module Agentilda
         "--commit               # run them, one worktree per plan, in parallel",
         "--commit -j 4          # …with four at a time",
         "--isolation shared     # one tree, serial — no git required",
-        "--commit --rounds 3    # …with a tighter ceiling",
-        "--commit --plan 005,006,007  # only the plans a batch step just created"
+        "--commit --rounds 3    # …capping every agent at three rounds per plan",
+        "--commit --plan 005,006,007  # only the plans a batch step just created",
+        "--commit -s 5          # …each agent's last five statuses under its row"
       ]
 
       # Option precedence, quietest to loudest: the built-in default, then
@@ -59,31 +83,26 @@ module Agentilda
 
         if options[:prompt] && !options[:agent]
           refuse("--prompt only works with --agent: it speaks to one agent, and without " \
-                 "that restriction every agent in the round would hear it.", 64)
+                 "that restriction every agent in the round would hear it.",
+            64)
         end
 
-        tree = tree_for(options)
-        root = options[:root] || File.dirname(tree.dir)
+        tree   = tree_for(options)
+        root   = options[:root] || File.dirname(tree.dir)
         agents = Agentilda::Agents.new
         agents = filtered(agents, options[:agent]) if options[:agent]
         agents = skipped(agents, options[:skip], options[:agent]) if options[:skip]
-        plans = options[:plan] ? scoped(tree, options[:plan]) : nil
+        plans  = options[:plan] ? scoped(tree, options[:plan]) : nil
         assignable!(agents, tree, plans, options[:agent]) if options[:agent]
 
         isolation = options.fetch(:isolation, "worktree").to_sym
-        jobs = (options[:jobs] || config[:jobs] || UI.default_jobs).to_i
-        timeout = (options[:timeout] || config[:timeout] || 900).to_i
-        chain = if options[:agent]
-          false
-        elsif options.key?(:chain)
-          options[:chain]
-        else
-          config.fetch(:chain, true)
-        end
+        jobs      = (options[:jobs] || config[:jobs] || UI.default_jobs).to_i
+        timeout   = (options[:timeout] || config[:timeout])&.to_i
 
-        if isolation == :worktree && !Worktree.new(root:).repository?
+        if isolation == :worktree && !::Agentilda::Worktree.new(root:).repository?
           refuse("#{root} is not a git repository, so plans cannot be isolated.\n\n" \
-                 "Run with --isolation shared to work in one tree, serially.", 66)
+                 "Run with --isolation shared to work in one tree, serially.",
+            66)
         end
 
         # Set before the loop starts, not after: `UI.animate?` (and therefore
@@ -91,37 +110,124 @@ module Agentilda
         # loop runs, not just when `report` prints its closing summary.
         quiet?(options)
         UI.log_path = options[:log] || config[:log] ||
-          File.join(Dir.tmpdir, "agentilda-#{File.basename(root)}.log")
+                      File.join(Dir.tmpdir, "agentilda-#{File.basename(root)}.log")
         info("Progress: #{UI.log_path}") unless quiet?(options)
         credentials_warning if commit?(options) && !quiet?(options)
 
+        # The state file is what a harness that dies leaves for the next one.
+        # It sits in .plans/ so a reboot keeps it, and it is ignored by name
+        # so it never rides along in a commit. Editing somebody's .gitignore
+        # is announced, the once it happens. The runner drops the file on a
+        # dry run, which is why it can be built unconditionally.
+        state = StateFile.new(path: StateFile.for(tree))
+        if commit?(options) && StateFile.ensure_ignored!(root) && !quiet?(options)
+          info("Added #{StateFile::IGNORE.join(" and ")} to .gitignore: the run keeps its state there.")
+        end
+
+        # The screen only on a terminal that is actually running agents: a dry
+        # run has nothing to draw and a pipe has nowhere to draw it. Without a
+        # screen the keys still work, so the one line says which.
+        # With a screen, ratatui owns the terminal's input, so the keyboard is
+        # fed from its loop rather than started on STDIN of its own.
         Control.reset!
-        keyboard = Keyboard.listen
-        UI.line("keys: h for help — w wrap up · n write out and stop · q quit") if keyboard && !quiet?(options)
+        scroll_height = options.fetch(:scroll_height, Screen::Ratatui::SCROLL_HEIGHT)
+        unless scroll_height.to_s.match?(/\A[1-9]\d*\z/)
+          refuse("--scroll-height must be a whole number of lines, 1 or more, not #{scroll_height.inspect}.", 64)
+        end
+        screen   = (Screen::Ratatui.new(scroll_height: scroll_height.to_i) if UI.animate? && commit?(options))
+        console  = (Console.new(screen:) if screen)
+        # A dry run gets no keyboard at all: every key it offers speaks to a
+        # running agent, and listening costs the terminal's raw mode, whose
+        # output post-processing the report below needs left alone.
+        keyboard = if screen
+                     Keyboard.new(sink: console).tap { |kb| screen.attach_keyboard(kb) }
+                   elsif commit?(options)
+                     Keyboard.listen(sink: console)
+                   end
+        UI.line("keys: h for help - s select, k kill, x extend, w wrap up, n stop, q quit") if keyboard && console.nil? && !quiet?(options)
 
         runner = Runner.new(
-          tree:, agents:, isolation:, jobs:, plans:, chain:,
-          worktree: (Worktree.new(root:) if isolation == :worktree),
-          max_rounds: (options[:rounds] || config[:rounds] || 10).to_i,
-          executor: Executor.new(root:, timeout:, dry_run: !commit?(options),
-            instructions: options[:prompt], model: options[:model],
-            max_tokens: (options[:max_tokens] || config[:max_tokens])&.to_i,
-            interactive: !keyboard.nil? && commit?(options)), dry_run: !commit?(options),
-          publisher: publisher_for(root, isolation, options)
+          tree:,
+          agents:,
+          isolation:,
+          jobs:,
+          plans:,
+          state:,
+          worktree:  (::Agentilda::Worktree.new(root:) if isolation == :worktree),
+          rounds:    (options[:rounds] || config[:rounds])&.to_i,
+          executor:  Executor.new(root:,
+            timeout:,
+            dry_run:      !commit?(options),
+            instructions: instructions_from(options[:prompt]),
+            model:        options[:model],
+            max_tokens:   (options[:max_tokens] || config[:max_tokens])&.to_i,
+            interactive:  !keyboard.nil? && commit?(options)),
+          dry_run:   !commit?(options),
+          publisher: publisher_for(root, isolation, options),
+          on_board:  console&.method(:paint)
         )
 
-        started = UI.monotonic
-        rounds = begin
-          runner.call
+        # The dispatcher exists only once the run starts, so the console is
+        # introduced to it through the block rather than up front.
+        started  = UI.monotonic
+        attempts = begin
+          screen&.open
+          Control.on_interrupt { runner.call { |dispatcher| console&.attach(dispatcher) } }
         ensure
+          screen&.close
           keyboard&.stop
         end
-        report(runner, rounds, options, seconds: UI.monotonic - started)
-        exit(failures(rounds).empty? ? 0 : 1)
+        report(runner, attempts, options, seconds: UI.monotonic - started)
+        exit(failures(attempts).empty? ? 0 : 1)
       end
 
       private
 
+      # The attempts list, padded into columns.
+      #
+      # Tabs used to separate these, which put every column on the next
+      # multiple of eight: one agent's name a character longer than the
+      # next one's pushed its round and mark a whole stop to the right, so
+      # nothing under `luke-backend` and `yoda-writer` lined up. Widths come
+      # from the rows themselves, so the columns are as narrow as the run
+      # allows and still square.
+      #
+      # @param attempts [Array<Agentilda::Runner::Attempt>]
+      # @return [Array<String>] one line per attempt, indented by two
+      def attempt_lines(attempts)
+        rows   = attempts.map { |a| [a.ordinal.to_s, a.agent.to_s, "[R:#{a.round}]", mark(a), a.note.to_s] }
+        widths = rows.transpose.map { |column| column.map { |cell| UI.display_width(cell) }.max.to_i }
+        rows.map do |cells|
+          # The note is last and is left as it is: padding the final column
+          # only adds trailing whitespace a copy-paste then carries.
+          last = cells.size - 1
+          "  #{cells.each_with_index.map { |cell, i| i == last ? cell : UI.fit(cell, widths[i] + 2) }.join}"
+        end
+      end
+
+      # @param attempt [Agentilda::Runner::Attempt]
+      # @return [String] what the attempt did to its plan's state
+      def mark(attempt)
+        return "FAIL" unless attempt.ok
+        return "#{attempt.from} -> #{attempt.to}" if attempt.advanced?
+
+        "no change"
+      end
+
+      # `--prompt` takes the instructions themselves or a file holding them.
+      # A short argument naming an existing file is read; anything else is
+      # the text, so a sentence that happens to match a filename in the
+      # project is not silently swapped for that file once it is long enough
+      # to be a sentence.
+      #
+      # @param prompt [String, nil]
+      # @return [String, nil]
+      def instructions_from(prompt)
+        return prompt unless prompt && prompt.length < PROMPT_PATH_LIMIT && File.file?(prompt)
+
+        File.read(prompt)
+      end
+
       # @param agents [Agentilda::Agents]
       # @param name [String]
       # @return [Agentilda::Agents] holding only the agent named — the
@@ -143,14 +249,15 @@ module Agentilda
       # @return [Agentilda::Agents] without the agents named
       def skipped(agents, text, restricted)
         roster = Agentilda::Agents.new
-        names = text.split(",").map(&:strip).reject(&:empty?)
+        names  = text.split(",").map(&:strip).reject(&:empty?)
         names.each do |name|
           roster.find(name) or
             refuse("No agent called #{name}.\n\nKnown: #{roster.all.map(&:name).join(", ")}", 65)
-          if name == restricted
-            refuse("--agent #{name} and --skip #{name} contradict each other: " \
-                   "one asks for only this agent, the other for anything but.", 64)
-          end
+          next unless name == restricted
+
+          refuse("--agent #{name} and --skip #{name} contradict each other: " \
+                 "one asks for only this agent, the other for anything but.",
+            64)
         end
         agents.without(*names)
       end
@@ -170,7 +277,8 @@ module Agentilda
           ordinal = Ordinal.parse(token)
           unless ordinal && known.include?(ordinal)
             refuse("No plan #{token} in #{tree.dir}.\n\n" \
-                   "Known: #{known.join(", ")}", 66)
+                   "Known: #{known.join(", ")}",
+              66)
           end
           ordinal
         }
@@ -188,27 +296,29 @@ module Agentilda
       # @param name [String]
       # @return [void]
       def assignable!(agents, tree, plans, name)
-        agent = agents.find(name)
+        agent  = agents.find(name)
         active = tree.subjects.select { |s|
           (plans.nil? || plans.include?(s.feature.ordinal)) &&
             !StateMachine::SETTLED.include?(s.status.key)
         }
         return if active.empty? || active.any? { |s| agent.handles?(s.status) }
 
-        roster = Agentilda::Agents.new
-        lines = active.map { |s|
+        roster  = Agentilda::Agents.new
+        lines   = active.map { |s|
           takers = roster.for_status(s.status).map(&:name)
+          verb   = takers.size == 1 ? "takes" : "take"
           "  #{s.feature.ordinal} is #{s.status.emoji} #{s.status.label}" \
-            "#{" — #{takers.join(", ")} takes it" unless takers.empty?}"
+            "#{" - #{takers.join(" and ")} #{verb} it" unless takers.empty?}"
         }
         handled = agent.handles.map { |k| Agentilda::STATUS_BY_KEY[k]&.then { |st| "#{st.emoji} #{st.label}" } || k }
         refuse("#{name} handles #{handled.join(", ")}, and no plan in scope is there:\n\n" \
-               "#{lines.join("\n")}\n\nName the agent that takes these states, or drop --agent.", 65)
+               "#{lines.join("\n")}\n\nName the agent that takes these states, or drop --agent.",
+          65)
       end
 
-      # @param rounds [Array]
-      # @return [Array]
-      def failures(rounds) = rounds.flat_map(&:attempts).reject(&:ok)
+      # @param attempts [Array<Agentilda::Runner::Attempt>]
+      # @return [Array<Agentilda::Runner::Attempt>]
+      def failures(attempts) = attempts.reject(&:ok)
 
       # The one thing this harness does that leaves the machine — pushing a
       # branch and opening its pull request — so it takes one more thing to
@@ -216,7 +326,7 @@ module Agentilda
       # isolation has to actually give each plan a branch of its own too.
       #
       # `nil` is how {Runner} is told to leave a finished worktree alone; it
-      # is what `--dont-push-anything` asks for, and what a shared tree gets
+      # is what `--no-git-push` asks for, and what a shared tree gets
       # by construction, since there is no separate branch there to push.
       #
       # @param root [String]
@@ -224,35 +334,33 @@ module Agentilda
       # @param options [Hash]
       # @return [Agentilda::Publisher, nil]
       def publisher_for(root, isolation, options)
-        return nil if isolation != :worktree || options[:dont_push_anything]
+        return nil if isolation != :worktree || options[:git_push] == false
 
         Publisher.new(root:, dry_run: !commit?(options))
       end
 
+      # One line per attempt: the plan, who ran, which of that agent's rounds
+      # it was, what moved, and the note. There is no round header any more
+      # because the loop has no rounds of its own: each agent counts its own
+      # per plan, so two agents on one plan can be on different numbers.
+      #
       # @param runner [Agentilda::Runner]
-      # @param rounds [Array]
+      # @param attempts [Array<Agentilda::Runner::Attempt>]
       # @param options [Hash]
       # @param seconds [Float] wall clock for the whole loop
       # @return [void]
-      def report(runner, rounds, options, seconds: 0.0)
-        rounds.each do |round|
-          puts "round #{round.number}"
-          round.attempts.each do |a|
-            mark = if !a.ok
-              "FAIL"
-            elsif a.advanced?
-              "#{a.from} -> #{a.to}"
-            else
-              "no change"
-            end
-            puts "  #{a.ordinal}\t#{a.agent}\t#{mark}\t#{a.note}"
-          end
-        end
+      def report(runner, attempts, options, seconds: 0.0)
+        # A leading blank line, because the spinners this replaces write to
+        # STDERR and the last of them may have left the cursor mid-line:
+        # without it the first attempt starts wherever that line stopped,
+        # indented by however much it had drawn.
+        puts ""
+        puts attempt_lines(attempts)
 
-        # What the run cost, on STDOUT with the rounds it belongs to, so a run
+        # What the run cost, on STDOUT with the attempts it belongs to, so a run
         # redirected to a file keeps its bill. A dry run spent nothing and gets
         # none of this.
-        tally = Tally.new(attempts: rounds.flat_map(&:attempts), seconds:, rounds: rounds.size)
+        tally = Tally.new(attempts:, seconds:)
         puts("", tally.render) if commit?(options)
 
         return if quiet?(options)
@@ -262,27 +370,27 @@ module Agentilda
                "re-run to resume where they stand.")
         end
 
-        advanced = rounds.sum(&:advanced)
-        blocked = runner.blocked
-        summary = ["#{rounds.size} round#{"s" unless rounds.size == 1}", "#{advanced} advanced"]
+        advanced = attempts.count(&:advanced?)
+        blocked  = runner.blocked
+        summary  = ["#{attempts.size} invocation#{"s" unless attempts.size == 1}", "#{advanced} advanced"]
         summary << (runner.isolated? ? "#{runner.jobs} at a time, one worktree each" : "serial, shared tree")
         summary << "#{blocked.size} blocked" unless blocked.empty?
-        summary << "#{failures(rounds).size} failed" unless failures(rounds).empty?
+        summary << "#{failures(attempts).size} failed" unless failures(attempts).empty?
 
         if !commit?(options)
           warn("Dry run — no agent was invoked.\n#{summary.join(" · ")}\n\nRe-run with --commit.")
-        elsif failures(rounds).empty?
+        elsif failures(attempts).empty?
           success("#{summary.join(" · ")}#{"\n\nEvery plan is done or deliberately parked." if runner.settled?}")
         else
-          error("#{summary.join(" · ")}\n\n#{failures(rounds).map { |f| "#{f.ordinal} #{f.agent}: #{f.note}" }.join("\n")}")
+          error("#{summary.join(" · ")}\n\n#{failures(attempts).map { |f| "#{f.ordinal} #{f.agent}: #{f.note}" }.join("\n")}")
         end
 
         return if blocked.empty?
 
         warn("#{blocked.size} plan#{"s" unless blocked.size == 1} need a human decision:\n" +
-             blocked.map { |b| "  #{b.feature.ordinal} #{b.status.emoji} #{b.feature.title} — see blocked.md" }.join("\n") +
-             "\n\nWrite the answers into blocked.md, then: agentilda unblock " \
-             "#{blocked.map { |b| b.feature.ordinal }.join(",")} --commit")
+               blocked.map { |b| "  #{b.feature.ordinal} #{b.status.emoji} #{b.feature.title} — see blocked.md" }.join("\n") +
+               "\n\nWrite the answers into blocked.md, then: agentilda unblock " \
+               "#{blocked.map { |b| b.feature.ordinal }.join(",")} --commit")
       end
     end
   end

data/lib/agentilda/cli/unblock/unblock.rb

@@ -17,17 +17,21 @@ module Agentilda
 
       # What each token turned out to be, for whoever has to fix it.
       PROBLEMS = {
-        missing: "no plan of that number",
+        missing:     "no plan of that number",
         not_blocked: "no blocked.md, so there is nothing to drain"
       }.freeze
 
       desc "Fold answered blocks into a plan's documents and retire blocked.md"
 
-      argument :plans, type: :array, required: true,
-        desc: "Which plans to drain: NNN or NNN.MM, e.g. 003 005.01"
+      argument :plans,
+        type:     :array,
+        required: true,
+        desc:     "Which plans to drain: NNN or NNN.MM, e.g. 003 005.01"
 
-      option :commit, type: :boolean, default: false,
-        desc: "Actually invoke the agent (default: dry run, prints the questions still open)"
+      option :commit,
+        type:    :boolean,
+        default: false,
+        desc:    "Actually invoke the agent (default: dry run, prints the questions still open)"
       option :agent, default: DEFAULT_AGENT, desc: "Hand the folder to a different agent"
       option :root, desc: "Repository root the agent works in (default: the .plans parent)"
 
@@ -43,8 +47,11 @@ module Agentilda
       def call(plans:, **options)
         tree = tree_for(options)
         quiet?(options)
-        unblocker = Unblocker.new(tree:, agent: agent_for(options), root: options[:root],
-          commit: commit?(options), executor: Executor.new(root: options[:root] || File.dirname(tree.dir),
+        unblocker = Unblocker.new(tree:,
+          agent: agent_for(options),
+          root: options[:root],
+          commit: commit?(options),
+          executor: Executor.new(root: options[:root] || File.dirname(tree.dir),
             dry_run: !commit?(options)))
 
         targets = unblocker.resolve(plans)
@@ -55,7 +62,7 @@ module Agentilda
         credentials_warning if commit?(options) && !quiet?(options)
         preflight(subjects, unblocker, options)
 
-        outcomes = unblocker.call(subjects)
+        outcomes = Control.on_interrupt { unblocker.call(subjects) }
         outcomes.each { |outcome| report(outcome, options) }
         footer(outcomes, options) unless quiet?(options)
         exit(worst(targets, outcomes))
@@ -110,7 +117,7 @@ module Agentilda
       # @param unblocker [Agentilda::Unblocker]
       # @param options [Hash]
       # @return [void]
-      def preflight(subjects, unblocker, options)
+      def preflight(subjects, _unblocker, options)
         return if quiet?(options)
 
         subjects.each do |subject|
@@ -190,7 +197,7 @@ module Agentilda
 
         unless commit?(options)
           warn("Dry run: no agent was invoked, and #{outcomes.size} " \
-               "plan#{"s" unless outcomes.size == 1} #{(outcomes.size == 1) ? "is" : "are"} unchanged.\n" \
+               "plan#{"s" unless outcomes.size == 1} #{outcomes.size == 1 ? "is" : "are"} unchanged.\n" \
                "Re-run with --commit to fold in whatever has been answered.")
           return
         end
@@ -203,9 +210,13 @@ module Agentilda
         success("#{folded} question#{"s" unless folded == 1} folded in · " \
                 "#{cleared} plan#{"s" unless cleared == 1} out of the block · " \
                 "#{waiting} still waiting on a human." +
-                (folded.zero? ? "\n\nNothing moved. An answer has to be written into blocked.md as its own " \
-                                "`## A<n>` section, answering the `## B<n>` of the same number, before " \
-                                "there is anything to fold." : ""))
+                (if folded.zero?
+                   "\n\nNothing moved. An answer has to be written into blocked.md as its own " \
+                     "`## A<n>` section, answering the `## B<n>` of the same number, before " \
+                     "there is anything to fold."
+                 else
+                   ""
+                 end))
       end
 
       # The most serious thing that happened, as an exit status. A tree that

data/lib/agentilda/cli/worktree/worktree.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda worktree` — create and seed worktrees for plans.
+    class Worktree < Base
+      desc "Create and seed a worktree for a plan"
+
+      argument :plan,
+        required: true,
+        desc:     "Plan ordinal (e.g. 002, 002.00, or a plan folder name)"
+
+      option :skip_seed,
+        type:    :boolean,
+        default: false,
+        desc:    "Create the worktree but skip seeding it with .env and credential files"
+
+      example [
+        "002                         # create/seed the worktree for plan 002.00",
+        "002.01                      # create/seed the worktree for plan 002.01",
+        "002.00-⚪️ → update-dsl      # find the plan by its folder name",
+        "--skip-seed 003             # create the worktree but don't seed it"
+      ]
+
+      # @param plan [String] plan identifier
+      # @param options [Hash]
+      # @return [void]
+      def call(plan:, **options)
+        tree = tree_for(options)
+        is_quiet = quiet?(options)
+
+        feature = resolve_plan(tree, plan)
+        unless feature
+          refuse("Could not find plan: #{plan}", 66)
+        end
+
+        root = File.dirname(tree.dir)
+        worktree = ::Agentilda::Worktree.new(root:)
+
+        checkout = worktree.checkout_for(feature)
+
+        return if is_quiet
+
+        if checkout.created?
+          puts("✓ Created worktree for #{feature.ordinal}: #{checkout.path}")
+        else
+          puts("✓ Using existing worktree for #{feature.ordinal}: #{checkout.path}")
+        end
+
+        unless options[:skip_seed]
+          seeded = worktree.seed(checkout.path)
+          if seeded
+            puts("✓ Seeded with .env and credential files")
+          else
+            warn("⚠ Could not seed worktree, see above for details")
+          end
+        end
+
+        puts("")
+        success("Worktree ready for #{feature.ordinal}")
+        puts("Path: #{checkout.path}")
+        puts("Branch: #{checkout.branch}")
+      end
+
+      private
+
+      # Find the plan that matches the given identifier.
+      #
+      # @param tree [Agentilda::Tree] plans directory wrapper
+      # @param plan [String] ordinal, folder name, or slug
+      # @return [Agentilda::Feature, nil]
+      def resolve_plan(tree, plan)
+        # Try parsing as an ordinal first
+        ordinal = ::Agentilda::Ordinal.parse(plan)
+        if ordinal
+          found = tree.features.find { |f| f.ordinal == ordinal }
+          return found if found
+        end
+
+        # Try matching by folder name
+        tree.features.find { |f| f.dirname == plan }
+      end
+    end
+  end
+end