harnex 0.6.5 → 0.7.4

data/guides/03_buddy.md

@@ -7,7 +7,7 @@ needs interpretation that simple stall policy cannot provide.
 For simple inactivity recovery, prefer built-in watch mode:
 
 ```bash
-harnex run codex --id cx-i-NN --watch --preset impl --context "Read /tmp/task-impl-NN.md"
+harnex run pi --id pi-i-NN --watch --preset impl --context "Read /tmp/task-impl-NN.md"
 ```
 
 Use a buddy when you need reasoning over pane contents, semantic checks, or
@@ -28,14 +28,15 @@ Use a buddy for:
 Spawn the worker first, then spawn the buddy:
 
 ```bash
-harnex run codex --id cx-i-42 --tmux cx-i-42 \
+harnex run pi --id pi-i-42 --tmux pi-i-42 \
   --context "Read and execute /tmp/task-impl-42.md"
 
-harnex run claude --id buddy-42 --tmux buddy-42
+harnex run pi --id buddy-42 --tmux buddy-42
 ```
 
 The buddy is just another harnex session. Inspect it, stop it, and read its
-logs with the same commands as any worker.
+logs with the same commands as any worker. Use Pi by default; swap to another
+adapter if your environment or policy requires it.
 
 ## Buddy Prompt
 
@@ -43,18 +44,18 @@ Give the buddy an explicit polling loop, stall threshold, nudge rule, return
 channel, and cleanup rule:
 
 ```text
-You are an accountability partner for harnex session `cx-i-42`.
+You are an accountability partner for harnex session `pi-i-42`.
 
 Every 5 minutes:
-- Run `harnex pane --id cx-i-42 --lines 30`.
-- Run `harnex status --id cx-i-42 --json`.
+- Run `harnex pane --id pi-i-42 --lines 30`.
+- Run `harnex status --id pi-i-42 --json`.
 
 If the worker appears stuck at a prompt or permission dialog for more than
 10 minutes with no progress, nudge it:
-- `harnex send --id cx-i-42 --message "You appear to have stalled. Continue with your current task."`
+- `harnex send --id pi-i-42 --message "You appear to have stalled. Continue with your current task."`
 
-If the worker exits or writes `/tmp/cx-i-42-done.txt`, report back:
-- `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "cx-i-42 finished. Check /tmp/cx-i-42-done.txt." Enter`
+If the worker exits or writes `/tmp/pi-i-42-done.txt`, report back:
+- `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "pi-i-42 finished. Check /tmp/pi-i-42-done.txt." Enter`
 
 Do not interfere with active work. Stop yourself after reporting completion.
 ```
@@ -73,7 +74,7 @@ harnex session:
 
 ```bash
 tmux capture-pane -t "$HARNEX_SPAWNER_PANE" -p
-tmux send-keys -t "$HARNEX_SPAWNER_PANE" "cx-i-42 finished" Enter
+tmux send-keys -t "$HARNEX_SPAWNER_PANE" "pi-i-42 finished" Enter
 ```
 
 If no tmux return pane is available, require the buddy to write a file and tell

data/guides/04_monitoring.md

@@ -17,16 +17,17 @@ Prefer signals in this order:
 | `harnex pane` | Live UI interpretation and prompt/error diagnosis |
 | `harnex status` | Session liveness and coarse state |
 
-For Codex app-server sessions, `harnex wait --until task_complete` is a strong
-turn-level fence. It still does not know your acceptance criteria; verify the
-expected artifact or tests afterward.
+For structured sessions (Pi RPC and Codex app-server),
+`harnex wait --until task_complete` is a strong turn-level fence. It still
+does not know your acceptance criteria; verify the expected artifact or tests
+afterward.
 
 ## Completion Test
 
 For unattended work, declare done with a conjunction of work-level facts:
 
 ```bash
-test -f /tmp/cx-i-NN-done.txt &&
+test -f /tmp/pi-i-NN-done.txt &&
   test -z "$(git status --short)" &&
   test "$(git log -1 --format=%ct)" -lt "$(($(date +%s) - 600))"
 ```
