harnex 0.7.12 → 0.7.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da71f86b7e940d085a54ae59ce7f70a9579ca23204213cbc41a017fd5d11ed9f
-  data.tar.gz: 194f3ac0c6fabf118e74542dd4836c5014721cdf0000973b03be07dceceeee3e
+  metadata.gz: e087c98409987c2494911c830e3670a23abc5129ed22030bebd7cee953f920fd
+  data.tar.gz: 036eb960f719874ba7f7954bcf3c4191ca324d4ff77f7098069b231327efbd87
 SHA512:
-  metadata.gz: 7975b8610b1d21c230fb0ccf7b55c16bdd9e9ff71c770bdb42f831e687313e47c9e01b20157fc8f95c767bdf716e3501fcb56a490d37dfb277f7ac1bd03fda74
-  data.tar.gz: 54e0d45f362d94efa2d0d698911c2d2b1daaf534c97be95bef99512d3c6ab8ad44bdb6d099eaff6d5bb38e08acee563901d94db528ab0b03df8a856648c88dd5
+  metadata.gz: a96531d075117e46512181ebb89fff0c0abb3ffbd829807d4fa9624b5c684255fc896882455678b7cce0e9094be11d4279beb5a6af84ad0a23e2974496d5d173
+  data.tar.gz: 530d365ae7a6bbd2d2d9f34a708babb8f5c9446290808ed23170fc8329997c2b9c6ce5dd62ae326905bec7f46cd222253b4815c61d484c9e600d40ff675d4fee

data/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [0.7.13] - 2026-07-15 | 12:24 PM | IST
+
+### Added
+
+- Dispatch summaries now include a stable additive `context` block with
+  terminal and peak active-context pressure, source/status provenance, bounded
+  sample counts, and explicit missing-sample handling. Pi RPC reports observed
+  `get_session_stats.contextUsage`; Codex app-server conservatively estimates
+  pressure from `tokenUsage.last` plus `modelContextWindow`; unsupported
+  adapters do not fabricate values.
+- Dispatch summaries now include additive `usage`, `attribution`, `outcome`, and
+  per-session `attempt` blocks. `usage.status` distinguishes provider-observed,
+  explicit-zero, caller-estimated, unsupported, and missing values so nullable
+  cost/token fields are never mistaken for zero.
+- `harnex run` accepts `--parent-dispatch-id`, `--parent-attempt-id`, and
+  `--attempt-kind` (`initial`, `retry`, `fix`, `review`, or `superseding`) to
+  preserve parent/child relationships while retaining separate raw effort rows.
+- Terminal event streams now emit `attempt_started` / `attempt_finished` and
+  translate Pi internal retry notices into `attempt_retry_scheduled`; the
+  Session exposes an `attempt_fallback_switched` telemetry seam for recovery
+  and fallback owners.
+- Bounded artifact reports can optionally record a semantic outcome
+  (`accepted`, `rejected`, `no_change`, or `unknown`). Final outcome blocks
+  retain git commit/path/LOC observations without claiming they prove authorship.
+
+### Changed
+
+- Dispatch telemetry documentation now distinguishes cumulative usage from
+  active context-window pressure and defines context sample/high-water/null
+  semantics alongside usage-cost provenance, strict attribution quality,
+  sidecar-backed outcomes, attempt linkage, and safe throughput/reliability
+  query examples.
+
 ## [0.7.12] - 2026-07-10 | 11:19 PM | IST
 
 ### Fixed

data/README.md

@@ -281,8 +281,9 @@ harnex run pi --id pi-i-52 \
 The sidecar schema is `harnex.artifact_report.v1`; harnex exposes the path as
 `HARNEX_ARTIFACT_REPORT_PATH` / `HARNEX_VALIDATION_REPORT_PATH`, then records a
 compact `artifact_report`, `validation`, and `artifacts` summary in the dispatch
-row. Missing or malformed reports are warning telemetry, not wrapped-process
-crashes.
+row. A sidecar can also assert the bounded outcome (`accepted`, `rejected`,
+`no_change`, or `unknown`); git changes alone never imply semantic acceptance.
+Missing or malformed reports are warning telemetry, not wrapped-process crashes.
 
 Queue runners can pass first-class attribution without hiding it in prose:
 
