harnex 0.7.3 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 315057f04a626949bd270491616595e98d3d298a4b49aa7d70d23aa0cda0501d
-  data.tar.gz: 06c539f5911aa58fa427c80570ca7998ce382d6077a015ae8dc4d181cf05a00f
+  metadata.gz: e99b85fa8112b666665da16757d871098867e0b05c9521c3507fc2092616f825
+  data.tar.gz: 78a5190335ee968c77d75531d23998c34272d24a3b6a8d6a53d5e9a8922c87da
 SHA512:
-  metadata.gz: 15b5c96adb86810626229e9d037992cce4566d8aee83856870735f9e28c8e61b63f567d6af18a946b98f9696b2387f9e6b1b77d65659989c749db5eb7de6ef1b
-  data.tar.gz: cdf1b6b3ce3c1934fd768b983df7db3e7aa296abd83e3c926d0a1b7760a5ff1cb9d433742b8edd15740ced1c0dc735d8027c6849eb474fa5049d73ae4246c5b2
+  metadata.gz: 4c32673867f2b86ee84fa1768ee4fee82a3ddb0fb69abd5c369349d59fe9feef3cc468ee71776115da19ca2997b1f647678b413f8c93d02538f56c17daf316d4
+  data.tar.gz: bf049097af8736c25991af1894dd15b6cc8159393f99eb215a0dc7ddd67f9716b1864589664fdd08671edc6859899c9cb84c46852b940323b8f11f42d5f8ee29

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [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

data/README.md

@@ -2,9 +2,9 @@
 
 Run multiple AI coding agents from your terminal and coordinate them.
 
-Harnex wraps Claude Code, OpenAI Codex, or any terminal CLI in a local
-harness so you can launch agents, send them tasks, watch live panes or
-transcripts, 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
@@ -34,7 +34,7 @@ or project-local docs are required.
 
 ```bash
 # Start an agent in tmux
-harnex run codex --id planner --tmux planner
+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
@@ -52,12 +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
-  a tmux-backed agent's live terminal, or Codex's synthesized
-  JSON-RPC transcript. 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.
@@ -76,7 +76,8 @@ job, watch it work, stop it when done.
 | Agent | Support |
 |-------|---------|
 | 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; `--legacy-pty` remains supported for TUI/interactive PTY use |
+| 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 |
 
@@ -87,22 +88,28 @@ model settings as child CLI config, for example `harnex run codex -- -c model=NA
 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 legacy PTY flag behavior.
+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 cx-plan
-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 cx-impl
-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 cl-review
@@ -137,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:
 
@@ -153,13 +162,17 @@ 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
+harnex events --id pi-impl-42
 ```
 
 Schema details and compatibility policy are documented in
@@ -167,10 +180,10 @@ Schema details and compatibility policy are documented in
 
 ## Dispatch history
 
-Every finished `harnex run` appends one JSON line to
-`<repo>/.harnex/dispatch.jsonl`. Harnex finds the repo by walking up from the
-run directory until it sees `.git/`; sessions outside a git repo write to
-`~/.local/state/harnex/dispatch.jsonl`.
+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:
 
@@ -182,18 +195,24 @@ harnex history --json | jq .
 Dispatch briefs can declare soft budget metadata through `--meta`:
 
 ```bash
-harnex run codex --meta '{"read_budget_lines":2000,"output_ceiling_lines":800}' ...
+harnex run pi --meta '{"read_budget_lines":2000,"output_ceiling_lines":800}' ...
 ```
 
 Those declared values are copied into summary `meta`. Terminal summary
-`actual` also records rough measurements for downstream enforcement:
-`lines_changed`, `output_lines`, `output_bytes`, and `event_records`.
-Harnex records the data only; consumers decide whether to fail closed.
+`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 codex --watch --preset impl --context "Read /tmp/task.md"`.
+`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.
@@ -203,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 worker-42
-harnex run claude --id buddy-42 --tmux buddy-42
+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`.
@@ -222,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 worker-99
-harnex run claude --id buddy-99 --tmux buddy-99
+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`.
@@ -258,7 +277,7 @@ 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 history` | List completed dispatches from `.harnex/dispatch.jsonl` |
@@ -266,7 +285,7 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 | `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/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,27 +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.
-Codex app-server runs also default to `service_tier="flex"`; add
-`--fast` to use `service_tier="fast"`.
+--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:
@@ -120,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
@@ -142,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."
 ```
 

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

@@ -24,8 +24,9 @@ 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