harnex 0.7.3 → 0.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 315057f04a626949bd270491616595e98d3d298a4b49aa7d70d23aa0cda0501d
-  data.tar.gz: 06c539f5911aa58fa427c80570ca7998ce382d6077a015ae8dc4d181cf05a00f
+  metadata.gz: 4c6173057b1fe4fa547979d3d9803f345acb4e658dd942aefa096ef886727c33
+  data.tar.gz: da1662c9dce791ae644aa4a0ea57d2124a1698593e6db98b2ac737d9f42816f6
 SHA512:
-  metadata.gz: 15b5c96adb86810626229e9d037992cce4566d8aee83856870735f9e28c8e61b63f567d6af18a946b98f9696b2387f9e6b1b77d65659989c749db5eb7de6ef1b
-  data.tar.gz: cdf1b6b3ce3c1934fd768b983df7db3e7aa296abd83e3c926d0a1b7760a5ff1cb9d433742b8edd15740ced1c0dc735d8027c6849eb474fa5049d73ae4246c5b2
+  metadata.gz: e2758cfa10fc9b221235efea20ff21be32b5558c1ab06eb4515cea5485be96e1371d663735c826d9587833caa46aed65486b5c3cedfe8ce3be04e7ac1c328f7f
+  data.tar.gz: 765cf4ef020f3a7cfa8bbd1aad517ac1b4ec8901579b3720ea618ec246b20009c07c088d4d86e354ead78194844bba771790df0271d54fccecad6f6058874d9f

data/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## [Unreleased]
 
+## [0.7.5] - 2026-05-26 | 05:18 PM | IST
+
+### Added
+
+- `Harnex::TerminalStatus` now resolves durable terminal dispatch state from
+  summary/history rows so commands can classify inactive sessions without
+  relying on tmp done markers.
+
+### Changed
+
+- `harnex status --json --id <id>` now returns a machine-readable row even when
+  the live session is gone, with `state` in `running|completed|failed|unknown`
+  and terminal metadata (`terminal`, `exit`, `exit_code`, `summary_out`).
+- `harnex wait --id <id>` now falls back to terminal summary/history telemetry
+  when registry and exit-status files are missing, returning `completed` on
+  summary success and `unknown` when no durable terminal signal exists.
+- Monitoring guides now treat `/tmp/*-done.txt` as legacy compatibility hints;
+  canonical completion is `harnex wait` / `harnex status --json` / dispatch
+  summary rows.
+
+## [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 `harnex status --id pi-i-42 --json` reports `state=completed` or `state=failed`, report back:
+- `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "pi-i-42 terminal state reached. Check harnex status --id pi-i-42 --json." 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,22 +17,27 @@ 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:
+For unattended work, first gate on harnex terminal state, then verify the task
+artifact and repo health:
 
 ```bash
-test -f /tmp/cx-i-NN-done.txt &&
-  test -z "$(git status --short)" &&
-  test "$(git log -1 --format=%ct)" -lt "$(($(date +%s) - 600))"
+harnex wait --id pi-i-NN --timeout 5400 &&
+  test -f path/to/expected-artifact &&
+  test -z "$(git status --short)"
 ```
 
-Adjust the artifact path and commit-age window to the task. The point is to
-avoid declaring done while a worker is between edits or between commits.
+`harnex wait` succeeds from durable terminal telemetry (`--summary-out` /
+`.harnex/dispatch.jsonl` / exit status), not from tmp done markers.
+
+Adjust the artifact path to the task. The point is to avoid declaring done while
+a worker is between edits or between commits.
 
 ## Why Pane State Alone Is Not Enough
 
@@ -51,43 +56,51 @@ 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
 
-Consumers often run a small shell loop that checks the expected done marker,
-tree state, and harnex liveness. Keep a hard wall-clock cap so an unattended
-pipeline cannot wait forever:
+Consumers often run a small shell loop that checks terminal state, then drops
+to pane diagnostics only while work is still running. Keep a hard wall-clock cap
+so an unattended pipeline cannot wait forever:
 
 ```bash
 start=$(date +%s)
 max_wait=5400
 
-until test -f /tmp/cx-i-NN-done.txt; do
+while :; 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
+  row=$(harnex status --id pi-i-NN --json | ruby -rjson -e 'rows=JSON.parse(STDIN.read); print JSON.generate(rows.first || {})')
+  state=$(printf '%s' "$row" | ruby -rjson -e 'print(JSON.parse(STDIN.read)["state"].to_s)')
+
+  case "$state" in
+    completed) echo "pi-i-NN completed"; break ;;
+    failed|unknown) echo "pi-i-NN terminal state: $state" >&2; exit 1 ;;
+    running) harnex pane --id pi-i-NN --lines 20 ;;
+    *) harnex pane --id pi-i-NN --lines 20 ;;
+  esac
+
   sleep 60
 done
 ```
@@ -106,7 +119,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"
 ```
 
@@ -124,6 +137,7 @@ interpretation.
 ## Anti-Patterns
 
 - Polling `state=prompt` alone and calling it done.
+- Blocking orchestrators on `/tmp/*-done.txt` as the only completion signal.
 - 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.