harnex 0.12.0 → 0.29.0

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 `pi`, `codex`, or `claude` |
+| `HARNEX_SESSION_CLI` | Wrapped CLI name, such as `pi` or `claude` |
 | `HARNEX_ID` | Current harnex session ID |
 | `HARNEX_SESSION_REPO_ROOT` | Repo root for the session |
 | `HARNEX_SESSION_ID` | Internal harnex instance ID |
@@ -68,15 +68,31 @@ harnex run pi --id pi-i-NN --tmux pi-i-NN \
   --context "Read and execute /tmp/task-impl-NN.md"
 ```
 
+For a one-shot task, add `--auto-stop --wait-done --wait-timeout 9m`: the
+same command blocks until the first turn's result and prints it with the
+launch fields (`turn_result.final_message` is the worker's reply; on 124 run
+the `resume` command it prints). `harnex ask "QUESTION"` does that for a
+read-only question and prints only the answer. See `harnex agents-guide
+claude` for the Claude Code patterns.
+
+To send a brief file's text itself, use `--context-file PATH`. Add
+`--context-section TEXT` to send only one part: after a Markdown heading that
+starts with TEXT, up to the next heading of the same or a higher level; after a
+plain marker line (e.g. `Sent verbatim as the harnex --context.`), to the end
+of the file. An empty result is refused before launch. `--meta-file PATH`
+reads `--meta` JSON from a file and refuses invalid JSON (inline `--meta`
+keys win). The brief's path and the SHA-256 of the sent text are recorded as
+`meta.context_file` / `meta.context_sha256` on the started event and dispatch
+rows.
+
 For one-shot context dispatches that should clean themselves up, add
-`--auto-stop`. It requires `--context` and does not keep the session alive for
-later reuse. On Codex app-server, a turn launched from `--context` is accepted
-only after structured command/tool activity or a Git delta. Optional claims and
-final prose cannot satisfy that observed-activity gate. A prose-only acknowledgment emits
-`completed_no_activity`, is
-visible as `task_failed` before teardown, and exits non-zero. This keeps
-parallel orchestration compact without converting agent turn completion into
-accepted work completion:
+`--auto-stop`. It requires `--context` (or `--context-file`) and does not keep
+the session alive for later reuse. A Pi turn is accepted when it settles. With
+`--require-artifact-report` it must also show command/tool activity or a Git
+delta; optional claims and final prose cannot satisfy that gate, and a
+prose-only acknowledgment emits `completed_no_activity`, is visible as
+`task_failed` before teardown, and exits non-zero. This keeps parallel
+orchestration compact:
 
 ```bash
 for i in 1 2 3; do
@@ -87,24 +103,56 @@ 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:
+Before an unattended queue run, prove the plumbing with one tiny real
+dispatch for the chosen worker and one declared fallback (with Pi, a fallback
+`--model`). Both must be inside your dispatch-model policy; an out-of-policy
+fallback is a launch blocker, not a fallback. `preflight` exits non-zero on any failed check
+(boot, registration, trust prompt, task read, workspace write, command exit,
+receipt, claims, completion, stop) and names the failure class:
 
 ```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'
+harnex preflight pi --cwd "$REPO" \
+  && harnex preflight pi --cwd "$REPO" --model "$FALLBACK_MODEL" \
+  && harnex run pi --id pi-i-NN --tmux pi-i-NN --context "Read and execute /tmp/task-NN.md" --auto-stop
 ```
 
-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.
+Add `--commit-check` when workers must commit (it commits only in a throwaway
+scratch repo). Preflight rows land in history with `phase=preflight` and stay
+out of `orchestration report` rollups unless `--include-preflight` is passed.
+
+To separate final acceptance from exploratory command noise in the receipt,
+declare the final commands: `--final-gate 'bundle exec rake test'` (repeatable).
+`validation.status` then reflects each gate's last observed exit, and
+`validation.commands_had_failures` keeps the history. Still replay the gates
+yourself before accepting work.
+
+For unattended work, pair each dispatch with an owner-addressed consumer and
+bounded native monitoring rather than depending on one long blocking watcher:
+
+```bash
+harnex run pi --id pi-i-NN --tmux pi-i-NN \
+  --context "Read and execute /tmp/task-NN.md" --auto-stop
+```
 
