harnex 0.8.0 → 0.10.0

data/guides/01_dispatch.md

@@ -22,9 +22,11 @@ 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 |
+| `HARNEX_ARTIFACT_REPORT_PATH` | Absolute harness-owned final receipt path |
+| `HARNEX_ARTIFACT_CLAIMS_PATH` | Optional bounded worker-claims input path |
+| `HARNEX_ARTIFACT_REPORT_SCHEMA` | Receipt schema identifier |
+| `HARNEX_ARTIFACT_REPORT_MODE` | `observed_state` for harness-authored receipts |
+| `HARNEX_ARTIFACT_REPORT_REQUIRED` | `1` when the compatibility strict flag was passed |
 
 Use `harnex send`, `harnex status`, `harnex wait`, `harnex pane`, and
 `harnex logs` to coordinate with peers. If you are not inside harnex,
@@ -69,8 +71,8 @@ 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` 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
+only after structured command/tool activity or a Git delta. Optional claims and
+final prose cannot satisfy that observed-activity gate. 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
@@ -103,33 +105,29 @@ harnex run codex --cwd /tmp/leximaze_eval_run_001 \
 `--root DIR` only overrides harnex's root attribution; it does not change the
 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. For blind/unattended work, initialize and require
-the report so a normal final answer cannot bypass proof acceptance:
+For queue closeout, do not ask workers to author proof JSON. Harnex writes a
+canonical receipt for every dispatch from the Git delta, structured command
+exits, turn outcome, and usage it observed. The default receipt lives outside
+the checkout under the Harnex state directory; pass `--artifact-report PATH`
+only when a queue needs a fixed destination. Consumers can run:
 
 ```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 \
-  --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
+harnex artifact-report validate /path/from/the-dispatch-row.json --final
+```
+
+A worker may add review context by writing only a small block to
+`$HARNEX_ARTIFACT_CLAIMS_PATH` before it completes:
+
+```json
+{"claims":{"summary":"Review complete","verdict":"changes_requested","findings":{"P1":0,"P2":1,"P3":0}}}
 ```
 
-The worker should keep the full explanation in `koder/` and put only compact
-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.
+Claims are bounded and advisory. They never determine receipt validity, and
+malformed/stale claims are ignored. `HARNEX_ARTIFACT_REPORT_PATH` is owned and
+overwritten by Harnex; JSON printed in final prose is not scraped. The legacy
+`artifact-report init` command and `--require-artifact-report` flag remain for
+compatibility, but normal dispatches need neither worker JSON nor an explicit
+receipt path.
 
 Queue runners should pass first-class attribution so dispatch rows can be grouped
 without path/id heuristics:
@@ -145,6 +143,11 @@ harnex run pi --id pi-i-NN --tmux pi-i-NN \
 `intent`, and at least one work id (`queue_id`, `entry_id`, `issue`, or `plan`)
 are present.
 
+Every dispatch writes one `dispatch_start` and one rich v2 `dispatch_end` row
+to the canonical repo/global dispatch stream, which is the only telemetry
+destination. Repo `.harnex/config.json` can warn on or reject non-canonical
+phase names before spawn.
+
 Pi runs use structured RPC (`pi --mode rpc`). Pass Pi child flags after `--`
 (e.g. `harnex run pi --context "..." -- --model anthropic/claude-sonnet-4-5 --thinking high`).
 

data/guides/04_monitoring.md

@@ -62,19 +62,19 @@ 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 run --attempt-kind retry|fallback` requires
+`--parent-dispatch-id`, and any retry/fix/fallback/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.
+`completed_no_activity` and fail this fence without transcript parsing. Harnex
+writes the observed-state receipt before publishing `task_complete`; optional
+worker claims never make an inactive turn pass. Harnex still does not judge
+semantic quality, so verify the expected artifact or tests afterward.
 
 ## Completion Test
 
@@ -91,8 +91,9 @@ harnex watch --id pi-i-NN --until done --max-wait 90m \
 
 `harnex watch --until done` wraps the `harnex wait --until done` work fence:
 it succeeds from `task_complete` or durable successful terminal telemetry
-(`--summary-out` / `.harnex/dispatch.jsonl` / exit status), returns non-zero for
-`task_failed` / failed terminal telemetry, returns `124` for `--max-wait`, and
+(the v2 `dispatch_end` in `.harnex/dispatch.jsonl`, an explicit mirror when
+configured, or exit status), returns non-zero for `task_failed` / failed
+terminal telemetry, returns `124` for `--max-wait`, and
 only writes done/fail markers as compatibility outputs after harnex has seen a
 terminal work signal.
 

