harnex 0.12.0 → 0.29.0

data/lib/harnex/adapters/pi.rb

@@ -2,6 +2,7 @@ require "json"
 require "open3"
 require "rubygems/version"
 require "timeout"
+require_relative "../owned_process_group"
 
 module Harnex
   module Adapters
@@ -83,13 +84,40 @@ module Harnex
         ["pi", "--mode", "rpc"]
       end
 
+      TRUST_FLAGS = %w[--approve -a --no-approve -na].freeze
+      HARNEX_MCP_TOOLS = %w[ask delegate result reply land discard lanes].map { |tool| "mcp__harnex__#{tool}" }.freeze
+      MCP_VERSION = Gem::Version.new("0.99.0")
+      NO_MCP_VERSION = Gem::Version.new("1.0.4")
+
       def build_command
         args = cli_extra_args
+        # RPC cannot show Pi's project-trust prompt: ignore project-local
+        # resources unless the caller passes --approve (#87).
+        args = ["--no-approve"] + args unless args.any? { |arg| TRUST_FLAGS.include?(arg) }
+        args = guard_mcp(args)
         args += ["--model", @startup_model] if @startup_model
         args += ["--thinking", @startup_effort] if @startup_effort
         base_command + args
       end
 
+      # #87: a worker never gets harnex's own MCP tools, so it cannot launch
+      # more workers (recursion) or escape a read-only ask through delegate.
+      # Pi >= 1.0.4 keeps MCP tools despite a --tools allowlist, so an
+      # allowlisted (read-only) worker runs with --no-mcp.
+      def guard_mcp(args)
+        version = parsed_agent_version
+        return args unless version && version >= MCP_VERSION
+        return args if args.include?("--no-mcp")
+        return args + ["--no-mcp"] if version >= NO_MCP_VERSION && (args & %w[--tools -t]).any?
+
+        index = args.index("--exclude-tools") || args.index("-xt")
+        return args + ["--exclude-tools", HARNEX_MCP_TOOLS.join(",")] unless index && args[index + 1]
+
+        merged = args.dup
+        merged[index + 1] = ([args[index + 1]] + HARNEX_MCP_TOOLS).join(",")
+        merged
+      end
+
       def configure_startup(model: nil, effort: nil)
         requested_model = model.to_s.strip
         requested_effort = effort.to_s.strip
@@ -146,9 +174,16 @@ module Harnex
         }
       end
 
-      def build_send_payload(text:, submit:, enter_only:, screen_text:, force: false)
+      # Pi queues a `followUp` prompt itself and delivers it when the running
+      # turn ends (before agent_settled), so a busy send never expires (#79).
+      def follow_up_supported?
+        true
+      end
+
+      def build_send_payload(text:, submit:, enter_only:, screen_text:, force: false, follow_up: false)
         state = input_state(nil)
-        if !force && submit && !enter_only && state[:input_ready] != true
+        follow_up = follow_up && !force && state[:state] == "busy"
+        if !force && !follow_up && submit && !enter_only && state[:input_ready] != true
           raise ArgumentError, blocked_message(state, enter_only: enter_only)
         end
 
@@ -157,6 +192,7 @@ module Harnex
 
         dispatch = { prompt: text.to_s }
         dispatch[:streaming_behavior] = "steer" if force && state[:state] == "busy"
