harnex 0.6.3 → 0.6.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f547957cf6589b1d153e4cf7e462482902ea71e7e1291281524e867596ea4730
-  data.tar.gz: 4f01e84be1c31692f2b68fa09850dd781116398ab45f3e6f0b2ad76c7f52846c
+  metadata.gz: 297484ce749d268b7582afd226d617c79fed80a12928ced5daa8df2c3bd4f763
+  data.tar.gz: 554528411e6bca5c6037ca579067f37b4b58626b88ed5c263fe95debe4517f70
 SHA512:
-  metadata.gz: eb7cd143d32da68e674bbc620d6ac6c56cb4388009e5f074ab54958288e6a02a0a31df38dae9a1713881ce0ea6315f2f8c01147a1b9b071056439bc8e3734518
-  data.tar.gz: a3c17557910b63e987cad3497c54599044417484710b8cd7cc2f152bfb9aa43b6231ba99c11efc93c0c9788bdc7f41077d22dda30e4a13b6be724f109e0eabbf
+  metadata.gz: 1aa029fe0d4177ef1a9043c863935655df9b636b48bedaad3f84d35e6d02d0b9255b16ce2c08a5220f2eb4b89930fe0002b2926c47039b7cb1eeab2a6e333b07
+  data.tar.gz: ab908f0f299a9a0ae286cf629202fa26d518f59658518515818c388f21daadbd42a4a839417878a99c3f863439df5d11dd51cdf7c3675b737638293b5c739832

data/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## [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
+
+- JSON-RPC adapter (`codex app-server`): harnex now mediates Codex's
+  server-to-client approval requests via the protocol — auto-approves
+  `applyPatchApproval`, `execCommandApproval`,
+  `item/commandExecution/requestApproval`, and
+  `item/fileChange/requestApproval`. Previously the adapter rejected
+  every server-side request with `-32601 "Unsupported server request"`,
+  which meant Codex's default sandbox blocked shell exec, file changes,
+  git commits, and package-manager invocations whenever a dispatched
+  worker tried to do real work. Autonomous worker dispatches now run
+  cleanly under the default sandbox without needing
+  `--dangerously-bypass-approvals-and-sandbox` or
+  `-c sandbox_mode=danger-full-access`.
+- `CodexAppServer#build_command` now appends operator-supplied codex
+  flags (passed via `harnex run codex -- -c key=value`) while still
+  filtering out the harnex-context entry that `--context` smuggles
+  through `@extra_args` (codex `app-server` rejects positional input).
+
+### Changed
+
+- `--legacy-pty` is now a long-term supported fallback rather than a
+  deprecated path. The 0.7.0-removal plan is dropped — the legacy PTY
+  adapter remains the right tool for interactive/TUI use cases and for
+  any operator who prefers terminal-native Codex chrome. JSON-RPC
+  remains the default for autonomous worker dispatches and structured
+  observability.
+
+### Added
+
+- JSON-RPC adapter: classify sub-5s pre-turn exits as `boot_failure`
+  (vs the existing `disconnected` terminal state), tracked by latching
+  on `turn/started`. `build_summary_actual` counts `boot_failure` exits
+  in `actual.disconnections` so early-boot deaths are not lost from
+  dispatch telemetry. First of three planned commits for issue #32;
+  remaining work (ensure-block telemetry write + optional `last_error`
+  capture) tracked separately.
+
 ## [0.6.3] — 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
