diffbroker 0.9.0

data/lib/diffbroker/reaper.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Diffbroker
+  # Stops the processes an agent leaves behind in a task worktree. Tools such as `rubocop --server`, spring or a language
+  # server detach from the agent (their parent becomes launchd/init), so they outlive it and its process group, keep the
+  # worktree as their working directory and pile up for days. Only processes whose working directory is inside the
+  # worktree root are ever touched, and only by pid: a process is never found by name or killed by group.
+  class Reaper
+    GRACE = 3
+    POLL = 0.1
+    INIT = /\A(?:\S*\/)?(?:systemd|launchd)\b/
+
+    def initialize(root:, runner: Runner.new, platform: Diffbroker.platform, proc_root: "/proc", grace: GRACE,
+                   signal: Process.method(:kill), sleeper: ->(seconds) { sleep(seconds) })
+      @root = real(root)
+      @runner = runner
+      @scanner = ProcessScanner.new(runner:, platform:, proc_root:)
+      @grace = grace
+      @signal = signal
+      @sleeper = sleeper
+    end
+
+    # A task ended in `dir`: whatever still runs there is a stray. Returns how many processes were stopped.
+    def reap!(dir)
+      dir = real(dir)
+      return 0 unless inside?(dir, @root)
+
+      stop(processes.select { inside?(_1[:cwd], dir) }.map { _1[:pid] })
+    rescue Error, SystemCallError
+      0
+    end
+
+    # Worktrees nobody works in (no agent process inside): their orphaned helpers are strays. A worktree with a live
+    # agent (a terminal run the user is still in) is left alone. Call it only when no task is running here.
+    def sweep!
+      pids = processes.group_by { worktree_of(_1[:cwd]) }.flat_map do |dir, inside|
+        next [] if dir.nil? || inside.any? { ProcessScanner.agent_for(_1[:args]) }
+
+        inside.select { _1[:orphan] }.map { _1[:pid] }
+      end
+      stop(pids)
+    rescue Error, SystemCallError
+      0
+    end
+
+    private
+
+    # [{ pid:, args:, cwd:, orphan: }] for every process with a working directory under the worktree root.
+    def processes
+      table = @runner.run!("ps", "-Ao", "pid=,ppid=,args=").lines.filter_map do |line|
+        pid, ppid, args = line.strip.split(" ", 3)
+        next unless pid.to_s.match?(/\A\d+\z/) && ppid.to_s.match?(/\A\d+\z/) && pid.to_i > 1 && pid.to_i != Process.pid
+
+        { pid: pid.to_i, ppid: ppid.to_i, args: args.to_s }
+      end
+      args_of = table.to_h { [ _1[:pid], _1[:args] ] }
+      cwds = @scanner.working_dirs(table.map { _1[:pid] })
+      table.filter_map do |process|
+        cwd = cwds[process[:pid]]
+        next unless cwd && inside?(cwd, @root)
+
+        process.merge(cwd:, orphan: process[:ppid] == 1 || args_of[process[:ppid]].to_s.match?(INIT))
+      end
+    end
+
+    # <root>/<owner>-<repo>/pr-<n>-<kind>, whatever depth the process is working at.
+    def worktree_of(cwd)
+      return unless cwd.start_with?("#{@root}/")
+
+      owner_repo, pr = cwd.delete_prefix("#{@root}/").split("/", 3).first(2)
+      File.join(@root, owner_repo, pr) if pr
+    end
+
+    def stop(pids)
+      pids = pids.uniq.select { deliver("TERM", _1) }
+      return 0 if pids.empty?
+
+      (@grace / POLL).ceil.times do
+        break if pids.none? { alive?(_1) }
+
+        @sleeper.call(POLL)
+      end
+      pids.each { deliver("KILL", _1) if alive?(_1) }
+      pids.size
+    end
+
+    def deliver(name, pid)
+      @signal.call(name, pid)
+      true
+    rescue SystemCallError
+      false
+    end
+
+    def alive?(pid)
+      @signal.call(0, pid)
+      true
+    rescue Errno::EPERM
+      true
+    rescue SystemCallError
+      false
+    end
+
+    def inside?(path, dir) = path == dir || path.start_with?("#{dir}/")
+
+    def real(path)
+      File.realpath(path)
+    rescue SystemCallError
+      File.expand_path(path)
+    end
+  end
+end