+        dispatch[:streaming_behavior] = "followUp" if follow_up
         {
           dispatch: dispatch,
           input_state: state,
@@ -176,8 +212,15 @@ module Harnex
         @disconnect_handler = block
       end
 
+      # Called once IO/PID ownership is installed, before any protocol writes.
+      # The owner should only publish readiness/schedule work, not block here.
+      def on_spawn(&block)
+        @spawn_handler = block
+      end
+
       def start_rpc(env: nil, cwd: nil, read_io: nil, write_io: nil, pid: nil)
         if read_io && write_io
+          @owned_process_group = nil
           @read_io = read_io
           @write_io = write_io
           @pid = pid
@@ -189,6 +232,7 @@ module Harnex
         @closed = false
         @disconnect_signaled = false
         @state = :prompt
+        @spawn_handler&.call(@pid)
         @stderr_thread = Thread.new { drain_stderr } if @stderr_io
         @reader_thread = Thread.new { read_loop }
         request_state_async
@@ -200,8 +244,10 @@ module Harnex
         apply_dispatch_overrides(model: model, effort: effort) unless @state == :busy
         payload = { "type" => "prompt", "message" => prompt.to_s }
         payload["streamingBehavior"] = streaming_behavior if streaming_behavior
-        request(payload)
+        # Events may settle a fast run before the prompt response wakes us.
+        # Mark busy before writing, never after the response.
         @state = :busy
+        request(payload)
         nil
       end
 
@@ -291,23 +337,32 @@ module Harnex
       end
 
       def terminate_subprocess(term_grace_seconds: STOP_TERM_GRACE_SECONDS, kill_grace_seconds: STOP_KILL_GRACE_SECONDS)
-        return false unless @pid
+        if @owned_process_group
+          return @owned_process_group.terminate(
+            term_grace_seconds: term_grace_seconds,
+            kill_grace_seconds: kill_grace_seconds
+          )
+        end
+
+        # Injected IO/PID callers retain direct-PID behavior, never group rights.
+        pid = @pid
+        return false unless pid
 
         begin
-          Process.kill("TERM", @pid)
+          Process.kill("TERM", pid)
         rescue Errno::ESRCH
           return true
         end
 
-        return true if wait_for_process_exit(@pid, term_grace_seconds)
+        return true if wait_for_process_exit(pid, term_grace_seconds)
 
         begin
-          Process.kill("KILL", @pid)
+          Process.kill("KILL", pid)
         rescue Errno::ESRCH
           return true
         end
 
-        wait_for_process_exit(@pid, kill_grace_seconds)
+        wait_for_process_exit(pid, kill_grace_seconds)
       end
 
       def pid
@@ -324,6 +379,9 @@ module Harnex
                    process_status
                  end
         @pid = nil
+        # Reaping can beat event/EOF processing. Bound an actual blocked read,
+        # not a local Session callback doing receipt/output I/O on this thread.
+        wait_for_reader_drain
         status
       rescue Errno::ECHILD
         @pid = nil
@@ -465,10 +523,25 @@ module Harnex
         nil
       end
 
+      def wait_for_reader_drain(timeout: 2.0)
+        exited_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        while @reader_thread&.alive?
+          @reader_thread.join(0.05)
+          read_started = @read_wait_started_at
+          next unless @reader_thread.alive? && read_started
+          next if Process.clock_gettime(Process::CLOCK_MONOTONIC) - [read_started, exited_at].max < timeout
+
+          signal_disconnect(Timeout::Error.new("pi rpc output did not close after process exit"))
+          break
+        end
+      end
+
       def read_loop
         buffer = +""
         loop do
+          @read_wait_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           chunk = @read_io.readpartial(4096)
+          @read_wait_started_at = nil
           buffer << chunk
 
           while (idx = buffer.index("\n"))
@@ -481,16 +554,22 @@ module Harnex
           end
         end
       rescue EOFError, IOError, Errno::EIO
-        nil
+        @read_wait_started_at = nil
+        if buffer.b.match?(/[^\t\n\v\f\r ]/n)
+          signal_disconnect(JSON::ParserError.new("pi rpc unterminated JSONL record at EOF"))
+        end
       ensure
+        @read_wait_started_at = nil
+        buffer&.clear
         signal_disconnect(nil)
       end
 
       def handle_line(line)
         message = JSON.parse(line)
         handle_message(message)
-      rescue JSON::ParserError => e
-        signal_disconnect(e)
+      rescue JSON::ParserError
+        # Parser diagnostics can quote arbitrary payloads, including thinking.
+        signal_disconnect(JSON::ParserError.new("pi rpc malformed JSONL record"))
       end
 
       def handle_message(message)
@@ -736,9 +815,10 @@ module Harnex
 
       def spawn_subprocess(env, cwd)
         spawn_env = env || {}
-        opts = {}
+        opts = { pgroup: true }
         opts[:chdir] = cwd if cwd
         stdin_io, stdout_io, stderr_io, wait_thr = Open3.popen3(spawn_env, *build_command, **opts)
+        @owned_process_group = OwnedProcessGroup.new(wait_thr.pid)
         [wait_thr.pid, stdin_io, stdout_io, stderr_io, wait_thr]
       end
 

data/lib/harnex/adapters.rb

@@ -1,7 +1,5 @@
 require_relative "adapters/base"
 require_relative "adapters/generic"
-require_relative "adapters/codex"
-require_relative "adapters/codex_appserver"
 require_relative "adapters/claude"
 require_relative "adapters/opencode"
 require_relative "adapters/pi"
@@ -18,20 +16,8 @@ module Harnex
       !key.to_s.strip.empty?
     end
 
-    # 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`); kept as a long-term supported
-    # fallback for interactive/TUI use cases.
-    def codex_appserver_enabled?
-      true
-    end
-
-    def build(key, extra_args = [], legacy_pty: false)
+    def build(key, extra_args = [])
       key_str = key.to_s
-      if key_str == "codex"
-        return legacy_pty ? Codex.new(extra_args) : CodexAppServer.new(extra_args)
-      end
-
       adapter_class = registry[key_str]
       return adapter_class.new(extra_args) if adapter_class
 
@@ -41,7 +27,6 @@ module Harnex
     def registry
       @registry ||= {
         "claude" => Claude,
-        "codex" => Codex,
         "opencode" => Opencode,
         "pi" => Pi
       }

data/lib/harnex/artifact_report.rb

@@ -1,6 +1,7 @@
 require "digest"
 require "fileutils"
 require "json"
+require "shellwords"
 require "time"
 
 module Harnex
@@ -14,11 +15,17 @@ module Harnex
     MAX_STRING_LENGTH = 2_000
     MAX_DIAGNOSTICS = 100
     MAX_CHANGED_PATHS = 200
+    MAX_FINAL_GATES = 20
     RECEIPT_VERSION = 1
     CLAIM_SEVERITIES = %w[P1 P2 P3].freeze
-    COMMAND_OBSERVATION_STATUSES = %w[observed unsupported].freeze
+    COMMAND_OBSERVATION_STATUSES = %w[observed partial unsupported].freeze
     GIT_OBSERVATION_STATUSES = %w[observed unavailable].freeze
     USAGE_STATUSES = %w[observed estimated unsupported missing zero].freeze
+    FINAL_GATE_STATUSES = %w[pass fail unknown undeclared].freeze
+    # Shells a structured adapter may wrap a model command in (`bash -lc
+    # '<cmd>'`). Unwrapping that transport layer is not fuzzy matching: the
+    # inner script must still equal the declared gate exactly.
+    FINAL_GATE_SHELLS = %w[sh bash zsh dash].freeze
 
     REPORT_STATUSES = %w[in_progress pass fail blocked unknown].freeze
     VALIDATION_STATUSES = %w[in_progress pass fail not_run unknown].freeze
@@ -252,24 +259,93 @@ module Harnex
       {}
     end
 
+    # Declared final gates as given to `harnex run --final-gate` (or meta
+    # `final_gates`): non-empty, bounded, de-duplicated, order kept.
+    def normalize_final_gates(value)
+      Array(value).filter_map do |gate|
+        next unless gate.is_a?(String)
+
+        text = gate.strip
+        text.empty? ? nil : bounded_string(text)
+      end.uniq.first(MAX_FINAL_GATES)
+    end
+
+    def final_gate_matches?(gate, command)
+      return false unless gate.is_a?(String) && command.is_a?(String)
+      return true if command == gate
+
+      inner = shell_wrapped_script(command)
+      !inner.nil? && inner == gate
+    end
+
+    # gates: [{"cmd" => String, "exit_code" => Integer or nil}], where
+    # exit_code is the harness-observed exit of the gate's LAST run.
+    # A gate never observed fails only when command observation was complete;
+    # otherwise it may be among the unobserved calls and reads unknown.
+    def final_gates_summary(gates, command_observation:)
+      entries = Array(gates).filter_map do |gate|
+        next unless gate.is_a?(Hash) && non_empty_string?(gate["cmd"])
+
+        { "cmd" => bounded_string(gate["cmd"]), "exit_code" => integer_or_nil(gate["exit_code"]) }
+      end.first(MAX_FINAL_GATES)
+      return { "declared" => 0, "observed_pass" => 0, "status" => "undeclared" } if entries.empty?
+
+      passed = entries.count { |entry| entry["exit_code"]&.zero? }
+      failed = entries.count { |entry| entry["exit_code"] && !entry["exit_code"].zero? }
+      missing = entries.count { |entry| entry["exit_code"].nil? }
+      status = if failed.positive?
+                 "fail"
+               elsif missing.positive?
+                 command_observation.to_s == "observed" ? "fail" : "unknown"
+               else
+                 "pass"
+               end
+      {
+        "declared" => entries.length,
+        "observed_pass" => passed,
+        "observed_fail" => failed,
+        "missing" => missing,
+        "status" => status,
+        "gates" => entries
+      }
+    end
+
     def build_observed(
       id:, session_id:, generated_at:, successful:, outcome_status:,
       outcome_summary:, git:, commands:, turn:, usage:, claims:,
-      command_observation:
+      command_observation:, stop: nil, commands_unobserved: 0,
+      final_gates: nil, commands_had_failures: nil
     )
       observed_commands = compact_commands(commands).select do |entry|
         non_empty_string?(entry["cmd"]) && entry["exit_code"].is_a?(Integer)
       end
+      unobserved = non_negative_integer_or_nil(commands_unobserved).to_i
       git_payload = compact_observed_git(git)
       turn_payload = compact_observed_turn(turn)
       usage_payload = compact_observed_usage(usage)
       claims_payload = compact_claims(claims)
-      validation_status = if observed_commands.empty?
+      # The session tracks failures across its whole history; the retained
+      # command window is capped, so it is only the fallback.
+      had_failures = if commands_had_failures.nil?
+                       observed_commands.any? { |entry| !entry["exit_code"].zero? }
+                     else
+                       !!commands_had_failures
+                     end
+      gates = final_gates_summary(final_gates, command_observation: command_observation)
+      # Declared final gates decide validation; exploratory failures before a
+      # green final run stay visible in commands_had_failures (#68). Without
+      # gates, commands that ran without structured exit evidence keep an
+      # otherwise clean history from reading as a pass.
+      validation_status = if gates["status"] != "undeclared"
+                            gates["status"]
+                          elsif had_failures
+                            "fail"
+                          elsif unobserved.positive?
+                            "unknown"
+                          elsif observed_commands.empty?
                             "not_run"
-                          elsif observed_commands.all? { |entry| entry["exit_code"].zero? }
-                            "pass"
                           else
-                            "fail"
+                            "pass"
                           end
       start_sha = git_payload["start_sha"].to_s
       end_sha = git_payload["end_sha"].to_s
@@ -287,7 +363,9 @@ module Harnex
         "validation" => {
           "status" => validation_status,
           "commands" => observed_commands,
-          "final_reported" => true
+          "final_reported" => true,
+          "commands_had_failures" => had_failures,
+          "final_gates" => gates
         },
         "artifacts" => [],
         "receipt" => {
@@ -305,6 +383,8 @@ module Harnex
           "usage" => usage_payload
         }
       }