data/guides/05_naming.md

@@ -66,17 +66,27 @@ If `--id` is missing, harnex generates a random session ID. The tmux window may
 look right, but `harnex status`, `harnex pane --id`, and logs need the random
 ID.
 
-## Retry Suffixes
+## Retry Suffixes And Linkage
 
-If a session fails and you dispatch a fresh attempt, append a suffix:
+If a session fails and you dispatch a fresh attempt, use a new ID and link it
+to the completed parent so Harnex can derive chain counts and recovery:
 
 ```text
-pi-i-42      first attempt
-pi-i-42b     second attempt
-pi-i-42c     third attempt
+pi-i-42      initial attempt
+pi-i-42-r1   retry of pi-i-42
+pi-i-42-r2   retry of pi-i-42-r1
 ```
 
-Keep the old session's logs. They are useful for diagnosis.
+```bash
+harnex run pi --id pi-i-42-r1 --tmux pi-i-42-r1 \
+  --attempt-kind retry --parent-dispatch-id pi-i-42 \
+  --context "Retry the bounded task."
+```
+
+Retry/fix/fallback/superseding work is refused while its named parent is still
+running unless `--allow-live-parent` explicitly authorizes isolated parallelism.
+Keep old logs for diagnosis; retention removes only expired/over-cap logs that
+do not belong to a current or live session.
 
 ## Task Files
 
@@ -104,8 +114,8 @@ If a legacy workflow still expects a done marker, derive it from the session ID:
 ```
 
 Treat done markers as compatibility hints only. Canonical completion should come
-from harnex terminal telemetry (`harnex wait` / `harnex status --json` / summary
-rows in `.harnex/dispatch.jsonl`).
+from harnex terminal telemetry (`harnex wait` / `harnex status --json` / v2
+`dispatch_end` rows in `.harnex/dispatch.jsonl`).
 
 When a brief asks for a completion marker, make it one line and include the
 highest-signal result: tests passed, review clean, or the blocking issue.

data/lib/harnex/adapters/base.rb

@@ -37,6 +37,16 @@ module Harnex
         nil
       end
 
+      # Whether the usage this adapter captures reports input_tokens
+      # INCLUSIVE of cached_tokens. Depends on the capture path, not just
+      # the provider: codex app-server JSON reports cached as a subset of
+      # input, while the codex TUI line the PTY adapter scrapes shows
+      # non-cached input with cached as a separate additive count. Feeds
+      # Pricing.compute (plan 33 Phase 2).
+      def usage_input_includes_cached?
+        false
+      end
+
       # Probes `<base_command.first> --version` with a short timeout and
       # memoizes the result for the adapter's lifetime. Returns nil when
       # the binary is missing, exits non-zero, or stalls past the timeout.

data/lib/harnex/adapters/codex_appserver.rb

@@ -59,6 +59,7 @@ module Harnex
         @initial_prompt = extract_initial_prompt(extra_args)
         @client = nil
         @thread_id = nil
+        @current_model = nil
         @current_turn_id = nil
         @state = :disconnected
         @last_completed_at = nil
@@ -78,6 +79,21 @@ module Harnex
         true
       end
 
+      # thread/tokenUsage/updated totals report cachedInputTokens as a
+      # subset of inputTokens (verified against a live captured row:
+      # input + output == total exactly, cached < input).
+      def usage_input_includes_cached?
+        true
+      end
+
+      # Effective model reported by the app-server's thread/start or
+      # thread/resume response (schema-required field). Feeds
+      # Session#summary_model so price-table cost can resolve without the
+      # caller passing `--meta '{"model": ...}'`.
+      def current_model
+        @current_model
+      end
+
       def context_telemetry_supported?
         true
       end
@@ -202,6 +218,7 @@ module Harnex
         ensure_open!
         result = @client.request("thread/resume", { threadId: thread_id })
         @thread_id = thread_id
+        @current_model = extract_model(result) || @current_model
         @state = :prompt
         result
       end
@@ -279,6 +296,7 @@ module Harnex
 
         result = @client.request("thread/start", {})
         @thread_id = extract_thread_id(result)
+        @current_model = extract_model(result) || @current_model
       end
 
       def extract_thread_id(payload)
@@ -287,6 +305,13 @@ module Harnex
         payload.dig("thread", "id")
       end
 
+      def extract_model(payload)
+        return nil unless payload.is_a?(Hash)
+
+        model = payload["model"]
+        model.is_a?(String) && !model.empty? ? model : nil
+      end
+
       def extract_initial_prompt(extra_args)
         return nil unless extra_args.is_a?(Array)