harnex 0.10.2 → 0.12.0

data/lib/harnex/adapters/pi.rb

@@ -1,5 +1,7 @@
 require "json"
 require "open3"
+require "rubygems/version"
+require "timeout"
 
 module Harnex
   module Adapters
@@ -9,7 +11,11 @@ module Harnex
     class Pi < Base
       STOP_TERM_GRACE_SECONDS = 0.5
       STOP_KILL_GRACE_SECONDS = 1.0
+      REQUEST_TIMEOUT_SECONDS = 30.0
+      STDERR_TAIL_BYTES = 16 * 1024
+      MIN_RPC_VERSION = Gem::Version.new("0.80.4")
       DIALOG_UI_METHODS = %w[select confirm input editor].freeze
+      THINKING_LEVELS = %w[off minimal low medium high xhigh max].freeze
 
       attr_reader :initial_prompt, :last_completed_at
 
@@ -20,8 +26,14 @@ module Harnex
         @disconnect_handler = nil
         @read_io = nil
         @write_io = nil
+        @stderr_io = nil
         @pid = nil
+        @wait_thr = nil
         @reader_thread = nil
+        @stderr_thread = nil
+        @stderr_mutex = Mutex.new
+        @stderr_tail = +""
+        @stderr_tail.force_encoding(Encoding::BINARY)
         @closed = false
         @disconnect_signaled = false
         @state = :disconnected
@@ -37,6 +49,8 @@ module Harnex
         )
         @model = nil
         @provider = nil
+        @startup_model = nil
+        @startup_effort = nil
         @session_stats_requested = false
         @last_completed_at = nil
       end
@@ -70,18 +84,53 @@ module Harnex
       end
 
       def build_command
-        base_command + cli_extra_args
+        args = cli_extra_args
+        args += ["--model", @startup_model] if @startup_model
+        args += ["--thinking", @startup_effort] if @startup_effort
+        base_command + args
+      end
+
+      def configure_startup(model: nil, effort: nil)
+        requested_model = model.to_s.strip
+        requested_effort = effort.to_s.strip
+        unless requested_effort.empty? || THINKING_LEVELS.include?(requested_effort)
+          raise ArgumentError,
+                "unsupported Pi thinking level #{requested_effort.inspect}; expected one of #{THINKING_LEVELS.join(', ')}"
+        end
+
+        @startup_model = requested_model.empty? ? nil : requested_model
+        @startup_effort = requested_effort.empty? ? nil : requested_effort
+        self
+      end
+
+      def validate_runtime!
+        version = parsed_agent_version
+        if version.nil?
+          raise "could not determine Pi version from `pi --version`; Pi RPC requires >= #{MIN_RPC_VERSION}"
+        end
+        return true if version >= MIN_RPC_VERSION
+
+        raise "Pi #{version} is too old for reliable RPC settlement; harnex requires Pi >= #{MIN_RPC_VERSION} (run `pi update`)"
+      end
+
+      def parsed_agent_version
+        match = agent_version.to_s.match(/(\d+\.\d+\.\d+)/)
+        match ? Gem::Version.new(match[1]) : nil
+      rescue ArgumentError
+        nil
       end
 
       def describe
         {
           transport: transport,
           protocol: "jsonl",
+          minimum_version: MIN_RPC_VERSION.to_s,
           events: %w[
-            agent_start agent_end turn_start turn_end message_start message_update message_end
+            agent_start agent_end agent_settled turn_start turn_end message_start message_update message_end
             tool_execution_start tool_execution_update tool_execution_end queue_update
-            compaction_start compaction_end auto_retry_start auto_retry_end extension_error
-            extension_ui_request
+            compaction_start compaction_end auto_retry_start auto_retry_end
+            summarization_retry_scheduled summarization_retry_attempt_start summarization_retry_finished
+            bash_execution_update extension_error extension_ui_request
           ]
         }
       end
@@ -106,8 +155,10 @@ module Harnex
         raise ArgumentError, "Pi RPC cannot stage input without submitting it" unless submit || enter_only
         raise ArgumentError, "Pi RPC does not support submit-only input" if enter_only
 
+        dispatch = { prompt: text.to_s }
+        dispatch[:streaming_behavior] = "steer" if force && state[:state] == "busy"
         {
-          dispatch: { prompt: text.to_s },
+          dispatch: dispatch,
           input_state: state,
           force: force
         }
