harnex 0.3.4 → 0.5.0

data/lib/harnex/core.rb

@@ -1,5 +1,6 @@
 require "digest"
 require "fileutils"
+require "optparse"
 require "securerandom"
 require "set"
 require "socket"
@@ -37,6 +38,93 @@ 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 harness_version
+    VERSION
+  end
+
+  def host_info
+    {
+      host: Socket.gethostname,
+      platform: RUBY_PLATFORM
+    }
+  rescue StandardError
+    {
+      host: nil,
+      platform: RUBY_PLATFORM
+    }
+  end
+
+  def strip_ansi(text)
+    text.to_s.gsub(/\e\[[0-9;]*[a-zA-Z]/, "")
+  end
+
+  def default_summary_out_path(repo_root)
+    koder_dir = File.join(repo_root.to_s, "koder")
+    return nil unless File.directory?(koder_dir)
+
+    File.join(koder_dir, "DISPATCH.jsonl")
+  end
+
+  def git_capture_start(repo_root)
+    sha = git_output(repo_root, "rev-parse", "HEAD")
+    branch = git_output(repo_root, "rev-parse", "--abbrev-ref", "HEAD")
+    return {} if sha.empty? || branch.empty?
+
+    {
+      sha: sha,
+      branch: branch
+    }
+  rescue StandardError
+    {}
+  end
+
+  def git_capture_end(repo_root, start_sha)
+    start_sha = start_sha.to_s.strip
+    return {} if start_sha.empty?
+
+    end_sha = git_output(repo_root, "rev-parse", "HEAD")
+    range = "#{start_sha}..#{end_sha}"
+    shortstat = git_output(repo_root, "diff", "--shortstat", range)
+    commits = Integer(git_output(repo_root, "rev-list", "--count", range))
+    stats = parse_git_shortstat(shortstat)
+
+    {
+      sha: end_sha,
+      loc_added: stats.fetch(:loc_added),
+      loc_removed: stats.fetch(:loc_removed),
+      files_changed: stats.fetch(:files_changed),
+      commits: commits
+    }
+  rescue StandardError
+    {}
+  end
+
   def repo_key(repo_root)
     Digest::SHA256.hexdigest(repo_root)[0, 16]
   end
@@ -113,6 +201,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?
@@ -283,4 +377,19 @@ module Harnex
       debounce_seconds: WATCH_DEBOUNCE_SECONDS
     )
   end
+
+  def git_output(repo_root, *args)
+    stdout, _stderr, status = Open3.capture3("git", "-C", repo_root.to_s, *args)
+    raise "git #{args.join(' ')} failed" unless status.success?
+
+    stdout.strip
+  end
+
+  def parse_git_shortstat(text)
+    {
+      files_changed: text.to_s[/(\d+)\s+files?\s+changed/, 1].to_i,
+      loc_added: text.to_s[/(\d+)\s+insertions?\(\+\)/, 1].to_i,
+      loc_removed: text.to_s[/(\d+)\s+deletions?\(-\)/, 1].to_i
+    }
+  end
 end

data/lib/harnex/runtime/session.rb

@@ -5,10 +5,41 @@ require "pty"
 module Harnex
   class Session
     OUTPUT_BUFFER_LIMIT = 64 * 1024
+    TRANSCRIPT_TAIL_BYTES = 16 * 1024
+    USAGE_FIELDS = %i[
+      input_tokens output_tokens reasoning_tokens cached_tokens total_tokens agent_session_id
+    ].freeze
+    class EventCounters
+      def initialize
+        @counts = {
+          stalls: 0,
+          force_resumes: 0,
+          disconnections: 0,
+          compactions: 0
+        }
+      end
+
+      def record(type)
+        case type.to_s
+        when "log_idle"
+          @counts[:stalls] += 1
+        when "resume"
+          @counts[:force_resumes] += 1
+        when "disconnect", "disconnection"
+          @counts[:disconnections] += 1
+        when "compaction"
+          @counts[:compactions] += 1
+        end
+      end
+
+      def snapshot
+        @counts.dup
+      end
+    end
 
-    attr_reader :repo_root, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch, :inbox, :description, :output_log_path
+    attr_reader :repo_root, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch, :inbox, :description, :meta, :summary_out, :output_log_path, :events_log_path
 
-    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, inbox_ttl: Inbox::DEFAULT_TTL)
+    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, summary_out: nil, inbox_ttl: Inbox::DEFAULT_TTL)
       @adapter = adapter
       @command = command
       @repo_root = repo_root
@@ -17,19 +48,32 @@ module Harnex
       @watch = watch
       @description = description.to_s.strip
       @description = nil if @description.empty?
