harnex 0.8.0 → 0.10.0

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/receipt 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

@@ -85,6 +85,7 @@ module Harnex
     # 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
@@ -97,10 +98,13 @@ module Harnex
       end
 
       raw.filter_map do |record|
-        next record unless DispatchHistory.start_record?(record)
-        next nil if start_completed?(record, ended)
+        if DispatchHistory.start_record?(record)
+          next nil if start_completed?(record, ended)
 
-        derive_live_record(record)
+          derive_live_record(record)
+        elsif DispatchHistory.end_record?(record)
+          record
+        end
       end
     end
 

data/lib/harnex/commands/run.rb

@@ -31,7 +31,7 @@ module Harnex
 
     KNOWN_FLAGS = %w[
       --id --description --detach --tmux --host --port --watch --watch-file
-      --stall-after --max-resumes --preset --context --meta --summary-out
+      --stall-after --max-resumes --preset --context --meta
       --artifact-report --validation-report --cwd --root --timeout --inbox-ttl
       --require-artifact-report --require-attribution --auto-stop --fast --legacy-pty
       --allow-live-parent --help
@@ -39,10 +39,10 @@ module Harnex
 
     # 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
+    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
+      --max-resumes --preset --context --meta --artifact-report
       --validation-report --cwd --root --timeout --inbox-ttl
     ].concat(TELEMETRY_FLAGS.keys).freeze
 
@@ -67,14 +67,13 @@ 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
           --artifact-report PATH
-                             Worker-written harnex.artifact_report.v1 JSON sidecar to ingest at exit
+                             Override the harness-authored observed-state receipt path
           --validation-report PATH
-                             Alias for --artifact-report; also exposed as HARNEX_VALIDATION_REPORT_PATH
+                             Compatibility alias for --artifact-report
           --require-artifact-report
-                             Fail closed unless PATH contains accepted final proof;
-                             requires --artifact-report or --validation-report
+                             Compatibility strict-proof flag; a default harness receipt
+                             path is used when no explicit path is provided
           --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
@@ -87,12 +86,12 @@ 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).
-                             retry requires --parent-dispatch-id so the
+                             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
@@ -124,8 +123,9 @@ module Harnex
           Compatibility: `--watch PATH` and `--watch=PATH` still configure file-hook mode.
           Bare `--watch` enables the babysitter.
           --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.
+          accepted completion after command/tool activity or a Git delta.
+          Every dispatch gets a harness-authored receipt. Workers may write only
+          optional claims to HARNEX_ARTIFACT_CLAIMS_PATH; claims never accept work.
           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.
@@ -136,7 +136,7 @@ module Harnex
           #{program_name} pi --id pi-i-42 --tmux pi-i-42 --context "Read /tmp/task-impl-42.md" --auto-stop
           #{program_name} pi --id pi-i-42 --watch --preset impl --context "Read /tmp/task-impl-42.md"
           #{program_name} codex --cwd /tmp/public-bundle --id eval-001 --context "Read README.md and write OUTPUT.md" --auto-stop
-          #{program_name} pi --id pi-i-52 --artifact-report .harnex/reports/pi-i-52.json --context "Write proof to $HARNEX_ARTIFACT_REPORT_PATH" --auto-stop
+          #{program_name} pi --id pi-r-64 --context 'Optionally write review claims to $HARNEX_ARTIFACT_CLAIMS_PATH' --auto-stop
           #{program_name} pi --project-id harnex --queue-id queue-005 --entry-id SP-4 --phase implement --intent queue-work --require-attribution --context "Implement SP-4"
           #{program_name} claude --id cl-r-42 --tmux cl-r-42 --description "Review task 42"
 
@@ -169,7 +169,6 @@ module Harnex
         meta: nil,
         telemetry: {},
         require_attribution: false,
-        summary_out: nil,
         artifact_report: nil,
         require_artifact_report: false,
         cwd: nil,
@@ -203,7 +202,7 @@ module Harnex
       validate_required_attribution!
 
       repo_root = resolve_run_root(cli_name, child_args)
-      @options[:summary_out] = resolve_summary_out(repo_root)
+      validate_repo_phase_policy!(repo_root)
       @options[:artifact_report] = resolve_artifact_report(repo_root)
       @options[:id] ||= Harnex.generate_id(repo_root)
       validate_unique_id!(repo_root)
@@ -272,7 +271,6 @@ module Harnex
       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]
@@ -307,7 +305,9 @@ module Harnex
         port: registry["port"],
         mode: "tmux",
         window: window_name,
-        output_log_path: Harnex.output_log_path(repo_root, @options[:id])
+        output_log_path: Harnex.output_log_path(repo_root, @options[:id]),
+        artifact_report_path: registry["artifact_report_path"],
+        artifact_claims_path: registry["artifact_claims_path"]
       }
       payload[:description] = @options[:description] if @options[:description]
       puts JSON.generate(payload)
@@ -346,7 +346,9 @@ module Harnex
         port: registry["port"],
         mode: "headless",
         log: log_path,
