harnex 0.7.13 → 0.7.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e087c98409987c2494911c830e3670a23abc5129ed22030bebd7cee953f920fd
-  data.tar.gz: 036eb960f719874ba7f7954bcf3c4191ca324d4ff77f7098069b231327efbd87
+  metadata.gz: e50f27f3d17436e058126d656fdaeb3dfd58cbfdb0e565b8f221ae6b579f3507
+  data.tar.gz: 01f08ae4414ed2e6a5d4d4503888349c7e27b7aee348b805a435f393ba0f95ad
 SHA512:
-  metadata.gz: a96531d075117e46512181ebb89fff0c0abb3ffbd829807d4fa9624b5c684255fc896882455678b7cce0e9094be11d4279beb5a6af84ad0a23e2974496d5d173
-  data.tar.gz: 530d365ae7a6bbd2d2d9f34a708babb8f5c9446290808ed23170fc8329997c2b9c6ce5dd62ae326905bec7f46cd222253b4815c61d484c9e600d40ff675d4fee
+  metadata.gz: f62483a74ed5651eecc43c2e30f5020ddd077b0038a17522309af411335c86b94a04d45eec39a2d33defcbb0d781b7ac1c3085c34bd24d0ab1f9baaeb5ebbc32
+  data.tar.gz: 896793c0dc92d82f62989105714be633fc3b4966752fa3049d7258529cc31fbad2ac0ef1ff36bec2c5b9ac1b2baf42ac325d96f3fe9228f8efbfd0b61bc0e906

data/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 ## [Unreleased]
 
+## [0.7.14] - 2026-07-15 | 10:06 PM | IST
+
+### Added
+
+- `harnex run` now accepts opt-in orchestration metadata flags
+  (`--orchestration-run-id`, `--orchestration-generation-id`,
+  `--orchestration-role`, `--orchestration-session-id`, and
+  `--orchestration-rotation-reason`) and emits a top-level `orchestration`
+  block when present.
+- New `harnex orchestration sample` / `harnex orchestration report` commands
+  ingest bounded external-primary samples and compute primary-versus-worker
+  queue rollups without storing prompts, transcripts, tool payloads, or secrets.
+- New `harnex artifact-report init PATH` and `harnex artifact-report validate
+  PATH [--final]` commands provide a bounded v1 report skeleton and
+  machine-readable field diagnostics without echoing report payloads.
+- `harnex run --require-artifact-report` makes fresh accepted/no-change report
+  proof part of the work verdict and exposes strict mode to workers through
+  `HARNEX_ARTIFACT_REPORT_REQUIRED=1`.
+
+### Changed
+
+- Autonomous Codex app-server turns launched with `--context` now distinguish
+  provider turn completion from accepted work completion. Harnex requires
+  structured command/tool activity, a Git delta, or a fresh accepted/no-change
+  report before emitting `task_complete`; the classifier never parses final
+  prose and applies equally to flex and fast service tiers.
+- Dispatch outcomes now include additive `class` and `report_status` fields,
+  and watch/wait/status/marker payloads preserve typed proof failures.
+
+### Fixed
+
+- Acknowledgment-only Codex turns now emit `completed_no_activity` and return a
+  non-zero work/auto-stop verdict instead of being reported as successful work.
+- Strict report mode fails closed for missing, malformed, unsupported,
+  oversized, schema-incomplete, rejected, and unchanged stale sidecars. A valid
+  explicit `no_change` report remains an accepted proof path for intentional
+  no-delta work, while report-shaped JSON printed in final prose is ignored.
+
 ## [0.7.13] - 2026-07-15 | 12:24 PM | IST
 
 ### Added

data/README.md

@@ -203,8 +203,14 @@ For file-change hooks, use `--watch-file PATH`. The older
 `--watch PATH`/`--watch=PATH` form is still accepted for compatibility, while
 bare `--watch` means babysitter mode.
 
-For one-shot startup prompts, add `--auto-stop`. It requires `--context`
-and stops the session after the first task completion or PTY prompt return.
+For 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
+`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
+structured activity signals.
 
 ## Completion and waiting
 
@@ -269,21 +275,35 @@ 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:
+canonical explanation in plain-text `koder/` files. Initialize the real schema
+instead of asking a model to reproduce it from prose:
 
 ```bash