@@ -131,24 +182,24 @@ module Harnex
           @write_io = write_io
           @pid = pid
         else
-          @pid, @write_io, @read_io = spawn_subprocess(env, cwd)
+          validate_runtime!
+          @pid, @write_io, @read_io, @stderr_io, @wait_thr = spawn_subprocess(env, cwd)
         end
 
         @closed = false
         @disconnect_signaled = false
         @state = :prompt
+        @stderr_thread = Thread.new { drain_stderr } if @stderr_io
         @reader_thread = Thread.new { read_loop }
         request_state_async
         self
       end
 
-      def dispatch(prompt:, model: nil, effort: nil)
+      def dispatch(prompt:, model: nil, effort: nil, streaming_behavior: nil)
         ensure_open!
-
+        apply_dispatch_overrides(model: model, effort: effort) unless @state == :busy
         payload = { "type" => "prompt", "message" => prompt.to_s }
-        payload["model"] = model if model
-        payload["thinkingLevel"] = effort if effort
-
+        payload["streamingBehavior"] = streaming_behavior if streaming_behavior
         request(payload)
         @state = :busy
         nil
@@ -156,7 +207,7 @@ module Harnex
 
       def interrupt(turn_id: nil)
         ensure_open!
-        request("type" => "abort")
+        request({ "type" => "abort" })
       rescue StandardError
         nil
       end
@@ -219,6 +270,7 @@ module Harnex
 
         begin
           @write_io.close unless @write_io&.closed?
+          @read_io.close if !@pid && !@wait_thr && @read_io && !@read_io.closed?
         rescue IOError
           nil
         end
@@ -229,6 +281,13 @@ module Harnex
           term_grace_seconds: STOP_TERM_GRACE_SECONDS,
           kill_grace_seconds: STOP_KILL_GRACE_SECONDS
         )
+        @reader_thread&.join(1)
+        @stderr_thread&.join(1)
+        [@read_io, @stderr_io].compact.each do |io|
+          io.close unless io.closed?
+        rescue IOError
+          nil
+        end
       end
 
       def terminate_subprocess(term_grace_seconds: STOP_TERM_GRACE_SECONDS, kill_grace_seconds: STOP_KILL_GRACE_SECONDS)
@@ -255,9 +314,36 @@ module Harnex
         @pid
       end
 
+      def wait_for_exit
+        return nil unless @wait_thr || @pid
+
+        status = if @wait_thr
+                   @wait_thr.value
+                 else
+                   _waited_pid, process_status = Process.wait2(@pid)
+                   process_status
+                 end
+        @pid = nil
+        status
+      rescue Errno::ECHILD
+        @pid = nil
+        nil
+      end
+
+      def stderr_tail
+        @stderr_mutex.synchronize { @stderr_tail.dup.force_encoding(Encoding::UTF_8).scrub("") }
+      end
+
+      def disconnect_diagnostic
+        tail = stderr_tail.strip
+        return "pi rpc disconnected" if tail.empty?
+
+        "pi rpc disconnected; stderr: #{tail}"
+      end
+
       private
 
-      def request(payload)
+      def request(payload, timeout: REQUEST_TIMEOUT_SECONDS)
         raise "pi rpc client is closed" if @closed
 
         queue = Queue.new
@@ -269,7 +355,7 @@ module Harnex
         end
 
         write_line(payload.merge("id" => id))
-        response = queue.pop
+        response = Timeout.timeout(timeout.to_f) { queue.pop }
         raise response if response.is_a?(Exception)
 
         unless response["success"]
@@ -278,6 +364,93 @@ module Harnex
 
         handle_response_data(response)
         response["data"] || {}