+      @meta = meta
+      @summary_out = summary_out.to_s.strip
+      @summary_out = nil if @summary_out.empty?
       @registry_path = Harnex.registry_path(repo_root, @id)
       @output_log_path = Harnex.output_log_path(repo_root, @id)
+      @events_log_path = Harnex.events_log_path(repo_root, @id)
       @session_id = SecureRandom.hex(8)
       @token = SecureRandom.hex(16)
       @port = Harnex.allocate_port(repo_root, @id, port, host: host)
       @mutex = Mutex.new
       @inject_mutex = Mutex.new
+      @events_mutex = Mutex.new
       @injected_count = 0
       @last_injected_at = nil
       @started_at = Time.now
       @server = nil
       @reader = nil
       @output_log = nil
+      @events_log = nil
+      @events_log_seq = 0
+      @event_counters = EventCounters.new
+      @git_start = {}
+      @git_end = {}
+      @usage_summary = {}
+      @ended_at = nil
+      @exit_reason = nil
       @writer = nil
       @pid = nil
       @term_signal = nil
@@ -60,8 +104,11 @@ module Harnex
     def run(validate_binary: true)
       validate_binary! if validate_binary
       prepare_output_log
+      prepare_events_log
       @reader, @writer, @pid = PTY.spawn(child_env, *command)
       @writer.sync = true
+      emit_started_event
+      emit_git_start_event
 
       install_signal_handlers
       sync_window_size
@@ -78,8 +125,15 @@ module Harnex
       _, status = Process.wait2(pid)
       @term_signal = status.signaled? ? status.termsig : nil
       @exit_code = status.exited? ? status.exitstatus : 128 + status.termsig
+      @ended_at = Time.now
 
       output_thread.join(1)
+      emit_session_end_telemetry
+      @exit_reason = classify_exit
+      summary_record = build_summary_record
+      append_summary_record(summary_record)
+      emit_summary_event
+      emit_exit_event
       input_thread&.kill
       watch_thread&.kill
       @exit_code
@@ -91,6 +145,7 @@ module Harnex
       cleanup_registry
       @reader&.close unless @reader&.closed?
       @output_log&.close unless @output_log&.closed?
+      @events_log&.close unless @events_log&.closed?
       @writer&.close unless @writer&.closed?
     end
 
@@ -109,8 +164,10 @@ module Harnex
         started_at: @started_at.iso8601,
         last_injected_at: @last_injected_at&.iso8601,
         injected_count: @injected_count,
-        output_log_path: output_log_path
+        output_log_path: output_log_path,
+        events_log_path: events_log_path
       }
+      payload.merge!(log_activity_snapshot)
       payload[:description] = description if description
 
       if watch
@@ -168,6 +225,7 @@ module Harnex
         input_state: payload[:input_state],
         force: payload[:force]
       )
+        .tap { emit_send_event(text, force: payload[:force]) }
     end
 
     def sync_window_size
@@ -327,6 +385,14 @@ module Harnex
       @output_log_failed = false
     end
 
+    def prepare_events_log
+      @events_log&.close unless @events_log&.closed?
+      @events_log = File.open(events_log_path, "ab")
+      @events_log.sync = true
+      @events_log_failed = false
+      @events_log_seq = 0
+    end
+
     def install_signal_handlers
       %w[INT TERM HUP QUIT].each do |signal_name|
         Signal.trap(signal_name) { forward_signal(signal_name) }
@@ -364,6 +430,217 @@ module Harnex
       warn("harnex: failed to write output log #{output_log_path}: #{e.message}")
     end
 
