harnex 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b38fbca70a1ec608f414f362bb16bff85bdb5c279a5c562c4dc7048fa6acb41
-  data.tar.gz: 7a9048de3efb9461489ab0678683e0d245e60e2ac3a1dd7e617d868fce927a51
+  metadata.gz: 0003e780e17784a566b09e37d39ca760531d78ef8b912093944bb7f1eb65c134
+  data.tar.gz: 58f1ec4d5919c19a7b445900aff28143636a530470e7d04bf1962532661d308e
 SHA512:
-  metadata.gz: a222bd5df7a1e02e7b6cebb2e0a63649b4433baef17be35a3dd03b4128e9b406af52ae71e9c063a6912dbb9af04b187072a693271fb72f24e4d61de462a7bf1c
-  data.tar.gz: eb2ca6564d079b0e162e72e9d07d01239ba2ce0c5b118fbd4360671d555c452571b2c64cb0f5a4be3c0b23c13e57b606d7ca98632d345f7570d5c69caacc9ad8
+  metadata.gz: f979f0c86edf2ac6a694b20e75392ed23059a43a38ea4de7a3620c3270589d08bacd880e5c4ec660859b4430528bb8ae56b90399397010fdb87e06c9ac926847
+  data.tar.gz: f109e68a8165cef5627ffa5a2a0ca1afb8e8ace1809591bdefdce6a7e7e8259c2db5e8764bbf06ec191ef7197beef45653377f7e5f0742535ffe5402f28ce12d

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 0.6.0 — 2026-05-06
+
+### Architectural pivot: Codex on JSON-RPC
+
+harnex now speaks `codex app-server` JSON-RPC over stdio for the
+Codex adapter. Pane-scraping is retired for Codex. Closed by
+construction:
+
+- #22 (Codex side; `--watch --stall-after` still applies to
+  claude/generic)
+- #24 (disconnect detection — `error` notifications and JSON-RPC
+  error responses replace screen-text regex)
+- #25 (first-class completion signal — `turn/completed` is it)
+
+### New
+
+- `harnex wait --until task_complete` — block until a turn completes.
+  Example: `harnex wait --id cx-i-242 --until task_complete`.
+  Adapter-agnostic; tails the events JSONL.
+- `harnex status --json` includes `last_completed_at`, `model`,
+  `effort`, `auto_disconnects`.
+- `harnex doctor` preflight checks Codex CLI ≥ 0.128.0.
+- `Adapter#transport` and `Adapter#describe` extension points so
+  callers can introspect adapter contracts. Default is
+  `:pty` for backward compatibility.
+
+### Migration
+
+- Codex CLI ≥ 0.128.0 required.
+- Existing `harnex run codex ...` invocations work unchanged.
+- Emergency fallback: `harnex run codex --legacy-pty ...` (the
+  pre-0.6.0 PTY adapter). Deprecated; will be removed in 0.7.0.
+
+### Cross-repo
+
+- Resolves holm #201 from the harnex side. holm #271 (substrate v2
+  meta) tracks the broader pivot.

data/TECHNICAL.md

@@ -321,7 +321,25 @@ The adapter reads the screen and returns a state hash:
 | `confirmation`           | `false`       | Modal confirmation    |
 | `unknown`                | `nil`         | Can't determine       |
 
-### Codex Adapter
+### Codex Adapter (default — JSON-RPC `app-server`)
+
+- `transport :stdio_jsonrpc` — speaks JSON-RPC 2.0 over the
+  subprocess's stdin/stdout, one JSON object per line.
+- Launches `codex app-server` (Codex CLI ≥ 0.128.0; verify with
+  `harnex doctor`).
+- Notifications (`turn/started`, `turn/completed`, `item/completed`,
+  `error`, `thread/compacted`, …) fan into the events log.
+  `task_complete` is the harnex-side event for `turn/completed`.
+- Disconnect is detected from JSON-RPC error responses, subprocess
+  EOF, parse errors, or a server `error` notification — no screen
+  regex required.
+- Synthesized transcript: `item/completed` text payloads stream to
+  both the output log and STDOUT so tmux/pane workflows continue to
+  work without a real PTY.
+- See `docs/codex-appserver.md` for the full mapping table and
+  troubleshooting.
+
+#### Codex Adapter (legacy PTY — `--legacy-pty`, removal in 0.7.0)
 
 - Launches with `--no-alt-screen` for inline screen output
 - Detects prompt by looking for `›` prefix in recent lines