+      rescue Timeout::Error
+        @id_mutex.synchronize { @pending.delete(id) if defined?(id) && id }
+        error = Timeout::Error.new("pi rpc #{payload["type"]} timed out after #{timeout}s")
+        signal_disconnect(error)
+        raise error
+      end
+
+      def apply_dispatch_overrides(model:, effort:)
+        requested_model = model.to_s.strip
+        requested_effort = effort.to_s.strip
+        if startup_controls_match?(requested_model, requested_effort)
+          validate_startup_controls!(
+            request({ "type" => "get_state" }),
+            model: requested_model,
+            effort: requested_effort
+          )
+          return
+        end
+
+        unless requested_model.empty?
+          provider, model_id = resolve_model_reference(requested_model)
+          selected = request({
+            "type" => "set_model",
+            "provider" => provider,
+            "modelId" => model_id
+          })
+          absorb_model(selected)
+        end
+
+        return if requested_effort.empty?
+
+        unless THINKING_LEVELS.include?(requested_effort)
+          raise ArgumentError,
+                "unsupported Pi thinking level #{requested_effort.inspect}; expected one of #{THINKING_LEVELS.join(', ')}"
+        end
+
+        request({ "type" => "set_thinking_level", "level" => requested_effort })
+        state = request({ "type" => "get_state" })
+        effective = state["thinkingLevel"].to_s
+        return if effective == requested_effort
+
+        raise ArgumentError,
+              "Pi could not apply thinking level #{requested_effort.inspect}; effective level is #{effective.empty? ? 'unknown' : effective.inspect}"
+      end
+
+      def startup_controls_match?(model, effort)
+        has_startup_control = @startup_model || @startup_effort
+        has_startup_control && model == @startup_model.to_s && effort == @startup_effort.to_s
+      end
+
+      def validate_startup_controls!(state, model:, effort:)
+        effective_model = state["model"]
+        if !model.empty? && effective_model.is_a?(Hash)
+          expected_provider, expected_id = model.include?("/") ? model.split("/", 2) : [nil, model]
+          actual_provider = effective_model["provider"].to_s
+          actual_id = effective_model["id"].to_s
+          model_matches = actual_id == expected_id && (expected_provider.nil? || actual_provider == expected_provider)
+          unless model_matches
+            raise ArgumentError,
+                  "Pi could not apply model #{model.inspect}; effective model is #{actual_provider}/#{actual_id}"
+          end
+        elsif !model.empty?
+          raise ArgumentError, "Pi could not report the effective model for requested #{model.inspect}"
+        end
+
+        return if effort.empty? || state["thinkingLevel"].to_s == effort
+
+        effective = state["thinkingLevel"].to_s
+        raise ArgumentError,
+              "Pi could not apply thinking level #{effort.inspect}; effective level is #{effective.empty? ? 'unknown' : effective.inspect}"
+      end
+
+      def resolve_model_reference(model)
+        requested = model.to_s.strip
+        if requested.include?("/")
+          provider, model_id = requested.split("/", 2)
+          return [provider, model_id] unless provider.empty? || model_id.empty?
+        end
+
+        data = request({ "type" => "get_available_models" })
+        matches = Array(data["models"]).select do |candidate|
+          candidate.is_a?(Hash) && candidate["id"].to_s == requested
+        end
+        return [matches.first["provider"], matches.first["id"]] if matches.length == 1
+
+        detail = matches.empty? ? "was not found" : "is ambiguous across #{matches.map { |m| m["provider"] }.uniq.join(', ')}"
+        raise ArgumentError, "Pi model #{requested.inspect} #{detail}; use provider/model"
       end
 
       def request_state_async
@@ -287,7 +460,7 @@ module Harnex
       end
 
       def attempt_live_summary_refresh
-        request("type" => "get_session_stats")
+        request({ "type" => "get_session_stats" })
       rescue StandardError
         nil
       end
@@ -350,6 +523,8 @@ module Harnex
           absorb_state_data(message["data"])
         when "get_session_stats"
           absorb_session_stats(message["data"])
+        when "set_model"
+          absorb_model(message["data"])
         end
       end
 
@@ -358,6 +533,11 @@ module Harnex
         when "agent_start", "turn_start"
           @state = :busy
         when "agent_end"
+          # agent_end is a low-level run boundary. Pi may still retry, compact,
+          # or process queued continuations, so only agent_settled is idle.
+          @state = :busy
+          request_session_stats_async
+        when "agent_settled"
           @state = :prompt
           @last_completed_at = Time.now
           request_session_stats_async
@@ -375,8 +555,14 @@ module Harnex
       def absorb_state_data(data)
         return unless data.is_a?(Hash)
 
-        @state = data["isStreaming"] ? :busy : :prompt
-        @state = :busy if data["isCompacting"]
+        observed_busy = data["isStreaming"] || data["isCompacting"]
+        if observed_busy
+          @state = :busy
+        elsif @state != :busy
+          # An earlier get_state response may arrive after a prompt was accepted.
+          # Never let that stale idle snapshot downgrade an event-proven busy state.
+          @state = :prompt
+        end
         @summary_mutex.synchronize do
           @session_summary[:agent_session_id] = data["sessionId"] if data["sessionId"]
         end
