harnex 0.7.9 → 0.7.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56d9111b2ab4f12716444ecef721331d9878a4485a4b305ecd4a1ad7546d4b77
-  data.tar.gz: 3f727b473455245ba916cabe1202a6abc2d6c5a07f4ae257b04898a296d9149c
+  metadata.gz: 2af8afe53ccea3fb668e920809da3fdbcd523ee5eef0179bcdd84f026077cff1
+  data.tar.gz: f675d4a401f703bf52adc88ce352fec04d2090533c3249bd0ac05e6828d030f0
 SHA512:
-  metadata.gz: a2a87ae57e9ddc34bb85805ea9e07f3523691cf979361f687f4c3c68534c0b9f7c9e276b83d8d28a91a15bc52913ef41e1e36b1993127c97c68c87aa75af5766
-  data.tar.gz: 92084ab180df22e16316226adaaa8170b0ab71ceeda1e4de3f097873ed6ecb8e22f8bca7b06b3c78b0a1a0c36d8b18c4b13dcebb7126aecd4523034fead38399
+  metadata.gz: cda7d84fd1f80c9526529b03293623eb16f76a78872e5e29640896be76f79a448ab3bf8f4c92c74c56b8f88b814739b7fbd201a6c91ba749d22ecdc5cf8a720e
+  data.tar.gz: bc6704fc2a86a01e61c1a431fd96781bbaf178029679bc1b5c64be699f82c49bbf8b27d4f921c0d7547752eadc2dc61cffc1bc946b99d0cd5d79dd46a0de77af

data/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.7.10] - 2026-07-10 | 10:57 PM | IST
+
+### Added
+
+- `harnex run --artifact-report PATH` / `--validation-report PATH` now expose a
+  worker-writable `harnex.artifact_report.v1` sidecar path via
+  `HARNEX_ARTIFACT_REPORT_PATH` and `HARNEX_VALIDATION_REPORT_PATH`, ingest the
+  report at dispatch finalization, and append compact top-level
+  `artifact_report`, `validation`, and `artifacts` blocks to the dispatch
+  summary row.
+
+### Changed
+
+- Dispatch telemetry docs, README, and the packaged dispatch agents-guide now
+  document sidecar proof while keeping plain-text `koder/` artifacts canonical.
+
+### Fixed
+
+- Missing, malformed, unsupported-schema, and oversized artifact reports now
+  fail soft with `artifact_report.ingest_status` warning telemetry instead of
+  crashing or changing the wrapped process exit code.
+
 ## [0.7.9] - 2026-07-10 | 10:33 PM | IST
 
 ### Added

data/README.md

@@ -268,6 +268,22 @@ 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:
+
+```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' \
+  --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.
+
 Those declared values are copied into summary `meta`. Terminal summary
 `actual` records timing, exit classification, token usage when the adapter can
 capture it, adapter-reported `cost_usd` when reliably available, git deltas,

data/guides/01_dispatch.md

@@ -95,6 +95,22 @@ 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:
+
+```bash
+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' \
+  --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.
+
 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/lib/harnex/artifact_report.rb

