gitbroker 0.3.0

data/lib/gitbroker/run_script.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "shellwords"
+require "rbconfig"
+
+module Gitbroker
+  # Terminal mode (spec §4.2 step 6): the script the terminal runs. The task token lives only here (0700, private
+  # state dir, deleted on start) and in the agent's environment. The prompt travels in an environment variable, so
+  # quoting never matters. When the agent exits, `gitbroker task-ended` tells GitBroker.
+  class RunScript
+    TASK_ID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/
+    EXE = File.join(Gitbroker::ROOT, "exe", "gitbroker")
+
+    def initialize(state_dir:, ruby: RbConfig.ruby, exe: EXE)
+      @state_dir = state_dir
+      @ruby = ruby
+      @exe = exe
+    end
+
+    def task_dir(task_id)
+      raise Error, "Invalid task id #{task_id.inspect}" unless task_id.to_s.match?(TASK_ID)
+
+      File.join(@state_dir, "tasks", task_id)
+    end
+
+    def write!(task_id:, worktree:, token:, server:, argv:, prompt:, notice: nil)
+      dir = task_dir(task_id)
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      File.chmod(0o700, dir)
+      path = File.join(dir, "run.sh")
+      FileUtils.rm_f(path)
+      File.write(path, render(task_id:, worktree:, token:, server:, argv:, prompt:, notice:), perm: 0o700)
+      File.chmod(0o700, path)
+      path
+    end
+
+    private
+
+    def render(task_id:, worktree:, token:, server:, argv:, prompt:, notice:)
+      inner = %(#{Shellwords.join(argv)} "$GITBROKER_PROMPT")
+      <<~SH
+        #!/bin/bash
+        # Written by the GitBroker companion for agent task #{task_id}. Deletes itself on start.
+        rm -f -- "$0"
+        #{"printf '%s\\n' #{Shellwords.escape(notice)}" if notice}
+        export GITBROKER_TASK_TOKEN=#{Shellwords.escape(token)}
+        export GITBROKER_TASK_ID=#{Shellwords.escape(task_id)}
+        export GITBROKER_SERVER=#{Shellwords.escape(server)}
+        export GITBROKER_PROMPT=#{Shellwords.escape(prompt)}
+        cd #{Shellwords.escape(worktree)} || exit 1
+        "${SHELL:-/bin/bash}" -lic #{Shellwords.escape(inner)}
+        status=$?
+        #{Shellwords.escape(@ruby)} #{Shellwords.escape(@exe)} task-ended "$status"
+      SH
+    end
+  end
+end

data/lib/gitbroker/runner.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Gitbroker
+  class Runner
+    # Spec §4.1: never let a repository's own config run code through git.
+    SAFE_GIT = [ "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null" ].freeze
+    # Git exports these to hooks (and `git rebase` etc.); inherited, they would point every git command at another
+    # repository, so each subprocess starts without them.
+    GIT_ENV = %w[GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES
+                 GIT_NAMESPACE GIT_PREFIX GIT_QUARANTINE_PATH].to_h { [ _1, nil ] }.freeze
+
+    def run!(*argv, chdir: nil)
+      options = chdir ? { chdir: } : {}
+      out, status = Open3.capture2e(GIT_ENV, *argv, **options)
+      raise Error, "`#{argv.join(" ")}` failed: #{out.strip}" unless status.success?
+
+      out
+    rescue Errno::ENOENT
+      raise Error, "#{argv.first} not found on PATH"
+    end
+
+    def success?(*argv)
+      _out, status = Open3.capture2e(GIT_ENV, *argv)
+      status.success?
+    rescue Errno::ENOENT
+      false
+    end
+
+    def capture(*argv)
+      out, _status = Open3.capture2e(GIT_ENV, *argv)
+      out
+    rescue Errno::ENOENT
+      ""
+    end
+
+    def git(dir, *args) = run!("git", *SAFE_GIT, "-C", dir, *args)
+    def git_success?(dir, *args) = success?("git", *SAFE_GIT, "-C", dir, *args)
+  end
+end

data/lib/gitbroker/service_installer.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+
+module Gitbroker
+  # Runs `gitbroker start` in the background as the logged-in user (launchd on macOS, systemd --user on Linux).
+  class ServiceInstaller
+    LABEL = "broker.git.companion"
+    EXE = File.join(Gitbroker::ROOT, "exe", "gitbroker")
+
+    def initialize(platform: Gitbroker.platform, home: Dir.home, ruby: RbConfig.ruby, exe: EXE, env: ENV, runner: Runner.new,
+                   uid: Process.uid)
+      @platform = platform
+      @home = home
+      @ruby = ruby
+      @exe = exe
+      @env = env
+      @runner = runner
+      @uid = uid
+    end
+
+    def install! = @platform == "macos" ? install_launchd! : install_systemd!
+
+    def installed? = File.exist?(@platform == "macos" ? launchd_path : systemd_path)
+
+    # Starts the installed service if it is not running (a running one is left alone). False when there is no
+    # service or the manager refused, so the caller can start the daemon itself.
+    def start!
+      return false unless installed?
+
+      if @platform == "macos"
+        @runner.success?("launchctl", "kickstart", target) || bootstrap_launchd
+      else
+        @runner.success?("systemctl", "--user", "start", "gitbroker.service")
+      end
+    end
+
+    # Stops the service through its manager so KeepAlive / Restart=always does not bring it back; `start!` undoes it
+    # (a booted-out launchd job is bootstrapped again).
+    def stop!
+      return false unless installed?
+
+      if @platform == "macos"
+        @runner.success?("launchctl", "bootout", target)
+      else
+        @runner.success?("systemctl", "--user", "stop", "gitbroker.service")
+      end
+    end
+
+    # Restarts the service so it runs the currently installed gem code. The manager does the restart: the daemon asking
+    # for it may be killed mid-call and the new process still starts.
+    def restart!
+      return false unless installed?
+
+      if @platform == "macos"
+        @runner.success?("launchctl", "kickstart", "-k", target) || bootstrap_launchd
+      else
+        @runner.success?("systemctl", "--user", "restart", "gitbroker.service")
+      end
+    end
+
+    def plist
+      arguments = [ @ruby, @exe, "start" ].map { "    <string>#{xml(_1)}</string>" }.join("\n")
+      environment = { "PATH" => @env["PATH"].to_s, "SHELL" => @env["SHELL"] || "/bin/zsh", "LANG" => @env["LANG"] || "en_US.UTF-8" }
+                    .map { |key, value| "    <key>#{key}</key>\n    <string>#{xml(value)}</string>" }.join("\n")
+      log = xml(File.join(@home, "Library", "Logs", "gitbroker.log"))
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+          <key>Label</key>
+          <string>#{LABEL}</string>
+          <key>ProgramArguments</key>
+          <array>
+        #{arguments}
+          </array>
+          <key>EnvironmentVariables</key>
+          <dict>
+        #{environment}
+          </dict>
+          <key>RunAtLoad</key>
+          <true/>
+          <key>KeepAlive</key>
+          <true/>
+          <key>StandardOutPath</key>
+          <string>#{log}</string>
+          <key>StandardErrorPath</key>
+          <string>#{log}</string>
+        </dict>
+        </plist>
+      XML
+    end
+
+    def unit
+      <<~UNIT
+        [Unit]
+        Description=GitBroker companion (runs your own agents on your pull requests)
+        After=network-online.target
+
+        [Service]
+        ExecStart="#{@ruby}" "#{@exe}" start
+        Restart=always
+        RestartSec=5
+        Environment="PATH=#{@env["PATH"]}"
+        Environment="SHELL=#{@env["SHELL"] || "/bin/bash"}"
+
+        [Install]
+        WantedBy=default.target
+      UNIT
+    end
+
+    private
+
+    def target = "gui/#{@uid}/#{LABEL}"
+
+    # kickstart fails once the job was booted out (`stop!`): load it again, RunAtLoad starts it.
+    def bootstrap_launchd = @runner.success?("launchctl", "bootstrap", "gui/#{@uid}", launchd_path)
+
+    def xml(value) = value.to_s.encode(xml: :text)
+
+    def launchd_path = File.join(@home, "Library", "LaunchAgents", "#{LABEL}.plist")
+    def systemd_path = File.join(@home, ".config", "systemd", "user", "gitbroker.service")
+
+    def install_launchd!
+      path = launchd_path
+      FileUtils.mkdir_p(File.dirname(path))
+      FileUtils.mkdir_p(File.join(@home, "Library", "Logs"))
+      File.write(path, plist)
+      @runner.success?("launchctl", "bootout", "gui/#{@uid}/#{LABEL}") # not loaded yet is fine
+      @runner.run!("launchctl", "bootstrap", "gui/#{@uid}", path)
+      path
+    end
+
+    def install_systemd!
+      path = systemd_path
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, unit)
+      @runner.run!("systemctl", "--user", "daemon-reload")
+      @runner.run!("systemctl", "--user", "enable", "--now", "gitbroker.service")
+      path
+    end
+  end
+end

