harnex 0.6.5 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 297484ce749d268b7582afd226d617c79fed80a12928ced5daa8df2c3bd4f763
-  data.tar.gz: 554528411e6bca5c6037ca579067f37b4b58626b88ed5c263fe95debe4517f70
+  metadata.gz: e99b85fa8112b666665da16757d871098867e0b05c9521c3507fc2092616f825
+  data.tar.gz: 78a5190335ee968c77d75531d23998c34272d24a3b6a8d6a53d5e9a8922c87da
 SHA512:
-  metadata.gz: 1aa029fe0d4177ef1a9043c863935655df9b636b48bedaad3f84d35e6d02d0b9255b16ce2c08a5220f2eb4b89930fe0002b2926c47039b7cb1eeab2a6e333b07
-  data.tar.gz: ab908f0f299a9a0ae286cf629202fa26d518f59658518515818c388f21daadbd42a4a839417878a99c3f863439df5d11dd51cdf7c3675b737638293b5c739832
+  metadata.gz: 4c32673867f2b86ee84fa1768ee4fee82a3ddb0fb69abd5c369349d59fe9feef3cc468ee71776115da19ca2997b1f647678b413f8c93d02538f56c17daf316d4
+  data.tar.gz: bf049097af8736c25991af1894dd15b6cc8159393f99eb215a0dc7ddd67f9716b1864589664fdd08671edc6859899c9cb84c46852b940323b8f11f42d5f8ee29

data/CHANGELOG.md

