harnex 0.6.4 → 0.6.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 354a4709831de10c8d19c40fbc4efa5b6df3d3fb1d0459fe1f4960b986eef8ad
-  data.tar.gz: 43e0617dac379a90281798fb7f1bd6973177111341d25cd29a1f0c6166580ada
+  metadata.gz: 297484ce749d268b7582afd226d617c79fed80a12928ced5daa8df2c3bd4f763
+  data.tar.gz: 554528411e6bca5c6037ca579067f37b4b58626b88ed5c263fe95debe4517f70
 SHA512:
-  metadata.gz: 3213b7c38243f315b9cb3dfed677c63211d7148e166393f8b599088c14d7d0128ebfd0e583068182c0fff8419e483abd8f0e0f2230c37a25beb4bb6d812d0463
-  data.tar.gz: 1aeb182b6e355df8dce1f8445ebfcc3bedea8c7a5655590ca3eeac900b5fdcbef38786a88ef9dc8d3d0eaf2717dc330a3e34e98965ef18af6ef6f5b105d50e95
+  metadata.gz: 1aa029fe0d4177ef1a9043c863935655df9b636b48bedaad3f84d35e6d02d0b9255b16ce2c08a5220f2eb4b89930fe0002b2926c47039b7cb1eeab2a6e333b07
+  data.tar.gz: ab908f0f299a9a0ae286cf629202fa26d518f59658518515818c388f21daadbd42a4a839417878a99c3f863439df5d11dd51cdf7c3675b737638293b5c739832

data/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## [Unreleased]
 