+      report["observed"]["commands_unobserved"] = unobserved if unobserved.positive?
+      report["observed"]["stop"] = compact_observed_stop(stop) if stop
       report["claims"] = claims_payload unless claims_payload.empty?
       fit_observed_report!(report)
     end
@@ -461,12 +541,61 @@ module Harnex
       end
 
       validate_commands(value["commands"], diagnostics) if value.key?("commands")
-      if value.key?("final_reported") && !boolean?(value["final_reported"])
+      %w[final_reported commands_had_failures].each do |key|
+        next unless value.key?(key) && !boolean?(value[key])
+
         diagnostics << diagnostic(
           "boolean_required",
-          "$.validation.final_reported",
-          "validation.final_reported must be true or false"
+          "$.validation.#{key}",
+          "validation.#{key} must be true or false"
+        )
+      end
+      validate_final_gates(value["final_gates"], diagnostics) if value.key?("final_gates")
+    end
+
+    def validate_final_gates(value, diagnostics)
+      unless value.is_a?(Hash)
+        diagnostics << diagnostic("object_required", "$.validation.final_gates", "validation.final_gates must be an object")
+        return
+      end
+
+      unless FINAL_GATE_STATUSES.include?(value["status"])
+        diagnostics << diagnostic(
+          "enum",
+          "$.validation.final_gates.status",
+          "validation.final_gates.status must be one of #{FINAL_GATE_STATUSES.join(', ')}"
+        )
+      end
+      %w[declared observed_pass observed_fail missing].each do |key|
+        next if !value.key?(key) && !%w[declared observed_pass].include?(key)
+        next if value[key].is_a?(Integer) && value[key] >= 0
+
+        diagnostics << diagnostic(
+          "integer_required",
+          "$.validation.final_gates.#{key}",
+          "validation.final_gates.#{key} must be a non-negative integer"
+        )
+      end
+      return unless value.key?("gates")
+
+      unless value["gates"].is_a?(Array) && value["gates"].length <= MAX_FINAL_GATES
+        diagnostics << diagnostic(
+          "array_required",
+          "$.validation.final_gates.gates",
+          "validation.final_gates.gates must be an array of at most #{MAX_FINAL_GATES} gates"
         )