-        output_log_path: Harnex.output_log_path(repo_root, @options[:id])
+        output_log_path: Harnex.output_log_path(repo_root, @options[:id]),
+        artifact_report_path: registry["artifact_report_path"],
+        artifact_claims_path: registry["artifact_claims_path"]
       }
       payload[:description] = @options[:description] if @options[:description]
       puts JSON.generate(payload) if emit_payload
@@ -371,7 +373,7 @@ module Harnex
             "Use a different --id or stop the existing session first."
     end
 
-    # Duplicate-dispatch guard (issue #62): a retry/fix/superseding attempt
+    # 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.
@@ -380,8 +382,8 @@ module Harnex
       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 " \
+      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
 
@@ -398,6 +400,30 @@ module Harnex
             "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(
@@ -410,7 +436,6 @@ module Harnex
         watch: watch,
         description: @options[:description],
         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],
@@ -599,11 +624,6 @@ module Harnex
         when telemetry_equals_regex
           flag = "--#{Regexp.last_match(1)}"
           @options[:telemetry][TELEMETRY_FLAGS.fetch(flag)] = required_option_value(flag, Regexp.last_match(2))
-        when "--summary-out"
-          index += 1
-          @options[:summary_out] = required_option_value(arg, argv[index])
-        when /\A--summary-out=(.+)\z/
-          @options[:summary_out] = required_option_value("--summary-out", Regexp.last_match(1))
         when "--artifact-report", "--validation-report"
           index += 1
           @options[:artifact_report] = required_option_value(arg, argv[index])
@@ -695,7 +715,7 @@ module Harnex
           nil
         when *VALUE_FLAGS
           index += 1
-        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|summary-out|artifact-report|validation-report|cwd|root|timeout|inbox-ttl)=/
+        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|artifact-report|validation-report|cwd|root|timeout|inbox-ttl)=/
           nil
         when telemetry_equals_regex
           nil
@@ -715,7 +735,7 @@ module Harnex
         arg == "-h" ||
         arg.start_with?(
           "--id=", "--description=", "--tmux=", "--host=", "--port=", "--watch=", "--watch-file=",
-          "--stall-after=", "--max-resumes=", "--preset=", "--context=", "--meta=", "--summary-out=",
+          "--stall-after=", "--max-resumes=", "--preset=", "--context=", "--meta=",
           "--artifact-report=", "--validation-report=", "--cwd=", "--root=", "--timeout=", "--inbox-ttl=",
           *TELEMETRY_EQUALS_PREFIXES
         )
@@ -746,12 +766,11 @@ module Harnex
       raise OptionParser::InvalidOption, "harnex run: --auto-stop requires --context"
     end
 
+    # Retained for compatibility with callers that still pass the strict flag.
+    # Session now allocates a harness-owned default receipt path, so an explicit
+    # --artifact-report path is no longer required.
     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"
+      true
     end
 
     def apply_telemetry_options!
@@ -842,13 +861,6 @@ module Harnex
       raise OptionParser::InvalidOption, "--meta must be valid JSON: #{e.message}"
     end
 
-    def resolve_summary_out(repo_root)
-      configured = @options[:summary_out]
-      return Harnex.default_summary_out_path(repo_root) if configured.nil?
-
-      File.expand_path(configured, repo_root)
-    end
-
     def resolve_artifact_report(repo_root)
       configured = @options[:artifact_report]
       return nil if configured.nil?

data/lib/harnex/commands/status.rb

@@ -127,7 +127,6 @@ module Harnex
         "work_state" => "running",
         "exit" => nil,
         "exit_code" => nil,
-        "summary_out" => nil,
         "ended_at" => nil,
         "source" => "dispatch_start",
         "degraded" => true,
@@ -150,7 +149,6 @@ module Harnex
         "work_state" => work_state,
         "exit" => nil,
         "exit_code" => nil,
-        "summary_out" => nil,
         "ended_at" => nil,
         "source" => degraded ? "registry" : "live",
         "degraded" => degraded

data/lib/harnex/commands/wait.rb

@@ -624,7 +624,6 @@ module Harnex
         artifact_report_status: status["artifact_report_status"],
         exit: status["exit"],
         exit_code: status["exit_code"],
-        summary_out: status["summary_out"],
         ended_at: status["ended_at"],
         source: status["source"]
       }

data/lib/harnex/config.rb

