harnex 0.6.5 → 0.7.3

data/lib/harnex/codex/app_server/client.rb

@@ -0,0 +1,348 @@
+require "json"
+require "open3"
+
+module Harnex
+  module Codex
+    module AppServer
+      # Extracted from Adapters::CodexAppServer per issue #41 Slice A.
+      # Pure move; behavior unchanged.
+      class Client
+        attr_reader :pid
+
+        def initialize(read_io:, write_io:, pid: nil)
+          @read_io = read_io
+          @write_io = write_io
+          @pid = pid
+          @next_id = 1
+          @pending = {}
+          @id_mutex = Mutex.new
+          @write_mutex = Mutex.new
+          @notification_handler = nil
+          @request_handler = nil
+          @disconnect_handler = nil
+          @disconnect_signaled = false
+          @closed = false
+          @reader_thread = nil
+        end
+
+        def on_notification(&block)
+          @notification_handler = block
+        end
+
+        # Handler for server-initiated requests (id + method). The block
+        # receives (method, params) and returns the response body for the
+        # JSON-RPC `result` field, or nil to reject with -32601.
+        def on_request(&block)
+          @request_handler = block
+        end
+
+        def on_disconnect(&block)
+          @disconnect_handler = block
+        end
+
+        def start
+          @reader_thread = Thread.new { read_loop }
+        end
+
+        def request(method, params = {})
+          raise "codex_appserver client is closed" if @closed
+
+          queue = Queue.new
+          id = @id_mutex.synchronize do
+            assigned = @next_id
+            @next_id += 1
+            @pending[assigned] = queue
+            assigned
+          end
+
+          write_line({ jsonrpc: "2.0", id: id, method: method, params: params })
+          result = queue.pop
+          raise result if result.is_a?(Exception)
+
+          result
+        end
+
+        def notify(method, params = {})
+          return if @closed
+
+          write_line({ jsonrpc: "2.0", method: method, params: params })
+        end
+
+        def close
+          return if @closed
+
+          @closed = true
+
+          @id_mutex.synchronize do
+            @pending.each_value { |q| q.push(StandardError.new("codex_appserver client closed")) }
+            @pending.clear
+          end
+
+          begin
+            @write_io.close unless @write_io.closed?
+          rescue IOError
+            nil
+          end
+
+          if @pid && process_alive?(@pid)
+            sleep 0.05
+            begin
+              Process.kill("TERM", @pid)
+            rescue Errno::ESRCH
+              nil
+            end
+          end
+
+          @reader_thread&.join(2)
+        end
+
+        def terminate_process(term_grace_seconds:, kill_grace_seconds:)
+          return false unless @pid
+
+          begin
+            Process.kill("TERM", @pid)
+          rescue Errno::ESRCH
+            return true
+          end
+
+          return true if wait_for_process_exit(@pid, term_grace_seconds)
+
+          begin
+            Process.kill("KILL", @pid)
+          rescue Errno::ESRCH
+            return true
+          end
+
+          wait_for_process_exit(@pid, kill_grace_seconds)
+        end
+
+        # Plan 30 Phase 2 — deployment-fallback subprocess restart.
+        #
+        # Spawns a `codex app-server` subprocess against a deployment_config
+        # and wraps it in a fresh Client. Caller is responsible for wiring
+        # handlers and running the JSON-RPC handshake — or use
+        # `spawn_with_fallback` for the full restart-with-resume flow.
+        def self.spawn(deployment_config:)
+          command = deployment_config[:command] || deployment_config["command"]
+          raise ArgumentError, "deployment_config requires :command" if command.nil? || Array(command).empty?
+
+          env = deployment_config[:env] || deployment_config["env"] || {}
+          cwd = deployment_config[:cwd] || deployment_config["cwd"]
+
+          opts = {}
+          opts[:chdir] = cwd if cwd
+
+          stdin_io, stdout_io, _stderr_io, wait_thr = Open3.popen3(env, *Array(command), **opts)
+          new(read_io: stdout_io, write_io: stdin_io, pid: wait_thr.pid)
+        end
+
+        # Plan 30 Phase 2 — full subprocess restart for deployment fallback.
+        #
+        # Spawns a new subprocess against the alternate deployment, wires
+        # the supplied handlers, runs the initialize handshake, and resumes
+        # the prior threadId. Returns the started Client.
+        #
+        # Handlers are installed *before* the reader thread starts so no
+        # post-handshake notification is dropped.
+        def self.spawn_with_fallback(prior_thread_id:, deployment_config:, handshake_params:,
+                                      notification_handler: nil, request_handler: nil,
+                                      disconnect_handler: nil)
+          raise ArgumentError, "prior_thread_id required" if prior_thread_id.nil? || prior_thread_id.to_s.empty?
+
+          client = spawn(deployment_config: deployment_config)
+          client.on_notification(&notification_handler) if notification_handler
+          client.on_request(&request_handler) if request_handler
+          client.on_disconnect(&disconnect_handler) if disconnect_handler
+          client.start
+
+          begin
+            client.request("initialize", handshake_params)
+            client.notify("initialized", {})
+            client.request("thread/resume", { threadId: prior_thread_id })
+          rescue StandardError
+            client.close
+            raise
+          end
+
+          client
+        end
+
+        # Plan 30 Phase 2 — graceful stop ahead of a deployment switch.
+        #
+        # Best-effort: issues `turn/interrupt` for any in-flight turn
+        # (bounded by interrupt_grace_seconds), drains pending RPC, and
+        # tears the subprocess down with the same TERM/KILL escalation
+        # used by `terminate_process`.
+        def stop_for_fallback(in_flight_turn: nil,
+                              term_grace_seconds: 0.5,
+                              kill_grace_seconds: 1.0,
+                              interrupt_grace_seconds: 0.5)
+          if in_flight_turn && !@closed
+            interrupt_thread = Thread.new do
+              begin
+                request("turn/interrupt", in_flight_turn)
+              rescue StandardError
+                nil
+              end
+            end
+            interrupt_thread.kill unless interrupt_thread.join(interrupt_grace_seconds)
+          end
+
+          return true if @closed
+
+          @closed = true
+
+          fail_pending_requests(StandardError.new("codex_appserver client closed for fallback"))
+
+          begin
+            @write_io.close unless @write_io.closed?
+          rescue IOError
+            nil
+          end
+
+          terminated =
+            if @pid
+              terminate_process(
+                term_grace_seconds: term_grace_seconds,
+                kill_grace_seconds: kill_grace_seconds
+              )
+            else
+              true
+            end
+
+          @reader_thread&.join(2)
+          terminated
+        end
+
+        private
+
+        def write_line(message)
+          @write_mutex.synchronize do
+            @write_io.write(JSON.generate(message))
+            @write_io.write("\n")
+            @write_io.flush
+          end
+        rescue Errno::EPIPE, IOError
+          signal_disconnect(nil)
+        end
+
+        def read_loop
+          buffer = +""
+          loop do
+            chunk = @read_io.readpartial(4096)
+            buffer << chunk
+            while (idx = buffer.index("\n"))
+              line = buffer.slice!(0, idx + 1).chomp
+              next if line.strip.empty?
+
+              handle_line(line)
+            end
+          end
+        rescue EOFError, IOError, Errno::EIO
+          nil
+        ensure
+          signal_disconnect(nil)
+        end
+
+        def handle_line(line)
+          message = JSON.parse(line)
+        rescue JSON::ParserError => e
+          signal_disconnect(e)
+          return
+        else
+          dispatch_message(message)
+        end
+
+        def dispatch_message(message)
+          if message["id"] && message["method"]
+            handle_server_request(message)
+            return
+          end
+
+          if message.key?("id")
+            pending = @id_mutex.synchronize { @pending.delete(message["id"]) }
+            return unless pending
+
+            if message["error"]
+              err_msg = message.dig("error", "message") || "RPC error"
+              pending.push(StandardError.new("codex_appserver RPC error: #{err_msg}"))
+              signal_disconnect(message["error"])
+            else
+              pending.push(message["result"] || {})
+            end
+            return
+          end
+
+          @notification_handler&.call(message) if message["method"]
+        end
+
+        def handle_server_request(message)
+          result =
+            begin
+              @request_handler&.call(message["method"], message["params"] || {})
+            rescue StandardError
+              nil
+            end
+
+          if result.nil?
+            write_line({
+              jsonrpc: "2.0",
+              id: message["id"],
+              error: { code: -32601, message: "Unsupported server request: #{message['method']}" }
+            })
+          else
+            write_line({
+              jsonrpc: "2.0",
+              id: message["id"],
+              result: result
+            })
+          end
+        end
+
+        def signal_disconnect(error)
+          return if @disconnect_signaled
+
+          @disconnect_signaled = true
+          fail_pending_requests(error)
+          @disconnect_handler&.call(error)
+        end
+
+        def fail_pending_requests(error)
+          exception =
+            if error.is_a?(Exception)
+              error
+            else
+              message = error.is_a?(Hash) ? error["message"] : nil
+              StandardError.new(message.to_s.empty? ? "codex_appserver disconnected" : message.to_s)
+            end
+
+          @id_mutex.synchronize do
+            @pending.each_value { |queue| queue.push(exception) }
+            @pending.clear
+          end
+        end
+
+        def process_alive?(pid)
+          Process.kill(0, pid)
+          true
+        rescue Errno::ESRCH, Errno::EPERM
+          false
+        end
+
+        def wait_for_process_exit(pid, timeout_seconds)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds.to_f
+          loop do
+            return true unless process_alive?(pid)
+
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            break if remaining <= 0
+
+            sleep([0.05, remaining].min)
+          end
+
+          !process_alive?(pid)
+        end
+      end
+    end
+  end
+end

data/lib/harnex/commands/doctor.rb

@@ -1,4 +1,5 @@
 require "json"
+require "optparse"
 
 module Harnex
   class Doctor
@@ -6,29 +7,40 @@ module Harnex
 
     def self.usage
       <<~TEXT
-        Usage: harnex doctor
+        Usage: harnex doctor [--sweep]
 
         Runs preflight checks for harnex's adapter dependencies.
         Currently verifies that Codex CLI is installed and at version
         >= #{MIN_CODEX_VERSION} (required for the JSON-RPC `app-server`
         adapter).
 
+        Options:
+          --sweep      Include a read-only report of harnex/tmux session drift
+          -h, --help   Show this help
+
         Common patterns:
           harnex doctor
+          harnex doctor --sweep
           harnex doctor --help
 
         Gotchas:
           doctor validates local adapter prerequisites; it does not start sessions.
+          --sweep is diagnostic only; it does not stop sessions or remove files.
           Run it after installing or upgrading Codex CLI.
       TEXT
     end
 
     def initialize(argv = [])
       @argv = argv.dup
+      @options = {
+        sweep: false,
+        help: false
+      }
     end
 
     def run
-      if @argv.include?("-h") || @argv.include?("--help")
+      parser.parse!(@argv)
+      if @options[:help]
         puts self.class.usage
         return 0
       end