+        return
+      end
+      value["gates"].each_with_index do |gate, index|
+        path = "$.validation.final_gates.gates[#{index}]"
+        unless gate.is_a?(Hash)
+          diagnostics << diagnostic("object_required", path, "final gate must be an object")
+          next
+        end
+        validate_required_string(gate, "cmd", "#{path}.cmd", diagnostics)
+        next if gate["exit_code"].nil? || gate["exit_code"].is_a?(Integer)
+
+        diagnostics << diagnostic("integer_required", "#{path}.exit_code", "final gate exit_code must be an integer or null")
       end
     end
 
@@ -624,14 +753,18 @@ module Harnex
       if value.key?("commands_truncated") && !boolean?(value["commands_truncated"])
         diagnostics << diagnostic("boolean_required", "$.observed.commands_truncated", "observed.commands_truncated must be true or false")
       end
+      if value.key?("commands_unobserved") && !(value["commands_unobserved"].is_a?(Integer) && value["commands_unobserved"] >= 0)
+        diagnostics << diagnostic("integer_required", "$.observed.commands_unobserved", "observed.commands_unobserved must be a non-negative integer")
+      end
       unless COMMAND_OBSERVATION_STATUSES.include?(value["command_observation"])
         diagnostics << diagnostic(
           "enum",
           "$.observed.command_observation",
-          "observed.command_observation must be observed or unsupported"
+          "observed.command_observation must be observed, partial, or unsupported"
         )
       end
 
