diffbroker 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3e54b099af52044a49465285a6e1c6433be4fbac0c9e2b76dade0717b42bb5cb
+  data.tar.gz: c27ba555b4cf84832fac018fabb0a32acbc13a2778a98f526db61304abd8f11f
+SHA512:
+  metadata.gz: 71929768b4b9c14a10e969ab4ace0687849082ce27816f4e78a04593d3f177fe3f286ad007e800a7f22bd57f6798b244ba43559ccca864ffde00f89c6e9764f5
+  data.tar.gz: 437c9ee4dd4b481ede08fc5c080c60bdb366741d33f89da9ae2af4285ae7c8875c9dde3776683612c003dce2eb8eb7b01828a679cbcf8d82f2d1cd07d61d72da

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuri Sidorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/exe/diffbroker

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/diffbroker"
+
+begin
+  exit Diffbroker::CLI.new(ARGV).run
+rescue Interrupt
+  exit 130
+end

data/lib/diffbroker/agent_projects.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Diffbroker
+  # The directories the user's own agents already know: Claude Code lists every project it ran in (~/.claude.json),
+  # Codex every project it trusts (~/.codex/config.toml). They tell where the user keeps code without asking and without
+  # walking the disk. Only the paths are read, and they never leave the machine: the server gets what RepoScanner
+  # finds in them (a repository name and a path), as for any other checkout.
+  module AgentProjects
+    CODEX_PROJECT = /\A\[projects\.(?:"((?:[^"\\]|\\.)*)"|'([^']*)')\]\s*\z/
+
+    def self.paths(home: Dir.home)
+      (claude(File.join(home, ".claude.json")) + codex(File.join(home, ".codex", "config.toml"))).uniq
+    end
+
+    def self.claude(file)
+      projects = File.file?(file) ? JSON.parse(File.read(file))["projects"] : nil
+      projects.is_a?(Hash) ? projects.keys.grep(String) : []
+    rescue JSON::ParserError, SystemCallError
+      []
+    end
+
+    def self.codex(file)
+      return [] unless File.file?(file)
+
+      File.foreach(file).filter_map { |line|
+        match = CODEX_PROJECT.match(line.strip)
+        match && (match[1] ? match[1].gsub(/\\(.)/, '\\1') : match[2])
+      }
+    rescue SystemCallError
+      []
+    end
+  end
+end