+    def emit_send_event(text, force:)
+      compact = text.to_s
+      truncated = compact.length > 200
+      preview = truncated ? "#{compact[0, 200]}…" : compact
+      emit_event("send", msg: preview, msg_truncated: truncated, forced: !!force)
+    end
+
+    def emit_started_event
+      payload = { pid: @pid }
+      payload[:meta] = meta if meta
+      emit_event("started", **payload)
+    end
+
+    def emit_git_start_event
+      @git_start = Harnex.git_capture_start(repo_root)
+      return if @git_start.empty?
+
+      emit_event("git", phase: "start", sha: @git_start[:sha], branch: @git_start[:branch])
+    end
+
+    def emit_session_end_telemetry
+      @usage_summary = normalized_usage_summary(adapter.parse_session_summary(transcript_tail))
+      emit_event("usage", **@usage_summary)
+
+      @git_end = Harnex.git_capture_end(repo_root, @git_start[:sha])
+      return if @git_end.empty?
+
+      emit_event(
+        "git",
+        phase: "end",
+        sha: @git_end[:sha],
+        loc_added: @git_end[:loc_added],
+        loc_removed: @git_end[:loc_removed],
+        files_changed: @git_end[:files_changed],
+        commits: @git_end[:commits]
+      )
+    end
+
+    def emit_summary_event
+      emit_event("summary", path: summary_out, exit: @exit_reason)
+    end
+
+    def emit_exit_event
+      payload = { code: @exit_code }
+      payload[:signal] = @term_signal if @term_signal
+      payload[:reason] = @exit_reason if @exit_reason
+      emit_event("exited", **payload)
+    end
+
+    def classify_exit
+      return "timeout" if @exit_code == 124
+      return "failure" unless @exit_code == 0
+      return "success" if session_summary_present?
+
+      "disconnected"
+    end
+
+    def session_summary_present?
+      @usage_summary.values.any? { |value| !value.nil? }
+    end
+
+    def build_summary_record
+      {
+        meta: build_summary_meta,
+        predicted: summary_predicted_payload,
+        actual: build_summary_actual
+      }
+    end
+
+    def build_summary_meta
+      info = Harnex.host_info
+      passthrough = meta_hash
+
+      {
+        id: id,
+        tmux_session: id,
+        description: description,
+        started_at: @started_at.iso8601,
+        ended_at: @ended_at&.iso8601,
+        harness: "harnex",
+        harness_version: Harnex.harness_version,
+        agent: adapter.key,
+        agent_version: nil,
+        agent_provider: nil,
+        agent_deployment: nil,
+        host: info[:host],
+        platform: info[:platform],
+        orchestrator: passthrough["orchestrator"],
+        orchestrator_session: passthrough["orchestrator_session"],
+        chain_id: passthrough["chain_id"],
+        parent_dispatch_id: passthrough["parent_dispatch_id"],
+        tier: passthrough["tier"],
+        phase: passthrough["phase"],
+        issue: passthrough["issue"],
+        plan: passthrough["plan"],
+        task_brief: passthrough["task_brief"],
+        repo: repo_root,
+        branch: @git_start[:branch],
+        start_sha: @git_start[:sha],
+        end_sha: @git_end[:sha]
+      }
+    end
+
+    def build_summary_actual
+      counters = @event_counters.snapshot
+      counters[:disconnections] = [counters[:disconnections], 1].max if @exit_reason == "disconnected"
+
+      {
+        model: meta_hash["model"],
+        effort: meta_hash["effort"],
+        duration_s: @ended_at ? (@ended_at - @started_at).to_i : nil,
+        input_tokens: @usage_summary[:input_tokens],
+        output_tokens: @usage_summary[:output_tokens],
+        reasoning_tokens: @usage_summary[:reasoning_tokens],
+        cached_tokens: @usage_summary[:cached_tokens],
+        cost_usd: nil,
+        loc_added: @git_end[:loc_added],
+        loc_removed: @git_end[:loc_removed],
+        files_changed: @git_end[:files_changed],
+        commits: @git_end[:commits],
+        exit: @exit_reason,
+        stalls: counters[:stalls],
+        force_resumes: counters[:force_resumes],
+        disconnections: counters[:disconnections],
+        compactions: counters[:compactions],
+        tests_run: nil,
+        tests_passed: nil,
+        tests_failed: nil
+      }
+    end
+
+    def summary_predicted_payload
+      predicted = meta_hash["predicted"]
+      predicted.is_a?(Hash) ? predicted : {}
+    end
+
+    def meta_hash
+      meta.is_a?(Hash) ? meta : {}
+    end
+
+    def append_summary_record(record)
+      return unless summary_out
+
+      FileUtils.mkdir_p(File.dirname(summary_out))
+      File.open(summary_out, "ab") do |file|
+        file.write(JSON.generate(record))
+        file.write("\n")
+      end
+    rescue StandardError => e
+      warn("harnex: failed to write dispatch summary #{summary_out}: #{e.message}")
+    end
+
+    def normalized_usage_summary(summary)
+      summary ||= {}
+      USAGE_FIELDS.to_h { |field| [field, summary[field] || summary[field.to_s]] }
+    end
+
+    def transcript_tail
+      return "" unless File.file?(output_log_path)
+
+      File.open(output_log_path, "rb") do |file|
+        size = file.size
+        file.seek([size - TRANSCRIPT_TAIL_BYTES, 0].max)
+        Harnex.strip_ansi(file.read.to_s)
+      end
+    rescue StandardError
+      ""
+    end
+
+    def emit_event(type, **payload)
+      @event_counters.record(type)
+      @events_mutex.synchronize do
+        return unless @events_log
+
+        @events_log_seq += 1
+        event = {
+          schema_version: 1,
+          seq: @events_log_seq,
+          ts: Time.now.utc.iso8601,
+          id: id,
+          type: type
+        }.merge(payload)
+        @events_log.write(JSON.generate(event))
+        @events_log.write("\n")
+        @events_log.flush
+      end
+    rescue StandardError => e
+      return if defined?(@events_log_failed) && @events_log_failed
+
+      @events_log_failed = true
+      warn("harnex: failed to write events log #{events_log_path}: #{e.message}")
+    end
+
+    def log_activity_snapshot
+      return { log_mtime: nil, log_idle_s: nil } unless File.file?(output_log_path)
+      return { log_mtime: nil, log_idle_s: nil } if File.size?(output_log_path).nil?
+
+      mtime = File.mtime(output_log_path)
+      idle_seconds = (Time.now - mtime).to_i
+      idle_seconds = 0 if idle_seconds.negative?
+      {
+        log_mtime: mtime.iso8601,
+        log_idle_s: idle_seconds
+      }
+    rescue StandardError
+      {
+        log_mtime: nil,
+        log_idle_s: nil
+      }
+    end
+
     def screen_snapshot
       @mutex.synchronize { @output_buffer.dup }
     end

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.3.4"
-  RELEASE_DATE = "2026-04-24"
+  VERSION = "0.5.0"
+  RELEASE_DATE = "2026-05-01"
 end