@@ -293,13 +294,15 @@ harnex run pi --project-id harnex --queue-id queue-005 --entry-id SP-4 \
 
 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`,
-`output_bytes`, and `event_records`.
+blocks. Every terminal row also has `usage` (so null is distinguishable from
+explicit zero or an estimate), `attribution`, `outcome`, and a joinable
+per-session `attempt` block. 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`, `output_bytes`, and
+`event_records`.
 Harnex records the data only; consumers decide whether to fail closed. See
 [docs/dispatch-telemetry.md](docs/dispatch-telemetry.md) for the field
 contract.

data/lib/harnex/adapters/base.rb

@@ -73,6 +73,22 @@ module Harnex
         {}
       end
 
+      # Whether this adapter has a supported source for token/cost telemetry.
+      # A supported source can still be missing for a particular run.
+      def usage_telemetry_supported?
+        false
+      end
+
+      # Whether this adapter exposes active context-window occupancy separately
+      # from cumulative usage. Supported sources can still yield no valid sample.
+      def context_telemetry_supported?
+        false
+      end
+
+      def context_telemetry_source
+        nil
+      end
+
       def send_wait_seconds(submit:, enter_only:)
         0.0
       end

data/lib/harnex/adapters/codex.rb

@@ -60,6 +60,10 @@ module Harnex
         end
       end
 
+      def usage_telemetry_supported?
+        true
+      end
+
       def parse_session_summary(transcript_tail)
         summary = empty_session_summary
         text = transcript_tail.to_s

data/lib/harnex/adapters/codex_appserver.rb

@@ -74,6 +74,18 @@ module Harnex
         "openai"
       end
 
+      def usage_telemetry_supported?
+        true
+      end
+
+      def context_telemetry_supported?
+        true
+      end
+
+      def context_telemetry_source
+        "codex_thread_token_usage_last"
+      end
+
       def base_command
         ["codex", "app-server"]
       end

data/lib/harnex/adapters/pi.rb

@@ -31,6 +31,10 @@ module Harnex
         @write_mutex = Mutex.new
         @summary_mutex = Mutex.new
         @session_summary = {}
+        @context_telemetry = ContextTelemetry.new(
+          status: "observed",
+          source: context_telemetry_source
+        )
         @model = nil
         @provider = nil
         @session_stats_requested = false
@@ -49,6 +53,18 @@ module Harnex
         @model
       end
 
+      def usage_telemetry_supported?
+        true
+      end
+
+      def context_telemetry_supported?
+        true
+      end
+
+      def context_telemetry_source
+        "pi_get_session_stats"
+      end
+
       def base_command
         ["pi", "--mode", "rpc"]
       end
@@ -147,11 +163,17 @@ module Harnex
 
       def request_session_stats_async
         return if @closed
-        return if @session_stats_requested
 
-        @session_stats_requested = true
+        should_request = @summary_mutex.synchronize do
+          next false if @session_stats_requested
+
+          @session_stats_requested = true
+        end
+        return unless should_request
+
         write_line("type" => "get_session_stats")
       rescue StandardError
+        clear_session_stats_request
         nil
       end
 
@@ -181,8 +203,10 @@ module Harnex
             agent_session_id: @session_summary[:agent_session_id],
             tool_calls: @session_summary[:tool_calls],
             cost_usd: @session_summary[:cost_usd],
+            cost_source: @session_summary[:cost_source],
             model: @session_summary[:model],
-            agent_provider: @session_summary[:agent_provider]
+            agent_provider: @session_summary[:agent_provider],
+            context: @context_telemetry.snapshot
           }
         end
       end
@@ -263,8 +287,7 @@ module Harnex
       end
 
       def attempt_live_summary_refresh
-        response = request("type" => "get_session_stats")
-        absorb_session_stats(response)
+        request("type" => "get_session_stats")
       rescue StandardError
         nil
       end
@@ -338,6 +361,8 @@ module Harnex
           @state = :prompt
           @last_completed_at = Time.now
           request_session_stats_async
+        when "compaction_end"
+          request_session_stats_async
         when "message_end"
           absorb_model_from_message(message["message"])
         end
@@ -362,6 +387,8 @@ module Harnex
         return unless data.is_a?(Hash)
 
         tokens = data["tokens"] || {}