+## [0.6.5] — 2026-05-07
+
+### Added
+
+- `harnex run --auto-stop` for one-shot `--context` dispatches.
+  JSON-RPC Codex sessions stop after the first `task_complete` event,
+  while PTY-backed sessions stop after the initial context turn returns
+  to a prompt. The shutdown path reuses `harnex stop`, including the
+  JSON-RPC TERM/KILL fallback.
+
+### Fixed
+
+- JSON-RPC Codex sessions now terminate their `codex app-server`
+  subprocess on `harnex stop`: harnex preserves the existing
+  `turn/interrupt` request, then sends TERM with a bounded KILL
+  fallback so the runner can release the API port and registry entry.
+- JSON-RPC adapter now captures token usage in `DISPATCH.jsonl`.
+  `Session#handle_rpc_notification` reads schema-true
+  `params["tokenUsage"]` on `thread/tokenUsage/updated`, and the
+  session-end telemetry path branches on `adapter.transport`: JSON-RPC
+  pulls the cumulative `tokenUsage.total` and maps the camelCase
+  `{input,output,cachedInput,reasoningOutput}Tokens` fields onto the
+  snake_case `actual.*_tokens` columns. PTY continues to scrape the
+  transcript tail. (#33)
+- JSON-RPC adapter rejects `-m`/`--model`/`--model=…` early with a
+  clear `ArgumentError` pointing at `-c model="<name>"`. Previously the
+  flag was silently forwarded to `codex app-server`, which exited at
+  startup and surfaced only as an opaque `disconnected` transport
+  message. Legacy PTY adapter (`--legacy-pty`) still accepts `-m`.
+  `harnex help run` and `guides/01_dispatch.md` document the JSON-RPC
+  vs PTY flag-form difference. (#34)
+
 ## [0.6.4] — 2026-05-06
 
 ### Fixed

data/TECHNICAL.md

@@ -28,6 +28,7 @@ harnex run codex -- --cd ~/other/repo
 | `--preset NAME`     | Watch preset (`impl`, `plan`, `gate`), requires `--watch`           |
 | `--watch-file PATH` | Auto-send a file-change hook (`--watch PATH`/`--watch=PATH` legacy) |
 | `--context TXT`     | Give the agent a task on startup                                    |
+| `--auto-stop`       | With `--context`, stop after the first task completion              |
 | `--timeout SEC`     | Wait budget for detached registration                               |
 
 ### `harnex send` — Talk to a running agent

data/guides/01_dispatch.md

@@ -63,10 +63,30 @@ harnex run codex --id cx-i-NN --tmux cx-i-NN \
   --context "Read and execute /tmp/task-impl-NN.md"
 ```
 
+For one-shot context dispatches that should clean themselves up, add
+`--auto-stop`. It requires `--context`, fires once on the first task
+completion, and does not keep the session alive for later reuse. This keeps
+parallel orchestration compact:
+
+```bash
+for i in 1 2 3; do
+  harnex run codex --id w-$i --tmux w-$i --detach \
+    --context "Read and execute /tmp/task-$i.md" --auto-stop &
+done
+for i in 1 2 3; do harnex wait --id w-$i & done
+wait
+```
+
 Rule: when you use `--tmux`, pass the same name as `--id`. If you pass only
 `--tmux NAME`, harnex creates a random session ID and the pane name no longer
 matches `harnex status` or `harnex pane --id`.
 
+Codex flag forms differ between transports. The default JSON-RPC adapter
+(`codex app-server`) does not accept `-m`/`--model`; pass the model as
+`-c model="<name>"` instead. The legacy PTY adapter (`harnex run codex
+--legacy-pty`) still accepts `-m`. Harnex rejects `-m` early on JSON-RPC
+with an actionable error rather than letting the subprocess boot-disconnect.
+
 ## Send
 
 Use `--message` for short instructions and file references:

data/lib/harnex/adapters/codex_appserver.rb

@@ -33,6 +33,8 @@ module Harnex
       ].freeze
 
       EVENTS = %w[task_complete turn_started item_completed disconnected].freeze
+      STOP_TERM_GRACE_SECONDS = 0.5
+      STOP_KILL_GRACE_SECONDS = 1.0
 
       # Server→client approval requests harnex auto-approves so dispatched
       # codex workers can run autonomously. Codex sends these via JSON-RPC
@@ -44,7 +46,7 @@ module Harnex
       APPROVAL_RESPONSES = {
         "applyPatchApproval"                    => { decision: "approved" },
         "execCommandApproval"                   => { decision: "approved" },
-        "item/commandExecution/requestApproval" => { decision: "approved" },
+        "item/commandExecution/requestApproval" => { decision: "accept" },
         "item/fileChange/requestApproval"       => { decision: "accept" }
       }.freeze
 
@@ -52,6 +54,7 @@ module Harnex
 
       def initialize(extra_args = [])
         super("codex", extra_args)
+        reject_unsupported_codex_flags!
         @initial_prompt = extract_initial_prompt(extra_args)
         @client = nil
         @thread_id = nil
@@ -165,7 +168,7 @@ module Harnex
         params[:effort] = effort if effort
 
         result = @client.request("turn/start", params)
-        @current_turn_id = result["turnId"] || result["turn_id"] || result["id"]
+        @current_turn_id = result.dig("turn", "id")
         @state = :busy
         @current_turn_id
       end
@@ -194,6 +197,13 @@ module Harnex
         @state = :disconnected
       end
 
+      def terminate_subprocess(term_grace_seconds: STOP_TERM_GRACE_SECONDS, kill_grace_seconds: STOP_KILL_GRACE_SECONDS)
+        @client&.terminate_process(
+          term_grace_seconds: term_grace_seconds,
+          kill_grace_seconds: kill_grace_seconds
+        )
+      end
+
       def pid
         @client&.pid
       end
@@ -215,7 +225,7 @@ module Harnex
       def extract_thread_id(payload)
         return nil unless payload.is_a?(Hash)
 
-        payload.dig("thread", "id") || payload["threadId"] || payload["thread_id"]
+        payload.dig("thread", "id")
       end
 
       def extract_initial_prompt(extra_args)
@@ -227,6 +237,21 @@ module Harnex
         nil
       end
 
+      # `codex app-server` does not implement `-m/--model`; passing it
+      # causes the subprocess to exit at startup, surfacing only as a
+      # null-message transport disconnect. Same flag still works on the
+      # legacy PTY adapter (`harnex run codex --legacy-pty`).
+      def reject_unsupported_codex_flags!
+        bad = @extra_args.find do |a|
+          s = a.to_s
+          s == "-m" || s == "--model" || s.start_with?("--model=")
+        end
+        return unless bad
+
+        raise ArgumentError,
+          "-m/--model is not supported by `codex app-server`. Use `-c model=\"<name>\"` instead."
+      end
+
       # Codex CLI flags only — strips the harnex-context entry that
       # `--context` smuggles through @extra_args.
       def cli_extra_args
@@ -256,7 +281,7 @@ module Harnex
         when "thread/started"
           @thread_id ||= extract_thread_id(params)
         when "turn/started"
-          @current_turn_id = params["turnId"] || params["turn_id"]
+          @current_turn_id = params.dig("turn", "id")
           @state = :busy
         when "turn/completed"
           @last_completed_at = Time.now
@@ -381,6 +406,26 @@ module Harnex
           @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
+
         private
 
         def write_line(message)
@@ -479,6 +524,20 @@ module Harnex
         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

data/lib/harnex/adapters/generic.rb

@@ -9,6 +9,17 @@ module Harnex
       def base_command
         [@cli_name]
       end
+
+      def input_state(screen_text)
+        if recent_lines(screen_text).any? { |line| prompt_line?(line) }
+          {
+            state: "prompt",
+            input_ready: true
+          }
+        else
+          super
+        end
+      end
     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 --legacy-pty --help
+      --timeout --inbox-ttl --auto-stop --legacy-pty --help
     ].freeze
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
@@ -32,6 +32,7 @@ module Harnex
           --preset NAME      Watch preset: impl, plan, gate (requires --watch)
           --watch-file PATH  Auto-send a file-change hook on modification
           --context TEXT     Inject as the initial prompt (prepends session header)
+          --auto-stop        Stop after the first task completion from --context
           --meta JSON        Attach parsed JSON metadata to the started event
           --summary-out PATH Append dispatch telemetry summary JSONL to PATH
           --timeout SECS     Max seconds to wait for detached registration (default: #{DEFAULT_TIMEOUT})
@@ -45,6 +46,7 @@ module Harnex
         Notes:
           Compatibility: `--watch PATH` and `--watch=PATH` still configure file-hook mode.
           Bare `--watch` enables the babysitter.
+          --auto-stop requires --context and fires once after the first completion.
           Explicit --stall-after/--max-resumes values override --preset defaults.
           CLIs with smart prompt detection: #{Adapters.known.join(', ')}
           Any other CLI name is launched with generic wrapping.
@@ -52,6 +54,7 @@ module Harnex
 
         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 --tmux cx-i-42 --context "Read /tmp/task-impl-42.md" --auto-stop
           #{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"
 
@@ -60,6 +63,8 @@ module Harnex
           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.
+          Codex JSON-RPC: pass model as `-c model=NAME`, not `-m NAME`. The
+            legacy PTY adapter (--legacy-pty) accepts `-m`.
       TEXT
     end
 
@@ -80,6 +85,7 @@ module Harnex
         context: nil,
         meta: nil,
         summary_out: nil,
+        auto_stop: false,
         detach: false,
         tmux: false,
         tmux_name: nil,
@@ -98,6 +104,7 @@ module Harnex
       end
 
       raise OptionParser::MissingArgument, "cli" if cli_name.nil?
+      validate_auto_stop_context!
 
       repo_root = Harnex.resolve_repo_root(adapter_repo_path(cli_name, child_args))
       @options[:summary_out] = resolve_summary_out(repo_root)
@@ -159,6 +166,7 @@ module Harnex
       tmux_cmd += ["--port", @options[:port].to_s] if @options[:port]
       tmux_cmd += ["--watch-file", @options[:watch]] if @options[:watch]
       tmux_cmd += ["--context", @options[:context]] if @options[:context]
+      tmux_cmd << "--auto-stop" if @options[:auto_stop]
       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]
@@ -266,7 +274,8 @@ module Harnex
         description: @options[:description],
         meta: @options[:meta],
         summary_out: @options[:summary_out],
-        inbox_ttl: @options[:inbox_ttl]
+        inbox_ttl: @options[:inbox_ttl],
+        auto_stop: @options[:auto_stop]
       )
     end
 
