harnex 0.3.4 → 0.5.0

data/lib/harnex/commands/run.rb

@@ -6,10 +6,13 @@ module Harnex
   class Runner
     DEFAULT_TIMEOUT = 5.0
     KNOWN_FLAGS = %w[
-      --id --description --detach --tmux --host --port --watch --context --timeout --inbox-ttl --help
+      --id --description --detach --tmux --host --port --watch --watch-file
+      --stall-after --max-resumes --preset --context --meta --summary-out
+      --timeout --inbox-ttl --help
     ].freeze
     VALUE_FLAGS = %w[
-      --id --description --host --port --watch --context --timeout --inbox-ttl
+      --id --description --host --port --watch --watch-file --stall-after
+      --max-resumes --preset --context --meta --summary-out --timeout --inbox-ttl
     ].freeze
 
     def self.usage(program_name = "harnex run")
@@ -23,13 +26,22 @@ module Harnex
           --tmux [NAME]      Run in a tmux window (implies --detach)
           --host HOST        Bind host for the local API (default: #{DEFAULT_HOST})
           --port PORT        Force a specific local API port
-          --watch PATH       Auto-send a file-change hook on modification
+          --watch            Enable blocking babysitter mode (foreground only)
+          --stall-after DUR  Force-resume threshold (default: #{RunWatcher::DEFAULT_STALL_AFTER_S.to_i}s)
+          --max-resumes N    Max forced resumes before escalation (default: #{RunWatcher::DEFAULT_MAX_RESUMES})
+          --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)
+          --meta JSON        Attach parsed JSON metadata to the started event
+          --summary-out PATH Append dispatch telemetry summary JSONL to PATH
           --timeout SECS     Max seconds to wait for detached registration (default: #{DEFAULT_TIMEOUT})
           --inbox-ttl SECS   Expire queued inbox messages after SECS (default: #{Inbox::DEFAULT_TTL})
           -h, --help         Show this help
 
         Notes:
+          Compatibility: `--watch PATH` and `--watch=PATH` still configure file-hook mode.
+          Bare `--watch` enables the babysitter.
+          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.
           Wrapper options may appear before or after <cli>.
@@ -43,8 +55,16 @@ module Harnex
         description: nil,
         host: DEFAULT_HOST,
         port: nil,
+        watch_enabled: false,
+        stall_after_s: RunWatcher::DEFAULT_STALL_AFTER_S,
+        stall_after_explicit: false,
+        max_resumes: RunWatcher::DEFAULT_MAX_RESUMES,
+        max_resumes_explicit: false,
+        preset: nil,
         watch: nil,
         context: nil,
+        meta: nil,
+        summary_out: nil,
         detach: false,
         tmux: false,
         tmux_name: nil,
@@ -64,13 +84,18 @@ module Harnex
       raise OptionParser::MissingArgument, "cli" if cli_name.nil?
 
       repo_root = Harnex.resolve_repo_root(adapter_repo_path(cli_name, child_args))
+      @options[:summary_out] = resolve_summary_out(repo_root)
       @options[:id] ||= Harnex.generate_id(repo_root)
       validate_unique_id!(repo_root)
       effective_child_args = apply_context(child_args)
       adapter = Harnex.build_adapter(cli_name, effective_child_args)
       @options[:detach] = true if @options[:tmux]
+      validate_watch_mode!
+      resolve_watch_preset!
 
-      if @options[:detach]
+      if @options[:watch_enabled]
+        run_watch_mode(adapter, repo_root)
+      elsif @options[:detach]
         run_detached(adapter, cli_name, child_args, repo_root)
       else
         run_foreground(adapter, repo_root)
@@ -90,10 +115,25 @@ module Harnex
       if @options[:tmux]
         run_in_tmux(cli_name, child_args, repo_root)
       else
-        run_headless(adapter, repo_root)
+        result = run_headless(adapter, repo_root)
+        result[:exit_code]
       end
     end
 
+    def run_watch_mode(adapter, repo_root)
+      Session.validate_binary!(adapter.build_command)
+
+      result = run_headless(adapter, repo_root, emit_payload: false)
+      return result[:exit_code] unless result[:ok]
+
+      RunWatcher.new(
+        id: @options[:id],
+        repo_root: repo_root,
+        stall_after_s: @options[:stall_after_s],
+        max_resumes: @options[:max_resumes]
+      ).run
+    end
+
     def run_in_tmux(cli_name, child_args, repo_root)
       harnex_bin = File.expand_path("../../../bin/harnex", __dir__)
       tmux_cmd = [harnex_bin, "run", cli_name]
@@ -101,8 +141,10 @@ module Harnex
       tmux_cmd += ["--description", @options[:description]] if @options[:description]
       tmux_cmd += ["--host", @options[:host]]
       tmux_cmd += ["--port", @options[:port].to_s] if @options[:port]
-      tmux_cmd += ["--watch", @options[:watch]] if @options[:watch]
+      tmux_cmd += ["--watch-file", @options[:watch]] if @options[:watch]
       tmux_cmd += ["--context", @options[:context]] if @options[:context]
+      tmux_cmd += ["--meta", JSON.generate(@options[:meta])] if @options[:meta]
+      tmux_cmd += ["--summary-out", @options[:summary_out]] if @options[:summary_out]
       tmux_cmd += ["--inbox-ttl", @options[:inbox_ttl].to_s]
       tmux_cmd += ["--"] + child_args unless child_args.empty?
 
@@ -137,7 +179,7 @@ module Harnex
       0
     end
 
-    def run_headless(adapter, repo_root)
+    def run_headless(adapter, repo_root, emit_payload: true)
       log_dir = File.join(Harnex::STATE_DIR, "logs")
       FileUtils.mkdir_p(log_dir)
       log_path = File.join(log_dir, "#{@options[:id]}.log")
@@ -159,7 +201,7 @@ module Harnex
       Process.detach(child_pid)
 
       registry = wait_for_registration(repo_root)
-      return registration_timeout(@options[:id]) unless registry
+      return { ok: false, exit_code: registration_timeout(@options[:id]) } unless registry
 
       payload = {
         ok: true,
@@ -172,12 +214,19 @@ module Harnex
         output_log_path: Harnex.output_log_path(repo_root, @options[:id])
       }
       payload[:description] = @options[:description] if @options[:description]
-      puts JSON.generate(payload)
-      0
+      puts JSON.generate(payload) if emit_payload
+      { ok: true, exit_code: 0, registry: registry, payload: payload }
     end
 
     private
 
+    def validate_watch_mode!
+      return unless @options[:watch_enabled]
+      return unless @options[:detach]
+
+      raise OptionParser::InvalidOption, "--watch is only supported in foreground mode"
+    end
+
     def validate_unique_id!(repo_root)
       existing = Harnex.read_registry(repo_root, @options[:id])
       return unless existing
@@ -198,6 +247,8 @@ module Harnex
         id: @options[:id],
         watch: watch,
         description: @options[:description],
+        meta: @options[:meta],
+        summary_out: @options[:summary_out],
         inbox_ttl: @options[:inbox_ttl]
       )
     end
@@ -294,15 +345,66 @@ module Harnex
         when /\A--port=(.+)\z/
           @options[:port] = Integer(required_option_value("--port", Regexp.last_match(1)))
         when "--watch"
-          index += 1
-          @options[:watch] = required_option_value(arg, argv[index])
+          value = argv[index + 1]
+          if value.nil? || value == "--" || wrapper_option_token?(value)
+            @options[:watch_enabled] = true
+          else
+            index += 1
+            @options[:watch] = required_option_value(arg, argv[index])
+          end
         when /\A--watch=(.+)\z/
           @options[:watch] = required_option_value("--watch", Regexp.last_match(1))
+        when "--watch-file"
+          index += 1
+          @options[:watch] = required_option_value(arg, argv[index])
+        when /\A--watch-file=(.+)\z/
+          @options[:watch] = required_option_value("--watch-file", Regexp.last_match(1))
+        when "--stall-after"
+          index += 1
+          @options[:stall_after_s] = Harnex.parse_duration_seconds(
+            required_option_value(arg, argv[index]),
+            option_name: "--stall-after"
+          )
+          @options[:stall_after_explicit] = true
+        when /\A--stall-after=(.+)\z/
+          @options[:stall_after_s] = Harnex.parse_duration_seconds(
+            required_option_value("--stall-after", Regexp.last_match(1)),
+            option_name: "--stall-after"
+          )
+          @options[:stall_after_explicit] = true
+        when "--max-resumes"
+          index += 1
+          @options[:max_resumes] = parse_non_negative_integer(
+            required_option_value(arg, argv[index]),
+            option_name: "--max-resumes"
+          )
+          @options[:max_resumes_explicit] = true
+        when /\A--max-resumes=(.+)\z/
+          @options[:max_resumes] = parse_non_negative_integer(
+            required_option_value("--max-resumes", Regexp.last_match(1)),
+            option_name: "--max-resumes"
+          )
+          @options[:max_resumes_explicit] = true
+        when "--preset"
+          index += 1
+          @options[:preset] = required_option_value(arg, argv[index])
+        when /\A--preset=(.+)\z/
+          @options[:preset] = required_option_value("--preset", Regexp.last_match(1))
         when "--context"
           index += 1
           @options[:context] = required_option_value(arg, argv[index])
         when /\A--context=(.+)\z/
           @options[:context] = required_option_value("--context", Regexp.last_match(1))
+        when "--meta"
+          index += 1
+          @options[:meta] = parse_meta(required_option_value(arg, argv[index]))
+        when /\A--meta=(.+)\z/
+          @options[:meta] = parse_meta(required_option_value("--meta", Regexp.last_match(1)))
+        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 "--timeout"
           index += 1
           @options[:timeout] = Float(required_option_value(arg, argv[index]))
@@ -358,7 +460,9 @@ module Harnex
           nil
         when *VALUE_FLAGS
           index += 1
-        when /\A--(?:id|description|host|port|watch|context|timeout|inbox-ttl)=/
+        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|summary-out|timeout|inbox-ttl)=/
+          nil
+        when /\A--preset=/
           nil
         else
           return true
@@ -372,7 +476,54 @@ module Harnex
     def wrapper_option_token?(arg)
       KNOWN_FLAGS.include?(arg) ||
         arg == "-h" ||
-        arg.start_with?("--id=", "--description=", "--tmux=", "--host=", "--port=", "--watch=", "--context=", "--timeout=", "--inbox-ttl=")
+        arg.start_with?(
+          "--id=", "--description=", "--tmux=", "--host=", "--port=", "--watch=", "--watch-file=",
+          "--stall-after=", "--max-resumes=", "--preset=", "--context=", "--meta=", "--summary-out=",
+          "--timeout=", "--inbox-ttl="
+        )
+    end
+
+    def resolve_watch_preset!
+      preset_name = @options[:preset]
+      return if preset_name.nil?
+
+      unless @options[:watch_enabled]
+        raise "harnex run: --preset requires --watch"
+      end
+
+      preset = WatchPresets.fetch(preset_name)
+      unless preset
+        valid = WatchPresets.valid_names.join(", ")
+        raise "harnex run: unknown --preset #{preset_name.inspect} (valid: #{valid})"
+      end
+
+      @options[:stall_after_s] = preset[:stall_after_s] unless @options[:stall_after_explicit]
+      @options[:max_resumes] = preset[:max_resumes] unless @options[:max_resumes_explicit]
+    end
+
+    def parse_non_negative_integer(value, option_name:)
+      integer = Integer(value)
+      raise OptionParser::InvalidArgument, "#{option_name} must be 0 or greater" if integer.negative?
+
+      integer
+    rescue ArgumentError
+      raise OptionParser::InvalidArgument, "#{option_name} must be an integer"
+    end
+
+    def parse_meta(value)
+      parsed = JSON.parse(value)
+      return parsed if parsed.is_a?(Hash)
+
+      raise OptionParser::InvalidOption, "--meta must be a JSON object"
+    rescue JSON::ParserError => e
+      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 default_inbox_ttl

data/lib/harnex/commands/status.rb

@@ -98,7 +98,7 @@ module Harnex
     end
 
     def render_table(sessions)
-      columns = ["ID", "CLI", "PID", "PORT", "AGE", "STATE", "REPO", "DESC"]
+      columns = ["ID", "CLI", "PID", "PORT", "AGE", "IDLE", "STATE", "REPO", "DESC"]
 
       rows = sessions.map { |session| table_row(session, columns) }
       widths = columns.to_h { |column| [column, ([column.length] + rows.map { |row| row.fetch(column).length }).max] }
@@ -117,6 +117,7 @@ module Harnex
         "PID" => session["pid"].to_s,
         "PORT" => session["port"].to_s,
         "AGE" => timeago(session["started_at"]),
+        "IDLE" => format_idle(session["log_idle_s"]),
         "STATE" => session.dig("input_state", "state").to_s.empty? ? "-" : session.dig("input_state", "state").to_s,
         "DESC" => truncate(session["description"])
       }
@@ -133,7 +134,22 @@ module Harnex
 
       seconds = (Time.now - Time.parse(timestamp.to_s)).to_i
       seconds = 0 if seconds.negative?
+      compact_duration(seconds)
+    rescue StandardError
+      timestamp.to_s
+    end
+
+    def format_idle(idle_seconds)
+      return "-" if idle_seconds.nil?
+
+      seconds = Integer(idle_seconds)
+      seconds = 0 if seconds.negative?
+      compact_duration(seconds)
+    rescue StandardError
+      "-"
+    end
 
+    def compact_duration(seconds)
       case seconds
       when 0...60
         "#{seconds}s"
@@ -144,8 +160,6 @@ module Harnex
       else
         "#{seconds / 86_400}d"
       end
-    rescue StandardError
-      timestamp.to_s
     end
 
     def truncate(value)

data/lib/harnex/commands/watch.rb

@@ -0,0 +1,209 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Harnex
+  class RunWatcher
+    DEFAULT_STALL_AFTER_S = 8 * 60.0
+    DEFAULT_MAX_RESUMES = 1
+    POLL_INTERVAL_S = 60.0
+    MAX_STATUS_ERRORS = 3
+    RESUME_TEXT = "resume"
+
+    def initialize(
+      id:,
+      repo_root:,
+      stall_after_s: DEFAULT_STALL_AFTER_S,
+      max_resumes: DEFAULT_MAX_RESUMES,
+      poll_interval_s: POLL_INTERVAL_S,
+      sleeper: nil,
+      monotonic_clock: nil,
+      out: $stdout,
+      err: $stderr
+    )
+      @id = Harnex.normalize_id(id)
+      @repo_root = repo_root
+      @stall_after_s = Float(stall_after_s)
+      @max_resumes = Integer(max_resumes)
+      @poll_interval_s = Float(poll_interval_s)
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @monotonic_clock = monotonic_clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @out = out
+      @err = err
+    end
+
+    def run
+      polls = 0
+      resumes = 0
+      final_state = "unknown"
+      outcome = :error
+      status_errors = 0
+      start_at = now
+
+      @out.puts(
+        "harnex watch: id=#{@id} stall-after=#{format_duration(@stall_after_s)} " \
+        "max-resumes=#{@max_resumes} poll=#{format_duration(@poll_interval_s)}"
+      )
+
+      loop do
+        polls += 1
+        snapshot = fetch_snapshot
+
+        case snapshot[:kind]
+        when :exited
+          final_state = "exited"
+          outcome = :exited
+          @out.puts("harnex watch: session exited")
+          break
+        when :error
+          if snapshot[:fatal]
+            @err.puts("harnex watch: #{snapshot[:error]}")
+            outcome = :error
+            break
+          end
+
+          status_errors += 1
+          if status_errors >= MAX_STATUS_ERRORS
+            @err.puts("harnex watch: #{snapshot[:error]} (status retry limit reached)")
+            outcome = :error
+            break
+          end
+        when :status
+          status_errors = 0
+          final_state = snapshot[:agent_state]
+
+          if snapshot[:stalled]
+            if resumes < @max_resumes
+              send_resume(snapshot[:registry])
+              resumes += 1
+              @out.puts(
+                "harnex watch: resume #{resumes}/#{@max_resumes} " \
+                "(idle=#{format_duration(snapshot[:idle_seconds])}, state=#{final_state})"
+              )
+            else
+              outcome = :escalated
+              @out.puts("harnex watch: max resumes reached, escalating")
+              break
+            end
+          end
+        end
+
+        @sleeper.call(@poll_interval_s)
+      end
+
+      elapsed = (now - start_at).round(1)
+      @out.puts(
+        "harnex watch: summary id=#{@id} polls=#{polls} resumes=#{resumes} " \
+        "final_state=#{final_state} outcome=#{outcome} elapsed_s=#{elapsed}"
+      )
+      outcome_to_exit_code(outcome)
+    rescue StandardError => e
+      @err.puts("harnex watch: #{e.message}")
+      1
+    end
+
+    private
+
+    def fetch_snapshot
+      registry = Harnex.read_registry(@repo_root, @id)
+      return { kind: :exited } unless registry
+
+      status = fetch_status(registry)
+      return status if status[:kind] == :error
+
+      payload = status[:payload]
+      unless payload.key?("log_idle_s")
+        return {
+          kind: :error,
+          fatal: true,
+          error: "status payload missing log_idle_s; upgrade to a Layer-1+ harnex build"
+        }
+      end
+
+      agent_state = payload["agent_state"].to_s.strip
+      return { kind: :exited } if agent_state == "exited"
+
+      idle_seconds = parse_idle_seconds(payload["log_idle_s"])
+      {
+        kind: :status,
+        registry: registry,
+        agent_state: agent_state.empty? ? "unknown" : agent_state,
+        idle_seconds: idle_seconds,
+        stalled: !idle_seconds.nil? && idle_seconds >= @stall_after_s
+      }
+    end
+
+    def fetch_status(registry)
+      uri = URI("http://#{registry.fetch('host')}:#{registry.fetch('port')}/status")
+      request = Net::HTTP::Get.new(uri)
+      request["Authorization"] = "Bearer #{registry['token']}" if registry["token"]
+
+      response = Net::HTTP.start(uri.host, uri.port, open_timeout: 1, read_timeout: 1) do |http|
+        http.request(request)
+      end
+
+      unless response.is_a?(Net::HTTPSuccess)
+        return { kind: :error, error: "status request failed with HTTP #{response.code} for session #{@id}" }
+      end
+
+      { kind: :status_payload, payload: JSON.parse(response.body) }
+    rescue StandardError => e
+      { kind: :error, error: "status request failed for session #{@id}: #{e.message}" }
+    end
+
+    def send_resume(registry)
+      uri = URI("http://#{registry.fetch('host')}:#{registry.fetch('port')}/send")
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{registry['token']}" if registry["token"]
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(
+        text: RESUME_TEXT,
+        submit: true,
+        enter_only: false,
+        force: true
+      )
+
+      response = Net::HTTP.start(uri.host, uri.port, open_timeout: 1, read_timeout: 1) do |http|
+        http.request(request)
+      end
+
+      return if response.is_a?(Net::HTTPSuccess)
+
+      raise "resume send failed with HTTP #{response.code} for session #{@id}"
+    rescue StandardError => e
+      raise "resume send failed for session #{@id}: #{e.message}"
+    end
+
+    def parse_idle_seconds(value)
+      return nil if value.nil?
+
+      seconds = Integer(value)
+      seconds.negative? ? 0 : seconds
+    rescue StandardError
+      nil
+    end
+
+    def outcome_to_exit_code(outcome)
+      case outcome
+      when :exited
+        0
+      when :escalated
+        2
+      else
+        1
+      end
+    end
+
+    def format_duration(seconds)
+      value = seconds.to_f
+      return "#{value.round(1)}s" if value < 60
+      return "#{(value / 60).round(1)}m" if value < 3600
+
+      "#{(value / 3600).round(1)}h"
+    end
+
+    def now
+      @monotonic_clock.call
+    end
+  end
+end

data/lib/harnex/commands/watch_presets.rb

@@ -0,0 +1,17 @@
+module Harnex
+  module WatchPresets
+    TABLE = {
+      "impl" => { stall_after_s: 8 * 60.0, max_resumes: 1 }.freeze,
+      "plan" => { stall_after_s: 3 * 60.0, max_resumes: 2 }.freeze,
+      "gate" => { stall_after_s: 15 * 60.0, max_resumes: 0 }.freeze
+    }.freeze
+
+    def self.fetch(name)
+      TABLE[name]
+    end
+
+    def self.valid_names
+      TABLE.keys
+    end
+  end
+end