+        context_usage = data["contextUsage"]
+        context_usage = {} unless context_usage.is_a?(Hash)
         @summary_mutex.synchronize do
           @session_summary[:input_tokens] = numeric_or_nil(tokens["input"])
           @session_summary[:output_tokens] = numeric_or_nil(tokens["output"])
@@ -369,10 +396,24 @@ module Harnex
           @session_summary[:total_tokens] = numeric_or_nil(tokens["total"])
           @session_summary[:tool_calls] = numeric_or_nil(data["toolCalls"])
           @session_summary[:cost_usd] = float_or_nil(data["cost"])
+          @session_summary[:cost_source] = "provider_reported" unless @session_summary[:cost_usd].nil?
           @session_summary[:agent_session_id] = data["sessionId"] if data["sessionId"]
           @session_summary[:model] = @model if @model
           @session_summary[:agent_provider] = @provider if @provider
+          @context_telemetry.record(
+            tokens: context_usage["tokens"],
+            window_tokens: context_usage["contextWindow"],
+            percent: context_usage["percent"]
+          )
         end
+      ensure
+        clear_session_stats_request
+      end
+
+      def clear_session_stats_request
+        @summary_mutex.synchronize { @session_stats_requested = false }
+      rescue StandardError
+        @session_stats_requested = false
       end
 
       def absorb_model_from_message(message)

data/lib/harnex/artifact_report.rb

@@ -74,6 +74,7 @@ module Harnex
     def build_payload(path, bytes:, sha256:, report:)
       artifacts = compact_artifacts(report["artifacts"])
       validation = compact_validation(report["validation"])
+      outcome = compact_outcome(report["outcome"])
       payload = {
         "artifact_report" => metadata(
           path,
@@ -89,6 +90,7 @@ module Harnex
       }
       payload["validation"] = validation if validation
       payload["artifacts"] = artifacts unless artifacts.empty?
+      payload["outcome"] = outcome if outcome
       payload
     end
 
@@ -144,6 +146,21 @@ module Harnex
       end
     end
 
+    def compact_outcome(value)
+      return nil unless value.is_a?(Hash)
+
+      status = value["status"].to_s
+      return nil unless %w[accepted rejected no_change unknown].include?(status)
+
+      payload = {
+        "status" => status,
+        "summary" => bounded_string_or_nil(value["summary"]),
+        "commit_sha" => bounded_string_or_nil(value["commit_sha"])
+      }
+      payload.delete_if { |_key, item| item.nil? }
+      payload
+    end
+
     def compact_artifacts(value)
       Array(value).first(MAX_ARTIFACTS).filter_map do |entry|
         next unless entry.is_a?(Hash)

data/lib/harnex/commands/run.rb

@@ -16,7 +16,10 @@ 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"
     }.freeze
     TELEMETRY_KEYS_TO_FLAGS = TELEMETRY_FLAGS.invert.freeze
     TELEMETRY_EQUALS_PREFIXES = TELEMETRY_FLAGS.keys.map { |flag| "#{flag}=" }.freeze
@@ -70,6 +73,12 @@ 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)
           --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
@@ -155,6 +164,7 @@ module Harnex
       raise OptionParser::MissingArgument, "cli" if cli_name.nil?
       validate_auto_stop_context!
       apply_telemetry_options!
+      validate_attempt_metadata!
       validate_required_attribution!
 
       repo_root = resolve_run_root(cli_name, child_args)
@@ -674,6 +684,15 @@ 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_required_attribution!
       return unless @options[:require_attribution]
 

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

data/lib/harnex/runtime/session.rb

@@ -9,8 +9,21 @@ module Harnex
     AUTOSTOP_TEARDOWN_GRACE_SECONDS_DEFAULT = 5.0
     USAGE_FIELDS = %i[
       input_tokens output_tokens reasoning_tokens cached_tokens total_tokens
-      agent_session_id cost_usd tool_calls model agent_provider
+      agent_session_id cost_usd cost_source tool_calls model agent_provider
     ].freeze
