harnex 0.10.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25ba2b12b69cc6351e2ca4ee1e72e5f378a3828f7486498a2e2a026cf9da771b
-  data.tar.gz: 7e3cc95587c16dcb0a7b9a3e8339546a9ffbe085e4517407f1325e87fd2f45ce
+  metadata.gz: 3ea3eab047cc2e9f086fba4cfb98c6f585ffe888fdee0fb018c35515fe6257b4
+  data.tar.gz: ba40b96028fd01e6ade7517374e7d26d92a5d147a7be2ec08a581cd0203dae62
 SHA512:
-  metadata.gz: fcaa6d99632c375c1315bfc553b99ccf5c583b58a52e627e0af951493481bf33af9b5de50ca4704a1e6e2d7d9a8aa6999b42d94347ff942b76ac5033eb870dae
-  data.tar.gz: 929011b78aa399cc098b644f0bb2a0995222df71698e450e7ab4785e1be9249e07e4d40225fbf80e02ea9a11f6fefd7913c27682110944ccadacea8f879e7200
+  metadata.gz: e1e85c57df13dd411b10308659b72376f9491f1c6e4d7c4e5d906f9f78096dc0f82a0ac866c01e356d75cedb5f285b71970d0ea175e5935ca8ed0e3bcf40dd88
+  data.tar.gz: 1283d788ceaff2e608f7e13b7f4f640d65d9f683e35cbe649cc9dd7d0223e094740df146fbe10ed6fa15685bf27671e9059c6378bb2bc8acc5c850aef5f6c9ab

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## [0.12.0] - 2026-09-03 | 10:09 AM | IST
+
+### Added
+
+- Registered sessions now atomically publish a typed completion marker under
+  `$HARNEX_STATE_DIR/done/` at the first accepted, rejected, failed, or error
+  work result, without requiring a `wait` or `watch` client.
+- `harnex run --on-done CMD` launches one non-blocking trusted local shell hook
+  with typed completion, receipt, commit, and elapsed-time environment values.
+  The option works in foreground, detached, and tmux launches.
+
+### Changed
+
+- `harnex status` now renders settled live work (`done`, `rejected`, or
+  `failed`) ahead of an adapter's prompt/busy state. Existing JSON fields and
+  the v2 dispatch envelope remain unchanged.
+
+## [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

@@ -87,6 +87,25 @@ for i in 1 2 3; do harnex watch --id w-$i --until done --max-wait 90m & done
 wait
 ```
 
+For unattended work, add a session-owned push signal rather than depending on
+one long blocking watcher call:
+
+```bash
+harnex run pi --id pi-i-NN --tmux pi-i-NN \
+  --context "Read and execute /tmp/task-NN.md" --auto-stop \
+  --on-done 'printf "%s %s\n" "$HARNEX_ID" "$HARNEX_OUTCOME" >> koder/scratch/HARNEX_WAKE.txt'
+```
+
+Every registered session writes
+`$HARNEX_STATE_DIR/done/<repo-key>--<normalized-id>.<outcome>`, even without a
+hook. `--on-done CMD` receives `HARNEX_ID`, `HARNEX_OUTCOME`,
+`HARNEX_WORK_STATE`, `HARNEX_RECEIPT_PATH`, `HARNEX_END_SHA`, and
+`HARNEX_ELAPSED_S`. Use a gitignored wake file. `CMD` is trusted `/bin/sh -c`
+input; never embed secrets in the command line.
+
+A push only wakes the consumer. Even `completed` requires report, artifact,
+test, and Git verification plus bounded `harnex watch --until done` calls.
+
 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`.
@@ -148,8 +167,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

@@ -17,12 +17,30 @@ Prefer signals in this order:
 | `harnex pane` | Live UI interpretation and prompt/error diagnosis |
 | `harnex status` | Session liveness and coarse state |
 
-For unattended monitors on existing visible/detached sessions, prefer
-`harnex watch --until done`: it returns on the work-level `task_complete` or
+For unattended sessions, combine bounded watcher calls with the runner-owned
+push path. Every session writes
+`$HARNEX_STATE_DIR/done/<repo-key>--<id>.<outcome>` at its first work-terminal
+result. `harnex run --on-done CMD` can also launch one non-blocking local hook,
+even without a watcher and while the agent remains alive at a prompt:
+
+```bash
+harnex run pi --id pi-i-NN --tmux pi-i-NN --context "Read the task brief" \
+  --auto-stop \
+  --on-done 'printf "%s %s\n" "$HARNEX_ID" "$HARNEX_OUTCOME" >> koder/scratch/HARNEX_WAKE.txt'
+harnex watch --id pi-i-NN --until done --max-wait 30m
+```
+
+Use a gitignored wake destination. `CMD` is trusted shell input; never embed
+secrets. It receives `HARNEX_ID`, `HARNEX_OUTCOME`, `HARNEX_WORK_STATE`,
+`HARNEX_RECEIPT_PATH`, `HARNEX_END_SHA`, and `HARNEX_ELAPSED_S`. `completed`
+wakes the consumer but does not certify the prose; verify the receipt and
+artifact before acting.
+
+`harnex watch --until done` returns on the work-level `task_complete` or
 `task_failed` signal, or terminal exit, whichever comes first. Successful work
 exits `0`, failed work exits non-zero, and wall-clock caps exit `124`. For
 callers that need the lower-level primitive, `harnex wait --until done` exposes
-the same work fence.
+the same work fence. Do not park an orchestrator in one unbounded watcher call.
 
 ## Live-Run Visibility
 
@@ -31,8 +49,10 @@ Every dispatch appends a `dispatch_start` row to the repo's dispatch stream
 completes it. Between those two rows the run is visible to every documented
 signal, from any cwd in the same repo:
 
-- `harnex status --id X` reports `state=running` for a live session. When the
-  live HTTP status API is unreachable it still reports running from the
+- `harnex status --id X` reports settled work as `done`, `rejected`, or
+  `failed` even while the adapter is back at `prompt`. When work is unsettled,
+  it reports the adapter input state. If the live HTTP status API is
+  unreachable it still reports running from the
   registry (or, failing that, from the uncompleted start row) and labels the
   row `degraded: true` with `source` set to `registry` or `dispatch_start`.
 - `harnex history` shows uncompleted dispatches as `running` (pid alive) or
@@ -68,8 +88,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
@@ -205,7 +228,8 @@ interpretation.
 - Polling `state=completed` alone and missing live sessions with `task_complete=true`.
 - Polling `state=prompt` alone and calling it done.
 - Wrapping `harnex wait` in loops that swallow non-zero `task_failed` results.
-- Blocking orchestrators on `/tmp/*-done.txt` as the only completion signal.
+- Blocking orchestrators on caller-owned `/tmp/*-done.txt` as the only completion signal.
+- Using one long watcher call without the runner-owned marker or `--on-done` push path.
 - Letting an unattended loop run with no wall-clock cap.
 - Reading raw tmux panes instead of `harnex pane`.
 - Using `--wait-for-idle` as acceptance proof.