harnex 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25ba2b12b69cc6351e2ca4ee1e72e5f378a3828f7486498a2e2a026cf9da771b
-  data.tar.gz: 7e3cc95587c16dcb0a7b9a3e8339546a9ffbe085e4517407f1325e87fd2f45ce
+  metadata.gz: bcf0c88485eceb630094f32cd520c12f6c3d5915f2e2b7790191c2ed98a236a5
+  data.tar.gz: f228c15c98a47d69b5b4c7129373f88d5eb42f6413ac998995294ef3271d99e3
 SHA512:
-  metadata.gz: fcaa6d99632c375c1315bfc553b99ccf5c583b58a52e627e0af951493481bf33af9b5de50ca4704a1e6e2d7d9a8aa6999b42d94347ff942b76ac5033eb870dae
-  data.tar.gz: 929011b78aa399cc098b644f0bb2a0995222df71698e450e7ab4785e1be9249e07e4d40225fbf80e02ea9a11f6fefd7913c27682110944ccadacea8f879e7200
+  metadata.gz: e3e6e7d4fe9b88ace781c9c9bc587316fce5e405063e6a575ddf5f46b4b76f6a05f7892e36656b7ef0b9160a5ad6890c1af5fe8e83ecd993c14d229c9a7d1468
+  data.tar.gz: c043e50074d2100651cbc22585f7d046f5621c51a5ea6d0433d24200f174df98c7fdfd4ea1ec46633cfeae496776c82b08e177abdae7abe547d2244da4f66be0

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.11.0] - 2026-08-14 | 01:03 PM | IST
+
+### Fixed
+
+- Pi RPC completion now fences on Pi 0.80.4+'s `agent_settled` event instead of
+  the lower-level `agent_end`. Provider retries, compaction recovery, and queued
+  continuations can no longer publish premature `task_complete` or open the
+  inbox early. Final `error`, `aborted`, and `length` stop reasons fail closed;
+  a settled run without an authoritative final assistant reason also fails.
+- Pi 0.84's breaking delta-only `message_update` shape is correlated from
+  `message_start` through authoritative `message_end`, preserving streamed
+  output without duplicating the final message.
+- Harnex `--model` and `--effort` now become supported Pi `--model` /
+  `--thinking` startup controls and are verified through RPC `get_state`,
+  instead of adding ignored fields to `prompt` or persisting RPC setters into
+  the user's Pi defaults. Model mismatches and clamped effort requests fail
+  before prompting, telemetry distinguishes requested from observed effective
+  model values, and forced busy sends use Pi's `steer` streaming behavior.
+- Pi RPC request waits are bounded, subprocess stderr is continuously drained
+  into a bounded diagnostic tail, and process status is read from Open3's wait
+  thread instead of racing it with a second `waitpid` and potentially losing a
+  nonzero exit status.
+
+### Changed
+
+- **Compatibility:** structured Pi dispatch now requires Pi >= 0.80.4. Both
+  foreground and detached/tmux launches validate the installed version before
+  spawn. This is the first Pi release with the final `agent_settled` fence.
+- Pi retry/compaction events retain settlement state and expose current
+  summarization-retry lifecycle events in Harnex's event stream.
+- Codex schema fixtures are refreshed against CLI 0.147.0 after a bounded
+  semantic review. The drift is limited to a string path-alias replacement and
+  additive optional thread/item fields that Harnex does not consume; existing
+  minimal response fixtures still validate, so no Codex adapter behavior
+  changes.
+
+### Added
+
+- `harnex doctor --adapter pi` statically verifies the Pi RPC version;
+  `--adapter all` checks both Pi and Codex while the no-argument default remains
+  Codex-compatible.
+- `docs/pi-rpc.md` documents transport semantics, project trust, lifecycle,
+  model controls, telemetry, and known boundaries. An opt-in live contract test
+  (`PI_INTEGRATION=1`) verifies the installed Pi event shape without adding
+  provider cost to the normal suite.
+
 ## [0.10.2] - 2026-08-08 | 06:49 PM | IST
 
 Docs-only patch: no library or CLI behavior changes. Released so the

data/README.md

@@ -12,8 +12,8 @@ gem install harnex
 
 Harnex itself requires **Ruby 3.x** and uses only the Ruby standard
 library. Install the CLIs you want to wrap separately; Codex JSON-RPC
-support requires Codex CLI **0.128.0 or newer**, and tmux-backed
-workflows require `tmux`.
+support requires Codex CLI **0.128.0 or newer**, Pi structured RPC requires
+Pi **0.80.4 or newer**, and tmux-backed workflows require `tmux`.
 
 Then ask the CLI what to do next:
 
@@ -23,8 +23,15 @@ harnex --help
 harnex agents-guide
 ```
 
-If you use Codex, run `harnex doctor` after installing or upgrading the
-Codex CLI. It verifies the local `codex app-server` prerequisite.
+Run the matching static check after installing or upgrading an agent CLI:
+
+```bash
+harnex doctor --adapter codex
+harnex doctor --adapter pi
+```
+
+These verify the local structured-transport version prerequisites without
+starting a model turn.
 
 `harnex agents-guide` is the agent-facing reference for dispatch, chain,
 buddy, monitoring, and naming patterns. It is packaged in the gem; no skills
@@ -106,7 +113,7 @@ an explicit working-directory/root selector for automation.
 |-------|---------|
 | Claude Code | PTY adapter with prompt detection, stop sequence, workspace trust, and vim mode handling |
 | OpenAI Codex | JSON-RPC `codex app-server` adapter by default; PTY mode remains supported for TUI/interactive use via `--legacy-pty` |
-| Pi | JSONL RPC adapter (`pi --mode rpc`) with structured completion, tool events, extension-UI auto-cancel, and session stats telemetry |
+| Pi | JSONL RPC adapter (`pi --mode rpc`, Pi >= 0.80.4) with settled completion, typed failures, tool/retry events, extension-UI auto-cancel, and session stats telemetry |
 | OpenCode | PTY adapter with native Ctrl+C stop handling and OpenCode-specific prompt/readiness heuristics |
 | Any terminal CLI | Generic PTY wrapping with local API, logs, status, and best-effort prompt detection |
 
@@ -121,9 +128,15 @@ terminal UI or PTY-only Codex flags. The flag name is historical; the PTY path
 is still supported.
 
 `harnex run pi` launches `pi --mode rpc` and sends `--context` as a structured
-`prompt` command (not a CLI positional argument). Pass Pi child flags after the
-separator, for example:
+`prompt` command (not a CLI positional argument). Harnex `--model` / `--effort`
+flags become Pi `--model` / `--thinking` startup controls and are verified over
+RPC before the prompt; use a deterministic `provider/model` value. Pass other
+Pi startup flags after the separator, for example:
 `harnex run pi --context "Implement X" -- --model anthropic/claude-sonnet-4-5 --thinking high`.
+For unattended runs, explicitly choose Pi project trust with child
+`--approve` or `--no-approve`; Harnex never auto-trusts repository code.
+See [docs/pi-rpc.md](docs/pi-rpc.md) for lifecycle, compatibility, and failure
+semantics.
 
 ## Multi-agent workflows
 
@@ -231,6 +244,8 @@ Choose the wait/watch predicate that matches how you launched the worker:
   `harnex wait --id ID --until task_complete --timeout SECS` when you need the
   exact successful-turn event instead of terminal-exit fallback. Use
   `--until task_failed` to wait specifically for a failed structured turn.
+  Pi completion is fenced on `agent_settled`, not the earlier `agent_end`, so
+  retries, compaction recovery, and queued continuations finish first.
 - `harnex send --wait-for-idle` is an atomic send fence for PTY-style
   interactions. It proves the turn returned to an idle/prompt state, not that
   your acceptance criteria passed.

data/TECHNICAL.md

@@ -363,6 +363,8 @@ Each adapter in `lib/harnex/adapters/` implements:
 | `inject_exit(writer)`     | Send adapter-specific stop text |
 | `infer_repo_path(argv)`   | Extract repo path from CLI args |
 | `wait_for_sendable(...)`  | Wait strategy before sending    |
+| `transport`                | PTY, JSON-RPC, or JSONL RPC     |
+| `validate_runtime!`        | Optional version/capability gate |
 
 ### Input States
 
@@ -404,6 +406,29 @@ The adapter reads the screen and returns a state hash:
 - See `docs/codex-appserver.md` for the full mapping table and
   troubleshooting.
 
+### Pi Adapter (JSONL RPC)
+
+- `transport :stdio_jsonl_rpc` launches `pi --mode rpc` and speaks Pi's
+  strict LF-delimited JSONL protocol. It is not JSON-RPC 2.0.
+- Requires Pi >= 0.80.4 and fails before spawn when the installed version
+  cannot provide the final `agent_settled` fence. Verify with
+  `harnex doctor --adapter pi`.
+- `agent_end` remains busy because retry, compaction recovery, or a queued
+  continuation may follow. `agent_settled` inspects the authoritative final
+  assistant `stopReason`: `stop` completes; `error`, `aborted`, `length`, a
+  missing reason, or an unknown reason fails closed.
+- Pi >= 0.84 emits delta-only `message_update` events. Harnex correlates those
+  deltas with `message_start` / `message_end` and does not depend on the removed
+  cumulative message snapshot.
+- Harnex `--model` and `--effort` become Pi `--model` / `--thinking`
+  startup flags and are verified with `get_state`; a model mismatch or clamped
+  effort is rejected before prompting without persisting an RPC model switch
+  into Pi's user defaults. Forced busy sends use `streamingBehavior=steer`.
+- RPC requests have a 30-second response bound. Stderr is continuously drained
+  into a bounded diagnostic tail, and subprocess status comes from Open3's wait
+  thread instead of racing it with another `waitpid`.
+- See `docs/pi-rpc.md` for trust policy, telemetry, and compatibility details.
+
 #### Codex Adapter (legacy PTY — `--legacy-pty`, long-term fallback)
 
 - Launches with `--no-alt-screen` for inline screen output

data/docs/pi-rpc.md

@@ -0,0 +1,151 @@
+# Pi RPC adapter
+
+Harnex runs Pi workers over Pi's structured subprocess protocol rather than
+scraping the TUI:
+
+```text
+harnex run pi  ->  pi --mode rpc  ->  LF-delimited JSON objects on stdio
+```
+
+Pi RPC is JSONL, not JSON-RPC 2.0. Codex uses `codex app-server` JSON-RPC;
+Harnex presents the same run/send/wait/events control surface over both.
+
+## Compatibility
+
+Harnex requires Pi **0.80.4 or newer** for structured dispatch. Pi 0.80.4 added
+`agent_settled`, the first lifecycle event that guarantees no automatic retry,
+compaction recovery, or queued continuation remains. `agent_end` is only a
+low-level run boundary and is never accepted as Harnex work completion.
+
+Check the installed transport before unattended work:
+
+```bash
+harnex doctor --adapter pi
+```
+
+`harnex run pi` also checks the version before spawn and fails closed when the
+version cannot be parsed or predates 0.80.4. The current contract was live
+verified against Pi 0.84.1.
+
+Pi 0.84.0 removed cumulative message snapshots from `message_update`. Harnex
+therefore assembles output from `assistantMessageEvent` deltas between
+`message_start` and authoritative `message_end` events. This remains compatible
+with Pi 0.80.4-0.83.x and avoids printing the final message twice on 0.84+.
+
+## Dispatch
+
+```bash
+harnex run pi --id cx-i-42 --tmux cx-i-42 \
+  --context "Implement issue 42 and run tests" --auto-stop
+
+harnex wait --id cx-i-42 --until task_complete --timeout 3600
+harnex events --id cx-i-42
+```
+
+`--context` is sent as an RPC `prompt` command; it is not passed as a Pi
+positional argument.
+
+Harnex model and effort flags are active controls, not telemetry-only labels:
+
+```bash
+harnex run pi \
+  --model anthropic/claude-sonnet-4-5 --effort high \
+  --context "Review the change" --auto-stop
+```
+
+Harnex maps those controls to Pi `--model` / `--thinking` startup flags, then
+verifies the effective values with RPC `get_state` before prompting. This avoids
+`set_model` / `set_thinking_level` persisting a dispatch override into the
+user's Pi defaults. Use `provider/model` for deterministic dispatch. Harnex
+fails before the prompt if Pi cannot apply the requested model or thinking level
+exactly, so requested and effective policy cannot silently diverge. Direct
+adapter callers can still use Pi's RPC setters for an intentional mid-session
+switch.
+
+Pass Pi startup flags after `--`:
+
+```bash
+harnex run pi --context "Implement X" --auto-stop -- \
+  --no-session --no-extensions --model anthropic/claude-sonnet-4-5
+```
+
+When both Harnex `--model` and a Pi child `--model` are supplied, the Harnex
+startup override is appended last and is authoritative for that dispatch.
+
+## Project trust
+
+Pi 0.79 added project trust. RPC mode cannot show the interactive trust prompt;
+an unresolved project follows Pi's global `defaultProjectTrust` policy. Harnex
+does not auto-trust repository code.
+
+For deterministic unattended runs, choose explicitly after reviewing the
+repository:
+
+```bash
+# Load trusted project-local .pi settings, packages, and extensions
+harnex run pi --context "..." -- --approve
+
+# Ignore project-local executable resources
+harnex run pi --context "..." -- --no-approve
+```
+
+Context files continue to follow Pi's documented trust behavior. Third-party or
+project extensions execute with the worker's OS privileges; `--approve` is a
+security decision, not merely a prompt-suppression flag.
+
+## Lifecycle and failures
+
+Harnex maps Pi events as follows:
+
+| Pi event | Harnex behavior |
+|---|---|
+| `agent_start`, `turn_start` | busy |
+| `agent_end` | remain busy; capture outcome/stats, but do not complete |
+| retry/compaction events | remain busy and emit structured telemetry |
+| `agent_settled` + final `stopReason=stop` | emit `task_complete` |
+| `agent_settled` + `error`, `aborted`, or `length` | emit `task_failed` |
+| `agent_settled` without an authoritative final stop reason | fail closed |
+| EOF, malformed JSON, or request timeout | disconnect/failure |
+
+A forced send while Pi is busy is translated to a `prompt` with
+`streamingBehavior="steer"`; ordinary sends wait for the settled prompt state.
+This avoids sending a plain prompt that current Pi correctly rejects while
+streaming.
+
+RPC requests are bounded, stderr is continuously drained into a bounded
+diagnostic tail, and Harnex consumes Open3's wait thread so the real subprocess
+exit status is not lost to a competing `waitpid`.
+
+## Telemetry
+
+At settlement and teardown, Harnex reads `get_session_stats` and records:
+
+- input/output/cache/total tokens and provider-reported cost;
+- tool-call count;
+- Pi session ID;
+- effective provider and model;
+- terminal and peak active-context usage.
+
+Message/tool/retry/compaction events are available through `harnex events`.
+Blocking extension dialogs (`select`, `confirm`, `input`, `editor`) are
+currently auto-cancelled so autonomous workers cannot hang. Full extension UI
+mediation is not implemented.
+
+## Boundaries
+
+- The structured adapter does not embed Pi's TypeScript SDK.
+- `--tmux` displays Harnex's synthesized RPC transcript, not Pi's native TUI.
+- First-class native Pi TUI/PTTY markers remain tracked in Issue `#45`.
+- Durable Pi session recovery is separate from lifecycle correctness and remains
+  part of the broader structured-recovery work.
+
+## Verification
+
+Hermetic tests cover lifecycle settlement, retry boundaries, failure stop
+reasons, delta-only message streaming, model/effort RPC controls, request
+timeouts, and telemetry. The opt-in live contract test is:
+
+```bash
+PI_INTEGRATION=1 ruby -Ilib -Itest \
+  test/harnex/adapters/pi_integration_test.rb
+```

data/guides/01_dispatch.md

@@ -148,8 +148,13 @@ to the canonical repo/global dispatch stream, which is the only telemetry
 destination. Repo `.harnex/config.json` can warn on or reject non-canonical
 phase names before spawn.
 
-Pi runs use structured RPC (`pi --mode rpc`). Pass Pi child flags after `--`
-(e.g. `harnex run pi --context "..." -- --model anthropic/claude-sonnet-4-5 --thinking high`).
+Pi runs use structured RPC (`pi --mode rpc`) and require Pi >= 0.80.4; gate
+unattended work with `harnex doctor --adapter pi`. Harnex `--model` / `--effort`
+apply verified Pi startup controls before the prompt. Pass other Pi startup
+flags after `--` (e.g. `harnex run pi --context "..." -- --model
+anthropic/claude-sonnet-4-5 --thinking high`).
+Since RPC cannot display Pi's trust prompt, explicitly pass child `--approve`
+for reviewed project-local resources or `--no-approve` to ignore them.
 
 Codex flag forms differ between transports. The default JSON-RPC adapter
 (`codex app-server`) does not accept `-m`/`--model`; pass the model as

data/guides/04_monitoring.md

@@ -68,8 +68,11 @@ named parent is still running in the same repo is refused. Wait for the parent
 (`harnex wait --id <parent> --until done`) or stop it first. Pass
 `--allow-live-parent` only for intentional parallelism (e.g. isolated
 worktrees). `--attempt-kind review` is exempt: a completed parent may still
-sit at a live prompt while its work is reviewed. For structured sessions (Pi RPC and Codex app-server),
-`harnex wait --until task_complete` remains the exact accepted-turn fence.
+sit at a live prompt while its work is reviewed. For structured sessions (Pi
+RPC and Codex app-server), `harnex wait --until task_complete` remains the exact
+accepted-turn fence. Pi reaches that fence only at `agent_settled`; an earlier
+`agent_end` can still be followed by retry, compaction recovery, or queued work.
+Final Pi `error`, `aborted`, and `length` stop reasons emit `task_failed`.
 Codex acknowledgment-only auto-stop turns are typed
 `completed_no_activity` and fail this fence without transcript parsing. Harnex
 writes the observed-state receipt before publishing `task_complete`; optional

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

@@ -145,6 +145,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
@@ -230,7 +233,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 +244,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]
@@ -424,7 +427,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,

data/lib/harnex/runtime/session.rb

@@ -161,6 +161,10 @@ module Harnex
       @completion_report_status = nil
       @completion_diagnostics = []
       @pi_streamed_text_by_message = {}
+      @pi_active_message_key = nil
+      @pi_last_assistant_stop_reason = nil
+      @pi_last_assistant_error = nil
+      @pi_last_retry_error = nil
       @auto_stop = !!auto_stop
       @auto_stop_fired = false
       @auto_stop_seen_busy = false
@@ -197,6 +201,7 @@ module Harnex
     end
 
     def run(validate_binary: true)
+      configure_adapter_startup!
       validate_binary! if validate_binary
       prune_retained_logs
       prepare_output_log
@@ -471,10 +476,18 @@ module Harnex
 
     def validate_binary!
       self.class.validate_binary!(command)
+      adapter.validate_runtime! if adapter.respond_to?(:validate_runtime!)
     end
 
     private
 
+    def configure_adapter_startup!
+      return unless adapter.respond_to?(:configure_startup)
+
+      adapter.configure_startup(model: meta_hash["model"], effort: meta_hash["effort"])
+      @command = adapter.build_command
+    end
+
     def structured_transport?
       %i[stdio_jsonrpc stdio_jsonl_rpc].include?(adapter.transport)
     end
@@ -501,9 +514,18 @@ module Harnex
 
       if @pid
         begin
-          _, status = Process.wait2(@pid)
-          @term_signal = status.signaled? ? status.termsig : nil
-          @exit_code = status.exited? ? status.exitstatus : 128 + status.termsig
+          status = if adapter.respond_to?(:wait_for_exit)
+                     adapter.wait_for_exit
+                   else
+                     _waited_pid, process_status = Process.wait2(@pid)
+                     process_status
+                   end
+          if status
+            @term_signal = status.signaled? ? status.termsig : nil
+            @exit_code = status.exited? ? status.exitstatus : 128 + status.termsig
+          else
+            @exit_code = 0
+          end
         rescue Errno::ECHILD
           @exit_code = 0
         end
