harnex 0.7.12 → 0.7.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da71f86b7e940d085a54ae59ce7f70a9579ca23204213cbc41a017fd5d11ed9f
-  data.tar.gz: 194f3ac0c6fabf118e74542dd4836c5014721cdf0000973b03be07dceceeee3e
+  metadata.gz: e50f27f3d17436e058126d656fdaeb3dfd58cbfdb0e565b8f221ae6b579f3507
+  data.tar.gz: 01f08ae4414ed2e6a5d4d4503888349c7e27b7aee348b805a435f393ba0f95ad
 SHA512:
-  metadata.gz: 7975b8610b1d21c230fb0ccf7b55c16bdd9e9ff71c770bdb42f831e687313e47c9e01b20157fc8f95c767bdf716e3501fcb56a490d37dfb277f7ac1bd03fda74
-  data.tar.gz: 54e0d45f362d94efa2d0d698911c2d2b1daaf534c97be95bef99512d3c6ab8ad44bdb6d099eaff6d5bb38e08acee563901d94db528ab0b03df8a856648c88dd5
+  metadata.gz: f62483a74ed5651eecc43c2e30f5020ddd077b0038a17522309af411335c86b94a04d45eec39a2d33defcbb0d781b7ac1c3085c34bd24d0ab1f9baaeb5ebbc32
+  data.tar.gz: 896793c0dc92d82f62989105714be633fc3b4966752fa3049d7258529cc31fbad2ac0ef1ff36bec2c5b9ac1b2baf42ac325d96f3fe9228f8efbfd0b61bc0e906

data/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 ## [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
+
+- Dispatch summaries now include a stable additive `context` block with
+  terminal and peak active-context pressure, source/status provenance, bounded
+  sample counts, and explicit missing-sample handling. Pi RPC reports observed
+  `get_session_stats.contextUsage`; Codex app-server conservatively estimates
+  pressure from `tokenUsage.last` plus `modelContextWindow`; unsupported
+  adapters do not fabricate values.
+- Dispatch summaries now include additive `usage`, `attribution`, `outcome`, and
+  per-session `attempt` blocks. `usage.status` distinguishes provider-observed,
+  explicit-zero, caller-estimated, unsupported, and missing values so nullable
+  cost/token fields are never mistaken for zero.
+- `harnex run` accepts `--parent-dispatch-id`, `--parent-attempt-id`, and
+  `--attempt-kind` (`initial`, `retry`, `fix`, `review`, or `superseding`) to
+  preserve parent/child relationships while retaining separate raw effort rows.
+- Terminal event streams now emit `attempt_started` / `attempt_finished` and
+  translate Pi internal retry notices into `attempt_retry_scheduled`; the
+  Session exposes an `attempt_fallback_switched` telemetry seam for recovery
+  and fallback owners.
+- Bounded artifact reports can optionally record a semantic outcome
+  (`accepted`, `rejected`, `no_change`, or `unknown`). Final outcome blocks
+  retain git commit/path/LOC observations without claiming they prove authorship.
+
+### Changed
+
+- Dispatch telemetry documentation now distinguishes cumulative usage from
+  active context-window pressure and defines context sample/high-water/null
+  semantics alongside usage-cost provenance, strict attribution quality,
+  sidecar-backed outcomes, attempt linkage, and safe throughput/reliability
+  query examples.
+
 ## [0.7.12] - 2026-07-10 | 11:19 PM | IST
 
 ### Fixed

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,20 +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. 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:
 
@@ -293,13 +314,36 @@ harnex run pi --project-id harnex --queue-id queue-005 --entry-id SP-4 \
 
 Soft budget metadata is copied into summary `meta`; queue/agent/reliability
 metadata is copied into top-level `queue`, `agent`, and `reliability` summary
-blocks. 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`.
+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`.
+
+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.
@@ -378,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:
 

data/lib/harnex/adapters/base.rb

@@ -73,6 +73,22 @@ module Harnex
         {}
       end
 
+      # Whether this adapter has a supported source for token/cost telemetry.
+      # A supported source can still be missing for a particular run.
+      def usage_telemetry_supported?
+        false
+      end
+
+      # Whether this adapter exposes active context-window occupancy separately
+      # from cumulative usage. Supported sources can still yield no valid sample.
+      def context_telemetry_supported?
+        false
+      end
+
+      def context_telemetry_source
+        nil
+      end
+
       def send_wait_seconds(submit:, enter_only:)
         0.0
       end

