harnex 0.7.13 → 0.7.14

data/lib/harnex/commands/artifact_report.rb

@@ -0,0 +1,94 @@
+require "json"
+require "optparse"
+
+module Harnex
+  class ArtifactReportCommand
+    def self.usage(program_name = "harnex artifact-report")
+      <<~TEXT
+        Usage:
+          #{program_name} init PATH [--force]
+          #{program_name} validate PATH [--final]
+
+        Commands:
+          init       Write a bounded harnex.artifact_report.v1 skeleton
+          validate   Validate schema and field shapes without printing report data
+
+        Options:
+          --final    Require an accepted/no_change final outcome, passing proof,
+                     and validation.final_reported=true
+          --force    Replace an existing file during init
+          -h, --help Show this help
+
+        Both commands print machine-readable JSON. `validate` exits 0 only when
+        the requested contract is satisfied; diagnostics contain field paths and
+        shape errors, never report payloads or transcripts.
+      TEXT
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      command = @argv.shift
+      case command
+      when "init"
+        run_init(@argv)
+      when "validate"
+        run_validate(@argv)
+      when nil, "help", "-h", "--help"
+        puts self.class.usage
+        0
+      else
+        raise OptionParser::ParseError, "unknown artifact-report command #{command.inspect}"
+      end
+    end
+
+    private
+
+    def run_init(argv)
+      options = { force: false, help: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: harnex artifact-report init PATH [--force]"
+        opts.on("--force", "Replace an existing report") { options[:force] = true }
+        opts.on("-h", "--help", "Show help") { options[:help] = true }
+      end
+      parser.parse!(argv)
+      return print_help if options[:help]
+
+      path = exactly_one_path!(argv, parser)
+      report_path = ArtifactReport.initialize_file(path, force: options[:force])
+      result = ArtifactReport.validate(report_path)
+      puts JSON.generate(result.public_payload(final: false).merge("created" => true))
+      result.ok ? 0 : 1
+    end
+
+    def run_validate(argv)
+      options = { final: false, help: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: harnex artifact-report validate PATH [--final]"
+        opts.on("--final", "Require accepted final proof") { options[:final] = true }
+        opts.on("-h", "--help", "Show help") { options[:help] = true }
+      end
+      parser.parse!(argv)
+      return print_help if options[:help]
+
+      path = exactly_one_path!(argv, parser)
+      result = ArtifactReport.validate(path, final: options[:final])
+      puts JSON.generate(result.public_payload(final: options[:final]))
+      result.ok ? 0 : 1
+    end
+
+    def exactly_one_path!(argv, parser)
+      raise OptionParser::MissingArgument, "PATH" if argv.empty?
+      raise OptionParser::InvalidArgument, "expected exactly one PATH\n#{parser}" unless argv.length == 1
+
+      argv.first
+    end
+
+    def print_help
+      puts self.class.usage
+      0
+    end
+  end
+end

data/lib/harnex/commands/orchestration.rb

@@ -0,0 +1,170 @@
+require "json"
+require "optparse"
+
+module Harnex
+  class OrchestrationCommand
+    def self.usage(program_name = "harnex orchestration")
+      <<~TEXT
+        Usage:
+          #{program_name} sample --out PATH --run-id ID --generation-id ID [options]
+          #{program_name} report --dispatch PATH --run-id ID [--samples PATH] [--json]
+
+        Sample options:
+          --project-id ID
+          --queue-id ID
+          --session-id ID
+          --event NAME                  sample, generation_started, generation_finished, rotation, recovery, or compaction
+          --ts ISO8601
+          --context-status STATUS       observed, estimated, unsupported, missing, or zero
+          --context-tokens N
+          --context-window-tokens N
+          --context-percent N
+          --context-peak-tokens N
+          --context-peak-percent N
+          --usage-status STATUS         observed, estimated, unsupported, missing, or zero
+          --usage-input-tokens N
+          --usage-output-tokens N
+          --usage-cached-input-tokens N
+          --usage-reasoning-tokens N
+          --usage-total-tokens N
+          --usage-cost-usd N
+          --usage-cost-source TEXT
+          --tool-calls N
+          --compactions N
+          --rotation-reason TEXT
+
+        Report options:
+          --dispatch PATH               Dispatch summary JSONL
+          --samples PATH                External primary sample JSONL
+          --run-id ID                   Logical orchestration run id
+          --json                        Output the full report JSON
+          -h, --help                    Show this help
+      TEXT
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      subcommand = @argv.shift
+      case subcommand
+      when "sample"
+        run_sample(@argv)
+      when "report"
+        run_report(@argv)
+      when "-h", "--help", nil
+        puts self.class.usage
+        0
+      else
+        raise OptionParser::ParseError, "unknown orchestration subcommand #{subcommand.inspect}"
+      end
+    end
+
+    private
+
+    def run_sample(argv)
+      options = {
+        context: {},
+        usage: {}
+      }
+      sample_parser(options).parse!(argv)
+      if options.delete(:help)
+        puts self.class.usage
+        return 0
+      end
+      path = required_option(options.delete(:out), "--out")
+      options["orchestration_run_id"] = required_option(options.delete(:run_id), "--run-id")
+      options["generation_id"] = required_option(options.delete(:generation_id), "--generation-id")
+      sample = Harnex::Orchestration.append_sample(path, options)
+      puts JSON.generate("ok" => true, "path" => path, "sample" => sample)
+      0
+    end
+
+    def run_report(argv)
+      options = { json: false }
+      report_parser(options).parse!(argv)
+      if options[:help]
+        puts self.class.usage
+        return 0
+      end
+      report = Harnex::Orchestration.report(
+        dispatch_path: required_option(options[:dispatch], "--dispatch"),
+        samples_path: options[:samples],
+        run_id: required_option(options[:run_id], "--run-id")
+      )
+      if options[:json]
+        puts JSON.generate(report)
+      else
+        puts render_report(report)
+      end
+      0
+    end
+
+    def sample_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: harnex orchestration sample --out PATH --run-id ID --generation-id ID [options]"
+        opts.on("--out PATH") { |value| options[:out] = value }
+        opts.on("--run-id ID") { |value| options[:run_id] = value }
+        opts.on("--generation-id ID") { |value| options[:generation_id] = value }
+        opts.on("--project-id ID") { |value| options["project_id"] = value }
+        opts.on("--queue-id ID") { |value| options["queue_id"] = value }
+        opts.on("--session-id ID") { |value| options["session_id"] = value }
+        opts.on("--event NAME") { |value| options["event"] = value }
+        opts.on("--ts ISO8601") { |value| options["ts"] = value }
+        opts.on("--context-status STATUS") { |value| options[:context]["status"] = value }
+        opts.on("--context-tokens N") { |value| options[:context]["terminal_tokens"] = value }
+        opts.on("--context-window-tokens N") { |value| options[:context]["window_tokens"] = value }
+        opts.on("--context-percent N") { |value| options[:context]["terminal_percent"] = value }
+        opts.on("--context-peak-tokens N") { |value| options[:context]["peak_tokens"] = value }
+        opts.on("--context-peak-percent N") { |value| options[:context]["peak_percent"] = value }
+        opts.on("--usage-status STATUS") { |value| options[:usage]["status"] = value }
+        opts.on("--usage-input-tokens N") { |value| options[:usage]["input_tokens"] = value }
+        opts.on("--usage-output-tokens N") { |value| options[:usage]["output_tokens"] = value }
+        opts.on("--usage-cached-input-tokens N") { |value| options[:usage]["cached_input_tokens"] = value }
+        opts.on("--usage-reasoning-tokens N") { |value| options[:usage]["reasoning_tokens"] = value }
+        opts.on("--usage-total-tokens N") { |value| options[:usage]["total_tokens"] = value }
+        opts.on("--usage-cost-usd N") { |value| options[:usage]["cost_usd"] = value }
+        opts.on("--usage-cost-source TEXT") { |value| options[:usage]["cost_source"] = value }
+        opts.on("--tool-calls N") { |value| options["tool_calls"] = value }
+        opts.on("--compactions N") { |value| options["compactions"] = value }
+        opts.on("--rotation-reason TEXT") { |value| options["rotation_reason"] = value }
+        opts.on("-h", "--help") { options[:help] = true }
+      end
+    end
+
+    def report_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: harnex orchestration report --dispatch PATH --run-id ID [options]"
+        opts.on("--dispatch PATH") { |value| options[:dispatch] = value }
+        opts.on("--samples PATH") { |value| options[:samples] = value }
+        opts.on("--run-id ID") { |value| options[:run_id] = value }
+        opts.on("--json") { options[:json] = true }
+        opts.on("-h", "--help") { options[:help] = true }
+      end
+    end
+
+    def required_option(value, name)
+      text = value.to_s.strip
+      raise OptionParser::MissingArgument, name if text.empty?
+
+      text
+    end
+
+    def render_report(report)
+      primary = report.fetch("primary")
+      workers = report.fetch("workers")
+      ratios = report.fetch("ratios")
+      [
+        "Run: #{report.fetch('orchestration_run_id')}",
+        "Primary: generations=#{primary.fetch('generation_count')} usage=#{primary.dig('usage', 'status')} total_tokens=#{format_value(primary.dig('usage', 'total_tokens'))} peak_context=#{format_value(primary.dig('context', 'peak_tokens'))} tool_calls=#{primary.fetch('tool_calls')}",
+        "Workers: dispatches=#{workers.fetch('dispatches')} usage=#{workers.dig('usage', 'status')} active_s=#{workers.fetch('active_s')} accepted=#{workers.dig('outcomes', 'accepted')} rejected=#{workers.dig('outcomes', 'rejected')} blocked=#{workers.dig('outcomes', 'blocked')} unknown=#{workers.dig('outcomes', 'unknown')}",
+        "Ratios: primary_tokens_per_accepted_entry=#{format_value(ratios.fetch('primary_total_tokens_per_accepted_entry'))} primary_tool_calls_per_accepted_entry=#{format_value(ratios.fetch('primary_tool_calls_per_accepted_entry'))}"
+      ].join("\n")
+    end
+
+    def format_value(value)
+      value.nil? ? "-" : value
+    end
+  end
+end

data/lib/harnex/commands/run.rb

@@ -19,7 +19,12 @@ module Harnex
       "--effort" => "effort",
       "--parent-dispatch-id" => "parent_dispatch_id",
       "--parent-attempt-id" => "parent_attempt_id",
-      "--attempt-kind" => "attempt_kind"
+      "--attempt-kind" => "attempt_kind",
+      "--orchestration-run-id" => "orchestration_run_id",
+      "--orchestration-generation-id" => "orchestration_generation_id",
+      "--orchestration-role" => "orchestration_role",
+      "--orchestration-session-id" => "orchestration_session_id",
+      "--orchestration-rotation-reason" => "orchestration_rotation_reason"
     }.freeze
     TELEMETRY_KEYS_TO_FLAGS = TELEMETRY_FLAGS.invert.freeze
     TELEMETRY_EQUALS_PREFIXES = TELEMETRY_FLAGS.keys.map { |flag| "#{flag}=" }.freeze
@@ -28,7 +33,7 @@ module Harnex
       --id --description --detach --tmux --host --port --watch --watch-file
       --stall-after --max-resumes --preset --context --meta --summary-out
       --artifact-report --validation-report --cwd --root --timeout --inbox-ttl
-      --require-attribution --auto-stop --fast --legacy-pty --help
+      --require-artifact-report --require-attribution --auto-stop --fast --legacy-pty --help
     ].concat(TELEMETRY_FLAGS.keys).freeze
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
@@ -53,7 +58,7 @@ module Harnex
           --preset NAME      Watch preset: impl, plan, gate (requires --watch)
           --watch-file PATH  Auto-send a file-change hook on modification
           --context TEXT     Inject as the initial prompt (prepends session header)