+      validate_observed_stop(value["stop"], diagnostics) if value.key?("stop")
       turn = value["turn"]
       unless turn.is_a?(Hash)
         diagnostics << diagnostic("object_required", "$.observed.turn", "observed.turn must be an object")
@@ -657,6 +790,30 @@ module Harnex
       end
     end
 
+    def validate_observed_stop(value, diagnostics)
+      path = "$.observed.stop"
+      unless value.is_a?(Hash)
+        diagnostics << diagnostic("object_required", path, "observed.stop must be an object")
+        return
+      end
+      { "reason" => StopRequest::REASONS, "origin" => StopRequest::ORIGINS,
+        "work_state" => StopRequest::WORK_STATES }.each do |key, allowed|
+        next if allowed.include?(value[key])
+
+        diagnostics << diagnostic("enum", "#{path}.#{key}", "stop #{key} is not supported")
+      end
+      validate_required_string(value, "requested_at", "#{path}.requested_at", diagnostics)
+      begin
+        Time.iso8601(value["requested_at"].to_s)
+      rescue ArgumentError
+        diagnostics << diagnostic("timestamp_required", "#{path}.requested_at", "stop timestamp must be ISO 8601")
+      end
+      if value.key?("runtime_limit_s") &&
+         !(finite_number?(value["runtime_limit_s"]) && value["runtime_limit_s"].positive?)
+        diagnostics << diagnostic("number_required", "#{path}.runtime_limit_s", "runtime limit must be finite and positive")
+      end
+    end
+
     def validate_final_contract(report, diagnostics)
       if harness_receipt?(report)
         validate_observed_final_contract(report, diagnostics)