data/lib/harnex.rb

@@ -12,12 +12,15 @@ require_relative "harnex/runtime/inbox"
 require_relative "harnex/runtime/file_change_hook"
 require_relative "harnex/runtime/api_server"
 require_relative "harnex/runtime/session"
+require_relative "harnex/commands/watch"
+require_relative "harnex/commands/watch_presets"
 require_relative "harnex/commands/run"
 require_relative "harnex/commands/send"
 require_relative "harnex/commands/wait"
 require_relative "harnex/commands/stop"
 require_relative "harnex/commands/status"
 require_relative "harnex/commands/logs"
+require_relative "harnex/commands/events"
 require_relative "harnex/commands/pane"
 require_relative "harnex/commands/recipes"
 require_relative "harnex/commands/guide"

data/skills/harnex-buddy/SKILL.md

@@ -8,6 +8,11 @@ description: Spawn an accountability partner for long-running harnex sessions. U
 For any long-running or unattended work, spawn a **buddy** — a second harnex
 agent that watches the worker and nudges it if it stalls.
 
+For plain stall recovery (force-resume on inactivity), prefer
+`harnex run --watch --preset impl`. Use a buddy when you need reasoning that
+policy checks cannot provide (doc drift, semantic checks, multi-session
+correlation).
+
 The buddy is an LLM, so it has intelligence for free. It reads the worker's
 screen, reasons about whether it's stuck, and composes a meaningful nudge.
 

data/skills/harnex-dispatch/SKILL.md

@@ -119,11 +119,27 @@ harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
   --context "Read and execute /tmp/task-impl-NN.md"
 ```
 
+### Built-in monitoring (`--watch`)
+
+For unattended implementation runs where you only need stall policy (not
+Claude-side reasoning), bundle dispatch and monitoring in one command:
+
+```bash
+harnex run codex --id cx-impl-42 --tmux cx-impl-42 --watch --preset impl
+```
+
+`--preset impl` applies the standard 8m stall threshold with one forced resume.
+Trade-off: `--watch` is foreground-blocking and policy-only (`stall-after` +
+`max-resumes`). Use pane polling (and buddy when needed) for richer reasoning.
+
 ## 2. Watch
 
 Poll the agent's screen with `harnex pane`. Checking is cheap — a 20-line
 tail is a few hundred bytes.
 
+For structured orchestration, prefer `harnex events --id <id>` over pane-text
+scraping.
+
 **Default: poll every 30 seconds.** This is fine for most work. The check
 itself costs almost nothing and catches completion quickly.
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.5.0
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-24 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies: []
 description: A local PTY harness that wraps terminal AI agents (Claude, Codex) and
   adds a control plane for discovery, messaging, and coordination.
@@ -32,6 +32,7 @@ files:
 - lib/harnex/adapters/codex.rb
 - lib/harnex/adapters/generic.rb
 - lib/harnex/cli.rb
+- lib/harnex/commands/events.rb
 - lib/harnex/commands/guide.rb
 - lib/harnex/commands/logs.rb
 - lib/harnex/commands/pane.rb
@@ -42,6 +43,8 @@ files:
 - lib/harnex/commands/status.rb
 - lib/harnex/commands/stop.rb
 - lib/harnex/commands/wait.rb
+- lib/harnex/commands/watch.rb
+- lib/harnex/commands/watch_presets.rb
 - lib/harnex/core.rb
 - lib/harnex/runtime/api_server.rb
 - lib/harnex/runtime/file_change_hook.rb