harnex 0.7.14 → 0.9.0

data/guides/05_naming.md

@@ -66,17 +66,27 @@ If `--id` is missing, harnex generates a random session ID. The tmux window may
 look right, but `harnex status`, `harnex pane --id`, and logs need the random
 ID.
 
-## Retry Suffixes
+## Retry Suffixes And Linkage
 
-If a session fails and you dispatch a fresh attempt, append a suffix:
+If a session fails and you dispatch a fresh attempt, use a new ID and link it
+to the completed parent so Harnex can derive chain counts and recovery:
 
 ```text
-pi-i-42      first attempt
-pi-i-42b     second attempt
-pi-i-42c     third attempt
+pi-i-42      initial attempt
+pi-i-42-r1   retry of pi-i-42
+pi-i-42-r2   retry of pi-i-42-r1
 ```
 
-Keep the old session's logs. They are useful for diagnosis.
+```bash
+harnex run pi --id pi-i-42-r1 --tmux pi-i-42-r1 \
+  --attempt-kind retry --parent-dispatch-id pi-i-42 \
+  --context "Retry the bounded task."
+```
+
+Retry/fix/fallback/superseding work is refused while its named parent is still
+running unless `--allow-live-parent` explicitly authorizes isolated parallelism.
+Keep old logs for diagnosis; retention removes only expired/over-cap logs that
+do not belong to a current or live session.
 
 ## Task Files
 
