harnex 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4158bd117bb14da526926a4f80e61c0d4809b5fb401ff718c2b64ddeb0075730
-  data.tar.gz: 6c2b75a37fbe9dbc9236b02898e9672c30af2bf72716c1c83152006760ff67de
+  metadata.gz: d0a3ac349311bc2677614dabb091443bb21ec82bf63852d237fb38fd47ecaeda
+  data.tar.gz: f1b909c7ed43636ea57a297e25f2adc1d56283faa5f8af882ed22b63b4c55f2f
 SHA512:
-  metadata.gz: 016be4a78e559a075d8477e99343290098025f0e0cf70538da97b647c281a94c8fbf3f704276dd5ba6d00d8d3f92321c16b4f875e6849e302037fb6bb2199cac
-  data.tar.gz: 8cec64fc830b8a37238b5ea1d0068d4422190ffb76dc0f936a10de95b6928512fdf25cf032ec5990e8c3a6e32d2012d4d0fac41f5946f68ad4e74b2e25ebce3a
+  metadata.gz: fe2b745dd618e1967fa5bbe1f7f55f4c0c2beb104cd6d213592f8545528118d3b3a80053b5643fce5482d3eaca9c7e6d800b6f5dd6d41873c0c9e5cc73aff332
+  data.tar.gz: 0c13e6cb6fe6bbac64e14ae43b23061a2b5a96cbc7f4699d438b5e5eac48ef70435c017b638635c0ded52886536f94aac37df712b1d67a9c5485dc0dd1cfa4b7

data/CHANGELOG.md

@@ -1,5 +1,105 @@
 # 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

data/README.md

@@ -206,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
@@ -258,13 +258,12 @@ 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 optional artifact-report sections.
+reliability, queue/orchestration, and a harness-authored observed-state receipt.
 
-`--summary-out PATH` has no default. It is an explicit compatibility mirror
-that copies the identical `dispatch_end` row to another JSONL file; do not pass
-it merely to preserve rich telemetry. `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.
+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:
 
@@ -279,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:
 
@@ -427,7 +427,7 @@ 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 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 |
@@ -448,7 +448,7 @@ 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 retention
+- [docs/configuration.md](docs/configuration.md) — phase allowlists and events/output/receipt retention
 
 ## License
 

data/TECHNICAL.md

@@ -30,17 +30,16 @@ harnex run codex -- --cd ~/other/repo
 | `--context TXT`     | Give the agent a task on startup                                    |
 | `--auto-stop`       | With `--context`, stop after accepted task completion               |
 | `--meta JSON`       | Attach bounded caller metadata                                      |
-| `--summary-out PATH` | Mirror the canonical v2 dispatch end row to another JSONL file     |
 | `--phase TEXT`      | First-class phase attribution (optionally repo-allowlisted)          |
-| `--artifact-report PATH` | Expose and ingest a bounded v1 proof sidecar                   |
-| `--require-artifact-report` | Fail closed unless the sidecar is accepted final proof      |
+| `--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 doctor` — Preflight, drift, and retention
 
@@ -51,22 +50,23 @@ harnex doctor --prune --dry-run
 harnex doctor --prune
 ```
 
-Plain output includes adapter prerequisites and events/output retention status.
+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` — Initialize and validate proof
+### `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
 
@@ -115,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.
 