data/lib/gitbroker/skill_installer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Gitbroker
+  # Copies the plugin's skills to ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/<name>, for running your own agent without
+  # the companion (the copy command). Companion runs load them with --plugin-dir and need no install.
+  class SkillInstaller
+    SOURCE = File.join(Gitbroker::ROOT, "plugin", "skills")
+
+    def initialize(home: Dir.home, env: ENV, source: SOURCE)
+      @home = home
+      @env = env
+      @source = source
+    end
+
+    def install!
+      skills = Dir[File.join(@source, "*", "SKILL.md")].map { File.dirname(_1) }.sort
+      raise Error, "No skills found at #{@source}" if skills.empty?
+
+      skills.map do |skill|
+        target = File.join(@env["CLAUDE_CONFIG_DIR"] || File.join(@home, ".claude"), "skills", File.basename(skill))
+        FileUtils.rm_rf(target)
+        FileUtils.mkdir_p(File.dirname(target))
+        FileUtils.cp_r(skill, target)
+        target
+      end
+    end
+  end
+end

data/lib/gitbroker/task_files.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Gitbroker
+  # Per-task files. They reference the task token as ${GITBROKER_TASK_TOKEN}; the value only exists in the agent
+  # process environment. Spec §4.2 step 4: the GitBroker MCP config lives outside the repository.
+  class TaskFiles
+    TOKEN_ENV = "GITBROKER_TASK_TOKEN"
+    HOOK_EVENTS = %w[SessionStart Stop SessionEnd].freeze
+    SETTINGS_PATH = File.join(".claude", "settings.local.json")
+
+    def initialize(task_dir:, worktree:, server:, task_id:, runner: Runner.new)
+      @task_dir = task_dir
+      @worktree = worktree
+      @server = server.to_s.chomp("/")
+      raise Error, "Invalid task id #{task_id.inspect}" unless task_id.to_s.match?(RunScript::TASK_ID)
+
+      @task_id = task_id
+      @runner = runner
+    end
+
+    def mcp_url = "#{@server}/mcp/messages"
+    def events_url = "#{@server}/agent_tasks/#{@task_id}/events"
+
+    def mcp_config!
+      FileUtils.mkdir_p(@task_dir, mode: 0o700)
+      File.chmod(0o700, @task_dir)
+      path = File.join(@task_dir, "mcp.json")
+      FileUtils.rm_f(path)
+      server = { "type" => "http", "url" => mcp_url, "headers" => { "x-task-token" => "${#{TOKEN_ENV}}" } }
+      File.write(path, "#{JSON.pretty_generate({ "mcpServers" => { "gitbroker" => server } })}\n", perm: 0o600)
+      File.chmod(0o600, path)
+      path
+    end
+
+    # Terminal mode with Claude Code (spec §4.2 step 6): HTTP hooks report start, stop and end.
+    def claude_hooks!
+      if @runner.git_success?(@worktree, "ls-files", "--error-unmatch", SETTINGS_PATH)
+        raise Error, "The repository tracks #{SETTINGS_PATH}; GitBroker will not edit tracked files."
+      end
+
+      path = File.join(@worktree, SETTINGS_PATH)
+      if [ File.dirname(path), path ].any? { File.symlink?(_1) }
+        raise Error, "#{SETTINGS_PATH} in #{@worktree} is a symlink; GitBroker will not write through it."
+      end
+
+      FileUtils.mkdir_p(File.dirname(path))
+      data = read_json(path)
+      existing = data["hooks"] || {}
+      raise Error, "#{path} has a \"hooks\" value that is not an object; fix it, then start the task again" unless existing.is_a?(Hash)
+
+      data["hooks"] = existing.merge(hooks) { |_event, theirs, ours| Array(theirs).reject { ours?(_1) } + ours }
+      File.write(path, "#{JSON.pretty_generate(data)}\n")
+      exclude_settings
+    end
+
+    def cleanup! = FileUtils.rm_rf(@task_dir)
+
+    private
+
+    def hooks
+      hook = { "type" => "http", "url" => events_url, "headers" => { "Authorization" => "Bearer ${#{TOKEN_ENV}}" },
+               "allowedEnvVars" => [ TOKEN_ENV ], "timeout" => 10 }
+      HOOK_EVENTS.to_h { [ _1, [ { "hooks" => [ hook ] } ] ] }
+    end
+
+    def ours?(group)
+      group.is_a?(Hash) && Array(group["hooks"]).any? { _1.is_a?(Hash) && _1["url"].to_s.start_with?("#{@server}/agent_tasks/") }
+    end
+
+    def exclude_settings
+      exclude = File.expand_path(@runner.git(@worktree, "rev-parse", "--git-path", "info/exclude").strip, @worktree)
+      FileUtils.mkdir_p(File.dirname(exclude))
+      content = File.exist?(exclude) ? File.read(exclude) : ""
+      entry = "/#{SETTINGS_PATH}"
+      return if content.lines(chomp: true).include?(entry)
+
+      File.write(exclude, "#{content}#{"\n" unless content.empty? || content.end_with?("\n")}#{entry}\n")
+    end
+
+    def read_json(path)
+      data = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+      data.is_a?(Hash) ? data : raise(JSON::ParserError)
+    rescue JSON::ParserError
+      raise Error, "#{path} is not valid JSON; fix or remove it, then start the task again"
+    end
+  end
+end