@@ -51,23 +52,23 @@ where to look.
 For active supervision:
 
 ```bash
-harnex pane --id cx-i-NN --lines 40
-harnex events --id cx-i-NN --snapshot
-harnex logs --id cx-i-NN --lines 80
+harnex pane --id pi-i-NN --lines 40
+harnex events --id pi-i-NN --snapshot
+harnex logs --id pi-i-NN --lines 80
 ```
 
 For continuous viewing:
 
 ```bash
-harnex pane --id cx-i-NN --follow --interval 2
-harnex logs --id cx-i-NN --follow
-harnex events --id cx-i-NN
+harnex pane --id pi-i-NN --follow --interval 2
+harnex logs --id pi-i-NN --follow
+harnex events --id pi-i-NN
 ```
 
 For task completion:
 
 ```bash
-harnex wait --id cx-i-NN --until task_complete --timeout 900
+harnex wait --id pi-i-NN --until task_complete --timeout 900
 ```
 
 ## Background Sweeper
@@ -80,14 +81,14 @@ pipeline cannot wait forever:
 start=$(date +%s)
 max_wait=5400
 
-until test -f /tmp/cx-i-NN-done.txt; do
+until test -f /tmp/pi-i-NN-done.txt; do
   if test "$(($(date +%s) - start))" -gt "$max_wait"; then
-    echo "wall-clock cap hit for cx-i-NN" >&2
+    echo "wall-clock cap hit for pi-i-NN" >&2
     exit 2
   fi
 
-  harnex status --id cx-i-NN --json
-  harnex pane --id cx-i-NN --lines 20
+  harnex status --id pi-i-NN --json
+  harnex pane --id pi-i-NN --lines 20
   sleep 60
 done
 ```
@@ -106,7 +107,7 @@ Use `harnex run --watch` when one foreground process should launch the worker
 and apply bounded stall recovery:
 
 ```bash
-harnex run codex --id cx-i-NN --watch --preset impl \
+harnex run pi --id pi-i-NN --watch --preset impl \
   --context "Read /tmp/task-impl-NN.md"
 ```
 

data/guides/05_naming.md

@@ -15,6 +15,7 @@ Common prefixes:
 
 | Prefix | Meaning |
 | --- | --- |
+| `pi` | Pi worker (default) |
 | `cx` | Codex worker |
 | `cl` | Claude worker |
 | `buddy` | Buddy monitor |
@@ -34,13 +35,13 @@ Common phases:
 Examples:
 
 ```text
-cx-m-42      Codex maps task 42
-cx-p-42      Codex writes plan 42
-cx-r-42      Codex reviews plan 42
-cx-f-42      Codex fixes plan 42
-cx-i-42      Codex implements plan 42
-cx-cr-42     Codex reviews implementation 42
-cx-cf-42     Codex fixes implementation 42
+pi-m-42      Pi maps task 42
+pi-p-42      Pi writes plan 42
+pi-r-42      Pi reviews plan 42
+pi-f-42      Pi fixes plan 42
+pi-i-42      Pi implements plan 42
+pi-cr-42     Pi reviews implementation 42
+pi-cf-42     Pi fixes implementation 42
 buddy-42     Buddy monitors task 42
 ```
 
@@ -52,13 +53,13 @@ short, and present in every artifact.
 Always pass both and keep them identical:
 
 ```bash
-harnex run codex --id cx-i-42 --tmux cx-i-42
+harnex run pi --id pi-i-42 --tmux pi-i-42
 ```
 
 Avoid this:
 
 ```bash
-harnex run codex --tmux cx-i-42
+harnex run pi --tmux pi-i-42
 ```
 
 If `--id` is missing, harnex generates a random session ID. The tmux window may
@@ -70,9 +71,9 @@ ID.
 If a session fails and you dispatch a fresh attempt, append a suffix:
 
 ```text
-cx-i-42      first attempt
-cx-i-42b     second attempt
-cx-i-42c     third attempt
+pi-i-42      first attempt
+pi-i-42b     second attempt
+pi-i-42c     third attempt
 ```
 
 Keep the old session's logs. They are useful for diagnosis.
@@ -97,9 +98,9 @@ session ID.
 Derive done markers from the session ID:
 
 ```text