data/lib/harnex/adapters/base.rb

@@ -20,6 +20,16 @@ module Harnex
         @extra_args = extra_args.dup
       end
 
+      # Default transport. Adapters speaking JSON-RPC override to
+      # :stdio_jsonrpc; Session#run uses this to pick the I/O path.
+      def transport
+        :pty
+      end
+
+      def describe
+        { transport: transport }
+      end
+
       def build_command
         base_command + @extra_args
       end

data/lib/harnex/adapters/codex_appserver.rb

@@ -0,0 +1,390 @@
+require "json"
+require "open3"
+
+module Harnex
+  module Adapters
+    # Codex `app-server` adapter — JSON-RPC over stdio.
+    #
+    # Talks to a spawned `codex app-server` subprocess by writing
+    # newline-delimited JSON-RPC messages on stdin and reading
+    # responses + notifications from stdout. Replaces the pane-scraping
+    # heuristics in `Adapters::Codex` (legacy, kept behind --legacy-pty).
+    class CodexAppServer < Base
+      CLIENT_TITLE = "harnex"
+      CLIENT_NAME = "harnex"
+
+      OPT_OUT_NOTIFICATIONS = %w[
+        item/agentMessage/delta
+        item/reasoning/summaryTextDelta
+        item/reasoning/summaryPartAdded
+        item/reasoning/textDelta
+      ].freeze
+
+      REQUEST_METHODS = %w[
+        initialize thread/start turn/start turn/interrupt thread/resume
+      ].freeze
+
+      NOTIFICATION_METHODS = %w[
+        thread/started turn/started turn/completed
+        item/started item/completed
+        thread/status/changed thread/tokenUsage/updated
+        thread/compacted account/rateLimits/updated
+        error
+      ].freeze
+
+      EVENTS = %w[task_complete turn_started item_completed disconnected].freeze
+
+      attr_reader :thread_id, :current_turn_id, :last_completed_at
+
+      def initialize(extra_args = [])
+        super("codex", extra_args)
+        @client = nil
+        @thread_id = nil
+        @current_turn_id = nil
+        @state = :disconnected
+        @last_completed_at = nil
+        @notification_handler = nil
+        @disconnect_handler = nil
+      end
+
+      def transport
+        :stdio_jsonrpc
+      end
+
+      def base_command
+        ["codex", "app-server"]
+      end
+
+      def describe
+        {
+          transport: transport,
+          request_methods: REQUEST_METHODS,
+          notification_methods: NOTIFICATION_METHODS,
+          events: EVENTS
+        }
+      end
+
+      def state
+        @state
+      end
+
+      # Override: state is RPC-driven, screen text is ignored.
+      def input_state(_screen_text = nil)
+        {
+          state: @state.to_s,
+          input_ready: @state == :prompt
+        }
+      end
+
+      # The screen-based send path is not used for stdio_jsonrpc.
+      # Session#run_jsonrpc routes through #dispatch instead.
+      def build_send_payload(*)
+        raise NotImplementedError, "codex_appserver uses #dispatch, not screen-based send"
+      end
+
+      # No-op: closing the subprocess is handled via #close.
+      def inject_exit(_writer, **_kwargs)
+        nil
+      end
+
+      def on_notification(&block)
+        @notification_handler = block
+      end
+
+      def on_disconnect(&block)
+        @disconnect_handler = block
+      end
+
+      # Start the JSON-RPC client. In production, spawns the codex
+      # subprocess. In tests, callers may pass pre-built IO objects.
+      def start_rpc(env: nil, cwd: nil, read_io: nil, write_io: nil, pid: nil)
+        if read_io && write_io
+          @client = JsonRpcClient.new(read_io: read_io, write_io: write_io, pid: pid)
+        else
+          spawn_pid, child_stdin, child_stdout = spawn_subprocess(env, cwd)
+          @client = JsonRpcClient.new(read_io: child_stdout, write_io: child_stdin, pid: spawn_pid)
+        end
+
+        @client.on_notification { |msg| handle_notification(msg) }
+        @client.on_disconnect { |err| handle_disconnect(err) }
+        @client.start
+        perform_handshake
+        @state = :prompt
+        self
+      end
+
+      def dispatch(prompt:, model: nil, effort: nil)
+        ensure_open!
+        ensure_thread!
+        params = {
+          threadId: @thread_id,
+          input: { content: [{ type: "text", text: prompt.to_s }] }
+        }
+        params[:model] = model if model
+        params[:effort] = effort if effort
+
+        result = @client.request("turn/start", params)
+        @current_turn_id = result["turnId"] || result["turn_id"] || result["id"]
+        @state = :busy
+        @current_turn_id
+      end
+
+      def interrupt(turn_id: nil)
+        ensure_open!
+        target = turn_id || @current_turn_id
+        return nil if target.nil?
+
+        @client.request("turn/interrupt", { threadId: @thread_id, turnId: target })
+      end
+
+      def resume(thread_id:)
+        ensure_open!
+        result = @client.request("thread/resume", { threadId: thread_id })
+        @thread_id = thread_id
+        @state = :prompt
+        result
+      end
+
+      def close
+        return unless @client
+
+        @client.close
+        @client = nil
+        @state = :disconnected
+      end
+
+      def pid
+        @client&.pid
+      end
+
+      private
+
+      def ensure_open!
+        raise "codex_appserver: client not started" unless @client
+        raise "codex_appserver: disconnected" if @state == :disconnected
+      end
+
+      def ensure_thread!
+        return if @thread_id
+
+        result = @client.request("thread/start", {})
+        @thread_id = result["threadId"] || result["thread_id"]
+      end
+
+      def perform_handshake
+        @client.request("initialize", {
+          clientInfo: {
+            title: CLIENT_TITLE,
+            name: CLIENT_NAME,
+            version: Harnex::VERSION
+          },
+          capabilities: {
+            experimentalApi: false,
+            optOutNotificationMethods: OPT_OUT_NOTIFICATIONS
+          }
+        })
+        @client.notify("initialized", {})
+      end
+
+      def handle_notification(message)
+        method = message["method"]
+        params = message["params"] || {}
+
+        case method
+        when "thread/started"
+          @thread_id ||= params["threadId"] || params["thread_id"]
+        when "turn/started"
+          @current_turn_id = params["turnId"] || params["turn_id"]
+          @state = :busy
+        when "turn/completed"
+          @last_completed_at = Time.now
+          @current_turn_id = nil
+          @state = :prompt
+        when "error"
+          @state = :disconnected
+        end
+
+        @notification_handler&.call(message)
+      end
+
+      def handle_disconnect(error)
+        @state = :disconnected
+        @disconnect_handler&.call(error)
+      end
+
+      def spawn_subprocess(env, cwd)
+        spawn_env = env || {}
+        opts = {}
+        opts[:chdir] = cwd if cwd
+        stdin_io, stdout_io, _stderr_io, wait_thr =
+          Open3.popen3(spawn_env, *build_command, **opts)
+        [wait_thr.pid, stdin_io, stdout_io]
+      end
+
+      # Minimal JSON-RPC 2.0 client. One JSON object per line.
+      # Responses keyed by id; everything else is a notification.
+      class JsonRpcClient
+        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
+          @disconnect_handler = nil
+          @disconnect_signaled = false
+          @closed = false
+          @reader_thread = nil
+        end
+
+        def on_notification(&block)
+          @notification_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
+
+        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"]
+            write_line({
+              jsonrpc: "2.0",
+              id: message["id"],
+              error: { code: -32601, message: "Unsupported server request: #{message['method']}" }
+            })
+            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 signal_disconnect(error)
+          return if @disconnect_signaled
+
+          @disconnect_signaled = true
+          @disconnect_handler&.call(error)
+        end
+
+        def process_alive?(pid)
+          Process.kill(0, pid)
+          true
+        rescue Errno::ESRCH, Errno::EPERM
+          false
+        end
+      end
+    end
+  end
+end

