harnex 0.10.0 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0a3ac349311bc2677614dabb091443bb21ec82bf63852d237fb38fd47ecaeda
-  data.tar.gz: f1b909c7ed43636ea57a297e25f2adc1d56283faa5f8af882ed22b63b4c55f2f
+  metadata.gz: 25ba2b12b69cc6351e2ca4ee1e72e5f378a3828f7486498a2e2a026cf9da771b
+  data.tar.gz: 7e3cc95587c16dcb0a7b9a3e8339546a9ffbe085e4517407f1325e87fd2f45ce
 SHA512:
-  metadata.gz: fe2b745dd618e1967fa5bbe1f7f55f4c0c2beb104cd6d213592f8545528118d3b3a80053b5643fce5482d3eaca9c7e6d800b6f5dd6d41873c0c9e5cc73aff332
-  data.tar.gz: 0c13e6cb6fe6bbac64e14ae43b23061a2b5a96cbc7f4699d438b5e5eac48ef70435c017b638635c0ded52886536f94aac37df712b1d67a9c5485dc0dd1cfa4b7
+  metadata.gz: fcaa6d99632c375c1315bfc553b99ccf5c583b58a52e627e0af951493481bf33af9b5de50ca4704a1e6e2d7d9a8aa6999b42d94347ff942b76ac5033eb870dae
+  data.tar.gz: 929011b78aa399cc098b644f0bb2a0995222df71698e450e7ab4785e1be9249e07e4d40225fbf80e02ea9a11f6fefd7913c27682110944ccadacea8f879e7200

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.10.2] - 2026-08-08 | 06:49 PM | IST
+
+Docs-only patch: no library or CLI behavior changes. Released so the
+packaged `agents-guide` surfaces serve the corrected guidance instead of the
+stale 0.10.1 copies.
+
+### Changed
+
+- `guides/04_monitoring.md`: the Completion Test's clean-tree check now
+  documents excluding the harness-owned dispatch stream
+  (`git status --short -- . ':!.harnex'`) in repos that track
+  `.harnex/dispatch.jsonl`. New anti-patterns: claiming "no live sessions"
+  from memory (finished agents park at prompts — sweep proven-done sessions,
+  then prove with `harnex status`) and failing clean-tree fences on
+  dispatch-stream growth.
+- `docs/dispatch-telemetry.md`: new "Clean-Tree Checks And The Tracked
+  Stream" section — the tracked stream grows mid-run and is harness-owned;
+  fences and worker briefs must exclude it and never revert it.
+
+Context: holm Analysis 803 (queue-process failure meta-analysis). During
+Q107 g2 a worker aborted after misreading dispatch-stream growth as foreign
+dirt, and a coordinator claimed "no live sessions" while 12 completed
+workers sat parked at prompts.
+
+## [0.10.1] - 2026-08-04 | 12:20 AM | IST
+
+Patch release: closes the recovery and regression-checking gap left
+after `0.10.0` removed the upstream telemetry mirror. The canonical
+`.harnex/dispatch.jsonl` stream remains the only writer; this release adds
+operator tooling to prove and repair that stream without schema migration.
+
+### Added
+
+- `harnex telemetry assert-canonical` validates the canonical dispatch stream
+  and, when explicit `--source` paths are supplied, fails closed on missing or
+  conflicting rich end rows. It is read-only, tolerates mixed-era history
+  including open v2 starts and legacy rows, and emits bounded redacted reports.
+- `harnex telemetry reconcile` uses the same analysis, defaults to dry-run, and
+  only appends missing rich end rows when `--apply` is passed. It never rewrites,
+  deletes, sorts, migrates, cleans source files, or discovers sources
+  automatically.
+- Source paths may be files or directories. Directory scans are bounded to
+  `.json`/`.jsonl`, skip `.git`, symlinks, and the resolved canonical stream,
+  ignore unrelated generic JSON, and treat identity or payload conflicts as
+  zero-write failures.
+
 ## [0.10.0] - 2026-08-03 | 01:44 PM | IST
 
 Minor bump, **breaking**: `--summary-out` is removed outright, so the canonical

data/docs/dispatch-telemetry.md

@@ -11,6 +11,16 @@ git repo it is `~/.local/state/harnex/dispatch.jsonl`. `harnex history`,
 `status --id`, and `wait` consume the same rows. Legacy v1 thin rows and
 pre-v2 envelope-less summaries may coexist and remain readable/skippable.
 
+## Clean-Tree Checks And The Tracked Stream
+
+Some repos deliberately track `.harnex/dispatch.jsonl` as project telemetry.
+There the stream grows while sessions run, so worker briefs, completion
+fences, and orchestration clean-tree checks must treat the path as
+harness-owned: expected to be dirty mid-run, never foreign dirt to abort on,
+and never a file a worker should revert or "clean up". Exclude it explicitly,
+for example `git status --porcelain -- . ':!.harnex'`, and commit its growth
+alongside the work it describes.
+
 ## CLI flags
 
 ```text
@@ -66,6 +76,42 @@ harnex orchestration report --dispatch .harnex/dispatch.jsonl --run-id queue-005
 
 Use `harnex history --json | jq .` for pipelines over the repo-local log.
 
+## Canonical assertion and reconciliation
+
+`harnex telemetry assert-canonical` is the read-only drift gate for the
+canonical dispatch stream. Without sources it performs structural validation;
+with explicit `--source PATH` inputs it also reports missing or conflicting rich
+end rows and exits non-zero until the canonical stream is clean.
+
+`harnex telemetry reconcile` runs the same analysis. It is a dry-run by default;
+only `--apply` appends missing rich end rows, and then only after the canonical
+stream and all source candidates have been parsed and conflict-checked. Apply
+uses one append lock, rechecks under that lock, and is idempotent.
+
+```text
+harnex telemetry assert-canonical [--canonical PATH | --global] [--source PATH ...] [--json]
+harnex telemetry reconcile [--canonical PATH | --global] --source PATH [--source PATH ...] [--apply] [--json]
+```
+
+The default canonical path is the repo-local `.harnex/dispatch.jsonl`, or the
+global dispatch stream outside a git repo. `--canonical` and `--global` are
+mutually exclusive. Sources are never discovered automatically: each `--source`
+must be a file or directory. Directory scans consider regular `.json` and
+`.jsonl` files, skip `.git`, symlinks, and the resolved canonical path, and
+ignore unrelated JSON that does not match a rich Harnex dispatch end shape.
+
+Mixed-era history is valid input. Legacy v1 thin rows, pre-v2 envelope-less rich
+summaries, and v2 start/end rows may coexist. Open v2 starts are tolerated
+because a running or interrupted dispatch may not have an end row yet. Identity
+checks normalize equivalent timestamp offsets, and conflicts fail closed rather
+than choosing a winner.
+
+Reports are bounded and redacted: they contain counts, statuses, identities, and
+path:line diagnostics, not raw telemetry payloads, prompts, claims, command
+text, or rich sections. The commands never rewrite, delete, sort, migrate,
+clean source files, reintroduce mirrors, or perform source discovery on their
+own.
+
 ## Metadata and prediction contract
 
 The v2 `dispatch_end` always has `meta`, `predicted`, `actual`, `agent`,

data/guides/04_monitoring.md

@@ -100,6 +100,17 @@ terminal work signal.
 Adjust the artifact path to the task. The point is to avoid declaring done while
 a worker is between edits or between commits.
 
+In repos that track the dispatch stream (`.harnex/dispatch.jsonl`), exclude it
+from the clean-tree check — harnex appends to it during every run, so it is
+legitimately dirty mid-run:
+
+```bash
+test -z "$(git status --short -- . ':!.harnex')"
+```
+
+Never treat harness-owned telemetry as foreign dirt, and never instruct a
+worker to revert or "clean up" the stream to satisfy a fence.
+
 ## Why Pane State Alone Is Not Enough
 
 Avoid using `state=prompt` or a quiet pane as the only completion signal:
@@ -199,3 +210,8 @@ interpretation.
 - Reading raw tmux panes instead of `harnex pane`.
 - Using `--wait-for-idle` as acceptance proof.
 - Reusing a worker after a failure changes the task scope.
+- Claiming "no live sessions" from memory. Finished agents park at prompts
+  indefinitely; sweep proven-done sessions, then prove the claim with
+  `harnex status`.
+- Failing a clean-tree fence on `.harnex/dispatch.jsonl` growth in repos that
+  track the dispatch stream.

data/lib/harnex/cli.rb

@@ -41,6 +41,8 @@ module Harnex
         OrchestrationCommand.new(@argv.drop(1)).run
       when "artifact-report"
         ArtifactReportCommand.new(@argv.drop(1)).run
+      when "telemetry"
+        TelemetryCommand.new(@argv.drop(1)).run
       when "help"
         puts help(@argv[1])
         0
@@ -91,6 +93,8 @@ module Harnex
         OrchestrationCommand.usage
       when "artifact-report"
         ArtifactReportCommand.usage
+      when "telemetry"
+        TelemetryCommand.usage
       else
         usage
       end
@@ -113,6 +117,7 @@ module Harnex
           harnex doctor
           harnex orchestration sample|report [options]
           harnex artifact-report init|validate PATH [options]
+          harnex telemetry assert-canonical|reconcile [options]
           harnex help [command]
 
         Commands:
@@ -135,6 +140,8 @@ module Harnex
                   Emit external primary samples and report orchestration tax
           artifact-report
                   Validate harness-authored receipts or initialize legacy v1 documents
+          telemetry
+                  Assert or reconcile canonical dispatch telemetry
           help    Show command help
 
         New to harnex? Start with: harnex guide
@@ -159,6 +166,7 @@ module Harnex
           harnex orchestration report --dispatch .harnex/dispatch.jsonl --run-id queue-005 --json
           harnex artifact-report validate /path/from-dispatch-row.json --final
           harnex artifact-report init .harnex/reports/legacy-v1.json
+          harnex telemetry assert-canonical --canonical .harnex/dispatch.jsonl --json
           harnex send --id main --message "Summarize current progress."
       TEXT
     end

data/lib/harnex/commands/telemetry.rb

@@ -0,0 +1,110 @@
+require "json"
+require "optparse"
+
+module Harnex
+  class TelemetryCommand
+    COMMANDS = %w[assert-canonical reconcile].freeze
+
+    def self.usage(program_name = "harnex telemetry")
+      <<~TEXT
+        Usage:
+          #{program_name} assert-canonical [--canonical PATH | --global] [--source PATH] [--json]
+          #{program_name} reconcile [--canonical PATH | --global] --source PATH [--apply] [--json]
+
+        Options:
+          --canonical PATH  Canonical dispatch JSONL path
+          --global          Use the global harnex dispatch JSONL
+          --source PATH     Source JSONL file or directory; repeatable
+          --apply           Append missing records when reconciling
+          --json            Emit JSON report
+          -h, --help        Show this help
+      TEXT
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      command = @argv.shift
+      case command
+      when nil, "-h", "--help"
+        puts self.class.usage
+        0
+      when *COMMANDS
+        options = parse_options(command, @argv)
+        if options[:help]
+          puts self.class.usage
+          return 0
+        end
+        validate_options!(command, options)
+        result = TelemetryReconciler.new(
+          command: command,
+          canonical: canonical_path(options),
+          sources: options[:sources],
+          apply: command == "reconcile" && options[:apply]
+        ).run
+        if options[:json]
+          puts JSON.generate(result.report)
+        else
+          puts render_human(result.report)
+        end
+        result.exitstatus
+      else
+        raise OptionParser::ParseError, "unknown telemetry subcommand #{command.inspect}"
+      end
+    end
+
+    private
+
+    def parse_options(command, argv)
+      options = { command: command, sources: [], apply: false, json: false }
+      parser(options).parse!(argv)
+      raise OptionParser::InvalidArgument, "unexpected arguments: #{argv.join(' ')}" unless argv.empty?
+
+      options
+    end
+
+    def parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: harnex telemetry #{options[:command]} [options]"
+        opts.on("--canonical PATH") { |value| options[:canonical] = value }
+        opts.on("--global") { options[:global] = true }
+        opts.on("--source PATH") { |value| options[:sources] << value }
+        opts.on("--apply") { options[:apply] = true }
+        opts.on("--json") { options[:json] = true }
+        opts.on("-h", "--help") { options[:help] = true }
+      end
+    end
+
+    def validate_options!(command, options)
+      if options[:canonical] && options[:global]
+        raise OptionParser::InvalidOption, "--canonical and --global are mutually exclusive"
+      end
+      if command == "assert-canonical" && options[:apply]
+        raise OptionParser::InvalidOption, "--apply is only supported with reconcile"
+      end
+      return unless command == "reconcile" && options[:sources].empty?
+
+      raise OptionParser::MissingArgument, "reconcile --source required"
+    end
+
+    def canonical_path(options)
+      return Harnex::DispatchHistory.global_path if options[:global]
+
+      options[:canonical] || Harnex::DispatchHistory.path_for(Dir.pwd)
+    end
+
+    def render_human(report)
+      lines = [
+        "telemetry #{report.fetch(:command)}: #{report.fetch(:status)}",
+        "canonical: #{report.fetch(:canonical)}",
+        "rows: #{report.fetch(:canonical_rows)} missing=#{report.fetch(:missing)} conflicts=#{report.fetch(:conflicts)} open_starts=#{report.fetch(:open_starts)} appended=#{report.fetch(:appended)}"
+      ]
+      report.fetch(:diagnostics).each { |diagnostic| lines << "diagnostic: #{diagnostic}" }
+      truncated = report.fetch(:diagnostics_truncated)
+      lines << "diagnostics truncated: #{truncated}" if truncated.to_i.positive?
+      lines.join("\n")
+    end
+  end
+end

data/lib/harnex/telemetry_reconciler.rb

@@ -0,0 +1,494 @@
+require "fileutils"
+require "json"
+require "set"
+require "time"
+
+module Harnex
+  class TelemetryReconciler
+    SCHEMA = "harnex.telemetry_reconcile.v1"
+    FAMILY_KEYS = %w[v2_start v2_end v1_end legacy_rich legacy_unknown].freeze
+    RICH_KEYS = %w[predicted agent usage context attribution outcome attempt reliability].freeze
+    MAX_DIAGNOSTICS = 50
+
+    Result = Struct.new(:report, :exitstatus, keyword_init: true)
+    Row = Struct.new(:record, :path, :line, :family, :identity, :match_identity, :sort_key, keyword_init: true)
+
+    def initialize(command:, canonical:, sources:, apply: false)
+      @command = command
+      @canonical = canonical
+      @sources = sources
+      @apply = apply
+      @diagnostics = []
+      @diagnostics_truncated = 0
+    end
+
+    def run
+      base = analyze
+      return finish(base) unless @apply && writable?(base)
+
+      appended, locked = append_missing_under_lock(base[:missing_rows])
+      locked[:appended] = appended
+      return finish(locked) unless locked[:fatal].empty? && locked[:conflict_rows].empty?
+
+      post = analyze
+      post[:appended] = appended
+      finish(post)
+    end
+
+    private
+
+    def analyze
+      reset_diagnostics
+      canonical = load_canonical(@canonical)
+      sources = discover_sources(@sources, @canonical)
+      source_rows = sources[:rows]
+      conflict_rows = sources[:conflicts]
+      missing_rows = []
+      present = 0
+
+      unless canonical[:fatal].empty? || source_rows.empty?
+        return analysis(canonical, sources, present, missing_rows, conflict_rows)
+      end
+
+      source_rows.each do |row|
+        match = find_match(row, canonical[:recoverable])
+        if match.nil?
+          missing_rows << row
+          diagnostic("missing #{identity_label(row)} at #{row.path}:#{row.line}")
+        elsif rows_payload_equal?(row, match)
+          present += 1
+        else
+          conflict_rows << [row, match]
+          diagnostic("identity conflict #{identity_label(row)} at #{row.path}:#{row.line} vs #{match.path}:#{match.line}")
+        end
+      end
+
+      analysis(canonical, sources, present, missing_rows, conflict_rows)
+    end
+
+    def analysis(canonical, sources, present, missing_rows, conflict_rows)
+      {
+        canonical_rows: canonical[:rows],
+        families: canonical[:families],
+        recoverable: canonical[:recoverable],
+        sources: sources[:summary],
+        fatal: canonical[:fatal] + sources[:fatal],
+        present: present,
+        missing_rows: dedupe_rows(missing_rows),
+        conflict_rows: conflict_rows,
+        open_starts: canonical[:open_starts],
+        appended: 0
+      }
+    end
+
+    def finish(state)
+      state[:fatal].each { |message| diagnostic(message) }
+      status =
+        if state[:fatal].any?
+          "corrupt"
+        elsif state[:conflict_rows].any?
+          "conflict"
+        elsif state[:missing_rows].any?
+          "drift"
+        else
+          "clean"
+        end
+
+      report = {
+        schema: SCHEMA,
+        command: @command,
+        status: status,
+        canonical: @canonical,
+        canonical_rows: state[:canonical_rows],
+        families: state[:families],
+        sources: state[:sources],
+        present: state[:present],
+        missing: state[:missing_rows].length,
+        conflicts: state[:conflict_rows].length,
+        open_starts: state[:open_starts],
+        appended: state[:appended],
+        diagnostics: @diagnostics,
+        diagnostics_truncated: @diagnostics_truncated
+      }
+      Result.new(report: report, exitstatus: status == "clean" ? 0 : 1)
+    end
+
+    def writable?(state) = state[:fatal].empty? && state[:conflict_rows].empty? && state[:missing_rows].any?
+
+    def load_canonical(path)
+      rows = []
+      fatal = []
+      families = FAMILY_KEYS.to_h { |key| [key, 0] }
+      starts = {}
+      ends = {}
+      recoverable = []
+
+      read_jsonl(path).each do |entry|
+        if entry[:error]
+          fatal << "malformed canonical JSON at #{path}:#{entry[:line]}"
+          next
+        end
+        record = entry[:record]
+        rows << record
+        unless record.is_a?(Hash)
+          fatal << "canonical JSON object required at #{path}:#{entry[:line]}"
+          next
+        end
+
+        case canonical_family(record)
+        when :v2_start
+          families["v2_start"] += 1
+          validate_v2(record, path, entry[:line], fatal) do |identity|
+            add_unique(starts, identity, record, path, entry[:line], fatal, "v2 start")
+          end
+        when :v2_end
+          families["v2_end"] += 1
+          validate_v2(record, path, entry[:line], fatal) do |identity|
+            add_unique(ends, identity, record, path, entry[:line], fatal, "v2 end")
+            recoverable << build_row(record, path, entry[:line], :v2)
+          end
+        when :v1_end
+          families["v1_end"] += 1
+        when :legacy_rich
+          families["legacy_rich"] += 1
+          recoverable << build_row(record, path, entry[:line], :legacy)
+        else
+          families["legacy_unknown"] += 1
+          diagnostic("legacy_unknown at #{path}:#{entry[:line]}")
+        end
+      end
+
+      ends.each do |identity, row|
+        fatal << "unpaired v2 end #{identity.join('|')} at #{row.path}:#{row.line}" unless starts.key?(identity)
+      end
+
+      {
+        rows: rows.length,
+        families: families,
+        recoverable: recoverable,
+        fatal: fatal,
+        open_starts: (starts.keys - ends.keys).length
+      }
+    end
+
+    def validate_v2(record, path, line, fatal)
+      unless record["schema_version"] == Harnex::DispatchHistory::SCHEMA_VERSION
+        fatal << "invalid v2 schema_version at #{path}:#{line}"
+        return
+      end
+      id = record["id"].to_s
+      session_id = record["session_id"].to_s
+      started_at = normalized_time(record["started_at"])
+      if id.empty? || session_id.empty? || started_at.nil?
+        fatal << "invalid v2 identity at #{path}:#{line}"
+        return
+      end
+
+      yield(["v2", session_id, id, started_at])
+    end
+
+    def add_unique(index, identity, record, path, line, fatal, label)
+      prior = index[identity]
+      if prior
+        kind = payload_equal?(record, prior.record) ? "duplicate v2 identity" : "identity conflict"
+        fatal << "#{kind} for #{label} #{identity.join('|')} at #{path}:#{line}"
+        return
+      end
+
+      index[identity] = Row.new(record: record, path: path, line: line)
+    end
+
+    def discover_sources(paths, canonical_path)
+      unique = paths.map { |path| File.expand_path(path) }.uniq
+      files = unique.flat_map { |path| source_files(path, canonical_path) }
+      rows = []
+      fatal = []
+
+      files.each do |file|
+        parsed = parse_source_file(file[:path], explicit: file[:explicit])
+        fatal.concat(parsed[:fatal])
+        rows.concat(parsed[:rows])
+      end
+
+      conflicts = source_conflicts(rows)
+      conflicts.each { |left, right| diagnostic("identity conflict #{identity_label(left)} at #{left.path}:#{left.line} vs #{right.path}:#{right.line}") }
+
+      {
+        rows: dedupe_source_rows(rows),
+        fatal: fatal,
+        summary: {
+          "paths" => unique.length,
+          "files_scanned" => files.length,
+          "candidates" => rows.length
+        },
+        conflicts: conflicts
+      }
+    end
+
+    def source_files(path, canonical_path)
+      canonical_real = realpath_or_expand(canonical_path)
+      if File.file?(path) && !File.symlink?(path)
+        return [{ path: path, explicit: true }]
+      end
+      return [] unless File.directory?(path)
+
+      files = []
+      Dir.children(path).sort.each do |child|
+        child_path = File.join(path, child)
+        next if child == ".git" || File.symlink?(child_path)
+
+        if File.directory?(child_path)
+          files.concat(source_files(child_path, canonical_path))
+        elsif File.file?(child_path) && child_path.match?(/\.(jsonl?|JSONL?)\z/)
+          next if realpath_or_expand(child_path) == canonical_real
+
+          files << { path: child_path, explicit: false }
+        end
+      end
+      files
+    end
+
+    def parse_source_file(path, explicit:)
+      parsed = parse_whole_json(path)
+      entries = parsed ? json_entries(parsed, path) : read_jsonl(path)
+      errors = entries.select { |entry| entry[:error] }
+      rows = entries.filter_map do |entry|
+        next if entry[:error]
+
+        source_candidate(entry[:record], path, entry[:line])
+      end
+
+      fatal = []
+      if explicit && errors.any?
+        fatal << "malformed source telemetry at #{path}:#{errors.first[:line]}"
+      elsif !explicit && rows.any? && errors.any?
+        fatal << "malformed source telemetry at #{path}:#{errors.first[:line]}"
+      end
+      { rows: rows, fatal: fatal }
+    end
+
+    def parse_whole_json(path)
+      text = File.read(path)
+      return nil if text.strip.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError, Errno::ENOENT, Errno::EACCES
+      nil
+    end
+
+    def json_entries(value, path)
+      records = value.is_a?(Array) ? value : [value]
+      records.each_with_index.map { |record, index| { record: record, line: index + 1, path: path } }
+    end
+
+    def read_jsonl(path)
+      return [] unless File.file?(path)
+
+      File.readlines(path, chomp: true).each_with_index.filter_map do |line, index|
+        next if line.strip.empty?
+
+        begin
+          { record: JSON.parse(line), line: index + 1, path: path }
+        rescue JSON::ParserError => error
+          { error: error, line: index + 1, path: path }
+        end
+      end
+    end
+
+    def canonical_family(record)
+      if record["schema_version"] == 2 && record["record_type"] == "dispatch_start"
+        :v2_start
+      elsif record["schema_version"] == 2 && record["record_type"] == "dispatch_end"
+        :v2_end
+      elsif record["schema_version"] == 1 && record.key?("status") && !record.key?("record_type")
+        :v1_end
+      elsif legacy_rich?(record)
+        :legacy_rich
+      else
+        :legacy_unknown
+      end
+    end
+
+    def source_candidate(record, path, line)
+      if v2_rich_end?(record)
+        build_row(record, path, line, :v2)
+      elsif legacy_rich?(record)
+        build_row(record, path, line, :legacy)
+      end
+    end
+
+    def v2_rich_end?(record)
+      record.is_a?(Hash) &&
+        record["schema_version"] == 2 &&
+        record["record_type"] == "dispatch_end" &&
+        !record["id"].to_s.empty? &&
+        !record["session_id"].to_s.empty? &&
+        normalized_time(record["started_at"]) &&
+        record["actual"].is_a?(Hash)
+    end
+
+    def legacy_rich?(record)
+      return false unless record.is_a?(Hash)
+
+      meta = record["meta"]
+      rich_key_count = legacy_rich_key_count(record)
+      meta.is_a?(Hash) &&
+        !meta["id"].to_s.empty? &&
+        normalized_time(meta["started_at"]) &&
+        record["actual"].is_a?(Hash) &&
+        (rich_key_count >= 2 || meta["harness"] == "harnex" && rich_key_count.positive?)
+    end
+
+    def build_row(record, path, line, family)
+      id = family == :v2 ? record["id"].to_s : record.dig("meta", "id").to_s
+      started_at = normalized_time(family == :v2 ? record["started_at"] : record.dig("meta", "started_at"))
+      session_id = family == :v2 ? record["session_id"].to_s : nil
+      identity = family == :v2 ? ["v2", session_id, id, started_at] : ["legacy", id, started_at]
+      Row.new(
+        record: record,
+        path: path,
+        line: line,
+        family: family,
+        identity: identity,
+        match_identity: [id, started_at],
+        sort_key: [started_at, path, line]
+      )
+    end
+
+    def find_match(row, canonical_rows)
+      same_family = canonical_rows.find { |candidate| candidate.identity == row.identity }
+      return same_family if same_family
+
+      canonical_rows.find { |candidate| candidate.match_identity == row.match_identity }
+    end
+
+    def source_conflicts(rows)
+      conflicts = []
+      rows.group_by(&:identity).each_value do |group|
+        first = group.first
+        group.drop(1).each { |row| conflicts << [first, row] unless payload_equal?(first.record, row.record) }
+      end
+      rows.group_by(&:match_identity).each_value do |group|
+        next unless group.map(&:family).uniq.length > 1
+
+        group.combination(2) do |left, right|
+          next if left.family == right.family
+
+          conflicts << [left, right] unless rows_payload_equal?(left, right)
+        end
+      end
+      conflicts
+    end
+
+    def dedupe_source_rows(rows)
+      selected = []
+      rows.sort_by { |row| [row.sort_key[0], row.match_identity, family_preference(row), row.path, row.line] }.each do |row|
+        next if selected.any? { |candidate| candidate.identity == row.identity }
+
+        match = selected.find { |candidate| candidate.family != row.family && candidate.match_identity == row.match_identity }
+        next if match && rows_payload_equal?(match, row)
+
+        selected << row
+      end
+      selected
+    end
+
+    def dedupe_rows(rows)
+      seen = Set.new
+      rows.sort_by(&:sort_key).select do |row|
+        key = row.identity
+        next false if seen.include?(key)
+
+        seen << key
+        true
+      end
+    end
+
+    def legacy_rich_key_count(record) = (RICH_KEYS & record.keys).length
+
+    def family_preference(row) = row.family == :legacy ? 0 : 1
+
+    def append_missing_under_lock(rows)
+      FileUtils.mkdir_p(File.dirname(@canonical))
+      File.open(@canonical, File::RDWR | File::CREAT, 0o644) do |file|
+        file.flock(File::LOCK_EX)
+        file.rewind
+        existing = file.read
+        locked = analyze
+        return [0, locked] unless writable?(locked)
+
+        still_missing = locked[:missing_rows].select { |row| rows.any? { |wanted| wanted.identity == row.identity } }
+        payload = still_missing.map { |row| JSON.generate(row.record) }.join("\n")
+        payload = "\n#{payload}" unless existing.empty? || existing.end_with?("\n")
+        payload = "#{payload}\n" unless payload.empty?
+        file.seek(0, IO::SEEK_END)
+        file.write(payload)
+        file.flush
+        [still_missing.length, locked.merge(missing_rows: [])]
+      ensure
+        file.flock(File::LOCK_UN) unless file.closed?
+      end
+    end
+
+    def payload_equal?(left, right) = deep_normalize(left) == deep_normalize(right)
+
+    def rows_payload_equal?(left, right)
+      if left.family != right.family
+        comparable_rich_payload(left.record) == comparable_rich_payload(right.record)
+      else
+        payload_equal?(left.record, right.record)
+      end
+    end
+
+    def comparable_rich_payload(record)
+      keys = ["meta", "actual"] + RICH_KEYS
+      deep_normalize(record.select { |key, _value| keys.include?(key) })
+    end
+
+    def deep_normalize(value)
+      case value
+      when Hash
+        value.keys.sort.to_h do |key|
+          normalized =
+            if key == "started_at"
+              normalized_time(value[key]) || value[key]
+            else
+              deep_normalize(value[key])
+            end
+          [key, normalized]
+        end
+      when Array
+        value.map { |item| deep_normalize(item) }
+      else
+        value
+      end
+    end
+
+    def normalized_time(value)
+      Time.iso8601(value.to_s).utc.iso8601
+    rescue ArgumentError
+      nil
+    end
+
+    def realpath_or_expand(path)
+      File.realpath(path)
+    rescue Errno::ENOENT, Errno::EACCES
+      File.expand_path(path)
+    end
+
+    def identity_label(row) = row.identity.join("|")
+
+    def reset_diagnostics
+      @diagnostics = []
+      @diagnostics_truncated = 0
+    end
+
+    def diagnostic(message)
+      if @diagnostics.length < MAX_DIAGNOSTICS
+        @diagnostics << message
+      else
+        @diagnostics_truncated += 1
+      end
+    end
+  end
+end

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.10.0"
-  RELEASE_DATE = "2026-08-03"
+  VERSION = "0.10.2"
+  RELEASE_DATE = "2026-08-08"
 end

data/lib/harnex.rb

@@ -11,6 +11,7 @@ require_relative "harnex/pricing"
 require_relative "harnex/terminal_status"
 require_relative "harnex/artifact_report"
 require_relative "harnex/context_telemetry"
+require_relative "harnex/telemetry_reconciler"
 require_relative "harnex/orchestration"
 require_relative "harnex/watcher"
 require_relative "harnex/adapters"
@@ -37,4 +38,5 @@ require_relative "harnex/commands/agents_guide"
 require_relative "harnex/commands/doctor"
 require_relative "harnex/commands/orchestration"
 require_relative "harnex/commands/artifact_report"
+require_relative "harnex/commands/telemetry"
 require_relative "harnex/cli"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.2
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-03 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies: []
 description: A local PTY harness that wraps terminal AI agents (Claude, Codex, Pi)
   and adds a control plane for discovery, messaging, and coordination.
@@ -61,6 +61,7 @@ files:
 - lib/harnex/commands/send.rb
 - lib/harnex/commands/status.rb
 - lib/harnex/commands/stop.rb
+- lib/harnex/commands/telemetry.rb
 - lib/harnex/commands/wait.rb
 - lib/harnex/commands/watch.rb
 - lib/harnex/commands/watch_presets.rb
@@ -77,6 +78,7 @@ files:
 - lib/harnex/runtime/message.rb
 - lib/harnex/runtime/session.rb
 - lib/harnex/runtime/session_state.rb
+- lib/harnex/telemetry_reconciler.rb
 - lib/harnex/terminal_status.rb
 - lib/harnex/version.rb
 - lib/harnex/watcher.rb