harnex 0.3.3 → 0.4.0

data/lib/harnex/commands/run.rb

@@ -6,10 +6,12 @@ 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 --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 --timeout --inbox-ttl
     ].freeze
 
     def self.usage(program_name = "harnex run")
@@ -23,13 +25,20 @@ 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)
           --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,6 +52,12 @@ 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,
         detach: false,
@@ -69,8 +84,12 @@ module Harnex
       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 +109,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,7 +135,7 @@ 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 += ["--inbox-ttl", @options[:inbox_ttl].to_s]
       tmux_cmd += ["--"] + child_args unless child_args.empty?
@@ -137,7 +171,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 +193,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 +206,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
@@ -294,10 +335,51 @@ 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])
@@ -358,7 +440,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|timeout|inbox-ttl)=/
+          nil
+        when /\A--preset=/
           nil
         else
           return true
@@ -372,7 +456,37 @@ 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=", "--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 default_inbox_ttl

data/lib/harnex/commands/skills.rb

@@ -4,20 +4,26 @@ module Harnex
   class Skills
     SKILLS_ROOT = File.expand_path("../../../../skills", __FILE__)
     INSTALL_SKILLS = %w[harnex-dispatch harnex-chain harnex-buddy].freeze
-    DEPRECATED_SKILLS = %w[dispatch chain-implement].freeze
+    DEPRECATED_SKILLS = %w[harnex dispatch chain-implement].freeze
+    SKILL_ALIASES = {
+      "harnex" => "harnex-dispatch",
+      "dispatch" => "harnex-dispatch",
+      "chain-implement" => "harnex-chain"
+    }.freeze
 
     def self.usage
       <<~TEXT
-        Usage: harnex skills <subcommand> [--local]
+        Usage: harnex skills <subcommand> [SKILL...] [--local]
 
         Subcommands:
-          install     Install bundled skills (globally by default)
+          install     Install bundled skills (globally by default; optional skill names)
           uninstall   Remove installed skills (globally by default)
 
         Options:
           --local     Target the current repo instead of global ~/.claude/
 
         Installs: #{INSTALL_SKILLS.join(', ')}
+        Aliases: harnex|dispatch -> harnex-dispatch, chain-implement -> harnex-chain
 
         By default, copies each skill to ~/.claude/skills/<skill>/
         and symlinks ~/.codex/skills/<skill> to it.
@@ -35,12 +41,13 @@ module Harnex
       subcommand = @argv.shift
       case subcommand
       when "install"
-        local, help = parse_args(@argv)
+        local, help, requested_skills = parse_args(@argv, allow_positional: true)
         return (puts self.class.usage; 0) if help
 
         remove_deprecated(local)
+        install_skills = requested_skills.empty? ? INSTALL_SKILLS : canonical_skill_names(requested_skills)
 
-        INSTALL_SKILLS.each do |skill_name|
+        install_skills.each do |skill_name|
           skill_source = resolve_skill_source(skill_name)
           unless skill_source
             return missing_skill(skill_name)
@@ -51,7 +58,7 @@ module Harnex
         end
         0
       when "uninstall"
-        local, help = parse_args(@argv)
+        local, help, = parse_args(@argv)
         return (puts self.class.usage; 0) if help
 
         (INSTALL_SKILLS + DEPRECATED_SKILLS).each do |skill_name|
@@ -70,9 +77,10 @@ module Harnex
 
     private
 
-    def parse_args(args)
+    def parse_args(args, allow_positional: false)
       local = false
       help = false
+      positional = []
 
       args.each do |arg|
         case arg
@@ -83,12 +91,16 @@ module Harnex
         when /\A-/
           raise "harnex skills: unknown option #{arg.inspect}"
         else
-          warn("harnex skills: unexpected argument #{arg.inspect}")
-          raise "harnex skills takes no positional arguments"
+          if allow_positional
+            positional << arg
+          else
+            warn("harnex skills: unexpected argument #{arg.inspect}")
+            raise "harnex skills takes no positional arguments"
+          end
         end
       end
 
-      [local, help]
+      [local, help, positional]
     end
 
     def resolve_skill_source(skill_name)
@@ -107,6 +119,14 @@ module Harnex
       end
     end
 
+    def canonical_skill_names(skill_names)
+      skill_names.map { |name| canonical_skill_name(name) }.uniq
+    end
+
+    def canonical_skill_name(skill_name)
+      SKILL_ALIASES.fetch(skill_name, skill_name)
+    end
+
     def install_local(skill_name, skill_source)
       repo_root = Harnex.resolve_repo_root(Dir.pwd)
       claude_dir = File.join(repo_root, ".claude", "skills", skill_name)

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

data/lib/harnex/core.rb

@@ -1,5 +1,6 @@
 require "digest"
 require "fileutils"
+require "optparse"
 require "securerandom"
 require "set"
 require "socket"
@@ -37,6 +38,32 @@ module Harnex
     File.expand_path(path)
   end
 
+  def parse_duration_seconds(value, option_name:)
+    text = value.to_s.strip
+    raise OptionParser::InvalidArgument, "#{option_name} requires a value" if text.empty?
+
+    match = text.match(/\A([0-9]+(?:\.[0-9]+)?)([smhSMH]?)\z/)
+    unless match
+      raise OptionParser::InvalidArgument,
+            "#{option_name} must be a positive duration (examples: 30, 30s, 5m, 2h)"
+    end
+
+    amount = Float(match[1])
+    multiplier =
+      case match[2].downcase
+      when "", "s" then 1.0
+      when "m" then 60.0
+      when "h" then 3600.0
+      else
+        raise OptionParser::InvalidArgument, "#{option_name} has an unsupported duration suffix"
+      end
+
+    seconds = amount * multiplier
+    raise OptionParser::InvalidArgument, "#{option_name} must be greater than 0" if seconds <= 0.0
+
+    seconds
+  end
+
   def repo_key(repo_root)
     Digest::SHA256.hexdigest(repo_root)[0, 16]
   end
@@ -113,6 +140,12 @@ module Harnex
     File.join(output_dir, "#{session_file_slug(repo_root, id)}.log")
   end
 
+  def events_log_path(repo_root, id)
+    events_dir = File.join(STATE_DIR, "events")
+    FileUtils.mkdir_p(events_dir)
+    File.join(events_dir, "#{session_file_slug(repo_root, id)}.jsonl")
+  end
+
   def session_file_slug(repo_root, id)
     slug = id_key(id)
     slug = "default" if slug.empty?