@@ -0,0 +1,221 @@
+require "digest"
+require "json"
+
+module Harnex
+  module ArtifactReport
+    SCHEMA = "harnex.artifact_report.v1"
+    MAX_BYTES = 256 * 1024
+    MAX_ARTIFACTS = 50
+    MAX_COMMANDS = 50
+    MAX_CANONICAL_ARTIFACTS = 50
+    MAX_EVIDENCE_ITEMS = 20
+    MAX_STRING_LENGTH = 2_000
+
+    module_function
+
+    def ingest(path)
+      report_path = File.expand_path(path.to_s)
+      return missing(report_path) unless File.file?(report_path)
+
+      bytes = File.size(report_path)
+      sha256 = file_sha256(report_path)
+      if bytes > MAX_BYTES
+        return warning(
+          report_path,
+          bytes: bytes,
+          sha256: sha256,
+          ingest_status: "oversized",
+          warning: "artifact report is #{bytes} bytes; max is #{MAX_BYTES} bytes"
+        )
+      end
+
+      parsed = JSON.parse(File.read(report_path, mode: "rb"))
+      unless parsed.is_a?(Hash)
+        return warning(
+          report_path,
+          bytes: bytes,
+          sha256: sha256,
+          ingest_status: "malformed",
+          warning: "artifact report must be a JSON object"
+        )
+      end
+
+      schema = parsed["schema"].to_s
+      unless schema == SCHEMA
+        return warning(
+          report_path,
+          bytes: bytes,
+          sha256: sha256,
+          ingest_status: "unsupported_schema",
+          schema: schema.empty? ? nil : bounded_string(schema),
+          warning: "unsupported artifact report schema #{schema.inspect}; expected #{SCHEMA}"
+        )
+      end
+
+      build_payload(report_path, bytes: bytes, sha256: sha256, report: parsed)
+    rescue JSON::ParserError => e
+      warning(
+        report_path,
+        bytes: safe_file_size(report_path),
+        sha256: safe_file_sha256(report_path),
+        ingest_status: "malformed",
+        warning: "malformed artifact report JSON: #{bounded_string(e.message)}"
+      )
+    rescue StandardError => e
+      warning(
+        report_path,
+        bytes: safe_file_size(report_path),
+        sha256: safe_file_sha256(report_path),
+        ingest_status: "error",
+        warning: "artifact report ingest failed: #{bounded_string(e.message)}"
+      )
+    end
+
+    def build_payload(path, bytes:, sha256:, report:)
+      artifacts = compact_artifacts(report["artifacts"])
+      validation = compact_validation(report["validation"])
+      payload = {
+        "artifact_report" => metadata(
+          path,
+          bytes: bytes,
+          sha256: sha256,
+          ingest_status: "ok",
+          schema: SCHEMA
+        ).merge(
+          "report_status" => bounded_string_or_nil(report["status"]),
+          "canonical_artifacts" => string_array(report["canonical_artifacts"], max_items: MAX_CANONICAL_ARTIFACTS),
+          "artifact_count" => artifacts.length
+        )
+      }
+      payload["validation"] = validation if validation
+      payload["artifacts"] = artifacts unless artifacts.empty?
+      payload
+    end
+
+    def missing(path)
+      warning(
+        path,
+        bytes: nil,
+        sha256: nil,
+        ingest_status: "missing",
+        warning: "artifact report not found"
+      )
+    end
+
+    def warning(path, bytes:, sha256:, ingest_status:, warning:, schema: nil)
+      report = metadata(path, bytes: bytes, sha256: sha256, ingest_status: ingest_status, schema: schema)
+      report["warning"] = bounded_string(warning)
+      { "artifact_report" => report }
+    end
+
+    def metadata(path, bytes:, sha256:, ingest_status:, schema: nil)
+      {
+        "path" => path.to_s,
+        "bytes" => bytes,
+        "sha256" => sha256,
+        "ingest_status" => ingest_status,
+        "schema" => schema
+      }
+    end
+
+    def compact_validation(value)
+      return nil unless value.is_a?(Hash)
+
+      payload = {}
+      payload["status"] = bounded_string_or_nil(value["status"])
+      payload["commands"] = compact_commands(value["commands"])
+      payload["final_reported"] = !!value["final_reported"] if value.key?("final_reported")
+      payload.delete_if { |_key, v| v.nil? || v == [] }
+      payload.empty? ? nil : payload
+    end
+
+    def compact_commands(value)
+      Array(value).first(MAX_COMMANDS).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        compact = {
+          "cmd" => bounded_string_or_nil(entry["cmd"]),
+          "exit_code" => integer_or_nil(entry["exit_code"]),
+          "status" => bounded_string_or_nil(entry["status"]),
+          "duration_s" => finite_float_or_nil(entry["duration_s"])
+        }
+        compact.delete_if { |_key, v| v.nil? }
+        compact.empty? ? nil : compact
+      end
+    end
+
+    def compact_artifacts(value)
+      Array(value).first(MAX_ARTIFACTS).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        compact = {
+          "type" => bounded_string_or_nil(entry["type"]),
+          "summary" => bounded_string_or_nil(entry["summary"]),
+          "evidence" => string_array(entry["evidence"], max_items: MAX_EVIDENCE_ITEMS),
+          "confidence" => finite_float_or_nil(entry["confidence"]),
+          "canonical_ref" => bounded_string_or_nil(entry["canonical_ref"])
+        }
+        compact.delete_if { |_key, v| v.nil? || v == [] }
+        compact.empty? ? nil : compact
+      end
+    end
+
+    def string_array(value, max_items:)
+      Array(value).first(max_items).filter_map do |item|
+        text = bounded_string_or_nil(item)
+        text unless text.nil? || text.empty?
+      end
+    end
+
+    def bounded_string_or_nil(value)
+      return nil if value.nil?
+
+      bounded_string(value)
+    end
+
+    def bounded_string(value)
+      text = value.to_s
+      return text if text.length <= MAX_STRING_LENGTH
+
+      text[0, MAX_STRING_LENGTH]
+    end
+
+    def integer_or_nil(value)
+      return nil if value.nil?
+
+      Integer(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def finite_float_or_nil(value)
+      return nil if value.nil?
+
+      number = Float(value)
+      number.finite? ? number : nil
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def file_sha256(path)
+      digest = Digest::SHA256.new
+      File.open(path, "rb") do |file|
+        buffer = +""
+        digest.update(buffer) while file.read(16 * 1024, buffer)
+      end
+      digest.hexdigest
+    end
+
+    def safe_file_size(path)
+      File.size(path) if File.file?(path)
+    rescue StandardError
+      nil
+    end
+
+    def safe_file_sha256(path)
+      file_sha256(path) if File.file?(path)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/harnex/commands/run.rb

@@ -8,11 +8,11 @@ module Harnex
     KNOWN_FLAGS = %w[
       --id --description --detach --tmux --host --port --watch --watch-file
       --stall-after --max-resumes --preset --context --meta --summary-out
-      --cwd --root --timeout --inbox-ttl --auto-stop --fast --legacy-pty --help
+      --artifact-report --validation-report --cwd --root --timeout --inbox-ttl --auto-stop --fast --legacy-pty --help
     ].freeze
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
-      --max-resumes --preset --context --meta --summary-out --cwd --root --timeout --inbox-ttl
+      --max-resumes --preset --context --meta --summary-out --artifact-report --validation-report --cwd --root --timeout --inbox-ttl
     ].freeze
 
     def self.usage(program_name = "harnex run")