@@ -474,7 +660,7 @@ module Harnex
 
       def ensure_open!
         raise "pi rpc client not started" unless @read_io && @write_io
-        raise "pi rpc disconnected" if @state == :disconnected
+        raise disconnect_diagnostic if @state == :disconnected
       end
 
       def connected?
@@ -494,7 +680,7 @@ module Harnex
         @disconnect_signaled = true
         @state = :disconnected
         fail_pending_requests(
-          error.is_a?(Exception) ? error : StandardError.new("pi rpc disconnected")
+          error.is_a?(Exception) ? error : StandardError.new(disconnect_diagnostic)
         )
         @disconnect_handler&.call(error)
       end
@@ -535,12 +721,25 @@ module Harnex
         @extra_args.reject { |a| a.is_a?(String) && a.start_with?("[harnex session id=") }
       end
 
+      def drain_stderr
+        loop do
+          chunk = @stderr_io.readpartial(4096)
+          @stderr_mutex.synchronize do
+            @stderr_tail << chunk
+            overflow = @stderr_tail.bytesize - STDERR_TAIL_BYTES
+            @stderr_tail = @stderr_tail.byteslice(overflow, STDERR_TAIL_BYTES) if overflow.positive?
+          end
+        end
+      rescue EOFError, IOError, Errno::EIO
+        nil
+      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]
+        stdin_io, stdout_io, stderr_io, wait_thr = Open3.popen3(spawn_env, *build_command, **opts)
+        [wait_thr.pid, stdin_io, stdout_io, stderr_io, wait_thr]
       end
 
       def blocked_message(state, enter_only:)

data/lib/harnex/commands/doctor.rb

@@ -4,17 +4,20 @@ require "optparse"
 module Harnex
   class Doctor
     MIN_CODEX_VERSION = Gem::Version.new("0.128.0")
+    MIN_PI_VERSION = Harnex::Adapters::Pi::MIN_RPC_VERSION
+    SUPPORTED_ADAPTERS = %w[codex pi].freeze
 
     def self.usage
       <<~TEXT
-        Usage: harnex doctor [--sweep] [--prune [--dry-run]]
+        Usage: harnex doctor [--adapter codex|pi|all] [--sweep] [--prune [--dry-run]]
 
-        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).
+        Runs static preflight checks for harnex adapter dependencies. Codex is
+        checked by default for backwards compatibility; select Pi explicitly
+        after installing or upgrading it.
 
         Options:
+          --adapter NAME
+                       Check codex, pi, or all (repeatable; default: codex)
           --sweep      Include a read-only report of harnex/tmux session drift
           --prune      Apply bounded harnex events/output/receipt retention pruning
           --dry-run    Preview --prune candidates without deleting
@@ -22,22 +25,25 @@ module Harnex
 
         Common patterns:
           harnex doctor
-          harnex doctor --sweep
+          harnex doctor --adapter pi
+          harnex doctor --adapter all --sweep
           harnex doctor --prune --dry-run
           harnex doctor --prune
           harnex doctor --help
 
         Gotchas:
           doctor validates local adapter prerequisites; it does not start sessions.
+          Pi RPC requires >= #{MIN_PI_VERSION} so `agent_settled` is available.
           --sweep is diagnostic only; it does not stop sessions or remove files.
           --dry-run must be paired with --prune.