data/lib/harnex/adapters.rb

@@ -1,6 +1,7 @@
 require_relative "adapters/base"
 require_relative "adapters/generic"
 require_relative "adapters/codex"
+require_relative "adapters/codex_appserver"
 require_relative "adapters/claude"
 
 module Harnex
@@ -15,11 +16,23 @@ module Harnex
       !key.to_s.strip.empty?
     end
 
-    def build(key, extra_args = [])
-      adapter_class = registry[key.to_s]
+    # Phase 3 flipped the default — `codex` resolves to CodexAppServer.
+    # Legacy PTY adapter is reachable via `legacy_pty: true` (driven by
+    # `harnex run codex --legacy-pty`). Will be removed in 0.7.0.
+    def codex_appserver_enabled?
+      true
+    end
+
+    def build(key, extra_args = [], legacy_pty: false)
+      key_str = key.to_s
+      if key_str == "codex"
+        return legacy_pty ? Codex.new(extra_args) : CodexAppServer.new(extra_args)
+      end
+
+      adapter_class = registry[key_str]
       return adapter_class.new(extra_args) if adapter_class
 
-      Generic.new(key.to_s, extra_args)
+      Generic.new(key_str, extra_args)
     end
 
     def registry

data/lib/harnex/cli.rb

@@ -31,6 +31,8 @@ module Harnex
         Guide.new.run
       when "skills"
         Skills.new(@argv.drop(1)).run