data/lib/harnex/adapters/codex.rb

@@ -60,6 +60,10 @@ module Harnex
         end
       end
 
+      def usage_telemetry_supported?
+        true
+      end
+
       def parse_session_summary(transcript_tail)
         summary = empty_session_summary
         text = transcript_tail.to_s

data/lib/harnex/adapters/codex_appserver.rb

@@ -74,6 +74,18 @@ module Harnex
         "openai"
       end
 
+      def usage_telemetry_supported?
+        true
+      end
+
+      def context_telemetry_supported?
+        true
+      end
+
+      def context_telemetry_source
+        "codex_thread_token_usage_last"
+      end
+
       def base_command
         ["codex", "app-server"]
       end

data/lib/harnex/adapters/pi.rb

@@ -31,6 +31,10 @@ module Harnex
         @write_mutex = Mutex.new
         @summary_mutex = Mutex.new
         @session_summary = {}
+        @context_telemetry = ContextTelemetry.new(
+          status: "observed",
+          source: context_telemetry_source
+        )
         @model = nil
         @provider = nil
         @session_stats_requested = false
@@ -49,6 +53,18 @@ module Harnex
         @model
       end
 
+      def usage_telemetry_supported?
+        true
+      end
+
+      def context_telemetry_supported?
+        true
+      end
+
+      def context_telemetry_source
+        "pi_get_session_stats"
+      end
+
       def base_command
         ["pi", "--mode", "rpc"]
       end
@@ -147,11 +163,17 @@ module Harnex
 
       def request_session_stats_async
         return if @closed
-        return if @session_stats_requested
 
-        @session_stats_requested = true
+        should_request = @summary_mutex.synchronize do
+          next false if @session_stats_requested
+
+          @session_stats_requested = true
+        end
+        return unless should_request
+
         write_line("type" => "get_session_stats")
       rescue StandardError
+        clear_session_stats_request
         nil
       end
 
@@ -181,8 +203,10 @@ module Harnex
             agent_session_id: @session_summary[:agent_session_id],
             tool_calls: @session_summary[:tool_calls],
             cost_usd: @session_summary[:cost_usd],
+            cost_source: @session_summary[:cost_source],
             model: @session_summary[:model],
-            agent_provider: @session_summary[:agent_provider]
+            agent_provider: @session_summary[:agent_provider],
+            context: @context_telemetry.snapshot
           }
         end
       end
@@ -263,8 +287,7 @@ module Harnex
       end
 
       def attempt_live_summary_refresh
-        response = request("type" => "get_session_stats")
-        absorb_session_stats(response)
+        request("type" => "get_session_stats")
       rescue StandardError
         nil
       end
@@ -338,6 +361,8 @@ module Harnex
           @state = :prompt
           @last_completed_at = Time.now
           request_session_stats_async
+        when "compaction_end"
+          request_session_stats_async
         when "message_end"
           absorb_model_from_message(message["message"])
         end
@@ -362,6 +387,8 @@ module Harnex
         return unless data.is_a?(Hash)
 
         tokens = data["tokens"] || {}
+        context_usage = data["contextUsage"]
+        context_usage = {} unless context_usage.is_a?(Hash)
         @summary_mutex.synchronize do
           @session_summary[:input_tokens] = numeric_or_nil(tokens["input"])
           @session_summary[:output_tokens] = numeric_or_nil(tokens["output"])
@@ -369,10 +396,24 @@ module Harnex
           @session_summary[:total_tokens] = numeric_or_nil(tokens["total"])
           @session_summary[:tool_calls] = numeric_or_nil(data["toolCalls"])
           @session_summary[:cost_usd] = float_or_nil(data["cost"])
+          @session_summary[:cost_source] = "provider_reported" unless @session_summary[:cost_usd].nil?
           @session_summary[:agent_session_id] = data["sessionId"] if data["sessionId"]
           @session_summary[:model] = @model if @model
           @session_summary[:agent_provider] = @provider if @provider
+          @context_telemetry.record(
+            tokens: context_usage["tokens"],
+            window_tokens: context_usage["contextWindow"],
+            percent: context_usage["percent"]
+          )
         end
+      ensure
+        clear_session_stats_request
+      end
+
+      def clear_session_stats_request
+        @summary_mutex.synchronize { @session_stats_requested = false }
+      rescue StandardError
+        @session_stats_requested = false
       end
 
       def absorb_model_from_message(message)