-          --auto-stop        Stop after the first task completion from --context
+          --auto-stop        Stop after the first accepted task completion from --context
           --fast             (codex only) Use Codex service_tier="fast".
                              Default Codex runs force service_tier="flex".
           --meta JSON        Attach parsed JSON metadata to the started event
@@ -62,6 +67,9 @@ module Harnex
                              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
+          --require-artifact-report
+                             Fail closed unless PATH contains accepted final proof;
+                             requires --artifact-report or --validation-report
           --project-id ID    Queue telemetry project id (first-class flags override --meta)
           --queue-id ID      Queue telemetry queue id
           --entry-id ID      Queue telemetry entry id
@@ -79,6 +87,16 @@ module Harnex
                              Parent attempt id for retry/fix/review joins
           --attempt-kind KIND
                              initial, retry, fix, review, or superseding (default: initial)
+          --orchestration-run-id ID
+                             Logical primary-orchestrator run id for queue rollups
+          --orchestration-generation-id ID
+                             Primary generation id after rotation/recovery boundaries
+          --orchestration-role ROLE
+                             primary or worker; defaults to worker in rollups when omitted
+          --orchestration-session-id ID
+                             External primary session id to preserve in rollups
+          --orchestration-rotation-reason TEXT
+                             Clean rotation/recovery reason for the generation
           --require-attribution
                              Fail before launch unless project/phase/intent and one work id are present
           --cwd DIR          Run the wrapped agent from DIR and use DIR as the session root
@@ -94,7 +112,9 @@ module Harnex
         Notes:
           Compatibility: `--watch PATH` and `--watch=PATH` still configure file-hook mode.
           Bare `--watch` enables the babysitter.
-          --auto-stop requires --context and fires once after the first completion.
+          --auto-stop requires --context. Structured Codex turns only count as
+          accepted completion after activity, Git delta, or accepted sidecar proof.
+          --require-artifact-report makes sidecar validation part of the run verdict.
           Explicit --stall-after/--max-resumes values override --preset defaults.
           CLIs with smart prompt detection: #{Adapters.known.join(', ')}
           Any other CLI name is launched with generic wrapping.
@@ -140,6 +160,7 @@ module Harnex
         require_attribution: false,
         summary_out: nil,
         artifact_report: nil,
+        require_artifact_report: false,
         cwd: nil,
         root: nil,
         auto_stop: false,
@@ -163,8 +184,10 @@ module Harnex
 
       raise OptionParser::MissingArgument, "cli" if cli_name.nil?
       validate_auto_stop_context!
+      validate_required_artifact_report!
       apply_telemetry_options!
       validate_attempt_metadata!
+      validate_orchestration_metadata!
       validate_required_attribution!
 
       repo_root = resolve_run_root(cli_name, child_args)
@@ -237,6 +260,7 @@ module Harnex
       tmux_cmd << "--require-attribution" if @options[:require_attribution]
       tmux_cmd += ["--summary-out", @options[:summary_out]] if @options[:summary_out]
       tmux_cmd += ["--artifact-report", @options[:artifact_report]] if @options[:artifact_report]
+      tmux_cmd << "--require-artifact-report" if @options[:require_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]
@@ -347,6 +371,7 @@ module Harnex
         meta: @options[:meta],
         summary_out: @options[:summary_out],
         artifact_report_path: @options[:artifact_report],
+        require_artifact_report: @options[:require_artifact_report],
         inbox_ttl: @options[:inbox_ttl],
         auto_stop: @options[:auto_stop],
         launch_cwd: history_cwd,
@@ -539,6 +564,8 @@ module Harnex
         when "--artifact-report", "--validation-report"
           index += 1
           @options[:artifact_report] = required_option_value(arg, argv[index])
+        when "--require-artifact-report"
+          @options[:require_artifact_report] = true
         when /\A--artifact-report=(.+)\z/
           @options[:artifact_report] = required_option_value("--artifact-report", Regexp.last_match(1))
         when /\A--validation-report=(.+)\z/
@@ -619,7 +646,7 @@ module Harnex
         case arg
         when "--"
           return false
-        when "-h", "--help", "--detach", "--tmux", "--auto-stop", "--require-attribution", "--fast", "--legacy-pty"
+        when "-h", "--help", "--detach", "--tmux", "--auto-stop", "--require-artifact-report", "--require-attribution", "--fast", "--legacy-pty"
           nil
         when /\A--tmux=/
           nil
@@ -676,6 +703,14 @@ module Harnex
       raise OptionParser::InvalidOption, "harnex run: --auto-stop requires --context"
     end
 
+    def validate_required_artifact_report!
+      return unless @options[:require_artifact_report]
+      return unless @options[:artifact_report].to_s.strip.empty?
+
+      raise OptionParser::InvalidOption,
+            "harnex run: --require-artifact-report requires --artifact-report PATH"
+    end
+
     def apply_telemetry_options!
       explicit = @options[:telemetry]
       return if explicit.empty? && @options[:meta].is_a?(Hash)
@@ -693,6 +728,15 @@ module Harnex
             "harnex run: --attempt-kind must be one of #{Session::ATTEMPT_KINDS.join(', ')}"
     end
 
+    def validate_orchestration_metadata!
+      metadata = @options[:meta].is_a?(Hash) ? @options[:meta] : {}
+      role = metadata["orchestration_role"].to_s
+      return if role.empty? || Orchestration::ROLES.include?(role)
+
+      raise OptionParser::InvalidOption,
+            "harnex run: --orchestration-role must be one of #{Orchestration::ROLES.join(', ')}"
+    end
+
     def validate_required_attribution!
       return unless @options[:require_attribution]
 

data/lib/harnex/commands/wait.rb

@@ -215,8 +215,11 @@ module Harnex
           process_state: "running",
           terminal: false,
           task_complete: !failed,
+          task_failed: failed,
           done: !failed,
-          work_state: failed ? "failed" : "completed"
+          work_state: failed ? "failed" : "completed",
+          outcome_class: event["outcome_class"],
+          artifact_report_status: event["artifact_report_status"]
         )
         payload[:last_error] = event["message"] || event["error"] if failed
       end
@@ -520,6 +523,8 @@ module Harnex
         task_failed: task_failed,
         done: done,
         work_state: work_state,
+        outcome_class: status["outcome_class"],
+        artifact_report_status: status["artifact_report_status"],
         exit: status["exit"],
         exit_code: status["exit_code"],
         summary_out: status["summary_out"],

data/lib/harnex/commands/watch.rb

@@ -304,6 +304,8 @@ module Harnex
         exit_code: exit_code,
         status: payload["status"],
         work_state: payload["work_state"],
+        outcome_class: payload["outcome_class"],
+        artifact_report_status: payload["artifact_report_status"],
         task_complete: payload["task_complete"] || payload["event"] == "task_complete",
         task_failed: payload["task_failed"] || payload["event"] == "task_failed",
         done: payload["done"],