harnex 0.12.0 → 0.29.0

data/lib/harnex/commands/doctor.rb

@@ -3,21 +3,18 @@ require "optparse"
 
 module Harnex
   class Doctor
-    MIN_CODEX_VERSION = Gem::Version.new("0.128.0")
     MIN_PI_VERSION = Harnex::Adapters::Pi::MIN_RPC_VERSION
-    SUPPORTED_ADAPTERS = %w[codex pi].freeze
+    SUPPORTED_ADAPTERS = %w[pi].freeze
 
     def self.usage
       <<~TEXT
-        Usage: harnex doctor [--adapter codex|pi|all] [--sweep] [--prune [--dry-run]]
+        Usage: harnex doctor [--adapter pi|all] [--sweep] [--prune [--dry-run]]
 
-        Runs static preflight checks for harnex adapter dependencies. Codex is
-        checked by default for backwards compatibility; select Pi explicitly
-        after installing or upgrading it.
+        Runs static preflight checks for harnex adapter dependencies (Pi).
 
         Options:
           --adapter NAME
-                       Check codex, pi, or all (repeatable; default: codex)
+                       Check pi or all (default: pi)
           --sweep      Include a read-only report of harnex/tmux session drift
           --prune      Apply bounded harnex events/output/receipt retention pruning
           --dry-run    Preview --prune candidates without deleting
@@ -34,6 +31,9 @@ module Harnex
         Gotchas:
           doctor validates local adapter prerequisites; it does not start sessions.
           Pi RPC requires >= #{MIN_PI_VERSION} so `agent_settled` is available.
+          JSON includes harnex_version and versioned capabilities; check
+          capabilities.runtime_budget == 1 before using run --max-runtime, and
+          capabilities.pi_command_proof == 1 before trusting Pi receipt commands.
           --sweep is diagnostic only; it does not stop sessions or remove files.
           --dry-run must be paired with --prune.
           Run it after installing or upgrading a selected agent CLI.
@@ -59,12 +59,32 @@ module Harnex
         return 0
       end
 
-      checks = selected_adapters.map { |name| name == "pi" ? check_pi : check_codex }
+      checks = selected_adapters.map { |_name| check_pi }
       retention = retention_payload
       summary = {
         ok: checks.all? { |c| c[:ok] } && retention.fetch(:ok, true),
         checks: checks,
-        retention: retention
+        retention: retention,
+        harnex_version: Harnex::VERSION,
+        integrations: MCPCommand.integrations,
+        capabilities: {
+          runtime_budget: 1,
+          work_activity: 1,
+          stop_provenance: 1,
+          monitor_deadline: 1,
+          monitor_heartbeat: 1,
+          pi_idle_stop: 1,
+          pi_command_proof: 1,
+          final_gates: 1,
+          outcome_classes: 1,
+          preflight: 1,
+          ask: 1,
+          final_message: 1,
+          owner_tag: 1,
+          ask_resume: 1,
+          lanes: 1,
+          mcp: 1
+        }
       }
       summary[:sweep] = sweep_payload if @options[:sweep]
       puts JSON.generate(summary)
@@ -75,8 +95,8 @@ module Harnex
 
     def parser
       @parser ||= OptionParser.new do |opts|
-        opts.banner = "Usage: harnex doctor [--adapter codex|pi|all] [--sweep] [--prune [--dry-run]]"
-        opts.on("--adapter NAME", "Check codex, pi, or all (repeatable)") { |value| @options[:adapters] << value.to_s.downcase }
+        opts.banner = "Usage: harnex doctor [--adapter pi|all] [--sweep] [--prune [--dry-run]]"
+        opts.on("--adapter NAME", "Check pi or all") { |value| @options[:adapters] << value.to_s.downcase }
         opts.on("--sweep", "Include read-only session drift diagnostics") { @options[:sweep] = true }
         opts.on("--prune", "Apply retention pruning") { @options[:prune] = true }
         opts.on("--dry-run", "Preview --prune candidates without deleting") { @options[:dry_run] = true }
@@ -99,7 +119,7 @@ module Harnex
 
     def selected_adapters
       requested = @options[:adapters]
-      return ["codex"] if requested.empty?
+      return ["pi"] if requested.empty?
       return SUPPORTED_ADAPTERS if requested.include?("all")
 
       requested.uniq
@@ -120,30 +140,6 @@ module Harnex
       { ok: false, error: e.message }
     end
 
