harnex 0.12.0 → 0.29.0

data/docs/agents.md

@@ -0,0 +1,119 @@
+# Coding agents
+
+harnex is built to be driven by coding agents: Claude Code, Pi, or anything
+that can run a shell command or call an MCP tool. A supervising agent hands a
+question or a task to a Pi worker (a GPT model by default), keeps working, and
+gets the worker's reply back as plain text it can act on.
+
+There are three ways in, from smoothest to most portable:
+
+1. **MCP tools** (`harnex mcp install`): `ask`, `delegate`, `result`,
+   `reply`, `land`, `discard` and `lanes` as native tools. See
+   [MCP server](mcp.md).
+2. **The `gpt` subagent** for Claude Code: a background subagent that relays
+   one brief to a worker and returns the reply verbatim.
+3. **The CLI** from any agent's shell tool: the same verbs as
+   [lanes](lanes.md).
+
+## Claude Code
+
+### MCP tools (main conversation)
+
+With the server registered, Claude calls the tools directly. A call that runs
+longer than two minutes moves to the background on its own; Claude keeps
+working and is notified when the result lands, so a `delegate` behaves like a
+background subagent without one:
+
+```text
+❯ Use the harnex delegate tool to have a GPT worker run the slow benchmark and tell me the score.
+● Calling harnex…
+  ⎿  pi-slow-bench: working 59s · 3 tool calls · now bash 44s
+● The GPT worker is still running the benchmark. I'll report the score when it finishes.
+● MCP task (harnex/delegate) completed.
+● The score is 302926.
+```
+
+### The `gpt` subagent
+
+`harnex mcp install` also installs a `gpt` agent definition at
+`~/.claude/agents/gpt.md` when none exists. It is a thin Haiku relay with only
+the harnex tools: it never does the task itself and returns the worker's reply
+exactly, footer included. Use it for parallel work (several `Agent` calls in
+one message) and for follow-ups (`SendMessage` to the same agent reaches the
+same worker, with its context).
+
+```text
+Agent(subagent_type: "gpt", prompt: """
+worktree: word-count
+
+Add TextKit.word_count(text) to lib/textkit.rb with a test; run bin/test.
+""")
+```
+
+Optional header lines, then a blank line, then the brief:
+
+| Header | Effect |
+| --- | --- |
+| `worktree: NAME` | Edit in a new worktree on `harnex/NAME`; land it afterwards |
+| `mode: write` | Run commands or edit the current checkout in place |
+| `mode: read` | Read-only, even if the brief mentions commands |
+| `model: provider/model`, `effort: low\|medium\|high` | Pick the worker's model |
+| `fallback: provider/model` | Retry a read-only ask on another model |
+| `cwd: DIR` | Work in another directory |
+
+Without a header, questions and reviews go to a read-only worker, and a brief
+that asks to run something or change files goes to a worker that can.
+The definition ships with harnex as [`agents/gpt.md`](../agents/gpt.md).
+
+### The CLI from Claude's Bash tool
+
+```bash
+harnex delegate --worktree word-count "Add TextKit.word_count(text) with a test; run bin/test."
+```
+
+Give the Bash call `timeout: 600000`: commands wait up to 9 minutes, and
+Claude Code's default Bash timeout is two minutes. On exit 124 run
+`harnex result NAME`. In the main conversation, `run_in_background` works too.
+
+### Things worth knowing
+
+- Claude Code loads agent definitions and MCP servers when a session starts;
+  restart after `harnex mcp install`.
+- Background results reach the parent XML-escaped (`&`, `<`). The relay's
+  own text is exact.
+- Headless `claude -p` stops background work ten idle minutes after the main
+  turn; set `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` for long unattended runs.
+
+## Pi
+
+`harnex mcp install` adds the server to `~/.pi/agent/mcp.json` with
+`exposure: direct`, so a Pi supervisor sees the tools like built-ins. Without
+MCP, Pi uses the CLI through its `bash` tool; `harnex agents-guide claude` is
+the short guide it needs (it applies to any supervising agent). Workers
+started by harnex never see harnex's own MCP tools, so a worker cannot start
+more workers.
+
+## Habits that keep it smooth
+
+- **Self-contained briefs.** The worker has not seen your conversation: name
+  the files, the expected behavior and the check (`bin/test`).
+- **A worktree for anything that edits.** `--worktree NAME` keeps parallel
+  lanes apart and your checkout clean until you land.
+- **Verify, then land.** `done` means the worker's turn ended without error,
+  not that the work is right. Read the diff and run the tests yourself.
+- **Land, don't merge by hand.** `land` also removes the worktree and branch.
+- **Check on a worker with `lanes`.** It shows the tool each worker is running
+  now.
+
+## Measuring it
+
+`evals/agents/run` drives real supervisors (Claude Code headless and Pi print
+mode, each with and without MCP) through seven scenarios against a fixture
+repository and scores correctness, tool calls, harnex usage errors, doc
+lookups and leftovers. harnex 0.29 passes all 28 runs with no harnex usage
+errors, no doc lookups and nothing left behind.
+
+```bash
+evals/agents/run --list
+evals/agents/run --supervisor claude,pi S2 S3
+```