-harnex run pi --id pi-i-52 \
-  --artifact-report .harnex/reports/pi-i-52.json \
-  --context 'Run validation, update koder/issues/52.md, and write JSON proof to $HARNEX_ARTIFACT_REPORT_PATH' \
+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
 ```
 
 The sidecar schema is `harnex.artifact_report.v1`; harnex exposes the path as
-`HARNEX_ARTIFACT_REPORT_PATH` / `HARNEX_VALIDATION_REPORT_PATH`, then records a
-compact `artifact_report`, `validation`, and `artifacts` summary in the dispatch
-row. A sidecar can also assert the bounded outcome (`accepted`, `rejected`,
-`no_change`, or `unknown`); git changes alone never imply semantic acceptance.
-Missing or malformed reports are warning telemetry, not wrapped-process crashes.
+`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.
 
 Queue runners can pass first-class attribution without hiding it in prose:
 
@@ -303,6 +323,27 @@ 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`.
+
+Long queue runners can also opt into logical primary-orchestrator rollups:
+
+```bash
+harnex run pi --orchestration-run-id queue-005 --orchestration-generation-id gen-1 \
+  --orchestration-role worker --project-id harnex --queue-id queue-005 \
+  --entry-id SP-4 --phase implement --intent queue-work ...
+
+harnex orchestration sample --out .harnex/orchestrator.jsonl \
+  --run-id queue-005 --generation-id primary-1 --session-id pi-primary-1 \
+  --context-tokens 64000 --context-window-tokens 200000 \
+  --usage-status observed --usage-total-tokens 129000 --tool-calls 31
+
+harnex orchestration report --dispatch .harnex/dispatch.jsonl \
+  --samples .harnex/orchestrator.jsonl --run-id queue-005 --json
+```
+
+External samples use the bounded `harnex.orchestrator_sample.v1` schema. They
+record ids, lifecycle/sample event names, aggregate usage/context counters,
+tool-call counts, compactions, and rotation reasons only; prompts, transcripts,
+tool arguments/results, secrets, and private payloads are out of scope.
 Harnex records the data only; consumers decide whether to fail closed. See
 [docs/dispatch-telemetry.md](docs/dispatch-telemetry.md) for the field
 contract.
@@ -381,6 +422,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 doctor` | Run adapter dependency preflight checks; add `--sweep` for read-only session drift diagnostics |
 | `harnex guide` | Getting started walkthrough |
 | `harnex agents-guide` | Agent-facing dispatch, chain, buddy, monitoring, and naming guides |

data/TECHNICAL.md

@@ -28,10 +28,29 @@ harnex run codex -- --cd ~/other/repo
 | `--preset NAME`     | Watch preset (`impl`, `plan`, `gate`), requires `--watch`           |
 | `--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 the first task completion              |
+| `--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      |
 | `--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.
+
+### `harnex artifact-report` — Initialize and validate 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.
+
 ### `harnex send` — Talk to a running agent
 
 ```bash

data/guides/01_dispatch.md

@@ -22,6 +22,9 @@ Inside a harnex-managed session, these environment variables are available:
 | `HARNEX_SESSION_REPO_ROOT` | Repo root for the session |
 | `HARNEX_SESSION_ID` | Internal harnex instance ID |
 | `HARNEX_SPAWNER_PANE` | Tmux pane ID of the invoker |
+| `HARNEX_ARTIFACT_REPORT_PATH` | Absolute configured proof-sidecar path |
+| `HARNEX_ARTIFACT_REPORT_SCHEMA` | Required sidecar schema identifier |
+| `HARNEX_ARTIFACT_REPORT_REQUIRED` | `1` when report proof is fail-closed |
 
 Use `harnex send`, `harnex status`, `harnex wait`, `harnex pane`, and
 `harnex logs` to coordinate with peers. If you are not inside harnex,