+      when "doctor"
+        Doctor.new(@argv.drop(1)).run
       when "help"
         puts help(@argv[1])
         0
@@ -101,6 +103,7 @@ module Harnex
           recipes List and read workflow recipes
           guide   Show the getting started guide
           skills  Install bundled skills into a repo or globally
+          doctor  Run preflight checks for adapter dependencies
           help    Show command help
 
         New to harnex? Start with: harnex guide

data/lib/harnex/commands/doctor.rb

@@ -0,0 +1,75 @@
+require "json"
+
+module Harnex
+  class Doctor
+    MIN_CODEX_VERSION = Gem::Version.new("0.128.0")
+
+    def self.usage
+      <<~TEXT
+        Usage: harnex doctor
+
+        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).
+      TEXT
+    end
+
+    def initialize(argv = [])
+      @argv = argv.dup
+    end
+
+    def run
+      if @argv.include?("-h") || @argv.include?("--help")
+        puts self.class.usage
+        return 0
+      end
+
+      checks = [check_codex]
+      summary = {
+        ok: checks.all? { |c| c[:ok] },
+        checks: checks
+      }
+      puts JSON.generate(summary)
+      summary[:ok] ? 0 : 1
+    end
+
+    private
+
+    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 capture(command)
+      output = `#{command} 2>&1`
+      [output, $?]
+    rescue StandardError => e
+      [e.message, nil]
+    end
+
+    def parse_version(text)
+      match = text.match(/(\d+\.\d+\.\d+)/)
+      match ? Gem::Version.new(match[1]) : nil
+    end
+  end
+end

data/lib/harnex/commands/run.rb