@@ -792,29 +814,43 @@ module Harnex
       event_type = message["type"].to_s
 
       case event_type
-      when "agent_start", "turn_start"
-        @turn_started_seen = true if event_type == "turn_start"
+      when "agent_start"
+        reset_pi_run_outcome!
         @state_machine.force_busy!
-        emit_event("turn_started") if event_type == "turn_start"
+      when "turn_start"
+        @turn_started_seen = true
+        @state_machine.force_busy!
+        emit_event("turn_started")
       when "agent_end"
+        capture_pi_agent_end(message)
+        @state_machine.force_busy!
+        emit_event("agent_end", will_retry: message["willRetry"] == true)
+        adapter.request_session_stats_async if adapter.respond_to?(:request_session_stats_async)
+      when "agent_settled"
         @state_machine.force_prompt!
-        record_successful_completion({})
+        emit_event("agent_settled", stop_reason: @pi_last_assistant_stop_reason)
+        settle_pi_task!
         adapter.request_session_stats_async if adapter.respond_to?(:request_session_stats_async)
-        schedule_auto_stop("task_complete", interrupt: false)
+        schedule_auto_stop("agent_settled", interrupt: false) if task_complete? || task_failed?
       when "message_start"
-        @pi_streamed_text_by_message[pi_message_key(message["message"])] = false
+        @pi_active_message_key = pi_message_key(message["message"])
+        @pi_streamed_text_by_message[@pi_active_message_key] = false
       when "message_update"
         event = message["assistantMessageEvent"] || {}
         delta = event["delta"]
-        key = pi_message_key(message["message"])
+        key = @pi_active_message_key || pi_message_key(message["message"])
         if event["type"] == "text_delta" && delta && !delta.empty?
           @pi_streamed_text_by_message[key] = true
           record_synthesized(delta, newline: false)
         end
       when "message_end"
-        key = pi_message_key(message["message"])
+        key = @pi_active_message_key || pi_message_key(message["message"])
         streamed = @pi_streamed_text_by_message.delete(key)
-        unless streamed
+        @pi_active_message_key = nil
+        capture_pi_assistant_message(message["message"])
+        if streamed
+          record_synthesized("\n", newline: false)
+        else
           text = pi_extract_message_text(message["message"])
           record_synthesized(text) if text
         end
@@ -828,13 +864,25 @@ module Harnex
         status = message["isError"] ? "error" : "ok"
         record_synthesized("tool-result: #{tool_name} (#{status})")
       when "compaction_start", "compaction_end"
-        emit_event("compaction", reason: message["reason"], phase: event_type)
+        emit_event(
+          "compaction",
+          reason: message["reason"],
+          phase: event_type,
+          will_retry: message["willRetry"],
+          aborted: message["aborted"],
+          error_message: message["errorMessage"]
+        )
       when "queue_update"
         nil
       when "auto_retry_start", "auto_retry_end"
         payload = message.reject { |k, _| k == "type" }
+        @pi_last_retry_error = message["finalError"].to_s if event_type == "auto_retry_end" && message["success"] == false
         emit_event(event_type, **payload)
         record_attempt_transition(type: "attempt_retry_scheduled", trigger: "adapter_auto_retry") if event_type == "auto_retry_start"