data/lib/diffbroker/repo_scanner.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Diffbroker
+  # Finds GitHub checkouts under the configured roots and reports them (DeviceRepository), so a card only offers
+  # agents where a checkout exists. Reads .git/config as a file; never runs git in scanned directories.
+  class RepoScanner
+    GITHUB_URL = %r{\A(?:https://(?:[^@/\s]+@)?github\.com/|git@github\.com:|ssh://git@github\.com/)([\w.-]+)/([\w.-]+?)(?:\.git)?/?\z}
+    SKIP = %w[node_modules vendor tmp log].freeze
+
+    def self.full_name_from(url)
+      match = GITHUB_URL.match(url.to_s.strip)
+      match && "#{match[1]}/#{match[2]}".downcase
+    end
+
+    # `hints` are directories known to hold work (the agents' project lists): each counts as a checkout when it, or a
+    # parent up to HINT_LEVELS above it, is one, however deep it is. Its parent folder is scanned too (HINT_PARENT_DEPTH
+    # levels), because the user keeps the other repositories next to it, where no agent has run. A parent that is the home
+    # folder (or above it) is never scanned: that is the whole account, not a place for code.
+    HINT_LEVELS = 4
+    HINT_PARENT_DEPTH = 2
+
+    # `exclude` (the task worktrees) is skipped everywhere. `ignored` (folders the user removed) is skipped by everything
+    # found by itself; `explicit_roots` (folders the user added) are scanned even inside an ignored folder.
+    def initialize(roots:, depth: 3, exclude: [], hints: [], home: Dir.home, explicit_roots: [], ignored: [])
+      @roots = roots
+      @explicit_roots = explicit_roots
+      @ignored = ignored.map { File.expand_path(_1) }
+      @hints = hints
+      @home = File.expand_path(home)
+      @depth = depth
+      @exclude = exclude.map { File.expand_path(_1) }
+      @skip = @exclude + @ignored
+    end
+
+    def scan
+      found = {}
+      @roots.each { |root| walk(File.expand_path(root), 0, found, @depth, @skip) if File.directory?(root) }
+      @explicit_roots.each { |root| walk(File.expand_path(root), 0, found, @depth, @exclude) if File.directory?(root) }
+      parents = @hints.filter_map { |hint| add_hint(File.expand_path(hint), found) }.map { File.dirname(_1) }.uniq
+      parents.each { |parent| walk(parent, 0, found, HINT_PARENT_DEPTH, @skip) if scannable_parent?(parent) }
+      found.sort.map { |full_name, path| { "full_name" => full_name, "path" => path } }
+    end
+
+    private
+
+    # Records the checkout a hint is in and returns its directory (nil when it is not in one).
+    def add_hint(dir, found)
+      HINT_LEVELS.times do
+        return nil if @skip.any? { |skipped| dir == skipped || dir.start_with?("#{skipped}/") }
+        return nil unless File.directory?(dir)
+
+        if File.exist?(File.join(dir, ".git"))
+          remote_names(dir).each { |name| found[name] = dir if found[name].nil? || dir.length < found[name].length }
+          return dir
+        end
+        dir = File.dirname(dir)
+      end
+      nil
+    end
+
+    def scannable_parent?(dir)
+      return true if dir.start_with?("#{@home}/")
+
+      !(dir == @home || dir == "/" || @home.start_with?("#{dir}/"))
+    end
+
+    def walk(dir, level, found, limit, skip)
+      return if skip.any? { |skipped| dir == skipped || dir.start_with?("#{skipped}/") }
+
+      if File.exist?(File.join(dir, ".git"))
+        remote_names(dir).each { |name| found[name] = dir if found[name].nil? || dir.length < found[name].length }
+        return
+      end
+      return if level >= limit
+
+      Dir.children(dir).sort.each do |child|
+        next if child.start_with?(".") || SKIP.include?(child)
+
+        path = File.join(dir, child)
+        walk(path, level + 1, found, limit, skip) if File.directory?(path) && !File.symlink?(path)
+      end
+    rescue Errno::EACCES, Errno::ENOENT, Errno::ENOTDIR
+      nil
+    end
+
+    def remote_names(dir) = GitContext.remote_urls(dir).filter_map { |_name, url| self.class.full_name_from(url) }.uniq
+  end
+end

data/lib/diffbroker/run_script.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "shellwords"
+require "rbconfig"
+
+module Diffbroker
+  # 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, `diffbroker task-ended` tells Diff Broker.
+  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/
+
+    # RubyGems' stable wrapper (ServiceInstaller.launcher): a terminal task may outlive an upgrade's `gem cleanup`.
+    def initialize(state_dir:, ruby: RbConfig.ruby, exe: ServiceInstaller.launcher)
+      @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
+
+    # publish: a command (argv) to run in this script, outside the agent, once the agent exited successfully: the push of
+    # an update_branch rebase (BranchPublisher), which the agent's own hooks would refuse.
+    def write!(task_id:, worktree:, token:, server:, argv:, prompt:, notice: nil, publish: 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:, publish:), perm: 0o700)
+      File.chmod(0o700, path)
+      path
+    end
+
+    private
+
+    def render(task_id:, worktree:, token:, server:, argv:, prompt:, notice:, publish:)
+      inner = %(#{Shellwords.join(argv)} "$DIFFBROKER_PROMPT")
+      publish_step = publish ? "if [ \"$status\" = \"0\" ]; then #{Shellwords.join(publish)}; fi" : nil
+      <<~SH
+        #!/bin/bash
+        # Written by the Diff Broker companion for agent task #{task_id}. Deletes itself on start.
+        rm -f -- "$0"
+        #{"printf '%s\\n' #{Shellwords.escape(notice)}" if notice}
+        export DIFFBROKER_TASK_TOKEN=#{Shellwords.escape(token)}
+        export DIFFBROKER_TASK_ID=#{Shellwords.escape(task_id)}
+        export DIFFBROKER_SERVER=#{Shellwords.escape(server)}
+        export DIFFBROKER_PROMPT=#{Shellwords.escape(prompt)}
+        cd #{Shellwords.escape(worktree)} || exit 1
+        "${SHELL:-/bin/bash}" -lic #{Shellwords.escape(inner)}
+        status=$?
+        #{publish_step}
+        #{Shellwords.escape(@ruby)} #{Shellwords.escape(@exe)} task-ended "$status"
+      SH
+    end
+  end
+end

data/lib/diffbroker/runner.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Diffbroker
+  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/diffbroker/service_installer.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+
+module Diffbroker
+  # Runs `diffbroker start` in the background as the logged-in user (launchd on macOS, systemd --user on Linux).
+  class ServiceInstaller
+    LABEL = "broker.diff.companion"
+    EXE = File.join(Diffbroker::ROOT, "exe", "diffbroker")
+
+    # What the service and the "Start companion" app run. RubyGems' own wrapper activates the newest installed diffbroker
+    # on every start, so a restart loads an upgraded gem and old versions can be removed. The gem's own exe is the
+    # fallback (and what a test passes), pinned to the version that ran `install-service`.
+    def self.launcher(bindir: launcher_bindirs)
+      Array(bindir).map { File.join(_1, "diffbroker") }.find { File.executable?(_1) } || EXE
+    end
+
+    # Where RubyGems puts the wrapper: the default bindir, the bindir of the install location this gem came from, and
+    # the per-user one (`gem install --user-install`).
+    def self.launcher_bindirs
+      spec = Gem.loaded_specs["diffbroker"]
+      [ Gem.bindir, (Gem.bindir(spec.base_dir) if spec), File.join(Gem.user_dir, "bin") ].compact.uniq
+    end
+
+    # True when the launcher is this version's own exe, which `gem cleanup` deletes once a newer version is installed.
+    def self.pinned?(launcher = self.launcher) = launcher == EXE
+
+    def initialize(platform: Diffbroker.platform, home: Dir.home, ruby: RbConfig.ruby, exe: ServiceInstaller.launcher, 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", "diffbroker.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", "diffbroker.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", "diffbroker.service")
+      end
+    end
+
+    # Stops and removes the background service. False when none was installed. The file goes first on macOS: booting
+    # out the job ends the daemon when it is the one uninstalling. systemd needs the unit file to disable it, so a
+    # daemon uninstalling itself may leave a disabled, stopped unit behind.
+    def uninstall!
+      return false unless installed?
+
+      if @platform == "macos"
+        File.delete(launchd_path)
+        @runner.success?("launchctl", "bootout", target)
+      else
+        @runner.success?("systemctl", "--user", "disable", "--now", "diffbroker.service")
+        File.delete(systemd_path)
+        @runner.success?("systemctl", "--user", "daemon-reload")
+      end
+      true
+    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", "diffbroker.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=Diff Broker 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", "diffbroker.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", "diffbroker.service")
+      path
+    end
+  end
+end

data/lib/diffbroker/skill_installer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Diffbroker
+  # 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(Diffbroker::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/diffbroker/task_files.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Diffbroker
+  # Per-task files. They reference the task token as ${DIFFBROKER_TASK_TOKEN}; the value only exists in the agent
+  # process environment. Spec §4.2 step 4: the Diff Broker MCP config lives outside the repository.
+  class TaskFiles
+    TOKEN_ENV = "DIFFBROKER_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" => { "diffbroker" => 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}; Diff Broker 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; Diff Broker 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