-    def check_codex
-      result = { name: "codex", required: ">= #{MIN_CODEX_VERSION}" }
-
-      version_output, status = capture("codex --version")
-      if status.nil?
-        return result.merge(ok: false, error: "codex CLI not found on PATH")
-      end
-      unless status.success?
-        return result.merge(ok: false, error: "codex --version failed: #{version_output.strip}")
-      end
-
-      version = parse_version(version_output)
-      if version.nil?
-        return result.merge(ok: false, found: version_output.strip, error: "could not parse codex version output")
-      end
-
-      if version < MIN_CODEX_VERSION
-        return result.merge(ok: false, found: version.to_s,
-                            error: "codex #{version} < required #{MIN_CODEX_VERSION}; upgrade with `npm i -g @openai/codex` or your platform package manager")
-      end
-
-      result.merge(ok: true, found: version.to_s)
-    end
-
     def check_pi
       result = { name: "pi", required: ">= #{MIN_PI_VERSION}" }
 
@@ -206,6 +202,8 @@ module Harnex
         end
       rescue JSON::ParserError
         stale << { registry_path: path, error: "invalid_json" }
+      rescue Errno::ENOENT
+        next # removed by a finalizing session after the glob
       end
 
       [active.sort_by { |session| [session["repo_root"].to_s, session["started_at"].to_s, session["id"].to_s] }.reverse, stale]

data/lib/harnex/commands/events.rb

@@ -20,9 +20,9 @@ module Harnex
           -h, --help      Show this help
 
         Common patterns:
-          #{program_name} --id cx-i-42 --snapshot
-          #{program_name} --id cx-i-42
-          #{program_name} --id cx-i-42 --from 2026-05-06T10:00:00Z --snapshot
+          #{program_name} --id pi-i-42 --snapshot
+          #{program_name} --id pi-i-42
+          #{program_name} --id pi-i-42 --from 2026-05-06T10:00:00Z --snapshot
 
         Gotchas:
           events is structured JSONL; logs is human transcript text.

data/lib/harnex/commands/history.rb

@@ -135,15 +135,9 @@ module Harnex
 
     def load_records
       path = DispatchHistory.path_for(Dir.pwd, global: @options[:global])
-      return [] unless File.file?(path)
+      return [] unless File.file?(path) || !ENV.fetch(DispatchHistory::HISTORY_READER_ENV, "").strip.empty?
 
-      File.readlines(path, chomp: true).filter_map do |line|
-        next if line.strip.empty?
-
-        JSON.parse(line)
-      rescue JSON::ParserError
-        nil
-      end
+      DispatchHistory.each_record(path).to_a
     end
 
     def started_after?(record, floor)

data/lib/harnex/commands/land.rb