@@ -37,6 +37,10 @@ module Harnex
                              Default Codex runs force service_tier="flex".
           --meta JSON        Attach parsed JSON metadata to the started event
           --summary-out PATH Append dispatch telemetry summary JSONL to PATH
+          --artifact-report PATH
+                             Worker-written harnex.artifact_report.v1 JSON sidecar to ingest at exit
+          --validation-report PATH
+                             Alias for --artifact-report; also exposed as HARNEX_VALIDATION_REPORT_PATH
           --cwd DIR          Run the wrapped agent from DIR and use DIR as the session root
           --root DIR         Override harnex session/root attribution without changing child cwd
           --timeout SECS     Max seconds to wait for detached registration (default: #{DEFAULT_TIMEOUT})
@@ -61,6 +65,7 @@ module Harnex
           #{program_name} pi --id pi-i-42 --tmux pi-i-42 --context "Read /tmp/task-impl-42.md" --auto-stop
           #{program_name} pi --id pi-i-42 --watch --preset impl --context "Read /tmp/task-impl-42.md"
           #{program_name} codex --cwd /tmp/public-bundle --id eval-001 --context "Read README.md and write OUTPUT.md" --auto-stop
+          #{program_name} pi --id pi-i-52 --artifact-report .harnex/reports/pi-i-52.json --context "Write proof to $HARNEX_ARTIFACT_REPORT_PATH" --auto-stop
           #{program_name} claude --id cl-r-42 --tmux cl-r-42 --description "Review task 42"
 
         Gotchas:
@@ -91,6 +96,7 @@ module Harnex
         context: nil,
         meta: nil,
         summary_out: nil,
+        artifact_report: nil,
         cwd: nil,
         root: nil,
         auto_stop: false,
@@ -117,6 +123,7 @@ module Harnex
 
       repo_root = resolve_run_root(cli_name, child_args)
       @options[:summary_out] = resolve_summary_out(repo_root)
+      @options[:artifact_report] = resolve_artifact_report(repo_root)
       @options[:id] ||= Harnex.generate_id(repo_root)
       validate_unique_id!(repo_root)
       effective_child_args = apply_context(apply_codex_service_tier(cli_name, child_args))
@@ -178,6 +185,7 @@ module Harnex
       tmux_cmd << "--auto-stop" if @options[:auto_stop]
       tmux_cmd += ["--meta", JSON.generate(@options[:meta])] if @options[:meta]
       tmux_cmd += ["--summary-out", @options[:summary_out]] if @options[:summary_out]
+      tmux_cmd += ["--artifact-report", @options[:artifact_report]] if @options[:artifact_report]
       tmux_cmd += ["--cwd", @options[:cwd]] if @options[:cwd]
       tmux_cmd += ["--root", @options[:root]] if @options[:root]
       tmux_cmd += ["--inbox-ttl", @options[:inbox_ttl].to_s]
@@ -287,6 +295,7 @@ module Harnex
         description: @options[:description],
         meta: @options[:meta],
         summary_out: @options[:summary_out],
+        artifact_report_path: @options[:artifact_report],
         inbox_ttl: @options[:inbox_ttl],
         auto_stop: @options[:auto_stop],
         launch_cwd: history_cwd,
@@ -468,6 +477,13 @@ module Harnex
           @options[:summary_out] = required_option_value(arg, argv[index])
         when /\A--summary-out=(.+)\z/
           @options[:summary_out] = required_option_value("--summary-out", Regexp.last_match(1))
+        when "--artifact-report", "--validation-report"
+          index += 1
+          @options[:artifact_report] = required_option_value(arg, argv[index])
+        when /\A--artifact-report=(.+)\z/
+          @options[:artifact_report] = required_option_value("--artifact-report", Regexp.last_match(1))
+        when /\A--validation-report=(.+)\z/
+          @options[:artifact_report] = required_option_value("--validation-report", Regexp.last_match(1))
         when "--cwd"
           index += 1
           @options[:cwd] = expand_existing_directory(required_option_value(arg, argv[index]), option_name: arg)
@@ -546,7 +562,7 @@ module Harnex
           nil
         when *VALUE_FLAGS
           index += 1
-        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|summary-out|cwd|root|timeout|inbox-ttl)=/
+        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|summary-out|artifact-report|validation-report|cwd|root|timeout|inbox-ttl)=/
           nil
         when /\A--preset=/
           nil