-A push only wakes the consumer. Even `completed` requires report, artifact,
-test, and Git verification plus bounded `harnex watch --until done` calls.
+When `harnex run` is invoked by a Pi shell tool, it captures `PI_SESSION_ID`
+(from a Claude Code Bash shell, `CLAUDE_CODE_SESSION_ID`; Pi's wins if both
+are present) before crossing detached/tmux process boundaries. The session registers a
+per-owner, per-attempt record under `$HARNEX_STATE_DIR/notifications/` before
+sending the structured initial prompt, then atomically settles that record at
+the first typed outcome. A nested Harnex worker never implicitly nominates
+itself; non-Pi or nested orchestrators can pass `--orchestration-session-id`
+explicitly. Dispatch-name reuse does not erase these records.
+
+Every registered session also writes the existing
+`$HARNEX_STATE_DIR/done/<repo-key>--<normalized-id>.<outcome>` marker. Optional
+`--on-done CMD` remains available for single-consumer integrations and receives
+`HARNEX_ID`, `HARNEX_OUTCOME`, `HARNEX_WORK_STATE`, `HARNEX_RECEIPT_PATH`,
+`HARNEX_END_SHA`, and `HARNEX_ELAPSED_S`; never use one destructive shared file
+as a multi-session delivery queue. `CMD` is trusted `/bin/sh -c` input, so do
+not embed secrets in the command line.
+
+A delivery only wakes the consumer. Even `completed` requires exact-receipt,
+artifact, test, and Git verification plus a durable consumer acknowledgment.
 
 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
@@ -115,7 +163,7 @@ wrapped agent from that directory and associate session metadata/default
 telemetry with it:
 
 ```bash
-harnex run codex --cwd /tmp/leximaze_eval_run_001 \
+harnex run pi --cwd /tmp/leximaze_eval_run_001 \
   --id lm-run-001 \
   --context "Read README.md and write RESPONSES.jsonl and OUTPUT.md" \
   --auto-stop
@@ -169,17 +217,11 @@ phase names before spawn.
 
 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
-`-c model="<name>"` instead. The legacy PTY adapter (`harnex run codex
---legacy-pty`) still accepts `-m`. Codex app-server runs also default to
-`service_tier="flex"`; add `--fast` to use `service_tier="fast"`.
+apply verified Pi startup controls before the prompt (e.g. `--model
+openai/gpt-5.1 --effort high`). Pass other Pi startup flags after
+`--` (e.g. `harnex run pi --context "..." -- --approve`).
+Since RPC cannot display Pi's trust prompt, harnex starts Pi with
+`--no-approve` (project-local resources ignored) unless you pass `--approve`.
 
 ## Send
 
@@ -196,6 +238,31 @@ an idle state; it is not a full work-completion signal.
 harnex send --id pi-i-NN --message "Run the acceptance test." --wait-for-idle --timeout 900
 ```
 
+Sending to a busy worker:
+
+- **Pi:** the message is handed to Pi at once as a follow-up (`delivery:
+  "follow_up"`) and delivered when the current turn ends. It cannot expire.
+  `--force` steers it into the turn now instead.
+- **Other adapters:** it queues until the agent is at a prompt. If it is not
+  delivered within `--timeout`, send withdraws it and exits 124; if it
+  expires in the inbox (`run --inbox-ttl`), send exits 1 with `status:
+  "expired"`. Either way the caller knows the note was not delivered.
+
+Every delivery reports `after_seq`. To wait for the turn a message started
+(for example after nudging a turn that failed on provider capacity), wait
+after that point so the earlier failure cannot answer:
+
+```bash
+harnex send --id pi-i-NN --message "Continue the same task from where you stopped" \
+  --wait-done --timeout 540
+# on exit 124, resume with the after_seq it printed:
+harnex wait --id pi-i-NN --until done --after-seq 812 --timeout 540
+```
+
+`--wait-done` uses the `wait --until done` exit codes (0 done, 1 failed, 2
+proof rejected, 4 stalled, 124 timeout). Without `--timeout` it waits for
+the turn without a cap.
+
 Messages sent from one harnex session to another include a relay header:
 
 ```text

data/guides/04_monitoring.md

@@ -17,31 +17,138 @@ Prefer signals in this order:
 | `harnex pane` | Live UI interpretation and prompt/error diagnosis |
 | `harnex status` | Session liveness and coarse state |
 
-For unattended sessions, combine bounded watcher calls with the runner-owned
-push path. Every session writes
+For unattended sessions, combine owner-addressed delivery with bounded native
+watching. 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:
+result. A Pi-launched dispatch also registers a durable per-owner, per-attempt
+record under `$HARNEX_STATE_DIR/notifications/` before its initial structured
+prompt, then atomically settles it at terminal work. The runner captures the
+invoking Pi shell's `PI_SESSION_ID`; nested workers are excluded unless an
+external owner is explicitly named with `--orchestration-session-id`.
 
 ```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