@@ -412,6 +421,8 @@ module Harnex
           @options[:context] = required_option_value(arg, argv[index])
         when /\A--context=(.+)\z/
           @options[:context] = required_option_value("--context", Regexp.last_match(1))
+        when "--auto-stop"
+          @options[:auto_stop] = true
         when "--meta"
           index += 1
           @options[:meta] = parse_meta(required_option_value(arg, argv[index]))
@@ -473,7 +484,7 @@ module Harnex
         case arg
         when "--"
           return false
-        when "-h", "--help", "--detach", "--tmux", "--legacy-pty"
+        when "-h", "--help", "--detach", "--tmux", "--auto-stop", "--legacy-pty"
           nil
         when /\A--tmux=/
           nil
@@ -520,6 +531,13 @@ module Harnex
       @options[:max_resumes] = preset[:max_resumes] unless @options[:max_resumes_explicit]
     end
 
+    def validate_auto_stop_context!
+      return unless @options[:auto_stop]
+      return if @options[:context]
+
+      raise OptionParser::InvalidOption, "harnex run: --auto-stop requires --context"
+    end
+
     def parse_non_negative_integer(value, option_name:)
       integer = Integer(value)
       raise OptionParser::InvalidArgument, "#{option_name} must be 0 or greater" if integer.negative?