@@ -8,7 +8,7 @@ module Harnex
     KNOWN_FLAGS = %w[
       --id --description --detach --tmux --host --port --watch --watch-file
       --stall-after --max-resumes --preset --context --meta --summary-out
-      --timeout --inbox-ttl --help
+      --timeout --inbox-ttl --legacy-pty --help
     ].freeze
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
@@ -36,6 +36,9 @@ module Harnex
           --summary-out PATH Append dispatch telemetry summary JSONL to PATH
           --timeout SECS     Max seconds to wait for detached registration (default: #{DEFAULT_TIMEOUT})
           --inbox-ttl SECS   Expire queued inbox messages after SECS (default: #{Inbox::DEFAULT_TTL})
+          --legacy-pty       (codex only) Use the legacy PTY adapter instead of
+                             the JSON-RPC `app-server` adapter. Deprecated; will
+                             be removed in 0.7.0.
           -h, --help         Show this help
 
         Notes:
@@ -70,6 +73,7 @@ module Harnex
         tmux_name: nil,
         timeout: DEFAULT_TIMEOUT,
         inbox_ttl: default_inbox_ttl,
+        legacy_pty: false,
         help: false
       }
     end
@@ -88,7 +92,7 @@ module Harnex
       @options[:id] ||= Harnex.generate_id(repo_root)
       validate_unique_id!(repo_root)
       effective_child_args = apply_context(child_args)
-      adapter = Harnex.build_adapter(cli_name, effective_child_args)
+      adapter = Harnex.build_adapter(cli_name, effective_child_args, legacy_pty: @options[:legacy_pty])
       @options[:detach] = true if @options[:tmux]
       validate_watch_mode!
       resolve_watch_preset!
@@ -146,6 +150,7 @@ module Harnex
       tmux_cmd += ["--meta", JSON.generate(@options[:meta])] if @options[:meta]
       tmux_cmd += ["--summary-out", @options[:summary_out]] if @options[:summary_out]
       tmux_cmd += ["--inbox-ttl", @options[:inbox_ttl].to_s]
+      tmux_cmd += ["--legacy-pty"] if @options[:legacy_pty]
       tmux_cmd += ["--"] + child_args unless child_args.empty?
 
       window_name = @options[:tmux_name] || @options[:id]
@@ -254,7 +259,7 @@ module Harnex
     end
 
     def adapter_repo_path(cli_name, child_args)
-      Harnex.build_adapter(cli_name, child_args).infer_repo_path(child_args)
+      Harnex.build_adapter(cli_name, child_args, legacy_pty: @options[:legacy_pty]).infer_repo_path(child_args)
     end
 
     def apply_context(child_args)
@@ -415,6 +420,8 @@ module Harnex
           @options[:inbox_ttl] = Float(required_option_value(arg, argv[index]))
         when /\A--inbox-ttl=(.+)\z/
           @options[:inbox_ttl] = Float(required_option_value("--inbox-ttl", Regexp.last_match(1)))
+        when "--legacy-pty"
+          @options[:legacy_pty] = true
         else
           if cli_name.nil?
             cli_name = arg
@@ -454,7 +461,7 @@ module Harnex
         case arg
         when "--"
           return false
-        when "-h", "--help", "--detach", "--tmux"
+        when "-h", "--help", "--detach", "--tmux", "--legacy-pty"
           nil
         when /\A--tmux=/
           nil

data/lib/harnex/commands/wait.rb

@@ -7,14 +7,20 @@ module Harnex
   class Waiter
     POLL_INTERVAL = 0.5
 
+    EVENT_PREDICATES = %w[task_complete].freeze
+
     def self.usage(program_name = "harnex wait")
       <<~TEXT
         Usage: #{program_name} [options]
 
         Options:
           --id ID         Session ID to wait for (required)
-          --until STATE   Wait until session reaches STATE (e.g. "prompt")
-                          Without --until, waits for session exit (default)
+          --until STATE   Wait until session reaches STATE. Supported:
+                            task_complete   (events JSONL — fires on
+                                             turn/completed; adapter-agnostic)
+                            <other>         (agent_state HTTP poll, e.g.
+                                             "prompt", "busy")
+                          Without --until, waits for session exit (default).
           --repo PATH     Resolve session using PATH's repo root (default: current repo)
           --timeout SECS  Maximum time to wait in seconds (default: unlimited)
           -h, --help      Show this help
@@ -42,7 +48,11 @@ module Harnex
       raise "--id is required for harnex wait" unless @options[:id]
 
       if @options[:until_state]
-        wait_until_state
+        if EVENT_PREDICATES.include?(@options[:until_state])
+          wait_until_event(@options[:until_state])
+        else
+          wait_until_state
+        end
       else
         wait_until_exit
       end
@@ -50,6 +60,102 @@ module Harnex
 
     private
 
+    def wait_until_event(predicate)
+      repo_root = Harnex.resolve_repo_root(@options[:repo_path])
+      events_path = Harnex.events_log_path(repo_root, @options[:id])
+      registry = Harnex.read_registry(repo_root, @options[:id])
+      start_time = Time.now
+      deadline = @options[:timeout] ? start_time + @options[:timeout] : nil
+
+      unless registry || File.exist?(events_path)
+        warn("harnex wait: no session found with id #{@options[:id].inspect}")
+        return 1
+      end
+
+      offset = 0
+      task_complete_seen = false
+
+      # Replay existing events first — we may already be past the predicate.
+      if File.exist?(events_path)
+        File.open(events_path, "r") do |f|
+          f.each_line do |line|
+            offset = f.pos
+            event = parse_event(line)
+            next unless event
+            task_complete_seen = true if event["type"] == "task_complete"
+            if matches?(event, predicate, task_complete_seen)
+              return emit_event_match(event, start_time)
+            end
+          end
+        end
+      end
+
+      target_pid = registry && registry["pid"]
+
+      loop do
+        if target_pid && !Harnex.alive_pid?(target_pid)
+          waited = (Time.now - start_time).round(1)
+          puts JSON.generate(ok: false, id: @options[:id], state: "exited", waited_seconds: waited)
+          return 1
+        end
+
+        if deadline && Time.now >= deadline
+          waited = (Time.now - start_time).round(1)
+          puts JSON.generate(ok: false, id: @options[:id], status: "timeout", waited_seconds: waited)
+          return 124
+        end
+
+        if File.exist?(events_path) && File.size(events_path) > offset
+          File.open(events_path, "r") do |f|
+            f.seek(offset)
+            f.each_line do |line|
+              event = parse_event(line)
+              next unless event
+              task_complete_seen = true if event["type"] == "task_complete"
+              if matches?(event, predicate, task_complete_seen)
+                offset = f.pos
+                return emit_event_match(event, start_time)
+              end
+            end
+            offset = f.pos
+          end
+        end
+
+        sleep 0.1
+      end
+    end
+
+    def parse_event(line)
+      JSON.parse(line)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def matches?(event, predicate, task_complete_seen)
+      type = event["type"]
+      case predicate
+      when "task_complete"
+        type == "task_complete"
+      when "prompt"
+        type == "task_complete" ||
+          (task_complete_seen && type == "agent_state" && event["state"] == "prompt")
+      else
+        false
+      end
+    end
+
+    def emit_event_match(event, start_time)
+      waited = (Time.now - start_time).round(1)
+      puts JSON.generate(
+        ok: true,
+        id: @options[:id],
+        event: event["type"],
+        seq: event["seq"],
+        waited_seconds: waited
+      )
+      0
+    end
+
     def wait_until_state
       repo_root = Harnex.resolve_repo_root(@options[:repo_path])
       target_state = @options[:until_state]

data/lib/harnex/core.rb

@@ -349,10 +349,10 @@ module Harnex
     false
   end
 
-  def build_adapter(cli, argv)
+  def build_adapter(cli, argv, legacy_pty: false)
     raise ArgumentError, "cli is required" if cli.to_s.strip.empty?
 
-    Adapters.build(cli, argv)
+    Adapters.build(cli, argv, legacy_pty: legacy_pty)
   end
 
   def session_cli(session)

data/lib/harnex/runtime/session.rb

@@ -25,7 +25,7 @@ module Harnex
           @counts[:stalls] += 1
         when "resume"
           @counts[:force_resumes] += 1
-        when "disconnect", "disconnection"
+        when "disconnect", "disconnection", "disconnected"
           @counts[:disconnections] += 1
         when "compaction"
           @counts[:compactions] += 1
@@ -74,6 +74,7 @@ module Harnex
       @usage_summary = {}
       @ended_at = nil
       @exit_reason = nil
+      @last_completed_at = nil
       @writer = nil
       @pid = nil
       @term_signal = nil
@@ -105,6 +106,13 @@ module Harnex
       validate_binary! if validate_binary
       prepare_output_log
       prepare_events_log
+
+      return run_jsonrpc if adapter.transport == :stdio_jsonrpc
+
+      run_pty
+    end
+
+    def run_pty
       @reader, @writer, @pid = PTY.spawn(child_env, *command)
       @writer.sync = true
       emit_started_event
@@ -179,6 +187,10 @@ module Harnex
       payload[:input_state] = adapter.input_state(screen_snapshot) if include_input_state
       payload[:agent_state] = @state_machine.to_s
       payload[:inbox] = @inbox.stats
+      payload[:last_completed_at] = @last_completed_at&.iso8601
+      payload[:model] = meta_hash["model"]
+      payload[:effort] = meta_hash["effort"]
+      payload[:auto_disconnects] = @event_counters.snapshot[:disconnections]
       payload
     end
 
@@ -193,6 +205,18 @@ module Harnex
     end
 
     def inject_stop
+      if adapter.transport == :stdio_jsonrpc
+        @inject_mutex.synchronize do
+          begin
+            adapter.interrupt
+          rescue StandardError
+            nil
+          end
+          @state_machine.force_busy!
+        end
+        return { ok: true, signal: "interrupt_sent" }
+      end
+
       raise "session is not running" unless pid && Harnex.alive_pid?(pid)
 
       @inject_mutex.synchronize do
@@ -204,6 +228,10 @@ module Harnex
     end
 
     def inject_via_adapter(text:, submit:, enter_only:, force: false)
+      if adapter.transport == :stdio_jsonrpc
+        return inject_via_jsonrpc(text: text, force: force)
+      end
+
       snapshot = adapter.wait_for_sendable(method(:screen_snapshot), submit: submit, enter_only: enter_only, force: force)
       payload = adapter.build_send_payload(
         text: text,
@@ -228,8 +256,32 @@ module Harnex
         .tap { emit_send_event(text, force: payload[:force]) }
     end
 
+    def inject_via_jsonrpc(text:, force: false)
+      turn_id = nil
+      @inject_mutex.synchronize do
+        turn_id = adapter.dispatch(prompt: text)
+        @state_machine.force_busy!
+        @injected_count += 1
+        @last_injected_at = Time.now
+        persist_registry
+      end
+
+      emit_send_event(text, force: force)
+      {
+        ok: true,
+        cli: adapter.key,
+        bytes_written: text.to_s.bytesize,
+        injected_count: @injected_count,
+        newline: false,
+        input_state: adapter.input_state(nil),
+        force: force,
+        turn_id: turn_id
+      }
+    end
+
     def sync_window_size
       return unless STDIN.tty?
+      return unless @writer
 
       @writer.winsize = STDIN.winsize
     rescue StandardError
@@ -242,6 +294,154 @@ module Harnex
 
     private
 
+    def run_jsonrpc
+      adapter.on_notification { |msg| handle_rpc_notification(msg) }
+      adapter.on_disconnect { |err| handle_rpc_disconnect(err) }
+
+      adapter.start_rpc(env: child_env, cwd: repo_root)
+      @pid = adapter.pid
+      emit_started_event
+      emit_git_start_event
+
+      install_signal_handlers
+      @server = ApiServer.new(self)
+      @server.start
+      persist_registry
+
+      watch_thread = start_watch_thread
+      @inbox.start
+
+      if @pid
+        begin
+          _, status = Process.wait2(@pid)
+          @term_signal = status.signaled? ? status.termsig : nil
+          @exit_code = status.exited? ? status.exitstatus : 128 + status.termsig
+        rescue Errno::ECHILD
+          @exit_code = 0
+        end
+      else
+        @rpc_done_lock = Mutex.new
+        @rpc_done_cond = ConditionVariable.new
+        @rpc_done_lock.synchronize { @rpc_done_cond.wait(@rpc_done_lock) until @rpc_done }
+        @exit_code = 0
+      end
+      @ended_at = Time.now
+
+      emit_session_end_telemetry
+      @exit_reason = classify_exit
+      summary_record = build_summary_record
+      append_summary_record(summary_record)
+      emit_summary_event
+      emit_exit_event
+      watch_thread&.kill
+      @exit_code
+    ensure
+      @inbox.stop
+      @server&.stop
+      begin
+        adapter.close
+      rescue StandardError
+        nil
+      end
+      persist_exit_status
+      cleanup_registry
+      @output_log&.close unless @output_log&.closed?
+      @events_log&.close unless @events_log&.closed?
+    end
+
+    def signal_rpc_done!
+      @rpc_done = true
+      if defined?(@rpc_done_lock) && @rpc_done_lock
+        @rpc_done_lock.synchronize { @rpc_done_cond&.signal }
+      end
+    end
+
+    def handle_rpc_notification(message)
+      method = message["method"]
+      params = message["params"] || {}
+
+      case method
+      when "thread/started"
+        @rpc_thread_id = params["threadId"] || params["thread_id"]
+      when "turn/started"
+        emit_event("turn_started", turnId: params["turnId"] || params["turn_id"])
+      when "turn/completed"
+        @last_completed_at = Time.now
+        payload = { turnId: params["turnId"] || params["turn_id"] }
+        payload[:status] = params["status"] if params["status"]
+        payload[:tokenUsage] = params["tokenUsage"] if params["tokenUsage"]
+        emit_event("task_complete", **payload)
+      when "item/completed"
+        emit_event("item_completed", item: params["item"])
+        text = render_item_text(params["item"])
+        record_synthesized(text) if text
+      when "thread/compacted"
+        emit_event("compaction", **params)
+      when "thread/tokenUsage/updated"
+        # Surfaced via status fields in Phase 4; no event spam.
+        @token_usage = params["usage"] || params
+      when "thread/status/changed"
+        # State machine reflects RPC state; no event needed.
+        nil
+      when "account/rateLimits/updated"
+        @rate_limits = params
+      when "error"
+        emit_event("disconnected", source: "error_notification", message: params["message"])
+        signal_rpc_done!
+      end
+    rescue StandardError => e
+      warn("harnex: rpc notification handler error: #{e.message}")
+    end
+
+    def handle_rpc_disconnect(error)
+      msg = error.is_a?(Hash) ? error["message"] : error&.message
+      emit_event("disconnected", source: "transport", message: msg) rescue nil
+      signal_rpc_done!
+    end
+
+    def render_item_text(item)
+      return nil unless item.is_a?(Hash)
+
+      type = item["type"] || item["kind"]
+      case type
+      when "agent_message", "assistant_message"
+        item["text"] || item.dig("message", "text")
+      when "tool_call"
+        name = item["name"] || item.dig("tool", "name") || "tool"
+        params = item["params"] || item["arguments"]
+        "tool: #{name}#{params ? " #{summarize(params)}" : ""}"
+      else
+        item["text"]
+      end
+    end
+
+    def summarize(value)
+      str = value.is_a?(String) ? value : JSON.generate(value)
+      str.length > 120 ? "#{str[0, 117]}..." : str
+    rescue StandardError
+      ""
+    end
+
+    def record_synthesized(text)
+      return if text.nil? || text.to_s.empty?
+
+      payload = text.to_s.dup
+      payload << "\n" unless payload.end_with?("\n")
+      bytes = payload.b
+      @mutex.synchronize do
+        append_output_log(bytes)
+        @output_buffer << bytes
+        overflow = @output_buffer.bytesize - OUTPUT_BUFFER_LIMIT
+        @output_buffer = @output_buffer.byteslice(overflow, OUTPUT_BUFFER_LIMIT) if overflow.positive?
+      end
+      begin
+        STDOUT.write(payload)
+        STDOUT.flush
+      rescue StandardError
+        nil
+      end
+    end
+
     def child_env
       env = {
         "HARNEX_SESSION_ID" => session_id,

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.5.0"
-  RELEASE_DATE = "2026-05-01"
+  VERSION = "0.6.0"
+  RELEASE_DATE = "2026-05-06"
 end

data/lib/harnex.rb

@@ -25,4 +25,5 @@ require_relative "harnex/commands/pane"
 require_relative "harnex/commands/recipes"
 require_relative "harnex/commands/guide"
 require_relative "harnex/commands/skills"
+require_relative "harnex/commands/doctor"
 require_relative "harnex/cli"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-01 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies: []
 description: A local PTY harness that wraps terminal AI agents (Claude, Codex) and
   adds a control plane for discovery, messaging, and coordination.
@@ -19,6 +19,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - GUIDE.md
 - LICENSE
 - README.md
@@ -30,8 +31,10 @@ files:
 - lib/harnex/adapters/base.rb
 - lib/harnex/adapters/claude.rb
 - lib/harnex/adapters/codex.rb
+- lib/harnex/adapters/codex_appserver.rb
 - lib/harnex/adapters/generic.rb
 - lib/harnex/cli.rb
+- lib/harnex/commands/doctor.rb
 - lib/harnex/commands/events.rb
 - lib/harnex/commands/guide.rb
 - lib/harnex/commands/logs.rb