+harnex run pi --id pi-i-NN --tmux pi-i-NN \
+  --context "Read the task brief" --auto-stop
+harnex watch --id pi-i-NN --until done --max-wait 15m --heartbeat 60s
 ```
 
-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.
+The consumer must match owner and attempt identity, verify the exact Harnex
+receipt, and persist acknowledgment before continuing. It must not erase a
+shared signal before delivery. `harnex run --on-done CMD` remains an optional
+non-blocking integration hook; `CMD` is trusted shell input, receives the typed
+`HARNEX_*` completion values, and must not target a destructive shared queue.
+`completed` is still only a wake: verify the artifact and acceptance gates.
 
 `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
+exits `0`, failed work exits non-zero, and observer caps exit `124`. For
 callers that need the lower-level primitive, `harnex wait --until done` exposes
 the same work fence. Do not park an orchestrator in one unbounded watcher call.
 
+## Heartbeats and Hard Observer Caps
+
+For LLM callers, opt in to `--heartbeat 60s` on `wait` or `watch`. While the
+observer is blocked, it flushes a diagnostic line to **stderr** at each interval:
+
+```text
+harnex wait: id=pi-i-NN waited=60.0s state=running last_event=started seq=1
+```
+
+These are the last observed state/event/sequence, not evidence of model or tool
+progress. Unknown observations remain `unknown`; a slow probe does not prevent
+heartbeats, but the snapshot can be stale. Neither UI repaint nor log freshness
+is interpreted as work activity. Heartbeats are off by default, including for
+JSON consumers. Even when enabled, stdout remains **one final JSON result**;
+consume stderr live rather than combining/buffering the streams until exit.
+
+`wait --timeout DUR` (alias `--max-wait`) and `watch --max-wait DUR` (alias
+`--timeout`) accept finite positive durations in seconds or with `s`, `m`, `h`
+suffixes. The cap uses a monotonic clock and includes repo resolution, registry
+and event reads, status HTTP, and final-event/exit-status grace. Heartbeats and
+new events never reset it. A late probe result cannot turn an expired observer
+into success. Timeout exits `124`, without stopping the live worker or writing
+compatibility done/fail markers, even with `--stop-on-terminal`.
+
+This bounds the **observer**, not worker runtime. The timed/heartbeat observer
+uses a short-lived, isolated read-side child; cancellation kills and reaps that
+child, not the session. Slow Ruby probes, HTTP, and even slow Ruby cleanup are
+bounded by the cap plus at most one poll and scheduling tolerance. This is not a
+promise to preempt uninterruptible kernel I/O or OS scheduling stalls. Output
+consumers must keep draining streams. Optional marker writes and
+`--stop-on-terminal` are post-observation actions, not read-side probes.
+
+## Worker Runtime Budgets, Activity, and Stops
+
+A watcher timeout stops **waiting**, not working. To cap the worker itself,
+first require `harnex doctor --adapter pi` to report `ok: true` and
+`capabilities.runtime_budget: 1` (available in Harnex 0.14.0+), then opt in:
+
+```bash
+harnex run pi --id pi-i-NN --tmux pi-i-NN \
+  --context "Read the task brief" --auto-stop --max-runtime 30m
+harnex watch --id pi-i-NN --max-wait 5m --heartbeat 60s
+```
+
+`--max-runtime` is a fixed monotonic budget in the session-owning runner. It is
+armed before child launch/initial prompt, after binary validation, and never
+reset by prompts, retries, UI chatter, or activity. Expiry requires no supervisor:
+it terminates the owned worker process group with bounded TERM/KILL escalation
+without waiting for an abort RPC, startup handshake, receipt lock, or runner
+stdout. Normal descendant processes in that group are included; descendants
+which deliberately create a different group/session are not contained. This is
+not an OS sandbox. Child shutdown and receipt/telemetry finalization can take
+additional time and still require working I/O/drained output; this is not a
+promise to preempt OS scheduling or uninterruptible I/O.
+Active work is failed with logical run exit `124`. Expiry used only to clean up
+already accepted idle work preserves that proof and logical exit `0`. The stop
+record says `runtime_budget` when expiry was the first requested stop. An earlier
+stop keeps its original labels but cannot disable the cap: `runtime_budget.enforced`
+and its timestamp plus `runtime_budget_expired` record actual enforcement
+independently. Without this option there is no runtime cap.
+
+`status --json` and dispatch-end records expose separate `activity` and
+`runtime_budget` objects:
+
+- `activity.turn_active`, `turn_started_at`, `turn_age_s` track the current
+  structured run, including quiet waits and retries.
+- `model_active`, `model_started_at`, `model_age_s` describe the observed
+  assistant stream/item lifetime, not hidden provider internals.
+- `last_model_activity_at` / `model_idle_s` and `last_tool_activity_at` /
+  `tool_idle_s` track their respective protocol events. Thinking deltas advance
+  the model clock without retaining their content in the activity tracker.
+- UI requests, queue updates, log mtime, and status reads never advance work
+  clocks. A new run clears the prior run's activity clocks; steering an active
+  run does not. PTY/unobserved activity is `status: unknown` with null clocks.
+- Existing `log_idle_s` and the status table's `IDLE` column remain **log age**,
+  not work progress. A degraded registry snapshot is stale, not a fresh sample.
+
+Stops record bounded caller-declared labels, separately from work acceptance:
+
+```bash
+harnex stop --id pi-i-NN --reason manual --origin cli
+```
+
+Reasons are `manual`, `completion`, `runtime_budget`; origins are `api`, `cli`,
+`auto_stop`, `watch`, `runtime`. These labels are not authenticated identities.
+The first stop request wins. Inspect the `stop_requested` event, live/terminal
+`stop` metadata, or receipt `observed.stop` for reason, origin, request time,
+work state at request, and an applicable runtime limit. Harnex's own budget
+expiry requests `runtime_budget`/`runtime` unless a prior stop already won;
+auto-stop uses `completion`/`auto_stop`;
+`watch --stop-on-terminal` uses `completion`/`watch`. Raw child status remains in
+`process_exited` for Pi and budgeted runs when observed (startup failure may
+have no raw wait status); the final run exit is logical status.
+
+Explicit idle Pi cleanup preserves the latest settled accepted/no-change proof,
+including after follow-up turns. Busy stop rejects unfinished work and cannot
+reuse an older accepted turn. Unexpected EOF, malformed/truncated JSONL, and abnormal
+idle teardown remain failures. Completion notifications remain once per session,
+not once per reusable turn; verify the receipt appropriate to each turn.
+
+Pi `send --force` while busy queues steering for a subsequent assistant turn.
+Transport/queue acceptance is not proof the current model call consumed it.
+Consumer wake deduplication/acknowledgment still belongs in the Pi bridge.
+
 ## Live-Run Visibility
 
 Every dispatch appends a `dispatch_start` row to the repo's dispatch stream
