harnex 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9142cc69cec0a0cf0dc3961ccc27dc3728baea445c7d83b4c2d69a34b7e6a499
-  data.tar.gz: b89c616cb2484d48e74ef88985a438f7ebb1c22b1af17dd44cbaab3ee0c020cd
+  metadata.gz: d0a3ac349311bc2677614dabb091443bb21ec82bf63852d237fb38fd47ecaeda
+  data.tar.gz: f1b909c7ed43636ea57a297e25f2adc1d56283faa5f8af882ed22b63b4c55f2f
 SHA512:
-  metadata.gz: 220566d1c646ca49b7f41f8ed053b2909dda8468ab3dc877bfcfe5f47b52988492d54b9d2fcc42ff0e42154921fde97af0824688b27df69e94bd9fc49b77c2f8
-  data.tar.gz: e52eca128c1f078171ab991acd25bafa810e8341a7f6c8f199535cd03b7a881ee03f2c4193afb01ece92cc00d0a8025a6bdb564739aeb13cbe6a02a4f4d87d0a
+  metadata.gz: fe2b745dd618e1967fa5bbe1f7f55f4c0c2beb104cd6d213592f8545528118d3b3a80053b5643fce5482d3eaca9c7e6d800b6f5dd6d41873c0c9e5cc73aff332
+  data.tar.gz: 0c13e6cb6fe6bbac64e14ae43b23061a2b5a96cbc7f4699d438b5e5eac48ef70435c017b638635c0ded52886536f94aac37df712b1d67a9c5485dc0dd1cfa4b7

data/CHANGELOG.md

@@ -1,5 +1,193 @@
 # Changelog
 
