gitbroker 0.3.0

data/lib/gitbroker/cli.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "optparse"
+require "rbconfig"
+require "socket"
+
+module Gitbroker
+  class CLI
+    HELP = <<~TEXT
+      Usage: gitbroker <command> [options]
+
+      Commands:
+        login [--server URL] [--name NAME]  Pair this machine with GitBroker (you type the code at /devices)
+        start                               Stay connected; run your agent when you ask from a PR card
+        launch                              Start the companion in the background if it is not running
+        stop                                Stop the companion (and its background service, so it stays stopped)
+        restart                             Restart the companion, e.g. after `gem update gitbroker`
+        install-service                     Run `gitbroker start` in the background (launchd / systemd --user), and let
+                                            the website's "Start companion" button wake it (gitbroker:// handler)
+        install-skill                       Install the gitbroker skills into ~/.claude/skills
+        status                              Show pairing, configuration and the repositories found
+        clean                               Remove finished agent worktrees (keeps ones with uncommitted work)
+        install-hooks [--yes]               Show your own Claude Code sessions on your cards (asks first)
+        uninstall-hooks                     Remove those hooks
+        help                                Show this help
+
+      Config: ~/.config/gitbroker/config.yml (server, roots, scan_depth, terminal, worktree_root, agent,
+              claude_args, codex_args). Your agent runs as you, with your own login and credentials.
+      Agent activity is visible only to you; only status is sent, never prompts, file contents or tool input.
+    TEXT
+
+    def initialize(argv, out: $stdout, err: $stderr, env: ENV, home: Dir.home, input: $stdin)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @env = env
+      @home = home
+      @input = input
+    end
+
+    def run
+      command = @argv.shift || "help"
+      return task_ended if command == "task-ended"
+      return hook if command == "hook"
+
+      case command
+      when "login" then login
+      when "start" then start
+      when "launch" then launch
+      when "stop" then stop
+      when "restart" then restart
+      when "install-service" then install_service
+      when "install-skill" then install_skill
+      when "status" then status
+      when "clean" then clean
+      when "install-hooks" then install_hooks
+      when "uninstall-hooks" then uninstall_hooks
+      when "help", "-h", "--help" then @out.puts(HELP)
+      else
+        @err.puts "Unknown command: #{command}"
+        @err.puts HELP
+        return 1
+      end
+      0
+    rescue Error, OptionParser::ParseError => e
+      @err.puts "gitbroker: #{e.message}"
+      1
+    end
+
+    private
+
+    def config = @config ||= Config.load(dir: Config.default_dir(@env), env: @env)
+
+    def login
+      options = {}
+      OptionParser.new do |parser|
+        parser.on("--server URL") { options[:server] = _1 }
+        parser.on("--name NAME") { options[:name] = _1 }
+      end.parse!(@argv)
+      @config = config.save!("server" => options[:server]) if options[:server]
+      Login.new(config:, out: @out, name: options[:name] || Socket.gethostname).run
+    end
+
+    def start
+      raise Error, "This machine is not paired. Run `gitbroker login` first." unless config.paired?
+
+      @out.puts "GitBroker companion #{VERSION} → #{config.server} (agent: #{config.agent}, terminal: #{config.terminal})"
+      Daemon.build(config, out: @out).run
+    end
+
+    def install_service
+      raise Error, "This machine is not paired. Run `gitbroker login` first." unless config.paired?
+
+      path = ServiceInstaller.new(home: @home, env: @env).install!
+      @out.puts "Installed and started #{path}. Run this again after upgrading the gem."
+      handler = UrlHandlerInstaller.new(home: @home).install!
+      @out.puts "Registered #{handler} so the website's \"Start companion\" button can wake it."
+    end
+
+    # The target of the website's gitbroker://start link and of `gitbroker launch` by hand: start the background
+    # service, or the daemon itself when none is installed. Safe to run when it is already running.
+    def launch
+      raise Error, "This machine is not paired. Run `gitbroker login` first." unless config.paired?
+      lifecycle.launch
+    end
+
+    def lifecycle = @lifecycle ||= Lifecycle.new(dir: config.dir, home: @home, service: ServiceInstaller.new(home: @home, env: @env))
+
+    # Works on this machine only. With a background service installed it is stopped through launchd / systemd, so it
+    # stays stopped until `gitbroker launch` (or the website's "Start companion" button).
+    def stop
+      @out.puts(lifecycle.stop ? "Stopped the companion." : "The companion is not running.")
+    end
+
+    def restart
+      raise Error, "This machine is not paired. Run `gitbroker login` first." unless config.paired?
+
+      lifecycle.restart
+      @out.puts "Restarting the companion."
+    end
+
+    def install_skill
+      SkillInstaller.new(home: @home, env: @env).install!.each { @out.puts "Installed the #{File.basename(_1)} skill to #{_1}." }
+    end
+
+    def status
+      @out.puts "GitBroker companion #{VERSION}"
+      @out.puts "Server:     #{config.server}"
+      @out.puts "Paired:     #{config.paired? ? "yes (device #{config.device_id})" : "no (run `gitbroker login`)"}"
+      @out.puts "Agent:      #{config.agent}"
+      @out.puts "Terminal:   #{config.terminal}"
+      @out.puts "Hooks:      #{hooks_installer.installed? ? "installed" : "not installed (gitbroker install-hooks)"}"
+      @out.puts "Roots:      #{config.roots.join(", ")}"
+      @out.puts "Worktrees:  #{config.worktree_root}"
+      @out.puts "Task worktrees: #{Worktree.new(root: config.worktree_root).list.size} (running or kept; `gitbroker clean` removes finished ones)"
+      repositories = RepoScanner.new(roots: config.roots, depth: config.scan_depth, exclude: [ config.worktree_root ]).scan
+      @out.puts "Repositories found: #{repositories.size}"
+      repositories.each { @out.puts "  #{_1["full_name"]}  #{_1["path"]}" }
+    end
+
+    # `git worktree remove` without --force refuses a worktree with modified or untracked files, so work is never lost.
+    def clean
+      worktree = Worktree.new(root: config.worktree_root)
+      worktree.list.each do |dir|
+        git_dir = GitContext.git_dir(dir)
+        repo_path = git_dir && File.dirname(GitContext.common_dir(git_dir))
+        removed = repo_path && File.directory?(repo_path) && worktree.remove!(dir, repo_path:)
+        @out.puts(removed ? "Removed #{dir}" : "Kept #{dir} (uncommitted work)")
+      end
+    end
+
+    def hooks_installer = HooksInstaller.default(env: @env, home: @home)
+
+    # Called by Claude Code on every hook event: silent, always exit 0.
+    def hook
+      Hook.new(event: @argv.shift, input: @input, socket_path: File.join(Config.default_dir(@env), "daemon.sock"), env: @env).run
+      0
+    rescue StandardError
+      0
+    end
+
+    def install_hooks
+      yes = @argv.delete("--yes")
+      installer = hooks_installer
+      @out.puts "This adds Claude Code command hooks (#{HooksInstaller::EVENTS.join(", ")}) to #{installer.settings_path}."
+      @out.puts "Each runs `gitbroker hook <event>`, which tells your running companion the session id, repository, branch " \
+                "and head SHA. It never sends prompts, file contents or tool input, and only you see the result."
+      unless yes
+        @out.print "Add the hooks? [y/N] "
+        return @out.puts("Nothing changed.") unless %w[y yes].include?(@input.gets.to_s.strip.downcase)
+      end
+      backup = installer.install!
+      @out.puts "Hooks installed#{" (previous settings saved to #{backup})" if backup}. New Claude Code sessions pick them up."
+    end
+
+    def uninstall_hooks
+      if hooks_installer.installed? || File.exist?(hooks_installer.settings_path)
+        backup = hooks_installer.uninstall!
+        @out.puts(backup ? "Hooks removed (previous settings saved to #{backup})." : "No GitBroker hooks found; nothing changed.")
+      else
+        @out.puts "No Claude Code settings file; nothing to remove."
+      end
+    end
+
+    # Called by the terminal run script after the agent exits: silent, always exit 0.
+    def task_ended
+      id = @env["GITBROKER_TASK_ID"].to_s
+      token = @env["GITBROKER_TASK_TOKEN"].to_s
+      return 0 if id.empty? || token.empty?
+
+      Api.new(server: @env["GITBROKER_SERVER"] || config.server, token:)
+         .post("/agent_tasks/#{id}/events", { hook_event_name: "TaskEnded", exit_status: @argv.first.to_s })
+      0
+    rescue StandardError # never break the user's terminal session over a status report
+      0
+    end
+  end
+end

data/lib/gitbroker/config.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Gitbroker
+  # ~/.config/gitbroker/config.yml (settings) and credentials.yml (0600, device token). Spec §4.1: roots, terminal,
+  # worktree location, preferred agent, and the agents' command-line args for autonomous runs (spec §4.2 step 5).
+  class Config
+    TERMINALS = %w[terminal iterm2 ghostty warp tmux].freeze
+    AGENTS = %w[claude codex].freeze
+    DEFAULT_SERVER = "https://git.broker"
+    DEFAULT_CLAUDE_ARGS = %w[--permission-mode auto --permission-prompts none].freeze
+    DEFAULT_CODEX_ARGS = %w[--sandbox workspace-write -c sandbox_workspace_write.network_access=true].freeze
+    # GitBroker sets these itself for every run; user args may not override them.
+    RESERVED_ARGS = %w[-p --print --output-format --mcp-config --strict-mcp-config --plugin-dir --json].freeze
+
+    attr_reader :dir, :data
+
+    def self.default_dir(env = ENV)
+      env["GITBROKER_CONFIG_DIR"] || File.join(env["XDG_CONFIG_HOME"] || File.join(Dir.home, ".config"), "gitbroker")
+    end
+
+    def self.load(dir: default_dir, env: ENV, platform: Gitbroker.platform)
+      path = File.join(dir, "config.yml")
+      data = File.exist?(path) ? YAML.safe_load_file(path) || {} : {}
+      new(dir:, data:, env:, platform:)
+    end
+
+    def initialize(dir:, data: {}, env: ENV, platform: Gitbroker.platform)
+      @dir = dir
+      @data = data.to_h.transform_keys(&:to_s)
+      @env = env
+      @platform = platform
+      validate!
+    end
+
+    def server = (@env["GITBROKER_SERVER"] || data["server"] || DEFAULT_SERVER).to_s.chomp("/")
+    def cable_url = "#{server.sub(/\Ahttp/, "ws")}/cable"
+    def roots = Array(data["roots"] || [ "~/Code" ]).map { File.expand_path(_1) }
+    def scan_depth = Integer(data["scan_depth"] || 3)
+    def terminal = (data["terminal"] || (@platform == "macos" ? "terminal" : "tmux")).to_s
+    def worktree_root = File.expand_path(data["worktree_root"] || "~/.local/share/gitbroker/worktrees")
+    def state_dir = File.expand_path(data["state_dir"] || "~/.local/state/gitbroker")
+    def agent = (data["agent"] || "claude").to_s
+    def claude_command = (data["claude_command"] || "claude").to_s
+    def codex_command = (data["codex_command"] || "codex").to_s
+    def claude_args = data.key?("claude_args") ? data["claude_args"] : DEFAULT_CLAUDE_ARGS
+    def codex_args = data.key?("codex_args") ? data["codex_args"] : DEFAULT_CODEX_ARGS
+
+    def credentials_path = File.join(dir, "credentials.yml")
+    def device_token = credentials["device_token"]
+    def device_id = credentials["device_id"]
+    def paired? = !device_token.to_s.empty?
+
+    def save!(updates)
+      merged = data.merge(updates.transform_keys(&:to_s)).compact
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      File.write(File.join(dir, "config.yml"), merged.to_yaml)
+      self.class.new(dir:, data: merged, env: @env, platform: @platform)
+    end
+
+    def save_credentials!(device_token:, device_id:)
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      File.write(credentials_path, { "device_token" => device_token, "device_id" => device_id, "server" => server }.to_yaml, perm: 0o600)
+      File.chmod(0o600, credentials_path)
+      @credentials = nil
+    end
+
+    private
+
+    def credentials
+      @credentials ||= File.exist?(credentials_path) ? YAML.safe_load_file(credentials_path) || {} : {}
+    end
+
+    def validate!
+      raise Error, "Unknown terminal #{terminal.inspect}. Use one of: #{TERMINALS.join(", ")}" unless TERMINALS.include?(terminal)
+      raise Error, "Unknown agent #{agent.inspect}. Use one of: #{AGENTS.join(", ")}" unless AGENTS.include?(agent)
+
+      { "claude_args" => claude_args, "codex_args" => codex_args }.each do |key, args|
+        raise Error, "#{key} must be a list of strings" unless args.is_a?(Array) && args.all?(String)
+
+        reserved = args.map { _1.split("=").first } & RESERVED_ARGS
+        raise Error, "#{key} may not set #{reserved.join(", ")}; GitBroker sets those itself" if reserved.any?
+      end
+    end
+  end
+end

data/lib/gitbroker/daemon.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "socket"
+require "set"
+
+module Gitbroker
+  # `gitbroker start`: keep the device connected, report checkouts, claim and run tasks, and relay the status of
+  # agents the user started themselves (relay: Task 31, process scanner: Task 32).
+  class Daemon
+    RESCAN_EVERY = 300
+    MAX_BACKOFF = 60
+    BATCH = 50
+    # Spec §5.2 / main §18.4: nothing else about an observed agent ever leaves the machine.
+    OBSERVATION_FIELDS = %w[event agent external_session_id repository branch head_sha occurred_at].freeze
+
+    def self.build(config, out: $stdout, relay: LocalRelay.new(path: File.join(config.dir, "daemon.sock")),
+                   process_scanner: build_process_scanner(config))
+      raise Error, "This machine is not paired. Run `gitbroker login` first." unless config.paired?
+
+      new(scanner: RepoScanner.new(roots: config.roots, depth: config.scan_depth, exclude: [ config.worktree_root ]),
+          client_factory: -> { CableClient.new(url: config.cable_url, token: config.device_token, origin: config.server) },
+          task_runner_factory: ->(report) { TaskRunner.new(config:, report:, out:) }, out:, relay:, process_scanner:,
+          lifecycle: Lifecycle.new(dir: config.dir))
+    end
+
+    # Claude sessions with hooks installed report real working/waiting status, so the scanner only looks for `claude`
+    # without hooks (checked on every scan, so installing hooks takes effect without a restart). GitBroker's own
+    # worktrees are skipped: those agents are tasks, reported by the task.
+    def self.build_process_scanner(config)
+      hooks = HooksInstaller.default
+      skip_claude = lambda do
+        hooks.installed?
+      rescue Error
+        false
+      end
+      ProcessScanner.new(skip_claude:, exclude: [ config.worktree_root ])
+    end
+
+    def initialize(scanner:, client_factory:, task_runner_factory:, out: $stdout, sleeper: ->(seconds) { sleep(seconds) },
+                   clock: -> { Time.now }, spawner: ->(&block) { Thread.new(&block) }, relay: nil, process_scanner: nil, lifecycle: nil)
+      @scanner = scanner
+      @client_factory = client_factory
+      @task_runner = task_runner_factory.call(method(:report))
+      @out = out
+      @sleeper = sleeper
+      @clock = clock
+      @spawner = spawner
+      @relay = relay
+      @process_scanner = process_scanner
+      @lifecycle = lifecycle
+      @repositories = []
+      @running = Set.new
+      @running_lock = Mutex.new
+    end
+
+    def run
+      @backoff = 1
+      @relay&.start
+      @lifecycle&.write_pid
+      until @stopping
+        begin
+          @client = @client_factory.call
+          wire(@client)
+          @client.run
+        rescue CableClient::Unauthorized
+          raise Error, "GitBroker rejected this device (revoked?). Run `gitbroker login` to pair again."
+        rescue Error, SystemCallError, IOError, SocketError, OpenSSL::SSL::SSLError => e
+          @out.puts "Connection problem: #{e.message}"
+        end
+        break if @stopping
+
+        @sleeper.call(@backoff)
+        @backoff = [ @backoff * 2, MAX_BACKOFF ].min
+      end
+    ensure
+      @relay&.stop
+      @lifecycle&.clear_pid
+      # Only now, with the connection closed, so two daemons never share the device.
+      @lifecycle.spawn_daemon if @respawn && @lifecycle
+    end
+
+    def stop
+      @stopping = true
+      @client&.stop
+    end
+
+    # Task runners report progress and results through whatever connection is live. A report sent while the device
+    # is reconnecting is lost; the server's sweep settles the task.
+    def report(action, data) = @client&.perform(action, data)
+
+    private
+
+    def wire(client)
+      client.on_subscribed do
+        @backoff = 1
+        rescan(client)
+        @out.puts "Connected. #{@repositories.size} repositories reported."
+      end
+      client.on_tick do
+        client.perform("heartbeat", "version" => VERSION)
+        rescan(client) if @scanned_at.nil? || @clock.call - @scanned_at >= RESCAN_EVERY
+        observe(client, @process_scanner.scan) if @process_scanner
+      end
+      client.on_poll { observe(client, @relay.drain) if @relay }
+      client.on_message { |message| handle(client, message) }
+    end
+
+    # The server replaces its list with each report, so every report carries the full list.
+    def rescan(client)
+      @repositories = @scanner.scan
+      @scanned_at = @clock.call
+      client.perform("repositories", "repositories" => @repositories)
+    end
+
+    def observe(client, events)
+      clean = Array(events).filter_map { _1.is_a?(Hash) ? _1.slice(*OBSERVATION_FIELDS) : nil }
+      clean.each_slice(BATCH) { client.perform("observe", "events" => _1) }
+    end
+
+    # The website's Restart / Stop buttons (Device#control!). Nothing else about the message is trusted or used.
+    def control(action)
+      return unless @lifecycle
+
+      case action
+      when "stop"
+        @out.puts "Stopping (asked from GitBroker)."
+        @lifecycle.stop_service
+        stop
+      when "restart"
+        @out.puts "Restarting (asked from GitBroker)."
+        # With a service the manager restarts us (it may kill us mid-call); otherwise respawn once the run loop has ended.
+        return if @lifecycle.restart_service
+
+        @respawn = true
+        stop
+      end
+    end
+
+    def handle(client, message)
+      return control(message["action"]) if message["type"] == "control"
+
+      id = message["task_id"]
+      return unless id.is_a?(String)
+
+      case message["type"]
+      when "task_available" then client.perform("claim", "task_id" => id)
+      when "cancel" then @task_runner.cancel(id)
+      when "task" then start_task(id, message)
+      end
+    end
+
+    def start_task(id, message)
+      return unless @running_lock.synchronize { @running.add?(id) }
+
+      repositories = @repositories
+      @spawner.call do
+        @task_runner.run(message, repositories:)
+      rescue StandardError => e
+        @out.puts "Task #{id} crashed: #{e.class}: #{e.message}"
+      ensure
+        @running_lock.synchronize { @running.delete(id) }
+      end
+    end
+  end
+end

data/lib/gitbroker/explain_verifier.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Gitbroker
+  # Understanding spec §6.2: after an explain run finishes writing, a second agent run in a fresh context checks every
+  # walkthrough step, summary, intuition claim and quiz answer against the code, and sends verify_explanation.
+  module ExplainVerifier
+    BRIEF = /^Run brief: .+$/
+
+    def self.prompt(task)
+      brief = task.fetch("prompt")[BRIEF] or raise Error, "The explain prompt has no run brief."
+      <<~PROMPT
+        Use the gitbroker-explain skill in verify mode. Someone else wrote this explanation; check it against the code with fresh eyes.
+        #{brief}
+        Read it with show_explanation (pass pull_request and explanation_id from the run brief), read the code each block refers to in
+        this worktree, and send every verdict in one verify_explanation call. Change nothing else.
+      PROMPT
+    end
+
+    # One `finished` for the task: the costs add up. A verifier that failed makes the task failed (the server then keeps the
+    # explanation "not verified"); one that was cancelled is cancelled.
+    def self.combine(write, verify)
+      costs = [ write.cost_usd, verify.cost_usd ].compact
+      status, code = case verify.status
+      when "done" then [ "done", nil ]
+      when "cancelled" then [ "cancelled", "cancelled" ]
+      else [ "failed", verify.error_code || "agent_failed" ]
+      end
+      TaskRunner::Outcome.new(status, costs.empty? ? nil : costs.sum.round(6), code, verify.last_output || write.last_output)
+    end
+  end
+end

data/lib/gitbroker/gh_check.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Gitbroker
+  # Spec §3.4: agents write to GitHub with the user's own gh only when gh's active github.com account is the
+  # GitBroker connection's login; otherwise through GitBroker's MCP write tools. Both write as the user.
+  class GhCheck
+    LOGIN = /Logged in to github\.com (?:account |as )([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))/
+
+    def initialize(runner: Runner.new)
+      @runner = runner
+    end
+
+    def matches?(login)
+      return false if login.to_s.empty?
+
+      output = @runner.capture("gh", "auth", "status", "--active", "--hostname", "github.com")
+      output = @runner.capture("gh", "auth", "status", "--hostname", "github.com") if output.include?("unknown flag")
+      logins = output.scan(LOGIN).flatten.uniq
+      logins.one? && logins.first.casecmp?(login.to_s)
+    end
+  end
+end

data/lib/gitbroker/git_context.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Gitbroker
+  # (owner/repo, branch, head SHA) for a working directory, read from .git files. The companion never runs git in
+  # directories it merely scans or that a hook/process reports, so a repository's config can never execute anything.
+  module GitContext
+    SHA = /\A[0-9a-f]{40}(?:[0-9a-f]{24})?\z/
+    MAX_DEPTH = 64
+
+    module_function
+
+    def resolve(cwd)
+      return nil if cwd.to_s.empty? || !File.directory?(cwd)
+
+      root = enclosing_checkout(File.expand_path(cwd)) or return nil
+      git_dir = git_dir(root) or return nil
+      repository = repository_from(remote_urls_in(common_dir(git_dir))) or return nil
+      branch, head_sha = head(git_dir)
+      { "repository" => repository, "branch" => branch, "head_sha" => head_sha }
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    def git_dir(dir)
+      dot_git = File.join(dir, ".git")
+      return dot_git if File.directory?(dot_git)
+      return nil unless File.file?(dot_git)
+
+      target = File.read(dot_git, 4_096)[/\Agitdir: (.+)$/, 1]
+      target && File.expand_path(target.strip, dir)
+    end
+
+    def common_dir(git_dir)
+      file = File.join(git_dir, "commondir")
+      File.file?(file) ? File.expand_path(File.read(file, 4_096).strip, git_dir) : git_dir
+    end
+
+    def remote_urls(dir)
+      git_dir = git_dir(dir)
+      git_dir ? remote_urls_in(common_dir(git_dir)) : []
+    rescue SystemCallError, IOError
+      []
+    end
+
+    # Minimal git-config reader: [remote "name"] sections, url = … keys.
+    def remote_urls_in(common)
+      path = File.join(common, "config")
+      return [] unless File.file?(path)
+
+      remote = nil
+      File.foreach(path).filter_map do |line|
+        line = line.strip
+        if (section = line.match(/\A\[\s*remote\s+"([^"]+)"\s*\]\z/))
+          remote = section[1]
+          nil
+        elsif line.start_with?("[")
+          remote = nil
+        elsif remote && (url = line.match(/\Aurl\s*=\s*(.+)\z/))
+          [ remote, url[1].strip.delete_prefix('"').delete_suffix('"') ]
+        end
+      end
+    end
+
+    def repository_from(remotes)
+      remotes.sort_by { |name, _url| name == "origin" ? 0 : 1 }.lazy.filter_map { |_name, url| RepoScanner.full_name_from(url) }.first
+    end
+
+    def head(git_dir)
+      head = File.read(File.join(git_dir, "HEAD"), 1_024).strip
+      return [ nil, (head if head.match?(SHA)) ] unless head.start_with?("ref: ")
+
+      ref = head.delete_prefix("ref: ")
+      [ ref.start_with?("refs/heads/") ? ref.delete_prefix("refs/heads/") : nil, read_ref(git_dir, ref) ]
+    end
+
+    def read_ref(git_dir, ref)
+      return nil if ref.include?("..")
+
+      [ git_dir, common_dir(git_dir) ].uniq.each do |dir|
+        loose = File.join(dir, ref)
+        return File.read(loose, 128).strip if File.file?(loose)
+      end
+      packed = File.join(common_dir(git_dir), "packed-refs")
+      return nil unless File.file?(packed)
+
+      File.foreach(packed) do |line|
+        sha, name = line.strip.split(" ", 2)
+        return sha if name == ref && sha.match?(SHA)
+      end
+      nil
+    end
+
+    def enclosing_checkout(dir)
+      MAX_DEPTH.times do
+        return dir if File.exist?(File.join(dir, ".git"))
+
+        parent = File.dirname(dir)
+        return nil if parent == dir
+
+        dir = parent
+      end
+      nil
+    end
+  end
+end

data/lib/gitbroker/hook.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Gitbroker
+  # `gitbroker hook <Event>`, run by Claude Code's user-level command hooks. It must never slow down or break Claude
+  # Code: it prints nothing, never raises, runs no subprocess, and skips everything when the daemon is not running or
+  # the session is a GitBroker task (reported through the task itself). It forwards status only; the prompt is never
+  # read.
+  class Hook
+    EVENTS = { "SessionStart" => "start", "UserPromptSubmit" => "prompt", "Stop" => "stop", "SessionEnd" => "end" }.freeze
+    TIMEOUT = 0.2
+    MAX_INPUT = 1_000_000
+
+    def initialize(event:, input:, socket_path:, env: ENV, clock: -> { Time.now })
+      @event = event.to_s
+      @input = input
+      @socket_path = socket_path
+      @env = env
+      @clock = clock
+    end
+
+    def run
+      observation = build
+      LocalRelay.send_line(@socket_path, JSON.generate(observation), timeout: TIMEOUT) if observation
+      nil
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def build
+      kind = EVENTS[@event]
+      return nil unless kind && File.socket?(@socket_path)
+      return nil unless @env["GITBROKER_TASK_ID"].to_s.empty?
+
+      data = JSON.parse(@input.read(MAX_INPUT).to_s)
+      return nil unless data.is_a?(Hash)
+
+      session_id = data["session_id"].to_s
+      return nil if session_id.empty?
+
+      context = GitContext.resolve(data["cwd"].to_s) || {} # files only; never runs git in the hook's cwd
+      { "event" => kind, "agent" => "claude_code", "external_session_id" => session_id,
+        "occurred_at" => @clock.call.utc.iso8601 }.merge(context)
+    end
+  end
+end