data/docs/dispatch-telemetry.md

@@ -11,6 +11,26 @@ git repo it is `~/.local/state/harnex/dispatch.jsonl`. `harnex history`,
 `status --id`, and `wait` consume the same rows. Legacy v1 thin rows and
 pre-v2 envelope-less summaries may coexist and remain readable/skippable.
 
+## Portable home paths
+
+From 0.14.1, new canonical records and reconciliation repair appends serialize
+string values equal to the current user's home as `~`, and paths beneath it as
+`~/...`. The home-directory match uses a complete path-component boundary;
+sibling directories, other users' tilde forms and paths outside that home are
+not rewritten. A path mentioned later inside a prose string is not scrubbed.
+This is path serialization, not a general identity or secret redactor.
+
+The writer serializes a copy. Runtime/session structures, the events stream,
+registry and receipt files retain their normal paths. Existing ledger rows are
+not rewritten automatically. Status API results still expose absolute repository
+roots, and path-consuming retention/report operations resolve portable paths
+against the reader's home.
+
+Reconciliation compares absolute paths under the current home and their portable
+forms consistently. Genuinely different paths, identities, values and outcomes
+still conflict. Home-relative paths are interpreted in the current user's home
+context; this does not infer another machine's home directory or migrate archives.
+
 ## Clean-Tree Checks And The Tracked Stream
 
 Some repos deliberately track `.harnex/dispatch.jsonl` as project telemetry.