data/lib/harnex/runtime/session.rb

@@ -39,7 +39,7 @@ module Harnex
 
     attr_reader :repo_root, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch, :inbox, :description, :meta, :summary_out, :output_log_path, :events_log_path
 
-    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, summary_out: nil, inbox_ttl: Inbox::DEFAULT_TTL)
+    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, summary_out: nil, inbox_ttl: Inbox::DEFAULT_TTL, auto_stop: false)
       @adapter = adapter
       @command = command
       @repo_root = repo_root
@@ -60,6 +60,8 @@ module Harnex
       @mutex = Mutex.new
       @inject_mutex = Mutex.new
       @events_mutex = Mutex.new
+      @stop_mutex = Mutex.new
+      @auto_stop_mutex = Mutex.new
       @injected_count = 0
       @last_injected_at = nil
       @started_at = Time.now
@@ -74,8 +76,14 @@ module Harnex
       @usage_summary = {}
       @ended_at = nil
       @exit_reason = nil
+      @last_error = nil
+      @session_finalized = false
       @turn_started_seen = false
       @last_completed_at = nil
+      @auto_stop = !!auto_stop
+      @auto_stop_fired = false
+      @auto_stop_seen_busy = false
+      @stop_requested = false
       @writer = nil
       @pid = nil
       @term_signal = nil
@@ -116,6 +124,7 @@ module Harnex
     def run_pty
       @reader, @writer, @pid = PTY.spawn(child_env, *command)
       @writer.sync = true
+      arm_auto_stop_after_initial_context
       emit_started_event
       emit_git_start_event
 
@@ -137,16 +146,12 @@ module Harnex
       @ended_at = Time.now
 
       output_thread.join(1)
-      emit_session_end_telemetry
-      @exit_reason = classify_exit
-      summary_record = build_summary_record
-      append_summary_record(summary_record)
-      emit_summary_event
-      emit_exit_event
+      finalize_session!
       input_thread&.kill
       watch_thread&.kill
       @exit_code
     ensure
+      finalize_session!
       @inbox.stop
       STDIN.cooked! if STDIN.tty? && stdin_state
       @server&.stop
@@ -205,21 +210,34 @@ module Harnex
       inject_sequence([{ text: text, newline: newline }])
     end
 
-    def inject_stop
+    def inject_stop(turn_id: nil)
+      unless adapter.transport == :stdio_jsonrpc
+        raise "session is not running" unless pid && Harnex.alive_pid?(pid)
+      end
+
+      return { ok: true, signal: "already_requested" } if stop_requested!
+
       if adapter.transport == :stdio_jsonrpc
         @inject_mutex.synchronize do
           begin
-            adapter.interrupt
+            adapter.interrupt(turn_id: turn_id)
           rescue StandardError
             nil
           end
           @state_machine.force_busy!
         end