@@ -0,0 +1,150 @@
+module Harnex
+  # `harnex land` / `harnex discard` (#87): finish a worktree lane. Land
+  # merges harnex/NAME into the main checkout's current branch, then removes
+  # the worktree and branch; on conflict git's merge stays in progress for
+  # the caller to resolve, and the next `land` cleans up. Discard drops the
+  # lane's work.
+  class Land
+    def self.usage(discard: false)
+      if discard
+        <<~TEXT
+          Usage: harnex discard NAME...
+
+          Stop a lane (if it is still working) and delete its worktree and branch
+          without merging. Uncommitted and unmerged work in the lane is lost.
+        TEXT
+      else
+        <<~TEXT
+          Usage: harnex land [NAME...]
+
+          Merge a worktree lane (branch harnex/NAME) into the current branch of the
+          main checkout, then remove its worktree and branch. With no NAME: every
+          finished worktree lane you started in this repo, oldest first. Uncommitted changes
+          in the lane are committed first. On a merge conflict the merge stays in
+          progress: resolve it, `git commit`, and run `harnex land NAME` again to
+          clean up (or `git merge --abort`).
+
+          Exit codes: 0 landed, 1 conflict or another problem (the lane is kept).
+        TEXT
+      end
+    end
+
+    def initialize(argv, out: $stdout, err: $stderr, discard: false, harnex_command: nil)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @discard = discard
+      @harnex_command = harnex_command || [Gem.ruby, File.expand_path("../../../bin/harnex", __dir__)]
+    end
+
+    def run
+      if (@argv.empty? && @discard) || @argv.any? { |arg| %w[-h --help].include?(arg) }
+        @out.puts self.class.usage(discard: @discard)
+        return @argv.empty? ? 2 : 0
+      end
+      flag = @argv.find { |arg| arg.start_with?("-") }
+      raise OptionParser::InvalidOption, "harnex #{verb}: unknown flag #{flag}" if flag
+
+      lanes = @argv.empty? ? finished_lanes : @argv.map { |name| Lanes.resolve(name) }
+      if lanes.empty?
+        @out.puts "no finished worktree lanes to land (see `harnex lanes`)"
+        return 0
+      end
+      lanes.map { |lane| @discard ? discard(lane) : land(lane) }.max
+    end
+
+    private
+
+    # `harnex land` alone: the caller's finished worktree lanes in this repo.
+    def finished_lanes
+      root = Lanes.main_root(Dir.pwd)
+      owner = Harnex.ambient_owner_id
+      Lanes.all.select { |lane| lane["repo_root"] == root && lane["owner"] == owner && lane["branch"] && lane["state"] == "done" }
+           .sort_by { |lane| lane["created_at"].to_s }
+    end
+
+    def verb
+      @discard ? "discard" : "land"
+    end
+
+    def land(lane)
+      name = lane["name"]
+      return say(lane, "already landed") if lane["state"] == "landed"
+      return refuse(lane, "it was discarded") if lane["state"] == "discarded"
+      return refuse(lane, "it worked in place (no worktree); its changes are already in #{lane['cwd']}") unless lane["branch"]
+      return refuse(lane, "it is still working; wait with `harnex result #{name}` or stop it with `harnex discard #{name}`") if Lanes.live?(lane)
+
+      root = lane["repo_root"]
+      if File.exist?(File.join(git_dir(root), "MERGE_HEAD"))
+        conflicts = conflicted(root)
+        return refuse(lane, "a merge is in progress in #{root}#{conflicts.empty? ? '' : " (conflicts: #{conflicts.join(', ')})"}; " \
+                          "finish it with `git commit` (or `git merge --abort`), then run `harnex land #{name}` again")
+      end
+
+      committed = commit_leftovers(lane)
+      target, = Lanes.git(root, "branch", "--show-current")
+      _out, _err, merged = Lanes.git(root, "merge-base", "--is-ancestor", lane["branch"], "HEAD")
+      unless merged
+        count, = Lanes.git(root, "rev-list", "--count", "HEAD..#{lane['branch']}")
+        _out, err, ok = Lanes.git(root, "merge", "--no-edit", lane["branch"])
+        unless ok
+          conflicts = conflicted(root)
+          return refuse(lane, "could not merge #{lane['branch']}: #{err.lines.last.to_s.strip}") if conflicts.empty?
+
+          return refuse(lane, "merge conflict in #{conflicts.join(', ')} (the merge is left in progress in #{root}).\n" \
+                            "   next: resolve the files, `git add` them and `git commit`, then `harnex land #{name}` again " \
+                            "to clean up; to give up: `git merge --abort`")
+        end
+      end
+
+      removed, err = Lanes.remove_worktree(lane)
+      return refuse(lane, "merged, but could not remove its worktree: #{err}") unless removed
+
+      lane["state"] = "landed"
+      lane["landed_at"] = Lanes.now
+      Lanes.save(lane)
+      what = merged ? "was already merged" : "merged #{lane['branch']} into #{target.empty? ? 'HEAD' : target} (#{count} commit#{count == '1' ? '' : 's'})"
+      say(lane, "#{what}#{committed ? '; committed its uncommitted changes first' : ''}; removed its worktree and branch")
+    end
+
+    def discard(lane)
+      return say(lane, "already #{lane['state']}") if Lanes::CLOSED_STATES.include?(lane["state"])
+
+      if Lanes.live?(lane)
+        Open3.capture3(*(@harnex_command + ["stop", "--id", lane["name"], "--repo", lane["run_root"]]))
+      end
+      Lanes.remove_worktree(lane, force: true) if lane["branch"]
+      lane["state"] = "discarded"
+      Lanes.save(lane)
+      say(lane, lane["branch"] ? "discarded; removed its worktree and branch #{lane['branch']}" : "discarded")
+    end
+
+    def commit_leftovers(lane)
+      return false unless lane["worktree"] && File.directory?(lane["worktree"]) && Lanes.dirty_paths(lane["worktree"]).any?
+
+      Lanes.git(lane["worktree"], "add", "-A")
+      _out, _err, ok = Lanes.git(lane["worktree"], "commit", "-q", "-m", "harnex: uncommitted changes from lane #{lane['name']}")
+      ok
+    end
+
+    def git_dir(root)
+      dir, = Lanes.git(root, "rev-parse", "--absolute-git-dir")
+      dir
+    end
+
+    def conflicted(root)
+      out, = Lanes.git(root, "diff", "--name-only", "--diff-filter=U")
+      out.lines.map(&:strip).reject(&:empty?)
+    end
+
+    def say(lane, text)
+      @out.puts "── #{lane['name']}: #{text}"
+      0
+    end
+
+    def refuse(lane, text)
+      @out.puts "── #{lane['name']}: not landed — #{text}"
+      1
+    end
+  end
+end

data/lib/harnex/commands/lanes.rb

@@ -0,0 +1,84 @@
+module Harnex
+  # `harnex lanes` (#87): the lanes in this repo (or everywhere), newest
+  # first, with what each needs next.
+  class LanesCommand
+    def self.usage
+      <<~TEXT
+        Usage: harnex lanes [--all] [--closed] [--json]
+
+        List the lanes of this repo: name, state, age, model, branch and what
+        to do next. Landed and discarded lanes are hidden unless --closed.
+
+        Options:
+          --all      Lanes of every repo
+          --closed   Include landed and discarded lanes
+          --json     JSON array of lane records
+          -h, --help Show this help
+      TEXT
+    end
+
+    def initialize(argv, out: $stdout)
+      @argv = argv.dup
+      @out = out
+    end
+
+    def run
+      unknown = @argv - %w[--all --closed --json -h --help]
+      raise OptionParser::InvalidOption, "harnex lanes: unknown argument #{unknown.first}" unless unknown.empty?
+
+      if (@argv & %w[-h --help]).any?
+        @out.puts self.class.usage
+        return 0
+      end
+
+      Lanes.sweep_merged(Lanes.main_root(Dir.pwd))
+      lanes = selected
+      if @argv.include?("--json")
+        @out.puts JSON.generate(lanes.map { |lane| lane.merge("live" => Lanes.live?(lane)) })
+      elsif lanes.empty?
+        @out.puts "no lanes#{@argv.include?('--all') ? '' : ' in this repo'} (start one with `harnex delegate`)"
+      else
+        @out.puts table(lanes)
+      end
+      0
+    end
+
+    private
+
+    def selected
+      root = Lanes.main_root(Dir.pwd) || File.expand_path(Dir.pwd)
+      lanes = Lanes.all
+      lanes = lanes.select { |lane| lane["repo_root"] == root } unless @argv.include?("--all")
+      lanes = lanes.select { |lane| Lanes.open?(lane) } unless @argv.include?("--closed")
+      lanes.sort_by { |lane| lane["launched_at"] || lane["created_at"] || "" }.reverse
+    end
+
+    def table(lanes)
+      rows = lanes.map do |lane|
+        [lane["name"], state(lane), Lanes.duration(lane["launched_at"] || lane["created_at"]),
+         lane["model"] || lane["requested_model"] || "-", lane["branch"] || lane["kind"], next_step(lane)]
+      end
+      header = %w[NAME STATE AGE MODEL BRANCH NEXT]
+      widths = header.each_index.map { |i| ([header[i]] + rows.map { |r| r[i].to_s }).map(&:length).max }
+      ([header] + rows).map { |row| row.each_with_index.map { |cell, i| i == row.length - 1 ? cell.to_s : cell.to_s.ljust(widths[i]) }.join("  ") }.join("\n")
+    end
+
+    def state(lane)
+      return lane["state"] unless lane["state"] == "running"
+      return "finished, uncollected" unless Lanes.live?(lane)
+
+      detail = Lanes.progress_line(lane)[/ · (now .*|thinking)\z/, 1]
+      detail ? "working (#{detail})" : "working"
+    end
+
+    def next_step(lane)
+      name = lane["name"]
+      case lane["state"]
+      when "running" then "harnex result #{name}"
+      when "done" then lane["branch"] ? "harnex land #{name}" : "harnex reply #{name} \"...\""
+      when "failed" then "harnex reply #{name} \"Continue...\""
+      else "-"
+      end
+    end
+  end
+end

data/lib/harnex/commands/logs.rb

@@ -19,9 +19,9 @@ module Harnex
           -h, --help    Show this help
 
         Common patterns:
-          #{program_name} --id cx-i-42 --lines 80
-          #{program_name} --id cx-i-42 --follow
-          #{program_name} --id cx-i-42 --repo /path/to/repo --lines 200
+          #{program_name} --id pi-i-42 --lines 80
+          #{program_name} --id pi-i-42 --follow
+          #{program_name} --id pi-i-42 --repo /path/to/repo --lines 200
 
         Gotchas:
           logs reads the persisted transcript, not the live tmux screen.

data/lib/harnex/commands/mcp.rb

@@ -0,0 +1,208 @@
+module Harnex
+  # `harnex mcp` (#87): serve the lane verbs over MCP stdio, or register that
+  # server with Claude Code (user scope) and Pi (~/.pi/agent/mcp.json).
+  class MCPCommand
+    SERVER_NAME = "harnex".freeze
+    PI_TIMEOUT_SECONDS = 7200
+    AGENT_SOURCE = File.expand_path("../../../agents/gpt.md", __dir__).freeze
+
+    def self.agent_path
+      File.expand_path("~/.claude/agents/gpt.md")
+    end
+
+    def self.usage
+      <<~TEXT
+        Usage: harnex mcp                  Serve MCP over stdio (what MCP clients run)
+               harnex mcp install [--claude] [--pi] [--no-agent] [--dry-run]
+               harnex mcp uninstall [--claude] [--pi]
+               harnex mcp status
+
+        Exposes ask, delegate, result, reply, land, discard and lanes as native tools.
+        install registers the server for Claude Code (`claude mcp add --scope user`)
+        and Pi (#{pi_config_path}, exposure direct). With neither flag it does both
+        (each only when that CLI is installed). For Claude Code it also installs the
+        `gpt` subagent at ~/.claude/agents/gpt.md unless one exists (--no-agent skips it).
+        Restart running sessions afterwards.
+      TEXT
+    end
+
+    # Where the agent-facing integrations stand (doctor reports this; it
+    # reads config files only, so it never starts a client).
+    def self.integrations
+      claude = begin
+        JSON.parse(File.read(File.expand_path("~/.claude.json"))).dig("mcpServers", SERVER_NAME)
+      rescue StandardError
+        nil
+      end
+      pi = begin
+        JSON.parse(File.read(pi_config_path)).dig("mcpServers", SERVER_NAME)
+      rescue StandardError
+        nil
+      end
+      result = { claude_mcp: !claude.nil?, pi_mcp: !pi.nil?,
+                 gpt_agent: File.exist?(agent_path) }
+      result[:hint] = "run `harnex mcp install` for native tools in Claude Code and Pi" unless claude && pi
+      result
+    end
+
+    def self.pi_config_path
+      dir = ENV["PI_AGENT_DIR"] || ENV["PI_CODING_AGENT_DIR"] || File.expand_path("~/.pi/agent")
+      File.join(dir, "mcp.json")
+    end
+
+    def initialize(argv, out: $stdout, err: $stderr)
+      @argv = argv.dup
+      @out = out
+      @err = err
+    end
+
+    def run
+      action = @argv.first.to_s.start_with?("-") || @argv.empty? ? "serve" : @argv.shift
+      if @argv.include?("-h") || @argv.include?("--help") || action == "help"
+        @out.puts self.class.usage
+        return 0
+      end
+
+      case action
+      when "serve" then MCP::Server.new.run
+      when "install" then install
+      when "uninstall" then uninstall
+      when "status" then status
+      else
+        raise OptionParser::InvalidArgument, "harnex mcp: unknown action #{action.inspect}; see harnex mcp --help"
+      end
+    end
+
+    private
+
+    def targets
+      chosen = %w[claude pi].select { |name| @argv.include?("--#{name}") }
+      chosen.empty? ? %w[claude pi] : chosen
+    end
+
+    def dry_run?
+      @argv.include?("--dry-run")
+    end
+
+    # The RubyGems wrapper next to this Ruby runs the newest installed harnex
+    # without depending on a version-manager shim or the client's cwd.
+    def server_command
+      wrapper = File.join(Gem.bindir, "harnex")
+      File.executable?(wrapper) ? wrapper : "harnex"
+    end
+
+    def install
+      targets.map { |target| send("install_#{target}") }.max
+    end
+
+    def uninstall
+      targets.map { |target| send("uninstall_#{target}") }.max
+    end
+
+    def install_claude
+      return skip("claude", "the claude CLI is not on PATH") unless which("claude")
+
+      command = ["claude", "mcp", "add", "--transport", "stdio", "--scope", "user", SERVER_NAME, "--", server_command, "mcp"]
+      if dry_run?
+        say("claude", "would run: #{command.join(' ')}")
+        return install_agent
+      end
+
+      Open3.capture3("claude", "mcp", "remove", SERVER_NAME, "--scope", "user")
+      out, status = Open3.capture2e(*command)
+      unless status.success?
+        @err.puts("harnex mcp: claude mcp add failed: #{out.strip}")
+        return 1
+      end
+
+      say("claude", "registered (user scope): #{server_command} mcp")
+      install_agent
+    end
+
+    # The `gpt` subagent relays a brief to a worker through these tools. A
+    # user's own agent of that name is never replaced.
+    def install_agent
+      return 0 if @argv.include?("--no-agent")
+
+      path = self.class.agent_path
+      return say("claude", "kept the existing gpt agent at #{path}") if File.exist?(path) || File.symlink?(path)
+      return say("claude", "would install the gpt agent at #{path}") if dry_run?
+
+      FileUtils.mkdir_p(File.dirname(path))
+      FileUtils.cp(AGENT_SOURCE, path)
+      say("claude", "installed the gpt agent at #{path} (Agent subagent_type \"gpt\")")
+    end
+
+    def uninstall_claude
+      return skip("claude", "the claude CLI is not on PATH") unless which("claude")
+
+      out, status = Open3.capture2e("claude", "mcp", "remove", SERVER_NAME, "--scope", "user")
+      say("claude", status.success? ? "removed" : "not registered (#{out.strip.lines.last.to_s.strip})")
+      path = self.class.agent_path
+      if File.file?(path) && !File.symlink?(path) && File.read(path) == File.read(AGENT_SOURCE)
+        FileUtils.rm_f(path)
+        say("claude", "removed the gpt agent harnex installed")
+      end
+      0
+    end
+
+    def install_pi
+      path = self.class.pi_config_path
+      return skip("pi", "#{File.dirname(path)} does not exist") unless File.directory?(File.dirname(path))
+
+      config = read_json(path)
+      config["mcpServers"] ||= {}
+      config["mcpServers"][SERVER_NAME] = {
+        "command" => server_command, "args" => ["mcp"], "exposure" => "direct", "timeout" => PI_TIMEOUT_SECONDS,
+        "description" => "Hand work to Pi workers (GPT models): ask, delegate, result, reply, land, discard, lanes"
+      }
+      return say("pi", "would write #{path}: #{JSON.generate(config['mcpServers'][SERVER_NAME])}") if dry_run?
+
+      Harnex.atomic_write_json(path, config)
+      say("pi", "registered in #{path} (exposure direct, timeout #{PI_TIMEOUT_SECONDS}s)")
+    end
+
+    def uninstall_pi
+      path = self.class.pi_config_path
+      config = read_json(path)
+      return say("pi", "not registered") unless config.dig("mcpServers", SERVER_NAME)
+
+      config["mcpServers"].delete(SERVER_NAME)
+      Harnex.atomic_write_json(path, config)
+      say("pi", "removed from #{path}")
+    end
+
+    def status
+      claude = if which("claude")
+                 out, ok = Open3.capture2e("claude", "mcp", "get", SERVER_NAME)
+                 ok.success? ? "registered: #{out.lines.grep(/Command|Args|Scope/i).map(&:strip).join('; ')}" : "not registered"
+               else
+                 "claude CLI not found"
+               end
+      pi = read_json(self.class.pi_config_path).dig("mcpServers", SERVER_NAME)
+      @out.puts "claude: #{claude}"
+      @out.puts "pi: #{pi ? "registered: #{pi['command']} #{Array(pi['args']).join(' ')} (exposure #{pi['exposure'] || 'codemode'})" : 'not registered'}"
+      0
+    end
+
+    def read_json(path)
+      JSON.parse(File.read(path))
+    rescue Errno::ENOENT
+      {}
+    end
+
+    def which(name)
+      ENV["PATH"].to_s.split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, name)) }
+    end
+
+    def say(target, text)
+      @out.puts "#{target}: #{text}"
+      0
+    end
+
+    def skip(target, reason)
+      @out.puts "#{target}: skipped (#{reason})"
+      0
+    end
+  end
+end