@@ -38,12 +50,21 @@ module Harnex
         ok: checks.all? { |c| c[:ok] },
         checks: checks
       }
+      summary[:sweep] = sweep_payload if @options[:sweep]
       puts JSON.generate(summary)
       summary[:ok] ? 0 : 1
     end
 
     private
 
+    def parser
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = "Usage: harnex doctor [--sweep]"
+        opts.on("--sweep", "Include read-only session drift diagnostics") { @options[:sweep] = true }
+        opts.on("-h", "--help", "Show help") { @options[:help] = true }
+      end
+    end
+
     def check_codex
       result = { name: "codex", required: ">= #{MIN_CODEX_VERSION}" }
 
@@ -75,6 +96,78 @@ module Harnex
       [e.message, nil]
     end
 
+    def sweep_payload
+      active, stale = read_session_registry
+      tmux_windows = read_tmux_windows
+      live_ids = active.map { |session| session["id"].to_s }.to_set
+
+      {
+        harnex_sessions: active,
+        tmux_windows_cx: tmux_windows,
+        orphan_tmux: tmux_windows.reject { |window| live_ids.include?(window[:session]) || live_ids.include?(window[:window]) },
+        stale_pid_files: stale
+      }
+    end
+
+    def read_session_registry
+      return [[], []] unless Dir.exist?(Harnex::SESSIONS_DIR)
+
+      active = []
+      stale = []
+
+      Dir.glob(File.join(Harnex::SESSIONS_DIR, "*.json")).sort.each do |path|
+        data = JSON.parse(File.read(path)).merge("registry_path" => path)
+        if data["pid"] && Harnex.alive_pid?(data["pid"])
+          active << data
+        else
+          stale << stale_session_files(data, path)
+        end
+      rescue JSON::ParserError
+        stale << { registry_path: path, error: "invalid_json" }
+      end
+
+      [active.sort_by { |session| [session["repo_root"].to_s, session["started_at"].to_s, session["id"].to_s] }.reverse, stale]
+    end
+
+    def stale_session_files(data, registry_path)
+      repo_root = data["repo_root"].to_s
+      id = data["id"].to_s
+      slug = repo_root.empty? || id.empty? ? nil : Harnex.session_file_slug(repo_root, id)
+      output_log_path = slug ? File.join(Harnex::STATE_DIR, "output", "#{slug}.log") : nil
+      events_log_path = slug ? File.join(Harnex::STATE_DIR, "events", "#{slug}.jsonl") : nil
+
+      {
+        id: id.empty? ? nil : id,
+        pid: data["pid"],
+        repo_root: repo_root.empty? ? nil : repo_root,
+        registry_path: registry_path,
+        output_log_path: file_or_nil(output_log_path),
+        events_log_path: file_or_nil(events_log_path)
+      }
+    end
+
+    def read_tmux_windows
+      output, status = capture("tmux list-windows -a -F '\#{session_name}\t\#{window_name}\t\#{pane_pid}'")
+      return [] unless status&.success?
+
+      output.lines.filter_map do |line|
+        session, window, pid = line.chomp.split("\t", 3)
+        next unless session.to_s.start_with?("cx-") || window.to_s.start_with?("cx-")
+
+        { session: session, window: window, pid: integer_or_nil(pid) }
+      end
+    end
+
+    def file_or_nil(path)
+      path if path && File.exist?(path)
+    end
+
+    def integer_or_nil(value)
+      Integer(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
     def parse_version(text)
       match = text.match(/(\d+\.\d+\.\d+)/)
       match ? Gem::Version.new(match[1]) : nil

data/lib/harnex/commands/history.rb

@@ -0,0 +1,149 @@
+require "json"
+require "optparse"
+require "time"
+
+module Harnex
+  class History
+    DEFAULT_LIMIT = 5
+
+    def self.usage(program_name = "harnex history")
+      <<~TEXT
+        Usage: #{program_name} [options]
+
+        Options:
+          --limit N   Number of records to show (default: #{DEFAULT_LIMIT})
+          --since DUR Only show records started within DUR (examples: 1h, 1d)
+          --id TEXT   Filter records whose id contains TEXT
+          --global    Read the global no-repo history file
+          --json      Output JSONL instead of a table
+          --all       Show all matching records
+          -h, --help  Show this help
+      TEXT
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+      @options = {
+        limit: DEFAULT_LIMIT,
+        since: nil,
+        id: nil,
+        global: false,
+        json: false,
+        all: false,
+        help: false
+      }
+    end
+
+    def run
+      parser.parse!(@argv)
+      if @options[:help]
+        puts self.class.usage
+        return 0
+      end
+
+      records = filtered_records
+      if @options[:json]
+        records.each { |record| puts JSON.generate(record) }
+      elsif !records.empty?
+        puts render_table(records)
+      end
+      0
+    end
+
+    private
+
+    def parser
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = "Usage: harnex history [options]"
+        opts.on("--limit N", Integer, "Number of records to show") do |value|
+          raise OptionParser::InvalidArgument, "--limit must be greater than 0" if value <= 0
+
+          @options[:limit] = value
+        end
+        opts.on("--since DUR", "Only show records started within DUR") { |value| @options[:since] = parse_since(value) }
+        opts.on("--id TEXT", "Filter records by id substring") { |value| @options[:id] = value.to_s }
+        opts.on("--global", "Read the global no-repo history file") { @options[:global] = true }
+        opts.on("--json", "Output JSONL") { @options[:json] = true }
+        opts.on("--all", "Show all matching records") { @options[:all] = true }
+        opts.on("-h", "--help", "Show help") { @options[:help] = true }
+      end
+    end
+
+    def parse_since(value)
+      Time.now - Harnex.parse_duration_seconds(value, option_name: "--since")
+    end
+
+    def filtered_records
+      records = load_records
+      records = records.select { |record| record["id"].to_s.include?(@options[:id]) } if @options[:id]
+      records = records.select { |record| started_after?(record, @options[:since]) } if @options[:since]
+      records = records.last(@options[:limit]) unless @options[:all]
+      records
+    end
+
+    def load_records
+      path = DispatchHistory.path_for(Dir.pwd, global: @options[:global])
+      return [] unless File.file?(path)
+
+      File.readlines(path, chomp: true).filter_map do |line|
+        next if line.strip.empty?
+
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    def started_after?(record, floor)
+      Time.iso8601(record.fetch("started_at")) >= floor
+    rescue KeyError, ArgumentError
+      false
+    end
+
+    def render_table(records)
+      columns = ["ID", "STARTED", "DURATION", "STATUS", "COMMIT", "TERMINAL", "TMUX"]
+      rows = records.map { |record| table_row(record) }
+      widths = columns.to_h { |column| [column, ([column.length] + rows.map { |row| row.fetch(column).length }).max] }
+
+      ([columns.to_h { |column| [column, column] }] + rows)
+        .map { |row| columns.map { |column| row.fetch(column).ljust(widths.fetch(column)) }.join("  ") }
+        .join("\n")
+    end
+
+    def table_row(record)
+      {
+        "ID" => record["id"].to_s,
+        "STARTED" => format_started(record["started_at"]),
+        "DURATION" => format_duration(record["duration_s"]),
+        "STATUS" => record["status"].to_s,
+        "COMMIT" => short_commit(record["commit_sha"]),
+        "TERMINAL" => record["terminal_event"].to_s,
+        "TMUX" => record["tmux_state"].to_s
+      }
+    end
+
+    def format_started(value)
+      Time.iso8601(value.to_s).getlocal.strftime("%Y-%m-%d %H:%M")
+    rescue ArgumentError
+      "-"
+    end
+
+    def format_duration(value)
+      seconds = Integer(value || 0)
+      hours = seconds / 3600
+      minutes = (seconds % 3600) / 60
+      rest = seconds % 60
+      return "#{hours}h#{minutes.to_s.rjust(2, '0')}m" if hours.positive?
+      return "#{minutes}m#{rest.to_s.rjust(2, '0')}s" if minutes.positive?
+
+      "#{rest}s"
+    rescue ArgumentError
+      "-"
+    end
+
+    def short_commit(value)
+      text = value.to_s
+      text.empty? ? "-" : text[0, 8]
+    end
+  end
+end