+    USAGE_MEASUREMENT_FIELDS = %i[
+      input_tokens output_tokens reasoning_tokens cached_tokens total_tokens cost_usd
+    ].freeze
+    USAGE_STATUSES = %w[observed estimated unsupported missing zero].freeze
+    CONTEXT_FIELDS = %i[
+      status source terminal_tokens window_tokens terminal_percent peak_tokens
+      peak_percent samples missing_samples latest_sample_status
+    ].freeze
+    CONTEXT_MEASUREMENT_FIELDS = %i[
+      terminal_tokens terminal_percent peak_tokens peak_percent
+    ].freeze
+    CONTEXT_SAMPLE_STATUSES = %w[observed estimated missing].freeze
+    ATTEMPT_KINDS = %w[initial retry fix review superseding].freeze
     SESSION_SUMMARY_SIGNAL_FIELDS = %i[
       input_tokens output_tokens reasoning_tokens cached_tokens total_tokens
       agent_session_id cost_usd
@@ -29,6 +42,8 @@ module Harnex
           force_resumes: 0,
           disconnections: 0,
           compactions: 0,
+          retries: 0,
+          throttle_429: 0,
           tool_calls: 0,
           commands_executed: 0
         }
@@ -44,6 +59,10 @@ module Harnex
           @counts[:disconnections] += 1
         when "compaction"
           @counts[:compactions] += 1
+        when "attempt_retry_scheduled"
+          @counts[:retries] += 1
+        when "throttle_429"
+          @counts[:throttle_429] += 1
         end
       end
 
@@ -107,6 +126,8 @@ module Harnex
       @git_start = {}
       @git_end = {}
       @usage_summary = {}
+      @context_summary = {}
+      @rpc_context_telemetry = nil
       @ended_at = nil
       @exit_reason = nil
       @last_error = nil
@@ -262,6 +283,23 @@ module Harnex
       !!@last_failed_at
     end
 
+    # Public seam for structured recovery/fallback owners (#42 / plan 30).
+    # The current session remains the parent attempt; a recovery implementation
+    # supplies a new child attempt id when it starts an independently billable arm.
+    def record_attempt_transition(type:, child_attempt_id: nil, trigger: nil)
+      unless %w[attempt_retry_scheduled attempt_fallback_switched].include?(type.to_s)
+        raise ArgumentError, "unsupported attempt transition #{type.inspect}"
+      end
+
+      emit_event(
+        type.to_s,
+        **attempt_lifecycle_context.merge(
+          child_attempt_id: summary_string(child_attempt_id),
+          trigger: summary_string(trigger)
+        )
+      )
+    end
+
     def git_start
       @git_start || {}
     end
@@ -524,8 +562,12 @@ module Harnex
         # Schema: ThreadTokenUsageUpdatedNotification carries
         # `tokenUsage: { last, total, modelContextWindow? }` where each
         # breakdown has camelCase {input,output,cachedInput,reasoningOutput,total}Tokens.
-        # Snapshot it; the cumulative `total` is read at session end.
-        @token_usage = params["tokenUsage"] if params["tokenUsage"].is_a?(Hash)
+        # Snapshot cumulative `total` for usage and aggregate `last` separately
+        # as conservative active-context pressure.
+        if params["tokenUsage"].is_a?(Hash)
+          @token_usage = params["tokenUsage"]
+          record_rpc_context_sample(@token_usage)
+        end
       when "thread/status/changed"
         # State machine reflects RPC state; no event needed.
         nil
@@ -544,6 +586,7 @@ module Harnex
           threadId: params["threadId"],
           turnId: params["turnId"]
         )
+        emit_event("throttle_429", source: "error_notification", message: message) if throttle_429?(message, params)
         signal_rpc_done! if params["turnId"].to_s.empty?
       end
     rescue StandardError => e
@@ -583,6 +626,13 @@ module Harnex
       error.is_a?(Hash) ? error["codexErrorInfo"] : nil
     end
 
+    def throttle_429?(message, params)
+      return true if message.to_s.match?(/\b429\b|rate limit/i)
+
+      error = params["error"]
+      error.is_a?(Hash) && error.values.any? { |value| value.to_s.match?(/\b429\b|rate limit/i) }
+    end
+
     def extract_turn_error_message(turn)
       error = turn["error"]
       return error["message"] if error.is_a?(Hash)
@@ -641,7 +691,9 @@ module Harnex
       when "queue_update"
         nil
       when "auto_retry_start", "auto_retry_end"