data/lib/diffbroker/agents/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Diffbroker
+  module Agents
+    class Base
+      TOKEN_ENV = "DIFFBROKER_TASK_TOKEN"
+      MAX_PATH = 100
+
+      def initialize(config:, worktree:)
+        @config = config
+        @worktree = worktree.to_s.chomp("/")
+      end
+
+      # The run's lines for the user's log: what the model said and the tools it called. Subclasses override.
+      def parse_log(_line) = []
+
+      def env(token, task_id) = { TOKEN_ENV => token, "DIFFBROKER_TASK_ID" => task_id }
+
+      private
+
+      # Spec §5.2: progress carries tool names and paths inside the worktree only.
+      def step(verb, path = nil, noun: "a file")
+        path = path.is_a?(String) ? path : ""
+        relative = path.start_with?("#{@worktree}/") ? path.delete_prefix("#{@worktree}/") : nil
+        return "#{verb} #{noun}" if relative.nil? || relative.empty? || relative.include?("..") || relative.match?(/[[:cntrl:]]/)
+
+        "#{verb} #{relative[0, MAX_PATH]}"
+      end
+
+      def parse_json(line)
+        event = JSON.parse(line)
+        event.is_a?(Hash) ? event : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      # The URL is written into a TOML override (Codex), so it must be a plain http(s) URL.
+      def mcp_url(mcp_config)
+        url = JSON.parse(File.read(mcp_config)).dig("mcpServers", "diffbroker", "url").to_s
+        raise Error, "Invalid Diff Broker MCP URL #{url.inspect} in #{mcp_config}" unless url.match?(%r{\Ahttps?://[^\s"'\\]+\z})
+
+        url
+      end
+    end
+  end
+end

data/lib/diffbroker/agents/claude.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Diffbroker
+  module Agents
+    # Claude Code. Autonomous: `claude -p … --output-format stream-json --verbose` (spec §4.2 step 5); the programmatic
+    # credit pool pays for it (spec §2). Terminal: interactive `claude`.
+    class Claude < Base
+      PLUGIN_DIR = File.join(Diffbroker::ROOT, "plugin")
+      # A bare `Read` in --allowedTools means every file on the machine, so a prompt-injected agent could read
+      # ~/.aws/credentials. `Read(./**)` is the worktree only (Grep and Glob follow Read rules), the settings flag makes
+      # the file tools refuse anything outside the working directory in every mode (a symlink out of the worktree
+      # included), and the deny rules name the usual secrets. Either of the first two alone was verified to block
+      # reads outside the worktree, in Read, Grep and Glob.
+      SECRET_PATHS = %w[Read(~/.ssh/**) Read(//**/.aws/**) Read(~/.gnupg/**) Read(~/.config/**) Read(~/.netrc)
+                        Read(~/.git-credentials) Read(//**/.env)].freeze
+      READ_ONLY_ARGS = [ "--permission-mode", "dontAsk", "--permission-prompts", "none",
+                         "--allowedTools", "Read(./**),mcp__diffbroker__*",
+                         "--disallowedTools", [ *%w[Bash Edit Write NotebookEdit WebFetch WebSearch], *SECRET_PATHS ].join(","),
+                         "--settings", { permissions: { blockReadsOutsideWorkingDirectories: true } }.to_json ].freeze
+      READS = %w[Read NotebookRead].freeze
+      EDITS = %w[Edit MultiEdit Write NotebookEdit].freeze
+
+      def initialize(config:, worktree:, plugin_dir: PLUGIN_DIR)
+        super(config:, worktree:)
+        @plugin_dir = plugin_dir
+      end
+
+      def name = "claude_code"
+
+      def autonomous_command(task, mcp_config:)
+        args = task["read_only"] ? READ_ONLY_ARGS : @config.claude_args
+        [ @config.claude_command, "-p", task.fetch("prompt"), "--output-format", "stream-json", "--verbose", *args,
+          "--mcp-config", mcp_config, *strict(task), "--plugin-dir", @plugin_dir ]
+      end
+
+      def terminal_command(task, mcp_config:)
+        [ @config.claude_command, "--mcp-config", mcp_config, *strict(task), "--plugin-dir", @plugin_dir ]
+      end
+
+      def parse_stream(line)
+        event = parse_json(line) or return nil
+
+        case event["type"]
+        when "system" then Progress.new(step: "starting", session_id: event["session_id"]) if event["subtype"] == "init"
+        when "assistant"
+          tool = Array(event.dig("message", "content")).reverse.find { _1.is_a?(Hash) && _1["type"] == "tool_use" }
+          tool && Progress.new(step: step_for(tool["name"].to_s, tool["input"].is_a?(Hash) ? tool["input"] : {}), session_id: nil)
+        when "result"
+          Result.new(cost_usd: event["total_cost_usd"], text: event["result"].to_s, error: event["is_error"] == true)
+        end
+      end
+
+      # Assistant text and thinking, each tool call (a name and a path or a short command), and the final answer. A tool's
+      # result is the file contents it read, which stay on the machine (spec §5.2).
+      def parse_log(line)
+        event = parse_json(line) or return []
+
+        case event["type"]
+        when "assistant" then Array(event.dig("message", "content")).filter_map { log_block(_1) }
+        when "result" then event["result"].to_s.strip.empty? ? [] : [ Entry.new(kind: event["is_error"] == true ? "error" : "result", text: event["result"].to_s) ]
+        else []
+        end
+      end
+
+      private
+
+      def log_block(block)
+        return unless block.is_a?(Hash)
+
+        case block["type"]
+        when "text" then Entry.new(kind: "text", text: block["text"].to_s) unless block["text"].to_s.strip.empty?
+        when "thinking" then Entry.new(kind: "thinking", text: block["thinking"].to_s) unless block["thinking"].to_s.strip.empty?
+        when "tool_use" then Entry.new(kind: "tool", text: tool_line(block["name"].to_s, block["input"].is_a?(Hash) ? block["input"] : {}))
+        end
+      end
+
+      def tool_line(tool, input)
+        detail = input["file_path"] || input["notebook_path"] || input["pattern"] || input["command"] || input["path"]
+        detail = relative_path(detail) if detail.is_a?(String)
+        [ tool.gsub(/[^\w-]/, "")[0, 40], (detail.to_s.gsub(/[[:cntrl:]]/, " ")[0, 200] if detail.is_a?(String)) ].compact.join(" ")
+      end
+
+      def relative_path(value) = value.start_with?("#{@worktree}/") ? value.delete_prefix("#{@worktree}/") : value
+
+      def strict(task) = task["untrusted"] ? [ "--strict-mcp-config" ] : []
+
+      def step_for(tool, input)
+        case tool
+        when *READS then step("reading", input["file_path"])
+        when *EDITS then step("editing", input["file_path"] || input["notebook_path"])
+        when "Bash" then "running a command"
+        when "Grep", "Glob" then "searching"
+        when /\Amcp__diffbroker__(\w+)\z/ then "calling #{Regexp.last_match(1)}"
+        when "TodoWrite" then "planning"
+        else "using #{tool.gsub(/[^\w-]/, "")[0, 40]}"
+        end
+      end
+    end
+  end
+end

data/lib/diffbroker/agents/codex.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Diffbroker
+  module Agents
+    # Codex. Autonomous: `codex exec --json` in a workspace-write sandbox with network (spec §4.2 step 5); the MCP
+    # server is configured for this run only with -c overrides. Codex reports no cost (counted as unknown).
+    # Read-only kinds use `--sandbox read-only`: Codex still runs shell commands there (read-only filesystem, no network),
+    # so it is not a no-exec mode. It also loads the user's own MCP servers (no --strict-mcp-config), which is why
+    # TaskRunner never runs Codex headless on an untrusted head.
+    class Codex < Base
+      READ_ONLY_ARGS = %w[--sandbox read-only].freeze
+
+      def name = "codex"
+
+      def autonomous_command(task, mcp_config:)
+        args = task["read_only"] ? READ_ONLY_ARGS : @config.codex_args
+        [ @config.codex_command, "exec", "--json", *args, *mcp_overrides(mcp_config), task.fetch("prompt") ]
+      end
+
+      def terminal_command(_task, mcp_config:) = [ @config.codex_command, *mcp_overrides(mcp_config) ]
+
+      def parse_stream(line)
+        event = parse_json(line) or return nil
+
+        case event["type"]
+        when "thread.started" then Progress.new(step: "starting", session_id: event["thread_id"])
+        when "item.started", "item.completed" then item(event["item"].is_a?(Hash) ? event["item"] : {})
+        when "turn.completed" then Result.new(cost_usd: nil, text: @last_message.to_s, error: false)
+        when "turn.failed", "error" then Result.new(cost_usd: nil, text: @last_message.to_s, error: true)
+        end
+      end
+
+      def parse_log(line)
+        event = parse_json(line) or return []
+        return [] unless %w[item.completed].include?(event["type"]) && event["item"].is_a?(Hash)
+
+        item = event["item"]
+        case item["type"]
+        when "agent_message" then item["text"].to_s.strip.empty? ? [] : [ Entry.new(kind: "text", text: item["text"].to_s) ]
+        when "reasoning" then item["text"].to_s.strip.empty? ? [] : [ Entry.new(kind: "thinking", text: item["text"].to_s) ]
+        when "command_execution" then [ Entry.new(kind: "tool", text: "Ran #{item["command"].to_s.gsub(/[[:cntrl:]]/, " ")[0, 200]}") ]
+        when "file_change" then [ Entry.new(kind: "tool", text: step("edited", first_change_path(item["changes"]))) ]
+        when "mcp_tool_call" then [ Entry.new(kind: "tool", text: "Called #{item["tool"].to_s.gsub(/[^\w]/, "")[0, 40]}") ]
+        else []
+        end
+      end
+
+      private
+
+      def item(item)
+        case item["type"]
+        when "command_execution" then Progress.new(step: "running a command", session_id: nil)
+        when "file_change" then Progress.new(step: step("editing", first_change_path(item["changes"])), session_id: nil)
+        when "mcp_tool_call" then Progress.new(step: "calling #{item["tool"].to_s.gsub(/[^\w]/, "")[0, 40]}", session_id: nil)
+        when "agent_message"
+          @last_message = item["text"]
+          nil
+        end
+      end
+
+      def first_change_path(changes)
+        change = changes.is_a?(Array) ? changes.first : nil
+        change.is_a?(Hash) ? change["path"] : nil
+      end
+
+      def mcp_overrides(mcp_config)
+        [ "-c", %(mcp_servers.diffbroker.url="#{mcp_url(mcp_config)}"),
+          "-c", %(mcp_servers.diffbroker.env_http_headers={ "x-task-token" = "#{TOKEN_ENV}" }) ]
+      end
+    end
+  end
+end

data/lib/diffbroker/agents.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Diffbroker
+  # The user's own coding agents, run headless (autonomous) or interactively (terminal). Spec §4.2 steps 5–7.
+  module Agents
+    Progress = Data.define(:step, :session_id)
+    Result = Data.define(:cost_usd, :text, :error)
+    # One line of the run for the user's own log (kind: text, thinking, tool, error or result). Tool results (file
+    # contents) are never an entry.
+    Entry = Data.define(:kind, :text)
+
+    autoload :Base, File.expand_path("agents/base", __dir__)
+    autoload :Claude, File.expand_path("agents/claude", __dir__)
+    autoload :Codex, File.expand_path("agents/codex", __dir__)
+
+    def self.for(config, worktree:) = (config.agent == "codex" ? Codex : Claude).new(config:, worktree:)
+  end
+end

data/lib/diffbroker/api.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Diffbroker
+  # JSON POST client for Diff Broker's companion endpoints (bearer device or task token).
+  class Api
+    class HttpError < Error
+      attr_reader :status, :body
+
+      def initialize(status, body)
+        @status = status
+        @body = body.is_a?(Hash) ? body : {}
+        super("HTTP #{status}: #{@body["error"] || body}")
+      end
+    end
+
+    def initialize(server:, token: nil)
+      @server = server.to_s.chomp("/")
+      @token = token
+    end
+
+    def post(path, body = {})
+      send_request(Net::HTTP::Post, path) { |request| request.body = JSON.generate(body) }
+    end
+
+    def get(path) = send_request(Net::HTTP::Get, path)
+
+    private
+
+    def send_request(verb, path)
+      uri = URI("#{@server}#{path}")
+      request = verb.new(uri)
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["User-Agent"] = "diffbroker/#{VERSION}"
+      request["Authorization"] = "Bearer #{@token}" if @token
+      yield request if block_given?
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: 30) do |http|
+        http.request(request)
+      end
+      parsed = parse(response.body)
+      raise HttpError.new(response.code.to_i, parsed) unless response.is_a?(Net::HTTPSuccess)
+
+      parsed
+    end
+
+    def parse(body)
+      return {} if body.to_s.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      { "error" => body.to_s[0, 200] }
+    end
+  end
+end

data/lib/diffbroker/branch_publisher.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Diffbroker
+  # Pushes the result of an update_branch task (a rebase onto the fresh base) after the agent has exited. The agent never
+  # pushes it: a rebase needs a lease-guarded forced push, and the user's own Claude Code hooks refuse those inside an
+  # agent run. The push is pinned to the head the task started from, so it can only replace exactly the history the agent
+  # rebased, never a commit somebody pushed meanwhile. Nothing is pushed unless the worktree is a finished, clean,
+  # linear rebase on top of the fresh base.
+  class BranchPublisher
+    Result = Struct.new(:status, :message) do
+      def pushed? = status == :pushed
+      def failed? = status == :failed
+    end
+
+    REF = %r{\A\w[\w./-]{0,200}\z}
+
+    def initialize(dir:, head_ref:, expected_sha:, base_ref:, remote: "origin", runner: Runner.new)
+      @dir = dir
+      @head_ref = head_ref.to_s
+      @expected = expected_sha.to_s
+      @base_ref = base_ref.to_s
+      @remote = remote.to_s
+      @runner = runner
+    end
+
+    def publish!
+      return failed("No branch name to push.") unless valid_ref?(@head_ref) && valid_ref?(@base_ref) && valid_ref?(@remote)
+      return failed("No starting head to protect.") unless @expected.match?(/\A[0-9a-f]{7,40}\z/)
+      return failed("A rebase or merge is still in progress in the worktree: finish it first.") if in_progress?
+      return failed("The worktree has uncommitted changes.") unless git("status", "--porcelain").strip.empty?
+
+      head = git("rev-parse", "HEAD").strip
+      return Result.new(:nothing, "Nothing to push: the branch did not change.") if head.start_with?(@expected) || @expected.start_with?(head)
+
+      git("fetch", "--quiet", @remote, @base_ref)
+      unless @runner.git_success?(@dir, "merge-base", "--is-ancestor", "#{@remote}/#{@base_ref}", "HEAD")
+        return failed("The branch is not on top of #{@remote}/#{@base_ref}: nothing pushed.")
+      end
+      unless git("rev-list", "--merges", "#{@remote}/#{@base_ref}..HEAD").strip.empty?
+        return failed("The branch contains merge commits; it must be a clean rebase: nothing pushed.")
+      end
+
+      git("push", lease_option, @remote, "HEAD:refs/heads/#{@head_ref}")
+      Result.new(:pushed, "Pushed #{@head_ref} rebased onto #{@remote}/#{@base_ref}.")
+    rescue Error => e
+      failed("Push failed: #{e.message.lines.first.to_s.strip}")
+    end
+
+    private
+
+    # Pinned to the starting head: git refuses the push if the remote branch is anywhere else.
+    def lease_option = "--force-with-lease=refs/heads/#{@head_ref}:#{@expected}"
+
+    def git(*args) = @runner.git(@dir, *args)
+
+    def failed(message) = Result.new(:failed, message)
+
+    def valid_ref?(ref) = ref.match?(REF) && !ref.include?("..") && !ref.end_with?("/", ".lock")
+
+    def in_progress?
+      %w[rebase-merge rebase-apply MERGE_HEAD CHERRY_PICK_HEAD].any? do |name|
+        File.exist?(File.absolute_path(git("rev-parse", "--git-path", name).strip, @dir))
+      end
+    end
+  end
+end

data/lib/diffbroker/cable_client.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "openssl"
+require "uri"
+require "websocket/driver"
+
+module Diffbroker
+  # One outbound WebSocket to Diff Broker's Action Cable (spec §4.1: no listening ports), one thread: IO.select drives
+  # reads, writes, ticks, polls and staleness. `perform` may be called from any thread (task runners report from their
+  # own); it only queues the frame and wakes the loop, so the socket (an SSL socket in production, which is not safe
+  # for concurrent reads and writes) is only ever touched by the thread in `run`. One client serves one connection.
+  class CableClient
+    class Unauthorized < Error; end
+    class HandshakeError < Error; end
+
+    # Action Cable's JSON wire format for DeviceChannel.
+    class Protocol
+      CHANNEL = "DeviceChannel"
+
+      def identifier = JSON.generate({ channel: CHANNEL })
+      def subscribe = JSON.generate({ command: "subscribe", identifier: })
+
+      def perform(action, data = {})
+        JSON.generate({ command: "message", identifier:, data: JSON.generate(data.merge("action" => action)) })
+      end
+
+      def parse(raw)
+        message = JSON.parse(raw)
+        return [ :ignored ] unless message.is_a?(Hash)
+
+        case message["type"]
+        when "welcome" then [ :welcome ]
+        when "ping" then [ :ping ]
+        when "confirm_subscription" then [ :confirmed ]
+        when "reject_subscription" then [ :rejected ]
+        when "disconnect" then [ :disconnect, message["reason"], message["reconnect"] ]
+        else message["identifier"] == identifier && message["message"].is_a?(Hash) ? [ :message, message["message"] ] : [ :ignored ]
+        end
+      rescue JSON::ParserError
+        [ :ignored ]
+      end
+    end
+
+    SUBPROTOCOL = "actioncable-v1-json"
+    STALE_AFTER = 20
+    TICK_EVERY = 30
+    POLL_EVERY = 1
+    SELECT_TIMEOUT = 1
+    CONNECT_TIMEOUT = 10
+    READ_CHUNK = 16_384
+
+    SocketAdapter = Struct.new(:url, :io) do
+      def write(data) = io.write(data)
+    end
+
+    def initialize(url:, token:, origin:, protocol: Protocol.new)
+      @url = url
+      @token = token
+      @origin = origin
+      @protocol = protocol
+      @outbox = Queue.new
+      @wake_reader, @wake_writer = IO.pipe
+    end
+
+    def on_subscribed(&block) = @on_subscribed = block
+    def on_message(&block) = @on_message = block
+    def on_tick(&block) = @on_tick = block
+    def on_poll(&block) = @on_poll = block
+
+    def perform(action, data = {})
+      @outbox << @protocol.perform(action, data)
+      wake
+    end
+
+    def stop
+      @stopped = true
+      wake
+    end
+
+    def run
+      @stopped = false
+      @welcomed = false
+      @subscribed = false
+      @io = open_socket
+      @driver = build_driver
+      @driver.start
+      @started = @last_ping = @last_tick = monotonic
+      @last_poll = 0.0
+      pump
+      final_flush
+    ensure
+      @io.close if @io && !@io.closed?
+      [ @wake_reader, @wake_writer ].each(&:close)
+    end
+
+    private
+
+    def build_driver
+      driver = WebSocket::Driver.client(SocketAdapter.new(@url, @io), protocols: [ SUBPROTOCOL ])
+      driver.set_header("Authorization", "Bearer #{@token}")
+      driver.set_header("Origin", @origin)
+      driver.on(:message) { |event| dispatch(event.data) }
+      driver.on(:close) { @stopped = true }
+      driver.on(:error) { |event| raise HandshakeError, event.message unless @welcomed }
+      driver
+    end
+
+    def pump
+      until @stopped
+        break if read == :eof
+
+        flush
+        stale!
+        tick
+        poll
+      end
+    end
+
+    def read
+      readable = @io.respond_to?(:pending) && @io.pending.positive? ? [ @io ] : IO.select([ @io, @wake_reader ], nil, nil, SELECT_TIMEOUT)&.first
+      return unless readable
+
+      @wake_reader.read_nonblock(1024, exception: false) if readable.include?(@wake_reader)
+      return unless readable.include?(@io)
+
+      chunk = @io.read_nonblock(READ_CHUNK, exception: false)
+      return :eof if chunk.nil?
+
+      @driver.parse(chunk) if chunk.is_a?(String)
+    end
+
+    def flush
+      return unless @welcomed
+
+      @driver.text(@outbox.pop) until @outbox.empty?
+    end
+
+    # Reports queued just before a stop (a task's `finished`) still go out; a dead socket just drops them.
+    def final_flush
+      flush
+    rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+      nil
+    end
+
+    def stale!
+      if @welcomed
+        @stopped = true if monotonic - @last_ping > STALE_AFTER
+      elsif monotonic - @started > STALE_AFTER
+        raise HandshakeError, "No welcome from #{@url} within #{STALE_AFTER} s"
+      end
+    end
+
+    def tick
+      return if monotonic - @last_tick < TICK_EVERY
+
+      @last_tick = monotonic
+      @on_tick&.call
+    end
+
+    def poll
+      return unless @subscribed && monotonic - @last_poll >= POLL_EVERY
+
+      @last_poll = monotonic
+      @on_poll&.call
+    end
+
+    def dispatch(raw)
+      kind, *rest = @protocol.parse(raw)
+      case kind
+      when :welcome
+        @welcomed = true
+        @last_ping = monotonic
+        @driver.text(@protocol.subscribe)
+      when :ping then @last_ping = monotonic
+      when :confirmed
+        @subscribed = true
+        @on_subscribed&.call
+      when :rejected then raise Unauthorized, "The server rejected the device channel subscription"
+      when :disconnect
+        raise Unauthorized, "The server rejected this device token" if rest.first == "unauthorized"
+
+        @stopped = true
+      when :message then @on_message&.call(rest.first)
+      end
+    end
+
+    def wake
+      @wake_writer.write_nonblock(".", exception: false)
+    rescue IOError
+      nil
+    end
+
+    def open_socket
+      uri = URI(@url)
+      raise Error, "Invalid cable URL #{@url.inspect}" unless %w[ws wss].include?(uri.scheme) && uri.host
+
+      tcp = Socket.tcp(uri.host, uri.port, connect_timeout: CONNECT_TIMEOUT)
+      return tcp unless uri.scheme == "wss"
+
+      context = OpenSSL::SSL::SSLContext.new
+      context.set_params(verify_mode: OpenSSL::SSL::VERIFY_PEER, verify_hostname: true)
+      ssl = OpenSSL::SSL::SSLSocket.new(tcp, context)
+      ssl.hostname = uri.host
+      ssl.sync_close = true
+      ssl.connect
+      ssl
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end