@@ -0,0 +1,170 @@
+require "json"
+
+module Harnex
+  module Config
+    CONFIG_RELATIVE_PATH = File.join(".harnex", "config.json").freeze
+    PHASE_POLICIES = %w[warn reject].freeze
+    RETENTION_DIRS = %w[events output receipts].freeze
+    RETENTION_FIELDS = %w[max_age_days max_bytes].freeze
+    RETENTION_ENV = {
+      "events" => {
+        "max_age_days" => "HARNEX_EVENTS_MAX_AGE_DAYS",
+        "max_bytes" => "HARNEX_EVENTS_MAX_BYTES"
+      },
+      "output" => {
+        "max_age_days" => "HARNEX_OUTPUT_MAX_AGE_DAYS",
+        "max_bytes" => "HARNEX_OUTPUT_MAX_BYTES"
+      },
+      "receipts" => {
+        "max_age_days" => "HARNEX_RECEIPTS_MAX_AGE_DAYS",
+        "max_bytes" => "HARNEX_RECEIPTS_MAX_BYTES"
+      }
+    }.freeze
+    DEFAULT_RETENTION_LIMITS = RETENTION_DIRS.to_h do |dir|
+      [dir, { "max_age_days" => 45, "max_bytes" => 1_073_741_824 }]
+    end.freeze
+
+    ConfigError = Class.new(StandardError)
+
+    RepoConfig = Struct.new(:root, :path, :data, keyword_init: true) do
+      def present?
+        !path.nil? && File.file?(path)
+      end
+
+      def phase
+        data.is_a?(Hash) ? data["phase"] : nil
+      end
+
+      def retention
+        data.is_a?(Hash) ? data["retention"] : nil
+      end
+    end
+
+    module_function
+
+    def load_repo(start_path)
+      root = DispatchHistory.find_git_root(start_path)
+      return RepoConfig.new(root: nil, path: nil, data: {}) unless root
+
+      path = File.join(root, CONFIG_RELATIVE_PATH)
+      return RepoConfig.new(root: root, path: path, data: {}) unless File.file?(path)
+
+      parsed = JSON.parse(File.read(path))
+      validate_document!(parsed, path)
+      RepoConfig.new(root: root, path: path, data: parsed)
+    rescue JSON::ParserError => e
+      raise ConfigError, "#{path}: malformed JSON: #{e.message}"
+    end
+
+    def validate_document!(document, path)
+      unless document.is_a?(Hash)
+        raise ConfigError, "#{path}: config must be a JSON object"
+      end
+
+      validate_phase!(document["phase"], path) if document.key?("phase")
+      validate_retention!(document["retention"], path) if document.key?("retention")
+    end
+
+    def validate_phase!(phase, path)
+      unless phase.is_a?(Hash)
+        raise ConfigError, "#{path}: $.phase must be an object"
+      end
+
+      allowlist = phase["allowlist"]
+      unless allowlist.is_a?(Array)
+        raise ConfigError, "#{path}: $.phase.allowlist must be an array"
+      end
+
+      allowlist.each_with_index do |entry, index|
+        next if entry.is_a?(String) && !entry.strip.empty?
+
+        raise ConfigError,
+          "#{path}: $.phase.allowlist[#{index}] must be a non-empty string"
+      end
+
+      policy = phase["policy"]
+      unless PHASE_POLICIES.include?(policy)
+        raise ConfigError,
+          "#{path}: $.phase.policy must be one of #{PHASE_POLICIES.join(', ')}"
+      end
+    end
+
+    def retention_limits(start_path = Dir.pwd, env: ENV, config: nil)
+      config ||= load_repo(start_path)
+      limits = deep_dup_retention_defaults
+      retention = config.retention
+
+      if retention
+        RETENTION_DIRS.each do |dir|
+          next unless retention.key?(dir)
+
+          RETENTION_FIELDS.each do |field|
+            next unless retention.fetch(dir).key?(field)
+
+            limits.fetch(dir)[field] = parse_positive_integer!(
+              retention.fetch(dir).fetch(field),
+              "#{config.path}: $.retention.#{dir}.#{field}"
+            )
+          end
+        end
+      end
+
+      RETENTION_ENV.each do |dir, fields|
+        fields.each do |field, name|
+          next unless env.key?(name)
+
+          limits.fetch(dir)[field] = parse_positive_integer!(
+            env.fetch(name),
+            name
+          )
+        end
+      end
+
+      limits
+    end
+
+    def validate_retention!(retention, path)
+      unless retention.is_a?(Hash)
+        raise ConfigError, "#{path}: $.retention must be an object"
+      end
+
+      retention.each do |dir, value|
+        unless RETENTION_DIRS.include?(dir)
+          raise ConfigError,
+            "#{path}: $.retention.#{dir} is not supported (expected events, output, or receipts)"
+        end
+        unless value.is_a?(Hash)
+          raise ConfigError, "#{path}: $.retention.#{dir} must be an object"
+        end
+
+        value.each do |field, limit|
+          unless RETENTION_FIELDS.include?(field)
+            raise ConfigError,
+              "#{path}: $.retention.#{dir}.#{field} is not supported"
+          end
+
+          parse_positive_integer!(
+            limit,
+            "#{path}: $.retention.#{dir}.#{field}"
+          )
+        end
+      end
+    end
+
+    def parse_positive_integer!(value, label)
+      text = value.to_s.strip
+      unless text.match?(/\A[0-9]+\z/)
+        raise ConfigError, "#{label} must be a positive integer"
+      end
+
+      integer = Integer(text)
+      raise ConfigError, "#{label} must be a positive integer" if integer <= 0
+
+      integer
+    end
+
+    def deep_dup_retention_defaults
+      DEFAULT_RETENTION_LIMITS.transform_values(&:dup)
+    end
+  end
+end