@@ -60,6 +167,10 @@ signal, from any cwd in the same repo:
   `dispatch_end` row.
 - `harnex wait --until done` blocks while the session's pid is alive, up to
   `--timeout`. "No signal yet" from a live worker is never terminal.
+- A bare `harnex wait` (no `--until`) fences process exit. A session started
+  without `--auto-stop` stays alive at its prompt after its turn, so stderr
+  carries a `note:` on entry and again if the turn settles mid-wait; switch
+  to `--until done`. `status --json` exposes `auto_stop`.
 
 A monitor consulting these signals can never classify a healthy mid-run
 worker as dead. If `status` says running, do not dispatch a replacement.
@@ -72,7 +183,8 @@ worker as dead. If `status` says running, do not dispatch a replacement.
 | `1` | `failed` | Work failed, process failed, or killed |
 | `2` | `rejected_proof` | Completed but proof rejected (`completed_no_activity`, `report_missing`, `report_invalid`, `report_rejected`) |
 | `3` | `no_such_session` | No live, start, event, or terminal signal for the id |
-| `124` | `timeout` | `--timeout` elapsed while the session was still running |
+| `4` | `stalled` | `--stall-after DUR`: no progress for DUR; worker is not stopped |
+| `124` | `timeout` | Observer cap elapsed before a result was obtained; worker is not stopped |
 
 The JSON payload always carries `wait_result` plus the work-state fields
 (`done`, `work_state`, `outcome_class`, `artifact_report_status`). The child
