harnex 0.7.13 → 0.8.0

data/lib/harnex/commands/artifact_report.rb

@@ -0,0 +1,94 @@
+require "json"
+require "optparse"
+
+module Harnex
+  class ArtifactReportCommand
+    def self.usage(program_name = "harnex artifact-report")
+      <<~TEXT
+        Usage:
+          #{program_name} init PATH [--force]
+          #{program_name} validate PATH [--final]
+
+        Commands:
+          init       Write a bounded harnex.artifact_report.v1 skeleton
+          validate   Validate schema and field shapes without printing report data
+
+        Options:
+          --final    Require an accepted/no_change final outcome, passing proof,
+                     and validation.final_reported=true
+          --force    Replace an existing file during init
+          -h, --help Show this help
+
+        Both commands print machine-readable JSON. `validate` exits 0 only when
+        the requested contract is satisfied; diagnostics contain field paths and
+        shape errors, never report payloads or transcripts.
+      TEXT
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      command = @argv.shift
+      case command
+      when "init"
+        run_init(@argv)
+      when "validate"
+        run_validate(@argv)
+      when nil, "help", "-h", "--help"
+        puts self.class.usage
+        0
+      else
+        raise OptionParser::ParseError, "unknown artifact-report command #{command.inspect}"
+      end
+    end
+
+    private
+
+    def run_init(argv)
+      options = { force: false, help: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: harnex artifact-report init PATH [--force]"
+        opts.on("--force", "Replace an existing report") { options[:force] = true }
+        opts.on("-h", "--help", "Show help") { options[:help] = true }
+      end
+      parser.parse!(argv)
+      return print_help if options[:help]
+
+      path = exactly_one_path!(argv, parser)
+      report_path = ArtifactReport.initialize_file(path, force: options[:force])
+      result = ArtifactReport.validate(report_path)
+      puts JSON.generate(result.public_payload(final: false).merge("created" => true))
+      result.ok ? 0 : 1
+    end
+
+    def run_validate(argv)
+      options = { final: false, help: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: harnex artifact-report validate PATH [--final]"
+        opts.on("--final", "Require accepted final proof") { options[:final] = true }
+        opts.on("-h", "--help", "Show help") { options[:help] = true }
+      end
+      parser.parse!(argv)
+      return print_help if options[:help]
+
+      path = exactly_one_path!(argv, parser)
+      result = ArtifactReport.validate(path, final: options[:final])
+      puts JSON.generate(result.public_payload(final: options[:final]))
+      result.ok ? 0 : 1
+    end
+
+    def exactly_one_path!(argv, parser)
+      raise OptionParser::MissingArgument, "PATH" if argv.empty?
+      raise OptionParser::InvalidArgument, "expected exactly one PATH\n#{parser}" unless argv.length == 1
+
+      argv.first
+    end
+
+    def print_help
+      puts self.class.usage
+      0
+    end
+  end
+end

data/lib/harnex/commands/history.rb

@@ -1,5 +1,6 @@
 require "json"
 require "optparse"
+require "set"
 require "time"
 
 module Harnex
@@ -74,13 +75,60 @@ module Harnex
     end
 
     def filtered_records
-      records = load_records
+      records = derived_records
       records = records.select { |record| record["id"].to_s.include?(@options[:id]) } if @options[:id]
       records = records.select { |record| started_after?(record, @options[:since]) } if @options[:since]
       records = records.last(@options[:limit]) unless @options[:all]
       records
     end
 
+    # One row per dispatch: start rows completed by an end row are dropped
+    # (the end row carries the outcome); uncompleted start rows surface as
+    # running (pid alive on this host) or interrupted (no end row, pid gone).
+    def derived_records
+      raw = load_records
+      ended = Set.new
+      raw.each do |record|
+        next unless DispatchHistory.end_record?(record)
+
+        session_id = record["session_id"].to_s
+        ended << "sid:#{session_id}" unless session_id.empty?
+        ended << "leg:#{record['id']}|#{record['started_at']}"
+      end
+
+      raw.filter_map do |record|
+        next record unless DispatchHistory.start_record?(record)
+        next nil if start_completed?(record, ended)
+
+        derive_live_record(record)
+      end
+    end
+
+    def start_completed?(record, ended)
+      session_id = record["session_id"].to_s
+      return true if !session_id.empty? && ended.include?("sid:#{session_id}")
+
+      ended.include?("leg:#{record['id']}|#{record['started_at']}")
+    end
+
+    def derive_live_record(record)
+      alive = DispatchHistory.same_host?(record) &&
+              record["pid"] && Harnex.alive_pid?(record["pid"])
+      record.merge(
+        "status" => alive ? "running" : "interrupted",
+        "terminal_event" => nil,
+        "duration_s" => alive ? seconds_since(record["started_at"]) : nil,
+        "ended_at" => nil
+      )
+    end
+
+    def seconds_since(timestamp)
+      seconds = (Time.now - Time.iso8601(timestamp.to_s)).to_i
+      seconds.negative? ? 0 : seconds
+    rescue ArgumentError
+      nil
+    end
+
     def load_records
       path = DispatchHistory.path_for(Dir.pwd, global: @options[:global])
       return [] unless File.file?(path)
@@ -129,7 +177,9 @@ module Harnex
     end
 
     def format_duration(value)
-      seconds = Integer(value || 0)
+      return "-" if value.nil?
+
+      seconds = Integer(value)
       hours = seconds / 3600
       minutes = (seconds % 3600) / 60
       rest = seconds % 60

data/lib/harnex/commands/orchestration.rb

@@ -0,0 +1,170 @@
+require "json"
+require "optparse"
+
+module Harnex
+  class OrchestrationCommand
+    def self.usage(program_name = "harnex orchestration")
+      <<~TEXT
+        Usage:
+          #{program_name} sample --out PATH --run-id ID --generation-id ID [options]
+          #{program_name} report --dispatch PATH --run-id ID [--samples PATH] [--json]
+
+        Sample options:
+          --project-id ID
+          --queue-id ID
+          --session-id ID
+          --event NAME                  sample, generation_started, generation_finished, rotation, recovery, or compaction
+          --ts ISO8601
+          --context-status STATUS       observed, estimated, unsupported, missing, or zero
+          --context-tokens N
+          --context-window-tokens N
+          --context-percent N
+          --context-peak-tokens N
+          --context-peak-percent N
+          --usage-status STATUS         observed, estimated, unsupported, missing, or zero
+          --usage-input-tokens N
+          --usage-output-tokens N
+          --usage-cached-input-tokens N
+          --usage-reasoning-tokens N
+          --usage-total-tokens N
+          --usage-cost-usd N
+          --usage-cost-source TEXT
+          --tool-calls N
+          --compactions N
+          --rotation-reason TEXT
+
+        Report options:
+          --dispatch PATH               Dispatch summary JSONL
+          --samples PATH                External primary sample JSONL
+          --run-id ID                   Logical orchestration run id
+          --json                        Output the full report JSON
+          -h, --help                    Show this help
+      TEXT
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      subcommand = @argv.shift
+      case subcommand
+      when "sample"
+        run_sample(@argv)
+      when "report"
+        run_report(@argv)
+      when "-h", "--help", nil
+        puts self.class.usage
+        0
+      else
+        raise OptionParser::ParseError, "unknown orchestration subcommand #{subcommand.inspect}"
+      end
+    end
+
+    private
+
+    def run_sample(argv)
+      options = {
+        context: {},
+        usage: {}
+      }
+      sample_parser(options).parse!(argv)
+      if options.delete(:help)
+        puts self.class.usage
+        return 0
+      end
+      path = required_option(options.delete(:out), "--out")
+      options["orchestration_run_id"] = required_option(options.delete(:run_id), "--run-id")
+      options["generation_id"] = required_option(options.delete(:generation_id), "--generation-id")
+      sample = Harnex::Orchestration.append_sample(path, options)
+      puts JSON.generate("ok" => true, "path" => path, "sample" => sample)
+      0
+    end
+
+    def run_report(argv)
+      options = { json: false }
+      report_parser(options).parse!(argv)
+      if options[:help]
+        puts self.class.usage
+        return 0
+      end
+      report = Harnex::Orchestration.report(
+        dispatch_path: required_option(options[:dispatch], "--dispatch"),
+        samples_path: options[:samples],
+        run_id: required_option(options[:run_id], "--run-id")
+      )
+      if options[:json]
+        puts JSON.generate(report)
+      else
+        puts render_report(report)
+      end
+      0
+    end
+
+    def sample_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: harnex orchestration sample --out PATH --run-id ID --generation-id ID [options]"
+        opts.on("--out PATH") { |value| options[:out] = value }
+        opts.on("--run-id ID") { |value| options[:run_id] = value }
+        opts.on("--generation-id ID") { |value| options[:generation_id] = value }
+        opts.on("--project-id ID") { |value| options["project_id"] = value }
+        opts.on("--queue-id ID") { |value| options["queue_id"] = value }
+        opts.on("--session-id ID") { |value| options["session_id"] = value }
+        opts.on("--event NAME") { |value| options["event"] = value }
+        opts.on("--ts ISO8601") { |value| options["ts"] = value }
+        opts.on("--context-status STATUS") { |value| options[:context]["status"] = value }
+        opts.on("--context-tokens N") { |value| options[:context]["terminal_tokens"] = value }
+        opts.on("--context-window-tokens N") { |value| options[:context]["window_tokens"] = value }
+        opts.on("--context-percent N") { |value| options[:context]["terminal_percent"] = value }
+        opts.on("--context-peak-tokens N") { |value| options[:context]["peak_tokens"] = value }
+        opts.on("--context-peak-percent N") { |value| options[:context]["peak_percent"] = value }
+        opts.on("--usage-status STATUS") { |value| options[:usage]["status"] = value }
+        opts.on("--usage-input-tokens N") { |value| options[:usage]["input_tokens"] = value }
+        opts.on("--usage-output-tokens N") { |value| options[:usage]["output_tokens"] = value }
+        opts.on("--usage-cached-input-tokens N") { |value| options[:usage]["cached_input_tokens"] = value }
+        opts.on("--usage-reasoning-tokens N") { |value| options[:usage]["reasoning_tokens"] = value }
+        opts.on("--usage-total-tokens N") { |value| options[:usage]["total_tokens"] = value }
+        opts.on("--usage-cost-usd N") { |value| options[:usage]["cost_usd"] = value }
+        opts.on("--usage-cost-source TEXT") { |value| options[:usage]["cost_source"] = value }
+        opts.on("--tool-calls N") { |value| options["tool_calls"] = value }
+        opts.on("--compactions N") { |value| options["compactions"] = value }
+        opts.on("--rotation-reason TEXT") { |value| options["rotation_reason"] = value }
+        opts.on("-h", "--help") { options[:help] = true }
+      end
+    end
+
+    def report_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: harnex orchestration report --dispatch PATH --run-id ID [options]"
+        opts.on("--dispatch PATH") { |value| options[:dispatch] = value }
+        opts.on("--samples PATH") { |value| options[:samples] = value }
+        opts.on("--run-id ID") { |value| options[:run_id] = value }
+        opts.on("--json") { options[:json] = true }
+        opts.on("-h", "--help") { options[:help] = true }
+      end
+    end
+
+    def required_option(value, name)
+      text = value.to_s.strip
+      raise OptionParser::MissingArgument, name if text.empty?
+
+      text
+    end
+
+    def render_report(report)
+      primary = report.fetch("primary")
+      workers = report.fetch("workers")
+      ratios = report.fetch("ratios")
+      [
+        "Run: #{report.fetch('orchestration_run_id')}",
+        "Primary: generations=#{primary.fetch('generation_count')} usage=#{primary.dig('usage', 'status')} total_tokens=#{format_value(primary.dig('usage', 'total_tokens'))} peak_context=#{format_value(primary.dig('context', 'peak_tokens'))} tool_calls=#{primary.fetch('tool_calls')}",
+        "Workers: dispatches=#{workers.fetch('dispatches')} usage=#{workers.dig('usage', 'status')} active_s=#{workers.fetch('active_s')} accepted=#{workers.dig('outcomes', 'accepted')} rejected=#{workers.dig('outcomes', 'rejected')} blocked=#{workers.dig('outcomes', 'blocked')} unknown=#{workers.dig('outcomes', 'unknown')}",
+        "Ratios: primary_tokens_per_accepted_entry=#{format_value(ratios.fetch('primary_total_tokens_per_accepted_entry'))} primary_tool_calls_per_accepted_entry=#{format_value(ratios.fetch('primary_tool_calls_per_accepted_entry'))}"
+      ].join("\n")
+    end
+
+    def format_value(value)
+      value.nil? ? "-" : value
+    end
+  end
+end

data/lib/harnex/commands/run.rb

@@ -19,7 +19,12 @@ module Harnex
       "--effort" => "effort",
       "--parent-dispatch-id" => "parent_dispatch_id",
       "--parent-attempt-id" => "parent_attempt_id",
-      "--attempt-kind" => "attempt_kind"
+      "--attempt-kind" => "attempt_kind",
+      "--orchestration-run-id" => "orchestration_run_id",
+      "--orchestration-generation-id" => "orchestration_generation_id",
+      "--orchestration-role" => "orchestration_role",
+      "--orchestration-session-id" => "orchestration_session_id",
+      "--orchestration-rotation-reason" => "orchestration_rotation_reason"
     }.freeze
     TELEMETRY_KEYS_TO_FLAGS = TELEMETRY_FLAGS.invert.freeze
     TELEMETRY_EQUALS_PREFIXES = TELEMETRY_FLAGS.keys.map { |flag| "#{flag}=" }.freeze
@@ -28,8 +33,13 @@ module Harnex
       --id --description --detach --tmux --host --port --watch --watch-file
       --stall-after --max-resumes --preset --context --meta --summary-out
       --artifact-report --validation-report --cwd --root --timeout --inbox-ttl
-      --require-attribution --auto-stop --fast --legacy-pty --help
+      --require-artifact-report --require-attribution --auto-stop --fast --legacy-pty
+      --allow-live-parent --help
     ].concat(TELEMETRY_FLAGS.keys).freeze
+
+    # Attempt kinds that redo the parent's work; dispatching one while the
+    # parent is still running duplicates work in the same checkout.
+    LIVE_PARENT_GUARDED_KINDS = %w[retry fix superseding].freeze
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
       --max-resumes --preset --context --meta --summary-out --artifact-report
@@ -53,7 +63,7 @@ module Harnex
           --preset NAME      Watch preset: impl, plan, gate (requires --watch)
           --watch-file PATH  Auto-send a file-change hook on modification
           --context TEXT     Inject as the initial prompt (prepends session header)
-          --auto-stop        Stop after the first task completion from --context
+          --auto-stop        Stop after the first accepted task completion from --context
           --fast             (codex only) Use Codex service_tier="fast".
                              Default Codex runs force service_tier="flex".
           --meta JSON        Attach parsed JSON metadata to the started event
@@ -62,6 +72,9 @@ module Harnex
                              Worker-written harnex.artifact_report.v1 JSON sidecar to ingest at exit
           --validation-report PATH
                              Alias for --artifact-report; also exposed as HARNEX_VALIDATION_REPORT_PATH
+          --require-artifact-report
+                             Fail closed unless PATH contains accepted final proof;
+                             requires --artifact-report or --validation-report
           --project-id ID    Queue telemetry project id (first-class flags override --meta)
           --queue-id ID      Queue telemetry queue id
           --entry-id ID      Queue telemetry entry id
@@ -78,7 +91,23 @@ module Harnex
           --parent-attempt-id ID
                              Parent attempt id for retry/fix/review joins
           --attempt-kind KIND
-                             initial, retry, fix, review, or superseding (default: initial)
+                             initial, retry, fix, review, or superseding (default: initial).
+                             retry requires --parent-dispatch-id so the
+                             duplicate-dispatch guard can verify the parent
+          --allow-live-parent
+                             Dispatch even though --parent-dispatch-id names a
+                             session that is still running (intentional
+                             parallelism, e.g. isolated worktrees)
+          --orchestration-run-id ID
+                             Logical primary-orchestrator run id for queue rollups
+          --orchestration-generation-id ID
+                             Primary generation id after rotation/recovery boundaries
+          --orchestration-role ROLE
+                             primary or worker; defaults to worker in rollups when omitted
+          --orchestration-session-id ID
+                             External primary session id to preserve in rollups
+          --orchestration-rotation-reason TEXT
+                             Clean rotation/recovery reason for the generation
           --require-attribution
                              Fail before launch unless project/phase/intent and one work id are present
           --cwd DIR          Run the wrapped agent from DIR and use DIR as the session root
@@ -94,7 +123,9 @@ module Harnex
         Notes:
           Compatibility: `--watch PATH` and `--watch=PATH` still configure file-hook mode.
           Bare `--watch` enables the babysitter.
-          --auto-stop requires --context and fires once after the first completion.
+          --auto-stop requires --context. Structured Codex turns only count as
+          accepted completion after activity, Git delta, or accepted sidecar proof.
+          --require-artifact-report makes sidecar validation part of the run verdict.
           Explicit --stall-after/--max-resumes values override --preset defaults.
           CLIs with smart prompt detection: #{Adapters.known.join(', ')}
           Any other CLI name is launched with generic wrapping.
@@ -140,9 +171,11 @@ module Harnex
         require_attribution: false,
         summary_out: nil,
         artifact_report: nil,
+        require_artifact_report: false,
         cwd: nil,
         root: nil,
         auto_stop: false,
+        allow_live_parent: false,
         detach: false,
         tmux: false,
         tmux_name: nil,
@@ -163,8 +196,10 @@ module Harnex
 
       raise OptionParser::MissingArgument, "cli" if cli_name.nil?
       validate_auto_stop_context!
+      validate_required_artifact_report!
       apply_telemetry_options!
       validate_attempt_metadata!
+      validate_orchestration_metadata!
       validate_required_attribution!
 
       repo_root = resolve_run_root(cli_name, child_args)
@@ -172,6 +207,7 @@ module Harnex
       @options[:artifact_report] = resolve_artifact_report(repo_root)
       @options[:id] ||= Harnex.generate_id(repo_root)
       validate_unique_id!(repo_root)
+      validate_live_parent_guard!(repo_root)
       effective_child_args = apply_context(apply_codex_service_tier(cli_name, child_args))
       adapter = Harnex.build_adapter(cli_name, effective_child_args, legacy_pty: @options[:legacy_pty])
       @options[:detach] = true if @options[:tmux]
@@ -235,8 +271,10 @@ module Harnex
         tmux_cmd += [flag, value] if flag && value
       end
       tmux_cmd << "--require-attribution" if @options[:require_attribution]
+      tmux_cmd << "--allow-live-parent" if @options[:allow_live_parent]
       tmux_cmd += ["--summary-out", @options[:summary_out]] if @options[:summary_out]
       tmux_cmd += ["--artifact-report", @options[:artifact_report]] if @options[:artifact_report]
+      tmux_cmd << "--require-artifact-report" if @options[:require_artifact_report]
       tmux_cmd += ["--cwd", @options[:cwd]] if @options[:cwd]
       tmux_cmd += ["--root", @options[:root]] if @options[:root]
       tmux_cmd += ["--inbox-ttl", @options[:inbox_ttl].to_s]
@@ -333,6 +371,33 @@ module Harnex
             "Use a different --id or stop the existing session first."
     end
 
+    # Duplicate-dispatch guard (issue #62): a retry/fix/superseding attempt
+    # whose parent dispatch is still running would duplicate work in the same
+    # checkout. Explicit --parent-dispatch-id only — the implicit HARNEX_ID
+    # lineage of a live spawner must not trip this.
+    def validate_live_parent_guard!(repo_root)
+      metadata = @options[:meta].is_a?(Hash) ? @options[:meta] : {}
+      kind = metadata["attempt_kind"].to_s
+      parent_id = metadata["parent_dispatch_id"].to_s.strip
+
+      if kind == "retry" && parent_id.empty?
+        raise "harnex run: --attempt-kind retry requires --parent-dispatch-id " \
+              "so the duplicate-dispatch guard can verify the parent is not still running."
+      end
+
+      return if @options[:allow_live_parent]
+      return if parent_id.empty?
+      return unless LIVE_PARENT_GUARDED_KINDS.include?(kind)
+
+      live = Harnex.active_sessions(repo_root, id: parent_id).first
+      return unless live
+
+      raise "harnex run: refusing #{kind} dispatch — parent dispatch #{parent_id.inspect} " \
+            "is still running (pid #{live['pid']}, started #{live['started_at']}). " \
+            "Wait for it (harnex wait --id #{parent_id} --until done), stop it, " \
+            "or pass --allow-live-parent for intentional parallelism."
+    end
+
     def build_session(adapter, repo_root)
       watch = Harnex.build_watch_config(@options[:watch], repo_root)
       Session.new(
@@ -347,6 +412,7 @@ module Harnex
         meta: @options[:meta],
         summary_out: @options[:summary_out],
         artifact_report_path: @options[:artifact_report],
+        require_artifact_report: @options[:require_artifact_report],
         inbox_ttl: @options[:inbox_ttl],
         auto_stop: @options[:auto_stop],
         launch_cwd: history_cwd,
@@ -516,6 +582,8 @@ module Harnex
           @options[:context] = required_option_value("--context", Regexp.last_match(1))
         when "--auto-stop"
           @options[:auto_stop] = true
+        when "--allow-live-parent"
+          @options[:allow_live_parent] = true
         when "--require-attribution"
           @options[:require_attribution] = true
         when "--fast"
@@ -539,6 +607,8 @@ module Harnex
         when "--artifact-report", "--validation-report"
           index += 1
           @options[:artifact_report] = required_option_value(arg, argv[index])
+        when "--require-artifact-report"
+          @options[:require_artifact_report] = true
         when /\A--artifact-report=(.+)\z/
           @options[:artifact_report] = required_option_value("--artifact-report", Regexp.last_match(1))
         when /\A--validation-report=(.+)\z/
@@ -619,7 +689,7 @@ module Harnex
         case arg
         when "--"
           return false
-        when "-h", "--help", "--detach", "--tmux", "--auto-stop", "--require-attribution", "--fast", "--legacy-pty"
+        when "-h", "--help", "--detach", "--tmux", "--auto-stop", "--require-artifact-report", "--require-attribution", "--fast", "--legacy-pty", "--allow-live-parent"
           nil
         when /\A--tmux=/
           nil
@@ -676,6 +746,14 @@ module Harnex
       raise OptionParser::InvalidOption, "harnex run: --auto-stop requires --context"
     end
 
+    def validate_required_artifact_report!
+      return unless @options[:require_artifact_report]
+      return unless @options[:artifact_report].to_s.strip.empty?
+
+      raise OptionParser::InvalidOption,
+            "harnex run: --require-artifact-report requires --artifact-report PATH"
+    end
+
     def apply_telemetry_options!
       explicit = @options[:telemetry]
       return if explicit.empty? && @options[:meta].is_a?(Hash)
@@ -693,6 +771,15 @@ module Harnex
             "harnex run: --attempt-kind must be one of #{Session::ATTEMPT_KINDS.join(', ')}"
     end
 
+    def validate_orchestration_metadata!
+      metadata = @options[:meta].is_a?(Hash) ? @options[:meta] : {}
+      role = metadata["orchestration_role"].to_s
+      return if role.empty? || Orchestration::ROLES.include?(role)
+
+      raise OptionParser::InvalidOption,
+            "harnex run: --orchestration-role must be one of #{Orchestration::ROLES.join(', ')}"
+    end
+
     def validate_required_attribution!
       return unless @options[:require_attribution]
 

data/lib/harnex/commands/status.rb

@@ -97,14 +97,49 @@ module Harnex
       return live unless @options[:id]
       return [live.first] unless live.empty?
 
+      running = running_from_start_record(fallback_repo_root)
+      return [running] if running
+
       terminal = Harnex::TerminalStatus.resolve(id: @options[:id], repo_root: fallback_repo_root)
       [terminal || Harnex::TerminalStatus.unknown(id: @options[:id], repo_root: fallback_repo_root)]
     end
 
+    # Registry row missing but the dispatch stream has an uncompleted start
+    # row whose pid is alive: the worker is running, just not registry-visible
+    # from this context. Report running (labelled degraded), never dead.
+    def running_from_start_record(repo_root)
+      start = Harnex::DispatchHistory.live_start_record(repo_root: repo_root, id: @options[:id])
+      return nil unless start
+
+      {
+        "id" => start["id"].to_s,
+        "cli" => start["cli"],
+        "pid" => start["pid"],
+        "description" => start["description"],
+        "repo_root" => start["repo_root"] || repo_root,
+        "started_at" => start["started_at"],
+        "state" => "running",
+        "process_state" => "running",
+        "terminal" => false,
+        "task_complete" => false,
+        "task_failed" => false,
+        "done" => false,
+        "work_state" => "running",
+        "exit" => nil,
+        "exit_code" => nil,
+        "summary_out" => nil,
+        "ended_at" => nil,
+        "source" => "dispatch_start",
+        "degraded" => true,
+        "live_status" => "unreachable"
+      }
+    end
+
     def normalize_live_status(session)
       task_failed = task_failed?(session)
       task_complete = task_complete?(session) && !task_failed
       work_state = task_failed ? "failed" : Harnex.work_state_for("running", task_complete: task_complete)
+      degraded = session["live_status"] == "unreachable"
       session.merge(
         "state" => "running",
         "process_state" => "running",
@@ -117,7 +152,8 @@ module Harnex
         "exit_code" => nil,
         "summary_out" => nil,
         "ended_at" => nil,
-        "source" => "live"
+        "source" => degraded ? "registry" : "live",
+        "degraded" => degraded
       )
     end
 
@@ -131,6 +167,9 @@ module Harnex
         !session["last_failed_at"].to_s.empty?
     end
 
+    # On HTTP failure the row is still backed by a verified-alive pid, but the
+    # data is the registry snapshot, not the live API — label it as degraded
+    # instead of silently passing it off as live.
     def load_live_status(session)
       uri = URI("http://#{session.fetch('host')}:#{session.fetch('port')}/status")
       request = Net::HTTP::Get.new(uri)
@@ -140,11 +179,11 @@ module Harnex
         http.request(request)
       end
 
-      return session unless response.is_a?(Net::HTTPSuccess)
+      return session.merge("live_status" => "unreachable") unless response.is_a?(Net::HTTPSuccess)
 
-      session.merge(JSON.parse(response.body))
+      session.merge(JSON.parse(response.body)).merge("live_status" => "ok")
     rescue StandardError
-      session
+      session.merge("live_status" => "unreachable")
     end
 
     def render_table(sessions)