@@ -908,9 +1065,11 @@ module Harnex
         "git" => compact_observed_git(value["git"]),
         "commands" => compact_commands(value["commands"]),
         "commands_truncated" => boolean_or_nil(value["commands_truncated"]),
+        "commands_unobserved" => non_negative_integer_or_nil(value["commands_unobserved"]),
         "command_observation" => bounded_string_or_nil(value["command_observation"]),
         "turn" => compact_observed_turn(value["turn"]),
-        "usage" => compact_observed_usage(value["usage"])
+        "usage" => compact_observed_usage(value["usage"]),
+        "stop" => compact_observed_stop(value["stop"])
       }
       payload.delete_if { |_key, item| item.nil? }
       payload.empty? ? nil : payload
@@ -955,6 +1114,17 @@ module Harnex
       payload
     end
 
+    def compact_observed_stop(value)
+      return nil unless value.is_a?(Hash)
+
+      payload = %w[reason origin work_state requested_at].to_h do |key|
+        [key, bounded_string_or_nil(hash_value(value, key))]
+      end
+      limit = finite_float_or_nil(hash_value(value, "runtime_limit_s"))
+      payload["runtime_limit_s"] = limit unless limit.nil?
+      payload
+    end
+
     def compact_observed_usage(value)
       value = {} unless value.is_a?(Hash)
       payload = {}
@@ -995,10 +1165,34 @@ module Harnex
       payload["status"] = bounded_string_or_nil(value["status"])
       payload["commands"] = compact_commands(value["commands"])
       payload["final_reported"] = !!value["final_reported"] if value.key?("final_reported")
+      payload["commands_had_failures"] = value["commands_had_failures"] if boolean?(value["commands_had_failures"])
+      payload["final_gates"] = compact_final_gates(value["final_gates"])
       payload.delete_if { |_key, item| item.nil? || item == [] }
       payload.empty? ? nil : payload
     end
 
+    # Dispatch rows keep the counts and status, not the gate command text.
+    def compact_final_gates(value)
+      return nil unless value.is_a?(Hash) && FINAL_GATE_STATUSES.include?(value["status"])
+
+      compact = { "status" => value["status"] }
+      %w[declared observed_pass observed_fail missing].each do |key|
+        compact[key] = value[key] if value[key].is_a?(Integer) && value[key] >= 0
+      end
+      compact
+    end
+
+    def shell_wrapped_script(command)
+      words = Shellwords.split(command)
+      return nil unless words.length == 3
+      return nil unless FINAL_GATE_SHELLS.include?(File.basename(words[0]))
+      return nil unless %w[-c -lc].include?(words[1])
+
+      words[2]
+    rescue ArgumentError
+      nil
+    end
+
     def compact_commands(value)
       Array(value).first(MAX_COMMANDS).filter_map do |entry|
         next unless entry.is_a?(Hash)