@@ -80,6 +192,92 @@ process's own exit code is reported as data (`exit_code`), never passed
 through as wait's exit status. Treat `2` as a work-acceptance failure, `3` as
 a coordination error (wrong id or wrong repo), and only `0` as success.
 
+### Stall detection (`--stall-after`)
+
+`harnex watch --stall-after DUR` (and `wait --until done --stall-after DUR`)
+exits `4` once the live session shows no progress for `DUR`. The worker is not
+nudged or stopped, and no done/fail marker is written. The result carries
+`stall: {clock, idle_s, threshold_s}`:
+
+- `clock: activity` (Pi, the structured adapter): seconds since the
+  latest turn start, model event, or tool event. It counts only while a turn
+  is active, so a session idle at its prompt between turns never stalls. A
+  command that prints nothing for longer than `DUR` counts as a stall too,
+  which also catches hung commands, so choose `DUR` above your longest quiet
+  build or test.
+- `clock: output_log` (PTY adapters): seconds since the transcript last
+  changed. This is conservative, because TUIs redraw spinners.
+
+```bash
+harnex watch --id pi-i-NN --until done --stall-after 25m --max-wait 4h
+case $? in 0) ;; 4) echo "stalled: inspect, nudge or stop it" ;; *) echo "not done" ;; esac
+```
+
+This replaces polling `activity.model_idle_s` yourself. `harnex run --watch
+--stall-after` is a separate babysitter that sends `resume` on output-log
+idle. If both run, set watch's `DUR` above run's `stall-after × (max-resumes
++ 1)`.
+
+## Owner Stream (Claude Code supervisors)
+
+One long-running command reports every dispatch an owner started, so a
+supervisor does not need a poller per worker:
+
+```bash
+harnex watch --owner --stall-after 25m
+```
+
+- **Owner:** `harnex run` from a Claude Code Bash shell records
+  `CLAUDE_CODE_SESSION_ID` as the dispatch owner (from Pi: `PI_SESSION_ID`).
+  `--owner` with no value resolves the same id. Pass
+  `--orchestration-session-id ID` to `run` and `--owner ID` to the stream to
+  name an owner explicitly.
+- **Output:** one JSON line per change, schema `harnex.owner_event.v1`. Events:
+  `started`, `done`, `rejected`, `failed`, `stalled` (with `--stall-after`;
+  once per episode), `stopped`, `timeout`. Each line carries `id`,
+  `session_id`, `repo`, `ts`, `work_state`, plus `outcome_class`,
+  `receipt_path`, `elapsed_s`, `stall`, `reason` where they apply, and a
+  readable `msg`. No heartbeats, so Claude Code's `Monitor` wakes only when
+  something needs a decision.
+- **Restarts:** a restarted stream re-announces `started` for running
+  dispatches and delivers only results it has not delivered before (cursor
+  under the owner's notifications directory). Delivery is not acceptance:
+  still verify the receipt and artifacts.
+- **Turns:** every turn reports its own result, once and in order, even when
+  several turns end between two polls. A lane nudged with `harnex send` after
+  it finished or failed reports again when that turn ends; the line carries
+  `turn` and the `msg` names it (`pi-i-NN turn 2 done ...`). Result lines
+  carry the worker's `final_message` (bounded; full text at
+  `final_message_path`).
+- **Lifetime:** it runs until killed, or until `--max-wait` (exit 124).
+
+### Claude Code subagents: `--once`
+
+A subagent cannot be woken by a background notification after it ends its
+turn, so it must block in a foreground Bash call (10-minute cap per call).
+`--once` makes one call cover every lane the owner launched:
+
+```bash
+harnex watch --owner --once --timeout 9m --cursor sub-a --stall-after 25m
+```
+
+It prints every undelivered result or stall that is ready (one JSON line
+each), advances the cursor and exits 0; with nothing new before `--timeout` it
+prints nothing and exits 124, so loop it. It never returns `started`, and a
+stall episode is reported once across calls. A subagent shares its parent's
+`CLAUDE_CODE_SESSION_ID`, so isolate it: launch its lanes with
+`harnex run --owner-tag TAG` and watch `harnex watch --owner --owner-tag TAG`
+(a separate owner, `<parent>/<TAG>`, with no other lanes and no backlog), or
+keep the shared owner with its own `--cursor NAME` and `--match 'pi-TAG-*'`.
+See `harnex agents-guide claude`.
+
+A status line or panel can poll `harnex status --all --json`. Each row has
+`id`, `cli`, `description`, `repo_root`, `started_at`, `state`, `work_state`,
+`done`, `task_complete`, `task_failed`, and `degraded`/`live_status`/`source`.
+A live session also has `agent_state`, `log_idle_s`, `auto_stop` and
+`activity` (`turn_active`, `model_idle_s`, `tool_idle_s`, ...). These fields
+are stable for consumers; new fields are additive.
+
 ## Duplicate-Dispatch Guard
 
 `harnex run --attempt-kind retry|fallback` requires