+      when "summarization_retry_scheduled", "summarization_retry_attempt_start", "summarization_retry_finished"
+        emit_event(event_type, **message.reject { |k, _| k == "type" })
+      when "bash_execution_update"
+        emit_event(event_type, id: message["id"], bytes: message["delta"].to_s.bytesize)
       when "extension_ui_request"
         handle_extension_ui_request(message)
       when "extension_error"
@@ -876,9 +924,19 @@ module Harnex
         return
       end
 
+      if msg.to_s.empty? && adapter.respond_to?(:disconnect_diagnostic)
+        msg = adapter.disconnect_diagnostic
+      end
       @last_error = msg.to_s unless msg.to_s.empty?
       @state_machine.force_busy!
       emit_event("disconnected", source: "transport", message: msg) rescue nil
+      if adapter.respond_to?(:terminate_subprocess)
+        Thread.new do
+          adapter.terminate_subprocess
+        rescue StandardError
+          nil
+        end
+      end
       signal_rpc_done!
     end
 
@@ -946,6 +1004,52 @@ module Harnex
       ""
     end
 
+    def reset_pi_run_outcome!
+      @pi_last_assistant_stop_reason = nil
+      @pi_last_assistant_error = nil
+      @pi_last_retry_error = nil
+    end
+
+    def capture_pi_agent_end(message)
+      assistant = Array(message["messages"]).reverse.find do |candidate|
+        candidate.is_a?(Hash) && candidate["role"] == "assistant"
+      end
+      capture_pi_assistant_message(assistant) if assistant
+    end
+
+    def capture_pi_assistant_message(message)
+      return unless message.is_a?(Hash) && message["role"] == "assistant"
+
+      reason = message["stopReason"].to_s
+      @pi_last_assistant_stop_reason = reason unless reason.empty?
+      error = message["errorMessage"].to_s
+      @pi_last_assistant_error = error unless error.empty?
+    end
+
+    def settle_pi_task!
+      return if @stop_requested && !task_complete? && !task_failed?
+
+      reason = @pi_last_assistant_stop_reason
+      case reason
+      when "stop"
+        record_successful_completion({})
+      when "error", "aborted", "length"
+        error = @pi_last_assistant_error || @pi_last_retry_error
+        error = "Pi agent settled with stopReason=#{reason}" if error.to_s.empty?
+        mark_task_failed(status: reason, error: error)
+      when nil, ""
+        mark_task_failed(
+          status: "missing_final_message",
+          error: "Pi agent settled without an authoritative final assistant stop reason"
+        )
+      else
+        mark_task_failed(
+          status: "unsupported_stop_reason",
+          error: "Pi agent settled with unsupported stopReason=#{reason}"
+        )
+      end
+    end
+
     def pi_extract_message_text(message)
       return nil unless message.is_a?(Hash)
 
@@ -2193,8 +2297,9 @@ module Harnex
     end
 
     def summary_model
-      meta_hash["model"] || @usage_summary[:model] ||
-        (adapter.current_model if adapter.respond_to?(:current_model))
+      @usage_summary[:model] ||
+        (adapter.current_model if adapter.respond_to?(:current_model)) ||
+        meta_hash["model"]
     end
 
     def summary_service_tier

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.10.2"
-  RELEASE_DATE = "2026-08-08"
+  VERSION = "0.11.0"
+  RELEASE_DATE = "2026-08-14"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.11.0
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-08 00:00:00.000000000 Z
+date: 2026-08-14 00:00:00.000000000 Z
 dependencies: []
 description: A local PTY harness that wraps terminal AI agents (Claude, Codex, Pi)
   and adds a control plane for discovery, messaging, and coordination.
@@ -30,6 +30,7 @@ files:
 - docs/configuration.md
 - docs/dispatch-telemetry.md
 - docs/events.md
+- docs/pi-rpc.md
 - guides/01_dispatch.md
 - guides/02_chain.md
 - guides/03_buddy.md