harnex 0.7.12 → 0.7.14

data/lib/harnex/cli.rb

@@ -37,6 +37,10 @@ module Harnex
         AgentsGuide.new(@argv.drop(1)).run
       when "doctor"
         Doctor.new(@argv.drop(1)).run
+      when "orchestration"
+        OrchestrationCommand.new(@argv.drop(1)).run
+      when "artifact-report"
+        ArtifactReportCommand.new(@argv.drop(1)).run
       when "help"
         puts help(@argv[1])
         0
@@ -83,6 +87,10 @@ module Harnex
         AgentsGuide.usage
       when "doctor"
         Doctor.usage
+      when "orchestration"
+        OrchestrationCommand.usage
+      when "artifact-report"
+        ArtifactReportCommand.usage
       else
         usage
       end
@@ -103,6 +111,8 @@ module Harnex
           harnex pane --id ID [options]
           harnex agents-guide [topic]
           harnex doctor
+          harnex orchestration sample|report [options]
+          harnex artifact-report init|validate PATH [options]
           harnex help [command]
 
         Commands:
@@ -121,6 +131,10 @@ module Harnex
           agents-guide
                   Show agent dispatch, chain, buddy, monitoring, and naming guides
           doctor  Run preflight checks and optional read-only session sweep
+          orchestration
+                  Emit external primary samples and report orchestration tax
+          artifact-report
+                  Initialize or validate harnex.artifact_report.v1 sidecars
           help    Show command help
 
         New to harnex? Start with: harnex guide
@@ -142,6 +156,9 @@ module Harnex
           harnex pane --id main --lines 40
           harnex agents-guide dispatch
           harnex doctor
+          harnex orchestration report --dispatch .harnex/dispatch.jsonl --run-id queue-005 --json
+          harnex artifact-report init .harnex/reports/cx-i-60.json
+          harnex artifact-report validate .harnex/reports/cx-i-60.json --final
           harnex send --id main --message "Summarize current progress."
       TEXT
     end

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

@@ -16,7 +16,15 @@ module Harnex
       "--plan" => "plan",
       "--intent" => "intent",
       "--model" => "model",
-      "--effort" => "effort"
+      "--effort" => "effort",
+      "--parent-dispatch-id" => "parent_dispatch_id",
+      "--parent-attempt-id" => "parent_attempt_id",
+      "--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
@@ -25,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
@@ -50,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
@@ -59,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
@@ -70,6 +81,22 @@ module Harnex
           --intent TEXT      Queue/work intent telemetry
           --model NAME       Requested model metadata (also used for structured dispatch)
           --effort LEVEL     Requested reasoning effort metadata (structured dispatch)
+          --parent-dispatch-id ID
+                             Parent dispatch id for retry/fix/review joins
+          --parent-attempt-id ID
+                             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
@@ -85,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.
@@ -131,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,
@@ -154,7 +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)
@@ -227,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]
@@ -337,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,
@@ -529,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/
@@ -609,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
@@ -666,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)
@@ -674,6 +719,24 @@ module Harnex
       @options[:meta] = (@options[:meta].is_a?(Hash) ? @options[:meta].dup : {}).merge(explicit)
     end
 
+    def validate_attempt_metadata!
+      metadata = @options[:meta].is_a?(Hash) ? @options[:meta] : {}
+      kind = metadata["attempt_kind"].to_s
+      return if kind.empty? || Session::ATTEMPT_KINDS.include?(kind)
+
+      raise OptionParser::InvalidOption,
+            "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"],

data/lib/harnex/context_telemetry.rb

@@ -0,0 +1,104 @@
+module Harnex
+  # Bounded in-memory aggregate for active context-window samples.
+  #
+  # It retains only the final valid occupancy sample, independent high-water
+  # marks, and counters that make unavailable samples visible without storing
+  # raw protocol payloads.
+  class ContextTelemetry
+    MEASUREMENT_STATUSES = %w[observed estimated].freeze
+
+    def initialize(status:, source:)
+      measurement_status = status.to_s
+      unless MEASUREMENT_STATUSES.include?(measurement_status)
+        raise ArgumentError, "context telemetry status must be observed or estimated"
+      end
+
+      @measurement_status = measurement_status
+      @source = source.to_s.empty? ? nil : source.to_s
+      @terminal_tokens = nil
+      @window_tokens = nil
+      @terminal_percent = nil
+      @peak_tokens = nil
+      @peak_percent = nil
+      @samples = 0
+      @missing_samples = 0
+      @latest_sample_status = nil
+      @valid_sample_seen = false
+    end
+
+    def record(tokens:, window_tokens:, percent: nil)
+      @samples += 1
+      token_count = nonnegative_integer(tokens)
+      window_size = positive_integer(window_tokens)
+      pressure_percent = nonnegative_float(percent)
+      pressure_percent ||= derived_percent(token_count, window_size)
+
+      if token_count.nil?
+        @missing_samples += 1
+        @latest_sample_status = "missing"
+        return snapshot
+      end
+
+      @valid_sample_seen = true
+      @terminal_tokens = token_count
+      @window_tokens = window_size
+      @terminal_percent = pressure_percent
+      @peak_tokens = [@peak_tokens, token_count].compact.max
+      @peak_percent = [@peak_percent, pressure_percent].compact.max
+      @latest_sample_status = @measurement_status
+      snapshot
+    end
+
+    def snapshot
+      {
+        status: @valid_sample_seen ? @measurement_status : "missing",
+        source: @source,
+        terminal_tokens: @terminal_tokens,
+        window_tokens: @window_tokens,
+        terminal_percent: @terminal_percent,
+        peak_tokens: @peak_tokens,
+        peak_percent: @peak_percent,
+        samples: @samples,
+        missing_samples: @missing_samples,
+        latest_sample_status: @latest_sample_status
+      }
+    end
+
+    private
+
+    def nonnegative_integer(value)
+      return nil if value.nil?
+
+      parsed = Integer(value)
+      return nil if value.is_a?(Numeric) && value.to_f != parsed.to_f
+      return nil if parsed.negative?
+
+      parsed
+    rescue ArgumentError, TypeError, FloatDomainError
+      nil
+    end
+
+    def positive_integer(value)
+      parsed = nonnegative_integer(value)
+      parsed&.positive? ? parsed : nil
+    end
+
+    def nonnegative_float(value)
+      return nil if value.nil?
+
+      parsed = Float(value)
+      return nil unless parsed.finite?
+      return nil if parsed.negative?
+
+      parsed
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def derived_percent(token_count, window_size)
+      return nil if token_count.nil? || window_size.nil?
+
+      ((token_count.to_f / window_size) * 100).round(2)
+    end
+  end
+end

data/lib/harnex/core.rb

@@ -141,6 +141,7 @@ module Harnex
     end_sha = git_output(repo_root, "rev-parse", "HEAD")
     range = "#{start_sha}..#{end_sha}"
     shortstat = git_output(repo_root, "diff", "--shortstat", range)
+    changed_paths = git_output(repo_root, "diff", "--name-only", range).lines.map(&:strip).reject(&:empty?).first(200)
     commits = Integer(git_output(repo_root, "rev-list", "--count", range))
     stats = parse_git_shortstat(shortstat)
 
@@ -149,6 +150,7 @@ module Harnex
       loc_added: stats.fetch(:loc_added),
       loc_removed: stats.fetch(:loc_removed),
       files_changed: stats.fetch(:files_changed),
+      changed_paths: changed_paths,
       commits: commits
     }
   rescue StandardError