@@ -330,6 +331,16 @@ The adapter reads the screen and returns a state hash:
 - 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`.
+- **Approval mediation**: Codex's app-server protocol delegates
+  sandbox/approval decisions to the JSON-RPC client via server-to-
+  client requests. Harnex auto-approves `applyPatchApproval`,
+  `execCommandApproval`, `item/commandExecution/requestApproval`, and
+  `item/fileChange/requestApproval`, so autonomous workers can run
+  shell commands, write files, commit, and invoke package managers
+  under Codex's default sandbox without any bypass flag. Other
+  server-to-client requests (permissions, user-input, dynamic-tool,
+  auth-refresh) currently fall through to `-32601` until use cases
+  appear.
 - Disconnect is detected from JSON-RPC error responses, subprocess
   EOF, parse errors, or a server `error` notification — no screen
   regex required.
@@ -339,7 +350,7 @@ The adapter reads the screen and returns a state hash:
 - See `docs/codex-appserver.md` for the full mapping table and
   troubleshooting.
 
-#### Codex Adapter (legacy PTY — `--legacy-pty`, removal in 0.7.0)
+#### Codex Adapter (legacy PTY — `--legacy-pty`, long-term fallback)
 
 - Launches with `--no-alt-screen` for inline screen output
 - Detects prompt by looking for `›` prefix in recent lines

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,11 +33,28 @@ 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
+      # when its sandbox/approval policy needs a client decision; without
+      # a handler the client returns -32601 and codex blocks the operation.
+      # Permissions / user-input / dynamic-tool / auth-refresh requests
+      # have richer response shapes and are deliberately not auto-handled
+      # — they fall through to -32601 until a use case appears.
+      APPROVAL_RESPONSES = {
+        "applyPatchApproval"                    => { decision: "approved" },
+        "execCommandApproval"                   => { decision: "approved" },
+        "item/commandExecution/requestApproval" => { decision: "accept" },
+        "item/fileChange/requestApproval"       => { decision: "accept" }
+      }.freeze
 
       attr_reader :thread_id, :current_turn_id, :last_completed_at, :initial_prompt
 
       def initialize(extra_args = [])
         super("codex", extra_args)
+        reject_unsupported_codex_flags!
         @initial_prompt = extract_initial_prompt(extra_args)
         @client = nil
         @thread_id = nil
@@ -56,8 +73,13 @@ module Harnex
         ["codex", "app-server"]
       end
 
+      # The harnex-context entry (set by `--context`) is delivered via
+      # JSON-RPC `turn/start`, not as a CLI argument — codex app-server
+      # rejects positional input and would exit immediately. Operator-
+      # supplied codex flags (passed via `harnex run codex -- ...`) are
+      # appended so e.g. `-c sandbox_mode=danger-full-access` works.
       def build_command
-        base_command
+        base_command + cli_extra_args
       end
 
       def describe
@@ -120,6 +142,7 @@ module Harnex
         end
 
         @client.on_notification { |msg| handle_notification(msg) }
+        @client.on_request { |method, params| handle_server_request(method, params) }
         @client.on_disconnect { |err| handle_disconnect(err) }
         @client.start
         perform_handshake
@@ -127,6 +150,13 @@ module Harnex
         self
       end
 
+      # Auto-approve known approval-style requests so dispatched workers
+      # can run without a human-in-the-loop. Returns the response body to
+      # serialize as JSON-RPC `result`, or `nil` to fall through to -32601.
+      def handle_server_request(method, _params)
+        APPROVAL_RESPONSES[method]
+      end
+
       def dispatch(prompt:, model: nil, effort: nil)
         ensure_open!
         ensure_thread!
@@ -138,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
@@ -167,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
@@ -188,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)
@@ -200,6 +237,27 @@ 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
+        @extra_args.reject { |a| a.is_a?(String) && a.start_with?("[harnex session id=") }
+      end
+
       def perform_handshake
         @client.request("initialize", {
           clientInfo: {
@@ -223,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
@@ -270,6 +328,7 @@ module Harnex
           @id_mutex = Mutex.new
           @write_mutex = Mutex.new
           @notification_handler = nil
+          @request_handler = nil
           @disconnect_handler = nil
           @disconnect_signaled = false
           @closed = false
@@ -280,6 +339,13 @@ module Harnex
           @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
@@ -340,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)
@@ -381,11 +467,7 @@ module Harnex
 
         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']}" }
-            })
+            handle_server_request(message)
             return
           end
 
@@ -406,6 +488,29 @@ module Harnex
           @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
 
@@ -419,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/adapters.rb

@@ -18,7 +18,8 @@ module Harnex
 
     # 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.
+    # `harnex run codex --legacy-pty`); kept as a long-term supported
+    # fallback for interactive/TUI use cases.
     def codex_appserver_enabled?
       true
     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,18 +32,21 @@ 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})
           --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.
+                             the JSON-RPC `app-server` adapter. Long-term
+                             supported fallback for interactive/TUI use; JSON-RPC
+                             remains the default for autonomous dispatches.
           -h, --help         Show this help
 
         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.
@@ -51,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"
 
@@ -59,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
 
@@ -79,6 +85,7 @@ module Harnex
         context: nil,
         meta: nil,
         summary_out: nil,
+        auto_stop: false,
         detach: false,
         tmux: false,
         tmux_name: nil,
@@ -97,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)
@@ -158,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]
@@ -265,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
 
@@ -411,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]))
@@ -472,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
@@ -519,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,7 +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
@@ -115,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
 
@@ -136,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
@@ -204,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!
@@ -340,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
@@ -375,17 +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"])
@@ -393,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!
@@ -411,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!
@@ -428,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
@@ -642,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)
@@ -677,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])
@@ -705,14 +731,90 @@ 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?
+      return "boot_failure" if boot_failure_exit?
       return "failure" unless @exit_code == 0
-      return "success" if session_summary_present?
 
       "disconnected"
     end
 
+    def boot_failure_exit?
+      return false unless adapter.transport == :stdio_jsonrpc
+      return false if @turn_started_seen
+
+      lifetime = (@ended_at || Time.now) - @started_at
+      lifetime <= 5
+    end
+
     def session_summary_present?
       @usage_summary.values.any? { |value| !value.nil? }
     end
@@ -761,9 +863,11 @@ module Harnex
 
     def build_summary_actual
       counters = @event_counters.snapshot
-      counters[:disconnections] = [counters[:disconnections], 1].max if @exit_reason == "disconnected"
+      if %w[disconnected boot_failure].include?(@exit_reason)
+        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,
@@ -785,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
@@ -813,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.3"
-  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.3
+  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.