@@ -134,8 +136,8 @@ harnex history --json | jq .
 
 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`. `--summary-out` is an
-explicit-only end-row mirror, not a second default stream.
+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
 
@@ -320,7 +322,7 @@ 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. Opportunistically enforce configured age/size retention for events/output,
+ 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:

data/docs/codex-appserver.md

@@ -42,7 +42,7 @@ After the handshake the client is ready to issue `thread/start` and
 |-----------------------------|--------------------|-------|
 | `thread/started`            | (metadata)         | Stashes `threadId` |
 | `turn/started`              | `turn_started`     | Carries `turnId` |
-| `turn/completed`            | `task_complete` or `task_failed` | Failed/interrupted statuses emit `task_failed` with the Codex error. A completed `--context` turn emits `task_complete` only with structured command/tool activity, Git delta, or fresh accepted/no-change report proof; otherwise it emits typed `completed_no_activity`. |
+| `turn/completed`            | `task_complete` or `task_failed` | Failed/interrupted statuses emit `task_failed` with the Codex error. A completed `--context` turn emits `task_complete` only with structured command/tool activity or a Git delta; otherwise it emits typed `completed_no_activity`. Harnex writes the observed-state receipt before the successful event. |
 | `item/started`              | (silent)           | Streaming deltas opted out |
 | `item/completed`            | `item_completed` + synthesized transcript | See "tmux/STDOUT" below |
 | `error`                     | `error`            | Turn-level Codex error notification; preserves nested `error.message` and does not count as a transport disconnect. |
@@ -102,19 +102,21 @@ harnex wait --id cx-i-242 --until task_complete --timeout 300
 
 `--until done` returns non-zero when it sees `task_failed` or failed terminal
 telemetry. This includes acknowledgment-only autonomous `--context` turns
-(`outcome_class=completed_no_activity`) and strict sidecar failures
-(`report_missing`, `report_invalid`, or `report_rejected`). Harnex classifies
-these from app-server item counters, Git state, and the configured report path;
-it does not inspect final-answer prose. The task-complete/task-failed waiters
+(`outcome_class=completed_no_activity`) and the rare receipt-write failure
+(`report_invalid`). Harnex classifies completion from app-server item counters
+and Git state; it does not inspect final-answer prose or trust worker claims.
+The task-complete/task-failed waiters
 tail the events JSONL — not the API socket — so they keep working across
 restarts and are adapter-agnostic.
 
-For blind dispatches that require report proof, combine
-`--artifact-report PATH --require-artifact-report`. Only a fresh valid sidecar
-at `PATH` can satisfy the contract; report-shaped JSON printed in an
-`agentMessage` is ordinary transcript text and is ignored. Use
-`harnex artifact-report init PATH` and `harnex artifact-report validate PATH
---final` to avoid hand-authoring the schema.
+Every blind dispatch receives a harness-authored receipt. No worker report is
+required: Harnex captures command exits, Git state, completion, and usage, then
+writes `HARNEX_ARTIFACT_REPORT_PATH` before emitting `task_complete`. Use
+`--artifact-report PATH` only to choose a fixed destination; otherwise the
+status/end row points to the default state-directory path. Review workers may
+write advisory summary/verdict/P1-P3 counts to `HARNEX_ARTIFACT_CLAIMS_PATH`.
+Claims and report-shaped `agentMessage` text cannot satisfy the activity gate.
+Consumers can run `harnex artifact-report validate PATH --final` afterward.
 
 ## `harnex doctor`
 
@@ -152,8 +154,9 @@ for autonomous worker dispatches; legacy-pty is for interactive/TUI use.
 - **`task_failed` immediately after dispatch.** Check
   `harnex events --id <session>`. Provider/model failures retain their Codex
   error message. `completed_no_activity` means the turn ended with no
-  command/tool or Git/report proof; `report_missing` / `report_invalid` /
-  `report_rejected` identify strict sidecar defects. Common provider failures
+  command/tool or Git activity. `report_invalid` now primarily identifies a
+  harness receipt-write failure; old rows may still contain the legacy
+  `report_missing` / `report_rejected` classes. Common provider failures
   include auth environment variables (for example `OPENAI_API_KEY` /
   `AZURE_OPENAI_API_KEY`) and model unavailability.
 

data/docs/configuration.md

@@ -46,14 +46,15 @@ The effective value is the first-class `harnex run --phase TEXT` value, or
 The allowlist must be an array of non-empty strings. Policy must be `warn` or
 `reject`.
 
-## Events and output retention
+## Events, output, and receipt retention
 
-Per-session event JSONL and output transcripts live under Harnex's local state
-directory and are not the durable dispatch stream:
+Per-session event JSONL, output transcripts, and generated proof receipts live
+under Harnex's local state directory and are not the durable dispatch stream:
 
 ```text
 ~/.local/state/harnex/events/
 ~/.local/state/harnex/output/
+~/.local/state/harnex/receipts/
 ```
 
 Defaults apply independently to each directory:
@@ -73,6 +74,10 @@ Override them in repo configuration:
     "output": {
       "max_age_days": 45,
       "max_bytes": 1073741824
+    },
+    "receipts": {
+      "max_age_days": 45,
+      "max_bytes": 1073741824
     }
   }
 }
@@ -85,10 +90,12 @@ HARNEX_EVENTS_MAX_AGE_DAYS
 HARNEX_EVENTS_MAX_BYTES
 HARNEX_OUTPUT_MAX_AGE_DAYS
 HARNEX_OUTPUT_MAX_BYTES
+HARNEX_RECEIPTS_MAX_AGE_DAYS
+HARNEX_RECEIPTS_MAX_BYTES
 ```
 
 Limits must be positive integers. Harnex deletes only regular files directly
-owned by the `events` and `output` directories: expired files first, then the
+owned by the `events`, `output`, and `receipts` directories: expired files first, then the
 oldest unprotected files until the size cap is met. It never follows paths
 outside those directories. Files for the current session, live registry PIDs,
 and alive uncompleted dispatch-start rows are protected. If protected files