@@ -2,6 +2,164 @@
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-05-25 | 08:45 AM | IST
+
+### Added
+
+- First-class `pi` structured adapter (`Harnex::Adapters::Pi`) for
+  `pi --mode rpc` JSONL transport. `harnex run pi` now supports
+  structured completion (`agent_end` -> `task_complete`), stop/abort,
+  extension-UI dialog auto-cancel in RPC mode, streamed output/tool
+  synthesis, and Pi session-stats telemetry capture.
+
+### Changed
+
+- Structured transport handling in `Session` now supports both Codex
+  JSON-RPC (`:stdio_jsonrpc`) and Pi JSONL RPC (`:stdio_jsonl_rpc`).
+- DISPATCH telemetry restores `actual.cost_usd` (adapter-reported
+  approximate USD when available). Pi sessions populate it from
+  `get_session_stats.cost`; adapters without reliable cost stay `null`.
+- README, dispatch telemetry docs, and dispatch guide now document Pi RPC
+  usage and the `--` child-flag pattern.
+
+## [0.7.3] - 2026-05-13 | 01:43 PM | IST
+
+### Added
+
+- `harnex run codex --fast` now opts Codex app-server runs into
+  `service_tier="fast"`. Default Codex runs now inject
+  `service_tier="flex"` unless the child CLI args already supply an
+  explicit `service_tier` config.
+- First-class `opencode` PTY adapter. `harnex run opencode` now uses
+  `Harnex::Adapters::Opencode` instead of the generic fallback, with
+  an OpenCode-specific stop sequence (double Ctrl+C), repo path
+  inference (`--dir` or positional project path), and session-id
+  extraction from transcript tails (`Continue opencode -s ...`).
+
+### Changed
+
+- `harnex run` now rejects unknown long flags before spawning the
+  agent process, with a clear error pointing at `harnex run --help`.
+  Anything past the `--` separator continues to forward unchanged
+  to the agent CLI. Closes the trigger that correlated with the F23
+  auto-stop teardown leak. Closes harnex issue #38.
+- Codex app-server contract fixtures are refreshed against
+  `codex-cli 0.130.0`; response builders now include the required
+  `thread.sessionId` field.
+- Internal Codex app-server code now has the extracted
+  `Harnex::Codex::AppServer::Client` namespace and the subprocess
+  restart primitive needed by the deployment-fallback plan. No
+  public fallback CLI flag is exposed yet.
+
+### Fixed
+
+- `harnex run` now defaults dispatch summaries to
+  `<repo>/.harnex/dispatch.jsonl` for every resolved repo, regardless
+  of whether a legacy `koder/` directory exists. Closes harnex issue
+  #39.
+- `harnex run` with `--auto-stop` now exits within a bounded grace
+  (default 5s, override via `HARNEX_AUTOSTOP_TEARDOWN_GRACE_SECONDS`)
+  after `task_complete`. Closes a leak where the wrapping Ruby parent
+  process could sleep on `futex_wait_queue` indefinitely during
+  teardown, surviving as `orphan_tmux` until manually swept (F09
+  detected; F23 remediates). Closes harnex issue #37.
+
+## [0.7.2] - 2026-05-08
+
+### Fixed
+
+- `harnex run` now resolves the repo-local
+  `<repo>/.harnex/dispatch.jsonl` write path from the supervisor's
+  launch cwd (captured at invocation time), not from the agent's
+  runtime cwd. Closes a regression where cross-repo dispatches
+  (supervisor in repo A, agent `cd`'s into repo B) wrote their
+  terminal row only to the global fallback, never to repo A.
+
+### Added
+
+- `harnex doctor --sweep` reports read-only harnex/tmux session drift,
+  including active registry rows, matching `cx-*` tmux windows, orphan
+  tmux windows, and stale session log files whose owning pid is gone.
+
+## [0.7.1] - 2026-05-08
+
+### Fixed
+
+- `harnex run --auto-stop` now observes the terminal `task_complete`
+  event after the agent subprocess exits before tearing down, closing
+  a race where one-shot dispatches could report `timeout` even when
+  the agent finished the task cleanly. Adds a regression test that
+  exercises the post-exit event drain path.
+
+- `harnex wait` predicates now classify dispatch progress by
+  structured event-record fields instead of regex-matching the
+  human-readable transcript, with the prior exact-marker text as a
+  legacy fallback. Eliminates a class of spurious matches where
+  prose containing a marker word was misread as a state transition.
+
+### Added
+
+- Dispatch summaries now preserve declared brief budget metadata
+  (`read_budget_lines`, `output_ceiling_lines`) from `--meta` and
+  record rough terminal measurements (`lines_changed`, `output_lines`,
+  `output_bytes`, `event_records`) for downstream budget enforcement.
+
+## [0.7.0] - 2026-05-08
+
+### Added
+
+- `harnex run` now appends one terminal dispatch record to
+  `<repo>/.harnex/dispatch.jsonl`, falling back to
+  `~/.local/state/harnex/dispatch.jsonl` outside git repos. New
+  `harnex history` reads that log with `--limit`, `--since`, `--id`,
+  `--global`, `--json`, and `--all` filters.
+- DISPATCH row `actual` now includes `turn_count`, `tool_calls`,
+  `commands_executed`, `rate_limits`, `output_log_path`, and
+  `events_log_path` — surfacing data harnex already tracked but did
+  not persist. `meta.parent_dispatch_id` now auto-derives from
+  `$HARNEX_ID` when not supplied via `--meta`. (#35 Tier 2)
+- DISPATCH row `meta.agent_provider` and `meta.agent_version` now
+  populated. `provider` is a per-adapter constant
+  (claude → `anthropic`, codex → `openai`, generic → nil).
+  `agent_version` lazily probes `<base_command.first> --version`
+  with a 2s timeout, memoizes per adapter, and falls back to nil if
+  the binary is missing or stalls. (#35 Tier 3)
+
+### Removed
+
+- DISPATCH row dropped four always-null fields with no code path
+  populating them: `actual.cost_usd`, `actual.tests_run`,
+  `actual.tests_passed`, `actual.tests_failed`, and
+  `meta.agent_deployment`. Cost computation belongs to downstream
+  consumers (per-model rate tables change frequently); test-result
+  aggregation belongs to CI integrations, not the harness; and the
+  `agent_deployment` concept had no source of truth. JSON Lines
+  consumers should update column readers — schema is now stable but
+  smaller. (#35 Tier 3)
+
+### Fixed
+
+- `harnex wait` (default exit-watch mode) now blocks until the
+  exit-status file is on disk after the agent subprocess dies, with
+  a 5s grace bound (override via `HARNEX_EXIT_STATUS_GRACE_SECONDS`).
+  The exit-status file is written *after* the DISPATCH row in the
+  parent's teardown ensure block, so its presence guarantees the row
+  is on disk. Closes the race where `wait` could return between
+  `Process.wait2` unblocking and `Session#finalize_session!`
+  appending the row, which made dispatch-poll orchestrators flake
+  on "missing telemetry". (#36)
+
+### Changed
+
+- `koder/STATE.md` is now a thin past / present / future handoff
+  instead of a long-running project history. Durable change history
+  belongs in `CHANGELOG.md`, release verification in `koder/releases/`,
+  and issue or implementation detail in `koder/issues/` or
+  `koder/plans/`.
+- Agent orientation and the repo-local `open` / `close` skills now
+  explicitly tell future sessions to keep `STATE.md` concise and route
+  detailed notes to the durable tracking document that owns them.
+
 ## [0.6.5] — 2026-05-07
 
 ### Added

data/README.md

@@ -2,15 +2,18 @@
 
 Run multiple AI coding agents from your terminal and coordinate them.
 
-Harnex wraps Claude Code and OpenAI Codex (or any terminal CLI) in a
-local harness so you can launch agents, send them tasks, watch their
-screens, and stop them cleanly — all from the command line.
+Harnex wraps Claude Code, OpenAI Codex, Pi, OpenCode, or any terminal CLI in a
+local harness so you can launch agents, send them tasks, inspect panes,
+transcripts, and events, and stop them cleanly -- all from the command line.
 
 ```bash
 gem install harnex
 ```
 
-Requires **Ruby 3.x**. No other dependencies.
+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`.
 
 Then ask the CLI what to do next:
 
@@ -20,6 +23,9 @@ 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.
+
 `harnex agents-guide` is the agent-facing reference for dispatch, chain,
 buddy, monitoring, and naming patterns. It is packaged in the gem; no skills
 or project-local docs are required.
@@ -28,7 +34,7 @@ or project-local docs are required.
 
 ```bash
 # Start an agent in tmux
-harnex run codex --id planner --tmux
+harnex run pi --id planner --tmux planner
 
 # Send it a task and wait for it to finish
 harnex send --id planner --message "Write a plan to /tmp/plan.md" --wait-for-idle
@@ -46,11 +52,12 @@ job, watch it work, stop it when done.
 ## Why use this
 
 - **You want agents to plan, implement, review, and fix — in sequence.**
-  Codex writes code. Claude reviews it. Another Codex fixes the review
+  Pi writes code. Claude reviews it. Pi (or another adapter) fixes the review
   findings. Each step is a fresh agent with clean context.
 
-- **You want to see what agents are doing.** `harnex pane` shows
-  the agent's live terminal. No black boxes.
+- **You want to see what agents are doing.** `harnex pane` captures a
+  tmux-backed terminal, `harnex logs` tails the persisted transcript, and
+  `harnex events` streams structured JSONL lifecycle events.
 
 - **You don't want to babysit.** Send a task with `--wait-for-idle`,
   walk away, check back when it's done.
@@ -68,31 +75,51 @@ job, watch it work, stop it when done.
 
 | Agent | Support |
 |-------|---------|
-| Claude Code | Full (prompt detection, stop sequence, vim mode) |
-| OpenAI Codex | Full (prompt detection, stop sequence) |
-| Any terminal CLI | Generic wrapping (everything works except smart prompt detection) |
+| 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 |
+| 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 |
+
+`harnex run codex` uses JSON-RPC by default. That path provides
+structured task-completion events, approval mediation, and token usage
+capture. Default JSON-RPC Codex does not accept `-m` / `--model`; pass
+model settings as child CLI config, for example `harnex run codex -- -c model=NAME`.
+Harnex forces Codex app-server `service_tier="flex"` unless you opt into
+`service_tier="fast"` with `harnex run codex --fast`.
+Use `harnex run codex --legacy-pty` when you specifically want Codex's
+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:
+`harnex run pi --context "Implement X" -- --model anthropic/claude-sonnet-4-5 --thinking high`.
 
 ## Multi-agent workflows
 
 The real power is chaining agents together:
 
 ```bash
-# 1. Codex writes a plan
-harnex run codex --id cx-plan --tmux
-harnex send --id cx-plan --message "Plan the auth module, write to /tmp/plan.md" --wait-for-idle
-harnex stop --id cx-plan
+# 1. Pi writes a plan
+harnex run pi --id pi-plan --tmux pi-plan
+harnex send --id pi-plan --message "Plan the auth module, write to /tmp/plan.md" --wait-for-idle
+harnex stop --id pi-plan
 
-# 2. Fresh Codex implements the plan
-harnex run codex --id cx-impl --tmux
-harnex send --id cx-impl --message "Implement /tmp/plan.md, run tests" --wait-for-idle
-harnex stop --id cx-impl
+# 2. Fresh Pi implements the plan
+harnex run pi --id pi-impl --tmux pi-impl
+harnex send --id pi-impl --message "Implement /tmp/plan.md, run tests" --wait-for-idle
+harnex stop --id pi-impl
 
 # 3. Claude reviews the implementation
-harnex run claude --id cl-review --tmux
+harnex run claude --id cl-review --tmux cl-review
 harnex send --id cl-review --message "Review changes against /tmp/plan.md, write /tmp/review.md" --wait-for-idle
 harnex stop --id cl-review
 ```
 
+For delegated work, pass the same value to `--id` and `--tmux` so
+`harnex status`, `harnex pane`, logs, and the tmux window name all line up.
+
 Harnex ships CLI-readable agent guides for this pattern:
 
 - **[Dispatch](guides/01_dispatch.md)** — the fire-and-watch pattern:
@@ -117,13 +144,15 @@ harnex agents-guide monitoring
 For unattended dispatches, use `--watch` instead of writing a bash poll loop:
 
 ```bash
-harnex run codex --id cx-impl-42 --watch --preset impl \
+harnex run pi --id pi-impl-42 --watch --preset impl \
   --context "Implement koder/plans/42_plan.md. Run tests and commit when done."
 ```
 
 `--watch` runs a foreground babysitter that checks session activity every 60s,
 force-resumes on stall up to a cap, and exits when the target session exits or
-the resume cap is reached.
+the resume cap is reached. It is foreground-only; use `--tmux` or `--detach`
+for visible/background sessions, and `--watch` when the current command should
+block as the monitor.
 
 Presets map to stall policy defaults:
 
@@ -133,19 +162,57 @@ Presets map to stall policy defaults:
 
 Explicit `--stall-after` and `--max-resumes` flags override preset defaults.
 
+For file-change hooks, use `--watch-file PATH`. The older
+`--watch PATH`/`--watch=PATH` form is still accepted for compatibility, while
+bare `--watch` means babysitter mode.
+
+For one-shot startup prompts, add `--auto-stop`. It requires `--context`
+and stops the session after the first task completion or PTY prompt return.
+
 For structured subscriptions, stream JSONL events:
 
 ```bash
-harnex events --id cx-impl-42 | jq -c '.'
+harnex events --id pi-impl-42
 ```
 
 Schema details and compatibility policy are documented in
 [docs/events.md](docs/events.md).
 
+## Dispatch history
+
+Every finished `harnex run` writes dispatch records. In a git repo, the
+default path is `<repo>/.harnex/dispatch.jsonl`; outside a git repo, the
+compact history record falls back to `~/.local/state/harnex/dispatch.jsonl`.
+`harnex history` reads the compact records from that location.
+
+Use `harnex history` to inspect it:
+
+```bash
+harnex history
+harnex history --json | jq .
+```
+
+Dispatch briefs can declare soft budget metadata through `--meta`:
+
+```bash
+harnex run pi --meta '{"read_budget_lines":2000,"output_ceiling_lines":800}' ...
+```
+
+Those declared values are copied into summary `meta`. Terminal summary
+`actual` records timing, exit classification, token usage when the adapter can
+capture it, adapter-reported `cost_usd` when reliably available, git deltas,
+task-completion state, operational counters (`stalls`, `force_resumes`,
+`disconnections`, `tool_calls`, `commands_executed`), output/event log paths,
+and rough volume measurements such as `lines_changed`, `output_lines`,
+`output_bytes`, and `event_records`.
+Harnex records the data only; consumers decide whether to fail closed. See
+[docs/dispatch-telemetry.md](docs/dispatch-telemetry.md) for the field
+contract.
+
 ## Long-running and overnight work
 
 For plain "force-resume on stall" recovery, use
-`harnex run --watch --preset impl`.
+`harnex run pi --watch --preset impl --context "Read /tmp/task.md"`.
 
 A **buddy** is for richer reasoning: doc drift checks, semantic sanity checks,
 and multi-session correlation. It's still just another harnex session.
@@ -155,8 +222,8 @@ and multi-session correlation. It's still just another harnex session.
 Spawn a buddy alongside a long-running implementation worker:
 
 ```bash
-harnex run codex --id worker-42 --tmux
-harnex run claude --id buddy-42 --tmux
+harnex run pi --id worker-42 --tmux worker-42
+harnex run pi --id buddy-42 --tmux buddy-42
 harnex send --id buddy-42 --message "$(cat <<'EOF'
 Watch harnex session worker-42.
 Every 5 minutes: run `harnex pane --id worker-42 --lines 30`.
@@ -165,7 +232,7 @@ nudge it: `harnex send --id worker-42 --message "Continue your task."`.
 When it exits, report back:
   tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-42 done" Enter
 EOF
-"
+)"
 ```
 
 ### Example: watch for doc drift during implementation
@@ -174,8 +241,8 @@ A buddy that checks whether a worker's code changes have left
 docs out of date:
 
 ```bash
-harnex run codex --id worker-99 --tmux
-harnex run claude --id buddy-99 --tmux
+harnex run pi --id worker-99 --tmux worker-99
+harnex run pi --id buddy-99 --tmux buddy-99
 harnex send --id buddy-99 --message "$(cat <<'EOF'
 Watch harnex session worker-99.
 Every 5 minutes: run `harnex pane --id worker-99 --lines 30`.
@@ -187,7 +254,7 @@ inline comments) that are now stale. If so, nudge the worker:
 When the worker exits, report a summary to the invoker:
   tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-99 done. Doc drift: <yes/no>" Enter
 EOF
-"
+)"
 ```
 
 ### The invoker doesn't need to be a harnex session
@@ -210,13 +277,15 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 | `harnex send --id <id>` | Send a message (queues if busy, `--wait-for-idle` to block until done) |
 | `harnex stop --id <id>` | Send the agent's native exit sequence |
 | `harnex status` | List running sessions (`--json` for full payloads) |
-| `harnex pane --id <id>` | Capture the agent's tmux screen (`--follow` for live) |
+| `harnex pane --id <id>` | Capture a tmux-backed session's screen (`--follow` for live) |
 | `harnex logs --id <id>` | Read session transcript (`--follow` to tail) |
 | `harnex events --id <id>` | Stream structured session events (`--snapshot` for non-blocking dump) |
-| `harnex wait --id <id>` | Block until exit or a target state |
+| `harnex history` | List completed dispatches from `.harnex/dispatch.jsonl` |
+| `harnex wait --id <id>` | Block until exit, a target state, or `--until task_complete` |
+| `harnex doctor` | Run adapter dependency preflight checks; add `--sweep` for read-only session drift diagnostics |
 | `harnex guide` | Getting started walkthrough |
 | `harnex agents-guide` | Agent-facing dispatch, chain, buddy, monitoring, and naming guides |
-| `harnex recipes` | Tested workflow patterns |
+| `harnex recipes` | List and read tested workflow patterns (`show 01`, `show buddy`) |
 
 ## Uninstalling
 

data/TECHNICAL.md

@@ -29,6 +29,7 @@ harnex run codex -- --cd ~/other/repo
 | `--watch-file PATH` | Auto-send a file-change hook (`--watch PATH`/`--watch=PATH` legacy) |
 | `--context TXT`     | Give the agent a task on startup                                    |
 | `--auto-stop`       | With `--context`, stop after the first task completion              |
+| `--fast`            | For Codex, use `service_tier="fast"` instead of default `flex`      |
 | `--timeout SEC`     | Wait budget for detached registration                               |
 
 ### `harnex send` — Talk to a running agent
@@ -88,6 +89,16 @@ harnex wait --id worker
 harnex wait --id worker --until prompt --timeout 300
 ```
 
+### `harnex history` — List completed dispatches
+
+```bash
+harnex history
+harnex history --json | jq .
+```
+
+Reads `<repo>/.harnex/dispatch.jsonl`, where `<repo>` is found by walking up
+until `.git/` is present. Use `--global` for the no-repo fallback file.
+
 ### `harnex logs` — Read session transcripts
 
 ```bash
@@ -247,6 +258,7 @@ Schema details and compatibility guarantees are in [docs/events.md](docs/events.
    ├── base.rb     adapter interface
    ├── generic.rb  fallback adapter for any CLI
    ├── codex.rb    codex-specific behavior
+   ├── opencode.rb opencode-specific behavior
    └── claude.rb   claude-specific behavior
 ```
 
@@ -365,6 +377,17 @@ The adapter reads the screen and returns a state hash:
 - Multi-step submit: types text, then sends Enter after a
   short delay so pasted prompts are actually submitted
 
+### OpenCode Adapter
+
+- Uses optimistic PTY prompt detection to avoid inbox deadlock
+  when OpenCode's alternate-screen TUI omits stable plain-text
+  prompt markers in snapshots.
+- Stop sequence sends a double Ctrl+C to match OpenCode's native
+  terminal shutdown path (interrupt first, force-quit second if
+  needed).
+- Multi-step submit mirrors Claude/Codex PTY behavior: text first,
+  then Enter with a short delay.
+
 ## State Machine
 
 `SessionState` tracks the agent's readiness:

data/guides/01_dispatch.md

@@ -17,7 +17,7 @@ Inside a harnex-managed session, these environment variables are available:
 
 | Variable | Meaning |
 | --- | --- |
-| `HARNEX_SESSION_CLI` | Wrapped CLI name, such as `codex` or `claude` |
+| `HARNEX_SESSION_CLI` | Wrapped CLI name, such as `pi`, `codex`, or `claude` |
 | `HARNEX_ID` | Current harnex session ID |
 | `HARNEX_SESSION_REPO_ROOT` | Repo root for the session |
 | `HARNEX_SESSION_ID` | Internal harnex instance ID |
@@ -34,13 +34,13 @@ Decide how results come back before you delegate work.
 Inside harnex, instruct the peer to reply to your own session:
 
 ```bash
-harnex send --id cx-i-NN --message "Read /tmp/task-impl-NN.md. When done, send one summary line back to harnex id $HARNEX_ID."
+harnex send --id pi-i-NN --message "Read /tmp/task-impl-NN.md. When done, send one summary line back to harnex id $HARNEX_ID."
 ```
 
 Outside harnex, require a file or another explicit return path:
 
 ```bash
-harnex send --id cx-i-NN --message "Read /tmp/task-impl-NN.md. Write final status to /tmp/cx-i-NN-done.txt."
+harnex send --id pi-i-NN --message "Read /tmp/task-impl-NN.md. Write final status to /tmp/pi-i-NN-done.txt."
 ```
 
 Do not delegate work without an explicit completion contract.
@@ -48,18 +48,18 @@ Do not delegate work without an explicit completion contract.
 ## Spawn
 
 Launch worker sessions in tmux when a user or orchestrator may need to inspect
-them live:
+them live. Default to Pi unless a task explicitly requires another adapter:
 
 ```bash
-harnex run codex --id cx-i-NN --tmux cx-i-NN \
+harnex run pi --id pi-i-NN --tmux pi-i-NN \
   --context "Implement the project plan in /tmp/task-impl-NN.md. Run tests when done."
 ```
 
-For long prompts, write the details into a file and reference it. PTYs are more
-reliable with short injected messages.
+For long prompts, write the details into a file and reference it. Structured
+sends are more reliable with short injected messages.
 
 ```bash
-harnex run codex --id cx-i-NN --tmux cx-i-NN \
+harnex run pi --id pi-i-NN --tmux pi-i-NN \
   --context "Read and execute /tmp/task-impl-NN.md"
 ```
 
@@ -70,7 +70,7 @@ parallel orchestration compact:
 
 ```bash
 for i in 1 2 3; do
-  harnex run codex --id w-$i --tmux w-$i --detach \
+  harnex run pi --id w-$i --tmux w-$i --detach \
     --context "Read and execute /tmp/task-$i.md" --auto-stop &
 done
 for i in 1 2 3; do harnex wait --id w-$i & done
@@ -81,25 +81,28 @@ Rule: when you use `--tmux`, pass the same name as `--id`. If you pass only
 `--tmux NAME`, harnex creates a random session ID and the pane name no longer
 matches `harnex status` or `harnex pane --id`.
 
+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`).
+
 Codex flag forms differ between transports. The default JSON-RPC adapter
 (`codex app-server`) does not accept `-m`/`--model`; pass the model as
 `-c model="<name>"` instead. The legacy PTY adapter (`harnex run codex
---legacy-pty`) still accepts `-m`. Harnex rejects `-m` early on JSON-RPC
-with an actionable error rather than letting the subprocess boot-disconnect.
+--legacy-pty`) still accepts `-m`. Codex app-server runs also default to
+`service_tier="flex"`; add `--fast` to use `service_tier="fast"`.
 
 ## Send
 
 Use `--message` for short instructions and file references:
 
 ```bash
-harnex send --id cx-i-NN --message "Continue with /tmp/task-impl-NN.md. Report final status to $HARNEX_ID."
+harnex send --id pi-i-NN --message "Continue with /tmp/task-impl-NN.md. Report final status to $HARNEX_ID."
 ```
 
 Use `--wait-for-idle` only as a turn fence. It proves that one send returned to
 an idle state; it is not a full work-completion signal.
 
 ```bash
-harnex send --id cx-i-NN --message "Run the acceptance test." --wait-for-idle --timeout 900
+harnex send --id pi-i-NN --message "Run the acceptance test." --wait-for-idle --timeout 900
 ```
 
 Messages sent from one harnex session to another include a relay header:
@@ -118,16 +121,16 @@ Use the lightest primitive that gives the signal you need:
 
 | Need | Command |
 | --- | --- |
-| Current live screen | `harnex pane --id cx-i-NN --lines 40` |
-| Continuous pane view | `harnex pane --id cx-i-NN --follow` |
-| Transcript tail | `harnex logs --id cx-i-NN --lines 80` |
-| Structured events | `harnex events --id cx-i-NN --snapshot` |
-| Native turn completion | `harnex wait --id cx-i-NN --until task_complete` |
+| Current live screen | `harnex pane --id pi-i-NN --lines 40` |
+| Continuous pane view | `harnex pane --id pi-i-NN --follow` |
+| Transcript tail | `harnex logs --id pi-i-NN --lines 80` |
+| Structured events | `harnex events --id pi-i-NN --snapshot` |
+| Native turn completion | `harnex wait --id pi-i-NN --until task_complete` |
 
 For unattended policy-only stall recovery, use 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"
 ```
 
 `--watch` is foreground-blocking. Use it when a single process should launch
@@ -140,10 +143,10 @@ Before stopping a worker, verify the expected artifact, test result, commit,
 or review output exists:
 
 ```bash
-harnex pane --id cx-i-NN --lines 60
+harnex pane --id pi-i-NN --lines 60
 git status --short
 git log --oneline -5
-harnex stop --id cx-i-NN
+harnex stop --id pi-i-NN
 ```
 
 Stop completed sessions promptly. Fresh workers are easier to reason about

data/guides/02_chain.md

@@ -39,6 +39,9 @@ Issue or request
 Each arrow is a fresh harnex worker when delegated. Pass state through files:
 the issue, plan, review file, fix summary, test log, or done marker.
 
+Default adapter choice for autonomous chain steps is Pi (`harnex run pi ...`).
+Use another adapter only when the task explicitly requires it.
+
 ## Per-Plan Loop
 
 For each independently testable plan:
@@ -72,8 +75,8 @@ Recommended limits:
 | Code review/fix | Serial per implementation |
 
 When parallelizing, cap the number of active workers to what the machine and
-CLI provider can handle. A practical upper bound is five Codex sessions across
-all active lanes unless the user requested more.
+CLI provider can handle. A practical upper bound is five active sessions across
+all lanes unless the user requested more.
 
 ## Worktrees
 
@@ -84,7 +87,7 @@ untracked files do not carry over.
 ```bash
 git worktree add ../project-plan-NN -b plan/NN main
 cd ../project-plan-NN
-harnex run codex --id cx-i-NN --tmux cx-i-NN \
+harnex run pi --id pi-i-NN --tmux pi-i-NN \
   --context "Read the project plan and implement this isolated lane."
 ```