+        if adapter.respond_to?(:terminate_subprocess)
+          Thread.new do
+            begin
+              adapter.terminate_subprocess
+            rescue Errno::ESRCH, StandardError
+              nil
+            end
+          end
+        end
         return { ok: true, signal: "interrupt_sent" }
       end
 
-      raise "session is not running" unless pid && Harnex.alive_pid?(pid)
-
       @inject_mutex.synchronize do
         adapter.inject_exit(@writer)
         @state_machine.force_busy!
@@ -341,15 +359,11 @@ module Harnex
       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
+      finalize_session!
       watch_thread&.kill
       @exit_code
     ensure
+      finalize_session!
       @inbox.stop
       @server&.stop
       begin
@@ -376,18 +390,20 @@ module Harnex
 
       case method
       when "thread/started"
-        @rpc_thread_id = params["threadId"] || params["thread_id"]
+        @rpc_thread_id = params.dig("thread", "id")
       when "turn/started"
         @turn_started_seen = true
         @state_machine.force_busy!
-        emit_event("turn_started", turnId: params["turnId"] || params["turn_id"])
+        emit_event("turn_started", turnId: params.dig("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"]
+        turn = params["turn"] || {}
+        payload = { turnId: turn["id"] }
+        payload[:status] = turn["status"] if turn["status"]
         payload[:tokenUsage] = params["tokenUsage"] if params["tokenUsage"]
         emit_event("task_complete", **payload)
+        schedule_auto_stop("task_complete", turn_id: payload[:turnId])
       when "item/completed"
         emit_event("item_completed", item: params["item"])
         text = render_item_text(params["item"])
@@ -395,14 +411,18 @@ module Harnex
       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
+        # Schema: ThreadTokenUsageUpdatedNotification carries
+        # `tokenUsage: { last, total, modelContextWindow? }` where each
+        # breakdown has camelCase {input,output,cachedInput,reasoningOutput,total}Tokens.
+        # Snapshot it; the cumulative `total` is read at session end.
+        @token_usage = params["tokenUsage"] if params["tokenUsage"].is_a?(Hash)
       when "thread/status/changed"
         # State machine reflects RPC state; no event needed.
         nil
       when "account/rateLimits/updated"
         @rate_limits = params
       when "error"
+        @last_error = params["message"].to_s unless params["message"].to_s.empty?
         @state_machine.force_busy!
         emit_event("disconnected", source: "error_notification", message: params["message"])
         signal_rpc_done!
@@ -413,6 +433,7 @@ module Harnex
 
     def handle_rpc_disconnect(error)
       msg = error.is_a?(Hash) ? error["message"] : error&.message
+      @last_error = msg.to_s unless msg.to_s.empty?
       @state_machine.force_busy!
       emit_event("disconnected", source: "transport", message: msg) rescue nil
       signal_rpc_done!
@@ -430,14 +451,15 @@ module Harnex
     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)}" : ""}"
+      case item["type"]
+      when "agentMessage"
+        item["text"]
+      when "mcpToolCall", "dynamicToolCall"
+        name = item["tool"] || "tool"
+        args = item["arguments"]
+        "tool: #{name}#{args ? " #{summarize(args)}" : ""}"
+      when "commandExecution"
+        "command: #{item["command"]}"
       else
         item["text"]
       end
@@ -644,7 +666,9 @@ module Harnex
         @output_buffer = @output_buffer.byteslice(overflow, OUTPUT_BUFFER_LIMIT) if overflow.positive?
         @output_buffer.dup
       end
-      @state_machine.update(snapshot)
+      old_state = @state_machine.to_s.to_sym
+      new_state = @state_machine.update(snapshot)
+      handle_auto_stop_pty_transition(old_state, new_state)
     end
 
     def append_output_log(chunk)
@@ -679,7 +703,7 @@ module Harnex
     end
 
     def emit_session_end_telemetry
-      @usage_summary = normalized_usage_summary(adapter.parse_session_summary(transcript_tail))
+      @usage_summary = normalized_usage_summary(collect_session_summary)
       emit_event("usage", **@usage_summary)
 
       @git_end = Harnex.git_capture_end(repo_root, @git_start[:sha])