@@ -24,7 +44,7 @@ alongside the work it describes.
 ## CLI flags
 
 ```text
-harnex run codex --meta '{"model":"gpt-5.3-codex","effort":"high","predicted":{"input_tokens":[200000,800000]}}'
+harnex run pi --meta '{"model":"openai/gpt-5.1","effort":"high","predicted":{"input_tokens":[200000,800000]}}'
 harnex run pi --context 'Implement the task; Harnex writes the final receipt'
 harnex run pi --artifact-report .harnex/receipts/pi-r-64.json --context 'Optionally write review claims to $HARNEX_ARTIFACT_CLAIMS_PATH'
 harnex run pi --project-id harnex --queue-id queue-005 --entry-id SP-4 --phase implement --intent queue-work --require-attribution
@@ -76,6 +96,31 @@ harnex orchestration report --dispatch .harnex/dispatch.jsonl --run-id queue-005
 
 Use `harnex history --json | jq .` for pipelines over the repo-local log.
 
+## Optional external archive bridge
+
+Repositories may keep the active stream bounded while preserving one logical
+history through two opt-in local executable hooks:
+
+- `HARNEX_DISPATCH_ARCHIVER=/absolute/path/to/helper` runs immediately before
+  each append as `helper --canonical PATH --incoming-bytes N`. Harnex holds a
+  stable sidecar lock under `$HARNEX_STATE_DIR/locks/` before invoking the
+  helper and opens the active stream only afterward, so an atomic replacement
+  cannot strand a waiting writer on the old inode. A helper failure emits a
+  bounded warning and the new row is still appended to the active stream.
+- `HARNEX_DISPATCH_HISTORY_READER=/absolute/path/to/helper` runs as
+  `helper --canonical PATH`. It must write the complete archive-plus-active
+  JSONL stream to stdout and exit successfully. Harnex captures that stream in
+  a private temporary file before exposing any rows; failure or malformed
+  output is reported as unavailable history rather than an empty result.
+
+Both values must name an absolute, executable, non-symlink local file. Harnex
+passes no telemetry bytes or credentials in arguments, does no network work of
+its own, suppresses helper output on the write path, and retains its ordinary
+active-file behavior when the hooks are unset. The repository-specific helper
+owns encryption, storage credentials, archive verification, and retrieval.
+`harnex history`, canonical assertion/reconciliation, latest-row lookup, and
+attempt-chain accounting consume the complete reader when configured.
+
 ## Canonical assertion and reconciliation
 
 `harnex telemetry assert-canonical` is the read-only drift gate for the
@@ -130,15 +175,19 @@ Harnex-owned `meta` fields are always populated when derivable: `id`,
 These top-level `--meta` keys pass through into `meta` when provided:
 `orchestrator`, `orchestrator_session`, `chain_id`, `parent_dispatch_id`,
 `parent_attempt_id`, `attempt_kind`, `tier`, `phase`, `issue`, `plan`, and
-`task_brief`. Queue-specific keys such as
+`task_brief`. `harnex run --context-file` fills `context_file` (absolute
+path), `context_sha256` (SHA-256 of the text actually sent) and, on
+`started.meta` only, `context_section`; it also defaults `task_brief` to the
+file path. Queue-specific keys such as
 `project_id`, `queue_id`, `entry_id`, `entry_title`, and `intent` are used for
 the top-level `queue` block but are not duplicated into legacy `meta`. Unknown
 top-level keys are kept on `started.meta` but are not copied into the v2 end
 row.
 
-`predicted` is copied verbatim from `--meta.predicted` when it is a JSON object;
-otherwise it is `{}`. Harnex does no profile lookup or recommendation-table
-resolution.
+`predicted` is copied from `--meta.predicted` when it is a JSON object;
+otherwise it is `{}`. The canonical record applies the portable-path serialization
+above; runtime values are unchanged. Harnex does no profile lookup or
+recommendation-table resolution.
 
 ## Queue, agent, and reliability blocks
 
@@ -168,17 +217,20 @@ routing details; legacy `meta.agent*` and `actual.model` stay for compatibility:
 ```json
 {
   "agent": {
-    "cli": "codex",
+    "cli": "pi",
     "provider": "openai",
-    "model_requested": "gpt-5.3-codex",
-    "model_effective": "gpt-5.3-codex",
+    "model_requested": "openai/gpt-5.1",
+    "model_effective": "gpt-5.1",
     "reasoning_effort": "high",
-    "service_tier": "flex",
-    "adapter_transport": "stdio_jsonrpc"
+    "service_tier": null,
+    "adapter_transport": "stdio_jsonl_rpc"
   }
 }
 ```
 
+`service_tier` is copied from `--meta` and is otherwise null; older rows may
+carry an adapter-set value.
+
 The top-level `reliability` block is always emitted and should be preferred over
 legacy `actual.disconnections` for reliability analytics:
 
@@ -270,18 +322,12 @@ last valid terminal and peak values intact while setting
 `latest_sample_status: "missing"`. Null never means zero.
 
 `context.status` is `observed` for Pi's dedicated
-`get_session_stats.contextUsage` signal, `estimated` for Codex app-server,
-`missing` when a supported source yielded no valid occupancy, or `unsupported`
-when the adapter has no active-context source. `source` is
-`pi_get_session_stats` or `codex_thread_token_usage_last` for those structured
-adapters and is null for unsupported adapters. Pi's percentage is adapter
-reported. Codex's `tokenUsage.last.totalTokens` is the latest model-reported
-active context size, but it excludes local items appended after that response;
-Harnex therefore labels it estimated and derives
-`terminal_percent = last.totalTokens / modelContextWindow * 100`. That is
-full-window pressure, not Codex TUI's baseline-adjusted “context left” display.
-No prompt, transcript, message, tool payload, or compaction summary is copied
-into this block.
+`get_session_stats.contextUsage` signal, `missing` when a supported source
+yielded no valid occupancy, or `unsupported` when the adapter has no
+active-context source (`estimated` appears only in older rows). `source` is
+`pi_get_session_stats` for Pi and null for unsupported adapters. Pi's
+percentage is adapter reported. No prompt, transcript, message, tool payload,
+or compaction summary is copied into this block.
 
 `attribution.status` is `complete` when `project_id`, `phase`, `intent`, and a
 work id are present; `partial` when any attribution is known but that contract
@@ -294,6 +340,45 @@ is normally `accepted` or `rejected`. `source=harnex_observed_state` identifies
 new receipts. The block also contains final commit/path/LOC observations; those
 facts prove the delta, not semantic quality or human authorship.
 
+`outcome.class` is one value from a closed vocabulary (#57):
+
+- **Completion:** `completed_with_proof`, `completed_with_activity`.
+- **Proof defects:** `completed_no_activity`, `report_missing`,
+  `report_invalid`, `report_rejected`.
+- **Process:** `task_failed` (the turn failed), `provider_capacity` (the turn
+  failed after the adapter's own provider retries ran out, from Pi's
+  structured `auto_retry_end success:false`; capacity or rate limits rather
+  than the work), `boot_failure` (structured
+  transport died before its first turn), `permission_prompt` (ended on a
+  trust/confirmation prompt the adapter recognizes), `timeout` (`--max-runtime`
+  stopped running work, or exit 124), `stopped_by_caller` (a manual stop
+  while work was running), `process_failed` (nonzero exit with no turn
+  verdict).
+- **Fallback:** `unknown`.
+
+Completion and proof classes are never overridden. Process classes refine an
+`unknown` or `task_failed` terminal, or a `report_rejected` receipt for a
+process that never signalled completion (finalization always writes a receipt,
+so that rejection records the failed process, not a proof verdict). Signals:
+the exit path, stop provenance, and final input state; never transcript text.
+A stop or deadline outranks `task_failed` only when the work was still running
+when it was stopped. A clean exit 0 without completion keeps its accepted
+receipt (`completed_with_proof`), as before. Older rows are not reclassified.
+
+`harnex orchestration report --run-id ID` (or `--queue-id ID`) counts
+`workers.outcome_classes` per raw attempt and per retry family. A family joins
+attempts by `parent_attempt_id`, by `parent_dispatch_id` for non-initial
+attempts (retry/fix/fallback/superseding/review), or by a reused dispatch id,
+so correlated retries count as one root cause. Spawner-derived parents of
+initial workers do not join families. Start rows are not counted. An optional
+`--failure-budget N [--budget-unit attempts|families] [--fatal-classes A,B]`
+adds a `failure_budget` verdict and exits 3 once N fatal failures are counted
+(1 is an error, 2 a usage error; a missing `--dispatch` file is an error).
+By default the fatal classes are `completed_no_activity`, `task_failed`,
+`provider_capacity`, `boot_failure`, `permission_prompt`, `timeout`, and `process_failed`; proof
+defects, caller stops and `unknown` are not fatal.
+Harnex supplies the ledger only: the caller decides what to do on a breach.
+
 Every end row has one Harnex-session `attempt`. Its random `id` is distinct
 from operator-visible `run_id`; `parent_attempt_id` and `parent_dispatch_id`
 link retries/fixes/reviews/fallbacks while each row keeps separate raw usage.
@@ -368,7 +453,7 @@ A generated receipt contains:
     "version": 1,
     "author": "harnex",
     "generated_at": "2026-08-03T05:00:00Z",
-    "id": "cx-r-64",
+    "id": "pi-r-64",
     "session_id": "8d8f3f07c8fc343d"
   },
   "outcome": {
@@ -415,23 +500,64 @@ A generated receipt contains:
 (`start_sha != end_sha`, commit count/path/LOC evidence) from an observed
 `no_change` result. `start_dirty`, `end_dirty`, and `worktree_changed` expose
 worktree caveats while unchanged pre-session dirt is excluded from the delta.
-Codex app-server `commandExecution` items contribute
-bounded command text, integer exit code, status, and optional duration. Other
-transports currently report `command_observation: "unsupported"` rather than
-guessing from prose or generic tool events. If the 256-KiB receipt cap requires
+Pi RPC built-in `bash` tool calls contribute bounded command text, integer
+exit code, status, and optional duration. Pi commands require an integer `result.structuredContent.exit_code`
+correlated by `toolCallId`; Pi bash calls without one (abort, timeout,
+extension override, older Pi, still running at teardown) are counted in
+`observed.commands_unobserved` and mark `command_observation` as `partial`
+when some exits were observed, or `unsupported` when none were. PTY transports
+report `command_observation: "unsupported"` rather than guessing from prose or
+generic tool events. If the 256-KiB receipt cap requires
 trimming, `commands_truncated` / `changed_paths_truncated` make that explicit;
 full aggregate counts remain in the dispatch row. Usage carries the same
 measured/missing/unsupported semantics as the dispatch
 row and is refreshed at teardown when final adapter usage becomes available.
 
 `validation.commands` mirrors all bounded observed command exits for legacy
-readers. Its aggregate status is `not_run`, `pass`, or `fail`; a failed
+readers. Its aggregate status is `not_run`, `pass`, or `fail`, or `unknown`
+when no observed exit failed but `commands_unobserved` is positive; a failed
 exploratory command may precede a successful turn. For harness receipts,
 `validate --final` therefore validates receipt authorship/shape, accepted turn,
 and accepted/no-change outcome instead of letting an intermediate command exit
 rewrite the harness verdict. Queue policy may impose a stricter command gate by
 inspecting `observed.commands`.
 
+Final gates (#68) separate acceptance from command history. Declare them with
+repeatable `harnex run --final-gate '<cmd>'` (or meta `"final_gates": [...]`,
+which `--final-gate` appends to). The receipt then carries:
+
+```json
+"validation": {
+  "status": "pass",
+  "commands_had_failures": true,
+  "final_gates": {
+    "declared": 1, "observed_pass": 1, "observed_fail": 0, "missing": 0,
+    "status": "pass",
+    "gates": [{ "cmd": "rake test", "exit_code": 0 }]
+  }
+}
+```
+
+- A gate matches an observed command by exact string. A structured adapter's
+  single-shell transport wrapper (`bash -lc '<cmd>'`, `sh -c '<cmd>'`) is
+  unwrapped first; the inner script must still equal the gate exactly.
+- Each gate is decided by its **last** observed run, so an intermediate
+  failure followed by a green final run passes.
+- A gate that never ran is `fail` when command observation was complete, and
+  `unknown` when it was `partial` or `unsupported` (PTY transports), since it
+  may be among the unobserved calls.
+- With gates declared, `validation.status` is the gate status. Without them,
+  `final_gates.status` is `undeclared` and `validation.status` keeps the
+  any-failure semantics above.
+- `commands_had_failures` covers the session's whole command history, not only
+  the retained 50-command window.
+- Dispatch rows keep `commands_had_failures` and the final-gate counts and
+  status, without the gate command text.
+
+This is receipt ergonomics, not proof: `validate --final` and outcome classes
+do not change, and supervisors should still replay declared final commands
+verbatim before accepting work.
+
 Reviewers can write one optional input file at
 `HARNEX_ARTIFACT_CLAIMS_PATH`:
 
@@ -467,30 +593,28 @@ not a required worker step for new dispatches.
 
 ## Autonomous completion gate
 
-For Codex app-server runs launched with `--context`, provider turn completion
-is not by itself accepted work completion. Harnex emits `task_complete` only
-when it has at least one structured command/tool/file-change item or a Git
-delta. If both are absent, it emits `task_failed` with
+A Pi turn counts as accepted work completion once it settles
+(`agent_settled`) without a final `error`, `aborted`, or `length` stop reason.
+With `--require-artifact-report`, Harnex also requires at least one structured
+command/tool call or a Git delta (PTY adapters can satisfy it only with a Git
+delta). If both are absent, it emits `task_failed` with
 `outcome_class=completed_no_activity`, writes a rejected observed receipt, and
-normalizes auto-stop to non-zero. This applies equally to
-`service_tier=flex` and `service_tier=fast` and deliberately ignores final
-answer text and claims. Intentional no-op work must still perform observable
+normalizes auto-stop to non-zero. The gate deliberately ignores final answer
+text and claims. Intentional no-op work must still perform observable
 inspection/validation; a model assertion of `no_change` cannot self-approve.
 
 PTY transports do not expose equivalent completion-item metadata, so their
-existing prompt-return auto-stop behavior remains. Non-Codex transports label
+existing prompt-return auto-stop behavior remains. PTY transports label
 command observation `unsupported`; Git and terminal state are still recorded
 without guessing.
 
 ## Actuals
 
-At process exit, harnex collects usage through the active adapter. JSON-RPC
-Codex sessions read cumulative `thread/tokenUsage/updated` data, Pi RPC sessions
-read `get_session_stats`, and PTY adapters parse the last 16 KB of transcript
-when they support a parser. Adapters without a parser emit nullable usage
-fields. Separately, Pi aggregates bounded `contextUsage` samples and Codex
-aggregates `tokenUsage.last` plus `modelContextWindow`; neither source is
-substituted with cumulative usage when active occupancy is unavailable.
+At process exit, harnex collects usage through the active adapter. Pi RPC
+sessions read `get_session_stats`, and PTY adapters parse the last 16 KB of
+transcript when they support a parser. Adapters without a parser emit nullable
+usage fields. Separately, Pi aggregates bounded `contextUsage` samples; they are
+never substituted with cumulative usage when active occupancy is unavailable.
 
 Git actuals capture the start/end SHA plus committed, staged, unstaged, and
 untracked changes relative to the worktree state observed at session start.
@@ -498,15 +622,25 @@ Unchanged pre-existing dirt is not credited to the worker, and harness-owned
 dispatch/receipt paths are excluded. Git failures leave the corresponding
 consolidated fields `null` and omit `git` events.
 
+Git is observed in the repository the agent works in. A lane launched with
+`--cwd <worktree> --root <checkout>`, where the two resolve to different Git
+toplevels, is observed in its `--cwd` worktree: `commit_sha`, `branch`,
+`start_sha`/`end_sha`, `observed.git`, activity and acceptance all describe
+the lane, so supervisor commits on the root never count as the lane's work.
+`--root` still decides where the rows are written. The `git` start event then
+carries `git_root`, and the end row's `root_commit_sha` records the `--root`
+repository's head (it is `null` for every other dispatch).
+
 The `actual` block includes model/effort hints from `--meta`, duration, token
 counts, `agent_session_id`, compatibility `cost_usd`, adapter transport, git
 deltas, exit reason, task completion state, signal/exit code, last error,
 operational counters (`stalls`, `force_resumes`, `disconnections`,
-`compactions`, `turn_count`, `tool_calls`, `commands_executed`), rate-limit
-payloads, output/event volume measurements, and output/events log paths. New
-additive attempt counters are `attempts_total`, `attempts_succeeded`,
-`attempts_failed`, `retry_count`, `throttle_429_count`, `disconnect_count`, and
-`fallback_triggered`. Throughput values are populated only for a
+`compactions`, `turn_count`, `tool_calls`, `commands_executed`), `rate_limits`
+(always null now; only older rows carry payloads), output/event volume
+measurements, and output/events log paths. New additive attempt counters are
+`attempts_total`, `attempts_succeeded`, `attempts_failed`, `retry_count`,
+`throttle_429_count` (no current producer, so 0 in new rows), `disconnect_count`,
+and `fallback_triggered`. Throughput values are populated only for a
 harness-accepted outcome: `throughput_tokens_per_s` and
 `throughput_successes_per_h`; `retry_tax_pct` is `0.0` when no retry occurred
 and `null` until a retry source can measure attributable wasted tokens.
@@ -538,8 +672,8 @@ jq -s 'map(select(.actual.attempts_total > 0))
 - `failure`: wrapped process exited non-zero, the observed-activity gate emitted
   `task_failed`, or Harnex could not write/validate the receipt.
 - `timeout`: wrapped process exited with code `124`.
-- `boot_failure`: JSON-RPC app-server exited within the startup window before a
-  turn was observed.
+- `boot_failure`: the structured Pi RPC transport exited within the startup
+  window (5 s) before a turn was observed.
 - `disconnected`: wrapped process exited `0` but no session summary was parsed.
 
 Canonical dispatch-stream writes remain best-effort. Receipt

data/docs/events.md

@@ -39,7 +39,8 @@ Every row includes this envelope:
 
 - `schema_version` (Integer): always `1`
 - `seq` (Integer): monotonic per session, starts at `1`
-- `ts` (String): UTC ISO-8601 timestamp
+- `ts` (String): UTC ISO-8601 timestamp with millisecond precision
+  (`2026-05-01T11:30:00.123Z`; rows before 0.16.0 have whole seconds)
 - `id` (String): session ID
 - `type` (String): event type
 
@@ -54,6 +55,18 @@ Emitted now (Layer 4):
 - `exited`: adds
   - `code` (Integer): synthesized numeric exit code
   - `signal` (Integer, optional): present for signaled exits
+- `task_complete` / `task_failed` (structured adapters): add `turn` (Integer),
+  the session's work turn. Turn 1 is the first prompt; a message injected
+  after a published result starts the next turn, announced by a `work_turn`
+  row (`turn`). `harnex send` reports `after_seq`, the newest `seq` before
+  its message, so `harnex wait --until done --after-seq N` waits for the turn
+  that message started or joined. They also carry, when known:
+  `final_message` (the worker's last reply this turn, at most 4,000
+  characters), `final_message_path` (the full text),
+  `final_message_truncated`, `follow_ups` (`{sent, pending}`), and the lane's
+  `end_sha` / `commits` at the turn's end.
+- `queue_update` (Pi): `follow_up` and `steering`, the sizes of Pi's pending
+  queues (counts only, never message text).
 
 ## 5. Stability promise
 
@@ -119,12 +132,12 @@ New event types:
 Example telemetry sequence:
 
 ```json
