plan_driven 0.1.0 → 0.2.0

data/lib/plan_driven/delivery.rb

@@ -24,6 +24,7 @@ module PlanDriven
                           guard_report: result.report.to_h)
       plan.log!("plan.drafted", actor: actor, model: llm.label, attempts: result.attempts,
                                 assumptions: result.assumptions)
+      Usage.record_llm(plan, llm, "plan drafted", actor: actor)
       Renderer.write_plan(plan, config: config)
       [plan, result]
     end
@@ -43,6 +44,7 @@ module PlanDriven
     def redraft_section(plan, key, instruction)
       text = drafter.redraft(plan.sections, key, instruction)
       edit_section(plan, key, text)
+      Usage.record_llm(plan, llm, "#{key} redrafted", actor: actor)
       text
     end
 
@@ -76,7 +78,11 @@ module PlanDriven
 
     def draft_tickets(plan, instruction: nil)
       require_status!(plan, %w[approved ticketed])
-      result = TicketGenerator.new(llm: llm, schema: schema, config: config).generate(plan, instruction: instruction)
+      result = begin
+        TicketGenerator.new(llm: llm, schema: schema, config: config).generate(plan, instruction: instruction)
+      ensure
+        Usage.record_llm(plan, llm, instruction ? "tickets redrafted" : "tickets drafted", actor: actor)
+      end
       raise GuardError, result.report.errors unless result.report.ok?
 
       replace_tickets(plan, result)
@@ -190,6 +196,7 @@ module PlanDriven
                                               method: config.merge_method)
       ticket.update!(merged_sha: result["sha"])
       Workflow.ticket_transition!(ticket, "merged")
+      clean_up_agent(ticket)
       ticket.plan.log!("ticket.merged", actor: actor, ticket: ticket, sha: result["sha"])
       finish(ticket.plan)
       ticket
@@ -233,13 +240,14 @@ module PlanDriven
       run = agents.run(ticket.agent_id, ticket.agent_run_id)
       return unless run.terminal?
 
+      Usage.record_agent(ticket, run, agents, actor: actor, config: config)
       if run.finished? && run.pr_url
         ticket.update!(pr_url: run.pr_url, pr_number: GitHub.pr_number(run.pr_url), branch: run.branch)
         Workflow.ticket_transition!(ticket, "pr_open")
-        ticket.plan.log!("ticket.pr_opened", actor: "cursor-agent", ticket: ticket, pr: run.pr_url)
+        ticket.plan.log!("ticket.pr_opened", actor: agent_actor, ticket: ticket, pr: run.pr_url)
       else
         Workflow.ticket_transition!(ticket, "failed")