-        emit_event(event_type, **message.reject { |k, _| k == "type" })
+        payload = message.reject { |k, _| k == "type" }
+        emit_event(event_type, **payload)
+        record_attempt_transition(type: "attempt_retry_scheduled", trigger: "adapter_auto_retry") if event_type == "auto_retry_start"
       when "extension_ui_request"
         handle_extension_ui_request(message)
       when "extension_error"
@@ -987,6 +1039,10 @@ module Harnex
       payload = { pid: @pid }
       payload[:meta] = meta if meta
       emit_event("started", **payload)
+      emit_event(
+        "attempt_started",
+        **attempt_lifecycle_context.merge(kind: summary_attempt_kind)
+      )
     end
 
     def emit_git_start_event
@@ -997,7 +1053,9 @@ module Harnex
     end
 
     def emit_session_end_telemetry
-      @usage_summary = normalized_usage_summary(collect_session_summary)
+      summary = collect_session_summary
+      @usage_summary = normalized_usage_summary(summary)
+      @context_summary = normalized_context_summary(summary)
       emit_event("usage", **@usage_summary)
 
       @git_end = Harnex.git_capture_end(repo_root, @git_start[:sha])
@@ -1010,6 +1068,7 @@ module Harnex
         loc_added: @git_end[:loc_added],
         loc_removed: @git_end[:loc_removed],
         files_changed: @git_end[:files_changed],
+        changed_paths: @git_end[:changed_paths],
         commits: @git_end[:commits]
       )
     end
@@ -1018,6 +1077,19 @@ module Harnex
       emit_event("summary", path: summary_out, exit: @exit_reason)
     end
 
+    def emit_attempt_finished(attempt)
+      emit_event(
+        "attempt_finished",
+        **attempt_lifecycle_context.merge(
+          parent_attempt_id: attempt["parent_attempt_id"],
+          status: attempt["status"],
+          exit_reason: attempt["exit_reason"],
+          end_ts: attempt["end_ts"],
+          wall_ms: attempt["wall_ms"]
+        )
+      )
+    end
+
     def emit_exit_event
       payload = { code: @exit_code }
       payload[:signal] = @term_signal if @term_signal
@@ -1035,12 +1107,15 @@ module Harnex
         emit_session_end_telemetry
       rescue StandardError => e
         @usage_summary = normalized_usage_summary(nil)
+        @context_summary = normalized_context_summary(nil)
         warn("harnex: failed to collect session-end telemetry: #{e.message}")
       end
       @exit_reason ||= classify_exit
-      append_summary_record(build_summary_record)
+      record = build_summary_record
+      append_summary_record(record)
       append_dispatch_history_record
       emit_summary_event
+      emit_attempt_finished(record.fetch(:attempt))
       emit_exit_event
     end
 
@@ -1170,16 +1245,24 @@ module Harnex
     end
 
     def build_summary_record
+      artifact_payload = artifact_report_path ? artifact_report_summary : nil
+      attribution = build_summary_attribution
+      outcome = build_summary_outcome(artifact_payload)
       record = {
         meta: build_summary_meta,
         predicted: summary_predicted_payload,
-        actual: build_summary_actual,
+        actual: build_summary_actual(outcome: outcome, attribution: attribution),
         agent: build_summary_agent,
+        usage: build_summary_usage,
+        context: build_summary_context,
+        attribution: attribution,
+        outcome: outcome,
+        attempt: build_summary_attempt,
         reliability: build_summary_reliability
       }
       queue = build_summary_queue
       record[:queue] = queue if queue
-      record.merge!(artifact_report_summary) if artifact_report_path
+      record.merge!(artifact_payload.reject { |key, _value| key == "outcome" }) if artifact_payload
       record
     end
 
@@ -1235,6 +1318,203 @@ module Harnex
       }
     end
 