-{"schema_version":1,"seq":1,"ts":"2026-05-01T11:30:00Z","id":"cx-i-372","type":"started","pid":12345,"meta":{"issue":"23","plan":"27","predicted":{"input_tokens":[200000,800000]}}}
-{"schema_version":1,"seq":2,"ts":"2026-05-01T11:30:00Z","id":"cx-i-372","type":"git","phase":"start","sha":"a8114695c1f0","branch":"main"}
-{"schema_version":1,"seq":3,"ts":"2026-05-01T11:42:13Z","id":"cx-i-372","type":"usage","input_tokens":104158,"output_tokens":2709,"reasoning_tokens":870,"cached_tokens":250880,"total_tokens":106867,"agent_session_id":"019ddf05-0f03-7d70-904f-23db7f00640f"}
-{"schema_version":1,"seq":4,"ts":"2026-05-01T11:42:13Z","id":"cx-i-372","type":"git","phase":"end","sha":"abc1234567","loc_added":312,"loc_removed":65,"files_changed":7,"commits":1}
-{"schema_version":1,"seq":5,"ts":"2026-05-01T11:42:13Z","id":"cx-i-372","type":"summary","path":"/home/u/proj/.harnex/dispatch.jsonl","exit":"success"}
-{"schema_version":1,"seq":6,"ts":"2026-05-01T11:42:13Z","id":"cx-i-372","type":"exited","code":0,"reason":"success"}
+{"schema_version":1,"seq":1,"ts":"2026-05-01T11:30:00Z","id":"pi-i-372","type":"started","pid":12345,"meta":{"issue":"23","plan":"27","predicted":{"input_tokens":[200000,800000]}}}
+{"schema_version":1,"seq":2,"ts":"2026-05-01T11:30:00Z","id":"pi-i-372","type":"git","phase":"start","sha":"a8114695c1f0","branch":"main"}
+{"schema_version":1,"seq":3,"ts":"2026-05-01T11:42:13Z","id":"pi-i-372","type":"usage","input_tokens":104158,"output_tokens":2709,"reasoning_tokens":870,"cached_tokens":250880,"total_tokens":106867,"agent_session_id":"019ddf05-0f03-7d70-904f-23db7f00640f"}
+{"schema_version":1,"seq":4,"ts":"2026-05-01T11:42:13Z","id":"pi-i-372","type":"git","phase":"end","sha":"abc1234567","loc_added":312,"loc_removed":65,"files_changed":7,"commits":1}
+{"schema_version":1,"seq":5,"ts":"2026-05-01T11:42:13Z","id":"pi-i-372","type":"summary","path":"/home/u/proj/.harnex/dispatch.jsonl","exit":"success"}
+{"schema_version":1,"seq":6,"ts":"2026-05-01T11:42:13Z","id":"pi-i-372","type":"exited","code":0,"reason":"success"}
 ```
 
 Events files are runtime logs, not the durable dispatch summary. Their age and