@@ -88,13 +286,13 @@ 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. 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
+sit at a live prompt while its work is reviewed. For structured Pi RPC
+sessions, `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`. With
+`--require-artifact-report`, an acknowledgment-only turn is typed
+`completed_no_activity` and fails this fence without transcript parsing. Harnex
 writes the observed-state receipt before publishing `task_complete`; optional
 worker claims never make an inactive turn pass. Harnex still does not judge
 semantic quality, so verify the expected artifact or tests afterward.
@@ -167,9 +365,9 @@ harnex events --id pi-i-NN
 For task completion:
 
 ```bash
-harnex watch --id pi-i-NN --until done --max-wait 15m
+harnex watch --id pi-i-NN --until done --max-wait 15m --heartbeat 60s
 # Primitive equivalent when a script wants raw wait semantics:
-harnex wait --id pi-i-NN --until done --timeout 900
+harnex wait --id pi-i-NN --until done --timeout 900 --heartbeat 60s
 # Or, when you specifically need the structured successful-turn event:
 harnex wait --id pi-i-NN --until task_complete --timeout 900
 ```
@@ -229,7 +427,7 @@ interpretation.
 - Polling `state=prompt` alone and calling it done.
 - Wrapping `harnex wait` in loops that swallow non-zero `task_failed` results.
 - 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.
+- Using one long watcher call without the runner-owned marker or owner-addressed delivery 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.

data/guides/05_naming.md

@@ -16,7 +16,6 @@ Common prefixes:
 | Prefix | Meaning |
 | --- | --- |
 | `pi` | Pi worker (default) |
-| `cx` | Codex worker |
 | `cl` | Claude worker |
 | `buddy` | Buddy monitor |
 

data/guides/06_claude.md