data/lib/gitbroker/task_runner.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Gitbroker
+  # Runs one agent task (spec §4.2): worktree → neutralize (untrusted only) → gh or MCP prompt → MCP config →
+  # autonomous agent process or a terminal → progress and the final `finished` report.
+  class TaskRunner
+    CANCEL_GRACE = 10
+    PROGRESS_INTERVAL = 3
+    MAX_OUTPUT = 500
+    PRINT_OUTPUT = 120
+
+    Handle = Struct.new(:pid, :cancelled)
+    Outcome = Struct.new(:status, :cost_usd, :error_code, :last_output)
+
+    def initialize(config:, report:, worktree: Worktree.new(root: config.worktree_root), neutralizer: Neutralizer.new,
+                   gh_check: GhCheck.new, launcher: Launcher.new(name: config.terminal), out: $stdout, grace: CANCEL_GRACE,
+                   progress_interval: PROGRESS_INTERVAL, run_script: RunScript.new(state_dir: config.state_dir))
+      @config = config
+      @report = report
+      @worktree = worktree
+      @neutralizer = neutralizer
+      @gh_check = gh_check
+      @launcher = launcher
+      @out = out
+      @grace = grace
+      @progress_interval = progress_interval
+      @run_script = run_script
+      @handles = {}
+      @running = Set.new
+      @cancelled = Set.new
+      @lock = Mutex.new
+    end
+
+    def run(task, repositories:)
+      id = task.fetch("task_id")
+      checkout = Array(repositories).find { _1["full_name"].to_s.casecmp?(task.fetch("repo").to_s) }
+      unless checkout
+        return finished(id, "failed", 0, "no_checkout", "No local checkout of #{task["repo"]} under #{@config.roots.join(", ")}")
+      end
+      # The server never offers this (spec §5.1); refuse anyway rather than run a stranger's code, or publish what an
+      # injected agent read, unattended.
+      if task["untrusted"] && (task["code_changing"] || task["terminal_only"]) && task["mode"] != "terminal"
+        return finished(id, "failed", 0, "untrusted_head", "This task runs only in a terminal on an untrusted head")
+      end
+
+      # Codex has no --strict-mcp-config equivalent: a headless run would load the user's own MCP servers next to a
+      # prompt-injected PR. Untrusted heads run Codex only in a terminal, where the user watches and approves.
+      if task["untrusted"] && task["mode"] != "terminal" && @config.agent == "codex"
+        return finished(id, "failed", 0, "untrusted_head",
+                        "Codex does not run untrusted heads unattended (it would load your own MCP servers). Use Open in terminal, or set agent: claude.")
+      end
+
+      repo_path = checkout["path"]
+      dir = @worktree.prepare(repo_path:, full_name: task["repo"], number: task["pr_number"], head_sha: task["head_sha"],
+                              kind: task["kind"], head_ref: task["head_ref"], branch: task["code_changing"] == true,
+                              cross_repository: task["cross_repository"] == true)
+      # Agents report real paths (macOS: /private/var, not /var); progress paths are matched against this form.
+      dir = File.realpath(dir)
+      restored = task["untrusted"] ? @neutralizer.neutralize!(dir, repo_path:, number: task["pr_number"], base_ref: base_ref(task)) : []
+      task = task.merge("prompt" => prompt_for(task))
+      agent = Agents.for(@config, worktree: dir)
+      say(id, "#{task["kind"]} on #{task["repo"]}##{task["pr_number"]}: starting (#{agent.name}, #{task["mode"] == "terminal" ? "terminal" : "autonomous"})")
+      say(id, "Worktree: #{dir}")
+      files = TaskFiles.new(task_dir: @run_script.task_dir(id), worktree: dir, server: @config.server, task_id: id)
+      mcp_config = files.mcp_config!
+
+      if task["mode"] == "terminal"
+        open_terminal(task, agent, files, mcp_config, dir, restored)
+      else
+        begin
+          run_autonomous(task, agent, mcp_config, dir)
+        ensure
+          files.cleanup!
+        end
+        if @worktree.remove!(dir, repo_path:)
+          say(id, "Removed worktree #{dir}")
+        else
+          say(id, "Kept #{dir}: it has uncommitted work.")
+        end
+      end
+    rescue Error, SystemCallError, KeyError => e
+      finished(id, "failed", 0, "agent_failed", e.message)
+    end
+
+    # Spec §4.2 step 9: SIGINT to the agent's process group, SIGTERM after the grace period if it is still running.
+    def cancel(task_id)
+      # A cancel that lands between an explain run's two processes has no handle; remember it so the verifier never starts.
+      handle = @lock.synchronize do
+        @cancelled << task_id if @running.include?(task_id)
+        @handles[task_id]
+      end
+      return @lock.synchronize { @cancelled.include?(task_id) } unless handle
+
+      handle.cancelled = true
+      signal("INT", handle.pid)
+      Thread.new do
+        sleep @grace
+        signal("TERM", handle.pid) if @lock.synchronize { @handles[task_id].equal?(handle) }
+      end
+      true
+    end
+
+    private
+
+    def base_ref(task) = task["base_ref"].to_s.empty? ? "main" : task["base_ref"]
+
+    def prompt_for(task)
+      gh = task["gh_prompt"].to_s
+      !task["read_only"] && !gh.empty? && @gh_check.matches?(task["github_login"]) ? gh : task.fetch("prompt")
+    end
+
+    def open_terminal(task, agent, files, mcp_config, dir, restored)
+      files.claude_hooks! if agent.name == "claude_code"
+      lines = [ ("Untrusted head: this PR's own code and tests run on your machine." if task["untrusted"]),
+                ("Removed or restored from #{base_ref(task)}: #{restored.join(", ")}." if restored.any?) ].compact
+      script = @run_script.write!(task_id: task["task_id"], worktree: dir, token: task.fetch("token"), server: @config.server,
+                                  argv: agent.terminal_command(task, mcp_config:), prompt: task["prompt"],
+                                  notice: lines.empty? ? nil : lines.join("\n"))
+      @launcher.launch!(script:, cwd: dir, title: "#{task["repo"].split("/").last.downcase}-#{task["pr_number"]}")
+      progress(task["task_id"], "opened in terminal", agent.name)
+    end
+
+    # An explain task gets a verifier pass in a fresh process after a successful write (understanding spec §6.2). The
+    # server only accepts verify_explanation once this process announces itself with progress phase "verifier".
+    def run_autonomous(task, agent, mcp_config, dir)
+      id = task["task_id"]
+      @lock.synchronize { @running << id }
+      outcome = run_process(task, agent, mcp_config, dir)
+      outcome = verify_after_write(task, outcome, agent, mcp_config, dir) if task["kind"] == "explain" && outcome.status == "done"
+      finished(id, outcome.status, outcome.cost_usd, outcome.error_code, outcome.last_output)
+    ensure
+      @lock.synchronize do
+        @running.delete(id)
+        @cancelled.delete(id)
+      end
+    end
+
+    def verify_after_write(task, write, agent, mcp_config, dir)
+      id = task["task_id"]
+      prompt = begin
+        ExplainVerifier.prompt(task)
+      rescue Error => e
+        # The explanation is written; keep its cost and let the server show it as not verified.
+        say(id, "Verifier skipped: #{e.message}")
+        return Outcome.new("done", write.cost_usd, nil, "Verifier skipped: #{e.message}")
+      end
+      return Outcome.new("cancelled", write.cost_usd, "cancelled", write.last_output) if @lock.synchronize { @cancelled.include?(id) }
+
+      verify = run_process(task.merge("prompt" => prompt), agent, mcp_config, dir, step: "verifying", phase: "verifier")
+      ExplainVerifier.combine(write, verify)
+    end
+
+    def run_process(task, agent, mcp_config, dir, step: "starting", phase: nil)
+      id = task["task_id"]
+      reader, writer = IO.pipe
+      env = Runner::GIT_ENV.merge(agent.env(task.fetch("token"), id))
+      pid = Process.spawn(env, *agent.autonomous_command(task, mcp_config:),
+                          chdir: dir, in: File::NULL, out: writer, err: writer, pgroup: true)
+      writer.close
+      handle = Handle.new(pid, false)
+      @lock.synchronize { @handles[id] = handle }
+      progress(id, step, agent.name, phase)
+      result = relay(id, agent, reader)
+      _pid, status = Process.wait2(pid)
+      # Only the agent's own result text: a raw stream-json line can carry file contents (spec §5.2).
+      output = result&.text
+
+      if handle.cancelled then Outcome.new("cancelled", result&.cost_usd, "cancelled", output)
+      elsif status.success? && !result&.error then Outcome.new("done", result&.cost_usd, nil, output)
+      else Outcome.new("failed", result&.cost_usd, "agent_failed", output)
+      end
+    ensure
+      writer.close if writer && !writer.closed?
+      reader&.close
+      @lock.synchronize { @handles.delete(id) }
+    end
+
+    # Coarse progress only (spec §5.2): a step when it changes, at most every progress_interval seconds.
+    def relay(id, agent, reader)
+      result = nil
+      last_step = "starting"
+      last_sent = monotonic
+      # A log that cannot be sent never ends the run: the work matters more than its transcript.
+      log = LogBuffer.new do |entries|
+        @report.call("log", { "task_id" => id, "entries" => entries })
+      rescue StandardError => e
+        say(id, "log not sent: #{e.class}")
+      end
+      reader.each_line do |line|
+        log.add(agent.parse_log(line))
+        case (event = agent.parse_stream(line))
+        when Agents::Result then result = event
+        when Agents::Progress
+          next if event.step == last_step || monotonic - last_sent < @progress_interval
+
+          progress(id, event.step)
+          last_step = event.step
+          last_sent = monotonic
+        end
+      end
+      result
+    ensure
+      log&.flush
+    end
+
+    # Batches the run's log lines: sent when a second has passed or ten are waiting, and once more at the end.
+    class LogBuffer
+      INTERVAL = 1.0
+      BATCH = 10
+
+      def initialize(&sender)
+        @sender = sender
+        @pending = []
+        @sent_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def add(entries)
+        @pending.concat(entries.map { { "kind" => _1.kind, "text" => _1.text.to_s.scrub } })
+        flush if @pending.size >= BATCH || (@pending.any? && Process.clock_gettime(Process::CLOCK_MONOTONIC) - @sent_at >= INTERVAL)
+      end
+
+      def flush
+        @pending.each_slice(BATCH) { @sender.call(_1) }
+        @pending = []
+        @sent_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    def progress(id, step, agent = nil, phase = nil)
+      @report.call("progress", { "task_id" => id, "step" => step, "agent" => agent, "phase" => phase }.compact)
+      say(id, "progress: #{step}") unless step == "starting"
+    end
+
+    def finished(id, status, cost_usd, error_code, last_output)
+      last = last_output.to_s.lines.last.to_s.strip
+      @report.call("finished", { "task_id" => id, "status" => status, "cost_usd" => cost_usd, "error_code" => error_code,
+                                 "last_output" => last[0, MAX_OUTPUT] })
+      summary = [ (error_code && error_code != status ? "#{status} (#{error_code})" : status), (format("$%.2f", cost_usd) if cost_usd&.positive?),
+                  (last[0, PRINT_OUTPUT] unless last.empty?) ].compact.join(" · ")
+      say(id, summary)
+      nil
+    end
+
+    # Timestamped one-liners for the terminal running `gitbroker start`. Only ids, steps and the agent's own final
+    # result line: never tokens, prompts or file contents.
+    def say(id, message) = @out.puts("#{Time.now.strftime("%H:%M:%S")} Task #{id.to_s[0, 8]} #{message}")
+
+    def signal(name, pid)
+      Process.kill(name, -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end