harnex 0.7.13 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e087c98409987c2494911c830e3670a23abc5129ed22030bebd7cee953f920fd
-  data.tar.gz: 036eb960f719874ba7f7954bcf3c4191ca324d4ff77f7098069b231327efbd87
+  metadata.gz: 9142cc69cec0a0cf0dc3961ccc27dc3728baea445c7d83b4c2d69a34b7e6a499
+  data.tar.gz: b89c616cb2484d48e74ef88985a438f7ebb1c22b1af17dd44cbaab3ee0c020cd
 SHA512:
-  metadata.gz: a96531d075117e46512181ebb89fff0c0abb3ffbd829807d4fa9624b5c684255fc896882455678b7cce0e9094be11d4279beb5a6af84ad0a23e2974496d5d173
-  data.tar.gz: 530d365ae7a6bbd2d2d9f34a708babb8f5c9446290808ed23170fc8329997c2b9c6ce5dd62ae326905bec7f46cd222253b4815c61d484c9e600d40ff675d4fee
+  metadata.gz: 220566d1c646ca49b7f41f8ed053b2909dda8468ab3dc877bfcfe5f47b52988492d54b9d2fcc42ff0e42154921fde97af0824688b27df69e94bd9fc49b77c2f8
+  data.tar.gz: e52eca128c1f078171ab991acd25bafa810e8341a7f6c8f199535cd03b7a881ee03f2c4193afb01ece92cc00d0a8025a6bdb564739aeb13cbe6a02a4f4d87d0a

data/CHANGELOG.md

@@ -1,6 +1,87 @@
 # Changelog
 
-## [Unreleased]
+## [0.8.0] - 2026-08-02 | 08:46 PM | IST
+
+Minor bump: two behavior changes below (`wait --until done` exit codes,
+`--attempt-kind retry` now requiring `--parent-dispatch-id`).
+
+### Added
+
+- Dispatch-start records (#62): every dispatch appends a durable
+  `dispatch_start` row to the repo dispatch stream at registration (id,
+  session_id, pid, host, started_at, meta, schema_version); the
+  `dispatch_end` row written at teardown completes it. End rows now carry
+  `record_type` and `session_id` so readers can pair them.
+- `harnex history` now shows uncompleted dispatches as `running` (pid alive
+  on this host) or `interrupted` (pid gone, no end row) instead of hiding
+  them until teardown.
+- Duplicate-dispatch guard (#62): `harnex run --attempt-kind retry` requires
+  `--parent-dispatch-id`, and retry/fix/superseding dispatches naming a
+  still-running parent in the same repo are refused with a clear error.
+  `--allow-live-parent` overrides for intentional parallelism; `review` is
+  exempt.
+
+### Changed
+
+- `harnex wait --until done` now has a documented exit-code contract
+  (guides/04_monitoring.md): `0` accepted work, `1` failed, `2` completed but
+  proof rejected, `3` no such session, `124` timeout. The wrapped process's
+  exit code is reported as payload data instead of being passed through.
+  Payloads carry a `wait_result` field.
+- `harnex wait --until done` re-checks liveness every poll (registry, then
+  uncompleted start row with alive pid) and blocks while the session's pid
+  is alive. Stale exit-status files and events from an earlier dispatch that
+  reused the same id are ignored while a live session is in view.
+- `harnex status` no longer silently reports stale registry data as live:
+  rows are labelled `source: live|registry|dispatch_start` with
+  `degraded: true` when the live status API was unreachable. With `--id`, a
+  running session whose registry row is missing is still reported running
+  from its uncompleted start row.
+- One canonical repo resolution for all dispatch-stream writers and readers:
+  history rows now key off the session's `repo_root` (matching the summary
+  path) instead of the launch cwd, and `repo_key` canonicalizes symlinked
+  paths via realpath so registries written from a symlinked cwd stay visible
+  to checkers resolving the physical path.
+- Refreshed the codex app-server schema fixtures against codex-cli 0.145.0
+  (10 fixtures; upstream-additive changes only, no adapter impact).
+
+## [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
 

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

@@ -22,10 +22,59 @@ For unattended monitors on existing visible/detached sessions, prefer
 `task_failed` signal, or terminal exit, whichever comes first. Successful work
 exits `0`, failed work exits non-zero, and wall-clock caps exit `124`. For
 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.
+the same work fence.
+
+## Live-Run Visibility
+
+Every dispatch appends a `dispatch_start` row to the repo's dispatch stream
+(`.harnex/dispatch.jsonl`) at registration; the `dispatch_end` row at teardown
+completes it. Between those two rows the run is visible to every documented
+signal, from any cwd in the same repo:
+
+- `harnex status --id X` reports `state=running` for a live session. When the
+  live HTTP status API is unreachable it still reports running from the
+  registry (or, failing that, from the uncompleted start row) and labels the
+  row `degraded: true` with `source` set to `registry` or `dispatch_start`.
+- `harnex history` shows uncompleted dispatches as `running` (pid alive) or
+  `interrupted` (pid gone, no end row). Completed dispatches render one
+  `dispatch_end` row.
+- `harnex wait --until done` blocks while the session's pid is alive, up to
+  `--timeout`. "No signal yet" from a live worker is never terminal.
+
+A monitor consulting these signals can never classify a healthy mid-run
+worker as dead. If `status` says running, do not dispatch a replacement.
+
+## `wait --until done` Exit-Code Contract
+
+| Code | `wait_result` | Meaning |
+| --- | --- | --- |
+| `0` | `done` | Completed with accepted work |
+| `1` | `failed` | Work failed, process failed, or killed |
+| `2` | `rejected_proof` | Completed but proof rejected (`completed_no_activity`, `report_missing`, `report_invalid`, `report_rejected`) |
+| `3` | `no_such_session` | No live, start, event, or terminal signal for the id |
+| `124` | `timeout` | `--timeout` elapsed while the session was still running |
+
+The JSON payload always carries `wait_result` plus the work-state fields
+(`done`, `work_state`, `outcome_class`, `artifact_report_status`). The child
+process's own exit code is reported as data (`exit_code`), never passed
+through as wait's exit status. Treat `2` as a work-acceptance failure, `3` as
+a coordination error (wrong id or wrong repo), and only `0` as success.
+
+## Duplicate-Dispatch Guard
+
+`harnex run --attempt-kind retry` requires `--parent-dispatch-id`, and any
+retry/fix/superseding dispatch whose named parent is still running in the
+same repo is refused. Wait for the parent
+(`harnex wait --id <parent> --until done`) or stop it first. Pass
+`--allow-live-parent` only for intentional parallelism (e.g. isolated
+worktrees). `--attempt-kind review` is exempt: a completed parent may still
+sit at a live prompt while its work is reviewed. For structured sessions (Pi RPC and Codex app-server),
+`harnex wait --until task_complete` remains the exact accepted-turn fence.
+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 +152,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: