harnex 0.7.12 → 0.7.14

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
@@ -18,6 +31,9 @@ module Harnex
     BUDGET_META_FIELDS = %w[read_budget_lines output_ceiling_lines].freeze
     QUEUE_FIELDS = %w[project_id queue_id entry_id entry_title issue plan phase tier intent].freeze
     AGENT_FIELDS = %w[cli provider model_requested model_effective reasoning_effort service_tier adapter_transport].freeze
+    ORCHESTRATION_FIELDS = %w[
+      run_id generation_id role project_id queue_id session_id rotation_reason
+    ].freeze
     RELIABILITY_FIELDS = %w[
       adapter_close real_disconnections stream_interruptions stalls force_resumes compactions recovered
     ].freeze
@@ -29,6 +45,8 @@ module Harnex
           force_resumes: 0,
           disconnections: 0,
           compactions: 0,
+          retries: 0,
+          throttle_429: 0,
           tool_calls: 0,
           commands_executed: 0
         }
@@ -44,6 +62,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
 
@@ -51,7 +73,7 @@ module Harnex
         return unless item.is_a?(Hash)
 
         case item["type"]
-        when "mcpToolCall", "dynamicToolCall"
+        when "mcpToolCall", "dynamicToolCall", "fileChange", "webSearch"
           @counts[:tool_calls] += 1
         when "commandExecution"
           @counts[:commands_executed] += 1
@@ -65,9 +87,9 @@ module Harnex
 
     attr_reader :repo_root, :launch_cwd, :child_cwd, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch,
                 :inbox, :description, :meta, :summary_out, :artifact_report_path, :output_log_path, :events_log_path,
-                :started_at, :ended_at, :exit_code, :term_signal
+                :started_at, :ended_at, :exit_code, :term_signal, :require_artifact_report
 
-    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, summary_out: nil, artifact_report_path: nil, inbox_ttl: Inbox::DEFAULT_TTL, auto_stop: false, launch_cwd: nil, child_cwd: nil)
+    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, summary_out: nil, artifact_report_path: nil, require_artifact_report: false, inbox_ttl: Inbox::DEFAULT_TTL, auto_stop: false, launch_cwd: nil, child_cwd: nil)
       @adapter = adapter
       @command = command
       @repo_root = repo_root
@@ -84,6 +106,9 @@ module Harnex
       @artifact_report_path = artifact_report_path.to_s.strip
       @artifact_report_path = nil if @artifact_report_path.empty?
       @artifact_report_path = File.expand_path(@artifact_report_path, repo_root) if @artifact_report_path
+      @require_artifact_report = !!require_artifact_report
+      raise ArgumentError, "require_artifact_report requires artifact_report_path" if @require_artifact_report && !@artifact_report_path
+      @artifact_report_start_fingerprint = Harnex::ArtifactReport.fingerprint(@artifact_report_path) if @artifact_report_path
       @registry_path = Harnex.registry_path(repo_root, @id)
       @output_log_path = Harnex.output_log_path(repo_root, @id)
       @events_log_path = Harnex.events_log_path(repo_root, @id)
@@ -107,6 +132,8 @@ module Harnex
       @git_start = {}
       @git_end = {}
       @usage_summary = {}
+      @context_summary = {}
+      @rpc_context_telemetry = nil
       @ended_at = nil
       @exit_reason = nil
       @last_error = nil
@@ -115,6 +142,9 @@ module Harnex
       @last_completed_at = nil
       @last_failed_at = nil
       @last_failed_status = nil
+      @completion_outcome_class = nil
+      @completion_report_status = nil
+      @completion_diagnostics = []
       @pi_streamed_text_by_message = {}
       @auto_stop = !!auto_stop
       @auto_stop_fired = false
@@ -187,6 +217,8 @@ module Harnex
       @exit_code = status.exited? ? status.exitstatus : 128 + status.termsig
       @ended_at = Time.now
 
+      enforce_required_artifact_report!
+      normalize_work_acceptance_exit_code!
       normalize_auto_stop_exit_code!
       drain_auto_stop_threads
       output_thread.join(1)
@@ -247,6 +279,8 @@ module Harnex
       payload[:task_failed] = task_failed
       payload[:done] = Harnex.work_done_for("running", task_complete: task_complete)
       payload[:work_state] = work_state
+      payload[:outcome_class] = @completion_outcome_class
+      payload[:artifact_report_status] = @completion_report_status
       payload[:last_error] = @last_error
       payload[:model] = summary_model
       payload[:effort] = meta_hash["effort"]
@@ -262,6 +296,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
@@ -444,6 +495,8 @@ module Harnex
       end
       @ended_at = Time.now
 
+      enforce_required_artifact_report!
+      normalize_work_acceptance_exit_code!
       normalize_auto_stop_exit_code!
       drain_auto_stop_threads
       finalize_session!
@@ -502,8 +555,7 @@ module Harnex
         payload[:status] = status if status
         payload[:tokenUsage] = params["tokenUsage"] if params["tokenUsage"].is_a?(Hash)
         if successful_turn_status?(status)
-          @last_completed_at = Time.now
-          emit_event("task_complete", **payload)
+          record_successful_completion(payload)
         else
           mark_task_failed(
             turn_id: turn_id,
@@ -524,8 +576,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 +600,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
@@ -557,15 +614,170 @@ module Harnex
       SUCCESSFUL_TURN_STATUSES.include?(text)
     end
 
-    def mark_task_failed(turn_id: nil, status: nil, error: nil, codex_error_info: nil)
+    def record_successful_completion(payload)
+      assessment = completion_gate_required? ? assess_completion_proof : { accepted: true }
+      unless assessment[:accepted]
+        mark_task_failed(
+          turn_id: payload[:turnId],
+          status: assessment.fetch(:outcome_class),
+          error: completion_failure_message(assessment.fetch(:outcome_class)),
+          outcome_class: assessment.fetch(:outcome_class),
+          artifact_report_status: assessment[:report_status],
+          diagnostics: assessment[:diagnostics]
+        )
+        return false
+      end
+
+      @last_failed_at = nil
+      @last_failed_status = nil
+      @last_error = nil
+      @last_completed_at = Time.now
+      if assessment[:outcome_class]
+        @completion_outcome_class = assessment[:outcome_class]
+        @completion_report_status = assessment[:report_status]
+        @completion_diagnostics = []
+      end
+
+      event_payload = payload.dup
+      event_payload[:outcome_class] = @completion_outcome_class if @completion_outcome_class
+      event_payload[:artifact_report_status] = @completion_report_status if @completion_report_status
+      emit_event("task_complete", **event_payload)
+      true
+    end
+
+    def completion_gate_required?
+      return true if require_artifact_report
+      return false unless adapter.transport == :stdio_jsonrpc
+
+      @auto_stop || (adapter.respond_to?(:initial_prompt) && !adapter.initial_prompt.to_s.empty?)
+    end
+
+    def assess_completion_proof
+      report_result = artifact_report_path ? Harnex::ArtifactReport.validate(artifact_report_path, final: true) : nil
+      report_fresh = report_result && report_result.status != "missing" && artifact_report_fresh?
+      report_stale = report_result && Harnex::ArtifactReport.accepted_final?(report_result) && !report_fresh
+      report_status = report_stale ? "stale" : report_result&.status
+      report_diagnostics = if report_stale
+                             [artifact_report_stale_diagnostic]
+                           else
+                             report_result&.diagnostics || []
+                           end
+
+      if report_result
+        if report_fresh && Harnex::ArtifactReport.accepted_final?(report_result)
+          return {
+            accepted: true,
+            outcome_class: "completed_with_proof",
+            report_status: "accepted",
+            diagnostics: []
+          }
+        end
+
+        report_outcome = Harnex::ArtifactReport.outcome_status(report_result)
+        if report_fresh && report_outcome == "rejected"
+          return {
+            accepted: false,
+            outcome_class: "report_rejected",
+            report_status: "rejected",
+            diagnostics: report_result.diagnostics
+          }
+        end
+
+        if require_artifact_report
+          outcome_class = report_result.status == "missing" ? "report_missing" : "report_invalid"
+          return {
+            accepted: false,
+            outcome_class: outcome_class,
+            report_status: report_status,
+            diagnostics: report_diagnostics
+          }
+        end
+      elsif require_artifact_report
+        return {
+          accepted: false,
+          outcome_class: "report_missing",
+          report_status: "missing",
+          diagnostics: []
+        }
+      end
+
+      if structured_activity_observed? || git_activity_observed?
+        {
+          accepted: true,
+          outcome_class: "completed_with_activity",
+          report_status: report_status,
+          diagnostics: []
+        }
+      else
+        {
+          accepted: false,
+          outcome_class: "completed_no_activity",
+          report_status: report_status,
+          diagnostics: report_diagnostics
+        }
+      end
+    end
+
+    def artifact_report_fresh?
+      current = Harnex::ArtifactReport.fingerprint(artifact_report_path)
+      return false unless current
+      return true unless @artifact_report_start_fingerprint
+
+      current != @artifact_report_start_fingerprint
+    end
+
+    def artifact_report_stale_diagnostic
+      {
+        "code" => "report_stale",
+        "path" => "$",
+        "message" => "artifact report was not created or updated during this session"
+      }
+    end
+
+    def structured_activity_observed?
+      counters = @event_counters.snapshot
+      counters[:commands_executed].to_i.positive? || counters[:tool_calls].to_i.positive?
+    end
+
+    def git_activity_observed?
+      return false if @git_start[:sha].to_s.empty?
+
+      snapshot = Harnex.git_capture_end(repo_root, @git_start[:sha])
+      snapshot[:commits].to_i.positive? || Array(snapshot[:changed_paths]).any? ||
+        (!snapshot[:sha].to_s.empty? && snapshot[:sha].to_s != @git_start[:sha].to_s)
+    end
+
+    def completion_failure_message(outcome_class)
+      case outcome_class
+      when "completed_no_activity"
+        "turn completed without command/tool execution, Git delta, or accepted artifact report"
+      when "report_missing"
+        "required artifact report is missing"
+      when "report_rejected"
+        "artifact report rejected work completion"
+      when "report_invalid"
+        "required artifact report is not valid final proof"
+      else
+        "work completion was not accepted"
+      end
+    end
+
+    def mark_task_failed(turn_id: nil, status: nil, error: nil, codex_error_info: nil, outcome_class: nil, artifact_report_status: nil, diagnostics: nil)
+      @last_completed_at = nil if outcome_class
       @last_failed_at = Time.now
       @last_failed_status = status.to_s.empty? ? "failed" : status.to_s
       @last_error = error.to_s unless error.to_s.empty?
+      @completion_outcome_class = outcome_class if outcome_class
+      @completion_report_status = artifact_report_status if artifact_report_status
+      @completion_diagnostics = Array(diagnostics).first(Harnex::ArtifactReport::MAX_DIAGNOSTICS) if diagnostics
 
       payload = { status: @last_failed_status }
       payload[:turnId] = turn_id if turn_id
       payload[:message] = error unless error.to_s.empty?
       payload[:codex_error_info] = codex_error_info if codex_error_info
+      payload[:outcome_class] = outcome_class if outcome_class
+      payload[:artifact_report_status] = artifact_report_status if artifact_report_status
+      payload[:diagnostics] = @completion_diagnostics unless @completion_diagnostics.empty?
       emit_event("task_failed", **payload)
     end
 
@@ -583,6 +795,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)
@@ -605,9 +824,8 @@ module Harnex
         @state_machine.force_busy!
         emit_event("turn_started") if event_type == "turn_start"
       when "agent_end"
-        @last_completed_at = Time.now
         @state_machine.force_prompt!
-        emit_event("task_complete")
+        record_successful_completion({})
         adapter.request_session_stats_async if adapter.respond_to?(:request_session_stats_async)
         schedule_auto_stop("task_complete", interrupt: false)
       when "message_start"
@@ -641,7 +859,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"
@@ -784,6 +1004,7 @@ module Harnex
         env["HARNEX_ARTIFACT_REPORT_PATH"] = artifact_report_path
         env["HARNEX_VALIDATION_REPORT_PATH"] = artifact_report_path
         env["HARNEX_ARTIFACT_REPORT_SCHEMA"] = Harnex::ArtifactReport::SCHEMA
+        env["HARNEX_ARTIFACT_REPORT_REQUIRED"] = "1" if require_artifact_report
       end
       env["HARNEX_SPAWNER_PANE"] = ENV["TMUX_PANE"] if ENV["TMUX_PANE"]
       env
@@ -868,6 +1089,8 @@ module Harnex
         task_failed: task_failed,
         done: Harnex.work_done_for(state, task_complete: task_complete),
         work_state: Harnex.work_state_for(state, task_complete: task_complete),
+        outcome_class: @completion_outcome_class,
+        artifact_report_status: @completion_report_status,
         started_at: @started_at.iso8601,
         exited_at: Time.now.iso8601,
         injected_count: @injected_count
@@ -987,6 +1210,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 +1224,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 +1239,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 +1248,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 +1278,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
 
@@ -1068,7 +1314,10 @@ module Harnex
       seen_busy = @auto_stop_mutex.synchronize do
         @auto_stop_seen_busy ||= old_state == :busy || new_state == :busy
       end
-      schedule_auto_stop("prompt_after_busy") if seen_busy && new_state == :prompt
+      return unless seen_busy && new_state == :prompt
+
+      record_successful_completion({}) if require_artifact_report
+      schedule_auto_stop("prompt_after_busy")
     end
 
     def schedule_auto_stop(reason, turn_id: nil, interrupt: true)
@@ -1130,6 +1379,55 @@ module Harnex
       AUTOSTOP_TEARDOWN_GRACE_SECONDS_DEFAULT
     end
 
+    def enforce_required_artifact_report!
+      return unless require_artifact_report
+      return if task_failed? && %w[report_missing report_invalid report_rejected].include?(@completion_outcome_class)
+
+      result = Harnex::ArtifactReport.validate(artifact_report_path, final: true)
+      report_fresh = result.status != "missing" && artifact_report_fresh?
+      report_accepted = Harnex::ArtifactReport.accepted_final?(result)
+      report_stale = report_accepted && !report_fresh
+      if report_fresh && report_accepted
+        @completion_outcome_class = "completed_with_proof"
+        @completion_report_status = "accepted"
+        @completion_diagnostics = []
+        return
+      end
+
+      report_outcome = Harnex::ArtifactReport.outcome_status(result)
+      outcome_class = if report_fresh && report_outcome == "rejected"
+                        "report_rejected"
+                      elsif result.status == "missing"
+                        "report_missing"
+                      else
+                        "report_invalid"
+                      end
+      report_status = if report_stale
+                        "stale"
+                      elsif report_fresh && report_outcome == "rejected"
+                        "rejected"
+                      else
+                        result.status
+                      end
+      diagnostics = report_stale ? [artifact_report_stale_diagnostic] : result.diagnostics
+      mark_task_failed(
+        status: outcome_class,
+        error: completion_failure_message(outcome_class),
+        outcome_class: outcome_class,
+        artifact_report_status: report_status,
+        diagnostics: diagnostics
+      )
+      @exit_code = 1 if @exit_code.nil? || @exit_code.zero? || @term_signal
+      @term_signal = nil if @exit_code == 1
+    end
+
+    def normalize_work_acceptance_exit_code!
+      return unless task_failed? && @completion_outcome_class
+
+      @exit_code = 1 if @exit_code.nil? || @exit_code.zero? || @term_signal
+      @term_signal = nil if @exit_code == 1
+    end
+
     def normalize_auto_stop_exit_code!
       return unless @auto_stop
       return unless @auto_stop_fired
@@ -1148,9 +1446,11 @@ module Harnex
 
     def classify_exit
       return "timeout" if @exit_code == 124
+      return "failure" if task_failed? && @completion_outcome_class
       return "boot_failure" if boot_failure_exit?
       return "failure" if task_failed?
       return "success" if @exit_code == 0 && task_complete?
+      return "success" if @exit_code == 0 && @completion_outcome_class == "completed_with_proof"
       return "success" if @exit_code == 0 && session_summary_present?
       return "failure" unless @exit_code == 0
 
@@ -1170,16 +1470,26 @@ 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
+      orchestration = build_summary_orchestration
+      record[:orchestration] = orchestration if orchestration
+      record.merge!(artifact_payload.reject { |key, _value| key == "outcome" }) if artifact_payload
       record
     end
 
@@ -1223,6 +1533,14 @@ module Harnex
       queue
     end
 
+    def build_summary_orchestration
+      orchestration = Orchestration.normalize_metadata(meta_hash)
+      return nil unless orchestration
+
+      orchestration["session_id"] ||= summary_agent_session_id || session_id
+      orchestration
+    end
+
     def build_summary_agent
       {
         "cli" => adapter.key,
@@ -1235,6 +1553,233 @@ 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") || {}
+      outcome_class, report_status = summary_proof_classification
+      proof_failure = %w[completed_no_activity report_missing report_invalid task_failed].include?(outcome_class)
+      status = proof_failure ? nil : sidecar_outcome["status"]
+      status = "no_change" if status.nil? && !proof_failure && @git_end.key?(:changed_paths) && @git_end[:changed_paths].empty?
+      status ||= "unknown"
+      status = "unknown" unless Harnex::ArtifactReport::OUTCOME_STATUSES.include?(status)
+      source = if proof_failure
+                 "harnex_completion_gate"
+               elsif sidecar_outcome["status"]
+                 "artifact_report"
+               else
+                 "harnex_git_observation"
+               end
+
+      {
+        "status" => status,
+        "class" => outcome_class,
+        "source" => source,
+        "report_status" => report_status,
+        "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 summary_proof_classification
+      return [@completion_outcome_class, @completion_report_status] if @completion_outcome_class
+      return ["task_failed", @completion_report_status] if task_failed?
+
+      if artifact_report_path
+        result = Harnex::ArtifactReport.validate(artifact_report_path, final: true)
+        report_fresh = result.status != "missing" && artifact_report_fresh?
+        report_accepted = Harnex::ArtifactReport.accepted_final?(result)
+        return ["completed_with_proof", "accepted"] if report_fresh && report_accepted
+        return ["report_rejected", "rejected"] if report_fresh && Harnex::ArtifactReport.outcome_status(result) == "rejected"
+        return ["unknown", "stale"] if report_accepted && !report_fresh
+        return ["unknown", result.status]
+      end
+
+      return ["completed_with_activity", @completion_report_status] if task_complete? && structured_activity_observed?
+
+      ["unknown", @completion_report_status]
+    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 +1794,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 +1836,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 +2005,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 +2032,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