@@ -565,7 +581,7 @@ module Harnex
         arg.start_with?(
           "--id=", "--description=", "--tmux=", "--host=", "--port=", "--watch=", "--watch-file=",
           "--stall-after=", "--max-resumes=", "--preset=", "--context=", "--meta=", "--summary-out=",
-          "--cwd=", "--root=", "--timeout=", "--inbox-ttl="
+          "--artifact-report=", "--validation-report=", "--cwd=", "--root=", "--timeout=", "--inbox-ttl="
         )
     end
 
@@ -645,6 +661,15 @@ module Harnex
       File.expand_path(configured, repo_root)
     end
 
+    def resolve_artifact_report(repo_root)
+      configured = @options[:artifact_report]
+      return nil if configured.nil?
+
+      path = File.expand_path(configured, repo_root)
+      FileUtils.mkdir_p(File.dirname(path))
+      path
+    end
+
     def default_inbox_ttl
       value = ENV["HARNEX_INBOX_TTL"]
       return Inbox::DEFAULT_TTL.to_f if value.nil? || value.strip.empty?

data/lib/harnex/runtime/session.rb

@@ -59,10 +59,10 @@ module Harnex
     end
 
     attr_reader :repo_root, :launch_cwd, :child_cwd, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch,
-                :inbox, :description, :meta, :summary_out, :output_log_path, :events_log_path,
+                :inbox, :description, :meta, :summary_out, :artifact_report_path, :output_log_path, :events_log_path,
                 :started_at, :ended_at, :exit_code, :term_signal
 