@@ -707,6 +731,73 @@ module Harnex
       emit_event("exited", **payload)
     end
 
+    def finalize_session!
+      return if @session_finalized
+      return unless @events_log
+
+      @session_finalized = true
+      @ended_at ||= Time.now
+      begin
+        emit_session_end_telemetry
+      rescue StandardError => e
+        @usage_summary = normalized_usage_summary(nil)
+        warn("harnex: failed to collect session-end telemetry: #{e.message}")
+      end
+      @exit_reason ||= classify_exit
+      append_summary_record(build_summary_record)
+      emit_summary_event
+      emit_exit_event
+    end
+
+    def stop_requested!
+      @stop_mutex.synchronize do
+        return true if @stop_requested
+
+        @stop_requested = true
+        false
+      end
+    end
+
+    def arm_auto_stop_after_initial_context
+      return unless @auto_stop
+      return unless adapter.transport == :pty
+
+      @auto_stop_mutex.synchronize { @auto_stop_seen_busy = true }
+      @state_machine.force_busy!
+    end
+
+    def handle_auto_stop_pty_transition(old_state, new_state)
+      return unless @auto_stop
+      return unless adapter.transport == :pty
+
+      seen_busy = @auto_stop_mutex.synchronize do
+        @auto_stop_seen_busy ||= old_state == :busy || new_state == :busy
+      end
+      schedule_auto_stop("prompt_after_busy") if seen_busy && new_state == :prompt
+    end
+
+    def schedule_auto_stop(reason, turn_id: nil)
+      return unless @auto_stop
+
+      should_fire = @auto_stop_mutex.synchronize do
+        if @auto_stop_fired
+          false
+        else
+          @auto_stop_fired = true
+          true
+        end
+      end
+      return unless should_fire
+
+      Thread.new do
+        begin
+          inject_stop(turn_id: turn_id)
+        rescue StandardError => e
+          warn("harnex: auto-stop failed after #{reason}: #{e.message}")
+        end
+      end
+    end
+
     def classify_exit
       return "timeout" if @exit_code == 124
       return "success" if @exit_code == 0 && session_summary_present?
@@ -776,7 +867,7 @@ module Harnex
         counters[:disconnections] = [counters[:disconnections], 1].max
       end
 
-      {
+      actual = {
         model: meta_hash["model"],
         effort: meta_hash["effort"],
         duration_s: @ended_at ? (@ended_at - @started_at).to_i : nil,
@@ -798,6 +889,8 @@ module Harnex
         tests_passed: nil,
         tests_failed: nil
       }
+      actual[:last_error] = @last_error if @exit_reason == "boot_failure" && @last_error
+      actual
     end
 
     def summary_predicted_payload
@@ -826,6 +919,33 @@ module Harnex
       USAGE_FIELDS.to_h { |field| [field, summary[field] || summary[field.to_s]] }
     end
 
+    # Adapters speaking JSON-RPC capture token usage from the structured
+    # `thread/tokenUsage/updated` notification stream and don't have a
+    # transcript to scrape; fall back to the schema-true cumulative
+    # `total` block. Other adapters parse the transcript tail.
+    def collect_session_summary
+      if adapter.transport == :stdio_jsonrpc
+        summary_from_token_usage
+      else
+        adapter.parse_session_summary(transcript_tail)
+      end
+    end
+
+    def summary_from_token_usage
+      return {} unless @token_usage.is_a?(Hash)
+
+      total = @token_usage["total"]
+      return {} unless total.is_a?(Hash)
+
+      {
+        input_tokens: total["inputTokens"],
+        output_tokens: total["outputTokens"],
+        reasoning_tokens: total["reasoningOutputTokens"],
+        cached_tokens: total["cachedInputTokens"],
+        total_tokens: total["totalTokens"]
+      }
+    end
+
     def transcript_tail
       return "" unless File.file?(output_log_path)
 

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.6.4"
-  RELEASE_DATE = "2026-05-06"
+  VERSION = "0.6.5"
+  RELEASE_DATE = "2026-05-07"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.6.4
+  version: 0.6.5
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-06 00:00:00.000000000 Z
+date: 2026-05-07 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.