+    def build_summary_usage
+      declared = meta_hash["usage"].is_a?(Hash) ? meta_hash["usage"] : {}
+      observed = USAGE_MEASUREMENT_FIELDS.any? { |field| !@usage_summary[field].nil? }
+      values = USAGE_MEASUREMENT_FIELDS.to_h do |field|
+        [field, @usage_summary[field].nil? ? declared_usage_value(declared, field) : @usage_summary[field]]
+      end
+      numeric_observations = USAGE_MEASUREMENT_FIELDS.filter_map do |field|
+        value = @usage_summary[field]
+        value if value.is_a?(Numeric)
+      end
+      estimated = declared["status"].to_s == "estimated"
+      status = if observed && numeric_observations.any? && numeric_observations.all?(&:zero?)
+                 "zero"
+               elsif observed
+                 "observed"
+               elsif estimated
+                 "estimated"
+               elsif adapter.usage_telemetry_supported?
+                 "missing"
+               else
+                 "unsupported"
+               end
+      cost_source = summary_string(@usage_summary[:cost_source])
+      cost_source ||= "provider_reported" if !@usage_summary[:cost_usd].nil?
+      cost_source ||= summary_string(declared["cost_source"]) || "caller_estimate" if status == "estimated"
+
+      {
+        "status" => status,
+        "cost_usd" => values[:cost_usd],
+        "cost_source" => cost_source,
+        "input_tokens" => values[:input_tokens],
+        "output_tokens" => values[:output_tokens],
+        "cached_input_tokens" => values[:cached_tokens],
+        "reasoning_tokens" => values[:reasoning_tokens],
+        "total_tokens" => values[:total_tokens]
+      }
+    end
+
+    def build_summary_context
+      measurement_present = CONTEXT_MEASUREMENT_FIELDS.any? do |field|
+        @context_summary[field].is_a?(Numeric)
+      end
+      reported_status = summary_string(@context_summary[:status])
+      status = if measurement_present
+                 %w[observed estimated].include?(reported_status) ? reported_status : "observed"
+               elsif adapter.context_telemetry_supported?
+                 "missing"
+               else
+                 "unsupported"
+               end
+      source = summary_string(@context_summary[:source])
+      source ||= adapter.context_telemetry_source if adapter.context_telemetry_supported?
+      latest_sample_status = summary_string(@context_summary[:latest_sample_status])
+      latest_sample_status = nil unless CONTEXT_SAMPLE_STATUSES.include?(latest_sample_status)
+
+      {
+        "status" => status,
+        "source" => source,
+        "terminal_tokens" => @context_summary[:terminal_tokens],
+        "window_tokens" => @context_summary[:window_tokens],
+        "terminal_percent" => @context_summary[:terminal_percent],
+        "peak_tokens" => @context_summary[:peak_tokens],
+        "peak_percent" => @context_summary[:peak_percent],
+        "samples" => context_sample_count(:samples),
+        "missing_samples" => context_sample_count(:missing_samples),
+        "latest_sample_status" => latest_sample_status
+      }
+    end
+
+    def context_sample_count(field)
+      value = @context_summary[field]
+      return 0 unless value.is_a?(Numeric) && value.finite? && !value.negative?
+
+      value.to_i
+    end
+
+    def declared_usage_value(declared, field)
+      return nil unless declared["status"].to_s == "estimated"
+
+      declared[field.to_s] || declared[usage_field_alias(field)]
+    end
+
+    def usage_field_alias(field)
+      field == :cached_tokens ? "cached_input_tokens" : field.to_s
+    end
+
+    def build_summary_attribution
+      queue = build_summary_queue || {}
+      required = %w[project_id phase intent]
+      work_fields = %w[entry_id issue plan queue_id]
+      required_complete = required.all? { |field| !queue[field].nil? }
+      work_field = work_fields.find { |field| !queue[field].nil? }
+      known = required.any? { |field| !queue[field].nil? } || work_field
+      status = required_complete && work_field ? "complete" : (known ? "partial" : "missing")
+
+      {
+        "status" => status,
+        "project_id" => queue["project_id"],
+        "phase" => queue["phase"],
+        "intent" => queue["intent"],
+        "work_type" => work_field,
+        "work_id" => work_field ? queue[work_field] : nil
+      }
+    end
+
+    def build_summary_outcome(artifact_payload)
+      sidecar_outcome = artifact_payload&.dig("outcome") || {}
+      status = sidecar_outcome["status"]
+      status = "no_change" if status.nil? && @git_end.key?(:changed_paths) && @git_end[:changed_paths].empty?
+      status ||= "unknown"
+      status = "unknown" unless %w[accepted rejected no_change unknown].include?(status)
+
+      {
+        "status" => status,
+        "source" => sidecar_outcome["status"] ? "artifact_report" : "harnex_git_observation",
+        "commit_sha" => sidecar_outcome["commit_sha"] || summary_commit_sha,
+        "changed_paths" => @git_end.key?(:changed_paths) ? @git_end[:changed_paths] : nil,
+        "loc_added" => @git_end[:loc_added],
+        "loc_removed" => @git_end[:loc_removed],
+        "lines_changed" => summary_lines_changed,
+        "files_changed" => @git_end[:files_changed],
+        "commits" => @git_end[:commits]
+      }
+    end
+
+    def build_summary_attempt
+      {
+        "run_id" => id,
+        "id" => session_id,
+        "parent_attempt_id" => summary_string(meta_hash["parent_attempt_id"]),
+        "parent_dispatch_id" => summary_string(meta_hash["parent_dispatch_id"]) || @parent_harnex_id,
+        "kind" => summary_attempt_kind,
+        "project_id" => summary_string(meta_hash["project_id"]),
+        "phase" => summary_string(meta_hash["phase"]),
+        "intent" => summary_string(meta_hash["intent"]),
+        "model_requested" => summary_string(meta_hash["model"]),
+        "model_effective" => summary_string(summary_model),
+        "deployment_effective" => summary_service_tier,
+        "reasoning_effort" => summary_string(meta_hash["effort"]),
+        "started_at" => @started_at.iso8601,
+        "ended_at" => @ended_at&.iso8601,
+        "start_ts" => @started_at.iso8601,
+        "end_ts" => @ended_at&.iso8601,
+        "wall_ms" => @ended_at ? ((@ended_at - @started_at) * 1000).round : nil,
+        "exit_reason" => @exit_reason,
+        "status" => summary_attempt_succeeded? ? "succeeded" : "failed"
+      }
+    end
+
+    def attempt_lifecycle_context
+      {
+        run_id: id,
+        attempt_id: session_id,
+        parent_attempt_id: summary_string(meta_hash["parent_attempt_id"]),
+        parent_dispatch_id: summary_string(meta_hash["parent_dispatch_id"]) || @parent_harnex_id,
+        project: summary_string(meta_hash["project_id"]),
+        phase: summary_string(meta_hash["phase"]),
+        intent: summary_string(meta_hash["intent"]),
+        model_requested: summary_string(meta_hash["model"]),
+        model_effective: summary_string(summary_model),
+        deployment_effective: summary_service_tier,
+        reasoning_effort: summary_string(meta_hash["effort"]),
+        start_ts: @started_at.iso8601
+      }
+    end
+
+    def summary_attempt_kind
+      candidate = summary_string(meta_hash["attempt_kind"])
+      ATTEMPT_KINDS.include?(candidate) ? candidate : "initial"
+    end
+
+    def summary_attempt_succeeded?
+      return false if task_failed?
+
+      @exit_reason == "success"
+    end
+
+    def accepted_throughput_tokens_per_s(total_tokens, duration_s, accepted)
+      return nil unless accepted && total_tokens.is_a?(Numeric) && duration_s.to_f.positive?
+
+      total_tokens.to_f / duration_s
+    end
+
+    def accepted_throughput_successes_per_h(duration_s, accepted)
+      return nil unless accepted && duration_s.to_f.positive?
+
+      3600.0 / duration_s
+    end
+
+    def summary_commit_sha
+      start_sha = @git_start[:sha].to_s
+      end_sha = @git_end[:sha].to_s
+      return nil if start_sha.empty? || end_sha.empty? || start_sha == end_sha
+
+      end_sha
+    end
+
     def build_summary_reliability
       counters = reliability_event_counters
       real_disconnections = counters[:disconnections].to_i