@@ -104,8 +114,8 @@ If a legacy workflow still expects a done marker, derive it from the session ID:
 ```
 
 Treat done markers as compatibility hints only. Canonical completion should come
-from harnex terminal telemetry (`harnex wait` / `harnex status --json` / summary
-rows in `.harnex/dispatch.jsonl`).
+from harnex terminal telemetry (`harnex wait` / `harnex status --json` / v2
+`dispatch_end` rows in `.harnex/dispatch.jsonl`).
 
 When a brief asks for a completion marker, make it one line and include the
 highest-signal result: tests passed, review clean, or the blocking issue.

data/lib/harnex/adapters/base.rb

@@ -37,6 +37,16 @@ module Harnex
         nil
       end
 
+      # Whether the usage this adapter captures reports input_tokens
+      # INCLUSIVE of cached_tokens. Depends on the capture path, not just
+      # the provider: codex app-server JSON reports cached as a subset of
+      # input, while the codex TUI line the PTY adapter scrapes shows
+      # non-cached input with cached as a separate additive count. Feeds
+      # Pricing.compute (plan 33 Phase 2).
+      def usage_input_includes_cached?
+        false
+      end
+
       # Probes `<base_command.first> --version` with a short timeout and
       # memoizes the result for the adapter's lifetime. Returns nil when
       # the binary is missing, exits non-zero, or stalls past the timeout.

data/lib/harnex/adapters/codex_appserver.rb

@@ -59,6 +59,7 @@ module Harnex
         @initial_prompt = extract_initial_prompt(extra_args)
         @client = nil
         @thread_id = nil
+        @current_model = nil
         @current_turn_id = nil
         @state = :disconnected
         @last_completed_at = nil
@@ -78,6 +79,21 @@ module Harnex
         true
       end
 
+      # thread/tokenUsage/updated totals report cachedInputTokens as a
+      # subset of inputTokens (verified against a live captured row:
+      # input + output == total exactly, cached < input).
+      def usage_input_includes_cached?
+        true
+      end
+
+      # Effective model reported by the app-server's thread/start or
+      # thread/resume response (schema-required field). Feeds
+      # Session#summary_model so price-table cost can resolve without the
+      # caller passing `--meta '{"model": ...}'`.
+      def current_model
+        @current_model
+      end
+
       def context_telemetry_supported?
         true
       end
@@ -202,6 +218,7 @@ module Harnex
         ensure_open!
         result = @client.request("thread/resume", { threadId: thread_id })
         @thread_id = thread_id
+        @current_model = extract_model(result) || @current_model
         @state = :prompt
         result
       end
@@ -279,6 +296,7 @@ module Harnex
 
         result = @client.request("thread/start", {})
         @thread_id = extract_thread_id(result)
+        @current_model = extract_model(result) || @current_model
       end
 
       def extract_thread_id(payload)
@@ -287,6 +305,13 @@ module Harnex
         payload.dig("thread", "id")
       end
 
+      def extract_model(payload)
+        return nil unless payload.is_a?(Hash)
+
+        model = payload["model"]
+        model.is_a?(String) && !model.empty? ? model : nil
+      end
+
       def extract_initial_prompt(extra_args)
         return nil unless extra_args.is_a?(Array)
 

data/lib/harnex/commands/doctor.rb

@@ -7,7 +7,7 @@ module Harnex
 
     def self.usage
       <<~TEXT
-        Usage: harnex doctor [--sweep]
+        Usage: harnex doctor [--sweep] [--prune [--dry-run]]
 
         Runs preflight checks for harnex's adapter dependencies.
         Currently verifies that Codex CLI is installed and at version
@@ -16,16 +16,21 @@ module Harnex
 
         Options:
           --sweep      Include a read-only report of harnex/tmux session drift
+          --prune      Apply bounded harnex events/output retention pruning
+          --dry-run    Preview --prune candidates without deleting
           -h, --help   Show this help
 
         Common patterns:
           harnex doctor
           harnex doctor --sweep
+          harnex doctor --prune --dry-run
+          harnex doctor --prune
           harnex doctor --help
 
         Gotchas:
           doctor validates local adapter prerequisites; it does not start sessions.
           --sweep is diagnostic only; it does not stop sessions or remove files.
+          --dry-run must be paired with --prune.
           Run it after installing or upgrading Codex CLI.
       TEXT
     end
@@ -34,21 +39,26 @@ module Harnex
       @argv = argv.dup
       @options = {
         sweep: false,
+        prune: false,
+        dry_run: false,
         help: false
       }
     end
 
     def run
       parser.parse!(@argv)
+      validate_options!
       if @options[:help]
         puts self.class.usage
         return 0
       end
 
       checks = [check_codex]
+      retention = retention_payload
       summary = {
-        ok: checks.all? { |c| c[:ok] },
-        checks: checks
+        ok: checks.all? { |c| c[:ok] } && retention.fetch(:ok, true),
+        checks: checks,
+        retention: retention
       }
       summary[:sweep] = sweep_payload if @options[:sweep]
       puts JSON.generate(summary)
@@ -59,12 +69,36 @@ module Harnex
 
     def parser
       @parser ||= OptionParser.new do |opts|
-        opts.banner = "Usage: harnex doctor [--sweep]"
+        opts.banner = "Usage: harnex doctor [--sweep] [--prune [--dry-run]]"
         opts.on("--sweep", "Include read-only session drift diagnostics") { @options[:sweep] = true }
+        opts.on("--prune", "Apply retention pruning") { @options[:prune] = true }
+        opts.on("--dry-run", "Preview --prune candidates without deleting") { @options[:dry_run] = true }
         opts.on("-h", "--help", "Show help") { @options[:help] = true }
       end
     end
 
+    def validate_options!
+      return if @options[:help]
+      return unless @options[:dry_run] && !@options[:prune]
+
+      raise OptionParser::InvalidOption, "--dry-run requires --prune"
+    end
+
+    def retention_payload
+      repo_root = Harnex.resolve_repo_root(Dir.pwd)
+      if @options[:prune]
+        Harnex::Retention.prune(
+          repo_root: repo_root,
+          dry_run: @options[:dry_run],
+          force: true
+        )
+      else
+        Harnex::Retention.status(repo_root: repo_root)
+      end
+    rescue Harnex::Config::ConfigError => e
+      { ok: false, error: e.message }
+    end
+
     def check_codex
       result = { name: "codex", required: ">= #{MIN_CODEX_VERSION}" }
 

data/lib/harnex/commands/history.rb

@@ -1,5 +1,6 @@
 require "json"
 require "optparse"
+require "set"
 require "time"
 
 module Harnex
@@ -74,13 +75,64 @@ 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).
+    # Rows in neither shape (pre-0.7.3 schemas) are skipped entirely.
+    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|
+        if DispatchHistory.start_record?(record)
+          next nil if start_completed?(record, ended)
+
+          derive_live_record(record)
+        elsif DispatchHistory.end_record?(record)
+          record
+        end
+      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 +181,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/run.rb

@@ -33,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-artifact-report --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 fallback superseding].freeze
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
       --max-resumes --preset --context --meta --summary-out --artifact-report
@@ -62,7 +67,7 @@ module Harnex
           --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
-          --summary-out PATH Append dispatch telemetry summary JSONL to PATH
+          --summary-out PATH Also mirror the dispatch end record JSONL to PATH
           --artifact-report PATH
                              Worker-written harnex.artifact_report.v1 JSON sidecar to ingest at exit
           --validation-report PATH
@@ -82,11 +87,17 @@ module Harnex
           --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 dispatch id for retry/fix/review/fallback joins
           --parent-attempt-id ID
-                             Parent attempt id for retry/fix/review joins
+                             Parent attempt id for retry/fix/review/fallback joins
           --attempt-kind KIND
-                             initial, retry, fix, review, or superseding (default: initial)
+                             initial, retry, fix, review, fallback, or superseding (default: initial).
+                             retry/fallback 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
@@ -164,6 +175,7 @@ module Harnex
         cwd: nil,
         root: nil,
         auto_stop: false,
+        allow_live_parent: false,
         detach: false,
         tmux: false,
         tmux_name: nil,
@@ -191,10 +203,12 @@ module Harnex
       validate_required_attribution!
 
       repo_root = resolve_run_root(cli_name, child_args)
+      validate_repo_phase_policy!(repo_root)
       @options[:summary_out] = resolve_summary_out(repo_root)
       @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]
@@ -258,6 +272,7 @@ 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]
@@ -357,6 +372,57 @@ module Harnex
             "Use a different --id or stop the existing session first."
     end
 
+    # Duplicate-dispatch guard (issue #62): a retry/fix/fallback/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 %w[retry fallback].include?(kind) && parent_id.empty?
+        raise "harnex run: --attempt-kind #{kind} 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 validate_repo_phase_policy!(repo_root)
+      config = Harnex::Config.load_repo(repo_root)
+      Harnex::Config.retention_limits(config: config)
+      phase_config = config.phase
+      return unless phase_config
+
+      metadata = @options[:meta].is_a?(Hash) ? @options[:meta] : {}
+      phase = metadata["phase"].to_s
+      allowlist = phase_config.fetch("allowlist")
+      return if allowlist.include?(phase)
+
+      policy = phase_config.fetch("policy")
+      message = "harnex run: meta.phase #{phase.empty? ? '(none)' : phase.inspect} " \
+                "is not allowlisted by #{config.path} " \
+                "(allowed: #{allowlist.join(', ')}; policy: #{policy})"
+      if policy == "warn"
+        warn("harnex: warning: #{message}")
+      else
+        raise OptionParser::InvalidOption, message
+      end
+    rescue Harnex::Config::ConfigError => e
+      raise OptionParser::InvalidOption, "harnex run: invalid config #{e.message}"
+    end
+
     def build_session(adapter, repo_root)
       watch = Harnex.build_watch_config(@options[:watch], repo_root)
       Session.new(
@@ -541,6 +607,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"
@@ -646,7 +714,7 @@ module Harnex
         case arg
         when "--"
           return false
-        when "-h", "--help", "--detach", "--tmux", "--auto-stop", "--require-artifact-report", "--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
@@ -799,9 +867,11 @@ module Harnex
       raise OptionParser::InvalidOption, "--meta must be valid JSON: #{e.message}"
     end
 
+    # Explicit-only mirror: the tracked dispatch stream is the canonical
+    # destination; --summary-out just duplicates the end record elsewhere.
     def resolve_summary_out(repo_root)
       configured = @options[:summary_out]
-      return Harnex.default_summary_out_path(repo_root) if configured.nil?
+      return nil if configured.nil?
 
       File.expand_path(configured, repo_root)
     end

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)