-    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, summary_out: nil, inbox_ttl: Inbox::DEFAULT_TTL, auto_stop: false, launch_cwd: nil, child_cwd: nil)
+    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, summary_out: nil, artifact_report_path: nil, inbox_ttl: Inbox::DEFAULT_TTL, auto_stop: false, launch_cwd: nil, child_cwd: nil)
       @adapter = adapter
       @command = command
       @repo_root = repo_root
@@ -76,6 +76,9 @@ module Harnex
       @meta = meta
       @summary_out = summary_out.to_s.strip
       @summary_out = nil if @summary_out.empty?
+      @artifact_report_path = artifact_report_path.to_s.strip
+      @artifact_report_path = nil if @artifact_report_path.empty?
+      @artifact_report_path = File.expand_path(@artifact_report_path, repo_root) if @artifact_report_path
       @registry_path = Harnex.registry_path(repo_root, @id)
       @output_log_path = Harnex.output_log_path(repo_root, @id)
       @events_log_path = Harnex.events_log_path(repo_root, @id)
@@ -772,6 +775,11 @@ module Harnex
         "HARNEX_SESSION_REPO_ROOT" => repo_root
       }
       env["HARNEX_DESCRIPTION"] = description if description
+      if artifact_report_path
+        env["HARNEX_ARTIFACT_REPORT_PATH"] = artifact_report_path
+        env["HARNEX_VALIDATION_REPORT_PATH"] = artifact_report_path
+        env["HARNEX_ARTIFACT_REPORT_SCHEMA"] = Harnex::ArtifactReport::SCHEMA
+      end
       env["HARNEX_SPAWNER_PANE"] = ENV["TMUX_PANE"] if ENV["TMUX_PANE"]
       env
     end
@@ -1157,11 +1165,13 @@ module Harnex
     end
 
     def build_summary_record
-      {
+      record = {
         meta: build_summary_meta,
         predicted: summary_predicted_payload,
         actual: build_summary_actual
       }
+      record.merge!(artifact_report_summary) if artifact_report_path
+      record
     end
 
     def build_summary_meta
@@ -1297,6 +1307,21 @@ module Harnex
       predicted.is_a?(Hash) ? predicted : {}
     end
 
+    def artifact_report_summary
+      Harnex::ArtifactReport.ingest(artifact_report_path)
+    rescue StandardError => e
+      {
+        "artifact_report" => {
+          "path" => artifact_report_path,
+          "bytes" => nil,
+          "sha256" => nil,
+          "ingest_status" => "error",
+          "schema" => nil,
+          "warning" => "artifact report ingest failed: #{e.message}"
+        }
+      }
+    end
+
     def meta_hash
       meta.is_a?(Hash) ? meta : {}
     end

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.7.9"
+  VERSION = "0.7.10"
   RELEASE_DATE = "2026-07-10"
 end

data/lib/harnex.rb

@@ -6,6 +6,7 @@ require_relative "harnex/version"
 require_relative "harnex/core"
 require_relative "harnex/dispatch_history"
 require_relative "harnex/terminal_status"
+require_relative "harnex/artifact_report"
 require_relative "harnex/watcher"
 require_relative "harnex/adapters"
 require_relative "harnex/runtime/session_state"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.7.9
+  version: 0.7.10
 platform: ruby
 authors:
 - Jikku Jose
@@ -40,6 +40,7 @@ files:
 - lib/harnex/adapters/generic.rb
 - lib/harnex/adapters/opencode.rb
 - lib/harnex/adapters/pi.rb
+- lib/harnex/artifact_report.rb
 - lib/harnex/cli.rb
 - lib/harnex/codex/app_server/client.rb
 - lib/harnex/commands/agents_guide.rb