@@ -1249,14 +1529,18 @@ module Harnex
       }
     end
 
-    def build_summary_actual
+    def build_summary_actual(outcome:, attribution:)
       counters = legacy_summary_event_counters
       output_measurements = summary_output_measurements
+      accepted = outcome["status"] == "accepted"
+      duration_s = @ended_at ? (@ended_at - @started_at).to_i : nil
+      attempt_succeeded = summary_attempt_succeeded?
+      total_tokens = @usage_summary[:total_tokens]
 
       actual = {
         model: summary_model,
         effort: meta_hash["effort"],
-        duration_s: @ended_at ? (@ended_at - @started_at).to_i : nil,
+        duration_s: duration_s,
         input_tokens: @usage_summary[:input_tokens],
         output_tokens: @usage_summary[:output_tokens],
         reasoning_tokens: @usage_summary[:reasoning_tokens],
@@ -1287,7 +1571,18 @@ module Harnex
         output_bytes: output_measurements[:bytes],
         event_records: @events_log_seq,
         output_log_path: output_log_path,
-        events_log_path: events_log_path
+        events_log_path: events_log_path,
+        attempts_total: 1,
+        attempts_succeeded: attempt_succeeded ? 1 : 0,
+        attempts_failed: attempt_succeeded ? 0 : 1,
+        retry_count: counters[:retries],
+        throttle_429_count: counters[:throttle_429],
+        disconnect_count: counters[:disconnections],
+        throughput_tokens_per_s: accepted_throughput_tokens_per_s(total_tokens, duration_s, accepted),
+        throughput_successes_per_h: accepted_throughput_successes_per_h(duration_s, accepted),
+        retry_tax_pct: counters[:retries].to_i.zero? ? 0.0 : nil,
+        unattributed: attribution["status"] != "complete",
+        fallback_triggered: false
       }
       actual
     end