-/tmp/cx-p-42-done.txt
-/tmp/cx-i-42-done.txt
-/tmp/cx-cr-42-done.txt
+/tmp/pi-p-42-done.txt
+/tmp/pi-i-42-done.txt
+/tmp/pi-cr-42-done.txt
 ```
 
 When a brief asks for a completion marker, make it one line and include the

data/lib/harnex/adapters/base.rb

@@ -1,7 +1,11 @@
+require "open3"
+require "timeout"
+
 module Harnex
   module Adapters
     class Base
       PROMPT_PREFIXES = [">", "\u203A", "\u276F"].freeze
+      AGENT_VERSION_TIMEOUT_SECONDS = 2.0
 
       # Adapter contract — subclasses MUST implement:
       #   base_command          -> Array[String]  CLI args to spawn
@@ -20,12 +24,28 @@ module Harnex
         @extra_args = extra_args.dup
       end
 
-      # Default transport. Adapters speaking JSON-RPC override to
-      # :stdio_jsonrpc; Session#run uses this to pick the I/O path.
+      # Default transport. Structured adapters override to :stdio_jsonrpc
+      # (Codex app-server) or :stdio_jsonl_rpc (Pi RPC); Session#run uses
+      # this to pick the I/O path.
       def transport
         :pty
       end
 
+      # Vendor of the underlying agent — populates DISPATCH meta.agent_provider.
+      # Subclasses override (claude → "anthropic", codex → "openai").
+      def provider
+        nil
+      end
+
+      # Probes `<base_command.first> --version` with a short timeout and
+      # memoizes the result for the adapter's lifetime. Returns nil when
+      # the binary is missing, exits non-zero, or stalls past the timeout.
+      def agent_version
+        return @agent_version if defined?(@agent_version)
+
+        @agent_version = probe_agent_version
+      end
+
       def describe
         { transport: transport }
       end
@@ -108,6 +128,20 @@ module Harnex
 
       protected
 
+      def probe_agent_version
+        cli = base_command.first
+        return nil unless cli
+
+        Timeout.timeout(AGENT_VERSION_TIMEOUT_SECONDS) do
+          stdout, status = Open3.capture2(cli, "--version", err: File::NULL, in: File::NULL)
+          return nil unless status.success?
+
+          stdout.to_s.lines.first&.strip
+        end
+      rescue Errno::ENOENT, Timeout::Error, StandardError
+        nil
+      end
+
       def submit_bytes
         "\r"
       end

data/lib/harnex/adapters/claude.rb

@@ -8,6 +8,10 @@ module Harnex
         super("claude", extra_args)
       end
 
+      def provider
+        "anthropic"
+      end
+
       def base_command
         [
           "claude",

data/lib/harnex/adapters/codex.rb

@@ -10,6 +10,10 @@ module Harnex
         @banner_seen = false
       end
 
+      def provider
+        "openai"
+      end
+
       def base_command
         [
           "codex",

data/lib/harnex/adapters/codex_appserver.rb

@@ -1,5 +1,6 @@
 require "json"
 require "open3"
+require_relative "../codex/app_server/client"
 
 module Harnex
   module Adapters
@@ -69,6 +70,10 @@ module Harnex
         :stdio_jsonrpc
       end
 
+      def provider
+        "openai"
+      end
+
       def base_command
         ["codex", "app-server"]
       end
@@ -135,10 +140,10 @@ module Harnex
       # subprocess. In tests, callers may pass pre-built IO objects.
       def start_rpc(env: nil, cwd: nil, read_io: nil, write_io: nil, pid: nil)
         if read_io && write_io
-          @client = JsonRpcClient.new(read_io: read_io, write_io: write_io, pid: pid)
+          @client = Harnex::Codex::AppServer::Client.new(read_io: read_io, write_io: write_io, pid: pid)
         else
           spawn_pid, child_stdin, child_stdout = spawn_subprocess(env, cwd)
-          @client = JsonRpcClient.new(read_io: child_stdout, write_io: child_stdin, pid: spawn_pid)
+          @client = Harnex::Codex::AppServer::Client.new(read_io: child_stdout, write_io: child_stdin, pid: spawn_pid)
         end
 
         @client.on_notification { |msg| handle_notification(msg) }
@@ -189,6 +194,48 @@ module Harnex
         result
       end
 
+      # Plan 30 Phase 2 — subprocess-restart primitive for deployment
+      # fallback. Stops the current JSON-RPC subprocess, spawns a new one
+      # against the supplied deployment_config, and resumes the same
+      # threadId so conversation state carries across. Thin orchestrator:
+      # counter snapshots, the `fallback_triggered` event, and any
+      # Session-level signaling land in plan 30 Phases 3–4 alongside the
+      # per-arm telemetry split. CLI flags land in Phase 5.
+      #
+      # deployment_config: { command: [...argv], env: {...}, cwd: nil }
+      def switch_deployment(deployment_config:,
+                            term_grace_seconds: STOP_TERM_GRACE_SECONDS,
+                            kill_grace_seconds: STOP_KILL_GRACE_SECONDS)
+        raise "codex_appserver: client not started" unless @client
+        raise "codex_appserver: no thread to resume" if @thread_id.nil? || @thread_id.to_s.empty?
+
+        prior_thread_id = @thread_id
+        in_flight =
+          if @current_turn_id
+            { threadId: prior_thread_id, turnId: @current_turn_id }
+          end
+
+        @client.stop_for_fallback(
+          in_flight_turn: in_flight,
+          term_grace_seconds: term_grace_seconds,
+          kill_grace_seconds: kill_grace_seconds
+        )
+
+        @client = Harnex::Codex::AppServer::Client.spawn_with_fallback(
+          prior_thread_id: prior_thread_id,
+          deployment_config: deployment_config,
+          handshake_params: handshake_initialize_params,
+          notification_handler: ->(msg) { handle_notification(msg) },
+          request_handler: ->(method, params) { handle_server_request(method, params) },
+          disconnect_handler: ->(err) { handle_disconnect(err) }
+        )
+
+        @thread_id = prior_thread_id
+        @current_turn_id = nil
+        @state = :prompt
+        self
+      end
+
       def close
         return unless @client
 
@@ -259,7 +306,12 @@ module Harnex
       end
 
       def perform_handshake
-        @client.request("initialize", {
+        @client.request("initialize", handshake_initialize_params)
+        @client.notify("initialized", {})
+      end
+
+      def handshake_initialize_params
+        {
           clientInfo: {
             title: CLIENT_TITLE,
             name: CLIENT_NAME,
@@ -269,8 +321,7 @@ module Harnex
             experimentalApi: false,
             optOutNotificationMethods: OPT_OUT_NOTIFICATIONS
           }
-        })
-        @client.notify("initialized", {})
+        }
       end
 
       def handle_notification(message)
@@ -314,231 +365,6 @@ module Harnex
         "Codex app-server is not at a prompt; wait and retry or use `harnex send --force` (state: #{state[:state]})"
       end
 
-      # Minimal JSON-RPC 2.0 client. One JSON object per line.
-      # Responses keyed by id; everything else is a notification.
-      class JsonRpcClient
-        attr_reader :pid
-
-        def initialize(read_io:, write_io:, pid: nil)
-          @read_io = read_io
-          @write_io = write_io
-          @pid = pid
-          @next_id = 1
-          @pending = {}
-          @id_mutex = Mutex.new
-          @write_mutex = Mutex.new
-          @notification_handler = nil
-          @request_handler = nil
-          @disconnect_handler = nil
-          @disconnect_signaled = false
-          @closed = false
-          @reader_thread = nil
-        end
-
-        def on_notification(&block)
-          @notification_handler = block
-        end
-
-        # Handler for server-initiated requests (id + method). The block
-        # receives (method, params) and returns the response body for the
-        # JSON-RPC `result` field, or nil to reject with -32601.
-        def on_request(&block)
-          @request_handler = block
-        end
-
-        def on_disconnect(&block)
-          @disconnect_handler = block
-        end
-
-        def start
-          @reader_thread = Thread.new { read_loop }
-        end
-
-        def request(method, params = {})
-          raise "codex_appserver client is closed" if @closed
-
-          queue = Queue.new
-          id = @id_mutex.synchronize do
-            assigned = @next_id
-            @next_id += 1
-            @pending[assigned] = queue
-            assigned
-          end
-
-          write_line({ jsonrpc: "2.0", id: id, method: method, params: params })
-          result = queue.pop
-          raise result if result.is_a?(Exception)
-
-          result
-        end
-
-        def notify(method, params = {})
-          return if @closed
-
-          write_line({ jsonrpc: "2.0", method: method, params: params })
-        end
-
-        def close
-          return if @closed
-
-          @closed = true
-
-          @id_mutex.synchronize do
-            @pending.each_value { |q| q.push(StandardError.new("codex_appserver client closed")) }
-            @pending.clear
-          end
-
-          begin
-            @write_io.close unless @write_io.closed?
-          rescue IOError
-            nil
-          end
-
-          if @pid && process_alive?(@pid)
-            sleep 0.05
-            begin
-              Process.kill("TERM", @pid)
-            rescue Errno::ESRCH
-              nil
-            end
-          end
-
-          @reader_thread&.join(2)
-        end
-
-        def terminate_process(term_grace_seconds:, kill_grace_seconds:)
-          return false unless @pid
-
-          begin
-            Process.kill("TERM", @pid)
-          rescue Errno::ESRCH
-            return true
-          end
-
-          return true if wait_for_process_exit(@pid, term_grace_seconds)
-
-          begin
-            Process.kill("KILL", @pid)
-          rescue Errno::ESRCH
-            return true
-          end
-
-          wait_for_process_exit(@pid, kill_grace_seconds)
-        end
-
-        private
-
-        def write_line(message)
-          @write_mutex.synchronize do
-            @write_io.write(JSON.generate(message))
-            @write_io.write("\n")
-            @write_io.flush
-          end
-        rescue Errno::EPIPE, IOError
-          signal_disconnect(nil)
-        end
-
-        def read_loop
-          buffer = +""
-          loop do
-            chunk = @read_io.readpartial(4096)
-            buffer << chunk
-            while (idx = buffer.index("\n"))
-              line = buffer.slice!(0, idx + 1).chomp
-              next if line.strip.empty?
-
-              handle_line(line)
-            end
-          end
-        rescue EOFError, IOError, Errno::EIO
-          nil
-        ensure
-          signal_disconnect(nil)
-        end
-
-        def handle_line(line)
-          message = JSON.parse(line)
-        rescue JSON::ParserError => e
-          signal_disconnect(e)
-          return
-        else
-          dispatch_message(message)
-        end
-
-        def dispatch_message(message)
-          if message["id"] && message["method"]
-            handle_server_request(message)
-            return
-          end
-
-          if message.key?("id")
-            pending = @id_mutex.synchronize { @pending.delete(message["id"]) }
-            return unless pending
-
-            if message["error"]
-              err_msg = message.dig("error", "message") || "RPC error"
-              pending.push(StandardError.new("codex_appserver RPC error: #{err_msg}"))
-              signal_disconnect(message["error"])
-            else
-              pending.push(message["result"] || {})
-            end
-            return
-          end
-
-          @notification_handler&.call(message) if message["method"]
-        end
-
-        def handle_server_request(message)
-          result =
-            begin
-              @request_handler&.call(message["method"], message["params"] || {})
-            rescue StandardError
-              nil
-            end
-
-          if result.nil?
-            write_line({
-              jsonrpc: "2.0",
-              id: message["id"],
-              error: { code: -32601, message: "Unsupported server request: #{message['method']}" }
-            })
-          else
-            write_line({
-              jsonrpc: "2.0",
-              id: message["id"],
-              result: result
-            })
-          end
-        end
-
-        def signal_disconnect(error)
-          return if @disconnect_signaled
-
-          @disconnect_signaled = true
-          @disconnect_handler&.call(error)
-        end
-
-        def process_alive?(pid)
-          Process.kill(0, pid)
-          true
-        rescue Errno::ESRCH, Errno::EPERM
-          false
-        end
-
-        def wait_for_process_exit(pid, timeout_seconds)
-          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds.to_f
-          loop do
-            return true unless process_alive?(pid)
-
-            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            break if remaining <= 0
-
-            sleep([0.05, remaining].min)
-          end
-
-          !process_alive?(pid)
-        end
-      end
     end
   end
 end