+## [0.10.0] - 2026-08-03 | 01:44 PM | IST
+
+Minor bump, **breaking**: `--summary-out` is removed outright, so the canonical
+`.harnex/dispatch.jsonl` is the only telemetry destination. Also fixes four
+runner reliability defects found while verifying that removal — concurrent
+registry corruption, a delivered send reported as failed, a corrupt registry
+entry crashing every session scan, and a closed stdout wedging the wrapped
+agent.
+
+### Fixed
+
+- **Concurrent registry writes no longer corrupt each other** (#66).
+  `write_registry` derived its temp path from the pid alone, but several
+  threads in one session write the same registry — the startup persist, the
+  inbox delivery thread, and one thread per API client. One thread renamed the
+  file another was still writing, and the loser raised `Errno::ENOENT`
+  (2080 failures in a 2400-write reproduction; now zero). Writes are also no
+  longer defeated by a state directory that was reaped mid-session.
+- **A failed registry write no longer fails an already delivered send** (#66).
+  Registry persistence runs *after* the prompt has reached the agent, so a
+  bookkeeping failure was reporting a dispatched turn as failed — enough to
+  make an orchestrator retry work already in flight. Post-injection refresh now
+  warns; startup persistence stays strict so an undiscoverable session still
+  fails loudly instead of running unreachable.
+- **One corrupt registry file no longer crashes every session scan** (#66).
+  A non-numeric pid raised `ArgumentError` out of `active_sessions`, taking
+  down `harnex status`, `harnex send`, and `harnex pane`. Such an entry is now
+  treated as dead and pruned, matching the existing self-healing for
+  unparseable JSON.
+- **A closed stdout no longer wedges the wrapped agent** (#66).
+  `Errno::EPIPE`/`EBADF` are not `IOError` subclasses, so they escaped the
+  output reader's rescue and killed the thread; the PTY then stopped draining
+  and the agent blocked forever on write, presenting as an agent hang with no
+  harness error. Draining is now unconditional and stdout echo is best-effort.
+  Both reader loops report an unexpected exit instead of vanishing silently.
+- `Retention` metadata writes route through the shared atomic writer instead of
+  repeating the same pid-only temp-name pattern.
+
+### Removed
+
+- **BREAKING: `--summary-out` is gone** (#65). `.harnex/dispatch.jsonl` is now
+  the only destination a dispatch writes telemetry to. Passing `--summary-out
+  PATH` or `--summary-out=PATH` is rejected as an unknown flag and exits
+  non-zero; it is deliberately not a silent ignore, so a stale caller fails
+  immediately rather than believing it still has a second copy. 0.9.0 demoted
+  the flag to an explicit-only mirror but left it in place; that mirror was the
+  source of a three-times-hand-reconciled stranded-telemetry class.
+- `summary_out_path` no longer appears on `dispatch_start` or `dispatch_end`
+  rows, and `summary_out` no longer appears in `harnex status --json`,
+  `harnex wait`, or `harnex watch` payloads. The `summary` event no longer
+  carries `mirror_path`.
+
+### Added
+
+- **Harness-authored observed-state receipts** (#64): every dispatch now writes
+  a canonical `harnex.artifact_report.v1` receipt without worker-authored JSON.
+  Receipts carry explicit `receipt.author=harnex` provenance, start/end Git
+  state (committed plus staged/unstaged/untracked paths and LOC), bounded Codex
+  command exits, turn acceptance, and usage. The receipt is written before a
+  structured `task_complete` event and refreshed with final teardown telemetry.
+- Every session receives a default repo-keyed receipt under
+  `~/.local/state/harnex/receipts/`; `--artifact-report` now overrides that
+  destination. Live status, detached/tmux launch payloads, dispatch-start rows,
+  and dispatch-end metadata expose the receipt and claims paths.
+- Review workers may write a bounded optional block to
+  `HARNEX_ARTIFACT_CLAIMS_PATH` (`summary`, `verdict`, and P1/P2/P3 counts).
+  Claims are sanitized and copied into the receipt but never participate in
+  completion acceptance or final-receipt validity.
+- Receipt files and claims inputs join the existing 45-day / 1-GiB retention
+  policy as a third independently configurable directory, including
+  `HARNEX_RECEIPTS_MAX_AGE_DAYS` / `HARNEX_RECEIPTS_MAX_BYTES` and live/current
+  path protection.
+
+### Changed
+
+- `TerminalStatus` resolves exclusively from the canonical stream. It
+  previously preferred the mirror file named by a record's `summary_out_path`,
+  which — with the writer removed — would have let a leftover mirror from an
+  older release resolve status from stale data. A pre-existing mirror file on
+  disk now has no effect on any id.
+- `status["source"]` reports `dispatch_end` where it previously reported
+  `summary_out` for rich end rows. `dispatch_history`, `dispatch_start`,
+  `live`, `registry`, and `none` are unchanged.
+- `artifact-report validate --final` preserves the legacy manual-v1 contract
+  while recognizing the additive harness-receipt contract. Harness receipts
+  validate observed acceptance and zero-delta evidence; failed exploratory
+  command exits remain factual telemetry for queue policy rather than allowing
+  worker claims to decide receipt validity.
+- Artifact fingerprints are now internal claims-freshness bookkeeping only.
+  Pre-existing, stale, malformed, or missing worker reports are overwritten by
+  fresh harness proof instead of becoming work-acceptance failures. The legacy
+  `init` command and `--require-artifact-report` flag remain compatible, but
+  neither an explicit path nor model-authored proof is required.
+- Codex autonomous completion still rejects acknowledgment-only turns as
+  `completed_no_activity`; optional claims cannot satisfy the observed-activity
+  gate. Receipt write/validation failure is fail-closed as `report_invalid`.
+- Git observation now baselines the starting worktree so uncommitted product
+  edits are included while unchanged pre-existing dirt and harness-owned
+  dispatch/receipt files are excluded.
+
+## [0.9.0] - 2026-08-03 | 01:11 AM | IST
+
+Minor bump: the durable dispatch row family is now v2, `--summary-out` changes
+from a default destination to an explicit mirror, and retention/phase policy add
+operator-visible behavior.
+
+### Added
+
+- **Price-table cost for token-reporting adapters** (#63, plan 33
+  Phase 2; subsumes #58's cost gap): new `lib/harnex/pricing.rb` holds a
+  static per-1M-token USD rate table keyed by provider + model, each entry
+  `as_of`-dated and hand-copied from the provider pricing pages
+  (OpenAI gpt-5.x/codex and Anthropic Claude families, rates as of
+  2026-08-02; update procedure documented in the file header).
+  `build_summary_usage` applies it only when `cost_usd` is null, usage
+  status is `observed`/`zero`, and the effective model matches the table —
+  then `cost_source: "price_table"` and a new always-present
+  `usage.cost_price_as_of` field record provenance. Unknown models stay
+  null; provider-reported cost (Pi) is never overwritten; costs are never
+  backfilled.
+- The codex app-server adapter now captures the effective model from the
+  schema-required `model` field on `thread/start` / `thread/resume`
+  responses, so `agent.model_effective` (and price-table lookup) resolves
+  without the caller passing `--meta '{"model": ...}'`.
+- Token-semantics are capture-path-aware: new adapter hook
+  `usage_input_includes_cached?` distinguishes codex app-server JSON
+  (cached ⊆ input → billable input = input − cached) from the codex PTY
+  transcript line (input excludes cached → cached prices additively).
+  Verified against the captured schema fixtures and a live app-server row.
+- Price-table lookup now covers Holm's effective `gpt-5.5` model and keys its
+  tier-sensitive rates by the recorded service tier (`standard`, `flex`, or
+  `fast`; `priority` aliases fast). Because published `gpt-5.5` rates split at
+  272K active context, Harnex also requires an observed peak below that boundary;
+  missing/long-context evidence remains unpriced rather than applying the wrong
+  short-context rate.
+- Optional repo phase policy in `.harnex/config.json`: an allowlist can `warn`
+  or `reject` non-canonical effective `meta.phase` values before spawn. Explicit
+  malformed policy files fail closed; no config preserves existing behavior.
+- Bounded events/output retention: 45-day and 1-GiB defaults per directory,
+  repo config plus environment overrides, current/live-session protection,
+  oldest-first age/size pruning, one-hour automatic throttle, and bounded
+  last-prune metadata. `harnex doctor` reports size/limits; `--prune --dry-run`
+  previews bounded candidate paths and `--prune` applies the policy.
+
+### Changed
+
+- **Single tracked telemetry stream** (#63, plan 33 Phase 1): a dispatch
+  now writes exactly two rows to the repo-tracked `.harnex/dispatch.jsonl`
+  — the `dispatch_start` row and one unified v2 `dispatch_end` row that
+  merges the thin envelope (top-level `schema_version: 2`, `record_type`,
+  `id`, `status`, `tier`, timing, `tmux_state`, …) with the rich summary
+  sections (`meta`, `predicted`, `actual`, `agent`, `usage`, `context`,
+  `attribution`, `outcome`, `attempt`, `reliability`, `queue?`,
+  `orchestration?`, artifact-report keys). Start rows stamp
+  `schema_version: 2` as well. Readers accept v1 and v2 rows mixed in one
+  file; `harnex history` keeps skipping pre-0.7.3 envelope-less rows.
+- `--summary-out` is now an explicit-only mirror: no default path. When
+  set, the identical v2 end record is appended there in addition to the
+  tracked stream. Consumers that redirected `--summary-out` to keep rich
+  rows should drop the flag — the tracked stream now carries everything.
+  `Harnex.default_summary_out_path` is removed; every writer and reader
+  resolves the stream through `DispatchHistory.path_for` (git-root walk,
+  global fallback), so non-git roots stream to the global file instead of
+  a repo-local `.harnex/` directory.
+- The `summary` event now points `path` at the tracked stream and carries
+  `mirror_path` when a mirror is configured.
+- `TerminalStatus` resolves a v2 end row as both summary and history in
+  one shot (branching on `record_type` first), so `wait --until done` and
+  `status --id` fall back to the unified stream; legacy duck-types remain
+  for pre-v2 files.
+- Cross-dispatch attempt fields are harness-derived from the canonical stream:
+  `attempts_total`/succeeded/failed, `fallback_triggered`, and
+  `reliability.recovered` follow bounded parent links and degrade safely on
+  missing, duplicate, malformed, or cyclic history. `fallback` is now a public,
+  live-parent-guarded attempt kind; in-run `retry_count` remains separate.
+- Public telemetry/configuration references under `docs/*.md` are now packaged
+  in the gem. README, GUIDE, TECHNICAL, agent guides, and event/telemetry docs
+  use the same canonical-stream, mirror, native-watch, pricing, phase-policy,
+  and retention terminology.
+
+### Fixed
+
+- `harnex history` no longer renders blank rows for pre-0.7.3
+  `{meta, predicted, actual}`-schema telemetry rows in
+  `.harnex/dispatch.jsonl`: rows recognized as neither start nor end
+  records are skipped in both table and `--json` output. The raw file is
+  untouched — legacy rows remain available for forensics.
+
 ## [0.8.0] - 2026-08-02 | 08:46 PM | IST
 
 Minor bump: two behavior changes below (`wait --until done` exit codes,

data/GUIDE.md

@@ -8,11 +8,11 @@ Treat harnex as a local supervisor harness, not as a conversation
 bus between agents.
 
 - Start a fresh worker for each step, usually with `--tmux`
-- Send one clear task, often by pointing the worker at a file
-- Use `--wait-for-idle` as a fence, then inspect with `harnex pane`
-- Ask the worker to write its output to a file when the next step
-  needs structured input
-- Stop the worker when that step is done
+- Give one clear startup task with `--context`; add `--auto-stop` for one-shot work
+- Monitor existing visible work with `harnex watch --until done`
+- Use `--wait-for-idle` only as a follow-up-send fence, then verify the artifact
+- Ask the worker to write its output to a file when the next step needs it
+- Stop completed interactive workers promptly
 
 For multi-step flows, chain fresh workers with file handoffs:
 Codex writes a plan, another Codex implements it, Claude reviews it,
@@ -49,14 +49,18 @@ automatically when the agent is ready. You don't have to wait
 or retry. Queueing exists, but the default workflow should still be
 one task per fresh worker.
 
-For unattended dispatch, prefer built-in monitoring over external poll loops:
+For unattended visible dispatch, prefer the native work-level watcher over
+external poll loops:
 
 ```bash
-harnex run codex --id impl --tmux impl --watch --preset impl
+harnex run codex --id impl --tmux impl \
+  --context "Read and execute /tmp/task-impl.md" --auto-stop
+harnex watch --id impl --until done --max-wait 90m
 ```
 
-This adds a foreground watcher that checks idle activity and performs bounded
-force-resume nudges. For full flag behavior and event-stream consumers, see
+`harnex run --watch --preset impl` is a separate foreground launch-and-stall
+babysitter; do not combine it with `--tmux` or `--detach`. For full flag
+behavior and event-stream consumers, see
 [TECHNICAL.md](TECHNICAL.md) and the built-in monitoring section in
 [README.md](README.md).
 
@@ -262,4 +266,7 @@ harnex agents-guide        # deeper agent-facing guidance
 ## What's next
 
 For the full command reference, flags, HTTP API, and internals,
-see [TECHNICAL.md](TECHNICAL.md).
+see [TECHNICAL.md](TECHNICAL.md). The packaged
+[dispatch telemetry](docs/dispatch-telemetry.md) and
+[configuration](docs/configuration.md) references cover the canonical v2 stream,
+phase allowlists, and log retention.

data/README.md

@@ -60,9 +60,10 @@ job, watch it work, stop it when done.
 ### Run from a temporary/public bundle
 
 Use `--cwd DIR` when the worker should see a specific directory rather than
-the orchestrator's current repo. Harnex starts the wrapped agent in `DIR`, sets
-that directory as the session root, and resolves default telemetry such as
-`.harnex/dispatch.jsonl` there:
+the orchestrator's current repo. Harnex starts the wrapped agent in `DIR` and
+uses it for session attribution. Canonical dispatch telemetry is written to the
+enclosing git root's `.harnex/dispatch.jsonl`; a non-git directory uses the
+global `~/.local/state/harnex/dispatch.jsonl` fallback:
 
 ```bash
 harnex run codex --cwd /tmp/leximaze_eval_run_001 \
@@ -205,8 +206,8 @@ bare `--watch` means babysitter mode.
 
 For one-shot startup prompts, add `--auto-stop`. It requires `--context`.
 A Codex app-server turn launched from `--context` only counts as accepted
-autonomous work when structured command/tool activity, a Git delta, or a fresh
-accepted/no-change artifact report proves activity. An acknowledgment-only turn emits
+autonomous work when structured command/tool activity or a Git delta proves
+activity. Optional receipt claims cannot satisfy this gate. An acknowledgment-only turn emits
 `outcome.class=completed_no_activity`, makes `watch --until done` return
 non-zero, and auto-stops with a non-zero verdict instead of reporting success.
 PTY adapters still stop on prompt return because they do not expose equivalent
@@ -252,14 +253,17 @@ Schema details and compatibility policy are documented in
 
 ## Dispatch history
 
-Every finished `harnex run` writes dispatch records. By default, the terminal
-summary JSONL path is `<session-root>/.harnex/dispatch.jsonl`; `--cwd DIR` makes
-`DIR` the session root, including for non-git temporary bundles. The compact
-history record is repo-local in a git tree and falls back to
-`~/.local/state/harnex/dispatch.jsonl` outside git.
-`harnex history` reads the compact records from that location, and
-`harnex status --id ID --json` / `harnex wait` can use the same durable
-terminal summaries when the live session registry is already gone.
+Every `harnex run` writes exactly one v2 `dispatch_start` row at registration
+and one rich v2 `dispatch_end` row at teardown. Both use the canonical stream:
+`<git-root>/.harnex/dispatch.jsonl` inside a git repo, or
+`~/.local/state/harnex/dispatch.jsonl` otherwise. The end row combines the
+history envelope with usage, context, attribution, outcome, attempt,
+reliability, queue/orchestration, and a harness-authored observed-state receipt.
+
+The canonical stream is the only destination; there is no flag to mirror a
+second copy elsewhere. `harnex history`, `harnex status --id ID --json`, and
+`harnex wait` all read the canonical stream when the live registry is gone.
+Mixed legacy v1 and v2 rows remain readable.
 
 Use `harnex history` to inspect it:
 
@@ -274,36 +278,37 @@ Dispatch briefs can declare soft budget metadata through `--meta`:
 harnex run pi --meta '{"read_budget_lines":2000,"output_ceiling_lines":800}' ...
 ```
 
-Workers can also write a small machine-readable proof sidecar while keeping the
-canonical explanation in plain-text `koder/` files. Initialize the real schema
-instead of asking a model to reproduce it from prose:
-
-```bash
-harnex artifact-report init .harnex/reports/pi-i-61.json
-harnex run pi --id pi-i-61 \
-  --artifact-report .harnex/reports/pi-i-61.json \
-  --require-artifact-report \
-  --context 'Run validation, update the canonical koder artifact, finalize $HARNEX_ARTIFACT_REPORT_PATH, and validate it with harnex artifact-report validate "$HARNEX_ARTIFACT_REPORT_PATH" --final' \
-  --auto-stop
+Every dispatch gets a canonical `harnex.artifact_report.v1` receipt generated
+by Harnex from observed state: start/end Git SHA and delta, changed paths and
+LOC, structured command exits when the transport exposes them, turn outcome,
+and usage. No model-authored proof JSON or `--artifact-report` flag is needed.
+The default file lives under `~/.local/state/harnex/receipts/`; the live status
+payload and final dispatch row expose its absolute path.
+
+Use `--artifact-report PATH` only to override that destination. During the run,
+`HARNEX_ARTIFACT_REPORT_PATH` names the harness-owned final file and
+`HARNEX_ARTIFACT_CLAIMS_PATH` names a separate optional worker input. A review
+worker may attach bounded context without controlling acceptance:
+
+```json
+{
+  "claims": {
+    "summary": "Review complete; one P2 remains.",
+    "verdict": "changes_requested",
+    "findings": { "P1": 0, "P2": 1, "P3": 0 }
+  }
+}
 ```
 
-The sidecar schema is `harnex.artifact_report.v1`; harnex exposes the path as
-`HARNEX_ARTIFACT_REPORT_PATH` / `HARNEX_VALIDATION_REPORT_PATH`, the schema as
-`HARNEX_ARTIFACT_REPORT_SCHEMA`, and strict mode as
-`HARNEX_ARTIFACT_REPORT_REQUIRED=1`. `harnex artifact-report validate PATH`
-checks field shapes; add `--final` to require `status=pass`, an
-`accepted`/`no_change` outcome with a summary, valid command exit codes, and
-`validation.final_reported=true`. Diagnostics contain bounded field paths and
-shape errors, not report payloads or transcripts.
-
-Without `--require-artifact-report`, report defects remain fail-soft warning
-telemetry. With it, a missing, malformed, unsupported, oversized,
-contract-incomplete, rejected, or unchanged stale report makes the work verdict
-non-zero. A fresh explicit `no_change` report can prove an intentional no-delta
-task without fake edits. Harnex records compact `artifact_report`, `validation`,
-and `artifacts` blocks plus `outcome.class` / `outcome.report_status`; Git
-changes alone never imply semantic acceptance, and JSON printed in final prose
-is never scraped as a sidecar.
+Harnex sanitizes that block and writes it into the receipt; malformed, stale,
+or missing claims are ignored. Claims and final prose can never turn an
+otherwise rejected completion into accepted proof. `harnex artifact-report
+validate PATH --final` validates the harness receipt for consumers, while the
+older `init` command and legacy worker-authored v1 validation remain available
+for compatibility. `--require-artifact-report` is also retained for existing
+scripts but no longer requires an explicit path. A receipt write failure fails
+closed as `report_invalid`; ordinary workers no longer fail because they forgot
+or malformed proof JSON.
 
 Queue runners can pass first-class attribution without hiding it in prose:
 
@@ -312,17 +317,17 @@ harnex run pi --project-id harnex --queue-id queue-005 --entry-id SP-4 \
   --phase implement --intent queue-work --require-attribution ...
 ```
 
-Soft budget metadata is copied into summary `meta`; queue/agent/reliability
-metadata is copied into top-level `queue`, `agent`, and `reliability` summary
-blocks. Every terminal row also has `usage` (so null is distinguishable from
-explicit zero or an estimate), `attribution`, `outcome`, and a joinable
-per-session `attempt` block. Terminal summary `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`.
+Soft budget metadata is copied into end-row `meta`; queue/agent/reliability
+metadata is copied into top-level `queue`, `agent`, and `reliability` blocks.
+Every end row also has `usage` (so null is distinguishable from explicit zero or
+an estimate), `attribution`, `outcome`, and a joinable `attempt` block. When an
+adapter reports tokens but no cost, Harnex may compute provider list-price cost
+only for an exact maintained provider/model/service-tier/context-rate match; such rows use
+`usage.cost_source: "price_table"` and carry `usage.cost_price_as_of`.
+Provider-reported cost remains authoritative, estimates remain labelled, and
+unknown rates stay null. `actual` also records timing, exit classification, git
+deltas, task-completion state, harness-derived cross-dispatch attempt counts,
+operational counters, output/event paths, and bounded volume measurements.
 
 Long queue runners can also opt into logical primary-orchestrator rollups:
 
@@ -422,8 +427,8 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 | `harnex events --id <id>` | Stream structured session events (`--snapshot` for non-blocking dump) |
 | `harnex history` | List completed dispatches from `.harnex/dispatch.jsonl` |
 | `harnex wait --id <id>` | Block until process exit by default; use `--until done` for unattended work completion or `--until task_complete` for exact structured turn completion |
-| `harnex artifact-report init\|validate PATH` | Create or validate bounded `harnex.artifact_report.v1` proof; use `validate --final` before strict completion |
-| `harnex doctor` | Run adapter dependency preflight checks; add `--sweep` for read-only session drift diagnostics |
+| `harnex artifact-report init\|validate PATH` | Validate harness-authored `harnex.artifact_report.v1` receipts; `init` remains for legacy/manual documents |
+| `harnex doctor` | Run dependency and retention diagnostics; `--sweep` reports session drift, `--prune --dry-run` previews retention, and `--prune` applies it |
 | `harnex guide` | Getting started walkthrough |
 | `harnex agents-guide` | Agent-facing dispatch, chain, buddy, monitoring, and naming guides |
 | `harnex recipes` | List and read tested workflow patterns (`show 01`, `show buddy`) |
@@ -442,6 +447,8 @@ longer used. Remove stale `~/.claude/skills/harnex-*` or
 
 - [GUIDE.md](GUIDE.md) — getting started walkthrough with examples
 - [TECHNICAL.md](TECHNICAL.md) — full command reference, flags, HTTP API, architecture
+- [docs/dispatch-telemetry.md](docs/dispatch-telemetry.md) — v2 dispatch stream and field contract
+- [docs/configuration.md](docs/configuration.md) — phase allowlists and events/output/receipt retention
 
 ## License
 

data/TECHNICAL.md

@@ -29,27 +29,44 @@ harnex run codex -- --cd ~/other/repo
 | `--watch-file PATH` | Auto-send a file-change hook (`--watch PATH`/`--watch=PATH` legacy) |
 | `--context TXT`     | Give the agent a task on startup                                    |
 | `--auto-stop`       | With `--context`, stop after accepted task completion               |
-| `--artifact-report PATH` | Expose and ingest a bounded v1 proof sidecar                   |
-| `--require-artifact-report` | Fail closed unless the sidecar is accepted final proof      |
+| `--meta JSON`       | Attach bounded caller metadata                                      |
+| `--phase TEXT`      | First-class phase attribution (optionally repo-allowlisted)          |
+| `--artifact-report PATH` | Override the harness-authored v1 receipt destination            |
+| `--require-artifact-report` | Compatibility strict flag; default receipt path is sufficient |
 | `--fast`            | For Codex, use `service_tier="fast"` instead of default `flex`      |
 | `--timeout SEC`     | Wait budget for detached registration                               |
 
 Codex app-server auto-stop rejects completion with no structured command/tool
-activity, Git delta, or fresh accepted/no-change report as
-`completed_no_activity`. Strict artifact-report mode works across transports
-and returns non-zero for missing, invalid, rejected, or stale proof.
+activity or Git delta as `completed_no_activity`. Every transport gets a
+harness-authored observed-state receipt; optional worker claims never determine
+acceptance, and receipt-write failure is fail-closed.
 
-### `harnex artifact-report` — Initialize and validate proof
+### `harnex doctor` — Preflight, drift, and retention
+
+```bash
+harnex doctor
+harnex doctor --sweep
+harnex doctor --prune --dry-run
+harnex doctor --prune
+```
+
+Plain output includes adapter prerequisites and events/output/receipt retention status.
+`--sweep` adds read-only live-session/tmux drift diagnostics. `--prune --dry-run`
+previews age/size-cap deletions; `--prune` applies them while preserving current
+and live-session files. See [docs/configuration.md](docs/configuration.md).
+
+### `harnex artifact-report` — Validate receipts and legacy proof
 
 ```bash
 harnex artifact-report init .harnex/reports/worker.json
 harnex artifact-report validate .harnex/reports/worker.json --final
 ```
 
-`init` writes a schema-valid in-progress skeleton (`--force` replaces an
-existing file). `validate` emits bounded machine-readable field diagnostics;
-`--final` additionally requires accepted/no-change final proof and successful
-validation records.
+Normal runs write their own final receipt, so workers do not call `init`.
+`validate` emits bounded machine-readable field diagnostics; `--final` accepts
+a complete harness receipt whose observed terminal state was accepted. `init`
+remains for legacy/manual v1 documents, whose older successful-validation
+contract is still supported.
 
 ### `harnex send` — Talk to a running agent
 
@@ -98,6 +115,8 @@ Use `--json` for full payloads. JSON includes:
 
 - `log_mtime` (ISO8601 or `null`) — transcript file mtime
 - `log_idle_s` (Integer or `null`) — seconds since last transcript write
+- `artifact_report_path` — harness-owned final observed-state receipt
+- `artifact_claims_path` — optional bounded worker-claims input
 
 Use `--all` for all repos.
 
@@ -115,8 +134,10 @@ harnex history
 harnex history --json | jq .
 ```
 
-Reads `<repo>/.harnex/dispatch.jsonl`, where `<repo>` is found by walking up
-until `.git/` is present. Use `--global` for the no-repo fallback file.
+Reads the canonical v2 stream at `<git-root>/.harnex/dispatch.jsonl`; use
+`--global` for `~/.local/state/harnex/dispatch.jsonl` outside a repo. Each run
+has one `dispatch_start` plus one rich `dispatch_end`. That stream is the only
+destination; no flag mirrors the end row into a second file.
 
 ### `harnex logs` — Read session transcripts
 
@@ -246,8 +267,9 @@ Transport file (append-only JSONL):
 ```
 
 Each row uses schema v1 with envelope fields `schema_version`, `seq`, `ts`,
-`id`, and `type`. Emitted today: `started`, `send`, `exited`. `send.msg` is a
-200-character preview with `msg_truncated` when shortened.
+`id`, and `type`. Lifecycle, send, usage, git, summary, attempt, completion,
+and adapter-specific events are additive; consumers must ignore unknown event
+types. `send.msg` is a 200-character preview with `msg_truncated` when shortened.
 
 Schema details and compatibility guarantees are in [docs/events.md](docs/events.md).
 
@@ -300,7 +322,8 @@ When you run `harnex run codex --id worker`:
       hash(repo_root + id) % port_span + base_port
       walk forward until a free port is found
  6. Start HTTP server on 127.0.0.1:<port>
- 7. Write registry file:
+ 7. Opportunistically enforce configured age/size retention for events/output/receipts,
+      preserving current and live-session files; then write registry file:
       ~/.local/state/harnex/sessions/<repo_hash>--<id>.json
       and open transcript file:
       ~/.local/state/harnex/output/<repo_hash>--<id>.log