@@ -1445,6 +1740,20 @@ module Harnex
       USAGE_FIELDS.to_h { |field| [field, summary[field] || summary[field.to_s]] }
     end
 
+    def normalized_context_summary(summary)
+      summary ||= {}
+      context = summary[:context] || summary["context"]
+      context = {} unless context.is_a?(Hash)
+      CONTEXT_FIELDS.to_h do |field|
+        value = if context.key?(field)
+                  context[field]
+                else
+                  context[field.to_s]
+                end
+        [field, value]
+      end
+    end
+
     # Structured adapters emit usage directly (JSON-RPC token snapshots,
     # Pi RPC stats). PTY adapters parse transcript tails when supported.
     def collect_session_summary
@@ -1458,18 +1767,34 @@ module Harnex
     end
 
     def summary_from_token_usage
-      return {} unless @token_usage.is_a?(Hash)
+      summary = {}
+      if @token_usage.is_a?(Hash) && @token_usage["total"].is_a?(Hash)
+        total = @token_usage["total"]
+        summary.merge!(
+          input_tokens: total["inputTokens"],
+          output_tokens: total["outputTokens"],
+          reasoning_tokens: total["reasoningOutputTokens"],
+          cached_tokens: total["cachedInputTokens"],
+          total_tokens: total["totalTokens"]
+        )
+      end
+      summary[:context] = @rpc_context_telemetry.snapshot if @rpc_context_telemetry
+      summary
+    end
 
-      total = @token_usage["total"]
-      return {} unless total.is_a?(Hash)
+    def record_rpc_context_sample(token_usage)
+      return unless adapter.context_telemetry_supported?
 
-      {
-        input_tokens: total["inputTokens"],
-        output_tokens: total["outputTokens"],
-        reasoning_tokens: total["reasoningOutputTokens"],
-        cached_tokens: total["cachedInputTokens"],
-        total_tokens: total["totalTokens"]
-      }
+      @rpc_context_telemetry ||= ContextTelemetry.new(
+        status: "estimated",
+        source: adapter.context_telemetry_source
+      )
+      last = token_usage["last"]
+      last = {} unless last.is_a?(Hash)
+      @rpc_context_telemetry.record(
+        tokens: last["totalTokens"],
+        window_tokens: token_usage["modelContextWindow"]
+      )
     end
 
     def transcript_tail

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.7.12"
-  RELEASE_DATE = "2026-07-10"
+  VERSION = "0.7.13"
+  RELEASE_DATE = "2026-07-15"
 end

data/lib/harnex.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.7.12
+  version: 0.7.13
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-07-15 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.
@@ -58,6 +58,7 @@ files:
 - lib/harnex/commands/wait.rb
 - lib/harnex/commands/watch.rb
 - lib/harnex/commands/watch_presets.rb
+- lib/harnex/context_telemetry.rb
 - lib/harnex/core.rb
 - lib/harnex/dispatch_history.rb
 - lib/harnex/runtime/api_server.rb