@@ -0,0 +1,96 @@
+# Claude Code: GPT Workers as Tools
+
+Harnex lets a Claude Code session or subagent hand work to Pi workers (GPT or
+other provider models) and get the result back the way it calls any tool. Each
+worker runs in a visible tmux window. Every command prints plain text: the
+worker's reply, then a `── NAME: …` footer with the lane's state, model, cost,
+commits and the next commands.
+
+## Pick The Command
+
+| Need | Command |
+| --- | --- |
+| A second opinion, an explanation, a read-only review | `harnex ask "QUESTION"` |
+| One task done by a worker | `harnex delegate --worktree NAME "TASK"`, then `harnex land NAME` |
+| Several tasks in parallel | `harnex delegate --no-wait --worktree NAME "TASK"` per task, then `harnex result` |
+| A follow-up to the same worker | `harnex reply NAME "MESSAGE"` |
+| Drop a lane | `harnex discard NAME` |
+| What is open | `harnex lanes` |
+
+Exit codes: 0 done, 1 failed, 2 usage error, 124 still working (the worker
+keeps going; `harnex result NAME` keeps waiting).
+
+### Ask
+
+```bash
+harnex ask "Which module writes dispatch rows, and is the lane case tested?"
+harnex ask --model openai/gpt-5.1 --file /tmp/review.md
+```
+
+The worker reads the repository with read-only tools, answers, and stops.
+stdout is the answer; stderr gets one line with the lane, its time and the
+model. `--write` lets it edit and run commands; `--fallback-model M` asks once
+more with another model after a provider-capacity failure.
+
+### Delegate, Review, Land
+
+```bash
+harnex delegate --worktree word-count "Add TextKit.word_count(text) with a test; run bin/test"
+git diff HEAD...harnex/word-count && bin/test   # your own check
+harnex land word-count
+```
+
+`--worktree NAME` creates `.harnex/worktrees/NAME` on branch `harnex/NAME` from
+`HEAD`. The worker is told to commit there. `harnex land NAME` merges the
+branch into the main checkout's current branch, then removes the worktree and
+branch; leftover uncommitted changes are committed first. On a merge conflict
+the merge stays in progress: resolve, `git commit`, and run `harnex land NAME`
+again to clean up. `harnex land` with no name lands every finished worktree
+lane you started in this repo. `harnex discard NAME` drops the lane's work. Without
+`--worktree`, the worker edits the current directory in place.
+
+### Parallel Lanes
+
+```bash
+harnex delegate --no-wait --worktree slugify "Fix TextKit.slugify ..."
+harnex delegate --no-wait --worktree truncate "Add TextKit.truncate ..."
+harnex result            # waits for all your lanes, printing each as it lands
+harnex land slugify && harnex land truncate
+```
+
+`harnex result` with no names covers every lane you started in this repo
+whose result you have not collected; `harnex result NAME...` names them.
+
+### Follow-Ups
+
+```bash
+harnex reply word-count "Also add TextKit.char_count(text) with a test."
+```
+
+A worker still on its turn takes the message as a follow-up. A finished lane
+is relaunched on its own Pi session, so the worker keeps everything it knew.
+After a provider-capacity failure, reply "Continue the same task from where
+you stopped", optionally with `--model OTHER`.
+
+## Rules For Claude Code
+
+- **Long tasks.** Commands wait 9 minutes by default (`--timeout`), under the
+  10-minute Bash cap. Give the Bash call `timeout: 600000`; the default 2
+  minutes kills the wait. On 124 run `harnex result NAME` until it lands. In
+  the main session you can also run the command with `run_in_background` and
+  be notified.
+- **Subagents** block in the foreground the same way; nothing needs a
+  background notification. A subagent shares its parent's
+  `CLAUDE_CODE_SESSION_ID`, so `harnex result` with no names also sees the
+  parent's lanes; name the lanes you wait for.
+- **Briefs are self-contained.** The worker has not seen the conversation.
+- **Verify before you report success.** `done` means the worker's turn ended
+  without error, not that the work is right. Check the diff and the tests.
+- **Clean up.** Land or discard every worktree lane; `harnex lanes` lists what
+  is still open.
+
+## Low-Level Commands
+
+`harnex run`, `send`, `wait`, `watch --owner` and `stop` remain for queues and
+custom orchestration (see `harnex agents-guide dispatch` and `monitoring`).
+Lanes are ordinary harnex sessions named after the lane.

data/lib/harnex/adapters/base.rb

@@ -24,25 +24,21 @@ module Harnex
         @extra_args = extra_args.dup
       end
 
-      # 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.
+      # Default transport. The structured Pi adapter overrides it to
+      # :stdio_jsonl_rpc; Session#run uses this to pick the I/O path.
       def transport
         :pty
       end
 
       # Vendor of the underlying agent — populates DISPATCH meta.agent_provider.
-      # Subclasses override (claude → "anthropic", codex → "openai").
+      # Subclasses override (claude → "anthropic").
       def provider
         nil
       end
 
       # Whether the usage this adapter captures reports input_tokens
       # INCLUSIVE of cached_tokens. Depends on the capture path, not just
-      # the provider: codex app-server JSON reports cached as a subset of
-      # input, while the codex TUI line the PTY adapter scrapes shows
-      # non-cached input with cached as a separate additive count. Feeds
-      # Pricing.compute (plan 33 Phase 2).
+      # the provider. Feeds Pricing.compute (plan 33 Phase 2).
       def usage_input_includes_cached?
         false
       end