-          Run it after installing or upgrading Codex CLI.
+          Run it after installing or upgrading a selected agent CLI.
       TEXT
     end
 
     def initialize(argv = [])
       @argv = argv.dup
       @options = {
+        adapters: [],
         sweep: false,
         prune: false,
         dry_run: false,
@@ -53,7 +59,7 @@ module Harnex
         return 0
       end
 
-      checks = [check_codex]
+      checks = selected_adapters.map { |name| name == "pi" ? check_pi : check_codex }
       retention = retention_payload
       summary = {
         ok: checks.all? { |c| c[:ok] } && retention.fetch(:ok, true),
@@ -69,7 +75,8 @@ module Harnex
 
     def parser
       @parser ||= OptionParser.new do |opts|
-        opts.banner = "Usage: harnex doctor [--sweep] [--prune [--dry-run]]"
+        opts.banner = "Usage: harnex doctor [--adapter codex|pi|all] [--sweep] [--prune [--dry-run]]"
+        opts.on("--adapter NAME", "Check codex, pi, or all (repeatable)") { |value| @options[:adapters] << value.to_s.downcase }
         opts.on("--sweep", "Include read-only session drift diagnostics") { @options[:sweep] = true }
         opts.on("--prune", "Apply retention pruning") { @options[:prune] = true }
         opts.on("--dry-run", "Preview --prune candidates without deleting") { @options[:dry_run] = true }
@@ -79,11 +86,25 @@ module Harnex
 
     def validate_options!
       return if @options[:help]
+
+      unknown = @options[:adapters] - SUPPORTED_ADAPTERS - ["all"]
+      unless unknown.empty?
+        raise OptionParser::InvalidArgument,
+              "--adapter must be one of #{(SUPPORTED_ADAPTERS + ["all"]).join(', ')}"
+      end
       return unless @options[:dry_run] && !@options[:prune]
 
       raise OptionParser::InvalidOption, "--dry-run requires --prune"
     end
 
+    def selected_adapters
+      requested = @options[:adapters]
+      return ["codex"] if requested.empty?
+      return SUPPORTED_ADAPTERS if requested.include?("all")
+
+      requested.uniq
+    end
+
     def retention_payload
       repo_root = Harnex.resolve_repo_root(Dir.pwd)
       if @options[:prune]
@@ -123,6 +144,33 @@ module Harnex
       result.merge(ok: true, found: version.to_s)
     end
 
+    def check_pi
+      result = { name: "pi", required: ">= #{MIN_PI_VERSION}" }
+
+      version_output, status = capture("pi --version")
+      if status.nil?
+        return result.merge(ok: false, error: "Pi CLI not found on PATH")
+      end
+      unless status.success?
+        return result.merge(ok: false, error: "pi --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 Pi version output")
+      end
+
+      if version < MIN_PI_VERSION
+        return result.merge(
+          ok: false,
+          found: version.to_s,
+          error: "Pi #{version} < required #{MIN_PI_VERSION}; run `pi update` before using the structured adapter"
+        )
+      end
+
+      result.merge(ok: true, found: version.to_s)
+    end
+
     def capture(command)
       output = `#{command} 2>&1`
       [output, $?]

data/lib/harnex/commands/run.rb

@@ -33,7 +33,7 @@ module Harnex
       --id --description --detach --tmux --host --port --watch --watch-file
       --stall-after --max-resumes --preset --context --meta
       --artifact-report --validation-report --cwd --root --timeout --inbox-ttl
-      --require-artifact-report --require-attribution --auto-stop --fast --legacy-pty
+      --require-artifact-report --require-attribution --auto-stop --on-done --fast --legacy-pty
       --allow-live-parent --help
     ].concat(TELEMETRY_FLAGS.keys).freeze
 
@@ -43,7 +43,7 @@ module Harnex
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
       --max-resumes --preset --context --meta --artifact-report
-      --validation-report --cwd --root --timeout --inbox-ttl
+      --validation-report --on-done --cwd --root --timeout --inbox-ttl
     ].concat(TELEMETRY_FLAGS.keys).freeze
 
     def self.usage(program_name = "harnex run")
@@ -64,6 +64,7 @@ module Harnex
           --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 accepted task completion from --context
+          --on-done CMD      Launch /bin/sh -c CMD once at the first typed work result
           --fast             (codex only) Use Codex service_tier="fast".
                              Default Codex runs force service_tier="flex".
           --meta JSON        Attach parsed JSON metadata to the started event
@@ -124,6 +125,8 @@ module Harnex
           Bare `--watch` enables the babysitter.
           --auto-stop requires --context. Structured Codex turns only count as
           accepted completion after command/tool activity or a Git delta.
+          --on-done CMD is trusted local shell input. Do not put secrets in CMD;
+          command lines may be visible to local process inspection.
           Every dispatch gets a harness-authored receipt. Workers may write only
           optional claims to HARNEX_ARTIFACT_CLAIMS_PATH; claims never accept work.
           Explicit --stall-after/--max-resumes values override --preset defaults.
