harnex 0.5.0 → 0.6.2

data/lib/harnex/commands/guide.rb

@@ -7,6 +7,15 @@ module Harnex
         Usage: harnex guide
 
         Print the getting started guide.
+
+        Common patterns:
+          harnex guide
+          harnex agents-guide
+          harnex recipes
+
+        Gotchas:
+          guide is short human onboarding.
+          agents-guide is the deeper operational reference for dispatching agents.
       TEXT
     end
 

data/lib/harnex/commands/logs.rb

@@ -17,6 +17,16 @@ module Harnex
           --follow      Keep streaming appended output until session exit
           --lines N     Print the last N lines before following (default: #{DEFAULT_LINES})
           -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
+
+        Gotchas:
+          logs reads the persisted transcript, not the live tmux screen.
+          Use pane when you need the current TUI view or prompt text.
+          --follow streams until the live session exits.
       TEXT
     end
 

data/lib/harnex/commands/pane.rb

@@ -20,6 +20,16 @@ module Harnex
           --interval N  Refresh interval in seconds for --follow (default: #{FOLLOW_INTERVAL.to_i})
           --json        Output JSON with capture metadata
           -h, --help    Show this help
+
+        Common patterns:
+          #{program_name} --id cx-i-42 --lines 40
+          #{program_name} --id cx-i-42 --lines 40 --json
+          #{program_name} --id cx-i-42 --follow --interval 2
+
+        Gotchas:
+          pane requires a tmux-backed session.
+          Use --repo when the same ID exists in multiple repos or worktrees.
+          Do not use pane state alone as completion proof; verify artifacts/tests.
       TEXT
     end
 

data/lib/harnex/commands/recipes.rb

@@ -17,6 +17,15 @@ module Harnex
           harnex recipes list
           harnex recipes show 01
           harnex recipes show fire_and_watch
+
+        Common patterns:
+          harnex recipes show 01   # Fire and Watch
+          harnex recipes show 02   # Chain Implement
+          harnex recipes show 03   # Buddy
+
+        Gotchas:
+          Recipes are compact command walkthroughs.
+          Use `harnex agents-guide` for the deeper agent-facing guide.
       TEXT
     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:
@@ -45,6 +48,17 @@ module Harnex
           CLIs with smart prompt detection: #{Adapters.known.join(', ')}
           Any other CLI name is launched with generic wrapping.
           Wrapper options may appear before or after <cli>.
+
+        Common patterns:
+          #{program_name} codex --id cx-i-42 --tmux cx-i-42 --context "Read /tmp/task-impl-42.md"
+          #{program_name} codex --id cx-i-42 --watch --preset impl --context "Read /tmp/task-impl-42.md"
+          #{program_name} claude --id cl-r-42 --tmux cl-r-42 --description "Review task 42"
+
+        Gotchas:
+          Always pair --id and --tmux with the same value for delegated work.
+          Passing --tmux without --id creates a random harnex session ID.
+          --watch is foreground-only; do not combine it with --tmux or --detach.
+          Use -- before child CLI flags when a flag could be parsed by harnex.
       TEXT
     end
 
@@ -70,6 +84,7 @@ module Harnex
         tmux_name: nil,
         timeout: DEFAULT_TIMEOUT,
         inbox_ttl: default_inbox_ttl,
+        legacy_pty: false,
         help: false
       }
     end
@@ -88,7 +103,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 +161,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 +270,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 +431,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 +472,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/send.rb

@@ -38,7 +38,19 @@ module Harnex
     end
 
     def self.usage(program_name = "harnex send")
-      build_parser({}, program_name).to_s
+      <<~TEXT
+        #{build_parser({}, program_name)}
+        Common patterns:
+          #{program_name} --id cx-i-42 --message "Read /tmp/task-impl-42.md" --wait-for-idle --timeout 900
+          #{program_name} --id cx-i-42 --message "Continue with the current task." --force
+          #{program_name} --id "$HARNEX_ID" --message "Worker finished; tests passed."
+
+        Gotchas:
+          --wait-for-idle is a turn fence, not proof that the whole task is done.
+          Use --no-wait for fire-and-forget delivery only when another monitor owns completion.
+          Long prompts are more reliable when written to a file and referenced by path.
+          Messages between harnex sessions get relay headers unless --no-relay is used.
+      TEXT
     end
 
     def initialize(argv)

data/lib/harnex/commands/status.rb

@@ -19,6 +19,16 @@ module Harnex
           --all        List sessions across all repos
           --json       Output JSON instead of a table
           -h, --help   Show this help
+
+        Common patterns:
+          #{program_name}
+          #{program_name} --all
+          #{program_name} --id cx-i-42 --json
+
+        Gotchas:
+          By default, status filters to the current repo root.
+          Use --all when supervising workers launched from sibling worktrees.
+          A prompt-like state is not a completion signal by itself.
       TEXT
     end
 

data/lib/harnex/commands/stop.rb

@@ -23,6 +23,16 @@ module Harnex
 
         Sends the adapter stop sequence to the session.
         Use `harnex wait --id ID` afterward to block until the session finishes.
+
+        Common patterns:
+          #{program_name} --id cx-i-42
+          #{program_name} --id cx-i-42 --repo /path/to/repo
+          #{program_name} --id cx-i-42 --timeout 15
+
+        Gotchas:
+          Stop only after verifying the worker's result landed.
+          For tmux sessions, stop targets the harnex session ID, not the tmux name.
+          If a session is in another repo/worktree, pass --repo or run status --all.
       TEXT
     end
 

data/lib/harnex/commands/wait.rb

@@ -7,17 +7,33 @@ 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
+
+        Common patterns:
+          #{program_name} --id cx-i-42 --until task_complete --timeout 900
+          #{program_name} --id cx-i-42 --until prompt --timeout 120
+          #{program_name} --id cx-i-42
+
+        Gotchas:
+          task_complete is an event predicate; prompt/busy are live state polls.
+          Prompt state alone does not prove work acceptance. Verify artifacts/tests.
+          Without --timeout, wait can block indefinitely.
       TEXT
     end
 
@@ -42,7 +58,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 +70,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, submit: submit, enter_only: enter_only, 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,43 @@ module Harnex
         .tap { emit_send_event(text, force: payload[:force]) }
     end
 
+    def inject_via_jsonrpc(text:, submit:, enter_only:, force: false)
+      payload = adapter.build_send_payload(
+        text: text,
+        submit: submit,
+        enter_only: enter_only,
+        screen_text: nil,
+        force: force
+      )
+      dispatch = payload.fetch(:dispatch).dup
+      dispatch[:model] = meta_hash["model"] if meta_hash["model"] && !dispatch.key?(:model)
+      dispatch[:effort] = meta_hash["effort"] if meta_hash["effort"] && !dispatch.key?(:effort)
+
+      turn_id = nil
+      @inject_mutex.synchronize do
+        turn_id = adapter.dispatch(**dispatch)
+        @state_machine.force_busy!
+        @injected_count += 1
+        @last_injected_at = Time.now
+        persist_registry
+      end
+
+      emit_send_event(dispatch.fetch(:prompt, text), force: payload[:force])
+      {
+        ok: true,
+        cli: adapter.key,
+        bytes_written: dispatch.fetch(:prompt, text).to_s.bytesize,
+        injected_count: @injected_count,
+        newline: false,
+        input_state: payload[:input_state],
+        force: payload[: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 +305,169 @@ 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
+      @state_machine.force_prompt!
+      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
+      dispatch_initial_prompt
+
+      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"
+        @state_machine.force_busy!
+        emit_event("turn_started", turnId: params["turnId"] || params["turn_id"])
+      when "turn/completed"
+        @last_completed_at = Time.now
+        @state_machine.force_prompt!
+        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"
+        @state_machine.force_busy!
+        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
+      @state_machine.force_busy!
+      emit_event("disconnected", source: "transport", message: msg) rescue nil
+      signal_rpc_done!
+    end
+
+    def dispatch_initial_prompt
+      return unless adapter.respond_to?(:initial_prompt)
+
+      prompt = adapter.initial_prompt
+      return if prompt.to_s.empty?
+
+      inject_via_jsonrpc(text: prompt, submit: true, enter_only: false, force: false)
+    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/runtime/session_state.rb

@@ -36,6 +36,13 @@ module Harnex
       end
     end
 
+    def force_prompt!
+      @mutex.synchronize do
+        @state = :prompt
+        @condvar.broadcast
+      end
+    end
+
     def wait_for_prompt(timeout)
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       @mutex.synchronize do

data/lib/harnex/version.rb

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

data/lib/harnex.rb

@@ -24,5 +24,6 @@ require_relative "harnex/commands/events"
 require_relative "harnex/commands/pane"
 require_relative "harnex/commands/recipes"
 require_relative "harnex/commands/guide"
-require_relative "harnex/commands/skills"
+require_relative "harnex/commands/agents_guide"
+require_relative "harnex/commands/doctor"
 require_relative "harnex/cli"