@@ -64,9 +67,14 @@ harnex run pi --id pi-i-NN --tmux pi-i-NN \
 ```
 
 For one-shot context dispatches that should clean themselves up, add
-`--auto-stop`. It requires `--context`, fires once on the first task
-completion, and does not keep the session alive for later reuse. This keeps
-parallel orchestration compact:
+`--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, Git delta, or fresh
+accepted/no-change sidecar proof. 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:
 
 ```bash
 for i in 1 2 3; do
@@ -96,20 +104,32 @@ harnex run codex --cwd /tmp/leximaze_eval_run_001 \
 child process cwd. Neither flag is a sandbox.
 
 For queue closeout, ask workers to write a compact sidecar in addition to their
-plain-text `koder/` artifact:
+plain-text `koder/` artifact. For blind/unattended work, initialize and require
+the report so a normal final answer cannot bypass proof acceptance:
 
 ```bash
+harnex artifact-report init .harnex/reports/pi-i-NN.json
 harnex run pi --id pi-i-NN --tmux pi-i-NN \
   --artifact-report .harnex/reports/pi-i-NN.json \
-  --context 'Update the canonical koder file and write harnex.artifact_report.v1 proof to $HARNEX_ARTIFACT_REPORT_PATH' \
+  --require-artifact-report \
+  --context 'Update the canonical koder file, finalize $HARNEX_ARTIFACT_REPORT_PATH, then run harnex artifact-report validate "$HARNEX_ARTIFACT_REPORT_PATH" --final' \
   --auto-stop
 ```
 
 The worker should keep the full explanation in `koder/` and put only compact
-machine-readable proof in the sidecar: validation command/status, typed
-artifact summaries (`finding`, `review`, `gate`, `blocker`, etc.), evidence,
-confidence, and canonical refs. Harnex records missing/malformed sidecars as
-warning telemetry instead of failing the wrapped process.
+machine-readable proof in the sidecar: an `accepted` or `no_change` outcome,
+validation command/status/exit codes, typed artifact summaries (`finding`,
+`review`, `gate`, `blocker`, etc.), evidence, confidence, and canonical refs.
+`harnex artifact-report validate PATH` checks the schema without echoing report
+payloads; `--final` additionally requires accepted final proof and
+`validation.final_reported=true`.
+
+Without `--require-artifact-report`, missing/malformed reports remain warning
+telemetry. Strict mode fails closed for missing, malformed, unsupported,
+oversized, schema-incomplete, rejected, or unchanged stale reports. JSON in the
+agent's final prose does not count: only the configured sidecar path is read.
+A fresh valid `no_change` report is the explicit proof path for intentional
+no-delta work.
 
 Queue runners should pass first-class attribution so dispatch rows can be grouped
 without path/id heuristics:

data/guides/04_monitoring.md

@@ -23,9 +23,12 @@ For unattended monitors on existing visible/detached sessions, prefer
 exits `0`, failed work exits non-zero, and wall-clock caps exit `124`. For
 callers that need the lower-level primitive, `harnex wait --until done` exposes
 the same work fence. For structured sessions (Pi RPC and Codex app-server),
-`harnex wait --until task_complete` remains the exact successful-turn fence.
-None of these know your acceptance criteria; verify the expected artifact or
-tests afterward.
+`harnex wait --until task_complete` remains the exact accepted-turn fence.
+Codex acknowledgment-only auto-stop turns are typed
+`completed_no_activity` and fail this fence without transcript parsing.
+`--require-artifact-report` can additionally make sidecar shape/final-proof
+acceptance part of the verdict. Harnex still does not judge semantic quality;
+verify the expected artifact or tests afterward.
 
 ## Completion Test
 
@@ -103,8 +106,11 @@ harnex watch --id pi-i-NN --until done --max-wait 90m \
 ```
 
 If that exits `124`, inspect the pane/logs/events and decide whether to nudge,
-stop, or continue. If it exits any other non-zero code, treat the work as
-failed; do not continue polling the same task as though it were still running.
+stop, or continue. If it exits any other non-zero code, inspect
+`outcome_class` / `artifact_report_status` in the JSON or fail marker, treat the
+work as failed, and do not continue polling the same task as though it were
+still running. `completed_no_activity`, `report_missing`, `report_invalid`, and
+`report_rejected` are work-acceptance failures rather than successful turns.
 
 Recommended caps: