harnex 0.7.10 → 0.7.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2af8afe53ccea3fb668e920809da3fdbcd523ee5eef0179bcdd84f026077cff1
-  data.tar.gz: f675d4a401f703bf52adc88ce352fec04d2090533c3249bd0ac05e6828d030f0
+  metadata.gz: 104afb9f09fe59bd24191fde1122294a35ae47069a929022228b4365d653da54
+  data.tar.gz: ac8032b88f3c0001718ffc053923000abbba33743e6de4b68459108ca481cbcf
 SHA512:
-  metadata.gz: cda7d84fd1f80c9526529b03293623eb16f76a78872e5e29640896be76f79a448ab3bf8f4c92c74c56b8f88b814739b7fbd201a6c91ba749d22ecdc5cf8a720e
-  data.tar.gz: bc6704fc2a86a01e61c1a431fd96781bbaf178029679bc1b5c64be699f82c49bbf8b27d4f921c0d7547752eadc2dc61cffc1bc946b99d0cd5d79dd46a0de77af
+  metadata.gz: f76c4a9847aebd46cca3bada6c0af0e622bb3840fa53160cb4811c2beac2a007c6a01faadf042ef22f73e55c2ddde5571adc56d774e5b444ece412ad656242e4
+  data.tar.gz: 1d9843aa631eb411fa31c772cf5c09b92cc5d5d67ed95583abf041fd250e31343c76215a8949f268563e14609416724fd681bad6bfc5c6b7c270a4f9639e6838

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [0.7.11] - 2026-07-10 | 11:14 PM | IST
+
+### Added
+
+- Dispatch summaries now include top-level additive `agent` and `reliability`
+  blocks for every run, and a top-level `queue` block when queue attribution is
+  provided. New consumers should prefer these blocks over legacy flat fields for
+  queue economics and reliability analytics.
+- `harnex run` now accepts first-class queue/agent telemetry flags:
+  `--project-id`, `--queue-id`, `--entry-id`, `--entry-title`, `--phase`,
+  `--tier`, `--issue`, `--plan`, `--intent`, `--model`, and `--effort`.
+  Explicit flags override same-named `--meta` values and are forwarded through
+  tmux re-exec.
+- `harnex run --require-attribution` fails before launching unless required
+  queue attribution is present (`project_id`, `phase`, `intent`, and at least
+  one work id).
+
+### Changed
+
+- Dispatch telemetry docs, README, and the packaged dispatch agents-guide now
+  document queue attribution, effective agent routing fields, reliability split,
+  and a sample queue grouping snippet.
+
 ## [0.7.10] - 2026-07-10 | 10:57 PM | IST
 
 ### Added

data/README.md

@@ -284,9 +284,18 @@ 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,
+Queue runners can pass first-class attribution without hiding it in prose:
+
+```bash
+harnex run pi --project-id harnex --queue-id queue-005 --entry-id SP-4 \
+  --phase implement --intent queue-work --require-attribution ...
+```
+
+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`,

data/guides/01_dispatch.md

@@ -111,6 +111,20 @@ 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.
 
+Queue runners should pass first-class attribution so dispatch rows can be grouped
+without path/id heuristics:
+
+```bash
+harnex run pi --id pi-i-NN --tmux pi-i-NN \
+  --project-id harnex --queue-id queue-005 --entry-id SP-4 \
+  --phase implement --intent queue-work --require-attribution \
+  --context "Read and execute /tmp/task-impl-NN.md"
+```
+
+`--require-attribution` fails before launch unless `project_id`, `phase`,
+`intent`, and at least one work id (`queue_id`, `entry_id`, `issue`, or `plan`)
+are present.
+
 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/commands/run.rb

@@ -5,15 +5,33 @@ require "shellwords"
 module Harnex
   class Runner
     DEFAULT_TIMEOUT = 5.0
+    TELEMETRY_FLAGS = {
+      "--project-id" => "project_id",
+      "--queue-id" => "queue_id",
+      "--entry-id" => "entry_id",
+      "--entry-title" => "entry_title",
+      "--phase" => "phase",
+      "--tier" => "tier",
+      "--issue" => "issue",
+      "--plan" => "plan",
+      "--intent" => "intent",
+      "--model" => "model",
+      "--effort" => "effort"
+    }.freeze
+    TELEMETRY_KEYS_TO_FLAGS = TELEMETRY_FLAGS.invert.freeze
+    TELEMETRY_EQUALS_PREFIXES = TELEMETRY_FLAGS.keys.map { |flag| "#{flag}=" }.freeze
+
     KNOWN_FLAGS = %w[
       --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 --auto-stop --fast --legacy-pty --help
-    ].freeze
+      --artifact-report --validation-report --cwd --root --timeout --inbox-ttl
+      --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
-      --max-resumes --preset --context --meta --summary-out --artifact-report --validation-report --cwd --root --timeout --inbox-ttl
-    ].freeze
+      --max-resumes --preset --context --meta --summary-out --artifact-report
+      --validation-report --cwd --root --timeout --inbox-ttl
+    ].concat(TELEMETRY_FLAGS.keys).freeze
 
     def self.usage(program_name = "harnex run")
       <<~TEXT
@@ -41,6 +59,19 @@ 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
+          --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
+          --entry-title TEXT Queue telemetry entry title
+          --phase TEXT       Queue/work phase telemetry
+          --tier TEXT        Queue/work tier telemetry
+          --issue ID         Queue/work issue telemetry
+          --plan ID          Queue/work plan telemetry
+          --intent TEXT      Queue/work intent telemetry
+          --model NAME       Requested model metadata (also used for structured dispatch)
+          --effort LEVEL     Requested reasoning effort metadata (structured dispatch)
+          --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
           --root DIR         Override harnex session/root attribution without changing child cwd
           --timeout SECS     Max seconds to wait for detached registration (default: #{DEFAULT_TIMEOUT})
@@ -66,6 +97,7 @@ module Harnex
           #{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} pi --project-id harnex --queue-id queue-005 --entry-id SP-4 --phase implement --intent queue-work --require-attribution --context "Implement SP-4"
           #{program_name} claude --id cl-r-42 --tmux cl-r-42 --description "Review task 42"
 
         Gotchas:
@@ -95,6 +127,8 @@ module Harnex
         watch: nil,
         context: nil,
         meta: nil,
+        telemetry: {},
+        require_attribution: false,
         summary_out: nil,
         artifact_report: nil,
         cwd: nil,
@@ -120,6 +154,8 @@ module Harnex
 
       raise OptionParser::MissingArgument, "cli" if cli_name.nil?
       validate_auto_stop_context!
+      apply_telemetry_options!
+      validate_required_attribution!
 
       repo_root = resolve_run_root(cli_name, child_args)
       @options[:summary_out] = resolve_summary_out(repo_root)
@@ -184,6 +220,11 @@ module Harnex
       tmux_cmd += ["--context", @options[:context]] if @options[:context]
       tmux_cmd << "--auto-stop" if @options[:auto_stop]
       tmux_cmd += ["--meta", JSON.generate(@options[:meta])] if @options[:meta]
+      @options[:telemetry].each do |key, value|
+        flag = TELEMETRY_KEYS_TO_FLAGS[key]
+        tmux_cmd += [flag, value] if flag && value
+      end
+      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 += ["--cwd", @options[:cwd]] if @options[:cwd]
@@ -465,6 +506,8 @@ module Harnex
           @options[:context] = required_option_value("--context", Regexp.last_match(1))
         when "--auto-stop"
           @options[:auto_stop] = true
+        when "--require-attribution"
+          @options[:require_attribution] = true
         when "--fast"
           @options[:fast] = true
         when "--meta"
@@ -472,6 +515,12 @@ module Harnex
           @options[:meta] = parse_meta(required_option_value(arg, argv[index]))
         when /\A--meta=(.+)\z/
           @options[:meta] = parse_meta(required_option_value("--meta", Regexp.last_match(1)))
+        when *TELEMETRY_FLAGS.keys
+          index += 1
+          @options[:telemetry][TELEMETRY_FLAGS.fetch(arg)] = required_option_value(arg, argv[index])
+        when telemetry_equals_regex
+          flag = "--#{Regexp.last_match(1)}"
+          @options[:telemetry][TELEMETRY_FLAGS.fetch(flag)] = required_option_value(flag, Regexp.last_match(2))
         when "--summary-out"
           index += 1
           @options[:summary_out] = required_option_value(arg, argv[index])
@@ -520,6 +569,10 @@ module Harnex
       [cli_name, forwarded]
     end
 
+    def telemetry_equals_regex
+      @telemetry_equals_regex ||= /\A--(#{TELEMETRY_FLAGS.keys.map { |flag| Regexp.escape(flag.delete_prefix("--")) }.join("|")})=(.+)\z/
+    end
+
     def unknown_long_flag?(arg)
       arg.start_with?("--")
     end
@@ -556,7 +609,7 @@ module Harnex
         case arg
         when "--"
           return false
-        when "-h", "--help", "--detach", "--tmux", "--auto-stop", "--fast", "--legacy-pty"
+        when "-h", "--help", "--detach", "--tmux", "--auto-stop", "--require-attribution", "--fast", "--legacy-pty"
           nil
         when /\A--tmux=/
           nil
@@ -564,6 +617,8 @@ module Harnex
           index += 1
         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 telemetry_equals_regex
+          nil
         when /\A--preset=/
           nil
         else
@@ -581,7 +636,8 @@ module Harnex
         arg.start_with?(
           "--id=", "--description=", "--tmux=", "--host=", "--port=", "--watch=", "--watch-file=",
           "--stall-after=", "--max-resumes=", "--preset=", "--context=", "--meta=", "--summary-out=",
-          "--artifact-report=", "--validation-report=", "--cwd=", "--root=", "--timeout=", "--inbox-ttl="
+          "--artifact-report=", "--validation-report=", "--cwd=", "--root=", "--timeout=", "--inbox-ttl=",
+          *TELEMETRY_EQUALS_PREFIXES
         )
     end
 
@@ -610,6 +666,32 @@ module Harnex
       raise OptionParser::InvalidOption, "harnex run: --auto-stop requires --context"
     end
 
+    def apply_telemetry_options!
+      explicit = @options[:telemetry]
+      return if explicit.empty? && @options[:meta].is_a?(Hash)
+      return if explicit.empty?
+
+      @options[:meta] = (@options[:meta].is_a?(Hash) ? @options[:meta].dup : {}).merge(explicit)
+    end
+
+    def validate_required_attribution!
+      return unless @options[:require_attribution]
+
+      metadata = @options[:meta].is_a?(Hash) ? @options[:meta] : {}
+      missing = %w[project_id phase intent].select { |key| blank_value?(metadata[key]) }
+      unless %w[queue_id entry_id issue plan].any? { |key| !blank_value?(metadata[key]) }
+        missing << "one of queue_id/entry_id/issue/plan"
+      end
+      return if missing.empty?
+
+      raise OptionParser::InvalidOption,
+            "harnex run: --require-attribution missing #{missing.join(', ')}"
+    end
+
+    def blank_value?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
     def apply_codex_service_tier(cli_name, child_args)
       return child_args unless cli_name.to_s == "codex"
       return child_args if child_service_tier_config?(child_args)

data/lib/harnex/runtime/session.rb

@@ -16,6 +16,11 @@ module Harnex
       agent_session_id cost_usd
     ].freeze
     BUDGET_META_FIELDS = %w[read_budget_lines output_ceiling_lines].freeze
+    QUEUE_FIELDS = %w[project_id queue_id entry_id entry_title issue plan phase tier intent].freeze
+    AGENT_FIELDS = %w[cli provider model_requested model_effective reasoning_effort service_tier adapter_transport].freeze
+    RELIABILITY_FIELDS = %w[
+      adapter_close real_disconnections stream_interruptions stalls force_resumes compactions recovered
+    ].freeze
     SUCCESSFUL_TURN_STATUSES = %w[completed success succeeded].freeze
     class EventCounters
       def initialize
@@ -1168,8 +1173,12 @@ module Harnex
       record = {
         meta: build_summary_meta,
         predicted: summary_predicted_payload,
-        actual: build_summary_actual
+        actual: build_summary_actual,
+        agent: build_summary_agent,
+        reliability: build_summary_reliability
       }
+      queue = build_summary_queue
+      record[:queue] = queue if queue
       record.merge!(artifact_report_summary) if artifact_report_path
       record
     end
@@ -1207,12 +1216,42 @@ module Harnex
       }.merge(summary_budget_meta)
     end
 
+    def build_summary_queue
+      queue = QUEUE_FIELDS.to_h { |field| [field, summary_string(meta_hash[field])] }
+      return nil if queue.values.all?(&:nil?)
+
+      queue
+    end
+
+    def build_summary_agent
+      {
+        "cli" => adapter.key,
+        "provider" => summary_agent_provider,
+        "model_requested" => summary_string(meta_hash["model"]),
+        "model_effective" => summary_string(summary_model),
+        "reasoning_effort" => summary_string(meta_hash["effort"]),
+        "service_tier" => summary_service_tier,
+        "adapter_transport" => adapter.transport.to_s
+      }
+    end
+
+    def build_summary_reliability
+      counters = summary_event_counters
+      real_disconnections = counters[:disconnections].to_i
+      {
+        "adapter_close" => summary_adapter_close(real_disconnections),
+        "real_disconnections" => real_disconnections,
+        "stream_interruptions" => real_disconnections,
+        "stalls" => counters[:stalls].to_i,
+        "force_resumes" => counters[:force_resumes].to_i,
+        "compactions" => counters[:compactions].to_i,
+        "recovered" => false
+      }
+    end
+
     def build_summary_actual
-      counters = @event_counters.snapshot
+      counters = summary_event_counters
       output_measurements = summary_output_measurements
-      if %w[disconnected boot_failure].include?(@exit_reason)
-        counters[:disconnections] = [counters[:disconnections], 1].max
-      end
 
       actual = {
         model: summary_model,
@@ -1298,6 +1337,52 @@ module Harnex
         (adapter.current_model if adapter.respond_to?(:current_model))
     end
 
+    def summary_service_tier
+      summary_string(meta_hash["service_tier"]) || service_tier_from_command
+    end
+
+    def service_tier_from_command
+      command.each_with_index do |arg, index|
+        text = arg.to_s
+        if text == "-c" || text == "--config"
+          parsed = parse_service_tier_config(command[index + 1])
+          return parsed if parsed
+        end
+        parsed = parse_service_tier_config(text)
+        return parsed if parsed
+      end
+      nil
+    end
+
+    def parse_service_tier_config(value)
+      text = value.to_s
+      match = text.match(/(?:\A|=)service_tier=\\?"?([^"\s]+)\\?"?/)
+      return nil unless match
+
+      summary_string(match[1])
+    end
+
+    def summary_event_counters
+      counters = @event_counters.snapshot
+      if %w[disconnected boot_failure].include?(@exit_reason)
+        counters[:disconnections] = [counters[:disconnections], 1].max
+      end
+      counters
+    end
+
+    def summary_adapter_close(real_disconnections)
+      return "interrupted" if @exit_code == 124 || @term_signal
+      return "lost" if %w[disconnected boot_failure].include?(@exit_reason) || real_disconnections.to_i.positive?
+      return "normal" if %w[success failure].include?(@exit_reason)
+
+      "unknown"
+    end
+
+    def summary_string(value)
+      text = value.to_s
+      text.empty? ? nil : text
+    end
+
     def summary_tool_calls(counters)
       @usage_summary[:tool_calls] || counters[:tool_calls]
     end

data/lib/harnex/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.7.10
+  version: 0.7.11
 platform: ruby
 authors:
 - Jikku Jose