-        ticket.plan.log!("ticket.agent_failed", actor: "cursor-agent", ticket: ticket, status: run.status,
+        ticket.plan.log!("ticket.agent_failed", actor: agent_actor, ticket: ticket, status: run.status,
                                                 result: run.result.to_s[0, 500])
       end
     end
@@ -250,6 +258,7 @@ module PlanDriven
 
       ticket.update!(merged_sha: pull["merge_commit_sha"])
       Workflow.ticket_transition!(ticket, "merged")
+      clean_up_agent(ticket)
       ticket.plan.log!("ticket.merged", actor: pull.dig("merged_by", "login") || "github", ticket: ticket,
                                         sha: pull["merge_commit_sha"], outside_plan_driven: true)
     end
@@ -262,6 +271,14 @@ module PlanDriven
       plan.log!("plan.delivered", actor: actor)
     end
 
+    def clean_up_agent(ticket)
+      agents.cleanup(ticket.agent_id) if ticket.agent_id && agents.respond_to?(:cleanup)
+    end
+
+    def agent_actor
+      "#{config.agent_provider}-agent"
+    end
+
     def feature_files(files, sha)
       files.select { |file| file["filename"].end_with?(".feature") && file["status"] != "removed" }
            .to_h { |file| [file["filename"], github.file(file["filename"], ref: sha)] }
@@ -344,7 +361,8 @@ module PlanDriven
     end
 
     def llm
-      @llm ||= LLM.new(config)
+      @llm = MeteredLLM.new(@llm || LLM.new(config)) unless @llm.is_a?(MeteredLLM)
+      @llm
     end
 
     def schema
@@ -356,7 +374,7 @@ module PlanDriven
     end
 
     def agents
-      @agents ||= CursorAgents.new(config: config)
+      @agents ||= Agents.build(config)
     end
   end
 end

data/lib/plan_driven/evidence.rb

@@ -17,6 +17,10 @@ module PlanDriven
       end
     end
 
+    # Scenarios commit and wipe data, so they never run against the development database, even
+    # when plan-driven itself was started from a development server (the wizard).
+    CUCUMBER_ENV = { "RAILS_ENV" => "test", "RACK_ENV" => "test" }.freeze
+
     module_function
 
     def tag_expression(plan)
@@ -29,7 +33,7 @@ module PlanDriven
         shown = command&.join(" ") || %(bundle exec cucumber --tags "#{tag_expression(plan)}")
         command ||= ["bundle", "exec", "cucumber", "--tags", tag_expression(plan), "--format", "json", "--out", out,
                      "--format", "progress"]
-        output, status = Open3.capture2e(*command, chdir: root.to_s)
+        output, status = Open3.capture2e(CUCUMBER_ENV, *command, chdir: root.to_s)
         json = File.exist?(out) ? File.read(out) : "[]"
         record(plan, json, command: shown, actor: actor, exit_ok: status.success?, output: output)
       end

data/lib/plan_driven/github.rb

@@ -33,6 +33,10 @@ module PlanDriven
       request(:post, "/repos/#{repository}/issues/#{number}/comments", { body: body })
     end
 
+    def create_pull(title:, head:, base:, body:)
+      request(:post, "/repos/#{repository}/pulls", { title: title, head: head, base: base, body: body })
+    end
+
     def pull(number)
       request(:get, "/repos/#{repository}/pulls/#{number}")
     end

data/lib/plan_driven/guards/migration_guard.rb

@@ -4,16 +4,29 @@ module PlanDriven
   module Guards
     # Zero-downtime rules for the Database changes section: expand first, contract last.
     class MigrationGuard
-      DESTRUCTIVE = /\b(remove|drop|delete|rename)\w*\b[^.\n]{0,80}\b(column|table|field)s?\b|
-                     \b(remove_column|drop_table|rename_column|rename_table|change_column)\b/ix
-      SAFE_REMOVAL = /ignored_columns|expand|contract|in a later (step|phase|release)|after (the )?backfill/i
+      # Removing a constraint, an index or a foreign key loses no data, so `remove_check_constraint`
+      # is not a removal; the migration methods that drop columns are listed by name.
+      DESTRUCTIVE = /
+        \b(remov(e|es|ed|ing|al)|drop(s|ped|ping)?|delet(e|es|ed|ing|ion)|renam(e|es|ed|ing))\b
+          [^.\n]{0,80}\b(column|table|field)s?\b
+        | \b(remove_columns?|remove_reference|remove_belongs_to|remove_timestamps|drop_table|
+             rename_column|rename_table|change_column)\b
+      /ix
+      # A removal is staged when its own sentence says so, or when it sits under a contract step.
+      SAFE_REMOVAL = Regexp.union(/ignored_columns|\bcontract\b/i, /in a later (step|phase|release|migration|deploy)/i,
+                                  /after (the )?(backfill|deploy)|once (reads|the code|no code)/i)
+      LATER_STEP = /\b(contract|clean[\s-]?up|later (step|phase|release|migration|deploy)|follow[\s-]?up)\b/i
+      ROLLBACK = /\b(roll[\s-]?back|down migration|undo)\b/i
+      NEGATED = /\b(no|not|never|none|nothing|don't|doesn't|won't|without|isn't|aren't)\b/i
+      UNCHANGED = /\b(not\s(be\s)?(changed|modified|touched)|unchanged|untouched|no\schanges?\b|
+                     keeps?\s(its|their)\s(current|existing)|stays?\sthe\ssame|as\s(it|they)\s(is|are)\stoday)/ix
       NOT_NULL = /\bnot[\s_-]?null\b|null:\s*false/i
       NOT_NULL_SAFE = /default|backfill|nullable first|after (the )?backfill|validate/i
       INDEX = /\badd_index\b|\bindex(es)?\b/i
       CONCURRENT = /concurrent|algorithm:\s*:concurrently|disable_ddl_transaction/i
       NEW_TABLE = /
         create_table\s+[:"']?([a-z][a-z0-9_]+)
-        | new\s+table:?\s*`?([a-z][a-z0-9_]+)
+        | new\s+table(?::\s*`?|\s+`)([a-z][a-z0-9_]+)
         | create\s+(?:a\s+|the\s+)?(?:new\s+)?`([a-z][a-z0-9_]+)`\s+table
         | create\s+(?:a\s+|the\s+)?(?:new\s+)?table\s+`?([a-z][a-z0-9_]+)
         | create:?\s+`([a-z][a-z0-9_]+)`(?!\s+(?:column|index))
@@ -35,18 +48,82 @@ module PlanDriven
         report
       end
 
+      # Tables the section creates. One that's already in the schema isn't new, however it's
+      # mentioned (a plan citing `20260929_create_rsvps.rb` as an example creates nothing).
       def new_tables
-        @text.scan(NEW_TABLE).flatten.compact.map(&:downcase).uniq
+        @text.scan(NEW_TABLE).flatten.compact.map(&:downcase).uniq - @schema.tables
       end
 
       private
 
       def check_destructive(report)
-        return unless @text.match?(DESTRUCTIVE)
-        return if @text.match?(SAFE_REMOVAL)
+        created = new_tables
+        unsafe = destructive_statements.reject do |statement, heading|
+          statement.match?(SAFE_REMOVAL) || statement.match?(ROLLBACK) ||
+            heading.to_s.match?(LATER_STEP) || heading.to_s.match?(ROLLBACK) ||
+            only_new_tables?(statement, created)
+        end
+        return if unsafe.empty?
+
+        report.error("Database changes remove or rename a column or table in one step " \
+                     "(\"#{unsafe.first.first.strip[0, 90]}\"). Split it: stop using it and add it to " \
+                     "`ignored_columns`, deploy, then remove it in a later contract step.")
+      end
+
+      # [sentence or code line, the heading it's under] for every change that removes or renames.
+      # Headings are only context ("### Removed or renamed columns"), and a negated sentence
+      # ("No column is removed") changes nothing.
+      def destructive_statements
+        statements.select do |statement, _heading, fenced|
+          statement.match?(DESTRUCTIVE) && (fenced || !negated?(statement))
+        end
+      end
+
+      public
+
+      # Existing tables the section changes: something is added to them or removed from them.
+      # Tables it only compares with ("same as `rsvps`") or names as staying the same
+      # ("### Tables not changed") don't count.
+      def changed_tables
+        removals = destructive_statements.reject { |statement, heading| unchanged?(statement, heading) }
+        @schema.tables.select do |table|
+          named = /\b#{Regexp.escape(table)}\b/
+          paragraph_changing(table).split("\n").any? { |line| !line.match?(UNCHANGED) } ||
+            removals.any? { |statement, _| statement.match?(named) }
+        end
+      end
+
+      private
+
+      def unchanged?(statement, heading)
+        statement.match?(UNCHANGED) || heading.to_s.match?(UNCHANGED)
+      end
+
+      # [sentence or code line, the heading above it, inside a code block?] for the whole section.
+      def statements
+        heading = nil
+        fenced = false
+        @text.each_line.with_object([]) do |line, found|
+          if line.start_with?("```")
+            fenced = !fenced
+          elsif !fenced && line.match?(/\A\#{1,6}\s/)
+            heading = line
+          else
+            (fenced ? [line] : line.split(/(?<=[.!?])\s+/)).each { |statement| found << [statement, heading, fenced] }
+          end
+        end
+      end
+
+      # Dropping or changing a table this plan creates touches nothing that runs today.
+      def only_new_tables?(statement, created)
+        named = statement.scan(/[:`"']([a-z][a-z0-9_]*)\b/).flatten & @schema.tables
+        created.any? && named.empty? && created.any? { |table| statement.match?(/\b#{Regexp.escape(table)}\b/) }
+      end
 
-        report.error("Database changes remove or rename a column or table in one step. Split it: stop using " \
-                     "it and add it to `ignored_columns`, deploy, then remove it in a later migration.")
+      # Only a negation before the change counts: "No column is removed", not "Drop it; no code reads it".
+      def negated?(statement)
+        change = statement =~ /\b(remove|drop|delete|rename|change_column)/i
+        change && statement[0, change].match?(NEGATED)
       end
 
       def check_not_null(report)

data/lib/plan_driven/guards/ticket_guard.rb

@@ -129,8 +129,7 @@ module PlanDriven
         touched = @tickets.flat_map { |ticket| ticket["touches"] }.uniq
         planned = MigrationGuard.new(@sections["database_changes"].to_s, schema: @schema)
         new_tables = planned.new_tables
-        mentioned = @schema.tables.select { |table| @sections["database_changes"].to_s.match?(/\b#{table}\b/) }
-        (new_tables + mentioned).uniq.each do |table|
+        (new_tables + planned.changed_tables).uniq.each do |table|
           next if touched.include?(table)
 
           report.warning("Database changes mention #{table}, but no ticket touches it")

data/lib/plan_driven/interview.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module PlanDriven
+  # The interview as the team changed it, with `plan-driven question` or the wizard's
+  # Configuration page. It lives in the application, in config/plan_driven/interview.yml, so it
+  # is committed and everyone on the team gets the same questions:
+  #
+  #     questions:
+  #       who:
+  #         question: Who owns it, and who reviews the pull requests?
+  #       success_metric:
+  #         title: Success metric
+  #         question: How will we know it worked?
+  #         group: Overview
+  #         required: false
+  #
+  # A key the template already asks changes that question; any other key adds one. Drafted
+  # sections belong to the model and can't be changed here.
+  module Interview
+    PATH = "config/plan_driven/interview.yml"
+    KEY = /\A[a-z][a-z0-9_]{1,39}\z/
+    FIELDS = %w[title question group required].freeze
+    HEADER = "# The plan_driven interview, as changed with `plan-driven question` or the wizard.\n" \
+             "# Commit it: everyone on the team gets the same questions.\n"
+
+    module_function
+
+    def path(root = PlanDriven.configuration.root_path)
+      Pathname(root).join(PATH)
+    end
+
+    def read(root = PlanDriven.configuration.root_path)
+      file = path(root)
+      return {} unless file.exist?
+
+      data = YAML.safe_load(file.read) || {}
+      questions = data.is_a?(Hash) ? data["questions"] : nil
+      questions.is_a?(Hash) ? questions.transform_values { |fields| fields.to_h.slice(*FIELDS) } : {}
+    rescue Psych::Exception => e
+      raise ConfigurationError, "#{PATH} isn't valid YAML: #{e.message}"
+    end
+
+    # The template with the team's changes applied. Asked sections keep their place; an added
+    # question goes after the last section of its group.
+    def apply(template, root = PlanDriven.configuration.root_path)
+      changes = read(root)
+      return template if changes.empty?
+
+      sections = template.sections.map(&:dup)
+      changes.each do |key, fields|
+        existing = sections.find { |section| section.key == key }
+        next if existing&.drafted?
+
+        if existing
+          update(existing, fields)
+        else
+          insert(sections, build(key, fields))
+        end
+      end
+      Template.new(sections)
+    end
+
+    # Adds or changes one question. Returns :added or :changed.
+    def change(key, fields, template:, root: PlanDriven.configuration.root_path)
+      key = validate_key(key, template)
+      fields = normalize(fields)
+      raise ArgumentError, "Nothing to change: pass --title, --ask, --group, --required or --optional" if fields.empty?
+
+      changes = read(root)
+      changes[key] = changes.fetch(key, {}).merge(fields)
+      added = template[key].nil?
+      validate_new(changes[key]) if added
+      write(changes, root)
+      added ? :added : :changed
+    end
+
+    # Removes an added question, or puts a changed one back to the template's default.
+    def remove(key, template:, root: PlanDriven.configuration.root_path)
+      changes = read(root)
+      raise ArgumentError, "#{key} has no changes to remove" unless changes.key?(key.to_s)
+
+      changes.delete(key.to_s)
+      write(changes, root)
+      template[key].nil? ? :removed : :reset
+    end
+
+    def origin(key, template:, root: PlanDriven.configuration.root_path)
+      return "default" unless read(root).key?(key.to_s)
+
+      template[key].nil? ? "added" : "changed"
+    end
+
+    def update(section, fields)
+      section.title = fields["title"] if fields["title"].to_s.strip != ""
+      section.question = fields["question"] if fields["question"].to_s.strip != ""
+      section.group = fields["group"] if Template::GROUPS.include?(fields["group"])
+      return unless fields.key?("required")
+
+      section.required = fields["required"] == true
+      section.min_words = section.required ? [section.min_words.to_i, 1].max : 0
+    end
+
+    def build(key, fields)
+      required = fields["required"] == true
+      group = Template::GROUPS.include?(fields["group"]) ? fields["group"] : "Overview"
+      Template::Section.new(
+        key: key, title: fields["title"].to_s, group: group, source: :ask, required: required,
+        min_words: required ? 1 : 0, question: fields["question"].to_s,
+        guidance: "The team's answer to: #{fields["question"]}"
+      )
+    end
+
+    def normalize(fields)
+      fields = fields.to_h.transform_keys(&:to_s).slice(*FIELDS).compact
+      %w[title question].each { |name| fields[name] = fields[name].to_s.strip if fields.key?(name) }
+      validate_group(fields["group"]) if fields.key?("group")
+      fields
+    end
+
+    def validate_new(fields)
+      raise ArgumentError, "A new question needs --title" if fields["title"].to_s.empty?
+      raise ArgumentError, "A new question needs --ask \"the question\"" if fields["question"].to_s.empty?
+    end
+
+    def insert(sections, section)
+      index = sections.rindex { |existing| existing.group == section.group }
+      index ? sections.insert(index + 1, section) : sections << section
+    end
+
+    def validate_key(key, template)
+      key = key.to_s.strip
+      unless key.match?(KEY)
+        raise ArgumentError,
+              "#{key.inspect} isn't a question key: lower case letters, digits and _, like success_metric"
+      end
+      if template[key]&.drafted?
+        raise ArgumentError, "#{key} is drafted by the model, not asked; only asked questions can be changed"
+      end
+
+      key
+    end
+
+    def validate_group(group)
+      return if Template::GROUPS.include?(group)
+
+      raise ArgumentError, "Unknown group #{group.inspect}. One of: #{Template::GROUPS.join(", ")}"
+    end
+
+    def write(changes, root)
+      file = path(root)
+      return file.tap { FileUtils.rm_f(file) } if changes.empty?
+
+      FileUtils.mkdir_p(file.dirname)
+      file.write(HEADER + YAML.dump("questions" => changes).delete_prefix("---\n"))
+      file
+    end
+  end
+end

data/lib/plan_driven/local_agents.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "securerandom"
+require "shellwords"
+
+module PlanDriven
+  # Which coding agents take the tickets: config.agent_provider.
+  module Agents
+    def self.build(config = PlanDriven.configuration)
+      case config.agent_provider.to_sym
+      when :cursor then CursorAgents.new(config: config)
+      when :local then LocalAgents.new(config: config)
+      else raise ConfigurationError, "config.agent_provider is #{config.agent_provider.inspect}; use :cursor or :local"
+      end
+    end
+  end
+
+  # Runs a coding agent CLI on this machine: Claude Code, Codex, the Cursor CLI, or anything else
+  # that edits the files in its working directory. The prompt arrives on stdin, or wherever the
+  # command says `{prompt_file}`.
+  #
+  #   config.agent_provider = :local
+  #   config.agent_command = "claude -p --permission-mode acceptEdits --output-format json"
+  #   config.agent_command = "codex exec --full-auto -"
+  #   config.agent_command = 'cursor-agent -p --force --output-format json "$(cat {prompt_file})"'
+  #
+  # Each ticket gets its own git worktree and branch under tmp/plan_driven/agents. When the
+  # command exits cleanly, plan_driven commits what it left, pushes the branch and opens the pull
+  # request, so the rest of the workflow (review, feedback, merge) is the same as with Cursor.
+  class LocalAgents
+    PR_BODY = "PR_DESCRIPTION.md"
+    INSTRUCTIONS = <<~TEXT.freeze
+      # Working locally
+      You are in a git worktree on the ticket's own branch. Don't push and don't open the pull request:
+      plan_driven does both when you finish. Write the pull request description (the part described
+      above) to `#{PR_BODY}` in the repository root; it becomes the pull request body and isn't committed.
+      Committing is optional, anything you leave uncommitted is committed for you.
+    TEXT
+
+    Run = CursorAgents::Run
+
+    def initialize(config: PlanDriven.configuration, github: nil)
+      @config = config
+      @github = github
+    end
+
+    def launch(prompt:, repo_url:, name:) # rubocop:disable Lint/UnusedMethodArgument
+      command!
+      id = "local-#{SecureRandom.hex(4)}"
+      state = { "id" => id, "name" => name, "branch" => "plan-driven/#{slug(name)}-#{id.delete_prefix("local-")}",
+                "dir" => root.join(id).to_s, "runs" => [] }
+      git(@config.root_path, "fetch", "--quiet", "origin", @config.base_branch)
+      git(@config.root_path, "worktree", "add", "--quiet", "-b", state["branch"], state["dir"],
+          "origin/#{@config.base_branch}")
+      run = start(state, "#{prompt}\n\n#{INSTRUCTIONS}")
+      [{ "id" => id, "url" => nil }, run]
+    end
+
+    def run(agent_id, run_id)
+      state = load(agent_id)
+      entry = state["runs"].find { |item| item["id"] == run_id } or raise ProviderError, "no local run #{run_id}"
+      return to_run(state, entry) if entry["status"]
+
+      exit_file = Pathname(entry["exit_file"])
+      if !exit_file.exist? && alive?(entry["pid"])
+        return to_run(state, entry, "RUNNING") unless overdue?(entry)
+
+        stop(entry["pid"])
+        return settle(state, entry, "EXPIRED", "stopped after #{@config.agent_timeout}s (config.agent_timeout)")
+      end
+
+      code = exit_file.exist? ? exit_file.read.strip.to_i : 1
+      unless code.zero?
+        return settle(state, entry, "ERROR",
+                      "the agent command exited with #{code}: #{log_tail(entry)}")
+      end
+
+      publish(state, entry)
+    end
+
+    def follow_up(agent_id, text)
+      state = load(agent_id)
+      start(state, "#{text}\n\n#{INSTRUCTIONS}")
+    end
+
+    # Tokens, when the command reports them the way Claude Code's `--output-format json` does.
+    def usage(agent_id, run_id)
+      entry = load(agent_id)["runs"].find { |item| item["id"] == run_id }
+      data = entry && reported_usage(Pathname(entry["log"]))
+      return {} unless data
+
+      { "input_tokens" => data["input_tokens"].to_i, "output_tokens" => data["output_tokens"].to_i,
+        "cache_write_tokens" => data["cache_creation_input_tokens"].to_i,
+        "cache_read_tokens" => data["cache_read_input_tokens"].to_i }
+    end
+
+    # Once the pull request is merged, the worktree and its local branch go.
+    def cleanup(agent_id)
+      state = load(agent_id)
+      git(@config.root_path, "worktree", "remove", "--force", state["dir"]) if Dir.exist?(state["dir"])
+      git_ok?(@config.root_path, "branch", "-D", state["branch"])
+    rescue ProviderError
+      nil
+    end
+
+    def me
+      { "apiKeyName" => "local: #{command!}" }
+    end
+
+    def model_ids
+      []
+    end
+
+    private
+
+    def start(state, prompt)
+      number = state["runs"].size + 1
+      base = root.join("#{state["id"]}-run-#{number}")
+      File.write("#{base}.prompt", prompt)
+      prompt_file = Shellwords.escape("#{base}.prompt")
+      agent = if command!.include?("{prompt_file}")
+                "#{command!.gsub("{prompt_file}", prompt_file)} < /dev/null"
+              else
+                "#{command!} < #{prompt_file}"
+              end
+      script = "#{agent} > #{Shellwords.escape("#{base}.log")} 2>&1; echo $? > #{Shellwords.escape("#{base}.exit")}"
+      pid = Process.spawn("sh", "-c", script, chdir: state["dir"], pgroup: true, in: File::NULL)
+      Process.detach(pid)
+      entry = { "id" => "#{state["id"]}-run-#{number}", "pid" => pid, "started_at" => Time.now.to_i,
+                "log" => "#{base}.log", "exit_file" => "#{base}.exit" }
+      state["runs"] << entry
+      save(state)
+      to_run(state, entry, "RUNNING")
+    end
+
+    # Commit, push, and open the pull request the first time; later runs push to the same one.
+    def publish(state, entry)
+      dir = Pathname(state["dir"])
+      body = commit_all(dir, state["name"])
+      if git(dir, "rev-list", "--count", "origin/#{@config.base_branch}..HEAD").strip == "0"
+        return settle(state, entry, "ERROR", "the agent finished without changing anything: #{log_tail(entry)}")
+      end
+
+      git(dir, "push", "--quiet", "--set-upstream", "origin", state["branch"])
+      state["pr_url"] ||= github.create_pull(title: state["name"], head: state["branch"], base: @config.base_branch,
+                                             body: body || state["name"])["html_url"]
+      settle(state, entry, "FINISHED", body.to_s[0, 500])
+    rescue ProviderError => e
+      settle(state, entry, "ERROR", e.message)
+    end
+
+    # Commits what the agent left, without its pull request description, which is returned.
+    def commit_all(dir, message)
+      body_file = dir.join(PR_BODY)
+      body = body_file.exist? ? body_file.read : nil
+      FileUtils.rm_f(body_file)
+      git(dir, "add", "--all")
+      git(dir, "commit", "--quiet", "-m", message) unless git_ok?(dir, "diff", "--cached", "--quiet")
+      body
+    end
+
+    def settle(state, entry, status, result)
+      entry["status"] = status
+      entry["result"] = result
+      entry["duration_ms"] = (Time.now.to_i - entry["started_at"]) * 1000
+      save(state)
+      to_run(state, entry)
+    end
+
+    def to_run(state, entry, status = entry["status"])
+      Run.new(id: entry["id"], agent_id: state["id"], status: status, result: entry["result"],
+              branch: state["branch"], pr_url: status == "FINISHED" ? state["pr_url"] : nil,
+              duration_ms: entry["duration_ms"])
+    end
+
+    def reported_usage(log)
+      return unless log.exist?
+
+      log.read.lines.reverse_each do |line|
+        data = JSON.parse(line)
+        return data["usage"] if data.is_a?(Hash) && data["usage"].is_a?(Hash)
+      rescue JSON::ParserError
+        next
+      end
+      nil
+    end
+
+    def command!
+      @config.agent_command.presence or
+        raise ConfigurationError, "config.agent_provider is :local, so set config.agent_command, for example " \
+                                  "\"claude -p --permission-mode acceptEdits --output-format json\""
+    end
+
+    def git(dir, *args)
+      out, status = Open3.capture2e("git", *args, chdir: dir.to_s)
+      raise ProviderError, "git #{args.first} failed: #{out.strip.last(300)}" unless status.success?
+
+      out
+    end
+
+    def git_ok?(dir, *args)
+      _out, status = Open3.capture2e("git", *args, chdir: dir.to_s)
+      status.success?
+    end
+
+    def alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    def overdue?(entry)
+      Time.now.to_i - entry["started_at"] > @config.agent_timeout.to_i
+    end
+
+    def stop(pid)
+      Process.kill("TERM", -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    def log_tail(entry)
+      log = Pathname(entry["log"])
+      log.exist? ? log.read.strip.last(300) : "no output"
+    end
+
+    def slug(name)
+      name.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")[0, 40]
+    end
+
+    def root
+      @config.root_path.join("tmp/plan_driven/agents").tap { |dir| FileUtils.mkdir_p(dir) }
+    end
+
+    def load(agent_id)
+      path = root.join("#{agent_id}.json")
+      raise ProviderError, "no local agent #{agent_id} (#{path} is missing)" unless path.exist?
+
+      JSON.parse(path.read)
+    end
+
+    def save(state)
+      File.write(root.join("#{state["id"]}.json"), JSON.pretty_generate(state))
+    end
+
+    def github
+      @github ||= GitHub.new
+    end
+  end
+end