@@ -145,6 +148,9 @@ 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.
+          Pi RPC requires Pi >= 0.80.4 (`harnex doctor --adapter pi`). Prefer
+            provider/model for Harnex --model, and explicitly pass child
+            --approve or --no-approve for deterministic project trust.
           Codex JSON-RPC: pass model as `-c model=NAME`, not `-m NAME`. The
             legacy PTY adapter (--legacy-pty) accepts `-m`.
       TEXT
@@ -174,6 +180,7 @@ module Harnex
         cwd: nil,
         root: nil,
         auto_stop: false,
+        on_done: nil,
         allow_live_parent: false,
         detach: false,
         tmux: false,
@@ -230,7 +237,7 @@ module Harnex
     end
 
     def run_detached(adapter, cli_name, child_args, repo_root)
-      Session.validate_binary!(adapter.build_command)
+      validate_adapter!(adapter)
 
       if @options[:tmux]
         run_in_tmux(cli_name, child_args, repo_root)
@@ -241,7 +248,7 @@ module Harnex
     end
 
     def run_watch_mode(adapter, repo_root)
-      Session.validate_binary!(adapter.build_command)
+      validate_adapter!(adapter)
 
       result = run_headless(adapter, repo_root, emit_payload: false)
       return result[:exit_code] unless result[:ok]
@@ -264,6 +271,7 @@ module Harnex
       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 += ["--on-done", @options[:on_done]] if @options[:on_done]
       tmux_cmd += ["--meta", JSON.generate(@options[:meta])] if @options[:meta]
       @options[:telemetry].each do |key, value|
         flag = TELEMETRY_KEYS_TO_FLAGS[key]
@@ -424,7 +432,21 @@ module Harnex
       raise OptionParser::InvalidOption, "harnex run: invalid config #{e.message}"
     end
 
+    def validate_adapter!(adapter)
+      configure_adapter_startup!(adapter)
+      Session.validate_binary!(adapter.build_command)
+      adapter.validate_runtime! if adapter.respond_to?(:validate_runtime!)
+    end
+
+    def configure_adapter_startup!(adapter)
+      return unless adapter.respond_to?(:configure_startup)
+
+      metadata = @options[:meta].is_a?(Hash) ? @options[:meta] : {}
+      adapter.configure_startup(model: metadata["model"], effort: metadata["effort"])
+    end
+
     def build_session(adapter, repo_root)
+      configure_adapter_startup!(adapter)
       watch = Harnex.build_watch_config(@options[:watch], repo_root)
       Session.new(
         adapter: adapter,
@@ -440,6 +462,7 @@ module Harnex
         require_artifact_report: @options[:require_artifact_report],
         inbox_ttl: @options[:inbox_ttl],
         auto_stop: @options[:auto_stop],
+        on_done: @options[:on_done],
         launch_cwd: history_cwd,
         child_cwd: session_child_cwd
       )
@@ -607,6 +630,11 @@ module Harnex
           @options[:context] = required_option_value("--context", Regexp.last_match(1))
         when "--auto-stop"
           @options[:auto_stop] = true
+        when "--on-done"
+          index += 1
+          @options[:on_done] = required_option_value(arg, argv[index])
+        when /\A--on-done=(.+)\z/
+          @options[:on_done] = required_option_value("--on-done", Regexp.last_match(1))
         when "--allow-live-parent"
           @options[:allow_live_parent] = true
         when "--require-attribution"
@@ -715,7 +743,7 @@ module Harnex
           nil
         when *VALUE_FLAGS
           index += 1
-        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|artifact-report|validation-report|cwd|root|timeout|inbox-ttl)=/
+        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|artifact-report|validation-report|on-done|cwd|root|timeout|inbox-ttl)=/
           nil
         when telemetry_equals_regex
           nil
@@ -736,7 +764,7 @@ module Harnex
         arg.start_with?(
           "--id=", "--description=", "--tmux=", "--host=", "--port=", "--watch=", "--watch-file=",
           "--stall-after=", "--max-resumes=", "--preset=", "--context=", "--meta=",
-          "--artifact-report=", "--validation-report=", "--cwd=", "--root=", "--timeout=", "--inbox-ttl=",
+          "--artifact-report=", "--validation-report=", "--on-done=", "--cwd=", "--root=", "--timeout=", "--inbox-ttl=",
           *TELEMETRY_EQUALS_PREFIXES
         )
     end